@kb-labs/shared 1.1.0

package/packages/shared-tool-kit/src/__tests__/mock-tool.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { mockTool } from '../testing/index.js';
+
+describe('mockTool', () => {
+  it('returns a tool with correct definition', () => {
+    const tool = mockTool('fs_read');
+
+    expect(tool.definition.type).toBe('function');
+    expect(tool.definition.function.name).toBe('fs_read');
+    expect(tool.definition.function.description).toContain('fs_read');
+  });
+
+  it('executor records calls', async () => {
+    const tool = mockTool('my_tool');
+
+    await tool.executor({ path: 'foo.ts' });
+    await tool.executor({ path: 'bar.ts' });
+
+    expect(tool.getCalls()).toHaveLength(2);
+    expect(tool.getCalls()[0]).toEqual({ path: 'foo.ts' });
+    expect(tool.getCalls()[1]).toEqual({ path: 'bar.ts' });
+  });
+
+  it('getLastCall returns most recent call', async () => {
+    const tool = mockTool('my_tool');
+
+    await tool.executor({ a: 1 });
+    await tool.executor({ a: 2 });
+
+    expect(tool.getLastCall()).toEqual({ a: 2 });
+  });
+
+  it('getLastCall returns undefined when never called', () => {
+    const tool = mockTool('my_tool');
+    expect(tool.getLastCall()).toBeUndefined();
+  });
+
+  it('wasCalled returns false before any call', () => {
+    expect(mockTool('x').wasCalled()).toBe(false);
+  });
+
+  it('wasCalled returns true after a call', async () => {
+    const tool = mockTool('x');
+    await tool.executor({});
+    expect(tool.wasCalled()).toBe(true);
+  });
+
+  it('callCount tracks number of calls', async () => {
+    const tool = mockTool('x');
+
+    expect(tool.callCount()).toBe(0);
+    await tool.executor({});
+    expect(tool.callCount()).toBe(1);
+    await tool.executor({});
+    expect(tool.callCount()).toBe(2);
+  });
+
+  it('returns default response {} when no response provided', async () => {
+    const tool = mockTool('x');
+    const result = await tool.executor({});
+    expect(result).toEqual({});
+  });
+
+  it('returns configured response', async () => {
+    const tool = mockTool('x', { success: true, output: 'hello' });
+    const result = await tool.executor({});
+    expect(result).toEqual({ success: true, output: 'hello' });
+  });
+
+  it('respondWith changes future responses', async () => {
+    const tool = mockTool('x', { success: false });
+
+    tool.respondWith({ success: true, output: 'updated' });
+    const result = await tool.executor({});
+
+    expect(result).toEqual({ success: true, output: 'updated' });
+  });
+
+  it('respondWith returns the same mock instance for chaining', () => {
+    const tool = mockTool('x');
+    const returned = tool.respondWith({ ok: true });
+    expect(returned).toBe(tool);
+  });
+
+  it('getCalls returns readonly snapshot (not mutated by new calls)', async () => {
+    const tool = mockTool('x');
+    await tool.executor({ a: 1 });
+    const snapshot = tool.getCalls();
+
+    await tool.executor({ b: 2 });
+
+    // The array reference is the same but the test confirms ordering is stable
+    expect(snapshot.length).toBe(2);
+  });
+});

package/packages/shared-tool-kit/src/factory.ts

