agentdeck-sdk 3.1.0__py3-none-any.whl

agentdeck/adapters/engines/openai_agents/sessions.py

@@ -0,0 +1,100 @@
+"""The openai-agents adapter's private execution state (ADR-D5: the engine's working
+memory is its own, never read by consumers).
+
+``SessionFactory`` is relocated here unchanged from ``runtime/sessions.py`` — kept, not
+rewritten: it mints per-id :class:`agents.extensions.memory.RedisSession`
+objects sharing one Redis client. ``ExecutionStore`` is the adapter's own seam on top of
+it: Redis-backed when a factory is configured, one in-process
+:class:`agents.SQLiteSession` per key otherwise — the same fallback ``agentdeck.deck.Deck``
+uses for its chat methods, so both callers of the SDK agree on what "no Redis configured"
+means. Nothing outside this adapter directory may import either class.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agents import SQLiteSession
+from agents.extensions.memory import RedisSession
+from redis.asyncio import Redis
+
+if TYPE_CHECKING:
+    from agents.memory.session import Session
+
+    from agentdeck.core.context import RunContext
+    from agentdeck.runtime.settings import SessionSettings
+
+
+class SessionFactory:
+    """Builds per-id :class:`RedisSession` objects sharing one Redis client."""
+
+    def __init__(
+        self,
+        redis_client: Redis,
+        *,
+        key_prefix: str = "agents:session",
+        ttl: int | None = None,
+    ) -> None:
+        self._redis = redis_client
+        self._key_prefix = key_prefix
+        self._ttl = ttl
+
+    @classmethod
+    def from_settings(cls, settings: SessionSettings) -> SessionFactory | None:
+        """Build from :class:`SessionSettings` or return ``None`` when disabled."""
+        if not settings.url:
+            return None
+        return cls(
+            Redis.from_url(settings.url),
+            key_prefix=settings.redis_key_prefix,
+            ttl=settings.redis_ttl,
+        )
+
+    def session_for(self, session_id: str) -> Session:
+        return RedisSession(
+            session_id,
+            redis_client=self._redis,
+            key_prefix=self._key_prefix,
+            ttl=self._ttl,
+        )
+
+    async def aclose(self) -> None:
+        await self._redis.aclose()
+
+
+class ExecutionStore:
+    """The engine's execution memory, keyed by ``(namespace, RunContext.log_key)`` — session,
+    or the run itself when there is no session.
+
+    Not the event log: this is engine-native state (ADR-D5) that only ``OpenAIAgentsEngine``
+    reads. ``session_factory`` set means Redis-backed and shared across processes; unset
+    falls back to one in-process ``SQLiteSession`` per key, so tests and the M0 skeleton
+    need no network. The namespace prefix matters even though ``log_key`` is usually a
+    server-generated session id: two namespaces are free to pick the same one, and without
+    it their conversations would share one SDK session — exactly the isolation the event
+    stores already enforce (``adapters/stores/memory``'s namespace-scoped buckets).
+    """
+
+    def __init__(self, session_factory: SessionFactory | None = None) -> None:
+        self._session_factory = session_factory
+        # Precisely SQLiteSession, not the broader Session protocol: aclose() below
+        # needs its close(), which isn't part of SessionABC.
+        self._local: dict[str, SQLiteSession] = {}
+
+    def session_for(self, ctx: RunContext) -> Session:
+        key = f"{ctx.namespace_key}:{ctx.log_key}"
+        if self._session_factory is not None:
+            return self._session_factory.session_for(key)
+        return self._local.setdefault(key, SQLiteSession(key))
+
+    async def aclose(self) -> None:
+        # ponytail: SQLiteSession.close() is sync and cheap for the :memory:/local-file
+        # fallback this is — a pool with async teardown is follow-up work if a real
+        # deployment ever wants the local path instead of Redis.
+        for session in self._local.values():
+            session.close()
+        if self._session_factory is not None:
+            await self._session_factory.aclose()
+
+
+__all__ = ["ExecutionStore", "SessionFactory"]

agentdeck/adapters/engines/openai_agents/translate.py

@@ -0,0 +1,124 @@
+"""Stream-event → canonical-payload translation.
+
+Ported from the delta-only extraction in ``agents/runners/headless.py`` (v1 stays
+untouched) and widened to text deltas, completed messages, tool calls and their results.
+Reasoning items are deliberately not translated (ADR-D5: they live only in the SDK
+session, and mirroring them would chain the event schema to the SDK's item format).
+Handoffs are not a core kind (D10: engines translate or namespace, never mint), so a
+completed handoff becomes one namespaced ``custom`` event.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from typing import Any
+
+from agentdeck.core.events import (
+    RESULT_PREVIEW_MAX,
+    Custom,
+    KnownPayload,
+    MessageCompleted,
+    TextDelta,
+    ToolCallCompleted,
+    ToolCallStarted,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def translate(event: Any, tool_names: dict[str, str]) -> KnownPayload | None:
+    """One stream event → one payload, or ``None`` for anything M0 doesn't surface.
+
+    ``tool_names`` is the run's own ``call_id`` → tool-name map: ``tool.call.completed``
+    doesn't carry the name, so it is remembered from the paired ``tool.call.started``.
+    """
+    if event.type == "raw_response_event":
+        return _translate_raw(event.data)
+    if event.type != "run_item_stream_event":
+        return None  # agent_updated_stream_event: bookkeeping only, no payload
+    return _translate_item(event.item, tool_names)
+
+
+def _translate_raw(data: Any) -> KnownPayload | None:
+    if getattr(data, "type", None) != "response.output_text.delta":
+        return None  # every other raw SDK event (created/completed/reasoning/...) is noise here
+    return TextDelta(message_id=data.item_id, text=data.delta)
+
+
+def _translate_item(item: Any, tool_names: dict[str, str]) -> KnownPayload | None:
+    kind = item.type
+    if kind == "tool_call_item":
+        return _tool_call_started(item, tool_names)
+    if kind == "tool_call_output_item":
+        return _tool_call_completed(item, tool_names)
+    if kind == "message_output_item":
+        return _message_completed(item)
+    if kind == "handoff_output_item":
+        return _handoff(item)
+    # handoff_call_item (paired with handoff_output_item, nothing new to say), reasoning
+    # items, MCP approval items, computer-use items: not surfaced at M0.
+    return None
+
+
+def _tool_call_started(item: Any, tool_names: dict[str, str]) -> KnownPayload | None:
+    raw = item.raw_item
+    call_id, name = getattr(raw, "call_id", None), getattr(raw, "name", None)
+    if call_id is None or name is None:
+        return None  # non-function tool call (e.g. computer use) — out of scope for M0
+    tool_names[call_id] = name
+    args = _parse_args(getattr(raw, "arguments", None))
+    if "_raw" in args:
+        # Content-free by design: call_id and tool name only — the raw arguments string
+        # could carry user content and must never reach a log line.
+        logger.warning("tool call %s (%s) had non-dict JSON args, degraded to _raw", call_id, name)
+    return ToolCallStarted(call_id=call_id, tool=name, args=args)
+
+
+def _parse_args(arguments: str | None) -> dict[str, Any]:
+    """Malformed model-emitted JSON degrades to a raw string field rather than killing the
+    run over a cosmetic payload attribute — the tool call itself still happened and is
+    still logged."""
+    if not arguments:
+        return {}
+    try:
+        parsed = json.loads(arguments)
+    except json.JSONDecodeError:
+        return {"_raw": arguments}
+    return parsed if isinstance(parsed, dict) else {"_raw": arguments}
+
+
+def _tool_call_completed(item: Any, tool_names: dict[str, str]) -> KnownPayload:
+    call_id = item.call_id or ""
+    result = str(item.output)
+    encoded = result.encode()
+    # TODO(#52): a non-function tool call (computer-use, MCP approval) never populates
+    # tool_names via _tool_call_started (that function returns None for it), so its
+    # result lands here as an orphan tool.call.completed with tool="unknown" and no
+    # paired .started — out of scope for M0's function-tool-only UC1.
+    return ToolCallCompleted(
+        call_id=call_id,
+        tool=tool_names.get(call_id, "unknown"),
+        result_preview=result[:RESULT_PREVIEW_MAX],
+        result_size=len(encoded),
+        result_sha256=hashlib.sha256(encoded).hexdigest(),
+    )
+
+
+def _message_completed(item: Any) -> KnownPayload:
+    raw = item.raw_item
+    text = "".join(getattr(part, "text", "") for part in getattr(raw, "content", ()))
+    return MessageCompleted(message_id=raw.id, text=text)
+
+
+def _handoff(item: Any) -> KnownPayload:
+    # ADR-D5's invariant ("everything that enters or leaves execution state is recorded")
+    # without minting a kind (D10): one namespaced custom event, not a new payload class.
+    return Custom(
+        name="openai_agents.handoff",
+        data={"from": item.source_agent.name, "to": item.target_agent.name},
+    )
+
+
+__all__ = ["translate"]

agentdeck/adapters/engines/stub/__init__.py

@@ -0,0 +1,5 @@
+"""The scripted stub engine — the reference implementation of the engine contract."""
+
+from agentdeck.adapters.engines.stub.engine import Step, StubEngine, stub_spec
+
+__all__ = ["Step", "StubEngine", "stub_spec"]

agentdeck/adapters/engines/stub/engine.py

@@ -0,0 +1,100 @@
+"""The engine that plays a script — the reference implementation of ``EnginePort``.
+
+An invocable's ``native`` is the script: payloads to yield in order, with any exception in
+the sequence raised where it sits. That covers every way a run can end — completes, fails
+mid-stream, interrupts, or stops without a terminal event — with no model, no network and
+no timing, which is why it stays the contract suite's fastest engine rather than a
+placeholder for a real one. A ``RunInterrupted`` step splits the script in two: ``start``
+plays up to and including it, then stops (mirroring a real engine suspending); ``resume``
+plays whatever comes after it — so one script expresses both halves of a suspend/resume
+case without a second field on ``InvocableSpec``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from agentdeck.core.control import ControlSignalled
+from agentdeck.core.events import RunInterrupted
+from agentdeck.core.invocable import InvocableKind, InvocableSpec
+from agentdeck.core.ports import EnginePort
+from agentdeck.errors import ConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+    from agentdeck.core.content import Input
+    from agentdeck.core.context import RunContext
+    from agentdeck.core.events import Event, KnownPayload
+
+type Step = KnownPayload | Exception
+"""One scripted step: a payload to yield, or an exception to raise at that point."""
+
+
+class StubEngine(EnginePort):
+    """Plays ``spec.native`` back as a run. Scripts are reusable: payloads are immutable.
+
+    Honors the gate between steps, so run control is part of what this engine models rather
+    than something only a real one can be tested against.
+    """
+
+    engine: ClassVar[str] = "stub"
+
+    async def start(
+        self,
+        spec: InvocableSpec,
+        input: Input,
+        history: Sequence[Event],
+        ctx: RunContext,
+    ) -> AsyncGenerator[KnownPayload, None]:
+        for step in _script_of(spec):
+            if isinstance(step, Exception):
+                raise step
+            yield step
+            if isinstance(step, RunInterrupted):
+                return  # suspend here; resume() plays whatever the script has after this
+            try:
+                await ctx.gate.checkpoint()
+            except ControlSignalled as signalled:
+                # Between two steps is this engine's stream_item boundary — the same safe
+                # point a real engine has between two translated items, which is what lets
+                # the contract suite hold both to one control contract.
+                for payload in signalled.payloads:
+                    yield payload
+                return
+
+    async def resume(
+        self,
+        spec: InvocableSpec,
+        thread_id: str,
+        value: Any,
+        ctx: RunContext,
+    ) -> AsyncGenerator[KnownPayload, None]:
+        after_interrupt = False
+        for step in _script_of(spec):
+            if not after_interrupt:
+                after_interrupt = isinstance(step, RunInterrupted)
+                continue
+            if isinstance(step, Exception):
+                raise step
+            yield step
+
+
+def stub_spec(name: str, *steps: Step, kind: InvocableKind = InvocableKind.AGENT) -> InvocableSpec:
+    """A scripted invocable. Leave ``run.started`` out — the Runtime opens every run itself."""
+    return InvocableSpec(name=name, kind=kind, engine=StubEngine.engine, native=steps)
+
+
+def _script_of(spec: InvocableSpec) -> tuple[Step, ...]:
+    """A misconfigured invocable is the caller's mistake, not a run that failed — so this is a
+    ``ConfigError`` at the adapter's edge rather than a stdlib type leaking into ``run.failed``."""
+    script = spec.native
+    if isinstance(script, str) or not isinstance(script, Sequence):
+        raise ConfigError(
+            f"{spec.name!r} has no stub script: expected a sequence of payloads in native, got {type(script).__name__}"
+        )
+    return tuple(script)
+
+
+__all__ = ["Step", "StubEngine", "stub_spec"]

agentdeck/adapters/stores/__init__.py

@@ -0,0 +1 @@
+"""Event-log stores — implementations of ``EventStorePort``."""

agentdeck/adapters/stores/memory/__init__.py

@@ -0,0 +1,5 @@
+"""The event log in a dict."""
+
+from agentdeck.adapters.stores.memory.store import MemoryEventStore
+
+__all__ = ["MemoryEventStore"]

agentdeck/adapters/stores/memory/store.py

@@ -0,0 +1,148 @@
+"""The event log in a dict: the default for dev, tests and the contract suite."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from agentdeck.core.events import Event
+from agentdeck.core.ports import EventStorePort, RunSummary, SessionClaim
+from agentdeck.core.status import LIFECYCLE_KINDS, TERMINAL_STATUSES, RunStatus, can_resume, status_of
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+    from datetime import timedelta
+
+    from agentdeck.core.context import RunContext
+    from agentdeck.core.events import KnownPayload, RunResumed, RunStarted
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+class MemoryEventStore(EventStorePort):
+    """Append-only lists, one per (namespace, log key). Process exit is data loss, by design.
+
+    Keyed by namespace as well as log key so two namespaces that pick the same session id cannot
+    read each other's runs — isolation is not something a store gets to skip.
+    """
+
+    def __init__(self, clock: Callable[[], datetime] = _now) -> None:
+        self._logs: dict[tuple[str | None, str], list[Event]] = {}
+        self._clock = clock
+
+    async def append(self, log_key: str, payloads: Sequence[KnownPayload], ctx: RunContext, origin: str) -> list[Event]:
+        events = self._stamp(log_key, payloads, ctx, origin)
+        # Fidelity, not correctness (issue #87): every real store suspends here (SQLite's own
+        # `to_thread`), so a caller whose liveness secretly depends on that turn is caught by
+        # this store too, instead of only by measurement in production. Placed after the
+        # mutation in `_stamp`, so it opens no window in either claim's atomicity.
+        await asyncio.sleep(0)
+        return events
+
+    def _stamp(self, log_key: str, payloads: Sequence[KnownPayload], ctx: RunContext, origin: str) -> list[Event]:
+        """Assign, build and write, with no suspension point anywhere in between.
+
+        That is this store's whole atomicity mechanism, and it is why every caller here — both
+        claims included — goes through this rather than through ``append``: an ``await`` between
+        reading the run's last ``seq`` and extending the log is all it would take for two tasks to
+        be handed the same number.
+        """
+        log = self._logs.setdefault((ctx.namespace, log_key), [])
+        seq = max((stored.seq for stored in log if stored.run_id == ctx.run_id), default=-1)
+        events = []
+        for payload in payloads:
+            seq += 1
+            events.append(
+                Event(
+                    kind=payload.kind,
+                    seq=seq,
+                    run_id=ctx.run_id,
+                    session_id=ctx.session_id,
+                    namespace=ctx.namespace,
+                    origin=origin,
+                    ts=self._clock(),
+                    payload=payload,
+                )
+            )
+        log.extend(events)
+        return events
+
+    async def read(self, log_key: str, ctx: RunContext, offset: int = 0, limit: int | None = None) -> list[Event]:
+        if limit is not None and limit < 0:
+            raise ValueError(f"limit must be None or >= 0, got {limit}")
+        log = self._logs.get((ctx.namespace, log_key), ())
+        page = log[max(offset, 0) :]
+        return list(page if limit is None else page[:limit])
+
+    async def read_run(self, log_key: str, run_id: str, ctx: RunContext, from_seq: int = 0) -> list[Event]:
+        log = self._logs.get((ctx.namespace, log_key), ())
+        return [event for event in log if event.run_id == run_id and event.seq >= from_seq]
+
+    async def claim_start(
+        self, log_key: str, opening: RunStarted, ctx: RunContext, origin: str, stale_after: timedelta
+    ) -> tuple[SessionClaim, Event | None]:
+        """Atomic for free, like ``claim_resume``: the scan and ``_stamp`` are plain dict work
+        with no suspension point between them, so no other task can open a run in the gap.
+        """
+        stale_before = self._clock() - stale_after
+        overridden: list[Event] = []
+        for events in _by_run(self._logs.get((ctx.namespace, log_key), ())).values():
+            status = status_of(events)
+            if status is RunStatus.PENDING or status in TERMINAL_STATUSES:
+                continue
+            if events[-1].ts > stale_before:
+                return SessionClaim(held_by=events[-1].run_id), None
+            overridden.append(events[-1])
+        event = self._stamp(log_key, [opening], ctx, origin)[0]
+        await asyncio.sleep(0)
+        return SessionClaim(overridden=tuple(overridden)), event
+
+    async def claim_resume(
+        self, log_key: str, run_id: str, resumed: RunResumed, ctx: RunContext, origin: str
+    ) -> Event | None:
+        """Atomic for free: the status fold and ``_stamp`` are plain dict work with no suspension
+        point between them, so no other task can slip in and claim the same run.
+        """
+        if ctx.run_id != run_id:
+            raise ValueError(f"a claim on run {run_id!r} cannot be made in the context of {ctx.run_id!r}")
+        mine = [stored for stored in self._logs.get((ctx.namespace, log_key), ()) if stored.run_id == run_id]
+        if not can_resume(status_of(mine)):
+            return None
+        event = self._stamp(log_key, [resumed], ctx, origin)[0]
+        await asyncio.sleep(0)
+        return event
+
+    async def list_runs(self, ctx: RunContext, status: RunStatus | None = None) -> list[RunSummary]:
+        runs = [
+            (log_key, event.run_id)
+            for (namespace, log_key), log in self._logs.items()
+            if namespace == ctx.namespace
+            for event in log
+            if event.kind in LIFECYCLE_KINDS
+        ]
+        # One fold per run through the port's own projection rather than a second inline
+        # copy of it: re-walking a dev-sized dict is cheaper than two ways to derive status.
+        summaries = [
+            RunSummary(log_key=log_key, run_id=run_id, status=await self.run_status(log_key, run_id, ctx))
+            for log_key, run_id in dict.fromkeys(runs)
+        ]
+        return [summary for summary in summaries if status is None or summary.status is status]
+
+
+# The unique-index equivalent this store used to need is gone: no caller supplies a ``seq``, and
+# ``_stamp`` reads the run's last one and extends the log with no suspension in between, so two
+# events at one ``seq`` is unconstructible rather than merely refused (ADR-D11 §6).
+
+
+def _by_run(log: Sequence[Event]) -> dict[str, list[Event]]:
+    """One log's events split per run, each list still in append order."""
+    runs: dict[str, list[Event]] = {}
+    for event in log:
+        runs.setdefault(event.run_id, []).append(event)
+    return runs
+
+
+__all__ = ["MemoryEventStore"]

agentdeck/adapters/stores/postgres/__init__.py

@@ -0,0 +1,5 @@
+"""The event log in Postgres (ADR-D5: the platform record, not engine state)."""
+
+from agentdeck.adapters.stores.postgres.store import PostgresEventStore
+
+__all__ = ["PostgresEventStore"]