agent-workflow-sdk 0.1.0__tar.gz

agent_workflow_sdk-0.1.0/.env.example

@@ -0,0 +1,17 @@
+# Copy this file to .env and fill in your keys. .env is gitignored.
+# Used by the live test suite (pytest -m live) and the backend examples.
+
+# OpenAI (or any OpenAI-compatible endpoint)
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o-mini
+# Optional: override for a compatible endpoint (Groq, Together, vLLM, ...)
+# OPENAI_BASE_URL=https://api.openai.com/v1
+
+# Anthropic (Messages API)
+ANTHROPIC_API_KEY=sk-ant-...
+ANTHROPIC_MODEL=claude-sonnet-4-20250514
+# Only needed for an org-level (unscoped) key; workspace-scoped keys omit this.
+# ANTHROPIC_WORKSPACE_ID=wrkspc_...
+
+# Kiro agent id (a valid v3 session mode, e.g. vibe / spec / developer)
+KIRO_AGENT=vibe

agent_workflow_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install (dev extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[ollama,dev]'
+      - name: Ruff (lint + format check)
+        run: |
+          ruff check agentflow tests examples
+          ruff format --check agentflow tests examples
+      - name: mypy (type check)
+        run: mypy agentflow
+      - name: pip-audit (dependency CVE scan)
+        run: pip-audit || true   # advisory; do not fail the build on transient DB issues
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (with dev + ollama extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[ollama,dev]'
+
+      - name: Run offline test suite with coverage
+        # The default addopts (-m 'not live') skips backend smoke tests, so CI
+        # stays hermetic — no agent CLIs or network required.
+        run: pytest -q --cov --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: ignore
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build wheel + sdist
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Check the built wheel ships py.typed
+        run: |
+          python - <<'PY'
+          import glob, zipfile, sys
+          wheel = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          assert "agentflow/py.typed" in names, "py.typed missing from wheel"
+          print("py.typed present in", wheel)
+          PY

agent_workflow_sdk-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+telemetry/
+.DS_Store
+.runs/
+*.egg-info/
+dist/
+build/
+.env
+.coverage
+coverage.xml
+.pytest_cache/

agent_workflow_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+All notable changes to `agent-workflow-sdk` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project aims to follow [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-09-29
+
+First public release: an async-first, LangGraph-style SDK for agent workflows
+with pluggable agent and LLM backends.
+
+### Added
+
+- Agent backends require an explicit `permission` policy — there is no
+  auto-approve default. Construct with `permission=AllowAll()` (trusted local
+  sandbox only), `DenyAll()`, `Interactive()`, or `ToolAllowlist(...)`.
+- Control-plane health/monitoring surface: `RunQueue.stats()` returns a
+  `QueueStats` (queue depth by status plus `expired_leases`, the running runs
+  whose lease is past due and await re-claim), and `WorkerPool.health()` returns
+  a `PoolHealth` (`workers`/`alive`/`busy`/`idle`, with `healthy` True when every
+  worker loop is alive). `Worker.busy` reports whether a worker is mid-run. Plain
+  values for the caller to expose via `/healthz` / `/metrics` (no HTTP layer
+  imposed). Implemented on both `MemoryRunQueue` and `PostgresRunQueue`.
+- `PrometheusHooks` (in the `prometheus` extra): a `Hooks` listener that records
+  run/node/step counters, a node-duration histogram, and backend-event counts as
+  Prometheus metrics, for operators who scrape Prometheus rather than run an OTel
+  collector. Uses a private `CollectorRegistry` by default; `exposition()`
+  renders the text format for a `/metrics` endpoint (the HTTP layer is the
+  caller's).
+- `ToolAllowlist` permission policy for least-privilege tool scoping, with a
+  configurable fallback (`DenyAll` by default).
+- Capability matrix in the README documenting which backends route tool
+  requests through `PermissionPolicy` (Kiro does; the one-shot CLI agents use
+  their own sandbox/flags).
+- Sensitive-data controls for persistence: `RedactKeys` redactor (mask values
+  by key fragment). `JsonlTelemetry(redact=...)` and `FileCheckpointer(
+  redact=...)` apply it before writing. Both create files/dirs owner-only
+  (0o600/0o700) by default (`secure_permissions=`). Checkpoint redaction is
+  opt-in and documented as non-resumable (masked values are lost).
+- `SqliteCheckpointer`: transactional durable checkpointer with atomic
+  per-`(thread, step)` revisions (WAL mode, upsert-with-revision-bump), safe
+  for concurrent/multi-process runners. `FileCheckpointer` is now documented as
+  single-writer/single-process.
+- Provider resilience: typed `BackendTransportError` now carries `status` and
+  `headers`; a 429 that outlives retries raises `BackendRateLimitError` with
+  `retry_after`. HTTP LLM backends accept `max_concurrency` to bound in-flight
+  requests, and `compile(max_node_concurrency=...)` bounds how many nodes run
+  concurrently within a super-step (limits fan-out request pressure).
+- State isolation: `compile(isolate_state="fanout"|"always"|"never")` (default
+  `"fanout"`) deep-copies a node's input on concurrent super-steps so an
+  in-place mutation of a shared nested container cannot race a sibling. Linear
+  graphs pay no copy cost.
+- `tool_loop` now sets a terminal `status` on the final state: `"completed"`
+  (model answered tool-free) or `"tool_calls_unresolved"` (hit `max_turns` with
+  pending tool calls). Callers must check it rather than assume the last
+  message is a final answer.
+- Tooling: Ruff (lint + format), mypy (type check, `agentflow` clean), and
+  pip-audit added to the `dev` extra and CI. Codebase formatted and typed to
+  zero findings.
+- Release artifacts: `LICENSE` (Apache-2.0) and `NOTICE`, SPDX metadata,
+  shipped in the wheel; real
+  project URLs, `CONTRIBUTING.md` (with a release process), and `SECURITY.md`
+  (reporting + security-relevant design notes).
+- `DESIGN.md`: architecture and the invariants/contracts a change must
+  preserve (dependency direction, execution model, checkpointer/store/control-
+  plane contracts, security posture, out-of-scope). Referenced from
+  `CONTRIBUTING.md` and the README layout.
+- `OtelHooks` (in the `otel` extra): an OpenTelemetry `Hooks` exporter emitting
+  a span per run and per node, recording errors and backend events, with a
+  versioned attribute schema (`EVENT_SCHEMA_VERSION`).
+- Backends are async context managers (`async with backend: ...`) so
+  `start()`/`close()` can't be skipped and `close()` runs on error. Kiro's
+  stdin writes now apply backpressure via `drain()`.
+- Synchronous facade on `CompiledGraph`: `invoke_sync`, `resume_sync`, and
+  `stream_sync` wrap `asyncio.run` for non-async callers, and refuse to run
+  inside an existing event loop rather than deadlock.
+- Control plane for managing runs outside the process that created them
+  (`agentflow.controlplane`). A `RunQueue` holds run requests; a `GraphRegistry`
+  maps a graph name to a compiled-graph factory (graphs are code, not data);
+  and a `Worker`/`WorkerPool` claims requests and executes them, so runs
+  survive a process restart and scale across workers. Run lifecycle:
+  `queued -> running -> succeeded | interrupted | failed | cancelled`, with
+  interrupted runs resumed via `enqueue_resume(run_id, value)` and cooperative
+  `request_cancel` (stops at a super-step boundary). Ships `MemoryRunQueue`
+  (single process) and `PostgresRunQueue` (in the `postgres` extra; `claim` uses
+  `FOR UPDATE SKIP LOCKED` for safe concurrent workers, with a lease/heartbeat
+  so a crashed worker's run is re-claimed). Also adds `Checkpointer.list_threads`
+  (+ `ThreadInfo`) to enumerate runs across all backends. An HTTP layer over
+  the queue is planned but not included.
+- `Store` protocol for durable cross-thread memory (distinct from a
+  checkpointer, which persists one thread's execution state). Items are
+  addressed by a `namespace` tuple and a string `key`, hold any JSON value, and
+  support an optional per-item TTL. Methods: `get`, `put`, `delete`, `search`
+  (by namespace prefix) and `list_namespaces`. Ships `MemoryStore` (ephemeral)
+  and `PostgresStore` (in the `postgres` extra; `text[]` namespace column for
+  native prefix search, `jsonb` value, `timestamptz` expiry filtered from every
+  read). Lazily exported so the core stays dependency-free.
+- `PostgresCheckpointer` (in the `postgres` extra, via `asyncpg`): durable
+  checkpoints in a Postgres table keyed by `(thread, step)` with a `revision`
+  column and `jsonb` payload. Transactional upsert bumps the revision
+  atomically; conditional writes check the stored revision under `FOR UPDATE`.
+  Postgres is the recommended production-durability default (a committed row
+  survives a crash without extra tuning). Lazily exported so the core stays
+  dependency-free.
+- Optimistic concurrency for checkpointers: `Checkpoint` gains a `revision`
+  field (write count per `(thread, step)`, set by the store on read), and
+  `Checkpointer.put(cp, if_revision=...)` performs a compare-and-set — a
+  mismatch raises the new `CheckpointConflict`. `None` (default) stays an
+  unconditional upsert, so existing `put(cp)` calls are unchanged. This lets
+  two resumes racing the same super-step fail loudly instead of silently
+  clobbering each other. Implemented across the Memory, Sqlite, File, Redis and
+  Postgres backends.
+- Retention on the `Checkpointer` protocol: `delete_thread(thread)` removes a
+  whole thread, and `prune(thread, before_step=..., older_than=...)` deletes
+  old checkpoints and returns the count removed. Implemented across all
+  backends.
+- `RedisCheckpointer` (in the `redis` extra): durable checkpoints on a Redis
+  server for distributed / multi-process runners — JSON value per step plus a
+  per-thread sorted-set step index, atomic pipeline writes. Shared checkpoint
+  serialization extracted to `checkpoint/_serde.py`. Lazily exported so the
+  core stays redis-free. Note: Redis is not crash-durable without AOF/RDB
+  persistence configured; prefer `PostgresCheckpointer` when durability matters.
+
+- HTTP retry/backoff for the httpx LLM backends (`OllamaBackend`,
+  `OpenAIBackend`, `AnthropicBackend`) via a shared `RetryPolicy` and
+  `open_stream` helper. Retries the connect/initial-response phase only (never
+  mid-stream), honors `Retry-After`, and retries transient statuses
+  (408/409/425/429/500/502/503/504) and transport errors. Configurable per
+  backend through the `retry=` argument.
+- Persistent telemetry: `JsonlTelemetry` (durable JSON Lines per run) and
+  `MultiHooks` (compose several listeners); `Hooks.on_event` surfaces backend
+  events emitted via `ctx.emit` to telemetry.
+- Coverage: `pytest-cov` dev dependency and `[tool.coverage]` config; opt-in
+  via `pytest --cov`. CI reports coverage.
+- `CHANGELOG.md`.
+
+Core engine (the foundation the above builds on):
+
+- Graph engine: `Graph` builder (`add_node`, `add_edge`,
+  `add_conditional_edges`), `START`/`END` sentinels, compile-time validation
+  (reachability, unknown targets, dead ends), and a `CompiledGraph` runnable
+  with `invoke` / `stream` / `resume` / `get_state` / `history`.
+- Typed state with per-key reducers (`last`, `append`, `add`, `merge`,
+  `union`) over a `TypedDict` schema; deterministic update merge.
+- Super-step execution: concurrent fan-out, deterministic reducer folding,
+  all-or-nothing step semantics, and a `step_limit` guard.
+- Whole-run timeout (`invoke(..., timeout=...)` → `RunTimeout`) with the last
+  checkpoint preserved for resume.
+- Input validation at run start (undeclared/reserved channels rejected).
+- Subgraph-as-node: `add_node(compiled_graph)` and `add_subgraph(...,
+  input_map=, output_map=)` with isolated checkpoint sub-threads.
+- Checkpointing: `Checkpointer` protocol, `MemoryCheckpointer`, durable
+  `FileCheckpointer`; resume and time-travel.
+- Human-in-the-loop: `ctx.interrupt(...)` suspends a run; `resume(value=...)`
+  continues it. `Interactive` permission policy drives real interrupts.
+- Backends behind one event stream. Agent: `KiroBackend` (persistent ACP
+  session), `CodexBackend`, `ClaudeCodeBackend` (one-shot CLI per turn). LLM:
+  `OllamaBackend`, `OpenAIBackend` (any OpenAI-compatible endpoint),
+  `AnthropicBackend` (Messages API). Permission policies `AllowAll`/`DenyAll`/
+  `Interactive`.
+- Prebuilt patterns: `iterate_until_converged`, `tool_loop` (graph-native LLM
+  function-calling), and `with_retry` / `with_timeout` node wrappers.
+- Observability: `Hooks` lifecycle callbacks and `RunMetrics`.
+- Packaging: `py.typed`, dependency-free core with optional `[ollama]` extra,
+  GitHub Actions CI (offline suite + wheel build), and a `live` pytest marker
+  separating opt-in real-backend smoke tests from the hermetic default run.
+
+[0.1.0]: https://github.com/dankosorkin/agent-workflow-sdk/releases/tag/v0.1.0

agent_workflow_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Thanks for your interest in `agent-workflow-sdk`.
+
+## Development setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[ollama,dev]'
+```
+
+## Before you open a PR
+
+Run the same checks CI runs. All must pass:
+
+```bash
+ruff check agentflow tests examples
+ruff format --check agentflow tests examples
+mypy agentflow
+pytest -q                 # offline suite (hermetic)
+```
+
+- Format with `ruff format` before committing.
+- Add tests for new behavior. The suite deliberately tests invariants
+  (concurrency, atomicity, timeouts, interrupts), not just happy paths.
+- Keep the core (`agentflow/` minus `backends/`) dependency-free. New provider
+  libraries go behind an optional extra.
+- Update `CHANGELOG.md` under `[Unreleased]`.
+
+## Live backend tests
+
+Backend smoke tests are opt-in and skipped by default. To run them you need the
+relevant CLIs/servers and keys (see `.env.example`):
+
+```bash
+pytest -m live
+```
+
+Each live test self-skips when its backend is absent.
+
+## Architecture
+
+Read `DESIGN.md` first — it records the invariants and contracts your change
+must preserve. In short: the dependency direction is strict, state → engine →
+backends, and the engine never imports a backend. Please preserve that
+boundary.
+
+## Commit and PR conventions
+
+- One logical change per PR; keep diffs reviewable.
+- Reference the affected area in the commit subject (e.g. `runtime:`,
+  `backends/openai:`).
+- Do not commit secrets. `.env` is gitignored; use `.env.example` as the
+  template.
+
+## Release process
+
+1. Move `[Unreleased]` entries in `CHANGELOG.md` under a new version heading;
+   bump `version` in `pyproject.toml` (SemVer).
+2. Ensure CI is green (lint, types, tests, build).
+3. Build and verify the artifacts: `python -m build` — confirm the wheel ships
+   `agentflow/py.typed` and the LICENSE.
+4. Tag `vX.Y.Z` and publish.
+
+Pre-1.0 the public API may change between minor versions; breaking changes are
+called out in the changelog.
+

agent_workflow_sdk-0.1.0/DESIGN.md

@@ -0,0 +1,206 @@
+# Design
+
+This document records the architecture and the contracts that the rest of the
+codebase depends on. The README shows how to use the SDK; this explains what
+must stay true as it changes. If a change would break an invariant here, that
+is a design decision, not a refactor.
+
+The import root is `agentflow`. The distribution name is `agent-workflow-sdk`.
+
+## Dependency direction
+
+The one hard rule: `state` to `engine` to `backends`, and never the reverse.
+
+- The core (`agentflow/` minus `backends/`) is dependency-free — standard
+  library only. Importing `agentflow` must not pull in `httpx`, `redis`,
+  `asyncpg`, `prometheus_client`, or `opentelemetry`.
+- The engine (`graph`, `runtime`, `compiled`, `state`) never imports a backend.
+- A backend imports only `events` and `errors` from the core, never `runtime`
+  or `graph`.
+- Every provider library lives behind an optional extra and is imported lazily,
+  so the class is only resolved when you actually reference it.
+
+This boundary is what lets the core run with zero third-party packages and lets
+a backend be swapped without touching workflow code.
+
+## State and reducers
+
+State is a set of named channels declared as a `TypedDict` subclass of `State`.
+Each channel has a reducer — a pure function `(current, update) -> new` — that
+folds a node's partial update into the current value.
+
+- A field annotated `Annotated[type, reducer]` uses that reducer. A bare field
+  uses `last` (last-value-wins), the default.
+- Built-in reducers: `last`, `append`, `add`, `merge`, `union`. A reducer must
+  be pure and must treat a `None` current as its empty value (empty list, 0,
+  empty dict/set).
+- Reducers are what make concurrent updates in one super-step merge
+  deterministically instead of racing on last-writer-wins.
+- Channel names starting with `__` and the names in `RESERVED_NAMES`
+  (`__step`, `__next`) belong to the engine. A schema or a node update that
+  writes one is rejected.
+- Nodes may only write declared channels. Writing an undeclared channel raises
+  rather than sitting silently in state — a typo fails fast.
+
+`State` is pure data: no async, no I/O, no engine imports. It can be understood
+and tested in isolation.
+
+## Execution model
+
+A run advances in super-steps. Each super-step runs the current frontier of
+nodes, folds their updates into state, computes the next frontier from the
+edges, and checkpoints — then the next super-step begins.
+
+Invariants that must hold:
+
+- Super-steps are all-or-nothing. If any node in a step raises, the whole
+  step's updates are discarded and no checkpoint is written for that step. The
+  last good checkpoint is the previous step, so a resume never sees a partial
+  step.
+- Updates within a step are folded in a deterministic node order, so
+  non-commutative reducers (`append`, `last`) are well-defined. Commutative
+  reducers (`add`, `union`) do not depend on it.
+- `step_limit` bounds total super-steps to catch a graph that never reaches
+  `END`.
+- A whole-run timeout cancels the in-flight step and raises `RunTimeout`; the
+  last completed step's checkpoint is intact, so a checkpointed run resumes.
+
+### State isolation
+
+`compile(isolate_state=...)` controls defensive copying of a node's input:
+
+- `"fanout"` (default) deep-copies a node's input only when more than one node
+  runs in the same super-step, so an in-place mutation of a shared nested
+  container cannot race a sibling. Linear graphs pay no copy cost.
+- `"always"` copies on every node; `"never"` never copies (fastest, but the
+  caller promises nodes do not mutate shared input in place).
+
+## Backends
+
+Two kinds of backend share one event vocabulary, so a node consumes either the
+same way — a stream of events ending in `TurnEnd`.
+
+- Agent backends (`AgentBackend`) drive a session that runs its own tools and
+  asks permission. Lifecycle is `start()` / `prompt(text)` / `close()`, also
+  usable as an async context manager. `KiroBackend` holds a long-lived
+  JSON-RPC (ACP) session; `CodexBackend` and `ClaudeCodeBackend` run a fresh
+  subprocess per turn and carry a resumable session id between turns.
+- LLM backends (`LLMBackend`) are stateless: messages in, token stream out.
+  They never run tools themselves — a tool call is a request the graph
+  fulfils.
+
+Contracts a backend must honor:
+
+- Import only `events` and `errors` from the core.
+- Subprocess backends use argv lists (never `shell=True`), so a prompt can
+  never be interpreted as a shell command.
+- Transport failures raise typed errors (`BackendTransportError`, and
+  `BackendRateLimitError` for a 429 that outlives retries). Retries cover the
+  connect / initial-response phase only, never a partially received stream.
+
+## Permissions
+
+Authorization is explicit. Agent backends require a `PermissionPolicy` — there
+is no auto-approve default. `AllowAll` is for a trusted local sandbox only;
+other policies are `DenyAll`, `Interactive`, and `ToolAllowlist`. Only Kiro
+routes tool requests through the policy; the one-shot CLI agents rely on their
+own sandbox flags (see the capability matrix in the README).
+
+## Checkpointing and durability
+
+A `Checkpointer` persists the execution state of one thread so a run can
+resume, be inspected, or fork (time-travel). It is keyed by `(thread, step)`.
+
+Contract:
+
+- `put(cp, if_revision=...)` — `Checkpoint` carries a `revision` (the write
+  count for its `(thread, step)`, set on read). Passing `if_revision` makes the
+  write a compare-and-set; a mismatch raises `CheckpointConflict`. `None`
+  (default) is an unconditional upsert, so plain `put(cp)` is unchanged. This
+  gives optimistic concurrency for two resumes racing the same super-step.
+- `get` / `history` — read one step or all steps of a thread.
+- `delete_thread` / `prune(before_step=, older_than=)` — retention.
+- `list_threads` — enumerate threads with a `ThreadInfo` summary, the
+  foundation the control plane builds on.
+
+Implementations: `MemoryCheckpointer`, `FileCheckpointer` (single-writer,
+atomic per-step files), `SqliteCheckpointer` (transactional, WAL),
+`RedisCheckpointer`, `PostgresCheckpointer`. Serialization is shared in
+`checkpoint/_serde.py` so the persistent backends never drift.
+
+Durability note: Postgres is the recommended production default — a committed
+row survives a crash without extra tuning. Redis is not crash-durable unless
+AOF/RDB persistence is configured.
+
+## Human-in-the-loop
+
+A node calls `await ctx.interrupt(payload)` to suspend the run for a human. The
+runtime writes an interrupted checkpoint and stops. `resume(thread, value=...)`
+continues the run, and the same `interrupt` call returns `value`. Because the
+frontier is persisted, this works across process restarts.
+
+## Store
+
+A `Store` is the other axis from a checkpointer: durable key-value data shared
+across threads (profiles, facts, long-term memory), addressed by a `namespace`
+tuple and a string `key`, holding any JSON value, with an optional per-item
+TTL. Expired items never surface from `get` or `search`. Implementations:
+`MemoryStore` and `PostgresStore`.
+
+Keep this distinct from a checkpointer: a checkpointer is one thread's
+execution state; a store is cross-thread application data.
+
+## Control plane
+
+The control plane manages runs from outside the process that created them. It
+is a library layer, not a service — there is no HTTP server (that is planned as
+a thin adapter over these methods).
+
+- `GraphRegistry` maps a graph name to a compiled-graph factory. Graphs are
+  code and cannot be serialized, so a run request references a graph by name;
+  the enqueuer and its workers must share an equivalent registry and the same
+  checkpointer.
+- `RunQueue` holds run requests. Lifecycle: `queued` to `running` to
+  `succeeded` / `interrupted` / `failed` / `cancelled`; an interrupted run
+  returns to `queued` via `enqueue_resume`. Cancellation is cooperative —
+  `request_cancel` stops a running graph at a super-step boundary, leaving a
+  consistent checkpoint.
+- `Worker` / `WorkerPool` claim requests under a time-bounded lease and execute
+  them; a heartbeat renews the lease, and a crashed worker's run is re-claimed
+  once its lease expires. `PostgresRunQueue` claims via
+  `FOR UPDATE SKIP LOCKED`, so each run goes to exactly one worker under
+  concurrency.
+- Monitoring: `RunQueue.stats()` and `WorkerPool.health()` return plain values
+  a caller can expose through its own `/healthz` and `/metrics`.
+
+## Observability
+
+`Hooks` are lifecycle callbacks attached at `compile(hooks=...)`. They are
+awaited but must never raise — an exception in a hook is swallowed so
+instrumentation cannot break a run. `RunMetrics`, `JsonlTelemetry`, `OtelHooks`
+(otel extra), and `PrometheusHooks` (prometheus extra) are all `Hooks`
+listeners; compose several with `MultiHooks`.
+
+## Security posture
+
+- Persistence is plaintext by default. Checkpoints and JSONL telemetry contain
+  prompts, model output, and tool arguments. `RedactKeys` (via `redact=`) masks
+  sensitive keys; files and directories are created owner-only (0o600/0o700)
+  where the filesystem supports it. Redacted checkpoints are not resumable to
+  the exact original state — masked values are lost.
+- Postgres backends validate the table name with `str.isidentifier()` before
+  interpolating it into SQL.
+- Treat model and tool output and fetched content as untrusted. The SDK does
+  not execute model output; nodes decide what to run.
+
+See `SECURITY.md` for the reporting process and the operator-facing summary.
+
+## What is intentionally out of scope
+
+- An HTTP/gRPC API over the control plane, and the auth/multi-tenancy that a
+  service layer implies. These are properties of a service, not this SDK, and
+  are deferred to a future `server` layer that adapts the existing queue
+  methods.
+- Rate limiting and per-tenant quotas. `max_concurrency` /
+  `max_node_concurrency` bound pressure within one process; per-tenant
+  isolation is the caller's responsibility until the service layer exists.