@jmtrin/opencode-kevin 0.4.0 → 0.6.0

package/dist/plugin/ArtifactWriter.js

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+import { closeSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { unifiedDiff } from "./diff.js";
+import { uuidv7 } from "./uuid.js";
+// v0.6.0 (K6-005 / plan §5.1, D6-02) — the frozen marker contract. The exact
+// byte sequences are load-bearing: README, v1.0.0 plan C-01 and the round-trip
+// test all depend on them.
+export const MARKER_BEGIN = "<!-- kevin:begin — curated by opencode-kevin, safe to edit -->";
+export const MARKER_END = "<!-- kevin:end -->";
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+ * Rule 5 (K6-008 / plan §5.1, D6-02) — the line-ending style comes from the
+ * FIRST line ending in the existing file: CRLF if it is CRLF, otherwise LF.
+ * A CRLF file whose last line lacks a terminator, and a mixed-ending file,
+ * are both resolved by the same first-ending rule, deterministically.
+ */
+function detectEol(text) {
+    const nl = text.indexOf("\n");
+    if (nl === -1)
+        return "\n";
+    return nl > 0 && text[nl - 1] === "\r" ? "\r\n" : "\n";
+}
+/**
+ * Rule 5 (K6-008) — normalize the generated body into the file's line-ending
+ * style so a CRLF file stays CRLF everywhere, including inside the block.
+ */
+function normalizeEol(body, eol) {
+    return body.replace(/\r\n/g, "\n").replace(/\n/g, eol);
+}
+/**
+ * Rule 9, layer (a) — the escaping discipline of `plugin/memory-format.ts`
+ * (`&`, `<`, `>`) made idempotent: an ampersand that already heads a known
+ * entity (`&amp;`, `&lt;`, `&gt;`, `&#NNN;`) is left alone, so sanitizing
+ * sanitized output is a fixed point. The round-trip property of the marker
+ * block depends on this: a non-idempotent escape would grow `&amp;lt;` on
+ * every regeneration (K6-009 / plan §5.1 rule 9).
+ */
+function escapeIdempotent(text) {
+    return text
+        .replace(/&(?!(amp|lt|gt|#\d+);)/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/**
+ * Rule 9 (K6-009 / plan §5.1, D6-02) — three layers applied to the body
+ * before splicing:
+ *   (a) the escaping discipline of `plugin/memory-format.ts`;
+ *   (b) strip any line containing `kevin:begin` or `kevin:end`, in any
+ *       casing, anywhere in the line;
+ *   (c) strip HTML comment terminators (`-->`).
+ * Without this, a memory containing a literal `<!-- kevin:end -->` line would
+ * close the marker comment early and let subsequent content escape the
+ * curated region on the next regeneration — a marker-injection variant of the
+ * v0.1.5 prompt-injection defect (plan §3.5).
+ */
+export function sanitizeArtifactBody(body) {
+    const escaped = escapeIdempotent(body);
+    const kept = escaped
+        .split("\n")
+        .filter((line) => !/kevin:begin|kevin:end/i.test(line))
+        .join("\n");
+    return kept.replace(/-->/g, "");
+}
+/**
+ * v0.6.0 (K6-005 / plan §5.1) — the single write path to disk (D6-01).
+ *
+ * `plan()` is pure: it reads the target file, locates the marker pair, splices
+ * the body between the markers and returns a {@link WritePlan}. It performs no
+ * writes — rule 1. `apply()` is implemented by K6-007; until then it is a stub
+ * that throws, so no caller can accidentally write before the audit trail
+ * exists.
+ *
+ * `projectId` is a constructor argument rather than a per-call argument so that
+ * every audit row is attributed without the call site having to remember.
+ */
+export class ArtifactWriter {
+    store;
+    projectId;
+    metrics;
+    constructor(store, projectId, metrics) {
+        this.store = store;
+        this.projectId = projectId;
+        this.metrics = metrics ?? null;
+    }
+    plan(path, body) {
+        let before;
+        try {
+            // Read as Buffer, not as utf8 text: readFileSync's text decoding
+            // strips a leading BOM, which would silently drop it on the next
+            // write. Buffer.toString keeps \uFEFF as a character of `before`.
+            before = readFileSync(path).toString("utf8");
+        }
+        catch (err) {
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                before = "";
+            }
+            else {
+                throw err;
+            }
+        }
+        const eol = detectEol(before);
+        // Rule 9 — sanitation happens in plan(), before hashing, so the hashes
+        // describe what was actually written.
+        const bodyEol = normalizeEol(sanitizeArtifactBody(body), eol);
+        const firstBegin = before.indexOf(MARKER_BEGIN);
+        const firstEnd = before.indexOf(MARKER_END);
+        let after;
+        let outcome = "written";
+        let reason;
+        if (firstBegin === -1 && firstEnd === -1) {
+            // Rule 2 — create: the block is appended at the end of the content,
+            // preceded by a blank line. For an empty file (missing file treated
+            // as "") the result is exactly: blank line, MARKER_BEGIN, body,
+            // MARKER_END, trailing newline.
+            const separator = before === "" ? eol : before.endsWith(eol) ? eol : eol + eol;
+            after =
+                before +
+                    separator +
+                    MARKER_BEGIN +
+                    eol +
+                    bodyEol +
+                    eol +
+                    MARKER_END +
+                    eol;
+        }
+        else if (firstBegin === -1 || firstEnd === -1) {
+            // Rule 3 — exactly one marker present.
+            after = before;
+            outcome = "refused";
+            reason =
+                firstBegin === -1
+                    ? "kevin:end marker present without kevin:begin"
+                    : "kevin:begin marker present without kevin:end";
+        }
+        else if (firstEnd < firstBegin) {
+            // Rule 3 — MARKER_END precedes MARKER_BEGIN.
+            after = before;
+            outcome = "refused";
+            reason = "kevin:end appears before kevin:begin";
+        }
+        else if (before.indexOf(MARKER_BEGIN, firstBegin + MARKER_BEGIN.length) !== -1 ||
+            before.indexOf(MARKER_END, firstEnd + MARKER_END.length) !== -1) {
+            // Rule 3 — more than one pair (any additional marker occurrence).
+            after = before;
+            outcome = "refused";
+            reason = "more than one marker pair present";
+        }
+        else {
+            // Rule 4 — bytes outside the marker pair are byte-identical. The
+            // block between the markers (begin marker, old block, end marker)
+            // is replaced by the regenerated block.
+            const blockEnd = firstEnd + MARKER_END.length;
+            after =
+                before.slice(0, firstBegin) +
+                    MARKER_BEGIN +
+                    eol +
+                    bodyEol +
+                    eol +
+                    MARKER_END +
+                    before.slice(blockEnd);
+            // Rule 6 — unchanged content is a noop, never a write.
+            outcome = after === before ? "noop" : "written";
+        }
+        return {
+            path,
+            before,
+            after,
+            // v0.6.0 (K6-006 / plan §5.2, D6-05) — approval prompts show bytes,
+            // never prose. Identical inputs yield "".
+            diff: unifiedDiff(path, before, after),
+            outcome,
+            ...(reason !== undefined ? { reason } : {}),
+            hashBefore: sha256(before),
+            hashAfter: sha256(after),
+        };
+    }
+    // v0.6.0 (K6-007 / plan §5.1, rules 7–8) — atomic write + audit row.
+    apply(plan, proposalId) {
+        // Rule 8 — refusals and noops still leave an audit trail; a refusal
+        // that leaves no trace is indistinguishable from a write that never
+        // happened. Rule 6 — a noop creates no temp file and writes nothing.
+        if (plan.outcome === "noop" || plan.outcome === "refused") {
+            if (plan.outcome === "noop") {
+                this.metrics?.incr("artifact_writes_noop", 1);
+            }
+            this.audit(plan, proposalId);
+            return plan.outcome;
+        }
+        // Rule 7 — write to `<path>.kevin.tmp` in the same directory (same
+        // filesystem, so rename is atomic), fsync, close, then rename over the
+        // target. Never write the target path directly, never truncate-then-write.
+        const tmpPath = `${plan.path}.kevin.tmp`;
+        let fd;
+        try {
+            fd = openSync(tmpPath, "w");
+            writeSync(fd, plan.after, null, "utf8");
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            this.renameTemp(tmpPath, plan.path);
+        }
+        catch (err) {
+            // Never leave .kevin.tmp litter next to the user's file.
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    // already closed or unusable; unlink below is the cleanup
+                }
+            }
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch {
+                // nothing to clean up
+            }
+            throw err;
+        }
+        this.metrics?.incr("artifact_writes_total", 1);
+        this.audit(plan, proposalId);
+        return "written";
+    }
+    // Fault-injection seam for the atomicity test: the rename is the point
+    // where a failure must leave the target untouched and the temp file gone.
+    renameTemp(tmpPath, target) {
+        renameSync(tmpPath, target);
+    }
+    audit(plan, proposalId) {
+        this.store
+            .prepare(`INSERT INTO artifact_writes
+				 (id, proposal_id, project_id, path, bytes_before, bytes_after,
+				  hash_before, hash_after, outcome, reason)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(uuidv7(), proposalId ?? null, this.projectId, plan.path, Buffer.byteLength(plan.before, "utf8"), Buffer.byteLength(plan.after, "utf8"), plan.hashBefore, plan.hashAfter, plan.outcome, plan.reason ?? null);
+    }
+}
+//# sourceMappingURL=ArtifactWriter.js.map

package/dist/plugin/ArtifactWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactWriter.js","sourceRoot":"","sources":["../../plugin/ArtifactWriter.ts"],"names":[],"mappings":"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"}

package/dist/plugin/ContextInjector.d.ts

@@ -1,8 +1,17 @@
 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";
+/**
+ * v0.6.0 (K6-023 / plan §5.8) — the effective pre-prompt budget shared by
+ * `ContextInjector.prePromptCap()` and `kevin_audit`'s channels block
+ * (budget_tokens). Single source of truth for the K6-021 clamp:
+ * default 400 when the raw value is missing/non-numeric, clamped to
+ * [0, 4000]; 0 means "push off".
+ */
+export declare function effectivePrePromptCap(raw: string | undefined): number;
 export interface ChatMessage {
     role: string;
     content: string;
@@ -21,6 +30,26 @@ 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;
@@ -76,13 +105,71 @@ export declare class ContextInjector {
      * `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`.
+     *
+     * v0.6.0 (K6-021 / plan §5.8) — default becomes "400" and the lower
+     * clamp bound drops to **0**: the roadmap's kill criterion K1 prescribes
+     * cutting the push budget to zero when coverage is poor, and v0.5's
+     * [100, 4000] clamp made that response unimplementable. A non-numeric
+     * value falls back to 400. `onSystemTransform` treats 0 as off and
+     * returns before any retrieval (see K6-021 acceptance).
+     */
+    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`: