sectr 0.0.4__py3-none-any.whl

sectr/__init__.py

@@ -0,0 +1,53 @@
+"""Sectr Python SDK: framework-agnostic agent deployment.
+
+Core (framework-free): `AgentApp` (route registry), `SessionContext` (the
+handler argument), `sectr.events` (typed events mirroring
+schema/event.schema.json), `sectr.tools` (`@tool` registry + approval
+gating). Handlers are async generators of events; the FastAPI server
+adapter (`sectr.server`) speaks the runner invoke contract, and framework
+adapters (`sectr.adapters.*`) wrap native framework objects into handlers.
+
+Contracts: `../schema/` is the single source of truth — see `schema/PLAN.md`
+and `sdk-python/PLAN.md`.
+"""
+
+from .app import AgentApp, Handler, Route
+from .context import SessionContext
+from .events import (
+    Envelope,
+    Error,
+    MessageDelta,
+    MessageEnd,
+    MessageStart,
+    NoMoreActions,
+    RunnerEvent,
+    TranscriptCompacted,
+    ToolApprovalRequired,
+    ToolCall,
+    ToolResult,
+    NoMoreActions,
+)
+from .tools import ApprovalRequired, Tool, tool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentApp",
+    "ApprovalRequired",
+    "Envelope",
+    "Error",
+    "Handler",
+    "MessageDelta",
+    "MessageEnd",
+    "MessageStart",
+    "Route",
+    "RunnerEvent",
+    "SessionContext",
+    "Tool",
+    "ToolApprovalRequired",
+    "ToolCall",
+    "ToolResult",
+    "NoMoreActions",
+    "TranscriptCompacted",
+    "tool",
+]

sectr/adapters/__init__.py

@@ -0,0 +1,12 @@
+"""Framework adapters (optional extras). Each adapter is a handler factory:
+it takes the framework's native object and returns a
+`(SessionContext) -> AsyncIterator[RunnerEvent]` handler, so registration is
+one line per app:
+
+    app.add_route("/chat", openai_agents(agent))
+    app.add_route("/chat", langgraph(graph))
+    app.add_route("/chat", claude_code(options))
+
+Mapping details (pause/resume semantics, transcript reconstruction) are
+documented per module and pinned by the variant sketches in `examples/`.
+"""

sectr/adapters/claude_code.py

