@visorcraft/idlehands 2.2.4 → 2.2.7

package/dist/agent.js

@@ -14,7 +14,11 @@ import { buildDefaultSystemPrompt } from './agent/prompt-builder.js';
 import { LeakDetector } from './security/leak-detector.js';
 import { PromptGuard } from './security/prompt-guard.js';
 import { ResponseCache } from './agent/response-cache.js';
+import { resilientCall } from './agent/resilient-provider.js';
 import { ToolLoopGuard } from './agent/tool-loop-guard.js';
+import { CaptureManager } from './agent/capture.js';
+import { ClientPool } from './agent/client-pool.js';
+import { ConversationBranch } from './agent/conversation-branch.js';
 import { isLspTool, isMutationTool, isReadOnlyTool, planModeSummary } from './agent/tool-policy.js';
 import { buildToolsSchema } from './agent/tools-schema.js';
 import { OpenAIClient } from './client.js';
@@ -31,6 +35,8 @@ import { MCPManager } from './mcp.js';
 import { BASE_MAX_TOKENS, deriveContextWindow, deriveGenerationParams, supportsVisionModel, } from './model-customization.js';
 import { ReplayStore } from './replay.js';
 import { checkExecSafety, checkPathSafety } from './safety.js';
+import { decideTurnRoute } from './routing/turn-router.js';
+import { RouteHysteresis } from './routing/hysteresis.js';
 import { normalizeApprovalMode } from './shared/config-utils.js';
 import { collectSnapshot } from './sys/context.js';
 import { ToolError, ValidationError } from './tools/tool-error.js';
