klyro 1.0.1 → 1.0.3

package/dist/cli/repl.js

@@ -185,6 +185,27 @@ export async function startRepl(opts = {}) {
         },
     });
     let adapter = buildAdapter(currentProvider, currentBaseUrl, currentApiKey);
+    // L15 failover — initial adapter only: extra `providers.failover` entries
+    // become fallback adapters for agent runs in this session. Live
+    // /provider switches rebuild a single adapter (buildAdapter) and bypass
+    // the chain — documented, not a bug.
+    let replFailoverAdapters = [];
+    try {
+        const { resolveProviderChain } = await import('./config.js');
+        const chain = await resolveProviderChain(cwd);
+        for (const entry of chain.slice(1)) {
+            if (!entry.apiKey)
+                continue;
+            try {
+                replFailoverAdapters.push(buildAdapter(entry.provider, entry.baseURL ?? currentBaseUrl, entry.apiKey));
+            }
+            catch { /* skip unbuildable entries */ }
+        }
+        if (replFailoverAdapters.length > 0) {
+            process.stderr.write(`klyro: failover chain: ${replFailoverAdapters.map((b) => b.id).join(' → ')}\n`);
+        }
+    }
+    catch { /* best-effort — single-provider session proceeds */ }
     const ctxBlock = await buildLevel6Context({ cwd });
     let ctxPrefix = ctxBlock.formatted ? `\n\n<context>\n${ctxBlock.formatted}\n</context>` : '';
     // 4.4 KLYRO.md hierarchy (mutable — /reload refreshes). Content is gated
@@ -646,6 +667,19 @@ export async function startRepl(opts = {}) {
         if (isMounted && directHooks)
             directHooks.clearTranscript();
     }
