sandoichi 0.4.2 → 0.5.0

package/README.md

@@ -26,7 +26,11 @@ Built-ins stay enabled. Profiles are declarative and local to the current projec
 
 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 separate. The library does not install hooks, register MCP servers, or make routing/backoff decisions for a host.
+The provider proxy is pass-through unless request transformation is explicitly enabled.
+
+The recoverable-history strategy is opt-in and keeps eligible results inline when they are below 3,072 bytes by default. Provider-boundary replay measurements are diagnostic paired evidence; they do not predict end-to-end agent behavior or provider billing across workloads.
+
+`computeWeightedUsage` and `summarizePairedSessions` keep mechanical reduction, weighted cost units, and paired-session evidence separate from the provider-usage report's reported cost provenance and coverage. Host-reported list estimates are not billed-cost records. 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).
 

package/index.mjs

@@ -90,6 +90,11 @@ export {
   recoverArtifactFromWorkspace,
 } from './src/artifact-recovery.mjs';
 export { runArtifactCli } from './src/artifact-cli.mjs';
+export {
+  DEFAULT_ARTIFACT_MAX_BYTES,
+  DEFAULT_ARTIFACT_TTL_MS,
+  cleanupArtifacts,
+} from './src/artifact-lifecycle.mjs';
 export { buildF1TelemetryEvent, publishF1Telemetry } from './src/f1-telemetry.mjs';
 export {
   F4_EVENT_SCHEMA,

package/package.json

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

package/src/accounting-cli.mjs

@@ -21,7 +21,7 @@ export function formatAccountingReport(report) {
     `reasoning: ${report.reasoningOutputTokens}`,
     `turns: ${report.turnCount}`,
     `weighted estimate: ${report.weightedCost.costUnits} cost units`,
-    `provider cost: ${report.cost.status === 'provider-reported' ? `$${report.cost.totalCostUsd.toFixed(6)}` : report.cost.status}`,
+    `reported cost: ${report.cost.totalCostUsd === null ? report.cost.status : `$${report.cost.totalCostUsd.toFixed(6)} (${report.cost.status})`}`,
   ];
   if (report.cost.effectiveRateUsdPerMillionTokens !== null) {
     lines.push(`blended effective rate: $${report.cost.effectiveRateUsdPerMillionTokens.toFixed(2)}/M tokens`);

package/src/artifact-lifecycle.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_ARTIFACT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const DEFAULT_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024;
+
+function validNumber(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${name} is invalid`);
+  return value;
+}
+
+function safeArtifact(directory, name) {
+  if (!/^[a-f0-9]{64}\.txt$/.test(name)) return null;
+  const target = path.join(directory, name);
+  let link;
+  try { link = fs.lstatSync(target); } catch { return null; }
+  if (!link.isFile() || link.isSymbolicLink()) return null;
+  let resolved;
+  try { resolved = fs.realpathSync(target); } catch { return null; }
+  if (resolved !== target) return null;
+  let stat;
+  try { stat = fs.statSync(target); } catch { return null; }
+  return { target, name, bytes: stat.size, mtimeMs: stat.mtimeMs };
+}
+
+export function cleanupArtifacts(
+  directory,
+  {
+    now = Date.now(), ttlMs = DEFAULT_ARTIFACT_TTL_MS,
+    maxBytes = DEFAULT_ARTIFACT_MAX_BYTES, preserveName = null,
+  } = {},
+) {
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) throw new TypeError('artifact directory is invalid');
+  validNumber(now, 'now');
+  validNumber(ttlMs, 'ttlMs');
+  validNumber(maxBytes, 'maxBytes');
+  if (preserveName !== null && !/^[a-f0-9]{64}\.txt$/.test(preserveName)) {
+    throw new TypeError('preserveName is invalid');
+  }
+  const directoryStat = fs.lstatSync(directory, { throwIfNoEntry: false });
+  if (!directoryStat?.isDirectory() || directoryStat.isSymbolicLink()) throw new Error('artifact directory is unsafe');
+
+  const entries = fs.readdirSync(directory).map((name) => safeArtifact(directory, name)).filter(Boolean);
+  const expired = entries.filter((entry) => now - entry.mtimeMs >= ttlMs);
+  const keep = entries.filter((entry) => !expired.includes(entry));
+  let totalBytes = keep.reduce((total, entry) => total + entry.bytes, 0);
+  const removals = [...expired, ...keep.sort((left, right) => {
+    if (left.name === preserveName) return 1;
+    if (right.name === preserveName) return -1;
+    return left.mtimeMs - right.mtimeMs || left.name.localeCompare(right.name);
+  })];
+  let removed = 0;
+  let removedBytes = 0;
+  for (const entry of removals) {
+    if (expired.includes(entry) || totalBytes > maxBytes) {
+      try {
+        const current = safeArtifact(directory, entry.name);
+        if (!current || current.target !== entry.target) continue;
+        fs.rmSync(current.target);
+        removed += 1;
+        removedBytes += current.bytes;
+        if (!expired.includes(entry)) totalBytes -= current.bytes;
+      } catch { /* cleanup is best-effort and never follows unresolved targets */ }
+    }
+  }
+  return { removed, removedBytes, retainedBytes: Math.max(0, totalBytes) };
+}

package/src/artifact-recovery.mjs

@@ -17,6 +17,11 @@ function handleDigest(ref) {
   return match[1];
 }
 
+export function validateArtifactHandle(ref) {
+  handleDigest(ref);
+  return ref;
+}
+
 function integer(value, name, { positive = false } = {}) {
   if (!Number.isSafeInteger(value) || value < (positive ? 1 : 0)) throw new TypeError(`${name} is invalid`);
   return value;

package/src/artifact-store.mjs

@@ -1,4 +1,4 @@
-import { recoverArtifactContent } from './artifact-recovery.mjs';
+import { recoverArtifactContent, validateArtifactHandle } from './artifact-recovery.mjs';
 
 const MAX_ARTIFACTS = 128;
 const MAX_STORED_BYTES = 64 * 1024 * 1024;
@@ -28,6 +28,7 @@ export function rememberArtifact(artifact) {
 }
 
 export function recoverStoredArtifact(options = {}) {
+  validateArtifactHandle(options.ref);
   const entry = store.get(options.ref);
   if (!entry) throw new Error('artifact handle is unavailable in this MCP session');
   store.delete(options.ref);

package/src/cache-attribution.mjs

@@ -45,6 +45,10 @@ function counter(value) {
   return Number.isSafeInteger(value) && value >= 0 ? value : 0;
 }
 
+function validCounter(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
 /** Stable digest of a JSON-serializable value. Order-sensitive by design: a reordered
  * tool array is a different byte prefix to the provider even if the set is equal. */
 export function shapeDigest(value) {
@@ -88,7 +92,9 @@ export function hasBreakpoint(body) {
  *
  * `current` / `previous` are `{ at, usage, tools, system, messages, body }`, where
  * `usage` is `{ cachedInputTokens, cacheWriteInputTokens, inputTokens }` as recorded
- * in the provider ledger. `previous` is null on the first turn of a session.
+ * in the provider ledger. `inputTokens` is the complete prompt, including cache
+ * reads and writes; `promptTokens` is accepted as its clearer alias. `previous` is
+ * null on the first turn of a session.
  */
 export function attributeTurn({
   current,
@@ -101,8 +107,10 @@ export function attributeTurn({
   const usage = object(current.usage) ? current.usage : {};
   const cacheReadTokens = counter(usage.cachedInputTokens);
   const cacheWriteTokens = counter(usage.cacheWriteInputTokens);
-  const freshInputTokens = counter(usage.inputTokens);
-  const totalPromptTokens = cacheReadTokens + cacheWriteTokens + freshInputTokens;
+  const promptTokens = validCounter(usage.promptTokens) ?? counter(usage.inputTokens);
+  const totalPromptTokens = promptTokens;
+  const effectiveInputTokens = Math.max(0, promptTokens - cacheReadTokens);
+  const freshInputTokens = Math.max(0, promptTokens - cacheReadTokens - cacheWriteTokens);
   const hit = cacheReadTokens > 0;
 
   const currentDigests = messageDigests(current.messages);
@@ -112,6 +120,8 @@ export function attributeTurn({
   const detail = {
     cacheReadTokens,
     cacheWriteTokens,
+    promptTokens,
+    effectiveInputTokens,
     freshInputTokens,
     totalPromptTokens,
     divergedAtMessage: divergedAt,

package/src/context-transform.mjs

@@ -1,9 +1,13 @@
+import path from 'node:path';
+
 import { estimateTokens } from './core.mjs';
 import { dedupeHistory } from './history-dedupe.mjs';
 import { selectHistoryCandidates, validateMaxHistoryTokens } from './history-budget.mjs';
 import { shakeHistoricalResult } from './history-shake.mjs';
 import { compactHistoricalStructure } from './history-structure.mjs';
 import { buildHistoryDisclosure } from './history-disclosure.mjs';
+import { prepareHistoryArtifact, persistHistoryArtifact } from './history-archive.mjs';
+import { createRedactionProfile } from './redaction-profile.mjs';
 
 const SUPERSEDED = '[sando superseded by newer read]';
 const USELESS = '[sando elided useless success]';
@@ -12,6 +16,11 @@ const USELESS_SUCCESSES = new Set([
   'no output.',
   '(no output)',
 ]);
+const DEFAULT_REDACTION_PROFILE = createRedactionProfile();
+const DEFAULT_HISTORY_ARCHIVE_RETAIN_RESULTS = 3;
+// A marker is useful only when the historical observation is materially larger
+// than the recovery instructions it replaces. Small results stay inline.
+const DEFAULT_HISTORY_ARCHIVE_MIN_BYTES = 3072;
 
 function object(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -76,10 +85,35 @@ function resultError(item, text) {
   return /^\s*(?:error|failed|failure)\b[:\s-]*/i.test(text);
 }
 
+function resultSuccess(item, provider, text) {
+  if (resultError(item, text)) return false;
+  if (provider === 'anthropic') return item.is_error !== true;
+  return item.ok === true || ['completed', 'success', 'succeeded'].includes(item.status);
+}
+
+function nativeCodexExecSafety(provider, call, record) {
+  const item = record.entry.item;
+  const output = item[record.entry.key];
+  if (provider !== 'openai-responses' || call?.providerType !== 'function_call'
+    || call.name !== 'exec_command' || item.type !== 'function_call_output') return null;
+  if (typeof output !== 'string') return false;
+  if (item.error !== undefined || item.is_error === true || item.ok === false
+    || (item.status !== undefined && !['completed', 'success', 'succeeded'].includes(item.status))) return false;
+  const lines = output.split(/\r?\n/);
+  const outputLine = lines.indexOf('Output:');
+  if (outputLine < 0) return false;
+  const exits = lines.slice(0, outputLine).filter((line) => line.startsWith('Process exited with code '));
+  return exits.length === 1 && exits[0] === 'Process exited with code 0';
+}
+
 function useless(text) {
   return USELESS_SUCCESSES.has(text.trim().toLowerCase());
 }
 
+function historyArchiveMarker(text) {
+  return /^\[sando archived result sando:sha256:[a-f0-9]{64}; /.test(text) && text.endsWith(']');
+}
+
 function resultText(value) {
   if (typeof value === 'string') return value;
   if (Array.isArray(value) && value.length > 0
@@ -168,7 +202,7 @@ function collectResponses(body) {
     if (['function_call', 'custom_tool_call'].includes(item?.type)) {
       entries.push({
         kind: 'call', id: item.call_id, name: item.name,
-        input: parseArguments(item.arguments ?? item.input), position,
+        input: parseArguments(item.arguments ?? item.input), position, providerType: item.type,
       });
     } else if (['function_call_output', 'custom_tool_call_output'].includes(item?.type)) {
       entries.push({
@@ -186,13 +220,14 @@ const COLLECTORS = {
   'openai-responses': collectResponses,
 };
 
-function historyRecords(entries, calls) {
+function historyRecords(entries, calls, provider) {
   return entries.flatMap((entry) => {
     if (entry.kind !== 'result') return [];
     const call = calls.get(entry.id);
     const text = resultText(entry.item[entry.key]);
     if (!call || text === null) return [];
     const isError = resultError(entry.item, text);
+    const safe = resultSuccess(entry.item, provider, text);
     return [{
       id: entry.id,
       toolName: call.name,
@@ -200,7 +235,7 @@ function historyRecords(entries, calls) {
       output: entry.item[entry.key],
       current: entry.current,
       historical: !entry.current,
-      safe: !isError,
+      safe,
       isError,
       position: entry.position,
       estimatedTokens: estimateTokens(text),
@@ -225,7 +260,29 @@ function collectHistoryRecords(provider, body) {
     calls.delete(id);
     results.delete(id);
   }
-  return historyRecords(entries, calls);
+  return historyRecords(entries, calls, provider);
+}
+
+const DEFAULT_STRATEGIES = Object.freeze({
+  supersededRead: true,
+  producerUseless: true,
+  exactDuplicate: true,
+  repeatedLines: true,
+  historyShake: true,
+  recoverableArchive: false,
+});
+
+function strategyPolicy(policy) {
+  if (!object(policy) || !Object.hasOwn(policy, 'strategies')) return DEFAULT_STRATEGIES;
+  if (!object(policy.strategies)) throw new TypeError('strategies must be an object');
+  const strategies = { ...DEFAULT_STRATEGIES };
+  for (const [name, enabled] of Object.entries(policy.strategies)) {
+    if (!Object.hasOwn(strategies, name) || typeof enabled !== 'boolean') {
+      throw new TypeError(`invalid context strategy: ${name}`);
+    }
+    strategies[name] = enabled;
+  }
+  return strategies;
 }
 
 export function detectProviderBody(body, headers = {}) {
@@ -322,16 +379,21 @@ function suffixTokensByPosition(body) {
   return suffix;
 }
 
-export function transformProviderRequest({ provider, body, policy, idleMs, redactionProfile } = {}) {
+export function transformProviderRequest({ provider, body, policy, idleMs, redactionProfile, historyArchiveRoot } = {}) {
   const clone = structuredClone(body);
   const estimatedInputTokens = estimate(body);
   const selectedProvider = provider ?? detectProviderBody(body);
+  const strategies = strategyPolicy(policy);
   const collector = COLLECTORS[selectedProvider];
   let supersededReads = 0;
   let elidedUselessSuccesses = 0;
   let deduplicatedResults = 0;
   let compactedStructures = 0;
   let shakenResults = 0;
+  let archivedResults = 0;
+  let archiveRedactionSkips = 0;
+  let archiveNoSavingsSkips = 0;
+  let archiveSizeSkips = 0;
   const disclosures = [];
   const disclose = (record, reason, originalText, visibleText, recovery = 'rerun-tool') => {
     if (typeof originalText !== 'string' || typeof visibleText !== 'string') return;
@@ -342,6 +404,22 @@ export function transformProviderRequest({ provider, body, policy, idleMs, redac
   const maxHistoryTokens = object(policy) && Object.hasOwn(policy, 'maxHistoryTokens')
     ? validateMaxHistoryTokens(policy.maxHistoryTokens)
     : null;
+  const historyArchiveRetainResults = object(policy) && Object.hasOwn(policy, 'historyArchiveRetainResults')
+    ? policy.historyArchiveRetainResults
+    : DEFAULT_HISTORY_ARCHIVE_RETAIN_RESULTS;
+  if (!Number.isSafeInteger(historyArchiveRetainResults) || historyArchiveRetainResults < 0) {
+    throw new TypeError('historyArchiveRetainResults must be a non-negative safe integer');
+  }
+  const historyArchiveMinBytes = object(policy) && Object.hasOwn(policy, 'historyArchiveMinBytes')
+    ? policy.historyArchiveMinBytes
+    : DEFAULT_HISTORY_ARCHIVE_MIN_BYTES;
+  if (!Number.isSafeInteger(historyArchiveMinBytes) || historyArchiveMinBytes < 0) {
+    throw new TypeError('historyArchiveMinBytes must be a non-negative safe integer');
+  }
+  if (strategies.recoverableArchive
+    && (typeof historyArchiveRoot !== 'string' || !path.isAbsolute(historyArchiveRoot))) {
+    throw new TypeError('historyArchiveRoot must be an absolute path');
+  }
   const budgetTriggered = maxHistoryTokens !== null
     && BigInt(estimatedInputTokens) * 5n > BigInt(maxHistoryTokens) * 4n;
   // Don't rewrite warm cached history unless the rewrite reclaims enough of the suffix
@@ -391,18 +469,46 @@ export function transformProviderRequest({ provider, body, policy, idleMs, redac
       results.delete(id);
     }
 
+    const archiveRecords = historyRecords(entries, calls, selectedProvider);
+    const resultEntries = entries.filter((entry) => entry.kind === 'result');
+    const recentEntries = new Set(historyArchiveRetainResults === 0
+      ? []
+      : resultEntries.slice(-historyArchiveRetainResults));
+    const archivedIds = new Set();
+    if (strategies.recoverableArchive) {
+      const profile = redactionProfile ?? DEFAULT_REDACTION_PROFILE;
+      if (!profile || typeof profile.redact !== 'function') throw new TypeError('history archive redaction profile is invalid');
+      for (const record of archiveRecords) {
+        const nativeSafety = nativeCodexExecSafety(selectedProvider, calls.get(record.id), record);
+        const safe = nativeSafety ?? record.safe;
+        if (!safe || !record.historical || recentEntries.has(record.entry)) continue;
+        const text = resultText(record.output);
+        if (text === null || historyArchiveMarker(text)) continue;
+        if (Buffer.byteLength(text, 'utf8') < historyArchiveMinBytes) { archiveSizeSkips += 1; continue; }
+        if (profile.redact(text).text !== text) { archiveRedactionSkips += 1; continue; }
+        const artifact = prepareHistoryArtifact({ root: historyArchiveRoot, content: text });
+        const reclaimed = reclaimedTokens(text, artifact.marker);
+        if (reclaimed === 0) { archiveNoSavingsSkips += 1; continue; }
+        if (cacheProtected(record.entry, reclaimed)) { cacheProtectedSkips += 1; continue; }
+        persistHistoryArtifact(artifact);
+        replaceResult(record.entry.item, record.entry.key, artifact.marker);
+        archivedIds.add(record.id);
+        archivedResults += 1;
+      }
+    }
+
     const reads = [];
     for (const call of calls.values()) {
       const result = results.get(call.id);
       const identity = readIdentity(call.name, call.input);
       const text = result && resultText(result.item[result.key]);
       if (!result || !identity || text === null) continue;
-      if (!resultError(result.item, text)) reads.push({ call, result, identity, text });
+      if (resultSuccess(result.item, selectedProvider, text)) reads.push({ call, result, identity, text });
     }
     reads.sort((a, b) => a.call.position - b.call.position);
-    for (let index = 0; index < reads.length; index += 1) {
+    for (let index = 0; strategies.supersededRead && index < reads.length; index += 1) {
       const old = reads[index];
-      if (old.result.current) continue;
+      if (old.result.current || archivedIds.has(old.call.id)) continue;
       const newer = reads.slice(index + 1).find((candidate) =>
         covers(candidate.identity, old.identity) && !useless(candidate.text));
       if (!newer) continue;
@@ -412,23 +518,24 @@ export function transformProviderRequest({ provider, body, policy, idleMs, redac
       supersededReads += 1;
     }
 
-    for (const [id, result] of results) {
-      if (!calls.has(id) || result.current) continue;
+    for (const [id, result] of strategies.producerUseless ? results : []) {
+      if (!calls.has(id) || result.current || archivedIds.has(id)) continue;
       const text = resultText(result.item[result.key]);
       if (text === null) continue;
-      if (text === SUPERSEDED || resultError(result.item, text) || !useless(text)) continue;
+      if (text === SUPERSEDED || !resultSuccess(result.item, selectedProvider, text) || !useless(text)) continue;
       if (cacheProtected(result, reclaimedTokens(text, USELESS))) { cacheProtectedSkips += 1; continue; }
       replaceResult(result.item, result.key, USELESS);
       disclose({ toolName: calls.get(id).name }, 'useless-success', text, USELESS);
       elidedUselessSuccesses += 1;
     }
 
-    const records = historyRecords(entries, calls);
+    const records = historyRecords(entries, calls, selectedProvider);
     const candidates = maxHistoryTokens === null
-      ? records.filter((record) => record.safe && record.historical)
-      : selectHistoryCandidates({ bodyTokens: estimatedInputTokens, maxHistoryTokens, candidates: records });
+      ? records.filter((record) => record.safe && record.historical && !archivedIds.has(record.id))
+      : selectHistoryCandidates({ bodyTokens: estimatedInputTokens, maxHistoryTokens, candidates: records })
+        .filter((record) => !archivedIds.has(record.id));
     const candidateIds = new Set(candidates.map((candidate) => candidate.id));
-    const reductions = dedupeHistory(records);
+    const reductions = strategies.exactDuplicate ? dedupeHistory(records) : { entries: [] };
     const recordsById = new Map(records.map((record) => [record.id, record]));
     for (const reduced of reductions.entries) {
       if (!candidateIds.has(reduced.id)) continue;
@@ -441,7 +548,7 @@ export function transformProviderRequest({ provider, body, policy, idleMs, redac
       deduplicatedResults += 1;
     }
 
-    for (const record of records) {
+    for (const record of strategies.repeatedLines ? records : []) {
       if (!candidateIds.has(record.id)) continue;
       const text = resultText(record.entry.item[record.entry.key]);
       if (text === null) continue;
@@ -458,7 +565,7 @@ export function transformProviderRequest({ provider, body, policy, idleMs, redac
       compactedStructures += 1;
     }
 
-    if (maxHistoryTokens !== null && budgetTriggered) {
+    if (strategies.historyShake && maxHistoryTokens !== null && budgetTriggered) {
       for (const record of records) {
         if (!candidateIds.has(record.id)) continue;
         const text = resultText(record.entry.item[record.entry.key]);
@@ -484,6 +591,7 @@ export function transformProviderRequest({ provider, body, policy, idleMs, redac
   if (deduplicatedResults > 0) reasons.push('duplicate-history');
   if (compactedStructures > 0) reasons.push('repeated-lines');
   if (shakenResults > 0) reasons.push('history-shake');
+  if (archivedResults > 0) reasons.unshift('recoverable-archive');
   return {
     body: clone,
     changed: reasons.length > 0,
@@ -497,6 +605,10 @@ export function transformProviderRequest({ provider, body, policy, idleMs, redac
       deduplicatedResults,
       compactedStructures,
       shakenResults,
+      archivedResults,
+      archiveRedactionSkips,
+      archiveNoSavingsSkips,
+      archiveSizeSkips,
       historyDisclosureCount: disclosures.length,
       historyDisclosureOriginalBytes: disclosures.reduce((total, item) => total + item.bytes.original, 0),
       historyDisclosureVisibleBytes: disclosures.reduce((total, item) => total + item.bytes.visible, 0),