toolwire 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+import { ZodType, ZodIssue } from 'zod';
+
+type JsonSchema = Record<string, unknown>;
+interface ToolConfig<TInput = unknown, TOutput = unknown> {
+    /** Unique name. 1–64 chars: letters, digits, underscores, hyphens. */
+    name: string;
+    /** Human description — explain when and how to call this tool. */
+    description: string;
+    /** Zod schema for input arguments. */
+    input: ZodType<TInput>;
+    /** Optional Zod schema for the return value. Validates handler output. */
+    output?: ZodType<TOutput>;
+    /** The implementation. Receives validated input and a ToolContext. */
+    handler: (input: TInput, context: ToolContext) => TOutput | Promise<TOutput>;
+    /** Timeout in milliseconds. Default: 30_000 */
+    timeout?: number;
+    /** Extra retry attempts on execution failure (not validation/timeout). Default: 0 */
+    retries?: number;
+    /** MCP-style behavioural hints (informational only — not enforced). */
+    annotations?: ToolAnnotations;
+    /**
+     * Override the auto-computed JSON Schema for the input.
+     * Useful when loading tools from remote manifests.
+     */
+    _jsonSchema?: JsonSchema;
+}
+interface ToolContext {
+    /** AbortSignal tied to the timeout. Handlers should honour this for cooperative cancellation. */
+    signal: AbortSignal;
+    /** Current attempt index (0 = first try, 1 = first retry, …). */
+    attempt: number;
+}
+interface ToolAnnotations {
+    /** Human-readable display title. */
+    title?: string;
+    /** Hint: tool only reads data, no side-effects. */
+    readOnly?: boolean;
+    /** Hint: tool modifies or deletes data. */
+    destructive?: boolean;
+    /** Hint: tool makes expensive external calls — consider caching. */
+    expensive?: boolean;
+    /** Hint: prompt user for confirmation before calling. */
+    requiresConfirmation?: boolean;
+    [key: string]: unknown;
+}
+interface ToolDefinition<TInput = unknown, TOutput = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly input: ZodType<TInput>;
+    readonly output: ZodType<TOutput> | undefined;
+    readonly handler: (input: TInput, context: ToolContext) => TOutput | Promise<TOutput>;
+    readonly timeout: number;
+    readonly retries: number;
+    readonly annotations: ToolAnnotations;
+    /** Pre-computed JSON Schema for the input. Used by provider adapters. */
+    readonly inputSchema: JsonSchema;
+    /** Pre-computed JSON Schema for the output, if an output schema was provided. */
+    readonly outputSchema: JsonSchema | undefined;
+}
+type ToolResult<T = unknown> = ToolSuccess<T> | ToolFailure;
+interface ToolSuccess<T = unknown> {
+    readonly success: true;
+    readonly data: T;
+    readonly toolName: string;
+    readonly durationMs: number;
+}
+interface ToolFailure {
+    readonly success: false;
+    readonly error: ToolError;
+    readonly toolName: string;
+    readonly durationMs: number;
+}
+type ToolErrorCode = 'VALIDATION_INPUT' | 'VALIDATION_OUTPUT' | 'EXECUTION' | 'TIMEOUT' | 'NOT_FOUND' | 'DISABLED';
+interface ToolError {
+    readonly code: ToolErrorCode;
+    /** Developer-readable message (suitable for logs). */
+    readonly message: string;
+    /** LLM-readable message formatted to help the model understand and retry. */
+    readonly llmMessage: string;
+    readonly toolName: string;
+    /** Whether the LLM should retry the call. */
+    readonly retryable: boolean;
+    /** Suggested wait before retrying (ms). */
+    readonly retryAfterMs?: number;
+    /** Full Zod issue list — only present for VALIDATION_* errors. */
+    readonly issues?: ReadonlyArray<ZodIssue>;
+    /** Original thrown value — only present for EXECUTION errors. */
+    readonly cause?: unknown;
+}
+interface Middleware {
+    /** Optional name for logging / debugging. */
+    name?: string;
+    /**
+     * Runs before execution, in registration order.
+     * Return a value to replace the tool arguments; return void/undefined to keep them.
+     */
+    beforeCall?: (toolName: string, args: unknown) => unknown | Promise<unknown> | void | Promise<void>;
+    /**
+     * Runs after a successful execution, in reverse registration order.
+     * Return a ToolSuccess to replace the result; return void/undefined to keep it.
+     */
+    afterCall?: (toolName: string, args: unknown, result: ToolSuccess) => ToolSuccess | Promise<ToolSuccess> | void | Promise<void>;
+    /**
+     * Runs on any failure (validation, execution, timeout, not-found, disabled).
+     * Return a ToolResult to recover from the error; return void/undefined to propagate the failure.
+     */
+    onError?: (toolName: string, args: unknown, failure: ToolFailure) => ToolResult | Promise<ToolResult> | void | Promise<void>;
+}
+interface ToolCallRequest {
+    /** Name of the tool to call. */
+    name: string;
+    /** Raw arguments from the LLM (validated against the input schema at runtime). */
+    arguments: unknown;
+}
+interface RegistryOptions {
+    /** Default timeout for tools that don't specify their own (ms). */
+    defaultTimeout?: number;
+}
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonSchema;
+        strict?: boolean;
+    };
+}
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: JsonSchema;
+}
+interface GeminiFunctionDeclaration {
+    name: string;
+    description: string;
+    parametersJsonSchema: JsonSchema;
+}
+interface GeminiToolConfig {
+    functionDeclarations: GeminiFunctionDeclaration[];
+}
+interface VercelAIToolDef {
+    description: string;
+    parameters: ZodType;
+}
+type VercelAIToolSet = Record<string, VercelAIToolDef>;
+interface ToolManifestEntry {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    endpoint: string;
+}
+interface ToolManifest {
+    version: '1.0';
+    tools: ToolManifestEntry[];
+}
+/** Extract the input type from a ToolDefinition. */
+type InferInput<T> = T extends ToolDefinition<infer I, unknown> ? I : never;
+/** Extract the output type from a ToolDefinition. */
+type InferOutput<T> = T extends ToolDefinition<unknown, infer O> ? O : never;
+
+/**
+ * Define a tool. Returns a frozen ToolDefinition with pre-computed JSON schemas.
+ *
+ * @example
+ * ```ts
+ * const search = tool({
+ *   name: 'search_web',
+ *   description: 'Search the web for current information',
+ *   input: z.object({ query: z.string().min(1) }),
+ *   handler: async ({ query }) => mySearchAPI(query),
+ *   timeout: 10_000,
+ * });
+ * ```
+ */
+declare function tool<TInput = unknown, TOutput = unknown>(config: ToolConfig<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
+
+type AnyTool = ToolDefinition<any, any>;
+declare class ToolRegistry {
+    private readonly tools;
+    private readonly disabledTools;
+    private readonly _middleware;
+    private readonly options;
+    constructor(tools?: AnyTool[], options?: RegistryOptions);
+    /** Add one or more tools. Returns `this` for chaining. */
+    register(tools: AnyTool | AnyTool[]): this;
+    /**
+     * Replace a registered tool in-place (hot-swap).
+     * Useful for swapping slow tools with cached versions mid-run.
+     */
+    swap(name: string, newTool: AnyTool): this;
+    /** Temporarily prevent a tool from being called. */
+    disable(name: string): this;
+    /** Re-enable a previously disabled tool. */
+    enable(name: string): this;
+    /** Add middleware. Returns `this` for chaining. */
+    use(middleware: Middleware | Middleware[]): this;
+    /** Return the names of all registered tools (including disabled ones). */
+    list(): string[];
+    /** Return a tool definition by name, or undefined if not found. */
+    get(name: string): AnyTool | undefined;
+    /**
+     * Return a human-readable list of enabled tools.
+     * Handy for injecting into a system prompt.
+     */
+    describe(): string;
+    /**
+     * Execute a tool call from an LLM.
+     * Always resolves (never throws) — check `result.success` to distinguish outcomes.
+     */
+    call(request: ToolCallRequest): Promise<ToolResult>;
+    /** Export tool schemas in OpenAI function-calling format. */
+    toOpenAI(options?: {
+        strict?: boolean;
+    }): OpenAITool[];
+    /** Export tool schemas in Anthropic tool-use format. */
+    toAnthropic(): AnthropicTool[];
+    /** Export tool schemas in Google Gemini format. */
+    toGemini(): GeminiToolConfig;
+    /** Export tool schemas in Vercel AI SDK format (passes Zod schemas directly). */
+    toVercelAI(): VercelAIToolSet;
+    /** Load tools from a directory of compiled JS/MJS files. */
+    static fromDir(dirPath: string): Promise<ToolRegistry>;
+    /** Load tools from a remote JSON manifest. */
+    static fromManifest(url: string): Promise<ToolRegistry>;
+    private enabledTools;
+}
+/** Convenience factory — same as `new ToolRegistry(tools, options)`. */
+declare function registry(tools?: AnyTool[], options?: RegistryOptions): ToolRegistry;
+
+/**
+ * Convert tool definitions to OpenAI function-calling format.
+ *
+ * @example
+ * ```ts
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   tools: reg.toOpenAI({ strict: true }),
+ *   messages,
+ * });
+ * ```
+ */
+declare function toOpenAI(tools: ToolDefinition<any, any>[], options?: {
+    strict?: boolean;
+}): OpenAITool[];
+
+/**
+ * Convert tool definitions to Anthropic tool-use format.
+ * Note: uses `input_schema` (not `parameters`).
+ *
+ * @example
+ * ```ts
+ * const response = await anthropic.messages.create({
+ *   model: 'claude-opus-4-6',
+ *   tools: reg.toAnthropic(),
+ *   messages,
+ * });
+ * ```
+ */
+declare function toAnthropic(tools: ToolDefinition<any, any>[]): AnthropicTool[];
+
+/**
+ * Convert tool definitions to Google Gemini format.
+ * Uses `parametersJsonSchema` (not `parameters`) and wraps in `functionDeclarations`.
+ *
+ * @example
+ * ```ts
+ * const response = await model.generateContent({
+ *   tools: [reg.toGemini()],
+ *   contents,
+ * });
+ * ```
+ */
+declare function toGemini(tools: ToolDefinition<any, any>[]): GeminiToolConfig;
+
+/**
+ * Convert tool definitions to Vercel AI SDK format.
+ * Unlike other adapters, this passes the original Zod schema directly
+ * (Vercel AI SDK handles JSON Schema conversion internally).
+ *
+ * @example
+ * ```ts
+ * const { text } = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools: reg.toVercelAI(),
+ *   prompt,
+ * });
+ * ```
+ */
+declare function toVercelAI(tools: ToolDefinition<any, any>[]): VercelAIToolSet;
+
+/**
+ * Load tools from a directory of compiled JavaScript files.
+ * Each file may export:
+ *   - `export default tool(...)` — a single tool as the default export
+ *   - `export const tools = [tool(...), ...]` — an array under the `tools` named export
+ *   - `export const myTool = tool(...)` — any named export that is a ToolDefinition
+ *
+ * Only `.js`, `.mjs`, and `.cjs` files are scanned.
+ * Files that fail to import are skipped with a warning.
+ */
+declare function fromDir(dirPath: string): Promise<ToolRegistry>;
+/**
+ * Load tools from a remote JSON manifest.
+ * The manifest must conform to the ToolManifest schema:
+ * ```json
+ * {
+ *   "version": "1.0",
+ *   "tools": [
+ *     { "name": "...", "description": "...", "inputSchema": {...}, "endpoint": "https://..." }
+ *   ]
+ * }
+ * ```
+ * Each tool is proxied as an HTTP POST to its `endpoint`.
+ */
+declare function fromManifest(url: string): Promise<ToolRegistry>;
+
+declare function makeNotFoundError(toolName: string, available: string[]): ToolError;
+declare function makeDisabledError(toolName: string): ToolError;
+declare function makeValidationInputError(toolName: string, issues: ZodIssue[]): ToolError;
+declare function makeValidationOutputError(toolName: string, issues: ZodIssue[]): ToolError;
+declare function makeTimeoutError(toolName: string, timeoutMs: number): ToolError;
+declare function makeExecutionError(toolName: string, cause: unknown, attempts: number): ToolError;
+declare function makeFailure(toolName: string, error: ToolError, durationMs: number): ToolFailure;
+
+export { type AnthropicTool, type GeminiFunctionDeclaration, type GeminiToolConfig, type InferInput, type InferOutput, type JsonSchema, type Middleware, type OpenAITool, type RegistryOptions, type ToolAnnotations, type ToolCallRequest, type ToolConfig, type ToolContext, type ToolDefinition, type ToolError, type ToolErrorCode, type ToolFailure, type ToolManifest, type ToolManifestEntry, ToolRegistry, type ToolResult, type ToolSuccess, type VercelAIToolDef, type VercelAIToolSet, fromDir, fromManifest, makeDisabledError, makeExecutionError, makeFailure, makeNotFoundError, makeTimeoutError, makeValidationInputError, makeValidationOutputError, registry, toAnthropic, toGemini, toOpenAI, toVercelAI, tool };