cadet-agent 0.20.2 → 0.24.0

package/src/harness/archive.mjs

@@ -0,0 +1,242 @@
+/**
+ * Cadet-Agent archive safety.
+ *
+ * A hardened, zero-dependency ZIP reader/extractor with explicit containment and
+ * resource limits. Rejects absolute paths, traversal after canonicalization,
+ * paths outside the target directory, oversized filenames, too many files,
+ * oversized compressed/uncompressed totals, and excessive compression ratios.
+ * Validates central-directory and local-header bounds before allocating, and
+ * verifies CRC-32 when present.
+ *
+ * Contract: docs/core/HarnessContract.md §9 (archive safety).
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, normalize, resolve, sep } from 'node:path';
+import { inflateRawSync } from 'node:zlib';
+
+export const SIG_EOCD = 0x06054b50;
+export const SIG_CD = 0x02014b50;
+export const SIG_LFH = 0x04034b50;
+
+const MIB = 1024 * 1024;
+
+/** Default archive limits (mirrors policy DEFAULT_ARCHIVE_LIMITS). */
+export const DEFAULT_ARCHIVE_LIMITS = Object.freeze({
+  maxCompressedBytes: 25 * MIB,
+  maxDecompressedBytes: 100 * MIB,
+  maxFiles: 2000,
+  maxFilenameBytes: 240,
+  maxCompressionRatio: 100,
+});
+
+export class ArchiveError extends Error {
+  constructor(message, code = 'archive-error') {
+    super(message);
+    this.name = 'ArchiveError';
+    this.code = code;
+  }
+}
+
+function read32(buf, off) { return buf.readUInt32LE(off); }
+function read16(buf, off) { return buf.readUInt16LE(off); }
+
+/** CRC-32 (IEEE) table, computed once. */
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xEDB88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+export function crc32(buf) {
+  let crc = 0xFFFFFFFF;
+  for (let i = 0; i < buf.length; i++) crc = CRC_TABLE[(crc ^ buf[i]) & 0xFF] ^ (crc >>> 8);
+  return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+export function findEocd(buf) {
+  if (buf.length < 22) throw new ArchiveError('Not a valid ZIP file: too short', 'not-a-zip');
+  const maxStart = Math.max(0, buf.length - 65535 - 22);
+  for (let i = buf.length - 22; i >= maxStart; i--) {
+    if (read32(buf, i) === SIG_EOCD) return i;
+  }
+  throw new ArchiveError('Not a valid ZIP file: EOCD signature not found', 'not-a-zip');
+}
+
+/**
+ * Validate that a resolved output path stays inside the target directory.
+ * Rejects absolute paths and any traversal that escapes after canonicalization.
+ */
+export function assertContained(targetDir, entryName) {
+  const raw = entryName.replace(/\\/g, '/');
+  if (raw.startsWith('/') || /^[a-zA-Z]:\//.test(raw)) {
+    throw new ArchiveError(`archive entry uses an absolute path: ${entryName}`, 'absolute-path');
+  }
+  const resolvedRoot = resolve(targetDir);
+  const resolved = resolve(join(targetDir, raw));
+  if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + sep)) {
+    throw new ArchiveError(`archive entry escapes the target directory: ${entryName}`, 'traversal');
+  }
+  return resolved;
+}
+
+function validateEntry(entry, limits, running) {
+  const nameBytes = Buffer.byteLength(entry.filename, 'utf-8');
+  if (nameBytes > limits.maxFilenameBytes) {
+    throw new ArchiveError(`archive entry filename exceeds ${limits.maxFilenameBytes} bytes: ${entry.filename.slice(0, 60)}`, 'filename-too-long');
+  }
+  if (entry.uncompressedSize > limits.maxDecompressedBytes || running.uncompressed + entry.uncompressedSize > limits.maxDecompressedBytes) {
+    throw new ArchiveError(`decompressed size exceeds ${limits.maxDecompressedBytes} bytes`, 'decompressed-too-large');
+  }
+  if (entry.compressedSize > limits.maxCompressedBytes || running.compressed + entry.compressedSize > limits.maxCompressedBytes) {
+    throw new ArchiveError(`compressed size exceeds ${limits.maxCompressedBytes} bytes`, 'compressed-too-large');
+  }
+  if (entry.uncompressedSize > 0 && entry.compressedSize > 0) {
+    const ratio = entry.uncompressedSize / entry.compressedSize;
+    if (ratio > limits.maxCompressionRatio) {
+      throw new ArchiveError(`compression ratio ${ratio.toFixed(1)}:1 exceeds ${limits.maxCompressionRatio}:1 for ${entry.filename}`, 'compression-ratio');
+    }
+  }
+}
+
+/**
+ * Iterate central-directory entries with bounds checking. Directory entries are
+ * yielded too (`isDirectory: true`) so callers can decide what to do, but the
+ * default extractor skips them.
+ */
+export function* readEntries(buf, limits = DEFAULT_ARCHIVE_LIMITS) {
+  const eocdOff = findEocd(buf);
+  const cdSize = read32(buf, eocdOff + 12);
+  const cdOff = read32(buf, eocdOff + 16);
+  const totalEntries = read16(buf, eocdOff + 10);
+
+  if (cdOff === 0xFFFFFFFF || cdSize === 0xFFFFFFFF) {
+    throw new ArchiveError('ZIP64 format is not supported', 'zip64');
+  }
+  if (cdOff + cdSize > buf.length) {
+    throw new ArchiveError('central directory extends past the end of the archive', 'malformed');
+  }
+  if (totalEntries > limits.maxFiles) {
+    throw new ArchiveError(`archive declares ${totalEntries} files, over the limit of ${limits.maxFiles}`, 'too-many-files');
+  }
+
+  const running = { compressed: 0, uncompressed: 0, files: 0 };
+  let off = cdOff;
+  const end = cdOff + cdSize;
+  while (off + 46 <= end) {
+    if (read32(buf, off) !== SIG_CD) {
+      throw new ArchiveError('malformed central directory entry', 'malformed');
+    }
+    const method = read16(buf, off + 10);
+    const crc = read32(buf, off + 16);
+    const compressedSize = read32(buf, off + 20);
+    const uncompressedSize = read32(buf, off + 24);
+    const filenameLen = read16(buf, off + 28);
+    const extraLen = read16(buf, off + 30);
+    const commentLen = read16(buf, off + 32);
+    const localHeaderOff = read32(buf, off + 42);
+    if (off + 46 + filenameLen + extraLen + commentLen > end) {
+      throw new ArchiveError('central directory entry extends past the directory', 'malformed');
+    }
+    const filename = buf.toString('utf-8', off + 46, off + 46 + filenameLen).replace(/\\/g, '/');
+    if (localHeaderOff + 30 > buf.length) {
+      throw new ArchiveError(`local header offset out of bounds for ${filename}`, 'malformed');
+    }
+
+    const isDirectory = filename.endsWith('/');
+    const entry = { filename, method, compressedSize, uncompressedSize, localHeaderOff, crc, isDirectory };
+    if (!isDirectory) {
+      running.files++;
+      if (running.files > limits.maxFiles) {
+        throw new ArchiveError(`archive contains more than ${limits.maxFiles} files`, 'too-many-files');
+      }
+      validateEntry(entry, limits, running);
+      running.compressed += compressedSize;
+      running.uncompressed += uncompressedSize;
+    }
+    yield entry;
+    off += 46 + filenameLen + extraLen + commentLen;
+  }
+}
+
+/** Decompress one entry's payload, validating the local header and CRC. */
+export function readEntryData(buf, entry) {
+  const { localHeaderOff } = entry;
+  if (read32(buf, localHeaderOff) !== SIG_LFH) {
+    throw new ArchiveError(`local file header signature missing for ${entry.filename}`, 'malformed');
+  }
+  const lfhFilenameLen = read16(buf, localHeaderOff + 26);
+  const lfhExtraLen = read16(buf, localHeaderOff + 28);
+  const dataStart = localHeaderOff + 30 + lfhFilenameLen + lfhExtraLen;
+  if (dataStart + entry.compressedSize > buf.length) {
+    throw new ArchiveError(`entry data extends past the end of the archive: ${entry.filename}`, 'malformed');
+  }
+  const compressed = buf.subarray(dataStart, dataStart + entry.compressedSize);
+
+  let data;
+  if (entry.method === 0) {
+    data = compressed;
+  } else if (entry.method === 8) {
+    try {
+      data = inflateRawSync(compressed);
+    } catch (err) {
+      throw new ArchiveError(`failed to inflate ${entry.filename}: ${err.message}`, 'inflate-failed');
+    }
+  } else {
+    throw new ArchiveError(
+      `unsupported compression method ${entry.method} for ${entry.filename}. ` +
+      'Download cadet-agent.zip manually from https://github.com/naishtech/cadet-agent/releases/latest',
+      'unsupported-method'
+    );
+  }
+
+  if (data.length !== entry.uncompressedSize) {
+    throw new ArchiveError(`size mismatch for ${entry.filename} (expected ${entry.uncompressedSize}, got ${data.length})`, 'size-mismatch');
+  }
+  // Verify CRC when the archive provides one (0 means "not recorded").
+  if (entry.crc !== 0 && crc32(data) !== entry.crc) {
+    throw new ArchiveError(`CRC mismatch for ${entry.filename}`, 'crc-mismatch');
+  }
+  return data;
+}
+
+/**
+ * Extract a ZIP into targetDir with full containment and limit enforcement.
+ * `filter` may return `{ skip: true }` to omit an entry. Returns extracted paths.
+ */
+export function extractArchive(buf, targetDir, { limits = DEFAULT_ARCHIVE_LIMITS, filter = null } = {}) {
+  if (buf.length > limits.maxCompressedBytes) {
+    throw new ArchiveError(`archive is ${buf.length} bytes, over the compressed limit of ${limits.maxCompressedBytes}`, 'compressed-too-large');
+  }
+  const extracted = [];
+  const skipped = [];
+  for (const entry of readEntries(buf, limits)) {
+    if (entry.isDirectory) continue;
+    if (filter) {
+      const decision = filter(entry);
+      if (decision === false || decision?.skip) { skipped.push(entry.filename); continue; }
+    }
+    const outPath = assertContained(targetDir, entry.filename);
+    const data = readEntryData(buf, entry);
+    mkdirSync(join(outPath, '..'), { recursive: true });
+    writeFileSync(outPath, data);
+    extracted.push(outPath);
+  }
+  return { extracted, skipped, targetDir: normalize(targetDir) };
+}
+
+/** Read a single entry's bytes without extracting (used for the manifest). */
+export function readArchiveEntry(buf, name, limits = DEFAULT_ARCHIVE_LIMITS) {
+  const normalized = name.replace(/\\/g, '/');
+  for (const entry of readEntries(buf, limits)) {
+    if (entry.isDirectory) continue;
+    if (entry.filename.replace(/^\.\//, '') === normalized.replace(/^\.\//, '')) {
+      return readEntryData(buf, entry);
+    }
+  }
+  return null;
+}

package/src/harness/budget.mjs

@@ -0,0 +1,298 @@
+/**
+ * Cadet-Agent harness budget accounting.
+ *
+ * Deterministic counters over the resolved policy. Consumed by the ledger,
+ * verification runner, CLI, and installer. A budget result is machine-readable
+ * and can never be confused with success: `ok === false` for warnings and stops.
+ *
+ * Contract: docs/core/HarnessContract.md §3 (budgets) and §4 (estimation).
+ */
+
+import { budgetForScope, warnThreshold, PolicyError } from './policy.mjs';
+
+export const BUDGET_RESULTS = Object.freeze(['ok', 'warning', 'exhausted']);
+
+const COUNTER_TO_BUDGET = Object.freeze({
+  contextTokens: 'maxContextTokens',
+  outputTokens: 'maxOutputTokens',
+  toolCalls: 'maxToolCalls',
+  retries: 'maxTotalRetries',
+  wallClockMs: 'maxWallClockMs',
+  estimatedCostUsd: 'maxEstimatedCostUsd',
+  downloadedBytes: 'maxDownloadedBytes',
+  decompressedBytes: 'maxDecompressedBytes',
+  archiveFiles: 'maxArchiveFiles',
+});
+
+/** Per-something counters that are tracked separately from the run totals. */
+function emptyCounters() {
+  return {
+    contextTokens: 0,
+    outputTokens: 0,
+    toolCalls: 0,
+    retries: 0,
+    wallClockMs: 0,
+    estimatedCostUsd: 0,
+    downloadedBytes: 0,
+    decompressedBytes: 0,
+    archiveFiles: 0,
+  };
+}
+
+function requireNonNegative(name, value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    throw new PolicyError(`Budget counter "${name}" must be a non-negative finite number (got ${value}).`);
+  }
+}
+
+/**
+ * A budget tracker for one scope (a run or a story).
+ * Immutable reads: `snapshot()` is a frozen copy.
+ */
+export class BudgetTracker {
+  constructor(policy, scope = 'perRun') {
+    this.scope = scope;
+    this.limits = budgetForScope(policy, scope);
+    const caps = budgetForScope(policy, 'perRun');
+    this.caps = caps; // hard safety ceilings, applied on top of scope overrides
+    this.counters = emptyCounters();
+    this.events = [];
+    // Counters whose value could not be measured. An unmeasurable cost budget
+    // must never be treated as satisfied (contract §4).
+    this.unknown = new Set();
+  }
+
+  /** Mark a counter as unmeasurable (e.g. provider cost with no rate card). */
+  markUnknown(name, reason = 'value not measurable') {
+    if (!(name in this.counters)) {
+      throw new PolicyError(`Unknown budget counter "${name}".`);
+    }
+    this.unknown.add(name);
+    this.events.push({ type: 'budget-unknown', counter: name, reason, at: new Date().toISOString() });
+  }
+
+  /**
+   * Add to a counter. Throws on unknown counter or invalid value rather than
+   * silently recording a wrong number.
+   */
+  add(name, amount, meta = {}) {
+    if (!(name in this.counters)) {
+      throw new PolicyError(`Unknown budget counter "${name}".`);
+    }
+    requireNonNegative(name, amount);
+    this.counters[name] += amount;
+    if (meta.reason) {
+      this.events.push({ type: 'budget-add', counter: name, amount, reason: meta.reason, at: new Date().toISOString() });
+    }
+    return this.evaluate(name);
+  }
+
+  set(name, value) {
+    if (!(name in this.counters)) {
+      throw new PolicyError(`Unknown budget counter "${name}".`);
+    }
+    requireNonNegative(name, value);
+    this.counters[name] = value;
+    return this.evaluate(name);
+  }
+
+  /** Evaluate one counter (or all) against its budget. */
+  evaluate(name) {
+    const names = name ? [name] : Object.keys(this.counters);
+    const checks = names.map((n) => this.check(n));
+    const worst = checks.reduce((acc, c) => (c.status === 'exhausted' ? c : acc.status === 'exhausted' ? acc : c.status === 'warning' ? c : acc), { status: 'ok' });
+    return {
+      status: worst.status,
+      ok: worst.status === 'ok',
+      exhausted: worst.status === 'exhausted',
+      checks,
+    };
+  }
+
+  check(name) {
+    const budgetKey = COUNTER_TO_BUDGET[name];
+    const limit = this.limits[budgetKey];
+    const cap = this.caps[budgetKey] || limit;
+    const used = this.counters[name];
+    const hard = Math.min(limit?.hard ?? Infinity, cap?.hard ?? Infinity);
+    const warn = limit ? warnThreshold(limit) : null;
+    let status = 'ok';
+    if (hard !== Infinity && used >= hard) status = 'exhausted';
+    else if (warn !== null && used >= warn) status = 'warning';
+    return {
+      counter: name,
+      budget: budgetKey,
+      used,
+      hard: hard === Infinity ? null : hard,
+      warn,
+      remaining: hard === Infinity ? null : Math.max(0, hard - used),
+      fraction: hard && hard !== Infinity ? used / hard : 0,
+      status,
+    };
+  }
+
+  /** Per-step retry check; `maxRetriesPerStep` is separate from the run total. */
+  checkStepRetries(stepRetries) {
+    const per = this.limits.maxRetriesPerStep?.hard ?? Infinity;
+    const total = this.check('retries');
+    let status = 'ok';
+    if (stepRetries >= per) status = 'exhausted';
+    else if (stepRetries + 1 >= per) status = 'warning';
+    if (total.status === 'exhausted') status = 'exhausted';
+    else if (status === 'ok' && total.status === 'warning') status = 'warning';
+    return {
+      counter: 'retriesPerStep',
+      used: stepRetries,
+      hard: per === Infinity ? null : per,
+      remaining: per === Infinity ? null : Math.max(0, per - stepRetries),
+      status,
+    };
+  }
+
+  snapshot() {
+    const checks = Object.keys(this.counters).map((n) => this.check(n));
+    return Object.freeze({
+      scope: this.scope,
+      counters: { ...this.counters },
+      checks,
+      events: [...this.events],
+    });
+  }
+
+  /** Machine-readable final result. `ok` is true only when every budget is within limits. */
+  result() {
+    const evaluation = this.evaluate();
+    const unknownCost = this.unknown.has('estimatedCostUsd');
+    return {
+      status: evaluation.status,
+      ok: evaluation.status === 'ok' && !unknownCost,
+      exhausted: evaluation.status === 'exhausted',
+      checks: evaluation.checks,
+      counters: { ...this.counters },
+      unknown: [...this.unknown],
+      costUnmeasurable: unknownCost,
+    };
+  }
+}
+
+/**
+ * A hard-stop result. Always `ok: false` — callers must never treat this as success.
+ */
+export function budgetExhaustedResult(reason, detail = {}) {
+  return {
+    status: 'exhausted',
+    ok: false,
+    exhausted: true,
+    exitCode: 3,
+    code: 'budget-exhausted',
+    reason,
+    ...detail,
+  };
+}
+
+/** Compute a consumption report row for display (no secrets involved). */
+export function budgetReport(tracker) {
+  return tracker.result().checks.map((c) => ({
+    budget: c.budget,
+    used: c.used,
+    hard: c.hard,
+    remaining: c.remaining,
+    overage: c.hard !== null && c.used > c.hard,
+    status: c.status,
+  }));
+}
+
+/**
+ * Evaluate all tracked counters for a hard stop. Returns
+ * `{ exhausted, reason, checks }`. A hard stop must block the operation, not
+ * merely record a warning.
+ */
+export function evaluateHardStop(tracker) {
+  const result = tracker.result();
+  if (result.exhausted) {
+    const first = result.checks.find((c) => c.status === 'exhausted');
+    return {
+      exhausted: true,
+      blocked: true,
+      reason: first ? `${first.budget} budget exhausted (used ${first.used} of ${first.hard})` : 'budget exhausted',
+      checks: result.checks,
+    };
+  }
+  if (result.costUnmeasurable) {
+    const costCheck = result.checks.find((c) => c.counter === 'estimatedCostUsd');
+    // Only block when a cost budget is actually configured.
+    if (costCheck && costCheck.hard !== null) {
+      return {
+        exhausted: false,
+        blocked: true,
+        reason: 'provider cost is unmeasurable (no rate card); the cost budget cannot be confirmed',
+        checks: result.checks,
+      };
+    }
+  }
+  return { exhausted: false, blocked: false, reason: null, checks: result.checks };
+}
+
+/**
+ * Estimate tokens from UTF-8 byte length (contract §4).
+ * Marked as an estimate so it can never be mistaken for provider telemetry.
+ */
+export function estimateTokens(textOrBytes, policy) {
+  const bytes = typeof textOrBytes === 'number'
+    ? textOrBytes
+    : Buffer.byteLength(String(textOrBytes ?? ''), 'utf-8');
+  const per = policy?.estimation?.bytesPerToken || 3;
+  return {
+    tokens: Math.ceil(bytes / per),
+    bytes,
+    source: 'estimate',
+    confidence: 'low',
+  };
+}
+
+/**
+ * Estimate provider cost from tokens and a rate card.
+ * Returns `{ known: false }` when no rate card exists — USD is never invented.
+ */
+export function estimateCost(inputTokens, outputTokens, policy) {
+  const model = policy?.model;
+  const card = model && policy?.estimation?.rateCards?.[model];
+  if (!card) {
+    return { known: false, usd: null, source: 'unknown', model: model || null };
+  }
+  const usd = inputTokens * (card.inputRate ?? 0) + outputTokens * (card.outputRate ?? 0);
+  return {
+    known: true,
+    usd: Math.round(usd * 10000) / 10000,
+    source: 'estimate',
+    model,
+    rateCardId: card.id || model,
+    effectiveDate: card.effectiveDate || null,
+  };
+}
+
+/** Normalize provider or estimated usage. Unknown is `unknown`, never zero. */
+export function normalizeUsage(usage, policy) {
+  if (!usage || (usage.inputTokens === undefined && usage.outputTokens === undefined && usage.bytes === undefined)) {
+    return { source: 'unknown', inputTokens: null, outputTokens: null, confidence: 'unknown' };
+  }
+  if (usage.source === 'provider') {
+    return {
+      source: 'provider',
+      inputTokens: usage.inputTokens ?? 0,
+      outputTokens: usage.outputTokens ?? 0,
+      cachedTokens: usage.cachedTokens ?? null,
+      confidence: 'high',
+    };
+  }
+  const est = estimateTokens(usage.bytes ?? 0, policy);
+  return {
+    source: 'estimate',
+    inputTokens: usage.inputTokens ?? est.tokens,
+    outputTokens: usage.outputTokens ?? 0,
+    cachedTokens: null,
+    confidence: est.confidence,
+  };
+}
+
+export { COUNTER_TO_BUDGET };