agentwrangler 0.1.0

package/dist/query/api/reports.js

@@ -0,0 +1,78 @@
+/**
+ * src/query/api/reports.ts — deterministic weekly report artifacts.
+ *
+ * Reports are bounded snapshots assembled from existing aggregate query APIs.
+ * They never include transcript content or raw event data and are safe to run
+ * unattended because they do not invoke an LLM or an external CLI.
+ */
+import { setQueryDb } from "../db-context.js";
+import { getSuccessRate } from "./outcomes.js";
+import { getGlobalOverview } from "./overview.js";
+import { listRecommendations } from "./recommendations.js";
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+export function isoWeekBounds(now) {
+    const daysSinceMonday = (now.getUTCDay() + 6) % 7;
+    const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() - daysSinceMonday));
+    return {
+        period_start: start.toISOString(),
+        period_end: new Date(start.getTime() + 7 * MS_PER_DAY).toISOString(),
+    };
+}
+/** Generate or return the idempotent weekly report for the ISO week containing `now`. */
+export function generateWeeklyReport(db, now = new Date()) {
+    setQueryDb(db);
+    const { period_start, period_end } = isoWeekBounds(new Date(now.getTime() - 7 * MS_PER_DAY));
+    const spendResponse = getGlobalOverview({ from: period_start, to: period_end });
+    const recommendationsResponse = listRecommendations();
+    const outcomesResponse = getSuccessRate();
+    const spend = spendResponse.data;
+    const recommendations = recommendationsResponse.data;
+    const outcomes = outcomesResponse.data;
+    const openRecommendations = [
+        ...(recommendations?.active ?? []),
+        ...(recommendations?.limit_warnings ?? []),
+    ]
+        .sort((a, b) => {
+        const aSavings = a.modeled_savings_u_per_wk ?? Number.NEGATIVE_INFINITY;
+        const bSavings = b.modeled_savings_u_per_wk ?? Number.NEGATIVE_INFINITY;
+        if (aSavings !== bSavings)
+            return bSavings - aSavings;
+        return a.rec_id.localeCompare(b.rec_id);
+    })
+        .slice(0, 5)
+        .map((rec) => ({
+        rec_id: rec.rec_id,
+        modeled_savings_u_per_wk: rec.modeled_savings_u_per_wk,
+    }));
+    const content = {
+        spend: {
+            cost_equiv_u: spend?.cost_equiv_u ?? 0,
+            turns: spend?.turns ?? 0,
+            turns_total: spend?.turns_total ?? 0,
+            unpriced_turns: spend?.unpriced_turns ?? 0,
+        },
+        top_recommendations: openRecommendations,
+        outcomes: {
+            terminal_n: outcomes?.terminal_n ?? 0,
+            success_rate: outcomes?.success_rate ?? null,
+            clean_success_n: outcomes?.clean_success_n ?? 0,
+            with_deferrals_n: outcomes?.with_deferrals_n ?? 0,
+            no_ci_success_n: outcomes?.no_ci_success_n ?? 0,
+            linkage_rate: outcomes?.linkage_rate ?? null,
+        },
+    };
+    const reportId = `weekly-${period_start}`;
+    db.prepare(`INSERT OR IGNORE INTO reports
+       (report_id, kind, period_start, period_end, generated_at, content_json)
+     VALUES (?, 'weekly', ?, ?, ?, ?)`).run(reportId, period_start, period_end, now.toISOString(), JSON.stringify(content));
+    const report = db.prepare("SELECT * FROM reports WHERE report_id = ?").get(reportId);
+    if (report === undefined)
+        throw new Error(`weekly report ${reportId} was not stored`);
+    return report;
+}
+export function listReports(db) {
+    return db.prepare("SELECT * FROM reports ORDER BY generated_at DESC").all();
+}
+export function getReport(db, id) {
+    return db.prepare("SELECT * FROM reports WHERE report_id = ?").get(id);
+}

package/dist/query/api/self-churn.js

