spatialagents 0.1.0__py3-none-any.whl

spatialagents/toolcache.py

@@ -0,0 +1,144 @@
+"""Tool-result caching (harness Layer 3): a read already answered is not run again.
+
+A product's reads are idempotent for a given revision of what they read, and
+its renders are deterministic, so `ToolResultCache.get_or_call` keys every
+cacheable call on
+
+    (capability, canonical(arguments), revision, product version)
+
+and hands back the stored answer instead of recomputing it -- across turns,
+sub-agents, retries and conversations. The same bytes sent to the model again
+also read from the provider's prompt cache.
+
+What may be cached is the backend's decision (`ToolBackend.cacheable`), made
+per call, and the caller asks the cache only for those: a write never, a call
+that returns cell-level data never (it is not copied onto disk a second time),
+viewer state never (what a tab shows changes without a receipt). A failed call
+is never stored, whoever asked.
+
+Invalidation is the revision (`ToolBackend.revision_token`), which every
+receipted write moves on. Edits a person makes outside the harness may leave
+no receipt, so an entry also expires after `max_age_s` (15 minutes by
+default).
+
+Entries are content-addressed files, `<root>/<k[:2]>/<key>.json`, images
+inline as base64, under the root the product gives (Plexora's
+`<data_root>/.agent/ai/toolcache/`, SCIMAP Pro's
+`<configDir>/ai-cache/toolcache/`). The product's version is part of every
+key, so a release never reads its predecessor's answers. A hit is reported as
+`source: cache` to the caller, which records it in the trace.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import threading
+import time
+from pathlib import Path
+
+from spatialagents.wire import canonical
+
+MAX_AGE_S = 15 * 60
+MAX_ENTRY_BYTES = 24 * 1024 * 1024
+
+
+def _encode(value):
+    if isinstance(value, (bytes, bytearray)):
+        return {"__b64__": base64.b64encode(bytes(value)).decode("ascii")}
+    if isinstance(value, dict):
+        return {k: _encode(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_encode(v) for v in value]
+    return value
+
+
+def _decode(value):
+    if isinstance(value, dict):
+        if set(value) == {"__b64__"}:
+            return base64.b64decode(value["__b64__"])
+        return {k: _decode(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_decode(v) for v in value]
+    return value
+
+
+class ToolResultCache:
+    def __init__(self, root: Path | str, *, version: str, max_age_s: float | None = MAX_AGE_S):
+        self.root = Path(root)
+        self.max_age_s = max_age_s
+        self.version = str(version)
+        self.hits = 0
+        self.misses = 0
+        self._lock = threading.Lock()
+
+    def key(self, capability: str, arguments: dict, revision: str) -> str:
+        material = canonical({"capability": capability, "arguments": arguments or {},
+                              "revision": str(revision), "version": self.version})
+        return hashlib.sha256(material.encode("utf-8")).hexdigest()[:40]
+
+    def _path(self, key: str) -> Path:
+        return self.root / key[:2] / f"{key}.json"
+
+    def get(self, key: str):
+        path = self._path(key)
+        try:
+            if self.max_age_s is not None and time.time() - path.stat().st_mtime > self.max_age_s:
+                return None
+            return _decode(json.loads(path.read_text(encoding="utf-8")))
+        except (OSError, ValueError):
+            return None
+
+    def put(self, key: str, outcome: dict) -> bool:
+        try:
+            text = json.dumps(_encode(outcome), separators=(",", ":"), ensure_ascii=False)
+        except (TypeError, ValueError):
+            return False
+        if len(text) > MAX_ENTRY_BYTES:
+            return False
+        path = self._path(key)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(f"{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+        tmp.write_text(text, encoding="utf-8")
+        try:
+            os.replace(tmp, path)
+        except PermissionError:
+            tmp.unlink(missing_ok=True)
+            return False
+        return True
+
+    def get_or_call(self, capability: str, arguments: dict, revision: str, call):
+        """`(outcome, source)`: the stored answer and `"cache"`, or `call()`'s and
+        `"live"` (stored when it succeeded). `capability` is the name the call
+        is keyed by (the backend's capability name for the tool); `call` takes
+        no arguments and returns a `ToolBackend.invoke` outcome. The caller
+        has already asked the backend whether this call may be cached."""
+        key = self.key(capability, arguments, revision)
+        stored = self.get(key)
+        if stored is not None:
+            with self._lock:
+                self.hits += 1
+            return stored, "cache"
+        outcome = call()
+        with self._lock:
+            self.misses += 1
+        if isinstance(outcome, dict) and outcome.get("ok"):
+            self.put(key, outcome)
+        return outcome, "live"
+
+    def sweep(self, now: float | None = None) -> int:
+        """Delete expired entries; returns how many."""
+        now = now or time.time()
+        removed = 0
+        if not self.root.is_dir() or self.max_age_s is None:
+            return 0
+        for path in self.root.glob("*/*.json"):
+            try:
+                if now - path.stat().st_mtime > self.max_age_s:
+                    path.unlink()
+                    removed += 1
+            except OSError:
+                continue
+        return removed

spatialagents/tools.py

@@ -0,0 +1,460 @@
+"""The conversational agent's tools: a product's tools, deferred.
+
+`ToolAdapter` turns a `ToolBackend`'s catalog into what a model is given, and
+runs what it calls.
+
+**Frozen at conversation start.** The catalog is every tool the policy could
+let through (`ToolBackend.catalog`: egress allowed; writes only when the
+policy allows writes; source-file writes and deletes included, because they
+pause for the user's approval rather than being refused), minus any name a
+local tool already has. Sorted by tool name, so the bytes are the same for
+every conversation of one build and policy.
+
+**Deferred schemas.** The model is not sent ~100 full tool schemas. The
+system prompt lists each catalog tool's name and one-line purpose; the
+`tools` array holds only the local tools (`load_tool`, `call_tool`,
+`list_skills`, `read_skill`, `read_artifact`, `server_info`, the sub-agent and
+board tools) and NEVER changes during a conversation. `load_tool` returns the
+full definitions it is asked for as its result, in the history; the model then
+runs a catalog tool through `call_tool(name, arguments)`. Providers cache
+tools first, then the system prompt, then the messages, so a tools array that
+grew on every load would make the next call rewrite the whole cached prefix
+and history; a fixed one keeps every call reading them from cache. Arguments
+are validated by the backend exactly as for a native tool call, and an
+approval is asked for the tool `call_tool` names, never bypassed through it.
+Two local tools describe the product (`list_skills`, `server_info`): their
+descriptions are the product's (`ChatProfile.tool_descriptions`).
+
+**Executing.** A catalog tool runs through `ToolBackend.invoke`, through the
+`ToolResultCache` when the backend says the call is cacheable (keyed on its
+`revision_token`); images go back as image blocks (`split_images`), text is
+compact JSON (`serialize`, bounded at the backend's `max_result_chars`), and a
+result above the offload threshold becomes a stub the model reads slices of
+with `read_artifact` (`offload.py`). A reversible write reports its
+operation_id so a panel can offer Undo.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import threading
+import time
+from dataclasses import dataclass, field
+
+from spatialagents import offload as offloading
+from spatialagents import serialize
+from spatialagents.policy import NEEDS_APPROVAL
+from spatialagents.wire import canonical, image_block, text_block
+
+#: The Worker accepts at most 64 tool definitions per request.
+MAX_TOOLS = 64
+#: Images one tool result may carry to the model.
+MAX_RESULT_IMAGES = 4
+
+LOAD_TOOL = "load_tool"
+CALL_TOOL = "call_tool"
+SPAWN_AGENTS = "spawn_agents"
+AWAIT_AGENTS = "await_agents"
+READ_BOARD = "read_board"
+POST_BOARD = "post_board"
+LIST_SKILLS = "list_skills"
+READ_SKILL = "read_skill"
+READ_ARTIFACT = "read_artifact"
+SERVER_INFO = "server_info"
+
+#: Local tools a sub-agent always has (it never spawns or loads beyond its brief).
+SUBAGENT_LOCAL = (LOAD_TOOL, CALL_TOOL, LIST_SKILLS, READ_SKILL, READ_ARTIFACT, SERVER_INFO, READ_BOARD,
+                  POST_BOARD)
+
+#: What the two product-describing local tools say when the product gives no words of its own.
+DEFAULT_DESCRIPTIONS = {
+    LIST_SKILLS: "The runtime skills: name, title and when to use each.",
+    SERVER_INFO: "What this application is: version, data directory, the permissions this conversation "
+                 "has, the skills and the licence.",
+}
+
+
+def _local_definitions(descriptions: dict | None = None) -> list:
+    said = {**DEFAULT_DESCRIPTIONS, **(descriptions or {})}
+    defs = [
+        {"name": LOAD_TOOL,
+         "description": "Get the full definitions (description and input_schema) of catalog tools, so you "
+                        "can call them with call_tool. Pass every name you expect to need.",
+         "input_schema": {"type": "object", "properties": {
+             "names": {"type": "array", "items": {"type": "string"},
+                       "description": "Tool names from the catalog."}}, "required": ["names"]}},
+        {"name": CALL_TOOL,
+         "description": "Run one catalog tool. `arguments` must match the input_schema load_tool returned "
+                        "for it. Several call_tool calls in one turn run in order.",
+         "input_schema": {"type": "object", "properties": {
+             "name": {"type": "string", "description": "A tool name from the catalog."},
+             "arguments": {"type": "object", "description": "The tool's arguments."}},
+             "required": ["name"]}},
+        {"name": LIST_SKILLS,
+         "description": said[LIST_SKILLS],
+         "input_schema": {"type": "object", "properties": {}}},
+        {"name": READ_SKILL,
+         "description": "Read one skill (a SKILL.md) before doing that kind of work.",
+         "input_schema": {"type": "object", "properties": {"name": {"type": "string"}},
+                          "required": ["name"]}},
+        {"name": SERVER_INFO,
+         "description": said[SERVER_INFO],
+         "input_schema": {"type": "object", "properties": {}}},
+        {"name": READ_ARTIFACT,
+         "description": "Read part of a large tool result that was offloaded (it came back as a stub "
+                        "with an artifact_id): a character range, or the lines matching a query.",
+         "input_schema": {"type": "object", "properties": {
+             "artifact_id": {"type": "string"},
+             "start": {"type": "integer", "description": "First character (default 0)."},
+             "end": {"type": "integer", "description": "One past the last character."},
+             "query": {"type": "string", "description": "Return the lines containing this text."}},
+             "required": ["artifact_id"]}},
+        {"name": SPAWN_AGENTS,
+         "description": "Run sub-agents for independent pieces of work, in parallel where their "
+                        "dependencies allow. Each gets a brief and returns a short typed summary. "
+                        "wait=false returns their ids at once; await_agents collects the summaries.",
+         "input_schema": {"type": "object", "properties": {
+             "agents": {"type": "array", "items": {"type": "object", "properties": {
+                 "id": {"type": "string", "description": "Optional id other agents can depend on."},
+                 "role": {"type": "string", "description": "A short role, e.g. image_reader."},
+                 "brief": {"type": "string", "description": "Exactly what this agent must do."},
+                 "inputs": {"type": "object", "description": "Small JSON inputs (names, ids)."},
+                 "depends_on": {"type": "array", "items": {"type": "string"}},
+                 "tools": {"type": "array", "items": {"type": "string"},
+                           "description": "Catalog tools it may call (default: the read-only ones)."}},
+                 "required": ["role", "brief"]}},
+             "wait": {"type": "boolean", "description": "Wait for every summary (default true)."}},
+             "required": ["agents"]}},
+        {"name": AWAIT_AGENTS,
+         "description": "Wait for sub-agents started with wait=false and return their summaries.",
+         "input_schema": {"type": "object", "properties": {
+             "ids": {"type": "array", "items": {"type": "string"}},
+             "timeout_s": {"type": "number", "description": "At most this long (default 120)."}},
+             "required": ["ids"]}},
+        {"name": READ_BOARD,
+         "description": "Read facts the agents of this conversation posted. A key ending in * reads "
+                        "every key with that prefix.",
+         "input_schema": {"type": "object", "properties": {
+             "keys": {"type": "array", "items": {"type": "string"}}}, "required": ["keys"]}},
+        {"name": POST_BOARD,
+         "description": "Post a small fact for the other agents of this conversation to read.",
+         "input_schema": {"type": "object", "properties": {
+             "key": {"type": "string"}, "value": {"description": "Any small JSON value."}},
+             "required": ["key", "value"]}},
+    ]
+    return sorted(defs, key=lambda d: d["name"])
+
+
+LOCAL_NAMES = tuple(d["name"] for d in _local_definitions())
+
+
+def one_line(purpose: str, limit: int = 140) -> str:
+    text = " ".join(str(purpose or "").split())
+    for stop in (". ", "; "):
+        if stop in text:
+            text = text.split(stop, 1)[0]
+            break
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "..."
+
+
+def build_catalog(backend, policy, *, viewer: bool = False) -> list:
+    """The tools a conversation may use under `policy`, by tool name."""
+    entries = []
+    for entry in backend.catalog(policy, viewer=viewer):
+        tool = str(entry["tool"])
+        if tool in LOCAL_NAMES:
+            continue
+        entries.append({"tool": tool, "capability": entry.get("capability") or tool,
+                        "permission": entry["permission"], "purpose": one_line(entry.get("purpose") or "")})
+    return sorted(entries, key=lambda e: e["tool"])
+
+
+def catalog_text(catalog: list) -> str:
+    marks = {"read": "", "reversible_write": " [write, undoable]",
+             "source_file_write": " [writes source file: needs approval]",
+             "destructive": " [cannot be undone: needs approval]"}
+    lines = ["TOOL CATALOG (load_tool gives a tool's definition; run it with call_tool)"]
+    lines += [f"- {e['tool']}: {e['purpose']}{marks.get(e['permission'], '')}" for e in catalog]
+    return "\n".join(lines)
+
+
+def definition_for(backend, tool: str) -> dict:
+    """The backend's definition of `tool` as the model is given it: titles
+    stripped (they repeat the field names), an object schema."""
+    given = backend.definition(tool) or {}
+    schema = _strip_titles(copy.deepcopy(given.get("input_schema") or {}))
+    schema.setdefault("type", "object")
+    return {"name": given.get("name") or tool, "description": given.get("description") or "",
+            "input_schema": schema}
+
+
+def _strip_titles(node):
+    if isinstance(node, dict):
+        props = node.get("properties")
+        out = {k: _strip_titles(v) for k, v in node.items() if k != "title" or isinstance(v, dict)}
+        if isinstance(props, dict):
+            out["properties"] = {k: _strip_titles(v) for k, v in props.items()}
+        return out
+    if isinstance(node, list):
+        return [_strip_titles(v) for v in node]
+    return node
+
+
+@dataclass
+class ToolOutcome:
+    tool_use_id: str
+    name: str
+    content: list
+    is_error: bool = False
+    source: str = "live"
+    capability: str | None = None
+    permission: str | None = None
+    operation_id: str | None = None
+    undo: bool = False
+    offloaded: str | None = None
+    images: list = field(default_factory=list)
+    summary: str = ""
+    latency_ms: int = 0
+    result: object = None
+    #: A revision guard this call moved: `{"scope", "before", "after"}` (`ToolBackend.revision_guard`).
+    advanced: dict | None = None
+
+    def block(self) -> dict:
+        block = {"type": "tool_result", "tool_use_id": self.tool_use_id, "content": self.content}
+        if self.is_error:
+            block["is_error"] = True
+        return block
+
+
+def error_outcome(tool_use_id: str, name: str, message: str, **fields) -> ToolOutcome:
+    return ToolOutcome(tool_use_id, name, [text_block(message)], is_error=True, summary=message, **fields)
+
+
+class ToolAdapter:
+    """The tools of one conversation. Thread-safe: sub-agents share it.
+
+    `offload_root` is where large results are stored (None: nothing is
+    offloaded, and a large result is only bounded). `descriptions` are the
+    product's words for its own local tools (`ChatProfile.tool_descriptions`)."""
+
+    def __init__(self, backend, *, policy, catalog: list | None = None, loaded: list | None = None,
+                 cache=None, viewer: bool = False, offload_tokens: int = 4000, offload_root=None,
+                 descriptions: dict | None = None):
+        self.backend = backend
+        self.policy = policy
+        self.catalog = list(catalog) if catalog is not None else build_catalog(backend, policy, viewer=viewer)
+        self.by_tool = {e["tool"]: e for e in self.catalog}
+        self.cache = cache
+        self.offload_tokens = offload_tokens
+        self.offload_root = offload_root
+        self.viewer = viewer
+        self.max_result_chars = int(getattr(backend, "max_result_chars", None) or serialize.MAX_RESULT_CHARS)
+        self.local = _local_definitions(descriptions)
+        self._loaded: list[dict] = []
+        self._lock = threading.Lock()
+        for name in loaded or ():
+            self._append(name)
+
+    # -- what the model is sent ---------------------------------------------------
+
+    @property
+    def loaded(self) -> list:
+        with self._lock:
+            return [d["name"] for d in self._loaded]
+
+    def definitions(self) -> list:
+        """The local tools, sorted: the same array for the whole conversation."""
+        return list(self.local)
+
+    def loaded_definitions(self) -> list:
+        with self._lock:
+            return list(self._loaded)
+
+    def catalog_text(self) -> str:
+        return catalog_text(self.catalog)
+
+    def _append(self, name: str) -> str:
+        if name in LOCAL_NAMES:
+            return "local"
+        if name not in self.by_tool:
+            return "unknown"
+        if any(d["name"] == name for d in self._loaded):
+            return "already"
+        self._loaded.append(definition_for(self.backend, name))
+        return "loaded"
+
+    def _definition(self, name: str) -> dict | None:
+        return next((d for d in self._loaded if d["name"] == name), None)
+
+    def load(self, names) -> dict:
+        """The definitions asked for, in the result. One already loaded is given
+        again: compaction may have summarised away the turn that first showed it."""
+        tools, unknown, local = [], [], []
+        with self._lock:
+            for name in dict.fromkeys(str(n) for n in (names or [])):
+                state = self._append(name)
+                if state == "unknown":
+                    unknown.append(name)
+                elif state == "local":
+                    local.append(name)
+                else:
+                    tools.append(self._definition(name))
+        result: dict = {"tools": tools, "call_with": CALL_TOOL}
+        if local:
+            result["local"] = local
+            result["hint"] = "local tools are already in your tools list; call them directly"
+        if unknown:
+            result["unknown"] = unknown
+            result["hint"] = "only names in the tool catalog can be loaded"
+        return result
+
+    @staticmethod
+    def resolve(name: str, arguments: dict) -> tuple[str, dict]:
+        """The tool a call really runs: `call_tool`'s target, or the call itself."""
+        if name != CALL_TOOL:
+            return name, dict(arguments or {})
+        inner = (arguments or {}).get("arguments")
+        if isinstance(inner, str):              # some models send the object as a JSON string
+            try:
+                inner = json.loads(inner) if inner.strip() else {}
+            except ValueError:
+                pass
+        return str((arguments or {}).get("name") or ""), inner if isinstance(inner, dict) else {}
+
+    # -- running a call -----------------------------------------------------------------
+
+    def describe(self, tool: str, arguments: dict | None = None) -> dict | None:
+        """`{"tool", "capability", "permission", "purpose"}` for a catalog tool and
+        these arguments (the permission is the backend's for this call), or None."""
+        entry = self.by_tool.get(tool)
+        if entry is None:
+            return None
+        return {"tool": tool, "capability": entry["capability"],
+                "permission": self.backend.permission(tool, dict(arguments or {})),
+                "purpose": self.backend.purpose(tool) or entry.get("purpose") or ""}
+
+    def needs_approval(self, tool: str, arguments: dict | None = None) -> bool:
+        if tool not in self.by_tool:
+            return False
+        return self.backend.permission(tool, dict(arguments or {})) in NEEDS_APPROVAL
+
+    def execute(self, tool_use_id: str, name: str, arguments: dict, *, policy=None,
+                allowed: set | None = None, approved: bool = False) -> ToolOutcome:
+        """Run one call. `approved`: the person approved this very call
+        (`ApprovalGate`), and `policy` already carries the flag it needs."""
+        started = time.monotonic()
+        arguments = dict(arguments or {})
+        if name == CALL_TOOL:
+            target, inner = self.resolve(name, arguments)
+            if not target or target == CALL_TOOL:
+                return error_outcome(tool_use_id, name, "call_tool needs the name of a catalog tool.",
+                                     source="local")
+            return self.execute(tool_use_id, target, inner, policy=policy, allowed=allowed, approved=approved)
+        if name in LOCAL_NAMES:
+            outcome = self._local(tool_use_id, name, arguments)
+        elif name not in self.by_tool:
+            outcome = error_outcome(tool_use_id, name, f"{name!r} is not a tool in this conversation's "
+                                    "catalog.", source="local")
+        elif allowed is not None and name not in allowed:
+            outcome = error_outcome(tool_use_id, name, f"{name} is not one of the tools this sub-agent "
+                                    "was given.", source="local")
+        else:
+            with self._lock:
+                shown = self._append(name) == "already"
+            outcome = self._backend(tool_use_id, name, arguments, policy or self.policy, approved)
+            if outcome.is_error and not shown:
+                # Called before load_tool showed its schema: show it now.
+                definition = self._definition(name)
+                outcome.content = outcome.content + [text_block("Definition: " + canonical(definition))]
+        outcome.latency_ms = int((time.monotonic() - started) * 1000)
+        return outcome
+
+    def _local(self, tool_use_id: str, name: str, arguments: dict) -> ToolOutcome:
+        try:
+            if name == LOAD_TOOL:
+                result = self.load(arguments.get("names") or ([arguments["name"]] if arguments.get("name")
+                                                              else []))
+            elif name == LIST_SKILLS:
+                result = {"skills": [{k: s.get(k) for k in ("name", "title", "when")}
+                                     for s in self.backend.skills()]}
+            elif name == READ_SKILL:
+                result = {"name": arguments.get("name"),
+                          "text": self.backend.read_skill(str(arguments.get("name")))}
+            elif name == SERVER_INFO:
+                result = self.backend.server_info(self.policy, tools=len(self.catalog), viewer=self.viewer)
+            elif name == READ_ARTIFACT:
+                if self.offload_root is None:
+                    raise KeyError("nothing is offloaded in this conversation")
+                result = offloading.read_artifact(arguments.get("artifact_id", ""), start=arguments.get("start"),
+                                                  end=arguments.get("end"), query=arguments.get("query"),
+                                                  root=self.offload_root)
+            else:
+                return error_outcome(tool_use_id, name, f"{name} is handled by the conversation, not here.",
+                                     source="local")
+        except KeyError as exc:
+            return error_outcome(tool_use_id, name, str(exc).strip("'\""), source="local")
+        return self.wrap(tool_use_id, name, result, source="local")
+
+    def wrap(self, tool_use_id: str, name: str, result, *, source: str = "local", **fields) -> ToolOutcome:
+        """A successful result as a tool_result: bounded text, offloaded when large."""
+        data = result if isinstance(result, str) else self.backend.serialize(result)
+        text = data if isinstance(data, str) else serialize.dumps(data)
+        stub = None
+        if self.offload_root is not None and offloading.tokens(text) > self.offload_tokens:
+            stub = offloading.offload(data, self.offload_tokens, root=self.offload_root)
+        if stub is not None:
+            text = canonical(stub)
+        elif not isinstance(data, str):
+            text = serialize.bound(data, self.max_result_chars)
+        return ToolOutcome(tool_use_id, name, [text_block(text)], source=source,
+                           offloaded=stub["artifact_id"] if stub else None,
+                           summary=_summary(result), result=result, **fields)
+
+    def _backend(self, tool_use_id: str, name: str, arguments: dict, policy, approved: bool) -> ToolOutcome:
+        entry = self.by_tool[name]
+        permission = self.backend.permission(name, arguments)
+
+        def call():
+            return self.backend.invoke(name, arguments, policy=policy, approved=approved)
+
+        if self.cache is not None and not approved and self.backend.cacheable(name, arguments):
+            outcome, source = self.cache.get_or_call(entry["capability"], arguments,
+                                                     self.backend.revision_token(name, arguments), call)
+        else:
+            outcome, source = call(), "live"
+        fields = {"capability": entry["capability"], "permission": permission}
+        if not outcome.get("ok"):
+            error = outcome.get("error") or {}
+            text = serialize.bound({"error": error, "operation_id": outcome.get("operation_id")},
+                                   self.max_result_chars)
+            return ToolOutcome(tool_use_id, name, [text_block(text)], is_error=True, source=source,
+                               summary=f"{error.get('code', 'error')}: {error.get('message', '')}"[:300],
+                               result={"error": error}, **fields)
+        result = outcome.get("result")
+        if isinstance(result, dict):
+            result = dict(result)                 # a cached answer is never mutated
+        result, images = self.backend.split_images(result)
+        op_id = None
+        undo = False
+        if permission != "read":
+            op_id = outcome.get("operation_id")
+            undo = bool(outcome.get("undo"))
+        wrapped = self.wrap(tool_use_id, name, result, source=source, operation_id=op_id, undo=undo,
+                            advanced=outcome.get("advanced") or None, **fields)
+        if images:
+            shown = images[:MAX_RESULT_IMAGES]
+            wrapped.content = [image_block(data, fmt) for data, fmt in shown] + wrapped.content
+            wrapped.images = shown
+        return wrapped
+
+
+def _summary(result) -> str:
+    if isinstance(result, str):
+        return result[:200]
+    if isinstance(result, dict):
+        keys = [k for k in result if not str(k).startswith("_")][:6]
+        return "{" + ", ".join(keys) + ("" if len(result) <= 6 else ", ...") + "}"
+    if isinstance(result, list):
+        return f"[{len(result)} items]"
+    return str(result)[:200]