feat: eagerly expose in-page tools to browser agents (#376)

Co-authored-by: agent <agent@opencode>
Co-authored-by: Anthony Fu (via agent) <reg-github-bot@antfu.me>

Author: 3 people

docs/content/1.guide/12.in-page-channel.md

@@ -64,7 +64,7 @@ Channel names are namespaced with the devframe id, like RPC ids. Function names
 
 ## The page script endpoint
 
-The required `functions` option and optional `events` option declare every incoming name on the endpoint's protocol side; use `{}` for an empty direction. Functions require a `handler`. Events accept an optional `handler`, and `{}` registers an event for runtime subscriptions through `on()`. Handlers are contextually typed from the shared protocol and support Standard-Schema argument validation and `jsonSerializable` metadata. `defineChannelFunction` retains the named definition shape for lower-level authoring.
+The required `functions` option and optional `events` option declare every incoming name on the endpoint's protocol side; use `{}` for an empty direction. Functions require a `handler`. Events accept an optional `handler`, and `{}` registers an event for runtime subscriptions through `on()`. Handlers are contextually typed from the shared protocol and support Standard-Schema argument validation and `jsonSerializable` metadata. A function with `agent` metadata is available to coding agents through MCP; the field implicitly enables strict JSON serialization (an explicit `jsonSerializable: false` conflicts). `defineChannelFunction` retains the named definition shape for lower-level authoring.
 
 `call()` accepts names from `functions`, including actions returning `void` or `Promise<void>`: callers can await completion and catch errors or timeouts. `emit()` and `on()` use the names declared in `events`. Function and event names have separate namespaces.
 

docs/content/6.errors/DF0080.md

@@ -0,0 +1,44 @@
+---
+title: 'DF0080: Agent In-Page Function Not JSON-Serializable'
+description: 'An in-page channel function sets `agent` but `jsonSerializable` is `false`.'
+---
+
+## Message
+
+> In-page channel function "{name}" has `agent` set but `jsonSerializable` is `false`; MCP requires JSON-serializable data.
+
+## Cause
+
+The `agent` field exposes an in-page function over the browser-to-node agent bridge and MCP, which only consumes JSON-shaped data, so it implicitly enables strict JSON serialization. An explicit `jsonSerializable: false` conflicts with that contract.
+
+## Example
+
+```ts
+import { createPageScriptChannel } from 'devframe/in-page-channel'
+
+createPageScriptChannel({
+  name: 'devframes:example',
+  functions: {
+    addTodo: {
+      agent: { description: 'Add a todo item.' },
+      jsonSerializable: false, // ✗ throws DF0080
+      handler: (text: string) => ({ added: text }),
+    },
+  },
+})
+```
+
+## Fix
+
+Remove `jsonSerializable: false` to use the implicit JSON contract, or remove `agent` to keep the function channel-only.
+
+```ts
+const addTodo = {
+  agent: { description: 'Add a todo item.' }, // jsonSerializable is inferred true
+  handler: (text: string) => ({ added: text }),
+}
+```
+
+## Source
+
+- [`packages/devframe/src/in-page-channel/internal.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/in-page-channel/internal.ts): `createLocalFunctionRegistry().register()` throws this when a definition combines `agent` with `jsonSerializable: false`, and infers `jsonSerializable: true` otherwise.

packages/agentic/src/connect/index.ts

@@ -67,10 +67,12 @@ export interface ConnectServerHandle {
 }
 
 /** One discovered instance in the `list-instances` payload: the registry record plus its probed MCP surface. */
+interface IndexedInstanceTools extends Pick<Tool, 'name' | 'title' | 'description' | 'inputSchema' | 'outputSchema' | 'annotations'> {}
+
 interface IndexedInstance extends Omit<DevframeInstanceRecord, 'mcp'> {
   mcp: {
     url: string
-    tools?: { name: string, description?: string }[]
+    tools?: IndexedInstanceTools[]
     error?: string
   } | null
   hint?: string
@@ -214,14 +216,8 @@ async function probePort(port: number, timeoutMs?: number): Promise<DevframeInst
   }
 }
 
-async function listInstanceTools(url: string, token: string | undefined): Promise<{ name: string, description?: string }[]> {
-  return withInstanceClient(url, token, async (client) => {
-    const listed = await client.listTools()
-    return listed.tools.map((tool: { name: string, description?: string }) => ({
-      name: tool.name,
-      description: tool.description,
-    }))
-  })
+async function listInstanceTools(url: string, token: string | undefined): Promise<IndexedInstanceTools[]> {
+  return withInstanceClient(url, token, async client => (await client.listTools()).tools)
 }
 
 async function call(
@@ -235,7 +231,8 @@ async function call(
     instancesDir: options.instancesDir,
     timeoutMs: options.timeoutMs,
   })
-  const record = live.find(r => r.port === args.port) ?? await probePort(args.port, options.timeoutMs)
+  const record = live.find(record => record.port === args.port && record.mcp)
+    ?? await probePort(args.port, options.timeoutMs)
   if (!record)
     throw diagnostics.DF0050({ port: args.port })
   if (!record.mcp)

packages/devframe/src/agent/safety.ts

@@ -0,0 +1,15 @@
+import type { RpcFunctionAgentOptions } from '../rpc/types'
+
+/**
+ * An agent tool's safety classification: the explicit `agent.safety`, else
+ * inferred from the function `type` (`static`/`query` are read-only, the rest
+ * mutate). Shared by every agent surface (MCP host, WebMCP, in-page bridge).
+ */
+export function resolveAgentSafety(
+  type: string | undefined,
+  agent: RpcFunctionAgentOptions,
+): 'read' | 'action' | 'destructive' {
+  if (agent.safety)
+    return agent.safety
+  return type === 'static' || type === 'query' || type == null ? 'read' : 'action'
+}

packages/devframe/src/client/browser-agent-rpc.test.ts

@@ -0,0 +1,54 @@
+import type { BrowserAgentToolManifest } from './browser-agent'
+import type { BrowserAgentInvocationDefinition } from './browser-agent-rpc'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { registerBrowserAgentTool } from './browser-agent'
+import { setupBrowserAgentRpcBridge } from './browser-agent-rpc'
+
+describe('browser agent RPC bridge', () => {
+  const disposals: (() => void)[] = []
+  afterEach(() => disposals.splice(0).forEach(dispose => dispose()))
+
+  it('synchronizes manifests and invokes the original browser tool', async () => {
+    const handlers = new Map<string, (...args: any[]) => unknown>()
+    const callOptional = vi.fn().mockResolvedValue(undefined)
+    const rpc = {
+      client: {
+        register(definition: BrowserAgentInvocationDefinition) {
+          handlers.set(definition.name, definition.handler)
+        },
+      },
+      callOptional(
+        method: 'devframe:agent:sync-client-tools',
+        clientId: string,
+        tools: BrowserAgentToolManifest[],
+      ) {
+        return callOptional(method, clientId, tools)
+      },
+      events: { on: () => () => {} },
+    }
+
+    disposals.push(registerBrowserAgentTool({
+      id: 'todos:add',
+      description: 'Add a todo.',
+      safety: 'action',
+      inputSchema: { type: 'object' },
+      invoke: args => ({ added: args.text }),
+    }))
+    disposals.push(setupBrowserAgentRpcBridge(rpc))
+    await vi.waitFor(() => expect(callOptional).toHaveBeenCalledWith(
+      'devframe:agent:sync-client-tools',
+      expect.any(String),
+      [{
+        id: 'todos:add',
+        description: 'Add a todo.',
+        safety: 'action',
+        inputSchema: { type: 'object' },
+      }],
+    ))
+
+    await expect(handlers.get('devframe:agent:invoke-client-tool')!(
+      'todos:add',
+      { text: 'milk' },
+    )).resolves.toEqual({ added: 'milk' })
+  })
+})

packages/devframe/src/client/browser-agent-rpc.ts

@@ -0,0 +1,78 @@
+import type { BrowserAgentToolManifest } from './browser-agent'
+import type { DevframeConnectionStatus } from './connection'
+import {
+  listBrowserAgentTools,
+  onBrowserAgentToolsChanged,
+} from './browser-agent'
+import { resolveClientId } from './client-id'
+
+export interface BrowserAgentInvocationDefinition {
+  name: 'devframe:agent:invoke-client-tool'
+  type: 'action'
+  jsonSerializable: true
+  handler: (id: string, args: Record<string, unknown>) => Promise<unknown>
+}
+
+interface BrowserAgentRpcClient {
+  client: { register: (definition: BrowserAgentInvocationDefinition) => void }
+  callOptional: (
+    method: 'devframe:agent:sync-client-tools',
+    clientId: string,
+    tools: BrowserAgentToolManifest[],
+  ) => Promise<unknown>
+  events: {
+    on: (
+      event: 'connection:status',
+      listener: (status: DevframeConnectionStatus, previous: DevframeConnectionStatus) => void,
+    ) => () => void
+  }
+}
+
+/** Mirror this document's browser-agent registry over its existing RPC connection. */
+export function setupBrowserAgentRpcBridge(rpc: BrowserAgentRpcClient): () => void {
+  rpc.client.register({
+    name: 'devframe:agent:invoke-client-tool',
+    type: 'action',
+    jsonSerializable: true,
+    handler: async (id: string, args: Record<string, unknown>) => {
+      const tool = listBrowserAgentTools().find(tool => tool.id === id)
+      if (!tool)
+        throw new Error(`[devframe/agent] browser tool "${id}" not found`)
+      return await tool.invoke(args)
+    },
+  })
+
+  let queued = false
+  let disposed = false
+  let lastSyncedCount = 0
+  const sync = (): void => {
+    if (queued || disposed)
+      return
+    queued = true
+    queueMicrotask(async () => {
+      queued = false
+      if (disposed)
+        return
+      const manifests = listBrowserAgentTools().map(({ invoke: _, ...manifest }) => manifest)
+      // Skip the no-op sync when nothing is registered and nothing was ever
+      // mirrored; a page with no browser-agent tools stays off the wire.
+      if (manifests.length === 0 && lastSyncedCount === 0)
+        return
+      lastSyncedCount = manifests.length
+      await rpc.callOptional('devframe:agent:sync-client-tools', resolveClientId(), manifests).catch(() => {})
+    })
+  }
+
+  const stopTools = onBrowserAgentToolsChanged(sync)
+  const stopConnection = rpc.events.on('connection:status', (status) => {
+    if (status === 'connected')
+      sync()
+  })
+  sync()
+
+  return () => {
+    disposed = true
+    stopTools()
+    stopConnection()
+  }
+}

packages/devframe/src/client/browser-agent.ts

@@ -0,0 +1,48 @@
+export interface BrowserAgentToolManifest {
+  id: string
+  title?: string
+  description: string
+  safety: 'read' | 'action' | 'destructive'
+  tags?: readonly string[]
+  inputSchema?: unknown
+}
+
+export interface BrowserAgentTool extends BrowserAgentToolManifest {
+  invoke: (args: Record<string, unknown>) => unknown | Promise<unknown>
+}
+
+interface BrowserAgentRegistryState {
+  tools: Map<symbol, BrowserAgentTool>
+  listeners: Set<() => void>
+}
+
+const REGISTRY_KEY = Symbol.for('devframe:browser-agent-registry')
+const state = ((globalThis as any)[REGISTRY_KEY] ??= {
+  tools: new Map(),
+  listeners: new Set(),
+}) as BrowserAgentRegistryState
+const { tools, listeners } = state
+
+function notifyChanged(): void {
+  for (const listener of listeners)
+    listener()
+}
+
+export function registerBrowserAgentTool(tool: BrowserAgentTool): () => void {
+  const key = Symbol(tool.id)
+  tools.set(key, tool)
+  notifyChanged()
+  return () => {
+    if (tools.delete(key))
+      notifyChanged()
+  }
+}
+
+export function listBrowserAgentTools(): BrowserAgentTool[] {
+  return [...tools.values()]
+}
+
+export function onBrowserAgentToolsChanged(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}

packages/devframe/src/client/client-id.ts

@@ -0,0 +1,31 @@
+import { nanoid } from 'devframe/utils/nanoid'
+
+const CLIENT_ID_STORAGE_KEY = 'devframe:client-id'
+let memoryClientId: string | undefined
+
+/**
+ * This browser tab's stable client id: one nanoid per tab, persisted in
+ * `sessionStorage` so it survives page reloads and RPC reconnects. The node
+ * side uses it to tell connected tabs apart across reconnects (see #394).
+ *
+ * Tab duplication copies `sessionStorage`, so two tabs can briefly share an id
+ * until per-tab disambiguation lands with the wider tab-metadata work.
+ */
+export function resolveClientId(win: Window | undefined = globalThis.window): string {
+  try {
+    const storage = win?.sessionStorage
+    if (storage) {
+      let id = storage.getItem(CLIENT_ID_STORAGE_KEY)
+      if (!id) {
+        id = nanoid()
+        storage.setItem(CLIENT_ID_STORAGE_KEY, id)
+      }
+      return id
+    }
+  }
+  catch {
+    // Storage unavailable (sandboxed iframe, disabled cookies); fall through.
+  }
+  memoryClientId ??= nanoid()
+  return memoryClientId
+}

packages/devframe/src/client/rpc-auth-gate.test.ts

@@ -145,4 +145,29 @@ describe('getDevframeRpcClient: auth bootstrap gates outbound calls', () => {
     // `close?:` exists to keep working.
     expect(() => rpc.close?.()).not.toThrow()
   })
+
+  const INVOKE_CLIENT_TOOL = 'devframe:agent:invoke-client-tool'
+
+  it('loads the browser-agent bridge only when the node advertises MCP', async () => {
+    const { getDevframeRpcClient } = await import('./rpc')
+    const rpc = await getDevframeRpcClient({
+      connectionMeta: { ...connectionMeta, mcp: { path: '__mcp' } },
+      otpParam: false,
+      simpleAuth: false,
+    })
+    // The bridge lives in its own chunk and registers this handler once loaded.
+    await vi.waitFor(() => expect(rpc.client.definitions.has(INVOKE_CLIENT_TOOL)).toBe(true))
+  })
+
+  it('leaves the browser-agent bridge unloaded without MCP', async () => {
+    const { getDevframeRpcClient } = await import('./rpc')
+    const rpc = await getDevframeRpcClient({
+      connectionMeta,
+      otpParam: false,
+      simpleAuth: false,
+    })
+    // Give any stray dynamic import time to resolve; it must not.
+    await new Promise(resolve => setTimeout(resolve, 20))
+    expect(rpc.client.definitions.has(INVOKE_CLIENT_TOOL)).toBe(false)
+  })
 })

packages/devframe/src/client/rpc.ts

@@ -356,6 +356,8 @@ export async function getDevframeRpcClient(
   const clientRpc: DevframeClientRpcHost = new RpcFunctionsCollectorBase<DevframeRpcClientFunctions, DevframeRpcContext>(context)
   // No-op when the browser provides no WebMCP model context.
   const disposeWebMcp = options.webmcp === false ? undefined : registerWebMcpTools(clientRpc)
+  let disposeBrowserAgentBridge: (() => void) | undefined
+  let closed = false
 
   async function fetchJsonFromBases(path: string): Promise<any> {
     const candidates = [
@@ -447,7 +449,9 @@ export async function getDevframeRpcClient(
 
   /** Release authentication and transport resources even if another disposer fails. */
   function closeRpcClient(): void {
+    closed = true
     try {
+      disposeBrowserAgentBridge?.()
       disposeWebMcp?.()
     }
     finally {
@@ -596,6 +600,18 @@ export async function getDevframeRpcClient(
     () => { bootstrapAuthSettled = true },
   )
 
+  // Only when the node advertises an MCP endpoint (`connectionMeta.mcp`) is the
+  // browser-agent bridge useful, so load it from its own chunk on demand and
+  // keep it out of the main client bundle for every non-MCP connection.
+  if (connectionMeta.mcp) {
+    void import('./browser-agent-rpc')
+      .then(({ setupBrowserAgentRpcBridge }) => {
+        if (!closed)
+          disposeBrowserAgentBridge = setupBrowserAgentRpcBridge(rpc)
+      })
+      .catch(() => {})
+  }
+
   // Listen for auth updates from other tabs (e.g., the auth page, or another
   // tab that just completed a code exchange).
   if (authChannel) {