@@ -0,0 +1,77 @@
+/**
+ * src/query/api/self-churn.ts — query-only L2b self-churn metrics.
+ *
+ * Self-churn measures later changes to session-authored lines using structural
+ * commit data only; no source text, paths, or diff content leave this surface.
+ */
+import { buildResponse } from "../envelope.js";
+/**
+ * Derive 14-day self-churn for sessions with turns in [from, to).
+ *
+ * A LEFT JOIN keeps in-window sessions that have no session_churn row yet (new
+ * sessions accumulate before the churn collector runs); the DB aggregates in one
+ * pass. Commit SHAs come from a second scan over the measured sessions only —
+ * one JSON array per session unioned into a set.
+ */
+export function getSelfChurn(db, opts) {
+    const workspaceFilter = opts.workspaceId === null ? "" : " AND t.workspace_id = ?";
+    const params = opts.workspaceId === null ? [opts.from, opts.to] : [opts.from, opts.to, opts.workspaceId];
+    const inWindow = `WITH in_window_turns AS (
+         SELECT t.session_id, t.workspace_id
+           FROM turns t
+          WHERE t.ts >= ? AND t.ts < ?${workspaceFilter}
+       ),
+       in_window_sessions AS (
+         SELECT DISTINCT session_id, workspace_id
+           FROM in_window_turns
+       )`;
+    const totals = db
+        .prepare(`${inWindow}
+       SELECT COUNT(*) AS session_count,
+              COALESCE(SUM(CASE WHEN sc.status != 'NO_REPO' AND sc.authored_lines > 0 THEN 1 ELSE 0 END), 0)
+                AS measured_session_count,
+              COALESCE(SUM(sc.authored_lines), 0) AS authored_lines_total,
+              COALESCE(SUM(sc.churned_lines), 0) AS churned_lines_total
+         FROM in_window_sessions iws
+         LEFT JOIN session_churn sc USING (session_id)`)
+        .get(...params);
+    const shaRows = db
+        .prepare(`${inWindow}
+       SELECT sc.commit_shas
+         FROM in_window_sessions iws
+         JOIN session_churn sc USING (session_id)
+        WHERE sc.status != 'NO_REPO' AND sc.authored_lines > 0`)
+        .all(...params);
+    const commitShas = new Set();
+    for (const row of shaRows) {
+        const shas = JSON.parse(row.commit_shas);
+        if (Array.isArray(shas)) {
+            for (const sha of shas) {
+                if (typeof sha === "string")
+                    commitShas.add(sha);
+            }
+        }
+    }
+    const data = {
+        ...totals,
+        churn_ratio: totals.authored_lines_total === 0
+            ? null
+            : totals.churned_lines_total / totals.authored_lines_total,
+        commit_shas: [...commitShas].sort(),
+        from: opts.from,
+        to: opts.to,
+        workspace_id: opts.workspaceId,
+    };
+    return buildResponse(data, {
+        claim_kind: "OBS_PROXY",
+        n: data.measured_session_count,
+        window: { from: opts.from, to: opts.to },
+        qualification: {
+            provisional_excluded: true,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "14-day self-churn of session-authored commits (structural proxy).",
+        },
+        ...(opts.workspaceId === null ? {} : { drilldown_ids: { workspace_id: opts.workspaceId } }),
+    });
+}

package/dist/query/api/self-percentiles.js

