agent-workflow-sdk 0.4.0__tar.gz → 0.6.0__tar.gz

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/CHANGELOG.md

@@ -4,6 +4,74 @@ 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.6.0] - 2026-09-29
+
+### Changed (breaking)
+
+- Quality-gate results and plan-executor tasks are now stored in state as plain
+  dicts, not dataclasses, so they are JSON-serializable and survive a durable
+  checkpointer. Read `state["gate_results"][name]` as a mapping
+  (`result["passed"]`, not `result.passed`), and read `plan_executor` results
+  as dicts (`r["output"]`, not `r.output`). The evaluator you pass to
+  `add_quality_gate` still returns a `GateResult`, and a handler still returns a
+  `TaskResult` — only the *stored* form changed. This fixes a real bug: either
+  prebuilt combined with a file/sqlite/postgres/redis checkpointer previously
+  raised "not JSON serializable" on the first checkpoint.
+
+### Added
+
+- `plan_executor` (`agentflow.prebuilt`): `add_plan_executor(g, handlers=...,
+  on_idle=...)` runs a dependency graph of tasks a planner emits as data — a
+  task runs once its prerequisites are done, independent tasks fan out
+  concurrently into a fixed slot pool, and the plan is checkpointed so a resume
+  recomputes the runnable frontier. Ships `Task`, `TaskResult`, the `PlanState`
+  mixin, and `plan_complete` / `plan_stalled`.
+- `scoring` (`agentflow.prebuilt`): a deterministic, backend-independent measure
+  for a candidate — `Score`, the `Scorer` contract, `score_candidates` (batch,
+  bounded concurrency), `best_of` (promote the best feasible, keep the incumbent
+  unless strictly beaten), and `ScoreCache`. The verifier half of an optimizer
+  loop, so swapping the proposer (a local agent, a hosted LLM) never changes the
+  score.
+- Token / cost budget: `Usage` (input/output/total tokens, optional `cost_usd`)
+  is now an optional field on `TurnEnd`, populated by the Ollama and Codex
+  backends. New `agentflow.prebuilt` helpers: `TokenMeter` (a `Hooks` listener
+  that sums usage for observation), the `BudgetState` mixin, `record_usage`, and
+  `over_budget` — budget lives in state, survives a resume, and a router stops
+  the run at a token or cost cap.
+
+### Documentation
+
+- A unified Tutorials section: the Q&A agent quick start, a ten-chapter
+  "Mechanics: building an optimizer" tutorial on a toy cost model, and a
+  ten-chapter "Applied: a query optimizer with agents" tutorial that measures
+  real index/rewrite candidates against a seeded SQLite database, with a local
+  Codex agent as the opt-in proposer.
+
+## [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

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-workflow-sdk
-Version: 0.4.0
+Version: 0.6.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
@@ -188,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
@@ -540,6 +541,35 @@ app = iterate_until_converged(work, perfect_score=100.0, patience=4)
 result = await app.invoke({})
 ```
 
+`agentflow.prebuilt.add_plan_executor(g, handlers=..., on_idle=...)` runs a
+dependency graph of tasks that a planner emits as data. The planner writes
+`Task`s (each with an `id`, a `kind`, and `prerequisites`) into a `by_key`
+`plan` channel; the executor runs each task once its prerequisites are done,
+fans independent ones out concurrently up to `max_fanout`, and loops until
+nothing is runnable. The graph stays static — a new task is new data, not a new
+node — so the plan is checkpointed and a resume recomputes what is runnable.
+This is how a workflow builds and re-optimizes its own execution plan as it
+goes. See `examples/plan_executor_demo.py`.
+
+```python
+from agentflow.prebuilt import PlanState, Task, TaskResult, add_plan_executor
+
+async def run_step(task, state, ctx) -> TaskResult:
+    return TaskResult(task.id, output=await do_work(task))
+
+async def planner(state, ctx):
+    return {"plan": {"tasks": [
+        Task("fetch", "step"),
+        Task("build", "step", prerequisites=("fetch",)),
+    ]}}
+
+g = Graph(PlanState)
+g.add_node("planner", planner)
+add_plan_executor(g, handlers={"step": run_step}, on_idle="planner")
+g.add_edge(START, "planner")
+g.add_edge("planner", "dispatch")
+```
+
 `agentflow.prebuilt.tool_loop(llm, tools)` compiles the function-calling agent
 loop as a two-node graph: an `agent` node calls the `LLMBackend`, a `tools`
 node runs any tool the model requested and appends the result to the
@@ -594,7 +624,7 @@ agentflow/
   checkpoint/         Checkpointer protocol + memory/file/sqlite/redis/postgres
   store/              Store protocol (cross-thread memory) + memory/postgres
   controlplane/       RunQueue + GraphRegistry + Worker (memory/postgres)
-  prebuilt/           iterate_until_converged, tool_loop, with_retry/with_timeout
+  prebuilt/           iterate_until_converged, tool_loop, plan_executor, gates
 examples/             runnable examples
 tests/                pytest suite (async; offline by default, `-m live` for real backends)
 DESIGN.md             architecture and contracts

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.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
@@ -491,6 +492,35 @@ app = iterate_until_converged(work, perfect_score=100.0, patience=4)
 result = await app.invoke({})
 ```
 
