@intx/agent 0.1.2

package/src/tool.test.ts

@@ -0,0 +1,217 @@
+import { describe, test, expect } from "bun:test";
+
+import type { ToolDefinition } from "@intx/types/runtime";
+
+import {
+  createToolRunner,
+  DuplicateToolError,
+  fromToolRunner,
+  stringTool,
+  tool,
+} from "./tool";
+
+const DEF_A: ToolDefinition = {
+  name: "a",
+  description: "tool a",
+  inputSchema: { type: "object" },
+};
+
+const DEF_B: ToolDefinition = {
+  name: "b",
+  description: "tool b",
+  inputSchema: { type: "object" },
+};
+
+describe("createToolRunner", () => {
+  test("dispatches to a full handler by tool name", async () => {
+    const runner = createToolRunner([
+      tool({
+        definition: DEF_A,
+        handler: async (call) => ({
+          callId: call.id,
+          content: `got ${String(call.arguments.x)}`,
+        }),
+      }),
+    ]);
+
+    const result = await runner.run(
+      { id: "c1", name: "a", arguments: { x: 5 } },
+      new AbortController().signal,
+    );
+
+    expect(result).toEqual({ callId: "c1", content: "got 5" });
+  });
+
+  test("lifts the string handler return into a ToolResult", async () => {
+    const runner = createToolRunner([
+      stringTool({
+        definition: DEF_A,
+        handler: async (args) => `hello ${String(args.name)}`,
+      }),
+    ]);
+
+    const result = await runner.run(
+      { id: "c2", name: "a", arguments: { name: "world" } },
+      new AbortController().signal,
+    );
+
+    expect(result).toEqual({ callId: "c2", content: "hello world" });
+  });
+
+  test("returns an error ToolResult for an unknown tool name", async () => {
+    const runner = createToolRunner([
+      tool({
+        definition: DEF_A,
+        handler: async (call) => ({ callId: call.id, content: "" }),
+      }),
+    ]);
+
+    const result = await runner.run(
+      { id: "c3", name: "nope", arguments: {} },
+      new AbortController().signal,
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.callId).toBe("c3");
+    expect(result.content).toBe("unknown tool: nope");
+  });
+
+  test("wraps a thrown error from a full handler into an error ToolResult", async () => {
+    const runner = createToolRunner([
+      tool({
+        definition: DEF_A,
+        handler: async () => {
+          throw new Error("boom");
+        },
+      }),
+    ]);
+
+    const result = await runner.run(
+      { id: "c4", name: "a", arguments: {} },
+      new AbortController().signal,
+    );
+
+    expect(result).toEqual({ callId: "c4", content: "boom", isError: true });
+  });
+
+  test("wraps a thrown error from a string handler into an error ToolResult", async () => {
+    const runner = createToolRunner([
+      stringTool({
+        definition: DEF_A,
+        handler: async () => {
+          throw new Error("bad input");
+        },
+      }),
+    ]);
+
+    const result = await runner.run(
+      { id: "c5", name: "a", arguments: {} },
+      new AbortController().signal,
+    );
+
+    expect(result).toEqual({
+      callId: "c5",
+      content: "bad input",
+      isError: true,
+    });
+  });
+
+  test("exposes definitions in registration order", () => {
+    const runner = createToolRunner([
+      tool({
+        definition: DEF_A,
+        handler: async (call) => ({ callId: call.id, content: "" }),
+      }),
+      stringTool({ definition: DEF_B, handler: async () => "x" }),
+    ]);
+
+    expect(runner.definitions.map((d) => d.name)).toEqual(["a", "b"]);
+  });
+
+  test("throws DuplicateToolError at construction on duplicate names", () => {
+    expect(() =>
+      createToolRunner([
+        tool({
+          definition: DEF_A,
+          handler: async (call) => ({ callId: call.id, content: "" }),
+        }),
+        stringTool({ definition: DEF_A, handler: async () => "x" }),
+      ]),
+    ).toThrow(DuplicateToolError);
+  });
+
+  test("propagates the AbortSignal to the handler", async () => {
+    let received: AbortSignal | undefined;
+    const runner = createToolRunner([
+      tool({
+        definition: DEF_A,
+        handler: async (call, signal) => {
+          received = signal;
+          return { callId: call.id, content: "ok" };
+        },
+      }),
+    ]);
+
+    const ctl = new AbortController();
+    await runner.run({ id: "c6", name: "a", arguments: {} }, ctl.signal);
+
+    expect(received).toBe(ctl.signal);
+  });
+
+  test("fromToolRunner wraps each definition as a full-handler AgentTool", async () => {
+    const calls: string[] = [];
+    const stubRunner = {
+      definitions: [DEF_A, DEF_B] as const,
+      run: async (call: {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+      }) => {
+        calls.push(call.name);
+        return Promise.resolve({
+          callId: call.id,
+          content: `ran ${call.name}`,
+        });
+      },
+    };
+
+    const tools = fromToolRunner(stubRunner);
+    const runner = createToolRunner(tools);
+
+    expect(runner.definitions.map((d) => d.name)).toEqual(["a", "b"]);
+
+    const ra = await runner.run(
+      { id: "c8", name: "a", arguments: {} },
+      new AbortController().signal,
+    );
+    expect(ra).toEqual({ callId: "c8", content: "ran a" });
+
+    const rb = await runner.run(
+      { id: "c9", name: "b", arguments: {} },
+      new AbortController().signal,
+    );
+    expect(rb).toEqual({ callId: "c9", content: "ran b" });
+
+    expect(calls).toEqual(["a", "b"]);
+  });
+
+  test("string handler receives the parsed arguments object", async () => {
+    let received: Record<string, unknown> | undefined;
+    const runner = createToolRunner([
+      stringTool({
+        definition: DEF_A,
+        handler: async (args) => {
+          received = args;
+          return "ok";
+        },
+      }),
+    ]);
+
+    await runner.run(
+      { id: "c7", name: "a", arguments: { foo: 1, bar: "x" } },
+      new AbortController().signal,
+    );
+
+    expect(received).toEqual({ foo: 1, bar: "x" });
+  });
+});

