refactor: clarify tool input coercion

packages/devframe/src/__tests__/tool-input.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import { toolInputToCommandArgs, toolInputToRpcArgs } from '../tool-input'
+
+describe('tool input positional arguments', () => {
+  it('passes arrays through and maps argN keys using the declared count', () => {
+    expect(toolInputToRpcArgs([1, 2], 2)).toEqual([1, 2])
+    expect(toolInputToRpcArgs({ arg0: 'a', arg1: 'b' }, 2)).toEqual(['a', 'b'])
+    expect(toolInputToRpcArgs({ arg0: 'a' }, 0)).toEqual([])
+  })
+
+  it('collects contiguous argN keys without a declared count', () => {
+    expect(toolInputToRpcArgs({ arg0: 1, arg1: 2 })).toEqual([1, 2])
+  })
+
+  it('treats null, undefined, and empty objects as zero-argument calls', () => {
+    expect(toolInputToRpcArgs(undefined)).toEqual([])
+    expect(toolInputToRpcArgs(null, 1)).toEqual([])
+    expect(toolInputToRpcArgs({})).toEqual([])
+  })
+
+  it('preserves undeclared RPC input as one argument', () => {
+    const input = { name: 'devframe' }
+    expect(toolInputToRpcArgs(input)).toEqual([input])
+  })
+
+  it('drops undeclared command input', () => {
+    expect(toolInputToCommandArgs({ name: 'devframe' })).toEqual([])
+  })
+})

packages/devframe/src/client/webmcp.ts

@@ -4,7 +4,7 @@ import { toAgentToolName } from 'devframe/utils/agent-tool-name'
 // Pure, browser-safe projections shared with the node-side MCP adapter, so
 // the WebMCP surface cannot drift from the MCP one.
 import { argsToJsonSchema } from '../adapters/mcp/to-json-schema'
-import { coerceAgentPositionalArgs } from '../node/agent-args'
+import { toolInputToRpcArgs } from '../tool-input'
 
 /**
  * Result a WebMCP tool's `execute` resolves with; mirrors the MCP
@@ -195,7 +195,7 @@ async function executeRpcTool<SetupContext>(
   args: Record<string, unknown>,
 ): Promise<WebMcpToolResult> {
   try {
-    const positional = coerceAgentPositionalArgs(args, def.args as readonly unknown[] | undefined, 'wrap')
+    const positional = toolInputToRpcArgs(args, def.args?.length)
     const handler = await getRpcHandler(def, context)
     const result = await handler(...positional)
     return { content: [{ type: 'text', text: stringifyResult(result) }] }

packages/devframe/src/internal/index.ts

@@ -9,8 +9,8 @@
 //   session/auth wiring the instance shell's own binding uses.
 // - `DevframeAgentHost`: the agent host implementation the hub composes into
 //   its own commands host.
-// - `coerceAgentPositionalArgs`: positional-arg coercion the hub applies when
-//   invoking agent tools as commands.
+// - `toolInputToCommandArgs`: positional-argument conversion the hub applies
+//   when invoking tool-backed commands.
 // - `registerDevframeInstance` / `listLiveDevframeInstances`: the instance
 //   registry: a custom host advertises itself; a devtool (the inspect plugin's
 //   Instances tab, the connector) enumerates what's running.
@@ -40,8 +40,6 @@
 export { loadAutoMcpAdapter, normalizeBasePath, resolveBasePath, resolveMcpConfig } from '../adapters/_shared'
 export type { ResolvedMcpConfig } from '../adapters/_shared'
 export { resolveClientAssets } from '../client-assets'
-export { coerceAgentPositionalArgs } from '../node/agent-args'
-export type { AgentArgsFallback } from '../node/agent-args'
 export { diagnostics } from '../node/diagnostics'
 export { DevframeAgentHost } from '../node/host-agent'
 export * from '../node/host-h3'
@@ -64,3 +62,5 @@ export type { ContextRpcServer, CreateContextRpcServerOptions } from '../node/rp
 export { normalizeHttpServerUrl } from '../node/utils'
 export { createRpcWireCodec, peekRpcWireFrame } from '../rpc/wire-codec'
 export type { RpcWireCodec } from '../rpc/wire-codec'
+export { coerceAgentPositionalArgs, toolInputToCommandArgs } from '../tool-input'
+export type { AgentArgsFallback } from '../tool-input'

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

@@ -17,7 +17,7 @@ import type {
 } from 'devframe/types'
 import { createEventEmitter } from 'devframe/utils/events'
 import { DEVFRAME_EVENTS } from '../events'
-import { coerceAgentPositionalArgs } from './agent-args'
+import { toolInputToRpcArgs } from '../tool-input'
 import { diagnostics } from './diagnostics'
 
 interface RegisteredTool {
@@ -184,7 +184,7 @@ export class DevframeAgentHost implements DevframeAgentHostType {
       // (what the MCP adapter sends after flattening), or a plain array.
       // An untyped RPC may take a single raw object, so undeclared object
       // payload wraps into one positional argument.
-      const positional = coerceAgentPositionalArgs(args, rpcDef.args as readonly unknown[] | undefined, 'wrap')
+      const positional = toolInputToRpcArgs(args, rpcDef.args?.length)
       return await this.context.rpc.invokeLocal(id as any, ...(positional as any))
     }
 

packages/devframe/src/tool-input.ts

@@ -0,0 +1,50 @@
+/**
+ * Convert an object-shaped tool input into positional arguments.
+ *
+ * Tool schemas expose positional parameters as `arg0`, `arg1`, and so on.
+ * Arrays pass through for callers that already provide positional arguments.
+ */
+function collectPositionalArgs(input: unknown, argumentCount: number | undefined): unknown[] | undefined {
+  if (Array.isArray(input))
+    return input
+  if (input === undefined || input === null)
+    return []
+  if (typeof input !== 'object')
+    return undefined
+
+  const record = input as Record<string, unknown>
+  if (argumentCount != null)
+    return Array.from({ length: argumentCount }, (_, index) => record[`arg${index}`])
+  if ('arg0' in record) {
+    const positional: unknown[] = []
+    while (`arg${positional.length}` in record)
+      positional.push(record[`arg${positional.length}`])
+    return positional
+  }
+  return Object.keys(record).length === 0 ? [] : undefined
+}
+
+/** Convert tool input for an RPC, preserving an untyped payload as arg 0. */
+export function toolInputToRpcArgs(input: unknown, argumentCount?: number): unknown[] {
+  return collectPositionalArgs(input, argumentCount) ?? [input]
+}
+
+/** Convert tool input for a command, whose arguments must be declared. */
+export function toolInputToCommandArgs(input: unknown, argumentCount?: number): unknown[] {
+  return collectPositionalArgs(input, argumentCount) ?? []
+}
+
+/** @deprecated Use {@link toolInputToRpcArgs} or {@link toolInputToCommandArgs}. */
+export type AgentArgsFallback = 'wrap' | 'drop'
+
+/** @deprecated Use {@link toolInputToRpcArgs} or {@link toolInputToCommandArgs}. */
+export function coerceAgentPositionalArgs(
+  input: unknown,
+  schemas: readonly unknown[] | undefined,
+  fallback: AgentArgsFallback = 'wrap',
+): unknown[] {
+  const argumentCount = schemas?.length
+  return fallback === 'drop'
+    ? toolInputToCommandArgs(input, argumentCount)
+    : toolInputToRpcArgs(input, argumentCount)
+}

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

