@kb-labs/shared-tool-kit 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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.
+ */
+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.
+ */
+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().
+ */
+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);
+ * ```
+ */
+declare function createTool<TInput extends Record<string, unknown> = Record<string, unknown>, TContext = unknown>(spec: ToolSpec<TInput, TContext>): (context: TContext) => ToolShape<TContext>;
+
+export { type ToolDefinitionShape, type ToolShape, type ToolSpec, createTool };

package/dist/index.js

@@ -0,0 +1,18 @@
+// src/factory.ts
+function createTool(spec) {
+  return (context) => ({
+    definition: {
+      type: "function",
+      function: {
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.parameters
+      }
+    },
+    executor: (input) => spec.execute(input, context)
+  });
+}
+
+export { createTool };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/testing/index.d.ts

@@ -0,0 +1,54 @@
+import { ToolShape } from '../index.js';
+
+/**
+ * @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' }]
+ * ```
+ */
+
+/**
+ * A mock tool with built-in call tracking for tests.
+ */
+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' });
+ * ```
+ */
+declare function mockTool(name: string, response?: unknown): MockToolInstance;
+
+export { type MockToolInstance, mockTool };

package/dist/testing/index.js

@@ -0,0 +1,35 @@
+// src/testing/index.ts
+function mockTool(name, response = {}) {
+  const calls = [];
+  let currentResponse = response;
+  const instance = {
+    definition: {
+      type: "function",
+      function: {
+        name,
+        description: `Mock tool: ${name}`,
+        parameters: {
+          type: "object",
+          properties: {}
+        }
+      }
+    },
+    executor: async (input) => {
+      calls.push(input);
+      return currentResponse;
+    },
+    getCalls: () => calls,
+    getLastCall: () => calls[calls.length - 1],
+    wasCalled: () => calls.length > 0,
+    callCount: () => calls.length,
+    respondWith: (newResponse) => {
+      currentResponse = newResponse;
+      return instance;
+    }
+  };
+  return instance;
+}
+
+export { mockTool };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/index.ts"],"names":[],"mappings":";AAoDO,SAAS,QAAA,CAAS,IAAA,EAAc,QAAA,GAAoB,EAAC,EAAqB;AAC/E,EAAA,MAAM,QAAmC,EAAC;AAC1C,EAAA,IAAI,eAAA,GAAkB,QAAA;AAEtB,EAAA,MAAM,QAAA,GAA6B;AAAA,IACjC,UAAA,EAAY;AAAA,MACV,IAAA,EAAM,UAAA;AAAA,MACN,QAAA,EAAU;AAAA,QACR,IAAA;AAAA,QACA,WAAA,EAAa,cAAc,IAAI,CAAA,CAAA;AAAA,QAC/B,UAAA,EAAY;AAAA,UACV,IAAA,EAAM,QAAA;AAAA,UACN,YAAY;AAAC;AACf;AACF,KACF;AAAA,IACA,QAAA,EAAU,OAAO,KAAA,KAAmC;AAClD,MAAA,KAAA,CAAM,KAAK,KAAK,CAAA;AAChB,MAAA,OAAO,eAAA;AAAA,IACT,CAAA;AAAA,IACA,UAAU,MAAM,KAAA;AAAA,IAChB,WAAA,EAAa,MAAM,KAAA,CAAM,KAAA,CAAM,SAAS,CAAC,CAAA;AAAA,IACzC,SAAA,EAAW,MAAM,KAAA,CAAM,MAAA,GAAS,CAAA;AAAA,IAChC,SAAA,EAAW,MAAM,KAAA,CAAM,MAAA;AAAA,IACvB,WAAA,EAAa,CAAC,WAAA,KAAyB;AACrC,MAAA,eAAA,GAAkB,WAAA;AAClB,MAAA,OAAO,QAAA;AAAA,IACT;AAAA,GACF;AAEA,EAAA,OAAO,QAAA;AACT","file":"index.js","sourcesContent":["/**\n * @kb-labs/shared-tool-kit/testing\n *\n * Mock utilities for testing agent tools.\n *\n * @example\n * ```ts\n * import { mockTool } from '@kb-labs/shared-tool-kit/testing';\n *\n * const tool = mockTool('fs_read', { success: true, output: 'file content' });\n * await tool.executor({ path: 'file.ts' });\n * console.log(tool.getCalls()); // [{ path: 'file.ts' }]\n * ```\n */\n\nimport type { ToolShape } from '../factory.js';\n\n/**\n * A mock tool with built-in call tracking for tests.\n */\nexport interface MockToolInstance extends ToolShape {\n  /** All calls made to this tool's executor */\n  getCalls: () => readonly Record<string, unknown>[];\n  /** Last call arguments, or undefined if never called */\n  getLastCall: () => Record<string, unknown> | undefined;\n  /** True if executor was called at least once */\n  wasCalled: () => boolean;\n  /** Number of times executor was called */\n  callCount: () => number;\n  /** Replace the response returned by executor */\n  respondWith: (response: unknown) => MockToolInstance;\n}\n\n/**\n * Create a mock tool for testing.\n *\n * The mock records all calls and returns a configurable response.\n *\n * @param name - Tool name (used in definition)\n * @param response - Default response returned by executor (default: `{}`)\n *\n * @example\n * ```ts\n * const fsRead = mockTool('fs_read', { success: true, output: 'hello' });\n *\n * // Use in registry mock or pass directly\n * await fsRead.executor({ path: 'foo.ts' });\n *\n * expect(fsRead.wasCalled()).toBe(true);\n * expect(fsRead.getLastCall()).toEqual({ path: 'foo.ts' });\n * ```\n */\nexport function mockTool(name: string, response: unknown = {}): MockToolInstance {\n  const calls: Record<string, unknown>[] = [];\n  let currentResponse = response;\n\n  const instance: MockToolInstance = {\n    definition: {\n      type: 'function' as const,\n      function: {\n        name,\n        description: `Mock tool: ${name}`,\n        parameters: {\n          type: 'object' as const,\n          properties: {},\n        },\n      },\n    },\n    executor: async (input: Record<string, unknown>) => {\n      calls.push(input);\n      return currentResponse;\n    },\n    getCalls: () => calls,\n    getLastCall: () => calls[calls.length - 1],\n    wasCalled: () => calls.length > 0,\n    callCount: () => calls.length,\n    respondWith: (newResponse: unknown) => {\n      currentResponse = newResponse;\n      return instance;\n    },\n  };\n\n  return instance;\n}\n"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kb-labs/shared-tool-kit",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Tool factory and mock utilities for KB Labs agent tool development",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing/index.js",
+      "types": "./dist/testing/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix"
+  }
+}