klyro 1.0.4 → 1.0.6

package/dist/index.js

@@ -56,12 +56,14 @@ async function main() {
         .option('--verbose', 'Verbose output')
         .option('--quiet', 'Suppress non-essential output')
         .option('--json', 'Force JSON output where supported')
-        .option('--yes', 'Auto-approve prompts where possible')
+        .option('--yes', 'Auto-approve commit prompts (scope: `klyro commit` only)')
         .option('--no-color', 'Disable colored output')
         .option('-p, --print <prompt>', 'Headless one-shot prompt (alias for run, --output json for machine)')
         .option('--output-format <fmt>', 'Headless output format: text|json|stream-json (default text)')
-        .option('--no-stream', 'Disable streaming (buffer full response)')
-        .option('--show-thinking', 'Show thinking blocks');
+        .option('--temperature <n>', 'Sampling temperature 0-2 (headless -p / run)', parseTemperature)
+        .option('--max-tokens <n>', 'Max output tokens per step (headless -p / run)', (v) => parsePositiveInt('--max-tokens', v))
+        .option('--no-stream', 'Disable streaming (TUI only; headless json always streams events)')
+        .option('--show-thinking', 'Show thinking blocks (TUI only)');
     // Unknown commands / unknown options are usage errors (exit 2 per PRD).
     // Help and version still exit 0; anything else rethrows to the last-resort
     // handler (exit 1).
@@ -197,12 +199,30 @@ async function main() {
         const code = await runDoctor({ json: !!opts.json });
         process.exit(code);
     });
