dex-agents 0.1.0__py3-none-any.whl

dex_agents/__init__.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Sustainable Use License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+
+"""Durable agent sessions for Dex.
+
+``AgentSessionFlow`` runs one agent session per Flow execution. A framework
+adapter implements ``AgentFrameworkRunner`` and passes it to the Flow; the
+Flow runs every model call and every tool call as its own Step, and owns the
+conversation, tool approvals, and live events. See the package README for the full contract.
+"""
+
+from dex_agents.client import AgentSessionClient
+from dex_agents.events import AgentEventType, AgentEventWriter
+from dex_agents.persistence import (
+    AGENT_MESSAGES,
+    AGENT_STATE,
+    AGENT_TOOL_CALLS,
+    AGENT_USAGE,
+    DEFAULT_AGENT_EVENTS_CAPACITY_BYTES,
+    FRAMEWORK_RUN_STATE,
+    INTERRUPT_RESOLUTIONS,
+    PENDING_INTERRUPTS,
+    QUEUED_USER_MESSAGES,
+    TOOL_CALL_RESULTS,
+    message_sequence_key,
+)
+from dex_agents.runner import (
+    APPROVAL_DEADLINE_PASSED,
+    DEFAULT_REJECTION_TOOL_RESULT,
+    OUTCOME_UNKNOWN_TOOL_RESULT,
+    TURN_FAILURE_NOTE_FOOTER,
+    TURN_FAILURE_NOTE_HEADER,
+    AgentFrameworkRunner,
+    AgentTurnContext,
+    AgentTurnOutcome,
+    DeferredToolCall,
+    DeferredToolExecution,
+    FrameworkMessage,
+    ToolCallsRequested,
+    ToolExecutionError,
+    ToolExecutionResult,
+    ToolPolicy,
+    TurnCompleted,
+    build_turn_failure_note,
+    describe_tool_call_outcome,
+    resolve_tool_policy,
+)
+from dex_agents.session_flow import AgentSessionFlow, AgentSessionOptions
+from dex_agents.values import (
+    AgentEvent,
+    AgentInterrupt,
+    AgentInterruptResolution,
+    AgentMessage,
+    AgentMessagesPage,
+    AgentSessionStartInput,
+    AgentSessionStatus,
+    AgentSnapshot,
+    AgentState,
+    AgentToolCall,
+    AgentUsage,
+    AgentUserMessage,
+    InterruptKind,
+    ListAgentMessagesRequest,
+    MessageRole,
+    ResolveInterruptRequest,
+    ToolCallCompleted,
+    ToolCallStatus,
+    ToolEffect,
+)
+
+__all__ = [
+    "AGENT_MESSAGES",
+    "AGENT_STATE",
+    "AGENT_TOOL_CALLS",
+    "AGENT_USAGE",
+    "APPROVAL_DEADLINE_PASSED",
+    "DEFAULT_AGENT_EVENTS_CAPACITY_BYTES",
+    "DEFAULT_REJECTION_TOOL_RESULT",
+    "FRAMEWORK_RUN_STATE",
+    "INTERRUPT_RESOLUTIONS",
+    "OUTCOME_UNKNOWN_TOOL_RESULT",
+    "PENDING_INTERRUPTS",
+    "QUEUED_USER_MESSAGES",
+    "TOOL_CALL_RESULTS",
+    "TURN_FAILURE_NOTE_FOOTER",
+    "TURN_FAILURE_NOTE_HEADER",
+    "AgentEvent",
+    "AgentEventType",
+    "AgentEventWriter",
+    "AgentFrameworkRunner",
+    "AgentInterrupt",
+    "AgentInterruptResolution",
+    "AgentMessage",
+    "AgentMessagesPage",
+    "AgentSessionClient",
+    "AgentSessionFlow",
+    "AgentSessionOptions",
+    "AgentSessionStartInput",
+    "AgentSessionStatus",
+    "AgentSnapshot",
+    "AgentState",
+    "AgentToolCall",
+    "AgentTurnContext",
+    "AgentTurnOutcome",
+    "AgentUsage",
+    "AgentUserMessage",
+    "DeferredToolCall",
+    "DeferredToolExecution",
+    "FrameworkMessage",
+    "InterruptKind",
+    "ListAgentMessagesRequest",
+    "MessageRole",
+    "ResolveInterruptRequest",
+    "ToolCallCompleted",
+    "ToolCallStatus",
+    "ToolCallsRequested",
+    "ToolEffect",
+    "ToolExecutionError",
+    "ToolExecutionResult",
+    "ToolPolicy",
+    "TurnCompleted",
+    "build_turn_failure_note",
+    "describe_tool_call_outcome",
+    "message_sequence_key",
+    "resolve_tool_policy",
+]