@@ -0,0 +1,45 @@
+"""Claude Code adapter (`sectr[claude-code]` extra) — the near-black-box
+case: the CLI owns its loop, tools, and permissions.
+
+`claude_code(**options)` returns a handler that (see
+`examples/claude-code/main.py`; session-memory mapping decided in
+`examples/claude-code/PLAN.md`):
+
+- runs the `claude` CLI (via claude-code-sdk) with `--resume` keyed to our
+  session_id (option (b): the CLI's workspace state persists across turns;
+  the journal stays authoritative for approvals, SSE, audit, transcript);
+- assistant text → MESSAGE_*; ToolUseBlock → TOOL_CALL; ToolResultBlock →
+  TOOL_RESULT; result message → NO_MORE_ACTIONS (turn over);
+- pause: the CLI's `can_use_tool` permission callback fires → the adapter
+  captures (tool_name, input), terminates the subprocess, journals
+  TOOL_APPROVAL_REQUIRED as the final frame (turn suspended, no sentinel);
+- resume: `--resume` the same session; when the CLI re-issues the gated
+  tool and asks permission, the adapter answers from
+  `ctx.decision` (allow/deny). At most ONE pending approval per
+  session is possible by the turn model.
+
+CI note: the `claude` binary is a shim script emitting canned JSONL
+(examples/claude-code/tests/shim_claude.py). Implementation pending.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from ..app import Handler
+from ..context import SessionContext
+from ..events import RunnerEvent
+
+__all__ = ["claude_code"]
+
+
+def claude_code(**options: Any) -> Handler:
+    """Handler factory wrapping claude-code-sdk options. Implementation
+    pending."""
+
+    async def handler(ctx: SessionContext) -> AsyncIterator[RunnerEvent]:
+        raise NotImplementedError("sectr.adapters.claude_code")
+        yield  # pragma: no cover - makes this an async generator
+
+    return handler

sectr/adapters/langgraph.py

@@ -0,0 +1,80 @@
+"""LangGraph adapter (`sectr[langgraph]` extra).
+
+`langgraph(graph)` returns a handler that (see `examples/langgraph/main.py`):
+
+- normal turn: transcript → `{"messages": [...]}` state; `graph.astream`
+  (stream_mode="messages") → MESSAGE_* / TOOL_CALL / TOOL_RESULT;
+  stream end → NO_MORE_ACTIONS (turn over). No LangGraph checkpointer — the journal
+  is the checkpoint.
+- pause: the sectr-gated tool raises `ApprovalRequired` inside the tool
+  node; the adapter catches it escaping `astream` → journaled
+  TOOL_APPROVAL_REQUIRED as the final frame (turn suspended, no sentinel).
+- resume: rebuild messages from the transcript, execute the approved tool
+  via the sectr tool wrapper (or denial), append the ToolMessage, continue.
+
+Post-MVP option (recorded in sdk-python/PLAN.md): a session-scoped
+checkpointer workspace enables idiomatic `interrupt()` /
+`Command(resume=decision)` tool bodies. Implementation pending.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, cast
+
+from ..app import Handler
+from ..context import SessionContext
+from ..events import RunnerEvent
+from ..tools import ApprovalRequired
+
+__all__ = ["langgraph", "as_langgraph_tool"]
+
+
+def langgraph(graph: Any) -> Handler:
+    """Handler factory wrapping a compiled LangGraph. Implementation pending."""
+
+    async def handler(ctx: SessionContext) -> AsyncIterator[RunnerEvent]:
+        raise NotImplementedError("sectr.adapters.langgraph")
+        yield  # pragma: no cover - makes this an async generator
+
+    return handler
+
+
+def as_langgraph_tool(t: Any) -> Any:
+    """Convert a sectr `Tool` into a LangGraph/langchain-compatible tool,
+    preserving approval gating: the coroutine raises `ApprovalRequired`
+    inside the tool node when gated (the adapter catches it escaping
+    `astream` and ends the turn). Skeleton implementation — schema inferred
+    from the original function signature; golden tests arrive with the
+    adapter's functional round."""
+    import inspect
+
+    from langchain_core.tools import StructuredTool
+    from pydantic import create_model
+
+    if t.description is None:
+        raise ValueError(f"tool {t.name!r} needs a docstring (used as the LLM description)")
+
+    params = inspect.signature(t.fn).parameters
+    fields = {
+        pname: (
+            p.annotation if p.annotation is not inspect.Parameter.empty else str,
+            ... if p.default is inspect.Parameter.empty else p.default,
+        )
+        for pname, p in params.items()
+    }
+    # pydantic's create_model overloads don't cleanly accept a heterogeneous
+    # kwargs dict — a cast is honest here; schema correctness is golden-tested
+    # with the adapter's functional round.
+    args_schema = create_model(f"{t.name}_args", **cast(Any, fields))
+
+    from ..tools import is_gated
+
+    async def _run(**kwargs: Any) -> Any:
+        if is_gated(t.name):
+            raise ApprovalRequired(t.name, kwargs)
+        return await t(**kwargs)
+
+    return StructuredTool.from_function(
+        coroutine=_run, name=t.name, description=t.description, args_schema=args_schema
+    )

sectr/adapters/openai_agents.py

