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

package/dist/MessageTree-CoIt_4nB.d.cts

@@ -0,0 +1,161 @@
+import { M as MessageAttachment, T as ToolCall, S as Source } from './types-BeFBBZ5i.cjs';
+
+/**
+ * Message Types
+ *
+ * Pure type definitions for chat messages.
+ * No logic, no side effects - just types.
+ */
+
+/**
+ * Chat message roles
+ */
+type MessageRole = "user" | "assistant" | "system" | "tool";
+/**
+ * UIMessage - The source of truth for UI state
+ *
+ * Inspired by Vercel AI SDK's UIMessage pattern.
+ * This is what your UI renders and what gets persisted.
+ */
+interface UIMessage {
+    /** Unique message ID */
+    id: string;
+    /** Message role */
+    role: MessageRole;
+    /** Message content */
+    content: string;
+    /** Thinking/reasoning content (for extended thinking models) */
+    thinking?: string;
+    /** Message attachments (images, PDFs, etc) */
+    attachments?: MessageAttachment[];
+    /** Tool calls made by assistant */
+    toolCalls?: ToolCall[];
+    /** Tool call ID (for tool result messages) */
+    toolCallId?: string;
+    /** Sources from knowledge base */
+    sources?: Source[];
+    /** Creation timestamp */
+    createdAt: Date;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /**
+     * Parent message ID for branching support.
+     * - null = root message (no parent)
+     * - undefined = legacy linear message (no branch awareness)
+     * - string = ID of parent message
+     */
+    parentId?: string | null;
+    /** Direct children IDs for O(1) sibling lookup */
+    childrenIds?: string[];
+}
+
+/**
+ * MessageTree — Bidirectional flat-map message tree for conversation branching.
+ *
+ * Industry-standard data structure used by ChatGPT, Claude.ai, and Gemini:
+ * - parentId + childrenIds[] for O(1) navigation
+ * - activeChildMap tracks the active path through the tree
+ *
+ * Zero React dependency — pure TypeScript, works in any environment.
+ */
+
+/**
+ * Branch navigation info for the UI navigator (← N/M →)
+ */
+interface BranchInfo {
+    /** 0-based index of this message among its siblings */
+    siblingIndex: number;
+    /** Total number of sibling variants at this fork */
+    totalSiblings: number;
+    /** Ordered IDs of all siblings (oldest-first) */
+    siblingIds: string[];
+    hasPrevious: boolean;
+    hasNext: boolean;
+}
+declare class MessageTree<T extends UIMessage = UIMessage> {
+    /** All messages by ID */
+    private nodeMap;
+    /** parentKey → ordered list of child IDs (insertion order = oldest-first) */
+    private childrenOf;
+    /** parentKey → currently-active child ID */
+    private activeChildMap;
+    /** Current leaf message ID (tip of the active path) */
+    private _currentLeafId;
+    /** Cached visible messages — invalidated on every mutation */
+    private _visibleCache;
+    /** Sentinel key used for root-level messages (parentId === null) */
+    static readonly ROOT_KEY = "__root__";
+    constructor(messages?: T[]);
+    /**
+     * Convert a legacy flat array (no parentId) to a tree-linked array.
+     *
+     * Rules:
+     * - Tool messages get parentId = the owning assistant message's id
+     *   (matched via toolCallId → toolCall.id).
+     * - All other messages get parentId of the previous non-tool message
+     *   (or null for the first message).
+     *
+     * Returns a new array with parentId/childrenIds filled in.
+     * Does NOT mutate the original messages.
+     */
+    static fromFlatArray<T extends UIMessage>(messages: T[]): T[];
+    /**
+     * Returns the visible path (root → current leaf) — what the UI renders
+     * and what gets sent to the API.
+     *
+     * Backward-compat: if NO message has parentId set (all undefined),
+     * falls back to insertion order (legacy linear mode).
+     */
+    getVisibleMessages(): T[];
+    private _invalidateCache;
+    /**
+     * Returns ALL messages across every branch (for persistence / ThreadManager).
+     */
+    getAllMessages(): T[];
+    /**
+     * Branch navigation info for the UI navigator.
+     * Returns null if the message has no siblings (only child).
+     */
+    getBranchInfo(messageId: string): BranchInfo | null;
+    get currentLeafId(): string | null;
+    get hasBranches(): boolean;
+    /**
+     * Insert a new message.
+     * - Updates childrenOf and nodeMap.
+     * - New branch becomes active (activeChildMap updated).
+     * - Updates current leaf.
+     */
+    addMessage(message: T): T;
+    /**
+     * Navigate: make messageId the active child at its parent fork,
+     * then walk to its leaf and update currentLeafId.
+     */
+    switchBranch(messageId: string): void;
+    /**
+     * Update message content in-place (streaming updates).
+     * No tree structure change.
+     */
+    updateMessage(id: string, updater: (msg: T) => T): boolean;
+    /**
+     * Set current leaf explicitly.
+     * Used by regenerate() to rewind the active path before pushing a new message.
+     */
+    setCurrentLeaf(leafId: string | null): void;
+    /**
+     * Rebuild entire tree from a message array.
+     * Used by setMessages().
+     */
+    reset(messages: T[]): void;
+    private _buildFromMessages;
+    private _parentKey;
+    /**
+     * Walk forward from a message along active children to find the leaf.
+     */
+    private _walkToLeaf;
+    /**
+     * Walk the active path from root to the current leaf.
+     */
+    private _getActivePath;
+}
+
+export { type BranchInfo as B, MessageTree as M, type UIMessage as U };

