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

package/dist/react/index.d.ts

@@ -1,13 +1,18 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { U as UIMessage, B as BranchInfo } from '../MessageTree-CzaN9Eul.js';
+export { M as MessageTree } from '../MessageTree-CzaN9Eul.js';
+import * as React$1 from 'react';
 import React__default from 'react';
-import { L as LLMConfig, l as ToolsConfig, s 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, y as InternalKnowledgeBaseConfig, B as InternalKnowledgeBaseSearchResponse, z as InternalKnowledgeBaseResult, Y as ThreadManagerState, Z as LoadStatus, U as ThreadManagerConfig, F as ThreadManager, V as ThreadManagerCallbacks, W as CreateThreadOptions, X as UpdateThreadOptions } from '../ThreadManager-Dkp_eLty.js';
-export { A as ActionParameter, q as CloudConfig, r as CopilotConfig, _ as LocalStorageAdapterConfig, J as createLocalStorageAdapter, O as createMemoryAdapter, i as generateSuggestionReason } from '../ThreadManager-Dkp_eLty.js';
-import { T as ToolDefinition, f as ToolSource, P as PermissionLevel, c as ToolInputSchema, m as ToolExecution$1, e as ToolContext, b as ToolResponse$1, g as ToolRenderProps, i as ToolSet, U as UnifiedToolCall, s as PermissionStorageConfig, t as PermissionStorageAdapter } from '../tools-coIcskZ4.js';
-export { n as AgentLoopConfig, h as ToolConfig, a as ToolExecutionStatus, r as ToolPermission, j as ToolSetEntry, u as tool } from '../tools-coIcskZ4.js';
-import { A as AsyncThreadStorageAdapter, c as MessageAttachment, f as ToolCall, S as Source, M as Message, T as Thread, a as ThreadData, b as ThreadStorageAdapter } from '../types-DG2ya08y.js';
-export { P as PersistenceConfig, h as ThreadStorageAdapter } from '../types-DG2ya08y.js';
-import { G as MCPServerConfig, U as UseMCPClientConfig, D as UseMCPClientReturn, E as UseMCPToolsConfig, F as UseMCPToolsReturn } from '../types-rjaSVmEF.js';
-export { b as MCPClientState } from '../types-rjaSVmEF.js';
+import { L as LLMConfig, l as ToolsConfig, s 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, y as InternalKnowledgeBaseConfig, B as InternalKnowledgeBaseSearchResponse, z as InternalKnowledgeBaseResult, Y as ThreadManagerState, Z as LoadStatus, U as ThreadManagerConfig, F as ThreadManager, V as ThreadManagerCallbacks, W as CreateThreadOptions, X as UpdateThreadOptions } from '../ThreadManager-BEAECB7Y.js';
+export { A as ActionParameter, q as CloudConfig, r as CopilotConfig, _ as LocalStorageAdapterConfig, J as createLocalStorageAdapter, O as createMemoryAdapter, i as generateSuggestionReason } from '../ThreadManager-BEAECB7Y.js';
+import { T as ToolDefinition, t as ToolOptimizationConfig, r as ContextUsage, f as ToolSource, P as PermissionLevel, c as ToolInputSchema, y as ToolExecution$1, e as ToolContext, b as ToolResponse$1, g as ToolRenderProps, i as ToolResultConfig, D as AIResponseMode, u as ToolSet, U as UnifiedToolCall, G as PermissionStorageConfig, H as PermissionStorageAdapter } from '../tools-DHZhF5km.js';
+export { z as AgentLoopConfig, q as ContextUsagePart, h as ToolConfig, a as ToolExecutionStatus, F as ToolPermission, v as ToolSetEntry, I as tool } from '../tools-DHZhF5km.js';
+import { A as AsyncThreadStorageAdapter, M as MessageAttachment, T as ToolCall, d as Message, S as Source, a as Thread, b as ThreadData, c as ThreadStorageAdapter } from '../types-BeFBBZ5i.js';
+export { P as PersistenceConfig, j as ThreadStorageAdapter } from '../types-BeFBBZ5i.js';
+import { G as MCPServerConfig, U as UseMCPClientConfig, D as UseMCPClientReturn, E as UseMCPToolsConfig, F as UseMCPToolsReturn } from '../types-BTyJu0WD.js';
+export { b as MCPClientState } from '../types-BTyJu0WD.js';
+import { S as SkillDefinition, R as ResolvedSkill } from '../types-BckL3hiw.js';
+export { C as ClientInlineSkill, b as SkillSource, c as SkillStrategy } from '../types-BckL3hiw.js';
 import { U as UseMCPUIIntentsConfig, m as UseMCPUIIntentsReturn } from '../types-B20VCJXL.js';
 
 /**
@@ -114,6 +119,16 @@ interface ChatRequest {
     actions?: unknown[];
     /** Additional body properties */
     body?: Record<string, unknown>;
+    /**
+     * Inline client skills to send to the server for merging with server-side skills.
+     * Set by AbstractChat when useSkill() hooks are active.
+     */
+    __skills?: Array<{
+        name: string;
+        description: string;
+        content: string;
+        strategy?: string;
+    }>;
 }
 /**
  * Chat response (non-streaming)
@@ -283,46 +298,6 @@ interface ChatTransport {
     setBody?(body: Resolvable<Record<string, unknown>>): void;
 }
 
-/**
- * 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>;
-}
-
 /**
  * ChatState Interface
  *
@@ -422,6 +397,30 @@ interface ChatState$1<T extends UIMessage = UIMessage> {
      * Get error snapshot
      */
     getErrorSnapshot?(): Error | undefined;
