flowjet 2.0.8__tar.gz → 2.0.10__tar.gz

{flowjet-2.0.8 → flowjet-2.0.10}/.gitignore

@@ -254,4 +254,6 @@ Temporary Items
 
 # Claude Code session-local
 .claude/
-.codebuddy/
+.codebuddy/
+# local wheel overrides for docker build (flowjet[boxlite] + local soothe)
+wheels/*.whl

{flowjet-2.0.8 → flowjet-2.0.10}/CHANGELOG.md

@@ -10,6 +10,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.10] — 2026-10-14
+
+### Changed
+
+- **Bump soothe and soothe-nano to the latest.** `soothe` `1.0.22 → 1.1.0`
+  and `soothe-nano` `1.3.3 → 1.4.2`. The version caps were lifted:
+  `soothe>=1.1.0,<2.0.0` and `soothe-nano>=1.4.2,<1.5.0`. The standalone
+  `soothe-sdk` package was removed in the new release; its modules merged
+  into `soothe` and `soothe-nano`. All FlowJet import paths were migrated:
+  `soothe_sdk.utils.serde` → `soothe_nano.utils.serde`,
+  `soothe_sdk.utils.formatting` → `soothe_nano.utils.formatting`,
+  `soothe_sdk.tools.metadata` → `soothe_nano.tools.metadata`, and
+  `soothe_sdk.display.message_processing` → `soothe.display.message_processing`.
+  The graceful try/except fallbacks in `progress.py` and `tool_stream.py`
+  now resolve to the real implementations instead of falling through to
+  fallbacks.
+
+## [2.0.9] — 2026-09-24
+
+### Fixed
+
+- **Suppress noisy third-party warnings at startup.** `requests` emits
+  `RequestsDependencyWarning` when the installed `urllib3` / `chardet` /
+  `charset_normalizer` versions fall outside its supported range, and
+  `soothe`'s `TypeSafeClassifier` triggers LangChain's `LangChainBetaWarning`.
+  Both are version-mismatch or beta-API notices the user cannot act on, so
+  they are now silenced at the earliest point of each entry point. A new
+  `core/_warnings.py` module exposes `suppress_known_warnings()`, called from
+  both the CLI (`cli.py`) and server (`server/__main__.py`) `main()` before
+  the heavy agent stack is imported.
+
 ## [2.0.8] — 2026-09-24
 
 ### Added

{flowjet-2.0.8 → flowjet-2.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flowjet
-Version: 2.0.8
+Version: 2.0.10
 Summary: FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by soothe-nano
 Project-URL: Homepage, https://github.com/caesar0301/flowjet
 Project-URL: Repository, https://github.com/caesar0301/flowjet
@@ -22,8 +22,8 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.11
-Requires-Dist: soothe-nano<1.4.0,>=1.3.0
-Requires-Dist: soothe<2.0.0,>=1.0.14
+Requires-Dist: soothe-nano<1.5.0,>=1.4.2
+Requires-Dist: soothe<2.0.0,>=1.1.0
 Provides-Extra: dev
 Requires-Dist: httpx>=0.27.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
@@ -35,10 +35,12 @@ Requires-Dist: ruff>=0.12.0; extra == 'dev'
 Requires-Dist: twine>=5.0.0; extra == 'dev'
 Provides-Extra: server
 Requires-Dist: agent-client-protocol[http]<1.0.0,>=0.12.1; extra == 'server'
+Requires-Dist: boxlite>=0.1.0; extra == 'server'
 Requires-Dist: fastapi>=0.115.0; extra == 'server'
 Requires-Dist: langchain-core>=0.3; extra == 'server'
 Requires-Dist: pydantic-settings>=2.0; extra == 'server'
 Requires-Dist: pydantic>=2.0; extra == 'server'
+Requires-Dist: s3fs>=2024.6; extra == 'server'
 Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'server'
 Description-Content-Type: text/markdown
 

{flowjet-2.0.8 → flowjet-2.0.10}/deploy/README.md

@@ -54,7 +54,7 @@ Services bound to localhost only. PostgreSQL uses default credentials (postgres/
 
 ## Config
 
-`nano.yml` uses the DashScope (OpenAI-compatible) provider with `${ENV_VAR}` substitution and PostgreSQL + pgvector persistence. It is mounted over the image's baked default (`/var/lib/soothe/config/nano.yml`), which uses SQLite for local development — the mount switches the whole runtime to Postgres mode for the container stack.
+`nano.yml` uses the DashScope (OpenAI-compatible) provider with `${ENV_VAR}` substitution and PostgreSQL + pgvector persistence. It is mounted over the image's baked default (`/flowjet/config/nano.yml`), which uses SQLite for local development — the mount switches the whole runtime to Postgres mode for the container stack.
 
 ## Security
 

{flowjet-2.0.8 → flowjet-2.0.10}/deploy/nano.yml

@@ -3,7 +3,7 @@
 # Mirrors ../soothe/deploy/nano.yml structure; keeps the DashScope provider
 # from config/nano.yml (flowjet-server default).
 #
-# Mounted at /var/lib/soothe/config/nano.yml (default agent path).
+# Mounted at /flowjet/config/nano.yml (default agent path).
 # Uses environment variable substitution (${ENV_VAR}).
 #
 # Required env vars (set in deploy/.env):

{flowjet-2.0.8 → flowjet-2.0.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flowjet"
-version = "2.0.8"
+version = "2.0.10"
 description = "FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by soothe-nano"
 readme = "README.md"
 license = { text = "MIT" }
@@ -25,14 +25,10 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-# The CLI stays a single-dependency wheel. Everything the HTTP service needs
-# lives in the `server` extra, and `flowjet.cli` never imports it at module
-# scope (see tests/unit/test_cli_no_server_deps.py).
+# Single-dependency CLI wheel; HTTP service deps live in the `server` extra.
 dependencies = [
-    # Default CLI runtime (FLOWJET_BACKEND=soothe). soothe is a host layer over
-    # soothe-nano, so nano stays pinned explicitly: soothe only caps it at <2.
-    "soothe>=1.0.14,<2.0.0",
-    "soothe-nano>=1.3.0,<1.4.0",
+    "soothe>=1.1.0,<2.0.0",
+    "soothe-nano>=1.4.2,<1.5.0",
 ]
 
 [project.optional-dependencies]
@@ -43,6 +39,10 @@ server = [
     "pydantic-settings>=2.0",
     "agent-client-protocol[http]>=0.12.1,<1.0.0",
     "langchain-core>=0.3",
+    # S3/MinIO workspace sync backend
+    "s3fs>=2024.6",
+    # microVM-per-workspace session isolation (https://github.com/boxlite-ai/boxlite)
+    "boxlite>=0.1.0",
 ]
 dev = [
     "pytest>=8.0.0",
@@ -62,14 +62,11 @@ dev = [
 
 [tool.uv]
 default-groups = ["dev"]
-# cryptography 46+ ships macOS wheels for arm64 only; Intel Macs must build from
-# source (Rust), which is slow and looks like a hang during `uv sync`.
+# cryptography 46+ lacks x86_64 macOS wheels; Intel Macs would build from source.
 constraint-dependencies = [
     "cryptography>=45,<46; platform_machine == 'x86_64' and sys_platform == 'darwin'",
 ]
 
-# soothe-nano is published on PyPI (>=0.9.9); resolve it from the default index.
-
 [project.scripts]
 flowjet = "flowjet.cli.cli:main"
 fj = "flowjet.cli.cli:main"
@@ -87,16 +84,13 @@ packages = ["src/flowjet"]
 [tool.hatch.build.targets.sdist]
 include = ["src/flowjet/", "nano.yml", "README.md", "LICENSE", "docs/", "CHANGELOG.md"]
 
-# Non-Python assets (shell completions, builtin_skills/) are shipped automatically
-# because they live inside the `src/flowjet` package, which hatchling includes
-# recursively. Do NOT re-list them in force-include — that adds the same file
-# twice and breaks `uv build` with "A second file is being added ... at the
-# same path".
+# Non-Python assets inside `src/flowjet` ship automatically; re-listing them in
+# force-include duplicates files and breaks `uv build`.
 
 [tool.ruff]
 line-length = 100
 target-version = "py311"
-# AgentSkills scripts are third-party / skill-local style; keep them out of package lint.
+# Third-party / skill-local scripts; excluded from package lint.
 extend-exclude = ["src/flowjet/builtin_skills"]
 
 [tool.ruff.lint]
@@ -112,8 +106,7 @@ warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
 
-# The moved server/bridge code is Any-heavy (nano and langchain objects); it is
-# checked loosely until it is annotated. CI has no mypy gate today.
+# Any-heavy moved code (nano/langchain objects); loosened until annotated.
 [[tool.mypy.overrides]]
 module = ["flowjet.server.*", "flowjet.core.bridges.*"]
 disallow_untyped_defs = false

{flowjet-2.0.8 → flowjet-2.0.10}/src/flowjet/cli/cli.py

@@ -717,6 +717,11 @@ def main_follow(argv: list[str] | None = None) -> int:
 
 
 def main(argv: list[str] | None = None) -> int:
+    # Silence noisy third-party warnings (requests version-mismatch,
+    # LangChain beta-API) before any heavy import pulls them in.
+    from flowjet.core._warnings import suppress_known_warnings
+
+    suppress_known_warnings()
     try:
         # Parse first so ``-V`` / ``-h`` / ``--help`` exit before we touch the
         # logging stack (and the heavy ``flowjet.cli.agent`` import it used to

{flowjet-2.0.8 → flowjet-2.0.10}/src/flowjet/cli/progress.py

@@ -308,7 +308,7 @@ def _compact(value: Any) -> str:
 
 def _abbrev_path(path: str) -> str:
     try:
-        from soothe_sdk.utils.formatting import convert_and_abbreviate_path
+        from soothe_nano.utils.formatting import convert_and_abbreviate_path
 
         return convert_and_abbreviate_path(path)
     except Exception:
@@ -320,7 +320,7 @@ def _abbrev_path(path: str) -> str:
 
 def _tool_meta(name: str) -> Any | None:
     try:
-        from soothe_sdk.tools.metadata import get_tool_meta
+        from soothe_nano.tools.metadata import get_tool_meta
 
         return get_tool_meta(name)
     except Exception:

flowjet-2.0.10/src/flowjet/core/_warnings.py

@@ -0,0 +1,53 @@
+"""Suppress noisy third-party warnings that are not actionable for users.
+
+These warnings come from dependencies (``requests``, ``soothe``/``langchain``)
+and fire at import time or agent build time. They are version-mismatch or
+beta-API notices that the user cannot fix, so we silence them globally at the
+earliest point of each entry point (CLI ``main`` and server ``main``).
+
+Call :func:`suppress_known_warnings` before importing the heavy agent stack.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+
+def suppress_known_warnings() -> None:
+    """Silence dependency warnings that users cannot act on.
+
+    Safe to call multiple times — ``filterwarnings`` is idempotent for the
+    same rule.
+
+    Suppressed:
+
+    * ``RequestsDependencyWarning`` — ``requests`` emits this when the
+      installed ``urllib3`` / ``chardet`` / ``charset_normalizer`` versions
+      fall outside its supported range. The versions still work; the warning
+      is informational only.
+    * ``LangChainBetaWarning`` — ``soothe`` uses ``TypeSafeClassifier`` which
+      is a beta LangChain API. The API may change, but the warning is noise
+      for end users.
+    """
+    # ``requests`` import-time version-mismatch warning.
+    warnings.filterwarnings(
+        "ignore",
+        category=UserWarning,
+        message=r".*urllib3 .* or chardet .* doesn't match a supported version.*",
+    )
+    # Also match by the concrete warning class when available — covers the
+    # exact ``RequestsDependencyWarning`` emitted by ``requests/__init__.py``.
+    try:
+        from requests.exceptions import RequestsDependencyWarning
+
+        warnings.filterwarnings("ignore", category=RequestsDependencyWarning)
+    except Exception:  # pragma: no cover - requests not installed / API changed
+        pass
+
+    # ``soothe`` / LangChain beta-API warning from ``TypeSafeClassifier``.
+    try:
+        from langchain_core._api.beta_decorator import LangChainBetaWarning
+
+        warnings.filterwarnings("ignore", category=LangChainBetaWarning)
+    except Exception:  # pragma: no cover - langchain not installed / API changed
+        pass

{flowjet-2.0.8 → flowjet-2.0.10}/src/flowjet/core/backend.py

@@ -15,15 +15,17 @@ FlowJet can build its agent two ways:
 
 The two surfaces switch **independently**, because they do not share the same
 constraints: the CLI builds one agent per invocation, while the server needs a
-dual-mode agent (AGENT + ASK graphs selected per request) — an API soothe does
-not expose today. Hence the defaults differ:
+dual-mode agent (AGENT + ASK graphs selected per request). The server now uses
+``ModeRoutedSootheAgent`` — one host agent per mode, lazily built — to provide
+dual-mode routing on the soothe backend. Hence both surfaces default to
+``soothe``:
 
 * ``FLOWJET_BACKEND`` (CLI) — default ``soothe``.
-* ``FLOWJET_SERVER_BACKEND`` (HTTP/ACP) — default ``nano``.
+* ``FLOWJET_SERVER_BACKEND`` (HTTP/ACP) — default ``soothe``.
 
 Both accept ``soothe`` or ``nano`` (case-insensitive); anything else is a hard
 error rather than a silent fallback, so a typo can never quietly run the wrong
-runtime.
+runtime. Set ``FLOWJET_SERVER_BACKEND=nano`` to fall back to the nano runtime.
 """
 
 from __future__ import annotations
@@ -47,9 +49,10 @@ class Backend(StrEnum):
 #: CLI builds one agent per invocation; the host runtime is the default there.
 DEFAULT_CLI_BACKEND = Backend.SOOTHE
 
-#: The server needs per-request mode switching (dual-mode agent), which soothe
-#: does not expose; it stays on nano until host dual-mode exists.
-DEFAULT_SERVER_BACKEND = Backend.NANO
+#: Both surfaces default to the host runtime (``soothe``). The server uses
+#: ``ModeRoutedSootheAgent`` for per-request mode switching (one host agent per
+#: mode, lazily built). Set ``FLOWJET_SERVER_BACKEND=nano`` to fall back to nano.
+DEFAULT_SERVER_BACKEND = Backend.SOOTHE
 
 _BACKENDS: dict[str, Backend] = {b.value: b for b in Backend}
 

{flowjet-2.0.8 → flowjet-2.0.10}/src/flowjet/core/backends/isolation/__init__.py

@@ -1,24 +1,36 @@
-"""Isolated thread-pool runtime (RFC-002 / RFC-003)."""
+"""Isolated runtime: thread-pool and boxlite microVM isolation."""
 
 from flowjet.core.backends.isolation.adapter import AgentAdapter, FakeAgentAdapter
 from flowjet.core.backends.isolation.admission import SessionAdmission
 from flowjet.core.backends.isolation.backend import IsolatingRuntimeBackend
+from flowjet.core.backends.isolation.boxlite_vm_pool import (
+    BoxLiteVMIsolationPool,
+    BoxLiteVMSettings,
+)
 from flowjet.core.backends.isolation.errors import IsolationError
+from flowjet.core.backends.isolation.isolation_pool import IsolationPool
 from flowjet.core.backends.isolation.mode_gate import InteractionModeGate
 from flowjet.core.backends.isolation.pool import PoolMetrics, PoolSettings, ThreadPool
 from flowjet.core.backends.isolation.request import IsolatedRunRequest
-from flowjet.core.backends.isolation.workspace import WorkspaceResolver
+from flowjet.core.backends.isolation.workspace import (
+    SyncAwareWorkspaceResolver,
+    WorkspaceResolver,
+)
 
 __all__ = [
     "AgentAdapter",
+    "BoxLiteVMIsolationPool",
+    "BoxLiteVMSettings",
     "FakeAgentAdapter",
     "IsolatedRunRequest",
     "IsolatingRuntimeBackend",
     "InteractionModeGate",
     "IsolationError",
+    "IsolationPool",
     "PoolMetrics",
     "PoolSettings",
     "SessionAdmission",
+    "SyncAwareWorkspaceResolver",
     "ThreadPool",
     "WorkspaceResolver",
 ]

{flowjet-2.0.8 → flowjet-2.0.10}/src/flowjet/core/backends/isolation/adapter.py

@@ -12,6 +12,8 @@ from flowjet.core.events import (
     RunCompleted,
     RunStarted,
     RuntimeEvent,
+    ToolCompleted,
+    ToolStarted,
     UsageInfo,
 )
 
@@ -53,6 +55,14 @@ class FakeAgentAdapter:
         yield Progress(stage="Working", message="Thinking…")
         if self.delay_s > 0:
             await asyncio.sleep(self.delay_s)
+
+        # Emit tool events when the caller requests them via metadata
+        # (mirrors FakeRuntimeBackend's emit_tools handling).
+        meta = req.metadata or {}
+        if meta.get("emit_tools"):
+            yield ToolStarted(tool="search", call_id="call_1")
+            yield ToolCompleted(tool="search", ok=True, call_id="call_1", duration_ms=12)
+
         # Write a marker file so concurrency tests can assert workspace isolation.
         marker = req.workspace / "last_input.txt"
         marker.write_text(req.input_text, encoding="utf-8")

{flowjet-2.0.8 → flowjet-2.0.10}/src/flowjet/core/backends/isolation/backend.py

@@ -1,4 +1,11 @@
-"""RuntimeBackend that admits, resolves workspaces, and submits to ThreadPool."""
+"""RuntimeBackend that admits, resolves workspaces, and submits to an isolation pool.
+
+Phase 1–2 use :class:`~flowjet.core.backends.isolation.pool.ThreadPool`.
+Phase 3 adds :class:`~flowjet.core.backends.isolation.boxlite_vm_pool.BoxLiteVMIsolationPool`
+for microVM-per-workspace session isolation via the external boxlite runtime.
+Both implement the
+:class:`~flowjet.core.backends.isolation.isolation_pool.IsolationPool` protocol.
+"""
 
 from __future__ import annotations
 
@@ -17,7 +24,17 @@ from flowjet.core.events import ModelInfo, RunRequest, RuntimeEvent
 
 
 class IsolatingRuntimeBackend:
-    """Pool-backed RuntimeBackend for the soothe-nano AgentAdapter."""
+    """Pool-backed RuntimeBackend for the soothe/nano AgentAdapter.
+
+    The workspace resolver is injectable (Phase 2): callers can pass a
+    :class:`SyncAwareWorkspaceResolver` to enable fsspec workspace sync.
+    The default is the local-only :class:`WorkspaceResolver` (Phase 1).
+
+    The isolation pool is injectable (Phase 3): callers can pass a
+    :class:`~flowjet.core.backends.isolation.boxlite_vm_pool.BoxLiteVMIsolationPool`
+    to enable microVM-per-workspace session isolation.  The default is the
+    in-process :class:`ThreadPool` (Phase 1/2).
+    """
 
     def __init__(
         self,
@@ -27,13 +44,14 @@ class IsolatingRuntimeBackend:
         pool_settings: PoolSettings | None = None,
         home: Path | str | None = None,
         admission: SessionAdmission | None = None,
-        pool: ThreadPool | None = None,
+        pool: Any | None = None,
         allow_external_workspace: bool = False,
         mode_gate: InteractionModeGate | None = None,
+        workspace_resolver: WorkspaceResolver | None = None,
     ) -> None:
         self._models = models or ["default"]
         home_path = Path(home).expanduser() if home else Path.home() / ".flowjet"
-        self._workspaces = WorkspaceResolver(
+        self._workspaces = workspace_resolver or WorkspaceResolver(
             home_path, allow_external_workspace=allow_external_workspace
         )
         self._admission = admission or SessionAdmission()
@@ -42,7 +60,7 @@ class IsolatingRuntimeBackend:
         self._started = False
 
     @property
-    def pool(self) -> ThreadPool:
+    def pool(self) -> Any:
         return self._pool
 
     @property
@@ -90,9 +108,18 @@ class IsolatingRuntimeBackend:
             metadata=metadata,
         )
         async with self._admission.admit(session):
-            async for event in self._pool.submit(isolated):
-                yield event
+            await self._workspaces.open_session(session, workspace)
+            try:
+                async for event in self._pool.submit(isolated):
+                    yield event
+            finally:
+                await self._workspaces.close_session(session, workspace)
 
     async def shutdown(self) -> None:
         await self._pool.shutdown()
+        shutdown_ws = getattr(self._workspaces, "shutdown", None)
+        if shutdown_ws is not None:
+            result = shutdown_ws()
+            if hasattr(result, "__await__"):
+                await result
         self._started = False

flowjet-2.0.10/src/flowjet/core/backends/isolation/boxlite_protocol.py

@@ -0,0 +1,161 @@
+"""JSON-lines protocol for boxlite container workers (Phase 3).
+
+Serializes :class:`IsolatedRunRequest` to JSON for transmission over the
+worker's stdin, and deserializes JSON event frames from the worker's stdout
+back into :data:`RuntimeEvent` objects.
+
+Wire format (one JSON object per line)::
+
+    {"type": "request", ...}        ← sent to worker stdin
+    {"type": "event", "event_type": "RunStarted", ...}
+    {"type": "done"}
+    {"type": "error", "message": "..."}
+    {"type": "cancelled"}
+    {"type": "ready"}              ← worker is ready for next request
+
+No external dependencies — only stdlib ``json`` and the flowjet event
+dataclasses.  This module is imported both by the pool (host side) and by
+the worker script (container side).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from flowjet.core.backends.isolation.request import IsolatedRunRequest
+from flowjet.core.events import (
+    InterruptWaiting,
+    Narration,
+    OutputTextDelta,
+    Progress,
+    RunCompleted,
+    RunFailed,
+    RunStarted,
+    RuntimeEvent,
+    ToolCompleted,
+    ToolStarted,
+    UsageInfo,
+)
+
+# Tag used in JSON frames to identify the event class.
+_EVENT_TYPE_TAG = "event_type"
+
+# Mapping from event type tag → constructor (for deserialization).
+_EVENT_REGISTRY: dict[str, type] = {
+    cls.__name__: cls
+    for cls in (
+        RunStarted,
+        Progress,
+        ToolStarted,
+        ToolCompleted,
+        Narration,
+        OutputTextDelta,
+        InterruptWaiting,
+        RunCompleted,
+        RunFailed,
+    )
+}
+
+
+# ---------------------------------------------------------------------------
+# Request serialization (host → worker)
+# ---------------------------------------------------------------------------
+
+
+def encode_request(req: IsolatedRunRequest) -> str:
+    """Serialize an :class:`IsolatedRunRequest` to a JSON-lines string."""
+    payload: dict[str, Any] = {
+        "type": "request",
+        "request_id": req.request_id,
+        "run_id": req.run_id,
+        "session": req.session,
+        "input_text": req.input_text,
+        "model": req.model,
+        "workspace": str(req.workspace),
+        "thread_id": req.thread_id,
+        "metadata": req.metadata,
+    }
+    return json.dumps(payload, ensure_ascii=False)
+
+
+# ---------------------------------------------------------------------------
+# Event serialization (worker → host)
+# ---------------------------------------------------------------------------
+
+
+def encode_event(event: RuntimeEvent) -> str:
+    """Serialize a :data:`RuntimeEvent` to a JSON-lines string."""
+    from dataclasses import asdict
+
+    data = asdict(event)  # type: ignore[arg-type]
+    data["type"] = "event"
+    data[_EVENT_TYPE_TAG] = type(event).__name__
+    return json.dumps(data, ensure_ascii=False)
+
+
+def decode_event(frame: dict[str, Any]) -> RuntimeEvent:
+    """Deserialize a JSON frame dict into a :data:`RuntimeEvent`.
+
+    Raises :class:`ValueError` for unknown event types.
+    """
+    event_type = frame.get(_EVENT_TYPE_TAG)
+    if event_type is None:
+        raise ValueError(f"frame missing {_EVENT_TYPE_TAG!r}: {frame!r}")
+    cls = _EVENT_REGISTRY.get(event_type)
+    if cls is None:
+        raise ValueError(f"unknown event type: {event_type!r}")
+    # Strip protocol-level keys before constructing the dataclass.
+    kwargs = {k: v for k, v in frame.items() if k not in ("type", _EVENT_TYPE_TAG)}
+    # Reconstruct nested dataclass fields (e.g. RunCompleted.usage → UsageInfo).
+    kwargs = _reconstruct_nested(kwargs)
+    return cls(**kwargs)  # type: ignore[call-arg]
+
+
+def _reconstruct_nested(kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Convert dict values back into nested dataclass instances where needed.
+
+    :func:`dataclasses.asdict` recursively converts nested dataclasses to
+    plain dicts.  This reverses that for known fields whose constructors
+    expect a dataclass, not a dict.
+    """
+    if "usage" in kwargs and isinstance(kwargs["usage"], dict):
+        kwargs["usage"] = UsageInfo(**kwargs["usage"])
+    return kwargs
+
+
+# ---------------------------------------------------------------------------
+# Control frame helpers
+# ---------------------------------------------------------------------------
+
+
+def make_control(frame_type: str, **fields: Any) -> str:
+    """Build a JSON-lines control frame (``done``, ``error``, etc.)."""
+    payload: dict[str, Any] = {"type": frame_type}
+    payload.update(fields)
+    return json.dumps(payload, ensure_ascii=False)
+
+
+def parse_frame(line: str) -> dict[str, Any]:
+    """Parse one JSON-lines frame from a worker's stdout."""
+    return json.loads(line)
+
+
+# ---------------------------------------------------------------------------
+# Request deserialization (worker side)
+# ---------------------------------------------------------------------------
+
+
+def decode_request(frame: dict[str, Any]) -> IsolatedRunRequest:
+    """Deserialize a JSON frame dict into an :class:`IsolatedRunRequest`."""
+    return IsolatedRunRequest(
+        run_id=frame["run_id"],
+        session=frame["session"],
+        input_text=frame["input_text"],
+        model=frame["model"],
+        workspace=Path(frame["workspace"]),
+        thread_id=frame.get("thread_id"),
+        metadata=frame.get("metadata"),
+        request_id=frame.get("request_id"),
+    )