events.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/events.py
 
"""
Typed event factory module — M2.1 (event substrate).
 
Purpose
-------
Provide one keyword-only factory function per ``EventKind`` (spec 07 §3.2,
20 kinds) that builds the matching payload model and wraps it in a fully
validated ``option_c_agent_contracts.TurnEvent`` envelope. The factories give
call sites ergonomics without inventing a parallel type system: every factory
returns a plain ``TurnEvent`` (ADR-2 of plan 095).
 
Responsibilities
----------------
- Expose one keyword-only ``make_*`` factory per ``EventKind`` that builds the
  matching payload model and a validated ``TurnEvent`` envelope.
- Expose ``EVENT_FACTORIES`` (kind -> factory) and ``new_event_id()``.
- Stay structure-only: no file I/O, no ``run_turn()`` instrumentation, no
  session-identity binding (those are M2.2-M2.5).
 
What this module is NOT
-----------------------
No file I/O, no logging beyond the L4 diagnostics marker, no ``run_turn()``
instrumentation, no session-identity binding. Callers pass ``session_id`` as an
explicit string; ``TurnEvent.session_id`` is non-optional in the contract and
M2.5 will plumb the real value through (until then callers pass a placeholder
such as ``"unbound"``). The choice is pushed to the caller so the factory
signatures stay honest (plan 095 §9 Q1).
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events (none emitted here)
    L3 — semantic details (none emitted here)
    L4 — module-load coverage marker (silent at default verbosity)
 
Contracts
---------
- Every returned object is a frozen ``option_c_agent_contracts.TurnEvent``;
  this module never subclasses contract models (plan 095 ADR-2).
- ``parent_event_id`` is mandatory for every kind except ``session_started``
  (enforced by the contract's envelope validator, not duplicated here).
- Module-level L4 ``_dbg`` is a diagnostics-coverage marker only.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- option_c_agent_contracts (TurnEvent envelope, EventKind, payload models)
- option_c_agent_contracts.events (the payload model each factory builds for its event kind)
"""
from __future__ import annotations
 
import uuid
from typing import Any, Callable, Mapping, Optional
 
from oc_diagnostics import _dbg
 
# ``option_c_agent_contracts`` is installed editable as a monorepo sibling
# (Plan 151 T7/B1 promoted the contracts packages to ``contracts/``); a plain
# import resolves the real package directly. The flat-layout sys.path bootstrap
# was retired here when the shadowing project dir left the subproject root.
from option_c_agent_contracts import (
    EventKind,
    Provenance,
    TurnEvent,
)
from option_c_agent_contracts.events import (
    AssistantMessagePayload,
    BranchSummaryPayload,
    CompactionCompletedPayload,
    CompactionStartedPayload,
    ErrorPayload,
    HookExecutedPayload,
    HubMessagePayload,
    PermissionDecisionPayload,
    PromptRenderedPayload,
    ProviderBudgetConsumedPayload,
    ProviderRateLimitedPayload,
    ProviderRetriedPayload,
    SessionEndedPayload,
    SessionStartedPayload,
    SubagentCompletedPayload,
    SubagentStartedPayload,
    ToolCallCompletedPayload,
    ToolCallProgressPayload,
    ToolCallProposedPayload,
    ToolCallStartedPayload,
    UserInputReceivedPayload,
)
 
_dbg("OC_CHAT.MAIN", "events", "module", 4)
 
 
def new_event_id() -> str:
    """Return a fresh UUID4 string for use as a ``TurnEvent.event_id``."""
    return str(uuid.uuid4())
 
 
