@jmtrin/opencode-kevin 1.1.0 → 1.3.0

package/dist/plugin/Feedback.d.ts

@@ -1,67 +0,0 @@
-import type { Store } from "./Store.js";
-import type { Metrics } from "./metrics.js";
-/**
- * v0.5.0 Feedback (K5-009 / plan §5.3, D5-02).
- *
- * The human-judgement half of the glassbox: the agent can report whether a
- * memory was useful, wrong, outdated, or should be ignored. Verdicts are
- * stored in `memory_feedback` (migration 006_v05_glassbox.sql) and folded
- * into the memory's `feedback_positive` / `feedback_negative` counters —
- * kept SEPARATE from `evidence_count` / `recurrence_count` by design: human
- * judgement is evidence about the memory, causal counters are evidence
- * about the world (the confidence-poisoning defect closed in v0.4.0).
- *
- * D5-07 — the `ignore` verdict is a hard lifecycle action, not a soft
- * signal: the memory is stamped `ignored = 1`, which excludes it from
- * retrieval (K5-008) and from the quality gate (K5-007).
- *
- * Schema:
- *   memory_feedback(id PK, memory_id, verdict, session_id, note, created_at)
- *   memories(feedback_positive, feedback_negative, ignored)
- */
-export type FeedbackVerdict = "useful" | "wrong" | "outdated" | "ignore";
-export interface FeedbackRecordInput {
-    memoryId: string;
-    verdict: FeedbackVerdict;
-    sessionId?: string | null;
-    note?: string | null;
-}
-export interface FeedbackRow {
-    id: string;
-    memoryId: string;
-    verdict: FeedbackVerdict;
-    sessionId: string | null;
-    note: string | null;
-    createdAt: string;
-}
-export interface FeedbackCounts {
-    positive: number;
-    negative: number;
-}
-export declare class Feedback {
-    private readonly store;
-    private readonly metrics;
-    private readonly now;
-    constructor(store: Store, metrics?: Metrics | null, now?: () => Date);
-    /**
-     * Records one human verdict and folds it into the memory's counters.
-     * Counters are RECOMPUTED from the table (never incremented) so rows
-     * deleted in tests or by hand cannot drift them.
-     *
-     * The `ignore` verdict also stamps `memories.ignored = 1` (D5-07).
-     * Returns the feedback row id.
-     */
-    record(input: FeedbackRecordInput): string;
-    /** Human-judgement counters for one memory (from the row, not the table). */
-    countsFor(memoryId: string): FeedbackCounts;
-    /**
-     * Raw verdict history, newest first. Used by `kevin_feedback` (K5-011)
-     * and by the audit tool (K5-016).
-     */
-    list(memoryId?: string, limit?: number): FeedbackRow[];
-    /**
-     * Recompute a memory's positive/negative counters straight from the
-     * verdict table. Kept private — `record` is the only mutation path.
-     */
-    private recomputeCounters;
-}

package/dist/plugin/Feedback.js