package/dist/MessageTree-CzaN9Eul.d.ts

@@ -0,0 +1,161 @@
+import { M as MessageAttachment, T as ToolCall, S as Source } from './types-BeFBBZ5i.js';
+
+/**
+ * Message Types
+ *
+ * Pure type definitions for chat messages.
+ * No logic, no side effects - just types.
+ */
+
+/**
+ * Chat message roles
+ */
+type MessageRole = "user" | "assistant" | "system" | "tool";
+/**
+ * UIMessage - The source of truth for UI state
+ *
+ * Inspired by Vercel AI SDK's UIMessage pattern.
+ * This is what your UI renders and what gets persisted.
+ */
+interface UIMessage {
+    /** Unique message ID */
+    id: string;
+    /** Message role */
+    role: MessageRole;
+    /** Message content */
+    content: string;
+    /** Thinking/reasoning content (for extended thinking models) */
+    thinking?: string;
+    /** Message attachments (images, PDFs, etc) */
+    attachments?: MessageAttachment[];
+    /** Tool calls made by assistant */
+    toolCalls?: ToolCall[];
+    /** Tool call ID (for tool result messages) */
+    toolCallId?: string;
+    /** Sources from knowledge base */
+    sources?: Source[];
+    /** Creation timestamp */
+    createdAt: Date;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /**
+     * Parent message ID for branching support.
+     * - null = root message (no parent)
+     * - undefined = legacy linear message (no branch awareness)
+     * - string = ID of parent message
+     */
+    parentId?: string | null;
+    /** Direct children IDs for O(1) sibling lookup */
+    childrenIds?: string[];
+}
+
+/**
+ * MessageTree — Bidirectional flat-map message tree for conversation branching.
+ *
+ * Industry-standard data structure used by ChatGPT, Claude.ai, and Gemini:
+ * - parentId + childrenIds[] for O(1) navigation
+ * - activeChildMap tracks the active path through the tree
+ *
+ * Zero React dependency — pure TypeScript, works in any environment.
+ */
+
+/**
+ * Branch navigation info for the UI navigator (← N/M →)
+ */
+interface BranchInfo {
+    /** 0-based index of this message among its siblings */
+    siblingIndex: number;
+    /** Total number of sibling variants at this fork */
+    totalSiblings: number;
+    /** Ordered IDs of all siblings (oldest-first) */
+    siblingIds: string[];
+    hasPrevious: boolean;
+    hasNext: boolean;
+}
+declare class MessageTree<T extends UIMessage = UIMessage> {
+    /** All messages by ID */
+    private nodeMap;
+    /** parentKey → ordered list of child IDs (insertion order = oldest-first) */
+    private childrenOf;
+    /** parentKey → currently-active child ID */
+    private activeChildMap;
+    /** Current leaf message ID (tip of the active path) */
+    private _currentLeafId;
+    /** Cached visible messages — invalidated on every mutation */
+    private _visibleCache;
+    /** Sentinel key used for root-level messages (parentId === null) */
+    static readonly ROOT_KEY = "__root__";
+    constructor(messages?: T[]);
+    /**
+     * Convert a legacy flat array (no parentId) to a tree-linked array.
+     *
+     * Rules:
+     * - Tool messages get parentId = the owning assistant message's id
+     *   (matched via toolCallId → toolCall.id).
+     * - All other messages get parentId of the previous non-tool message
+     *   (or null for the first message).
+     *
+     * Returns a new array with parentId/childrenIds filled in.
+     * Does NOT mutate the original messages.
+     */
+    static fromFlatArray<T extends UIMessage>(messages: T[]): T[];
+    /**
+     * Returns the visible path (root → current leaf) — what the UI renders
+     * and what gets sent to the API.
+     *
+     * Backward-compat: if NO message has parentId set (all undefined),
+     * falls back to insertion order (legacy linear mode).
+     */
+    getVisibleMessages(): T[];
+    private _invalidateCache;
+    /**
+     * Returns ALL messages across every branch (for persistence / ThreadManager).
+     */
+    getAllMessages(): T[];
+    /**
+     * Branch navigation info for the UI navigator.
+     * Returns null if the message has no siblings (only child).
+     */
+    getBranchInfo(messageId: string): BranchInfo | null;
+    get currentLeafId(): string | null;
+    get hasBranches(): boolean;
+    /**
+     * Insert a new message.
+     * - Updates childrenOf and nodeMap.
+     * - New branch becomes active (activeChildMap updated).
+     * - Updates current leaf.
+     */
+    addMessage(message: T): T;
+    /**
+     * Navigate: make messageId the active child at its parent fork,
+     * then walk to its leaf and update currentLeafId.
+     */
+    switchBranch(messageId: string): void;
+    /**
+     * Update message content in-place (streaming updates).
+     * No tree structure change.
+     */
+    updateMessage(id: string, updater: (msg: T) => T): boolean;
+    /**
+     * Set current leaf explicitly.
+     * Used by regenerate() to rewind the active path before pushing a new message.
+     */
+    setCurrentLeaf(leafId: string | null): void;
+    /**
+     * Rebuild entire tree from a message array.
+     * Used by setMessages().
+     */
+    reset(messages: T[]): void;
+    private _buildFromMessages;
+    private _parentKey;
+    /**
+     * Walk forward from a message along active children to find the leaf.
+     */
+    private _walkToLeaf;
+    /**
+     * Walk the active path from root to the current leaf.
+     */
+    private _getActivePath;
+}
+
+export { type BranchInfo as B, MessageTree as M, type UIMessage as U };

