klyro 1.0.16 → 1.0.18

package/dist/agent/anthropic-adapter.js

@@ -17,6 +17,8 @@
  */
 import { assertSafeBaseURL } from '../chat.js';
 import { parseRetryAfterMs } from './provider-adapter.js';
+import { estimateTokens } from '../context/tokenizer.js';
+import { proxiedFetch } from '../shared/proxy.js';
 const DEFAULT_VERSION = '2023-06-01';
 const DEFAULT_TIMEOUT_MS = 120_000;
 export const PROMPT_CACHING_BETA = 'prompt-caching-2024-07-31';
@@ -40,7 +42,7 @@ export function anthropicAdapter(opts) {
     const betas = [...(opts.betas ?? [])];
     if (promptCache && !betas.includes(PROMPT_CACHING_BETA))
         betas.push(PROMPT_CACHING_BETA);
-    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const fetchImpl = opts.fetchImpl ?? proxiedFetch;
     if (!fetchImpl) {
         throw new Error('anthropicAdapter: no fetch available — pass opts.fetchImpl or run on Node 18+');
     }
@@ -52,6 +54,29 @@ export function anthropicAdapter(opts) {
                 fetchImpl, version, authHeader, betas, promptCache,
             });
         },
+        // 2.1 — capability discovery via the Anthropic Models API.
+        // Returns [] when unavailable (callers fall back to configured ids).
+        async listModels() {
+            try {
+                const headers = { 'anthropic-version': version };
+                if (authHeader === 'x-api-key')
+                    headers['x-api-key'] = opts.apiKey;
+                else
+                    headers['Authorization'] = `Bearer ${opts.apiKey}`;
+                const res = await fetchImpl(`${baseURL}/v1/models`, { headers });
+                if (!res.ok)
+                    return [];
+                const json = (await res.json());
+                const ids = Array.isArray(json.data) ? json.data.map((m) => m.id).filter((id) => typeof id === 'string' && id.length > 0) : [];
+                return [...new Set(ids)];
+            }
+            catch {
+                return [];
+            }
+        },
+        countTokens(text) {
+            return estimateTokens(text);
+        },
     };
 }
 /**

package/dist/agent/provider-adapter.d.ts

@@ -68,11 +68,17 @@ export interface CallRequest {
     tools: ToolDefinition[];
     maxTokens?: number;
     temperature?: number;
+    /** Reasoning effort for reasoning models ( OpenAI `reasoning_effort` ); adapters that lack the concept ignore it. */
+    reasoningEffort?: 'low' | 'medium' | 'high';
     signal?: AbortSignal;
 }
 export interface ProviderAdapter {
     readonly id: string;
     stream(req: CallRequest): AsyncIterable<StreamEvent>;
+    /** Optional capability discovery: model ids (2.1). Absent = unknown, use configured ids. */
+    listModels?(): Promise<string[]>;
+    /** Optional local token estimate (2.1). Absent = caller estimates. */
+    countTokens?(text: string): number | Promise<number>;
 }
 export interface HttpAdapterOptions {
     baseURL: string;
@@ -110,6 +116,7 @@ interface ChatCompletionsRequest {
     }>;
     max_tokens?: number;
     temperature?: number;
+    reasoning_effort?: 'low' | 'medium' | 'high';
     stream: true;
 }
 /**

package/dist/agent/provider-adapter.js

@@ -11,6 +11,8 @@
  * runtime loop sees one shape regardless of provider quirks.
  */
 import { redact } from '../policy/secret-redactor.js';
+import { estimateTokens } from '../context/tokenizer.js';
+import { proxiedFetch } from '../shared/proxy.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
 /**
  * Parse a `Retry-After` response header value into milliseconds.
@@ -157,6 +159,8 @@ export function buildChatCompletionsBody(req) {
         body.max_tokens = req.maxTokens;
     if (typeof req.temperature === 'number')
         body.temperature = req.temperature;
+    if (req.reasoningEffort)
+        body.reasoning_effort = req.reasoningEffort;
     if (req.tools.length) {
         body.tools = req.tools.map((t) => ({
             type: 'function',
@@ -166,13 +170,34 @@ export function buildChatCompletionsBody(req) {
     return body;
 }
 export function httpChatAdapter(opts) {
-    const fetchImpl = opts.fetchImpl ?? fetch;
+    const fetchImpl = opts.fetchImpl ?? proxiedFetch;
     const url = `${opts.baseURL.replace(/\/+$/, '')}/chat/completions`;
     return {
         id: 'http-chat',
         stream(req) {
             return streamChatCompletions(url, opts, req, fetchImpl);
         },
+        // 2.1 — capability discovery: list model ids via OpenAI /models.
+        // Returns [] when the endpoint doesn't serve a model list (not an
+        // error: callers fall back to configured ids).
+        async listModels() {
+            try {
+                const res = await fetchImpl(`${opts.baseURL.replace(/\/+$/, '')}/models`, {
+                    headers: opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {},
+                });
+                if (!res.ok)
+                    return [];
+                const json = (await res.json());
+                const ids = Array.isArray(json.data) ? json.data.map((m) => m.id).filter((id) => typeof id === 'string' && id.length > 0) : [];
+                return [...new Set(ids)];
+            }
+            catch {
+                return [];
+            }
+        },
+        countTokens(text) {
+            return estimateTokens(text);
+        },
     };
 }
 async function* streamChatCompletions(url, opts, req, fetchImpl) {

package/dist/agent/runtime.d.ts

@@ -83,6 +83,7 @@ export interface RunOptions {
     maxTimeMs?: number;
     maxTokens?: number;
     temperature?: number;
+    reasoningEffort?: 'low' | 'medium' | 'high';
     signal?: AbortSignal;
     nonInteractive: boolean;
     /**
@@ -157,6 +158,12 @@ export interface RunOptions {
         allowedPaths?: readonly string[];
         model?: string;
     };
+    /**
+     * Root sandbox extensions (--add-dir): extra resolvable roots for file
+     * tools, merged with cwd. Child scopes (parentContext.allowedPaths) still
+     * narrow further when present.
+     */
+    allowedPaths?: readonly string[];
     /**
      * Delegation bridge (P0). Present on the root run so the model can call
      * spawn_agent / task_list / task_get. The tool layer reads it from the
@@ -264,6 +271,13 @@ export type RuntimeEvent = {
     kind: 'model_override';
     requested: string;
     effective: string;
+} | {
+    kind: 'turn.summary';
+    turn: number;
+    toolCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    durationMs: number;
 };
 export interface RunResult {
     status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked' | 'stuck';

package/dist/agent/runtime.js

@@ -119,6 +119,8 @@ export async function run(opts, deps) {
         }
     };
     let steps = 0;
+    // 4.5c — per-turn start time for turn.summary durationMs.
+    let turnStartMs = Date.now();
     let lastRemindTurn = 0;
     let toolCallCount = 0;
     let finalText = '';
@@ -223,18 +225,6 @@ export async function run(opts, deps) {
     const sessionId = opts.persist?.sessionId;
     // 6.1 baseline cache per HEAD — capture before first edit
     let baselinePrimed = false;
-    async function primeBaseline() {
-        if (baselinePrimed)
-            return;
-        baselinePrimed = true;
-        const cmd = opts.verify?.command ?? detectVerifyCommand(opts.cwd);
-        if (!cmd)
-            return;
-        try {
-            await ensureBaseline(opts.cwd, cmd);
-        }
-        catch { /* ignore */ }
-    }
     async function checkpoint(msg, obs) {
         if (!store || !sessionId)
             return;
@@ -259,6 +249,23 @@ export async function run(opts, deps) {
             // best-effort — don't crash runtime on persistence failure
         }
     }