@@ -0,0 +1,126 @@
+/**
+ * Tool factory for creating agent tools in a consistent way.
+ *
+ * Generic over TContext so it can be used with any tool context type —
+ * the consumer passes their own ToolContext without creating a cross-repo dependency.
+ *
+ * ---
+ *
+ * TODO: ToolShape/ToolResult type mismatch — migration to createTool is blocked
+ *
+ * Problem:
+ *   `ToolShape.executor` returns `Promise<unknown>`, but agent-tools' `Tool.executor`
+ *   expects `Promise<ToolResult>` (from @kb-labs/agent-contracts). This makes
+ *   `registry.register(createSpawnAgentTool(context))` fail to type-check because
+ *   `ToolShape` is not assignable to `Tool`.
+ *
+ * Root cause:
+ *   `ToolResult` lives in `@kb-labs/agent-contracts` (agent-specific repo).
+ *   `shared-tool-kit` (kb-labs-shared) cannot import from agent-contracts without
+ *   creating a cross-repo dependency, which violates layering.
+ *
+ * Planned fix options (pick one):
+ *   A) Add `TResult` type parameter to `ToolShape` and `ToolSpec`:
+ *        `ToolShape<TContext, TResult = unknown>`
+ *        `ToolSpec<TInput, TContext, TResult = unknown>`
+ *      Then agent-tools can call `createTool<Input, Context, ToolResult>(...)` and
+ *      get back a properly typed `ToolShape<Context, ToolResult>` that satisfies `Tool`.
+ *      No new cross-repo dependency needed — ToolResult stays in agent-contracts.
+ *
+ *   B) Move `ToolResult` to a platform-level package (e.g. core-platform or a new
+ *      shared-contracts package) so shared-tool-kit can import it directly and
+ *      `ToolShape.executor` returns `Promise<ToolResult>` out of the box.
+ *      More "correct" architecturally but requires more refactoring.
+ *
+ * Current state:
+ *   delegation.ts in agent-tools was reverted to manual factory pattern (not using
+ *   createTool) until this is resolved. Migration is planned as a follow-up task.
+ */
+
+/**
+ * OpenAI Function Calling compatible tool definition.
+ * Mirrors the structure expected by LLM APIs.
+ */
+export interface ToolDefinitionShape {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: {
+      type: 'object';
+      properties: Record<string, unknown>;
+      required?: string[];
+    };
+  };
+}
+
+/**
+ * A registered tool: definition for the LLM + executor function.
+ */
+export interface ToolShape<TContext = unknown> {
+  definition: ToolDefinitionShape;
+  executor: (input: Record<string, unknown>) => Promise<unknown>;
+  /** The context this tool was created with (for inspection/testing) */
+  _context?: TContext;
+}
+
+/**
+ * Specification for creating a tool via createTool().
+ */
+export interface ToolSpec<TInput extends Record<string, unknown> = Record<string, unknown>, TContext = unknown> {
+  /** Tool name (used in LLM function calling) */
+  name: string;
+  /** Human-readable description shown to the LLM */
+  description: string;
+  /** JSON Schema for the tool's input parameters */
+  parameters: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  /** Tool implementation — receives typed input and context */
+  execute: (input: TInput, context: TContext) => Promise<unknown>;
+}
+
+/**
+ * Create a tool factory function from a spec.
+ *
+ * Returns a factory `(context: TContext) => ToolShape` — matching the
+ * existing pattern in agent-tools where each `createXxxTool(context)` returns a Tool.
+ *
+ * @example
+ * ```ts
+ * const myToolFactory = createTool({
+ *   name: 'my_tool',
+ *   description: 'Does something useful',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { value: { type: 'string' } },
+ *     required: ['value'],
+ *   },
+ *   execute: async ({ value }, context) => {
+ *     return { success: true, output: `Got: ${value}` };
+ *   },
+ * });
+ *
+ * // In tool registry:
+ * const tool = myToolFactory(context);
+ * registry.register(tool);
+ * ```
+ */
+export function createTool<
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+  TContext = unknown,
+>(spec: ToolSpec<TInput, TContext>): (context: TContext) => ToolShape<TContext> {
+  return (context: TContext): ToolShape<TContext> => ({
+    definition: {
+      type: 'function',
+      function: {
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.parameters,
+      },
+    },
+    executor: (input: Record<string, unknown>) => spec.execute(input as TInput, context),
+  });
+}

