spatialagents 0.1.0__py3-none-any.whl

spatialagents/__init__.py

@@ -0,0 +1,66 @@
+"""The chat harness runtime BioCognia's products share.
+
+A product (Plexora, SCIMAP Pro) brings its tools, its words and its places on
+disk; this package is the rest of an in-app AI conversation: the streamed
+model call through the BioCognia AI gateway, the tool loop with deferred
+schemas, approvals, sub-agents, compaction, the tool-result cache, offloaded
+results, the conversation store and the local trace. It never imports a
+product. A product binds it through a `backend.ToolBackend` (what its tools
+are and how one runs), a `runner.ChatProfile` (its prompt content, task names
+and wording), a `plans.PlanHost` (its two plan packets and its workflow layer)
+and the roots, version and callbacks each store takes.
+
+    wire           the request envelope, canonical JSON, usage, task ids on the wire
+    gateway        the streamed model call, on biocognia.gateway's token and transport
+    cache_plan     prefix fingerprints and the cache-hit monitor
+    schema         answer models -> structured-output JSON schema, and back
+    orchestrator   task graph, parallel scheduler, shared blackboard
+    trace          the local trace: runs, model calls, cache verdicts, tool calls
+    policy         the permission and egress vocabulary, and `Policy`
+    errors         `AgentError` and its codes (a product registers its own)
+    sessions       a session on disk: record, control, transcript, packets, lock
+    conversations  conversations on disk, and the service that runs their turns
+    approvals      source-file writes and deletes wait for the user (control.json)
+    toolcache      read results remembered per revision
+    offload        large tool results as stubs, read back in slices
+    serialize      results as bounded JSON
+    backend        the `ToolBackend` protocol a product implements
+    tools          a backend's tools as deferred tools (load_tool / call_tool)
+    prefix         the cached system prompt's mechanism
+    runner         the conversational agent: a tool loop, sub-agents, compaction
+    plans          the plan runner: compose and summarise packets over a product's PlanHost
+    chat.http      the chat's HTTP + SSE contract (ChatApi), framework-free
+    chat.server    the page and the API on a loopback port, stdlib only
+    chat.cli       the terminal loop
+    testing        FakeGateway, FakeToolBackend, FakePlanHost, ScriptedBrain (and inert fixtures)
+
+Every submodule is imported on first use, so `import spatialagents` costs
+nothing. Model calls are refused before a socket opens under
+`BIOCOGNIA_OFFLINE=1`.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+__version__ = "0.1.0"
+
+_SUBMODULES = frozenset({
+    "approvals", "backend", "cache_plan", "chat", "conversations", "errors", "gateway", "offload",
+    "orchestrator", "plans", "policy", "prefix", "runner", "schema", "serialize", "sessions", "testing",
+    "toolcache", "tools", "trace", "wire",
+})
+
+__all__ = ["__version__", *sorted(_SUBMODULES)]
+
+
+def __getattr__(name: str):
+    if name in _SUBMODULES:
+        module = importlib.import_module(f"{__name__}.{name}")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | _SUBMODULES)

spatialagents/approvals.py

@@ -0,0 +1,137 @@
+"""Human in the loop: a call that writes the user's source file or cannot be
+undone waits for the user.
+
+The permission classes decide (`policy.PERMISSIONS`); a call's class is the
+backend's answer for those arguments (`ToolBackend.permission`), so one tool
+may read in one call and write a source file in the next:
+
+    read                 runs
+    reversible_write     runs; its operation_id goes to the person as an Undo chip
+    source_file_write    waits for an approval
+    destructive          waits for an approval
+
+`ApprovalGate.ask` writes a pending approval into the conversation's
+`control.json` (`approvals.<id>`, and `paused: true, paused_by: "approval"`),
+announces `approval_requested`, and waits for the record to change. The
+person's Approve / Deny (a panel's button posting to the product's route, a
+terminal's y/N) calls `decide`. Approve runs THAT one call with the policy
+flag it needs (`policy.elevated`) and the backend's confirmation
+(`ToolBackend.invoke(..., approved=True)`); Deny, a stop or an expiry return an
+error tool_result ("the user declined") so the model knows not to try another
+way round. Sub-agents share their parent's gate, so one sub-agent's approval
+pauses the whole conversation.
+
+Model output cannot authorise its own writes: `decide` is reached only from a
+surface the person holds, never from a tool the model can call.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+
+from spatialagents.errors import AgentError
+from spatialagents.policy import elevated
+
+__all__ = ["DECIDED", "DECLINED", "PENDING", "ApprovalGate", "decide", "elevated", "new_approval_id"]
+
+PENDING = "pending"
+DECIDED = ("approved", "denied", "stopped", "expired")
+DECLINED = "The user declined this call. Do not try to reach the same result another way; say what " \
+           "you would have done and continue without it."
+
+
+def new_approval_id() -> str:
+    return f"apr_{uuid.uuid4().hex[:10]}"
+
+
+def _pending(control: dict) -> list:
+    return [a for a in (control.get("approvals") or {}).values() if a.get("status") == PENDING]
+
+
+def decide(store, conversation_id: str, approval_id: str, approve: bool, *, by: str = "viewer") -> dict:
+    """Record the user's answer. Raises `invalid_input` for an unknown approval
+    and `conflict` for one already decided."""
+    with store.lock(conversation_id):
+        control = store.control(conversation_id)
+        approvals = dict(control.get("approvals") or {})
+        approval = approvals.get(approval_id)
+        if approval is None:
+            raise AgentError("invalid_input", f"no approval {approval_id!r} in this conversation")
+        if approval.get("status") != PENDING:
+            raise AgentError("conflict", f"{approval_id} was already {approval.get('status')}",
+                             detail={"status": approval.get("status")})
+        approval = {**approval, "status": "approved" if approve else "denied", "decided_by": by,
+                    "decided_at": time.time()}
+        approvals[approval_id] = approval
+        changes = {"approvals": approvals}
+        others = [a for a in approvals.values() if a.get("status") == PENDING]
+        if not others and control.get("paused_by") == "approval":
+            changes.update(paused=False, paused_by=None)
+        store.set_control(conversation_id, **changes)
+    return approval
+
+
+class ApprovalGate:
+    def __init__(self, store, conversation_id: str, *, poll_s: float = 0.1, timeout_s: float = 3600.0):
+        self.store = store
+        self.conversation_id = conversation_id
+        self.poll_s = poll_s
+        self.timeout_s = timeout_s
+
+    def request(self, *, tool: str, capability: str, permission: str, purpose: str = "", arguments: dict,
+                agent: str | None = None) -> dict:
+        approval = {"approval_id": new_approval_id(), "tool": tool, "capability": capability,
+                    "permission": permission, "purpose": (purpose or "")[:300],
+                    "arguments": arguments, "agent": agent, "status": PENDING, "requested_at": time.time()}
+        with self.store.lock(self.conversation_id):
+            control = self.store.control(self.conversation_id)
+            approvals = dict(control.get("approvals") or {})
+            approvals[approval["approval_id"]] = approval
+            self.store.set_control(self.conversation_id, approvals=approvals, paused=True,
+                                   paused_by="approval")
+        return approval
+
+    def wait(self, approval_id: str) -> str:
+        deadline = time.monotonic() + self.timeout_s
+        while True:
+            control = self.store.control(self.conversation_id)
+            approval = (control.get("approvals") or {}).get(approval_id) or {}
+            status = approval.get("status")
+            if status in DECIDED:
+                return status
+            if control.get("stopped"):
+                self._close(approval_id, "stopped")
+                return "stopped"
+            if time.monotonic() >= deadline:
+                self._close(approval_id, "expired")
+                return "expired"
+            time.sleep(self.poll_s)
+
+    def _close(self, approval_id: str, status: str) -> None:
+        try:
+            with self.store.lock(self.conversation_id):
+                control = self.store.control(self.conversation_id)
+                approvals = dict(control.get("approvals") or {})
+                if approval_id in approvals and approvals[approval_id].get("status") == PENDING:
+                    approvals[approval_id] = {**approvals[approval_id], "status": status,
+                                              "decided_at": time.time()}
+                changes = {"approvals": approvals}
+                if not [a for a in approvals.values() if a.get("status") == PENDING] \
+                        and control.get("paused_by") == "approval":
+                    changes.update(paused=False, paused_by=None)
+                self.store.set_control(self.conversation_id, **changes)
+        except OSError:
+            pass
+
+    def ask(self, *, tool: str, capability: str, permission: str, purpose: str = "", arguments: dict, emit,
+            agent: str | None = None) -> tuple:
+        """`(status, approval)`: request, announce through `emit`, and wait."""
+        approval = self.request(tool=tool, capability=capability, permission=permission, purpose=purpose,
+                                arguments=arguments, agent=agent)
+        emit({"event": "approval_requested", **{k: approval[k] for k in (
+            "approval_id", "tool", "capability", "permission", "purpose", "arguments", "agent")}})
+        status = self.wait(approval["approval_id"])
+        emit({"event": "approval_decided", "approval_id": approval["approval_id"], "status": status,
+              "agent": agent})
+        return status, approval

