@octocodeai/freellama-mcp-server 0.1.0 → 0.5.0

package/adapters/bash_agent.py

@@ -8,9 +8,9 @@ variable under test is the tool surface: this agent has no structured tool schem
 
 from __future__ import annotations
 
+from contextlib import ExitStack
 import json
 import os
-import re
 import subprocess
 import time
 from pathlib import Path
@@ -25,50 +25,21 @@ from agent_context import (
     REPEAT_NOTICE,
     ObservationStore,
     call_signature,
-    paginate,
-    page_footer,
     parse_json_action,
     write_failure_result,
 )
-from agent_transport import chat_request, request_headers, unwrap_chat_response
+import shell_sandbox
+from shell_sandbox import ReadOnlyShell
+from agent_transport import chat_request, request_headers, unwrap_chat_response, PromptCacheUsage, retryable_chat_error, resolve_model_identity, chat_error_details
 
 # Nothing is clipped any more. `calls[].result` is written to result.json on disk and read by the
 # MCP layer — it never enters the model's context, so there was never a reason to shorten it. What
 # the MODEL sees is paginated instead: one page plus an exact instruction for fetching the next.
 # See the pagination section of agent_context.py for why clipping was data loss, not economy.
 
-DENYLIST = re.compile(
-    r"\bsudo\b|\brm\s+-rf\s+/(?!\S)|:\(\)\s*\{.*:\|:.*\}|\bcurl\b|\bwget\b|\bnc\b|\bssh\b|>\s*/dev/(sd|nvme|disk)",
-    re.IGNORECASE,
-)
-
-# Home and well-known absolute prefixes. A relative `grep /pattern/` is not a filesystem path;
-# `/etc/passwd` is. `..` as a path component walks out of cwd=workspace.
-_HOME_ESCAPE = re.compile(r"(?:^|[\s=\"'])(?:~(?:/|$)|\$HOME\b|\$\{HOME\})")
-_ABS_PATH = re.compile(r"(?:^|[\s=\"'])(/(?:[^\s\"']+))")
-_DOTDOT_PATH = re.compile(r"(?:^|[\s=\"'/])\.\.(?:/|[\s\"']|$)")
-_FS_ABS_PREFIX = re.compile(
-    r"^/(?:etc|usr|home|Users|var|tmp|private|opt|root|System|Library|bin|sbin|dev|Applications|Volumes)(?:/|$)"
-)
-
-
-def assert_command_confined(root: Path, command_text: str) -> None:
-    """Reject commands that read outside the workspace. The MCP allowlist only constrains
-    the workspace *root*; without this, `cat /etc/hosts` from cwd=root succeeds."""
-    if _HOME_ESCAPE.search(command_text):
-        raise ValueError("command blocked: home-directory path is outside the workspace")
-    if _DOTDOT_PATH.search(command_text):
-        raise ValueError("command blocked: '..' walks outside the workspace")
-    root = root.resolve()
-    for match in _ABS_PATH.finditer(command_text):
-        raw = match.group(1)
-        candidate = Path(raw)
-        looks_like_fs = _FS_ABS_PREFIX.match(raw) is not None or candidate.exists()
-        if not looks_like_fs:
-            continue
-        resolved = candidate.resolve()
-        if resolved != root and root not in resolved.parents:
-            raise ValueError(f"command blocked: path escapes workspace: {raw}")
+# Validation, restricted bash, a scrubbed environment and (where the host allows) an OS sandbox
+# live in shell_sandbox; see its module docstring for why the old regex denylist was not enough.
+assert_command_confined = shell_sandbox.assert_command_confined
 
 
 def request_json(url: str, payload: dict[str, Any], timeout_seconds: float) -> dict[str, Any]:
@@ -96,28 +67,15 @@ def parse_action(content: str) -> dict[str, Any]:
     return value
 
 
