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

package/dist/{tools-coIcskZ4.d.ts → tools-DHZhF5km.d.cts}

@@ -134,6 +134,140 @@ type AIContent = {
     type: "text";
     text: string;
 };
+/**
+ * How large tool results should be trimmed before they are sent back to the AI.
+ */
+type ToolTruncationStrategy = "head" | "head-tail" | "smart";
+/**
+ * Truncation controls for tool results.
+ */
+interface ToolResultTruncationConfig {
+    enabled?: boolean;
+    maxContextShare?: number;
+    hardMaxChars?: number;
+    minKeepChars?: number;
+    strategy?: ToolTruncationStrategy;
+    preserveErrors?: boolean;
+}
+/**
+ * Global or per-tool controls for how tool results are represented in prompts.
+ */
+interface ToolResultConfig {
+    truncation?: ToolResultTruncationConfig;
+}
+/**
+ * Named tool profile for selective loading.
+ */
+interface ToolProfile {
+    name: string;
+    description?: string;
+    include?: string[];
+    exclude?: string[];
+}
+/**
+ * Tool profile configuration.
+ */
+interface ToolProfileConfig {
+    enabled?: boolean;
+    defaultProfile?: string;
+    profiles?: Record<string, ToolProfile>;
+    /** When false, active profiles exclude tools that do not declare profile membership. */
+    includeUnprofiled?: boolean;
+    dynamicSelection?: {
+        enabled?: boolean;
+        maxTools?: number;
+    };
+}
+/**
+ * History compaction behavior for long-running sessions.
+ */
+interface ContextHistoryConfig {
+    maxMessages?: number;
+    maxTokens?: number;
+    maxContextShare?: number;
+    pruneStrategy?: "oldest" | "least-relevant" | "summarize";
+}
+/**
+ * Optional summarization controls used during history compaction.
+ */
+interface ContextSummarizationConfig {
+    enabled?: boolean;
+    triggerAt?: number;
+    chunkSize?: number;
+    preserveRecent?: number;
+    fallbackBehavior?: "truncate" | "statistical" | "error";
+}
+/**
+ * Token estimation controls.
+ */
+interface TokenEstimationConfig {
+    safetyMargin?: number;
+    charsPerToken?: number;
+}
+/**
+ * Conversation context management.
+ */
+interface ContextManagementConfig {
+    enabled?: boolean;
+    history?: ContextHistoryConfig;
+    summarization?: ContextSummarizationConfig;
+    tokenEstimation?: TokenEstimationConfig;
+}
+/**
+ * One budget bucket in the prompt context.
+ */
+interface ContextUsagePart {
+    tokens: number;
+    percent: number;
+}
+/**
+ * Prompt context usage snapshot.
+ */
+interface ContextUsage {
+    total: ContextUsagePart;
+    breakdown: {
+        systemPrompt: ContextUsagePart;
+        history: ContextUsagePart;
+        toolResults: ContextUsagePart;
+        tools: ContextUsagePart;
+    };
+    budget: {
+        available: number;
+        remaining: number;
+    };
+    warnings: string[];
+}
+/**
+ * Real-time context budget configuration.
+ */
+interface ContextBudgetConfig {
+    enabled?: boolean;
+    budget?: {
+        contextWindowTokens?: number;
+        inputHeadroomRatio?: number;
+        systemPromptShare?: number;
+        historyShare?: number;
+        toolResultsShare?: number;
+        toolDefinitionsShare?: number;
+    };
+    enforcement?: {
+        mode?: "warn" | "truncate" | "error";
+        onBudgetExceeded?: (info: ContextUsage) => void;
+    };
+    monitoring?: {
+        enabled?: boolean;
+        onUsageUpdate?: (usage: ContextUsage) => void;
+    };
+}
+/**
+ * Framework-agnostic optimization controls for tool-heavy chat sessions.
+ */
+interface ToolOptimizationConfig {
+    toolProfiles?: ToolProfileConfig;
+    toolResultConfig?: ToolResultConfig;
+    contextManagement?: ContextManagementConfig;
+    contextBudget?: ContextBudgetConfig;
+}
 /**
  * Tool response format
  */
