@yourgpt/copilot-sdk 0.1.0 → 0.1.1

package/dist/tools-eeJ5iEC4.d.cts

@@ -0,0 +1,595 @@
+/**
+ * Tool-related types for the agentic loop
+ */
+/**
+ * Supported AI providers for tool calling
+ */
+type AIProvider = "anthropic" | "openai" | "xai" | "grok" | "gemini" | "groq" | "ollama";
+/**
+ * Where the tool executes
+ */
+type ToolLocation = "server" | "client";
+/**
+ * JSON Schema property definition
+ */
+interface JSONSchemaProperty {
+    type: "string" | "number" | "boolean" | "object" | "array" | "integer" | "null";
+    description?: string;
+    enum?: (string | number | boolean)[];
+    items?: JSONSchemaProperty;
+    properties?: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    default?: unknown;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+}
+/**
+ * JSON Schema for tool input
+ */
+interface ToolInputSchema {
+    type: "object";
+    properties: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+/**
+ * Tool execution context
+ *
+ * Provides runtime information to tool handlers including cancellation signals,
+ * request metadata, and custom context data.
+ */
+interface ToolContext {
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Thread ID if using threads */
+    threadId?: string;
+    /** Custom context data passed from runtime config */
+    data?: Record<string, unknown>;
+    /**
+     * Unique ID for this specific tool call.
+     * Useful for logging, tracing, and correlating tool executions.
+     */
+    toolCallId?: string;
+    /**
+     * Request headers (for auth in server tools).
+     * Contains headers from the original HTTP request.
+     *
+     * @example
+     * ```typescript
+     * handler: async (params, context) => {
+     *   const token = context?.headers?.authorization;
+     *   if (!token) return failure('Authentication required');
+     *   // ...
+     * }
+     * ```
+     */
+    headers?: Record<string, string>;
+    /**
+     * Full request metadata for server-side tools.
+     * Provides access to HTTP method, URL, and headers.
+     *
+     * @example
+     * ```typescript
+     * handler: async (params, context) => {
+     *   console.log(`Tool called from: ${context?.request?.url}`);
+     *   // Forward auth to internal service
+     *   const authHeader = context?.request?.headers?.authorization;
+     * }
+     * ```
+     */
+    request?: {
+        /** HTTP method (GET, POST, etc.) */
+        method?: string;
+        /** Request URL path */
+        url?: string;
+        /** Request headers */
+        headers?: Record<string, string>;
+    };
+    /**
+     * Data passed from user's approval action.
+     * Only present when tool has `needsApproval: true` and user approved with extra data.
+     *
+     * @example
+     * ```typescript
+     * // In render function:
+     * approval.onApprove({ supervisor: selectedSupervisor });
+     *
+     * // In handler:
+     * handler: async (params, context) => {
+     *   const supervisor = context?.approvalData?.supervisor;
+     *   await assignToSupervisor(params.ticketId, supervisor);
+     * }
+     * ```
+     */
+    approvalData?: Record<string, unknown>;
+}
+/**
+ * AI response behavior for tool results.
+ *
+ * Controls what the AI sees after a tool executes and renders UI.
+ *
+ * - `'none'`: AI generates minimal response, UI component handles display
+ * - `'brief'`: AI gets summary context (via aiContext), gives brief acknowledgment
+ * - `'full'`: AI receives full data and responds accordingly (default)
+ */
+type AIResponseMode = "none" | "brief" | "full";
+/**
+ * Multimodal content for AI to analyze
+ */
+type AIContent = {
+    type: "image";
+    data: string;
+    mediaType: string;
+} | {
+    type: "text";
+    text: string;
+};
+/**
+ * Tool response format
+ */
+interface ToolResponse<T = unknown> {
+    /** Whether the tool succeeded */
+    success: boolean;
+    /** Human-readable message */
+    message?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Result data */
+    data?: T;
+    /**
+     * Override AI context for this specific result.
+     * Takes precedence over tool-level aiContext config.
+     * If set, this message is sent to AI instead of full result data.
+     *
+     * @example
+     * ```typescript
+     * return {
+     *   success: true,
+     *   data: sensitiveData,
+     *   _aiContext: '[Data retrieved - contains sensitive info, displayed to user]'
+     * };
+     * ```
+     */
+    _aiContext?: string;
+    /**
+     * Override AI response mode for this specific result.
+     * Takes precedence over tool-level aiResponseMode config.
+     */
+    _aiResponseMode?: AIResponseMode;
+    /**
+     * Content for AI to analyze (images, documents, etc.).
+     * When present, these are included as multimodal content for AI analysis.
+     *
+     * @example
+     * ```typescript
+     * // Screenshot for AI to analyze
+     * return {
+     *   success: true,
+     *   message: 'Screenshot captured',
+     *   _aiContent: [{ type: 'image', data: base64, mediaType: 'image/png' }]
+     * };
+     * ```
+     */
+    _aiContent?: AIContent[];
+}
+/**
+ * Approval callbacks passed to render when tool requires user action.
+ * Only present when status is "approval-required".
+ */
+interface ToolApprovalCallbacks {
+    /**
+     * Approve execution and optionally pass extra data to the handler.
+     * The extraData is available in handler via `context.approvalData`.
+     *
+     * @example
+     * ```tsx
+     * // Simple approval
+     * approval.onApprove();
+     *
+     * // Approval with data (e.g., user selection)
+     * approval.onApprove({ supervisor: { name: "John", role: "Manager" } });
+     * ```
+     */
+    onApprove: (extraData?: Record<string, unknown>) => void;
+    /**
+     * Reject the tool execution with optional reason.
+     * This stops the tool from executing and returns an error to AI.
+     */
+    onReject: (reason?: string) => void;
+    /** Custom message from tool's approvalMessage config */
+    message?: string;
+}
+/**
+ * Props passed to tool render function.
+ *
+ * The render function is called for every status change, enabling
+ * full lifecycle rendering similar to Vercel AI SDK.
+ *
+ * @example
+ * ```tsx
+ * render: ({ status, args, approval, result }) => {
+ *   if (status === "approval-required" && approval) {
+ *     return <ApprovalCard onConfirm={() => approval.onApprove()} />;
+ *   }
+ *   if (status === "executing") {
+ *     return <LoadingSkeleton />;
+ *   }
+ *   if (status === "completed") {
+ *     return <ResultCard data={result.data} />;
+ *   }
+ *   return null;
+ * }
+ * ```
+ */
+interface ToolRenderProps<TParams = Record<string, unknown>> {
+    /**
+     * Current execution status:
+     * - `pending`: Tool call received, waiting to start
+     * - `approval-required`: Waiting for user approval (when needsApproval is set)
+     * - `executing`: Handler is running
+     * - `completed`: Handler finished successfully
+     * - `error`: Handler failed
+     */
+    status: "pending" | "approval-required" | "executing" | "completed" | "error";
+    /** Arguments passed to the tool */
+    args: TParams;
+    /** Result if completed */
+    result?: ToolResponse;
+    /** Error if failed */
+    error?: string;
+    /** Tool call ID */
+    toolCallId: string;
+    /** Tool name */
+    toolName: string;
+    /**
+     * Approval callbacks - only present when status is "approval-required".
+     * Use these to create custom approval UIs that can pass extra data to the handler.
+     */
+    approval?: ToolApprovalCallbacks;
+}
+/**
+ * Tool definition with JSON Schema
+ */
+interface ToolDefinition<TParams = Record<string, unknown>> {
+    /** Unique tool name */
+    name: string;
+    /** Tool description for LLM */
+    description: string;
+    /** Where the tool executes (server or client) */
+    location: ToolLocation;
+    /**
+     * Human-readable title for UI display.
+     * Can be a static string or a function that generates title from args.
+     *
+     * @example
+     * ```typescript
+     * title: "Get order details"
+     * // or dynamic:
+     * title: (args) => `Order #${args.orderId}`
+     * ```
+     */
+    title?: string | ((args: TParams) => string);
+    /**
+     * Title shown while executing (present tense with "...").
+     * If not provided, uses `title` with "..." appended.
+     *
+     * @example
+     * ```typescript
+     * executingTitle: (args) => `Fetching order #${args.orderId}...`
+     * ```
+     */
+    executingTitle?: string | ((args: TParams) => string);
+    /**
+     * Title shown after completion.
+     * If not provided, defaults to `title`.
+     *
+     * @example
+     * ```typescript
+     * completedTitle: (args) => `Retrieved order #${args.orderId}`
+     * ```
+     */
+    completedTitle?: string | ((args: TParams) => string);
+    /** JSON Schema for input parameters */
+    inputSchema: ToolInputSchema;
+    /** Handler function (optional for client tools registered on server) */
+    handler?: (params: TParams, context?: ToolContext) => Promise<ToolResponse> | ToolResponse;
+    /** Optional render function for UI */
+    render?: (props: ToolRenderProps<TParams>) => unknown;
+    /** Whether the tool is available (for conditional registration) */
+    available?: boolean;
+    /**
+     * Require user approval before execution.
+     * Can be:
+     * - `true`: Always require approval
+     * - `false` or `undefined`: No approval needed (default)
+     * - `(params) => boolean`: Conditional approval based on input
+     *
+     * Similar to Vercel AI SDK v6's needsApproval pattern.
+     */
+    needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);
+    /**
+     * Custom message shown in the approval UI.
+     * Can be a string or a function that generates a message from params.
+     * If not provided, a default message with the tool name is shown.
+     */
+    approvalMessage?: string | ((params: TParams) => string);
+    /**
+     * How the AI should respond when this tool's result is rendered as UI.
+     *
+     * - `'none'`: AI generates minimal response ("[Result displayed to user]").
+     *   Use for tools where UI component fully handles the display (stats cards, etc.)
+     *
+     * - `'brief'`: AI receives summary context (from aiContext) and gives brief acknowledgment.
+     *   Use for charts/visualizations where AI should acknowledge but not repeat data.
+     *
+     * - `'full'`: AI receives complete data and responds accordingly (default).
+     *   Use for tools where AI should analyze and elaborate on results.
+     *
+     * @default 'full'
+     *
+     * @example
+     * ```typescript
+     * // Chart tool - AI acknowledges without repeating data
+     * const chartTool: ToolDefinition = {
+     *   name: 'get_chart',
+     *   aiResponseMode: 'brief',
+     *   aiContext: (result) => `[Chart displayed: ${result.data.title}]`,
+     *   handler: async () => ({ success: true, data: chartData })
+     * };
+     * ```
+     */
+    aiResponseMode?: AIResponseMode;
+    /**
+     * Context/summary sent to AI instead of (or along with) full result.
+     *
+     * Used when:
+     * - `aiResponseMode: 'brief'` - This becomes the only thing AI sees
+     * - `aiResponseMode: 'full'` - This is prepended to full data for context
+     *
+     * Can be:
+     * - `string`: Static message (e.g., "[Weather data displayed]")
+     * - `function`: Dynamic based on result (e.g., (result) => `[Chart: ${result.data.title}]`)
+     *
+     * @example
+     * ```typescript
+     * // Static context
+     * aiContext: '[Analytics chart displayed to user]'
+     *
+     * // Dynamic context based on result
+     * aiContext: (result, args) => {
+     *   const { title, currentValue } = result.data;
+     *   return `[Chart displayed: ${title}, showing ${currentValue}]`;
+     * }
+     * ```
+     */
+    aiContext?: string | ((result: ToolResponse, args: Record<string, unknown>) => string);
+}
+/**
+ * Unified tool call format (internal representation)
+ */
+interface UnifiedToolCall {
+    /** Unique tool call ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool input arguments */
+    input: Record<string, unknown>;
+}
+/**
+ * Unified tool result format
+ */
+interface UnifiedToolResult {
+    /** Tool call ID this result is for */
+    toolCallId: string;
+    /** Serialized result content (JSON string) */
+    content: string;
+    /** Whether the tool succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Tool execution status
+ */
+type ToolExecutionStatus = "pending" | "executing" | "completed" | "error";
+/**
+ * Tool approval status (for human-in-the-loop)
+ *
+ * Similar to Vercel AI SDK v6's tool approval pattern.
+ */
+type ToolApprovalStatus = "none" | "required" | "approved" | "rejected";
+/**
+ * Permission level for tool execution
+ *
+ * Controls whether approval is needed and how the choice is remembered:
+ * - "ask" - Always prompt user (default)
+ * - "allow_always" - Auto-approve, persisted to storage
+ * - "deny_always" - Auto-reject, persisted to storage
+ * - "session" - Auto-approve for current session only
+ */
+type PermissionLevel = "ask" | "allow_always" | "deny_always" | "session";
+/**
+ * Stored tool permission record
+ */
+interface ToolPermission {
+    /** Tool name (unique identifier) */
+    toolName: string;
+    /** Permission level */
+    level: PermissionLevel;
+    /** When permission was set */
+    createdAt: number;
+    /** Last time this permission was used */
+    lastUsedAt?: number;
+}
+/**
+ * Permission storage configuration
+ */
+interface PermissionStorageConfig {
+    /**
+     * Storage type:
+     * - "localStorage" - Persists across browser sessions
+     * - "sessionStorage" - Clears when tab closes
+     * - "memory" - In-memory only (for SSR or testing)
+     */
+    type: "localStorage" | "sessionStorage" | "memory";
+    /** Storage key prefix (default: "yourgpt-permissions") */
+    keyPrefix?: string;
+}
+/**
+ * Permission storage adapter interface (for custom implementations)
+ */
+interface PermissionStorageAdapter {
+    /** Get permission for a tool */
+    get(toolName: string): Promise<ToolPermission | null>;
+    /** Set permission for a tool */
+    set(permission: ToolPermission): Promise<void>;
+    /** Remove permission for a tool */
+    remove(toolName: string): Promise<void>;
+    /** Get all permissions */
+    getAll(): Promise<ToolPermission[]>;
+    /** Clear all permissions */
+    clear(): Promise<void>;
+}
+/**
+ * Tool execution record (for UI tracking)
+ */
+interface ToolExecution {
+    /** Tool call ID */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool arguments */
+    args: Record<string, unknown>;
+    /** Execution status */
+    status: ToolExecutionStatus;
+    /** Result if completed */
+    result?: ToolResponse;
+    /** Error message if failed */
+    error?: string;
+    /** Timestamp when execution started */
+    timestamp: number;
+    /** Duration in ms (set when completed) */
+    duration?: number;
+    /** Approval status for this execution */
+    approvalStatus: ToolApprovalStatus;
+    /** Message shown in approval UI (from tool's approvalMessage) */
+    approvalMessage?: string;
+    /** Timestamp when user responded to approval request */
+    approvalTimestamp?: number;
+}
+/**
+ * Agentic loop configuration
+ */
+interface AgentLoopConfig {
+    /** Maximum iterations before stopping (default: 20) */
+    maxIterations?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Whether to enable the agentic loop (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Agent loop state (for tracking)
+ */
+interface AgentLoopState {
+    /** Current iteration number */
+    iteration: number;
+    /** Maximum iterations allowed */
+    maxIterations: number;
+    /** Whether the loop is currently running */
+    running: boolean;
+    /** Whether max iterations was reached */
+    maxIterationsReached: boolean;
+    /** Whether the loop was aborted */
+    aborted: boolean;
+}
+/**
+ * A set of tools, keyed by tool name
+ *
+ * @example
+ * ```typescript
+ * const myTools: ToolSet = {
+ *   capture_screenshot: screenshotTool,
+ *   get_weather: weatherTool,
+ * };
+ * ```
+ */
+type ToolSet = Record<string, ToolDefinition>;
+/**
+ * Configuration for creating a tool
+ */
+interface ToolConfig<TParams = Record<string, unknown>> {
+    /** Tool description for LLM */
+    description: string;
+    /** Where the tool executes (default: 'client') */
+    location?: ToolLocation;
+    /** Human-readable title for UI display */
+    title?: string | ((args: TParams) => string);
+    /** Title shown while executing */
+    executingTitle?: string | ((args: TParams) => string);
+    /** Title shown after completion */
+    completedTitle?: string | ((args: TParams) => string);
+    /** JSON Schema for input parameters */
+    inputSchema?: ToolInputSchema;
+    /** Handler function */
+    handler?: (params: TParams, context?: ToolContext) => Promise<ToolResponse> | ToolResponse;
+    /** Optional render function for UI */
+    render?: (props: ToolRenderProps<TParams>) => unknown;
+    /** Whether the tool is available */
+    available?: boolean;
+    /** Require user approval before execution */
+    needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);
+    /** Custom message shown in the approval UI */
+    approvalMessage?: string | ((params: TParams) => string);
+    /** AI response mode for this tool (default: 'full') */
+    aiResponseMode?: AIResponseMode;
+    /** Context/summary sent to AI instead of full result */
+    aiContext?: string | ((result: ToolResponse, args: Record<string, unknown>) => string);
+}
+/**
+ * Create a tool definition (similar to Vercel AI SDK's tool())
+ *
+ * @example
+ * ```typescript
+ * const weatherTool = tool({
+ *   description: 'Get weather for a location',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       location: { type: 'string', description: 'City name' },
+ *     },
+ *     required: ['location'],
+ *   },
+ *   handler: async ({ location }) => {
+ *     const weather = await fetchWeather(location);
+ *     return success(weather);
+ *   },
+ * });
+ * ```
+ */
+declare function tool<TParams = Record<string, unknown>>(config: ToolConfig<TParams>): Omit<ToolDefinition<TParams>, "name">;
+/**
+ * Convert ToolDefinition to OpenAI tool format
+ */
+declare function toolToOpenAIFormat(tool: ToolDefinition): object;
+/**
+ * Convert ToolDefinition to Anthropic tool format
+ */
+declare function toolToAnthropicFormat(tool: ToolDefinition): object;
+/**
+ * Create a tool result response
+ */
+declare function createToolResult(toolCallId: string, response: ToolResponse): UnifiedToolResult;
+/**
+ * Create a successful tool response
+ */
+declare function success<T = unknown>(data?: T, message?: string): ToolResponse<T>;
+/**
+ * Create a failed tool response
+ */
+declare function failure(error: string): ToolResponse;
+
+export { type AIProvider as A, type JSONSchemaProperty as J, type PermissionLevel as P, type ToolDefinition as T, type UnifiedToolCall as U, type ToolExecutionStatus as a, type ToolResponse as b, type ToolInputSchema as c, type ToolLocation as d, type ToolContext as e, type ToolRenderProps as f, type ToolConfig as g, type ToolSet as h, type UnifiedToolResult as i, type ToolApprovalStatus as j, type ToolExecution as k, type AgentLoopConfig as l, type AgentLoopState as m, type AIResponseMode as n, type AIContent as o, type ToolPermission as p, type PermissionStorageConfig as q, type PermissionStorageAdapter as r, toolToOpenAIFormat as s, tool as t, toolToAnthropicFormat as u, createToolResult as v, success as w, failure as x };