foldkit-agent-webmcp 0.2.0 → 0.3.0

package/README.md

@@ -1,69 +1,125 @@
 # `foldkit-agent-webmcp`
 
-The browser-native adapter for [`foldkit-agent`](../agent). It projects exposed
-Foldkit Messages into Chrome's experimental WebMCP Imperative API.
+Publishes a [`foldkit-agent`](../agent) runtime as browser-native WebMCP tools.
 
-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.
+Use it when an agent runs **inside the page** and should operate the same live
+Foldkit application the person is using. This package does not define new agent
+capabilities and does not automate the DOM. It translates the capabilities your
+agent contract already exposes into `document.modelContext` tools.
 
 ```text
-browser agent -> document.modelContext -> foldkit-agent-webmcp
-              -> Foldkit AgentRuntime  -> Message -> update -> Model + Commands
+Foldkit application
+       |
+       v
+AssistantAgent              protocol-neutral contract
+       |
+       | AgentBuilder.bind(...)
+       v
+AgentRuntime                live Model + dispatch + policy
+       |
+       v
+foldkit-agent-webmcp        adapter only
+       |
+       v
+document.modelContext      browser tools
+       |
+       v
+Message -> update -> Model + Commands
 ```
 
+The authority boundary stays in `foldkit-agent`: the contract decides what the
+agent may observe and which Messages it may cause. WebMCP only makes those
+capabilities available to a browser-resident agent.
+
+[WebMCP](https://github.com/webmachinelearning/webmcp) is an experimental web
+platform proposal. No stable browser ships it today, so feature detection is
+part of the normal integration path.
+
 ## Install
 
 ```bash
 pnpm add foldkit-agent foldkit-agent-webmcp
 ```
 
-## Usage
+`foldkit`, `effect`, and `foldkit-agent` are peer dependencies.
+
+## Sixty seconds: publish a bound runtime
+
+Assume the application already declared a protocol-neutral contract:
+
+```ts
+const AgentBuilder = Agent.forApplication(App).withPrincipal<Principal>()
+const AssistantAgent = AgentBuilder.make({ ... })
+```
+
+Bind that contract to the running application, then register its currently
+available capabilities with WebMCP:
 
 ```ts
 import { AgentWebMcp } from 'foldkit-agent-webmcp'
 
-const registration = AgentWebMcp.register({ agent: agentRuntime })
+const agentRuntime = AgentBuilder.bind({
+  definition: AssistantAgent,
+  host: {
+    model: mounted.model,
+    dispatch: message => mounted.dispatch(message),
+    subscribe: mounted.subscribe,
+    observe: mounted.observe, // required only by capabilities with completion contracts
+  },
+})
+
+const modelContext = AgentWebMcp.documentModelContext()
+
+if (modelContext !== undefined) {
+  const registration = AgentWebMcp.register({
+    agent: agentRuntime,
+    modelContext,
+  })
+
+  window.addEventListener('beforeunload', () => registration.unregister())
+}
 ```
 
-[examples/todo](../../examples/todo) registers a real contract and executes the
-resulting tools.
+That is the whole architecture: the contract remains protocol-neutral, the
+runtime remains the one authority for availability/authorization/dispatch, and
+this package translates it to the browser API.
 
-`agent` is the `AgentRuntime` returned by `Agent.bind(...)`.
+`documentModelContext()` is safe during SSR and returns `undefined` when no
+WebMCP producer surface exists. Calling `register()` without a model context
+throws rather than silently pretending registration succeeded.
 
-Each currently available capability becomes one tool:
+Registration starts immediately, but browser registration is asynchronous.
+`register()` returns after reconciliation is scheduled; use
+`await registration.refresh()` when the caller needs to know that the browser
+has accepted the current tool set, and `onError` for background reconcile
+failures.
 
-```text
-capability name     -> tool name
-variant description -> description
-derived JSON Schema -> inputSchema
-Runtime dispatch    -> execute
-```
+## What a capability becomes
 
-No schema or handler is repeated in this package.
+Each **currently available** capability becomes one WebMCP tool:
 
-### Options
+```text
+foldkit-agent                    WebMCP
 
-| 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. |
-| `invocationId` | `crypto.randomUUID()` | Supplies the invocation id. |
-| `onError` | — | Reports a failure from a reconcile no caller is awaiting. |
+capability name          ->      tool name
+variant description      ->      description
+encoded input Schema     ->      inputSchema
+AgentRuntime dispatch    ->      execute
+completion contract      ->      resolved tool outcome
+```
 
-### Returned registration
+No input schema or handler is written again. `execute` delegates to the bound
+runtime, which performs the same decode, availability check, authorization,
+dispatch, cancellation, and completion handling as every other adapter.
 
-```ts
-registration.refresh()     // reconcile against the current Model
-registration.registered()  // capability names currently registered
-registration.unregister()  // abort every registration and stop following
-```
+A capability with a completion contract resolves when its correlated success or
+failure Message is observed. Without one, validated dispatch is the completion
+boundary.
 
-## Dynamic availability
+## Tools follow the Model
 
-Tool availability is a projection of Model state, which falls out of TEA:
+Availability is Model-dependent, so the advertised WebMCP tool set may change as
+the application changes:
 
 ```ts
 RequestedDeleteTodo: {
@@ -74,32 +130,52 @@ RequestedDeleteTodo: {
 ```
 
 ```text
-Todo list          tools: create_todo
-user selects todo  -> Model changes
-                   -> tools: create_todo, delete_todo
+no selection       tools: create_todo
+       |
+user selects todo
+       v
+selected todo      tools: create_todo, delete_todo
 ```
 
-The adapter holds one `AbortController` per registered tool and passes its
-signal in the options bag, where `registerTool` takes it:
+With `followModel: true` (the default) and a host with `subscribe`, a Model
+change reconciles registrations. A capability that disappears is unregistered;
+a newly available capability is registered.
+
+Availability is stronger than discoverability. A capability absent from the
+tool list is also refused if a caller somehow invokes its known name.
+
+Reconciliation is serialized, so overlapping Model changes cannot register the
+same capability twice. A failed browser registration is not recorded as live and
+is retried on a later reconcile.
+
+## Registration lifecycle
+
+`AgentWebMcp.register` returns:
 
 ```ts
-await document.modelContext.registerTool(tool, { signal: controller.signal })
+registration.registered()  // capability names currently registered
+await registration.refresh() // reconcile against the current Model
+registration.unregister()  // stop following and abort every registration
 ```
 
-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`.
+The main options are:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `agent` | — | The bound `AgentRuntime`. |
+| `modelContext` | `document.modelContext` | Producer surface to register against; pass a stand-in in tests. |
+| `followModel` | `true` | Reconcile tools as capability availability changes. |
+| `signal` | — | Unregister everything when aborted. |
+| `invocationId` | `crypto.randomUUID()` | Supplies protocol invocation ids. |
+| `onError` | — | Receives failures from background reconciliation. |
 
-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.
+Each registered tool has its own registration `AbortController`. That signal is
+for the WebMCP registration itself. It is distinct from a tool invocation's
+execution signal, which is forwarded to `AgentRuntime` as `Invocation.signal`.
 
 ## Errors
 
-A dispatch failure is returned as a tool error rather than thrown, so the
-calling agent can act on it:
+Application refusals become tool errors the calling agent can reason about:
 
 ```text
 No such capability: delete_todo
@@ -109,12 +185,52 @@ Invalid input for "create_todo"
 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` does not expose underlying application errors to the caller. A host or
+adapter defect is flattened to a generic failure; the detailed error stays in
+the application.
+
+## Testing without a browser
+
+`modelContext` is the only browser-specific seam this package needs. Pass an
+object with `registerTool` to capture descriptors and invoke their `execute`
+functions directly:
+
+```ts
+const registration = AgentWebMcp.register({
+  agent: agentRuntime,
+  modelContext: fakeModelContext,
+})
+
+await registration.refresh()
+```
+
+That is how the package test suite and [`examples/todo`](../../examples/todo)
+exercise the real adapter path without requiring browser support.
+
+[`examples/todo-app`](../../examples/todo-app) shows the same adapter attached to
+a real local-first Foldkit application.
+
+## Choosing an adapter
+
+All four adapters serve the same `AssistantAgent` contract through a bound
+runtime. Serving more than one does not duplicate capability declarations.
+
+| 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`](../agent-mcp) |
+| Another agent, over A2A | [`foldkit-agent-a2a`](../agent-a2a) |
+| An Agent Native host | [`foldkit-agent-native`](../agent-native) |
 
 ## 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 may change independently of Foldkit Plus. Its browser
+shape is intentionally isolated here. If the proposal changes, this adapter can
+change without changing the protocol-neutral `foldkit-agent` contract or the
+application's Messages.
+
+## See also
+
+- [Agents guide](../../docs/agents.md) — the full builder → contract → runtime mental model.
+- [`foldkit-agent`](../agent) — declares and binds the contract this package serves.
+- [WebMCP](https://github.com/webmachinelearning/webmcp) — the browser proposal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldkit-agent-webmcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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.2.0"
+    "foldkit-agent": "^0.3.0"
   },
   "dependencies": {},
   "devDependencies": {
@@ -47,7 +47,7 @@
     "foldkit": "0.158.2",
     "tsdown": "^0.23.0",
     "typescript": "^5.7.2",
-    "foldkit-agent": "0.2.0"
+    "foldkit-agent": "0.3.0"
   },
   "scripts": {
     "build": "tsdown",