sandoichi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yuzushi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# sandoichi
+
+Cuts what Claude Code and Codex charge you to re-read their own output. Redacts secrets, caps oversized tool results, and, if you turn it on, trims request history before it's sent — all without calling an LLM itself.
+
+This is the core library (`@sando/core` renamed `sandoichi` for npm). For the Claude Code plugin, Codex plugin, and provider proxy, see the [main repo](https://github.com/yuzushi-dev/Sando).
+
+## Install
+
+```sh
+npm install sandoichi
+```
+
+Requires Node.js `22.22.x`.
+
+## Usage
+
+```js
+import { optimizeToolOutput, createProviderProxy } from 'sandoichi';
+```
+
+See [index.mjs](./index.mjs) for the full list of exports (tool-output optimization, provider request transforms, semantic compaction, metrics, status line rendering).
+
+## License
+
+MIT

package/index.mjs

@@ -0,0 +1,54 @@
+export {
+  createReceipt,
+  estimateTokens,
+  normalizeEvent,
+  normalizePolicy,
+  optimizeToolOutput,
+} from './src/core.mjs';
+export { detectProviderBody, listSemanticCandidates, transformProviderRequest } from './src/context-transform.mjs';
+export {
+  buildSemanticPrompt,
+  createSemanticCompactor,
+  SEMANTIC_SUMMARY_SCHEMA,
+  validateSemanticSummary,
+} from './src/semantic-compactor.mjs';
+export { createProviderProxy } from './src/proxy.mjs';
+export { shakeHistoricalResult } from './src/history-shake.mjs';
+export {
+  attributeSession,
+  attributeTurn,
+  CACHE_MISS_CAUSES,
+} from './src/cache-attribution.mjs';
+export {
+  buildMetricsReport,
+  defaultMetricsPath,
+  formatMetricsReport,
+  readMetrics,
+  recordMetrics,
+} from './src/metrics.mjs';
+export {
+  aggregateProviderLedger,
+  createProviderLedgerEntry,
+  PROVIDER_LEDGER_SCHEMA,
+  PROVIDER_LEDGER_VERSION,
+} from './src/provider-ledger.mjs';
+export {
+  appendProviderUsage,
+  buildProviderUsageReport,
+  collectProviderUsage,
+  defaultProviderUsagePath,
+  parseClaudeTranscript,
+  parseCodexTranscript,
+  readProviderUsage,
+  PROVIDER_USAGE_SCHEMA,
+  PROVIDER_USAGE_VERSION,
+} from './src/provider-usage.mjs';
+export { planToolRoute, ROUTING_POLICY_VERSION } from './src/routing.mjs';
+export { readStatusSnapshot, renderStatusLine, STATUSLINE_MAX_AGE_MS } from './src/statusline.mjs';
+export {
+  activeSessionForPane,
+  currentTmuxPanePid,
+  defaultActiveSessionPath,
+  readActiveSessions,
+  recordActiveSession,
+} from './src/active-session.mjs';

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "sandoichi",
+  "version": "0.1.0",
+  "description": "Cuts what Claude Code and Codex charge you to re-read their own output.",
+  "license": "MIT",
+  "author": "yuzushi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuzushi-dev/Sando.git",
+    "directory": "packages/sando"
+  },
+  "homepage": "https://github.com/yuzushi-dev/Sando#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.0 <23"
+  },
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  }
+}

package/src/active-session.mjs

