@gea-ai/agent-sdk 0.1.261009-alpha.0 → 0.1.261010-alpha.0

package/dist/agent-call.d.ts

@@ -1225,7 +1225,9 @@ export declare function createWorkerRunCancelTool({ host, }: {
         status: "abort_requested" | "not_running";
     }, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 });
-export declare function readWorkerAgentResponse(response: Response): Promise<{
+export declare function readWorkerAgentResponse(response: Response, options?: {
+    persistedSessionWaiting?: () => Promise<boolean>;
+}): Promise<{
     status: "completed" | "suspended";
     text: string;
 }>;

package/dist/agent-call.js

@@ -70,6 +70,23 @@ export function createWorkerAgentTool(input) {
                             error: "child_busy",
                             message: "This child Session has unfinished work. Wait for its Run before continuing the Session.",
                         };
+                    if (response.status === 403) {
+                        const rejection = z
+                            .object({
+                            error: z
+                                .string()
+                                .max(80)
+                                .regex(/^[A-Za-z0-9_.-]+$/),
+                        })
+                            .safeParse(value);
+                        if (rejection.success) {
+                            console.error("Child run rejected", {
+                                status: 403,
+                                error: rejection.data.error,
+                            });
+                            throw new Error(`Agent invocation was rejected (403 ${rejection.data.error}).`);
+                        }
+                    }
                 }
                 throw new Error(`Agent invocation was rejected (${response.status}).`);
             }
@@ -99,7 +116,15 @@ export function createWorkerRunCancelTool({ host, }) {
 }
 class AgentChildRunResponseError extends TaggedError("AgentChildRunResponseError")() {
 }
