@octocodeai/freellama-mcp-server 0.1.0 → 0.5.0

package/adapters/agent_context.py

@@ -20,6 +20,9 @@ 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
@@ -47,6 +50,10 @@ 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:
@@ -224,7 +231,7 @@ class ContextBudgeter:
 
     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 for this exact model/chat template.
+    lowers) the estimate multiplier. A model tag alone does not identify an immutable template.
     """
 
     def __init__(
@@ -298,8 +305,45 @@ def context_budget(
 
 
 def _compact(content: str, policy: ContextPolicy) -> str:
-    preview = " ".join(content[: policy.compact_preview_chars].split())
-    return f"[earlier observation compacted to save context] {preview}…"
+    """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(
@@ -338,8 +382,9 @@ def fit_to_context(
     ]
     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) <= budget:
+        if count(trimmed) <= target:
             break
         if index in protected:
             continue
@@ -439,10 +484,12 @@ class AgentContextManager:
         *,
         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,
@@ -453,7 +500,17 @@ class AgentContextManager:
         self.compactions = 0
 
     def _model_key(self) -> str:
-        return hashlib.sha256(self.model.encode("utf-8")).hexdigest()[:24]
+        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():
@@ -463,11 +520,17 @@ class AgentContextManager:
         for path in self.calibration_dir.glob(f"{self._model_key()}-*.json"):
             try:
                 record = json.loads(path.read_text(encoding="utf-8"))
-                if record.get("schema_version") != 1 or record.get("model") != self.model:
+                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, float(record.get("scale", 1.0)))
-                samples = max(samples, int(record.get("samples", 0)))
-            except (OSError, ValueError, TypeError, json.JSONDecodeError):
+                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 {}
 
@@ -477,8 +540,7 @@ class AgentContextManager:
         self.calibration_dir.mkdir(parents=True, exist_ok=True)
         key = self._model_key()
         record = {
-            "schema_version": 1,
-            "model": self.model,
+            **self._calibration_contract(),
             "scale": self.budgeter.scale,
             "samples": self.budgeter.calibration_samples,
         }
@@ -515,6 +577,8 @@ class AgentContextManager:
             **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,
@@ -598,24 +662,31 @@ PARSE_REPAIR_NOTICE = (
 # ---------------------------------------------------------------------------------------------
 
 def paginate(text: str, page: int = 1, page_size: int = OBSERVATION_PAGE_CHARS) -> tuple[str, int, int]:
-    """Return `(chunk, page, total_pages)`, splitting on line boundaries.
+    """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.
+    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:
-        # A single line longer than a page gets its own page rather than being split.
         if size and size + len(line) > page_size:
             pages.append([])
             size = 0
-        pages[-1].append(line)
-        size += len(line)
+        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
@@ -625,8 +696,12 @@ 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 ""
-    remaining = total - page
-    nxt = page + 1 if remaining else 1
+    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}}} '
@@ -634,30 +709,142 @@ def page_footer(step: int, page: int, total: int, total_chars: int) -> str:
     )
 
 
+@dataclass(frozen=True)
+class StoredObservation:
+    path: Path
+    index_path: Path
+    characters: int
+    pages: int
+    metadata: dict[str, str]
+
+
 class ObservationStore:
-    """Keeps every observation in full so any page can be served later.
+    """Disk-backed exact observations with one small descriptor per step in memory.
 
-    This is what makes pagination lossless rather than a nicer-looking clip: the text stays here
-    whole, and the conversation only ever holds the page the model asked for.
+    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._by_step: dict[int, str] = {}
+        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 put(self, step: int, text: str) -> None:
-        self._by_step[step] = text
+    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:
-        return self._by_step.get(step)
+        """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."""
-        text = self._by_step.get(step)
-        if text is None:
+        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})", "")
-        chunk, page, total = paginate(text, page, self.page_size)
-        return chunk, page_footer(step, page, total, len(text))
+        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()

package/adapters/agent_transport.py

@@ -3,8 +3,137 @@
 from __future__ import annotations
 
 import os
+import hashlib
+import json
+import re
 from pathlib import Path
 from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+def _read_identity_json(url: str) -> dict[str, Any]:
