klyro 1.0.5 → 1.0.7

package/dist/index.js

@@ -60,8 +60,10 @@ async function main() {
         .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).
@@ -143,8 +145,9 @@ async function main() {
     program
         .command('update')
         .description('Check for klyro updates (cached 24h, KLYRO_NO_UPDATE_CHECK=1 to disable)')
-        .action(async () => {
-        const code = await runUpdate();
+        .option('--apply', 'Apply the update now via npm i -g (opt-in; default is notify-only)')
+        .action(async (opts) => {
+        const code = await runUpdate({ apply: !!opts.apply });
         process.exit(code);
     });
     program
@@ -197,12 +200,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 +264,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 +320,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 +362,7 @@ async function main() {
                 requireVerify: !!opts.requireVerify,
                 agent: opts.agent,
                 maxDepth: opts.maxDepth,
+                bare: !!opts.bare,
             });
             process.exit(code);
         }
@@ -370,17 +394,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 +420,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 +441,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 +476,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,69 +501,19 @@ 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, observations: obs }, null, 2));
         process.stdout.write(`exported ${full} → ${out}\n`);
-    });
-    sessions.command('import <file>').description('Import session from file (restores record + messages + observations)').action(async (file) => {
+    }
+    async function sessionImport(file) {
         let data;
         try {
             data = JSON.parse(await (await import('node:fs/promises')).readFile(file, 'utf-8'));
@@ -604,8 +560,8 @@ async function main() {
             }
         }
         process.stdout.write(`imported → ${created.id} (${restored} messages restored)\n`);
-    });
-    sessions.command('fork <id>').description('Fork session with full context (9.4)').action(async (id) => {
+    }
+    async function sessionFork(id) {
         const { getDefaultSessionStore, matchSessionIds } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
         const matches = await matchSessionIds(store, id);
@@ -621,8 +577,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);
@@ -637,7 +593,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)).option('--verify-command <cmd>', 'Override verification command').option('--verify', 'Enable verification (default: enabled)').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 () => {
@@ -654,10 +667,14 @@ async function main() {
             process.stdout.write(`${name} source=${source}${spec?.disabled ? ' disabled' : ''}\n`);
         }
     });
