@kognitivedev/tools 0.2.2

package/README.md

@@ -0,0 +1,40 @@
+# @kognitivedev/tools
+
+> Tool system for Kognitive agents — createTool, ToolRegistry, approval workflows, and AI SDK conversion.
+
+## Installation
+
+```bash
+bun add @kognitivedev/tools
+```
+
+## Quick Start
+
+```typescript
+import { createTool, ToolRegistry } from "@kognitivedev/tools";
+import { z } from "zod";
+import { streamText } from "ai";
+
+const searchTool = createTool({
+  id: "search",
+  description: "Search documentation",
+  inputSchema: z.object({ query: z.string() }),
+  execute: async (input) => ({ results: [`Result for: ${input.query}`] }),
+});
+
+const registry = new ToolRegistry();
+registry.register(searchTool);
+
+const result = await streamText({
+  model: openai("gpt-4o"),
+  tools: registry.toAISDKTools(),
+  messages,
+});
+```
+
+## Features
+
+- **createTool** — typed tool factory with Zod schemas
+- **ToolRegistry** — named collection with `toAISDKTools()` conversion
+- **Approval** — `requireApproval` (boolean or conditional function)
+- **AI SDK native** — converts directly to AI SDK `tool()` format

package/dist/__tests__/tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/tools.test.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const zod_1 = require("zod");
+const index_1 = require("../index");
+const mockContext = {
+    abortSignal: new AbortController().signal,
+    resourceId: { projectId: "test" },
+    emit: vitest_1.vi.fn(),
+};
+(0, vitest_1.describe)("createTool", () => {
+    (0, vitest_1.it)("creates a tool with correct properties", () => {
+        const tool = (0, index_1.createTool)({
+            id: "test-tool",
+            description: "A test tool",
+            inputSchema: zod_1.z.object({ query: zod_1.z.string() }),
+            execute: async (input) => ({ result: input.query }),
+        });
+        (0, vitest_1.expect)(tool.id).toBe("test-tool");
+        (0, vitest_1.expect)(tool.description).toBe("A test tool");
+        (0, vitest_1.expect)(tool.inputSchema).toBeDefined();
+        (0, vitest_1.expect)(tool.execute).toBeTypeOf("function");
+    });
+    (0, vitest_1.it)("executes with input and context", async () => {
+        const tool = (0, index_1.createTool)({
+            id: "echo",
+            description: "Echo",
+            inputSchema: zod_1.z.object({ msg: zod_1.z.string() }),
+            execute: async (input) => input.msg,
+        });
+        const result = await tool.execute({ msg: "hello" }, mockContext);
+        (0, vitest_1.expect)(result).toBe("hello");
+    });
+});
+(0, vitest_1.describe)("ToolRegistry", () => {
+    (0, vitest_1.it)("registers and retrieves tools", () => {
+        const registry = new index_1.ToolRegistry();
+        const tool = (0, index_1.createTool)({
+            id: "t1",
+            description: "Tool 1",
+            inputSchema: zod_1.z.object({}),
+            execute: async () => "ok",
+        });
+        registry.register(tool);
+        (0, vitest_1.expect)(registry.get("t1")).toBe(tool);
+        (0, vitest_1.expect)(registry.has("t1")).toBe(true);
+        (0, vitest_1.expect)(registry.size).toBe(1);
+    });
+    (0, vitest_1.it)("throws on duplicate registration", () => {
+        const registry = new index_1.ToolRegistry();
+        const tool = (0, index_1.createTool)({
+            id: "t1",
+            description: "Tool",
+            inputSchema: zod_1.z.object({}),
+            execute: async () => "ok",
+        });
+        registry.register(tool);
+        (0, vitest_1.expect)(() => registry.register(tool)).toThrow("already registered");
+    });
+    (0, vitest_1.it)("all returns all tools", () => {
+        const registry = new index_1.ToolRegistry();
+        const t1 = (0, index_1.createTool)({ id: "t1", description: "1", inputSchema: zod_1.z.object({}), execute: async () => 1 });
+        const t2 = (0, index_1.createTool)({ id: "t2", description: "2", inputSchema: zod_1.z.object({}), execute: async () => 2 });
+        registry.register(t1);
+        registry.register(t2);
+        (0, vitest_1.expect)(registry.all()).toHaveLength(2);
+    });
+    (0, vitest_1.it)("remove deletes tool", () => {
+        const registry = new index_1.ToolRegistry();
+        const tool = (0, index_1.createTool)({ id: "t1", description: "1", inputSchema: zod_1.z.object({}), execute: async () => 1 });
+        registry.register(tool);
+        registry.remove("t1");
+        (0, vitest_1.expect)(registry.has("t1")).toBe(false);
+    });
+    (0, vitest_1.it)("toAISDKTools returns record with tool ids as keys", () => {
+        const registry = new index_1.ToolRegistry();
+        registry.register((0, index_1.createTool)({ id: "search", description: "Search", inputSchema: zod_1.z.object({ q: zod_1.z.string() }), execute: async () => "result" }));
+        const sdkTools = registry.toAISDKTools();
+        (0, vitest_1.expect)(sdkTools).toHaveProperty("search");
+    });
+});
+(0, vitest_1.describe)("needsApproval", () => {
+    (0, vitest_1.it)("returns false when no requireApproval", () => {
+        const tool = (0, index_1.createTool)({ id: "t", description: "t", inputSchema: zod_1.z.object({}), execute: async () => null });
+        (0, vitest_1.expect)((0, index_1.needsApproval)(tool, {})).toBe(false);
+    });
+    (0, vitest_1.it)("returns true when requireApproval is true", () => {
+        const tool = (0, index_1.createTool)({ id: "t", description: "t", inputSchema: zod_1.z.object({}), execute: async () => null, requireApproval: true });
+        (0, vitest_1.expect)((0, index_1.needsApproval)(tool, {})).toBe(true);
+    });
+    (0, vitest_1.it)("evaluates function requireApproval", () => {
+        const tool = (0, index_1.createTool)({
+            id: "t",
+            description: "t",
+            inputSchema: zod_1.z.object({ amount: zod_1.z.number() }),
+            execute: async () => null,
+            requireApproval: (input) => input.amount > 100,
+        });
+        (0, vitest_1.expect)((0, index_1.needsApproval)(tool, { amount: 50 })).toBe(false);
+        (0, vitest_1.expect)((0, index_1.needsApproval)(tool, { amount: 200 })).toBe(true);
+    });
+});
+(0, vitest_1.describe)("executeWithApproval", () => {
+    (0, vitest_1.it)("executes when no approval needed", async () => {
+        const tool = (0, index_1.createTool)({ id: "t", description: "t", inputSchema: zod_1.z.object({}), execute: async () => "done" });
+        const result = await (0, index_1.executeWithApproval)(tool, {}, mockContext);
+        (0, vitest_1.expect)(result).toBe("done");
+    });
+    (0, vitest_1.it)("throws when approval needed but no handler", async () => {
+        const tool = (0, index_1.createTool)({ id: "t", description: "t", inputSchema: zod_1.z.object({}), execute: async () => "done", requireApproval: true });
+        await (0, vitest_1.expect)((0, index_1.executeWithApproval)(tool, {}, mockContext)).rejects.toThrow("Approval denied");
+    });
+    (0, vitest_1.it)("executes when handler approves", async () => {
+        const tool = (0, index_1.createTool)({ id: "t", description: "t", inputSchema: zod_1.z.object({}), execute: async () => "done", requireApproval: true });
+        const handler = vitest_1.vi.fn().mockResolvedValue(true);
+        const result = await (0, index_1.executeWithApproval)(tool, {}, mockContext, handler);
+        (0, vitest_1.expect)(result).toBe("done");
+        (0, vitest_1.expect)(handler).toHaveBeenCalled();
+    });
+    (0, vitest_1.it)("throws when handler denies", async () => {
+        const tool = (0, index_1.createTool)({ id: "t", description: "t", inputSchema: zod_1.z.object({}), execute: async () => "done", requireApproval: true });
+        const handler = vitest_1.vi.fn().mockResolvedValue(false);
+        await (0, vitest_1.expect)((0, index_1.executeWithApproval)(tool, {}, mockContext, handler)).rejects.toThrow("Approval denied");
+    });
+});

