spatialagents 0.1.0__py3-none-any.whl

spatialagents/testing.py

@@ -0,0 +1,927 @@
+"""Test helpers: a stand-in gateway, a stand-in product, a scripted model.
+
+Registered as a pytest plugin (`spatialagents = "spatialagents.testing"`) that
+is inert unless a suite asks for one of its fixtures, so installing the
+package changes nothing about a product's test run. No network, no model and
+no product is needed for any of it.
+
+`FakeGateway` is a real HTTP server on a loopback port (like
+`biocognia.testing.FakeService`) that speaks the BioCognia AI gateway's wire:
+`/v1/ai/messages` takes only `task` (`<product>.<module>.<task>`), `context`,
+`request` and `model`, as the real one does, and streams Anthropic-shaped
+events between `biocognia.accepted` and `biocognia.usage`, and `/v1/ai/runs`
+quotes and closes runs. The "model" is a brain function given the decision
+packet the harness sent (and the whole request body); it answers with JSON or
+text, with a `Reply` that streams `tool_use` blocks the way a provider does
+(`input_json_delta` pieces, `stop_reason: tool_use`), or with `(status,
+code)` to refuse like the gateway. The usage is a prompt-cache emulator that
+reads from cache the longest prefix of the request it has seen before and
+writes the rest, so cache verdicts and prefix stability can be tested. A
+product's suite subclasses it to name itself (`PRODUCT`: every task must be
+its own) and its run prices (`PRICES`).
+
+`FakeToolBackend` is a `backend.ToolBackend` over `FakeTool`s defined in the
+test: the reference backend, and the contract a product's backend is held
+to. `FakePlanHost` is the same for `plans.PlanHost`, and `plan_brain` answers
+its two packets. `ScriptedBrain` answers a conversation's calls from a script,
+or replays a list of tool calls (a plan's steps) one per call, as an oracle.
+
+    tokens = fixed_tokens()                         # a token source, no licence
+    with FakeGateway(ScriptedBrain([Reply("hi")])) as fake:
+        client = GatewayClient(tokens, fake.url, sleep=lambda s: None)
+
+Fixtures (all opt-in): `spatialagents_gateway` (start FakeGateways, stopped at
+teardown), `spatialagents_tokens`, `spatialagents_backend` (an empty
+FakeToolBackend to add tools to).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import threading
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from types import SimpleNamespace
+from typing import Any, Callable
+
+from spatialagents.wire import canonical
+
+CHARS_PER_TOKEN = 3.5
+IMAGE_TOKENS = 1600
+#: $4 / $0.20 / $5 / $20 per MTok, as Opus 5.5 on the real gateway.
+UNIT = {"in": 4.0, "read": 0.2, "write": 5.0, "out": 20.0}
+
+
+def _marked(value) -> bool:
+    if isinstance(value, dict):
+        return "cache_control" in value or any(_marked(v) for v in value.values())
+    if isinstance(value, list):
+        return any(_marked(v) for v in value)
+    return False
+
+
+def _unmarked(value):
+    """`value` without cache_control keys: a provider matches a cached prefix by
+    content, wherever the breakpoint sat on the call that wrote it."""
+    if isinstance(value, dict):
+        return {k: _unmarked(v) for k, v in value.items() if k != "cache_control"}
+    if isinstance(value, list):
+        return [_unmarked(v) for v in value]
+    return value
+
+
+def _tokens(value) -> int:
+    if isinstance(value, dict):
+        if value.get("type") == "image":
+            return IMAGE_TOKENS
+        if value.get("type") == "text":
+            return max(1, int(len(value.get("text", "")) / CHARS_PER_TOKEN))
+    if isinstance(value, list):
+        return sum(_tokens(v) for v in value)
+    if isinstance(value, dict):
+        return _tokens(value.get("content", []))
+    return max(1, int(len(str(value)) / CHARS_PER_TOKEN))
+
+
+class Reply:
+    """A brain's answer with tool calls: optional text, then `tool_use` blocks
+    (`{"name", "input", "id"?}`), streamed as a provider streams them."""
+
+    def __init__(self, text: str = "", tool_uses=()):
+        self.text = text
+        self.tool_uses = [dict(t) for t in tool_uses]
+
+    def __repr__(self):
+        return f"Reply({self.text!r}, {self.tool_uses!r})"
+
+
+def tool_results(body: dict) -> list:
+    """The `tool_result` blocks of the newest user turn of a request body."""
+    messages = body["request"]["messages"]
+    if not messages or messages[-1].get("role") != "user":
+        return []
+    content = messages[-1].get("content")
+    return [b for b in (content if isinstance(content, list) else []) if b.get("type") == "tool_result"]
+
+
+def result_text(block: dict) -> str:
+    content = block.get("content")
+    if isinstance(content, str):
+        return content
+    return "".join(b.get("text", "") for b in content or [] if b.get("type") == "text")
+
+
+def last_user_text(body: dict) -> str:
+    for message in reversed(body["request"]["messages"]):
+        if message.get("role") != "user":
+            continue
+        content = message.get("content")
+        if isinstance(content, str):
+            return content
+        texts = [b.get("text", "") for b in content or [] if b.get("type") == "text"]
+        if texts:
+            return texts[-1]
+    return ""
+
+
+def last_packet(messages: list) -> dict | None:
+    """The newest decision packet among the user turns (skipping repair turns):
+    a JSON object with a `packet_id`, optionally followed by `ANSWER SCHEMA:`."""
+    for message in reversed(messages):
+        if message.get("role") != "user":
+            continue
+        content = message.get("content") or []
+        for block in reversed(content if isinstance(content, list) else []):
+            if block.get("type") == "text":
+                try:
+                    value = json.loads(block["text"].split("\nANSWER SCHEMA:")[0])
+                except ValueError:
+                    break
+                if isinstance(value, dict) and "packet_id" in value:
+                    return value
+    return None
+
+
+#: What the real gateway accepts at the top of a messages body (workers/ai TOP_KEYS).
+WIRE_KEYS = {"task", "context", "request", "model"}
+WIRE_TASK = re.compile(r"^[a-z][a-z0-9_]{1,31}\.[a-z][a-z0-9_]{0,31}\.[a-z][a-z0-9_]{0,31}$")
+
+
+class FakeGateway:
+    #: The product every task must be filed under (`<PRODUCT>.<module>.<task>`), or None for any.
+    PRODUCT: str | None = None
+    #: Run prices by feature, `{feature: (unit, credits per unit)}` (the real gateway's catalogue).
+    PRICES: dict = {}
+    #: A feature the price list does not name.
+    DEFAULT_PRICE = ("unit", 25)
+
+    def __init__(self, brain, *, credits_micro: int = 10_000_000, markup: float = 2.0):
+        self.brain = brain
+        self.calls: list[dict] = []
+        self.runs: dict[str, dict] = {}
+        self.seen_prefixes: set[str] = set()
+        self.credits = credits_micro
+        self.markup = markup
+        self.fail_with: list[tuple[int, str]] = []      # queued (status, code) refusals
+        self.lock = threading.Lock()
+        self._offline = None
+        gateway = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *args):
+                pass
+
+            def _json(self, status, body, headers=None):
+                data = json.dumps(body).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(data)))
+                for k, v in (headers or {}).items():
+                    self.send_header(k, v)
+                self.end_headers()
+                self.wfile.write(data)
+
+            def _body(self):
+                length = int(self.headers.get("Content-Length") or 0)
+                return json.loads(self.rfile.read(length) or b"{}")
+
+            def do_GET(self):
+                if self.path.startswith("/v1/ai/balance"):
+                    return self._json(200, {"org_id": "org_test", "product": gateway.PRODUCT or "test",
+                                            "mode": "credits", "available_micro": gateway.credits,
+                                            "member": {"limit": None, "used": 0, "period": "2026-10"},
+                                            "product_cap": {"limit": None, "used": 0, "period": "2026-10"},
+                                            "action_url": "https://account.biocognia.test/portal/ai",
+                                            "action_label": "Add credits or ask an owner"})
+                if self.path.startswith("/v1/ai/pricing"):
+                    return self._json(200, {"credit_micro": 10_000, "features": {
+                        name: {"unit": unit, "credits": credits, "price_micro": credits * 10_000}
+                        for name, (unit, credits) in gateway.PRICES.items()}})
+                return self._json(404, {"error": {"code": "not_found", "message": "no"}})
+
+            def do_POST(self):
+                body = self._body()
+                if self.path in ("/v1/ai/runs", "/v1/ai/dev/runs"):
+                    run_id = f"run_{len(gateway.runs) + 1}"
+                    credits = gateway.PRICES.get(body["feature"], gateway.DEFAULT_PRICE)[1]
+                    run = {"run_id": run_id, "feature": body["feature"], "units": body["units"],
+                           "quote_micro": body["units"] * credits * 10_000,
+                           "quote_credits": body["units"] * credits,
+                           "accrued_micro": 0, "charged_micro": 0, "calls": 0, "status": "open",
+                           "billing": "dev" if "/dev/" in self.path else "credits"}
+                    gateway.runs[run_id] = run
+                    return self._json(201, run)
+                if self.path.startswith("/v1/ai/runs/") and self.path.endswith("/finish"):
+                    run = gateway.runs[self.path.split("/")[4]]
+                    run["status"] = "finished"
+                    return self._json(200, run)
+                if self.path in ("/v1/ai/messages", "/v1/ai/dev/messages"):
+                    return gateway._messages(self, body)
+                return self._json(404, {"error": {"code": "not_found", "message": "no"}})
+
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.url = f"http://127.0.0.1:{self.server.server_address[1]}"
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+
+    def __enter__(self):
+        # A suite runs under BIOCOGNIA_OFFLINE=1, which the shared gateway
+        # client honours before opening any socket; this gateway is on
+        # loopback, so it is switched off while the fake runs.
+        self._offline = os.environ.pop("BIOCOGNIA_OFFLINE", None)
+        self.thread.start()
+        return self
+
+    def __exit__(self, *exc):
+        self.server.shutdown()
+        self.server.server_close()
+        if self._offline is not None:
+            os.environ["BIOCOGNIA_OFFLINE"] = self._offline
+
+    # -- the model call ---------------------------------------------------------
+
+    def _usage(self, request: dict) -> dict:
+        """Prompt-cache emulation, Anthropic-style: segments are the tools, the
+        system prompt, then each message; a prefix is stored only where a
+        cache_control breakpoint ends it, and the longest stored prefix is read,
+        the rest written. So a request that marks only its system prompt never
+        reads its earlier turns from cache, as on the real API."""
+        segments = (([request["tools"]] if request.get("tools") else []) + [request.get("system") or []]
+                    + list(request["messages"]))
+        running = hashlib.sha256()
+        keys = []
+        for segment in segments:
+            running.update(canonical(_unmarked(segment)).encode())
+            keys.append(running.hexdigest())
+        tokens = [_tokens(segment) for segment in segments]
+        with self.lock:
+            hit = max((i + 1 for i, key in enumerate(keys) if key in self.seen_prefixes), default=0)
+            for segment, key in zip(segments, keys):
+                if _marked(segment):
+                    self.seen_prefixes.add(key)
+        return {"input_uncached": 3, "cache_read": sum(tokens[:hit]), "cache_write_5m": sum(tokens[hit:]),
+                "cache_write_1h": 0}
+
+    def _messages(self, handler, body: dict):
+        unknown = set(body) - WIRE_KEYS
+        if unknown:
+            return handler._json(400, {"error": {"code": "invalid_request",
+                                                 "message": f"Unknown field `{sorted(unknown)[0]}`."}})
+        if not isinstance(body.get("task"), str) or not WIRE_TASK.match(body["task"]) \
+                or (self.PRODUCT is not None and not body["task"].startswith(f"{self.PRODUCT}.")):
+            return handler._json(400, {"error": {"code": "invalid_request",
+                                                 "message": "`task` is <product>.<module>.<task>."}})
+        with self.lock:
+            refusal = self.fail_with.pop(0) if self.fail_with else None
+        if refusal:
+            status, code = refusal
+            return handler._json(status, {"error": {"code": code, "message": code, "retry_after": 0}})
+        request = body["request"]
+        packet = last_packet(request["messages"])
+        answer = self.brain(packet, body)
+        if isinstance(answer, tuple) and len(answer) == 2 and isinstance(answer[0], int):
+            status, code = answer                       # a brain may refuse, like the gateway
+            return handler._json(status, {"error": {"code": code, "message": code, "retry_after": 0}})
+        tool_uses = []
+        if isinstance(answer, Reply):
+            text, tool_uses = answer.text, answer.tool_uses
+        else:
+            text = answer if isinstance(answer, str) else canonical(answer)
+        usage = self._usage(request)
+        usage["output_tokens"] = max(1, int((len(text) + len(canonical(tool_uses))) / CHARS_PER_TOKEN))
+        cost = int((usage["input_uncached"] * UNIT["in"] + usage["cache_read"] * UNIT["read"]
+                    + usage["cache_write_5m"] * UNIT["write"] + usage["output_tokens"] * UNIT["out"]))
+        dev = handler.path.startswith("/v1/ai/dev/")
+        price = cost if dev else int(cost * self.markup)
+        run = self.runs.get((body.get("context") or {}).get("run_id") or "")
+        with self.lock:
+            charged = price
+            if run:
+                accrued = run["accrued_micro"] + price
+                charged = max(0, min(accrued, run["quote_micro"]) - run["charged_micro"])
+                run["accrued_micro"], run["charged_micro"] = accrued, run["charged_micro"] + charged
+                run["calls"] += 1
+            self.credits -= charged
+            number = len(self.calls) + 1
+            self.calls.append({"path": handler.path, "body": body, "tool_uses": tool_uses,
+                               "idempotency_key": handler.headers.get("Idempotency-Key"),
+                               "usage": usage, "packet_id": (packet or {}).get("packet_id")})
+        rid = f"req_{number}"
+        content_events = []
+        index = 0
+        if text or not tool_uses:
+            content_events += [
+                ("content_block_start", {"type": "content_block_start", "index": 0,
+                                         "content_block": {"type": "text", "text": ""}}),
+                ("content_block_delta", {"type": "content_block_delta", "index": 0,
+                                         "delta": {"type": "text_delta", "text": text[: len(text) // 2]}}),
+                ("content_block_delta", {"type": "content_block_delta", "index": 0,
+                                         "delta": {"type": "text_delta", "text": text[len(text) // 2:]}}),
+                ("content_block_stop", {"type": "content_block_stop", "index": 0})]
+            index = 1
+        for n, use in enumerate(tool_uses):
+            raw = json.dumps(use.get("input") or {})
+            tid = use.get("id") or f"toolu_{number}_{n}"
+            content_events += [
+                ("content_block_start", {"type": "content_block_start", "index": index, "content_block": {
+                    "type": "tool_use", "id": tid, "name": use["name"], "input": {}}}),
+                ("content_block_delta", {"type": "content_block_delta", "index": index,
+                                         "delta": {"type": "input_json_delta", "partial_json": raw[: len(raw) // 2]}}),
+                ("content_block_delta", {"type": "content_block_delta", "index": index,
+                                         "delta": {"type": "input_json_delta", "partial_json": raw[len(raw) // 2:]}}),
+                ("content_block_stop", {"type": "content_block_stop", "index": index})]
+            index += 1
+        events = [
+            ("biocognia.accepted", {"gateway_request_id": rid, "billing": "dev" if dev else "credits"}),
+            ("message_start", {"type": "message_start", "message": {"id": f"msg_{number}", "usage": {
+                "input_tokens": usage["input_uncached"], "cache_read_input_tokens": usage["cache_read"],
+                "cache_creation_input_tokens": usage["cache_write_5m"], "output_tokens": 1}}}),
+            *content_events,
+            ("message_delta", {"type": "message_delta",
+                               "delta": {"stop_reason": "tool_use" if tool_uses else "end_turn"},
+                               "usage": {"output_tokens": usage["output_tokens"]}}),
+            ("message_stop", {"type": "message_stop"}),
+            ("biocognia.usage", {"gateway_request_id": rid, "status": "ok", "usage_source": "provider",
+                                 "usage": usage, "price_micro": price, "charged_micro": charged,
+                                 "billing": "dev" if dev else "credits", "model": "approved-model-a",
+                                 "provider": "provider-x",
+                                 **({"cost_micro": cost} if dev else {}),
+                                 "run": dict(run) if run else None,
+                                 "balance": {"available_micro": self.credits}}),
+        ]
+        handler.send_response(200)
+        handler.send_header("Content-Type", "text/event-stream")
+        handler.end_headers()
+        for name, data in events:
+            handler.wfile.write(f"event: {name}\ndata: {json.dumps(data)}\n\n".encode())
+            handler.wfile.flush()
+
+
+# -- a token source without a licence --------------------------------------------------------
+
+
+def fixed_tokens(product: str = "testapp", token: str = "BIOCAI1.test", *, version: str = "0.0.0"):
+    """A `biocognia.gateway.TokenSource` that always answers `token`, for a
+    product with this id: what a gateway client in a test is given."""
+    from biocognia.gateway import TokenSource
+
+    licensing = SimpleNamespace(product=SimpleNamespace(id=product, name=product, cli=product, version=version))
+    return TokenSource(licensing, token)
+
+
+def client(fake: "FakeGateway", *, product: str = "testapp", **options):
+    """A `gateway.GatewayClient` for `fake`, with no waiting between retries."""
+    from spatialagents.gateway import GatewayClient
+
+    options.setdefault("sleep", lambda seconds: None)
+    return GatewayClient(fixed_tokens(product), fake.url, **options)
+
+
+# -- a stand-in product ------------------------------------------------------------------------
+
+
+class ToolFailure(Exception):
+    """Raised by a `FakeTool` handler: the call fails with this code and message."""
+
+    def __init__(self, code: str, message: str, detail=None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.detail = detail
+
+
+@dataclass
+class FakeTool:
+    """One tool of a `FakeToolBackend`.
+
+    `handler(arguments)` returns the result (a dict may carry `_images`, and a
+    write's `_receipt` -- `{"undo": bool, "advanced": {...}}` -- which is lifted
+    into the outcome); raising `ToolFailure` fails the call with its code, any
+    other exception as `internal_error`. `permission` is a class or a function
+    of the arguments (a tool whose class depends on them). `input_schema` is a
+    JSON schema; its `required` fields are checked, and so are the types
+    `integer`, `number`, `string` and `boolean` of its properties."""
+
+    name: str
+    handler: Callable[[dict], Any]
+    purpose: str = ""
+    permission: str | Callable[[dict], str] = "read"
+    input_schema: dict = field(default_factory=lambda: {"type": "object", "properties": {}})
+    #: None: cacheable when it reads.
+    cacheable: bool | None = None
+    egress: str = "aggregates"
+    viewer: bool = False
+    capability: str | None = None
+
+    def permission_for(self, arguments: dict) -> str:
+        return self.permission(arguments) if callable(self.permission) else self.permission
+
+
+_TYPES = {"integer": int, "number": (int, float), "string": str, "boolean": bool}
+
+
+class FakeToolBackend:
+    """A `ToolBackend` over the `FakeTool`s a test defines.
+
+    It checks a call as a product's own surface would: the arguments against
+    the schema, the policy's egress and write permissions, and for a
+    source-file write or a delete the policy flag AND the person's approval
+    (`approved=True`) -- so an agent that never asked is refused with
+    `permission_required`. Every successful write moves `revision` on (what
+    `revision_token` answers), so a remembered read is invalidated by any write.
+    `calls` records every invoke: `(tool, arguments, approved)`."""
+
+    def __init__(self, tools=(), *, skills: dict | None = None, info: dict | None = None,
+                 revision_guard: tuple[str, str] | None = None, max_result_chars: int | None = None):
+        from spatialagents import serialize
+
+        self.tools: dict[str, FakeTool] = {}
+        for tool in tools:
+            self.add(tool)
+        self.skill_texts = dict(skills or {})
+        self.info = dict(info or {})
+        self.revision_guard = revision_guard
+        self.max_result_chars = max_result_chars or serialize.MAX_RESULT_CHARS
+        self.revision = 0
+        self.calls: list[tuple] = []
+        self._ops = 0
+        self._lock = threading.Lock()
+
+    def add(self, tool: FakeTool) -> FakeTool:
+        self.tools[tool.name] = tool
+        return tool
+
+    def tool(self, name: str, *, purpose: str = "", permission="read", schema: dict | None = None, **kw):
+        """Decorator: the function becomes a tool's handler."""
+        def register(handler):
+            self.add(FakeTool(name, handler, purpose=purpose, permission=permission,
+                              input_schema=schema or {"type": "object", "properties": {}}, **kw))
+            return handler
+        return register
+
+    # -- the protocol ----------------------------------------------------------------
+
+    def catalog(self, policy, *, viewer: bool = False) -> list[dict]:
+        out = []
+        for tool in self.tools.values():
+            permission = tool.permission_for({})
+            if tool.egress not in policy.egress:
+                continue
+            if permission != "read" and not policy.allow_writes:
+                continue
+            if tool.viewer and not viewer:
+                continue
+            out.append({"tool": tool.name, "capability": tool.capability or f"fake.{tool.name}",
+                        "permission": permission, "purpose": tool.purpose})
+        return out
+
+    def definition(self, tool: str) -> dict:
+        spec = self.tools[tool]
+        return {"name": spec.name, "description": spec.purpose, "input_schema": json.loads(json.dumps(
+            spec.input_schema))}
+
+    def permission(self, tool: str, arguments: dict) -> str:
+        spec = self.tools.get(tool)
+        return spec.permission_for(arguments) if spec else "read"
+
+    def purpose(self, tool: str) -> str:
+        spec = self.tools.get(tool)
+        return spec.purpose if spec else ""
+
+    def cacheable(self, tool: str, arguments: dict) -> bool:
+        spec = self.tools.get(tool)
+        if spec is None:
+            return False
+        if spec.cacheable is not None:
+            return spec.cacheable
+        return self.permission(tool, arguments) == "read" and spec.egress not in ("row_level", "raw_pixels") \
+            and not spec.viewer
+
+    def revision_token(self, tool: str, arguments: dict) -> str:
+        return str(self.revision)
+
+    def skills(self) -> list[dict]:
+        return [{"name": name, "title": name.replace("-", " ").title(), "when": f"before {name} work"}
+                for name in self.skill_texts]
+
+    def read_skill(self, name: str) -> str:
+        if name not in self.skill_texts:
+            raise KeyError(f"no skill {name!r}")
+        return self.skill_texts[name]
+
+    def server_info(self, policy, *, tools: int, viewer: bool) -> dict:
+        return {"product": "fake", **self.info, "policy": policy.describe(), "n_tools": tools,
+                "viewer": viewer, "skills": [s["name"] for s in self.skills()]}
+
+    def serialize(self, value):
+        from spatialagents import serialize
+
+        return serialize.clean(value)
+
+    def split_images(self, result) -> tuple:
+        from spatialagents.backend import split_images
+
+        return split_images(result)
+
+    def invoke(self, tool: str, arguments: dict, *, policy, approved: bool = False) -> dict:
+        from spatialagents import backend
+
+        arguments = dict(arguments or {})
+        with self._lock:
+            self.calls.append((tool, arguments, approved))
+        spec = self.tools.get(tool)
+        if spec is None:
+            return backend.failed("unknown_capability", f"no tool {tool!r}")
+        problem = self._check(spec, arguments)
+        if problem:
+            return backend.failed("invalid_input", problem)
+        permission = spec.permission_for(arguments)
+        refused = self._refused(spec, permission, policy, approved)
+        if refused:
+            return refused
+        operation_id = None
+        if permission != "read":
+            with self._lock:
+                self._ops += 1
+                operation_id = f"op_{self._ops:04d}"
+        try:
+            result = spec.handler(arguments)
+        except ToolFailure as exc:
+            return backend.failed(exc.code, exc.message, detail=exc.detail, operation_id=operation_id)
+        except Exception as exc:              # noqa: BLE001 -- the outcome says what happened
+            return backend.failed("internal_error", f"{type(exc).__name__}: {exc}", operation_id=operation_id)
+        receipt = result.pop("_receipt", None) if isinstance(result, dict) else None
+        if permission != "read":
+            with self._lock:
+                self.revision += 1
+        receipt = receipt or {}
+        return backend.ok(result, operation_id=operation_id,
+                          undo=bool(receipt.get("undo", permission == "reversible_write")),
+                          advanced=receipt.get("advanced"))
+
+    # -- checks ------------------------------------------------------------------------
+
+    @staticmethod
+    def _check(spec: FakeTool, arguments: dict) -> str | None:
+        schema = spec.input_schema or {}
+        missing = [name for name in schema.get("required") or () if name not in arguments]
+        if missing:
+            return f"missing {', '.join(missing)}"
+        for name, prop in (schema.get("properties") or {}).items():
+            kind = _TYPES.get((prop or {}).get("type"))
+            if name in arguments and kind is not None and arguments[name] is not None:
+                value = arguments[name]
+                if not isinstance(value, kind) or (kind is int and isinstance(value, bool)):
+                    return f"{name} must be {prop['type']}"
+        return None
+
+    @staticmethod
+    def _refused(spec: FakeTool, permission: str, policy, approved: bool) -> dict | None:
+        from spatialagents import backend
+
+        if spec.egress not in policy.egress:
+            return backend.failed("permission_required", f"{spec.name} returns {spec.egress} data")
+        if permission != "read" and not policy.allow_writes:
+            return backend.failed("permission_required", f"{spec.name} changes state, and this conversation "
+                                  "may only read")
+        if permission == "source_file_write" and not (policy.allow_source_writes and approved):
+            return backend.failed("permission_required", f"{spec.name} writes into the user's source file; "
+                                  "the user must approve it", detail={"permission": permission})
+        if permission == "destructive" and not (policy.allow_destructive and approved):
+            return backend.failed("permission_required", f"{spec.name} cannot be undone; the user must "
+                                  "approve it", detail={"permission": permission})
+        return None
+
+
+# -- a stand-in plan host --------------------------------------------------------------------------
+
+#: The sentence kinds a summary may use, as SCIMAP Pro's claims checker names them.
+SENTENCE_KINDS = ("computed", "interpretation", "background", "proposed")
+
+
+class FakePlanHost:
+    """A `plans.PlanHost` over functions a test defines: the reference host.
+
+    `functions` maps a name to `handler(arguments) -> result` (raise to fail
+    the step). A composed answer is `{"steps": [{"id", "function",
+    "arguments", "rationale"}], "summary"}`; a step naming a function there is
+    not is a repairable `unknown_function` problem, and no steps is "nothing
+    to run". `decisions` are added to every composed plan (blocking, each
+    `{id, kind, question, options?, binds?}`); an answer that `binds` a name
+    fills `{name}` in the steps' arguments. A step with `checkpoint: true`
+    raises a non-blocking `confirm_labels` decision after it runs, and the run
+    waits there. A summary's computed sentence must cite a step that ran;
+    settling downgrades one that does not to an interpretation, and writes
+    `<root>/<plan_id>.report.md` when a root is given."""
+
+    def __init__(self, functions: dict, *, decisions=(), root=None, compose_task: str = "plan.compose",
+                 summarise_task: str = "plan.summarise", claim_ceiling: str = "descriptive"):
+        self.functions = dict(functions)
+        self.decision_specs = [dict(d) for d in decisions]
+        self.root = root
+        self.compose_task = compose_task
+        self.summarise_task = summarise_task
+        self.claim_ceiling = claim_ceiling
+        self.plans: dict = {}
+        self.calls: list = []
+        self._n = 0
+        self._lock = threading.Lock()
+
+    # -- compose -----------------------------------------------------------------
+
+    def compose_schema(self) -> dict:
+        value = {"anyOf": [{"type": "string"}, {"type": "number"}, {"type": "boolean"}, {"type": "null"}]}
+        return {"type": "object", "properties": {
+            "steps": {"type": "array", "items": {"type": "object", "properties": {
+                "id": {"type": "string"}, "function": {"type": "string", "enum": sorted(self.functions)},
+                "arguments": {"type": "object", "additionalProperties": value},
+                "rationale": {"type": "string"}, "checkpoint": {"type": "boolean"}},
+                "required": ["id", "function", "arguments", "rationale"]}},
+            "summary": {"type": "string"}}, "required": ["steps", "summary"]}
+
+    def compose_packet(self, goal: str, dataset: str) -> dict:
+        self.calls.append(("compose_packet", goal, dataset))
+        return {"task": self.compose_task, "schema": self.compose_schema(),
+                "input": {"goal": goal, "dataset": dataset, "functions": sorted(self.functions),
+                          "instructions": "Compose steps from `functions` that answer the goal."}}
+
+    def accept_composed(self, goal: str, dataset: str, answer: dict, *, plan_id: str | None = None):
+        self.calls.append(("accept_composed", plan_id))
+        steps = list((answer or {}).get("steps") or [])
+        if not steps:
+            return None, []
+        if plan_id is not None and self.plans.get(plan_id, {}).get("status") not in (None, "draft", "validated"):
+            raise ValueError(f"plan {plan_id} is confirmed; a new composition is a new plan")
+        with self._lock:
+            self._n += 1
+            plan_id = plan_id or f"pl_{self._n:04d}"
+        plan = {"id": plan_id, "version": 1, "goal": goal, "dataset": dataset, "status": "draft",
+                "claim_ceiling": self.claim_ceiling, "unit_of_replication": "image", "n_per_arm": None,
+                "parameters": {}, "steps": [], "decisions": [], "validation": {"ok": False, "problems": []}}
+        problems = []
+        for n, step in enumerate(steps, start=1):
+            function = str(step.get("function"))
+            plan["steps"].append({"id": str(step.get("id") or f"s{n}"), "n": n, "function": function,
+                                  "arguments": dict(step.get("arguments") or {}),
+                                  "template_arguments": dict(step.get("arguments") or {}),
+                                  "rationale": step.get("rationale"), "rationale_by": "agent",
+                                  "checkpoint": bool(step.get("checkpoint")), "status": "pending", "error": None})
+            if function not in self.functions:
+                problems.append({"step": plan["steps"][-1]["id"], "kind": "unknown_function", "blocking": True,
+                                 "message": f"{function!r} is not a function; choose from {sorted(self.functions)}"})
+        plan["decisions"] = [{"state": "open", "answer": None, "blocking": True, "options": [], "binds": [],
+                              "step_ids": [], **spec} for spec in self.decision_specs]
+        plan["validation"]["problems"] = problems
+        self.plans[plan_id] = plan
+        self._validate(plan)
+        return self.plan(plan_id), [p for p in problems if p["kind"] == "unknown_function"]
+
+    def _validate(self, plan: dict) -> None:
+        if plan["status"] not in ("draft", "validated"):
+            return
+        blocking = [d for d in plan["decisions"] if d["state"] == "open" and d.get("blocking", True)]
+        problems = [p for p in plan["validation"]["problems"] if p.get("blocking")]
+        plan["validation"]["ok"] = not blocking and not problems
+        plan["status"] = "validated" if plan["validation"]["ok"] else "draft"
+
+    # -- the view and the person ----------------------------------------------------
+
+    def plan(self, plan_id: str) -> dict:
+        if plan_id not in self.plans:
+            raise KeyError(f"no plan {plan_id!r}")
+        out = json.loads(json.dumps(self.plans[plan_id], default=str))
+        for step in out["steps"]:
+            step.pop("template_arguments", None)
+        out["next"] = {"draft": "answer the open decisions", "validated": "confirm to run",
+                       "awaiting_decision": "answer, then continue", "done": "summarise"}.get(out["status"], "")
+        return out
+
+    def answer(self, plan_id: str, decision_id: str, value) -> dict:
+        self.calls.append(("answer", decision_id, value))
+        plan = self.plans[plan_id]
+        decision = next((d for d in plan["decisions"] if d["id"] == decision_id), None)
+        if decision is None:
+            raise ValueError(f"plan {plan_id} has no decision {decision_id!r}")
+        ids = [o.get("id") for o in decision.get("options") or () if isinstance(o, dict)]
+        if ids and value not in ids:
+            raise ValueError(f"{value!r} is not one of {ids}")
+        decision.update(state="answered", answer=value, answered_by="user")
+        for name in decision.get("binds") or ():
+            plan["parameters"][name] = value
+        bound = plan["parameters"]
+        for step in plan["steps"]:
+            step["arguments"] = {k: bound.get(v[1:-1], v) if isinstance(v, str) and v[:1] == "{" and v[-1:] == "}"
+                                 else v for k, v in step["template_arguments"].items()}
+        self._validate(plan)
+        return self.plan(plan_id)
+
+    # -- the run ---------------------------------------------------------------------------
+
+    def run(self, plan_id: str, *, confirm: bool = False, from_step=None, until_step=None) -> dict:
+        self.calls.append(("run", confirm, from_step, until_step))
+        plan = self.plans[plan_id]
+        if plan["status"] in ("draft", "validated"):
+            if not confirm:
+                return {**self.plan(plan_id), "ran": [], "status": "needs_confirmation"}
+            if plan["status"] != "validated":
+                raise ValueError(f"plan {plan_id} is not ready to confirm")
+            plan["status"] = "confirmed"
+        if any(d["state"] == "answered" and d["answer"] == "stop" for d in plan["decisions"]):
+            plan["status"] = "stopped"
+            return {**self.plan(plan_id), "ran": []}
+        ran = []
+        plan["status"] = "running"
+        started = from_step is None
+        for step in plan["steps"]:
+            if not started:
+                started = step["id"] == str(from_step)
+                if not started:
+                    continue
+            if step["status"] == "done" and from_step is None:
+                continue
+            if any(d["state"] == "open" and step["id"] in (d.get("step_ids") or ()) for d in plan["decisions"]):
+                plan["status"] = "awaiting_decision"
+                break
+            try:
+                result = self.functions[step["function"]](dict(step["arguments"]))
+                step.update(status="done", error=None, result=result)
+            except Exception as exc:          # noqa: BLE001 -- recorded on the step
+                step.update(status="failed", error={"message": f"{type(exc).__name__}: {exc}"})
+            ran.append({"step": step["id"], "n": step["n"], "function": step["function"],
+                        "status": step["status"], **({"error": step["error"]} if step["error"] else {})})
+            if step["status"] == "failed":
+                plan["status"] = "failed"
+                break
+            if step.get("checkpoint"):
+                later = [s["id"] for s in plan["steps"] if s["n"] > step["n"]]
+                if later and not any(d["id"] == f"d-look-{step['id']}" for d in plan["decisions"]):
+                    plan["decisions"].append({
+                        "id": f"d-look-{step['id']}", "kind": "confirm_labels", "blocking": False,
+                        "question": f"Do the labels {step['id']} made look right?", "state": "open",
+                        "answer": None, "step_ids": later[:1], "binds": [],
+                        "options": [{"id": "continue", "label": "They look right; continue", "recommended": True},
+                                    {"id": "stop", "label": "Stop here"}]})
+                    plan["status"] = "awaiting_decision"
+                    break
+            if until_step is not None and step["id"] == str(until_step):
+                plan["status"] = "stopped"
+                break
+        else:
+            plan["status"] = "done"
+        return {**self.plan(plan_id), "ran": ran}
+
+    # -- the summary --------------------------------------------------------------------------
+
+    def _ran(self, plan: dict) -> dict:
+        return {s["id"]: s for s in plan["steps"] if s["status"] == "done"}
+
+    def summarise_packet(self, plan_id: str) -> dict:
+        plan = self.plans[plan_id]
+        ran = self._ran(plan)
+        cite = {"type": "string", "enum": sorted(ran)} if ran else {"type": "string"}
+        return {"task": self.summarise_task,
+                "input": {"goal": plan["goal"], "claim_ceiling": plan["claim_ceiling"],
+                          "results": [{"cite": sid, "function": s["function"], "result": s.get("result")}
+                                      for sid, s in ran.items()]},
+                "schema": {"type": "object", "properties": {"sentences": {"type": "array", "items": {
+                    "type": "object", "properties": {"kind": {"type": "string", "enum": list(SENTENCE_KINDS)},
+                                                     "text": {"type": "string"},
+                                                     "cites": {"type": "array", "items": cite}},
+                    "required": ["kind", "text", "cites"]}}}, "required": ["sentences"]}}
+
+    def accept_summary(self, plan_id: str, answer: dict) -> list:
+        ran = self._ran(self.plans[plan_id])
+        problems = []
+        for n, sentence in enumerate((answer or {}).get("sentences") or (), start=1):
+            if sentence.get("kind") == "computed" and not sentence.get("cites"):
+                problems.append({"sentence": n, "message": f"sentence {n} is computed but cites no result"})
+            unknown = [c for c in sentence.get("cites") or () if c not in ran]
+            if unknown:
+                problems.append({"sentence": n, "message": f"sentence {n} cites {unknown}, which did not run"})
+        return problems
+
+    def settle_summary(self, plan_id: str, answer: dict) -> dict:
+        ran = self._ran(self.plans[plan_id])
+        settled = []
+        for sentence in (answer or {}).get("sentences") or ():
+            cites = [c for c in sentence.get("cites") or () if c in ran]
+            kind = sentence.get("kind") if sentence.get("kind") in SENTENCE_KINDS else "interpretation"
+            caveats = []
+            if kind == "computed" and not cites:
+                kind, caveats = "interpretation", ["cites no result that ran"]
+            settled.append({"kind": kind, "text": str(sentence.get("text") or ""), "cites": cites,
+                            "caveats": caveats})
+        lines = [f"# {self.plans[plan_id]['goal']}", ""]
+        for kind in SENTENCE_KINDS:
+            mine = [s for s in settled if s["kind"] == kind]
+            if mine:
+                lines += [f"## {kind.title()}", ""] + [f"- {s['text']}" + (f" [{', '.join(s['cites'])}]"
+                                                                          if s["cites"] else "")
+                                                      for s in mine] + [""]
+        markdown = "\n".join(lines)
+        path = None
+        if self.root is not None:
+            from pathlib import Path
+
+            path = Path(self.root) / f"{plan_id}.report.md"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(markdown, encoding="utf-8")
+        return {"sentences": settled, "markdown": markdown, "path": str(path) if path else None}
+
+
+def plan_brain(compose, summary=None, *, subagent=None):
+    """A FakeGateway brain for plan packets: `compose` answers (a list, used in
+    order, or one answer) for compose calls and `summary` likewise for summary
+    calls, told apart by the task; anything else answers `{}`."""
+    queues = {"compose": list(compose) if isinstance(compose, list) else [compose],
+              "summarise": list(summary) if isinstance(summary, list) else ([summary] if summary else [])}
+
+    def brain(packet, body):
+        task = body.get("task") or ""
+        name = "compose" if task.endswith(".compose") else "summarise" if task.endswith(".summarise") else None
+        if name is None or not queues[name]:
+            return {}
+        step = queues[name].pop(0) if len(queues[name]) > 1 else queues[name][0]
+        return step(body) if callable(step) else step
+    return brain
+
+
+# -- a scripted model ----------------------------------------------------------------------------
+
+
+class ScriptedBrain:
+    """A FakeGateway brain that answers from a script.
+
+    `steps` answer the main conversation's calls in order: a `Reply`, a string
+    or JSON-able answer, `(status, code)` to refuse, or a function of the
+    request body returning one of those. When the script runs out it answers
+    `final`. `subagent` (a function of the body, or a list like `steps`)
+    answers sub-agent calls (`context.agent == "chat_subagent"`). `bodies`
+    keeps every request body it was asked with.
+
+    `ScriptedBrain.replaying(calls)` is the oracle form: each call of a plan
+    (`{"name", "arguments"}`) is issued through `call_tool`, one per model
+    call, then `final`."""
+
+    def __init__(self, steps=(), *, final="done.", subagent=None):
+        self.steps = list(steps)
+        self.final = final
+        self.subagent = subagent if callable(subagent) or subagent is None else list(subagent)
+        self.bodies: list[dict] = []
+        self._lock = threading.Lock()
+
+    @classmethod
+    def replaying(cls, calls, *, final: str = "done.") -> "ScriptedBrain":
+        steps = [Reply("", [{"name": "call_tool", "input": {"name": c["name"],
+                                                             "arguments": dict(c.get("arguments") or {})}}])
+                 for c in calls]
+        return cls(steps, final=final)
+
+    def _next(self, queue: list, body):
+        step = queue.pop(0) if queue else Reply(self.final)
+        return step(body) if callable(step) else step
+
+    def __call__(self, packet, body):
+        with self._lock:
+            self.bodies.append(body)
+            if (body.get("context") or {}).get("agent") == "chat_subagent" and self.subagent is not None:
+                if callable(self.subagent):
+                    return self.subagent(body)
+                return self._next(self.subagent, body)
+            return self._next(self.steps, body)
+
+
+# -- pytest fixtures (inert unless asked for) -------------------------------------------------------
+
+try:
+    import pytest
+except ImportError:  # pragma: no cover - the package works without pytest
+    pytest = None
+
+if pytest is not None:
+
+    @pytest.fixture
+    def spatialagents_gateway():
+        """`start(brain, **options)` -> a running FakeGateway, stopped at teardown."""
+        started = []
+
+        def start(brain, **options):
+            fake = FakeGateway(brain, **options).__enter__()
+            started.append(fake)
+            return fake
+
+        yield start
+        for fake in reversed(started):
+            fake.__exit__(None, None, None)
+
+    @pytest.fixture
+    def spatialagents_tokens():
+        """A token source for product `testapp` that needs no licence."""
+        return fixed_tokens()
+
+    @pytest.fixture
+    def spatialagents_backend():
+        """An empty FakeToolBackend; add tools with `.add(FakeTool(...))` or `@backend.tool(...)`."""
+        return FakeToolBackend()