Python
"""Event model — the contract between the turn engine and any surface (TUI/GUI/IDE).
No token streaming in v1, so granularity is per-message/per-tool. Streaming later adds
`assistant_delta` / `tool_output_delta` without changing the rest.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from enum import Enum
from typing import Any
class EventType(str, Enum):
TURN_START = "turn_start"
ASSISTANT_DELTA = "assistant_delta"
REASONING_DELTA = "reasoning_delta" # model thinking text (display-only, never replayed)
ASSISTANT_MESSAGE = "assistant_message"
TOOL_PROPOSED = "tool_proposed"
PERMISSION_REQUIRED = "permission_required"
DIRECTORY_REQUESTED = "directory_requested" # agent asks the user to grant a folder
TOOL_REQUESTED = "tool_requested" # agent asks for a missing CLI tool (scanner, etc.)
CONNECTOR_REQUESTED = "connector_requested" # request_connector / grant_connector gate (§11.6)
QUESTION_REQUESTED = (
"question_requested" # agent asks the user a free-text/multiple-choice question
)
PLAN_PROPOSED = (
"plan_proposed" # agent presents a plan for approval (plan mode exit)
)
TEAM_PROPOSED = (
"team_proposed" # a lead proposes a worker roster (the staffing gate)
)
ITEMS_PROPOSED = (
"items_proposed" # a lead proposes work items (the decomposition gate);
# unlike propose_plan this is mode-independent — approval creates the items
)
TOOL_STARTED = "tool_started"
TOOL_FINISHED = "tool_finished"
ITERATION_END = "iteration_end"
# OPE-238: the actions auto-approve let run with no card this turn (a gate tier or a
# reviewer "allow"), emitted just before the event that ends the turn.
TURN_SUMMARY = "turn_summary"
TURN_END = "turn_end"
ERROR = "error"
INTERRUPTED = "interrupted"
COMPACTING = "compacting" # compaction started — surfaces show a transient signal
COMPACTED = "compacted" # outbound history was compacted (summary or trim)
# OPE-171: the reply was cut off at the output-token limit with no tool call; the
# engine nudged the model to act and is going round the loop again.
CONTINUATION = "continuation"
# The session's sandbox is being made (its first turn), and is up: the surfaces show
# "Preparing the … sandbox" in between.
SANDBOX_PREPARING = "sandbox_preparing"
SANDBOX_READY = "sandbox_ready"
@dataclass
class Event:
type: EventType
data: dict[str, Any] = field(default_factory=dict)