From c0e703cab200236ac7b16b3407ea6e5b9bea9d0f Mon Sep 17 00:00:00 2001
From: "mark a. foltz" <mfoltz@chromium.org>
Date: Mon, 28 Sep 2026 15:52:06 -0700
Subject: [PATCH 1/3] Add explainer for continuations

---
 continuations-explainer.md | 265 +++++++++++++++++++++++++++++++++++++
 1 file changed, 265 insertions(+)
 create mode 100644 continuations-explainer.md

diff --git a/continuations-explainer.md b/continuations-explainer.md
new file mode 100644
index 0000000..283e551
--- /dev/null
+++ b/continuations-explainer.md
@@ -0,0 +1,265 @@
+# Continuation Tokens
+
+[*mark a. foltz*](mailto:mfoltz@google.com)
+
+# Overview
+
+[WebMCP](https://webmachinelearning.github.io/webmcp/) allows sites to declare
+imperative script tools to be invoked by agents. To complete a task, control
+flow is typically exchanged between the site and the agent.  The agent initiates
+a tool call on the site, the site executes the tool with site-defined
+Javascript, and returns output to the agent, which consumes the output and plans
+the next action.
+
+However, tool calls are restricted to execute in a single document, and a single
+Promise per tool call.  This leads to unfortunate limitations:
+
+* If a site executes a server request that navigates the document, the original
+  tool request is ended and the agent does not receive a success signal or tool
+  output.
+* If a tool call wants to append further output, for example to list a following
+  page of results, it has no way of doing so.
+
+We propose a *Tool Continuation* as a way for the tool author to request that
+the agent invoke the tool at a future time on a related document.
+
+**This introduces a higher level of abstraction for the agent.** Instead of
+acting on the site with a fragmented collection of tools partitioned according
+to the site structure (pages/frames), it can act on the site as a cohesive
+application with tools matching end-user use cases (like "checkout").  Tool
+continuations allow these use cases to be implemented across documents and
+frames without the agent needing to reverse engineer the site's internal
+structure.
+
+# Use Cases (In Scope)
+
+Let's consider a clothing e-commerce site [dresswear.com](http://dresswear.com)
+that allows the user to browse items of clothing, add them to a cart and check
+out.
+
+## Cross-document tool invocation
+
+After completing add-to-cart, the user wants to check out. The site offers a
+tool to do so:
+
+```js
+checkout(shipping_address, billing_address, card_details)
+```
+
+However, the implementation of this tool is actually spread across three
+distinct pages (`/shipping`, `/billing`, `/checkout`). For the tool to complete,
+the site needs to do a hard navigation across these three pages before finally
+submitting the checkout request to the server.
+
+## Cross-frame tool invocation
+
+[dresswear.com](http://dresswear.com) has a feature where the user can virtually
+try on an item of clothing while on an item page.  Because the try-on
+application is expensive to load, it is created on-demand in a same-origin
+`<iframe>` on the page.
+
+The main page exposes a tool for the try-on feature:
+
+```js
+try_on(item_id)
+```
+
+However, the virtual try-on can only be fulfilled in the `<iframe>`, which is
+only created on demand, so the tool can't be implemented entirely in the main
+page.
+
+# Proposal
+
+## Token Creation
+
+We introduce a `ModelContextToolInvocation` object that is passed to a tool's
+execute callback via the `ToolExecuteCallbackOptions`.  This object allows the
+execute callback to access context about the current tool execution and request
+tokens.
+
+```js
+
+dictionary ToolExecuteCallbackOptions {
+  required AbortSignal signal;
+  required ModelContextToolInvocation invocation;
+};
+
+[Exposed=Window, SecureContext]
+interface ModelContextToolInvocation {
+  // Requests a unique continuation token for this invocation.  Can be redeemed
+  // to continue tool execution on another document.
+  Promise<DOMString> requestToken();
+}
+```
+Notes:
+
+* `requestToken()` returns a DOMString to allow simple storage and transmission
+  of the token.
+* `requestToken()` returns a `Promise` to allow the token to be successfully
+  registered with agents and bound to the correct origin before returning, which
+  likely requires cross-process IPC.
+* `requestToken()` rejects if the current task is not executing the callback for a tool.
+
+## Token Redemption
+
+Sites redeem a token by calling `resumeTool()`, which registers a request to
+resume tool execution.  This can happen in a document other than the one that
+generated the token.  The site is responsible for passing this token (along with
+any other additional state required for the tool call to resume) to the new
+document before calling `resumeTool()`.
+
+
+```js
+[Exposed=Window, SecureContext]
+partial interface ModelContext {
+  Promise<undefined> resumeTool(DOMString token, ToolExecuteCallback callback);
+};
+```
+
+**This action has the following side effects:**
+
+* If the token is accepted for redemption, then the Promise resolves
+  successfully.
+* The browser will call `callback` again shortly in the document that requested
+  it.
+* The `callback` will be passed the input object that was passed to the original
+  tool call and a new `ToolExecuteCallbackOptions.`
+
+**The following conditions apply on token redemption:**
+
+* The token may only be redeemed once.  
+* Calls to resumeTool() while the initial tool is executing are allowed, but any
+  invocation of the callback will occur after the initial tool call is complete.
+* Redemption fails if the document is not same-origin and part of the same
+  browsing context. same browsing context group.
+* If the original tool call is canceled by the caller (via AbortSignal for
+  web-platform callers, or internally by a built-in agent)`,`then the token is
+  revoked.
+* The browser may limit the lifetime of a token, i.e. it cannot be redeemed at
+  an arbitrary time later.  The initial limit will be set by looking at agent
+  trajectory data, and will probably fall around 60 seconds.
+* The token is implicitly canceled by the browser if the agent abandoned the
+  task, received different user instructions, was blocked from accessing the
+  site, etc.
+
+If any of these conditions are not met, then `resumeTool()` rejects.
+
+## Agent Behaviors
+
+When the tool requests a token, this is a signal to the agent that the tool has
+not completed execution.  Any output from the tool should be considered as
+partial output, and the browser should expect additional output before the tool
+invocation is completed.
+
+The browser will wait until all tokens are redeemed in the chain, all tool calls
+have resolved, and show the model the final output of all tool calls.  This
+blocks the agent until the completion of a chain of continued tool calls.
+
+# Examples
+
+## Cross-document tool invocation
+
+```js
+// /billing.html
+<script>
+modelContext.registerTool({
+   name: "checkout",
+   inputSchema: {
+     type: "object",
+     properties: {
+       billing_address: { type: "string" },
+       shipping_address: { type: "string" }
+     }, required: ["billing_address", "shipping_address"]
+   },
+   execute: async (input, options) => {
+    // We'll need to continue on the next page for billing info.
+    const token = await options.invocation.requestToken();
+    // Handle billing_address (submit to server, etc.)
+    await submitBillingAddress(input.billing_address);
+    // Navigate to /shipping.html
+    window.location.href = '/shipping.html?checkout_token=${token}';
+  }
+)};
+</script>
+```
+
+```js
+// /shipping.html
+<script>
+// Request resumption of the checkout tool.
+modelContext.resumeTool(
+  new URLSearchParams(window.location.search).get('token'),
+  async (input, options) => {
+    // We'll need to continue again on the next page for confirmation.
+    const token = await options.invocation.requestToken();
+    // Handle shipping_address (submit to server, etc.)
+    await submitShippingAddress(input.shipping_address);
+    // Navigate to /confirmation.html
+    window.location.href = '/confirmation.html?token=${token}';
+  }
+);
+</script>
+```
+# Alternatives Considered
+
+*Cross-navigation Promises.* We could invent a type of Promise (or some other
+script object) that survives navigation and is passed from one tool to
+another.  This seems technically very complicated as that object could have
+references into multiple script states and DOM trees.
+
+*Tool Chaining.* We could have a tool return a call to another tool to be
+invoked as a subsequent action by the agent.  This is a variant, but exposes
+the application structure to the agent, which would need to chain multiple
+tools to accomplish the intended task.  A goal is to minimize exposure of the
+site structure for tools that cross document boundaries.
+
+# Document Lifecycle Considerations
+
+Tokens cannot be requested or redeemed on inactive documents or frames.
+
+_Question:_ If a tool requests a token, and at a later time the tool call does
+not complete (because the document becomes inactive or unloaded), then does the
+token remain valid?
+
+_Question:_ If a document requests a token then performs a cross-origin
+navigation, does the token remain valid?  If so, how many navigations are
+allowed before the token expires?
+
+# Security and Privacy Considerations
+
+The token should be unguessable.  Tokens should be created and tracked in a
+trusted process to ensure access by permitted same-origin document(s) and
+one-time redemption.
+
+Its bearer will get access to the knowledge that a tool was called and the input
+to that tool, which may contain private user information.  For this reason, the
+token is intended to be origin-bound.  Leaking it to untrusted origins is not a
+risk as it cannot be redeemed on them.
+
+_Question:_ Do we allow tokens to be redeemed by a same-origin \<iframe\>
+embedded in a cross-origin main frame?  This depends on how we view tokens
+related to storage partitioning.
+
+# Accessibility Considerations
+
+This proposal does not create new accessibility considerations.
+
+# Future Extensions (Out of Scope for Initial Proposal)
+
+- Partial function calling
+- Cross-origin tool calling in frames
+- Document-to-worker tool calling (and vice versa)
+- Document-to-server handoff
+
+## Browsing context groups
+
+Tools or agents may open additional browsing contexts (tabs, popup windows), and
+it may be advantageous to allow tool calls to span these additional documents.
+The scoping of tokens to browsing contexts can be relaxed in the future if this
+does not introduce any implementation or agent compatibility issues.
+
+## Declarative Forms
+
+If the tool is declared through a `<form>` element, we can configure the form to
+generate a token that can be redeemed in a post-submit document.  This could be
+done through an additional `<form>` attribute or `<input>` type.

From 487f3831452953e9dfa758c172b74b5119a2377e Mon Sep 17 00:00:00 2001
From: "mark a. foltz" <mfoltz@chromium.org>
Date: Tue, 29 Sep 2026 12:57:25 -0700
Subject: [PATCH 2/3] Respond to comments from Dom and Francois

---
 continuations-explainer.md | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/continuations-explainer.md b/continuations-explainer.md
index 283e551..6f0690c 100644
--- a/continuations-explainer.md
+++ b/continuations-explainer.md
@@ -78,9 +78,7 @@ execute callback to access context about the current tool execution and request
 tokens.
 
 ```js
-
-dictionary ToolExecuteCallbackOptions {
-  required AbortSignal signal;
+partial dictionary ToolExecuteCallbackOptions {
   required ModelContextToolInvocation invocation;
 };
 
@@ -96,9 +94,9 @@ Notes:
 * `requestToken()` returns a DOMString to allow simple storage and transmission
   of the token.
 * `requestToken()` returns a `Promise` to allow the token to be successfully
-  registered with agents and bound to the correct origin before returning, which
-  likely requires cross-process IPC.
-* `requestToken()` rejects if the current task is not executing the callback for a tool.
+  registered with agents and bound to the correct origin before returning.
+* `requestToken()` rejects if the tool Promise associated with the invocation
+  has settled.
 
 ## Token Redemption
 
@@ -161,7 +159,6 @@ blocks the agent until the completion of a chain of continued tool calls.
 
 ```js
 // /billing.html
-<script>
 modelContext.registerTool({
    name: "checkout",
    inputSchema: {
@@ -177,15 +174,13 @@ modelContext.registerTool({
     // Handle billing_address (submit to server, etc.)
     await submitBillingAddress(input.billing_address);
     // Navigate to /shipping.html
-    window.location.href = '/shipping.html?checkout_token=${token}';
+    window.location.href = '/shipping.html?token=${token}';
   }
 )};
-</script>
 ```
 
 ```js
 // /shipping.html
-<script>
 // Request resumption of the checkout tool.
 modelContext.resumeTool(
   new URLSearchParams(window.location.search).get('token'),
@@ -198,7 +193,6 @@ modelContext.resumeTool(
     window.location.href = '/confirmation.html?token=${token}';
   }
 );
-</script>
 ```
 # Alternatives Considered
 

From 8a8020f0b55b507ddb2b8c5e84a99d2276ced395 Mon Sep 17 00:00:00 2001
From: "mark a. foltz" <mfoltz@chromium.org>
Date: Fri, 2 Oct 2026 13:07:58 -0700
Subject: [PATCH 3/3] Respond to more comments from Dom and Francois

---
 continuations-explainer.md | 40 +++++++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 16 deletions(-)

diff --git a/continuations-explainer.md b/continuations-explainer.md
index 6f0690c..3a88db7 100644
--- a/continuations-explainer.md
+++ b/continuations-explainer.md
@@ -1,6 +1,7 @@
 # Continuation Tokens
 
-[*mark a. foltz*](mailto:mfoltz@google.com)
+[*mark a. foltz*](mailto:mfoltz@google.com), grateful for input from Dominic
+Farolino and several others.
 
 # Overview
 
@@ -129,9 +130,9 @@ partial interface ModelContext {
 * Calls to resumeTool() while the initial tool is executing are allowed, but any
   invocation of the callback will occur after the initial tool call is complete.
 * Redemption fails if the document is not same-origin and part of the same
-  browsing context. same browsing context group.
+  browsing context.
 * If the original tool call is canceled by the caller (via AbortSignal for
-  web-platform callers, or internally by a built-in agent)`,`then the token is
+  web-platform callers, or internally by a built-in agent), then the token is
   revoked.
 * The browser may limit the lifetime of a token, i.e. it cannot be redeemed at
   an arbitrary time later.  The initial limit will be set by looking at agent
@@ -142,12 +143,19 @@ partial interface ModelContext {
 
 If any of these conditions are not met, then `resumeTool()` rejects.
 
+Note that `resumeTool()` is passed a `signal` via
+`ToolExecuteCallbackOptions.signal` for the browser or agent to signal
+cancellation of a resumed tool execution, the same way a `signal` was passed to
+the original invocation of `executeTool()`.  If that `signal` is triggered
+during the execution of the `resumeTool()` callback, then its `Promise` will be
+rejected.
+
 ## Agent Behaviors
 
 When the tool requests a token, this is a signal to the agent that the tool has
 not completed execution.  Any output from the tool should be considered as
-partial output, and the browser should expect additional output before the tool
-invocation is completed.
+intermediate output that is not shown to the agent, and the browser should
+expect final output to show to the agent when the tool invocation is completed.
 
 The browser will wait until all tokens are redeemed in the chain, all tool calls
 have resolved, and show the model the final output of all tool calls.  This
@@ -160,21 +168,21 @@ blocks the agent until the completion of a chain of continued tool calls.
 ```js
 // /billing.html
 modelContext.registerTool({
-   name: "checkout",
-   inputSchema: {
-     type: "object",
-     properties: {
-       billing_address: { type: "string" },
-       shipping_address: { type: "string" }
-     }, required: ["billing_address", "shipping_address"]
-   },
-   execute: async (input, options) => {
+  name: "checkout",
+  inputSchema: {
+    type: "object",
+    properties: {
+      billing_address: { type: "string" },
+      shipping_address: { type: "string" }
+    }, required: ["billing_address", "shipping_address"]
+  },
+  execute: async (input, options) => {
     // We'll need to continue on the next page for billing info.
     const token = await options.invocation.requestToken();
     // Handle billing_address (submit to server, etc.)
     await submitBillingAddress(input.billing_address);
     // Navigate to /shipping.html
-    window.location.href = '/shipping.html?token=${token}';
+    window.location.href = `/shipping.html?token=${token}`;
   }
 )};
 ```
@@ -190,7 +198,7 @@ modelContext.resumeTool(
     // Handle shipping_address (submit to server, etc.)
     await submitShippingAddress(input.shipping_address);
     // Navigate to /confirmation.html
-    window.location.href = '/confirmation.html?token=${token}';
+    window.location.href = `/confirmation.html?token=${token}`;
   }
 );
 ```