generic-ml-cache-core 0.2.0__py3-none-any.whl

generic_ml_cache_core/__init__.py

@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""generic-ml-cache-core: the hexagonal core library.
+
+Record a real ML client (or API) call once, replay it forever by its content key.
+
+This is a stateless library: it holds the domain model, the use cases, the port
+contracts, AND the default outbound adapters (SQLite execution repository,
+filesystem blob store, local client runner, API client, metrics, clock,
+fingerprint). It bakes in *structure* (table names, blob naming, schema) but no
+*location* -- the data source (store path) and configuration are injected by the
+caller. Wire it with :func:`build_use_cases`, or construct the adapters and use
+cases directly. The CLI / a daemon / an embedding app are inbound drivers that
+supply the data source and map their surface onto this library.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("generic-ml-cache-core")
+except PackageNotFoundError:  # running from an uninstalled source tree
+    __version__ = "0+unknown"
+
+from generic_ml_cache_core.adapter.inbound.composition import (  # noqa: E402  # fmt: skip
+    WiredUseCases,
+    build_use_cases,
+)
+from generic_ml_cache_core.adapter.out.client import (  # noqa: E402  # fmt: skip
+    ClientAdapter,
+    get_adapter,
+    register,
+)
+from generic_ml_cache_core.common.checksum import (  # noqa: E402  # fmt: skip
+    checksum_input_data,
+    file_content_fingerprint,
+    text_checksum,
+)
+from generic_ml_cache_core.common.errors import (  # noqa: E402  # fmt: skip
+    CacheError,
+    CacheMiss,
+    ClientNotFound,
+    RunInterrupted,
+    UnknownClient,
+)
+
+__all__ = [
+    "__version__",
+    "build_use_cases",
+    "WiredUseCases",
+    "register",
+    "get_adapter",
+    "ClientAdapter",
+    "checksum_input_data",
+    "text_checksum",
+    "file_content_fingerprint",
+    "CacheError",
+    "CacheMiss",
+    "ClientNotFound",
+    "RunInterrupted",
+    "UnknownClient",
+]

