fix(agent-core-v2): coerce string-typed tool arguments at the parse boundary

.changeset/tool-args-type-coercion.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix tool calls failing validation when a model sends numeric or boolean arguments as strings.

packages/agent-core-v2/src/agent/toolExecutor/toolExecutorService.ts

@@ -7,7 +7,10 @@
  * through the ordered `onDidExecuteTool` hook, publishes tool lifecycle
  * events through `event`, records telemetry through `telemetry`, truncates
  * oversized outputs through `toolResultTruncation`, and logs parse
- * diagnostics through `log`. Bound at Agent scope.
+ * diagnostics through `log`. Non-conforming argument types are normalized
+ * through the `tool` domain's args normalization before validation, with
+ * coercions surfaced as model-visible notes on the tool result. Bound at
+ * Agent scope.
  */
 
 import { InstantiationType } from '#/_base/di/extensions';
@@ -23,6 +26,7 @@ import {
   type JsonType,
   type ToolArgsValidator,
 } from '#/tool/args-validator';
+import { normalizeToolArgs, type ArgCoercion } from '#/tool/args-normalize';
 import { PathSecurityError } from '#/tool/path-access';
 import { isAbortError, isUserCancellation } from '#/_base/utils/abort';
 import { IEventBus } from '#/app/event/eventBus';
