@octocodeai/freellama-mcp-server 0.5.0 → 0.6.1

package/adapters/agent_context.py

@@ -1,850 +0,0 @@
-#!/usr/bin/env python3
-"""Context-window management shared by the research/benchmark adapters.
-
-Why this exists, concretely. Both adapters run at `num_ctx=8192` and append a full observation
-(up to 3000 characters) after every turn. At the benchmark's `max_turns=10` the conversation
-reaches roughly 9-10k tokens — past the window. Ollama does not error on that: it silently
-truncates from the **front** of the prompt, and the front is the system prompt. The agent loses
-its own tool schema and output contract mid-run, then returns prose instead of JSON, and the run
-is recorded as `model did not return a JSON action` — a parsing failure that reads like a model
-weakness but is really a context-management bug in the harness.
-
-Everything here is deterministic and dependency-free, because the adapters are copied verbatim
-into the published MCP package (`packages/mcp/scripts/bundle-adapters.mjs`) and must keep running
-with nothing but the standard library.
-"""
-
-from __future__ import annotations
-
-import json
-import hashlib
-import math
-import os
-import re
-import struct
-import tempfile
-import time
-from dataclasses import asdict, dataclass
-from pathlib import Path
-from typing import Any, Callable, Mapping
-
-# Ollama reports no token counts until after a call, so the first budget uses a configurable
-# approximation. Real prompt_eval_count values then raise the multiplier whenever this estimate
-# was optimistic; it never lowers itself from a sample.
-CHARS_PER_TOKEN = 4
-# Headroom held back from `num_ctx` on top of `num_predict`: chat templating, tool-call scaffolding
-# and the token estimate's own error all land inside the same window.
-SAFETY_MARGIN_TOKENS = 256
-# Base64 bytes are not text tokens. Multimodal templates turn each image into a bounded token
-# sequence; charging a conservative fixed amount avoids treating a 5MB JPEG as 1.25M text tokens.
-IMAGE_TOKEN_ESTIMATE = 1024
-# Observations kept verbatim. The two most recent are what the model is actually reasoning over;
-# older ones have usually already been distilled into the answer it is assembling.
-DEFAULT_KEEP_RECENT = 2
-# How much of a compacted observation survives as a breadcrumb, so the model still knows the call
-# happened and roughly what it returned rather than silently losing the step.
-COMPACT_PREVIEW_CHARS = 180
-# Emergency clipping keeps this fraction of the current payload on each pass. It is deliberately
-# iterative: rounding and per-message metadata make a one-shot subtraction unsafe.
-COMPACT_RETAIN_RATIO = 0.8
-CLIP_HEAD_RATIO = 2 / 3
-# Full observations are kept outside the prompt and served in line-aware pages of this size.
-OBSERVATION_PAGE_CHARS = 3000
-# Once an overflow requires changing old observations, reclaim modest headroom in the same pass.
-# This is a target after overflow, not an early trigger; already-fitting prefixes stay untouched.
-COMPACTION_TARGET_RATIO = 0.9
-COMPACT_MARKER = "[earlier observation compacted to save context"
-
-
-def _env_int(env: Mapping[str, str], name: str, default: int, *, minimum: int = 0) -> int:
-    raw = env.get(name)
-    if raw is None or raw == "":
-        return default
-    try:
-        value = int(raw)
-    except ValueError as error:
-        raise ValueError(f"{name} must be an integer, got {raw!r}") from error
-    if value < minimum:
-        raise ValueError(f"{name} must be >= {minimum}, got {value}")
-    return value
-
-
-def _env_float(env: Mapping[str, str], name: str, default: float, *, minimum: float = 0.0) -> float:
-    raw = env.get(name)
-    if raw is None or raw == "":
-        return default
-    try:
-        value = float(raw)
-    except ValueError as error:
-        raise ValueError(f"{name} must be a number, got {raw!r}") from error
-    if not math.isfinite(value) or value < minimum:
-        raise ValueError(f"{name} must be finite and >= {minimum}, got {raw!r}")
-    return value
-
-
-def _env_bool(env: Mapping[str, str], name: str, default: bool) -> bool:
-    raw = env.get(name)
-    if raw is None or raw == "":
-        return default
-    normalized = raw.strip().lower()
-    if normalized in {"1", "true", "yes", "on"}:
-        return True
-    if normalized in {"0", "false", "no", "off"}:
-        return False
-    raise ValueError(f"{name} must be true/false, got {raw!r}")
-
-
-@dataclass(frozen=True)
-class ContextPolicy:
-    """Validated context-management policy shared by every research adapter."""
-
-    chars_per_token: float = CHARS_PER_TOKEN
-    safety_margin_tokens: int = SAFETY_MARGIN_TOKENS
-    image_token_estimate: int = IMAGE_TOKEN_ESTIMATE
-    keep_recent: int = DEFAULT_KEEP_RECENT
-    compact_preview_chars: int = COMPACT_PREVIEW_CHARS
-    compact_retain_ratio: float = COMPACT_RETAIN_RATIO
-    clip_head_ratio: float = CLIP_HEAD_RATIO
-    observation_page_chars: int = OBSERVATION_PAGE_CHARS
-    pinned_overflow: str = "error"
-
-    def __post_init__(self) -> None:
-        if not math.isfinite(self.chars_per_token) or self.chars_per_token <= 0:
-            raise ValueError("chars_per_token must be finite and > 0")
-        if self.safety_margin_tokens < 0 or self.image_token_estimate < 0 or self.keep_recent < 0:
-            raise ValueError("context token estimates and keep_recent must be >= 0")
-        if self.compact_preview_chars <= 0 or self.observation_page_chars <= 0:
-            raise ValueError("preview and page sizes must be > 0")
-        if not 0 < self.compact_retain_ratio < 1:
-            raise ValueError("compact_retain_ratio must be between 0 and 1")
-        if not 0 < self.clip_head_ratio < 1:
-            raise ValueError("clip_head_ratio must be between 0 and 1")
-        if self.pinned_overflow not in {"error", "clip"}:
-            raise ValueError("pinned_overflow must be 'error' or 'clip'")
-
-    @classmethod
-    def from_env(cls, env: Mapping[str, str] | None = None) -> "ContextPolicy":
-        values = os.environ if env is None else env
-        pinned_overflow = values.get("FREELLAMA_AGENT_PINNED_OVERFLOW", "error").strip().lower()
-        return cls(
-            chars_per_token=_env_float(values, "FREELLAMA_AGENT_CHARS_PER_TOKEN", CHARS_PER_TOKEN, minimum=0.000001),
-            safety_margin_tokens=_env_int(values, "FREELLAMA_AGENT_SAFETY_MARGIN_TOKENS", SAFETY_MARGIN_TOKENS),
-            image_token_estimate=_env_int(values, "FREELLAMA_AGENT_IMAGE_TOKEN_ESTIMATE", IMAGE_TOKEN_ESTIMATE),
-            keep_recent=_env_int(values, "FREELLAMA_AGENT_KEEP_RECENT", DEFAULT_KEEP_RECENT),
-            compact_preview_chars=_env_int(values, "FREELLAMA_AGENT_COMPACT_PREVIEW_CHARS", COMPACT_PREVIEW_CHARS, minimum=1),
-            compact_retain_ratio=_env_float(values, "FREELLAMA_AGENT_COMPACT_RETAIN_RATIO", COMPACT_RETAIN_RATIO, minimum=0.000001),
-            clip_head_ratio=_env_float(values, "FREELLAMA_AGENT_CLIP_HEAD_RATIO", CLIP_HEAD_RATIO, minimum=0.000001),
-            observation_page_chars=_env_int(values, "FREELLAMA_AGENT_OBSERVATION_PAGE_CHARS", OBSERVATION_PAGE_CHARS, minimum=1),
-            pinned_overflow=pinned_overflow,
-        )
-
-    def metadata(self) -> dict[str, Any]:
-        return asdict(self)
-
-
-@dataclass(frozen=True)
-class AgentRuntimeConfig:
-    """Typed operational settings; safety confinement remains an invariant, not a knob."""
-
-    max_turns: int
-    num_ctx: int
-    num_predict: int
-    temperature: float
-    seed: int
-    request_timeout_seconds: float
-    retry_attempts: int
-    retry_backoff_seconds: float
-    tool_timeout_seconds: float
-    keep_alive: str
-    think: bool
-    max_parse_repairs: int
-    parse_repair_echo_chars: int
-    context: ContextPolicy
-
-    @classmethod
-    def from_env(
-        cls,
-        *,
-        default_tool_timeout_seconds: float,
-        env: Mapping[str, str] | None = None,
-    ) -> "AgentRuntimeConfig":
-        values = os.environ if env is None else env
-        context = ContextPolicy.from_env(values)
-        config = cls(
-            max_turns=_env_int(values, "FREELLAMA_AGENT_MAX_TURNS", 10, minimum=1),
-            num_ctx=_env_int(values, "FREELLAMA_AGENT_NUM_CTX", 8192, minimum=1),
-            num_predict=_env_int(values, "FREELLAMA_AGENT_NUM_PREDICT", 512, minimum=1),
-            temperature=_env_float(values, "FREELLAMA_AGENT_TEMPERATURE", 0.0),
-            seed=_env_int(values, "FREELLAMA_AGENT_SEED", 42),
-            request_timeout_seconds=_env_float(values, "FREELLAMA_AGENT_REQUEST_TIMEOUT_SECONDS", 600.0, minimum=0.001),
-            retry_attempts=_env_int(values, "FREELLAMA_AGENT_RETRY_ATTEMPTS", 2, minimum=1),
-            retry_backoff_seconds=_env_float(values, "FREELLAMA_AGENT_RETRY_BACKOFF_SECONDS", 5.0),
-            tool_timeout_seconds=_env_float(values, "FREELLAMA_AGENT_TOOL_TIMEOUT_SECONDS", default_tool_timeout_seconds, minimum=0.001),
-            keep_alive=values.get("FREELLAMA_AGENT_KEEP_ALIVE", "5m").strip(),
-            think=_env_bool(values, "FREELLAMA_AGENT_THINK", False),
-            max_parse_repairs=_env_int(values, "FREELLAMA_AGENT_MAX_PARSE_REPAIRS", MAX_PARSE_REPAIRS, minimum=0),
-            parse_repair_echo_chars=_env_int(values, "FREELLAMA_AGENT_PARSE_REPAIR_ECHO_CHARS", 500, minimum=1),
-            context=context,
-        )
-        if context_budget(config.num_ctx, config.num_predict, context.safety_margin_tokens) <= 0:
-            raise ValueError(
-                "FREELLAMA_AGENT_NUM_CTX must exceed FREELLAMA_AGENT_NUM_PREDICT plus "
-                "FREELLAMA_AGENT_SAFETY_MARGIN_TOKENS"
-            )
-        if not config.keep_alive:
-            raise ValueError("FREELLAMA_AGENT_KEEP_ALIVE must not be empty")
-        return config
-
-    def metadata(self) -> dict[str, Any]:
-        result = asdict(self)
-        result.pop("context", None)
-        return result
-
-
-def estimate_tokens(text: str, chars_per_token: float = CHARS_PER_TOKEN) -> int:
-    """Approximate a first-call token count; later model counts calibrate the multiplier."""
-    return math.floor(len(text) / chars_per_token) + 1
-
-
-def messages_tokens(messages: list[dict[str, Any]], policy: ContextPolicy | None = None) -> int:
-    """Estimate typed Ollama messages without flattening images/tool calls into text."""
-    policy = policy or ContextPolicy()
-    total = 0
-    for message in messages:
-        content = message.get("content", "")
-        total += estimate_tokens(
-            content if isinstance(content, str) else json.dumps(content, ensure_ascii=False),
-            policy.chars_per_token,
-        )
-        images = message.get("images", [])
-        if isinstance(images, list):
-            total += len(images) * policy.image_token_estimate
-        metadata = {key: value for key, value in message.items() if key not in {"content", "images"}}
-        total += estimate_tokens(
-            json.dumps(metadata, ensure_ascii=False, default=str), policy.chars_per_token
-        )
-    return total
-
-
-class ContextBudgeter:
-    """Conservative estimate calibrated by Ollama's real post-call prompt count.
-
-    Ollama currently has no stable preflight tokenizer endpoint. The first call therefore uses the
-    configured character estimate. After every successful call, `prompt_eval_count` raises (never
-    lowers) the estimate multiplier. A model tag alone does not identify an immutable template.
-    """
-
-    def __init__(
-        self,
-        policy: ContextPolicy | None = None,
-        *,
-        initial_scale: float = 1.0,
-        calibration_samples: int = 0,
-    ) -> None:
-        self.policy = policy or ContextPolicy()
-        self.scale = max(float(initial_scale), 1.0)
-        self.calibration_samples = max(int(calibration_samples), 0)
-
-    def estimate(self, messages: list[dict[str, Any]]) -> int:
-        return math.ceil(messages_tokens(messages, self.policy) * self.scale)
-
-    def observe(self, messages: list[dict[str, Any]], prompt_eval_count: Any) -> bool:
-        try:
-            actual = int(prompt_eval_count)
-        except (TypeError, ValueError):
-            return False
-        if actual <= 0:
-            return False
-        baseline = max(messages_tokens(messages, self.policy), 1)
-        previous = self.scale
-        self.scale = max(self.scale, actual / baseline)
-        self.calibration_samples += 1
-        return self.scale > previous
-
-    def metadata(self) -> dict[str, Any]:
-        return {
-            "token_counting": "model_calibrated_estimate" if self.calibration_samples else "configured_estimate",
-            "estimate_scale": round(self.scale, 6),
-            "calibration_samples": self.calibration_samples,
-        }
-
-
-def clip(text: str, limit: int, head_ratio: float = CLIP_HEAD_RATIO) -> str:
-    """Truncate to `limit` characters keeping both ends.
-
-    The adapters previously did `text[-limit:]`, keeping only the tail. That is the wrong half for
-    almost every tool used here: a directory listing, a grep result and a file read all put their
-    most identifying content first, so tail-only truncation threw away the part the model needed
-    and kept the trailing noise. Keeping a majority head plus a minority tail preserves the
-    beginning of the result while still showing where it ended.
-    """
-    if not 0 < head_ratio < 1:
-        raise ValueError("head_ratio must be between 0 and 1")
-    if limit <= 0 or len(text) <= limit:
-        return text
-    marker_template = "\n… [{dropped} characters elided] …\n"
-    # Reserve room for the marker itself so the result never exceeds `limit`.
-    marker_budget = len(marker_template.format(dropped=len(text)))
-    usable = max(limit - marker_budget, 0)
-    if usable == 0:
-        return text[:limit]
-    head_chars = int(usable * head_ratio)
-    tail_chars = usable - head_chars
-    dropped = len(text) - head_chars - tail_chars
-    tail = text[-tail_chars:] if tail_chars else ""
-    return text[:head_chars] + marker_template.format(dropped=dropped) + tail
-
-
-def context_budget(
-    num_ctx: int,
-    num_predict: int,
-    safety_margin_tokens: int = SAFETY_MARGIN_TOKENS,
-) -> int:
-    """Tokens available for the conversation itself, once generation and slack are reserved."""
-    return max(num_ctx - num_predict - safety_margin_tokens, 0)
-
-
-def _compact(content: str, policy: ContextPolicy) -> str:
-    """Keep a deterministic evidence breadcrumb and a usable stored-output handle.
-
-    This is an extract, not a semantic summary: no inferred facts or decisions are added. Existing
-    breadcrumbs remain byte-identical so later overflows do not invalidate the prefix again.
-    """
-    if content.startswith(COMPACT_MARKER):
-        return content
-    step_match = re.match(r"Observation \(step ([0-9]+)\):\n", content)
-    recovery = ""
-    body = content
-    if step_match:
-        step = int(step_match.group(1))
-        body = content[step_match.end():]
-        # Adapter-generated ledger precedes untrusted tool bytes. Preserve its concrete handles
-        # and status; this never promotes a tool result into instructions or inferred facts.
-        ledger_line, separator, remainder = body.partition("\n")
-        ledger = ledger_line if ledger_line.startswith("[evidence ledger: ") and ledger_line.endswith("]") else ""
-        if ledger and separator:
-            body = remainder
-        # Adapter loop reminders describe the old turn, not the evidence. The latest turn retains
-        # its live reminder; exclude this known suffix from the tail extract of older results.
-        body = re.sub(
-            r"\n\n(?:Commands|Tool calls) remaining: [0-9]+\. Finish now if the task is answerable; "
-            r"do not repeat prior (?:commands|calls)\.$", "", body,
-        )
-        # Read only the footer shape generated by page_footer, preserving page completeness.
-        footer_match = re.search(r"\n\n\[page ([0-9]+) of ([0-9]+) — [0-9]+ characters total, nothing discarded\. ", body)
-        page = int(footer_match.group(1)) if footer_match else 1
-        total = int(footer_match.group(2)) if footer_match else 1
-        if footer_match:
-            body = body[:footer_match.start()]
-        recovery = (
-            f'; step {step}, page {page} of {total}; retrieve stored output: '
-            f'{{"action":"page","step":{step},"page":{page}}}'
-        )
-        if ledger:
-            recovery += f"; {ledger}"
-    preview = clip(body, policy.compact_preview_chars, policy.clip_head_ratio)
-    return f"{COMPACT_MARKER}{recovery}] {preview}"
-
-
-def fit_to_context(
-    messages: list[dict[str, Any]],
-    *,
-    num_ctx: int,
-    num_predict: int,
-    keep_recent: int | None = None,
-    policy: ContextPolicy | None = None,
-    token_counter: Callable[[list[dict[str, Any]]], int] | None = None,
-) -> tuple[list[dict[str, Any]], bool]:
-    """Trim a conversation to fit `num_ctx`, protecting the parts that must never be dropped.
-
-    Returns `(messages, compacted)`. The system prompt (index 0) and the original question
-    (index 1) are pinned: they are the two messages Ollama's own front-truncation would delete
-    first, and losing either is what turns a working agent into one that emits prose instead of
-    JSON. Compaction walks oldest-first through the observation turns, so the model keeps a
-    breadcrumb of every step it took even when the full text of the early ones is gone.
-    """
-    policy = policy or ContextPolicy()
-    keep_recent = policy.keep_recent if keep_recent is None else keep_recent
-    budget = context_budget(num_ctx, num_predict, policy.safety_margin_tokens)
-    count = token_counter or (lambda value: messages_tokens(value, policy))
-    if count(messages) <= budget:
-        return messages, False
-
-    pinned = min(2, len(messages))
-    trimmed = [dict(message) for message in messages]
-    # Tool-result messages are first-class observations in native Ollama agent loops. Preserve their
-    # role and tool_name/tool_call linkage; compact only their textual payload.
-    observations = [
-        index
-        for index in range(pinned, len(trimmed))
-        if trimmed[index].get("role") in {"user", "tool"}
-        and isinstance(trimmed[index].get("content"), str)
-    ]
-    protected = set(observations[-keep_recent:]) if keep_recent else set()
-    compacted = False
-    target = math.floor(budget * COMPACTION_TARGET_RATIO)
-    for index in observations:
-        if count(trimmed) <= target:
-            break
-        if index in protected:
-            continue
-        content = trimmed[index].get("content", "")
-        replacement = _compact(content, policy)
-        if len(replacement) < len(content):
-            trimmed[index]["content"] = replacement
-            compacted = True
-
-    # Still over after compacting every droppable observation: the recent turns alone exceed the
-    # window. Clip the protected ones too rather than hand Ollama a prompt it will truncate blind.
-    #
-    # This shrinks the largest observation repeatedly instead of computing one subtraction, because
-    # the token estimate rounds up per message: a single-pass calculation lands just over budget
-    # and "just over" is exactly as silently truncated as "far over". Loop until it actually fits.
-    guard = 0
-    while count(trimmed) > budget and guard < 200:
-        guard += 1
-        widest = max(
-            observations,
-            key=lambda index: len(trimmed[index].get("content", "")),
-            default=None,
-        )
-        if widest is None:
-            break
-        content = trimmed[widest].get("content", "")
-        keep = max(int(len(content) * policy.compact_retain_ratio), policy.compact_preview_chars)
-        if keep >= len(content):
-            break
-        trimmed[widest]["content"] = clip(content, keep, policy.clip_head_ratio)
-        compacted = True
-    # Old reasoning traces can dwarf the answer and are not required to preserve a tool-call pair.
-    # Keep the field typed, but reduce its payload after observations have already been compacted.
-    for message in trimmed[pinned:-2]:
-        thinking = message.get("thinking")
-        if count(trimmed) <= budget:
-            break
-        if isinstance(thinking, str) and len(thinking) > policy.compact_preview_chars:
-            message["thinking"] = _compact(thinking, policy)
-            compacted = True
-
-    # Compact any remaining non-pinned textual history before considering the pinned contract.
-    guard = 0
-    while count(trimmed) > budget and guard < 200:
-        guard += 1
-        candidates = [
-            index
-            for index, message in enumerate(trimmed[pinned:], start=pinned)
-            if isinstance(message.get("content"), str)
-            and len(message.get("content", "")) > policy.compact_preview_chars
-        ]
-        if not candidates:
-            break
-        widest = max(candidates, key=lambda index: len(trimmed[index].get("content", "")))
-        content = trimmed[widest]["content"]
-        keep = max(int(len(content) * policy.compact_retain_ratio), policy.compact_preview_chars)
-        if keep >= len(content):
-            break
-        trimmed[widest]["content"] = clip(content, keep, policy.clip_head_ratio)
-        compacted = True
-
-    # Pinned text is byte-preserved by default. An operator may explicitly choose `clip`, but the
-    # safe default fails before Ollama can silently front-truncate the system contract or question.
-    guard = 0
-    while policy.pinned_overflow == "clip" and count(trimmed) > budget and guard < 200:
-        guard += 1
-        candidates = [
-            index
-            for index, message in enumerate(trimmed[:pinned])
-            if isinstance(message.get("content"), str)
-            and len(message.get("content", "")) > policy.compact_preview_chars
-        ]
-        if not candidates:
-            break
-        widest = max(candidates, key=lambda index: len(trimmed[index].get("content", "")))
-        content = trimmed[widest]["content"]
-        keep = max(int(len(content) * policy.compact_retain_ratio), policy.compact_preview_chars)
-        if keep >= len(content):
-            break
-        trimmed[widest]["content"] = clip(content, keep, policy.clip_head_ratio)
-        compacted = True
-    if count(trimmed) > budget:
-        raise ValueError(
-            "pinned system/question content and minimum history exceed context budget: "
-            f"{count(trimmed)} > {budget} estimated tokens. Increase FREELLAMA_AGENT_NUM_CTX, "
-            "reduce the task/instructions, or explicitly set FREELLAMA_AGENT_PINNED_OVERFLOW=clip."
-        )
-    return trimmed, compacted
-
-
-class AgentContextManager:
-    """Stateful adapter facade: fit, calibrate, count compactions, and report policy."""
-
-    def __init__(
-        self,
-        runtime: AgentRuntimeConfig,
-        *,
-        model: str = "",
-        calibration_dir: Path | None = None,
-        calibration_identity: str = "",
-    ) -> None:
-        self.runtime = runtime
-        self.model = model
-        self.calibration_dir = calibration_dir
-        self.calibration_identity = calibration_identity
-        loaded = self._load_calibration()
-        self.budgeter = ContextBudgeter(
-            runtime.context,
-            initial_scale=loaded.get("scale", 1.0),
-            calibration_samples=loaded.get("samples", 0),
-        )
-        self.calibration_source = "persistent_model_cache" if loaded else "current_process"
-        self.compactions = 0
-
-    def _model_key(self) -> str:
-        return hashlib.sha256(json.dumps(self._calibration_contract(), sort_keys=True).encode("utf-8")).hexdigest()[:24]
-
-    def _calibration_contract(self) -> dict[str, Any]:
-        return {
-            "schema_version": 2,
-            "model": self.model,
-            "identity": self.calibration_identity,
-            "estimator_version": 1,
-            "chars_per_token": self.runtime.context.chars_per_token,
-            "image_token_estimate": self.runtime.context.image_token_estimate,
-        }
-
-    def _load_calibration(self) -> dict[str, Any]:
-        if not self.model or self.calibration_dir is None or not self.calibration_dir.exists():
-            return {}
-        best_scale = 1.0
-        samples = 0
-        for path in self.calibration_dir.glob(f"{self._model_key()}-*.json"):
-            try:
-                record = json.loads(path.read_text(encoding="utf-8"))
-                if not isinstance(record, dict):
-                    continue
-                if any(record.get(key) != value for key, value in self._calibration_contract().items()):
-                    continue
-                scale = float(record.get("scale", 1.0))
-                record_samples = int(record.get("samples", 0))
-                if not math.isfinite(scale) or scale < 1 or record_samples <= 0:
-                    continue
-                best_scale = max(best_scale, scale)
-                samples = max(samples, record_samples)
-            except (OSError, ValueError, TypeError, OverflowError):
-                continue
-        return {"scale": best_scale, "samples": samples} if samples else {}
-
-    def _persist_calibration(self) -> None:
-        if not self.model or self.calibration_dir is None:
-            return
-        self.calibration_dir.mkdir(parents=True, exist_ok=True)
-        key = self._model_key()
-        record = {
-            **self._calibration_contract(),
-            "scale": self.budgeter.scale,
-            "samples": self.budgeter.calibration_samples,
-        }
-        final = self.calibration_dir / f"{key}-{time.time_ns()}-{os.getpid()}.json"
-        temporary = final.with_suffix(".tmp")
-        temporary.write_text(json.dumps(record, sort_keys=True) + "\n", encoding="utf-8")
-        os.replace(temporary, final)
-        # Bounded, race-tolerant history: independent records make concurrent writers monotonic;
-        # retaining the newest 32 avoids an unbounded cache without a cross-platform file lock.
-        records = sorted(self.calibration_dir.glob(f"{key}-*.json"), key=lambda path: path.name)
-        for stale in records[:-32]:
-            try:
-                stale.unlink()
-            except FileNotFoundError:
-                pass
-
-    def fit(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        fitted, compacted = fit_to_context(
-            messages,
-            num_ctx=self.runtime.num_ctx,
-            num_predict=self.runtime.num_predict,
-            policy=self.runtime.context,
-            token_counter=self.budgeter.estimate,
-        )
-        self.compactions += int(compacted)
-        return fitted
-
-    def observe(self, messages: list[dict[str, Any]], prompt_eval_count: Any) -> None:
-        if self.budgeter.observe(messages, prompt_eval_count):
-            self._persist_calibration()
-
-    def metadata(self) -> dict[str, Any]:
-        return {
-            **self.runtime.context.metadata(),
-            **self.budgeter.metadata(),
-            "calibration_source": self.calibration_source,
-            "calibration_scope": "provided_identity_and_estimator" if self.calibration_identity else "model_tag_and_estimator",
-            "compaction_target_ratio": COMPACTION_TARGET_RATIO,
-            "estimated_input_budget": context_budget(
-                self.runtime.num_ctx,
-                self.runtime.num_predict,
-                self.runtime.context.safety_margin_tokens,
-            ),
-            "compactions": self.compactions,
-        }
-
-
-def write_failure_result(result_path: Path, answer: str) -> None:
-    """Write the minimum valid adapter result for a failure before the normal result path."""
-    result_path.parent.mkdir(parents=True, exist_ok=True)
-    result_path.write_text(
-        json.dumps({"final_answer": answer, "tool_calls": [], "usage": {}}, indent=2) + "\n",
-        encoding="utf-8",
-    )
-
-
-def parse_json_action(content: str) -> dict[str, Any]:
-    """Recover one JSON object while leaving adapter-specific action validation to the caller."""
-    text = content.strip()
-    if text.startswith("```"):
-        lines = text.splitlines()
-        text = "\n".join(lines[1:-1]).strip()
-    try:
-        value = json.loads(text)
-    except json.JSONDecodeError:
-        decoder = json.JSONDecoder()
-        start = text.find("{")
-        if start < 0:
-            raise ValueError("model did not return a JSON action") from None
-        try:
-            value, _ = decoder.raw_decode(text, start)
-        except json.JSONDecodeError:
-            raise ValueError("model did not return a valid JSON action") from None
-    if not isinstance(value, dict) or not isinstance(value.get("action"), str):
-        raise ValueError("model action must be a JSON object with an action")
-    return value
-
-
-def call_signature(payload: Any) -> str:
-    """Stable identity for a tool call, so an exact repeat can be recognized.
-
-    Both adapters tell the model "do not repeat prior calls" and neither enforced it. A repeat is
-    not just a wasted turn out of ten — it also re-appends an observation the model has already
-    seen, spending context twice on one fact.
-    """
-    return json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str)
-
-
-REPEAT_NOTICE = (
-    "(identical call already made this run — its result is above and was not re-executed. "
-    "Use a different call, or finish now with the evidence already collected.)"
-)
-
-
-# How many unparseable turns to try to repair before giving up on the run. A model that emits prose
-# instead of JSON once will usually correct when told so explicitly; aborting on the first one threw
-# away an entire delegation — including every tool result already gathered — and surfaced as
-# "model did not return a valid JSON action", which reads like model weakness rather than a loop
-# with no error recovery.
-MAX_PARSE_REPAIRS = 2
-
-PARSE_REPAIR_NOTICE = (
-    "Your last reply was not a valid JSON action, so it was discarded. Reply with EXACTLY one JSON "
-    "object and nothing else — no prose before or after, no markdown fence. Use the action shapes "
-    "given in your instructions. If you already have enough evidence, send the finish action now."
-)
-
-# ---------------------------------------------------------------------------------------------
-# Pagination — the alternative to throwing data away
-#
-# Clipping an observation is silent data loss the model can never recover: a routine
-# `grep -rn "def " .` over jinja produces ~27,000 characters, and a 3,000-character clip discarded
-# 89% of it. The model cannot ask for the rest, cannot tell how much it is missing, and will
-# happily conclude "not found" from a window that never contained the answer.
-#
-# Pagination keeps every byte. The full observation is retained, the model is shown one page plus
-# an exact instruction for requesting the next, and asking for page 2 re-serves stored text rather
-# than re-running the command — so paging costs a turn, never a duplicate subprocess.
-# ---------------------------------------------------------------------------------------------
-
-def paginate(text: str, page: int = 1, page_size: int = OBSERVATION_PAGE_CHARS) -> tuple[str, int, int]:
-    """Return `(chunk, page, total_pages)`, preferring line boundaries within a hard limit.
-
-    Line-aware on purpose: these observations are grep hits, directory listings and file slices,
-    where a chunk cut mid-line yields a truncated path or a half identifier — exactly the kind of
-    fragment that gets misread as data rather than as damage. An oversized individual line is
-    split to keep even minified JSON/logs bounded; joining all chunks reproduces the exact input.
-    """
-    if page_size <= 0:
-        raise ValueError("observation page size must be > 0")
-    if not text:
-        return "", 1, 1
-    lines = text.splitlines(keepends=True)
-    pages: list[list[str]] = [[]]
-    size = 0
-    for line in lines:
-        if size and size + len(line) > page_size:
-            pages.append([])
-            size = 0
-        for start in range(0, len(line), page_size):
-            part = line[start:start + page_size]
-            if size and size + len(part) > page_size:
-                pages.append([])
-                size = 0
-            pages[-1].append(part)
-            size += len(part)
-    total = max(1, len(pages))
-    page = max(1, min(page, total))
-    return "".join(pages[page - 1]), page, total
-
-
-def page_footer(step: int, page: int, total: int, total_chars: int) -> str:
-    """Tell the model exactly how to get the rest — or that there is no rest."""
-    if total <= 1:
-        return ""
-    if page >= total:
-        return (
-            f'\n\n[page {page} of {total} — {total_chars} characters total, nothing discarded. '
-            'End of stored output.]'
-        )
-    nxt = page + 1
-    return (
-        f'\n\n[page {page} of {total} — {total_chars} characters total, nothing discarded. '
-        f'For the next page send exactly: {{"action":"page","step":{step},"page":{nxt}}} '
-        f"— that re-reads stored output and does NOT re-run the command.]"
-    )
-
-
-@dataclass(frozen=True)
-class StoredObservation:
-    path: Path
-    index_path: Path
-    characters: int
-    pages: int
-    metadata: dict[str, str]
-
-
-class ObservationStore:
-    """Disk-backed exact observations with one small descriptor per step in memory.
-
-    Page offsets also live on disk; an arbitrary page read loads one fixed-width offset record
-    and one page. The subprocess result exists transiently at put(), never across model turns.
-    """
-
-    def __init__(self, page_size: int = OBSERVATION_PAGE_CHARS) -> None:
-        if page_size <= 0:
-            raise ValueError("observation page size must be > 0")
-        self._temporary = tempfile.TemporaryDirectory(prefix="freellama-observations-")
-        self.directory = Path(self._temporary.name)
-        self._by_step: dict[int, StoredObservation] = {}
-        self.page_size = page_size
-
-    def __enter__(self) -> "ObservationStore":
-        return self
-
-    def __exit__(self, *_: Any) -> None:
-        self.close()
-
-    def close(self) -> None:
-        self._by_step.clear()
-        self._temporary.cleanup()
-
-    def put(self, step: int, text: str, *, metadata: Mapping[str, Any] | None = None) -> None:
-        if step < 1:
-            raise ValueError("observation step must be positive")
-        path = self.directory / f"{step}.utf8"
-        index_path = self.directory / f"{step}.index"
-        start = offset = pages = 0
-        with path.open("wb") as output, index_path.open("wb") as index:
-            while start < len(text):
-                end = min(start + self.page_size, len(text))
-                # Prefer a complete line without allocating or splitting the full result. A line
-                # longer than a page is split at the hard character limit, losslessly.
-                if end < len(text):
-                    newline = text.rfind("\n", start, end)
-                    if newline >= start:
-                        end = newline + 1
-                encoded = text[start:end].encode("utf-8")
-                output.write(encoded)
-                next_offset = offset + len(encoded)
-                index.write(struct.pack(">QQ", offset, next_offset))
-                offset = next_offset
-                pages += 1
-                start = end
-            if not pages:
-                index.write(struct.pack(">QQ", 0, 0))
-                pages = 1
-        bounded_metadata = {
-            key: clip(str(value), 240)
-            for key, value in (metadata or {}).items()
-            if key in {"action", "status", "source"}
-        }
-        self._by_step[step] = StoredObservation(path, index_path, len(text), pages, bounded_metadata)
-
-    def get(self, step: int) -> str | None:
-        """Explicit full materialization for consumers that need it; adapters use view/write_result."""
-        record = self._by_step.get(step)
-        return record.path.read_bytes().decode("utf-8") if record else None
-
-    def page_count(self, step: int) -> int:
-        return self._by_step[step].pages
-
-    def view(self, step: int, page: int = 1) -> tuple[str, str]:
-        """Return `(body, footer)` for one page of a stored observation."""
-        record = self._by_step.get(step)
-        if record is None:
-            known = ", ".join(str(k) for k in sorted(self._by_step)) or "none yet"
-            return (f"no stored output for step {step} (known steps: {known})", "")
-        page = max(1, min(page, record.pages))
-        with record.index_path.open("rb") as index:
-            index.seek((page - 1) * 16)
-            start, end = struct.unpack(">QQ", index.read(16))
-        with record.path.open("rb") as output:
-            output.seek(start)
-            chunk = output.read(end - start).decode("utf-8")
-        return chunk, page_footer(step, page, record.pages, record.characters)
-
-    def message(self, step: int, page: int = 1) -> str:
-        body, footer = self.view(step, page)
-        record = self._by_step.get(step)
-        if record is None:
-            return f"Observation (step {step}):\n{body}"
-        page = max(1, min(page, record.pages))
-        ledger = {
-            **record.metadata, "step": step, "page": page, "total_pages": record.pages,
-            "trust": "untrusted_tool_output",
-        }
-        return (
-            f"Observation (step {step}):\n[evidence ledger: "
-            f"{json.dumps(ledger, ensure_ascii=False, separators=(',', ':'))}]\n{body}{footer}"
-        )
-
-    def write_result(self, result_path: Path, result: dict[str, Any]) -> None:
-        """Atomically stream the public JSON result, restoring full call results from disk."""
-        result_path.parent.mkdir(parents=True, exist_ok=True)
-        temporary: Path | None = None
-        try:
-            with tempfile.NamedTemporaryFile(
-                mode="w", encoding="utf-8", dir=result_path.parent,
-                prefix=f".{result_path.name}.", suffix=".tmp", delete=False,
-            ) as output:
-                temporary = Path(output.name)
-                output.write("{")
-                for field_index, (key, value) in enumerate(result.items()):
-                    if field_index:
-                        output.write(",")
-                    output.write(json.dumps(key) + ":")
-                    if key != "tool_calls":
-                        json.dump(value, output, ensure_ascii=False)
-                        continue
-                    output.write("[")
-                    for step, call in enumerate(value, start=1):
-                        if step > 1:
-                            output.write(",")
-                        metadata = {key: value for key, value in call.items() if key != "result"}
-                        encoded = json.dumps(metadata, ensure_ascii=False)
-                        output.write(encoded[:-1] + ("," if metadata else "") + '"result":"')
-                        with self._by_step[step].path.open("r", encoding="utf-8", newline="") as source:
-                            while chunk := source.read(16_384):
-                                output.write(json.dumps(chunk, ensure_ascii=False)[1:-1])
-                        output.write('"}')
-                    output.write("]")
-                output.write("}\n")
-            os.replace(temporary, result_path)
-        finally:
-            if temporary is not None and temporary.exists():
-                temporary.unlink()