package/dist/adapters/ai-sdk.d.ts

@@ -0,0 +1,50 @@
+import type { ToolSet } from "ai";
+import type { Tool } from "../types";
+import type { ResourceId } from "@kognitivedev/shared";
+/**
+ * Options for converting enhanced tools to AI SDK format.
+ */
+export interface AISDKToolOptions {
+    /** Resource context to inject into tool execution. */
+    resourceId?: ResourceId;
+    /** Memory snapshot to inject into tool context. */
+    memory?: {
+        systemBlock: string | null;
+        userContextBlock: string | null;
+    };
+    /** Abort signal to pass to tool execution. */
+    abortSignal?: AbortSignal;
+    /** Event handler for tool emissions. */
+    onEmit?: (toolId: string, event: string, data: unknown) => void;
+}
+/**
+ * Convert a single enhanced Tool to an AI SDK-compatible tool object.
+ *
+ * Returns a plain object matching the AI SDK Tool interface shape.
+ * This can be used directly with streamText, generateText, etc.
+ *
+ * @example
+ * ```ts
+ * import { streamText } from 'ai';
+ *
+ * const sdkTool = toAISDKTool(myTool, {
+ *   resourceId: { projectId: 'proj_1', userId: 'user_1' },
+ * });
+ * const result = await streamText({
+ *   model: openai('gpt-4o'),
+ *   tools: { search: sdkTool },
+ *   messages,
+ * });
+ * ```
+ */
+export declare function toAISDKTool(tool: Tool<any, any>, options?: AISDKToolOptions): ToolSet[string];
+/**
+ * Convert an array of enhanced Tools to an AI SDK ToolSet record.
+ *
+ * @example
+ * ```ts
+ * const tools = toAISDKTools([searchTool, createTool], { resourceId });
+ * const result = await streamText({ model, tools, messages });
+ * ```
+ */
+export declare function toAISDKTools(tools: Tool<any, any>[], options?: AISDKToolOptions): ToolSet;

