callai-cli 0.9.0__py3-none-any.whl

callai/adapters/grok.py

@@ -0,0 +1,207 @@
+"""Adapter for xAI's Grok Build CLI (``grok --output-format json --single=PROMPT``)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..errors import UsageError
+from ..request import Request
+from ..result import Completed, Result
+from .base import Adapter, content_text, json_line, jsonl_events, strip_ansi, tool_result, tool_use
+
+# Verified against grok 1.0.70 with scripted tool calls from the stub (write, edit, shell). A headless
+# run refuses (and cancels the turn on) any call that needs approval, so "default" already blocks
+# writes and shell. read-only also removes every tool but grok's read tools; --tools keeps
+# search_tool/use_tool (the gateway to MCP and deferred tools), so those are removed explicitly.
+# auto uses allow rules: grok accepts --permission-mode acceptEdits but still refused a headless write,
+# and --permission-mode auto lets a model-based safety check approve calls (shell included).
+_PERMISSION_FLAGS: dict[str, list[str]] = {
+    "default": [],
+    "read-only": ["--tools", "read_file,grep,list_dir", "--disallowed-tools", "search_tool,use_tool"],
+    "auto": ["--allow", "Write", "--allow", "Edit"],  # writes and edits yes; shell etc. refused
+    "bypass": ["--permission-mode", "bypassPermissions"],
+}
+
+
+class Grok(Adapter):
+    """``grok --output-format json`` — parses the single JSON result object."""
+
+    name = "grok"
+    binary = "grok"
+    install_url = "https://x.ai/cli"
+
+    def build_argv(self, req: Request) -> list[str]:
+        """Build the ``grok`` command line.
+
+        grok's ``-p``/``--single`` has no ``--`` escape (``-p --help`` is a parser error), so the prompt
+        goes last as one ``--single=PROMPT`` element, which takes any text as the value.
+
+        Args:
+            req: The request to run.
+
+        ``-o stream-json`` uses ``--output-format streaming-json`` (JSON lines; see :meth:`parse`).
+
+        Returns:
+            The argv list, prompt last.
+
+        Raises:
+            UsageError: If the prompt starts with ``/``, which grok runs as a slash command.
+        """
+        if req.prompt.lstrip().startswith("/"):
+            raise UsageError(
+                "grok runs a prompt starting with '/' as a slash command (e.g. /compact), even after "
+                "leading spaces, and has no escape; start the prompt with other text"
+            )
+        fmt = "streaming-json" if req.output_format == "stream-json" else "json"
+        argv = [self.binary, "--output-format", fmt]
+        if req.model:
+            argv += ["--model", req.model]
+        argv += _PERMISSION_FLAGS[req.permission]
+        if req.system_prompt is not None:
+            argv += ["--system-prompt-override", req.system_prompt]
+        return [*argv, *_session_flags(req), *req.extra_args, f"--single={req.prompt}"]
+
+    def parse(self, completed: Completed, req: Request) -> Result:
+        """Parse the JSON object printed by ``grok --output-format json`` (or rebuilt from ``streaming-json``).
+
+        Success is ``{"text", "stopReason": "end_turn", "sessionId", "usage", "modelUsage", ...}``.
+        Failure is ``{"type": "error", "message"}`` (also on stderr, exit 1), or a result whose
+        ``stopReason`` isn't ``end_turn``: ``cancelled`` when grok refused a tool call that needs
+        approval (exit **0**), ``max_turn_requests`` for ``--max-turns`` (exit 1). Those carry no
+        text; the reason is on stderr.
+
+        Args:
+            completed: Raw process outcome.
+            req: The request that produced it.
+
+        Returns:
+            The normalised result.
+        """
+        obj = _result_object(completed.stdout)
+        is_error_obj = isinstance(obj, dict) and obj.get("type") == "error"
+        text = obj.get("message" if is_error_obj else "text") if isinstance(obj, dict) else None
+        if not isinstance(text, str):  # no JSON result (e.g. a crash): the reason is on stderr
+            text = strip_ansi(completed.stderr).strip() or strip_ansi(completed.stdout).strip()
+            return self.text_result(completed, req).with_updates(text=text, is_error=True)
+        stop = obj.get("stopReason")
+        failed = is_error_obj or completed.exit_code != 0 or stop not in (None, "end_turn")
+        if failed and not text:
+            text = strip_ansi(completed.stderr).strip() or str(stop or "")
+        cost = obj.get("total_cost_usd")
+        return Result(
+            harness_name=self.name,
+            model=_model(obj.get("modelUsage")) or req.model,
+            text=text,
+            exit_code=completed.exit_code,
+            is_error=failed,
+            duration_ms=completed.duration_ms,
+            session_id=obj.get("sessionId"),
+            usage=_usage(obj.get("usage")),
+            cost_usd=cost if isinstance(cost, int | float) else None,
+            argv=completed.argv,
+            raw_stdout=completed.stdout,
+            raw_stderr=completed.stderr,
+        )
+
+    def stream_events(self, line: str, state: dict[str, Any]) -> list[dict[str, Any]]:
+        """Map a ``grok --output-format streaming-json`` line: text pieces and tool calls.
+
+        A call is reported from ``tool_call`` and its result from the ``tool_call_update`` whose
+        status is ``completed`` or ``failed`` (a refused call fails with "User cancelled ...").
+
+        Args:
+            line: One stdout line.
+            state: Unused.
+
+        Returns:
+            The events.
+        """
+        data = json_line(line)
+        kind = data.get("type") if data else None
+        if kind == "text":
+            return [{"type": "text", "text": data.get("data", "")}]
+        if kind == "tool_call":
+            return [tool_use(data.get("toolCallId"), data.get("toolName"), data.get("rawInput"))]
+        if kind == "tool_call_update" and data.get("status") in ("completed", "failed"):
+            blocks = data.get("content") if isinstance(data.get("content"), list) else []
+            output = "".join(content_text([b.get("content")]) for b in blocks if isinstance(b, dict))
+            return [tool_result(data.get("toolCallId"), data["status"] == "failed", output)]
+        return []
+
+
+def _result_object(stdout: str) -> dict[str, Any] | None:
+    """The run's result object, from ``--output-format json`` or ``streaming-json`` output.
+
+    json mode prints one object. streaming-json prints JSON lines: ``text`` pieces, then an ``end``
+    object that is the json-mode object without ``text``, or the same ``{"type": "error"}`` object.
+
+    Args:
+        stdout: grok's stdout.
+
+    Returns:
+        The object (for a stream, ``end`` with the joined text added), or ``None`` if there is none.
+    """
+    try:
+        whole = json.loads(stdout)
+    except ValueError:
+        whole = None
+    if isinstance(whole, dict) and whole.get("type") != "end":
+        return whole
+    events = jsonl_events(stdout)
+    last = next((e for e in reversed(events) if e.get("type") in ("end", "error")), None)
+    if last is None or last["type"] == "error":
+        return last
+    text = "".join(e["data"] for e in events if e.get("type") == "text" and isinstance(e.get("data"), str))
+    return {**last, "text": text}
+
+
+def _usage(raw: Any) -> dict[str, int] | None:
+    """Normalise grok's usage; its ``input_tokens`` excludes cache reads and writes, so add them back.
+
+    Args:
+        raw: The result's ``usage`` object.
+
+    Returns:
+        ``{"input_tokens", "output_tokens"}`` or ``None``.
+    """
+    if not isinstance(raw, dict):
+        return None
+    keys = ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens")
+    return {
+        "input_tokens": sum(int(raw.get(k) or 0) for k in keys),
+        "output_tokens": int(raw.get("output_tokens") or 0),
+    }
+
+
+def _model(model_usage: Any) -> str | None:
+    """The model that did most of the work, by tokens, from ``modelUsage``.
+
+    Args:
+        model_usage: The result's ``modelUsage`` object (model id → counts).
+
+    Returns:
+        The model id, or ``None`` if none is reported.
+    """
+    if not isinstance(model_usage, dict):
+        return None
+    sizes = {
+        m: int(u.get("inputTokens") or 0) + int(u.get("outputTokens") or 0)
+        for m, u in model_usage.items()
+        if isinstance(u, dict)
+    }
+    return max(sizes, key=sizes.__getitem__) if sizes else None
+
+
+def _session_flags(req: Request) -> list[str]:
+    """The harness's flags for ``--resume ID`` / ``--continue`` (none for a new session).
+
+    Args:
+        req: The request.
+
+    Returns:
+        The flags.
+    """
+    if req.resume is not None:
+        return [f"--resume={req.resume}"]
+    return ["--continue"] if req.continue_session else []

callai/adapters/hermes.py

@@ -0,0 +1,112 @@
+"""Adapter for Nous Research's Hermes Agent (``hermes chat -Q --query=PROMPT``)."""
+
+from __future__ import annotations
+
+import re
+
+from ..errors import UsageError
+from ..request import Request
+from ..result import Completed, Result
+from .base import Adapter, strip_ansi
+
+# Verified against hermes-agent 0.19.0 with scripted tool calls from the stub. hermes runs file writes
+# and ordinary shell commands without asking; only "dangerous" commands need approval, which a
+# non-interactive run denies on timeout. -t takes toolset names, and no toolset is read-only.
+_PERMISSION_FLAGS: dict[str, list[str]] = {
+    "default": [],
+    "auto": ["-t", "file"],  # read_file, write_file, patch, search_files: edits yes, shell no
+    "bypass": ["--yolo"],
+}
+_SESSION_RE = re.compile(r"^session_id: (\S+)$", re.MULTILINE)
+
+
+class Hermes(Adapter):
+    """``hermes chat -Q`` — the answer is stdout minus hermes's display lines."""
+
+    name = "hermes"
+    binary = "hermes"
+    install_url = "https://hermes-agent.nousresearch.com/docs/"
+
+    def build_argv(self, req: Request) -> list[str]:
+        """Build the ``hermes`` command line.
+
+        Not ``hermes -z``: one-shot mode auto-approves every tool call. ``--source tool`` keeps callai
+        runs out of the user's session list. The prompt goes last as one ``--query=PROMPT`` element,
+        so a prompt starting with ``-`` can't be read as an option.
+
+        Args:
+            req: The request to run.
+
+        Returns:
+            The argv list, prompt last.
+
+        Raises:
+            UsageError: For ``--permission read-only`` (no read-only toolset) or ``--continue`` (hermes
+                would continue the user's interactive session, not callai's last run).
+        """
+        if req.permission == "read-only":
+            raise UsageError(
+                "--permission read-only: hermes has no read-only toolset (its `file` toolset can write); "
+                "use the default or --permission auto"
+            )
+        if req.continue_session:
+            raise UsageError(
+                "--continue: hermes only continues its most recent interactive session, not callai's runs; "
+                "use --resume with the session_id callai reported"
+            )
+        argv = [self.binary, "chat", "-Q", "--source", "tool"]
+        if req.model:
+            argv += ["-m", req.model]
+        argv += _PERMISSION_FLAGS[req.permission]
+        return [*argv, *_session_flags(req), *req.extra_args, f"--query={req.prompt}"]
+
+    def build_env(self, req: Request) -> dict[str, str]:
+        """Pass ``--system-prompt`` as ``HERMES_EPHEMERAL_SYSTEM_PROMPT``.
+
+        hermes has no flag for it; it reads this variable (before ``agent.system_prompt`` in its
+        config) and never saves it to the session history.
+
+        Args:
+            req: The request to run.
+
+        Returns:
+            The variable when a system prompt is given, else nothing (an inherited one is kept).
+        """
+        return {} if req.system_prompt is None else {"HERMES_EPHEMERAL_SYSTEM_PROMPT": req.system_prompt}
+
+    def parse(self, completed: Completed, req: Request) -> Result:
+        r"""Parse ``hermes chat -Q`` output.
+
+        hermes prints the answer with a plain ``print`` (``\n`` line ends) after the run. Its display
+        lines (tool diff previews, warnings, "denying command") go through prompt_toolkit and end in
+        ``\r\n``, so those are dropped. The session id is on stderr. Failure is a non-zero exit, or
+        no answer at all, whose reason ("Error: ...") is then on stderr.
+
+        Args:
+            completed: Raw process outcome.
+            req: The request that produced it.
+
+        Returns:
+            The normalised result.
+        """
+        answer = "".join(line for line in completed.stdout.splitlines(keepends=True) if not line.endswith("\r\n"))
+        text = strip_ansi(answer).strip()
+        failed = completed.exit_code != 0 or not text
+        if not text:
+            text = strip_ansi(_SESSION_RE.sub("", completed.stderr)).strip()
+        match = _SESSION_RE.search(completed.stderr)
+        return self.text_result(completed, req).with_updates(
+            text=text, is_error=failed, session_id=match.group(1) if match else None
+        )
+
+
+def _session_flags(req: Request) -> list[str]:
+    """The harness's flag for ``--resume ID`` (``--continue`` is refused in ``build_argv``).
+
+    Args:
+        req: The request.
+
+    Returns:
+        The flags.
+    """
+    return ["--resume", req.resume] if req.resume is not None else []

