omk-agent-core 0.90.8 → 0.91.0

package/dist/agent-loop.js

@@ -3,7 +3,13 @@
  * Transforms to Message[] only at the LLM call boundary.
  */
 import { EventStream, streamSimple, validateToolArguments, } from "omk-ai";
+import { bindToolIdentity, isPlainArguments } from "./builtin-tool-resource-claims.js";
 import { partitionToolBatchWaves } from "./parallel-tool-batch.js";
+import { scheduleDagLevels } from "./tool-dag-scheduler.js";
+import { awaitWithAbort, createErrorToolResult, createImmutableJsonSnapshot, createImmutableSnapshot, finalizeExecutedToolCall, parseJsonValue, stampToolResultEnvelope, } from "./tool-execution-boundary.js";
+import { resolveToolTimeoutMs, runToolCallWithTimeout } from "./tool-timeout.js";
+import { createSyntheticToolResult, inspectTranscriptIntegrity, repairTranscriptIntegrity, } from "./tool-transcript-integrity.js";
+import { createToolResultEnvelope, } from "./types.js";
 const EMPTY_USAGE = {
     input: 0,
     output: 0,
@@ -13,35 +19,76 @@ const EMPTY_USAGE = {
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 };
 /**
- * Terminate the public event stream after the underlying loop rejected.
+ * Decide how to terminate a run after the underlying loop rejected.
  *
- * Mirrors `Agent.handleRunFailure`: synthesizes an assistant failure message
- * so consumers observe a coherent message_start/message_end/turn_end/agent_end
- * sequence, then ends the stream so `for await` consumers and `stream.result()`
- * always settle.
+ * A synthetic assistant failure may only be appended on top of a transcript
+ * whose tool turns are all closed. When `completedMessages` ends with an open
+ * tool turn, a safe missing-only closure (synthetic results for the unambiguous
+ * missing tail calls) is appended first so the failure assistant never creates
+ * an `assistant(tool calls) -> assistant(failure)` interleaving.
  *
- * Invariant: non-abort failures keep stopReason "error" and the same event
- * sequence; when the loop signal was aborted, the synthetic message reports
- * stopReason "aborted".
+ * If the transcript is ambiguous (duplicate/orphan/interleave, or a
+ * mid-transcript gap) it is never auto-repaired: the plan returns no failure
+ * message so the caller ends the stream without fabricating a turn over
+ * corruption. Pure apart from `Date.now()` on the failure message.
  */
-function endStreamWithFailure(stream, config, completedMessages, error, signal) {
-    const failureMessage = {
+export function planFailureTermination(completedMessages, model, error, aborted) {
+    const messages = [...completedMessages];
+    const closureResults = [];
+    if (!inspectTranscriptIntegrity(messages).ok) {
+        try {
+            const repaired = repairTranscriptIntegrity(messages, "Tool result missing; run terminated by error");
+            // repairTranscriptIntegrity appends synthetic results only for
+            // unambiguous missing tail calls; anything ambiguous throws above.
+            for (let i = messages.length; i < repaired.length; i++) {
+                const result = createImmutableSnapshot(repaired[i]);
+                closureResults.push(result);
+                messages.push(result);
+            }
+        }
+        catch {
+            // Ambiguous transcript: never auto-repair. Fail closed without a
+            // synthetic assistant turn over a corrupt transcript.
+            return { messages, failureMessage: undefined, closureResults: [] };
+        }
+    }
+    const failureMessage = createImmutableSnapshot({
         role: "assistant",
         content: [{ type: "text", text: "" }],
-        api: config.model.api,
-        provider: config.model.provider,
-        model: config.model.id,
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
         usage: EMPTY_USAGE,
-        stopReason: signal?.aborted ? "aborted" : "error",
+        stopReason: aborted ? "aborted" : "error",
         errorMessage: error instanceof Error ? error.message : String(error),
         timestamp: Date.now(),
-    };
-    const messages = [...completedMessages, failureMessage];
-    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 });
-    stream.end(messages);
+    });
+    return { messages: [...messages, failureMessage], failureMessage, closureResults };
+}
+/**
+ * Terminate the public event stream after the underlying loop rejected.
+ *
+ * Uses {@link planFailureTermination} so the disposition of any unresolved tool
+ * calls matches transcript repair exactly: an unambiguous open turn is closed
+ * with synthetic results before a coherent
+ * message_start/message_end/turn_end/agent_end sequence for the failure
+ * assistant, and an ambiguous transcript fails closed (agent_end only, no
+ * fabricated assistant). The stream always settles for `for await` consumers
+ * and `stream.result()`.
+ */
+function endStreamWithFailure(stream, config, completedMessages, error, signal) {
+    const plan = planFailureTermination(completedMessages, config.model, error, signal?.aborted ?? false);
+    for (const result of plan.closureResults) {
+        stream.push({ type: "message_start", message: result });
+        stream.push({ type: "message_end", message: result });
+    }
+    if (plan.failureMessage) {
+        stream.push({ type: "message_start", message: plan.failureMessage });
+        stream.push({ type: "message_end", message: plan.failureMessage });
+        stream.push({ type: "turn_end", message: plan.failureMessage, toolResults: [] });
+    }
+    stream.push({ type: "agent_end", messages: plan.messages });
+    stream.end(plan.messages);
 }
 /**
  * Start an agent loop with a new prompt message.
@@ -79,7 +126,7 @@ export function agentLoopContinue(context, config, signal, streamFn) {
     // provider supports assistant pre-fill); only an assistant turn that still
     // carries unresolved tool calls is a hard error because the provider will
     // reject the request without matching tool results.
-    assertContinuableTail(context.messages);
+    assertContinuableTranscript(context.messages);
     const stream = createAgentStream();
     const completedMessages = [];
     void runAgentLoopContinue(context, config, async (event) => {
@@ -96,60 +143,55 @@ export function agentLoopContinue(context, config, signal, streamFn) {
 }
 export async function runAgentLoop(prompts, context, config, emit, signal, streamFn) {
     const newMessages = [...prompts];
-    const currentContext = {
-        ...context,
-        messages: [...context.messages, ...prompts],
-    };
-    await emit({ type: "agent_start" });
-    await emit({ type: "turn_start" });
+    const currentContext = { ...context, messages: [...context.messages, ...prompts] };
+    const publish = (event) => emit(createImmutableSnapshot(event));
+    await publish({ type: "agent_start" });
+    await publish({ type: "turn_start" });
     for (const prompt of prompts) {
-        await emit({ type: "message_start", message: prompt });
-        await emit({ type: "message_end", message: prompt });
+        await publish({ type: "message_start", message: prompt });
+        await publish({ type: "message_end", message: prompt });
     }
-    await runLoop(currentContext, newMessages, config, signal, emit, streamFn);
+    await runLoop(currentContext, newMessages, config, signal, publish, streamFn);
     return newMessages;
 }
 export async function runAgentLoopContinue(context, config, emit, signal, streamFn) {
     if (context.messages.length === 0) {
         throw new Error("Cannot continue: no messages in context");
     }
-    assertContinuableTail(context.messages);
+    assertContinuableTranscript(context.messages);
     const newMessages = [];
     const currentContext = { ...context };
-    await emit({ type: "agent_start" });
-    await emit({ type: "turn_start" });
-    await runLoop(currentContext, newMessages, config, signal, emit, streamFn);
+    const publish = (event) => emit(createImmutableSnapshot(event));
+    await publish({ type: "agent_start" });
+    await publish({ type: "turn_start" });
+    await runLoop(currentContext, newMessages, config, signal, publish, streamFn);
     return newMessages;
 }
 function createAgentStream() {
     return new EventStream((event) => event.type === "agent_end", (event) => (event.type === "agent_end" ? event.messages : []));
 }
 /**
- * Validate that the final message in `messages` is one a provider can continue
- * from without an opaque rejection.
+ * Validate the full transcript before continuing. Replaces the earlier
+ * last-message-only tail check: `assistant(A,B) -> result(A)` and any
+ * duplicate/orphan/interleaved structure now fail before the first provider
+ * request, not only a trailing assistant message that still carries tool calls.
  *
- * - A trailing user/toolResult message is always fine.
- * - A trailing assistant turn is fine ONLY when it carries no unresolved tool
- *   calls. If it does carry tool calls, there is no matching toolResult to send
- *   and every provider (OpenAI/Anthropic/Google) rejects the request, so we
- *   fail fast with a clear, actionable error.
- *
- * This intentionally does NOT inspect `convertToLlm` output: that transform is
- * provider-specific and runs once per turn. The conservative check here keeps
- * the common "continue after a finished text answer" path working (compaction,
- * session resume, explicit retries) while still protecting the broken tool-call
- * case.
+ * A trailing assistant turn with no tool calls (plain text/thinking) remains
+ * continuable, so compaction, session resume, and explicit retries keep working.
  */
