aria-code 0.52.0__py3-none-any.whl

aria_code/runtime/events.py

@@ -0,0 +1,113 @@
+"""Runtime event and trace records for Aria Code."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class RuntimeEvent:
+    event_id: str
+    type: str
+    timestamp: float
+    data: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def create(cls, event_type: str, data: Dict[str, Any] | None = None) -> "RuntimeEvent":
+        return cls(uuid.uuid4().hex[:12], event_type, time.time(), data or {})
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class ToolCallRecord:
+    tool: str
+    params: Dict[str, Any]
+    result: Dict[str, Any]
+    elapsed_ms: float
+    started_at: float
+    ended_at: float
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class TurnResultRecord:
+    status: str
+    success: bool
+    cancelled: bool
+    provider: str
+    error: str
+    final_text: str
+    summary: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class RuntimeTrace:
+    """In-memory trace of runtime events for session replay/debugging."""
+
+    def __init__(
+        self,
+        event_sink: Optional[Callable[[RuntimeEvent], None]] = None,
+    ) -> None:
+        self.events: List[RuntimeEvent] = []
+        self.tool_calls: List[ToolCallRecord] = []
+        self.turn_results: List[TurnResultRecord] = []
+        self.event_sink = event_sink
+
+    def emit(self, event_type: str, data: Dict[str, Any] | None = None) -> RuntimeEvent:
+        event = RuntimeEvent.create(event_type, data)
+        self.events.append(event)
+        if self.event_sink is not None:
+            try:
+                self.event_sink(event)
+            except Exception:
+                # Observability must never turn a successful tool call into a
+                # failed one. The in-memory trace remains available as fallback.
+                pass
+        return event
+
+    def add_tool_call(self, record: ToolCallRecord) -> None:
+        self.tool_calls.append(record)
+        self.emit("tool_result", {
+            "tool": record.tool,
+            "success": bool(record.result.get("success")),
+            "elapsed_ms": record.elapsed_ms,
+        })
+
+    def add_turn_result(self, record: Dict[str, Any]) -> TurnResultRecord:
+        turn = TurnResultRecord(
+            status=str(record.get("status", "")),
+            success=bool(record.get("success")),
+            cancelled=bool(record.get("cancelled")),
+            provider=str(record.get("provider", "")),
+            error=str(record.get("error", "")),
+            final_text=str(record.get("final_text", "")),
+            summary=str(record.get("summary", "")),
+            metadata=dict(record.get("metadata") or {}),
+        )
+        self.turn_results.append(turn)
+        self.emit("turn_complete", {
+            "status": turn.status,
+            "success": turn.success,
+            "cancelled": turn.cancelled,
+            "provider": turn.provider,
+            "summary": turn.summary,
+        })
+        return turn
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "events": [event.to_dict() for event in self.events],
+            "tool_calls": [call.to_dict() for call in self.tool_calls],
+            "turn_results": [turn.to_dict() for turn in self.turn_results],
+        }

aria_code/runtime/gateway.py

@@ -0,0 +1,150 @@
+"""Neutral agent-turn Gateway — the single entry every adapter calls.
+
+This is the documented runtime convergence point: one tested turn driver behind
+a thin set of adapters (interactive CLI, headless ``-p``, daemon, HTTP API). It
+is deliberately free of UI/provider specifics — callers supply:
+
+  • ``provider_fn``   — which model/backend a round calls (built by each adapter)
+  • ``tool_executor`` — the local tool registry
+  • streaming callbacks — rendered however the adapter likes
+
+``run_turn`` drives :func:`runtime.run_agent`, folds its event stream into a
+structured :class:`TurnResult`, and forwards callbacks live.
+
+Because it imports only ``runtime`` primitives (no ``apps.cli``, no concrete
+providers), it can be reused from another process/repo — e.g. the Arthera
+FastAPI backend — so the CLI and the API share ONE agent loop instead of
+re-implementing turn management three times.
+
+Streaming note: ``run_agent`` emits tool-call / tool-result / status / complete /
+cancelled / error *events*, but streams **tokens and thinking through callbacks**
+(it never yields token events). So ``run_turn`` passes ``on_token``/``on_thinking``
+straight to ``run_agent`` (single fire, enables live streaming) while consuming
+tool/status/lifecycle via the event stream (avoids double-firing those).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional
+
+# Import from the submodule (not the ``runtime`` package) so this module can be
+# imported from ``runtime/__init__`` without a circular dependency.
+from aria_code.runtime.agent_loop import (
+    AgentEventCancelled,
+    AgentEventComplete,
+    AgentEventError,
+    AgentEventStatus,
+    AgentEventToolCall,
+    AgentEventToolResult,
+    AgentOptions,
+    run_agent,
+)
+
+
+@dataclass(frozen=True)
+class TurnResult:
+    """Adapter-agnostic outcome of one agent turn."""
+
+    text: str = ""
+    final: Any = None             # AgentTurnResult when the turn completed
+    error: Optional[str] = None
+    cancelled: bool = False
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and not self.cancelled
+
+
+async def run_turn(
+    prompt: str,
+    history: list,
+    *,
+    provider_fn: Callable,
+    tool_executor,
+    tool_schemas: Optional[List[dict]] = None,
+    on_token: Optional[Callable[[str], None]] = None,
+    on_thinking: Optional[Callable[[str], None]] = None,
+    on_tool_call: Optional[Callable[[str, dict], None]] = None,
+    on_tool_result: Optional[Callable[[str, dict], None]] = None,
+    on_status: Optional[Callable[[str, str], None]] = None,
+    cancel_event=None,
+    max_rounds: int = 30,
+    confirm_tools=(),
+    approval_callback: Optional[Callable] = None,
+    approval_applier: Optional[Callable] = None,
+    requires_evidence: bool = False,
+    grounding_tools=(),
+    evidence_already_grounded: bool = False,
+    acceptance=None,
+) -> TurnResult:
+    """Drive one ``run_agent`` turn; return its text + lifecycle as a TurnResult.
+
+    Tokens are forwarded to ``on_token`` as they stream and accumulated here, so
+    the returned ``text`` is independent of the result object's field names; it
+    falls back to the turn result's authoritative ``final_text`` only if nothing
+    streamed (e.g. a non-streaming provider).
+
+    ``acceptance`` takes an :class:`~aria_code.runtime.acceptance.AcceptanceGate`.
+    Passing one makes "done" conditional on the inferred checks going green for
+    every adapter at once — CLI, headless, daemon and API — which is the point
+    of having a single gateway. Omitting it keeps the previous behaviour.
+    """
+    schemas = list(tool_schemas or [])
+    acc: List[str] = []
+    final = None
+    error: Optional[str] = None
+    cancelled = False
+
+    def _on_token(tok: str) -> None:
+        acc.append(tok)
+        if on_token is not None:
+            on_token(tok)
+
+    async for ev in run_agent(
+        prompt,
+        history,
+        provider_fn=provider_fn,
+        tool_executor=tool_executor,
+        options=AgentOptions(
+            max_rounds=max_rounds,
+            tool_schemas=schemas,
+            confirm_tools=frozenset(confirm_tools or ()),
+            approval_callback=approval_callback,
+            approval_applier=approval_applier,
+            requires_evidence=bool(requires_evidence),
+            grounding_tools=frozenset(grounding_tools or ()),
+            evidence_already_grounded=bool(evidence_already_grounded),
+            acceptance=acceptance,
+        ),
+        on_token=_on_token,         # streamed live (run_agent emits no token events)
+        on_thinking=on_thinking,    # streamed live (no thinking events either)
+        cancel_event=cancel_event,
+    ):
+        if isinstance(ev, AgentEventToolCall):
+            if on_tool_call is not None:
+                on_tool_call(ev.tool, dict(ev.params))
+        elif isinstance(ev, AgentEventToolResult):
+            if on_tool_result is not None:
+                on_tool_result(ev.tool, dict(ev.result))
+        elif isinstance(ev, AgentEventStatus):
+            if on_status is not None:
+                phase = getattr(ev, "phase", "") or getattr(ev, "state", "") or ""
+                on_status(phase, ev.message)
+        elif isinstance(ev, AgentEventComplete):
+            final = ev.result
+        elif isinstance(ev, AgentEventCancelled):
+            cancelled = True
+            if not acc:
+                partial = getattr(ev, "partial_text", "") or ""
+                if partial:
+                    acc.append(partial)
+            break
+        elif isinstance(ev, AgentEventError):
+            error = ev.error
+            break
+
+    text = "".join(acc)
+    if not text and final is not None:
+        text = getattr(final, "final_text", "") or ""
+    return TurnResult(text=text, final=final, error=error, cancelled=cancelled)