databricks-agentbricks 0.2.0__py3-none-any.whl

databricks_agentkit/openai/__init__.py

@@ -0,0 +1,93 @@
+"""OpenAI Agents SDK adapter for running an agent on Databricks (installed via ``databricks-agentbricks[openai]``).
+
+Composable pieces you drop into an existing OpenAI Agents SDK agent — a session store, MCP servers
+declared in ``agent.toml``, long-term memory tools, and MLflow tracing. Each maps onto a slot the
+Agents SDK already has, so migrating an existing agent is a graft, not a rewrite::
+
+    from databricks_agentkit.openai import (
+        session_store,
+        mcp_servers,
+        memory_tools,
+        configure_tracing,
+    )
+
+    configure_tracing()
+    agent = Agent(
+        name="Agent",
+        model="databricks-gpt-5-2",
+        tools=[*your_tools, *memory_tools()],
+        mcp_servers=await mcp_servers(),  # your agent.toml servers + any you pass
+    )
+    result = await Runner.run(agent, messages, session=session_store(session_id))
+
+These need the agent stack (openai-agents, databricks-openai, mlflow), so they sit behind the
+``[openai]`` extra to keep a plain ``databricks-agentbricks`` installation independent of agent frameworks.
+
+``__all__`` is the curated surface. Other entry points (``DatabricksSessionStore``) are reachable by
+their submodule paths but not re-exported here.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from databricks_agentkit.openai.genie import genie_tools
+    from databricks_agentkit.openai.mcp import mcp_servers
+    from databricks_agentkit.openai.memory import memory_tools
+    from databricks_agentkit.openai.sessions import session_store
+    from databricks_agentkit.runtime import (
+        start_trace,
+        workspace_client,
+        workspace_headers,
+    )
+
+
+def configure_tracing() -> None:
+    """Enable MLflow tracing with OpenAI autologging. Call once at startup.
+
+    Safe to call unconditionally — tracing turns on only when the MLflow destination and experiment
+    are configured in the environment (see :func:`databricks_agentkit.runtime.configure_tracing`).
+    """
+    import mlflow
+
+    from databricks_agentkit.runtime import configure_tracing as _configure_tracing
+
+    _configure_tracing(autolog=mlflow.openai.autolog)
+
+
+__all__ = [
+    "genie_tools",
+    # MCP servers from agent.toml (plus any you pass) — hand them to Agent(mcp_servers=...).
+    "mcp_servers",
+    # Long-term memory tools (opt-in via AGENT_MEMORY_STORE) — add to your tool list.
+    "memory_tools",
+    # Session persistence — pass session_store(session_id) to Runner.run(session=...).
+    "session_store",
+    # MLflow tracing (OpenAI autolog bound in) — call configure_tracing() once at startup.
+    "configure_tracing",
+    # Wrap each invocation in start_trace() so a trace is recorded (pass session_id= to tag it).
+    "start_trace",
+    # Workspace SDK client construction.
+    "workspace_client",
+    "workspace_headers",
+]
+
+# Re-exports resolved lazily (PEP 562) so importing one submodule (e.g. ``.mcp``) does not eagerly
+# pull in the others' dependencies. ``configure_tracing`` is defined above (binds OpenAI autolog).
+_MODULE_BY_NAME = {
+    "genie_tools": "databricks_agentkit.openai.genie",
+    "mcp_servers": "databricks_agentkit.openai.mcp",
+    "memory_tools": "databricks_agentkit.openai.memory",
+    "session_store": "databricks_agentkit.openai.sessions",
+    "start_trace": "databricks_agentkit.runtime",
+    "workspace_client": "databricks_agentkit.runtime",
+    "workspace_headers": "databricks_agentkit.runtime",
+}
+
+
+def __getattr__(name: str) -> object:
+    module = _MODULE_BY_NAME.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(module), name)

databricks_agentkit/openai/genie.py

@@ -0,0 +1,50 @@
+"""Native Genie Agent tools for OpenAI Agents, configured through ``agent.toml``."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from agents import FunctionTool, function_tool
+
+from databricks_agentkit.runtime.auth import AuthError
+from databricks_agentkit.runtime.genie import GenieAgent
+from databricks_agentkit.runtime.tool_manifest import load_tools
+
+if TYPE_CHECKING:
+    from databricks.sdk import WorkspaceClient
+
+
+def genie_tools(
+    *, workspace_client_for: Callable[[str], WorkspaceClient] | None = None
+) -> list[FunctionTool]:
+    """Build ask, poll and query-result tools for each configured Genie Agent.
+
+    Space IDs are bound from the manifest, not exposed as model arguments. Construction performs
+    no authentication or network requests; an agent with no Genie Agent bindings gets no tools.
+    """
+    tools = []
+    for record in load_tools(expected_framework="openai"):
+        if record.kind != "genie_agent":
+            continue
+        if (
+            record.auth == "user"
+            and workspace_client_for is None
+            and os.getenv("DATABRICKS_APP_NAME")
+        ):
+            raise AuthError(
+                "MCP_USER_AUTHORIZATION_MISSING",
+                "This deployed Genie integration requires request-user authorization.",
+                integration_id=record.id,
+            )
+        agent = GenieAgent(
+            record.space_id or "",
+            auth=record.auth or "app",
+            workspace_client_for=workspace_client_for,
+        )
+        tools.extend(
+            function_tool(method, name_override=f"{record.id}_{method.__name__}")
+            for method in (agent.ask, agent.poll, agent.query_result)
+        )
+    return tools

