@gea-ai/agent-sdk 0.1.260920-alpha.0 → 0.1.260920-alpha.2

package/README.md

@@ -19,6 +19,16 @@ provider configuration, or environment values.
 `toModelOutput({ toolCallId, input, output })`, following AI SDK's separation
 between the result used by the application and the result shown to the model.
 Both server and client tools retain output types in `InferAgentUITools`.
+Both the default Agent Core engine and `aiSdk()` support client Tools without
+`execute`. A client Tool waits for an `output-available` or `output-error` part
+on the original assistant message and Tool call ID. Submit all pending client
+results/approval decisions together through the existing continuation flow.
+Core pauses server handlers in the same batch until those interactions complete,
+following its existing whole-batch approval behavior.
+Tool results resume the same Run while its interaction remains pending.
+Waiting for client input releases execution: a new user message skips the old
+interaction and starts a new Run in the same Session, without an explicit cancel.
+Skipped calls become errors in the transcript/model context; late results are rejected.
 
 `outputSchema` is a declaration/type hint. It never parses, coerces or validates
 returned data, including client-supplied results. It is serialized in the Agent

package/dist/agent-session-execution.js

@@ -3,7 +3,7 @@ import { agentModelCallsSchema, } from "@gea-ai/contract/agent-usage";
 import { AGENT_SESSION_COMPUTER_LEASE_MS, agentSessionComputerSchema, agentSessionComputerReferenceSchema, AGENT_SESSION_EXECUTION_LEASE_MS, AGENT_SESSION_EXECUTION_PROTOCOL_VERSION, MAX_AGENT_SESSION_RESPONSE_BYTES, MAX_AGENT_SESSION_EXECUTION_ATTEMPTS, MAX_AGENT_SESSION_EXECUTION_BODY_BYTES, MAX_AGENT_SESSION_PAGE_SIZE, agentSessionAttemptIdentitySchema, agentSessionExecutionRenewSchema, agentSessionExecutionCompleteSchema, agentSessionExecutionPauseSchema, agentSessionExecutionControlSchema, agentSessionExecutionMutationSchema, agentSessionExecutionStartSchema, } from "@gea-ai/contract/agent-session";
 import { z } from "zod";
 import { activeComputerOperation } from "./agent-session-computer.js";
-import { isAgentSessionInboxBusy, scheduleAgentSessionInbox, getAgentSessionRunState, handleAgentSessionInboxRequest, hasAgentSessionInbox, } from "./agent-session-inbox.js";
+import { isAgentSessionInboxBusy, scheduleAgentSessionInbox, getAgentSessionRunState, handleAgentSessionInboxRequest, hasAgentSessionInbox, skipAgentSessionInputWait, } from "./agent-session-inbox.js";
 // Managed execution owns its own durable state; PostgreSQL copies the live stream.
 const prefix = "execution-v2:";
 const key = (name) => `${prefix}${name}`;
