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

agent_workflow_sdk-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Something behaves incorrectly or crashes
+labels: bug
+---
+
+## What happened
+
+A clear description of the bug and what you expected instead.
+
+## Reproduction
+
+Smallest graph/code that reproduces it. A runnable snippet is ideal.
+
+```python
+# ...
+```
+
+## Environment
+
+- `agent-workflow-sdk` version:
+- Python version:
+- Backend involved (KiroBackend / CodexBackend / ClaudeCodeBackend / OllamaBackend / OpenAIBackend / AnthropicBackend / none):
+- Checkpointer / Store / control-plane backend, if relevant (memory / file / sqlite / redis / postgres):
+
+## Logs or traceback
+
+```
+paste here
+```

agent_workflow_sdk-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Propose a capability or change
+labels: enhancement
+---
+
+## Problem
+
+What are you trying to do that the SDK makes hard or impossible today?
+
+## Proposed solution
+
+What you'd like to see. If it touches the public API, sketch the shape
+(a node, a backend, a prebuilt pattern, a control-plane method, ...).
+
+## Alternatives considered
+
+Workarounds you've tried, or other designs you weighed.
+
+## Scope check
+
+Does this fit a library (engine, backends, control plane) rather than a
+service layer? See `DESIGN.md` for what is intentionally out of scope.

