ctxcarry 0.3.0

package/dist/cli.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import { captureSnapshot, runAgent } from "./capture.js";
+import { compileAgent, handoffTokenEstimate, rawEventText, renderCurrentHandoff } from "./compile.js";
+import { compactState } from "./distill.js";
+import { learnFromSessions } from "./learn.js";
+import { serveMcp } from "./mcp-server.js";
+import { estimateSavings, estimateTokens } from "./tokens.js";
+import { appendEvent, ctxcarryDirName, ensureInitialized, initStore, readState } from "./store.js";
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    try {
+        switch (args.command) {
+            case undefined:
+            case "--help":
+            case "-h":
+            case "help":
+                printHelp();
+                return;
+            case "init":
+                initStore();
+                console.log(`Initialized ${ctxcarryDirName()}/ and ctxcarry.config.json`);
+                return;
+            case "capture":
+                ensureInitialized();
+                printSnapshot(captureSnapshot(stringFlag(args, "agent")));
+                return;
+            case "note":
+                ensureInitialized();
+                addNote(args);
+                return;
+            case "run":
+                ensureInitialized();
+                {
+                    const result = await runAgent(requiredPositional(args, 0, "agent"));
+                    console.log(`Recorded session ${result.sessionId}.`);
+                    console.log(`Session files: ${result.sessionDir}`);
+                    process.exitCode = result.exitCode;
+                }
+                return;
+            case "compact":
+                ensureInitialized();
+                compactState();
+                console.log("Compacted .ctxcarry/state.json and .ctxcarry/state.md");
+                return;
+            case "compile":
+                ensureInitialized();
+                compileCommand(args);
+                return;
+            case "switch":
+                ensureInitialized();
+                switchCommand(args);
+                return;
+            case "status":
+                ensureInitialized();
+                statusCommand();
+                return;
+            case "tokens":
+                ensureInitialized();
+                tokensCommand(args);
+                return;
+            case "learn":
+                ensureInitialized();
+                learnCommand(args);
+                return;
+            case "mcp":
+                ensureInitialized();
+                await mcpCommand(args);
+                return;
+            default:
+                throw new Error(`Unknown command "${args.command}". Run \`ctxcarry --help\`.`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`ctxcarry: ${message}`);
+        process.exitCode = 1;
+    }
+}
+function addNote(args) {
+    const type = stringFlag(args, "type");
+    const text = stringFlag(args, "text");
+    const agent = stringFlag(args, "agent");
+    if (!type || !["decision", "failure", "todo", "constraint", "task", "next", "resolved"].includes(type)) {
+        throw new Error("`ctxcarry note` requires --type decision|failure|todo|constraint|task|next|resolved.");
+    }
+    if (!text) {
+        throw new Error("`ctxcarry note` requires --text.");
+    }
+    appendEvent({
+        type: "note",
+        noteType: type,
+        content: text,
+        agent
+    });
+    console.log(`Recorded ${type} note.`);
+}
+function compileCommand(args) {
+    const agent = stringFlag(args, "agent") ?? requiredPositional(args, 0, "agent");
+    const output = compileAgent(agent, numberFlag(args, "budget"));
+    console.log(`Compiled ${agent} ctxcarry to ${output}`);
+}
+function switchCommand(args) {
+    const agent = requiredPositional(args, 0, "agent");
+    compactState();
+    const output = compileAgent(agent, numberFlag(args, "budget"));
+    console.log(`Prepared ${agent} ctxcarry in ${output}.`);
+    if (agent === "codex") {
+        console.log("Next: run `codex` in this repo.");
+    }
+}
+function statusCommand() {
+    const state = readState();
+    const failures = state.working.failures.length;
+    const estimate = handoffTokenEstimate("codex");
+    console.log(`Current task: ${state.working.currentTask}`);
+    console.log(`Status: ${state.working.status}`);
+    console.log(`Current branch: ${state.working.currentBranch ?? "Unknown"}`);
+    console.log(`Files touched: ${state.working.touchedFiles.length}`);
+    console.log(`Open failures: ${failures}`);
+    console.log(`Decisions: ${state.episodic.decisions.length}`);
+    console.log(`Token estimate for Codex Handoff: ${estimate}`);
+}
+function tokensCommand(args) {
+    const agent = stringFlag(args, "agent") ?? "codex";
+    const packed = renderCurrentHandoff(agent, numberFlag(args, "budget"));
+    const raw = rawEventText();
+    console.log(`Agent: ${agent}`);
+    console.log(`Packed estimate: ${estimateTokens(packed)} tokens`);
+    console.log(`Raw event estimate: ${estimateTokens(raw)} tokens`);
+    console.log(`Estimated savings: ${estimateSavings(raw, packed)}%`);
+}
+function printSnapshot(snapshot) {
+    console.log(snapshot.isRepo ? "Captured git snapshot." : "Captured snapshot outside a git repository.");
+    console.log(`Branch: ${snapshot.branch ?? "Unknown"}`);
+    console.log(`Changed files: ${snapshot.changedFiles.length}`);
+}
+function printHelp() {
+    console.log(`ctxcarry local agent ctxcarry CLI
+
+Usage:
+  ctxcarry init
+  ctxcarry capture [--agent claude]
+  ctxcarry note --type decision|failure|todo|constraint|task|next|resolved --text "..."
+  ctxcarry run <agent>
+  ctxcarry compact
+  ctxcarry compile --agent codex|claude [--budget 4000]
+  ctxcarry switch <agent> [--budget 4000]
+  ctxcarry status
+  ctxcarry tokens [--agent codex] [--budget 4000]
+  ctxcarry learn [--apply]
+  ctxcarry mcp serve
+`);
+}
+function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    const positional = [];
+    const flags = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2);
+            const next = rest[index + 1];
+            if (next && !next.startsWith("--")) {
+                flags[name] = next;
+                index += 1;
+            }
+            else {
+                flags[name] = true;
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { command, positional, flags };
+}
+function stringFlag(args, name) {
+    const value = args.flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+function requiredPositional(args, index, name) {
+    const value = args.positional[index];
+    if (!value) {
+        throw new Error(`Missing required ${name}.`);
+    }
+    return value;
+}
+function numberFlag(args, name) {
+    const value = stringFlag(args, name);
+    if (!value) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`--${name} must be a positive number.`);
+    }
+    return parsed;
+}
+function learnCommand(args) {
+    const markdown = learnFromSessions(Boolean(args.flags.apply));
+    console.log(markdown);
+    if (args.flags.apply) {
+        console.log("\nApplied learned guidance to .ctxcarry/learned.md, AGENTS.md, and CLAUDE.md");
+    }
+}
+async function mcpCommand(args) {
+    const subcommand = requiredPositional(args, 0, "mcp subcommand");
+    if (subcommand !== "serve") {
+        throw new Error("Only `ctxcarry mcp serve` is supported.");
+    }
+    await serveMcp();
+}
+await main();

