codeep 1.3.41 → 2.0.0

package/dist/utils/agent.js

@@ -165,10 +165,66 @@ export async function runAgent(prompt, projectContext, options = {}) {
     const protocol = config.get('protocol');
     const providerId = config.get('provider');
     const useNativeTools = supportsNativeTools(providerId, protocol);
+    // Fetch the MCP tool catalog once per agent run. The session id keys into
+    // mcpRegistry; if no MCP servers are registered (or mcpSessionId is unset,
+    // e.g. TUI mode) we get back an empty array and the agent behaves as
+    // before. We do this before building the system prompt so the fallback
+    // text path can include MCP tools in its catalog too.
+    //
+    // We also append per-server "virtual" tools that wrap resource_list /
+    // resource_read / prompt_list / prompt_get so the agent can discover and
+    // pull MCP resources & prompts without the user having to type `/mcp
+    // read <uri>` manually. Servers that don't expose resources or prompts
+    // get no virtual tools — the wrappers are only emitted where useful.
+    let mcpToolDefs = [];
+    if (opts.mcpSessionId) {
+        try {
+            const { getSessionTools, getSessionVirtualTools } = await import('./mcpRegistry.js');
+            const [registered, virtuals] = await Promise.all([
+                getSessionTools(opts.mcpSessionId),
+                getSessionVirtualTools(opts.mcpSessionId),
+            ]);
+            mcpToolDefs = [...registered, ...virtuals].map(t => ({
+                name: t.agentName,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            }));
+        }
+        catch {
+            // Don't let a registry blip kill the whole agent run.
+        }
+    }
+    // Skill bundles — structured `.codeep/skills/<name>/SKILL.md` directories
+    // the agent can discover and invoke via the `invoke_skill` tool. We just
+    // add the tool def here; the catalog block is appended to systemPrompt
+    // below alongside project rules / progress / etc. so we don't clobber
+    // those.
+    let skillCatalogBlock = '';
+    try {
+        const { loadSkillBundles, formatBundlesForSysprompt } = await import('./skillBundles.js');
+        const bundles = loadSkillBundles(projectContext.root);
+        if (bundles.length > 0) {
+            mcpToolDefs.push({
+                name: 'invoke_skill',
+                description: 'Invoke a Codeep skill bundle (curated workflow). Returns the SKILL.md body — follow its instructions step by step. Use when the user\'s request matches a skill\'s purpose.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', description: 'Skill name from the catalog (e.g. "deploy").' },
+                    },
+                    required: ['name'],
+                },
+            });
+            skillCatalogBlock = formatBundlesForSysprompt(bundles);
+        }
+    }
+    catch {
+        // Skill loading failure shouldn't fail the whole agent run.
+    }
     // Build system prompt - use fallback format if native tools not supported
     let systemPrompt = useNativeTools
         ? getAgentSystemPrompt(projectContext)
