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

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

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.6.0] - 2026-06-14
+
+Make delegated tasks **interactive** — a per-task event transcript, agent
+self-delegation tools, and talk-back. Builds on the 0.5.0 task engine.
+
+### Added
+- **Event transcript per task.** `TaskRunner` now *streams* each run's events to
+  the store as they arrive (instead of draining at the end), via two new
+  `TaskStore` methods — `append_events` / `get_events`. This is what makes a
+  per-task detail/replay view (and live-tailing) possible. `InMemoryTaskStore`
+  implements both.
+- **`TASK_TOOLS`** (`langgraph_stream_parser.tasks.tools`) — five agent-facing
+  delegation tools (`start_async_task`, `check_async_task`, `list_async_tasks`,
+  `update_async_task`, `cancel_async_task`) so an agent can spawn async copies of
+  itself against the local runner (no remote server). Mirrors the deepagents
+  async-subagent contract.
+- **`current_task_id`** context var — set while a task's agent runs, so a
+  sub-task it spawns is automatically linked to it (`parent_id`), forming a tree.
+- **`TaskRunner.followup(task_id, message)`** — send a follow-up to a finished
+  task; continues its thread (it remembers prior work) and re-runs in the
+  background. `TaskRunner.store` property for read access from tools.
+
+### Notes
+- Additive; the 0.5.0 API is unchanged. The streaming rewrite preserves the
+  same terminal-outcome → board-state mapping and cancel/shutdown semantics
+  (regression-tested).
+
 ## [0.5.0] - 2026-06-14
 
 An **async task-delegation engine** — the reusable core behind a "delegate a

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-stream-parser
-Version: 0.5.0
+Version: 0.6.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

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

@@ -1,6 +1,6 @@
 [project]
 name = "langgraph-stream-parser"
-version = "0.5.0"
+version = "0.6.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"}

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

