You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
PR #179 adds the toolchange event and establishes the cross-origin tool discovery model: a tool registered with exposedTo: ["https://agent.example"] becomes visible to agent.example via toolchange, and that document can subsequently invoke it. This closes the consumer side of the cross-origin relationship the permitted origin learns when tools become available.
The gap
The registrant side has no equivalent signal. When agent.example invokes the tool, the current ToolExecuteCallback fires:
webidlcallback ToolExecuteCallback = Promise (object input, ModelContextClient client);
The client object carries no information about which origin triggered the call. This is consequential when exposedTo lists multiple origins:
jsdocument.modelContext.registerTool({
name: "get-record",
description: "Fetches a record by ID",
inputSchema: { type: "object", properties: { id: { type: "string" } } },
execute(input, client) {
// client.callerOrigin does not exist
// both callers below receive identical behavior
return getFullRecord(input.id);
}
}, {
exposedTo: [
"https://internal-agent.example",
"https://partner-agent.example"
]
});
The browser already enforces that only listed origins may invoke the tool the exposedTo allowlist check happens during IPC routing before execute() fires. But the result of that check which specific listed origin passed is not forwarded to the callback. The registrant cannot observe it from any other available surface.
The exposedTo declaration creates a named, multi-party relationship at registration time. Without caller identity at invocation time, the registrant cannot implement differentiated behavior within that relationship serving different response shapes to different permitted callers, or making dynamic decisions based on which party in an established relationship is acting.
Proposal
Add callerOrigin as a USVString? attribute on ModelContextClient:
webidlinterface ModelContextClient {
// ... existing members ...
readonly attribute USVString? callerOrigin;
};
callerOrigin is the serialization of the invoking document's origin, produced by running the serialize an origin algorithm. It is null when the invoking agent is a browser's agent.
The browser already computes this value during the exposedTo allowlist check it is the target origin in the tool is visible to an origin algorithm. This proposal forwards it to the callback rather than discarding it.
MessageEvent.origin (HTML §9.4.3) is the closest parallel. In postMessage, the browser enforces origin-based routing; MessageEvent.origin lets the receiver differentiate among already-permitted senders rather than gate access. The motivation here is identical: exposedTo is the allowlist, the browser enforces it, and callerOrigin lets the registrant distinguish which permitted party acted.
Spec delta
The change touches two places in the current spec:
§4.2.3 ModelContextClient interface add the callerOrigin attribute to the IDL and define its value as the serialized origin of the invoking document, set by the browser when constructing the ModelContextClient instance passed to execute.
§3 tool definition / execute steps the execute steps for imperatively-registered tools (currently "steps that invoke the supplied ToolExecuteCallback") need to specify that the ModelContextClient passed to the callback is constructed with callerOrigin set to the serialized origin of the invoking document at the point the allowlist check passes.
The native-agent case
For tools invoked by a browser's agent (no explicit exposedTo, or invoked natively), callerOrigin should be null.
Rationale: a browser's agent has no document origin in the sense the web platform uses that term. Using null (rather than a sentinel string like "browser") is the correct type-safe choice it avoids introducing an unstructured magic string into an otherwise origin-typed field, it is consistent with how the platform handles absent origins elsewhere (e.g. opaque origins serializing to "null" is already a known footgun, so we should not add another string consumers need to guard against), and it gives registrants a clean boolean branch: if (client.callerOrigin === null) means native agent. This does intersect with the open question in the explainer about native-agent exposure and should be resolved in coordination with that discussion.
Background
PR #179 adds the toolchange event and establishes the cross-origin tool discovery model: a tool registered with exposedTo: ["https://agent.example"] becomes visible to agent.example via toolchange, and that document can subsequently invoke it. This closes the consumer side of the cross-origin relationship the permitted origin learns when tools become available.
The gap
The registrant side has no equivalent signal. When agent.example invokes the tool, the current ToolExecuteCallback fires:
webidlcallback ToolExecuteCallback = Promise (object input, ModelContextClient client);
The client object carries no information about which origin triggered the call. This is consequential when exposedTo lists multiple origins:
jsdocument.modelContext.registerTool({
name: "get-record",
description: "Fetches a record by ID",
inputSchema: { type: "object", properties: { id: { type: "string" } } },
execute(input, client) {
// client.callerOrigin does not exist
// both callers below receive identical behavior
return getFullRecord(input.id);
}
}, {
exposedTo: [
"https://internal-agent.example",
"https://partner-agent.example"
]
});
The browser already enforces that only listed origins may invoke the tool the exposedTo allowlist check happens during IPC routing before execute() fires. But the result of that check which specific listed origin passed is not forwarded to the callback. The registrant cannot observe it from any other available surface.
The exposedTo declaration creates a named, multi-party relationship at registration time. Without caller identity at invocation time, the registrant cannot implement differentiated behavior within that relationship serving different response shapes to different permitted callers, or making dynamic decisions based on which party in an established relationship is acting.
Proposal
Add callerOrigin as a USVString? attribute on ModelContextClient:
webidlinterface ModelContextClient {
// ... existing members ...
readonly attribute USVString? callerOrigin;
};
callerOrigin is the serialization of the invoking document's origin, produced by running the serialize an origin algorithm. It is null when the invoking agent is a browser's agent.
The browser already computes this value during the exposedTo allowlist check it is the target origin in the tool is visible to an origin algorithm. This proposal forwards it to the callback rather than discarding it.
Usage:
jsexecute(input, client) {
if (client.callerOrigin === "https://partner-agent.example") {
return { summary: getSummary(input.id) };
}
return { full: getFullRecord(input.id) };
}
Precedent
MessageEvent.origin (HTML §9.4.3) is the closest parallel. In postMessage, the browser enforces origin-based routing; MessageEvent.origin lets the receiver differentiate among already-permitted senders rather than gate access. The motivation here is identical: exposedTo is the allowlist, the browser enforces it, and callerOrigin lets the registrant distinguish which permitted party acted.
Spec delta
The change touches two places in the current spec:
§4.2.3 ModelContextClient interface add the callerOrigin attribute to the IDL and define its value as the serialized origin of the invoking document, set by the browser when constructing the ModelContextClient instance passed to execute.
§3 tool definition / execute steps the execute steps for imperatively-registered tools (currently "steps that invoke the supplied ToolExecuteCallback") need to specify that the ModelContextClient passed to the callback is constructed with callerOrigin set to the serialized origin of the invoking document at the point the allowlist check passes.
The native-agent case
For tools invoked by a browser's agent (no explicit exposedTo, or invoked natively), callerOrigin should be null.
Rationale: a browser's agent has no document origin in the sense the web platform uses that term. Using null (rather than a sentinel string like "browser") is the correct type-safe choice it avoids introducing an unstructured magic string into an otherwise origin-typed field, it is consistent with how the platform handles absent origins elsewhere (e.g. opaque origins serializing to "null" is already a known footgun, so we should not add another string consumers need to guard against), and it gives registrants a clean boolean branch: if (client.callerOrigin === null) means native agent. This does intersect with the open question in the explainer about native-agent exposure and should be resolved in coordination with that discussion.
Related issues