@jmtrin/opencode-kevin 1.1.0 → 1.3.0

package/dist/plugin/ArtifactWriter.js

@@ -1,291 +0,0 @@
-import { createHash } from "node:crypto";
-import { closeSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
-import { unifiedDiff } from "./diff.js";
-import { escapeForFence, escapeForMarkerBlock, escapeForOkfLine, } from "./escape.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) — superseded in v1.0.0 by `escapeForMarkerBlock`
- * in `plugin/escape.ts` (K10-027), which carries the same idempotent
- * entity discipline.
- */
-/**
- * v1.0.0 (K10-027 / plan §5.7) — the boundary functions now live in
- * `plugin/escape.ts`; this composer applies them in fence-then-marker
- * order. Layer (b) — strip any line containing `kevin:begin` or
- * `kevin:end`, in any casing — is a filter rather than an escape and
- * stays here. Without layer (b), 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). The trailing `-->` strip is kept
- * as defence in depth although `escapeForMarkerBlock` already escapes
- * every `>` that could form one.
- */
-export function sanitizeArtifactBody(body) {
-    const escaped = escapeForMarkerBlock(escapeForFence(body));
-    const kept = escaped
-        .split("\n")
-        .filter((line) => !/kevin:begin|kevin:end/i.test(line))
-        .join("\n");
-    return kept.replace(/-->/g, "");
-}
-/**
- * v1.0.0 (K10-027 / plan §5.7, rule 2) — whole-file writes escape by
- * container. Only `.okf` files are line-oriented JSON: each line gets
- * `escapeForOkfLine`, which is the identity on a well-formed OKF line
- * (canonical JSON never contains raw control characters) and therefore
- * preserves the re-render `noop`. Kevin-owned markdown paths keep their
- * bytes — fences there are legitimate content.
- */
-export function escapeForContainer(path, content) {
-    if (!path.endsWith(".okf"))
-        return content;
-    return content
-        .split("\n")
-        .map((line) => {
-        // A CRLF file (healHeader preserves the original EOL) leaves a
-        // trailing \r on each line after the split — it is line-ending
-        // bytes, not statement content, so it must survive untouched.
-        if (line.endsWith("\r")) {
-            return `${escapeForOkfLine(line.slice(0, -1))}\r`;
-        }
-        return escapeForOkfLine(line);
-    })
-        .join("\n");
-}
-/**
- * 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(pathOrRequest, body) {
-        const request = typeof pathOrRequest === "string"
-            ? { path: pathOrRequest, mode: "markers", content: body ?? "" }
-            : pathOrRequest;
-        const { path, mode, content } = request;
-        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;
-            }
-        }
-        if (mode === "whole") {
-            // K8-019 (D8-08) — the whole-file path. The file is Kevin-owned,
-            // so there are no markers, no sanitization and no EOL
-            // normalization: the rendered bytes are written as-is, which is
-            // what makes a re-render of the same content a `noop`. A
-            // caller-side refusal leaves the file untouched and is audited
-            // like any other refusal: after = before, both hashes recorded.
-            const refusal = request.refusal;
-            const refused = refusal !== undefined;
-            // K10-027 — the container boundary: OKF lines are escaped at the
-            // single write path, never by callers.
-            const after = refused ? before : escapeForContainer(path, content);
-            return {
-                path,
-                before,
-                after,
-                diff: unifiedDiff(path, before, after),
-                outcome: refused ? "refused" : after === before ? "noop" : "written",
-                ...(refusal !== undefined ? { reason: refusal } : {}),
-                hashBefore: sha256(before),
-                hashAfter: sha256(after),
-            };
-        }
-        const eol = detectEol(before);
-        // Rule 9 — sanitation happens in plan(), before hashing, so the hashes
-        // describe what was actually written.
-        const bodyEol = normalizeEol(sanitizeArtifactBody(content), 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),
-        };
-    }
-    /**
-     * K8-019 (D8-08) — the single write funnel: every file Kevin writes
-     * goes through this method, which is the ONLY call site of `apply()`
-     * in the plugin (asserted by tests/unit/single_write_path.test.ts).
-     */
-    write(request, proposalId) {
-        return this.apply(this.plan(request), proposalId);
-    }
-    // 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);
-    }
-}

