@cairnkeep/cli 2.3.1 → 2.5.0

package/mcp-memory-server/dist/trajectory-cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { fitTrajectoryToBytes, normalizeClaudeTranscript, normalizeOpenCodeSession, normalizePiSession } from "./trajectory-normalize.js";
+import { redactTrajectory } from "./trajectory-redaction.js";
+import { getTrajectoryLimits } from "./trajectory-schema.js";
+import { doctorTrajectoryStore, listTrajectories, pruneTrajectories, putTrajectory, showTrajectory } from "./trajectory-store.js";
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+function usage() {
+    return `cairn trajectory — local structured session trajectories
+
+Usage:
+  cairn trajectory list [--json]
+  cairn trajectory show <session-id-or-prefix> [--json]
+  cairn trajectory prune [--dry-run] [--json]
+`;
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function humanList(value) {
+    if (value.sessions.length === 0)
+        return "No local trajectories found.";
+    const lines = value.sessions.map((entry) => [
+        entry.session_id,
+        entry.harness,
+        entry.ended_at,
+        `${entry.event_count} events`,
+        `${entry.logical_bytes} bytes`,
+    ].join("\t"));
+    return `${lines.join("\n")}\n${value.sessions.length} session(s), ${value.logical_bytes} logical bytes`;
+}
+function humanShow(value) {
+    return [
+        `Session: ${value.session_id}`,
+        `Harness: ${value.harness}`,
+        `Started: ${value.started_at}`,
+        `Ended: ${value.ended_at}`,
+        `Events: ${value.events.length}`,
+        `Truncated: ${value.capture.truncated ? "yes" : "no"}`,
+        "",
+        JSON.stringify(value.events, null, 2),
+    ].join("\n");
+}
+function humanPrune(value) {
+    const prefix = value.dry_run ? "Would remove" : "Removed";
+    return `${prefix} ${value.removed.length} session(s); ${value.remaining_sessions} remain (${value.logical_bytes} logical bytes).`;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function captureClaude(args) {
+    const [transcriptPath, projectRoot] = args;
+    if (!transcriptPath || !projectRoot)
+        throw new Error("capture-claude requires a transcript path and project root.");
+    const limits = getTrajectoryLimits();
+    const normalized = await normalizeClaudeTranscript(transcriptPath, projectRoot);
+    const redacted = redactTrajectory(normalized, projectRoot);
+    const fitted = fitTrajectoryToBytes(redacted, limits.sessionMaxBytes);
+    await putTrajectory(projectRoot, fitted, limits);
+}
+async function captureOpenCode(args) {
+    const [projectRoot] = args;
+    if (!projectRoot)
+        throw new Error("capture-opencode requires a project root.");
+    const limits = getTrajectoryLimits();
+    const normalized = normalizeOpenCodeSession(JSON.parse(await readStdin()), projectRoot);
+    const redacted = redactTrajectory(normalized, projectRoot);
+    const fitted = fitTrajectoryToBytes(redacted, limits.sessionMaxBytes);
+    await putTrajectory(projectRoot, fitted, limits);
+}
+async function capturePi(args) {
+    const [projectRoot] = args;
+    if (!projectRoot)
+        throw new Error("capture-pi requires a project root.");
+    const limits = getTrajectoryLimits();
+    const normalized = normalizePiSession(JSON.parse(await readStdin()), projectRoot);
+    const redacted = redactTrajectory(normalized, projectRoot);
+    const fitted = fitTrajectoryToBytes(redacted, limits.sessionMaxBytes);
+    await putTrajectory(projectRoot, fitted, limits);
+}
+async function main() {
+    const [command = "help", ...args] = process.argv.slice(2);
+    if (command === "capture-claude" || command === "capture-opencode" || command === "capture-pi") {
+        try {
+            if (command === "capture-claude")
+                await captureClaude(args);
+            else if (command === "capture-opencode")
+                await captureOpenCode(args);
+            else
+                await capturePi(args);
+        }
+        catch {
+            process.stderr.write("trajectory capture skipped: local validation or persistence failed\n");
+        }
+        return;
+    }
+    try {
+        if (command === "list") {
+            const value = await listTrajectories(process.cwd());
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : humanList(value)}\n`);
+            return;
+        }
+        if (command === "show") {
+            const identifier = args.find((arg) => !arg.startsWith("-"));
+            if (!identifier)
+                throw new Error("show requires a session ID or unambiguous prefix.");
+            const value = await showTrajectory(identifier, process.cwd());
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : humanShow(value)}\n`);
+            return;
+        }
+        if (command === "prune") {
+            const value = await pruneTrajectories(process.cwd(), getTrajectoryLimits(), hasFlag(args, "--dry-run"));
+            process.stdout.write(`${hasFlag(args, "--json") ? JSON.stringify(value) : humanPrune(value)}\n`);
+            return;
+        }
+        if (command === "doctor") {
+            const value = await doctorTrajectoryStore(process.cwd(), hasFlag(args, "--repair"));
+            process.stdout.write(`${JSON.stringify(value)}\n`);
+            if (!value.ok)
+                process.exitCode = 2;
+            return;
+        }
+        if (command === "help" || command === "--help" || command === "-h") {
+            process.stdout.write(usage());
+            return;
+        }
+        throw new Error(`unknown trajectory command "${command}".`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "unknown error";
+        process.stderr.write(`cairn trajectory: ${message}\n`);
+        process.exitCode = 2;
+    }
+}
+await main();

package/mcp-memory-server/dist/trajectory-normalize.js

@@ -0,0 +1,448 @@
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { resolve } from "node:path";
+import { TRAJECTORY_SCHEMA_VERSION, trajectorySessionSchema, } from "./trajectory-schema.js";
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function array(value) {
+    return Array.isArray(value) ? value : [];
+}
+function string(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function number(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function isoTimestamp(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return new Date(value).toISOString();
+    if (typeof value !== "string" || Number.isNaN(Date.parse(value)))
+        return undefined;
+    return new Date(value).toISOString();
+}
+function addUsage(total, usage) {
+    for (const key of Object.keys(usage)) {
+        const value = usage[key];
+        if (value === undefined)
+            continue;
+        total[key] = (total[key] ?? 0) + value;
+    }
+}
+function compactUsage(value) {
+    return Object.values(value).some((item) => item !== undefined) ? value : undefined;
+}
+function usageFromClaude(value) {
+    const usage = object(value);
+    if (!usage)
+        return undefined;
+    return compactUsage({
+        input_tokens: number(usage.input_tokens),
+        output_tokens: number(usage.output_tokens),
+        cache_read_tokens: number(usage.cache_read_input_tokens),
+        cache_write_tokens: number(usage.cache_creation_input_tokens),
+    });
+}
+function usageFromOpenCode(value, cost) {
+    const usage = object(value);
+    if (!usage && number(cost) === undefined)
+        return undefined;
+    const cache = object(usage?.cache);
+    return compactUsage({
+        input_tokens: number(usage?.input),
+        output_tokens: number(usage?.output),
+        reasoning_tokens: number(usage?.reasoning),
+        cache_read_tokens: number(cache?.read),
+        cache_write_tokens: number(cache?.write),
+        cost: number(cost),
+    });
+}
+function usageFromPi(value) {
+    const usage = object(value);
+    if (!usage)
+        return undefined;
+    const cost = object(usage.cost);
+    return compactUsage({
+        input_tokens: number(usage.input),
+        output_tokens: number(usage.output),
+        cache_read_tokens: number(usage.cacheRead),
+        cache_write_tokens: number(usage.cacheWrite),
+        cost: number(cost?.total),
+    });
+}
+function createState() {
+    return { events: [], usage: {}, timestamps: [], omittedReasoning: 0, omittedUnknown: 0 };
+}
+function pushEvent(state, kind, payload, timestamp, nativeId, parentId) {
+    if (timestamp)
+        state.timestamps.push(timestamp);
+    state.events.push({
+        sequence: state.events.length,
+        kind,
+        ...(timestamp ? { timestamp } : {}),
+        ...(nativeId ? { native_id: nativeId } : {}),
+        ...(parentId ? { parent_id: parentId } : {}),
+        payload,
+    });
+}
+function pushUsage(state, usage, timestamp, nativeId) {
+    addUsage(state.usage, usage);
+    pushEvent(state, "usage", usage, timestamp, nativeId);
+}
+function finalize(state, sessionId, harness, projectRoot, explicitStart, explicitEnd) {
+    const sorted = [...state.timestamps].sort();
+    const now = new Date().toISOString();
+    const startedAt = explicitStart ?? sorted[0] ?? now;
+    const endedAt = explicitEnd ?? sorted.at(-1) ?? startedAt;
+    return trajectorySessionSchema.parse({
+        schema_version: TRAJECTORY_SCHEMA_VERSION,
+        session_id: sessionId,
+        harness,
+        project_root: resolve(projectRoot),
+        started_at: startedAt,
+        ended_at: endedAt,
+        ...(compactUsage(state.usage) ? { usage: state.usage } : {}),
+        events: state.events.map((event, sequence) => ({ ...event, sequence })),
+        capture: {
+            captured_at: now,
+            omitted_reasoning_blocks: state.omittedReasoning,
+            omitted_unknown_records: state.omittedUnknown,
+            truncated: false,
+        },
+    });
+}
+export async function normalizeClaudeTranscript(transcriptPath, projectRoot) {
+    const state = createState();
+    let sessionId;
+    let pendingUsage;
+    const lines = createInterface({ input: createReadStream(transcriptPath, { encoding: "utf8" }), crlfDelay: Infinity });
+    const flushPendingUsage = () => {
+        if (!pendingUsage)
+            return;
+        pushUsage(state, pendingUsage.usage, pendingUsage.timestamp, pendingUsage.nativeId);
+        pendingUsage = undefined;
+    };
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = object(JSON.parse(line)) ?? {};
+        }
+        catch {
+            state.omittedUnknown += 1;
+            continue;
+        }
+        sessionId ??= string(row.sessionId);
+        const type = string(row.type);
+        const timestamp = isoTimestamp(row.timestamp);
+        const nativeId = string(row.uuid);
+        const parentId = string(row.parentUuid);
+        if (type === "system") {
+            flushPendingUsage();
+            pushEvent(state, "system_event", { event: string(row.subtype) ?? "system" }, timestamp, nativeId, parentId);
+            continue;
+        }
+        if (type !== "user" && type !== "assistant") {
+            state.omittedUnknown += 1;
+            continue;
+        }
+        const message = object(row.message);
+        const rawContent = message?.content;
+        const content = typeof rawContent === "string"
+            ? [{ type: "text", text: rawContent }]
+            : array(rawContent);
+        const isAssistant = type === "assistant";
+        let emittedToolInvocation = false;
+        let emittedToolResult = false;
+        const hasToolResult = !isAssistant && content.some((item) => string(object(item)?.type) === "tool_result");
+        if (!isAssistant && !hasToolResult)
+            flushPendingUsage();
+        for (const item of content) {
+            const part = object(item);
+            const partType = string(part?.type);
+            if (partType === "thinking" || partType === "reasoning") {
+                state.omittedReasoning += 1;
+                continue;
+            }
+            if (partType === "text") {
+                const text = string(part?.text);
+                if (text)
+                    pushEvent(state, isAssistant ? "model_output" : "user_message", { text }, timestamp, nativeId, parentId);
+                continue;
+            }
+            if (partType === "tool_use" && isAssistant) {
+                emittedToolInvocation = true;
+                pushEvent(state, "tool_invocation", {
+                    call_id: string(part?.id) ?? "",
+                    tool_name: string(part?.name) ?? "unknown",
+                    input: part?.input ?? null,
+                }, timestamp, nativeId, parentId);
+                continue;
+            }
+            if (partType === "tool_result") {
+                emittedToolResult = true;
+                pushEvent(state, "tool_result", {
+                    call_id: string(part?.tool_use_id) ?? "",
+                    output: part?.content ?? null,
+                    is_error: part?.is_error === true,
+                }, timestamp, nativeId, parentId);
+                continue;
+            }
+            state.omittedUnknown += 1;
+        }
+        const usage = usageFromClaude(message?.usage);
+        if (usage) {
+            if (emittedToolInvocation && !emittedToolResult)
+                pendingUsage = { usage, timestamp, nativeId };
+            else
+                pushUsage(state, usage, timestamp, nativeId);
+        }
+        if (emittedToolResult)
+            flushPendingUsage();
+    }
+    flushPendingUsage();
+    if (!sessionId)
+        throw new Error("Claude transcript did not contain a session ID.");
+    return finalize(state, sessionId, "claude-code", projectRoot);
+}
+export function normalizeOpenCodeSession(raw, projectRoot) {
+    const root = object(raw);
+    const session = object(root?.session);
+    const sessionId = string(session?.id);
+    if (!sessionId)
+        throw new Error("OpenCode session did not contain an ID.");
+    const sessionTime = object(session?.time);
+    const explicitStart = isoTimestamp(sessionTime?.created);
+    const explicitEnd = isoTimestamp(sessionTime?.updated);
+    const state = createState();
+    pushEvent(state, "system_event", { event: "session_start" }, explicitStart);
+    for (const rawMessage of array(root?.messages)) {
+        const message = object(rawMessage);
+        const info = object(message?.info);
+        const role = string(info?.role);
+        if (role !== "user" && role !== "assistant") {
+            state.omittedUnknown += 1;
+            continue;
+        }
+        const time = object(info?.time);
+        const timestamp = isoTimestamp(time?.created);
+        const nativeId = string(info?.id);
+        let emittedStepUsage = false;
+        for (const rawPart of array(message?.parts)) {
+            const part = object(rawPart);
+            const partType = string(part?.type);
+            if (partType === "reasoning" || partType === "thinking") {
+                state.omittedReasoning += 1;
+                continue;
+            }
+            if (partType === "text") {
+                const text = string(part?.text);
+                if (text)
+                    pushEvent(state, role === "assistant" ? "model_output" : "user_message", { text }, timestamp, nativeId);
+                continue;
+            }
+            if (partType === "tool" && role === "assistant") {
+                const toolState = object(part?.state);
+                const callId = string(part?.callID) ?? "";
+                const toolTimestamp = isoTimestamp(object(toolState?.time)?.start) ?? timestamp;
+                pushEvent(state, "tool_invocation", {
+                    call_id: callId,
+                    tool_name: string(part?.tool) ?? "unknown",
+                    input: toolState?.input ?? null,
+                }, toolTimestamp, string(part?.id), nativeId);
+                if (toolState && ("output" in toolState || "error" in toolState)) {
+                    pushEvent(state, "tool_result", {
+                        call_id: callId,
+                        output: toolState.output ?? toolState.error ?? null,
+                        is_error: toolState.status === "error" || "error" in toolState,
+                    }, isoTimestamp(object(toolState.time)?.end) ?? timestamp, string(part?.id), nativeId);
+                }
+                continue;
+            }
+            if (partType === "step-finish") {
+                const usage = usageFromOpenCode(part?.tokens, part?.cost);
+                if (usage) {
+                    pushUsage(state, usage, timestamp, string(part?.id));
+                    emittedStepUsage = true;
+                }
+                continue;
+            }
+            state.omittedUnknown += 1;
+        }
+        if (role === "assistant" && !emittedStepUsage) {
+            const usage = usageFromOpenCode(info?.tokens, info?.cost);
+            if (usage)
+                pushUsage(state, usage, isoTimestamp(time?.completed) ?? timestamp, nativeId);
+        }
+    }
+    return finalize(state, sessionId, "opencode", projectRoot, explicitStart, explicitEnd);
+}
+function piTextContent(value, state) {
+    if (typeof value === "string")
+        return value.length > 0 ? [value] : [];
+    const texts = [];
+    for (const rawPart of array(value)) {
+        const part = object(rawPart);
+        if (string(part?.type) === "text") {
+            const text = string(part?.text);
+            if (text)
+                texts.push(text);
+        }
+        else {
+            state.omittedUnknown += 1;
+        }
+    }
+    return texts;
+}
+export function normalizePiSession(raw, projectRoot) {
+    const root = object(raw);
+    const session = object(root?.session);
+    const sessionId = string(session?.id);
+    if (!sessionId)
+        throw new Error("Pi session did not contain an ID.");
+    const state = createState();
+    for (const rawEntry of array(session?.entries)) {
+        const entry = object(rawEntry);
+        const type = string(entry?.type);
+        const timestamp = isoTimestamp(entry?.timestamp);
+        const nativeId = string(entry?.id);
+        const parentId = string(entry?.parentId);
+        if (type === "model_change") {
+            pushEvent(state, "system_event", {
+                event: "model_change",
+                provider: string(entry?.provider) ?? "unknown",
+                model: string(entry?.modelId) ?? "unknown",
+            }, timestamp, nativeId, parentId);
+            continue;
+        }
+        if (type === "thinking_level_change") {
+            pushEvent(state, "system_event", {
+                event: "thinking_level_change",
+                level: string(entry?.thinkingLevel) ?? "unknown",
+            }, timestamp, nativeId, parentId);
+            continue;
+        }
+        if (type !== "message") {
+            state.omittedUnknown += 1;
+            continue;
+        }
+        const message = object(entry?.message);
+        const role = string(message?.role);
+        const messageTimestamp = timestamp ?? isoTimestamp(message?.timestamp);
+        if (role === "user") {
+            for (const text of piTextContent(message?.content, state)) {
+                pushEvent(state, "user_message", { text }, messageTimestamp, nativeId, parentId);
+            }
+            continue;
+        }
+        if (role === "assistant") {
+            for (const rawPart of array(message?.content)) {
+                const part = object(rawPart);
+                const partType = string(part?.type);
+                if (partType === "thinking" || partType === "reasoning") {
+                    state.omittedReasoning += 1;
+                    continue;
+                }
+                if (partType === "text") {
+                    const text = string(part?.text);
+                    if (text)
+                        pushEvent(state, "model_output", { text }, messageTimestamp, nativeId, parentId);
+                    continue;
+                }
+                if (partType === "toolCall") {
+                    pushEvent(state, "tool_invocation", {
+                        call_id: string(part?.id) ?? "",
+                        tool_name: string(part?.name) ?? "unknown",
+                        input: part?.arguments ?? null,
+                    }, messageTimestamp, nativeId, parentId);
+                    continue;
+                }
+                state.omittedUnknown += 1;
+            }
+            const errorMessage = string(message?.errorMessage);
+            if (errorMessage) {
+                pushEvent(state, "system_event", {
+                    event: "model_error",
+                    message: errorMessage,
+                    provider: string(message?.provider) ?? "unknown",
+                    model: string(message?.model) ?? "unknown",
+                    stop_reason: string(message?.stopReason) ?? "error",
+                }, messageTimestamp, nativeId, parentId);
+            }
+            const usage = usageFromPi(message?.usage);
+            if (usage)
+                pushUsage(state, usage, messageTimestamp, nativeId);
+            continue;
+        }
+        if (role === "toolResult") {
+            const output = piTextContent(message?.content, state);
+            pushEvent(state, "tool_result", {
+                call_id: string(message?.toolCallId) ?? "",
+                output: output.join("\n"),
+                is_error: message?.isError === true,
+            }, messageTimestamp, nativeId, parentId);
+            const usage = usageFromPi(message?.usage);
+            if (usage)
+                pushUsage(state, usage, messageTimestamp, nativeId);
+            continue;
+        }
+        state.omittedUnknown += 1;
+    }
+    return finalize(state, sessionId, "pi", projectRoot);
+}
+function truncateUtf8(value, maxBytes) {
+    const bytes = Buffer.from(value, "utf8");
+    if (bytes.length <= maxBytes)
+        return value;
+    let result = bytes.subarray(0, Math.max(0, maxBytes)).toString("utf8");
+    while (result.endsWith("\uFFFD"))
+        result = result.slice(0, -1);
+    return result;
+}
+function truncateValue(value, maxStringBytes) {
+    if (typeof value === "string")
+        return truncateUtf8(value, maxStringBytes);
+    if (Array.isArray(value))
+        return value.map((item) => truncateValue(item, maxStringBytes));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, truncateValue(child, maxStringBytes)]));
+    }
+    return value;
+}
+export function fitTrajectoryToBytes(session, maxBytes) {
+    const originalBytes = Buffer.byteLength(JSON.stringify(session), "utf8");
+    if (originalBytes <= maxBytes)
+        return session;
+    const result = structuredClone(session);
+    result.capture.truncated = true;
+    result.capture.original_bytes = originalBytes;
+    result.capture.omitted_size_events = 0;
+    const maxStringBytes = Math.max(64, Math.min(1024, Math.floor(maxBytes / Math.max(8, result.events.length * 2))));
+    result.events = result.events.map((event) => {
+        const before = Buffer.byteLength(JSON.stringify(event.payload), "utf8");
+        const payload = truncateValue(event.payload, maxStringBytes);
+        const after = Buffer.byteLength(JSON.stringify(payload), "utf8");
+        return before === after ? event : { ...event, payload, truncation: { original_bytes: before, stored_bytes: after } };
+    });
+    while (result.events.length > 0 && Buffer.byteLength(JSON.stringify(result), "utf8") > maxBytes) {
+        result.events.pop();
+        result.capture.omitted_size_events = (result.capture.omitted_size_events ?? 0) + 1;
+    }
+    result.events = result.events.map((event, sequence) => ({ ...event, sequence }));
+    let storedBytes = 0;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        result.capture.stored_bytes = storedBytes;
+        const next = Buffer.byteLength(JSON.stringify(result), "utf8");
+        if (next === storedBytes)
+            break;
+        storedBytes = next;
+    }
+    result.capture.stored_bytes = Buffer.byteLength(JSON.stringify(result), "utf8");
+    if (Buffer.byteLength(JSON.stringify(result), "utf8") > maxBytes) {
+        throw new Error(`Trajectory metadata exceeds the ${maxBytes}-byte session limit.`);
+    }
+    return trajectorySessionSchema.parse(result);
+}