sandoichi 0.4.0 → 0.4.2

package/README.md

@@ -1,6 +1,6 @@
 # sandoichi
 
-`sandoichi` is Sando's optional JavaScript library. The full Sando plugin is the main product. Install it through the Claude Code or Codex marketplace.
+`sandoichi` is Sando's optional JavaScript library. The marketplace plugin is the main product. Install the plugin through the Claude Code or Codex marketplace.
 
 ```bash
 npm install sandoichi
@@ -24,12 +24,12 @@ Project-specific detectors can be declared in `.sando/redaction.json`:
 
 Built-ins stay enabled. Profiles are declarative and local to the current project; invalid profiles fail visibly.
 
-The library requires Node.js `>=22.22.0 <23` and has no runtime dependencies. Installing it does not install or enable the plugin. The plugin is the supported host surface; this package exports the context/history runtime, provider usage report, paired accounting, and explicit proxy API only.
+The library requires Node.js `>=22.22.0 <23` and has no runtime dependencies. Installing it does not install or enable the plugin. The plugin remains the supported host surface; this package exports the bounded output/disclosure runtime, context footprint audit, F1/F3/F4 evidence APIs, provider usage report, paired accounting, and explicit proxy API. Host hooks and MCP registration remain outside the package API.
 
-`computeWeightedUsage` and `summarizePairedSessions` keep mechanical reduction, weighted estimates, provider-reported cost, and paired-session evidence distinct. The benchmark report adds explicit replay counterfactuals. The library does not install hooks, register MCP servers, or make routing/backoff decisions for a host.
+`computeWeightedUsage` and `summarizePairedSessions` keep mechanical reduction, weighted estimates, provider-reported cost, and paired-session evidence separate. The library does not install hooks, register MCP servers, or make routing/backoff decisions for a host.
 
 For plugin installation, see the [main project README](https://github.com/yuzushi-dev/Sando#readme).
 
 Telemetry is off by default. An interactive npm install asks once for consent; see the [full disclosure](https://github.com/yuzushi-dev/Sando/blob/main/TELEMETRY.md).
 
-MIT.
+License: MIT.

package/index.mjs

@@ -56,7 +56,77 @@ export {
   PROVIDER_USAGE_VERSION,
 } from './src/provider-usage.mjs';
 export { planToolRoute, ROUTING_POLICY_VERSION } from './src/routing.mjs';
+export {
+  CONTEXT_CAPTURE_SCHEMA,
+  CONTEXT_CATEGORIES,
+  CONTEXT_FOOTPRINT_SCHEMA,
+  CONTEXT_FOOTPRINT_VERSION,
+  buildContextFootprintReport,
+  detectToolSearchState,
+  serializeContextFootprint,
+} from './src/context-footprint.mjs';
+export { classifyContextRequest } from './src/context-classifier.mjs';
+export { formatContextFootprintReport, runContextAuditCli } from './src/context-audit-cli.mjs';
+export {
+  CONTEXT_CAPTURE_RECORD_SCHEMA,
+  CONTEXT_CAPTURE_RECORD_VERSION,
+  buildContextCaptureRecord,
+  defaultContextCapturePath,
+  normalizeProviderUsage,
+  recordContextCapture,
+} from './src/context-capture.mjs';
+export {
+  ARTIFACT_TOOL_NAME,
+  RESULT_DISCLOSURE_SCHEMA,
+  RESULT_DISCLOSURE_VERSION,
+  buildResultDisclosure,
+  serializeResultDisclosure,
+} from './src/result-disclosure.mjs';
+export {
+  ARTIFACT_RECOVERY_SCHEMA,
+  ARTIFACT_RECOVERY_VERSION,
+  MAX_RECOVERY_BYTES,
+  recoverArtifactContent,
+  recoverArtifactFromWorkspace,
+} from './src/artifact-recovery.mjs';
+export { runArtifactCli } from './src/artifact-cli.mjs';
+export { buildF1TelemetryEvent, publishF1Telemetry } from './src/f1-telemetry.mjs';
+export {
+  F4_EVENT_SCHEMA,
+  F4_EVENT_VERSION,
+  F4_HOSTS,
+  F4_LATENCY_BUCKETS,
+  F4_OPERATIONS,
+  F4_OUTCOMES,
+  F4_RESULT_BUCKETS,
+  buildF4Event,
+  buildF4TelemetryEvent,
+  defaultF4EventsPath,
+  DEFAULT_F4_TELEMETRY_ENDPOINT,
+  digestCapability,
+  latencyBucket,
+  publishF4Telemetry,
+  recordF4Event,
+  resultBucket,
+  serializeF4Event,
+} from './src/f4-telemetry.mjs';
+export {
+  GATE_EVIDENCE_SCHEMA,
+  GATE_SCHEMA,
+  GATE_THRESHOLDS,
+  GATE_VERSION,
+  evaluateGatewayGate,
+  serializeGatewayGate,
+} from './src/gateway-gate.mjs';
+export {
+  HISTORY_DISCLOSURE_SCHEMA,
+  HISTORY_DISCLOSURE_VERSION,
+  buildHistoryDisclosure,
+  serializeHistoryDisclosure,
+} from './src/history-disclosure.mjs';
 export { readStatusSnapshot, renderStatusLine, STATUSLINE_MAX_AGE_MS } from './src/statusline.mjs';
+export { GATEWAY_CATALOG_TOOL, LAZY_MCP_GATEWAY_SCHEMA, createLazyMcpGateway, validateJsonSchema } from './src/lazy-mcp-gateway.mjs';
+export { createConfiguredMcpServers, spawnMcpTransport, startLazyMcpGatewayStdio } from './src/lazy-mcp-gateway-stdio.mjs';
 export {
   activeSessionForPane,
   currentTmuxPanePid,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandoichi",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Bound repeated tool-output context in Claude Code and Codex with deterministic local routing and provider accounting.",
   "license": "MIT",
   "author": "yuzushi",

package/src/artifact-cli.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { recoverArtifactFromWorkspace } from './artifact-recovery.mjs';
+
+function usage() {
+  return 'Usage: sando artifact get --ref HANDLE [--root DIR] [--start-byte N --end-byte N | --start-line N --end-line N] [--max-bytes N] [--json]\n';
+}
+
+function number(value, name) {
+  if (!/^\d+$/.test(value ?? '')) throw new Error(`${name} must be a non-negative integer`);
+  const result = Number(value);
+  if (!Number.isSafeInteger(result)) throw new Error(`${name} is too large`);
+  return result;
+}
+
+function parseArgs(argv) {
+  let args = [...argv];
+  if (args[0] === 'artifact') args = args.slice(1);
+  if (args[0] === 'get') args = args.slice(1);
+  const result = { root: process.cwd(), json: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--json') result.json = true;
+    else if (argument === '--help' || argument === '-h') result.help = true;
+    else if (['--root', '--ref', '--start-byte', '--end-byte', '--start-line', '--end-line', '--max-bytes'].includes(argument)) {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value`);
+      const key = argument.slice(2).replaceAll('-', '');
+      result[key] = ['startbyte', 'endbyte', 'startline', 'endline', 'maxbytes'].includes(key)
+        ? number(value, argument)
+        : value;
+      index += 1;
+    } else throw new Error('unknown artifact option');
+  }
+  if (!result.help && !result.ref) throw new Error('--ref is required');
+  if (!result.help && ((result.startbyte !== undefined) !== (result.endbyte !== undefined)
+    || (result.startline !== undefined) !== (result.endline !== undefined))) throw new Error('artifact ranges require start and end');
+  return result;
+}
+
+function terminal(report) {
+  return `Sando artifact ${report.handle}: ${report.bytes}B${report.truncated ? ' (bounded)' : ''}\n${report.content}\n`;
+}
+
+export function runArtifactCli({ argv = process.argv.slice(2), stdout = process.stdout, stderr = process.stderr } = {}) {
+  try {
+    const options = parseArgs(argv);
+    if (options.help) { stdout.write(usage()); return null; }
+    const report = recoverArtifactFromWorkspace({
+      cwd: path.resolve(options.root), ref: options.ref,
+      ...(options.startbyte !== undefined ? { startByte: options.startbyte, endByte: options.endbyte } : {}),
+      ...(options.startline !== undefined ? { startLine: options.startline, endLine: options.endline } : {}),
+      ...(options.maxbytes !== undefined ? { maxBytes: options.maxbytes } : {}),
+    });
+    stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : terminal(report));
+    return report;
+  } catch (error) {
+    stderr.write(`sando artifact get: ${error instanceof Error ? error.message : String(error)}\n${usage()}`);
+    process.exitCode = 2;
+    return null;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) runArtifactCli();