-        : getFallbackSystemPrompt(projectContext);
+        : getFallbackSystemPrompt(projectContext, mcpToolDefs);
     // Inject project rules (from .codeep/rules.md or CODEEP.md)
     const projectRules = loadProjectRules(projectContext.root);
     if (projectRules) {
@@ -191,6 +247,12 @@ export async function runAgent(prompt, projectContext, options = {}) {
     if (chatHistoryStr) {
         systemPrompt += chatHistoryStr;
     }
+    // Skill bundles catalog goes last — closest to the user prompt so the
+    // model is most likely to remember the available skills when matching
+    // intent. Empty string when there are none.
+    if (skillCatalogBlock) {
+        systemPrompt += '\n\n' + skillCatalogBlock;
+    }
     // Initial user message with optional task plan
     let initialPrompt = prompt;
     if (taskPlan) {
@@ -282,13 +344,35 @@ export async function runAgent(prompt, projectContext, options = {}) {
             // Calculate dynamic timeout based on task complexity
             const dynamicTimeout = calculateDynamicTimeout(iteration, baseTimeout);
             debug(`Using timeout: ${dynamicTimeout}ms (base: ${baseTimeout}ms)`);
+            // Refresh MCP tool list if a server flagged its catalog as changed
+            // (e.g. via `tools/list_changed` notification, or after an
+            // auto-restart). This keeps the agent in sync mid-run instead of
+            // requiring a session restart to see new tools.
+            if (opts.mcpSessionId) {
+                try {
+                    const { consumeSessionCatalogChanges, getSessionTools } = await import('./mcpRegistry.js');
+                    const dirty = consumeSessionCatalogChanges(opts.mcpSessionId);
+                    if (dirty.has('tools')) {
+                        const refreshed = await getSessionTools(opts.mcpSessionId);
+                        mcpToolDefs = refreshed.map(t => ({
+                            name: t.agentName,
+                            description: t.description,
+                            inputSchema: t.inputSchema,
+                        }));
+                        debug(`MCP tool catalog refreshed mid-run: ${mcpToolDefs.length} tool(s)`);
+                    }
+                }
+                catch {
+                    // Don't let a refresh hiccup break the iteration.
+                }
+            }
             // Get AI response with retry logic for timeouts
             let chatResponse = null;
             let retryCount = 0;
             while (true) {
                 try {
-                    chatResponse = await agentChat(messages, systemPrompt, opts.onChunk, opts.abortSignal, dynamicTimeout * (1 + retryCount * 0.5) // Increase timeout on retry
-                    );
+                    chatResponse = await agentChat(messages, systemPrompt, opts.onChunk, opts.abortSignal, dynamicTimeout * (1 + retryCount * 0.5), // Increase timeout on retry
+                    mcpToolDefs);
                     consecutiveTimeouts = 0; // Reset consecutive count on success
                     consecutiveRateLimits = 0;
                     break;
@@ -559,12 +643,12 @@ export async function runAgent(prompt, projectContext, options = {}) {
                         catch (err) {
                             debug('onExecuteCommand callback threw, falling back to local execution:', err);
                             // Fallback to local execution if callback throws
-                            toolResult = await executeTool(toolCall, cwd);
+                            toolResult = await executeTool(toolCall, cwd, opts.fs, opts.mcpSessionId);
                         }
                     }
                 }
                 else {
-                    toolResult = await executeTool(toolCall, projectContext.root || process.cwd());
+                    toolResult = await executeTool(toolCall, projectContext.root || process.cwd(), opts.fs, opts.mcpSessionId);
                 }
                 opts.onToolResult?.(toolResult, toolCall);
                 // Log action
@@ -737,7 +821,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
                     }
                     // Get AI response to fix errors
                     try {
-                        const fixResponse = await agentChat(messages, systemPrompt, opts.onChunk, opts.abortSignal);
+                        const fixResponse = await agentChat(messages, systemPrompt, opts.onChunk, opts.abortSignal, undefined, mcpToolDefs);
                         const { content: fixContent, toolCalls: fixToolCalls } = fixResponse;
                         if (fixToolCalls.length === 0) {
                             // Agent gave up or thinks it's fixed
@@ -749,7 +833,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
                         const fixResults = [];
                         for (const toolCall of fixToolCalls) {
                             opts.onToolCall?.(toolCall);
-                            const toolResult = await executeTool(toolCall, projectContext.root || process.cwd());
+                            const toolResult = await executeTool(toolCall, projectContext.root || process.cwd(), opts.fs, opts.mcpSessionId);
                             opts.onToolResult?.(toolResult, toolCall);
                             const actionLog = createActionLog(toolCall, toolResult);
                             actions.push(actionLog);

package/dist/utils/agentChat.d.ts

@@ -13,6 +13,7 @@
  */
 import { ProjectContext } from './project';
 import { Message } from '../config/index';
+import { AdditionalToolDef } from './tools';
 import type { AgentChatResponse } from './agentStream';
 export type { AgentChatResponse };
 /**
@@ -52,12 +53,19 @@ export declare function formatChatHistoryForAgent(history?: Array<{
     content: string;
 }>, maxChars?: number): string;
 export declare function getAgentSystemPrompt(projectContext: ProjectContext): string;
-export declare function getFallbackSystemPrompt(projectContext: ProjectContext): string;
+export declare function getFallbackSystemPrompt(projectContext: ProjectContext, additionalTools?: AdditionalToolDef[]): string;
 /**
  * Make a chat API call for agent mode with native tool support.
  * Falls back to agentChatFallback() if provider doesn't support tools.
  */
-export declare function agentChat(messages: Message[], systemPrompt: string, onChunk?: (chunk: string) => void, abortSignal?: AbortSignal, dynamicTimeout?: number): Promise<AgentChatResponse>;
+export declare function agentChat(messages: Message[], systemPrompt: string, onChunk?: (chunk: string) => void, abortSignal?: AbortSignal, dynamicTimeout?: number, 
+/**
+ * Extra tool definitions appended to the catalog (currently used to
+ * surface MCP-registered tools as first-class entries the model can
+ * invoke). Optional — built-in tools work the same whether this is
+ * omitted or an empty array.
+ */
+additionalTools?: AdditionalToolDef[]): Promise<AgentChatResponse>;
 /**
  * Fallback chat without native tools (text-based tool format)
  */

package/dist/utils/agentChat.js

@@ -20,6 +20,7 @@ import { getProviderBaseUrl, getProviderAuthHeader, supportsNativeTools, getEffe
 import { recordTokenUsage, extractOpenAIUsage, extractAnthropicUsage } from './tokenTracker.js';
 import { parseOpenAIToolCalls, parseAnthropicToolCalls, parseToolCalls } from './toolParsing.js';
 import { formatToolDefinitions, getOpenAITools, getAnthropicTools } from './tools.js';
+import { readOpenRouterPreferences } from './openrouterPrefs.js';
 import { handleStream, handleOpenAIAgentStream, handleAnthropicAgentStream } from './agentStream.js';
 import { logger } from './logger.js';
 const debug = (...args) => {
@@ -212,14 +213,21 @@ ${projectContext.structure ? `\n## Project Structure\n${projectContext.structure
         return intelligence ? `\n\n${generateContextFromIntelligence(intelligence)}` : '';
     })()}`;
 }
-export function getFallbackSystemPrompt(projectContext) {
-    return getAgentSystemPrompt(projectContext) + '\n\n' + formatToolDefinitions();
+export function getFallbackSystemPrompt(projectContext, additionalTools) {
+    return getAgentSystemPrompt(projectContext) + '\n\n' + formatToolDefinitions(additionalTools);
 }
 /**
  * Make a chat API call for agent mode with native tool support.
  * Falls back to agentChatFallback() if provider doesn't support tools.
  */
-export async function agentChat(messages, systemPrompt, onChunk, abortSignal, dynamicTimeout) {
+export async function agentChat(messages, systemPrompt, onChunk, abortSignal, dynamicTimeout, 
+/**
+ * Extra tool definitions appended to the catalog (currently used to
+ * surface MCP-registered tools as first-class entries the model can
+ * invoke). Optional — built-in tools work the same whether this is
+ * omitted or an empty array.
+ */
+additionalTools) {
     const protocol = config.get('protocol');
     const model = config.get('model');
     const providerId = config.get('provider');
@@ -255,6 +263,14 @@ export async function agentChat(messages, systemPrompt, onChunk, abortSignal, dy
     }
     if (protocol === 'anthropic')
         headers['anthropic-version'] = '2023-06-01';
+    // OpenRouter branding — surfaces "Codeep" in the OpenRouter dashboard
+    // attribution so users (and OpenRouter itself, for any partnership
+    // tracking) see which app generated the traffic. Spec is informal; both
+    // headers are documented at openrouter.ai/docs#headers.
+    if (providerId === 'openrouter') {
+        headers['HTTP-Referer'] = 'https://codeep.dev';
+        headers['X-Title'] = 'Codeep';
+    }
     try {
         let endpoint;
         let body;
@@ -264,18 +280,30 @@ export async function agentChat(messages, systemPrompt, onChunk, abortSignal, dy
             const maxTok = getEffectiveMaxTokens(providerId, Math.max(config.get('maxTokens'), 16384));
             const tokParam = usesMaxCompletionTokens(providerId) ? { max_completion_tokens: maxTok } : { max_tokens: maxTok };
             endpoint = `${baseUrl}/chat/completions`;
+            // OpenRouter-specific extras: request `usage` block in the response
+            // body so we get per-call cost (skips our local pricing lookup), and
+            // optionally a provider-routing preferences object the user set via
+            // `/openrouter prefer …`.
+            const openRouterExtras = {};
+            if (providerId === 'openrouter') {
+                openRouterExtras.usage = { include: true };
+                const prefs = readOpenRouterPreferences();
+                if (prefs)
+                    openRouterExtras.provider = prefs;
+            }
             body = {
                 model, messages: [{ role: 'system', content: systemPrompt }, ...messages],
-                tools: getOpenAITools(), tool_choice: 'auto', stream: useStreaming,
+                tools: getOpenAITools(additionalTools), tool_choice: 'auto', stream: useStreaming,
                 ...tempParam, ...tokParam,
                 ...(useStreaming && providerId === 'openai' ? { stream_options: { include_usage: true } } : {}),
+                ...openRouterExtras,
             };
         }
         else {
             endpoint = `${baseUrl}/v1/messages`;
             body = {
                 model, system: systemPrompt, messages,
-                tools: getAnthropicTools(), stream: useStreaming,
+                tools: getAnthropicTools(additionalTools), stream: useStreaming,
                 ...tempParam, max_tokens: getEffectiveMaxTokens(providerId, Math.max(config.get('maxTokens'), 16384)),
             };
         }
@@ -298,8 +326,15 @@ export async function agentChat(messages, systemPrompt, onChunk, abortSignal, dy
         const data = await response.json();
         const usageExtractor = protocol === 'openai' ? extractOpenAIUsage : extractAnthropicUsage;
         const usage = usageExtractor(data);
-        if (usage)
-            recordTokenUsage(usage, model, providerId);
+        if (usage) {
+            // OpenRouter returns the authoritative per-call cost in
+            // `usage.cost` (USD). Use it instead of our local pricing table
+            // since the catalog has 100+ models we don't track ourselves.
+            const reportedCost = providerId === 'openrouter' && typeof data?.usage?.cost === 'number'
+                ? data.usage.cost
+                : undefined;
+            recordTokenUsage(usage, model, providerId, reportedCost);
+        }
         if (protocol === 'openai') {
             const message = data.choices?.[0]?.message;
             const content = message?.content || '';
@@ -426,8 +461,12 @@ export async function agentChatFallback(messages, systemPrompt, onChunk, abortSi
             const data = await response.json();
             const fallbackUsageExtractor = protocol === 'openai' ? extractOpenAIUsage : extractAnthropicUsage;
             const fallbackUsage = fallbackUsageExtractor(data);
-            if (fallbackUsage)
-                recordTokenUsage(fallbackUsage, model, providerId);
+            if (fallbackUsage) {
+                const reportedCost = providerId === 'openrouter' && typeof data?.usage?.cost === 'number'
+                    ? data.usage.cost
+                    : undefined;
+                recordTokenUsage(fallbackUsage, model, providerId, reportedCost);
+            }
             content = protocol === 'openai' ? (data.choices?.[0]?.message?.content || '') : (data.content?.[0]?.text || '');
         }
         const toolCalls = parseToolCalls(content);

package/dist/utils/agentStream.js

@@ -120,8 +120,12 @@ export async function handleOpenAIAgentStream(body, onChunk, model, providerId)
     }
     if (usageData) {
         const usage = extractOpenAIUsage(usageData);
-        if (usage)
-            recordTokenUsage(usage, model, providerId);
+        if (usage) {
+            const reportedCost = providerId === 'openrouter' && typeof usageData?.usage?.cost === 'number'
+                ? usageData.usage.cost
+                : undefined;
+            recordTokenUsage(usage, model, providerId, reportedCost);
+        }
     }
     const rawToolCalls = Array.from(toolCallMap.values()).map(tc => ({
         id: tc.id,

package/dist/utils/checkpoints.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Session checkpoints — `/checkpoint` and `/rewind`.
+ *
+ * A checkpoint is a snapshot of the agent conversation at a point in time:
+ * session history, provider/model state, and the list of files the agent has
+ * touched in this session. It does NOT snapshot file content — that's git's
+ * job, and trying to do it ourselves means either a 100KB-per-file ceiling
+ * with surprise truncation, or a real-time disk hog. We surface a hint at
+ * rewind time telling the user how to restore files via git.
+ *
+ * Use cases this is for:
+ *   - User suspects the agent is going off the rails after N steps and
+ *     wants to roll the conversation back to before that turn.
+ *   - User is about to start a risky multi-step refactor and wants a
+ *     named bookmark to return to if it gets messy.
+ *
+ * Use cases this is NOT for:
+ *   - Replacing git. If you only need file rollback, `git restore` /
+ *     `git stash` is faster and reliable.
+ *   - Cross-session persistence beyond the workspace's `.codeep/checkpoints/`
+ *     folder — checkpoints are per-project, not global.
+ *
+ * On-disk shape (`.codeep/checkpoints/<id>.json`):
+ * {
+ *   "id": "ck-2026-05-18-abc123",
+ *   "name": "before big refactor",
+ *   "createdAt": "...",
+ *   "sessionId": "session-2026-05-18-...",
+ *   "provider": "z.ai",
+ *   "model": "glm-5.1",
+ *   "messages": [ ... ],
+ *   "filesTouched": ["src/a.ts", "src/b.ts"],
+ *   "gitHead": "abcdef0"        // optional, recorded only if cwd is a git repo
+ * }
+ */
+import type { Message } from '../config/index.js';
+export interface Checkpoint {
+    id: string;
+    name?: string;
+    createdAt: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    messages: Message[];
+    filesTouched: string[];
+    gitHead?: string;
+}
+/** Lightweight metadata for `/checkpoints` list — avoids loading full message arrays. */
+export interface CheckpointMeta {
+    id: string;
+    name?: string;
+    createdAt: string;
+    sessionId: string;
+    messageCount: number;
+    filesTouchedCount: number;
+    gitHead?: string;
+}
+/**
+ * Create a new checkpoint snapshot of the current session state.
+ * Returns the persisted checkpoint object.
+ */
+export declare function createCheckpoint(opts: {
+    workspaceRoot: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    messages: Message[];
+    filesTouched: string[];
+    name?: string;
+}): Checkpoint;
+/**
+ * Load a single checkpoint by id. Returns null if not found or unreadable.
+ */
+export declare function loadCheckpoint(workspaceRoot: string, id: string): Checkpoint | null;
+/**
+ * List checkpoints in the workspace, newest first. Returns metadata only —
+ * the full `messages` array is not loaded so this is cheap for `/checkpoints`.
+ */
+export declare function listCheckpoints(workspaceRoot: string): CheckpointMeta[];
+/**
+ * Delete a checkpoint by id. Returns true if a file was removed.
+ */
+export declare function deleteCheckpoint(workspaceRoot: string, id: string): boolean;
+/**
+ * Format a checkpoint list as a Markdown block for `/checkpoints` output.
+ */
+export declare function formatCheckpointList(metas: CheckpointMeta[]): string;
+/**
+ * Build the user-facing hint shown after a successful /rewind. Tells the
+ * user how to bring their files back to checkpoint state — checkpoints
+ * don't snapshot file content, so this is the only restore path.
+ */
+export declare function buildRewindGitHint(cp: Checkpoint): string;

package/dist/utils/checkpoints.js

@@ -0,0 +1,205 @@
+/**
+ * Session checkpoints — `/checkpoint` and `/rewind`.
+ *
+ * A checkpoint is a snapshot of the agent conversation at a point in time:
+ * session history, provider/model state, and the list of files the agent has
+ * touched in this session. It does NOT snapshot file content — that's git's
+ * job, and trying to do it ourselves means either a 100KB-per-file ceiling
+ * with surprise truncation, or a real-time disk hog. We surface a hint at
+ * rewind time telling the user how to restore files via git.
+ *
+ * Use cases this is for:
+ *   - User suspects the agent is going off the rails after N steps and
+ *     wants to roll the conversation back to before that turn.
+ *   - User is about to start a risky multi-step refactor and wants a
+ *     named bookmark to return to if it gets messy.
+ *
+ * Use cases this is NOT for:
+ *   - Replacing git. If you only need file rollback, `git restore` /
+ *     `git stash` is faster and reliable.
+ *   - Cross-session persistence beyond the workspace's `.codeep/checkpoints/`
+ *     folder — checkpoints are per-project, not global.
+ *
+ * On-disk shape (`.codeep/checkpoints/<id>.json`):
+ * {
+ *   "id": "ck-2026-05-18-abc123",
+ *   "name": "before big refactor",
+ *   "createdAt": "...",
+ *   "sessionId": "session-2026-05-18-...",
+ *   "provider": "z.ai",
+ *   "model": "glm-5.1",
+ *   "messages": [ ... ],
+ *   "filesTouched": ["src/a.ts", "src/b.ts"],
+ *   "gitHead": "abcdef0"        // optional, recorded only if cwd is a git repo
+ * }
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, statSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { execSync } from 'child_process';
+function getCheckpointsDir(workspaceRoot) {
+    const dir = join(workspaceRoot, '.codeep', 'checkpoints');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function readGitHead(workspaceRoot) {
+    try {
+        // Short SHA is enough for human display; full SHA available via git if needed.
+        const out = execSync('git rev-parse --short HEAD', {
+            cwd: workspaceRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2000,
+        }).trim();
+        return out || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Generate a unique, human-recognizable checkpoint id.
+ * Format: `ck-YYYY-MM-DD-<8-char-uuid>`
+ */
+function generateCheckpointId() {
+    const date = new Date().toISOString().slice(0, 10);
+    return `ck-${date}-${randomUUID().slice(0, 8)}`;
+}
+/**
+ * Create a new checkpoint snapshot of the current session state.
+ * Returns the persisted checkpoint object.
+ */
+export function createCheckpoint(opts) {
+    const checkpoint = {
+        id: generateCheckpointId(),
+        name: opts.name,
+        createdAt: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        provider: opts.provider,
+        model: opts.model,
+        messages: opts.messages,
+        filesTouched: opts.filesTouched,
+        gitHead: readGitHead(opts.workspaceRoot),
+    };
+    const dir = getCheckpointsDir(opts.workspaceRoot);
+    writeFileSync(join(dir, `${checkpoint.id}.json`), JSON.stringify(checkpoint, null, 2));
+    return checkpoint;
+}
+/**
+ * Load a single checkpoint by id. Returns null if not found or unreadable.
+ */
+export function loadCheckpoint(workspaceRoot, id) {
+    // Defensive: reject ids that look like path traversal attempts. Real ids are
+    // `ck-YYYY-MM-DD-<hex>` so the regex is tight enough to catch typos too.
+    if (!/^ck-\d{4}-\d{2}-\d{2}-[a-f0-9]{8}$/.test(id))
+        return null;
+    const file = join(getCheckpointsDir(workspaceRoot), `${id}.json`);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List checkpoints in the workspace, newest first. Returns metadata only —
+ * the full `messages` array is not loaded so this is cheap for `/checkpoints`.
+ */
+export function listCheckpoints(workspaceRoot) {
+    const dir = getCheckpointsDir(workspaceRoot);
+    let files;
+    try {
+        files = readdirSync(dir).filter(f => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const metas = [];
+    for (const file of files) {
+        try {
+            const full = join(dir, file);
+            const stat = statSync(full);
+            const cp = JSON.parse(readFileSync(full, 'utf-8'));
+            metas.push({
+                id: cp.id,
+                name: cp.name,
+                createdAt: cp.createdAt || stat.mtime.toISOString(),
+                sessionId: cp.sessionId,
+                messageCount: cp.messages?.length ?? 0,
+                filesTouchedCount: cp.filesTouched?.length ?? 0,
+                gitHead: cp.gitHead,
+            });
+        }
+        catch {
+            // Skip corrupt entries — don't let one bad checkpoint block the list.
+        }
+    }
+    // Newest first by createdAt.
+    metas.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+    return metas;
+}
+/**
+ * Delete a checkpoint by id. Returns true if a file was removed.
+ */
+export function deleteCheckpoint(workspaceRoot, id) {
+    if (!/^ck-\d{4}-\d{2}-\d{2}-[a-f0-9]{8}$/.test(id))
+        return false;
+    const file = join(getCheckpointsDir(workspaceRoot), `${id}.json`);
+    if (!existsSync(file))
+        return false;
+    try {
+        unlinkSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format a checkpoint list as a Markdown block for `/checkpoints` output.
+ */
+export function formatCheckpointList(metas) {
+    if (metas.length === 0) {
+        return [
+            '_No checkpoints yet._',
+            '',
+            'Create one with `/checkpoint [name]` before risky refactors so you can `/rewind` if things go sideways.',
+        ].join('\n');
+    }
+    const lines = ['## Checkpoints', ''];
+    for (const m of metas) {
+        const label = m.name ? `**${m.name}** (\`${m.id}\`)` : `\`${m.id}\``;
+        const gitFragment = m.gitHead ? ` · git \`${m.gitHead}\`` : '';
+        const date = m.createdAt.slice(0, 19).replace('T', ' ');
+        lines.push(`- ${label}`, `  ${date} · ${m.messageCount} message${m.messageCount === 1 ? '' : 's'} · ${m.filesTouchedCount} file${m.filesTouchedCount === 1 ? '' : 's'} touched${gitFragment}`);
+    }
+    lines.push('', 'Use `/rewind <id>` to restore a checkpoint, or `/checkpoint delete <id>` to drop one.');
+    return lines.join('\n');
+}
+/**
+ * Build the user-facing hint shown after a successful /rewind. Tells the
+ * user how to bring their files back to checkpoint state — checkpoints
+ * don't snapshot file content, so this is the only restore path.
+ */
+export function buildRewindGitHint(cp) {
+    if (cp.gitHead) {
+        return [
+            `**Files were NOT restored** — only the conversation. To bring files back to the state at checkpoint time:`,
+            '',
+            '```bash',
+            `git stash  # save current uncommitted changes if you want to keep them`,
+            `git checkout ${cp.gitHead} -- ${cp.filesTouched.length > 0 ? cp.filesTouched.map(f => `'${f}'`).join(' ') : '.'}`,
+            '```',
+        ].join('\n');
+    }
+    return [
+        '**Files were NOT restored** — only the conversation.',
+        cp.filesTouched.length > 0
+            ? `Files the agent touched between checkpoint and now: ${cp.filesTouched.map(f => `\`${f}\``).join(', ')}.`
+            : '',
+        'Use `git` (or your editor\'s undo) to revert any file changes you don\'t want.',
+    ].filter(Boolean).join('\n');
+}

package/dist/utils/context.d.ts

@@ -27,6 +27,30 @@ export declare function clearContext(projectPath: string): boolean;
  * Get all saved contexts
  */
 export declare function getAllContexts(): ConversationContext[];
+/**
+ * AI-powered compaction of a conversation history.
+ *
+ * Used by the `/compact` slash command. Sends the older portion of the
+ * conversation to the active provider with a summarization prompt, then
+ * replaces those messages with a single system message containing the
+ * summary. Keeps the last `keepRecent` messages verbatim so the
+ * conversation can continue without losing the most recent context.
+ *
+ * Returns the same `history` (untouched) if there isn't enough to
+ * meaningfully compact.
+ */
+export declare function compactHistory(history: Message[], options?: {
+    keepRecent?: number;
+    projectContext?: import('./project').ProjectContext | null;
+    /** Cap on how long the summarization API call can take, in ms. Defaults to 60s. */
+    timeoutMs?: number;
+    /** External abort signal (e.g. user pressed /stop). Combined with the timeout. */
+    abortSignal?: AbortSignal;
+}): Promise<{
+    compacted: Message[];
+    replaced: number;
+    summary: string;
+}>;
 /**
  * Summarize messages for context persistence
  * Keeps recent messages and summarizes older ones