@jmtrin/opencode-kevin 0.3.0 → 0.5.0

package/dist/plugin/index.js

@@ -3,8 +3,11 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { tool } from "@opencode-ai/plugin";
+import { Archiver } from "./Archiver.js";
 import { CausalChain } from "./CausalChain.js";
 import { ContextInjector } from "./ContextInjector.js";
+import { Feedback } from "./Feedback.js";
+import { InjectionLedger } from "./InjectionLedger.js";
 import { MemoryService, } from "./MemoryService.js";
 import { Migrate } from "./Migrate.js";
 import { PatternMiner } from "./PatternMiner.js";
@@ -12,13 +15,30 @@ import { ERROR_LINE_RE, Reflector, STRONG_ERROR_RE } from "./Reflector.js";
 import { Retrospective } from "./Retrospective.js";
 import { Store } from "./Store.js";
 import { ToolCallObserver } from "./ToolCallObserver.js";
+import { fingerprint } from "./fingerprint.js";
+import { buildAudit } from "./kevin_audit.js";
 import { kevinWhy } from "./kevin_why.js";
-import { formatMemories } from "./memory-format.js";
-import { Metrics, estimateTokens } from "./metrics.js";
+import { Metrics } from "./metrics.js";
 import { exportMarkdown, exportOkf } from "./okf-export.js";
 import { importOkf } from "./okf-import.js";
-const SYSTEM_TRANSFORM_TOKENS = 1500;
-const COMPACTING_TOKENS = 2000;
+/**
+ * v0.4.0 (K4-021) — settings surfaced by `kevin_config` (plan §8.8).
+ * Unknown keys are rejected on `set` unless `strict: false`.
+ */
+export const KEVIN_CONFIG_KEYS = [
+    "quality_gate_enabled",
+    "lesson_snippet_injection",
+    "patternminer_enabled",
+    "cross_project_enabled",
+    "llm_reflection_enabled",
+    "tool_calls_dedup_enabled",
+    // v0.5.0 (K5-003 / plan §8.13) — omitting these makes `kevin_config set`
+    // return { error: "unknown_key" } while `kevin_config list` still shows
+    // the keys seeded by migration 006.
+    "deterministic_retrieval",
+    "pre_prompt_budget_tokens",
+    "archive_after_days",
+];
 function resolveMigrationsDir() {
     const here = dirname(fileURLToPath(import.meta.url));
     return join(here, "..", "migrations");
@@ -35,6 +55,10 @@ export const KevinPlugin = async (input, options) => {
     const migrationsDir = opts.migrationsDir ?? resolveMigrationsDir();
     await new Migrate(store, migrationsDir).run();
     const metrics = new Metrics(store);
+    // v0.4.0 (K4-019): the plugin hooks expose no project field, so the
+    // project id is derived once from the plugin host's working directory
+    // (plan §5.7 fallback; D2-11 project scoping wired into the live path).
+    const projectId = fingerprint(process.cwd());
     const memoryService = new MemoryService(store, metrics);
     const observer = new ToolCallObserver(store, metrics);
     // v0.3.0 fix — Prepared UPDATE used by Reflector.onLinkError to stamp
@@ -53,14 +77,31 @@ export const KevinPlugin = async (input, options) => {
             linkErrorStmt.run(fp, callID);
         },
     }, metrics);
-    const injector = new ContextInjector(memoryService, metrics);
+    // v0.4.0 (K4-017): the single injection path. The inline transform/
+    // compacting logic was removed; the ContextInjector now owns the whole
+    // pipeline (QualityGate admission + snippet payload + ledger rows),
+    // so ledger and injector share the same store.
+    const ledger = new InjectionLedger(store, metrics);
+    const injector = new ContextInjector(memoryService, metrics, ledger);
+    // v0.5.0 (K5-009/011 / plan §5.3) — human feedback component behind the
+    // `kevin_feedback` tool; 'ignore' verdicts also stamp memories.ignored.
+    const feedback = new Feedback(store, metrics);
+    // v0.5.0 (K5-012 / plan §5.4) — retires stale memories at session.idle.
+    const archiver = new Archiver(store, memoryService, metrics);
     const retrospective = new Retrospective(store, memoryService, {
         dir: opts.retrospectivesDir,
     }, metrics);
     const patternMiner = new PatternMiner(store, memoryService, metrics);
     const causalChain = new CausalChain(store, memoryService, metrics);
     let currentSessionId = null;