@@ -306,6 +440,18 @@ interface ToolDefinition<TParams = Record<string, unknown>> {
      * @default "custom"
      */
     source?: ToolSource;
+    /** Optional category for search, filtering, and budgets */
+    category?: string;
+    /** Optional group for profile-based tool selection */
+    group?: string;
+    /** Deferred tools are discoverable but need not be sent on every request */
+    deferLoading?: boolean;
+    /** Profile memberships for selective tool loading */
+    profiles?: string[];
+    /** Extra keywords for dynamic tool selection */
+    searchKeywords?: string[];
+    /** Per-tool prompt/result shaping controls */
+    resultConfig?: ToolResultConfig;
     /**
      * Human-readable title for UI display.
      * Can be a static string or a function that generates title from args.
@@ -548,6 +694,8 @@ interface AgentLoopConfig {
     debug?: boolean;
     /** Whether to enable the agentic loop (default: true) */
     enabled?: boolean;
+    /** Optional prompt/tool optimization controls */
+    optimization?: ToolOptimizationConfig;
 }
 /**
  * Agent loop state (for tracking)
@@ -598,6 +746,18 @@ interface ToolConfig<TParams = Record<string, unknown>> {
     description: string;
     /** Where the tool executes (default: 'client') */
     location?: ToolLocation;
+    /** Optional category for search, filtering, and budgets */
+    category?: string;
+    /** Optional group for profile-based tool selection */
+    group?: string;
+    /** Deferred tools are discoverable but omitted from the default prompt */
+    deferLoading?: boolean;
+    /** Profile memberships for selective tool loading */
+    profiles?: string[];
+    /** Extra keywords for dynamic tool selection */
+    searchKeywords?: string[];
+    /** Per-tool prompt/result shaping controls */
+    resultConfig?: ToolResultConfig;
     /** Human-readable title for UI display */
     title?: string | ((args: TParams) => string);
     /** Title shown while executing */
@@ -666,4 +826,4 @@ declare function success<T = unknown>(data?: T, message?: string): ToolResponse<
  */
 declare function failure(error: string): ToolResponse;
 
-export { type AIProvider as A, type JSONSchemaProperty as J, type PermissionLevel as P, type ToolDefinition as T, type UnifiedToolCall as U, type ToolExecutionStatus as a, type ToolResponse as b, type ToolInputSchema as c, type ToolLocation as d, type ToolContext as e, type ToolSource as f, type ToolRenderProps as g, type ToolConfig as h, type ToolSet as i, type ToolSetEntry as j, type UnifiedToolResult as k, type ToolApprovalStatus as l, type ToolExecution as m, type AgentLoopConfig as n, type AgentLoopState as o, type AIResponseMode as p, type AIContent as q, type ToolPermission as r, type PermissionStorageConfig as s, type PermissionStorageAdapter as t, tool as u, toolToOpenAIFormat as v, toolToAnthropicFormat as w, createToolResult as x, success as y, failure as z };
+export { type AIProvider as A, type AgentLoopState as B, type ContextHistoryConfig as C, type AIResponseMode as D, type AIContent as E, type ToolPermission as F, type PermissionStorageConfig as G, type PermissionStorageAdapter as H, tool as I, type JSONSchemaProperty as J, toolToOpenAIFormat as K, toolToAnthropicFormat as L, createToolResult as M, success as N, failure as O, type PermissionLevel as P, type ToolDefinition as T, type UnifiedToolCall as U, type ToolExecutionStatus as a, type ToolResponse as b, type ToolInputSchema as c, type ToolLocation as d, type ToolContext as e, type ToolSource as f, type ToolRenderProps as g, type ToolConfig as h, type ToolResultConfig as i, type ToolResultTruncationConfig as j, type ToolTruncationStrategy as k, type ToolProfile as l, type ToolProfileConfig as m, type ContextSummarizationConfig as n, type TokenEstimationConfig as o, type ContextManagementConfig as p, type ContextUsagePart as q, type ContextUsage as r, type ContextBudgetConfig as s, type ToolOptimizationConfig as t, type ToolSet as u, type ToolSetEntry as v, type UnifiedToolResult as w, type ToolApprovalStatus as x, type ToolExecution as y, type AgentLoopConfig as z };

