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

alias.ts

@@ -31,7 +31,6 @@ export const alias = {
   'devframe/utils/shared-state': r('devframe/src/utils/shared-state.ts'),
   'devframe/utils/streaming-channel': r('devframe/src/utils/streaming-channel.ts'),
   'devframe/utils/structured-clone': r('devframe/src/utils/structured-clone.ts'),
-  'devframe/utils/valibot-json-schema': r('devframe/src/utils/valibot-json-schema.ts'),
   'devframe/utils/when': r('devframe/src/utils/when.ts'),
   'devframe/adapters/cac': r('devframe/src/adapters/cac.ts'),
   'devframe/adapters/cli': r('devframe/src/adapters/cli.ts'),

packages/devframe/package.json

@@ -54,7 +54,6 @@
     "./utils/shared-state": "./dist/utils/shared-state.mjs",
     "./utils/streaming-channel": "./dist/utils/streaming-channel.mjs",
     "./utils/structured-clone": "./dist/utils/structured-clone.mjs",
-    "./utils/valibot-json-schema": "./dist/utils/valibot-json-schema.mjs",
     "./utils/when": "./dist/utils/when.mjs",
     "./package.json": "./package.json"
   },

packages/devframe/src/adapters/mcp/to-json-schema.ts

@@ -1,4 +1,4 @@
-// Moved to `devframe/utils/valibot-json-schema` so hosts without the MCP SDK
-// (e.g. the hub's commands→agent bridge) can convert schemas too. This module
-// keeps the adapter-local import path stable.
-export { valibotArgsToJsonSchema, valibotReturnToJsonSchema } from 'devframe/utils/valibot-json-schema'
+// Shared internal conversion (also used by the agent host to project
+// `AgentToolInput.args`); this module keeps the adapter-local import path
+// stable.
+export { valibotArgsToJsonSchema, valibotReturnToJsonSchema } from '../../utils/valibot-json-schema'

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

@@ -16,6 +16,7 @@ import type {
   RpcFunctionAgentOptions,
 } from 'devframe/types'
 import { createEventEmitter } from 'devframe/utils/events'
+import { valibotArgsToJsonSchema } from '../utils/valibot-json-schema'
 import { diagnostics } from './diagnostics'
 
 interface RegisteredTool {
@@ -211,7 +212,10 @@ export class DevframeAgentHost implements DevframeAgentHostType {
       description: input.description,
       safety: input.safety ?? 'action',
       tags: input.tags,
-      inputSchema: input.inputSchema,
+      // Valibot args are the source of truth (mirroring RPC definitions);
+      // an explicit JSON-Schema override wins when given.
+      inputSchema: input.inputSchema
+        ?? (input.args?.length ? valibotArgsToJsonSchema(input.args).schema : undefined),
       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 { GenericSchema } from 'valibot'
 import type { RpcFunctionAgentOptions } from '../rpc/types'
 import type { EventEmitter } from './events'
 
@@ -44,6 +45,15 @@ export interface AgentToolInput {
   description: string
   safety?: 'read' | 'action' | 'destructive'
   tags?: readonly string[]
+  /**
+   * Positional valibot schemas describing the tool's arguments — the same
+   * shape RPC definitions carry. The host derives the tool's JSON-Schema
+   * input from them (a single `v.object(...)` schema is unwrapped — the
+   * friendliest shape at the agent boundary). Purely descriptive: the
+   * handler still receives the caller's args object as-is.
+   */
+  args?: readonly GenericSchema[]
+  /** Raw JSON-Schema input override. Prefer {@link args}. */
   inputSchema?: unknown
   outputSchema?: unknown
   examples?: readonly { args: unknown[], description?: string }[]

packages/devframe/tsdown.config.ts

@@ -99,7 +99,6 @@ const serverEntries = {
   'utils/launch-editor': 'src/utils/launch-editor.ts',
   'utils/open': 'src/utils/open.ts',
   'utils/serve-static': 'src/utils/serve-static.ts',
-  'utils/valibot-json-schema': 'src/utils/valibot-json-schema.ts',
   'adapters/cac': 'src/adapters/cac.ts',
   'adapters/cli': 'src/adapters/cli.ts',
   'adapters/dev': 'src/adapters/dev.ts',

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 {
@@ -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 ?? [])
@@ -203,17 +203,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.
+ * schemas → zero-arg call; a single `v.object(...)` schema (unwrapped at the
+ * tool boundary) → the object itself; positional schemas → `arg0..argN` keys
+ * in order.
  */
 function coercePositionalArgs(
   args: unknown,
-  schemas: readonly unknown[] | undefined,
-  unwrapped: boolean,
+  schemas: DevframeCommandAgentOptions['args'],
 ): unknown[] {
   if (!schemas || schemas.length === 0)
     return []
-  if (unwrapped)
+  if (schemas.length === 1 && schemas[0]!.type === 'object')
     return [args ?? {}]
   const obj = (args ?? {}) as Record<string, unknown>
   return schemas.map((_, i) => obj[`arg${i}`])

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.