Files
archie/ui/src/lib/webmcp.ts
T
sam d55dedab86 feat(webui): publish WebMCP tools for the dashboard
Register the dashboard's own tools with document.modelContext so an in-page
agent can read tasks, events, and daemon health, and recover a stuck task:
list_tasks, get_task, recent_events and daemon_health (read-only), plus
retry_task, stop_task and cancel_task (consequential). The human review gate
(approve/reject) and the destructive verbs (abandon/archive) are deliberately
not exposed.

Every tool calls the same ui/src/lib/api.ts client the interface calls, so the
agent and the UI exercise one set of endpoints, one CSRF header and one error
shape. Registration is framework-agnostic (lib/webmcp.ts machinery,
lib/webmcp-tools.ts list, lib/archie-webmcp.ts the api binding) and no-ops when
document.modelContext is absent, which it is outside the WebMCP origin trial.
Tools returning agent, operator or inbound content carry untrustedContentHint;
only the recovery actions carry consequentialHint.

Verified in system Chrome 152 with --enable-features=WebMCP: seven tools listed
with schemas and annotations, all four read-only tools executed against the live
dashboard, and the flagless run mounts the dashboard with no exception.
2026-09-22 13:53:41 +10:00

82 lines
3.0 KiB
TypeScript

// WebMCP registration for the dashboard.
//
// WebMCP is the browser API an in-page agent uses to discover and call a site's
// own tools. Registration lives here rather than in a component: the tool layer
// talks to the dashboard's HTTP client, so it survives whatever renders it.
//
// The receiver is `document.modelContext` (Chromium 150+). The earlier
// `navigator.modelContext.provideContext({tools})` shape registers nothing in
// shipping Chrome. WebMCP is an origin trial, so an absent modelContext is
// normal rather than an error: registration no-ops and the dashboard is
// unaffected.
/** The annotation hints a WebMCP host reads. */
export interface WebMcpAnnotations {
readOnlyHint?: boolean;
untrustedContentHint?: boolean;
consequentialHint?: boolean;
}
/** One dashboard tool as registered with the browser. */
export interface WebMcpTool {
name: string;
description: string;
inputSchema: Record<string, unknown>;
annotations: WebMcpAnnotations;
execute: (input: Record<string, unknown>) => Promise<unknown> | unknown;
}
/** The part of the ModelContext interface these tools use. */
interface ModelContextLike {
registerTool: (tool: WebMcpTool, options?: { signal?: AbortSignal }) => Promise<void>;
}
/** The outcome of registration: whether it took, and how to undo it. */
export interface WebMcpRegistration {
registered: boolean;
dispose: () => void;
}
function modelContext(): ModelContextLike | undefined {
if (typeof document === "undefined") return undefined;
const context = (document as Document & { modelContext?: ModelContextLike }).modelContext;
return typeof context?.registerTool === "function" ? context : undefined;
}
/**
* Registers tools with the page's model context, returning a registration whose
* `dispose` aborts the shared signal (WebMCP has no unregister method).
*
* A host that rejects one tool does not lose the others; a host that is absent
* is a no-op. Neither is worth failing the dashboard over.
*/
export async function registerWebMcpTools(tools: WebMcpTool[]): Promise<WebMcpRegistration> {
const context = modelContext();
if (!context) return { registered: false, dispose: () => {} };
const controller = new AbortController();
for (const tool of tools) {
try {
await context.registerTool(tool, { signal: controller.signal });
} catch (err) {
console.warn(`webmcp: registering ${tool.name} failed`, err);
}
}
return { registered: true, dispose: () => controller.abort() };
}
/**
* A register function that replaces its previous registration on each call.
* Tool modules re-run under hot reload, and WebMCP has no way to list and
* unregister tools: without this, a reload publishes a second copy of every
* tool.
*/
export function createWebMcpRegistrar(tools: WebMcpTool[]): () => Promise<WebMcpRegistration> {
let current: WebMcpRegistration | undefined;
return async () => {
current?.dispose();
current = await registerWebMcpTools(tools);
return current;
};
}