refactor: infer JSON serialization for agent in-page functions and dedupe safety

Align the in-page `agent` option with #379: setting `agent` now implies
`jsonSerializable: true` instead of requiring it, and DF0080 only fires on an
explicit `jsonSerializable: false`.

Collapse the three copies of the agent safety inference (WebMCP, the MCP host,
and the in-page bridge) into one shared `resolveAgentSafety` helper, and drop
the redundant id de-duplication in the browser-agent registry since the
node-side tool provider already dedupes.

Co-authored-by: agent <agent@opencode>

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. A function with `agent` metadata must set `jsonSerializable: true` and is available to coding agents through MCP. `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

@@ -1,15 +1,15 @@
 ---
 title: 'DF0080: Agent In-Page Function Not JSON-Serializable'
-description: 'An in-page channel function sets `agent` but does not set `jsonSerializable: true`.'
+description: 'An in-page channel function sets `agent` but `jsonSerializable` is `false`.'
 ---
 
 ## Message
 
-> In-page channel function "{name}" has `agent` set but `jsonSerializable` is not `true`; MCP requires JSON-serializable data.
+> In-page channel function "{name}" has `agent` set but `jsonSerializable` is `false`; MCP requires JSON-serializable data.
 
 ## Cause
 
-A function exposed to coding agents crosses the browser-to-node agent bridge and is surfaced over MCP, whose payloads must be JSON-serializable. Declaring `agent` without `jsonSerializable: true` leaves the channel free to move non-JSON values (through structured clone) that MCP cannot represent.
+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
 
@@ -21,24 +21,24 @@ createPageScriptChannel({
   functions: {
     addTodo: {
       agent: { description: 'Add a todo item.' },
-      handler: (text: string) => ({ added: text }), // ✗ `agent` without `jsonSerializable: true`
+      jsonSerializable: false, // ✗ throws DF0080
+      handler: (text: string) => ({ added: text }),
     },
   },
 })
 ```
 
 ## Fix
 
-Set `jsonSerializable: true` when the payload is JSON-safe, or remove `agent` to keep the function channel-only.
+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: true, // ✓
+  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 carries `agent` without `jsonSerializable: true`.
+- [`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/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.ts

@@ -1,5 +1,3 @@
-import type { RpcFunctionAgentOptions } from 'devframe/rpc'
-
 export interface BrowserAgentToolManifest {
   id: string
   title?: string
@@ -41,24 +39,10 @@ export function registerBrowserAgentTool(tool: BrowserAgentTool): () => void {
 }
 
 export function listBrowserAgentTools(): BrowserAgentTool[] {
-  const unique = new Map<string, BrowserAgentTool>()
-  for (const tool of tools.values()) {
-    if (!unique.has(tool.id))
-      unique.set(tool.id, tool)
-  }
-  return [...unique.values()]
+  return [...tools.values()]
 }
 
 export function onBrowserAgentToolsChanged(listener: () => void): () => void {
   listeners.add(listener)
   return () => listeners.delete(listener)
 }
-
-export function resolveBrowserAgentSafety(
-  type: string | undefined,
-  agent: RpcFunctionAgentOptions,
-): BrowserAgentToolManifest['safety'] {
-  if (agent.safety)
-    return agent.safety
-  return type === 'static' || type === 'query' || type == null ? 'read' : 'action'
-}

packages/devframe/src/client/webmcp.ts

@@ -1,9 +1,10 @@
-import type { RpcFunctionAgentOptions, RpcFunctionDefinitionAnyWithContext, RpcFunctionsCollector, RpcFunctionType } from 'devframe/rpc'
+import type { RpcFunctionAgentOptions, RpcFunctionDefinitionAnyWithContext, RpcFunctionsCollector } from 'devframe/rpc'
 import { getRpcHandler } from 'devframe/rpc'
 import { toAgentToolName } from 'devframe/utils/agent-tool-name'
 // Pure, browser-safe projections shared with the node-side MCP adapter
 // (`@devframes/agentic/mcp`, via `devframe/internal`), so the WebMCP surface
 // cannot drift from the MCP one.
+import { resolveAgentSafety } from '../agent/safety'
 import { argsToJsonSchema } from '../agent/to-json-schema'
 import { toolInputToRpcArgs } from '../tool-input'
 
@@ -132,14 +133,15 @@ export function registerWebMcpTools<LocalFunctions, SetupContext>(
     }
 
     const controller = new AbortController()
+    const safety = resolveAgentSafety(def.type, agent)
     const result = modelContext.registerTool({
       name,
       description: agent.description,
       inputSchema: argsToJsonSchema(def.args),
       annotations: {
         title: agent.title ?? def.name,
-        readOnlyHint: resolveSafety(def, agent) === 'read',
-        destructiveHint: resolveSafety(def, agent) === 'destructive',
+        readOnlyHint: safety === 'read',
+        destructiveHint: safety === 'destructive',
       },
       execute: args => executeRpcTool(def, clientRpc.context, args),
     }, { signal: controller.signal })
@@ -180,16 +182,6 @@ export function registerWebMcpTools<LocalFunctions, SetupContext>(
   }
 }
 
-function resolveSafety(
-  def: RpcFunctionDefinitionAnyWithContext<any>,
-  agent: RpcFunctionAgentOptions,
-): 'read' | 'action' | 'destructive' {
-  if (agent.safety)
-    return agent.safety
-  const type: RpcFunctionType = def.type ?? 'query'
-  return type === 'static' || type === 'query' ? 'read' : 'action'
-}
-
 async function executeRpcTool<SetupContext>(
   def: RpcFunctionDefinitionAnyWithContext<SetupContext>,
   context: SetupContext,

packages/devframe/src/in-page-channel/agent.test.ts

@@ -62,13 +62,31 @@ describe('in-page channel agent tools', () => {
     expect(listBrowserAgentTools().some(tool => tool.id === 'devframes:test:add')).toBe(false)
   })
 
-  it('rejects agent exposure without strict JSON serialization', () => {
+  it('infers strict JSON serialization when agent is set', () => {
+    const channel = createPageScriptChannel<TestProtocol>({
+      name: 'devframes:inferred',
+      window: false,
+      heartbeat: false,
+      functions: {
+        add: {
+          agent: { description: 'Add two numbers.' },
+          handler: (a, b) => ({ sum: a + b }),
+        },
+        hidden: { handler: () => 'internal' },
+      },
+    })
+    expect(listBrowserAgentTools().some(tool => tool.id === 'devframes:inferred:add')).toBe(true)
+    channel.close()
+  })
+
+  it('rejects agent exposure with explicit jsonSerializable: false', () => {
     expect(() => createPageScriptChannel<TestProtocol>({
       name: 'devframes:invalid',
       window: false,
       functions: {
         add: {
           agent: { description: 'Add two numbers.' },
+          jsonSerializable: false,
           handler: (a, b) => ({ sum: a + b }),
         },
         hidden: { handler: () => 'internal' },

packages/devframe/src/in-page-channel/diagnostics.ts

@@ -9,8 +9,8 @@ export const diagnostics = /* #__PURE__ */ defineDiagnostics({
     },
     DF0080: {
       why: (p: { name: string }) =>
-        `In-page channel function "${p.name}" has \`agent\` set but \`jsonSerializable\` is not \`true\`; MCP requires JSON-serializable data.`,
-      fix: 'Set `jsonSerializable: true` if the payload is JSON-safe, or remove `agent` to keep it channel-only.',
+        `In-page channel function "${p.name}" has \`agent\` set but \`jsonSerializable\` is \`false\`; MCP requires JSON-serializable data.`,
+      fix: 'Remove `jsonSerializable: false`, or remove `agent` to keep it channel-only.',
     },
   },
 })