+`agentflow.prebuilt.add_plan_executor(g, handlers=..., on_idle=...)` runs a
+dependency graph of tasks that a planner emits as data. The planner writes
+`Task`s (each with an `id`, a `kind`, and `prerequisites`) into a `by_key`
+`plan` channel; the executor runs each task once its prerequisites are done,
+fans independent ones out concurrently up to `max_fanout`, and loops until
+nothing is runnable. The graph stays static — a new task is new data, not a new
+node — so the plan is checkpointed and a resume recomputes what is runnable.
+This is how a workflow builds and re-optimizes its own execution plan as it
+goes. See `examples/plan_executor_demo.py`.
+
+```python
+from agentflow.prebuilt import PlanState, Task, TaskResult, add_plan_executor
+
+async def run_step(task, state, ctx) -> TaskResult:
+    return TaskResult(task.id, output=await do_work(task))
+
+async def planner(state, ctx):
+    return {"plan": {"tasks": [
+        Task("fetch", "step"),
+        Task("build", "step", prerequisites=("fetch",)),
+    ]}}
+
+g = Graph(PlanState)
+g.add_node("planner", planner)
+add_plan_executor(g, handlers={"step": run_step}, on_idle="planner")
+g.add_edge(START, "planner")
+g.add_edge("planner", "dispatch")
+```
+
 `agentflow.prebuilt.tool_loop(llm, tools)` compiles the function-calling agent
 loop as a two-node graph: an `agent` node calls the `LLMBackend`, a `tools`
 node runs any tool the model requested and appends the result to the
@@ -545,7 +575,7 @@ agentflow/
   checkpoint/         Checkpointer protocol + memory/file/sqlite/redis/postgres
   store/              Store protocol (cross-thread memory) + memory/postgres
   controlplane/       RunQueue + GraphRegistry + Worker (memory/postgres)
-  prebuilt/           iterate_until_converged, tool_loop, with_retry/with_timeout
+  prebuilt/           iterate_until_converged, tool_loop, plan_executor, gates
 examples/             runnable examples
 tests/                pytest suite (async; offline by default, `-m live` for real backends)
 DESIGN.md             architecture and contracts

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/agentflow/__init__.py

