@nexface/agent 0.1.1-alpha.6 → 0.1.1-alpha.8

package/dist/agent.js

@@ -1,8 +1,8 @@
-import { decodeRequest, toProtocolMessages, mergeProtocolMessages, runResponse } from "./request.js";
+import { decodeRequest, convertMessages, parseResume, approvalResponseSchema, toolResultResponseSchema, toProtocolMessages, mergeProtocolMessages, runResponse } from "./request.js";
 import { getInternalToolRuntime } from "@nexface/tools/internal";
 import { BROWSER_TOOLS_SKILL, serializeBrowserToolsSkill, } from "./browser-prompt.js";
 import { AgentError, isAgentError } from "./errors.js";
-import { EventType, TextInputContentSchema, ImageInputContentSchema, ResumeEntrySchema } from "@ag-ui/core";
+import { EventType, RunAgentInputSchema } from "@ag-ui/core";
 import { agentBrand } from "./types.js";
 import { describeModelConfig, prepareModelConfig, resolveModelBinding, } from "./model/binding.js";
 import { AgentModelError } from "./model/error.js";
@@ -612,9 +612,11 @@ class AgentRunStream {
                 this.#emit({
                     type: EventType.RUN_FINISHED, threadId, runId: id,
                     outcome: result.outcome,
-                    result: { ...(result.output === undefined ? {} : { output: result.output }), ...(result.checkpoint ? { checkpoint: result.checkpoint } : {}) },
+                    result: { ...(result.output === undefined ? {} : { output: result.output }) },
                 });