+    /**
+     * 4.5c — end-of-turn summary: emit a turn.summary event (cumulative
+     * toolCalls + token counts, per-turn durationMs) and record a compact
+     * one-line summary in the transcript.
+     */
+    async function emitTurnSummary() {
+        const durationMs = Date.now() - turnStartMs;
+        emit?.({ kind: 'turn.summary', turn: steps, toolCalls: toolCallCount, inputTokens: usage.input, outputTokens: usage.output, durationMs });
+        const msg = {
+            role: 'user',
+            content: [text(`[turn ${steps} summary] ${toolCallCount} tool call(s), ${usage.input} in / ${usage.output} out tokens, ${durationMs}ms`)],
+        };
+        transcript.push(msg);
+        await checkpoint(msg);
+        // Invalidate token cache since transcript changed
+        tokenCache = { lastRef: null, lastSystem: undefined, lastCount: 0 };
+    }
     // Persist initial user message
     if (store && sessionId && transcript.length > 0) {
         // Fire-and-forget initial checkpoint (don't await to block loop start)
@@ -319,6 +326,11 @@ export async function run(opts, deps) {
             // Abort cascade (fix: background shells must not outlive the run).
             const killed = killAllJobs();
             emitKlyro({ type: 'abort', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', reason: killed.length > 0 ? `aborted by operator (${killed.length} background job(s) killed)` : 'aborted by operator' });
+            // 2.4 — explicit interrupted marker: partial output stays labeled in
+            // the transcript so resume/replay never mistakes it for final text.
+            const interruptedNote = { role: 'user', content: [text('[system note] Interrupted by user — output above is partial and preserved.')] };
+            transcript.push(interruptedNote);
+            await checkpoint(interruptedNote);
             if (store && sessionId) {
                 try {
                     await store.setStatus(sessionId, 'aborted', finalText);
@@ -329,6 +341,7 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined, phase: 'blocked' };
         }
         steps++;
+        turnStartMs = Date.now();
         // 8.4 — stale-todo reminder: every 20 turns, re-inject pending plan
         // items from `.klyro/plans/todos.json` (written by todo_write) so a
         // long run cannot silently drop its checklist. Best-effort + tiny.
@@ -399,23 +412,22 @@ export async function run(opts, deps) {
             tools: toolDefinitions(deps.registry),
             ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
             ...(typeof opts.temperature === 'number' ? { temperature: opts.temperature } : {}),
+            ...(opts.reasoningEffort ? { reasoningEffort: opts.reasoningEffort } : {}),
             ...(opts.signal ? { signal: opts.signal } : {}),
         };
         const events = activeAdapter.stream(req);
         let textBuf = '';
         // Thinking is ephemeral: streamed to the UI live, never stored in the
         // transcript, and cleared when the turn's answer completes.
-        let thinkingBuf = '';
         const pendingToolCalls = new Map();
-        let lastFinishReason;
         // Set when this step's request must be re-issued after overflow recovery.
         let overflowRetryPending = false;
         // Set when a terminal provider error consumed a failover adapter — the
         // step is re-issued against the next adapter without consuming budget.
         let failoverPending = false;
-        let failoverFrom = '';
-        let failoverTo = '';
-        let failoverReason = '';
+        let failoverFrom;
+        let failoverTo;
+        let failoverReason;
         for await (const ev of events) {
             if (opts.signal?.aborted)
                 break outer;
@@ -424,7 +436,6 @@ export async function run(opts, deps) {
                 emit?.({ kind: 'text_delta', text: ev.text });
             }
             else if (ev.kind === 'thinking_delta') {
-                thinkingBuf += ev.text;
                 emit?.({ kind: 'thinking_delta', text: ev.text });
             }
             else if (ev.kind === 'tool_call_start') {
@@ -441,7 +452,6 @@ export async function run(opts, deps) {
                 // tool_calls are accumulated; finalization happens after stream.
             }
             else if (ev.kind === 'message_end') {
-                lastFinishReason = ev.finishReason;
                 if (ev.usage) {
                     usage.input += ev.usage.input;
                     usage.output += ev.usage.output;
@@ -553,9 +563,7 @@ export async function run(opts, deps) {
         if (failoverPending) {
             failoverPending = false;
             textBuf = '';
-            thinkingBuf = '';
             pendingToolCalls.clear();
-            lastFinishReason = undefined;
             steps--;
             emit?.({ kind: 'step_end', step: steps + 1 });
             continue outer;
@@ -613,6 +621,10 @@ export async function run(opts, deps) {
             emit?.({ kind: 'aborted' });
             const killed = killAllJobs();
             emitKlyro({ type: 'abort', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', reason: killed.length > 0 ? `aborted by operator (${killed.length} background job(s) killed)` : 'aborted by operator' });
+            // 2.4 — explicit interrupted marker (see loop-top abort).
+            const interruptedNote = { role: 'user', content: [text('[system note] Interrupted by user — output above is partial and preserved.')] };
+            transcript.push(interruptedNote);
+            await checkpoint(interruptedNote);
             if (store && sessionId) {
                 try {
                     await store.setStatus(sessionId, 'aborted', finalText);
@@ -623,6 +635,9 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
         }
         if (finalizedCalls.length === 0) {
+            // 4.5c — the turn completed (final text, malformed-only, or
+            // stop-hook continuation): summarize before the verify branching.
+            await emitTurnSummary();
             // Steerable stop: a stop hook asked for one more turn instead of
             // completing. Consumed once per verdict, max 3 per run.
             if (stopCont !== null && stopContUsed < 3) {
@@ -907,6 +922,7 @@ export async function run(opts, deps) {
                 : {}),
             agentDepth: opts.parentContext?.depth ?? 0,
             agentMaxDepth: opts.parentContext?.maxDepth ?? 1,
+            ...(opts.allowedPaths ? { agentAllowedPaths: opts.allowedPaths } : {}),
             ...(opts.parentContext?.allowedTools ? { agentAllowedTools: opts.parentContext.allowedTools } : {}),
             ...(opts.parentContext?.allowedPaths ? { agentAllowedPaths: opts.parentContext.allowedPaths } : {}),
             ...(opts.parentContext?.model ?? opts.model ? { agentModel: opts.parentContext?.model ?? opts.model } : {}),
@@ -1058,6 +1074,18 @@ export async function run(opts, deps) {
                     }
                 }
             }
+            // 4.5a — shell/git mutations bypass file-change inference: take a
+            // pre-execution snapshot so the turn stays restorable. Best-effort.
+            if (call.name === 'shell_exec' || call.name.startsWith('git_')) {
+                try {
+                    const { snapshot } = await import('../checkpoints/store.js');
+                    await snapshot(opts.cwd, [...fileEditCounts.keys()].slice(-20), {
+                        ...(sessionId !== undefined ? { sessionId } : {}),
+                        eventId: call.id,
+                    });
+                }
+                catch { /* ignore */ }
+            }
             let obs;
             try {
                 obs = await deps.registry.execute(call.name, call.input, toolCtx);
@@ -1145,7 +1173,10 @@ export async function run(opts, deps) {
                     // 4.5 — checkpoint snapshot after each mutation
                     try {
                         const { snapshot } = await import('../checkpoints/store.js');
-                        await snapshot(opts.cwd, [fileChanged.path]);
+                        await snapshot(opts.cwd, [fileChanged.path], {
+                            ...(sessionId !== undefined ? { sessionId } : {}),
+                            eventId: call.id,
+                        });
                     }
                     catch { /* ignore */ }
                     // 5.2 file edit count
@@ -1258,6 +1289,8 @@ export async function run(opts, deps) {
                     break;
             }
         }
+        // 4.5c — the tool turn completed: summarize (cumulative counts).
+        await emitTurnSummary();
         // P0 — drain finished sub-agent completions into parent visibility.
         // drainCompletions is OPTIONAL on the bridge — guarded with `?.` so
         // older bridges without it simply yield nothing.
@@ -1308,6 +1341,10 @@ export async function run(opts, deps) {
     }
     if (opts.signal?.aborted) {
         emit?.({ kind: 'aborted' });
+        // 2.4 — explicit interrupted marker (see loop-top abort).
+        const interruptedNote = { role: 'user', content: [text('[system note] Interrupted by user — output above is partial and preserved.')] };
+        transcript.push(interruptedNote);
+        await checkpoint(interruptedNote);
         if (store && sessionId) {
             try {
                 await store.setStatus(sessionId, 'aborted', finalText);

package/dist/chat.js

@@ -20,6 +20,16 @@
  */
 /** Default request timeout: 60s. */
 const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Legacy output flows through the shared terminal renderer (3.1): all
+ * human output leaves via the renderer module, which also sanitizes
+ * control sequences out of model text.
+ */
+import { TerminalRenderer, writeStdoutDrained } from './renderers/terminal.js';
+const renderer = new TerminalRenderer();
+function frame(text) {
+    renderer.handle({ type: 'stream.delta', ts: Date.now(), sessionId: 'legacy-chat', text });
+}
 /** Max bytes of an error response body we will print. */
 const MAX_ERROR_BODY_BYTES = 4_000;
 /** Strip a trailing slash so we can append /chat/completions cleanly. */
@@ -187,7 +197,7 @@ export async function streamToStdout(body, signal) {
     const reader = body.getReader();
     const decoder = new TextDecoder('utf-8');
     let buf = '';
-    process.stdout.write('\n');
+    frame('\n');
     try {
         while (true) {
             if (signal.aborted)
@@ -209,7 +219,7 @@ export async function streamToStdout(body, signal) {
                         continue;
                     const data = line.slice(5).trim();
                     if (data === '[DONE]') {
-                        process.stdout.write('\n');
+                        frame('\n');
                         return;
                     }
                     // Handle case where data was split across chunks and reassembled as event
@@ -224,7 +234,7 @@ export async function streamToStdout(body, signal) {
                     }
                     const text = parsed.choices?.[0]?.delta?.content;
                     if (text) {
-                        if (!await writeWithBackpressure(text, signal)) {
+                        if (!await writeStdoutDrained(text, signal)) {
                             try {
                                 await reader.cancel();
                             }
@@ -246,7 +256,7 @@ export async function streamToStdout(body, signal) {
                         continue;
                     const data = line.slice(5).trim();
                     if (data === '[DONE]') {
-                        process.stdout.write('\n');
+                        frame('\n');
                         return;
                     }
                     if (data === '')
@@ -255,7 +265,7 @@ export async function streamToStdout(body, signal) {
                         const parsed = JSON.parse(data);
                         const text = parsed.choices?.[0]?.delta?.content;
                         if (text) {
-                            if (!await writeWithBackpressure(text, signal)) {
+                            if (!await writeStdoutDrained(text, signal)) {
                                 try {
                                     await reader.cancel();
                                 }
@@ -270,7 +280,7 @@ export async function streamToStdout(body, signal) {
                 }
             }
         }
-        process.stdout.write('\n');
+        frame('\n');
     }
     finally {
         try {
@@ -281,56 +291,6 @@ export async function streamToStdout(body, signal) {
         }
     }
 }
-/**
- * Write to stdout and wait for the drain event if the buffer is full.
- * Returns false if stdout has been closed (e.g. piped to `head`).
- * Respects abort signal — resolves false if aborted while waiting.
- */
-function writeWithBackpressure(chunk, signal) {
-    return new Promise((resolve) => {
-        if (signal?.aborted) {
-            resolve(false);
-            return;
-        }
-        if (!process.stdout.write(chunk)) {
-            let settled = false;
-            const cleanup = () => {
-                process.stdout.off('drain', onDrain);
-                process.stdout.off('error', onError);
-                if (signal)
-                    signal.removeEventListener('abort', onAbort);
-            };
-            const onDrain = () => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                resolve(true);
-            };
-            const onError = () => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                resolve(false);
-            };
-            const onAbort = () => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                resolve(false);
-            };
-            process.stdout.once('drain', onDrain);
-            process.stdout.once('error', onError);
-            if (signal)
-                signal.addEventListener('abort', onAbort, { once: true });
-        }
-        else {
-            resolve(true);
-        }
-    });
-}
 /**
  * Read up to `max` bytes from a response body. Used for error responses where
  * we want to surface the cause without risking OOM on a misbehaving server.

package/dist/checkpoints/store.d.ts

@@ -10,7 +10,21 @@
  * enforced at the trace/persist boundaries (TraceWriter, SessionStore)
  * instead of here.
  */
-export declare function snapshot(cwd: string, files: string[]): Promise<string>;
+/** Optional provenance recorded into a checkpoint's .meta.json. */
+export interface SnapshotOptions {
+    sessionId?: string;
+    eventId?: string;
+}
+/** Checkpoint meta on disk — sessionId/eventId are absent on old metas. */
+export interface CheckpointMeta {
+    id: string;
+    files: string[];
+    missing: string[];
+    ts: number;
+    sessionId?: string;
+    eventId?: string;
+}
+export declare function snapshot(cwd: string, files: string[], opts?: SnapshotOptions): Promise<string>;
 export declare function listCheckpoints(cwd: string): Promise<string[]>;
 export interface CheckpointInfo {
     /** 1-based index from the latest (1 = newest, like `undo(n)`). */

package/dist/checkpoints/store.js

@@ -55,7 +55,7 @@ function containedPath(cwd, base, rel) {
         return null;
     return out;
 }
-export async function snapshot(cwd, files) {
+export async function snapshot(cwd, files, opts) {
     const dir = ckptDir(cwd);
     await fs.mkdir(dir, { recursive: true });
     lockDown(dir, 0o700);
@@ -92,7 +92,12 @@ export async function snapshot(cwd, files) {
     // leaves a truncated .meta.json that undo() then trusts).
     const metaPath = path.join(dest, '.meta.json');
     const metaTmp = `${metaPath}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
-    await fs.writeFile(metaTmp, JSON.stringify({ id, files: kept, missing, ts: Date.now() }, null, 2));
+    const meta = { id, files: kept, missing, ts: Date.now() };
+    if (opts?.sessionId !== undefined)
+        meta.sessionId = opts.sessionId;
+    if (opts?.eventId !== undefined)
+        meta.eventId = opts.eventId;
+    await fs.writeFile(metaTmp, JSON.stringify(meta, null, 2));
     lockDown(metaTmp, 0o600);
     await fsyncFile(metaTmp);
     try {

package/dist/cli/args.d.ts

@@ -1 +1,8 @@
 export declare function parsePositiveInt(name: string, v: string): number;
+/**
+ * 5.3 — `--auto-answer <text>` wiring. `ask_user` honors
+ * `KLYRO_AUTO_ANSWER` in headless runs; `klyro run` / `klyro eval` set it
+ * from the flag via this helper before the run starts (explicit env wins
+ * when the flag is omitted). Exported for tests.
+ */
+export declare function applyAutoAnswer(value: string | undefined): void;

package/dist/cli/args.js

@@ -12,3 +12,13 @@ export function parsePositiveInt(name, v) {
     }
     return n;
 }
+/**
+ * 5.3 — `--auto-answer <text>` wiring. `ask_user` honors
+ * `KLYRO_AUTO_ANSWER` in headless runs; `klyro run` / `klyro eval` set it
+ * from the flag via this helper before the run starts (explicit env wins
+ * when the flag is omitted). Exported for tests.
+ */
+export function applyAutoAnswer(value) {
+    if (value !== undefined)
+        process.env.KLYRO_AUTO_ANSWER = value;
+}

package/dist/cli/completion.js

@@ -19,9 +19,6 @@ const COMMAND_FLAGS = {
     completion: ['bash', 'zsh', 'fish', 'powershell'],
     resume: ['-m', '--model', '--max-steps'],
 };
-function flagsFor(cmd) {
-    return [...GLOBAL_FLAGS, ...(COMMAND_FLAGS[cmd] ?? [])];
-}
 function bashScript() {
     const cmdCases = Object.entries(COMMAND_FLAGS)
         .map(([c, fs]) => `      ${c}) opts="${fs.join(' ')}" ;;`)

package/dist/cli/doctor.d.ts

@@ -3,6 +3,19 @@
  * Runs quick diagnostics: node version, config, provider reachability,
  * persistence dir, git, tools.
  */
+/**
+ * Pure byte interpreter for `doctor --keys` (unit-tested): names what a
+ * terminal delivered so broken arrow/paste/scroll input becomes provable
+ * fact instead of guesswork. Covers arrows, paging/home/end, Ctrl codes,
+ * bracketed-paste markers, and SGR/X10 mouse sequences.
+ */
+export declare function describeKeyBytes(chunk: Buffer): string;
+/**
+ * Interactive key probe: raw-mode stdin echo of every chunk with its
+ * meaning. Proves what THIS terminal delivers for arrows, Ctrl+P/N,
+ * paste, and wheel — run it when TUI input misbehaves.
+ */
+export declare function runKeysProbe(): Promise<number>;
 export declare function runDoctor(opts?: {
     json?: boolean;
     cwd?: string;