fix(kernel-agents): report invalid-argument tool calls as tool errors

Normalize capability invocation failures at the exo membrane: capabilitiesFrom wraps every guarded call so a guard rejection (or any thrown value) becomes a real Error naming the expected signature, e.g. "Error calling add(a: number, b: number): …". This holds even when the guard rejects with an opaque value (as under the test shim), so every caller — both agent strategies and remote discover() — gets an actionable message instead of a load-bearing String(error) fallback at one call site. The chat agent surfaces that message verbatim and only frames JSON parse failures itself.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: grypez

packages/kernel-agents/src/capabilities/discover.test.ts

@@ -69,6 +69,24 @@ describe('makeInternalCapabilities', () => {
     expect(await rejects(capabilities.add.func({} as never))).toBe(true);
   });
 
+  it('normalizes the rejection into a real error naming the expected signature', async () => {
+    // Whatever the guard rejects with (an opaque value under the test shim), the
+    // membrane rethrows a real `Error` carrying the method signature so callers
+    // can surface an actionable message to the model.
+    let caught: unknown;
+    try {
+      await capabilities.count.func({ word: 12345 } as never);
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    expect(
+      (caught as Error).message.startsWith(
+        'Error calling count(word: string): ',
+      ),
+    ).toBe(true);
+  });
+
   it('throws at construction when an implementation has no matching schema', () => {
     expect(() =>
       makeInternalCapabilities(

packages/kernel-agents/src/capabilities/discover.ts

@@ -16,6 +16,21 @@ import type { CapabilityRecord, CapabilitySpec } from '../types.ts';
  */
 type Invoke = (method: string, positionalArgs: unknown[]) => unknown;
 
+/**
+ * Render a method's expected call signature from its schema — e.g.
+ * `add(a: number, b: number)` — for use in invocation-error messages.
+ *
+ * @param name - The method name.
+ * @param schema - The method schema whose `args` describe the parameters.
+ * @returns The formatted signature.
+ */
+const formatSignature = (name: string, schema: MethodSchema): string => {
+  const params = Object.entries(schema.args)
+    .map(([arg, argSchema]) => `${arg}: ${argSchema.type}`)
+    .join(', ');
+  return `${name}(${params})`;
+};
+
 /**
  * Build a {@link CapabilityRecord} from a method-schema description, mapping each
  * capability's object arguments to positional arguments for the exo method.
@@ -36,12 +51,26 @@ const capabilitiesFrom = (
   Object.fromEntries(
     Object.entries(description).map(([name, schema]) => {
       const argNames = Object.keys(schema.args);
-      // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-      const func = async (args: Record<string, unknown>) =>
-        invoke(
-          name,
-          argNames.map((argName) => args[argName]),
-        );
+      const func = async (args: Record<string, unknown>): Promise<unknown> => {
+        try {
+          return await invoke(
+            name,
+            argNames.map((argName) => args[argName]),
+          );
+        } catch (error) {
+          // The exo's interface guard is the sole argument enforcer, so a shape
+          // mismatch rejects here before the implementation runs — but that is
+          // indistinguishable from an error thrown by the implementation, so
+          // the signature is reported as context, not a diagnosed cause.
+          // Wrapping also guarantees a real `Error` even when the guard rejects
+          // with an opaque value (e.g. under the test shim), so every caller
+          // gets the method signature to surface to the model.
+          const detail = error instanceof Error ? error.message : String(error);
+          throw new Error(
+            `Error calling ${formatSignature(name, schema)}: ${detail}`,
+          );
+        }
+      };
       return [name, { func, schema }] as [
         string,
         CapabilitySpec<never, unknown>,

packages/kernel-agents/src/strategies/chat-agent.test.ts

@@ -155,6 +155,53 @@ describe('makeChatAgent', () => {
     ).toBe(true);
   });
 
+  it('injects a tool error for an invalid-argument tool call and continues', async () => {
+    const add = vi.fn(async (a: number, b: number) => a + b);
+    const addCap = makeMethodCapability(
+      'Math',
+      'add',
+      add,
+      S.method(
+        'Add two numbers',
+        [S.arg('a', S.number()), S.arg('b', S.number())],
+        S.number(),
+      ),
+    );
+
+    const recorded: ChatMessage[][] = [];
+    let call = 0;
+    const chat: BoundChat = async ({ messages }) => {
+      recorded.push([...messages]);
+      call += 1;
+      if (call === 1) {
+        // `b` is missing, so the exo's interface guard rejects the call.
+        return makeToolCallResponse('0', [makeToolCall('c1', 'add', { a: 3 })]);
+      }
+      return makeTextResponse('recovered');
+    };
+
+    const agent = makeChatAgent({ chat, capabilities: { add: addCap } });
+    const result = await agent.task('add 3 and ?');
+
+    // The guard rejection surfaces as a tool error rather than crashing the
+    // task, and the implementation never runs with the bad arguments.
+    expect(result).toBe('recovered');
+    expect(add).not.toHaveBeenCalled();
+    const secondTurn = recorded[1] ?? [];
+    // The membrane normalizes the rejection into a real error carrying the
+    // expected signature, so the message is actionable even when the guard
+    // itself rejects with an opaque value (as it does under the test shim).
+    expect(
+      secondTurn.some(
+        (message) =>
+          message.role === 'tool' &&
+          message.content.startsWith(
+            'Error calling add(a: number, b: number):',
+          ),
+      ),
+    ).toBe(true);
+  });
+
   it('throws when invocation budget is exceeded', async () => {
     const ping = makeMethodCapability(
       'Server',

packages/kernel-agents/src/strategies/chat-agent.ts

@@ -159,47 +159,49 @@ export const makeChatAgent = ({
             const { name, arguments: argsJson } = toolCall.function;
             logger?.info(`Invoking capability: ${name}`);
 
-            const spec = Object.hasOwn(agentCapabilities, name)
-              ? agentCapabilities[name]
-              : undefined;
-            if (spec === undefined) {
-              const errorContent = `Unknown capability "${name}"`;
+            const pushTool = (content: string): void => {
               const toolMsg: ChatMessage = {
                 role: 'tool',
                 tool_call_id: toolCall.id,
-                content: errorContent,
+                content,
               };
               chatHistory.push(toolMsg);
               history.push(new ChatTurn(toolMsg));
+            };
+
+            const spec = Object.hasOwn(agentCapabilities, name)
+              ? agentCapabilities[name]
+              : undefined;
+            if (spec === undefined) {
+              pushTool(`Unknown capability "${name}"`);
+              continue;
+            }
+
+            let args: Record<string, unknown>;
+            try {
+              args = parseToolArguments(argsJson);
+            } catch (error) {
+              // Malformed tool-call JSON from the model — never reaches the
+              // capability, so the membrane can't frame it; name it here.
+              const message =
+                error instanceof Error ? error.message : String(error);
+              pushTool(`Error calling ${name}: ${message}`);
               continue;
             }
 
             let toolResult: unknown;
             try {
-              const args = parseToolArguments(argsJson);
-              // The capability is backed by a pattern-guarded exo, so its
-              // interface guard enforces the argument shape; a mismatch rejects
-              // here and is reported as the tool error below.
+              // The capability is backed by a pattern-guarded exo whose
+              // interface guard is the sole argument enforcer. On a mismatch the
+              // membrane rejects with a descriptive `Error calling <signature>:
+              // …`, which we surface verbatim so the model can self-correct.
               toolResult = await spec.func(args as never);
             } catch (error) {
-              const errorContent = `Error calling ${name}: ${(error as Error).message}`;
-              const toolMsg: ChatMessage = {
-                role: 'tool',
-                tool_call_id: toolCall.id,
-                content: errorContent,
-              };
-              chatHistory.push(toolMsg);
-              history.push(new ChatTurn(toolMsg));
+              pushTool(error instanceof Error ? error.message : String(error));
               continue;
             }
 
-            const toolMsg: ChatMessage = {
-              role: 'tool',
-              tool_call_id: toolCall.id,
-              content: JSON.stringify(toolResult),
-            };
-            chatHistory.push(toolMsg);
-            history.push(new ChatTurn(toolMsg));
+            pushTool(JSON.stringify(toolResult));
           }
         }
         throw new Error('Invocation budget exceeded');