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

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/.gitignore

@@ -11,3 +11,6 @@ build/
 .coverage
 coverage.xml
 .pytest_cache/
+.mypy_cache/
+.ruff_cache/
+site/

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

@@ -4,6 +4,99 @@ 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.2.0] - 2026-10-01
+
+### Added
+
+- Quality gates (`agentflow.prebuilt`): `add_quality_gate(g, name, evaluator,
+  *, on_pass, on_fail, on_escalate, max_attempts=3)` adds a checked
+  accept/revise/escalate checkpoint built from a conditional edge and a
+  per-gate attempt counter. An evaluator returns a `GateResult(passed, score,
+  reasons, feedback)`; mix `GateState` into a schema for the `gate_attempts`
+  and `gate_results` channels. All three routes are required so a gate never
+  silently ships a failing artifact once attempts run out.
+- `GateEvent` (`agentflow.events`): a gate emits `started` / `passed` /
+  `failed` / `escalated` via `ctx.emit`, so `RunMetrics`, `JsonlTelemetry`, and
+  the run stream show every gate decision. `Context.emit` now accepts a
+  backend event or a `GateEvent`.
+- Idempotency helpers (`agentflow.prebuilt`): `skip_if_done(node, store, *,
+  namespace, key_from, ttl=None)` runs a node once per distinct key and serves
+  the cached update from a `Store` thereafter; `artifact_key(value)` is a
+  stable content hash to key it by.
+- Structured interrupt-payload convention (`agentflow.interrupts`):
+  `QualityGateReview` and `ClarificationRequest` (each with `.to_payload()`
+  carrying a `type` discriminator) plus `interrupt_type(payload)`, generalizing
+  the `PermissionRequest` shape so a UI or control plane can render any pause.
+- Docs: "Quality gates" and "Long-running loops" chapters, a generated API
+  reference (mkdocstrings), and the `examples/quality_gate.py` and
+  `examples/research_plan_implement_review.py` examples.
+
+- Atomic conditional write on `Store`: `put(..., if_absent=True)` creates only
+  if no live item exists at the key, else raises the new `StoreConflict` (an
+  expired item counts as absent and can be reclaimed). Implemented for
+  `MemoryStore` (atomic within a process) and `PostgresStore` (atomic across
+  processes via a single conditional `INSERT`). This is the store-level
+  primitive for a single-flight claim.
+- Effect-level idempotency (`agentflow.prebuilt`): `IdempotentOp(store,
+  namespace)` protects one side effect inside a node with an atomic claim → run
+  → commit in a `Store`, so a resume or retry does not repeat it, and two
+  workers racing the same key give one winner and one conflict (the
+  duplicate-starter race is closed within a backend). Its `on_incomplete` policy
+  (`"error"` default, `"rerun"`, `"skip"`) handles a prior attempt left
+  `in_flight`, and `on_error` (`"keep"` default, `"release"`) controls the
+  marker when `fn` raises — because an exception does not prove the effect was
+  skipped (a lost response after a successful `POST`). `effect_key(*parts)`
+  builds a stable token to pass downstream as the provider's idempotency key.
+  New `IncompleteEffectError`. This narrows the duplicate window and makes every
+  ambiguous case explicit, but does not by itself guarantee exactly-once at the
+  orchestrator layer — the winner can still crash or lose its response inside
+  the effect, so exactly-once ultimately needs idempotency at the effect.
+  Checkpoints alone give only at-least-once, since a super-step is atomic over
+  state only.
+
+### Fixed
+
+- `import agentflow.prebuilt` no longer requires the `ollama`/`httpx` extra.
+  `httpx` is now imported lazily inside `open_stream`, so the `backends`
+  package (and `RetryPolicy`) and the prebuilt patterns load dependency-free;
+  `httpx` is pulled in only when an HTTP stream is actually opened by a
+  concrete LLM backend.
+
+## [0.1.1] - 2026-09-29
+
+### Added
+
+- `Callback(async_fn)` permission policy: asks a human (or any resolver) inline
+  within the same turn and answers the agent's request immediately, without an
+  engine interrupt/resume. This is the correct policy for a persistent-session
+  backend like Kiro — `Interactive` suspends the run and resumes a new turn,
+  which deadlocks a live ACP session that is holding the original turn open
+  awaiting the decision. `Interactive` remains right for one-shot backends.
+- Permission policy is now translated to CLI launch flags for the one-shot
+  agents (best-effort upfront enforcement, since they have no per-tool runtime
+  gate): `CodexBackend` derives `--sandbox` (`AllowAll` → `workspace-write`,
+  `DenyAll`/`ToolAllowlist` → `read-only`); `ClaudeCodeBackend` derives
+  `--allowed-tools` from a `ToolAllowlist` and `--permission-mode plan` from
+  `DenyAll`. An explicit `sandbox=`/`allowed_tools=`/`permission_mode=` you pass
+  always wins over the derived value.
+
+### Changed
+
+- `CodexBackend(sandbox=...)` now defaults to `None` (derive from the policy)
+  instead of `"read-only"`. With `permission=AllowAll()` this means Codex now
+  launches `workspace-write` rather than `read-only`; pass `sandbox="read-only"`
+  explicitly to keep the old behavior.
+
+### Fixed
+
+- `KiroBackend` now extracts the tool name from the v3 permission request
+  (`_meta.kiro.toolId` / `consent.capability` / `toolCall.title`), so a
+  `PermissionRequest` no longer arrives with an empty `tool`.
+- `KiroBackend.close()` returns promptly (short per-phase grace, configurable
+  via `close_grace`) and signals the child's whole process group, so the v3
+  CLI's helper process (`kiro-cli-chat`) is reaped instead of stranding the
+  terminal.
+
 ## [0.1.0] - 2026-09-29
 
 First public release: an async-first, LangGraph-style SDK for agent workflows