agent_workflow_sdk-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## What and why
+
+What this changes and the problem it solves. Link any related issue.
+
+## How
+
+Key implementation points a reviewer should know. Note any new public API
+or any change to a documented contract in `DESIGN.md`.
+
+## Checklist
+
+- [ ] `ruff check agentflow tests examples` passes
+- [ ] `ruff format --check agentflow tests examples` passes
+- [ ] `mypy agentflow` passes
+- [ ] `pytest -q` (offline suite) passes; added/updated tests for the change
+- [ ] Docs updated if behavior or public API changed (README / `docs/` / docstrings)
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` for a user-facing change

{agent_workflow_sdk-0.2.0 → agent_workflow_sdk-0.3.0}/.github/workflows/ci.yml

@@ -78,3 +78,39 @@ jobs:
           assert "agentflow/py.typed" in names, "py.typed missing from wheel"
           print("py.typed present in", wheel)
           PY
+
+  pg-tests:
+    # The Postgres backends (Store, Checkpointer, RunQueue) are skipped by the
+    # hermetic default run, so their real SQL paths are exercised here against
+    # a live server started as a service container.
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: agentflow_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install (postgres + ollama + dev extras)
+        # ollama is included for httpx: pytest imports every test module during
+        # collection, and the HTTP-backend test modules import httpx at top
+        # level — without it, collection errors before the -m pg filter applies.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[postgres,ollama,dev]'
+      - name: Run the Postgres test suite
+        env:
+          POSTGRES_TEST_DSN: postgresql://postgres:postgres@localhost:5432/agentflow_test
+        run: pytest -q -m pg tests/test_postgres_store.py tests/test_postgres_checkpointer.py tests/test_postgres_runqueue.py

agent_workflow_sdk-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+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.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+# Allow one concurrent deploy; a newer run supersedes an in-flight one.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install docs extra
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[docs]'
+      - name: Build the site (strict)
+        run: mkdocs build --strict
+      - name: Upload the Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

agent_workflow_sdk-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Release
+
+# Publish to PyPI and cut a GitHub Release when a version tag is pushed.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Verify the tag matches the packaged version
+        # A tag of vX.Y.Z must match pyproject's version and __version__, so a
+        # mistagged release fails here instead of publishing the wrong build.
+        run: |
+          python -m pip install --upgrade pip
+          tag="${GITHUB_REF_NAME#v}"
+          proj=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          pkg=$(python -c "import re; print(re.search(r'__version__ = \"([^\"]+)\"', open('agentflow/__init__.py').read()).group(1))")
+          echo "tag=$tag pyproject=$proj package=$pkg"
+          test "$tag" = "$proj" || { echo "tag != pyproject version"; exit 1; }
+          test "$tag" = "$pkg"  || { echo "tag != __version__"; exit 1; }
+
+      - name: Build wheel + sdist
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Check artifacts (twine + py.typed)
+        run: |
+          python -m pip install twine
+          python -m twine check dist/*
+          python - <<'PY'
+          import glob, zipfile
+          wheel = glob.glob("dist/*.whl")[0]
+          assert "agentflow/py.typed" in zipfile.ZipFile(wheel).namelist(), "py.typed missing"
+          print("py.typed present in", wheel)
+          PY
+
+      - name: Upload built artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing (OIDC): no API token stored anywhere. Configure the
+    # matching publisher for this repo/workflow on PyPI once (Project settings
+    # -> Publishing) and every tagged build publishes with no secret.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Fetch built artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Fetch built artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create the GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes "See [CHANGELOG.md](https://github.com/${GITHUB_REPOSITORY}/blob/main/CHANGELOG.md) for what changed."

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

@@ -4,6 +4,48 @@ 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.3.0] - 2026-10-02
+
+### Added
+
+- Watch nodes: park a run on an external system without burning turns while
+  nothing changes. `ctx.wait(wake_at, payload)` is a timer-based sibling of the
+  human interrupt — it suspends the run until a time, then re-runs the node.
+  `Checkpoint` gains `wake_at` and a derived `suspend_kind` (`"human"` |
+  `"timer"`); the human-interrupt path is unchanged.
+- Durable parked execution: `RunStatus.WAITING` + `RunRecord.wake_at`. A run
+  parked on `ctx.wait` is `WAITING` in the queue and does not hold a worker;
+  `claim` re-takes it once `wake_at` passes (symmetric to lease expiry), in both
+  `MemoryRunQueue` and `PostgresRunQueue`. The worker frees itself on a timer
+  suspend and resumes on re-claim.
+- `CompiledGraph.run_until_done(...)` drives timer waits inline (sleeps until
+  `wake_at` and resumes), for running a watch loop without the control plane —
+  the process must stay alive for the wait, unlike the parked control-plane
+  path.
+- `agentflow.prebuilt.watch`: `WatchResult` (idle/activity/terminal), the
+  `Watcher` protocol, `CommandWatcher` (poll any command that prints the
+  contract JSON), `watch_node` (polls, parks on idle, loops until non-idle), and
+  `route_watch`. GitHub/CI/etc. are examples over `CommandWatcher`, not core.
+  See `examples/watch_until_done.py`.
+
+### Fixed
+
+- First-use schema creation on PostgreSQL is now concurrency-safe. `CREATE TABLE
+  IF NOT EXISTS` can collide on `pg_type` when two sessions bootstrap the same
+  table at once; the Postgres backends now run that DDL under a
+  `pg_advisory_xact_lock` (plus an in-process lock), so a pool of workers
+  starting together no longer races.
+
+### Changed
+
+- Internal: the Postgres backends (`PostgresStore`, `PostgresCheckpointer`,
+  `PostgresRunQueue`) now have a real-server contract test suite, run in CI
+  against a `postgres` service container. The tests are marked `pg` and skipped
+  by the default hermetic run (they need `POSTGRES_TEST_DSN`); they cover the
+  SQL-only paths the in-memory suites can't — the `if_absent` conditional write
+  and `StoreConflict`, the `if_revision` compare-and-set and `CheckpointConflict`,
+  and concurrent `claim` under `FOR UPDATE SKIP LOCKED`.
+
 ## [0.2.0] - 2026-10-01
 
 ### Added
@@ -99,8 +141,8 @@ 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.
+First public release: an async-first SDK for agent workflows with pluggable
+agent and LLM backends.
 
 ### Added
 

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: agent-workflow-sdk
-Version: 0.2.0
-Summary: Async-first, LangGraph-style SDK for building agent workflows with pluggable agent and LLM backends.
+Version: 0.3.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
 Project-URL: Changelog, https://github.com/dankosorkin/agent-workflow-sdk/blob/main/CHANGELOG.md
@@ -45,69 +45,137 @@ Description-Content-Type: text/markdown
 
 # agent-workflow-sdk
 
-An async-first, LangGraph-style SDK for building agent workflows from
-composable pieces. You describe a workflow as a graph of nodes over a typed,
-reducer-based state, and run it against a pluggable backend — a coding agent
-(Kiro, Codex, or Claude Code) or a plain LLM (Ollama, any OpenAI-compatible
-endpoint, or Anthropic).
+[![PyPI](https://img.shields.io/pypi/v/agent-workflow-sdk)](https://pypi.org/project/agent-workflow-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-workflow-sdk)](https://pypi.org/project/agent-workflow-sdk/)
+[![CI](https://github.com/dankosorkin/agent-workflow-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/dankosorkin/agent-workflow-sdk/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/agent-workflow-sdk)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-live-brightgreen)](https://dankosorkin.github.io/agent-workflow-sdk/)
 
-The import root is `agentflow`. The distribution name is
-`agent-workflow-sdk`.
+An async-first SDK for building agent workflows from composable pieces. You
+describe a workflow as a graph of nodes over a typed, reducer-based state, and
+run it against a pluggable backend — a local coding agent (Claude Code, Codex,
+or Kiro) or a plain LLM (Ollama, any OpenAI-compatible endpoint, or Anthropic).
 
-## Why
+The import root is `agentflow`. The distribution name is `agent-workflow-sdk`.
 
-- Build any workflow from primitives: nodes, edges, conditional routing, and
-  a shared state. Not a fixed loop, not a linear chain.
+## Who it's for
+
+You drive a **local coding-agent CLI** — Claude Code, Codex, or Kiro — and you
+want to orchestrate it with real control flow: branches, loops, retries, a
+human approving a step, a run that survives a crash and resumes. You get that
+without wiring up an API key, because the agent runs through its own CLI and
+its own auth. (An API key path exists too — point a node at `OpenAIBackend` or
+`AnthropicBackend` when you want one — but it's an option, not a requirement.)
+
+It is a library, not a coding agent out of the box. If a ready-made agent CLI
+already does what you need, use that. Reach for this when you need to build the
+workflow *around* the agent and keep that logic independent of which backend
+runs underneath.
+
+- Build any workflow from primitives: nodes, edges, conditional routing, and a
+  shared state. Not a fixed loop, not a linear chain.
 - Swap the backend without touching workflow code. Agents and LLMs share one
   event vocabulary.
 - Async everywhere: the engine, backends, checkpointing, and streaming.
 - Durable by default: every super-step is checkpointed, runs resume after a
   crash, and human-in-the-loop interrupts suspend and resume a run.
 
-
 ## Install
 
+```bash
+pip install agent-workflow-sdk
+```
+
 The core is dependency-free. Backends that need extra libraries are optional
-extras.
+extras — e.g. `pip install 'agent-workflow-sdk[ollama]'` for the HTTP LLM
+backends. Python 3.11+ is required.
+
+The local-agent backends need their CLI on PATH: `claude` for Claude Code,
+`codex` for Codex, `kiro-cli` for Kiro. No API key is needed — each CLI uses
+its own login.
+
+To work on the SDK itself, clone and install editable:
 
 ```bash
