fix: infer JSON serialization for agent RPCs

Author: posva

docs/content/1.guide/3.rpc.md

@@ -193,7 +193,6 @@ Add an `agent` field to expose the function to coding agents over MCP:
 defineRpcFunction({
   name: 'get-modules',
   type: 'query',
-  jsonSerializable: true,
   args: [v.object({ limit: v.number() })],
   returns: v.array(v.object({ id: v.string(), size: v.number() })),
   agent: {
@@ -207,7 +206,7 @@ defineRpcFunction({
 })
 ```
 
-Exposing a function over MCP requires `jsonSerializable: true`.
+The `agent` field implicitly enables strict JSON serialization because MCP consumes JSON-shaped data. Set `jsonSerializable: true` directly when an RPC-only function also benefits from that contract.
 
 ## What's next
 

docs/content/6.errors/DF0019.md

@@ -1,29 +1,30 @@
 ---
 title: 'DF0019: Agent Requires JSON-Serializable RPC'
-description: 'RPC function "{name}" has agent set but jsonSerializable is not true; MCP requires JSON-serializable data.'
+description: 'RPC function "{name}" has agent set but jsonSerializable is false; MCP requires JSON-serializable data.'
 ---
 
 ## Message
 
-> RPC function "`{name}`" has `agent` set but `jsonSerializable` is not `true`; MCP requires JSON-serializable data.
+> RPC function "`{name}`" has `agent` set but `jsonSerializable` is `false`; MCP requires JSON-serializable data.
 
 ## Cause
 
-The `agent` field exposes an RPC function as an MCP tool, and MCP only consumes JSON-shaped data. A function with `agent` set is rejected unless it also declares `jsonSerializable: true`.
+The `agent` field exposes an RPC function as an MCP tool and implicitly enables strict JSON serialization. An explicit `jsonSerializable: false` conflicts with MCP's JSON-shaped data.
 
 ## Example
 
 ```ts
 defineRpcFunction({
   name: 'my-plugin:summary',
   agent: { description: 'Returns a summary' },
-  handler: () => ({ items: [1, 2, 3] }), // ✗ throws DF0019: missing jsonSerializable: true
+  jsonSerializable: false, // ✗ throws DF0019
+  handler: () => ({ items: [1, 2, 3] }),
 })
 ```
 
 ## Fix
 
-Set `jsonSerializable: true` if the payload is JSON-safe, or remove `agent` to keep it RPC-only.
+Remove `jsonSerializable: false` to use the implicit JSON contract, or remove `agent` to keep the function RPC-only.
 
 ```ts
 defineRpcFunction({
@@ -36,4 +37,4 @@ defineRpcFunction({
 
 ## Source
 
-- [`packages/devframe/src/rpc/collector.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/collector.ts): `RpcFunctionsCollectorBase.register()` throws `DF0019` when a definition has `agent` set but is not declared `jsonSerializable: true`.
+- [`packages/devframe/src/rpc/collector.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/collector.ts): `RpcFunctionsCollectorBase.register()` throws `DF0019` when a definition combines `agent` with `jsonSerializable: false`.

packages/devframe/src/rpc/collector.test.ts

@@ -2,13 +2,14 @@ import { describe, expect, it, vi } from 'vitest'
 import { RpcFunctionsCollectorBase } from './collector'
 
 describe('agent gating (DF0019)', () => {
-  it('rejects registration when agent is set without jsonSerializable: true', () => {
+  it('infers jsonSerializable: true when agent is set', () => {
     const collector = new RpcFunctionsCollectorBase({})
-    expect(() => collector.register({
+    collector.register({
       name: 'plugin:fn',
       agent: { description: 'x' },
       handler: () => 0,
-    } as any)).toThrowError(/MCP requires JSON-serializable/)
+    } as any)
+    expect(collector.get('plugin:fn')?.jsonSerializable).toBe(true)
   })
 
   it('rejects when agent + jsonSerializable: false', () => {
@@ -40,14 +41,15 @@ describe('agent gating (DF0019)', () => {
     } as any)).not.toThrow()
   })
 
-  it('also enforces the gate on update()', () => {
+  it('also infers jsonSerializable: true on update()', () => {
     const collector = new RpcFunctionsCollectorBase({})
     collector.register({ name: 'plugin:fn', handler: () => 0 } as any)
-    expect(() => collector.update({
+    collector.update({
       name: 'plugin:fn',
       agent: { description: 'x' },
       handler: () => 0,
-    } as any)).toThrowError(/MCP requires JSON-serializable/)
+    } as any)
+    expect(collector.get('plugin:fn')?.jsonSerializable).toBe(true)
   })
 })
 

packages/devframe/src/rpc/collector.ts

@@ -43,7 +43,7 @@ export class RpcFunctionsCollectorBase<
     if (this.definitions.has(fn.name) && !force) {
       throw diagnostics.DF0021({ name: fn.name })
     }
-    assertAgentJsonSerializable(fn)
+    fn = normalizeAgentJsonSerializable(fn)
     this.definitions.set(fn.name, fn)
     this._onChanged.forEach(cb => cb(fn.name))
   }
@@ -52,7 +52,7 @@ export class RpcFunctionsCollectorBase<
     if (!this.definitions.has(fn.name) && !force) {
       throw diagnostics.DF0022({ name: fn.name })
     }
-    assertAgentJsonSerializable(fn)
+    fn = normalizeAgentJsonSerializable(fn)
     this.definitions.set(fn.name, fn)
     this._onChanged.forEach(cb => cb(fn.name))
   }
@@ -94,9 +94,12 @@ export class RpcFunctionsCollectorBase<
   }
 }
 
-function assertAgentJsonSerializable(
-  fn: RpcFunctionDefinition<string, any, any, any, any, any, any>,
-): void {
-  if (fn.agent && fn.jsonSerializable !== true)
+function normalizeAgentJsonSerializable<T extends RpcFunctionDefinition<string, any, any, any, any, any, any>>(
+  fn: T,
+): T {
+  if (fn.agent && fn.jsonSerializable === false)
     throw diagnostics.DF0019({ name: fn.name })
+  if (fn.agent && fn.jsonSerializable === undefined)
+    return { ...fn, jsonSerializable: true }
+  return fn
 }

packages/devframe/src/rpc/diagnostics.ts

@@ -5,8 +5,8 @@ export const diagnostics = defineDiagnostics({
   codes: {
     DF0019: {
       why: (p: { name: string }) =>
-        `RPC 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 RPC-only.',
+        `RPC 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 RPC-only.',
     },
     DF0020: {
       why: (p: { name: string, type: string, path: string }) =>

packages/devframe/src/rpc/types.ts

@@ -178,7 +178,7 @@ export interface RpcFunctionDefinitionBase {
    * - `true`: args and return are encoded with strict `JSON.stringify`
    *   on the wire and on disk. Misshapen values throw `DF0019` at the
    *   sender, surfacing the bug *during the offending call* rather than
-   *   silently coercing to `{}` later. Required for `agent` exposure.
+   *   silently coercing to `{}` later. Inferred for `agent` exposure.
    * - `false` (default): payloads use `structured-clone-es`, which
    *   round-trips Maps/Sets/cycles. Functions in this mode cannot be
    *   exposed via the `agent` field; registration throws `DF0018`.
@@ -249,7 +249,7 @@ export type RpcFunctionDefinition<
          * (no Map/Set/Date/BigInt/cycles/class instances/undefined/Symbol/Function).
          *
          * - `true`: wire and dump use strict `JSON.stringify`; misshapen
-         *   values throw `DF0019` at the call site. Required for `agent`.
+         *   values throw `DF0019` at the call site. Inferred for `agent`.
          * - `false` (default): `structured-clone-es` round-trips fancy
          *   types. Cannot be `agent`-exposed (registration throws `DF0018`).
          */
@@ -295,7 +295,7 @@ export type RpcFunctionDefinition<
          * (no Map/Set/Date/BigInt/cycles/class instances/undefined/Symbol/Function).
          *
          * - `true`: wire and dump use strict `JSON.stringify`; misshapen
-         *   values throw `DF0019` at the call site. Required for `agent`.
+         *   values throw `DF0019` at the call site. Inferred for `agent`.
          * - `false` (default): `structured-clone-es` round-trips fancy
          *   types. Cannot be `agent`-exposed (registration throws `DF0018`).
          */