sandoichi 0.1.0

package/src/provider-usage.mjs

@@ -0,0 +1,224 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const SCHEMA = 'sando-provider-usage/v1';
+const VERSION = 1;
+const LOCK_WAIT_MS = 10;
+const LOCK_ATTEMPTS = 250;
+const STALE_LOCK_MS = 30_000;
+
+export const PROVIDER_USAGE_SCHEMA = SCHEMA;
+export const PROVIDER_USAGE_VERSION = VERSION;
+
+function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function text(value) { return typeof value === 'string' && value.length > 0; }
+function counter(value) { return Number.isSafeInteger(value) && value >= 0; }
+function safeSum(...values) {
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return Number.isSafeInteger(total) ? total : null;
+}
+function sha256(value) { return `sha256:${createHash('sha256').update(value).digest('hex')}`; }
+function isoDate(value, fallback = new Date()) {
+  const date = value === undefined ? new Date(fallback) : new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toISOString();
+}
+function optionalCounter(value) { return value === undefined ? 0 : counter(value) ? value : null; }
+function jsonLines(textValue) {
+  if (typeof textValue !== 'string') throw new TypeError('transcript must be text');
+  return textValue.split(/\r?\n/).flatMap((line) => {
+    if (!line.trim()) return [];
+    try {
+      const value = JSON.parse(line);
+      return record(value) ? [{ value, line }] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function usageRecord({ host, source, sourceKey, sessionId, turnId, at, inputTokens, cachedInputTokens = 0,
+  cacheWriteInputTokens = 0, outputTokens, reasoningOutputTokens = 0 }) {
+  if (!text(host) || !text(source) || !text(sourceKey)
+    || (sessionId !== null && !text(sessionId)) || (turnId !== null && !text(turnId))
+    || !text(at) || !counter(inputTokens) || !counter(cachedInputTokens)
+    || !counter(cacheWriteInputTokens) || !counter(outputTokens) || !counter(reasoningOutputTokens)) return null;
+  const totalTokens = safeSum(inputTokens, outputTokens);
+  if (totalTokens === null) return null;
+  const identity = JSON.stringify({ host, source, sourceKey, at, inputTokens, cachedInputTokens,
+    cacheWriteInputTokens, outputTokens, reasoningOutputTokens, totalTokens });
+  return {
+    eventKey: `usage:${host}:${sha256(identity)}`,
+    schema: SCHEMA, version: VERSION, host, source,
+    sessionId: sessionId ?? null, turnId: turnId ?? null, at,
+    inputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens,
+    reasoningOutputTokens, totalTokens,
+  };
+}
+
+function claudeRecord(value, index, { sessionId = null, turnId = null, now } = {}) {
+  if (value.type !== 'assistant' || !record(value.message?.usage)) return null;
+  const usage = value.message.usage;
+  const inputTokens = usage.input_tokens;
+  const cachedInputTokens = optionalCounter(usage.cache_read_input_tokens);
+  const cacheWriteInputTokens = optionalCounter(usage.cache_creation_input_tokens);
+  const outputTokens = usage.output_tokens;
+  if (!counter(inputTokens) || cachedInputTokens === null || cacheWriteInputTokens === null || !counter(outputTokens)) return null;
+  const totalInputTokens = safeSum(inputTokens, cachedInputTokens, cacheWriteInputTokens);
+  if (totalInputTokens === null) return null;
+  const totalTokens = usage.total_tokens === undefined ? safeSum(totalInputTokens, outputTokens) : usage.total_tokens;
+  if (!counter(totalTokens) || totalTokens !== totalInputTokens + outputTokens) return null;
+  return usageRecord({
+    host: 'claude', source: 'claude-transcript', sourceKey: value.uuid ?? value.request_id ?? value.timestamp ?? String(index),
+    sessionId, turnId: value.turn_id ?? turnId, at: isoDate(value.timestamp, now),
+    inputTokens: totalInputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens,
+  });
+}
+
+function codexRecord(value, index, { sessionId = null, turnId = null, now } = {}) {
+  const usage = value.type === 'turn.completed'
+    ? value.usage
+    : value.type === 'event_msg' && value.payload?.type === 'token_count'
+      ? value.payload.info?.last_token_usage ?? value.payload.info?.usage
+      : undefined;
+  if (!record(usage)) return null;
+  const inputTokens = usage.input_tokens;
+  const cachedInputTokens = optionalCounter(usage.cached_input_tokens ?? usage.cache_read_input_tokens);
+  const cacheWriteInputTokens = optionalCounter(usage.cache_write_input_tokens);
+  const outputTokens = usage.output_tokens;
+  const reasoningOutputTokens = optionalCounter(usage.reasoning_output_tokens);
+  if (!counter(inputTokens) || cachedInputTokens === null || cacheWriteInputTokens === null
+    || !counter(outputTokens) || reasoningOutputTokens === null) return null;
+  const totalTokens = usage.total_tokens === undefined ? safeSum(inputTokens, outputTokens) : usage.total_tokens;
+  if (!counter(totalTokens) || totalTokens !== inputTokens + outputTokens) return null;
+  return usageRecord({
+    host: 'codex', source: 'codex-transcript', sourceKey: value.turn_id ?? value.id ?? value.timestamp ?? String(index),
+    sessionId, turnId: value.turn_id ?? turnId, at: isoDate(value.timestamp, now),
+    inputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens, reasoningOutputTokens,
+  });
+}
+
+export function parseClaudeTranscript(textValue, options = {}) {
+  return jsonLines(textValue).map(({ value }, index) => claudeRecord(value, index, options)).filter(Boolean);
+}
+
+export function parseCodexTranscript(textValue, options = {}) {
+  return jsonLines(textValue).map(({ value }, index) => codexRecord(value, index, options)).filter(Boolean);
+}
+
+export function defaultProviderUsagePath(env = process.env) {
+  const configured = env.SANDO_PROVIDER_USAGE_PATH;
+  if (configured !== undefined) {
+    if (typeof configured !== 'string' || !path.isAbsolute(configured)) throw new Error('provider usage 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', 'provider-usage.json');
+}
+
+function timezone() { return new Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'; }
+function emptyState() { return { schema: SCHEMA, version: VERSION, timezone: timezone(), records: [] }; }
+function resolvePath(storagePath) {
+  if (typeof storagePath !== 'string' || !path.isAbsolute(storagePath)) throw new Error('provider usage path must be absolute');
+  return storagePath;
+}
+
+function validateUsage(value) {
+  if (!record(value) || value.schema !== SCHEMA || value.version !== VERSION || !text(value.eventKey)
+    || !text(value.host) || !text(value.source) || !text(value.at)
+    || (value.sessionId !== null && !text(value.sessionId)) || (value.turnId !== null && !text(value.turnId))
+    || !counter(value.inputTokens) || !counter(value.cachedInputTokens) || !counter(value.cacheWriteInputTokens)
+    || !counter(value.outputTokens) || !counter(value.reasoningOutputTokens) || !counter(value.totalTokens)
+    || value.totalTokens !== value.inputTokens + value.outputTokens) throw new Error('provider usage record is invalid');
+}
+
+function validateState(value) {
+  if (!record(value) || value.schema !== SCHEMA || value.version !== VERSION || !Array.isArray(value.records)) {
+    throw new Error('provider usage state is invalid');
+  }
+  const keys = new Set();
+  for (const item of value.records) {
+    validateUsage(item);
+    if (keys.has(item.eventKey)) throw new Error('provider usage state contains duplicate events');
+    keys.add(item.eventKey);
+  }
+  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('provider usage 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('provider usage 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}.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 readProviderUsage(storagePath = defaultProviderUsagePath()) {
+  const filePath = resolvePath(storagePath);
+  if (!fs.existsSync(filePath)) return emptyState();
+  return validateState(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+}
+
+export function appendProviderUsage({ storagePath = defaultProviderUsagePath(), records = [] } = {}) {
+  if (!Array.isArray(records)) throw new TypeError('provider usage records must be an array');
+  for (const item of records) validateUsage(item);
+  const filePath = resolvePath(storagePath);
+  ensureDirectory(path.dirname(filePath));
+  return withLock(`${filePath}.lock`, () => {
+    const state = readProviderUsage(filePath);
+    const existing = new Set(state.records.map((item) => item.eventKey));
+    for (const item of records) if (!existing.has(item.eventKey)) { state.records.push(item); existing.add(item.eventKey); }
+    atomicWrite(filePath, state);
+    return state;
+  });
+}
+
+export function collectProviderUsage({ host, transcriptPath, sessionId = null, turnId = null,
+  storagePath = defaultProviderUsagePath(), now } = {}) {
+  if (!['claude', 'codex'].includes(host) || typeof transcriptPath !== 'string' || !transcriptPath) return { records: [], state: readProviderUsage(storagePath) };
+  try {
+    const textValue = fs.readFileSync(transcriptPath, 'utf8');
+    const parse = host === 'claude' ? parseClaudeTranscript : parseCodexTranscript;
+    const records = parse(textValue, { sessionId, turnId, now });
+    return { records, state: appendProviderUsage({ storagePath, records }) };
+  } catch {
+    return { records: [], state: readProviderUsage(storagePath) };
+  }
+}
+
+export function buildProviderUsageReport(state, { sessionId } = {}) {
+  const records = validateState(state).records.filter((item) => sessionId === undefined || item.sessionId === sessionId);
+  const sessions = new Set(records.map((item) => `${item.host}\0${item.sessionId ?? '<unknown>'}`));
+  const sum = (field) => records.reduce((total, item) => total + item[field], 0);
+  return {
+    eventCount: records.length, sessionCount: sessions.size,
+    inputTokens: sum('inputTokens'), cachedInputTokens: sum('cachedInputTokens'),
+    cacheWriteInputTokens: sum('cacheWriteInputTokens'), outputTokens: sum('outputTokens'),
+    reasoningOutputTokens: sum('reasoningOutputTokens'), totalTokens: sum('totalTokens'),
+  };
+}

package/src/proxy-metrics.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const SCHEMA = 'sando-proxy-metrics/v1';
+
+/**
+ * Durable per-request record of what the proxy did and what the provider actually
+ * billed, so a real median savings figure can be computed later from real usage
+ * instead of a single live probe. Append-only JSONL: one line per forwarded request,
+ * safe to `tail -f` or fold with a small aggregation script.
+ */
+export function defaultProxyMetricsPath(env = process.env) {
+  const configured = env.SANDO_PROXY_METRICS_PATH;
+  if (configured !== undefined) return configured;
+  const stateHome = env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
+  return path.join(stateHome, 'sando', 'proxy-requests.jsonl');
+}
+
+export function recordProxyRequest({ storagePath, provider, model, stats, usage, now = new Date() } = {}) {
+  if (typeof storagePath !== 'string' || !storagePath) throw new TypeError('storagePath is required');
+  if (typeof provider !== 'string' || !provider) throw new TypeError('provider is required');
+  fs.mkdirSync(path.dirname(storagePath), { recursive: true, mode: 0o700 });
+  const record = {
+    schema: SCHEMA,
+    at: now.toISOString(),
+    provider,
+    model: typeof model === 'string' ? model : null,
+    stats: stats ?? null,
+    usage: usage ?? null,
+  };
+  fs.appendFileSync(storagePath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  return record;
+}

package/src/proxy.mjs

@@ -0,0 +1,212 @@
+import http from 'node:http';
+
+import { detectProviderBody, listSemanticCandidates, transformProviderRequest } from './context-transform.mjs';
+import { recordProxyRequest } from './proxy-metrics.mjs';
+
+const DEFAULT_MAX_BODY_BYTES = 16 * 1024 * 1024;
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection', 'content-length', 'keep-alive', 'proxy-authenticate',
+  'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade', 'host',
+  'accept-encoding', 'content-encoding',
+]);
+
+function assertUpstream(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new TypeError('upstream must be an absolute URL'); }
+  if (!['http:', 'https:'].includes(url.protocol)) throw new TypeError('upstream must use http or https');
+  if (url.username || url.password) throw new TypeError('upstream must not contain credentials');
+  return url;
+}
+
+function readBody(request, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let bytes = 0;
+    request.on('data', (chunk) => {
+      bytes += chunk.length;
+      if (bytes > maxBytes) {
+        reject(new Error('request body exceeds proxy limit'));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on('end', () => resolve(Buffer.concat(chunks)));
+    request.on('error', reject);
+  });
+}
+
+function targetUrl(upstream, requestUrl) {
+  const request = new URL(requestUrl, 'http://sando.invalid');
+  const target = new URL(upstream);
+  const basePath = target.pathname.replace(/\/$/, '');
+  target.pathname = `${basePath}${request.pathname}` || '/';
+  target.search = request.search;
+  return target;
+}
+
+function forwardedHeaders(request) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (HOP_BY_HOP_HEADERS.has(name.toLowerCase()) || value === undefined) continue;
+    headers.set(name, Array.isArray(value) ? value.join(', ') : value);
+  }
+  headers.set('accept-encoding', 'identity');
+  return headers;
+}
+
+function responseHeaders(response) {
+  const headers = {};
+  response.headers.forEach((value, name) => {
+    if (!HOP_BY_HOP_HEADERS.has(name.toLowerCase())) headers[name] = value;
+  });
+  return headers;
+}
+
+const MAX_USAGE_SCAN_BYTES = 2 * 1024 * 1024;
+
+/** Merges every `"usage":{...}` object seen across a (possibly streamed) Anthropic
+ *  response: `message_start` carries input/cache token counts, `message_delta`
+ *  carries the final output count, and later objects overwrite matching keys. */
+function extractUsage(text) {
+  let usage = null;
+  for (const match of text.matchAll(/"usage":\s*(\{[^{}]*\})/g)) {
+    try { usage = { ...usage, ...JSON.parse(match[1]) }; } catch { /* ignore malformed fragment */ }
+  }
+  return usage;
+}
+
+async function pipeResponse(response, outgoing, onText) {
+  outgoing.writeHead(response.status, response.statusText, responseHeaders(response));
+  if (!response.body) {
+    outgoing.end();
+    return;
+  }
+  const decoder = new TextDecoder();
+  let scanned = 0;
+  for await (const chunk of response.body) {
+    outgoing.write(chunk);
+    if (onText && scanned < MAX_USAGE_SCAN_BYTES) {
+      scanned += chunk.length;
+      onText(decoder.decode(chunk, { stream: true }));
+    }
+  }
+  outgoing.end();
+}
+
+function jsonResponse(outgoing, status, body) {
+  const text = JSON.stringify(body);
+  outgoing.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(text) });
+  outgoing.end(text);
+}
+
+function createSemanticStats(candidates) {
+  return {
+    candidates: candidates.length,
+    attempted: candidates.length,
+    accepted: 0,
+    cacheHits: 0,
+    fallbacks: 0,
+    skipped: 0,
+    netSavedTokens: 0,
+    pending: candidates.length,
+  };
+}
+
+async function observeSemanticCandidates({ provider, candidates, semanticCompactor, stats }) {
+  for (const candidate of candidates) {
+    try {
+      const result = await semanticCompactor({ provider, ...candidate });
+      if (result?.status === 'candidate') stats.accepted += 1;
+      else if (result?.status === 'fallback') stats.fallbacks += 1;
+      else stats.skipped += 1;
+      if (result?.cacheHit === true) stats.cacheHits += 1;
+      if (Number.isSafeInteger(result?.netSavedTokens)) stats.netSavedTokens += result.netSavedTokens;
+    } catch {
+      stats.fallbacks += 1;
+    } finally {
+      stats.pending -= 1;
+    }
+  }
+}
+
+export async function createProviderProxy({ upstream, host = '127.0.0.1', port = 0, policy = {}, maxBodyBytes = DEFAULT_MAX_BODY_BYTES, semanticCompactor, metricsPath } = {}) {
+  const upstreamUrl = assertUpstream(upstream);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new TypeError('port is invalid');
+  if (!Number.isInteger(maxBodyBytes) || maxBodyBytes < 1024) throw new TypeError('maxBodyBytes is invalid');
+  let lastStats = null;
+  let lastRequestAt = null;
+
+  const server = http.createServer(async (request, outgoing) => {
+    try {
+      if (request.method === 'GET' && new URL(request.url, 'http://sando.invalid').pathname === '/health') {
+        jsonResponse(outgoing, 200, { schema: 'sando-provider-proxy/v1', status: 'ok', lastStats });
+        return;
+      }
+      const rawBody = await readBody(request, maxBodyBytes);
+      let body = rawBody;
+      let recordProvider = null;
+      let recordModel = null;
+      let recordStats = null;
+      if (rawBody.length > 0 && /application\/json/i.test(request.headers['content-type'] ?? '')) {
+        try {
+          const parsed = JSON.parse(rawBody.toString('utf8'));
+          const provider = detectProviderBody(parsed, request.headers);
+          if (provider) {
+            const now = Date.now();
+            const idleMs = lastRequestAt === null ? null : now - lastRequestAt;
+            lastRequestAt = now;
+            const transformed = transformProviderRequest({ provider, body: parsed, policy, idleMs });
+            if (transformed.changed) body = Buffer.from(JSON.stringify(transformed.body));
+            lastStats = { provider, ...transformed.stats, changed: transformed.changed, reasons: transformed.reasons };
+            recordProvider = provider;
+            recordModel = typeof parsed?.model === 'string' ? parsed.model : null;
+            recordStats = transformed.stats;
+            if (typeof semanticCompactor === 'function') {
+              const candidates = listSemanticCandidates({ provider, body: transformed.body });
+              const stats = createSemanticStats(candidates);
+              lastStats.semantic = stats;
+              setImmediate(() => observeSemanticCandidates({ provider, candidates, semanticCompactor, stats }));
+            }
+          }
+        } catch {
+          body = rawBody;
+        }
+      }
+      const response = await fetch(targetUrl(upstreamUrl, request.url), {
+        method: request.method,
+        headers: forwardedHeaders(request),
+        body: ['GET', 'HEAD'].includes(request.method) ? undefined : body,
+        redirect: 'manual',
+      });
+      let responseText = '';
+      await pipeResponse(response, outgoing, metricsPath ? (chunk) => { responseText += chunk; } : undefined);
+      if (metricsPath && recordProvider) {
+        try {
+          recordProxyRequest({
+            storagePath: metricsPath, provider: recordProvider, model: recordModel,
+            stats: recordStats, usage: extractUsage(responseText),
+          });
+        } catch { /* metrics are best-effort and must never affect the proxied response */ }
+      }
+    } catch (error) {
+      if (!outgoing.headersSent) jsonResponse(outgoing, error.message === 'request body exceeds proxy limit' ? 413 : 502, { error: 'sando proxy upstream failure' });
+      else outgoing.destroy();
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolve);
+  });
+  const address = server.address();
+  const actualPort = typeof address === 'object' && address ? address.port : port;
+  return {
+    server,
+    host,
+    port: actualPort,
+    url: `http://${host}:${actualPort}`,
+    get lastStats() { return lastStats; },
+    close: () => new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())),
+  };
+}

package/src/routing.mjs

@@ -0,0 +1,89 @@
+export const ROUTING_POLICY_VERSION = 'sando-routing/v1';
+
+const READ_SUMMARY_LIMITS = Object.freeze({
+  minTotalLines: 100,
+  maxSummaryBytes: 2 * 1024 * 1024,
+  maxSummaryLines: 20_000,
+});
+const GREP_LIMITS = Object.freeze({
+  files: 20,
+  matchesPerFile: 20,
+  singleFileMatches: 200,
+  internalTotalMatches: 2_000,
+  nativeMaxFileBytes: 4 * 1024 * 1024,
+  timeoutMs: 30_000,
+  maxColumns: 512,
+});
+const OUTPUT_LIMITS = Object.freeze({
+  spillBytes: 50 * 1024,
+  headBytes: 20 * 1024,
+  tailBytes: 20 * 1024,
+  tailLines: 500,
+  maxColumns: 768,
+});
+
+const isNonNegativeSafeInteger = (value) => Number.isSafeInteger(value) && value >= 0;
+
+export function planToolRoute({
+  toolName,
+  selector = false,
+  raw = false,
+  lineCount = 0,
+  fileBytes,
+  prose = false,
+  summarizeProse = false,
+  summarizeEnabled = true,
+  grepScope = 'multi',
+  outputBytes = 0,
+} = {}) {
+  const name = typeof toolName === 'string' ? toolName.toLowerCase() : toolName;
+  const readCanSummarize = name === 'read'
+    && !selector
+    && !raw
+    && summarizeEnabled
+    && (!prose || summarizeProse)
+    && isNonNegativeSafeInteger(lineCount)
+    && lineCount >= READ_SUMMARY_LIMITS.minTotalLines
+    && lineCount <= READ_SUMMARY_LIMITS.maxSummaryLines
+    && isNonNegativeSafeInteger(fileBytes)
+    && fileBytes > 0
+    && fileBytes <= READ_SUMMARY_LIMITS.maxSummaryBytes;
+
+  if (readCanSummarize) {
+    return {
+      route: 'summary',
+      modelVisible: 'elided-structure',
+      source: 'sando-read-summarize',
+      limits: READ_SUMMARY_LIMITS,
+    };
+  }
+
+  if (name === 'grep') {
+    return {
+      route: 'structured',
+      modelVisible: 'bounded-matches',
+      source: 'sando-grep',
+      limits: Object.freeze({
+        ...GREP_LIMITS,
+        matchesPerFile: grepScope === 'single-file'
+          ? GREP_LIMITS.singleFileMatches
+          : GREP_LIMITS.matchesPerFile,
+      }),
+    };
+  }
+
+  if (name === 'bash' && isNonNegativeSafeInteger(outputBytes) && outputBytes > OUTPUT_LIMITS.spillBytes) {
+    return {
+      route: 'artifact',
+      modelVisible: 'head-tail-artifact-ref',
+      source: 'sando-output-meta',
+      limits: OUTPUT_LIMITS,
+    };
+  }
+
+  return {
+    route: 'passthrough',
+    modelVisible: 'bounded-output',
+    source: 'spike-default',
+  };
+}

package/src/secret-redaction.mjs

@@ -0,0 +1,21 @@
+export function redact(text) {
+  let count = 0;
+  const replace = (pattern, replacement) => {
+    text = text.replace(pattern, (...args) => {
+      count += 1;
+      return typeof replacement === 'function' ? replacement(...args) : replacement;
+    });
+  };
+  replace(/-----BEGIN [A-Z ]+ KEY-----[\s\S]*?-----END [A-Z ]+ KEY-----/g, '[REDACTED PRIVATE KEY]');
+  replace(/\b(?:sk|rk)-[A-Za-z0-9_-]{12,}\b/g, '[REDACTED TOKEN]');
+  replace(/\bgh[pousr]_[A-Za-z0-9_-]{12,}\b/g, '[REDACTED TOKEN]');
+  replace(/\bgithub_pat_[A-Za-z0-9_-]{20,}\b/g, '[REDACTED TOKEN]');
+  replace(/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED TOKEN]');
+  replace(/(authorization\s*[:=]\s*(?:bearer\s+)?)[^\s,"'}]+/gi, (_match, prefix) => `${prefix}[REDACTED]`);
+  replace(/(["']?(?:api[_-]?key|access[_-]?token|password|secret|private[_-]?key)["']?\s*[:=]\s*["']?)[^\s,"'}]+/gi, (_match, prefix) => `${prefix}[REDACTED]`);
+  return { text, count };
+}
+
+export function hasSecret(text) {
+  return /(?:authorization|api[_-]?key|access[_-]?token|password|secret|private[_-]?key)\s*[:=]\s*(?!\[REDACTED\])\S+|-----BEGIN [A-Z ]+ KEY-----|\b(?:sk|rk)-[A-Za-z0-9_-]{12,}\b|\bgh[pousr]_[A-Za-z0-9_-]{12,}\b|\bgithub_pat_[A-Za-z0-9_-]{20,}\b|\bAKIA[0-9A-Z]{16}\b/i.test(text);
+}