package/dist/{tools-coIcskZ4.d.cts → tools-DHZhF5km.d.ts}

@@ -134,6 +134,140 @@ type AIContent = {
     type: "text";
     text: string;
 };
+/**
+ * How large tool results should be trimmed before they are sent back to the AI.
+ */
+type ToolTruncationStrategy = "head" | "head-tail" | "smart";
+/**
+ * Truncation controls for tool results.
+ */
+interface ToolResultTruncationConfig {
+    enabled?: boolean;
+    maxContextShare?: number;
+    hardMaxChars?: number;
+    minKeepChars?: number;
+    strategy?: ToolTruncationStrategy;
+    preserveErrors?: boolean;
+}
+/**
+ * Global or per-tool controls for how tool results are represented in prompts.
+ */
+interface ToolResultConfig {
+    truncation?: ToolResultTruncationConfig;
+}
+/**
+ * Named tool profile for selective loading.
+ */
+interface ToolProfile {
+    name: string;
+    description?: string;
+    include?: string[];
+    exclude?: string[];
+}
+/**
+ * Tool profile configuration.
+ */
+interface ToolProfileConfig {
+    enabled?: boolean;
+    defaultProfile?: string;
+    profiles?: Record<string, ToolProfile>;
+    /** When false, active profiles exclude tools that do not declare profile membership. */
+    includeUnprofiled?: boolean;
+    dynamicSelection?: {
+        enabled?: boolean;
+        maxTools?: number;
+    };
+}
+/**
+ * History compaction behavior for long-running sessions.
+ */
+interface ContextHistoryConfig {
+    maxMessages?: number;
+    maxTokens?: number;
+    maxContextShare?: number;
+    pruneStrategy?: "oldest" | "least-relevant" | "summarize";
+}
+/**
+ * Optional summarization controls used during history compaction.
+ */
+interface ContextSummarizationConfig {
+    enabled?: boolean;
+    triggerAt?: number;
+    chunkSize?: number;
+    preserveRecent?: number;
+    fallbackBehavior?: "truncate" | "statistical" | "error";
+}
+/**
+ * Token estimation controls.
+ */
+interface TokenEstimationConfig {
+    safetyMargin?: number;
+    charsPerToken?: number;
+}
+/**
+ * Conversation context management.
+ */
+interface ContextManagementConfig {
+    enabled?: boolean;
+    history?: ContextHistoryConfig;
+    summarization?: ContextSummarizationConfig;
+    tokenEstimation?: TokenEstimationConfig;
+}
+/**
+ * One budget bucket in the prompt context.
+ */
+interface ContextUsagePart {
+    tokens: number;
+    percent: number;
+}
+/**
+ * Prompt context usage snapshot.
+ */
+interface ContextUsage {
+    total: ContextUsagePart;
+    breakdown: {
+        systemPrompt: ContextUsagePart;
+        history: ContextUsagePart;
+        toolResults: ContextUsagePart;
+        tools: ContextUsagePart;
+    };
+    budget: {
+        available: number;
+        remaining: number;
+    };
+    warnings: string[];
+}
+/**
+ * Real-time context budget configuration.
+ */
+interface ContextBudgetConfig {
+    enabled?: boolean;
+    budget?: {
+        contextWindowTokens?: number;
+        inputHeadroomRatio?: number;
+        systemPromptShare?: number;
+        historyShare?: number;
+        toolResultsShare?: number;
+        toolDefinitionsShare?: number;
+    };
+    enforcement?: {
+        mode?: "warn" | "truncate" | "error";
+        onBudgetExceeded?: (info: ContextUsage) => void;
+    };
+    monitoring?: {
+        enabled?: boolean;
+        onUsageUpdate?: (usage: ContextUsage) => void;
+    };
+}
+/**
+ * Framework-agnostic optimization controls for tool-heavy chat sessions.
+ */
+interface ToolOptimizationConfig {
+    toolProfiles?: ToolProfileConfig;
+    toolResultConfig?: ToolResultConfig;
+    contextManagement?: ContextManagementConfig;
+    contextBudget?: ContextBudgetConfig;
+}
 /**
  * Tool response format
  */
