@agentick/core 0.0.1

package/dist/tool/tool.d.ts

@@ -0,0 +1,403 @@
+/**
+ * Tool Creation
+ *
+ * createTool() returns a ToolClass that can be:
+ * 1. Passed directly to models: engine.execute({ tools: [MyTool] })
+ * 2. Run directly: await MyTool.run(input)
+ * 3. Used in JSX: <MyTool />
+ *
+ * Core tool types (ToolMetadata, ToolDefinition, ExecutableTool, etc.)
+ * are defined in types.ts to keep them centralized.
+ */
+import React from "react";
+import type { ExtractArgs, Middleware, Procedure } from "@agentick/kernel";
+import type { ProviderToolOptions, LibraryToolOptions } from "../types";
+import { ToolExecutionType, ToolIntent, type ClientToolDefinition, type ToolDefinition as BaseToolDefinition } from "@agentick/shared/tools";
+import type { ContentBlock } from "@agentick/shared/blocks";
+import { type RecoveryAction, type TickState } from "../component/component";
+import type { TickResult } from "../hooks/types";
+import type { COM } from "../com/object-model";
+import type { COMInput } from "../com/types";
+import type { JSX } from "../jsx/jsx-runtime";
+import type { ComponentBaseProps } from "../jsx/jsx-types";
+import type { CompiledStructure } from "../compiler/types";
+export { ToolIntent, ToolExecutionType, type ToolCall, type ToolResult, type ToolConfirmationResult, } from "@agentick/shared/tools";
+export type { ToolConfirmationResponse } from "@agentick/shared";
+export type { BaseToolDefinition, ClientToolDefinition };
+/**
+ * Version-agnostic Zod schema type.
+ * Allows different Zod versions to work together without "excessively deep" errors.
+ */
+export interface ZodSchema<T = unknown> {
+    parse: (data: unknown) => T;
+    safeParse: (data: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: unknown;
+    };
+    _output: T;
+}
+/**
+ * Tool handler function signature.
+ * Takes typed input and an optional COM for accessing agent state.
+ *
+ * When called during agent execution (model calls the tool), `ctx` is provided.
+ * When called directly via `MyTool.run(input)`, `ctx` is undefined.
+ */
+export type ToolHandler<TInput = any, TOutput extends ContentBlock[] = ContentBlock[]> = (input: TInput, ctx?: COM) => TOutput | Promise<TOutput>;
+/**
+ * Options for createTool().
+ *
+ * Mirrors ToolMetadata but with additional creation-time options
+ * (handler, middleware, component lifecycle hooks).
+ */
+export interface CreateToolOptions<TInput = any, TOutput extends ContentBlock[] = ContentBlock[]> {
+    /** Tool name (used by model to call the tool) */
+    name: string;
+    /** Description shown to the model */
+    description: string;
+    /** Zod schema for input validation */
+    input: ZodSchema<TInput>;
+    /**
+     * Optional Zod schema for output validation.
+     * Used for type-safe tool composition, workflow orchestration,
+     * and runtime validation of handler return values.
+     */
+    output?: ZodSchema<TOutput>;
+    /**
+     * Handler function that executes the tool.
+     * Receives typed input and an optional COM for accessing agent state.
+     *
+     * When called during agent execution, `ctx` is provided so the handler
+     * can set state, publish to channels, read context, etc.
+     * When called directly via `MyTool.run(input)`, `ctx` is undefined.
+     *
+     * Optional for CLIENT and PROVIDER tools (no server-side execution).
+     *
+     * @example
+     * ```typescript
+     * handler: async (input, ctx) => {
+     *   const result = doSomething(input);
+     *   ctx?.setState("lastResult", result);
+     *   return [{ type: "text", text: JSON.stringify(result) }];
+     * }
+     * ```
+     */
+    handler?: ToolHandler<TInput, TOutput>;
+    /**
+     * Execution type (SERVER, CLIENT, MCP, PROVIDER).
+     * Default: SERVER
+     */
+    type?: ToolExecutionType;
+    /**
+     * Tool intent (RENDER, ACTION, COMPUTE).
+     * Helps clients decide how to handle/render tool calls.
+     * Default: COMPUTE
+     */
+    intent?: ToolIntent;
+    /**
+     * Whether execution should wait for client response.
+     * Only applicable for CLIENT type tools.
+     * - true: Server pauses until tool_result received (e.g., forms)
+     * - false: Server continues with defaultResult (e.g., charts)
+     * Default: false
+     */
+    requiresResponse?: boolean;
+    /**
+     * Timeout in ms when waiting for client response.
+     * Only applicable when requiresResponse is true.
+     * Default: 30000
+     */
+    timeout?: number;
+    /**
+     * Default result when requiresResponse is false.
+     * Returned immediately for render tools.
+     * Default: [{ type: 'text', text: '[{name} rendered on client]' }]
+     */
+    defaultResult?: ContentBlock[];
+    /**
+     * Whether execution requires user confirmation before running.
+     * Applies to any tool type (SERVER, CLIENT, MCP).
+     *
+     * - boolean: Always require (true) or never require (false)
+     * - function: Conditional - receives input, returns whether confirmation needed.
+     *   Can be async to check persisted "always allow" state.
+     *   Use Context.get() inside the function to access execution context.
+     *
+     * Default: false
+     *
+     * @example
+     * ```typescript
+     * // Always require confirmation
+     * requiresConfirmation: true,
+     *
+     * // Conditional - check persisted preferences
+     * requiresConfirmation: async (input) => {
+     *   const ctx = context();
+     *   const prefs = await getPrefs(ctx.user?.id);
+     *   return !prefs.alwaysAllow.includes('my_tool');
+     * },
+     * ```
+     */
+    requiresConfirmation?: boolean | ((input: TInput) => boolean | Promise<boolean>);
+    /**
+     * Message to show user when requesting confirmation.
+     * Can be a string or a function that receives the input.
+     * Default: "Allow {tool_name} to execute?"
+     *
+     * @example
+     * ```typescript
+     * confirmationMessage: (input) => `Delete file "${input.path}"?`,
+     * ```
+     */
+    confirmationMessage?: string | ((input: TInput) => string);
+    /**
+     * Provider-specific tool options.
+     * Keyed by provider name (openai, google, anthropic, etc.).
+     * Used by adapters when converting tools.
+     */
+    providerOptions?: ProviderToolOptions;
+    /**
+     * MCP server configuration (for MCP tools).
+     */
+    mcpConfig?: {
+        serverUrl?: string;
+        serverName?: string;
+        transport?: "stdio" | "sse" | "websocket";
+        [key: string]: any;
+    };
+    /** Middleware applied to handler execution */
+    middleware?: Middleware[];
+    onMount?: (ctx: COM) => void | Promise<void>;
+    onUnmount?: (ctx: COM) => void | Promise<void>;
+    onStart?: (ctx: COM) => void | Promise<void>;
+    onTickStart?: (tickState: TickState, ctx: COM) => void | Promise<void>;
+    onTickEnd?: (result: TickResult, ctx: COM) => void | Promise<void>;
+    onComplete?: (finalState: COMInput, ctx: COM) => void | Promise<void>;
+    onError?: (tickState: TickState, ctx: COM) => RecoveryAction | void;
+    render?: (tickState: TickState, ctx: COM) => JSX.Element | null;
+    onAfterCompile?: (compiled: CompiledStructure, ctx: COM) => void | Promise<void>;
+}
+/**
+ * A ToolClass is both:
+ * - An ExecutableTool (via static metadata/run) - can be passed to models
+ * - A functional component - can be used in JSX
+ *
+ * This enables the three usage patterns:
+ * - engine.execute({ tools: [MyTool] })  -- passes static metadata/run
+ * - await MyTool.run(input)              -- calls static run procedure
+ * - <MyTool />                           -- renders component that registers tool
+ */
+export interface ToolClass<TInput = any> {
+    /** Tool metadata (static property) */
+    metadata: ToolMetadata<TInput>;
+    /** Run procedure (static property). Undefined for client-only tools. */
+    run?: Procedure<ToolHandler<TInput>>;
+    /** Functional component that registers the tool on mount */
+    (props?: ComponentBaseProps): React.ReactElement | null;
+}
+/**
+ * ToolClass with run guaranteed to be defined (when handler is provided).
+ */
+export interface RunnableToolClass<TInput = any> extends ToolClass<TInput> {
+    run: Procedure<ToolHandler<TInput>>;
+}
+/**
+ * Creates a tool that can be passed to models, run directly, or used in JSX.
+ *
+ * The returned class has static `metadata` and `run` properties making it
+ * a valid ExecutableTool, while also being instantiable as a Component.
+ *
+ * @example
+ * ```typescript
+ * const Calculator = createTool({
+ *   name: 'calculator',
+ *   description: 'Performs mathematical calculations',
+ *   input: z.object({
+ *     expression: z.string().describe('Math expression to evaluate')
+ *   }),
+ *   handler: async ({ expression }) => {
+ *     const result = eval(expression);
+ *     return [{ type: 'text', text: String(result) }];
+ *   },
+ * });
+ *
+ * // Pattern 1: Pass to model
+ * engine.execute({
+ *   messages: [...],
+ *   tools: [Calculator],
+ * });
+ *
+ * // Pattern 2: Run directly
+ * const result = await Calculator.run({ expression: '2 + 2' });
+ *
+ * // Pattern 3: Use in JSX (registers tool when component mounts)
+ * function MyAgent() {
+ *   return (
+ *     <>
+ *       <Calculator />
+ *       <Model />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example Client tool (no handler)
+ * ```typescript
+ * const RenderChart = createTool({
+ *   name: 'render_chart',
+ *   description: 'Renders a chart in the UI',
+ *   input: z.object({
+ *     type: z.enum(['line', 'bar', 'pie']),
+ *     data: z.array(z.object({ label: z.string(), value: z.number() })),
+ *   }),
+ *   type: ToolExecutionType.CLIENT,
+ *   intent: ToolIntent.RENDER,
+ *   requiresResponse: false,
+ *   defaultResult: [{ type: 'text', text: '[Chart rendered]' }],
+ * });
+ * ```
+ */
+export declare function createTool<TInput = any, TOutput extends ContentBlock[] = ContentBlock[]>(options: CreateToolOptions<TInput, TOutput> & {
+    handler: ToolHandler<TInput>;
+}): RunnableToolClass<TInput>;
+export declare function createTool<TInput = any, TOutput extends ContentBlock[] = ContentBlock[]>(options: CreateToolOptions<TInput, TOutput> & {
+    handler?: undefined;
+}): ToolClass<TInput>;
+/**
+ * Tool definition in provider-compatible format (JSON Schema).
+ * This is what gets passed to model adapters.
+ *
+ * Extends the base ToolDefinition from @agentick/shared with backend-specific fields.
+ */
+export interface ToolDefinition extends BaseToolDefinition {
+    /**
+     * Provider-specific tool configurations.
+     * Keyed by provider name (e.g., 'openai', 'google', 'anthropic').
+     * Adapters will use their provider-specific config when converting tools.
+     * Each adapter can extend this type using module augmentation.
+     */
+    providerOptions?: ProviderToolOptions;
+    /**
+     * Library-specific tool configurations.
+     * Keyed by library name (e.g., 'ai-sdk', 'langchain', 'llamaindex').
+     * Used by adapters for library-specific tool behavior (timeouts, callbacks, etc.).
+     * Each adapter can extend this type using module augmentation.
+     */
+    libraryOptions?: LibraryToolOptions;
+    /**
+     * MCP-specific configuration (only relevant if type === 'mcp').
+     * Contains connection info and MCP server details.
+     */
+    mcpConfig?: {
+        serverUrl?: string;
+        serverName?: string;
+        transport?: "stdio" | "sse" | "websocket";
+        [key: string]: any;
+    };
+}
+export interface ToolMetadata<TInput = any, TOutput = any> {
+    name: string;
+    description: string;
+    input: ZodSchema<TInput>;
+    /**
+     * Optional Zod schema for output validation.
+     * Used for type-safe tool composition and workflow orchestration.
+     */
+    output?: ZodSchema<TOutput>;
+    /**
+     * Tool execution type. Determines how the tool is executed.
+     * Default: SERVER (engine executes tool.run on server).
+     */
+    type?: ToolExecutionType;
+    /**
+     * Tool intent describes what the tool does (render, action, compute).
+     * Used by clients to determine how to render/handle tool calls.
+     * Default: COMPUTE
+     */
+    intent?: ToolIntent;
+    /**
+     * Whether execution should wait for client response.
+     * Only applicable for CLIENT type tools.
+     * - true: Server pauses and waits for tool_result from client (e.g., forms)
+     * - false: Server continues immediately with defaultResult (e.g., charts)
+     * Default: false
+     */
+    requiresResponse?: boolean;
+    /**
+     * Timeout in milliseconds when waiting for client response.
+     * Only applicable when requiresResponse is true.
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Default result to use when requiresResponse is false.
+     * Returned immediately for render tools that don't need client feedback.
+     * Default: [{ type: 'text', text: '[{tool_name} rendered on client]' }]
+     */
+    defaultResult?: ContentBlock[];
+    /**
+     * Whether execution requires user confirmation before running.
+     * Applies to any tool type (SERVER, CLIENT, MCP).
+     *
+     * - boolean: Always require (true) or never require (false)
+     * - function: Conditional - receives input, returns whether confirmation needed.
+     *   Can be async to check persisted "always allow" state.
+     *   Use Context.get() inside the function to access execution context.
+     *
+     * Default: false
+     */
+    requiresConfirmation?: boolean | ((input: any) => boolean | Promise<boolean>);
+    /**
+     * Message to show user when requesting confirmation.
+     * Can be a string or a function that receives the input.
+     * Default: "Allow {tool_name} to execute?"
+     */
+    confirmationMessage?: string | ((input: any) => string);
+    /**
+     * Provider-specific tool configurations.
+     * Keyed by provider name (e.g., 'openai', 'google', 'anthropic').
+     * Preserved when converting to ToolDefinition.
+     * Each adapter can extend this type using module augmentation.
+     */
+    providerOptions?: ProviderToolOptions;
+    /**
+     * Library-specific tool configurations.
+     * Keyed by library name (e.g., 'ai-sdk', 'langchain', 'llamaindex').
+     * Used by adapters for library-specific tool behavior (timeouts, callbacks, etc.).
+     * Each adapter can extend this type using module augmentation.
+     */
+    libraryOptions?: LibraryToolOptions;
+    /**
+     * MCP-specific configuration (only relevant if type === 'mcp').
+     * Contains connection info and MCP server details.
+     */
+    mcpConfig?: {
+        serverUrl?: string;
+        serverName?: string;
+        transport?: "stdio" | "sse" | "websocket";
+        [key: string]: any;
+    };
+}
+export interface ExecutableTool<THandler extends (input: any, ctx?: COM) => ContentBlock[] | Promise<ContentBlock[]> = (input: any, ctx?: COM) => ContentBlock[] | Promise<ContentBlock[]>> {
+    metadata: ToolMetadata<ExtractArgs<THandler>[0]>;
+    run?: Procedure<THandler>;
+}
+/**
+ * Convert ClientToolDefinition to ToolDefinition for engine use.
+ */
+export declare function clientToolToDefinition(clientTool: ClientToolDefinition): ToolDefinition;
+/**
+ * Type guard: checks if a value is a ToolClass.
+ */
+export declare function isToolClass(value: any): value is ToolClass;
+/**
+ * Extract ExecutableTool from a ToolClass.
+ * Useful when you need just the metadata/run without the component.
+ */
+export declare function toExecutableTool(toolClass: ToolClass): ExecutableTool;
+/**
+ * Check if value implements ExecutableTool interface.
+ */
+export declare function isExecutableTool(value: any): value is ExecutableTool;
+//# sourceMappingURL=tool.d.ts.map

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

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