+    program
+        .command('init')
+        .description('Bootstrap this project: scan + KLYRO.md draft + .mcp.json skeleton (never overwrites)')
+        .action(async () => {
+        const { initProject, nextStepsText } = await import('./cli/init.js');
+        try {
+            const { created, skipped } = await initProject(process.cwd());
+            for (const f of created)
+                process.stdout.write(`created ${f}\n`);
+            for (const f of skipped)
+                process.stdout.write(`kept ${f}\n`);
+            process.stdout.write(nextStepsText() + '\n');
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`klyro: init failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    });
     // Support `klyro "prompt"` positional headless (2.5)
     program.argument('[prompt]', 'Headless one-shot prompt (same as -p)');
     program
         .action(async (promptArg) => {
-        const opts = program.opts();
-        // 9.2 — --continue / --resume handling
+        const opts = program.opts(); // 9.2 — --continue / --resume handling
         if (opts.continue || typeof opts.resume === 'string') {
             const { getDefaultSessionStore } = await import('./persistence/session.js');
             const store = getDefaultSessionStore();
@@ -243,6 +263,7 @@ async function main() {
                 cwd: process.cwd(),
                 model: process.env.KLYRO_MODEL ?? 'gpt-4o-mini',
                 maxTokens: opts.maxTokens,
+                temperature: opts.temperature,
                 output: output,
                 provider: process.env.KLYRO_PROVIDER,
             });
@@ -298,6 +319,7 @@ async function main() {
         .option('--require-verify', 'Fail with exit 8 if no verification passed after edits (6.5)')
         .option('--agent <name>', 'Run under an orchestrator context enabling spawn_agent/task_list/task_get (explorer|implementer|tester|reviewer)')
         .option('--max-depth <n>', 'Max spawn depth for child agents (default 1)', (v) => parsePositiveInt('--max-depth', v))
+        .option('--bare', 'Deterministic runs: skip MCP, hooks, memory/KLYRO.md/context, persistence')
         .action(async (prompt, opts) => {
         const model = opts.model ?? process.env.KLYRO_MODEL;
         if (!model) {
@@ -339,6 +361,7 @@ async function main() {
                 requireVerify: !!opts.requireVerify,
                 agent: opts.agent,
                 maxDepth: opts.maxDepth,
+                bare: !!opts.bare,
             });
             process.exit(code);
         }
@@ -370,17 +393,18 @@ async function main() {
         .option('--runs <n>', 'Runs per fixture (default 1)', (v) => parsePositiveInt('--runs', v))
         .option('--parallel <n>', 'Parallelism (default 1)', (v) => parsePositiveInt('--parallel', v))
         .option('--model <id>', 'Model for eval')
+        .option('--judge-model <id>', 'Live model id for grading judge.rubric (needs endpoint + key)')
         .action(async (input, opts) => {
         const output = (opts.output ?? 'human');
         if (opts.suite) {
-            const code = await runEval({ inputPath: input ?? '-', output, suite: opts.suite, filter: opts.filter, runs: opts.runs, parallel: opts.parallel, model: opts.model });
+            const code = await runEval({ inputPath: input ?? '-', output, suite: opts.suite, filter: opts.filter, runs: opts.runs, parallel: opts.parallel, model: opts.model, judgeModel: opts.judgeModel });
             process.exit(code);
         }
         if (!input) {
             process.stderr.write('klyro eval: missing input (provide <input> or --suite)\n');
             process.exit(2);
         }
-        const code = await runEval({ inputPath: input, output, suite: opts.suite, filter: opts.filter, runs: opts.runs, parallel: opts.parallel, model: opts.model });
+        const code = await runEval({ inputPath: input, output, suite: opts.suite, filter: opts.filter, runs: opts.runs, parallel: opts.parallel, model: opts.model, judgeModel: opts.judgeModel });
         process.exit(code);
     });
     program
@@ -395,14 +419,11 @@ async function main() {
         process.stdout.write(out + '\n');
         process.exit(0);
     });
-    // Level 9 — Session management
-    const session = program.command('session').description('Session persistence (Level 9)');
-    session
-        .command('list')
-        .description('List persisted sessions')
-        .option('--status <s>', 'Filter by status: open|complete|verify_failed|aborted|max_steps')
-        .option('--json', 'Output JSON')
-        .action(async (opts) => {
+    // Level 9 — Session management.
+    // One namespace: `session` and `sessions` accept the SAME subcommands
+    // (list/show/resume/export/import/fork/delete). Handlers live here once
+    // and both command groups delegate to them.
+    async function sessionList(opts) {
         const { getDefaultSessionStore, formatSession } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
         const all = await store.list(opts.status ? { status: opts.status } : undefined);
@@ -419,25 +440,26 @@ async function main() {
                 }
             }
         }
-    });
-    session
-        .command('show <id>')
-        .description('Show session transcript and observations')
-        .option('--json', 'Output JSON')
-        .action(async (id, opts) => {
+    }
+    async function resolveOrExit(id) {
         const { getDefaultSessionStore, resolveSessionId, matchSessionIds } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
         const full = await resolveSessionId(store, id);
-        if (!full) {
-            const matches = await matchSessionIds(store, id);
-            if (matches.length > 1) {
-                process.stderr.write(`ambiguous id "${id}" matches:\n${matches.map((r) => `  ${r.id.slice(0, 8)}  ${r.task.slice(0, 50)}`).join('\n')}\n`);
-            }
-            else {
-                process.stderr.write(`session not found: ${id}\n`);
-            }
-            process.exit(2);
+        if (full)
+            return full;
+        const matches = await matchSessionIds(store, id);
+        if (matches.length > 1) {
+            process.stderr.write(`ambiguous id "${id}" matches:\n${matches.map((r) => `  ${r.id.slice(0, 8)}  ${r.task.slice(0, 50)}`).join('\n')}\n`);
+        }
+        else {
+            process.stderr.write(`session not found: ${id}\n`);
         }
+        process.exit(2);
+    }
+    async function sessionShow(id, opts) {
+        const { getDefaultSessionStore } = await import('./persistence/session.js');
+        const store = getDefaultSessionStore();
+        const full = await resolveOrExit(id);
         const rec = await store.get(full);
         const msgs = await store.loadMessages(full);
         const obs = await store.loadObservations(full);
@@ -453,28 +475,11 @@ async function main() {
             for (const o of obs)
                 process.stdout.write(`  ${o.toolName} -> ${o.isError ? 'ERR' : 'ok'} ${JSON.stringify(o.output).slice(0, 120)}\n`);
         }
-    });
-    session
-        .command('resume <id>')
-        .description('Resume a persisted session (requires KLYRO_MODEL etc.)')
-        .option('-m, --model <id>', 'Model (default: from session or env)')
-        .option('--max-steps <n>', 'Max steps (default 30)', (v) => parsePositiveInt('--max-steps', v))
-        .option('--verify-command <cmd>', 'Override verification command')
-        .option('--verify', 'Enable verification (default: enabled)')
-        .action(async (id, opts) => {
-        const { getDefaultSessionStore, resolveSessionId, matchSessionIds } = await import('./persistence/session.js');
+    }
+    async function sessionResume(id, opts) {
+        const { getDefaultSessionStore } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
-        const full = await resolveSessionId(store, id);
-        if (!full) {
-            const matches = await matchSessionIds(store, id);
-            if (matches.length > 1) {
-                process.stderr.write(`ambiguous id "${id}" matches:\n${matches.map((r) => `  ${r.id.slice(0, 8)}  ${r.task.slice(0, 50)}`).join('\n')}\n`);
-            }
-            else {
-                process.stderr.write(`session not found: ${id}\n`);
-            }
-            process.exit(2);
-        }
+        const full = await resolveOrExit(id);
         const rec = await store.get(full);
         if (!rec) {
             process.stderr.write(`session not found: ${id}\n`);
@@ -495,75 +500,67 @@ async function main() {
             verifyCommand: opts.verifyCommand,
         });
         process.exit(code);
-    });
-    // Alias: klyro resume <id> → klyro session resume <id>
-    program
-        .command('resume <id>')
-        .description('Alias for `klyro session resume <id>`')
-        .option('-m, --model <id>', 'Model')
-        .option('--max-steps <n>', 'Max steps', (v) => parsePositiveInt('--max-steps', v))
-        .action(async (id, opts) => {
-        const { getDefaultSessionStore, resolveSessionId, matchSessionIds } = await import('./persistence/session.js');
-        const store = getDefaultSessionStore();
-        const full = await resolveSessionId(store, id);
-        if (!full) {
-            const matches = await matchSessionIds(store, id);
-            if (matches.length > 1) {
-                process.stderr.write(`ambiguous id "${id}" matches:\n${matches.map((r) => `  ${r.id.slice(0, 8)}  ${r.task.slice(0, 50)}`).join('\n')}\n`);
-            }
-            else {
-                process.stderr.write(`session not found: ${id}\n`);
-            }
-            process.exit(2);
-        }
-        const rec = await store.get(full);
-        if (!rec) {
-            process.stderr.write(`session not found: ${id}\n`);
-            process.exit(2);
-        }
-        const model = opts.model ?? rec.config.model ?? process.env.KLYRO_MODEL;
-        if (!model) {
-            process.stderr.write('klyro: KLYRO_MODEL is not set (or pass --model)\n');
-            process.exit(2);
-        }
-        const code = await runOnce({
-            task: rec.task,
-            cwd: rec.cwd,
-            model,
-            maxSteps: opts.maxSteps ?? rec.config.maxSteps,
-            sessionId: full,
-        });
-        process.exit(code);
-    });
-    program.command('scan').description('Scan project (7.1) — languages, frameworks, commands, 300ms cached').option('--json', 'JSON output').action(async (opts) => { const { runScan } = await import('./cli/scan.js'); process.exit(await runScan({ cwd: process.cwd(), json: !!opts.json })); });
-    program.command('project').description('Alias for scan').option('--json', 'JSON output').action(async (opts) => { const { runProject } = await import('./cli/scan.js'); process.exit(await runProject({ cwd: process.cwd(), json: !!opts.json })); });
-    // 9.2 — Continue / resume top-level flags (also handled via session resume)
-    program.option('-c, --continue', 'Continue most recent session in cwd (9.2)');
-    program.option('-r, --resume [id]', 'Resume session by id or pick most recent');
-    // 9.4 — Sessions extended: fork/rename/export/import/prune/history + locks
-    const sessions = program.command('sessions').description('Alias for session');
-    sessions.command('export <id> [file]').description('Export session to file (9.4)').action(async (id, file) => {
-        const { getDefaultSessionStore, resolveSessionId } = await import('./persistence/session.js');
+    }
+    async function sessionExport(id, file) {
+        const { getDefaultSessionStore } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
-        const full = await resolveSessionId(store, id);
-        if (!full) {
-            process.stderr.write(`session not found: ${id}\n`);
-            process.exit(2);
-        }
+        const full = await resolveOrExit(id);
         const rec = await store.get(full);
         const msgs = await store.loadMessages(full);
+        const obs = await store.loadObservations(full);
         const out = file ?? `${full}.export.json`;
-        await (await import('node:fs/promises')).writeFile(out, JSON.stringify({ record: rec, messages: msgs }, null, 2));
+        await (await import('node:fs/promises')).writeFile(out, JSON.stringify({ record: rec, messages: msgs, observations: obs }, null, 2));
         process.stdout.write(`exported ${full} → ${out}\n`);
-    });
-    sessions.command('import <file>').description('Import session from file').action(async (file) => {
-        const data = JSON.parse(await (await import('node:fs/promises')).readFile(file, 'utf-8'));
+    }
+    async function sessionImport(file) {
+        let data;
+        try {
+            data = JSON.parse(await (await import('node:fs/promises')).readFile(file, 'utf-8'));
+        }
+        catch (err) {
+            process.stderr.write(`klyro: cannot import ${file}: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+        const rec = data.record ?? {};
         const { getDefaultSessionStore } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
-        const rec = await store.create({ cwd: data.record?.cwd ?? process.cwd(), task: data.record?.task ?? 'imported', config: data.record?.config ?? { model: 'imported', maxSteps: 30 } });
-        process.stdout.write(`imported → ${rec.id}\n`);
-    });
-    sessions.command('fork <id>').description('Fork session with full context (9.4)').action(async (id) => {
+        const cfg = (rec.config && typeof rec.config === 'object' ? rec.config : { model: 'imported', maxSteps: 30 });
+        const created = await store.create({ cwd: typeof rec.cwd === 'string' ? rec.cwd : process.cwd(), task: typeof rec.task === 'string' ? rec.task : 'imported', config: cfg });
+        // Restore the transcript — previously this was silently dropped (lossy
+        // import). Messages/observations go through append* so at-rest redaction
+        // still applies. Malformed entries fail loudly instead of half-importing.
+        const d = data;
+        let restored = 0;
+        if (d.messages !== undefined) {
+            if (!Array.isArray(d.messages)) {
+                process.stderr.write(`klyro: import failed: "messages" is not an array in ${file}\n`);
+                process.exit(2);
+            }
+            for (const m of d.messages) {
+                if (!m || typeof m !== 'object' || typeof m.role !== 'string' || !('content' in m)) {
+                    process.stderr.write(`klyro: import failed: malformed message entry in ${file}\n`);
+                    process.exit(2);
+                }
+                await store.appendMessage(created.id, m);
+                restored++;
+            }
+        }
+        if (d.observations !== undefined) {
+            if (!Array.isArray(d.observations)) {
+                process.stderr.write(`klyro: import failed: "observations" is not an array in ${file}\n`);
+                process.exit(2);
+            }
+            for (const o of d.observations) {
+                if (!o || typeof o !== 'object') {
+                    process.stderr.write(`klyro: import failed: malformed observation entry in ${file}\n`);
+                    process.exit(2);
+                }
+                await store.appendObservation(created.id, o);
+            }
+        }
+        process.stdout.write(`imported → ${created.id} (${restored} messages restored)\n`);
+    }
+    async function sessionFork(id) {
         const { getDefaultSessionStore, matchSessionIds } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
         const matches = await matchSessionIds(store, id);
@@ -579,8 +576,8 @@ async function main() {
         const forked = await store.fork(full);
         const msgs = await store.loadMessages(forked.id);
         process.stdout.write(`forked ${full.slice(0, 8)} → ${forked.id.slice(0, 8)} (${msgs.length} messages carried over)\n`);
-    });
-    sessions.command('delete <id>').description('Delete a session and its artifacts').action(async (id) => {
+    }
+    async function sessionDelete(id) {
         const { getDefaultSessionStore, matchSessionIds } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
         const matches = await matchSessionIds(store, id);
@@ -595,7 +592,64 @@ async function main() {
         const full = matches[0].id;
         await store.delete(full);
         process.stdout.write(`deleted ${full.slice(0, 8)}\n`);
-    });
+    }
+    const session = program.command('session').description('Session persistence (Level 9)');
+    session
+        .command('list')
+        .description('List persisted sessions')
+        .option('--status <s>', 'Filter by status: open|complete|verify_failed|aborted|max_steps')
+        .option('--json', 'Output JSON')
+        .action(async (opts) => { await sessionList(opts); });
+    session
+        .command('show <id>')
+        .description('Show session transcript and observations')
+        .option('--json', 'Output JSON')
+        .action(async (id, opts) => { await sessionShow(id, opts); });
+    session
+        .command('resume <id>')
+        .description('Resume a persisted session (requires KLYRO_MODEL etc.)')
+        .option('-m, --model <id>', 'Model (default: from session or env)')
+        .option('--max-steps <n>', 'Max steps (default 30)', (v) => parsePositiveInt('--max-steps', v))
+        .option('--verify-command <cmd>', 'Override verification command')
+        .option('--verify', 'Enable verification (default: enabled)')
+        .action(async (id, opts) => { await sessionResume(id, opts); });
+    session
+        .command('export <id> [file]')
+        .description('Export session to file (9.4)')
+        .action(async (id, file) => { await sessionExport(id, file); });
+    session
+        .command('import <file>')
+        .description('Import session from file (restores record + messages + observations)')
+        .action(async (file) => { await sessionImport(file); });
+    session
+        .command('fork <id>')
+        .description('Fork session with full context (9.4)')
+        .action(async (id) => { await sessionFork(id); });
+    session
+        .command('delete <id>')
+        .description('Delete a session and its artifacts')
+        .action(async (id) => { await sessionDelete(id); });
+    // Alias: klyro resume <id> → klyro session resume <id>
+    program
+        .command('resume <id>')
+        .description('Alias for `klyro session resume <id>`')
+        .option('-m, --model <id>', 'Model')
+        .option('--max-steps <n>', 'Max steps', (v) => parsePositiveInt('--max-steps', v))
+        .action(async (id, opts) => { await sessionResume(id, opts); });
+    program.command('scan').description('Scan project (7.1) — languages, frameworks, commands, 300ms cached').option('--json', 'JSON output').action(async (opts) => { const { runScan } = await import('./cli/scan.js'); process.exit(await runScan({ cwd: process.cwd(), json: !!opts.json })); });
+    program.command('project').description('Alias for scan').option('--json', 'JSON output').action(async (opts) => { const { runProject } = await import('./cli/scan.js'); process.exit(await runProject({ cwd: process.cwd(), json: !!opts.json })); });
+    // 9.2 — Continue / resume top-level flags (also handled via session resume)
+    program.option('-c, --continue', 'Continue most recent session in cwd (9.2)');
+    program.option('-r, --resume [id]', 'Resume session by id or pick most recent');
+    // 9.4 — same namespace as `session`: every subcommand works under both.
+    const sessions = program.command('sessions').description('Alias for session (same subcommands)');
+    sessions.command('list').description('List persisted sessions').option('--status <s>', 'Filter by status').option('--json', 'Output JSON').action(async (opts) => { await sessionList(opts); });
+    sessions.command('show <id>').description('Show session transcript and observations').option('--json', 'Output JSON').action(async (id, opts) => { await sessionShow(id, opts); });
+    sessions.command('resume <id>').description('Resume a persisted session').option('-m, --model <id>', 'Model').option('--max-steps <n>', 'Max steps', (v) => parsePositiveInt('--max-steps', v)).action(async (id, opts) => { await sessionResume(id, opts); });
+    sessions.command('export <id> [file]').description('Export session to file (9.4)').action(async (id, file) => { await sessionExport(id, file); });
+    sessions.command('import <file>').description('Import session from file (restores record + messages + observations)').action(async (file) => { await sessionImport(file); });
+    sessions.command('fork <id>').description('Fork session with full context (9.4)').action(async (id) => { await sessionFork(id); });
+    sessions.command('delete <id>').description('Delete a session and its artifacts').action(async (id) => { await sessionDelete(id); });
     // 10.1 — MCP
     const mcp = program.command('mcp').description('MCP client/server (10.1)');
     mcp.command('list').description('List MCP servers').action(async () => {
@@ -612,7 +666,35 @@ async function main() {
             process.stdout.write(`${name} source=${source}${spec?.disabled ? ' disabled' : ''}\n`);
         }
     });
-    mcp.command('add <name> <url>').description('Add MCP server').action(async (name) => { process.stdout.write(`added mcp ${name} (stub)\n`); });
+    mcp.command('add <name> <command> [args...]').description('Add a project MCP server to .mcp.json (stdio command, or https:// URL for remote)').action(async (name, command, args) => {
+        const { addProjectServer, projectMcpPath } = await import('./mcp/config.js');
+        try {
+            // URL first arg → remote Streamable-HTTP server; else stdio command.
+            const spec = /^https?:\/\//i.test(command)
+                ? { url: command }
+                : { command, ...(args && args.length > 0 ? { args } : {}) };
+            addProjectServer(process.cwd(), name, spec);
+            process.stdout.write(`added mcp server "${name}" → ${projectMcpPath(process.cwd())}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`klyro: mcp add failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+    });
+    mcp.command('remove <name>').description('Remove a project MCP server from .mcp.json').action(async (name) => {
+        const { removeProjectServer, projectMcpPath } = await import('./mcp/config.js');
+        try {
+            if (!removeProjectServer(process.cwd(), name)) {
+                process.stderr.write(`klyro: mcp server not found in ${projectMcpPath(process.cwd())}: ${name}\n`);
+                process.exit(2);
+            }
+            process.stdout.write(`removed mcp server "${name}"\n`);
+        }
+        catch (err) {
+            process.stderr.write(`klyro: mcp remove failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+    });
     mcp.command('probe <name>').description('Connect to an MCP server (15s timeout), list its tools, print count+names').action(async (name) => {
         const { loadMcpServers } = await import('./mcp/config.js');
         const cfg = loadMcpServers(process.cwd());
@@ -621,18 +703,21 @@ async function main() {
             process.stderr.write(`klyro: mcp server not found: ${name}\n`);
             process.exit(2);
         }
-        const { McpClient } = await import('./mcp/client.js');
-        const client = new McpClient(name, spec);
-        // 15s overall probe budget (connect has its own internal timeout too).
+        const { makeMcpClient } = await import('./mcp/registry.js');
+        const client = makeMcpClient(name, spec); // 15s overall probe budget (connect has its own internal timeout too).
         const timer = setTimeout(() => {
             process.stderr.write(`klyro: mcp probe ${name} timed out after 15s\n`);
             process.exit(2);
         }, 15_000);
         try {
-            await client.connect();
+            const withConnect = client;
+            if (typeof withConnect.connect === 'function')
+                await withConnect.connect();
             const tools = await client.listTools();
+            const prompts = typeof client.promptsList === 'function' ? await client.promptsList().catch(() => []) : [];
             const names = tools.map((t) => t.name);
-            process.stdout.write(`${name}: ${tools.length} tool(s)${names.length > 0 ? `: ${names.join(', ')}` : ''}\n`);
+            const extra = prompts.length > 0 ? `, ${prompts.length} prompt(s): ${prompts.map((p) => p.name).join(', ')}` : '';
+            process.stdout.write(`${name}: ${tools.length} tool(s)${names.length > 0 ? `: ${names.join(', ')}` : ''}${extra}\n`);
             process.exit(0);
         }
         catch (err) {
@@ -647,7 +732,11 @@ async function main() {
             catch { /* ignore */ }
         }
     });
-    mcp.command('serve').description('Serve as MCP server').action(async () => { process.stdout.write('klyro mcp serve — exposing tools (stub)\n'); });
+    mcp.command('serve').description('Serve builtin tools as an MCP server over stdio (policy-gated)').action(async () => {
+        const { serveStdio } = await import('./mcp/serve.js');
+        const code = await serveStdio(process.cwd());
+        process.exit(code);
+    });
     // 10.2 — Hooks: list configured preToolUse/postToolUse hooks.
     program.command('hooks [cmd]').description('Hooks (10.2): `klyro hooks` or `klyro hooks list` prints configured hooks').action(async (cmd) => {
         if (cmd && cmd !== 'list') {
@@ -661,15 +750,16 @@ async function main() {
             return;
         }
         for (const h of hooks)
-            process.stdout.write(`${h.name} ${h.event} ${h.command}\n`);
+            process.stdout.write(`${h.name} ${h.event}${h.matcher ? ` (${h.matcher})` : ''} ${h.command}\n`);
     });
-    program.command('agents [name] [extra...]').description('List agents (10.2), show one, or run: agents run <name> <task...>').action(async (name, extra) => {
-        const { BUILTIN_AGENTS } = await import('./agent/orchestrator.js');
+    program.command('agents [name] [extra...]').description('List agents (builtins + .klyro/agents/*.md), show one, or run: agents run <name> <task...>').action(async (name, extra) => {
+        const { listAllAgents } = await import('./agent/orchestrator.js');
+        const ALL = listAllAgents(process.cwd());
         // `klyro agents run <name> <task...>`: one-shot run under a named agent.
         if (name === 'run') {
             const [agentName, ...taskParts] = extra ?? [];
-            if (!agentName || !BUILTIN_AGENTS.some((a) => a.id === agentName)) {
-                process.stderr.write(`klyro: unknown agent: ${agentName ?? '(missing)'} (known: ${BUILTIN_AGENTS.map((a) => a.id).join(', ')})\n`);
+            if (!agentName || !ALL.some((a) => a.id === agentName)) {
+                process.stderr.write(`klyro: unknown agent: ${agentName ?? '(missing)'} (known: ${ALL.map((a) => a.id).join(', ')})\n`);
                 process.exit(2);
             }
             const task = (taskParts ?? []).join(' ').trim();
@@ -686,19 +776,20 @@ async function main() {
             process.exit(code);
         }
         if (!name) {
-            for (const a of BUILTIN_AGENTS)
-                process.stdout.write(`${a.id} — ${a.description}\n`);
+            for (const a of ALL)
+                process.stdout.write(`${a.id}${a.source && a.source !== 'builtin' ? ` (${a.source})` : ''} — ${a.description}\n`);
             return;
         }
-        const def = BUILTIN_AGENTS.find((a) => a.id === name);
+        const def = ALL.find((a) => a.id === name);
         if (!def) {
-            process.stderr.write(`klyro: unknown agent: ${name} (known: ${BUILTIN_AGENTS.map((a) => a.id).join(', ')})\n`);
+            process.stderr.write(`klyro: unknown agent: ${name} (known: ${ALL.map((a) => a.id).join(', ')})\n`);
             process.exit(2);
         }
         const tools = def.allowedTools ?? ['<inherited: all parent tools>'];
         const lines = [
             `agent: ${def.id}`,
             `description: ${def.description}`,
+            `source: ${def.source ?? 'builtin'}`,
             `tools (${tools.length}): ${tools.join(', ')}`,
             `readonly: ${def.readonly ?? false}`,
             `canSpawn: ${def.canSpawn ?? false}`,
@@ -706,6 +797,8 @@ async function main() {
             `maxSteps: ${def.maxSteps ?? '<default>'}`,
             `maxTokens: ${def.maxTokens ?? '<default>'}`,
         ];
+        if (def.prompt)
+            lines.push(`prompt: ${def.prompt.slice(0, 200)}${def.prompt.length > 200 ? '…' : ''}`);
         process.stdout.write(lines.join('\n') + '\n');
     });
     // 10.3 — Web / git workflows / SDK

package/dist/mcp/client.d.ts

@@ -9,6 +9,15 @@ export interface McpResource {
     name?: string;
     mimeType?: string;
 }
+export interface McpPromptDef {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
 export interface McpCallResult {
     /** Normalized text payload (content blocks joined). */
     text: string;
@@ -19,6 +28,8 @@ export interface McpClientLike {
     listTools(signal?: AbortSignal): Promise<McpToolDef[]>;
     callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpCallResult>;
     listResources(signal?: AbortSignal): Promise<McpResource[]>;
+    promptsList?(signal?: AbortSignal): Promise<McpPromptDef[]>;
+    promptsGet?(name: string, args?: Record<string, string>, signal?: AbortSignal): Promise<string>;
     close(): Promise<void>;
 }
 export declare class McpError extends Error {
@@ -43,6 +54,10 @@ export declare class McpClient implements McpClientLike {
     callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpCallResult>;
     listResources(signal?: AbortSignal): Promise<McpResource[]>;
     readResource(uri: string, signal?: AbortSignal): Promise<string>;
+    /** List prompts; servers without prompts support yield [] (not an error). */
+    promptsList(signal?: AbortSignal): Promise<McpPromptDef[]>;
+    /** Get a prompt's messages as text. Throws McpError when unsupported/unknown. */
+    promptsGet(name: string, args?: Record<string, string>, signal?: AbortSignal): Promise<string>;
     close(): Promise<void>;
     /** Test hook: number of in-flight JSON-RPC requests. */
     pendingCount(): number;

package/dist/mcp/client.js

@@ -2,7 +2,8 @@
  * P1 — MCP stdio client (r-11-17.md §3.1).
  *
  * Minimal JSON-RPC 2.0 over newline-delimited stdio: `initialize`,
- * `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`.
+ * `tools/list`, `tools/call`, `resources/list`, `resources/read`,
+ * `prompts/list`, `prompts/get`, `ping`.
  * Every call is bound to an `AbortSignal` and a per-call timeout; spawn
  * failures and server errors surface as typed `McpError`s — never throws
  * raw across the boundary.
@@ -38,15 +39,22 @@ export class McpClient {
     constructor(name, spec) {
         this.name = name;
         this.spec = spec;
+        // URL specs route to RemoteMcpClient via makeMcpClient — direct
+        // construction without a command is a programming error, fail fast.
+        if (!spec.command)
+            throw new McpError(`mcp server "${name}" has no command (use url for remote servers)`, 'INVALID_SPEC');
     }
     async connect() {
         if (this.child)
             return;
+        const command = this.spec.command;
+        if (!command)
+            throw new McpError(`mcp server "${this.name}" has no command (use url for remote servers)`, 'INVALID_SPEC');
         const timeoutMs = this.spec.policy?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         await new Promise((resolve, reject) => {
             let child;
             try {
-                child = spawn(this.spec.command, this.spec.args ?? [], {
+                child = spawn(command, this.spec.args ?? [], {
                     stdio: ['pipe', 'pipe', 'pipe'],
                     env: { ...process.env, ...(this.spec.env ?? {}) },
                     shell: false,
@@ -136,6 +144,38 @@ export class McpClient {
         const contents = Array.isArray(res.contents) ? res.contents : [];
         return contents.map((c) => (typeof c.text === 'string' ? c.text : JSON.stringify(c))).join('\n');
     }
+    /** List prompts; servers without prompts support yield [] (not an error). */
+    async promptsList(signal) {
+        this.assertLive();
+        let res;
+        try {
+            res = (await this.request('prompts/list', {}, this.timeout(), signal));
+        }
+        catch (err) {
+            if (err instanceof McpError && err.code === 'SERVER_ERROR' && err.details?.code === -32601) {
+                return [];
+            }
+            throw err;
+        }
+        return Array.isArray(res.prompts) ? res.prompts : [];
+    }
+    /** Get a prompt's messages as text. Throws McpError when unsupported/unknown. */
+    async promptsGet(name, args, signal) {
+        this.assertLive();
+        const res = (await this.request('prompts/get', { name, arguments: args ?? {} }, this.timeout(), signal));
+        const messages = Array.isArray(res.messages) ? res.messages : [];
+        const parts = [];
+        if (typeof res.description === 'string' && res.description)
+            parts.push(res.description);
+        for (const m of messages) {
+            const c = m.content;
+            if (c && typeof c.text === 'string')
+                parts.push(c.text);
+            else if (c !== undefined)
+                parts.push(JSON.stringify(c));
+        }
+        return parts.join('\n\n');
+    }
     async close() {
         // Idempotent vs the exit handler: closed is set FIRST (the on('exit')
         // callback checks it before failAll), and a second close() with no child