dex_agents/client.py

@@ -0,0 +1,224 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Sustainable Use License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+
+"""Typed Client calls for agent sessions."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import timedelta
+
+from dex import AsyncClient, RpcLockConflictError, StartFlowOptions, StreamMessage
+
+from dex_agents.session_flow import AgentSessionFlow
+from dex_agents.values import (
+    AgentEvent,
+    AgentMessagesPage,
+    AgentSessionStartInput,
+    AgentSnapshot,
+    AgentUserMessage,
+    ListAgentMessagesRequest,
+    ResolveInterruptRequest,
+)
+
+_LOCK_CONFLICT_RETRY_INTERVAL_SECONDS = 0.05
+
+
+class AgentSessionClient:
+    """Start agent sessions and call their RPCs with typed arguments.
+
+    Wrap the application's ``AsyncClient`` and the registered
+    ``AgentSessionFlow``. Every method is a thin call through the Client; the
+    session ID is the Flow ID.
+
+    Example:
+        >>> sessions = AgentSessionClient(client, flow)
+        >>> await sessions.start_session("session-42")
+        >>> await sessions.send_user_message("session-42", "Refund order 7")
+        >>> snapshot = await sessions.get_agent_snapshot("session-42")
+        >>> for interrupt in snapshot.pending_interrupts:
+        ...     await sessions.resolve_interrupt("session-42", interrupt.interrupt_id,
+        ...                                      approved=True)
+    """
+
+    def __init__(
+        self,
+        client: AsyncClient,
+        flow: AgentSessionFlow,
+        *,
+        lock_conflict_retry_timeout: timedelta = timedelta(seconds=5),
+    ) -> None:
+        """Create a typed view over one agent's sessions.
+
+        Args:
+            client: An open ``AsyncClient`` whose Registry contains ``flow``.
+                The caller keeps ownership and closes it.
+            flow: The registered ``AgentSessionFlow`` instance.
+            lock_conflict_retry_timeout: How long ``resolve_interrupt`` retries
+                an ``RpcLockConflictError``. Defaults to five seconds.
+        """
+        self._client = client
+        self._flow = flow
+        self._lock_conflict_retry_timeout = lock_conflict_retry_timeout
+
+    @property
+    def flow(self) -> AgentSessionFlow:
+        """Return the agent session Flow these calls target.
+
+        Returns:
+            The Flow passed to the constructor.
+        """
+        return self._flow
+
+    async def start_session(
+        self,
+        session_id: str,
+        initial_message: str | None = None,
+        options: StartFlowOptions | None = None,
+    ) -> str:
+        """Start one agent session.
+
+        Args:
+            session_id: Flow ID of the new session.
+            initial_message: Optional first user message.
+            options: Start options, such as a Request ID for an idempotent start.
+                ``None`` uses ``StartFlowOptions()``.
+
+        Returns:
+            The server-assigned run ID.
+
+        Raises:
+            FlowAlreadyStartedError: If the Flow ID is already in use.
+        """
+        return await self._client.start_flow(
+            self._flow,
+            session_id,
+            AgentSessionStartInput(initial_message=initial_message),
+            options or StartFlowOptions(),
+        )
+
+    async def send_user_message(self, session_id: str, text: str) -> bool:
+        """Queue one user message.
+
+        Args:
+            session_id: Running session.
+            text: Message text.
+
+        Returns:
+            ``True`` when queued; ``False`` for whitespace-only text.
+
+        Raises:
+            FlowNotActiveOrNotFoundError: If the session is not running.
+        """
+        return await self._client.invoke_rpc(
+            self._flow.send_user_message, session_id, AgentUserMessage(text=text)
+        )
+
+    async def resolve_interrupt(
+        self,
+        session_id: str,
+        interrupt_id: str,
+        *,
+        approved: bool,
+        rejection_message: str | None = None,
+    ) -> bool:
+        """Approve or reject one pending interrupt.
+
+        The call retries ``RpcLockConflictError`` until
+        ``lock_conflict_retry_timeout`` passes. A retry is safe because a
+        conflicting call makes no change.
+
+        Args:
+            session_id: Running session.
+            interrupt_id: ``AgentInterrupt.interrupt_id``.
+            approved: ``True`` to run the tool call.
+            rejection_message: Message the model sees after a rejection.
+
+        Returns:
+            ``True`` when resolved; ``False`` when it is unknown, already resolved,
+            or past its deadline.
+
+        Raises:
+            RpcLockConflictError: If the lock stays busy past the retry timeout.
+            FlowNotActiveOrNotFoundError: If the session is not running.
+        """
+        request = ResolveInterruptRequest(
+            interrupt_id=interrupt_id, approved=approved, rejection_message=rejection_message
+        )
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + self._lock_conflict_retry_timeout.total_seconds()
+        while True:
+            try:
+                return await self._client.invoke_rpc(
+                    self._flow.resolve_interrupt, session_id, request
+                )
+            except RpcLockConflictError:
+                if loop.time() >= deadline:
+                    raise
+                await asyncio.sleep(_LOCK_CONFLICT_RETRY_INTERVAL_SECONDS)
+
+    async def get_agent_snapshot(self, session_id: str) -> AgentSnapshot:
+        """Return the session snapshot a UI renders.
+
+        Args:
+            session_id: Running or retained closed session.
+
+        Returns:
+            The snapshot from ``get_agent_snapshot``.
+        """
+        return await self._client.invoke_rpc(self._flow.get_agent_snapshot, session_id)
+
+    async def list_agent_messages(
+        self,
+        session_id: str,
+        *,
+        before_sequence: int | None = None,
+        limit: int = 50,
+    ) -> AgentMessagesPage:
+        """Return one page of stored messages, oldest first.
+
+        Args:
+            session_id: Running or retained closed session.
+            before_sequence: Anchor from the previous page, or ``None`` for the newest page.
+            limit: Page size, clamped to 1 through 200.
+
+        Returns:
+            The page from ``list_agent_messages``.
+        """
+        return await self._client.invoke_rpc(
+            self._flow.list_agent_messages,
+            session_id,
+            ListAgentMessagesRequest(before_sequence=before_sequence, limit=limit),
+        )
+
+    async def read_agent_event(
+        self,
+        session_id: str,
+        resume_token: str = "",
+        timeout: timedelta | None = None,
+    ) -> StreamMessage[AgentEvent]:
+        """Wait for the next ``AgentEvents`` message after a resume token.
+
+        Pass each returned ``resume_token`` to the next call. Events are best
+        effort: after a gap, rebuild from ``get_agent_snapshot``.
+
+        Args:
+            session_id: Session whose events to read.
+            resume_token: Token from the previous message, or ``""`` for the
+                oldest retained event.
+            timeout: Server-side long-poll duration, or ``None`` for the default.
+
+        Returns:
+            The next event and its resume token.
+
+        Raises:
+            LongPollTimeoutError: If no event arrives before the long poll ends.
+        """
+        return await self._client.read_stream(
+            session_id, self._flow.agent_events, resume_token, timeout
+        )

dex_agents/events.py

@@ -0,0 +1,222 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Sustainable Use License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+
+"""Live event writing for the ``AgentEvents`` Stream."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from collections.abc import Callable, Mapping
+from enum import StrEnum
+
+from dex_agents.values import AgentEvent, ToolCallStatus
+
+
+class AgentEventType(StrEnum):
+    """Name every event the session writes to ``AgentEvents``.
+
+    ``AgentEvent.type`` holds one of these values as a string. Payloads are
+    JSON objects with snake_case keys.
+
+    Attributes:
+        TURN_STARTED: A user message started a turn. Payload ``{"sequence"}``,
+            the user message sequence.
+        TURN_COMPLETED: The turn produced its final answer. Payload
+            ``{"message_count"}``, the number of messages the turn appended.
+        TURN_FAILED: ``RecordTurnFailure`` ended the turn. Payload ``{"error"}``.
+        TEXT_DELTA: Visible model text. Payload ``{"text"}``.
+        REASONING_DELTA: A provider-authored reasoning summary. Payload ``{"text"}``.
+        TOOL_CALL_STARTED: A tool started. Payload ``{"tool_call_id", "tool_name"}``.
+        TOOL_CALL_FINISHED: A tool call's record became final, including a
+            rejection. Payload ``{"tool_call_id", "tool_name", "status"}``.
+        TOOL_CALL_DEFERRED: The model asked for a tool call, which runs in its own Step.
+            Payload ``{"tool_call_id", "tool_name", "effect", "requires_approval"}``.
+        INTERRUPT_RAISED: A tool call waits for approval. Payload
+            ``{"interrupt_id", "tool_call_id", "tool_name", "deadline"}``.
+        INTERRUPT_RESOLVED: An interrupt was answered or expired. Payload
+            ``{"interrupt_id", "approved", "rejection_message"}``.
+        USAGE_RECORDED: The session added one model call's usage. Payload
+            ``{"recorded", "session"}``, each an ``AgentUsage`` object.
+    """
+
+    TURN_STARTED = "turn_started"
+    TURN_COMPLETED = "turn_completed"
+    TURN_FAILED = "turn_failed"
+    TEXT_DELTA = "text_delta"
+    REASONING_DELTA = "reasoning_delta"
+    TOOL_CALL_STARTED = "tool_call_started"
+    TOOL_CALL_FINISHED = "tool_call_finished"
+    TOOL_CALL_DEFERRED = "tool_call_deferred"
+    INTERRUPT_RAISED = "interrupt_raised"
+    INTERRUPT_RESOLVED = "interrupt_resolved"
+    USAGE_RECORDED = "usage_recorded"
+
+
+class AgentEventWriter:
+    """Write live events for one Step attempt to ``AgentEvents``.
+
+    The session gives every runner call a writer bound to the current turn ID,
+    Step execution ID, and Step attempt. Writes enqueue immediately and never
+    block. They are best effort: a retry can repeat them and a consumer can miss
+    them, so never put durable results only in events.
+
+    Every method is safe to call from any thread, such as a synchronous tool
+    running in an executor thread. A call from another thread hands the event
+    to the event loop that created the writer, and the Stream receives it in
+    call order. Events written after the runner call returns are dropped.
+
+    Example:
+        >>> async def run_model_step(self, turn: AgentTurnContext) -> AgentTurnOutcome:
+        ...     async for chunk in model.stream(...):
+        ...         turn.events.write_text_delta(chunk.text)
+    """
+
+    def __init__(
+        self,
+        write_agent_event: Callable[[AgentEvent], None],
+        turn_id: str | None,
+        attempt: int,
+        step_execution_id: str = "",
+    ) -> None:
+        """Create a writer that stamps every event with its turn and Step attempt.
+
+        The session constructs writers. Construct one yourself only to test a
+        runner without a Dex Server. A writer created while an event loop runs
+        calls ``write_agent_event`` only on that loop's thread.
+
+        Args:
+            write_agent_event: Callable that appends one event to the Stream.
+            turn_id: Turn stamped on every event, or ``None``.
+            attempt: One-based Step attempt stamped on every event.
+            step_execution_id: Dex Step execution ID stamped on every event.
+        """
+        self._write_agent_event = write_agent_event
+        self._turn_id = turn_id
+        self._attempt = attempt
+        self._step_execution_id = step_execution_id
+        try:
+            self._loop: asyncio.AbstractEventLoop | None = asyncio.get_running_loop()
+        except RuntimeError:
+            self._loop = None
+        self._loop_thread_id = threading.get_ident()
+
+    @property
+    def turn_id(self) -> str | None:
+        """Return the turn ID stamped on every event.
+
+        Returns:
+            ``"turn-<n>"``, or ``None`` outside a turn.
+        """
+        return self._turn_id
+
+    @property
+    def attempt(self) -> int:
+        """Return the Step attempt stamped on every event.
+
+        Returns:
+            The one-based attempt of the Step that owns this writer.
+        """
+        return self._attempt
+
+    @property
+    def step_execution_id(self) -> str:
+        """Return the Dex Step execution ID stamped on every event.
+
+        Returns:
+            The ID shared by every attempt of the Step that owns this writer.
+        """
+        return self._step_execution_id
+
+    def write_event(self, event_type: AgentEventType | str, payload: Mapping[str, object]) -> None:
+        """Write one event with a JSON object payload.
+
+        Prefer the typed methods below for the standard event types. Use this
+        method for an adapter-specific type; give it an adapter prefix, such as
+        ``"openai_agents.handoff"``, so it never collides with a standard type.
+
+        Args:
+            event_type: Event type stored in ``AgentEvent.type``.
+            payload: JSON-compatible object stored as ``AgentEvent.payload`` text.
+
+        Raises:
+            TypeError: If ``payload`` is not JSON-serializable.
+            RuntimeError: If called from another thread after the writer's
+                event loop closed.
+        """
+        event = AgentEvent(
+            type=str(event_type),
+            turn_id=self._turn_id,
+            attempt=self._attempt,
+            payload=json.dumps(dict(payload), ensure_ascii=False, sort_keys=True),
+            step_execution_id=self._step_execution_id,
+        )
+        if self._loop is None or threading.get_ident() == self._loop_thread_id:
+            self._write_agent_event(event)
+            return
+        # The Dex Step output queue belongs to the event loop and is not thread-safe.
+        self._loop.call_soon_threadsafe(self._write_agent_event, event)
+
+    def write_text_delta(self, text: str) -> None:
+        """Write a chunk of visible model text.
+
+        Every call writes one Stream message. Batch very small chunks when the
+        framework emits one per token.
+
+        Args:
+            text: Text chunk, written as ``{"text": text}``.
+        """
+        if text:
+            self.write_event(AgentEventType.TEXT_DELTA, {"text": text})
+
+    def write_reasoning_delta(self, text: str) -> None:
+        """Write a chunk of a provider-authored reasoning summary.
+
+        Call it only for an explicit provider reasoning-summary event. Never
+        label ordinary model text as reasoning.
+
+        Args:
+            text: Reasoning summary chunk, written as ``{"text": text}``.
+        """
+        if text:
+            self.write_event(AgentEventType.REASONING_DELTA, {"text": text})
+
+    def write_tool_call_started(self, tool_call_id: str, tool_name: str) -> None:
+        """Report that a tool started running.
+
+        The session writes this event when a tool call Step starts. A runner
+        writes it only for a tool its framework cannot defer.
+
+        Args:
+            tool_call_id: Framework tool call ID.
+            tool_name: Tool name.
+        """
+        self.write_event(
+            AgentEventType.TOOL_CALL_STARTED,
+            {"tool_call_id": tool_call_id, "tool_name": tool_name},
+        )
+
+    def write_tool_call_finished(
+        self,
+        tool_call_id: str,
+        tool_name: str,
+        status: ToolCallStatus,
+    ) -> None:
+        """Report that a tool finished running.
+
+        Args:
+            tool_call_id: Framework tool call ID.
+            tool_name: Tool name.
+            status: ``SUCCEEDED`` or ``FAILED`` for a call that ran, or another
+                final status the session recorded.
+        """
+        self.write_event(
+            AgentEventType.TOOL_CALL_FINISHED,
+            {"tool_call_id": tool_call_id, "tool_name": tool_name, "status": str(status)},
+        )