databricks_agentkit/openai/mcp.py

@@ -0,0 +1,189 @@
+"""Build MCP servers for the agent from the ones declared in ``agent.toml`` (plus any the agent adds).
+
+``mcp_servers()`` is the entry point: it reads the MCP servers declared in ``agent.toml``
+(sandbox/mcp + uc_function) and returns Agents SDK ``McpServer`` objects, with sandbox downscoping
+applied. Hand them to ``Agent(mcp_servers=...)``; the Agents SDK connects and lists their tools
+lazily inside ``Runner.run``. An agent with its own hand-built servers passes them as
+``extra_servers``; leaving ``agent.toml`` empty simply yields no declared servers. Typical use::
+
+    servers = await mcp_servers()  # just the agent.toml servers
+    servers = await mcp_servers(build_mcp_servers())  # agent.toml servers + the agent's own
+
+Unlike a fetch-once tool list, these are connection objects: open them for the life of the request
+(e.g. via ``AsyncExitStack``), because the SDK lists each server's tools only when the run needs them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from databricks_openai.agents import McpServer
+
+from databricks_agentkit.runtime import mcp_auth
+from databricks_agentkit.runtime.auth import AuthError
+from databricks_agentkit.runtime.tool_manifest import (
+    ToolRecord,
+    downscope_wire,
+    load_tools,
+)
+from databricks_agentkit.runtime.workspace import workspace_client, workspace_headers
+
+_FRAMEWORK = "openai"
+_auth_error = mcp_auth.mcp_auth_error
+_tool_error = mcp_auth.mcp_tool_error
+
+
+class _ConfiguredMcpServer(McpServer):
+    """Keep request-user failures out of SDK best-effort discovery and tool results."""
+
+    def __init__(self, *args: Any, request_user: bool, **kwargs: Any) -> None:
+        self._agentbricks_request_user = request_user
+        if request_user:
+            kwargs["failure_error_function"] = self._raise_tool_error
+        super().__init__(*args, **kwargs)
+
+    def _raise_tool_error(self, context: Any, error: Exception) -> str:
+        raise _auth_error(error, self.name) or AuthError(
+            "MCP_TOOL_FAILED", "The configured MCP tool failed.", 502, self.name
+        ) from None
+
+    async def connect(self):
+        if not self._agentbricks_request_user:
+            return await super().connect()
+        try:
+            return await super().connect()
+        except Exception as error:
+            raise _auth_error(error, self.name) or AuthError(
+                "MCP_TOOL_FAILED",
+                "Could not connect to the configured MCP service.",
+                502,
+                self.name,
+            ) from None
+
+    async def list_tools(self, *args, **kwargs):
+        if not self._agentbricks_request_user:
+            return await super().list_tools(*args, **kwargs)
+        try:
+            return await super().list_tools(*args, **kwargs)
+        except Exception as error:
+            raise _auth_error(error, self.name) or AuthError(
+                "MCP_TOOL_FAILED", "Could not discover configured MCP tools.", 502, self.name
+            ) from None
+
+    async def call_tool(self, tool_name, arguments, **kwargs):
+        if not self._agentbricks_request_user:
+            return await super().call_tool(tool_name, arguments, **kwargs)
+        try:
+            call = getattr(McpServer.call_tool, "__wrapped__", McpServer.call_tool)
+            result = await call(self, tool_name, arguments, **kwargs)
+        except Exception as error:
+            raise _auth_error(error, self.name) or AuthError(
+                "MCP_TOOL_FAILED", "The configured MCP tool failed.", 502, self.name
+            ) from None
+        if getattr(result, "isError", False) and (error := _tool_error(result, self.name)):
+            raise error
+        return result
+
+
+class _DownscopedMcpServer(_ConfiguredMcpServer):
+    """An ``McpServer`` that injects a sandbox downscope into every ``call_tool``.
+
+    The Databricks sandbox MCP applies the downscope from the call's ``_meta``; the Agents SDK does
+    not surface a per-call hook, so bind the manifest's downscope to the server and add it on each
+    invocation. Only sandbox bindings need this — plain MCP / UC-function servers use the base class.
+    """
+
+    def __init__(self, *args: Any, downscope: dict[str, Any], **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._downscope = downscope
+
+    async def call_tool(self, tool_name, arguments, **kwargs):
+        meta = {**(kwargs.pop("meta", None) or {}), "downscope": self._downscope}
+        return await super().call_tool(tool_name, arguments, meta=meta, **kwargs)
+
+
+def _server_from_tool(
+    tool: ToolRecord,
+    *,
+    workspace_client_for: mcp_auth.WorkspaceClientResolver | None = None,
+) -> McpServer | None:
+    if tool.kind not in {"sandbox", "mcp", "uc_function", "genie_one"}:
+        return None
+    mode = tool.auth or "app"
+    client = mcp_auth.resolve_mcp_workspace_client(
+        mode, tool.id, workspace_client_for, workspace_client
+    )
+    host = client.config.host.rstrip("/")
+    if tool.kind in {"sandbox", "mcp", "genie_one"}:
+        url = (
+            f"{host}/api/2.0/mcp/genie"
+            if tool.kind == "genie_one"
+            else f"{host}/ai-gateway/mcp-services/{tool.service}"
+        )
+        if tool.kind == "sandbox":
+            return _DownscopedMcpServer(
+                url=url,
+                name=tool.id,
+                workspace_client=client,
+                timeout=120.0,
+                downscope=downscope_wire(tool),
+                request_user=mode == "user",
+            )
+        if tool.kind == "genie_one":
+            return _ConfiguredMcpServer(
+                name=tool.id,
+                workspace_client=client,
+                timeout=120.0,
+                params={"url": url, "headers": workspace_headers()},
+                request_user=mode == "user",
+            )
+        return _ConfiguredMcpServer(
+            url=url,
+            name=tool.id,
+            workspace_client=client,
+            timeout=120.0,
+            request_user=mode == "user",
+        )
+    if tool.kind == "uc_function":
+        catalog, schema, function_name = (tool.function or "").split(".")
+        return _ConfiguredMcpServer.from_uc_function(
+            catalog=catalog,
+            schema=schema,
+            function_name=function_name,
+            name=tool.id,
+            workspace_client=client,
+            timeout=120.0,
+            request_user=mode == "user",
+        )
+    return None
+
+
+def _declared_servers(
+    *,
+    workspace_client_for: mcp_auth.WorkspaceClientResolver | None = None,
+) -> list[McpServer]:
+    """The MCP servers declared in the agent's ``agent.toml`` (may be empty)."""
+    tools = load_tools(expected_framework=_FRAMEWORK)
+    return [
+        server
+        for tool in tools
+        if (server := _server_from_tool(tool, workspace_client_for=workspace_client_for))
+        is not None
+    ]
+
+
+async def mcp_servers(
+    extra_servers: list[McpServer] | None = None,
+    *,
+    workspace_client_for: mcp_auth.WorkspaceClientResolver | None = None,
+) -> list[McpServer]:
+    """Build the agent's configured servers with request identity and sandbox downscoping.
+
+    Includes the MCP servers declared in ``agent.toml``; pass ``extra_servers`` to add servers the
+    agent builds itself. Request-user failures propagate. App and extra servers retain the SDK's
+    best-effort behavior; the request resolver is never forwarded to extra servers.
+    """
+    return [
+        *_declared_servers(workspace_client_for=workspace_client_for),
+        *(extra_servers or []),
+    ]