+    // Update nudge (best-effort, cached 24h, silent fail): a single stderr
+    // line when a newer version exists. No prompt, no blocking — the check
+    // itself is fire-and-forget.
+    void (async () => {
+        try {
+            const { checkForUpdate } = await import('./update.js');
+            const cur = readVersion();
+            const latest = await checkForUpdate(cur);
+            if (latest)
+                process.stderr.write(`Update available: ${cur} → ${latest} (klyro update)\n`);
+        }
+        catch { /* silent */ }
+    })();
     app = render(React.createElement(App, {
         initialModel: model,
         maxSteps: currentMaxSteps,
@@ -897,8 +931,14 @@ export async function startRepl(opts = {}) {
                     else if (ev.kind === 'aborted') {
                         queuedStatus({ status: 'aborted' });
                     }
+                    else if (ev.kind === 'model_override') {
+                        queuedAppend({ id: `movr-${Date.now()}`, kind: 'text', text: `[model] override: requested ${ev.requested} → effective ${ev.effective}`, role: 'assistant' });
+                    }
                 },
-            }, { adapter, registry, policy, approval, systemPrompt: systemPromptFn });
+            }, {
+                adapter, registry, policy, approval, systemPrompt: systemPromptFn,
+                ...(replFailoverAdapters.length > 0 ? { failoverAdapters: replFailoverAdapters } : {}),
+            });
             if (result.finalText)
                 lastAssistantText = result.finalText;
             if (result.verification) {

package/dist/cli/run.d.ts

@@ -70,6 +70,12 @@ export interface RunCliOptions {
     agent?: string;
     maxDepth?: number;
 }
+/**
+ * Double-Ctrl+C detector (pure, exported for tests): the second SIGINT
+ * within 1500ms of the first forces `process.exit(130)`. The live handler
+ * below owns the timestamp closure; tests exercise only this predicate.
+ */
+export declare function shouldForceExit(lastSigintAt: number | undefined, now: number): boolean;
 export declare function runOnce(opts: RunCliOptions): Promise<number>;
 /** Wrap a system-prompt fn to inject Level-6 context (project map etc.) + KLYRO.md (4.4). */
 export declare function makeRunSystemPrompt(cwd: string, base: SystemPromptFn): Promise<SystemPromptFn>;

package/dist/cli/run.js

@@ -16,6 +16,7 @@ import { run } from '../agent/runtime.js';
 import { builtinRegistry } from '../tools/registry.js';
 import { builtinRules, clonePolicyConfig, PolicyEngine } from '../policy/engine.js';
 import { DenyAllApprovalPrompt } from '../policy/approval.js';
+import { redact } from '../policy/secret-redactor.js';
 import { buildLevel6Context } from '../context/level6.js';
 import { memoryBlock } from '../context/memory.js';
 import { resolveSessionId } from '../persistence/session.js';
@@ -24,6 +25,14 @@ function readEnv(name, fallback) {
     const v = process.env[name];
     return v && v.length > 0 ? v : fallback;
 }
+/**
+ * Double-Ctrl+C detector (pure, exported for tests): the second SIGINT
+ * within 1500ms of the first forces `process.exit(130)`. The live handler
+ * below owns the timestamp closure; tests exercise only this predicate.
+ */
+export function shouldForceExit(lastSigintAt, now) {
+    return lastSigintAt !== undefined && now - lastSigintAt < 1500;
+}
 export async function runOnce(opts) {
     // P0.5 — load <cwd>/.env first so KLYRO_* vars resolve without `export`.
     // Never throws (missing file is a no-op); explicit env wins (no-clobber).
@@ -88,6 +97,36 @@ export async function runOnce(opts) {
             adapter = retryingAdapter(httpChatAdapter({ baseURL: baseUrl, apiKey, timeoutMs: opts.timeoutMs ?? 60_000 }), { onRetry: onRetryEmit });
         }
     }
+    // L15 provider failover: extra chain entries (after the primary) become
+    // fallback adapters for the runtime. Custom injected adapters (tests)
+    // skip chain wiring. Failures resolving the chain never block the run.
+    let failoverAdapters;
+    if (!opts.adapter) {
+        try {
+            const { resolveProviderChain } = await import('./config.js');
+            const chain = await resolveProviderChain(opts.cwd);
+            const fallbacks = chain.slice(1);
+            if (fallbacks.length > 0) {
+                const built = [];
+                for (const entry of fallbacks) {
+                    if (!entry.apiKey)
+                        continue;
+                    const base = entry.provider === 'anthropic'
+                        ? anthropicAdapter({ baseURL: entry.baseURL, apiKey: entry.apiKey, timeoutMs: opts.timeoutMs ?? 60_000 })
+                        : entry.baseURL
+                            ? httpChatAdapter({ baseURL: entry.baseURL, apiKey: entry.apiKey, timeoutMs: opts.timeoutMs ?? 60_000 })
+                            : null;
+                    if (base)
+                        built.push(retryingAdapter(base, { onRetry: onRetryEmit }));
+                }
+                if (built.length > 0) {
+                    failoverAdapters = built;
+                    stderr.write(`klyro: failover chain: ${built.map((b) => b.id).join(' → ')}\n`);
+                }
+            }
+        }
+        catch { /* best-effort — single-provider run proceeds */ }
+    }
     const registry = builtinRegistry();
     const policy = new PolicyEngine(builtinRules(), clonePolicyConfig());
     // Persisted "always allow" patterns apply to one-shot runs too.
@@ -149,6 +188,16 @@ export async function runOnce(opts) {
                 return 2;
             }
             sessionId = full;
+            // M22 resume-lock warning (read-only probe — takeover proceeds anyway).
+            try {
+                const { readSessionLock } = await import('../persistence/store.js');
+                const { getDefaultSessionsDir } = await import('../persistence/session.js');
+                const lock = readSessionLock(opts.sessionsDir ?? getDefaultSessionsDir(), sessionId);
+                if (lock.held && lock.alive) {
+                    stderr.write(`klyro: session ${sessionId.slice(0, 8)} is locked by live pid ${lock.pid ?? '?'} — taking over (proceeding anyway)\n`);
+                }
+            }
+            catch { /* probe is best-effort; never block resume */ }
             const msgs = await store.loadMessages(sessionId);
             // Convert StoredMessage to Message
             initialTranscript = msgs.map((m) => ({ role: m.role, content: m.content }));
@@ -176,7 +225,17 @@ export async function runOnce(opts) {
     // persistence is disabled or the session was never created).
     sessionIdForRetry.id = sessionId ?? 'ephemeral';
     const ac = new AbortController();
+    // Double-Ctrl+C: first press aborts the run; a second press within
+    // 1500ms forces process.exit(130) (shouldForceExit owns the predicate).
+    let lastSigintAt;
     const onSigint = () => {
+        const now = Date.now();
+        if (shouldForceExit(lastSigintAt, now)) {
+            stderr.write('\nklyro: SIGINT twice — forcing exit\n');
+            process.exit(130);
+            return;
+        }
+        lastSigintAt = now;
         stderr.write('\nklyro: SIGINT — aborting\n');
         ac.abort();
     };
@@ -298,8 +357,20 @@ export async function runOnce(opts) {
                     if (output === 'human')
                         stderr.write(`[session ${ev.sessionId.slice(0, 8)} checkpoint]\n`);
                 }
+                else if (ev.kind === 'provider_failover') {
+                    stderr.write(`[failover] ${ev.from} → ${ev.to}: ${ev.reason.slice(0, 200)}\n`);
+                }
+                else if (ev.kind === 'budget_warning') {
+                    stderr.write(`[budget] ${(ev.ratio * 100).toFixed(0)}% of max cost used (threshold ${(ev.threshold * 100).toFixed(0)}%)\n`);
+                }
+                else if (ev.kind === 'model_override') {
+                    stderr.write(`[model] override: requested ${ev.requested} → effective ${ev.effective}\n`);
+                }
             },
-        }, { adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt });
+        }, {
+            adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt,
+            ...(failoverAdapters ? { failoverAdapters } : {}),
+        });
     }
     finally {
         doneSigint();
@@ -404,8 +475,10 @@ async function dryRunReport(opts) {
         maxSteps: opts.maxSteps,
         maxTokens: opts.maxTokens,
         temperature: opts.temperature,
-        systemPrompt,
-        task: opts.task,
+        // Secrets must never leak into a printable report: redact both the
+        // assembled system prompt and the task before printing.
+        systemPrompt: redact(systemPrompt),
+        task: redact(opts.task),
         toolCount: registry.list().length,
         toolNames: registry.list().map((t) => t.name),
         policyRules: rules.map((r) => r.name),

package/dist/context/tokenizer.d.ts

@@ -7,6 +7,14 @@
  * never overflows the model's true window because the heuristic
  * overestimates mixed text.
  *
+ * R3 — accuracy improvement: the heuristic is *calibrated* against the
+ * provider's reported usage when available. The runtime calls
+ * `calibrateEstimate` after each message_end that carries usage, which
+ * adjusts the per-character ratio toward the real value observed for this
+ * model. The calibration is bounded (0.1–0.6 chars/token) so a bad sample
+ * can't make the budget non-conservative. Until the first sample arrives,
+ * the safe chars/4 default is used.
+ *
  * Strategy:
  *   1. Always preserve the system prompt, the latest user task, and the
  *      latest assistant message.
@@ -28,10 +36,20 @@ export interface BudgetCheck {
     used: number;
     cap: number;
 }
+/**
+ * Calibrate the heuristic against provider-reported usage. Pass the actual
+ * input token count and the char length of the transcript that was sent.
+ * The ratio self-corrects toward the model's true tokenizer behavior.
+ */
+export declare function calibrateEstimate(usedChars: number, reportedInputTokens: number): number;
+/** Current chars/token ratio (after calibration, if any). */
+export declare function charsPerTokenRatio(): number;
 export declare function estimateTokens(s: string): number;
 export declare function estimateMessage(m: Message): number;
 /** Total input tokens for a transcript + optional system prompt. */
 export declare function totalTokens(system: string | undefined, messages: Message[]): number;
+/** Count the raw character length of a transcript for calibration. */
+export declare function transcriptCharLength(system: string | undefined, messages: Message[]): number;
 /** True if the input fits under the budget cap. */
 export declare function withinBudget(system: string | undefined, messages: Message[], budget: TokenBudget): BudgetCheck;
 /**

package/dist/context/tokenizer.js

@@ -7,6 +7,14 @@
  * never overflows the model's true window because the heuristic
  * overestimates mixed text.
  *
+ * R3 — accuracy improvement: the heuristic is *calibrated* against the
+ * provider's reported usage when available. The runtime calls
+ * `calibrateEstimate` after each message_end that carries usage, which
+ * adjusts the per-character ratio toward the real value observed for this
+ * model. The calibration is bounded (0.1–0.6 chars/token) so a bad sample
+ * can't make the budget non-conservative. Until the first sample arrives,
+ * the safe chars/4 default is used.
+ *
  * Strategy:
  *   1. Always preserve the system prompt, the latest user task, and the
  *      latest assistant message.
@@ -16,8 +24,32 @@
  *   3. If still over budget, summarize the surviving tail into a single
  *      user message ("Earlier in this session: …").
  */
+/** Calibration ratio: chars per token. Starts at 4.0 (the classic heuristic)
+ *  and self-corrects toward the provider's reported usage. Bounded to
+ *  [MIN_RATIO, MAX_RATIO] = [2.0, 6.0] so a pathological sample (a tool dump
+ *  that tokenizes densely, or a sparse prompt) can't drive the budget into a
+ *  non-conservative regime. Real tokenizers sit around 3.5–4.5 chars/token. */
+const MIN_RATIO = 2.0;
+const MAX_RATIO = 6.0;
+let charsPerToken = 4.0;
+/**
+ * Calibrate the heuristic against provider-reported usage. Pass the actual
+ * input token count and the char length of the transcript that was sent.
+ * The ratio self-corrects toward the model's true tokenizer behavior.
+ */
+export function calibrateEstimate(usedChars, reportedInputTokens) {
+    if (reportedInputTokens <= 0 || usedChars <= 0)
+        return charsPerToken;
+    const newRatio = usedChars / reportedInputTokens;
+    charsPerToken = Math.max(MIN_RATIO, Math.min(MAX_RATIO, newRatio));
+    return charsPerToken;
+}
+/** Current chars/token ratio (after calibration, if any). */
+export function charsPerTokenRatio() {
+    return charsPerToken;
+}
 export function estimateTokens(s) {
-    return Math.ceil(s.length / 4);
+    return Math.ceil(s.length / charsPerToken);
 }
 export function estimateMessage(m) {
     let n = 4; // role + structural overhead
@@ -43,6 +75,23 @@ export function totalTokens(system, messages) {
         n += estimateMessage(m);
     return n;
 }
+/** Count the raw character length of a transcript for calibration. */
+export function transcriptCharLength(system, messages) {
+    let n = system ? system.length : 0;
+    for (const m of messages) {
+        for (const b of m.content) {
+            if (b.kind === 'text')
+                n += b.text.length;
+            else if (b.kind === 'tool_use')
+                n += b.name.length + JSON.stringify(b.input).length;
+            else if (b.kind === 'tool_result') {
+                const out = typeof b.output === 'string' ? b.output : JSON.stringify(b.output ?? '');
+                n += out.length + (b.name?.length ?? 0);
+            }
+        }
+    }
+    return n;
+}
 /** True if the input fits under the budget cap. */
 export function withinBudget(system, messages, budget) {
     const used = totalTokens(system, messages);

package/dist/events/bus.d.ts

@@ -4,6 +4,11 @@
  */
 import type { KlyroEvent } from './catalog.js';
 type Listener = (ev: KlyroEvent) => void;
+/** Cap for the retained event history. Long sessions emit a lot of
+ *  stream.delta / tool.result events; keeping them all grows memory
+ *  without bound. We retain a fixed recent window plus the structural
+ *  events (phase, verify, error) so replays stay coherent. */
+export declare const HISTORY_CAP = 10000;
 export declare class EventBus {
     private listeners;
     private history;

package/dist/events/bus.js

@@ -2,11 +2,21 @@
  * 3.1 — core/events emitter
  * In-memory pub/sub for KlyroEvents. Sync delivery, no buffering.
  */
+/** Cap for the retained event history. Long sessions emit a lot of
+ *  stream.delta / tool.result events; keeping them all grows memory
+ *  without bound. We retain a fixed recent window plus the structural
+ *  events (phase, verify, error) so replays stay coherent. */
+export const HISTORY_CAP = 10_000;
 export class EventBus {
     listeners = new Set();
     history = [];
     emit(ev) {
         this.history.push(ev);
+        if (this.history.length > HISTORY_CAP) {
+            // Cheap uniform prune: drop every other oldest event so a flood of
+            // deltas can't force a reallocation on each emit.
+            this.history = this.history.filter((_, i) => i % 2 === 1);
+        }
         for (const l of [...this.listeners]) {
             try {
                 l(ev);

package/dist/events/catalog.d.ts

@@ -1,6 +1,15 @@
 /**
  * 3.1 — KlyroEvent catalog (Appendix C)
  * Every observable action in the harness is a typed event.
+ *
+ * Reserved-future members (declared but intentionally unproduced — no
+ * emitter exists yet, so do not treat their absence as a bug):
+ * `subtask.tool_call`, `subtask.tool_result`.
+ * `subtask.progress` IS emitted (throttled: max 1 per child tool call,
+ * in-process children only; process-isolated children don't run the emitter).
+ * The orchestrator otherwise emits started/completed/failed/cancelled/
+ * timed_out/merged only; grep for emitters before assuming one of the
+ * reserved members fires.
  */
 export type KlyroEvent = {
     type: 'session.start';

package/dist/events/catalog.js

@@ -1,5 +1,14 @@
 /**
  * 3.1 — KlyroEvent catalog (Appendix C)
  * Every observable action in the harness is a typed event.
+ *
+ * Reserved-future members (declared but intentionally unproduced — no
+ * emitter exists yet, so do not treat their absence as a bug):
+ * `subtask.tool_call`, `subtask.tool_result`.
+ * `subtask.progress` IS emitted (throttled: max 1 per child tool call,
+ * in-process children only; process-isolated children don't run the emitter).
+ * The orchestrator otherwise emits started/completed/failed/cancelled/
+ * timed_out/merged only; grep for emitters before assuming one of the
+ * reserved members fires.
  */
 export {};

package/dist/index.js

@@ -349,7 +349,7 @@ async function main() {
     });
     program
         .command('chat [prompt]')
-        .description('Legacy streamed chat. Without a prompt, start an interactive REPL.')
+        .description('Legacy streamed chat. Without a prompt, start an interactive REPL. (deprecated: history truncation is approximate; prefer `klyro tui`)')
         .option('-s, --system <text>', 'System message', 'You are a helpful assistant.')
         .option('-m, --model <id>', 'Override the model (default: env KLYRO_MODEL)')
         .option('-t, --timeout <ms>', 'Request timeout in ms (default: env KLYRO_TIMEOUT_MS or 60000)', (v) => parsePositiveInt('-t/--timeout', v))
@@ -613,11 +613,78 @@ async function main() {
         }
     });
     mcp.command('add <name> <url>').description('Add MCP server').action(async (name) => { process.stdout.write(`added mcp ${name} (stub)\n`); });
+    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());
+        const spec = cfg.servers[name];
+        if (!spec) {
+            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 timer = setTimeout(() => {
+            process.stderr.write(`klyro: mcp probe ${name} timed out after 15s\n`);
+            process.exit(2);
+        }, 15_000);
+        try {
+            await client.connect();
+            const tools = await client.listTools();
+            const names = tools.map((t) => t.name);
+            process.stdout.write(`${name}: ${tools.length} tool(s)${names.length > 0 ? `: ${names.join(', ')}` : ''}\n`);
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`klyro: mcp probe ${name} failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+        finally {
+            clearTimeout(timer);
+            try {
+                await client.close();
+            }
+            catch { /* ignore */ }
+        }
+    });
     mcp.command('serve').description('Serve as MCP server').action(async () => { process.stdout.write('klyro mcp serve — exposing tools (stub)\n'); });
-    // 10.2 — Hooks / agents
-    program.command('hooks').description('List hooks (10.2)').action(async () => { process.stdout.write('hooks: SessionStart UserPromptSubmit PreToolUse PostToolUse (stub)\n'); });
-    program.command('agents [name]').description('List agents (10.2) or show one agent definition').action(async (name) => {
+    // 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') {
+            process.stderr.write(`klyro: unknown hooks command: ${cmd} (usage: klyro hooks [list])\n`);
+            process.exit(2);
+        }
+        const { loadHooks } = await import('./cli/hooks.js');
+        const hooks = loadHooks(process.cwd());
+        if (hooks.length === 0) {
+            process.stdout.write('hooks: none configured (.klyro/hooks.json, ~/.klyro/hooks.json)\n');
+            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');
+        // `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`);
+                process.exit(2);
+            }
+            const task = (taskParts ?? []).join(' ').trim();
+            if (!task) {
+                process.stderr.write('klyro: agents run requires a task (usage: klyro agents run <name> <task...>)\n');
+                process.exit(2);
+            }
+            const model = process.env.KLYRO_MODEL;
+            if (!model) {
+                process.stderr.write('klyro: KLYRO_MODEL is not set (or pass --model via klyro run)\n');
+                process.exit(2);
+            }
+            const code = await runOnce({ task, cwd: process.cwd(), model, agent: agentName });
+            process.exit(code);
+        }
         if (!name) {
             for (const a of BUILTIN_AGENTS)
                 process.stdout.write(`${a.id} — ${a.description}\n`);
@@ -642,7 +709,24 @@ async function main() {
         process.stdout.write(lines.join('\n') + '\n');
     });
     // 10.3 — Web / git workflows / SDK
-    program.command('commit').description('Create commit (10.3)').action(async () => { process.stdout.write('commit — conventional message (stub, use /commit)\n'); });
+    program
+        .command('commit')
+        .description('Commit staged changes with a conventional message (verification hooks always run)')
+        .option('--dry-run', 'Print the message + files without committing')
+        .option('--message <msg>', 'Summary for the conventional message (default: update <n> files)')
+        .option('--force-secret', 'Commit even if the staged diff looks like it contains a secret')
+        .action(async (opts) => {
+        const { runCommit } = await import('./cli/commit.js');
+        const globalYes = program.opts().yes ?? process.env.KLYRO_YES === '1';
+        const code = await runCommit({
+            cwd: process.cwd(),
+            yes: !!globalYes,
+            dryRun: !!opts.dryRun,
+            ...(opts.message !== undefined ? { message: opts.message } : {}),
+            forceSecret: !!opts.forceSecret,
+        });
+        process.exit(code);
+    });
     program.command('audit [session]').description('Verify audit chain (13.4)').action(async (session) => {
         if (!session) {
             process.stderr.write('klyro: audit requires a session id (usage: klyro audit <session>)\n');

package/dist/mcp/client.js

@@ -90,7 +90,7 @@ export class McpClient {
                         await this.request('initialize', {
                             protocolVersion: PROTOCOL_VERSION,
                             capabilities: {},
-                            clientInfo: { name: 'klyro', version: '1.0.1' },
+                            clientInfo: { name: 'klyro', version: '1.0.2' },
                         }, timeoutMs);
                         this.notify('notifications/initialized', {});
                         this.connected = true;

package/dist/mcp/registry.d.ts

@@ -1,21 +1,3 @@
-/**
- * P1 — MCP tool registration (r-11-17.md §3.1).
- *
- * Exposes MCP server tools through the {@link ToolRegistry} under
- * `mcp__<server>__<tool>` names. Security properties (non-negotiable):
- *
- *   1. Deny-by-default: `evaluateMcpPolicy` runs BEFORE any client I/O; a
- *      denied tool returns POLICY_DENIED without touching the subprocess.
- *   2. Redact-before-transcript: every success value AND error message passes
- *      through `redact()` before it can reach the model or trace.
- *   3. `requireApproval` servers add an ask-rule to the PolicyEngine so the
- *      runtime loop prompts before executing.
- *
- * Permission class: no code in src consumes `Tool.permission` (it is
- * write-only metadata today), so we pick the most restrictive class,
- * 'admin' — the same class as `spawn_agent`, since MCP tools execute
- * arbitrary external side effects (read/write/network) outside our control.
- */
 import { type McpClientLike } from './client.js';
 import { type McpServerSpec } from './config.js';
 import type { PolicyEngine } from '../policy/engine.js';

package/dist/mcp/registry.js

@@ -15,7 +15,18 @@
  * write-only metadata today), so we pick the most restrictive class,
  * 'admin' — the same class as `spawn_agent`, since MCP tools execute
  * arbitrary external side effects (read/write/network) outside our control.
+ *
+ * Debug capture: when `KLYRO_MCP_DEBUG=1` is set, every MCP tool success
+ * AND error ALSO writes the UNREDACTED raw JSON payload (pre-redaction,
+ * may contain secrets — handle accordingly) to
+ * `<configDir>/tool-output/mcp-<server>-<ts>.json` (mode 0600) and notes
+ * the path on stderr. `<configDir>` is `$KLYRO_CONFIG_DIR` when set,
+ * otherwise `~/.klyro`. Default off: with the flag unset (or any value
+ * other than `1`) no file is written and behaviour is unchanged.
  */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { McpClient, McpError } from './client.js';
 import { loadMcpServers } from './config.js';
 import { evaluateMcpPolicy } from './policy.js';
@@ -48,7 +59,39 @@ export function sanitizeMcpName(server, tool) {
 function errMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
-async function executeMcpTool(spec, toolDef, client, input, ctx) {
+/** Debug-capture filename disambiguator when Date.now() collides. */
+let mcpDebugCounter = 0;
+/**
+ * `KLYRO_MCP_DEBUG=1` capture: write the UNREDACTED raw payload to
+ * `<configDir>/tool-output/mcp-<server>-<ts>.json` (mode 0600) + a stderr
+ * note. Best-effort and synchronous — never throws into the tool path.
+ */
+function captureMcpDebug(server, tool, payload) {
+    if (process.env.KLYRO_MCP_DEBUG !== '1')
+        return;
+    try {
+        const base = process.env.KLYRO_CONFIG_DIR ?? path.join(os.homedir() || process.cwd(), '.klyro');
+        const dir = path.join(base, 'tool-output');
+        fs.mkdirSync(dir, { recursive: true });
+        const safe = server.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 32) || 'server';
+        let file = path.join(dir, `mcp-${safe}-${Date.now()}.json`);
+        if (fs.existsSync(file)) {
+            mcpDebugCounter += 1;
+            file = path.join(dir, `mcp-${safe}-${Date.now()}-${mcpDebugCounter}.json`);
+        }
+        fs.writeFileSync(file, JSON.stringify({ server, tool, payload }, null, 2), { mode: 0o600 });
+        try {
+            process.stderr.write(`klyro: mcp debug captured ${server}/${tool} -> ${file}\n`);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    catch {
+        /* best-effort only */
+    }
+}
+async function executeMcpTool(server, spec, toolDef, client, input, ctx) {
     try {
         // (1) Deny-by-default — runs BEFORE any client I/O.
         const decision = evaluateMcpPolicy(spec.policy, toolDef.name);
@@ -67,16 +110,20 @@ async function executeMcpTool(spec, toolDef, client, input, ctx) {
             // (3) Typed server failures keep their code; everything else is TOOL_ERROR.
             // Redact BEFORE the message can reach the model/trace.
             if (err instanceof McpError) {
+                captureMcpDebug(server, toolDef.name, { code: err.code, message: err.message, details: err.details });
                 return { ok: false, error: { code: err.code, message: redact(err.message) } };
             }
+            captureMcpDebug(server, toolDef.name, { message: errMessage(err) });
             return { ok: false, error: { code: 'TOOL_ERROR', message: redact(errMessage(err)) } };
         }
         // (4) Server-reported error → TOOL_ERROR, redacted, bounded.
         if (res.isError) {
+            captureMcpDebug(server, toolDef.name, res.raw);
             return { ok: false, error: { code: 'TOOL_ERROR', message: redact(res.text).slice(0, 2000) } };
         }
         // (5) Success — redact BEFORE the value reaches the model/trace, then
         // truncate to a bounded size with a marker.
+        captureMcpDebug(server, toolDef.name, res.raw);
         const redacted = redact(res.text);
         if (redacted.length > MCP_SUCCESS_MAX_CHARS) {
             return {
@@ -177,7 +224,7 @@ export async function registerMcpServers(cfg, opts) {
                     // 'admin': most restrictive class — MCP tools run arbitrary
                     // external side effects; nothing in src reads this field yet.
                     permission: 'admin',
-                    execute: (input, ctx) => executeMcpTool(boundSpec, boundDef, boundClient, input, ctx),
+                    execute: (input, ctx) => executeMcpTool(server, boundSpec, boundDef, boundClient, input, ctx),
                 });
                 registry.register(tool);
                 registered.push(name);

package/dist/policy/engine.d.ts

@@ -84,6 +84,22 @@ export declare class PolicyEngine {
 /** Builtin set of rules. Order matters: first match wins. */
 export declare function builtinRules(): PolicyRule[];
 export declare function matchesGlobRule(call: ToolCallLike, rule: string): boolean;
+/** Branches that `git push` must never target without an explicit opt-out. */
+export declare const PROTECTED_BRANCHES: string[];
+/** Matches `push` with a protected branch name later on the same line. */
+export declare const PROTECTED_PUSH_RE: RegExp;
+/**
+ * True when the command is a `git push` with NO ref/positional args
+ * (e.g. `git push`, `git push -f`) — i.e. it pushes whatever is checked
+ * out. `git push origin feature` is explicit, not bare.
+ */
+export declare function isBareGitPush(cmd: string): boolean;
+/**
+ * Resolve the currently checked-out branch via `git branch --show-current`.
+ * Returns null on any failure (not a repo, git missing) — callers treat
+ * null as "unknown" and allow the normal policy flow to continue.
+ */
+export declare function currentGitBranch(cwd: string): string | null;
 /** Hard-deny for obviously destructive shell patterns. */
 export declare const shellDenyRule: PolicyRule;
 /** Allowlist for shell — exact or prefix. Anything not in the list asks. */