generic_ml_cache_core/adapter/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/adapter/inbound/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/adapter/inbound/composition.py

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""The composition root: build the real adapters and wire the use cases.
+
+This is the *only* place that names every concrete adapter. It reads where to
+store things, constructs the outbound adapters, and hands them to the use-case
+services through their constructors. A driving adapter (the CLI) asks for the
+wired use cases and depends only on the inbound ports.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+from generic_ml_cache_core.adapter.out.api.stub_api_client_adapter import StubApiClientAdapter
+from generic_ml_cache_core.adapter.out.client.local_client_runner import LocalClientRunner
+from generic_ml_cache_core.adapter.out.client.passthrough_client_runner import (
+    PassthroughClientRunner,
+)
+from generic_ml_cache_core.adapter.out.clock.system_clock import SystemClock
+from generic_ml_cache_core.adapter.out.fingerprint.filesystem_file_fingerprint import (
+    FilesystemFileFingerprint,
+)
+from generic_ml_cache_core.adapter.out.metrics.access_registry import AccessRegistry
+from generic_ml_cache_core.adapter.out.metrics.journal_metrics import JournalMetrics
+from generic_ml_cache_core.adapter.out.persistence.sqlite_execution_repository import (
+    SqliteExecutionRepository,
+)
+from generic_ml_cache_core.adapter.out.storage.filesystem_blob_store import FilesystemBlobStore
+from generic_ml_cache_core.application.usecase.probe_service import ProbeService
+from generic_ml_cache_core.application.usecase.run_api_execution_service import (
+    RunApiExecutionService,
+)
+from generic_ml_cache_core.application.usecase.run_managed_local_execution_service import (
+    RunManagedLocalExecutionService,
+)
+from generic_ml_cache_core.application.usecase.run_passthrough_execution_service import (
+    RunPassthroughExecutionService,
+)
+
+_BLOBS_DIRNAME = "blobs"
+_EXECUTIONS_DB = "executions.sqlite3"
+
+#: given a client name, the executable override to use, or None for the default.
+ExecutableOverride = Callable[[str], Optional[str]]
+
+
+@dataclass(frozen=True)
+class WiredUseCases:
+    """The use cases a driving adapter needs, plus the stores the read-only CLI
+    views (inspect/stats/list) query directly."""
+
+    run_managed: RunManagedLocalExecutionService
+    run_passthrough: RunPassthroughExecutionService
+    run_api: RunApiExecutionService
+    probe: ProbeService
+    blob_store: FilesystemBlobStore
+    repository: SqliteExecutionRepository
+    metrics: JournalMetrics
+
+
+def build_use_cases(
+    store_root: Path,
+    executable_override: Optional[ExecutableOverride] = None,
+    timeout: Optional[float] = None,
+) -> WiredUseCases:
+    """Construct the outbound adapters under ``store_root`` and wire the services.
+
+    Layout: ``store_root/blobs/`` for output bytes, ``store_root/executions.sqlite3``
+    for the structured records, and the access-event registry beside them.
+    """
+    store_root = Path(store_root)
+    clock = SystemClock()
+    blob_store = FilesystemBlobStore(store_root / _BLOBS_DIRNAME)
+    repository = SqliteExecutionRepository(store_root / _EXECUTIONS_DB, clock)
+    metrics = JournalMetrics(AccessRegistry(store_root))
+    file_fingerprint = FilesystemFileFingerprint()
+    local_runner = LocalClientRunner(executable_override, timeout)
+    passthrough_runner = PassthroughClientRunner(executable_override, timeout)
+    api_client = StubApiClientAdapter()
+
+    return WiredUseCases(
+        run_managed=RunManagedLocalExecutionService(
+            file_fingerprint, local_runner, blob_store, repository, metrics
+        ),
+        run_passthrough=RunPassthroughExecutionService(
+            passthrough_runner, blob_store, repository, metrics
+        ),
+        run_api=RunApiExecutionService(api_client, blob_store, repository, metrics),
+        probe=ProbeService(file_fingerprint, repository),
+        blob_store=blob_store,
+        repository=repository,
+        metrics=metrics,
+    )

generic_ml_cache_core/adapter/out/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/adapter/out/api/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/adapter/out/api/stub_api_client_adapter.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""StubApiClientAdapter: a deterministic, offline stand-in for a provider API."""
+
+from __future__ import annotations
+
+from typing import List
+
+from generic_ml_cache_core.application.domain.model.run.client_run_result import ClientRunResult
+from generic_ml_cache_core.application.domain.model.run.message import Message
+from generic_ml_cache_core.application.domain.model.usage.token_usage import TokenUsage
+from generic_ml_cache_core.application.port.out.api_client_port import ApiClientPort
+
+
+class StubApiClientAdapter(ApiClientPort):
+    """A deterministic stand-in for a real provider API.
+
+    It runs everywhere — including CI, where no provider is reachable — by
+    synthesising a reply from the inputs: stdout echoes the last message, and the
+    token usage is a deterministic function of the message sizes. Same inputs ->
+    same result, so it behaves correctly under caching. Swap in a real adapter
+    when one exists; the port contract is identical.
+    """
+
+    def run(self, provider: str, model: str, messages: List[Message]) -> ClientRunResult:
+        last_content = messages[-1].content if messages else ""
+        reply = f"[stub:{provider}:{model}] {last_content}"
+        input_tokens = sum(len(message.content) for message in messages)
+        token_usage = TokenUsage(input_tokens=input_tokens, output_tokens=len(reply))
+        return ClientRunResult(exit_code=0, stdout=reply, token_usage=token_usage)

generic_ml_cache_core/adapter/out/client/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Client adapters.
+
+Importing this package registers the built-in adapters. The Claude adapter is
+registered eagerly. Codex and Cursor are also registered so all three v0.0.1
+clients are available out of the box; their flag mappings are best-effort and
+documented as such.
+"""
+
+from __future__ import annotations
+
+from generic_ml_cache_core.adapter.out.client.codex import CodexAdapter
+from generic_ml_cache_core.adapter.out.client.cursor import CursorAdapter
+from generic_ml_cache_core.adapter.out.client.registry import (
+    get_adapter,
+    register,
+    registered_names,
+)
+from generic_ml_cache_core.application.port.out.base import ClientAdapter
+
+# Eager registration of the built-in adapters.
+from . import claude  # noqa: F401  (registers ClaudeAdapter)
+
+register(CodexAdapter())
+register(CursorAdapter())
+
+__all__ = ["ClientAdapter", "get_adapter", "register", "registered_names"]

