@yourgpt/copilot-sdk 0.1.0 → 1.0.0

package/dist/react/index.d.ts

@@ -1,7 +1,52 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React__default from 'react';
-import { M as MessageAttachment, A as ToolCall, f as Source, D as LLMConfig, T as ToolDefinition, af as PermissionLevel, i as ToolInputSchema, G as CopilotConfig, s as ToolsConfig, y as Message, O as ActionDefinition, v as CapturedContext, t as ToolConsentRequest, r as ToolType, aa as ToolExecution$1, u as ToolConsentResponse, S as ScreenshotOptions, C as ConsoleLogOptions, N as NetworkRequestOptions, I as IntentDetectionResult, k as ToolContext, h as ToolResponse$1, a4 as ToolRenderProps, a6 as ToolSet, a7 as UnifiedToolCall, Y as InternalKnowledgeBaseConfig, _ as InternalKnowledgeBaseSearchResponse, Z as InternalKnowledgeBaseResult, ah as PermissionStorageConfig, ai as PermissionStorageAdapter } from '../thread-C2FjuGLb.js';
-export { K as ActionParameter, ab as AgentLoopConfig, E as CloudConfig, a1 as PersistenceConfig, $ as Thread, a0 as ThreadData, a2 as ThreadStorageAdapter, g as ToolExecutionStatus, ag as ToolPermission, o as generateSuggestionReason } from '../thread-C2FjuGLb.js';
+import { q as LLMConfig, s as CopilotConfig, l as ToolsConfig, t as ActionDefinition, o as CapturedContext, m as ToolConsentRequest, T as ToolType, n as ToolConsentResponse, S as ScreenshotOptions, C as ConsoleLogOptions, N as NetworkRequestOptions, I as IntentDetectionResult, z as InternalKnowledgeBaseConfig, D as InternalKnowledgeBaseSearchResponse, B as InternalKnowledgeBaseResult, $ as ThreadManagerState, a0 as LoadStatus, X as ThreadManagerConfig, M as ThreadManager, Y as ThreadManagerCallbacks, Z as CreateThreadOptions, _ as UpdateThreadOptions } from '../ThreadManager-BjC15mh8.js';
+export { A as ActionParameter, r as CloudConfig, a1 as LocalStorageAdapterConfig, Q as createLocalStorageAdapter, U as createMemoryAdapter, i as generateSuggestionReason } from '../ThreadManager-BjC15mh8.js';
+import { X as AsyncThreadStorageAdapter, M as MessageAttachment, i as ToolCall, S as Source, T as ToolDefinition, x as PermissionLevel, c as ToolInputSchema, g as Message, s as ToolExecution$1, e as ToolContext, b as ToolResponse$1, n as ToolRenderProps, p as ToolSet, U as UnifiedToolCall, k as Thread, l as ThreadData, _ as ThreadStorageAdapter, z as PermissionStorageConfig, B as PermissionStorageAdapter } from '../types-BtAaOV07.js';
+export { t as AgentLoopConfig, P as PersistenceConfig, m as ThreadStorageAdapter, a as ToolExecutionStatus, y as ToolPermission } from '../types-BtAaOV07.js';
+
+/**
+ * Server Thread Storage Adapter
+ *
+ * Fetches threads from a user-provided API endpoint.
+ * Implements AsyncThreadStorageAdapter for optimized single-thread operations.
+ */
+
+/**
+ * Configuration for server adapter
+ */
+interface ServerAdapterConfig {
+    /**
+     * Endpoint URL for thread API
+     * @example "/api/threads"
+     */
+    endpoint: string;
+    /**
+     * Additional headers to include in requests (e.g., auth tokens)
+     */
+    headers?: Record<string, string>;
+    /**
+     * Custom fetch function (useful for testing or adding interceptors)
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Create a server-based thread storage adapter
+ *
+ * @example
+ * ```typescript
+ * const adapter = createServerAdapter({
+ *   threadsUrl: "/api/threads",
+ *   headers: {
+ *     Authorization: `Bearer ${token}`,
+ *   },
+ * });
+ *
+ * const { threads } = useThreadManager({ adapter });
+ * ```
+ */
+declare function createServerAdapter(config: ServerAdapterConfig): AsyncThreadStorageAdapter;
 
 /**
  * Message Types
@@ -339,6 +384,10 @@ interface ToolExecution {
     error?: string;
     startedAt?: Date;
     completedAt?: Date;
+    /** Custom approval message from tool definition */
+    approvalMessage?: string;
+    /** Data passed from user's approval action (e.g., selected supervisor) */
+    approvalData?: Record<string, unknown>;
 }
 /**
  * Tool response
@@ -393,7 +442,22 @@ interface AgentLoopState$1 {
  * Agent loop actions interface
  */
 interface AgentLoopActions {
-    approveToolExecution: (executionId: string, permissionLevel?: PermissionLevel) => void;
+    /**
+     * Approve a tool execution with optional extra data.
+     * The extraData is passed to the tool handler via context.approvalData.
+     *
+     * @param executionId - The tool execution ID
+     * @param extraData - Optional data from user's approval action (e.g., selected item)
+     * @param permissionLevel - Optional permission level for persistence
+     */
+    approveToolExecution: (executionId: string, extraData?: Record<string, unknown>, permissionLevel?: PermissionLevel) => void;
+    /**
+     * Reject a tool execution.
+     *
+     * @param executionId - The tool execution ID
+     * @param reason - Optional rejection reason
+     * @param permissionLevel - Optional permission level for persistence
+     */
     rejectToolExecution: (executionId: string, reason?: string, permissionLevel?: PermissionLevel) => void;
     clearToolExecutions: () => void;
 }