-                return result;
+                return result.outcome.type === "success"
+                    ? { outcome: result.outcome, output: result.output }
+                    : { outcome: result.outcome };
             }
             catch (error) {
                 await this.onResult?.(undefined, this.#controller.signal.aborted);
@@ -673,6 +675,8 @@ class Nexface {
     #requestPending;
     #requestResult;
     #requestUsed = false;
+    #hasRun = false;
+    #receiptQueue = [];
     #pendingModelConfig;
     #modelBinding;
     #modelInfo;
@@ -702,7 +706,7 @@ class Nexface {
         const hasToolRuntime = "toolRuntime" in options
             && options.toolRuntime !== undefined;
         if ("toolBridge" in options) {
-            throw new AgentError("AGENT_TOOL_RUNTIME_UNAVAILABLE", "toolBridge is no longer supported. Use toolRuntime locally or ChatClient with HTTP + SSE.");
+            throw new AgentError("AGENT_TOOL_RUNTIME_UNAVAILABLE", "toolBridge is no longer supported. Use toolRuntime locally or NexfaceProvider with HTTP + SSE.");
         }
         if (hasToolRuntime) {
             assertToolRuntime(options.toolRuntime);
@@ -745,7 +749,12 @@ class Nexface {
                     throw new Error("Conversation can only be restored into a new Agent.");
                 this.#messages.push(...structuredClone(messages));
             },
-            settle: (interruptId, settlement) => this.#settleInterrupt(interruptId, settlement),
+            settle: (interruptId, settlement, receipts) => {
+                const settled = this.#settleInterrupt(interruptId, settlement);
+                if (receipts)
+                    this.#alignCancellationReceipts(receipts);
+                return settled;
+            },
             authorizePageResponse: (response) => {
                 this.#authorizedPageResponses.add(response);
             },
@@ -783,114 +792,264 @@ class Nexface {
         }
     }
     run(input, options = {}) {
-        if ("messages" in input)
-            return this.#runRequest(input, options);
-        if (this.#activeRun) {
+        this.#assertAvailable();
+        let messages;
+        let resume;
+        try {
+            if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => key !== "messages" && key !== "resume"))
+                throw new Error("run accepts only messages and resume.");
+            if (input.messages !== undefined && !Array.isArray(input.messages))
+                throw new Error("messages must be an array.");
+            if (input.resume !== undefined && (!Array.isArray(input.resume) || input.resume.length !== 1))
+                throw new Error("Exactly one resume entry is required.");
+            resume = input.resume?.[0] ? parseResume(input.resume[0]) : undefined;
+            if (!input.messages?.length && !resume)
+                throw new Error("Provide messages or resume.");
+            const previous = mergeProtocolMessages(toProtocolMessages(this.#messages), this.#requestMessages);
+            const incomingIds = new Set(input.messages?.map((message) => message.id));
+            messages = convertMessages([...previous, ...input.messages ?? []]).filter((message) => incomingIds.has(message.id));
+            for (const message of messages)
+                if (message.role === "assistant")
+                    validateToolCallIds(message.toolCalls);
+            if (resume) {
+                if (!this.#pendingInterrupt || resume.interruptId !== this.#pendingInterrupt.descriptor.id)
+                    throw new Error("The interrupt is no longer pending.");
+                if (resume.status === "resolved") {
+                    if (!("approved" in resume.payload))
+                        throw new Error("This pending approval requires an approval response.");
+                    if (messages.length)
+                        throw new Error("A resolved approval cannot start a new task.");
+                    if (!resume.payload.approved && this.#pendingInterrupt.descriptor.mode === "page")
+                        throw new Error("A page confirmation cannot be rejected through run.");
+                    if (resume.payload.approved && this.#pendingInterrupt.descriptor.mode === "page" && !this.#authorizedPageResponses.delete(input.resume[0]))
+                        throw new Error("Page confirmation must be submitted through its registered usePageConfirmation Hook.");
+                }
+            }
+        }
+        catch (error) {
+            throw new AgentError("INVALID_RUN_INPUT", error instanceof Error ? error.message : "Invalid Agent input.");
+        }
+        return this.#start({ kind: "local", messages, protocolMessages: structuredClone(input.messages ?? []), ...(resume ? { resume } : {}) }, options);
+    }
+    runRequest(input, options = {}) {
+        let wire;
+        try {
+            wire = RunAgentInputSchema.parse(input);
+        }
+        catch (error) {
+            throw new AgentError("INVALID_RUN_INPUT", error instanceof Error ? error.message : "Invalid request shape.");
+        }
+        if (this.#hasRun || this.#activeRun || this.#modelSwitch || this.#messages.length || this.#toolRuntime)
+            throw new AgentError("AGENT_REQUEST_REQUIRES_NEW_AGENT", "runRequest requires a new Agent without a local ToolRuntime.");
+        return this.#start({ kind: "request", wire: structuredClone(wire) }, options);
+    }
+    #assertAvailable() {
+        if (this.#activeRun)
             throw new AgentError("AGENT_RUN_ACTIVE", "An agent run is already active.");
+        if (this.#modelSwitch)
+            throw new AgentModelError("AGENT_RUN_BLOCKED", "The model cannot be switched while the Agent is busy.");
+        if (this.#requestUsed)
+            throw new AgentError("AGENT_REQUEST_REQUIRES_NEW_AGENT", "A request Agent cannot be reused.");
+    }
+    #start(source, options) {
+        const runId = source.kind === "request" ? source.wire.runId : createId();
+        if (source.kind === "local" && !options.signal?.aborted) {
+            if (this.#toolRuntime && !source.resume) {
+                const previousOperation = this.#operation;
+                const abort = new AbortController();
+                const handle = getInternalToolRuntime(this.#toolRuntime).beginInternalOperation({
+                    signal: abort.signal,
+                    taskProgress: { phase: "processing" },
+                    onCancel: () => {
+                        abort.abort(new DOMException("Agent operation cancelled.", "AbortError"));
+                        if (this.#operation?.abort === abort && this.#pendingInterrupt)
+                            this.#settleInterrupt(this.#pendingInterrupt.descriptor.id, { type: "cancel" });
+                    },
+                    ...(previousOperation ? { replaceWaiting: previousOperation.handle } : {}),
+                });
+                this.#operation = { handle, abort };
+            }
+            if (!source.resume && this.#pendingInterrupt) {
+                const previous = this.#takeInterrupt(this.#pendingInterrupt.descriptor.id);
+                this.#appendInterruptedBatch(previous, errorPayload(new AgentToolError("TOOL_CANCELLED", "A new user message replaced the pending task.", { toolExecuted: false })));
+            }
+            else if (source.resume && this.#pendingInterrupt) {
+                // Transfer ownership before exposing the resumed Run to cancellation.
+                this.#pendingInterrupt.descriptor = Object.freeze({ ...this.#pendingInterrupt.descriptor, runId });
+            }
         }
-        if (this.#modelSwitch) {
-            throw new AgentModelError("AGENT_RUN_BLOCKED", "An agent run cannot start while the model is switching.");
+        if (source.kind === "request") {
+            this.#requestUsed = true;
+            this.#requestIdentity = { threadId: source.wire.threadId, runId };
         }
-        if ("resume" in input) {
-            if (!Array.isArray(input.resume) || input.resume.length !== 1) {
-                throw new AgentError("INVALID_RUN_INPUT", "Nexface currently requires exactly one resume entry.");
+        this.#hasRun = true;
+        const run = this.#createRun(runId, options, async (emit, signal) => {
+            signal.throwIfAborted();
+            let incoming;
+            let resume;
+            let restored;
+            let requestInput;
+            let history = [];
+            if (source.kind === "request") {
+                try {
+                    requestInput = decodeRequest(source.wire);
+                    history = this.#prepareRequestHistory(requestInput);
+                    restored = requestInput.continuation;
+                }
+                catch (error) {
+                    throw new AgentError("INVALID_RUN_INPUT", error instanceof Error ? error.message : "Invalid request recovery.");
+                }
+                incoming = requestInput.newMessages;
+                resume = requestInput.resume;
             }
-            const parsedEntry = ResumeEntrySchema.safeParse(input.resume[0]);
-            if (!parsedEntry.success) {
-                throw new AgentError("INVALID_RUN_INPUT", "The resume entry does not match the AG-UI interrupt response schema.");
+            else {
+                incoming = source.messages;
+                resume = source.resume;
             }
-            const entry = parsedEntry.data;
-            if (entry.status === "cancelled") {
-                throw new AgentError("INVALID_RUN_INPUT", "Cancelling a pending interrupt does not create an Agent Run.");
+            const binding = this.#modelBinding ?? await resolveModelBinding(this.#pendingModelConfig, signal);
+            signal.throwIfAborted();
+            if (restored?.replay !== undefined) {
+                if (!binding.restoreReplay)
+                    throw new AgentError("INVALID_RUN_INPUT", "The model cannot restore native replay data.");
+                binding.restoreReplay(restored.replay, history);
             }
-            if (typeof entry.payload?.approved !== "boolean") {
-                throw new AgentError("INVALID_RUN_INPUT", "Approval response requires a boolean approved field.");
+            // Commit only after recovery and native replay have both been validated.
+            this.#modelBinding = binding;
+            this.#modelInfo = binding.info;
+            this.#pendingModelConfig = undefined;
+            if (requestInput && source.kind === "request") {
+                this.#request = requestInput;
+                this.#requestMessages = source.wire.messages;
+                this.#receiptQueue = [...requestInput.receipts];
+                this.#messages.push(...history);
+                for (const skill of restored?.loadedSkills ?? [])
+                    this.#loadedSkills.add(skill);
+                this.#browserSkillLoaded = restored?.browserSkillLoaded ?? false;
+                this.#contextRevision = restored?.contextRevision ?? -1;
+                this.#lastContextSerialized = restored?.lastContextSerialized;
+                const pending = restored?.pending;
+                if (pending) {
+                    this.#requestPending = structuredClone(pending);
+                    this.#requestResult = requestInput.toolResult;
+                }
             }
-            const pending = this.#pendingInterrupt;
-            if (entry.payload.approved
-                && pending?.descriptor.id === entry.interruptId
-                && pending.descriptor.mode === "page"
-                && !this.#authorizedPageResponses.delete(input.resume[0])) {
-                throw new AgentError("INVALID_RUN_INPUT", "Page confirmation must be submitted through its registered usePageConfirmation Hook.");
+            const rememberLocalInput = () => {
+                if (source.kind === "local")
+                    this.#requestMessages = [...mergeProtocolMessages(toProtocolMessages(this.#messages), this.#requestMessages), ...source.protocolMessages];
+            };
+            if (resume?.status === "cancelled") {
+                if (this.#pendingInterrupt) {
+                    const pending = this.#takeInterrupt(resume.interruptId);
+                    this.#appendInterruptedBatch(pending, errorPayload(new AgentToolError("TOOL_CANCELLED", "The pending task was cancelled.", { toolExecuted: false })), emit);
+                }
+                else if (this.#requestPending) {
+                    this.#cancelRequestPending(emit);
+                }
+                if (!incoming.length) {
+                    rememberLocalInput();
+                    return { outcome: { type: "success" }, output: "" };
+                }
             }
-            const continuation = this.#resolveInterrupt(entry.interruptId, entry.payload.approved ? "confirm" : "reject", options);
-            if (!continuation) {
-                throw new AgentError("INVALID_RUN_INPUT", "The interrupt is no longer pending or cannot accept this response.");
+            else if (resume?.status === "resolved" && "approved" in resume.payload) {
+                rememberLocalInput();
+                return this.#continueApproval(resume.interruptId, resume.payload.approved ? "confirm" : "reject", emit, signal, runId);
             }
-            return continuation;
-        }
-        const raw = input.message.content;
-        const content = typeof raw === "string" ? raw.trim() : raw.map((part) => part.type === "text" ? TextInputContentSchema.parse(part) : ImageInputContentSchema.parse(part));
-        if (!content.length) {
-            throw new AgentError("INVALID_RUN_INPUT", "Agent message content is required.");
-        }
-        if (options.signal?.aborted) {
-            return new AgentRunStream(createId(), this.id, options, async (_emit, signal) => {
-                signal.throwIfAborted();
-                throw new Error("An aborted Run cannot execute.");
-            });
-        }
-        if (this.#toolRuntime) {
-            const abort = new AbortController();
-            const handle = getInternalToolRuntime(this.#toolRuntime).beginInternalOperation({
-                signal: abort.signal,
-                taskProgress: { phase: "processing" },
-                onCancel: () => {
-                    abort.abort(new DOMException("Agent operation cancelled.", "AbortError"));
-                    if (this.#operation?.abort === abort && this.#pendingInterrupt) {
-                        this.#settleInterrupt(this.#pendingInterrupt.descriptor.id, { type: "cancel" });
-                    }
-                },
-                ...(this.#pendingInterrupt && this.#operation ? { replaceWaiting: this.#operation.handle } : {}),
-            });
-            // The old handle has been replaced atomically; invalidation cannot close the new one.
-            this.#operation = undefined;
-            if (this.#pendingInterrupt)
-                this.#invalidateInterrupt("A new user message started.", "new_message");
-            this.#operation = { handle, abort };
-        }
-        else if (this.#pendingInterrupt) {
-            this.#invalidateInterrupt("A new user message started.", "new_message");
-        }
-        const inputMessage = { id: input.message.id ?? createId(), role: "user", content };
-        const runId = createId();
-        const pendingModelConfig = this.#pendingModelConfig;
-        const existingBinding = this.#modelBinding;
-        const run = this.#createRun(runId, options, async (emit, signal) => {
+            rememberLocalInput();
+            const contexts = validateBridgeContexts(await this.#toolBridge.getContexts({ signal }));
+            this.#appendContextCheckpoint(contexts);
+            const definitions = validateBridgeTools(await this.#toolBridge.getTools({ signal }));
+            appendRuntimeCatalogCheckpoint(this.#messages, definitions.filter(({ name }) => !NATIVE_TOOL_NAMES.has(name)));
+            const previousLength = this.#messages.length;
+            this.#messages.push(...structuredClone(incoming));
             try {
-                const binding = existingBinding ?? await resolveModelBinding(pendingModelConfig, signal);
-                signal.throwIfAborted();
-                if (!this.#modelBinding && this.#pendingModelConfig === pendingModelConfig) {
-                    this.#modelBinding = binding;
-                    this.#modelInfo = binding.info;
-                    this.#pendingModelConfig = undefined;
-                }
-                const contexts = validateBridgeContexts(await this.#toolBridge.getContexts({ signal }));
-                this.#appendContextCheckpoint(contexts);
-                const definitions = validateBridgeTools(await this.#toolBridge.getTools({ signal }));
-                const applicationDefinitions = definitions
-                    .filter(({ name }) => !NATIVE_TOOL_NAMES.has(name));
-                appendRuntimeCatalogCheckpoint(this.#messages, applicationDefinitions);
-                this.#messages.push(inputMessage);
-                return await this.#execute(emit, signal, binding, definitions, runId);
+                const pending = this.#requestPending;
+                return await this.#execute(emit, signal, binding, definitions, runId, pending ? { step: pending.step, recoverableFailures: pending.recoverableFailures, unresolvedToolFailures: new Set(pending.unresolvedToolFailures) } : undefined);
             }
             catch (error) {
-                // Preserve history after a Tool may have caused application side effects.
-                if (this.#messages.at(-1) === inputMessage)
-                    this.#messages.pop();
+                // Roll back untouched input, but keep history after a tool may have executed.
+                if (this.#messages.length === previousLength + incoming.length)
+                    this.#messages.splice(previousLength);
                 throw error;
             }
         });
         this.#activeRun = run;
-        void run.result.then(() => {
-            if (this.#activeRun === run)
-                this.#activeRun = undefined;
-        }, () => {
-            if (this.#activeRun === run)
-                this.#activeRun = undefined;
-        });
+        if (source.kind === "local" && source.resume)
+            this.#operation?.handle.setWaitingForUser(false);
+        void run.result.then(() => { if (this.#activeRun === run)
+            this.#activeRun = undefined; }, () => { if (this.#activeRun === run)
+            this.#activeRun = undefined; });
         return run;
     }
+    #prepareRequestHistory(input) {
+        validateBridgeTools(input.tools);
+        validateBridgeContexts(input.contexts);
+        const definitions = [...input.tools, ...[...this.#registered.values()].map((tool) => tool.definition)];
+        validateBridgeTools(definitions);
+        const restored = input.continuation;
+        if (restored && (JSON.stringify(restored.model) !== JSON.stringify(this.model) || !Array.isArray(restored.loadedSkills) || !Number.isInteger(restored.contextRevision) || typeof restored.browserSkillLoaded !== "boolean"))
+            throw new Error("Invalid Agent state.");
+        for (const name of restored?.loadedSkills ?? [])
+            if (!this.#skillsByName.has(name))
+                throw new Error("A restored Skill is unavailable.");
+        const catalog = serializeRuntimeCatalog(definitions.filter(({ name }) => !NATIVE_TOOL_NAMES.has(name)));
+        const history = input.messages.map((message) => {
+            if (message.role !== "system") {
+                if (message.role === "assistant")
+                    validateToolCallIds(message.toolCalls);
+                return structuredClone(message);
+            }
+            const skill = message.content.startsWith("nexface:skill:") ? this.#skillsByName.get(message.content.slice(14)) : undefined;
+            const content = skill ? serializeSkill(skill) : message.content === "nexface:browser" ? serializeBrowserToolsSkill() : message.content === "nexface:catalog" ? catalog : undefined;
+            if (!content)
+                throw new Error("Untrusted system message.");
+            return { role: "system", content };
+        });
+        for (const message of input.newMessages)
+            if (message.role === "assistant")
+                validateToolCallIds(message.toolCalls);
+        const pending = restored?.pending;
+        if (pending) {
+            if (!Number.isInteger(pending.step) || pending.step < 0 || !Number.isInteger(pending.recoverableFailures) || pending.recoverableFailures < 0 || !Array.isArray(pending.unresolvedToolFailures) || pending.unresolvedToolFailures.some((name) => typeof name !== "string") || typeof pending.browserSkillAvailable !== "boolean" || typeof pending.loadBrowserSkill !== "boolean")
+                throw new Error("Invalid pending budget.");
+            validateToolCallIds(pending.calls);
+            const batchIndex = history.reduce((last, message, index) => message.role === "assistant" ? index : last, -1);
+            const batch = history[batchIndex];
+            if (batch?.role !== "assistant")
+                throw new Error("Pending call has no assistant message.");
+            const firstIndex = batch.toolCalls.findIndex((call) => call.id === pending.calls[0].id);
+            if (firstIndex < 0 || JSON.stringify(batch.toolCalls.slice(firstIndex)) !== JSON.stringify(pending.calls))
+                throw new Error("Pending calls do not match their original batch.");
+            if (history.slice(batchIndex + 1).some((message) => message.role === "tool" && pending.calls.some((call) => call.id === message.toolCallId)))
+                throw new Error("Pending call already has a result.");
+            const first = pending.calls[0];
+            const prepared = prepareToolCall(first, new Set(NATIVE_TOOL_NAMES), this.#skills.length > 0);
+            if (prepared.preparationError)
+                throw prepared.preparationError;
+            // Client receipts settle the original call even if its Binding has since changed.
+            const definition = validateBridgeTools([pending.definition])[0];
+            if (!definition || definition.name !== prepared.displayName)
+                throw new Error("Pending tool definition changed.");
+            const pendingInput = prepared.kind === "application" ? prepared.input : Object.fromEntries(Object.entries(parseArguments(first)).filter(([key]) => key !== "progressLabel"));
+            const inputErrors = validateToolInput(definition.inputSchema, pendingInput);
+            if (inputErrors.length)
+                throw new Error(`Invalid pending tool input: ${inputErrors.join(" ")}`);
+            if (this.#registered.has(prepared.displayName))
+                throw new Error("A client result cannot settle a registered tool.");
+        }
+        return history;
+    }
+    #cancelRequestPending(emit) {
+        const pending = this.#requestPending;
+        this.#requestPending = undefined;
+        this.#requestResult = undefined;
+        for (const [index, call] of pending.calls.entries()) {
+            const prepared = prepareToolCall(call, new Set(NATIVE_TOOL_NAMES), this.#skills.length > 0);
+            const payload = errorPayload(new AgentToolError(index === 0 ? "TOOL_CANCELLED" : "TOOL_SKIPPED", "The pending task was cancelled.", { toolExecuted: false }));
+            this.#messages.push({ role: "tool", toolCallId: call.id, name: call.name, content: modelToolPayload(prepared, payload) });
+            emit({ type: EventType.TOOL_CALL_RESULT, messageId: createId(), role: "tool", toolCallId: call.id, content: serializeToolPayload(payload) });
+        }
+        this.#loadPendingBrowserSkill(pending);
+    }
     async #executeRegistered(tool, input, toolCallId, progressLabel, emit, signal) {
         const progress = { phase: "tool", toolCallId, ...(progressLabel ? { progressLabel } : {}) };
         const runtime = this.#toolRuntime && getInternalToolRuntime(this.#toolRuntime);
@@ -906,7 +1065,7 @@ class Nexface {
             emit({ type: EventType.CUSTOM, name: "nexface.tool-execution", value: { toolCallId, status: "finished" } });
         }
     }
-    #checkpoint(binding) {
+    #exportState(binding) {
         toProtocolMessages(this.#messages);
         const messages = this.#messages.map((message) => {
             if (message.role !== "system")
@@ -920,113 +1079,12 @@ class Nexface {
             return { role: "system", content: "nexface:catalog" };
         });
         const continuation = {
-            version: 1, timeline: messages.map((message) => message.role === "system" || message.role === "application_context" ? { internal: message } : { messageId: message.id }), model: this.model, loadedSkills: [...this.#loadedSkills], browserSkillLoaded: this.#browserSkillLoaded,
+            version: 2, threadId: this.#requestIdentity.threadId, timeline: messages.map((message) => message.role === "system" || message.role === "application_context" ? { internal: message } : { messageId: message.id }), model: this.model, loadedSkills: [...this.#loadedSkills], browserSkillLoaded: this.#browserSkillLoaded,
             contextRevision: this.#contextRevision, ...(this.#lastContextSerialized === undefined ? {} : { lastContextSerialized: this.#lastContextSerialized }),
             ...(binding.exportReplay ? { replay: binding.exportReplay(this.#messages) } : {}),
             ...(this.#requestPending ? { pending: this.#requestPending } : {}),
         };
-        return { continuation: JSON.stringify(continuation) };
-    }
-    #runRequest(wire, options) {
-        let input;
-        try {
-            input = decodeRequest(wire);
-        }
-        catch (error) {
-            throw new AgentError("INVALID_RUN_INPUT", error instanceof Error ? error.message : "Invalid request.");
-        }
-        this.#requestIdentity = { threadId: wire.threadId, runId: wire.runId };
-        this.#requestMessages = wire.messages;
-        if (this.#requestUsed || this.#activeRun || this.#messages.length || this.#toolRuntime)
-            throw new AgentError("INVALID_RUN_INPUT", "Request input requires a new server Agent.");
-        if (!Array.isArray(input.messages) || !Array.isArray(input.tools) || !Array.isArray(input.contexts))
-            throw new AgentError("INVALID_RUN_INPUT", "Invalid request input.");
-        validateBridgeTools(input.tools);
-        validateBridgeContexts(input.contexts);
-        this.#requestUsed = true;
-        this.#request = structuredClone(input);
-        let continuation;
-        try {
-            continuation = input.continuation ? JSON.parse(input.continuation) : undefined;
-            if (continuation && (continuation.version !== 1 || JSON.stringify(continuation.model) !== JSON.stringify(this.model) || !Array.isArray(continuation.loadedSkills) || !Number.isInteger(continuation.contextRevision)))
-                throw new Error("Invalid continuation.");
-            if (continuation?.pending) {
-                const pending = continuation.pending;
-                if (!Array.isArray(pending.calls) || !pending.calls.length || !Number.isInteger(pending.step) || pending.step < 0 || !Number.isInteger(pending.recoverableFailures) || pending.recoverableFailures < 0 || !Array.isArray(pending.unresolvedToolFailures))
-                    throw new Error("Invalid pending batch.");
-                validateToolCallIds(pending.calls);
-                if (input.toolResult?.toolCallId !== pending.calls[0]?.id)
-                    throw new Error("Missing or mismatched browser result.");
-                const batchIndex = input.messages.reduce((last, message, index) => message.role === "assistant" ? index : last, -1);
-                const batch = input.messages[batchIndex];
-                const outstanding = batch?.role === "assistant" ? batch.toolCalls : [];
-                for (const call of pending.calls) {
-                    if (!outstanding.some((item) => item.id === call.id && item.name === call.name && item.arguments === call.arguments) || input.messages.slice(batchIndex + 1).some((message) => message.role === "tool" && message.toolCallId === call.id))
-                        throw new Error("Pending call does not match history.");
-                }
-                const first = pending.calls[0];
-                const target = first.name === "callAppTool" ? JSON.parse(first.arguments).name : first.name;
-                if (target && this.#registered.has(target))
-                    throw new Error("A browser result cannot settle a server tool.");
-                if (typeof input.toolResult?.confirmed !== "undefined" && typeof input.toolResult.confirmed !== "boolean")
-                    throw new Error("Invalid confirmation result.");
-                if (input.toolResult?.error && (typeof input.toolResult.error.code !== "string" || typeof input.toolResult.error.message !== "string"))
-                    throw new Error("Invalid browser error.");
-                this.#requestPending = structuredClone(pending);
-                this.#requestResult = structuredClone(input.toolResult);
-            }
-            else if (input.toolResult)
-                throw new Error("Unexpected browser result.");
-            for (const name of continuation?.loadedSkills ?? []) {
-                if (!this.#skillsByName.has(name))
-                    throw new Error("A restored Skill is unavailable.");
-                this.#loadedSkills.add(name);
-            }
-            this.#browserSkillLoaded = continuation?.browserSkillLoaded ?? false;
-            this.#contextRevision = continuation?.contextRevision ?? -1;
-            this.#lastContextSerialized = continuation?.lastContextSerialized;
-            const catalog = serializeRuntimeCatalog([...input.tools, ...[...this.#registered.values()].map((tool) => tool.definition)].filter((tool) => !NATIVE_TOOL_NAMES.has(tool.name)));
-            for (const message of input.messages) {
-                if (!message || !["system", "user", "assistant", "tool", "application_context"].includes(message.role))
-                    throw new Error("Invalid history message.");
-                if (message.role === "system") {
-                    const skill = message.content.startsWith("nexface:skill:") ? this.#skillsByName.get(message.content.slice(14)) : undefined;
-                    const content = skill ? serializeSkill(skill) : message.content === "nexface:browser" ? serializeBrowserToolsSkill() : message.content === "nexface:catalog" ? catalog : undefined;
-                    if (!content)
-                        throw new Error("Untrusted system message.");
-                    this.#messages.push({ role: "system", content });
-                }
-                else {
-                    if (message.role === "assistant")
-                        validateToolCallIds(message.toolCalls);
-                    if (message.role === "user" && typeof message.content !== "string") {
-                        if (!Array.isArray(message.content))
-                            throw new Error("Invalid user content.");
-                        message.content.forEach((part) => part.type === "text" ? TextInputContentSchema.parse(part) : ImageInputContentSchema.parse(part));
-                    }
-                    else if (message.role !== "assistant" && typeof message.content !== "string")
-                        throw new Error("Invalid history content.");
-                    this.#messages.push(structuredClone(message));
-                }
-            }
-        }
-        catch (error) {
-            throw new AgentError("INVALID_RUN_INPUT", error instanceof Error ? error.message : "Invalid request.");
-        }
-        const run = this.#createRun(wire.runId, options, async (emit, signal) => {
-            const binding = await resolveModelBinding(this.#pendingModelConfig, signal);
-            this.#modelBinding = binding;
-            if (continuation?.replay !== undefined)
-                binding.restoreReplay?.(continuation.replay, this.#messages);
-            this.#appendContextCheckpoint(validateBridgeContexts(input.contexts));
-            const definitions = validateBridgeTools(await this.#toolBridge.getTools({ signal }));
-            const pending = this.#requestPending;
-            const result = await this.#execute(emit, signal, binding, definitions, run.id, pending ? { step: pending.step, recoverableFailures: pending.recoverableFailures, unresolvedToolFailures: new Set(pending.unresolvedToolFailures) } : undefined);
-            return result.outcome.type === "success" ? { ...result, checkpoint: this.#checkpoint(binding) } : result;
-        });
-        this.#activeRun = run;
-        void run.result.then(() => { this.#activeRun = undefined; }, () => { this.#activeRun = undefined; });
-        return run;
+        return structuredClone({ nexface: continuation });
     }
     #createRun(id, options, execute) {
         const operation = this.#operation;
@@ -1034,7 +1092,6 @@ class Nexface {
             ...options,
             signal: AbortSignal.any([operation.abort.signal, ...(options.signal ? [options.signal] : [])]),
         } : options;
-        let resumedResultId = this.#request?.toolResultMessageId;
         return new AgentRunStream(id, this.#requestIdentity?.threadId ?? this.id, runOptions, async (emit, signal) => {
             const onAbort = () => operation?.abort.abort(signal.reason);
             if (signal.aborted)
@@ -1044,18 +1101,26 @@ class Nexface {
             try {
                 const result = await execute((event) => {
                     if (event.type === EventType.TOOL_CALL_RESULT) {
-                        const previous = this.#requestMessages.find((item) => item.id === resumedResultId && item.role === "tool" && item.toolCallId === event.toolCallId);
-                        if (previous) {
-                            event = { ...event, messageId: previous.id };
-                            resumedResultId = undefined;
-                        }
+                        const receiptIndex = this.#receiptQueue.findIndex((item) => item.role === "tool" && item.toolCallId === event.toolCallId);
+                        const previous = receiptIndex < 0 ? undefined : this.#receiptQueue.splice(receiptIndex, 1)[0];
+                        if (previous?.role === "tool")
+                            event = { ...event, messageId: previous.id, ...(this.#request?.resume?.status === "cancelled" ? { content: previous.content } : {}) };
                         const message = this.#messages.at(-1);
-                        if (message?.role === "tool" && message.toolCallId === event.toolCallId)
+                        if (message?.role === "tool" && message.toolCallId === event.toolCallId) {
                             message.id = event.messageId;
+                            if (previous?.role === "tool" && this.#request?.resume?.status === "cancelled") {
+                                const original = JSON.parse(message.content);
+                                message.content = JSON.stringify({ ...(original.toolName ? { toolName: original.toolName } : {}), ...JSON.parse(previous.content) });
+                            }
+                        }
                     }
                     emit(event);
                 }, signal);
-                emit({ type: EventType.MESSAGES_SNAPSHOT, messages: mergeProtocolMessages(toProtocolMessages(this.#messages), this.#requestMessages) });
+                const messages = mergeProtocolMessages(toProtocolMessages(this.#messages), this.#requestMessages);
+                this.#requestMessages = structuredClone(messages);
+                emit({ type: EventType.MESSAGES_SNAPSHOT, messages });
+                if (this.#requestIdentity)
+                    emit({ type: EventType.STATE_SNAPSHOT, snapshot: this.#exportState(this.#modelBinding) });
                 return result;
             }
             finally {
@@ -1363,8 +1428,8 @@ class Nexface {
                             throw new AgentToolError("INVALID_INPUT", inputErrors.join(" "), { errors: inputErrors });
                         }
                         if (this.#request && !registered) {
-                            this.#requestPending = { interruptId: createId(), calls: preparedCalls.slice(index).map((item) => item.call), step, recoverableFailures, unresolvedToolFailures: [...unresolvedToolFailures], browserSkillAvailable: browserSkillAvailableForRequest, loadBrowserSkill: shouldLoadBrowserSkill };
-                            return { outcome: { type: "interrupt", interrupts: [{ id: this.#requestPending.interruptId, reason: "tool_call", toolCallId: prepared.call.id, metadata: { nexface: { kind: "client-tool-execution", action: { toolCallId: prepared.call.id, definition: expectedDefinition, input: toolInput, ...(prepared.progressLabel ? { progressLabel: prepared.progressLabel } : {}) } } } }] }, checkpoint: this.#checkpoint(binding) };
+                            this.#requestPending = { kind: "client-tool-execution", definition: expectedDefinition, interruptId: createId(), calls: preparedCalls.slice(index).map((item) => item.call), step, recoverableFailures, unresolvedToolFailures: [...unresolvedToolFailures], browserSkillAvailable: browserSkillAvailableForRequest, loadBrowserSkill: shouldLoadBrowserSkill };
+                            return { outcome: { type: "interrupt", interrupts: [{ id: this.#requestPending.interruptId, reason: "tool_call", toolCallId: prepared.call.id, responseSchema: toolResultResponseSchema, metadata: { nexface: { kind: "client-tool-execution", action: { toolCallId: prepared.call.id, definition: expectedDefinition, input: toolInput, ...(prepared.progressLabel ? { progressLabel: prepared.progressLabel } : {}) } } } }] } };
                         }
                         const confirmation = runtimeTool?.confirmation;
                         if (runtimeTool && confirmation) {
@@ -1403,6 +1468,7 @@ class Nexface {
                                 remaining: preparedCalls.slice(index + 1),
                                 modelBinding: binding,
                                 nextStep: step + 1,
+                                loadBrowserSkill: shouldLoadBrowserSkill,
                                 recoverableFailures,
                                 unresolvedToolFailures: new Set(unresolvedToolFailures),
                                 removeInvalidationListener: () => { },
@@ -1415,7 +1481,7 @@ class Nexface {
                             runtimeTool.lifecycleSignal.addEventListener("abort", onRuntimeToolDisposed, { once: true });
                             pending.removeInvalidationListener = () => runtimeTool.lifecycleSignal.removeEventListener("abort", onRuntimeToolDisposed);
                             this.#pendingInterrupt = pending;
-                            return { outcome: { type: "interrupt", interrupts: [{ id: descriptor.id, reason: "tool_call", toolCallId: descriptor.toolCallId, metadata: { nexface: { kind: "tool-approval", approval: descriptor } } }] } };
+                            return { outcome: { type: "interrupt", interrupts: [{ id: descriptor.id, reason: "tool_call", toolCallId: descriptor.toolCallId, responseSchema: approvalResponseSchema, metadata: { nexface: { kind: "tool-approval", source: "runtime", approval: descriptor } } }] } };
                         }
                         output = registered ? await this.#executeRegistered(registered, toolInput, prepared.call.id, prepared.progressLabel, emit, signal) : runtimeTool && this.#toolRuntime
                             ? await getInternalToolRuntime(this.#toolRuntime).executeWithProgress(runtimeTool, toolInput, { signal, ...(prepared.progressLabel ? { progressLabel: prepared.progressLabel } : {}) })
@@ -1441,8 +1507,8 @@ class Nexface {
                             const inputErrors = validateToolInput(expectedDefinition.inputSchema, toolInput);
                             if (inputErrors.length)
                                 throw new AgentToolError("INVALID_INPUT", inputErrors.join(" "));
-                            this.#requestPending = { interruptId: createId(), calls: preparedCalls.slice(index).map((item) => item.call), step, recoverableFailures, unresolvedToolFailures: [...unresolvedToolFailures], browserSkillAvailable: browserSkillAvailableForRequest, loadBrowserSkill: shouldLoadBrowserSkill };
-                            return { outcome: { type: "interrupt", interrupts: [{ id: this.#requestPending.interruptId, reason: "tool_call", toolCallId: prepared.call.id, metadata: { nexface: { kind: "client-tool-execution", action: { toolCallId: prepared.call.id, definition: expectedDefinition, input: toolInput, ...(progressLabel ? { progressLabel } : {}) } } } }] }, checkpoint: this.#checkpoint(binding) };
+                            this.#requestPending = { kind: "client-tool-execution", definition: expectedDefinition, interruptId: createId(), calls: preparedCalls.slice(index).map((item) => item.call), step, recoverableFailures, unresolvedToolFailures: [...unresolvedToolFailures], browserSkillAvailable: browserSkillAvailableForRequest, loadBrowserSkill: shouldLoadBrowserSkill };
+                            return { outcome: { type: "interrupt", interrupts: [{ id: this.#requestPending.interruptId, reason: "tool_call", toolCallId: prepared.call.id, responseSchema: toolResultResponseSchema, metadata: { nexface: { kind: "client-tool-execution", action: { toolCallId: prepared.call.id, definition: expectedDefinition, input: toolInput, ...(progressLabel ? { progressLabel } : {}) } } } }] } };
                         }
                         const nativeRuntimeTool = this.#toolRuntime?.getTools().find((tool) => tool.definition === expectedDefinition);
                         output = nativeRuntimeTool && this.#toolRuntime
@@ -1591,6 +1657,37 @@ class Nexface {
                 });
             }
         }
+        this.#loadPendingBrowserSkill(pending);
+    }
+    #loadPendingBrowserSkill(pending) {
+        if (pending.loadBrowserSkill && !this.#browserSkillLoaded) {
+            this.#messages.push({ role: "system", content: serializeBrowserToolsSkill() });
+            this.#browserSkillLoaded = true;
+        }
+    }
+    #alignCancellationReceipts(protocol) {
+        const ownerIndex = protocol.reduce((last, message, index) => message.role === "assistant" && message.toolCalls?.length ? index : last, -1);
+        const owner = protocol[ownerIndex];
+        if (!owner)
+            return;
+        const historyIndex = this.#messages.findIndex((message) => message.id === owner.id && message.role === "assistant");
+        if (historyIndex < 0)
+            return;
+        const codes = new Set(["TOOL_CANCELLED", "TOOL_CONFIRMATION_INVALIDATED", "TOOL_SKIPPED"]);
+        for (const receipt of protocol.slice(ownerIndex + 1)) {
+            if (receipt.role === "user" || (receipt.role === "assistant" && receipt.toolCalls?.length))
+                break;
+            if (receipt.role !== "tool")
+                continue;
+            const current = this.#messages.slice(historyIndex + 1).find((message) => message.role === "tool" && message.toolCallId === receipt.toolCallId);
+            if (current?.role !== "tool")
+                continue;
+            try {
+                if (codes.has(JSON.parse(current.content)?.error?.code) && codes.has(JSON.parse(receipt.content)?.error?.code))
+                    current.id = receipt.id;
+            }
+            catch { /* Only known cancellation receipts are aligned. */ }
+        }
     }
     #invalidateInterrupt(message, reason) {
         const pending = this.#pendingInterrupt;
@@ -1615,103 +1712,85 @@ class Nexface {
         this.#appendInterruptedBatch(pending, errorPayload(new AgentToolError("TOOL_CONFIRMATION_INVALIDATED", settlement.message, { reason: settlement.reason, toolExecuted: false })));
         return true;
     }
-    #resolveInterrupt(id, decision, options = {}) {
-        const current = this.#pendingInterrupt;
-        if (!current || current.descriptor.id !== id)
-            return undefined;
-        if (decision === "reject" && current.descriptor.mode !== "chat") {
-            return undefined;
-        }
-        options.signal?.throwIfAborted();
+    async #continueApproval(id, decision, emit, signal, runId) {
         const pending = this.#takeInterrupt(id);
         if (!pending)
-            return undefined;
+            throw new AgentError("INVALID_RUN_INPUT", "The interrupt is no longer pending.");
         this.#operation?.handle.setWaitingForUser(false);
-        const runId = createId();
-        const run = this.#createRun(runId, options, async (emit, signal) => {
-            let currentFailed = decision === "reject";
-            if (decision === "reject") {
-                this.#appendInterruptedBatch(pending, errorPayload(new AgentToolError("TOOL_CONFIRMATION_REJECTED", `Tool "${pending.descriptor.toolName}" was rejected by the user.`, { toolExecuted: false })), emit);
+        let currentFailed = decision === "reject";
+        if (decision === "reject") {
+            this.#appendInterruptedBatch(pending, errorPayload(new AgentToolError("TOOL_CONFIRMATION_REJECTED", `Tool "${pending.descriptor.toolName}" was rejected by the user.`, { toolExecuted: false })), emit);
+        }
+        else {
+            let payload;
+            try {
+                const output = await getInternalToolRuntime(this.#toolRuntime).executeWithProgress(pending.runtimeTool, pending.input, { signal, ...(pending.prepared.progressLabel ? { progressLabel: pending.prepared.progressLabel } : {}) });
+                payload = { result: output ?? null };
             }
-            else {
-                let payload;
-                try {
-                    if (!this.#toolRuntime) {
-                        throw new AgentToolError("TOOL_CONFIRMATION_INVALIDATED", `Tool "${pending.descriptor.toolName}" no longer has a local Runtime.`, { toolExecuted: false });
-                    }
-                    const output = await getInternalToolRuntime(this.#toolRuntime).executeWithProgress(pending.runtimeTool, pending.input, { signal, ...(pending.prepared.progressLabel ? { progressLabel: pending.prepared.progressLabel } : {}) });
-                    payload = { result: output ?? null };
-                }
-                catch (error) {
-                    currentFailed = true;
-                    const normalized = signal.aborted
-                        ? new AgentToolError("TOOL_CANCELLED", `Tool "${pending.descriptor.toolName}" was cancelled with the Agent run.`)
-                        : error;
-                    payload = errorPayload(normalized);
-                }
-                const eventContent = serializeToolPayload(payload);
+            catch (error) {
+                currentFailed = true;
+                const normalized = signal.aborted
+                    ? new AgentToolError("TOOL_CANCELLED", `Tool "${pending.descriptor.toolName}" was cancelled with the Agent run.`)
+                    : error;
+                payload = errorPayload(normalized);
+            }
+            const eventContent = serializeToolPayload(payload);
+            this.#messages.push({
+                role: "tool",
+                toolCallId: pending.prepared.call.id,
+                name: pending.prepared.call.name,
+                content: modelToolPayload(pending.prepared, payload),
+            });
+            emit({
+                type: EventType.TOOL_CALL_RESULT,
+                messageId: createId(),
+                role: "tool",
+                toolCallId: pending.prepared.call.id,
+                content: eventContent,
+            });
+            for (const prepared of pending.remaining) {
+                const skipped = new AgentToolError("TOOL_SKIPPED", "Skipped because an earlier tool call required confirmation.", { failedToolCallId: pending.prepared.call.id });
+                const skippedPayload = errorPayload(skipped);
                 this.#messages.push({
                     role: "tool",
-                    toolCallId: pending.prepared.call.id,
-                    name: pending.prepared.call.name,
-                    content: modelToolPayload(pending.prepared, payload),
+                    toolCallId: prepared.call.id,
+                    name: prepared.call.name,
+                    content: modelToolPayload(prepared, skippedPayload),
                 });
                 emit({
                     type: EventType.TOOL_CALL_RESULT,
                     messageId: createId(),
                     role: "tool",
-                    toolCallId: pending.prepared.call.id,
-                    content: eventContent,
+                    toolCallId: prepared.call.id,
+                    content: serializeToolPayload(skippedPayload),
                 });
-                for (const prepared of pending.remaining) {
-                    const skipped = new AgentToolError("TOOL_SKIPPED", "Skipped because an earlier tool call required confirmation.", { failedToolCallId: pending.prepared.call.id });
-                    const skippedPayload = errorPayload(skipped);
-                    this.#messages.push({
-                        role: "tool",
-                        toolCallId: prepared.call.id,
-                        name: prepared.call.name,
-                        content: modelToolPayload(prepared, skippedPayload),
-                    });
-                    emit({
-                        type: EventType.TOOL_CALL_RESULT,
-                        messageId: createId(),
-                        role: "tool",
-                        toolCallId: prepared.call.id,
-                        content: serializeToolPayload(skippedPayload),
-                    });
-                }
-            }
-            signal.throwIfAborted();
-            const unresolved = new Set(pending.unresolvedToolFailures);
-            if (currentFailed)
-                unresolved.add(pending.prepared.displayName);
-            else
-                unresolved.delete(pending.prepared.displayName);
-            for (const prepared of pending.remaining) {
-                unresolved.add(prepared.displayName);
             }
-            const contexts = validateBridgeContexts(await this.#toolBridge.getContexts({ signal }));
-            this.#appendContextCheckpoint(contexts);
-            const nextRecoverableFailures = pending.recoverableFailures
-                + (currentFailed ? 1 : 0);
-            if (decision === "confirm"
-                && currentFailed
-                && nextRecoverableFailures > this.#maxRetries) {
-                throw new AgentError("AGENT_RUN_LIMIT_REACHED", "Agent recovery attempt limit reached.");
-            }
-            const definitions = validateBridgeTools(await this.#toolBridge.getTools({ signal }));
-            return this.#execute(emit, signal, pending.modelBinding, definitions, runId, {
-                step: pending.nextStep,
-                recoverableFailures: nextRecoverableFailures,
-                unresolvedToolFailures: unresolved,
-            });
+        }
+        signal.throwIfAborted();
+        this.#loadPendingBrowserSkill(pending);
+        const unresolved = new Set(pending.unresolvedToolFailures);
+        if (currentFailed)
+            unresolved.add(pending.prepared.displayName);
+        else
+            unresolved.delete(pending.prepared.displayName);
+        for (const prepared of pending.remaining) {
+            unresolved.add(prepared.displayName);
+        }
+        const contexts = validateBridgeContexts(await this.#toolBridge.getContexts({ signal }));
+        this.#appendContextCheckpoint(contexts);
+        const nextRecoverableFailures = pending.recoverableFailures
+            + (currentFailed ? 1 : 0);
+        if (decision === "confirm"
+            && currentFailed
+            && nextRecoverableFailures > this.#maxRetries) {
+            throw new AgentError("AGENT_RUN_LIMIT_REACHED", "Agent recovery attempt limit reached.");
+        }
+        const definitions = validateBridgeTools(await this.#toolBridge.getTools({ signal }));
+        return this.#execute(emit, signal, pending.modelBinding, definitions, runId, {
+            step: pending.nextStep,
+            recoverableFailures: nextRecoverableFailures,
+            unresolvedToolFailures: unresolved,
         });
-        this.#activeRun = run;
-        void run.result.finally(() => {
-            if (this.#activeRun === run)
-                this.#activeRun = undefined;
-        }).catch(() => undefined);
-        return run;
     }
     #appendContextCheckpoint(entries) {
         const serializedEntries = JSON.stringify(entries);