package/dist/adapters/ai-sdk.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toAISDKTool = toAISDKTool;
+exports.toAISDKTools = toAISDKTools;
+/**
+ * Build a ToolContext from AISDKToolOptions for a specific tool.
+ */
+function buildContext(toolId, options) {
+    var _a, _b;
+    return {
+        abortSignal: (_a = options.abortSignal) !== null && _a !== void 0 ? _a : new AbortController().signal,
+        resourceId: (_b = options.resourceId) !== null && _b !== void 0 ? _b : { projectId: "default" },
+        memory: options.memory,
+        emit: (event, data) => {
+            var _a;
+            (_a = options.onEmit) === null || _a === void 0 ? void 0 : _a.call(options, toolId, event, data);
+        },
+    };
+}
+/**
+ * Convert a single enhanced Tool to an AI SDK-compatible tool object.
+ *
+ * Returns a plain object matching the AI SDK Tool interface shape.
+ * This can be used directly with streamText, generateText, etc.
+ *
+ * @example
+ * ```ts
+ * import { streamText } from 'ai';
+ *
+ * const sdkTool = toAISDKTool(myTool, {
+ *   resourceId: { projectId: 'proj_1', userId: 'user_1' },
+ * });
+ * const result = await streamText({
+ *   model: openai('gpt-4o'),
+ *   tools: { search: sdkTool },
+ *   messages,
+ * });
+ * ```
+ */
+function toAISDKTool(tool, options = {}) {
+    const context = buildContext(tool.id, options);
+    // Construct the AI SDK tool object directly.
+    // The AI SDK tool() function is a passthrough identity function for type safety.
+    // Building the object directly avoids generic type inference issues with `any`.
+    // AI SDK v6 uses `inputSchema` (not `parameters`).
+    return {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        execute: async (input) => {
+            const result = await tool.execute(input, context);
+            if (tool.toModelOutput) {
+                return tool.toModelOutput(result);
+            }
+            return result;
+        },
+    };
+}
+/**
+ * Convert an array of enhanced Tools to an AI SDK ToolSet record.
+ *
+ * @example
+ * ```ts
+ * const tools = toAISDKTools([searchTool, createTool], { resourceId });
+ * const result = await streamText({ model, tools, messages });
+ * ```
+ */
+function toAISDKTools(tools, options = {}) {
+    const result = {};
+    for (const t of tools) {
+        result[t.id] = toAISDKTool(t, options);
+    }
+    return result;
+}

package/dist/approval.d.ts

@@ -0,0 +1,15 @@
+import type { Tool, ToolContext, ApprovalRequest } from "./types";
+/**
+ * Callback type for handling tool approval requests.
+ * Return true to approve, false to deny.
+ */
+export type ApprovalHandler = (request: ApprovalRequest) => Promise<boolean>;
+/**
+ * Check if a tool requires approval for the given input.
+ */
+export declare function needsApproval<TInput>(tool: Tool<TInput, any>, input: TInput): boolean;
+/**
+ * Execute a tool with approval check.
+ * If the tool requires approval and the handler denies it, throws ApprovalDeniedError.
+ */
+export declare function executeWithApproval<TInput, TOutput>(tool: Tool<TInput, TOutput>, input: TInput, context: ToolContext, approvalHandler?: ApprovalHandler): Promise<TOutput>;

package/dist/approval.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.needsApproval = needsApproval;
+exports.executeWithApproval = executeWithApproval;
+const shared_1 = require("@kognitivedev/shared");
+/**
+ * Check if a tool requires approval for the given input.
+ */
+function needsApproval(tool, input) {
+    if (!tool.requireApproval)
+        return false;
+    if (typeof tool.requireApproval === "function") {
+        return tool.requireApproval(input);
+    }
+    return true;
+}
+/**
+ * Execute a tool with approval check.
+ * If the tool requires approval and the handler denies it, throws ApprovalDeniedError.
+ */
+async function executeWithApproval(tool, input, context, approvalHandler) {
+    if (needsApproval(tool, input)) {
+        if (!approvalHandler) {
+            throw new shared_1.ApprovalDeniedError(tool.id);
+        }
+        const approved = await approvalHandler({
+            toolId: tool.id,
+            input,
+            description: tool.description,
+        });
+        if (!approved) {
+            throw new shared_1.ApprovalDeniedError(tool.id);
+        }
+    }
+    return tool.execute(input, context);
+}

package/dist/create-tool.d.ts

@@ -0,0 +1,22 @@
+import type { ToolDefinition, Tool } from "./types";
+/**
+ * Create an enhanced tool with approval, abort, and context support.
+ *
+ * Tools created with this function can be converted to AI SDK tool() format
+ * via ToolRegistry.toAISDKTools() or toAISDKTool().
+ *
+ * @example
+ * ```ts
+ * const searchTool = createTool({
+ *   id: 'search-docs',
+ *   description: 'Search documentation',
+ *   inputSchema: z.object({ query: z.string() }),
+ *   execute: async (input, ctx) => {
+ *     // ctx.abortSignal, ctx.memory, ctx.resourceId available
+ *     return { results: [...] };
+ *   },
+ *   requireApproval: true,
+ * });
+ * ```
+ */
+export declare function createTool<TInput, TOutput>(definition: ToolDefinition<TInput, TOutput>): Tool<TInput, TOutput>;

