diff --git a/index.bs b/index.bs index bbb561c..8d4c0f9 100644 --- a/index.bs +++ b/index.bs @@ -190,6 +190,9 @@ A model context is a [=struct=] with the following [=struct/items=]: object's event loop, and because it is event-loop-local, it can get out of sync from the [=traversable navigable=]'s more "global" map. + : pending tool readiness promises + :: a [=set=] of {{Promise}} objects, initially empty. + A tool definition is a [=struct=] with the following [=struct/items=]: @@ -457,6 +460,9 @@ To notify documents of a tool change given a {{Document}} |tool owner event=] named {{ModelContext/toolchange}} at |targetDocument|'s [=Document/associated ModelContext|associated ModelContext=]. +Issue(#374): Each call to these steps fires a separate {{ModelContext/toolchange}} event. Consider +coalescing the events fired for multiple tool registrations and unregistrations. +

This algorithm's use of the [=webmcp task source=], and the fact that it runs [=in parallel=], means that the timing between firing the {{ModelContext/toolchange}} event, and other tasks queued @@ -500,6 +506,63 @@ a [=list=] of [=origins=] |exposed origins|, and an [=origin=] |accessing origin

+
+To update the tools ready state given a {{Document}} |document|, run these steps: + +1. [=Assert=]: these steps are running on |document|'s [=relevant agent=]'s [=agent/event loop=]. + +1. Let |context| be |document|'s [=Document/associated ModelContext|associated + ModelContext=]'s [=ModelContext/internal context=]. + +1. Set |document|'s [=Document/tools ready=] to true if |context|'s [=model context/pending tool + readiness promises=] is [=set/is empty|empty=]; otherwise false. + +
+ +
+To wait for tools to be ready given a [=top-level traversable=] |traversable|, returning +"ready" or "aborted", run these steps: + +1. [=Assert=]: these steps are running [=in parallel=]. + +1. Let |activeDocument| be |traversable|'s [=navigable/active document=]. + +1. [=Assert=]: |activeDocument| is [=Document/fully active=]. + +1. Let |areAllReady| be an algorithm that returns a [=boolean=] by running these steps: + + 1. If |activeDocument| is not [=Document/fully active=], then return true. + + Note: If |activeDocument| becomes inactive while waiting (for example, because |traversable| + navigated or was destroyed), returning true here immediately unblocks the wait. + + 1. [=list/For each=] [=navigable=] |navigable| of |activeDocument|'s [=Document/inclusive + descendant navigables=]: + + 1. Let |document| be |navigable|'s [=navigable/active document=]. + + 1.

If |document|'s [=Document/tools ready=] is false, then return + false.