@@ -217,13 +223,19 @@ export async function createSession(opts) {
     const mcpHasEnabledTools = (mcpManager?.listTools().length ?? 0) > 0;
     const mcpLazySchemaMode = Boolean(mcpManager && mcpHasEnabledTools);
     let mcpToolsLoaded = !mcpLazySchemaMode;
-    const getToolsSchema = () => buildToolsSchema({
+    const routeHysteresis = new RouteHysteresis({
+        minDwell: cfg.routing?.hysteresisMinDwell ?? 2,
+        enabled: cfg.routing?.hysteresis !== false,
+    });
+    const conversationBranch = new ConversationBranch();
+    const getToolsSchema = (slimFast) => buildToolsSchema({
         activeVaultTools,
         passiveVault: !activeVaultTools && vaultEnabled && vaultMode === 'passive',
         sysMode: cfg.mode === 'sys',
         lspTools: lspManager?.hasServers() === true,
         mcpTools: mcpToolsLoaded ? (mcpManager?.getEnabledToolSchemas() ?? []) : [],
         allowSpawnTask: spawnTaskEnabled,
+        slimFast,
     });
     const vault = vaultEnabled
         ? (opts.runtime?.vault ??
@@ -392,6 +404,27 @@ export async function createSession(opts) {
             console.warn(`[warn] sys-eager snapshot failed: ${e?.message ?? e}`);
         }
     }
+    const buildCompactSessionMeta = () => {
+        const caps = [];
+        if (vaultEnabled)
+            caps.push('vault');
+        if (lspManager?.hasServers())
+            caps.push('lsp');
+        if (mcpManager)
+            caps.push('mcp');
+        if (spawnTaskEnabled)
+            caps.push('subagents');
+        const lines = [
+            `[cwd: ${cfg.dir}]`,
+            `[harness: ${harness.id}]`,
+            '[fast-lane prelude: concise response by default; ask for details if needed.]',
+            caps.length ? `[optional capabilities: ${caps.join(', ')}]` : '',
+        ].filter(Boolean);
+        const maxChars = cfg.routing?.fastCompactPreludeMaxChars ?? 320;
+        const joined = lines.join('\n');
+        return joined.length > maxChars ? `${joined.slice(0, maxChars - 1)}…` : joined;
+    };
+    const compactSessionMeta = buildCompactSessionMeta();
     const defaultSystemPromptBase = SYSTEM_PROMPT;
     let activeSystemPromptBase = (cfg.system_prompt_override ?? '').trim() || defaultSystemPromptBase;
     let systemPromptOverridden = (cfg.system_prompt_override ?? '').trim().length > 0;
@@ -429,6 +462,8 @@ export async function createSession(opts) {
         lastEditedPath = undefined;
         initialConnectionProbeDone = false;
         mcpToolsLoaded = !mcpLazySchemaMode;
+        routeHysteresis.reset();
+        conversationBranch.reset();
     };
     const restore = (next) => {
         if (!Array.isArray(next) || next.length < 2) {
@@ -1056,6 +1091,7 @@ export async function createSession(opts) {
     const ppSamples = [];
     const tgSamples = [];
     let lastTurnMetrics;
+    let lastTurnDebug;
     let lastServerHealth;
     let lastToolLoopStats = {
         totalHistory: 0,
@@ -1074,29 +1110,114 @@ export async function createSession(opts) {
         },
     };
     let lastModelsProbeMs = 0;
-    const capturesDir = path.join(stateDir(), 'captures');
-    let captureEnabled = false;
-    let capturePath;
-    let lastCaptureRecord = null;
-    const defaultCapturePath = () => {
-        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-        return path.join(capturesDir, `${stamp}.jsonl`);
+    const capture = new CaptureManager(stateDir());
+    const normalizeEndpoint = (endpoint) => endpoint.trim().replace(/\/+$/, '');
+    const clientPool = new ClientPool({
+        primary: client,
+        primaryEndpoint: cfg.endpoint,
+        apiKey: opts.apiKey,
+        cfg,
+        capture,
+        ClientCtor: OpenAIClient,
+    });
+    // Thin wrapper used by setEndpoint when primary client is replaced.
+    const applyClientRuntimeOptions = (target) => {
+        if (typeof target.setVerbose === 'function')
+            target.setVerbose(cfg.verbose);
+        if (typeof cfg.response_timeout === 'number' && cfg.response_timeout > 0)
+            target.setResponseTimeout(cfg.response_timeout);
+        if (typeof target.setConnectionTimeout === 'function' && typeof cfg.connection_timeout === 'number' && cfg.connection_timeout > 0)
+            target.setConnectionTimeout(cfg.connection_timeout);
+        if (typeof target.setInitialConnectionCheck === 'function' && typeof cfg.initial_connection_check === 'boolean')
+            target.setInitialConnectionCheck(cfg.initial_connection_check);
+        if (typeof target.setInitialConnectionProbeTimeout === 'function' && typeof cfg.initial_connection_timeout === 'number' && cfg.initial_connection_timeout > 0)
+            target.setInitialConnectionProbeTimeout(cfg.initial_connection_timeout);
     };
-    const appendCaptureRecord = async (record, outPath) => {
-        await fs.mkdir(path.dirname(outPath), { recursive: true });
-        await fs.appendFile(outPath, JSON.stringify(record) + '\n', 'utf8');
+    const attachCaptureHook = (target) => {
+        if (typeof target.setExchangeHook !== 'function')
+            return;
+        target.setExchangeHook(capture.createExchangeHook());
     };
-    const wireCaptureHook = () => {
-        if (typeof client.setExchangeHook !== 'function')
+    const getClientForEndpoint = (endpoint) => clientPool.getForEndpoint(endpoint);
+    let runtimeRoutingModules = null;
+    let runtimeRoutingUnavailable = false;
+    let runtimeModelIdsCache = null;
+    const loadRuntimeRoutingModules = async () => {
+        if (runtimeRoutingUnavailable)
+            return null;
+        if (runtimeRoutingModules)
+            return runtimeRoutingModules;
+        try {
+            const [planner, executor, store] = await Promise.all([
+                import('./runtime/planner.js'),
+                import('./runtime/executor.js'),
+                import('./runtime/store.js'),
+            ]);
+            runtimeRoutingModules = { planner, executor, store };
+            return runtimeRoutingModules;
+        }
+        catch {
+            runtimeRoutingUnavailable = true;
+            return null;
+        }
+    };
+    const loadRuntimeModelIds = async () => {
+        if (runtimeModelIdsCache)
+            return runtimeModelIdsCache;
+        const mods = await loadRuntimeRoutingModules();
+        if (!mods) {
+            runtimeModelIdsCache = new Set();
+            return runtimeModelIdsCache;
+        }
+        try {
+            const runtimes = await mods.store.loadRuntimes();
+            runtimeModelIdsCache = new Set(runtimes.models.filter((m) => m.enabled !== false).map((m) => m.id));
+            return runtimeModelIdsCache;
+        }
+        catch {
+            runtimeModelIdsCache = new Set();
+            return runtimeModelIdsCache;
+        }
+    };
+    const ensureRuntimeModelActive = async (runtimeModelId) => {
+        const mods = await loadRuntimeRoutingModules();
+        if (!mods)
+            throw new Error('Runtime routing is unavailable in this build/environment');
+        const runtimes = await mods.store.loadRuntimes();
+        runtimeModelIdsCache = new Set(runtimes.models.filter((m) => m.enabled !== false).map((m) => m.id));
+        const modelExists = runtimes.models.some((m) => m.enabled !== false && m.id === runtimeModelId);
+        if (!modelExists) {
+            throw new Error(`Runtime model not found or disabled: ${runtimeModelId}`);
+        }
+        let active = await mods.executor.loadActiveRuntime();
+        if (active?.healthy && active.modelId === runtimeModelId && active.endpoint) {
+            if (normalizeEndpoint(active.endpoint) !== normalizeEndpoint(cfg.endpoint)) {
+                await setEndpoint(active.endpoint);
+            }
             return;
-        client.setExchangeHook(async (record) => {
-            lastCaptureRecord = record;
-            if (!captureEnabled)
-                return;
-            const target = capturePath || defaultCapturePath();
-            capturePath = target;
-            await appendCaptureRecord(record, target);
-        });
+        }
+        const planResult = mods.planner.plan({ modelId: runtimeModelId, mode: 'live' }, runtimes, active);
+        if (!planResult.ok) {
+            throw new Error(`Runtime switch plan failed for ${runtimeModelId}: ${planResult.reason}`);
+        }
+        if (!planResult.reuse) {
+            const execResult = await mods.executor.execute(planResult, {
+                confirm: async () => false,
+            });
+            if (!execResult.ok) {
+                throw new Error(`Runtime switch failed for ${runtimeModelId}: ${execResult.error ?? 'unknown error'}`);
+            }
+        }
+        active = await mods.executor.loadActiveRuntime();
+        if (!active?.endpoint || active.healthy !== true) {
+            throw new Error(`Runtime did not become healthy for ${runtimeModelId}`);
+        }
+        if (normalizeEndpoint(active.endpoint) !== normalizeEndpoint(cfg.endpoint)) {
+            await setEndpoint(active.endpoint);
+        }
+    };
+    const wireCaptureHook = () => {
+        attachCaptureHook(client);
     };
     wireCaptureHook();
     const replayEnabled = cfg.trifecta?.enabled !== false && cfg.trifecta?.replay?.enabled !== false;
@@ -1228,9 +1349,9 @@ export async function createSession(opts) {
         else {
             client = new OpenAIClient(normalized, opts.apiKey, cfg.verbose);
         }
-        if (typeof client.setVerbose === 'function') {
-            client.setVerbose(cfg.verbose);
-        }
+        applyClientRuntimeOptions(client);
+        clientPool.setPrimary(client);
+        clientPool.reset();
         wireCaptureHook();
         modelsList = normalizeModelsResponse(await client.models());
         const chosen = modelName?.trim()
@@ -1239,25 +1360,12 @@ export async function createSession(opts) {
                 (await autoPickModel(client, modelsList)));
         setModel(chosen);
     };
-    const captureOn = async (filePath) => {
-        const target = filePath?.trim() ? path.resolve(filePath) : defaultCapturePath();
-        await fs.mkdir(path.dirname(target), { recursive: true });
-        await fs.appendFile(target, '', 'utf8');
-        captureEnabled = true;
-        capturePath = target;
-        return target;
-    };
-    const captureOff = () => {
-        captureEnabled = false;
-    };
-    const captureLast = async (filePath) => {
-        if (!lastCaptureRecord) {
-            throw new Error('No captured request/response pair is available yet.');
-        }
-        const target = filePath?.trim() ? path.resolve(filePath) : capturePath || defaultCapturePath();
-        await appendCaptureRecord(lastCaptureRecord, target);
-        return target;
-    };
+    const captureOn = (filePath) => capture.on(filePath);
+    const captureOff = () => capture.off();
+    const captureSetRedact = (enabled) => capture.setRedact(enabled);
+    const captureGetRedact = () => capture.getRedact();
+    const captureOpen = () => capture.open();
+    const captureLast = (filePath) => capture.last(filePath);
     const listMcpServers = () => {
         return mcpManager?.listServers() ?? [];
     };
@@ -1288,6 +1396,7 @@ export async function createSession(opts) {
     const close = async () => {
         await mcpManager?.close().catch(() => { });
         await lspManager?.close().catch(() => { });
+        await clientPool.closeAll();
         vault?.close();
         lens?.close();
     };
@@ -1388,16 +1497,38 @@ export async function createSession(opts) {
             : cfg.max_iterations;
         const wallStart = Date.now();
         const delegationForbiddenByUser = userDisallowsDelegation(instruction);
+        const rawInstructionText = userContentToText(instruction).trim();
+        // Route early so first-turn prelude/tool choices can adapt.
+        const turnRoute = decideTurnRoute(cfg, rawInstructionText, model);
+        // Apply hysteresis to suppress rapid lane thrashing in auto mode.
+        const hysteresisResult = routeHysteresis.apply(turnRoute.selectedMode, turnRoute.selectedModeSource);
+        if (hysteresisResult.suppressed) {
+            // Override the selected mode with the hysteresis-stabilized lane.
+            turnRoute.selectedMode = hysteresisResult.lane;
+            turnRoute.selectedModeSource = 'hysteresis';
+        }
+        const routeFastByAuto = turnRoute.requestedMode === 'auto' &&
+            turnRoute.selectedMode === 'fast' &&
+            turnRoute.selectedModeSource !== 'override';
+        const compactPreludeEnabled = cfg.routing?.fastCompactPrelude !== false;
+        // Never use compact prelude when the harness injected format reminders
+        // (e.g. tool_calls format for nemotron) — those are critical for correctness.
+        const hasHarnessInjection = sessionMetaPending
+            ? sessionMetaPending.includes('Use the tool_calls mechanism') ||
+                sessionMetaPending.includes('[Format reminder]')
+            : false;
+        const useCompactPrelude = Boolean(sessionMetaPending && compactPreludeEnabled && routeFastByAuto && !hasHarnessInjection);
         // Prepend session meta to the first user instruction (§9b: variable context
         // goes in first user message, not system prompt, to preserve KV cache).
         // This avoids two consecutive user messages without an assistant response.
         let userContent = instruction;
         if (sessionMetaPending) {
+            const prelude = useCompactPrelude ? compactSessionMeta : sessionMetaPending;
             if (typeof instruction === 'string') {
-                userContent = `${sessionMetaPending}\n\n${instruction}`;
+                userContent = `${prelude}\n\n${instruction}`;
             }
             else {
-                userContent = [{ type: 'text', text: sessionMetaPending }, ...instruction];
+                userContent = [{ type: 'text', text: prelude }, ...instruction];
             }
             sessionMetaPending = null;
         }
@@ -1436,6 +1567,8 @@ export async function createSession(opts) {
                 // Vault search is best-effort; don't fail the turn
             }
         }
+        // Save rollback checkpoint before this turn (captures pre-turn state).
+        conversationBranch.checkpoint(messages.length, typeof instruction === 'string' ? instruction : '[multimodal]');
         messages.push({ role: 'user', content: userContent });
         const hookObj = typeof hooks === 'function' ? { onToken: hooks } : (hooks ?? {});
         let turns = 0;
@@ -1561,7 +1694,6 @@ export async function createSession(opts) {
             }
             return { text: finalText, turns, toolCalls };
         };
-        const rawInstructionText = userContentToText(instruction).trim();
         lastAskInstructionText = rawInstructionText;
         lastCompactionReminderObjective = '';
         if (hooksEnabled)
@@ -1575,6 +1707,9 @@ export async function createSession(opts) {
             if (typeof client.probeConnection === 'function') {
                 await client.probeConnection();
                 initialConnectionProbeDone = true;
+                if (typeof client.getEndpoint === 'function') {
+                    clientPool.markProbed(client.getEndpoint());
+                }
             }
         }
         if (retrievalRequested) {
@@ -1621,6 +1756,54 @@ export async function createSession(opts) {
             });
             return await finalizeAsk(miss);
         }
+        const primaryRoute = turnRoute.providerTargets[0];
+        const runtimeModelIds = await loadRuntimeModelIds();
+        const routeRuntimeFallbackModels = (primaryRoute?.fallbackModels ?? []).filter((m) => runtimeModelIds.has(m));
+        const apiProviderTargets = turnRoute.providerTargets.map((target) => ({
+            ...target,
+            fallbackModels: (target.fallbackModels ?? []).filter((m) => !runtimeModelIds.has(m)),
+        }));
+        const routeApiFallbackModels = apiProviderTargets[0]?.fallbackModels ?? [];
+        const primaryUsesRuntimeModel = !!primaryRoute?.model && runtimeModelIds.has(primaryRoute.model);
+        const fastLaneToolless = cfg.routing?.fastLaneToolless !== false &&
+            routeFastByAuto &&
+            turnRoute.classificationHint === 'fast';
+        // Fast-lane slim tools: on subsequent turns of a fast-route ask, include only
+        // read-only / lightweight tools to reduce per-turn token overhead (~40-50%).
+        // Only active when the classifier explicitly said 'fast' (not heuristic/fallback).
+        const fastLaneSlimTools = cfg.routing?.fastLaneSlimTools !== false &&
+            routeFastByAuto &&
+            turnRoute.classificationHint === 'fast';
+        // Non-runtime route models can be selected directly in-session.
+        if (!primaryUsesRuntimeModel && primaryRoute?.model && primaryRoute.model !== model) {
+            setModel(primaryRoute.model);
+        }
+        if (cfg.verbose) {
+            const routeParts = [
+                `requested=${turnRoute.requestedMode}`,
+                `selected=${turnRoute.selectedMode}`,
+                `source=${turnRoute.selectedModeSource}`,
+                `hint=${turnRoute.classificationHint ?? 'none'}`,
+                `provider=${primaryRoute?.name ?? 'default'}`,
+                `model=${primaryRoute?.model ?? model}`,
+            ];
+            if (turnRoute.heuristicDecision)
+                routeParts.push(`heuristic=${turnRoute.heuristicDecision}`);
+            if (primaryUsesRuntimeModel) {
+                const runtimeChain = [primaryRoute?.model, ...routeRuntimeFallbackModels]
+                    .filter(Boolean)
+                    .join(' -> ');
+                routeParts.push(`runtime_chain=${runtimeChain || 'none'}`);
+            }
+            else if (routeApiFallbackModels.length) {
+                routeParts.push(`api_fallbacks=${routeApiFallbackModels.join(',')}`);
+            }
+            if (useCompactPrelude)
+                routeParts.push('compact_prelude=on');
+            if (fastLaneToolless)
+                routeParts.push('fast_toolless=on');
+            console.error(`[routing] ${routeParts.join(' ')}`);
+        }
         const persistReviewArtifact = async (finalText) => {
             if (!vault || !shouldPersistReviewArtifact)
                 return;
@@ -2018,10 +2201,38 @@ export async function createSession(opts) {
                 let resp;
                 try {
                     try {
-                        const toolsForTurn = cfg.no_tools || forceToollessRecoveryTurn
+                        // turns is 1-indexed (incremented at loop top), so first iteration = 1.
+                        const forceToollessByRouting = fastLaneToolless && turns === 1;
+                        // On fast-lane subsequent turns, slim the schema to read-only tools.
+                        const useSlimFast = !forceToollessByRouting && fastLaneSlimTools && turns > 1;
+                        const toolsForTurn = cfg.no_tools || forceToollessRecoveryTurn || forceToollessByRouting
                             ? []
-                            : getToolsSchema().filter((t) => !suppressedTools.has(t.function.name));
-                        const toolChoiceForTurn = cfg.no_tools || forceToollessRecoveryTurn ? 'none' : 'auto';
+                            : getToolsSchema(useSlimFast).filter((t) => !suppressedTools.has(t.function.name));
+                        const toolChoiceForTurn = cfg.no_tools || forceToollessRecoveryTurn || forceToollessByRouting ? 'none' : 'auto';
+                        const promptBytesEstimate = Buffer.byteLength(JSON.stringify(messages), 'utf8');
+                        const toolSchemaBytesEstimate = toolsForTurn.length
+                            ? Buffer.byteLength(JSON.stringify(toolsForTurn), 'utf8')
+                            : 0;
+                        const toolSchemaTokenEstimate = estimateToolSchemaTokens(toolsForTurn);
+                        lastTurnDebug = {
+                            requestedMode: turnRoute.requestedMode,
+                            selectedMode: turnRoute.selectedMode,
+                            selectedModeSource: turnRoute.selectedModeSource,
+                            classificationHint: turnRoute.classificationHint,
+                            provider: primaryRoute?.name ?? 'default',
+                            model: primaryRoute?.model ?? model,
+                            runtimeRoute: primaryUsesRuntimeModel,
+                            compactPrelude: useCompactPrelude,
+                            fastLaneToolless,
+                            fastLaneSlimTools: useSlimFast,
+                            promptBytes: promptBytesEstimate,
+                            toolSchemaBytes: toolSchemaBytesEstimate,
+                            toolSchemaTokens: toolSchemaTokenEstimate,
+                            toolCount: toolsForTurn.length,
+                        };
+                        if (cfg.verbose) {
+                            console.error(`[turn-debug] prompt_bytes=${promptBytesEstimate} tools=${toolsForTurn.length} tool_schema_bytes=${toolSchemaBytesEstimate} tool_schema_tokens~=${toolSchemaTokenEstimate}`);
+                        }
                         // ── Response cache: check for cached response ──────────────
                         // Only cache tool-less turns (final answers, explanations) since
                         // tool-calling turns have side effects that shouldn't be replayed.
@@ -2045,8 +2256,7 @@ export async function createSession(opts) {
                             }
                         }
                         if (!resp) {
-                            resp = await client.chatStream({
-                                model,
+                            const chatOptsBase = {
                                 messages,
                                 tools: toolsForTurn,
                                 tool_choice: toolChoiceForTurn,
@@ -2055,9 +2265,10 @@ export async function createSession(opts) {
                                 max_tokens: maxTokens,
                                 extra: {
                                     cache_prompt: cfg.cache_prompt ?? true,
-                                    // Speculative decoding: draft model params for llama-server
                                     ...(cfg.draft_model ? { draft_model: cfg.draft_model } : {}),
-                                    ...(cfg.draft_n ? { speculative: { n: cfg.draft_n, p_min: cfg.draft_p_min ?? 0.5 } } : {}),
+                                    ...(cfg.draft_n
+                                        ? { speculative: { n: cfg.draft_n, p_min: cfg.draft_p_min ?? 0.5 } }
+                                        : {}),
                                     ...(frequencyPenalty && { frequency_penalty: frequencyPenalty }),
                                     ...(presencePenalty && { presence_penalty: presencePenalty }),
                                 },
@@ -2065,7 +2276,98 @@ export async function createSession(opts) {
                                 requestId: `r${reqCounter}`,
                                 onToken: hookObj.onToken,
                                 onFirstDelta,
-                            });
+                            };
+                            if (primaryUsesRuntimeModel && primaryRoute?.model) {
+                                // Runtime-native routing: lane model/fallbacks reference runtime model IDs.
+                                const runtimePrimaryModel = primaryRoute.model;
+                                const runtimeFallbackMap = {};
+                                if (routeRuntimeFallbackModels.length > 0) {
+                                    runtimeFallbackMap[runtimePrimaryModel] = routeRuntimeFallbackModels;
+                                }
+                                resp = await resilientCall([
+                                    {
+                                        name: 'runtime-router',
+                                        execute: async (runtimeModelId) => {
+                                            await ensureRuntimeModelActive(runtimeModelId);
+                                            const runtimeClient = getClientForEndpoint();
+                                            const runtimeModel = model;
+                                            return runtimeClient.chatStream({ ...chatOptsBase, model: runtimeModel });
+                                        },
+                                    },
+                                ], runtimePrimaryModel, {
+                                    maxRetries: 0,
+                                    modelFallbacks: runtimeFallbackMap,
+                                    onRetry: (info) => {
+                                        if (cfg.verbose) {
+                                            console.error(`[routing] runtime-fallback: model=${info.model} attempt=${info.attempt}/${info.maxAttempts} reason=${info.reason}`);
+                                        }
+                                    },
+                                });
+                            }
+                            else {
+                                const isLikelyAuthError = (errMsg) => {
+                                    const lower = errMsg.toLowerCase();
+                                    return (lower.includes('refresh_token_reused') ||
+                                        lower.includes('missing bearer') ||
+                                        lower.includes('missing api key') ||
+                                        lower.includes('invalid api key') ||
+                                        lower.includes('authentication failed') ||
+                                        lower.includes('unauthorized') ||
+                                        lower.includes('forbidden') ||
+                                        lower.includes('invalid token'));
+                                };
+                                const providerFailures = [];
+                                for (const target of apiProviderTargets.length
+                                    ? apiProviderTargets
+                                    : [{
+                                            name: primaryRoute?.name ?? 'default',
+                                            endpoint: primaryRoute?.endpoint,
+                                            model: primaryRoute?.model ?? model,
+                                            fallbackModels: routeApiFallbackModels,
+                                        }]) {
+                                    const routeEndpoint = target.endpoint;
+                                    const activeClient = getClientForEndpoint(routeEndpoint);
+                                    if (routeEndpoint) {
+                                        await clientPool.probeIfNeeded(routeEndpoint);
+                                    }
+                                    const routeModel = target.model || model;
+                                    const modelFallbackMap = {};
+                                    if (target.fallbackModels?.length) {
+                                        modelFallbackMap[routeModel] = target.fallbackModels;
+                                    }
+                                    try {
+                                        resp = await resilientCall([
+                                            {
+                                                name: target.name ?? 'default',
+                                                execute: (m) => activeClient.chatStream({ ...chatOptsBase, model: m }),
+                                            },
+                                        ], routeModel, {
+                                            maxRetries: 0,
+                                            modelFallbacks: modelFallbackMap,
+                                            onRetry: (info) => {
+                                                if (cfg.verbose) {
+                                                    console.error(`[routing] retry: provider=${info.provider} model=${info.model} attempt=${info.attempt}/${info.maxAttempts} reason=${info.reason}`);
+                                                }
+                                            },
+                                        });
+                                        break;
+                                    }
+                                    catch (providerErr) {
+                                        const errMsg = String(providerErr?.message ?? providerErr ?? 'unknown error');
+                                        const compactErr = errMsg.replace(/\s+/g, ' ').trim();
+                                        providerFailures.push(`${target.name}: ${compactErr}`);
+                                        if (cfg.verbose && isLikelyAuthError(errMsg)) {
+                                            console.warn(`[routing] auth/provider failure on ${target.name}; trying next provider fallback`);
+                                        }
+                                        if (isContextWindowExceededError(providerErr)) {
+                                            throw providerErr;
+                                        }
+                                    }
+                                }
+                                if (!resp) {
+                                    throw new Error(`All routed providers failed for this turn. ${providerFailures.join(' | ')}`);
+                                }
+                            }
                         } // end if (!resp) — cache miss path
                         // Successful response resets overflow recovery budget.
                         overflowCompactionAttempts = 0;
@@ -2835,6 +3137,7 @@ export async function createSession(opts) {
                         let content = '';
                         let reusedCachedReadOnlyExec = false;
                         let reusedCachedReadTool = false;
+                        let toolFallbackNote = null;
                         if (name === 'exec' && repeatedReadOnlyExecSigs.has(sig)) {
                             const cached = execObservationCacheBySig.get(sig);
                             if (cached) {
@@ -2868,7 +3171,92 @@ export async function createSession(opts) {
                                     toolName: name,
                                     onToolStream: emitToolStream,
                                 };
-                                const value = await builtInFn(callCtx, args);
+                                let value;
+                                try {
+                                    value = await builtInFn(callCtx, args);
+                                }
+                                catch (err) {
+                                    const msg = String(err?.message ?? err ?? '');
+                                    // Fallback #1: edit_file mismatch -> targeted edit_range based on closest-match hint.
+                                    const isEditMismatch = name === 'edit_file' && /edit_file:\s*old_text not found/i.test(msg);
+                                    if (isEditMismatch && typeof args?.path === 'string') {
+                                        const best = msg.match(/Closest match at line\s+(\d+)\s*\((\d+)% similarity\)/i);
+                                        const bestLine = best ? Number.parseInt(best[1], 10) : NaN;
+                                        const similarity = best ? Number.parseInt(best[2], 10) : NaN;
+                                        const oldTextForRange = String(args?.old_text ?? '');
+                                        const oldLineCount = Math.max(1, oldTextForRange.split(/\r?\n/).length);
+                                        const endLine = Number.isFinite(bestLine)
+                                            ? bestLine + oldLineCount - 1
+                                            : Number.NaN;
+                                        const editRangeFn = tools['edit_range'];
+                                        if (editRangeFn &&
+                                            Number.isFinite(bestLine) &&
+                                            Number.isFinite(endLine) &&
+                                            Number.isFinite(similarity) &&
+                                            similarity >= 70) {
+                                            const fallbackArgs = {
+                                                path: args.path,
+                                                start_line: bestLine,
+                                                end_line: endLine,
+                                                replacement: args.new_text,
+                                            };
+                                            if (cfg.verbose) {
+                                                console.warn(`[edit_file] auto-fallback to edit_range at ${bestLine}-${endLine} (${similarity}% similarity)`);
+                                            }
+                                            value = await editRangeFn(callCtx, fallbackArgs);
+                                            args = fallbackArgs;
+                                            toolFallbackNote = 'auto edit_range fallback';
+                                        }
+                                        else {
+                                            throw err;
+                                        }
+                                    }
+                                    else {
+                                        const isWriteRefusal = name === 'write_file' &&
+                                            !args?.overwrite &&
+                                            !args?.force &&
+                                            /write_file:\s*refusing to overwrite existing non-empty file/i.test(msg);
+                                        if (!isWriteRefusal)
+                                            throw err;
+                                        // Fallback #2 (preferred): rewrite existing file via edit_range first.
+                                        const editRangeFn = tools['edit_range'];
+                                        let usedEditRangeFallback = false;
+                                        if (editRangeFn && typeof args?.path === 'string') {
+                                            try {
+                                                const absWritePath = args.path.startsWith('/')
+                                                    ? args.path
+                                                    : path.resolve(projectDir, args.path);
+                                                const curText = await fs.readFile(absWritePath, 'utf8');
+                                                const totalLines = Math.max(1, curText.split(/\r?\n/).length);
+                                                const fallbackArgs = {
+                                                    path: args.path,
+                                                    start_line: 1,
+                                                    end_line: totalLines,
+                                                    replacement: args.content,
+                                                };
+                                                if (cfg.verbose) {
+                                                    console.warn(`[write_file] auto-fallback to edit_range for existing file (${totalLines} lines)`);
+                                                }
+                                                value = await editRangeFn(callCtx, fallbackArgs);
+                                                args = fallbackArgs;
+                                                toolFallbackNote = 'auto edit_range fallback';
+                                                usedEditRangeFallback = true;
+                                            }
+                                            catch {
+                                                // fall through to explicit overwrite retry below
+                                            }
+                                        }
+                                        if (!usedEditRangeFallback) {
+                                            const retryArgs = { ...args, overwrite: true };
+                                            if (cfg.verbose) {
+                                                console.warn('[write_file] auto-retrying with overwrite=true after explicit overwrite refusal');
+                                            }
+                                            value = await builtInFn(callCtx, retryArgs);
+                                            args = retryArgs;
+                                            toolFallbackNote = 'auto overwrite fallback';
+                                        }
+                                    }
+                                }
                                 content = typeof value === 'string' ? value : JSON.stringify(value);
                                 if (READ_FILE_CACHE_TOOLS.has(name) &&
                                     typeof content === 'string' &&
@@ -2954,6 +3342,9 @@ export async function createSession(opts) {
                         let summary = reusedCachedReadOnlyExec
                             ? 'cached read-only exec observation (unchanged)'
                             : toolResultSummary(name, args, content, true);
+                        if (toolFallbackNote) {
+                            summary = `${summary} (${toolFallbackNote})`;
+                        }
                         const resultEvent = {
                             id: callId,
                             name,
@@ -3527,17 +3918,32 @@ export async function createSession(opts) {
             return currentContextTokens > 0 ? currentContextTokens : estimateTokensFromMessages(messages);
         },
         ask,
+        rollback: () => {
+            const cp = conversationBranch.rollback();
+            if (!cp)
+                return null;
+            const removed = messages.length - cp.messageCount;
+            messages.length = cp.messageCount;
+            return { preview: cp.preview, removedMessages: removed };
+        },
+        listCheckpoints: () => conversationBranch.list(),
         setModel,
         setEndpoint,
         listModels,
         refreshServerHealth,
         getPerfSummary,
         getToolLoopStats: () => lastToolLoopStats,
+        get lastAskInstructionText() {
+            return lastAskInstructionText;
+        },
         captureOn,
         captureOff,
         captureLast,
+        captureSetRedact,
+        captureGetRedact,
+        captureOpen,
         get capturePath() {
-            return capturePath;
+            return capture.path;
         },
         getSystemPrompt: () => messages[0]?.role === 'system' ? String(messages[0].content) : activeSystemPromptBase,
         setSystemPrompt,
@@ -3564,6 +3970,9 @@ export async function createSession(opts) {
         get lastTurnMetrics() {
             return lastTurnMetrics;
         },
+        get lastTurnDebug() {
+            return lastTurnDebug;
+        },
         get lastServerHealth() {
             return lastServerHealth;
         },