langgraph-stream-parser 0.4.0__tar.gz → 0.5.0__tar.gz

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.5.0}/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
         include:
           # One Windows job for cross-platform coverage (primary dev env).
           - os: windows-latest

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.5.0}/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.5.0] - 2026-06-14
+
+An **async task-delegation engine** — the reusable core behind a "delegate a
+task, it runs in the background, track it on a board" surface. Single-process,
+dependency-free; surfaces provide a concrete store.
+
+### Added
+- **`langgraph_stream_parser.tasks`** — `TaskRunner` (an asyncio worker pool that
+  drives the shared `SessionAdapter`), a `TaskStore` protocol with a dependency-free
+  `InMemoryTaskStore` reference impl, the `Task` record + `TaskState` machine
+  (`queued → ongoing → review_needed → done/failed/cancelled`), and
+  `set_runner`/`get_runner` so agent tools can reach the runner.
+  `enqueue()` returns a `task_id` immediately (non-blocking); workers run each
+  task as its own session and transition it by the run's outcome; `cancel`,
+  `resume` (HITL), and `retry` round out the controls; orphaned `ongoing` tasks
+  are requeued on `start()`.
+- **`Session.outcome`** (+ `Session.interrupt` / `Session.error`) — a typed
+  terminal-outcome signal set by the session adapter
+  (`complete | interrupted | error | cancelled`). Headless consumers read this
+  instead of re-inspecting the event stream. Correctly distinguishes a HITL
+  pause from completion (the parser always emits a trailing `CompleteEvent`,
+  even after an interrupt).
+
+### Fixed
+- `__version__` was stale at `0.2.1` (pyproject was already ahead); now `0.5.0`.
+
+### Notes
+- Additive and dependency-free. The engine depends only on the `TaskStore`
+  protocol and the public `SessionAdapter` surface, so a surface can back it
+  with any store (in-memory, SQLite, …) and later graduate to a remote Agent
+  Protocol server without changing the engine.
+
+## [0.4.1] - 2026-06-14
+
+AG-UI bridge robustness — an edge-case audit (`tests/test_agui_matrix.py`, run against purpose-built tool-calling / interrupting / erroring / checkpointer-less agents) surfaced three real issues, now fixed:
+
+### Fixed
+- **Graphs compiled without a checkpointer no longer hard-crash.** The AG-UI adapter calls `graph.aget_state()`, which raises `No checkpointer set` — common for plain user graphs. `build_agent()` now auto-attaches an in-memory checkpointer when the graph lacks one (AG-UI needs threaded state for interrupts/resume regardless).
+- **Agent exceptions mid-run now emit a terminal `RUN_ERROR`** instead of silently killing the stream / unhandled 500. The endpoint is now a resilient wrapper around the agent run.
+
+### Verified (was previously only claimed)
+- Tool calls map to `TOOL_CALL_START`/`ARGS`/`END` + `TOOL_CALL_RESULT`.
+- Interrupts surface as a `CUSTOM` `on_interrupt` event; resume via `forwardedProps.command.resume` continues the run (HITL round-trip).
+- Multi-turn thread state persists; concurrent requests are isolated (per-request agent clone). Note: AG-UI clients must use **unique message ids** per turn — the adapter dedupes by id.
+
 ## [0.4.0] - 2026-06-14
 
 Adopt **AG-UI** for the wire (see `docs/adr/0001-adopt-ag-ui-for-the-wire.md`).

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: langgraph-stream-parser
-Version: 0.4.0
-Summary: Universal parser + host layer for LangGraph agents — typed stream events, agent-spec loading, layered config, and an AG-UI bridge
+Version: 0.5.0
+Summary: Universal parser + host layer for LangGraph agents — typed stream events, agent-spec loading, layered config, an AG-UI bridge, and an async task-delegation engine
 Project-URL: Homepage, https://github.com/dkedar7/langgraph-stream-parser
 Project-URL: Documentation, https://github.com/dkedar7/langgraph-stream-parser#readme
 Project-URL: Repository, https://github.com/dkedar7/langgraph-stream-parser
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.5.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "langgraph-stream-parser"
-version = "0.4.0"
-description = "Universal parser + host layer for LangGraph agents — typed stream events, agent-spec loading, layered config, and an AG-UI bridge"
+version = "0.5.0"
+description = "Universal parser + host layer for LangGraph agents — typed stream events, agent-spec loading, layered config, an AG-UI bridge, and an async task-delegation engine"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.11"
@@ -24,6 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.5.0}/src/langgraph_stream_parser/__init__.py