package/dist/create-tool.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTool = createTool;
+/**
+ * Create an enhanced tool with approval, abort, and context support.
+ *
+ * Tools created with this function can be converted to AI SDK tool() format
+ * via ToolRegistry.toAISDKTools() or toAISDKTool().
+ *
+ * @example
+ * ```ts
+ * const searchTool = createTool({
+ *   id: 'search-docs',
+ *   description: 'Search documentation',
+ *   inputSchema: z.object({ query: z.string() }),
+ *   execute: async (input, ctx) => {
+ *     // ctx.abortSignal, ctx.memory, ctx.resourceId available
+ *     return { results: [...] };
+ *   },
+ *   requireApproval: true,
+ * });
+ * ```
+ */
+function createTool(definition) {
+    return {
+        id: definition.id,
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+        outputSchema: definition.outputSchema,
+        execute: definition.execute,
+        requireApproval: definition.requireApproval,
+        toModelOutput: definition.toModelOutput,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { ToolDefinition, Tool, ToolContext, ApprovalRequest } from "./types";
+export { createTool } from "./create-tool";
+export { ToolRegistry } from "./registry";
+export type { ApprovalHandler } from "./approval";
+export { needsApproval, executeWithApproval } from "./approval";
+export type { AISDKToolOptions } from "./adapters/ai-sdk";
+export { toAISDKTool, toAISDKTools } from "./adapters/ai-sdk";

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toAISDKTools = exports.toAISDKTool = exports.executeWithApproval = exports.needsApproval = exports.ToolRegistry = exports.createTool = void 0;
+var create_tool_1 = require("./create-tool");
+Object.defineProperty(exports, "createTool", { enumerable: true, get: function () { return create_tool_1.createTool; } });
+// Registry
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "ToolRegistry", { enumerable: true, get: function () { return registry_1.ToolRegistry; } });
+var approval_1 = require("./approval");
+Object.defineProperty(exports, "needsApproval", { enumerable: true, get: function () { return approval_1.needsApproval; } });
+Object.defineProperty(exports, "executeWithApproval", { enumerable: true, get: function () { return approval_1.executeWithApproval; } });
+var ai_sdk_1 = require("./adapters/ai-sdk");
+Object.defineProperty(exports, "toAISDKTool", { enumerable: true, get: function () { return ai_sdk_1.toAISDKTool; } });
+Object.defineProperty(exports, "toAISDKTools", { enumerable: true, get: function () { return ai_sdk_1.toAISDKTools; } });

package/dist/registry.d.ts

@@ -0,0 +1,56 @@
+import type { Tool } from "./types";
+import { type AISDKToolOptions } from "./adapters/ai-sdk";
+/**
+ * Registry for managing a named collection of tools.
+ * Provides lookup by ID and bulk conversion to AI SDK format.
+ *
+ * @example
+ * ```ts
+ * const registry = new ToolRegistry();
+ * registry.register(searchTool);
+ * registry.register(createTicketTool);
+ *
+ * // Use with AI SDK streamText directly
+ * const result = await streamText({
+ *   model: openai('gpt-4o'),
+ *   tools: registry.toAISDKTools(),
+ *   messages,
+ * });
+ * ```
+ */
+export declare class ToolRegistry {
+    private tools;
+    /**
+     * Register a tool. Throws if a tool with the same ID already exists.
+     */
+    register(tool: Tool<any, any>): void;
+    /**
+     * Get a tool by ID. Returns undefined if not found.
+     */
+    get(id: string): Tool<any, any> | undefined;
+    /**
+     * Check if a tool with the given ID is registered.
+     */
+    has(id: string): boolean;
+    /**
+     * Remove a tool by ID.
+     */
+    remove(id: string): boolean;
+    /**
+     * Get all registered tools.
+     */
+    all(): Tool<any, any>[];
+    /**
+     * Get the number of registered tools.
+     */
+    get size(): number;
+    /**
+     * Convert all registered tools to AI SDK tool() format.
+     * The returned object can be passed directly to streamText/generateText.
+     */
+    toAISDKTools(options?: AISDKToolOptions): Record<string, any>;
+    /**
+     * Get tool IDs that require approval for the given input context.
+     */
+    getApprovalRequired(inputs: Record<string, unknown>): string[];
+}

package/dist/registry.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = void 0;
+const approval_1 = require("./approval");
+const ai_sdk_1 = require("./adapters/ai-sdk");
+/**
+ * Registry for managing a named collection of tools.
+ * Provides lookup by ID and bulk conversion to AI SDK format.
+ *
+ * @example
+ * ```ts
+ * const registry = new ToolRegistry();
+ * registry.register(searchTool);
+ * registry.register(createTicketTool);
+ *
+ * // Use with AI SDK streamText directly
+ * const result = await streamText({
+ *   model: openai('gpt-4o'),
+ *   tools: registry.toAISDKTools(),
+ *   messages,
+ * });
+ * ```
+ */
+class ToolRegistry {
+    constructor() {
+        this.tools = new Map();
+    }
+    /**
+     * Register a tool. Throws if a tool with the same ID already exists.
+     */
+    register(tool) {
+        if (this.tools.has(tool.id)) {
+            throw new Error(`Tool with id "${tool.id}" already registered`);
+        }
+        this.tools.set(tool.id, tool);
+    }
+    /**
+     * Get a tool by ID. Returns undefined if not found.
+     */
+    get(id) {
+        return this.tools.get(id);
+    }
+    /**
+     * Check if a tool with the given ID is registered.
+     */
+    has(id) {
+        return this.tools.has(id);
+    }
+    /**
+     * Remove a tool by ID.
+     */
+    remove(id) {
+        return this.tools.delete(id);
+    }
+    /**
+     * Get all registered tools.
+     */
+    all() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Get the number of registered tools.
+     */
+    get size() {
+        return this.tools.size;
+    }
+    /**
+     * Convert all registered tools to AI SDK tool() format.
+     * The returned object can be passed directly to streamText/generateText.
+     */
+    toAISDKTools(options) {
+        const result = {};
+        for (const tool of this.tools.values()) {
+            result[tool.id] = (0, ai_sdk_1.toAISDKTool)(tool, options);
+        }
+        return result;
+    }
+    /**
+     * Get tool IDs that require approval for the given input context.
+     */
+    getApprovalRequired(inputs) {
+        const result = [];
+        for (const tool of this.tools.values()) {
+            const input = inputs[tool.id];
+            if (input !== undefined && (0, approval_1.needsApproval)(tool, input)) {
+                result.push(tool.id);
+            }
+        }
+        return result;
+    }
+}
+exports.ToolRegistry = ToolRegistry;

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+import type { ZodType } from "zod";
+import type { ResourceId, Metadata } from "@kognitivedev/shared";
+/**
+ * Context provided to tool execute functions.
+ * Enriched with memory, abort signal, and event emission.
+ */
+export interface ToolContext {
+    /** Signal for aborting long-running tool operations. */
+    abortSignal: AbortSignal;
+    /** Resource scope (user, project, session). */
+    resourceId: ResourceId;
+    /** Memory snapshot if available (injected by agent runtime). */
+    memory?: {
+        systemBlock: string | null;
+        userContextBlock: string | null;
+    };
+    /** Emit events for streaming partial results or progress updates. */
+    emit: (event: string, data: unknown) => void;
+    /** Arbitrary metadata passed through from the caller. */
+    metadata?: Metadata;
+}
+/**
+ * Definition for creating an enhanced tool.
+ */
+export interface ToolDefinition<TInput = any, TOutput = any> {
+    /** Unique identifier for the tool. */
+    id: string;
+    /** Human-readable description (sent to the model). */
+    description: string;
+    /** Zod schema for validating tool input. */
+    inputSchema: ZodType<TInput>;
+    /** Optional Zod schema for validating tool output. */
+    outputSchema?: ZodType<TOutput>;
+    /** Execute the tool with validated input and context. */
+    execute: (input: TInput, context: ToolContext) => Promise<TOutput>;
+    /**
+     * Whether this tool requires human approval before execution.
+     * - `true`: Always require approval
+     * - Function: Conditionally require based on input
+     */
+    requireApproval?: boolean | ((input: TInput) => boolean);
+    /**
+     * Transform tool output before sending to the model.
+     * Useful for large outputs — keep full result in application, send summary to model.
+     */
+    toModelOutput?: (output: TOutput) => string;
+}
+/**
+ * A created tool instance with its definition and metadata.
+ */
+export interface Tool<TInput = any, TOutput = any> {
+    /** Unique identifier. */
+    id: string;
+    /** Human-readable description. */
+    description: string;
+    /** Input schema. */
+    inputSchema: ZodType<TInput>;
+    /** Output schema. */
+    outputSchema?: ZodType<TOutput>;
+    /** Execute the tool. */
+    execute: (input: TInput, context: ToolContext) => Promise<TOutput>;
+    /** Approval requirement. */
+    requireApproval?: boolean | ((input: TInput) => boolean);
+    /** Output transformation for model context. */
+    toModelOutput?: (output: TOutput) => string;
+}
+/**
+ * Request for human approval of a tool execution.
+ */
+export interface ApprovalRequest {
+    toolId: string;
+    input: unknown;
+    description: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@kognitivedev/tools",
+  "version": "0.2.2",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@kognitivedev/shared": "workspace:*"
+  },
+  "peerDependencies": {
+    "ai": ">=5.0.0",
+    "zod": ">=3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "ai": "^6.0.0",
+    "zod": "^3.23.8",
+    "vitest": "^3.0.0"
+  },
+  "description": "Tool system with approval workflows and AI SDK conversion",
+  "keywords": [
+    "kognitive",
+    "ai",
+    "tools",
+    "approval",
+    "vercel-ai-sdk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kognitivedev/kognitive",
+    "directory": "packages/tools"
+  },
+  "homepage": "https://kognitive.dev"
+}

