feat(agent): list connected browser tabs and route client tool calls per tab

Forward agent-flagged in-page channel functions to the node MCP endpoint
(ports the bridge from #376 onto 0.10), and make each connected browser
tab visible and addressable: a built-in devframe:agent:list-clients tool,
a reserved client_id argument on forwarded tools, and focus-aware default
routing so an unaddressed call follows the tab the user looked at last.
devframe connect nests the tab list under mcp.clients per instance.

Closes #394

Author: antfubot

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 must set `jsonSerializable: true` and is forwarded to coding agents [over the node's MCP endpoint](/guide/agent-native#in-page-tools-over-mcp). `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/1.guide/15.agent-native.md

@@ -160,6 +160,28 @@ rpc.client.register({
 > [!WARNING]
 > WebMCP is an experimental proposal; `registerWebMcpTools` tracks the current draft (`AbortSignal`-based unregistration) and earlier handle-returning drafts, but the browser API may still change.
 
+## In-page tools over MCP
+
+An [in-page channel](/guide/in-page-channel) function carrying an `agent` field (and `jsonSerializable: true`) is forwarded to the node side over the page's RPC connection and served from the same MCP endpoint as node-side tools, under the id `<channel name>:<function name>`. The page keeps executing the handler; the node relays the call and the result.
+
+```ts
+const channel = createPageScriptChannel({
+  name: 'my-plugin',
+  functions: {
+    'selected-node': {
+      type: 'query',
+      jsonSerializable: true,
+      agent: { description: 'Return the node the user selected in the page. Call it before proposing an edit.' },
+      handler: () => getSelectedNode(),
+    },
+  },
+})
+```
+
+Every connected browser tab syncs its own manifest, so the same app open in several tabs exposes each tool once, plus a built-in `devframe:agent:list-clients` tool (wire name `devframe_agent_list-clients`) listing the connected tabs: a per-tab `id` (stable across reloads), `url`, `title`, `visible`/`focused`, `connectedAt`, and the tool ids that tab exposes. `devframe connect` nests the same list under `mcp.clients` for each instance.
+
+A forwarded tool accepts a reserved `client_id` argument to run on one tab. Without it, the call goes to the most recently focused visible tab, falling back to the tab that synced last; an unknown `client_id` fails with [DF0081](/errors/DF0081), which lists the live ids. Tabs re-sync on focus and visibility changes, so an unaddressed call follows the tab the user looked at last.
+
 ## Writing descriptions agents act on
 
 Describe *when* to use a tool, not just its return:

docs/content/6.errors/DF0080.md

@@ -0,0 +1,36 @@
+---
+title: 'DF0080: In-Page Channel Agent Function Not JSON-Serializable'
+description: 'In-page channel function "{name}" has `agent` set but `jsonSerializable` is not `true`; MCP requires JSON-serializable data.'
+---
+
+## Message
+
+> In-page channel function "`{name}`" has `agent` set but `jsonSerializable` is not `true`; MCP requires JSON-serializable data.
+
+## Cause
+
+An in-page channel function declares `agent` metadata, so it is forwarded to coding agents over the node's MCP endpoint, but it did not opt into strict JSON serialization. MCP carries arguments and results as JSON, so a function whose payload may hold non-JSON values (class instances, `Map`s, functions) cannot be exposed safely.
+
+## Example
+
+```ts
+import { createPageScriptChannel } from 'devframe/in-page-channel'
+
+createPageScriptChannel({
+  name: 'my-plugin',
+  functions: {
+    'selected-node': {
+      agent: { description: 'Return the selected node.' }, // ✗ no `jsonSerializable: true`
+      handler: () => getSelectedNode(),
+    },
+  },
+})
+```
+
+## Fix
+
+Set `jsonSerializable: true` when the payload is JSON-safe, or drop the `agent` field to keep the function channel-only.
+
+## 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 an `agent`-flagged definition lacks `jsonSerializable: true`.

docs/content/6.errors/DF0081.md

@@ -0,0 +1,20 @@
+---
+title: 'DF0081: Addressed Client Not Connected'
+description: 'Tool "{tool}" was addressed to client "{clientId}", but no connected browser tab has that id and the tool.'
+---
+
+## Message
+
+> Tool "`{tool}`" was addressed to client "`{clientId}`", but no connected browser tab has that id and the tool. Connected clients: `{live}`.
+
+## Cause
+
+A forwarded in-page tool was called with a `client_id` that matches none of the browser tabs currently connected to this devframe (or the tab with that id does not expose the tool). Tab ids survive reloads but not closing the tab, so an id an agent listed earlier may have gone away since.
+
+## Fix
+
+Call `devframe:agent:list-clients` (wire name `devframe_agent_list-clients`; `mcp.clients` in `devframe connect`'s `list-instances`) to get the live ids and retry with one of them, or omit `client_id` to target the most recently focused tab.
+
+## Source
+
+- [`packages/devframe/src/node/client-agent.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/client-agent.ts): the forwarded tool's handler throws this when no connected session matches the requested `client_id`.

docs/content/6.errors/index.md

@@ -86,6 +86,8 @@ Emitted by `devframe`: the framework-neutral host, RPC, streaming, assets, servi
 | [DF0077](/errors/DF0077) | error | In-Page Channel Function Not Registered |
 | [DF0078](/errors/DF0078) | warn | Agent Surface Without @devframes/agentic |
 | [DF0079](/errors/DF0079) | error | MCP Enabled Without @devframes/agentic |
+| [DF0080](/errors/DF0080) | error | In-Page Channel Agent Function Not JSON-Serializable |
+| [DF0081](/errors/DF0081) | error | Addressed Client Not Connected |
 
 ## Hub: context & lifecycle (DF80xx)
 

packages/agentic/src/connect/index.ts

@@ -1,9 +1,9 @@
 import type { Tool } from '@modelcontextprotocol/server'
-import type { DevframeInstanceRecord } from 'devframe/internal'
+import type { ConnectedClient, DevframeInstanceRecord } from 'devframe/internal'
 import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
 import { Server } from '@modelcontextprotocol/server'
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
-import { diagnostics, listLiveDevframeInstances, probeDevframeOrigin } from 'devframe/internal'
+import { diagnostics, LIST_CLIENTS_TOOL, listLiveDevframeInstances, probeDevframeOrigin } from 'devframe/internal'
 import { toAgentToolName } from 'devframe/utils/agent-tool-name'
 import { Diagnostic } from 'devframe/utils/nostics'
 import { joinURL } from 'devframe/utils/url'
@@ -71,11 +71,16 @@ interface IndexedInstance extends Omit<DevframeInstanceRecord, 'mcp'> {
   mcp: {
     url: string
     tools?: { name: string, description?: string }[]
+    /** Browser tabs connected to the instance, when it forwards client tools. */
+    clients?: ConnectedClient[]
     error?: string
   } | null
   hint?: string
 }
 
+/** Wire name of the built-in tab-listing tool an instance exposes once a browser tab connects. */
+const LIST_CLIENTS_NAME = toAgentToolName(LIST_CLIENTS_TOOL)
+
 // Gateway tool ids follow the `devframe:<area>:<fn>` convention; the wire
 // names are their sanitized forms (`devframe_connect_list-instances`, …).
 const INDEX_TOOL = toAgentToolName('devframe:connect:list-instances')
@@ -88,7 +93,7 @@ const GATEWAY_TOOLS: Tool[] = [
   {
     name: INDEX_TOOL,
     title: 'Discover running devframes',
-    description: 'Discover every running devframe dev server on this machine and list each one\'s MCP tools. Call this FIRST, before assuming which devtools are available; the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.',
+    description: 'Discover every running devframe dev server on this machine and list each one\'s MCP tools, plus the browser tabs connected to it (`mcp.clients`). Call this FIRST, before assuming which devtools are available; the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.',
     inputSchema: { type: 'object', properties: {} },
     annotations: { readOnlyHint: true, destructiveHint: false },
   },
@@ -101,7 +106,7 @@ const GATEWAY_TOOLS: Tool[] = [
       properties: {
         port: { type: 'number', description: 'The instance\'s port, from the list-instances tool.' },
         tool: { type: 'string', description: 'Tool name, from the instance\'s tool list.' },
-        args: { type: 'object', description: 'Arguments object for the tool. Omit for zero-argument tools.' },
+        args: { type: 'object', description: 'Arguments object for the tool. Omit for zero-argument tools. Tools forwarded from a browser tab accept `client_id` (from `mcp.clients` in list-instances) to target one tab; omitted, the most recently focused tab runs it.' },
       },
       required: ['port', 'tool'],
       additionalProperties: false,
@@ -176,7 +181,7 @@ async function index(options: ConnectServerOptions): Promise<unknown> {
     }
     const url = `${record.origin}${mcp.path}`
     try {
-      entry.mcp = { url, tools: await listInstanceTools(url, resolveAuthToken(options.authToken, record)) }
+      entry.mcp = { url, ...await indexInstanceMcp(url, resolveAuthToken(options.authToken, record)) }
     }
     catch (error) {
       entry.mcp = { url, error: error instanceof Error ? error.message : String(error) }
@@ -214,13 +219,22 @@ async function probePort(port: number, timeoutMs?: number): Promise<DevframeInst
   }
 }
 
-async function listInstanceTools(url: string, token: string | undefined): Promise<{ name: string, description?: string }[]> {
+async function indexInstanceMcp(
+  url: string,
+  token: string | undefined,
+): Promise<Pick<NonNullable<IndexedInstance['mcp']>, 'tools' | 'clients'>> {
   return withInstanceClient(url, token, async (client) => {
     const listed = await client.listTools()
-    return listed.tools.map((tool: { name: string, description?: string }) => ({
+    const tools = listed.tools.map((tool: { name: string, description?: string }) => ({
       name: tool.name,
       description: tool.description,
     }))
+    if (!tools.some(tool => tool.name === LIST_CLIENTS_NAME))
+      return { tools }
+    const result = await client.callTool({ name: LIST_CLIENTS_NAME, arguments: {} })
+    // `structuredContent` is untyped on the wire; the tool's outputSchema fixes this shape.
+    const clients = (result.structuredContent as { clients?: ConnectedClient[] } | undefined)?.clients ?? []
+    return { tools, clients }
   })
 }
 

packages/agentic/src/mcp/__tests__/mcp-client-tools.test.ts

@@ -0,0 +1,87 @@
+import type { StartedServer } from 'devframe/internal'
+import type { DevframeDefinition, DevframeRpcClientFunctions, DevframeRpcServerFunctions } from 'devframe/types'
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
+import { createDevServer } from 'devframe/adapters/dev'
+import { createRpcClient } from 'devframe/rpc/client'
+import { createWsRpcChannel } from 'devframe/rpc/transports/ws-client'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const definition: DevframeDefinition = {
+  id: 'client-tools-test',
+  name: 'Client Tools Test',
+  version: '0.0.0',
+  packageName: '@devframe/client-tools-test',
+  homepage: 'https://example.com',
+  description: 'Fixture: a devframe whose only agent tools live in browser tabs.',
+  setup() {},
+}
+
+/** A browser tab: one RPC connection exposing `page:selection` and answering with its own id. */
+function connectTab(origin: string, client: { id: string, focused: boolean, visible?: boolean }) {
+  const clientFunctions = {
+    'devframe:agent:invoke-client-tool': async (id: string, args: Record<string, unknown>) => ({ tab: client.id, tool: id, args }),
+  }
+  const rpc = createRpcClient<DevframeRpcServerFunctions, DevframeRpcClientFunctions>(
+    clientFunctions as any,
+    { channel: createWsRpcChannel({ url: `${origin.replace('http', 'ws')}/__ws` }) },
+  )
+  const sync = (focused = client.focused) => rpc.$call('devframe:agent:sync-client-tools', {
+    client: { id: client.id, url: `http://app.local/${client.id}`, title: client.id, visible: client.visible ?? true, focused },
+    tools: [{ id: 'page:selection', description: 'Read the selection.', safety: 'read', inputSchema: { type: 'object', properties: {} } }],
+  })
+  return { rpc, sync }
+}
+
+describe('client tools over the MCP route', () => {
+  let server: StartedServer | undefined
+  afterEach(async () => {
+    await server?.close()
+    server = undefined
+  })
+
+  it('lists connected tabs and routes calls per tab', async () => {
+    server = await createDevServer(definition, { host: '127.0.0.1', port: 0, auth: false, mcp: true })
+    const a = connectTab(server.origin, { id: 'tab-a', focused: false })
+    const b = connectTab(server.origin, { id: 'tab-b', focused: true })
+    await a.sync()
+    await b.sync()
+
+    const mcp = new Client({ name: 'test', version: '0.0.0' }, { versionNegotiation: { mode: 'auto' } })
+    await mcp.connect(new StreamableHTTPClientTransport(new URL(`${server.origin}/__mcp`), {
+      requestInit: { headers: { origin: server.origin } },
+    }))
+    try {
+      const { tools } = await mcp.listTools()
+      const names = tools.map(t => t.name)
+      expect(names).toContain('devframe_agent_list-clients')
+      expect(names.filter(n => n === 'page_selection')).toHaveLength(1)
+      expect((tools.find(t => t.name === 'page_selection')!.inputSchema as any).properties.client_id).toMatchObject({ type: 'string' })
+
+      const listed = await mcp.callTool({ name: 'devframe_agent_list-clients', arguments: {} })
+      expect(listed.structuredContent).toEqual({
+        clients: [
+          expect.objectContaining({ id: 'tab-a', url: 'http://app.local/tab-a', focused: false, tools: ['page:selection'] }),
+          expect.objectContaining({ id: 'tab-b', focused: true, tools: ['page:selection'] }),
+        ],
+      })
+
+      const unaddressed = await mcp.callTool({ name: 'page_selection', arguments: {} })
+      expect(JSON.parse((unaddressed.content as any)[0].text)).toMatchObject({ tab: 'tab-b', args: {} })
+
+      const addressed = await mcp.callTool({ name: 'page_selection', arguments: { client_id: 'tab-a' } })
+      expect(JSON.parse((addressed.content as any)[0].text)).toMatchObject({ tab: 'tab-a', args: {} })
+
+      const missing = await mcp.callTool({ name: 'page_selection', arguments: { client_id: 'gone' } })
+      expect(missing.isError).toBe(true)
+      expect((missing.content as any)[0].text).toMatch(/DF0081.*tab-a, tab-b/s)
+
+      // Focus moves to a: unaddressed calls follow it.
+      await a.sync(true)
+      const refocused = await mcp.callTool({ name: 'page_selection', arguments: {} })
+      expect(JSON.parse((refocused.content as any)[0].text)).toMatchObject({ tab: 'tab-a' })
+    }
+    finally {
+      await mcp.close()
+    }
+  })
+})

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

@@ -0,0 +1,58 @@
+import type { BrowserAgentSync } 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 with a tab snapshot 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', sync: BrowserAgentSync) {
+        return callOptional(method, sync)
+      },
+      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',
+      {
+        client: {
+          id: expect.any(String),
+          url: expect.any(String),
+          title: expect.any(String),
+          visible: expect.any(Boolean),
+          focused: expect.any(Boolean),
+        },
+        tools: [{
+          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' })
+  })
+})