+    // BUG-011 — process-global last derived query. Cleared on
+    // `session.idle`; the per-session map below is the preferred source.
     let lastUserQuery = null;
+    // v0.4.0 (K4-018) — compaction may fire without a recent chat.message
+    // (auto-compact after a long tool turn, resumed sessions). Keep the
+    // last derived query PER SESSION so the compacting hook can always
+    // resolve a query for the session it runs in.
+    const lastUserQueryBySession = new Map();
     const pending = new Set();
     const toolCache = new Map();
     const TOOL_CACHE_MAX = 500;
@@ -105,6 +146,7 @@ export const KevinPlugin = async (input, options) => {
             errorType,
             sessionId: sessionID,
             callID,
+            projectId,
         }));
     }
     return {
@@ -172,6 +214,10 @@ export const KevinPlugin = async (input, options) => {
                         type: args.type,
                         limit: args.limit,
                         full: args.full === true,
+                        // BUG-001 — pass the flag through so the slim mapper
+                        // can include the evidence fields (the old code cast
+                        // SlimMemory rows to Memory and read undefined fields).
+                        evidence: args.evidence === true,
                     });
                     const rows = args.full === true
                         ? memories.map((m) => ({
@@ -180,7 +226,7 @@ export const KevinPlugin = async (input, options) => {
                             content: m.content,
                             scope: m.scope,
                         }))
-                        : memories.map((m, i) => {
+                        : memories.map((m) => {
                             const base = {
                                 id: m.id,
                                 type: m.type,
@@ -189,12 +235,14 @@ export const KevinPlugin = async (input, options) => {
                                 snippet: m.snippet,
                             };
                             if (args.evidence === true) {
-                                const full = memories[i];
+                                // SlimMemoryWithEvidence — carried by the
+                                // mapper, no per-row getById needed.
+                                const ev = m;
                                 return {
                                     ...base,
-                                    confidence: full.confidence ?? null,
-                                    evidence_count: full.evidenceCount ?? null,
-                                    last_verified_at: full.lastVerifiedAt ?? null,
+                                    confidence: ev.confidence ?? null,
+                                    evidence_count: ev.evidence_count ?? null,
+                                    last_verified_at: ev.last_verified_at ?? null,
                                 };
                             }
                             return base;
@@ -238,6 +286,15 @@ export const KevinPlugin = async (input, options) => {
                             fingerprint: mem.fingerprint ?? null,
                             origin: mem.origin ?? null,
                             metadata: mem.metadata ?? null,
+                            // BUG-010 — v0.3/v0.4 evidence fields so kevin_get
+                            // is the full-fidelity read path (mapRow already
+                            // computes confidence via computeConfidence).
+                            confidence: mem.confidence ?? null,
+                            evidence_count: mem.evidenceCount ?? null,
+                            recurrence_count: mem.recurrenceCount ?? null,
+                            last_verified_at: mem.lastVerifiedAt ?? null,
+                            status: mem.status ?? "active",
+                            fix_args: mem.fixArgs ?? null,
                         }),
                     };
                 },
@@ -296,6 +353,45 @@ export const KevinPlugin = async (input, options) => {
                     const memoriesAgent = byOrigin.agent ?? 0;
                     const memoriesPattern = byOrigin.pattern ?? 0;
                     const memoriesCausal = byOrigin.causal ?? 0;
+                    // v0.4.0 (K4-024): per-origin recurrence_count totals
+                    // (plan §8.8 — honest negative-evidence breakdown).
+                    // Best-effort: DBs pre-005 lack the column; the rest of
+                    // the block must still work (same pattern as
+                    // ledger.settle in session.idle).
+                    let recurrenceByOrigin = {};
+                    try {
+                        const recRows = store
+                            .prepare(`SELECT origin, SUM(recurrence_count) as c
+								 FROM memories
+								 GROUP BY origin`)
+                            .all();
+                        for (const r of recRows) {
+                            recurrenceByOrigin[r.origin ?? "agent"] = r.c;
+                        }
+                    }
+                    catch {
+                        recurrenceByOrigin = {};
+                    }
+                    // v0.5.0 (K5-021 / plan §5.7) — lifecycle counts; best-effort
+                    // on pre-006 DBs (columns may be missing).
+                    let memoriesIgnored = 0;
+                    let memoriesArchived = 0;
+                    try {
+                        memoriesIgnored = store
+                            .prepare("SELECT COUNT(*) as c FROM memories WHERE ignored = 1")
+                            .get().c;
+                    }
+                    catch {
+                        memoriesIgnored = 0;
+                    }
+                    try {
+                        memoriesArchived = store
+                            .prepare("SELECT COUNT(*) as c FROM memories WHERE status = 'archived'")
+                            .get().c;
+                    }
+                    catch {
+                        memoriesArchived = 0;
+                    }
                     return {
                         title: "Estado de Kevin",
                         output: JSON.stringify({
@@ -307,10 +403,48 @@ export const KevinPlugin = async (input, options) => {
                             tool_calls: toolCallCount.c,
                             retrospectives: retroCount.c,
                             metrics: metrics.snapshot(),
+                            // v0.4.0 (K4-008): precision block. The
+                            // human-facing "patterns promoted" reading is
+                            // `patterns_promoted_new` (K4-009 corrected the
+                            // inflated `patterns_causal` counter; its key
+                            // stays frozen in metrics for compatibility).
+                            precision_rate: metrics.precisionRate(),
+                            injections_total: metrics.get("injections_total"),
+                            injections_effective: metrics.get("injections_effective"),
+                            injections_ineffective: metrics.get("injections_ineffective"),
+                            patterns_promoted_new: metrics.get("patterns_promoted_new"),
+                            // v0.4.0 (K4-024): per-origin recurrence totals.
+                            recurrence_by_origin: recurrenceByOrigin,
+                            // v0.5.0 (K5-021 / plan §5.7) — glassbox fields.
+                            injections_inconclusive: metrics.get("injections_inconclusive"),
+                            coverage_rate: metrics.coverageRate(),
+                            blocked: metrics.blockedSnapshot(),
+                            memories_ignored: memoriesIgnored,
+                            memories_archived: memoriesArchived,
+                            feedback: {
+                                positive: metrics.get("feedback_positive_total"),
+                                negative: metrics.get("feedback_negative_total"),
+                            },
                         }),
                     };
                 },
             }),
+            kevin_audit: tool({
+                description: 'Auditoria de solo lectura de la DB (v0.5.0, glassbox): memorias por status/origin/type, salud de inyecciones (precision/coverage), contadores bloqueados, feedback por verdicto, tokens inyectados. Sin writes, sin LLM. En DBs pre-006 devuelve los bloques computables con "partial": true. verbose añade el bloque settings.',
+                args: {
+                    verbose: tool.schema.boolean().default(false),
+                },
+                async execute(args) {
+                    const report = buildAudit(store, metrics);
+                    const payload = args.verbose
+                        ? report
+                        : { ...report, settings: undefined };
+                    return {
+                        title: "Auditoria de Kevin",
+                        output: JSON.stringify(payload),
+                    };
+                },
+            }),
             kevin_retrospective: tool({
                 description: "Genera un retrospective markdown para una sesion (resume tools que fallaron y lecciones aprendidas).",
                 args: {
@@ -361,6 +495,90 @@ export const KevinPlugin = async (input, options) => {
                     };
                 },
             }),
+            kevin_feedback: tool({
+                description: "Reporta juicio humano sobre una memoria (v0.5.0). verdict: useful | wrong | outdated | ignore. 'ignore' excluye la memoria de retrieval e inyeccion (D5-07); los demas ajustan confidence via computeConfidence (D5-02).",
+                args: {
+                    memory_id: tool.schema.string().min(1),
+                    verdict: tool.schema
+                        .enum(["useful", "wrong", "outdated", "ignore"])
+                        .describe("useful: la memoria ayudo. wrong: era incorrecta. outdated: ya no aplica. ignore: no volver a mostrarla."),
+                    note: tool.schema.string().optional(),
+                    session_id: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const memory = memoryService.getById(args.memory_id);
+                    if (!memory) {
+                        return {
+                            title: "Feedback no registrado",
+                            output: JSON.stringify({
+                                message: `No memory found for id "${args.memory_id}".`,
+                            }),
+                        };
+                    }
+                    try {
+                        const feedbackId = feedback.record({
+                            memoryId: args.memory_id,
+                            verdict: args.verdict,
+                            sessionId: args.session_id ?? currentSessionId ?? null,
+                            note: args.note,
+                        });
+                        const counts = feedback.countsFor(args.memory_id);
+                        return {
+                            title: "Feedback registrado",
+                            output: JSON.stringify({
+                                feedback_id: feedbackId,
+                                memory_id: args.memory_id,
+                                verdict: args.verdict,
+                                counters: counts,
+                                ignored: args.verdict === "ignore" ? true : memory.ignored === true,
+                            }),
+                        };
+                    }
+                    catch (err) {
+                        return {
+                            title: "Feedback no registrado",
+                            output: JSON.stringify({
+                                message: err instanceof Error ? err.message : String(err),
+                            }),
+                        };
+                    }
+                },
+            }),
+            kevin_trace: tool({
+                description: "Predice que memorias se inyectarian en el prompt para una query (v0.5.0, dry-run estricto). Retorna el plan: items admitidos/bloqueados con su razon, tokens totales estimados. NO inyecta, NO mueve contadores, NO muta el seen-set, NO hace bump de relevancia (D5-08). Si omites query, usa la ultima query derivada de la sesion.",
+                args: {
+                    query: tool.schema.string().optional(),
+                    session_id: tool.schema.string().optional(),
+                    tag: tool.schema
+                        .enum(["context", "memory"])
+                        .default("context")
+                        .describe("context = pre-prompt (cap por setting pre_prompt_budget_tokens, default 900), memory = compacting (cap 2000)"),
+                    cap: tool.schema.number().int().positive().optional(),
+                },
+                async execute(args) {
+                    const sid = args.session_id ?? currentSessionId ?? "";
+                    const query = args.query ??
+                        (sid ? (lastUserQueryBySession.get(sid) ?? null) : null) ??
+                        lastUserQuery;
+                    if (!query) {
+                        return {
+                            title: "Trace sin query",
+                            output: JSON.stringify({
+                                message: "No query derivada disponible. Pasa query explicitamente.",
+                            }),
+                        };
+                    }
+                    const plan = injector.plan(query, {
+                        tag: args.tag,
+                        cap: args.cap,
+                        sessionId: sid,
+                    });
+                    return {
+                        title: "Plan de inyeccion (dry-run)",
+                        output: JSON.stringify(plan),
+                    };
+                },
+            }),
             kevin_export: tool({
                 description: "Exporta memorias curadas (decision, rule, pattern) como markdown o formato OKF. v0.3.0.",
                 args: {
@@ -392,6 +610,68 @@ export const KevinPlugin = async (input, options) => {
                     };
                 },
             }),
+            kevin_config: tool({
+                description: "Lee o modifica settings de Kevin sin SQL (v0.4.0). list: todas las settings de kevin_settings. set: upsert de una key conocida (rechaza keys desconocidas salvo strict:false).",
+                args: {
+                    action: tool.schema.enum(["list", "set"]).describe("list | set"),
+                    key: tool.schema
+                        .string()
+                        .optional()
+                        .describe("Clave a modificar (action=set)."),
+                    value: tool.schema
+                        .string()
+                        .optional()
+                        .describe("Nuevo valor (action=set). Default '1'."),
+                    strict: tool.schema
+                        .boolean()
+                        .default(true)
+                        .optional()
+                        .describe("Con strict=true (default) se rechazan keys desconocidas."),
+                },
+                async execute(args) {
+                    if (args.action === "list") {
+                        const rows = store
+                            .prepare("SELECT key, value FROM kevin_settings ORDER BY key")
+                            .all();
+                        const settings = {};
+                        for (const r of rows)
+                            settings[r.key] = r.value;
+                        return {
+                            title: "Configuracion de Kevin",
+                            output: JSON.stringify(settings),
+                        };
+                    }
+                    if (!args.key) {
+                        return {
+                            title: "kevin_config",
+                            output: JSON.stringify({
+                                error: "missing_key",
+                                action: "set",
+                            }),
+                        };
+                    }
+                    const known = KEVIN_CONFIG_KEYS.includes(args.key);
+                    if (!known && args.strict !== false) {
+                        return {
+                            title: "kevin_config",
+                            output: JSON.stringify({
+                                error: "unknown_key",
+                                key: args.key,
+                                known_keys: [...KEVIN_CONFIG_KEYS],
+                            }),
+                        };
+                    }
+                    const value = args.value ?? "1";
+                    store
+                        .prepare(`INSERT INTO kevin_settings (key, value) VALUES (?, ?)
+							 ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
+                        .run(args.key, value);
+                    return {
+                        title: "kevin_config",
+                        output: JSON.stringify({ ok: true, key: args.key, value }),
+                    };
+                },
+            }),
         },
         "tool.execute.before": async (hookInput, output) => {
             rememberToolCall(hookInput.callID, hookInput.tool, output.args);
@@ -400,6 +680,7 @@ export const KevinPlugin = async (input, options) => {
                 args: output.args,
                 sessionId: hookInput.sessionID,
                 callID: hookInput.callID,
+                projectId,
             }, {});
         },
         "tool.execute.after": async (hookInput, output) => {
@@ -427,6 +708,7 @@ export const KevinPlugin = async (input, options) => {
                 args: hookInput.args,
                 sessionId: hookInput.sessionID,
                 callID: hookInput.callID,
+                projectId,
             }, { success, stdout, stderr, exitCode });
             if (!success) {
                 const errorType = observer.inferErrorType(stderr, stdout, exitCode);
@@ -439,13 +721,14 @@ export const KevinPlugin = async (input, options) => {
                     errorType,
                     sessionId: hookInput.sessionID,
                     callID: hookInput.callID,
+                    projectId,
                 }));
             }
             else {
-                causalChain.onSuccess(hookInput.tool, hookInput.args, null, hookInput.sessionID);
+                causalChain.onSuccess(hookInput.tool, hookInput.args, projectId, hookInput.sessionID);
             }
         },
-        "chat.message": async (_hookInput, output) => {
+        "chat.message": async (hookInput, output) => {
             const text = output.parts
                 .map((p) => p)
                 .filter((p) => p.type === "text")
@@ -454,63 +737,104 @@ export const KevinPlugin = async (input, options) => {
             if (text.trim()) {
                 const derived = injector.deriveQuery([{ role: "user", content: text }]);
                 lastUserQuery = derived.length > 0 ? derived : null;
+                if (hookInput.sessionID && lastUserQuery) {
+                    lastUserQueryBySession.set(hookInput.sessionID, lastUserQuery);
+                }
             }
         },
-        "experimental.chat.system.transform": async (_hookInput, output) => {
-            if (!lastUserQuery)
+        "experimental.chat.system.transform": async (hookInput, output) => {
+            // BUG-011 — prefer the per-session query so a new session whose
+            // first transform fires before any chat.message cannot reuse the
+            // previous session's query (the global is cleared on idle).
+            const query = lastUserQueryBySession.get(hookInput.sessionID ?? "") ?? lastUserQuery;
+            if (!query)
                 return;
             const suggestion = injector.generateSuggestion();
             if (suggestion)
                 output.system.push(suggestion);
-            const memories = memoryService.getRelevant({
-                query: lastUserQuery,
-                maxTokens: SYSTEM_TRANSFORM_TOKENS,
-                scope: "project",
-            });
-            const block = formatMemories(memories, "context");
-            if (block) {
-                output.system.push(block);
-                metrics.incr("tokens_injected_pre_prompt", estimateTokens(block));
-            }
+            injector.onSystemTransform({
+                sessionID: hookInput.sessionID ?? undefined,
+                messages: [{ role: "user", content: query }],
+            }, output);
         },
-        "experimental.session.compacting": async (_hookInput, output) => {
-            const query = lastUserQuery;
-            if (!query)
-                return;
+        "experimental.session.compacting": async (hookInput, output) => {
+            // v0.4.0 (K4-018) — plan §5.6: compaction often fires with no
+            // recent chat.message (auto-compact after a long tool turn,
+            // resumed sessions). Resolve a query per session first, then
+            // the global fallback, then any messages the runtime may
+            // provide (defensive — the current SDK contract only exposes
+            // sessionID).
+            // BUG-012 — the HITL suggestion fires AT MOST ONCE per session:
+            // whichever hook (transform or compacting) runs first consumes
+            // the pending recurrence signal (generateSuggestion resets it).
             const suggestion = injector.generateSuggestion();
             if (suggestion)
                 output.context.push(suggestion);
-            const memories = memoryService.getRelevant({
-                query,
-                maxTokens: COMPACTING_TOKENS,
-                scope: "project",
-            });
-            const block = formatMemories(memories, "memory");
-            if (block) {
-                output.context.push(block);
-                metrics.incr("tokens_injected_compacting", estimateTokens(block));
-            }
+            const sid = hookInput.sessionID;
+            const sessionQuery = lastUserQueryBySession.get(sid) ?? lastUserQuery;
+            const runtimeMessages = hookInput
+                .messages;
+            const messages = sessionQuery != null
+                ? [{ role: "user", content: sessionQuery }]
+                : (runtimeMessages ?? []);
+            injector.onCompacting({
+                sessionID: sid,
+                messages,
+            }, output);
         },
         event: async ({ event }) => {
             const type = event.type;
             const props = event.properties ?? {};
             if (type === "session.created") {
                 const info = props.info;
-                if (info?.id)
+                if (info?.id) {
                     currentSessionId = info.id;
+                    // BUG-011 — a fresh session must not inherit the
+                    // previous session's derived query (the global may
+                    // still hold it if no idle fired).
+                    lastUserQueryBySession.delete(info.id);
+                    // v0.4.0 (K4-017) — plan §5.1 rule 3: the per-session
+                    // seen-set resets when a session is created.
+                    injector.onSessionCreated(info.id);
+                }
             }
             else if (type === "session.idle") {
                 const sid = props.sessionID;
                 if (sid) {
                     toolCache.clear();
+                    // BUG-011 — the session is done: drop the global query
+                    // so the next session cannot reuse it.
+                    lastUserQuery = null;
+                    // v0.4.0 (K4-024) — plan §5.2: settle the session's
+                    // unmeasured injections (effective/ineffective +
+                    // recurrence_count charges) at idle. Best-effort: a
+                    // legacy DB without migration 005 has no ledger table.
+                    try {
+                        ledger.settle(sid);
+                    }
+                    catch {
+                        // best-effort: a legacy DB without the ledger
+                        // table must not break the idle path
+                    }
+                    // v0.5.0 (K5-012 / plan §5.4) — retire stale lessons at
+                    // idle; pre-006 DBs degrade to a no-op.
+                    try {
+                        archiver.run();
+                    }
+                    catch {
+                        // best-effort, same pattern as ledger.settle
+                    }
                     fireAndForget(retrospective.generate(sid));
                     memoryService.boostPositiveReflectors(sid);
                     const recurred = memoryService.penalizeRecurringReflectors(sid);
-                    injector.setRecurrences(recurred);
-                    patternMiner.mine();
-                    fireAndForget(Promise.resolve().then(() => {
-                        causalChain.onSessionIdle(sid);
-                    }));
+                    injector.setRecurrences(recurred, sid);
+                    patternMiner.mine(projectId);
+                    fireAndForget(Promise.resolve()
+                        .then(() => causalChain.onSessionIdle(sid))
+                        // non-blocking — promote is a best-effort pass
+                        // (legacy DBs pre-005 lack the recurrence_count
+                        // column)
+                        .catch(() => { }));
                 }
                 metrics.flush();
             }