@kb-labs/shared-tool-kit 2.118.2 → 2.119.0-canary.0c078654e

package/dist/index.js.map

@@ -1 +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"]}
+{"version":3,"sources":["../../home/runner/work/kb-labs/kb-labs/shared/tool-kit/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.js.map

@@ -1 +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"]}
+{"version":3,"sources":["../../../home/runner/work/kb-labs/kb-labs/shared/tool-kit/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

@@ -1,7 +1,7 @@
 {
   "name": "@kb-labs/shared-tool-kit",
   "description": "Tool factory and mock utilities for KB Labs agent tool development",
-  "version": "2.118.2",
+  "version": "2.119.0-canary.0c078654e",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,7 +25,7 @@
     "tsup": "^8.5.0",
     "typescript": "^5.6.3",
     "vitest": "^3.2.6",
-    "@kb-labs/devkit": "2.118.2"
+    "@kb-labs/devkit": "2.119.0-canary.0c078654e"
   },
   "engines": {
     "node": ">=22.0.0",