@@ -63,8 +63,10 @@ from .tasks import (
     InMemoryTaskStore,
     Task,
     TaskState,
+    TASK_TOOLS,
     set_runner,
     get_runner,
+    current_task_id,
     outcome_to_state,
 )
 from .compat import (
@@ -74,7 +76,7 @@ from .compat import (
     aresume_graph_from_interrupt,
 )
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 __all__ = [
     # Main parser
@@ -114,8 +116,10 @@ __all__ = [
     "InMemoryTaskStore",
     "Task",
     "TaskState",
+    "TASK_TOOLS",
     "set_runner",
     "get_runner",
+    "current_task_id",
     "outcome_to_state",
     # Serialization
     "event_to_dict",

{langgraph_stream_parser-0.5.0 → langgraph_stream_parser-0.6.0}/src/langgraph_stream_parser/tasks/__init__.py

@@ -20,7 +20,8 @@ Example:
 """
 from __future__ import annotations
 
-from .runner import TaskRunner, get_runner, set_runner
+from .runner import TaskRunner, current_task_id, get_runner, set_runner
+from .tools import TASK_TOOLS
 from .state import (
     CANCELLED,
     DONE,
@@ -38,6 +39,8 @@ __all__ = [
     "TaskRunner",
     "set_runner",
     "get_runner",
+    "current_task_id",
+    "TASK_TOOLS",
     "TaskStore",
     "InMemoryTaskStore",
     "Task",

{langgraph_stream_parser-0.5.0 → langgraph_stream_parser-0.6.0}/src/langgraph_stream_parser/tasks/runner.py

@@ -21,6 +21,7 @@ atomic claim is only atomic within one process — run one server worker.
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import logging
 import uuid
 from typing import Any, Optional
@@ -39,6 +40,18 @@ from .store import Task, TaskStore, now_iso
 
 logger = logging.getLogger(__name__)
 
+#: Set to the running task's id while its agent executes, so delegation tools
+#: called by that agent can record the spawned sub-task's ``parent_id``.
+#: ``asyncio.create_task`` copies the context, so the value propagates into the
+#: agent's run task and the tools it invokes.
+current_task_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "langstage_current_task_id", default=None
+)
+
+#: Event ``type`` values that end a run's stream (the parser emits exactly one
+#: per turn; an interrupt is followed by a trailing ``complete``).
+_TERMINAL_EVENT_TYPES = frozenset({"complete", "error", "cancelled"})
+
 
 class TaskRunner:
     """Runs delegated tasks on the app's asyncio loop. See module docstring."""
@@ -64,6 +77,11 @@ class TaskRunner:
         self._wake = asyncio.Event()
         self._started = False
 
+    @property
+    def store(self) -> TaskStore:
+        """The task store backing this runner (for read access from tools)."""
+        return self._store
+
     # ── lifecycle ────────────────────────────────────────────────────
     async def start(self) -> None:
         """Set up the store, recover orphans, and spawn worker coroutines."""
@@ -158,6 +176,36 @@ class TaskRunner:
         t.add_done_callback(self._side_tasks.discard)
         return True
 
+    async def followup(self, task_id: str, message: str) -> bool:
+        """Send a follow-up message to a finished task's thread (talk-back).
+
+        Continues the conversation on the same thread (the checkpointer keeps
+        history), runs in the background, and flips the task to ``ongoing`` →
+        ``done`` with the new reply. For a ``review_needed`` task use
+        :meth:`resume` instead. Non-blocking.
+        """
+        if not message or not message.strip():
+            return False
+        task = await self._store.get(task_id)
+        if task is None or task.get("state") not in {DONE, FAILED, CANCELLED}:
+            return False
+        await self._store.update(
+            task_id, state=ONGOING, finished_at=None, error=None, started_at=now_iso()
+        )
+        t = asyncio.create_task(self._followup_run(task, message.strip()))
+        self._side_tasks.add(t)
+        t.add_done_callback(self._side_tasks.discard)
+        return True
+
+    async def _followup_run(self, task: Task, message: str) -> None:
+        task_id = task["task_id"]
+        token = current_task_id.set(task_id)
+        try:
+            session = self._adapter.submit_message(task["thread_id"], message)
+        finally:
+            current_task_id.reset(token)
+        await self._await_run(task_id, session)
+
     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)."""
@@ -195,25 +243,46 @@ class TaskRunner:
 
     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)}]"],
-        )
+        # Tag the context so any sub-task the agent spawns records this as parent.
+        token = current_task_id.set(task_id)
+        try:
+            session = self._adapter.submit_message(
+                task["thread_id"],
+                task["prompt"],
+                context_parts=[f"[{self._context_label}: {task.get('title', task_id)}]"],
+            )
+        finally:
+            current_task_id.reset(token)
         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)
+        token = current_task_id.set(task_id)
+        try:
+            session = self._adapter.submit_decisions(task["thread_id"], decisions)
+        finally:
+            current_task_id.reset(token)
         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."""
+        """Stream the run's events to the store as they arrive, then record the
+        terminal outcome. Streaming (vs draining at the end) is what makes the
+        per-task detail/replay view possible — including live-tailing."""
+        content_parts: list[str] = []
+        q = getattr(session, "event_queue", None)
+        run_task = getattr(session, "current_task", None)
         try:
-            run_task = getattr(session, "current_task", None)
-            if run_task is not None:
+            if q is not None:
+                while True:
+                    event = await q.get()
+                    await self._store.append_events(task_id, [event])
+                    if event.get("type") == "content" and event.get("role", "assistant") == "assistant":
+                        content_parts.append(event.get("content", ""))
+                    if event.get("type") in _TERMINAL_EVENT_TYPES:
+                        break
+            if run_task is not None and not run_task.done():
                 await run_task
         except asyncio.CancelledError:
             cur = asyncio.current_task()
@@ -221,18 +290,30 @@ class TaskRunner:
                 # 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)
+            # Otherwise the *run* task was cancelled via ``cancel()`` — its state
+            # is already set; persist any stragglers and stop.
+            await self._flush_remaining(task_id, q)
             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)
+        result_text = "".join(content_parts).strip() or None
+        await self._record_outcome(task_id, session, result_text)
+
+    async def _flush_remaining(self, task_id: str, q: Any) -> None:
+        if q is None:
+            return
+        leftover: list[dict[str, Any]] = []
+        while not q.empty():
+            try:
+                leftover.append(q.get_nowait())
+            except asyncio.QueueEmpty:  # pragma: no cover
+                break
+        if leftover:
+            await self._store.append_events(task_id, leftover)
 
     async def _record_outcome(
-        self, task_id: str, session: Any, events: list[dict[str, Any]]
+        self, task_id: str, session: Any, result_text: Optional[str]
     ) -> None:
         outcome = getattr(session, "outcome", None)
         state = outcome_to_state(outcome)
@@ -240,38 +321,13 @@ class TaskRunner:
         if state in TERMINAL_STATES:
             fields["finished_at"] = now_iso()
         if state == DONE:
-            fields["result"] = self._result_text(events)
+            fields["result"] = result_text
         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

{langgraph_stream_parser-0.5.0 → langgraph_stream_parser-0.6.0}/src/langgraph_stream_parser/tasks/store.py

@@ -85,6 +85,15 @@ class TaskStore(Protocol):
         recover from a crash). Returns the number requeued."""
         ...
 
+    async def append_events(self, task_id: str, events: list[dict[str, Any]]) -> None:
+        """Append serialized stream events to a task's transcript (the live
+        stream the runner produces). Enables a detail/replay view per task."""
+        ...
+
+    async def get_events(self, task_id: str) -> list[dict[str, Any]]:
+        """Return a task's full event transcript in order (empty if none)."""
+        ...
+
 
 class InMemoryTaskStore:
     """Dependency-free reference store. Not durable across process restarts.
@@ -95,6 +104,7 @@ class InMemoryTaskStore:
 
     def __init__(self) -> None:
         self._tasks: dict[str, Task] = {}
+        self._events: dict[str, list[dict[str, Any]]] = {}
         self._lock = asyncio.Lock()
 
     async def setup(self) -> None:
@@ -149,3 +159,9 @@ class InMemoryTaskStore:
                 task["started_at"] = None
                 n += 1
         return n
+
+    async def append_events(self, task_id: str, events: list[dict[str, Any]]) -> None:
+        self._events.setdefault(task_id, []).extend(events)
+
+    async def get_events(self, task_id: str) -> list[dict[str, Any]]:
+        return list(self._events.get(task_id, []))

langgraph_stream_parser-0.6.0/src/langgraph_stream_parser/tasks/tools.py

@@ -0,0 +1,121 @@
+"""Agent-facing delegation tools — let an agent spawn async copies of itself.
+
+These mirror the deepagents async-subagent tool contract, but run against the
+LOCAL :class:`TaskRunner` + store (no remote Agent Protocol server). The agent
+gets a ``task_id`` back immediately and should NOT poll — the task runs in the
+background while the agent keeps working.
+
+Wire them into a host's toolset alongside its other tools; they reach the
+process-global runner via :func:`get_runner`, so a sub-task the agent spawns is
+automatically linked to the spawning task (``parent_id``) via the
+``current_task_id`` context var.
+"""
+from __future__ import annotations
+
+from langchain_core.tools import tool as langchain_tool
+
+from .runner import current_task_id, get_runner
+
+_UNAVAILABLE = "Async task delegation is unavailable in this context."
+
+
+@langchain_tool
+async def start_async_task(title: str, prompt: str) -> str:
+    """Delegate a task to a background copy of yourself.
+
+    Returns a task_id immediately; the task runs in the background while you
+    keep working. Do NOT wait or poll — report the task_id to the user and move
+    on. Use this for long or parallelizable work.
+
+    Args:
+        title: A short human-readable name for the task.
+        prompt: The full instruction for the background agent to carry out.
+    """
+    runner = get_runner()
+    if runner is None:
+        return _UNAVAILABLE
+    try:
+        task_id = await runner.enqueue(
+            title=title, prompt=prompt, parent_id=current_task_id.get()
+        )
+    except ValueError as e:
+        return f"Could not start task: {e}"
+    return f"Started async task '{title}'. task_id: {task_id} (running in the background)."
+
+
+@langchain_tool
+async def check_async_task(task_id: str) -> str:
+    """Check a delegated task's current status and result. Does not block.
+
+    Call this once when the user asks about a task — never poll in a loop.
+    """
+    runner = get_runner()
+    if runner is None:
+        return _UNAVAILABLE
+    task = await runner.store.get(task_id)
+    if task is None:
+        return f"No delegated task with id {task_id}."
+    state = task.get("state")
+    if state == "done":
+        return f"Task {task_id} is done.\n\nResult:\n{task.get('result') or '(no text output)'}"
+    if state == "failed":
+        return f"Task {task_id} failed: {task.get('error') or 'unknown error'}"
+    if state == "review_needed":
+        return f"Task {task_id} is paused and needs human review/approval before it can continue."
+    return f"Task {task_id} is {state}."
+
+
+@langchain_tool
+async def list_async_tasks() -> str:
+    """List delegated tasks and their current states."""
+    runner = get_runner()
+    if runner is None:
+        return _UNAVAILABLE
+    tasks = await runner.store.list()
+    if not tasks:
+        return "No delegated tasks."
+    lines = [
+        f"- {t['task_id']} [{t.get('state')}] {t.get('title')}" for t in tasks
+    ]
+    return "Delegated tasks:\n" + "\n".join(lines)
+
+
+@langchain_tool
+async def update_async_task(task_id: str, message: str) -> str:
+    """Send a follow-up instruction to a finished delegated task.
+
+    Continues that task's conversation on its own thread (it remembers its prior
+    work) and runs in the background. Use for "now also do X" on a completed task.
+    """
+    runner = get_runner()
+    if runner is None:
+        return _UNAVAILABLE
+    ok = await runner.followup(task_id, message)
+    return (
+        f"Sent follow-up to task {task_id} (running in the background)."
+        if ok
+        else f"Could not update task {task_id} (not found, or it is still running)."
+    )
+
+
+@langchain_tool
+async def cancel_async_task(task_id: str) -> str:
+    """Cancel a delegated task that is queued, running, or awaiting review."""
+    runner = get_runner()
+    if runner is None:
+        return _UNAVAILABLE
+    ok = await runner.cancel(task_id)
+    return (
+        f"Cancelled task {task_id}."
+        if ok
+        else f"Could not cancel task {task_id} (not found or already finished)."
+    )
+
+
+TASK_TOOLS = [
+    start_async_task,
+    check_async_task,
+    list_async_tasks,
+    update_async_task,
+    cancel_async_task,
+]

{langgraph_stream_parser-0.5.0 → langgraph_stream_parser-0.6.0}/tests/test_tasks.py

@@ -21,10 +21,18 @@ from langgraph_stream_parser.tasks import (
     REVIEW_NEEDED,
     InMemoryTaskStore,
     TaskRunner,
+    current_task_id,
     get_runner,
     set_runner,
 )
 from langgraph_stream_parser.tasks.store import now_iso
+from langgraph_stream_parser.tasks.tools import (
+    cancel_async_task,
+    check_async_task,
+    list_async_tasks,
+    start_async_task,
+    update_async_task,
+)
 
 from .fixtures.mocks import (
     AI_MESSAGE_WITH_TOOL_CALLS,
@@ -419,3 +427,103 @@ class TestRunnerHardening:
             assert row["result"]  # tokens concatenated into the final text
         finally:
             await runner.shutdown()
+
+
+# ── 6. Slice 2: event transcript, followup, delegation tools ─────────
+
+
+class TestEventTranscript:
+    async def test_events_streamed_to_store(self):
+        adapter = SessionAdapter(graph=MockGraph([[SIMPLE_AI_MESSAGE]]), stream_mode="updates")
+        store = InMemoryTaskStore()
+        runner = TaskRunner(adapter, store, concurrency=1, poll_interval=0.05)
+        await runner.start()
+        try:
+            tid = await runner.enqueue(title="t", prompt="hi")
+            await _wait_state(store, tid, DONE)
+            events = await store.get_events(tid)
+            types = [e.get("type") for e in events]
+            assert "content" in types
+            assert types[-1] == "complete"  # terminal event recorded last
+        finally:
+            await runner.shutdown()
+
+    async def test_followup_reruns_thread(self):
+        graph = MockGraph([[SIMPLE_AI_MESSAGE], [SIMPLE_AI_MESSAGE]])
+        adapter = SessionAdapter(graph=graph, stream_mode="updates")
+        store = InMemoryTaskStore()
+        runner = TaskRunner(adapter, store, concurrency=1, poll_interval=0.05)
+        await runner.start()
+        try:
+            tid = await runner.enqueue(title="t", prompt="hi")
+            await _wait_state(store, tid, DONE)
+            assert await runner.followup(tid, "now do more") is True
+            await _wait_state(store, tid, DONE)
+            events = await store.get_events(tid)
+            # the thread ran twice → two terminal completes in the transcript
+            assert sum(1 for e in events if e.get("type") == "complete") == 2
+        finally:
+            await runner.shutdown()
+
+    async def test_followup_rejected_on_unknown(self):
+        store = InMemoryTaskStore()
+        runner = TaskRunner(SessionAdapter(graph=MockGraph([[]])), store)
+        assert await runner.followup("nope", "hi") is False
+
+
+def _task_id_from(out: str) -> str:
+    return out.split("task_id:")[1].split()[0].strip().rstrip(".")
+
+
+class TestDelegationTools:
+    async def test_start_check_list(self):
+        adapter = SessionAdapter(graph=MockGraph([[SIMPLE_AI_MESSAGE]]), stream_mode="updates")
+        store = InMemoryTaskStore()
+        runner = TaskRunner(adapter, store, concurrency=1, poll_interval=0.05)
+        await runner.start()
+        set_runner(runner)
+        try:
+            out = await start_async_task.ainvoke({"title": "research", "prompt": "go research"})
+            assert "task_id:" in out
+            tid = _task_id_from(out)
+            await _wait_state(store, tid, DONE)
+            assert "done" in (await check_async_task.ainvoke({"task_id": tid})).lower()
+            assert tid in await list_async_tasks.ainvoke({})
+        finally:
+            set_runner(None)
+            await runner.shutdown()
+
+    async def test_parent_id_from_context(self):
+        # The runner sets current_task_id while an agent runs; a tool the agent
+        # calls must stamp the spawned task's parent_id from it.
+        store = InMemoryTaskStore()
+        runner = TaskRunner(SessionAdapter(graph=MockGraph([[SIMPLE_AI_MESSAGE]])), store)  # not started
+        set_runner(runner)
+        try:
+            token = current_task_id.set("parent-123")
+            try:
+                out = await start_async_task.ainvoke({"title": "child", "prompt": "p"})
+            finally:
+                current_task_id.reset(token)
+            child = await store.get(_task_id_from(out))
+            assert child["parent_id"] == "parent-123"
+        finally:
+            set_runner(None)
+
+    async def test_cancel_tool(self):
+        store = InMemoryTaskStore()
+        runner = TaskRunner(SessionAdapter(graph=MockGraph([[SIMPLE_AI_MESSAGE]])), store)  # not started
+        set_runner(runner)
+        try:
+            tid = await runner.enqueue(title="t", prompt="p")
+            assert "Cancelled" in await cancel_async_task.ainvoke({"task_id": tid})
+            assert (await store.get(tid))["state"] == CANCELLED
+        finally:
+            set_runner(None)
+
+    async def test_tools_unavailable_without_runner(self):
+        set_runner(None)
+        assert "unavailable" in (
+            await start_async_task.ainvoke({"title": "x", "prompt": "p"})
+        ).lower()
+        assert "unavailable" in (await list_async_tasks.ainvoke({})).lower()