@@ -57,6 +57,16 @@ from .extractors.builtins import (
 )
 from .resume import create_resume_input, prepare_agent_input
 from .host import load_agent_spec, HostConfig, Workspace
+from .tasks import (
+    TaskRunner,
+    TaskStore,
+    InMemoryTaskStore,
+    Task,
+    TaskState,
+    set_runner,
+    get_runner,
+    outcome_to_state,
+)
 from .compat import (
     stream_graph_updates,
     astream_graph_updates,
@@ -64,7 +74,7 @@ from .compat import (
     aresume_graph_from_interrupt,
 )
 
-__version__ = "0.2.1"
+__version__ = "0.5.0"
 
 __all__ = [
     # Main parser
@@ -98,6 +108,15 @@ __all__ = [
     "load_agent_spec",
     "HostConfig",
     "Workspace",
+    # Task-delegation engine
+    "TaskRunner",
+    "TaskStore",
+    "InMemoryTaskStore",
+    "Task",
+    "TaskState",
+    "set_runner",
+    "get_runner",
+    "outcome_to_state",
     # Serialization
     "event_to_dict",
     # Legacy/compat functions

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.5.0}/src/langgraph_stream_parser/adapters/session.py

@@ -23,7 +23,7 @@ import uuid
 from datetime import datetime
 from typing import Any, AsyncIterator
 
-from ..events import CompleteEvent, ErrorEvent, event_to_dict
+from ..events import CompleteEvent, ErrorEvent, InterruptEvent, event_to_dict
 from ..parser import StreamParser
 from ..resume import create_resume_input, prepare_agent_input
 
@@ -38,6 +38,19 @@ class Session:
         self.current_task: asyncio.Task | None = None
         self.sse_connected: bool = False
         self.created_at: datetime = datetime.now()
+        # Typed terminal outcome of the most recent turn, set by ``_produce``.
+        # One of ``"complete" | "interrupted" | "error" | "cancelled"``, or
+        # ``None`` before the first turn finishes. Headless consumers (e.g. a
+        # task runner) read this instead of re-inspecting the event stream to
+        # tell whether a turn finished, paused on a HITL interrupt, or failed.
+        self.outcome: str | None = None
+        # When ``outcome == "interrupted"``, the serialized InterruptEvent
+        # (``{"type": "interrupt", "action_requests": [...], ...}``) that paused
+        # the turn — everything a consumer needs to render a review gate and
+        # build resume decisions. ``None`` otherwise.
+        self.interrupt: dict[str, Any] | None = None
+        # When ``outcome in {"error"}``, a human-readable error string.
+        self.error: str | None = None
 
     def cancel_current(self) -> bool:
         """Cancel the in-flight turn if any. Returns True if one was cancelled."""
@@ -192,8 +205,18 @@ class SessionAdapter:
         return session
 
     async def _produce(self, session: Session, input_data: Any) -> None:
-        """Run one turn, pushing serialized events onto the session queue."""
+        """Run one turn, pushing serialized events onto the session queue.
+
+        Also records the turn's terminal outcome on the session
+        (``session.outcome`` + ``session.interrupt`` / ``session.error``) so
+        headless consumers don't have to re-inspect the event stream.
+        """
         parser = StreamParser(stream_mode=self._stream_mode, **self._parser_kwargs)
+        # Fresh turn → clear any prior outcome.
+        session.outcome = None
+        session.interrupt = None
+        session.error = None
+        pending_interrupt: dict[str, Any] | None = None
         try:
             stream = self._graph.astream(
                 input_data,
@@ -201,14 +224,33 @@ class SessionAdapter:
                 stream_mode=self._stream_mode,
             )
             async for event in parser.aparse(stream):
-                session.push(event_to_dict(event, max_result_len=self._max_result_len))
-                # Terminal events end the turn; the parser emits exactly one.
-                if isinstance(event, (CompleteEvent, ErrorEvent)):
+                data = event_to_dict(event, max_result_len=self._max_result_len)
+                session.push(data)
+                if isinstance(event, InterruptEvent):
+                    # The graph paused for HITL. The parser still emits a
+                    # trailing CompleteEvent when the stream ends, so remember
+                    # the interrupt and reinterpret that Complete below.
+                    pending_interrupt = data
+                elif isinstance(event, ErrorEvent):
+                    session.outcome = "error"
+                    session.error = event.error
+                    return
+                elif isinstance(event, CompleteEvent):
+                    # A Complete that follows an interrupt means "paused",
+                    # not "finished" — distinguish the two for consumers.
+                    if pending_interrupt is not None:
+                        session.outcome = "interrupted"
+                        session.interrupt = pending_interrupt
+                    else:
+                        session.outcome = "complete"
                     return
         except asyncio.CancelledError:
+            session.outcome = "cancelled"
             session.push({"type": "cancelled"})
             raise
         except Exception as exc:  # noqa: BLE001 — surfaced to the client, not swallowed
+            session.outcome = "error"
+            session.error = f"{type(exc).__name__}: {exc}"
             session.push({"type": "error", "error": f"{type(exc).__name__}: {exc}"})
 
     # ── Consuming (SSE) ──────────────────────────────────────────────

{langgraph_stream_parser-0.4.0 → langgraph_stream_parser-0.5.0}/src/langgraph_stream_parser/agui/__init__.py

@@ -24,8 +24,9 @@ Quick start::
     from langgraph_stream_parser.agui import build_app
     app = build_app(my_compiled_graph)   # an ASGI app; run with uvicorn
 """
-from __future__ import annotations
-
+# NB: intentionally NOT `from __future__ import annotations`. The resilient
+# endpoint below needs real (non-string) annotations so FastAPI can resolve
+# RunAgentInput as the request body; PEP 604 unions work natively on >=3.11.
 from typing import Any
 
 __all__ = ["build_agent", "add_agui_endpoint", "build_app", "serve", "DEFAULT_AGENT_NAME"]
@@ -71,6 +72,17 @@ def build_agent(
         from ag_ui_langgraph import LangGraphAgent
     except ImportError as e:  # pragma: no cover - exercised only without the extra
         raise RuntimeError(_IMPORT_HINT) from e
+    # AG-UI requires threaded state — the adapter calls graph.aget_state() and
+    # supports interrupts/resume, both of which need a checkpointer. Many user
+    # graphs are compiled without one (and would otherwise hard-crash with
+    # "No checkpointer set"), so attach an in-memory default when absent.
+    if getattr(graph, "checkpointer", None) is None:
+        try:
+            from langgraph.checkpoint.memory import InMemorySaver
+
+            graph.checkpointer = InMemorySaver()
+        except Exception:  # pragma: no cover - best-effort; LangGraphAgent will surface real issues
+            pass
     return LangGraphAgent(name=name, graph=graph, description=description, config=config)
 
 
@@ -87,15 +99,53 @@ def add_agui_endpoint(
 
     ``graph`` may be a compiled graph or an already-built ``LangGraphAgent``.
     Returns the same ``app`` for chaining.
+
+    The endpoint is *resilient*: if the agent raises mid-run, a terminal
+    ``RUN_ERROR`` event is emitted and the stream closes cleanly, rather than
+    crashing the connection with an unhandled 500 (the bare upstream adapter
+    lets node exceptions propagate). Each request runs on its own cloned agent.
     """
     try:
-        from ag_ui_langgraph import add_langgraph_fastapi_endpoint
+        from ag_ui.core import EventType, RunAgentInput, RunErrorEvent
+        from ag_ui.encoder import EventEncoder
+        from fastapi import Request
+        from fastapi.responses import StreamingResponse
     except ImportError as e:  # pragma: no cover
         raise RuntimeError(_IMPORT_HINT) from e
+
     agent = graph if _is_langgraph_agent(graph) else build_agent(
         graph, name=name, description=description, config=config
     )
-    add_langgraph_fastapi_endpoint(app, agent, path=path)
+
+    @app.post(path)
+    async def _run(input_data: RunAgentInput, request: Request):
+        accept = request.headers.get("accept")
+        try:
+            encoder = EventEncoder(accept=accept)
+        except TypeError:  # pragma: no cover - older SDKs without the accept kwarg
+            encoder = EventEncoder()
+        media_type = getattr(encoder, "get_content_type", lambda: "text/event-stream")()
+        run_agent = agent.clone()
+
+        async def gen():
+            try:
+                async for ev in run_agent.run(input_data):
+                    # run() yields SSE-encoded strings; encode objects defensively.
+                    yield ev if isinstance(ev, (str, bytes)) else encoder.encode(ev)
+            except Exception as exc:  # noqa: BLE001 - surfaced to the client as RUN_ERROR
+                yield encoder.encode(
+                    RunErrorEvent(
+                        type=EventType.RUN_ERROR,
+                        message=f"{type(exc).__name__}: {exc}",
+                    )
+                )
+
+        return StreamingResponse(gen(), media_type=media_type)
+
+    @app.get(path)
+    async def _health():
+        return {"status": "ok", "agent": {"name": getattr(agent, "name", name)}}
+
     return app
 
 

langgraph_stream_parser-0.5.0/src/langgraph_stream_parser/tasks/__init__.py

@@ -0,0 +1,54 @@
+"""Async task-delegation engine for LangGraph agents.
+
+A small, single-process control plane that lets a host accept tasks, run them
+as background agent sessions, and track them through a four-column board
+(queued → ongoing → review_needed → done/failed/cancelled).
+
+- :class:`TaskRunner` — the worker pool that drives a ``SessionAdapter``.
+- :class:`TaskStore` — the persistence protocol (surfaces provide a concrete
+  store; :class:`InMemoryTaskStore` is a dependency-free reference impl).
+- :data:`TASK_TOOLS` — agent tools so an agent can delegate to copies of
+  itself (added in a later release).
+
+Example:
+    from langgraph_stream_parser import SessionAdapter
+    from langgraph_stream_parser.tasks import TaskRunner, InMemoryTaskStore
+
+    runner = TaskRunner(adapter, InMemoryTaskStore(), concurrency=3)
+    await runner.start()
+    task_id = await runner.enqueue(title="research", prompt="...")
+"""
+from __future__ import annotations
+
+from .runner import TaskRunner, get_runner, set_runner
+from .state import (
+    CANCELLED,
+    DONE,
+    FAILED,
+    ONGOING,
+    QUEUED,
+    REVIEW_NEEDED,
+    TERMINAL_STATES,
+    TaskState,
+    outcome_to_state,
+)
+from .store import InMemoryTaskStore, Task, TaskStore, now_iso
+
+__all__ = [
+    "TaskRunner",
+    "set_runner",
+    "get_runner",
+    "TaskStore",
+    "InMemoryTaskStore",
+    "Task",
+    "now_iso",
+    "TaskState",
+    "outcome_to_state",
+    "TERMINAL_STATES",
+    "QUEUED",
+    "ONGOING",
+    "REVIEW_NEEDED",
+    "DONE",
+    "FAILED",
+    "CANCELLED",
+]

langgraph_stream_parser-0.5.0/src/langgraph_stream_parser/tasks/runner.py

@@ -0,0 +1,286 @@
+"""TaskRunner: a single-process async worker pool for delegated agent tasks.
+
+Generalizes the cron-scheduler pattern (an asyncio task driving the shared
+``SessionAdapter``) into a durable, board-backed task queue:
+
+- ``enqueue`` writes a ``queued`` row and returns a ``task_id`` immediately —
+  the caller (an HTTP handler or an agent tool) never blocks on the run.
+- ``concurrency`` worker coroutines each claim the oldest ``queued`` task
+  (atomically, via the store), run it as its own ``SessionAdapter`` session,
+  and transition it to ``done`` / ``failed`` / ``review_needed`` based on the
+  session's typed ``outcome``.
+- on ``start`` any ``ongoing`` rows left by a crash are requeued.
+
+The runner depends only on the :class:`TaskStore` protocol and the public
+``SessionAdapter`` surface, so a surface can back it with any store (in-memory,
+SQLite, …) without touching this code.
+
+Single-process by design: the worker count *is* the concurrency cap, and the
+atomic claim is only atomic within one process — run one server worker.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from typing import Any, Optional
+
+from .state import (
+    CANCELLED,
+    DONE,
+    FAILED,
+    ONGOING,
+    QUEUED,
+    REVIEW_NEEDED,
+    TERMINAL_STATES,
+    outcome_to_state,
+)
+from .store import Task, TaskStore, now_iso
+
+logger = logging.getLogger(__name__)
+
+
+class TaskRunner:
+    """Runs delegated tasks on the app's asyncio loop. See module docstring."""
+
+    def __init__(
+        self,
+        adapter: Any,
+        store: TaskStore,
+        *,
+        concurrency: int = 3,
+        thread_prefix: str = "task-",
+        context_label: str = "Async task",
+        poll_interval: float = 2.0,
+    ) -> None:
+        self._adapter = adapter
+        self._store = store
+        self._concurrency = max(1, concurrency)
+        self._thread_prefix = thread_prefix
+        self._context_label = context_label
+        self._poll_interval = poll_interval
+        self._workers: list[asyncio.Task] = []
+        self._side_tasks: set[asyncio.Task] = set()  # resume runs, etc.
+        self._wake = asyncio.Event()
+        self._started = False
+
+    # ── lifecycle ────────────────────────────────────────────────────
+    async def start(self) -> None:
+        """Set up the store, recover orphans, and spawn worker coroutines."""
+        if self._started:
+            return
+        await self._store.setup()
+        recovered = await self._store.requeue_orphans()
+        if recovered:
+            logger.info("TaskRunner requeued %d orphaned task(s) on startup", recovered)
+        self._started = True
+        self._workers = [
+            asyncio.create_task(self._worker(i)) for i in range(self._concurrency)
+        ]
+        # Kick the workers in case there's already queued work.
+        self._wake.set()
+
+    async def shutdown(self) -> None:
+        tasks = [*self._workers, *self._side_tasks]
+        for t in tasks:
+            t.cancel()
+        # Await the cancellations so no tasks linger past shutdown (otherwise
+        # the event loop can't close cleanly on the way down).
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        self._workers.clear()
+        self._side_tasks.clear()
+        self._started = False
+
+    # ── public API ───────────────────────────────────────────────────
+    async def enqueue(
+        self,
+        *,
+        title: str,
+        prompt: str,
+        agent_spec: Optional[str] = None,
+        parent_id: Optional[str] = None,
+    ) -> str:
+        """Create a queued task and return its id immediately (non-blocking)."""
+        if not prompt or not prompt.strip():
+            raise ValueError("Task prompt is required.")
+        task_id = uuid.uuid4().hex
+        task: Task = {
+            "task_id": task_id,
+            "parent_id": parent_id,
+            "title": (title or prompt).strip()[:200],
+            "prompt": prompt.strip(),
+            "agent_spec": agent_spec,
+            "state": QUEUED,
+            "thread_id": f"{self._thread_prefix}{task_id}",
+            "created_at": now_iso(),
+            "started_at": None,
+            "finished_at": None,
+            "result": None,
+            "artifacts": None,
+            "error": None,
+            "interrupt": None,
+        }
+        await self._store.create(task)
+        self._wake.set()
+        return task_id
+
+    async def cancel(self, task_id: str) -> bool:
+        """Cancel a task. Stops the in-flight run if it's ``ongoing``."""
+        task = await self._store.get(task_id)
+        if task is None or task.get("state") in TERMINAL_STATES:
+            return False
+        # Mark cancelled first, then interrupt the in-flight run. The worker
+        # awaiting that run sees the run task's CancelledError (its own
+        # ``cancelling()`` is 0) and leaves the already-set state alone.
+        await self._store.update(
+            task_id, state=CANCELLED, finished_at=now_iso()
+        )
+        if task.get("state") == ONGOING:
+            self._adapter.cancel(task["thread_id"])
+        return True
+
+    async def resume(self, task_id: str, decisions: list[dict[str, Any]]) -> bool:
+        """Resume a ``review_needed`` task with HITL decisions (non-blocking).
+
+        Flips the task back to ``ongoing`` and runs the resume in the
+        background so the caller (an approve/reject HTTP handler) returns at
+        once.
+        """
+        task = await self._store.get(task_id)
+        if task is None or task.get("state") != REVIEW_NEEDED:
+            return False
+        await self._store.update(
+            task_id, state=ONGOING, interrupt=None, started_at=now_iso()
+        )
+        t = asyncio.create_task(self._resume_run(task, decisions))
+        self._side_tasks.add(t)
+        t.add_done_callback(self._side_tasks.discard)
+        return True
+
+    async def retry(self, task_id: str) -> bool:
+        """Re-queue a ``failed`` / ``cancelled`` task (same thread → resumes
+        from its last checkpoint where a durable saver is configured)."""
+        task = await self._store.get(task_id)
+        if task is None or task.get("state") not in {FAILED, CANCELLED}:
+            return False
+        await self._store.update(
+            task_id,
+            state=QUEUED,
+            error=None,
+            finished_at=None,
+            started_at=None,
+        )
+        self._wake.set()
+        return True
+
+    # ── internals ────────────────────────────────────────────────────
+    async def _worker(self, idx: int) -> None:
+        while True:
+            try:
+                task = await self._store.claim_next()
+            except Exception:  # pragma: no cover - defensive
+                logger.exception("worker %d: claim_next failed", idx)
+                task = None
+            if task is None:
+                # Nothing to do: sleep until woken or the poll timeout fires
+                # (the timeout self-heals any missed wake signal).
+                try:
+                    await asyncio.wait_for(self._wake.wait(), timeout=self._poll_interval)
+                except asyncio.TimeoutError:
+                    pass
+                self._wake.clear()
+                continue
+            await self._run_one(task)
+
+    async def _run_one(self, task: Task) -> None:
+        task_id = task["task_id"]
+        session = self._adapter.submit_message(
+            task["thread_id"],
+            task["prompt"],
+            context_parts=[f"[{self._context_label}: {task.get('title', task_id)}]"],
+        )
+        await self._await_run(task_id, session)
+
+    async def _resume_run(
+        self, task: Task, decisions: list[dict[str, Any]]
+    ) -> None:
+        task_id = task["task_id"]
+        session = self._adapter.submit_decisions(task["thread_id"], decisions)
+        await self._await_run(task_id, session)
+
+    async def _await_run(self, task_id: str, session: Any) -> None:
+        """Await a session's in-flight turn and record the outcome."""
+        try:
+            run_task = getattr(session, "current_task", None)
+            if run_task is not None:
+                await run_task
+        except asyncio.CancelledError:
+            cur = asyncio.current_task()
+            if cur is not None and cur.cancelling() > 0:
+                # This worker is itself being cancelled (shutdown) → propagate
+                # so it can exit; leave the task ``ongoing`` for restart recovery.
+                raise
+            # Otherwise the *run* task was cancelled via ``cancel()`` — its
+            # state is already set; just drain and stop.
+            self._drain(session)
+            return
+        except Exception:  # pragma: no cover - _produce captures its own errors
+            logger.exception("task %s run raised", task_id)
+
+        events = self._drain(session)
+        await self._record_outcome(task_id, session, events)
+
+    async def _record_outcome(
+        self, task_id: str, session: Any, events: list[dict[str, Any]]
+    ) -> None:
+        outcome = getattr(session, "outcome", None)
+        state = outcome_to_state(outcome)
+        fields: dict[str, Any] = {"state": state}
+        if state in TERMINAL_STATES:
+            fields["finished_at"] = now_iso()
+        if state == DONE:
+            fields["result"] = self._result_text(events)
+        elif state == REVIEW_NEEDED:
+            fields["interrupt"] = getattr(session, "interrupt", None)
+        elif state == FAILED:
+            fields["error"] = getattr(session, "error", None) or "Task run failed."
+        await self._store.update(task_id, **fields)
+
+    @staticmethod
+    def _drain(session: Any) -> list[dict[str, Any]]:
+        """Drain a headless session's event queue (no SSE consumer)."""
+        events: list[dict[str, Any]] = []
+        q = getattr(session, "event_queue", None)
+        if q is None:
+            return events
+        while not q.empty():
+            try:
+                events.append(q.get_nowait())
+            except asyncio.QueueEmpty:  # pragma: no cover
+                break
+        return events
+
+    @staticmethod
+    def _result_text(events: list[dict[str, Any]]) -> Optional[str]:
+        """Reconstruct the assistant's final text from streamed content events."""
+        parts = [
+            e.get("content", "")
+            for e in events
+            if e.get("type") == "content" and e.get("role", "assistant") == "assistant"
+        ]
+        text = "".join(parts).strip()
+        return text or None
+
+
+# ── process-global singleton (so agent tools can reach the runner) ──
+_runner: Optional[TaskRunner] = None
+
+
+def set_runner(runner: Optional[TaskRunner]) -> None:
+    global _runner
+    _runner = runner
+
+
+def get_runner() -> Optional[TaskRunner]:
+    return _runner