@sema-ai/core 1.275.1

package/dist/engine/loop/agent-loop.js

@@ -0,0 +1,1490 @@
+/**
+ * First-party agent loop (design/118 ④a — de-vendoring 4/6).
+ *
+ * Rewritten from the vendored openclaw distillation with the loop's control flow made EXPLICIT as a
+ * state machine (the CC query.ts State/transition shape, sema deps injected): every "go around again"
+ * is a named {@link LoopContinue} and every exit is a named {@link LoopTerminal}, so tests can assert
+ * WHICH path ran (test/loop-transitions.test.ts) instead of inferring it from event order. ④a is
+ * behavior-1:1 with the vendored loop — no new recovery chains; those land in ④b as new Continue
+ * reasons on this skeleton.
+ *
+ * Load-bearing invariants carried over verbatim (the VENDORED EDIT provenance comments are kept at
+ * their sites as history):
+ * - A-1 layer ② abort-before-stream guard (a mid-batch abort must never reach the next provider
+ *   request) — {@link runSingleTurn} entry guard, Terminal `aborted_before_stream`.
+ * - Durable double-execution gate (a deferred parallel tool closure must never run its side effect
+ *   after a mid-batch suspend/abort) — {@link executePreparedToolCall} entry guard.
+ * - D4 post-hook posture (afterToolCall throw must not rewrite a committed side effect into a flat
+ *   failure) — {@link finalizeExecutedToolCall}.
+ * - The TWO queue drain points (1.204 priority wiring基石): steer drains at every turn end
+ *   (Continue `steer_injected` / mid-work boundary), followUp drains only when the agent would
+ *   otherwise stop (Continue `follow_up_injected`). Never merge these into one queue.
+ * - text_delta.partial reconstruction (upstream cherry-pick 6fcc945702).
+ */
+import { EventStream as LlmEventStream } from "../llm/index.js";
+import { findToolByName, validateToolArguments } from "../llm/index.js";
+// VENDORED EDIT (design/136 §2.4, same class as the design/115 P0 findToolByName edit): the retired-tool
+// tombstone table lives with OLD_TO_NEW in core (single "historical names" archive point); the roster-miss
+// branch consults it AFTER findToolByName so a deployment's own same-named tool always wins.
+import { TOMBSTONED_TOOLS } from "../../core/tool-name-aliases.js";
+import { resolveAgentCoreStreamFn } from "./runtime-deps.js";
+const EMPTY_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+const EventStreamConstructor = LlmEventStream;
+function appendTextDeltaToAssistantMessage(message, contentIndex, delta) {
+    const content = [...message.content];
+    const currentContent = content[contentIndex];
+    content[contentIndex] =
+        currentContent?.type === "text"
+            ? { ...currentContent, text: currentContent.text + delta }
+            : { type: "text", text: delta };
+    return { ...message, content };
+}
+function resolveAssistantMessageUpdate(event, currentMessage) {
+    if ("partial" in event && event.partial) {
+        return event.partial;
+    }
+    if (event.type === "text_delta") {
+        return appendTextDeltaToAssistantMessage(currentMessage, event.contentIndex, event.delta);
+    }
+    return currentMessage;
+}
+/**
+ * Start an agent loop with a new prompt message.
+ * The prompt is added to the context and events are emitted for it.
+ */
+export function agentLoop(prompts, context, config, signal, streamFn, runtime) {
+    const stream = createAgentStream();
+    void runAgentLoop(prompts, context, config, async (event) => {
+        stream.push(event);
+    }, signal, streamFn, runtime)
+        .then((messages) => {
+        stream.end(messages);
+    })
+        .catch((error) => {
+        pushLoopFailure(stream, config, error, signal?.aborted === true);
+    });
+    return stream;
+}
+/**
+ * Continue an agent loop from the current context without adding a new message.
+ * Used for retries - context already has user message or tool results.
+ *
+ * **Important:** The last message in context must convert to a `user` or `toolResult` message
+ * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
+ * This cannot be validated here since `convertToLlm` is only called once per turn.
+ */
+export function agentLoopContinue(context, config, signal, streamFn, runtime) {
+    if (context.messages.length === 0) {
+        throw new Error("Cannot continue: no messages in context");
+    }
+    if (context.messages[context.messages.length - 1].role === "assistant") {
+        throw new Error("Cannot continue from message role: assistant");
+    }
+    const stream = createAgentStream();
+    void runAgentLoopContinue(context, config, async (event) => {
+        stream.push(event);
+    }, signal, streamFn, runtime)
+        .then((messages) => {
+        stream.end(messages);
+    })
+        .catch((error) => {
+        pushLoopFailure(stream, config, error, signal?.aborted === true);
+    });
+    return stream;
+}
+/** Run a prompt-started loop and emit events through a caller-owned sink. */
+export async function runAgentLoop(prompts, context, config, emit, signal, streamFn, runtime, trace) {
+    const newMessages = [...prompts];
+    const currentContext = {
+        ...context,
+        messages: [...context.messages, ...prompts],
+    };
+    await emit({ type: "agent_start" });
+    await emit({ type: "turn_start" });
+    for (const prompt of prompts) {
+        await emit({ type: "message_start", message: prompt });
+        await emit({ type: "message_end", message: prompt });
+    }
+    await runLoop(currentContext, newMessages, config, signal, emit, streamFn, runtime, trace);
+    return newMessages;
+}
+/** Continue an existing loop context and emit only newly produced messages. */
+export async function runAgentLoopContinue(context, config, emit, signal, streamFn, runtime, trace) {
+    if (context.messages.length === 0) {
+        throw new Error("Cannot continue: no messages in context");
+    }
+    if (context.messages[context.messages.length - 1].role === "assistant") {
+        throw new Error("Cannot continue from message role: assistant");
+    }
+    const newMessages = [];
+    const currentContext = { ...context };
+    await emit({ type: "agent_start" });
+    await emit({ type: "turn_start" });
+    await runLoop(currentContext, newMessages, config, signal, emit, streamFn, runtime, trace);
+    return newMessages;
+}
+function createAgentStream() {
+    return new EventStreamConstructor((event) => event.type === "agent_end", (event) => (event.type === "agent_end" ? event.messages : []));
+}
+function createLoopFailureMessage(config, error, aborted) {
+    return {
+        role: "assistant",
+        content: [{ type: "text", text: "" }],
+        api: config.model.api,
+        provider: config.model.provider,
+        model: config.model.id,
+        usage: EMPTY_USAGE,
+        stopReason: aborted ? "aborted" : "error",
+        errorMessage: error instanceof Error ? error.message : String(error),
+        timestamp: Date.now(),
+    };
+}
+function pushLoopFailure(stream, config, error, aborted) {
+    const failureMessage = createLoopFailureMessage(config, error, aborted);
+    stream.push({ type: "message_start", message: failureMessage });
+    stream.push({ type: "message_end", message: failureMessage });
+    stream.push({ type: "turn_end", message: failureMessage, toolResults: [] });
+    stream.push({ type: "agent_end", messages: [failureMessage] });
+}
+// ④b default prompt-too-long classifier: conservative provider-message patterns (an integrator with a
+// typed error channel overrides via `recovery.promptTooLong.detect`). Only consulted when a recovery
+// hook is configured. Honest cost note: a false positive triggers one bounded recover() call — at the
+// harness wiring that PERSISTS a forced compaction to the session (visible, not free), so patterns
+// stay word-bounded and error-scoped; recovery-less runs are untouched either way.
+const PROMPT_TOO_LONG_RE = /context.{0,3}length|context_length|context window (?:limit|exceeded)|reached its context window|prompt is too long|too many tokens|maximum context|exceeds? .{0,30}(?:context|token)|input is too long|\b413\b/i;
+/** No non-blank text/thinking and no tool calls — mirrors the harness's empty-failure-persistence skip. */
+function isBlankFailureContent(message) {
+    return message.content.every((c) => c.type === "text" ? c.text.trim() === "" : c.type === "thinking" ? c.thinking.trim() === "" : false);
+}
+function defaultDetectPromptTooLong(message) {
+    return message.stopReason === "error" && PROMPT_TOO_LONG_RE.test(message.errorMessage ?? "");
+}
+/**
+ * M1 (docs/PARITY-CONTEXT-TRANSACTIONS-2026-07-10 §4, CC 2.1.198 withhold parity): hold back the
+ * message_start/message_end of a stream-final that LOOKS like a recoverable prompt-too-long failure
+ * (error stop + classifier match + blank content — the same predicate the recovery gate uses), so
+ * the loop can decide the recovery outcome BEFORE consumers see any error. CC 198 does this inside
+ * its stream decoder (`claude-cli-2.1.198.pretty.js:473371-473374`, `if (!$s) yield`); ours is a
+ * hold-buffer at the loop's emit seam (degrading.ts heldStart pattern, adapted to the final).
+ *
+ * Safety shape: a real PTL rejection fails BEFORE the provider streams anything, so its
+ * message_start is the terminal-path one (emitted together with message_end, carrying the final
+ * error message) — both get held as a unit. A LIVE partial start (stopReason "stop" placeholder,
+ * stream-engine emptyAssistant) is never a candidate and passes through untouched, and once a live
+ * start went out we never hold the end (no dangling message_start on a later discard). All other
+ * events pass through verbatim — non-PTL error ordering is untouched by construction.
+ */
+function createPtlWithholdBuffer(emit, detect) {
+    const held = [];
+    let liveStartEmitted = false;
+    const isCandidate = (message) => message.role === "assistant" &&
+        message.stopReason === "error" &&
+        detect(message) &&
+        isBlankFailureContent(message);
+    return {
+        sink: async (event) => {
+            if (event.type === "message_start" && isCandidate(event.message)) {
+                held.push(event); // terminal-path start of a candidate failure (paired with its end below)
+                return;
+            }
+            if (event.type === "message_end" && !liveStartEmitted && isCandidate(event.message)) {
+                held.push(event);
+                return;
+            }
+            if (event.type === "message_start")
+                liveStartEmitted = true;
+            await emit(event);
+        },
+        async flush() {
+            for (const event of held.splice(0))
+                await emit(event);
+        },
+        discard() {
+            held.length = 0;
+        },
+    };
+}
+/** S2 (design/119): retry nudge for a `toolUse` stop that carried zero parseable tool calls. */
+function createMalformedToolUseNudge() {
+    return {
+        role: "custom",
+        customType: "loop:malformed-tool-use-retry",
+        content: "Your previous response indicated tool use but contained no valid tool call. Re-issue the tool call(s) now, with complete and valid JSON arguments — provide exactly one JSON value per parameter, and do not truncate.",
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+/** S2 (design/119): retry nudge for a turn that produced only internal reasoning, no visible output. */
+function createThinkingOnlyNudge() {
+    return {
+        role: "custom",
+        customType: "loop:thinking-only-retry",
+        content: "Your previous response had no visible output — it contained only internal reasoning. Respond now with your answer as visible text (or make the required tool calls); do not end the turn with reasoning alone.",
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+/** design/124 tier A: continue nudge after a partially-finalized (mid-stream cut, promoted) "stop" turn.
+ *  Separate message + counter from the truncated-output nudge — the cause differs (connection loss, not a
+ *  token budget) and the model already sees the brain's "may be incomplete" warning in the transcript. */
+function createMidstreamPartialContinueNudge() {
+    return {
+        role: "custom",
+        customType: "loop:midstream-partial-continue",
+        content: "Your previous response was cut off mid-stream by a connection failure — the content above may be incomplete. Continue EXACTLY where you left off; do not repeat any content you already produced, do not re-introduce or summarize.",
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+/** The ④b synthetic continue nudge — a non-displayed custom message (convertToLlm renders it as user). */
+/** T1-4: the different-approach nudge after a degenerate-repetition cutoff (same custom-message shape as
+ *  the truncated-output continue — event ordering flows through the normal pending-message path). */
+function createDegenerateRecoveryNudge() {
+    return {
+        role: "custom",
+        customType: "loop:degenerate-output-recovery",
+        content: "Your previous reply degenerated into repetition and was cut off. Do NOT repeat or continue that text. " +
+            "Take a DIFFERENT approach: state your next concrete step or conclusion in one short sentence, then proceed normally.",
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+/** design/130 P2b: the write-out nudge after a walltime cutoff — the salvaged prefix stays in the
+ *  transcript; the model gets ONE short final turn inside the reserved cushion. */
+function createWalltimeCutoffRecoveryNudge() {
+    return {
+        role: "custom",
+        customType: "loop:walltime-cutoff-recovery",
+        content: "Your previous response crossed the task's wall-clock deadline and was cut off (the partial text above is preserved). " +
+            "This is the FINAL turn: write your best current answer / deliverables NOW in one short response — no new work, no long commands.",
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+/** service [405] codex delta-b: the length-stop variant for a turn whose whole budget went to
+ *  (non-replayed) reasoning — "continue where you left off" would point at nothing the provider
+ *  can see. Ask for the answer directly. */
+function createReasoningCutContinueNudge() {
+    return {
+        role: "custom",
+        customType: "loop:truncated-output-continue",
+        content: "Your previous response hit the output-token limit before producing any visible text (the budget went to internal reasoning). " +
+            "Do NOT restart the long reasoning: state your current best answer or next concrete action directly as visible text (or make the required tool call) now.",
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+function createContinueNudge() {
+    return {
+        role: "custom",
+        customType: "loop:truncated-output-continue",
+        content: "Your previous response was cut off because it hit the output-token limit. Continue EXACTLY where you left off — do not repeat any content you already produced, do not re-introduce or summarize.",
+        display: false,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Main loop logic shared by agentLoop and agentLoopContinue.
+ *
+ * Drive rule (identical to the vendored nested while-loops, made explicit):
+ * - While work remains (`hasMoreToolCalls || pendingMessages`), run turns; after each turn drain
+ *   the STEERING queue (drain point A — mid-work boundary).
+ * - When work runs out, drain the FOLLOW-UP queue (drain point B — the agent was about to stop);
+ *   a non-empty drain re-enters the turn loop, an empty one is the natural `completed` Terminal.
+ * Every Terminal path emits `agent_end` exactly once.
+ */
+async function runLoop(initialContext, newMessages, initialConfig, signal, emit, streamFn, runtime, trace) {
+    const state = {
+        context: initialContext,
+        config: initialConfig,
+        newMessages,
+        firstTurn: true,
+        // Check for steering messages at start (user may have typed while waiting)
+        pendingMessages: (await initialConfig.getSteeringMessages?.()) || [],
+        hasMoreToolCalls: true,
+        truncatedOutputContinues: 0,
+        // [477] 1.253 双轨终审 MED: seed from HISTORY, not 0 — the `staticReasoningCut` tag is persisted
+        // on each downgraded assistant message, so a resumed run (suspend/resume rebuilds LoopState)
+        // counts prior downgrades instead of re-granting a fresh 2-recovery budget every runLoop.
+        staticReasoningCutRecoveries: initialContext.messages.filter((m) => m.role === "assistant" && m.staticReasoningCut === true).length,
+        degenerateContinues: 0,
+        walltimeCutoffContinues: 0,
+        malformedToolUseRetries: 0,
+        thinkingOnlyRetries: 0,
+        midstreamPartialContinues: 0,
+    };
+    while (true) {
+        if (!state.hasMoreToolCalls && state.pendingMessages.length === 0) {
+            // Drain point B: the agent would otherwise stop. Follow-up messages route through the same
+            // pending-message path so event ordering matches steering messages.
+            const followUpMessages = (await state.config.getFollowUpMessages?.()) || [];
+            if (followUpMessages.length === 0) {
+                trace?.({ kind: "terminal", reason: "completed" });
+                break;
+            }
+            state.pendingMessages = followUpMessages;
+            trace?.({ kind: "continue", reason: "follow_up_injected" });
+        }
+        const outcome = await runSingleTurn(state, signal, emit, streamFn, runtime, trace);
+        if (outcome.kind === "terminal") {
+            trace?.({ kind: "terminal", reason: outcome.reason });
+            // Terminal turns have already emitted `agent_end`.
+            return;
+        }
+        // Only a turn with actual further work is a Continue; a turn that ran dry falls through to the
+        // top-of-loop decision (drain point B → follow_up_injected, or the natural `completed` Terminal).
+        if (outcome.recovered) {
+            trace?.({ kind: "continue", reason: outcome.recovered });
+        }
+        else if (state.pendingMessages.length > 0) {
+            trace?.({ kind: "continue", reason: "steer_injected" });
+        }
+        else if (state.hasMoreToolCalls) {
+            trace?.({ kind: "continue", reason: "next_turn" });
+        }
+    }
+    await emit({ type: "agent_end", messages: state.newMessages });
+}
+/** [477]: per-run stop-loss for static reasoning-cut downgrades — the 3rd reasoning-only static
+ *  max_tokens hit fails loud again (no infinite truncate/continue token burn on a budget-ignoring
+ *  thinking model). */
+const MAX_STATIC_REASONING_CUT_RECOVERIES = 2;
+/** One turn: A-1 guard → inject pending → stream assistant → tool batch → boundary hooks → drain steer. */
+async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
+    // VENDORED EDIT provenance (audit A-1 layer ②, design/64 §28.3): an abort that fired during the
+    // previous turn's tool batch used to reach the next streamAssistantResponse anyway, which fails
+    // fast on the aborted signal and synthesizes an EMPTY stopReason:"aborted" assistant message —
+    // persisted into the session BETWEEN the interrupted batch and its later reconcile tool_results,
+    // leaving the session a permanently invalid sequence for strict providers (assistant tool_calls
+    // not all answered before the next assistant). Exit cleanly instead: no doomed request, no junk
+    // message; the caller's interrupt reconcile then appends its synthetic tool_results directly
+    // after the real batch — a legal transcript. (Durable invariant — see design/45.)
+    if (signal?.aborted) {
+        await emit({ type: "agent_end", messages: state.newMessages });
+        return { kind: "terminal", reason: "aborted_before_stream" };
+    }
+    if (!state.firstTurn) {
+        await emit({ type: "turn_start" });
+    }
+    else {
+        state.firstTurn = false;
+    }
+    // Process pending messages (inject before next assistant response)
+    if (state.pendingMessages.length > 0) {
+        for (const message of state.pendingMessages) {
+            await emit({ type: "message_start", message });
+            await emit({ type: "message_end", message });
+            state.context.messages.push(message);
+            state.newMessages.push(message);
+        }
+    }
+    // Stream assistant response. design/120 P2: the in-stream executor is PER-STREAM (a PTL retry
+    // below gets a fresh one); it is created unconditionally — with streamingToolExecution unset it
+    // admits nothing and every path below sees an empty executor (exactly the pre-P2 behavior).
+    let executor = new StreamToolExecutor(state.context, state.config, signal, emit);
+    // design/120 §5.2 settle barrier: after ANY stream final, await every in-flight in-stream call
+    // before any later step — recovery, terminal reconciliation and the batch pipeline must all start
+    // with zero in-stream work in flight. try/finally (codex impl-review BLOCKER-2): a THROW out of
+    // the stream (an emit/hook throw is the reachable case — brains report errors as events, not
+    // throws) must still settle, or admitted side effects would outlive the loop-failure terminal
+    // with nobody awaiting them. settle() never rejects (runOne's belt catch). Results still held at
+    // a throw are unrecoverable by design (no final assistant exists to own them in the transcript) —
+    // documented limitation, same shape as the pre-P2 loop-failure path.
+    // [477]: grant the brain the static reasoning-cut → recoverable-length downgrade only while the
+    // loop can actually recover it (truncated-output recovery configured — without the continue chain
+    // a downgraded `length` would just end the run as a silent empty stop, strictly worse than the
+    // fail-loud error) and the per-run stop-loss budget lasts.
+    const staticReasoningCutDowngrade = state.config.recovery?.truncatedOutput !== undefined &&
+        state.staticReasoningCutRecoveries < MAX_STATIC_REASONING_CUT_RECOVERIES;
+    // M1 (PARITY-CONTEXT-TRANSACTIONS §4): while a PTL recovery could still be attempted, withhold a
+    // candidate failure's message_start/message_end from consumers — CC 198 holds these errors inside
+    // its stream decoder (`:473371-473374`) and only leaks them once recovery's outcome is known.
+    // Recovery succeeded ⇒ the failed assistant is never seen (matches the existing pop-from-context);
+    // failed/declined/gate-unmet ⇒ flush() leaks the events at that point. The terminal truth is
+    // unchanged — only the interim "error → continued anyway" sequence disappears. Live visibility of
+    // the retry is deliberately given up (by-design trade, `withholdErrorEvents: false` restores it).
+    const ptl = state.config.recovery?.promptTooLong;
+    const ptlDetect = ptl?.detect ?? defaultDetectPromptTooLong;
+    const withholdEnabled = ptl !== undefined && (ptl.withholdErrorEvents ?? true);
+    let withhold = withholdEnabled ? createPtlWithholdBuffer(emit, ptlDetect) : undefined;
+    let message;
+    try {
+        message = await streamAssistantResponse(state.context, state.config, signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade);
+    }
+    finally {
+        await executor.settle();
+    }
+    // ④b recovery chain — prompt-too-long: retry INSIDE the turn (no extra `turn_start`). The failed
+    // assistant is dropped from the retry context and never enters the run's returned messages; its
+    // stream events are WITHHELD above (M1) until the recovery outcome is known. The recover() hook
+    // owns the policy (compact/trim); the loop owns the bounded transition (CC reactive-compact adapted).
+    {
+        if (ptl) {
+            const detect = ptlDetect;
+            const maxRetries = ptl.maxRetries ?? 2;
+            let attempt = 0;
+            while (message.stopReason === "error" &&
+                !signal?.aborted &&
+                detect(message) &&
+                // Recovery is gated on an EMPTY failure (no non-blank text/thinking, no tool calls) — the
+                // same predicate the harness uses to SKIP persisting failure assistants. A partial-content
+                // failure was already persisted by message_end, so popping it here would fork the in-memory
+                // context from the session (and a retry would leave adjacent assistants in the transcript);
+                // surface it as the terminal error instead, exactly like the pre-④b loop.
+                isBlankFailureContent(message) &&
+                // design/120 P2 guard: an in-stream side effect already happened ⇒ never pop-and-retry
+                // (the retried model would re-issue the call = double execution). A REAL prompt-too-long
+                // failure produces no output, so its executor is always empty — zero loss. This also covers
+                // the content-loss tear path isBlankFailureContent alone can't see (empty content, work
+                // done); note the merge-back in streamAssistantResponse already de-blanks that message, so
+                // this clause is belt-and-suspenders.
+                executor.admittedCount === 0 &&
+                attempt < maxRetries) {
+                attempt++;
+                // Drop the failed assistant from the context tail before handing the transcript to recover().
+                if (state.context.messages[state.context.messages.length - 1] === message) {
+                    state.context.messages.pop();
+                }
+                // Contract says recover() must not throw; treat a throw as "recovery declined" (belt), never
+                // as a new failure that would swallow the original prompt-too-long error.
+                let replaced;
+                try {
+                    replaced = await ptl.recover(state.context.messages, attempt);
+                }
+                catch {
+                    replaced = undefined;
+                }
+                if (!replaced) {
+                    // Recovery declined — restore the failed assistant so downstream sees the true transcript.
+                    // (Its withheld events leak via the flush below — the decline IS the known outcome.)
+                    state.context.messages.push(message);
+                    break;
+                }
+                // M1: recovery replaced the transcript — the failed assistant's withheld events are
+                // discarded (consumers never see the recovered error), and the retry stream gets a fresh
+                // buffer (the retry itself may hit prompt-too-long again).
+                withhold?.discard();
+                withhold = withholdEnabled ? createPtlWithholdBuffer(emit, ptlDetect) : undefined;
+                state.context.messages = replaced;
+                trace?.({ kind: "continue", reason: "reactive_compact_retry" });
+                executor = new StreamToolExecutor(state.context, state.config, signal, emit); // per-stream
+                try {
+                    message = await streamAssistantResponse(state.context, state.config, signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade);
+                }
+                finally {
+                    await executor.settle(); // same throw-safety as the first stream (BLOCKER-2)
+                }
+            }
+        }
+    }
+    // M1: whatever is still held now has a KNOWN outcome — retries exhausted, recovery declined, or
+    // the gate never fired (aborted / maxRetries 0). Leak it here so the consumer's terminal truth is
+    // exactly the pre-M1 one (message_start+message_end of the surviving failure, original order).
+    await withhold?.flush();
+    state.newMessages.push(message);
+    // [477]: count each downgraded reasoning-cut turn against the per-run stop-loss (the brain tags
+    // them; once the budget is spent the grant above goes false and the next hit fails loud).
+    if (message.staticReasoningCut === true)
+        state.staticReasoningCutRecoveries++;
+    // T1-4 recovery — degenerate-repetition cutoff: the brain already cancelled the stream and salvaged the
+    // prefix into this errored turn. Ending the run here voids all prior work over one bad sampling run; nudge
+    // a DIFFERENT-approach continue instead, bounded to consecutive maxContinues (default 2). The cut-off turn
+    // stays in the transcript (its salvaged text is real context; the model sees what it repeated). On the
+    // cap, fall through to the normal error terminal (assemble → output.degenerate + salvagedOutput).
+    {
+        const degen = state.config.recovery?.degenerateOutput;
+        if (degen &&
+            message.stopReason === "error" &&
+            !signal?.aborted &&
+            degen.detect(message) &&
+            // codex 1.238 F2 (BLOCKER, r2 补角): a tool_call anywhere on this errored assistant — an admitted
+            // in-stream call OR a completed-but-unexecuted call in the final content (non-streaming path) —
+            // means recovering past it hands the provider a tool_call with no tool_result (4xx on strict
+            // providers). Gate BOTH faces; the rare degenerate+tool-call combo falls through to the error
+            // terminal, whose harvest writes the results correctly.
+            executor.admittedCount === 0 &&
+            message.content.every((b) => b.type !== "toolCall") &&
+            state.degenerateContinues < (degen.maxContinues ?? 2)) {
+            state.degenerateContinues++;
+            // codex F1: this turn still ENDED — emit its turn_end (the zero-shell usage rides the message with
+            // the brain's usageMissing flag) so turn accounting and save-points hold across the recovery.
+            await emit({ type: "turn_end", message, toolResults: [] });
+            // codex F5 (steer wins): drain the boundary steer first — a user redirect drives the next turn and
+            // suppresses the nudge; the continue is counted either way (bounded).
+            const drained = (await state.config.getSteeringMessages?.()) || [];
+            state.pendingMessages = drained.length > 0 ? drained : [createDegenerateRecoveryNudge()];
+            return { kind: "ran", recovered: "degenerate_output_recovery" };
+        }
+        if (message.stopReason !== "error")
+            state.degenerateContinues = 0;
+    }
+    // design/130 P2b — walltime-cutoff write-out recovery: the brain cut this turn at the soft
+    // per-call deadline (deliberate, salvaged prefix in the transcript). Ending the run here would
+    // void the reserved write-out cushion; nudge ONE bounded final turn instead. Same shape and
+    // gates as the degenerate recovery above (codex 1.238 F2: any tool_call face — admitted
+    // in-stream OR completed-but-unexecuted in content — forces the error terminal, whose harvest
+    // writes the results correctly). The counter is NOT reset on success: the deadline only gets
+    // nearer, so the cap bounds the whole run (no cutoff/recover ping-pong; the error terminal then
+    // assembles as timeout + salvagedOutput).
+    {
+        const wc = state.config.recovery?.walltimeCutoff;
+        if (wc &&
+            message.stopReason === "error" &&
+            !signal?.aborted &&
+            wc.detect(message) &&
+            executor.admittedCount === 0 &&
+            message.content.every((b) => b.type !== "toolCall") &&
+            state.walltimeCutoffContinues < (wc.maxContinues ?? 1)) {
+            state.walltimeCutoffContinues++;
+            // codex F1 (same as degenerate): this turn still ENDED — emit its turn_end so turn
+            // accounting and save-points hold across the recovery.
+            await emit({ type: "turn_end", message, toolResults: [] });
+            // codex F5 (steer wins): a boundary steer (e.g. the runner's finalize instruction, if it
+            // already fired) drives the write-out turn and suppresses the generic nudge.
+            const drained = (await state.config.getSteeringMessages?.()) || [];
+            state.pendingMessages = drained.length > 0 ? drained : [createWalltimeCutoffRecoveryNudge()];
+            return { kind: "ran", recovered: "walltime_cutoff_recovery" };
+        }
+    }
+    if (message.stopReason === "error" || message.stopReason === "aborted") {
+        // design/120 §5.4: in-stream side effects already happened — commit their REAL results before
+        // the terminal (a real result beats the wake-reconcile [INTERRUPTED] synthesis); unstarted
+        // calls stay for wake A-1. With an empty executor this is exactly the pre-P2 path.
+        const errorFinalResults = await harvestExecutorOnErrorFinal(executor, state, message, signal, emit);
+        // design/130 P2b (codex HIGH): a WALLTIME-CUT final may carry tool calls that CLOSED before the
+        // cut but were never admitted for execution — the harvest above only covers executor-admitted
+        // entries, so those calls would persist unanswered (a strict provider 4xxes the next request on
+        // this session forever). Synthesize an error toolResult for each uncovered call, scoped to the
+        // walltime cutoff ONLY (the pre-existing degenerate/error terminals keep their long-standing
+        // behavior — widening this is a separate decision).
+        if (state.config.recovery?.walltimeCutoff?.detect(message)) {
+            const covered = new Set(errorFinalResults.map((r) => r.toolCallId));
+            for (const tc of message.content.filter((c) => c.type === "toolCall")) {
+                if (covered.has(tc.id))
+                    continue;
+                const synthetic = {
+                    role: "toolResult",
+                    toolCallId: tc.id,
+                    toolName: tc.name,
+                    content: [{ type: "text", text: "[call aborted by walltime cutoff — never executed]" }],
+                    isError: true,
+                    timestamp: Date.now(),
+                };
+                await emitToolResultMessage(synthetic, emit);
+                state.context.messages.push(synthetic);
+                state.newMessages.push(synthetic);
+                errorFinalResults.push(synthetic);
+            }
+        }
+        await emit({ type: "turn_end", message, toolResults: errorFinalResults });
+        await emit({ type: "agent_end", messages: state.newMessages });
+        return { kind: "terminal", reason: "assistant_error" };
+    }
+    // Check for tool calls
+    const toolCalls = message.content.filter((c) => c.type === "toolCall");
+    const toolResults = [];
+    state.hasMoreToolCalls = false;
+    if (toolCalls.length > 0) {
+        const executedToolBatch = await executeToolCalls(state.context, message, state.config, signal, emit, executor);
+        toolResults.push(...executedToolBatch.messages);
+        state.hasMoreToolCalls = !executedToolBatch.terminate;
+        for (const result of toolResults) {
+            state.context.messages.push(result);
+            state.newMessages.push(result);
+        }
+    }
+    else {
+        // Extreme contract breach: a done final with ZERO toolCall content while the executor admitted
+        // work (the batch pipeline never runs, so its orphan drain can't). Close the pairs here (F-3).
+        for (const orphan of executor.remaining()) {
+            executor.take(orphan.toolCall.id);
+            await closeOrphanedStreamEntry(orphan, emit);
+        }
+    }
+    await emit({ type: "turn_end", message, toolResults });
+    const nextTurnContext = {
+        message,
+        toolResults,
+        context: state.context,
+        newMessages: state.newMessages,
+    };
+    const nextTurnSnapshot = await state.config.prepareNextTurn?.(nextTurnContext);
+    if (nextTurnSnapshot) {
+        state.context = nextTurnSnapshot.context ?? state.context;
+        state.config = Object.assign({}, state.config, {
+            model: nextTurnSnapshot.model ?? state.config.model,
+            reasoning: nextTurnSnapshot.thinkingLevel === undefined
+                ? state.config.reasoning
+                : nextTurnSnapshot.thinkingLevel === "off"
+                    ? undefined
+                    : nextTurnSnapshot.thinkingLevel,
+        });
+    }
+    if (await state.config.shouldStopAfterTurn?.({
+        message,
+        toolResults,
+        context: state.context,
+        newMessages: state.newMessages,
+    })) {
+        await emit({ type: "agent_end", messages: state.newMessages });
+        return { kind: "terminal", reason: "stop_requested" };
+    }
+    // Drain point A (mid-work boundary): steering messages inject before the next provider request.
+    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+    // ④b recovery chain — truncated output: a `length`-stopped answer with NO tool calls would end
+    // the run mid-sentence. When enabled, inject a synthetic continue nudge (through the normal
+    // pending-message path so event ordering matches every other injected message) and run another
+    // turn — bounded to `maxContinues` CONSECUTIVE times; any non-length turn resets the counter.
+    // A length-stop WITH tool calls needs no nudge (the tool results drive the next turn anyway).
+    const truncated = state.config.recovery?.truncatedOutput;
+    if (message.stopReason === "length") {
+        if (truncated &&
+            toolCalls.length === 0 &&
+            // A steer drained at this same boundary means the USER redirected — their message drives the
+            // next turn; appending a "continue exactly where you left off" nudge after it would fight the
+            // redirect from the recency position. The continue counter is untouched (no nudge happened).
+            state.pendingMessages.length === 0 &&
+            state.truncatedOutputContinues < (truncated.maxContinues ?? 3)) {
+            state.truncatedOutputContinues++;
+            // codex 实现审 #2: this early return would skip the midstream-partial reset below, so a
+            // partial→length-recovery→partial alternation would be miscounted as CONSECUTIVE partials and
+            // burn the 3-nudge budget early. A length turn is never a partial-finalized stop — reset here too.
+            state.midstreamPartialContinues = 0;
+            // service [405] codex delta-b: a length stop with NO visible text (reasoning consumed the
+            // budget — the dynamicCut shape) must NOT say "continue where you left off": reasoning is not
+            // replayed to OpenAI-family providers, so the model would see an empty assistant + a request
+            // to seamlessly continue nothing. Ask for a fresh visible answer instead.
+            const noVisibleText = !message.content.some((c) => c.type === "text" && c.text.trim() !== "");
+            state.pendingMessages = [...state.pendingMessages, noVisibleText ? createReasoningCutContinueNudge() : createContinueNudge()];
+            return { kind: "ran", recovered: "max_output_tokens_recovery" };
+        }
+    }
+    else {
+        state.truncatedOutputContinues = 0;
+    }
+    // design/124 tier A downstream: a partially-finalized "stop" turn (mid-stream cut whose substantive
+    // prefix was promoted to content by the brain) must not end an autonomous run as an incomplete
+    // success — there is no user to notice the "may be incomplete" warning and re-prompt. Bounded
+    // continue nudge, truncatedOutput 范式: steer wins (a drained redirect suppresses the nudge), own
+    // counter + own message (never mixed with the length-stop budget), consecutive-reset. Always on
+    // (no config gate): the flag only ever appears when the brain recovered a mid-stream failure, and
+    // ending silently there is strictly worse for every integrator. A `partialFinalized` toolUse turn
+    // takes the normal tool path above — its results drive the next turn anyway.
+    if (message.stopReason === "stop" && message.partialFinalized === true) {
+        if (toolCalls.length === 0 &&
+            state.pendingMessages.length === 0 &&
+            state.midstreamPartialContinues < 3) {
+            state.midstreamPartialContinues++;
+            state.pendingMessages = [createMidstreamPartialContinueNudge()];
+            return { kind: "ran", recovered: "midstream_partial_recovery" };
+        }
+    }
+    else {
+        state.midstreamPartialContinues = 0;
+    }
+    // S2 recovery (design/119, CC 198 :473745-): a `toolUse` stop whose every tool call was dropped as
+    // malformed (the brain already appended a visible note) used to end the run silently mid-task —
+    // the model believes it acted, nothing ran. Nudge a retry, bounded per run. Steer wins (same
+    // reasoning as the truncated-output guard above).
+    const malformed = state.config.recovery?.malformedToolUse;
+    if (malformed &&
+        message.stopReason === "toolUse" &&
+        toolCalls.length === 0 &&
+        state.pendingMessages.length === 0 &&
+        state.malformedToolUseRetries < (malformed.maxRetries ?? 1)) {
+        state.malformedToolUseRetries++;
+        state.pendingMessages = [createMalformedToolUseNudge()];
+        return { kind: "ran", recovered: "malformed_tool_use_retry" };
+    }
+    // S2 recovery (design/119, CC 198 :473786- — the adaptive-thinking companion): a normal stop whose
+    // content is ONLY thinking (no non-blank text, no tool calls) is a silent empty success. Nudge the
+    // model to answer visibly, bounded per run. Steer wins.
+    const thinkingOnly = state.config.recovery?.thinkingOnly;
+    if (thinkingOnly &&
+        message.stopReason === "stop" &&
+        toolCalls.length === 0 &&
+        state.pendingMessages.length === 0 &&
+        state.thinkingOnlyRetries < (thinkingOnly.maxRetries ?? 1) &&
+        message.content.some((c) => c.type === "thinking") &&
+        !message.content.some((c) => c.type === "text" && c.text.trim() !== "")) {
+        state.thinkingOnlyRetries++;
+        state.pendingMessages = [createThinkingOnlyNudge()];
+        return { kind: "ran", recovered: "thinking_only_retry" };
+    }
+    return { kind: "ran" };
+}
+/**
+ * Stream an assistant response from the LLM.
+ * This is where AgentMessage[] gets transformed to Message[] for the LLM.
+ */
+async function streamAssistantResponse(context, config, signal, emit, streamFn, runtime, executor, staticReasoningCutDowngrade) {
+    // Apply context transform if configured (AgentMessage[] → AgentMessage[])
+    let messages = context.messages;
+    if (config.transformContext) {
+        messages = await config.transformContext(messages, signal);
+    }
+    // Convert to LLM-compatible messages (AgentMessage[] → Message[])
+    const llmMessages = await config.convertToLlm(messages);
+    // Build LLM context
+    const llmContext = {
+        systemPrompt: context.systemPrompt,
+        messages: llmMessages,
+        tools: context.tools,
+    };
+    const streamFunction = resolveAgentCoreStreamFn(runtime, streamFn);
+    // Resolve API key (important for expiring tokens)
+    const resolvedApiKey = (config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;
+    // design/130 P1: a wall-clock-aware host may shrink THIS call's output cap; evaluated per call
+    // (the spread below would otherwise carry the run-static maxTokens snapshot).
+    const perCallMaxTokens = config.maxTokensPerCall?.();
+    // design/130 P2b: soft per-call wall-clock deadline — a brain that observes the wall clock
+    // crossing it cuts the stream (salvaging the prefix) instead of riding into the hard abort.
+    const perCallDeadlineMs = config.callDeadlineMsPerCall?.();
+    const response = await streamFunction(config.model, llmContext, {
+        ...config,
+        // service [405]: `maxTokensDynamic` marks the cap as ENGINE-shrunk — a reasoning-only
+        // max_tokens hit then degrades to a recoverable `length` stop instead of the fail-loud error.
+        ...(perCallMaxTokens !== undefined ? { maxTokens: perCallMaxTokens, maxTokensDynamic: true } : {}),
+        ...(perCallDeadlineMs !== undefined ? { callDeadlineMs: perCallDeadlineMs } : {}),
+        // [477]: the loop's per-run stop-loss grant for the STATIC reasoning-cut downgrade (the static
+        // sibling of maxTokensDynamic above) — a reasoning-only static max_tokens hit then degrades to
+        // a recoverable `length` the truncated-output continue picks up.
+        ...(staticReasoningCutDowngrade === true ? { staticReasoningCutDowngrade: true } : {}),
+        apiKey: resolvedApiKey,
+        signal,
+    });
+    let partialMessage = null;
+    let addedPartial = false;
+    for await (const event of response) {
+        switch (event.type) {
+            case "start": {
+                const message = event.partial;
+                partialMessage = message;
+                context.messages.push(message);
+                addedPartial = true;
+                await emit({ type: "message_start", message: { ...message } });
+                break;
+            }
+            case "text_start":
+            case "text_delta":
+            case "text_end":
+            case "thinking_start":
+            case "thinking_delta":
+            case "thinking_end":
+            case "toolcall_start":
+            case "toolcall_delta":
+            case "toolcall_end":
+                if (partialMessage) {
+                    const message = resolveAssistantMessageUpdate(event, partialMessage);
+                    partialMessage = message;
+                    context.messages[context.messages.length - 1] = message;
+                    await emit({
+                        type: "message_update",
+                        assistantMessageEvent: event,
+                        message: { ...message },
+                    });
+                }
+                // design/120 P2: a completed-arguments call may start executing while the stream is live.
+                // Admission (opt-in flag + safe tool + source-order barrier + cap) lives in the executor;
+                // when it declines, the call simply waits for the post-stream batch pipeline as before.
+                // `partialMessage` may be null on a protocol-violating stream (toolcall_end before start) —
+                // that DECLINE must still go through the executor so the source-order barrier rises
+                // (impl-review F-1: skipping maybeAdmit entirely let a LATER safe call execute in-stream
+                // before this earlier bounced one, breaking the admitted-is-a-prefix invariant).
+                if (event.type === "toolcall_end" && executor) {
+                    executor.maybeAdmit(event.toolCall, partialMessage);
+                }
+                break;
+            case "done":
+            case "error": {
+                const finalMessage = await response.result();
+                // design/120 §5.4 content-loss defense: an error/aborted final must not drop a toolCall
+                // block whose call ALREADY executed in-stream (persistence point is message_end below).
+                if (executor && (finalMessage.stopReason === "error" || finalMessage.stopReason === "aborted")) {
+                    mergeBackAdmittedCalls(finalMessage, executor);
+                }
+                if (addedPartial) {
+                    context.messages[context.messages.length - 1] = finalMessage;
+                }
+                else {
+                    context.messages.push(finalMessage);
+                }
+                if (!addedPartial) {
+                    await emit({ type: "message_start", message: { ...finalMessage } });
+                }
+                await emit({ type: "message_end", message: finalMessage });
+                return finalMessage;
+            }
+        }
+    }
+    const finalMessage = await response.result();
+    if (executor && (finalMessage.stopReason === "error" || finalMessage.stopReason === "aborted")) {
+        mergeBackAdmittedCalls(finalMessage, executor); // same defense for the no-terminal-event path
+    }
+    if (addedPartial) {
+        context.messages[context.messages.length - 1] = finalMessage;
+    }
+    else {
+        context.messages.push(finalMessage);
+        await emit({ type: "message_start", message: { ...finalMessage } });
+    }
+    await emit({ type: "message_end", message: finalMessage });
+    return finalMessage;
+}
+/**
+ * Execute tool calls from an assistant message.
+ */
+async function executeToolCalls(currentContext, assistantMessage, config, signal, emit, executor) {
+    const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
+    if (config.toolExecution === "sequential") {
+        // Explicit whole-batch serial override — semantics preserved (design/120 §1.2). The in-stream
+        // executor never admits under this mode (its very first admission check), so there is nothing
+        // to harvest here.
+        return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit);
+    }
+    // design/120 P1: partitioned execution replaces the old any-sequential→whole-batch-serial pre-scan
+    // (which kept mixed read/write batches — the main beneficiary — fully serial forever). Consecutive
+    // concurrency-safe calls run as one capped parallel batch; unsafe calls run as singleton batches;
+    // batches execute strictly in assistant source order. Safe = explicit `executionMode:"parallel"`
+    // or a true-returning input hook — fail-closed for undeclared tools (CC 2.1.206 TOOL_DEFAULTS
+    // parity; see isCallConcurrencySafe below). The defineTool effect derivation maps read → parallel
+    // and write/idempotent/undeclared → sequential.
+    return executeToolCallsPartitioned(currentContext, assistantMessage, toolCalls, config, signal, emit, executor);
+}
+async function executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit) {
+    const finalizedCalls = [];
+    const messages = [];
+    for (const toolCall of toolCalls) {
+        await emit({
+            type: "tool_execution_start",
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            args: toolCall.arguments,
+        });
+        const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
+        let finalized;
+        if (preparation.kind === "immediate") {
+            finalized = {
+                toolCall,
+                result: preparation.result,
+                isError: preparation.isError,
+            };
+        }
+        else {
+            const executed = await executePreparedToolCall(preparation, signal, emit);
+            finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
+        }
+        await emitToolExecutionEnd(finalized, emit);
+        const toolResultMessage = createToolResultMessage(finalized);
+        await emitToolResultMessage(toolResultMessage, emit);
+        finalizedCalls.push(finalized);
+        messages.push(toolResultMessage);
+        if (signal?.aborted) {
+            break;
+        }
+    }
+    return {
+        messages,
+        terminate: shouldTerminateToolBatch(finalizedCalls),
+    };
+}
+/**
+ * design/120 P1.5 (CC `isConcurrencySafe(parsedInput)` parity): per-CALL concurrency safety.
+ * FAIL-CLOSED direction (CC 2.1.206 `TOOL_DEFAULTS.isConcurrencySafe → false`, pretty.js:280839):
+ * only an explicit `executionMode:"parallel"` (static opt-in — CC's statically-true read tools) or a
+ * true-returning input-level `isConcurrencySafe` hook (Bash read-only commands — the one real CC
+ * consumer) makes a call batch-safe. An UNDECLARED tool, an unknown tool name (CC partitioner
+ * `o?.isConcurrencySafe(...)` → false, pretty.js:520091), and a throwing hook are all unsafe.
+ */
+function isCallConcurrencySafe(tool, args) {
+    if (!tool)
+        return false;
+    if (tool.executionMode === "parallel")
+        return true;
+    if (!tool.isConcurrencySafe)
+        return false;
+    try {
+        return tool.isConcurrencySafe(args) === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * CC 2.1.206 partition parity (pretty.js:520087-520096): a call is batch-safe ONLY if its arguments
+ * VALIDATE against the tool's schema (CC `safeParse` — a malformed call never rides a parallel batch;
+ * it stays a singleton and surfaces its validation error at execution) AND the tool/hook opts in.
+ * The hook sees the validated+coerced args — same as CC handing `parsed.data` to `isConcurrencySafe`.
+ */
+function isBatchSafeToolCall(tool, toolCall) {
+    if (!tool)
+        return false;
+    let args;
+    try {
+        args = validateToolArguments(tool, prepareToolCallArguments(tool, toolCall));
+    }
+    catch {
+        return false;
+    }
+    return isCallConcurrencySafe(tool, args);
+}
+/** design/120 P1: consecutive-safe partitioning (CC 198 partitionToolCalls semantics). */
+function partitionToolCalls(toolCalls, tools) {
+    const batches = [];
+    for (const tc of toolCalls) {
+        // VENDORED EDIT provenance (design/115 P0): alias-aware lookup, same as the old pre-scan.
+        const safe = isBatchSafeToolCall(findToolByName(tools, tc.name), tc);
+        const last = batches[batches.length - 1];
+        if (safe && last?.safe) {
+            last.calls.push(tc);
+        }
+        else {
+            batches.push({ safe, calls: [tc] });
+        }
+    }
+    return batches;
+}
+/** Minimal semaphore for the per-batch concurrency cap (design/120 §1.3; CC default 10). */
+async function runCapped(thunks, limit) {
+    const results = new Array(thunks.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(limit, thunks.length)) }, async () => {
+        while (next < thunks.length) {
+            const i = next++;
+            results[i] = await thunks[i]();
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * design/120 P1 — partitioned batch execution. Per partition: SERIAL preflight in source order
+ * (tool_execution_start + prepare + the design/37 gate — a suspending gate can therefore never fire
+ * before an earlier-source-order batch has executed: deliberate divergence from CC, whose per-call
+ * chains run concurrently but which has no durable suspend), then capped-concurrent execution, then
+ * the batch's tool-result message artifacts in source order (so each batch's results are committed
+ * before the next batch's gates run — design/120 §1.2 premise). The durable double-execution gate
+ * inside executePreparedToolCall and the mid-batch abort semantics are unchanged: an abort leaves
+ * the current batch's unstarted closures and ALL later batches unexecuted (the dangling set the
+ * interrupt reconcile / suspendedBatch machinery already handles — sub-batch boundaries are NOT
+ * persisted, checkpoint batchToolCallIds stays the whole assistant batch).
+ */
+async function executeToolCallsPartitioned(currentContext, assistantMessage, toolCalls, config, signal, emit, executor) {
+    const cap = config.maxToolConcurrency ?? 10;
+    const allFinalized = [];
+    const messages = [];
+    // design/120 P2 harvest: commit the in-stream executor's held outcomes FIRST (finalize with the
+    // FINAL assistant message + tool_execution_end + tool-result message), before any batch
+    // preflight/gate runs — a later gate's durable checkpoint (batchContextAt scans committed
+    // toolResults) then counts every already-executed call in completedCallIds, so the resume-side
+    // [DEFERRED] ("it was NOT executed") can never lie about an executed call. The source-order
+    // barrier makes admitted calls a leading prefix of the batch, so this commit order IS the P1
+    // source order. Harvest iterates ALL calls (not prefix-break) as a hardening: even if a provider
+    // violated the ordering contract, an executed call is never re-run by the batch pipeline below.
+    const remainingCalls = [];
+    for (const toolCall of toolCalls) {
+        const held = executor?.take(toolCall.id);
+        if (!held) {
+            remainingCalls.push(toolCall);
+            continue;
+        }
+        const finalized = await finalizeStreamEntry(currentContext, assistantMessage, held, config, signal);
+        await emitToolExecutionEnd(finalized, emit);
+        const toolResultMessage = createToolResultMessage(finalized);
+        await emitToolResultMessage(toolResultMessage, emit);
+        allFinalized.push(finalized);
+        messages.push(toolResultMessage);
+    }
+    // A done-final content is a superset of admitted calls (the P2.0 provider contract), so the
+    // executor is fully drained above; anything left is a contract breach — drop the outcome but
+    // close its in-stream start with a synthetic end so id-pairing consumers never hang (F-3).
+    if (executor) {
+        for (const orphan of executor.remaining()) {
+            executor.take(orphan.toolCall.id);
+            await closeOrphanedStreamEntry(orphan, emit);
+        }
+    }
+    const batches = partitionToolCalls(remainingCalls, currentContext.tools);
+    outer: for (const batch of batches) {
+        if (signal?.aborted)
+            break;
+        // Serial preflight (source order): start events + prepare + gate. Immediate outcomes (blocked /
+        // not-found / validation failures) finalize here, exactly like both pre-P1 paths.
+        const entries = [];
+        for (const toolCall of batch.calls) {
+            await emit({
+                type: "tool_execution_start",
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+                args: toolCall.arguments,
+            });
+            const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal);
+            if (preparation.kind === "immediate") {
+                const finalized = { toolCall, result: preparation.result, isError: preparation.isError };
+                await emitToolExecutionEnd(finalized, emit);
+                entries.push({ finalized, toolCall });
+            }
+            else {
+                entries.push({ prepared: preparation, toolCall });
+            }
+            if (signal?.aborted) {
+                // Mid-preflight abort: later calls in this batch and all later batches stay unstarted —
+                // same dangling-set shape as the pre-P1 paths.
+                await settleBatch(entries, true);
+                break outer;
+            }
+        }
+        await settleBatch(entries, batch.safe);
+    }
+    return { messages, terminate: shouldTerminateToolBatch(allFinalized) };
+    /** Execute the batch's prepared calls (capped-concurrent when safe, serial otherwise), then emit
+     *  this batch's tool-result messages in source order. */
+    async function settleBatch(entries, concurrent) {
+        const runOne = (prepared) => async () => {
+            const executed = await executePreparedToolCall(prepared, signal, emit);
+            const finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, signal);
+            await emitToolExecutionEnd(finalized, emit);
+            return finalized;
+        };
+        const preparedEntries = entries.filter((e) => e.prepared);
+        let executedResults;
+        if (concurrent && preparedEntries.length > 1) {
+            executedResults = await runCapped(preparedEntries.map((e) => runOne(e.prepared)), cap);
+        }
+        else {
+            executedResults = [];
+            for (const e of preparedEntries) {
+                executedResults.push(await runOne(e.prepared)());
+            }
+        }
+        let idx = 0;
+        for (const e of entries) {
+            const finalized = e.finalized ?? executedResults[idx++];
+            if (!finalized)
+                continue;
+            allFinalized.push(finalized);
+            const toolResultMessage = createToolResultMessage(finalized);
+            await emitToolResultMessage(toolResultMessage, emit);
+            messages.push(toolResultMessage);
+        }
+    }
+}
+/**
+ * design/120 P2: executes concurrency-safe tool calls WHILE the model is still streaming.
+ *
+ * Lifecycle is per-stream (one instance per streamAssistantResponse call — the PTL-retry re-stream
+ * gets a fresh one). Admission (see {@link AgentLoopConfig.streamingToolExecution}) is deliberately
+ * narrower than CC's: opt-in flag + non-sequential dispatch + safe tool + source-order barrier + cap.
+ * The barrier is the CC processQueue FIFO-break equivalent, hardened: once ANY call bounces to the
+ * post-stream batch pipeline, every later call bounces too, so an admitted set is always a leading
+ * prefix of the assistant batch — a source-order-later call can never execute before a bounced
+ * source-order-earlier one, and the harvest's commit order stays identical to the P1 source order.
+ *
+ * In-stream we emit ONLY `tool_execution_start` (at launch) and `tool_execution_update` (the tool's
+ * own onUpdate). Finalization (afterToolCall), `tool_execution_end` and the tool-result message
+ * artifacts are all deferred to the post-stream harvest, where the FINAL assistant message exists —
+ * a mid-stream partial must never reach the tool_result hook or the session (message artifacts
+ * committed mid-stream would interleave illegally with the still-open assistant message).
+ */
+class StreamToolExecutor {
+    context;
+    config;
+    signal;
+    emit;
+    entries = new Map();
+    admittedOrder = [];
+    barrier = false;
+    inFlight = 0;
+    constructor(context, config, signal, emit) {
+        this.context = context;
+        this.config = config;
+        this.signal = signal;
+        this.emit = emit;
+    }
+    /** Number of calls this executor admitted (0 ⇒ the stream behaved exactly as pre-P2). */
+    get admittedCount() {
+        return this.admittedOrder.length;
+    }
+    /** All admitted calls in admission order (read-only; used by the error-final content merge-back). */
+    admittedToolCalls() {
+        return this.admittedOrder.map((id) => this.entries.get(id)?.toolCall).filter((tc) => tc !== undefined);
+    }
+    /**
+     * Admission check + launch for a call whose arguments just completed mid-stream (`toolcall_end`).
+     * Every rejection raises the source-order barrier — from then on this executor admits nothing.
+     */
+    maybeAdmit(toolCall, partialAssistant) {
+        if (this.barrier)
+            return;
+        if (this.config.streamingToolExecution !== true ||
+            this.config.toolExecution === "sequential" ||
+            this.signal?.aborted ||
+            partialAssistant === null || // protocol violation (no start yet) — bounce AND raise the barrier
+            !isBatchSafeToolCall(findToolByName(this.context.tools, toolCall.name), toolCall) || // P1.5: same per-call judgment as the batch partitioner (schema-invalid ⇒ unsafe, CC 206 parity)
+            this.inFlight >= (this.config.maxToolConcurrency ?? 10) ||
+            this.entries.has(toolCall.id) // defensive: at-most-once per id (provider contract)
+        ) {
+            this.barrier = true;
+            return;
+        }
+        const entry = { toolCall, promise: Promise.resolve() };
+        this.entries.set(toolCall.id, entry);
+        this.admittedOrder.push(toolCall.id);
+        entry.promise = this.runOne(entry, partialAssistant);
+    }
+    async runOne(entry, partialAssistant) {
+        this.inFlight++;
+        try {
+            await this.emit({
+                type: "tool_execution_start",
+                toolCallId: entry.toolCall.id,
+                toolName: entry.toolCall.name,
+                args: entry.toolCall.arguments,
+            });
+            // Full prepare chain — defense in depth: beforeToolCall (block / updatedInput) works exactly
+            // as on the batch path. The host's streamingToolExecution opt-in promises it cannot durably
+            // suspend here. `partialAssistant` is the documented hook-payload snapshot (design/120 §5).
+            const preparation = await prepareToolCall(this.context, partialAssistant, entry.toolCall, this.config, this.signal);
+            if (preparation.kind === "immediate") {
+                entry.immediate = preparation;
+                return;
+            }
+            entry.prepared = preparation;
+            entry.executed = await executePreparedToolCall(preparation, this.signal, this.emit);
+        }
+        catch (error) {
+            // prepare/execute return error results by contract; this belt catches an emit() throw so
+            // settle() never rejects and the held outcome is still a well-formed error result.
+            entry.immediate = {
+                kind: "immediate",
+                result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
+                isError: true,
+            };
+        }
+        finally {
+            this.inFlight--;
+        }
+    }
+    /**
+     * The stream-final barrier (design/120 §5.2): await every in-flight call. MUST run after ANY
+     * stream final (done/error/aborted) and before any later step — the batch pipeline therefore
+     * starts with zero in-stream calls in flight (sequential exclusivity + the concurrency cap hold
+     * structurally), and nothing can emit after the turn exits.
+     */
+    async settle() {
+        this.barrier = true;
+        await Promise.all([...this.entries.values()].map((e) => e.promise));
+    }
+    /** After settle: remove and return the held outcome for a call id (undefined = not admitted). */
+    take(id) {
+        const entry = this.entries.get(id);
+        if (entry)
+            this.entries.delete(id);
+        return entry;
+    }
+    /** After settle: entries not yet taken, in admission order (the error-final harvest). */
+    remaining() {
+        return this.admittedOrder
+            .map((id) => this.entries.get(id))
+            .filter((e) => e !== undefined);
+    }
+}
+/** Finalize one held executor entry into the standard outcome shape (afterToolCall runs HERE, with
+ *  the final assistant message — never a mid-stream partial). */
+async function finalizeStreamEntry(currentContext, assistantMessage, entry, config, signal) {
+    if (entry.prepared && entry.executed) {
+        return finalizeExecutedToolCall(currentContext, assistantMessage, entry.prepared, entry.executed, config, signal);
+    }
+    const immediate = entry.immediate ?? {
+        kind: "immediate",
+        // Unreachable after settle() (runOne always sets one of the outcome fields) — fail honest.
+        result: createErrorToolResult("in-stream execution produced no outcome"),
+        isError: true,
+    };
+    return { toolCall: entry.toolCall, result: immediate.result, isError: immediate.isError };
+}
+/**
+ * design/120 impl-review F-3: an executor entry whose call cannot be attached to the transcript
+ * (missing from the final content — a provider-contract breach) already emitted
+ * `tool_execution_start` in-stream; close the start/end pair with a synthetic error end so
+ * activity/spinner consumers that pair by toolCallId never hold a permanently-open call. The
+ * outcome itself is dropped (an ownerless toolResult would be an illegal transcript).
+ */
+async function closeOrphanedStreamEntry(entry, emit) {
+    await emit({
+        type: "tool_execution_end",
+        toolCallId: entry.toolCall.id,
+        toolName: entry.toolCall.name,
+        result: createErrorToolResult("in-stream result dropped: the call is missing from the final assistant content (provider contract breach)"),
+        isError: true,
+    });
+}
+/**
+ * design/120 §5.4 error/aborted-final harvest: commit every held outcome (the side effects already
+ * happened — a real result beats a wake-reconcile [INTERRUPTED] synthesis), in admission order,
+ * BEFORE the terminal turn_end/agent_end. Unstarted calls stay untouched — the existing wake A-1
+ * reconcile closes them honestly.
+ */
+async function harvestExecutorOnErrorFinal(executor, state, finalMessage, signal, emit) {
+    const held = executor.remaining();
+    if (held.length === 0)
+        return [];
+    const results = [];
+    const persistedCallIds = new Set(finalMessage.content.filter((c) => c.type === "toolCall").map((c) => c.id));
+    for (const entry of held) {
+        executor.take(entry.toolCall.id);
+        // A result may only enter the transcript when its toolCall exists on the persisted assistant —
+        // the merge-back in streamAssistantResponse makes this the norm; a missing id here means the
+        // merge-back path was bypassed (defensive), and an ownerless toolResult would be an illegal
+        // transcript, so the outcome is dropped — with a synthetic end closing its in-stream start (F-3).
+        if (!persistedCallIds.has(entry.toolCall.id)) {
+            await closeOrphanedStreamEntry(entry, emit);
+            continue;
+        }
+        const finalized = await finalizeStreamEntry(state.context, finalMessage, entry, state.config, signal);
+        await emitToolExecutionEnd(finalized, emit);
+        const toolResultMessage = createToolResultMessage(finalized);
+        await emitToolResultMessage(toolResultMessage, emit);
+        state.context.messages.push(toolResultMessage);
+        state.newMessages.push(toolResultMessage);
+        results.push(toolResultMessage);
+    }
+    return results;
+}
+/**
+ * design/120 §5.4 content-loss defense: an error/aborted final whose message dropped mid-stream
+ * blocks (the stream-engine tear path synthesizes an EMPTY-content error assistant) would leave an
+ * already-executed in-stream call with zero transcript trace — no toolCall on the assistant, so its
+ * result could never be attached and even wake reconcile couldn't see an orphan. Merge the
+ * executor-held calls back into the final content BEFORE message_end (the persistence point).
+ * The message also stops qualifying as an empty-failure skip, so it persists.
+ */
+function mergeBackAdmittedCalls(finalMessage, executor) {
+    const admitted = executor.admittedToolCalls();
+    if (admitted.length === 0)
+        return;
+    const present = new Set(finalMessage.content.filter((c) => c.type === "toolCall").map((c) => c.id));
+    const missing = admitted.filter((tc) => !present.has(tc.id));
+    if (missing.length === 0)
+        return;
+    finalMessage.content = [...finalMessage.content, ...missing];
+}
+function shouldTerminateToolBatch(finalizedCalls) {
+    return (finalizedCalls.length > 0 &&
+        finalizedCalls.every((finalized) => finalized.result.terminate === true));
+}
+function prepareToolCallArguments(tool, toolCall) {
+    if (!tool.prepareArguments) {
+        return toolCall;
+    }
+    const preparedArguments = tool.prepareArguments(toolCall.arguments);
+    if (preparedArguments === toolCall.arguments) {
+        return toolCall;
+    }
+    return {
+        ...toolCall,
+        arguments: preparedArguments,
+    };
+}
+async function prepareToolCall(currentContext, assistantMessage, toolCall, config, signal) {
+    const tool = findToolByName(currentContext.tools, toolCall.name);
+    if (!tool) {
+        // design/136 §2.4 — TOMBSTONED tool names get an explicit migration message (immediate error result,
+        // model can self-correct) instead of the generic not-found. Checked ONLY on a roster miss, so a
+        // deployment-defined custom tool of the same name wins (the tombstone yields).
+        const tombstone = TOMBSTONED_TOOLS[toolCall.name];
+        if (tombstone !== undefined) {
+            return {
+                kind: "immediate",
+                result: createErrorToolResult(tombstone),
+                isError: true,
+            };
+        }
+        // make-real field finding (design/120 验证): a weaker model that guesses a wrong tool name
+        // (bash/cat/exec/read_file…) got a bare "not found" and kept guessing until the run died.
+        // List the real roster so the very next attempt can self-correct — the highest-leverage
+        // recovery text in the loop (bounded: names only).
+        const available = (currentContext.tools ?? []).map((t) => t.name).join(", ");
+        return {
+            kind: "immediate",
+            result: createErrorToolResult(`Tool ${toolCall.name} not found.${available ? ` Available tools: ${available}` : ""}`),
+            isError: true,
+        };
+    }
+    try {
+        const preparedToolCall = prepareToolCallArguments(tool, toolCall);
+        let finalArgs = validateToolArguments(tool, preparedToolCall);
+        if (config.beforeToolCall) {
+            const beforeResult = await config.beforeToolCall({
+                assistantMessage,
+                toolCall,
+                args: finalArgs,
+                context: currentContext,
+            }, signal);
+            if (signal?.aborted) {
+                return {
+                    kind: "immediate",
+                    result: createErrorToolResult("Operation aborted"),
+                    isError: true,
+                };
+            }
+            if (beforeResult?.block) {
+                return {
+                    kind: "immediate",
+                    result: createErrorToolResult(beforeResult.reason || "Tool execution was blocked"),
+                    isError: true,
+                };
+            }
+            // A non-blocking hook may rewrite the args (design/37 `updatedInput`). Re-validate the rewrite
+            // against the tool schema before it can reach `tool.execute()` — a hook must never be able to
+            // smuggle schema-invalid args past validation. Throws propagate to the catch below as an error
+            // tool result, exactly like an invalid model-supplied call.
+            if (beforeResult?.updatedInput !== undefined) {
+                finalArgs = validateToolArguments(tool, {
+                    ...preparedToolCall,
+                    arguments: beforeResult.updatedInput,
+                });
+            }
+        }
+        if (signal?.aborted) {
+            return {
+                kind: "immediate",
+                result: createErrorToolResult("Operation aborted"),
+                isError: true,
+            };
+        }
+        return {
+            kind: "prepared",
+            toolCall,
+            tool,
+            args: finalArgs,
+        };
+    }
+    catch (error) {
+        return {
+            kind: "immediate",
+            result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
+            isError: true,
+        };
+    }
+}
+async function executePreparedToolCall(prepared, signal, emit) {
+    const updateEvents = [];
+    // Upstream-parity gate (2026-07 diff, openclaw 5ea80c8d80 class): a misbehaving tool that keeps
+    // calling onUpdate AFTER its execute() promise settled would otherwise emit
+    // `tool_execution_update` events after `tool_execution_end`/result persistence — an event-order
+    // contract violation. Once the outcome is settled, late updates are silently dropped.
+    let acceptingUpdates = true;
+    // VENDORED EDIT provenance (sema durable-checkpoint hardening): a deferred PARALLEL tool closure
+    // (preflight-gated, then run together in Promise.all) can reach here AFTER a mid-batch durable
+    // suspend/abort fired `signal.abort()`. Without this guard, a tool whose own `execute` ignores
+    // `signal.aborted` would run its side effect on the off-branch turn, yet the durable resume tells
+    // the model that sibling "was NOT executed" → DOUBLE-execution. Short-circuit BEFORE `tool.execute`
+    // so the "not executed" assertion holds unconditionally — even for a non-abort-cooperative tool —
+    // keeping the once-only/exactly-once continuation invariant (design/45 §4.ter).
+    if (signal?.aborted) {
+        return { result: createErrorToolResult("operation aborted before execution"), isError: true };
+    }
+    try {
+        const result = await prepared.tool.execute(prepared.toolCall.id, prepared.args, signal, (partialResult) => {
+            if (!acceptingUpdates) {
+                return;
+            }
+            updateEvents.push(Promise.resolve(emit({
+                type: "tool_execution_update",
+                toolCallId: prepared.toolCall.id,
+                toolName: prepared.toolCall.name,
+                args: prepared.toolCall.arguments,
+                partialResult,
+            })));
+        });
+        acceptingUpdates = false;
+        await Promise.all(updateEvents);
+        return { result, isError: false };
+    }
+    catch (error) {
+        acceptingUpdates = false;
+        await Promise.all(updateEvents);
+        return {
+            result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
+            isError: true,
+        };
+    }
+}
+async function finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, signal) {
+    let result = executed.result;
+    let isError = executed.isError;
+    if (config.afterToolCall) {
+        try {
+            const afterResult = await config.afterToolCall({
+                assistantMessage,
+                toolCall: prepared.toolCall,
+                args: prepared.args,
+                result,
+                isError,
+                context: currentContext,
+            }, signal);
+            if (afterResult) {
+                result = {
+                    content: afterResult.content ?? result.content,
+                    details: afterResult.details ?? result.details,
+                    terminate: afterResult.terminate ?? result.terminate,
+                };
+                isError = afterResult.isError ?? isError;
+            }
+        }
+        catch (error) {
+            // VENDORED EDIT provenance (sema vendored bug-hunt D4): the tool ALREADY executed (its side
+            // effect committed in executePreparedToolCall) BEFORE afterToolCall runs. A throw in the
+            // post-tool hook (sema design/37 tool_result policy) must NOT rewrite a SUCCEEDED
+            // side-effecting tool into a FLAT failure — in our autonomous loop the model "recovers" by
+            // RE-issuing it (duplicate open_pr / double write_file). Keep the real outcome (result/isError
+            // unchanged) and APPEND a note that POST-processing failed; never force isError.
+            const note = `[post-tool processing failed (the tool already executed): ${error instanceof Error ? error.message : String(error)}]`;
+            result = { ...result, content: [...result.content, { type: "text", text: note }] };
+        }
+    }
+    return {
+        toolCall: prepared.toolCall,
+        result,
+        isError,
+    };
+}
+function createErrorToolResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        details: {},
+    };
+}
+async function emitToolExecutionEnd(finalized, emit) {
+    await emit({
+        type: "tool_execution_end",
+        toolCallId: finalized.toolCall.id,
+        toolName: finalized.toolCall.name,
+        result: finalized.result,
+        isError: finalized.isError,
+    });
+}
+function createToolResultMessage(finalized) {
+    return {
+        role: "toolResult",
+        toolCallId: finalized.toolCall.id,
+        toolName: finalized.toolCall.name,
+        content: finalized.result.content,
+        details: finalized.result.details,
+        isError: finalized.isError,
+        timestamp: Date.now(),
+    };
+}
+async function emitToolResultMessage(toolResultMessage, emit) {
+    await emit({ type: "message_start", message: toolResultMessage });
+    await emit({ type: "message_end", message: toolResultMessage });
+}
+//# sourceMappingURL=agent-loop.js.map