agent-workflow-sdk 0.3.0__tar.gz → 0.5.0__tar.gz

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/.github/workflows/docs.yml

@@ -1,12 +1,18 @@
 name: Docs
 
-# Build the mkdocs site and deploy it to GitHub Pages on a version tag, or on
-# demand from the Actions tab. Enable Pages once (Settings -> Pages -> Source:
-# GitHub Actions) for the deploy step to publish.
+# Build the mkdocs site and deploy it to GitHub Pages when docs change on main,
+# or on demand from the Actions tab. Triggering on main (not a tag) matches the
+# github-pages environment's branch protection, which allows the default branch
+# — a tag push is rejected by that rule. Enable Pages once
+# (Settings -> Pages -> Source: GitHub Actions) for the deploy step to publish.
 on:
   push:
-    tags:
-      - "v*"
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "agentflow/**"
+      - ".github/workflows/docs.yml"
   workflow_dispatch:
 
 # Allow one concurrent deploy; a newer run supersedes an in-flight one.

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.5.0] - 2026-10-04
+
+### Added
+
+- `by_key(policy)` reducer (`agentflow.state`, re-exported from `agentflow`):
+  a reducer for a dict channel whose fields each fold with their own reducer.
+  Where `merge` applies one last-wins policy to a whole dict, `by_key` lets a
+  single structured channel hold fields that accumulate differently — e.g. one
+  `search` channel where `intents` / `candidates` / `verified` grow via
+  `append` while `events` / `incumbent` are replaced via `last`. This is the
+  core primitive a dual-state search/optimization layer (single planner,
+  concurrent workers, a deterministic promotion boundary) builds on; the
+  fan-out, state isolation, checkpoints, Store, and quality gates it also needs
+  already exist. See the dual-state search recipe and
+  `examples/dual_state_search.py`.
+
+### Notes
+
+- `by_key` folding is one level of structure, not a recursive deep-merge: each
+  field's value is combined whole by its reducer (so `last` on a field replaces
+  the whole object, it does not patch one of its keys). Writing a field absent
+  from the policy raises `KeyError`, mirroring how the engine rejects writes to
+  undeclared top-level channels. Use it for distinct fields that accumulate
+  differently, not for concurrent partial patches of the same nested object.
+
+## [0.4.0] - 2026-10-03
+
+### Added
+
+- Optional HTTP control-plane server (`server` extra): `agentflow.server.
+  create_app(queue)` returns a FastAPI ASGI app that maps 1:1 onto a
+  `RunQueue`, so runs can be enqueued and observed over the network. Routes:
+  `POST /runs`, `GET /runs/{id}`, `GET /runs`, `POST /runs/{id}/resume`,
+  `POST /runs/{id}/cancel`, `GET /stats`, `GET /healthz`. Request/response
+  bodies are Pydantic models, so FastAPI serves interactive OpenAPI docs at
+  `/docs`. `pool_health=` wires a `WorkerPool`'s health into `/healthz`. The
+  app adds no behavior of its own — each route forwards to one queue method.
+  See `examples/serve_control_plane.py` and the control-plane docs.
+- `server` install extra: `pip install 'agent-workflow-sdk[server]'`
+  (`fastapi>=0.110`). The core remains dependency-free; serve the returned
+  ASGI app with any ASGI server (e.g. `uvicorn`), installed separately.
+
+### Changed
+
+- The worker protocol (`claim` / `heartbeat` / `complete`) is deliberately not
+  exposed over HTTP; workers talk to the queue directly. The HTTP layer ships
+  no authentication, authorization, rate limiting, or multi-tenancy — those
+  stay out of scope and are the caller's responsibility (trust boundary /
+  reverse proxy). `DESIGN.md` updated accordingly.
+
 ## [0.3.0] - 2026-10-02
 
 ### Added

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/DESIGN.md

