@orkestrel/mcp 0.0.32 → 0.0.34

package/README.md

@@ -76,8 +76,9 @@ and the browser face (`./browser`), which is ESM only.
 
 `npm run test:conformance` starts the real Streamable HTTP server from this
 package's source and runs
-`@modelcontextprotocol/conformance@0.2.0-alpha.10` against MCP revision
-`2026-07-28`. The recorded result is **23 passed / 0 failed**. That is a
+`@modelcontextprotocol/conformance@0.2.0-alpha.11` against MCP revision
+`2026-07-28`. The recorded result is **147 passed / 0 failed**, from the run on
+2026-09-29 against the built `dist/`. That is a
 genuine foreign MCP client driving this server end to end, and it is
 evidence about the wire. It resolves the runner from `node_modules` and
 drives a loopback socket, so the run is offline and `npm test` gates it.

package/dist/src/browser/index.d.ts

@@ -433,6 +433,23 @@ export declare function isWebMCPDocument(value: unknown): value is WebMCPDocumen
  */
 export declare function isWebMCPRegistry(value: unknown): value is WebMCPRegistryInterface;
 
+/**
+ * Determines whether an unknown value is a WebMCP execution event.
+ *
+ * @remarks
+ * Reads the IDL's `toolName` attribute and nothing else, so it admits a `ToolActivatedEvent`
+ * and a `ToolCancelEvent` and refuses a plain `Event`.
+ *
+ * @param value - The unknown value to inspect
+ * @returns True if the value carries a string `toolName`; false otherwise
+ *
+ * @example
+ * ```ts
+ * isWebMCPToolEvent(new Event('toolactivated')) // false
+ * ```
+ */
+export declare function isWebMCPToolEvent(value: unknown): value is WebMCPToolEvent;
+
 /**
  * Determines whether two WebMCP descriptors advertise the same tool to the registry.
  *
@@ -618,7 +635,7 @@ export declare interface MessagePortTransportOptions {
 export declare class ModelContext implements ModelContextInterface {
     #private;
     /**
-     * Binds a narrowed document's registry and arms the `toolchange` subscription.
+     * Binds a narrowed document's registry and arms its change and execution subscriptions.
      *
      * @param document - The document whose `modelContext` this handle bridges
      * @param options - The emitter's initial hooks and listener-error handler; see
@@ -632,28 +649,37 @@ export declare class ModelContext implements ModelContextInterface {
 }
 
 /**
- * Options for {@link ModelContextInterface.adopt} — the origins whose tools are read.
+ * Options for {@link ModelContextInterface.adopt} — the origins and debugging tools to include.
  *
  * @remarks
  * `origins` is this package's one-word name for WebMCP's `fromOrigins`, forwarded unchanged.
  * Omitting it reads this document's own registrations.
+ * If `debugging` is `true`, tools carrying `annotations.debugging: true` are included;
+ * if `false` or omitted, they are excluded. Default: `false`.
  */
 export declare interface ModelContextAdoptOptions {
     readonly origins?: readonly string[];
+    readonly debugging?: boolean;
 }
 
 /**
- * Reports the moments a WebMCP registry's contents changed.
+ * Reports changes and execution events from a WebMCP registry.
  *
  * @remarks
  * Declared as a `type` alias rather than an interface, so the type-literal satisfies
- * `EventMap` structurally. One event, because the registry publishes one: WebMCP's
+ * `EventMap` structurally. The 2026-09-29 WebMCP draft's
  * `toolchange` names no tool and carries no payload, so the bridge republishes it as a bare
  * signal and a listener re-reads {@link ModelContextInterface.adopt} to learn what changed.
+ * `toolactivated` and `toolcancel` carry the tool name; cancellation uses the bridge's
+ * lifecycle verb `abort`.
  */
 export declare type ModelContextEventMap = {
     /** Reports that the document's registry changed — re-read it to learn how. */
     readonly change: readonly [];
+    /** Reports the tool whose execution begins. */
+    readonly activate: readonly [name: string];
+    /** Reports the tool whose pending execution is aborted. */
+    readonly abort: readonly [name: string];
 };
 
 /**
@@ -672,7 +698,7 @@ export declare type ModelContextEventMap = {
  * never registered are untouched.
  */
 export declare interface ModelContextInterface {
-    /** Holds the emitter republishing the registry's `toolchange` as `change`. */
+    /** Holds the emitter republishing registry changes, activation, and aborts. */
     readonly emitter: EmitterInterface<ModelContextEventMap>;
     /**
      * Registers every tool the manager holds at this moment, then follows it.
@@ -734,9 +760,12 @@ export declare interface ModelContextInterface {
      */
     publish(tools: ToolManagerInterface, options?: ModelContextPublishOptions): Promise<void>;
     /**
-     * Reads the document's registered tools as locally executable tools.
+     * Reads the document's registered tools as locally executable tools, excluding debugging tools unless requested.
      *
      * @remarks
+     * Tools carrying `annotations.debugging: true` are excluded unless `options.debugging`
+     * is `true`. Tools with a false or omitted hint are included either way.
+     *
      * Each returned tool's `execute` runs the registry's `executeTool` and forwards its
      * `ToolContext.signal` as WebMCP's `signal`, so an agent-side abort reaches the foreign
      * tool. The value resolves unchanged: WebMCP's own sources disagree about whether a tool
@@ -747,8 +776,8 @@ export declare interface ModelContextInterface {
      * unreadable or hostile schema refuse the whole `adopt` call, and the arguments reach a
      * handler in another document that has to validate them anyway.
      *
-     * @param options - The optional origin filter; see {@link ModelContextAdoptOptions}
-     * @returns The registry's tools, in registry order
+     * @param options - The origin and debugging filters; see {@link ModelContextAdoptOptions}
+     * @returns The included registry tools, in registry order
      */
     adopt(options?: ModelContextAdoptOptions): Promise<readonly ToolInterface[]>;
     /**
@@ -964,6 +993,12 @@ export declare function toolAnnotationsToWebMCP(annotations: ToolAnnotations): W
  */
 export declare function toolToWebMCP(definition: ToolDefinition): WebMCPDescriptor | undefined;
 
+/** Names the WebMCP IDL `toolcancel` event the bridge republishes as `abort`. */
+export declare const WEBMCP_ABORT_EVENT = "toolcancel";
+
+/** Names the WebMCP IDL `toolactivated` event the bridge republishes as `activate`. */
+export declare const WEBMCP_ACTIVATED_EVENT = "toolactivated";
+
 /** Names the WebMCP registry event the bridge republishes as its own `change`. */
 export declare const WEBMCP_CHANGE_EVENT = "toolchange";
 
@@ -971,17 +1006,20 @@ export declare const WEBMCP_CHANGE_EVENT = "toolchange";
  * Describes a tool's observable effects as the WebMCP registry declares them.
  *
  * @remarks
- * Transliterates the WebMCP `ToolAnnotations` dictionary. The IDL defaults each member to
+ * Transliterates the 2026-09-29 WebMCP draft's `ToolAnnotations` dictionary. The IDL defaults each member to
  * `false`; this declaration keeps every member optional instead, because the bridge projects
  * from `@orkestrel/tool`'s `ToolAnnotations` and never invents a hint the author omitted. The
  * mapping is `pure` to `readOnlyHint`, `untrusted` to `untrustedContentHint`, and
  * `consequential` to `consequentialHint` — a fuller correspondence than the MCP wire's, which
  * has no counterpart for `untrusted` and spells the consequence `destructiveHint`.
+ * The `debugging` hint has no domain counterpart: publication omits it and adoption filters it before
+ * projecting the remaining hints.
  */
 export declare interface WebMCPAnnotations {
     readonly readOnlyHint?: boolean;
     readonly untrustedContentHint?: boolean;
     readonly consequentialHint?: boolean;
+    readonly debugging?: boolean;
 }
 
 /**
@@ -1109,9 +1147,10 @@ export declare interface WebMCPRegisterOptions {
  * Represents the WebMCP tool registry a document exposes as `document.modelContext`.
  *
  * @remarks
- * Transliterates the WebMCP `ModelContext` interface, which extends `EventTarget`: the
- * operations plus the `toolchange` subscription the bridge republishes as
- * {@link ModelContextEventMap}'s `change`. Only the members the bridge touches are declared,
+ * Transliterates the 2026-09-29 WebMCP draft's `ModelContext` interface, which extends
+ * `EventTarget`: the operations plus the `toolchange`, `toolactivated`, and `toolcancel`
+ * subscriptions the bridge republishes as {@link ModelContextEventMap}'s `change`,
+ * `activate`, and `abort`. Only the members the bridge touches are declared,
  * exactly as {@link ScopeInterface} declares only what `createScopeServer` touches, so a real
  * `ModelContext` satisfies this structurally and an IDL-faithful double satisfies it without
  * implementing the whole of `EventTarget`.
@@ -1131,8 +1170,10 @@ export declare interface WebMCPRegistryInterface {
     executeTool(tool: WebMCPRegisteredTool, input?: Readonly<Record<string, unknown>>, options?: WebMCPExecuteOptions): Promise<unknown>;
     /** Subscribes to the registry's `toolchange` event. */
     addEventListener(type: 'toolchange', listener: () => void): void;
+    addEventListener(type: 'toolactivated' | 'toolcancel', listener: (event: Event) => void): void;
     /** Drops a `toolchange` subscription. */
     removeEventListener(type: 'toolchange', listener: () => void): void;
+    removeEventListener(type: 'toolactivated' | 'toolcancel', listener: (event: Event) => void): void;
 }
 
 /**
@@ -1146,6 +1187,18 @@ export declare interface WebMCPTool extends WebMCPDescriptor {
     readonly execute: WebMCPExecuteHandler;
 }
 
+/**
+ * Carries the tool name a WebMCP execution event reports.
+ *
+ * @remarks
+ * Transliterates the `toolName` attribute of `ToolActivatedEvent` and `ToolCancelEvent` in
+ * the 2026-09-29 WebMCP draft, the only event member the bridge reads. The `isWebMCPToolEvent`
+ * guard narrows a dispatched `Event` onto this shape.
+ */
+export declare interface WebMCPToolEvent {
+    readonly toolName: string;
+}
+
 /**
  * Options for the WebMCP registry's `getTools` — the origins whose tools are read.
  *

package/dist/src/browser/index.js

@@ -9,6 +9,10 @@ var DEFAULT_MCP_SERVER_NAME = "@orkestrel/mcp";
 var DEFAULT_MCP_SERVER_VERSION = "1.0.0";
 /** Names the WebMCP registry event the bridge republishes as its own `change`. */
 var WEBMCP_CHANGE_EVENT = "toolchange";