package/src/__tests__/tools.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { createTool, ToolRegistry, needsApproval, executeWithApproval } from "../index";
+import type { ToolContext } from "../types";
+
+const mockContext: ToolContext = {
+    abortSignal: new AbortController().signal,
+    resourceId: { projectId: "test" },
+    emit: vi.fn(),
+};
+
+describe("createTool", () => {
+    it("creates a tool with correct properties", () => {
+        const tool = createTool({
+            id: "test-tool",
+            description: "A test tool",
+            inputSchema: z.object({ query: z.string() }),
+            execute: async (input) => ({ result: input.query }),
+        });
+
+        expect(tool.id).toBe("test-tool");
+        expect(tool.description).toBe("A test tool");
+        expect(tool.inputSchema).toBeDefined();
+        expect(tool.execute).toBeTypeOf("function");
+    });
+
+    it("executes with input and context", async () => {
+        const tool = createTool({
+            id: "echo",
+            description: "Echo",
+            inputSchema: z.object({ msg: z.string() }),
+            execute: async (input) => input.msg,
+        });
+
+        const result = await tool.execute({ msg: "hello" }, mockContext);
+        expect(result).toBe("hello");
+    });
+});
+
+describe("ToolRegistry", () => {
+    it("registers and retrieves tools", () => {
+        const registry = new ToolRegistry();
+        const tool = createTool({
+            id: "t1",
+            description: "Tool 1",
+            inputSchema: z.object({}),
+            execute: async () => "ok",
+        });
+
+        registry.register(tool);
+        expect(registry.get("t1")).toBe(tool);
+        expect(registry.has("t1")).toBe(true);
+        expect(registry.size).toBe(1);
+    });
+
+    it("throws on duplicate registration", () => {
+        const registry = new ToolRegistry();
+        const tool = createTool({
+            id: "t1",
+            description: "Tool",
+            inputSchema: z.object({}),
+            execute: async () => "ok",
+        });
+
+        registry.register(tool);
+        expect(() => registry.register(tool)).toThrow("already registered");
+    });
+
+    it("all returns all tools", () => {
+        const registry = new ToolRegistry();
+        const t1 = createTool({ id: "t1", description: "1", inputSchema: z.object({}), execute: async () => 1 });
+        const t2 = createTool({ id: "t2", description: "2", inputSchema: z.object({}), execute: async () => 2 });
+        registry.register(t1);
+        registry.register(t2);
+        expect(registry.all()).toHaveLength(2);
+    });
+
+    it("remove deletes tool", () => {
+        const registry = new ToolRegistry();
+        const tool = createTool({ id: "t1", description: "1", inputSchema: z.object({}), execute: async () => 1 });
+        registry.register(tool);
+        registry.remove("t1");
+        expect(registry.has("t1")).toBe(false);
+    });
+
+    it("toAISDKTools returns record with tool ids as keys", () => {
+        const registry = new ToolRegistry();
+        registry.register(createTool({ id: "search", description: "Search", inputSchema: z.object({ q: z.string() }), execute: async () => "result" }));
+        const sdkTools = registry.toAISDKTools();
+        expect(sdkTools).toHaveProperty("search");
+    });
+});
+
+describe("needsApproval", () => {
+    it("returns false when no requireApproval", () => {
+        const tool = createTool({ id: "t", description: "t", inputSchema: z.object({}), execute: async () => null });
+        expect(needsApproval(tool, {})).toBe(false);
+    });
+
+    it("returns true when requireApproval is true", () => {
+        const tool = createTool({ id: "t", description: "t", inputSchema: z.object({}), execute: async () => null, requireApproval: true });
+        expect(needsApproval(tool, {})).toBe(true);
+    });
+
+    it("evaluates function requireApproval", () => {
+        const tool = createTool({
+            id: "t",
+            description: "t",
+            inputSchema: z.object({ amount: z.number() }),
+            execute: async () => null,
+            requireApproval: (input: { amount: number }) => input.amount > 100,
+        });
+        expect(needsApproval(tool, { amount: 50 })).toBe(false);
+        expect(needsApproval(tool, { amount: 200 })).toBe(true);
+    });
+});
+
+describe("executeWithApproval", () => {
+    it("executes when no approval needed", async () => {
+        const tool = createTool({ id: "t", description: "t", inputSchema: z.object({}), execute: async () => "done" });
+        const result = await executeWithApproval(tool, {}, mockContext);
+        expect(result).toBe("done");
+    });
+
+    it("throws when approval needed but no handler", async () => {
+        const tool = createTool({ id: "t", description: "t", inputSchema: z.object({}), execute: async () => "done", requireApproval: true });
+        await expect(executeWithApproval(tool, {}, mockContext)).rejects.toThrow("Approval denied");
+    });
+
+    it("executes when handler approves", async () => {
+        const tool = createTool({ id: "t", description: "t", inputSchema: z.object({}), execute: async () => "done", requireApproval: true });
+        const handler = vi.fn().mockResolvedValue(true);
+        const result = await executeWithApproval(tool, {}, mockContext, handler);
+        expect(result).toBe("done");
+        expect(handler).toHaveBeenCalled();
+    });
+
+    it("throws when handler denies", async () => {
+        const tool = createTool({ id: "t", description: "t", inputSchema: z.object({}), execute: async () => "done", requireApproval: true });
+        const handler = vi.fn().mockResolvedValue(false);
+        await expect(executeWithApproval(tool, {}, mockContext, handler)).rejects.toThrow("Approval denied");
+    });
+});