generic_ml_cache_core/adapter/out/client/claude.py

@@ -0,0 +1,214 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Adapter for Anthropic's Claude Code CLI (headless / print mode).
+
+Treat the exact flags as configuration, not gospel -- override the executable
+with the seam and adjust here if the CLI changes.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from generic_ml_cache_core.adapter.out.client.registry import register
+from generic_ml_cache_core.application.domain.model.parsed_output import ParsedOutput
+from generic_ml_cache_core.application.domain.model.usage.usage import (
+    Usage,
+    float_or_none,
+    int_or_none,
+)
+from generic_ml_cache_core.application.port.out.base import (
+    ClientAdapter,
+    ensure_trailing_newline,
+    final_result_object,
+)
+
+
+class ClaudeAdapter(ClientAdapter):
+    name = "claude"
+    default_executable = "claude"
+
+    def build_argv(
+        self,
+        executable,
+        run_dir,
+        model,
+        effort,
+        context,
+        prompt,
+        system_prompt,
+        client_args=(),
+        grants=(),
+    ) -> List[str]:
+        # The prompt and context are delivered on stdin (see stdin_payload), never
+        # as an argv argument, so an arbitrarily large prompt cannot hit the OS
+        # single-argument size limit. With -p/--print and no prompt argument,
+        # Claude reads the prompt from stdin.
+        # Capability doors (write/read/shell/net/web-search) now live in a config
+        # FILE written by grant_setup into CLAUDE_CONFIG_DIR -- not in argv.
+        # build_argv carries only transport: print mode, model, effort, the system
+        # prompt, JSON output (so usage comes back), and the verbatim passthrough.
+        argv = [executable, "-p", "--model", model]
+        # Effort is optional: when omitted, let Claude apply its own per-model
+        # default rather than passing an empty (and invalid) --effort value.
+        if effort:
+            argv += ["--effort", effort]
+        # Streaming output mode (one NDJSON event per line) so a live consumer can
+        # watch progress; the recorded answer + usage are lifted from the final
+        # `result` event, which is byte-identical to the old single-object json
+        # (proven against the live CLI), so the stored output is unchanged. --verbose is
+        # required for stream-json to emit the full stream; --include-partial-
+        # messages adds token-level deltas for the live feed.
+        argv += [
+            "--append-system-prompt",
+            system_prompt,
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--include-partial-messages",
+        ]
+        # Passthrough args go last: Claude takes the prompt on stdin, so there is no
+        # trailing positional to sit in front of. Appended verbatim, uninterpreted.
+        argv += client_args
+        return argv
+
+    def parse_output(self, stdout: str) -> ParsedOutput:
+        """Claude's headless JSON is a single object: ``result`` is the answer
+        text, ``usage`` holds the (primary-model) token counts, ``total_cost_usd``
+        is the cumulative cost estimate across every model the run used, and
+        ``modelUsage`` breaks it down per model (the main model plus any subagent
+        models). The per-model breakdown is kept verbatim in ``raw``; the
+        normalized counts come from the headline ``usage`` block, the cost from the
+        cumulative ``total_cost_usd``.
+        """
+        try:
+            doc = final_result_object(stdout)
+            if not isinstance(doc, dict):
+                raise ValueError("no result object")
+        except (json.JSONDecodeError, ValueError):
+            return ParsedOutput(text=stdout, usage=None)
+
+        text = doc.get("result")
+        if not isinstance(text, str):
+            # Not the shape we expected -- keep the raw output, skip usage.
+            return ParsedOutput(text=stdout, usage=None)
+
+        block = doc.get("usage") if isinstance(doc.get("usage"), dict) else {}
+        raw: Dict[str, Any] = {}
+        for key in ("usage", "modelUsage", "total_cost_usd"):
+            if key in doc:
+                raw[key] = doc[key]
+
+        usage = Usage(
+            input_tokens=int_or_none(block.get("input_tokens")),
+            output_tokens=int_or_none(block.get("output_tokens")),
+            cache_read_tokens=int_or_none(block.get("cache_read_input_tokens")),
+            cache_write_tokens=int_or_none(block.get("cache_creation_input_tokens")),
+            # Claude folds reasoning into output_tokens; it is not separable here.
+            reasoning_tokens=None,
+            cost_usd=float_or_none(doc.get("total_cost_usd")),
+            raw=raw,
+        )
+        return ParsedOutput(text=ensure_trailing_newline(text), usage=usage)
+
+    def stdin_payload(self, context, prompt, system_prompt) -> Optional[str]:
+        # Prompt + context go to the client on stdin. The system prompt is a
+        # separate, small argv flag (--append-system-prompt), so it stays in argv.
+        return f"{context}\n\n{prompt}" if context else prompt
+
+    def read_access_argv(self, paths):
+        # Claude Code grants read access to extra directories via --add-dir.
+        argv = []
+        for p in paths:
+            argv += ["--add-dir", p]
+        return argv
+
+    def grant_setup(self, run_dir, config_home, grants):
+        # Uniform door: write settings.json into a redirected CLAUDE_CONFIG_DIR so
+        # the FILE (not a flag) enables capabilities. Verified against the live CLI:
+        # the redirected home governs because the run folder is clean of a project
+        # .claude/ that would outrank it. acceptEdits + Write/Edit are always on so
+        # a file-producing call actually writes (the record-path guarantee); each
+        # named grant ADDS its allow-token. The cache enables; it never closes
+        # (docs/reference/grants.md).
+        allow = ["Write(**)", "Edit(**)"]
+        if "read" in grants:
+            allow.append("Read(**)")
+        if "shell" in grants:
+            allow.append("Bash(**)")
+        if "net" in grants:
+            allow.append("WebFetch")
+        if "web-search" in grants:
+            allow.append("WebSearch")
+        settings = {"permissions": {"allow": allow}, "defaultMode": "acceptEdits"}
+        config_home.mkdir(parents=True, exist_ok=True)
+        (config_home / "settings.json").write_text(json.dumps(settings), encoding="utf-8")
+        # Seed credentials so the relocated home is authenticated. Subscription
+        # login lives in ~/.claude; an API key in the env carries over on its own.
+        # Bulk caches (projects/history/todos/shell-snapshots) are skipped; a stray
+        # settings.local.json would outrank ours, so it is dropped.
+        src = Path.home() / ".claude"
+        if src.is_dir():
+            skip = {
+                "projects",
+                "history",
+                "todos",
+                "shell-snapshots",
+                "settings.json",
+                "settings.local.json",
+            }
+            for child in src.iterdir():
+                if child.name in skip:
+                    continue
+                dest = config_home / child.name
+                try:
+                    if child.is_dir():
+                        shutil.copytree(child, dest, dirs_exist_ok=True)
+                    else:
+                        shutil.copy2(child, dest)
+                except OSError:
+                    pass  # best-effort seeding; an env API key still authenticates
+        # Claude Code also keeps a top-level ~/.claude.json (account, onboarding,
+        # project trust) BESIDE the ~/.claude dir; under a redirected CLAUDE_CONFIG_DIR
+        # it is expected at <home>/.claude.json. Seed it too, or Claude Code finds no
+        # main config, writes a fresh default and backs it up, and warns once per
+        # internal phase (harmless but noisy). Deleted with the run like the rest.
+        main_config = Path.home() / ".claude.json"
+        if main_config.is_file():
+            try:
+                shutil.copy2(main_config, config_home / ".claude.json")
+            except OSError:
+                pass  # best-effort; the run still proceeds without it (just noisy)
+        return {"CLAUDE_CONFIG_DIR": str(config_home)}
+
+    def stream_event(self, raw_line):
+        try:
+            d = json.loads(raw_line)
+        except (json.JSONDecodeError, ValueError):
+            return None
+        if not isinstance(d, dict):
+            return None
+        t = d.get("type")
+        if t == "system":
+            sub = d.get("subtype")
+            if sub == "init":
+                return {"kind": "start"}
+            if sub == "thinking_tokens":
+                return {"kind": "thinking"}
+            return None
+        if t == "stream_event":
+            ev = d.get("event")
+            if isinstance(ev, dict) and ev.get("type") == "content_block_start":
+                block = ev.get("content_block")
+                if isinstance(block, dict) and block.get("type") == "tool_use":
+                    return {"kind": "tool", "name": block.get("name")}
+            return None
+        if t == "result":
+            return {"kind": "result"}
+        return None
+
+
+register(ClaudeAdapter())