+/** Names the WebMCP IDL `toolactivated` event the bridge republishes as `activate`. */
+var WEBMCP_ACTIVATED_EVENT = "toolactivated";
+/** Names the WebMCP IDL `toolcancel` event the bridge republishes as `abort`. */
+var WEBMCP_ABORT_EVENT = "toolcancel";
 //#endregion
 //#region src/browser/validators.ts
 /**
@@ -57,6 +61,24 @@ function isWebMCPRegistry(value) {
 function isWebMCPDocument(value) {
 	return objectOf({ modelContext: isWebMCPRegistry })(value);
 }
+/**
+* Determines whether an unknown value is a WebMCP execution event.
+*
+* @remarks
+* Reads the IDL's `toolName` attribute and nothing else, so it admits a `ToolActivatedEvent`
+* and a `ToolCancelEvent` and refuses a plain `Event`.
+*
+* @param value - The unknown value to inspect
+* @returns True if the value carries a string `toolName`; false otherwise
+*
+* @example
+* ```ts
+* isWebMCPToolEvent(new Event('toolactivated')) // false
+* ```
+*/
+function isWebMCPToolEvent(value) {
+	return objectOf({ toolName: isString })(value);
+}
 //#endregion
 //#region src/browser/helpers.ts
 /**
@@ -358,12 +380,14 @@ var ModelContext = class {
 	#emitter;
 	#registrations = /* @__PURE__ */ new Map();
 	#listener;