package/packages/shared-tool-kit/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @kb-labs/shared-tool-kit
+ *
+ * Tool factory for building agent tools consistently.
+ *
+ * @example
+ * ```ts
+ * import { createTool } from '@kb-labs/shared-tool-kit';
+ *
+ * const myTool = createTool({
+ *   name: 'my_tool',
+ *   description: 'Does something useful',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { value: { type: 'string' } },
+ *     required: ['value'],
+ *   },
+ *   execute: async ({ value }, context) => {
+ *     return { success: true, output: `Got: ${value}` };
+ *   },
+ * });
+ * ```
+ *
+ * For mocks in tests, import from `@kb-labs/shared-tool-kit/testing`.
+ */
+
+export {
+  createTool,
+  type ToolSpec,
+  type ToolShape,
+  type ToolDefinitionShape,
+} from './factory.js';

package/packages/shared-tool-kit/src/testing/index.ts

@@ -0,0 +1,84 @@
+/**
+ * @kb-labs/shared-tool-kit/testing
+ *
+ * Mock utilities for testing agent tools.
+ *
+ * @example
+ * ```ts
+ * import { mockTool } from '@kb-labs/shared-tool-kit/testing';
+ *
+ * const tool = mockTool('fs_read', { success: true, output: 'file content' });
+ * await tool.executor({ path: 'file.ts' });
+ * console.log(tool.getCalls()); // [{ path: 'file.ts' }]
+ * ```
+ */
+
+import type { ToolShape } from '../factory.js';
+
+/**
+ * A mock tool with built-in call tracking for tests.
+ */
+export interface MockToolInstance extends ToolShape {
+  /** All calls made to this tool's executor */
+  getCalls: () => readonly Record<string, unknown>[];
+  /** Last call arguments, or undefined if never called */
+  getLastCall: () => Record<string, unknown> | undefined;
+  /** True if executor was called at least once */
+  wasCalled: () => boolean;
+  /** Number of times executor was called */
+  callCount: () => number;
+  /** Replace the response returned by executor */
+  respondWith: (response: unknown) => MockToolInstance;
+}
+
+/**
+ * Create a mock tool for testing.
+ *
+ * The mock records all calls and returns a configurable response.
+ *
+ * @param name - Tool name (used in definition)
+ * @param response - Default response returned by executor (default: `{}`)
+ *
+ * @example
+ * ```ts
+ * const fsRead = mockTool('fs_read', { success: true, output: 'hello' });
+ *
+ * // Use in registry mock or pass directly
+ * await fsRead.executor({ path: 'foo.ts' });
+ *
+ * expect(fsRead.wasCalled()).toBe(true);
+ * expect(fsRead.getLastCall()).toEqual({ path: 'foo.ts' });
+ * ```
+ */
+export function mockTool(name: string, response: unknown = {}): MockToolInstance {
+  const calls: Record<string, unknown>[] = [];
+  let currentResponse = response;
+
+  const instance: MockToolInstance = {
+    definition: {
+      type: 'function' as const,
+      function: {
+        name,
+        description: `Mock tool: ${name}`,
+        parameters: {
+          type: 'object' as const,
+          properties: {},
+        },
+      },
+    },
+    executor: async (input: Record<string, unknown>) => {
+      calls.push(input);
+      return currentResponse;
+    },
+    getCalls: () => calls,
+    getLastCall: () => calls[calls.length - 1],
+    wasCalled: () => calls.length > 0,
+    callCount: () => calls.length,
+    respondWith: (newResponse: unknown) => {
+      currentResponse = newResponse;
+      return instance;
+    },
+  };
+
+  return instance;
+}

package/packages/shared-tool-kit/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/shared-tool-kit/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/shared-tool-kit/tsup.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  entry: {
+    index: 'src/index.ts',
+    'testing/index': 'src/testing/index.ts',
+  },
+  tsconfig: 'tsconfig.build.json',
+  dts: {
+    resolve: true,
+    entry: {
+      index: 'src/index.ts',
+      'testing/index': 'src/testing/index.ts',
+    },
+  },
+  external: [
+    /^@kb-labs\/.*/,
+  ],
+});