mixdog 0.9.23 → 0.9.24

package/src/runtime/agent/orchestrator/agent-runtime/agent-progress-watchdog.mjs

@@ -33,6 +33,62 @@ export function isAgentProgressWatchdogAbortError(err) {
     return typeof msg === 'string' && WATCHDOG_ABORT_RE.test(msg);
 }
 
+// Tools that enforce their own execution deadline: 'shell' kills the process
+// at its configured timeout; 'task' wait is bounded by its own wait budget.
+// These are NOT blanket-exempted from the tool-running watchdog — if their own
+// deadline timer dies the session would otherwise hang forever. Instead the
+// watchdog raises the tool-running ceiling to their self-deadline + a grace
+// window (below), so normal long runs are allowed but a dead timer is still
+// caught. Unknown/missing self-deadline falls back to the plain toolRunningMs.
+const SELF_DEADLINE_TOOLS = new Set(['shell', 'task']);
+// Grace added on top of a tool's own deadline before the watchdog steps in, so
+// the tool's in-process kill always fires first under normal operation.
+const TOOL_SELF_DEADLINE_GRACE_MS = 60_000;
+// Fallback deadlines matching the tool implementations (bash-tool.mjs default
+// 120s foreground timeout; task/shell-job wait default 30s budget).
+const SHELL_DEFAULT_TIMEOUT_MS = 120_000;
+const TASK_DEFAULT_WAIT_MS = 30_000;
+
+function bareToolName(toolName) {
+    if (typeof toolName !== 'string' || !toolName) return '';
+    // Strip any MCP/server prefix (e.g. 'server__shell' or 'server.shell').
+    return toolName.split(/[.]|__/).pop();
+}
+
+function isSelfDeadlineTool(toolName) {
+    const bare = bareToolName(toolName);
+    return SELF_DEADLINE_TOOLS.has(bare) || SELF_DEADLINE_TOOLS.has(toolName);
+}
+
+/**
+ * Resolve the self-enforced deadline (ms) for a tool call from its arguments,
+ * recorded into the progress snapshot at dispatch time. Returns a positive
+ * number when the tool enforces its own deadline, or null when unknown/missing
+ * (caller then falls back to the plain toolRunningMs ceiling).
+ *   - shell: explicit `timeout` (ms) if positive, else the 120s default.
+ *   - task:  explicit `timeout_ms` if positive, else 30s for the `wait` action
+ *            (other actions carry no wait budget -> null).
+ */
+export function resolveToolSelfDeadlineMs(toolName, args) {
+    if (!isSelfDeadlineTool(toolName)) return null;
+    const bare = bareToolName(toolName);
+    const a = (args && typeof args === 'object') ? args : {};
+    if (bare === 'shell') {
+        const t = Number(a.timeout);
+        if (Number.isFinite(t) && t > 0) return t;
+        const envDefault = parseInt(process.env.BASH_DEFAULT_TIMEOUT_MS ?? '', 10);
+        return envDefault > 0 ? envDefault : SHELL_DEFAULT_TIMEOUT_MS;
+    }
+    if (bare === 'task') {
+        const t = Number(a.timeout_ms);
+        if (Number.isFinite(t) && t > 0) return t;
+        const action = typeof a.action === 'string' ? a.action : '';
+        if (action === 'wait') return TASK_DEFAULT_WAIT_MS;
+        return null;
+    }
+    return null;
+}
+
 function assistantMessageText(content) {
     if (typeof content === 'string') return content;
     if (!Array.isArray(content)) return '';
@@ -209,7 +265,26 @@ export function evaluateAgentWatchdogAbort(snapshot, now, policy) {
         && policy.toolRunningMs > 0
         && now - snapshot.toolStartedAt > policy.toolRunningMs
     ) {
-        return new AgentStallAbortError(`agent tool running stale (${policy.toolRunningMs}ms)`);
+        // Deadline-aware ceiling for tools that self-enforce their own deadline
+        // ('shell'/'task'). Rather than a blanket exemption (which would hang
+        // forever if the tool's own timer died), raise the tool-running ceiling
+        // to max(toolRunningMs, selfDeadlineMs + grace): normal long runs are
+        // allowed because the tool kills itself first, but a dead deadline timer
+        // is still caught after the grace window. Unknown/missing self-deadline
+        // (selfDeadlineMs <= 0) keeps the plain toolRunningMs behavior. All
+        // other tools are unaffected.
+        let ceilingMs = policy.toolRunningMs;
+        const selfDeadlineMs = Number(snapshot.toolSelfDeadlineMs);
+        if (
+            isSelfDeadlineTool(snapshot.currentTool)
+            && Number.isFinite(selfDeadlineMs)
+            && selfDeadlineMs > 0
+        ) {
+            ceilingMs = Math.max(policy.toolRunningMs, selfDeadlineMs + TOOL_SELF_DEADLINE_GRACE_MS);
+        }
+        if (now - snapshot.toolStartedAt > ceilingMs) {
+            return new AgentStallAbortError(`agent tool running stale (${ceilingMs}ms)`);
+        }
     }
 
     return null;

package/src/runtime/agent/orchestrator/config.mjs

@@ -1,5 +1,5 @@
 import { resolvePluginData } from '../../shared/plugin-paths.mjs';
-import { readSection, updateSection, getAgentApiKey, AGENT_PROVIDER_ENV } from '../../shared/config.mjs';
+import { readSection, updateSection, updateSectionAsync, getAgentApiKey, AGENT_PROVIDER_ENV } from '../../shared/config.mjs';
 import { OPENAI_COMPAT_PRESETS } from './providers/openai-compat-presets.mjs';
 import {
     hasAnthropicOAuthCredentials,
@@ -241,6 +241,14 @@ function persistAgentConfig(build) {
     updateSection('agent', (current) => build(hasKeys(current) ? current : {}));
 }
 
+// Async twin of persistAgentConfig: same in-lock rebase-on-current semantics,
+// but the whole-section RMW runs through updateSectionAsync so a debounced
+// timer flush never blocks the event loop on icacls/backup. Reuses the same
+// config lock file, so it stays linearizable with the sync writers.
+async function persistAgentConfigAsync(build) {
+    await updateSectionAsync('agent', (current) => build(hasKeys(current) ? current : {}));
+}
+
 // Recap toggle (recap.enabled, default true) gates ONLY the background memory
 // cycles. The memory module itself is always-on. On load we fold a legacy
 // `modules.memory === false` flag into recap.enabled=false one time; the caller
@@ -506,23 +514,34 @@ export function loadConfig(options = {}) {
  * concurrent instance's edits are not reverted.
  */
 /** In-lock patch of `skills.disabled` only (avoids whole-config lost-update). */
-export function patchSkillsDisabled(disabledNames) {
+function buildSkillsDisabledPatch(disabledNames) {
     const names = disabledNames instanceof Set
         ? [...disabledNames]
         : (Array.isArray(disabledNames) ? disabledNames : []);
     const nextSkills = normalizeSkillsConfig({ disabled: names });
-    persistAgentConfig((current) => {
+    const build = (current) => {
         const cur = { ...current };
         const target = (cur.agent && cur.agent.providers)
             ? (cur.agent = { ...cur.agent })
             : cur;
         target.skills = nextSkills;
         return cur;
-    });
+    };
+    return { build, nextSkills };
+}
+export function patchSkillsDisabled(disabledNames) {
+    const { build, nextSkills } = buildSkillsDisabledPatch(disabledNames);
+    persistAgentConfig(build);
+    return nextSkills;
+}
+// Async twin used by the debounced skills flush timer.
+export async function patchSkillsDisabledAsync(disabledNames) {
+    const { build, nextSkills } = buildSkillsDisabledPatch(disabledNames);
+    await persistAgentConfigAsync(build);
     return nextSkills;
 }
 
-export function saveConfig(config) {
+function buildAgentSaveBuilder(config) {
     // Strip ephemeral defaults from providers but preserve any unknown
     // per-provider subkey so future schema additions round-trip through the
     // setup UI without changes here. apiKey is intentionally omitted —
@@ -556,7 +575,7 @@ export function saveConfig(config) {
     // Build the replacement from `existingRaw` — the section read INSIDE the
     // file lock — not a snapshot taken before it, so unmanaged keys written by
     // a concurrent instance survive the save (lost-update guard).
-    persistAgentConfig((existingRaw) => ({
+    return (existingRaw) => ({
         ...existingRaw,
         guide: config.guide || existingRaw.guide || undefined,
         providers: persistedProviders,
@@ -582,7 +601,14 @@ export function saveConfig(config) {
         update: config.update || {},
         recap: config.recap || {},
         modules: config.modules || existingRaw.modules || {},
-    }));
+    });
+}
+export function saveConfig(config) {
+    persistAgentConfig(buildAgentSaveBuilder(config));
+}
+// Async twin used by the debounced config-save flush timer.
+export async function saveConfigAsync(config) {
+    await persistAgentConfigAsync(buildAgentSaveBuilder(config));
 }
 // --- Preset helpers ---
 // preset shape: { id, name, type: 'agent', provider, model, effort?, fast?, tools? }

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -407,9 +407,38 @@ export function stripDeferredToolManifestBlock(text) {
         .trimEnd();
 }
 
-/** Inject the skill-style deferred pool (name + description) into BP1 once at session start; never rewrite BP1 after. */
-export function applyInitialDeferredToolManifestToBp1(session, poolNames) {
-    if (!session || !Array.isArray(session.messages) || session.deferredToolBp1Applied) return false;
+// Rebuild path: replace the FIRST previously-injected <available-deferred-tools>
+// block (with its leading `---` separator) with the fresh manifest IN PLACE, so
+// the block keeps its original position and no sibling BP1 block (skills
+// manifest, agent rules, …) is reordered or dropped. The fresh manifest already
+// carries the mcp-instructions companion, so any pre-existing standalone one is
+// removed first to avoid duplication.
+export function rebuildDeferredToolManifestBlock(text, manifest) {
+    let out = String(text || '').replace(MCP_INSTRUCTIONS_BLOCK_RE, '');
+    let replaced = false;
+    out = out.replace(DEFERRED_TOOLS_BLOCK_RE, (match, sep) => {
+        if (replaced) return '';
+        replaced = true;
+        return `${sep || ''}${manifest}`;
+    });
+    if (!replaced) {
+        const base = out.trimEnd();
+        out = base ? `${base}\n\n---\n\n${manifest}` : manifest;
+    }
+    return out;
+}
+
+/**
+ * Inject the skill-style deferred pool (name + description) into BP1 at session
+ * start. Normally once; with `{ rebuild: true }` it strips any existing
+ * <available-deferred-tools>/<mcp-instructions> block and re-injects the fresh
+ * pool in place (used by the first-turn MCP refresh, before the prompt renders,
+ * so late-connected MCP tools land in the INITIAL manifest — never duplicated).
+ */
+export function applyInitialDeferredToolManifestToBp1(session, poolNames, options = {}) {
+    const rebuild = options?.rebuild === true;
+    if (!session || !Array.isArray(session.messages)) return false;
+    if (session.deferredToolBp1Applied && !rebuild) return false;
     const pool = Array.isArray(poolNames) ? poolNames : [];
     const descByName = new Map();
     for (const tool of Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : []) {
@@ -432,15 +461,21 @@ export function applyInitialDeferredToolManifestToBp1(session, poolNames) {
     }
     if (idx === -1) return false;
     const raw = typeof session.messages[idx].content === 'string' ? session.messages[idx].content : '';
-    if (bp1HasDeferredToolManifestBlock(raw)) {
+    if (bp1HasDeferredToolManifestBlock(raw) && !rebuild) {
         session.deferredToolBp1Applied = true;
         return true;
     }
     if (manifest) {
-        const base = stripDeferredToolManifestBlock(raw);
-        session.messages[idx].content = base
-            ? `${base}\n\n---\n\n${manifest}`
-            : manifest;
+        if (rebuild && bp1HasDeferredToolManifestBlock(raw)) {
+            // Anchored in-place rebuild: swap the previously injected manifest
+            // block for the fresh one at its EXISTING position.
+            session.messages[idx].content = rebuildDeferredToolManifestBlock(raw, manifest);
+        } else {
+            const base = stripDeferredToolManifestBlock(raw);
+            session.messages[idx].content = base
+                ? `${base}\n\n---\n\n${manifest}`
+                : manifest;
+        }
     }
     session.deferredToolBp1Applied = true;
     session.updatedAt = Date.now();

package/src/runtime/agent/orchestrator/mcp/child-tree.mjs

@@ -86,6 +86,45 @@ export async function collectDescendants(rootPid) {
     return descendantsOf(childrenOf, rootPid);
 }
 
+/**
+ * Immediate, non-blocking tree kill for a transport whose MCP handshake never
+ * completed (shutdown-during-connect). Unlike shutdownStdioChild there is no
+ * grace wait and no identity-checked enumeration on Windows — the ChildProcess
+ * handle is live, so the pid is current, and taskkill /T reaps the still-
+ * parented tree. Everything is unref'd/fire-and-forget so the kill can never
+ * hold the caller's event loop open (the caller is a process about to exit).
+ */
+export function killStdioChildTreeFast(transport) {
+    const proc = transport?._process;
+    const pid = (typeof transport?.pid === 'number' ? transport.pid : null) ?? proc?.pid ?? null;
+    if (!pid) return false;
+    if (proc && (proc.exitCode !== null || proc.signalCode !== null)) return false;
+    try { proc?.unref?.(); } catch { /* ignore */ }
+    for (const s of [proc?.stdin, proc?.stdout, proc?.stderr]) {
+        try { s?.unref?.(); } catch { /* ignore */ }
+        try { s?.destroy?.(); } catch { /* ignore */ }
+    }
+    if (isWin) {
+        try {
+            const cp = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], {
+                windowsHide: true,
+                detached: true,
+                stdio: 'ignore',
+            });
+            cp.unref();
+        } catch { /* ignore */ }
+        return true;
+    }
+    // POSIX: cheap ps enumerate, then SIGKILL descendants + root. Best-effort
+    // and un-awaited; a straggler orphan is reparented to init, not leaked by us.
+    void collectDescendants(pid).then((pids) => {
+        for (const p of [...pids, pid]) {
+            try { process.kill(p, 'SIGKILL'); } catch { /* ignore */ }
+        }
+    }).catch(() => { /* ignore */ });
+    return true;
+}
+
 function isAlive(pid) {
     try {
         process.kill(pid, 0);

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -4,7 +4,7 @@ import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
 import { smartReadTruncate } from '../tools/builtin/read-formatting.mjs';
-import { shutdownStdioChild } from './child-tree.mjs';
+import { shutdownStdioChild, killStdioChildTreeFast } from './child-tree.mjs';
 // --- Types ---
 /** Known auto-detect targets: port file path relative to tmpdir.
  *  Note: `mixdog` used to self-loopback via active-instance.json's
@@ -16,6 +16,8 @@ const AUTO_DETECT_PORTS = {
     'mixdog-memory': { dir: 'mixdog', file: 'active-instance.json', portField: 'memory_port', endpoint: '/mcp' },
 };
 const DEFAULT_MCP_CALL_TIMEOUT_MS = 0;
+// Per-server STARTUP handshake budget (connect + listTools). Codex parity: 10s.
+export const DEFAULT_MCP_STARTUP_TIMEOUT_MS = 10000;
 // --- State ---
 const servers = new Map();
 let mcpSdkPromise = null;
@@ -97,21 +99,31 @@ export function resolveMcpTransportKind(cfg) {
  * Supports stdio (child process) and http (Streamable HTTP) transports.
  */
 export async function connectMcpServers(config) {
+    // Capture the abort generation SYNCHRONOUSLY at entry: the boot path fires
+    // this un-awaited, so a runtime close can land while connectServer is still
+    // loading the SDK. A capture taken any later would already see the bumped
+    // generation and register the server anyway (leaking its stdio child).
+    const genAtStart = _connectAbortGeneration;
     const failures = [];
-    for (const [name, cfg] of Object.entries(config)) {
+    const entries = Object.entries(config).filter(([name, cfg]) => {
         if (cfg?.enabled === false) {
             mcpLog(`[mcp-client] Skipping disabled server "${name}"\n`);
-            continue;
+            return false;
         }
-        try {
-            await connectServer(name, cfg);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            mcpLog(`[mcp-client] Failed to connect "${name}": ${msg}\n`);
-            failures.push({ name, msg });
-        }
-    }
+        return true;
+    });
+    // Connect all servers in PARALLEL: a slow/hung server (bounded by its
+    // per-server startup timeout) must never delay the others' handshakes.
+    const settled = await Promise.allSettled(
+        entries.map(([name, cfg]) => connectServer(name, cfg, genAtStart)),
+    );
+    settled.forEach((res, i) => {
+        if (res.status !== 'rejected') return;
+        const [name] = entries[i];
+        const msg = res.reason instanceof Error ? res.reason.message : String(res.reason);
+        mcpLog(`[mcp-client] Failed to connect "${name}": ${msg}\n`);
+        failures.push({ name, msg });
+    });
     if (failures.length > 0) {
         const detail = failures.map(f => `${f.name}: ${f.msg}`).join('; ');
         const err = new Error(`[mcp-client] ${failures.length} MCP server(s) failed to connect — ${detail}`);
@@ -234,6 +246,26 @@ export function isMcpToolCallTimeoutError(err) {
     return err?.code === 'EMCPTOOLTIMEOUT';
 }
 
+// MCP per-server STARTUP timeout: bounds the connect + listTools handshake so a
+// slow or hung server can't stall boot or the first turn. Default 10s (codex
+// parity). Per-server override: startupTimeoutMs / startupTimeoutSec. Global
+// env: MIXDOG_MCP_STARTUP_TIMEOUT_MS. A value of 0/off/none/false disables it.
+export function resolveMcpStartupTimeoutMs(cfg = {}, env = process.env) {
+    const rawMs = cfg?.startupTimeoutMs ?? cfg?.startup_timeout_ms;
+    const rawSec = cfg?.startupTimeoutSec ?? cfg?.startup_timeout_sec;
+    const rawEnv = env?.MIXDOG_MCP_STARTUP_TIMEOUT_MS;
+    let raw;
+    let scale = 1;
+    if (rawMs != null && rawMs !== '') raw = rawMs;
+    else if (rawSec != null && rawSec !== '') { raw = rawSec; scale = 1000; }
+    else if (rawEnv != null && rawEnv !== '') raw = rawEnv;
+    else return DEFAULT_MCP_STARTUP_TIMEOUT_MS;
+    if (raw === 0 || (typeof raw === 'string' && /^(0|off|none|false)$/i.test(raw.trim()))) return 0;
+    const parsed = Number(raw) * scale;
+    if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MCP_STARTUP_TIMEOUT_MS;
+    return Math.round(parsed);
+}
+
 async function _callToolWithTimeout(server, toolName, args) {
     let timer;
     const timeoutMs = resolveMcpCallTimeoutMs(server?.cfg);
@@ -339,6 +371,22 @@ export function mcpToolHasField(name, field) {
  * Disconnect all MCP servers.
  */
 export async function disconnectAll() {
+    // Abort handshakes still in flight: bump the generation so a connect that
+    // completes after this point tears itself down instead of registering, and
+    // reap any already-spawned stdio child now so its ref'd ChildProcess handle
+    // can't keep the event loop alive (close-during-connect previously leaked
+    // the uvx/npx wrapper tree and hung process exit).
+    _connectAbortGeneration++;
+    for (const entry of [..._pendingConnects]) {
+        _pendingConnects.delete(entry);
+        // Mid-handshake child: nothing to shut down gracefully — hard-kill the
+        // tree without holding the event loop (this path runs during process
+        // exit; the spec-order grace dance would delay exit by seconds).
+        try { killStdioChildTreeFast(entry.transport); }
+        catch { /* ignore */ }
+        try { void entry.client.close().catch(() => { /* ignore */ }); }
+        catch { /* ignore */ }
+    }
     for (const [name, server] of servers) {
         try {
             await _closeServer(server);
@@ -382,7 +430,13 @@ async function _closeServer(server) {
     try { await server.client.close(); }
     catch { /* ignore */ }
 }
-async function connectServer(name, cfg) {
+// Connects whose handshake has not finished yet: disconnectAll() must be able
+// to see (and tear down) their transports, because `servers` only lists fully
+// handshaken entries. Generation token aborts a connect that outlives a
+// disconnectAll() issued mid-handshake (runtime close during boot connect).
+let _connectAbortGeneration = 0;
+const _pendingConnects = new Set();
+async function connectServer(name, cfg, genAtStart = _connectAbortGeneration) {
     const {
         Client,
         StdioClientTransport,
@@ -390,6 +444,11 @@ async function connectServer(name, cfg) {
         SSEClientTransport,
         WebSocketClientTransport,
     } = await loadMcpSdk();
+    if (genAtStart !== _connectAbortGeneration) {
+        // disconnectAll() ran while the SDK was loading: nothing spawned yet —
+        // abort before creating a transport/child at all.
+        throw new Error(`MCP server "${name}" connect aborted by shutdown`);
+    }
     const client = new Client({ name: `mixdog-agent/${name}`, version: '1.0.0' });
     let transport;
     const kind = resolveMcpTransportKind(cfg);
@@ -472,23 +531,78 @@ async function connectServer(name, cfg) {
     else {
         throw new Error(`Invalid config for "${name}": need autoDetect, type (stdio/http/sse/ws), url (http), or command (stdio)`);
     }
-    await client.connect(transport);
-    const instructionsRaw = typeof client.getInstructions === 'function'
-        ? client.getInstructions()
-        : undefined;
-    const instructions = typeof instructionsRaw === 'string' ? instructionsRaw.trim() : '';
-    const toolsResult = await client.listTools();
-    if (!toolsResult || !Array.isArray(toolsResult.tools)) {
-        throw new Error(`[mcp-client] ListTools returned invalid shape for "${name}": missing or non-array tools field`);
+    const pending = { name, client, transport };
+    _pendingConnects.add(pending);
+    try {
+        // Bound the connect + listTools handshake so a slow/hung server can't
+        // stall boot or the first turn. On expiry we tear down the pending
+        // transport/child (nothing leaks) and fail this server like any other
+        // connect failure — the parallel Promise.allSettled means other servers
+        // are unaffected.
+        const startupTimeoutMs = resolveMcpStartupTimeoutMs(cfg);
+        let startupTimer = null;
+        let startupTimedOut = false;
+        const handshake = (async () => {
+            await client.connect(transport);
+            const instructionsRaw = typeof client.getInstructions === 'function'
+                ? client.getInstructions()
+                : undefined;
+            const instr = typeof instructionsRaw === 'string' ? instructionsRaw.trim() : '';
+            const result = await client.listTools();
+            return { instructions: instr, toolsResult: result };
+        })();
+        let instructions;
+        let toolsResult;
+        try {
+            if (startupTimeoutMs > 0) {
+                const guard = new Promise((_, rej) => {
+                    startupTimer = setTimeout(() => {
+                        startupTimedOut = true;
+                        const err = new Error(`MCP server "${name}" startup exceeded ${startupTimeoutMs}ms budget — raise per-server "startupTimeoutSec"/"startupTimeoutMs" or env MIXDOG_MCP_STARTUP_TIMEOUT_MS`);
+                        err.code = 'EMCPSTARTUPTIMEOUT';
+                        rej(err);
+                    }, startupTimeoutMs);
+                });
+                ({ instructions, toolsResult } = await Promise.race([handshake, guard]));
+            } else {
+                ({ instructions, toolsResult } = await handshake);
+            }
+        } catch (err) {
+            if (startupTimedOut) {
+                // Tear down the pending transport/child so a hung handshake never
+                // leaks a stdio process or socket — fire-and-forget (like the
+                // tool-call timeout path) so a slow tree-kill never delays this
+                // server's failure or the parallel batch's resolution.
+                try { _closeServer({ client, transport }).catch(() => {}); }
+                catch { /* ignore */ }
+                // Never let the late handshake settle into an unhandled rejection.
+                handshake.catch(() => {});
+            }
+            throw err;
+        } finally {
+            if (startupTimer) clearTimeout(startupTimer);
+        }
+        if (!toolsResult || !Array.isArray(toolsResult.tools)) {
+            throw new Error(`[mcp-client] ListTools returned invalid shape for "${name}": missing or non-array tools field`);
+        }
+        if (genAtStart !== _connectAbortGeneration) {
+            // disconnectAll() ran mid-handshake: never register — tear down.
+            try { await _closeServer({ client, transport }); }
+            catch { /* ignore */ }
+            throw new Error(`MCP server "${name}" connect aborted by shutdown`);
+        }
+        const tools = toolsResult.tools.map((t) => ({
+            name: `mcp__${name}__${t.name}`,
+            description: t.description || '',
+            inputSchema: (t.inputSchema || { type: 'object', properties: {} }),
+            ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
+        }));
+        const toolNames = tools.map(t => t.name);
+        servers.set(name, { name, client, transport, tools, cfg, instructions });
+        _invalidateMcpToolFieldMemo();
+        mcpLog(`[mcp] connected: ${tools.length} tools — ${toolNames.join(', ')}\n`);
+    }
+    finally {
+        _pendingConnects.delete(pending);
     }
-    const tools = toolsResult.tools.map((t) => ({
-        name: `mcp__${name}__${t.name}`,
-        description: t.description || '',
-        inputSchema: (t.inputSchema || { type: 'object', properties: {} }),
-        ...(t.annotations && typeof t.annotations === 'object' ? { annotations: t.annotations } : {}),
-    }));
-    const toolNames = tools.map(t => t.name);
-    servers.set(name, { name, client, transport, tools, cfg, instructions });
-    _invalidateMcpToolFieldMemo();
-    mcpLog(`[mcp] connected: ${tools.length} tools — ${toolNames.join(', ')}\n`);
 }

package/src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs

@@ -301,6 +301,21 @@ function nativeAnthropicTools(opts) {
         ? opts.nativeTools.filter(t => t && typeof t === 'object')
         : [];
 }
+// Map the orchestrator-level opts.toolChoice into Anthropic's tool_choice.
+// Only 'none' is activated: it lets the hard-cap final turn keep the tool
+// DEFINITIONS in-request (so the tools->system->messages prefix — and its
+// prompt-cache prefix — stay byte-identical to prior turns) while forbidding
+// tool USE, so the model can only emit text. Forced values
+// ('required'->{type:'any'}, {name}->{type:'tool'}) are deliberately NOT
+// mapped: Anthropic returns a 400 for any forced tool_choice while
+// extended/adaptive thinking is enabled, and the only caller that sets
+// opts.toolChoice='required' (the forced-first-tool turn) runs with
+// effort/thinking active on reasoning models — activating it would convert a
+// previously-harmless no-op into a hard 400 on exactly that turn. Attached
+// only when the request actually carries tools (see buildRequestBody).
+function toAnthropicToolChoice(toolChoice) {
+    return toolChoice === 'none' ? { type: 'none' } : undefined;
+}
 function deferredAnthropicTools(activeTools, opts) {
     if (opts?.session?.deferredNativeTools !== true) return [];
     // A request whose ONLY tools are deferred is rejected by the API with
@@ -464,10 +479,25 @@ function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_
         return -1;
     };
 
+    const firstRequestUserPromptIdx = () => {
+        // Iteration-1 fallback: on the very first request a session has only the
+        // current user prompt — no tool_result tail and no earlier user turn, so
+        // both anchors above return -1 and NO message breakpoint is placed. That
+        // left the whole tools+system prefix (~4.2k) uncached on iter1: nothing
+        // was written, so iter2 re-sent it as a fresh full write instead of a
+        // read hit. Anchor the current prompt's tail so the stable prefix is
+        // cache-written on the first ask and read back on the next. Only used
+        // when neither real anchor exists, so later turns still prefer the
+        // tool_result / previous-user-text anchors (never the volatile new
+        // prompt). Synthetic <system-reminder> turns are excluded by hasUserText.
+        if (latestToolResultTailIdx() !== -1 || previousUserTextAnchorIdx() !== -1) return -1;
+        const tailIdx = sanitizedMessages.length - 1;
+        return hasUserText(sanitizedMessages[tailIdx]) ? tailIdx : -1;
+    };
     if (messageTtl !== null) {
         const slots = Math.max(0, Math.min(4, Number(messageSlots) || 0));
         const marked = new Set();
-        const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx()];
+        const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx(), firstRequestUserPromptIdx()];
         for (const idx of candidates) {
             if (slots <= 0) break;
             if (idx < 0 || marked.has(idx) || !canMarkMessageIdx(idx)) continue;
@@ -597,6 +627,13 @@ function buildRequestBody(messages, model, tools, sendOpts) {
         // a slot that's better spent on messages tail.
         body.tools = [...nativeTools, ...toAnthropicTools([...(tools || []), ...deferredTools])];
     }
+    // tool_choice only when tools are actually present (Anthropic rejects
+    // tool_choice without tools). 'none' rides the hard-cap final turn to
+    // forbid tool USE while keeping the tools prefix stable for cache reuse.
+    if (body.tools) {
+        const toolChoice = toAnthropicToolChoice(opts.toolChoice);
+        if (toolChoice) body.tool_choice = toolChoice;
+    }
 
     applyAnthropicEffortToBody(body, {
         model,

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -308,6 +308,22 @@ function nativeAnthropicTools(opts) {
         ? opts.nativeTools.filter(t => t && typeof t === 'object')
         : [];
 }
+// Map the orchestrator-level opts.toolChoice into Anthropic's tool_choice.
+// Only 'none' is activated: it lets the hard-cap final turn keep the tool
+// DEFINITIONS in-request (so the tools->system->messages prefix — and its
+// prompt-cache prefix — stay byte-identical to prior turns) while forbidding
+// tool USE, so the model can only emit text. Forced values
+// ('required'->{type:'any'}, {name}->{type:'tool'}) are deliberately NOT
+// mapped: Anthropic returns a 400 for any forced tool_choice while
+// extended/adaptive thinking is enabled, and the only caller that sets
+// opts.toolChoice='required' (the forced-first-tool turn) runs with
+// effort/thinking active on reasoning models — activating it would convert a
+// previously-harmless no-op into a hard 400 on exactly that turn. Attached
+// only when the request actually carries tools (see _doSend). Mirrors
+// anthropic-oauth.mjs.
+function toAnthropicToolChoice(toolChoice) {
+    return toolChoice === 'none' ? { type: 'none' } : undefined;
+}
 function deferredAnthropicTools(activeTools, opts) {
     if (opts?.session?.deferredNativeTools !== true) return [];
     // Guard against an all-deferred tools array — the API rejects it with
@@ -458,10 +474,25 @@ function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_
         return -1;
     };
 
+    const firstRequestUserPromptIdx = () => {
+        // Iteration-1 fallback: on the very first request a session has only the
+        // current user prompt — no tool_result tail and no earlier user turn, so
+        // both anchors above return -1 and NO message breakpoint is placed. That
+        // left the whole tools+system prefix (~4.2k) uncached on iter1: nothing
+        // was written, so iter2 re-sent it as a fresh full write instead of a
+        // read hit. Anchor the current prompt's tail so the stable prefix is
+        // cache-written on the first ask and read back on the next. Only used
+        // when neither real anchor exists, so later turns still prefer the
+        // tool_result / previous-user-text anchors (never the volatile new
+        // prompt). Synthetic <system-reminder> turns are excluded by hasUserText.
+        if (latestToolResultTailIdx() !== -1 || previousUserTextAnchorIdx() !== -1) return -1;
+        const tailIdx = sanitizedMessages.length - 1;
+        return hasUserText(sanitizedMessages[tailIdx]) ? tailIdx : -1;
+    };
     if (messageTtl !== null) {
         const slots = Math.max(0, Math.min(4, Number(messageSlots) || 0));
         const marked = new Set();
-        const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx()];
+        const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx(), firstRequestUserPromptIdx()];
         for (const idx of candidates) {
             if (slots <= 0) break;
             if (idx < 0 || marked.has(idx) || !canMarkMessageIdx(idx)) continue;
@@ -578,6 +609,13 @@ export class AnthropicProvider {
             // Anthropic prefix semantics (order: tools → system → messages).
             params.tools = [...nativeTools, ...toAnthropicTools([...(tools || []), ...deferredAnthropicTools(tools || [], opts)])];
         }
+        // tool_choice only when tools are actually present (Anthropic rejects
+        // tool_choice without tools). 'none' rides the hard-cap final turn to
+        // forbid tool USE while keeping the tools prefix stable for cache reuse.
+        if (params.tools) {
+            const toolChoice = toAnthropicToolChoice(opts.toolChoice);
+            if (toolChoice) params.tool_choice = toolChoice;
+        }
         // Known tool names for the shared parseSSEStream leaked-tool-call guard
         // (same guard fixes both Anthropic providers). Recovered leaked calls
         // are only synthesized when they name a tool actually offered here.