+    with urlopen(Request(url, headers=request_headers()), timeout=5) as response:
+        payload = response.read(1024 * 1024 + 1)
+    if len(payload) > 1024 * 1024:
+        raise ValueError("model identity catalog exceeds size limit")
+    return json.loads(payload)
+
+
+def resolve_model_identity(
+    endpoint: str, model: str, system_prompt: str, *, read_json=None,
+) -> dict[str, Any]:
+    """Resolve immutable manifest identity once per adapter run, without loading a model.
+
+    Managed catalogs honor exact CPU backend assignment. Failure disables persistent calibration;
+    a mutable tag or a hash of the prompt alone must never masquerade as model identity.
+    """
+    endpoint = endpoint.rstrip("/")
+    managed_suffix = "/_freellama/v1/tasks"
+    url = (endpoint[:-len(managed_suffix)] + "/_freellama/v1/models"
+           if endpoint.endswith(managed_suffix) else endpoint + "/api/tags")
+    unknown = {"identity": "", "verified": False, "scope": "current_process_only"}
+    try:
+        payload = (read_json or _read_identity_json)(url)
+        entries = payload.get("models", []) if isinstance(payload, dict) else []
+        if not isinstance(entries, list):
+            return unknown
+        names = {model}
+        if ":" not in model.rsplit("/", 1)[-1]:
+            names.add(model + ":latest")
+        entry = next((item for item in entries if isinstance(item, dict)
+                      and item.get("name", item.get("model")) in names), None)
+        digest = entry.get("digest") if entry else None
+        if not isinstance(digest, str) or not re.fullmatch(r"(?:sha256:)?[0-9a-fA-F]{64}", digest):
+            return unknown
+        digest = digest.removeprefix("sha256:").lower()
+        contract = {"endpoint": endpoint, "model": model, "digest": digest,
+                    "system_hash": hashlib.sha256(system_prompt.encode("utf-8")).hexdigest()}
+        return {"identity": hashlib.sha256(json.dumps(contract, sort_keys=True).encode()).hexdigest(),
+                "verified": True, "scope": "manifest_digest_and_system_prompt", "digest": digest}
+    except (OSError, ValueError, TypeError):
+        return unknown
+
+
+def retryable_chat_error(error: Exception) -> bool:
+    """Retry known refusals only; a timeout may leave inference running upstream."""
+    if isinstance(error, HTTPError):
+        return error.code == 503
+    return isinstance(error, URLError) and isinstance(error.reason, ConnectionRefusedError)
+
+
+def chat_error_details(error: Exception) -> tuple[str, dict[str, Any] | None]:
+    """Retain bounded application refusal receipts, excluding request/auth payloads."""
+    diagnostic = f"{type(error).__name__}: {error}"
+    if not isinstance(error, HTTPError):
+        return diagnostic, None
+    details: dict[str, Any] = {"status": error.code}
+    try:
+        body = error.read(64 * 1024 + 1)
+        if len(body) > 64 * 1024:
+            return diagnostic, details
+        payload = json.loads(body)
+        if not isinstance(payload, dict) or not isinstance(payload.get("error"), str):
+            return diagnostic, details
+        receipt_fields = {
+            "error", "code", "reason", "retry_after_seconds", "resource_admission", "lifecycle",
+            "placement", "execution", "admission", "route", "decision", "quality", "feedback",
+        }
+        payload_fields = {
+            "prompt", "system", "system_prompt", "messages", "content", "input", "images", "tools",
+            "request", "request_options", "headers", "authorization", "token", "api_key", "auth_token",
+        }
+
+        def receipt_value(value: Any) -> Any:
+            if isinstance(value, dict):
+                return {key: receipt_value(item) for key, item in value.items() if key.lower() not in payload_fields}
+            if isinstance(value, list):
+                return [receipt_value(item) for item in value]
+            return value
+
+        receipt = {key: receipt_value(value) for key, value in payload.items() if key in receipt_fields}
+        details["receipt"] = receipt
+        diagnostic = f"HTTP {error.code}: {receipt['error']}"
+    except (OSError, ValueError, RecursionError):
+        pass
+    finally:
+        error.close()
+    return diagnostic, details
+
+
+class PromptCacheUsage:
+    """Aggregate optional Ollama cache reads without treating unavailable turns as zero."""
+
+    def __init__(self) -> None:
+        self.calls = 0
+        self.reported_calls = 0
+        self.reported_tokens = 0
+        self.reported_prompt_tokens = 0
+
+    def observe(self, response: dict[str, Any]) -> None:
+        self.calls += 1
+        cached = response.get("prompt_eval_cached_count")
+        prompt = response.get("prompt_eval_count")
+        if type(cached) is int and type(prompt) is int and 0 <= cached <= prompt:
+            self.reported_calls += 1
+            self.reported_tokens += cached
+            self.reported_prompt_tokens += prompt
+
+    @property
+    def tokens(self) -> int | None:
+        return self.reported_tokens if self.calls > 0 and self.calls == self.reported_calls else None
+
+    def metadata(self) -> dict[str, Any]:
+        return {
+            "status": "reported" if self.tokens is not None else (
+                "partially_reported" if self.reported_calls else "not_reported"
+            ),
+            "calls": self.calls,
+            "reported_calls": self.reported_calls,
+            "reported_tokens": self.reported_tokens if self.reported_calls else None,
+            "hit_ratio": self.reported_tokens / self.reported_prompt_tokens
+            if self.tokens is not None and self.reported_prompt_tokens else None,
+        }
 
 
 def request_headers() -> dict[str, str]:
@@ -59,6 +188,8 @@ def chat_request(
         "model": model,
         "messages": messages,
         "stream": False,
+        "truncate": False,
+        "shift": False,
         "format": "json",
         "think": think,
         "keep_alive": keep_alive,