package/src/adapters/ai-sdk.ts

@@ -0,0 +1,94 @@
+import type { ToolSet } from "ai";
+import type { Tool, ToolContext } from "../types";
+import type { ResourceId } from "@kognitivedev/shared";
+
+/**
+ * Options for converting enhanced tools to AI SDK format.
+ */
+export interface AISDKToolOptions {
+    /** Resource context to inject into tool execution. */
+    resourceId?: ResourceId;
+    /** Memory snapshot to inject into tool context. */
+    memory?: { systemBlock: string | null; userContextBlock: string | null };
+    /** Abort signal to pass to tool execution. */
+    abortSignal?: AbortSignal;
+    /** Event handler for tool emissions. */
+    onEmit?: (toolId: string, event: string, data: unknown) => void;
+}
+
+/**
+ * Build a ToolContext from AISDKToolOptions for a specific tool.
+ */
+function buildContext(toolId: string, options: AISDKToolOptions): ToolContext {
+    return {
+        abortSignal: options.abortSignal ?? new AbortController().signal,
+        resourceId: options.resourceId ?? { projectId: "default" },
+        memory: options.memory,
+        emit: (event, data) => {
+            options.onEmit?.(toolId, event, data);
+        },
+    };
+}
+
+/**
+ * Convert a single enhanced Tool to an AI SDK-compatible tool object.
+ *
+ * Returns a plain object matching the AI SDK Tool interface shape.
+ * This can be used directly with streamText, generateText, etc.
+ *
+ * @example
+ * ```ts
+ * import { streamText } from 'ai';
+ *
+ * const sdkTool = toAISDKTool(myTool, {
+ *   resourceId: { projectId: 'proj_1', userId: 'user_1' },
+ * });
+ * const result = await streamText({
+ *   model: openai('gpt-4o'),
+ *   tools: { search: sdkTool },
+ *   messages,
+ * });
+ * ```
+ */
+export function toAISDKTool(
+    tool: Tool<any, any>,
+    options: AISDKToolOptions = {}
+): ToolSet[string] {
+    const context = buildContext(tool.id, options);
+
+    // Construct the AI SDK tool object directly.
+    // The AI SDK tool() function is a passthrough identity function for type safety.
+    // Building the object directly avoids generic type inference issues with `any`.
+    // AI SDK v6 uses `inputSchema` (not `parameters`).
+    return {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        execute: async (input: any) => {
+            const result = await tool.execute(input, context);
+            if (tool.toModelOutput) {
+                return tool.toModelOutput(result);
+            }
+            return result;
+        },
+    } as unknown as ToolSet[string];
+}
+
+/**
+ * Convert an array of enhanced Tools to an AI SDK ToolSet record.
+ *
+ * @example
+ * ```ts
+ * const tools = toAISDKTools([searchTool, createTool], { resourceId });
+ * const result = await streamText({ model, tools, messages });
+ * ```
+ */
+export function toAISDKTools(
+    tools: Tool<any, any>[],
+    options: AISDKToolOptions = {}
+): ToolSet {
+    const result: ToolSet = {};
+    for (const t of tools) {
+        result[t.id] = toAISDKTool(t, options);
+    }
+    return result;
+}

