foldkit-agent-webmcp 0.1.0 → 0.2.1

package/README.md

@@ -1,37 +1,82 @@
 # `foldkit-agent-webmcp`
 
-The browser-native adapter for [`foldkit-agent`](../agent). It projects exposed
-Foldkit Messages into Chrome's experimental WebMCP Imperative API.
+Turns a [`foldkit-agent`](https://github.com/doeixd/foldkit-plus/tree/main/packages/agent)
+contract into browser tools, so an agent running **inside the page** can use the
+application the person in front of it is already using.
 
-WebMCP runs in the page itself, so a tool's `execute` dispatches directly into
-the same live Foldkit Runtime the human is already using — no DOM automation,
-and no external browser-session bridge.
+[WebMCP](https://github.com/webmachinelearning/webmcp) is an experimental web
+platform proposal: a page publishes tools on `document.modelContext`, and a
+browser-resident agent calls them. Because the tool runs in the page, its
+`execute` dispatches a Message straight into the live Foldkit Runtime. There is
+no DOM automation, no scraping, no second copy of the application's logic, and
+no browser-session bridge.
 
 ```text
 browser agent -> document.modelContext -> foldkit-agent-webmcp
               -> Foldkit AgentRuntime  -> Message -> update -> Model + Commands
 ```
 
+The agent can only do what the contract exposes, and the contract only exposes
+Messages `update` already handles. Everything an agent may see or do is decided
+in `foldkit-agent`; this package translates and nothing else.
+
 ## Install
 
 ```bash
 pnpm add foldkit-agent foldkit-agent-webmcp
 ```
 
+`foldkit`, `effect`, and `foldkit-agent` are peer dependencies.
+
 ## Usage
 
+The whole path, from a declared contract to live tools:
+
 ```ts
 import { AgentWebMcp } from 'foldkit-agent-webmcp'
 
-const registration = AgentWebMcp.register({ agent: agentRuntime })
+// 1. Bind the contract to the running application. `TodoAgent` is
+//    `Agent.forApplication(App)`, or `Agent.forModel<Model>()` without one.
+const agent = TodoAgent.bind({
+  definition: AppAgent,
+  host: {
+    model: mounted.model,
+    dispatch: (message: Message) => {
+      mounted.dispatch(message)
+    },
+    subscribe: mounted.subscribe, // lets tools appear and disappear with the Model
+    observe: mounted.observe, // required by a capability with a completion contract
+  },
+})
+
+// 2. Publish it, if this browser speaks WebMCP.
+const modelContext = AgentWebMcp.documentModelContext()
+if (modelContext !== undefined) {
+  const registration = AgentWebMcp.register({ agent, modelContext })
+  window.addEventListener('beforeunload', () => registration.unregister())
+}
 ```
 
-[examples/todo](../../examples/todo) registers a real contract and executes the
-resulting tools.
+**Check for support first.** WebMCP ships in no stable browser today, so
+`document.modelContext` is usually absent. `documentModelContext()` returns it
+or `undefined`, and is safe on a server, where there is no `document` at all.
+Calling `register()` without a model context **throws**, on the grounds that
+silently registering nothing would look like a working integration. Feature-detect,
+or pass a `modelContext` of your own.
 
-`agent` is the `AgentRuntime` returned by `Agent.bind(...)`.
+Registration begins immediately and in the background: `register` returns as
+soon as the reconcile is scheduled, not when the browser has accepted the tools.
+Pass `onError` to hear about a failure in that first pass, or `await
+registration.refresh()` when you want to know the tools are live.
 
-Each currently available capability becomes one tool:
+[`examples/todo`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo)
+registers a real contract and executes the resulting tools;
+[`examples/todo-app`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo-app)
+does it in a real browser over a local-first replica.
+
+## What a capability becomes
+
+Each **currently available** capability becomes one tool:
 
 ```text
 capability name     -> tool name
@@ -40,30 +85,35 @@ derived JSON Schema -> inputSchema
 Runtime dispatch    -> execute
 ```
 
-No schema or handler is repeated in this package.
+No schema and no handler is written twice. `execute` decodes its input through
+the capability's own Effect Schema, runs `available` and `authorize`, and
+dispatches; a capability with a `completion` contract resolves when the
+correlated Message is applied, so the agent learns the outcome rather than that
+the call was received.
 
 ### Options
 
 | Option | Default | Purpose |
 | --- | --- | --- |
 | `agent` | — | The bound `AgentRuntime`. |
-| `modelContext` | `document.modelContext` | The WebMCP producer surface. |
-| `signal` | — | Unregisters everything when aborted. |
-| `followModel` | `true` | Reconcile registrations as the Model changes. |
+| `modelContext` | `document.modelContext` | The WebMCP producer surface. Pass one to target a different surface, or to drive the adapter in a test. |
+| `signal` | — | Unregisters everything when aborted. An already-aborted signal unregisters at once. |
+| `followModel` | `true` | Reconcile registrations as the Model changes. Inert unless the host supports `subscribe`. |
 | `invocationId` | `crypto.randomUUID()` | Supplies the invocation id. |
-| `onError` | — | Reports a failure from a reconcile no caller is awaiting. |
+| `onError` | — | Reports a failure from a reconcile no caller is awaiting: the initial registration, or one a Model change triggered. |
 
-### Returned registration
+### The returned registration
 
 ```ts
-registration.refresh()     // reconcile against the current Model
-registration.registered()  // capability names currently registered
-registration.unregister()  // abort every registration and stop following
+registration.refresh() // Promise: reconcile against the current Model
+registration.registered() // the capability names currently registered
+registration.unregister() // abort every registration and stop following
 ```
 
-## Dynamic availability
+## Tools appear and disappear with the Model
 
-Tool availability is a projection of Model state, which falls out of TEA:
+Availability is a projection of Model state, which falls out of the
+architecture rather than needing its own mechanism:
 
 ```ts
 RequestedDeleteTodo: {
@@ -79,6 +129,12 @@ user selects todo  -> Model changes
                    -> tools: create_todo, delete_todo
 ```
 
+With `followModel` left on and a host that supports `subscribe`, every
+transition reconciles the registrations: capabilities that are gone have their
+registration signal aborted, and capabilities that have appeared are registered.
+Availability is stronger than visibility. A capability the Model does not
+currently offer is absent from the tool list **and** refused if called by name.
+
 The adapter holds one `AbortController` per registered tool and passes its
 signal in the options bag, where `registerTool` takes it:
 
@@ -88,18 +144,20 @@ await document.modelContext.registerTool(tool, { signal: controller.signal })
 
 Aborting that signal is what unregisters the tool, so it must not go on the
 descriptor. This is the registration signal, distinct from the execution signal
-passed to `execute`, which is forwarded as `Invocation.signal`.
+passed to `execute`, which is forwarded as `Invocation.signal` so an agent can
+cancel a call in flight.
 
 Reconciles are serialized, and a capability is recorded as registered only once
-`registerTool` resolves. A registration the browser refuses is not recorded and
-is retried on the next reconcile; `refresh()` rejects with the first failure
-after attempting the rest. Nothing is registered once `unregister()` has run,
-and a registration that was in flight when it ran is aborted.
+`registerTool` resolves, so two overlapping reconciles cannot register one tool
+twice. A registration the browser refuses is not recorded and is retried on the
+next reconcile; `refresh()` rejects with the first failure after attempting the
+rest. Nothing is registered once `unregister()` has run, and a registration that
+was in flight when it ran is aborted.
 
 ## Errors
 
-A dispatch failure is returned as a tool error rather than thrown, so the
-calling agent can act on it:
+A dispatch failure comes back as a tool error rather than a rejection, so the
+calling agent can read it and decide what to do:
 
 ```text
 No such capability: delete_todo
@@ -110,11 +168,41 @@ Capability "create_todo" failed unexpectedly
 ```
 
 The last covers an unexpected defect, such as the host's `dispatch` throwing.
-`execute` never rejects and never echoes the underlying error back to the
-caller.
+`execute` never rejects, and never echoes the underlying error back to the
+caller: the detail stays in the application, and the agent gets a message
+written for it.
+
+## Testing without a browser
+
+`modelContext` is the only thing this package needs from the platform, so pass
+your own object with a `registerTool` method to capture the descriptors and call
+their `execute` directly. That is how this package's own suite and
+[`examples/todo`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo)
+exercise the real registration path with no browser involved.
+
+## Choosing an adapter
+
+| Where the agent runs | Adapter |
+| --- | --- |
+| In the page, beside the user | `foldkit-agent-webmcp` |
+| An external MCP client, over stdio or HTTP | [`foldkit-agent-mcp`](https://github.com/doeixd/foldkit-plus/tree/main/packages/agent-mcp) |
+| Another agent, over A2A | [`foldkit-agent-a2a`](https://github.com/doeixd/foldkit-plus/tree/main/packages/agent-a2a) |
+| An Agent Native host | [`foldkit-agent-native`](https://github.com/doeixd/foldkit-plus/tree/main/packages/agent-native) |
+
+They share one contract, so serving two at once is two calls, not two
+definitions.
 
 ## Why this stays an adapter
 
-WebMCP is experimental and evolving. The types it needs are declared locally in
-`src/webmcp.ts` rather than imported, so the browser API can change without the
-Foldkit agent contract changing with it.
+WebMCP is experimental and still changing. The types it needs are declared
+locally in `src/webmcp.ts` rather than imported, so the browser API can move
+without the Foldkit agent contract moving with it. If the proposal changes
+shape, this package changes and nothing else does.
+
+## See also
+
+- [The agents guide](https://github.com/doeixd/foldkit-plus/blob/main/docs/agents.md)
+  — what an agent may see and do, and why a capability is a Message.
+- [`foldkit-agent`](https://github.com/doeixd/foldkit-plus/tree/main/packages/agent)
+  — the contract this adapter serves.
+- [WebMCP](https://github.com/webmachinelearning/webmcp) — the proposal.

package/dist/index.mjs

@@ -52,9 +52,8 @@ const register = (options) => {
 					signal: context.signal
 				})));
 				if (result._tag === "Failure") return textResult(result.failure.message, true);
-				const { completion } = result.success;
-				if (completion === void 0) return textResult(`Dispatched ${result.success.tag}`);
-				return textResult(`${completion.status === "completed" ? "Completed" : "Failed"}: ${completion.message._tag}`, completion.status === "failed");
+				const summary = Agent.summarize(result.success);
+				return textResult(summary.text, !summary.ok);
 			} catch {
 				return textResult(`Capability "${name}" failed unexpectedly`, true);
 			}

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/webmcp.ts","../src/register.ts","../src/agentWebMcp.ts"],"sourcesContent":["/**\n * The slice of Chrome's experimental WebMCP Imperative API this adapter uses.\n *\n * These types are declared locally rather than imported: the API is still\n * experimental, and Foldkit should not be coupled to a browser proposal that is\n * still changing.\n */\n\n/** Metadata passed to a tool's `execute` function. */\nexport interface ToolExecutionContext {\n  /** Cancellation for this invocation: is this call still wanted? */\n  readonly signal?: AbortSignal | undefined\n}\n\n/** The value a WebMCP tool returns. */\nexport interface ToolResult {\n  readonly content: ReadonlyArray<{ readonly type: 'text'; readonly text: string }>\n  readonly isError?: boolean\n}\n\n/** A tool registration as accepted by `document.modelContext.registerTool`. */\nexport interface ToolDescriptor {\n  readonly name: string\n  readonly description: string\n  readonly inputSchema: Record<string, unknown>\n  readonly execute: (input: any, context: ToolExecutionContext) => Promise<ToolResult>\n}\n\n/**\n * Options accepted alongside a tool registration.\n *\n * The registration signal belongs here, not on the descriptor: aborting it is\n * how the documented API unregisters a tool.\n */\nexport interface RegisterToolOptions {\n  readonly signal?: AbortSignal | undefined\n}\n\n/** The producer surface exposed on `document.modelContext`. */\nexport interface ModelContext {\n  readonly registerTool: (\n    tool: ToolDescriptor,\n    options?: RegisterToolOptions,\n  ) => void | Promise<unknown>\n}\n\n/** Reads `document.modelContext`, when the page provides it. */\nexport const documentModelContext = (): ModelContext | undefined => {\n  if (typeof document === 'undefined') return undefined\n  return (document as unknown as { modelContext?: ModelContext }).modelContext\n}\n","import { Agent } from 'foldkit-agent'\nimport { Effect } from 'effect'\nimport {\n  type ModelContext,\n  type ToolDescriptor,\n  type ToolResult,\n  documentModelContext,\n} from './webmcp.js'\n\n/** A live WebMCP registration. */\nexport interface Registration {\n  /** Re-reads availability from the current Model and reconciles registrations. */\n  readonly refresh: () => Promise<void>\n  /** Unregisters every tool and stops following the Model. */\n  readonly unregister: () => void\n  /** The capability names currently registered with WebMCP. */\n  readonly registered: () => ReadonlyArray<string>\n}\n\nexport interface RegisterOptions<Model, Context_, Principal, ByName, ByTag> {\n  /** The agent contract bound to a live Foldkit Runtime. */\n  readonly agent: Agent.AgentRuntime<Model, Context_, Principal, ByName, ByTag>\n  /** Defaults to `document.modelContext`. */\n  readonly modelContext?: ModelContext | undefined\n  /** Unregisters everything when aborted. */\n  readonly signal?: AbortSignal | undefined\n  /**\n   * Follow the live Model and reconcile registrations as `available(model)`\n   * changes. Defaults to `true`, and is inert unless the host supports\n   * subscription.\n   */\n  readonly followModel?: boolean | undefined\n  /** Supplies an invocation id. Defaults to `crypto.randomUUID()`. */\n  readonly invocationId?: (() => string) | undefined\n  /**\n   * Reports a failure from a reconcile that no caller is awaiting -- the\n   * initial registration, or one triggered by a Model change.\n   */\n  readonly onError?: ((error: unknown) => void) | undefined\n}\n\nconst textResult = (text: string, isError = false): ToolResult => ({\n  content: [{ type: 'text', text }],\n  isError,\n})\n\n/**\n * Projects an agent contract into `document.modelContext.registerTool(...)`.\n *\n * Each currently available capability becomes one tool: the capability name\n * becomes the tool name, the variant description becomes the description, the\n * derived JSON Schema becomes `inputSchema`, and `execute` validates its input\n * and dispatches into the same live Foldkit Runtime the human is using.\n *\n * Tool availability is itself a projection of Model state. When\n * `available(model)` changes, registrations are reconciled: capabilities that\n * are gone have their registration signal aborted, and capabilities that have\n * appeared are registered.\n *\n * @example\n * ```ts\n * const registration = AgentWebMcp.register({ agent: agentRuntime })\n * ```\n */\nexport const register = <Model, Context_, Principal, ByName, ByTag>(\n  options: RegisterOptions<Model, Context_, Principal, ByName, ByTag>,\n): Registration => {\n  const modelContext = options.modelContext ?? documentModelContext()\n  if (modelContext === undefined) {\n    throw new Error(\n      'WebMCP is unavailable: no document.modelContext. Pass an explicit modelContext to register().',\n    )\n  }\n\n  const { agent } = options\n  const nextInvocationId = options.invocationId ?? Agent.newInvocationId\n\n  /** One AbortController per registered tool: aborting it unregisters that tool. */\n  const controllers = new Map<string, AbortController>()\n  let disposed = false\n\n  const toolFor = (\n    name: string,\n    description: string,\n    inputSchema: Record<string, unknown>,\n  ): { readonly controller: AbortController; readonly tool: ToolDescriptor } => {\n    const controller = new AbortController()\n\n    const execute = async (\n      input: unknown,\n      context: { readonly signal?: AbortSignal | undefined },\n    ): Promise<ToolResult> => {\n      try {\n        // WebMCP hands the page a promise-returning callback, so this is the\n        // edge where Effect meets the browser, not a run inside a service.\n        const result = await Effect.runPromise(\n          Effect.result(\n            // The tool name and payload both come off the wire.\n            agent.messages.dispatchUnknown(name, input, {\n              id: nextInvocationId(),\n              transport: 'webmcp',\n              signal: context.signal,\n            }),\n          ),\n        )\n\n        // Every agent failure carries a message written for this audience.\n        if (result._tag === 'Failure') return textResult(result.failure.message, true)\n\n        // A declared completion contract has already resolved by the time\n        // dispatch returns, so a failed completion is a failed tool call --\n        // reported the same way the MCP adapter reports it.\n        const { completion } = result.success\n        if (completion === undefined) return textResult(`Dispatched ${result.success.tag}`)\n\n        return textResult(\n          `${completion.status === 'completed' ? 'Completed' : 'Failed'}: ${completion.message._tag}`,\n          completion.status === 'failed',\n        )\n      } catch {\n        // `Effect.result` captures expected failures but not defects, and a\n        // rejected tool promise is not something a calling agent can act on.\n        // Report it as a tool error without leaking the application's internals.\n        return textResult(`Capability \"${name}\" failed unexpectedly`, true)\n      }\n    }\n\n    return { controller, tool: { name, description, inputSchema, execute } }\n  }\n\n  const runReconcile = async (): Promise<void> => {\n    if (disposed) return\n\n    const available = await Effect.runPromise(agent.messages.available)\n    const wanted = new Map(available.map(descriptor => [descriptor.name, descriptor]))\n\n    // Unregister capabilities the Model no longer offers.\n    for (const [name, controller] of [...controllers]) {\n      if (!wanted.has(name)) {\n        controller.abort()\n        controllers.delete(name)\n      }\n    }\n\n    // Register capabilities that have appeared.\n    let failure: unknown\n    for (const [name, descriptor] of wanted) {\n      // unregister() can land while an await above is pending. Nothing more is\n      // registered after that.\n      if (disposed) return\n      if (controllers.has(name)) continue\n\n      const { controller, tool } = toolFor(name, descriptor.description, descriptor.inputSchema)\n\n      try {\n        // The signal goes in the options bag: aborting it is what unregisters\n        // the tool.\n        await modelContext.registerTool(tool, { signal: controller.signal })\n      } catch (error) {\n        // Nothing was registered, so nothing is recorded and nothing to abort.\n        failure ??= error\n        continue\n      }\n\n      // Disposal can also land while this registration is in flight, in which\n      // case the tool is already registered and has to be taken back.\n      if (disposed) {\n        controller.abort()\n        return\n      }\n\n      // Recorded only once the browser has accepted it.\n      controllers.set(name, controller)\n    }\n\n    if (failure !== undefined) throw failure\n  }\n\n  /**\n   * Reconciles are serialized.\n   *\n   * A capability is recorded only once the browser has accepted it, so two\n   * overlapping reconciles would both see it as missing and register it twice.\n   */\n  let queue: Promise<void> = Promise.resolve()\n\n  const reconcile = (): Promise<void> => {\n    const next = queue.then(runReconcile, runReconcile)\n    queue = next.then(\n      () => {},\n      () => {},\n    )\n    return next\n  }\n\n  let unsubscribe: () => void = () => {}\n\n  const unregister = (): void => {\n    disposed = true\n    for (const controller of controllers.values()) controller.abort()\n    controllers.clear()\n    unsubscribe()\n  }\n\n  /**\n   * Reconciles without a caller to await the result. A rejection here would\n   * otherwise become an unhandled rejection, so it is reported through\n   * `onError` and the registration is left as it was.\n   */\n  const reconcileInBackground = (): void => {\n    reconcile().catch(error => {\n      options.onError?.(error)\n    })\n  }\n\n  reconcileInBackground()\n\n  if (options.followModel !== false) {\n    unsubscribe = agent.subscribe(reconcileInBackground)\n  }\n\n  if (options.signal?.aborted === true) {\n    // An already-aborted signal never fires its listener.\n    unregister()\n  } else {\n    options.signal?.addEventListener('abort', unregister, { once: true })\n  }\n\n  return {\n    refresh: reconcile,\n    unregister,\n    registered: () => [...controllers.keys()],\n  }\n}\n","export { register, type RegisterOptions, type Registration } from './register.js'\nexport { documentModelContext } from './webmcp.js'\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/webmcp.ts","../src/register.ts","../src/agentWebMcp.ts"],"sourcesContent":["/**\n * The slice of Chrome's experimental WebMCP Imperative API this adapter uses.\n *\n * These types are declared locally rather than imported: the API is still\n * experimental, and Foldkit should not be coupled to a browser proposal that is\n * still changing.\n */\n\n/** Metadata passed to a tool's `execute` function. */\nexport interface ToolExecutionContext {\n  /** Cancellation for this invocation: is this call still wanted? */\n  readonly signal?: AbortSignal | undefined\n}\n\n/** The value a WebMCP tool returns. */\nexport interface ToolResult {\n  readonly content: ReadonlyArray<{ readonly type: 'text'; readonly text: string }>\n  readonly isError?: boolean\n}\n\n/** A tool registration as accepted by `document.modelContext.registerTool`. */\nexport interface ToolDescriptor {\n  readonly name: string\n  readonly description: string\n  readonly inputSchema: Record<string, unknown>\n  readonly execute: (input: any, context: ToolExecutionContext) => Promise<ToolResult>\n}\n\n/**\n * Options accepted alongside a tool registration.\n *\n * The registration signal belongs here, not on the descriptor: aborting it is\n * how the documented API unregisters a tool.\n */\nexport interface RegisterToolOptions {\n  readonly signal?: AbortSignal | undefined\n}\n\n/** The producer surface exposed on `document.modelContext`. */\nexport interface ModelContext {\n  readonly registerTool: (\n    tool: ToolDescriptor,\n    options?: RegisterToolOptions,\n  ) => void | Promise<unknown>\n}\n\n/** Reads `document.modelContext`, when the page provides it. */\nexport const documentModelContext = (): ModelContext | undefined => {\n  if (typeof document === 'undefined') return undefined\n  return (document as unknown as { modelContext?: ModelContext }).modelContext\n}\n","import { Agent } from 'foldkit-agent'\nimport { Effect } from 'effect'\nimport {\n  type ModelContext,\n  type ToolDescriptor,\n  type ToolResult,\n  documentModelContext,\n} from './webmcp.js'\n\n/** A live WebMCP registration. */\nexport interface Registration {\n  /** Re-reads availability from the current Model and reconciles registrations. */\n  readonly refresh: () => Promise<void>\n  /** Unregisters every tool and stops following the Model. */\n  readonly unregister: () => void\n  /** The capability names currently registered with WebMCP. */\n  readonly registered: () => ReadonlyArray<string>\n}\n\nexport interface RegisterOptions<Model, Context_, Principal, ByName, ByTag> {\n  /** The agent contract bound to a live Foldkit Runtime. */\n  readonly agent: Agent.AgentRuntime<Model, Context_, Principal, ByName, ByTag>\n  /** Defaults to `document.modelContext`. */\n  readonly modelContext?: ModelContext | undefined\n  /** Unregisters everything when aborted. */\n  readonly signal?: AbortSignal | undefined\n  /**\n   * Follow the live Model and reconcile registrations as `available(model)`\n   * changes. Defaults to `true`, and is inert unless the host supports\n   * subscription.\n   */\n  readonly followModel?: boolean | undefined\n  /** Supplies an invocation id. Defaults to `crypto.randomUUID()`. */\n  readonly invocationId?: (() => string) | undefined\n  /**\n   * Reports a failure from a reconcile that no caller is awaiting -- the\n   * initial registration, or one triggered by a Model change.\n   */\n  readonly onError?: ((error: unknown) => void) | undefined\n}\n\nconst textResult = (text: string, isError = false): ToolResult => ({\n  content: [{ type: 'text', text }],\n  isError,\n})\n\n/**\n * Projects an agent contract into `document.modelContext.registerTool(...)`.\n *\n * Each currently available capability becomes one tool: the capability name\n * becomes the tool name, the variant description becomes the description, the\n * derived JSON Schema becomes `inputSchema`, and `execute` validates its input\n * and dispatches into the same live Foldkit Runtime the human is using.\n *\n * Tool availability is itself a projection of Model state. When\n * `available(model)` changes, registrations are reconciled: capabilities that\n * are gone have their registration signal aborted, and capabilities that have\n * appeared are registered.\n *\n * @example\n * ```ts\n * const registration = AgentWebMcp.register({ agent: agentRuntime })\n * ```\n */\nexport const register = <Model, Context_, Principal, ByName, ByTag>(\n  options: RegisterOptions<Model, Context_, Principal, ByName, ByTag>,\n): Registration => {\n  const modelContext = options.modelContext ?? documentModelContext()\n  if (modelContext === undefined) {\n    throw new Error(\n      'WebMCP is unavailable: no document.modelContext. Pass an explicit modelContext to register().',\n    )\n  }\n\n  const { agent } = options\n  const nextInvocationId = options.invocationId ?? Agent.newInvocationId\n\n  /** One AbortController per registered tool: aborting it unregisters that tool. */\n  const controllers = new Map<string, AbortController>()\n  let disposed = false\n\n  const toolFor = (\n    name: string,\n    description: string,\n    inputSchema: Record<string, unknown>,\n  ): { readonly controller: AbortController; readonly tool: ToolDescriptor } => {\n    const controller = new AbortController()\n\n    const execute = async (\n      input: unknown,\n      context: { readonly signal?: AbortSignal | undefined },\n    ): Promise<ToolResult> => {\n      try {\n        // WebMCP hands the page a promise-returning callback, so this is the\n        // edge where Effect meets the browser, not a run inside a service.\n        const result = await Effect.runPromise(\n          Effect.result(\n            // The tool name and payload both come off the wire.\n            agent.messages.dispatchUnknown(name, input, {\n              id: nextInvocationId(),\n              transport: 'webmcp',\n              signal: context.signal,\n            }),\n          ),\n        )\n\n        // Every agent failure carries a message written for this audience.\n        if (result._tag === 'Failure') return textResult(result.failure.message, true)\n\n        // A declared completion contract has already resolved by the time\n        // dispatch returns, so a failed completion is a failed tool call.\n        const summary = Agent.summarize(result.success)\n        return textResult(summary.text, !summary.ok)\n      } catch {\n        // `Effect.result` captures expected failures but not defects, and a\n        // rejected tool promise is not something a calling agent can act on.\n        // Report it as a tool error without leaking the application's internals.\n        return textResult(`Capability \"${name}\" failed unexpectedly`, true)\n      }\n    }\n\n    return { controller, tool: { name, description, inputSchema, execute } }\n  }\n\n  const runReconcile = async (): Promise<void> => {\n    if (disposed) return\n\n    const available = await Effect.runPromise(agent.messages.available)\n    const wanted = new Map(available.map(descriptor => [descriptor.name, descriptor]))\n\n    // Unregister capabilities the Model no longer offers.\n    for (const [name, controller] of [...controllers]) {\n      if (!wanted.has(name)) {\n        controller.abort()\n        controllers.delete(name)\n      }\n    }\n\n    // Register capabilities that have appeared.\n    let failure: unknown\n    for (const [name, descriptor] of wanted) {\n      // unregister() can land while an await above is pending. Nothing more is\n      // registered after that.\n      if (disposed) return\n      if (controllers.has(name)) continue\n\n      const { controller, tool } = toolFor(name, descriptor.description, descriptor.inputSchema)\n\n      try {\n        // The signal goes in the options bag: aborting it is what unregisters\n        // the tool.\n        await modelContext.registerTool(tool, { signal: controller.signal })\n      } catch (error) {\n        // Nothing was registered, so nothing is recorded and nothing to abort.\n        failure ??= error\n        continue\n      }\n\n      // Disposal can also land while this registration is in flight, in which\n      // case the tool is already registered and has to be taken back.\n      if (disposed) {\n        controller.abort()\n        return\n      }\n\n      // Recorded only once the browser has accepted it.\n      controllers.set(name, controller)\n    }\n\n    if (failure !== undefined) throw failure\n  }\n\n  /**\n   * Reconciles are serialized.\n   *\n   * A capability is recorded only once the browser has accepted it, so two\n   * overlapping reconciles would both see it as missing and register it twice.\n   */\n  let queue: Promise<void> = Promise.resolve()\n\n  const reconcile = (): Promise<void> => {\n    const next = queue.then(runReconcile, runReconcile)\n    queue = next.then(\n      () => {},\n      () => {},\n    )\n    return next\n  }\n\n  let unsubscribe: () => void = () => {}\n\n  const unregister = (): void => {\n    disposed = true\n    for (const controller of controllers.values()) controller.abort()\n    controllers.clear()\n    unsubscribe()\n  }\n\n  /**\n   * Reconciles without a caller to await the result. A rejection here would\n   * otherwise become an unhandled rejection, so it is reported through\n   * `onError` and the registration is left as it was.\n   */\n  const reconcileInBackground = (): void => {\n    reconcile().catch(error => {\n      options.onError?.(error)\n    })\n  }\n\n  reconcileInBackground()\n\n  if (options.followModel !== false) {\n    unsubscribe = agent.subscribe(reconcileInBackground)\n  }\n\n  if (options.signal?.aborted === true) {\n    // An already-aborted signal never fires its listener.\n    unregister()\n  } else {\n    options.signal?.addEventListener('abort', unregister, { once: true })\n  }\n\n  return {\n    refresh: reconcile,\n    unregister,\n    registered: () => [...controllers.keys()],\n  }\n}\n","export { register, type RegisterOptions, type Registration } from './register.js'\nexport { documentModelContext } from './webmcp.js'\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldkit-agent-webmcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "WebMCP adapter for foldkit-agent. Projects exposed Foldkit Messages into document.modelContext tools.",
   "keywords": [
     "foldkit",
@@ -39,7 +39,7 @@
   "peerDependencies": {
     "effect": "^4.0.0-rc.112",
     "foldkit": "^0.158.2",
-    "foldkit-agent": "^0.1.0"
+    "foldkit-agent": "^0.2.1"
   },
   "dependencies": {},
   "devDependencies": {
@@ -47,7 +47,7 @@
     "foldkit": "0.158.2",
     "tsdown": "^0.23.0",
     "typescript": "^5.7.2",
-    "foldkit-agent": "0.1.0"
+    "foldkit-agent": "0.2.1"
   },
   "scripts": {
     "build": "tsdown",