databricks_agentkit/openai/memory.py

@@ -0,0 +1,67 @@
+"""Long-term memory tools — opt-in, gated on ``AGENT_MEMORY_STORE``.
+
+Unlike the session store (short-term transcript for one conversation), long-term memory is exposed
+to the model as two tools — ``remember`` and ``recall`` — over the Databricks managed memory store's
+``2.0/agents`` entries API. Facts persist across conversations.
+
+``memory_tools(actor)`` returns the tools when ``AGENT_MEMORY_STORE`` is set, else an empty list, so
+the model never sees them when memory is unconfigured. The agent composes them into its tool list.
+This is a stand-in for a future ``databricks-openai`` memory helper — when the SDK provides one, swap
+the import in ``agent.py`` and delete this file.
+
+Memory entries are per-actor. ``actor`` is the identity whose memory these tools read and write — the
+caller (the agent server) supplies it, typically the signed-in user, so each user gets their own
+long-term memory. It is **closed over**, not a tool argument: the model only ever sees ``remember``'s
+and ``recall``'s own parameters and cannot set or spoof the actor. Pass a fixed value for one shared
+memory (e.g. a team knowledge base).
+"""
+
+from agents import FunctionTool, function_tool
+
+from databricks_agentkit.runtime.workspace import workspace_client
+
+_AGENTS_API = "/api/2.0/agents"
+
+
+def _api():
+    # Build the client lazily (needs workspace auth) so importing this module stays cheap.
+    return workspace_client().api_client
+
+
+def memory_tools(actor: str, store: str | None = None) -> list[FunctionTool]:
+    """The long-term-memory tools for ``actor`` when a memory store is configured, else none.
+
+    The store resolves ``store`` arg → ``AGENT_MEMORY_STORE`` env → the ``[memory_store]`` binding in
+    agent.toml (`ab memory bind`) → none (no tools). ``actor`` partitions the store; it is captured
+    in the tools' closures (not exposed to the model). Call this per request with the identity whose
+    memory to use (e.g. the signed-in user).
+    """
+    from databricks_agentkit.runtime.tool_manifest import resolve_memory_store
+
+    store = resolve_memory_store(store)
+    if not store:
+        return []
+    store_path = f"{_AGENTS_API}/memory-stores/{store}"
+
+    @function_tool
+    def remember(fact: str, topic: str) -> str:
+        """Persist a durable fact about the user in long-term memory."""
+        _api().do(
+            "POST",
+            f"{store_path}/entries",
+            body={"actor_id": actor, "path": f"/{topic}/{fact[:8]}.md", "content": fact},
+        )
+        return "stored"
+
+    @function_tool
+    def recall(query: str) -> str:
+        """Search the user's long-term memory for facts relevant to the query."""
+        data = _api().do(
+            "POST",
+            f"{store_path}/entries:search",
+            body={"actor_id": actor, "query": query, "limit": 5},
+        )
+        entries = data.get("managed_memory_entries") or []
+        return "\n".join(f"- {e.get('content')}" for e in entries) or "No relevant memories."
+
+    return [remember, recall]