@@ -600,7 +604,10 @@ export class AgentToolExecutorService implements IAgentToolExecutorService {
 
     const coercedResult = coerceToolResult(didCtx.result, call.toolName);
     const effectiveResult = normalizeToolResult(coercedResult);
-    const finalResult: ToolResult = {
+    const mergedNote = [call.normalizationNote, effectiveResult.note]
+      .filter((part): part is string => typeof part === 'string' && part.length > 0)
+      .join('\n');
+    const baseResult = {
       ...effectiveResult,
       description: result.description,
       display: result.display,
@@ -612,6 +619,8 @@ export class AgentToolExecutorService implements IAgentToolExecutorService {
       stopBatchAfterThis: result.stopBatchAfterThis,
       delivery: coercedResult.delivery,
     };
+    const finalResult: ToolResult =
+      mergedNote.length > 0 ? { ...baseResult, note: mergedNote } : baseResult;
     return this.resultTruncation.truncateForModel({
       toolName: call.toolName,
       toolCallId: call.toolCall.id,
@@ -626,6 +635,7 @@ interface RunnableToolCall {
   readonly toolName: string;
   readonly tool: ExecutableTool;
   readonly args: unknown;
+  readonly normalizationNote?: string;
 }
 
 interface RejectedToolCall {
@@ -715,17 +725,37 @@ function preflightToolCall(
       output: unavailable,
     };
   }
-  const validationError = validateExecutableToolArgs(tool, parsedArgs.data);
+  const normalization = normalizeToolArgs(tool.parameters, parsedArgs.data);
+  if (normalization.coercions.length > 0) {
+    log?.debug('tool args coerced to match schema', {
+      toolName,
+      toolCallId: toolCall.id,
+      coercions: normalization.coercions
+        .map((coercion) => `${coercion.path}: ${coercion.received} -> ${coercion.expected}`)
+        .join('; '),
+    });
+  }
+  const validationError = validateExecutableToolArgs(tool, normalization.args);
   if (validationError !== null) {
     return {
       kind: 'rejected',
       toolCall,
       toolName,
-      args: parsedArgs.data,
+      args: normalization.args,
       output: `Invalid args for tool "${toolName}": ${validationError}`,
     };
   }
-  return { kind: 'runnable', toolCall, toolName, tool, args: parsedArgs.data };
+  return {
+    kind: 'runnable',
+    toolCall,
+    toolName,
+    tool,
+    args: normalization.args,
+    normalizationNote:
+      normalization.coercions.length > 0
+        ? coercionNote(toolName, normalization.coercions)
+        : undefined,
+  };
 }
 
 export function parseToolCallArguments(raw: unknown): {
@@ -746,6 +776,13 @@ export function parseToolCallArguments(raw: unknown): {
   }
 }
 
+function coercionNote(toolName: string, coercions: readonly ArgCoercion[]): string {
+  const details = coercions
+    .map((coercion) => `${coercion.path}: ${coercion.received} -> ${coercion.expected}`)
+    .join('; ');
+  return `<system>Note: tool "${toolName}" received argument type(s) that did not match its schema (${details}). They were coerced to the declared types before validation. Emit argument types exactly as the tool schema declares.</system>`;
+}
+
 function validateExecutableToolArgs(tool: ExecutableTool, args: unknown): string | null {
   let validator = validators.get(tool);
   if (validator === undefined) {

packages/agent-core-v2/src/tool/args-normalize.ts

@@ -0,0 +1,206 @@
+/**
+ * `tool` domain (L3) — pre-validation tool-args normalization.
+ *
+ * Model tool-call output is untrusted input: some providers emit primitive
+ * arguments as JSON strings (`"3"` for an integer) instead of the declared
+ * types. The harness absorbs that at the parse/validation boundary — the
+ * earliest point it controls — while keeping validation itself strict.
+ *
+ * The rules are deliberately generic and bounded so this layer stays a single
+ * schema-driven rule instead of growing into a catalog of model-specific
+ * hacks:
+ *   - only string → integer / number / boolean coercions are attempted
+ *   - only when the coercion is lossless and the schema does not already
+ *     accept strings at that position
+ *   - `$ref` nodes and ambiguous (string-accepting) schemas are left alone
+ *   - composition keywords are consulted for type discovery only, never as a
+ *     proof of validity; under-coercion is deliberate, since whatever this
+ *     layer misses still faces strict validation below
+ *
+ * Whatever cannot be normalized still fails validation afterwards, where the
+ * error message reports what was actually received. Pure helper; no scoped
+ * service.
+ */
+
+export type CoercionTarget = 'integer' | 'number' | 'boolean';
+
+export interface ArgCoercion {
+  readonly path: string;
+  readonly received: string;
+  readonly expected: CoercionTarget;
+}
+
+export interface ArgsNormalization {
+  readonly args: unknown;
+  readonly coercions: readonly ArgCoercion[];
+}
+
+const INTEGER_TEXT = /^[+-]?\d+$/;
+const NUMBER_TEXT = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+type PrimitiveType = 'string' | 'integer' | 'number' | 'boolean' | 'object' | 'array' | 'null';
+
+function collectPrimitiveTypes(node: Record<string, unknown>, into: Set<PrimitiveType>): void {
+  const type = node['type'];
+  if (typeof type === 'string') into.add(type as PrimitiveType);
+  if (Array.isArray(type)) {
+    for (const entry of type) {
+      if (typeof entry === 'string') into.add(entry as PrimitiveType);
+    }
+  }
+  for (const keyword of ['anyOf', 'oneOf', 'allOf'] as const) {
+    const branches = node[keyword];
+    if (Array.isArray(branches)) {
+      for (const branch of branches) {
+        if (branch !== null && typeof branch === 'object' && !Array.isArray(branch)) {
+          collectPrimitiveTypes(branch as Record<string, unknown>, into);
+        }
+      }
+    }
+  }
+}
+
+function isSchemaNode(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isUnconstrained(node: Record<string, unknown>): boolean {
+  return (
+    node['type'] === undefined &&
+    node['const'] === undefined &&
+    node['enum'] === undefined &&
+    node['$ref'] === undefined
+  );
+}
+
+function stringAlreadyValid(node: Record<string, unknown>, raw: string): boolean {
+  if (node['const'] === raw) return true;
+  const enumValues = node['enum'];
+  if (Array.isArray(enumValues) && enumValues.includes(raw)) return true;
+  for (const keyword of ['anyOf', 'oneOf'] as const) {
+    const branches = node[keyword];
+    if (!Array.isArray(branches)) continue;
+    for (const branch of branches) {
+      if (!isSchemaNode(branch)) continue;
+      if (isUnconstrained(branch) || stringAlreadyValid(branch, raw)) return true;
+    }
+  }
+  return false;
+}
+
+function coerceString(
+  raw: string,
+  expected: ReadonlySet<PrimitiveType>,
+): { readonly value: number | boolean; readonly target: CoercionTarget } | undefined {
+  if (expected.has('integer') && INTEGER_TEXT.test(raw)) {
+    const parsed = Number(raw);
+    if (Number.isSafeInteger(parsed)) return { value: parsed, target: 'integer' };
+    return undefined;
+  }
+  if (expected.has('number') && NUMBER_TEXT.test(raw)) {
+    const parsed = Number(raw);
+    const lossless = INTEGER_TEXT.test(raw) ? Number.isSafeInteger(parsed) : Number.isFinite(parsed);
+    if (lossless) return { value: parsed, target: 'number' };
+    return undefined;
+  }
+  if (expected.has('boolean') && (raw === 'true' || raw === 'false')) {
+    return { value: raw === 'true', target: 'boolean' };
+  }
+  return undefined;
+}
+
+export function describeReceivedValue(value: unknown): string {
+  if (typeof value === 'string') return `string ${JSON.stringify(value)}`;
+  if (typeof value === 'number') return `number ${String(value)}`;
+  if (typeof value === 'boolean') return `boolean ${String(value)}`;
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (Array.isArray(value)) return 'array';
+  return 'object';
+}
+
+function normalizeValue(
+  node: Record<string, unknown>,
+  value: unknown,
+  path: string,
+  coercions: ArgCoercion[],
+): unknown {
+  if (typeof value === 'string') {
+    const expected = new Set<PrimitiveType>();
+    collectPrimitiveTypes(node, expected);
+    if (!expected.has('string') && !stringAlreadyValid(node, value)) {
+      const coerced = coerceString(value, expected);
+      if (coerced !== undefined) {
+        coercions.push({
+          path,
+          received: describeReceivedValue(value),
+          expected: coerced.target,
+        });
+        return coerced.value;
+      }
+    }
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    const items = node['items'];
+    if (items !== null && typeof items === 'object' && !Array.isArray(items)) {
+      const itemSchema = items as Record<string, unknown>;
+      if (itemSchema['$ref'] === undefined) {
+        let changed: unknown[] | undefined;
+        for (let index = 0; index < value.length; index += 1) {
+          const normalized = normalizeValue(
+            itemSchema,
+            value[index],
+            `${path}/${String(index)}`,
+            coercions,
+          );
+          if (normalized !== value[index]) {
+            changed ??= [...value];
+            changed[index] = normalized;
+          }
+        }
+        return changed ?? value;
+      }
+    }
+    return value;
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const properties = node['properties'];
+    if (properties !== null && typeof properties === 'object' && !Array.isArray(properties)) {
+      const record = value as Record<string, unknown>;
+      let changed: Record<string, unknown> | undefined;
+      for (const [key, child] of Object.entries(properties)) {
+        if (child === null || typeof child !== 'object' || Array.isArray(child)) continue;
+        const childSchema = child as Record<string, unknown>;
+        if (childSchema['$ref'] !== undefined) continue;
+        if (!(key in record)) continue;
+        const normalized = normalizeValue(
+          childSchema,
+          record[key],
+          `${path}/${key.replace(/~/g, '~0').replace(/\//g, '~1')}`,
+          coercions,
+        );
+        if (normalized !== record[key]) {
+          changed ??= { ...record };
+          changed[key] = normalized;
+        }
+      }
+      return changed ?? value;
+    }
+    return value;
+  }
+
+  return value;
+}
+
+export function normalizeToolArgs(
+  schema: Record<string, unknown>,
+  args: unknown,
+): ArgsNormalization {
+  const coercions: ArgCoercion[] = [];
+  if (schema['$ref'] !== undefined) return { args, coercions };
+  const normalized = normalizeValue(schema, args, '', coercions);
+  return { args: normalized, coercions };
+}

packages/agent-core-v2/src/tool/args-validator.ts

@@ -3,16 +3,19 @@
  *
  * Compiles tool-parameter JSON Schemas into AJV validators (draft-07 /
  * 2019-09 / 2020-12 detected per schema) and formats validation failures
- * into model-readable messages. Only the executor path loads this module,
- * so the AJV instances are paid for once, at execution time. Pure helper;
- * no scoped service.
+ * into model-readable messages — type failures report the value that was
+ * actually received, deduplicated across union branches. Only the executor
+ * path loads this module, so the AJV instances are paid for once, at
+ * execution time. Pure helper; no scoped service.
  */
 
 import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv';
 import Ajv2019 from 'ajv/dist/2019';
 import Ajv2020 from 'ajv/dist/2020';
 import addFormats from 'ajv-formats';
 
+import { describeReceivedValue } from '#/tool/args-normalize';
+
 const DRAFT_07_AJV = new Ajv({ strict: false, allErrors: true });
 addFormats(DRAFT_07_AJV);
 
@@ -67,7 +70,18 @@ export interface JsonObject extends Record<string, JsonType> {}
 
 export type ToolArgsValidator = ValidateFunction<JsonType>;
 
-function formatValidationError(error: ErrorObject): string {
+function valueAtInstancePath(root: JsonType, instancePath: string): unknown {
+  if (instancePath.length === 0) return root;
+  let current: unknown = root;
+  for (const segment of instancePath.split('/').slice(1)) {
+    const key = segment.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (current === null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+function formatValidationError(error: ErrorObject, args: JsonType): string {
   if (error.keyword === 'required' && 'missingProperty' in error.params) {
     return `must have required property '${String(error.params['missingProperty'])}'`;
   }
@@ -77,7 +91,11 @@ function formatValidationError(error: ErrorObject): string {
   }
 
   const path = error.instancePath ? `${error.instancePath} ` : '';
-  return `${path}${error.message ?? 'is invalid'}`;
+  const received =
+    error.keyword === 'type'
+      ? ` (received ${describeReceivedValue(valueAtInstancePath(args, error.instancePath))})`
+      : '';
+  return `${path}${error.message ?? 'is invalid'}${received}`;
 }
 
 export function compileToolArgsValidator(schema: Record<string, unknown>): ToolArgsValidator {
@@ -95,5 +113,5 @@ export function validateToolArgs(validator: ToolArgsValidator, args: JsonType):
     return 'Tool parameter validation failed';
   }
 
-  return errors.map((error) => formatValidationError(error)).join('; ');
+  return [...new Set(errors.map((error) => formatValidationError(error, args)))].join('; ');
 }