@@ -306,6 +440,18 @@ interface ToolDefinition<TParams = Record<string, unknown>> {
      * @default "custom"
      */
     source?: ToolSource;
+    /** Optional category for search, filtering, and budgets */
+    category?: string;
+    /** Optional group for profile-based tool selection */
+    group?: string;
+    /** Deferred tools are discoverable but need not be sent on every request */
+    deferLoading?: boolean;
+    /** Profile memberships for selective tool loading */
+    profiles?: string[];
+    /** Extra keywords for dynamic tool selection */
+    searchKeywords?: string[];
+    /** Per-tool prompt/result shaping controls */
+    resultConfig?: ToolResultConfig;
     /**
      * Human-readable title for UI display.
      * Can be a static string or a function that generates title from args.
@@ -548,6 +694,8 @@ interface AgentLoopConfig {
     debug?: boolean;
     /** Whether to enable the agentic loop (default: true) */
     enabled?: boolean;
+    /** Optional prompt/tool optimization controls */
+    optimization?: ToolOptimizationConfig;
 }
 /**
  * Agent loop state (for tracking)
@@ -598,6 +746,18 @@ interface ToolConfig<TParams = Record<string, unknown>> {
     description: string;
     /** Where the tool executes (default: 'client') */
     location?: ToolLocation;
+    /** Optional category for search, filtering, and budgets */
+    category?: string;
+    /** Optional group for profile-based tool selection */
+    group?: string;
+    /** Deferred tools are discoverable but omitted from the default prompt */
+    deferLoading?: boolean;
+    /** Profile memberships for selective tool loading */
+    profiles?: string[];
+    /** Extra keywords for dynamic tool selection */
+    searchKeywords?: string[];
+    /** Per-tool prompt/result shaping controls */
+    resultConfig?: ToolResultConfig;
     /** Human-readable title for UI display */
     title?: string | ((args: TParams) => string);
     /** Title shown while executing */
@@ -666,4 +826,4 @@ declare function success<T = unknown>(data?: T, message?: string): ToolResponse<
  */
 declare function failure(error: string): ToolResponse;
 
-export { type AIProvider as A, type JSONSchemaProperty as J, type PermissionLevel as P, type ToolDefinition as T, type UnifiedToolCall as U, type ToolExecutionStatus as a, type ToolResponse as b, type ToolInputSchema as c, type ToolLocation as d, type ToolContext as e, type ToolSource as f, type ToolRenderProps as g, type ToolConfig as h, type ToolSet as i, type ToolSetEntry as j, type UnifiedToolResult as k, type ToolApprovalStatus as l, type ToolExecution as m, type AgentLoopConfig as n, type AgentLoopState as o, type AIResponseMode as p, type AIContent as q, type ToolPermission as r, type PermissionStorageConfig as s, type PermissionStorageAdapter as t, tool as u, toolToOpenAIFormat as v, toolToAnthropicFormat as w, createToolResult as x, success as y, failure as z };
+export { type AIProvider as A, type AgentLoopState as B, type ContextHistoryConfig as C, type AIResponseMode as D, type AIContent as E, type ToolPermission as F, type PermissionStorageConfig as G, type PermissionStorageAdapter as H, tool as I, type JSONSchemaProperty as J, toolToOpenAIFormat as K, toolToAnthropicFormat as L, createToolResult as M, success as N, failure as O, type PermissionLevel as P, type ToolDefinition as T, type UnifiedToolCall as U, type ToolExecutionStatus as a, type ToolResponse as b, type ToolInputSchema as c, type ToolLocation as d, type ToolContext as e, type ToolSource as f, type ToolRenderProps as g, type ToolConfig as h, type ToolResultConfig as i, type ToolResultTruncationConfig as j, type ToolTruncationStrategy as k, type ToolProfile as l, type ToolProfileConfig as m, type ContextSummarizationConfig as n, type TokenEstimationConfig as o, type ContextManagementConfig as p, type ContextUsagePart as q, type ContextUsage as r, type ContextBudgetConfig as s, type ToolOptimizationConfig as t, type ToolSet as u, type ToolSetEntry as v, type UnifiedToolResult as w, type ToolApprovalStatus as x, type ToolExecution as y, type AgentLoopConfig as z };