+	#activated;
+	#aborted;
 	#followed = void 0;
 	#pendingManager = void 0;
 	#queue = Promise.resolve();
 	#destroyed = false;
 	/**
-	* Binds a narrowed document's registry and arms the `toolchange` subscription.
+	* Binds a narrowed document's registry and arms its change and execution subscriptions.
 	*
 	* @param document - The document whose `modelContext` this handle bridges
 	* @param options - The emitter's initial hooks and listener-error handler; see
@@ -377,6 +401,10 @@ var ModelContext = class {
 		});
 		this.#listener = this.#republish.bind(this);
 		this.#registry.addEventListener(WEBMCP_CHANGE_EVENT, this.#listener);
+		this.#activated = this.#republishTool.bind(this, "activate");
+		this.#aborted = this.#republishTool.bind(this, "abort");
+		this.#registry.addEventListener(WEBMCP_ACTIVATED_EVENT, this.#activated);
+		this.#registry.addEventListener(WEBMCP_ABORT_EVENT, this.#aborted);
 	}
 	get emitter() {
 		return this.#emitter;
@@ -391,7 +419,7 @@ var ModelContext = class {
 		return settled;
 	}
 	async adopt(options) {
-		return (await this.#registry.getTools(options?.origins === void 0 ? {} : { fromOrigins: options.origins })).map((tool) => createTool({
+		return (await this.#registry.getTools(options?.origins === void 0 ? {} : { fromOrigins: options.origins })).filter((tool) => options?.debugging === true || tool.annotations?.debugging !== true).map((tool) => createTool({
 			...webMCPToTool(tool),
 			execute: this.#execute.bind(this, tool)
 		}));
@@ -402,6 +430,8 @@ var ModelContext = class {
 		this.#unfollow();
 		this.#pendingManager = void 0;
 		this.#registry.removeEventListener(WEBMCP_CHANGE_EVENT, this.#listener);
+		this.#registry.removeEventListener(WEBMCP_ACTIVATED_EVENT, this.#activated);
+		this.#registry.removeEventListener(WEBMCP_ABORT_EVENT, this.#aborted);
 		for (const held of this.#registrations.values()) held.controller.abort();
 		this.#registrations.clear();
 		this.#emitter.destroy();
@@ -409,6 +439,9 @@ var ModelContext = class {
 	#republish() {
 		this.#emitter.emit("change");
 	}
+	#republishTool(name, event) {
+		if (isWebMCPToolEvent(event)) this.#emitter.emit(name, event.toolName);
+	}
 	#follow(tools, options) {
 		this.#unfollow();
 		const changed = this.#changed.bind(this, tools, options);
@@ -1182,6 +1215,6 @@ function createModelContext(options) {
 	return new ModelContext(host, options);
 }
 //#endregion
-export { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, MessagePortTransport, ModelContext, WEBMCP_CHANGE_EVENT, WebSocketClientTransport, buildWebMCPProjections, collectWebMCPProjections, createHTTPClientTransport, createMessagePortTransport, createModelContext, createPageServer, createScopeMessageListener, createScopeServer, createScopeTransport, createWebSocketClientTransport, describeWebMCPTool, isWebMCPDocument, isWebMCPRegistry, matchesDescriptor, toolAnnotationsToWebMCP, toolToWebMCP, webMCPAnnotationsToTool, webMCPToTool };
+export { DEFAULT_MCP_SERVER_NAME, DEFAULT_MCP_SERVER_VERSION, MessagePortTransport, ModelContext, WEBMCP_ABORT_EVENT, WEBMCP_ACTIVATED_EVENT, WEBMCP_CHANGE_EVENT, WebSocketClientTransport, buildWebMCPProjections, collectWebMCPProjections, createHTTPClientTransport, createMessagePortTransport, createModelContext, createPageServer, createScopeMessageListener, createScopeServer, createScopeTransport, createWebSocketClientTransport, describeWebMCPTool, isWebMCPDocument, isWebMCPRegistry, isWebMCPToolEvent, matchesDescriptor, toolAnnotationsToWebMCP, toolToWebMCP, webMCPAnnotationsToTool, webMCPToTool };
 
 //# sourceMappingURL=index.js.map