agentwrangler 0.1.0

package/dist/detector/detectors/d10_catalog_footprint.js

@@ -0,0 +1,146 @@
+/**
+ * D10 CATALOG_FOOTPRINT.
+ *
+ * This detector reports the derived MCP/plugin/skill catalog as an estimate.
+ * The ContextInventoryProbe records Tool-Search configuration facts separately
+ * in a zero-token SETTINGS_SYSTEM row, so D10 can distinguish deferred tools
+ * from server-level alwaysLoad exemptions without persisting catalog content.
+ * Per-turn loaded-tool attribution and economic savings remain gated on R11.
+ */
+import { GLOBAL_WORKSPACE_ID, parseToolSearchState, } from "../context-probe.js";
+/** Retained as the unvalidated catalog-size review threshold. */
+export const D10_CATALOG_FOOTPRINT_TARGET_TOKENS = 40_000;
+function catalogStateLabel(state) {
+    switch (state.effective_catalog_state) {
+        case "alwaysLoad":
+            return `alwaysLoad keeps ${state.always_load_count} MCP server(s) upfront`;
+        case "deferred":
+            return "Tool Search defers MCP tool definitions until they are needed";
+        case "threshold":
+            return "Tool Search uses threshold loading, so some MCP definitions may be upfront";
+        case "upfront":
+            return "MCP tool definitions load upfront because Tool Search is disabled";
+        default:
+            return "MCP tool load behavior is unknown";
+    }
+}
+function statusNote(state, catalogTokens, withinTarget) {
+    const target = D10_CATALOG_FOOTPRINT_TARGET_TOKENS;
+    const comparison = withinTarget ? "is within" : "exceeds";
+    return `catalog estimate ${catalogTokens} token(s) ${comparison} ${target} target; ${catalogStateLabel(state)}; loaded-tool economics are not measured`;
+}
+function stateRow(db) {
+    const row = db
+        .prepare(`SELECT attribution_version
+         FROM context_inventory
+        WHERE workspace_id = ? AND component = 'SETTINGS_SYSTEM'
+        ORDER BY probed_at DESC
+        LIMIT 1`)
+        .get(GLOBAL_WORKSPACE_ID);
+    return row === undefined ? null : parseToolSearchState(row.attribution_version);
+}
+function catalogRows(db) {
+    return db
+        .prepare(`SELECT file_ref, file_hash, tokens, probed_at
+         FROM context_inventory
+        WHERE workspace_id = ? AND component = 'MCP_SCHEMAS'
+        ORDER BY file_ref`)
+        .all(GLOBAL_WORKSPACE_ID);
+}
+function configEvidence(state) {
+    return {
+        tool_search_mode: state.tool_search_mode,
+        effective_catalog_state: state.effective_catalog_state,
+        configured_value: state.configured_value,
+        always_load_flags: state.always_load_flags,
+        always_load_count: state.always_load_count,
+        always_load_flags_truncated: state.always_load_flags_truncated,
+        catalog_item_count: state.catalog_item_count,
+        catalog_item_count_truncated: state.catalog_item_count_truncated,
+        catalog_hash: state.catalog_hash,
+    };
+}
+export const d10Detector = {
+    id: "D10",
+    name: "CATALOG_FOOTPRINT",
+    evaluate(db, _ctx) {
+        const rows = catalogRows(db);
+        const state = stateRow(db);
+        if (rows.length === 0) {
+            return {
+                fired: [],
+                status: "NOT_EVALUATED",
+                note: state === null
+                    ? "catalog estimate unavailable; Tool-Search config state is not measured"
+                    : `catalog estimate unavailable; ${catalogStateLabel(state)}`,
+            };
+        }
+        if (state === null) {
+            return {
+                fired: [],
+                status: "NOT_EVALUATED",
+                note: "catalog inventory is estimated, but Tool-Search config state is not measured",
+            };
+        }
+        const catalogTokens = rows.reduce((sum, row) => sum + row.tokens, 0);
+        const withinTarget = catalogTokens <= D10_CATALOG_FOOTPRINT_TARGET_TOKENS;
+        if (withinTarget) {
+            return {
+                fired: [],
+                status: "INACTIVE",
+                note: statusNote(state, catalogTokens, true),
+            };
+        }
+        const delta = catalogTokens - D10_CATALOG_FOOTPRINT_TARGET_TOKENS;
+        const latestProbedAt = rows.reduce((latest, row) => (latest === null || row.probed_at > latest ? row.probed_at : latest), null);
+        const refs = rows.map((row) => row.file_ref);
+        const evidence = {
+            title: `Review ${state.effective_catalog_state} tool catalog: ${Math.round(catalogTokens / 1000)}K tokens`,
+            component: "MCP_SCHEMAS",
+            file_ref: refs.length === 1 ? refs[0] : null,
+            file_refs: refs,
+            source_count: rows.length,
+            catalog_tokens: catalogTokens,
+            catalog_target_tokens: D10_CATALOG_FOOTPRINT_TARGET_TOKENS,
+            delta_context_tokens: delta,
+            estimate: true,
+            priority: "down-ranked",
+            thresholds_unvalidated: true,
+            loaded_tool_telemetry: "unavailable",
+            probed_at: latestProbedAt,
+            ...configEvidence(state),
+            steps: [
+                "Review enabled MCP servers, plugins, and skills in the local Claude catalog",
+                "Keep only the small set of MCP servers that need alwaysLoad on every turn",
+                "Disable rarely used plugins or leave infrequent tools deferred",
+                "Re-measure: ContextInventoryProbe refreshes catalog and config facts on the next daemon pass",
+            ],
+        };
+        const fired = {
+            scopeKey: "D10|global|MCP_SCHEMAS",
+            category: "TOOLING",
+            scope_workspace_id: null,
+            lever: "Too many connected tools, plugins, and skills",
+            target_metric: "catalog_context_tokens",
+            // R11 is required before catalog size can become a freed-headroom claim.
+            modeled_savings_u_per_wk: null,
+            modeled_formula: {
+                model: "D10_CATALOG_FOOTPRINT_CONFIG_V1",
+                inputs: {
+                    catalog_tokens: catalogTokens,
+                    catalog_target_tokens: D10_CATALOG_FOOTPRINT_TARGET_TOKENS,
+                    delta_context_tokens: delta,
+                    catalog_item_count: state.catalog_item_count,
+                    always_load_count: state.always_load_count,
+                },
+                kind: "estimate",
+            },
+            evidence,
+        };
+        return {
+            fired: [fired],
+            status: "ACTIVE",
+            note: statusNote(state, catalogTokens, false),
+        };
+    },
+};

