@codelionapps/unharness 0.0.0-stage → 0.1.0

package/src/collector.ts

@@ -0,0 +1,178 @@
+import { createServer, type Server } from 'node:http';
+import { gunzipSync } from 'node:zlib';
+import { saveBundle, tx, type DB } from './db.ts';
+import { eve, sessionKey } from './adapters/eve.ts';
+import type { OtelSpan } from './types.ts';
+
+// Local OTLP/HTTP JSON trace receiver for eve. Spans are stripped to a metadata whitelist BEFORE storage,
+// staged in otel_span, then each touched session is re-derived via eve.fromSpans and saved delete-and-replace.
+
+const MAX_BODY = 20 * 1024 * 1024;
+
+// Only ids, names, model/provider, usage counts, action kinds/outcomes, run linkage, error type.
+// Everything else (prompts, responses, tool args/results, error messages, ...) is dropped at the door.
+const KEEP = new Set([
+  'agent.run.id', 'ai.telemetry.metadata.sessionId', 'ai.telemetry.metadata.session_id', 'gen_ai.conversation.id',
+  'gen_ai.operation.name', 'agent.invocation.role', 'agent.turn.id', 'agent.turn.outcome',
+  'agent.run.type', 'agent.parent_run.id', 'agent.parent_call.id', 'agent.subagent.name',
+  'agent.name', 'gen_ai.agent.name', 'agent.framework.name', 'agent.framework.version',
+  'gen_ai.request.model', 'gen_ai.response.model', 'agent.model.id', 'ai.model.id', 'ai.model.provider', 'gen_ai.provider.name', 'gen_ai.system',
+  'gen_ai.usage.input_tokens', 'gen_ai.usage.output_tokens', 'gen_ai.usage.cache_read.input_tokens',
+  'gen_ai.usage.cache_write.input_tokens', 'gen_ai.usage.cache_creation.input_tokens',
+  'ai.usage.inputTokens', 'ai.usage.outputTokens', 'ai.usage.promptTokens', 'ai.usage.completionTokens',
+  'ai.usage.cachedInputTokens', 'ai.usage.reasoningTokens', 'ai.usage.inputTokenDetails.cacheReadTokens',
+  'ai.usage.inputTokenDetails.cacheWriteTokens', 'ai.usage.outputTokenDetails.reasoningTokens',
+  'gen_ai.tool.name', 'gen_ai.tool.call.id', 'ai.toolCall.name', 'ai.toolCall.id',
+  'agent.action.kind', 'agent.action.name', 'agent.action.outcome', 'error.type',
+  'otel.scope.name', 'otel.scope.version',
+]);
+
+type Attr = OtelSpan['attrs'][string];
+const anyValue = (v: any): Attr | undefined => {
+  if (!v || typeof v !== 'object') return undefined;
+  if ('stringValue' in v) return String(v.stringValue);
+  if ('intValue' in v) return Number(v.intValue); // JS exporters send a number, others a decimal string
+  if ('doubleValue' in v) return Number(v.doubleValue);
+  if ('boolValue' in v) return Boolean(v.boolValue);
+  if ('arrayValue' in v) return (v.arrayValue?.values ?? []).map((x: any) => String(anyValue(x) ?? ''));
+  return undefined; // kvlist/bytes: nothing we need
+};
+const attrMap = (list: any): OtelSpan['attrs'] => {
+  const out: OtelSpan['attrs'] = {};
+  for (const kv of Array.isArray(list) ? list : []) {
+    const v = anyValue(kv?.value);
+    if (typeof kv?.key === 'string' && v !== undefined) out[kv.key] = v;
+  }
+  return out;
+};
+
+// Unix nanos as a decimal string, or undefined if malformed (eve.ts BigInt()s these; one bad span would 400 its session forever).
+// JSON numbers are accepted when integral (ns values exceed 2^53, so they're already rounded to ~256ns; fine for ms).
+const nanos = (v: unknown): string | undefined =>
+  typeof v === 'string' && /^\d{1,19}$/.test(v) ? v
+  : typeof v === 'number' && Number.isInteger(v) && v >= 0 && v < 1e19 ? BigInt(v).toString()
+  : undefined;
+
+// ExportTraceServiceRequest (JSON) -> flat spans. Scope name/version are folded into `resource`.
+// Spans with malformed timestamps are skipped and counted in `skipped.n`.
+export function decodeOtlp(body: unknown, skipped = { n: 0 }): OtelSpan[] {
+  const spans: OtelSpan[] = [];
+  for (const rs of (body as any)?.resourceSpans ?? []) {
+    const resource = attrMap(rs?.resource?.attributes);
+    for (const ss of rs?.scopeSpans ?? []) {
+      const scope = { ...resource, 'otel.scope.name': String(ss?.scope?.name ?? ''), 'otel.scope.version': String(ss?.scope?.version ?? '') };
+      for (const s of ss?.spans ?? []) {
+        if (typeof s?.spanId !== 'string' || !s.spanId) continue;
+        const start = nanos(s.startTimeUnixNano);
+        const end = s.endTimeUnixNano == null ? start : nanos(s.endTimeUnixNano);
+        if (!start || !end) { skipped.n++; continue; }
+        spans.push({
+          trace_id: String(s.traceId ?? ''),
+          span_id: s.spanId,
+          parent_span_id: s.parentSpanId || null,
+          name: String(s.name ?? ''),
+          start_ns: start,
+          end_ns: end,
+          status_code: Number(s.status?.code ?? 0),
+          attrs: attrMap(s.attributes),
+          resource: scope,
+        });
+      }
+    }
+  }
+  return spans;
+}
+
+const whitelist = (a: OtelSpan['attrs']) => Object.fromEntries(Object.entries(a).filter(([k]) => KEEP.has(k)));
+
+// Span names can carry anything (e.g. @vercel/otel `fetch GET https://...?api_key=...`). Only spans eve.ts can use are
+// stored, and their name only if it has a known shape: eve's `chat <model>` / `execute_tool <tool>` / `invoke_agent <agent>`
+// (model/tool/agent names only), `agent.step`, or AI SDK `ai.*` (eve.ts matches ai.*.doStream/doGenerate, ai.toolCall).
+const EVE_NAME = /^(?:invoke_agent|chat|execute_tool)(?: (?!.*\/\/)[\w.:@\/-]{1,128})?$|^agent\.step$/;
+const AI_NAME = /^ai\.[\w.]{1,128}$/;
+const opName = (s: OtelSpan) => { const v = s.attrs['gen_ai.operation.name'] ?? s.resource['gen_ai.operation.name']; return v == null ? null : String(v); };
+const usable = (s: OtelSpan) => opName(s) != null || EVE_NAME.test(s.name) || AI_NAME.test(s.name);
+const safeName = (s: OtelSpan) => (EVE_NAME.test(s.name) || AI_NAME.test(s.name) ? s.name : opName(s));
+
+const loadSpans = (db: DB, keys: string[]): OtelSpan[] =>
+  (db.prepare(`SELECT * FROM otel_span WHERE session_id IN (${keys.map(() => '?').join(',')})`).all(...keys) as any[]).map((r) => ({
+    trace_id: r.trace_id, span_id: r.span_id, parent_span_id: r.parent_span_id, name: r.name ?? '',
+    start_ns: r.start_ns, end_ns: r.end_ns, status_code: r.status_code, attrs: JSON.parse(r.attrs), resource: {},
+  }));
+
+// Stage spans (whitelisted; resource keys merged into attrs) and rebuild every touched run.
+export async function ingest(db: DB, spans: OtelSpan[]): Promise<string[]> {
+  const touched = new Set<string>();
+  const put = db.prepare('INSERT OR REPLACE INTO otel_span VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+  const now = new Date().toISOString();
+  tx(db, () => {
+    for (const s of spans) {
+      if (!usable(s)) continue;
+      const key = sessionKey(s);
+      touched.add(key);
+      const parent = s.attrs['agent.parent_run.id'];
+      if (parent != null) touched.add(String(parent)); // parent's SubagentSpawn gains child_run_id
+      const attrs = { ...whitelist(s.resource), ...whitelist(s.attrs) };
+      put.run(s.span_id, s.trace_id, s.parent_span_id, key, safeName(s), s.start_ns, s.end_ns, s.status_code, JSON.stringify(attrs), now);
+    }
+  });
+  if (!touched.size) return [];
+  // children of touched sessions are needed so parent spawns can link to them
+  const keys = [...touched];
+  const children = db.prepare(
+    `SELECT DISTINCT session_id FROM otel_span WHERE json_extract(attrs, '$."agent.parent_run.id"') IN (${keys.map(() => '?').join(',')})`,
+  ).all(...keys) as { session_id: string }[];
+  const bundles = eve.fromSpans!(loadSpans(db, [...new Set([...keys, ...children.map((c) => c.session_id)])]));
+  for (const b of bundles) {
+    const known = db.prepare('SELECT setup_fingerprint_id FROM run WHERE id = ?').get(b.run.id) as { setup_fingerprint_id: string | null } | undefined;
+    // wait for a model before fingerprinting so an early tool-only batch doesn't pin a model-less setup
+    const fp = known?.setup_fingerprint_id || !b.requests[0] ? null : await eve.fingerprint({ cwd: null, model: b.requests[0].model, harness_version: b.run.harness_version });
+    tx(db, () => saveBundle(db, b, fp));
+  }
+  return keys;
+}
+
+const send = (res: import('node:http').ServerResponse, code: number, body: object) =>
+  res.writeHead(code, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+
+export function startCollector(db: DB, port: number): Promise<Server> {
+  const server = createServer((req, res) => {
+    if (req.method !== 'POST' || req.url?.split('?')[0] !== '/v1/traces') return send(res, 404, { error: 'POST /v1/traces only' });
+    // browsers can POST text/plain cross-origin without preflight; OTLP exporters never send Origin
+    if (req.headers.origin != null) return send(res, 403, { error: 'cross-origin requests are not accepted' });
+    const type = req.headers['content-type'] ?? '';
+    if (type.split(';')[0].trim().toLowerCase() !== 'application/json') {
+      return send(res, 415, {
+        error: `unsupported content-type "${type}": only OTLP/HTTP JSON is accepted. Set OTEL_EXPORTER_OTLP_PROTOCOL=http/json or use OTLPHttpJsonTraceExporter from @vercel/otel.`,
+      });
+    }
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on('data', (c: Buffer) => {
+      size += c.length;
+      if (size > MAX_BODY) { send(res, 413, { error: 'body too large' }); req.destroy(); }
+      else chunks.push(c);
+    });
+    req.on('end', async () => {
+      if (size > MAX_BODY) return;
+      try {
+        let buf = Buffer.concat(chunks);
+        if (/gzip/i.test(String(req.headers['content-encoding'] ?? ''))) buf = gunzipSync(buf, { maxOutputLength: 5 * MAX_BODY });
+        const skipped = { n: 0 };
+        const spans = decodeOtlp(JSON.parse(buf.toString('utf8')), skipped);
+        const sessions = await ingest(db, spans);
+        console.log(`eve: ${spans.length} spans${skipped.n ? ` (${skipped.n} with malformed timestamps skipped)` : ''}, sessions: ${sessions.join(', ') || '—'}`);
+        send(res, 200, {});
+      } catch (e) {
+        send(res, 400, { error: (e as Error).message });
+      }
+    });
+  });
+  return new Promise((resolve) =>
+    server.listen(port, '127.0.0.1', () => {
+      const addr = server.address();
+      console.log(`Unharness collector on http://127.0.0.1:${typeof addr === 'object' && addr ? addr.port : port}/v1/traces`);
+      resolve(server);
+    }),
+  );
+}

package/src/db.ts

@@ -0,0 +1,182 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { repoInfo, sha256 } from './util.ts';
+import { dbFile } from './profiles.ts';
+import { deriveChecks } from './checks.ts';
+import { costOf, loadPricing } from './pricing.ts';
+import { SCHEMA_VERSION, type RunBundle, type SetupFingerprint, type SourceRef } from './types.ts';
+
+// Migrations indexed by PRAGMA user_version. Append only.
+const MIGRATIONS = [
+  `
+  CREATE TABLE run (
+    id TEXT PRIMARY KEY, harness TEXT NOT NULL, harness_version TEXT, user TEXT, machine_id TEXT,
+    repo TEXT, branch TEXT, started_at TEXT NOT NULL, ended_at TEXT NOT NULL,
+    setup_fingerprint_id TEXT, parent_run_id TEXT, resumed_from_run_id TEXT, outcome TEXT,
+    active_ms INTEGER, tool_ms INTEGER, schema_version INTEGER NOT NULL
+  );
+  CREATE INDEX run_ended ON run(ended_at);
+  CREATE INDEX run_parent ON run(parent_run_id);
+  CREATE TABLE run_tag (run_id TEXT NOT NULL, tag TEXT NOT NULL, PRIMARY KEY (run_id, tag));
+  CREATE INDEX run_tag_tag ON run_tag(tag);
+  CREATE TABLE request (
+    run_id TEXT NOT NULL REFERENCES run(id) ON DELETE CASCADE, seq INTEGER NOT NULL, ts TEXT,
+    model TEXT, provider TEXT, input INTEGER, output INTEGER, cache_read INTEGER,
+    cache_write_5m INTEGER, cache_write_1h INTEGER, reasoning INTEGER, token_breakdown TEXT,
+    duration_ms INTEGER, cost_usd REAL, pricing_version TEXT, PRIMARY KEY (run_id, seq)
+  );
+  CREATE TABLE tool_call (
+    run_id TEXT NOT NULL REFERENCES run(id) ON DELETE CASCADE, seq INTEGER NOT NULL, request_seq INTEGER,
+    tool_name TEXT, tool_kind TEXT, mcp_server TEXT, status TEXT, duration_ms INTEGER, result_tokens INTEGER,
+    PRIMARY KEY (run_id, seq)
+  );
+  CREATE TABLE skill_invocation (
+    run_id TEXT NOT NULL REFERENCES run(id) ON DELETE CASCADE, seq INTEGER NOT NULL,
+    skill_name TEXT, source TEXT, tokens_loaded INTEGER, PRIMARY KEY (run_id, seq)
+  );
+  CREATE TABLE subagent_spawn (
+    run_id TEXT NOT NULL REFERENCES run(id) ON DELETE CASCADE, seq INTEGER NOT NULL,
+    child_run_id TEXT, agent_type TEXT, status TEXT, PRIMARY KEY (run_id, seq)
+  );
+  CREATE TABLE compaction (
+    run_id TEXT NOT NULL REFERENCES run(id) ON DELETE CASCADE, seq INTEGER NOT NULL,
+    at_request_seq INTEGER, trigger TEXT, tokens_before INTEGER, tokens_after INTEGER, PRIMARY KEY (run_id, seq)
+  );
+  CREATE TABLE file_access (
+    run_id TEXT NOT NULL REFERENCES run(id) ON DELETE CASCADE, path TEXT NOT NULL, op TEXT NOT NULL,
+    count INTEGER, PRIMARY KEY (run_id, path, op)
+  );
+  CREATE TABLE check_run (
+    run_id TEXT NOT NULL REFERENCES run(id) ON DELETE CASCADE, seq INTEGER NOT NULL,
+    check_class TEXT, runner TEXT, exit_code INTEGER, passed INTEGER, duration_ms INTEGER, seq_in_run INTEGER,
+    PRIMARY KEY (run_id, seq)
+  );
+  CREATE TABLE setup_fingerprint (id TEXT PRIMARY KEY, created_at TEXT NOT NULL);
+  CREATE TABLE setup_component (
+    fingerprint_id TEXT NOT NULL REFERENCES setup_fingerprint(id) ON DELETE CASCADE,
+    kind TEXT NOT NULL, name TEXT NOT NULL, hash TEXT, content_ref TEXT, PRIMARY KEY (fingerprint_id, kind, name)
+  );
+  CREATE TABLE source_file (
+    path_hash TEXT PRIMARY KEY, adapter TEXT, size INTEGER, mtime_ms REAL, parser_version INTEGER, imported_at TEXT
+  );
+  CREATE TABLE otel_span (
+    span_id TEXT PRIMARY KEY, trace_id TEXT, parent_span_id TEXT, session_id TEXT, name TEXT,
+    start_ns TEXT, end_ns TEXT, status_code INTEGER, attrs TEXT, received_at TEXT
+  );
+  CREATE INDEX otel_span_session ON otel_span(session_id);
+  `,
+];
+
+export type DB = DatabaseSync;
+
+export function openDb(file = dbFile()): DB {
+  if (file !== ':memory:') mkdirSync(path.dirname(file), { recursive: true });
+  const db = new DatabaseSync(file);
+  db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON;');
+  const { user_version } = db.prepare('PRAGMA user_version').get() as { user_version: number };
+  if (user_version > MIGRATIONS.length) {
+    db.close();
+    throw new Error(`${file} was created by a newer Unharness (schema v${user_version}; this version supports v${MIGRATIONS.length}). Update: npm i -g @codelionapps/unharness`);
+  }
+  for (let v = user_version; v < MIGRATIONS.length; v++) {
+    tx(db, () => {
+      db.exec(MIGRATIONS[v]);
+      db.exec(`PRAGMA user_version = ${v + 1}`);
+    });
+  }
+  return db;
+}
+
+export function tx<T>(db: DB, fn: () => T): T {
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const r = fn();
+    db.exec('COMMIT');
+    return r;
+  } catch (e) {
+    db.exec('ROLLBACK');
+    throw e;
+  }
+}
+
+function insert(db: DB, table: string, row: Record<string, unknown>) {
+  const keys = Object.keys(row);
+  db.prepare(`INSERT INTO ${table} (${keys.join(',')}) VALUES (${keys.map(() => '?').join(',')})`)
+    .run(...keys.map((k) => toSql(row[k])));
+}
+
+const toSql = (v: unknown) =>
+  v === undefined ? null : typeof v === 'boolean' ? Number(v) : v !== null && typeof v === 'object' ? JSON.stringify(v) : (v as string | number | null);
+
+export function saveFingerprint(db: DB, fp: SetupFingerprint) {
+  if (db.prepare('SELECT 1 FROM setup_fingerprint WHERE id = ?').get(fp.id)) return;
+  insert(db, 'setup_fingerprint', { id: fp.id, created_at: new Date().toISOString() });
+  for (const c of fp.components) insert(db, 'setup_component', { fingerprint_id: fp.id, ...c, content_ref: null });
+}
+
+// Delete-and-replace one run. Preserves manual tags (separate table), outcome and the fingerprint
+// recorded at first import. Derives checks from bash tool calls and prices requests.
+export function saveBundle(db: DB, b: RunBundle, fingerprint?: SetupFingerprint | null) {
+  const pricing = loadPricing();
+  const prev = db.prepare('SELECT setup_fingerprint_id, outcome FROM run WHERE id = ?').get(b.run.id) as
+    | { setup_fingerprint_id: string | null; outcome: string | null } | undefined;
+  // a re-imported (grown) session keeps the price its old requests were imported with; `sync --reprice` updates all
+  const oldCost = new Map((db.prepare('SELECT seq, model, cost_usd, pricing_version FROM request WHERE run_id = ?').all(b.run.id) as any[])
+    .map((r) => [`${r.seq}\0${r.model}`, r]));
+  db.prepare('DELETE FROM run WHERE id = ?').run(b.run.id);
+
+  let fpId = prev?.setup_fingerprint_id ?? b.run.setup_fingerprint_id;
+  if (!fpId && fingerprint) {
+    saveFingerprint(db, fingerprint);
+    fpId = fingerprint.id;
+  }
+  insert(db, 'run', {
+    ...b.run, setup_fingerprint_id: fpId, outcome: prev?.outcome ?? b.run.outcome, schema_version: SCHEMA_VERSION,
+  });
+  for (const r of b.requests) {
+    const old = oldCost.get(`${r.seq}\0${r.model}`);
+    const cost = old?.pricing_version ? old.cost_usd : costOf(r, pricing);
+    insert(db, 'request', { run_id: b.run.id, ...r, token_breakdown: null, cost_usd: cost, pricing_version: old?.pricing_version ?? (cost == null ? null : pricing.version) });
+  }
+  for (const t of b.toolCalls) {
+    const { command: _c, exit_code: _e, output: _o, ...rest } = t; // in-memory only, never persisted
+    insert(db, 'tool_call', { run_id: b.run.id, ...rest });
+  }
+  b.skills.forEach((s, seq) => insert(db, 'skill_invocation', { run_id: b.run.id, seq, ...s }));
+  b.subagents.forEach((s, seq) => insert(db, 'subagent_spawn', { run_id: b.run.id, seq, ...s }));
+  b.compactions.forEach((c, seq) => insert(db, 'compaction', { run_id: b.run.id, seq, ...c }));
+  const files = new Map<string, number>();
+  for (const f of b.files) files.set(`${f.op}\0${f.path}`, (files.get(`${f.op}\0${f.path}`) ?? 0) + f.count);
+  for (const [k, count] of files) {
+    const [op, p] = k.split('\0');
+    insert(db, 'file_access', { run_id: b.run.id, path: p, op, count });
+  }
+  const checks = b.checks.length ? b.checks : deriveChecks(b.toolCalls, repoInfo(b.cwd).root, b.cwd);
+  checks.forEach((c, seq) => insert(db, 'check_run', { run_id: b.run.id, seq, ...c }));
+}
+
+// Incremental import bookkeeping. Paths are hashed so no absolute path lands in the DB.
+export function isImported(db: DB, adapter: string, src: SourceRef, parserVersion: number): boolean {
+  const row = db.prepare('SELECT size, mtime_ms, parser_version FROM source_file WHERE path_hash = ?').get(sha256(src.path)) as
+    | { size: number; mtime_ms: number; parser_version: number } | undefined;
+  return !!row && row.size === src.size && row.mtime_ms === src.mtime_ms && row.parser_version === parserVersion;
+}
+
+export function markImported(db: DB, adapter: string, src: SourceRef, parserVersion: number) {
+  db.prepare('INSERT OR REPLACE INTO source_file VALUES (?, ?, ?, ?, ?, ?)')
+    .run(sha256(src.path), adapter, src.size, src.mtime_ms, parserVersion, new Date().toISOString());
+}
+
+export function repriceAll(db: DB): number {
+  const pricing = loadPricing();
+  const rows = db.prepare('SELECT run_id, seq, model, input, output, cache_read, cache_write_5m, cache_write_1h FROM request').all() as any[];
+  const upd = db.prepare('UPDATE request SET cost_usd = ?, pricing_version = ? WHERE run_id = ? AND seq = ?');
+  tx(db, () => {
+    for (const r of rows) {
+      const c = costOf(r, pricing);
+      upd.run(c, c == null ? null : pricing.version, r.run_id, r.seq);
+    }
+  });
+  return rows.length;
+}

package/src/fingerprint.ts

@@ -0,0 +1,60 @@
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { sha256 } from './util.ts';
+import type { SetupComponent, SetupFingerprint } from './types.ts';
+
+// Shared building blocks for adapter fingerprints. Only names + hashes leave this module.
+
+// Hash a file, or a directory recursively (sorted relative paths + contents). null if missing.
+export function hashPath(p: string): string | null {
+  if (!existsSync(p)) return null;
+  const st = statSync(p);
+  if (st.isFile()) return sha256(readFileSync(p));
+  const parts: string[] = [];
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile()) parts.push(`${path.relative(p, full)}\0${sha256(readFileSync(full))}`);
+    }
+  };
+  walk(p);
+  return sha256(parts.join('\n'));
+}
+
+// One component per entry of a directory (e.g. each skill / agent / command), named by entry.
+export function dirComponents(kind: string, dir: string, prefix = ''): SetupComponent[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => !e.name.startsWith('.'))
+    .flatMap((e) => {
+      const hash = hashPath(path.join(dir, e.name));
+      return hash ? [{ kind, name: prefix + e.name.replace(/\.md$/, ''), hash }] : [];
+    });
+}
+
+export function fileComponent(kind: string, name: string, file: string): SetupComponent[] {
+  const hash = hashPath(file);
+  return hash ? [{ kind, name, hash }] : [];
+}
+
+// Hash a JSON value after removing secret-ish keys (env, headers, tokens) at any depth.
+const SECRET = /^(env|headers|token|apikey|api_key|authorization|password|secret|bearer_token(_env_var)?)$/i;
+export function hashJson(v: unknown): string {
+  const strip = (x: unknown): unknown =>
+    Array.isArray(x) ? x.map(strip)
+      : x && typeof x === 'object'
+        ? Object.fromEntries(Object.entries(x).filter(([k]) => !SECRET.test(k)).sort(([a], [b]) => a.localeCompare(b)).map(([k, val]) => [k, strip(val)]))
+        : x;
+  return sha256(JSON.stringify(strip(v)));
+}
+
+export function valueComponent(kind: string, name: string, value: unknown): SetupComponent[] {
+  return value == null ? [] : [{ kind, name, hash: hashJson(value) }];
+}
+
+export function makeFingerprint(components: SetupComponent[]): SetupFingerprint {
+  const sorted = [...components].sort((a, b) => `${a.kind}/${a.name}`.localeCompare(`${b.kind}/${b.name}`));
+  return { id: sha256(sorted.map((c) => `${c.kind}/${c.name}=${c.hash}`).join('\n')).slice(0, 16), components: sorted };
+}