@@ -11,6 +11,8 @@ const sequenceKey = (name, sequence) => key(`${name}:${sequence.toString().padSt
 const runEventRangeSchema = z.strictObject({
     start: z.number().int().nonnegative(),
     end: z.number().int().nonnegative().nullable(),
+    messageId: z.string().optional(),
+    messageStart: z.number().int().nonnegative().optional(),
 });
 class SessionProtocolError extends Error {
     reason;
@@ -100,6 +102,21 @@ async function writeValues(tx, input) {
     await tx.put(key("message-sequence"), messageSequence);
     let eventSequence = (await tx.get(key("event-sequence"))) ?? 0;
     for (const event of input.events) {
+        if (event.type === "start" &&
+            typeof event.messageId === "string" &&
+            input.runId) {
+            const rangeKey = key(`run-events:${encodeURIComponent(input.runId)}`);
+            const stored = await tx.get(rangeKey);
+            if (stored !== undefined) {
+                const range = runEventRangeSchema.parse(stored);
+                if (range.messageId !== event.messageId)
+                    await tx.put(rangeKey, {
+                        ...range,
+                        messageId: event.messageId,
+                        messageStart: eventSequence,
+                    });
+            }
+        }
         const entry = { event, sequence: ++eventSequence };
         await putSessionPayload(tx, sequenceKey("event", entry.sequence), entry);
     }
@@ -449,6 +466,14 @@ export async function handleAgentSessionExecutionRequest(request, storage) {
                 return { duplicate: false, outcome };
             }));
         }
+        if (request.method === "POST" && url.pathname === "/v2/turns/skip-input") {
+            const input = z
+                .strictObject({ runId: z.uuid() })
+                .parse(await readBody(request));
+            return json(await storage.transaction(async (tx) => ({
+                requested: await skipAgentSessionInputWait(tx, input.runId),
+            })));
+        }
         if (request.method === "POST" && url.pathname === "/v2/turns/cancel") {
             const input = z
                 .object({ runId: agentSessionAttemptIdentitySchema.shape.runId })
@@ -497,6 +522,14 @@ export async function handleAgentSessionExecutionRequest(request, storage) {
                 return { duplicate: false, revision, turn };
             }));
         }
+        const messageMatch = /^\/v2\/messages\/([^/]+)$/u.exec(url.pathname);
+        if (request.method === "GET" && messageMatch) {
+            const id = decodeURIComponent(messageMatch[1]);
+            const sequence = await storage.get(key(`message-id:${encodeURIComponent(id)}`));
+            if (sequence === undefined)
+                throw new SessionProtocolError("message_not_found", 404);
+            return json(await storage.transaction((tx) => getSessionPayload(tx, sequenceKey("message", sequence))));
+        }
         if (request.method === "GET" && url.pathname === "/v2/model-context")
             return json({
                 context: (await storage.transaction((tx) => getSessionPayload(tx, key("model-context")))) ?? null,
@@ -520,7 +553,10 @@ export async function handleAgentSessionExecutionRequest(request, storage) {
                 const end = range.end ?? (await tx.get(key("event-sequence"))) ?? 0;
                 if (after > end || (after !== 0 && after < range.start))
                     throw new SessionProtocolError("invalid_cursor", 400);
-                const start = Math.max(after, range.start);
+                const start = Math.max(after, !url.searchParams.has("after") &&
+                    url.searchParams.get("latestMessage") === "true"
+                    ? (range.messageStart ?? range.start)
+                    : range.start);
                 const events = await entries(tx, "event", start, Math.min(limit, end - start));
                 const nextCursor = events.at(-1)?.sequence ?? start;
                 const receipt = await tx.get(key(`outcome:${encodeURIComponent(runId)}`));

package/dist/agent-session-inbox.d.ts

@@ -1,5 +1,7 @@
 import { type AgentChildRun } from "@gea-ai/contract/agent-worker-tools";
 import type { AgentSessionStorage, AgentSessionTransactionStorage } from "./agent-session";
+/** Atomically supersede only an idle input wait, never a running invocation. */
+export declare function skipAgentSessionInputWait(tx: AgentSessionTransactionStorage, runId: string): Promise<boolean>;
 export declare function hasAgentSessionInbox(tx: AgentSessionTransactionStorage): Promise<boolean>;
 /** Read the logical Run independently of the currently leased invocation. */
 export declare function getAgentSessionRunState(tx: AgentSessionTransactionStorage, runId: string): Promise<{

package/dist/agent-session-inbox.js

@@ -7,6 +7,7 @@ import { agentChildRunSchema, } from "@gea-ai/contract/agent-worker-tools";
 import { combineTraceContexts, readTraceContext } from "./trace-context.js";
 import { traceContextSchema } from "@gea-ai/contract/traces";
 import { activeComputerOperation } from "./agent-session-computer.js";
+import { getSessionPayload, putSessionPayload } from "./agent-session-payload.js";
 const stateKey = "inbox:v1";
 const waitSchema = agentRunWaitInputSchema.omit({ timeoutMs: true }).extend({
     turnId: z.uuid(),
@@ -39,6 +40,82 @@ const stateSchema = z.strictObject({
     terminalQueue: z.array(terminalSchema).max(8).default([]),
 });
 const executionInputSchema = z.strictObject({ executionId: z.uuid() });
+async function skipInputWait(tx, state, runs) {
+    const pending = state.inputWait;
+    if (!pending || !state.transport)
+        return false;
+    // Both journals retain the same assistant ID. Seal visible pending parts as
+    // well as the Run so a late client result cannot resurrect the interaction.
+    for (const prefix of ["", "execution-v2:"]) {
+        const sequence = await tx.get(`${prefix}message-id:${encodeURIComponent(pending.messageId)}`);
+        if (sequence === undefined)
+            continue;
+        const key = `${prefix}message:${String(sequence).padStart(16, "0")}`;
+        const stored = await getSessionPayload(tx, key);
+        const envelope = prefix
+            ? z
+                .object({ message: agentApplicationAssistantMessageSchema })
+                .passthrough()
+                .parse(stored)
+            : null;
+        const message = envelope?.message ?? agentApplicationAssistantMessageSchema.parse(stored);
+        const skipped = {
+            ...message,
+            parts: message.parts.map((part) => (part.type === "dynamic-tool" || part.type.startsWith("tool-")) &&
+                [
+                    "input-streaming",
+                    "input-available",
+                    "approval-requested",
+                    "approval-responded",
+                ].includes(String(part.state))
+                ? {
+                    ...part,
+                    state: "output-error",
+                    errorText: "Tool interaction was skipped by a new user message; no result was provided.",
+                }
+                : part),
+        };
+        await putSessionPayload(tx, key, envelope ? { ...envelope, message: skipped } : skipped);
+    }
+    const terminal = {
+        execution: {
+            id: pending.turnId,
+            turnId: pending.turnId,
+            messages: [],
+            waitResult: null,
+        },
+        outcome: {
+            status: "interrupted",
+            text: "Pending tool interaction skipped by a new user message.",
+        },
+        transport: state.transport,
+    };
+    state.inputWait = null;
+    if (runs.some((run) => !run.outcome)) {
+        state.stopped = true;
+        for (const run of runs)
+            if (!run.outcome)
+                run.cancelRequested = true;
+        await tx.put("child-runs", { runs });
+        state.draining = terminal;
+    }
+    else if (state.terminal)
+        state.terminalQueue.push(terminal);
+    else
+        state.terminal = terminal;
+    await save(tx, state, runs);
+    return true;
+}
+/** Atomically supersede only an idle input wait, never a running invocation. */
+export async function skipAgentSessionInputWait(tx, runId) {
+    const state = await readState(tx);
+    if (!state ||
+        state.execution ||
+        state.inputWait?.turnId !== runId ||
+        state.terminalQueue.length >= 8)
+        return false;
+    return skipInputWait(tx, state, await readChildRuns(tx));
+}
 // A turn admits a bounded batch. Messages beyond it retain their original order.
 function takeMessages(state, steeringOnly) {
     const messages = [];
@@ -219,7 +296,9 @@ async function save(tx, state, runs) {
             });
     const ready = state.wait
         ? waitResult(state, runs) !== null
-        : !state.inputWait && state.messages.length > 0;
+        : state.inputWait
+            ? state.messages.some((message) => message.sender.type === "user")
+            : state.messages.length > 0;
     const cancelling = runs.some((run) => !run.outcome && run.cancelRequested);
     state.pendingStarts = state.pendingStarts.filter((id) => runs.some((run) => run.id === id && !run.outcome && !run.cancelRequested));
     const storedTurn = state.execution
@@ -352,14 +431,20 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                     state.terminalQueue.length >= 8 ||
                     (state.wait && input.message?.mode !== "steering") ||
                     (state.inputWait &&
-                        input.continuation?.id !== state.inputWait.messageId))
+                        input.continuation &&
+                        input.continuation.id !== state.inputWait.messageId))
                     return Response.json({ error: "session_busy" }, { status: 409 });
-                state.transport = input.transport;
                 const previous = input.message
                     ? await tx.get(`inbox:message:${input.message.id}`)
                     : undefined;
                 if (previous !== undefined)
                     return Response.json({ error: "message_already_accepted" }, { status: 409 });
+                if (input.message && state.inputWait) {
+                    await skipInputWait(tx, state, runs);
+                    if (state.draining)
+                        return Response.json({ error: "session_busy" }, { status: 409 });
+                }
+                state.transport = input.transport;
                 let resumedWait = state.resumeWait;
                 if (state.wait && input.message) {
                     state.messages.push(input.message);
@@ -458,6 +543,12 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                     await save(tx, state, runs);
                     return Response.json({ execution: null });
                 }
+                if (state.inputWait &&
+                    state.messages.some((message) => message.sender.type === "user") &&
+                    !state.execution &&
+                    !state.draining &&
+                    state.terminalQueue.length < 8)
+                    await skipInputWait(tx, state, runs);
                 if (state.execution ||
                     state.terminal ||
                     state.draining ||
@@ -468,6 +559,7 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                     return Response.json({ execution: null });
                 const messages = takeMessages(state, state.wait !== null);
                 const joining = state.wait?.toolCallId === null;
+                state.stopped = false;
                 state.execution = {
                     id: crypto.randomUUID(),
                     turnId: state.wait?.turnId ?? crypto.randomUUID(),

package/dist/agent-session-stream.js

@@ -4,9 +4,10 @@ import { UI_MESSAGE_STREAM_HEADERS } from "ai";
 export async function streamManagedAgentSessionRun(request, session) {
     const url = new URL(request.url);
     url.pathname = "/v2/run-events";
-    // Public reconnects replay this Run from the beginning, as the API contract specifies.
+    // Replay the active response. User steering starts a new response within the same Run.
     url.searchParams.delete("after");
     url.searchParams.delete("limit");
+    url.searchParams.set("latestMessage", "true");
     const abort = new AbortController();
     let cancelled = false;
     const onDisconnect = () => abort.abort(request.signal.reason);
@@ -34,14 +35,28 @@ export async function streamManagedAgentSessionRun(request, session) {
             return new Response(null, { status: 204 });
         }
         const encoder = new TextEncoder();
+        let messageId;
         return new Response(new ReadableStream({
             async pull(controller) {
                 try {
                     while (!abort.signal.aborted) {
                         if (page.events.length) {
-                            controller.enqueue(encoder.encode(page.events
-                                .map(({ event }) => `data: ${JSON.stringify(event)}\n\n`)
-                                .join("")));
+                            let text = "";
+                            for (const { event } of page.events) {
+                                if (event.type === "start" &&
+                                    typeof event.messageId === "string") {
+                                    if (messageId && messageId !== event.messageId) {
+                                        // The old subscriber must never feed a second response into useChat's reducer.
+                                        controller.enqueue(encoder.encode(text + "data: [DONE]\n\n"));
+                                        controller.close();
+                                        dispose();
+                                        return;
+                                    }
+                                    messageId = event.messageId;
+                                }
+                                text += `data: ${JSON.stringify(event)}\n\n`;
+                            }
+                            controller.enqueue(encoder.encode(text));
                             page = { ...page, events: [] };
                             return;
                         }

package/dist/agent-worker.js

@@ -29,7 +29,7 @@ import { toAgentHttpFile, } from "@gea-ai/contract/agent-http-api";
 import { handleHostedAgentHttp } from "./agent-http.js";
 import { createWorkerAgentTool, createWorkerRunCancelTool } from "./agent-call.js";
 import { AgentSessionRunner, resumeSessionWait } from "./agent-session-runner.js";
-import { agentRunWaitInputSchema, agentSessionInboxExecutionSchema, sessionExecutionMessage, } from "@gea-ai/contract/agent-session-inbox";
+import { agentRunWaitInputSchema, toAgentRunWaitOutput, agentSessionInboxExecutionSchema, sessionExecutionMessage, } from "@gea-ai/contract/agent-session-inbox";
 import { agentWorkerInvocationIdentitySchema } from "@gea-ai/contract/agent-worker-tools";
 import { MAX_AGENT_ARTIFACT_IMAGES, MAX_AGENT_ARTIFACT_IMAGE_BYTES, studioArtifactInputFileSchema, studioArtifactCreateUploadSchema, studioArtifactListSchema, } from "@gea-ai/contract/studio-artifacts";
 import { parsePatch } from "./vendor/codex-patch/parser.js";
@@ -42,7 +42,7 @@ import { AGENT_APPLICATION_PREFIX, buildAgentApplicationPath, agentApplicationAs
 import { AGENT_APPLICATION_CHAT_ID_HEADER, AGENT_APPLICATION_MESSAGE_ID_HEADER, AGENT_APPLICATION_RUN_ID_HEADER, agentApplicationKeySchema, agentApplicationRunRequestSchema, } from "@gea-ai/contract";
 import { AGENT_CHANNEL_EXECUTION_TIMEOUT_MS, agentChannelInvocationContextSchema, agentChannelAddressSchema, agentChannelHttpMessageRequestSchema, agentChannelOpaqueIdSchema, agentChannelProjectTerminalCommandSchema, agentChannelRunTerminalCallbackSchema, agentChannelStartRunCommandSchema, } from "@gea-ai/contract/agent-channels";
 import { agentSessionClaimChannelRunResultSchema, agentSessionCompleteChannelRunResultSchema, agentSessionGetModelContextResultSchema, agentSessionAttemptIdentitySchema, agentSessionExecutionStartResultSchema, agentSessionExecutionMutationResultSchema, agentSessionPutModelContextResultSchema, } from "@gea-ai/contract/agent-session";
-import { InvalidResponseDataError, convertToModelMessages, isToolUIPart, createUIMessageStreamResponse, createUIMessageStream, asSchema, jsonSchema, stepCountIs, streamText, tool, } from "ai";
+import { InvalidResponseDataError, convertToModelMessages, isToolUIPart, validateUIMessages, createUIMessageStreamResponse, createUIMessageStream, asSchema, jsonSchema, stepCountIs, streamText, tool, } from "ai";
 import { agentWorkerConnectionDeleteOutputSchema, agentWorkerConnectionGetOutputSchema, agentWorkerConnectionSetOutputSchema, agentWorkerToolInitializationSchema, MAX_AGENT_WORKER_TOOLS, } from "@gea-ai/contract/agent-worker-tools";
 import { agentToolIdentitySchema, } from "@gea-ai/contract/agent-packages";
 import { z } from "zod";
@@ -475,7 +475,8 @@ async function runPreparedAgent(runtime, agentKey, request, environment, identif
     const headers = new Headers(response.headers);
     headers.set(AGENT_APPLICATION_CHAT_ID_HEADER, chatId);
     headers.set(AGENT_APPLICATION_RUN_ID_HEADER, runId);
-    headers.set(AGENT_APPLICATION_MESSAGE_ID_HEADER, responseMessageId);
+    headers.set(AGENT_APPLICATION_MESSAGE_ID_HEADER, response.headers.get(AGENT_APPLICATION_MESSAGE_ID_HEADER) ??
+        responseMessageId);
     return new Response(response.body, {
         headers,
         status: response.status,
@@ -3404,6 +3405,14 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         path: sessionExecution ? "/v2/model-context" : "/v1/model-context",
         schema: agentSessionGetModelContextResultSchema,
     });
+    if (submittedUser &&
+        storedContext.context &&
+        storedContext.context.runId !== payload.runId) {
+        // A new user Run supersedes the previous idle tool interaction. Close its
+        // missing results before appending user input; never execute the skipped batch.
+        storedContext.context.messages = closeInterruptedToolCalls(storedContext.context.messages.map(decodeAgentModelProxyValue), "Tool interaction was skipped by a new user message; no result was provided.").map(encodeAgentModelProxyValue);
+        delete storedContext.context.metadata.agentCore;
+    }
     // Reuse durable conversions when UI history is replayed, so file conversion
     // does not upload another Artifact on every turn or approval continuation.
     const retainedToolCalls = new Set();
@@ -3420,6 +3429,66 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 modelOutputs.set(part.toolCallId, part.output);
         }
     }
+    const suspendedMessageId = storedContext.context?.runId === payload.runId
+        ? storedContext.context.metadata.suspendedMessageId
+        : undefined;
+    const resumesResponse = Boolean(suspendedMessageId &&
+        input.inboxExecution &&
+        !input.inboxExecution.messages.some((message) => message.sender.type === "user"));
+    let responseBaseline;
+    let interruptedResponse;
+    let interruptedWait;
+    if (suspendedMessageId && input.inboxExecution) {
+        const saved = await requestSessionJson({
+            chatId: payload.chatId,
+            method: "GET",
+            namespace: input.sessionNamespace,
+            path: `${sessionExecution ? "/v2" : "/v1"}/messages/${encodeURIComponent(suspendedMessageId)}`,
+            schema: z.object({ message: z.unknown() }),
+        });
+        const [message] = await validateUIMessages({
+            messages: [saved.message],
+        });
+        if (!message || message.role !== "assistant")
+            throw new Error("Suspended response is not an assistant message.");
+        // Invocation completion is not message completion. Do not retain its waiting metadata.
+        if (message.metadata) {
+            delete message.metadata.sessionStatus;
+            delete message.metadata.finishedAt;
+            delete message.metadata.finishReason;
+        }
+        const result = input.inboxExecution.waitResult;
+        if (result) {
+            const part = message.parts.find((part) => isToolUIPart(part) && part.toolCallId === result.toolCallId);
+            if (!part || !isToolUIPart(part))
+                throw new Error("Suspended response is missing its wait tool.");
+            if (resumesResponse) {
+                Object.assign(part, {
+                    state: "output-available",
+                    output: toAgentRunWaitOutput(result),
+                });
+            }
+            else {
+                const errorText = "Wait interrupted by a new user message.";
+                Object.assign(part, { state: "output-error", errorText });
+                interruptedWait = {
+                    type: "tool-output-error",
+                    toolCallId: result.toolCallId,
+                    errorText,
+                };
+            }
+        }
+        if (resumesResponse)
+            responseBaseline = message;
+        else {
+            message.metadata = {
+                ...message.metadata,
+                finishedAt: new Date(),
+                finishReason: "other",
+            };
+            interruptedResponse = message;
+        }
+    }
     const modelMessages = replaceInputFiles(await convertToModelMessages(payload.originalMessages.map((message) => storedContext.context && message.role === "assistant"
         ? {
             ...message,
@@ -3480,7 +3549,10 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         }
     }
     else if (input.inboxExecution &&
-        storedContext.context?.runId === payload.runId) {
+        storedContext.context?.runId === payload.runId &&
+        // Core resumes its persisted tool batch and validates approvals separately.
+        // Replaying UI approval parts here would overwrite that model projection.
+        !(engine && storedContext.context.metadata.agentCore)) {
         // The Run survives a join/steering continuation, but its newly accepted input is still new context.
         context.messages = input.inboxExecution.continuation
             ? replaceLastAssistantInteraction({
@@ -3489,6 +3561,12 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             })
             : [...context.messages, ...currentTurn];
     }
+    if (responseBaseline) {
+        payload.responseMessageId = responseBaseline.id;
+        // Model context was restored independently above; this baseline is only for UI assembly.
+        payload.originalMessages = [responseBaseline];
+    }
+    delete context.metadata.suspendedMessageId;
     if (submittedUser && startsNewTurn)
         context.metadata.turnImages = inputFiles
             .filter((file) => file.mediaType.startsWith("image/"))
@@ -3907,16 +3985,18 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             })),
         ];
         if (inboxRunner?.suspendedToolCallId) {
-            responseMessage.parts = responseMessage.parts.map((part) => "toolCallId" in part &&
-                part.toolCallId === inboxRunner.suspendedToolCallId
-                ? {
-                    type: "tool-runWait",
-                    toolCallId: part.toolCallId,
-                    state: "input-available",
-                    input: "input" in part ? part.input : {},
+            responseMessage.parts = responseMessage.parts.map((part) => {
+                if (isToolUIPart(part) &&
+                    part.toolCallId === inboxRunner.suspendedToolCallId &&
+                    part.state === "output-available") {
+                    const { output: _output, approval: _approval, ...pending } = part;
+                    return { ...pending, state: "input-available" };
                 }
-                : part);
+                return part;
+            });
         }
+        if (inboxRunner?.suspended)
+            context.metadata.suspendedMessageId = responseMessage.id;
         responseMessage.metadata = {
             ...responseMessage.metadata,
             ...(await contextFinished),
@@ -4006,13 +4086,16 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         const pending = context.metadata.agentCore;
         let lastCoreFinishReason = pending ? "tool-calls" : "stop";
         if (pending && currentTurn.some((message) => message.role === "user"))
-            throw new Error("Resolve pending approvals before starting another turn.");
+            throw new Error("Resolve pending tool interactions before starting another turn.");
         const messageId = pending?.messageId ?? payload.responseMessageId;
-        const responses = pending
+        const pendingMessage = pending
             ? z
                 .object({ parts: z.array(z.unknown()) })
                 .parse(payload.originalMessages.find((message) => message.id === pending.messageId))
-                .parts.flatMap((part) => {
+            : undefined;
+        const responses = pendingMessage
+            ? pendingMessage.parts
+                .flatMap((part) => {
                 const parsed = z
                     .object({
                     state: z.literal("approval-responded"),
@@ -4026,6 +4109,49 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 // Keep unknown IDs so Rust still rejects foreign/duplicate responses.
                 .filter((response) => !pending.pendingStep.approvals.some((approval) => approval.id === response.id && approval.response != null))
             : [];
+        // Model conversion already applies the Tool's toModelOutput (including
+        // managed file adoption); retain the raw client output for the UI stream.
+        const modelResults = new Map(fromModelMessages((pending?.pendingStep.client_calls?.length
+            ? modelMessages
+            : []).flatMap((message) => message.role === "tool"
+            ? [
+                {
+                    ...message,
+                    content: message.content.filter((part) => part.type === "tool-result"),
+                },
+            ]
+            : [])).flatMap((message) => message.content.flatMap((part) => part.type === "tool_result" ? [[part.call_id, part]] : [])));
+        const clientResults = (pendingMessage?.parts ?? []).flatMap((part) => {
+            const result = z
+                .discriminatedUnion("state", [
+                z.object({
+                    state: z.literal("output-available"),
+                    toolCallId: z.string(),
+                    output: z.json(),
+                }),
+                z.object({
+                    state: z.literal("output-error"),
+                    toolCallId: z.string(),
+                    errorText: z.string(),
+                }),
+            ])
+                .safeParse(part);
+            if (!result.success ||
+                !pending?.pendingStep.client_calls?.includes(result.data.toolCallId))
+                return [];
+            const value = result.data;
+            const modelResult = modelResults.get(value.toolCallId);
+            if (!modelResult)
+                throw new Error(`Missing client Tool model output: ${value.toolCallId}`);
+            return [
+                {
+                    call_id: value.toolCallId,
+                    output: value.state === "output-error" ? value.errorText : value.output,
+                    is_error: value.state === "output-error",
+                    model_output: modelResult.model_output,
+                },
+            ];
+        });
         const coreTools = await createCoreWorkerTools({
             tools,
             approval: toolApproval,
@@ -4084,7 +4210,9 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 }
                 : undefined,
             pending_step: pending?.pendingStep,
-        }), pending ? { type: "approval_response", responses } : { type: "start" }, {
+        }), pending
+            ? { type: "tool_response", responses, results: clientResults }
+            : { type: "start" }, {
             ...coreTools,
             onError: engine.onError,
             fetch: (request, init) => coreConnection.fetch(request, init),
@@ -4188,7 +4316,8 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                             ? "stop"
                             : outcome.reason === "stopped"
                                 ? lastCoreFinishReason
-                                : outcome.reason === "awaiting_approval"
+                                : outcome.reason === "awaiting_approval" ||
+                                    outcome.reason === "awaiting_tool_results"
                                     ? "tool-calls"
                                     : "length",
                     });
@@ -4429,6 +4558,46 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     }
     const durableStream = stream.pipeThrough(new TransformStream({
         async transform(chunk, controller) {
+            if (chunk.type === "start" && interruptedResponse) {
+                const events = [
+                    ...(interruptedWait ? [interruptedWait] : []),
+                    { type: "finish", finishReason: "other" },
+                ];
+                if (sessionExecution)
+                    await mutateSession({
+                        messages: [{ ...interruptedResponse }],
+                        events,
+                    });
+                else {
+                    await appendSessionValue({
+                        body: { message: interruptedResponse, runId: payload.runId },
+                        chatId: payload.chatId,
+                        namespace: input.sessionNamespace,
+                        path: "/v1/messages",
+                    });
+                    for (const event of events)
+                        await appendStreamEvent(event);
+                }
+            }
+            if (chunk.type === "start" && responseBaseline) {
+                // Each internal invocation still has its own start/finish for accounting.
+                // The public journal represents one response across those invocations.
+                controller.enqueue(chunk);
+                const result = input.inboxExecution?.waitResult;
+                if (result) {
+                    const output = {
+                        type: "tool-output-available",
+                        toolCallId: result.toolCallId,
+                        output: toAgentRunWaitOutput(result),
+                    };
+                    if (sessionExecution)
+                        await mutateSession({ events: [output] });
+                    else
+                        await appendStreamEvent(output);
+                    controller.enqueue(output);
+                }
+                return;
+            }
             if (chunk.type === "tool-output-available" &&
                 chunk.toolCallId === inboxRunner?.suspendedToolCallId)
                 return;
@@ -4455,6 +4624,10 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                     finishReason: metadata.finishReason,
                     messageMetadata: metadata,
                 };
+                if (metadata.sessionStatus === "waiting") {
+                    controller.enqueue(chunk);
+                    return;
+                }
             }
             if (sessionExecution) {
                 await mutateSession({ events: [chunk] });
@@ -4483,7 +4656,17 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 reader.releaseLock();
             }
         })());
-        return createUIMessageStreamResponse({ stream: response });
+        return createUIMessageStreamResponse({
+            stream: response,
+            headers: {
+                [AGENT_APPLICATION_MESSAGE_ID_HEADER]: payload.responseMessageId,
+            },
+        });
     }
-    return createUIMessageStreamResponse({ stream: durableStream });
+    return createUIMessageStreamResponse({
+        stream: durableStream,
+        headers: {
+            [AGENT_APPLICATION_MESSAGE_ID_HEADER]: payload.responseMessageId,
+        },
+    });
 }

package/dist/experimental/agent-core-messages.d.ts

@@ -19,7 +19,7 @@ export declare function toFileData(data: AgentCoreFileData): {
 export declare function toCoreModelOutput(output: ToolResultOutput): AgentCoreModelOutput;
 export declare function fromModelMessages(messages: ModelMessage[]): AgentCoreMessage[];
 /** Close only the interrupted trailing batch, after host operations have settled. */
-export declare function closeInterruptedToolCalls(messages: ModelMessage[]): ModelMessage[];
+export declare function closeInterruptedToolCalls(messages: ModelMessage[], reason?: string): ModelMessage[];
 export declare function toToolModelOutput(part: Extract<AgentCoreMessage["content"][number], {
     type: "tool_result";
 }>): LanguageModelV4ToolResultOutput;

package/dist/experimental/agent-core-messages.js

@@ -137,7 +137,7 @@ export function fromModelMessages(messages) {
     }));
 }
 /** Close only the interrupted trailing batch, after host operations have settled. */
-export function closeInterruptedToolCalls(messages) {
+export function closeInterruptedToolCalls(messages, reason = "Agent execution was interrupted before a tool result was recorded. The operation may have taken effect; its outcome is unknown.") {
     let index = messages.length - 1;
     while (index >= 0 && messages[index]?.role === "tool")
         index--;
@@ -165,7 +165,7 @@ export function closeInterruptedToolCalls(messages) {
                 toolName,
                 output: {
                     type: "error-text",
-                    value: "Agent execution was interrupted before a tool result was recorded. The operation may have taken effect; its outcome is unknown.",
+                    value: reason,
                 },
             })),
         },

package/dist/experimental/agent-core-tools.js

@@ -7,7 +7,7 @@ export function createAgentCoreTools(options) {
     return {
         async decideTool(call, signal) {
             const action = options.actions[call.name];
-            if (!action?.handler)
+            if (!action)
                 return { type: "denied", reason: `Tool is unavailable: ${call.name}` };
             const parsed = await action.inputSchema.safeParseAsync(call.input);
             if (!parsed.success)
@@ -35,8 +35,9 @@ export function createAgentCoreTools(options) {
                 return {
                     type: "approval_required",
                     approval_id: options.approvalId?.(call) ?? crypto.randomUUID(),
+                    ...(!action.handler ? { client: true } : {}),
                 };
-            return { type: "approved" };
+            return { type: action.handler ? "approved" : "client" };
         },
         async tool(call, signal) {
             const action = options.actions[call.name];

package/dist/experimental/agent-core-ui.js

@@ -158,7 +158,7 @@ export async function* projectAgentCoreEvents(turn, options) {
                     break;
                 case "tool_ready":
                     calls.set(event.call.id, event.call);
-                    if (resumed)
+                    if (resumed && !event.client)
                         break;
                     part = {
                         type: "tool-call",
@@ -267,7 +267,8 @@ export async function* projectAgentCoreEvents(turn, options) {
                 : outcome.reason === "model_limit"
                     ? "length"
                     : outcome.reason === "step_limit" ||
-                        outcome.reason === "awaiting_approval"
+                        outcome.reason === "awaiting_approval" ||
+                        outcome.reason === "awaiting_tool_results"
                         ? "tool-calls"
                         : "error",
         messageMetadata,

package/dist/experimental/agent-core-worker-tools.js

@@ -37,7 +37,7 @@ export async function createCoreWorkerTools(options) {
         async decideTool(call, signal) {
             signal.throwIfAborted();
             const tool = options.tools[call.name];
-            if (!tool?.execute)
+            if (!tool)
                 return { type: "denied", reason: `Tool is unavailable: ${call.name}` };
             const parsed = await safeValidateTypes({
                 value: call.input,
@@ -69,8 +69,12 @@ export async function createCoreWorkerTools(options) {
                         : "Tool execution denied",
                 };
             if (type === "user-approval" || guardrailType === "user-approval")
-                return { type: "approval_required", approval_id: crypto.randomUUID() };
-            return { type: "approved" };
+                return {
+                    type: "approval_required",
+                    approval_id: crypto.randomUUID(),
+                    ...(!tool.execute ? { client: true } : {}),
+                };
+            return { type: tool.execute ? "approved" : "client" };
         },
         async tool(call, signal) {
             const tool = options.tools[call.name];

package/dist/experimental/agent-core.d.ts

@@ -26,7 +26,7 @@ export interface AgentCoreHost {
     prepareStep?(step: AgentCorePrepareStep, signal: AbortSignal): Promise<AgentCoreMessage[] | null | void>;
     finishStep?(step: AgentCoreFinishedStep, signal: AbortSignal): Promise<AgentCoreMessage[] | null | void>;
     /** Core awaits this even after cancellation. Drain retained work and persist
-     * final context here; awaiting_approval is a pause, not a completed turn. */
+     * final context here; approval/client-result waits are pauses, not completed turns. */
     finishRun?(outcome: AgentCoreOutcome, signal: AbortSignal): Promise<void>;
     model?(request: AgentCoreModelRequest, signal: AbortSignal): AsyncIterable<AgentCoreModelPart>;
     tool(call: AgentCoreToolCall, signal: AbortSignal): Promise<AgentCoreToolResult>;
@@ -37,13 +37,13 @@ export interface AgentCoreHost {
 export declare function createAgentCore(module: WebAssembly.Module, config: AgentCoreConfig): {
     run(message: AgentCoreInput, host: AgentCoreHost, emit: (event: AgentCoreEvent) => Promise<void>, signal: AbortSignal): Promise<{
         output?: z.util.JSONType | undefined;
-        reason: "awaiting_approval" | "cancelled" | "completed" | "failed" | "model_limit" | "step_limit" | "stopped";
+        reason: "awaiting_approval" | "awaiting_tool_results" | "cancelled" | "completed" | "failed" | "model_limit" | "step_limit" | "stopped";
         error: string | null;
         details?: AgentCoreErrorDetails | undefined;
     }>;
     runOutcome(message: AgentCoreInput, host: AgentCoreHost, emit: (event: AgentCoreEvent) => Promise<void>, signal: AbortSignal): Promise<{
         output?: z.util.JSONType | undefined;
-        reason: "awaiting_approval" | "cancelled" | "completed" | "failed" | "model_limit" | "step_limit" | "stopped";
+        reason: "awaiting_approval" | "awaiting_tool_results" | "cancelled" | "completed" | "failed" | "model_limit" | "step_limit" | "stopped";
         error: string | null;
         details?: AgentCoreErrorDetails | undefined;
     }>;

package/dist/experimental/agent-core.js

@@ -351,7 +351,7 @@ export function createAgentCore(module, config) {
             })),
         },
     }).exports);
-    if (exports.agent_abi_version() !== 13)
+    if (exports.agent_abi_version() !== 14)
         throw new Error("Unsupported Agent Core ABI.");
     const run = jspi.promising(exports.agent_run);
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gea-ai/agent-sdk",
-  "version": "0.1.260920-alpha.0",
+  "version": "0.1.260920-alpha.2",
   "private": false,
   "homepage": "https://musegea.com/developers",
   "license": "Apache-2.0",
@@ -104,7 +104,7 @@
     "@ai-sdk/otel": "1.0.9",
     "@ai-sdk/provider": "4.0.1",
     "@ai-sdk/provider-utils": "5.0.2",
-    "@gea-ai/contract": "0.1.260920-alpha.0",
+    "@gea-ai/contract": "0.1.260920-alpha.2",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/context-async-hooks": "2.10.0",
     "@opentelemetry/core": "2.10.0",