-def run_shell(root: Path, command_text: str, timeout_seconds: float) -> str:
-    if not command_text.strip():
-        raise ValueError("empty shell command")
-    if DENYLIST.search(command_text):
-        raise ValueError("command blocked by safety denylist")
-    assert_command_confined(root, command_text)
-    result = subprocess.run(
-        ["/bin/bash", "-c", command_text],
-        cwd=root,
-        text=True,
-        capture_output=True,
-        timeout=timeout_seconds,
-        check=False,
-    )
-    output = (result.stdout or "") + (result.stderr or "")
-    if not output.strip():
-        output = f"(no output, exit code {result.returncode})"
-    return output
+def run_shell(root: Path, command_text: str, timeout_seconds: float, shell: ReadOnlyShell | None = None) -> str:
+    if shell is not None:
+        return shell.run(command_text, timeout_seconds)
+    with ReadOnlyShell(root) as scoped:
+        return scoped.run(command_text, timeout_seconds)
 
 
 def system_prompt() -> str:
-    return """You are a local coding agent in an isolated benchmark workspace containing a pinned repository, rooted at the current directory. You solve tasks using ONLY raw POSIX shell commands — no editors, no special tools, no network access. Return exactly one JSON object per turn:
+    return """You are a local code-research agent in a read-only workspace rooted at the current directory. Use raw POSIX shell commands without editors, special tools, or network access. Return exactly one JSON object per turn:
 
 {"action":"shell","command":"one shell command, e.g. grep -n \\"class Group\\" click/src/click/core.py"}
 {"action":"page","step":2,"page":2}
@@ -126,33 +84,35 @@ def system_prompt() -> str:
 These are the complete action schemas. Use only `shell`, `page`, or `finish`; every shown field is
 required with the shown type. An invalid shape is rejected and costs one bounded repair turn.
 
-Long output is PAGINATED, never truncated: you are shown page 1 and told the total. Nothing is
-discarded, so "not found" is only a real answer once you have seen every page you need. Send the
-page action to read another page of a previous step — it re-reads stored output and does not re-run
-the command, so it is cheaper than repeating the search.
+Full command output is stored in pages; you see page 1 and the total. Context fitting can shorten
+an observation in the conversation. Request its stored page to recover the evidence without
+re-running the command. Claim "not found" only after checking the relevant search scope and pages.
 
-Use standard Unix utilities: ls, find, cat, grep, sed, awk, head, tail, wc, tree (if present). Chain
-with pipes if needed, but keep each turn to a single shell invocation. Never edit files. Be decisive:
-most tasks need 2-6 commands. Call finish as soon as the requested facts are established.
+The shell is READ-ONLY and restricted. Available tools: ls, find, grep, rg, cat, head, tail, wc,
+sort, uniq, cut, tr, nl, sed (bounded read-only inline programs), jq, diff, xargs
+(only echo, printf, true, or false targets), tree, file, stat, and read-only git
+(log, show, grep, ls-files, diff, blame, status). There is no awk, python, network, output
+redirection, script-file loading, recursive symlink following, paths outside the workspace,
+$(...) substitution, $VARIABLES, or loops: write paths and patterns literally and
+chain tools with pipes, one pipeline per turn. A refused command costs a turn, so follow these
+rules. Be decisive: most tasks need 2-6 commands. Call finish as soon as the requested facts are
+established.
 
 SCOPE YOUR SEARCHES. A real workspace holds far more than its source, and an unscoped grep drowns
 the answer in vendored and generated files. Always exclude them:
   grep -rn "PATTERN" . --exclude-dir={node_modules,target,.venv,venv,dist,build,.git,vendor,__pycache__,.octocode,site-packages}
-Matches under fixtures/, test/fixtures/, mocks/ or examples/ are usually scaffolding, NOT the real
-implementation — a mock named like the thing you are looking for is a trap, not an answer. Prefer
-src/, packages/*/src/, lib/ and the repo root, and name the file you took the answer from.
+For implementation questions, prefer src/, packages/*/src/, lib/ and the repo root before fixtures,
+mocks, or examples. If the question targets tests or examples, inspect those files. Name the file
+that supplies the answer.
 If a search returns nothing, widen the pattern before concluding the thing does not exist: absence
 of a grep hit is weak evidence, and "not found" is only a real answer once you have looked in the
 source directories.