+    /**
+     * Set the current leaf message ID.
+     * Used by regenerate() to rewind the active path before pushing a new response.
+     */
+    setCurrentLeaf?(leafId: string | null): void;
+    /**
+     * Get all messages across all branches (for persistence).
+     * The base messages getter returns only the visible path.
+     */
+    getAllMessages?(): T[];
+    /**
+     * Get branch navigation info for a message.
+     * Returns null if the message has no siblings.
+     */
+    getBranchInfo?(messageId: string): BranchInfo | null;
+    /**
+     * Navigate to a specific message variant (sibling branch).
+     * Updates the active path to go through messageId.
+     */
+    switchBranch?(messageId: string): void;
+    /**
+     * Whether any message has siblings (branching has occurred).
+     */
+    readonly hasBranches?: boolean;
 }
 
 /**
@@ -463,10 +462,12 @@ interface ChatConfig {
     body?: Resolvable<Record<string, unknown>>;
     /** Thread ID for conversation persistence */
     threadId?: string;
-    /** Debug mode */
+    /** Enable debug logging */
     debug?: boolean;
     /** Available tools (passed to LLM) */
     tools?: ToolDefinition[];
+    /** Optional prompt/tool optimization controls */
+    optimization?: ToolOptimizationConfig;
 }
 /**
  * Server-side tool execution info (from streaming action events)
@@ -497,6 +498,8 @@ interface ChatCallbacks<T extends UIMessage = UIMessage> {
     onToolCalls?: (toolCalls: T["toolCalls"]) => void;
     /** Called when generation is complete */
     onFinish?: (messages: T[]) => void;
+    /** Called when prompt context usage changes */
+    onContextUsageChange?: (usage: ContextUsage) => void;
     /** Called when a server-side tool starts executing (action:start event) */
     onServerToolStart?: (info: ServerToolInfo) => void;
     /** Called when a server-side tool receives args (action:args event) */