package/src/artifact-recovery.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+export const ARTIFACT_RECOVERY_SCHEMA = 'sando-artifact-recovery/v1';
+export const ARTIFACT_RECOVERY_VERSION = 1;
+export const MAX_RECOVERY_BYTES = 1_048_576;
+const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+function digest(text) {
+  return `sha256:${createHash('sha256').update(text).digest('hex')}`;
+}
+
+function handleDigest(ref) {
+  const match = typeof ref === 'string' && ref.match(/^sando:(sha256:[a-f0-9]{16,64})$/);
+  if (!match) throw new TypeError('artifact handle is invalid');
+  return match[1];
+}
+
+function integer(value, name, { positive = false } = {}) {
+  if (!Number.isSafeInteger(value) || value < (positive ? 1 : 0)) throw new TypeError(`${name} is invalid`);
+  return value;
+}
+
+function continuation(byte) { return (byte & 0xc0) === 0x80; }
+
+function safeBufferText(buffer, start, end) {
+  if (start > 0 && continuation(buffer[start])) throw new RangeError('byte range splits UTF-8');
+  if (end < buffer.length && continuation(buffer[end])) throw new RangeError('byte range splits UTF-8');
+  return buffer.subarray(start, end).toString('utf8');
+}
+
+function prefix(buffer, limit) {
+  let end = Math.min(buffer.length, limit);
+  while (end > 0 && end < buffer.length && continuation(buffer[end])) end -= 1;
+  return { text: buffer.subarray(0, end).toString('utf8'), truncated: end < buffer.length };
+}
+
+export function recoverArtifactContent({
+  ref, content, digest: expectedDigest, sourceBytes, startByte, endByte, startLine, endLine, maxBytes,
+} = {}) {
+  const handlePrefix = handleDigest(ref).slice('sha256:'.length);
+  const handle = ref;
+  if (typeof content !== 'string') throw new TypeError('artifact content is invalid');
+  const actualDigest = digest(content);
+  if (expectedDigest !== undefined && expectedDigest !== actualDigest) throw new Error('artifact digest integrity check failed');
+  const full = Buffer.from(content, 'utf8');
+  if (!actualDigest.slice('sha256:'.length).startsWith(handlePrefix)) throw new Error('artifact handle does not match content');
+  const limit = maxBytesValue(maxBytes);
+  const byteMode = startByte !== undefined || endByte !== undefined;
+  const lineMode = startLine !== undefined || endLine !== undefined;
+  if (byteMode && lineMode) throw new TypeError('artifact range is ambiguous');
+  let selected;
+  let range;
+  if (byteMode) {
+    const start = integer(startByte ?? 0, 'startByte');
+    const end = integer(endByte ?? full.length, 'endByte');
+    if (start > end || end > full.length) throw new RangeError('artifact byte range is invalid');
+    selected = safeBufferText(full, start, end);
+    range = { type: 'bytes', start, end };
+  } else if (lineMode) {
+    const start = integer(startLine ?? 1, 'startLine', { positive: true });
+    const end = integer(endLine ?? start, 'endLine', { positive: true });
+    const lines = content.split('\n');
+    if (start > end || start > lines.length || end > lines.length) throw new RangeError('artifact line range is invalid');
+    selected = lines.slice(start - 1, end).join('\n');
+    range = { type: 'lines', start, end };
+  } else {
+    selected = content;
+    range = { type: 'all' };
+  }
+  const selectedBuffer = Buffer.from(selected, 'utf8');
+  const bounded = prefix(selectedBuffer, limit);
+  const totalSourceBytes = integer(sourceBytes ?? full.length, 'sourceBytes');
+  if (totalSourceBytes !== full.length) throw new Error('artifact source byte metadata is inconsistent');
+  return {
+    schema: ARTIFACT_RECOVERY_SCHEMA,
+    version: ARTIFACT_RECOVERY_VERSION,
+    handle,
+    digest: actualDigest,
+    content: bounded.text,
+    bytes: Buffer.byteLength(bounded.text),
+    sourceBytes: totalSourceBytes,
+    range,
+    truncated: bounded.truncated,
+  };
+}
+
+function maxBytesValue(value) {
+  const result = value ?? 65_536;
+  integer(result, 'maxBytes', { positive: true });
+  if (result > MAX_RECOVERY_BYTES) throw new RangeError('maxBytes exceeds recovery limit');
+  return result;
+}
+
+function safeDirectory(target, name) {
+  const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+  if (!stat || !stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`${name} is unavailable or unsafe`);
+}
+
+export function recoverArtifactFromWorkspace({ cwd, ref, ...range } = {}) {
+  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) throw new TypeError('artifact cwd is invalid');
+  const root = fs.realpathSync(cwd);
+  if (!fs.statSync(root).isDirectory()) throw new TypeError('artifact cwd is not a directory');
+  const stateRoot = path.join(root, '.sando');
+  const privateRoot = path.join(stateRoot, 'sando');
+  const directory = path.join(privateRoot, 'artifacts');
+  safeDirectory(stateRoot, 'artifact state');
+  safeDirectory(privateRoot, 'artifact private state');
+  safeDirectory(directory, 'artifact directory');
+  const digestPrefix = handleDigest(ref).slice('sha256:'.length);
+  const candidates = fs.readdirSync(directory)
+    .filter((entry) => /^[a-f0-9]{64}\.txt$/.test(entry) && entry.startsWith(digestPrefix));
+  if (candidates.length !== 1) throw new Error(candidates.length ? 'artifact handle is ambiguous' : 'artifact handle is unavailable');
+  const digestValue = `sha256:${candidates[0].slice(0, -'.txt'.length)}`;
+  const target = path.join(directory, candidates[0]);
+  const relative = path.relative(directory, target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('artifact path escapes directory');
+  let descriptor;
+  try {
+    descriptor = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile()) throw new Error('artifact handle is unavailable');
+    if (stat.size > MAX_ARTIFACT_BYTES) throw new RangeError('artifact exceeds recovery limit');
+    const content = new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(descriptor));
+    return recoverArtifactContent({ ref, content, digest: digestValue, ...range });
+  } catch (error) {
+    if (['ELOOP', 'ENOENT'].includes(error?.code)) throw new Error('artifact handle is unavailable', { cause: error });
+    throw error;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}