databricks_agentkit/openai/sessions.py

@@ -0,0 +1,157 @@
+"""Conversation session store for the agent.
+
+The OpenAI Agents SDK persists conversation state through a **Session** — an object with
+``get_items``/``add_items``/``pop_item``/``clear_session`` over a list of Responses input items.
+``Runner.run(..., session=session_store(session_id))`` reads prior turns from it and appends the new
+ones. ``session_store(session_id)`` returns the Session for a given conversation.
+
+Default (no config): an in-process ``SQLiteSession`` backed by ``:memory:``, cached per session id —
+multi-turn history is preserved within a single running process, no database. It does NOT survive
+restarts or span replicas.
+
+Durable (``AGENT_SESSION_STORE`` set): a ``DatabricksSessionStore``. Instead of a database the app
+connects to directly, it stores each Responses item as one **session item** through the managed
+Session Store REST API (over RPCs only — no Lakebase/Postgres connection), so the transcript is
+durable across restarts and replicas. Setting the env var is the only change; the agent code is
+identical.
+
+Note — unlike the LangGraph checkpointer, a Session persists only the conversation transcript, not
+paused human-in-the-loop run state. Durable HITL would need the paused ``RunState`` stashed
+separately; ``agent.py`` keeps pending runs in-process only (see ``PendingRuns``).
+
+The durable store uses a vendored REST client (``session_store_client.py``) so the template needs no
+unpublished dependency; swap it for the published package when it lands.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from agents import SQLiteSession, TResponseInputItem
+from agents.memory import SessionABC
+
+from databricks_agentkit.runtime.session_store_client import Session as _StoreSession
+from databricks_agentkit.runtime.session_store_client import SessionStoreClient
+
+# Fetch items oldest-first so the transcript replays in write order.
+_ORDER_BY = "create_time asc"
+
+# One in-process Session per session id, built lazily and shared — that's what makes multi-turn work
+# in-process (the durable store needs no cache; each call resolves the same REST-backed session).
+_local_sessions: dict[str, SQLiteSession] = {}
+
+
+def session_store(
+    session_id: str, actor: str | None = None, store: str | None = None
+) -> SessionABC:
+    """The Session the agent persists conversation state to for ``session_id``.
+
+    In-memory ``SQLiteSession`` by default; a durable ``DatabricksSessionStore`` when a managed store
+    is configured. The store name resolves ``store`` arg → ``AGENT_SESSION_STORE`` env → the
+    ``[session_store]`` binding in agent.toml (`ab sessions bind`) → none. ``actor`` partitions the
+    durable store — the caller supplies it (typically the signed-in user), so each user's transcripts
+    stay separate; it defaults to ``session_id`` and is ignored by the in-memory store.
+    """
+    from databricks_agentkit.runtime.tool_manifest import resolve_session_store
+
+    store = resolve_session_store(store)
+    if store:
+        return DatabricksSessionStore(session_id, store, actor_id=actor or session_id)
+    cached = _local_sessions.get(session_id)
+    if cached is None:
+        cached = SQLiteSession(session_id)  # ":memory:" — process-local, non-durable
+        _local_sessions[session_id] = cached
+    return cached
+
+
+class DatabricksSessionStore(SessionABC):
+    """An Agents SDK ``Session`` over the Databricks Session Store REST API.
+
+    Each Responses input item is stored as one Session Store item whose ``data`` is the item dict
+    (opaque JSON to the store). ``get_items`` replays them in write order; ``pop_item`` and
+    ``clear_session`` are supported for the SDK's retry rollback path. The session is created on first
+    use (get-or-create), keyed by the conversation's ``session_id`` under the configured actor.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        session_store_name: str,
+        *,
+        actor_id: str,
+        client: Optional[SessionStoreClient] = None,
+        workspace_client: Optional[Any] = None,
+    ) -> None:
+        if not session_store_name:
+            raise ValueError("session_store_name is required")
+        self.session_id = session_id
+        self._actor_id = actor_id
+        self._client = (client or SessionStoreClient(workspace_client)).set_session_store(
+            session_store_name
+        )
+        self._session: _StoreSession | None = None
+
+    async def get_items(self, limit: int | None = None) -> list[TResponseInputItem]:
+        items = await _run_sync(self._read_items)
+        return items[-limit:] if limit is not None else items
+
+    async def add_items(self, items: list[TResponseInputItem]) -> None:
+        if not items:
+            return
+        await _run_sync(lambda: self._client.append_items(self._resolve(), items=list(items)))
+
+    async def pop_item(self) -> TResponseInputItem | None:
+        # The REST store has no pop; re-list, clear, and re-append all but the last. Only used on the
+        # SDK's best-effort retry rollback, so the extra round-trip is acceptable and rare.
+        def _pop() -> TResponseInputItem | None:
+            items = self._read_items()
+            if not items:
+                return None
+            session = self._resolve()
+            self._client.clear_items(session)
+            if items[:-1]:
+                self._client.append_items(session, items=items[:-1])
+            return items[-1]
+
+        return await _run_sync(_pop)
+
+    async def clear_session(self) -> None:
+        await _run_sync(lambda: self._client.clear_items(self._resolve()))
+
+    # ----- internals ----------------------------------------------------------
+
+    def _resolve(self) -> _StoreSession:
+        if self._session is not None:
+            return self._session
+        try:
+            self._session = self._client.get_session(session_id=self.session_id)
+        except tuple(_not_found_errors()) as _:  # type: ignore[misc]
+            self._session = self._client.create_session(
+                actor_id=self._actor_id,
+                session_id=self.session_id,
+                metadata={"client": "agentbricks-openai-agent"},
+            )
+        return self._session
+
+    def _read_items(self) -> list[TResponseInputItem]:
+        return [item.data for item in self._client.list_items(self._resolve(), order_by=_ORDER_BY)]
+
+
+def _not_found_errors() -> tuple[type, ...]:
+    """Exception types that mean 'session does not exist yet'."""
+    try:
+        from databricks.sdk.errors import NotFound
+
+        return (NotFound,)
+    except ImportError:  # pragma: no cover - SDK always present in practice
+        return (_SessionNotFound,)
+
+
+class _SessionNotFound(Exception):
+    """Fallback 'not found' used only when databricks.sdk is unavailable."""
+
+
+async def _run_sync(fn):
+    import asyncio
+
+    return await asyncio.get_running_loop().run_in_executor(None, fn)

