Agent / foldkit-agent-webmcp

Registration lifecycle

AgentWebMcp.register returns:

registration.registered()  // capability names currently registered
await registration.refresh() // reconcile against the current Model
registration.unregister()  // stop following and abort every registration

The main options are:

Option	Default	Purpose
`agent`	—	The bound `AgentRuntime`.
`modelContext`	`pageModelContext()`	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.
`forms`	—	Capabilities drawn as forms (`formTool`): agent submissions are answered, and declarative browsers get no second, imperative tool.

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

Application refusals become tool errors the calling agent can reason about:

No such capability: delete_todo
Capability "delete_todo" is not available right now
Not authorized to invoke "delete_todo"
Invalid input for "create_todo"
Capability "create_todo" failed unexpectedly

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:

const registration = AgentWebMcp.register({
  agent: agentRuntime,
  modelContext: fakeModelContext,
})

await registration.refresh()

That is how the package test suite and examples/todo exercise the real adapter path without requiring browser support.

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`
Another agent, over A2A	`foldkit-agent-a2a`
An Agent Native host	`foldkit-agent-native`

Why this stays an adapter

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.

Errors#

Testing without a browser#

Choosing an adapter#

Why this stays an adapter#

See also#

Errors

Testing without a browser

Choosing an adapter

Why this stays an adapter

See also