omega-coding-agent 0.1.0__py3-none-any.whl

omega_agent/__init__.py

@@ -0,0 +1,19 @@
+"""omega_agent — Layer 2, the portable core.
+
+The loop, the harness, the two event vocabularies, the message model, and the
+provider *contract*. What it knows about: messages, events, tools, turns.
+
+What it does not know about, and must never learn: **files, shells, terminals,
+and vendors.** Those are `omega_coding` and `omega_ai` respectively, and both of
+them import this package rather than the other way round.
+
+`provider.py` living here is the point of the whole arrangement. The consumer
+defines the interface and adapters conform to it — reverse that and Anthropic's
+shape becomes the shape of the system. `omega_ai/provider.py` is a re-export, so
+adapters can import from their own package without owning the contract, which is
+exactly what Tau does.
+
+`tests/test_layers.py` enforces all of this rather than trusting it.
+"""
+
+__version__ = "0.2.0"

omega_agent/agent_events.py

@@ -0,0 +1,166 @@
+"""The ten agent events — Layer 2's vocabulary.
+
+Tier 1 had one event vocabulary and the loop handed it straight upward. That was
+honest for a tier whose only consumer was a `print` statement, but it has a cost
+the CLI made visible: **tool results had no event at all.** `cli.py` reported them
+by watching the transcript list grow, after the fact.
+
+So there are two vocabularies, and the split is the point:
+
+| | the **12** (`events.py`) | the **10** (this file) |
+|---|---|---|
+| about | one model response arriving | the whole run's progress |
+| granularity | one token | "a tool started" |
+| audience | Layer 2 | Layer 4 — a UI |
+
+They nest four deep: **agent ▸ turn ▸ message ▸ tool execution.** A renderer can
+indent on that structure without tracking any state of its own.
+
+Nothing is lost by moving up a level. Every one of the twelve is carried by
+exactly one of these ten, on the `stream_event` field of the three `message_*`
+events — so a consumer that wants token deltas still gets them, and a consumer
+that only wants "what is happening" can ignore them.
+
+Pi and Tau converged on these ten names, as they did on the twelve. Copied
+verbatim rather than improved.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import Field
+
+from omega_agent.events import AssistantMessageEvent
+from omega_agent.types import AssistantMessage, ToolCall, ToolResultMessage, WireModel
+
+#: The four nesting levels, outermost first. Exposed so a renderer can derive
+#: indentation from the vocabulary instead of hardcoding it.
+AGENT_EVENT_NESTING = ("agent", "turn", "message", "tool_execution")
+
+#: Why a run ended. `stop` is the only success: the model stopped asking for
+#: tools. The other three are all "it did not finish", distinguished because a
+#: UI should say which.
+AgentEndReason = Literal["stop", "max_turns", "error", "aborted"]
+
+
+# ----------------------------------------------------------------- agent scope
+
+class AgentStartEvent(WireModel):
+    """The run begins. Carries nothing — the loop's inputs are the caller's."""
+
+    type: Literal["agent_start"] = "agent_start"
+
+
+class AgentEndEvent(WireModel):
+    """The run is over, for any reason.
+
+    Exactly one of these is emitted per run, including on failure. Tier 1
+    signalled failure by yielding a bare provider `error` event, which meant a
+    consumer had to distinguish "this turn failed" from "the run is over".
+    """
+
+    type: Literal["agent_end"] = "agent_end"
+    reason: AgentEndReason
+    error_message: str | None = None
+
+
+# ------------------------------------------------------------------ turn scope
+
+class TurnStartEvent(WireModel):
+    type: Literal["turn_start"] = "turn_start"
+    turn: int
+
+
+class TurnEndEvent(WireModel):
+    type: Literal["turn_end"] = "turn_end"
+    turn: int
+
+
+# --------------------------------------------------------------- message scope
+
+# All three carry `stream_event`, the underlying one of the twelve. That is what
+# keeps the coarser vocabulary from being a downgrade: a renderer wanting text
+# deltas reads `stream_event`, one wanting progress ignores it.
+
+class MessageStartEvent(WireModel):
+    type: Literal["message_start"] = "message_start"
+    message: AssistantMessage
+    stream_event: AssistantMessageEvent
+
+
+class MessageUpdateEvent(WireModel):
+    type: Literal["message_update"] = "message_update"
+    message: AssistantMessage
+    stream_event: AssistantMessageEvent
+
+
+class MessageEndEvent(WireModel):
+    """The response is complete — or failed, which is also complete.
+
+    `message` is the final assistant message either way. A stream that produced
+    500 tokens and then died reports both, as in Tier 1.
+    """
+
+    type: Literal["message_end"] = "message_end"
+    message: AssistantMessage
+    stream_event: AssistantMessageEvent
+
+
+# -------------------------------------------------------- tool execution scope
+
+class ToolExecutionStartEvent(WireModel):
+    """A tool is about to run. **The event Tier 1 could not emit.**"""
+
+    type: Literal["tool_execution_start"] = "tool_execution_start"
+    tool_call: ToolCall
+
+
+class ToolExecutionUpdateEvent(WireModel):
+    """Progress from a tool that is still running.
+
+    Nothing emits this in Tier 2 — no built-in tool reports progress yet. It is
+    declared because the vocabulary is ten, not nine, and because a long
+    `run_shell` streaming its output is the obvious next use. Same reasoning as
+    Tier 1's `CancellationToken`: the seam ships before the thing that fills it.
+    """
+
+    type: Literal["tool_execution_update"] = "tool_execution_update"
+    tool_call_id: str
+    details: dict[str, Any] | None = None
+
+
+class ToolExecutionEndEvent(WireModel):
+    type: Literal["tool_execution_end"] = "tool_execution_end"
+    tool_call: ToolCall
+    result: ToolResultMessage
+
+
+AgentEvent = Annotated[
+    AgentStartEvent
+    | AgentEndEvent
+    | TurnStartEvent
+    | TurnEndEvent
+    | MessageStartEvent
+    | MessageUpdateEvent
+    | MessageEndEvent
+    | ToolExecutionStartEvent
+    | ToolExecutionUpdateEvent
+    | ToolExecutionEndEvent,
+    Field(discriminator="type"),
+]
+
+AGENT_EVENT_TYPES = frozenset(
+    {
+        "agent_start",
+        "agent_end",
+        "turn_start",
+        "turn_end",
+        "message_start",
+        "message_update",
+        "message_end",
+        "tool_execution_start",
+        "tool_execution_update",
+        "tool_execution_end",
+    }
+)

omega_agent/cancellation.py

@@ -0,0 +1,52 @@
+"""A cancellation token you can actually set.
+
+`types.py` defines `CancellationToken` as a Protocol — one method, "should I
+stop?" — and Tier 1 threaded it through the provider interface, the loop, and
+every tool executor without ever creating one. The seam was complete and inert.
+This is the twenty lines that fill it.
+
+Kept separate from `harness.py` on purpose. The harness *owns* an instance, but
+the token itself has no dependencies and no knowledge of a conversation, which
+makes it trivially testable and reusable by anything that needs to be
+interruptible.
+
+**It latches.** Once cancelled it stays cancelled until `reset()`, so a check
+that happens slightly late still sees the cancellation. The alternative — a
+signal that clears itself when read — loses interrupts that arrive between two
+checks, which is the worst kind of bug to debug.
+"""
+
+from __future__ import annotations
+
+
+class CancelSignal:
+    """Set by whoever handles the interrupt; read by whoever can act on it.
+
+    Deliberately not `asyncio.Event`. An Event's natural use is `await
+    event.wait()`, which invites code that blocks until cancellation. What is
+    wanted here is the opposite: a cheap, synchronous "am I still wanted?" that
+    a tool can poll inside a loop, and that a signal handler can set without
+    needing an event loop to hand.
+    """
+
+    __slots__ = ("_cancelled",)
+
+    def __init__(self) -> None:
+        self._cancelled = False
+
+    def is_cancelled(self) -> bool:
+        """The whole `CancellationToken` protocol."""
+        return self._cancelled
+
+    def cancel(self) -> None:
+        """Request a stop. Idempotent, and safe to call from a signal handler."""
+        self._cancelled = True
+
+    def reset(self) -> None:
+        """Clear the request, ready for the next turn.
+
+        The harness calls this before every run. Without it the first Ctrl-C
+        would cancel every later turn too — an agent that appears to break
+        permanently the first time you interrupt it.
+        """
+        self._cancelled = False

omega_agent/events.py

@@ -0,0 +1,157 @@
+"""The twelve stream events — Layer 1's vocabulary.
+
+This file is the contract between the provider layer and everything above it.
+Pi and Tau, written in different languages by different people, converged on
+exactly these twelve names and these exact `type` strings. That convergence is
+the strongest evidence in either codebase that the vocabulary *is* the
+architecture, so the names are copied verbatim rather than improved.
+
+Deliberately a separate module from `types.py`. Tier 2 introduces a second,
+coarser vocabulary — the ten *agent* events — which will live in its own file
+beside this one. Keeping them apart means you can always tell at a glance which
+layer an event belongs to.
+
+Shape of a well-formed stream:
+
+    start
+      text_start → text_delta* → text_end
+      thinking_start → thinking_delta* → thinking_end
+      toolcall_start → toolcall_delta* → toolcall_end
+    done | error
+
+Two invariants the provider layer owes upward, enforced in the adapter:
+
+    * exactly one `start`
+    * exactly one terminal event — `done` or `error` — even if the vendor
+      stream dies silently
+
+Buying those here, once, means the loop never needs a timeout, a sentinel, or a
+"what if the stream just stops" branch.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from omega_agent.types import AssistantMessage, ToolCall, WireModel
+
+# Every streaming event carries `partial`: the whole message as it exists so far.
+# It costs a copy per event and buys stateless consumers — a renderer can ignore
+# the delta entirely and just redraw `partial`.
+
+
+class AssistantStartEvent(WireModel):
+    type: Literal["start"] = "start"
+    partial: AssistantMessage
+
+
+# ------------------------------------------------------------------------ text
+
+class TextStartEvent(WireModel):
+    type: Literal["text_start"] = "text_start"
+    content_index: int
+    partial: AssistantMessage
+
+
+class TextDeltaEvent(WireModel):
+    type: Literal["text_delta"] = "text_delta"
+    content_index: int
+    delta: str
+    partial: AssistantMessage
+
+
+class TextEndEvent(WireModel):
+    type: Literal["text_end"] = "text_end"
+    content_index: int
+    content: str
+    partial: AssistantMessage
+
+
+# -------------------------------------------------------------------- thinking
+
+class ThinkingStartEvent(WireModel):
+    type: Literal["thinking_start"] = "thinking_start"
+    content_index: int
+    partial: AssistantMessage
+
+
+class ThinkingDeltaEvent(WireModel):
+    type: Literal["thinking_delta"] = "thinking_delta"
+    content_index: int
+    delta: str
+    partial: AssistantMessage
+
+
+class ThinkingEndEvent(WireModel):
+    type: Literal["thinking_end"] = "thinking_end"
+    content_index: int
+    content: str
+    partial: AssistantMessage
+
+
+# ------------------------------------------------------------------- tool calls
+
+class ToolCallStartEvent(WireModel):
+    type: Literal["toolcall_start"] = "toolcall_start"
+    content_index: int
+    partial: AssistantMessage
+
+
+class ToolCallDeltaEvent(WireModel):
+    type: Literal["toolcall_delta"] = "toolcall_delta"
+    content_index: int
+    delta: str
+    partial: AssistantMessage
+
+
+class ToolCallEndEvent(WireModel):
+    type: Literal["toolcall_end"] = "toolcall_end"
+    content_index: int
+    tool_call: ToolCall
+    partial: AssistantMessage
+
+
+# -------------------------------------------------------------------- terminal
+
+DoneReason = Literal["stop", "length", "toolUse"]
+ErrorReason = Literal["aborted", "error"]
+
+
+class AssistantDoneEvent(WireModel):
+    type: Literal["done"] = "done"
+    reason: DoneReason
+    message: AssistantMessage
+
+
+class AssistantErrorEvent(WireModel):
+    """A failure, delivered as data rather than raised.
+
+    A stream that emitted 500 tokens and *then* failed has two things to report.
+    An exception carries only the failure and discards the tokens; this carries
+    both, because `error` holds the message accumulated so far.
+    """
+
+    type: Literal["error"] = "error"
+    reason: ErrorReason
+    error: AssistantMessage
+
+
+AssistantMessageEvent = Annotated[
+    AssistantStartEvent
+    | TextStartEvent
+    | TextDeltaEvent
+    | TextEndEvent
+    | ThinkingStartEvent
+    | ThinkingDeltaEvent
+    | ThinkingEndEvent
+    | ToolCallStartEvent
+    | ToolCallDeltaEvent
+    | ToolCallEndEvent
+    | AssistantDoneEvent
+    | AssistantErrorEvent,
+    Field(discriminator="type"),
+]
+
+TERMINAL_EVENT_TYPES = frozenset({"done", "error"})