@@ -0,0 +1,109 @@
+import { isoWeekBounds } from "./reports.js";
+const WINDOW_DAYS = 90;
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function getSessionSpendPercentile(db, sessionId) {
+    const target = db
+        .prepare(`SELECT workspace_id, cost_equiv_u, last_turn_at
+         FROM sessions
+        WHERE session_id = ?`)
+        .get(sessionId);
+    if (target === undefined || target.cost_equiv_u === null || target.last_turn_at === null) {
+        return { percentile: null, n: 0, window_days: WINDOW_DAYS };
+    }
+    const windowStart = new Date(Date.parse(target.last_turn_at) - WINDOW_DAYS * DAY_MS).toISOString();
+    const population = db
+        .prepare(`SELECT COUNT(*) AS population_count,
+              COALESCE(SUM(CASE WHEN cost_equiv_u <= ? THEN 1 ELSE 0 END), 0) AS at_or_below_count
+         FROM sessions
+        WHERE workspace_id = ?
+          AND last_turn_at >= ?
+          AND last_turn_at <= ?
+          AND cost_equiv_u IS NOT NULL`)
+        .get(target.cost_equiv_u, target.workspace_id, windowStart, target.last_turn_at);
+    if (population.population_count < 20) {
+        return { percentile: null, n: population.population_count, window_days: WINDOW_DAYS };
+    }
+    // Ties count at or below; the UI renders "top X%" as 1 - percentile.
+    return {
+        percentile: population.at_or_below_count / population.population_count,
+        n: population.population_count,
+        window_days: WINDOW_DAYS,
+    };
+}
+// ---------------------------------------------------------------------------
+// Per-week self-percentiles — this (current, partial) ISO week vs the 8 full
+// weeks immediately before it, for spend and cache-write share.
+//
+// "Your own history" is the honest peer group: the percentile ranks this week
+// against the trailing full weeks (<= ties, mirroring the per-session form).
+// Deterministic — the caller passes an explicit `now`; every window boundary is
+// derived from it plus fixed offsets, never a scattered Date.now().
+// ---------------------------------------------------------------------------
+const TRAILING_WEEKS = 8;
+/**
+ * A rank needs a few reference weeks to mean anything; below this the percentile
+ * is withheld (null) rather than reported as noise off one or two weeks.
+ */
+const MIN_TRAILING_WEEKS_WITH_DATA = 4;
+const WEEK_MS = 7 * DAY_MS;
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const lo = sorted[mid - 1];
+    const hi = sorted[mid];
+    if (sorted.length % 2 === 0) {
+        return lo !== undefined && hi !== undefined ? (lo + hi) / 2 : (hi ?? lo ?? null);
+    }
+    return hi ?? null;
+}
+/** Rank `thisValue` against `trailing` values with data — <= ties, mirroring the per-session form. */
+function weeklyMetric(thisValue, trailing) {
+    const withData = trailing.filter((v) => v !== null);
+    const n = withData.length;
+    const trailing_median = median(withData);
+    if (thisValue === null || n < MIN_TRAILING_WEEKS_WITH_DATA) {
+        return { this_week: thisValue, percentile: null, trailing_median, n };
+    }
+    const atOrBelow = withData.filter((v) => v <= thisValue).length;
+    return { this_week: thisValue, percentile: atOrBelow / n, trailing_median, n };
+}
+export function getWeeklySelfPercentile(db, now) {
+    const stmt = db.prepare(`SELECT COUNT(*)                                                    AS turns,
+            COALESCE(SUM(cost_equiv_u), 0)                              AS spend_u,
+            COALESCE(SUM(cache_write_5m + cache_write_1h
+                         + cache_write_other), 0)                       AS cache_write,
+            COALESCE(SUM(cache_read_tokens), 0)                         AS cache_read
+       FROM turns
+      WHERE ts >= ? AND ts < ? AND provisional = 0`);
+    const weekMetrics = (start, end) => {
+        const row = stmt.get(start, end);
+        const cacheTotal = row.cache_write + row.cache_read;
+        return {
+            turns: row.turns,
+            spend_u: row.spend_u,
+            cache_write_share: cacheTotal === 0 ? null : row.cache_write / cacheTotal,
+        };
+    };
+    const { period_start, period_end } = isoWeekBounds(now);
+    const currentStartMs = Date.parse(period_start);
+    const current = weekMetrics(period_start, period_end);
+    // The 8 contiguous full weeks immediately before the current week. period_start
+    // is a Monday, so each trailing boundary is a whole-week shift from it.
+    const trailing = [];
+    for (let k = 1; k <= TRAILING_WEEKS; k += 1) {
+        const start = new Date(currentStartMs - k * WEEK_MS).toISOString();
+        const end = new Date(currentStartMs - (k - 1) * WEEK_MS).toISOString();
+        trailing.push(weekMetrics(start, end));
+    }
+    const spend = weeklyMetric(current.turns > 0 ? current.spend_u : null, trailing.map((w) => (w.turns > 0 ? w.spend_u : null)));
+    const cache_write_share = weeklyMetric(current.cache_write_share, trailing.map((w) => w.cache_write_share));
+    return {
+        week_start: period_start,
+        trailing_weeks: TRAILING_WEEKS,
+        min_weeks_with_data: MIN_TRAILING_WEEKS_WITH_DATA,
+        spend,
+        cache_write_share,
+    };
+}

package/dist/query/api/session-drivers.js

