@yourgpt/copilot-sdk 2.1.5-alpha.0 → 2.1.5-alpha.2

package/dist/{chunk-4QXY2PBG.js → chunk-3AONOZLY.js}

@@ -69,5 +69,5 @@ function failure(error) {
 }
 
 export { createToolResult, failure, success, tool, toolToAnthropicFormat, toolToOpenAIFormat };
-//# sourceMappingURL=chunk-4QXY2PBG.js.map
-//# sourceMappingURL=chunk-4QXY2PBG.js.map
+//# sourceMappingURL=chunk-3AONOZLY.js.map
+//# sourceMappingURL=chunk-3AONOZLY.js.map

package/dist/{chunk-4QXY2PBG.js.map → chunk-3AONOZLY.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/types/tools.ts"],"names":["tool"],"mappings":";AAw8BO,SAAS,KACd,MAAA,EACuC;AACvC,EAAA,OAAO;AAAA,IACL,aAAa,MAAA,CAAO,WAAA;AAAA,IACpB,QAAA,EAAU,OAAO,QAAA,IAAY,QAAA;AAAA,IAC7B,UAAU,MAAA,CAAO,QAAA;AAAA,IACjB,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,cAAc,MAAA,CAAO,YAAA;AAAA,IACrB,UAAU,MAAA,CAAO,QAAA;AAAA,IACjB,gBAAgB,MAAA,CAAO,cAAA;AAAA,IACvB,cAAc,MAAA,CAAO,YAAA;AAAA;AAAA,IAErB,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,gBAAgB,MAAA,CAAO,cAAA;AAAA,IACvB,gBAAgB,MAAA,CAAO,cAAA;AAAA;AAAA,IAEvB,WAAA,EAAa,OAAO,WAAA,IAAe;AAAA,MACjC,IAAA,EAAM,QAAA;AAAA,MACN,YAAY,EAAC;AAAA,MACb,UAAU;AAAC,KACb;AAAA,IACA,SAAS,MAAA,CAAO,OAAA;AAAA,IAChB,QAAQ,MAAA,CAAO,MAAA;AAAA,IACf,WAAW,MAAA,CAAO,SAAA;AAAA,IAClB,QAAQ,MAAA,CAAO,MAAA;AAAA,IACf,eAAe,MAAA,CAAO,aAAA;AAAA,IACtB,iBAAiB,MAAA,CAAO,eAAA;AAAA,IACxB,gBAAgB,MAAA,CAAO,cAAA;AAAA,IACvB,WAAW,MAAA,CAAO;AAAA,GACpB;AACF;AASO,SAAS,mBAAmBA,KAAAA,EAA8B;AAC/D,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,UAAA;AAAA,IACN,QAAA,EAAU;AAAA,MACR,MAAMA,KAAAA,CAAK,IAAA;AAAA,MACX,aAAaA,KAAAA,CAAK,WAAA;AAAA,MAClB,YAAYA,KAAAA,CAAK;AAAA;AACnB,GACF;AACF;AAKO,SAAS,sBAAsBA,KAAAA,EAA8B;AAClE,EAAA,OAAO;AAAA,IACL,MAAMA,KAAAA,CAAK,IAAA;AAAA,IACX,aAAaA,KAAAA,CAAK,WAAA;AAAA,IAClB,cAAcA,KAAAA,CAAK;AAAA,GACrB;AACF;AAKO,SAAS,gBAAA,CACd,YACA,QAAA,EACmB;AACnB,EAAA,OAAO;AAAA,IACL,UAAA;AAAA,IACA,OAAA,EAAS,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAA;AAAA,IAChC,SAAS,QAAA,CAAS,OAAA;AAAA,IAClB,OAAO,QAAA,CAAS;AAAA,GAClB;AACF;AAKO,SAAS,OAAA,CACd,MACA,OAAA,EACiB;AACjB,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,IAAA;AAAA,IACT,IAAA;AAAA,IACA;AAAA,GACF;AACF;AAKO,SAAS,QAAQ,KAAA,EAA6B;AACnD,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,KAAA;AAAA,IACT;AAAA,GACF;AACF","file":"chunk-4QXY2PBG.js","sourcesContent":["/**\n * Tool-related types for the agentic loop\n */\n\nimport type { ActionRenderProps } from \"./actions\";\n\n// ============================================\n// Provider Types\n// ============================================\n\n/**\n * Supported AI providers for tool calling\n */\nexport type AIProvider =\n  | \"anthropic\"\n  | \"openai\"\n  | \"xai\"\n  | \"grok\"\n  | \"gemini\"\n  | \"groq\"\n  | \"ollama\";\n\n/**\n * Where the tool executes\n */\nexport type ToolLocation = \"server\" | \"client\";\n\n/**\n * Source/origin of the tool\n * - \"mcp\": Tool from an MCP (Model Context Protocol) server\n * - \"native\": Built-in SDK tool\n * - \"custom\": User-defined tool\n */\nexport type ToolSource = \"mcp\" | \"native\" | \"custom\";\n\n// ============================================\n// Tool Definition Types\n// ============================================\n\n/**\n * JSON Schema property definition\n */\nexport interface JSONSchemaProperty {\n  type:\n    | \"string\"\n    | \"number\"\n    | \"boolean\"\n    | \"object\"\n    | \"array\"\n    | \"integer\"\n    | \"null\";\n  description?: string;\n  enum?: (string | number | boolean)[];\n  items?: JSONSchemaProperty;\n  properties?: Record<string, JSONSchemaProperty>;\n  required?: string[];\n  default?: unknown;\n  minLength?: number;\n  maxLength?: number;\n  minimum?: number;\n  maximum?: number;\n  pattern?: string;\n}\n\n/**\n * JSON Schema for tool input\n */\nexport interface ToolInputSchema {\n  type: \"object\";\n  properties: Record<string, JSONSchemaProperty>;\n  required?: string[];\n  additionalProperties?: boolean;\n}\n\n/**\n * Tool execution context\n *\n * Provides runtime information to tool handlers including cancellation signals,\n * request metadata, and custom context data.\n */\nexport interface ToolContext {\n  /** Abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Thread ID if using threads */\n  threadId?: string;\n  /** Custom context data passed from runtime config */\n  data?: Record<string, unknown>;\n\n  // ============================================\n  // Rich Context (Vercel AI SDK pattern)\n  // ============================================\n\n  /**\n   * Unique ID for this specific tool call.\n   * Useful for logging, tracing, and correlating tool executions.\n   */\n  toolCallId?: string;\n\n  /**\n   * Request headers (for auth in server tools).\n   * Contains headers from the original HTTP request.\n   *\n   * @example\n   * ```typescript\n   * handler: async (params, context) => {\n   *   const token = context?.headers?.authorization;\n   *   if (!token) return failure('Authentication required');\n   *   // ...\n   * }\n   * ```\n   */\n  headers?: Record<string, string>;\n\n  /**\n   * Full request metadata for server-side tools.\n   * Provides access to HTTP method, URL, and headers.\n   *\n   * @example\n   * ```typescript\n   * handler: async (params, context) => {\n   *   console.log(`Tool called from: ${context?.request?.url}`);\n   *   // Forward auth to internal service\n   *   const authHeader = context?.request?.headers?.authorization;\n   * }\n   * ```\n   */\n  request?: {\n    /** HTTP method (GET, POST, etc.) */\n    method?: string;\n    /** Request URL path */\n    url?: string;\n    /** Request headers */\n    headers?: Record<string, string>;\n  };\n\n  /**\n   * Data passed from user's approval action.\n   * Only present when tool has `needsApproval: true` and user approved with extra data.\n   *\n   * @example\n   * ```typescript\n   * // In render function:\n   * approval.onApprove({ supervisor: selectedSupervisor });\n   *\n   * // In handler:\n   * handler: async (params, context) => {\n   *   const supervisor = context?.approvalData?.supervisor;\n   *   await assignToSupervisor(params.ticketId, supervisor);\n   * }\n   * ```\n   */\n  approvalData?: Record<string, unknown>;\n}\n\n// ============================================\n// AI Response Control Types\n// ============================================\n\n/**\n * AI response behavior for tool results.\n *\n * Controls what the AI sees after a tool executes and renders UI.\n *\n * - `'none'`: AI generates minimal response, UI component handles display\n * - `'brief'`: AI gets summary context (via aiContext), gives brief acknowledgment\n * - `'full'`: AI receives full data and responds accordingly (default)\n */\nexport type AIResponseMode = \"none\" | \"brief\" | \"full\";\n\n/**\n * Multimodal content for AI to analyze\n */\nexport type AIContent =\n  | { type: \"image\"; data: string; mediaType: string }\n  | { type: \"text\"; text: string };\n\n/**\n * How large tool results should be trimmed before they are sent back to the AI.\n */\nexport type ToolTruncationStrategy = \"head\" | \"head-tail\" | \"smart\";\n\n/**\n * Truncation controls for tool results.\n */\nexport interface ToolResultTruncationConfig {\n  enabled?: boolean;\n  maxContextShare?: number;\n  hardMaxChars?: number;\n  minKeepChars?: number;\n  strategy?: ToolTruncationStrategy;\n  preserveErrors?: boolean;\n}\n\n/**\n * Global or per-tool controls for how tool results are represented in prompts.\n */\nexport interface ToolResultConfig {\n  truncation?: ToolResultTruncationConfig;\n}\n\n/**\n * Named tool profile for selective loading.\n */\nexport interface ToolProfile {\n  name: string;\n  description?: string;\n  include?: string[];\n  exclude?: string[];\n}\n\n/**\n * Tool profile configuration.\n */\nexport interface ToolProfileConfig {\n  enabled?: boolean;\n  defaultProfile?: string;\n  profiles?: Record<string, ToolProfile>;\n  /** When false, active profiles exclude tools that do not declare profile membership. */\n  includeUnprofiled?: boolean;\n  dynamicSelection?: {\n    enabled?: boolean;\n    maxTools?: number;\n  };\n}\n\n/**\n * History compaction behavior for long-running sessions.\n */\nexport interface ContextHistoryConfig {\n  maxMessages?: number;\n  maxTokens?: number;\n  maxContextShare?: number;\n  pruneStrategy?: \"oldest\" | \"least-relevant\" | \"summarize\";\n}\n\n/**\n * Optional summarization controls used during history compaction.\n */\nexport interface ContextSummarizationConfig {\n  enabled?: boolean;\n  triggerAt?: number;\n  chunkSize?: number;\n  preserveRecent?: number;\n  fallbackBehavior?: \"truncate\" | \"statistical\" | \"error\";\n}\n\n/**\n * Token estimation controls.\n */\nexport interface TokenEstimationConfig {\n  safetyMargin?: number;\n  charsPerToken?: number;\n}\n\n/**\n * Conversation context management.\n */\nexport interface ContextManagementConfig {\n  enabled?: boolean;\n  history?: ContextHistoryConfig;\n  summarization?: ContextSummarizationConfig;\n  tokenEstimation?: TokenEstimationConfig;\n}\n\n/**\n * One budget bucket in the prompt context.\n */\nexport interface ContextUsagePart {\n  tokens: number;\n  percent: number;\n}\n\n/**\n * Prompt context usage snapshot.\n */\nexport interface ContextUsage {\n  total: ContextUsagePart;\n  breakdown: {\n    systemPrompt: ContextUsagePart;\n    history: ContextUsagePart;\n    toolResults: ContextUsagePart;\n    tools: ContextUsagePart;\n  };\n  budget: {\n    available: number;\n    remaining: number;\n  };\n  warnings: string[];\n}\n\n/**\n * Real-time context budget configuration.\n */\nexport interface ContextBudgetConfig {\n  enabled?: boolean;\n  budget?: {\n    contextWindowTokens?: number;\n    inputHeadroomRatio?: number;\n    systemPromptShare?: number;\n    historyShare?: number;\n    toolResultsShare?: number;\n    toolDefinitionsShare?: number;\n  };\n  enforcement?: {\n    mode?: \"warn\" | \"truncate\" | \"error\";\n    onBudgetExceeded?: (info: ContextUsage) => void;\n  };\n  monitoring?: {\n    enabled?: boolean;\n    onUsageUpdate?: (usage: ContextUsage) => void;\n  };\n}\n\n/**\n * Framework-agnostic optimization controls for tool-heavy chat sessions.\n */\nexport interface ToolOptimizationConfig {\n  toolProfiles?: ToolProfileConfig;\n  toolResultConfig?: ToolResultConfig;\n  contextManagement?: ContextManagementConfig;\n  contextBudget?: ContextBudgetConfig;\n}\n\n/**\n * Tool response format\n */\nexport interface ToolResponse<T = unknown> {\n  /** Whether the tool succeeded */\n  success: boolean;\n  /** Human-readable message */\n  message?: string;\n  /** Error message if failed */\n  error?: string;\n  /** Result data */\n  data?: T;\n\n  // ============================================\n  // AI Response Control (result-level overrides)\n  // ============================================\n\n  /**\n   * Override AI context for this specific result.\n   * Takes precedence over tool-level aiContext config.\n   * If set, this message is sent to AI instead of full result data.\n   *\n   * @example\n   * ```typescript\n   * return {\n   *   success: true,\n   *   data: sensitiveData,\n   *   _aiContext: '[Data retrieved - contains sensitive info, displayed to user]'\n   * };\n   * ```\n   */\n  _aiContext?: string;\n\n  /**\n   * Override AI response mode for this specific result.\n   * Takes precedence over tool-level aiResponseMode config.\n   */\n  _aiResponseMode?: AIResponseMode;\n\n  /**\n   * Content for AI to analyze (images, documents, etc.).\n   * When present, these are included as multimodal content for AI analysis.\n   *\n   * @example\n   * ```typescript\n   * // Screenshot for AI to analyze\n   * return {\n   *   success: true,\n   *   message: 'Screenshot captured',\n   *   _aiContent: [{ type: 'image', data: base64, mediaType: 'image/png' }]\n   * };\n   * ```\n   */\n  _aiContent?: AIContent[];\n\n  /**\n   * MCP-UI resources for rendering interactive UI components.\n   * These are extracted from MCP tool results and rendered as iframes.\n   * Not sent to the AI - purely for UI rendering.\n   *\n   * @example\n   * ```typescript\n   * // MCP tool returning UI\n   * return {\n   *   success: true,\n   *   message: 'Product displayed',\n   *   _uiResources: [{\n   *     uri: 'ui://shop/product/123',\n   *     mimeType: 'text/html',\n   *     content: '<div class=\"product\">...</div>',\n   *     metadata: { height: '300px' }\n   *   }]\n   * };\n   * ```\n   */\n  _uiResources?: Array<{\n    uri: string;\n    mimeType:\n      | \"text/html\"\n      | \"text/uri-list\"\n      | \"application/vnd.mcp-ui.remote-dom\";\n    content?: string;\n    blob?: string;\n    metadata?: {\n      title?: string;\n      width?: string;\n      height?: string;\n      sandbox?: string[];\n      className?: string;\n    };\n  }>;\n}\n\n/**\n * Approval callbacks passed to render when tool requires user action.\n * Only present when status is \"approval-required\".\n */\nexport interface ToolApprovalCallbacks {\n  /**\n   * Approve execution and optionally pass extra data to the handler.\n   * The extraData is available in handler via `context.approvalData`.\n   *\n   * @example\n   * ```tsx\n   * // Simple approval\n   * approval.onApprove();\n   *\n   * // Approval with data (e.g., user selection)\n   * approval.onApprove({ supervisor: { name: \"John\", role: \"Manager\" } });\n   * ```\n   */\n  onApprove: (extraData?: Record<string, unknown>) => void;\n\n  /**\n   * Reject the tool execution with optional reason.\n   * This stops the tool from executing and returns an error to AI.\n   */\n  onReject: (reason?: string) => void;\n\n  /** Custom message from tool's approvalMessage config */\n  message?: string;\n}\n\n/**\n * Props passed to tool render function.\n *\n * The render function is called for every status change, enabling\n * full lifecycle rendering similar to Vercel AI SDK.\n *\n * @example\n * ```tsx\n * render: ({ status, args, approval, result }) => {\n *   if (status === \"approval-required\" && approval) {\n *     return <ApprovalCard onConfirm={() => approval.onApprove()} />;\n *   }\n *   if (status === \"executing\") {\n *     return <LoadingSkeleton />;\n *   }\n *   if (status === \"completed\") {\n *     return <ResultCard data={result.data} />;\n *   }\n *   return null;\n * }\n * ```\n */\nexport interface ToolRenderProps<TParams = Record<string, unknown>> {\n  /**\n   * Current execution status:\n   * - `pending`: Tool call received, waiting to start\n   * - `approval-required`: Waiting for user approval (when needsApproval is set)\n   * - `executing`: Handler is running\n   * - `completed`: Handler finished successfully\n   * - `error`: Handler failed\n   */\n  status: \"pending\" | \"approval-required\" | \"executing\" | \"completed\" | \"error\";\n\n  /** Arguments passed to the tool */\n  args: TParams;\n\n  /** Result if completed */\n  result?: ToolResponse;\n\n  /** Error if failed */\n  error?: string;\n\n  /** Tool call ID */\n  toolCallId: string;\n\n  /** Tool name */\n  toolName: string;\n\n  /**\n   * Approval callbacks - only present when status is \"approval-required\".\n   * Use these to create custom approval UIs that can pass extra data to the handler.\n   */\n  approval?: ToolApprovalCallbacks;\n}\n\n/**\n * Tool definition with JSON Schema\n */\nexport interface ToolDefinition<TParams = Record<string, unknown>> {\n  /** Unique tool name */\n  name: string;\n  /** Tool description for LLM */\n  description: string;\n  /** Where the tool executes (server or client) */\n  location: ToolLocation;\n  /**\n   * Source/origin of the tool.\n   * Used to distinguish MCP tools from native/custom tools for UI rendering.\n   * @default \"custom\"\n   */\n  source?: ToolSource;\n  /** Optional category for search, filtering, and budgets */\n  category?: string;\n  /** Optional group for profile-based tool selection */\n  group?: string;\n  /** Deferred tools are discoverable but need not be sent on every request */\n  deferLoading?: boolean;\n  /** Profile memberships for selective tool loading */\n  profiles?: string[];\n  /** Extra keywords for dynamic tool selection */\n  searchKeywords?: string[];\n  /** Per-tool prompt/result shaping controls */\n  resultConfig?: ToolResultConfig;\n\n  // ============================================\n  // Display Configuration\n  // ============================================\n\n  /**\n   * Human-readable title for UI display.\n   * Can be a static string or a function that generates title from args.\n   *\n   * @example\n   * ```typescript\n   * title: \"Get order details\"\n   * // or dynamic:\n   * title: (args) => `Order #${args.orderId}`\n   * ```\n   */\n  title?: string | ((args: TParams) => string);\n\n  /**\n   * Title shown while executing (present tense with \"...\").\n   * If not provided, uses `title` with \"...\" appended.\n   *\n   * @example\n   * ```typescript\n   * executingTitle: (args) => `Fetching order #${args.orderId}...`\n   * ```\n   */\n  executingTitle?: string | ((args: TParams) => string);\n\n  /**\n   * Title shown after completion.\n   * If not provided, defaults to `title`.\n   *\n   * @example\n   * ```typescript\n   * completedTitle: (args) => `Retrieved order #${args.orderId}`\n   * ```\n   */\n  completedTitle?: string | ((args: TParams) => string);\n  /** JSON Schema for input parameters */\n  inputSchema: ToolInputSchema;\n  /** Handler function (optional for client tools registered on server) */\n  handler?: (\n    params: TParams,\n    context?: ToolContext,\n  ) => Promise<ToolResponse> | ToolResponse;\n  /** Optional render function for UI */\n  render?: (props: ToolRenderProps<TParams>) => unknown;\n  /** Whether the tool is available (for conditional registration) */\n  available?: boolean;\n\n  /**\n   * Hide this tool's execution from the chat UI.\n   * When true, tool calls and results won't be displayed to the user,\n   * but the tool will still execute normally.\n   * @default false\n   */\n  hidden?: boolean;\n\n  /**\n   * Require user approval before execution.\n   * Can be:\n   * - `true`: Always require approval\n   * - `false` or `undefined`: No approval needed (default)\n   * - `(params) => boolean`: Conditional approval based on input\n   *\n   * Similar to Vercel AI SDK v6's needsApproval pattern.\n   */\n  needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);\n\n  /**\n   * Custom message shown in the approval UI.\n   * Can be a string or a function that generates a message from params.\n   * If not provided, a default message with the tool name is shown.\n   */\n  approvalMessage?: string | ((params: TParams) => string);\n\n  // ============================================\n  // AI Response Control\n  // ============================================\n\n  /**\n   * How the AI should respond when this tool's result is rendered as UI.\n   *\n   * - `'none'`: AI generates minimal response (\"[Result displayed to user]\").\n   *   Use for tools where UI component fully handles the display (stats cards, etc.)\n   *\n   * - `'brief'`: AI receives summary context (from aiContext) and gives brief acknowledgment.\n   *   Use for charts/visualizations where AI should acknowledge but not repeat data.\n   *\n   * - `'full'`: AI receives complete data and responds accordingly (default).\n   *   Use for tools where AI should analyze and elaborate on results.\n   *\n   * @default 'full'\n   *\n   * @example\n   * ```typescript\n   * // Chart tool - AI acknowledges without repeating data\n   * const chartTool: ToolDefinition = {\n   *   name: 'get_chart',\n   *   aiResponseMode: 'brief',\n   *   aiContext: (result) => `[Chart displayed: ${result.data.title}]`,\n   *   handler: async () => ({ success: true, data: chartData })\n   * };\n   * ```\n   */\n  aiResponseMode?: AIResponseMode;\n\n  /**\n   * Context/summary sent to AI instead of (or along with) full result.\n   *\n   * Used when:\n   * - `aiResponseMode: 'brief'` - This becomes the only thing AI sees\n   * - `aiResponseMode: 'full'` - This is prepended to full data for context\n   *\n   * Can be:\n   * - `string`: Static message (e.g., \"[Weather data displayed]\")\n   * - `function`: Dynamic based on result (e.g., (result) => `[Chart: ${result.data.title}]`)\n   *\n   * @example\n   * ```typescript\n   * // Static context\n   * aiContext: '[Analytics chart displayed to user]'\n   *\n   * // Dynamic context based on result\n   * aiContext: (result, args) => {\n   *   const { title, currentValue } = result.data;\n   *   return `[Chart displayed: ${title}, showing ${currentValue}]`;\n   * }\n   * ```\n   */\n  aiContext?:\n    | string\n    | ((result: ToolResponse, args: Record<string, unknown>) => string);\n}\n\n// ============================================\n// Unified Tool Call Types (Provider-Agnostic)\n// ============================================\n\n/**\n * Unified tool call format (internal representation)\n */\nexport interface UnifiedToolCall {\n  /** Unique tool call ID */\n  id: string;\n  /** Tool name */\n  name: string;\n  /** Tool input arguments */\n  input: Record<string, unknown>;\n}\n\n/**\n * Unified tool result format\n */\nexport interface UnifiedToolResult {\n  /** Tool call ID this result is for */\n  toolCallId: string;\n  /** Serialized result content (JSON string) */\n  content: string;\n  /** Whether the tool succeeded */\n  success: boolean;\n  /** Error message if failed */\n  error?: string;\n}\n\n// ============================================\n// Tool Execution Types\n// ============================================\n\n/**\n * Tool execution status\n */\nexport type ToolExecutionStatus =\n  | \"pending\"\n  | \"executing\"\n  | \"completed\"\n  | \"error\";\n\n/**\n * Tool approval status (for human-in-the-loop)\n *\n * Similar to Vercel AI SDK v6's tool approval pattern.\n */\nexport type ToolApprovalStatus =\n  | \"none\" // No approval needed (default)\n  | \"required\" // Waiting for user decision\n  | \"approved\" // User approved, execution can proceed\n  | \"rejected\"; // User rejected, execution skipped\n\n// ============================================\n// Permission Persistence Types\n// ============================================\n\n/**\n * Permission level for tool execution\n *\n * Controls whether approval is needed and how the choice is remembered:\n * - \"ask\" - Always prompt user (default)\n * - \"allow_always\" - Auto-approve, persisted to storage\n * - \"deny_always\" - Auto-reject, persisted to storage\n * - \"session\" - Auto-approve for current session only\n */\nexport type PermissionLevel =\n  | \"ask\"\n  | \"allow_always\"\n  | \"deny_always\"\n  | \"session\";\n\n/**\n * Stored tool permission record\n */\nexport interface ToolPermission {\n  /** Tool name (unique identifier) */\n  toolName: string;\n  /** Permission level */\n  level: PermissionLevel;\n  /** When permission was set */\n  createdAt: number;\n  /** Last time this permission was used */\n  lastUsedAt?: number;\n}\n\n/**\n * Permission storage configuration\n */\nexport interface PermissionStorageConfig {\n  /**\n   * Storage type:\n   * - \"localStorage\" - Persists across browser sessions\n   * - \"sessionStorage\" - Clears when tab closes\n   * - \"memory\" - In-memory only (for SSR or testing)\n   */\n  type: \"localStorage\" | \"sessionStorage\" | \"memory\";\n  /** Storage key prefix (default: \"yourgpt-permissions\") */\n  keyPrefix?: string;\n}\n\n/**\n * Permission storage adapter interface (for custom implementations)\n */\nexport interface PermissionStorageAdapter {\n  /** Get permission for a tool */\n  get(toolName: string): Promise<ToolPermission | null>;\n  /** Set permission for a tool */\n  set(permission: ToolPermission): Promise<void>;\n  /** Remove permission for a tool */\n  remove(toolName: string): Promise<void>;\n  /** Get all permissions */\n  getAll(): Promise<ToolPermission[]>;\n  /** Clear all permissions */\n  clear(): Promise<void>;\n}\n\n/**\n * Tool execution record (for UI tracking)\n */\nexport interface ToolExecution {\n  /** Tool call ID */\n  id: string;\n  /** Tool name */\n  name: string;\n  /** Tool arguments */\n  args: Record<string, unknown>;\n  /** Execution status */\n  status: ToolExecutionStatus;\n  /** Result if completed */\n  result?: ToolResponse;\n  /** Error message if failed */\n  error?: string;\n  /** Timestamp when execution started */\n  timestamp: number;\n  /** Duration in ms (set when completed) */\n  duration?: number;\n\n  // Approval fields (for needsApproval tools)\n\n  /** Approval status for this execution */\n  approvalStatus: ToolApprovalStatus;\n  /** Message shown in approval UI (from tool's approvalMessage) */\n  approvalMessage?: string;\n  /** Timestamp when user responded to approval request */\n  approvalTimestamp?: number;\n\n  /**\n   * Whether this tool execution should be hidden from the UI.\n   * Server-side tools can set this to hide internal operations from users.\n   */\n  hidden?: boolean;\n}\n\n// ============================================\n// Agent Loop Types\n// ============================================\n\n/**\n * Agentic loop configuration\n */\nexport interface AgentLoopConfig {\n  /** Maximum iterations before stopping (default: 20) */\n  maxIterations?: number;\n  /** Enable debug logging */\n  debug?: boolean;\n  /** Whether to enable the agentic loop (default: true) */\n  enabled?: boolean;\n  /** Optional prompt/tool optimization controls */\n  optimization?: ToolOptimizationConfig;\n}\n\n/**\n * Agent loop state (for tracking)\n */\nexport interface AgentLoopState {\n  /** Current iteration number */\n  iteration: number;\n  /** Maximum iterations allowed */\n  maxIterations: number;\n  /** Whether the loop is currently running */\n  running: boolean;\n  /** Whether max iterations was reached */\n  maxIterationsReached: boolean;\n  /** Whether the loop was aborted */\n  aborted: boolean;\n}\n\n// ============================================\n// ToolSet Type (Vercel AI SDK pattern)\n// ============================================\n\n/**\n * A tool definition without the name (name is derived from the key in ToolSet)\n */\nexport type ToolSetEntry<TParams = Record<string, unknown>> = Omit<\n  ToolDefinition<TParams>,\n  \"name\"\n>;\n\n/**\n * A set of tools, keyed by tool name\n *\n * The key becomes the tool name, so tool definitions don't need a name property.\n * Use with the `tool()` helper for clean syntax.\n *\n * @example\n * ```typescript\n * const myTools: ToolSet = {\n *   capture_screenshot: tool({\n *     description: 'Capture screenshot',\n *     handler: async () => ({ success: true }),\n *   }),\n *   get_weather: tool({\n *     description: 'Get weather',\n *     inputSchema: { type: 'object', properties: { city: { type: 'string' } } },\n *     handler: async ({ city }) => ({ success: true, data: { temp: 72 } }),\n *   }),\n * };\n * ```\n */\nexport type ToolSet = Record<string, ToolSetEntry>;\n\n// ============================================\n// Tool Helper Function (Vercel AI SDK pattern)\n// ============================================\n\n/**\n * Configuration for creating a tool\n */\nexport interface ToolConfig<TParams = Record<string, unknown>> {\n  /** Tool description for LLM */\n  description: string;\n  /** Where the tool executes (default: 'client') */\n  location?: ToolLocation;\n  /** Optional category for search, filtering, and budgets */\n  category?: string;\n  /** Optional group for profile-based tool selection */\n  group?: string;\n  /** Deferred tools are discoverable but omitted from the default prompt */\n  deferLoading?: boolean;\n  /** Profile memberships for selective tool loading */\n  profiles?: string[];\n  /** Extra keywords for dynamic tool selection */\n  searchKeywords?: string[];\n  /** Per-tool prompt/result shaping controls */\n  resultConfig?: ToolResultConfig;\n\n  // Display Configuration\n  /** Human-readable title for UI display */\n  title?: string | ((args: TParams) => string);\n  /** Title shown while executing */\n  executingTitle?: string | ((args: TParams) => string);\n  /** Title shown after completion */\n  completedTitle?: string | ((args: TParams) => string);\n\n  /** JSON Schema for input parameters */\n  inputSchema?: ToolInputSchema;\n  /** Handler function */\n  handler?: (\n    params: TParams,\n    context?: ToolContext,\n  ) => Promise<ToolResponse> | ToolResponse;\n  /** Optional render function for UI */\n  render?: (props: ToolRenderProps<TParams>) => unknown;\n  /** Whether the tool is available */\n  available?: boolean;\n  /** Hide this tool from chat UI display */\n  hidden?: boolean;\n  /** Require user approval before execution */\n  needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);\n  /** Custom message shown in the approval UI */\n  approvalMessage?: string | ((params: TParams) => string);\n  /** AI response mode for this tool (default: 'full') */\n  aiResponseMode?: AIResponseMode;\n  /** Context/summary sent to AI instead of full result */\n  aiContext?:\n    | string\n    | ((result: ToolResponse, args: Record<string, unknown>) => string);\n}\n\n/**\n * Create a tool definition (similar to Vercel AI SDK's tool())\n *\n * @example\n * ```typescript\n * const weatherTool = tool({\n *   description: 'Get weather for a location',\n *   inputSchema: {\n *     type: 'object',\n *     properties: {\n *       location: { type: 'string', description: 'City name' },\n *     },\n *     required: ['location'],\n *   },\n *   handler: async ({ location }) => {\n *     const weather = await fetchWeather(location);\n *     return success(weather);\n *   },\n * });\n * ```\n */\nexport function tool<TParams = Record<string, unknown>>(\n  config: ToolConfig<TParams>,\n): Omit<ToolDefinition<TParams>, \"name\"> {\n  return {\n    description: config.description,\n    location: config.location ?? \"client\",\n    category: config.category,\n    group: config.group,\n    deferLoading: config.deferLoading,\n    profiles: config.profiles,\n    searchKeywords: config.searchKeywords,\n    resultConfig: config.resultConfig,\n    // Display configuration\n    title: config.title,\n    executingTitle: config.executingTitle,\n    completedTitle: config.completedTitle,\n    // Schema and handlers\n    inputSchema: config.inputSchema ?? {\n      type: \"object\",\n      properties: {},\n      required: [],\n    },\n    handler: config.handler,\n    render: config.render,\n    available: config.available,\n    hidden: config.hidden,\n    needsApproval: config.needsApproval,\n    approvalMessage: config.approvalMessage,\n    aiResponseMode: config.aiResponseMode,\n    aiContext: config.aiContext,\n  };\n}\n\n// ============================================\n// Helper Functions\n// ============================================\n\n/**\n * Convert ToolDefinition to OpenAI tool format\n */\nexport function toolToOpenAIFormat(tool: ToolDefinition): object {\n  return {\n    type: \"function\",\n    function: {\n      name: tool.name,\n      description: tool.description,\n      parameters: tool.inputSchema,\n    },\n  };\n}\n\n/**\n * Convert ToolDefinition to Anthropic tool format\n */\nexport function toolToAnthropicFormat(tool: ToolDefinition): object {\n  return {\n    name: tool.name,\n    description: tool.description,\n    input_schema: tool.inputSchema,\n  };\n}\n\n/**\n * Create a tool result response\n */\nexport function createToolResult(\n  toolCallId: string,\n  response: ToolResponse,\n): UnifiedToolResult {\n  return {\n    toolCallId,\n    content: JSON.stringify(response),\n    success: response.success,\n    error: response.error,\n  };\n}\n\n/**\n * Create a successful tool response\n */\nexport function success<T = unknown>(\n  data?: T,\n  message?: string,\n): ToolResponse<T> {\n  return {\n    success: true,\n    data,\n    message,\n  };\n}\n\n/**\n * Create a failed tool response\n */\nexport function failure(error: string): ToolResponse {\n  return {\n    success: false,\n    error,\n  };\n}\n"]}
+{"version":3,"sources":["../src/core/types/tools.ts"],"names":["tool"],"mappings":";AAk9BO,SAAS,KACd,MAAA,EACuC;AACvC,EAAA,OAAO;AAAA,IACL,aAAa,MAAA,CAAO,WAAA;AAAA,IACpB,QAAA,EAAU,OAAO,QAAA,IAAY,QAAA;AAAA,IAC7B,UAAU,MAAA,CAAO,QAAA;AAAA,IACjB,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,cAAc,MAAA,CAAO,YAAA;AAAA,IACrB,UAAU,MAAA,CAAO,QAAA;AAAA,IACjB,gBAAgB,MAAA,CAAO,cAAA;AAAA,IACvB,cAAc,MAAA,CAAO,YAAA;AAAA;AAAA,IAErB,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,gBAAgB,MAAA,CAAO,cAAA;AAAA,IACvB,gBAAgB,MAAA,CAAO,cAAA;AAAA;AAAA,IAEvB,WAAA,EAAa,OAAO,WAAA,IAAe;AAAA,MACjC,IAAA,EAAM,QAAA;AAAA,MACN,YAAY,EAAC;AAAA,MACb,UAAU;AAAC,KACb;AAAA,IACA,SAAS,MAAA,CAAO,OAAA;AAAA,IAChB,QAAQ,MAAA,CAAO,MAAA;AAAA,IACf,WAAW,MAAA,CAAO,SAAA;AAAA,IAClB,QAAQ,MAAA,CAAO,MAAA;AAAA,IACf,eAAe,MAAA,CAAO,aAAA;AAAA,IACtB,iBAAiB,MAAA,CAAO,eAAA;AAAA,IACxB,gBAAgB,MAAA,CAAO,cAAA;AAAA,IACvB,WAAW,MAAA,CAAO;AAAA,GACpB;AACF;AASO,SAAS,mBAAmBA,KAAAA,EAA8B;AAC/D,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,UAAA;AAAA,IACN,QAAA,EAAU;AAAA,MACR,MAAMA,KAAAA,CAAK,IAAA;AAAA,MACX,aAAaA,KAAAA,CAAK,WAAA;AAAA,MAClB,YAAYA,KAAAA,CAAK;AAAA;AACnB,GACF;AACF;AAKO,SAAS,sBAAsBA,KAAAA,EAA8B;AAClE,EAAA,OAAO;AAAA,IACL,MAAMA,KAAAA,CAAK,IAAA;AAAA,IACX,aAAaA,KAAAA,CAAK,WAAA;AAAA,IAClB,cAAcA,KAAAA,CAAK;AAAA,GACrB;AACF;AAKO,SAAS,gBAAA,CACd,YACA,QAAA,EACmB;AACnB,EAAA,OAAO;AAAA,IACL,UAAA;AAAA,IACA,OAAA,EAAS,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAA;AAAA,IAChC,SAAS,QAAA,CAAS,OAAA;AAAA,IAClB,OAAO,QAAA,CAAS;AAAA,GAClB;AACF;AAKO,SAAS,OAAA,CACd,MACA,OAAA,EACiB;AACjB,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,IAAA;AAAA,IACT,IAAA;AAAA,IACA;AAAA,GACF;AACF;AAKO,SAAS,QAAQ,KAAA,EAA6B;AACnD,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,KAAA;AAAA,IACT;AAAA,GACF;AACF","file":"chunk-3AONOZLY.js","sourcesContent":["/**\n * Tool-related types for the agentic loop\n */\n\nimport type { ActionRenderProps } from \"./actions\";\n\n// ============================================\n// Provider Types\n// ============================================\n\n/**\n * Supported AI providers for tool calling\n */\nexport type AIProvider =\n  | \"anthropic\"\n  | \"openai\"\n  | \"xai\"\n  | \"grok\"\n  | \"gemini\"\n  | \"groq\"\n  | \"ollama\";\n\n/**\n * Where the tool executes\n */\nexport type ToolLocation = \"server\" | \"client\";\n\n/**\n * Source/origin of the tool\n * - \"mcp\": Tool from an MCP (Model Context Protocol) server\n * - \"native\": Built-in SDK tool\n * - \"custom\": User-defined tool\n */\nexport type ToolSource = \"mcp\" | \"native\" | \"custom\";\n\n// ============================================\n// Tool Definition Types\n// ============================================\n\n/**\n * JSON Schema property definition\n */\nexport interface JSONSchemaProperty {\n  type:\n    | \"string\"\n    | \"number\"\n    | \"boolean\"\n    | \"object\"\n    | \"array\"\n    | \"integer\"\n    | \"null\";\n  description?: string;\n  enum?: (string | number | boolean)[];\n  items?: JSONSchemaProperty;\n  properties?: Record<string, JSONSchemaProperty>;\n  required?: string[];\n  default?: unknown;\n  minLength?: number;\n  maxLength?: number;\n  minimum?: number;\n  maximum?: number;\n  pattern?: string;\n}\n\n/**\n * JSON Schema for tool input\n */\nexport interface ToolInputSchema {\n  type: \"object\";\n  properties: Record<string, JSONSchemaProperty>;\n  required?: string[];\n  additionalProperties?: boolean;\n}\n\n/**\n * Tool execution context\n *\n * Provides runtime information to tool handlers including cancellation signals,\n * request metadata, and custom context data.\n */\nexport interface ToolContext {\n  /** Abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Thread ID if using threads */\n  threadId?: string;\n  /** Custom context data passed from runtime config */\n  data?: Record<string, unknown>;\n\n  // ============================================\n  // Rich Context (Vercel AI SDK pattern)\n  // ============================================\n\n  /**\n   * Unique ID for this specific tool call.\n   * Useful for logging, tracing, and correlating tool executions.\n   */\n  toolCallId?: string;\n\n  /**\n   * Request headers (for auth in server tools).\n   * Contains headers from the original HTTP request.\n   *\n   * @example\n   * ```typescript\n   * handler: async (params, context) => {\n   *   const token = context?.headers?.authorization;\n   *   if (!token) return failure('Authentication required');\n   *   // ...\n   * }\n   * ```\n   */\n  headers?: Record<string, string>;\n\n  /**\n   * Full request metadata for server-side tools.\n   * Provides access to HTTP method, URL, and headers.\n   *\n   * @example\n   * ```typescript\n   * handler: async (params, context) => {\n   *   console.log(`Tool called from: ${context?.request?.url}`);\n   *   // Forward auth to internal service\n   *   const authHeader = context?.request?.headers?.authorization;\n   * }\n   * ```\n   */\n  request?: {\n    /** HTTP method (GET, POST, etc.) */\n    method?: string;\n    /** Request URL path */\n    url?: string;\n    /** Request headers */\n    headers?: Record<string, string>;\n  };\n\n  /**\n   * Data passed from user's approval action.\n   * Only present when tool has `needsApproval: true` and user approved with extra data.\n   *\n   * @example\n   * ```typescript\n   * // In render function:\n   * approval.onApprove({ supervisor: selectedSupervisor });\n   *\n   * // In handler:\n   * handler: async (params, context) => {\n   *   const supervisor = context?.approvalData?.supervisor;\n   *   await assignToSupervisor(params.ticketId, supervisor);\n   * }\n   * ```\n   */\n  approvalData?: Record<string, unknown>;\n}\n\n// ============================================\n// AI Response Control Types\n// ============================================\n\n/**\n * AI response behavior for tool results.\n *\n * Controls what the AI sees after a tool executes and renders UI.\n *\n * - `'none'`: AI generates minimal response, UI component handles display\n * - `'brief'`: AI gets summary context (via aiContext), gives brief acknowledgment\n * - `'full'`: AI receives full data and responds accordingly (default)\n */\nexport type AIResponseMode = \"none\" | \"brief\" | \"full\";\n\n/**\n * Multimodal content for AI to analyze\n */\nexport type AIContent =\n  | { type: \"image\"; data: string; mediaType: string }\n  | { type: \"text\"; text: string };\n\n/**\n * How large tool results should be trimmed before they are sent back to the AI.\n */\nexport type ToolTruncationStrategy = \"head\" | \"head-tail\" | \"smart\";\n\n/**\n * Truncation controls for tool results.\n */\nexport interface ToolResultTruncationConfig {\n  enabled?: boolean;\n  maxContextShare?: number;\n  hardMaxChars?: number;\n  minKeepChars?: number;\n  strategy?: ToolTruncationStrategy;\n  preserveErrors?: boolean;\n}\n\n/**\n * Global or per-tool controls for how tool results are represented in prompts.\n */\nexport interface ToolResultConfig {\n  truncation?: ToolResultTruncationConfig;\n}\n\n/**\n * Named tool profile for selective loading.\n */\nexport interface ToolProfile {\n  name: string;\n  description?: string;\n  include?: string[];\n  exclude?: string[];\n}\n\n/**\n * Tool profile configuration.\n */\nexport interface ToolProfileConfig {\n  enabled?: boolean;\n  defaultProfile?: string;\n  profiles?: Record<string, ToolProfile>;\n  /** When false, active profiles exclude tools that do not declare profile membership. */\n  includeUnprofiled?: boolean;\n  dynamicSelection?: {\n    enabled?: boolean;\n    maxTools?: number;\n  };\n}\n\n/**\n * History compaction behavior for long-running sessions.\n */\nexport interface ContextHistoryConfig {\n  maxMessages?: number;\n  maxTokens?: number;\n  maxContextShare?: number;\n  pruneStrategy?: \"oldest\" | \"least-relevant\" | \"summarize\";\n}\n\n/**\n * Optional summarization controls used during history compaction.\n */\nexport interface ContextSummarizationConfig {\n  enabled?: boolean;\n  triggerAt?: number;\n  chunkSize?: number;\n  preserveRecent?: number;\n  fallbackBehavior?: \"truncate\" | \"statistical\" | \"error\";\n}\n\n/**\n * Token estimation controls.\n */\nexport interface TokenEstimationConfig {\n  safetyMargin?: number;\n  charsPerToken?: number;\n}\n\n/**\n * Conversation context management.\n */\nexport interface ContextManagementConfig {\n  enabled?: boolean;\n  history?: ContextHistoryConfig;\n  summarization?: ContextSummarizationConfig;\n  tokenEstimation?: TokenEstimationConfig;\n}\n\n/**\n * One budget bucket in the prompt context.\n */\nexport interface ContextUsagePart {\n  tokens: number;\n  percent: number;\n}\n\n/**\n * Prompt context usage snapshot.\n */\nexport interface ContextUsage {\n  total: ContextUsagePart;\n  breakdown: {\n    systemPrompt: ContextUsagePart;\n    history: ContextUsagePart;\n    toolResults: ContextUsagePart;\n    tools: ContextUsagePart;\n  };\n  budget: {\n    available: number;\n    remaining: number;\n  };\n  warnings: string[];\n}\n\n/**\n * Real-time context budget configuration.\n */\nexport interface ContextBudgetConfig {\n  enabled?: boolean;\n  budget?: {\n    contextWindowTokens?: number;\n    inputHeadroomRatio?: number;\n    systemPromptShare?: number;\n    historyShare?: number;\n    toolResultsShare?: number;\n    toolDefinitionsShare?: number;\n  };\n  enforcement?: {\n    mode?: \"warn\" | \"truncate\" | \"error\";\n    onBudgetExceeded?: (info: ContextUsage) => void;\n  };\n  monitoring?: {\n    enabled?: boolean;\n    onUsageUpdate?: (usage: ContextUsage) => void;\n  };\n}\n\n/**\n * Framework-agnostic optimization controls for tool-heavy chat sessions.\n */\nexport interface ToolOptimizationConfig {\n  toolProfiles?: ToolProfileConfig;\n  toolResultConfig?: ToolResultConfig;\n  contextManagement?: ContextManagementConfig;\n  contextBudget?: ContextBudgetConfig;\n}\n\n/**\n * Tool response format\n */\nexport interface ToolResponse<T = unknown> {\n  /** Whether the tool succeeded */\n  success: boolean;\n  /** Human-readable message */\n  message?: string;\n  /** Error message if failed */\n  error?: string;\n  /** Result data */\n  data?: T;\n\n  // ============================================\n  // AI Response Control (result-level overrides)\n  // ============================================\n\n  /**\n   * Override AI context for this specific result.\n   * Takes precedence over tool-level aiContext config.\n   * If set, this message is sent to AI instead of full result data.\n   *\n   * @example\n   * ```typescript\n   * return {\n   *   success: true,\n   *   data: sensitiveData,\n   *   _aiContext: '[Data retrieved - contains sensitive info, displayed to user]'\n   * };\n   * ```\n   */\n  _aiContext?: string;\n\n  /**\n   * Override AI response mode for this specific result.\n   * Takes precedence over tool-level aiResponseMode config.\n   */\n  _aiResponseMode?: AIResponseMode;\n\n  /**\n   * Content for AI to analyze (images, documents, etc.).\n   * When present, these are included as multimodal content for AI analysis.\n   *\n   * @example\n   * ```typescript\n   * // Screenshot for AI to analyze\n   * return {\n   *   success: true,\n   *   message: 'Screenshot captured',\n   *   _aiContent: [{ type: 'image', data: base64, mediaType: 'image/png' }]\n   * };\n   * ```\n   */\n  _aiContent?: AIContent[];\n\n  /**\n   * MCP-UI resources for rendering interactive UI components.\n   * These are extracted from MCP tool results and rendered as iframes.\n   * Not sent to the AI - purely for UI rendering.\n   *\n   * @example\n   * ```typescript\n   * // MCP tool returning UI\n   * return {\n   *   success: true,\n   *   message: 'Product displayed',\n   *   _uiResources: [{\n   *     uri: 'ui://shop/product/123',\n   *     mimeType: 'text/html',\n   *     content: '<div class=\"product\">...</div>',\n   *     metadata: { height: '300px' }\n   *   }]\n   * };\n   * ```\n   */\n  _uiResources?: Array<{\n    uri: string;\n    mimeType:\n      | \"text/html\"\n      | \"text/uri-list\"\n      | \"application/vnd.mcp-ui.remote-dom\";\n    content?: string;\n    blob?: string;\n    metadata?: {\n      title?: string;\n      width?: string;\n      height?: string;\n      sandbox?: string[];\n      className?: string;\n    };\n  }>;\n}\n\n/**\n * Approval callbacks passed to render when tool requires user action.\n * Only present when status is \"approval-required\".\n */\nexport interface ToolApprovalCallbacks {\n  /**\n   * Approve execution and optionally pass extra data to the handler.\n   * The extraData is available in handler via `context.approvalData`.\n   *\n   * @example\n   * ```tsx\n   * // Simple approval\n   * approval.onApprove();\n   *\n   * // Approval with data (e.g., user selection)\n   * approval.onApprove({ supervisor: { name: \"John\", role: \"Manager\" } });\n   * ```\n   */\n  onApprove: (extraData?: Record<string, unknown>) => void;\n\n  /**\n   * Reject the tool execution with optional reason.\n   * This stops the tool from executing and returns an error to AI.\n   */\n  onReject: (reason?: string) => void;\n\n  /** Custom message from tool's approvalMessage config */\n  message?: string;\n}\n\n/**\n * Props passed to tool render function.\n *\n * The render function is called for every status change, enabling\n * full lifecycle rendering similar to Vercel AI SDK.\n *\n * @example\n * ```tsx\n * render: ({ status, args, approval, result }) => {\n *   if (status === \"approval-required\" && approval) {\n *     return <ApprovalCard onConfirm={() => approval.onApprove()} />;\n *   }\n *   if (status === \"executing\") {\n *     return <LoadingSkeleton />;\n *   }\n *   if (status === \"completed\") {\n *     return <ResultCard data={result.data} />;\n *   }\n *   return null;\n * }\n * ```\n */\nexport interface ToolRenderProps<TParams = Record<string, unknown>> {\n  /**\n   * Current execution status:\n   * - `pending`: Tool call received, waiting to start\n   * - `approval-required`: Waiting for user approval (when needsApproval is set)\n   * - `executing`: Handler is running\n   * - `completed`: Handler finished successfully\n   * - `error`: Handler failed\n   */\n  status: \"pending\" | \"approval-required\" | \"executing\" | \"completed\" | \"error\";\n\n  /** Arguments passed to the tool */\n  args: TParams;\n\n  /** Result if completed */\n  result?: ToolResponse;\n\n  /** Error if failed */\n  error?: string;\n\n  /** Tool call ID */\n  toolCallId: string;\n\n  /** Tool name */\n  toolName: string;\n\n  /**\n   * Approval callbacks - only present when status is \"approval-required\".\n   * Use these to create custom approval UIs that can pass extra data to the handler.\n   */\n  approval?: ToolApprovalCallbacks;\n}\n\n/**\n * Tool definition with JSON Schema\n */\nexport interface ToolDefinition<TParams = Record<string, unknown>> {\n  /** Unique tool name */\n  name: string;\n  /** Tool description for LLM */\n  description: string;\n  /** Where the tool executes (server or client) */\n  location: ToolLocation;\n  /**\n   * Source/origin of the tool.\n   * Used to distinguish MCP tools from native/custom tools for UI rendering.\n   * @default \"custom\"\n   */\n  source?: ToolSource;\n  /** Optional category for search, filtering, and budgets */\n  category?: string;\n  /** Optional group for profile-based tool selection */\n  group?: string;\n  /** Deferred tools are discoverable but need not be sent on every request */\n  deferLoading?: boolean;\n  /** Profile memberships for selective tool loading */\n  profiles?: string[];\n  /** Extra keywords for dynamic tool selection */\n  searchKeywords?: string[];\n  /** Per-tool prompt/result shaping controls */\n  resultConfig?: ToolResultConfig;\n\n  // ============================================\n  // Display Configuration\n  // ============================================\n\n  /**\n   * Human-readable title for UI display.\n   * Can be a static string or a function that generates title from args.\n   *\n   * @example\n   * ```typescript\n   * title: \"Get order details\"\n   * // or dynamic:\n   * title: (args) => `Order #${args.orderId}`\n   * ```\n   */\n  title?: string | ((args: TParams) => string);\n\n  /**\n   * Title shown while executing (present tense with \"...\").\n   * If not provided, uses `title` with \"...\" appended.\n   *\n   * @example\n   * ```typescript\n   * executingTitle: (args) => `Fetching order #${args.orderId}...`\n   * ```\n   */\n  executingTitle?: string | ((args: TParams) => string);\n\n  /**\n   * Title shown after completion.\n   * If not provided, defaults to `title`.\n   *\n   * @example\n   * ```typescript\n   * completedTitle: (args) => `Retrieved order #${args.orderId}`\n   * ```\n   */\n  completedTitle?: string | ((args: TParams) => string);\n  /** JSON Schema for input parameters */\n  inputSchema: ToolInputSchema;\n  /** Handler function (optional for client tools registered on server) */\n  handler?: (\n    params: TParams,\n    context?: ToolContext,\n  ) => Promise<ToolResponse> | ToolResponse;\n  /** Optional render function for UI */\n  render?: (props: ToolRenderProps<TParams>) => unknown;\n  /** Whether the tool is available (for conditional registration) */\n  available?: boolean;\n\n  /**\n   * Hide this tool's execution from the chat UI.\n   * When true, tool calls and results won't be displayed to the user,\n   * but the tool will still execute normally.\n   * @default false\n   */\n  hidden?: boolean;\n\n  /**\n   * Require user approval before execution.\n   * Can be:\n   * - `true`: Always require approval\n   * - `false` or `undefined`: No approval needed (default)\n   * - `(params) => boolean`: Conditional approval based on input\n   *\n   * Similar to Vercel AI SDK v6's needsApproval pattern.\n   */\n  needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);\n\n  /**\n   * Custom title shown in the approval UI.\n   * If not provided, the tool name is used.\n   */\n  approvalTitle?: string | ((params: TParams) => string);\n\n  /**\n   * Custom message shown in the approval UI.\n   * Can be a string or a function that generates a message from params.\n   * If not provided, a default message with the tool name is shown.\n   */\n  approvalMessage?: string | ((params: TParams) => string);\n\n  // ============================================\n  // AI Response Control\n  // ============================================\n\n  /**\n   * How the AI should respond when this tool's result is rendered as UI.\n   *\n   * - `'none'`: AI generates minimal response (\"[Result displayed to user]\").\n   *   Use for tools where UI component fully handles the display (stats cards, etc.)\n   *\n   * - `'brief'`: AI receives summary context (from aiContext) and gives brief acknowledgment.\n   *   Use for charts/visualizations where AI should acknowledge but not repeat data.\n   *\n   * - `'full'`: AI receives complete data and responds accordingly (default).\n   *   Use for tools where AI should analyze and elaborate on results.\n   *\n   * @default 'full'\n   *\n   * @example\n   * ```typescript\n   * // Chart tool - AI acknowledges without repeating data\n   * const chartTool: ToolDefinition = {\n   *   name: 'get_chart',\n   *   aiResponseMode: 'brief',\n   *   aiContext: (result) => `[Chart displayed: ${result.data.title}]`,\n   *   handler: async () => ({ success: true, data: chartData })\n   * };\n   * ```\n   */\n  aiResponseMode?: AIResponseMode;\n\n  /**\n   * Context/summary sent to AI instead of (or along with) full result.\n   *\n   * Used when:\n   * - `aiResponseMode: 'brief'` - This becomes the only thing AI sees\n   * - `aiResponseMode: 'full'` - This is prepended to full data for context\n   *\n   * Can be:\n   * - `string`: Static message (e.g., \"[Weather data displayed]\")\n   * - `function`: Dynamic based on result (e.g., (result) => `[Chart: ${result.data.title}]`)\n   *\n   * @example\n   * ```typescript\n   * // Static context\n   * aiContext: '[Analytics chart displayed to user]'\n   *\n   * // Dynamic context based on result\n   * aiContext: (result, args) => {\n   *   const { title, currentValue } = result.data;\n   *   return `[Chart displayed: ${title}, showing ${currentValue}]`;\n   * }\n   * ```\n   */\n  aiContext?:\n    | string\n    | ((result: ToolResponse, args: Record<string, unknown>) => string);\n}\n\n// ============================================\n// Unified Tool Call Types (Provider-Agnostic)\n// ============================================\n\n/**\n * Unified tool call format (internal representation)\n */\nexport interface UnifiedToolCall {\n  /** Unique tool call ID */\n  id: string;\n  /** Tool name */\n  name: string;\n  /** Tool input arguments */\n  input: Record<string, unknown>;\n}\n\n/**\n * Unified tool result format\n */\nexport interface UnifiedToolResult {\n  /** Tool call ID this result is for */\n  toolCallId: string;\n  /** Serialized result content (JSON string) */\n  content: string;\n  /** Whether the tool succeeded */\n  success: boolean;\n  /** Error message if failed */\n  error?: string;\n}\n\n// ============================================\n// Tool Execution Types\n// ============================================\n\n/**\n * Tool execution status\n */\nexport type ToolExecutionStatus =\n  | \"pending\"\n  | \"executing\"\n  | \"completed\"\n  | \"error\";\n\n/**\n * Tool approval status (for human-in-the-loop)\n *\n * Similar to Vercel AI SDK v6's tool approval pattern.\n */\nexport type ToolApprovalStatus =\n  | \"none\" // No approval needed (default)\n  | \"required\" // Waiting for user decision\n  | \"approved\" // User approved, execution can proceed\n  | \"rejected\"; // User rejected, execution skipped\n\n// ============================================\n// Permission Persistence Types\n// ============================================\n\n/**\n * Permission level for tool execution\n *\n * Controls whether approval is needed and how the choice is remembered:\n * - \"ask\" - Always prompt user (default)\n * - \"allow_always\" - Auto-approve, persisted to storage\n * - \"deny_always\" - Auto-reject, persisted to storage\n * - \"session\" - Auto-approve for current session only\n */\nexport type PermissionLevel =\n  | \"ask\"\n  | \"allow_always\"\n  | \"deny_always\"\n  | \"session\";\n\n/**\n * Stored tool permission record\n */\nexport interface ToolPermission {\n  /** Tool name (unique identifier) */\n  toolName: string;\n  /** Permission level */\n  level: PermissionLevel;\n  /** When permission was set */\n  createdAt: number;\n  /** Last time this permission was used */\n  lastUsedAt?: number;\n}\n\n/**\n * Permission storage configuration\n */\nexport interface PermissionStorageConfig {\n  /**\n   * Storage type:\n   * - \"localStorage\" - Persists across browser sessions\n   * - \"sessionStorage\" - Clears when tab closes\n   * - \"memory\" - In-memory only (for SSR or testing)\n   */\n  type: \"localStorage\" | \"sessionStorage\" | \"memory\";\n  /** Storage key prefix (default: \"yourgpt-permissions\") */\n  keyPrefix?: string;\n}\n\n/**\n * Permission storage adapter interface (for custom implementations)\n */\nexport interface PermissionStorageAdapter {\n  /** Get permission for a tool */\n  get(toolName: string): Promise<ToolPermission | null>;\n  /** Set permission for a tool */\n  set(permission: ToolPermission): Promise<void>;\n  /** Remove permission for a tool */\n  remove(toolName: string): Promise<void>;\n  /** Get all permissions */\n  getAll(): Promise<ToolPermission[]>;\n  /** Clear all permissions */\n  clear(): Promise<void>;\n}\n\n/**\n * Tool execution record (for UI tracking)\n */\nexport interface ToolExecution {\n  /** Tool call ID */\n  id: string;\n  /** Tool name */\n  name: string;\n  /** Tool arguments */\n  args: Record<string, unknown>;\n  /** Execution status */\n  status: ToolExecutionStatus;\n  /** Result if completed */\n  result?: ToolResponse;\n  /** Error message if failed */\n  error?: string;\n  /** Timestamp when execution started */\n  timestamp: number;\n  /** Duration in ms (set when completed) */\n  duration?: number;\n\n  // Approval fields (for needsApproval tools)\n\n  /** Approval status for this execution */\n  approvalStatus: ToolApprovalStatus;\n  /** Title shown in approval UI (from tool's approvalTitle) */\n  approvalTitle?: string;\n  /** Message shown in approval UI (from tool's approvalMessage) */\n  approvalMessage?: string;\n  /** Timestamp when user responded to approval request */\n  approvalTimestamp?: number;\n\n  /**\n   * Whether this tool execution should be hidden from the UI.\n   * Server-side tools can set this to hide internal operations from users.\n   */\n  hidden?: boolean;\n}\n\n// ============================================\n// Agent Loop Types\n// ============================================\n\n/**\n * Agentic loop configuration\n */\nexport interface AgentLoopConfig {\n  /** Maximum iterations before stopping (default: 20) */\n  maxIterations?: number;\n  /** Enable debug logging */\n  debug?: boolean;\n  /** Whether to enable the agentic loop (default: true) */\n  enabled?: boolean;\n  /** Optional prompt/tool optimization controls */\n  optimization?: ToolOptimizationConfig;\n}\n\n/**\n * Agent loop state (for tracking)\n */\nexport interface AgentLoopState {\n  /** Current iteration number */\n  iteration: number;\n  /** Maximum iterations allowed */\n  maxIterations: number;\n  /** Whether the loop is currently running */\n  running: boolean;\n  /** Whether max iterations was reached */\n  maxIterationsReached: boolean;\n  /** Whether the loop was aborted */\n  aborted: boolean;\n}\n\n// ============================================\n// ToolSet Type (Vercel AI SDK pattern)\n// ============================================\n\n/**\n * A tool definition without the name (name is derived from the key in ToolSet)\n */\nexport type ToolSetEntry<TParams = Record<string, unknown>> = Omit<\n  ToolDefinition<TParams>,\n  \"name\"\n>;\n\n/**\n * A set of tools, keyed by tool name\n *\n * The key becomes the tool name, so tool definitions don't need a name property.\n * Use with the `tool()` helper for clean syntax.\n *\n * @example\n * ```typescript\n * const myTools: ToolSet = {\n *   capture_screenshot: tool({\n *     description: 'Capture screenshot',\n *     handler: async () => ({ success: true }),\n *   }),\n *   get_weather: tool({\n *     description: 'Get weather',\n *     inputSchema: { type: 'object', properties: { city: { type: 'string' } } },\n *     handler: async ({ city }) => ({ success: true, data: { temp: 72 } }),\n *   }),\n * };\n * ```\n */\nexport type ToolSet = Record<string, ToolSetEntry>;\n\n// ============================================\n// Tool Helper Function (Vercel AI SDK pattern)\n// ============================================\n\n/**\n * Configuration for creating a tool\n */\nexport interface ToolConfig<TParams = Record<string, unknown>> {\n  /** Tool description for LLM */\n  description: string;\n  /** Where the tool executes (default: 'client') */\n  location?: ToolLocation;\n  /** Optional category for search, filtering, and budgets */\n  category?: string;\n  /** Optional group for profile-based tool selection */\n  group?: string;\n  /** Deferred tools are discoverable but omitted from the default prompt */\n  deferLoading?: boolean;\n  /** Profile memberships for selective tool loading */\n  profiles?: string[];\n  /** Extra keywords for dynamic tool selection */\n  searchKeywords?: string[];\n  /** Per-tool prompt/result shaping controls */\n  resultConfig?: ToolResultConfig;\n\n  // Display Configuration\n  /** Human-readable title for UI display */\n  title?: string | ((args: TParams) => string);\n  /** Title shown while executing */\n  executingTitle?: string | ((args: TParams) => string);\n  /** Title shown after completion */\n  completedTitle?: string | ((args: TParams) => string);\n\n  /** JSON Schema for input parameters */\n  inputSchema?: ToolInputSchema;\n  /** Handler function */\n  handler?: (\n    params: TParams,\n    context?: ToolContext,\n  ) => Promise<ToolResponse> | ToolResponse;\n  /** Optional render function for UI */\n  render?: (props: ToolRenderProps<TParams>) => unknown;\n  /** Whether the tool is available */\n  available?: boolean;\n  /** Hide this tool from chat UI display */\n  hidden?: boolean;\n  /** Require user approval before execution */\n  needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);\n  /** Custom title shown in the approval UI */\n  approvalTitle?: string | ((params: TParams) => string);\n  /** Custom message shown in the approval UI */\n  approvalMessage?: string | ((params: TParams) => string);\n  /** AI response mode for this tool (default: 'full') */\n  aiResponseMode?: AIResponseMode;\n  /** Context/summary sent to AI instead of full result */\n  aiContext?:\n    | string\n    | ((result: ToolResponse, args: Record<string, unknown>) => string);\n}\n\n/**\n * Create a tool definition (similar to Vercel AI SDK's tool())\n *\n * @example\n * ```typescript\n * const weatherTool = tool({\n *   description: 'Get weather for a location',\n *   inputSchema: {\n *     type: 'object',\n *     properties: {\n *       location: { type: 'string', description: 'City name' },\n *     },\n *     required: ['location'],\n *   },\n *   handler: async ({ location }) => {\n *     const weather = await fetchWeather(location);\n *     return success(weather);\n *   },\n * });\n * ```\n */\nexport function tool<TParams = Record<string, unknown>>(\n  config: ToolConfig<TParams>,\n): Omit<ToolDefinition<TParams>, \"name\"> {\n  return {\n    description: config.description,\n    location: config.location ?? \"client\",\n    category: config.category,\n    group: config.group,\n    deferLoading: config.deferLoading,\n    profiles: config.profiles,\n    searchKeywords: config.searchKeywords,\n    resultConfig: config.resultConfig,\n    // Display configuration\n    title: config.title,\n    executingTitle: config.executingTitle,\n    completedTitle: config.completedTitle,\n    // Schema and handlers\n    inputSchema: config.inputSchema ?? {\n      type: \"object\",\n      properties: {},\n      required: [],\n    },\n    handler: config.handler,\n    render: config.render,\n    available: config.available,\n    hidden: config.hidden,\n    needsApproval: config.needsApproval,\n    approvalMessage: config.approvalMessage,\n    aiResponseMode: config.aiResponseMode,\n    aiContext: config.aiContext,\n  };\n}\n\n// ============================================\n// Helper Functions\n// ============================================\n\n/**\n * Convert ToolDefinition to OpenAI tool format\n */\nexport function toolToOpenAIFormat(tool: ToolDefinition): object {\n  return {\n    type: \"function\",\n    function: {\n      name: tool.name,\n      description: tool.description,\n      parameters: tool.inputSchema,\n    },\n  };\n}\n\n/**\n * Convert ToolDefinition to Anthropic tool format\n */\nexport function toolToAnthropicFormat(tool: ToolDefinition): object {\n  return {\n    name: tool.name,\n    description: tool.description,\n    input_schema: tool.inputSchema,\n  };\n}\n\n/**\n * Create a tool result response\n */\nexport function createToolResult(\n  toolCallId: string,\n  response: ToolResponse,\n): UnifiedToolResult {\n  return {\n    toolCallId,\n    content: JSON.stringify(response),\n    success: response.success,\n    error: response.error,\n  };\n}\n\n/**\n * Create a successful tool response\n */\nexport function success<T = unknown>(\n  data?: T,\n  message?: string,\n): ToolResponse<T> {\n  return {\n    success: true,\n    data,\n    message,\n  };\n}\n\n/**\n * Create a failed tool response\n */\nexport function failure(error: string): ToolResponse {\n  return {\n    success: false,\n    error,\n  };\n}\n"]}

