@jmtrin/opencode-kevin 1.2.0 → 1.4.0

package/dist/plugin/HookLiveness.js

@@ -1,322 +0,0 @@
-import { HOOK_NAMES } from "./Migrate.js";
-const DEFAULT_THRESHOLD = 3;
-/**
- * v0.9.0 (K9-010 / plan §5.3, D9-09) — parse the TEXT setting
- * `dead_hook_report_threshold` into the [1, 1000] clamp. NaN and empty
- * fall back to 3 (never 0: a zero threshold would report every hook dead
- * before a single session completes a checkpoint).
- */
-export function parseThreshold(text) {
-    if (text === null || text === undefined || text === "")
-        return DEFAULT_THRESHOLD;
-    const n = Number.parseInt(text, 10);
-    // NaN → default; 0 is not a valid threshold (K9-010 AC: 'abc'/''/'0'
-    // all clamp to the default of three — never zero).
-    if (Number.isNaN(n) || n === 0)
-        return DEFAULT_THRESHOLD;
-    return Math.min(1000, Math.max(1, n));
-}
-/**
- * v0.9.0 (K9-009/K9-010 / plan §5.3) — wraps the plugin's hooks with a
- * success-path recorder, dedups per-session checkpoints, and reports each
- * hook's liveness state. Persistence is machine-scoped: the hook_liveness
- * table carries no project_id or repo_id (D9-08).
- */
-export class HookLiveness {
-    store;
-    options;
-    // v1.1.0 (K11-015) — debug counter for excess arity; never logged on hot path
-    excessArityCount = 0;
-    counters;
-    seenSessions;
-    suppressedSessions = new Set();
-    threshold;
-    pluginVersion;
-    constructor(store, options) {
-        this.store = store;
-        this.options = options;
-        this.threshold = parseThreshold(options.thresholdText);
-        this.pluginVersion = options.pluginVersion;
-        this.counters = new Map();
-        this.seenSessions = new Map();
-        for (const hook of HOOK_NAMES) {
-            this.counters.set(hook, {
-                fireCount: 0,
-                errorCount: 0,
-                expectedCount: 0,
-                firstSeenAt: null,
-                lastSeenAt: null,
-                deadSince: null,
-            });
-            this.seenSessions.set(hook, new Set());
-        }
-        this.loadFromDb();
-    }
-    /**
-     * Returns a new object with the same keys; function values are replaced
-     * by delegating wrappers, non-function values (the tool map) pass by
-     * reference. When liveness is disabled, returns the argument unchanged —
-     * the same object, not a copy.
-     */
-    wrap(hooks) {
-        if (!this.options.enabled)
-            return hooks;
-        const out = {};
-        for (const [key, value] of Object.entries(hooks)) {
-            if (typeof value === "function") {
-                out[key] = this.makeWrapper(key, value);
-            }
-            else {
-                out[key] = value;
-            }
-        }
-        return out;
-    }
-    /**
-     * v0.9.0 (K9-010 / plan §5.3) — a checkpoint: the session reached a
-     * model turn (tool.execute.after fired), so the system prompt was
-     * assembled and `experimental.chat.system.transform` MUST have been
-     * offered. Deduped per session: 20 tool calls in one session count
-     * exactly one expectation.
-     */
-    expect(hook, sessionID) {
-        const seen = this.seenSessions.get(hook);
-        if (!seen || seen.has(sessionID))
-            return;
-        seen.add(sessionID);
-        const counters = this.counters.get(hook);
-        if (!counters)
-            return;
-        counters.expectedCount += 1;
-        // The dead flag is materialized here (not only in report()) so that
-        // flush() persists dead_since even when no report() was ever called:
-        // kevin_doctor's PURE-SQL blocks read dead_since from the table.
-        if (counters.fireCount === 0 &&
-            counters.expectedCount >= this.threshold &&
-            counters.deadSince === null) {
-            counters.deadSince = counters.lastSeenAt ?? new Date().toISOString();
-        }
-        // v0.9.0 (K9-011 / plan §5.3) — when the injection hook is dead, the
-        // checkpointed session was suppressed: the host stopped offering the
-        // transform, so no injection could happen. Counted once per session
-        // (same dedup as expected_count) and persisted by flush(). This is
-        // the counter that turns "zero injections" from an ambiguous number
-        // into a diagnosis.
-        if (hook === "experimental.chat.system.transform" &&
-            counters.deadSince !== null &&
-            !this.suppressedSessions.has(sessionID)) {
-            this.suppressedSessions.add(sessionID);
-        }
-    }
-    /**
-     * Per-hook liveness verdicts in canonical HOOK_NAMES order.
-     * A hook that fired once is live forever; dead requires both zero fires
-     * and `expectedCount >= threshold`; everything else is unknown — and
-     * unknown is never rounded to healthy (D9-09).
-     */
-    report() {
-        const out = [];
-        for (const hook of HOOK_NAMES) {
-            const c = this.counters.get(hook);
-            if (!c)
-                continue;
-            let state;
-            if (c.fireCount > 0) {
-                state = "live";
-            }
-            else if (c.expectedCount >= this.threshold) {
-                // dead_since is set ONCE and never cleared: it documents the
-                // historical death even if the hook later recovers.
-                if (c.deadSince === null) {
-                    c.deadSince = c.lastSeenAt ?? new Date().toISOString();
-                }
-                state = "dead";
-            }
-            else {
-                state = "unknown";
-            }
-            out.push({
-                hook,
-                experimental: hook.startsWith("experimental."),
-                state,
-                firstSeenAt: c.firstSeenAt,
-                lastSeenAt: c.lastSeenAt,
-                fireCount: c.fireCount,
-                expectedCount: c.expectedCount,
-                deadSince: c.deadSince,
-            });
-        }
-        return out;
-    }
-    /** Persists every counter row. Called on the metrics.flush() cadence. */
-    flush() {
-        const store = this.store;
-        store.transaction(() => {
-            // Created lazily on first flush, mirroring Metrics.flush(): the
-            // migration guarantees the table in production, but unit tests
-            // against pre-010 DBs must not explode at dispose.
-            store.exec(`CREATE TABLE IF NOT EXISTS hook_liveness (
-				    hook          TEXT PRIMARY KEY,
-				    experimental  INTEGER NOT NULL DEFAULT 0,
-				    fire_count    INTEGER NOT NULL DEFAULT 0,
-				    error_count   INTEGER NOT NULL DEFAULT 0,
-				    expected_count INTEGER NOT NULL DEFAULT 0,
-				    first_seen_at TEXT,
-				    last_seen_at  TEXT,
-				    dead_since    TEXT,
-				    plugin_version TEXT
-				  )`);
-            const upsert = store.prepare(`INSERT INTO hook_liveness (hook, experimental, fire_count, error_count,
-				  expected_count, first_seen_at, last_seen_at, dead_since, plugin_version)
-				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-				 ON CONFLICT(hook) DO UPDATE SET
-				   experimental = excluded.experimental,
-				   fire_count = excluded.fire_count,
-				   error_count = excluded.error_count,
-				   expected_count = excluded.expected_count,
-				   first_seen_at = excluded.first_seen_at,
-				   last_seen_at = excluded.last_seen_at,
-				   dead_since = excluded.dead_since,
-				   plugin_version = excluded.plugin_version`);
-            for (const [hook, c] of this.counters) {
-                upsert.run(hook, hook.startsWith("experimental.") ? 1 : 0, c.fireCount, c.errorCount, c.expectedCount, c.firstSeenAt, c.lastSeenAt, c.deadSince, this.pluginVersion);
-            }
-            // v0.9.0 (K9-011 / plan §5.3) — the four v0.9.0 counters are
-            // re-derived here, on the metrics cadence, exactly like the 009
-            // post-apply hook re-derives hooks_dead_total: SUM(fire_count),
-            // SUM(error_count), COUNT(dead_since) and the per-session
-            // suppression count. No Metrics dependency, no writes in the hot
-            // path — flush() is the single persistence point.
-            let fireSum = 0;
-            let errorSum = 0;
-            let deadCount = 0;
-            for (const c of this.counters.values()) {
-                fireSum += c.fireCount;
-                errorSum += c.errorCount;
-                if (c.deadSince !== null)
-                    deadCount += 1;
-            }
-            store.exec(`CREATE TABLE IF NOT EXISTS kevin_metrics (
-				    key        TEXT PRIMARY KEY,
-				    value      INTEGER NOT NULL DEFAULT 0,
-				    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
-				  )`);
-            const derive = store.prepare(`INSERT INTO kevin_metrics (key, value, updated_at)
-				 VALUES (?, ?, datetime('now'))
-				 ON CONFLICT(key) DO UPDATE SET
-				   value = excluded.value,
-				   updated_at = datetime('now')`);
-            derive.run("hook_fires_total", fireSum);
-            derive.run("hook_errors_total", errorSum);
-            derive.run("hooks_dead_total", deadCount);
-            derive.run("injections_suppressed_dead_hook", this.suppressedSessions.size);
-        });
-    }
-    makeWrapper(key, delegate) {
-        const record = () => {
-            // v1.0.0 (K10-013) — dispose is recorded inside its own delegate
-            // (via recordDispose()) rather than here: the wrapper's post-return
-            // record would land after the store is closed and could never be
-            // persisted — the event being detected is the process ending.
-            if (key === "dispose")
-                return;
-            if (HOOK_NAMES.includes(key)) {
-                this.recordSuccess(key);
-            }
-        };
-        const recordError = (e) => {
-            if (HOOK_NAMES.includes(key)) {
-                this.recordError(key);
-            }
-            throw e;
-        };
-        // v1.1.0 (K11-015) — arity guard: maximum supported arity is 2 (plan §5.5).
-        // Excess args are sliced and counted via excessArityCount; never logged.
-        return async (...args) => {
-            let callArgs = args;
-            if (args.length > 2) {
-                this.excessArityCount++;
-                callArgs = args.slice(0, 2);
-            }
-            try {
-                const result = await delegate(...callArgs);
-                record();
-                return result;
-            }
-            catch (e) {
-                return recordError(e);
-            }
-        };
-    }
-    /**
-     * v1.0.0 (K10-013 / plan §5.3) — records the `dispose` fire and
-     * flushes immediately, from inside the dispose delegate: this is the
-     * last write of the process, and nothing after it can persist.
-     */
-    recordDispose() {
-        this.recordSuccess("dispose");
-        this.flush();
-    }
-    recordSuccess(hook) {
-        const c = this.counters.get(hook);
-        if (!c)
-            return;
-        c.fireCount += 1;
-        const now = new Date().toISOString();
-        if (c.firstSeenAt === null)
-            c.firstSeenAt = now;
-        c.lastSeenAt = now;
-    }
-    recordError(hook) {
-        const c = this.counters.get(hook);
-        if (!c)
-            return;
-        c.errorCount += 1;
-    }
-    loadFromDb() {
-        let rows = [];
-        try {
-            rows = this.store
-                .prepare("SELECT hook, fire_count, error_count, expected_count, first_seen_at, last_seen_at, dead_since FROM hook_liveness")
-                .all();
-        }
-        catch {
-            // Graceful: pre-010 DBs have no hook_liveness table; the seeded
-            // zeros remain until the first flush creates rows.
-            rows = [];
-        }
-        for (const row of rows) {
-            if (!HOOK_NAMES.includes(row.hook))
-                continue;
-            const c = this.counters.get(row.hook);
-            if (!c)
-                continue;
-            c.fireCount = row.fire_count;
-            c.errorCount = row.error_count;
-            c.expectedCount = row.expected_count;
-            c.firstSeenAt = row.first_seen_at;
-            c.lastSeenAt = row.last_seen_at;
-            c.deadSince = row.dead_since;
-        }
-    }
-}
-export function reduceVerdict(reports) {
-    if (reports.length === 0) {
-        return { verdict: "unknown", reason: "no hook reports yet" };
-    }
-    const dead = reports.filter((r) => r.state === "dead");
-    if (dead.length > 0) {
-        return {
-            verdict: "degraded",
-            reason: `${dead.map((r) => r.hook).join(", ")} dead since ${dead[0].deadSince ?? "unknown"}; ${dead.length} affected hook(s)`,
-        };
-    }
-    if (reports.every((r) => r.state === "live")) {
-        return { verdict: "healthy", reason: "all hooks live" };
-    }
-    const pending = reports.filter((r) => r.state === "unknown").length;
-    return {
-        verdict: "unknown",
-        reason: `${pending} hook(s) without checkpoint`,
-    };
-}

