refactor(agent): shrink the public API surface

- drop the devframe/utils/valibot-json-schema subpath: AgentToolInput
  gains valibot args (the same shape RPC definitions carry); the agent
  host derives the JSON-Schema input internally, and the hub passes
  schemas through untouched — conversion is an implementation detail
  again
- devframe/node exports only registerDevframeInstance (+ its two types)
  from the instance registry; the read/probe/prune helpers stay internal
  to the connector

Author: antfubot

packages/devframe/src/adapters/mcp/build-server.ts

@@ -348,6 +348,8 @@ function projectTool(tool: AgentTool, ctx: DevframeNodeContext): Tool {
 }
 
 function computeInputSchema(tool: AgentTool, ctx: DevframeNodeContext): unknown {
+  if (tool.kind === 'tool')
+    return argsToJsonSchema(tool.args).schema
   if (tool.kind !== 'rpc' || !tool.rpcName)
     return { type: 'object', properties: {} }
   const def = ctx.rpc.definitions.get(tool.rpcName) as RpcFunctionDefinitionAnyWithContext<DevframeNodeContext> | undefined

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

@@ -270,6 +270,39 @@ describe('devToolsAgentHost', () => {
     })
   })
 
+  describe('valibot args on tool inputs', () => {
+    it('derives the JSON-Schema input from a single object schema (unwrapped)', async () => {
+      const v = await import('valibot')
+      const ctx = createContext()
+      ctx.agent.registerTool({
+        id: 'schema:tool',
+        description: 'Schema-typed.',
+        args: [v.object({ name: v.optional(v.string()) })],
+        handler: args => args,
+      })
+
+      const tool = ctx.agent.getTool('schema:tool')!
+      const schema = tool.inputSchema as { type: string, properties: Record<string, unknown> }
+      expect(schema.type).toBe('object')
+      expect(Object.keys(schema.properties)).toEqual(['name'])
+    })
+
+    it('an explicit inputSchema override wins over args', async () => {
+      const v = await import('valibot')
+      const ctx = createContext()
+      ctx.agent.registerTool({
+        id: 'override:tool',
+        description: 'Override.',
+        args: [v.object({ ignored: v.string() })],
+        inputSchema: { type: 'object', properties: { custom: { type: 'string' } } },
+        handler: () => {},
+      })
+
+      const schema = ctx.agent.getTool('override:tool')!.inputSchema as { properties: Record<string, unknown> }
+      expect(Object.keys(schema.properties)).toEqual(['custom'])
+    })
+  })
+
   describe('registerToolProvider()', () => {
     it('queries the provider lazily on list/getTool/invoke', async () => {
       const ctx = createContext()

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

@@ -211,6 +211,11 @@ export class DevframeAgentHost implements DevframeAgentHostType {
       description: input.description,
       safety: input.safety ?? 'action',
       tags: input.tags,
+      // Standard Schema `args` are carried raw (mirroring how an RPC-backed
+      // tool defers to `ctx.rpc.definitions`) — consumers (the MCP adapter)
+      // convert to JSON Schema on demand. An explicit `inputSchema` override
+      // wins when given.
+      args: input.args,
       inputSchema: input.inputSchema,
       outputSchema: input.outputSchema,
       examples: input.examples,

packages/devframe/src/node/index.ts

@@ -9,7 +9,10 @@ export type { RpcFunctionsHost } from './host-functions'
 export * from './host-h3'
 export * from './host-services'
 export * from './host-views'
-export * from './instance-registry'
+// Only registration is public — custom hosts (e.g. @devframes/next) record
+// themselves; the read/probe/prune helpers stay internal to the connector.
+export { registerDevframeInstance } from './instance-registry'
+export type { DevframeInstanceRecord, DevframeInstanceRegistration } from './instance-registry'
 export * from './rpc-shared-state'
 export * from './rpc-streaming'
 export * from './scope'

packages/devframe/src/types/agent.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { RpcFunctionAgentOptions } from '../rpc/types'
 import type { EventEmitter } from './events'
 
@@ -24,6 +25,14 @@ export interface AgentTool {
   tags?: readonly string[]
   /** Present for `kind === 'rpc'` — points to the RPC function name. */
   rpcName?: string
+  /**
+   * Positional Standard Schemas describing a `kind: 'tool'` entry's
+   * arguments — carried on the tool itself (mirroring how `rpcName` defers
+   * an RPC-backed tool's schemas to `ctx.rpc.definitions`) so consumers
+   * (e.g. the MCP adapter) convert Standard Schema → JSON Schema on demand,
+   * same as RPC `args`.
+   */
+  args?: readonly StandardSchemaV1[]
   /** JSON Schema describing the input (positional args synthesized to an object). */
   inputSchema?: unknown
   /** JSON Schema describing the output. */
@@ -44,6 +53,17 @@ export interface AgentToolInput {
   description: string
   safety?: 'read' | 'action' | 'destructive'
   tags?: readonly string[]
+  /**
+   * Positional Standard Schemas describing the tool's arguments — the same
+   * shape RPC definitions carry (any [Standard Schema](https://standardschema.dev/)
+   * validator: valibot, zod, arktype, devframe's built-in `s` builder, …).
+   * Each is advertised under `arg0` / `arg1` / … on the tool's JSON-Schema
+   * input, matching how the agent bridge coerces the incoming payload back
+   * into positional arguments. Purely descriptive: the handler still
+   * receives the caller's args object as-is.
+   */
+  args?: readonly StandardSchemaV1[]
+  /** Raw JSON-Schema input override. Prefer {@link args}. */
   inputSchema?: unknown
   outputSchema?: unknown
   examples?: readonly { args: unknown[], description?: string }[]

packages/hub/package.json

@@ -42,19 +42,20 @@
     "devframe": "workspace:*"
   },
   "dependencies": {
+    "@standard-schema/spec": "catalog:deps",
     "birpc": "catalog:deps",
     "destr": "catalog:deps",
     "nostics": "catalog:deps",
     "pathe": "catalog:deps",
     "perfect-debounce": "catalog:deps",
     "tinyexec": "catalog:deps",
-    "valibot": "catalog:deps",
     "zigpty": "catalog:deps"
   },
   "devDependencies": {
     "@types/node": "catalog:types",
     "devframe": "workspace:*",
     "mlly": "catalog:build",
-    "tsdown": "catalog:build"
+    "tsdown": "catalog:build",
+    "valibot": "catalog:deps"
   }
 }

packages/hub/src/node/__tests__/host-commands.test.ts

@@ -110,9 +110,10 @@ describe('devframeCommandsHost agent bridge', () => {
     expect((tool.inputSchema as { type: string }).type).toBe('object')
     expect(agent.list().tools.map(t => t.id)).toEqual(['demo:greet'])
 
-    // A single object args schema is unwrapped — the MCP args object lands
-    // as the handler's first positional argument.
-    await expect(agent.invoke('demo:greet', { name: 'devframe' })).resolves.toBe('done')
+    // Each declared arg schema is advertised (and read back) under its own
+    // `argN` key — the MCP args object's `arg0` becomes the handler's first
+    // positional argument.
+    await expect(agent.invoke('demo:greet', { arg0: { name: 'devframe' } })).resolves.toBe('done')
     expect(calls).toEqual([[{ name: 'devframe' }]])
   })
 

packages/hub/src/node/host-commands.ts

@@ -1,13 +1,13 @@
 import type { AgentToolInput, AgentToolProviderHandle } from 'devframe/types'
 import type {
+  DevframeCommandAgentOptions,
   DevframeCommandHandle,
   DevframeCommandsHost as DevframeCommandsHostType,
   DevframeServerCommandEntry,
   DevframeServerCommandInput,
 } from '../types/commands'
 import type { DevframeHubContext } from './context'
 import { createEventEmitter } from 'devframe/utils/events'
-import { valibotArgsToJsonSchema } from 'devframe/utils/valibot-json-schema'
 import { diagnostics } from './diagnostics'
 
 function findChildCommand(command: DevframeServerCommandInput, id: string): DevframeServerCommandInput | undefined {
@@ -145,7 +145,7 @@ export class DevframeCommandsHost implements DevframeCommandsHostType {
   }
 
   private toSerializable(cmd: DevframeServerCommandInput): DevframeServerCommandEntry {
-    // `agent` stays server-side: it carries valibot schemas (not wire-safe)
+    // `agent` stays server-side: it carries Standard Schema validators (not wire-safe)
     // and only concerns the agent projection, not the palette.
     const { handler: _, agent: __, children, ...rest } = cmd
     return {
@@ -179,16 +179,16 @@ export class DevframeCommandsHost implements DevframeCommandsHostType {
     const walk = (command: DevframeServerCommandInput): void => {
       const agent = command.agent
       if (agent && command.handler) {
-        const { schema, unwrapped } = valibotArgsToJsonSchema(agent.args)
         tools.push({
           id: command.id,
           title: agent.title ?? command.title,
           description: agent.description,
           safety: agent.safety ?? 'action',
           tags: agent.tags,
-          inputSchema: schema,
+          // The agent host derives the tool's JSON-Schema input from these.
+          args: agent.args,
           handler: async (args: unknown) =>
-            this.execute(command.id, ...coercePositionalArgs(args, agent.args, unwrapped)),
+            this.execute(command.id, ...coercePositionalArgs(args, agent.args)),
         })
       }
       for (const child of command.children ?? [])
@@ -201,20 +201,17 @@ export class DevframeCommandsHost implements DevframeCommandsHostType {
 }
 
 /**
- * Map the single-object args an MCP client sends onto the command handler's
- * positional parameters, mirroring the agent host's RPC coercion: no declared
- * schemas → zero-arg call; a single unwrapped object schema → the object
- * itself; positional schemas → `arg0..argN` keys in order.
+ * Map the `arg0`/`arg1`/… keyed object an MCP client sends onto the command
+ * handler's positional parameters — mirroring the agent host's RPC
+ * coercion: no declared schemas → zero-arg call; each declared schema reads
+ * its own `argN` key, in order.
  */
 function coercePositionalArgs(
   args: unknown,
-  schemas: readonly unknown[] | undefined,
-  unwrapped: boolean,
+  schemas: DevframeCommandAgentOptions['args'],
 ): unknown[] {
   if (!schemas || schemas.length === 0)
     return []
-  if (unwrapped)
-    return [args ?? {}]
   const obj = (args ?? {}) as Record<string, unknown>
   return schemas.map((_, i) => obj[`arg${i}`])
 }

packages/hub/src/types/commands.ts

@@ -1,5 +1,5 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { EventEmitter } from 'devframe/types'
-import type { GenericSchema } from 'valibot'
 import type { DevframeDockEntryIcon } from './docks'
 
 export interface DevframeCommandKeybinding {
@@ -73,12 +73,13 @@ export interface DevframeCommandAgentOptions {
   /** Free-form tags for grouping/filtering. */
   tags?: readonly string[]
   /**
-   * Positional valibot schemas for the handler's arguments, converted to the
-   * tool's JSON-Schema input (a single `v.object(...)` schema is unwrapped —
-   * the friendliest shape at the agent boundary). Omitted: the tool takes no
-   * arguments.
+   * Positional [Standard Schema](https://standardschema.dev/) validators for
+   * the handler's arguments — the same shape RPC definitions carry (valibot,
+   * zod, arktype, devframe's built-in `s` builder, …). Each is advertised
+   * under `arg0` / `arg1` / … on the tool's JSON-Schema input. Omitted: the
+   * tool takes no arguments.
    */
-  args?: readonly GenericSchema[]
+  args?: readonly StandardSchemaV1[]
 }
 
 /**

plans/031-agent-native-mcp-wave.md

@@ -69,8 +69,9 @@ literal "/_next/mcp" shape on devframe primitives.
    resource projection (which stays — many clients only consume tools).
 7. **Hub commands → agent bridge** — opt-in `agent?: { description, safety?,
    args? }` on `DevframeServerCommandInput` (mirrors the RPC convention;
-   description required; optional valibot args schema reusing
-   `valibotArgsToJsonSchema`, zero-arg default). `createHubContext` projects
+   description required; optional valibot args schemas carried through
+   `AgentToolInput.args` — JSON-Schema conversion stays an internal detail of
+   the agent host/MCP adapter; zero-arg default). `createHubContext` projects
    agent-flagged, handler-bearing server commands into `ctx.agent` tools,
    tracking register/update/unregister. `when` clauses evaluate client-side
    only and are **not** enforced for agent calls — documented caveat.