spatialagents/backend.py

@@ -0,0 +1,181 @@
+"""What a product's tools are to the harness: the `ToolBackend` protocol.
+
+The conversational loop (`runner.py`) and its tools (`tools.py`) never touch a
+product's registry. Everything they need from it goes through one object a
+product implements -- Plexora's `RegistryBackend` over its capability
+registry, SCIMAP Pro's `ScimapBackend` over its MCP toolset -- and this
+protocol is the whole of that contract:
+
+    catalog(policy, viewer=)        the tools a conversation may use, frozen at its start
+    definition(tool)                one tool's {name, description, input_schema}
+    permission(tool, arguments)     its permission class FOR THESE ARGUMENTS
+    invoke(tool, arguments, policy=, approved=)   run it; an outcome dict, never raises
+    purpose(tool)                   what it does, for the person approving it
+    cacheable(tool, arguments)      whether its result may be remembered
+    revision_token(tool, arguments) what a remembered result is valid for
+    skills() / read_skill(name)     the product's runtime skills
+    server_info(policy, tools=, viewer=)   what `server_info` answers in a conversation
+    serialize(value)                a result as JSON-able data
+    split_images(result)            (result without images, [(bytes, format)])
+
+and two attributes, `max_result_chars` (how long one serialized result may
+be) and `revision_guard` (see below).
+
+**Permission depends on the arguments.** SCIMAP Pro's `run_function` is a
+`reversible_write` on an in-memory table and a `source_file_write` when the
+table is out of core, so the class is asked per call; the catalog's
+`permission` is what the tool usually is, and only marks the catalog line.
+`read` runs, `reversible_write` runs and its `operation_id` becomes an Undo
+chip, `source_file_write` and `destructive` wait for the person
+(`approvals.py`). Whether the call may run at all is still the backend's
+check in `invoke`: the harness never decides what is scientifically allowed.
+
+**`invoke` with `approved=True`** is a call the person approved: the policy it
+is given already carries the flag the class needs (`policy.elevated`), and
+the backend confirms the call the way its own tools are confirmed (Plexora
+adds `confirm: true` where a capability takes one). Nothing else may pass
+`approved=True`.
+
+**The outcome** of `invoke`:
+
+    {"ok": True, "result": <data>, "operation_id": str | None, "undo": bool,
+     "advanced": {"scope": str, "before": str, "after": str} | None}
+    {"ok": False, "error": {"code", "message", "detail", "retryable"}, "operation_id": str | None}
+
+`result` is JSON-able apart from image bytes, which `split_images` lifts out
+(the default reads them from `result["_images"]`). `undo` says the write has
+an exact reversal the person can ask for; `advanced` says it moved a revision
+guard from `before` to `after` (below). A domain failure is an outcome, not an
+exception: the model reads the error and tries something else.
+
+**Revision guards.** A product whose writes carry an optimistic-concurrency
+guard names its two arguments in `revision_guard` -- `(scope, expected)`,
+Plexora's `("project", "expected_revision")` -- and reports each write's move
+in `advanced`. Writes a model sends together each name the revision it read
+before the first ran; the runner carries each one forward past the turn's own
+earlier writes, and only those (`AgentRunner._carry_revision`).
+
+Every method but the first four has a default here, so a backend subclasses
+`ToolBackend` and implements what it has. `testing.FakeToolBackend` is the
+reference implementation, and the compatibility contract both products'
+backends are tested against.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from spatialagents import serialize as _serialize
+from spatialagents.errors import AgentError
+
+
+def split_images(result) -> tuple:
+    """(result without images, [(bytes, format)]) -- images travel as image
+    content. `result["_images"]` holds PNG bytes, or `{data, format}` for
+    another format (WebP: the same pixels, a third of the bytes)."""
+    if not isinstance(result, dict):
+        return result, []
+    images = result.pop("_images", None) or []
+    out = []
+    for image in images:
+        if isinstance(image, (bytes, bytearray)):
+            out.append((bytes(image), "png"))
+        elif isinstance(image, dict) and isinstance(image.get("data"), (bytes, bytearray)):
+            out.append((bytes(image["data"]), str(image.get("format") or "png")))
+    return result, out
+
+
+def ok(result=None, *, operation_id: str | None = None, undo: bool = False, advanced: dict | None = None) -> dict:
+    """A successful outcome."""
+    out = {"ok": True, "result": result, "operation_id": operation_id}
+    if undo:
+        out["undo"] = True
+    if advanced:
+        out["advanced"] = dict(advanced)
+    return out
+
+
+def failed(code: str, message: str, *, detail=None, retryable: bool = False,
+           operation_id: str | None = None) -> dict:
+    """A refused or failed outcome, with a code from `errors.known()`."""
+    return {"ok": False, "error": AgentError(code, message, detail=detail, retryable=retryable).to_problem(),
+            "operation_id": operation_id}
+
+
+def refusal(exc: AgentError, *, operation_id: str | None = None) -> dict:
+    """`exc` as an outcome."""
+    return {"ok": False, "error": exc.to_problem(), "operation_id": operation_id}
+
+
+class ToolBackend(Protocol):
+    """A product's tools, as the harness drives them."""
+
+    #: Characters in one serialized tool result (the product's MCP server's own limit).
+    max_result_chars: int = _serialize.MAX_RESULT_CHARS
+    #: `(scope argument, expected-revision argument)` of a write's revision guard, or None.
+    revision_guard: tuple[str, str] | None = None
+
+    def catalog(self, policy, *, viewer: bool = False) -> list[dict]:
+        """The tools a conversation under `policy` may use: `{"tool", "capability",
+        "permission", "purpose"}` each (`capability` defaults to the tool's
+        name). Every tool the policy could let through -- egress allowed,
+        writes only when it allows writes, source-file writes and deletes
+        included, because they pause for approval rather than being refused.
+        `viewer`: a live view is attached, so tools that drive it may be offered.
+        The harness sorts it, drops names its own local tools use, and freezes
+        it for the conversation."""
+        raise NotImplementedError
+
+    def definition(self, tool: str) -> dict:
+        """`{"name", "description", "input_schema"}`: what `load_tool` hands the
+        model. The input schema is a JSON schema (pydantic's is fine: titles
+        are stripped by the harness)."""
+        raise NotImplementedError
+
+    def permission(self, tool: str, arguments: dict) -> str:
+        """This call's permission class (`policy.PERMISSIONS`)."""
+        raise NotImplementedError
+
+    def invoke(self, tool: str, arguments: dict, *, policy, approved: bool = False) -> dict:
+        """Run one call; the outcome described above. Validates the arguments,
+        checks the policy and the licence, writes the product's audit -- as
+        any other surface of the product would."""
+        raise NotImplementedError
+
+    def purpose(self, tool: str) -> str:
+        """What the tool does, for the person deciding whether to let it run."""
+        return ""
+
+    def cacheable(self, tool: str, arguments: dict) -> bool:
+        """Whether this call's result may be remembered (`toolcache.py`): a
+        read of something with a revision, never a write, never cell-level
+        data, never what a live view shows."""
+        return False
+
+    def revision_token(self, tool: str, arguments: dict) -> str:
+        """What a remembered result of this call is valid for: it changes
+        whenever a write changes what the call reads."""
+        return "0"
+
+    def skills(self) -> list[dict]:
+        """The runtime skills a conversation may read: `{"name", "title", "when"}` each."""
+        return []
+
+    def read_skill(self, name: str) -> str:
+        """One skill's text. Raises KeyError for a skill there is not."""
+        raise KeyError(f"no skill {name!r}")
+
+    def server_info(self, policy, *, tools: int, viewer: bool) -> dict:
+        """What `server_info` answers inside a conversation: the product's
+        version, where its data is, the permissions (`policy.describe()`),
+        how many tools the conversation has, the skills, the licence."""
+        return {"policy": policy.describe(), "n_tools": tools, "viewer": viewer,
+                "skills": [s.get("name") for s in self.skills()]}
+
+    def serialize(self, value) -> Any:
+        """`value` as JSON-able data (the harness bounds and offloads it)."""
+        return _serialize.clean(value)
+
+    def split_images(self, result) -> tuple:
+        """(result without images, [(bytes, format)])."""
+        return split_images(result)