@@ -6,7 +6,7 @@ import type {
   DevframeServerCommandInput,
 } from '../types/commands'
 import type { DevframeHubContext } from './context'
-import { coerceAgentPositionalArgs } from 'devframe/internal'
+import { toolInputToCommandArgs } from 'devframe/internal'
 import { createEventEmitter } from 'devframe/utils/events'
 import { HUB_EVENTS } from '../events'
 import { diagnostics } from './diagnostics'
@@ -193,7 +193,7 @@ export class DevframeCommandsHost implements DevframeCommandsHostType {
            * declared `agent.args` schemas; undeclared payload is dropped.
            */
           handler: async (args: unknown) =>
-            this.execute(command.id, ...coerceAgentPositionalArgs(args, agent.args, 'drop')),
+            this.execute(command.id, ...toolInputToCommandArgs(args, agent.args?.length)),
         })
       }
       for (const child of command.children ?? [])

tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts

@@ -15,6 +15,7 @@ export interface RpcWireCodec {
 // #endregion
 
 // #region Types
+/** @deprecated */
 export type AgentArgsFallback = 'wrap' | 'drop';
 // #endregion
 
@@ -48,6 +49,7 @@ export declare class DevframeAgentHost implements DevframeAgentHost$1 {
 // #endregion
 
 // #region Functions
+/** @deprecated */
 export declare function coerceAgentPositionalArgs(_: unknown, _: readonly unknown[] | undefined, _?: AgentArgsFallback): unknown[];
 export declare function createH3DevframeHost(_: CreateH3DevframeHostOptions): DevframeHost;
 export declare function createRpcWireCodec(_?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>): RpcWireCodec;
@@ -58,6 +60,7 @@ export declare function peekRpcWireFrame(_: string): {
   i?: string;
 };
 export declare function resolveClientAssets(_: DevframeDefinition): StaticAssetsSource | undefined;
+export declare function toolInputToCommandArgs(_: unknown, _?: number): unknown[];
 // #endregion
 
 // #region Variables

tests/__snapshots__/tsnapi/devframe/internal.snapshot.js

@@ -21,4 +21,5 @@ export { resolveClientAssets }
 export { resolveInstanceRegister }
 export { resolveMcpConfig }
 export { samePath }
+export { toolInputToCommandArgs }
 // #endregion