@@ -152,9 +152,11 @@ 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).
+The control plane manages runs from outside the process that created them. The
+core is a library layer, not a service. An optional HTTP layer — the `server`
+extra, `agentflow.server.create_app` — is a thin FastAPI adapter mapping 1:1
+over the queue methods below; it adds no behavior of its own, and auth and
+multi-tenancy remain out of scope (see below).
 
 - `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;
@@ -172,6 +174,13 @@ a thin adapter over these methods).
   concurrency.
 - Monitoring: `RunQueue.stats()` and `WorkerPool.health()` return plain values
   a caller can expose through its own `/healthz` and `/metrics`.
+- HTTP (optional, `server` extra): `agentflow.server.create_app(queue)` returns
+  a FastAPI ASGI app exposing the enqueue-and-observe plane — `POST /runs`,
+  `GET /runs/{id}`, `GET /runs`, `POST /runs/{id}/resume`,
+  `POST /runs/{id}/cancel`, `GET /stats`, `GET /healthz`. The worker protocol
+  (`claim` / `heartbeat` / `complete`) is deliberately not exposed; workers
+  talk to the queue directly. Each route forwards to one queue method, so the
+  HTTP layer carries no state of its own.
 
 ## Observability
 
@@ -197,10 +206,11 @@ 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.
+- Authentication, authorization, and multi-tenancy over the HTTP layer. The
+  optional `server` extra adapts the queue to HTTP, but it ships no auth and no
+  per-tenant isolation — those are properties of a service, not this SDK. Run
+  it inside your own trust boundary, or behind a reverse proxy that supplies
+  them. A gRPC API is not provided.
 - 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.

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-workflow-sdk
-Version: 0.3.0
+Version: 0.5.0
 Summary: Async-first SDK for orchestrating local coding-agent CLIs (Claude Code, Codex, Kiro) and LLMs as durable, graph-based workflows.
 Project-URL: Homepage, https://github.com/dankosorkin/agent-workflow-sdk
 Project-URL: Repository, https://github.com/dankosorkin/agent-workflow-sdk
@@ -20,6 +20,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Provides-Extra: dev
 Requires-Dist: fakeredis>=2.20; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
 Requires-Dist: prometheus-client>=0.20; extra == 'dev'
@@ -41,6 +43,8 @@ Provides-Extra: prometheus
 Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
 Provides-Extra: redis
 Requires-Dist: redis>=5; extra == 'redis'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
 Description-Content-Type: text/markdown
 
 # agent-workflow-sdk
@@ -184,7 +188,8 @@ shows the iterate-until-converged loop.
 State is a `TypedDict` subclass of `State`. Each field is a channel; annotate
 it with a reducer that folds each node's update into the current value. A
 field without a reducer uses `last` (last-value-wins). Built-in reducers:
-`last`, `append`, `add`, `merge`, `union`. A node returns a partial update; it
+`last`, `append`, `add`, `merge`, `union`, and `by_key` (a dict channel whose
+fields each fold with their own reducer). A node returns a partial update; it
 never mutates the state it was given.
 
 ### Nodes and edges

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/README.md

@@ -139,7 +139,8 @@ shows the iterate-until-converged loop.
 State is a `TypedDict` subclass of `State`. Each field is a channel; annotate
 it with a reducer that folds each node's update into the current value. A
 field without a reducer uses `last` (last-value-wins). Built-in reducers:
-`last`, `append`, `add`, `merge`, `union`. A node returns a partial update; it
+`last`, `append`, `add`, `merge`, `union`, and `by_key` (a dict channel whose
+fields each fold with their own reducer). A node returns a partial update; it
 never mutates the state it was given.
 
 ### Nodes and edges

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/agentflow/__init__.py

@@ -90,6 +90,7 @@ from agentflow.state import (
     State,
     add,
     append,
+    by_key,
     last,
     merge,
     union,
@@ -97,7 +98,7 @@ from agentflow.state import (
 from agentflow.store import Item, MemoryStore, Store
 from agentflow.telemetry import JsonlTelemetry, MultiHooks
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "__version__",
@@ -109,6 +110,7 @@ __all__ = [
     "append",
     "add",
     "merge",
+    "by_key",
     "union",
     # graph
     "Graph",

agent_workflow_sdk-0.5.0/agentflow/server/__init__.py

@@ -0,0 +1,46 @@
+# Copyright 2026 Daniel Sorkin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""An HTTP adapter over the control-plane run queue (optional ``server`` extra).
+
+This is the thin service layer DESIGN.md defers to: a FastAPI app that maps 1:1
+onto :class:`~agentflow.controlplane.queue.RunQueue` methods, so a run can be
+enqueued, inspected, resumed, or cancelled over HTTP from anywhere. It adds no
+behavior the queue does not already have.
+
+    from agentflow import PostgresRunQueue
+    from agentflow.server import create_app
+
+    app = create_app(PostgresRunQueue(dsn))   # an ASGI app; serve with uvicorn
+
+What it exposes is the *enqueue and observe* plane: ``POST /runs``, ``GET
+/runs/{id}``, ``GET /runs``, ``POST /runs/{id}/resume``, ``POST
+/runs/{id}/cancel``, ``GET /stats``, ``GET /healthz``. The worker protocol
+(``claim`` / ``heartbeat`` / ``complete``) is deliberately *not* exposed —
+those mutate run state and belong to workers, which talk to the queue directly
+(in-process or via the same Postgres queue), not over this API.
+
+Scope, stated plainly: there is no authentication, authorization, rate
+limiting, or multi-tenancy here — DESIGN.md defers those as properties of a
+service. Run this inside your own trust boundary, or behind a reverse proxy
+that supplies them. It is an adapter, not a hardened public endpoint.
+
+Requires the ``server`` extra: ``pip install 'agent-workflow-sdk[server]'``.
+Serve the returned ASGI app with any ASGI server (e.g. ``uvicorn``), which you
+install separately.
+"""
+
+from agentflow.server.app import create_app
+
+__all__ = ["create_app"]

agent_workflow_sdk-0.5.0/agentflow/server/app.py

@@ -0,0 +1,205 @@
+# Copyright 2026 Daniel Sorkin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""FastAPI app factory mapping HTTP routes onto a ``RunQueue``.
+
+Each route is a direct adapter over one queue method; see the package docstring
+for the exposed surface and the explicit non-goals (no auth, no worker
+protocol). Response/request shapes are Pydantic models so the generated OpenAPI
+docs (``/docs``) are accurate.
+
+Note: this module intentionally does NOT use ``from __future__ import
+annotations``. FastAPI resolves endpoint annotations with ``get_type_hints``,
+which cannot re-evaluate a stringized ``Depends(get_queue)`` that references a
+function-local dependency — real annotation objects are required.
+"""
+
+from collections.abc import Callable
+from typing import Annotated, Any
+
+try:
+    from fastapi import Depends, FastAPI, HTTPException, Query
+    from pydantic import BaseModel, Field
+except ModuleNotFoundError as exc:  # pragma: no cover - import-time guard
+    raise ModuleNotFoundError(
+        "agentflow.server requires FastAPI. Install the extra: "
+        "pip install 'agent-workflow-sdk[server]'"
+    ) from exc
+
+from agentflow.controlplane.queue import RunQueue
+from agentflow.controlplane.records import QueueStats, RunRecord
+from agentflow.errors import RunNotFound
+
+__all__ = ["create_app"]
+
+
+# ---------------------------------------------------------------------------
+# Wire models (what crosses the HTTP boundary)
+# ---------------------------------------------------------------------------
+
+
+class EnqueueRequest(BaseModel):
+    """Body for ``POST /runs`` — ask to run a registered graph."""
+
+    graph: str = Field(..., description="Name of a graph registered on the worker side.")
+    input: dict[str, Any] = Field(default_factory=dict, description="Initial state for the run.")
+    thread: str | None = Field(None, description="Checkpoint thread; defaults to the run id.")
+
+
+class ResumeRequest(BaseModel):
+    """Body for ``POST /runs/{run_id}/resume`` — answer an interrupted run."""
+
+    value: Any = Field(None, description="Value fed to the interrupted node on resume.")
+
+
+class RunResponse(BaseModel):
+    """One run's queue record."""
+
+    run_id: str
+    graph: str
+    thread: str
+    status: str
+    input: dict[str, Any] = Field(default_factory=dict)
+    resume_value: Any = None
+    error: str | None = None
+    attempt: int = 0
+    created_at: str = ""
+    updated_at: str = ""
+    lease_until: str | None = None
+    wake_at: str | None = None
+    cancel_requested: bool = False
+
+    @classmethod
+    def of(cls, rec: RunRecord) -> "RunResponse":
+        return cls(
+            run_id=rec.run_id,
+            graph=rec.graph,
+            thread=rec.thread,
+            status=rec.status,
+            input=dict(rec.input),
+            resume_value=rec.resume_value,
+            error=rec.error,
+            attempt=rec.attempt,
+            created_at=rec.created_at,
+            updated_at=rec.updated_at,
+            lease_until=rec.lease_until,
+            wake_at=rec.wake_at,
+            cancel_requested=rec.cancel_requested,
+        )
+
+
+class CancelResponse(BaseModel):
+    cancelled: bool = Field(
+        ..., description="True if the run existed and was not already terminal."
+    )
+
+
+class StatsResponse(BaseModel):
+    total: int = 0
+    by_status: dict[str, int] = Field(default_factory=dict)
+    expired_leases: int = 0
+
+    @classmethod
+    def of(cls, s: QueueStats) -> "StatsResponse":
+        return cls(total=s.total, by_status=dict(s.by_status), expired_leases=s.expired_leases)
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+
+def create_app(
+    queue: RunQueue,
+    *,
+    pool_health: Callable[[], Any] | None = None,
+    title: str = "AgentFlow control plane",
+) -> FastAPI:
+    """Build a FastAPI app over ``queue``.
+
+    ``queue`` is any :class:`~agentflow.controlplane.queue.RunQueue` (Memory for
+    a single process, Postgres for a shared/durable one). ``pool_health``, if
+    given, is a zero-arg callable returning a
+    :class:`~agentflow.controlplane.records.PoolHealth` (typically
+    ``pool.health``); ``GET /healthz`` reports it when present. The app adds no
+    behavior of its own — every route forwards to a queue method.
+    """
+    app = FastAPI(title=title, version="1")
+
+    def get_queue() -> RunQueue:
+        return queue
+
+    # FastAPI dependency injected via the Annotated form (the modern idiom:
+    # keeps Depends() out of the parameter default, so no ruff B008). Inlined in
+    # each signature rather than aliased to a local var, because FastAPI
+    # resolves annotations by name and would not see a function-local alias.
+    @app.post("/runs", response_model=RunResponse, status_code=201, tags=["runs"])
+    async def enqueue_run(
+        body: EnqueueRequest, q: Annotated[RunQueue, Depends(get_queue)]
+    ) -> RunResponse:
+        rec = await q.enqueue(body.graph, body.input, thread=body.thread)
+        return RunResponse.of(rec)
+
+    @app.get("/runs/{run_id}", response_model=RunResponse, tags=["runs"])
+    async def get_run(run_id: str, q: Annotated[RunQueue, Depends(get_queue)]) -> RunResponse:
+        rec = await q.get(run_id)
+        if rec is None:
+            raise HTTPException(status_code=404, detail=f"no run with id {run_id!r}")
+        return RunResponse.of(rec)
+
+    @app.get("/runs", response_model=list[RunResponse], tags=["runs"])
+    async def list_runs(
+        q: Annotated[RunQueue, Depends(get_queue)],
+        status: Annotated[str | None, Query()] = None,
+        graph: Annotated[str | None, Query()] = None,
+        limit: Annotated[int, Query(ge=1, le=1000)] = 100,
+        offset: Annotated[int, Query(ge=0)] = 0,
+    ) -> list[RunResponse]:
+        recs = await q.list(status=status, graph=graph, limit=limit, offset=offset)
+        return [RunResponse.of(r) for r in recs]
+
+    @app.post("/runs/{run_id}/resume", response_model=RunResponse, tags=["runs"])
+    async def resume_run(
+        run_id: str, body: ResumeRequest, q: Annotated[RunQueue, Depends(get_queue)]
+    ) -> RunResponse:
+        try:
+            rec = await q.enqueue_resume(run_id, body.value)
+        except RunNotFound:
+            raise HTTPException(status_code=404, detail=f"no run with id {run_id!r}") from None
+        return RunResponse.of(rec)
+
+    @app.post("/runs/{run_id}/cancel", response_model=CancelResponse, tags=["runs"])
+    async def cancel_run(run_id: str, q: Annotated[RunQueue, Depends(get_queue)]) -> CancelResponse:
+        cancelled = await q.request_cancel(run_id)
+        return CancelResponse(cancelled=cancelled)
+
+    @app.get("/stats", response_model=StatsResponse, tags=["monitoring"])
+    async def get_stats(q: Annotated[RunQueue, Depends(get_queue)]) -> StatsResponse:
+        return StatsResponse.of(await q.stats())
+
+    @app.get("/healthz", tags=["monitoring"])
+    async def healthz() -> dict[str, Any]:
+        body: dict[str, Any] = {"status": "ok"}
+        if pool_health is not None:
+            h = pool_health()
+            body["pool"] = {
+                "workers": h.workers,
+                "alive": h.alive,
+                "busy": h.busy,
+                "idle": h.idle,
+                "healthy": h.healthy,
+            }
+        return body
+
+    return app

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/agentflow/state.py

@@ -57,6 +57,7 @@ __all__ = [
     "append",
     "add",
     "merge",
+    "by_key",
     "union",
     "channels_from_schema",
     "apply_update",
@@ -129,6 +130,65 @@ def merge(current: Any, update: Any) -> dict:
     return base
 
 
+def by_key(policy: Mapping[str, Reducer]) -> Reducer:
+    """Build a reducer for a dict channel that folds each key with its own reducer.
+
+    Where :func:`merge` applies one policy (last-wins) to a whole dict, this
+    lets a single structured channel hold keys that accumulate differently —
+    for example an ``intents`` list that grows with :func:`append` beside an
+    ``events`` list that is replaced with :func:`last` and an ``incumbent`` that
+    is overwritten whole::
+
+        search = by_key({
+            "intents":   append,   # grow
+            "candidates": append,  # grow (concurrent workers each add one)
+            "verified":  append,   # grow
+            "events":    last,     # replace (planner clears what it consumed)
+            "incumbent": last,     # overwrite the current best, whole
+        })
+
+        class OptState(State):
+            search: Annotated[dict, search]
+
+    Folding rules, given ``current`` (``None`` is treated as ``{}``) and an
+    ``update`` dict:
+
+    - Only keys present in ``update`` are folded; a key absent from ``update``
+      keeps its ``current`` value untouched.
+    - Each folded key ``k`` is combined as ``policy[k](current.get(k),
+      update[k])`` — so ``{"events": []}`` genuinely clears ``events`` (that is
+      a ``last`` of an empty list, not a no-op), while ``{}`` or ``None`` is a
+      no-op returning a copy of ``current``.
+    - A key in ``update`` that is not in ``policy`` raises :class:`KeyError`.
+      Writing an undeclared field is a bug (usually a typo), mirroring how the
+      engine rejects writes to undeclared top-level channels.
+    - A key in ``current`` that is not in ``policy`` is passed through
+      unchanged; the policy only governs keys an update actually writes.
+
+    The value under each key is combined *whole* by that key's reducer; this is
+    one level of structure, not a recursive deep-merge. It is for distinct keys
+    that accumulate differently, not for concurrent partial patches of the same
+    nested object.
+    """
+    policy = dict(policy)
+
+    def _by_key(current: Any, update: Any) -> dict:
+        base = dict(current) if current is not None else {}
+        if not update:
+            return base
+        for key, value in update.items():
+            reducer = policy.get(key)
+            if reducer is None:
+                raise KeyError(
+                    f"by_key update wrote field {key!r} with no reducer in policy; "
+                    f"declared fields: {sorted(policy)}"
+                )
+            base[key] = reducer(base.get(key), value)
+        return base
+
+    return _by_key
+
+
 def union(current: Any, update: Any) -> set:
     """Set union. ``None`` current is the empty set."""
     base = set(current) if current is not None else set()

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/docs/concepts/state.md

@@ -31,6 +31,35 @@ A field annotated `Annotated[type, reducer]` uses that reducer. A bare field use
 
 `append` extends when the update is a list or tuple, and appends a single element otherwise. Any pure `(current, update) -> new` is a valid reducer — the built-ins are just the common ones. A reducer must be pure and must treat a `None` current as its empty value.
 
+## Structured channels with `by_key`
+
+`merge` folds a whole dict with one policy (last-wins). When one dict channel holds fields that must accumulate differently, `by_key` gives each field its own reducer:
+
+```python
+from agentflow import State, append, by_key, last
+from typing import Annotated
+
+search = by_key({
+    "intents": append,     # grow
+    "candidates": append,  # grow (concurrent workers each add one)
+    "events": last,        # replace
+    "incumbent": last,     # overwrite the current best, whole
+})
+
+class OptState(State):
+    search: Annotated[dict, search]
+```
+
+A node writes the fields it changes, and each is folded by that field's reducer. `{"search": {"candidates": [c]}}` appends one candidate; `{"search": {"events": []}}` clears events. Fields a node does not write are left untouched, so two nodes in one super-step writing different fields never clobber each other.
+
+Three rules worth stating plainly:
+
+- A field in the update that is not in the policy raises `KeyError`. Writing an undeclared field is a bug, just like writing an undeclared top-level channel.
+- Each field's value is folded whole by its reducer. This is one level of structure, not a recursive deep-merge: `last` on `incumbent` replaces the whole object, it does not patch one of its keys.
+- Use `by_key` for distinct fields that accumulate differently, not for concurrent partial patches of the same nested object.
+
+This is the channel behind a search or optimization loop, where a planner appends intents, concurrent workers append candidates, and a verifier replaces events and overwrites the incumbent whole. See the [dual-state search recipe](../patterns/long-running-loops.md#recipe-dual-state-search-with-a-planner-and-a-promotion-boundary) and `examples/dual_state_search.py`.
+
 ## Nodes return deltas, not absolutes
 
 A node returns a partial update — a dict of channel names to values — and the engine folds each value through that channel's reducer:

{agent_workflow_sdk-0.3.0 → agent_workflow_sdk-0.5.0}/docs/durability/control-plane.md

@@ -4,7 +4,7 @@
 
 ## What it is, and is not
 
-The control plane is a library layer, not a service. There is no bundled HTTP server, auth, or tenancy — those are properties of a service you build on top, and are deliberately out of scope. What you get is the durable machinery: a queue, a registry, and workers, all as plain objects you drive.
+The control plane is a library layer first. What you get is the durable machinery: a queue, a registry, and workers, all as plain objects you drive. An optional HTTP layer (the `server` extra) wraps the queue so you can drive it over the network — covered at the end of this chapter. There is still no auth or tenancy anywhere in it; those are properties of a service you put in front, and stay out of scope.
 
 ## The pieces
 
@@ -105,6 +105,67 @@ if not health.healthy:
 
 A rising `expired_leases` is the signal that workers are dying or falling behind their heartbeat. `health.healthy` is False when any configured worker loop is not alive — a readiness signal you can expose directly.
 
+## Over HTTP
+
+Everything so far drives the queue from Python. The optional `server` extra wraps the same queue in a FastAPI app, so you can enqueue and observe runs over the network — from a different language, a web UI, or a `curl` in a shell.
+
+```bash
+pip install 'agent-workflow-sdk[server]'
+```
+
+`create_app` takes a `RunQueue` and returns an ASGI app. It adds no behavior of its own; each route forwards to one queue method.
+
+```python
+from agentflow import PostgresRunQueue
+from agentflow.server import create_app
+
+queue = PostgresRunQueue(dsn)
+app = create_app(queue)        # an ASGI app
+```
+
+Serve it with any ASGI server. `uvicorn` is a common choice and you install it yourself:
+
+```bash
+uvicorn myapp:app --port 8000
+```
+
+The routes map 1:1 onto the queue methods from earlier in this chapter:
+
+- `POST /runs` enqueues a run. Body: `{"graph": "...", "input": {...}, "thread": "..."}` (thread optional). Returns `201` with the run record.
+- `GET /runs/{id}` returns one run record, or `404` if there is no such run.
+- `GET /runs` lists runs. Query params: `status`, `graph`, `limit` (1–1000), `offset`.
+- `POST /runs/{id}/resume` re-queues an interrupted run. Body: `{"value": ...}`. `404` if there is no such run.
+- `POST /runs/{id}/cancel` requests cancellation. Returns `{"cancelled": true}` unless the run was unknown or already terminal.
+- `GET /stats` returns the `QueueStats` snapshot (`total`, `by_status`, `expired_leases`).
+- `GET /healthz` returns `{"status": "ok"}`, plus a `pool` block when you pass `pool_health`.
+
+Because the models are typed, FastAPI serves interactive OpenAPI docs at `/docs` and the raw schema at `/openapi.json` with no extra work.
+
+A quick enqueue over HTTP:
+
+```bash
+curl -X POST localhost:8000/runs \
+  -H 'content-type: application/json' \
+  -d '{"graph": "summarize", "input": {"text": "..."}}'
+```
+
+Wire the pool's health into `/healthz` by passing the callable:
+
+```python
+pool = WorkerPool(queue, registry, concurrency=4)
+app = create_app(queue, pool_health=lambda: pool.health())
+```
+
+### What it does not expose
+
+The worker protocol — `claim`, `heartbeat`, `complete` — is deliberately absent from the HTTP surface. Those methods mutate run state and belong to workers, which talk to the queue directly (in-process, or via the same `PostgresRunQueue`), not over this API. The HTTP layer is the enqueue-and-observe plane only.
+
+### Trust boundary
+
+There is no authentication, authorization, rate limiting, or multi-tenancy in this app. It is an adapter over the queue, not a hardened public endpoint. Run it inside your own trust boundary, or behind a reverse proxy or gateway that supplies those. Anyone who can reach it can enqueue, cancel, and resume any run.
+
+See the [HTTP server API reference](../reference/api/server.md) for the request and response models.
+
 ## When to use the control plane
 
 - Use inline `invoke`/`stream` when the run belongs to the calling process — a request handler, a script, a test.