package/dist/detector/detectors/d1_ctx_always_loaded.js

@@ -0,0 +1,203 @@
+/**
+ * src/detector/detectors/d1_ctx_always_loaded.ts — D1 CTX_ALWAYS_LOADED_OVERSIZE.
+ *
+ * Fires PER-SOURCE against per-source token targets (UNVALIDATED defaults).
+ * For each context_inventory row:
+ *   - fire when source_tokens > D1_SOURCE_TARGETS[component]
+ *   - delta = source_tokens - target (trimmable portion)
+ *   - weekly savings µUSD = delta × turns_per_week × blended_cache_read_price
+ *
+ * GLOBAL sources (workspace_id = '__global__'): multiply turns_per_week by the
+ * count of active (non-global) workspaces; set scope_workspace_id = null.
+ * PER-WORKSPACE sources: keep the real workspace_id as scope_workspace_id.
+ *
+ * scopeKey = `D1|<workspace_id_or_global>|<component>|<file_ref-basename>`
+ * so rec_id is stable and unique per source.
+ *
+ * When context_inventory is empty, returns NOT_EVALUATED (ContextInventoryProbe
+ * not yet run or no sources found).
+ */
+import * as path from "node:path";
+import { LIST_PRICES } from "../../ingest/pricing.js";
+import { GLOBAL_WORKSPACE_ID } from "../context-probe.js";
+import { D1_SOURCE_TARGETS, d1Savings } from "../savings.js";
+/** Opus list cache-read price ($/MTok) — anchor when a workspace has no cache reads. */
+const OPUS_CACHE_READ_PRICE = LIST_PRICES.opus?.[2] ?? 0.5;
+/** Steps[] wording per component — numbered, source-specific action plan. */
+function stepsFor(component, fileRef) {
+    switch (component) {
+        case "CLAUDE_MD":
+            return [
+                `Open ${fileRef}`,
+                "Move changelog/history/rationale prose to a linked doc",
+                "Keep current-state rules + pointers only",
+                "Re-measure: probe re-sizes on next daemon pass",
+            ];
+        case "MEMORY":
+            return [
+                `Review memory files under ${fileRef}`,
+                "Delete stale or duplicate memories",
+                "Consolidate overlapping facts into concise entries",
+                "Re-measure: probe re-sizes on next daemon pass",
+            ];
+        case "MCP_SCHEMAS":
+            return [
+                "List enabled plugins/skills in ~/.claude/plugins and ~/.claude/skills",
+                "Identify rarely-used skills from recent session activity",
+                "Extract to on-demand usage or disable the plugin",
+                "Re-measure: probe re-sizes on next daemon pass",
+            ];
+        default:
+            return [`Trim ${fileRef} to reduce always-loaded context`];
+    }
+}
+/** Short imperative title per component — written into evidence.title (read by toCard). */
+function titleFor(component, tokens, target) {
+    const label = component === "CLAUDE_MD" ? "CLAUDE.md" : component === "MEMORY" ? "memory" : "MCP schemas";
+    const fromK = Math.round(tokens / 1_000);
+    const toK = Math.round(target / 1_000);
+    return `Trim ${label}: ${fromK}K→${toK}K tokens`;
+}
+/** Lever label per component. */
+function leverFor(component) {
+    switch (component) {
+        case "CLAUDE_MD":
+            return "Move changelog/history prose out of CLAUDE.md; keep current-state + pointers.";
+        case "MEMORY":
+            return "Prune stale/duplicate memories; consolidate overlapping facts.";
+        case "MCP_SCHEMAS":
+            return "Identify rarely-used skills/plugins; extract to on-demand or disable.";
+        default:
+            return "Trim always-loaded context source to the per-source target.";
+    }
+}
+export const d1Detector = {
+    id: "D1",
+    name: "CTX_ALWAYS_LOADED_OVERSIZE",
+    evaluate(db, ctx) {
+        // Early exit when there is nothing to evaluate.
+        const inventoryCount = db.prepare("SELECT COUNT(*) AS n FROM context_inventory").get().n;
+        if (inventoryCount === 0) {
+            return {
+                fired: [],
+                status: "NOT_EVALUATED",
+                note: "no context_inventory rows — run ContextInventoryProbe first",
+            };
+        }
+        // Only sources with an active D1 contract are evaluable. MCP_SCHEMAS is a
+        // catalog estimate and is intentionally owned by the gated D10 detector.
+        const rows = db
+            .prepare(`SELECT probe_id, workspace_id, component, file_ref, tokens, probed_at
+           FROM context_inventory
+          WHERE component IN ('CLAUDE_MD', 'MEMORY')`)
+            .all();
+        if (rows.length === 0) {
+            return {
+                fired: [],
+                status: "NOT_EVALUATED",
+                note: inventoryCount === 0
+                    ? "no context_inventory rows — run ContextInventoryProbe first"
+                    : "no evaluable context_inventory rows — catalog estimates are gated behind D10 load-state telemetry",
+            };
+        }
+        // Count active (non-global) workspaces for the global multiplier.
+        const activeWorkspaceCount = db
+            .prepare("SELECT COUNT(*) AS n FROM workspaces WHERE workspace_id != ?")
+            .get(GLOBAL_WORKSPACE_ID).n;
+        // Turn metrics for ALL non-global workspaces (used for global sources).
+        const globalMetrics = db
+            .prepare(`SELECT COUNT(*) AS turns_per_week,
+                COALESCE(SUM(cache_read_tokens), 0) AS cache_read_tokens,
+                COALESCE(SUM(cache_read_tokens *
+                  (SELECT CAST(json_extract(ps.unit_prices_json, '$[2]') AS REAL)
+                     FROM pricing_snapshots ps
+                    WHERE ps.snapshot_id = t.pricing_snapshot_id)), 0) AS cache_read_spend_u
+           FROM turns t
+          WHERE t.workspace_id != ? AND t.ts >= ? AND t.ts < ?`)
+            .get(GLOBAL_WORKSPACE_ID, ctx.fromIso, ctx.toIso);
+        const fired = [];
+        for (const row of rows) {
+            const target = D1_SOURCE_TARGETS[row.component];
+            if (target === undefined)
+                continue; // unsupported component — skip
+            if (row.tokens <= target)
+                continue; // within target — no rec
+            const delta = row.tokens - target;
+            const isGlobal = row.workspace_id === GLOBAL_WORKSPACE_ID;
+            const scope = isGlobal ? "global" : "workspace";
+            // Turn metrics: global sources use all-workspace aggregate; per-workspace
+            // sources query only their own workspace.
+            let metrics;
+            if (isGlobal) {
+                metrics = globalMetrics;
+            }
+            else {
+                metrics = db
+                    .prepare(`SELECT COUNT(*) AS turns_per_week,
+                    COALESCE(SUM(cache_read_tokens), 0) AS cache_read_tokens,
+                    COALESCE(SUM(cache_read_tokens *
+                      (SELECT CAST(json_extract(ps.unit_prices_json, '$[2]') AS REAL)
+                         FROM pricing_snapshots ps
+                        WHERE ps.snapshot_id = t.pricing_snapshot_id)), 0) AS cache_read_spend_u
+               FROM turns t
+              WHERE t.workspace_id = ? AND t.ts >= ? AND t.ts < ?`)
+                    .get(row.workspace_id, ctx.fromIso, ctx.toIso);
+            }
+            // Effective turns: for global, the total already spans all workspaces.
+            // workspace_multiplier is stored in evidence for display transparency.
+            const effectiveTurns = isGlobal ? metrics.turns_per_week : metrics.turns_per_week;
+            const blendedPrice = metrics.cache_read_tokens > 0
+                ? metrics.cache_read_spend_u / metrics.cache_read_tokens
+                : OPUS_CACHE_READ_PRICE;
+            const { savingsU, formula } = d1Savings(delta, effectiveTurns, Number(blendedPrice.toFixed(6)));
+            // Skip dormant workspaces: no turns in-window ⇒ zero modeled savings this week,
+            // so the rec would be noise ("prune memory · 0 tokens/wk freed"). Latent bloat in
+            // an inactive workspace resurfaces on a later pass once it has activity again.
+            if (savingsU === 0)
+                continue;
+            const fileBasename = path.basename(row.file_ref);
+            // scopeKey uses workspace_id (or 'global' for __global__) to keep it unique
+            // across workspaces with the same component+basename.
+            const scopeSegment = isGlobal ? "global" : row.workspace_id;
+            const scopeKey = `D1|${scopeSegment}|${row.component}|${fileBasename}`;
+            const evidenceBase = {
+                title: titleFor(row.component, row.tokens, target),
+                component: row.component,
+                file_ref: row.file_ref,
+                source_tokens: row.tokens,
+                source_target: target,
+                delta_context_tokens: delta,
+                turns_per_week: effectiveTurns,
+                modeled_savings_basis: "LIST_EQUIV",
+                billed_cost_claim: "UNAVAILABLE",
+                scope,
+                steps: stepsFor(row.component, row.file_ref),
+            };
+            if (isGlobal) {
+                evidenceBase.workspace_multiplier = activeWorkspaceCount;
+            }
+            fired.push({
+                scopeKey,
+                category: "CONTEXT",
+                scope_workspace_id: isGlobal ? null : row.workspace_id,
+                lever: leverFor(row.component),
+                target_metric: "avg_context_per_turn",
+                modeled_savings_u_per_wk: savingsU,
+                modeled_formula: formula,
+                evidence: evidenceBase,
+            });
+        }
+        if (fired.length === 0) {
+            return {
+                fired: [],
+                status: "INACTIVE",
+                note: "all context_inventory sources within per-source targets",
+            };
+        }
+        return {
+            fired,
+            status: "ACTIVE",
+            note: `${fired.length} source(s) exceed their per-source target (CLAUDE_MD=${D1_SOURCE_TARGETS.CLAUDE_MD}, MEMORY=${D1_SOURCE_TARGETS.MEMORY}); catalog estimates are gated behind D10 load-state telemetry`,
+        };
+    },
+};