@@ -1,120 +0,0 @@
-import { hasFeedbackTable } from "./columns.js";
-import { uuidv7 } from "./uuid.js";
-const POSITIVE_VERDICTS = ["useful"];
-const NEGATIVE_VERDICTS = [
-    "wrong",
-    "outdated",
-    "ignore",
-];
-// v1.1.0 (K11-011) — table probe delegates to columns registry
-export class Feedback {
-    store;
-    metrics;
-    now;
-    constructor(store, metrics, now = () => new Date()) {
-        this.store = store;
-        this.metrics = metrics ?? null;
-        this.now = now;
-    }
-    /**
-     * Records one human verdict and folds it into the memory's counters.
-     * Counters are RECOMPUTED from the table (never incremented) so rows
-     * deleted in tests or by hand cannot drift them.
-     *
-     * The `ignore` verdict also stamps `memories.ignored = 1` (D5-07).
-     * Returns the feedback row id.
-     */
-    record(input) {
-        if (!hasFeedbackTable(this.store)) {
-            throw new Error("kevin_feedback requires migration 006_v05_glassbox.sql (missing table memory_feedback)");
-        }
-        const id = uuidv7();
-        this.store
-            .prepare(`INSERT INTO memory_feedback
-				   (id, memory_id, verdict, session_id, note)
-				 VALUES (?, ?, ?, ?, ?)`)
-            .run(id, input.memoryId, input.verdict, input.sessionId ?? null, input.note ?? null);
-        this.recomputeCounters(input.memoryId);
-        if (input.verdict === "ignore") {
-            this.store
-                .prepare("UPDATE memories SET ignored = 1 WHERE id = ?")
-                .run(input.memoryId);
-        }
-        // v0.5.0 (K5-023 / plan §5.3, D5-06) — lifecycle action of a
-        // negative verdict. `wrong` is an opinion and deserves a second
-        // opinion: it demotes only at feedback_negative >= 2. `outdated`
-        // is a self-verifying claim about the world and acts at once.
-        // `useful` confirms the memory and refreshes its verification.
-        if (input.verdict === "outdated") {
-            this.store
-                .prepare("UPDATE memories SET status = 'stale' WHERE id = ?")
-                .run(input.memoryId);
-        }
-        else if (input.verdict === "wrong") {
-            const counts = this.countsFor(input.memoryId);
-            if (counts.negative >= 2) {
-                this.store
-                    .prepare("UPDATE memories SET status = 'stale' WHERE id = ?")
-                    .run(input.memoryId);
-            }
-        }
-        else if (input.verdict === "useful") {
-            this.store
-                .prepare("UPDATE memories SET last_verified_at = datetime('now') WHERE id = ?")
-                .run(input.memoryId);
-        }
-        if (POSITIVE_VERDICTS.includes(input.verdict)) {
-            this.metrics?.incr("feedback_positive_total", 1);
-        }
-        else if (NEGATIVE_VERDICTS.includes(input.verdict)) {
-            this.metrics?.incr("feedback_negative_total", 1);
-        }
-        return id;
-    }
-    /** Human-judgement counters for one memory (from the row, not the table). */
-    countsFor(memoryId) {
-        const row = this.store
-            .prepare("SELECT feedback_positive, feedback_negative FROM memories WHERE id = ?")
-            .get(memoryId);
-        if (!row)
-            return { positive: 0, negative: 0 };
-        return { positive: row.feedback_positive, negative: row.feedback_negative };
-    }
-    /**
-     * Raw verdict history, newest first. Used by `kevin_feedback` (K5-011)
-     * and by the audit tool (K5-016).
-     */
-    list(memoryId, limit = 50) {
-        const rows = this.store
-            .prepare(`SELECT id, memory_id, verdict, session_id, note, created_at
-				   FROM memory_feedback
-				  ${memoryId ? "WHERE memory_id = ?" : ""}
-				  ORDER BY created_at DESC, rowid DESC
-				  LIMIT ?`)
-            .all(...(memoryId ? [memoryId, limit] : [limit]));
-        return rows.map((r) => ({
-            id: r.id,
-            memoryId: r.memory_id,
-            verdict: r.verdict,
-            sessionId: r.session_id,
-            note: r.note,
-            createdAt: r.created_at,
-        }));
-    }
-    /**
-     * Recompute a memory's positive/negative counters straight from the
-     * verdict table. Kept private — `record` is the only mutation path.
-     */
-    recomputeCounters(memoryId) {
-        this.store
-            .prepare(`UPDATE memories SET
-				   feedback_positive = (
-				     SELECT COUNT(*) FROM memory_feedback
-				      WHERE memory_id = ? AND verdict = 'useful'),
-				   feedback_negative = (
-				     SELECT COUNT(*) FROM memory_feedback
-				      WHERE memory_id = ? AND verdict IN ('wrong','outdated','ignore'))
-				 WHERE id = ?`)
-            .run(memoryId, memoryId, memoryId);
-    }
-}

package/dist/plugin/HookLiveness.d.ts

@@ -1,88 +0,0 @@
-import { HOOK_NAMES } from "./Migrate.js";
-import type { Store } from "./Store.js";
-export type HookName = (typeof HOOK_NAMES)[number];
-export type LivenessState = "live" | "dead" | "unknown";
-export interface HookReport {
-    hook: HookName;
-    experimental: boolean;
-    state: LivenessState;
-    firstSeenAt: string | null;
-    lastSeenAt: string | null;
-    fireCount: number;
-    expectedCount: number;
-    /** v0.9.0 (K9-012) — set once when the hook went dead; never cleared. */
-    deadSince: string | null;
-}
-/**
- * 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 declare function parseThreshold(text: string | null | undefined): number;
-interface HookLivenessOptions {
-    /** `hook_liveness_enabled === "1"` (TEXT comparison, decided at construction). */
-    enabled: boolean;
-    /** Raw TEXT of `dead_hook_report_threshold`; parsed+clamped in report(). */
-    thresholdText: string | null | undefined;
-    /** `host.pluginVersion` at construction, stored on every flushed row. */
-    pluginVersion: string | null;
-}
-/**
- * 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 declare class HookLiveness {
-    private readonly store;
-    private readonly options;
-    excessArityCount: number;
-    private readonly counters;
-    private readonly seenSessions;
-    private readonly suppressedSessions;
-    private readonly threshold;
-    private readonly pluginVersion;
-    constructor(store: Store, options: HookLivenessOptions);
-    /**
-     * 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<T>(hooks: T): T;
-    /**
-     * 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: HookName, sessionID: string): void;
-    /**
-     * 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(): HookReport[];
-    /** Persists every counter row. Called on the metrics.flush() cadence. */
-    flush(): void;
-    private makeWrapper;
-    /**
-     * 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(): void;
-    private recordSuccess;
-    private recordError;
-    private loadFromDb;
-}
-export type HostVerdict = "healthy" | "degraded" | "unknown";
-export interface HostVerdictResult {
-    verdict: HostVerdict;
-    reason: string;
-}
-export declare function reduceVerdict(reports: readonly HookReport[]): HostVerdictResult;
-export {};

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`,
-    };
-}