package/src/artifact-store.mjs

@@ -0,0 +1,43 @@
+import { recoverArtifactContent } from './artifact-recovery.mjs';
+
+const MAX_ARTIFACTS = 128;
+const MAX_STORED_BYTES = 64 * 1024 * 1024;
+const store = new Map();
+let storedBytes = 0;
+
+export function rememberArtifact(artifact) {
+  if (!artifact || typeof artifact.ref !== 'string' || typeof artifact.content !== 'string') throw new TypeError('artifact is invalid');
+  const bytes = Buffer.byteLength(artifact.content);
+  if (bytes > MAX_STORED_BYTES) throw new RangeError('artifact exceeds in-process recovery limit');
+  const previous = store.get(artifact.ref);
+  if (previous) storedBytes -= previous.bytes;
+  store.delete(artifact.ref);
+  while (store.size >= MAX_ARTIFACTS || storedBytes + bytes > MAX_STORED_BYTES) {
+    const oldest = store.keys().next().value;
+    if (oldest === undefined) break;
+    storedBytes -= store.get(oldest).bytes;
+    store.delete(oldest);
+  }
+  store.set(artifact.ref, {
+    content: artifact.content,
+    digest: artifact.sourceDigest,
+    sourceBytes: artifact.sourceBytes ?? artifact.bytes,
+    bytes,
+  });
+  storedBytes += bytes;
+}
+
+export function recoverStoredArtifact(options = {}) {
+  const entry = store.get(options.ref);
+  if (!entry) throw new Error('artifact handle is unavailable in this MCP session');
+  store.delete(options.ref);
+  store.set(options.ref, entry);
+  return recoverArtifactContent({ ...options, ...entry });
+}
+
+export function exposeMcpResult(result) {
+  if (!result?.artifact) return result;
+  rememberArtifact(result.artifact);
+  const { content: _content, ...artifact } = result.artifact;
+  return { ...result, artifact };
+}

