codeep 1.3.42 → 2.0.1

package/dist/utils/hooks.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Project-local lifecycle hooks.
+ *
+ * User drops executable shell scripts in `.codeep/hooks/<event>.sh` and Codeep
+ * runs them at the relevant moment during a session. Generalises what the
+ * `agentAutoCommit` and `agentAutoVerify` config flags do — anything those
+ * can do, a `post_edit` hook can do too, without a code change in the CLI.
+ *
+ * Supported events:
+ *
+ *   `pre_tool_call`   — fires before every tool execution. NON-ZERO exit
+ *                       BLOCKS the tool call (the agent gets a clear error
+ *                       message). Use for policy enforcement: block writes
+ *                       to certain paths, refuse risky commands, etc.
+ *
+ *   `post_edit`       — fires after a successful write_file or edit_file.
+ *                       Exit code is ignored (auto-format / auto-lint:
+ *                       failure shouldn't block the agent). Receives the
+ *                       file path. Use for prettier/eslint/gofmt.
+ *
+ *   `on_error`        — fires when a tool call returns success=false.
+ *                       Exit code ignored. Use for centralised logging
+ *                       or alerting.
+ *
+ *   `pre_commit`      — fires before the /commit skill stages anything.
+ *                       NON-ZERO exit BLOCKS the commit. Use for test
+ *                       runs, lint gates, etc.
+ *
+ * Environment variables every hook receives:
+ *   CODEEP_HOOK_EVENT     - one of the event names above
+ *   CODEEP_WORKSPACE      - workspace root absolute path
+ *   CODEEP_SESSION_ID     - current Codeep session id
+ *
+ * Event-specific extras:
+ *   pre_tool_call / on_error:
+ *     CODEEP_HOOK_TOOL    - tool name (read_file, write_file, …)
+ *     CODEEP_HOOK_PARAMS  - JSON-encoded tool parameters
+ *   post_edit:
+ *     CODEEP_HOOK_TOOL    - 'write_file' | 'edit_file'
+ *     CODEEP_HOOK_FILE    - absolute path of the file that was edited
+ *
+ * Security note: hooks run arbitrary shell. They are project-scoped — a
+ * cloned repo with hostile hooks would execute its scripts on the user's
+ * machine the first time they trigger an agent tool call. The welcome
+ * banner warns when hooks exist (see `summarizeHooks`); we do not run
+ * hooks from `~/.codeep/hooks/` (global) for that reason.
+ */
+export type HookEvent = 'pre_tool_call' | 'post_edit' | 'on_error' | 'pre_commit';
+export declare const HOOK_EVENTS: readonly HookEvent[];
+export interface HookContext {
+    event: HookEvent;
+    workspaceRoot: string;
+    sessionId?: string;
+    /** For pre_tool_call / on_error / post_edit */
+    toolName?: string;
+    /** For pre_tool_call / on_error */
+    toolParams?: Record<string, unknown>;
+    /** For post_edit */
+    filePath?: string;
+}
+export interface HookResult {
+    /** True if a hook script existed and was actually invoked. */
+    executed: boolean;
+    /** Exit code, or 0 if no hook was present. */
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** True if this hook event blocks downstream work AND the hook failed. */
+    blocked: boolean;
+    /** Path that was executed (useful for error messages). */
+    scriptPath?: string;
+}
+/**
+ * Execute the configured hook for an event, if any. Returns `executed: false`
+ * if no script exists. Caller is responsible for checking `blocked` and
+ * aborting the parent action when it's true.
+ */
+export declare function runHook(ctx: HookContext, opts?: {
+    timeoutMs?: number;
+}): HookResult;
+/**
+ * Inspect a workspace and return which hook scripts are installed.
+ * Used by the welcome banner and `/hooks` slash command.
+ */
+export declare function listInstalledHooks(workspaceRoot: string): {
+    event: HookEvent;
+    scriptPath: string;
+}[];
+/**
+ * Render an installed-hook list as Markdown for `/hooks` output.
+ */
+export declare function formatHookList(hooks: ReturnType<typeof listInstalledHooks>): string;
+/**
+ * Short one-line summary used in the welcome banner when hooks are present.
+ * Returns empty string if no hooks installed.
+ */
+export declare function summarizeHooks(workspaceRoot: string): string;

package/dist/utils/hooks.js

@@ -0,0 +1,223 @@
+/**
+ * Project-local lifecycle hooks.
+ *
+ * User drops executable shell scripts in `.codeep/hooks/<event>.sh` and Codeep
+ * runs them at the relevant moment during a session. Generalises what the
+ * `agentAutoCommit` and `agentAutoVerify` config flags do — anything those
+ * can do, a `post_edit` hook can do too, without a code change in the CLI.
+ *
+ * Supported events:
+ *
+ *   `pre_tool_call`   — fires before every tool execution. NON-ZERO exit
+ *                       BLOCKS the tool call (the agent gets a clear error
+ *                       message). Use for policy enforcement: block writes
+ *                       to certain paths, refuse risky commands, etc.
+ *
+ *   `post_edit`       — fires after a successful write_file or edit_file.
+ *                       Exit code is ignored (auto-format / auto-lint:
+ *                       failure shouldn't block the agent). Receives the
+ *                       file path. Use for prettier/eslint/gofmt.
+ *
+ *   `on_error`        — fires when a tool call returns success=false.
+ *                       Exit code ignored. Use for centralised logging
+ *                       or alerting.
+ *
+ *   `pre_commit`      — fires before the /commit skill stages anything.
+ *                       NON-ZERO exit BLOCKS the commit. Use for test
+ *                       runs, lint gates, etc.
+ *
+ * Environment variables every hook receives:
+ *   CODEEP_HOOK_EVENT     - one of the event names above
+ *   CODEEP_WORKSPACE      - workspace root absolute path
+ *   CODEEP_SESSION_ID     - current Codeep session id
+ *
+ * Event-specific extras:
+ *   pre_tool_call / on_error:
+ *     CODEEP_HOOK_TOOL    - tool name (read_file, write_file, …)
+ *     CODEEP_HOOK_PARAMS  - JSON-encoded tool parameters
+ *   post_edit:
+ *     CODEEP_HOOK_TOOL    - 'write_file' | 'edit_file'
+ *     CODEEP_HOOK_FILE    - absolute path of the file that was edited
+ *
+ * Security note: hooks run arbitrary shell. They are project-scoped — a
+ * cloned repo with hostile hooks would execute its scripts on the user's
+ * machine the first time they trigger an agent tool call. The welcome
+ * banner warns when hooks exist (see `summarizeHooks`); we do not run
+ * hooks from `~/.codeep/hooks/` (global) for that reason.
+ */
+import { existsSync, readdirSync, statSync, accessSync, constants } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+export const HOOK_EVENTS = ['pre_tool_call', 'post_edit', 'on_error', 'pre_commit'];
+/** Events whose non-zero exit aborts the action that triggered them. */
+const BLOCKING_EVENTS = new Set(['pre_tool_call', 'pre_commit']);
+const NOT_EXECUTED = { executed: false, exitCode: 0, stdout: '', stderr: '', blocked: false };
+function getHooksDir(workspaceRoot) {
+    return join(workspaceRoot, '.codeep', 'hooks');
+}
+function findHookScript(workspaceRoot, event) {
+    const dir = getHooksDir(workspaceRoot);
+    if (!existsSync(dir))
+        return null;
+    // Allow `.sh` and bare (no-extension) executable; users sometimes prefer
+    // `.codeep/hooks/post_edit` over `post_edit.sh`. Try both.
+    for (const name of [`${event}.sh`, event]) {
+        const full = join(dir, name);
+        if (!existsSync(full))
+            continue;
+        try {
+            const stat = statSync(full);
+            if (!stat.isFile())
+                continue;
+            // Must be executable by the current user — otherwise we'd surprise
+            // them with a hook that silently does nothing.
+            accessSync(full, constants.X_OK);
+            return full;
+        }
+        catch {
+            // Not executable or unreadable — try next candidate.
+        }
+    }
+    return null;
+}
+/**
+ * Execute the configured hook for an event, if any. Returns `executed: false`
+ * if no script exists. Caller is responsible for checking `blocked` and
+ * aborting the parent action when it's true.
+ */
+export function runHook(ctx, opts = {}) {
+    const script = findHookScript(ctx.workspaceRoot, ctx.event);
+    if (!script)
+        return NOT_EXECUTED;
+    const env = {
+        ...process.env,
+        CODEEP_HOOK_EVENT: ctx.event,
+        CODEEP_WORKSPACE: ctx.workspaceRoot,
+    };
+    if (ctx.sessionId)
+        env.CODEEP_SESSION_ID = ctx.sessionId;
+    if (ctx.toolName)
+        env.CODEEP_HOOK_TOOL = ctx.toolName;
+    if (ctx.toolParams) {
+        // Cap env var size — most shells choke at ~128KB total env, and a
+        // `write_file` with a 100KB content field would single-handedly blow
+        // past that. We truncate the serialised JSON instead and append a
+        // marker so hook scripts can detect overflow if they care.
+        const PARAMS_CAP = 8192;
+        let serialized = JSON.stringify(ctx.toolParams);
+        if (serialized.length > PARAMS_CAP) {
+            serialized = serialized.slice(0, PARAMS_CAP) + '...[truncated]';
+        }
+        env.CODEEP_HOOK_PARAMS = serialized;
+    }
+    if (ctx.filePath)
+        env.CODEEP_HOOK_FILE = ctx.filePath;
+    // 30s ceiling so a runaway lint / test command can't wedge the agent
+    // loop. Configurable per-call so tests can use a tight timeout.
+    const timeout = opts.timeoutMs ?? 30_000;
+    let proc;
+    try {
+        proc = spawnSync(script, [], {
+            cwd: ctx.workspaceRoot,
+            env,
+            timeout,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        // Should be rare — spawnSync usually returns a result rather than throwing.
+        return {
+            executed: true,
+            exitCode: 1,
+            stdout: '',
+            stderr: `hook spawn failed: ${err.message}`,
+            blocked: BLOCKING_EVENTS.has(ctx.event),
+            scriptPath: script,
+        };
+    }
+    const exitCode = proc.status ?? (proc.error ? 1 : 0);
+    const stdout = proc.stdout ?? '';
+    const stderr = proc.stderr ?? '';
+    const blocked = BLOCKING_EVENTS.has(ctx.event) && exitCode !== 0;
+    return { executed: true, exitCode, stdout, stderr, blocked, scriptPath: script };
+}
+/**
+ * Inspect a workspace and return which hook scripts are installed.
+ * Used by the welcome banner and `/hooks` slash command.
+ */
+export function listInstalledHooks(workspaceRoot) {
+    const dir = getHooksDir(workspaceRoot);
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    // Build a set of which events have a script — try both `<event>.sh` and
+    // bare-name forms, mirroring findHookScript.
+    const seen = new Set();
+    const out = [];
+    for (const event of HOOK_EVENTS) {
+        for (const candidate of [`${event}.sh`, event]) {
+            if (!entries.includes(candidate))
+                continue;
+            const full = join(dir, candidate);
+            try {
+                if (!statSync(full).isFile())
+                    continue;
+                accessSync(full, constants.X_OK);
+                if (seen.has(event))
+                    break;
+                seen.add(event);
+                out.push({ event, scriptPath: full });
+                break;
+            }
+            catch {
+                // Skip unreadable / non-executable.
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Render an installed-hook list as Markdown for `/hooks` output.
+ */
+export function formatHookList(hooks) {
+    if (hooks.length === 0) {
+        return [
+            '_No hooks installed in this workspace._',
+            '',
+            'Drop an executable script in `.codeep/hooks/<event>.sh` to enable one. Supported events:',
+            '',
+            ...HOOK_EVENTS.map(e => `- \`${e}\`${BLOCKING_EVENTS.has(e) ? '  *(non-zero exit blocks the action)*' : ''}`),
+            '',
+            'Example — auto-format on save:',
+            '',
+            '```bash',
+            '#!/bin/bash',
+            '# .codeep/hooks/post_edit.sh',
+            'prettier --write "$CODEEP_HOOK_FILE" 2>/dev/null',
+            '```',
+        ].join('\n');
+    }
+    const lines = ['## Installed hooks', ''];
+    for (const h of hooks) {
+        const tag = BLOCKING_EVENTS.has(h.event) ? ' *(blocking)*' : '';
+        lines.push(`- \`${h.event}\`${tag} — \`${h.scriptPath}\``);
+    }
+    return lines.join('\n');
+}
+/**
+ * Short one-line summary used in the welcome banner when hooks are present.
+ * Returns empty string if no hooks installed.
+ */
+export function summarizeHooks(workspaceRoot) {
+    const hooks = listInstalledHooks(workspaceRoot);
+    if (hooks.length === 0)
+        return '';
+    return `${hooks.length} hook${hooks.length === 1 ? '' : 's'} active (${hooks.map(h => h.event).join(', ')})`;
+}

package/dist/utils/mcpClient.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Minimal MCP (Model Context Protocol) stdio client.
+ *
+ * Each `McpClient` instance owns one child process running an MCP server
+ * (e.g. `npx @modelcontextprotocol/server-filesystem /some/path`). It speaks
+ * JSON-RPC 2.0 over stdio per the MCP spec, performs the
+ * initialize → tools/list handshake, and exposes a `callTool` method that
+ * agent tool dispatch routes through.
+ *
+ * Scope of this MVP:
+ *   - initialize + tools/list discovery
+ *   - tools/call forwarding
+ *   - stop() kills the process and rejects in-flight requests
+ *
+ * NOT covered yet (defer to a future iteration):
+ *   - resources / prompts / sampling MCP primitives
+ *   - capability negotiation beyond "we want tools"
+ *   - server-initiated requests (we ignore them)
+ *   - reconnect on crash (process exit is fatal for that client)
+ */
+import type { McpServer } from '../acp/protocol.js';
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+export interface McpResource {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpResourceContent {
+    uri: string;
+    mimeType?: string;
+    /** Text payload — set when the server returns a text resource. */
+    text?: string;
+    /** Base64 blob payload — set when the server returns binary. */
+    blob?: string;
+}
+export interface McpPrompt {
+    name: string;
+    description?: string;
+    /** Argument metadata if the prompt is parameterised. */
+    arguments?: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+}
+export interface McpPromptMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: {
+        type: string;
+        text?: string;
+        [k: string]: unknown;
+    };
+}
+/**
+ * Server-initiated `sampling/createMessage` request payload. MCP servers
+ * that opt into the `sampling` capability send this to ask the host LLM
+ * (Codeep, in our case) to generate a completion on their behalf.
+ */
+export interface SamplingCreateMessageParams {
+    messages: {
+        role: 'user' | 'assistant';
+        content: {
+            type: 'text';
+            text: string;
+        } | {
+            type: 'image';
+            data: string;
+            mimeType: string;
+        };
+    }[];
+    modelPreferences?: {
+        hints?: {
+            name?: string;
+        }[];
+        costPriority?: number;
+        speedPriority?: number;
+        intelligencePriority?: number;
+    };
+    systemPrompt?: string;
+    includeContext?: 'none' | 'thisServer' | 'allServers';
+    temperature?: number;
+    maxTokens?: number;
+    stopSequences?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface SamplingCreateMessageResult {
+    role: 'assistant';
+    content: {
+        type: 'text';
+        text: string;
+    };
+    model: string;
+    stopReason?: 'endTurn' | 'stopSequence' | 'maxTokens';
+}
+export declare class McpClient {
+    readonly server: McpServer;
+    readonly clientOpts: {
+        workspaceRoot?: string;
+        onSamplingRequest?: (params: SamplingCreateMessageParams) => Promise<SamplingCreateMessageResult>;
+    };
+    /** Stdio transport state. Null when running over HTTP (or before start). */
+    private child;
+    /** HTTP transport state. Null when running over stdio. */
+    private http;
+    private pending;
+    private buffer;
+    private stopped;
+    private toolsCache;
+    /** True when this client is configured for the Streamable HTTP transport. */
+    private get isHttp();
+    /**
+     * Rolling-window record of recent crash times (ms epoch). Used by the
+     * auto-reconnect logic: too many crashes in a short window → give up
+     * instead of spinning indefinitely on a broken server.
+     */
+    private crashTimestamps;
+    /** Reconnect tuning — generous defaults, configurable via env if needed. */
+    private readonly MAX_RESTARTS;
+    private readonly RESTART_WINDOW_MS;
+    /** Has the agent loop been notified that this server is fully gone? */
+    private gaveUp;
+    /**
+     * Optional callback fired after a successful auto-restart. The registry
+     * uses this to drop its tools cache so the next `listTools()` re-queries
+     * (the server may expose a different tool set after restart).
+     */
+    onRestart?: () => void;
+    /**
+     * Optional callback fired when the client gives up after exceeding the
+     * restart budget. The registry uses this to surface a visible "MCP
+     * server died" error in /mcp.
+     */
+    onGaveUp?: (reason: string) => void;
+    /**
+     * Optional callback fired when the server sends a `notifications/*`
+     * indicating its catalog changed (tools, resources, prompts). The
+     * registry forwards this up so the agent loop can re-fetch on the next
+     * iteration.
+     */
+    onCatalogChanged?: (kind: 'tools' | 'resources' | 'prompts') => void;
+    /**
+     * @param server  MCP server config (command, args, env, name).
+     * @param opts    Optional client metadata.
+     *                - `workspaceRoot` exposed to the server as a root via
+     *                  the `roots` capability so filesystem-style servers
+     *                  can scope their reads.
+     *                - `onSamplingRequest` makes the client advertise the
+     *                  `sampling` capability and routes server-initiated
+     *                  `sampling/createMessage` to the host LLM.
+     */
+    constructor(server: McpServer, clientOpts?: {
+        workspaceRoot?: string;
+        onSamplingRequest?: (params: SamplingCreateMessageParams) => Promise<SamplingCreateMessageResult>;
+    });
+    /** Open the transport and perform the MCP handshake. */
+    start(opts?: {
+        initTimeoutMs?: number;
+    }): Promise<void>;
+    /** Discover tools the server exposes. Cached on first call. */
+    listTools(): Promise<McpTool[]>;
+    /**
+     * Discover resources the server exposes. Not all servers implement
+     * resources/list — those return a `-32601 Method not found`, which we
+     * surface as an empty array (callers can treat absence and emptiness
+     * the same way).
+     */
+    listResources(): Promise<McpResource[]>;
+    /** Read one resource by URI. */
+    readResource(uri: string): Promise<McpResourceContent[]>;
+    /** Discover prompt templates the server exposes (optional capability). */
+    listPrompts(): Promise<McpPrompt[]>;
+    /** Materialise a prompt template into its message sequence. */
+    getPrompt(name: string, args?: Record<string, unknown>): Promise<{
+        description?: string;
+        messages: McpPromptMessage[];
+    }>;
+    /** Invoke a tool on this server. */
+    callTool(name: string, args: Record<string, unknown>, opts?: {
+        timeoutMs?: number;
+    }): Promise<string>;
+    /**
+     * Attempt to spawn a fresh child process after a crash. Tries up to
+     * MAX_RESTARTS times within RESTART_WINDOW_MS, then gives up. After a
+     * successful restart, `toolsCache` is cleared so the next listTools()
+     * re-queries — the server may legitimately expose different tools after
+     * a code reload.
+     */
+    private attemptRestart;
+    /** Wire up data/exit/error listeners on the current child. Used by start() and attemptRestart(). */
+    private attachChildHandlers;
+    /** Tear down the transport (stdio child or HTTP stream) and reject pending requests. */
+    stop(): Promise<void>;
+    private handleStdout;
+    /**
+     * Handle a request from the MCP server (server-initiated JSON-RPC).
+     * Currently handled methods:
+     *   - `roots/list` — return the workspace folder if provided
+     *   - `sampling/createMessage` — delegate to the host LLM callback if
+     *     one was wired into the constructor; otherwise -32601 (so a
+     *     server that asks without us advertising the capability gets a
+     *     clear "no" instead of a hang).
+     *
+     * Anything else replies with `-32601 Method not found` per JSON-RPC spec.
+     */
+    private handleServerRequest;
+    /** Serialise and send a JSON-RPC response over whichever transport is active. */
+    private writeResponse;
+    /**
+     * Single send path used by request/notify/writeResponse. Stdio just
+     * pipes the serialised frame + newline. HTTP POSTs the JSON body; the
+     * response (or any later SSE event) re-enters via `dispatchFrame`.
+     * Errors on the HTTP path reject pending request promises so the
+     * agent doesn't hang waiting on a frame that'll never come.
+     */
+    private writeFrame;
+    /**
+     * Common entry point for every incoming JSON-RPC frame, regardless of
+     * transport. Stdio's `handleStdout` parses lines and forwards each
+     * here; the HTTP transport calls this directly from its `onFrame`.
+     */
+    private dispatchFrame;
+    private request;
+    private notify;
+}