tinker-agent 1.0.65

package/README.md

@@ -0,0 +1,173 @@
+# Tinker
+
+**Tinker** is a personal coding agent — an interactive TUI (Terminal User Interface) and one-shot CLI tool that drives an LLM in an agent loop with file, search, shell, and MCP tools to read and modify a local workspace.
+
+Built with [Bun](https://bun.sh) + TypeScript ESM, powered by [Ink](https://github.com/vadimdemedes/ink) (React for CLIs).
+
+## Features
+
+- **Interactive TUI**: Full terminal user interface with session management, prompt history, and slash commands.
+- **One-shot CLI**: Run a single prompt non-interactively with `tinker run "prompt"`.
+- **Built-in tools**:
+  - `Glob` / `Grep` — Find and search files by pattern or content
+  - `Read` / `Write` / `Edit` — File I/O with content hashing and concurrent-modification protection
+  - `Bash` — Run shell commands (foreground and background) with per-task working directories
+  - `TaskList` / `TaskOutput` / `TaskStop` — Manage long-running background shell tasks
+  - `WebSearch` — Search the web via Exa API
+  - `WebFetch` — Fetch and refine web page content (local, browser, or Exa backend)
+  - `Recall` — Search or retrieve model-visible history from the current session
+- **MCP integration**: Connect external [Model Context Protocol](https://modelcontextprotocol.io) servers — their tools are dynamically registered as `mcp__<server>__<tool>`.
+- **Session persistence**: Sessions are persisted via SQLite, supporting session resume, history recall, and a catalog to browse and switch between sessions.
+- **Observation system**: Tool execution results are formatted into structured text that the model sees, with separate raw results for event logs and TUI display.
+- **Turn cancellation**: Users can cancel an ongoing turn safely, with protocol-safe synthetic tool messages.
+- **Context metering**: Budget-aware context management with protocol validation before sending requests to the model.
+- **Deterministic context compaction**: Idle sessions can swap eligible historical tool output into Recall-addressable placeholders without calling the model.
+- **Choice of models**: Supports any OpenAI-compatible API (defaults to DeepSeek). Configurable via environment variables.
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone <repo>
+cd tinker
+bun install
+
+# Start the interactive TUI
+bun run tinker
+
+# Run a one-shot prompt
+bun run tinker run "explain the project structure"
+```
+
+### Slash Commands
+
+- `/view <path>` — Open a readable UTF-8 text file in a full-window viewer. Relative
+  paths must remain inside the workspace; absolute paths may point outside it. Use
+  the keyboard or mouse wheel to scroll and press `Esc` to close the viewer.
+- `/status` — Show session and context details.
+- `/compact` — Deterministically compact eligible historical tool output while the session is idle.
+- `/model [profile-name]` — Choose a model profile for a new session.
+- `/resume [session-id]` — Choose or directly resume a stored session.
+- `/session delete <session-id> --confirm` — Delete a stored session.
+- `/quit` — Exit the TUI.
+
+## Configuration
+
+Tinker is configured via environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `TINKER_MODEL` | — | Required model name when `TINKER_MODELS` is not set |
+| `TINKER_BASE_URL` | — | Required API base URL |
+| `TINKER_API_KEY` | — | Required API key |
+| `TINKER_MODELS` | — | Path to a multi-model profiles JSON file (see below) |
+| `TINKER_WORKSPACE` | `process.cwd()` | Workspace root |
+| `TINKER_MAX_ITERATIONS` | `512` | Max agent loop iterations per turn |
+| `EXA_API_KEY` | — | Enables WebSearch tool |
+| `TINKER_MCP_CONFIG` | — | Path to MCP server config JSON |
+| `TINKER_EVENT_LOG` | `$TINKER_DIR/events.jsonl` | Event log path |
+| `TINKER_SESSION_DIR` | `$TINKER_DIR/sessions` | Session storage directory |
+| `TINKER_INCLUDE_REASONING` | `false` | Include model reasoning in output |
+| `TINKER_TASK_STOP_GRACE_MS` | `5000` | Grace period before SIGKILL |
+| `TINKER_MCP_TIMEOUT_MS` | `30000` | MCP tool timeout |
+| `TINKER_CONTEXT_BUDGET_TOKENS` | `128000` | Context budget in tokens |
+
+### Multi-Model Profiles
+
+Set `TINKER_MODELS` in `.env` to point to a JSON file with multiple named model
+profiles. When set, the profile's `default` field selects the startup model, and
+the `/model` slash command (available in new sessions before any turns) lets you
+switch to another profile. If `TINKER_MODELS` is not set, Tinker falls back to
+the individual `TINKER_*` environment variables. A configured profiles file must
+exist and be valid; Tinker does not silently fall back when it cannot be loaded.
+
+```json
+{
+  "default": "deepseek",
+  "profiles": {
+    "deepseek": {
+      "model": "deepseek-chat",
+      "apiBase": "https://api.deepseek.com/v1",
+      "apiKey": "sk-xxx",
+      "contextWindowTokens": 128000,
+      "maxSupportedOutputTokens": 8192
+    },
+    "gpt-4o": {
+      "model": "gpt-4o",
+      "apiBase": "https://api.openai.com/v1",
+      "apiKey": "sk-yyy",
+      "contextWindowTokens": 128000,
+      "maxSupportedOutputTokens": 16384,
+      "includeReasoningContent": true
+    }
+  }
+}
+```
+
+You can also start TUI with a specific profile:
+
+```bash
+bun run tinker --profile gpt-4o
+```
+
+Switching models creates a new session. The previous session is preserved and
+can be resumed with `/resume`. Each session records its profile name, and resume
+reopens the session with that profile. Resume fails clearly if the profile is no
+longer present or its runtime contract has changed. Older sessions without a
+stored profile name can resume only when their model name uniquely matches one
+configured profile.
+
+`Read` has a fixed 262144-byte (256 KiB) content limit per call. A successful
+call always returns the complete requested line range. Use `offset` and `limit`
+to page through larger files; oversized requests fail instead of returning
+truncated content.
+
+## Commands
+
+```bash
+bun install              # Install dependencies
+bun run tinker           # Start the interactive TUI
+bun run tinker run "..." # Run a one-shot CLI prompt
+bun test                 # Run test suite
+bun run typecheck        # TypeScript type checking (tsc --noEmit)
+bun run lint             # ESLint (zero warnings required)
+bun run format           # Biome code formatting
+bun run check            # Full check: typecheck + format + lint + test
+```
+
+## Project Structure
+
+```
+tinker/
+├── src/
+│   ├── cli/           # Entry points (tui, run), config
+│   ├── agent/         # Agent loop, session ledger, turn cancellation, context metering
+│   ├── tools/         # Tool executors (bash, glob, grep, read, write, edit, recall, etc.)
+│   ├── model/         # Model clients (OpenAI-compatible, fake), chat mapping, preflight
+│   ├── mcp/           # MCP server management, tool executor adapter
+│   ├── observation/   # Tool result → model-visible text
+│   ├── session/       # SQLite session store, catalog, history reader, resume
+│   ├── events/        # Event sinks, JSONL log, stdout printer
+│   ├── tui/           # Ink/React UI components, projection store, session controller
+│   ├── context/       # Context protocol validation, protocol frame construction
+│   └── ids/           # Runtime ID generation (UUID v7)
+├── docs/              # Design notes and planning documents
+├── .tinker/           # Runtime data (sessions, bash tasks, events)
+└── package.json
+```
+
+## Design Philosophy
+
+- **Fast-fail**: Validate assumptions early and return clear errors close to the source. Structured failures allow the model to correct and retry.
+- **Model sees only text**: Tool execution results are rendered into readable text for the model. Raw result data with extra detail is kept for event logs and the TUI.
+- **Protocol safety**: All tool calls produce protocol-safe messages — even cancellations, fatal errors, or interruptions generate well-formed tool messages so the agent loop can continue.
+- **Session durability**: Every turn, iteration, and tool call is committed to the SQLite ledger before the model is called, enabling reliable resume and history recall.
+
+## Requirements
+
+- [Bun](https://bun.sh) (developed with Bun 1.x)
+- A compatible LLM API (defaults to DeepSeek; any OpenAI-compatible API works)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "tinker-agent",
+  "version": "1.0.65",
+  "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "tinker": "src/cli/index.ts",
+    "tinker-agent": "src/cli/index.ts"
+  },
+  "files": [
+    "src/agent",
+    "src/cli",
+    "src/context",
+    "src/events",
+    "src/ids",
+    "src/instructions",
+    "src/mcp",
+    "src/model",
+    "src/observation",
+    "src/session",
+    "src/tools",
+    "src/tui",
+    "patches",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "bench:long-session": "bun scripts/bench-long-session-memory.ts",
+    "bench:recall": "bun scripts/bench-recall.ts",
+    "bench:smoke": "bun scripts/bench-smoke.ts",
+    "tinker": "bun src/cli/index.ts",
+    "check": "bun run typecheck && bun run format:check && bun run lint && bun test && bun run bench:smoke",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint": "eslint \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" --max-warnings=0",
+    "lint:fix": "eslint \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" --fix",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@assistant-ui/react-ink": "^0.0.31",
+    "@assistant-ui/react-ink-markdown": "^0.0.30",
+    "@inkjs/ui": "^2.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mozilla/readability": "^0.6.0",
+    "diff": "^9.0.0",
+    "glob": "^13.0.6",
+    "ink": "^7.1.0",
+    "linkedom": "^0.18.13",
+    "openai": "^6.45.0",
+    "react": "^19.2.7",
+    "shiki": "^4.3.1",
+    "turndown": "^7.2.4",
+    "uuid": "^14.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
+    "@eslint/js": "^10.0.1",
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19.2.17",
+    "@types/turndown": "^5.0.6",
+    "eslint": "^10.6.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.7.0",
+    "ink-testing-library": "^4.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1"
+  },
+  "patchedDependencies": {
+    "markdansi@0.3.2": "patches/markdansi@0.3.2.patch"
+  }
+}

package/patches/markdansi@0.3.2.patch

@@ -0,0 +1,37 @@
+diff --git a/dist/render.js b/dist/render.js
+index 5de3a5d5c1e0c8bfe8dec992ca3d57987f2ba6ee..53237b86315dc56fdb2e6295aea698ee033350ce 100644
+--- a/dist/render.js
++++ b/dist/render.js
+@@ -572,7 +572,7 @@ function renderTable(node, ctx) {
+             const content = ctx.options.tableTruncate
+                 ? truncateCell(cell, target, ctx.options.tableEllipsis)
+                 : cell;
+-            const wrapped = wrapText(content, ctx.options.wrap ? target : Number.MAX_SAFE_INTEGER, ctx.options.wrap);
++            const wrapped = wrapText(content, ctx.options.wrap ? target : Number.MAX_SAFE_INTEGER, ctx.options.wrap).flatMap((line) => hardWrapTableCellLine(line, target, ctx.options.wrap));
+             return wrapped.map((l) => {
+                 const aligned = padCell(l, target, aligns[idx] ?? "left");
+                 const padded = `${padStr}${aligned}${padStr}`;
+@@ -627,6 +627,23 @@ function sliceCellContent(text, width) {
+     }
+     return sliced;
+ }
++function hardWrapTableCellLine(text, width, wrap) {
++    if (!wrap || width <= 0 || visibleWidth(text) <= width)
++        return [text];
++    const parts = [];
++    let remaining = text;
++    while (visibleWidth(remaining) > width) {
++        const part = sliceCellContent(remaining, width);
++        const consumedWidth = visibleWidth(part);
++        if (consumedWidth <= 0)
++            break;
++        parts.push(part);
++        remaining = sliceAnsi(remaining, consumedWidth);
++    }
++    if (remaining !== "")
++        parts.push(remaining);
++    return parts.length ? parts : [text];
++}
+ function wrapCodeLine(text, width) {
+     // Hard-wrap code even without spaces while keeping ANSI-safe width accounting.
+     if (width <= 0)

package/src/agent/context-builder.ts

@@ -0,0 +1,43 @@
+import type { ToolDefinition } from "../tools/types";
+import type {
+  BuiltContextRequest,
+  CompiledRevisionContext,
+  StoredContextRevisionV5,
+  SwapOverride,
+} from "../context/context-revision";
+import type { ProtocolContextView } from "../context/protocol-frame";
+
+export class ContextBuilder {
+  build(input: {
+    canonical: ProtocolContextView;
+    revision: StoredContextRevisionV5;
+    activeOverrides: readonly SwapOverride[];
+    compiled: CompiledRevisionContext;
+    tools: readonly ToolDefinition[];
+    candidateUserPrompt?: string;
+  }): BuiltContextRequest {
+    if (input.canonical.sessionId !== input.compiled.sessionId) {
+      throw new Error(
+        "Compiled context and canonical history belong to different sessions.",
+      );
+    }
+    const messages = input.compiled.entries.map((entry) => entry.message);
+    if (input.candidateUserPrompt !== undefined) {
+      if (input.candidateUserPrompt.trim() === "") {
+        throw new Error("Cannot build a candidate context with an empty prompt.");
+      }
+      messages.push({ role: "user", content: input.candidateUserPrompt });
+    }
+    return Object.freeze({
+      canonical: input.canonical,
+      revision: input.revision,
+      activeOverrides: input.activeOverrides,
+      compiled: input.compiled,
+      request: {
+        messages,
+        tools: [...input.tools],
+      },
+      candidateUserPromptIncluded: input.candidateUserPrompt !== undefined,
+    });
+  }
+}

package/src/agent/context-meter.ts

@@ -0,0 +1,310 @@
+import type { ModelContextBudget } from "../model/model-context-profile";
+import type {
+  ModelRequestOutput,
+  ModelUsage,
+  PreparedModelRequest,
+} from "../model/model-client";
+import {
+  assertContextBudget,
+  contextPressure,
+  type ContextPressure,
+  type ContextUsageSource,
+} from "../model/model-request-preflight";
+import { lastPromptPrefixHash, promptPrefixHashes } from "../model/prompt-prefix-hash";
+import {
+  estimatePromptSegments,
+  RollingTokenCalibration,
+  type RawContextBreakdown,
+} from "../model/token-estimator";
+
+export type MeasuredContextAnchor = {
+  readonly totalTokens: number;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly segmentCount: number;
+  readonly prefixHash: string;
+  readonly requestConfigHash: string;
+  readonly toolSchemaHash: string;
+};
+
+export type ContextUsageSnapshot = {
+  usedInputTokens: number;
+  source: ContextUsageSource;
+  pressure: ContextPressure;
+  inputBudgetTokens: number;
+  triggerTokens: number;
+  triggerRatio: number;
+  requestMaxOutputTokens: number;
+  lastProviderUsage?: ModelUsage;
+  rawFullEstimate?: RawContextBreakdown;
+  rawDeltaTokens?: number;
+  guardedDeltaTokens?: number;
+  correctionFactor: number;
+  calibrationSampleCount: number;
+  prefixHash: string;
+  requestConfigHash: string;
+  toolSchemaHash: string;
+};
+
+export type ContextInvalidationReason =
+  | "request_config_changed"
+  | "tool_schema_changed"
+  | "context_rebuilt"
+  | "runtime_reset";
+
+type PreparedMeasurement = {
+  rawFullEstimate: RawContextBreakdown;
+  snapshot: ContextUsageSnapshot;
+};
+
+export class ContextMeter {
+  private readonly calibration = new RollingTokenCalibration();
+  private measurements = new WeakMap<object, PreparedMeasurement>();
+  private anchor?: MeasuredContextAnchor;
+  private lastProviderUsage?: ModelUsage;
+  private calibrationIdentity?: string;
+
+  constructor(
+    private readonly budget: ModelContextBudget,
+    private readonly options: {
+      enableAnchor?: boolean;
+      onMeasuredAnchor?: (anchor: MeasuredContextAnchor) => void;
+    } = {},
+  ) {}
+
+  restoreExactMeasuredAnchor(
+    prepared: PreparedModelRequest,
+    anchor: MeasuredContextAnchor,
+  ): boolean {
+    this.requireMatchingOutputLimit(prepared);
+    this.refreshCalibrationIdentity(prepared);
+    assertMeasuredContextAnchor(anchor);
+
+    const prefixHashes = promptPrefixHashes(
+      prepared.requestConfigHash,
+      prepared.promptSegments,
+    );
+    if (
+      anchor.requestConfigHash !== prepared.requestConfigHash ||
+      anchor.toolSchemaHash !== prepared.toolSchemaHash ||
+      anchor.segmentCount !== prepared.promptSegments.length ||
+      anchor.prefixHash !== lastPromptPrefixHash(prefixHashes)
+    ) {
+      this.anchor = undefined;
+      this.lastProviderUsage = undefined;
+      return false;
+    }
+
+    this.anchor = Object.freeze({ ...anchor });
+    this.lastProviderUsage = {
+      promptTokens: anchor.promptTokens,
+      completionTokens: anchor.completionTokens,
+      totalTokens: anchor.totalTokens,
+    };
+    return true;
+  }
+
+  measure(prepared: PreparedModelRequest): ContextUsageSnapshot {
+    this.requireMatchingOutputLimit(prepared);
+    this.refreshCalibrationIdentity(prepared);
+
+    const rawFullEstimate = estimatePromptSegments(prepared.promptSegments);
+    const correctionFactor = this.calibration.correctionFactor();
+    const prefixHashes = promptPrefixHashes(
+      prepared.requestConfigHash,
+      prepared.promptSegments,
+    );
+    const prefixHash = lastPromptPrefixHash(prefixHashes);
+    const anchor = this.usableAnchor(prepared, prefixHashes);
+
+    let source: ContextUsageSource;
+    let usedInputTokens: number;
+    let rawDeltaTokens: number | undefined;
+    let guardedDeltaTokens: number | undefined;
+    if (anchor === undefined) {
+      source = "estimated_full";
+      usedInputTokens = Math.ceil(rawFullEstimate.totalTokens * correctionFactor);
+    } else {
+      source = "measured_plus_estimated_delta";
+      rawDeltaTokens = estimatePromptSegments(
+        prepared.promptSegments.slice(anchor.segmentCount),
+      ).totalTokens;
+      guardedDeltaTokens = Math.ceil(rawDeltaTokens * correctionFactor);
+      usedInputTokens = anchor.totalTokens + guardedDeltaTokens;
+    }
+
+    const snapshot: ContextUsageSnapshot = {
+      usedInputTokens,
+      source,
+      pressure: contextPressure(usedInputTokens, this.budget),
+      inputBudgetTokens: this.budget.inputBudgetTokens,
+      triggerTokens: this.budget.triggerTokens,
+      triggerRatio: this.budget.triggerRatio,
+      requestMaxOutputTokens: this.budget.requestMaxOutputTokens,
+      ...(this.lastProviderUsage === undefined
+        ? {}
+        : { lastProviderUsage: { ...this.lastProviderUsage } }),
+      rawFullEstimate,
+      ...(rawDeltaTokens === undefined ? {} : { rawDeltaTokens }),
+      ...(guardedDeltaTokens === undefined ? {} : { guardedDeltaTokens }),
+      correctionFactor,
+      calibrationSampleCount: this.calibration.sampleCount(),
+      prefixHash,
+      requestConfigHash: prepared.requestConfigHash,
+      toolSchemaHash: prepared.toolSchemaHash,
+    };
+    this.measurements.set(prepared, { rawFullEstimate, snapshot });
+    return snapshot;
+  }
+
+  recordProviderUsage(
+    prepared: PreparedModelRequest,
+    output: ModelRequestOutput,
+  ): ContextUsageSnapshot {
+    const measurement = this.measurements.get(prepared);
+    if (measurement === undefined) {
+      throw new Error("Cannot record provider usage before measuring the request.");
+    }
+
+    this.calibration.record(
+      output.usage.promptTokens,
+      measurement.rawFullEstimate.totalTokens,
+    );
+    this.lastProviderUsage = { ...output.usage };
+    const replaySegments = prepared.assistantReplaySegments(output.message);
+    const anchoredSegments = [...prepared.promptSegments, ...replaySegments];
+    const prefixHash = lastPromptPrefixHash(
+      promptPrefixHashes(prepared.requestConfigHash, anchoredSegments),
+    );
+    if (this.options.enableAnchor !== false) {
+      const anchor = Object.freeze({
+        totalTokens: output.usage.totalTokens,
+        promptTokens: output.usage.promptTokens,
+        completionTokens: output.usage.completionTokens,
+        segmentCount: anchoredSegments.length,
+        prefixHash,
+        requestConfigHash: prepared.requestConfigHash,
+        toolSchemaHash: prepared.toolSchemaHash,
+      });
+      this.anchor = anchor;
+      this.options.onMeasuredAnchor?.(anchor);
+    }
+
+    const usedInputTokens = output.usage.totalTokens;
+    return {
+      usedInputTokens,
+      source: "provider_measured",
+      pressure: contextPressure(usedInputTokens, this.budget),
+      inputBudgetTokens: this.budget.inputBudgetTokens,
+      triggerTokens: this.budget.triggerTokens,
+      triggerRatio: this.budget.triggerRatio,
+      requestMaxOutputTokens: this.budget.requestMaxOutputTokens,
+      lastProviderUsage: { ...output.usage },
+      rawFullEstimate: measurement.rawFullEstimate,
+      correctionFactor: this.calibration.correctionFactor(),
+      calibrationSampleCount: this.calibration.sampleCount(),
+      prefixHash,
+      requestConfigHash: prepared.requestConfigHash,
+      toolSchemaHash: prepared.toolSchemaHash,
+    };
+  }
+
+  assertWithinBudget(snapshot: ContextUsageSnapshot): void {
+    assertContextBudget({
+      usedInputTokens: snapshot.usedInputTokens,
+      source: snapshot.source,
+      ...this.budget,
+    });
+  }
+
+  startRevision(input: {
+    reason: "context_rebuilt";
+    requestConfigHash: string;
+    toolSchemaHash: string;
+  }): void {
+    const nextIdentity = `${input.requestConfigHash}:${input.toolSchemaHash}`;
+    if (
+      this.calibrationIdentity !== undefined &&
+      this.calibrationIdentity !== nextIdentity
+    ) {
+      this.anchor = undefined;
+      this.lastProviderUsage = undefined;
+      this.measurements = new WeakMap();
+      this.calibration.clear();
+      this.calibrationIdentity = nextIdentity;
+      throw new Error(
+        "Context revision changed the request configuration or tool schema.",
+      );
+    }
+    this.anchor = undefined;
+    this.lastProviderUsage = undefined;
+    this.measurements = new WeakMap();
+    this.calibrationIdentity = nextIdentity;
+  }
+
+  invalidate(reason: ContextInvalidationReason): void {
+    void reason;
+    this.anchor = undefined;
+    this.lastProviderUsage = undefined;
+    this.measurements = new WeakMap();
+    this.calibration.clear();
+    this.calibrationIdentity = undefined;
+  }
+
+  private usableAnchor(
+    prepared: PreparedModelRequest,
+    prefixHashes: readonly string[],
+  ): MeasuredContextAnchor | undefined {
+    const anchor = this.anchor;
+    if (anchor === undefined) {
+      return undefined;
+    }
+    if (
+      anchor.requestConfigHash !== prepared.requestConfigHash ||
+      anchor.toolSchemaHash !== prepared.toolSchemaHash ||
+      anchor.segmentCount > prepared.promptSegments.length ||
+      prefixHashes[anchor.segmentCount] !== anchor.prefixHash
+    ) {
+      this.anchor = undefined;
+      return undefined;
+    }
+    return anchor;
+  }
+
+  private requireMatchingOutputLimit(prepared: PreparedModelRequest): void {
+    if (prepared.requestMaxOutputTokens !== this.budget.requestMaxOutputTokens) {
+      throw new Error(
+        `Prepared request output limit must equal the context budget: expected ${this.budget.requestMaxOutputTokens}, received ${prepared.requestMaxOutputTokens}.`,
+      );
+    }
+  }
+
+  private refreshCalibrationIdentity(prepared: PreparedModelRequest): void {
+    const next = `${prepared.requestConfigHash}:${prepared.toolSchemaHash}`;
+    if (this.calibrationIdentity !== undefined && this.calibrationIdentity !== next) {
+      this.anchor = undefined;
+      this.calibration.clear();
+    }
+    this.calibrationIdentity = next;
+  }
+}
+
+function assertMeasuredContextAnchor(anchor: MeasuredContextAnchor): void {
+  for (const [name, value] of [
+    ["promptTokens", anchor.promptTokens],
+    ["completionTokens", anchor.completionTokens],
+    ["totalTokens", anchor.totalTokens],
+    ["segmentCount", anchor.segmentCount],
+  ] as const) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new Error(
+        `Measured context anchor ${name} must be a non-negative safe integer; received ${value}.`,
+      );
+    }
+  }
+  if (anchor.totalTokens !== anchor.promptTokens + anchor.completionTokens) {
+    throw new Error(
+      "Measured context anchor totalTokens must equal promptTokens + completionTokens.",
+    );
+  }
+}