-pip install -e .            # core only
-pip install -e '.[ollama]'  # + httpx, for the Ollama LLM backend
-pip install -e '.[dev]'     # + pytest, pytest-asyncio
+git clone https://github.com/dankosorkin/agent-workflow-sdk
+cd agent-workflow-sdk
+pip install -e '.[dev]'
 ```
 
-Python 3.11+ is required. The Kiro backend needs `kiro-cli` on PATH.
+## Quickstart: a local agent, gated by a human
 
-## Quickstart
-
-A graph that loops until a counter reaches a target, then stops.
+A two-step workflow that puts the SDK's point on one screen. A **Claude Code**
+node does the work in its own session; then the run **pauses for a human** to
+approve before anything proceeds. Because every step is checkpointed, the
+pause survives a process restart — you can approve now, tomorrow, or from a
+different process, and the run resumes exactly where it stopped. No API key:
+Claude Code runs through its own CLI login.
 
 ```python
 import asyncio
 from typing import Annotated
-from agentflow import Graph, START, END, State, add, append
-
-class CountState(State):
-    n: Annotated[int, add]        # updates are summed
-    log: Annotated[list, append]  # updates are concatenated
-
-async def tick(state, ctx):
-    return {"n": 1, "log": f"tick {state.get('n', 0) + 1}"}
-
-def route(state):
-    return "again" if state["n"] < 5 else "done"
-
-g = Graph(CountState)
-g.add_node("tick", tick)
-g.add_edge(START, "tick")
-g.add_conditional_edges("tick", route, {"again": "tick", "done": END})
-app = g.compile()
-
-print(asyncio.run(app.invoke({"n": 0, "log": []})))
+from agentflow import Graph, START, END, State, FileCheckpointer, last, append
+from agentflow.backends.claude_code import ClaudeCodeBackend
+from agentflow.backends.base import DenyAll
+from agentflow.events import TextChunk, TurnEnd
+
+class ReviewState(State):
+    target: Annotated[str, last]
+    proposal: Annotated[str, last]
+    approved: Annotated[bool, last]
+    log: Annotated[list, append]
+
+claude = ClaudeCodeBackend(model="sonnet", permission=DenyAll())  # read-only
+
+async def propose(state, ctx):
+    text = []
+    async for ev in claude.prompt(
+        f"Review this repo and propose ONE concrete improvement to {state['target']}. "
+        "Describe the change; do not apply it."
+    ):
+        if isinstance(ev, TextChunk):
+            ctx.emit(ev)              # stream tokens to the caller as they arrive
+            text.append(ev.text)
+        elif isinstance(ev, TurnEnd):
+            text = [ev.text] if ev.text else text
+    return {"proposal": "".join(text)}
+
+async def gate(state, ctx):
+    # Suspend the whole run until a human answers. On a fresh run this stops
+    # here and checkpoints; on resume, interrupt() returns the human's value.
+    decision = await ctx.interrupt({"review": state["proposal"]})
+    return {"approved": decision == "approve", "log": f"human said: {decision}"}
+
+g = Graph(ReviewState)
+g.add_node("propose", propose)
+g.add_node("gate", gate)
+g.add_edge(START, "propose")
+g.add_edge("propose", "gate")
+g.add_edge("gate", END)
+
+async def main():
+    app = g.compile(checkpointer=FileCheckpointer(".runs"))  # durable
+    async with claude:
+        state = await app.invoke({"target": "the README"}, thread="demo")
+        # The run is now parked at the gate. Show the proposal, get a decision:
+        cp = await app.get_state("demo")
+        print(cp.interrupt_payload["review"])          # Claude's proposal
+        final = await app.resume("demo", value="approve")
+        print(final["approved"], final["log"])
+
+asyncio.run(main())
 ```
 
-See `examples/hello_graph.py` and `examples/optimize_loop.py` for runnable
-versions.
+That is the whole value in one example: a real local agent does the work, the
+graph owns the control flow, a human gates the result, and durability means
+the pause is not tied to this process staying alive. Swap `ClaudeCodeBackend`
+for `CodexBackend`, `KiroBackend`, or an LLM backend and the workflow code
+above does not change.
+
+Prefer to learn the engine first, with no backend and nothing to install
+beyond the core? `examples/hello_graph.py` is a minimal counter graph that
+shows state, reducers, and edges on their own; `examples/optimize_loop.py`
+shows the iterate-until-converged loop.
 
 ## Core concepts