package/dist/compile.js

@@ -0,0 +1,152 @@
+import fs from "node:fs";
+import { ctxcarryPath } from "./paths.js";
+import { estimateTokens } from "./tokens.js";
+import { redactText } from "./redact.js";
+import { readConfig, readState, writeHandoff, writeManagedFile } from "./store.js";
+export function compileAgent(agent, budgetTokens) {
+    const config = readConfig();
+    const state = readState();
+    const agentConfig = config.agents[agent];
+    if (!agentConfig?.enabled) {
+        throw new Error(`Agent "${agent}" is not enabled in ctxcarry.config.json.`);
+    }
+    const markdown = agent === "claude" ? renderClaude(state, budgetTokens) : renderCodex(state, budgetTokens);
+    writeHandoff(agent, markdown);
+    writeManagedFile(agentConfig.output, markdown);
+    return agentConfig.output;
+}
+export function renderCodex(state, budgetTokens) {
+    return packToBudget(() => {
+        const body = renderHandoff("Codex Handoff", state);
+        return [
+            "# ctxcarry Project Context",
+            "",
+            "Use this compact project state before continuing work. Treat `.ctxcarry/` as the source of truth for generated context.",
+            "",
+            body
+        ].join("\n");
+    }, state, "codex", budgetTokens);
+}
+export function renderClaude(state, budgetTokens) {
+    return packToBudget(() => {
+        const body = renderHandoff("Claude Code Handoff", state);
+        return [
+            "# ctxcarry Memory",
+            "",
+            "This file is generated from local ctxcarry project memory.",
+            "",
+            body
+        ].join("\n");
+    }, state, "claude", budgetTokens);
+}
+export function renderCurrentHandoff(agent = "codex", budgetTokens) {
+    const state = readState();
+    return agent === "claude" ? renderClaude(state, budgetTokens) : renderCodex(state, budgetTokens);
+}
+export function handoffTokenEstimate(agent = "codex") {
+    const ctxcarry = renderCurrentHandoff(agent);
+    return estimateTokens(ctxcarry);
+}
+export function rawEventText() {
+    const eventsPath = ctxcarryPath("events.jsonl");
+    return fs.existsSync(eventsPath) ? fs.readFileSync(eventsPath, "utf8") : "";
+}
+function renderHandoff(title, state) {
+    const sections = [
+        `## ${title}`,
+        "",
+        "### Current Task",
+        state.working.currentTask,
+        "",
+        "### Current Status",
+        state.working.status,
+        "",
+        "### Current Branch",
+        state.working.currentBranch ?? "Unknown",
+        "",
+        "### Recommended Next Step",
+        renderNextStep(state)
+    ];
+    appendSection(sections, "Files Touched", state.working.touchedFiles);
+    appendSection(sections, "Decisions Made", state.episodic.decisions.map((item) => item.content));
+    appendSection(sections, "Constraints", state.working.constraints.map((item) => item.content));
+    appendSection(sections, "Known Failures", state.working.failures.map((item) => item.content));
+    appendSection(sections, "Last Commands", state.working.lastCommands);
+    return redactText(sections.join("\n"));
+}
+function renderNextStep(state) {
+    const explicit = state.working.nextSteps.at(-1)?.content;
+    if (explicit) {
+        return explicit;
+    }
+    const failure = state.working.failures.at(-1)?.content;
+    if (failure) {
+        return `Investigate current failure: ${failure}`;
+    }
+    if (state.working.touchedFiles.length > 0) {
+        return "Review the touched files and run the relevant tests.";
+    }
+    return "Record the current task with `ctxcarry note --type task --text \"...\"`.";
+}
+function renderList(items) {
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function appendSection(sections, title, items) {
+    if (items.length === 0) {
+        return;
+    }
+    sections.push("", `### ${title}`, renderList(items));
+}
+function packToBudget(render, state, agent, budgetTokens) {
+    const full = redactText(render());
+    if (!budgetTokens || estimateTokens(full) <= budgetTokens) {
+        return full;
+    }
+    const compactState = {
+        ...state,
+        working: {
+            ...state.working,
+            touchedFiles: state.working.touchedFiles.slice(0, 20),
+            lastCommands: state.working.lastCommands.slice(-3),
+            constraints: state.working.constraints.slice(-10),
+            failures: state.working.failures.slice(-10),
+            todos: [],
+            nextSteps: state.working.nextSteps.slice(-3)
+        },
+        episodic: {
+            ...state.episodic,
+            sessions: state.episodic.sessions.slice(-2),
+            decisions: state.episodic.decisions.slice(-10),
+            attempts: [],
+            resolved: []
+        }
+    };
+    const compact = agent === "claude" ? renderClaude(compactState) : renderCodex(compactState);
+    if (estimateTokens(compact) <= budgetTokens) {
+        return compact;
+    }
+    const minimum = [
+        agent === "claude" ? "# ctxcarry Memory" : "# ctxcarry Project Context",
+        "",
+        `## ${agent === "claude" ? "Claude Code" : "Codex"} ctxcarry`,
+        "",
+        "### Current Task",
+        truncate(state.working.currentTask, 600),
+        "",
+        "### Current Status",
+        state.working.status,
+        "",
+        "### Recommended Next Step",
+        truncate(renderNextStep(state), 600)
+    ];
+    appendSection(minimum, "Constraints", state.working.constraints.slice(-5).map((item) => truncate(item.content, 240)));
+    appendSection(minimum, "Known Failures", state.working.failures.slice(-5).map((item) => truncate(item.content, 240)));
+    appendSection(minimum, "Files Touched", state.working.touchedFiles.slice(0, 10));
+    return redactText(minimum.join("\n"));
+}
+function truncate(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxChars - 3))}...`;
+}

package/dist/content-router.js

@@ -0,0 +1,93 @@
+export function routeContent(label, content) {
+    const kind = detectKind(label, content);
+    if (kind === "log" || kind === "command") {
+        return summarizeLog(content, kind);
+    }
+    if (kind === "diff") {
+        return summarizeDiff(content);
+    }
+    if (kind === "transcript" || kind === "summary") {
+        return summarizeTranscript(content, kind);
+    }
+    return {
+        kind,
+        summary: firstLines(content, 8),
+        signals: []
+    };
+}
+function detectKind(label, content) {
+    const lower = `${label}\n${content.slice(0, 2000)}`.toLowerCase();
+    if (lower.includes("diff --git") || lower.includes(" files changed") || lower.includes("insertions(+)")) {
+        return "diff";
+    }
+    if (/(\bfail\b|\berror\b|exception|stack trace|at .*:\d+:\d+)/i.test(content)) {
+        return label.includes("command") ? "command" : "log";
+    }
+    if (/^##\s+(current task|files changed|decisions|constraints|failures|commands run|next step)/im.test(content)) {
+        return "summary";
+    }
+    if (/\b(user|assistant|tool):/i.test(content)) {
+        return "transcript";
+    }
+    return "unknown";
+}
+function summarizeLog(content, kind) {
+    const lines = uniqueLines(content);
+    const error = lines.find((line) => /(?:error:|expected|received|exception|timeout|fatal)/i.test(line));
+    const failingTest = lines.find((line) => /\.(?:test|spec)\.[tj]sx?/i.test(line));
+    const appFrame = lines.find((line) => /\bat .*?(?:src|app|lib|components|tests)\//.test(line));
+    const command = lines.find((line) => /^(?:pnpm|npm|yarn|bun|cargo|pytest|go test|swift test)\b/.test(line));
+    const signals = [error, failingTest, appFrame, command].filter((line) => Boolean(line));
+    return {
+        kind,
+        summary: signals.length > 0 ? signals.join("; ") : firstLines(lines.join("\n"), 6),
+        signals
+    };
+}
+function summarizeDiff(content) {
+    const files = uniqueLines(content)
+        .map((line) => {
+        const git = line.match(/^diff --git a\/(.+?) b\//);
+        if (git)
+            return git[1];
+        const stat = line.match(/^(.+?)\s+\|\s+\d+/);
+        if (stat)
+            return stat[1].trim();
+        return "";
+    })
+        .filter(Boolean);
+    return {
+        kind: "diff",
+        summary: files.length > 0 ? `Changed files: ${files.slice(0, 25).join(", ")}` : firstLines(content, 8),
+        signals: files
+    };
+}
+function summarizeTranscript(content, kind) {
+    const lines = uniqueLines(content);
+    const signals = lines.filter((line) => /(?:decision|constraint|failure|next step|current task|do not|failed|fix|todo)/i.test(line)).slice(0, 20);
+    return {
+        kind,
+        summary: signals.length > 0 ? signals.join("\n") : firstLines(lines.join("\n"), 10),
+        signals
+    };
+}
+function firstLines(content, count) {
+    return content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(0, count)
+        .join("\n");
+}
+function uniqueLines(content) {
+    const seen = new Set();
+    const result = [];
+    for (const line of content.split("\n").map((item) => item.trim()).filter(Boolean)) {
+        const normalized = line.toLowerCase().replace(/\s+/g, " ");
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        result.push(line);
+    }
+    return result;
+}