package/src/context-audit-cli.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  CONTEXT_CAPTURE_SCHEMA,
+  buildContextFootprintReport,
+} from './context-footprint.mjs';
+
+const MAX_CAPTURE_BYTES = 8 * 1024 * 1024;
+
+function usage() {
+  return 'Usage: sando context audit --host claude|codex [--input CAPTURE.json] [--json]\n';
+}
+
+function parseArgs(argv) {
+  let args = [...argv];
+  if (args[0] === 'context') args = args.slice(1);
+  if (args[0] === 'audit') args = args.slice(1);
+  const result = { host: undefined, input: undefined, json: false, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--help' || argument === '-h') result.help = true;
+    else if (argument === '--json') result.json = true;
+    else if (argument === '--host' || argument === '--input') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value`);
+      result[argument.slice(2)] = value;
+      index += 1;
+    } else throw new Error('unknown context audit option');
+  }
+  if (!result.help && !result.host) throw new Error('--host is required');
+  return result;
+}
+
+function readCapture(inputPath) {
+  let descriptor;
+  try {
+    descriptor = fs.openSync(inputPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > MAX_CAPTURE_BYTES) throw new Error('capture input is too large or not a file');
+    const source = fs.readFileSync(descriptor, 'utf8');
+    if (Buffer.byteLength(source, 'utf8') > MAX_CAPTURE_BYTES) throw new Error('capture input is too large');
+    try {
+      return JSON.parse(source);
+    } catch {
+      throw new Error('capture JSON is invalid');
+    }
+  } catch (error) {
+    if (error?.message === 'capture JSON is invalid' || error?.message === 'capture input is too large or not a file'
+      || error?.message === 'capture input is too large') throw error;
+    throw new Error('capture input cannot be read');
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+function unavailableCapture(host) {
+  return { schema: CONTEXT_CAPTURE_SCHEMA, host, body: { state: 'unavailable' } };
+}
+
+export function formatContextFootprintReport(report) {
+  const attribution = report.attribution.status === 'unavailable'
+    ? 'unavailable'
+    : `${report.attribution.status} (${report.attribution.bodyBytes}B, unknown ${report.attribution.unknownBytes}B)`;
+  const estimated = report.tokenAccounting.estimated.totalTokens === null
+    ? 'unavailable'
+    : String(report.tokenAccounting.estimated.totalTokens);
+  const provider = report.tokenAccounting.providerReported?.inputTokens === undefined
+    ? 'unavailable'
+    : String(report.tokenAccounting.providerReported.inputTokens);
+  return [
+    `Sando context audit: ${report.host}/${report.requestFormat ?? 'format unavailable'}`,
+    `body: ${report.observation.status}`,
+    `attribution: ${attribution}`,
+    `tool search: ${report.toolSearch.state}`,
+    `estimated input tokens: ${estimated}`,
+    `provider input tokens: ${provider}`,
+    `provenance: ${report.provenanceDigest}`,
+  ].join('\n') + '\n';
+}
+
+export function runContextAuditCli({ argv = process.argv.slice(2), stdout = process.stdout, stderr = process.stderr } = {}) {
+  try {
+    const options = parseArgs(argv);
+    if (options.help) {
+      stdout.write(usage());
+      return null;
+    }
+    const capture = options.input ? readCapture(options.input) : unavailableCapture(options.host);
+    if (capture?.host !== options.host) throw new Error('capture host does not match --host');
+    const report = buildContextFootprintReport(capture);
+    stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : formatContextFootprintReport(report));
+    return report;
+  } catch (error) {
+    stderr.write(`sando context audit: ${error instanceof Error ? error.message : String(error)}\n${usage()}`);
+    process.exitCode = 2;
+    return null;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) runContextAuditCli();

package/src/context-capture.mjs

@@ -0,0 +1,200 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  CONTEXT_CAPTURE_SCHEMA,
+  buildContextFootprintReport,
+  serializeContextFootprint,
+} from './context-footprint.mjs';
+import { classifyContextRequest } from './context-classifier.mjs';
+
+export const CONTEXT_CAPTURE_RECORD_SCHEMA = 'sando-context-capture-record/v1';
+export const CONTEXT_CAPTURE_RECORD_VERSION = 1;
+
+const PROVIDER_FORMATS = Object.freeze({
+  anthropic: { host: 'claude', requestFormat: 'anthropic' },
+  'openai-responses': { host: 'codex', requestFormat: 'openai-responses' },
+});
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function counter(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function add(left, right) {
+  const result = left + right;
+  return Number.isSafeInteger(result) ? result : null;
+}
+
+function optionalCounter(value) {
+  return value === undefined || value === null ? 0 : counter(value);
+}
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function isoDate(value) {
+  const date = value instanceof Date ? value : new Date(value ?? Date.now());
+  if (Number.isNaN(date.getTime())) throw new TypeError('capture timestamp is invalid');
+  return date.toISOString();
+}
+
+function safeModel(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'string' || value.length > 256) throw new TypeError('capture model is invalid');
+  return value;
+}
+
+function rawText(value) {
+  if (typeof value === 'string') return value;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value).toString('utf8');
+  throw new TypeError('raw request body is invalid');
+}
+
+function anthropicUsage(value) {
+  if (!object(value)) return null;
+  const input = counter(value.input_tokens);
+  const cacheRead = optionalCounter(value.cache_read_input_tokens);
+  const cacheWrite = optionalCounter(value.cache_creation_input_tokens);
+  const output = counter(value.output_tokens);
+  if (input === null || cacheRead === null || cacheWrite === null || output === null) return null;
+  const inputTokens = add(add(input, cacheRead), cacheWrite);
+  const totalTokens = inputTokens === null ? null : add(inputTokens, output);
+  if (totalTokens === null) return null;
+  const result = {
+    inputTokens,
+    cachedInputTokens: cacheRead,
+    cacheWriteInputTokens: cacheWrite,
+    cacheReadInputTokens: cacheRead,
+    outputTokens: output,
+    totalTokens,
+  };
+  if (counter(value.reasoning_output_tokens) !== null) result.reasoningOutputTokens = value.reasoning_output_tokens;
+  if (typeof value.total_cost_usd === 'number' && Number.isFinite(value.total_cost_usd) && value.total_cost_usd >= 0) {
+    result.totalCostUsd = value.total_cost_usd;
+  }
+  return result;
+}
+
+function responsesUsage(value) {
+  if (!object(value)) return null;
+  const input = counter(value.input_tokens);
+  const output = counter(value.output_tokens);
+  const cached = optionalCounter(value.cached_input_tokens
+    ?? value.cache_read_input_tokens
+    ?? value.input_tokens_details?.cached_tokens);
+  const cacheWrite = optionalCounter(value.cache_write_input_tokens);
+  const reasoning = optionalCounter(value.reasoning_output_tokens
+    ?? value.output_tokens_details?.reasoning_tokens);
+  if ([input, output, cached, cacheWrite, reasoning].some((item) => item === null)
+    || reasoning > output) return null;
+  const totalTokens = value.total_tokens === undefined ? add(input, output) : counter(value.total_tokens);
+  if (totalTokens === null || totalTokens !== input + output) return null;
+  const result = {
+    inputTokens: input,
+    cachedInputTokens: cached,
+    cacheWriteInputTokens: cacheWrite,
+    cacheReadInputTokens: cached,
+    outputTokens: output,
+    reasoningOutputTokens: reasoning,
+    totalTokens,
+  };
+  if (typeof value.total_cost_usd === 'number' && Number.isFinite(value.total_cost_usd) && value.total_cost_usd >= 0) {
+    result.totalCostUsd = value.total_cost_usd;
+  }
+  return result;
+}
+
+export function normalizeProviderUsage(provider, usage) {
+  if (usage === undefined || usage === null) return null;
+  if (provider === 'anthropic') return anthropicUsage(usage);
+  if (provider === 'openai-responses') return responsesUsage(usage);
+  return null;
+}
+
+export function defaultContextCapturePath(env = process.env) {
+  const configured = env.SANDO_CONTEXT_FOOTPRINT_PATH;
+  if (configured !== undefined) {
+    if (typeof configured !== 'string' || !path.isAbsolute(configured)) throw new Error('context capture path must be absolute');
+    return configured;
+  }
+  const stateHome = env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
+  if (!path.isAbsolute(stateHome)) throw new Error('state directory must be absolute');
+  return path.join(stateHome, 'sando', 'context-footprints.jsonl');
+}
+
+export function buildContextCaptureRecord({
+  host, provider, rawBody, requestBody, sessionKey, model, providerUsage, now = new Date(), toolSearch,
+} = {}) {
+  const format = PROVIDER_FORMATS[provider];
+  if (!format || host !== format.host) throw new TypeError('provider and capture host do not match');
+  if (typeof sessionKey !== 'string' || sessionKey.length === 0) return null;
+  const content = rawText(rawBody);
+  let body = requestBody;
+  if (body === undefined) {
+    try { body = JSON.parse(content); } catch { body = null; }
+  }
+  const classification = classifyContextRequest({ provider, body });
+  const report = buildContextFootprintReport({
+    schema: CONTEXT_CAPTURE_SCHEMA,
+    host,
+    requestFormat: format.requestFormat,
+    body: { state: 'observed', content },
+    segments: classification.segments,
+    providerUsage: normalizeProviderUsage(provider, providerUsage),
+    toolSearch: toolSearch ?? { state: 'indeterminate' },
+  });
+  return {
+    schema: CONTEXT_CAPTURE_RECORD_SCHEMA,
+    version: CONTEXT_CAPTURE_RECORD_VERSION,
+    at: isoDate(now),
+    host,
+    provider,
+    requestFormat: format.requestFormat,
+    model: safeModel(model),
+    sessionKeyDigest: sha256(sessionKey),
+    report,
+  };
+}
+
+function ensureDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('context capture directory is unsafe');
+  fs.chmodSync(directory, 0o700);
+}
+
+function validateRecord(record) {
+  if (!object(record)
+    || record.schema !== CONTEXT_CAPTURE_RECORD_SCHEMA
+    || record.version !== CONTEXT_CAPTURE_RECORD_VERSION
+    || typeof record.at !== 'string'
+    || typeof record.host !== 'string'
+    || typeof record.provider !== 'string'
+    || typeof record.requestFormat !== 'string'
+    || !/^sha256:[0-9a-f]{64}$/.test(record.sessionKeyDigest)
+    || !object(record.report)
+    || record.report.schema !== 'sando-context-footprint/v1') {
+    throw new TypeError('context capture record is invalid');
+  }
+  serializeContextFootprint(record.report);
+}
+
+export function recordContextCapture({ storagePath, record } = {}) {
+  if (typeof storagePath !== 'string' || !path.isAbsolute(storagePath)) throw new Error('context capture path must be absolute');
+  validateRecord(record);
+  ensureDirectory(path.dirname(storagePath));
+  if (fs.existsSync(storagePath)) {
+    const stat = fs.lstatSync(storagePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('context capture file is unsafe');
+  }
+  fs.appendFileSync(storagePath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  fs.chmodSync(storagePath, 0o600);
+  return record;
+}