Skip to content

Add ToolActivatedEvent and ToolCancelEvent interfaces #146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
beaufortfrancois wants to merge 4 commits into
base: executeTools
Choose a base branch
from
Open

Add ToolActivatedEvent and ToolCancelEvent interfaces #146

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
88b279e
Add ToolActivatedEvent and ToolCancelEvent interfaces
beaufortfrancois Mar 19, 2026
7dbb2aa
Rebase
beaufortfrancois May 27, 2026
46633b1
Specify and fire toolactivated event in imperative execute steps
beaufortfrancois Aug 6, 2026
1099a80
Specify and fire toolcancel event when tool execution is aborted
beaufortfrancois Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 72 additions & 9 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -411,7 +411,9 @@ The <dfn>imperative execute steps</dfn>, given a {{ModelContextTool}} |tool|, a
1. If |inputObject| [=Object type|is not an Object=] is false, then run |completionSteps| given null
and false, and abort these steps.

Issue(#146): Specify and fire the "<code>toolactivated</code>" event.
1. [=Fire an event=] named {{ModelContext/toolactivated}} at |targetDocument|'s [=Document/associated
ModelContext|associated <code>ModelContext</code>=], using {{ToolActivatedEvent}}, with its
{{ToolActivatedEvent/toolName}} attribute initialized to |tool|'s {{ModelContextTool/name}}.

1. Let |toolPromise| be the result of [=invoke|invoking=] |tool|'s {{ModelContextTool/execute}} with
|inputObject|.
Expand Down Expand Up @@ -526,6 +528,8 @@ interface ModelContext : EventTarget {
Promise<DOMString> executeTool(RegisteredTool tool, DOMString inputArguments, optional ModelContextExecuteToolOptions options = {});

attribute EventHandler ontoolchange;
attribute EventHandler ontoolactivated;
attribute EventHandler ontoolcancel;
};
</xmp>

Expand Down Expand Up @@ -828,6 +832,11 @@ The <dfn method for=ModelContext>executeTool(<var>tool</var>, <var>inputArgument

1. [=Assert=]: |expectedTargetOrigin| is not an [=opaque origin=].

1. Let |targetWindow| be |tool|'s {{RegisteredTool/window}}.

1. Let |targetDocument| be |targetWindow|'s [=associated Document|associated
<code>Document</code>=].

1. Let |promise| be [=a new promise=] created in [=this=]'s [=relevant realm=].

1. If |options|'s {{ModelContextExecuteToolOptions/signal}} [=map/exists=], then:
Expand All @@ -841,15 +850,13 @@ The <dfn method for=ModelContext>executeTool(<var>tool</var>, <var>inputArgument

1. [=Reject=] |promise| with |signal|'s [=AbortSignal/abort reason=].

Issue(#48): Wire up |signal| to the tool execution callback in the tool host's document, so
that tool abort is communicated all the way through. This should also fire the
"<code>toolcanceled</code>" event in the target document. See also <a
href=https://github.com/webmachinelearning/webmcp/issues/146>issue #146</a>.

1. Let |targetWindow| be |tool|'s {{RegisteredTool/window}}.
1. [=Fire an event=] named {{ModelContext/toolcancel}} at |targetDocument|'s
[=Document/associated ModelContext|associated <code>ModelContext</code>=], using
{{ToolCancelEvent}}, with its {{ToolCancelEvent/toolName}} attribute initialized to
|tool|'s {{RegisteredTool/name}}.

1. Let |targetDocument| be |targetWindow|'s [=associated Document|associated
<code>Document</code>=].
Issue(#48): Wire up |signal| to the tool execution callback in the tool host's document, so
that tool abort is communicated all the way through.

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

Expand Down Expand Up @@ -1158,6 +1165,56 @@ dictionary RegisteredTool {
</dl>


<h4 id="tool-activated-event">ToolActivatedEvent Interface</h4>

The {{ToolActivatedEvent}} interface represents a {{ModelContext/toolactivated}} event that is dispatched at {{ModelContext}} when a tool is invoked by an [=agent=].

<xmp class="idl">
[Exposed=Window, SecureContext]
interface ToolActivatedEvent : Event {
constructor(DOMString type, optional ToolActivatedEventInit eventInitDict = {});
readonly attribute DOMString toolName;
readonly attribute Element? element;
};

dictionary ToolActivatedEventInit : EventInit {
DOMString toolName = "";
Element? element = null;
};
</xmp>

<dl class="domintro" dfn-type=attribute dfn-for=ToolActivatedEvent>
: <dfn>toolName</dfn>
:: Returns the name of the tool that was activated.
: <dfn>element</dfn>
:: Returns the form element associated with the tool, if any.
</dl>

<h4 id="tool-cancel-event">ToolCancelEvent Interface</h4>

The {{ToolCancelEvent}} interface represents a {{ModelContext/toolcancel}} event that is dispatched at {{ModelContext}} when a tool's invocation is canceled by an [=agent=].

<xmp class="idl">
[Exposed=Window, SecureContext]
interface ToolCancelEvent : Event {
constructor(DOMString type, optional ToolCancelEventInit eventInitDict = {});
readonly attribute DOMString toolName;
readonly attribute Element? element;
};

dictionary ToolCancelEventInit : EventInit {
DOMString toolName = "";

@bwalderman bwalderman Mar 19, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at this interface, I'm seeing a potential problem with multiple agents and concurrent activations of the same tool. Which one should be cancelled if all we know is the tool name? I'll comment on the issue.

Element? element = null;
};
</xmp>

<dl class="domintro" dfn-type=attribute dfn-for=ToolCancelEvent>
: <dfn>toolName</dfn>
:: Returns the name of the tool that was canceled.
: <dfn>element</dfn>
:: Returns the form element associated with the tool, if any.
</dl>

<h3 id="declarative-api">Declarative WebMCP</h3>

This section is entirely a TODO. For now, refer to the [explainer draft](https://github.com/webmachinelearning/webmcp/pull/76).
Expand Down Expand Up @@ -1217,6 +1274,12 @@ that must be supported, as [=event handler IDL attributes=], by all {{ModelConte
<tr>
<td><dfn attribute for="ModelContext">ontoolchange</dfn>
<td><dfn event for="ModelContext">toolchange</dfn>
<tr>
<td><dfn attribute for="ModelContext">ontoolactivated</dfn>
<td><dfn event for="ModelContext">toolactivated</dfn>
<tr>
<td><dfn attribute for="ModelContext">ontoolcancel</dfn>
<td><dfn event for="ModelContext">toolcancel</dfn>
</table>

<h3 id="permissions-policy">Permissions policy integration</h3>
Expand Down
Loading