package/dist/{ThreadManager-Dkp_eLty.d.ts → ThreadManager-BEAECB7Y.d.ts}

@@ -1,4 +1,4 @@
-import { T as Thread, a as ThreadData, b as ThreadStorageAdapter, A as AsyncThreadStorageAdapter, M as Message } from './types-DG2ya08y.js';
+import { a as Thread, b as ThreadData, c as ThreadStorageAdapter, A as AsyncThreadStorageAdapter, d as Message } from './types-BeFBBZ5i.js';
 
 /**
  * Tool types for App Context Awareness

package/dist/{ThreadManager-LfFRhr4e.d.cts → ThreadManager-Cw5fwyCN.d.cts}

@@ -1,4 +1,4 @@
-import { T as Thread, a as ThreadData, b as ThreadStorageAdapter, A as AsyncThreadStorageAdapter, M as Message } from './types-DG2ya08y.cjs';
+import { a as Thread, b as ThreadData, c as ThreadStorageAdapter, A as AsyncThreadStorageAdapter, d as Message } from './types-BeFBBZ5i.cjs';
 
 /**
  * Tool types for App Context Awareness

package/dist/{chunk-POZNNKNJ.cjs → chunk-246B6X5D.cjs}

@@ -5,6 +5,12 @@ function tool(config) {
   return {
     description: config.description,
     location: config.location ?? "client",
+    category: config.category,
+    group: config.group,
+    deferLoading: config.deferLoading,
+    profiles: config.profiles,
+    searchKeywords: config.searchKeywords,
+    resultConfig: config.resultConfig,
     // Display configuration
     title: config.title,
     executingTitle: config.executingTitle,
@@ -70,5 +76,5 @@ exports.success = success;
 exports.tool = tool;
 exports.toolToAnthropicFormat = toolToAnthropicFormat;
 exports.toolToOpenAIFormat = toolToOpenAIFormat;
-//# sourceMappingURL=chunk-POZNNKNJ.cjs.map
-//# sourceMappingURL=chunk-POZNNKNJ.cjs.map
+//# sourceMappingURL=chunk-246B6X5D.cjs.map
+//# sourceMappingURL=chunk-246B6X5D.cjs.map

package/dist/chunk-246B6X5D.cjs.map

@@ -0,0 +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-246B6X5D.cjs","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"]}

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

@@ -3,6 +3,12 @@ function tool(config) {
   return {
     description: config.description,
     location: config.location ?? "client",
+    category: config.category,
+    group: config.group,
+    deferLoading: config.deferLoading,
+    profiles: config.profiles,
+    searchKeywords: config.searchKeywords,
+    resultConfig: config.resultConfig,
     // Display configuration
     title: config.title,
     executingTitle: config.executingTitle,
@@ -63,5 +69,5 @@ function failure(error) {
 }
 
 export { createToolResult, failure, success, tool, toolToAnthropicFormat, toolToOpenAIFormat };
-//# sourceMappingURL=chunk-QLH6TSCC.js.map
-//# sourceMappingURL=chunk-QLH6TSCC.js.map
+//# sourceMappingURL=chunk-4QXY2PBG.js.map
+//# sourceMappingURL=chunk-4QXY2PBG.js.map

package/dist/chunk-4QXY2PBG.js.map

@@ -0,0 +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"]}