@cairnkeep/cli 2.3.1 → 2.5.0

package/mcp-memory-server/dist/note-distiller.js

@@ -0,0 +1,177 @@
+import { createHash } from "node:crypto";
+import { buildFailureSignature } from "./failure-signature.js";
+import { enrichNoteEvidence } from "./note-enrichment.js";
+import { isNoteDistillationEnabled } from "./note-schema.js";
+import { applyDistilledSession, applyNoteEnrichment, getNoteEnrichmentEvidence, } from "./note-store.js";
+import { listTrajectories, showTrajectory } from "./trajectory-store.js";
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function string(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    const record = object(value);
+    if (!record)
+        return value;
+    return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, stableValue(item)]));
+}
+function hash(domain, value) {
+    return createHash("sha256").update(`cairnkeep:notes:v1:${domain}\0${JSON.stringify(stableValue(value))}`).digest("hex");
+}
+function validationKey(toolName, input) {
+    return hash("validation", { tool_name: toolName.trim().toLowerCase(), input });
+}
+function evidenceText(payload) {
+    for (const key of ["output", "message", "error", "stderr"]) {
+        const value = string(payload[key]);
+        if (value)
+            return value.slice(0, 32768);
+        if (payload[key] !== undefined && payload[key] !== null)
+            return JSON.stringify(stableValue(payload[key])).slice(0, 32768);
+    }
+    return "Unknown structured failure";
+}
+function explicitFailure(payload) {
+    if (payload.is_error === true)
+        return true;
+    for (const key of ["exit_code", "status", "status_code"]) {
+        const value = payload[key];
+        if (typeof value === "number" && Number.isFinite(value) && value !== 0)
+            return true;
+    }
+    return false;
+}
+function explicitSuccess(payload) {
+    if (payload.is_error === false)
+        return true;
+    for (const key of ["exit_code", "status", "status_code"])
+        if (payload[key] === 0)
+            return true;
+    return false;
+}
+function occurrence(session, sessionDigest, event, outcome, evidence, toolName, key) {
+    return {
+        session_id: session.session_id,
+        session_digest: sessionDigest,
+        ended_at: session.ended_at,
+        sequence: event.sequence,
+        outcome,
+        ...(toolName ? { tool_name: toolName.slice(0, 256) } : {}),
+        ...(key ? { validation_key: key } : {}),
+        evidence: evidence.replace(/\s+/g, " ").trim().slice(0, 4096) || "Structured event",
+    };
+}
+function extractSession(session) {
+    const sessionDigest = hash("trajectory", session);
+    const invocations = new Map();
+    const failures = [];
+    const successes = [];
+    for (const event of [...session.events].sort((a, b) => a.sequence - b.sequence)) {
+        const payload = object(event.payload) ?? {};
+        if (event.kind === "tool_invocation") {
+            const callId = string(payload.call_id);
+            const toolName = string(payload.tool_name);
+            if (callId && toolName)
+                invocations.set(callId, { toolName, input: payload.input, key: validationKey(toolName, payload.input) });
+            continue;
+        }
+        if (event.kind === "tool_result") {
+            const invocation = invocations.get(string(payload.call_id) ?? "");
+            if (!invocation)
+                continue;
+            if (explicitFailure(payload)) {
+                const raw = evidenceText(payload);
+                const signature = buildFailureSignature(raw, { root: session.project_root });
+                failures.push({
+                    signature,
+                    occurrence: occurrence(session, sessionDigest, event, "failure", signature.normalized_message, invocation.toolName, invocation.key),
+                    sequence: event.sequence,
+                });
+            }
+            else if (explicitSuccess(payload)) {
+                successes.push({
+                    validation_key: invocation.key,
+                    occurrence: occurrence(session, sessionDigest, event, "resolution", "Equivalent validation invocation succeeded.", invocation.toolName, invocation.key),
+                });
+            }
+            continue;
+        }
+        if (event.kind === "system_event" && payload.event === "model_error") {
+            const raw = evidenceText(payload);
+            const signature = buildFailureSignature(raw, { root: session.project_root, component: "model" });
+            failures.push({
+                signature,
+                occurrence: occurrence(session, sessionDigest, event, "failure", signature.normalized_message),
+                sequence: event.sequence,
+            });
+            continue;
+        }
+        if (event.kind === "model_output") {
+            const text = string(payload.text)?.trim();
+            if (!text || !/^(?:I am abandoning this approach|I will not pursue this strategy)\b/i.test(text))
+                continue;
+            const latest = [...failures].reverse().find((failure) => failure.sequence < event.sequence && !failure.abandonment);
+            if (latest)
+                latest.abandonment = occurrence(session, sessionDigest, event, "abandonment", text);
+        }
+    }
+    return { digest: sessionDigest, failures: failures.map(({ sequence: _sequence, ...failure }) => failure), successes };
+}
+export async function distillProject(options) {
+    if (!isNoteDistillationEnabled()) {
+        return {
+            schema_version: 1,
+            enabled: false,
+            created: [],
+            updated: [],
+            already_processed: [],
+            enrichment_skipped: [],
+            enrichment_failed: [],
+            failed: [],
+        };
+    }
+    const sessions = options.sessionId
+        ? [await showTrajectory(options.sessionId, options.projectRoot)]
+        : await (async () => {
+            const listed = await listTrajectories(options.projectRoot);
+            const selected = await Promise.all(listed.sessions.map((entry) => showTrajectory(entry.session_id, options.projectRoot)));
+            return selected.sort((left, right) => left.ended_at.localeCompare(right.ended_at) || left.session_id.localeCompare(right.session_id));
+        })();
+    const result = {
+        schema_version: 1,
+        enabled: true,
+        created: [],
+        updated: [],
+        already_processed: [],
+        enrichment_skipped: [],
+        enrichment_failed: [],
+        failed: [],
+    };
+    for (const session of sessions) {
+        const extracted = extractSession(session);
+        const stored = applyDistilledSession({
+            projectRoot: options.projectRoot,
+            sessionId: session.session_id,
+            sessionDigest: extracted.digest,
+            failures: extracted.failures,
+            successes: extracted.successes,
+        });
+        result.created.push(...stored.created);
+        result.updated.push(...stored.updated);
+        result.already_processed.push(...stored.already_processed);
+        for (const note of [...stored.created, ...stored.updated]) {
+            const enriched = await enrichNoteEvidence(getNoteEnrichmentEvidence(note.id));
+            if (enriched.status === "enriched")
+                applyNoteEnrichment(note.id, enriched.enrichment);
+            else if (enriched.status === "enrichment_skipped")
+                result.enrichment_skipped.push({ id: note.id, reason: enriched.reason });
+            else
+                result.enrichment_failed.push({ id: note.id, error: enriched.error });
+        }
+        result.project_id ??= stored.created[0]?.project_id ?? stored.updated[0]?.project_id;
+    }
+    return result;
+}