package/src/approval.ts

@@ -0,0 +1,48 @@
+import type { Tool, ToolContext, ApprovalRequest } from "./types";
+import { ApprovalDeniedError } from "@kognitivedev/shared";
+
+/**
+ * Callback type for handling tool approval requests.
+ * Return true to approve, false to deny.
+ */
+export type ApprovalHandler = (request: ApprovalRequest) => Promise<boolean>;
+
+/**
+ * Check if a tool requires approval for the given input.
+ */
+export function needsApproval<TInput>(
+    tool: Tool<TInput, any>,
+    input: TInput
+): boolean {
+    if (!tool.requireApproval) return false;
+    if (typeof tool.requireApproval === "function") {
+        return tool.requireApproval(input);
+    }
+    return true;
+}
+
+/**
+ * Execute a tool with approval check.
+ * If the tool requires approval and the handler denies it, throws ApprovalDeniedError.
+ */
+export async function executeWithApproval<TInput, TOutput>(
+    tool: Tool<TInput, TOutput>,
+    input: TInput,
+    context: ToolContext,
+    approvalHandler?: ApprovalHandler
+): Promise<TOutput> {
+    if (needsApproval(tool, input)) {
+        if (!approvalHandler) {
+            throw new ApprovalDeniedError(tool.id);
+        }
+        const approved = await approvalHandler({
+            toolId: tool.id,
+            input,
+            description: tool.description,
+        });
+        if (!approved) {
+            throw new ApprovalDeniedError(tool.id);
+        }
+    }
+    return tool.execute(input, context);
+}

package/src/create-tool.ts

