gsd-pi 2.22.0 → 2.23.0

package/README.md

@@ -221,6 +221,26 @@ gsd
 
 Both terminals read and write the same `.gsd/` files on disk. Your decisions in terminal 2 are picked up automatically at the next phase boundary — no need to stop auto mode.
 
+### Headless mode — CI and scripts
+
+`gsd headless` runs any `/gsd` command without a TUI. Designed for CI pipelines, cron jobs, and scripted automation.
+
+```bash
+# Run auto mode in CI
+gsd headless --timeout 600000
+
+# One unit at a time (cron-friendly)
+gsd headless next
+
+# Machine-readable status
+gsd headless --json status
+
+# Force a specific pipeline phase
+gsd headless dispatch plan
+```
+
+Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Pair with [remote questions](./docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
+
 ### First launch
 
 On first run, GSD launches a branded setup wizard that walks you through LLM provider selection (OAuth or API key), then optional tool API keys (Brave Search, Context7, Jina, Slack, Discord). Every step is skippable — press Enter to skip any. If you have an existing Pi installation, your provider credentials (LLM and tool keys) are imported automatically. Run `gsd config` anytime to re-run the wizard.
@@ -254,7 +274,10 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `Ctrl+Alt+V`            | Toggle voice transcription                                      |
 | `Ctrl+Alt+B`            | Show background shell processes                                 |
 | `gsd config`            | Re-run the setup wizard (LLM provider + tool keys)              |
+| `gsd update`            | Update GSD to the latest version                                |
+| `gsd headless [cmd]`    | Run `/gsd` commands without TUI (CI, cron, scripts)             |
 | `gsd --continue` (`-c`) | Resume the most recent session for the current directory        |
+| `gsd sessions`          | Interactive session picker — browse and resume any saved session |
 
 ---
 
@@ -396,7 +419,7 @@ GSD ships with 14 extensions, all loaded automatically:
 | Extension              | What it provides                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
 | **GSD**                | Core workflow engine, auto mode, commands, dashboard                                                                   |
-| **Browser Tools**      | Playwright-based browser with form intelligence, intent-ranked element finding, and semantic actions                   |
+| **Browser Tools**      | Playwright-based browser with form intelligence, intent-ranked element finding, semantic actions, PDF export, session state persistence, network mocking, device emulation, structured extraction, visual diffing, region zoom, test code generation, and prompt injection detection |
 | **Search the Web**     | Brave Search, Tavily, or Jina page extraction                                                                          |
 | **Google Search**      | Gemini-powered web search with AI-synthesized answers                                                                  |
 | **Context7**           | Up-to-date library/framework documentation                                                                             |
@@ -482,6 +505,7 @@ GSD is a TypeScript application that embeds the Pi coding agent SDK.
 gsd (CLI binary)
   └─ loader.ts          Sets PI_PACKAGE_DIR, GSD env vars, dynamic-imports cli.ts
       └─ cli.ts         Wires SDK managers, loads extensions, starts InteractiveMode
+          ├─ headless.ts     Headless orchestrator (spawns RPC child, auto-responds, detects completion)
           ├─ onboarding.ts   First-run setup wizard (LLM provider + tool keys)
           ├─ wizard.ts       Env hydration from stored auth.json credentials
           ├─ app-paths.ts    ~/.gsd/agent/, ~/.gsd/sessions/, auth.json

package/dist/cli.js

@@ -91,6 +91,59 @@ if (cliFlags.messages[0] === 'update') {
     await runUpdate();
     process.exit(0);
 }
+// `gsd sessions` — list past sessions and pick one to resume
+if (cliFlags.messages[0] === 'sessions') {
+    const cwd = process.cwd();
+    const safePath = `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+    const projectSessionsDir = join(sessionsDir, safePath);
+    process.stderr.write(chalk.dim(`Loading sessions for ${cwd}...\n`));
+    const sessions = await SessionManager.list(cwd, projectSessionsDir);
+    if (sessions.length === 0) {
+        process.stderr.write(chalk.yellow('No sessions found for this directory.\n'));
+        process.exit(0);
+    }
+    process.stderr.write(chalk.bold(`\n  Sessions (${sessions.length}):\n\n`));
+    const maxShow = 20;
+    const toShow = sessions.slice(0, maxShow);
+    for (let i = 0; i < toShow.length; i++) {
+        const s = toShow[i];
+        const date = s.modified.toLocaleString();
+        const msgs = s.messageCount;
+        const name = s.name ? ` ${chalk.cyan(s.name)}` : '';
+        const preview = s.firstMessage
+            ? s.firstMessage.replace(/\n/g, ' ').substring(0, 80)
+            : chalk.dim('(empty)');
+        const num = String(i + 1).padStart(3);
+        process.stderr.write(`  ${chalk.bold(num)}. ${chalk.green(date)} ${chalk.dim(`(${msgs} msgs)`)}${name}\n`);
+        process.stderr.write(`       ${chalk.dim(preview)}\n\n`);
+    }
+    if (sessions.length > maxShow) {
+        process.stderr.write(chalk.dim(`  ... and ${sessions.length - maxShow} more\n\n`));
+    }
+    // Interactive selection
+    const readline = await import('node:readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    const answer = await new Promise((resolve) => {
+        rl.question(chalk.bold('  Enter session number to resume (or q to quit): '), resolve);
+    });
+    rl.close();
+    const choice = parseInt(answer, 10);
+    if (isNaN(choice) || choice < 1 || choice > toShow.length) {
+        process.stderr.write(chalk.dim('Cancelled.\n'));
+        process.exit(0);
+    }
+    const selected = toShow[choice - 1];
+    process.stderr.write(chalk.green(`\nResuming session from ${selected.modified.toLocaleString()}...\n\n`));
+    // Mark for the interactive session below to open this specific session
+    cliFlags.continue = true;
+    cliFlags._selectedSessionPath = selected.path;
+}
+// `gsd headless` — run auto-mode without TUI
+if (cliFlags.messages[0] === 'headless') {
+    const { runHeadless, parseHeadlessArgs } = await import('./headless.js');
+    await runHeadless(parseHeadlessArgs(process.argv));
+    process.exit(0);
+}
 // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
 // Provision local managed binaries first so Pi sees them without probing PATH.
@@ -98,7 +151,10 @@ ensureManagedTools(join(agentDir, 'bin'));
 const authStorage = AuthStorage.create(authFilePath);
 loadStoredEnvKeys(authStorage);
 migratePiCredentials(authStorage);
-const modelRegistry = new ModelRegistry(authStorage);
+// Resolve models.json path with fallback to ~/.pi/agent/models.json
+const { resolveModelsJsonPath } = await import('./models-resolver.js');
+const modelsJsonPath = resolveModelsJsonPath();
+const modelRegistry = new ModelRegistry(authStorage, modelsJsonPath);
 const settingsManager = SettingsManager.create(agentDir);
 // Run onboarding wizard on first launch (no LLM provider configured)
 if (!isPrintMode && shouldRunOnboarding(authStorage, settingsManager.getDefaultProvider())) {
@@ -298,9 +354,11 @@ if (existsSync(sessionsDir)) {
         // Non-fatal — don't block startup if migration fails
     }
 }
-const sessionManager = cliFlags.continue
-    ? SessionManager.continueRecent(cwd, projectSessionsDir)
-    : SessionManager.create(cwd, projectSessionsDir);
+const sessionManager = cliFlags._selectedSessionPath
+    ? SessionManager.open(cliFlags._selectedSessionPath, projectSessionsDir)
+    : cliFlags.continue
+        ? SessionManager.continueRecent(cwd, projectSessionsDir)
+        : SessionManager.create(cwd, projectSessionsDir);
 exitIfManagedResourcesAreNewer(agentDir);
 initResources(agentDir);
 const resourceLoader = buildResourceLoader(agentDir);

package/dist/headless.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Headless Orchestrator — `gsd headless`
+ *
+ * Runs any /gsd subcommand without a TUI by spawning a child process in
+ * RPC mode, auto-responding to extension UI requests, and streaming
+ * progress to stderr.
+ *
+ * Exit codes:
+ *   0 — complete (command finished successfully)
+ *   1 — error or timeout
+ *   2 — blocked (command reported a blocker)
+ */
+export interface HeadlessOptions {
+    timeout: number;
+    json: boolean;
+    model?: string;
+    command: string;
+    commandArgs: string[];
+}
+export declare function parseHeadlessArgs(argv: string[]): HeadlessOptions;
+export declare function runHeadless(options: HeadlessOptions): Promise<void>;

package/dist/headless.js

@@ -0,0 +1,346 @@
+/**
+ * Headless Orchestrator — `gsd headless`
+ *
+ * Runs any /gsd subcommand without a TUI by spawning a child process in
+ * RPC mode, auto-responding to extension UI requests, and streaming
+ * progress to stderr.
+ *
+ * Exit codes:
+ *   0 — complete (command finished successfully)
+ *   1 — error or timeout
+ *   2 — blocked (command reported a blocker)
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+// RpcClient is not in @gsd/pi-coding-agent's public exports — import from dist directly.
+// This relative path resolves correctly from both src/ (via tsx) and dist/ (compiled).
+import { RpcClient } from '../packages/pi-coding-agent/dist/modes/rpc/rpc-client.js';
+// ---------------------------------------------------------------------------
+// CLI Argument Parser
+// ---------------------------------------------------------------------------
+export function parseHeadlessArgs(argv) {
+    const options = {
+        timeout: 300_000,
+        json: false,
+        command: 'auto',
+        commandArgs: [],
+    };
+    const args = argv.slice(2);
+    let positionalStarted = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === 'headless')
+            continue;
+        if (!positionalStarted && arg.startsWith('--')) {
+            if (arg === '--timeout' && i + 1 < args.length) {
+                options.timeout = parseInt(args[++i], 10);
+                if (Number.isNaN(options.timeout) || options.timeout <= 0) {
+                    process.stderr.write('[headless] Error: --timeout must be a positive integer (milliseconds)\n');
+                    process.exit(1);
+                }
+            }
+            else if (arg === '--json') {
+                options.json = true;
+            }
+            else if (arg === '--model' && i + 1 < args.length) {
+                // --model can also be passed from the main CLI; headless-specific takes precedence
+                options.model = args[++i];
+            }
+        }
+        else if (!positionalStarted) {
+            positionalStarted = true;
+            options.command = arg;
+        }
+        else {
+            options.commandArgs.push(arg);
+        }
+    }
+    return options;
+}
+// ---------------------------------------------------------------------------
+// JSONL Helper
+// ---------------------------------------------------------------------------
+function serializeJsonLine(obj) {
+    return JSON.stringify(obj) + '\n';
+}
+// ---------------------------------------------------------------------------
+// Extension UI Auto-Responder
+// ---------------------------------------------------------------------------
+function handleExtensionUIRequest(event, writeToStdin) {
+    const { id, method } = event;
+    let response;
+    switch (method) {
+        case 'select':
+            response = { type: 'extension_ui_response', id, value: event.options?.[0] ?? '' };
+            break;
+        case 'confirm':
+            response = { type: 'extension_ui_response', id, confirmed: true };
+            break;
+        case 'input':
+            response = { type: 'extension_ui_response', id, value: '' };
+            break;
+        case 'editor':
+            response = { type: 'extension_ui_response', id, value: event.prefill ?? '' };
+            break;
+        case 'notify':
+        case 'setStatus':
+        case 'setWidget':
+        case 'setTitle':
+        case 'set_editor_text':
+            response = { type: 'extension_ui_response', id, value: '' };
+            break;
+        default:
+            process.stderr.write(`[headless] Warning: unknown extension_ui_request method "${method}", cancelling\n`);
+            response = { type: 'extension_ui_response', id, cancelled: true };
+            break;
+    }
+    writeToStdin(serializeJsonLine(response));
+}
+// ---------------------------------------------------------------------------
+// Progress Formatter
+// ---------------------------------------------------------------------------
+function formatProgress(event) {
+    const type = String(event.type ?? '');
+    switch (type) {
+        case 'tool_execution_start':
+            return `[tool] ${event.toolName ?? 'unknown'}`;
+        case 'agent_start':
+            return '[agent] Session started';
+        case 'agent_end':
+            return '[agent] Session ended';
+        case 'extension_ui_request':
+            if (event.method === 'notify') {
+                return `[gsd] ${event.message ?? ''}`;
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Completion Detection
+// ---------------------------------------------------------------------------
+const TERMINAL_KEYWORDS = ['complete', 'stopped', 'blocked'];
+const IDLE_TIMEOUT_MS = 15_000;
+function isTerminalNotification(event) {
+    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
+        return false;
+    const message = String(event.message ?? '').toLowerCase();
+    return TERMINAL_KEYWORDS.some((kw) => message.includes(kw));
+}
+function isBlockedNotification(event) {
+    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
+        return false;
+    return String(event.message ?? '').toLowerCase().includes('blocked');
+}
+// ---------------------------------------------------------------------------
+// Quick Command Detection
+// ---------------------------------------------------------------------------
+const QUICK_COMMANDS = new Set([
+    'status', 'queue', 'history', 'hooks', 'export', 'stop', 'pause',
+    'capture', 'skip', 'undo', 'knowledge', 'config', 'prefs',
+    'cleanup', 'migrate', 'doctor', 'remote', 'help', 'steer',
+    'triage', 'visualize',
+]);
+function isQuickCommand(command) {
+    return QUICK_COMMANDS.has(command);
+}
+// ---------------------------------------------------------------------------
+// Main Orchestrator
+// ---------------------------------------------------------------------------
+export async function runHeadless(options) {
+    const startTime = Date.now();
+    // Validate .gsd/ directory
+    const gsdDir = join(process.cwd(), '.gsd');
+    if (!existsSync(gsdDir)) {
+        process.stderr.write('[headless] Error: No .gsd/ directory found in current directory.\n');
+        process.stderr.write("[headless] Run 'gsd' interactively first to initialize a project.\n");
+        process.exit(1);
+    }
+    // Resolve CLI path for the child process
+    const cliPath = process.env.GSD_BIN_PATH || process.argv[1];
+    if (!cliPath) {
+        process.stderr.write('[headless] Error: Cannot determine CLI path. Set GSD_BIN_PATH or run via gsd.\n');
+        process.exit(1);
+    }
+    // Create RPC client
+    const clientOptions = {
+        cliPath,
+        cwd: process.cwd(),
+    };
+    if (options.model) {
+        clientOptions.model = options.model;
+    }
+    const client = new RpcClient(clientOptions);
+    // Event tracking
+    let totalEvents = 0;
+    let toolCallCount = 0;
+    let blocked = false;
+    let completed = false;
+    let exitCode = 0;
+    const recentEvents = [];
+    function trackEvent(event) {
+        totalEvents++;
+        const type = String(event.type ?? 'unknown');
+        if (type === 'tool_execution_start') {
+            toolCallCount++;
+        }
+        // Keep last 20 events for diagnostics
+        const detail = type === 'tool_execution_start'
+            ? String(event.toolName ?? '')
+            : type === 'extension_ui_request'
+                ? `${event.method}: ${event.title ?? event.message ?? ''}`
+                : undefined;
+        recentEvents.push({ type, timestamp: Date.now(), detail });
+        if (recentEvents.length > 20)
+            recentEvents.shift();
+    }
+    // Stdin writer for sending extension_ui_response to child
+    let stdinWriter = null;
+    // Completion promise
+    let resolveCompletion;
+    const completionPromise = new Promise((resolve) => {
+        resolveCompletion = resolve;
+    });
+    // Idle timeout — fallback completion detection
+    let idleTimer = null;
+    function resetIdleTimer() {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        if (toolCallCount > 0) {
+            idleTimer = setTimeout(() => {
+                completed = true;
+                resolveCompletion();
+            }, IDLE_TIMEOUT_MS);
+        }
+    }
+    // Overall timeout
+    const timeoutTimer = setTimeout(() => {
+        process.stderr.write(`[headless] Timeout after ${options.timeout / 1000}s\n`);
+        exitCode = 1;
+        resolveCompletion();
+    }, options.timeout);
+    // Event handler
+    client.onEvent((event) => {
+        const eventObj = event;
+        trackEvent(eventObj);
+        resetIdleTimer();
+        // --json mode: forward all events as JSONL to stdout
+        if (options.json) {
+            process.stdout.write(JSON.stringify(eventObj) + '\n');
+        }
+        else {
+            // Progress output to stderr
+            const line = formatProgress(eventObj);
+            if (line)
+                process.stderr.write(line + '\n');
+        }
+        // Handle extension_ui_request
+        if (eventObj.type === 'extension_ui_request' && stdinWriter) {
+            // Check for terminal notification before auto-responding
+            if (isBlockedNotification(eventObj)) {
+                blocked = true;
+            }
+            if (isTerminalNotification(eventObj)) {
+                completed = true;
+            }
+            handleExtensionUIRequest(eventObj, stdinWriter);
+            // If we detected a terminal notification, resolve after responding
+            if (completed) {
+                exitCode = blocked ? 2 : 0;
+                resolveCompletion();
+                return;
+            }
+        }
+        // Quick commands: resolve on first agent_end
+        if (eventObj.type === 'agent_end' && isQuickCommand(options.command) && !completed) {
+            completed = true;
+            resolveCompletion();
+            return;
+        }
+        // Long-running commands: agent_end after tool execution — possible completion
+        // The idle timer + terminal notification handle this case.
+    });
+    // Signal handling
+    const signalHandler = () => {
+        process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
+        exitCode = 1;
+        client.stop().finally(() => {
+            clearTimeout(timeoutTimer);
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            process.exit(exitCode);
+        });
+    };
+    process.on('SIGINT', signalHandler);
+    process.on('SIGTERM', signalHandler);
+    // Start the RPC session
+    try {
+        await client.start();
+    }
+    catch (err) {
+        process.stderr.write(`[headless] Error: Failed to start RPC session: ${err instanceof Error ? err.message : String(err)}\n`);
+        clearTimeout(timeoutTimer);
+        process.exit(1);
+    }
+    // Access stdin writer from the internal process
+    const internalProcess = client.process;
+    if (!internalProcess?.stdin) {
+        process.stderr.write('[headless] Error: Cannot access child process stdin\n');
+        await client.stop();
+        clearTimeout(timeoutTimer);
+        process.exit(1);
+    }
+    stdinWriter = (data) => {
+        internalProcess.stdin.write(data);
+    };
+    // Detect child process crash
+    internalProcess.on('exit', (code) => {
+        if (!completed) {
+            const msg = `[headless] Child process exited unexpectedly with code ${code ?? 'null'}\n`;
+            process.stderr.write(msg);
+            exitCode = 1;
+            resolveCompletion();
+        }
+    });
+    if (!options.json) {
+        process.stderr.write(`[headless] Running /gsd ${options.command}${options.commandArgs.length > 0 ? ' ' + options.commandArgs.join(' ') : ''}...\n`);
+    }
+    // Send the command
+    const command = `/gsd ${options.command}${options.commandArgs.length > 0 ? ' ' + options.commandArgs.join(' ') : ''}`;
+    try {
+        await client.prompt(command);
+    }
+    catch (err) {
+        process.stderr.write(`[headless] Error: Failed to send prompt: ${err instanceof Error ? err.message : String(err)}\n`);
+        exitCode = 1;
+    }
+    // Wait for completion
+    if (exitCode === 0 || exitCode === 2) {
+        await completionPromise;
+    }
+    // Cleanup
+    clearTimeout(timeoutTimer);
+    if (idleTimer)
+        clearTimeout(idleTimer);
+    process.removeListener('SIGINT', signalHandler);
+    process.removeListener('SIGTERM', signalHandler);
+    await client.stop();
+    // Summary
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+    const status = blocked ? 'blocked' : exitCode === 1 ? (totalEvents === 0 ? 'error' : 'timeout') : 'complete';
+    process.stderr.write(`[headless] Status: ${status}\n`);
+    process.stderr.write(`[headless] Duration: ${duration}s\n`);
+    process.stderr.write(`[headless] Events: ${totalEvents} total, ${toolCallCount} tool calls\n`);
+    // On failure, print last 5 events for diagnostics
+    if (exitCode !== 0) {
+        const lastFive = recentEvents.slice(-5);
+        if (lastFive.length > 0) {
+            process.stderr.write('[headless] Last events:\n');
+            for (const e of lastFive) {
+                process.stderr.write(`  ${e.type}${e.detail ? `: ${e.detail}` : ''}\n`);
+            }
+        }
+    }
+    process.exit(exitCode);
+}

package/dist/help-text.js

@@ -17,6 +17,36 @@ const SUBCOMMAND_HELP = {
         '',
         'Equivalent to: npm install -g gsd-pi@latest',
     ].join('\n'),
+    sessions: [
+        'Usage: gsd sessions',
+        '',
+        'List all saved sessions for the current directory and interactively',
+        'pick one to resume. Shows date, message count, and a preview of the',
+        'first message for each session.',
+        '',
+        'Sessions are stored per-directory, so you only see sessions that were',
+        'started from the current working directory.',
+        '',
+        'Compare with --continue (-c) which always resumes the most recent session.',
+    ].join('\n'),
+    headless: [
+        'Usage: gsd headless [flags] [command] [args...]',
+        '',
+        'Run /gsd commands without the TUI. Default command: auto',
+        '',
+        'Flags:',
+        '  --timeout N     Overall timeout in ms (default: 300000)',
+        '  --json          JSONL event stream to stdout',
+        '  --model ID      Override model',
+        '',
+        'Examples:',
+        '  gsd headless                    Run /gsd auto',
+        '  gsd headless next               Run one unit',
+        '  gsd headless --json status      Machine-readable status',
+        '  gsd headless --timeout 60000    With 1-minute timeout',
+        '',
+        'Exit codes: 0 = complete, 1 = error/timeout, 2 = blocked',
+    ].join('\n'),
 };
 export function printHelp(version) {
     process.stdout.write(`GSD v${version} — Get Shit Done\n\n`);
@@ -35,6 +65,8 @@ export function printHelp(version) {
     process.stdout.write('\nSubcommands:\n');
     process.stdout.write('  config                   Re-run the setup wizard\n');
     process.stdout.write('  update                   Update GSD to the latest version\n');
+    process.stdout.write('  sessions                 List and resume a past session\n');
+    process.stdout.write('  headless [cmd] [args]    Run /gsd commands without TUI (default: auto)\n');
     process.stdout.write('\nRun gsd <subcommand> --help for subcommand-specific help.\n');
 }
 export function printSubcommandHelp(subcommand, version) {

package/dist/mcp-server.d.ts

@@ -1,4 +1,8 @@
-interface McpTool {
+/**
+ * Minimal tool interface matching GSD's AgentTool shape.
+ * Avoids a direct dependency on @gsd/pi-agent-core from this compiled module.
+ */
+export interface McpToolDef {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
@@ -11,8 +15,21 @@ interface McpTool {
         }>;
     }>;
 }
+/**
+ * Starts a native MCP (Model Context Protocol) server over stdin/stdout.
+ *
+ * This enables GSD's tools (read, write, edit, bash, grep, glob, ls, etc.)
+ * to be used by external AI clients such as Claude Desktop, VS Code Copilot,
+ * and any MCP-compatible host.
+ *
+ * The server registers all tools from the agent session's tool registry and
+ * maps MCP tools/list and tools/call requests to GSD tool definitions and
+ * execution, respectively.
+ *
+ * All MCP SDK imports are dynamic to avoid subpath export resolution issues
+ * with TypeScript's NodeNext module resolution.
+ */
 export declare function startMcpServer(options: {
-    tools: McpTool[];
+    tools: McpToolDef[];
     version?: string;
 }): Promise<void>;
-export {};

package/dist/mcp-server.js

@@ -2,6 +2,20 @@
 // at runtime but TypeScript cannot statically type-check. We construct the
 // specifiers dynamically so tsc treats them as `any`.
 const MCP_PKG = '@modelcontextprotocol/sdk';
+/**
+ * Starts a native MCP (Model Context Protocol) server over stdin/stdout.
+ *
+ * This enables GSD's tools (read, write, edit, bash, grep, glob, ls, etc.)
+ * to be used by external AI clients such as Claude Desktop, VS Code Copilot,
+ * and any MCP-compatible host.
+ *
+ * The server registers all tools from the agent session's tool registry and
+ * maps MCP tools/list and tools/call requests to GSD tool definitions and
+ * execution, respectively.
+ *
+ * All MCP SDK imports are dynamic to avoid subpath export resolution issues
+ * with TypeScript's NodeNext module resolution.
+ */
 export async function startMcpServer(options) {
     const { tools, version = '0.0.0' } = options;
     const serverMod = await import(`${MCP_PKG}/server`);
@@ -10,11 +24,13 @@ export async function startMcpServer(options) {
     const Server = serverMod.Server;
     const StdioServerTransport = stdioMod.StdioServerTransport;
     const { ListToolsRequestSchema, CallToolRequestSchema } = typesMod;
+    // Build a lookup map for fast tool resolution on calls
     const toolMap = new Map();
     for (const tool of tools) {
         toolMap.set(tool.name, tool);
     }
     const server = new Server({ name: 'gsd', version }, { capabilities: { tools: {} } });
+    // tools/list — return every registered GSD tool with its JSON Schema parameters
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: tools.map((t) => ({
             name: t.name,
@@ -22,6 +38,7 @@ export async function startMcpServer(options) {
             inputSchema: t.parameters,
         })),
     }));
+    // tools/call — execute the requested tool and return content blocks
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         const tool = toolMap.get(name);
@@ -32,7 +49,9 @@ export async function startMcpServer(options) {
             };
         }
         try {
-            const result = await tool.execute(`mcp-${Date.now()}`, args ?? {}, undefined, undefined);
+            const result = await tool.execute(`mcp-${Date.now()}`, args ?? {}, undefined, // no AbortSignal
+            undefined);
+            // Convert AgentToolResult content blocks to MCP content format
             const content = result.content.map((block) => {
                 if (block.type === 'text')
                     return { type: 'text', text: block.text ?? '' };
@@ -47,6 +66,7 @@ export async function startMcpServer(options) {
             return { isError: true, content: [{ type: 'text', text: message }] };
         }
     });
+    // Connect to stdin/stdout transport
     const transport = new StdioServerTransport();
     await server.connect(transport);
     process.stderr.write(`[gsd] MCP server started (v${version})\n`);