package/src/tool.ts

@@ -0,0 +1,148 @@
+// Tool registration and dispatch.
+//
+// Two registration shapes are supported:
+//
+//   `tool({ definition, handler })`        — handler receives the full
+//                                            ToolCall and returns the full
+//                                            ToolResult. Use when the
+//                                            handler needs the callId or
+//                                            wants to set isError/detail/
+//                                            pendingMarker.
+//
+//   `stringTool({ definition, handler })`  — sugar for the common case of
+//                                            "compute a string from the
+//                                            parsed arguments." The callId
+//                                            is filled in from the
+//                                            surrounding ToolCall, and
+//                                            isError is false unless the
+//                                            handler throws.
+//
+// `createToolRunner(tools)` builds a `ToolRunner` that dispatches by tool
+// name. Per the ToolRunner contract (packages/types/src/runtime.ts), `run`
+// must not throw — unknown tool names and handler exceptions are surfaced
+// as `ToolResult` with `isError: true` so the model sees them and can
+// recover.
+
+import type {
+  ToolCall,
+  ToolDefinition,
+  ToolResult,
+  ToolRunner,
+} from "@intx/types/runtime";
+
+export type ToolHandler = (
+  call: ToolCall,
+  signal: AbortSignal,
+) => Promise<ToolResult>;
+
+export type StringToolHandler = (
+  args: Record<string, unknown>,
+  signal: AbortSignal,
+) => Promise<string>;
+
+export type AgentTool =
+  | { kind: "full"; definition: ToolDefinition; handler: ToolHandler }
+  | {
+      kind: "string";
+      definition: ToolDefinition;
+      handler: StringToolHandler;
+    };
+
+export function tool(args: {
+  definition: ToolDefinition;
+  handler: ToolHandler;
+}): AgentTool {
+  return { kind: "full", definition: args.definition, handler: args.handler };
+}
+
+export function stringTool(args: {
+  definition: ToolDefinition;
+  handler: StringToolHandler;
+}): AgentTool {
+  return {
+    kind: "string",
+    definition: args.definition,
+    handler: args.handler,
+  };
+}
+
+/**
+ * Adapt a pre-built ToolRunner (e.g. the one returned by
+ * `createPosixTools`) into a list of AgentTools that can be passed to
+ * `createAgent({ tools })`. Each definition becomes a full-handler
+ * AgentTool that delegates to the runner's `run`.
+ *
+ * Use this when integrating tool packages whose public surface is a
+ * single ToolRunner rather than individual handlers.
+ */
+export function fromToolRunner(runner: {
+  readonly definitions: readonly ToolDefinition[];
+  run: ToolRunner["run"];
+}): AgentTool[] {
+  return runner.definitions.map((definition) => ({
+    kind: "full",
+    definition,
+    handler: (call, signal) => runner.run(call, signal),
+  }));
+}
+
+export class DuplicateToolError extends Error {
+  readonly toolName: string;
+
+  constructor(toolName: string) {
+    super(`duplicate tool name: ${toolName}`);
+    this.name = "DuplicateToolError";
+    this.toolName = toolName;
+  }
+}
+
+export type AgentToolRunner = ToolRunner & {
+  readonly definitions: readonly ToolDefinition[];
+};
+
+/**
+ * Build a `ToolRunner` that dispatches by tool name. Throws
+ * `DuplicateToolError` at construction if any two tools share a name.
+ *
+ * At call time, unknown tool names and exceptions from handlers are
+ * converted to `ToolResult { isError: true }` so the contract on
+ * `ToolRunner.run` ("must not throw") is upheld.
+ */
+export function createToolRunner(tools: AgentTool[]): AgentToolRunner {
+  const byName = new Map<string, AgentTool>();
+  for (const t of tools) {
+    if (byName.has(t.definition.name)) {
+      throw new DuplicateToolError(t.definition.name);
+    }
+    byName.set(t.definition.name, t);
+  }
+
+  const definitions: readonly ToolDefinition[] = tools.map((t) => t.definition);
+
+  return {
+    definitions,
+    async run(call, signal): Promise<ToolResult> {
+      const found = byName.get(call.name);
+      if (found === undefined) {
+        return {
+          callId: call.id,
+          content: `unknown tool: ${call.name}`,
+          isError: true,
+        };
+      }
+      try {
+        if (found.kind === "full") {
+          return await found.handler(call, signal);
+        }
+        const text = await found.handler(call.arguments, signal);
+        return { callId: call.id, content: text };
+      } catch (err) {
+        return {
+          callId: call.id,
+          content: err instanceof Error ? err.message : String(err),
+          isError: true,
+        };
+      }
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.ts"]
+}