@@ -0,0 +1,136 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const SCHEMA = 'sando-active-session/v1';
+const VERSION = 1;
+const LOCK_WAIT_MS = 10;
+const LOCK_ATTEMPTS = 250;
+const STALE_LOCK_MS = 30_000;
+
+export const ACTIVE_SESSION_SCHEMA = SCHEMA;
+export const ACTIVE_SESSION_VERSION = VERSION;
+
+function text(value) { return typeof value === 'string' && value.length > 0; }
+function pane(value) { return text(value) && /^%\d+$/.test(value); }
+function pid(value) {
+  const number = typeof value === 'number' ? value : Number(value);
+  return Number.isSafeInteger(number) && number > 0 ? number : null;
+}
+
+function emptyState() { return { schema: SCHEMA, version: VERSION, entries: [] }; }
+
+function resolvePath(storagePath) {
+  if (typeof storagePath !== 'string' || !path.isAbsolute(storagePath)) {
+    throw new Error('active session path must be absolute');
+  }
+  return storagePath;
+}
+
+function validateState(value) {
+  if (!value || typeof value !== 'object' || value.schema !== SCHEMA
+    || value.version !== VERSION || !Array.isArray(value.entries)) {
+    throw new Error('active session state is invalid');
+  }
+  const panes = new Set();
+  for (const entry of value.entries) {
+    if (!pane(entry.paneId) || !text(entry.sessionId) || pid(entry.panePid) === null
+      || typeof entry.updatedAt !== 'string' || Number.isNaN(Date.parse(entry.updatedAt))) {
+      throw new Error('active session entry is invalid');
+    }
+    if (panes.has(entry.paneId)) throw new Error('active session state contains duplicate panes');
+    panes.add(entry.paneId);
+  }
+  return value;
+}
+
+function ensureDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('active session directory is unsafe');
+  fs.chmodSync(directory, 0o700);
+}
+
+function waitForLock() {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_WAIT_MS);
+}
+
+function withLock(lockPath, operation) {
+  let handle;
+  for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt += 1) {
+    try { handle = fs.openSync(lockPath, 'wx', 0o600); break; }
+    catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const stat = fs.statSync(lockPath, { throwIfNoEntry: false });
+      if (stat && Date.now() - stat.mtimeMs > STALE_LOCK_MS) fs.rmSync(lockPath, { force: true });
+      else waitForLock();
+    }
+  }
+  if (handle === undefined) throw new Error('active session lock timeout');
+  try { return operation(); }
+  finally { fs.closeSync(handle); fs.rmSync(lockPath, { force: true }); }
+}
+
+function atomicWrite(filePath, value) {
+  const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+  try { fs.renameSync(temporary, filePath); }
+  catch (error) { fs.rmSync(temporary, { force: true }); throw error; }
+  fs.chmodSync(filePath, 0o600);
+}
+
+export function defaultActiveSessionPath(env = process.env) {
+  const configured = env.SANDO_ACTIVE_SESSION_PATH;
+  if (configured !== undefined) return resolvePath(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', 'active-sessions.json');
+}
+
+export function readActiveSessions(storagePath = defaultActiveSessionPath()) {
+  const filePath = resolvePath(storagePath);
+  if (!fs.existsSync(filePath)) return emptyState();
+  const stat = fs.lstatSync(filePath);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('active session file is unsafe');
+  return validateState(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+}
+
+export function currentTmuxPanePid(paneId, env = process.env) {
+  if (!pane(paneId)) return null;
+  const configured = pid(env.SANDO_CODEX_PANE_PID);
+  if (configured !== null) return configured;
+  try {
+    return pid(execFileSync('tmux', ['display-message', '-p', '-t', paneId, '#{pane_pid}'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim());
+  } catch {
+    return null;
+  }
+}
+
+export function recordActiveSession({ sessionId, paneId, panePid, storagePath = defaultActiveSessionPath(), now = new Date() } = {}) {
+  if (!text(sessionId) || !pane(paneId) || pid(panePid) === null) return false;
+  const filePath = resolvePath(storagePath);
+  ensureDirectory(path.dirname(filePath));
+  return withLock(`${filePath}.lock`, () => {
+    const state = readActiveSessions(filePath);
+    const entry = { paneId, panePid: pid(panePid), sessionId, updatedAt: new Date(now).toISOString() };
+    const index = state.entries.findIndex((candidate) => candidate.paneId === paneId);
+    if (index === -1) state.entries.push(entry);
+    else state.entries[index] = entry;
+    atomicWrite(filePath, state);
+    return true;
+  });
+}
+
+export function activeSessionForPane({ paneId, panePid, storagePath = defaultActiveSessionPath() } = {}) {
+  if (!pane(paneId) || pid(panePid) === null) return undefined;
+  try {
+    const entry = readActiveSessions(storagePath).entries.find((candidate) => candidate.paneId === paneId);
+    return entry && entry.panePid === pid(panePid) ? entry : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/cache-attribution.mjs

@@ -0,0 +1,182 @@
+/**
+ * Why did the provider prompt cache miss on this turn?
+ *
+ * The provider ledger already records `cachedInputTokens` / `cacheWriteInputTokens`
+ * per turn, but a raw hit rate cannot say *why* a miss happened, and on its own it
+ * is the wrong instrument: a divergence behind the last cache breakpoint still costs
+ * a re-prefill while the hit is scored against the prefix that did match. So this
+ * module classifies each turn against the previous one and reports cache-write
+ * volume alongside hit/miss.
+ *
+ * Deterministic: pure functions over recorded counters and request shapes. No
+ * network, no LLM, no provider call.
+ *
+ * Anthropic invalidates hierarchically — `tools` -> `system` -> `messages` — and any
+ * change at one level invalidates that level and everything after it, so the causes
+ * below are ordered and the first match wins.
+ */
+
+const CAUSES = [
+  'tools-changed',
+  'system-changed',
+  'history-rewritten',
+  'below-minimum',
+  'no-breakpoint',
+  'cold-start',
+  'ttl-expired',
+  'unexplained',
+];
+
+export const CACHE_MISS_CAUSES = Object.freeze([...CAUSES]);
+
+// Anthropic's smallest cacheable prompt across current models. Below this the
+// request is processed uncached with no error, so a "miss" is expected, not a defect.
+const DEFAULT_MIN_CACHEABLE_TOKENS = 1024;
+
+// Longest cache lifetime Anthropic offers (1h). A gap wider than this guarantees the
+// entry is gone regardless of anything the client did.
+const DEFAULT_MAX_TTL_MS = 60 * 60 * 1000;
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function counter(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+/** 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) {
+  const json = JSON.stringify(value ?? null);
+  let hash = 0;
+  for (let index = 0; index < json.length; index += 1) {
+    hash = ((hash << 5) - hash + json.charCodeAt(index)) | 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+
+/** Per-message digests, so a rewritten historical message is visible as a prefix
+ * divergence rather than only as a changed whole-history digest. */
+export function messageDigests(messages) {
+  return Array.isArray(messages) ? messages.map((message) => shapeDigest(message)) : [];
+}
+
+/** Index of the first message whose bytes differ from the previous turn's, or null
+ * when the previous turn is a prefix of this one (i.e. this turn only appended). */
+export function firstDivergence(previousDigests, currentDigests) {
+  const bound = Math.min(previousDigests.length, currentDigests.length);
+  for (let index = 0; index < bound; index += 1) {
+    if (previousDigests[index] !== currentDigests[index]) return index;
+  }
+  return currentDigests.length < previousDigests.length ? bound : null;
+}
+
+/** Does this request carry any cache_control breakpoint at all? */
+export function hasBreakpoint(body) {
+  if (!object(body) && !Array.isArray(body)) return false;
+  if (Array.isArray(body)) return body.some((item) => hasBreakpoint(item));
+  for (const [key, value] of Object.entries(body)) {
+    if (key === 'cache_control' && value !== undefined) return true;
+    if (hasBreakpoint(value)) return true;
+  }
+  return false;
+}
+
+/**
+ * Classify one turn.
+ *
+ * `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.
+ */
+export function attributeTurn({
+  current,
+  previous = null,
+  minCacheableTokens = DEFAULT_MIN_CACHEABLE_TOKENS,
+  maxTtlMs = DEFAULT_MAX_TTL_MS,
+} = {}) {
+  if (!object(current)) throw new TypeError('current turn is required');
+
+  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 hit = cacheReadTokens > 0;
+
+  const currentDigests = messageDigests(current.messages);
+  const previousDigests = previous ? messageDigests(previous.messages) : [];
+  const divergedAt = previous ? firstDivergence(previousDigests, currentDigests) : null;
+
+  const detail = {
+    cacheReadTokens,
+    cacheWriteTokens,
+    freshInputTokens,
+    totalPromptTokens,
+    divergedAtMessage: divergedAt,
+    messagesBeforeDivergence: divergedAt ?? currentDigests.length,
+    breakpointPresent: hasBreakpoint(current.body ?? current),
+  };
+
+  if (hit) return { hit: true, cause: null, ...detail };
+
+  // Ordered by Anthropic's invalidation hierarchy: the first true cause explains
+  // everything after it, so reporting a later one would be misleading.
+  let cause;
+  if (!previous) cause = 'cold-start';
+  else if (shapeDigest(current.tools) !== shapeDigest(previous.tools)) cause = 'tools-changed';
+  else if (shapeDigest(current.system) !== shapeDigest(previous.system)) cause = 'system-changed';
+  else if (divergedAt !== null) cause = 'history-rewritten';
+  else if (!detail.breakpointPresent) cause = 'no-breakpoint';
+  else if (totalPromptTokens > 0 && totalPromptTokens < minCacheableTokens) cause = 'below-minimum';
+  else if (elapsedMs(previous.at, current.at) > maxTtlMs) cause = 'ttl-expired';
+  else cause = 'unexplained';
+
+  return { hit: false, cause, ...detail };
+}
+
+function elapsedMs(from, to) {
+  const start = Date.parse(from ?? '');
+  const end = Date.parse(to ?? '');
+  return Number.isFinite(start) && Number.isFinite(end) ? end - start : 0;
+}
+
+/**
+ * Classify a whole session and summarize it.
+ *
+ * Reports cache-write volume as a first-class figure, not just hit rate: a turn can
+ * be scored a "hit" against a short matched prefix while re-writing most of the
+ * conversation, and that cost is invisible to hit rate alone.
+ */
+export function attributeSession(turns, options = {}) {
+  if (!Array.isArray(turns)) throw new TypeError('turns must be an array');
+
+  const results = turns.map((turn, index) =>
+    attributeTurn({ ...options, current: turn, previous: index === 0 ? null : turns[index - 1] }));
+
+  const misses = results.filter((result) => !result.hit);
+  const causes = Object.fromEntries(CAUSES.map((cause) => [cause, 0]));
+  for (const miss of misses) causes[miss.cause] += 1;
+
+  const sum = (key) => results.reduce((total, result) => total + result[key], 0);
+  const cacheReadTokens = sum('cacheReadTokens');
+  const cacheWriteTokens = sum('cacheWriteTokens');
+  const freshInputTokens = sum('freshInputTokens');
+
+  return {
+    schema: 'sando-cache-attribution/v1',
+    turns: results.length,
+    hits: results.length - misses.length,
+    misses: misses.length,
+    hitRate: results.length === 0 ? null : (results.length - misses.length) / results.length,
+    causes,
+    cacheReadTokens,
+    cacheWriteTokens,
+    freshInputTokens,
+    // Cache writes bill at 1.25x (5m) or 2x (1h) of base input while reads bill at
+    // 0.1x, so write volume relative to reads is the ratio that actually tracks spend.
+    writeToReadRatio: cacheReadTokens === 0 ? null : cacheWriteTokens / cacheReadTokens,
+    perTurn: results,
+  };
+}