@strands-agents/sdk 0.0.1

package/dist/tools/function-tool.js

@@ -0,0 +1,237 @@
+import { deepCopy } from '../types/json';
+/**
+ * A Tool implementation that wraps a callback function and handles all ToolResult conversion.
+ *
+ * FunctionTool allows creating tools from existing functions without needing to manually
+ * handle ToolResult formatting or error handling. It supports multiple callback patterns:
+ * - Async generators for streaming responses
+ * - Promises for async operations
+ * - Synchronous functions for immediate results
+ *
+ * All return values are automatically wrapped in ToolResult, and errors are caught and
+ * returned as error ToolResults.
+ *
+ * @example
+ * ```typescript
+ * // Create a tool with streaming
+ * const streamingTool = new FunctionTool({
+ *   name: 'processor',
+ *   description: 'Processes data with progress updates',
+ *   inputSchema: { type: 'object', properties: { data: { type: 'string' } } },
+ *   callback: async function* (input: any) {
+ *     yield 'Starting processing...'
+ *     // Do some work
+ *     yield 'Halfway done...'
+ *     // More work
+ *     return 'Processing complete!'
+ *   }
+ * })
+ * ```
+ */
+export class FunctionTool {
+    /**
+     * The unique name of the tool.
+     */
+    toolName;
+    /**
+     * Human-readable description of what the tool does.
+     */
+    description;
+    /**
+     * OpenAPI JSON specification for the tool.
+     */
+    toolSpec;
+    /**
+     * The callback function that implements the tool's logic.
+     */
+    _callback;
+    /**
+     * Creates a new FunctionTool instance.
+     *
+     * @param config - Configuration object for the tool
+     *
+     * @example
+     * ```typescript
+     * const tool = new FunctionTool({
+     *   name: 'greeter',
+     *   description: 'Greets a person by name',
+     *   inputSchema: {
+     *     type: 'object',
+     *     properties: { name: { type: 'string' } },
+     *     required: ['name']
+     *   },
+     *   callback: (input: any) => `Hello, ${input.name}!`
+     * })
+     * ```
+     */
+    constructor(config) {
+        this.toolName = config.name;
+        this.description = config.description;
+        this.toolSpec = {
+            name: config.name,
+            description: config.description,
+            inputSchema: config.inputSchema,
+        };
+        this._callback = config.callback;
+    }
+    /**
+     * Executes the tool with streaming support.
+     * Handles all callback patterns (async generator, promise, sync) and converts results to ToolResult.
+     *
+     * @param toolContext - Context information including the tool use request and invocation state
+     * @returns Async generator that yields ToolStreamEvents and returns a ToolResult
+     */
+    async *stream(toolContext) {
+        const { toolUse } = toolContext;
+        try {
+            const result = this._callback(toolUse.input, toolContext);
+            // Check if result is an async generator
+            if (result && typeof result === 'object' && Symbol.asyncIterator in result) {
+                // Handle async generator: yield each value as ToolStreamEvent, wrap final value in ToolResult
+                const generator = result;
+                // Iterate through all yielded values
+                let iterResult = await generator.next();
+                while (!iterResult.done) {
+                    // Each yielded value becomes a ToolStreamEvent
+                    yield {
+                        type: 'toolStreamEvent',
+                        data: iterResult.value,
+                    };
+                    iterResult = await generator.next();
+                }
+                // The generator's return value (when done = true) is wrapped in ToolResult
+                return this._wrapInToolResult(iterResult.value, toolUse.toolUseId);
+            }
+            else if (result instanceof Promise) {
+                // Handle promise: await and wrap in ToolResult
+                const value = await result;
+                return this._wrapInToolResult(value, toolUse.toolUseId);
+            }
+            else {
+                // Handle synchronous value: wrap in ToolResult
+                return this._wrapInToolResult(result, toolUse.toolUseId);
+            }
+        }
+        catch (error) {
+            // Handle any errors and yield as error ToolResult
+            return this._createErrorResult(error, toolUse.toolUseId);
+        }
+    }
+    /**
+     * Wraps a value in a ToolResult with success status.
+     *
+     * Due to AWS Bedrock limitations (only accepts objects as JSON content), the following
+     * rules are applied:
+     * - Strings → toolResultTextContent
+     * - Numbers, Booleans → toolResultTextContent (converted to string)
+     * - null, undefined → toolResultTextContent (special string representation)
+     * - Objects → toolResultJsonContent (with deep copy)
+     * - Arrays → toolResultJsonContent wrapped in \{ $value: array \} (with deep copy)
+     *
+     * @param value - The value to wrap (can be any type)
+     * @param toolUseId - The tool use ID for the ToolResult
+     * @returns A ToolResult containing the value
+     */
+    _wrapInToolResult(value, toolUseId) {
+        try {
+            // Handle null with special string representation as text content
+            if (value === null) {
+                return {
+                    toolUseId,
+                    status: 'success',
+                    content: [
+                        {
+                            type: 'toolResultTextContent',
+                            text: '<null>',
+                        },
+                    ],
+                };
+            }
+            // Handle undefined with special string representation as text content
+            if (value === undefined) {
+                return {
+                    toolUseId,
+                    status: 'success',
+                    content: [
+                        {
+                            type: 'toolResultTextContent',
+                            text: '<undefined>',
+                        },
+                    ],
+                };
+            }
+            // Handle primitives (strings, numbers, booleans) as text content
+            // Bedrock doesn't accept primitives as JSON content, so we convert all to strings
+            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                return {
+                    toolUseId,
+                    status: 'success',
+                    content: [
+                        {
+                            type: 'toolResultTextContent',
+                            text: String(value),
+                        },
+                    ],
+                };
+            }
+            // Handle arrays by wrapping in object { $value: array }
+            if (Array.isArray(value)) {
+                const copiedValue = deepCopy(value);
+                return {
+                    toolUseId,
+                    status: 'success',
+                    content: [
+                        {
+                            type: 'toolResultJsonContent',
+                            json: { $value: copiedValue },
+                        },
+                    ],
+                };
+            }
+            // Handle objects as JSON content with deep copy
+            const copiedValue = deepCopy(value);
+            return {
+                toolUseId,
+                status: 'success',
+                content: [
+                    {
+                        type: 'toolResultJsonContent',
+                        json: copiedValue,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            // If deep copy fails (circular references, non-serializable values), return error result
+            return this._createErrorResult(error, toolUseId);
+        }
+    }
+    /**
+     * Creates an error ToolResult from an error object.
+     * Ensures all errors are normalized to Error objects and includes the original error
+     * in the ToolResult for inspection by hooks, error handlers, and event loop.
+     *
+     * TODO: Implement consistent logging format as defined in #30
+     * This error should be logged to the caller using the established logging pattern.
+     *
+     * @param error - The error that occurred (can be Error object or any thrown value)
+     * @param toolUseId - The tool use ID for the ToolResult
+     * @returns A ToolResult with error status, error message content, and original error object
+     */
+    _createErrorResult(error, toolUseId) {
+        // Ensure error is an Error object (wrap non-Error values)
+        const errorObject = error instanceof Error ? error : new Error(String(error));
+        return {
+            toolUseId,
+            status: 'error',
+            content: [
+                {
+                    type: 'toolResultTextContent',
+                    text: `Error: ${errorObject.message}`,
+                },
+            ],
+            error: errorObject,
+        };
+    }
+}
+//# sourceMappingURL=function-tool.js.map

package/dist/tools/function-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-tool.js","sourceRoot":"","sources":["../../src/tools/function-tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,43 @@
+import type { Tool } from './tool';
+/**
+ * Registry for managing Tool instances.
+ */
+export declare class ToolRegistry {
+    private readonly _tools;
+    /**
+     * Creates a new ToolRegistry instance with an empty registry.
+     */
+    constructor();
+    /**
+     * Registers one or more tools with the registry.
+     * Accepts single Tool or array of Tools for convenience.
+     *
+     * @param tool - Single Tool instance or array of Tool instances to register
+     * @throws If a tool with duplicate name already exists
+     * @throws If tool name is invalid (must be 1-64 chars, alphanumeric with hyphens/underscores)
+     * @throws If tool description is empty
+     */
+    register(tool: Tool | Tool[]): void;
+    /**
+     * Retrieves a tool by its unique name.
+     *
+     * @param name - The unique name of the tool to retrieve
+     * @returns The Tool instance, or undefined if not found
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * Removes a tool from the registry.
+     *
+     * @param name - The name of the tool to remove
+     * @throws If tool with given name doesn't exist
+     */
+    remove(name: string): void;
+    /**
+     * Returns all registered tools as an array.
+     * Returns a copy of the internal array to prevent external mutation.
+     *
+     * @returns Array of all registered Tool instances, or empty array if no tools registered
+     */
+    list(): Tool[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAElC;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAE1C;;OAEG;;IAKH;;;;;;;;OAQG;IACI,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI;IAoC1C;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAI1C;;;;;OAKG;IACI,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IASjC;;;;;OAKG;IACI,IAAI,IAAI,IAAI,EAAE;CAGtB"}

package/dist/tools/registry.js

@@ -0,0 +1,82 @@
+/**
+ * Registry for managing Tool instances.
+ */
+export class ToolRegistry {
+    _tools;
+    /**
+     * Creates a new ToolRegistry instance with an empty registry.
+     */
+    constructor() {
+        this._tools = new Map();
+    }
+    /**
+     * Registers one or more tools with the registry.
+     * Accepts single Tool or array of Tools for convenience.
+     *
+     * @param tool - Single Tool instance or array of Tool instances to register
+     * @throws If a tool with duplicate name already exists
+     * @throws If tool name is invalid (must be 1-64 chars, alphanumeric with hyphens/underscores)
+     * @throws If tool description is empty
+     */
+    register(tool) {
+        const tools = Array.isArray(tool) ? tool : [tool];
+        for (const t of tools) {
+            // Validate tool name is a string
+            if (typeof t.toolName !== 'string') {
+                throw new Error('Tool name must be a string');
+            }
+            // Validate tool name length (1-64 characters)
+            if (t.toolName.length < 1 || t.toolName.length > 64) {
+                throw new Error('Tool name must be between 1 and 64 characters');
+            }
+            // Validate tool name pattern (alphanumeric with hyphens and underscores)
+            const validNamePattern = /^[a-zA-Z0-9_-]+$/;
+            if (!validNamePattern.test(t.toolName)) {
+                throw new Error('Tool name must contain only alphanumeric characters, hyphens, and underscores');
+            }
+            // Validate tool description if present
+            if (t.description !== undefined && t.description !== null) {
+                if (typeof t.description !== 'string' || t.description.length < 1) {
+                    throw new Error('Tool description must be a non-empty string');
+                }
+            }
+            // Check for duplicate names
+            if (this._tools.has(t.toolName)) {
+                throw new Error(`Tool with name '${t.toolName}' already registered`);
+            }
+            this._tools.set(t.toolName, t);
+        }
+    }
+    /**
+     * Retrieves a tool by its unique name.
+     *
+     * @param name - The unique name of the tool to retrieve
+     * @returns The Tool instance, or undefined if not found
+     */
+    get(name) {
+        return this._tools.get(name);
+    }
+    /**
+     * Removes a tool from the registry.
+     *
+     * @param name - The name of the tool to remove
+     * @throws If tool with given name doesn't exist
+     */
+    remove(name) {
+        // Check if tool exists
+        if (!this._tools.has(name)) {
+            throw new Error(`Tool with name '${name}' not found`);
+        }
+        this._tools.delete(name);
+    }
+    /**
+     * Returns all registered tools as an array.
+     * Returns a copy of the internal array to prevent external mutation.
+     *
+     * @returns Array of all registered Tool instances, or empty array if no tools registered
+     */
+    list() {
+        return Array.from(this._tools.values());
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,CAAmB;IAE1C;;OAEG;IACH;QACE,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAgB,CAAA;IACvC,CAAC;IAED;;;;;;;;OAQG;IACI,QAAQ,CAAC,IAAmB;QACjC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAEjD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,iCAAiC;YACjC,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAA;YAC/C,CAAC;YAED,8CAA8C;YAC9C,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;gBACpD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;YAClE,CAAC;YAED,yEAAyE;YACzE,MAAM,gBAAgB,GAAG,kBAAkB,CAAA;YAC3C,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACvC,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAA;YAClG,CAAC;YAED,uCAAuC;YACvC,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;gBAC1D,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAClE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;gBAChE,CAAC;YACH,CAAC;YAED,4BAA4B;YAC5B,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,QAAQ,sBAAsB,CAAC,CAAA;YACtE,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;QAChC,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,GAAG,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,IAAY;QACxB,uBAAuB;QACvB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,aAAa,CAAC,CAAA;QACvD,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IAED;;;;;OAKG;IACI,IAAI;QACT,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;IACzC,CAAC;CACF"}

package/dist/tools/tool.d.ts

@@ -0,0 +1,157 @@
+import type { ToolSpec, ToolUse, ToolResult } from './types';
+export type { ToolSpec } from './types';
+/**
+ * Context provided to tool implementations during execution.
+ * Contains framework-level state and information from the agent invocation.
+ *
+ * @typeParam T - Optional type for strongly typing invocationState. Callers can pass any object
+ *               as invocationState (including references), but it must be a dictionary/object.
+ *               T allows strong typing when desired, while Record\<string, unknown\> accepts any object.
+ *
+ * @example
+ * ```typescript
+ * interface MyState {
+ *   userId: string
+ *   sessionId: string
+ * }
+ *
+ * const context: ToolContext<MyState> = {
+ *   invocationState: {
+ *     userId: 'user-123',
+ *     sessionId: 'session-456'
+ *   }
+ * }
+ * ```
+ */
+export interface ToolContext<T extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * The tool use request that triggered this tool execution.
+     * Contains the tool name, toolUseId, and input parameters.
+     */
+    toolUse: ToolUse;
+    /**
+     * Caller-provided state from agent invocation.
+     * This allows passing context from the agent level down to tool execution.
+     */
+    invocationState: T;
+}
+/**
+ * Event yielded during tool execution to report streaming progress.
+ * Tools can yield zero or more of these events before returning the final ToolResult.
+ *
+ * @example
+ * ```typescript
+ * const streamEvent: ToolStreamEvent = {
+ *   type: 'toolStreamEvent',
+ *   data: 'Processing step 1...'
+ * }
+ *
+ * // Or with structured data
+ * const streamEvent: ToolStreamEvent = {
+ *   type: 'toolStreamEvent',
+ *   data: { progress: 50, message: 'Halfway complete' }
+ * }
+ * ```
+ */
+export interface ToolStreamEvent {
+    /**
+     * Discriminator for tool stream events.
+     */
+    type: 'toolStreamEvent';
+    /**
+     * Caller-provided data for the progress update.
+     * Can be any type of data the tool wants to report.
+     */
+    data?: unknown;
+}
+/**
+ * Type alias for the async generator returned by tool stream methods.
+ * Yields ToolStreamEvents during execution and returns a ToolResult.
+ */
+export type ToolStreamGenerator = AsyncGenerator<ToolStreamEvent, ToolResult, never>;
+/**
+ * Interface for tool implementations.
+ * Tools are used by agents to interact with their environment and perform specific actions.
+ *
+ * The Tool interface provides a streaming execution model where tools can yield
+ * progress events during execution before returning a final result.
+ *
+ * Most implementations should use FunctionTool rather than implementing this interface directly.
+ */
+export interface Tool {
+    /**
+     * The unique name of the tool.
+     * This MUST match the name in the toolSpec.
+     */
+    toolName: string;
+    /**
+     * Human-readable description of what the tool does.
+     * This helps the model understand when to use the tool.
+     *
+     * This MUST match the description in the toolSpec.description.
+     */
+    description: string;
+    /**
+     * OpenAPI JSON specification for the tool.
+     * Defines the tool's name, description, and input schema.
+     */
+    toolSpec: ToolSpec;
+    /**
+     * Executes the tool with streaming support.
+     * Yields zero or more ToolStreamEvents during execution, then returns
+     * exactly one ToolResult as the final value.
+     *
+     * @param toolContext - Context information including the tool use request and invocation state
+     * @returns Async generator that yields ToolStreamEvents and returns a ToolResult
+     *
+     * @example
+     * ```typescript
+     * const context = {
+     *   toolUse: {
+     *     name: 'calculator',
+     *     toolUseId: 'calc-123',
+     *     input: { operation: 'add', a: 5, b: 3 }
+     *   },
+     *   invocationState: {}
+     * }
+     *
+     * // The return value is only accessible via explicit .next() calls
+     * const generator = tool.stream(context)
+     * for await (const event of generator) {
+     *   // Only yields are captured here
+     *   console.log('Progress:', event.data)
+     * }
+     * // Or manually handle the return value:
+     * let result = await generator.next()
+     * while (!result.done) {
+     *   console.log('Progress:', result.value.data)
+     *   result = await generator.next()
+     * }
+     * console.log('Final result:', result.value.status)
+     * ```
+     */
+    stream(toolContext: ToolContext): ToolStreamGenerator;
+}
+/**
+ * Extended tool interface that supports direct invocation with type-safe input and output.
+ * This interface is useful for testing and standalone tool execution.
+ *
+ * @typeParam TInput - Type for the tool's input parameters
+ * @typeParam TReturn - Type for the tool's return value
+ */
+export interface InvokableTool<TInput, TReturn> extends Tool {
+    /**
+     * Invokes the tool directly with type-safe input and returns the unwrapped result.
+     *
+     * Unlike stream(), this method:
+     * - Returns the raw result (not wrapped in ToolResult)
+     * - Consumes async generators and returns only the final value
+     * - Lets errors throw naturally (not wrapped in error ToolResult)
+     *
+     * @param input - The input parameters for the tool
+     * @param context - Optional tool execution context
+     * @returns The unwrapped result
+     */
+    invoke(input: TInput, context?: ToolContext): Promise<TReturn>;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/tools/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/tools/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAE5D,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtF;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,eAAe,EAAE,CAAC,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,iBAAiB,CAAA;IAEvB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC,eAAe,EAAE,UAAU,EAAE,KAAK,CAAC,CAAA;AAEpF;;;;;;;;GAQG;AACH,MAAM,WAAW,IAAI;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,QAAQ,EAAE,QAAQ,CAAA;IAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB,CAAA;CACtD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,EAAE,OAAO,CAAE,SAAQ,IAAI;IAC1D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/D"}

package/dist/tools/tool.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool.js.map

package/dist/tools/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/tools/tool.ts"],"names":[],"mappings":""}

package/dist/tools/types.d.ts

@@ -0,0 +1,119 @@
+import type { JSONSchema, JSONValue } from '../types/json';
+/**
+ * Result of a tool execution.
+ * Contains the outcome and any data returned by the tool.
+ */
+export interface ToolResult {
+    /**
+     * The ID of the tool use that this result corresponds to.
+     */
+    toolUseId: string;
+    /**
+     * Status indicating success or error.
+     */
+    status: ToolResultStatus;
+    /**
+     * Array of content blocks containing the tool's output.
+     */
+    content: ToolResultContent[];
+    /**
+     * The original error object when status is 'error'.
+     * Available for inspection by hooks, error handlers, and event loop.
+     * Tools must wrap non-Error thrown values into Error objects.
+     */
+    error?: Error;
+}
+/**
+ * Status of a tool execution.
+ * Indicates whether the tool executed successfully or encountered an error.
+ */
+export type ToolResultStatus = 'success' | 'error';
+/**
+ * Content returned from a tool execution.
+ * Can be either text or structured JSON data.
+ *
+ * This is a discriminated union where the `type` field determines the content format.
+ */
+export type ToolResultContent = ToolResultTextContent | ToolResultJsonContent;
+/**
+ * Text content returned from a tool execution.
+ */
+export interface ToolResultTextContent {
+    /**
+     * Discriminator for text content.
+     */
+    type: 'toolResultTextContent';
+    /**
+     * Plain text result from the tool.
+     */
+    text: string;
+}
+/**
+ * JSON content returned from a tool execution.
+ */
+export interface ToolResultJsonContent {
+    /**
+     * Discriminator for JSON content.
+     */
+    type: 'toolResultJsonContent';
+    /**
+     * Structured JSON result from the tool.
+     */
+    json: JSONValue;
+}
+/**
+ * Specification for a tool that can be used by the model.
+ * Defines the tool's name, description, and input schema.
+ */
+export interface ToolSpec {
+    /**
+     * The unique name of the tool.
+     */
+    name: string;
+    /**
+     * A description of what the tool does.
+     * This helps the model understand when to use the tool.
+     */
+    description: string;
+    /**
+     * JSON Schema defining the expected input structure for the tool.
+     */
+    inputSchema: JSONSchema;
+}
+/**
+ * Represents a tool usage request from the model.
+ * The model generates this when it wants to use a tool.
+ */
+export interface ToolUse {
+    /**
+     * The name of the tool to execute.
+     */
+    name: string;
+    /**
+     * Unique identifier for this tool use instance.
+     * Used to match tool results back to their requests.
+     */
+    toolUseId: string;
+    /**
+     * The input parameters for the tool.
+     * Must be JSON-serializable.
+     */
+    input: JSONValue;
+}
+/**
+ * Specifies how the model should choose which tool to use.
+ *
+ * - `{ auto: {} }` - Let the model decide whether to use a tool
+ * - `{ any: {} }` - Force the model to use one of the available tools
+ * - `{ tool: { name: 'toolName' } }` - Force the model to use a specific tool
+ */
+export type ToolChoice = {
+    auto: Record<string, never>;
+} | {
+    any: Record<string, never>;
+} | {
+    tool: {
+        name: string;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE1D;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;OAEG;IACH,MAAM,EAAE,gBAAgB,CAAA;IAExB;;OAEG;IACH,OAAO,EAAE,iBAAiB,EAAE,CAAA;IAE5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAA;AAElD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,GAAG,qBAAqB,CAAA;AAE7E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,IAAI,EAAE,uBAAuB,CAAA;IAE7B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,IAAI,EAAE,uBAAuB,CAAA;IAE7B;;OAEG;IACH,IAAI,EAAE,SAAS,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,WAAW,EAAE,UAAU,CAAA;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAA;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA"}

package/dist/tools/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":""}