package/dist/{types-rjaSVmEF.d.ts → types-BTyJu0WD.d.ts}

@@ -1,4 +1,4 @@
-import { T as ToolDefinition } from './tools-coIcskZ4.js';
+import { T as ToolDefinition } from './tools-DHZhF5km.js';
 
 /**
  * MCP (Model Context Protocol) Type Definitions

package/dist/types-BckL3hiw.d.cts

@@ -0,0 +1,93 @@
+/**
+ * Skills System — Type Definitions
+ *
+ * Skills are instruction playbooks the AI loads on demand.
+ * Separate from Tools (execution layer) — skills shape behavior, tools do work.
+ */
+type SkillStrategy = "eager" | "auto" | "manual";
+type SkillSource = {
+    type: "inline";
+    content: string;
+} | {
+    type: "url";
+    url: string;
+} | {
+    type: "file";
+    path: string;
+};
+interface SkillDefinition {
+    name: string;
+    description: string;
+    source: SkillSource;
+    /** @default "auto" */
+    strategy?: SkillStrategy;
+    version?: string;
+}
+interface ResolvedSkill extends SkillDefinition {
+    /** Fully resolved content string */
+    content: string;
+}
+type SkillDiagnosticWinner = "server-dir" | "remote-url" | "client-inline";
+interface SkillDiagnostic {
+    type: "collision";
+    name: string;
+    winner: SkillDiagnosticWinner;
+    loser: SkillDiagnosticWinner;
+}
+interface ClientInlineSkill {
+    name: string;
+    description: string;
+    content: string;
+    strategy?: SkillStrategy;
+}
+interface LoadSkillsOptions {
+    /** Path to /skills directory (server-only) */
+    dir?: string;
+    /** Remote .md URLs to fetch */
+    remoteUrls?: string[];
+    /** Inline skills from useSkill() hooks */
+    clientSkills?: ClientInlineSkill[];
+}
+interface LoadSkillsResult {
+    skills: ResolvedSkill[];
+    diagnostics: SkillDiagnostic[];
+    /**
+     * Build a complete system prompt incorporating eager + auto skill catalog.
+     * Prepends eager skill content, appends auto catalog.
+     */
+    buildSystemPrompt(basePrompt?: string): string;
+    /**
+     * The load_skill tool definition ready to register with your AI framework.
+     * Returns structured result: { name, description, strategy, content, source }
+     */
+    tools: {
+        load_skill: {
+            description: string;
+            parameters: {
+                type: "object";
+                properties: {
+                    name: {
+                        type: "string";
+                        description: string;
+                    };
+                };
+                required: ["name"];
+            };
+            execute: (args: {
+                name: string;
+            }) => Promise<LoadSkillResult | LoadSkillError>;
+        };
+    };
+}
+interface LoadSkillResult {
+    name: string;
+    description: string;
+    strategy: SkillStrategy;
+    content: string;
+    source: "server-dir" | "remote-url" | "client-inline";
+}
+interface LoadSkillError {
+    error: string;
+}
+
+export type { ClientInlineSkill as C, LoadSkillsOptions as L, ResolvedSkill as R, SkillDefinition as S, LoadSkillsResult as a, SkillSource as b, SkillStrategy as c, SkillDiagnostic as d, SkillDiagnosticWinner as e, LoadSkillResult as f, LoadSkillError as g };