@@ -639,12 +703,13 @@ declare class AbstractAgentLoop implements AgentLoopActions {
     private executeSingleTool;
     /**
      * Wait for user approval
+     * Returns approval result with optional extraData from user's action
      */
     private waitForApproval;
     /**
-     * Approve a tool execution
+     * Approve a tool execution with optional extra data
      */
-    approveToolExecution(executionId: string, _permissionLevel?: PermissionLevel): void;
+    approveToolExecution(executionId: string, extraData?: Record<string, unknown>, _permissionLevel?: PermissionLevel): void;
     /**
      * Reject a tool execution
      */
@@ -695,13 +760,14 @@ interface CopilotContextValue {
     sendMessage: (content: string, attachments?: MessageAttachment[]) => Promise<void>;
     stop: () => void;
     clearMessages: () => void;
+    setMessages: (messages: UIMessage[]) => void;
     regenerate: (messageId?: string) => Promise<void>;
     registerTool: (tool: ToolDefinition) => void;
     unregisterTool: (name: string) => void;
     registeredTools: ToolDefinition[];
     toolExecutions: ToolExecution[];
     pendingApprovals: ToolExecution[];
-    approveToolExecution: (id: string, permissionLevel?: PermissionLevel) => void;
+    approveToolExecution: (id: string, extraData?: Record<string, unknown>, permissionLevel?: PermissionLevel) => void;
     rejectToolExecution: (id: string, reason?: string, permissionLevel?: PermissionLevel) => void;
     registerAction: (action: ActionDefinition) => void;
     unregisterAction: (name: string) => void;
@@ -1588,6 +1654,328 @@ interface DevLoggerState {
  */
 declare function useDevLogger(): DevLoggerState;
 
+/**
+ * ReactThreadManagerState - React-specific implementation of ThreadManagerState
+ *
+ * This class implements the ThreadManagerState interface with callback-based
+ * reactivity for use with React's useSyncExternalStore.
+ *
+ * Pattern follows ReactChatState for consistency.
+ */
+
+/**
+ * ReactThreadManagerState implements ThreadManagerState with callback-based reactivity
+ *
+ * @example
+ * ```tsx
+ * const state = new ReactThreadManagerState();
+ *
+ * // Subscribe to changes (for useSyncExternalStore)
+ * const unsubscribe = state.subscribe(() => {
+ *   console.log('State changed');
+ * });
+ *
+ * // Get snapshot (for useSyncExternalStore)
+ * const threads = state.threads;
+ * ```
+ */
+declare class ReactThreadManagerState implements ThreadManagerState {
+    private _threads;
+    private _currentThreadId;
+    private _currentThread;
+    private _loadStatus;
+    private _error;
+    private subscribers;
+    constructor(initialThreads?: Thread[]);
+    get threads(): Thread[];
+    get currentThreadId(): string | null;
+    get currentThread(): ThreadData | null;
+    get loadStatus(): LoadStatus;
+    get error(): Error | undefined;
+    set threads(value: Thread[]);
+    setThreads(threads: Thread[]): void;
+    setCurrentThread(thread: ThreadData | null): void;
+    setCurrentThreadId(id: string | null): void;
+    addThread(thread: Thread): void;
+    updateThread(id: string, updates: Partial<Thread>): void;
+    removeThread(id: string): void;
+    setLoadStatus(status: LoadStatus): void;
+    setError(error: Error | undefined): void;
+    /**
+     * Subscribe to state changes.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * ```tsx
+     * const threads = useSyncExternalStore(
+     *   state.subscribe,
+     *   () => state.threads
+     * );
+     * ```
+     */
+    subscribe: (callback: () => void) => (() => void);
+    getThreadsSnapshot(): Thread[];
+    getCurrentThreadSnapshot(): ThreadData | null;
+    getLoadStatusSnapshot(): LoadStatus;
+    getErrorSnapshot(): Error | undefined;
+    private notify;
+    /**
+     * Cleanup subscriptions
+     */
+    dispose(): void;
+}
+/**
+ * Create a ReactThreadManagerState instance
+ */
+declare function createReactThreadManagerState(initialThreads?: Thread[]): ReactThreadManagerState;
+
+/**
+ * ReactThreadManager - React adapter for ThreadManager
+ *
+ * Extends ThreadManager with React-specific state management.
+ */
+
+/**
+ * Configuration for ReactThreadManager
+ */
+interface ReactThreadManagerConfig extends Omit<ThreadManagerConfig, "state"> {
+}
+/**
+ * ReactThreadManager - React adapter for ThreadManager
+ *
+ * Uses ReactThreadManagerState for React's useSyncExternalStore compatibility.
+ *
+ * @example
+ * ```tsx
+ * const manager = createReactThreadManager();
+ *
+ * // In a component using useSyncExternalStore
+ * const threads = useSyncExternalStore(
+ *   manager.subscribe,
+ *   manager.getThreadsSnapshot
+ * );
+ * ```
+ */
+declare class ReactThreadManager extends ThreadManager {
+    protected state: ReactThreadManagerState;
+    constructor(config?: ReactThreadManagerConfig, callbacks?: ThreadManagerCallbacks);
+    /**
+     * Subscribe to state changes
+     * Use with useSyncExternalStore
+     */
+    subscribe: (callback: () => void) => (() => void);
+    /**
+     * Get threads snapshot
+     */
+    getThreadsSnapshot: () => typeof this.threads;
+    /**
+     * Get current thread snapshot
+     */
+    getCurrentThreadSnapshot: () => typeof this.currentThread;
+    /**
+     * Get current thread ID snapshot
+     */
+    getCurrentThreadIdSnapshot: () => string | null;
+    /**
+     * Get load status snapshot
+     */
+    getLoadStatusSnapshot: () => typeof this.loadStatus;
+    /**
+     * Get error snapshot
+     */
+    getErrorSnapshot: () => typeof this.error;
+    /**
+     * Get isLoading snapshot
+     */
+    getIsLoadingSnapshot: () => boolean;
+    private static readonly EMPTY_THREADS;
+    private static readonly IDLE_STATUS;
+    /**
+     * Get threads snapshot for server (always empty for hydration consistency)
+     */
+    getThreadsServerSnapshot: () => Thread[];
+    /**
+     * Get current thread snapshot for server (always null)
+     */
+    getCurrentThreadServerSnapshot: () => typeof this.currentThread;
+    /**
+     * Get current thread ID snapshot for server (always null)
+     */
+    getCurrentThreadIdServerSnapshot: () => string | null;
+    /**
+     * Get load status snapshot for server (always "idle")
+     */
+    getLoadStatusServerSnapshot: () => typeof this.loadStatus;
+    /**
+     * Get error snapshot for server (always undefined)
+     */
+    getErrorServerSnapshot: () => typeof this.error;
+    /**
+     * Get isLoading snapshot for server (always false)
+     */
+    getIsLoadingServerSnapshot: () => boolean;
+    /**
+     * Dispose of the manager
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Create a ReactThreadManager instance
+ */
+declare function createReactThreadManager(config?: ReactThreadManagerConfig, callbacks?: ThreadManagerCallbacks): ReactThreadManager;
+
+/**
+ * useThreadManager - React hook for thread management
+ *
+ * Provides thread CRUD operations with localStorage persistence by default.
+ * Uses useSyncExternalStore for optimal React integration.
+ */
+
+/**
+ * Configuration for useThreadManager hook
+ */
+interface UseThreadManagerConfig extends ReactThreadManagerConfig {
+    /**
+     * Storage adapter for persistence
+     * @default localStorage adapter
+     */
+    adapter?: ThreadStorageAdapter | AsyncThreadStorageAdapter;
+    /**
+     * Debounce delay for auto-save (ms)
+     * @default 1000
+     */
+    saveDebounce?: number;
+    /**
+     * Whether to auto-load threads on mount
+     * @default true
+     */
+    autoLoad?: boolean;
+    /**
+     * Whether to auto-restore the last active thread on load
+     * Requires adapter to support getLastActiveThreadId/setLastActiveThreadId
+     * @default true
+     */
+    autoRestoreLastThread?: boolean;
+    /**
+     * Callbacks for thread events
+     */
+    callbacks?: ThreadManagerCallbacks;
+}
+/**
+ * Return type for useThreadManager hook
+ */
+interface UseThreadManagerReturn {
+    /** All threads (metadata only) */
+    threads: Thread[];
+    /** Currently loaded thread (with messages) */
+    currentThread: ThreadData | null;
+    /** Currently selected thread ID */
+    currentThreadId: string | null;
+    /** Whether threads are currently loading */
+    isLoading: boolean;
+    /** Current load status */
+    loadStatus: LoadStatus;
+    /** Current error */
+    error: Error | undefined;
+    /**
+     * Create a new thread
+     */
+    createThread: (options?: CreateThreadOptions) => Promise<ThreadData>;
+    /**
+     * Switch to a different thread
+     */
+    switchThread: (id: string) => Promise<ThreadData | null>;
+    /**
+     * Update the current thread
+     */
+    updateCurrentThread: (updates: UpdateThreadOptions) => Promise<void>;
+    /**
+     * Delete a thread
+     */
+    deleteThread: (id: string) => Promise<void>;
+    /**
+     * Clear the current thread selection
+     */
+    clearCurrentThread: () => void;
+    /**
+     * Refresh threads from storage
+     */
+    refreshThreads: () => Promise<void>;
+    /**
+     * Save changes immediately (bypass debounce)
+     */
+    saveNow: () => Promise<void>;
+    /**
+     * Clear all threads
+     */
+    clearAllThreads: () => Promise<void>;
+    /**
+     * Whether there are pending changes waiting to be saved
+     */
+    hasPendingChanges: boolean;
+    /**
+     * Get messages for the current thread (convenience getter)
+     */
+    messages: Message[];
+    /**
+     * Update messages for the current thread (convenience setter)
+     */
+    setMessages: (messages: Message[]) => Promise<void>;
+}
+/**
+ * useThreadManager - React hook for thread management
+ *
+ * Provides thread CRUD operations with localStorage persistence by default.
+ *
+ * @example Basic usage (localStorage by default)
+ * ```tsx
+ * function App() {
+ *   const {
+ *     threads,
+ *     currentThread,
+ *     createThread,
+ *     switchThread,
+ *     updateCurrentThread,
+ *   } = useThreadManager();
+ *
+ *   return (
+ *     <CopilotProvider
+ *       runtimeUrl="/api/chat"
+ *       threadId={currentThread?.id}
+ *       initialMessages={currentThread?.messages}
+ *       onMessagesChange={(msgs) => updateCurrentThread({ messages: msgs })}
+ *     >
+ *       <ThreadPicker
+ *         value={currentThread?.id}
+ *         threads={threads}
+ *         onSelect={switchThread}
+ *         onNewThread={() => createThread()}
+ *       />
+ *       <Chat />
+ *     </CopilotProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom adapter
+ * ```tsx
+ * const { threads } = useThreadManager({
+ *   adapter: myDatabaseAdapter,
+ * });
+ * ```
+ *
+ * @example With callbacks
+ * ```tsx
+ * const { threads } = useThreadManager({
+ *   callbacks: {
+ *     onThreadCreated: (thread) => console.log('Created:', thread.id),
+ *     onError: (error) => console.error('Error:', error),
+ *   },
+ * });
+ * ```
+ */
+declare function useThreadManager(config?: UseThreadManagerConfig): UseThreadManagerReturn;
+
 /**
  * Create a permission storage adapter based on config
  */
@@ -1821,4 +2209,4 @@ interface UseChatReturn {
  */
 declare function useChat(config: UseChatConfig): UseChatReturn;
 
-export { type AIContextItem, AbstractAgentLoop, AbstractChat, ActionDefinition, type AgentLoopActions, type AgentLoopCallbacks, type AgentLoopState, type CapabilitiesResponse, CapturedContext, type ChatActions, type ChatCallbacks, type ChatConfig, type ChatState, type ChatStatus, type ToolExecution as ChatToolExecution, type ToolResponse as ChatToolResponse, type CombinedChatState, CopilotConfig, type CopilotContextValue, CopilotProvider, type CopilotProviderProps, type AgentLoopState$1 as CoreAgentLoopState, type ChatState$1 as CoreChatState, type DevLoggerState, IntentDetectionResult, type KnowledgeBaseConfig, type KnowledgeBaseResult, type KnowledgeBaseSearchResponse, LLMConfig, Message, PermissionLevel, PermissionStorageAdapter, PermissionStorageConfig, type ProviderCapabilities, ReactChat, type ReactChatConfig, ReactChatState, Source, type Suggestion, ToolConsentRequest, ToolConsentResponse, ToolContext, ToolDefinition, ToolExecution$1 as ToolExecution, ToolResponse$1 as ToolResponse, ToolType, type ToolsActions, ToolsConfig, type ToolsState, type UIMessage, UnifiedToolCall, type UseAIToolsOptions, type UseAIToolsReturn, type UseAgentOptions, type UseAgentReturn, type UseChatConfig, type UseChatReturn, type UseKnowledgeBaseConfig, type UseSuggestionsOptions, type UseSuggestionsReturn, type UseToolConfig, type UseToolExecutorReturn, type UseToolWithSchemaConfig, createPermissionStorage, createReactChat, createReactChatState, createSessionPermissionCache, formatKnowledgeResultsForAI, initialAgentLoopState, searchKnowledgeBase, useAIAction, useAIActions, useAIContext, useAIContexts, useAITools, useAgent, useCapabilities, useChat, useCopilot, useDevLogger, useFeatureSupport, useKnowledgeBase, useSuggestions, useSupportedMediaTypes, useTool, useToolExecutor, useToolWithSchema, useTools, useToolsWithSchema };
+export { type AIContextItem, AbstractAgentLoop, AbstractChat, ActionDefinition, type AgentLoopActions, type AgentLoopCallbacks, type AgentLoopState, AsyncThreadStorageAdapter, type CapabilitiesResponse, CapturedContext, type ChatActions, type ChatCallbacks, type ChatConfig, type ChatState, type ChatStatus, type ToolExecution as ChatToolExecution, type ToolResponse as ChatToolResponse, type CombinedChatState, CopilotConfig, type CopilotContextValue, CopilotProvider, type CopilotProviderProps, type AgentLoopState$1 as CoreAgentLoopState, type ChatState$1 as CoreChatState, type DevLoggerState, IntentDetectionResult, type KnowledgeBaseConfig, type KnowledgeBaseResult, type KnowledgeBaseSearchResponse, LLMConfig, Message, PermissionLevel, PermissionStorageAdapter, PermissionStorageConfig, type ProviderCapabilities, ReactChat, type ReactChatConfig, ReactChatState, ReactThreadManager, type ReactThreadManagerConfig, ReactThreadManagerState, type ServerAdapterConfig, Source, type Suggestion, Thread, ThreadData, ToolConsentRequest, ToolConsentResponse, ToolContext, ToolDefinition, ToolExecution$1 as ToolExecution, ToolResponse$1 as ToolResponse, ToolType, type ToolsActions, ToolsConfig, type ToolsState, type UIMessage, UnifiedToolCall, type UseAIToolsOptions, type UseAIToolsReturn, type UseAgentOptions, type UseAgentReturn, type UseChatConfig, type UseChatReturn, type UseKnowledgeBaseConfig, type UseSuggestionsOptions, type UseSuggestionsReturn, type UseThreadManagerConfig, type UseThreadManagerReturn, type UseToolConfig, type UseToolExecutorReturn, type UseToolWithSchemaConfig, createPermissionStorage, createReactChat, createReactChatState, createReactThreadManager, createReactThreadManagerState, createServerAdapter, createSessionPermissionCache, formatKnowledgeResultsForAI, initialAgentLoopState, searchKnowledgeBase, useAIAction, useAIActions, useAIContext, useAIContexts, useAITools, useAgent, useCapabilities, useChat, useCopilot, useDevLogger, useFeatureSupport, useKnowledgeBase, useSuggestions, useSupportedMediaTypes, useThreadManager, useTool, useToolExecutor, useToolWithSchema, useTools, useToolsWithSchema };

package/dist/react/index.js

@@ -1,4 +1,4 @@
-export { AbstractAgentLoop, AbstractChat, CopilotProvider, ReactChat, ReactChatState, createPermissionStorage, createReactChat, createReactChatState, createSessionPermissionCache, formatKnowledgeResultsForAI, initialAgentLoopState, searchKnowledgeBase, useAIAction, useAIActions, useAIContext, useAIContexts, useAITools, useAgent, useCapabilities, useChat, useCopilot, useDevLogger, useFeatureSupport, useKnowledgeBase, useSuggestions, useSupportedMediaTypes, useTool, useToolExecutor, useToolWithSchema, useTools, useToolsWithSchema } from '../chunk-QUGTRQSS.js';
-export { generateSuggestionReason } from '../chunk-N4OA2J32.js';
+export { AbstractAgentLoop, AbstractChat, CopilotProvider, ReactChat, ReactChatState, ReactThreadManager, ReactThreadManagerState, createPermissionStorage, createReactChat, createReactChatState, createReactThreadManager, createReactThreadManagerState, createSessionPermissionCache, formatKnowledgeResultsForAI, initialAgentLoopState, searchKnowledgeBase, useAIAction, useAIActions, useAIContext, useAIContexts, useAITools, useAgent, useCapabilities, useChat, useCopilot, useDevLogger, useFeatureSupport, useKnowledgeBase, useSuggestions, useSupportedMediaTypes, useThreadManager, useTool, useToolExecutor, useToolWithSchema, useTools, useToolsWithSchema } from '../chunk-XAVZZVUL.js';
+export { createLocalStorageAdapter, createMemoryAdapter, createServerAdapter, generateSuggestionReason } from '../chunk-QSEGNATZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map