Signal tool stability with waitForToolsUntil() for user agent observations by khushalsagar · Pull Request #373 · webmachinelearning/webmcp

khushalsagar · 2026-11-03T19:32:23Z

Implement the resolution from #328 (minutes) and #328 (comment):

Add the IDL for waitForToolsUntil and toolsReady, and state tracking for the tools-ready state based on pending promises.
Wait for tools-ready (up to an implementation-defined timeout) in perform an observation.
Dispatch a toolchange event (ToolChangeEvent with ready) when tools become not ready and suppress dispatch of this event until tools become ready again.

Wiring the wait for tools-ready to getTools() and changing dispatch of toolchange events is deferred for a follow up PR.

Note: There's still an open question for the Document lifecycle until which tools are presumed to be not ready.

Part of #328.

Preview | Diff

khushalsagar · 2026-11-03T19:32:25Z

A tangential thing worth taking up in a separate PR: the toolChange notification from register/unregister isn't coalesced well right now. It's triggered for every register/unregister call. Seems like it would be better to do it in a separate task (or microtask?) since in a task the state will be updated by multiple calls and we should dispatch a single event for all those mutations.

markafoltz

Overall structure looks good, it this PR has several features (toolchange event, modelContext.toolsReady, blocking getTools()) not yet landed; are you thinking of adjusting this once the implementations land?

markafoltz · 2026-11-09T23:50:29Z

+1. [=set/Append=] |promise| to |context|'s [=model context/pending tool readiness promises=].
+
+1. [=Update the tools-ready state=] given |document|.


Web IDL wraps every Promise<any> argument in a new promise, so even waitForToolsUntil(Promise.resolve()) or waitForToolsUntil(42) synchronously sets tools-ready to false and fires toolchange{ready:false} at every document. A microtask later it fires toolchange{ready:true}.

Chromium returns early when the promise has already settled, so it fires nothing. The waitForToolsUntil(42) case in the WPT would behave differently from the spec once ToolChangeEvent ships.

Suggest coalescing: have update the tools-ready state queue a task that compares the current state with the last state we notified about, and notify only when they differ. This fits with your PR comment about coalescing the register/unregister notifications.

Updated the spec to match the WPTs and ignore already settled promises, nice catch!

Deferred the ToolChangeEvent dispatch changes to a follow-up PR, will take care of toolchange event batching there. Also, my comment was about an existing issue with no batching for toolchange in the register/unregister case tracked in #374.

