@crewhaus/tool-executor 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@crewhaus/tool-executor",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Execute a single tool: validate → permission-check → invoke → format result",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "@crewhaus/tool-validate": "0.0.0",
+    "@crewhaus/tool-permission-matcher": "0.0.0",
+    "@crewhaus/tool-builder": "0.0.0",
+    "zod": "^3.23.8"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-executor"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-executor#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+import { ToolPermissionError, executeTool } from "./index";
+
+const schema = z.object({ command: z.string() });
+
+function makeEchoTool(overrides?: Partial<RegisteredTool>): RegisteredTool {
+  return {
+    name: "Bash",
+    description: "Run a command",
+    inputSchema: schema as RegisteredTool["inputSchema"],
+    execute: async (input) => `ran: ${(input as { command: string }).command}`,
+    concurrencySafe: false,
+    readOnly: false,
+    destructive: false,
+    requiresSandbox: false,
+    classifyOutput: true,
+    scope: "internal",
+    requireJustification: false,
+    ...overrides,
+  };
+}
+
+describe("executeTool — happy path", () => {
+  test("returns isError:false with content from execute", async () => {
+    const result = await executeTool(makeEchoTool(), { command: "ls" }, { toolUseId: "1" });
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe("ran: ls");
+    expect(result.toolUseId).toBe("1");
+  });
+
+  test("no allowedPatterns means all tools are permitted", async () => {
+    const result = await executeTool(makeEchoTool(), { command: "rm -rf /" }, { toolUseId: "2" });
+    expect(result.isError).toBe(false);
+  });
+
+  test("matching allowedPattern permits the call", async () => {
+    const result = await executeTool(
+      makeEchoTool(),
+      { command: "git status" },
+      { toolUseId: "3", allowedPatterns: ["Bash(git *)"] },
+    );
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe("ran: git status");
+  });
+});
+
+describe("executeTool — validation failure", () => {
+  test("returns isError:true when input fails schema", async () => {
+    const result = await executeTool(makeEchoTool(), { command: 99 }, { toolUseId: "4" });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Bash");
+  });
+
+  test("returns isError:true for null input", async () => {
+    const result = await executeTool(makeEchoTool(), null, { toolUseId: "5" });
+    expect(result.isError).toBe(true);
+  });
+});
+
+describe("executeTool — permission denied", () => {
+  test("returns isError:true when no pattern matches", async () => {
+    const result = await executeTool(
+      makeEchoTool(),
+      { command: "ls" },
+      { toolUseId: "6", allowedPatterns: ["Bash(git *)"] },
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("not permitted");
+    expect(result.content).toContain("Bash");
+  });
+
+  test("returns isError:true when patterns list is empty", async () => {
+    const result = await executeTool(
+      makeEchoTool(),
+      { command: "ls" },
+      { toolUseId: "7", allowedPatterns: [] },
+    );
+    expect(result.isError).toBe(true);
+  });
+});
+
+describe("executeTool — execute throws", () => {
+  test("returns isError:true with error message", async () => {
+    const failTool = makeEchoTool({
+      execute: async () => {
+        throw new Error("disk full");
+      },
+    });
+    const result = await executeTool(failTool, { command: "write" }, { toolUseId: "8" });
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe("disk full");
+  });
+
+  test("captures non-Error throws as strings", async () => {
+    const failTool = makeEchoTool({
+      execute: async () => {
+        throw "string error";
+      },
+    });
+    const result = await executeTool(failTool, { command: "x" }, { toolUseId: "9" });
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe("string error");
+  });
+});
+
+describe("ToolPermissionError", () => {
+  test("has code 'tool' and stable name", () => {
+    const err = new ToolPermissionError("Bash");
+    expect(err.code).toBe("tool");
+    expect(err.name).toBe("ToolPermissionError");
+    expect(err.toolName).toBe("Bash");
+  });
+});

package/src/index.ts

@@ -0,0 +1,82 @@
+import { CrewhausError } from "@crewhaus/errors";
+import type { RegisteredTool, ToolExecuteResult } from "@crewhaus/tool-catalog";
+import { compilePattern, matchesPattern } from "@crewhaus/tool-permission-matcher";
+import { validateToolInput } from "@crewhaus/tool-validate";
+
+/**
+ * Section 14 — `content` widened from `string` to `string | ToolResultContent`
+ * so tools like `ReadImage` can return Anthropic image content blocks. Error
+ * paths still produce a string (validation message, permission refusal,
+ * thrown-error.message) — the union is only meaningful on the success path.
+ */
+export type ToolResult = {
+  readonly toolUseId: string;
+  readonly content: ToolExecuteResult;
+  readonly isError: boolean;
+};
+
+export type ExecutionContext = {
+  readonly toolUseId: string;
+  /** When present, the tool call must match at least one pattern. Absent = allow all. */
+  readonly allowedPatterns?: ReadonlyArray<string>;
+  /** Optional cooperative-cancellation signal forwarded to the tool. */
+  readonly signal?: AbortSignal;
+  /**
+   * Section 13 — opaque runtime bridge forwarded into the tool's
+   * `ToolExecuteContext.bridge`. Framework-aware tools (the Task tool) cast
+   * it; ordinary tools ignore it.
+   */
+  readonly bridge?: unknown;
+  /**
+   * Section 18 — runtime-core supplies this so streaming tools
+   * (`tool-code-execution`) can forward stdout/stderr chunks to the trace
+   * bus as `tool_stream_chunk` events.
+   */
+  readonly onStreamChunk?: (stream: "stdout" | "stderr", chunk: string) => void;
+};
+
+export class ToolPermissionError extends CrewhausError {
+  override readonly name = "ToolPermissionError";
+  readonly toolName: string;
+  constructor(toolName: string) {
+    super("tool", `tool "${toolName}" is not permitted by the current permission set`);
+    this.toolName = toolName;
+  }
+}
+
+export async function executeTool(
+  tool: RegisteredTool,
+  rawInput: unknown,
+  context: ExecutionContext,
+): Promise<ToolResult> {
+  const { toolUseId, allowedPatterns } = context;
+
+  const validation = validateToolInput(tool, rawInput);
+  if (!validation.ok) {
+    return { toolUseId, content: validation.error.message, isError: true };
+  }
+
+  if (allowedPatterns !== undefined) {
+    const compiled = allowedPatterns.map(compilePattern);
+    const permitted = compiled.some((p) => matchesPattern(p, tool.name, rawInput));
+    if (!permitted) {
+      return {
+        toolUseId,
+        content: new ToolPermissionError(tool.name).message,
+        isError: true,
+      };
+    }
+  }
+
+  try {
+    const content = await tool.execute(validation.value, {
+      signal: context.signal,
+      ...(context.bridge !== undefined ? { bridge: context.bridge } : {}),
+      ...(context.onStreamChunk !== undefined ? { onStreamChunk: context.onStreamChunk } : {}),
+    });
+    return { toolUseId, content, isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { toolUseId, content: msg, isError: true };
+  }
+}

package/src/integration.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Integration test: wires ToolCatalog + buildTool + validateToolInput +
+ * matchesPattern + executeTool together with a real mock tool. No mocking of
+ * internal modules — each layer is exercised end-to-end.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import { buildTool } from "@crewhaus/tool-builder";
+import { type RegisteredTool, ToolCatalog } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+import { executeTool } from "./index";
+
+const greetSchema = z.object({ name: z.string() });
+type GreetInput = z.infer<typeof greetSchema>;
+
+const greetDef = {
+  name: "Greet",
+  description: "Returns a greeting",
+  inputSchema: greetSchema,
+  execute: async (input: GreetInput) => `Hello, ${input.name}!`,
+  readOnly: true,
+};
+
+const failDef = {
+  name: "Fail",
+  description: "Always throws",
+  inputSchema: greetSchema,
+  execute: async (_input: GreetInput): Promise<string> => {
+    throw new Error("intentional failure");
+  },
+};
+
+describe("integration: full execution pipeline", () => {
+  let catalog: ToolCatalog;
+
+  // Type-narrowing lookup so the test body never needs `!`. Throws
+  // descriptively if a tool is missing — which would itself indicate a
+  // catalog bug worth surfacing.
+  function lookup(name: string): RegisteredTool {
+    const tool = catalog.get(name);
+    if (!tool) throw new Error(`expected tool "${name}" to be registered`);
+    return tool;
+  }
+
+  beforeEach(() => {
+    catalog = new ToolCatalog();
+    catalog.register(buildTool(greetDef));
+    catalog.register(buildTool(failDef));
+  });
+
+  test("catalog → buildTool → executeTool succeeds end-to-end", async () => {
+    const tool = lookup("Greet");
+    const result = await executeTool(tool, { name: "World" }, { toolUseId: "i1" });
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe("Hello, World!");
+    expect(result.toolUseId).toBe("i1");
+  });
+
+  test("buildTool applies fail-closed defaults in the catalog", () => {
+    const tool = lookup("Greet");
+    expect(tool.concurrencySafe).toBe(false);
+    expect(tool.destructive).toBe(false);
+    expect(tool.readOnly).toBe(true); // explicit
+  });
+
+  test("permission pattern allows matching tool call", async () => {
+    const tool = lookup("Greet");
+    const result = await executeTool(
+      tool,
+      { name: "Max" },
+      { toolUseId: "i2", allowedPatterns: ["Greet"] },
+    );
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe("Hello, Max!");
+  });
+
+  test("permission pattern denies non-matching tool call", async () => {
+    const tool = lookup("Greet");
+    const result = await executeTool(
+      tool,
+      { name: "Max" },
+      { toolUseId: "i3", allowedPatterns: ["Bash(git *)"] },
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("not permitted");
+  });
+
+  test("tool that throws produces isError:true result", async () => {
+    const tool = lookup("Fail");
+    const result = await executeTool(tool, { name: "anyone" }, { toolUseId: "i4" });
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe("intentional failure");
+  });
+
+  test("invalid input is caught before execute is called", async () => {
+    const tool = lookup("Greet");
+    const result = await executeTool(tool, { name: 42 }, { toolUseId: "i5" });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Greet");
+  });
+
+  test("wildcard permission pattern permits all tools", async () => {
+    const tool = lookup("Greet");
+    const result = await executeTool(
+      tool,
+      { name: "Everyone" },
+      { toolUseId: "i6", allowedPatterns: ["*"] },
+    );
+    expect(result.isError).toBe(false);
+  });
+});