@@ -641,6 +644,39 @@ interface AgentLoopActions {
  */
 declare const initialAgentLoopState: AgentLoopState$1;
 
+type RequestMessage = ChatRequest["messages"][number];
+type RequestTool = {
+    name: string;
+    description: string;
+    category?: string;
+    group?: string;
+    deferLoading?: boolean;
+    profiles?: string[];
+    searchKeywords?: string[];
+    inputSchema: unknown;
+};
+declare class ChatContextOptimizer {
+    private config;
+    private activeProfile;
+    private lastContextUsage;
+    constructor(config?: ToolOptimizationConfig);
+    updateConfig(config?: ToolOptimizationConfig): void;
+    setActiveProfile(profile?: string): void;
+    getContextUsage(): ContextUsage | null;
+    prepare(params: {
+        messages: UIMessage[];
+        tools?: ToolDefinition[];
+        systemPrompt?: string;
+    }): {
+        messages: RequestMessage[];
+        tools?: RequestTool[];
+        contextUsage: ContextUsage;
+        warnings: string[];
+    };
+    private selectTools;
+    private transformMessages;
+}
+
 /**
  * Event types emitted by AbstractChat
  */
@@ -682,6 +718,8 @@ declare class AbstractChat<T extends UIMessage = UIMessage> {
     protected transport: ChatTransport;
     protected config: ChatConfig;
     protected callbacks: ChatCallbacks<T>;
+    protected optimizer: ChatContextOptimizer;
+    protected lastContextUsage: ContextUsage | null;
     private eventHandlers;
     private streamState;
     constructor(init: ChatInit<T>);
@@ -696,8 +734,16 @@ declare class AbstractChat<T extends UIMessage = UIMessage> {
     /**
      * Send a message
      * Returns false if a request is already in progress
+     *
+     * @param content - Message content
+     * @param attachments - Optional attachments
+     * @param options - Optional branching options
+     * @param options.editMessageId - Edit flow: new message branches from the
+     *   same parent as this message ID, creating a parallel conversation path
      */
-    sendMessage(content: string, attachments?: MessageAttachment[]): Promise<boolean>;
+    sendMessage(content: string, attachments?: MessageAttachment[], options?: {
+        editMessageId?: string;
+    }): Promise<boolean>;
     /**
      * Resolve any tool_calls that don't have corresponding tool_results.
      * This prevents Anthropic API errors when tool_use has no tool_result.
@@ -728,9 +774,21 @@ declare class AbstractChat<T extends UIMessage = UIMessage> {
      */
     setMessages(messages: T[]): void;
     /**
-     * Regenerate last response
+     * Regenerate last response.
+     *
+     * Branch-aware: when the state supports branching (setCurrentLeaf is available),
+     * regenerate creates a new sibling response instead of destroying the original.
+     * The old response is preserved and navigable via switchBranch().
+     *
+     * Legacy fallback: when branching is not available, uses old slice() behavior.
      */
     regenerate(messageId?: string): Promise<void>;
+    /**
+     * Returns all messages across all branches when the state supports it
+     * (branch-aware), otherwise returns the visible path.
+     * Use this whenever firing onMessagesChange so inactive branches are not lost.
+     */
+    private _allMessages;
     /**
      * Subscribe to events
      */
@@ -749,10 +807,51 @@ declare class AbstractChat<T extends UIMessage = UIMessage> {
      * Set tools available for the LLM
      */
     setTools(tools: ToolDefinition[]): void;
+    /**
+     * Update prompt/tool optimization behavior.
+     */
+    setOptimizationConfig(config?: ToolOptimizationConfig): void;
+    /**
+     * Select the active tool profile for future requests.
+     */
+    setToolProfile(profile?: string): void;
+    /**
+     * Get the most recent prompt context usage snapshot.
+     */
+    getContextUsage(): ContextUsage | null;
+    /**
+     * Inline skills from the client (sent on every request for server to merge)
+     */
+    protected inlineSkills: Array<{
+        name: string;
+        description: string;
+        content: string;
+        strategy?: string;
+    }>;
+    /**
+     * Set inline skills (called by SkillProvider via React layer)
+     */
+    setInlineSkills(skills: Array<{
+        name: string;
+        description: string;
+        content: string;
+        strategy?: string;
+    }>): void;
     /**
      * Dynamic context from useAIContext hook
      */
     protected dynamicContext: string;
+    /**
+     * Optional transform applied to messages just before building the HTTP request.
+     * Used by the message-history / compaction system to send a pruned message list
+     * without mutating the in-memory store (which keeps the full history for display).
+     */
+    private requestMessageTransform;
+    /**
+     * Set (or clear) the per-request message transform.
+     * Pass null to disable.
+     */
+    setRequestMessageTransform(fn: ((messages: UIMessage[]) => UIMessage[]) | null): void;
     /**
      * Set dynamic context (appended to system prompt)
      */
@@ -781,32 +880,37 @@ declare class AbstractChat<T extends UIMessage = UIMessage> {
      * Build the request payload
      */
     protected buildRequest(): {
-        messages: ({
-            role: "tool";
-            content: string;
-            tool_call_id: string;
-            tool_calls?: undefined;
-            attachments?: undefined;
-        } | {
-            role: MessageRole;
-            content: string;
-            tool_calls: ToolCall[] | undefined;
-            tool_call_id: string | undefined;
-            attachments: MessageAttachment[] | undefined;
-        })[];
+        messages: {
+            role: string;
+            content: string | null;
+            tool_calls?: unknown[];
+            tool_call_id?: string;
+            attachments?: unknown[];
+        }[];
         threadId: string | undefined;
         systemPrompt: string | undefined;
         llm: Partial<LLMConfig> | undefined;
         tools: {
             name: string;
             description: string;
+            category: string | undefined;
+            group: string | undefined;
+            deferLoading: boolean | undefined;
+            profiles: string[] | undefined;
+            searchKeywords: string[] | undefined;
             inputSchema: ToolInputSchema;
         }[] | undefined;
+        __skills: {
+            name: string;
+            description: string;
+            content: string;
+            strategy?: string;
+        }[] | undefined;
     };
     /**
      * Handle streaming response
      */
-    protected handleStreamResponse(stream: AsyncIterable<StreamChunk>): Promise<void>;
+    protected handleStreamResponse(stream: AsyncIterable<StreamChunk>, preCreatedMessageId?: string): Promise<void>;
     /**
      * Handle JSON (non-streaming) response
      */
@@ -815,10 +919,11 @@ declare class AbstractChat<T extends UIMessage = UIMessage> {
      * Handle errors
      */
     protected handleError(error: Error): void;
-    /**
-     * Debug logging
-     */
+    private _log?;
+    private get log();
     protected debug(action: string, data?: unknown): void;
+    protected debugGroup(label: string, collapsed?: boolean): void;
+    protected debugGroupEnd(): void;
     /**
      * Type guard for async iterable
      */
@@ -1010,6 +1115,191 @@ declare class AbstractAgentLoop implements AgentLoopActions {
     revive(): void;
 }
 
+/**
+ * Message History Types
+ *
+ * Core types for the dual-layer context management system.
+ * DisplayMessage extends UIMessage for full backward-compat.
+ */
+
+/**
+ * DisplayMessage — what the UI renders, never shrinks.
+ * Extends UIMessage so it can be used anywhere UIMessage is accepted.
+ */
+interface DisplayMessage extends UIMessage {
+    /** Unix timestamp (ms). Mirrors createdAt for easier arithmetic. */
+    timestamp: number;
+}
+/**
+ * CompactionMarker — injected into displayMessages when compaction fires.
+ * Shown in the UI as a divider: "Earlier conversation summarized".
+ */
+interface CompactionMarker extends DisplayMessage {
+    role: "system";
+    /** Discriminator — always 'compaction-marker' */
+    type: "compaction-marker";
+    /** Human-readable summary of what was compacted */
+    content: string;
+    /** IDs of the DisplayMessages that were summarized */
+    summarizedMessageIds: string[];
+    /** Approximate tokens saved by this compaction */
+    tokensSaved: number;
+}
+/**
+ * LLMMessage — the compacted form sent to the model on each request.
+ * Derived from DisplayMessages; never persisted directly.
+ */
+interface LLMMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+/**
+ * CompactedToolResult — replaces a full tool result when it is old
+ * enough to prune. Preserves key metadata without the full payload.
+ */
+interface CompactedToolResult {
+    type: "compacted-tool-result";
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    executedAt: number;
+    status: "success" | "error";
+    /** Original byte size before compaction */
+    originalSize: number;
+    /** One-line summary e.g. "Searched for 'react hooks' — 15 results" */
+    summary: string;
+    /** First 200 chars of original result, if no LLM summary available */
+    extract?: string;
+}
+/**
+ * SessionCompactionState — persisted to localStorage between reloads.
+ */
+interface SessionCompactionState {
+    /** The current rolling summary (null = no compaction yet) */
+    rollingSummary: string | null;
+    /** Timestamp of last compaction (null = never compacted) */
+    lastCompactionAt: number | null;
+    /** How many times compaction has run this session */
+    compactionCount: number;
+    /** Cumulative tokens saved across all compactions */
+    totalTokensSaved: number;
+    /** User-pinned facts that survive all compaction */
+    workingMemory: string[];
+    /** Current displayMessages count (for diagnostics) */
+    displayMessageCount: number;
+    /** Current llmMessages count (for diagnostics) */
+    llmMessageCount: number;
+}
+/**
+ * TokenUsage — live token estimate after each AI response.
+ */
+interface TokenUsage {
+    /** Estimated tokens currently in LLM context */
+    current: number;
+    /** Max tokens configured (maxContextTokens) */
+    max: number;
+    /** current / max (0–1) */
+    percentage: number;
+    /** True when percentage > compactionThreshold */
+    isApproaching: boolean;
+}
+/**
+ * CompactionEvent — fired via onCompaction callback after each compaction.
+ */
+interface CompactionEvent {
+    /** 'auto' = threshold triggered, 'manual' = compactSession() called */
+    type: "auto" | "manual";
+    compactionCount: number;
+    messagesSummarized: number;
+    tokensSaved: number;
+    timestamp: number;
+}
+type CompactionStrategy = "none" | "sliding-window" | "summary-buffer" | "selective-prune";
+/**
+ * MessageHistoryConfig — passed as messageHistory prop to CopilotProvider
+ * or directly to useMessageHistory().
+ */
+interface MessageHistoryConfig {
+    /**
+     * Compaction strategy.
+     * @default 'none' — current SDK behaviour, zero breaking changes
+     */
+    strategy?: CompactionStrategy;
+    /**
+     * Hard token ceiling for LLM context.
+     * @default 128000
+     */
+    maxContextTokens?: number;
+    /**
+     * Tokens reserved for the model's reply; subtracted from budget before pruning.
+     * @default 4096
+     */
+    reserveForResponse?: number;
+    /**
+     * Ratio of maxContextTokens at which auto-compaction fires.
+     * @default 0.75
+     */
+    compactionThreshold?: number;
+    /**
+     * Minimum messages always kept verbatim (most recent N). Never compacted.
+     * @default 10
+     */
+    recentBuffer?: number;
+    /**
+     * Hard char truncation cap per tool result before sending. 0 = no cap.
+     * @default 10000
+     */
+    toolResultMaxChars?: number;
+    /**
+     * Your /api/compact endpoint. Required when strategy is 'summary-buffer'.
+     */
+    compactionUrl?: string;
+    /**
+     * Persist display history + compaction state across page reloads.
+     * @default false
+     */
+    persistSession?: boolean;
+    /**
+     * localStorage/IndexedDB key prefix.
+     * @default 'copilot-session'
+     */
+    storageKey?: string;
+    /** Fired after every compaction. */
+    onCompaction?: (event: CompactionEvent) => void;
+    /** Fired after every message with current token estimate. */
+    onTokenUsage?: (usage: TokenUsage) => void;
+}
+interface UseMessageHistoryOptions extends MessageHistoryConfig {
+    /** Disable auto-compaction for this component even if provider has it on. */
+    skipCompaction?: boolean;
+    /** Token estimation precision. @default 'fast' */
+    tokenEstimation?: "fast" | "accurate" | "off";
+    /** Custom async summarizer. Overrides /api/compact. */
+    summarizer?: (messages: LLMMessage[]) => Promise<string>;
+}
+interface UseMessageHistoryReturn {
+    /** Full immutable UI history. Pass to CopilotChat. */
+    displayMessages: DisplayMessage[];
+    /** Compacted LLM context. Rebuilt on each render. */
+    llmMessages: LLMMessage[];
+    /** Live token estimate. Updated after each AI response. */
+    tokenUsage: TokenUsage;
+    /** True while auto-compaction is running (summarizing old messages). */
+    isCompacting: boolean;
+    /** Compaction metadata. */
+    compactionState: SessionCompactionState;
+    /** Manually trigger compaction. Optional instructions guide the summarizer. */
+    compactSession: (instructions?: string) => Promise<void>;
+    /** Pin a string that survives all future compactions. */
+    addToWorkingMemory: (fact: string) => void;
+    /** Remove all working memory facts. */
+    clearWorkingMemory: () => void;
+    /** Clear history, compaction state, and persistence. Fresh start. */
+    resetSession: () => void;
+}
+
 interface CopilotProviderProps {
     children: React__default.ReactNode;
     /**
@@ -1049,6 +1339,20 @@ interface CopilotProviderProps {
     maxIterationsMessage?: string;
     /** MCP servers to connect to automatically */
     mcpServers?: MCPServerConfig[];
+    /** Optional prompt/tool optimization controls (tool profiles, context budgets, etc.) */
+    optimization?: ToolOptimizationConfig;
+    /**
+     * Context window management config. Controls compaction strategy, token budgets,
+     * session persistence, and working memory.
+     * @default strategy: 'none' — current behaviour, zero breaking changes
+     */
+    messageHistory?: MessageHistoryConfig;
+    /**
+     * Convenience prop to pre-register inline skills.
+     * Wraps children with <SkillProvider skills={skills}>.
+     * Only inline skills (source.type === "inline") are supported client-side.
+     */
+    skills?: SkillDefinition[];
 }
 interface CopilotContextValue {
     messages: UIMessage[];
@@ -1060,6 +1364,12 @@ interface CopilotContextValue {
     clearMessages: () => void;
     setMessages: (messages: UIMessage[]) => void;
     regenerate: (messageId?: string) => Promise<void>;
+    switchBranch: (messageId: string) => void;
+    getBranchInfo: (messageId: string) => BranchInfo | null;
+    editMessage: (messageId: string, newContent: string) => Promise<void>;
+    hasBranches: boolean;
+    /** Get ALL messages across all branches (for persistence). Visible path only when no branches. */
+    getAllMessages: () => UIMessage[];
     registerTool: (tool: ToolDefinition) => void;
     unregisterTool: (name: string) => void;
     registeredTools: ToolDefinition[];
@@ -1073,6 +1383,20 @@ interface CopilotContextValue {
     addContext: (context: string, parentId?: string) => string;
     removeContext: (id: string) => void;
     setSystemPrompt: (prompt: string) => void;
+    /** Total characters currently registered in the AI context tree (system prompt contribution). */
+    contextChars: number;
+    /**
+     * Live prompt context usage snapshot — updated on every message send.
+     * Includes token counts and percentages for systemPrompt, history, toolResults, tools buckets.
+     * null until the first message is sent.
+     */
+    contextUsage: ContextUsage | null;
+    setInlineSkills: (skills: Array<{
+        name: string;
+        description: string;
+        content: string;
+        strategy?: string;
+    }>) => void;
     threadId?: string;
     /**
      * Runtime URL configuration.
@@ -1082,7 +1406,7 @@ interface CopilotContextValue {
     toolsConfig?: ToolsConfig;
 }
 declare function useCopilot(): CopilotContextValue;
-declare function CopilotProvider({ children, runtimeUrl, systemPrompt, tools: toolsConfig, threadId, initialMessages, onMessagesChange, onError, streaming, headers, body, debug, maxIterations, maxIterationsMessage, mcpServers, }: CopilotProviderProps): react_jsx_runtime.JSX.Element;
+declare function CopilotProvider({ children, runtimeUrl, systemPrompt, tools: toolsConfig, threadId, initialMessages, onMessagesChange, onError, streaming, headers, body, debug, maxIterations, maxIterationsMessage, mcpServers, optimization, messageHistory, skills, }: CopilotProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Chat UI state interface (UI-only state, not message data)
@@ -1150,7 +1474,7 @@ interface ChatActions {
     stopGeneration: () => void;
     /** Clear all messages */
     clearMessages: () => void;
-    /** Regenerate last response */
+    /** Regenerate last response (branch-aware: preserves original as sibling) */
     regenerate: (messageId?: string) => Promise<void>;
     /** Set messages directly */
     setMessages: (messages: Message[]) => void;
@@ -1160,6 +1484,17 @@ interface ChatActions {
      * - Free: converts to base64
      */
     processAttachment: (file: File) => Promise<MessageAttachment>;
+    /** Navigate to a sibling branch (← / → navigation) */
+    switchBranch: (messageId: string) => void;
+    /** Get branch navigation info for a message */
+    getBranchInfo: (messageId: string) => BranchInfo | null;
+    /**
+     * Edit a user message: sends newContent as a new branch from the same
+     * parent as the original message. Preserves the original in place.
+     */
+    editMessage: (messageId: string, newContent: string) => Promise<void>;
+    /** Whether any message has siblings (branching has occurred) */
+    hasBranches: boolean;
 }
 /**
  * Tools actions interface
@@ -1413,6 +1748,28 @@ interface UseToolConfig<TParams = Record<string, unknown>> {
      * @default false
      */
     hidden?: boolean;
+    /** Deferred tools stay out of the default request payload; discovered only when query matches */
+    deferLoading?: boolean;
+    /** Profile memberships for selective tool loading */
+    profiles?: string[];
+    /** Extra keywords for dynamic tool-selection scoring */
+    searchKeywords?: string[];
+    /** Optional group for profile-based selection */
+    group?: string;
+    /** Optional category for search, filtering, and budgets */
+    category?: string;
+    /** Per-tool prompt/result shaping controls */
+    resultConfig?: ToolResultConfig;
+    /** Human-readable title for UI display */
+    title?: string | ((args: TParams) => string);
+    /** Title shown while executing */
+    executingTitle?: string | ((args: TParams) => string);
+    /** Title shown after completion */
+    completedTitle?: string | ((args: TParams) => string);
+    /** How the AI should respond when this tool's result is rendered as UI */
+    aiResponseMode?: AIResponseMode;
+    /** Context/summary sent to AI instead of full result */
+    aiContext?: string | ((result: ToolResponse$1, args: Record<string, unknown>) => string);
 }
 /**
  * Register a client-side tool
@@ -2463,6 +2820,74 @@ declare function createMessageIntentHandler(sendMessage: (message: string) => vo
  */
 declare function createToolIntentHandler(callTool: (name: string, args?: Record<string, unknown>) => Promise<unknown>): UseMCPUIIntentsConfig;
 
+/**
+ * Per-message token usage returned by the LLM provider.
+ */
+interface MessageTokenUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/**
+ * Context window stats — updated reactively as messages are sent and contexts change.
+ */
+interface ContextStats {
+    /**
+     * Full context usage snapshot from the last send — includes token counts and
+     * percentages for every budget bucket (systemPrompt, history, toolResults, tools).
+     * null until the first message is sent.
+     */
+    contextUsage: ContextUsage | null;
+    /**
+     * Convenience: total estimated tokens currently in the prompt (from contextUsage).
+     * Falls back to a fast chars/3.5 estimate from contextChars before first send.
+     */
+    totalTokens: number;
+    /**
+     * Convenience: percentage of context window used (0–1).
+     * 0 until first send.
+     */
+    usagePercent: number;
+    /** Total characters currently in the AI context (system prompt contribution). */
+    contextChars: number;
+    /** Number of tools currently registered in the agent loop. */
+    toolCount: number;
+    /** Number of visible (non-system) messages in the active thread. */
+    messageCount: number;
+    /**
+     * Actual token usage from the last assistant message metadata (if provider returned it).
+     * null if not available.
+     */
+    lastResponseUsage: MessageTokenUsage | null;
+}
+/**
+ * useContextStats — live snapshot of the AI copilot's context window usage.
+ *
+ * `contextUsage` is the richest field — it has full breakdown by bucket with
+ * token counts and percentages, updated on every message send.
+ *
+ * @example
+ * ```tsx
+ * const { contextUsage, toolCount, totalTokens, usagePercent } = useContextStats();
+ * // contextUsage.breakdown.systemPrompt.percent — % of window used by system prompt
+ * // contextUsage.breakdown.history.tokens — tokens from conversation history
+ * // usagePercent — overall window fill (0–1)
+ * ```
+ */
+declare function useContextStats(): ContextStats;
+
+declare function useSkill(skill: SkillDefinition): void;
+
+interface UseSkillStatusReturn {
+    /** All currently registered skills */
+    skills: ResolvedSkill[];
+    /** Number of registered skills */
+    count: number;
+    /** Check if a skill with the given name is registered */
+    has: (name: string) => boolean;
+}
+declare function useSkillStatus(): UseSkillStatusReturn;
+
 /**
  * Create a permission storage adapter based on config
  */
@@ -2476,14 +2901,16 @@ declare function createSessionPermissionCache(): Map<string, PermissionLevel>;
 /**
  * ReactChatState - React-specific implementation of ChatState
  *
- * This class implements the ChatState interface with callback-based
- * reactivity for use with React's useSyncExternalStore.
+ * Backed by MessageTree for conversation branching support.
+ * The `messages` getter returns only the visible path (active branch).
+ * Use `getAllMessages()` for full persistence.
  *
  * Pattern inspired by Vercel AI SDK's useSyncExternalStore pattern.
  */
 
 /**
  * ReactChatState implements ChatState with callback-based reactivity
+ * and full conversation branching support via MessageTree.
  *
  * @example
  * ```tsx
@@ -2494,16 +2921,25 @@ declare function createSessionPermissionCache(): Map<string, PermissionLevel>;
  *   console.log('State changed');
  * });
  *
- * // Get snapshot (for useSyncExternalStore)
+ * // Get visible path (active branch only)
  * const messages = state.messages;
+ *
+ * // Get all messages across branches (for persistence)
+ * const all = state.getAllMessages();
  * ```
  */
 declare class ReactChatState<T extends UIMessage = UIMessage> implements ChatState$1<T> {
-    private _messages;
+    private tree;
     private _status;
     private _error;
     private subscribers;
     constructor(initialMessages?: T[]);
+    /**
+     * Returns the VISIBLE PATH (active branch) — what the UI renders
+     * and what gets sent to the API.
+     *
+     * For all messages across all branches, use getAllMessages().
+     */
     get messages(): T[];
     get status(): ChatStatus$1;
     get error(): Error | undefined;
@@ -2517,6 +2953,27 @@ declare class ReactChatState<T extends UIMessage = UIMessage> implements ChatSta
     updateMessageById(id: string, updater: (message: T) => T): boolean;
     setMessages(messages: T[]): void;
     clearMessages(): void;
+    /**
+     * Returns ALL messages across all branches.
+     * Use this for persistence (ThreadManager save).
+     */
+    getAllMessages(): T[];
+    /**
+     * Get branch navigation info for a message.
+     * Returns null if the message has no siblings.
+     */
+    getBranchInfo(messageId: string): BranchInfo | null;
+    /**
+     * Navigate to a sibling branch.
+     * Triggers re-render via notify().
+     */
+    switchBranch(messageId: string): void;
+    /**
+     * Set the current leaf (used by regenerate() to rewind active path).
+     * Triggers re-render via notify().
+     */
+    setCurrentLeaf(leafId: string | null): void;
+    get hasBranches(): boolean;
     /**
      * Subscribe to state changes.
      * Returns an unsubscribe function.
@@ -2626,6 +3083,23 @@ declare class ReactChat extends AbstractChat<UIMessage> {
      * Subscribe to error events
      */
     onError(handler: ChatEventHandler<"error">): () => void;
+    /**
+     * Navigate to a sibling branch (makes it the active path).
+     */
+    switchBranch(messageId: string): void;
+    /**
+     * Get branch navigation info for a message.
+     * Returns null if the message has no siblings.
+     */
+    getBranchInfo(messageId: string): BranchInfo | null;
+    /**
+     * Get all messages across all branches (for persistence).
+     */
+    getAllMessages(): UIMessage[];
+    /**
+     * Whether any message has siblings (branching has occurred).
+     */
+    get hasBranches(): boolean;
     dispose(): void;
     /**
      * Revive a disposed instance (for React StrictMode compatibility)
@@ -2654,7 +3128,7 @@ interface UseChatConfig extends Omit<ReactChatConfig, "callbacks"> {
  * Hook return type
  */
 interface UseChatReturn {
-    /** All messages */
+    /** All messages (visible path — active branch only) */
     messages: UIMessage[];
     /** Current status */
     status: ChatStatus$1;
@@ -2674,7 +3148,7 @@ interface UseChatReturn {
     clearMessages: () => void;
     /** Set messages directly */
     setMessages: (messages: UIMessage[]) => void;
-    /** Regenerate last response */
+    /** Regenerate last response (branch-aware: preserves original as sibling) */
     regenerate: (messageId?: string) => Promise<void>;
     /** Continue with tool results */
     continueWithToolResults: (toolResults: Array<{
@@ -2683,6 +3157,27 @@ interface UseChatReturn {
     }>) => Promise<void>;
     /** Reference to the ReactChat instance */
     chatRef: React.RefObject<ReactChat | null>;
+    /**
+     * Navigate to a sibling branch (← / → navigation).
+     * Only populated when chat is branch-aware.
+     */
+    switchBranch?: (messageId: string) => void;
+    /**
+     * Get branch navigation info for a message.
+     * Returns null if the message has no siblings.
+     * Only populated when chat is branch-aware.
+     */
+    getBranchInfo?: (messageId: string) => BranchInfo | null;
+    /**
+     * Edit a user message: sends newContent as a new branch from the same
+     * parent as the original message. Preserves the original message in place.
+     * Only populated when chat is branch-aware.
+     */
+    editMessage?: (messageId: string, newContent: string) => Promise<void>;
+    /**
+     * Whether any message has siblings (branching has occurred).
+     */
+    hasBranches?: boolean;
 }
 /**
  * useChat - Thin React wrapper using useSyncExternalStore
@@ -2706,4 +3201,105 @@ interface UseChatReturn {
  */
 declare function useChat(config: UseChatConfig): UseChatReturn;
 
-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, 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, ToolSet, ToolType, type ToolsActions, ToolsConfig, type ToolsState, type UIMessage, UnifiedToolCall, type UseAIToolsOptions, type UseAIToolsReturn, type UseAgentOptions, type UseAgentReturn, type UseChatConfig, type UseChatReturn, type UseKnowledgeBaseConfig, UseMCPClientConfig, UseMCPClientReturn, UseMCPToolsConfig, UseMCPToolsReturn, UseMCPUIIntentsConfig, UseMCPUIIntentsReturn, type UseSuggestionsOptions, type UseSuggestionsReturn, type UseThreadManagerConfig, type UseThreadManagerReturn, type UseToolConfig, type UseToolExecutorReturn, type UseToolWithSchemaConfig, createMessageIntentHandler, createPermissionStorage, createReactChat, createReactChatState, createReactThreadManager, createReactThreadManagerState, createServerAdapter, createSessionPermissionCache, createToolIntentHandler, formatKnowledgeResultsForAI, initialAgentLoopState, searchKnowledgeBase, useAIAction, useAIActions, useAIContext, useAIContexts, useAITools, useAgent, useCapabilities, useChat, useCopilot, useDevLogger, useFeatureSupport, useKnowledgeBase, useMCPClient, useMCPTools, useMCPUIIntents, useSuggestions, useSupportedMediaTypes, useThreadManager, useTool, useToolExecutor, useToolWithSchema, useTools, useToolsWithSchema };
+interface SkillProviderProps {
+    children: React__default.ReactNode;
+    /** Pre-register skills (eager or auto strategies) */
+    skills?: SkillDefinition[];
+    /**
+     * Future: URL to fetch a remote skill manifest
+     * @experimental
+     */
+    remoteManifest?: string;
+}
+declare function SkillProvider({ children, skills: skillsProp, }: SkillProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * defineSkill — type-safe skill factory
+ *
+ * Identity function with type inference. Same pattern as useTool.
+ *
+ * @example
+ * ```ts
+ * const brandVoice = defineSkill({
+ *   name: "brand-voice",
+ *   description: "Ensures responses match our brand tone",
+ *   strategy: "eager",
+ *   source: {
+ *     type: "inline",
+ *     content: "Always respond in a friendly, concise tone...",
+ *   },
+ * });
+ *
+ * // Use in SkillProvider
+ * <SkillProvider skills={[brandVoice]}>
+ *   <App />
+ * </SkillProvider>
+ * ```
+ */
+
+declare function defineSkill(def: SkillDefinition): SkillDefinition;
+
+/**
+ * useMessageHistory
+ *
+ * Dual-layer message access with optional compaction.
+ * Strategy 'none' (default) = zero-config, 100% backward-compat.
+ */
+
+declare function useMessageHistory(options?: UseMessageHistoryOptions): UseMessageHistoryReturn;
+
+interface MessageHistoryContextValue {
+    /** Merged config (provider defaults, overridable per-component) */
+    config: Required<Pick<MessageHistoryConfig, "strategy" | "maxContextTokens" | "reserveForResponse" | "compactionThreshold" | "recentBuffer" | "toolResultMaxChars" | "persistSession" | "storageKey">> & MessageHistoryConfig;
+    /** Current token usage (updated after each AI response) */
+    tokenUsage: TokenUsage;
+    /** Current compaction state */
+    compactionState: SessionCompactionState;
+}
+declare const defaultMessageHistoryConfig: {
+    strategy: "none";
+    maxContextTokens: number;
+    reserveForResponse: number;
+    compactionThreshold: number;
+    recentBuffer: number;
+    toolResultMaxChars: number;
+    persistSession: boolean;
+    storageKey: string;
+};
+declare const MessageHistoryContext: React$1.Context<MessageHistoryContextValue>;
+declare function useMessageHistoryContext(): MessageHistoryContextValue;
+
+/**
+ * Message Utilities
+ *
+ * Conversion helpers between UIMessage / DisplayMessage / LLMMessage.
+ * Core invariant: tool-call pairs are always kept atomic.
+ */
+
+/**
+ * Promote a UIMessage to a DisplayMessage.
+ * Safe to call on an existing DisplayMessage (idempotent).
+ */
+declare function toDisplayMessage(msg: UIMessage): DisplayMessage;
+/**
+ * Convert a DisplayMessage to the LLMMessage format sent to the model.
+ * CompactionMarkers are converted to system messages with the rolling summary.
+ */
+declare function toLLMMessage(msg: DisplayMessage): LLMMessage;
+/**
+ * Convert an array of DisplayMessages to LLMMessages.
+ */
+declare function toLLMMessages(messages: DisplayMessage[]): LLMMessage[];
+/**
+ * Keep tool-call pairs atomic — an assistant message with tool_calls
+ * must always be followed by its tool-result messages.
+ *
+ * When slicing/pruning, call this to ensure the window boundary never
+ * splits an assistant message from its tool results.
+ *
+ * Returns the input array with any split pairs re-attached at the start.
+ */
+declare function keepToolPairsAtomic(messages: DisplayMessage[]): DisplayMessage[];
+declare function isCompactionMarker(msg: DisplayMessage): msg is CompactionMarker;
+
+export { type AIContextItem, AbstractAgentLoop, AbstractChat, ActionDefinition, type AgentLoopActions, type AgentLoopCallbacks, type AgentLoopState, AsyncThreadStorageAdapter, BranchInfo, type CapabilitiesResponse, CapturedContext, type ChatActions, type ChatCallbacks, type ChatConfig, type ChatState, type ChatStatus, type ToolExecution as ChatToolExecution, type ToolResponse as ChatToolResponse, type CombinedChatState, type CompactedToolResult, type CompactionEvent, type CompactionMarker, type CompactionStrategy, type ContextStats, ContextUsage, type CopilotContextValue, CopilotProvider, type CopilotProviderProps, type AgentLoopState$1 as CoreAgentLoopState, type ChatState$1 as CoreChatState, type DevLoggerState, type DisplayMessage, IntentDetectionResult, type KnowledgeBaseConfig, type KnowledgeBaseResult, type KnowledgeBaseSearchResponse, LLMConfig, type LLMMessage, Message, type MessageHistoryConfig, MessageHistoryContext, type MessageHistoryContextValue, type MessageTokenUsage, PermissionLevel, PermissionStorageAdapter, PermissionStorageConfig, type ProviderCapabilities, ReactChat, type ReactChatConfig, ReactChatState, ReactThreadManager, type ReactThreadManagerConfig, ReactThreadManagerState, ResolvedSkill, type ServerAdapterConfig, type SessionCompactionState, SkillDefinition, SkillProvider, type SkillProviderProps, Source, type Suggestion, Thread, ThreadData, type TokenUsage, ToolConsentRequest, ToolConsentResponse, ToolContext, ToolDefinition, ToolExecution$1 as ToolExecution, ToolResponse$1 as ToolResponse, ToolSet, ToolType, type ToolsActions, ToolsConfig, type ToolsState, UIMessage, UnifiedToolCall, type UseAIToolsOptions, type UseAIToolsReturn, type UseAgentOptions, type UseAgentReturn, type UseChatConfig, type UseChatReturn, type UseKnowledgeBaseConfig, UseMCPClientConfig, UseMCPClientReturn, UseMCPToolsConfig, UseMCPToolsReturn, UseMCPUIIntentsConfig, UseMCPUIIntentsReturn, type UseMessageHistoryOptions, type UseMessageHistoryReturn, type UseSkillStatusReturn, type UseSuggestionsOptions, type UseSuggestionsReturn, type UseThreadManagerConfig, type UseThreadManagerReturn, type UseToolConfig, type UseToolExecutorReturn, type UseToolWithSchemaConfig, createMessageIntentHandler, createPermissionStorage, createReactChat, createReactChatState, createReactThreadManager, createReactThreadManagerState, createServerAdapter, createSessionPermissionCache, createToolIntentHandler, defaultMessageHistoryConfig, defineSkill, formatKnowledgeResultsForAI, initialAgentLoopState, isCompactionMarker, keepToolPairsAtomic, searchKnowledgeBase, toDisplayMessage, toLLMMessage, toLLMMessages, useAIAction, useAIActions, useAIContext, useAIContexts, useAITools, useAgent, useCapabilities, useChat, useContextStats, useCopilot, useDevLogger, useFeatureSupport, useKnowledgeBase, useMCPClient, useMCPTools, useMCPUIIntents, useMessageHistory, useMessageHistoryContext, useSkill, useSkillStatus, useSuggestions, useSupportedMediaTypes, useThreadManager, useTool, useToolExecutor, useToolWithSchema, useTools, useToolsWithSchema };