package/dist/tool/tool.js

@@ -0,0 +1,176 @@
+/**
+ * Tool Creation
+ *
+ * createTool() returns a ToolClass that can be:
+ * 1. Passed directly to models: engine.execute({ tools: [MyTool] })
+ * 2. Run directly: await MyTool.run(input)
+ * 3. Used in JSX: <MyTool />
+ *
+ * Core tool types (ToolMetadata, ToolDefinition, ExecutableTool, etc.)
+ * are defined in types.ts to keep them centralized.
+ */
+import React, { useEffect, useRef } from "react";
+import { createEngineProcedure, isProcedure } from "../procedure";
+import { ToolExecutionType, ToolIntent, } from "@agentick/shared/tools";
+import {} from "../component/component";
+import { useCom, useTickState, useOnTickStart, useOnTickEnd, useAfterCompile } from "../hooks";
+// Re-export for convenience
+export { ToolIntent, ToolExecutionType, } from "@agentick/shared/tools";
+// Implementation
+export function createTool(options) {
+    // Build metadata from options
+    const metadata = {
+        name: options.name,
+        description: options.description,
+        input: options.input,
+        output: options.output,
+        type: options.type,
+        intent: options.intent,
+        requiresResponse: options.requiresResponse,
+        timeout: options.timeout,
+        defaultResult: options.defaultResult,
+        requiresConfirmation: options.requiresConfirmation,
+        confirmationMessage: options.confirmationMessage,
+        providerOptions: options.providerOptions,
+        mcpConfig: options.mcpConfig,
+    };
+    // Create run procedure if handler is provided
+    const run = options.handler
+        ? isProcedure(options.handler)
+            ? options.handler
+            : createEngineProcedure({
+                name: "tool:run", // Low cardinality span name
+                metadata: {
+                    type: "tool",
+                    toolName: options.name,
+                    id: options.name,
+                    operation: "run",
+                },
+                middleware: options.middleware || [],
+                // Execution boundary: tool runs are child executions of the model call
+                executionBoundary: "child",
+                executionType: "tool",
+            }, options.handler)
+        : undefined;
+    // Create functional component with static tool properties
+    // Using a functional component instead of a class ensures compatibility
+    // with React's reconciler (class components must extend React.Component)
+    const ToolComponent = function ToolComponent(_props) {
+        const ctx = useCom();
+        // Note: useTickState returns hooks/types.ts TickState, but lifecycle callbacks
+        // expect component/component.ts TickState. They're compatible at runtime,
+        // so we use type assertion. The hooks version is a simplified subset.
+        const tickState = useTickState();
+        // Track lifecycle callbacks (should only fire once per component lifecycle)
+        const hasCalledMountRef = useRef(false);
+        // Call onMount/onStart lifecycle hooks once
+        useEffect(() => {
+            if (!hasCalledMountRef.current) {
+                hasCalledMountRef.current = true;
+                if (options.onMount) {
+                    Promise.resolve(options.onMount(ctx)).catch(console.error);
+                }
+                if (options.onStart) {
+                    Promise.resolve(options.onStart(ctx)).catch(console.error);
+                }
+            }
+            return () => {
+                if (options.onUnmount) {
+                    Promise.resolve(options.onUnmount(ctx)).catch(console.error);
+                }
+            };
+        }, [ctx]);
+        // Tick lifecycle hooks - data first, ctx last
+        if (options.onTickStart) {
+            useOnTickStart((hookTickState, hookCtx) => {
+                if (options.onTickStart) {
+                    Promise.resolve(options.onTickStart(hookTickState, hookCtx)).catch(console.error);
+                }
+            });
+        }
+        if (options.onTickEnd) {
+            useOnTickEnd((result, hookCtx) => {
+                if (options.onTickEnd) {
+                    Promise.resolve(options.onTickEnd(result, hookCtx)).catch(console.error);
+                }
+            });
+        }
+        if (options.onAfterCompile) {
+            useAfterCompile((compiled, hookCtx) => {
+                if (options.onAfterCompile) {
+                    Promise.resolve(options.onAfterCompile(compiled, hookCtx)).catch(console.error);
+                }
+            });
+        }
+        // Render a <tool> element for the collector to find
+        // This is the declarative approach - tools are collected from the tree
+        const toolElement = React.createElement("tool", {
+            name: metadata.name,
+            description: metadata.description,
+            schema: metadata.input,
+            handler: run,
+            // Include full metadata for advanced use cases
+            metadata,
+        });
+        // If custom render provided, wrap both tool element and render output
+        if (options.render) {
+            const renderOutput = options.render(tickState, ctx);
+            return React.createElement(React.Fragment, null, toolElement, renderOutput);
+        }
+        return toolElement;
+    };
+    // Attach static properties to make it a valid ToolClass
+    ToolComponent.metadata = metadata;
+    ToolComponent.run = run;
+    return ToolComponent;
+}
+// ClientToolDefinition is now exported from '@agentick/shared'
+/**
+ * Convert ClientToolDefinition to ToolDefinition for engine use.
+ */
+export function clientToolToDefinition(clientTool) {
+    return {
+        name: clientTool.name,
+        description: clientTool.description,
+        input: clientTool.input,
+        output: clientTool.output,
+        type: ToolExecutionType.CLIENT,
+        intent: clientTool.intent ?? ToolIntent.RENDER,
+        requiresResponse: clientTool.requiresResponse ?? false,
+        timeout: clientTool.timeout ?? 30000,
+        defaultResult: clientTool.defaultResult ?? [
+            { type: "text", text: `[${clientTool.name} rendered on client]` },
+        ],
+    };
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+/**
+ * Type guard: checks if a value is a ToolClass.
+ */
+export function isToolClass(value) {
+    return value && typeof value === "function" && "metadata" in value && value.metadata?.name;
+}
+/**
+ * Extract ExecutableTool from a ToolClass.
+ * Useful when you need just the metadata/run without the component.
+ */
+export function toExecutableTool(toolClass) {
+    return {
+        metadata: toolClass.metadata,
+        run: toolClass.run,
+    };
+}
+/**
+ * Check if value implements ExecutableTool interface.
+ */
+export function isExecutableTool(value) {
+    return (value &&
+        typeof value === "object" &&
+        "metadata" in value &&
+        value.metadata?.name &&
+        value.metadata?.description &&
+        value.metadata?.input);
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool/tool.js.map

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