docs: move examples to docs/recipes/ with updated links (closes #28 partially)

nficano · nficano · commit 627282741359 · 2026-05-21T23:22:35.000-04:00
diff --git a/docs/recipes/ack-backpressure.md b/docs/recipes/ack-backpressure.md
@@ -0,0 +1,17 @@
+# Ack back-pressure
+
+The runtime emits events faster than the client acknowledges them;
+once the unacked window exceeds the configured limit, the runtime
+pauses production and emits a `status` event with
+`phase: "backpressure"`, then resumes once acks catch up.
+
+Source: [`../../examples/ack_backpressure/`](../../examples/ack_backpressure/).
+
+```sh
+uv run python -m examples.ack_backpressure.runtime &
+uv run python -m examples.ack_backpressure.client
+```
+
+## See also
+
+- Guide: [Job events](../guides/job-events.md) — event acknowledgement.
diff --git a/docs/recipes/agent-versions.md b/docs/recipes/agent-versions.md
@@ -0,0 +1,18 @@
+# Agent versions
+
+The runtime registers two versions of `weekly-report`; the client
+submits one job against `weekly-report@2026.05.0` and a second
+against bare `weekly-report` (resolved to the default version), and
+the example asserts both jobs ran the expected handler.
+
+Source: [`../../examples/agent_versions/`](../../examples/agent_versions/).
+
+```sh
+uv run python -m examples.agent_versions.runtime &
+uv run python -m examples.agent_versions.client
+```
+
+## See also
+
+- Guide: [Sessions](../guides/sessions.md) — agent versions (§6.2).
+- Guide: [Jobs](../guides/jobs.md) — `agent_version` submit option.
diff --git a/docs/recipes/cancel.md b/docs/recipes/cancel.md
@@ -0,0 +1,18 @@
+# Cancel
+
+The client sends `job.cancel`; the runtime cancels the agent task and
+emits a terminal `job.error` with code `CANCELLED`. The agent body
+receives `asyncio.CancelledError` and may run cleanup before the
+terminal envelope ships.
+
+Source: [`../../examples/cancel/`](../../examples/cancel/).
+
+```sh
+uv run python -m examples.cancel.runtime &
+uv run python -m examples.cancel.client
+```
+
+## See also
+
+- Guide: [Jobs](../guides/jobs.md) — Cancellation.
+- Spec: [ARCP v1.1 §7.3](https://arcp.dev/spec/v1.1#section-7.3).
diff --git a/docs/recipes/cost-budget.md b/docs/recipes/cost-budget.md
@@ -0,0 +1,16 @@
+# Cost budget
+
+A client submits a job with `max_cost_usd: 0.05`; the agent
+reports successive cost increments until the budget reaches zero,
+and the next `ctx.report_cost(...)` call fails with `LeaseExceededError`.
+
+Source: [`../../examples/cost_budget/`](../../examples/cost_budget/).
+
+```sh
+uv run python -m examples.cost_budget.runtime &
+uv run python -m examples.cost_budget.client
+```
+
+## See also
+
+- Guide: [Leases](../guides/leases.md) — cost budgets.
diff --git a/docs/recipes/custom-auth.md b/docs/recipes/custom-auth.md
@@ -0,0 +1,18 @@
+# Custom auth
+
+A runtime mounts a custom `BearerVerifier` that consults an external
+identity store, replacing the `StaticBearerVerifier` used in the
+quickstart. Demonstrates the seam between transport-level
+authentication and the rest of the protocol.
+
+Source: [`../../examples/custom_auth/`](../../examples/custom_auth/).
+
+```sh
+uv run python -m examples.custom_auth.runtime &
+uv run python -m examples.custom_auth.client
+```
+
+## See also
+
+- Guide: [Authentication](../guides/auth.md).
+- Spec: [ARCP v1.1 §6.1](https://arcp.dev/spec/v1.1#section-6.1).
diff --git a/docs/recipes/delegate.md b/docs/recipes/delegate.md
@@ -0,0 +1,19 @@
+# Delegate
+
+A parent agent submits a child job to a peer runtime through
+`JobContext.delegate(...)`, propagating `parent_job_id` and
+`trace_id`, and requesting a strict-subset lease. Demonstrates how
+delegation composes the recursive case of jobs / events / leases.
+
+Source: [`../../examples/delegate/`](../../examples/delegate/).
+
+```sh
+uv run python -m examples.delegate.runtime &
+uv run python -m examples.delegate.client
+```
+
+## See also
+
+- Guide: [Delegation](../guides/delegation.md).
+- Guide: [Architecture](../architecture.md) — Delegation (§10).
+- Spec: [ARCP v1.1 §10](https://arcp.dev/spec/v1.1#section-10).
diff --git a/docs/recipes/heartbeat.md b/docs/recipes/heartbeat.md
@@ -0,0 +1,16 @@
+# Heartbeat
+
+The runtime emits `session.ping` at a short interval; the client
+replies with `session.pong`. The example then simulates a stalled
+client to surface `HEARTBEAT_LOST` and a `session.error` close.
+
+Source: [`../../examples/heartbeat/`](../../examples/heartbeat/).
+
+```sh
+uv run python -m examples.heartbeat.runtime &
+uv run python -m examples.heartbeat.client
+```
+
+## See also
+
+- Guide: [Job events](../guides/job-events.md) — `job.heartbeat`.
diff --git a/docs/recipes/host-aiohttp.md b/docs/recipes/host-aiohttp.md
@@ -0,0 +1,17 @@
+# Host: aiohttp
+
+Attaches `arcp.middleware.aiohttp.arcp_aiohttp_handler(runtime)` to an
+`aiohttp.web.Application` route, serving ARCP from an aiohttp host
+process.
+
+Source: [`../../examples/host_aiohttp/`](../../examples/host_aiohttp/).
+
+```sh
+uv run python -m examples.host_aiohttp.server &
+uv run python -m examples.host_aiohttp.client
+```
+
+## See also
+
+- Guide: [Architecture](../architecture.md) — aiohttp middleware.
+- Guide: [Transports](../transports.md).
diff --git a/docs/recipes/host-asgi.md b/docs/recipes/host-asgi.md
@@ -0,0 +1,17 @@
+# Host: ASGI
+
+Mounts `arcp.middleware.asgi.arcp_asgi_app(runtime, allowed_hosts=[...])`
+at `/arcp` inside a Starlette application, serving ARCP alongside
+ordinary HTTP routes via uvicorn.
+
+Source: [`../../examples/host_asgi/`](../../examples/host_asgi/).
+
+```sh
+uv run python -m examples.host_asgi.server &
+uv run python -m examples.host_asgi.client
+```
+
+## See also
+
+- Guide: [Architecture](../architecture.md) — ASGI middleware.
+- Guide: [Transports](../transports.md).
diff --git a/docs/recipes/host-tracing.md b/docs/recipes/host-tracing.md
@@ -0,0 +1,19 @@
+# Host: OpenTelemetry
+
+Wraps the runtime's accept loop with
+`arcp.middleware.otel.with_tracing(...)` to propagate W3C trace
+context across the wire and emit v1.1 span attributes per spec §11.
+The example uses the OTel console exporter so traces are visible
+without an external collector.
+
+Source: [`../../examples/host_tracing/`](../../examples/host_tracing/).
+
+```sh
+uv run python -m examples.host_tracing.runtime &
+uv run python -m examples.host_tracing.client
+```
+
+## See also
+
+- Guide: [Observability](../guides/observability.md).
+- Spec: [ARCP v1.1 §11](https://arcp.dev/spec/v1.1#section-11).
diff --git a/docs/recipes/idempotent-retry.md b/docs/recipes/idempotent-retry.md
@@ -0,0 +1,18 @@
+# Idempotent retry
+
+The client submits the same `(principal, agent, input,
+idempotency_key)` twice and receives the same `job_id` both times.
+Demonstrates the spec §7.4 deduplication contract on the in-memory
+idempotency store.
+
+Source: [`../../examples/idempotent_retry/`](../../examples/idempotent_retry/).
+
+```sh
+uv run python -m examples.idempotent_retry.runtime &
+uv run python -m examples.idempotent_retry.client
+```
+
+## See also
+
+- Guide: [Jobs](../guides/jobs.md) — Idempotency.
+- Spec: [ARCP v1.1 §7.4](https://arcp.dev/spec/v1.1#section-7.4).
diff --git a/docs/recipes/lease-expires-at.md b/docs/recipes/lease-expires-at.md
@@ -0,0 +1,16 @@
+# Lease expires_at
+
+A client submits a job with a 2-second `expires_at`; the agent
+sleeps past the deadline and the next `ctx.authorize(...)` raises
+`LeaseExpiredError`, terminating the job with the same code.
+
+Source: [`../../examples/lease_expires_at/`](../../examples/lease_expires_at/).
+
+```sh
+uv run python -m examples.lease_expires_at.runtime &
+uv run python -m examples.lease_expires_at.client
+```
+
+## See also
+
+- Guide: [Leases](../guides/leases.md) — absolute expiry timestamp.
diff --git a/docs/recipes/lease-violation.md b/docs/recipes/lease-violation.md
@@ -0,0 +1,19 @@
+# Lease violation
+
+An agent calls `ctx.authorize("net.fetch", "https://evil.example/")`
+against a lease that does not grant that target; the runtime
+emits `job.error` with code `LEASE_SUBSET_VIOLATION`. Demonstrates
+the lease validator path and the failure surface in `arcp._errors`.
+
+Source: [`../../examples/lease_violation/`](../../examples/lease_violation/).
+
+```sh
+uv run python -m examples.lease_violation.runtime &
+uv run python -m examples.lease_violation.client
+```
+
+## See also
+
+- Guide: [Leases](../guides/leases.md).
+- Guide: [Errors](../guides/errors.md).
+- Spec: [ARCP v1.1 §9.1](https://arcp.dev/spec/v1.1#section-9.1).
diff --git a/docs/recipes/list-jobs.md b/docs/recipes/list-jobs.md
@@ -0,0 +1,16 @@
+# List jobs
+
+The client submits three jobs against the same agent, then issues
+`session.list_jobs` with status and agent filters plus a small
+`limit` to demonstrate cursor paging.
+
+Source: [`../../examples/list_jobs/`](../../examples/list_jobs/).
+
+```sh
+uv run python -m examples.list_jobs.runtime &
+uv run python -m examples.list_jobs.client
+```
+
+## See also
+
+- Guide: [Jobs](../guides/jobs.md) — List jobs.
diff --git a/docs/recipes/progress.md b/docs/recipes/progress.md
@@ -0,0 +1,17 @@
+# Progress
+
+An agent scans a list of files and emits `ctx.progress(done=i,
+total=n)` for each item. The client renders the
+running tally before consuming the terminal `job.result`.
+
+Source: [`../../examples/progress/`](../../examples/progress/).
+
+```sh
+uv run python -m examples.progress.runtime &
+uv run python -m examples.progress.client
+```
+
+## See also
+
+- Guide: [Job events](../guides/job-events.md) — `job.progress`.
+- Guide: [Jobs](../guides/jobs.md) — Job context.
diff --git a/docs/recipes/provisioned-credentials.md b/docs/recipes/provisioned-credentials.md
@@ -0,0 +1,17 @@
+# Provisioned credentials
+
+A runtime installs an `InMemoryCredentialProvisioner`, advertises
+`model.use` and `provisioned_credentials`, and accepts a job whose
+lease scopes the generated credential to `tier-fast/*` and `USD:1.00`.
+
+Source: [`../../examples/provisioned_credentials/`](../../examples/provisioned_credentials/).
+
+```sh
+uv run python -m examples.provisioned_credentials.server &
+uv run python -m examples.provisioned_credentials.client
+```
+
+## See also
+
+- Guide: [Authentication](../guides/auth.md).
+- Guide: [Leases](../guides/leases.md).
diff --git a/docs/recipes/result-chunk.md b/docs/recipes/result-chunk.md
@@ -0,0 +1,17 @@
+# Result chunk
+
+An agent renders a 200 KB payload as a stream of `result_chunk`
+events; the client collects them via `handle.collect_chunks()` and
+asserts the reassembled bytes match the source.
+
+Source: [`../../examples/result_chunk/`](../../examples/result_chunk/).
+
+```sh
+uv run python -m examples.result_chunk.runtime &
+uv run python -m examples.result_chunk.client
+```
+
+## See also
+
+- Guide: [Job events](../guides/job-events.md) — `job.result_chunk`.
+- Guide: [Jobs](../guides/jobs.md) — Streaming results.
diff --git a/docs/recipes/resume.md b/docs/recipes/resume.md
@@ -0,0 +1,18 @@
+# Stream resume
+
+The client connects, submits a job, drops the transport mid-stream,
+opens a new transport, and resumes the session with
+`resume_token` and `resume_from_seq`. The runtime replays missed events
+since `last_event_seq` from its event log.
+
+Source: [`../../examples/resume/`](../../examples/resume/).
+
+```sh
+uv run python -m examples.resume.runtime &
+uv run python -m examples.resume.client
+```
+
+## See also
+
+- Guide: [Stream resume](../guides/resume.md).
+- Spec: [ARCP v1.1 §6.3](https://arcp.dev/spec/v1.1#section-6.3).
diff --git a/docs/recipes/stdio.md b/docs/recipes/stdio.md
@@ -0,0 +1,19 @@
+# Stdio transport
+
+A parent process spawns a child runtime over `StdioTransport` and
+submits one job. Demonstrates the child-process subagent topology
+in spec §4.2 without any sockets.
+
+Source: [`../../examples/stdio/`](../../examples/stdio/).
+
+```sh
+uv run python -m examples.stdio.parent
+```
+
+The parent script forks `examples.stdio.child` and connects via
+pipes.
+
+## See also
+
+- Guide: [Transports](../transports.md) — stdio transport.
+- Spec: [ARCP v1.1 §4.2](https://arcp.dev/spec/v1.1#section-4.2).
diff --git a/docs/recipes/submit-and-stream.md b/docs/recipes/submit-and-stream.md
@@ -0,0 +1,23 @@
+# Submit and stream
+
+The hello-world example: a client submits one job and streams its
+events until the terminal `job.result`. Demonstrates the connect /
+submit / iterate / close lifecycle without leases, idempotency, or
+v1.1 features.
+
+Source: [`../../examples/submit_and_stream/`](../../examples/submit_and_stream/).
+
+Run the two-process WebSocket variant:
+
+```sh
+uv run python -m examples.submit_and_stream.runtime &
+uv run python -m examples.submit_and_stream.client
+```
+
+Or run the single-process paired-transport variant from
+[Getting started](../getting-started.md).
+
+## See also
+
+- Guide: [Architecture](../architecture.md).
+- Guide: [Jobs](../guides/jobs.md).
diff --git a/docs/recipes/subscribe.md b/docs/recipes/subscribe.md
@@ -0,0 +1,17 @@
+# Subscribe
+
+A submitter client starts a long-running job; a separate operator
+client connects, calls `client.subscribe(job_id, history=True)`, and
+replays the prior events before continuing live.
+
+Source: [`../../examples/subscribe/`](../../examples/subscribe/).
+
+```sh
+uv run python -m examples.subscribe.runtime &
+uv run python -m examples.subscribe.submitter &
+uv run python -m examples.subscribe.observer
+```
+
+## See also
+
+- Guide: [Job events](../guides/job-events.md) — Subscribe without a job handle.
diff --git a/docs/recipes/vendor-extensions.md b/docs/recipes/vendor-extensions.md