package/mcp-memory-server/dist/note-enrichment.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { isNoteDistillationEnabled, noteEnrichmentContentSchema } from "./note-schema.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const evidenceSchema = z.object({
+    id: z.string().min(1).max(256),
+    normalized_error: z.string().min(1).max(4096),
+    component: z.string().max(1024),
+    status: z.enum(["unresolved", "resolved", "abandoned"]),
+    attempts: z.array(z.string().min(1).max(4096)).max(64),
+}).strict();
+function truthy(value) {
+    return /^(?:1|true|yes|on)$/i.test(value?.trim() ?? "");
+}
+function config() {
+    if (!isNoteDistillationEnabled() || !truthy(process.env.CAIRN_NOTE_ENRICHMENT))
+        return null;
+    const apiKey = process.env.CAIRN_LLM_API_KEY?.trim();
+    const rawUrl = process.env.CAIRN_LLM_API_URL?.trim();
+    const model = process.env.CAIRN_NOTE_ENRICHMENT_MODEL?.trim();
+    if (!apiKey || !rawUrl || !model)
+        return null;
+    const url = new URL(rawUrl);
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw new Error("CAIRN_LLM_API_URL must use http or https.");
+    const rawTimeout = Number(process.env.CAIRN_NOTE_ENRICHMENT_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout >= 100 && rawTimeout <= 120_000
+        ? Math.floor(rawTimeout)
+        : DEFAULT_TIMEOUT_MS;
+    return { apiUrl: rawUrl.replace(/\/+$/, ""), apiKey, model, timeoutMs };
+}
+function parseContent(value) {
+    const stripped = value.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+    return noteEnrichmentContentSchema.parse(JSON.parse(stripped));
+}
+async function request(configured, evidence) {
+    const response = await fetch(`${configured.apiUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${configured.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: configured.model,
+            temperature: 0,
+            max_tokens: 1000,
+            response_format: { type: "json_object" },
+            messages: [
+                {
+                    role: "system",
+                    content: "Summarize the supplied already-redacted failure evidence. Return strict JSON with summary, lessons, and caveats. Do not infer failure identity, lifecycle, or provenance.",
+                },
+                { role: "user", content: JSON.stringify(evidence) },
+            ],
+        }),
+        signal: AbortSignal.timeout(configured.timeoutMs),
+    });
+    if (!response.ok)
+        throw new Error(`provider returned HTTP ${response.status}`);
+    const raw = await response.text();
+    if (Buffer.byteLength(raw, "utf8") > MAX_RESPONSE_BYTES)
+        throw new Error("provider response exceeded the local size limit");
+    const outer = z.object({
+        choices: z.array(z.object({ message: z.object({ content: z.string() }).passthrough() }).passthrough()).min(1),
+    }).passthrough().parse(JSON.parse(raw));
+    return parseContent(outer.choices[0].message.content);
+}
+export async function enrichNoteEvidence(rawEvidence) {
+    let configured;
+    try {
+        configured = config();
+    }
+    catch (error) {
+        return { status: "enrichment_failed", error: error instanceof Error ? error.message : "invalid enrichment configuration" };
+    }
+    if (!configured)
+        return { status: "enrichment_skipped", reason: "optional enrichment is disabled or incompletely configured" };
+    const parsed = evidenceSchema.safeParse(rawEvidence);
+    if (!parsed.success)
+        return { status: "enrichment_failed", error: "enrichment evidence failed local validation" };
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            return { status: "enriched", enrichment: await request(configured, parsed.data) };
+        }
+        catch (error) {
+            if (attempt === 1) {
+                const name = error instanceof Error ? error.name : "Error";
+                return { status: "enrichment_failed", error: `optional enrichment failed locally (${name})` };
+            }
+        }
+    }
+    return { status: "enrichment_failed", error: "optional enrichment failed locally" };
+}

package/mcp-memory-server/dist/note-schema.js

@@ -0,0 +1,4 @@
+export { NODE_SCHEMA_VERSION as NOTE_SCHEMA_VERSION, failureFrameSchema, failureLookupKeysSchema, failureSignatureSchema, noteEnrichmentContentSchema, noteNodeSchema, noteOccurrenceSchema, } from "./node-schema.js";
+export function isNoteDistillationEnabled(value = process.env.CAIRN_NOTE_DISTILLATION) {
+    return /^(?:1|true|yes|on)$/i.test(value?.trim() ?? "");
+}