@@ -165,4 +258,5 @@ Core engine (the foundation the above builds on):
   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.1]: https://github.com/dankosorkin/agent-workflow-sdk/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/dankosorkin/agent-workflow-sdk/releases/tag/v0.1.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-workflow-sdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: Async-first, LangGraph-style SDK for building agent workflows with pluggable agent and LLM backends.
 Project-URL: Homepage, https://github.com/dankosorkin/agent-workflow-sdk
 Project-URL: Repository, https://github.com/dankosorkin/agent-workflow-sdk
@@ -27,6 +27,9 @@ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
 Provides-Extra: ollama
 Requires-Dist: httpx>=0.27; extra == 'ollama'
 Provides-Extra: otel
@@ -284,25 +287,28 @@ machine (set `KIRO_AGENT` to a valid agent id, e.g. `vibe`, to include Kiro).
 A `PermissionPolicy` is **required** when constructing an agent backend — there
 is no default, because auto-approving an agent's tool use is a security choice
 the caller must make explicitly. Options: `AllowAll` (trusted local sandbox
-only), `DenyAll`, `Interactive` (escalate to a human via an engine interrupt),
-or `ToolAllowlist({"read_file", ...}, fallback=DenyAll())` for least-privilege
-scoping.
+only), `DenyAll`, `ToolAllowlist({"read_file", ...}, fallback=DenyAll())` for
+least-privilege scoping, and two ways to ask a human — `Interactive` (suspends
+the run via an engine interrupt; resume with a decision) and `Callback(async
+fn)` (asks inline within the same turn, no interrupt — the right choice for a
+persistent-session backend like Kiro).
 
 ```python
 from agentflow.backends import AllowAll, ToolAllowlist, DenyAll
 KiroBackend("vibe", permission=ToolAllowlist({"read_file"}, fallback=DenyAll()))
 ```
 
-Capability matrix — where the policy actually applies:
+Capability matrix — how the policy is applied:
 
-| Backend | Routes tool requests through `PermissionPolicy`? |
+| Backend | How `PermissionPolicy` applies |
 | --- | --- |
-| `KiroBackend` | Yes — ACP `session/request_permission` is resolved by the policy (and `Interactive` drives a real HITL interrupt). |
-| `CodexBackend` | No — one-shot CLI; permission is governed by its `--sandbox` mode. The policy field is still required but does not intercept prompts. |
-| `ClaudeCodeBackend` | No — one-shot CLI; permission is governed by CLI flags (`--permission-mode`, `--allowed-tools`). |
+| `KiroBackend` | Runtime gate — ACP `session/request_permission` is resolved by the policy per tool call (`Interactive`/`Callback` ask a human; `ToolAllowlist` filters). |
+| `CodexBackend` | Translated to a launch flag — the policy sets Codex's `--sandbox` when you don't set it yourself: `AllowAll` → `workspace-write`, `DenyAll`/`ToolAllowlist` → `read-only`. No per-tool runtime gate. |
+| `ClaudeCodeBackend` | Translated to launch flags — `ToolAllowlist` → `--allowed-tools`, `DenyAll` → `--permission-mode plan` (read-only), when you don't set those yourself. No per-tool runtime gate. |
 