package/dist/types-BckL3hiw.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Skills System — Type Definitions
+ *
+ * Skills are instruction playbooks the AI loads on demand.
+ * Separate from Tools (execution layer) — skills shape behavior, tools do work.
+ */
+type SkillStrategy = "eager" | "auto" | "manual";
+type SkillSource = {
+    type: "inline";
+    content: string;
+} | {
+    type: "url";
+    url: string;
+} | {
+    type: "file";
+    path: string;
+};
+interface SkillDefinition {
+    name: string;
+    description: string;
+    source: SkillSource;
+    /** @default "auto" */
+    strategy?: SkillStrategy;
+    version?: string;
+}
+interface ResolvedSkill extends SkillDefinition {
+    /** Fully resolved content string */
+    content: string;
+}
+type SkillDiagnosticWinner = "server-dir" | "remote-url" | "client-inline";
+interface SkillDiagnostic {
+    type: "collision";
+    name: string;
+    winner: SkillDiagnosticWinner;
+    loser: SkillDiagnosticWinner;
+}
+interface ClientInlineSkill {
+    name: string;
+    description: string;
+    content: string;
+    strategy?: SkillStrategy;
+}
+interface LoadSkillsOptions {
+    /** Path to /skills directory (server-only) */
+    dir?: string;
+    /** Remote .md URLs to fetch */
+    remoteUrls?: string[];
+    /** Inline skills from useSkill() hooks */
+    clientSkills?: ClientInlineSkill[];
+}
+interface LoadSkillsResult {
+    skills: ResolvedSkill[];
+    diagnostics: SkillDiagnostic[];
+    /**
+     * Build a complete system prompt incorporating eager + auto skill catalog.
+     * Prepends eager skill content, appends auto catalog.
+     */
+    buildSystemPrompt(basePrompt?: string): string;
+    /**
+     * The load_skill tool definition ready to register with your AI framework.
+     * Returns structured result: { name, description, strategy, content, source }
+     */
+    tools: {
+        load_skill: {
+            description: string;
+            parameters: {
+                type: "object";
+                properties: {
+                    name: {
+                        type: "string";
+                        description: string;
+                    };
+                };
+                required: ["name"];
+            };
+            execute: (args: {
+                name: string;
+            }) => Promise<LoadSkillResult | LoadSkillError>;
+        };
+    };
+}
+interface LoadSkillResult {
+    name: string;
+    description: string;
+    strategy: SkillStrategy;
+    content: string;
+    source: "server-dir" | "remote-url" | "client-inline";
+}
+interface LoadSkillError {
+    error: string;
+}
+
+export type { ClientInlineSkill as C, LoadSkillsOptions as L, ResolvedSkill as R, SkillDefinition as S, LoadSkillsResult as a, SkillSource as b, SkillStrategy as c, SkillDiagnostic as d, SkillDiagnosticWinner as e, LoadSkillResult as f, LoadSkillError as g };

package/dist/{types-C8t4Ut8f.d.cts → types-BdX7uPj0.d.cts}

