agentwrangler 0.1.0

package/dist/detector/calibration.js

@@ -0,0 +1,302 @@
+/**
+ * src/detector/calibration.ts — Bytes→token calibration for D6 (R12).
+ *
+ * Calibrates the bytes-per-token ratio used by D6 TOOL_RESULT_BLOAT by sampling
+ * real tool-result content blocks from the user's own transcripts and counting
+ * their tokens via Anthropic's free count_tokens API (no generation, no charge).
+ *
+ * Privacy gate (opt-in, OFF by default):
+ *   Calibration sends sampled tool-result TEXT to Anthropic count_tokens.
+ *   AgentWrangler's invariant is "no data leaves your machine," so calibration
+ *   requires explicit opt-in via user_config.bytes_per_token_calibration_enabled.
+ *   When disabled: no text leaves, D6 uses the default ratio, modeled_savings=null.
+ *
+ * SEC-101:
+ *   Sampled text lives in memory ONLY for the count_tokens call and is immediately
+ *   discarded. Only byte length, token count, the final ratio, and the provenance
+ *   string are stored (in user_config). No raw content ever reaches the DB, a file,
+ *   or any log.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { countTokens } from "../oauth/count-tokens.js";
+// ---------------------------------------------------------------------------
+// Default constants
+// ---------------------------------------------------------------------------
+/** Default bytes-per-token when no calibration has been run. */
+export const DEFAULT_BYTES_PER_TOKEN = 4;
+/** Fallback model when the DB has no turns or the auto-picked model 404s. */
+const FALLBACK_MODEL = "claude-sonnet-4-6";
+/** Minimum successful samples before we trust the median. */
+const MIN_SAMPLES = 30;
+/** Default maximum samples to collect. */
+const DEFAULT_MAX_SAMPLES = 150;
+/** Skip blocks larger than this (bytes). */
+const DEFAULT_MAX_BLOCK_BYTES = 100_000;
+// ---------------------------------------------------------------------------
+// user_config helpers (local; mirrors settings-store pattern)
+// ---------------------------------------------------------------------------
+export function configGet(db, key) {
+    const row = db.prepare("SELECT value FROM user_config WHERE key = ?").get(key);
+    return row?.value ?? null;
+}
+export function configSet(db, key, value) {
+    db.prepare(`INSERT INTO user_config (key, value, updated_at) VALUES (?, ?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`).run(key, value, new Date().toISOString());
+}
+/**
+ * Resolve the bytes-per-token ratio from user_config.
+ * Falls back to DEFAULT_BYTES_PER_TOKEN (4) when no calibration has been run.
+ */
+export function resolveBytesPerToken(db) {
+    const raw = configGet(db, "bytes_per_token");
+    const measuredAt = configGet(db, "bytes_per_token_measured_at");
+    const provenance = configGet(db, "bytes_per_token_provenance");
+    // Extract model from provenance ("calibrated {date} via count_tokens · model {model} · ...")
+    let model = null;
+    if (provenance !== null) {
+        const m = /· model ([^ ·]+)/.exec(provenance);
+        if (m)
+            model = m[1] ?? null;
+    }
+    if (raw === null) {
+        return {
+            ratio: DEFAULT_BYTES_PER_TOKEN,
+            calibrated: false,
+            measuredAt: null,
+            model: null,
+            provenance: null,
+        };
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return {
+            ratio: DEFAULT_BYTES_PER_TOKEN,
+            calibrated: false,
+            measuredAt: null,
+            model: null,
+            provenance: null,
+        };
+    }
+    return { ratio: parsed, calibrated: true, measuredAt, model, provenance };
+}
+/** Resolve text content from a tool_result block (string or content[].type=text). */
+function extractToolResultText(b) {
+    const content = b.content;
+    if (typeof content === "string")
+        return content || null;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const c of content) {
+            if (typeof c === "object" &&
+                c !== null &&
+                c.type === "text" &&
+                typeof c.text === "string") {
+                parts.push(c.text);
+            }
+        }
+        return parts.length > 0 ? parts.join("") : null;
+    }
+    return null;
+}
+/** Recursively collect JSONL file paths under a directory. */
+function collectJsonlPaths(dir, out, limit) {
+    if (out.length >= limit)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (out.length >= limit)
+            break;
+        if (e.isFile() && e.name.endsWith(".jsonl")) {
+            out.push(path.join(dir, e.name));
+        }
+    }
+    for (const e of entries) {
+        if (out.length >= limit)
+            break;
+        if (e.isDirectory()) {
+            collectJsonlPaths(path.join(dir, e.name), out, limit);
+        }
+    }
+}
+/**
+ * Sample tool_result text blocks from JSONL files under scanRoots.
+ *
+ * SEC-101: returned text is in-memory only; never written to disk or DB.
+ * Callers must discard text immediately after counting tokens.
+ */
+export function sampleToolResultBlocks(scanRoots, opts = {}) {
+    const maxSamples = opts.maxSamples ?? DEFAULT_MAX_SAMPLES;
+    const maxBlockBytes = opts.maxBlockBytes ?? DEFAULT_MAX_BLOCK_BYTES;
+    const maxFiles = opts.maxFiles ?? 500;
+    // Collect JSONL file paths across all scan roots.
+    const filePaths = [];
+    for (const root of scanRoots) {
+        collectJsonlPaths(root, filePaths, maxFiles);
+        if (filePaths.length >= maxFiles)
+            break;
+    }
+    const samples = [];
+    for (const filePath of filePaths) {
+        if (samples.length >= maxSamples)
+            break;
+        let content;
+        try {
+            content = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const lines = content.split("\n");
+        for (const line of lines) {
+            if (samples.length >= maxSamples)
+                break;
+            const trimmed = line.trim();
+            if (trimmed === "")
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (typeof rec !== "object" || rec === null)
+                continue;
+            const r = rec;
+            const message = typeof r.message === "object" && r.message !== null
+                ? r.message
+                : null;
+            if (!message || !Array.isArray(message.content))
+                continue;
+            for (const block of message.content) {
+                if (samples.length >= maxSamples)
+                    break;
+                if (typeof block !== "object" || block === null)
+                    continue;
+                const b = block;
+                if (b.type !== "tool_result")
+                    continue;
+                const text = extractToolResultText(b);
+                if (text === null || text.length === 0)
+                    continue;
+                // Measure UTF-8 byte length.
+                const bytes = Buffer.byteLength(text, "utf8");
+                if (bytes > maxBlockBytes)
+                    continue;
+                // SEC-101: text is in-memory only; will be discarded after counter() call.
+                samples.push({ text, bytes });
+            }
+        }
+    }
+    return samples;
+}
+// ---------------------------------------------------------------------------
+// Main calibration function
+// ---------------------------------------------------------------------------
+/**
+ * Calibrate the bytes-per-token ratio by sampling real tool-result content
+ * blocks and counting tokens via Anthropic's count_tokens API.
+ *
+ * Steps:
+ *   1. Guard: opt-in flag must be enabled.
+ *   2. Determine model (most-frequent turns.model; fall back to FALLBACK_MODEL).
+ *   3. Sample blocks; count tokens; require ≥ MIN_SAMPLES successful counts.
+ *   4. Compute median bytes/input_tokens ratio.
+ *   5. Persist to user_config (counts/ratio only; no text).
+ *   6. Return {ok, ratio, n, model, provenance}.
+ *
+ * @param db       The SQLite database (for opt-in flag + model query + persistence).
+ * @param opts.model   Override the auto-picked model (tests / manual trigger).
+ * @param opts.counter Injectable token counter (defaults to countTokens).
+ * @param opts.sampler Injectable block sampler (defaults to sampleToolResultBlocks).
+ * @param opts.scanRoots Override scan roots (defaults to user_config.scan_roots + daemon config).
+ */
+export async function calibrateBytesPerToken(db, opts = {}) {
+    // 1. Guard: opt-in required.
+    const enabled = configGet(db, "bytes_per_token_calibration_enabled");
+    if (enabled !== "true") {
+        return { ok: false, reason: "calibration disabled — enable in Settings first" };
+    }
+    // 2. Determine model.
+    let model = opts.model ?? null;
+    if (model === null) {
+        const row = db
+            .prepare(`SELECT model, COUNT(*) AS cnt
+           FROM turns
+          WHERE model IS NOT NULL AND model != ''
+          GROUP BY model
+          ORDER BY cnt DESC
+          LIMIT 1`)
+            .get();
+        model = row?.model ?? FALLBACK_MODEL;
+    }
+    // 3. Sample blocks and count tokens.
+    const counter = opts.counter ?? countTokens;
+    const sampler = opts.sampler ?? sampleToolResultBlocks;
+    // Resolve scan roots: from user_config or caller override.
+    let scanRoots = opts.scanRoots ?? [];
+    if (scanRoots.length === 0) {
+        const raw = configGet(db, "scan_roots");
+        if (raw !== null) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed))
+                    scanRoots = parsed;
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    // Collect samples (text in memory only — SEC-101).
+    const blocks = sampler(scanRoots, { maxSamples: DEFAULT_MAX_SAMPLES });
+    // Try the auto-picked model first; fall back to FALLBACK_MODEL on 404.
+    const usedModel = model;
+    const ratios = [];
+    let fallbackUsed = false;
+    for (const block of blocks) {
+        // SEC-101: block.text lives here only for this count call.
+        let result = await counter(block.text, usedModel);
+        // Fall back to stable model on 404 (old model id).
+        if (!result.ok && result.status === 404 && usedModel !== FALLBACK_MODEL) {
+            result = await counter(block.text, FALLBACK_MODEL);
+            fallbackUsed = true;
+        }
+        if (!result.ok)
+            continue;
+        if (result.input_tokens <= 0)
+            continue;
+        ratios.push(block.bytes / result.input_tokens);
+    }
+    // 4. Require minimum sample count.
+    if (ratios.length < MIN_SAMPLES) {
+        return {
+            ok: false,
+            reason: `Only ${ratios.length} successful sample(s) — need ≥${MIN_SAMPLES} (check OAuth login or increase scan roots).`,
+        };
+    }
+    // 5. Compute median.
+    const sorted = [...ratios].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const median = sorted.length % 2 === 1
+        ? sorted[mid]
+        : (sorted[mid - 1] + sorted[mid]) / 2;
+    const effectiveModel = fallbackUsed ? FALLBACK_MODEL : usedModel;
+    const date = new Date().toISOString().slice(0, 10);
+    const ratioStr = median.toFixed(4);
+    const provenance = `calibrated ${date} via count_tokens · model ${effectiveModel} · N=${ratios.length} · median ${ratioStr}`;
+    // 6. Persist (counts/ratio/provenance only — no text).
+    db.transaction(() => {
+        configSet(db, "bytes_per_token", String(median));
+        configSet(db, "bytes_per_token_measured_at", new Date().toISOString());
+        configSet(db, "bytes_per_token_provenance", provenance);
+    })();
+    return { ok: true, ratio: median, n: ratios.length, model: effectiveModel, provenance };
+}