-For the one-shot CLI agents, configure their own controls (sandbox, allowed
-tools) — the SDK policy alone does not sandbox them.
+For the one-shot CLI agents the policy is a best-effort *upfront* mapping to
+their own controls, not our runtime interception — an explicit `sandbox=` /
+`allowed_tools=` you pass always wins over the derived value.
 
 ## Checkpointing and human-in-the-loop
 

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/README.md

@@ -242,25 +242,28 @@ machine (set `KIRO_AGENT` to a valid agent id, e.g. `vibe`, to include Kiro).
 A `PermissionPolicy` is **required** when constructing an agent backend — there
 is no default, because auto-approving an agent's tool use is a security choice
 the caller must make explicitly. Options: `AllowAll` (trusted local sandbox
-only), `DenyAll`, `Interactive` (escalate to a human via an engine interrupt),
-or `ToolAllowlist({"read_file", ...}, fallback=DenyAll())` for least-privilege
-scoping.
+only), `DenyAll`, `ToolAllowlist({"read_file", ...}, fallback=DenyAll())` for
+least-privilege scoping, and two ways to ask a human — `Interactive` (suspends
+the run via an engine interrupt; resume with a decision) and `Callback(async
+fn)` (asks inline within the same turn, no interrupt — the right choice for a
+persistent-session backend like Kiro).
 
 ```python
 from agentflow.backends import AllowAll, ToolAllowlist, DenyAll
 KiroBackend("vibe", permission=ToolAllowlist({"read_file"}, fallback=DenyAll()))
 ```
 
-Capability matrix — where the policy actually applies:
+Capability matrix — how the policy is applied:
 
-| Backend | Routes tool requests through `PermissionPolicy`? |
+| Backend | How `PermissionPolicy` applies |
 | --- | --- |
-| `KiroBackend` | Yes — ACP `session/request_permission` is resolved by the policy (and `Interactive` drives a real HITL interrupt). |
-| `CodexBackend` | No — one-shot CLI; permission is governed by its `--sandbox` mode. The policy field is still required but does not intercept prompts. |
-| `ClaudeCodeBackend` | No — one-shot CLI; permission is governed by CLI flags (`--permission-mode`, `--allowed-tools`). |
+| `KiroBackend` | Runtime gate — ACP `session/request_permission` is resolved by the policy per tool call (`Interactive`/`Callback` ask a human; `ToolAllowlist` filters). |
+| `CodexBackend` | Translated to a launch flag — the policy sets Codex's `--sandbox` when you don't set it yourself: `AllowAll` → `workspace-write`, `DenyAll`/`ToolAllowlist` → `read-only`. No per-tool runtime gate. |
+| `ClaudeCodeBackend` | Translated to launch flags — `ToolAllowlist` → `--allowed-tools`, `DenyAll` → `--permission-mode plan` (read-only), when you don't set those yourself. No per-tool runtime gate. |
 
-For the one-shot CLI agents, configure their own controls (sandbox, allowed
-tools) — the SDK policy alone does not sandbox them.
+For the one-shot CLI agents the policy is a best-effort *upfront* mapping to
+their own controls, not our runtime interception — an explicit `sandbox=` /
+`allowed_tools=` you pass always wins over the derived value.
 
 ## Checkpointing and human-in-the-loop
 

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/agentflow/__init__.py