@@ -1,4 +1,4 @@
-import { T as ToolDefinition } from './tools-coIcskZ4.cjs';
+import { T as ToolDefinition } from './tools-DHZhF5km.cjs';
 
 /**
  * MCP (Model Context Protocol) Type Definitions

package/dist/{types-DG2ya08y.d.ts → types-BeFBBZ5i.d.cts}

@@ -1,3 +1,56 @@
+/**
+ * Copilot SDK Logger
+ *
+ * Simple debug logger with console grouping support.
+ *
+ * Usage:
+ *   debug={true}   → enable all logs
+ *   debug={false}  → silent (default)
+ *
+ * Runtime toggle from browser console (no rebuild needed):
+ *   window.__COPILOT_DEBUG = true
+ *   window.__COPILOT_DEBUG = false
+ */
+/** Well-known log scopes — used internally as labels, not exposed to the user. */
+type LogScope = "streaming" | "tools" | "provider" | string;
+/** Debug config accepted by CopilotProvider. true = on, false = off. */
+type DebugConfig = boolean;
+declare global {
+    interface Window {
+        __COPILOT_DEBUG?: boolean;
+    }
+}
+interface ScopedLogger {
+    /** Log a message with optional data */
+    (action: string, data?: unknown): void;
+    /** Open a collapsible group — all subsequent logs nest inside until groupEnd() */
+    group(label: string): void;
+    /** Open a collapsed group (hidden by default in DevTools) */
+    groupCollapsed(label: string): void;
+    /** Close the most recently opened group */
+    groupEnd(): void;
+}
+/**
+ * Create a scoped logger bound to a specific namespace.
+ *
+ * @param scope      - Label shown in brackets, e.g. "streaming", "tools"
+ * @param getEnabled - Returns whether debug logging is currently on
+ *
+ * @example
+ * const log = createLogger("streaming", () => this.config.debug ?? false);
+ * log("sendMessage", { content });
+ * // → [streaming] sendMessage { content: '...' }
+ *
+ * log.groupCollapsed("Stream #1");
+ * log("chunk", { type: "message:start" });  // nested inside group
+ * log.groupEnd();
+ */
+/**
+ * One-shot log — for cases where you don't keep a persistent logger.
+ */
+declare function logOnce(scope: LogScope, enabled: boolean, action: string, data?: unknown): void;
+declare function createLogger(scope: LogScope, getEnabled: () => boolean): ScopedLogger;
+
 /**
  * Message roles in a conversation (OpenAI format)
  */
@@ -131,6 +184,15 @@ interface Message {
     metadata?: MessageMetadata;
     /** When the message was created */
     created_at: Date;
+    /**
+     * Parent message ID for branching support.
+     * - null = root message (no parent)
+     * - undefined = legacy linear message (no branch awareness)
+     * - string = ID of parent message
+     */
+    parent_id?: string | null;
+    /** Direct children IDs for O(1) sibling lookup */
+    children_ids?: string[];
 }
 /**
  * Helper to parse tool call arguments
@@ -153,6 +215,7 @@ declare function createUserMessage(content: string, options?: {
     id?: string;
     thread_id?: string;
     attachments?: MessageAttachment[];
+    parent_id?: string | null;
 }): Message;
 /**
  * Create an assistant message
@@ -364,4 +427,4 @@ interface AsyncThreadStorageAdapter extends ThreadStorageAdapter {
     listThreads?: (options?: ListThreadsOptions) => Promise<ListThreadsResult>;
 }
 
-export { type AsyncThreadStorageAdapter as A, type ListThreadsOptions as L, type Message as M, type PersistenceConfig as P, type Source as S, type Thread as T, type ThreadData as a, type ThreadStorageAdapter as b, type MessageAttachment as c, type MessageRole as d, type MessageMetadata as e, type ToolCall as f, type TokenUsage as g, type ThreadStorageAdapter$1 as h, generateThreadTitle as i, createMessage as j, createUserMessage as k, createAssistantMessage as l, createToolMessage as m, createToolCall as n, hasToolCalls as o, parseToolCallArgs as p, isToolResult as q, type ListThreadsResult as r };
+export { type AsyncThreadStorageAdapter as A, type DebugConfig as D, type ListThreadsOptions as L, type MessageAttachment as M, type PersistenceConfig as P, type Source as S, type ToolCall as T, type Thread as a, type ThreadData as b, type ThreadStorageAdapter as c, type Message as d, createLogger as e, type ScopedLogger as f, type MessageRole as g, type MessageMetadata as h, type TokenUsage as i, type ThreadStorageAdapter$1 as j, generateThreadTitle as k, logOnce as l, createMessage as m, createUserMessage as n, createAssistantMessage as o, createToolMessage as p, createToolCall as q, parseToolCallArgs as r, hasToolCalls as s, isToolResult as t, type ListThreadsResult as u };