@strands-agents/sdk 0.0.1

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

@@ -0,0 +1,188 @@
+import { createErrorResult, Tool } from './tool.js';
+import { ToolStreamEvent } from './tool.js';
+import { deepCopy } from '../types/json.js';
+import { JsonBlock, TextBlock, ToolResultBlock } from '../types/messages.js';
+/**
+ * A Tool implementation that wraps a callback function and handles all ToolResultBlock conversion.
+ *
+ * FunctionTool allows creating tools from existing functions without needing to manually
+ * handle ToolResultBlock 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 ToolResultBlock, and errors are caught and
+ * returned as error ToolResultBlocks.
+ *
+ * @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 extends Tool {
+    /**
+     * The unique name of the tool.
+     */
+    name;
+    /**
+     * 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) {
+        super();
+        this.name = 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 ToolResultBlock.
+     *
+     * @param toolContext - Context information including the tool use request and invocation state
+     * @returns Async generator that yields ToolStreamEvents and returns a ToolResultBlock
+     */
+    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 ToolResultBlock
+                const generator = result;
+                // Iterate through all yielded values
+                let iterResult = await generator.next();
+                while (!iterResult.done) {
+                    // Each yielded value becomes a ToolStreamEvent
+                    yield new ToolStreamEvent({
+                        data: iterResult.value,
+                    });
+                    iterResult = await generator.next();
+                }
+                // The generator's return value (when done = true) is wrapped in ToolResultBlock
+                return this._wrapInToolResult(iterResult.value, toolUse.toolUseId);
+            }
+            else if (result instanceof Promise) {
+                // Handle promise: await and wrap in ToolResultBlock
+                const value = await result;
+                return this._wrapInToolResult(value, toolUse.toolUseId);
+            }
+            else {
+                // Handle synchronous value: wrap in ToolResultBlock
+                return this._wrapInToolResult(result, toolUse.toolUseId);
+            }
+        }
+        catch (error) {
+            // Handle any errors and yield as error ToolResultBlock
+            return createErrorResult(error, toolUse.toolUseId);
+        }
+    }
+    /**
+     * Wraps a value in a ToolResultBlock with success status.
+     *
+     * Due to AWS Bedrock limitations (only accepts objects as JSON content), the following
+     * rules are applied:
+     * - Strings → TextBlock
+     * - Numbers, Booleans → TextBlock (converted to string)
+     * - null, undefined → TextBlock (special string representation)
+     * - Objects → JsonBlock (with deep copy)
+     * - Arrays → JsonBlock 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 ToolResultBlock
+     * @returns A ToolResultBlock containing the value
+     */
+    _wrapInToolResult(value, toolUseId) {
+        try {
+            // Handle null with special string representation as text content
+            if (value === null) {
+                return new ToolResultBlock({
+                    toolUseId,
+                    status: 'success',
+                    content: [new TextBlock('<null>')],
+                });
+            }
+            // Handle undefined with special string representation as text content
+            if (value === undefined) {
+                return new ToolResultBlock({
+                    toolUseId,
+                    status: 'success',
+                    content: [new TextBlock('<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 new ToolResultBlock({
+                    toolUseId,
+                    status: 'success',
+                    content: [new TextBlock(String(value))],
+                });
+            }
+            // Handle arrays by wrapping in object { $value: array }
+            if (Array.isArray(value)) {
+                const copiedValue = deepCopy(value);
+                return new ToolResultBlock({
+                    toolUseId,
+                    status: 'success',
+                    content: [new JsonBlock({ json: { $value: copiedValue } })],
+                });
+            }
+            // Handle objects as JSON content with deep copy
+            const copiedValue = deepCopy(value);
+            return new ToolResultBlock({
+                toolUseId,
+                status: 'success',
+                content: [new JsonBlock({ json: copiedValue })],
+            });
+        }
+        catch (error) {
+            // If deep copy fails (circular references, non-serializable values), return error result
+            return createErrorResult(error, toolUseId);
+        }
+    }
+}
+//# sourceMappingURL=function-tool.js.map

package/dist/src/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/src/tools/mcp-tool.d.ts

@@ -0,0 +1,36 @@
+import { Tool, type ToolContext, type ToolStreamGenerator } from './tool.js';
+import type { ToolSpec } from './types.js';
+import type { JSONSchema } from '../types/json.js';
+import type { McpClient } from '../mcp.js';
+export interface McpToolConfig {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+    client: McpClient;
+}
+/**
+ * A Tool implementation that proxies calls to a remote MCP server.
+ *
+ * Unlike FunctionTool, which wraps local logic, McpTool delegates execution
+ * to the connected McpClient and translates the SDK's response format
+ * directly into ToolResultBlocks.
+ */
+export declare class McpTool extends Tool {
+    readonly name: string;
+    readonly description: string;
+    readonly toolSpec: ToolSpec;
+    private readonly mcpClient;
+    constructor(config: McpToolConfig);
+    stream(toolContext: ToolContext): ToolStreamGenerator;
+    /**
+     * Type Guard: Checks if value matches the expected MCP SDK result shape.
+     * \{ content: unknown[]; isError?: boolean \}
+     */
+    private _isMcpToolResult;
+    /**
+     * Type Guard: Checks if an item is a Text content block.
+     * \{ type: 'text'; text: string \}
+     */
+    private _isMcpTextContent;
+}
+//# sourceMappingURL=mcp-tool.d.ts.map

package/dist/src/tools/mcp-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAA;AAE7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,UAAU,CAAA;IACvB,MAAM,EAAE,SAAS,CAAA;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,OAAQ,SAAQ,IAAI;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;gBAEzB,MAAM,EAAE,aAAa;IAa1B,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB;IAiC5D;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAS1B"}

package/dist/src/tools/mcp-tool.js

@@ -0,0 +1,78 @@
+import { createErrorResult, Tool } from './tool.js';
+import { JsonBlock, TextBlock, ToolResultBlock } from '../types/messages.js';
+/**
+ * A Tool implementation that proxies calls to a remote MCP server.
+ *
+ * Unlike FunctionTool, which wraps local logic, McpTool delegates execution
+ * to the connected McpClient and translates the SDK's response format
+ * directly into ToolResultBlocks.
+ */
+export class McpTool extends Tool {
+    name;
+    description;
+    toolSpec;
+    mcpClient;
+    constructor(config) {
+        super();
+        this.name = config.name;
+        this.description = config.description;
+        this.toolSpec = {
+            name: config.name,
+            description: config.description,
+            inputSchema: config.inputSchema,
+        };
+        this.mcpClient = config.client;
+    }
+    // eslint-disable-next-line require-yield
+    async *stream(toolContext) {
+        const { toolUseId, input } = toolContext.toolUse;
+        try {
+            // Input is validated by MCP Client before invocation
+            const rawResult = await this.mcpClient.callTool(this, input);
+            if (!this._isMcpToolResult(rawResult)) {
+                throw new Error('Invalid tool result from MCP Client: missing content array');
+            }
+            const content = rawResult.content.map((item) => {
+                if (this._isMcpTextContent(item)) {
+                    return new TextBlock(item.text);
+                }
+                return new JsonBlock({ json: item });
+            });
+            if (content.length === 0) {
+                content.push(new TextBlock('Tool execution completed successfully with no output.'));
+            }
+            return new ToolResultBlock({
+                toolUseId,
+                status: rawResult.isError ? 'error' : 'success',
+                content,
+            });
+        }
+        catch (error) {
+            return createErrorResult(error, toolUseId);
+        }
+    }
+    /**
+     * Type Guard: Checks if value matches the expected MCP SDK result shape.
+     * \{ content: unknown[]; isError?: boolean \}
+     */
+    _isMcpToolResult(value) {
+        if (typeof value !== 'object' || value === null) {
+            return false;
+        }
+        // Safe cast to generic record to check properties
+        const record = value;
+        return Array.isArray(record.content);
+    }
+    /**
+     * Type Guard: Checks if an item is a Text content block.
+     * \{ type: 'text'; text: string \}
+     */
+    _isMcpTextContent(value) {
+        if (typeof value !== 'object' || value === null) {
+            return false;
+        }
+        const record = value;
+        return record.type === 'text' && typeof record.text === 'string';
+    }
+}
+//# sourceMappingURL=mcp-tool.js.map

package/dist/src/tools/mcp-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool.js","sourceRoot":"","sources":["../../../src/tools/mcp-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAA8C,MAAM,WAAW,CAAA;AAG/F,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAU5E;;;;;;GAMG;AACH,MAAM,OAAO,OAAQ,SAAQ,IAAI;IACtB,IAAI,CAAQ;IACZ,WAAW,CAAQ;IACnB,QAAQ,CAAU;IACV,SAAS,CAAW;IAErC,YAAY,MAAqB;QAC/B,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAA;QACvB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAA;QACrC,IAAI,CAAC,QAAQ,GAAG;YACd,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,CAAA;QACD,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,CAAA;IAChC,CAAC;IAED,yCAAyC;IACzC,KAAK,CAAC,CAAC,MAAM,CAAC,WAAwB;QACpC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,WAAW,CAAC,OAAO,CAAA;QAEhD,IAAI,CAAC;YACH,qDAAqD;YACrD,MAAM,SAAS,GAAY,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAkB,CAAC,CAAA;YAElF,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC;gBACtC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAA;YAC/E,CAAC;YAED,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE;gBACtD,IAAI,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;oBACjC,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACjC,CAAC;gBAED,OAAO,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,IAAiB,EAAE,CAAC,CAAA;YACnD,CAAC,CAAC,CAAA;YAEF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,uDAAuD,CAAC,CAAC,CAAA;YACtF,CAAC;YAED,OAAO,IAAI,eAAe,CAAC;gBACzB,SAAS;gBACT,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;gBAC/C,OAAO;aACR,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;QAC5C,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,gBAAgB,CAAC,KAAc;QACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,kDAAkD;QAClD,MAAM,MAAM,GAAG,KAAgC,CAAA;QAE/C,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACtC,CAAC;IAED;;;OAGG;IACK,iBAAiB,CAAC,KAAc;QACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,MAAM,MAAM,GAAG,KAAgC,CAAA;QAE/C,OAAO,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAA;IAClE,CAAC;CACF"}

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

@@ -0,0 +1,167 @@
+import type { ToolSpec, ToolUse } from './types.js';
+import { ToolResultBlock } from '../types/messages.js';
+import type { AgentData } from '../types/agent.js';
+export type { ToolSpec } from './types.js';
+/**
+ * Context provided to tool implementations during execution.
+ * Contains framework-level state and information from the agent invocation.
+ */
+export interface ToolContext {
+    /**
+     * The tool use request that triggered this tool execution.
+     * Contains the tool name, toolUseId, and input parameters.
+     */
+    toolUse: ToolUse;
+    /**
+     * The agent instance that is executing this tool.
+     * Provides access to agent state and other agent-level information.
+     */
+    agent: AgentData;
+}
+/**
+ * Data for a tool stream event.
+ */
+export interface ToolStreamEventData {
+    /**
+     * 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;
+}
+/**
+ * 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 = new ToolStreamEvent({
+ *   data: 'Processing step 1...'
+ * })
+ *
+ * // Or with structured data
+ * const streamEvent = new ToolStreamEvent({
+ *   data: { progress: 50, message: 'Halfway complete' }
+ * })
+ * ```
+ */
+export declare class ToolStreamEvent implements ToolStreamEventData {
+    /**
+     * Discriminator for tool stream events.
+     */
+    readonly type: "toolStreamEvent";
+    /**
+     * Caller-provided data for the progress update.
+     * Can be any type of data the tool wants to report.
+     */
+    readonly data?: unknown;
+    constructor(eventData: {
+        data?: unknown;
+    });
+}
+/**
+ * Type alias for the async generator returned by tool stream methods.
+ * Yields ToolStreamEvents during execution and returns a ToolResultBlock.
+ */
+export type ToolStreamGenerator = AsyncGenerator<ToolStreamEvent, ToolResultBlock, undefined>;
+/**
+ * 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 declare abstract class Tool {
+    /**
+     * The unique name of the tool.
+     * This MUST match the name in the toolSpec.
+     */
+    abstract name: 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.
+     */
+    abstract description: string;
+    /**
+     * OpenAPI JSON specification for the tool.
+     * Defines the tool's name, description, and input schema.
+     */
+    abstract toolSpec: ToolSpec;
+    /**
+     * Executes the tool with streaming support.
+     * Yields zero or more ToolStreamEvents during execution, then returns
+     * exactly one ToolResultBlock 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 ToolResultBlock
+     *
+     * @example
+     * ```typescript
+     * const context = {
+     *   toolUse: {
+     *     name: 'calculator',
+     *     toolUseId: 'calc-123',
+     *     input: { operation: 'add', a: 5, b: 3 }
+     *   },
+     * }
+     *
+     * // 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)
+     * ```
+     */
+    abstract 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>;
+}
+/**
+ * Creates an error ToolResultBlock from an error object.
+ * Ensures all errors are normalized to Error objects and includes the original error
+ * in the ToolResultBlock 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 ToolResultBlock
+ * @returns A ToolResultBlock with error status, error message content, and original error object
+ */
+export declare function createErrorResult(error: unknown, toolUseId: string): ToolResultBlock;
+//# sourceMappingURL=tool.d.ts.map

package/dist/src/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,MAAM,YAAY,CAAA;AACnD,OAAO,EAAa,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAGlD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,IAAI,EAAE,iBAAiB,CAAA;IAEvB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAgB,YAAW,mBAAmB;IACzD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAS;IAE1C;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;gBAEX,SAAS,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE;CAK1C;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC,eAAe,EAAE,eAAe,EAAE,SAAS,CAAC,CAAA;AAE7F;;;;;;;;GAQG;AACH,8BAAsB,IAAI;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB;CAC/D;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;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAUpF"}

package/dist/src/tools/tool.js

@@ -0,0 +1,68 @@
+import { TextBlock, ToolResultBlock } from '../types/messages.js';
+import { normalizeError } from '../errors.js';
+/**
+ * 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 = new ToolStreamEvent({
+ *   data: 'Processing step 1...'
+ * })
+ *
+ * // Or with structured data
+ * const streamEvent = new ToolStreamEvent({
+ *   data: { progress: 50, message: 'Halfway complete' }
+ * })
+ * ```
+ */
+export class 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;
+    constructor(eventData) {
+        if (eventData.data !== undefined) {
+            this.data = eventData.data;
+        }
+    }
+}
+/**
+ * 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 class Tool {
+}
+/**
+ * Creates an error ToolResultBlock from an error object.
+ * Ensures all errors are normalized to Error objects and includes the original error
+ * in the ToolResultBlock 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 ToolResultBlock
+ * @returns A ToolResultBlock with error status, error message content, and original error object
+ */
+export function createErrorResult(error, toolUseId) {
+    // Ensure error is an Error object (wrap non-Error values)
+    const errorObject = normalizeError(error);
+    return new ToolResultBlock({
+        toolUseId,
+        status: 'error',
+        content: [new TextBlock(`Error: ${errorObject.message}`)],
+        error: errorObject,
+    });
+}
+//# sourceMappingURL=tool.js.map

package/dist/src/tools/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../../src/tools/tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAsC7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAC1B;;OAEG;IACM,IAAI,GAAG,iBAA0B,CAAA;IAE1C;;;OAGG;IACM,IAAI,CAAU;IAEvB,YAAY,SAA6B;QACvC,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAA;QAC5B,CAAC;IACH,CAAC;CACF;AAQD;;;;;;;;GAQG;AACH,MAAM,OAAgB,IAAI;CAqDzB;AAyBD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,SAAiB;IACjE,0DAA0D;IAC1D,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IAEzC,OAAO,IAAI,eAAe,CAAC;QACzB,SAAS;QACT,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,UAAU,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QACzD,KAAK,EAAE,WAAW;KACnB,CAAC,CAAA;AACJ,CAAC"}

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

@@ -0,0 +1,62 @@
+import type { JSONSchema, JSONValue } from '../types/json.js';
+/**
+ * Status of a tool execution.
+ * Indicates whether the tool executed successfully or encountered an error.
+ */
+export type ToolResultStatus = 'success' | 'error';
+/**
+ * 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: 'name' } }` - 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/src/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,kBAAkB,CAAA;AAE7D;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAA;AAElD;;;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/src/tools/types.js

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

package/dist/src/tools/types.js.map

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