dex_agents/persistence.py

@@ -0,0 +1,87 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Sustainable Use License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+
+"""Persistence definitions shared by every agent session Flow type.
+
+Every ``AgentSessionFlow`` registers these exact definition objects, so a
+Client can read any agent session with ``AsyncClient.get_attributes``. The
+``AgentEvents`` Stream is not here: each Flow type owns its own Stream object,
+available as ``AgentSessionFlow.agent_events``.
+
+Example:
+    >>> values = await client.get_attributes("session-42", AGENT_STATE, AGENT_USAGE)
+    >>> state = values.get(AGENT_STATE)
+"""
+
+from __future__ import annotations
+
+from dex import Attribute, AttributeMap, Channel, ChannelMap
+
+from dex_agents.values import (
+    AgentInterrupt,
+    AgentInterruptResolution,
+    AgentMessage,
+    AgentState,
+    AgentToolCall,
+    AgentUsage,
+    AgentUserMessage,
+    ToolCallCompleted,
+)
+
+#: Current session position. Unset until ``StartAgentSession`` commits.
+AGENT_STATE: Attribute[AgentState] = Attribute("AgentState", AgentState)
+
+#: Conversation messages keyed by ``message_sequence_key(sequence)``.
+AGENT_MESSAGES: AttributeMap[AgentMessage] = AttributeMap("AgentMessages", AgentMessage)
+
+#: Opaque framework run state JSON text, set only while a turn is suspended.
+FRAMEWORK_RUN_STATE: Attribute[str] = Attribute("FrameworkRunState", str)
+
+#: Deferred tool call records of the active turn, keyed by tool call ID.
+AGENT_TOOL_CALLS: AttributeMap[AgentToolCall] = AttributeMap("AgentToolCalls", AgentToolCall)
+
+#: Interrupts that ``resolve_interrupt`` can still answer.
+PENDING_INTERRUPTS: Attribute[list[AgentInterrupt]] = Attribute(
+    "PendingInterrupts", list[AgentInterrupt]
+)
+
+#: Model usage of the whole session.
+AGENT_USAGE: Attribute[AgentUsage] = Attribute("AgentUsage", AgentUsage)
+
+#: User messages waiting for the session to start their turns.
+QUEUED_USER_MESSAGES: Channel[AgentUserMessage] = Channel("QueuedUserMessages", AgentUserMessage)
+
+#: Interrupt answers keyed by interrupt ID.
+INTERRUPT_RESOLUTIONS: ChannelMap[AgentInterruptResolution] = ChannelMap(
+    "InterruptResolutions", AgentInterruptResolution
+)
+
+#: Internal results of tool call Steps; ``ResumeTurn`` waits for one per tool call.
+TOOL_CALL_RESULTS: Channel[ToolCallCompleted] = Channel("ToolCallResults", ToolCallCompleted)
+
+#: Default ``AgentEvents`` Stream capacity: 10 MiB.
+DEFAULT_AGENT_EVENTS_CAPACITY_BYTES = 10 * 1024 * 1024
+
+
+def message_sequence_key(sequence: int) -> str:
+    """Return the ``AgentMessages`` map instance for a message sequence.
+
+    Use it to read one stored message with ``AGENT_MESSAGES.instance(...)``.
+
+    Args:
+        sequence: Positive message sequence.
+
+    Returns:
+        The sequence as a 12-digit zero-padded decimal, such as ``"000000000007"``.
+
+    Raises:
+        ValueError: If ``sequence`` is not positive.
+    """
+    if sequence <= 0:
+        raise ValueError("message sequence must be positive")
+    return f"{sequence:012d}"