-ASKED FOR A DEFAULT? Find where it is DECLARED, not where it appears. A value like a port or a
-timeout is scattered across tests, docs and examples that merely pass it; those are occurrences, not
-the default. The declaration is an attribute or initializer — `default_value = `, `unwrap_or(`,
-`const `, `static `, a settings schema, a clap/argparse arg. Grep for the declaration form, and if
-you can only find occurrences, say which file you took it from and that you did not find a
-declaration. Test files (`tests/`, `*_test.*`, `*_contract.*`) define nothing — they consume it."""
+For a production default, find its declaration before relying on test occurrences. Declarations look like
+`default=`, `unwrap_or(`, `const `, `static `, or a settings schema initializer.
+For a test-specific default or fixture, inspect its test declaration."""
 
 
-def main() -> int:
+def _main(resources: ExitStack) -> int:
     model = os.environ.get("FREELLAMA_TARGET_MODEL") or os.environ["FREELLAMA_BENCH_MODEL"]
     workspace = Path(os.environ["FREELLAMA_BENCH_WORKSPACE"]).resolve()
     prompt = Path(os.environ["FREELLAMA_BENCH_PROMPT"]).read_text(encoding="utf-8")
@@ -174,15 +134,22 @@ def main() -> int:
     ]
     calls: list[dict[str, Any]] = []
     usage = {"input_tokens": 0, "output_tokens": 0, "cache_read_tokens": None, "cache_write_tokens": None}
+    cache_usage = PromptCacheUsage()
     metrics = {"load_ms": 0.0, "prompt_eval_ms": 0.0, "eval_ms": 0.0}
     execution_receipts: list[dict[str, Any]] = []
     answer = ""
     failure: str | None = None
+    transport_error: dict[str, Any] | None = None
     calibration_dir = os.environ.get("FREELLAMA_AGENT_TOKEN_CALIBRATION_DIR", "").strip()
+    calibration_model_identity = (
+        resolve_model_identity(managed_endpoint or endpoint, model, messages[0]["content"])
+        if calibration_dir else {"verified": False, "scope": "persistence_disabled", "identity": ""}
+    )
     context_manager = AgentContextManager(
         runtime,
         model=model,
-        calibration_dir=Path(calibration_dir) if calibration_dir else None,
+        calibration_identity=calibration_model_identity["identity"],
+        calibration_dir=Path(calibration_dir) if calibration_dir and calibration_model_identity["verified"] else None,
     )
     try:
         messages = context_manager.fit(messages)
@@ -199,9 +166,8 @@ def main() -> int:
     }
 
     def call_model() -> dict[str, Any]:
-        # The proxy already retries 500/502/504 (packages/rust-core/src/proxy.rs); this loop is a
-        # second, slower layer for outages that outlast the proxy's own retry budget — losing a
-        # whole multi-turn conversation to one bad turn would be wasteful.
+        # Retry explicit overload/connection refusals only. Replaying a timeout or an uncertain
+        # transport failure can overlap a generation that is still consuming the runner.
         last_error: Exception | None = None
         for attempt in range(runtime.retry_attempts):
             try:
@@ -223,12 +189,16 @@ def main() -> int:
                 )
                 break
             except (HTTPError, URLError, TimeoutError) as error:
+                if not retryable_chat_error(error):
+                    raise
                 last_error = error
                 if attempt + 1 < runtime.retry_attempts:
                     time.sleep(runtime.retry_backoff_seconds)
         else:
             raise last_error  # type: ignore[misc]
         usage["input_tokens"] += int(response.get("prompt_eval_count", 0))
+        cache_usage.observe(response)
+        usage["cache_read_tokens"] = cache_usage.tokens
         usage["output_tokens"] += int(response.get("eval_count", 0))
         metrics["load_ms"] += float(response.get("load_duration", 0)) / 1_000_000
         metrics["prompt_eval_ms"] += float(response.get("prompt_eval_duration", 0)) / 1_000_000