@@ -0,0 +1,399 @@
+"""openai-agents adapter (`sectr[openai-agents]` extra).
+
+`openai_agents(agent, *, model=None, run_config=None)` returns a handler
+mapping the SDK's native streaming + HITL onto the platform contract
+(design: `sdk-python/PLAN.md`, "Resume semantics (framework adapters)"):
+
+- normal turn: transcript → input items; `Runner.run_streamed`; text deltas
+  → MESSAGE_DELTA; `tool_called` → TOOL_CALL; `tool_output` → TOOL_RESULT;
+  exhaustion → NO_MORE_ACTIONS (appended by `drive`).
+- pause: the framework's native interruption path — approval-gated tools
+  (`needs_approval` ∪ platform `SECTR_APPROVAL_POLICY`) produce
+  `result.interruptions` after the stream drains. Verified against SDK 0.22:
+  the gated call DOES stream a `tool_called` item before the interruption
+  (only the `ToolApprovalItem` itself is suppressed from the item stream),
+  so TOOL_CALL is journaled from the stream; the interruption path journals
+  it too only if the stream never emitted it (defensive against SDK
+  changes), then TOOL_APPROVAL_REQUIRED as the final frame (turn suspended).
+  More than one interruption in one turn cannot be represented by the
+  contract (one decision per resume) and fails loudly — batched approvals
+  are backlogged (see schema/PLAN.md).
+- resume (`reason.kind == "approval_decision"`): NO RunState — the runner is
+  stateless and the journal is framework-opaque. Input items are rebuilt
+  from the transcript, the pending call is answered (approved: the tool
+  object is executed directly; denied: the SDK's model-visible rejection
+  text), and the run continues — the LLM sees the full conversation
+  including the answered call and generates only the continuation.
+- tracing is disabled by default (dev runs have no OpenAI tracing sink);
+  pass your own `run_config` to override any of this.
+
+The sectr tool registry (`sectr.tools`) is NOT involved — openai-agents has
+native HITL, so tools stay 100% framework code (zero sectr imports in the
+user's tool module, per `examples/PLAN.md`).
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import AsyncIterator
+from dataclasses import replace
+from typing import Any, cast
+
+from agents import Agent as OAgent  # noqa: N811 — disambiguate from sectr
+from agents import Model, RunConfig, Runner
+from agents.tool_context import ToolContext
+from agents.items import (
+    MessageOutputItem,
+    ToolApprovalItem,
+    ToolCallItem,
+    ToolCallOutputItem,
+)
+from agents.tool import FunctionTool
+from agents.stream_events import RawResponsesStreamEvent, RunItemStreamEvent
+
+from ..app import Handler
+from ..context import SessionContext
+from ..events import (
+    Error,
+    MessageDelta,
+    MessageEnd,
+    MessageStart,
+    RunnerEvent,
+    ToolCall,
+    ToolApprovalRequired,
+    ToolResult,
+)
+from ..tools import platform_approval_policy
+
+__all__ = ["openai_agents"]
+
+# The SDK's default model-visible text for a rejected approval
+# (`agents.run_internal.items.REJECTION_MESSAGE`); kept literal so the
+# adapter doesn't depend on a private module path.
+REJECTION_MESSAGE = "Tool execution was not approved."
+
+
+def openai_agents(
+    agent: OAgent,
+    *,
+    model: Model | None = None,
+    run_config: RunConfig | None = None,
+) -> Handler:
+    """Handler factory wrapping an `agents.Agent`.
+
+    `model` / `run_config` pass through to `Runner.run_streamed` — used for
+    deterministic fakes in CI (`SECTR_FAKE=1` in the examples) and power-user
+    config. Tracing is disabled unless the caller supplies a run_config.
+    """
+
+    async def handler(ctx: SessionContext) -> AsyncIterator[RunnerEvent]:
+        run_agent = _apply_platform_policy(agent)
+        config = run_config or RunConfig(model=model, tracing_disabled=True)
+
+        input_items: Any
+        resumed_result: ToolResult | None = None
+        if ctx.reason.get("kind") == "approval_decision":
+            input_items, resumed_result = await _resume_input(ctx, agent)
+        else:
+            # EVERY turn continues the conversation: rebuild input items
+            # from the canonical transcript (which already contains this
+            # invocation's user message via its INVOCATION_STARTED).
+            # Feeding only `ctx.input` here ran every user turn as a COLD
+            # conversation — the model never saw prior turns (found live
+            # in the M1 run: turn 2 forgot the order ID turn 1 had just
+            # looked up; scripted fake-model tests used self-contained
+            # turns and empty transcripts, so it was invisible).
+            input_items = _transcript_items(ctx)
+        if resumed_result is not None:
+            yield resumed_result
+
+        result = Runner.run_streamed(run_agent, cast(Any, input_items), run_config=config)
+
+        open_message: str | None = None  # synthesized id of the streaming message
+        journaled_calls: set[str] = set()  # call_ids already TOOL_CALL-journaled
+        async for event in result.stream_events():
+            if isinstance(event, RawResponsesStreamEvent):
+                raw = event.data  # an OpenAI response stream event (0.22: `data`)
+                if raw.type == "response.output_text.delta":
+                    if open_message is None:
+                        open_message = uuid.uuid4().hex[:16]
+                        yield MessageStart(role="assistant", message_id=open_message)
+                    yield MessageDelta(
+                        message_id=open_message,
+                        delta={"type": "text", "text": raw.delta},
+                    )
+                elif raw.type in (
+                    "response.reasoning_summary_text.delta",
+                    "response.reasoning_text.delta",
+                ):
+                    if open_message is None:
+                        open_message = uuid.uuid4().hex[:16]
+                        yield MessageStart(role="assistant", message_id=open_message)
+                    yield MessageDelta(
+                        message_id=open_message,
+                        delta={"type": "reasoning", "text": raw.delta},
+                    )
+                continue
+            if isinstance(event, RunItemStreamEvent):
+                if isinstance(event.item, MessageOutputItem):
+                    if open_message is not None:
+                        yield MessageEnd(message_id=open_message)
+                        open_message = None
+                elif isinstance(event.item, ToolCallItem):
+                    call: Any = event.item.raw_item
+                    call_id = _call_id(call)
+                    journaled_calls.add(call_id)
+                    yield ToolCall(
+                        tool_call_id=call_id,
+                        name=_name(call),
+                        arguments=_loads(_arguments(call)),
+                    )
+                elif isinstance(event.item, ToolCallOutputItem):
+                    yield ToolResult(
+                        tool_call_id=_call_id(event.item.raw_item),
+                        result=event.item.output,
+                    )
+
+        if not result.interruptions:
+            return  # drive appends NO_MORE_ACTIONS
+
+        if len(result.interruptions) > 1:
+            # The contract suspends a turn on exactly one decision; parallel
+            # gated calls can't be mapped honestly yet (batched approvals are
+            # backlogged — schema/PLAN.md).
+            yield Error(
+                message=(
+                    f"{len(result.interruptions)} tool calls need approval in one "
+                    "turn; batched approvals are not supported yet"
+                ),
+                code="multiple_approvals",
+            )
+            return
+
+        interruption: ToolApprovalItem = result.interruptions[0]
+        call = interruption.raw_item  # typed `Any` at the ToolCallItem branch above
+        call_id, name = _call_id(call), _name(call)
+        if call_id not in journaled_calls:
+            # Gated calls are normally journaled via the streamed tool_called
+            # item; journal here too in case an SDK change stops emitting it —
+            # name + arguments must suffice for a resumed runner (contract).
+            yield ToolCall(tool_call_id=call_id, name=name, arguments=_loads(_arguments(call)))
+        yield ToolApprovalRequired(
+            tool_call_id=call_id,
+            name=name,
+            arguments=_loads(_arguments(call)),
+        )
+
+    # Framework marker — `sectr inspect` surfaces this in the manifest and
+    # the dev gateway reports it via /dev/status (DevStatus.framework).
+    handler.sectr_framework = "openai-agents"  # type: ignore[attr-defined]
+    return handler
+
+
+# ----------------------------------------------------------------------
+# Platform policy union
+# ----------------------------------------------------------------------
+
+
+def _apply_platform_policy(agent: OAgent) -> OAgent:
+    """Mark tools named by `SECTR_APPROVAL_POLICY` as approval-gated. The
+    framework then treats them exactly like code-marked `needs_approval`
+    tools — deployment config alone can gate a tool the user forgot to
+    mark. No-op when the policy is empty or already covers every name."""
+    policy = set(platform_approval_policy())
+    if not policy:
+        return agent
+    marked = {
+        tool.name: replace(tool, needs_approval=True)  # type: ignore[arg-type]
+        for tool in agent.tools
+        if tool.name in policy
+    }
+    if not marked:
+        return agent
+    tools = [marked.get(tool.name, tool) for tool in agent.tools]
+    return agent.clone(tools=tools)
+
+
+# ----------------------------------------------------------------------
+# Resume: transcript → input items
+# ----------------------------------------------------------------------
+
+
+from openai.types.responses import ResponseInputItemParam
+
+
+def _transcript_items(ctx: SessionContext) -> list[ResponseInputItemParam]:
+    """Convert the canonical transcript view (`ctx.messages`) into
+    openai-agents input items. Used by BOTH turn kinds — a user_message
+    turn continues the conversation (the transcript's last message is the
+    new user input); the approval-resume path appends the answered pending
+    call on top.
+
+    - user/assistant easy messages pass through as-is
+    - journaled TOOL_CALLs (chat-style `tool_calls`) become `function_call`
+      items with their original call_ids
+    - journaled TOOL_RESULTs become `function_call_output` items
+
+    The return type is the SDK's item union (Literal-tagged TypedDicts) so
+    mypy rejects unknown item type names / malformed shapes statically —
+    `function_call_result` (the wrong vocabulary, three live failures ago)
+    fails to typecheck here.
+    """
+    items: list[ResponseInputItemParam] = []
+    for msg in ctx.messages:
+        if msg["role"] == "user":
+            # `input` is opaque JSON per the invoke contract ("exactly as
+            # submitted"): the CLI sends a string, the console sends
+            # {"message": …}. Provider items need string content — a dict
+            # here hits the converter's part-iterator and explodes with
+            # `Unknown content: message` (it iterates the dict's KEYS).
+            # Stringify exactly the way the old current-input path did.
+            content = msg["content"]
+            items.append(
+                {"role": "user", "content": content if isinstance(content, str) else _dumps(content)}
+            )
+        elif msg["role"] == "tool":
+            items.append(
+                {
+                    "type": "function_call_output",
+                    "call_id": msg["tool_call_id"],
+                    "output": msg["content"],
+                }
+            )
+        else:  # assistant
+            if msg.get("content"):
+                items.append({"role": "assistant", "content": msg["content"]})
+            for call in msg.get("tool_calls") or []:
+                items.append(
+                    {
+                        "type": "function_call",
+                        "call_id": call["id"],
+                        "name": call["function"]["name"],
+                        "arguments": call["function"]["arguments"],
+                    }
+                )
+
+    # The invoke contract guarantees the transcript contains this
+    # invocation's INVOCATION_STARTED, so the fold above already emitted
+    # the current user message. A partial transcript (tests, harnesses)
+    # falls back to appending the current input — a turn never runs
+    # without its user message.
+    if ctx.reason.get("kind") == "user_message" and ctx.reason.get("input") is not None:
+        raw = ctx.reason["input"]
+        if not any(m["role"] == "user" and m["content"] == raw for m in ctx.messages):
+            items.append(
+                {"role": "user", "content": raw if isinstance(raw, str) else _dumps(raw)}
+            )
+    return items
+
+
+async def _resume_input(
+    ctx: SessionContext, agent: OAgent
+) -> tuple[list[ResponseInputItemParam], ToolResult | None]:
+    """Rebuild openai-agents input items from the canonical transcript view
+    (`ctx.messages`) via [`_transcript_items`], then answer the pending
+    approval call. The answered tool's result is also journaled (the
+    returned ToolResult event — the run itself will never re-emit it, the
+    answered call is already in the conversation).
+    """
+    items = _transcript_items(ctx)
+
+    pending = ctx.pending_tool_call
+    if pending is None:
+        return items, None
+
+    # The journaled TOOL_CALL already produced a function_call item above;
+    # only append it when absent (defensive for journals without one).
+    if not any(
+        item.get("type") == "function_call" and item.get("call_id") == pending["tool_call_id"]
+        for item in items
+    ):
+        items.append(
+            {
+                "type": "function_call",
+                "call_id": pending["tool_call_id"],
+                "name": pending["name"],
+                "arguments": _dumps(pending["arguments"]),
+            }
+        )
+
+    if ctx.decision["approved"]:
+        output = await _execute_pending(agent, pending)
+    else:
+        output = REJECTION_MESSAGE
+    items.append(
+        {"type": "function_call_output", "call_id": pending["tool_call_id"], "output": output}
+    )
+    return items, ToolResult(tool_call_id=pending["tool_call_id"], result=output)
+
+
+async def _execute_pending(agent: OAgent, pending: dict[str, Any]) -> Any:
+    """Execute the approved tool call directly (`FunctionTool.on_invoke_tool`).
+
+    The decision is in hand, so gating does not apply — the same rule as
+    raw-mode `ctx.execute` on an approval-resume turn. The tool object comes
+    from the agent's tool list by name (name + arguments are in the journal;
+    the original process is gone).
+    """
+    tool = next(
+        (t for t in agent.tools if isinstance(t, FunctionTool) and t.name == pending["name"]),
+        None,
+    )
+    if tool is None:
+        raise RuntimeError(f"approved tool {pending['name']!r} is not on the agent")
+    arguments = pending["arguments"]
+    if not isinstance(arguments, str):
+        arguments = _dumps(arguments)
+    tool_context = ToolContext(
+        context=None,
+        tool_name=pending["name"],
+        tool_call_id=pending["tool_call_id"],
+        tool_arguments=arguments,
+        agent=agent,
+        run_config=RunConfig(),
+    )
+    return await tool.on_invoke_tool(tool_context, arguments)
+
+
+# ----------------------------------------------------------------------
+# helpers
+# ----------------------------------------------------------------------
+
+
+def _call_id(raw: Any) -> str:
+    """Run-item raw payloads are pydantic objects or plain param dicts
+    depending on path — read defensively (the union is wide; only function
+    calls reach these attributes in practice)."""
+    if isinstance(raw, dict):
+        return raw.get("call_id") or ""
+    return getattr(raw, "call_id", "") or ""
+
+
+def _name(raw: Any) -> str:
+    if isinstance(raw, dict):
+        return raw.get("name") or ""
+    return getattr(raw, "name", "") or ""
+
+
+def _arguments(raw: Any) -> Any:
+    if isinstance(raw, dict):
+        return raw.get("arguments")
+    return getattr(raw, "arguments", None)
+
+
+def _loads(value: Any) -> Any:
+    """Model-emitted arguments arrive as a JSON string; parse so the journal
+    stores structured data (the schema wants `arguments: any`)."""
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return value
+    return value
+
+
+def _dumps(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, default=str)

sectr/app.py

@@ -0,0 +1,79 @@
+"""AgentApp — route registry and manifest source (see `sdk-python/PLAN.md`).
+
+Handlers all share one signature — `(SessionContext) -> AsyncIterator[
+RunnerEvent]` — whether hand-written (`@app.agent_route`) or produced by a
+framework adapter (`app.add_route("/chat", openai_agents(agent))`). The
+FastAPI adapter (`sectr.server`) mounts the registry as `POST /invocations`
+endpoints dispatched by `route`; `sectr.inspect` extracts the manifest.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import AsyncIterator, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .context import SessionContext
+from .events import RunnerEvent
+
+__all__ = ["AgentApp", "Route", "Handler"]
+
+Handler = Callable[[SessionContext], AsyncIterator[RunnerEvent]]
+
+_ROUTE_RE = re.compile(r"^/[A-Za-z0-9_\-/]*$")
+
+
+@dataclass
+class Route:
+    path: str
+    handler: Handler
+
+
+class AgentApp:
+    """Ordered route registry. One per user project; discovered by
+    `sectr inspect` via the `entry = "module:attribute"` in sectr.toml."""
+
+    def __init__(
+        self,
+        *,
+        name: str | None = None,
+        env: list[str] | None = None,
+    ) -> None:
+        self.name = name
+        self.routes: list[Route] = []
+        # Env var NAMES the sidecar must inject from the secret store at
+        # spawn. Values never pass through the manifest (write-only secrets).
+        self.env: tuple[str, ...] = tuple(env or ())
+
+    def add_route(self, path: str, handler: Handler) -> None:
+        """Register `handler` at `path` (e.g. "/customer-support"). Paths
+        must start with "/" and be unique — the platform routes sessions by
+        (app, path)."""
+        if not _ROUTE_RE.match(path):
+            raise ValueError(f"invalid route path {path!r} — must start with '/'")
+        if any(r.path == path for r in self.routes):
+            raise ValueError(f"route {path!r} already registered")
+        self.routes.append(Route(path=path, handler=handler))
+
+    def agent_route(self, path: str) -> Callable[[Handler], Handler]:
+        """Decorator flavor for hand-written handlers:
+
+            @app.agent_route("/chat")
+            async def chat(ctx: SessionContext): ...
+        """
+
+        def register(handler: Handler) -> Handler:
+            self.add_route(path, handler)
+            return handler
+
+        return register
+
+    def manifest(self) -> dict[str, Any]:
+        """The quick manifest (`sectr inspect` scan mode). The AUTHORITATIVE
+        manifest is extracted by importing this app under SECTR_MANIFEST=1 —
+        see `sectr.inspect`."""
+        return {
+            "name": self.name,
+            "routes": [{"path": r.path} for r in self.routes],
+        }