callai/adapters/opencode.py

@@ -0,0 +1,186 @@
+"""Adapter for the opencode CLI (``opencode run``)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..errors import UsageError
+from ..request import Request
+from ..result import Completed, Result
+from .base import Adapter, json_line, jsonl_events, tool_result, tool_use
+
+# Verified against opencode 1.19.5. Levels opencode cannot honour fail closed (DESIGN.md §7).
+_PERMISSION_FLAGS: dict[str, list[str]] = {"default": [], "bypass": ["--auto"]}
+_UNSUPPORTED_PERMISSION = {
+    "read-only": "opencode has no read-only mode (its plan agent still allows shell commands); "
+    "pass `-- --agent plan` yourself if that is acceptable",
+    "auto": "opencode has no 'auto-approve edits only' mode (--auto approves everything); "
+    "use --permission bypass or the default",
+}
+# `--print-logs --log-level ERROR` puts the real failure reason on stderr, e.g.
+#   level=ERROR ... error="ProviderModelNotFoundError: Model not found: ..." cause="..."
+_ERROR_LOG_RE = re.compile(r'level=ERROR\b.*?\berror="((?:[^"\\]|\\.)*)"')
+
+
+class OpenCode(Adapter):
+    """``opencode run --format json`` — parses the JSONL event stream."""
+
+    name = "opencode"
+    binary = "opencode"
+    install_url = "https://opencode.ai/docs/"
+
+    def build_argv(self, req: Request) -> list[str]:
+        """Build the ``opencode run`` command line.
+
+        opencode wraps every message argument that contains a space in literal quotes before sending
+        it to the model, so the prompt is passed split on single spaces; opencode joins the pieces
+        with single spaces, which rebuilds the prompt exactly (all of it after ``--``).
+
+        Args:
+            req: The request to run.
+
+        Returns:
+            The argv list.
+
+        Raises:
+            UsageError: For permission levels or a system prompt opencode cannot honour.
+        """
+        if req.permission in _UNSUPPORTED_PERMISSION:
+            raise UsageError(f"--permission {req.permission}: {_UNSUPPORTED_PERMISSION[req.permission]}")
+        if req.system_prompt is not None:
+            raise UsageError("opencode run has no system prompt option; drop --system-prompt")
+        argv = [self.binary, "run", "--format", "json", "--print-logs", "--log-level", "ERROR"]
+        if req.model:
+            argv += ["--model", req.model]
+        argv += _PERMISSION_FLAGS[req.permission]
+        return [*argv, *_session_flags(req), *req.extra_args, "--", *req.prompt.split(" ")]
+
+    def parse(self, completed: Completed, req: Request) -> Result:
+        """Parse the JSONL events of ``opencode run --format json``.
+
+        The answer is the text of the last step (earlier steps precede tool calls); tokens and cost
+        are summed over all steps. An ``error`` event or a non-zero exit is a failure, reported with
+        the ERROR log line from stderr when there is one (the event itself is often generic).
+
+        Args:
+            completed: Raw process outcome.
+            req: The request that produced it.
+
+        Returns:
+            The normalised result.
+        """
+        events = jsonl_events(completed.stdout)
+        if not events:
+            return self.text_result(completed, req).with_updates(is_error=True)
+        texts: list[str] = []
+        session_id = None
+        usage: dict[str, int] | None = None
+        cost: float | None = None
+        failure: str | None = None
+        for ev in events:
+            session_id = session_id or ev.get("sessionID")
+            part = ev.get("part") or {}
+            kind = ev.get("type")
+            if kind == "step_start":
+                texts = []
+            elif kind == "text" and isinstance(part.get("text"), str):
+                texts.append(part["text"])
+            elif kind == "step_finish":
+                usage, cost = _add_step(usage, cost, part)
+            elif kind == "error":
+                err = ev.get("error") or {}
+                failure = (err.get("data") or {}).get("message") or err.get("name") or "opencode error"
+        log = _ERROR_LOG_RE.search(completed.stderr)
+        if failure is not None and log:
+            failure = log.group(1).replace('\\"', '"')
+        text = "\n".join(texts)
+        return Result(
+            harness_name=self.name,
+            model=req.model,
+            text=failure if failure is not None else text,
+            exit_code=completed.exit_code,
+            is_error=failure is not None or completed.exit_code != 0,
+            duration_ms=completed.duration_ms,
+            session_id=session_id,
+            usage=usage,
+            cost_usd=cost,
+            argv=completed.argv,
+            raw_stdout=completed.stdout,
+            raw_stderr=completed.stderr,
+        )
+
+    def stream_events(self, line: str, state: dict[str, Any]) -> list[dict[str, Any]]:
+        """Map an ``opencode run --format json`` line: ``text`` parts, and ``tool_use`` parts.
+
+        opencode 1.19.5 prints a tool part once the call has finished, with its input and output
+        together, so both events come from one line. A part seen earlier (still running) isn't
+        reported twice; ``state`` remembers it.
+
+        Args:
+            line: One stdout line.
+            state: Remembers reported call ids (``"started"``).
+
+        Returns:
+            The events.
+        """
+        data = json_line(line)
+        part = data.get("part") if data else None
+        if not isinstance(part, dict):
+            return []
+        if data.get("type") == "text":
+            return [{"type": "text", "text": part.get("text", "")}]
+        call = part.get("state")
+        if data.get("type") != "tool_use" or not isinstance(call, dict):
+            return []
+        call_id = part.get("callID")
+        started = state.setdefault("started", set())
+        events = []
+        if call_id not in started:
+            started.add(call_id)
+            events.append(tool_use(call_id, part.get("tool"), call.get("input")))
+        if call.get("status") in ("completed", "error"):
+            failed = call["status"] == "error"
+            output = call.get("error" if failed else "output")
+            events.append(tool_result(call_id, failed, output if isinstance(output, str) else ""))
+        return events
+
+
+def _add_step(
+    usage: dict[str, int] | None, cost: float | None, part: dict[str, Any]
+) -> tuple[dict[str, int] | None, float | None]:
+    """Add one ``step_finish`` part's tokens and cost to the running totals.
+
+    opencode's ``input`` excludes cached tokens, so cache reads and writes are added back in.
+
+    Args:
+        usage: Totals so far, or ``None``.
+        cost: Cost so far, or ``None``.
+        part: The ``step_finish`` event's part.
+
+    Returns:
+        The updated ``(usage, cost)``.
+    """
+    tokens = part.get("tokens")
+    if isinstance(tokens, dict):
+        cache = tokens.get("cache") or {}
+        usage = usage or {"input_tokens": 0, "output_tokens": 0}
+        usage["input_tokens"] += sum(int(v or 0) for v in (tokens.get("input"), cache.get("read"), cache.get("write")))
+        usage["output_tokens"] += int(tokens.get("output") or 0)
+    if isinstance(part.get("cost"), int | float):
+        cost = (cost or 0) + part["cost"]
+    return usage, cost
+
+
+def _session_flags(req: Request) -> list[str]:
+    """The harness's flags for ``--resume ID`` / ``--continue`` (none for a new session).
+
+    Args:
+        req: The request.
+
+    Returns:
+        The flags.
+    """
+    if req.resume is not None:
+        return ["--session", req.resume]
+    return ["--continue"] if req.continue_session else []

callai/adapters/pi.py

@@ -0,0 +1,179 @@
+"""Adapter for the pi coding agent (``pi --mode json``)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import UsageError
+from ..request import Request
+from ..result import Completed, Result
+from .base import Adapter, content_text, json_line, jsonl_events, strip_ansi, tool_result, tool_use
+
+# pi has no approval prompts, only tool allowlists (verified against pi 1.4.0 and the stub's request
+# log). --tools keeps MCP tools, so restricted levels also pass --no-mcp.
+_READ_TOOLS = "read,grep,find,ls"
+_PERMISSION_FLAGS: dict[str, list[str]] = {
+    "default": [],
+    "read-only": ["--tools", _READ_TOOLS, "--no-mcp"],
+    "auto": ["--tools", f"{_READ_TOOLS},edit,write", "--no-mcp"],  # edits yes, shell no
+    "bypass": [],  # pi's default already runs every tool without asking
+}
+_FAILED_STOPS = {"error", "aborted", "length"}
+
+
+class Pi(Adapter):
+    """``pi --mode json`` — parses the JSONL session events."""
+
+    name = "pi"
+    binary = "pi"
+    install_url = "https://pi.dev/docs/latest/quickstart"
+
+    def build_argv(self, req: Request) -> list[str]:
+        """Build the ``pi`` command line.
+
+        Args:
+            req: The request to run.
+
+        Returns:
+            The argv list, prompt last after ``--``.
+
+        Raises:
+            UsageError: If the prompt starts with ``@``, which pi always reads as a file to attach.
+        """
+        if req.prompt.startswith("@"):
+            raise UsageError(
+                "pi reads a prompt starting with '@' as a file to attach, and has no escape; "
+                "start the prompt with other text (e.g. a space)"
+            )
+        argv = [self.binary, "--mode", "json"]
+        if req.model:
+            argv += ["--model", req.model]
+        argv += _PERMISSION_FLAGS[req.permission]
+        if req.system_prompt is not None:
+            argv += ["--system-prompt", req.system_prompt]
+        return [*argv, *_session_flags(req), *req.extra_args, "--", req.prompt]
+
+    def parse(self, completed: Completed, req: Request) -> Result:
+        """Parse the JSONL events of ``pi --mode json``.
+
+        The answer is the text of the last assistant ``message_end``. pi exits 0 even when the model
+        call fails, so failure comes from that message's ``stopReason`` (error, aborted or length),
+        a missing assistant message, or a non-zero exit. Usage and cost are summed over all turns.
+
+        Args:
+            completed: Raw process outcome.
+            req: The request that produced it.
+
+        Returns:
+            The normalised result.
+        """
+        events = jsonl_events(completed.stdout)
+        if not events:  # e.g. a model pi doesn't know: the reason is only on stderr
+            text = strip_ansi(completed.stderr).strip() or strip_ansi(completed.stdout).strip()
+            return self.text_result(completed, req).with_updates(text=text, is_error=True)
+        session_id = None
+        last: dict[str, Any] | None = None
+        usage: dict[str, int] | None = None
+        cost: float | None = None
+        for ev in events:
+            if ev.get("type") == "session":
+                session_id = ev.get("id")
+            message = ev.get("message") or {}
+            if ev.get("type") == "message_end" and message.get("role") == "assistant":
+                last = message
+                usage, cost = _add_usage(usage, cost, message.get("usage"))
+        text, failed, model = "", last is None, req.model
+        if last is not None:
+            text = "\n".join(
+                b["text"]
+                for b in last.get("content") or []
+                if b.get("type") == "text" and isinstance(b.get("text"), str)
+            )
+            stop = last.get("stopReason")
+            if stop in _FAILED_STOPS:
+                failed = True
+                if stop != "length":
+                    text = last.get("errorMessage") or stop
+            if last.get("provider") and last.get("model"):
+                model = f"{last['provider']}/{last['model']}"
+        return Result(
+            harness_name=self.name,
+            model=model,
+            text=text,
+            exit_code=completed.exit_code,
+            is_error=failed or completed.exit_code != 0,
+            duration_ms=completed.duration_ms,
+            session_id=session_id,
+            usage=usage,
+            cost_usd=cost,
+            argv=completed.argv,
+            raw_stdout=completed.stdout,
+            raw_stderr=completed.stderr,
+        )
+
+    def stream_events(self, line: str, state: dict[str, Any]) -> list[dict[str, Any]]:
+        """Map a ``pi --mode json`` line: text deltas, and tool executions.
+
+        Text comes from ``text_delta`` updates (pieces of a message as the model writes them), not
+        from the whole messages pi repeats in ``message_end``/``turn_end``, so nothing is reported twice.
+
+        Args:
+            line: One stdout line.
+            state: Unused.
+
+        Returns:
+            The events.
+        """
+        data = json_line(line)
+        kind = data.get("type") if data else None
+        if kind == "message_update":
+            update = data.get("assistantMessageEvent")
+            if isinstance(update, dict) and update.get("type") == "text_delta":
+                return [{"type": "text", "text": update.get("delta", "")}]
+        elif kind == "tool_execution_start":
+            return [tool_use(data.get("toolCallId"), data.get("toolName"), data.get("args"))]
+        elif kind == "tool_execution_end":
+            result = data.get("result")
+            output = content_text(result.get("content")) if isinstance(result, dict) else ""
+            return [tool_result(data.get("toolCallId"), bool(data.get("isError")), output)]
+        return []
+
+
+def _add_usage(
+    usage: dict[str, int] | None, cost: float | None, raw: Any
+) -> tuple[dict[str, int] | None, float | None]:
+    """Add one assistant message's usage to the running totals.
+
+    pi's ``input`` excludes cached tokens, so ``cacheRead`` and ``cacheWrite`` are added back in.
+
+    Args:
+        usage: Totals so far, or ``None``.
+        cost: Cost so far, or ``None``.
+        raw: The message's ``usage`` object.
+
+    Returns:
+        The updated ``(usage, cost)``.
+    """
+    if not isinstance(raw, dict):
+        return usage, cost
+    usage = usage or {"input_tokens": 0, "output_tokens": 0}
+    usage["input_tokens"] += sum(int(raw.get(k) or 0) for k in ("input", "cacheRead", "cacheWrite"))
+    usage["output_tokens"] += int(raw.get("output") or 0)
+    total = (raw.get("cost") or {}).get("total")
+    if isinstance(total, int | float):
+        cost = (cost or 0) + total
+    return usage, cost
+
+
+def _session_flags(req: Request) -> list[str]:
+    """The harness's flags for ``--resume ID`` / ``--continue`` (none for a new session).
+
+    Args:
+        req: The request.
+
+    Returns:
+        The flags.
+    """
+    if req.resume is not None:
+        return ["--session", req.resume]
+    return ["--continue"] if req.continue_session else []