@@ -55,12 +55,15 @@ from agentflow.errors import (
     NodeError,
     RunNotFound,
     RunTimeout,
+    StoreConflict,
+    StoreError,
 )
 from agentflow.events import (
     Allow,
     ChatRequest,
     Deny,
     ErrorEvent,
+    GateEvent,
     Message,
     PermissionOption,
     PermissionRequest,
@@ -73,6 +76,11 @@ from agentflow.events import (
     TurnEnd,
 )
 from agentflow.graph import END, START, Graph, Node, Router
+from agentflow.interrupts import (
+    ClarificationRequest,
+    QualityGateReview,
+    interrupt_type,
+)
 from agentflow.observability import Hooks, NodeStat, RunMetrics
 from agentflow.redaction import RedactKeys, Redactor, redact_none
 from agentflow.runtime import Context, StreamEvent
@@ -89,7 +97,7 @@ from agentflow.state import (
 from agentflow.store import Item, MemoryStore, Store
 from agentflow.telemetry import JsonlTelemetry, MultiHooks
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "__version__",
@@ -133,8 +141,13 @@ __all__ = [
     "PermissionOption",
     "TurnEnd",
     "ErrorEvent",
+    "GateEvent",
     "Allow",
     "Deny",
+    # human-in-the-loop interrupt payloads
+    "QualityGateReview",
+    "ClarificationRequest",
+    "interrupt_type",
     # checkpointing
     "Checkpoint",
     "Checkpointer",
@@ -171,6 +184,8 @@ __all__ = [
     "BackendRateLimitError",
     "CheckpointError",
     "CheckpointConflict",
+    "StoreError",
+    "StoreConflict",
     "ControlPlaneError",
     "RunNotFound",
     "InterruptError",

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/agentflow/backends/_http.py

@@ -41,12 +41,13 @@ from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from datetime import UTC, datetime
-from typing import Any
-
-import httpx
+from typing import TYPE_CHECKING, Any
 
 from agentflow.errors import BackendRateLimitError, BackendTransportError
 
+if TYPE_CHECKING:
+    import httpx
+
 __all__ = ["RetryPolicy", "open_stream"]
 
 _RETRYABLE_STATUS = frozenset({408, 409, 425, 429, 500, 502, 503, 504})
@@ -117,6 +118,8 @@ async def open_stream(
     """
     pol = policy or RetryPolicy(max_retries=0)
     # Resolve the sleeper at call time so tests can monkeypatch asyncio.sleep.
+    import httpx  # local: keep RetryPolicy importable without the http extra
+
     if sleep is None:
         sleep = asyncio.sleep
     attempt = 0

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/agentflow/backends/base.py

@@ -25,7 +25,8 @@ This module imports only :mod:`agentflow.events` and
 
 from __future__ import annotations
 
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import dataclass
 from typing import Any, Protocol, runtime_checkable
 
 from agentflow.errors import InterruptError
@@ -50,7 +51,10 @@ __all__ = [
     "AllowAll",
     "DenyAll",
     "Interactive",
+    "Callback",
     "ToolAllowlist",
+    "PolicyIntent",
+    "policy_intent",
 ]
 
 
@@ -311,6 +315,36 @@ class Interactive:
         return _normalize_decision(answer)
 
 
+class Callback:
+    """Ask a human (or any resolver) inline, without interrupting the graph.
+
+    Unlike :class:`Interactive` — which suspends the whole run via
+    ``ctx.interrupt`` and requires a separate ``resume()`` — this awaits a
+    caller-supplied async function *within the same turn* and answers the
+    agent's permission request immediately. That matters for a persistent
+    session backend (Kiro's ACP): the agent is holding one turn open waiting
+    for the decision, so the answer must go back in that turn rather than
+    abandoning it and starting a new one.
+
+    ``resolver`` is ``async (PermissionRequest) -> decision`` where the
+    decision is an :class:`Allow`/:class:`Deny`, or a value normalized the same
+    way as a resume value (``"y"``/``"n"``, ``None``, an option id, ...).
+
+        async def ask(req):
+            answer = await asyncio.to_thread(input, f"allow {req.tool}? [y/N] ")
+            return answer
+
+        backend = KiroBackend("vibe", permission=Callback(ask))
+    """
+
+    def __init__(self, resolver: Callable[[PermissionRequest], Awaitable[Any]]) -> None:
+        self._resolver = resolver
+
+    async def decide(self, req: PermissionRequest) -> PermissionDecision:
+        answer = await self._resolver(req)
+        return _normalize_decision(answer)
+
+
 def _normalize_decision(answer: Any) -> PermissionDecision:
     """Coerce a human's resume value into a PermissionDecision."""
     if isinstance(answer, (Allow, Deny)):
@@ -325,3 +359,46 @@ def _normalize_decision(answer: Any) -> PermissionDecision:
     if answer is None or answer is False:
         return Deny()
     return Allow()
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyIntent:
+    """A backend-agnostic reading of a permission policy, for CLI backends.
+
+    The one-shot CLI agents (Codex, Claude Code) do not surface per-tool
+    permission requests we can gate at runtime — they enforce permissions via
+    their own launch flags. This distils a :class:`PermissionPolicy` into an
+    upfront intent those backends can translate to flags:
+
+    - ``deny_all``: the policy denies everything (``DenyAll``, or an empty
+      ``ToolAllowlist`` whose fallback denies) — launch as restrictively as the
+      CLI allows.
+    - ``allow_all``: the policy approves everything (``AllowAll``).
+    - ``allowlist``: the explicit set of permitted tools (``ToolAllowlist``),
+      or ``None`` when the policy is not an allowlist.
+
+    An ``Interactive``/``Callback`` policy has no static answer (it needs a
+    live request), so it reads as neither allow_all nor deny_all — the CLI's
+    own default applies. This is a best-effort mapping, not our runtime gate;
+    the CLI's controls are authoritative.
+    """
+
+    deny_all: bool = False
+    allow_all: bool = False
+    allowlist: frozenset[str] | None = None
+
+
+def policy_intent(policy: PermissionPolicy) -> PolicyIntent:
+    """Best-effort static reading of ``policy`` for CLI-flag translation."""
+    if isinstance(policy, AllowAll):
+        return PolicyIntent(allow_all=True)
+    if isinstance(policy, DenyAll):
+        return PolicyIntent(deny_all=True)
+    if isinstance(policy, ToolAllowlist):
+        allowed = frozenset(policy.allowed)
+        # An empty allowlist with a denying fallback means "deny everything".
+        if not allowed and isinstance(policy.fallback, DenyAll):
+            return PolicyIntent(deny_all=True, allowlist=allowed)
+        return PolicyIntent(allowlist=allowed)
+    # Interactive / Callback / custom: no static answer.
+    return PolicyIntent()

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/agentflow/backends/claude_code.py

@@ -35,7 +35,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any
 
-from agentflow.backends.base import PermissionPolicy
+from agentflow.backends.base import PermissionPolicy, policy_intent
 from agentflow.backends.cli_exec import CLIExecBackend, TurnAccumulator
 from agentflow.events import BackendEvent, TextChunk, ToolCall
 
@@ -102,12 +102,26 @@ class ClaudeCodeBackend(CLIExecBackend):
             cmd += ["--model", self.model]
         if self.agent:
             cmd += ["--agent", self.agent]
-        if self.allowed_tools:
-            cmd += ["--allowed-tools", " ".join(self.allowed_tools)]
+
+        # Explicit tool flags win; otherwise derive them from the permission
+        # policy. Claude Code has no per-tool runtime gate we can hook, so a
+        # ToolAllowlist maps to --allowed-tools and a deny-all policy maps to
+        # the read-only "plan" permission mode (no edits/commands).
+        allowed = list(self.allowed_tools)
+        permission_mode = self.permission_mode
+        if not allowed and permission_mode is None:
+            intent = policy_intent(self.permission)
+            if intent.allowlist is not None and intent.allowlist:
+                allowed = sorted(intent.allowlist)
+            elif intent.deny_all:
+                permission_mode = "plan"
+
+        if allowed:
+            cmd += ["--allowed-tools", " ".join(allowed)]
         if self.disallowed_tools:
             cmd += ["--disallowed-tools", " ".join(self.disallowed_tools)]
-        if self.permission_mode:
-            cmd += ["--permission-mode", self.permission_mode]
+        if permission_mode:
+            cmd += ["--permission-mode", permission_mode]
         if self.skip_permissions:
             cmd.append("--allow-dangerously-skip-permissions")
         if session_id:

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/agentflow/backends/codex.py

@@ -32,7 +32,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Literal
 
-from agentflow.backends.base import PermissionPolicy
+from agentflow.backends.base import PermissionPolicy, policy_intent
 from agentflow.backends.cli_exec import CLIExecBackend, TurnAccumulator
 from agentflow.events import BackendEvent, TextChunk, ToolCall, ToolResult
 
@@ -46,7 +46,7 @@ class CodexBackend(CLIExecBackend):
         self,
         *,
         model: str | None = None,
-        sandbox: str = "read-only",
+        sandbox: str | None = None,
         skip_git_repo_check: bool = True,
         cwd: Path | str = ".",
         permission: PermissionPolicy,
@@ -55,16 +55,34 @@ class CodexBackend(CLIExecBackend):
     ) -> None:
         super().__init__(cwd=cwd, permission=permission, timeout=timeout)
         self.model = model
+        # ``sandbox`` explicitly set by the caller always wins. When left None
+        # it is derived from the permission policy: a deny-all / allowlist
+        # policy launches Codex ``read-only`` (Codex has no per-tool gate, so
+        # this is the closest upfront enforcement), while AllowAll permits
+        # workspace writes. See _effective_sandbox.
         self.sandbox = sandbox
         self.skip_git_repo_check = skip_git_repo_check
         self.extra_args = list(extra_args or [])
 
+    def _effective_sandbox(self) -> str:
+        if self.sandbox is not None:
+            return self.sandbox  # explicit caller choice wins
+        intent = policy_intent(self.permission)
+        if intent.allow_all:
+            return "workspace-write"
+        if intent.deny_all or intent.allowlist is not None:
+            return "read-only"
+        # Interactive/Callback/custom: no static answer — default to the safe
+        # read-only sandbox rather than granting writes implicitly.
+        return "read-only"
+
     def build_command(self, prompt: str, session_id: str | None) -> list[str]:
         cmd = ["codex", "exec", "--json"]
         if self.skip_git_repo_check:
             cmd.append("--skip-git-repo-check")
-        if self.sandbox:
-            cmd += ["-s", self.sandbox]
+        sandbox = self._effective_sandbox()
+        if sandbox:
+            cmd += ["-s", sandbox]
         if self.model:
             cmd += ["-m", self.model]
         cmd += self.extra_args

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/agentflow/backends/kiro.py

@@ -30,6 +30,8 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import json
+import os
+import signal
 from collections.abc import AsyncIterator
 from pathlib import Path
 from typing import Any, Literal
@@ -67,12 +69,18 @@ class KiroBackend(BaseAgentBackend):
         engine: str = "v3",
         cwd: Path | str = _DEFAULT_CWD,
         permission: PermissionPolicy,
+        close_grace: float = 0.5,
     ) -> None:
         super().__init__(permission=permission)
         self.agent = agent
         self.model = model
         self.engine = engine
         self.cwd = Path(cwd)
+        # Per-phase grace on close(): wait this long for a clean exit, then
+        # terminate, then (after another grace) kill. Kept short because the
+        # v3 engine typically will not exit on stdin close, and we should not
+        # block a caller's shutdown for seconds waiting on it.
+        self._close_grace = close_grace
 
         self._proc: asyncio.subprocess.Process | None = None
         self._session_id: str | None = None
@@ -114,6 +122,12 @@ class KiroBackend(BaseAgentBackend):
                 # ACP responses (e.g. session/new listing every available mode)
                 # can exceed asyncio's 64KiB default readline buffer; raise it.
                 limit=8 * 1024 * 1024,
+                # Put kiro-cli in its own process group so close() can signal
+                # the whole tree. The v3 CLI spawns a child (kiro-cli-chat)
+                # that outlives a kill of the parent alone, stranding the
+                # terminal; killing the group reaps it too. POSIX-only —
+                # ignored on platforms without it.
+                start_new_session=True,
             )
         except OSError as exc:
             raise BackendTransportError(f"could not start kiro-cli: {exc}") from exc
@@ -133,14 +147,20 @@ class KiroBackend(BaseAgentBackend):
         try:
             if proc.stdin and not proc.stdin.is_closing():
                 proc.stdin.close()
+            # The v3 engine often does not exit on stdin close (it waits on its
+            # own idle timeout), so don't block for seconds hoping it will.
+            # Give it a short grace to exit cleanly, then signal the whole
+            # process group (SIGTERM, then SIGKILL) so the CLI's child process
+            # (kiro-cli-chat) is reaped too, not just the parent. Each phase
+            # has a brief window so close() returns promptly.
             try:
-                await asyncio.wait_for(proc.wait(), timeout=3)
+                await asyncio.wait_for(proc.wait(), timeout=self._close_grace)
             except TimeoutError:
-                proc.terminate()
+                self._signal_group(proc, signal.SIGTERM)
                 try:
-                    await asyncio.wait_for(proc.wait(), timeout=2)
+                    await asyncio.wait_for(proc.wait(), timeout=self._close_grace)
                 except TimeoutError:
-                    proc.kill()
+                    self._signal_group(proc, signal.SIGKILL)
         finally:
             if self._reader_task:
                 self._reader_task.cancel()
@@ -149,6 +169,26 @@ class KiroBackend(BaseAgentBackend):
             self._proc = None
             self._fail_pending(BackendTransportError("backend closed"))
 
+    @staticmethod
+    def _signal_group(proc: asyncio.subprocess.Process, sig: int) -> None:
+        """Send ``sig`` to the child's whole process group, if possible.
+
+        The child was started with ``start_new_session=True`` so it leads its
+        own group; signalling ``-pgid`` reaches its descendants too. Falls back
+        to signalling just the process where process groups aren't available
+        (e.g. Windows) or the group has already gone. Never raises.
+        """
+        with contextlib.suppress(ProcessLookupError, PermissionError, OSError, AttributeError):
+            pgid = os.getpgid(proc.pid)
+            os.killpg(pgid, sig)
+            return
+        # Fallback: signal the process directly.
+        with contextlib.suppress(ProcessLookupError, OSError):
+            if sig == signal.SIGKILL:
+                proc.kill()
+            else:
+                proc.terminate()
+
     # ------------------------------------------------------------------
     # Public API — one turn as an event stream
     # ------------------------------------------------------------------
@@ -412,7 +452,7 @@ class KiroBackend(BaseAgentBackend):
         )
         req = PermissionRequest(
             id=str(request_id),
-            tool=params.get("toolName") or params.get("tool") or "",
+            tool=_extract_tool_name(params),
             options=options,
             detail=params,
         )
@@ -508,6 +548,30 @@ class KiroBackend(BaseAgentBackend):
             queue.put_nowait(event)
 
 
+def _extract_tool_name(params: dict[str, Any]) -> str:
+    """Pull the tool name out of a session/request_permission payload.
+
+    Kiro v3 does not use ``toolName``/``tool``; it puts the machine name under
+    ``_meta.kiro.toolId`` (and ``_meta.kiro.consent.capability``) and a
+    human-readable label under ``toolCall.title``. Fall back through those,
+    then to the legacy flat keys, so older shapes still work.
+    """
+    meta = params.get("_meta")
+    if isinstance(meta, dict):
+        kiro_meta = meta.get("kiro")
+        if isinstance(kiro_meta, dict):
+            tool_id = kiro_meta.get("toolId")
+            if tool_id:
+                return str(tool_id)
+            consent = kiro_meta.get("consent")
+            if isinstance(consent, dict) and consent.get("capability"):
+                return str(consent["capability"])
+    tool_call = params.get("toolCall")
+    if isinstance(tool_call, dict) and tool_call.get("title"):
+        return str(tool_call["title"])
+    return params.get("toolName") or params.get("tool") or ""
+
+
 def _map_status(status: Any) -> Literal["ok", "error", "pending"]:
     if status in ("completed", "success", "ok"):
         return "ok"

{agent_workflow_sdk-0.1.0 → agent_workflow_sdk-0.2.0}/agentflow/errors.py

@@ -31,6 +31,8 @@ __all__ = [
     "BackendRateLimitError",
     "CheckpointError",
     "CheckpointConflict",
+    "StoreError",
+    "StoreConflict",
     "ControlPlaneError",
     "RunNotFound",
     "InterruptError",
@@ -138,6 +140,22 @@ class CheckpointConflict(CheckpointError):
         )
 
 
+class StoreError(AgentFlowError):
+    """A store operation could not be completed."""
+
+
+class StoreConflict(StoreError):
+    """A conditional store write (``put(..., if_absent=True)``) failed because a
+    live item already exists at ``(namespace, key)`` — another writer claimed it
+    first. The loser re-reads and reacts (e.g. treats the effect as already
+    in-flight or done). This is what makes a claim an atomic single-flight."""
+
+    def __init__(self, namespace: tuple[str, ...], key: str):
+        self.namespace = namespace
+        self.key = key
+        super().__init__(f"store conflict: {key!r} under {namespace} already exists")
+
+
 class RunTimeout(GraphError):
     """A whole-run timeout fired before the graph reached END.