def _make(
    kind: EventKind,
    payload: Any,
    *,
    event_id: str,
    parent_event_id: Optional[str],
    session_id: str,
    ts: str,
    turn_id: Optional[str] = None,
    tool_call_id: Optional[str] = None,
    permission_decision_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    """Assemble + validate a ``TurnEvent`` envelope around ``payload``.
 
    Defaulting ``provenance`` to a *fresh* ``Provenance()`` per call (never a
    shared module-level instance) matches the contract field's
    ``default_factory`` and keeps factory outputs independent.
    """
    return TurnEvent(
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        turn_id=turn_id,
        tool_call_id=tool_call_id,
        permission_decision_id=permission_decision_id,
        ts=ts,
        kind=kind,
        payload=payload,
        provenance=provenance if provenance is not None else Provenance(),
        prompt_version=prompt_version,
    )
 
 
# --- session -----------------------------------------------------------------
def make_session_started(
    *,
    event_id: str,
    parent_event_id: Optional[str] = None,
    session_id: str,
    ts: str,
    agent_role: str,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    """The session root. ``parent_event_id`` defaults to ``None`` (only kind allowed to be a root)."""
    return _make(
        "session_started",
        SessionStartedPayload(agent_role=agent_role),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_session_ended(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    outcome: str,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "session_ended",
        SessionEndedPayload(outcome=outcome),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
# --- turn --------------------------------------------------------------------
def make_user_input_received(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    text: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "user_input_received",
        UserInputReceivedPayload(text=text),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_assistant_message(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    text: str,
    is_final: bool = True,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "assistant_message",
        AssistantMessagePayload(text=text, is_final=is_final),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
# --- model -------------------------------------------------------------------
def make_prompt_rendered(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    prompt_version: str,
    layer_ids: Optional[list[str]] = None,
    layer_hashes: Optional[dict[str, str]] = None,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
) -> TurnEvent:
    return _make(
        "prompt_rendered",
        PromptRenderedPayload(
            prompt_version=prompt_version,
            layer_ids=list(layer_ids) if layer_ids is not None else [],
            layer_hashes=dict(layer_hashes) if layer_hashes is not None else {},
        ),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_provider_rate_limited(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    provider_name: str,
    retry_after_seconds: Optional[float] = None,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "provider_rate_limited",
        ProviderRateLimitedPayload(
            provider_name=provider_name,
            retry_after_seconds=retry_after_seconds,
        ),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_provider_retried(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    provider_name: str,
    attempt: int,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "provider_retried",
        ProviderRetriedPayload(provider_name=provider_name, attempt=attempt),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_provider_budget_consumed(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    provider_name: str,
    input_tokens: int = 0,
    output_tokens: int = 0,
    cost_usd: Optional[float] = None,
    model: Optional[str] = None,
    cache_read_tokens: Optional[int] = None,
    cache_miss_tokens: Optional[int] = None,
    priced_at: Optional[str] = None,
    rate_effective_from: Optional[str] = None,
    rate_verified_at: Optional[str] = None,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    """Plan 203: ``cost_usd=None`` means UNKNOWN, not free.
 
    The default is ``None`` rather than ``0.0`` so a caller that cannot price
    a sample gets the truthful encoding by omission instead of manufacturing
    spend the projection would sum as real.
    """
    return _make(
        "provider_budget_consumed",
        ProviderBudgetConsumedPayload(
            provider_name=provider_name,
            input_tokens=input_tokens,
            output_tokens=output_tokens,
            cost_usd=cost_usd,
            model=model,
            cache_read_tokens=cache_read_tokens,
            cache_miss_tokens=cache_miss_tokens,
            priced_at=priced_at,
            rate_effective_from=rate_effective_from,
            rate_verified_at=rate_verified_at,
        ),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
# --- tool --------------------------------------------------------------------
def make_tool_call_proposed(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    tool_name: str,
    requested_args: Optional[dict[str, Any]] = None,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "tool_call_proposed",
        ToolCallProposedPayload(
            tool_name=tool_name,
            requested_args=dict(requested_args) if requested_args is not None else {},
        ),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_permission_decision(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    permission_decision_id: str,
    decision: str,
    decided_by: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
    # M8.1 WU-0a (§A.4): the single-decision audit fields (all Optional; the
    # payload model enforces the closed-Literal constraints on risk_class /
    # final_outcome / authorization_mode / denial_reason_code).
    tool_call_id: Optional[str] = None,
    policy_version: Optional[str] = None,
    risk_class: Optional[str] = None,
    final_outcome: Optional[str] = None,
    input_hash: Optional[str] = None,
    permission_request_id: Optional[str] = None,
    canonical_request_hash: Optional[str] = None,
    grant_fingerprint: Optional[str] = None,
    envelope_fingerprint: Optional[str] = None,
    grant_key_fingerprint: Optional[str] = None,
    authorization_mode: Optional[str] = None,
    denial_reason_code: Optional[str] = None,
) -> TurnEvent:
    """Sets ``permission_decision_id`` on both the payload and the envelope.
 
    The M8.1 audit fields are threaded onto the payload when supplied; omitting
    them yields the legacy 3-field shape (wire-compat).
    """
    return _make(
        "permission_decision",
        PermissionDecisionPayload(
            permission_decision_id=permission_decision_id,
            decision=decision,
            decided_by=decided_by,
            tool_call_id=tool_call_id,
            policy_version=policy_version,
            risk_class=risk_class,
            final_outcome=final_outcome,
            input_hash=input_hash,
            permission_request_id=permission_request_id,
            canonical_request_hash=canonical_request_hash,
            grant_fingerprint=grant_fingerprint,
            envelope_fingerprint=envelope_fingerprint,
            grant_key_fingerprint=grant_key_fingerprint,
            authorization_mode=authorization_mode,
            denial_reason_code=denial_reason_code,
        ),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        permission_decision_id=permission_decision_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_tool_call_started(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    tool_call_id: str,
    tool_name: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    """Sets ``tool_call_id`` on both the payload and the envelope."""
    return _make(
        "tool_call_started",
        ToolCallStartedPayload(tool_call_id=tool_call_id, tool_name=tool_name),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        tool_call_id=tool_call_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_tool_call_progress(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    tool_call_id: str,
    message: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    """Sets ``tool_call_id`` on both the payload and the envelope."""
    return _make(
        "tool_call_progress",
        ToolCallProgressPayload(tool_call_id=tool_call_id, message=message),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        tool_call_id=tool_call_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_tool_call_completed(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    tool_call_id: str,
    outcome: str,
    result_artifact_id: Optional[str] = None,
    error_summary: Optional[str] = None,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    """Sets ``tool_call_id`` on both the payload and the envelope.
 
    Plan 203 (audit G10): *error_summary* carries WHY a call failed. The
    contract bounds it at ``ERROR_SUMMARY_MAX_CHARS`` and truncates rather
    than rejects, so a caller may pass the failure text it has in hand
    without pre-trimming it.
    """
    return _make(
        "tool_call_completed",
        ToolCallCompletedPayload(
            tool_call_id=tool_call_id,
            outcome=outcome,
            result_artifact_id=result_artifact_id,
            error_summary=error_summary,
        ),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        tool_call_id=tool_call_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
# --- sub-agent ---------------------------------------------------------------
def make_subagent_started(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    subagent_session_id: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "subagent_started",
        SubagentStartedPayload(subagent_session_id=subagent_session_id),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_subagent_completed(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    subagent_session_id: str,
    outcome: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "subagent_completed",
        SubagentCompletedPayload(
            subagent_session_id=subagent_session_id, outcome=outcome
        ),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
# --- context -----------------------------------------------------------------
def make_compaction_started(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    reason: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "compaction_started",
        CompactionStartedPayload(reason=reason),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_compaction_completed(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    summary_artifact_id: Optional[str] = None,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "compaction_completed",
        CompactionCompletedPayload(summary_artifact_id=summary_artifact_id),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_branch_summary(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    summary: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "branch_summary",
        BranchSummaryPayload(summary=summary),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
# --- errors / hooks ----------------------------------------------------------
def make_error(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    error_summary: str,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "error",
        ErrorPayload(error_summary=error_summary),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_hook_executed(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    hook_name: str,
    exit_code: int = 0,
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    return _make(
        "hook_executed",
        HookExecutedPayload(hook_name=hook_name, exit_code=exit_code),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
def make_hub_message(
    *,
    event_id: str,
    parent_event_id: str,
    session_id: str,
    ts: str,
    message_id: str,
    hub_kind: str,
    sender: str,
    recipient: str,
    subject: Optional[str] = None,
    in_reply_to: Optional[str] = None,
    summary: str = "",
    turn_id: Optional[str] = None,
    provenance: Optional[Provenance] = None,
    prompt_version: Optional[str] = None,
) -> TurnEvent:
    """Plan 259: one addressed hub message, as telemetry.
 
    Published by ``core/hub_bus.py``'s carrier when a bus was injected, so
    a session's own event writer records the fleet traffic that crossed
    it. The payload carries routing and a one-line summary and nothing
    else: the hub's durable log is the record of WHAT was said, and this
    event is only the record that something was said.
    """
    return _make(
        "hub_message",
        HubMessagePayload(
            message_id=message_id,
            hub_kind=hub_kind,
            sender=sender,
            recipient=recipient,
            subject=subject,
            in_reply_to=in_reply_to,
            summary=summary,
        ),
        event_id=event_id,
        parent_event_id=parent_event_id,
        session_id=session_id,
        ts=ts,
        turn_id=turn_id,
        provenance=provenance,
        prompt_version=prompt_version,
    )
 
 
# A kind-to-factory lookup. Tests parametrize over this; M2.7 replay maps a
# kind string back to its constructor. Adding a kind post-v0.1 is a deliberate
# multi-step edit (see ADR-2): contract enum + payload + union, then one
# factory here + one entry below.
EVENT_FACTORIES: Mapping[EventKind, Callable[..., TurnEvent]] = {
    "session_started": make_session_started,
    "session_ended": make_session_ended,
    "user_input_received": make_user_input_received,
    "assistant_message": make_assistant_message,
    "prompt_rendered": make_prompt_rendered,
    "provider_rate_limited": make_provider_rate_limited,
    "provider_retried": make_provider_retried,
    "provider_budget_consumed": make_provider_budget_consumed,
    "tool_call_proposed": make_tool_call_proposed,
    "permission_decision": make_permission_decision,
    "tool_call_started": make_tool_call_started,
    "tool_call_progress": make_tool_call_progress,
    "tool_call_completed": make_tool_call_completed,
    "subagent_started": make_subagent_started,
    "subagent_completed": make_subagent_completed,
    "compaction_started": make_compaction_started,
    "compaction_completed": make_compaction_completed,
    "branch_summary": make_branch_summary,
    "error": make_error,
    "hook_executed": make_hook_executed,
    "hub_message": make_hub_message,
}
 
__all__ = [
    "EVENT_FACTORIES",
    "new_event_id",
    "make_session_started",
    "make_session_ended",
    "make_user_input_received",
    "make_assistant_message",
    "make_prompt_rendered",
    "make_provider_rate_limited",
    "make_provider_retried",
    "make_provider_budget_consumed",
    "make_tool_call_proposed",
    "make_permission_decision",
    "make_tool_call_started",
    "make_tool_call_progress",
    "make_tool_call_completed",
    "make_subagent_started",
    "make_subagent_completed",
    "make_compaction_started",
    "make_compaction_completed",
    "make_branch_summary",
    "make_error",
    "make_hook_executed",
    "make_hub_message",
]