@@ -246,7 +216,8 @@ def main() -> int:
             return False
 
     seen_calls: dict[str, int] = {}
-    observations = ObservationStore(runtime.context.observation_page_chars)
+    observations = resources.enter_context(ObservationStore(runtime.context.observation_page_chars))
+    shell = resources.enter_context(ReadOnlyShell(workspace))
     parse_failures = 0
     for _ in range(runtime.max_turns):
         # Transport failures are terminal (call_model already retried them). A *parse* failure is
@@ -255,7 +226,8 @@ def main() -> int:
         try:
             response = call_model()
         except (HTTPError, URLError, TimeoutError) as error:
-            failure = f"agent response failed: {type(error).__name__}: {error}"
+            diagnostic, transport_error = chat_error_details(error)
+            failure = f"agent response failed: {diagnostic}"
             break
         raw = str(response.get("message", {}).get("content", ""))
         try:
@@ -280,9 +252,8 @@ def main() -> int:
                 want_page = int(action.get("page", 1))
             except (TypeError, ValueError):
                 want_step, want_page = 0, 1
-            body, footer = observations.view(want_step, want_page)
             messages.append({"role": "assistant", "content": json.dumps(action, ensure_ascii=False)})
-            messages.append({"role": "user", "content": f"Observation (step {want_step}):\n{body}{footer}"})
+            messages.append({"role": "user", "content": observations.message(want_step, want_page)})
             if not refit():
                 break
             continue
@@ -299,7 +270,7 @@ def main() -> int:
             status = "repeat"
         else:
             try:
-                observation = run_shell(workspace, command_text, runtime.tool_timeout_seconds)
+                observation = run_shell(workspace, command_text, runtime.tool_timeout_seconds, shell)
                 status = "ok"
             except (OSError, ValueError, subprocess.TimeoutExpired) as error:
                 observation = f"tool error: {type(error).__name__}: {error}"
@@ -311,17 +282,13 @@ def main() -> int:
             "arguments": {"command": command_text},
             "status": status,
             "duration_ms": round((time.perf_counter() - started) * 1000, 3),
-            "result": observation,
         })
         messages.append({"role": "assistant", "content": json.dumps(action, ensure_ascii=False)})
         remaining = runtime.max_turns - len(calls)
         step = len(calls)
-        observations.put(step, observation)
-        body, shown_page, total_pages = paginate(
-            observation, page_size=runtime.context.observation_page_chars
-        )
-        footer = page_footer(step, shown_page, total_pages, len(observation))
-        messages.append({"role": "user", "content": f"Observation (step {step}):\n{body}{footer}\n\nCommands remaining: {remaining}. Finish now if the task is answerable; do not repeat prior commands."})
+        observations.put(step, observation, metadata={"action": "shell", "status": status, "source": command_text})
+        del observation
+        messages.append({"role": "user", "content": observations.message(step) + f"\n\nCommands remaining: {remaining}. Finish now if the task is answerable; do not repeat prior commands."})
         if not refit():
             break
     else:
@@ -334,7 +301,8 @@ def main() -> int:
                     raise ValueError("forced final response was not finish")
                 answer = str(final_action.get("answer", "")).strip()
             except (HTTPError, URLError, TimeoutError, ValueError, json.JSONDecodeError) as error:
-                failure = f"agent exceeded {runtime.max_turns} turns and finalization failed: {type(error).__name__}: {error}"
+                diagnostic, transport_error = chat_error_details(error)
+                failure = f"agent exceeded {runtime.max_turns} turns and finalization failed: {diagnostic}"
 
     if not answer:
         answer = failure or "agent stopped without a final answer"
@@ -345,6 +313,7 @@ def main() -> int:
         "provider_metrics": metrics,
         "model_metadata": {
             "adapter": "bash_shell_agent_v1",
+            "sandbox": shell.kind,
             "temperature": chat_options["temperature"],
             "seed": chat_options["seed"],
             "num_ctx": chat_options["num_ctx"],
@@ -357,14 +326,20 @@ def main() -> int:
             "execution_preference": execution_preference,
             "min_placement_evidence": min_placement_evidence,
             "execution_receipts": execution_receipts,
-            "cache_token_metrics": "not_reported_by_ollama",
+            **({"transport_error": transport_error} if transport_error else {}),
+            "cache_token_metrics": cache_usage.metadata(),
+            "calibration_model_identity": calibration_model_identity,
         },
     }