generic_ml_cache_core/adapter/out/client/codex.py

@@ -0,0 +1,171 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Adapter for OpenAI's Codex CLI (non-interactive).
+
+Effort maps to ``model_reasoning_effort``. Flags
+are best-effort for v0.0.1 and are easy to correct here; the executable seam
+lets you point at any binary.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from generic_ml_cache_core.application.domain.model.parsed_output import ParsedOutput
+from generic_ml_cache_core.application.domain.model.usage.usage import Usage, int_or_none
+from generic_ml_cache_core.application.port.out.base import (
+    ClientAdapter,
+    ensure_trailing_newline,
+)
+
+
+class CodexAdapter(ClientAdapter):
+    name = "codex"
+    default_executable = "codex"
+
+    def build_argv(
+        self,
+        executable,
+        run_dir,
+        model,
+        effort,
+        context,
+        prompt,
+        system_prompt,
+        client_args=(),
+        grants=(),
+    ) -> List[str]:
+        # Capability doors (sandbox write, network, web-search) now live in
+        # $CODEX_HOME/config.toml written by grant_setup -- not in argv. build_argv
+        # carries only transport: the exec subcommand, JSON events, the no-git-repo
+        # escape and the cwd fence, model + effort, the system prompt, passthrough,
+        # and the trailing stdin marker.
+        argv = [
+            executable,
+            "exec",
+            "--json",
+            "--skip-git-repo-check",
+            "-C",
+            str(run_dir),
+            "--model",
+            model,
+        ]
+        # Effort is optional: when omitted, leave model_reasoning_effort unset so
+        # Codex uses the model's own default instead of an empty override.
+        if effort:
+            argv += ["-c", f"model_reasoning_effort={effort}"]
+        # The prompt + context are delivered on stdin (see stdin_payload), so a
+        # large prompt cannot exceed the OS argument-size limit. The trailing "-"
+        # tells `codex exec` to read the prompt from stdin instead of an argv
+        # argument; communicate() then closes stdin on EOF, which also avoids the
+        # "reading additional input from stdin" hang codex shows in a non-TTY child
+        # when a prompt argument is given but stdin is left open. The system prompt
+        # is a small config value and stays in argv.
+        argv += ["-c", f"experimental_instructions={system_prompt}"]
+        # Passthrough args before the trailing "-" (the stdin marker, codex's last
+        # positional), so they are still parsed as flags. Appended verbatim.
+        argv += client_args
+        argv.append("-")
+        return argv
+
+    def stdin_payload(self, context, prompt, system_prompt) -> Optional[str]:
+        return f"{context}\n\n{prompt}" if context else prompt
+
+    def parse_output(self, stdout: str) -> ParsedOutput:
+        """Codex's ``--json`` output is a JSON-lines *stream* of events, one per
+        line. The answer text is the ``text`` of the final ``agent_message`` item;
+        the usage is the ``usage`` block on the final ``turn.completed`` event.
+        Codex reports reasoning tokens *separately* from output, reports no
+        cache-write count (so that stays unknown), and reports no cost.
+        """
+        answer: Optional[str] = None
+        usage_block: Optional[Dict[str, Any]] = None
+        for line in stdout.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue  # tolerate a stray non-JSON line in the stream
+            if not isinstance(event, dict):
+                continue
+            if event.get("type") == "item.completed":
+                item = event.get("item")
+                if isinstance(item, dict) and item.get("type") == "agent_message":
+                    text = item.get("text")
+                    if isinstance(text, str):
+                        answer = text  # keep the latest; the final one is the answer
+            elif event.get("type") == "turn.completed":
+                block = event.get("usage")
+                if isinstance(block, dict):
+                    usage_block = block
+
+        if answer is None:
+            # Never found the answer event -- hand back the raw stream, no usage.
+            return ParsedOutput(text=stdout, usage=None)
+
+        usage = None
+        if usage_block is not None:
+            usage = Usage(
+                input_tokens=int_or_none(usage_block.get("input_tokens")),
+                output_tokens=int_or_none(usage_block.get("output_tokens")),
+                cache_read_tokens=int_or_none(usage_block.get("cached_input_tokens")),
+                # Codex reports no cache-write count: unknown, not zero.
+                cache_write_tokens=None,
+                reasoning_tokens=int_or_none(usage_block.get("reasoning_output_tokens")),
+                cost_usd=None,
+                raw=dict(usage_block),
+            )
+        return ParsedOutput(text=ensure_trailing_newline(answer), usage=usage)
+
+    def grant_setup(self, run_dir, config_home, grants):
+        # Uniform door: write $CODEX_HOME/config.toml so the FILE enables
+        # capabilities. The run folder is untrusted (a fresh temp dir), so a
+        # folder-local .codex/config.toml would be skipped -- we redirect the home
+        # instead and seed auth.json into it. workspace-write is always on (the
+        # record-path guarantee); it already permits read + shell, so granting
+        # those needs nothing extra (Codex exposes no file-level read/shell *deny*
+        # -- a documented limit, not a door we close). net flips network_access on;
+        # web-search sets web_search=live. The cache enables (docs/reference/grants.md).
+        lines = ['approval_policy = "never"', 'sandbox_mode = "workspace-write"']
+        if "web-search" in grants:
+            lines.append('web_search = "live"')
+        if "net" in grants:
+            lines += ["[sandbox_workspace_write]", "network_access = true"]
+        config_home.mkdir(parents=True, exist_ok=True)
+        (config_home / "config.toml").write_text("\n".join(lines) + "\n", encoding="utf-8")
+        auth = Path.home() / ".codex" / "auth.json"
+        if auth.is_file():
+            try:
+                shutil.copy2(auth, config_home / "auth.json")
+            except OSError:
+                pass  # best-effort; an env API key still authenticates the run
+        return {"CODEX_HOME": str(config_home)}
+
+    def stream_event(self, raw_line):
+        try:
+            ev = json.loads(raw_line)
+        except (json.JSONDecodeError, ValueError):
+            return None
+        if not isinstance(ev, dict):
+            return None
+        t = ev.get("type")
+        if t == "thread.started":
+            return {"kind": "start"}
+        if t == "turn.completed":
+            return {"kind": "result"}
+        if t in ("error", "turn.failed"):
+            return {"kind": "error"}
+        if t == "item.completed":
+            item = ev.get("item")
+            if isinstance(item, dict):
+                it = item.get("type")
+                if it == "agent_message":
+                    return {"kind": "message"}
+                if it:
+                    return {"kind": "tool", "name": it}
+        return None