Can you add an Issue(374) note in the spec about the toolchange coalescing (if there isn't one already)?

…omments - Defer ToolChangeEvent/toolchange readiness dispatch and the getTools() wait to a follow-up PR. - wait for tools to be ready: capture the top-level active document up front, drop the null check, and return "ready" or "navigated". - perform an observation: return early on "navigated". - waitForToolsUntil(): ignore already-settled promises, split React into fulfilled/rejected branches, and always update tools-ready on settle. - Move tools-ready below the ModelContext creation paragraph, rename the example variable, and fix in-parallel indentation in registerTool().

The navigable can also be destroyed while waiting, so "navigated" was too narrow. Update the note in perform an observation to cover both cases.

* WebPlatform: implement WebMCP (document.modelContext) - document.modelContext and the ModelContext interface of the WebMCP specification: registerTool() (name/description validation, schema serialization, exposedTo, signal), getTools() (frame tree, same-origin and fromOrigins/exposedTo filtering, sorted by name), executeTool() (pending executions per traversable, cancellation, toolcancel and toolactivated events, unloading document cleanup steps), toolchange - the Tool interface of webmachinelearning/webmcp#348 (what Chromium and the WPT implement) instead of the RegisteredTool dictionary, and the outputSchema member - waitForToolsUntil() and toolsReady of webmachinelearning/webmcp#373, marked [Experimental("WEBPLATEXP0018")] - the "tools" permissions policy feature and WebPlatformFeatures.WebMcpEnabled - a host API for the application, as the browser agent: BrowsingContext.GetModelContextTools(), ExecuteModelContextToolAsync() and ModelContextToolsReady - ScriptEngine JSON hooks (JSON.stringify/JSON.parse of the realm) - WPT: run webmcp; the declarative API (explainer only) is skipped, and the subtests that expect unquoted string results are TEST BUGs (webmachinelearning/webmcp#361) * WebPlatform: address the review of WebMCP - the settlement of a tool and of a waitForToolsUntil() promise is handled by a task of the event loop (a task of the application can complete on another thread) - the realms capture JSON.parse() and JSON.stringify() when they are created, before the page can replace them - executeTool() checks the caller again after serializing the arguments (toJSON() can detach it) - Tool.Document is the document that registered the tool

markafoltz

LGTM % adding Issues for things to follow up on.

markafoltz · 2026-11-13T23:40:50Z

+      disconnected and is no longer [=Document/fully active=]. Returning true here immediately
+      unblocks the wait so the caller can check [=Document/fully active=] and abort.
+
+   1. [=list/For each=] [=navigable=] |navigable| of |activeDocument|'s [=Document/inclusive


I didn't see a note about permissions policy near the tools-ready definition, where I expected to find it.

markafoltz · 2026-11-13T23:43:39Z

+1. [=set/Append=] |promise| to |context|'s [=model context/pending tool readiness promises=].
+
+1. [=Update the tools-ready state=] given |document|.


Can you add an Issue(374) note in the spec about the toolchange coalescing (if there isn't one already)?

markafoltz · 2026-11-13T23:51:04Z

+
+1. Let |activeDocument| be |traversable|'s [=navigable/active document=].
+
+1. [=Assert=]: |activeDocument| is [=Document/fully active=].


This is checked before these steps are run, but can this be asserted if this is running in parallel, or do we need to abort if it's no longer the case?

markafoltz · 2026-11-13T23:54:07Z

+
+<dl class="domintro" dfn-type=attribute dfn-for=ToolChangeEvent>
+  : <dfn>ready</dfn>
+  :: Returns true if the tools are ready to be read, or false if tool updates are in progress.


Add a Issue(236) note here to update it later?

markafoltz · 2026-11-13T23:54:34Z


 1. Run the following steps [=in parallel=]:

+   1. [=Wait for tools to be ready=] given |toolRequestor|'s [=node navigable=]'s


Add Issue(328) here noting the deadlock issue?

markafoltz · 2026-11-13T23:58:35Z

+1. If |toolsReady| is false, then return.
+
+1. [=In parallel=], [=notify documents of a tool change=] given |targetDocument|, |exposed
+   origins|, and |toolsReady|.


I don't feel strongly, it just looks a little odd. It should be a minor change on this PR?

markafoltz · 2026-11-13T23:58:41Z


-  1. [=Notify documents of a tool change=] given |tool owner| and |exposed origins|.
+  1. If |toolsReady| is true, then [=notify documents of a tool change=] given |tool owner|,
+     |exposed origins|, and |toolsReady|.


khushalsagar force-pushed the wait-for-tools-until branch 2 times, most recently from 94b382b to 9f62142 Compare November 3, 2026 20:26

khushalsagar requested review from domfarolino and markafoltz November 3, 2026 20:40

Signal tool stability with waitForToolsUntil() and ToolChangeEvent

59af1ff

khushalsagar force-pushed the wait-for-tools-until branch from 9f62142 to 59af1ff Compare November 3, 2026 20:41

kurotanshi mentioned this pull request Nov 9, 2026

本週技術趨勢週報（2026-W46） kurotanshi/grok-weekly#9

Open

markafoltz requested changes Nov 9, 2026

View reviewed changes

markafoltz mentioned this pull request Nov 10, 2026

Clarify the document associated with ModelContext #379

Closed

khushalsagar mentioned this pull request Nov 10, 2026

Batch toolChange notifications for tool registry changes #374

Open

kurotanshi mentioned this pull request Nov 11, 2026

本日技術趨勢日報（2026-11-11） kurotanshi/grok-weekly#11

Open

khushalsagar added 2 commits November 11, 2026 02:10

Return "abort" from wait for tools to be ready

c12e126

The navigable can also be destroyed while waiting, so "navigated" was too narrow. Update the note in perform an observation to cover both cases.

kurotanshi mentioned this pull request Nov 12, 2026

本日技術趨勢日報（2026-11-12） kurotanshi/grok-weekly#12

Open

meziantou mentioned this pull request Nov 12, 2026

WebPlatform: implement WebMCP (document.modelContext) meziantou/Meziantou.Framework#4878

Merged

khushalsagar changed the title ~~Signal tool stability with waitForToolsUntil() and ToolChangeEvent~~ Signal tool stability with waitForToolsUntil() for user agent observations Nov 13, 2026

add point about UA heuristics.

82c0aa6

markafoltz approved these changes Nov 14, 2026

View reviewed changes

		1. [=set/Append=] \|promise\| to \|context\|'s [=model context/pending tool readiness promises=].

		1. [=Update the tools-ready state=] given \|document\|.


		1. Let \|activeDocument\| be \|traversable\|'s [=navigable/active document=].

		1. [=Assert=]: \|activeDocument\| is [=Document/fully active=].


		1. Run the following steps [=in parallel=]:

		1. [=Wait for tools to be ready=] given \|toolRequestor\|'s [=node navigable=]'s

Conversation

khushalsagar commented Nov 3, 2026 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

khushalsagar commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markafoltz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

markafoltz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

khushalsagar commented Nov 3, 2026 •

edited by pr-preview Bot

Loading

khushalsagar commented Nov 3, 2026 •

edited

Loading