package/dist/plugin/CausalChain.d.ts

@@ -1,22 +0,0 @@
-import { type EnrichFn } from "./LessonFixer.js";
-import type { MemoryService } from "./MemoryService.js";
-import type { Store } from "./Store.js";
-import type { Metrics } from "./metrics.js";
-export declare class CausalChain {
-    private store;
-    private memoryService;
-    private metrics;
-    private enrichFn?;
-    constructor(store: Store, memoryService: MemoryService, metrics: Metrics | null, enrichFn?: EnrichFn | undefined);
-    onSuccess(_tool: string, _args: Record<string, unknown>, _projectId: string | null, sessionId: string): void;
-    onSessionIdle(sessionId: string): Promise<number>;
-    /**
-     * 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.
-     */
-    private enrichIfEnabled;
-    private isLlmReflectionEnabled;
-}

package/dist/plugin/CausalChain.js

@@ -1,197 +0,0 @@
-import { extractFixArgs, } from "./LessonFixer.js";
-import { hasColumn } from "./columns.js";
-import { toMs } from "./time-ms.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;
-    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
-    // §K3-007 acceptance: "within 24h and within 10 tool calls").
-    // v0.3.0 fix (bug #3) — the old code linked the most recent session
-    // success to the most recent unlinked error memory regardless of
-    // distance, so an unrelated success (e.g. an `ls` run after a
-    // typecheck failure) was stamped as the fix for that error.
-    onSuccess(_tool, _args, _projectId, sessionId) {
-        // v1.1.0 (K11-004 / plan §5.2, D11-01/D11-07) — ms-aware window: prefer _ms
-        const hasTsMs = hasColumn(this.store, "tool_calls", "ts_ms");
-        const successRow = (hasTsMs
-            ? this.store.prepare(`SELECT rowid, tool, args_summary, ts, ts_ms FROM tool_calls
-						 WHERE session_id = ? AND success = 1
-						 ORDER BY rowid DESC LIMIT 1`)
-            : this.store.prepare(`SELECT rowid, tool, args_summary, ts FROM tool_calls
-						 WHERE session_id = ? AND success = 1
-						 ORDER BY rowid DESC LIMIT 1`)).get(sessionId);
-        if (!successRow)
-            return;
-        const linkedFps = new Set(this.store
-            .prepare(`SELECT DISTINCT fix_for_fingerprint FROM tool_calls
-						 WHERE session_id = ? AND fix_for_fingerprint IS NOT NULL`)
-            .all(sessionId).map((r) => r.fix_for_fingerprint));
-        // Most recent failing calls in this session, newest first. The
-        // failing call's `error_fingerprint` (stamped by Reflector via
-        // onLinkError) is the SAME identity dimension the error memory
-        // uses; `fingerprint` is the legacy tool|args|success hash and
-        // simply never matches a reflector error memory.
-        const failRows = (hasTsMs
-            ? this.store.prepare(`SELECT rowid, COALESCE(error_fingerprint, fingerprint) AS fp, ts, ts_ms
-						 FROM tool_calls
-						 WHERE session_id = ?
-						   AND success = 0
-						   AND (error_fingerprint IS NOT NULL OR fingerprint IS NOT NULL)
-						 ORDER BY rowid DESC LIMIT ?`)
-            : this.store.prepare(`SELECT rowid, COALESCE(error_fingerprint, fingerprint) AS fp, ts
-						 FROM tool_calls
-						 WHERE session_id = ?
-						   AND success = 0
-						   AND (error_fingerprint IS NOT NULL OR fingerprint IS NOT NULL)
-						 ORDER BY rowid DESC LIMIT ?`)).all(sessionId, MAX_LINK_DISTANCE);
-        for (const fail of failRows) {
-            if (!fail.fp || linkedFps.has(fail.fp))
-                continue;
-            const dist = successRow.rowid - fail.rowid;
-            if (dist <= 0 || dist > MAX_LINK_DISTANCE)
-                continue;
-            // v1.1.0 — ≤24h window uses ms when available
-            const successMs = toMs(successRow.ts, successRow.ts_ms ?? null);
-            const failMs = toMs(fail.ts, fail.ts_ms ?? null);
-            if (successMs !== null && failMs !== null) {
-                const diff = successMs - failMs;
-                if (diff < 0 || diff > 86_400_000)
-                    continue;
-            }
-            const mem = this.store
-                .prepare(`SELECT 1 FROM memories
-					 WHERE fingerprint = ? AND type = 'error'
-					   AND origin = 'reflector' AND status IN ('active', 'stale')
-					   AND created_at > datetime('now', '-24 hours')
-					 LIMIT 1`)
-                .get(fail.fp);
-            if (!mem)
-                continue;
-            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;
-        }
-    }
-    async onSessionIdle(sessionId) {
-        const linkedErrors = this.store
-            .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
-				 FROM memories m
-				 WHERE m.type = 'error'
-				   AND m.origin = 'reflector'
-				   AND m.fingerprint IN (
-				       SELECT DISTINCT fix_for_fingerprint
-				       FROM tool_calls
-				       WHERE session_id = ? AND fix_for_fingerprint IS NOT NULL
-				   )
-				   AND m.status IN ('active', 'stale')
-				 GROUP BY m.fingerprint
-				 HAVING (
-				     SELECT MAX(tc.ts) FROM tool_calls tc
-				     WHERE tc.fix_for_fingerprint = m.fingerprint
-				 ) >= COALESCE(
-				     (SELECT MAX(m2.updated_at) FROM memories m2
-				      WHERE m2.fingerprint = m.fingerprint
-				        AND m2.type = 'pattern'
-				        AND m2.origin = 'causal'),
-				     '1970-01-01'
-				 )`)
-            .all(sessionId);
-        let promoted = 0;
-        for (const err of linkedErrors) {
-            try {
-                const result = this.memoryService.promoteToPattern(err.id, err.evidence_count, err.recurrence_count ?? 0);
-                if (result) {
-                    promoted++;
-                    // 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 {
-                // promoteToPattern may fail if the error memory was removed
-            }
-        }
-        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";
-    }
-}

package/dist/plugin/ConflictDetector.d.ts

@@ -1,35 +0,0 @@
-import type { MemoryService } from "./MemoryService.js";
-import type { RepoTruth } from "./RepoTruth.js";
-import type { Store } from "./Store.js";
-import type { Metrics } from "./metrics.js";
-export type ConflictKind = "repo_truth" | "decision_pair" | "temporal";
-export interface Conflict {
-    readonly id: string;
-    readonly kind: ConflictKind;
-    readonly memoryA: string;
-    readonly memoryB?: string;
-    readonly factId?: string;
-    readonly detail: string;
-}
-export interface RepoTruthConflictInput {
-    readonly memoryId: string;
-    readonly factId?: string | null;
-    readonly reasons: readonly string[];
-}
-export declare class ConflictDetector {
-    private readonly store;
-    private readonly projectId;
-    private readonly repoTruth?;
-    private readonly memoryService?;
-    private readonly metrics;
-    constructor(store: Store, projectId: string, metrics?: Metrics | null, repoTruth?: RepoTruth | undefined, memoryService?: MemoryService | undefined);
-    detect(repoTruthInput?: readonly RepoTruthConflictInput[]): Conflict[];
-    acknowledge(id: string): void;
-    /** Human-only operation. It resolves the conflict row, never a memory. */
-    resolve(id: string, keepMemoryId: string): void;
-    private detectRepoTruth;
-    private repoTruthInputs;
-    private detectDecisionPairs;
-    private detectTemporal;
-    private insertIfNew;
-}