@jmtrin/opencode-kevin 0.3.0 → 0.5.0

package/dist/plugin/CausalChain.js

@@ -1,13 +1,20 @@
+import { extractFixArgs, } from "./LessonFixer.js";
 /** K3-007 — a success only links to a failure within this many calls. */
 const MAX_LINK_DISTANCE = 10;
 export class CausalChain {
     store;
     memoryService;
     metrics;
-    constructor(store, memoryService, metrics) {
+    enrichFn;
+    constructor(store, memoryService, metrics, 
+    // v0.4.0 (K4-015) — opt-in promotion-time LLM phrasing. Absent in
+    // production (zero network calls by default); injected by tests or
+    // by a future settings-driven wiring.
+    enrichFn) {
         this.store = store;
         this.memoryService = memoryService;
         this.metrics = metrics;
+        this.enrichFn = enrichFn;
     }
     // K3-007: link a success to the failing fingerprint only when it
     // occurred within MAX_LINK_DISTANCE tool calls of the failure (plan
@@ -18,7 +25,7 @@ export class CausalChain {
     // typecheck failure) was stamped as the fix for that error.
     onSuccess(_tool, _args, _projectId, sessionId) {
         const successRow = this.store
-            .prepare(`SELECT rowid FROM tool_calls
+            .prepare(`SELECT rowid, tool, args_summary FROM tool_calls
 				 WHERE session_id = ? AND success = 1
 				 ORDER BY rowid DESC LIMIT 1`)
             .get(sessionId);
@@ -50,7 +57,7 @@ export class CausalChain {
             const mem = this.store
                 .prepare(`SELECT 1 FROM memories
 					 WHERE fingerprint = ? AND type = 'error'
-					   AND origin = 'reflector' AND status = 'active'
+					   AND origin = 'reflector' AND status IN ('active', 'stale')
 					   AND created_at > datetime('now', '-24 hours')
 					 LIMIT 1`)
                 .get(fail.fp);
@@ -59,13 +66,27 @@ export class CausalChain {
             this.store
                 .prepare("UPDATE tool_calls SET fix_for_fingerprint = ? WHERE rowid = ?")
                 .run(fail.fp, successRow.rowid);
+            // v0.4.0 (K4-014) — deterministic "Fixed by:" raw material
+            // (plan §5.4 / D4-07): copy the linked success call's
+            // args_summary into memories.fix_args for every active row of
+            // that fingerprint (error + pattern), zero LLM cost.
+            const fixArgs = extractFixArgs({
+                tool: successRow.tool,
+                args_summary: successRow.args_summary ?? null,
+            });
+            if (fixArgs) {
+                this.store
+                    .prepare(`UPDATE memories SET fix_args = ?
+						 WHERE fingerprint = ? AND status IN ('active', 'stale')`)
+                    .run(fixArgs, fail.fp);
+            }
             this.metrics?.incr("causal_links", 1);
             return;
         }
     }
-    onSessionIdle(sessionId) {
+    async onSessionIdle(sessionId) {
         const linkedErrors = this.store
-            .prepare(`SELECT m.id, m.fingerprint,
+            .prepare(`SELECT m.id, m.fingerprint, m.recurrence_count,
 				        (SELECT COUNT(*)
 				         FROM tool_calls tc_all
 				         WHERE tc_all.fix_for_fingerprint = m.fingerprint) as evidence_count
@@ -77,26 +98,38 @@ export class CausalChain {
 				       FROM tool_calls
 				       WHERE session_id = ? AND fix_for_fingerprint IS NOT NULL
 				   )
-				   AND m.status = 'active'
+				   AND m.status IN ('active', 'stale')
 				 GROUP BY m.fingerprint
 				 HAVING (
-				     SELECT MAX(tc.rowid) FROM tool_calls tc
+				     SELECT MAX(tc.ts) FROM tool_calls tc
 				     WHERE tc.fix_for_fingerprint = m.fingerprint
-				 ) > COALESCE(
-				     (SELECT MAX(m2.rowid) FROM memories m2
+				 ) >= COALESCE(
+				     (SELECT MAX(m2.updated_at) FROM memories m2
 				      WHERE m2.fingerprint = m.fingerprint
 				        AND m2.type = 'pattern'
 				        AND m2.origin = 'causal'),
-				     0
+				     '1970-01-01'
 				 )`)
             .all(sessionId);
         let promoted = 0;
         for (const err of linkedErrors) {
             try {
-                const id = this.memoryService.promoteToPattern(err.id, err.evidence_count);
-                if (id) {
+                const result = this.memoryService.promoteToPattern(err.id, err.evidence_count, err.recurrence_count ?? 0);
+                if (result) {
                     promoted++;
-                    this.metrics?.incr("patterns_causal", 1);
+                    // v0.4.0 (K4-009) — only a NEW pattern row counts as a
+                    // promotion; the idempotent refresh path no longer
+                    // inflates the metric. `patterns_causal` is deprecated
+                    // (key kept for compat, never incremented).
+                    if (result.created) {
+                        this.metrics?.incr("patterns_promoted_new", 1);
+                        // v0.4.0 (K4-015) — promotion-time LLM enrichment:
+                        // at most one call per NEW pattern, gated on
+                        // `kevin_settings.llm_reflection_enabled` and the
+                        // per-pattern `metadata.enriched` marker. Never on
+                        // the failure hot path.
+                        await this.enrichIfEnabled(err.id, result.id);
+                    }
                 }
             }
             catch {
@@ -105,5 +138,42 @@ export class CausalChain {
         }
         return promoted;
     }
+    /**
+     * v0.4.0 (K4-015) — fire the opt-in enrich hook at most once per
+     * promoted pattern. The hook's one-line phrase replaces the
+     * deterministic `Fixed by:` line; null keeps it. A call (phrase or
+     * not) stamps `metadata.enriched` so repeated idle cycles stay at
+     * one LLM call per pattern.
+     */
+    async enrichIfEnabled(errorId, patternId) {
+        if (!this.enrichFn || !this.isLlmReflectionEnabled())
+            return;
+        const pattern = this.memoryService.getById(patternId);
+        if (!pattern)
+            return;
+        const meta = (pattern.metadata ?? {});
+        if (meta.enriched === true)
+            return;
+        const phrase = await this.enrichFn({
+            lesson: pattern.content,
+            fixArgs: pattern.fixArgs ?? null,
+            originalError: this.memoryService.getById(errorId)?.content ?? null,
+        });
+        const content = phrase
+            ? pattern.content.includes("\nFixed by: ")
+                ? pattern.content.replace(/\nFixed by: .+$/s, `\n${phrase}`)
+                : `${pattern.content}\n${phrase}`
+            : pattern.content;
+        this.memoryService.update(patternId, {
+            content,
+            metadata: { ...meta, enriched: true },
+        });
+    }
+    isLlmReflectionEnabled() {
+        const row = this.store
+            .prepare("SELECT value FROM kevin_settings WHERE key = ?")
+            .get("llm_reflection_enabled");
+        return row?.value === "1";
+    }
 }
 //# sourceMappingURL=CausalChain.js.map

package/dist/plugin/CausalChain.js.map

@@ -1 +1 @@
-{"version":3,"file":"CausalChain.js","sourceRoot":"","sources":["../../plugin/CausalChain.ts"],"names":[],"mappings":"AAIA,yEAAyE;AACzE,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,MAAM,OAAO,WAAW;IAEd;IACA;IACA;IAHT,YACS,KAAY,EACZ,aAA4B,EAC5B,OAAuB;QAFvB,UAAK,GAAL,KAAK,CAAO;QACZ,kBAAa,GAAb,aAAa,CAAe;QAC5B,YAAO,GAAP,OAAO,CAAgB;IAC7B,CAAC;IAEJ,iEAAiE;IACjE,oEAAoE;IACpE,8DAA8D;IAC9D,oEAAoE;IACpE,iEAAiE;IACjE,8DAA8D;IAC9D,4DAA4D;IAC5D,SAAS,CACR,KAAa,EACb,KAA8B,EAC9B,UAAyB,EACzB,SAAiB;QAEjB,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK;aAC3B,OAAO,CACP;;iCAE6B,CAC7B;aACA,GAAG,CAAC,SAAS,CAAkC,CAAC;QAClD,IAAI,CAAC,UAAU;YAAE,OAAO;QAExB,MAAM,SAAS,GAAG,IAAI,GAAG,CAEvB,IAAI,CAAC,KAAK;aACR,OAAO,CACP;gEAC0D,CAC1D;aACA,GAAG,CAAC,SAAS,CACf,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CACnC,CAAC;QAEF,+DAA+D;QAC/D,+DAA+D;QAC/D,+DAA+D;QAC/D,+DAA+D;QAC/D,iDAAiD;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK;aACzB,OAAO,CACP;;;;;iCAK6B,CAC7B;aACA,GAAG,CAAC,SAAS,EAAE,iBAAiB,CAG/B,CAAC;QAEJ,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAE,SAAS;YACjD,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;YAC3C,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,iBAAiB;gBAAE,SAAS;YAEpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK;iBACpB,OAAO,CACP;;;;cAIS,CACT;iBACA,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,IAAI,CAAC,GAAG;gBAAE,SAAS;YAEnB,IAAI,CAAC,KAAK;iBACR,OAAO,CACP,+DAA+D,CAC/D;iBACA,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;YACtC,OAAO;QACR,CAAC;IACF,CAAC;IAED,aAAa,CAAC,SAAiB;QAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK;aAC7B,OAAO,CACP;;;;;;;;;;;;;;;;;;;;;;;OAuBG,CACH;aACA,GAAG,CAAC,SAAS,CAIZ,CAAC;QAEJ,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAChC,IAAI,CAAC;gBACJ,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAC7C,GAAG,CAAC,EAAE,EACN,GAAG,CAAC,cAAc,CAClB,CAAC;gBACF,IAAI,EAAE,EAAE,CAAC;oBACR,QAAQ,EAAE,CAAC;oBACX,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;gBAC1C,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,4DAA4D;YAC7D,CAAC;QACF,CAAC;QAED,OAAO,QAAQ,CAAC;IACjB,CAAC;CACD"}
+{"version":3,"file":"CausalChain.js","sourceRoot":"","sources":["../../plugin/CausalChain.ts"],"names":[],"mappings":"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"}

package/dist/plugin/ContextInjector.d.ts

@@ -1,5 +1,9 @@
+import type { InjectionLedger } from "./InjectionLedger.js";
 import type { MemoryService } from "./MemoryService.js";
+import { type GateReason } from "./QualityGate.js";
 import { type Metrics } from "./metrics.js";
+export declare const QUALITY_GATE_SETTING = "quality_gate_enabled";
+export declare const SNIPPET_INJECTION_SETTING = "lesson_snippet_injection";
 export interface ChatMessage {
     role: string;
     content: string;
@@ -18,22 +22,68 @@ export interface CompactingInput {
 export interface CompactingOutput {
     context: string[];
 }
+export interface InjectionPlanItem {
+    id: string;
+    type: string;
+    decision: "admitted" | "blocked";
+    /** Gate reason when blocked; null for admitted items. */
+    reason?: GateReason;
+    /** Estimated tokens this memory would contribute to the block. */
+    tokens: number;
+}
+export interface InjectionPlan {
+    query: string;
+    tag: "context" | "memory";
+    cap: number;
+    would_inject: boolean;
+    /** Estimated tokens of the block that WOULD be produced (0 when
+     * nothing would be injected). */
+    total_tokens: number;
+    admitted: InjectionPlanItem[];
+    blocked: InjectionPlanItem[];
+}
 export declare class ContextInjector {
     private memoryService;
     private metrics;
+    private ledger;
     private lastRecurrenceCount;
-    constructor(memoryService: MemoryService, metrics?: Metrics | null);
+    /** v0.4.0 (K4-016) — session that produced the last recurrence set. */
+    private lastRecurredSession;
+    /** v0.4.0 (K4-017) — per-session seen-set (plan §5.1 rule 3). */
+    private readonly seenBySession;
+    constructor(memoryService: MemoryService, metrics?: Metrics | null, ledger?: InjectionLedger | null);
+    /**
+     * v0.4.0 (K4-017) — reset the per-session seen-set when a session is
+     * created (plan §5.1 rule 3). Wired from the `session.created` event.
+     */
+    onSessionCreated(sessionId: string): void;
     /**
      * v0.3.0 (K3-020) — notify the injector that the negative feedback half
      * fired N times in the last session.idle. The next system.transform or
      * compacting hook will prepend a HITL suggestion block.
+     * v0.4.0 (K4-016) — the session id enables the concrete suggestion:
+     * the most-recurred fingerprint's pattern + its fix_args.
      */
-    setRecurrences(count: number): void;
+    setRecurrences(count: number, sessionId?: string): void;
     /**
-     * v0.3.0 (K3-020) — generate a HITL suggestion block when recurrences
-     * occurred. Returns the block or empty string. Resets the counter.
+     * v0.4.0 (K4-016) — generate a CONCRETE HITL suggestion block when
+     * recurrences occurred (plan §5.5): names the most-recurred pattern,
+     * its exact recurrence count, observed fix_args and confidence. The
+     * AGENTS.md draft line derives from the lesson's `Suggestion:` text —
+     * never a canned string, and never the anonymous "the same error
+     * pattern" without naming the pattern and count.
+     *
+     * BUG-012 — emits AT MOST ONCE per session: calling it resets the
+     * pending recurrence signal, so whichever hook (system.transform or
+     * compacting) runs first in a session consumes the block. Documented
+     * behavior; wire index.ts to match.
      */
     generateSuggestion(): string;
+    /**
+     * v0.4.0 (K4-016) — the AGENTS.md draft line derives from the lesson's
+     * `Suggestion:` text (kept verbatim in the pattern's `Original:` block).
+     */
+    private agentsDraftLine;
     /**
      * v0.2.0 (K2-024): origin-aware ranking at injection time is delegated
      * to `MemoryService.getRelevant()` (K2-023, D2-13). The injector does
@@ -42,8 +92,106 @@ export declare class ContextInjector {
      * callers. Plan §B6.5: "apply the same multiplier as
      * MemoryService.recall so reflector lessons outrank agent-saved notes
      * at injection time" — satisfied transitively via the getRelevant call.
+     *
+     * v0.4.0 (K4-017): after retrieval, every memory is filtered through
+     * `QualityGate.canInject` (session seen-set + recurrence + strength),
+     * and each admitted memory is recorded in the `InjectionLedger`
+     * (plan §5.2 — one row per injected memory).
+     *
+     * v0.5.0 (K5-014 / plan §8.10) — the pipeline is decomposed into
+     * `fetchSlice` (ranked retrieval + budget overflow) + `evaluate`
+     * (pure gate verdicts) + this orchestrator, so the read-only `plan()`
+     * can mirror it without any side effect (D5-08).
      */
     private inject;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10) — the ranked-retrieval stage shared by
+     * `inject` and `plan`. With `dry = true` it is a strict read:
+     *
+     *  - the probe fetch never bumps (BUG-016), like the live path;
+     *  - the overflow retry ALSO fetches with `bump: false` (the live path
+     *    lets the retry fetch bump once — that is the only difference);
+     *  - the no-retry bump is skipped.
+     *
+     * This is what lets `plan()` predict the EXACT slice the live path
+     * would inject without mutating a single relevance score.
+     */
+    private fetchSlice;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10, D5-08) — PUBLIC read-only prediction of
+     * what `inject` WOULD do for a query: same retrieval, same gate, zero
+     * side effects. Never moves a counter, never writes the seen-set, never
+     * bumps relevance, never records ledger rows. `kevin_trace` (K5-015)
+     * surfaces this to the agent; tests freeze the clock + settings around
+     * it.
+     */
+    plan(query: string, options?: {
+        tag?: "context" | "memory";
+        cap?: number;
+        sessionId?: string;
+    }): InjectionPlan;
+    /**
+     * v0.5.0 (K5-014 / plan §8.10) — PURE gate evaluation shared by `admit`
+     * (live path) and `plan` (read-only path): returns the verdict for every
+     * candidate plus the seen-set as it WOULD look afterwards. Never writes
+     * state — the caller decides whether to persist.
+     */
+    private evaluate;
+    /**
+     * v0.5.0 (K5-017 / plan §8.11, D5-11) — the effective pre-prompt cap,
+     * read at call time from `pre_prompt_budget_tokens` (seeded "900" by
+     * migration 006). Clamped to [100, 4000]; a non-numeric value falls
+     * back to 900. `kevin_trace` reports the value used via `plan().cap`.
+     */
+    private prePromptCap;
+    /**
+     * v0.4.0 (K4-017) — QualityGate admission: filters the ranked slice to
+     * memories that may be injected this session, updating the session
+     * seen-set.
+     *
+     * v0.5.0 (K5-007 / plan §5.2, D5-04) — uses `canInjectVerdict` and
+     * increments the matching `injections_blocked_*` counter for every
+     * rejection, so gate policy becomes measurable. When `dryRun === true`
+     * the counters stay untouched (D5-08) — and so does the seen-set
+     * (a dry run is a strict read, K5-014).
+     *
+     * BUG-005 — strength/actionability now go through the REAL
+     * `QualityGate.evaluate` semantics (plan §5.1 rules 1-2), which this
+     * class had only re-derived from `metadata.dispatch`:
+     *   - dispatched code → strong + actionable (rescued errorType);
+     *   - generic fallback suggestion + no code → weak, NOT actionable
+     *     (the generic-suggestion ban is now enforced even for legacy
+     *     lessons without dispatch metadata, as long as the `Suggestion:`
+     *     text is available);
+     *   - specific suggestion without code → strong + actionable;
+     *   - no `Suggestion:` text at all (agent-saved note) → strong +
+     *     actionable — the agent explicitly asked to remember it;
+     *   - causal patterns (type='pattern') → always strong + actionable:
+     *     they are the FIXED form of a fingerprint (K4-025).
+     */
+    private admit;
+    /**
+     * BUG-005 — the single source of truth for a memory's lesson quality,
+     * shared by `admit` (the gate) and `format` (the K4-023 `(low
+     * confidence)` marker). Routes lessons through `QualityGate.evaluate`
+     * — the production call site that was previously missing.
+     */
+    private lessonQuality;
+    /**
+     * v0.4.0 (K4-017) — one ledger row per admitted memory (plan §5.2).
+     * Token attribution uses the memory's share of the final block.
+     */
+    private recordInjections;
+    /**
+     * v0.4.0 (K4-012) — snippet injection payload (plan §5.1 rule 5,
+     * D4-05): rows show `id:` + first 2 non-empty lines + `<protect>`
+     * instead of the full body. Gated by the `lesson_snippet_injection`
+     * setting (default `'1'`); when `'0'`, full content is restored.
+     * `escapeInjectedText` is applied to snippet content by the formatter.
+     * v0.4.0 (K4-023) — weak lessons admitted in debug mode are flagged so
+     * the formatter renders the `(low confidence)` marker.
+     */
+    private format;
     deriveQuery(messages: ChatMessage[]): string;
     onSystemTransform(input: SystemTransformInput, output: SystemTransformOutput): void;
     onCompacting(input: CompactingInput, output: CompactingOutput): void;