@@ -0,0 +1,153 @@
+/** Per-session, privacy-safe detector attribution. */
+import { buildResponse } from "../envelope.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DETECTOR_ORDER = { D6: 0, D8: 1, D7: 2, D2: 3 };
+const DRIVER_CONFIG = {
+    D2: {
+        label: "SESSION_LONG_FULL_CONTEXT",
+        fields: [],
+        routing: "hook",
+    },
+    D6: {
+        label: "TOOL_RESULT_BLOAT",
+        fields: ["tool_result_bytes", "bloat_share", "attributed_tool", "turn_count"],
+        shareField: "bloat_share",
+        routing: "rec_card",
+    },
+    D7: {
+        label: "LOOP_RETRY_WASTE",
+        fields: [
+            "loop_flagged_turn_count",
+            "repeat_excess_event_count",
+            "total_turn_count",
+            "loop_flagged_turn_share",
+        ],
+        shareField: "loop_flagged_turn_share",
+        routing: "hook",
+    },
+    D8: {
+        label: "CACHE_WRITE_CHURN",
+        fields: ["churn_event_count", "total_churn_creation_tokens", "creation_share", "regime"],
+        shareField: "creation_share",
+        routing: "hook",
+    },
+};
+function parseEvidence(evidenceJson) {
+    try {
+        const value = JSON.parse(evidenceJson);
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isSessionAttribution(evidence, sessionId) {
+    return (evidence.session_id === sessionId ||
+        (Array.isArray(evidence.session_ids) && evidence.session_ids.includes(sessionId)));
+}
+function whitelistedMeasured(detectorId, evidence) {
+    if (detectorId === "D2")
+        return { in_long_context_group: true };
+    const measured = {};
+    for (const field of DRIVER_CONFIG[detectorId].fields) {
+        const value = evidence[field];
+        if ((typeof value === "number" && Number.isFinite(value)) ||
+            typeof value === "string" ||
+            typeof value === "boolean") {
+            measured[field] = value;
+        }
+    }
+    return measured;
+}
+function boundedShare(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.min(1, Math.max(0, value))
+        : null;
+}
+function percentile(db, session) {
+    if (session.last_turn_at === null)
+        return 0;
+    const referenceMs = Date.parse(session.last_turn_at);
+    if (!Number.isFinite(referenceMs))
+        return 0;
+    const windowStart = new Date(referenceMs - 30 * DAY_MS).toISOString();
+    const row = db
+        .prepare(`SELECT COUNT(*) AS population_count,
+              COALESCE(SUM(CASE WHEN cost_equiv_u <= ? THEN 1 ELSE 0 END), 0) AS at_or_below_count
+         FROM sessions
+        WHERE last_turn_at >= ? AND last_turn_at <= ?`)
+        .get(session.cost_equiv_u, windowStart, session.last_turn_at);
+    if (row.population_count === 0)
+        return 0;
+    return Math.round((1000 * row.at_or_below_count) / row.population_count) / 10;
+}
+/**
+ * Return session-attributed detector drivers without exposing transcript content.
+ */
+export function getSessionDrivers(db, sessionId) {
+    const session = db
+        .prepare(`SELECT workspace_id, cost_equiv_u, last_turn_at
+         FROM sessions
+        WHERE session_id = ?`)
+        .get(sessionId);
+    if (session === undefined) {
+        return buildResponse(null, {
+            claim_kind: "N_A",
+            n: 0,
+            drilldown_ids: { session_id: sessionId },
+        });
+    }
+    const recommendations = db
+        .prepare(`SELECT rec_id, detector_id, modeled_savings_u_per_wk, evidence_json
+         FROM recommendations
+        WHERE state = 'PROPOSED'
+          AND detector_id IN ('D2', 'D6', 'D7', 'D8')
+          AND (scope_workspace_id = ? OR scope_workspace_id IS NULL)`)
+        .all(session.workspace_id);
+    const drivers = [];
+    for (const recommendation of recommendations) {
+        const evidence = parseEvidence(recommendation.evidence_json);
+        if (evidence === null || !isSessionAttribution(evidence, sessionId))
+            continue;
+        const config = DRIVER_CONFIG[recommendation.detector_id];
+        const share = boundedShare(config.shareField === undefined ? undefined : evidence[config.shareField]);
+        drivers.push({
+            detector_id: recommendation.detector_id,
+            label: config.label,
+            measured: whitelistedMeasured(recommendation.detector_id, evidence),
+            share,
+            rec_id: recommendation.rec_id,
+            routing: config.routing,
+            ...(recommendation.modeled_savings_u_per_wk === null
+                ? {}
+                : { approx_usd: recommendation.modeled_savings_u_per_wk / 1_000_000 }),
+        });
+    }
+    drivers.sort((a, b) => {
+        const savingsDiff = (b.approx_usd ?? 0) - (a.approx_usd ?? 0);
+        if (savingsDiff !== 0)
+            return savingsDiff;
+        const shareDiff = (b.share ?? 0) - (a.share ?? 0);
+        if (shareDiff !== 0)
+            return shareDiff;
+        return DETECTOR_ORDER[a.detector_id] - DETECTOR_ORDER[b.detector_id];
+    });
+    return buildResponse({
+        session_id: sessionId,
+        workspace_id: session.workspace_id,
+        percentile: percentile(db, session),
+        drivers,
+    }, {
+        claim_kind: "OBS_PROXY",
+        n: drivers.length,
+        drilldown_ids: { session_id: sessionId, workspace_id: session.workspace_id },
+        qualification: {
+            provisional_excluded: false,
+            unpriced_turns: 0,
+            claim_kinds_count: 1,
+            note: "Per-driver figures are observed proxies; never summed.",
+        },
+    });
+}

package/dist/query/api/settings.js

@@ -0,0 +1,85 @@
+/**
+ * src/query/api/settings.ts — LocalQueryAPI: settings method stubs.
+ *
+ * WP4 owns this file. These signatures and return types are FROZEN by WP0.
+ * Do NOT change method signatures without a plan decision.
+ *
+ * All methods return stub responses. WP4 implements the real bodies,
+ * wiring to the user_config table and WorkspaceRegistry.
+ */
+import { getQueryDb } from "../db-context.js";
+import { buildResponse } from "../envelope.js";
+import { applySettingsUpdate as _applySettingsUpdate, calibrateLimit as _calibrateLimit, resetDatabase as _resetDatabase, getSettingsData, } from "../settings-store.js";
+import { calibrateBytesPerToken as _calibrateBytesPerToken } from "../../detector/calibration.js";
+// ---------------------------------------------------------------------------
+// Method stubs — WP4 fills these
+// ---------------------------------------------------------------------------
+/**
+ * Return the current daemon settings.
+ * Reads user_config + WorkspaceRegistry; parser_health from the injected Health instance.
+ */
+export function getSettings() {
+    const db = getQueryDb();
+    const data = getSettingsData(db);
+    return buildResponse(data, {
+        claim_kind: "N_A",
+        n: 1,
+    });
+}
+/**
+ * Apply a partial settings update and persist to user_config.
+ * Validates scan_roots paths before writing. Throws on invalid input.
+ *
+ * This is the write path; it requires the CSRF same-origin gate (enforced in http.ts).
+ */
+export function updateSettings(update) {
+    const db = getQueryDb();
+    const data = _applySettingsUpdate(db, update);
+    return buildResponse(data, {
+        claim_kind: "N_A",
+        n: 1,
+    });
+}
+/**
+ * Wipe all ingested data tables and return fresh settings.
+ * Preserves user_config and schema_migrations.
+ */
+export function resetDatabase() {
+    const db = getQueryDb();
+    const data = _resetDatabase(db);
+    return buildResponse(data, {
+        claim_kind: "N_A",
+        n: 1,
+    });
+}
+/**
+ * Auto-calibrate `:limit_tokens` from the user's local oauth/usage utilization.
+ * Implements ADR-111: limit_tokens ≈ tokens_in_window / seven_day.utilization.
+ *
+ * Always returns 200; ok:false means calibration failed gracefully (429, low
+ * utilization) — the client shows the reason and falls back to manual entry.
+ * This is a write path; it requires the CSRF same-origin gate (enforced in http.ts).
+ */
+export async function calibrateLimit() {
+    const db = getQueryDb();
+    const result = await _calibrateLimit(db);
+    return buildResponse(result, {
+        claim_kind: "N_A",
+        n: 1,
+    });
+}
+/**
+ * Calibrate the bytes-per-token ratio via Anthropic's count_tokens API (R12).
+ *
+ * Requires opt-in to be enabled (user_config.bytes_per_token_calibration_enabled="true").
+ * Returns ok:false when disabled or when <30 successful samples could be collected.
+ * This is a write path; it requires the CSRF same-origin gate (enforced in http.ts).
+ */
+export async function calibrateBytesPerToken() {
+    const db = getQueryDb();
+    const result = await _calibrateBytesPerToken(db);
+    return buildResponse(result, {
+        claim_kind: "N_A",
+        n: 1,
+    });
+}