-export async function readWorkerAgentResponse(response) {
+const childDiagnosticIdentifierPattern = /^[A-Za-z0-9_.-]+$/;
+function childDiagnosticIdentifier(value) {
+    return typeof value === "string" &&
+        value.length <= 80 &&
+        childDiagnosticIdentifierPattern.test(value)
+        ? value
+        : undefined;
+}
+export async function readWorkerAgentResponse(response, options) {
     if (response.status === 409 &&
         response.headers.get("x-gea-session-execution") === "already-started") {
         await response.body?.cancel();
@@ -117,6 +142,9 @@ export async function readWorkerAgentResponse(response) {
     let completed = false;
     let suspended = false;
     let failure;
+    let legacyToolCalls = false;
+    let otherUnacceptableFinish = false;
+    let sawStreamFailure = false;
     const reader = parseJsonEventStream({
         stream: response.body,
         schema: uiMessageChunkSchema,
@@ -133,26 +161,46 @@ export async function readWorkerAgentResponse(response) {
             const chunk = event.value;
             if (chunk.type === "text-delta")
                 text += chunk.delta;
-            if (chunk.type === "error")
+            if (chunk.type === "error") {
+                sawStreamFailure = true;
                 failure ??= new AgentChildRunResponseError({
                     code: "child_stream_error",
                     message: chunk.errorText,
                 });
-            if (chunk.type === "abort")
+            }
+            if (chunk.type === "abort") {
+                sawStreamFailure = true;
                 failure ??= new AgentChildRunResponseError({
                     code: "child_stream_aborted",
                     message: "Child Agent was cancelled.",
                 });
+            }
             if (chunk.type === "finish") {
                 suspended = z
                     .object({ sessionStatus: z.literal("waiting") })
                     .safeParse(chunk.messageMetadata).success;
-                if (chunk.finishReason !== "stop" &&
-                    !(suspended && chunk.finishReason === "tool-calls"))
+                const unacceptable = chunk.finishReason !== "stop" &&
+                    !(suspended && chunk.finishReason === "tool-calls");
+                if (unacceptable) {
+                    if (chunk.finishReason === "tool-calls" && !suspended)
+                        legacyToolCalls = true;
+                    else
+                        otherUnacceptableFinish = true;
+                    const parsedSession = z
+                        .object({ sessionStatus: z.unknown() })
+                        .safeParse(chunk.messageMetadata);
+                    const rawSessionStatus = parsedSession.success
+                        ? parsedSession.data.sessionStatus
+                        : undefined;
+                    const sessionStatus = childDiagnosticIdentifier(rawSessionStatus);
                     failure ??= new AgentChildRunResponseError({
                         code: "child_finish_reason",
                         message: `Child Agent did not complete (${chunk.finishReason ?? "unknown"}).`,
+                        finishReason: childDiagnosticIdentifier(chunk.finishReason) ?? "unknown",
+                        hasSessionStatus: rawSessionStatus !== undefined,
+                        ...(sessionStatus ? { sessionStatus } : {}),
                     });
+                }
                 completed = true;
             }
         }
@@ -161,6 +209,18 @@ export async function readWorkerAgentResponse(response) {
         await reader.cancel();
         reader.releaseLock();
     }
+    if (options?.persistedSessionWaiting &&
+        legacyToolCalls &&
+        !otherUnacceptableFinish &&
+        !sawStreamFailure &&
+        failure instanceof AgentChildRunResponseError &&
+        failure.code === "child_finish_reason") {
+        const waiting = await Result.tryPromise(() => options.persistedSessionWaiting());
+        if (waiting.isOk() && waiting.value) {
+            failure = undefined;
+            suspended = true;
+        }
+    }
     if (failure)
         throw failure;
     if (!completed)

package/dist/agent-channel-api.js

@@ -40,7 +40,7 @@ export function extractChannelReply(messageValue, responseMessageId) {
 }
 /** Channel owns delivery; ordinary Agents API owns admission, execution and history. */
 export async function executeChannelAgentRun(input) {
-    const fetchApi = async (path, body) => {
+    const fetchApi = async (path, body, headers) => {
         input.signal.throwIfAborted();
         const response = await input.binding.fetch(`/api/v1${path}`, {
             method: body === undefined ? "GET" : "POST",
@@ -48,7 +48,7 @@ export async function executeChannelAgentRun(input) {
             ...(body === undefined
                 ? {}
                 : {
-                    headers: { "content-type": "application/json" },
+                    headers: { "content-type": "application/json", ...headers },
                     body: JSON.stringify(body),
                 }),
         });
@@ -67,7 +67,7 @@ export async function executeChannelAgentRun(input) {
         id: input.runId,
         input: input.message,
         stream: false,
-    })).body?.cancel();
+    }, { "idempotency-key": input.runId })).body?.cancel();
     let stream = true;
     for (;;) {
         const current = runSchema.parse(await (await fetchApi(`/runs/${input.runId}`)).json());

package/dist/agent-remote-run.js

@@ -62,13 +62,42 @@ export async function submitRemoteRun(fetch, input, options = {}) {
             }))).id;
             signal.throwIfAborted();
             submitting = true;
-            // No automatic replay: a lost response does not prove Run admission failed.
-            const response = await fetch(`/sessions/${sessionId}/runs`, {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                signal,
-                body: JSON.stringify({ input: message, stream: false }),
+            // One key per logical submission. Retries reuse it so a lost 202 cannot
+            // start a second Run. A later call to submitRemoteRun is a new request.
+            const idempotencyKey = crypto.randomUUID();
+            const runBody = JSON.stringify({
+                id: idempotencyKey,
+                input: message,
+                stream: false,
             });
+            const runHeaders = {
+                "content-type": "application/json",
+                "idempotency-key": idempotencyKey,
+            };
+            let response;
+            for (let attempt = 0; attempt < 3; attempt++) {
+                signal.throwIfAborted();
+                try {
+                    response = await fetch(`/sessions/${sessionId}/runs`, {
+                        method: "POST",
+                        headers: runHeaders,
+                        signal,
+                        body: runBody,
+                    });
+                }
+                catch (error) {
+                    if (signal.aborted || attempt === 2)
+                        throw error;
+                    continue;
+                }
+                const retryable = [502, 503, 504].includes(response.status);
+                const admitted = response.headers.has("x-gea-agent-run-id");
+                if (!retryable || admitted || attempt === 2)
+                    break;
+                await response.body?.cancel();
+            }
+            if (!response)
+                throw new Error("Remote Run was not submitted.");
             rejected = [400, 401, 403, 404, 405, 409, 413, 415, 422, 429].includes(response.status);
             const run = agentHttpRunSchema.parse(await responseJson(response));
             if (run.session_id !== sessionId)

package/dist/agent-run-host.d.ts

@@ -11,17 +11,21 @@ export type AgentChildRunSession = (operation: string, body: unknown, traceConte
 export declare class AgentRunHost {
     private readonly host;
     private readonly executions;
+    private readonly executionDone;
     private readonly work;
     private closed;
     private readonly shutdown;
     constructor(host: {
         session: AgentChildRunSession;
+        /** Authorize against the root Session and return its retained child binding. */
+        resolveSession?(sessionId: string): Promise<Response>;
         remoteFetch?(destination: RemoteRunDestination, path: string, init?: RequestInit): Promise<Response>;
         transferRemoteInputs?(destination: RemoteRunDestination, files: RemoteInputFiles, scope: StudioArtifactScope | undefined, signal: AbortSignal): Promise<RemoteFileMapping>;
         register(run: AgentChildRun): Promise<string>;
         invoke(run: AgentChildRun, signal: AbortSignal, continuation?: TraceContinuation, inboxExecution?: AgentSessionInboxExecution): Promise<{
             response: Response;
             dispose?: () => void;
+            persistedSessionWaiting?: () => Promise<boolean>;
         }>;
         cancelChild(run: AgentChildRun): Promise<boolean | void>;
         onError(error: unknown, identity?: {

package/dist/agent-run-host.js

@@ -1,7 +1,7 @@
 import { submitRemoteRun, observeRemoteRun, cancelRemoteRun, } from "./agent-remote-run.js";
 import { z } from "zod";
 import { Result } from "better-result";
-import { agentChildRunSchema, getAgentCallFileIds, agentChildRunListResultSchema, agentChildRunStartResultSchema, } from "@gea-ai/contract/agent-worker-tools";
+import { agentChildRunSchema, agentChildSessionSchema, getAgentCallFileIds, agentChildRunListResultSchema, agentChildRunStartResultSchema, } from "@gea-ai/contract/agent-worker-tools";
 import { readWorkerAgentResponse } from "./agent-call.js";
 export { readWorkerAgentResponse } from "./agent-call.js";
 export { streamManagedAgentSessionRun } from "./agent-session-stream.js";
@@ -9,6 +9,7 @@ export { streamManagedAgentSessionRun } from "./agent-session-stream.js";
 export class AgentRunHost {
     host;
     executions = new Map();
+    executionDone = new Map();
     work = new Set();
     closed = false;
     shutdown = new AbortController();
@@ -31,24 +32,94 @@ export class AgentRunHost {
         return this.host.session(operation, body, traceContext);
     }
     async start(input) {
-        if (input.sessionId) {
+        let authorizedSession;
+        if (input.sessionId && this.host.resolveSession) {
+            const response = await this.host.resolveSession(input.sessionId);
+            if (!response.ok)
+                return response;
+            authorizedSession = z
+                .object({ session: agentChildSessionSchema })
+                .parse(await response.json()).session;
+            if (authorizedSession.sessionId !== input.sessionId ||
+                (input.target !== undefined &&
+                    input.target !==
+                        (authorizedSession.target ?? authorizedSession.agentKey)))
+                return Response.json({ error: "unknown_child_session" }, { status: 403 });
+            input = {
+                ...input,
+                agentKey: authorizedSession.agentKey,
+                target: authorizedSession.target ?? authorizedSession.agentKey,
+                destination: authorizedSession.destination,
+            };
+            // Existing parent ledgers already carry this immutable binding. Keep their
+            // original start payload so deployed strict-schema bundles still resume.
+            const listed = await this.host.session("list", {});
+            if (!listed.ok)
+                return listed;
+            const page = agentChildRunListResultSchema.parse(await listed.json());
+            if (page.runs.some((run) => run.sessionId === input.sessionId)) {
+                authorizedSession = undefined;
+            }
+            else if (page.subagentConcurrencyVersion) {
+                const local = await this.host.session("session", {
+                    sessionId: input.sessionId,
+                });
+                if (local.ok) {
+                    z.object({
+                        session: agentChildSessionSchema.omit({ sessionId: true }),
+                    }).parse(await local.json());
+                    authorizedSession = undefined;
+                }
+                else if (local.status !== 403)
+                    return local;
+            }
+        }
+        else if (input.sessionId) {
             const response = await this.host.session("list", {});
             if (!response.ok)
                 return response;
             const page = agentChildRunListResultSchema.parse(await response.json());
-            let destination = page.runs.find((run) => run.sessionId === input.sessionId)?.destination;
+            const listed = page.runs.find((run) => run.sessionId === input.sessionId);
+            let destination = listed?.destination;
+            let recordedTarget;
             if (page.subagentConcurrencyVersion) {
                 const relation = await this.host.session("session", {
                     sessionId: input.sessionId,
                 });
+                // This parent ledger does not own the Session. Do not invent a target.
                 if (!relation.ok)
                     return relation;
-                destination = z
+                const session = z
                     .object({
-                    session: agentChildRunSchema.pick({ destination: true }).strip(),
+                    session: agentChildRunSchema
+                        .pick({ target: true, agentKey: true, destination: true })
+                        .strip(),
                 })
-                    .parse(await relation.json()).session.destination;
+                    .parse(await relation.json()).session;
+                destination = session.destination;
+                recordedTarget = session.target ?? session.agentKey;
             }
+            else if (!listed) {
+                return Response.json({ error: "unknown_child_session" }, { status: 403 });
+            }
+            else {
+                recordedTarget = listed.target ?? listed.agentKey;
+            }
+            // v0.56.2 bundles admit resume only when
+            // (stored target ?? agentKey) === (request target ?? request agentKey).
+            // Dispatch sends the parent agentKey and may omit target. Copy the
+            // ledger target after ownership is confirmed. Legacy remote admission
+            // compares the stored target on this host and does not use that copy.
+            const callsBundle = destination?.type !== "remote" || !!page.subagentConcurrencyVersion;
+            if (callsBundle &&
+                recordedTarget !== undefined &&
+                input.target !== undefined &&
+                input.target !== recordedTarget)
+                return Response.json({ error: "unknown_child_session" }, { status: 403 });
+            if (callsBundle &&
+                input.target === undefined &&
+                recordedTarget !== undefined)
+                input = { ...input, target: recordedTarget };
             if (destination?.type === "remote")
                 return this.startRemote({ ...input, destination });
             input = { ...input, destination: destination ?? input.destination };
@@ -56,7 +127,10 @@ export class AgentRunHost {
         if (this.closed)
             return new Response("Run dispatcher is stopping", { status: 503 });
         const { artifactScope: _artifactScope, signal: _signal, ...sessionInput } = input;
-        const response = await this.host.session("start", sessionInput);
+        const response = await this.host.session("start", {
+            ...sessionInput,
+            ...(authorizedSession ? { authorizedSession } : {}),
+        });
         if (!response.ok)
             return response;
         const { run, scheduled } = agentChildRunStartResultSchema.parse(await response.json());
@@ -96,10 +170,12 @@ export class AgentRunHost {
             if (input.sessionId) {
                 const previous = runs.find((run) => run.sessionId === input.sessionId);
                 if (!previous ||
-                    previous.target !== input.target ||
+                    (input.target !== undefined && input.target !== previous.target) ||
                     JSON.stringify(previous.destination) !==
                         JSON.stringify(input.destination))
                     return new Response("Unknown child Session", { status: 403 });
+                if (input.target === undefined && previous.target !== undefined)
+                    sessionInput.target = previous.target;
                 if (runs.some((run) => run.sessionId === input.sessionId && !run.outcome))
                     return new Response("Child Session is busy", { status: 409 });
             }
@@ -185,7 +261,11 @@ export class AgentRunHost {
             runId: run.id,
             sessionId: run.sessionId,
         });
-        this.track(this.execute(run, cancellation, inboxExecution), {
+        const done = this.execute(run, cancellation, inboxExecution).finally(() => {
+            this.executionDone.delete(run.id);
+        });
+        this.executionDone.set(run.id, done);
+        this.track(done, {
             runId: run.id,
             sessionId: run.sessionId,
         });
@@ -268,7 +348,9 @@ export class AgentRunHost {
             await this.host.register(run);
             const invocation = await this.host.invoke(run, cancellation.signal, inboxExecution?.tracing ?? { parent: run.traceContext, links: [] }, inboxExecution);
             try {
-                await readWorkerAgentResponse(invocation.response);
+                await readWorkerAgentResponse(invocation.response, {
+                    persistedSessionWaiting: invocation.persistedSessionWaiting,
+                });
             }
             finally {
                 invocation.dispose?.();
@@ -308,8 +390,10 @@ export class AgentRunHost {
             }
             else {
                 this.dispatch(run);
-                if ((await this.host.cancelChild(run)) !== false)
+                if ((await this.host.cancelChild(run)) !== false) {
                     this.executions.get(runId)?.abort();
+                    await this.executionDone.get(runId);
+                }
             }
         }
         return Response.json({

package/dist/agent-session-children.js

@@ -3,7 +3,7 @@ import { agentApplicationAssistantMessageSchema } from "@gea-ai/contract/agent-a
 import { readTraceContext } from "./trace-context.js";
 import { traceContextSchema } from "@gea-ai/contract/traces";
 import { DEFAULT_MAX_CONCURRENT_SUBAGENTS, maxConcurrentSubagentsSchema, } from "@gea-ai/contract/agent-packages";
-import { AGENT_SUBAGENT_CONCURRENCY_HEADER, agentChildRunSchema, agentChildRunStartInputSchema, agentChildRunDestinationSchema, agentChildRunOutcomeSchema, agentChildRunListInputSchema, } from "@gea-ai/contract/agent-worker-tools";
+import { AGENT_SUBAGENT_CONCURRENCY_HEADER, agentChildRunSchema, agentChildSessionSchema, agentChildRunStartInputSchema, agentChildRunDestinationSchema, agentChildRunOutcomeSchema, agentChildRunListInputSchema, } from "@gea-ai/contract/agent-worker-tools";
 import { notifyAgentSessionChildRun, scheduleAgentSessionChildRunChanges, queueAgentSessionChildRun, acceptAgentSessionChildRun, inheritedAgentSessionMetadata, } from "./agent-session-inbox.js";
 import { getChildRun, getChildSession, listChildRuns, putChildRun, readChildRunIndex, readChildRuns, saveChildRunIndex, } from "./agent-session-child-store.js";
 const runIdSchema = z.strictObject({ runId: z.uuid() });
@@ -12,6 +12,8 @@ const startSchema = agentChildRunStartInputSchema.extend({
     agentKey: z.string().min(1).max(80),
     destination: agentChildRunDestinationSchema.optional(),
     traceContext: traceContextSchema.optional(),
+    // Only the controlled Host transport can supply a root-authorized binding.
+    authorizedSession: agentChildSessionSchema.optional(),
 });
 const reservationSchema = startSchema
     .pick({
@@ -96,14 +98,38 @@ export async function handleAgentSessionChildren(request, storage) {
                 const runs = await readChildRuns(tx);
                 if (!index && runs.length >= 128)
                     return Response.json({ error: "child_run_limit" }, { status: 409 });
-                const previous = input.sessionId
-                    ? await getChildSession(tx, input.sessionId)
+                if (input.authorizedSession &&
+                    (remote ||
+                        input.authorizedSession.sessionId !== input.sessionId ||
+                        input.authorizedSession.destination.type !== "worker"))
+                    return Response.json({ error: "unknown_child_session" }, { status: 403 });
+                const previous = input.authorizedSession ??
+                    (input.sessionId
+                        ? await getChildSession(tx, input.sessionId)
+                        : undefined);
+                // Hosted callers authorize the root Session. The local ledger remains
+                // the binding source for hosts without a Session directory.
+                if (input.sessionId && !previous)
+                    return Response.json({ error: "unknown_child_session" }, { status: 403 });
+                const recordedTarget = previous
+                    ? (previous.target ?? previous.agentKey)
                     : undefined;
-                if (input.sessionId &&
-                    (!previous ||
-                        (previous.target ?? previous.agentKey) !==
-                            (input.target ?? input.agentKey)))
+                if (previous &&
+                    input.target !== undefined &&
+                    input.target !== recordedTarget)
                     return Response.json({ error: "unknown_child_session" }, { status: 403 });
+                const resumedTarget = input.target ?? previous?.target;
+                const { authorizedSession: _authorizedSession, ...startInput } = input;
+                const continued = {
+                    ...startInput,
+                    ...(resumedTarget === undefined ? {} : { target: resumedTarget }),
+                    ...(previous
+                        ? {
+                            agentKey: previous.agentKey,
+                            destination: previous.destination ?? input.destination,
+                        }
+                        : {}),
+                };
                 if (remote &&
                     previous &&
                     JSON.stringify(previous.destination) !==
@@ -132,12 +158,12 @@ export async function handleAgentSessionChildren(request, storage) {
                         id: reservationId,
                         sessionId: input.sessionId,
                     });
-                    await tx.put(`child-reservation:${reservationId}`, reservationSchema.parse(input));
+                    await tx.put(`child-reservation:${reservationId}`, reservationSchema.parse(continued));
                     await saveChildRunIndex(tx, index);
                     return Response.json({ reservationId });
                 }
                 const run = agentChildRunSchema.parse({
-                    ...input,
+                    ...continued,
                     id: crypto.randomUUID(),
                     sessionId: input.sessionId ?? crypto.randomUUID(),
                     agentKey: previous?.agentKey ?? input.agentKey,

package/dist/agent-session-inbox.js

@@ -35,6 +35,8 @@ const stateSchema = z.strictObject({
     transport: agentSessionTransportSchema.nullable().default(null),
     started: z.boolean().default(false),
     stopped: z.boolean().default(false),
+    /** User cancel. Process recovery sets `stopped` with `interrupted` and must not set this. */
+    cancelRequested: z.boolean().default(false),
     resumeWait: agentRunWaitResultSchema.nullable().default(null),
     pendingStarts: z.array(z.uuid()).max(128).default([]),
     terminal: terminalSchema.nullable().default(null),
@@ -238,9 +240,13 @@ export async function queueAgentSessionChildRun(tx, run) {
     // External protocols retain their own execution and cancellation transport.
     if (!state?.transport)
         return false;
-    // A remote receipt can arrive after its parent's cancellation or terminal commit.
-    if (state.stopped ||
-        (await tx.get(`inbox:outcome:${run.parentRunId}`)) !== undefined) {
+    // Explicit cancellation propagates to delayed receipts. Ordinary parent
+    // completion does not revoke an already admitted child dispatch.
+    const savedOutcome = await tx.get(`inbox:outcome:${run.parentRunId}`);
+    const parentCancelled = savedOutcome !== undefined &&
+        agentSessionDispatchSchema.shape.outcome.unwrap().parse(savedOutcome)
+            .status === "cancelled";
+    if (state.stopped || parentCancelled) {
         run.cancelRequested = true;
         await putChildRun(tx, run);
     }
@@ -423,7 +429,11 @@ export async function notifyAgentSessionChildRun(tx, run) {
     if (!state || !run.outcome)
         return;
     const runs = await readInboxChildRuns(tx, state);
-    if (state.stopped) {
+    // Completion belongs to the originating Run. A later turn can explicitly
+    // wait for this receipt, but must not receive an unsolicited old notification.
+    const parentFinished = (await tx.get(`inbox:outcome:${run.parentRunId}`)) !== undefined;
+    if (state.stopped ||
+        (parentFinished && !state.wait?.runIds.includes(run.id))) {
         await save(tx, state, runs);
         return;
     }
@@ -482,6 +492,45 @@ async function finishInbox(tx, state, runs, input) {
             pendingStarts: state.pendingStarts.length,
         });
     }
+    // A durable user cancel wins a later transport failure or shutdown abort.
+    // Socket close can report `failed` before the worker observes the abort,
+    // and a request abort without cancelRequestedAt is only an interruption.
+    // Release can arrive after cancelRequestedAt is stored but before the inbox
+    // flag. An interrupted stop (process recovery or graceful shutdown) sets
+    // `stopped` without that flag and must stay failed or interrupted.
+    if (outcome?.status === "failed" ||
+        outcome?.status === "cancelled" ||
+        outcome?.status === "interrupted") {
+        const storedTurn = await tx.get("execution-v2:active-turn");
+        const turn = storedTurn === undefined
+            ? null
+            : agentSessionExecutionTurnSchema.parse(storedTurn);
+        const userCancel = state.cancelRequested ||
+            (turn?.runId === state.execution.turnId &&
+                Boolean(turn.cancelRequestedAt));
+        if (userCancel) {
+            if (outcome.status !== "cancelled")
+                outcome = { ...outcome, status: "cancelled" };
+            state.cancelRequested = true;
+            state.stopped = true;
+        }
+    }
+    // A later transport failure must not replace a cancel this turn already sealed.
+    if (outcome?.status === "failed" || outcome?.status === "interrupted") {
+        const turnId = state.execution.turnId;
+        const sealedCancelled = [state.terminal, ...state.terminalQueue].some((entry) => entry?.execution.turnId === turnId &&
+            entry.outcome.status === "cancelled");
+        const stored = sealedCancelled
+            ? undefined
+            : await tx.get(`inbox:outcome:${turnId}`);
+        const storedOutcome = stored === undefined
+            ? null
+            : agentSessionDispatchSchema.shape.outcome.unwrap().safeParse(stored);
+        if (sealedCancelled || storedOutcome?.data?.status === "cancelled") {
+            outcome = { ...outcome, status: "cancelled" };
+            state.stopped = true;
+        }
+    }
     if (inputWait && !outcome && !state.stopped) {
         state.inputWait = {
             turnId: state.execution.turnId,
@@ -599,6 +648,7 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                 transport: null,
                 started: false,
                 stopped: false,
+                cancelRequested: false,
                 resumeWait: null,
                 terminal: null,
                 draining: null,
@@ -707,8 +757,10 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                 state.inputWait = null;
                 state.inputNotification = null;
                 state.resumeWait = null;
-                if (!state.draining)
+                if (!state.draining) {
                     state.stopped = false;
+                    state.cancelRequested = false;
+                }
                 state.started = path === "/v1/inbox/start";
                 if (input.message)
                     await tx.put(`inbox:message:${input.message.id}`, input.message);
@@ -775,8 +827,10 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                 if (new TextEncoder().encode(JSON.stringify(state) + JSON.stringify(message)).byteLength > 2_000_000)
                     return Response.json({ error: "inbox_full" }, { status: 429 });
                 state.messages.push(message);
-                if (!state.draining)
+                if (!state.draining) {
                     state.stopped = false;
+                    state.cancelRequested = false;
+                }
                 await tx.put(key, message);
                 await save(tx, state, runs);
                 return Response.json({ id: message.id, duplicate: false });
@@ -805,6 +859,7 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                 const joining = state.wait?.toolCallId === null;
                 await consumeInputRequest(tx, state, runs, result);
                 state.stopped = false;
+                state.cancelRequested = false;
                 state.execution = {
                     id: crypto.randomUUID(),
                     metadata: state.metadata,
@@ -847,6 +902,8 @@ export async function handleAgentSessionInboxRequest(request, storage) {
                             state.draining?.execution.turnId))
                     return Response.json({ cancelled: false });
                 state.stopped = true;
+                if (!input.interrupted)
+                    state.cancelRequested = true;
                 if (input.cancelPending)
                     state.messages = [];
                 if (state.wait?.toolCallId)

package/dist/agent-worker.js

@@ -14,6 +14,7 @@ import { agentToolOutputOffloadOptionsSchema } from "@gea-ai/contract/agent-cont
 import { resolveAgentToolOutputOffload } from "@gea-ai/contract/agent-context";
 import { decodeAgentModelProxyValue, encodeAgentModelProxyValue, } from "@gea-ai/contract/agent-model-proxy";
 import { createGeaAI, modelDescriptorSchema } from "./gea-ai.js";
+import { hostRejectionError } from "./host-rejection.js";
 import { storeToolModelOutput, resolveToolArtifacts, } from "./tool-model-output.js";
 import { mcpToolModelOutput } from "./mcp-tool-output.js";
 import { AgentMediaReadError, readAgentMedia } from "./agent-media-read.js";
@@ -2340,7 +2341,7 @@ function createHostBackedAgentTools(input) {
 async function requireHostJson(host, path, init) {
     const response = await host.fetch(`${HOST_PATH}${path}`, init);
     if (!response.ok)
-        throw new Error(`Agent host rejected ${path} (${response.status}).`);
+        throw await hostRejectionError(path, response);
     return decodeWireValue(await response.json());
 }
 async function createGeaCoreConnection(host, publicModel, requestOptions, signal, maxOutputTokens) {
@@ -2762,12 +2763,38 @@ export async function runAgentWorkerRequest(input) {
                 });
                 if (input.inboxExecution) {
                     const inboxStartedAt = performance.now();
-                    const status = termination === "cancelled"
+                    let status = termination === "cancelled"
                         ? "cancelled"
-                        : termination === "failed" ||
-                            results.some((result) => result.status === "rejected")
-                            ? "failed"
-                            : inboxOutcome.status;
+                        : termination === "interrupted"
+                            ? "interrupted"
+                            : termination === "failed" ||
+                                results.some((result) => result.status === "rejected")
+                                ? "failed"
+                                : inboxOutcome.status;
+                    // A request abort is interrupted until a durable user cancel is
+                    // visible. Parent cancel sets cancelRequestedAt before aborting
+                    // the fetch, so this recheck still seals that run as cancelled.
+                    if ((status === "failed" || status === "interrupted") &&
+                        input.sessionExecution) {
+                        try {
+                            const state = await requestSessionJson({
+                                chatId: sessionChatId,
+                                method: "GET",
+                                namespace: input.sessionNamespace,
+                                path: "/v2/state?view=metadata",
+                                schema: agentSessionExecutionStateSchema,
+                            });
+                            const active = state.activeTurn;
+                            if (active?.cancelRequestedAt &&
+                                active.runId === input.sessionExecution.runId &&
+                                active.attemptId === input.sessionExecution.attemptId)
+                                status = "cancelled";
+                        }
+                        catch {
+                            // A metadata miss must not skip release. finishInbox remaps a
+                            // failed or interrupted outcome when the same cancel is durable.
+                        }
+                    }
                     invocationSpan?.setAttribute("gea.session.status", status);
                     const inbox = {
                         executionId: input.inboxExecution.id,
@@ -2900,12 +2927,16 @@ export async function runAgentWorkerRequest(input) {
                 stopComputer = stop;
             }, (outcome) => {
                 inboxOutcome = outcome;
-                if (outcome.status === "failed" || outcome.status === "cancelled")
+                if (outcome.status === "failed" ||
+                    outcome.status === "cancelled" ||
+                    outcome.status === "interrupted")
                     termination ??= outcome.status;
             }, invocationTiming);
         }
         catch (error) {
-            termination ??= signal.aborted ? "cancelled" : "failed";
+            // Lease expiry and an explicit cancel assign termination before they
+            // abort. A bare request abort is process shutdown, not a user cancel.
+            termination ??= signal.aborted ? "interrupted" : "failed";
             cancellation.abort(error);
             try {
                 await finish();
@@ -2938,7 +2969,7 @@ export async function runAgentWorkerRequest(input) {
                 throw failure.reason;
         };
         const cancel = (reason) => {
-            termination ??= "cancelled";
+            termination ??= "interrupted";
             return stop(reason);
         };
         const onAbort = () => waitUntil(cancel(signal.reason));
@@ -2966,7 +2997,7 @@ export async function runAgentWorkerRequest(input) {
                     controller.close();
                 }
                 catch (error) {
-                    termination ??= "failed";
+                    termination ??= signal.aborted ? "interrupted" : "failed";
                     try {
                         await stop(error);
                     }
@@ -4120,7 +4151,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         // A UI reader may cancel as soon as it receives an error chunk. Preserve
         // the execution's original failure before publishing that chunk.
         ownSessionOutcome({
-            status: input.request.signal.aborted ? "cancelled" : "failed",
+            status: input.request.signal.aborted ? "interrupted" : "failed",
             text: executionErrorText(error),
         });
         recordExecutionFailure(error);
@@ -4207,6 +4238,9 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     };
     let terminalMessage;
     let terminalEvent;
+    // Inbox suspension is a live protocol frame, not a journaled response end.
+    // Hold it until the final context commit so a failed commit cannot publish waiting.
+    let liveFinish;
     const saveResponseMessage = async ({ responseMessage, }) => {
         const saveStartedAt = performance.now();
         const metadata = await contextFinished;
@@ -4224,6 +4258,21 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         }
         if (inboxRunner?.suspended)
             context.metadata.suspendedMessageId = responseMessage.id;
+        const needsInput = !inboxRunner?.suspended &&
+            responseMessage.parts.some((part) => "state" in part &&
+                (part.state === "approval-requested" ||
+                    (part.state === "input-available" &&
+                        input.snapshot.tools.some((tool) => tool.type === "custom" &&
+                            tool.execution === "client" &&
+                            part.type === `tool-${tool.name}`))));
+        // The same metadata object is held by the deferred finish frame. Do not
+        // publish waiting until the final context commit succeeds; a failed commit
+        // seals the call as failed and must not leave the message looking suspended.
+        const markWaiting = !failure &&
+            (needsInput ||
+                Boolean(inboxRunner?.suspended && metadata.sessionStatus === "waiting"));
+        if (markWaiting)
+            delete metadata.sessionStatus;
         responseMessage.metadata = {
             ...responseMessage.metadata,
             ...metadata,
@@ -4258,7 +4307,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             // journal. Throwing from onFinish would truncate those chunks and hide
             // both the error and final usage from clients.
             ownSessionOutcome({
-                status: input.request.signal.aborted ? "cancelled" : "failed",
+                status: input.request.signal.aborted ? "interrupted" : "failed",
                 text: executionErrorText(failure.error, responseMessage.parts
                     .flatMap((part) => (part.type === "text" ? [part.text] : []))
                     .join("")),
@@ -4276,19 +4325,39 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             }
             throw error;
         }
+        if (markWaiting) {
+            metadata.sessionStatus = "waiting";
+            responseMessage.metadata = {
+                ...responseMessage.metadata,
+                sessionStatus: "waiting",
+            };
+            if (terminalMessage) {
+                terminalMessage = {
+                    ...terminalMessage,
+                    metadata: {
+                        ...terminalMessage.metadata,
+                        sessionStatus: "waiting",
+                    },
+                };
+            }
+            else if (sessionExecution) {
+                await mutateSession({ messages: [{ ...responseMessage }] });
+            }
+            else {
+                await appendSessionValue({
+                    body: { message: responseMessage, runId: payload.runId },
+                    chatId: payload.chatId,
+                    namespace: input.sessionNamespace,
+                    path: "/v1/messages",
+                });
+            }
+        }
         const contextPersistedAt = performance.now();
         persistenceSpan?.setAttributes({
             "gea.session.finish.context_wait_ms": Math.round(contextFinishedAt - saveStartedAt),
             "gea.session.finish.transcript_ms": Math.round(transcriptFinishedAt - transcriptStartedAt),
             "gea.session.finish.context_write_ms": Math.round(contextPersistedAt - transcriptFinishedAt),
         });
-        const needsInput = !inboxRunner?.suspended &&
-            responseMessage.parts.some((part) => "state" in part &&
-                (part.state === "approval-requested" ||
-                    (part.state === "input-available" &&
-                        input.snapshot.tools.some((tool) => tool.type === "custom" &&
-                            tool.execution === "client" &&
-                            part.type === `tool-${tool.name}`))));
         ownSessionOutcome({
             ...(needsInput
                 ? {
@@ -4957,14 +5026,19 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                         finishReason: metadata.finishReason,
                         messageMetadata: metadata,
                     };
-                    if (metadata.sessionStatus === "waiting") {
-                        controller.enqueue(chunk);
+                    if (inboxRunner?.suspended && metadata.finishReason !== "error") {
+                        // onFinish commits context before this frame is published. The
+                        // journal keeps the resumed response's finish, not this boundary.
+                        liveFinish = chunk;
                         continue;
                     }
-                    if (sessionExecution &&
-                        !input.channelJournal &&
-                        !inboxRunner?.suspended &&
-                        metadata.finishReason === "stop") {
+                    if (metadata.finishReason === "tool-calls" ||
+                        (sessionExecution &&
+                            !input.channelJournal &&
+                            !inboxRunner?.suspended &&
+                            metadata.finishReason === "stop")) {
+                        // onFinish commits context before publishing waiting metadata.
+                        // Flush emits this frame only after that commit returns.
                         terminalEvent = chunk;
                         continue;
                     }
@@ -4982,16 +5056,26 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 controller.enqueue(event);
         },
         async flush(controller) {
-            if (!terminalMessage && !terminalEvent)
+            if (!terminalMessage && !terminalEvent && !liveFinish)
                 return;
-            const startedAt = performance.now();
-            await mutateSession({
-                ...(terminalMessage ? { messages: [{ ...terminalMessage }] } : {}),
-                ...(terminalEvent ? { events: [terminalEvent] } : {}),
-            });
-            persistenceSpan?.setAttribute("gea.session.finish.transcript_ms", Math.round(performance.now() - startedAt));
+            if (terminalMessage || terminalEvent) {
+                const startedAt = performance.now();
+                if (sessionExecution) {
+                    await mutateSession({
+                        ...(terminalMessage
+                            ? { messages: [{ ...terminalMessage }] }
+                            : {}),
+                        ...(terminalEvent ? { events: [terminalEvent] } : {}),
+                    });
+                }
+                else if (terminalEvent)
+                    await appendStreamEvent(terminalEvent);
+                persistenceSpan?.setAttribute("gea.session.finish.transcript_ms", Math.round(performance.now() - startedAt));
+            }
             if (terminalEvent)
                 controller.enqueue(terminalEvent);
+            if (liveFinish)
+                controller.enqueue(liveFinish);
         },
     }));
     if (engine || sessionExecution) {

package/dist/gea-ai.js

@@ -7,6 +7,7 @@ import { AGENT_MODEL_PROXY_PROTOCOL_VERSION, AGENT_MODEL_PROXY_TRANSPORT, agentC
 import { mergeLlmJson } from "@gea-ai/contract/llm-catalog";
 import { wrapLanguageModel } from "ai";
 import { z } from "zod";
+import { hostRejectionError } from "./host-rejection.js";
 import { addCacheControlToMessages, addCacheControlToToolList, } from "./cache-control.js";
 const HOST_PATH = "/internal/agent-worker-host/v1";
 const jsonObjectSchema = z.record(z.string(), z.json());
@@ -117,7 +118,7 @@ export async function createGeaAI(host, publicModel, extraBody, client, requestB
     const path = `/model?model=${encodeURIComponent(publicModel)}&includeModelId=true&includeMaxOutputTokens=true&includeCatalogConfig=true`;
     const response = await host.fetch(`${HOST_PATH}${path}`);
     if (!response.ok)
-        throw new Error(`Agent host rejected ${path} (${response.status}).`);
+        throw await hostRejectionError(path, response);
     const descriptor = modelDescriptorSchema.parse(await response.json());
     if ("transport" in descriptor) {
         return createHostedGeaLanguageModel({ client, host, publicModel });

package/dist/host-rejection.d.ts

@@ -0,0 +1,12 @@
+type HostRejectionDetail = {
+    code?: string;
+    reason?: string;
+};
+export declare class AgentHostRejectionError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly reason: string | undefined;
+    constructor(path: string, status: number, detail: HostRejectionDetail);
+}
+export declare function hostRejectionError(path: string, response: Response): Promise<AgentHostRejectionError>;
+export {};

package/dist/host-rejection.js

@@ -0,0 +1,78 @@
+import { Result } from "better-result";
+import { z } from "zod";
+const HOST_REJECTION_DETAIL_LIMIT = 500;
+const detailString = z.preprocess((value) => (typeof value === "string" ? value : undefined), z.string().optional());
+const hostErrorFieldsSchema = z.object({
+    code: detailString,
+    message: detailString,
+    reason: detailString,
+});
+const hostErrorBodySchema = hostErrorFieldsSchema.extend({
+    error: z.unknown().optional(),
+});
+function clipHostDetail(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length > HOST_REJECTION_DETAIL_LIMIT
+        ? trimmed.slice(0, HOST_REJECTION_DETAIL_LIMIT)
+        : trimmed;
+}
+function readFields(value) {
+    const parsed = hostErrorFieldsSchema.safeParse(value);
+    if (!parsed.success)
+        return {};
+    return {
+        code: clipHostDetail(parsed.data.code ?? ""),
+        reason: clipHostDetail(parsed.data.reason ?? "") ??
+            clipHostDetail(parsed.data.message ?? ""),
+    };
+}
+function detailFromText(body) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        return {};
+    const parsed = Result.try(() => JSON.parse(trimmed));
+    if (parsed.isErr()) {
+        const reason = clipHostDetail(trimmed);
+        return reason ? { reason } : {};
+    }
+    const bodyFields = hostErrorBodySchema.safeParse(parsed.value);
+    if (!bodyFields.success)
+        return {};
+    const nested = readFields(bodyFields.data.error);
+    const top = readFields(parsed.value);
+    return {
+        code: nested.code ?? top.code,
+        reason: nested.reason ?? top.reason,
+    };
+}
+async function readHostRejectionDetail(response) {
+    const body = await Result.tryPromise(() => response.text());
+    if (body.isErr())
+        return {};
+    return detailFromText(body.value);
+}
+function hostRejectionMessage(path, status, detail) {
+    const summary = detail.code && detail.reason
+        ? `${detail.code} - ${detail.reason}`
+        : (detail.code ?? detail.reason);
+    return summary
+        ? `Agent host rejected ${path} (${status}): ${summary}`
+        : `Agent host rejected ${path} (${status}).`;
+}
+export class AgentHostRejectionError extends Error {
+    status;
+    code;
+    reason;
+    constructor(path, status, detail) {
+        super(hostRejectionMessage(path, status, detail));
+        this.name = "AgentHostRejectionError";
+        this.status = status;
+        this.code = detail.code;
+        this.reason = detail.reason;
+    }
+}
+export async function hostRejectionError(path, response) {
+    return new AgentHostRejectionError(path, response.status, await readHostRejectionDetail(response));
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const agentSdkVersion = "0.1.261009-alpha.0";
+export declare const agentSdkVersion = "0.1.261010-alpha.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/build-sdk-version.mjs from package.json.
-export const agentSdkVersion = "0.1.261009-alpha.0";
+export const agentSdkVersion = "0.1.261010-alpha.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gea-ai/agent-sdk",
-  "version": "0.1.261009-alpha.0",
+  "version": "0.1.261010-alpha.0",
   "private": false,
   "homepage": "https://musegea.com/developers",
   "license": "Apache-2.0",
@@ -119,7 +119,7 @@
     "@ai-sdk/otel": "1.0.119",
     "@ai-sdk/provider": "4.0.19",
     "@ai-sdk/provider-utils": "5.0.50",
-    "@gea-ai/contract": "0.1.261009-alpha.0",
+    "@gea-ai/contract": "0.1.261010-alpha.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/context-async-hooks": "2.10.0",
     "@opentelemetry/core": "2.10.0",