-    result_path.parent.mkdir(parents=True, exist_ok=True)
-    result_path.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    observations.write_result(result_path, result)
     print(answer)
     return 1 if failure else 0
 
 
+def main() -> int:
+    with ExitStack() as resources:
+        return _main(resources)
+
+
 if __name__ == "__main__":
     raise SystemExit(main())

package/adapters/octocode_agent.py

@@ -9,6 +9,7 @@ mirrors verbatim.
 
 from __future__ import annotations
 
+from contextlib import ExitStack
 import json
 import os
 import subprocess
@@ -25,12 +26,10 @@ from agent_context import (
     REPEAT_NOTICE,
     ObservationStore,
     call_signature,
-    paginate,
-    page_footer,
     parse_json_action,
     write_failure_result,
 )
-from agent_transport import chat_request, request_headers, unwrap_chat_response
+from agent_transport import chat_request, request_headers, unwrap_chat_response, PromptCacheUsage, retryable_chat_error, resolve_model_identity, chat_error_details
 
 OCTOCODE_TOOLS = {"localViewStructure", "localFindFiles", "localSearchCode", "localGetFileContent", "lspGetSemantics"}
 PATH_KEYS = ("path", "uri")
@@ -78,6 +77,12 @@ def parse_action(content: str) -> dict[str, Any]:
     return value
 
 