package/dist/detector/context-history-retention.js

@@ -0,0 +1,312 @@
+import { performance } from "node:perf_hooks";
+import { GLOBAL_WORKSPACE_ID } from "./context-probe.js";
+import { isD1SourceBackedRecommendation, parseD1SourceIdentity } from "./d1-source-identity.js";
+import { AFTER_WINDOW_DAYS } from "./measurement.js";
+export const CONTEXT_HISTORY_RETENTION_VERSION = "context-history-retention-v1";
+export const DEFAULT_CONTEXT_HISTORY_RETENTION_POLICY = Object.freeze({
+    maxAgeDays: 90,
+    maxUnprotectedRowsPerSource: 64,
+});
+const COMPONENTS = new Set([
+    "CLAUDE_MD",
+    "RULES",
+    "MCP_SCHEMAS",
+    "SETTINGS_SYSTEM",
+    "MEMORY",
+    "OTHER",
+]);
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const DELETE_CHUNK_SIZE = 500;
+class RetentionPlanError extends Error {
+    failureClass;
+    malformedOpenEffectN;
+    constructor(failureClass, malformedOpenEffectN = 0) {
+        super(failureClass);
+        this.failureClass = failureClass;
+        this.malformedOpenEffectN = malformedOpenEffectN;
+    }
+}
+function sourceKey(workspaceId, component, fileRef) {
+    return JSON.stringify([workspaceId, component, fileRef]);
+}
+function canonicalTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms) || new Date(ms).toISOString() !== value)
+        return null;
+    return ms;
+}
+function validateInputs(now, policy) {
+    const nowMs = now.getTime();
+    if (!Number.isFinite(nowMs))
+        throw new RetentionPlanError("invalid_clock");
+    if (!Number.isSafeInteger(policy.maxAgeDays) ||
+        policy.maxAgeDays <= 0 ||
+        !Number.isSafeInteger(policy.maxAgeDays * MS_PER_DAY) ||
+        !Number.isSafeInteger(policy.maxUnprotectedRowsPerSource) ||
+        policy.maxUnprotectedRowsPerSource < 0) {
+        throw new RetentionPlanError("invalid_policy");
+    }
+    return { nowMs, startedAt: now.toISOString() };
+}
+function validateHistoryRows(db) {
+    const rows = db
+        .prepare(`SELECT id, workspace_id, component, file_ref, observed_at
+         FROM context_inventory_history
+        ORDER BY id ASC`)
+        .all();
+    return rows.map((row) => {
+        const observedMs = canonicalTimestamp(row.observed_at);
+        if (!Number.isSafeInteger(row.id) ||
+            row.id <= 0 ||
+            typeof row.workspace_id !== "string" ||
+            row.workspace_id.length === 0 ||
+            !COMPONENTS.has(row.component) ||
+            typeof row.file_ref !== "string" ||
+            row.file_ref.length === 0 ||
+            observedMs === null) {
+            throw new RetentionPlanError("invalid_history_row");
+        }
+        const component = row.component;
+        return {
+            ...row,
+            component,
+            observedMs,
+            sourceKey: sourceKey(row.workspace_id, component, row.file_ref),
+        };
+    });
+}
+function readOpenEffects(db) {
+    const recs = db
+        .prepare(`SELECT rec_id, detector_id, scope_workspace_id, evidence_json, target_metric, adopted_at
+         FROM recommendations
+        WHERE state IN ('ADOPTED', 'MEASURING')
+        ORDER BY rec_id ASC`)
+        .all();
+    const sourceBacked = recs.filter(isD1SourceBackedRecommendation);
+    const effects = [];
+    let malformedN = 0;
+    for (const rec of sourceBacked) {
+        const adoptedMs = canonicalTimestamp(rec.adopted_at);
+        const identity = parseD1SourceIdentity(rec.evidence_json);
+        const component = identity?.component;
+        const workspaceId = rec.scope_workspace_id ?? GLOBAL_WORKSPACE_ID;
+        const openRows = db
+            .prepare(`SELECT measured_at, before_from, before_to, after_from, after_to
+           FROM recommendation_effects
+          WHERE rec_id = ? AND verdict IS NULL
+          ORDER BY measured_at ASC`)
+            .all(rec.rec_id);
+        if (adoptedMs === null ||
+            identity === null ||
+            identity.fileRef.length === 0 ||
+            !COMPONENTS.has(component) ||
+            workspaceId.length === 0 ||
+            openRows.length !== 1) {
+            malformedN++;
+            continue;
+        }
+        const effect = openRows[0];
+        if (effect === undefined) {
+            malformedN++;
+            continue;
+        }
+        const measuredMs = canonicalTimestamp(effect.measured_at);
+        const beforeFromMs = canonicalTimestamp(effect.before_from);
+        const beforeToMs = canonicalTimestamp(effect.before_to);
+        const afterFromMs = canonicalTimestamp(effect.after_from);
+        const afterToMs = canonicalTimestamp(effect.after_to);
+        if (measuredMs === null ||
+            beforeFromMs === null ||
+            beforeToMs === null ||
+            afterFromMs === null ||
+            afterToMs === null ||
+            effect.measured_at !== rec.adopted_at ||
+            measuredMs !== adoptedMs ||
+            beforeFromMs > beforeToMs ||
+            beforeToMs !== adoptedMs ||
+            afterFromMs !== adoptedMs ||
+            afterToMs !== adoptedMs + AFTER_WINDOW_DAYS * MS_PER_DAY) {
+            malformedN++;
+            continue;
+        }
+        effects.push({
+            sourceKey: sourceKey(workspaceId, component, identity.fileRef),
+            beforeToMs,
+            afterFromMs,
+            afterToMs,
+        });
+    }
+    if (malformedN > 0)
+        throw new RetentionPlanError("invalid_open_effect", malformedN);
+    return effects;
+}
+function emptySummary(mode, startedAt, failureClass, malformedOpenEffectN = 0) {
+    return {
+        policy_version: CONTEXT_HISTORY_RETENTION_VERSION,
+        mode,
+        started_at: startedAt,
+        source_n: 0,
+        rows_before: 0,
+        latest_protected_n: 0,
+        open_window_protected_n: 0,
+        recent_retained_n: 0,
+        count_retained_n: 0,
+        delete_candidate_n: 0,
+        rows_deleted: 0,
+        rows_after: 0,
+        malformed_open_effect_n: malformedOpenEffectN,
+        duration_ms: 0,
+        failure_class: failureClass,
+    };
+}
+function planRetention(db, now, policy, mode) {
+    const { nowMs, startedAt } = validateInputs(now, policy);
+    const rows = validateHistoryRows(db);
+    const effects = readOpenEffects(db);
+    const bySource = new Map();
+    for (const row of rows) {
+        const group = bySource.get(row.sourceKey);
+        if (group === undefined)
+            bySource.set(row.sourceKey, [row]);
+        else
+            group.push(row);
+    }
+    for (const group of bySource.values()) {
+        group.sort((a, b) => b.observedMs - a.observedMs || b.id - a.id);
+    }
+    const latestIds = new Set();
+    for (const group of bySource.values()) {
+        const latest = group[0];
+        if (latest === undefined)
+            throw new RetentionPlanError("latest_invariant");
+        latestIds.add(latest.id);
+    }
+    const openWindowIds = new Set();
+    for (const effect of effects) {
+        const group = bySource.get(effect.sourceKey) ?? [];
+        const baseline = group.find((row) => row.observedMs <= effect.beforeToMs);
+        if (baseline !== undefined)
+            openWindowIds.add(baseline.id);
+        for (const row of group) {
+            if (row.observedMs > effect.afterFromMs && row.observedMs <= effect.afterToMs) {
+                openWindowIds.add(row.id);
+            }
+        }
+    }
+    const cutoffMs = nowMs - policy.maxAgeDays * MS_PER_DAY;
+    const recentIds = new Set();
+    const ordinaryRetainedIds = new Set();
+    const candidateIds = [];
+    for (const group of bySource.values()) {
+        const unprotected = group.filter((row) => !latestIds.has(row.id) && !openWindowIds.has(row.id));
+        for (const row of unprotected) {
+            if (row.observedMs >= cutoffMs)
+                recentIds.add(row.id);
+        }
+        for (const row of unprotected.slice(0, policy.maxUnprotectedRowsPerSource)) {
+            if (row.observedMs >= cutoffMs)
+                ordinaryRetainedIds.add(row.id);
+        }
+        for (const row of unprotected) {
+            if (!ordinaryRetainedIds.has(row.id))
+                candidateIds.push(row.id);
+        }
+    }
+    candidateIds.sort((a, b) => a - b);
+    const summary = {
+        ...emptySummary(mode, startedAt, null),
+        source_n: bySource.size,
+        rows_before: rows.length,
+        latest_protected_n: latestIds.size,
+        open_window_protected_n: openWindowIds.size,
+        recent_retained_n: recentIds.size,
+        count_retained_n: ordinaryRetainedIds.size,
+        delete_candidate_n: candidateIds.length,
+        rows_after: rows.length,
+    };
+    return { candidateIds, latestIds: [...latestIds].sort((a, b) => a - b), summary };
+}
+function failureSummary(mode, now, error, attempted) {
+    const retentionError = error instanceof RetentionPlanError ? error : null;
+    const startedAt = Number.isFinite(now.getTime()) ? now.toISOString() : "";
+    return {
+        ...(attempted ??
+            emptySummary(mode, startedAt, retentionError?.failureClass ?? "database_error", retentionError?.malformedOpenEffectN ?? 0)),
+        mode,
+        rows_deleted: 0,
+        rows_after: attempted?.rows_before ?? 0,
+        malformed_open_effect_n: retentionError?.malformedOpenEffectN ?? attempted?.malformed_open_effect_n ?? 0,
+        failure_class: retentionError?.failureClass ?? "database_error",
+    };
+}
+function withDuration(summary, startedAtMs) {
+    return {
+        ...summary,
+        duration_ms: Math.max(0, Math.round(performance.now() - startedAtMs)),
+    };
+}
+export function inspectContextHistoryRetention(db, now, policy = DEFAULT_CONTEXT_HISTORY_RETENTION_POLICY) {
+    const startedAtMs = performance.now();
+    try {
+        const plan = planRetention(db, now, policy, "inspect");
+        return {
+            ok: true,
+            summary: withDuration(plan.summary, startedAtMs),
+            candidate_ids: plan.candidateIds,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: withDuration(failureSummary("inspect", now, error), startedAtMs),
+            candidate_ids: [],
+        };
+    }
+}
+export function compactContextHistory(db, now, policy = DEFAULT_CONTEXT_HISTORY_RETENTION_POLICY) {
+    const startedAtMs = performance.now();
+    let attempted;
+    try {
+        const run = db.transaction(() => {
+            const plan = planRetention(db, now, policy, "compact");
+            attempted = plan.summary;
+            let rowsDeleted = 0;
+            for (let offset = 0; offset < plan.candidateIds.length; offset += DELETE_CHUNK_SIZE) {
+                const chunk = plan.candidateIds.slice(offset, offset + DELETE_CHUNK_SIZE);
+                const placeholders = chunk.map(() => "?").join(",");
+                const result = db
+                    .prepare(`DELETE FROM context_inventory_history WHERE id IN (${placeholders})`)
+                    .run(...chunk);
+                rowsDeleted += result.changes;
+            }
+            if (rowsDeleted !== plan.candidateIds.length) {
+                throw new RetentionPlanError("delete_count_invariant");
+            }
+            const rowsAfter = db.prepare("SELECT COUNT(*) AS n FROM context_inventory_history").get().n;
+            if (rowsAfter !== plan.summary.rows_before - rowsDeleted) {
+                throw new RetentionPlanError("row_count_invariant");
+            }
+            for (const latestId of plan.latestIds) {
+                const retained = db
+                    .prepare("SELECT 1 AS present FROM context_inventory_history WHERE id = ?")
+                    .get(latestId);
+                if (retained === undefined)
+                    throw new RetentionPlanError("latest_invariant");
+            }
+            return {
+                ...plan.summary,
+                rows_deleted: rowsDeleted,
+                rows_after: rowsAfter,
+            };
+        });
+        return { ok: true, summary: withDuration(run.immediate(), startedAtMs) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: withDuration(failureSummary("compact", now, error, attempted), startedAtMs),
+        };
+    }
+}