package/dist/{chunk-JKGFQUHJ.cjs → chunk-MDS23G2S.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var chunk246B6X5D_cjs = require('./chunk-246B6X5D.cjs');
+var chunkTPB7XED6_cjs = require('./chunk-TPB7XED6.cjs');
 var chunkNUXLAZOE_cjs = require('./chunk-NUXLAZOE.cjs');
 
 // src/core/tools/builtin/webSearch.ts
-var webSearchTool = chunk246B6X5D_cjs.tool({
+var webSearchTool = chunkTPB7XED6_cjs.tool({
   description: `Search the web for current information. Use this when the user asks about:
 - Recent events, news, or current affairs
 - Real-time data (prices, weather, stocks, sports scores)
@@ -70,7 +70,7 @@ function createWebSearchTool(config) {
         };
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Web search failed";
-        return chunk246B6X5D_cjs.failure(errorMessage);
+        return chunkTPB7XED6_cjs.failure(errorMessage);
       }
     }
   };
@@ -78,5 +78,5 @@ function createWebSearchTool(config) {
 
 exports.createWebSearchTool = createWebSearchTool;
 exports.webSearchTool = webSearchTool;
-//# sourceMappingURL=chunk-JKGFQUHJ.cjs.map
-//# sourceMappingURL=chunk-JKGFQUHJ.cjs.map
+//# sourceMappingURL=chunk-MDS23G2S.cjs.map
+//# sourceMappingURL=chunk-MDS23G2S.cjs.map

package/dist/{chunk-JKGFQUHJ.cjs.map → chunk-MDS23G2S.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/tools/builtin/webSearch.ts"],"names":["tool","formatSearchResultsForAI","executeWebSearch","summarizeSearchResults","failure"],"mappings":";;;;;;AAoDO,IAAM,gBAAgBA,sBAAA,CAAsB;AAAA,EACjD,WAAA,EAAa,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qDAAA,CAAA;AAAA,EAOb,QAAA,EAAU,QAAA;AAAA;AAAA,EAEV,KAAA,EAAO,CAAC,IAAA,KAAS,CAAA,eAAA,EAAkB,KAAK,KAAK,CAAA,CAAA,CAAA;AAAA,EAC7C,cAAA,EAAgB,CAAC,IAAA,KAAS,CAAA,uBAAA,EAA0B,KAAK,KAAK,CAAA,IAAA,CAAA;AAAA,EAC9D,cAAA,EAAgB,CAAC,IAAA,KAAS,CAAA,mBAAA,EAAsB,KAAK,KAAK,CAAA,CAAA,CAAA;AAAA,EAE1D,WAAA,EAAa;AAAA,IACX,IAAA,EAAM,QAAA;AAAA,IACN,UAAA,EAAY;AAAA,MACV,KAAA,EAAO;AAAA,QACL,IAAA,EAAM,QAAA;AAAA,QACN,WAAA,EAAa;AAAA,OACf;AAAA,MACA,UAAA,EAAY;AAAA,QACV,IAAA,EAAM,QAAA;AAAA,QACN,WAAA,EACE,2DAAA;AAAA,QACF,OAAA,EAAS,CAAA;AAAA,QACT,OAAA,EAAS;AAAA,OACX;AAAA,MACA,WAAA,EAAa;AAAA,QACX,IAAA,EAAM,QAAA;AAAA,QACN,IAAA,EAAM,CAAC,OAAA,EAAS,UAAU,CAAA;AAAA,QAC1B,WAAA,EACE;AAAA;AACJ,KACF;AAAA,IACA,QAAA,EAAU,CAAC,OAAO;AAAA,GACpB;AAAA,EAEA,aAAA,EAAe,KAAA;AAAA;AAAA;AAAA,EAGf,cAAA,EAAgB,MAAA;AAAA,EAChB,SAAA,EAAW,CAAC,MAAA,EAAQ,IAAA,KAAS;AAC3B,IAAA,IAAI,CAAC,MAAA,CAAO,OAAA,EAAS,OAAO,CAAA,eAAA,EAAkB,OAAO,KAAK,CAAA,CAAA;AAC1D,IAAA,MAAM,OAAO,MAAA,CAAO,IAAA;AACpB,IAAA,OAAOC,2CAAyB,IAAI,CAAA;AAAA,EACtC;AACF,CAAC;AAoEM,SAAS,oBACd,MAAA,EACiC;AACjC,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,YAAA;AAAA,IACN,GAAG,aAAA;AAAA,IACH,OAAA,EAAS,OAAO,MAAA,KAA4B;AAC1C,MAAA,IAAI;AACF,QAAA,MAAM,WAAW,MAAMC,kCAAA;AAAA,UACrB;AAAA,YACE,OAAO,MAAA,CAAO,KAAA;AAAA,YACd,UAAA,EAAY,MAAA,CAAO,UAAA,IAAc,MAAA,CAAO,UAAA,IAAc,CAAA;AAAA,YACtD,WAAA,EAAa,MAAA,CAAO,WAAA,IAAe,MAAA,CAAO,WAAA,IAAe;AAAA,WAC3D;AAAA,UACA;AAAA,SACF;AAGA,QAAA,MAAM,SAAA,GAAYD,2CAAyB,QAAQ,CAAA;AAEnD,QAAA,OAAO;AAAA,UACL,OAAA,EAAS,IAAA;AAAA,UACT,OAAA,EAASE,yCAAuB,QAAQ,CAAA;AAAA,UACxC,IAAA,EAAM,QAAA;AAAA,UACN,UAAA,EAAY;AAAA,SACd;AAAA,MACF,SAAS,KAAA,EAAO;AACd,QAAA,MAAM,YAAA,GACJ,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,mBAAA;AAC3C,QAAA,OAAOC,0BAAQ,YAAY,CAAA;AAAA,MAC7B;AAAA,IACF;AAAA,GACF;AACF","file":"chunk-JKGFQUHJ.cjs","sourcesContent":["/**\n * Built-in Web Search Tool\n *\n * A pre-configured tool for searching the web with multiple provider support.\n * Runs on the server to protect API keys.\n *\n * Supports tree-shaking - import providers directly for smaller bundles.\n *\n * @example\n * ```typescript\n * // Option 1: String provider (lazy loaded at runtime)\n * import { createWebSearchTool } from '@yourgpt/copilot-sdk';\n * const webSearch = createWebSearchTool({\n *   provider: 'tavily',\n *   apiKey: process.env.TAVILY_API_KEY,\n * });\n *\n * // Option 2: Direct provider import (best for tree-shaking)\n * import { createWebSearchTool, tavilyProvider } from '@yourgpt/copilot-sdk';\n * const webSearch = createWebSearchTool({\n *   provider: tavilyProvider,\n *   apiKey: process.env.TAVILY_API_KEY,\n * });\n *\n * // Add to your runtime\n * const runtime = createRuntime({\n *   tools: [webSearch],\n * });\n * ```\n */\n\nimport { tool, success, failure } from \"../../types/tools\";\nimport type { ToolDefinition } from \"../../types/tools\";\nimport {\n  executeWebSearch,\n  formatSearchResultsForAI,\n  summarizeSearchResults,\n  type WebSearchConfigExtended,\n} from \"../webSearch\";\nimport type {\n  WebSearchConfig,\n  WebSearchParams,\n  WebSearchResponse,\n  WebSearchProviderInterface,\n} from \"../webSearch/types\";\n\n/**\n * Base web search tool definition\n *\n * This is the core tool definition. Use `createWebSearchTool()` to create\n * a configured instance with your provider settings.\n */\nexport const webSearchTool = tool<WebSearchParams>({\n  description: `Search the web for current information. Use this when the user asks about:\n- Recent events, news, or current affairs\n- Real-time data (prices, weather, stocks, sports scores)\n- Information that might have changed after your training cutoff\n- Facts that need verification with current sources\n- Research topics that require up-to-date information`,\n\n  location: \"server\", // Runs on server to protect API keys\n\n  title: (args) => `Searching for \"${args.query}\"`,\n  executingTitle: (args) => `Searching the web for \"${args.query}\"...`,\n  completedTitle: (args) => `Found results for \"${args.query}\"`,\n\n  inputSchema: {\n    type: \"object\",\n    properties: {\n      query: {\n        type: \"string\",\n        description: \"The search query to find relevant information\",\n      },\n      maxResults: {\n        type: \"number\",\n        description:\n          \"Maximum number of results to return (default: 5, max: 10)\",\n        minimum: 1,\n        maximum: 10,\n      },\n      searchDepth: {\n        type: \"string\",\n        enum: [\"basic\", \"advanced\"],\n        description:\n          \"Search depth - 'advanced' provides more thorough results but may be slower\",\n      },\n    },\n    required: [\"query\"],\n  },\n\n  needsApproval: false, // No user data exposed, just searching\n\n  // Control what AI sees from results\n  aiResponseMode: \"full\",\n  aiContext: (result, args) => {\n    if (!result.success) return `Search failed: ${result.error}`;\n    const data = result.data as WebSearchResponse;\n    return formatSearchResultsForAI(data);\n  },\n});\n\n/**\n * Create a configured web search tool\n *\n * Supports both string provider names (lazy loaded) and direct provider imports (tree-shakeable).\n *\n * @param config - Web search configuration including provider and API key\n * @returns A configured tool definition ready to use\n *\n * @example\n * ```typescript\n * // ===== BEST FOR TREE-SHAKING: Direct provider import =====\n * import { createWebSearchTool, openaiProvider } from '@yourgpt/copilot-sdk/core';\n *\n * const webSearch = createWebSearchTool({\n *   provider: openaiProvider, // Only this provider in bundle\n *   apiKey: process.env.OPENAI_API_KEY,\n * });\n *\n * // ===== STRING PROVIDERS (Lazy loaded at runtime) =====\n *\n * // OpenAI (uses your OpenAI API key)\n * const webSearch = createWebSearchTool({\n *   provider: 'openai',\n *   apiKey: process.env.OPENAI_API_KEY,\n * });\n *\n * // Google (uses your Google/Gemini API key)\n * const webSearch = createWebSearchTool({\n *   provider: 'google',\n *   apiKey: process.env.GOOGLE_API_KEY,\n * });\n *\n * // Tavily (AI-optimized search with answer generation)\n * const webSearch = createWebSearchTool({\n *   provider: 'tavily',\n *   apiKey: process.env.TAVILY_API_KEY,\n *   includeAnswer: true,\n *   maxResults: 5,\n * });\n *\n * // Serper (Google results)\n * const webSearch = createWebSearchTool({\n *   provider: 'serper',\n *   apiKey: process.env.SERPER_API_KEY,\n * });\n *\n * // Brave Search (privacy-focused)\n * const webSearch = createWebSearchTool({\n *   provider: 'brave',\n *   apiKey: process.env.BRAVE_API_KEY,\n * });\n *\n * // Self-hosted SearXNG (no API key needed)\n * const webSearch = createWebSearchTool({\n *   provider: 'searxng',\n *   baseUrl: 'https://your-searxng-instance.com',\n * });\n *\n * // Exa (AI-optimized semantic search)\n * const webSearch = createWebSearchTool({\n *   provider: 'exa',\n *   apiKey: process.env.EXA_API_KEY,\n *   searchDepth: 'advanced',\n * });\n * ```\n */\nexport function createWebSearchTool(\n  config: WebSearchConfigExtended,\n): ToolDefinition<WebSearchParams> {\n  return {\n    name: \"web_search\",\n    ...webSearchTool,\n    handler: async (params: WebSearchParams) => {\n      try {\n        const response = await executeWebSearch(\n          {\n            query: params.query,\n            maxResults: params.maxResults ?? config.maxResults ?? 5,\n            searchDepth: params.searchDepth ?? config.searchDepth ?? \"basic\",\n          },\n          config,\n        );\n\n        // Build the AI context string\n        const aiContext = formatSearchResultsForAI(response);\n\n        return {\n          success: true,\n          message: summarizeSearchResults(response),\n          data: response,\n          _aiContext: aiContext,\n        };\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : \"Web search failed\";\n        return failure(errorMessage);\n      }\n    },\n  };\n}\n\n/**\n * Utility types for web search tool configuration\n */\nexport type {\n  WebSearchConfig,\n  WebSearchParams,\n  WebSearchResponse,\n  WebSearchProviderInterface,\n};\nexport type { WebSearchConfigExtended };\n"]}
+{"version":3,"sources":["../src/core/tools/builtin/webSearch.ts"],"names":["tool","formatSearchResultsForAI","executeWebSearch","summarizeSearchResults","failure"],"mappings":";;;;;;AAoDO,IAAM,gBAAgBA,sBAAA,CAAsB;AAAA,EACjD,WAAA,EAAa,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qDAAA,CAAA;AAAA,EAOb,QAAA,EAAU,QAAA;AAAA;AAAA,EAEV,KAAA,EAAO,CAAC,IAAA,KAAS,CAAA,eAAA,EAAkB,KAAK,KAAK,CAAA,CAAA,CAAA;AAAA,EAC7C,cAAA,EAAgB,CAAC,IAAA,KAAS,CAAA,uBAAA,EAA0B,KAAK,KAAK,CAAA,IAAA,CAAA;AAAA,EAC9D,cAAA,EAAgB,CAAC,IAAA,KAAS,CAAA,mBAAA,EAAsB,KAAK,KAAK,CAAA,CAAA,CAAA;AAAA,EAE1D,WAAA,EAAa;AAAA,IACX,IAAA,EAAM,QAAA;AAAA,IACN,UAAA,EAAY;AAAA,MACV,KAAA,EAAO;AAAA,QACL,IAAA,EAAM,QAAA;AAAA,QACN,WAAA,EAAa;AAAA,OACf;AAAA,MACA,UAAA,EAAY;AAAA,QACV,IAAA,EAAM,QAAA;AAAA,QACN,WAAA,EACE,2DAAA;AAAA,QACF,OAAA,EAAS,CAAA;AAAA,QACT,OAAA,EAAS;AAAA,OACX;AAAA,MACA,WAAA,EAAa;AAAA,QACX,IAAA,EAAM,QAAA;AAAA,QACN,IAAA,EAAM,CAAC,OAAA,EAAS,UAAU,CAAA;AAAA,QAC1B,WAAA,EACE;AAAA;AACJ,KACF;AAAA,IACA,QAAA,EAAU,CAAC,OAAO;AAAA,GACpB;AAAA,EAEA,aAAA,EAAe,KAAA;AAAA;AAAA;AAAA,EAGf,cAAA,EAAgB,MAAA;AAAA,EAChB,SAAA,EAAW,CAAC,MAAA,EAAQ,IAAA,KAAS;AAC3B,IAAA,IAAI,CAAC,MAAA,CAAO,OAAA,EAAS,OAAO,CAAA,eAAA,EAAkB,OAAO,KAAK,CAAA,CAAA;AAC1D,IAAA,MAAM,OAAO,MAAA,CAAO,IAAA;AACpB,IAAA,OAAOC,2CAAyB,IAAI,CAAA;AAAA,EACtC;AACF,CAAC;AAoEM,SAAS,oBACd,MAAA,EACiC;AACjC,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,YAAA;AAAA,IACN,GAAG,aAAA;AAAA,IACH,OAAA,EAAS,OAAO,MAAA,KAA4B;AAC1C,MAAA,IAAI;AACF,QAAA,MAAM,WAAW,MAAMC,kCAAA;AAAA,UACrB;AAAA,YACE,OAAO,MAAA,CAAO,KAAA;AAAA,YACd,UAAA,EAAY,MAAA,CAAO,UAAA,IAAc,MAAA,CAAO,UAAA,IAAc,CAAA;AAAA,YACtD,WAAA,EAAa,MAAA,CAAO,WAAA,IAAe,MAAA,CAAO,WAAA,IAAe;AAAA,WAC3D;AAAA,UACA;AAAA,SACF;AAGA,QAAA,MAAM,SAAA,GAAYD,2CAAyB,QAAQ,CAAA;AAEnD,QAAA,OAAO;AAAA,UACL,OAAA,EAAS,IAAA;AAAA,UACT,OAAA,EAASE,yCAAuB,QAAQ,CAAA;AAAA,UACxC,IAAA,EAAM,QAAA;AAAA,UACN,UAAA,EAAY;AAAA,SACd;AAAA,MACF,SAAS,KAAA,EAAO;AACd,QAAA,MAAM,YAAA,GACJ,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,mBAAA;AAC3C,QAAA,OAAOC,0BAAQ,YAAY,CAAA;AAAA,MAC7B;AAAA,IACF;AAAA,GACF;AACF","file":"chunk-MDS23G2S.cjs","sourcesContent":["/**\n * Built-in Web Search Tool\n *\n * A pre-configured tool for searching the web with multiple provider support.\n * Runs on the server to protect API keys.\n *\n * Supports tree-shaking - import providers directly for smaller bundles.\n *\n * @example\n * ```typescript\n * // Option 1: String provider (lazy loaded at runtime)\n * import { createWebSearchTool } from '@yourgpt/copilot-sdk';\n * const webSearch = createWebSearchTool({\n *   provider: 'tavily',\n *   apiKey: process.env.TAVILY_API_KEY,\n * });\n *\n * // Option 2: Direct provider import (best for tree-shaking)\n * import { createWebSearchTool, tavilyProvider } from '@yourgpt/copilot-sdk';\n * const webSearch = createWebSearchTool({\n *   provider: tavilyProvider,\n *   apiKey: process.env.TAVILY_API_KEY,\n * });\n *\n * // Add to your runtime\n * const runtime = createRuntime({\n *   tools: [webSearch],\n * });\n * ```\n */\n\nimport { tool, success, failure } from \"../../types/tools\";\nimport type { ToolDefinition } from \"../../types/tools\";\nimport {\n  executeWebSearch,\n  formatSearchResultsForAI,\n  summarizeSearchResults,\n  type WebSearchConfigExtended,\n} from \"../webSearch\";\nimport type {\n  WebSearchConfig,\n  WebSearchParams,\n  WebSearchResponse,\n  WebSearchProviderInterface,\n} from \"../webSearch/types\";\n\n/**\n * Base web search tool definition\n *\n * This is the core tool definition. Use `createWebSearchTool()` to create\n * a configured instance with your provider settings.\n */\nexport const webSearchTool = tool<WebSearchParams>({\n  description: `Search the web for current information. Use this when the user asks about:\n- Recent events, news, or current affairs\n- Real-time data (prices, weather, stocks, sports scores)\n- Information that might have changed after your training cutoff\n- Facts that need verification with current sources\n- Research topics that require up-to-date information`,\n\n  location: \"server\", // Runs on server to protect API keys\n\n  title: (args) => `Searching for \"${args.query}\"`,\n  executingTitle: (args) => `Searching the web for \"${args.query}\"...`,\n  completedTitle: (args) => `Found results for \"${args.query}\"`,\n\n  inputSchema: {\n    type: \"object\",\n    properties: {\n      query: {\n        type: \"string\",\n        description: \"The search query to find relevant information\",\n      },\n      maxResults: {\n        type: \"number\",\n        description:\n          \"Maximum number of results to return (default: 5, max: 10)\",\n        minimum: 1,\n        maximum: 10,\n      },\n      searchDepth: {\n        type: \"string\",\n        enum: [\"basic\", \"advanced\"],\n        description:\n          \"Search depth - 'advanced' provides more thorough results but may be slower\",\n      },\n    },\n    required: [\"query\"],\n  },\n\n  needsApproval: false, // No user data exposed, just searching\n\n  // Control what AI sees from results\n  aiResponseMode: \"full\",\n  aiContext: (result, args) => {\n    if (!result.success) return `Search failed: ${result.error}`;\n    const data = result.data as WebSearchResponse;\n    return formatSearchResultsForAI(data);\n  },\n});\n\n/**\n * Create a configured web search tool\n *\n * Supports both string provider names (lazy loaded) and direct provider imports (tree-shakeable).\n *\n * @param config - Web search configuration including provider and API key\n * @returns A configured tool definition ready to use\n *\n * @example\n * ```typescript\n * // ===== BEST FOR TREE-SHAKING: Direct provider import =====\n * import { createWebSearchTool, openaiProvider } from '@yourgpt/copilot-sdk/core';\n *\n * const webSearch = createWebSearchTool({\n *   provider: openaiProvider, // Only this provider in bundle\n *   apiKey: process.env.OPENAI_API_KEY,\n * });\n *\n * // ===== STRING PROVIDERS (Lazy loaded at runtime) =====\n *\n * // OpenAI (uses your OpenAI API key)\n * const webSearch = createWebSearchTool({\n *   provider: 'openai',\n *   apiKey: process.env.OPENAI_API_KEY,\n * });\n *\n * // Google (uses your Google/Gemini API key)\n * const webSearch = createWebSearchTool({\n *   provider: 'google',\n *   apiKey: process.env.GOOGLE_API_KEY,\n * });\n *\n * // Tavily (AI-optimized search with answer generation)\n * const webSearch = createWebSearchTool({\n *   provider: 'tavily',\n *   apiKey: process.env.TAVILY_API_KEY,\n *   includeAnswer: true,\n *   maxResults: 5,\n * });\n *\n * // Serper (Google results)\n * const webSearch = createWebSearchTool({\n *   provider: 'serper',\n *   apiKey: process.env.SERPER_API_KEY,\n * });\n *\n * // Brave Search (privacy-focused)\n * const webSearch = createWebSearchTool({\n *   provider: 'brave',\n *   apiKey: process.env.BRAVE_API_KEY,\n * });\n *\n * // Self-hosted SearXNG (no API key needed)\n * const webSearch = createWebSearchTool({\n *   provider: 'searxng',\n *   baseUrl: 'https://your-searxng-instance.com',\n * });\n *\n * // Exa (AI-optimized semantic search)\n * const webSearch = createWebSearchTool({\n *   provider: 'exa',\n *   apiKey: process.env.EXA_API_KEY,\n *   searchDepth: 'advanced',\n * });\n * ```\n */\nexport function createWebSearchTool(\n  config: WebSearchConfigExtended,\n): ToolDefinition<WebSearchParams> {\n  return {\n    name: \"web_search\",\n    ...webSearchTool,\n    handler: async (params: WebSearchParams) => {\n      try {\n        const response = await executeWebSearch(\n          {\n            query: params.query,\n            maxResults: params.maxResults ?? config.maxResults ?? 5,\n            searchDepth: params.searchDepth ?? config.searchDepth ?? \"basic\",\n          },\n          config,\n        );\n\n        // Build the AI context string\n        const aiContext = formatSearchResultsForAI(response);\n\n        return {\n          success: true,\n          message: summarizeSearchResults(response),\n          data: response,\n          _aiContext: aiContext,\n        };\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : \"Web search failed\";\n        return failure(errorMessage);\n      }\n    },\n  };\n}\n\n/**\n * Utility types for web search tool configuration\n */\nexport type {\n  WebSearchConfig,\n  WebSearchParams,\n  WebSearchResponse,\n  WebSearchProviderInterface,\n};\nexport type { WebSearchConfigExtended };\n"]}

package/dist/{chunk-6BMQZIS3.js → chunk-PT2TOHG5.js}

@@ -1,4 +1,4 @@
-import { ThreadManager, createLogger, zodToJsonSchema, isConsoleCaptureActive, startConsoleCapture, isNetworkCaptureActive, startNetworkCapture, stopConsoleCapture, stopNetworkCapture, isScreenshotSupported, captureScreenshot, getConsoleLogs, getNetworkRequests, clearConsoleLogs, clearNetworkRequests, formatLogsForAI, formatRequestsForAI, detectIntent, streamSSE, zodObjectToInputSchema } from './chunk-UXJ6LIZB.js';
+import { ThreadManager, createLogger, zodToJsonSchema, isConsoleCaptureActive, startConsoleCapture, isNetworkCaptureActive, startNetworkCapture, stopConsoleCapture, stopNetworkCapture, isScreenshotSupported, captureScreenshot, getConsoleLogs, getNetworkRequests, clearConsoleLogs, clearNetworkRequests, formatLogsForAI, formatRequestsForAI, detectIntent, streamSSE, zodObjectToInputSchema } from './chunk-WZ2TOZ7M.js';
 import { createMCPClient, MCPToolAdapter } from './chunk-EWVQWTNV.js';
 import { SkillRegistry } from './chunk-VNLLW3ZI.js';
 import React2, { createContext, useRef, useState, useCallback, useEffect, useMemo, useContext, useSyncExternalStore } from 'react';
@@ -1622,18 +1622,23 @@ var AbstractChat = class {
         "resolveUnresolvedToolCalls",
         `Adding ${unresolvedIds.length} missing tool results`
       );
+      const visibleMsgs = this.state.messages;
+      let errorChainParentId = visibleMsgs.length > 0 ? visibleMsgs[visibleMsgs.length - 1].id : void 0;
       for (const toolCallId of unresolvedIds) {
+        const toolMessageId = generateMessageId();
         const toolMessage = {
-          id: generateMessageId(),
+          id: toolMessageId,
           role: "tool",
           content: JSON.stringify({
             success: false,
             error: "Tool execution was interrupted. Please try again."
           }),
           toolCallId,
-          createdAt: /* @__PURE__ */ new Date()
+          createdAt: /* @__PURE__ */ new Date(),
+          ...errorChainParentId !== void 0 ? { parentId: errorChainParentId } : {}
         };
         this.state.pushMessage(toolMessage);
+        errorChainParentId = toolMessageId;
       }
       this.callbacks.onMessagesChange?.(this._allMessages());
     }
@@ -1649,6 +1654,8 @@ var AbstractChat = class {
     this.debug("continueWithToolResults", toolResults);
     try {
       const attachmentsToAdd = [];
+      const visibleMessages = this.state.messages;
+      let chainParentId = visibleMessages.length > 0 ? visibleMessages[visibleMessages.length - 1].id : void 0;
       for (const { toolCallId, result } of toolResults) {
         const typedResult = result;
         let messageContent;
@@ -1665,14 +1672,17 @@ var AbstractChat = class {
         } else {
           messageContent = typeof result === "string" ? result : JSON.stringify(result);
         }
+        const toolMessageId = generateMessageId();
         const toolMessage = {
-          id: generateMessageId(),
+          id: toolMessageId,
           role: "tool",
           content: messageContent,
           toolCallId,
-          createdAt: /* @__PURE__ */ new Date()
+          createdAt: /* @__PURE__ */ new Date(),
+          ...chainParentId !== void 0 ? { parentId: chainParentId } : {}
         };
         this.state.pushMessage(toolMessage);
+        chainParentId = toolMessageId;
       }
       if (attachmentsToAdd.length > 0) {
         this.debug(
@@ -1684,7 +1694,8 @@ var AbstractChat = class {
           role: "user",
           content: "Here's my screen:",
           attachments: attachmentsToAdd,
-          createdAt: /* @__PURE__ */ new Date()
+          createdAt: /* @__PURE__ */ new Date(),
+          ...chainParentId !== void 0 ? { parentId: chainParentId } : {}
         };
         this.state.pushMessage(userMessage);
       }
@@ -2657,11 +2668,14 @@ var AbstractAgentLoop = class {
     }
     let approvalData;
     if (tool2.needsApproval && !this.config.autoApprove) {
+      const approvalTitle = typeof tool2.approvalTitle === "function" ? tool2.approvalTitle(toolCall.args) : tool2.approvalTitle;
       const approvalMessage = typeof tool2.approvalMessage === "function" ? tool2.approvalMessage(toolCall.args) : tool2.approvalMessage;
       execution.approvalStatus = "required";
+      execution.approvalTitle = approvalTitle;
       execution.approvalMessage = approvalMessage;
       this.updateToolExecution(toolCall.id, {
         approvalStatus: "required",
+        approvalTitle,
         approvalMessage
       });
       this.callbacks.onApprovalRequired?.(execution);
@@ -4834,6 +4848,7 @@ function useTool(config, dependencies = []) {
       render: config.render,
       available: config.available ?? true,
       needsApproval: config.needsApproval,
+      approvalTitle: config.approvalTitle,
       approvalMessage: config.approvalMessage,
       hidden: config.hidden,
       deferLoading: config.deferLoading,
@@ -7408,5 +7423,5 @@ function defineSkill(def) {
 }
 
 export { AbstractAgentLoop, AbstractChat, CopilotProvider, MessageHistoryContext, MessageTree, ReactChat, ReactChatState, ReactThreadManager, ReactThreadManagerState, SkillProvider, createMessageIntentHandler, createPermissionStorage, createReactChat, createReactChatState, createReactThreadManager, createReactThreadManagerState, createSessionPermissionCache, createToolIntentHandler, defaultMessageHistoryConfig, defineSkill, formatKnowledgeResultsForAI, initialAgentLoopState, isCompactionMarker, keepToolPairsAtomic, searchKnowledgeBase, toDisplayMessage, toLLMMessage, toLLMMessages, useAIAction, useAIActions, useAIContext, useAIContexts, useAITools, useAgent, useCapabilities, useChat, useContextStats, useCopilot, useDevLogger, useFeatureSupport, useKnowledgeBase, useMCPClient, useMCPTools, useMCPUIIntents, useMessageHistory, useMessageHistoryContext, useSkill, useSkillStatus, useSuggestions, useSupportedMediaTypes, useThreadManager, useTool, useToolExecutor, useToolWithSchema, useTools, useToolsWithSchema };
-//# sourceMappingURL=chunk-6BMQZIS3.js.map
-//# sourceMappingURL=chunk-6BMQZIS3.js.map
+//# sourceMappingURL=chunk-PT2TOHG5.js.map
+//# sourceMappingURL=chunk-PT2TOHG5.js.map