-    mcp.command('add <name> <command> [args...]').description('Add a project MCP server to .mcp.json (stdio command)').action(async (name, command, args) => {
+    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 {
-            addProjectServer(process.cwd(), name, { command, ...(args && args.length > 0 ? { args } : {}) });
+            // 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) {
@@ -687,18 +704,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) {
@@ -713,6 +733,58 @@ async function main() {
             catch { /* ignore */ }
         }
     });
+    mcp.command('trust <name>').description('Trust a project MCP server spec (records its hash, enables auto-connect)').action(async (name) => {
+        const { loadMcpServers } = await import('./mcp/config.js');
+        const { McpTrust, hashSpec } = await import('./mcp/trust.js');
+        const cfg = loadMcpServers(process.cwd());
+        const spec = cfg.servers[name];
+        if (!spec) {
+            process.stderr.write(`klyro: mcp server not found: ${name}\n`);
+            process.exit(2);
+        }
+        new McpTrust().approve(name, hashSpec(spec));
+        process.stdout.write(`trusted mcp server "${name}" (source=${cfg.sources[name] ?? 'unknown'})\n`);
+    });
+    mcp.command('prompts [server]').description('List MCP prompts as /mcp__<server>__<prompt> slash names').action(async (server) => {
+        const { loadMcpServers, enabledServers } = await import('./mcp/config.js');
+        const { makeMcpClient } = await import('./mcp/registry.js');
+        const cfg = loadMcpServers(process.cwd());
+        const targets = server ? [server] : Object.keys(enabledServers(cfg));
+        if (targets.length === 0) {
+            process.stdout.write('mcp prompts: none (no servers configured)\n');
+            return;
+        }
+        let shown = 0;
+        for (const name of targets) {
+            const spec = cfg.servers[name];
+            if (!spec) {
+                process.stderr.write(`klyro: mcp server not found: ${name}\n`);
+                continue;
+            }
+            const client = makeMcpClient(name, spec);
+            try {
+                const withConnect = client;
+                if (typeof withConnect.connect === 'function')
+                    await withConnect.connect();
+                const prompts = typeof client.promptsList === 'function' ? await client.promptsList() : [];
+                for (const p of prompts) {
+                    process.stdout.write(`/mcp__${name}__${p.name}${p.description ? ` — ${p.description}` : ''}\n`);
+                    shown++;
+                }
+            }
+            catch (err) {
+                process.stderr.write(`klyro: mcp prompts ${name} failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+            finally {
+                try {
+                    await client.close();
+                }
+                catch { /* ignore */ }
+            }
+        }
+        if (shown === 0)
+            process.stdout.write('mcp prompts: none exposed by configured servers\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());
@@ -731,15 +803,49 @@ async function main() {
             return;
         }
         for (const h of hooks)
-            process.stdout.write(`${h.name} ${h.event} ${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');
+            process.stdout.write(`${h.name} ${h.event}${h.matcher ? ` (${h.matcher})` : ''} ${h.command}\n`);
+    });
+    program.command('agents [name] [extra...]').description('List agents (builtins + .klyro/agents/*.md), show one, lint files, or run: agents run <name> <task...>').action(async (name, extra) => {
+        const { listAllAgents } = await import('./agent/orchestrator.js');
+        const ALL = listAllAgents(process.cwd());
+        // `klyro agents lint`: validate custom agent files (ids, tool names).
+        if (name === 'lint') {
+            const { loadCustomAgents } = await import('./agent/custom-agents.js');
+            const { builtinRegistry } = await import('./tools/registry.js');
+            const known = new Set(builtinRegistry().list().map((t) => t.name));
+            const customs = loadCustomAgents(process.cwd());
+            if (customs.length === 0) {
+                process.stdout.write('agents lint: no custom agents in .klyro/agents/ (or ~/.klyro/agents/)\n');
+                return;
+            }
+            let bad = 0;
+            for (const a of customs) {
+                const problems = [];
+                if (!a.description || a.description === `Custom agent ${a.id}`)
+                    problems.push('missing description');
+                for (const t of a.allowedTools ?? []) {
+                    if (!known.has(t))
+                        problems.push(`unknown tool "${t}" (will be dropped at spawn)`);
+                }
+                if (!a.prompt && !(a.allowedTools ?? []).length)
+                    problems.push('no prompt body and no tools — agent has no specialization');
+                if (problems.length > 0) {
+                    bad++;
+                    process.stdout.write(`${a.id} (${a.source ?? 'custom'}):\n${problems.map((p) => `  ! ${p}`).join('\n')}\n`);
+                }
+                else {
+                    process.stdout.write(`${a.id} (${a.source ?? 'custom'}): ok\n`);
+                }
+            }
+            if (bad > 0)
+                process.exit(2);
+            return;
+        }
         // `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();
@@ -756,19 +862,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}`,
@@ -776,6 +883,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/auth.d.ts

@@ -0,0 +1,85 @@
+/** Shape of the `auth` block on an MCP server spec (see config.ts). */
+export interface McpAuthSpec {
+    /** OAuth 2.0 client identifier registered with the authorization server. */
+    clientId: string;
+    /** Token endpoint; when absent, discovered from the server's metadata. */
+    tokenEndpoint?: string;
+    /**
+     * Authorization endpoint; when absent, discovered from the server's
+     * metadata. The MCP server URL is the OAuth resource server, so its
+     * `/.well-known/oauth-authorization-server` metadata is the default
+     * discovery source (per the MCP 2025-06-18 auth spec).
+     */
+    authorizationEndpoint?: string;
+    /** Custom redirect URI; defaults to a loopback listener on 127.0.0.1. */
+    redirectUri?: string;
+    /** Space-separated additional scopes to request. */
+    scopes?: string;
+}
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+export interface CachedToken {
+    access_token: string;
+    token_type: string;
+    /** Unix seconds when the token expires. 0 = unknown (treated as valid). */
+    expires_at: number;
+    refresh_token?: string;
+    scope?: string;
+    cachedAtMs: number;
+}
+export declare const TOKEN_STALE_MARGIN_S = 60;
+export declare const TOKENS_FILE = "mcp-tokens.json";
+/** Fully load the token cache as a plain object (missing/corrupt → {}). */
+export declare function loadMcpTokens(): Record<string, CachedToken>;
+/**
+ * Persist a token to the 0600 cache. Merges by key so concurrent server
+ * writes don't clobber each other. A symlinked cache path is refused (the
+ * write would land outside the klyro config dir or be swapped mid-write).
+ */
+export declare function saveMcpToken(cacheKey: string, token: CachedToken): void;
+/** Stable cache key for a server URL + clientId. */
+export declare function mcpTokenCacheKey(url: string, clientId: string): string;
+/** True when a cached token is still usable (with a clock-skew margin). */
+export declare function tokenValid(t: CachedToken): boolean;
+/** PKCE (RFC 7636 §4.1): cryptographically-random 43-128 char code verifier. */
+export declare function generateCodeVerifier(): string;
+/** PKCE §4.2: base64url SHA-256 challenge of the verifier. */
+export declare function codeChallengeFromVerifier(verifier: string): string;
+export interface AuthResolveResult {
+    /** Extra headers (e.g. `Authorization`) to attach to MCP requests. */
+    headers: Record<string, string>;
+    /** True when a cached token was used (no interactive flow needed). */
+    fromCache: boolean;
+}
+/**
+ * Resolve auth headers for a server: reuse a valid cached token, else run
+ * the interactive Authorization Code + PKCE flow. Returns only the headers;
+ * failures surface as `AuthError` so callers (the MCP probe/connect path)
+ * can turn them into a clear error instead of a hang.
+ */
+export declare function resolveAuth(auth: McpAuthSpec, cacheKey: string): Promise<AuthResolveResult>;
+interface TokenResponse {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+}
+/**
+ * Run the Authorization Code flow with PKCE over a one-shot loopback
+ * redirect (RFC 8252). Best-effort and headless-friendly: on any failure it
+ * throws `AuthError` rather than leaving a stray listener. The token endpoint
+ * defaults to the OAuth metadata `token_endpoint` when the server advertises
+ * it, else the spec's `tokenEndpoint`.
+ */
+export declare function runCodeFlow(auth: McpAuthSpec, serverUrl?: string): Promise<TokenResponse | null>;
+/**
+ * Scrub credential-bearing headers from debug capture so `KLYRO_MCP_DEBUG`
+ * never writes a live access token to disk. Non-credential headers pass
+ * through untouched.
+ */
+export declare function scrubAuthHeaders(headers: Record<string, string>): Record<string, string>;
+/** Refreshes a stale token when a refresh_token is cached (best-effort). */
+export declare function tryRefresh(auth: McpAuthSpec, cached: CachedToken): Promise<CachedToken | null>;
+export {};