+ + 1. Return true. + +1. [=iteration/While=] true: + + 1. If the result of running |areAllReady| is true, then [=iteration/break=]. + + 1. If an [=implementation-defined=] timeout has elapsed since this loop began, then + [=iteration/break=]. + + Note: The timeout is measured from when this loop begins. Calling + {{ModelContext/waitForToolsUntil()}} with additional promises while the loop is running does not + reset or extend the timeout, and calling it after the loop exits does not delay an operation that + has already been unblocked. + +1. Return "ready" if |activeDocument| is [=Document/fully active=]; otherwise + "aborted". + +
+
The tool execute steps, given a [=string=] |toolName|, a {{Document}} |targetDocument|, a [=string=] |inputArguments|, an algorithm |completionSteps|, and a [=unique internal value=] |uuid|, @@ -705,6 +768,18 @@ Upon creation of the {{Document}} object, its [=Document/associated ModelContext {{Document}}'s [=relevant realm=], whose [=ModelContext/associated Document|associated Document=] is set to the {{Document}}. +Each {{Document}} object has a tools ready [=boolean=], initially true. + +Note: Although [=Document/tools ready=] is modified on the {{Document}}'s [=relevant agent=]'s +[=agent/event loop=] and read in parallel, implementations +synchronize updates to [=Document/tools ready=] (for example, via inter-process communication to the +browser process) ordered with updates to [=model context/tool map=]. + +Issue(#328): [=Document/tools ready=] should be false when the {{Document}} is created, unless the +{{Document}} is not [=allowed to use=] the "{{tools}}" feature. This gives authors an opportunity to +use {{ModelContext/waitForToolsUntil()}} until a deterministic {{Document}} lifecycle point. The +exact lifecycle point still needs to be resolved. +
@@ -729,6 +804,7 @@ The {{ModelContext}} interface provides methods for web applications to register [Exposed=Window, SecureContext] interface ModelContext : EventTarget { Promise<undefined> registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {}); + undefined waitForToolsUntil(Promise<any> promise); Promise<sequence<RegisteredTool>> getTools(optional ModelContextGetToolOptions options = {}); Promise<DOMString> executeTool(RegisteredTool tool, optional object inputObject, optional ModelContextExecuteToolOptions options = {}); @@ -755,6 +831,14 @@ is. or {{ModelContextTool/outputSchema}} is invalid.</p> </dd> + <dt><code><var ignore>document</var>.{{Document/modelContext}}.{{ModelContext/waitForToolsUntil(promise)}}</code></dt> + <dd> + <p>Signals that the document is asynchronously registering or updating its tools, and that tool + consumers should wait until <var ignore>promise</var> settles (or a timeout elapses) before + reading the document's tools. Multiple promises can be registered; the document's tools are + considered ready once all registered promises have settled.</p> + </dd> + <dt><code><var ignore>document</var>.{{Document/modelContext}}.{{ModelContext/getTools(options)}}</code></dt> <dd> <p>Returns a promise that resolves to a list of registered tools exposed to this document by @@ -789,6 +873,24 @@ is. ``` </div> +<div class=example id=waiting-for-tools> + The following delays tool discovery until asynchronous tool registration completes: + + ```js + const toolsRegistered = (async () => { + const config = await fetch('/api/tools-config').then(r => r.json()); + for (const tool of config.tools) { + await document.modelContext.registerTool({ + name: tool.name, + description: tool.description, + execute: async (input) => { /* ... */ } + }); + } + })(); + + document.modelContext.waitForToolsUntil(toolsRegistered); + ``` +</div> <div algorithm> The <dfn method for=ModelContext>registerTool(<var>tool</var>, <var>options</var>)</dfn> method steps are: @@ -922,15 +1024,52 @@ The <dfn method for=ModelContext>registerTool(<var>tool</var>, <var>options</var 1. Run the following steps [=in parallel=]: - 1. [=Notify documents of a tool change=] given |tool owner| and |exposed origins|. + 1. [=Notify documents of a tool change=] given |tool owner| and |exposed origins|. - 1. [=Queue a global task=] on the [=webmcp task source=] given |global| to [=resolve=] |promise| - with undefined. + 1. [=Queue a global task=] on the [=webmcp task source=] given |global| to [=resolve=] |promise| + with undefined. 1. Return |promise|. </div> +<div algorithm> +The <dfn method for=ModelContext>waitForToolsUntil(<var>promise</var>)</dfn> method steps are: + +1. Let |document| be [=this=]'s [=ModelContext/associated Document|associated + <code>Document</code>=]. + +1. If |document| is not [=Document/fully active=], then [=exception/throw=] an "{{InvalidStateError}}" + {{DOMException}}. + +1. If |document| is not [=allowed to use=] the "{{tools}}" feature, then [=exception/throw=] a + "{{NotAllowedError}}" {{DOMException}}. + +1. Let |context| be [=this=]'s [=ModelContext/internal context=]. + +1. [=set/Append=] |promise| to |context|'s [=model context/pending tool readiness promises=]. + +1. [=Update the tools ready state=] given |document|. + +1. Let |settleSteps| be the following steps: + + 1. [=set/Remove=] |promise| from |context|'s [=model context/pending tool readiness + promises=]. + + 1. [=Update the tools ready state=] given |document|. + +1. [=promise/React=] to |promise|: + + - If |promise| was fulfilled or rejected, then run |settleSteps|. + +1. [=In parallel=], wait an [=implementation-defined=] amount of time, then [=queue a global task=] + on the [=webmcp task source=] given |document|'s [=relevant global object=] to run |settleSteps|. + + Note: This ensures that a promise which never settles doesn't keep the {{Document}} in the not + ready state indefinitely. + +</div> + <div algorithm> The <dfn method for=ModelContext>getTools(<var>options</var>)</dfn> method steps are: @@ -1587,6 +1726,13 @@ steps: 1. [=Assert=]: |traversable|'s [=navigable/active document=] is [=Document/fully active=]. +1. If the result of [=waiting for tools to be ready=] given |traversable| is + "<code>aborted</code>", then return. + + Note: This happens if |traversable| navigated to a new {{Document}} or was destroyed while + waiting. In the navigation case, implementations will typically [=perform an observation=] + again for the new [=navigable/active document=]. + 1. Let |observation| be a new [=observation=]. 1. Let |flat descendants| be the [=Document/inclusive descendant navigables=] of |traversable|'s @@ -1641,6 +1787,12 @@ observation=] given any [=top-level browsing context=] in the [=user agent=] [=b group set=], at any time, although implementations typically reserve this operation for when the user is interacting with a [=browser agent=] while web content is in view. +Note: Calling {{ModelContext/waitForToolsUntil()}} only delays [=observations=] that the [=user +agent=] chooses to perform while a {{Document}}'s [=Document/tools ready=] is false. Toggling +[=Document/tools ready=] does not by itself cause or guarantee that the [=user agent=] will +[=perform an observation=]. The user agent might apply internal heuristics to ensure page +stability before taking an observation. + <h2 id="security-privacy">Security and Privacy Considerations</h2>