databricks_agentkit/runtime/ARCHITECTURE.md

@@ -0,0 +1,64 @@
+# Managed runtime internals
+
+The managed runtime owns the HTTP lifecycle for one agent invocation: accepting an idempotent request,
+scheduling work, storing status and events, returning results, and replaying events to a reconnecting
+client. The public HTTP resource is an **invocation**; its UUID is also the idempotency key.
+
+```text
+Client
+  │ POST /api/invocations, GET status/events
+  ▼
+DurableAgentServer
+  HTTP adapter and @app.invoke / @app.recover hooks
+  ▼
+Runtime
+  submit, wait/poll, and event replay
+  ├── RuntimeStore
+  │     accept/get/claim/complete/fail/events
+  │     ├── InMemoryRuntimeStore
+  │     └── LakebaseDurableRuntimeStore
+  └── InvocationExecutor
+        ├── LocalInvocationExecutor
+        └── DurableInvocationExecutor
+              ├── Heartbeat
+              └── RecoveryScheduler
+```
+
+## Lifecycle
+
+`DurableAgentServer` uses `Runtime.from_environment(...)` for managed processes and
+`Runtime.from_store(...)` when a caller supplies a store explicitly. The selected Runtime Store
+determines the execution mode:
+
+- `InMemoryRuntimeStore` uses `Runtime.local()` and `LocalInvocationExecutor`. It supports the same
+  foreground, background, polling, streaming, and replay APIs, but state ends with the process.
+- `LakebaseDurableRuntimeStore` implements `DurableRuntimeStore`, so `Runtime.durable()` uses
+  `DurableInvocationExecutor`. It heartbeats the active attempt and can schedule recovery after a
+  worker stops heartbeating.
+
+`RuntimeStore` deliberately has no heartbeat operation or heartbeat state. Those lease details are
+owned by `DurableRuntimeStore` and its Lakebase implementation.
+
+`RuntimeStore.accept(invocation_id, request)` defines idempotency. The same ID and request returns
+the existing invocation; the same ID and different request raises `InvocationConflictError`.
+
+The durable executor always scans for persisted `QUEUED` invocations, including after process
+restart, and starts their first attempt through `@app.invoke`. Reads also schedule queued work as a
+safety net when a request moves between replicas. `@app.recover` is optional: registering it enables
+a separate scanner to replace stale `ACTIVE` attempts. Recovery is at least once, so agent side
+effects must be idempotent.
+
+## Code map
+
+| Path | Responsibility |
+| --- | --- |
+| `app.py` | FastAPI adapter and agent-hook registration |
+| `runtime.py` | Runtime factories plus submit, polling, and replay facade |
+| `store.py` | Shared Runtime Store contract and in-memory implementation |
+| `execution.py` | Common attempt execution and process-local scheduler |
+| `types.py` | Invocation records, contexts, errors, and JSON types |
+| `durability/store.py` | Durable Store extension for leases and recovery claims |
+| `durability/execution.py` | Durable scheduling and heartbeat-wrapped attempts |
+| `durability/heartbeat.py` | Lease refresh lifecycle |
+| `durability/recovery.py` | Stale-attempt scanning and recovery scheduling |
+| `durability/lakebase_runtime_store.py` | Lakebase Runtime Store implementation |