spatialagents/cache_plan.py

@@ -0,0 +1,117 @@
+"""Prefix fingerprints and the cache-hit monitor.
+
+A prompt cache pays only while the prefix is byte-identical, and a silent
+change (a timestamp, an unsorted dict, a reordered tool list) multiplies the
+cost of every later call without failing anything. So every call is checked:
+from a worker's second call on, the provider must report reading at least
+the prefix from cache. A miss is logged with the fingerprint, counted in the
+trace, and shown by the product's trace report (`TraceStore.cache_report`).
+The monitor logs through the `log` it is given -- the product's harness
+logger -- so a product's log configuration sees its own misses.
+
+The expected size is an estimate (characters / 3.5), and tool schemas and
+prose tokenize denser than that, while providers count cached reads in
+blocks (128 tokens at OpenAI-style caches). So the estimate is only a rough
+first bar; once the provider has reported reading the prefix on a worker's
+first call -- which reads only the system prompt another worker wrote -- that
+size is the bar. A worker's later calls also read its own earlier turns (the
+rolling breakpoints, wire.with_breakpoints), so their reads and every write
+are prefix plus history and never set the bar. A model whose provider has
+never reported caching anything for a prefix gets the verdict `uncached`:
+nothing changed in the prefix, and a warning per call would say nothing new.
+
+Some engines (vLLM / SGLang behind Chat Completions) report the chat
+template's first few tokens as cached on every call, even a brand-new prompt:
+a read or write of TEMPLATE_TOKENS or fewer is that, not a cached prefix. And
+a best-effort cache (SayGM's TEE models hit or miss with their own load) can
+miss call after call on a prefix that never changed: each prefix warns once,
+and the rest are counted in the trace.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass, field
+
+from spatialagents.wire import Usage, canonical
+
+log = logging.getLogger("spatialagents")
+
+CHARS_PER_TOKEN = 3.5
+#: Share of the expected prefix a warm call must read from cache.
+HIT_SHARE = 0.9
+#: How far below the characters-based estimate a prefix's real token count may
+#: be, before any provider-reported size is known for it.
+ESTIMATE_SLACK = 0.7
+#: Cached tokens at or under this are the chat template's opening, not a prefix.
+TEMPLATE_TOKENS = 32
+
+
+def fingerprint(system: list) -> str:
+    return hashlib.sha256(canonical(system).encode("utf-8")).hexdigest()[:16]
+
+
+def expected_tokens(system: list) -> int:
+    return int(len(canonical(system)) / CHARS_PER_TOKEN)
+
+
+@dataclass
+class CacheMonitor:
+    """Verdicts per call: `cold` (first call of a worker, may write), `hit`,
+    `miss` (a warm call that did not read the prefix), `uncached` (a warm call
+    on a prefix the provider has never reported caching at all)."""
+
+    seen: dict = field(default_factory=dict)
+    counts: dict = field(default_factory=lambda: {"cold": 0, "hit": 0, "miss": 0, "uncached": 0})
+    usage: Usage = field(default_factory=Usage)
+    #: The prefix's real cached size per prefix, from what a worker's first
+    #: call read: it replaces the estimate as the bar.
+    cached: dict = field(default_factory=dict)
+    #: The prefixes the provider has reported reading or writing anything for.
+    caching: dict = field(default_factory=dict)
+    #: The prefixes a miss has already been logged for.
+    warned: set = field(default_factory=set)
+    #: Where verdicts worth a line are logged: the product's harness logger, so
+    #: its log configuration (and its tests) see them.
+    log: logging.Logger = field(default=log, repr=False, compare=False)
+
+    def observe(self, prefix_fp: str, prefix_tokens: int, usage: Usage, *, warm: bool) -> str:
+        for name in Usage.__dataclass_fields__:
+            setattr(self.usage, name, getattr(self.usage, name) + getattr(usage, name))
+        read = usage.cache_read if usage.cache_read > TEMPLATE_TOKENS else 0
+        wrote = usage.cache_write if usage.cache_write > TEMPLATE_TOKENS else 0
+        known = self.seen.get(prefix_fp, False)
+        self.seen[prefix_fp] = True
+        reported = self.cached.get(prefix_fp, 0)
+        if reported:
+            bar = HIT_SHARE * min(reported, prefix_tokens)
+        else:
+            bar = HIT_SHARE * ESTIMATE_SLACK * prefix_tokens
+        bar = min(bar, HIT_SHARE * max(1, usage.input_total))
+        if not warm and not known:
+            verdict = "cold"
+        elif read and read >= bar:
+            verdict = "hit"
+        elif not self.caching.get(prefix_fp) and not read and not wrote:
+            verdict = "uncached"
+            if not self.counts["uncached"]:
+                self.log.info("prompt caching not reported on prefix %s: the provider wrote and read "
+                              "nothing", prefix_fp)
+        else:
+            verdict = "miss"
+            if prefix_fp not in self.warned:
+                self.warned.add(prefix_fp)
+                self.log.warning("prompt-cache miss on prefix %s: read %d of ~%d prefix tokens "
+                                 "(further misses on it are counted in the trace, not logged)",
+                                 prefix_fp, usage.cache_read, int(reported or prefix_tokens))
+        if read or wrote:
+            self.caching[prefix_fp] = True
+        if read and not warm:
+            self.cached[prefix_fp] = max(reported, read)
+        self.counts[verdict] += 1
+        return verdict
+
+    def read_share(self) -> float:
+        total = self.usage.input_total
+        return self.usage.cache_read / total if total else 0.0

spatialagents/chat/__init__.py

@@ -0,0 +1,11 @@
+"""The surfaces a conversation and a plan are driven from.
+
+    http      ChatApi: the HTTP + SSE contract, framework-free, over ChatService and PlanService
+    server    ChatServer: the page and the API on a loopback port (stdlib only), token -> cookie
+    static/   the page: chat.js (no build step), chat.css, index.html
+    cli       the terminal loop (`plexora ai chat`, `scimappro ai chat --terminal`)
+
+A product with a web app of its own mounts `ChatApi` behind its own guards
+(Plexora's Flask blueprint is a thin adapter over it); one without serves it
+with `ChatServer`.
+"""

spatialagents/chat/cli.py

@@ -0,0 +1,84 @@
+"""A conversation in the terminal: a plain `input()` / `print()` loop.
+
+    runner = service.runner(conversation_id)
+    loop(runner, label="plexora")
+
+Each line the person types is one turn; its events are printed as they
+happen -- the answer streaming as it is written, a line per tool call and
+result (with the Undo id of a reversible write), the running credit, a pause
+and why, sub-agents starting and finishing. A call that needs approval asks
+`approve? [y/N]` and the answer is the person's own (`approvals.decide`, by
+`terminal`): nothing the model says can answer it. An empty line, `exit`,
+`quit`, end of input or Ctrl-C ends the loop and releases the conversation for
+another process to resume.
+
+The product's command around it starts or resumes the conversation, says what
+it is and how to resume it, and returns the exit code.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from spatialagents.approvals import decide
+
+#: Credits are 10,000 micro-dollars (the gateway's `credit_micro`).
+CREDIT_MICRO = 10_000
+
+
+def credits(micro) -> str:
+    """`micro` (micro-dollars) as the person reads it: credits and dollars."""
+    micro = int(micro or 0)
+    return f"{micro / CREDIT_MICRO:,.1f} credits (${micro / 1_000_000:,.2f})"
+
+
+def loop(runner, *, read=input, write=print, label: str = "assistant", out=None) -> int:
+    """Read lines, run turns, print their events, until the person stops.
+
+    `read(prompt)` and `write(line)` are the terminal (tests pass their own);
+    the streamed answer goes to `out` (default: `sys.stdout` as it is at the
+    time), after `label> `."""
+    stream = out or sys.stdout
+    cid = runner.conversation_id
+    while True:
+        try:
+            text = read("you> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        if not text or text.lower() in ("exit", "quit"):
+            break
+        streaming = False
+        for event in runner.turn(text):
+            kind = event.get("event")
+            who = f"[{event['agent']}] " if event.get("agent") else ""
+            if kind == "text_delta" and not event.get("agent"):
+                if not streaming:
+                    stream.write(f"{label}> ")
+                    streaming = True
+                stream.write(event["text"])
+                stream.flush()
+                continue
+            if streaming and kind != "text_delta":
+                stream.write("\n")
+                streaming = False
+            if kind == "tool_call":
+                write(f"  {who}-> {event['tool']}")
+            elif kind == "tool_result":
+                extra = f"  (undo: {event['operation_id']})" if event.get("undo") else ""
+                write(f"  {who}<- {event['tool']}: {'ok' if event['ok'] else 'error'} [{event['source']}]{extra}")
+            elif kind == "approval_requested":
+                write(f"  {who}{event['tool']} ({event['permission']}) wants to run with "
+                      f"{json.dumps(event.get('arguments'))}")
+                answer = read("  approve? [y/N] ").strip().lower()
+                decide(runner.store, cid, event["approval_id"], answer in ("y", "yes"), by="terminal")
+            elif kind == "usage" and not event.get("agent"):
+                write(f"  ({credits(event.get('total_charged_micro'))} so far)")
+            elif kind == "paused":
+                write(f"  paused: {event.get('reason')} -- {event.get('resume')}")
+            elif kind == "error":
+                write(f"  error: {event.get('code')}: {event.get('message')}")
+            elif kind in ("agent_started", "agent_finished"):
+                write(f"  {who}{kind.replace('_', ' ')}: {event.get('brief') or event.get('summary') or ''}")
+    runner.store.release(cid)
+    return 0