package/dist/detector/detectors/d2_session_long_full_context.js

@@ -0,0 +1,119 @@
+/**
+ * src/detector/detectors/d2_session_long_full_context.ts — D2 SESSION_LONG_FULL_CONTEXT.
+ *
+ * Fires (global scope) when >= N qualifying long-context sessions appear in the
+ * trailing week. Qualifying = more than 150 reconciled turns in the same
+ * evaluation window AND AVG(context_tokens) > 180_000 over those same rows.
+ *
+ * Savings: cache-read spend the qualifying sessions generate × an (unvalidated)
+ * reduction fraction. The cache-read price is derived PER-MODEL from each turn's
+ * own pricing snapshot (unit_prices_json[2]), never a hard-coded scalar (§1 D2 (b)).
+ */
+import { capWeightedTokens, resolveCapReadCoeff } from "../../query/cap-weighted.js";
+import { D2_AVG_CONTEXT_THRESHOLD, D2_MIN_QUALIFYING_SESSIONS, D2_REDUCTION_FRACTION, D2_TURN_COUNT_THRESHOLD, d2Savings, } from "../savings.js";
+/** Cache-read price is index 2 of unit_prices_json ([in, out, cacheRead, cw5m, cw1h]). */
+function cacheReadPrice(unitPricesJson) {
+    if (unitPricesJson === null)
+        return 0;
+    try {
+        const arr = JSON.parse(unitPricesJson);
+        return arr[2] ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export const d2Detector = {
+    id: "D2",
+    name: "SESSION_LONG_FULL_CONTEXT",
+    evaluate(db, ctx) {
+        const qualifying = db
+            .prepare(`SELECT t.session_id AS session_id,
+                AVG(t.context_tokens) AS avg_context,
+                COUNT(*) AS qualifying_turns
+           FROM turns t
+          WHERE t.ts >= ? AND t.ts < ? AND t.provisional = 0
+          GROUP BY t.session_id
+         HAVING COUNT(*) > ? AND AVG(t.context_tokens) > ?
+          ORDER BY t.session_id ASC`)
+            .all(ctx.fromIso, ctx.toIso, D2_TURN_COUNT_THRESHOLD, D2_AVG_CONTEXT_THRESHOLD);
+        if (qualifying.length < D2_MIN_QUALIFYING_SESSIONS) {
+            return {
+                fired: [],
+                status: "INACTIVE",
+                note: `${qualifying.length} qualifying long-context session(s) in window (trigger ≥ ${D2_MIN_QUALIFYING_SESSIONS})`,
+            };
+        }
+        const sessionIds = qualifying.map((q) => q.session_id).sort();
+        const placeholders = sessionIds.map(() => "?").join(",");
+        const qualifyingTurnCount = qualifying.reduce((sum, session) => sum + session.qualifying_turns, 0);
+        const rawContextAverageTokensPerTurn = qualifyingTurnCount > 0
+            ? qualifying.reduce((sum, session) => sum + session.avg_context * session.qualifying_turns, 0) / qualifyingTurnCount
+            : 0;
+        // Cap-weighted burn is a separate annotation on the raw-context rec. It
+        // never participates in the qualifying-session gate above.
+        const capReadCoefficient = resolveCapReadCoeff(db);
+        const capBySession = new Map(capWeightedTokens(db, {
+            fromIso: ctx.fromIso,
+            toIso: ctx.toIso,
+            groupBy: "session_id",
+            coeff: capReadCoefficient,
+        }).map((row) => [row.group, row.cap_weighted_tokens]));
+        const capWeightedBurnTokensPerWeek = sessionIds.reduce((sum, sessionId) => sum + (capBySession.get(sessionId) ?? 0), 0);
+        // Cache-read spend over the qualifying sessions' turns in the window, priced
+        // per-model from each turn's own pricing snapshot.
+        const rows = db
+            .prepare(`SELECT t.cache_read_tokens AS cache_read_tokens, ps.unit_prices_json AS unit_prices_json
+           FROM turns t
+           LEFT JOIN pricing_snapshots ps ON ps.snapshot_id = t.pricing_snapshot_id
+          WHERE t.session_id IN (${placeholders})
+            AND t.ts >= ? AND t.ts < ? AND t.provisional = 0`)
+            .all(...sessionIds, ctx.fromIso, ctx.toIso);
+        let cacheReadTokensPerWeek = 0;
+        let cacheReadSpendU = 0;
+        for (const r of rows) {
+            cacheReadTokensPerWeek += r.cache_read_tokens;
+            cacheReadSpendU += r.cache_read_tokens * cacheReadPrice(r.unit_prices_json);
+        }
+        const { savingsU, formula } = d2Savings(cacheReadTokensPerWeek, cacheReadSpendU, D2_REDUCTION_FRACTION);
+        const n = qualifying.length;
+        const fired = {
+            scopeKey: `D2|global|${formula.model}`,
+            category: "CONTEXT",
+            scope_workspace_id: null,
+            lever: "/clear between unrelated tasks; split long work; avoid mid-task /compact.",
+            target_metric: "avg_context_per_turn",
+            modeled_savings_u_per_wk: savingsU,
+            modeled_formula: formula,
+            evidence: {
+                title: `Shorten sessions: ${n} long-context run${n === 1 ? "" : "s"} this week`,
+                qualifying_session_count: qualifying.length,
+                qualifying_turn_count: qualifyingTurnCount,
+                session_ids: sessionIds,
+                denominator: "reconciled turns in the evaluation window",
+                turn_count_threshold: D2_TURN_COUNT_THRESHOLD,
+                avg_context_threshold: D2_AVG_CONTEXT_THRESHOLD,
+                raw_context_average_tokens_per_turn: Number(rawContextAverageTokensPerTurn.toFixed(2)),
+                raw_context_basis: "RAW_USAGE",
+                cap_weighted_burn_tokens_per_week: capWeightedBurnTokensPerWeek,
+                cap_weighted_burn_basis: "CAP_PROXY",
+                cap_read_coefficient: capReadCoefficient,
+                cap_read_coefficient_unvalidated: true,
+                cache_read_tokens_per_week: cacheReadTokensPerWeek,
+                cache_read_spend_u_per_week: Math.round(cacheReadSpendU),
+                cache_read_exposure_tokens_per_week: cacheReadTokensPerWeek,
+                cache_read_exposure_spend_u_per_week: Math.round(cacheReadSpendU),
+                cache_read_exposure_spend_basis: "LIST_EQUIV",
+                modeled_savings_basis: "LIST_EQUIV",
+                billed_cost_claim: "UNAVAILABLE",
+                reduction_fraction: D2_REDUCTION_FRACTION,
+                thresholds_unvalidated: true,
+            },
+        };
+        return {
+            fired: [fired],
+            status: "ACTIVE",
+            note: `${qualifying.length} qualifying long-context sessions this week`,
+        };
+    },
+};