@@ -74,6 +74,7 @@ from agentflow.events import (
     ToolResult,
     ToolSpec,
     TurnEnd,
+    Usage,
 )
 from agentflow.graph import END, START, Graph, Node, Router
 from agentflow.interrupts import (
@@ -90,6 +91,7 @@ from agentflow.state import (
     State,
     add,
     append,
+    by_key,
     last,
     merge,
     union,
@@ -97,7 +99,7 @@ from agentflow.state import (
 from agentflow.store import Item, MemoryStore, Store
 from agentflow.telemetry import JsonlTelemetry, MultiHooks
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"
 
 __all__ = [
     "__version__",
@@ -109,6 +111,7 @@ __all__ = [
     "append",
     "add",
     "merge",
+    "by_key",
     "union",
     # graph
     "Graph",
@@ -139,6 +142,7 @@ __all__ = [
     "ToolResult",
     "PermissionRequest",
     "PermissionOption",
+    "Usage",
     "TurnEnd",
     "ErrorEvent",
     "GateEvent",

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/agentflow/backends/cli_exec.py

@@ -48,6 +48,7 @@ from agentflow.events import (
     ErrorEvent,
     TextRequest,
     TurnEnd,
+    Usage,
 )
 
 __all__ = ["CLIExecBackend", "TurnAccumulator"]
@@ -61,6 +62,9 @@ class TurnAccumulator:
     stop_reason: str | None = None
     session_id: str | None = None
     is_error: bool = False
+    #: Token/cost usage, if the CLI reports it (set by the subclass on the
+    #: terminal event). Left None when the CLI surfaces no counts.
+    usage: Usage | None = None
 
     def add_text(self, text: str) -> None:
         if text:
@@ -178,6 +182,7 @@ class CLIExecBackend(BaseAgentBackend):
         yield TurnEnd(
             text=acc.text,
             stop_reason=acc.stop_reason or ("error" if acc.is_error else "end_turn"),
+            usage=acc.usage,
         )
 
     # ------------------------------------------------------------------

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/agentflow/backends/codex.py

@@ -34,7 +34,7 @@ from typing import Any, Literal
 
 from agentflow.backends.base import PermissionPolicy, policy_intent
 from agentflow.backends.cli_exec import CLIExecBackend, TurnAccumulator
-from agentflow.events import BackendEvent, TextChunk, ToolCall, ToolResult
+from agentflow.events import BackendEvent, TextChunk, ToolCall, ToolResult, Usage
 
 __all__ = ["CodexBackend"]
 
@@ -109,6 +109,14 @@ class CodexBackend(CLIExecBackend):
 
         if kind == "turn.completed":
             acc.stop_reason = "end_turn"
+            usage = obj.get("usage")
+            if isinstance(usage, dict):
+                pin = usage.get("input_tokens")
+                pout = usage.get("output_tokens")
+                total = usage.get("total_tokens")
+                if total is None and (pin is not None or pout is not None):
+                    total = (pin or 0) + (pout or 0)
+                acc.usage = Usage(input_tokens=pin, output_tokens=pout, total_tokens=total)
             return []
 
         if kind == "turn.failed" or kind == "error":

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/agentflow/backends/ollama.py

@@ -45,6 +45,7 @@ from agentflow.events import (
     ToolCall,
     ToolCallSpec,
     TurnEnd,
+    Usage,
 )
 
 try:
@@ -99,6 +100,7 @@ class OllamaBackend(BaseLLMBackend):
         text_parts: list[str] = []
         tool_calls: list[ToolCallSpec] = []
         stop_reason: str | None = None
+        usage: Usage | None = None
 
         async with (
             self.concurrency_guard(),
@@ -127,6 +129,13 @@ class OllamaBackend(BaseLLMBackend):
 
                     if chunk.get("done"):
                         stop_reason = chunk.get("done_reason") or "stop"
+                        # Ollama reports token counts on the final chunk:
+                        # prompt_eval_count = input, eval_count = output.
+                        pin = chunk.get("prompt_eval_count")
+                        pout = chunk.get("eval_count")
+                        if pin is not None or pout is not None:
+                            total = (pin or 0) + (pout or 0) if (pin or pout) else None
+                            usage = Usage(input_tokens=pin, output_tokens=pout, total_tokens=total)
             except httpx.HTTPError as exc:
                 raise BackendTransportError(f"ollama stream failed: {exc}") from exc
 
@@ -136,7 +145,7 @@ class OllamaBackend(BaseLLMBackend):
             content=final_text,
             tool_calls=tuple(tool_calls),
         )
-        yield TurnEnd(text=final_text, stop_reason=stop_reason, message=message)
+        yield TurnEnd(text=final_text, stop_reason=stop_reason, message=message, usage=usage)
 
     # ------------------------------------------------------------------
 

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/agentflow/events.py

@@ -44,6 +44,7 @@ __all__ = [
     "ToolResult",
     "PermissionOption",
     "PermissionRequest",
+    "Usage",
     "TurnEnd",
     "ErrorEvent",
     "BackendEvent",
@@ -178,14 +179,35 @@ class PermissionRequest:
     detail: dict[str, Any] = field(default_factory=dict)
 
 
+@dataclass(frozen=True, slots=True)
+class Usage:
+    """Token (and optional cost) usage reported by a backend for one turn.
+
+    All fields are optional because backends differ in what they report: some
+    give input/output splits, some only a total, some none at all. A field left
+    ``None`` means "not reported" — a token budget simply cannot count what a
+    backend does not surface, and the budget helpers treat ``None`` as zero.
+    ``cost_usd`` is only present when a backend or the caller supplies pricing;
+    the SDK ships no price table (it would go stale), so budget on tokens by
+    default and set ``cost_usd`` yourself if you want a dollar cap.
+    """
+
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+    cost_usd: float | None = None
+
+
 @dataclass(frozen=True, slots=True)
 class TurnEnd:
-    """Terminal event of a turn. Carries the fully assembled assistant text
-    and the backend's stop reason (e.g. ``end_turn``, ``max_tokens``)."""
+    """Terminal event of a turn. Carries the fully assembled assistant text,
+    the backend's stop reason (e.g. ``end_turn``, ``max_tokens``), and optional
+    token/cost :class:`Usage` when the backend reports it."""
 
     text: str = ""
     stop_reason: str | None = None
     message: Message | None = None
+    usage: Usage | None = None
 
 
 @dataclass(frozen=True, slots=True)

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/agentflow/prebuilt/__init__.py

@@ -14,11 +14,28 @@
 
 """Prebuilt graph patterns built entirely from core primitives."""
 
+from agentflow.prebuilt.budget import BudgetState, TokenMeter, over_budget, record_usage
 from agentflow.prebuilt.effects import IdempotentOp, IncompleteEffectError, effect_key
 from agentflow.prebuilt.gate import Evaluator, GateResult, GateState, add_quality_gate
 from agentflow.prebuilt.idempotent import artifact_key, skip_if_done
 from agentflow.prebuilt.loop import Candidate, iterate_until_converged
+from agentflow.prebuilt.plan_executor import (
+    Handler,
+    PlanState,
+    Task,
+    TaskResult,
+    add_plan_executor,
+    plan_complete,
+    plan_stalled,
+)
 from agentflow.prebuilt.resilience import with_retry, with_timeout
+from agentflow.prebuilt.scoring import (
+    Score,
+    ScoreCache,
+    Scorer,
+    best_of,
+    score_candidates,
+)
 from agentflow.prebuilt.tool_loop import Tool, ToolLoopState, tool_loop
 from agentflow.prebuilt.watch import (
     CommandWatcher,
@@ -31,6 +48,13 @@ from agentflow.prebuilt.watch import (
 __all__ = [
     "Candidate",
     "iterate_until_converged",
+    "Task",
+    "TaskResult",
+    "PlanState",
+    "Handler",
+    "add_plan_executor",
+    "plan_complete",
+    "plan_stalled",
     "GateResult",
     "GateState",
     "Evaluator",
@@ -45,6 +69,15 @@ __all__ = [
     "tool_loop",
     "with_retry",
     "with_timeout",
+    "Score",
+    "Scorer",
+    "ScoreCache",
+    "score_candidates",
+    "best_of",
+    "TokenMeter",
+    "BudgetState",
+    "record_usage",
+    "over_budget",
     "WatchResult",
     "Watcher",
     "CommandWatcher",

agent_workflow_sdk-0.6.0/agentflow/prebuilt/budget.py

@@ -0,0 +1,174 @@
+# 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.
+
+"""Token / cost budget for an autonomous run.
+
+An agentic loop that proposes with an LLM runs many rounds, each costing
+tokens. Time has a guard (``with_timeout``), load has one (``max_concurrency``),
+loop length has one (``step_limit``) — this is the guard for *spend*.
+
+Two pieces, matching "how much did I spend?" and "stop at a cap":
+
+- :class:`TokenMeter` is a :class:`~agentflow.observability.Hooks` listener that
+  sums usage across a run from the backend events a node emits. Pure
+  observation — it never affects the run (a hook cannot, by contract), so it
+  answers "how much?" but cannot stop anything.
+
+- To *stop*, budget is state. Mix :class:`BudgetState` into your schema, have
+  the node that drives the LLM add its turn's usage with :func:`record_usage`,
+  and have your router call :func:`over_budget` and route to a stop/escalate
+  node when the cap is exceeded. Because the budget rides the checkpoint, it
+  survives a resume (a resumed run does not forget what it already spent), and
+  stopping is a routing decision — the same discipline as every other stop in
+  the SDK: the work writes an artifact, a router decides what happens next.
+
+    class SearchState(BudgetState):
+        ...
+
+    async def propose(state, ctx):
+        turn = await call_llm(...)                 # yields a TurnEnd with .usage
+        return {**result, **record_usage(turn.usage)}
+
+    def route(state):
+        if over_budget(state, max_tokens=100_000):
+            return "stop"
+        return "continue"
+
+The stop takes effect at the next super-step boundary, not mid-turn, so a run
+may overshoot the cap by at most the turn in flight. That is the deliberate
+trade of the state-based design: durable and engine-free, at the cost of
+turn-granular (not token-exact) enforcement.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from agentflow.events import Usage
+from agentflow.observability import Hooks
+from agentflow.state import State, add, by_key
+
+__all__ = ["TokenMeter", "BudgetState", "record_usage", "over_budget"]
+
+
+class BudgetState(State):
+    """Mix into a schema to add the ``budget`` channel the helpers accumulate.
+
+    The channel is a dict whose numeric fields each sum via ``add``, so many
+    nodes (or many rounds) fold their spend together. Fields mirror
+    :class:`~agentflow.events.Usage`: ``input_tokens``, ``output_tokens``,
+    ``total_tokens``, ``cost_usd``.
+    """
+
+    budget: Annotated[
+        dict,
+        by_key(
+            {
+                "input_tokens": add,
+                "output_tokens": add,
+                "total_tokens": add,
+                "cost_usd": add,
+            }
+        ),
+    ]
+
+
+def record_usage(usage: Usage | None) -> dict[str, Any]:
+    """Return a state update that adds ``usage`` into the ``budget`` channel.
+
+    A ``None`` usage (a backend that reports no counts) contributes nothing —
+    the returned update is empty, so a node can unconditionally
+    ``return {**result, **record_usage(turn.usage)}``. Only the fields the
+    backend actually reported are added; a missing field is treated as zero and
+    omitted, so it does not fabricate a total.
+    """
+    if usage is None:
+        return {}
+    fields: dict[str, Any] = {}
+    if usage.input_tokens is not None:
+        fields["input_tokens"] = usage.input_tokens
+    if usage.output_tokens is not None:
+        fields["output_tokens"] = usage.output_tokens
+    # total: prefer the reported total, else derive from input+output if present
+    if usage.total_tokens is not None:
+        fields["total_tokens"] = usage.total_tokens
+    elif usage.input_tokens is not None or usage.output_tokens is not None:
+        fields["total_tokens"] = (usage.input_tokens or 0) + (usage.output_tokens or 0)
+    if usage.cost_usd is not None:
+        fields["cost_usd"] = usage.cost_usd
+    if not fields:
+        return {}
+    return {"budget": fields}
+
+
+def over_budget(
+    state: Any,
+    *,
+    max_tokens: int | None = None,
+    max_cost_usd: float | None = None,
+) -> bool:
+    """True when accumulated spend has reached or passed a given cap.
+
+    Checks whichever caps are provided: ``max_tokens`` against the summed
+    ``total_tokens``, ``max_cost_usd`` against the summed ``cost_usd``. With no
+    caps given it is always ``False`` (nothing to enforce). Spend not yet
+    recorded (a backend that reports nothing) reads as zero, so a token cap can
+    only fire when some backend actually surfaced counts.
+    """
+    budget = state.get("budget") or {}
+    tokens_over = max_tokens is not None and budget.get("total_tokens", 0) >= max_tokens
+    cost_over = max_cost_usd is not None and budget.get("cost_usd", 0.0) >= max_cost_usd
+    return bool(tokens_over or cost_over)
+
+
+class TokenMeter(Hooks):
+    """A Hooks listener that accumulates token/cost usage across a run.
+
+    Attach at ``compile(hooks=...)``. It sums the usage on every ``TurnEnd`` a
+    node surfaces via ``ctx.emit``. Pure observation for logging or a metrics
+    readout — it does not and cannot stop a run (hooks must never change
+    behavior). To stop on a cap, use :func:`over_budget` in a router.
+    """
+
+    def __init__(self) -> None:
+        self.input_tokens = 0
+        self.output_tokens = 0
+        self.total_tokens = 0
+        self.cost_usd = 0.0
+        self.turns = 0
+
+    async def on_event(self, thread: str, step: int, node: str, event: Any) -> None:
+        usage = getattr(event, "usage", None)
+        if not isinstance(usage, Usage):
+            return
+        self.turns += 1
+        if usage.input_tokens:
+            self.input_tokens += usage.input_tokens
+        if usage.output_tokens:
+            self.output_tokens += usage.output_tokens
+        if usage.total_tokens is not None:
+            self.total_tokens += usage.total_tokens
+        elif usage.input_tokens or usage.output_tokens:
+            self.total_tokens += (usage.input_tokens or 0) + (usage.output_tokens or 0)
+        if usage.cost_usd:
+            self.cost_usd += usage.cost_usd
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "turns": self.turns,
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "total_tokens": self.total_tokens,
+            "cost_usd": round(self.cost_usd, 6),
+        }

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.6.0}/agentflow/prebuilt/gate.py

@@ -81,6 +81,11 @@ class GateResult:
     ``passed`` is the only field the router requires. ``score`` and ``reasons``
     are for observability and human review; ``feedback`` is the actionable text
     a revise node can consume to improve the artifact on the next attempt.
+
+    The gate stores this verdict in state as a plain dict (via :meth:`to_dict`),
+    not as this object, so it is JSON-serializable and survives a durable
+    checkpointer. Read it from ``state["gate_results"][name]`` as a mapping:
+    ``result["passed"]``, ``result["feedback"]``, and so on.
     """
 
     passed: bool
@@ -88,6 +93,15 @@ class GateResult:
     reasons: list[str] = field(default_factory=list)
     feedback: str | None = None
 
+    def to_dict(self) -> dict[str, Any]:
+        """A JSON-serializable view, as stored in the ``gate_results`` channel."""
+        return {
+            "passed": self.passed,
+            "score": self.score,
+            "reasons": list(self.reasons),
+            "feedback": self.feedback,
+        }
+
 
 class GateState(State):
     """Mix into a state schema to add the channels quality gates need.
@@ -99,7 +113,10 @@ class GateState(State):
 
     #: Attempt count per gate name.
     gate_attempts: Annotated[dict, merge]
-    #: The most recent :class:`GateResult` per gate name.
+    #: The most recent verdict per gate name, stored as a plain dict
+    #: (``{"passed", "score", "reasons", "feedback"}``) so it is
+    #: JSON-serializable and survives a durable checkpointer. Read it as a
+    #: mapping — ``state["gate_results"]["name"]["passed"]``.
     gate_results: Annotated[dict, last]
 
 
@@ -173,15 +190,15 @@ def add_quality_gate(
         )
 
         results = dict(state.get("gate_results") or {})
-        results[name] = result
+        results[name] = result.to_dict()  # store a plain dict, not the dataclass
         return {"gate_attempts": {name: attempt}, "gate_results": results}
 
     def route(state: Mapping[str, Any]) -> str:
         results = state.get("gate_results") or {}
-        result: GateResult | None = results.get(name)
+        result: dict[str, Any] | None = results.get(name)
         attempts = state.get("gate_attempts") or {}
         attempt = int(attempts.get(name, 0))
-        if result is not None and result.passed:
+        if result is not None and result["passed"]:
             return "pass"
         if attempt >= max_attempts:
             return "escalate"