-function assertContinuableTail(messages) {
-    const last = messages[messages.length - 1];
-    if (last.role !== "assistant") {
+function assertContinuableTranscript(messages) {
+    const report = inspectTranscriptIntegrity(messages);
+    if (report.ok) {
         return;
     }
-    const hasPendingToolCalls = last.content.some((c) => c.type === "toolCall");
-    if (hasPendingToolCalls) {
+    const last = messages[messages.length - 1];
+    if (last !== undefined && last.role === "assistant" && last.content.some((block) => block.type === "toolCall")) {
         throw new Error("Cannot continue: the last assistant message has pending tool calls without matching results. " +
             "Add tool results or a new user message before continuing.");
     }
+    const summary = report.issues.map((issue) => `${issue.kind}:${issue.toolCallId}`).join(", ");
+    throw new Error(`Cannot continue: invalid tool transcript (${summary}). ` +
+        "Append terminal tool results or repair the transcript before continuing.");
 }
 /**
  * Main loop logic shared by agentLoop and agentLoopContinue.
@@ -184,25 +226,59 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             // Stream assistant response
             const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);
             newMessages.push(message);
+            // Provider output is untrusted protocol input. Reject duplicate call IDs
+            // and every other ambiguous turn before any tool can execute.
+            const emittedIntegrity = inspectTranscriptIntegrity(currentContext.messages);
+            const emittedAmbiguities = emittedIntegrity.issues.filter((issue) => issue.kind !== "missing_result");
+            if (emittedAmbiguities.length > 0) {
+                const summary = emittedAmbiguities.map((issue) => `${issue.kind}:${issue.toolCallId}`).join(", ");
+                throw new Error(`Refusing tool execution: invalid emitted tool transcript (${summary}).`);
+            }
+            const toolCalls = message.content.filter((c) => c.type === "toolCall");
             if (message.stopReason === "error" || message.stopReason === "aborted") {
-                await emit({ type: "turn_end", message, toolResults: [] });
+                const toolResults = [];
+                const reason = message.stopReason === "aborted"
+                    ? "Operation aborted"
+                    : "Skipped because the provider terminated before tool execution";
+                const disposition = message.stopReason === "aborted" ? "aborted" : "skipped";
+                for (const toolCall of toolCalls) {
+                    const result = createImmutableSnapshot(createSyntheticToolResult(toolCall.id, toolCall.name, reason, Date.now(), disposition));
+                    currentContext.messages.push(result);
+                    newMessages.push(result);
+                    toolResults.push(result);
+                    await emitToolResultMessage(result, emit);
+                }
+                await emit({ type: "turn_end", message, toolResults });
                 await emit({ type: "agent_end", messages: newMessages });
                 return;
             }
-            // Check for tool calls
-            const toolCalls = message.content.filter((c) => c.type === "toolCall");
             const toolResults = [];
+            let stopAfterToolBatch = false;
             hasMoreToolCalls = false;
             if (toolCalls.length > 0) {
                 const executedToolBatch = await executeToolCalls(currentContext, message, config, signal, emit);
                 toolResults.push(...executedToolBatch.messages);
                 hasMoreToolCalls = !executedToolBatch.terminate;
-                for (const result of toolResults) {
-                    currentContext.messages.push(result);
-                    newMessages.push(result);
+                stopAfterToolBatch = executedToolBatch.stopRun ?? false;
+                if (signal?.aborted) {
+                    // Close only unresolved calls, preserving finalized results, then stop
+                    // before hooks, queues, or another provider request.
+                    const synthesized = await closeAbortedToolBatch(currentContext, toolCalls, toolResults, emit);
+                    toolResults.push(...synthesized);
+                    for (const result of toolResults)
+                        newMessages.push(result);
+                    await emit({ type: "turn_end", message, toolResults });
+                    await emit({ type: "agent_end", messages: newMessages });
+                    return;
                 }
+                for (const result of toolResults)
+                    newMessages.push(result);
             }
             await emit({ type: "turn_end", message, toolResults });
+            if (stopAfterToolBatch) {
+                await emit({ type: "agent_end", messages: newMessages });
+                return;
+            }
             const nextTurnContext = {
                 message,
                 toolResults,
@@ -250,10 +326,24 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
  * This is where AgentMessage[] gets transformed to Message[] for the LLM.
  */
 async function streamAssistantResponse(context, config, signal, emit, streamFn) {
+    // Validate the full transcript before every provider request. This fails
+    // fast for `assistant(A,B) -> result(A)` and any duplicate/orphan/interleaved
+    // structure that the provider would otherwise reject opaquely.
+    const integrityReport = inspectTranscriptIntegrity(context.messages);
+    if (!integrityReport.ok) {
+        const summary = integrityReport.issues.map((issue) => `${issue.kind}:${issue.toolCallId}`).join(", ");
+        throw new Error(`Refusing provider request: invalid tool transcript (${summary}). ` +
+            "Append terminal tool results or repair the transcript before retrying.");
+    }
     // Apply context transform if configured (AgentMessage[] → AgentMessage[])
     let messages = context.messages;
     if (config.transformContext) {
         messages = await config.transformContext(messages, signal);
+        const transformedIntegrity = inspectTranscriptIntegrity(messages);
+        if (!transformedIntegrity.ok) {
+            const summary = transformedIntegrity.issues.map((issue) => `${issue.kind}:${issue.toolCallId}`).join(", ");
+            throw new Error(`Refusing provider request: transformed context has an invalid tool transcript (${summary}).`);
+        }
     }
     // Convert to LLM-compatible messages (AgentMessage[] → Message[])
     const llmMessages = await config.convertToLlm(messages);
@@ -333,6 +423,11 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn)
  */
 async function executeToolCalls(currentContext, assistantMessage, config, signal, emit) {
     const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
+    // dag-v2 is opt-in only. An explicit sequential execution mode takes
+    // precedence and continues through the established waves-v1 path below.
+    if (config.toolScheduler === "dag-v2" && config.toolExecution !== "sequential") {
+        return executeToolCallsDagLevels(currentContext, assistantMessage, toolCalls, config, signal, emit);
+    }
     const hasSequentialToolCall = toolCalls.some((tc) => currentContext.tools?.find((t) => t.name === tc.name)?.executionMode === "sequential");
     const toolPolicies = new Map();
     for (const tool of currentContext.tools ?? []) {
@@ -371,25 +466,197 @@ async function executeToolCallsInWaves(currentContext, assistantMessage, toolCal
             : await executeToolCallsParallel(currentContext, assistantMessage, waveCalls, config, signal, emit);
         messages.push(...executedWave.messages);
         waveTerminates.push(executedWave.terminate);
-        if (signal?.aborted) {
+        if (signal?.aborted)
             break;
-        }
     }
     return {
         messages,
         terminate: waveTerminates.length > 0 && waveTerminates.every(Boolean),
     };
 }
+/**
+ * Execute a tool-call batch using the dag-v2 scheduler.
+ *
+ * Initial planning applies only the pure argument compatibility shim. Each
+ * candidate level authorizes calls, re-resolves claims from exact final args,
+ * and emits lifecycle starts only when a final safe sublevel begins. Results
+ * remain globally buffered and are emitted in source order.
+ */
+async function executeToolCallsDagLevels(currentContext, assistantMessage, toolCalls, config, signal, emit) {
+    const plans = toolCalls.map((toolCall) => planToolCall(currentContext, toolCall));
+    const boundTools = plans.flatMap((plan) => (plan.kind === "planned" ? [plan.tool] : []));
+    const toolPolicies = new Map();
+    for (const tool of boundTools) {
+        if (tool.executionMode && !toolPolicies.has(tool.name))
+            toolPolicies.set(tool.name, tool.executionMode);
+    }
+    const claimableCalls = [];
+    for (const plan of plans) {
+        if (plan.kind === "immediate" || !isPlainArguments(plan.args)) {
+            claimableCalls.length = 0;
+            break;
+        }
+        claimableCalls.push({ id: plan.toolCall.id, name: plan.toolCall.name, arguments: plan.args });
+    }
+    let levels;
+    if (claimableCalls.length === toolCalls.length) {
+        const scheduled = await awaitWithAbort(() => scheduleDagLevels(claimableCalls, {
+            cwd: config.cwd ?? process.cwd(),
+            toolPolicies,
+            registeredTools: boundTools,
+            strictExtensionClaims: config.strictExtensionClaims,
+            maxConcurrency: config.maxToolConcurrency,
+            resourceKeyResolver: config.resourceKeyResolver,
+        }), signal);
+        levels = scheduled.kind === "aborted" ? [] : scheduled.value.levels;
+    }
+    else {
+        levels = toolCalls.map((_toolCall, sourceIndex) => [sourceIndex]);
+    }
+    const finalizedByIndex = new Array(toolCalls.length).fill(undefined);
+    let skippedReason;
+    let stoppedByUnsettledTimeout = false;
+    for (const level of levels) {
+        if (signal?.aborted)
+            break;
+        const executedLevel = await runDagLevelCalls(currentContext, assistantMessage, level, toolCalls, plans, toolPolicies, config, signal, emit);
+        for (const outcome of executedLevel.outcomes)
+            finalizedByIndex[outcome.sourceIndex] = outcome.finalized;
+        if (signal?.aborted)
+            break;
+        if (executedLevel.stoppedByUnsettledTimeout) {
+            skippedReason = "Skipped because a preceding DAG tool timed out before its execution promise settled";
+            stoppedByUnsettledTimeout = true;
+            break;
+        }
+        if (shouldTerminateToolBatch(executedLevel.outcomes.map((outcome) => outcome.finalized))) {
+            skippedReason = "Skipped because the preceding DAG level requested termination";
+            break;
+        }
+    }
+    const messages = [];
+    const finalizedCalls = [];
+    for (let index = 0; index < toolCalls.length; index++) {
+        const finalized = finalizedByIndex[index];
+        if (finalized) {
+            messages.push(createToolResultMessage(finalized));
+            finalizedCalls.push(finalized);
+        }
+        else if (signal?.aborted) {
+            const toolCall = toolCalls[index];
+            messages.push(createImmutableSnapshot(createSyntheticToolResult(toolCall.id, toolCall.name, "Operation aborted")));
+        }
+        else if (skippedReason !== undefined) {
+            const toolCall = toolCalls[index];
+            messages.push(createImmutableSnapshot(createSyntheticToolResult(toolCall.id, toolCall.name, skippedReason, Date.now(), "skipped")));
+        }
+    }
+    // Close the full source-ordered batch before result notification; calls not
+    // reached by a candidate level receive no execution lifecycle.
+    for (const message of messages) {
+        currentContext.messages.push(message);
+        try {
+            await emitToolResultMessage(message, emit);
+        }
+        finally {
+            finalizedCalls.find(({ toolCall }) => toolCall.id === message.toolCallId)?.commitTerminal?.();
+        }
+    }
+    return {
+        messages,
+        terminate: skippedReason !== undefined || shouldTerminateToolBatch(finalizedCalls),
+        stopRun: stoppedByUnsettledTimeout,
+    };
+}
+/** Authorize one candidate DAG level, re-plan final claims, and run its safe sublevels. */
+async function runDagLevelCalls(currentContext, assistantMessage, levelIndices, toolCalls, plans, toolPolicies, config, signal, emit) {
+    const outcomes = [];
+    const runnable = [];
+    for (const sourceIndex of levelIndices) {
+        const toolCall = toolCalls[sourceIndex];
+        const plan = plans[sourceIndex];
+        const preparation = plan.kind === "immediate"
+            ? plan
+            : await authorizePlannedToolCall(currentContext, assistantMessage, plan, config, signal);
+        if (preparation.kind === "immediate") {
+            outcomes.push({
+                sourceIndex,
+                finalized: {
+                    toolCall,
+                    result: preparation.result,
+                    isError: preparation.isError,
+                    envelope: preparation.envelope,
+                },
+            });
+        }
+        else {
+            runnable.push({ sourceIndex, preparation });
+        }
+        if (signal?.aborted)
+            return { outcomes, stoppedByUnsettledTimeout: false };
+    }
+    const finalClaimableCalls = [];
+    for (const { preparation } of runnable) {
+        if (!isPlainArguments(preparation.args)) {
+            finalClaimableCalls.length = 0;
+            break;
+        }
+        finalClaimableCalls.push({
+            id: preparation.toolCall.id,
+            name: preparation.toolCall.name,
+            arguments: preparation.args,
+        });
+    }
+    let executionLevels;
+    if (finalClaimableCalls.length === runnable.length) {
+        const scheduled = await awaitWithAbort(() => scheduleDagLevels(finalClaimableCalls, {
+            cwd: config.cwd ?? process.cwd(),
+            toolPolicies,
+            registeredTools: runnable.map(({ preparation }) => preparation.tool),
+            strictExtensionClaims: config.strictExtensionClaims,
+            maxConcurrency: config.maxToolConcurrency,
+            resourceKeyResolver: config.resourceKeyResolver,
+        }), signal);
+        if (scheduled.kind === "aborted")
+            return { outcomes, stoppedByUnsettledTimeout: false };
+        executionLevels = scheduled.value.levels;
+    }
+    else {
+        executionLevels = runnable.map((_entry, index) => [index]);
+    }
+    for (const executionLevel of executionLevels) {
+        if (signal?.aborted)
+            break;
+        for (const entryIndex of executionLevel) {
+            await emitToolExecutionStart(runnable[entryIndex].preparation, emit);
+        }
+        const finalizedLevel = await Promise.all(executionLevel.map(async (entryIndex) => {
+            const entry = runnable[entryIndex];
+            const executed = await executePreparedToolCall(entry.preparation, config, signal, emit);
+            const finalized = await finalizeExecutedToolCall({
+                currentContext,
+                assistantMessage,
+                prepared: entry.preparation,
+                executed,
+                afterToolCall: config.afterToolCall,
+                signal,
+            });
+            await emitToolExecutionEnd(finalized, emit);
+            return { sourceIndex: entry.sourceIndex, finalized };
+        }));
+        outcomes.push(...finalizedLevel);
+        if (signal?.aborted)
+            break;
+        if (finalizedLevel.some(({ finalized }) => finalized.envelope.disposition === "timeout" && finalized.isRealPromiseSettled?.() === false)) {
+            return { outcomes, stoppedByUnsettledTimeout: true };
+        }
+    }
+    return { outcomes, stoppedByUnsettledTimeout: false };
+}
 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") {
@@ -397,15 +664,31 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
                 toolCall,
                 result: preparation.result,
                 isError: preparation.isError,
+                envelope: preparation.envelope,
             };
         }
         else {
-            const executed = await executePreparedToolCall(preparation, signal, emit);
-            finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
+            await emitToolExecutionStart(preparation, emit);
+            const executed = await executePreparedToolCall(preparation, config, signal, emit);
+            finalized = await finalizeExecutedToolCall({
+                currentContext,
+                assistantMessage,
+                prepared: preparation,
+                executed,
+                afterToolCall: config.afterToolCall,
+                signal,
+            });
         }
-        await emitToolExecutionEnd(finalized, emit);
         const toolResultMessage = createToolResultMessage(finalized);
-        await emitToolResultMessage(toolResultMessage, emit);
+        currentContext.messages.push(toolResultMessage);
+        if (preparation.kind === "prepared")
+            await emitToolExecutionEnd(finalized, emit);
+        try {
+            await emitToolResultMessage(toolResultMessage, emit);
+        }
+        finally {
+            finalized.commitTerminal?.();
+        }
         finalizedCalls.push(finalized);
         messages.push(toolResultMessage);
         if (signal?.aborted) {
@@ -420,20 +703,14 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
 async function executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, signal, emit) {
     const finalizedCalls = [];
     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);
         if (preparation.kind === "immediate") {
             const finalized = {
                 toolCall,
                 result: preparation.result,
                 isError: preparation.isError,
+                envelope: preparation.envelope,
             };
-            await emitToolExecutionEnd(finalized, emit);
             finalizedCalls.push(finalized);
             if (signal?.aborted) {
                 break;
@@ -441,8 +718,16 @@ async function executeToolCallsParallel(currentContext, assistantMessage, toolCa
             continue;
         }
         finalizedCalls.push(async () => {
-            const executed = await executePreparedToolCall(preparation, signal, emit);
-            const finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, signal);
+            await emitToolExecutionStart(preparation, emit);
+            const executed = await executePreparedToolCall(preparation, config, signal, emit);
+            const finalized = await finalizeExecutedToolCall({
+                currentContext,
+                assistantMessage,
+                prepared: preparation,
+                executed,
+                afterToolCall: config.afterToolCall,
+                signal,
+            });
             await emitToolExecutionEnd(finalized, emit);
             return finalized;
         });
@@ -454,7 +739,13 @@ async function executeToolCallsParallel(currentContext, assistantMessage, toolCa
     const messages = [];
     for (const finalized of orderedFinalizedCalls) {
         const toolResultMessage = createToolResultMessage(finalized);
-        await emitToolResultMessage(toolResultMessage, emit);
+        currentContext.messages.push(toolResultMessage);
+        try {
+            await emitToolResultMessage(toolResultMessage, emit);
+        }
+        finally {
+            finalized.commitTerminal?.();
+        }
         messages.push(toolResultMessage);
     }
     return {
@@ -478,146 +769,160 @@ function prepareToolCallArguments(tool, toolCall) {
         arguments: preparedArguments,
     };
 }
-async function prepareToolCall(currentContext, assistantMessage, toolCall, config, signal) {
-    const tool = currentContext.tools?.find((t) => t.name === toolCall.name);
-    if (!tool) {
-        return {
-            kind: "immediate",
-            result: createErrorToolResult(`Tool ${toolCall.name} not found`),
-            isError: true,
-        };
+function immediateOutcome(disposition, reason) {
+    return {
+        kind: "immediate",
+        result: createErrorToolResult(reason),
+        isError: true,
+        envelope: createToolResultEnvelope({ disposition, synthetic: true, executionStarted: false, reason }),
+    };
+}
+function planToolCall(currentContext, untrustedToolCall) {
+    try {
+        const toolCall = createImmutableJsonSnapshot(untrustedToolCall);
+        if (toolCall.id.length === 0 || toolCall.name.length === 0)
+            throw new TypeError("Invalid empty tool identity");
+        const candidate = currentContext.tools?.find((tool) => tool.name === toolCall.name);
+        if (!candidate)
+            return immediateOutcome("failed", `Tool ${toolCall.name} not found`);
+        const tool = bindToolIdentity(candidate, toolCall.name);
+        const prepared = prepareToolCallArguments(tool, toolCall);
+        const args = createImmutableJsonSnapshot(prepared.arguments);
+        const preparedToolCall = createImmutableSnapshot({ ...toolCall, arguments: args });
+        return { kind: "planned", toolCall, preparedToolCall, tool, args };
     }
+    catch (error) {
+        return immediateOutcome("failed", error instanceof Error ? error.message : String(error));
+    }
+}
+async function authorizePlannedToolCall(currentContext, assistantMessage, plan, config, signal) {
     try {
-        const preparedToolCall = prepareToolCallArguments(tool, toolCall);
-        const validatedArgs = validateToolArguments(tool, preparedToolCall);
-        if (config.beforeToolCall) {
-            const beforeResult = await config.beforeToolCall({
-                assistantMessage,
-                toolCall,
-                args: validatedArgs,
+        const hookArgs = parseJsonValue(validateToolArguments(plan.tool, plan.preparedToolCall));
+        const beforeToolCall = config.beforeToolCall;
+        if (beforeToolCall) {
+            const bounded = await awaitWithAbort(() => beforeToolCall({
+                assistantMessage: createImmutableSnapshot(assistantMessage),
+                toolCall: plan.toolCall,
+                args: hookArgs,
                 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,
-                };
+            }, signal), signal);
+            if (bounded.kind === "aborted" || signal?.aborted)
+                return immediateOutcome("aborted", "Operation aborted");
+            if (bounded.value?.block) {
+                return immediateOutcome("blocked", bounded.value.reason || "Tool execution was blocked");
             }
         }
-        if (signal?.aborted) {
-            return {
-                kind: "immediate",
-                result: createErrorToolResult("Operation aborted"),
-                isError: true,
-            };
-        }
+        if (signal?.aborted)
+            return immediateOutcome("aborted", "Operation aborted");
+        const args = createImmutableJsonSnapshot(hookArgs);
         return {
             kind: "prepared",
-            toolCall,
-            tool,
-            args: validatedArgs,
+            toolCall: plan.toolCall,
+            tool: plan.tool,
+            args,
+            eventArgs: createImmutableSnapshot(args),
+            timeoutMs: resolveToolTimeoutMs(plan.tool, config, plan.toolCall.name),
         };
     }
     catch (error) {
-        return {
-            kind: "immediate",
-            result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
-            isError: true,
-        };
+        return immediateOutcome("failed", error instanceof Error ? error.message : String(error));
     }
 }
-async function executePreparedToolCall(prepared, signal, emit) {
-    const updateEvents = [];
-    try {
-        const result = await prepared.tool.execute(prepared.toolCall.id, prepared.args, signal, (partialResult) => {
-            updateEvents.push(Promise.resolve(emit({
-                type: "tool_execution_update",
-                toolCallId: prepared.toolCall.id,
-                toolName: prepared.toolCall.name,
-                args: prepared.toolCall.arguments,
-                partialResult,
-            })));
-        });
-        await Promise.all(updateEvents);
-        return { result, isError: false };
-    }
-    catch (error) {
-        await Promise.all(updateEvents);
-        return {
-            result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
-            isError: true,
-        };
-    }
+async function prepareToolCall(currentContext, assistantMessage, toolCall, config, signal) {
+    const plan = planToolCall(currentContext, toolCall);
+    return plan.kind === "immediate"
+        ? plan
+        : authorizePlannedToolCall(currentContext, assistantMessage, plan, config, signal);
 }
-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;
+async function executePreparedToolCall(prepared, config, signal, emit) {
+    let realPromiseSettled = false;
+    let commitTerminal = () => { };
+    const terminalCommitted = new Promise((resolve) => {
+        commitTerminal = resolve;
+    });
+    const executed = await runToolCallWithTimeout({
+        toolCallId: prepared.toolCall.id,
+        toolName: prepared.toolCall.name,
+        timeoutMs: prepared.timeoutMs,
+        lateSettlement: config.toolExecutionPolicy?.lateSettlement,
+        signal,
+        start: async (childSignal, onUpdate) => {
+            try {
+                return await prepared.tool.execute(prepared.toolCall.id, prepared.args, childSignal, onUpdate);
             }
-        }
-        catch (error) {
-            result = createErrorToolResult(error instanceof Error ? error.message : String(error));
-            isError = true;
-        }
-    }
-    return {
-        toolCall: prepared.toolCall,
-        result,
-        isError,
-    };
+            finally {
+                realPromiseSettled = true;
+            }
+        },
+        emitUpdate: (partialResult) => emit({
+            type: "tool_execution_update",
+            toolCallId: prepared.toolCall.id,
+            toolName: prepared.toolCall.name,
+            args: prepared.eventArgs,
+            partialResult: createImmutableSnapshot(partialResult),
+        }),
+        emitLateSettlement: async (settlement) => {
+            await terminalCommitted;
+            await emit({
+                type: "tool_execution_late_settlement",
+                toolCallId: settlement.toolCallId,
+                toolName: settlement.toolName,
+                disposition: settlement.disposition,
+                outcome: settlement.outcome,
+            });
+        },
+        toErrorResult: (error) => createErrorToolResult(error instanceof Error ? error.message : String(error)),
+    });
+    return { ...executed, isRealPromiseSettled: () => realPromiseSettled, commitTerminal };
 }
-function createErrorToolResult(message) {
-    return {
-        content: [{ type: "text", text: message }],
-        details: {},
-    };
+async function emitToolExecutionStart(prepared, emit) {
+    await emit({
+        type: "tool_execution_start",
+        toolCallId: prepared.toolCall.id,
+        toolName: prepared.toolCall.name,
+        args: prepared.eventArgs,
+    });
 }
 async function emitToolExecutionEnd(finalized, emit) {
     await emit({
         type: "tool_execution_end",
         toolCallId: finalized.toolCall.id,
         toolName: finalized.toolCall.name,
-        result: finalized.result,
+        result: createImmutableSnapshot(finalized.result),
         isError: finalized.isError,
     });
 }
 function createToolResultMessage(finalized) {
-    return {
+    return createImmutableSnapshot({
         role: "toolResult",
         toolCallId: finalized.toolCall.id,
         toolName: finalized.toolCall.name,
         content: finalized.result.content,
-        details: finalized.result.details,
+        details: stampToolResultEnvelope(finalized.result.details, finalized.envelope),
         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 });
 }
+/** Commit and notify one aborted terminal for each unresolved, unstarted call. */
+async function closeAbortedToolBatch(currentContext, toolCalls, existingResults, emit) {
+    const resolvedIds = new Set(existingResults.map((result) => result.toolCallId));
+    const synthesized = [];
+    for (const toolCall of toolCalls) {
+        if (resolvedIds.has(toolCall.id)) {
+            continue;
+        }
+        const result = createImmutableSnapshot(createSyntheticToolResult(toolCall.id, toolCall.name, "Operation aborted"));
+        currentContext.messages.push(result);
+        await emit({ type: "message_start", message: result });
+        await emit({ type: "message_end", message: result });
+        synthesized.push(result);
+        // Guard against a duplicated call id within the same assistant message.
+        resolvedIds.add(toolCall.id);
+    }
+    return synthesized;
+}
 //# sourceMappingURL=agent-loop.js.map