+# Pinned: an unpinned `npx octocode` downloads whatever is latest at call time (a supply-chain
+# risk for a tool that reads the user's workspace) and the first download can exceed the tool
+# timeout. Override deliberately with FREELLAMA_AGENT_OCTOCODE_PACKAGE.
+OCTOCODE_PACKAGE = os.environ.get("FREELLAMA_AGENT_OCTOCODE_PACKAGE", "octocode@19.1.0")
+
+
 def run_octocode(
     root: Path,
     tool_name: str,
@@ -90,7 +95,7 @@ def run_octocode(
     for key in PATH_KEYS:
         if key in resolved and isinstance(resolved[key], str):
             resolved[key] = str(safe_resolve(root, resolved[key]))
-    command = ["npx", "octocode", "tools", tool_name, "--queries", json.dumps(resolved), "--compact"]
+    command = ["npx", "--yes", OCTOCODE_PACKAGE, "tools", tool_name, "--queries", json.dumps(resolved), "--compact"]
     result = subprocess.run(
         command,
         cwd=root,
@@ -106,46 +111,41 @@ def run_octocode(
 
 
 def system_prompt(workspace: str) -> str:
-    return f"""You are a local coding agent in an isolated benchmark workspace at {workspace}. You may not read or search files directly — you can only call the `octocode` local tools below. Return exactly one JSON object per turn.
+    return f"""You are a local code-research agent in a read-only workspace at {workspace}. Read or search files only through the `octocode` local tools below. Return exactly one JSON object per turn.
 
 Tools (call as {{"action":"octocode","tool":"<name>","queries":{{...}}}}):
 
 localViewStructure - browse a directory tree, no content loaded; cheapest first orientation step.
-  queries: path (string, required, absolute), maxDepth (int), recursive (bool), filesOnly (bool),
+  path (string, required, absolute), maxDepth (int), recursive (bool), filesOnly (bool),
   directoriesOnly (bool), pattern (glob/substring filter).
 
 localFindFiles - find files/dirs by name, glob, regex, or type; returns paths only, not content.
-  queries: path (string, required, absolute), names (array of globs), pathPattern (glob over full
-  path), regex (basename regex), entryType ("f"|"d"), excludeDir (array, e.g. ["node_modules",".git"]).
+  path (string, required, absolute), names (array of globs), pathPattern (glob over full path),
+  regex (basename regex), entryType ("f"|"d"), excludeDir (array, e.g. ["node_modules",".git"]).
 
 localSearchCode - search file contents for text/regex; returns file+line matches. Your main tool.
-  queries: path (string, required, absolute), keywords (string; literal or regex search term),
+  path (string, required, absolute), keywords (string; literal or regex search term),
   mode ("paginated"|"discovery"|"detailed"), include/exclude (glob arrays),
   caseInsensitive (bool), maxFiles (int).
   Do NOT pass mode "structural" with keywords — structural (AST) search takes `pattern`/`rule`
   instead and hard-errors on keywords, costing you a turn for nothing.
 
 localGetFileContent - read one file or a line range/matched slice of it.
-  queries: path (string, required, absolute), fullContent (bool; small files only), startLine +
+  path (string, required, absolute), fullContent (bool; small files only), startLine +
   endLine (ints, both required together), matchString (anchor text/regex), minify
   ("none"|"standard"|"symbols" — "symbols" gives a cheap outline first).
 
 lspGetSemantics - LSP semantic queries: definitions, references, callers/callees, symbol outline.
-  queries: uri (string, required, absolute path), type ("definition"|"references"|"callers"|
-  "callees"|"documentSymbols"|"hover"|...), symbolName (exact identifier), lineHint (int; get this
-  from a prior search/documentSymbols call, never guess it).
-  An EMPTY result is ambiguous, and it will not tell you which case you hit: it reports
-  serverAvailable=true whether the language server is still indexing the project or genuinely
-  cannot analyse the file. Measured here on the same files: a cold server returned
-  totalSymbols=0 for Rust, and once warm the identical call returned 35. Python returned 139-430,
-  TypeScript 45. So totalSymbols=0 means "ask again or search instead", NOT "no such symbol" and
-  NOT "unsupported". Do not spend more than one retry on it — prefer localSearchCode, which needs
-  no index and cannot be cold.
+  uri (string, required, absolute path), type ("definition"|"references"|"callers"|
+  "callees"|"documentSymbols"|"hover"), symbolName (exact name), lineHint (int from a prior
+  search result — never guess it).
+  An empty result is ambiguous: indexing or unavailable analysis can produce no symbols.
+  Retry once or use localSearchCode; an empty LSP result alone does not prove absence.
 
 Read another page of an earlier step: {{"action":"page","step":2,"page":2}}
-Long output is PAGINATED, never truncated — you see page 1 and the total, and nothing is discarded.
-"Not found" is only a real answer once you have seen every page you need. Paging re-reads stored
-output and does NOT re-run the tool, so it is cheaper than repeating a search.
+Full tool output is stored in pages; you see page 1 and the total. Context fitting can shorten
+an observation in the conversation. Request its stored page to recover the evidence without
+re-running the tool. Claim "not found" only after checking the relevant search scope and pages.
 
 Finish with: {{"action":"finish","answer":"concise final answer with repository-relative evidence"}}
 
@@ -155,24 +155,21 @@ is rejected and costs one bounded repair turn.
 
 SCOPE YOUR SEARCHES. Pass excludeDir/exclude on every search in a real workspace —
 ["node_modules","target",".venv","dist","build",".git","vendor","__pycache__",".octocode"] — or
-vendored and generated files will bury the answer. Matches under fixtures/, mocks/ or examples/ are
-scaffolding, NOT the real implementation. Prefer src/, packages/*/src/ and lib/, and name the file
-you took the answer from. Absence of a match is weak evidence: widen the pattern before concluding
+vendored and generated files will bury the answer. For implementation questions, prefer src/,
+packages/*/src/ and lib/ before fixtures, mocks, or examples. If the question targets tests or examples,
+inspect those files. Name the file that supplies the answer. Absence of a match is weak evidence: widen the pattern before concluding
 something does not exist.
-ASKED FOR A DEFAULT? Find where it is DECLARED, not where it appears. A value like a port or a
-timeout is scattered across tests, docs and examples that merely pass it; those are occurrences, not
-the default. The declaration is an attribute or initializer — `default_value = `, `unwrap_or(`,
-`const `, `static `, a settings schema, a clap/argparse arg. Grep for the declaration form, and if
-you can only find occurrences, say which file you took it from and that you did not find a
-declaration. Test files (`tests/`, `*_test.*`, `*_contract.*`) define nothing — they consume it.
+For a production default, find its declaration before relying on test occurrences. Declarations look like
+`default=`, `unwrap_or(`, `const `, `static `, or a settings schema initializer.
+For a test-specific default or fixture, inspect its test declaration.
 
 All paths you pass must resolve inside the workspace; relative paths are resolved against the
-workspace root automatically. Orient cheap (localViewStructure/documentSymbols) before reading in
+workspace root automatically. Orient cheap (localViewStructure) before reading in
 full. Be decisive: most tasks need 2-6 tool calls. Never edit or write files — you only have
 read-only tools. Call finish as soon as the requested facts are established."""
 
 
-def main() -> int:
+def _main(resources: ExitStack) -> int:
     model = os.environ.get("FREELLAMA_TARGET_MODEL") or os.environ["FREELLAMA_BENCH_MODEL"]
     workspace = Path(os.environ["FREELLAMA_BENCH_WORKSPACE"]).resolve()
     prompt = Path(os.environ["FREELLAMA_BENCH_PROMPT"]).read_text(encoding="utf-8")
@@ -194,15 +191,22 @@ def main() -> int:
     ]
     calls: list[dict[str, Any]] = []
     usage = {"input_tokens": 0, "output_tokens": 0, "cache_read_tokens": None, "cache_write_tokens": None}
+    cache_usage = PromptCacheUsage()
     metrics = {"load_ms": 0.0, "prompt_eval_ms": 0.0, "eval_ms": 0.0}
     execution_receipts: list[dict[str, Any]] = []
     answer = ""
     failure: str | None = None
+    transport_error: dict[str, Any] | None = None
     calibration_dir = os.environ.get("FREELLAMA_AGENT_TOKEN_CALIBRATION_DIR", "").strip()
+    calibration_model_identity = (
+        resolve_model_identity(managed_endpoint or endpoint, model, messages[0]["content"])
+        if calibration_dir else {"verified": False, "scope": "persistence_disabled", "identity": ""}
+    )
     context_manager = AgentContextManager(
         runtime,
         model=model,
-        calibration_dir=Path(calibration_dir) if calibration_dir else None,
+        calibration_identity=calibration_model_identity["identity"],
+        calibration_dir=Path(calibration_dir) if calibration_dir and calibration_model_identity["verified"] else None,
     )
     try:
         messages = context_manager.fit(messages)
@@ -219,9 +223,8 @@ def main() -> int:
     }
 
     def call_model() -> dict[str, Any]:
-        # The proxy already retries 500/502/504 (packages/rust-core/src/proxy.rs); this loop is a
-        # second, slower layer for outages that outlast the proxy's own retry budget — losing a
-        # whole multi-turn conversation to one bad turn would be wasteful.
+        # Retry explicit overload/connection refusals only. Replaying a timeout or an uncertain
+        # transport failure can overlap a generation that is still consuming the runner.
         last_error: Exception | None = None
         for attempt in range(runtime.retry_attempts):
             try:
@@ -243,12 +246,16 @@ def main() -> int:
                 )
                 break
             except (HTTPError, URLError, TimeoutError) as error:
+                if not retryable_chat_error(error):
+                    raise
                 last_error = error
                 if attempt + 1 < runtime.retry_attempts:
                     time.sleep(runtime.retry_backoff_seconds)
         else:
             raise last_error  # type: ignore[misc]
         usage["input_tokens"] += int(response.get("prompt_eval_count", 0))
+        cache_usage.observe(response)
+        usage["cache_read_tokens"] = cache_usage.tokens
         usage["output_tokens"] += int(response.get("eval_count", 0))
         metrics["load_ms"] += float(response.get("load_duration", 0)) / 1_000_000
         metrics["prompt_eval_ms"] += float(response.get("prompt_eval_duration", 0)) / 1_000_000
@@ -266,7 +273,7 @@ def main() -> int:
             return False
 
     seen_calls: dict[str, int] = {}
-    observations = ObservationStore(runtime.context.observation_page_chars)
+    observations = resources.enter_context(ObservationStore(runtime.context.observation_page_chars))
     parse_failures = 0
     for _ in range(runtime.max_turns):
         # Transport failures are terminal (call_model already retried them). A *parse* failure is
@@ -275,7 +282,8 @@ def main() -> int:
         try:
             response = call_model()
         except (HTTPError, URLError, TimeoutError) as error:
-            failure = f"agent response failed: {type(error).__name__}: {error}"
+            diagnostic, transport_error = chat_error_details(error)
+            failure = f"agent response failed: {diagnostic}"
             break
         raw = str(response.get("message", {}).get("content", ""))
         try:
@@ -300,9 +308,8 @@ def main() -> int:
                 want_page = int(action.get("page", 1))
             except (TypeError, ValueError):
                 want_step, want_page = 0, 1
-            body, footer = observations.view(want_step, want_page)
             messages.append({"role": "assistant", "content": json.dumps(action, ensure_ascii=False)})
-            messages.append({"role": "user", "content": f"Observation (step {want_step}):\n{body}{footer}"})
+            messages.append({"role": "user", "content": observations.message(want_step, want_page)})
             if not refit():
                 break
             continue
@@ -335,17 +342,13 @@ def main() -> int:
             "arguments": {"tool": tool_name, "queries": queries},
             "status": status,
             "duration_ms": round((time.perf_counter() - started) * 1000, 3),
-            "result": observation,
         })
         messages.append({"role": "assistant", "content": json.dumps(action, ensure_ascii=False)})
         remaining = runtime.max_turns - len(calls)
         step = len(calls)
-        observations.put(step, observation)
-        body, shown_page, total_pages = paginate(
-            observation, page_size=runtime.context.observation_page_chars
-        )
-        footer = page_footer(step, shown_page, total_pages, len(observation))
-        messages.append({"role": "user", "content": f"Observation (step {step}):\n{body}{footer}\n\nTool calls remaining: {remaining}. Finish now if the task is answerable; do not repeat prior calls."})
+        observations.put(step, observation, metadata={"action": tool_name, "status": status, "source": json.dumps(queries, ensure_ascii=False)})
+        del observation
+        messages.append({"role": "user", "content": observations.message(step) + f"\n\nTool calls remaining: {remaining}. Finish now if the task is answerable; do not repeat prior calls."})
         if not refit():
             break
     else:
@@ -358,7 +361,8 @@ def main() -> int:
                     raise ValueError("forced final response was not finish")
                 answer = str(final_action.get("answer", "")).strip()
             except (HTTPError, URLError, TimeoutError, ValueError, json.JSONDecodeError) as error:
-                failure = f"agent exceeded {runtime.max_turns} turns and finalization failed: {type(error).__name__}: {error}"
+                diagnostic, transport_error = chat_error_details(error)
+                failure = f"agent exceeded {runtime.max_turns} turns and finalization failed: {diagnostic}"
 
     if not answer:
         answer = failure or "agent stopped without a final answer"
@@ -381,14 +385,20 @@ def main() -> int:
             "execution_preference": execution_preference,
             "min_placement_evidence": min_placement_evidence,
             "execution_receipts": execution_receipts,
-            "cache_token_metrics": "not_reported_by_ollama",
+            **({"transport_error": transport_error} if transport_error else {}),
+            "cache_token_metrics": cache_usage.metadata(),
+            "calibration_model_identity": calibration_model_identity,
         },
     }
-    result_path.parent.mkdir(parents=True, exist_ok=True)
-    result_path.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    observations.write_result(result_path, result)
     print(answer)
     return 1 if failure else 0
 
 
+def main() -> int:
+    with ExitStack() as resources:
+        return _main(resources)
+
+
 if __name__ == "__main__":
     raise SystemExit(main())