packages/devframe/src/in-page-channel/internal.ts

@@ -4,8 +4,9 @@ import type { RpcArgsSchema } from '../rpc/types'
 import type { InPageChannelControlFrame } from './protocol'
 import type { InPageFunctionDefinitionAny, InPageFunctionType } from './types'
 import { createBirpc } from 'birpc'
+import { resolveAgentSafety } from '../agent/safety'
 import { argsToJsonSchema } from '../agent/to-json-schema'
-import { registerBrowserAgentTool, resolveBrowserAgentSafety } from '../client/browser-agent'
+import { registerBrowserAgentTool } from '../client/browser-agent'
 import { toolInputToRpcArgs } from '../tool-input'
 import { diagnostics } from './diagnostics'
 import { isControlFrame } from './protocol'
@@ -189,8 +190,13 @@ export function createLocalFunctionRegistry(codec: InPageChannelSerialization):
   return {
     definitions,
     register(definition) {
-      if ('agent' in definition && definition.agent && definition.jsonSerializable !== true)
-        throw diagnostics.DF0080({ name: definition.name })
+      // `agent` implies strict JSON serialization, since MCP consumes
+      // JSON-shaped data; an explicit `jsonSerializable: false` conflicts.
+      if ('agent' in definition && definition.agent) {
+        if (definition.jsonSerializable === false)
+          throw diagnostics.DF0080({ name: definition.name })
+        definition.jsonSerializable = true
+      }
       definitions.set(channelMethod(definition.type, definition.name), definition)
     },
     // The shared-state layer keys its handlers by their own fully-qualified
@@ -276,7 +282,7 @@ export function registerInPageAgentTools(
       id: `${channelName}:${definition.name}`,
       title: agent.title ?? definition.name,
       description: agent.description,
-      safety: resolveBrowserAgentSafety(definition.type, agent),
+      safety: resolveAgentSafety(definition.type, agent),
       tags: agent.tags,
       inputSchema: argsToJsonSchema(definition.args),
       invoke: (args) => {

packages/devframe/src/node/host-agent.ts

@@ -1,4 +1,4 @@
-import type { RpcFunctionDefinitionAnyWithContext, RpcFunctionType } from 'devframe/rpc'
+import type { RpcFunctionDefinitionAnyWithContext } from 'devframe/rpc'
 import type {
   AgentHandle,
   AgentManifest,
@@ -16,6 +16,7 @@ import type {
   RpcFunctionAgentOptions,
 } from 'devframe/types'
 import { createEventEmitter } from 'devframe/utils/events'
+import { resolveAgentSafety } from '../agent/safety'
 import { DEVFRAME_EVENTS } from '../events'
 import { toolInputToRpcArgs } from '../tool-input'
 import { diagnostics } from './diagnostics'
@@ -261,8 +262,7 @@ export class DevframeAgentHost implements DevframeAgentHostType {
       if (!agent.description || typeof agent.description !== 'string')
         throw diagnostics.DF0014({ name })
 
-      const type: RpcFunctionType = def.type ?? 'query'
-      const safety = agent.safety ?? inferSafety(type)
+      const safety = resolveAgentSafety(def.type, agent)
       out.push({
         id: name,
         kind: 'rpc',
@@ -287,9 +287,3 @@ export class DevframeAgentHost implements DevframeAgentHostType {
     return undefined
   }
 }
-
-function inferSafety(type: RpcFunctionType): 'read' | 'action' | 'destructive' {
-  if (type === 'static' || type === 'query')
-    return 'read'
-  return 'action'
-}