@@ -0,0 +1,35 @@
+import type { ToolDefinition, Tool } from "./types";
+
+/**
+ * Create an enhanced tool with approval, abort, and context support.
+ *
+ * Tools created with this function can be converted to AI SDK tool() format
+ * via ToolRegistry.toAISDKTools() or toAISDKTool().
+ *
+ * @example
+ * ```ts
+ * const searchTool = createTool({
+ *   id: 'search-docs',
+ *   description: 'Search documentation',
+ *   inputSchema: z.object({ query: z.string() }),
+ *   execute: async (input, ctx) => {
+ *     // ctx.abortSignal, ctx.memory, ctx.resourceId available
+ *     return { results: [...] };
+ *   },
+ *   requireApproval: true,
+ * });
+ * ```
+ */
+export function createTool<TInput, TOutput>(
+    definition: ToolDefinition<TInput, TOutput>
+): Tool<TInput, TOutput> {
+    return {
+        id: definition.id,
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+        outputSchema: definition.outputSchema,
+        execute: definition.execute,
+        requireApproval: definition.requireApproval,
+        toModelOutput: definition.toModelOutput,
+    };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Core
+export type { ToolDefinition, Tool, ToolContext, ApprovalRequest } from "./types";
+export { createTool } from "./create-tool";
+
+// Registry
+export { ToolRegistry } from "./registry";
+
+// Approval
+export type { ApprovalHandler } from "./approval";
+export { needsApproval, executeWithApproval } from "./approval";
+
+// AI SDK Adapter
+export type { AISDKToolOptions } from "./adapters/ai-sdk";
+export { toAISDKTool, toAISDKTools } from "./adapters/ai-sdk";

package/src/registry.ts

@@ -0,0 +1,97 @@
+import type { Tool, ToolContext } from "./types";
+import type { ApprovalHandler } from "./approval";
+import { needsApproval } from "./approval";
+import { toAISDKTool, type AISDKToolOptions } from "./adapters/ai-sdk";
+
+/**
+ * Registry for managing a named collection of tools.
+ * Provides lookup by ID and bulk conversion to AI SDK format.
+ *
+ * @example
+ * ```ts
+ * const registry = new ToolRegistry();
+ * registry.register(searchTool);
+ * registry.register(createTicketTool);
+ *
+ * // Use with AI SDK streamText directly
+ * const result = await streamText({
+ *   model: openai('gpt-4o'),
+ *   tools: registry.toAISDKTools(),
+ *   messages,
+ * });
+ * ```
+ */
+export class ToolRegistry {
+    private tools = new Map<string, Tool<any, any>>();
+
+    /**
+     * Register a tool. Throws if a tool with the same ID already exists.
+     */
+    register(tool: Tool<any, any>): void {
+        if (this.tools.has(tool.id)) {
+            throw new Error(`Tool with id "${tool.id}" already registered`);
+        }
+        this.tools.set(tool.id, tool);
+    }
+
+    /**
+     * Get a tool by ID. Returns undefined if not found.
+     */
+    get(id: string): Tool<any, any> | undefined {
+        return this.tools.get(id);
+    }
+
+    /**
+     * Check if a tool with the given ID is registered.
+     */
+    has(id: string): boolean {
+        return this.tools.has(id);
+    }
+
+    /**
+     * Remove a tool by ID.
+     */
+    remove(id: string): boolean {
+        return this.tools.delete(id);
+    }
+
+    /**
+     * Get all registered tools.
+     */
+    all(): Tool<any, any>[] {
+        return Array.from(this.tools.values());
+    }
+
+    /**
+     * Get the number of registered tools.
+     */
+    get size(): number {
+        return this.tools.size;
+    }
+
+    /**
+     * Convert all registered tools to AI SDK tool() format.
+     * The returned object can be passed directly to streamText/generateText.
+     */
+    toAISDKTools(options?: AISDKToolOptions): Record<string, any> {
+        const result: Record<string, any> = {};
+        for (const tool of this.tools.values()) {
+            result[tool.id] = toAISDKTool(tool, options);
+        }
+        return result;
+    }
+
+    /**
+     * Get tool IDs that require approval for the given input context.
+     */
+    getApprovalRequired(inputs: Record<string, unknown>): string[] {
+        const result: string[] = [];
+        for (const tool of this.tools.values()) {
+            const input = inputs[tool.id];
+            if (input !== undefined && needsApproval(tool, input)) {
+                result.push(tool.id);
+            }
+        }
+        return result;
+    }
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+import type { ZodType } from "zod";
+import type { ResourceId, Metadata } from "@kognitivedev/shared";
+
+/**
+ * Context provided to tool execute functions.
+ * Enriched with memory, abort signal, and event emission.
+ */
+export interface ToolContext {
+    /** Signal for aborting long-running tool operations. */
+    abortSignal: AbortSignal;
+    /** Resource scope (user, project, session). */
+    resourceId: ResourceId;
+    /** Memory snapshot if available (injected by agent runtime). */
+    memory?: { systemBlock: string | null; userContextBlock: string | null };
+    /** Emit events for streaming partial results or progress updates. */
+    emit: (event: string, data: unknown) => void;
+    /** Arbitrary metadata passed through from the caller. */
+    metadata?: Metadata;
+}
+
+/**
+ * Definition for creating an enhanced tool.
+ */
+export interface ToolDefinition<TInput = any, TOutput = any> {
+    /** Unique identifier for the tool. */
+    id: string;
+    /** Human-readable description (sent to the model). */
+    description: string;
+    /** Zod schema for validating tool input. */
+    inputSchema: ZodType<TInput>;
+    /** Optional Zod schema for validating tool output. */
+    outputSchema?: ZodType<TOutput>;
+    /** Execute the tool with validated input and context. */
+    execute: (input: TInput, context: ToolContext) => Promise<TOutput>;
+    /**
+     * Whether this tool requires human approval before execution.
+     * - `true`: Always require approval
+     * - Function: Conditionally require based on input
+     */
+    requireApproval?: boolean | ((input: TInput) => boolean);
+    /**
+     * Transform tool output before sending to the model.
+     * Useful for large outputs — keep full result in application, send summary to model.
+     */
+    toModelOutput?: (output: TOutput) => string;
+}
+
+/**
+ * A created tool instance with its definition and metadata.
+ */
+export interface Tool<TInput = any, TOutput = any> {
+    /** Unique identifier. */
+    id: string;
+    /** Human-readable description. */
+    description: string;
+    /** Input schema. */
+    inputSchema: ZodType<TInput>;
+    /** Output schema. */
+    outputSchema?: ZodType<TOutput>;
+    /** Execute the tool. */
+    execute: (input: TInput, context: ToolContext) => Promise<TOutput>;
+    /** Approval requirement. */
+    requireApproval?: boolean | ((input: TInput) => boolean);
+    /** Output transformation for model context. */
+    toModelOutput?: (output: TOutput) => string;
+}
+
+/**
+ * Request for human approval of a tool execution.
+ */
+export interface ApprovalRequest {
+    toolId: string;
+    input: unknown;
+    description: string;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "module": "commonjs",
+        "rootDir": "src",
+        "outDir": "dist",
+        "declaration": true,
+        "noEmit": false,
+        "incremental": false
+    },
+    "include": [
+        "src"
+    ]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: "node",
+    },
+});