package/dist/plugin/InjectionLedger.d.ts

@@ -1,98 +0,0 @@
-import type { Store } from "./Store.js";
-import type { Metrics } from "./metrics.js";
-/**
- * v0.4.0 InjectionLedger (K4-006/K4-007, plan §5.2, D4-04).
- *
- * The measurement half of the closed feedback loop: every lesson injected
- * into a prompt is recorded in `kevin_injections`, and at `session.idle` the
- * ledger settles each unmeasured row — if the same fingerprint failed again
- * after the injection, the lesson is `ineffective`; otherwise `effective`.
- * `precision_rate = effective / total` is the honest, measured value of the
- * injection system (replacing Kevin_Token_Impact-style estimates).
- *
- * Schema (migration 005_v04_signal.sql):
- *   kevin_injections(id PK, memory_id, fingerprint, session_id, hook,
- *                    tokens, injected_at, outcome)
- *
- * BUG-015 — a ledger row is only meaningful when its fingerprint can be
- * matched against failing tool_calls (`COALESCE(error_fingerprint,
- * fingerprint)`). Memories WITHOUT a fingerprint (agent-saved notes) can
- * never match, so they are NOT recorded: settle() would otherwise mark
- * them `effective` forever and inflate `precision_rate`. The caller
- * (ContextInjector.recordInjections) skips them.
- */
-export type InjectionHook = "pre_prompt" | "compacting";
-export type InjectionOutcome = "unmeasured" | "effective" | "ineffective" | "inconclusive";
-export interface InjectionRecordInput {
-    memoryId: string;
-    fingerprint: string;
-    sessionId: string;
-    hook: InjectionHook;
-    tokens: number;
-    /**
-     * v0.8.0 (K8-024 / plan §5.7) — the memory's layer, passed by the
-     * caller (the injector already knows it — no lookup on the hot path).
-     * Drives the `injections_from_shared` counter.
-     */
-    layer?: string | null;
-}
-interface InjectionRow {
-    id: string;
-    memory_id: string;
-    fingerprint: string;
-    session_id: string;
-    hook: InjectionHook;
-    tokens: number;
-    injected_at: string;
-    outcome: InjectionOutcome;
-}
-export declare class InjectionLedger {
-    private readonly store;
-    private readonly metrics;
-    constructor(store: Store, metrics?: Metrics | null);
-    /**
-     * Records one injected memory. Idempotent at the row level (UUID PK);
-     * duplicates are expected only via the caller's per-session seen-set.
-     */
-    record(input: InjectionRecordInput): void;
-    /**
-     * Settles every unmeasured injection of the session: a fingerprint that
-     * failed again (as a failing tool_call) after the injection is
-     * `ineffective`, otherwise `effective`. Idempotent — only
-     * `outcome = 'unmeasured'` rows are flipped, and the recurrence charge
-     * is `MAX(recurrence_count, n)` where n = all failing calls of the
-     * fingerprint after `injected_at` (a later idle re-computes n and
-     * catches up — plan §5.1 rule 4: 3 recurrences → stale).
-     *
-     * An ineffective injection also bumps the target memory's
-     * `recurrence_count` (negative evidence, plan §5.3) and stamps
-     * `last_injected_at` (monotonically — an older row can never
-     * regress a newer injection's timestamp; the column means "most
-     * recent injection").
-     */
-    settle(sessionId: string): void;
-    /**
-     * Per-fingerprint failing tool-call counts for the session. Feeds
-     * QualityGate.canInject and the HITL suggestion block.
-     */
-    recurrencesFor(sessionId: string): Map<string, number>;
-    /**
-     * v0.4.0 (K4-017) — recurrence counts for the QualityGate at
-     * injection time: only failing calls that happened AFTER the
-     * fingerprint was already injected this session count. The failure
-     * that *created* a lesson is not a recurrence — it precedes any
-     * injection (plan §5.1 rule 4, same `ts >= injected_at` semantics
-     * `settle` uses).
-     */
-    postInjectionRecurrencesFor(sessionId: string): Map<string, number>;
-    /** Number of rows for the session not yet settled (drives tests and settle). */
-    unsettledForSession(sessionId: string): number;
-    /** Latest ledger rows for a session, newest first (used by tests/tools). */
-    rowsForSession(sessionId: string): InjectionRow[];
-    /**
-     * v0.5.0 (K5-005 / plan §8.4) — one grouped rollup over the whole
-     * ledger, zero-filled for every outcome. Consumed by `kevin_audit`.
-     */
-    outcomeCounts(): Record<InjectionOutcome, number>;
-}
-export {};