sandoichi 0.1.0

package/src/semantic-compactor.mjs

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto';
+
+import { estimateTokens } from './core.mjs';
+import { redact, hasSecret } from './secret-redaction.mjs';
+
+export const SEMANTIC_SUMMARY_SCHEMA = 'sando-semantic-summary/v1';
+
+const DEFAULT_POLICY = Object.freeze({
+  minInputTokens: 8000,
+  maxSummaryRatio: 0.2,
+  timeoutMs: 1500,
+});
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function facts(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((fact) => typeof fact !== 'string' || fact.length === 0)) {
+    throw new TypeError('requiredFacts must be non-empty strings');
+  }
+  return [...new Set(value)];
+}
+
+function parseResponse(value) {
+  if (typeof value === 'string') {
+    try { return JSON.parse(value); } catch { return null; }
+  }
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+
+function usageCounter(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function validatePolicy(policy) {
+  const result = { ...DEFAULT_POLICY, ...(policy ?? {}) };
+  if (!Number.isInteger(result.minInputTokens) || result.minInputTokens < 1
+    || !Number.isFinite(result.maxSummaryRatio) || result.maxSummaryRatio <= 0 || result.maxSummaryRatio >= 1
+    || !Number.isInteger(result.timeoutMs) || result.timeoutMs < 1) {
+    throw new TypeError('invalid semantic compactor policy');
+  }
+  return result;
+}
+
+export function buildSemanticPrompt({ provider, model, toolName, text, requiredFacts = [] } = {}) {
+  const required = facts(requiredFacts);
+  return [
+    `Schema: ${SEMANTIC_SUMMARY_SCHEMA}`,
+    'Summarize the historical tool result for a coding agent.',
+    'Keep exact paths, identifiers, errors, numbers, negations, and every required fact.',
+    'Preserved facts must be copied verbatim from the tool result or required-facts list; do not invent or estimate counts.',
+    'Return JSON only with schema, summary, and preservedFacts fields.',
+    `Provider: ${provider ?? 'unknown'}`,
+    `Model: ${model ?? 'unknown'}`,
+    `Tool: ${toolName ?? 'unknown'}`,
+    `Required facts: ${required.length ? required.join(', ') : '(none)'}`,
+    `<tool_result>\n${text}\n</tool_result>`,
+  ].join('\n');
+}
+
+export function validateSemanticSummary({ originalText, summary, requiredFacts = [], maxSummaryRatio = DEFAULT_POLICY.maxSummaryRatio } = {}) {
+  if (typeof originalText !== 'string' || typeof summary !== 'string') {
+    return { valid: false, reason: 'invalid-text' };
+  }
+  if (!Number.isFinite(maxSummaryRatio) || maxSummaryRatio <= 0 || maxSummaryRatio >= 1) {
+    return { valid: false, reason: 'invalid-ratio' };
+  }
+  const required = facts(requiredFacts);
+  const inputTokens = estimateTokens(originalText);
+  const outputTokens = estimateTokens(summary);
+  if (!summary.trim()) return { valid: false, reason: 'empty-summary', inputTokens, outputTokens };
+  if (outputTokens >= inputTokens) return { valid: false, reason: 'not-smaller', inputTokens, outputTokens };
+  if (outputTokens / Math.max(1, inputTokens) > maxSummaryRatio) {
+    return { valid: false, reason: 'summary-too-large', inputTokens, outputTokens };
+  }
+  const missing = required.find((fact) => !summary.includes(fact));
+  if (missing) return { valid: false, reason: 'missing-required-fact', missing, inputTokens, outputTokens };
+  if (hasSecret(summary)) return { valid: false, reason: 'secret-detected', inputTokens, outputTokens };
+  return { valid: true, inputTokens, outputTokens };
+}
+
+function cacheKey({ provider, model, toolName, text, requiredFacts }) {
+  return sha256(JSON.stringify({
+    schema: SEMANTIC_SUMMARY_SCHEMA,
+    provider: provider ?? null,
+    model: model ?? null,
+    toolName: toolName ?? null,
+    text,
+    requiredFacts,
+  }));
+}
+
+async function withTimeout(complete, request, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      const error = new Error('semantic compactor timeout');
+      error.code = 'SEMANTIC_TIMEOUT';
+      reject(error);
+    }, timeoutMs);
+  });
+  const operation = Promise.resolve().then(() => complete({ ...request, signal: controller.signal }));
+  try {
+    return await Promise.race([operation, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function createSemanticCompactor({ complete, cache = new Map(), policy } = {}) {
+  if (typeof complete !== 'function') throw new TypeError('semantic compactor complete callback is required');
+  if (!cache || typeof cache.get !== 'function' || typeof cache.set !== 'function') {
+    throw new TypeError('semantic compactor cache must implement get and set');
+  }
+  const options = validatePolicy(policy);
+
+  return async function compact({ provider, model, toolName, text, historical = true, isError = false, requiredFacts = [] } = {}) {
+    if (typeof text !== 'string') throw new TypeError('semantic compactor text must be a string');
+    const required = facts(requiredFacts);
+    const inputTokens = estimateTokens(text);
+    const base = {
+      mode: 'shadow',
+      status: 'fallback',
+      fallbackText: text,
+      inputTokens,
+      outputTokens: inputTokens,
+      grossSavedTokens: 0,
+      netSavedTokens: 0,
+      cacheHit: false,
+    };
+    if (!historical) return { ...base, status: 'skipped', reason: 'current-result' };
+    if (isError) return { ...base, status: 'skipped', reason: 'error-result' };
+    if (inputTokens < options.minInputTokens) return { ...base, status: 'skipped', reason: 'below-threshold' };
+
+    const safe = redact(text);
+    const safeFacts = required.map((fact) => redact(fact).text);
+    const prompt = buildSemanticPrompt({ provider, model, toolName, text: safe.text, requiredFacts: safeFacts });
+    const key = cacheKey({ provider, model, toolName, text: safe.text, requiredFacts: safeFacts });
+    const started = Date.now();
+    let cached;
+    try { cached = cache.get(key); } catch { cached = undefined; }
+    if (cached?.summary) {
+      const validation = validateSemanticSummary({
+        originalText: text, summary: cached.summary, requiredFacts: required,
+        maxSummaryRatio: options.maxSummaryRatio,
+      });
+      if (validation.valid) {
+        const grossSavedTokens = inputTokens - validation.outputTokens;
+        return {
+          ...base,
+          status: 'candidate',
+          summary: cached.summary,
+          outputTokens: validation.outputTokens,
+          grossSavedTokens,
+          netSavedTokens: grossSavedTokens,
+          cacheHit: true,
+          providerUsage: null,
+          latencyMs: Date.now() - started,
+          redactions: safe.count,
+        };
+      }
+      try { cache.delete?.(key); } catch { /* fail open */ }
+    }
+
+    let raw;
+    try {
+      raw = await withTimeout(complete, { provider, model, toolName, prompt, text: safe.text, requiredFacts: safeFacts }, options.timeoutMs);
+    } catch (error) {
+      return { ...base, reason: error?.code === 'SEMANTIC_TIMEOUT' ? 'timeout' : 'compactor-error', latencyMs: Date.now() - started };
+    }
+    const response = parseResponse(raw);
+    if (response?.schema !== SEMANTIC_SUMMARY_SCHEMA || typeof response.summary !== 'string'
+      || !Array.isArray(response.preservedFacts)
+      || response.preservedFacts.some((fact) => typeof fact !== 'string')) {
+      return { ...base, reason: 'invalid-response', latencyMs: Date.now() - started };
+    }
+    if (response.preservedFacts.some((fact) => !safe.text.includes(fact))) {
+      return { ...base, reason: 'response-ungrounded-fact', latencyMs: Date.now() - started };
+    }
+    if (required.some((fact) => !response.preservedFacts.includes(fact))) {
+      return { ...base, reason: 'response-missing-fact', latencyMs: Date.now() - started };
+    }
+    const summary = required.reduce(
+      (value, fact) => value.includes(fact) ? value : `${value}\n${fact}`,
+      response.summary,
+    );
+    const validation = validateSemanticSummary({
+      originalText: text, summary, requiredFacts: required,
+      maxSummaryRatio: options.maxSummaryRatio,
+    });
+    if (!validation.valid) return { ...base, reason: validation.reason, latencyMs: Date.now() - started };
+
+    const usage = response.usage && typeof response.usage === 'object' ? response.usage : {};
+    const compactorInputTokens = usageCounter(usage.inputTokens) ?? estimateTokens(prompt);
+    const compactorOutputTokens = usageCounter(usage.outputTokens) ?? estimateTokens(JSON.stringify(response));
+    const grossSavedTokens = inputTokens - validation.outputTokens;
+    const netSavedTokens = grossSavedTokens - compactorInputTokens - compactorOutputTokens;
+    try { cache.set(key, { summary }); } catch { /* fail open */ }
+    return {
+      ...base,
+      status: 'candidate',
+      summary,
+      outputTokens: validation.outputTokens,
+      grossSavedTokens,
+      netSavedTokens,
+      cacheHit: false,
+      providerUsage: usage,
+      compactorInputTokens,
+      compactorOutputTokens,
+      latencyMs: Date.now() - started,
+      redactions: safe.count,
+    };
+  };
+}

package/src/statusline.mjs

@@ -0,0 +1,100 @@
+import {
+  buildMetricsReport,
+  defaultMetricsPath,
+  readMetrics,
+} from './metrics.mjs';
+import {
+  buildProviderUsageReport,
+  defaultProviderUsagePath,
+  readProviderUsage,
+} from './provider-usage.mjs';
+
+export const STATUSLINE_MAX_AGE_MS = 5 * 60 * 1000;
+
+function latestAt(records) {
+  const timestamp = records.reduce((latest, item) => {
+    const value = Date.parse(item.at);
+    return Number.isFinite(value) && value > latest ? value : latest;
+  }, Number.NEGATIVE_INFINITY);
+  return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : undefined;
+}
+
+function scopedRecords(records, { host, sessionId } = {}) {
+  return records.filter((item) => {
+    if (host !== undefined && item.host !== host) return false;
+    if (sessionId !== undefined && item.sessionId !== sessionId) return false;
+    return true;
+  });
+}
+
+function readMetricsSnapshot(metricsPath, { host, sessionId, model } = {}) {
+  try {
+    const state = readMetrics(metricsPath);
+    const records = scopedRecords(state.records, { host, sessionId });
+    if (!records.length) return undefined;
+    const report = buildMetricsReport({ ...state, records }, { sessionId });
+    const hasProvider = records.some((item) => item.providerReportedSavingsTokens !== null);
+    const hasEstimate = records.some((item) => item.providerReportedSavingsTokens === null);
+    const providerSavings = report.cumulative.providerReportedSavingsTokens;
+    const source = hasProvider && !hasEstimate && providerSavings !== null
+      ? 'provider-reported' : 'estimate';
+    const latest = [...records].sort((left, right) => left.at.localeCompare(right.at)).at(-1);
+    return {
+      updatedAt: latestAt(records), source,
+      model: model ?? latest?.model,
+      savedTokens: source === 'provider-reported'
+        ? providerSavings : report.cumulative.estimatedTransformSavingsTokens,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function readProviderSnapshot(providerUsagePath, { host, sessionId } = {}) {
+  try {
+    const state = readProviderUsage(providerUsagePath);
+    const records = scopedRecords(state.records, { host, sessionId });
+    if (!records.length) return undefined;
+    return { ...buildProviderUsageReport({ ...state, records }), updatedAt: latestAt(records) };
+  } catch {
+    return undefined;
+  }
+}
+
+export function readStatusSnapshot({
+  metricsPath = defaultMetricsPath(),
+  providerUsagePath = defaultProviderUsagePath(),
+  host,
+  sessionId,
+  model,
+} = {}) {
+  return {
+    metrics: readMetricsSnapshot(metricsPath, { host, sessionId, model }),
+    providerUsage: readProviderSnapshot(providerUsagePath, { host, sessionId }),
+  };
+}
+
+function compactTokens(value) {
+  if (value < 1_000) return String(value);
+  if (value < 1_000_000) return `${Number((value / 1_000).toFixed(1))}k`;
+  return `${Number((value / 1_000_000).toFixed(2))}M`;
+}
+
+// The rate is the session's own blended $/token (totalCostUsd / totalTokens),
+// so cache reads (0.1x) and cache writes (1.25x/2x) are already folded in:
+// it's the harness's real billed rate, not a reconstructed list price.
+function compactCost(tokens, effectiveRate) {
+  return `$${(tokens * effectiveRate).toFixed(2)}`;
+}
+
+export function renderStatusLine({ metrics, providerUsage, totalCostUsd } = {}, _now = Date.now()) {
+  if (!metrics || !['estimate', 'provider-reported'].includes(metrics.source)
+    || !Number.isSafeInteger(metrics.savedTokens) || metrics.savedTokens <= 0) return '🥪 —';
+  const estimated = metrics.source === 'estimate';
+  const savings = `${estimated ? '~' : ''}${compactTokens(metrics.savedTokens)} token saved`;
+  const effectiveRate = Number.isFinite(totalCostUsd) && totalCostUsd > 0
+    && Number.isSafeInteger(providerUsage?.totalTokens) && providerUsage.totalTokens > 0
+    ? totalCostUsd / providerUsage.totalTokens : undefined;
+  const cost = effectiveRate === undefined ? undefined : compactCost(metrics.savedTokens, effectiveRate);
+  return `🥪 ${[savings, cost && `(-${cost})`].filter(Boolean).join(' ')}`;
+}