From eaf812b2dd581d73acc5339f1dc3a8a5e8700392 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Fri, 6 Mar 2026 13:12:17 +0530
Subject: [PATCH 01/72] feat: add Resolvable pattern for dynamic config
 (v2.1.1)

- Add Resolvable<T> type for static or getter function values
- Support dynamic headers, runtimeUrl, and body props
- Values resolved fresh at request time
- Backward compatible - static values still work

Co-Authored-By: Claude <noreply@anthropic.com>
---
 packages/copilot-sdk/package.json             |   2 +-
 .../copilot-sdk/src/chat/ChatWithTools.ts     |  39 ++++++-
 .../src/chat/adapters/HttpTransport.ts        |  73 ++++++++++++-
 .../src/chat/classes/AbstractChat.ts          |  39 +++++++
 .../src/chat/interfaces/ChatTransport.ts      |  50 ++++++++-
 packages/copilot-sdk/src/chat/types/chat.ts   |  28 ++++-
 packages/copilot-sdk/src/core/utils/index.ts  |   1 +
 .../copilot-sdk/src/core/utils/resolvable.ts  | 101 ++++++++++++++++++
 .../src/react/provider/CopilotProvider.tsx    |  56 +++++++++-
 9 files changed, 368 insertions(+), 21 deletions(-)
 create mode 100644 packages/copilot-sdk/src/core/utils/resolvable.ts

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index 30d5cd8..ace9889 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",
diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index c42d705..766c107 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -16,6 +16,7 @@ import type {
   MessageAttachment,
   PermissionLevel,
 } from "../core";
+import type { Resolvable } from "../core/utils/resolvable";
 import { AbstractChat } from "./classes/AbstractChat";
 import { AbstractAgentLoop } from "./AbstractAgentLoop";
 import type { ChatConfig, ChatCallbacks } from "./types";
@@ -26,18 +27,23 @@ import type { ChatTransport } from "./interfaces/ChatTransport";
 
 /**
  * Configuration for ChatWithTools
+ *
+ * Supports both static values and getter functions for dynamic configuration.
+ * Getter functions are resolved at request time, ensuring fresh values.
  */
 export interface ChatWithToolsConfig {
-  /** Runtime API endpoint */
-  runtimeUrl: string;
+  /** Runtime API endpoint - can be static or getter function */
+  runtimeUrl: Resolvable<string>;
   /** LLM configuration */
   llm?: ChatConfig["llm"];
   /** System prompt */
   systemPrompt?: string;
   /** Enable streaming (default: true) */
   streaming?: boolean;
-  /** Request headers */
-  headers?: Record<string, string>;
+  /** Request headers - can be static or getter function */
+  headers?: Resolvable<Record<string, string>>;
+  /** Additional body properties - can be static or getter function */
+  body?: Resolvable<Record<string, unknown>>;
   /** Thread ID for conversation persistence */
   threadId?: string;
   /** Debug mode */
@@ -125,6 +131,7 @@ export class ChatWithTools {
       systemPrompt: config.systemPrompt,
       streaming: config.streaming,
       headers: config.headers,
+      body: config.body,
       threadId: config.threadId,
       debug: config.debug,
       initialMessages: config.initialMessages,
@@ -372,6 +379,30 @@ export class ChatWithTools {
     this.chat.setSystemPrompt(prompt);
   }
 
+  /**
+   * Set headers configuration
+   * Can be static headers or a getter function for dynamic resolution
+   */
+  setHeaders(headers: ChatWithToolsConfig["headers"]): void {
+    this.chat.setHeaders(headers);
+  }
+
+  /**
+   * Set URL configuration
+   * Can be static URL or a getter function for dynamic resolution
+   */
+  setUrl(url: ChatWithToolsConfig["runtimeUrl"]): void {
+    this.chat.setUrl(url);
+  }
+
+  /**
+   * Set body configuration
+   * Additional properties merged into every request body
+   */
+  setBody(body: ChatWithToolsConfig["body"]): void {
+    this.chat.setBody(body);
+  }
+
   // ============================================
   // Tool Registration
   // ============================================
diff --git a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
index c13ad36..07cb1de 100644
--- a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
+++ b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
@@ -2,6 +2,7 @@
  * HttpTransport - HTTP/SSE implementation of ChatTransport
  *
  * Uses fetch with streaming for SSE responses.
+ * Supports dynamic configuration via getter functions.
  */
 
 import type {
@@ -12,15 +13,29 @@ import type {
   TransportConfig,
 } from "../interfaces";
 import { parseSSELine } from "../functions";
+import { resolveValues } from "../../core/utils/resolvable";
 
 /**
  * HTTP Transport for chat API
  *
+ * Supports both static and dynamic configuration. When using getter functions,
+ * values are resolved fresh on every request.
+ *
  * @example
  * ```typescript
+ * // Static config
  * const transport = new HttpTransport({
  *   url: '/api/chat',
- *   headers: { ... },
+ *   headers: { "x-api-key": "static" },
+ * });
+ *
+ * // Dynamic config (recommended for auth/runtime values)
+ * const transport = new HttpTransport({
+ *   url: () => getApiEndpoint(),
+ *   headers: () => ({
+ *     Authorization: `Bearer ${getToken()}`,
+ *     ...getCustomHeaders(),
+ *   }),
  * });
  *
  * const stream = await transport.send(request);
@@ -44,6 +59,7 @@ export class HttpTransport implements ChatTransport {
 
   /**
    * Send a chat request
+   * Resolves dynamic config values (url, headers, body) fresh at request time
    */
   async send(
     request: ChatRequest,
@@ -53,11 +69,28 @@ export class HttpTransport implements ChatTransport {
     this.streaming = true;
 
     try {
-      const response = await fetch(this.config.url, {
+      // Resolve dynamic values at request time (not constructor time)
+      // This ensures fresh values on every request
+      // Optimized: skips async overhead if all values are static
+      console.log(
+        "[HttpTransport] Config headers type:",
+        typeof this.config.headers,
+      );
+      console.log("[HttpTransport] Config headers:", this.config.headers);
+
+      const resolved = await resolveValues({
+        url: this.config.url,
+        headers: this.config.headers ?? {},
+        configBody: this.config.body ?? {},
+      });
+
+      console.log("[HttpTransport] Resolved headers:", resolved.headers);
+
+      const response = await fetch(resolved.url as string, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          ...this.config.headers,
+          ...(resolved.headers as Record<string, string>),
         },
         body: JSON.stringify({
           messages: request.messages,
@@ -67,6 +100,7 @@ export class HttpTransport implements ChatTransport {
           tools: request.tools,
           actions: request.actions,
           streaming: this.config.streaming,
+          ...(resolved.configBody as Record<string, unknown>),
           ...request.body,
         }),
         signal: this.abortController.signal,
@@ -118,6 +152,39 @@ export class HttpTransport implements ChatTransport {
     return this.streaming;
   }
 
+  /**
+   * Update headers configuration
+   * Can be static headers or a getter function for dynamic resolution
+   *
+   * @example
+   * ```typescript
+   * // Static
+   * transport.setHeaders({ "x-api-key": "new-key" });
+   *
+   * // Dynamic (resolved fresh on each request)
+   * transport.setHeaders(() => ({ Authorization: `Bearer ${getToken()}` }));
+   * ```
+   */
+  setHeaders(headers: TransportConfig["headers"]): void {
+    this.config.headers = headers;
+  }
+
+  /**
+   * Update URL configuration
+   * Can be static URL or a getter function for dynamic resolution
+   */
+  setUrl(url: TransportConfig["url"]): void {
+    this.config.url = url;
+  }
+
+  /**
+   * Update body configuration
+   * Additional properties merged into every request body
+   */
+  setBody(body: TransportConfig["body"]): void {
+    this.config.body = body;
+  }
+
   /**
    * Create an async iterable from a ReadableStream
    */
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 2befd5c..caa4dca 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -182,6 +182,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       systemPrompt: init.systemPrompt,
       streaming: init.streaming ?? true,
       headers: init.headers,
+      body: init.body,
       threadId: init.threadId,
       debug: init.debug,
     };
@@ -192,11 +193,13 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       (new SimpleChatState<T>() as ChatState<T>);
 
     // Use provided transport or create default
+    // Pass Resolvable values - they are resolved at request time
     this.transport =
       init.transport ??
       new HttpTransport({
         url: init.runtimeUrl,
         headers: init.headers,
+        body: init.body,
         streaming: init.streaming ?? true,
       });
 
@@ -576,6 +579,42 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     this.debug("System prompt updated", { length: prompt.length });
   }
 
+  /**
+   * Set headers configuration
+   * Can be static headers or a getter function for dynamic resolution
+   */
+  setHeaders(headers: ChatConfig["headers"]): void {
+    this.config.headers = headers;
+    if (this.transport.setHeaders && headers !== undefined) {
+      this.transport.setHeaders(headers);
+    }
+    this.debug("Headers config updated");
+  }
+
+  /**
+   * Set URL configuration
+   * Can be static URL or a getter function for dynamic resolution
+   */
+  setUrl(url: ChatConfig["runtimeUrl"]): void {
+    this.config.runtimeUrl = url;
+    if (this.transport.setUrl) {
+      this.transport.setUrl(url);
+    }
+    this.debug("URL config updated");
+  }
+
+  /**
+   * Set body configuration
+   * Additional properties merged into every request body
+   */
+  setBody(body: ChatConfig["body"]): void {
+    this.config.body = body;
+    if (this.transport.setBody && body !== undefined) {
+      this.transport.setBody(body);
+    }
+    this.debug("Body config updated");
+  }
+
   /**
    * Build the request payload
    */
diff --git a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
index 0b3ff20..ab7abe5 100644
--- a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
+++ b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
@@ -6,6 +6,7 @@
  */
 
 import type { UIMessage } from "../types";
+import type { Resolvable } from "../../core/utils/resolvable";
 
 /**
  * Chat request to send
@@ -150,16 +151,57 @@ export interface ChatTransport {
    * Check if currently streaming
    */
   isStreaming(): boolean;
+
+  /**
+   * Update headers configuration (optional)
+   * Can be static headers or a getter function for dynamic resolution
+   */
+  setHeaders?(headers: Resolvable<Record<string, string>>): void;
+
+  /**
+   * Update URL configuration (optional)
+   * Can be static URL or a getter function for dynamic resolution
+   */
+  setUrl?(url: Resolvable<string>): void;
+
+  /**
+   * Update body configuration (optional)
+   * Additional properties merged into every request body
+   */
+  setBody?(body: Resolvable<Record<string, unknown>>): void;
 }
 
 /**
  * Transport configuration
+ *
+ * Supports both static values and getter functions for dynamic configuration.
+ * Getter functions are resolved at request time, ensuring fresh values.
+ *
+ * @example
+ * ```typescript
+ * // Static config
+ * const config: TransportConfig = {
+ *   url: "/api/chat",
+ *   headers: { "x-api-key": "static-key" },
+ * };
+ *
+ * // Dynamic config (resolved fresh on each request)
+ * const config: TransportConfig = {
+ *   url: () => getApiUrl(),
+ *   headers: () => ({
+ *     Authorization: `Bearer ${getToken()}`,
+ *     ...getCustomHeaders(),
+ *   }),
+ * };
+ * ```
  */
 export interface TransportConfig {
-  /** API endpoint URL */
-  url: string;
-  /** Request headers */
-  headers?: Record<string, string>;
+  /** API endpoint URL - can be static or getter function */
+  url: Resolvable<string>;
+  /** Request headers - can be static or getter function */
+  headers?: Resolvable<Record<string, string>>;
+  /** Additional body properties - can be static or getter function */
+  body?: Resolvable<Record<string, unknown>>;
   /** Enable streaming (default: true) */
   streaming?: boolean;
   /** Request timeout in ms */
diff --git a/packages/copilot-sdk/src/chat/types/chat.ts b/packages/copilot-sdk/src/chat/types/chat.ts
index df413c4..f59c1d9 100644
--- a/packages/copilot-sdk/src/chat/types/chat.ts
+++ b/packages/copilot-sdk/src/chat/types/chat.ts
@@ -5,6 +5,7 @@
  */
 
 import type { LLMConfig, MessageAttachment, ToolDefinition } from "../../core";
+import type { Resolvable } from "../../core/utils/resolvable";
 import type { UIMessage } from "./message";
 
 /**
@@ -14,18 +15,37 @@ export type ChatStatus = "ready" | "submitted" | "streaming" | "error";
 
 /**
  * Chat configuration
+ *
+ * Supports both static values and getter functions for dynamic configuration.
+ * Using getter functions ensures fresh values on every request.
+ *
+ * @example
+ * ```typescript
+ * const config: ChatConfig = {
+ *   // Static URL
+ *   runtimeUrl: "/api/chat",
+ *
+ *   // Dynamic headers - resolved fresh on every request
+ *   headers: () => ({
+ *     Authorization: `Bearer ${getToken()}`,
+ *     ...getCustomHeaders(),
+ *   }),
+ * };
+ * ```
  */
 export interface ChatConfig {
-  /** Runtime API endpoint */
-  runtimeUrl: string;
+  /** Runtime API endpoint - can be static or getter function */
+  runtimeUrl: Resolvable<string>;
   /** LLM configuration */
   llm?: Partial<LLMConfig>;
   /** System prompt */
   systemPrompt?: string;
   /** Enable streaming (default: true) */
   streaming?: boolean;
-  /** Request headers */
-  headers?: Record<string, string>;
+  /** Request headers - can be static or getter function */
+  headers?: Resolvable<Record<string, string>>;
+  /** Additional body properties - can be static or getter function */
+  body?: Resolvable<Record<string, unknown>>;
   /** Thread ID for conversation persistence */
   threadId?: string;
   /** Debug mode */
diff --git a/packages/copilot-sdk/src/core/utils/index.ts b/packages/copilot-sdk/src/core/utils/index.ts
index 57cb684..a780015 100644
--- a/packages/copilot-sdk/src/core/utils/index.ts
+++ b/packages/copilot-sdk/src/core/utils/index.ts
@@ -2,3 +2,4 @@ export * from "./stream";
 export * from "./id";
 export * from "./zod-to-json-schema";
 export * from "./attachments";
+export * from "./resolvable";
diff --git a/packages/copilot-sdk/src/core/utils/resolvable.ts b/packages/copilot-sdk/src/core/utils/resolvable.ts
new file mode 100644
index 0000000..596b6d5
--- /dev/null
+++ b/packages/copilot-sdk/src/core/utils/resolvable.ts
@@ -0,0 +1,101 @@
+/**
+ * Resolvable - Type utility for values that can be static or dynamic
+ *
+ * This pattern allows SDK consumers to pass either:
+ * - Static value: `headers: { "x-api-key": "abc123" }`
+ * - Getter function: `headers: () => ({ "x-api-key": getToken() })`
+ *
+ * Values are resolved at request time, ensuring fresh data on every API call.
+ * This is the modern pattern used by tanstack-query, tRPC, and axios interceptors.
+ *
+ * @example
+ * ```tsx
+ * // Static (for values that never change)
+ * <CopilotProvider headers={{ "x-api-key": "static-key" }} />
+ *
+ * // Dynamic (for values that change at runtime)
+ * <CopilotProvider
+ *   headers={() => ({
+ *     Authorization: `Bearer ${getToken()}`,
+ *     ...getCustomHeaders(),
+ *   })}
+ * />
+ * ```
+ */
+
+/**
+ * A value that can be either static or a getter function
+ * Getter can be sync or async for flexibility
+ */
+export type Resolvable<T> = T | (() => T) | (() => Promise<T>);
+
+/**
+ * Check if a value is a getter function
+ */
+export function isGetter<T>(
+  value: Resolvable<T>,
+): value is (() => T) | (() => Promise<T>) {
+  return typeof value === "function";
+}
+
+/**
+ * Resolve a potentially dynamic value
+ * Handles: static value, sync getter, or async getter
+ * Optimized: skips async overhead for static values
+ */
+export async function resolveValue<T>(value: Resolvable<T>): Promise<T> {
+  if (!isGetter(value)) {
+    return value;
+  }
+  try {
+    return await value();
+  } catch (error) {
+    console.error("[Copilot SDK] Error resolving dynamic config value:", error);
+    throw error;
+  }
+}
+
+/**
+ * Resolve multiple values in parallel
+ * Optimized: only uses Promise.all if there are actual getters
+ */
+export async function resolveValues<
+  T extends Record<string, Resolvable<unknown>>,
+>(
+  values: T,
+): Promise<{ [K in keyof T]: T[K] extends Resolvable<infer U> ? U : T[K] }> {
+  const entries = Object.entries(values);
+  const hasGetters = entries.some(([, v]) => isGetter(v));
+
+  if (!hasGetters) {
+    // Fast path: no getters, return as-is
+    return values as {
+      [K in keyof T]: T[K] extends Resolvable<infer U> ? U : T[K];
+    };
+  }
+
+  // Resolve all values in parallel
+  const resolved = await Promise.all(
+    entries.map(async ([key, val]) => [key, await resolveValue(val)]),
+  );
+
+  return Object.fromEntries(resolved) as {
+    [K in keyof T]: T[K] extends Resolvable<infer U> ? U : T[K];
+  };
+}
+
+/**
+ * Resolve a potentially dynamic value (sync only)
+ * Use when you know the getter is synchronous
+ */
+export function resolveValueSync<T>(value: T | (() => T)): T {
+  if (typeof value === "function") {
+    return (value as () => T)();
+  }
+  return value;
+}
+
+/**
+ * Type to extract the resolved type from a Resolvable
+ */
+export type ResolvedType<T> = T extends Resolvable<infer U> ? U : T;
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index fca9380..531d697 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -28,6 +28,7 @@ import type {
 } from "../../core";
 
 import type { MCPServerConfig } from "../../mcp/types";
+import type { Resolvable } from "../../core/utils/resolvable";
 
 import type { UIMessage, ToolExecution } from "../../chat";
 
@@ -66,8 +67,11 @@ function MCPConnection({ config }: { config: MCPServerConfig }) {
 
 export interface CopilotProviderProps {
   children: React.ReactNode;
-  /** Runtime API endpoint URL */
-  runtimeUrl: string;
+  /**
+   * Runtime API endpoint URL
+   * Can be static string or getter function for dynamic resolution.
+   */
+  runtimeUrl: Resolvable<string>;
   /** System prompt sent with each request */
   systemPrompt?: string;
   /** @deprecated Use useTools() hook instead */
@@ -82,8 +86,16 @@ export interface CopilotProviderProps {
   onError?: (error: Error) => void;
   /** Enable/disable streaming (default: true) */
   streaming?: boolean;
-  /** Custom headers to send with each request */
-  headers?: Record<string, string>;
+  /**
+   * Custom headers to send with each request
+   * Can be static object or getter function for dynamic resolution.
+   */
+  headers?: Resolvable<Record<string, string>>;
+  /**
+   * Additional body properties to include in each request
+   * Can be static object or getter function for dynamic resolution.
+   */
+  body?: Resolvable<Record<string, unknown>>;
   /** Enable debug logging */
   debug?: boolean;
   /** Max tool execution iterations (default: 20) */
@@ -142,7 +154,11 @@ export interface CopilotContextValue {
 
   // Config
   threadId?: string;
-  runtimeUrl: string;
+  /**
+   * Runtime URL configuration.
+   * Can be a static string or getter function (matches what was passed to provider).
+   */
+  runtimeUrl: Resolvable<string>;
   toolsConfig?: ToolsConfig;
 }
 
@@ -175,6 +191,7 @@ export function CopilotProvider({
   onError,
   streaming,
   headers,
+  body,
   debug = false,
   maxIterations,
   maxIterationsMessage,
@@ -240,6 +257,7 @@ export function CopilotProvider({
         initialMessages: uiInitialMessages,
         streaming,
         headers,
+        body,
         debug,
         maxIterations,
         maxIterationsMessage,
@@ -271,6 +289,34 @@ export function CopilotProvider({
     }
   }, [systemPrompt, debugLog]);
 
+  // ============================================
+  // Headers & Body Reactivity
+  // ============================================
+
+  // Watch for headers prop changes and update chat
+  useEffect(() => {
+    if (chatRef.current && headers !== undefined) {
+      chatRef.current.setHeaders(headers);
+      debugLog("Headers config updated from prop");
+    }
+  }, [headers, debugLog]);
+
+  // Watch for body prop changes
+  useEffect(() => {
+    if (chatRef.current && body !== undefined) {
+      chatRef.current.setBody(body);
+      debugLog("Body config updated from prop");
+    }
+  }, [body, debugLog]);
+
+  // Watch for runtimeUrl prop changes
+  useEffect(() => {
+    if (chatRef.current && runtimeUrl !== undefined) {
+      chatRef.current.setUrl(runtimeUrl);
+      debugLog("URL config updated from prop");
+    }
+  }, [runtimeUrl, debugLog]);
+
   // Subscribe to chat state with useSyncExternalStore
   const messages = useSyncExternalStore(
     chatRef.current.subscribe,

From 51feaf5fefde4375dcc859bd37bf03c28fafb837 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 9 Mar 2026 11:46:42 +0530
Subject: [PATCH 02/72] feat: integrate Anthropic SDK and enhance tool
 execution tracking

- Added '@anthropic-ai/sdk' dependency to the project.
- Introduced a new test page for the Express demo showcasing custom tool renderers.
- Enhanced server-side tool execution tracking with hidden flags to manage UI visibility.
- Updated environment variables and package versions for better integration.
- Improved knowledge base search functionality and tool execution management in the Copilot SDK.
---
 .../app/test-express-demo/page.tsx            | 361 +++++++++++++++++
 .../app/test-max-iterations/page.tsx          |   3 -
 examples/express-demo/.env.example            |   3 +
 examples/express-demo/package.json            |   1 +
 examples/express-demo/src/index.ts            | 372 ++++++++++++++----
 packages/copilot-sdk/package.json             |   2 +-
 .../copilot-sdk/src/chat/AbstractAgentLoop.ts |  67 +++-
 .../copilot-sdk/src/chat/ChatWithTools.ts     |  60 +++
 .../src/chat/adapters/HttpTransport.ts        |   8 -
 .../src/chat/classes/AbstractChat.ts          | 220 ++++++++++-
 .../src/chat/functions/stream/processChunk.ts |   1 +
 .../src/chat/interfaces/ChatTransport.ts      |  22 +-
 packages/copilot-sdk/src/chat/types/chat.ts   |  18 +
 packages/copilot-sdk/src/chat/types/index.ts  |   1 +
 .../copilot-sdk/src/chat/types/message.ts     |   2 +
 packages/copilot-sdk/src/chat/types/tool.ts   |   5 +
 packages/copilot-sdk/src/core/index.ts        |   1 +
 packages/copilot-sdk/src/core/types/tools.ts  |  30 +-
 .../src/react/hooks/useToolExecutor.ts        |   1 +
 packages/copilot-sdk/src/react/index.ts       |   7 +
 .../composed/chat/default-message.tsx         |  16 +-
 .../ui/components/composed/connected-chat.tsx |  41 +-
 .../composed/tools/tool-execution-list.tsx    |   5 +
 packages/llm-sdk/package.json                 |   2 +-
 packages/llm-sdk/src/adapters/anthropic.ts    |  50 ++-
 packages/llm-sdk/src/core/stream-events.ts    |  11 +
 .../src/providers/anthropic/provider.ts       |  72 ++--
 packages/llm-sdk/src/server/agent-loop.ts     |   3 +-
 packages/llm-sdk/src/server/runtime.ts        |   7 +
 packages/llm-sdk/src/server/stream-result.ts  |  23 ++
 pnpm-lock.yaml                                |   3 +
 31 files changed, 1255 insertions(+), 163 deletions(-)
 create mode 100644 examples/experimental/app/test-express-demo/page.tsx

diff --git a/examples/experimental/app/test-express-demo/page.tsx b/examples/experimental/app/test-express-demo/page.tsx
new file mode 100644
index 0000000..d971493
--- /dev/null
+++ b/examples/experimental/app/test-express-demo/page.tsx
@@ -0,0 +1,361 @@
+"use client";
+
+import { useState } from "react";
+import { CopilotProvider, useTools, tool } from "@yourgpt/copilot-sdk/react";
+import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
+import "@yourgpt/copilot-sdk/ui/styles.css";
+import "@yourgpt/copilot-sdk/ui/themes/claude.css";
+
+// ============================================
+// CUSTOM TOOL RENDERERS
+// ============================================
+
+/**
+ * Custom renderer for get_current_time tool (server-side)
+ */
+function TimeCard({
+  execution,
+}: {
+  execution: { status: string; result?: unknown; error?: string };
+}) {
+  if (execution.status === "executing") {
+    return (
+      <div className="flex items-center gap-2 p-3 rounded-lg bg-muted/50 animate-pulse">
+        <span className="text-lg">🕐</span>
+        <span className="text-sm text-muted-foreground">Getting time...</span>
+      </div>
+    );
+  }
+
+  if (execution.status === "error" || execution.status === "failed") {
+    return (
+      <div className="flex items-center gap-2 p-3 rounded-lg bg-destructive/10 text-destructive">
+        <span className="text-lg">❌</span>
+        <span className="text-sm">
+          {execution.error || "Failed to get time"}
+        </span>
+      </div>
+    );
+  }
+
+  const result = execution.result as {
+    time?: string;
+    timezone?: string;
+  } | null;
+
+  if (!result?.time) {
+    return null;
+  }
+
+  const date = new Date(result.time);
+  const formattedTime = date.toLocaleTimeString("en-US", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: true,
+  });
+  const formattedDate = date.toLocaleDateString("en-US", {
+    weekday: "long",
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+  });
+
+  return (
+    <div className="flex items-center gap-3 p-4 rounded-xl bg-gradient-to-r from-blue-500/10 to-purple-500/10 border border-blue-500/20">
+      <div className="text-4xl">🕐</div>
+      <div className="flex flex-col">
+        <span className="text-2xl font-bold tracking-tight">
+          {formattedTime}
+        </span>
+        <span className="text-sm text-muted-foreground">{formattedDate}</span>
+        {result.timezone && (
+          <span className="text-xs text-muted-foreground/70 mt-1">
+            📍 {result.timezone}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Custom renderer for calculate_expression tool (frontend)
+ */
+function CalculatorCard({
+  execution,
+}: {
+  execution: {
+    status: string;
+    result?: unknown;
+    error?: string;
+    args: Record<string, unknown>;
+  };
+}) {
+  if (execution.status === "executing") {
+    return (
+      <div className="flex items-center gap-2 p-3 rounded-lg bg-muted/50 animate-pulse">
+        <span className="text-lg">🧮</span>
+        <span className="text-sm text-muted-foreground">Calculating...</span>
+      </div>
+    );
+  }
+
+  if (execution.status === "error" || execution.status === "failed") {
+    return (
+      <div className="flex items-center gap-2 p-3 rounded-lg bg-destructive/10 text-destructive">
+        <span className="text-lg">❌</span>
+        <span className="text-sm">
+          {execution.error || "Calculation failed"}
+        </span>
+      </div>
+    );
+  }
+
+  const result = execution.result as {
+    expression?: string;
+    result?: number;
+  } | null;
+  const expression =
+    (execution.args?.expression as string) || result?.expression || "";
+
+  return (
+    <div className="flex items-center gap-3 p-4 rounded-xl bg-gradient-to-r from-green-500/10 to-emerald-500/10 border border-green-500/20">
+      <div className="text-4xl">🧮</div>
+      <div className="flex flex-col">
+        <span className="text-sm text-muted-foreground font-mono">
+          {expression}
+        </span>
+        <span className="text-3xl font-bold tracking-tight">
+          {result?.result}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Custom renderer for get_user_location tool (frontend)
+ */
+function LocationCard({
+  execution,
+}: {
+  execution: { status: string; result?: unknown; error?: string };
+}) {
+  if (execution.status === "executing") {
+    return (
+      <div className="flex items-center gap-2 p-3 rounded-lg bg-muted/50 animate-pulse">
+        <span className="text-lg">📍</span>
+        <span className="text-sm text-muted-foreground">
+          Getting location...
+        </span>
+      </div>
+    );
+  }
+
+  if (execution.status === "error" || execution.status === "failed") {
+    return (
+      <div className="flex items-center gap-2 p-3 rounded-lg bg-destructive/10 text-destructive">
+        <span className="text-lg">❌</span>
+        <span className="text-sm">
+          {execution.error || "Failed to get location"}
+        </span>
+      </div>
+    );
+  }
+
+  const result = execution.result as {
+    city?: string;
+    country?: string;
+    coordinates?: { lat: number; lng: number };
+  } | null;
+
+  if (!result) {
+    return null;
+  }
+
+  return (
+    <div className="flex items-center gap-3 p-4 rounded-xl bg-gradient-to-r from-orange-500/10 to-amber-500/10 border border-orange-500/20">
+      <div className="text-4xl">📍</div>
+      <div className="flex flex-col">
+        <span className="text-xl font-bold">{result.city}</span>
+        <span className="text-sm text-muted-foreground">{result.country}</span>
+        {result.coordinates && (
+          <span className="text-xs text-muted-foreground/70 mt-1 font-mono">
+            {result.coordinates.lat.toFixed(4)},{" "}
+            {result.coordinates.lng.toFixed(4)}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ============================================
+// FRONTEND TOOLS REGISTRATION
+// ============================================
+
+/**
+ * Component that registers frontend tools
+ */
+function FrontendToolsRegistration() {
+  useTools({
+    calculate_expression: tool({
+      description:
+        "Calculate a mathematical expression. Use this when the user asks to compute math.",
+      location: "client",
+      inputSchema: {
+        type: "object",
+        properties: {
+          expression: {
+            type: "string",
+            description:
+              "The math expression to evaluate (e.g., '2 + 2', '10 * 5')",
+          },
+        },
+        required: ["expression"],
+      },
+      handler: async (params) => {
+        const { expression } = params as { expression: string };
+        try {
+          // Safe math evaluation using Function constructor (safer than eval)
+          const sanitized = expression.replace(/[^0-9+\-*/().%\s]/g, "");
+          // eslint-disable-next-line @typescript-eslint/no-implied-eval
+          const result = new Function(`return ${sanitized}`)();
+          return {
+            success: true,
+            expression,
+            result: Number(result),
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: `Invalid expression: ${error instanceof Error ? error.message : "Unknown error"}`,
+          };
+        }
+      },
+    }),
+    get_user_location: tool({
+      description:
+        "Get the user's current location (simulated). Use this when user asks about their location.",
+      location: "client",
+      inputSchema: {
+        type: "object",
+        properties: {},
+      },
+      handler: async () => {
+        // Simulate async location lookup
+        await new Promise((resolve) => setTimeout(resolve, 500));
+
+        // Simulated location data
+        return {
+          success: true,
+          city: "San Francisco",
+          country: "United States",
+          coordinates: {
+            lat: 37.7749,
+            lng: -122.4194,
+          },
+        };
+      },
+    }),
+  });
+
+  return null;
+}
+
+// ============================================
+// MAIN PAGE COMPONENT
+// ============================================
+
+/**
+ * Test page for Express Demo with server-side + frontend tools
+ *
+ * Make sure express-demo is running on port 3001:
+ *   cd examples/express-demo && pnpm dev
+ *
+ * Then run experimental:
+ *   cd examples/experimental && pnpm dev
+ *
+ * Visit: http://localhost:3000/test-express-demo
+ */
+export default function TestExpressDemoPage() {
+  const [isStreaming, setIsStreaming] = useState(true);
+
+  const runtimeUrl = isStreaming
+    ? "http://localhost:3001/api/copilot/stream"
+    : "http://localhost:3001/api/copilot/chat";
+
+  return (
+    <div className="h-screen w-full flex flex-col">
+      <header className="p-4 border-b bg-card">
+        <div className="flex items-center justify-between">
+          <div>
+            <h1 className="text-lg font-semibold">
+              Express Demo - Full Tools Test
+            </h1>
+            <p className="text-sm text-muted-foreground">
+              <span className="font-medium text-purple-500">Server:</span>{" "}
+              search_knowledge_base (hidden), get_current_time
+              {" | "}
+              <span className="font-medium text-green-500">Frontend:</span>{" "}
+              calculate_expression, get_user_location
+            </p>
+          </div>
+          <div className="flex items-center gap-2">
+            <label className="text-sm text-muted-foreground">Mode:</label>
+            <button
+              onClick={() => setIsStreaming(!isStreaming)}
+              className={`px-3 py-1.5 rounded-md text-sm font-medium transition-colors ${isStreaming ? "bg-green-500/20 text-green-600 border border-green-500/30" : "bg-blue-500/20 text-blue-600 border border-blue-500/30"}`}
+            >
+              {isStreaming ? "🔴 Streaming" : "📦 Non-Streaming"}
+            </button>
+          </div>
+        </div>
+        <div className="mt-2 text-xs text-muted-foreground">
+          <code>{runtimeUrl}</code>
+        </div>
+      </header>
+
+      <div className="flex-1" key={isStreaming ? "stream" : "chat"}>
+        <CopilotProvider
+          runtimeUrl={runtimeUrl}
+          streaming={isStreaming}
+          systemPrompt={`You are a helpful assistant with access to multiple tools:
+
+SERVER-SIDE TOOLS (executed on the server):
+- search_knowledge_base: Search for information about YourGPT SDK
+- get_current_time: Get the current server time
+
+FRONTEND TOOLS (executed in the browser):
+- calculate_expression: Evaluate math expressions
+- get_user_location: Get the user's location
+
+Use these tools when appropriate to help the user.`}
+          debug={true}
+          maxIterations={5}
+        >
+          <FrontendToolsRegistration />
+          <CopilotChat
+            showHeader
+            showThreadPicker
+            persistence
+            className="h-full csdk-theme-claude"
+            placeholder="Try: 'What is YourGPT SDK?', 'Calculate 25 * 4', 'What's my location?', 'What time is it?'"
+            suggestions={[
+              "What is YourGPT SDK?",
+              "Calculate 25 * 4 + 10",
+              "What's my location?",
+              "What time is it?",
+            ]}
+            toolRenderers={{
+              get_current_time: TimeCard,
+              calculate_expression: CalculatorCard,
+              get_user_location: LocationCard,
+            }}
+          />
+        </CopilotProvider>
+      </div>
+    </div>
+  );
+}
diff --git a/examples/experimental/app/test-max-iterations/page.tsx b/examples/experimental/app/test-max-iterations/page.tsx
index 486db26..ec229f4 100644
--- a/examples/experimental/app/test-max-iterations/page.tsx
+++ b/examples/experimental/app/test-max-iterations/page.tsx
@@ -46,7 +46,6 @@ function TestTools() {
   useTools({
     // Step 1: Initialize a process
     step1_initialize: {
-      name: "step1_initialize",
       location: "client",
       description:
         "Step 1: Initialize a multi-step process. MUST be called first before step2.",
@@ -71,7 +70,6 @@ function TestTools() {
 
     // Step 2: Process
     step2_process: {
-      name: "step2_process",
       location: "client",
       description:
         "Step 2: Process the initialized task. Call this after step1_initialize.",
@@ -96,7 +94,6 @@ function TestTools() {
 
     // Step 3: Finalize
     step3_finalize: {
-      name: "step3_finalize",
       location: "client",
       description:
         "Step 3: Finalize and complete the process. Call this after step2_process.",
diff --git a/examples/express-demo/.env.example b/examples/express-demo/.env.example
index 6494087..a3947e3 100644
--- a/examples/express-demo/.env.example
+++ b/examples/express-demo/.env.example
@@ -1,2 +1,5 @@
+# Choose one provider (Anthropic preferred for server-side tools)
+ANTHROPIC_API_KEY=sk-ant-your-key-here
 OPENAI_API_KEY=sk-your-key-here
+
 PORT=3001
diff --git a/examples/express-demo/package.json b/examples/express-demo/package.json
index c771188..b8c30c0 100644
--- a/examples/express-demo/package.json
+++ b/examples/express-demo/package.json
@@ -8,6 +8,7 @@
     "start": "tsx src/index.ts"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
     "@yourgpt/llm-sdk": "workspace:*",
     "cors": "^2.8.5",
     "dotenv": "^16.4.0",
diff --git a/examples/express-demo/src/index.ts b/examples/express-demo/src/index.ts
index 1f29bef..a289289 100644
--- a/examples/express-demo/src/index.ts
+++ b/examples/express-demo/src/index.ts
@@ -1,42 +1,214 @@
 import "dotenv/config";
 import express from "express";
 import cors from "cors";
-import { createRuntime } from "@yourgpt/llm-sdk";
+import { createRuntime, type ToolDefinition } from "@yourgpt/llm-sdk";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
 import { createOpenAI } from "@yourgpt/llm-sdk/openai";
 
 const app = express();
 app.use(cors());
 app.use(express.json());
 
-// Create runtime once at startup
+// ============================================
+// DUMMY KNOWLEDGE BASE DATA
+// ============================================
+
+const KNOWLEDGE_BASE_DATA = [
+  {
+    doc_id: "kb_001",
+    content:
+      "YourGPT Copilot SDK is a powerful toolkit for building AI-powered chat interfaces. It supports multiple LLM providers including OpenAI, Anthropic Claude, Google Gemini, and local models via Ollama.",
+    score: 0.95,
+  },
+  {
+    doc_id: "kb_002",
+    content:
+      "To install the SDK, run: npm install @yourgpt/llm-sdk. The SDK provides createRuntime() for server-side usage and CopilotProvider for React clients.",
+    score: 0.92,
+  },
+  {
+    doc_id: "kb_003",
+    content:
+      "Server-side tools are defined with location: 'server' and include a handler function. The handler is executed on the server and results are sent back to the LLM for processing.",
+    score: 0.89,
+  },
+  {
+    doc_id: "kb_004",
+    content:
+      "The agent loop automatically handles multi-turn tool calls. Configure maxIterations in agentLoop config to limit the number of turns. Default is 20 iterations.",
+    score: 0.87,
+  },
+  {
+    doc_id: "kb_005",
+    content:
+      "For billing and usage tracking, use the onFinish callback which provides token usage data. Usage data is available server-side only and is stripped before sending to clients.",
+    score: 0.85,
+  },
+  {
+    doc_id: "kb_006",
+    content:
+      "Pricing for YourGPT services: Basic plan is $29/month with 100k tokens. Pro plan is $99/month with 1M tokens. Enterprise plans with custom limits available.",
+    score: 0.82,
+  },
+  {
+    doc_id: "kb_007",
+    content:
+      "To enable debug logging, set debug: true in createRuntime config. This will log all tool calls, LLM requests, and streaming events to the console.",
+    score: 0.8,
+  },
+];
+
+// ============================================
+// SERVER-SIDE TOOL: SEARCH KNOWLEDGE BASE
+// ============================================
+
+const serverTools: ToolDefinition[] = [
+  {
+    name: "search_knowledge_base",
+    description:
+      "Search the knowledge base for relevant documents. Use this when the user asks questions about YourGPT, the SDK, pricing, features, or how to use the product.",
+    location: "server",
+    // HIDDEN: This tool runs silently - user won't see it in the chat UI
+    hidden: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "The search query to find relevant documents",
+        },
+        limit: {
+          type: "number",
+          description: "Maximum number of results to return (1-10)",
+        },
+      },
+      required: ["query"],
+    },
+    handler: async (params) => {
+      const args = params as { query: string; limit?: number };
+      const searchLimit = Math.min(Math.max(args.limit || 3, 1), 10);
+
+      console.log(
+        `\n[search_knowledge_base] Query: "${args.query}", Limit: ${searchLimit}`,
+      );
+
+      // Simulate search delay
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Simple keyword matching for demo
+      const query = args.query.toLowerCase();
+      const results = KNOWLEDGE_BASE_DATA.filter((doc) =>
+        doc.content.toLowerCase().includes(query.split(" ")[0]),
+      )
+        .slice(0, searchLimit)
+        .map((doc) => ({
+          content: doc.content,
+          score: doc.score,
+          doc_id: doc.doc_id,
+        }));
+
+      // If no matches, return top results
+      if (results.length === 0) {
+        const topResults = KNOWLEDGE_BASE_DATA.slice(0, searchLimit).map(
+          (doc) => ({
+            content: doc.content,
+            score: doc.score,
+            doc_id: doc.doc_id,
+          }),
+        );
+        console.log(
+          `[search_knowledge_base] No exact matches, returning top ${topResults.length} results`,
+        );
+        return { results: topResults };
+      }
+
+      console.log(`[search_knowledge_base] Found ${results.length} results`);
+      return { results };
+    },
+  },
+  {
+    name: "get_current_time",
+    description: "Get the current server time",
+    location: "server",
+    // VISIBLE: This tool will show in the chat UI (hidden: false is default)
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+    handler: async () => {
+      const now = new Date();
+      console.log(`\n[get_current_time] ${now.toISOString()}`);
+      return {
+        time: now.toISOString(),
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+      };
+    },
+  },
+];
+
+// ============================================
+// CREATE PROVIDERS
+// ============================================
+
+// Anthropic Provider (preferred for server-side tools)
+const anthropic = createAnthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+// OpenAI Provider (fallback)
 const openai = createOpenAI({
   apiKey: process.env.OPENAI_API_KEY,
 });
 
+// Choose provider based on env
+const provider = process.env.ANTHROPIC_API_KEY ? anthropic : openai;
+const model = process.env.ANTHROPIC_API_KEY
+  ? "claude-haiku-4-5"
+  : "gpt-4o-mini";
+
+console.log(
+  `Using provider: ${process.env.ANTHROPIC_API_KEY ? "Anthropic" : "OpenAI"}`,
+);
+console.log(`Using model: ${model}`);
+
+// ============================================
+// CREATE RUNTIME WITH SERVER-SIDE TOOLS
+// ============================================
+
 const runtime = createRuntime({
-  provider: openai,
-  model: "gpt-5.2",
-  systemPrompt: "You are a helpful AI assistant. Keep responses concise.",
+  provider,
+  model,
+  systemPrompt: `You are a helpful AI assistant for YourGPT. You have access to a knowledge base tool to search for information about YourGPT products, SDK, pricing, and features.
+
+IMPORTANT: When the user asks about YourGPT, the SDK, pricing, or any product-related question, ALWAYS use the search_knowledge_base tool first to find accurate information before responding.
+
+Be helpful, concise, and accurate. If the knowledge base doesn't have the answer, say so.`,
+  debug: true,
+  tools: serverTools,
+  agentLoop: {
+    enabled: true,
+    maxIterations: 5,
+    debug: true,
+  },
 });
 
 // ============================================
 // COPILOT SDK COMPATIBLE ENDPOINTS
-// Use these with CopilotProvider
 // ============================================
 
 /**
  * Streaming (SSE) - Primary endpoint for Copilot SDK
- * Returns: text/event-stream with SSE events
  */
 app.post("/api/copilot/stream", async (req, res) => {
-  console.log("[/api/copilot/stream] SSE streaming");
-  //log headers
-  console.log("Headers:", req.headers);
+  console.log("\n========================================");
+  console.log("[/api/copilot/stream] SSE streaming request");
+  console.log("Messages:", JSON.stringify(req.body.messages, null, 2));
+  console.log("========================================\n");
 
   await runtime
     .stream(req.body, {
       onFinish: ({ messages, usage }) => {
-        console.log("\n=== onFinish ===");
+        console.log("\n=== Stream Complete ===");
         console.log("Messages:", messages.length);
         console.log("Usage:", usage);
       },
@@ -46,47 +218,92 @@ app.post("/api/copilot/stream", async (req, res) => {
 
 /**
  * Non-streaming - For Copilot SDK with streaming={false}
- * Returns: { text, messages, toolCalls } (usage stripped)
  */
 app.post("/api/copilot/chat", async (req, res) => {
-  console.log("[/api/copilot/chat] Non-streaming JSON");
+  console.log("\n========================================");
+  console.log("[/api/copilot/chat] Non-streaming request");
+  console.log("Messages:", JSON.stringify(req.body.messages, null, 2));
+  console.log("========================================\n");
 
-  // Usage is now included in result - strip before sending to client
   const { usage, ...clientResult } = await runtime.chat(req.body);
 
-  // Log usage server-side for billing
   if (usage) {
-    console.log("[/api/copilot/chat] Usage:", usage);
+    console.log("\n=== Chat Complete ===");
+    console.log("Usage:", usage);
   }
 
-  // Send to client without usage
   res.json(clientResult);
 });
 
 /**
  * Express handler - One-liner alternative
- * Returns: text/event-stream with SSE events
  */
 app.post("/api/copilot/handler", runtime.expressHandler());
 
 // ============================================
-// RAW STREAMING ENDPOINTS
-// For custom clients (NOT Copilot SDK)
+// DIRECT TEST ENDPOINT (bypasses CopilotProvider format)
 // ============================================
 
 /**
- * Raw text stream - Plain text chunks
- * Returns: text/plain stream
+ * Direct test endpoint that mimics the CopilotController pattern
+ * Similar to what's used in the real YourGPT Copilot backend
  */
+app.post("/api/test/copilot-response", async (req, res) => {
+  console.log("\n========================================");
+  console.log("[/api/test/copilot-response] Direct API test");
+  console.log("Body:", JSON.stringify(req.body, null, 2));
+  console.log("========================================\n");
+
+  try {
+    const { messages, system, temperature, max_tokens } = req.body;
+
+    if (!messages || !Array.isArray(messages) || messages.length === 0) {
+      return res.status(400).json({
+        type: "RXERROR",
+        message: "Invalid params: messages array is required",
+      });
+    }
+
+    // Use runtime.chat() for non-streaming response (like the original code)
+    const result = await runtime.chat({
+      messages,
+      systemPrompt: system,
+      config: {
+        temperature,
+        maxTokens: max_tokens || 4096,
+      },
+    });
+
+    console.log("\n=== Response Complete ===");
+    console.log("Text length:", result.text?.length || 0);
+    console.log("Tool calls:", result.toolCalls?.length || 0);
+    console.log("Messages:", result.messages?.length || 0);
+
+    // Return in the format expected by the original controller
+    return res.status(200).json({
+      text: result.text,
+      messages: result.messages,
+      toolCalls: result.toolCalls,
+    });
+  } catch (error) {
+    console.error("[/api/test/copilot-response] Error:", error);
+    return res.status(500).json({
+      type: "RXERROR",
+      message: "Failed to process copilot request",
+      error: error instanceof Error ? error.message : "Unknown error",
+    });
+  }
+});
+
+// ============================================
+// RAW STREAMING ENDPOINTS
+// ============================================
+
 app.post("/api/raw/stream/text", async (req, res) => {
   console.log("[/api/raw/stream/text] Plain text streaming");
   await runtime.stream(req.body).pipeTextToResponse(res);
 });
 
-/**
- * Raw stream with events - Stream with logging
- * Returns: text/event-stream (but logs events server-side)
- */
 app.post("/api/raw/stream/events", async (req, res) => {
   console.log("[/api/raw/stream/events] Streaming with event handlers");
 
@@ -110,23 +327,14 @@ app.post("/api/raw/stream/events", async (req, res) => {
 
 // ============================================
 // RAW NON-STREAMING ENDPOINTS
-// For custom clients (NOT Copilot SDK)
 // ============================================
 
-/**
- * Generate text only
- * Returns: { text: string }
- */
 app.post("/api/raw/generate/text", async (req, res) => {
   console.log("[/api/raw/generate/text] Text only response");
   const text = await runtime.stream(req.body).text();
   res.json({ text });
 });
 
-/**
- * Generate full response (raw - includes usage)
- * Returns: { text, messages, toolCalls, usage }
- */
 app.post("/api/raw/generate/full", async (req, res) => {
   console.log("[/api/raw/generate/full] Full response data");
   const { text, messages, toolCalls, usage } = await runtime
@@ -135,22 +343,6 @@ app.post("/api/raw/generate/full", async (req, res) => {
   res.json({ text, messages, toolCalls, usage });
 });
 
-/**
- * Generate with metadata
- * Returns: { text, messageCount, toolCallCount }
- */
-app.post("/api/raw/generate/summary", async (req, res) => {
-  console.log("[/api/raw/generate/summary] Summary response");
-  const { text, messages, toolCalls } = await runtime
-    .stream(req.body)
-    .collect();
-  res.json({
-    text,
-    messageCount: messages.length,
-    toolCallCount: toolCalls.length,
-  });
-});
-
 // ============================================
 // HEALTH CHECK
 // ============================================
@@ -158,20 +350,25 @@ app.post("/api/raw/generate/summary", async (req, res) => {
 app.get("/api/health", (_req, res) => {
   res.json({
     status: "ok",
-    copilotEndpoints: [
-      "POST /api/copilot/stream - SSE streaming (CopilotProvider default)",
-      "POST /api/copilot/chat - Non-streaming JSON (streaming={false})",
-      "POST /api/copilot/handler - Express handler one-liner",
-    ],
-    rawStreamEndpoints: [
-      "POST /api/raw/stream/text - Plain text stream",
-      "POST /api/raw/stream/events - Stream with server-side event logging",
-    ],
-    rawGenerateEndpoints: [
-      "POST /api/raw/generate/text - Returns { text }",
-      "POST /api/raw/generate/full - Returns { text, messages, toolCalls, usage }",
-      "POST /api/raw/generate/summary - Returns { text, messageCount, toolCallCount }",
-    ],
+    provider: process.env.ANTHROPIC_API_KEY ? "anthropic" : "openai",
+    model,
+    serverTools: serverTools.map((t) => t.name),
+    endpoints: {
+      copilot: [
+        "POST /api/copilot/stream - SSE streaming",
+        "POST /api/copilot/chat - Non-streaming JSON",
+        "POST /api/copilot/handler - Express handler",
+      ],
+      test: [
+        "POST /api/test/copilot-response - Direct API test (mimics CopilotController)",
+      ],
+      raw: [
+        "POST /api/raw/stream/text - Plain text stream",
+        "POST /api/raw/stream/events - Stream with event logging",
+        "POST /api/raw/generate/text - Returns { text }",
+        "POST /api/raw/generate/full - Returns { text, messages, toolCalls, usage }",
+      ],
+    },
   });
 });
 
@@ -182,37 +379,38 @@ app.get("/api/health", (_req, res) => {
 const port = process.env.PORT || 3001;
 app.listen(port, () => {
   console.log(`
-Express Demo Server running on http://localhost:${port}
+╔══════════════════════════════════════════════════════════════╗
+║         Express Demo - Server-Side Tools                      ║
+╠══════════════════════════════════════════════════════════════╣
+║  Server:   http://localhost:${port}                              ║
+║  Provider: ${(process.env.ANTHROPIC_API_KEY ? "Anthropic" : "OpenAI").padEnd(47)}║
+║  Model:    ${model.padEnd(47)}║
+╚══════════════════════════════════════════════════════════════╝
 
-=== COPILOT SDK ENDPOINTS ===
-  POST /api/copilot/stream   - SSE streaming (default)
-  POST /api/copilot/chat     - Non-streaming JSON
-  POST /api/copilot/handler  - Express handler
-
-=== RAW STREAMING ===
-  POST /api/raw/stream/text   - Plain text stream
-  POST /api/raw/stream/events - Stream with event logging (includes usage)
-
-=== RAW NON-STREAMING ===
-  POST /api/raw/generate/text    - Returns { text }
-  POST /api/raw/generate/full    - Returns { text, messages, toolCalls, usage }
-  POST /api/raw/generate/summary - Returns { text, messageCount, toolCallCount }
+Server-side Tools:
+  - search_knowledge_base: Search dummy KB data
+  - get_current_time: Get server time
 
 === TEST CURLS ===
 
-# Copilot SDK - Streaming
+# Test knowledge base search (server-side tool)
+curl -X POST http://localhost:${port}/api/copilot/chat \\
+  -H "Content-Type: application/json" \\
+  -d '{"messages":[{"role":"user","content":"What is YourGPT SDK?"}]}'
+
+# Test streaming with tools
 curl -X POST http://localhost:${port}/api/copilot/stream \\
   -H "Content-Type: application/json" \\
-  -d '{"messages":[{"role":"user","content":"Say hello"}]}'
+  -d '{"messages":[{"role":"user","content":"Tell me about SDK pricing"}]}'
 
-# Copilot SDK - Non-streaming
-curl -X POST http://localhost:${port}/api/copilot/chat \\
+# Test direct API (mimics CopilotController)
+curl -X POST http://localhost:${port}/api/test/copilot-response \\
   -H "Content-Type: application/json" \\
-  -d '{"messages":[{"role":"user","content":"Say hello"}]}'
+  -d '{"messages":[{"role":"user","content":"How do I install the SDK?"}]}'
 
-# Raw - Full response with usage
-curl -X POST http://localhost:${port}/api/raw/generate/full \\
+# Test time tool
+curl -X POST http://localhost:${port}/api/copilot/chat \\
   -H "Content-Type: application/json" \\
-  -d '{"messages":[{"role":"user","content":"Say hello"}]}'
+  -d '{"messages":[{"role":"user","content":"What time is it?"}]}'
   `);
 });
diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index ace9889..cd0669a 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",
diff --git a/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts b/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
index ef9de10..470cdaf 100644
--- a/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
+++ b/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
@@ -170,6 +170,15 @@ export class AbstractAgentLoop implements AgentLoopActions {
   }
 
   private addToolExecution(execution: ToolExecution): void {
+    // Check for duplicate by ID - skip if already exists
+    const existingIndex = this._toolExecutions.findIndex(
+      (e) => e.id === execution.id,
+    );
+    if (existingIndex !== -1) {
+      // Skip duplicate - don't add or merge
+      return;
+    }
+
     this._toolExecutions = [...this._toolExecutions, execution];
 
     // Prune old executions if over limit (prevents memory leak)
@@ -182,10 +191,10 @@ export class AbstractAgentLoop implements AgentLoopActions {
     this.callbacks.onExecutionsChange?.(this._toolExecutions);
   }
 
-  private updateToolExecution(
-    id: string,
-    update: Partial<ToolExecution>,
-  ): void {
+  /**
+   * Update a tool execution with partial data
+   */
+  updateToolExecution(id: string, update: Partial<ToolExecution>): void {
     this._toolExecutions = this._toolExecutions.map((exec) =>
       exec.id === id ? { ...exec, ...update } : exec,
     );
@@ -307,6 +316,7 @@ export class AbstractAgentLoop implements AgentLoopActions {
       status: "pending",
       approvalStatus: "none",
       startedAt: new Date(),
+      hidden: tool?.hidden,
     };
 
     this.addToolExecution(execution);
@@ -493,6 +503,55 @@ export class AbstractAgentLoop implements AgentLoopActions {
     this._maxIterationsReached = false;
   }
 
+  // ============================================
+  // Server-Side Tool Tracking
+  // ============================================
+
+  /**
+   * Add a server-side tool execution (from streaming action:start event)
+   * Used to track tools executed on the server (not client-side)
+   */
+  addServerToolExecution(info: {
+    id: string;
+    name: string;
+    hidden?: boolean;
+  }): void {
+    const execution: ToolExecution = {
+      id: info.id,
+      toolCallId: info.id,
+      name: info.name,
+      args: {},
+      status: "executing",
+      approvalStatus: "none",
+      startedAt: new Date(),
+      hidden: info.hidden,
+    };
+    this.addToolExecution(execution);
+  }
+
+  /**
+   * Update a server-side tool execution with args (from action:args event)
+   */
+  updateServerToolArgs(id: string, args: Record<string, unknown>): void {
+    this.updateToolExecution(id, { args });
+  }
+
+  /**
+   * Complete a server-side tool execution (from action:end event)
+   */
+  completeServerToolExecution(info: {
+    id: string;
+    result?: unknown;
+    error?: string;
+  }): void {
+    this.updateToolExecution(info.id, {
+      status: info.error ? "failed" : "completed",
+      result: info.result,
+      error: info.error,
+      completedAt: new Date(),
+    });
+  }
+
   /**
    * Cancel all pending and executing tools
    * This will:
diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index 766c107..555f258 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -146,6 +146,66 @@ export class ChatWithTools {
         onMessageFinish: callbacks.onMessageFinish,
         onToolCalls: callbacks.onToolCalls,
         onFinish: callbacks.onFinish,
+        // Server-side tool callbacks - track in agentLoop for UI display
+        // IMPORTANT: Only track tools that are NOT registered client-side
+        // Client-side tools are tracked via executeToolCalls() path
+        onServerToolStart: (info) => {
+          // Check if execution with this ID already exists
+          const existingExecution = this.agentLoop.toolExecutions.find(
+            (e) => e.id === info.id,
+          );
+          if (existingExecution) {
+            // Update hidden flag if this event has it (agent-loop sends hidden, adapter doesn't)
+            if (
+              info.hidden !== undefined &&
+              existingExecution.hidden !== info.hidden
+            ) {
+              this.debug(
+                "Updating hidden flag for existing execution:",
+                info.name,
+                info.hidden,
+              );
+              this.agentLoop.updateToolExecution(info.id, {
+                hidden: info.hidden,
+              });
+            }
+            return;
+          }
+          // Skip if this tool is registered client-side (will be tracked via executeToolCalls)
+          const isClientTool = this.agentLoop.tools.some(
+            (t) => t.name === info.name && t.location === "client",
+          );
+          if (isClientTool) {
+            this.debug("Skipping server tracking for client tool:", info.name);
+            return;
+          }
+          this.debug("Server tool started:", info.name, {
+            hidden: info.hidden,
+            id: info.id,
+          });
+          this.agentLoop.addServerToolExecution(info);
+        },
+        onServerToolArgs: (info) => {
+          // Skip if this tool is registered client-side
+          const isClientTool = this.agentLoop.tools.some(
+            (t) => t.name === info.name && t.location === "client",
+          );
+          if (isClientTool) return;
+          this.debug("Server tool args:", info.name, info.args);
+          this.agentLoop.updateServerToolArgs(info.id, info.args ?? {});
+        },
+        onServerToolEnd: (info) => {
+          // Skip if this tool is registered client-side
+          const isClientTool = this.agentLoop.tools.some(
+            (t) => t.name === info.name && t.location === "client",
+          );
+          if (isClientTool) return;
+          this.debug("Server tool ended:", info.name, {
+            error: info.error,
+            hasResult: !!info.result,
+          });
+          this.agentLoop.completeServerToolExecution(info);
+        },
       },
     });
 
diff --git a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
index 07cb1de..63a500a 100644
--- a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
+++ b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
@@ -72,20 +72,12 @@ export class HttpTransport implements ChatTransport {
       // Resolve dynamic values at request time (not constructor time)
       // This ensures fresh values on every request
       // Optimized: skips async overhead if all values are static
-      console.log(
-        "[HttpTransport] Config headers type:",
-        typeof this.config.headers,
-      );
-      console.log("[HttpTransport] Config headers:", this.config.headers);
-
       const resolved = await resolveValues({
         url: this.config.url,
         headers: this.config.headers ?? {},
         configBody: this.config.body ?? {},
       });
 
-      console.log("[HttpTransport] Resolved headers:", resolved.headers);
-
       const response = await fetch(resolved.url as string, {
         method: "POST",
         headers: {
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index caa4dca..2a47223 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -754,9 +754,94 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         return;
       }
 
+      // Handle message:end mid-stream (server-side agent loop turn completed)
+      // This creates separate messages for each turn instead of combining them
+      if (chunk.type === "message:end" && this.streamState?.content) {
+        this.debug("message:end mid-stream - finalizing current turn");
+
+        // Finalize current message with its content and tool calls
+        const turnMessage = streamStateToMessage(this.streamState) as T;
+
+        // Add toolCallsHidden metadata if applicable
+        const toolCallsHidden: Record<string, boolean> = {};
+        for (const [id, result] of this.streamState.toolResults) {
+          if (result.hidden !== undefined) {
+            toolCallsHidden[id] = result.hidden;
+          }
+        }
+        if (
+          turnMessage.toolCalls?.length &&
+          Object.keys(toolCallsHidden).length > 0
+        ) {
+          (turnMessage as T & { metadata?: Record<string, unknown> }).metadata =
+            {
+              ...(turnMessage as T & { metadata?: Record<string, unknown> })
+                .metadata,
+              toolCallsHidden,
+            };
+        }
+
+        this.state.updateMessageById(
+          this.streamState.messageId,
+          () => turnMessage,
+        );
+        this.callbacks.onMessageFinish?.(turnMessage);
+
+        // Reset stream state for next turn - will be initialized on next message:start
+        this.streamState = null;
+        continue;
+      }
+
+      // Handle message:start after a mid-stream finalization
+      if (chunk.type === "message:start" && this.streamState === null) {
+        this.debug("message:start after mid-stream end - creating new message");
+        const newMessage = createEmptyAssistantMessage() as T;
+        this.state.pushMessage(newMessage);
+        this.streamState = createStreamState(newMessage.id);
+        this.callbacks.onMessageStart?.(newMessage.id);
+        continue;
+      }
+
       // Update stream state (pure function)
+      // Skip if streamState is null (shouldn't happen but be safe)
+      if (!this.streamState) {
+        this.debug("warning", "streamState is null, skipping chunk");
+        continue;
+      }
       this.streamState = processStreamChunk(chunk, this.streamState);
 
+      // Emit server tool callbacks for action events
+      if (chunk.type === "action:start") {
+        this.callbacks.onServerToolStart?.({
+          id: chunk.id,
+          name: chunk.name,
+          hidden: chunk.hidden,
+        });
+      } else if (chunk.type === "action:args") {
+        let args: Record<string, unknown> = {};
+        try {
+          args = JSON.parse(chunk.args);
+        } catch {
+          // Keep empty args
+        }
+        // Get name from toolResults (set by action:start)
+        const existingResult = this.streamState?.toolResults.get(chunk.id);
+        if (existingResult) {
+          this.callbacks.onServerToolArgs?.({
+            id: chunk.id,
+            name: existingResult.name,
+            args,
+          });
+        }
+      } else if (chunk.type === "action:end") {
+        this.callbacks.onServerToolEnd?.({
+          id: chunk.id,
+          name: chunk.name,
+          result: chunk.result,
+          error: chunk.error,
+        });
+      }
+
       // Update message in state BY ID (not last position)
       // This is critical: when tool calls trigger nested streams,
       // updateLastMessage would update the wrong message
@@ -781,28 +866,105 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       // Check for completion
       if (isStreamDone(chunk)) {
         this.debug("streamDone", { chunk });
+
+        // CRITICAL: Process messages from done event (server-side tool results)
+        // Without this, tool_call_id is lost and causes Anthropic API errors
+        if (chunk.type === "done" && chunk.messages?.length) {
+          this.debug("processDoneMessages", {
+            count: chunk.messages.length,
+          });
+
+          // Build hidden map from stream state's toolResults
+          const toolCallsHidden: Record<string, boolean> = {};
+          if (this.streamState?.toolResults) {
+            for (const [id, result] of this.streamState.toolResults) {
+              if (result.hidden !== undefined) {
+                toolCallsHidden[id] = result.hidden;
+              }
+            }
+          }
+
+          for (const msg of chunk.messages) {
+            // Skip ALL assistant messages - they're handled via streaming
+            // (message:end/message:start events create separate messages for each turn)
+            if (msg.role === "assistant") {
+              continue;
+            }
+
+            // For assistant messages with tool_calls, add hidden metadata
+            let metadata: Record<string, unknown> | undefined;
+            if (
+              msg.role === "assistant" &&
+              msg.tool_calls?.length &&
+              Object.keys(toolCallsHidden).length > 0
+            ) {
+              metadata = { toolCallsHidden };
+            }
+
+            const message = {
+              id: generateMessageId(),
+              role: msg.role as T["role"],
+              content: msg.content ?? "",
+              toolCalls: msg.tool_calls as T["toolCalls"],
+              toolCallId: msg.tool_call_id,
+              createdAt: new Date(),
+              metadata,
+            } as T;
+
+            this.state.pushMessage(message);
+          }
+        }
+
         break;
       }
     }
 
     this.debug("handleStreamResponse", `Processed ${chunkCount} chunks`);
 
-    // Finalize - update by ID to ensure we update the correct message
-    const finalMessage = streamStateToMessage(this.streamState) as T;
-    this.state.updateMessageById(
-      this.streamState.messageId,
-      () => finalMessage,
-    );
+    // If streamState was already finalized (via message:end mid-stream), skip finalization
+    if (!this.streamState) {
+      this.debug("streamState already finalized via message:end");
+    } else {
+      // Build hidden map from stream state's toolResults for final message metadata
+      const toolCallsHidden: Record<string, boolean> = {};
+      if (this.streamState.toolResults) {
+        for (const [id, result] of this.streamState.toolResults) {
+          if (result.hidden !== undefined) {
+            toolCallsHidden[id] = result.hidden;
+          }
+        }
+      }
+
+      // Finalize - update by ID to ensure we update the correct message
+      const finalMessage = streamStateToMessage(this.streamState) as T;
+
+      // Add toolCallsHidden metadata if we have tool calls with hidden flags
+      if (
+        finalMessage.toolCalls?.length &&
+        Object.keys(toolCallsHidden).length > 0
+      ) {
+        (finalMessage as T & { metadata?: Record<string, unknown> }).metadata =
+          {
+            ...(finalMessage as T & { metadata?: Record<string, unknown> })
+              .metadata,
+            toolCallsHidden,
+          };
+      }
+
+      this.state.updateMessageById(
+        this.streamState.messageId,
+        () => finalMessage,
+      );
 
-    // Check if we got any content
-    if (
-      !finalMessage.content &&
-      (!finalMessage.toolCalls || finalMessage.toolCalls.length === 0)
-    ) {
-      this.debug("warning", "Empty response - no content and no tool calls");
+      // Check if we got any content
+      if (
+        !finalMessage.content &&
+        (!finalMessage.toolCalls || finalMessage.toolCalls.length === 0)
+      ) {
+        this.debug("warning", "Empty response - no content and no tool calls");
+      }
     }
 
-    this.callbacks.onMessageFinish?.(finalMessage);
     this.callbacks.onMessagesChange?.(this.state.messages);
 
     // Only set status to "ready" if NO tool calls were emitted
@@ -822,14 +984,46 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
    * Handle JSON (non-streaming) response
    */
   protected handleJsonResponse(response: ChatResponse): void {
+    // Build a map of tool call hidden flags from response.toolCalls
+    const toolCallHiddenMap = new Map<string, boolean>();
+    if (response.toolCalls) {
+      for (const tc of response.toolCalls) {
+        if (tc.hidden !== undefined) {
+          toolCallHiddenMap.set(tc.id, tc.hidden);
+        }
+      }
+    }
+
     // Add response messages
     for (const msg of response.messages ?? []) {
+      // For assistant messages with tool_calls, add hidden info to metadata
+      let metadata: Record<string, unknown> | undefined;
+      if (
+        msg.role === "assistant" &&
+        msg.tool_calls &&
+        toolCallHiddenMap.size > 0
+      ) {
+        const toolCallsHidden: Record<string, boolean> = {};
+        for (const tc of msg.tool_calls as Array<{ id: string }>) {
+          const hidden = toolCallHiddenMap.get(tc.id);
+          if (hidden !== undefined) {
+            toolCallsHidden[tc.id] = hidden;
+          }
+        }
+        if (Object.keys(toolCallsHidden).length > 0) {
+          metadata = { toolCallsHidden };
+        }
+      }
+
       const message = {
         id: generateMessageId(),
         role: msg.role as T["role"],
         content: msg.content ?? "",
         toolCalls: msg.tool_calls as T["toolCalls"],
+        // CRITICAL: Preserve toolCallId for tool messages (fixes Anthropic API errors)
+        toolCallId: msg.tool_call_id,
         createdAt: new Date(),
+        metadata,
       } as T;
 
       this.state.pushMessage(message);
diff --git a/packages/copilot-sdk/src/chat/functions/stream/processChunk.ts b/packages/copilot-sdk/src/chat/functions/stream/processChunk.ts
index f2adef1..7daebd7 100644
--- a/packages/copilot-sdk/src/chat/functions/stream/processChunk.ts
+++ b/packages/copilot-sdk/src/chat/functions/stream/processChunk.ts
@@ -78,6 +78,7 @@ export function processStreamChunk(
         id: chunk.id,
         name: chunk.name,
         status: "executing",
+        hidden: chunk.hidden,
       });
       return { ...state, toolResults: newResults };
     }
diff --git a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
index ab7abe5..59e8b31 100644
--- a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
+++ b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
@@ -43,9 +43,18 @@ export interface ChatResponse {
     role: string;
     content: string | null;
     tool_calls?: unknown[];
+    /** Tool call ID for tool result messages */
+    tool_call_id?: string;
   }>;
   /** Whether client needs to execute tools */
   requiresAction?: boolean;
+  /** Tool calls with metadata (includes hidden flag for server-side tools) */
+  toolCalls?: Array<{
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    hidden?: boolean;
+  }>;
 }
 
 /**
@@ -87,9 +96,18 @@ export type StreamChunk =
   | { type: "tool_calls"; toolCalls: unknown[]; assistantMessage: unknown }
   | { type: "source:add"; source: unknown }
   | { type: "error"; message: string }
-  | { type: "done"; messages?: unknown[]; requiresAction?: boolean }
+  | {
+      type: "done";
+      messages?: Array<{
+        role: string;
+        content: string | null;
+        tool_calls?: unknown[];
+        tool_call_id?: string;
+      }>;
+      requiresAction?: boolean;
+    }
   // Tool action events (from llm-sdk agent-loop)
-  | { type: "action:start"; id: string; name: string }
+  | { type: "action:start"; id: string; name: string; hidden?: boolean }
   | { type: "action:args"; id: string; args: string }
   | {
       type: "action:end";
diff --git a/packages/copilot-sdk/src/chat/types/chat.ts b/packages/copilot-sdk/src/chat/types/chat.ts
index f59c1d9..f2f14a4 100644
--- a/packages/copilot-sdk/src/chat/types/chat.ts
+++ b/packages/copilot-sdk/src/chat/types/chat.ts
@@ -66,6 +66,16 @@ export interface ChatRequestOptions {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * Server-side tool execution info (from streaming action events)
+ */
+export interface ServerToolInfo {
+  id: string;
+  name: string;
+  args?: Record<string, unknown>;
+  hidden?: boolean;
+}
+
 /**
  * Chat callbacks for state updates
  */
@@ -86,6 +96,14 @@ export interface ChatCallbacks<T extends UIMessage = UIMessage> {
   onToolCalls?: (toolCalls: T["toolCalls"]) => void;
   /** Called when generation is complete */
   onFinish?: (messages: T[]) => 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) */
+  onServerToolArgs?: (info: ServerToolInfo) => void;
+  /** Called when a server-side tool finishes (action:end event) */
+  onServerToolEnd?: (
+    info: ServerToolInfo & { result?: unknown; error?: string },
+  ) => void;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/chat/types/index.ts b/packages/copilot-sdk/src/chat/types/index.ts
index c5d6e26..2b78396 100644
--- a/packages/copilot-sdk/src/chat/types/index.ts
+++ b/packages/copilot-sdk/src/chat/types/index.ts
@@ -19,6 +19,7 @@ export type {
   ChatCallbacks,
   ChatInit,
   SendMessageOptions,
+  ServerToolInfo,
 } from "./chat";
 
 // Tool types
diff --git a/packages/copilot-sdk/src/chat/types/message.ts b/packages/copilot-sdk/src/chat/types/message.ts
index 47ea564..514b141 100644
--- a/packages/copilot-sdk/src/chat/types/message.ts
+++ b/packages/copilot-sdk/src/chat/types/message.ts
@@ -52,6 +52,8 @@ export interface StreamToolResult {
   args?: Record<string, unknown>;
   result?: unknown;
   error?: string;
+  /** Whether this tool should be hidden from UI */
+  hidden?: boolean;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/chat/types/tool.ts b/packages/copilot-sdk/src/chat/types/tool.ts
index 6b5495a..3f2d142 100644
--- a/packages/copilot-sdk/src/chat/types/tool.ts
+++ b/packages/copilot-sdk/src/chat/types/tool.ts
@@ -65,6 +65,11 @@ export interface ToolExecution {
   approvalMessage?: string;
   /** Data passed from user's approval action (e.g., selected supervisor) */
   approvalData?: Record<string, unknown>;
+  /**
+   * Whether this tool execution should be hidden from the UI.
+   * When true, the tool won't appear in the chat, but still executes normally.
+   */
+  hidden?: boolean;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/core/index.ts b/packages/copilot-sdk/src/core/index.ts
index 3821b05..da66e12 100644
--- a/packages/copilot-sdk/src/core/index.ts
+++ b/packages/copilot-sdk/src/core/index.ts
@@ -168,6 +168,7 @@ export type {
   ToolDefinition,
   ToolConfig,
   ToolSet,
+  ToolSetEntry,
   UnifiedToolCall,
   UnifiedToolResult,
   ToolExecutionStatus,
diff --git a/packages/copilot-sdk/src/core/types/tools.ts b/packages/copilot-sdk/src/core/types/tools.ts
index 776b32d..ae785d4 100644
--- a/packages/copilot-sdk/src/core/types/tools.ts
+++ b/packages/copilot-sdk/src/core/types/tools.ts
@@ -651,6 +651,12 @@ export interface ToolExecution {
   approvalMessage?: string;
   /** Timestamp when user responded to approval request */
   approvalTimestamp?: number;
+
+  /**
+   * Whether this tool execution should be hidden from the UI.
+   * Server-side tools can set this to hide internal operations from users.
+   */
+  hidden?: boolean;
 }
 
 // ============================================
@@ -689,18 +695,36 @@ export interface AgentLoopState {
 // ToolSet Type (Vercel AI SDK pattern)
 // ============================================
 
+/**
+ * A tool definition without the name (name is derived from the key in ToolSet)
+ */
+export type ToolSetEntry<TParams = Record<string, unknown>> = Omit<
+  ToolDefinition<TParams>,
+  "name"
+>;
+
 /**
  * A set of tools, keyed by tool name
  *
+ * The key becomes the tool name, so tool definitions don't need a name property.
+ * Use with the `tool()` helper for clean syntax.
+ *
  * @example
  * ```typescript
  * const myTools: ToolSet = {
- *   capture_screenshot: screenshotTool,
- *   get_weather: weatherTool,
+ *   capture_screenshot: tool({
+ *     description: 'Capture screenshot',
+ *     handler: async () => ({ success: true }),
+ *   }),
+ *   get_weather: tool({
+ *     description: 'Get weather',
+ *     inputSchema: { type: 'object', properties: { city: { type: 'string' } } },
+ *     handler: async ({ city }) => ({ success: true, data: { temp: 72 } }),
+ *   }),
  * };
  * ```
  */
-export type ToolSet = Record<string, ToolDefinition>;
+export type ToolSet = Record<string, ToolSetEntry>;
 
 // ============================================
 // Tool Helper Function (Vercel AI SDK pattern)
diff --git a/packages/copilot-sdk/src/react/hooks/useToolExecutor.ts b/packages/copilot-sdk/src/react/hooks/useToolExecutor.ts
index a009f48..d7bbaa4 100644
--- a/packages/copilot-sdk/src/react/hooks/useToolExecutor.ts
+++ b/packages/copilot-sdk/src/react/hooks/useToolExecutor.ts
@@ -101,6 +101,7 @@ export function useToolExecutor(): UseToolExecutorReturn {
         status: "executing",
         timestamp: Date.now(),
         approvalStatus: "none",
+        hidden: tool.hidden,
       };
 
       // Add to execution list
diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index 16b3344..ed433b4 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -189,9 +189,16 @@ export type {
   ToolExecutionStatus,
   UnifiedToolCall,
   AgentLoopConfig,
+  // ToolSet types (for useTools)
+  ToolSet,
+  ToolSetEntry,
+  ToolConfig,
   // Permission types
   PermissionLevel,
   ToolPermission,
   PermissionStorageConfig,
   PermissionStorageAdapter,
 } from "../core";
+
+// Re-export tool helper function (Vercel AI SDK pattern)
+export { tool } from "../core";
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index 09edafa..e2d31c2 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -275,18 +275,22 @@ export function DefaultMessage({
     );
   }
 
-  // Helper: check if a tool is hidden (shouldn't appear in UI)
-  const isToolHidden = (toolName: string): boolean => {
-    const toolDef = registeredTools?.find((t) => t.name === toolName);
+  // Helper: check if a tool execution is hidden (shouldn't appear in UI)
+  // Checks both: 1) execution's hidden flag (from server), 2) registered tool's hidden flag
+  const isToolHidden = (exec: { name: string; hidden?: boolean }): boolean => {
+    // Check execution's own hidden flag first (from server's action:start event)
+    if (exec.hidden === true) return true;
+    // Then check registered tool definition
+    const toolDef = registeredTools?.find((t) => t.name === exec.name);
     return toolDef?.hidden === true;
   };
 
   // Separate tool executions into categories (excluding hidden tools)
   const pendingApprovalTools = message.toolExecutions?.filter(
-    (exec) => exec.approvalStatus === "required" && !isToolHidden(exec.name),
+    (exec) => exec.approvalStatus === "required" && !isToolHidden(exec),
   );
   const completedTools = message.toolExecutions?.filter(
-    (exec) => exec.approvalStatus !== "required" && !isToolHidden(exec.name),
+    (exec) => exec.approvalStatus !== "required" && !isToolHidden(exec),
   );
 
   // Helper: check if tool has any custom render (toolRenderers, mcpToolRenderer, or tool.render)
@@ -487,7 +491,7 @@ export function DefaultMessage({
 
             {/* MCP-UI Resources - Interactive components from MCP tools (excluding hidden) */}
             {message.toolExecutions
-              ?.filter((exec) => !isToolHidden(exec.name))
+              ?.filter((exec) => !isToolHidden(exec))
               .map((exec) => {
                 const uiResources = exec.result?._uiResources;
                 if (!uiResources || uiResources.length === 0) return null;
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index 68698a7..cb3e0a3 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -337,6 +337,7 @@ function CopilotChatBase(
       error: exec.error,
       timestamp: exec.startedAt ? exec.startedAt.getTime() : Date.now(),
       approvalStatus: exec.approvalStatus,
+      hidden: exec.hidden,
     }),
   );
 
@@ -385,6 +386,11 @@ function CopilotChatBase(
           );
         } else {
           // Build from stored tool_calls + tool messages (historical)
+          // Get hidden info from message metadata (set by handleJsonResponse)
+          const toolCallsHidden = (
+            m.metadata as { toolCallsHidden?: Record<string, boolean> }
+          )?.toolCallsHidden;
+
           messageToolExecutions = m.toolCalls.map(
             (tc: {
               id: string;
@@ -405,6 +411,15 @@ function CopilotChatBase(
               } catch {
                 // Keep empty args
               }
+              // Check hidden from metadata first (from server response),
+              // then fall back to registeredTools
+              let hidden = toolCallsHidden?.[tc.id];
+              if (hidden === undefined) {
+                const toolDef = registeredTools?.find(
+                  (t) => t.name === tc.function.name,
+                );
+                hidden = toolDef?.hidden;
+              }
               return {
                 id: tc.id,
                 name: tc.function.name,
@@ -414,6 +429,7 @@ function CopilotChatBase(
                   : "pending") as ToolExecutionData["status"],
                 result,
                 timestamp: Date.now(), // Historical - use current time
+                hidden,
               };
             },
           );
@@ -432,6 +448,11 @@ function CopilotChatBase(
         messageToolExecutions = savedExecutions;
       }
 
+      // Filter out hidden tool executions for the message
+      const visibleToolExecutions = messageToolExecutions?.filter(
+        (exec) => !exec.hidden,
+      );
+
       return {
         id: m.id,
         role: m.role as "user" | "assistant" | "system",
@@ -441,11 +462,27 @@ function CopilotChatBase(
         attachments: m.attachments,
         // Include tool_calls for assistant messages
         tool_calls: m.toolCalls,
-        // Attach matched tool executions to assistant messages
-        toolExecutions: messageToolExecutions,
+        // Attach matched tool executions to assistant messages (only visible ones)
+        toolExecutions: visibleToolExecutions,
         // Include metadata (citations from native web search, etc.)
         metadata: m.metadata,
+        // Mark if this message had only hidden tools (for filtering empty bubbles)
+        _hasOnlyHiddenTools:
+          messageToolExecutions &&
+          messageToolExecutions.length > 0 &&
+          (!visibleToolExecutions || visibleToolExecutions.length === 0),
       };
+    })
+    // Filter out empty assistant messages that only had hidden tools
+    .filter((m) => {
+      if (
+        m.role === "assistant" &&
+        !m.content &&
+        (m as { _hasOnlyHiddenTools?: boolean })._hasOnlyHiddenTools
+      ) {
+        return false;
+      }
+      return true;
     });
 
   // Show suggestions only when no messages
diff --git a/packages/copilot-sdk/src/ui/components/composed/tools/tool-execution-list.tsx b/packages/copilot-sdk/src/ui/components/composed/tools/tool-execution-list.tsx
index 37ee341..e24f91f 100644
--- a/packages/copilot-sdk/src/ui/components/composed/tools/tool-execution-list.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/tools/tool-execution-list.tsx
@@ -79,6 +79,11 @@ export interface ToolExecutionData {
   approvalMessage?: string;
   /** Data passed from user's approval action (e.g., selected item) */
   approvalData?: Record<string, unknown>;
+  /**
+   * Whether this tool execution should be hidden from the UI.
+   * Server-side tools can set this to hide internal operations from users.
+   */
+  hidden?: boolean;
 }
 
 /**
diff --git a/packages/llm-sdk/package.json b/packages/llm-sdk/package.json
index b8948a9..f9fefa9 100644
--- a/packages/llm-sdk/package.json
+++ b/packages/llm-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/llm-sdk",
-  "version": "2.1.0",
+  "version": "2.1.3",
   "description": "AI SDK for building AI Agents with any LLM",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
diff --git a/packages/llm-sdk/src/adapters/anthropic.ts b/packages/llm-sdk/src/adapters/anthropic.ts
index 14a021e..c646fce 100644
--- a/packages/llm-sdk/src/adapters/anthropic.ts
+++ b/packages/llm-sdk/src/adapters/anthropic.ts
@@ -90,6 +90,10 @@ export class AnthropicAdapter implements LLMAdapter {
     const pendingToolResults: Array<{ tool_use_id: string; content: string }> =
       [];
 
+    // Track tool_use ids from assistant messages for inference
+    let lastToolCallIds: string[] = [];
+    let toolResultIndex = 0;
+
     for (const msg of rawMessages) {
       // Skip system messages (handled separately)
       if (msg.role === "system") continue;
@@ -110,6 +114,10 @@ export class AnthropicAdapter implements LLMAdapter {
             })),
           });
           pendingToolResults.length = 0;
+          // Clear tracking - tool results have been flushed, any subsequent
+          // tool results without a new tool_use are orphaned
+          lastToolCallIds = [];
+          toolResultIndex = 0;
         }
 
         // Convert assistant message with potential tool_calls
@@ -134,6 +142,10 @@ export class AnthropicAdapter implements LLMAdapter {
           | undefined;
 
         if (toolCalls && toolCalls.length > 0) {
+          // Track tool call IDs for inferring missing tool_call_id in tool messages
+          lastToolCallIds = toolCalls.map((tc) => tc.id);
+          toolResultIndex = 0;
+
           for (const tc of toolCalls) {
             let input = {};
             try {
@@ -156,8 +168,44 @@ export class AnthropicAdapter implements LLMAdapter {
         }
       } else if (msg.role === "tool") {
         // Collect tool results to be bundled into a user message
+        let toolCallId = msg.tool_call_id as string | undefined;
+
+        // If tool_call_id is missing, try to infer from preceding assistant's tool_calls
+        if (!toolCallId && lastToolCallIds.length > 0) {
+          toolCallId = lastToolCallIds[toolResultIndex];
+          toolResultIndex++;
+          console.warn(
+            `[llm-sdk] Tool message missing tool_call_id, inferred: ${toolCallId}`,
+          );
+        }
+
+        if (!toolCallId) {
+          console.warn(
+            "[llm-sdk] Skipping tool message with missing tool_call_id (no inference possible):",
+            msg,
+          );
+          continue;
+        }
+
+        // Skip orphaned tool results (no pending tool_use to match)
+        // This happens when there's a duplicate/stale tool result in the conversation
+        if (lastToolCallIds.length === 0) {
+          console.warn(
+            `[llm-sdk] Skipping orphaned tool result (no pending tool_use): ${toolCallId}`,
+          );
+          continue;
+        }
+
+        // Skip if this tool_call_id is not in the expected list
+        if (!lastToolCallIds.includes(toolCallId)) {
+          console.warn(
+            `[llm-sdk] Skipping tool result with unexpected tool_call_id: ${toolCallId}`,
+          );
+          continue;
+        }
+
         pendingToolResults.push({
-          tool_use_id: msg.tool_call_id as string,
+          tool_use_id: toolCallId,
           content:
             typeof msg.content === "string"
               ? msg.content
diff --git a/packages/llm-sdk/src/core/stream-events.ts b/packages/llm-sdk/src/core/stream-events.ts
index 5b61039..259eb94 100644
--- a/packages/llm-sdk/src/core/stream-events.ts
+++ b/packages/llm-sdk/src/core/stream-events.ts
@@ -83,6 +83,8 @@ export interface ActionStartEvent extends BaseEvent {
   type: "action:start";
   id: string;
   name: string;
+  /** Whether this tool should be hidden from UI */
+  hidden?: boolean;
 }
 
 /**
@@ -121,6 +123,8 @@ export interface ToolCallInfo {
   id: string;
   name: string;
   args: Record<string, unknown>;
+  /** Whether this tool should be hidden from UI */
+  hidden?: boolean;
 }
 
 /**
@@ -431,6 +435,13 @@ export interface ToolDefinition<TParams = Record<string, unknown>> {
   ) => unknown | Promise<unknown>;
   render?: (props: unknown) => unknown;
   available?: boolean;
+  /**
+   * Hide this tool's execution from the chat UI.
+   * When true, tool calls and results won't be displayed to the user,
+   * but the tool will still execute normally.
+   * @default false
+   */
+  hidden?: boolean;
   needsApproval?: boolean;
   approvalMessage?: string | ((params: TParams) => string);
   /** AI response mode for this tool (none, brief, full) */
diff --git a/packages/llm-sdk/src/providers/anthropic/provider.ts b/packages/llm-sdk/src/providers/anthropic/provider.ts
index ea65af8..4b48b6e 100644
--- a/packages/llm-sdk/src/providers/anthropic/provider.ts
+++ b/packages/llm-sdk/src/providers/anthropic/provider.ts
@@ -369,38 +369,45 @@ function formatMessagesForAnthropic(messages: CoreMessage[]): {
   const formatted: any[] = [];
   const pendingToolResults: any[] = [];
 
-  for (const msg of messages) {
-    if (msg.role === "system") {
-      system += (system ? "\n" : "") + msg.content;
-      continue;
-    }
+  // Helper to flush pending tool results with validation
+  const flushToolResults = () => {
+    if (pendingToolResults.length === 0) return;
+
+    const validResults = pendingToolResults.filter((tr) => {
+      if (!tr.toolCallId) {
+        console.warn("[llm-sdk] Skipping tool result with missing toolCallId");
+        return false;
+      }
+      return true;
+    });
 
-    // Flush pending tool results before adding assistant messages
-    if (msg.role === "assistant" && pendingToolResults.length > 0) {
+    if (validResults.length > 0) {
       formatted.push({
         role: "user",
-        content: pendingToolResults.map((tr) => ({
+        content: validResults.map((tr) => ({
           type: "tool_result",
           tool_use_id: tr.toolCallId,
           content: tr.content,
         })),
       });
-      pendingToolResults.length = 0;
+    }
+    pendingToolResults.length = 0;
+  };
+
+  for (const msg of messages) {
+    if (msg.role === "system") {
+      system += (system ? "\n" : "") + msg.content;
+      continue;
+    }
+
+    // Flush pending tool results before adding assistant messages
+    if (msg.role === "assistant" && pendingToolResults.length > 0) {
+      flushToolResults();
     }
 
     if (msg.role === "user") {
       // Flush pending tool results first
-      if (pendingToolResults.length > 0) {
-        formatted.push({
-          role: "user",
-          content: pendingToolResults.map((tr) => ({
-            type: "tool_result",
-            tool_use_id: tr.toolCallId,
-            content: tr.content,
-          })),
-        });
-        pendingToolResults.length = 0;
-      }
+      flushToolResults();
 
       if (typeof msg.content === "string") {
         formatted.push({ role: "user", content: msg.content });
@@ -460,24 +467,27 @@ function formatMessagesForAnthropic(messages: CoreMessage[]): {
         formatted.push({ role: "assistant", content });
       }
     } else if (msg.role === "tool") {
+      // Handle both camelCase (SDK format) and snake_case (OpenAI format)
+      const toolCallId =
+        msg.toolCallId ?? (msg as any).tool_call_id ?? (msg as any).toolUseId;
+
+      if (!toolCallId) {
+        console.warn(
+          "[llm-sdk] Tool message missing toolCallId, skipping:",
+          msg,
+        );
+        continue;
+      }
+
       pendingToolResults.push({
-        toolCallId: msg.toolCallId,
+        toolCallId,
         content: msg.content,
       });
     }
   }
 
   // Flush any remaining tool results
-  if (pendingToolResults.length > 0) {
-    formatted.push({
-      role: "user",
-      content: pendingToolResults.map((tr) => ({
-        type: "tool_result",
-        tool_use_id: tr.toolCallId,
-        content: tr.content,
-      })),
-    });
-  }
+  flushToolResults();
 
   return { system, messages: formatted };
 }
diff --git a/packages/llm-sdk/src/server/agent-loop.ts b/packages/llm-sdk/src/server/agent-loop.ts
index 3eaa058..7dbd121 100644
--- a/packages/llm-sdk/src/server/agent-loop.ts
+++ b/packages/llm-sdk/src/server/agent-loop.ts
@@ -345,11 +345,12 @@ async function executeToolCalls(
       continue;
     }
 
-    // Emit action start
+    // Emit action start (include hidden flag for client-side filtering)
     emitEvent?.({
       type: "action:start",
       id: toolCall.id,
       name: toolCall.name,
+      hidden: tool.hidden ?? false,
     });
 
     // Emit arguments
diff --git a/packages/llm-sdk/src/server/runtime.ts b/packages/llm-sdk/src/server/runtime.ts
index 7df99dc..ada24d3 100644
--- a/packages/llm-sdk/src/server/runtime.ts
+++ b/packages/llm-sdk/src/server/runtime.ts
@@ -982,6 +982,11 @@ export class Runtime {
           messages: messagesWithResults as ChatRequest["messages"],
         };
 
+        // Signal end of current message turn before continuing
+        // This tells the client to finalize the current assistant message
+        // The recursive call will emit a new message:start for the next turn
+        yield { type: "message:end" } as StreamEvent;
+
         // Continue the agent loop - pass accumulated messages and HTTP request
         for await (const event of this.processChatWithLoop(
           nextRequest,
@@ -1208,10 +1213,12 @@ export class Runtime {
 
           // Emit tool call events
           for (const tc of result.toolCalls) {
+            const tool = allTools.find((t) => t.name === tc.name);
             yield {
               type: "action:start",
               id: tc.id,
               name: tc.name,
+              hidden: tool?.hidden ?? false,
             } as StreamEvent;
             yield {
               type: "action:args",
diff --git a/packages/llm-sdk/src/server/stream-result.ts b/packages/llm-sdk/src/server/stream-result.ts
index 39c23d2..f02edd2 100644
--- a/packages/llm-sdk/src/server/stream-result.ts
+++ b/packages/llm-sdk/src/server/stream-result.ts
@@ -529,6 +529,29 @@ export class StreamResult {
         collected.toolCalls.push(...event.toolCalls);
         break;
 
+      case "action:start":
+        // Capture tool call with hidden flag (for server-side tools)
+        collected.toolCalls.push({
+          id: event.id,
+          name: event.name,
+          args: {},
+          hidden: event.hidden,
+        });
+        break;
+
+      case "action:args": {
+        // Update args for the tool call
+        const tc = collected.toolCalls.find((t) => t.id === event.id);
+        if (tc) {
+          try {
+            tc.args = JSON.parse(event.args || "{}");
+          } catch {
+            tc.args = {};
+          }
+        }
+        break;
+      }
+
       case "done":
         if (event.messages) {
           collected.messages.push(...event.messages);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3d2793c..9c7152e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -386,6 +386,9 @@ importers:
 
   examples/express-demo:
     dependencies:
+      '@anthropic-ai/sdk':
+        specifier: ^0.39.0
+        version: 0.39.0
       '@yourgpt/llm-sdk':
         specifier: workspace:*
         version: link:../../packages/llm-sdk

From 1054b8ab41b62de62f56ef71c62865ba4436edc2 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 9 Mar 2026 16:07:28 +0530
Subject: [PATCH 03/72] feat: update Copilot SDK version and enhance Zod to
 JSON Schema conversion

- Bump version from 2.1.3 to 2.1.4 in package.json.
- Improve zodToJsonSchema function to support ToolInputSchema compatibility.
- Refactor internal schema conversion logic for better clarity and maintainability.
- Enhance useTool hook to support both Zod schemas and JSON schemas for input parameters.
---
 packages/copilot-sdk/package.json             |  2 +-
 .../src/core/utils/zod-to-json-schema.ts      | 38 +++++++--
 .../copilot-sdk/src/react/hooks/useTool.ts    | 80 +++++++++++++++----
 3 files changed, 94 insertions(+), 26 deletions(-)

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index cd0669a..205fa35 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",
diff --git a/packages/copilot-sdk/src/core/utils/zod-to-json-schema.ts b/packages/copilot-sdk/src/core/utils/zod-to-json-schema.ts
index e3fc8e6..01f9ff3 100644
--- a/packages/copilot-sdk/src/core/utils/zod-to-json-schema.ts
+++ b/packages/copilot-sdk/src/core/utils/zod-to-json-schema.ts
@@ -188,9 +188,29 @@ function getZodEnumValues(
 // ============================================
 
 /**
- * Convert a Zod schema to JSON Schema property (supports Zod 3 and 4)
+ * Convert a Zod schema to JSON Schema property (supports Zod 3 and 4).
+ * When used with z.object(), the result is compatible with ToolInputSchema.
+ *
+ * @example
+ * ```ts
+ * // For tool input schemas
+ * useTool({
+ *   inputSchema: zodToJsonSchema(z.object({
+ *     name: z.string().describe("User name"),
+ *   })),
+ * });
+ * ```
+ */
+export function zodToJsonSchema(schema: unknown): ToolInputSchema {
+  const result = _zodToJsonSchemaInternal(schema);
+  // Cast to ToolInputSchema - callers should only pass z.object() schemas for tool inputs
+  return result as unknown as ToolInputSchema;
+}
+
+/**
+ * Internal implementation for recursive schema conversion
  */
-export function zodToJsonSchema(schema: unknown): JSONSchemaProperty {
+function _zodToJsonSchemaInternal(schema: unknown): JSONSchemaProperty {
   if (!isZodSchema(schema)) {
     return { type: "string" };
   }
@@ -240,7 +260,9 @@ export function zodToJsonSchema(schema: unknown): JSONSchemaProperty {
       const innerType = getZodInnerType(schema);
       const result: JSONSchemaProperty = {
         type: "array",
-        items: innerType ? zodToJsonSchema(innerType) : { type: "string" },
+        items: innerType
+          ? _zodToJsonSchemaInternal(innerType)
+          : { type: "string" },
       };
       if (description) result.description = description;
       return result;
@@ -256,7 +278,7 @@ export function zodToJsonSchema(schema: unknown): JSONSchemaProperty {
       const required: string[] = [];
 
       for (const [key, value] of Object.entries(shapeObj)) {
-        properties[key] = zodToJsonSchema(value);
+        properties[key] = _zodToJsonSchemaInternal(value);
 
         // Check if the field is required (not optional/nullable)
         const fieldTypeName = getZodTypeName(value);
@@ -281,7 +303,7 @@ export function zodToJsonSchema(schema: unknown): JSONSchemaProperty {
     case "ZodNullable": {
       const innerType = getZodInnerType(schema);
       if (innerType) {
-        return zodToJsonSchema(innerType);
+        return _zodToJsonSchemaInternal(innerType);
       }
       return { type: "string", description };
     }
@@ -289,7 +311,7 @@ export function zodToJsonSchema(schema: unknown): JSONSchemaProperty {
     case "ZodDefault": {
       const innerType = getZodInnerType(schema);
       if (innerType) {
-        const result = zodToJsonSchema(innerType);
+        const result = _zodToJsonSchemaInternal(innerType);
         // Note: Default value extraction is complex in Zod 4, skip for now
         return result;
       }
@@ -342,7 +364,7 @@ export function zodToJsonSchema(schema: unknown): JSONSchemaProperty {
       }
 
       if (options && options.length > 0) {
-        return zodToJsonSchema(options[0]);
+        return _zodToJsonSchemaInternal(options[0]);
       }
       return { type: "string", description };
     }
@@ -362,7 +384,7 @@ export function zodToJsonSchema(schema: unknown): JSONSchemaProperty {
  * This fallback implementation is for older Zod versions.
  */
 export function zodObjectToInputSchema(schema: unknown): ToolInputSchema {
-  const jsonSchema = zodToJsonSchema(schema);
+  const jsonSchema = _zodToJsonSchemaInternal(schema);
 
   if (jsonSchema.type !== "object" || !jsonSchema.properties) {
     const typeName = getZodTypeName(schema);
diff --git a/packages/copilot-sdk/src/react/hooks/useTool.ts b/packages/copilot-sdk/src/react/hooks/useTool.ts
index d66081c..028833d 100644
--- a/packages/copilot-sdk/src/react/hooks/useTool.ts
+++ b/packages/copilot-sdk/src/react/hooks/useTool.ts
@@ -1,29 +1,47 @@
 "use client";
 
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useMemo } from "react";
 import type {
   ToolDefinition,
   ToolResponse,
   ToolContext,
   ToolRenderProps,
   ToolSet,
+  ToolInputSchema,
 } from "../../core";
+import { zodToJsonSchema } from "../../core";
 import { useCopilot } from "../provider/CopilotProvider";
 
 /**
- * Configuration for registering a tool (legacy format)
+ * Check if value is a Zod schema
+ */
+function isZodSchema(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    ("_def" in obj && typeof obj._def === "object") ||
+    ("_zod" in obj && typeof obj._zod === "object") ||
+    "~standard" in obj
+  );
+}
+
+/**
+ * Configuration for registering a tool
  */
 export interface UseToolConfig<TParams = Record<string, unknown>> {
   /** Unique tool name */
   name: string;
   /** Tool description for LLM */
   description: string;
-  /** JSON Schema for input parameters */
-  inputSchema: {
-    type: "object";
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
+  /**
+   * Input schema - accepts either:
+   * - Zod schema: z.object({ name: z.string() })
+   * - JSON Schema: { type: "object", properties: { name: { type: "string" } } }
+   *
+   * Zod schemas are automatically converted to JSON Schema at runtime.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputSchema: any;
   /** Handler function */
   handler: (
     params: TParams,
@@ -51,22 +69,37 @@ export interface UseToolConfig<TParams = Record<string, unknown>> {
  * This hook registers a tool that can be called by the AI during a conversation.
  * The tool will execute on the client side.
  *
+ * Supports both Zod schemas and JSON schemas for inputSchema.
+ *
  * @example
  * ```tsx
+ * // Using Zod schema (recommended)
+ * import { z } from "zod";
+ *
  * useTool({
  *   name: "navigate_to_page",
  *   description: "Navigate to a specific page in the app",
+ *   inputSchema: z.object({
+ *     path: z.string().describe("The path to navigate to"),
+ *   }),
+ *   handler: async ({ path }) => {
+ *     router.push(path);
+ *     return { success: true, message: `Navigated to ${path}` };
+ *   },
+ * });
+ *
+ * // Using JSON Schema
+ * useTool({
+ *   name: "open_modal",
+ *   description: "Open a modal dialog",
  *   inputSchema: {
  *     type: "object",
  *     properties: {
- *       path: { type: "string", description: "The path to navigate to" },
+ *       modalId: { type: "string" },
  *     },
- *     required: ["path"],
- *   },
- *   handler: async ({ path }) => {
- *     router.push(path);
- *     return { success: true, message: `Navigated to ${path}` };
+ *     required: ["modalId"],
  *   },
+ *   handler: async ({ modalId }) => { ... },
  * });
  * ```
  */
@@ -80,13 +113,21 @@ export function useTool<TParams = Record<string, unknown>>(
   // Update ref when config changes
   configRef.current = config;
 
+  // Convert Zod schema to JSON Schema if needed (memoized)
+  const inputSchema = useMemo(() => {
+    if (isZodSchema(config.inputSchema)) {
+      return zodToJsonSchema(config.inputSchema);
+    }
+    return config.inputSchema as ToolInputSchema;
+  }, [config.inputSchema]);
+
   useEffect(() => {
     // Create tool definition
     const tool: ToolDefinition = {
       name: config.name,
       description: config.description,
       location: "client",
-      inputSchema: config.inputSchema as ToolDefinition["inputSchema"],
+      inputSchema,
       handler: async (params, context) => {
         return configRef.current.handler(params as TParams, context);
       },
@@ -106,7 +147,7 @@ export function useTool<TParams = Record<string, unknown>>(
       unregisterTool(config.name);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config.name, ...dependencies]);
+  }, [config.name, inputSchema, ...dependencies]);
 }
 
 /**
@@ -219,11 +260,16 @@ export function useToolsArray<TParams = Record<string, unknown>>(
     const toolNames: string[] = [];
 
     for (const config of tools) {
+      // Convert Zod schema if needed
+      const inputSchema = isZodSchema(config.inputSchema)
+        ? zodToJsonSchema(config.inputSchema)
+        : (config.inputSchema as ToolInputSchema);
+
       const tool: ToolDefinition = {
         name: config.name,
         description: config.description,
         location: "client",
-        inputSchema: config.inputSchema as ToolDefinition["inputSchema"],
+        inputSchema,
         handler: async (params, context) => {
           const currentConfig = toolsRef.current.find(
             (t) => t.name === config.name,

From 70041a7c6ea8b0d4a910c64d84b50774c021e1fe Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Wed, 11 Mar 2026 11:20:47 +0530
Subject: [PATCH 04/72] feat: enhance Express demo with minimal runtime and
 response endpoints

- Introduced a BODY_SIZE_LIMIT environment variable for request size management.
- Added minimal runtime for a simple AI assistant prompt.
- Implemented two new endpoints: a streaming endpoint and a non-streaming endpoint for copilot responses.
---
 examples/express-demo/src/index.ts | 34 +++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/examples/express-demo/src/index.ts b/examples/express-demo/src/index.ts
index a289289..165ca0c 100644
--- a/examples/express-demo/src/index.ts
+++ b/examples/express-demo/src/index.ts
@@ -6,8 +6,11 @@ import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
 import { createOpenAI } from "@yourgpt/llm-sdk/openai";
 
 const app = express();
+const BODY_SIZE_LIMIT = process.env.BODY_SIZE_LIMIT || "100mb";
+
 app.use(cors());
-app.use(express.json());
+app.use(express.json({ limit: BODY_SIZE_LIMIT }));
+app.use(express.urlencoded({ extended: true, limit: BODY_SIZE_LIMIT }));
 
 // ============================================
 // DUMMY KNOWLEDGE BASE DATA
@@ -192,6 +195,35 @@ Be helpful, concise, and accurate. If the knowledge base doesn't have the answer
   },
 });
 
+// ============================================
+// MINIMAL RUNTIME (No tools, simple prompt)
+// ============================================
+
+const minimalRuntime = createRuntime({
+  provider,
+  model,
+  systemPrompt: "You are a helpful AI assistant.",
+});
+
+// ============================================
+// MINIMAL COPILOT RESPONSE ENDPOINT
+// ============================================
+
+/**
+ * Minimal streaming endpoint - no tools, simple prompt
+ */
+app.post("/api/copilot-response", async (req, res) => {
+  await minimalRuntime.stream(req.body).pipeToResponse(res);
+});
+
+/**
+ * Minimal non-streaming endpoint - no tools, simple prompt
+ */
+app.post("/api/copilot-response/chat", async (req, res) => {
+  const result = await minimalRuntime.chat(req.body);
+  res.json(result);
+});
+
 // ============================================
 // COPILOT SDK COMPATIBLE ENDPOINTS
 // ============================================

From b26f06e83621907b6490e19fca95c385d6fc8d79 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Wed, 11 Mar 2026 16:54:41 +0530
Subject: [PATCH 05/72] Add tool management, deferred loading, and native
 search support

---
 WEB_SEARCH_IMPLEMENTATION.md                  |  385 -----
 examples/experimental/README.md               |   24 +-
 .../app/api/chat/tool-scale/route.ts          |  141 ++
 examples/experimental/app/page.tsx            |    5 +
 examples/experimental/app/tool-scale/page.tsx |  286 ++++
 .../experimental/lib/tool-scale/catalog.ts    |  827 ++++++++++
 .../lib/tool-scale/client-tools.ts            |   58 +
 .../lib/tool-scale/server-tools.ts            |   51 +
 examples/express-demo/README.md               |   40 +
 examples/express-demo/src/index.ts            |   44 +
 .../copilot-sdk/src/chat/ChatWithTools.ts     |   29 +
 .../src/chat/adapters/HttpTransport.ts        |    1 +
 .../src/chat/classes/AbstractChat.ts          |  217 +--
 packages/copilot-sdk/src/chat/index.ts        |    1 +
 .../src/chat/interfaces/ChatTransport.ts      |    2 +
 .../copilot-sdk/src/chat/optimizations.ts     | 1352 +++++++++++++++++
 packages/copilot-sdk/src/chat/types/chat.ts   |   12 +-
 packages/copilot-sdk/src/core/index.ts        |   13 +
 packages/copilot-sdk/src/core/types/tools.ts  |  179 +++
 packages/llm-sdk/README.md                    |   59 +
 packages/llm-sdk/src/adapters/anthropic.ts    |  135 +-
 packages/llm-sdk/src/adapters/azure.ts        |   20 +-
 packages/llm-sdk/src/adapters/base.ts         |  113 ++
 packages/llm-sdk/src/adapters/google.ts       |   42 +-
 packages/llm-sdk/src/adapters/ollama.ts       |   19 +-
 packages/llm-sdk/src/adapters/openai.ts       |  343 ++++-
 packages/llm-sdk/src/adapters/xai.ts          |   20 +-
 packages/llm-sdk/src/core/stream-events.ts    |  116 ++
 packages/llm-sdk/src/index.ts                 |   15 +
 packages/llm-sdk/src/providers/anthropic.ts   |    8 +-
 packages/llm-sdk/src/providers/gemini.ts      |    8 +-
 packages/llm-sdk/src/providers/openai.ts      |    8 +-
 packages/llm-sdk/src/server/agent-loop.ts     |  122 +-
 packages/llm-sdk/src/server/index.ts          |    9 +
 packages/llm-sdk/src/server/runtime.ts        |  362 ++++-
 packages/llm-sdk/src/server/tool-selection.ts |  587 +++++++
 packages/llm-sdk/src/server/types.ts          |   22 +
 tool-search-implementation.md                 |  253 +++
 38 files changed, 5332 insertions(+), 596 deletions(-)
 delete mode 100644 WEB_SEARCH_IMPLEMENTATION.md
 create mode 100644 examples/experimental/app/api/chat/tool-scale/route.ts
 create mode 100644 examples/experimental/app/tool-scale/page.tsx
 create mode 100644 examples/experimental/lib/tool-scale/catalog.ts
 create mode 100644 examples/experimental/lib/tool-scale/client-tools.ts
 create mode 100644 examples/experimental/lib/tool-scale/server-tools.ts
 create mode 100644 packages/copilot-sdk/src/chat/optimizations.ts
 create mode 100644 packages/llm-sdk/src/server/tool-selection.ts
 create mode 100644 tool-search-implementation.md

diff --git a/WEB_SEARCH_IMPLEMENTATION.md b/WEB_SEARCH_IMPLEMENTATION.md
deleted file mode 100644
index eb27ae8..0000000
--- a/WEB_SEARCH_IMPLEMENTATION.md
+++ /dev/null
@@ -1,385 +0,0 @@
-# Web Search Implementation - Technical Documentation
-
-> Temporary documentation for the native web search feature implementation.
-
----
-
-## Current Implementation Status
-
-### Completed
-
-- [x] Native web search for all 3 LLM providers (OpenAI, Google, Anthropic)
-- [x] Single API call (was 2 calls before - LLM + search provider)
-- [x] Citations displayed as chips below messages (like Perplexity/ChatGPT)
-- [x] Tree-shakeable subpath exports (~3KB per provider vs ~50KB for all)
-- [x] Unified Citation format across all providers
-- [x] HoverCard preview for citations with favicon and domain
-- [x] Hidden "Web search" tool step when native citations exist
-- [x] Debug logs cleaned up
-- [x] Simplified naming (removed "-native" suffix)
-
----
-
-## Architecture
-
-### Package Structure
-
-```
-@yourgpt/copilot-sdk
-├── /core                         # Main exports
-├── /react                        # React hooks
-├── /ui                           # UI components
-└── /tools                        # Tree-shakeable tool exports
-    ├── /web-search               # Shared types + utilities
-    ├── /openai                   # openaiSearch()
-    ├── /google                   # googleSearch()
-    ├── /anthropic                # anthropicSearch()
-    ├── /tavily                   # tavilySearch()
-    ├── /serper                   # serperSearch()
-    ├── /brave                    # braveSearch()
-    ├── /exa                      # exaSearch()
-    └── /searxng                  # searxngSearch()
-```
-
-### Provider Implementation Files
-
-```
-packages/copilot-sdk/src/core/tools/webSearch/providers/
-├── openai.ts      # OpenAI Responses API with web_search tool
-├── google.ts      # Gemini API with google_search grounding
-├── anthropic.ts   # Anthropic Messages API with web_search_20250305
-├── tavily.ts      # Tavily API
-├── serper.ts      # Serper (Google) API
-├── brave.ts       # Brave Search API
-├── exa.ts         # Exa (semantic) API
-└── searxng.ts     # Self-hosted SearXNG
-```
-
-### LLM Adapters with Native Web Search
-
-```
-packages/llm-sdk/src/adapters/
-├── openai.ts      # webSearch config → web_search_preview tool
-├── google.ts      # webSearch config → google_search grounding
-└── anthropic.ts   # webSearch config → web_search_20260209 tool
-```
-
----
-
-## Unified Citation Format
-
-All providers normalize to this format:
-
-```typescript
-interface Citation {
-  index: number; // 1-based index
-  url: string; // Source URL
-  title: string; // Page title or domain
-  domain?: string; // Extracted domain (e.g., "example.com")
-  favicon?: string; // Google favicon URL
-  citedText?: string; // Relevant excerpt (Anthropic only)
-}
-```
-
-### Stream Event
-
-```typescript
-yield { type: "citation", citations: Citation[] };
-```
-
-### Message Metadata
-
-Citations are stored in message metadata:
-
-```typescript
-message.metadata.citations: Citation[]
-```
-
----
-
-## Provider-Specific Details
-
-### OpenAI
-
-**Tool Type:** `web_search_preview`
-**API:** Chat Completions (streaming)
-**Citations:** `delta.annotations[]` with `type: "url_citation"`
-
-```typescript
-// Adapter config
-webSearch: true | WebSearchConfig;
-
-// Emits during stream
-if (annotation.type === "url_citation") {
-  collectedCitations.push({
-    url: annotation.url_citation.url,
-    title: annotation.url_citation.title,
-  });
-}
-```
-
-### Google (Gemini)
-
-**Tool Type:** `{ google_search: {} }`
-**API:** generateContent (streaming)
-**Citations:** `candidate.groundingMetadata.groundingChunks[]`
-
-```typescript
-// Grounding metadata
-groundingMetadata: {
-  groundingChunks: [
-    { web: { uri: string, title?: string } }
-  ]
-}
-```
-
-### Anthropic
-
-**Tool Type:** `web_search_20260209` (streaming adapter) / `web_search_20250305` (standalone)
-**API:** Messages (streaming)
-**Citations:** `content[].citations[]` with `type: "web_search_result_location"`
-
-```typescript
-// Citation format
-{
-  type: "web_search_result_location",
-  url: string,
-  title: string,
-  cited_text?: string,  // Unique to Anthropic
-}
-```
-
-**Note:** Anthropic provides `cited_text` - the actual text from the page that was cited.
-
----
-
-## UI Components
-
-### SourceGroup (`source.tsx`)
-
-Displays citations as chips with hover preview.
-
-```tsx
-<SourceGroup
-  sources={sources}
-  showFavicon={true}
-  numbered={false}
-  maxVisible={6}
-/>
-```
-
-### Source (individual chip)
-
-```tsx
-<Source
-  href="https://example.com/article"
-  title="Article Title"
-  description="Optional description"
-  showFavicon={true}
-/>
-```
-
-### HoverCard
-
-Uses `@radix-ui/react-hover-card` for preview on hover.
-Animation requires `tw-animate-css` (Tailwind v4) in user's project.
-
----
-
-## Known Issues & Fixes Applied
-
-### 1. Citations Lost After Stream Ends
-
-**Problem:** `useInternalThreadManager` was calling `setMessages()` even without persistence adapter, overwriting metadata.
-
-**Fix:** Added `!adapter` check:
-
-```typescript
-useEffect(() => {
-  if (!adapter) return; // Skip sync when no persistence
-  // ...
-}, [adapter, messages]);
-```
-
-**File:** `packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts`
-
-### 2. Tool Step Showing During Native Search
-
-**Problem:** "Web search" tool step was showing during streaming for native web search.
-
-**Fix:** Don't emit `action:start`/`action:end` for `web_search` tool:
-
-```typescript
-if (currentToolUse.name !== "web_search") {
-  yield { type: "action:start", ... };
-}
-```
-
-**File:** `packages/llm-sdk/src/adapters/anthropic.ts`
-
-### 3. Citations Layout
-
-**Problem:** SourceGroup was rendering to the right of message content.
-
-**Fix:** Moved SourceGroup inside the content div in `default-message.tsx`.
-
-### 4. HoverCard Animations
-
-**Problem:** No transition on hover card.
-
-**Solution:** Users need to add `tw-animate-css` package (Tailwind v4):
-
-```bash
-pnpm add tw-animate-css
-```
-
-```css
-@import "tailwindcss";
-@import "tw-animate-css";
-```
-
----
-
-## Suggestions for Future Improvements
-
-### 1. Extract Duplicate Utilities
-
-The `extractDomain` function is duplicated in:
-
-- `adapters/openai.ts`
-- `adapters/google.ts`
-- `adapters/anthropic.ts`
-- `ui/components/ui/source.tsx`
-
-**Suggestion:** Create shared `packages/llm-sdk/src/utils/url.ts`
-
-### 2. Add Anthropic to Documentation Tabs
-
-The `web-search.mdx` docs are missing Anthropic tab in provider examples.
-
-### 3. Citation Loading State
-
-Currently citations appear after stream ends. Consider showing a subtle "Searching..." indicator during streaming.
-
-### 4. Consolidate Citation Components
-
-Both `citations.tsx` and `source.tsx` exist. Consider:
-
-- Deprecating one, or
-- Clearly documenting when to use each
-
-### 5. Error Boundary for Citations
-
-Add graceful fallback if favicon fails to load (currently just hides).
-
-### 6. Version Consistency
-
-Ensure Anthropic web search version is consistent:
-
-- Adapter: `web_search_20260209`
-- Standalone: `web_search_20250305`
-
-Pick one version and use consistently.
-
----
-
-## Usage Examples
-
-### Native Web Search (Recommended)
-
-```typescript
-// In adapter config - single API call
-const adapter = createAnthropicAdapter({
-  apiKey: process.env.ANTHROPIC_API_KEY,
-  model: "claude-sonnet-4-20250514",
-  webSearch: true, // Enable native web search
-});
-```
-
-### Tree-Shakeable Tool Import
-
-```typescript
-import { openaiSearch } from "@yourgpt/copilot-sdk/tools/openai";
-
-const webSearch = openaiSearch({
-  apiKey: process.env.OPENAI_API_KEY,
-  maxResults: 5,
-});
-
-const runtime = createRuntime({
-  provider: openai,
-  model: "gpt-4o",
-  tools: [webSearch],
-});
-```
-
-### Legacy Import (All Providers)
-
-```typescript
-import { createWebSearchTool } from "@yourgpt/copilot-sdk/core";
-
-const webSearch = createWebSearchTool({
-  provider: "anthropic",
-  apiKey: process.env.ANTHROPIC_API_KEY,
-});
-```
-
----
-
-## Bundle Size
-
-| Import Pattern                         | Size   |
-| -------------------------------------- | ------ |
-| `@yourgpt/copilot-sdk/tools/openai`    | ~2.5KB |
-| `@yourgpt/copilot-sdk/tools/google`    | ~2.5KB |
-| `@yourgpt/copilot-sdk/tools/anthropic` | ~3KB   |
-| `@yourgpt/copilot-sdk/tools/tavily`    | ~3KB   |
-| `@yourgpt/copilot-sdk/core` (all)      | ~50KB  |
-
-**~85% reduction** when using single provider import.
-
----
-
-## Testing
-
-### Demo App
-
-```bash
-cd examples/web-search-demo
-pnpm dev
-# Open http://localhost:3009
-```
-
-### Test Queries
-
-- "What are the latest AI news?"
-- "What's the weather in New York?"
-- "Who won the most recent Super Bowl?"
-- "What's the current price of Bitcoin?"
-
----
-
-## Files Modified in This Feature
-
-### New Files
-
-- `packages/copilot-sdk/src/tools/*/index.ts` (8 tool exports)
-- `packages/copilot-sdk/src/core/tools/webSearch/providers/*.ts` (8 providers)
-- `packages/copilot-sdk/src/ui/components/ui/source.tsx`
-- `packages/copilot-sdk/src/ui/components/ui/citations.tsx`
-- `examples/web-search-demo/` (entire demo app)
-- `apps/docs/content/docs/tools/built-in/web-search.mdx`
-
-### Modified Files
-
-- `packages/llm-sdk/src/adapters/openai.ts` (webSearch support)
-- `packages/llm-sdk/src/adapters/google.ts` (webSearch support)
-- `packages/llm-sdk/src/adapters/anthropic.ts` (webSearch support)
-- `packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx`
-- `packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts`
-- `packages/copilot-sdk/package.json` (subpath exports)
-- `packages/copilot-sdk/tsup.config.ts` (entry points)
-
----
-
-_Last updated: 2026-02-23_
diff --git a/examples/experimental/README.md b/examples/experimental/README.md
index 999af41..7f7ff49 100644
--- a/examples/experimental/README.md
+++ b/examples/experimental/README.md
@@ -8,14 +8,15 @@ This directory contains experimental and raw examples for testing various SDK fe
 
 ## Available Demos
 
-| Demo                    | Path               | Description                                       |
-| ----------------------- | ------------------ | ------------------------------------------------- |
-| **Non-Streaming**       | `/non-streaming`   | `runtime.generate()` with CopilotChat             |
-| **Theme Demo**          | `/theme-demo`      | 9 theme presets with live preview                 |
-| **Multi-Provider**      | `/providers`       | OpenAI, Anthropic, Google side-by-side            |
-| **Compound Components** | `/compound-test`   | Custom home screen with `Chat.Home`, `Chat.Input` |
-| **Tool Types**          | `/tool-types-demo` | Different tool rendering patterns                 |
-| **Widgets**             | `/widgets`         | Standalone UI components                          |
+| Demo                    | Path               | Description                                           |
+| ----------------------- | ------------------ | ----------------------------------------------------- |
+| **Non-Streaming**       | `/non-streaming`   | `runtime.generate()` with CopilotChat                 |
+| **Theme Demo**          | `/theme-demo`      | 9 theme presets with live preview                     |
+| **Multi-Provider**      | `/providers`       | OpenAI, Anthropic, Google side-by-side                |
+| **Compound Components** | `/compound-test`   | Custom home screen with `Chat.Home`, `Chat.Input`     |
+| **Tool Types**          | `/tool-types-demo` | Different tool rendering patterns                     |
+| **Tool Scale Lab**      | `/tool-scale`      | 100 tools with profiles, search, and deferred loading |
+| **Widgets**             | `/widgets`         | Standalone UI components                              |
 
 ## Quick Start
 
@@ -79,19 +80,22 @@ experimental/
 │   ├── providers/                  # Multi-provider test
 │   ├── compound-test/              # Compound components
 │   ├── tool-types-demo/            # Tool rendering patterns
+│   ├── tool-scale/                 # 100-tool selection/profile lab
 │   ├── widgets/                    # Standalone widgets
 │   └── api/
 │       └── chat/
 │           ├── openai/route.ts
 │           ├── anthropic/route.ts
-│           └── google/route.ts
+│           ├── google/route.ts
+│           └── tool-scale/route.ts
 ├── components/
 │   ├── theme-provider.tsx
 │   ├── provider-card.tsx
 │   └── tools/
 ├── lib/
 │   ├── utils.ts
-│   └── tools/
+│   ├── tools/
+│   └── tool-scale/
 └── README.md
 ```
 
diff --git a/examples/experimental/app/api/chat/tool-scale/route.ts b/examples/experimental/app/api/chat/tool-scale/route.ts
new file mode 100644
index 0000000..12d9cc6
--- /dev/null
+++ b/examples/experimental/app/api/chat/tool-scale/route.ts
@@ -0,0 +1,141 @@
+import { createRuntime } from "@yourgpt/llm-sdk";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
+import { createOpenAI } from "@yourgpt/llm-sdk/openai";
+
+import { toolScaleServerTools } from "@/lib/tool-scale/server-tools";
+
+function resolveProvider() {
+  if (process.env.ANTHROPIC_API_KEY) {
+    return {
+      providerName: "Anthropic",
+      provider: createAnthropic({
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      }),
+      model: "claude-haiku-4-5",
+    };
+  }
+
+  // if (process.env.OPENAI_API_KEY) {
+  //   return {
+  //     providerName: "OpenAI",
+  //     provider: createOpenAI({
+  //       apiKey: process.env.OPENAI_API_KEY,
+  //     }),
+  //     model: "gpt-5-mini-2025-08-07",
+  //     // model: "gpt-5.4",
+  //   };
+  // }
+
+  throw new Error(
+    "Set ANTHROPIC_API_KEY or OPENAI_API_KEY to run the tool scale lab example.",
+  );
+}
+
+const { providerName, provider, model } = resolveProvider();
+
+const runtime = createRuntime({
+  provider,
+  model,
+  debug: process.env.NODE_ENV === "development",
+  systemPrompt: `You are the Tool Scale Lab assistant.
+
+You are testing a project with 100 tools: 30 server-side and 70 client-side.
+Use tools sparingly and intentionally.
+
+When tools are missing, rely on the search_tools meta-tool to discover deferred tools rather than guessing.
+Keep answers short and explain which class of tools you used when it helps the user understand tool selection behavior.`,
+  tools: toolScaleServerTools,
+  agentLoop: {
+    enabled: true,
+    maxIterations: 6,
+    debug: process.env.NODE_ENV === "development",
+    toolSelection: {
+      enabled: true,
+      defaultProfile: "support",
+      includeUnprofiled: false,
+      search: {
+        enabled: true,
+        maxResults: 6,
+        minScore: 0.15,
+        exposeWhenToolCountExceeds: 12,
+        metaToolName: "search_tools",
+        strictDeferredLoading: true,
+      },
+      dynamicSelection: {
+        enabled: true,
+        maxTools: 6,
+      },
+      profiles: {
+        support: {
+          include: [
+            "profile:support",
+            "category:knowledge",
+            "category:billing",
+            "category:browser",
+            "category:utility",
+          ],
+          exclude: ["group:admin"],
+        },
+        workspace: {
+          include: [
+            "profile:workspace",
+            "category:workspace",
+            "category:browser",
+            "category:analytics",
+            "category:utility",
+          ],
+        },
+        commerce: {
+          include: [
+            "profile:commerce",
+            "category:commerce",
+            "category:billing",
+            "group:actions",
+          ],
+        },
+        admin: {
+          include: [
+            "profile:admin",
+            "category:operations",
+            "category:analytics",
+            "category:utility",
+          ],
+        },
+      },
+      nativeProviderHints: {
+        anthropic: {
+          toolChoice: "auto",
+          disableParallelToolUse: true,
+        },
+        openai: {
+          toolChoice: "auto",
+          parallelToolCalls: false,
+        },
+      },
+    },
+  },
+});
+
+export async function POST(request: Request) {
+  try {
+    return await runtime.handleRequest(request);
+  } catch (error) {
+    return Response.json(
+      {
+        error: error instanceof Error ? error.message : "Unknown error",
+      },
+      { status: 500 },
+    );
+  }
+}
+
+export async function GET() {
+  return Response.json({
+    status: "ok",
+    provider: providerName,
+    model,
+    toolCount: {
+      server: toolScaleServerTools.length,
+    },
+  });
+}
diff --git a/examples/experimental/app/page.tsx b/examples/experimental/app/page.tsx
index a87f4b1..fa3a9a7 100644
--- a/examples/experimental/app/page.tsx
+++ b/examples/experimental/app/page.tsx
@@ -26,6 +26,11 @@ const demos = [
     href: "/tool-types-demo",
     description: "Different tool rendering patterns",
   },
+  {
+    name: "Tool Scale Lab",
+    href: "/tool-scale",
+    description: "100-tool profile, search, and deferred-loading demo",
+  },
   {
     name: "Widgets",
     href: "/widgets",
diff --git a/examples/experimental/app/tool-scale/page.tsx b/examples/experimental/app/tool-scale/page.tsx
new file mode 100644
index 0000000..4178a3f
--- /dev/null
+++ b/examples/experimental/app/tool-scale/page.tsx
@@ -0,0 +1,286 @@
+"use client";
+
+import { useState } from "react";
+import { CopilotProvider, useTools } from "@yourgpt/copilot-sdk/react";
+import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
+import "@yourgpt/copilot-sdk/ui/styles.css";
+import "@yourgpt/copilot-sdk/ui/themes/claude.css";
+
+import { toolScaleClientTools } from "@/lib/tool-scale/client-tools";
+import {
+  getProfileToolStats,
+  toolScaleCounts,
+  toolScaleProfiles,
+} from "@/lib/tool-scale/catalog";
+
+function ToolScaleClientRegistration() {
+  useTools(toolScaleClientTools);
+  return null;
+}
+
+const profilePrompts: Record<string, string[]> = {
+  support: [
+    "What refund policy and SLA guidance should I give a customer asking about delayed support?",
+    "Search the right docs and pricing tools for an enterprise plan migration question.",
+  ],
+  workspace: [
+    "Help me summarize the current workspace layout and find blocked tasks for tomorrow.",
+    "What document and scheduling tools should you use to inspect upcoming deadlines?",
+  ],
+  commerce: [
+    "Check checkout issues, promo codes, and shipping details for an abandoned cart flow.",
+    "Which billing and commerce tools would you use for a failed payment complaint?",
+  ],
+  admin: [
+    "Inspect incident status, audit signals, and dashboard metrics for an operations review.",
+    "What tools are relevant for a compliance and analytics triage session?",
+  ],
+};
+
+const requestSnippet = `{
+  "toolProfile": "support",
+  "messages": [
+    {
+      "role": "user",
+      "content": "Help me answer a pricing and SLA question"
+    }
+  ]
+}`;
+
+const selectionSnippet = `toolSelection: {
+  enabled: true,
+  defaultProfile: "support",
+  includeUnprofiled: false,
+  search: {
+    enabled: true,
+    maxResults: 6,
+    exposeWhenToolCountExceeds: 12,
+    metaToolName: "search_tools",
+    strictDeferredLoading: true,
+  },
+  dynamicSelection: {
+    enabled: true,
+    maxTools: 6,
+  },
+}`;
+
+export default function ToolScalePage() {
+  const [activeProfile, setActiveProfile] = useState("support");
+  const stats = getProfileToolStats(activeProfile);
+
+  return (
+    <div className="min-h-screen bg-background">
+      <div className="mx-auto flex min-h-screen max-w-7xl flex-col gap-6 p-4 md:p-6">
+        <header className="rounded-3xl border bg-card p-6 shadow-sm">
+          <div className="flex flex-col gap-4 lg:flex-row lg:items-end lg:justify-between">
+            <div className="max-w-3xl space-y-3">
+              <p className="text-xs font-semibold uppercase tracking-[0.22em] text-muted-foreground">
+                Experimental Tool Scale Lab
+              </p>
+              <h1 className="text-3xl font-semibold tracking-tight">
+                100-tool mixed runtime test
+              </h1>
+              <p className="text-sm leading-6 text-muted-foreground">
+                This example simulates a project with {toolScaleCounts.total}{" "}
+                tools: {toolScaleCounts.server} server-side and{" "}
+                {toolScaleCounts.client} client-side. Most tools are deferred,
+                so the model sees a small profile-specific slice up front and
+                discovers the rest through `search_tools`.
+              </p>
+            </div>
+
+            <div className="grid grid-cols-2 gap-3 text-sm sm:grid-cols-4">
+              <div className="rounded-2xl border bg-background p-3">
+                <div className="text-muted-foreground">Total</div>
+                <div className="text-2xl font-semibold">
+                  {toolScaleCounts.total}
+                </div>
+              </div>
+              <div className="rounded-2xl border bg-background p-3">
+                <div className="text-muted-foreground">Server</div>
+                <div className="text-2xl font-semibold">
+                  {toolScaleCounts.server}
+                </div>
+              </div>
+              <div className="rounded-2xl border bg-background p-3">
+                <div className="text-muted-foreground">Client</div>
+                <div className="text-2xl font-semibold">
+                  {toolScaleCounts.client}
+                </div>
+              </div>
+              <div className="rounded-2xl border bg-background p-3">
+                <div className="text-muted-foreground">Deferred</div>
+                <div className="text-2xl font-semibold">
+                  {toolScaleCounts.deferred}
+                </div>
+              </div>
+            </div>
+          </div>
+        </header>
+
+        <div className="grid gap-6 lg:grid-cols-[360px_minmax(0,1fr)]">
+          <aside className="space-y-6">
+            <section className="rounded-3xl border bg-card p-5">
+              <h2 className="text-lg font-semibold">Active profile</h2>
+              <p className="mt-1 text-sm text-muted-foreground">
+                `toolProfile` is sent in the request body. The runtime applies
+                the matching profile first, then dynamic selection, then
+                deferred search.
+              </p>
+
+              <div className="mt-4 grid gap-2">
+                {toolScaleProfiles.map((profile) => (
+                  <button
+                    key={profile.id}
+                    type="button"
+                    onClick={() => setActiveProfile(profile.id)}
+                    className={`rounded-2xl border px-4 py-3 text-left transition-colors ${
+                      activeProfile === profile.id
+                        ? "border-foreground bg-foreground text-background"
+                        : "bg-background hover:bg-accent"
+                    }`}
+                  >
+                    <div className="font-medium">{profile.label}</div>
+                    <div
+                      className={`mt-1 text-xs ${
+                        activeProfile === profile.id
+                          ? "text-background/80"
+                          : "text-muted-foreground"
+                      }`}
+                    >
+                      {profile.description}
+                    </div>
+                  </button>
+                ))}
+              </div>
+            </section>
+
+            <section className="rounded-3xl border bg-card p-5">
+              <h2 className="text-lg font-semibold">Profile effect</h2>
+              <div className="mt-4 grid grid-cols-2 gap-3 text-sm">
+                <div className="rounded-2xl border bg-background p-3">
+                  <div className="text-muted-foreground">Eligible tools</div>
+                  <div className="text-2xl font-semibold">{stats.total}</div>
+                </div>
+                <div className="rounded-2xl border bg-background p-3">
+                  <div className="text-muted-foreground">Immediate</div>
+                  <div className="text-2xl font-semibold">
+                    {stats.immediate}
+                  </div>
+                </div>
+                <div className="rounded-2xl border bg-background p-3">
+                  <div className="text-muted-foreground">Deferred</div>
+                  <div className="text-2xl font-semibold">{stats.deferred}</div>
+                </div>
+                <div className="rounded-2xl border bg-background p-3">
+                  <div className="text-muted-foreground">Dynamic cap</div>
+                  <div className="text-2xl font-semibold">6</div>
+                </div>
+              </div>
+
+              <div className="mt-4 rounded-2xl border bg-background p-4 text-sm text-muted-foreground">
+                <p>
+                  For{" "}
+                  <span className="font-medium text-foreground">
+                    {activeProfile}
+                  </span>
+                  , the model starts from {stats.total} eligible tools, but only
+                  a few immediate tools are available up front. Query-aware
+                  ranking narrows that to at most 6 tools for the current turn.
+                  The remaining deferred matches stay behind `search_tools`.
+                </p>
+              </div>
+
+              <div className="mt-4 space-y-3 text-sm">
+                <div>
+                  <div className="font-medium">Categories</div>
+                  <div className="mt-1 text-muted-foreground">
+                    {stats.categories.join(", ")}
+                  </div>
+                </div>
+                <div>
+                  <div className="font-medium">Groups</div>
+                  <div className="mt-1 text-muted-foreground">
+                    {stats.groups.join(", ")}
+                  </div>
+                </div>
+              </div>
+            </section>
+
+            <section className="rounded-3xl border bg-card p-5">
+              <h2 className="text-lg font-semibold">How profiling works</h2>
+              <ol className="mt-4 space-y-3 text-sm text-muted-foreground">
+                <li>
+                  1. The client sends `toolProfile` with the chat request.
+                </li>
+                <li>
+                  2. The runtime keeps only tools tagged for that profile or
+                  matched by configured selectors.
+                </li>
+                <li>
+                  3. Dynamic selection ranks the remaining tools against the
+                  last user context and caps the upfront list.
+                </li>
+                <li>
+                  4. Deferred tools are hidden until the model calls
+                  `search_tools`, which loads the matched tools on the next loop
+                  iteration.
+                </li>
+              </ol>
+            </section>
+
+            <section className="rounded-3xl border bg-card p-5">
+              <h2 className="text-lg font-semibold">Request body</h2>
+              <pre className="mt-3 overflow-x-auto rounded-2xl bg-muted p-4 text-xs leading-5">
+                {requestSnippet.replace("support", activeProfile)}
+              </pre>
+            </section>
+
+            <section className="rounded-3xl border bg-card p-5">
+              <h2 className="text-lg font-semibold">Selection config</h2>
+              <pre className="mt-3 overflow-x-auto rounded-2xl bg-muted p-4 text-xs leading-5">
+                {selectionSnippet}
+              </pre>
+            </section>
+          </aside>
+
+          <section className="overflow-hidden rounded-3xl border bg-card">
+            <div className="border-b px-5 py-4">
+              <h2 className="text-lg font-semibold">Run the scenario</h2>
+              <p className="mt-1 text-sm text-muted-foreground">
+                Switch profiles, then ask for something that should require
+                docs, billing, workspace, checkout, or operations tools. The
+                runtime will receive `toolProfile: "{activeProfile}"`.
+              </p>
+              <div className="mt-3 flex flex-wrap gap-2">
+                {profilePrompts[activeProfile].map((prompt) => (
+                  <span
+                    key={prompt}
+                    className="rounded-full border bg-background px-3 py-1 text-xs text-muted-foreground"
+                  >
+                    {prompt}
+                  </span>
+                ))}
+              </div>
+            </div>
+
+            <div className="h-[calc(100vh-220px)] min-h-[640px]">
+              <CopilotProvider
+                runtimeUrl="/api/chat/tool-scale"
+                body={{ toolProfile: activeProfile }}
+                debug
+              >
+                <ToolScaleClientRegistration />
+                <CopilotChat
+                  className="h-full csdk-theme-claude"
+                  placeholder={`Ask with the ${activeProfile} profile...`}
+                  suggestions={profilePrompts[activeProfile]}
+                />
+              </CopilotProvider>
+            </div>
+          </section>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/examples/experimental/lib/tool-scale/catalog.ts b/examples/experimental/lib/tool-scale/catalog.ts
new file mode 100644
index 0000000..1e25207
--- /dev/null
+++ b/examples/experimental/lib/tool-scale/catalog.ts
@@ -0,0 +1,827 @@
+export type ToolLocation = "server" | "client";
+
+export interface ToolSeed {
+  name: string;
+  title: string;
+  description: string;
+  location: ToolLocation;
+  category: string;
+  group: string;
+  profiles: string[];
+  deferLoading: boolean;
+  searchKeywords: string[];
+}
+
+interface ClusterDefinition {
+  prefix: string;
+  location: ToolLocation;
+  category: string;
+  group: string;
+  profiles: string[];
+  immediateCount: number;
+  items: Array<{
+    slug: string;
+    title: string;
+    description: string;
+    keywords: string[];
+  }>;
+}
+
+function createClusterTools(cluster: ClusterDefinition): ToolSeed[] {
+  return cluster.items.map((item, index) => ({
+    name: `${cluster.prefix}_${item.slug}`,
+    title: item.title,
+    description: item.description,
+    location: cluster.location,
+    category: cluster.category,
+    group: cluster.group,
+    profiles: cluster.profiles,
+    deferLoading: true,
+    // deferLoading: index >= cluster.immediateCount,
+    searchKeywords: [
+      cluster.category,
+      cluster.group,
+      ...cluster.profiles,
+      ...item.keywords,
+    ],
+  }));
+}
+
+const SERVER_CLUSTERS: ClusterDefinition[] = [
+  {
+    prefix: "support",
+    location: "server",
+    category: "knowledge",
+    group: "support",
+    profiles: ["support", "research"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "search_product_docs",
+        title: "Search product docs",
+        description: "Find official product documentation for support answers.",
+        keywords: ["docs", "product", "guide"],
+      },
+      {
+        slug: "search_api_reference",
+        title: "Search API reference",
+        description:
+          "Find API contracts, request formats, and SDK reference material.",
+        keywords: ["api", "sdk", "reference"],
+      },
+      {
+        slug: "find_setup_guides",
+        title: "Find setup guides",
+        description:
+          "Locate setup and onboarding walkthroughs for new integrations.",
+        keywords: ["setup", "onboarding", "installation"],
+      },
+      {
+        slug: "find_migration_notes",
+        title: "Find migration notes",
+        description: "Locate migration checklists and breaking-change notes.",
+        keywords: ["migration", "upgrade", "release"],
+      },
+      {
+        slug: "lookup_security_faq",
+        title: "Lookup security FAQ",
+        description:
+          "Retrieve security, privacy, and compliance answers for customers.",
+        keywords: ["security", "privacy", "compliance"],
+      },
+      {
+        slug: "lookup_pricing_matrix",
+        title: "Lookup pricing matrix",
+        description: "Find plan tiers, usage caps, and pricing notes.",
+        keywords: ["pricing", "plans", "limits"],
+      },
+      {
+        slug: "search_release_notes",
+        title: "Search release notes",
+        description: "Find release highlights, feature launches, and fixes.",
+        keywords: ["release", "changelog", "feature"],
+      },
+      {
+        slug: "find_troubleshooting_playbooks",
+        title: "Find troubleshooting playbooks",
+        description:
+          "Retrieve support playbooks for common incidents and errors.",
+        keywords: ["troubleshooting", "incident", "errors"],
+      },
+      {
+        slug: "search_integration_cookbook",
+        title: "Search integration cookbook",
+        description: "Find integration recipes for common product setups.",
+        keywords: ["integration", "cookbook", "recipes"],
+      },
+      {
+        slug: "lookup_sla_policies",
+        title: "Lookup SLA policies",
+        description: "Find SLA, uptime, and support response policy details.",
+        keywords: ["sla", "uptime", "policy"],
+      },
+    ],
+  },
+  {
+    prefix: "finance",
+    location: "server",
+    category: "billing",
+    group: "finance",
+    profiles: ["support", "sales", "finance"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "get_invoice_status",
+        title: "Get invoice status",
+        description: "Check invoice status, payment attempts, and due dates.",
+        keywords: ["invoice", "payment", "status"],
+      },
+      {
+        slug: "get_plan_entitlements",
+        title: "Get plan entitlements",
+        description: "Inspect plan entitlements, seats, and included limits.",
+        keywords: ["plan", "entitlements", "seats"],
+      },
+      {
+        slug: "lookup_credit_balance",
+        title: "Lookup credit balance",
+        description:
+          "Find remaining credits and rollover details for an account.",
+        keywords: ["credits", "balance", "usage"],
+      },
+      {
+        slug: "find_refund_policy",
+        title: "Find refund policy",
+        description:
+          "Retrieve refund rules, eligibility criteria, and time windows.",
+        keywords: ["refund", "policy", "eligibility"],
+      },
+      {
+        slug: "get_contract_terms",
+        title: "Get contract terms",
+        description: "Inspect contract renewal dates and commercial terms.",
+        keywords: ["contract", "renewal", "terms"],
+      },
+      {
+        slug: "lookup_discount_rules",
+        title: "Lookup discount rules",
+        description:
+          "Find discounting rules and approved commercial exceptions.",
+        keywords: ["discount", "commercial", "pricing"],
+      },
+      {
+        slug: "find_tax_guidance",
+        title: "Find tax guidance",
+        description:
+          "Retrieve region-specific tax handling and invoicing notes.",
+        keywords: ["tax", "region", "invoice"],
+      },
+      {
+        slug: "get_overage_breakdown",
+        title: "Get overage breakdown",
+        description: "Inspect overage drivers and top consumption buckets.",
+        keywords: ["overage", "consumption", "usage"],
+      },
+      {
+        slug: "lookup_checkout_rules",
+        title: "Lookup checkout rules",
+        description: "Find checkout, trial, and subscription conversion rules.",
+        keywords: ["checkout", "trial", "subscription"],
+      },
+      {
+        slug: "find_procurement_packet",
+        title: "Find procurement packet",
+        description:
+          "Locate procurement, vendor, and approval packet material.",
+        keywords: ["procurement", "vendor", "security"],
+      },
+    ],
+  },
+  {
+    prefix: "ops",
+    location: "server",
+    category: "operations",
+    group: "admin",
+    profiles: ["ops", "admin"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "check_incident_status",
+        title: "Check incident status",
+        description: "Review current incident state and impacted systems.",
+        keywords: ["incident", "status", "systems"],
+      },
+      {
+        slug: "get_usage_snapshot",
+        title: "Get usage snapshot",
+        description: "Inspect current usage and system-level traffic shape.",
+        keywords: ["usage", "traffic", "snapshot"],
+      },
+      {
+        slug: "lookup_rate_limit_state",
+        title: "Lookup rate limit state",
+        description: "Check rate-limit windows and throttling activity.",
+        keywords: ["rate", "limit", "throttle"],
+      },
+      {
+        slug: "find_feature_flags",
+        title: "Find feature flags",
+        description: "Inspect active feature flags for an environment.",
+        keywords: ["feature", "flags", "environment"],
+      },
+      {
+        slug: "resolve_workspace_owner",
+        title: "Resolve workspace owner",
+        description: "Find workspace ownership and escalation contacts.",
+        keywords: ["workspace", "owner", "escalation"],
+      },
+      {
+        slug: "inspect_team_roles",
+        title: "Inspect team roles",
+        description: "List team roles, permissions, and admin assignments.",
+        keywords: ["team", "roles", "permissions"],
+      },
+      {
+        slug: "review_audit_events",
+        title: "Review audit events",
+        description: "Search recent audit events and security changes.",
+        keywords: ["audit", "security", "events"],
+      },
+      {
+        slug: "lookup_region_status",
+        title: "Lookup region status",
+        description: "Check service health and capacity by region.",
+        keywords: ["region", "health", "capacity"],
+      },
+      {
+        slug: "find_data_retention_rules",
+        title: "Find data retention rules",
+        description: "Inspect retention windows and deletion policies.",
+        keywords: ["retention", "deletion", "policy"],
+      },
+      {
+        slug: "get_compliance_controls",
+        title: "Get compliance controls",
+        description: "Retrieve compliance control mappings and attestations.",
+        keywords: ["compliance", "controls", "attestation"],
+      },
+    ],
+  },
+];
+
+const CLIENT_CLUSTERS: ClusterDefinition[] = [
+  {
+    prefix: "browser",
+    location: "client",
+    category: "browser",
+    group: "inspection",
+    profiles: ["support", "workspace"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "inspect_dom_outline",
+        title: "Inspect DOM outline",
+        description: "Inspect the current page structure and headings.",
+        keywords: ["dom", "html", "headings"],
+      },
+      {
+        slug: "capture_visible_text",
+        title: "Capture visible text",
+        description: "Capture visible text content from the active page.",
+        keywords: ["text", "content", "page"],
+      },
+      {
+        slug: "find_primary_actions",
+        title: "Find primary actions",
+        description: "Locate the main buttons and calls to action on the page.",
+        keywords: ["buttons", "cta", "actions"],
+      },
+      {
+        slug: "find_form_fields",
+        title: "Find form fields",
+        description: "List form fields and labels available on the page.",
+        keywords: ["form", "fields", "labels"],
+      },
+      {
+        slug: "inspect_error_banner",
+        title: "Inspect error banner",
+        description: "Check for visible alert, toast, or error banners.",
+        keywords: ["error", "alert", "toast"],
+      },
+      {
+        slug: "extract_help_links",
+        title: "Extract help links",
+        description: "Collect help center and support links from the UI.",
+        keywords: ["help", "support", "links"],
+      },
+      {
+        slug: "scan_table_headers",
+        title: "Scan table headers",
+        description: "Inspect visible table headers and summary labels.",
+        keywords: ["table", "headers", "data"],
+      },
+      {
+        slug: "read_navigation_labels",
+        title: "Read navigation labels",
+        description: "List current navigation items and sidebar labels.",
+        keywords: ["navigation", "sidebar", "menu"],
+      },
+      {
+        slug: "detect_modal_state",
+        title: "Detect modal state",
+        description: "Check whether a modal or drawer is currently open.",
+        keywords: ["modal", "drawer", "dialog"],
+      },
+      {
+        slug: "inspect_page_metadata",
+        title: "Inspect page metadata",
+        description: "Read page title, URL path, and language metadata.",
+        keywords: ["metadata", "url", "language"],
+      },
+    ],
+  },
+  {
+    prefix: "browser",
+    location: "client",
+    category: "browser",
+    group: "actions",
+    profiles: ["support", "commerce"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "focus_search_box",
+        title: "Focus search box",
+        description: "Find and focus the main search input in the UI.",
+        keywords: ["search", "input", "focus"],
+      },
+      {
+        slug: "scroll_to_section",
+        title: "Scroll to section",
+        description: "Scroll the current page to a matching section.",
+        keywords: ["scroll", "section", "page"],
+      },
+      {
+        slug: "expand_accordion",
+        title: "Expand accordion",
+        description: "Expand a collapsed accordion or disclosure element.",
+        keywords: ["accordion", "expand", "collapse"],
+      },
+      {
+        slug: "copy_selected_text",
+        title: "Copy selected text",
+        description: "Copy highlighted or matched text from the page.",
+        keywords: ["copy", "text", "selection"],
+      },
+      {
+        slug: "highlight_form_errors",
+        title: "Highlight form errors",
+        description:
+          "Identify invalid form fields and focus them for the user.",
+        keywords: ["form", "errors", "validation"],
+      },
+      {
+        slug: "open_help_center",
+        title: "Open help center",
+        description: "Open the help center from the current experience.",
+        keywords: ["help", "center", "support"],
+      },
+      {
+        slug: "dismiss_banner",
+        title: "Dismiss banner",
+        description: "Dismiss the active banner, toast, or notice if present.",
+        keywords: ["dismiss", "toast", "banner"],
+      },
+      {
+        slug: "toggle_preview_panel",
+        title: "Toggle preview panel",
+        description: "Toggle a preview or detail side panel in the interface.",
+        keywords: ["preview", "panel", "toggle"],
+      },
+      {
+        slug: "jump_to_checkout_step",
+        title: "Jump to checkout step",
+        description: "Move to a matching step in a checkout or wizard flow.",
+        keywords: ["checkout", "wizard", "step"],
+      },
+      {
+        slug: "activate_primary_tab",
+        title: "Activate primary tab",
+        description: "Switch to the primary or requested tab in a tab set.",
+        keywords: ["tab", "switch", "navigation"],
+      },
+    ],
+  },
+  {
+    prefix: "workspace",
+    location: "client",
+    category: "workspace",
+    group: "documents",
+    profiles: ["workspace", "support"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "open_doc_outline",
+        title: "Open doc outline",
+        description: "Open or summarize the current document outline.",
+        keywords: ["document", "outline", "doc"],
+      },
+      {
+        slug: "list_recent_files",
+        title: "List recent files",
+        description: "List the most recent files visible in the workspace.",
+        keywords: ["recent", "files", "workspace"],
+      },
+      {
+        slug: "find_comment_threads",
+        title: "Find comment threads",
+        description: "Inspect recent comment threads and unresolved notes.",
+        keywords: ["comments", "threads", "notes"],
+      },
+      {
+        slug: "detect_unpublished_changes",
+        title: "Detect unpublished changes",
+        description: "Check whether there are unpublished or unsaved edits.",
+        keywords: ["publish", "draft", "changes"],
+      },
+      {
+        slug: "read_doc_permissions",
+        title: "Read doc permissions",
+        description:
+          "Inspect sharing and permission hints for the current doc.",
+        keywords: ["sharing", "permissions", "access"],
+      },
+      {
+        slug: "open_command_palette",
+        title: "Open command palette",
+        description: "Open the command palette for quick workspace actions.",
+        keywords: ["command", "palette", "shortcut"],
+      },
+      {
+        slug: "search_workspace_mentions",
+        title: "Search workspace mentions",
+        description: "Find mentions, assignments, and @references in the UI.",
+        keywords: ["mentions", "assignments", "workspace"],
+      },
+      {
+        slug: "inspect_publish_checks",
+        title: "Inspect publish checks",
+        description: "Inspect publishing checks, blockers, and warnings.",
+        keywords: ["publish", "checks", "warnings"],
+      },
+      {
+        slug: "find_content_templates",
+        title: "Find content templates",
+        description: "Find reusable templates and starter documents.",
+        keywords: ["templates", "content", "starter"],
+      },
+      {
+        slug: "review_editor_panels",
+        title: "Review editor panels",
+        description:
+          "List editor panels, drawers, and sidebars currently visible.",
+        keywords: ["editor", "panels", "sidebar"],
+      },
+    ],
+  },
+  {
+    prefix: "workspace",
+    location: "client",
+    category: "workspace",
+    group: "scheduling",
+    profiles: ["workspace"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "list_calendar_slots",
+        title: "List calendar slots",
+        description:
+          "Read available meeting slots in the current scheduling view.",
+        keywords: ["calendar", "slots", "schedule"],
+      },
+      {
+        slug: "find_upcoming_deadlines",
+        title: "Find upcoming deadlines",
+        description: "Find upcoming deadlines and due dates in the UI.",
+        keywords: ["deadlines", "due", "dates"],
+      },
+      {
+        slug: "inspect_task_board_columns",
+        title: "Inspect task board columns",
+        description: "Inspect the current task board lanes and counts.",
+        keywords: ["task", "board", "kanban"],
+      },
+      {
+        slug: "read_assignee_filters",
+        title: "Read assignee filters",
+        description: "Inspect active assignee and owner filters.",
+        keywords: ["assignee", "owner", "filters"],
+      },
+      {
+        slug: "find_blocked_tasks",
+        title: "Find blocked tasks",
+        description: "Locate blocked tasks or status badges in the board.",
+        keywords: ["blocked", "tasks", "status"],
+      },
+      {
+        slug: "open_meeting_notes",
+        title: "Open meeting notes",
+        description: "Open or summarize linked meeting notes.",
+        keywords: ["meeting", "notes", "agenda"],
+      },
+      {
+        slug: "read_project_milestones",
+        title: "Read project milestones",
+        description: "Inspect milestone labels and delivery checkpoints.",
+        keywords: ["milestones", "delivery", "project"],
+      },
+      {
+        slug: "find_status_updates",
+        title: "Find status updates",
+        description: "Collect recent project status updates from the UI.",
+        keywords: ["status", "updates", "project"],
+      },
+      {
+        slug: "inspect_backlog_filters",
+        title: "Inspect backlog filters",
+        description: "Review active backlog filters and search chips.",
+        keywords: ["backlog", "filters", "search"],
+      },
+      {
+        slug: "read_capacity_view",
+        title: "Read capacity view",
+        description: "Inspect team capacity and planned workload signals.",
+        keywords: ["capacity", "planning", "workload"],
+      },
+    ],
+  },
+  {
+    prefix: "commerce",
+    location: "client",
+    category: "commerce",
+    group: "checkout",
+    profiles: ["commerce", "support"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "read_cart_summary",
+        title: "Read cart summary",
+        description: "Read cart totals, quantities, and current items.",
+        keywords: ["cart", "summary", "totals"],
+      },
+      {
+        slug: "read_shipping_options",
+        title: "Read shipping options",
+        description: "Read current shipping methods and estimates.",
+        keywords: ["shipping", "delivery", "estimates"],
+      },
+      {
+        slug: "inspect_promo_field",
+        title: "Inspect promo field",
+        description: "Inspect the coupon or promotional code field state.",
+        keywords: ["promo", "coupon", "discount"],
+      },
+      {
+        slug: "find_payment_errors",
+        title: "Find payment errors",
+        description:
+          "Check for visible payment failures or validation messages.",
+        keywords: ["payment", "errors", "checkout"],
+      },
+      {
+        slug: "read_subscription_selector",
+        title: "Read subscription selector",
+        description: "Inspect subscription plans visible in the purchase flow.",
+        keywords: ["subscription", "plans", "purchase"],
+      },
+      {
+        slug: "locate_tax_breakdown",
+        title: "Locate tax breakdown",
+        description: "Locate tax lines and fee breakdown in checkout.",
+        keywords: ["tax", "fees", "breakdown"],
+      },
+      {
+        slug: "capture_return_policy_banner",
+        title: "Capture return policy banner",
+        description:
+          "Capture return or cancellation policy text from the page.",
+        keywords: ["return", "cancellation", "policy"],
+      },
+      {
+        slug: "find_saved_cards",
+        title: "Find saved cards",
+        description: "Inspect the saved payment methods shown in the UI.",
+        keywords: ["cards", "payment", "saved"],
+      },
+      {
+        slug: "read_checkout_steps",
+        title: "Read checkout steps",
+        description: "List the current steps in the checkout wizard.",
+        keywords: ["checkout", "steps", "wizard"],
+      },
+      {
+        slug: "inspect_order_notes",
+        title: "Inspect order notes",
+        description: "Inspect order notes and delivery instructions fields.",
+        keywords: ["order", "notes", "delivery"],
+      },
+    ],
+  },
+  {
+    prefix: "analytics",
+    location: "client",
+    category: "analytics",
+    group: "dashboard",
+    profiles: ["admin", "workspace"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "read_kpi_strip",
+        title: "Read KPI strip",
+        description: "Read the top KPI numbers visible in the dashboard.",
+        keywords: ["kpi", "dashboard", "metrics"],
+      },
+      {
+        slug: "inspect_chart_legend",
+        title: "Inspect chart legend",
+        description: "Inspect chart legends and visible series labels.",
+        keywords: ["chart", "legend", "series"],
+      },
+      {
+        slug: "find_date_filters",
+        title: "Find date filters",
+        description: "Inspect date-range filters applied in analytics views.",
+        keywords: ["date", "filters", "analytics"],
+      },
+      {
+        slug: "read_growth_badges",
+        title: "Read growth badges",
+        description:
+          "Read trend indicators and growth badges in analytics cards.",
+        keywords: ["growth", "trends", "badges"],
+      },
+      {
+        slug: "inspect_funnel_steps",
+        title: "Inspect funnel steps",
+        description: "Inspect funnel stages and conversion labels.",
+        keywords: ["funnel", "conversion", "stages"],
+      },
+      {
+        slug: "capture_table_rows",
+        title: "Capture table rows",
+        description: "Capture the visible analytics table rows for analysis.",
+        keywords: ["table", "rows", "analytics"],
+      },
+      {
+        slug: "read_segment_chips",
+        title: "Read segment chips",
+        description: "Inspect active segments and cohort chips.",
+        keywords: ["segments", "cohorts", "chips"],
+      },
+      {
+        slug: "inspect_alert_thresholds",
+        title: "Inspect alert thresholds",
+        description:
+          "Inspect threshold or anomaly settings in analytics widgets.",
+        keywords: ["alerts", "thresholds", "anomaly"],
+      },
+      {
+        slug: "find_export_actions",
+        title: "Find export actions",
+        description: "Locate CSV, export, or share actions for dashboards.",
+        keywords: ["export", "csv", "share"],
+      },
+      {
+        slug: "inspect_dashboard_tabs",
+        title: "Inspect dashboard tabs",
+        description: "Inspect top-level tabs and grouped analytics views.",
+        keywords: ["tabs", "dashboard", "views"],
+      },
+    ],
+  },
+  {
+    prefix: "utility",
+    location: "client",
+    category: "utility",
+    group: "capture",
+    profiles: ["support", "workspace", "admin"],
+    immediateCount: 2,
+    items: [
+      {
+        slug: "get_browser_locale",
+        title: "Get browser locale",
+        description:
+          "Read the current browser locale and timezone information.",
+        keywords: ["locale", "timezone", "browser"],
+      },
+      {
+        slug: "get_window_dimensions",
+        title: "Get window dimensions",
+        description: "Read the current viewport and window size.",
+        keywords: ["viewport", "window", "screen"],
+      },
+      {
+        slug: "capture_selection_context",
+        title: "Capture selection context",
+        description:
+          "Capture the current text selection and surrounding context.",
+        keywords: ["selection", "context", "highlight"],
+      },
+      {
+        slug: "read_clipboard_preview",
+        title: "Read clipboard preview",
+        description: "Read clipboard text preview when available.",
+        keywords: ["clipboard", "copy", "paste"],
+      },
+      {
+        slug: "capture_console_summary",
+        title: "Capture console summary",
+        description: "Capture a lightweight console message summary.",
+        keywords: ["console", "logs", "errors"],
+      },
+      {
+        slug: "inspect_network_summary",
+        title: "Inspect network summary",
+        description:
+          "Inspect a lightweight summary of captured network requests.",
+        keywords: ["network", "requests", "summary"],
+      },
+      {
+        slug: "read_session_flags",
+        title: "Read session flags",
+        description:
+          "Read temporary session flags relevant to the current page.",
+        keywords: ["session", "flags", "state"],
+      },
+      {
+        slug: "capture_page_snapshot",
+        title: "Capture page snapshot",
+        description: "Capture a lightweight page snapshot for later reasoning.",
+        keywords: ["snapshot", "page", "capture"],
+      },
+      {
+        slug: "inspect_focus_state",
+        title: "Inspect focus state",
+        description: "Inspect the currently focused element and nearby labels.",
+        keywords: ["focus", "element", "labels"],
+      },
+      {
+        slug: "read_keyboard_shortcuts",
+        title: "Read keyboard shortcuts",
+        description: "Read visible keyboard shortcuts or hotkey hints.",
+        keywords: ["keyboard", "shortcuts", "hotkeys"],
+      },
+    ],
+  },
+];
+
+export const serverToolSeeds = SERVER_CLUSTERS.flatMap(createClusterTools);
+export const clientToolSeeds = CLIENT_CLUSTERS.flatMap(createClusterTools);
+export const toolScaleSeeds = [...serverToolSeeds, ...clientToolSeeds];
+
+export const toolScaleCounts = {
+  total: toolScaleSeeds.length,
+  server: serverToolSeeds.length,
+  client: clientToolSeeds.length,
+  deferred: toolScaleSeeds.filter((tool) => tool.deferLoading).length,
+  immediate: toolScaleSeeds.filter((tool) => !tool.deferLoading).length,
+};
+
+export const toolScaleProfiles = [
+  {
+    id: "support",
+    label: "Support",
+    description:
+      "Customer support, docs, billing, browser inspection, utility capture.",
+  },
+  {
+    id: "workspace",
+    label: "Workspace",
+    description:
+      "Project, document, scheduling, browser, and analytics collaboration tools.",
+  },
+  {
+    id: "commerce",
+    label: "Commerce",
+    description: "Checkout, pricing, purchase, and customer-flow tools.",
+  },
+  {
+    id: "admin",
+    label: "Admin",
+    description: "Operations, compliance, analytics, and governance tools.",
+  },
+];
+
+export function getProfileToolStats(profile: string) {
+  const tools = toolScaleSeeds.filter((tool) =>
+    tool.profiles.includes(profile),
+  );
+  return {
+    total: tools.length,
+    immediate: tools.filter((tool) => !tool.deferLoading).length,
+    deferred: tools.filter((tool) => tool.deferLoading).length,
+    server: tools.filter((tool) => tool.location === "server").length,
+    client: tools.filter((tool) => tool.location === "client").length,
+    categories: Array.from(new Set(tools.map((tool) => tool.category))).sort(),
+    groups: Array.from(new Set(tools.map((tool) => tool.group))).sort(),
+  };
+}
diff --git a/examples/experimental/lib/tool-scale/client-tools.ts b/examples/experimental/lib/tool-scale/client-tools.ts
new file mode 100644
index 0000000..9d41a00
--- /dev/null
+++ b/examples/experimental/lib/tool-scale/client-tools.ts
@@ -0,0 +1,58 @@
+"use client";
+
+import type { ToolSet } from "@yourgpt/copilot-sdk/react";
+
+import { clientToolSeeds } from "@/lib/tool-scale/catalog";
+
+const sharedInputSchema = {
+  type: "object" as const,
+  properties: {
+    task: {
+      type: "string" as const,
+      description: "What the tool should help with in this simulation.",
+    },
+    target: {
+      type: "string" as const,
+      description: "Optional page element, record, or area of interest.",
+    },
+  },
+};
+
+export const toolScaleClientTools: ToolSet = Object.fromEntries(
+  clientToolSeeds.map((seed) => [
+    seed.name,
+    {
+      description: seed.description,
+      location: "client",
+      category: seed.category,
+      group: seed.group,
+      profiles: seed.profiles,
+      deferLoading: seed.deferLoading,
+      searchKeywords: seed.searchKeywords,
+      inputSchema: sharedInputSchema,
+      handler: async (params) => {
+        const args = (params ?? {}) as { task?: string; target?: string };
+
+        return {
+          success: true,
+          tool: seed.name,
+          title: seed.title,
+          location: seed.location,
+          category: seed.category,
+          group: seed.group,
+          matchedProfiles: seed.profiles,
+          deferred: seed.deferLoading,
+          requestedTask: args.task ?? "general assistance",
+          target: args.target ?? "active page",
+          browserContext: {
+            path:
+              typeof window === "undefined" ? "/" : window.location.pathname,
+            locale:
+              typeof navigator === "undefined" ? "unknown" : navigator.language,
+          },
+          summary: `${seed.title} returned a simulated browser-side result for the scale-test example.`,
+        };
+      },
+    },
+  ]),
+) as ToolSet;
diff --git a/examples/experimental/lib/tool-scale/server-tools.ts b/examples/experimental/lib/tool-scale/server-tools.ts
new file mode 100644
index 0000000..ffc6f06
--- /dev/null
+++ b/examples/experimental/lib/tool-scale/server-tools.ts
@@ -0,0 +1,51 @@
+import type { ToolDefinition } from "@yourgpt/llm-sdk";
+
+import { serverToolSeeds } from "@/lib/tool-scale/catalog";
+
+const sharedInputSchema = {
+  type: "object" as const,
+  properties: {
+    task: {
+      type: "string",
+      description: "What the tool should help with in this simulation.",
+    },
+    target: {
+      type: "string",
+      description: "Optional object, account, page, or entity to inspect.",
+    },
+  },
+};
+
+export const toolScaleServerTools: ToolDefinition[] = serverToolSeeds.map(
+  (seed) => ({
+    name: seed.name,
+    description: seed.description,
+    location: "server",
+    category: seed.category,
+    group: seed.group,
+    profiles: seed.profiles,
+    deferLoading: seed.deferLoading,
+    searchKeywords: seed.searchKeywords,
+    inputSchema: sharedInputSchema,
+    handler: async (params) => {
+      const args = (params ?? {}) as { task?: string; target?: string };
+
+      return {
+        tool: seed.name,
+        title: seed.title,
+        location: seed.location,
+        category: seed.category,
+        group: seed.group,
+        matchedProfiles: seed.profiles,
+        deferred: seed.deferLoading,
+        requestedTask: args.task ?? "general assistance",
+        target: args.target ?? "current context",
+        summary: `${seed.title} returned a simulated ${seed.category} response for the scale-test example.`,
+        guidance: [
+          `Use ${seed.title.toLowerCase()} when the user needs ${seed.group} help.`,
+          `This tool belongs to the ${seed.category} category and is tagged for ${seed.profiles.join(", ")} profiles.`,
+        ],
+      };
+    },
+  }),
+);
diff --git a/examples/express-demo/README.md b/examples/express-demo/README.md
index b60ee63..e4fc352 100644
--- a/examples/express-demo/README.md
+++ b/examples/express-demo/README.md
@@ -19,6 +19,8 @@
 - Error handling
 - CORS configuration
 - Request/response streaming
+- Tool profiles and selective loading
+- Provider-aware tool hints for Anthropic/OpenAI
 
 ## Quick Start
 
@@ -75,6 +77,44 @@ export OPENAI_API_KEY=your-api-key-here
 | `/api/chat/events`  | Event handlers         | With `on('text', ...)`      |
 | `/api/chat/web`     | `toResponse()`         | Web Response conversion     |
 
+## Tool Selection Demo
+
+The demo runtime tags tools with profiles and categories, then enables `agentLoop.toolSelection`.
+
+- Default profile: `support`
+- Alternate profile: `utility`
+- Tool search over deferred tools: enabled
+- Dynamic selection: enabled
+- Native hints:
+  - Anthropic: single-tool preference + no parallel tool use
+  - OpenAI: single-tool preference + parallel tool calls disabled
+
+Example request using the utility profile:
+
+```bash
+curl -X POST http://localhost:3001/api/copilot/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "toolProfile": "utility",
+    "messages": [
+      { "role": "user", "content": "What time is it on the server?" }
+    ]
+  }'
+```
+
+Example request using the support profile:
+
+```bash
+curl -X POST http://localhost:3001/api/copilot/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "toolProfile": "support",
+    "messages": [
+      { "role": "user", "content": "What does the Copilot SDK support?" }
+    ]
+  }'
+```
+
 ## Test Commands
 
 ### SSE Streaming (default)
diff --git a/examples/express-demo/src/index.ts b/examples/express-demo/src/index.ts
index 165ca0c..88ba6c7 100644
--- a/examples/express-demo/src/index.ts
+++ b/examples/express-demo/src/index.ts
@@ -71,6 +71,10 @@ const serverTools: ToolDefinition[] = [
     description:
       "Search the knowledge base for relevant documents. Use this when the user asks questions about YourGPT, the SDK, pricing, features, or how to use the product.",
     location: "server",
+    category: "knowledge",
+    group: "search",
+    profiles: ["support", "research"],
+    searchKeywords: ["docs", "pricing", "features", "sdk", "yourgpt"],
     // HIDDEN: This tool runs silently - user won't see it in the chat UI
     hidden: true,
     inputSchema: {
@@ -133,6 +137,11 @@ const serverTools: ToolDefinition[] = [
     name: "get_current_time",
     description: "Get the current server time",
     location: "server",
+    category: "utility",
+    group: "time",
+    profiles: ["utility"],
+    deferLoading: true,
+    searchKeywords: ["time", "clock", "timezone", "date"],
     // VISIBLE: This tool will show in the chat UI (hidden: false is default)
     inputSchema: {
       type: "object",
@@ -192,6 +201,39 @@ Be helpful, concise, and accurate. If the knowledge base doesn't have the answer
     enabled: true,
     maxIterations: 5,
     debug: true,
+    toolSelection: {
+      enabled: true,
+      defaultProfile: "support",
+      includeUnprofiled: true,
+      search: {
+        enabled: true,
+        maxResults: 3,
+        exposeWhenToolCountExceeds: 1,
+      },
+      dynamicSelection: {
+        enabled: true,
+        maxTools: 2,
+      },
+      profiles: {
+        support: {
+          include: ["category:knowledge", "search_knowledge_base"],
+          exclude: ["group:time"],
+        },
+        utility: {
+          include: ["category:utility", "get_current_time"],
+        },
+      },
+      nativeProviderHints: {
+        anthropic: {
+          toolChoice: "single",
+          disableParallelToolUse: true,
+        },
+        openai: {
+          toolChoice: "single",
+          parallelToolCalls: false,
+        },
+      },
+    },
   },
 });
 
@@ -234,6 +276,7 @@ app.post("/api/copilot-response/chat", async (req, res) => {
 app.post("/api/copilot/stream", async (req, res) => {
   console.log("\n========================================");
   console.log("[/api/copilot/stream] SSE streaming request");
+  console.log("Tool profile:", req.body.toolProfile || "default");
   console.log("Messages:", JSON.stringify(req.body.messages, null, 2));
   console.log("========================================\n");
 
@@ -254,6 +297,7 @@ app.post("/api/copilot/stream", async (req, res) => {
 app.post("/api/copilot/chat", async (req, res) => {
   console.log("\n========================================");
   console.log("[/api/copilot/chat] Non-streaming request");
+  console.log("Tool profile:", req.body.toolProfile || "default");
   console.log("Messages:", JSON.stringify(req.body.messages, null, 2));
   console.log("========================================\n");
 
diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index 555f258..501c6cd 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -12,6 +12,7 @@
  */
 
 import type {
+  ContextUsage,
   ToolDefinition,
   MessageAttachment,
   PermissionLevel,
@@ -54,6 +55,8 @@ export interface ChatWithToolsConfig {
   tools?: ToolDefinition[];
   /** Max tool execution iterations (default: 20) */
   maxIterations?: number;
+  /** Optional prompt/tool optimization controls */
+  optimization?: ChatConfig["optimization"];
   /** Custom error message when max iterations reached (sent to AI as tool result) */
   maxIterationsMessage?: string;
   /** State implementation (injected by framework adapter) */
@@ -70,6 +73,8 @@ export interface ChatWithToolsCallbacks extends ChatCallbacks<UIMessage> {
   onToolExecutionsChange?: (executions: ToolExecution[]) => void;
   /** Called when a tool requires approval */
   onApprovalRequired?: (execution: ToolExecution) => void;
+  /** Called when prompt context usage changes */
+  onContextUsageChange?: (usage: ContextUsage) => void;
 }
 
 /**
@@ -132,6 +137,7 @@ export class ChatWithTools {
       streaming: config.streaming,
       headers: config.headers,
       body: config.body,
+      optimization: config.optimization,
       threadId: config.threadId,
       debug: config.debug,
       initialMessages: config.initialMessages,
@@ -146,6 +152,7 @@ export class ChatWithTools {
         onMessageFinish: callbacks.onMessageFinish,
         onToolCalls: callbacks.onToolCalls,
         onFinish: callbacks.onFinish,
+        onContextUsageChange: callbacks.onContextUsageChange,
         // Server-side tool callbacks - track in agentLoop for UI display
         // IMPORTANT: Only track tools that are NOT registered client-side
         // Client-side tools are tracked via executeToolCalls() path
@@ -425,6 +432,28 @@ export class ChatWithTools {
     this.chat.setTools(tools);
   }
 
+  /**
+   * Update prompt/tool optimization controls.
+   */
+  setOptimizationConfig(config?: ChatConfig["optimization"]): void {
+    this.config.optimization = config;
+    this.chat.setOptimizationConfig(config);
+  }
+
+  /**
+   * Set the active tool profile used for request-time tool selection.
+   */
+  setToolProfile(profile?: string): void {
+    this.chat.setToolProfile(profile);
+  }
+
+  /**
+   * Get the most recent prompt context usage snapshot.
+   */
+  getContextUsage(): ContextUsage | null {
+    return this.chat.getContextUsage();
+  }
+
   /**
    * Set dynamic context (from useAIContext hook)
    */
diff --git a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
index 63a500a..3e74624 100644
--- a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
+++ b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
@@ -90,6 +90,7 @@ export class HttpTransport implements ChatTransport {
           systemPrompt: request.systemPrompt,
           llm: request.llm,
           tools: request.tools,
+          toolCatalog: request.toolCatalog,
           actions: request.actions,
           streaming: this.config.streaming,
           ...(resolved.configBody as Record<string, unknown>),
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 2a47223..859f19c 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -11,10 +11,12 @@
  */
 
 import type {
+  ContextUsage,
   MessageAttachment,
   AIResponseMode,
   ToolResponse,
   ToolDefinition,
+  ToolOptimizationConfig,
 } from "../../core";
 import type { ChatState } from "../interfaces/ChatState";
 import type {
@@ -40,9 +42,9 @@ import {
   createStreamState,
   processStreamChunk,
   isStreamDone,
-  requiresToolExecution,
 } from "../functions/stream";
 import { SimpleChatState } from "../interfaces/ChatState";
+import { ChatContextOptimizer } from "../optimizations";
 
 // ============================================
 // AI Response Control Helper
@@ -165,6 +167,8 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
   protected transport: ChatTransport;
   protected config: ChatConfig;
   protected callbacks: ChatCallbacks<T>;
+  protected optimizer: ChatContextOptimizer;
+  protected lastContextUsage: ContextUsage | null = null;
 
   // Event handlers
   private eventHandlers = new Map<
@@ -185,6 +189,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       body: init.body,
       threadId: init.threadId,
       debug: init.debug,
+      optimization: init.optimization,
     };
 
     // Use provided state or create default
@@ -205,6 +210,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
 
     // Store callbacks
     this.callbacks = init.callbacks ?? {};
+    this.optimizer = new ChatContextOptimizer(init.optimization);
 
     // Set initial messages
     if (init.initialMessages?.length) {
@@ -557,6 +563,28 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     this.config.tools = tools;
   }
 
+  /**
+   * Update prompt/tool optimization behavior.
+   */
+  setOptimizationConfig(config?: ToolOptimizationConfig): void {
+    this.config.optimization = config;
+    this.optimizer.updateConfig(config);
+  }
+
+  /**
+   * Select the active tool profile for future requests.
+   */
+  setToolProfile(profile?: string): void {
+    this.optimizer.setActiveProfile(profile);
+  }
+
+  /**
+   * Get the most recent prompt context usage snapshot.
+   */
+  getContextUsage(): ContextUsage | null {
+    return this.lastContextUsage;
+  }
+
   /**
    * Dynamic context from useAIContext hook
    */
@@ -619,102 +647,35 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
    * Build the request payload
    */
   protected buildRequest() {
-    // Send tools in SDK format - runtime handles conversion to LLM format
-    // Filter out tools that are marked as unavailable
-    const tools = this.config.tools
-      ?.filter((tool) => tool.available !== false)
-      .map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-        inputSchema: tool.inputSchema,
-      }));
-
-    // Build a map of toolCallId -> { toolName, args } from assistant messages
-    const toolCallMap = new Map<
-      string,
-      { toolName: string; args: Record<string, unknown> }
-    >();
-    for (const msg of this.state.messages) {
-      if (msg.role === "assistant" && msg.toolCalls) {
-        for (const tc of msg.toolCalls) {
-          try {
-            const args = tc.function?.arguments
-              ? JSON.parse(tc.function.arguments)
-              : {};
-            toolCallMap.set(tc.id, { toolName: tc.function.name, args });
-          } catch {
-            toolCallMap.set(tc.id, { toolName: tc.function.name, args: {} });
-          }
-        }
-      }
-    }
-
-    // Create a lookup for tool definitions by name
-    const toolDefMap = new Map<string, ToolWithAIConfig>();
-    if (this.config.tools) {
-      for (const tool of this.config.tools) {
-        toolDefMap.set(tool.name, {
-          name: tool.name,
-          aiResponseMode: tool.aiResponseMode,
-          aiContext: tool.aiContext,
-        });
-      }
-    }
+    const systemPrompt = this.dynamicContext
+      ? `${this.config.systemPrompt || ""}\n\n## Current App Context:\n${this.dynamicContext}`.trim()
+      : this.config.systemPrompt;
+    const optimized = this.optimizer.prepare({
+      messages: this.state.messages,
+      tools: this.config.tools,
+      systemPrompt,
+    });
+    this.lastContextUsage = optimized.contextUsage;
+    this.callbacks.onContextUsageChange?.(optimized.contextUsage);
 
     return {
-      messages: this.state.messages.map((m) => {
-        // For tool messages, transform based on aiResponseMode at SEND time
-        // This preserves full data in storage while sending brief to AI
-        if (m.role === "tool" && m.content && m.toolCallId) {
-          try {
-            const fullResult = JSON.parse(m.content);
-
-            // Look up the tool name and args from the tool call
-            const toolCallInfo = toolCallMap.get(m.toolCallId);
-            const toolDef = toolCallInfo
-              ? toolDefMap.get(toolCallInfo.toolName)
-              : undefined;
-            const toolArgs = toolCallInfo?.args;
-
-            const transformedContent = buildToolResultContentForAI(
-              fullResult,
-              toolDef,
-              toolArgs,
-            );
-            return {
-              role: m.role,
-              content: transformedContent,
-              tool_call_id: m.toolCallId,
-            };
-          } catch (e) {
-            // If not JSON, send as-is (log in debug mode)
-            this.debug("Failed to parse tool message JSON", {
-              content: m.content?.slice(0, 100),
-              error: e instanceof Error ? e.message : String(e),
-            });
-            return {
-              role: m.role,
-              content: m.content,
-              tool_call_id: m.toolCallId,
-            };
-          }
-        }
-
-        // Other messages unchanged
-        return {
-          role: m.role,
-          content: m.content,
-          tool_calls: m.toolCalls,
-          tool_call_id: m.toolCallId,
-          attachments: m.attachments,
-        };
-      }),
+      messages: optimized.messages,
       threadId: this.config.threadId,
-      systemPrompt: this.dynamicContext
-        ? `${this.config.systemPrompt || ""}\n\n## Current App Context:\n${this.dynamicContext}`.trim()
-        : this.config.systemPrompt,
+      systemPrompt,
       llm: this.config.llm,
-      tools: tools?.length ? tools : undefined,
+      tools: optimized.tools?.length ? optimized.tools : undefined,
+      toolCatalog: this.config.tools?.length
+        ? this.config.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            category: tool.category,
+            group: tool.group,
+            deferLoading: tool.deferLoading,
+            profiles: tool.profiles,
+            searchKeywords: tool.searchKeywords,
+            inputSchema: tool.inputSchema,
+          }))
+        : undefined,
     };
   }
 
@@ -856,13 +817,6 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         this.callbacks.onMessageDelta?.(assistantMessage.id, chunk.content);
       }
 
-      // Check for tool calls - only emit once per stream
-      if (requiresToolExecution(chunk) && !toolCallsEmitted) {
-        toolCallsEmitted = true;
-        this.debug("toolCalls", { toolCalls: updatedMessage.toolCalls });
-        this.emit("toolCalls", { toolCalls: updatedMessage.toolCalls });
-      }
-
       // Check for completion
       if (isStreamDone(chunk)) {
         this.debug("streamDone", { chunk });
@@ -874,6 +828,11 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
             count: chunk.messages.length,
           });
 
+          const currentStreamToolCallIds = new Set(
+            this.streamState?.toolCalls?.map((toolCall) => toolCall.id) ?? [],
+          );
+          const messagesToInsert: T[] = [];
+
           // Build hidden map from stream state's toolResults
           const toolCallsHidden: Record<string, boolean> = {};
           if (this.streamState?.toolResults) {
@@ -885,9 +844,26 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
           }
 
           for (const msg of chunk.messages) {
-            // Skip ALL assistant messages - they're handled via streaming
-            // (message:end/message:start events create separate messages for each turn)
-            if (msg.role === "assistant") {
+            // Skip plain assistant text messages because they are already represented
+            // by streamed message:start/message:delta/message:end events. Preserve
+            // assistant messages that carry tool_calls so tool results keep a valid
+            // preceding assistant tool_call message in local state.
+            if (msg.role === "assistant" && !msg.tool_calls?.length) {
+              continue;
+            }
+
+            // The current streamed turn already becomes an assistant message from
+            // streamState/tool_calls handling. Skip the duplicate copy from the
+            // done payload, but keep assistant tool_call messages from earlier
+            // recursive turns (for example search_tools followed by a later client
+            // tool call).
+            if (
+              msg.role === "assistant" &&
+              msg.tool_calls?.length &&
+              (msg.tool_calls as Array<{ id: string }>).every((toolCall) =>
+                currentStreamToolCallIds.has(toolCall.id),
+              )
+            ) {
               continue;
             }
 
@@ -911,7 +887,40 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
               metadata,
             } as T;
 
-            this.state.pushMessage(message);
+            messagesToInsert.push(message);
+          }
+
+          if (messagesToInsert.length > 0) {
+            const currentMessages = this.state.messages;
+            const currentStreamIndex = this.streamState
+              ? currentMessages.findIndex(
+                  (message) => message.id === this.streamState!.messageId,
+                )
+              : -1;
+
+            if (currentStreamIndex === -1) {
+              this.state.setMessages([...currentMessages, ...messagesToInsert]);
+            } else {
+              this.state.setMessages([
+                ...currentMessages.slice(0, currentStreamIndex),
+                ...messagesToInsert,
+                ...currentMessages.slice(currentStreamIndex),
+              ]);
+            }
+          }
+
+          // Only execute client tools once the full done payload has been
+          // merged into local state. Emitting earlier on the first tool_calls
+          // chunk can race with recursive server-tool turns and produce an
+          // invalid continuation order for OpenAI-compatible providers.
+          if (
+            chunk.requiresAction &&
+            !toolCallsEmitted &&
+            updatedMessage.toolCalls?.length
+          ) {
+            toolCallsEmitted = true;
+            this.debug("toolCalls", { toolCalls: updatedMessage.toolCalls });
+            this.emit("toolCalls", { toolCalls: updatedMessage.toolCalls });
           }
         }
 
diff --git a/packages/copilot-sdk/src/chat/index.ts b/packages/copilot-sdk/src/chat/index.ts
index f36494e..eddc84b 100644
--- a/packages/copilot-sdk/src/chat/index.ts
+++ b/packages/copilot-sdk/src/chat/index.ts
@@ -75,6 +75,7 @@ export { AbstractChat, type ChatEvent, type ChatEventHandler } from "./classes";
 
 // AbstractAgentLoop (tool execution)
 export { AbstractAgentLoop } from "./AbstractAgentLoop";
+export { ChatContextOptimizer } from "./optimizations";
 
 // ChatWithTools (coordinated chat + tools - recommended)
 export {
diff --git a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
index 59e8b31..9ea76f4 100644
--- a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
+++ b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
@@ -28,6 +28,8 @@ export interface ChatRequest {
   llm?: Record<string, unknown>;
   /** Tool definitions */
   tools?: unknown[];
+  /** Full client-side tool catalog for server-side selection/search */
+  toolCatalog?: unknown[];
   /** Action definitions */
   actions?: unknown[];
   /** Additional body properties */
diff --git a/packages/copilot-sdk/src/chat/optimizations.ts b/packages/copilot-sdk/src/chat/optimizations.ts
new file mode 100644
index 0000000..9cced3f
--- /dev/null
+++ b/packages/copilot-sdk/src/chat/optimizations.ts
@@ -0,0 +1,1352 @@
+import type {
+  ContextUsage,
+  ContextSummarizationConfig,
+  ToolDefinition,
+  ToolOptimizationConfig,
+  ToolResultTruncationConfig,
+  ToolTruncationStrategy,
+} from "../core";
+import type { ChatRequest } from "./interfaces";
+import type { UIMessage } from "./types";
+
+const DEFAULT_CHARS_PER_TOKEN = 4;
+const DEFAULT_SAFETY_MARGIN = 1.2;
+const DEFAULT_INPUT_HEADROOM_RATIO = 0.75;
+const DEFAULT_SYSTEM_PROMPT_SHARE = 0.15;
+const DEFAULT_HISTORY_SHARE = 0.5;
+const DEFAULT_TOOL_RESULTS_SHARE = 0.3;
+const DEFAULT_TOOL_DEFINITIONS_SHARE = 0.05;
+const DEFAULT_MAX_TOOL_RESULT_CONTEXT_SHARE = 0.3;
+const DEFAULT_TOOL_RESULT_HARD_MAX_CHARS = 400_000;
+const DEFAULT_TOOL_RESULT_MIN_KEEP_CHARS = 2_000;
+const DEFAULT_TOOL_RESULT_STRATEGY: ToolTruncationStrategy = "head-tail";
+const DEFAULT_RECENT_HISTORY_PRESERVE = 6;
+const TOOL_RESULT_TRUNCATION_NOTICE =
+  "\n\n[tool result truncated to fit prompt budget]";
+const TOOL_RESULT_COMPACTION_NOTICE =
+  "[tool result compacted to preserve context budget]";
+const SYSTEM_PROMPT_TRUNCATION_NOTICE =
+  "\n\n[system prompt truncated to fit prompt budget]";
+const HISTORY_SUMMARY_HEADER = "Conversation summary of earlier context:";
+const HISTORY_SUMMARY_COMPACTION_NOTICE =
+  "\n\n[summary compacted to preserve context continuity]";
+const DEFAULT_SUMMARY_TRIGGER = 12;
+const DEFAULT_SUMMARY_CHUNK_SIZE = 10;
+const DEFAULT_SUMMARY_MAX_CHARS = 1_600;
+const SUMMARY_STOP_WORDS = new Set([
+  "about",
+  "after",
+  "again",
+  "also",
+  "because",
+  "been",
+  "before",
+  "being",
+  "could",
+  "from",
+  "have",
+  "into",
+  "just",
+  "more",
+  "need",
+  "only",
+  "over",
+  "same",
+  "some",
+  "than",
+  "that",
+  "their",
+  "them",
+  "then",
+  "there",
+  "these",
+  "they",
+  "this",
+  "those",
+  "through",
+  "under",
+  "very",
+  "want",
+  "were",
+  "what",
+  "when",
+  "where",
+  "which",
+  "while",
+  "with",
+  "would",
+  "your",
+]);
+
+type RequestMessage = ChatRequest["messages"][number];
+type RequestTool = {
+  name: string;
+  description: string;
+  category?: string;
+  group?: string;
+  deferLoading?: boolean;
+  profiles?: string[];
+  searchKeywords?: string[];
+  inputSchema: unknown;
+};
+
+type PreparedBuckets = {
+  systemPrompt: string | undefined;
+  transformedMessages: RequestMessage[];
+  historyMessages: RequestMessage[];
+  toolResultMessages: RequestMessage[];
+  requestTools: RequestTool[] | undefined;
+};
+
+function clampRatio(value: number | undefined, fallback: number): number {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(1, Math.max(0, value as number));
+}
+
+function unique<T>(values: T[]): T[] {
+  return [...new Set(values)];
+}
+
+function stringifyContent(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value == null) {
+    return "";
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function normalizeWhitespace(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function abbreviateText(text: string, maxChars = 220): string {
+  const normalized = normalizeWhitespace(text);
+  if (!normalized) {
+    return "";
+  }
+  if (normalized.length <= maxChars) {
+    return normalized;
+  }
+  return `${normalized.slice(0, Math.max(1, maxChars - 3)).trimEnd()}...`;
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9_\s-]/g, " ")
+    .split(/\s+/)
+    .filter((token) => token.length > 1);
+}
+
+function estimateTokens(
+  text: string,
+  charsPerToken = DEFAULT_CHARS_PER_TOKEN,
+): number {
+  if (!text) {
+    return 0;
+  }
+  return Math.ceil(text.length / Math.max(1, charsPerToken));
+}
+
+function estimateMessageTokens(
+  message: RequestMessage,
+  charsPerToken = DEFAULT_CHARS_PER_TOKEN,
+): number {
+  const content =
+    typeof message.content === "string"
+      ? message.content
+      : JSON.stringify(message.content ?? "");
+  const toolCalls = message.tool_calls
+    ? JSON.stringify(message.tool_calls)
+    : "";
+  const attachments = message.attachments
+    ? JSON.stringify(message.attachments)
+    : "";
+  return estimateTokens(
+    `${message.role}\n${content}\n${toolCalls}\n${attachments}`,
+    charsPerToken,
+  );
+}
+
+function estimateToolTokens(
+  tool: RequestTool,
+  charsPerToken = DEFAULT_CHARS_PER_TOKEN,
+): number {
+  return estimateTokens(JSON.stringify(tool), charsPerToken);
+}
+
+function buildToolQuery(messages: UIMessage[]): string {
+  return messages
+    .filter(
+      (message) => message.role === "user" || message.role === "assistant",
+    )
+    .slice(-3)
+    .map((message) => message.content)
+    .filter(Boolean)
+    .join(" ");
+}
+
+function matchesSelector(
+  tool: ToolDefinition,
+  selector: string,
+  activeProfile?: string,
+): boolean {
+  const normalized = selector.trim().toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+
+  if (normalized === "*" || normalized === "all") {
+    return true;
+  }
+  if (normalized === tool.name.toLowerCase()) {
+    return true;
+  }
+  if (normalized.startsWith("group:")) {
+    return (tool.group ?? "").toLowerCase() === normalized.slice(6);
+  }
+  if (normalized.startsWith("category:")) {
+    return (tool.category ?? "").toLowerCase() === normalized.slice(9);
+  }
+  if (normalized.startsWith("profile:")) {
+    return (tool.profiles ?? [])
+      .map((value) => value.toLowerCase())
+      .includes(normalized.slice(8));
+  }
+  if (activeProfile && normalized === activeProfile.toLowerCase()) {
+    return (tool.profiles ?? [])
+      .map((value) => value.toLowerCase())
+      .includes(normalized);
+  }
+  return false;
+}
+
+function scoreTool(
+  tool: ToolDefinition,
+  queryTokens: string[],
+  activeProfile?: string,
+): number {
+  const haystack = [
+    tool.name,
+    tool.description,
+    tool.category,
+    tool.group,
+    ...(tool.profiles ?? []),
+    ...(tool.searchKeywords ?? []),
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+
+  let score = tool.deferLoading ? 0 : 2;
+  if (activeProfile && tool.profiles?.includes(activeProfile)) {
+    score += 2;
+  }
+  for (const token of queryTokens) {
+    if (tool.name.toLowerCase() === token) {
+      score += 6;
+    } else if (tool.name.toLowerCase().includes(token)) {
+      score += 4;
+    } else if (haystack.includes(token)) {
+      score += 2;
+    }
+  }
+  return score;
+}
+
+function truncateText(
+  text: string,
+  maxChars: number,
+  strategy: ToolTruncationStrategy,
+  notice = TOOL_RESULT_TRUNCATION_NOTICE,
+): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+
+  const bodyBudget = Math.max(1, maxChars - notice.length);
+  if (strategy === "head") {
+    return text.slice(0, bodyBudget) + notice;
+  }
+
+  if (strategy === "head-tail" || strategy === "smart") {
+    const tailLooksImportant =
+      strategy === "smart"
+        ? /\b(error|exception|failed|traceback|summary|result|done|complete)\b/i.test(
+            text.slice(-2000),
+          )
+        : true;
+    if (tailLooksImportant && bodyBudget > 32) {
+      const tailBudget = Math.min(Math.floor(bodyBudget * 0.3), 4_000);
+      const headBudget = Math.max(1, bodyBudget - tailBudget - 32);
+      return (
+        text.slice(0, headBudget) +
+        "\n\n[... omitted ...]\n\n" +
+        text.slice(-tailBudget) +
+        notice
+      );
+    }
+  }
+
+  return text.slice(0, bodyBudget) + notice;
+}
+
+function isHistorySummaryMessage(message: RequestMessage): boolean {
+  return (
+    message.role === "system" &&
+    typeof message.content === "string" &&
+    message.content.startsWith(HISTORY_SUMMARY_HEADER)
+  );
+}
+
+function collectTopKeywords(messages: RequestMessage[]): string[] {
+  const counts = new Map<string, number>();
+  for (const message of messages) {
+    if (message.role !== "user") {
+      continue;
+    }
+    for (const token of tokenize(stringifyContent(message.content))) {
+      if (token.length < 3 || SUMMARY_STOP_WORDS.has(token)) {
+        continue;
+      }
+      counts.set(token, (counts.get(token) ?? 0) + 1);
+    }
+  }
+
+  return [...counts.entries()]
+    .sort((left, right) => {
+      const countDiff = right[1] - left[1];
+      if (countDiff !== 0) {
+        return countDiff;
+      }
+      return left[0].localeCompare(right[0]);
+    })
+    .slice(0, 5)
+    .map(([token]) => token);
+}
+
+function collectToolCallNames(messages: RequestMessage[]): Map<string, string> {
+  const toolCallNames = new Map<string, string>();
+  for (const message of messages) {
+    if (message.role !== "assistant" || !message.tool_calls?.length) {
+      continue;
+    }
+    for (const toolCall of message.tool_calls) {
+      const parsedToolCall = toolCall as {
+        id?: string;
+        function?: { name?: string };
+      };
+      if (parsedToolCall.id && parsedToolCall.function?.name) {
+        toolCallNames.set(parsedToolCall.id, parsedToolCall.function.name);
+      }
+    }
+  }
+  return toolCallNames;
+}
+
+function compressSummaryContent(
+  content: string,
+  maxChars: number,
+  fallbackBehavior: ContextSummarizationConfig["fallbackBehavior"] | undefined,
+): string {
+  if (content.length <= maxChars) {
+    return content;
+  }
+  if (fallbackBehavior === "error") {
+    throw new Error("History summary exceeded configured continuity budget.");
+  }
+  if (fallbackBehavior === "statistical") {
+    const lines = content.split("\n");
+    const retained = lines.filter((line) =>
+      /^(Conversation summary|Stats:|- Messages compacted:|- User turns compacted:|- Assistant turns compacted:|- Tool results compacted:|- Latest user request before preserved window:|- Latest assistant response before preserved window:)/.test(
+        line,
+      ),
+    );
+    const statistical = retained.join("\n");
+    if (statistical.length <= maxChars) {
+      return statistical;
+    }
+  }
+  return truncateText(
+    content,
+    maxChars,
+    "head",
+    HISTORY_SUMMARY_COMPACTION_NOTICE,
+  );
+}
+
+function buildHistorySummary(
+  messages: RequestMessage[],
+  summarization?: ContextSummarizationConfig,
+  maxChars = DEFAULT_SUMMARY_MAX_CHARS,
+): RequestMessage | null {
+  if (messages.length === 0) {
+    return null;
+  }
+
+  if (summarization?.enabled === false) {
+    return null;
+  }
+
+  const previousSummaries = messages.filter(isHistorySummaryMessage);
+  const rawMessages = messages.filter(
+    (message) => !isHistorySummaryMessage(message),
+  );
+  const focusWindowSize = Math.max(
+    1,
+    summarization?.chunkSize ?? DEFAULT_SUMMARY_CHUNK_SIZE,
+  );
+  const detailedThreshold = Math.max(
+    1,
+    summarization?.triggerAt ?? DEFAULT_SUMMARY_TRIGGER,
+  );
+  const focusMessages = rawMessages.slice(-focusWindowSize);
+  const userMessages = rawMessages.filter((message) => message.role === "user");
+  const assistantMessages = rawMessages.filter(
+    (message) => message.role === "assistant",
+  );
+  const toolMessages = rawMessages.filter((message) => message.role === "tool");
+  const recentUser =
+    abbreviateText(stringifyContent(userMessages.at(-1)?.content), 240) ||
+    "n/a";
+  const recentAssistant =
+    abbreviateText(stringifyContent(assistantMessages.at(-1)?.content), 240) ||
+    "n/a";
+  const recentUserGoals = userMessages
+    .slice(-3)
+    .map((message) => abbreviateText(stringifyContent(message.content), 180))
+    .filter(Boolean);
+  const recentAssistantNotes = assistantMessages
+    .map((message) => abbreviateText(stringifyContent(message.content), 180))
+    .filter(Boolean)
+    .slice(-2);
+  const toolCallNames = collectToolCallNames(rawMessages);
+  const toolActivity = unique([
+    ...focusMessages
+      .filter((message) => message.role === "assistant")
+      .flatMap((message) =>
+        (message.tool_calls ?? [])
+          .map((toolCall) => {
+            const parsedToolCall = toolCall as {
+              function?: { name?: string };
+            };
+            return parsedToolCall.function?.name;
+          })
+          .filter((name): name is string => Boolean(name)),
+      ),
+    ...toolMessages
+      .slice(-2)
+      .map((message) => {
+        const toolName = message.tool_call_id
+          ? toolCallNames.get(message.tool_call_id)
+          : undefined;
+        const snippet = abbreviateText(stringifyContent(message.content), 120);
+        return toolName && snippet
+          ? `${toolName}: ${snippet}`
+          : (toolName ?? snippet);
+      })
+      .filter(Boolean),
+  ]).slice(-4);
+  const priorSummaryCarryForward = previousSummaries
+    .map((message) =>
+      abbreviateText(
+        stringifyContent(message.content).replace(
+          `${HISTORY_SUMMARY_HEADER}\n`,
+          "",
+        ),
+        180,
+      ),
+    )
+    .filter(Boolean)
+    .slice(-2);
+  const topKeywords =
+    rawMessages.length >= detailedThreshold
+      ? collectTopKeywords(
+          focusMessages.length > 0 ? focusMessages : rawMessages,
+        )
+      : [];
+
+  const lines = [
+    HISTORY_SUMMARY_HEADER,
+    "Stats:",
+    `- Messages compacted: ${messages.length}`,
+    `- User turns compacted: ${userMessages.length}`,
+    `- Assistant turns compacted: ${assistantMessages.length}`,
+    `- Tool results compacted: ${toolMessages.length}`,
+  ];
+
+  if (previousSummaries.length > 0) {
+    lines.push(`- Previous summaries merged: ${previousSummaries.length}`);
+  }
+  if (rawMessages.length > focusMessages.length) {
+    lines.push(
+      `- Older compacted messages outside the detailed window: ${rawMessages.length - focusMessages.length}`,
+    );
+  }
+  if (topKeywords.length > 0) {
+    lines.push(`- Recurring user topics: ${topKeywords.join(", ")}`);
+  }
+  if (recentUser !== "n/a") {
+    lines.push(`- Latest user request before preserved window: ${recentUser}`);
+  }
+  if (recentAssistant !== "n/a") {
+    lines.push(
+      `- Latest assistant response before preserved window: ${recentAssistant}`,
+    );
+  }
+  if (recentUserGoals.length > 0) {
+    lines.push("Carry forward user goals:");
+    for (const goal of recentUserGoals) {
+      lines.push(`- ${goal}`);
+    }
+  }
+  if (recentAssistantNotes.length > 0) {
+    lines.push("Carry forward assistant commitments:");
+    for (const note of recentAssistantNotes) {
+      lines.push(`- ${note}`);
+    }
+  }
+  if (toolActivity.length > 0) {
+    lines.push("Recent tool activity:");
+    for (const item of toolActivity) {
+      lines.push(`- ${item}`);
+    }
+  }
+  if (priorSummaryCarryForward.length > 0) {
+    lines.push("Earlier carried-forward context:");
+    for (const item of priorSummaryCarryForward) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  const content = compressSummaryContent(
+    lines.join("\n"),
+    maxChars,
+    summarization?.fallbackBehavior,
+  );
+
+  return {
+    role: "system",
+    content,
+  };
+}
+
+function buildToolDefinitions(
+  selectedTools: ToolDefinition[],
+): RequestTool[] | undefined {
+  if (selectedTools.length === 0) {
+    return undefined;
+  }
+
+  return selectedTools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    category: tool.category,
+    group: tool.group,
+    deferLoading: tool.deferLoading,
+    profiles: tool.profiles,
+    searchKeywords: tool.searchKeywords,
+    inputSchema: tool.inputSchema,
+  }));
+}
+
+function resolveTruncationConfig(params: {
+  tool?: ToolDefinition;
+  config?: ToolOptimizationConfig;
+}): Required<ToolResultTruncationConfig> {
+  const charsPerToken =
+    params.config?.contextManagement?.tokenEstimation?.charsPerToken ??
+    DEFAULT_CHARS_PER_TOKEN;
+  const contextWindowTokens =
+    params.config?.contextBudget?.budget?.contextWindowTokens;
+  const globalConfig = params.config?.toolResultConfig?.truncation;
+  const perToolConfig = params.tool?.resultConfig?.truncation;
+  const merged = { ...globalConfig, ...perToolConfig };
+  const hardMaxChars =
+    merged.hardMaxChars ??
+    (contextWindowTokens
+      ? Math.floor(
+          contextWindowTokens *
+            clampRatio(
+              merged.maxContextShare,
+              DEFAULT_MAX_TOOL_RESULT_CONTEXT_SHARE,
+            ) *
+            charsPerToken,
+        )
+      : DEFAULT_TOOL_RESULT_HARD_MAX_CHARS);
+
+  return {
+    enabled: merged.enabled ?? true,
+    maxContextShare: clampRatio(
+      merged.maxContextShare,
+      DEFAULT_MAX_TOOL_RESULT_CONTEXT_SHARE,
+    ),
+    hardMaxChars: Math.max(1, hardMaxChars),
+    minKeepChars: Math.max(
+      256,
+      merged.minKeepChars ?? DEFAULT_TOOL_RESULT_MIN_KEEP_CHARS,
+    ),
+    strategy: merged.strategy ?? DEFAULT_TOOL_RESULT_STRATEGY,
+    preserveErrors: merged.preserveErrors ?? true,
+  };
+}
+
+function buildToolResultContent(
+  result: unknown,
+  tool?: ToolDefinition,
+  args?: Record<string, unknown>,
+): string {
+  if (typeof result === "string") {
+    return result;
+  }
+
+  const typedResult = (result ?? null) as
+    | ({
+        _aiResponseMode?: "none" | "brief" | "full";
+        _aiContext?: string;
+        _aiContent?: unknown;
+        _uiResources?: unknown;
+      } & Record<string, unknown>)
+    | null;
+  const responseMode =
+    typedResult?._aiResponseMode ?? tool?.aiResponseMode ?? "full";
+
+  if (typedResult?._aiContent) {
+    return JSON.stringify(typedResult._aiContent);
+  }
+
+  let aiContext = typedResult?._aiContext;
+  if (!aiContext && tool?.aiContext) {
+    aiContext =
+      typeof tool.aiContext === "function"
+        ? tool.aiContext(
+            (typedResult ?? { success: true }) as never,
+            args ?? {},
+          )
+        : tool.aiContext;
+  }
+
+  switch (responseMode) {
+    case "none":
+      return aiContext ?? "[Result displayed to user]";
+    case "brief":
+      return aiContext ?? "[Tool executed successfully]";
+    case "full":
+    default: {
+      if (aiContext) {
+        const {
+          _aiResponseMode,
+          _aiContext,
+          _aiContent,
+          _uiResources,
+          ...dataOnly
+        } = typedResult ?? {};
+        return `${aiContext}\n\nFull data: ${JSON.stringify(dataOnly)}`;
+      }
+      if (typedResult?._uiResources) {
+        const { _uiResources, ...dataOnly } = typedResult;
+        return JSON.stringify(dataOnly);
+      }
+      return JSON.stringify(result);
+    }
+  }
+}
+
+export function buildToolResultContentForPrompt(
+  result: unknown,
+  tool: ToolDefinition | undefined,
+  args: Record<string, unknown>,
+  config: ToolOptimizationConfig | undefined,
+): string {
+  const text = buildToolResultContent(result, tool, args);
+  const truncation = resolveTruncationConfig({ tool, config });
+  if (!truncation.enabled) {
+    return text;
+  }
+
+  if (
+    truncation.preserveErrors &&
+    typeof result === "object" &&
+    result !== null &&
+    "error" in result &&
+    typeof (result as { error?: unknown }).error === "string"
+  ) {
+    return text;
+  }
+
+  const maxChars = Math.max(truncation.minKeepChars, truncation.hardMaxChars);
+  return truncateText(text, maxChars, truncation.strategy);
+}
+
+function sliceHistoryToMaxMessages(params: {
+  historyMessages: RequestMessage[];
+  maxMessages: number | undefined;
+  pruneStrategy: "oldest" | "least-relevant" | "summarize" | undefined;
+  summarization?: ContextSummarizationConfig;
+}): RequestMessage[] {
+  const { historyMessages, maxMessages, pruneStrategy, summarization } = params;
+  if (!maxMessages || historyMessages.length <= maxMessages) {
+    return historyMessages;
+  }
+
+  const dropped = historyMessages.slice(
+    0,
+    historyMessages.length - maxMessages,
+  );
+  const kept = historyMessages.slice(-maxMessages);
+  if (pruneStrategy === "summarize") {
+    const summary = buildHistorySummary(dropped, summarization);
+    return summary ? [summary, ...kept] : kept;
+  }
+  return kept;
+}
+
+function compactHistoryToTokenBudget(params: {
+  historyMessages: RequestMessage[];
+  maxTokens: number | undefined;
+  preserveRecent: number;
+  charsPerToken: number;
+  pruneStrategy: "oldest" | "least-relevant" | "summarize" | undefined;
+  summarization?: ContextSummarizationConfig;
+}): RequestMessage[] {
+  const {
+    maxTokens,
+    preserveRecent,
+    charsPerToken,
+    pruneStrategy,
+    summarization,
+  } = params;
+  let historyMessages = params.historyMessages;
+  if (!maxTokens) {
+    return historyMessages;
+  }
+
+  const getHistoryTokens = () =>
+    historyMessages.reduce(
+      (sum, message) => sum + estimateMessageTokens(message, charsPerToken),
+      0,
+    );
+
+  while (historyMessages.length > 1 && getHistoryTokens() > maxTokens) {
+    const prunableCount = Math.max(0, historyMessages.length - preserveRecent);
+    if (prunableCount <= 0) {
+      const firstMessage = historyMessages[0];
+      if (
+        isHistorySummaryMessage(firstMessage) &&
+        typeof firstMessage.content === "string"
+      ) {
+        const compactedSummary = compressSummaryContent(
+          firstMessage.content,
+          Math.max(400, Math.floor(maxTokens * charsPerToken * 0.25)),
+          summarization?.fallbackBehavior,
+        );
+        if (compactedSummary !== firstMessage.content) {
+          historyMessages = [
+            { ...firstMessage, content: compactedSummary },
+            ...historyMessages.slice(1),
+          ];
+          continue;
+        }
+      }
+      historyMessages = historyMessages.slice(1);
+      continue;
+    }
+
+    const pruned = historyMessages.slice(0, prunableCount);
+    const kept = historyMessages.slice(prunableCount);
+    if (pruneStrategy === "summarize") {
+      const summary = buildHistorySummary(
+        pruned,
+        summarization,
+        Math.max(500, Math.floor(maxTokens * charsPerToken * 0.35)),
+      );
+      historyMessages = summary ? [summary, ...kept] : kept;
+    } else {
+      historyMessages = kept;
+    }
+  }
+
+  return historyMessages;
+}
+
+function compactToolResultsToBudget(params: {
+  toolResultMessages: RequestMessage[];
+  maxTokens: number | undefined;
+  charsPerToken: number;
+}): RequestMessage[] {
+  let toolResultMessages = params.toolResultMessages;
+  if (!params.maxTokens) {
+    return toolResultMessages;
+  }
+
+  const getToolResultTokens = () =>
+    toolResultMessages.reduce(
+      (sum, message) =>
+        sum + estimateMessageTokens(message, params.charsPerToken),
+      0,
+    );
+
+  while (
+    toolResultMessages.length > 0 &&
+    getToolResultTokens() > params.maxTokens
+  ) {
+    const index = toolResultMessages.findIndex(
+      (message) => message.content !== TOOL_RESULT_COMPACTION_NOTICE,
+    );
+    if (index === -1) {
+      break;
+    }
+
+    toolResultMessages = toolResultMessages.map((message, currentIndex) =>
+      currentIndex === index
+        ? { ...message, content: TOOL_RESULT_COMPACTION_NOTICE }
+        : message,
+    );
+  }
+
+  return toolResultMessages;
+}
+
+function fitToolsToBudget(params: {
+  tools: RequestTool[] | undefined;
+  maxTokens: number | undefined;
+  charsPerToken: number;
+}): RequestTool[] | undefined {
+  let tools = params.tools;
+  if (!tools?.length || !params.maxTokens) {
+    return tools;
+  }
+
+  const getToolTokens = () =>
+    tools!.reduce(
+      (sum, tool) => sum + estimateToolTokens(tool, params.charsPerToken),
+      0,
+    );
+
+  while (tools.length > 0 && getToolTokens() > params.maxTokens) {
+    tools = tools.slice(0, -1);
+  }
+
+  return tools;
+}
+
+function truncateSystemPromptToBudget(params: {
+  systemPrompt: string | undefined;
+  maxTokens: number | undefined;
+  charsPerToken: number;
+}): string | undefined {
+  const { systemPrompt, maxTokens, charsPerToken } = params;
+  if (!systemPrompt || !maxTokens) {
+    return systemPrompt;
+  }
+
+  const maxChars = maxTokens * charsPerToken;
+  if (systemPrompt.length <= maxChars) {
+    return systemPrompt;
+  }
+
+  return truncateText(
+    systemPrompt,
+    maxChars,
+    "head",
+    SYSTEM_PROMPT_TRUNCATION_NOTICE,
+  );
+}
+
+function calculateBuckets(params: {
+  systemPrompt: string | undefined;
+  historyMessages: RequestMessage[];
+  toolResultMessages: RequestMessage[];
+  requestTools: RequestTool[] | undefined;
+  charsPerToken: number;
+  availableBudget: number;
+  warnings: string[];
+}): ContextUsage {
+  const systemPromptTokens = estimateTokens(
+    params.systemPrompt ?? "",
+    params.charsPerToken,
+  );
+  const historyTokens = params.historyMessages.reduce(
+    (sum, message) =>
+      sum + estimateMessageTokens(message, params.charsPerToken),
+    0,
+  );
+  const toolResultsTokens = params.toolResultMessages.reduce(
+    (sum, message) =>
+      sum + estimateMessageTokens(message, params.charsPerToken),
+    0,
+  );
+  const toolDefinitionTokens = (params.requestTools ?? []).reduce(
+    (sum, tool) => sum + estimateToolTokens(tool, params.charsPerToken),
+    0,
+  );
+  const total =
+    systemPromptTokens +
+    historyTokens +
+    toolResultsTokens +
+    toolDefinitionTokens;
+  const budget = Number.isFinite(params.availableBudget)
+    ? params.availableBudget
+    : total;
+  const toPart = (tokens: number) => ({
+    tokens,
+    percent: budget > 0 ? Number(((tokens / budget) * 100).toFixed(2)) : 0,
+  });
+
+  return {
+    total: toPart(total),
+    breakdown: {
+      systemPrompt: toPart(systemPromptTokens),
+      history: toPart(historyTokens),
+      toolResults: toPart(toolResultsTokens),
+      tools: toPart(toolDefinitionTokens),
+    },
+    budget: {
+      available: budget,
+      remaining: Math.max(0, budget - total),
+    },
+    warnings: unique(params.warnings),
+  };
+}
+
+function mergeBucketsInOriginalOrder(params: {
+  transformedMessages: RequestMessage[];
+  historyMessages: RequestMessage[];
+  toolResultMessages: RequestMessage[];
+}): RequestMessage[] {
+  const historyQueue = [...params.historyMessages];
+  const toolQueue = [...params.toolResultMessages];
+
+  return params.transformedMessages.flatMap((message) => {
+    if (message.role === "tool") {
+      const nextTool = toolQueue.shift();
+      return nextTool ? [nextTool] : [];
+    }
+    const nextHistory = historyQueue.shift();
+    return nextHistory ? [nextHistory] : [];
+  });
+}
+
+export class ChatContextOptimizer {
+  private config: ToolOptimizationConfig | undefined;
+  private activeProfile: string | undefined;
+  private lastContextUsage: ContextUsage | null = null;
+
+  constructor(config?: ToolOptimizationConfig) {
+    this.config = config;
+    this.activeProfile = config?.toolProfiles?.defaultProfile;
+  }
+
+  updateConfig(config?: ToolOptimizationConfig): void {
+    this.config = config;
+    if (!this.activeProfile) {
+      this.activeProfile = config?.toolProfiles?.defaultProfile;
+    }
+  }
+
+  setActiveProfile(profile?: string): void {
+    this.activeProfile = profile?.trim() || undefined;
+  }
+
+  getContextUsage(): ContextUsage | null {
+    return this.lastContextUsage;
+  }
+
+  prepare(params: {
+    messages: UIMessage[];
+    tools?: ToolDefinition[];
+    systemPrompt?: string;
+  }): {
+    messages: RequestMessage[];
+    tools?: RequestTool[];
+    contextUsage: ContextUsage;
+    warnings: string[];
+  } {
+    const charsPerToken =
+      this.config?.contextManagement?.tokenEstimation?.charsPerToken ??
+      DEFAULT_CHARS_PER_TOKEN;
+    const safetyMargin =
+      this.config?.contextManagement?.tokenEstimation?.safetyMargin ??
+      DEFAULT_SAFETY_MARGIN;
+    const warnings: string[] = [];
+    const contextManagement = this.config?.contextManagement;
+    const contextBudget = this.config?.contextBudget;
+    const allTools = params.tools ?? [];
+    const selectedTools = this.selectTools(allTools, params.messages);
+    const transformedMessages = this.transformMessages(
+      params.messages,
+      allTools,
+    );
+    const preserveRecent =
+      contextManagement?.summarization?.preserveRecent ??
+      DEFAULT_RECENT_HISTORY_PRESERVE;
+
+    let buckets: PreparedBuckets = {
+      systemPrompt: params.systemPrompt,
+      transformedMessages,
+      historyMessages: transformedMessages.filter(
+        (message) => message.role !== "tool",
+      ),
+      toolResultMessages: transformedMessages.filter(
+        (message) => message.role === "tool",
+      ),
+      requestTools: buildToolDefinitions(selectedTools),
+    };
+
+    if (contextManagement?.enabled) {
+      buckets.historyMessages = sliceHistoryToMaxMessages({
+        historyMessages: buckets.historyMessages,
+        maxMessages: contextManagement.history?.maxMessages,
+        pruneStrategy: contextManagement.history?.pruneStrategy,
+        summarization: contextManagement?.summarization,
+      });
+    }
+
+    const budgetConfig = contextBudget?.budget;
+    const contextWindowTokens = budgetConfig?.contextWindowTokens;
+    const inputHeadroomRatio = clampRatio(
+      budgetConfig?.inputHeadroomRatio,
+      DEFAULT_INPUT_HEADROOM_RATIO,
+    );
+    const availableBudget = contextWindowTokens
+      ? Math.max(1, Math.floor(contextWindowTokens * inputHeadroomRatio))
+      : Number.POSITIVE_INFINITY;
+
+    const sharedBudget = Number.isFinite(availableBudget)
+      ? availableBudget
+      : undefined;
+    const systemPromptBudget = sharedBudget
+      ? Math.max(
+          1,
+          Math.floor(
+            sharedBudget *
+              clampRatio(
+                budgetConfig?.systemPromptShare,
+                DEFAULT_SYSTEM_PROMPT_SHARE,
+              ),
+          ),
+        )
+      : undefined;
+    const historyBudgetByShare = sharedBudget
+      ? Math.max(
+          1,
+          Math.floor(
+            sharedBudget *
+              clampRatio(budgetConfig?.historyShare, DEFAULT_HISTORY_SHARE),
+          ),
+        )
+      : undefined;
+    const historyBudgetByConfig =
+      contextManagement?.enabled && contextManagement.history?.maxTokens
+        ? Math.floor(contextManagement.history.maxTokens / safetyMargin)
+        : undefined;
+    const historyBudget =
+      historyBudgetByShare && historyBudgetByConfig
+        ? Math.min(historyBudgetByShare, historyBudgetByConfig)
+        : (historyBudgetByShare ?? historyBudgetByConfig);
+    const toolResultsBudget = sharedBudget
+      ? Math.max(
+          1,
+          Math.floor(
+            sharedBudget *
+              clampRatio(
+                budgetConfig?.toolResultsShare,
+                DEFAULT_TOOL_RESULTS_SHARE,
+              ),
+          ),
+        )
+      : undefined;
+    const toolDefinitionsBudget = sharedBudget
+      ? Math.max(
+          1,
+          Math.floor(
+            sharedBudget *
+              clampRatio(
+                budgetConfig?.toolDefinitionsShare,
+                DEFAULT_TOOL_DEFINITIONS_SHARE,
+              ),
+          ),
+        )
+      : undefined;
+
+    if (contextBudget?.enabled) {
+      buckets.systemPrompt = truncateSystemPromptToBudget({
+        systemPrompt: buckets.systemPrompt,
+        maxTokens: systemPromptBudget,
+        charsPerToken,
+      });
+    }
+
+    buckets.historyMessages = compactHistoryToTokenBudget({
+      historyMessages: buckets.historyMessages,
+      maxTokens: historyBudget,
+      preserveRecent,
+      charsPerToken,
+      pruneStrategy: contextManagement?.history?.pruneStrategy,
+      summarization: contextManagement?.summarization,
+    });
+
+    buckets.toolResultMessages = compactToolResultsToBudget({
+      toolResultMessages: buckets.toolResultMessages,
+      maxTokens: toolResultsBudget,
+      charsPerToken,
+    });
+
+    buckets.requestTools = fitToolsToBudget({
+      tools: buckets.requestTools,
+      maxTokens: toolDefinitionsBudget,
+      charsPerToken,
+    });
+
+    let usage = calculateBuckets({
+      ...buckets,
+      charsPerToken,
+      availableBudget,
+      warnings,
+    });
+
+    if (
+      Number.isFinite(availableBudget) &&
+      usage.total.tokens > availableBudget
+    ) {
+      // Final global fallback: preserve recent history, compact tool results first, then trim history and tools.
+      buckets.toolResultMessages = compactToolResultsToBudget({
+        toolResultMessages: buckets.toolResultMessages,
+        maxTokens: Math.max(
+          1,
+          usage.breakdown.toolResults.tokens -
+            usage.total.tokens +
+            availableBudget,
+        ),
+        charsPerToken,
+      });
+
+      usage = calculateBuckets({
+        ...buckets,
+        charsPerToken,
+        availableBudget,
+        warnings,
+      });
+
+      if (usage.total.tokens > availableBudget) {
+        const overflow = usage.total.tokens - availableBudget;
+        buckets.historyMessages = compactHistoryToTokenBudget({
+          historyMessages: buckets.historyMessages,
+          maxTokens: Math.max(1, usage.breakdown.history.tokens - overflow),
+          preserveRecent,
+          charsPerToken,
+          pruneStrategy: contextManagement?.history?.pruneStrategy,
+        });
+        usage = calculateBuckets({
+          ...buckets,
+          charsPerToken,
+          availableBudget,
+          warnings,
+        });
+      }
+
+      if (usage.total.tokens > availableBudget) {
+        buckets.requestTools = fitToolsToBudget({
+          tools: buckets.requestTools,
+          maxTokens: Math.max(
+            1,
+            usage.breakdown.tools.tokens -
+              (usage.total.tokens - availableBudget),
+          ),
+          charsPerToken,
+        });
+        usage = calculateBuckets({
+          ...buckets,
+          charsPerToken,
+          availableBudget,
+          warnings,
+        });
+      }
+    }
+
+    if (
+      Number.isFinite(availableBudget) &&
+      usage.total.tokens > availableBudget
+    ) {
+      warnings.push(
+        `Prompt budget exceeded: using ${usage.total.tokens} tokens of ${availableBudget}.`,
+      );
+      usage = {
+        ...usage,
+        warnings: unique(warnings),
+      };
+      if (contextBudget?.enforcement?.mode === "error") {
+        throw new Error(warnings[warnings.length - 1]);
+      }
+      contextBudget?.enforcement?.onBudgetExceeded?.(usage);
+    } else {
+      usage = {
+        ...usage,
+        warnings: unique(warnings),
+      };
+    }
+
+    contextBudget?.monitoring?.onUsageUpdate?.(usage);
+    this.lastContextUsage = usage;
+
+    return {
+      messages: mergeBucketsInOriginalOrder(buckets),
+      tools: buckets.requestTools,
+      contextUsage: usage,
+      warnings: usage.warnings,
+    };
+  }
+
+  private selectTools(
+    tools: ToolDefinition[],
+    messages: UIMessage[],
+  ): ToolDefinition[] {
+    if (!tools.length) {
+      return [];
+    }
+
+    const available = tools.filter((tool) => tool.available !== false);
+    const profileConfig = this.config?.toolProfiles;
+    if (!profileConfig?.enabled) {
+      return available;
+    }
+
+    const activeProfile = this.activeProfile ?? profileConfig.defaultProfile;
+    const includeUnprofiled = profileConfig.includeUnprofiled ?? true;
+    const profile = activeProfile
+      ? profileConfig.profiles?.[activeProfile]
+      : undefined;
+    let filtered = available;
+
+    if (profile?.include?.length) {
+      filtered = filtered.filter(
+        (tool) =>
+          profile.include!.some((selector) =>
+            matchesSelector(tool, selector, activeProfile),
+          ) ||
+          (!!activeProfile && tool.profiles?.includes(activeProfile)),
+      );
+    } else if (activeProfile) {
+      filtered = filtered.filter((tool) => {
+        if (tool.profiles?.length) {
+          return tool.profiles.includes(activeProfile);
+        }
+        return includeUnprofiled;
+      });
+    }
+
+    if (profile?.exclude?.length) {
+      filtered = filtered.filter(
+        (tool) =>
+          !profile.exclude!.some((selector) =>
+            matchesSelector(tool, selector, activeProfile),
+          ),
+      );
+    }
+
+    if (!profileConfig.dynamicSelection?.enabled) {
+      return filtered;
+    }
+
+    const maxTools = Math.max(
+      1,
+      Math.min(
+        profileConfig.dynamicSelection.maxTools ?? filtered.length,
+        filtered.length,
+      ),
+    );
+    const queryTokens = tokenize(buildToolQuery(messages));
+    return [...filtered]
+      .sort((left, right) => {
+        const scoreDiff =
+          scoreTool(right, queryTokens, activeProfile) -
+          scoreTool(left, queryTokens, activeProfile);
+        if (scoreDiff !== 0) {
+          return scoreDiff;
+        }
+        return left.name.localeCompare(right.name);
+      })
+      .slice(0, maxTools);
+  }
+
+  private transformMessages(
+    messages: UIMessage[],
+    allTools: ToolDefinition[],
+  ): RequestMessage[] {
+    const toolCallMap = new Map<
+      string,
+      { toolName: string; args: Record<string, unknown> }
+    >();
+    for (const message of messages) {
+      if (message.role !== "assistant" || !message.toolCalls?.length) {
+        continue;
+      }
+      for (const toolCall of message.toolCalls) {
+        try {
+          toolCallMap.set(toolCall.id, {
+            toolName: toolCall.function.name,
+            args: JSON.parse(toolCall.function.arguments),
+          });
+        } catch {
+          toolCallMap.set(toolCall.id, {
+            toolName: toolCall.function.name,
+            args: {},
+          });
+        }
+      }
+    }
+
+    const toolDefMap = new Map(
+      allTools.map((tool) => [tool.name, tool] as const),
+    );
+
+    return messages.map((message) => {
+      if (message.role !== "tool") {
+        return {
+          role: message.role,
+          content: message.content,
+          tool_calls: message.toolCalls,
+          tool_call_id: message.toolCallId,
+          attachments: message.attachments,
+        };
+      }
+
+      const toolCall = message.toolCallId
+        ? toolCallMap.get(message.toolCallId)
+        : undefined;
+      const tool = toolCall ? toolDefMap.get(toolCall.toolName) : undefined;
+      let content = message.content;
+
+      try {
+        const parsed = JSON.parse(message.content);
+        content = buildToolResultContentForPrompt(
+          parsed,
+          tool,
+          toolCall?.args ?? {},
+          this.config,
+        );
+      } catch {
+        content = buildToolResultContentForPrompt(
+          message.content,
+          tool,
+          toolCall?.args ?? {},
+          this.config,
+        );
+      }
+
+      return {
+        role: message.role,
+        content,
+        tool_call_id: message.toolCallId,
+      };
+    });
+  }
+}
diff --git a/packages/copilot-sdk/src/chat/types/chat.ts b/packages/copilot-sdk/src/chat/types/chat.ts
index f2f14a4..1c536ae 100644
--- a/packages/copilot-sdk/src/chat/types/chat.ts
+++ b/packages/copilot-sdk/src/chat/types/chat.ts
@@ -4,7 +4,13 @@
  * Configuration and status types for chat functionality.
  */
 
-import type { LLMConfig, MessageAttachment, ToolDefinition } from "../../core";
+import type {
+  ContextUsage,
+  LLMConfig,
+  MessageAttachment,
+  ToolDefinition,
+  ToolOptimizationConfig,
+} from "../../core";
 import type { Resolvable } from "../../core/utils/resolvable";
 import type { UIMessage } from "./message";
 
@@ -52,6 +58,8 @@ export interface ChatConfig {
   debug?: boolean;
   /** Available tools (passed to LLM) */
   tools?: ToolDefinition[];
+  /** Optional prompt/tool optimization controls */
+  optimization?: ToolOptimizationConfig;
 }
 
 /**
@@ -96,6 +104,8 @@ export 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) */
diff --git a/packages/copilot-sdk/src/core/index.ts b/packages/copilot-sdk/src/core/index.ts
index da66e12..dcc7d36 100644
--- a/packages/copilot-sdk/src/core/index.ts
+++ b/packages/copilot-sdk/src/core/index.ts
@@ -167,6 +167,19 @@ export type {
   ToolRenderProps,
   ToolDefinition,
   ToolConfig,
+  ToolResultConfig,
+  ToolResultTruncationConfig,
+  ToolTruncationStrategy,
+  ToolProfile,
+  ToolProfileConfig,
+  ContextHistoryConfig,
+  ContextSummarizationConfig,
+  TokenEstimationConfig,
+  ContextManagementConfig,
+  ContextUsagePart,
+  ContextUsage,
+  ContextBudgetConfig,
+  ToolOptimizationConfig,
   ToolSet,
   ToolSetEntry,
   UnifiedToolCall,
diff --git a/packages/copilot-sdk/src/core/types/tools.ts b/packages/copilot-sdk/src/core/types/tools.ts
index ae785d4..b10c4d5 100644
--- a/packages/copilot-sdk/src/core/types/tools.ts
+++ b/packages/copilot-sdk/src/core/types/tools.ts
@@ -174,6 +174,153 @@ export type AIContent =
   | { type: "image"; data: string; mediaType: string }
   | { type: "text"; text: string };
 
+/**
+ * How large tool results should be trimmed before they are sent back to the AI.
+ */
+export type ToolTruncationStrategy = "head" | "head-tail" | "smart";
+
+/**
+ * Truncation controls for tool results.
+ */
+export 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.
+ */
+export interface ToolResultConfig {
+  truncation?: ToolResultTruncationConfig;
+}
+
+/**
+ * Named tool profile for selective loading.
+ */
+export interface ToolProfile {
+  name: string;
+  description?: string;
+  include?: string[];
+  exclude?: string[];
+}
+
+/**
+ * Tool profile configuration.
+ */
+export 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.
+ */
+export interface ContextHistoryConfig {
+  maxMessages?: number;
+  maxTokens?: number;
+  maxContextShare?: number;
+  pruneStrategy?: "oldest" | "least-relevant" | "summarize";
+}
+
+/**
+ * Optional summarization controls used during history compaction.
+ */
+export interface ContextSummarizationConfig {
+  enabled?: boolean;
+  triggerAt?: number;
+  chunkSize?: number;
+  preserveRecent?: number;
+  fallbackBehavior?: "truncate" | "statistical" | "error";
+}
+
+/**
+ * Token estimation controls.
+ */
+export interface TokenEstimationConfig {
+  safetyMargin?: number;
+  charsPerToken?: number;
+}
+
+/**
+ * Conversation context management.
+ */
+export interface ContextManagementConfig {
+  enabled?: boolean;
+  history?: ContextHistoryConfig;
+  summarization?: ContextSummarizationConfig;
+  tokenEstimation?: TokenEstimationConfig;
+}
+
+/**
+ * One budget bucket in the prompt context.
+ */
+export interface ContextUsagePart {
+  tokens: number;
+  percent: number;
+}
+
+/**
+ * Prompt context usage snapshot.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface ToolOptimizationConfig {
+  toolProfiles?: ToolProfileConfig;
+  toolResultConfig?: ToolResultConfig;
+  contextManagement?: ContextManagementConfig;
+  contextBudget?: ContextBudgetConfig;
+}
+
 /**
  * Tool response format
  */
@@ -368,6 +515,18 @@ export 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;
 
   // ============================================
   // Display Configuration
@@ -673,6 +832,8 @@ export interface AgentLoopConfig {
   debug?: boolean;
   /** Whether to enable the agentic loop (default: true) */
   enabled?: boolean;
+  /** Optional prompt/tool optimization controls */
+  optimization?: ToolOptimizationConfig;
 }
 
 /**
@@ -738,6 +899,18 @@ export 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;
 
   // Display Configuration
   /** Human-readable title for UI display */
@@ -799,6 +972,12 @@ export function tool<TParams = Record<string, unknown>>(
   return {
     description: config.description,
     location: config.location ?? "client",
+    category: config.category,
+    group: config.group,
+    deferLoading: config.deferLoading,
+    profiles: config.profiles,
+    searchKeywords: config.searchKeywords,
+    resultConfig: config.resultConfig,
     // Display configuration
     title: config.title,
     executingTitle: config.executingTitle,
diff --git a/packages/llm-sdk/README.md b/packages/llm-sdk/README.md
index e546c5d..c6f7c50 100644
--- a/packages/llm-sdk/README.md
+++ b/packages/llm-sdk/README.md
@@ -55,6 +55,65 @@ export async function POST(req: Request) {
 }
 ```
 
+## Selective Tool Loading
+
+`llm-sdk` can now narrow tools before they reach the provider. This is opt-in and works with both local ranking and provider-native hints.
+
+```ts
+import { createRuntime, type ToolDefinition } from "@yourgpt/llm-sdk";
+import { createOpenAI } from "@yourgpt/llm-sdk/openai";
+
+const tools: ToolDefinition[] = [
+  {
+    name: "search_docs",
+    description: "Search product docs",
+    location: "server",
+    category: "knowledge",
+    profiles: ["support", "research"],
+    searchKeywords: ["docs", "kb", "help"],
+    inputSchema: { type: "object", properties: { query: { type: "string" } } },
+    handler: async ({ query }) => ({ query }),
+  },
+  {
+    name: "get_time",
+    description: "Get current time",
+    location: "server",
+    category: "utility",
+    profiles: ["utility"],
+    deferLoading: true,
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => ({ now: new Date().toISOString() }),
+  },
+];
+
+const runtime = createRuntime({
+  provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  model: "gpt-4o-mini",
+  tools,
+  agentLoop: {
+    enabled: true,
+    toolSelection: {
+      enabled: true,
+      defaultProfile: "support",
+      search: {
+        enabled: true,
+        maxResults: 4,
+        exposeWhenToolCountExceeds: 1,
+      },
+      dynamicSelection: { enabled: true, maxTools: 2 },
+      nativeProviderHints: {
+        openai: { toolChoice: "single", parallelToolCalls: false },
+      },
+    },
+  },
+});
+
+// Request body can override the active profile:
+// { "messages": [...], "toolProfile": "utility" }
+```
+
+When `search.enabled` is on, deferred tools can be discovered through a hidden `search_tools` server tool. Matching tools are loaded into the next loop iteration instead of sending every deferred tool definition up front.
+
 ## Documentation
 
 Visit **[copilot-sdk.yourgpt.ai](https://copilot-sdk.yourgpt.ai)** for full documentation:
diff --git a/packages/llm-sdk/src/adapters/anthropic.ts b/packages/llm-sdk/src/adapters/anthropic.ts
index c646fce..6c84361 100644
--- a/packages/llm-sdk/src/adapters/anthropic.ts
+++ b/packages/llm-sdk/src/adapters/anthropic.ts
@@ -3,6 +3,7 @@ import type {
   StreamEvent,
   WebSearchConfig,
   Citation,
+  ToolDefinition,
 } from "../core/stream-events";
 import { generateMessageId } from "../core/utils";
 import type {
@@ -13,6 +14,7 @@ import type {
 import {
   formatMessagesForAnthropic,
   messageToAnthropicContent,
+  logProviderPayload,
   type AnthropicContentBlock,
 } from "./base";
 
@@ -337,6 +339,37 @@ export class AnthropicAdapter implements LLMAdapter {
     return messages;
   }
 
+  private buildNativeSearchTools(
+    tools: ToolDefinition[],
+    variant: "bm25" | "regex" = "bm25",
+  ): Array<Record<string, unknown>> {
+    const nativeSearchTool =
+      variant === "regex"
+        ? {
+            type: "tool_search_tool_regex_20251119",
+            name: "tool_search_tool_regex",
+          }
+        : {
+            type: "tool_search_tool_bm25_20251119",
+            name: "tool_search_tool_bm25",
+          };
+
+    const providerTools = tools
+      .filter((tool) => tool.available !== false)
+      .map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.inputSchema ?? {
+          type: "object" as const,
+          properties: {},
+          required: [],
+        },
+        defer_loading: tool.deferLoading === true,
+      }));
+
+    return [nativeSearchTool, ...providerTools];
+  }
+
   /**
    * Build common request options for both streaming and non-streaming
    */
@@ -358,32 +391,38 @@ export class AnthropicAdapter implements LLMAdapter {
       messages = formatted.messages as Array<Record<string, unknown>>;
     }
 
-    // Convert actions to Anthropic tool format
-    const tools: Array<Record<string, unknown>> =
-      request.actions?.map((action) => ({
-        name: action.name,
-        description: action.description,
-        input_schema: {
-          type: "object" as const,
-          properties: action.parameters
-            ? Object.fromEntries(
-                Object.entries(action.parameters).map(([key, param]) => [
-                  key,
-                  {
-                    type: param.type,
-                    description: param.description,
-                    enum: param.enum,
-                  },
-                ]),
-              )
-            : {},
-          required: action.parameters
-            ? Object.entries(action.parameters)
-                .filter(([, param]) => param.required)
-                .map(([key]) => key)
-            : [],
-        },
-      })) || [];
+    const anthropicNativeSearch =
+      request.providerToolOptions?.anthropic?.nativeToolSearch;
+
+    const tools: Array<Record<string, unknown>> = anthropicNativeSearch?.enabled
+      ? this.buildNativeSearchTools(
+          request.toolDefinitions ?? [],
+          anthropicNativeSearch.variant,
+        )
+      : request.actions?.map((action) => ({
+          name: action.name,
+          description: action.description,
+          input_schema: {
+            type: "object" as const,
+            properties: action.parameters
+              ? Object.fromEntries(
+                  Object.entries(action.parameters).map(([key, param]) => [
+                    key,
+                    {
+                      type: param.type,
+                      description: param.description,
+                      enum: param.enum,
+                    },
+                  ]),
+                )
+              : {},
+            required: action.parameters
+              ? Object.entries(action.parameters)
+                  .filter(([, param]) => param.required)
+                  .map(([key]) => key)
+              : [],
+          },
+        })) || [];
 
     // Check for web search configuration (from request or adapter config)
     const webSearchConfig = request.webSearch ?? this.config.webSearch;
@@ -436,6 +475,31 @@ export class AnthropicAdapter implements LLMAdapter {
       tools: tools.length ? tools : undefined,
     };
 
+    const anthropicToolOptions = request.providerToolOptions?.anthropic;
+    if (tools.length > 0 && anthropicToolOptions) {
+      if (
+        anthropicToolOptions.toolChoice ||
+        anthropicToolOptions.disableParallelToolUse !== undefined
+      ) {
+        const toolChoice: Record<string, unknown> =
+          typeof anthropicToolOptions.toolChoice === "object"
+            ? {
+                type: "tool",
+                name: anthropicToolOptions.toolChoice.name,
+              }
+            : anthropicToolOptions.toolChoice
+              ? { type: anthropicToolOptions.toolChoice }
+              : { type: "auto" };
+
+        if (anthropicToolOptions.disableParallelToolUse !== undefined) {
+          toolChoice.disable_parallel_tool_use =
+            anthropicToolOptions.disableParallelToolUse;
+        }
+
+        options.tool_choice = toolChoice;
+      }
+    }
+
     // Add server tool configuration for web search
     if (serverToolConfiguration) {
       options.server_tool_configuration = serverToolConfiguration;
@@ -466,7 +530,19 @@ export class AnthropicAdapter implements LLMAdapter {
     } as Record<string, unknown> & { stream: false };
 
     try {
+      logProviderPayload(
+        "anthropic",
+        "request payload",
+        nonStreamingOptions,
+        request.debug,
+      );
       const response = await client.messages.create(nonStreamingOptions);
+      logProviderPayload(
+        "anthropic",
+        "response payload",
+        response,
+        request.debug,
+      );
 
       // Parse response
       let content = "";
@@ -512,6 +588,12 @@ export class AnthropicAdapter implements LLMAdapter {
     yield { type: "message:start", id: messageId };
 
     try {
+      logProviderPayload(
+        "anthropic",
+        "request payload",
+        options,
+        request.debug,
+      );
       const stream = await client.messages.stream(options);
 
       let currentToolUse: {
@@ -536,6 +618,7 @@ export class AnthropicAdapter implements LLMAdapter {
         | undefined;
 
       for await (const event of stream) {
+        logProviderPayload("anthropic", "stream event", event, request.debug);
         // Check for abort
         if (request.signal?.aborted) {
           break;
diff --git a/packages/llm-sdk/src/adapters/azure.ts b/packages/llm-sdk/src/adapters/azure.ts
index 4de7071..ea7f1db 100644
--- a/packages/llm-sdk/src/adapters/azure.ts
+++ b/packages/llm-sdk/src/adapters/azure.ts
@@ -15,7 +15,11 @@ import type {
   ChatCompletionRequest,
   CompletionResult,
 } from "./base";
-import { formatMessagesForOpenAI, formatTools } from "./base";
+import {
+  formatMessagesForOpenAI,
+  formatTools,
+  logProviderPayload,
+} from "./base";
 
 // ============================================
 // Types
@@ -177,7 +181,7 @@ export class AzureAdapter implements LLMAdapter {
     yield { type: "message:start", id: messageId };
 
     try {
-      const stream = await client.chat.completions.create({
+      const payload = {
         // Azure uses deployment name, not model name
         model: this.config.deploymentName,
         messages,
@@ -185,7 +189,9 @@ export class AzureAdapter implements LLMAdapter {
         temperature: request.config?.temperature ?? this.config.temperature,
         max_tokens: request.config?.maxTokens ?? this.config.maxTokens,
         stream: true,
-      });
+      };
+      logProviderPayload("azure", "request payload", payload, request.debug);
+      const stream = await client.chat.completions.create(payload);
 
       let currentToolCall: {
         id: string;
@@ -194,6 +200,7 @@ export class AzureAdapter implements LLMAdapter {
       } | null = null;
 
       for await (const chunk of stream) {
+        logProviderPayload("azure", "stream chunk", chunk, request.debug);
         // Check for abort
         if (request.signal?.aborted) {
           break;
@@ -292,13 +299,16 @@ export class AzureAdapter implements LLMAdapter {
       ? formatTools(request.actions)
       : undefined;
 
-    const response = await client.chat.completions.create({
+    const payload = {
       model: this.config.deploymentName,
       messages,
       tools,
       temperature: request.config?.temperature ?? this.config.temperature,
       max_tokens: request.config?.maxTokens ?? this.config.maxTokens,
-    });
+    };
+    logProviderPayload("azure", "request payload", payload, request.debug);
+    const response = await client.chat.completions.create(payload);
+    logProviderPayload("azure", "response payload", response, request.debug);
 
     const choice = response.choices[0];
     const message = choice?.message;
diff --git a/packages/llm-sdk/src/adapters/base.ts b/packages/llm-sdk/src/adapters/base.ts
index 11d1863..e788b67 100644
--- a/packages/llm-sdk/src/adapters/base.ts
+++ b/packages/llm-sdk/src/adapters/base.ts
@@ -4,7 +4,9 @@ import type {
   ActionDefinition,
   StreamEvent,
   LLMConfig,
+  ToolDefinition,
   WebSearchConfig,
+  ProviderToolRuntimeOptions,
 } from "../core/stream-events";
 import type { TokenUsage } from "../core/types";
 
@@ -31,6 +33,8 @@ export interface ChatCompletionRequest {
   rawMessages?: Array<Record<string, unknown>>;
   /** Available actions/tools */
   actions?: ActionDefinition[];
+  /** Full tool definitions for provider-native tool search / deferred loading paths. */
+  toolDefinitions?: ToolDefinition[];
   /** System prompt */
   systemPrompt?: string;
   /** LLM configuration overrides */
@@ -42,6 +46,10 @@ export interface ChatCompletionRequest {
    * When true or configured, the provider's native search is enabled.
    */
   webSearch?: boolean | WebSearchConfig;
+  /** Optional provider-specific tool policy hints derived from runtime selection. */
+  providerToolOptions?: ProviderToolRuntimeOptions;
+  /** Enable adapter-level provider payload logging. */
+  debug?: boolean;
 }
 
 /**
@@ -86,6 +94,55 @@ export interface LLMAdapter {
  */
 export type AdapterFactory = (config: LLMConfig) => LLMAdapter;
 
+function stringifyForDebug(value: unknown): string {
+  return JSON.stringify(
+    value,
+    (_key, currentValue) => {
+      if (typeof currentValue === "bigint") {
+        return currentValue.toString();
+      }
+      if (currentValue instanceof Error) {
+        return {
+          name: currentValue.name,
+          message: currentValue.message,
+          stack: currentValue.stack,
+        };
+      }
+      return currentValue;
+    },
+    2,
+  );
+}
+
+export function logProviderPayload(
+  provider: string,
+  label: string,
+  payload: unknown,
+  enabled?: boolean,
+): void {
+  if (!enabled) {
+    return;
+  }
+
+  // Stream chunks/events are too noisy for regular debug output and can flood
+  // terminal context. Keep request/response payload logging, but suppress the
+  // per-event stream logs unless we add a separate verbose flag later.
+  if (label.toLowerCase().includes("stream ")) {
+    return;
+  }
+
+  try {
+    console.log(
+      `[llm-sdk:${provider}] ${label}\n${stringifyForDebug(payload)}`,
+    );
+  } catch (error) {
+    console.log(
+      `[llm-sdk:${provider}] ${label} (failed to stringify payload)`,
+      error,
+    );
+  }
+}
+
 /**
  * Convert messages to provider format (simple text only)
  */
@@ -162,11 +219,66 @@ function parameterToJsonSchema(param: {
         ),
       ]),
     );
+    schema.additionalProperties = false;
   }
 
   return schema;
 }
 
+export function normalizeObjectJsonSchema(
+  schema: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!schema || typeof schema !== "object") {
+    return {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    };
+  }
+
+  const normalized: Record<string, unknown> = { ...schema };
+  const type = normalized.type;
+
+  if (type === "object") {
+    const properties =
+      normalized.properties &&
+      typeof normalized.properties === "object" &&
+      !Array.isArray(normalized.properties)
+        ? (normalized.properties as Record<string, unknown>)
+        : {};
+
+    normalized.properties = Object.fromEntries(
+      Object.entries(properties).map(([key, value]) => [
+        key,
+        normalizeObjectJsonSchema(value as Record<string, unknown>),
+      ]),
+    );
+
+    const propertyKeys = Object.keys(properties);
+    const required = Array.isArray(normalized.required)
+      ? normalized.required.filter(
+          (value): value is string => typeof value === "string",
+        )
+      : [];
+    normalized.required = Array.from(new Set([...required, ...propertyKeys]));
+
+    if (normalized.additionalProperties === undefined) {
+      normalized.additionalProperties = false;
+    }
+  } else if (
+    type === "array" &&
+    normalized.items &&
+    typeof normalized.items === "object"
+  ) {
+    normalized.items = normalizeObjectJsonSchema(
+      normalized.items as Record<string, unknown>,
+    );
+  }
+
+  return normalized;
+}
+
 /**
  * Convert actions to OpenAI tool format
  */
@@ -198,6 +310,7 @@ export function formatTools(actions: ActionDefinition[]): Array<{
               .filter(([, param]) => param.required)
               .map(([key]) => key)
           : [],
+        additionalProperties: false,
       },
     },
   }));
diff --git a/packages/llm-sdk/src/adapters/google.ts b/packages/llm-sdk/src/adapters/google.ts
index 34c9d34..520d43e 100644
--- a/packages/llm-sdk/src/adapters/google.ts
+++ b/packages/llm-sdk/src/adapters/google.ts
@@ -18,7 +18,7 @@ import type {
   ChatCompletionRequest,
   CompletionResult,
 } from "./base";
-import { formatTools } from "./base";
+import { formatTools, logProviderPayload } from "./base";
 
 // ============================================
 // Types
@@ -373,6 +373,24 @@ export class GoogleAdapter implements LLMAdapter {
     yield { type: "message:start", id: messageId };
 
     try {
+      logProviderPayload(
+        "google",
+        "request payload",
+        {
+          model: modelId,
+          history: mergedContents.slice(0, -1),
+          systemInstruction: systemInstruction
+            ? { parts: [{ text: systemInstruction }] }
+            : undefined,
+          tools: toolsArray.length > 0 ? toolsArray : undefined,
+          generationConfig: {
+            temperature: request.config?.temperature ?? this.config.temperature,
+            maxOutputTokens: request.config?.maxTokens ?? this.config.maxTokens,
+          },
+          messageParts: mergedContents[mergedContents.length - 1]?.parts,
+        },
+        request.debug,
+      );
       // Start chat session with system instruction
       const chat = model.startChat({
         history: mergedContents.slice(0, -1), // All but the last message
@@ -402,6 +420,7 @@ export class GoogleAdapter implements LLMAdapter {
       const collectedCitations: Citation[] = [];
 
       for await (const chunk of result.stream) {
+        logProviderPayload("google", "stream chunk", chunk, request.debug);
         // Check for abort
         if (request.signal?.aborted) {
           break;
@@ -501,6 +520,12 @@ export class GoogleAdapter implements LLMAdapter {
 
       try {
         const response = await result.response;
+        logProviderPayload(
+          "google",
+          "response payload",
+          response,
+          request.debug,
+        );
         if (response.usageMetadata) {
           usage = {
             prompt_tokens: response.usageMetadata.promptTokenCount || 0,
@@ -611,6 +636,20 @@ export class GoogleAdapter implements LLMAdapter {
 
     const tools = formatToolsForGemini(request.actions);
 
+    const payload = {
+      model: modelId,
+      history: mergedContents.slice(0, -1),
+      systemInstruction: systemInstruction
+        ? { parts: [{ text: systemInstruction }] }
+        : undefined,
+      tools: tools ? [tools] : undefined,
+      generationConfig: {
+        temperature: request.config?.temperature ?? this.config.temperature,
+        maxOutputTokens: request.config?.maxTokens ?? this.config.maxTokens,
+      },
+      messageParts: mergedContents[mergedContents.length - 1]?.parts,
+    };
+    logProviderPayload("google", "request payload", payload, request.debug);
     const chat = model.startChat({
       history: mergedContents.slice(0, -1),
       systemInstruction: systemInstruction
@@ -626,6 +665,7 @@ export class GoogleAdapter implements LLMAdapter {
     const lastMessage = mergedContents[mergedContents.length - 1];
     const result = await chat.sendMessage(lastMessage.parts);
     const response = result.response;
+    logProviderPayload("google", "response payload", response, request.debug);
 
     // Extract content and tool calls
     let textContent = "";
diff --git a/packages/llm-sdk/src/adapters/ollama.ts b/packages/llm-sdk/src/adapters/ollama.ts
index 9d56f26..a06dad3 100644
--- a/packages/llm-sdk/src/adapters/ollama.ts
+++ b/packages/llm-sdk/src/adapters/ollama.ts
@@ -5,7 +5,7 @@ import type {
 } from "../core/stream-events";
 import { generateMessageId, generateToolCallId } from "../core/utils";
 import type { LLMAdapter, ChatCompletionRequest } from "./base";
-import { formatMessages, formatTools } from "./base";
+import { formatMessages, formatTools, logProviderPayload } from "./base";
 import type { OllamaModelOptions } from "../providers/types";
 
 /**
@@ -288,18 +288,20 @@ export class OllamaAdapter implements LLMAdapter {
         Object.assign(ollamaOptions, this.config.options);
       }
 
+      const payload = {
+        model: request.config?.model || this.model,
+        messages,
+        tools,
+        stream: true,
+        options: ollamaOptions,
+      };
+      logProviderPayload("ollama", "request payload", payload, request.debug);
       const response = await fetch(`${this.baseUrl}/api/chat`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
         },
-        body: JSON.stringify({
-          model: request.config?.model || this.model,
-          messages,
-          tools,
-          stream: true,
-          options: ollamaOptions,
-        }),
+        body: JSON.stringify(payload),
         signal: request.signal,
       });
 
@@ -336,6 +338,7 @@ export class OllamaAdapter implements LLMAdapter {
 
           try {
             const chunk = JSON.parse(line);
+            logProviderPayload("ollama", "stream chunk", chunk, request.debug);
 
             // Handle content
             if (chunk.message?.content) {
diff --git a/packages/llm-sdk/src/adapters/openai.ts b/packages/llm-sdk/src/adapters/openai.ts
index b910065..36d96fd 100644
--- a/packages/llm-sdk/src/adapters/openai.ts
+++ b/packages/llm-sdk/src/adapters/openai.ts
@@ -3,10 +3,20 @@ import type {
   StreamEvent,
   WebSearchConfig,
   Citation,
+  ToolDefinition,
 } from "../core/stream-events";
 import { generateMessageId, generateToolCallId } from "../core/utils";
-import type { LLMAdapter, ChatCompletionRequest } from "./base";
-import { formatMessagesForOpenAI, formatTools } from "./base";
+import type {
+  LLMAdapter,
+  ChatCompletionRequest,
+  CompletionResult,
+} from "./base";
+import {
+  formatMessagesForOpenAI,
+  formatTools,
+  logProviderPayload,
+  normalizeObjectJsonSchema,
+} from "./base";
 
 /**
  * OpenAI adapter configuration
@@ -53,7 +63,230 @@ export class OpenAIAdapter implements LLMAdapter {
     return this.client;
   }
 
+  private shouldUseResponsesApi(request: ChatCompletionRequest): boolean {
+    return (
+      request.providerToolOptions?.openai?.nativeToolSearch?.enabled === true &&
+      request.providerToolOptions.openai.nativeToolSearch.useResponsesApi !==
+        false &&
+      Array.isArray(request.toolDefinitions) &&
+      request.toolDefinitions.length > 0
+    );
+  }
+
+  private buildResponsesInput(
+    request: ChatCompletionRequest,
+  ): Array<Record<string, unknown>> {
+    const sourceMessages =
+      request.rawMessages && request.rawMessages.length > 0
+        ? request.rawMessages
+        : (formatMessagesForOpenAI(request.messages, undefined) as Array<
+            Record<string, unknown>
+          >);
+    const input: Array<Record<string, unknown>> = [];
+
+    for (const message of sourceMessages) {
+      if (message.role === "system") {
+        continue;
+      }
+
+      if (message.role === "assistant") {
+        const content =
+          typeof message.content === "string"
+            ? message.content
+            : Array.isArray(message.content)
+              ? message.content
+              : message.content
+                ? JSON.stringify(message.content)
+                : "";
+
+        if (content) {
+          input.push({
+            type: "message",
+            role: "assistant",
+            content,
+          });
+        }
+
+        const toolCalls = Array.isArray(message.tool_calls)
+          ? (message.tool_calls as Array<{
+              id: string;
+              function?: { name?: string; arguments?: string };
+            }>)
+          : [];
+
+        for (const toolCall of toolCalls) {
+          input.push({
+            type: "function_call",
+            call_id: toolCall.id,
+            name: toolCall.function?.name,
+            arguments: toolCall.function?.arguments ?? "{}",
+          });
+        }
+        continue;
+      }
+
+      if (message.role === "tool") {
+        input.push({
+          type: "function_call_output",
+          call_id: message.tool_call_id,
+          output:
+            typeof message.content === "string"
+              ? message.content
+              : JSON.stringify(message.content ?? null),
+        });
+        continue;
+      }
+
+      input.push({
+        type: "message",
+        role: message.role === "developer" ? "developer" : "user",
+        content:
+          typeof message.content === "string"
+            ? message.content
+            : Array.isArray(message.content)
+              ? message.content
+              : JSON.stringify(message.content ?? ""),
+      });
+    }
+
+    return input;
+  }
+
+  private buildResponsesTools(
+    tools: ToolDefinition[],
+  ): Array<Record<string, unknown>> {
+    const nativeTools = tools
+      .filter((tool) => tool.available !== false)
+      .map((tool) => ({
+        type: "function",
+        name: tool.name,
+        description: tool.description,
+        parameters: normalizeObjectJsonSchema(
+          (tool.inputSchema as Record<string, unknown> | undefined) ?? {
+            type: "object",
+            properties: {},
+            required: [],
+          },
+        ),
+        strict: true,
+        defer_loading: tool.deferLoading === true,
+      }));
+
+    return [{ type: "tool_search" }, ...nativeTools];
+  }
+
+  private parseResponsesResult(response: any): CompletionResult {
+    const content =
+      typeof response?.output_text === "string" ? response.output_text : "";
+    const toolCalls = Array.isArray(response?.output)
+      ? response.output
+          .filter((item: any) => item?.type === "function_call")
+          .map((item: any) => ({
+            id: item.call_id ?? item.id ?? generateToolCallId(),
+            name: item.name,
+            args: (() => {
+              try {
+                return JSON.parse(item.arguments ?? "{}");
+              } catch {
+                return {};
+              }
+            })(),
+          }))
+      : [];
+
+    return {
+      content,
+      toolCalls,
+      usage: response?.usage
+        ? {
+            promptTokens: response.usage.input_tokens ?? 0,
+            completionTokens: response.usage.output_tokens ?? 0,
+            totalTokens:
+              response.usage.total_tokens ??
+              (response.usage.input_tokens ?? 0) +
+                (response.usage.output_tokens ?? 0),
+          }
+        : undefined,
+      rawResponse: response as Record<string, unknown>,
+    };
+  }
+
+  private async completeWithResponses(
+    request: ChatCompletionRequest,
+  ): Promise<CompletionResult> {
+    const client = await this.getClient();
+    const openaiToolOptions = request.providerToolOptions?.openai;
+    const payload = {
+      model: request.config?.model || this.model,
+      instructions: request.systemPrompt,
+      input: this.buildResponsesInput(request),
+      tools: this.buildResponsesTools(request.toolDefinitions ?? []),
+      tool_choice:
+        openaiToolOptions?.toolChoice === "required"
+          ? "required"
+          : openaiToolOptions?.toolChoice === "auto"
+            ? "auto"
+            : undefined,
+      parallel_tool_calls: openaiToolOptions?.parallelToolCalls,
+      temperature: request.config?.temperature ?? this.config.temperature,
+      max_output_tokens: request.config?.maxTokens ?? this.config.maxTokens,
+      stream: false,
+    };
+
+    logProviderPayload("openai", "request payload", payload, request.debug);
+    const response = await client.responses.create(payload);
+    logProviderPayload("openai", "response payload", response, request.debug);
+
+    return this.parseResponsesResult(response);
+  }
+
   async *stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent> {
+    if (this.shouldUseResponsesApi(request)) {
+      const messageId = generateMessageId();
+      yield { type: "message:start", id: messageId };
+
+      try {
+        const result = await this.completeWithResponses(request);
+
+        if (result.content) {
+          yield { type: "message:delta", content: result.content };
+        }
+
+        for (const toolCall of result.toolCalls) {
+          yield {
+            type: "action:start",
+            id: toolCall.id,
+            name: toolCall.name,
+          };
+          yield {
+            type: "action:args",
+            id: toolCall.id,
+            args: JSON.stringify(toolCall.args),
+          };
+        }
+
+        yield { type: "message:end" };
+        yield {
+          type: "done",
+          usage: result.usage
+            ? {
+                prompt_tokens: result.usage.promptTokens,
+                completion_tokens: result.usage.completionTokens,
+                total_tokens: result.usage.totalTokens,
+              }
+            : undefined,
+        };
+        return;
+      } catch (error) {
+        yield {
+          type: "error",
+          message: error instanceof Error ? error.message : "Unknown error",
+          code: "OPENAI_RESPONSES_ERROR",
+        };
+        return;
+      }
+    }
+
     const client = await this.getClient();
 
     // Use raw messages if provided (for agent loop with tool calls), otherwise format from Message[]
@@ -163,15 +396,31 @@ export class OpenAIAdapter implements LLMAdapter {
     yield { type: "message:start", id: messageId };
 
     try {
-      const stream = await client.chat.completions.create({
+      const openaiToolOptions = request.providerToolOptions?.openai;
+      const toolChoice =
+        openaiToolOptions?.toolChoice &&
+        typeof openaiToolOptions.toolChoice === "object"
+          ? {
+              type: "function" as const,
+              function: {
+                name: openaiToolOptions.toolChoice.name,
+              },
+            }
+          : openaiToolOptions?.toolChoice;
+      const payload = {
         model: request.config?.model || this.model,
         messages,
         tools: tools.length > 0 ? tools : undefined,
+        tool_choice: tools.length > 0 ? toolChoice : undefined,
+        parallel_tool_calls:
+          tools.length > 0 ? openaiToolOptions?.parallelToolCalls : undefined,
         temperature: request.config?.temperature ?? this.config.temperature,
         max_tokens: request.config?.maxTokens ?? this.config.maxTokens,
         stream: true,
         stream_options: { include_usage: true },
-      });
+      };
+      logProviderPayload("openai", "request payload", payload, request.debug);
+      const stream = await client.chat.completions.create(payload);
 
       let currentToolCall: {
         id: string;
@@ -192,6 +441,7 @@ export class OpenAIAdapter implements LLMAdapter {
         | undefined;
 
       for await (const chunk of stream) {
+        logProviderPayload("openai", "stream chunk", chunk, request.debug);
         // Check for abort
         if (request.signal?.aborted) {
           break;
@@ -308,6 +558,91 @@ export class OpenAIAdapter implements LLMAdapter {
       };
     }
   }
+
+  async complete(request: ChatCompletionRequest): Promise<CompletionResult> {
+    if (this.shouldUseResponsesApi(request)) {
+      return this.completeWithResponses(request);
+    }
+
+    const client = await this.getClient();
+
+    let messages: Array<Record<string, unknown>>;
+    if (request.rawMessages && request.rawMessages.length > 0) {
+      messages = request.rawMessages;
+      if (
+        request.systemPrompt &&
+        !messages.some((message) => message.role === "system")
+      ) {
+        messages = [
+          { role: "system", content: request.systemPrompt },
+          ...messages,
+        ];
+      }
+    } else {
+      messages = formatMessagesForOpenAI(
+        request.messages,
+        request.systemPrompt,
+      ) as Array<Record<string, unknown>>;
+    }
+
+    const tools: Array<Record<string, unknown>> = request.actions?.length
+      ? formatTools(request.actions)
+      : [];
+
+    const openaiToolOptions = request.providerToolOptions?.openai;
+    const toolChoice =
+      openaiToolOptions?.toolChoice &&
+      typeof openaiToolOptions.toolChoice === "object"
+        ? {
+            type: "function" as const,
+            function: {
+              name: openaiToolOptions.toolChoice.name,
+            },
+          }
+        : openaiToolOptions?.toolChoice;
+
+    const payload = {
+      model: request.config?.model || this.model,
+      messages,
+      tools: tools.length > 0 ? tools : undefined,
+      tool_choice: tools.length > 0 ? toolChoice : undefined,
+      parallel_tool_calls:
+        tools.length > 0 ? openaiToolOptions?.parallelToolCalls : undefined,
+      temperature: request.config?.temperature ?? this.config.temperature,
+      max_tokens: request.config?.maxTokens ?? this.config.maxTokens,
+      stream: false,
+    };
+
+    logProviderPayload("openai", "request payload", payload, request.debug);
+    const response = await client.chat.completions.create(payload);
+    logProviderPayload("openai", "response payload", response, request.debug);
+
+    const choice = response.choices?.[0];
+    const message = choice?.message;
+    return {
+      content: message?.content ?? "",
+      toolCalls:
+        message?.tool_calls?.map((toolCall: any) => ({
+          id: toolCall.id ?? generateToolCallId(),
+          name: toolCall.function?.name ?? "",
+          args: (() => {
+            try {
+              return JSON.parse(toolCall.function?.arguments ?? "{}");
+            } catch {
+              return {};
+            }
+          })(),
+        })) ?? [],
+      usage: response.usage
+        ? {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens,
+          }
+        : undefined,
+      rawResponse: response as Record<string, unknown>,
+    };
+  }
 }
 
 /**
diff --git a/packages/llm-sdk/src/adapters/xai.ts b/packages/llm-sdk/src/adapters/xai.ts
index 0e6adc2..e176fbe 100644
--- a/packages/llm-sdk/src/adapters/xai.ts
+++ b/packages/llm-sdk/src/adapters/xai.ts
@@ -15,7 +15,11 @@ import type {
   ChatCompletionRequest,
   CompletionResult,
 } from "./base";
-import { formatMessagesForOpenAI, formatTools } from "./base";
+import {
+  formatMessagesForOpenAI,
+  formatTools,
+  logProviderPayload,
+} from "./base";
 
 // ============================================
 // Types
@@ -147,14 +151,16 @@ export class XAIAdapter implements LLMAdapter {
     yield { type: "message:start", id: messageId };
 
     try {
-      const stream = await client.chat.completions.create({
+      const payload = {
         model: request.config?.model || this.model,
         messages,
         tools,
         temperature: request.config?.temperature ?? this.config.temperature,
         max_tokens: request.config?.maxTokens ?? this.config.maxTokens,
         stream: true,
-      });
+      };
+      logProviderPayload("xai", "request payload", payload, request.debug);
+      const stream = await client.chat.completions.create(payload);
 
       let currentToolCall: {
         id: string;
@@ -163,6 +169,7 @@ export class XAIAdapter implements LLMAdapter {
       } | null = null;
 
       for await (const chunk of stream) {
+        logProviderPayload("xai", "stream chunk", chunk, request.debug);
         // Check for abort
         if (request.signal?.aborted) {
           break;
@@ -261,13 +268,16 @@ export class XAIAdapter implements LLMAdapter {
       ? formatTools(request.actions)
       : undefined;
 
-    const response = await client.chat.completions.create({
+    const payload = {
       model: request.config?.model || this.model,
       messages,
       tools,
       temperature: request.config?.temperature ?? this.config.temperature,
       max_tokens: request.config?.maxTokens ?? this.config.maxTokens,
-    });
+    };
+    logProviderPayload("xai", "request payload", payload, request.debug);
+    const response = await client.chat.completions.create(payload);
+    logProviderPayload("xai", "response payload", response, request.debug);
 
     const choice = response.choices[0];
     const message = choice?.message;
diff --git a/packages/llm-sdk/src/core/stream-events.ts b/packages/llm-sdk/src/core/stream-events.ts
index 259eb94..9611dad 100644
--- a/packages/llm-sdk/src/core/stream-events.ts
+++ b/packages/llm-sdk/src/core/stream-events.ts
@@ -427,6 +427,10 @@ export interface ToolDefinition<TParams = Record<string, unknown>> {
   name: string;
   description: string;
   location: ToolLocation;
+  /** Optional logical category for tool search and selective loading. */
+  category?: string;
+  /** Optional group label for related tools. */
+  group?: string;
   title?: string | ((args: TParams) => string);
   inputSchema?: ToolInputSchema;
   handler?: (
@@ -450,6 +454,117 @@ export interface ToolDefinition<TParams = Record<string, unknown>> {
   aiContext?:
     | string
     | ((result: ToolResponse, args: Record<string, unknown>) => string);
+  /** Hint that this tool should be loaded lazily when dynamic selection is active. */
+  deferLoading?: boolean;
+  /** Named profiles this tool belongs to (for example "coding" or "search"). */
+  profiles?: string[];
+  /** Extra keywords used by lightweight tool search/ranking. */
+  searchKeywords?: string[];
+}
+
+export interface ToolProfile {
+  include?: string[];
+  exclude?: string[];
+}
+
+export interface ToolDynamicSelectionConfig {
+  enabled?: boolean;
+  maxTools?: number;
+}
+
+export interface ToolSearchConfig {
+  enabled?: boolean;
+  /**
+   * Search execution mode.
+   * - auto: use native provider search when supported, otherwise fall back to manual search_tools
+   * - native: require provider-native search when supported, otherwise fall back to manual search_tools
+   * - manual: always use the SDK-managed search_tools fallback
+   */
+  mode?: "auto" | "native" | "manual";
+  metaToolName?: string;
+  maxResults?: number;
+  minScore?: number;
+  exposeWhenToolCountExceeds?: number;
+  /** Anthropic native tool search variant. Defaults to bm25. */
+  anthropicVariant?: "bm25" | "regex";
+  /**
+   * When true, tools marked with deferLoading stay hidden from the initial
+   * selected tool list and are only introduced after search_tools loads them.
+   */
+  strictDeferredLoading?: boolean;
+}
+
+export interface OpenAIToolSelectionHints {
+  /**
+   * "single" forces the selected tool when exactly one tool remains after selection.
+   * Otherwise the adapter falls back to automatic tool choice.
+   */
+  toolChoice?: "auto" | "required" | "single";
+  /** Set false to disable parallel tool calls on OpenAI-compatible providers. */
+  parallelToolCalls?: boolean;
+}
+
+export interface AnthropicToolSelectionHints {
+  /**
+   * "single" forces the selected tool when exactly one tool remains after selection.
+   * Otherwise the adapter falls back to Anthropic's automatic tool choice.
+   */
+  toolChoice?: "auto" | "any" | "single";
+  /** Disable parallel tool use when supported by the Anthropic API. */
+  disableParallelToolUse?: boolean;
+}
+
+export interface ToolNativeProviderHints {
+  openai?: OpenAIToolSelectionHints;
+  anthropic?: AnthropicToolSelectionHints;
+}
+
+export interface ToolSelectionConfig {
+  enabled?: boolean;
+  defaultProfile?: string;
+  profiles?: Record<string, ToolProfile>;
+  /** When false, active profiles exclude tools without explicit profile membership. */
+  includeUnprofiled?: boolean;
+  dynamicSelection?: ToolDynamicSelectionConfig;
+  /** Optional indexed search over deferred tools. */
+  search?: ToolSearchConfig;
+  /** Optional provider-native hints layered on top of local tool selection. */
+  nativeProviderHints?: ToolNativeProviderHints;
+}
+
+export interface OpenAIProviderToolOptions {
+  toolChoice?:
+    | "auto"
+    | "required"
+    | {
+        type: "function";
+        name: string;
+      };
+  parallelToolCalls?: boolean;
+  nativeToolSearch?: {
+    enabled: boolean;
+    useResponsesApi?: boolean;
+  };
+}
+
+export interface AnthropicProviderToolOptions {
+  toolChoice?:
+    | "auto"
+    | "any"
+    | {
+        type: "tool";
+        name: string;
+      };
+  disableParallelToolUse?: boolean;
+  nativeToolSearch?: {
+    enabled: boolean;
+    variant: "bm25" | "regex";
+  };
+}
+
+export interface ProviderToolRuntimeOptions {
+  openai?: OpenAIProviderToolOptions;
+  anthropic?: AnthropicProviderToolOptions;
 }
 
 /**
@@ -459,6 +574,7 @@ export interface AgentLoopConfig {
   maxIterations?: number;
   debug?: boolean;
   enabled?: boolean;
+  toolSelection?: ToolSelectionConfig;
 }
 
 /**
diff --git a/packages/llm-sdk/src/index.ts b/packages/llm-sdk/src/index.ts
index 99bc56d..cc22c30 100644
--- a/packages/llm-sdk/src/index.ts
+++ b/packages/llm-sdk/src/index.ts
@@ -89,10 +89,15 @@ export { DEFAULT_CAPABILITIES } from "./core/types";
 export {
   Runtime,
   createRuntime,
+  selectTools,
+  searchTools,
+  shouldExposeToolSearch,
+  buildProviderToolOptions,
   type RuntimeConfig,
   type ChatRequest,
   type ActionRequest,
   type RequestContext,
+  type ToolSearchMatch,
 } from "./server";
 
 // StreamResult (Industry Standard Pattern)
@@ -186,6 +191,16 @@ export type {
   UnifiedToolResult,
   ToolExecution,
   AgentLoopConfig,
+  ToolProfile,
+  ToolDynamicSelectionConfig,
+  ToolSearchConfig,
+  OpenAIToolSelectionHints,
+  AnthropicToolSelectionHints,
+  ToolNativeProviderHints,
+  ToolSelectionConfig,
+  OpenAIProviderToolOptions,
+  AnthropicProviderToolOptions,
+  ProviderToolRuntimeOptions,
   DoneEventMessage,
   ToolCallInfo,
   TokenUsageRaw,
diff --git a/packages/llm-sdk/src/providers/anthropic.ts b/packages/llm-sdk/src/providers/anthropic.ts
index 6aa7733..4880680 100644
--- a/packages/llm-sdk/src/providers/anthropic.ts
+++ b/packages/llm-sdk/src/providers/anthropic.ts
@@ -27,7 +27,13 @@ export function transformTools(tools: ToolDefinition[]): AnthropicTool[] {
   return tools.map((tool) => ({
     name: tool.name,
     description: tool.description,
-    input_schema: tool.inputSchema,
+    input_schema: tool.inputSchema
+      ? {
+          type: "object",
+          properties: tool.inputSchema.properties ?? {},
+          required: tool.inputSchema.required,
+        }
+      : { type: "object", properties: {} },
   }));
 }
 
diff --git a/packages/llm-sdk/src/providers/gemini.ts b/packages/llm-sdk/src/providers/gemini.ts
index 1c7b141..41c49af 100644
--- a/packages/llm-sdk/src/providers/gemini.ts
+++ b/packages/llm-sdk/src/providers/gemini.ts
@@ -31,7 +31,13 @@ export function transformTools(
       functionDeclarations: tools.map((tool) => ({
         name: tool.name,
         description: tool.description,
-        parameters: tool.inputSchema,
+        parameters: tool.inputSchema
+          ? {
+              type: "object",
+              properties: tool.inputSchema.properties ?? {},
+              required: tool.inputSchema.required,
+            }
+          : { type: "object", properties: {} },
       })),
     },
   ];
diff --git a/packages/llm-sdk/src/providers/openai.ts b/packages/llm-sdk/src/providers/openai.ts
index 8610ce6..72f8538 100644
--- a/packages/llm-sdk/src/providers/openai.ts
+++ b/packages/llm-sdk/src/providers/openai.ts
@@ -30,7 +30,13 @@ export function transformTools(tools: ToolDefinition[]): OpenAITool[] {
     function: {
       name: tool.name,
       description: tool.description,
-      parameters: tool.inputSchema,
+      parameters: tool.inputSchema
+        ? {
+            type: "object",
+            properties: tool.inputSchema.properties ?? {},
+            required: tool.inputSchema.required,
+          }
+        : { type: "object", properties: {} },
     },
   }));
 }
diff --git a/packages/llm-sdk/src/server/agent-loop.ts b/packages/llm-sdk/src/server/agent-loop.ts
index 7dbd121..0363770 100644
--- a/packages/llm-sdk/src/server/agent-loop.ts
+++ b/packages/llm-sdk/src/server/agent-loop.ts
@@ -22,6 +22,12 @@ import type {
 import type { AIProvider } from "../providers/types";
 import { generateToolCallId, generateMessageId } from "../core/utils";
 import { getFormatter } from "../providers";
+import {
+  buildProviderToolOptions,
+  searchTools,
+  selectTools,
+  shouldExposeToolSearch,
+} from "./tool-selection";
 
 // ========================================
 // Constants
@@ -50,11 +56,17 @@ export interface AgentLoopOptions {
   signal?: AbortSignal;
   /** Loop configuration */
   config?: AgentLoopConfig;
+  /** Optional active tool profile for selective loading. */
+  toolProfile?: string;
   /**
    * LLM call function
    * Should call the LLM and return the raw response
    */
-  callLLM: (messages: unknown[], tools: unknown[]) => Promise<unknown>;
+  callLLM: (
+    messages: unknown[],
+    tools: unknown[],
+    providerToolOptions?: ReturnType<typeof buildProviderToolOptions>,
+  ) => Promise<unknown>;
   /**
    * Server-side tool executor
    * Called when a server-side tool needs to be executed
@@ -103,6 +115,7 @@ export async function* runAgentLoop(
     provider,
     signal,
     config,
+    toolProfile,
     callLLM,
     executeServerTool,
     waitForClientToolResult,
@@ -111,15 +124,14 @@ export async function* runAgentLoop(
   const maxIterations = config?.maxIterations ?? DEFAULT_MAX_ITERATIONS;
   const debug = config?.debug ?? false;
   const formatter = getFormatter(provider.name);
+  const toolSearchMetaToolName =
+    config?.toolSelection?.search?.metaToolName ?? "search_tools";
 
   // Separate server and client tools
   const serverTools = tools.filter((t) => t.location === "server");
   const clientTools = tools.filter((t) => t.location === "client");
   const allTools = [...serverTools, ...clientTools];
 
-  // Transform tools to provider format
-  const providerTools = formatter.transformTools(allTools);
-
   // Build conversation
   const conversation: ConversationMessage[] = buildConversation(
     messages,
@@ -127,13 +139,15 @@ export async function* runAgentLoop(
   );
 
   let iteration = 0;
+  let loadedToolNames = new Set<string>();
 
   if (debug) {
     console.log("[AgentLoop] Starting with", {
       messageCount: messages.length,
-      toolCount: allTools.length,
+      availableToolCount: allTools.length,
       serverToolCount: serverTools.length,
       clientToolCount: clientTools.length,
+      activeProfile: toolProfile ?? config?.toolSelection?.defaultProfile,
       maxIterations,
     });
   }
@@ -159,13 +173,84 @@ export async function* runAgentLoop(
       maxIterations,
     };
 
+    const selectedTools = selectTools({
+      tools: allTools,
+      messages,
+      config: config?.toolSelection,
+      activeProfile: toolProfile,
+      forceIncludeNames: [...loadedToolNames],
+    });
+    const toolSearchTool = shouldExposeToolSearch({
+      tools: allTools,
+      selectedTools,
+      config: config?.toolSelection,
+    })
+      ? ({
+          name: toolSearchMetaToolName,
+          description:
+            "Search available deferred tools and load the most relevant ones for the next step when the required tool is not currently exposed.",
+          location: "server",
+          hidden: true,
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Describe the tool capability you need to find.",
+              },
+              limit: {
+                type: "number",
+                description: "Maximum number of matching tools to load.",
+              },
+            },
+            required: ["query"],
+          },
+          handler: async (params: Record<string, unknown>) => {
+            const query = typeof params.query === "string" ? params.query : "";
+            const limit =
+              typeof params.limit === "number" ? params.limit : undefined;
+            const results = searchTools({
+              tools: allTools,
+              query,
+              config: config?.toolSelection,
+              activeProfile: toolProfile,
+              limit,
+              excludeNames: selectedTools.map((tool) => tool.name),
+            });
+            return {
+              success: true,
+              query,
+              loadedTools: results.map((result) => result.name),
+              results,
+            };
+          },
+        } satisfies ToolDefinition)
+      : null;
+    const effectiveSelectedTools = toolSearchTool
+      ? [...selectedTools, toolSearchTool]
+      : selectedTools;
+    const providerToolOptions = buildProviderToolOptions({
+      providerName: provider.name,
+      selectedTools: effectiveSelectedTools,
+      config: config?.toolSelection,
+      metaToolName: toolSearchMetaToolName,
+    });
+    const providerTools = formatter.transformTools(effectiveSelectedTools);
+
     if (debug) {
-      console.log(`[AgentLoop] Iteration ${iteration}/${maxIterations}`);
+      console.log(`[AgentLoop] Iteration ${iteration}/${maxIterations}`, {
+        selectedToolCount: effectiveSelectedTools.length,
+        loadedDeferredTools: [...loadedToolNames],
+      });
     }
 
     try {
       // Call LLM
-      const response = await callLLM(conversation, providerTools);
+      const response = await callLLM(
+        conversation,
+        providerTools,
+        providerToolOptions,
+      );
 
       // Parse tool calls and text from response
       const toolCalls = formatter.parseToolCalls(response);
@@ -191,7 +276,7 @@ export async function* runAgentLoop(
         // Execute tools
         const results = await executeToolCalls(
           toolCalls,
-          tools,
+          effectiveSelectedTools,
           executeServerTool,
           waitForClientToolResult,
           function* (event: StreamEvent) {
@@ -213,6 +298,27 @@ export async function* runAgentLoop(
           }
         }
 
+        for (const result of results) {
+          const toolCall = toolCalls.find((tc) => tc.id === result.toolCallId);
+          if (!toolCall || toolCall.name !== toolSearchMetaToolName) {
+            continue;
+          }
+          try {
+            const parsed = JSON.parse(result.content) as {
+              loadedTools?: unknown;
+            };
+            if (Array.isArray(parsed.loadedTools)) {
+              for (const toolName of parsed.loadedTools) {
+                if (typeof toolName === "string" && toolName) {
+                  loadedToolNames.add(toolName);
+                }
+              }
+            }
+          } catch {
+            // Ignore malformed tool search result payloads.
+          }
+        }
+
         // Add assistant message with tool calls to conversation
         const assistantMessage = formatter.buildAssistantToolMessage(
           toolCalls,
diff --git a/packages/llm-sdk/src/server/index.ts b/packages/llm-sdk/src/server/index.ts
index 3729d9b..c7258fc 100644
--- a/packages/llm-sdk/src/server/index.ts
+++ b/packages/llm-sdk/src/server/index.ts
@@ -52,3 +52,12 @@ export {
   DEFAULT_MAX_ITERATIONS,
   type AgentLoopOptions,
 } from "./agent-loop";
+
+// Tool selection
+export {
+  selectTools,
+  searchTools,
+  shouldExposeToolSearch,
+  buildProviderToolOptions,
+} from "./tool-selection";
+export type { ToolSearchMatch } from "./tool-selection";
diff --git a/packages/llm-sdk/src/server/runtime.ts b/packages/llm-sdk/src/server/runtime.ts
index ada24d3..23c0c52 100644
--- a/packages/llm-sdk/src/server/runtime.ts
+++ b/packages/llm-sdk/src/server/runtime.ts
@@ -26,6 +26,36 @@ import type {
 import { createSSEResponse } from "./streaming";
 import { StreamResult, type CollectedResult } from "./stream-result";
 import { GenerateResult } from "./generate-result";
+import {
+  buildProviderToolOptions,
+  filterToolsByProfile,
+  resolveNativeToolSearch,
+  searchTools,
+  selectTools,
+  shouldExposeToolSearch,
+} from "./tool-selection";
+
+type ToolSearchState = {
+  loadedToolNames: string[];
+};
+
+type NativeToolSearchState = ReturnType<typeof resolveNativeToolSearch>;
+
+type ToolSearchResult = {
+  success: true;
+  query: string;
+  loadedTools: string[];
+  results: Array<{
+    name: string;
+    description: string;
+    location?: ToolDefinition["location"];
+    category?: string;
+    group?: string;
+    profiles?: string[];
+    searchKeywords?: string[];
+    score: number;
+  }>;
+};
 
 // ============================================
 // AI Response Control
@@ -244,6 +274,7 @@ export class Runtime {
       config: request.config,
       signal,
       webSearch: this.getWebSearchConfig(),
+      debug: this.config.debug,
     };
 
     // Stream response from adapter
@@ -311,7 +342,15 @@ export class Runtime {
       const body = (await request.json()) as ChatRequest;
 
       if (this.config.debug) {
-        console.log("[Copilot SDK] Request:", JSON.stringify(body, null, 2));
+        console.log("[Copilot SDK] Request:", {
+          messageCount: body.messages?.length ?? 0,
+          toolCount: body.tools?.length ?? 0,
+          toolCatalogCount: body.toolCatalog?.length ?? 0,
+          hasSystemPrompt: Boolean(body.systemPrompt),
+          threadId: body.threadId,
+          streaming: body.streaming !== false,
+          toolProfile: body.toolProfile,
+        });
       }
 
       // Create abort controller from request signal
@@ -644,6 +683,195 @@ export class Runtime {
     return undefined;
   }
 
+  private collectToolsForRequest(request: ChatRequest): ToolDefinition[] {
+    const allTools: ToolDefinition[] = [...this.tools.values()];
+
+    const clientTools =
+      this.config.agentLoop?.toolSelection?.enabled &&
+      request.toolCatalog?.length
+        ? request.toolCatalog
+        : request.tools;
+
+    if (clientTools) {
+      for (const tool of clientTools) {
+        allTools.push({
+          name: tool.name,
+          description: tool.description,
+          location: "client",
+          category: tool.category,
+          group: tool.group,
+          deferLoading: tool.deferLoading,
+          profiles: tool.profiles,
+          searchKeywords: tool.searchKeywords,
+          inputSchema: tool.inputSchema as ToolDefinition["inputSchema"],
+        });
+      }
+    }
+
+    return allTools;
+  }
+
+  private selectToolsForRequest(
+    request: ChatRequest,
+    allTools: ToolDefinition[],
+    toolSearchState?: ToolSearchState,
+  ): ToolDefinition[] {
+    return selectTools({
+      tools: allTools,
+      messages: request.messages,
+      config: this.config.agentLoop?.toolSelection,
+      activeProfile: request.toolProfile,
+      forceIncludeNames: toolSearchState?.loadedToolNames,
+    });
+  }
+
+  private resolveNativeToolSearchForRequest(): NativeToolSearchState {
+    return resolveNativeToolSearch({
+      providerName: this.adapter.provider,
+      modelName: this.getModel(),
+      config: this.config.agentLoop?.toolSelection,
+    });
+  }
+
+  private buildNativeToolCatalogForRequest(
+    request: ChatRequest,
+    allTools: ToolDefinition[],
+  ): ToolDefinition[] {
+    return filterToolsByProfile({
+      tools: allTools,
+      config: this.config.agentLoop?.toolSelection,
+      activeProfile: request.toolProfile,
+    });
+  }
+
+  private buildProviderToolOptionsForRequest(selectedTools: ToolDefinition[]) {
+    return buildProviderToolOptions({
+      providerName: this.adapter.provider,
+      modelName: this.getModel(),
+      selectedTools,
+      config: this.config.agentLoop?.toolSelection,
+      metaToolName: this.getToolSearchMetaToolName(),
+    });
+  }
+
+  private getToolSearchMetaToolName(): string {
+    return (
+      this.config.agentLoop?.toolSelection?.search?.metaToolName ??
+      "search_tools"
+    );
+  }
+
+  private createToolSearchTool(
+    request: ChatRequest,
+    allTools: ToolDefinition[],
+    selectedTools: ToolDefinition[],
+  ): ToolDefinition | null {
+    if (
+      !shouldExposeToolSearch({
+        tools: allTools,
+        selectedTools,
+        config: this.config.agentLoop?.toolSelection,
+      })
+    ) {
+      return null;
+    }
+
+    const toolName = this.getToolSearchMetaToolName();
+    const excludedNames = selectedTools.map((tool) => tool.name);
+
+    return {
+      name: toolName,
+      description:
+        "Search available deferred tools and load the most relevant ones for the next step when the right tool is not currently exposed.",
+      location: "server",
+      hidden: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Describe the tool capability you need to find.",
+          },
+          limit: {
+            type: "number",
+            description: "Maximum number of matching tools to load.",
+          },
+        },
+        required: ["query"],
+      },
+      handler: async (params) => {
+        const args = params as { query: string; limit?: number };
+        const results = searchTools({
+          tools: allTools,
+          query: args.query,
+          config: this.config.agentLoop?.toolSelection,
+          activeProfile: request.toolProfile,
+          limit: args.limit,
+          excludeNames: excludedNames,
+        });
+
+        if (this.config.debug || this.config.agentLoop?.debug) {
+          console.log("[Copilot SDK] search_tools result:", {
+            query: args.query,
+            activeProfile:
+              request.toolProfile ??
+              this.config.agentLoop?.toolSelection?.defaultProfile,
+            selectedToolCount: selectedTools.length,
+            catalogCount: allTools.length,
+            loadedTools: results.map((result) => result.name),
+            results: results.map((result) => ({
+              name: result.name,
+              location: result.location,
+              category: result.category,
+              group: result.group,
+              score: result.score,
+            })),
+          });
+        }
+
+        return {
+          success: true,
+          query: args.query,
+          loadedTools: results.map((result) => result.name),
+          results,
+        } satisfies ToolSearchResult;
+      },
+    };
+  }
+
+  private extendLoadedToolNames(
+    current: ToolSearchState | undefined,
+    results: Array<{ name: string; result: unknown }>,
+  ): ToolSearchState | undefined {
+    const loaded = new Set(current?.loadedToolNames ?? []);
+    const searchToolName = this.getToolSearchMetaToolName();
+
+    for (const result of results) {
+      if (result.name !== searchToolName) {
+        continue;
+      }
+      const typedResult = result.result as {
+        loadedTools?: unknown;
+      } | null;
+      if (!Array.isArray(typedResult?.loadedTools)) {
+        continue;
+      }
+      for (const toolName of typedResult.loadedTools) {
+        if (typeof toolName === "string" && toolName) {
+          loaded.add(toolName);
+        }
+      }
+    }
+
+    if (loaded.size === 0) {
+      return current;
+    }
+
+    return {
+      loadedToolNames: [...loaded],
+    };
+  }
+
   /**
    * Process a chat request with tool support (Vercel AI SDK pattern)
    *
@@ -663,6 +891,7 @@ export class Runtime {
     _isRecursive?: boolean,
     // HTTP request for extracting headers (auth context)
     _httpRequest?: Request,
+    _toolSearchState?: ToolSearchState,
   ): AsyncGenerator<StreamEvent> {
     const debug = this.config.debug || this.config.agentLoop?.debug;
 
@@ -679,6 +908,7 @@ export class Runtime {
         _accumulatedMessages,
         _isRecursive,
         _httpRequest,
+        _toolSearchState,
       )) {
         yield event;
       }
@@ -689,25 +919,44 @@ export class Runtime {
     const newMessages: DoneEventMessage[] = _accumulatedMessages || [];
     const maxIterations = this.config.agentLoop?.maxIterations || 20;
 
-    // Collect all tools (server + client from request)
-    const allTools: ToolDefinition[] = [...this.tools.values()];
-
-    // Add client tools from request
-    if (request.tools) {
-      for (const tool of request.tools) {
-        allTools.push({
-          name: tool.name,
-          description: tool.description,
-          location: "client",
-          inputSchema: tool.inputSchema as ToolDefinition["inputSchema"],
-        });
-      }
-    }
+    const allTools = this.collectToolsForRequest(request);
+    const nativeToolSearch = this.resolveNativeToolSearchForRequest();
+    const nativeToolCatalog = nativeToolSearch
+      ? this.buildNativeToolCatalogForRequest(request, allTools)
+      : null;
+    const selectedTools =
+      nativeToolCatalog ??
+      this.selectToolsForRequest(request, allTools, _toolSearchState);
+    const toolSearchTool = nativeToolSearch
+      ? null
+      : this.createToolSearchTool(request, allTools, selectedTools);
+    const effectiveSelectedTools = nativeToolCatalog
+      ? nativeToolCatalog
+      : toolSearchTool
+        ? [...selectedTools, toolSearchTool]
+        : selectedTools;
+    const providerToolOptions = this.buildProviderToolOptionsForRequest(
+      effectiveSelectedTools,
+    );
+    const selectedToolMap = new Map(
+      effectiveSelectedTools.map((tool) => [tool.name, tool] as const),
+    );
 
     if (debug) {
       console.log(
         `[Copilot SDK] Processing chat with ${allTools.length} tools`,
       );
+      if (effectiveSelectedTools.length !== allTools.length) {
+        console.log(
+          `[Copilot SDK] Tool selection active: ${effectiveSelectedTools.length}/${allTools.length} tools`,
+          {
+            activeProfile:
+              request.toolProfile ??
+              this.config.agentLoop?.toolSelection?.defaultProfile,
+            nativeSearch: nativeToolSearch?.provider ?? null,
+          },
+        );
+      }
       // Log messages with attachments for debugging vision support
       for (let i = 0; i < request.messages.length; i++) {
         const msg = request.messages[i];
@@ -747,11 +996,16 @@ export class Runtime {
     const completionRequest: ChatCompletionRequest = {
       messages: [], // Not used when rawMessages is provided
       rawMessages: request.messages as Array<Record<string, unknown>>,
-      actions: this.convertToolsToActions(allTools),
+      actions: nativeToolSearch
+        ? undefined
+        : this.convertToolsToActions(effectiveSelectedTools),
+      toolDefinitions: nativeToolSearch ? effectiveSelectedTools : undefined,
       systemPrompt: systemPrompt,
       config: request.config,
       signal,
       webSearch: this.getWebSearchConfig(),
+      providerToolOptions,
+      debug,
     };
 
     // Stream from adapter
@@ -846,7 +1100,7 @@ export class Runtime {
       const clientToolCalls: ToolCallInfo[] = [];
 
       for (const tc of toolCalls) {
-        const tool = allTools.find((t) => t.name === tc.name);
+        const tool = selectedToolMap.get(tc.name);
         if (tool?.location === "server" && tool.handler) {
           serverToolCalls.push(tc);
         } else {
@@ -868,7 +1122,7 @@ export class Runtime {
         "toolContext" in this.config ? this.config.toolContext : undefined;
 
       for (const tc of serverToolCalls) {
-        const tool = allTools.find((t) => t.name === tc.name);
+        const tool = selectedToolMap.get(tc.name);
         if (tool?.handler) {
           if (debug) {
             console.log(`[Copilot SDK] Executing server-side tool: ${tc.name}`);
@@ -896,6 +1150,7 @@ export class Runtime {
             yield {
               type: "action:end",
               id: tc.id,
+              name: tc.name,
               result,
             } as StreamEvent;
           } catch (error) {
@@ -917,6 +1172,7 @@ export class Runtime {
             yield {
               type: "action:end",
               id: tc.id,
+              name: tc.name,
               error:
                 error instanceof Error
                   ? error.message
@@ -981,6 +1237,13 @@ export class Runtime {
           ...request,
           messages: messagesWithResults as ChatRequest["messages"],
         };
+        const nextToolSearchState = this.extendLoadedToolNames(
+          _toolSearchState,
+          serverToolResults.map((result) => ({
+            name: result.name,
+            result: result.result,
+          })),
+        );
 
         // Signal end of current message turn before continuing
         // This tells the client to finalize the current assistant message
@@ -994,6 +1257,7 @@ export class Runtime {
           newMessages,
           true, // Mark as recursive
           _httpRequest,
+          nextToolSearchState,
         )) {
           yield event;
         }
@@ -1076,6 +1340,7 @@ export class Runtime {
     _accumulatedMessages?: DoneEventMessage[],
     _isRecursive?: boolean,
     _httpRequest?: Request,
+    _toolSearchState?: ToolSearchState,
   ): AsyncGenerator<StreamEvent> {
     const newMessages: DoneEventMessage[] = _accumulatedMessages || [];
     const debug = this.config.debug || this.config.agentLoop?.debug;
@@ -1087,20 +1352,9 @@ export class Runtime {
       total_tokens: number;
     } = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
 
-    // Collect all tools (server + client from request)
-    const allTools: ToolDefinition[] = [...this.tools.values()];
-
-    // Add client tools from request
-    if (request.tools) {
-      for (const tool of request.tools) {
-        allTools.push({
-          name: tool.name,
-          description: tool.description,
-          location: "client",
-          inputSchema: tool.inputSchema as ToolDefinition["inputSchema"],
-        });
-      }
-    }
+    const allTools = this.collectToolsForRequest(request);
+    const nativeToolSearch = this.resolveNativeToolSearchForRequest();
+    let toolSearchState = _toolSearchState;
 
     // Build system prompt
     const systemPrompt = request.systemPrompt || this.config.systemPrompt || "";
@@ -1144,21 +1398,48 @@ export class Runtime {
           _accumulatedMessages,
           _isRecursive,
           _httpRequest,
+          toolSearchState,
         )) {
           yield event;
         }
         return;
       }
 
+      const nativeToolCatalog = nativeToolSearch
+        ? this.buildNativeToolCatalogForRequest(request, allTools)
+        : null;
+      const selectedTools =
+        nativeToolCatalog ??
+        this.selectToolsForRequest(request, allTools, toolSearchState);
+      const toolSearchTool = nativeToolSearch
+        ? null
+        : this.createToolSearchTool(request, allTools, selectedTools);
+      const effectiveSelectedTools = nativeToolCatalog
+        ? nativeToolCatalog
+        : toolSearchTool
+          ? [...selectedTools, toolSearchTool]
+          : selectedTools;
+      const providerToolOptions = this.buildProviderToolOptionsForRequest(
+        effectiveSelectedTools,
+      );
+      const selectedToolMap = new Map(
+        effectiveSelectedTools.map((tool) => [tool.name, tool] as const),
+      );
+
       // Create completion request
       const completionRequest: ChatCompletionRequest = {
         messages: [],
         rawMessages: conversationMessages,
-        actions: this.convertToolsToActions(allTools),
+        actions: nativeToolSearch
+          ? undefined
+          : this.convertToolsToActions(effectiveSelectedTools),
+        toolDefinitions: nativeToolSearch ? effectiveSelectedTools : undefined,
         systemPrompt: systemPrompt,
         config: request.config,
         signal,
         webSearch: this.getWebSearchConfig(),
+        providerToolOptions,
+        debug,
       };
 
       try {
@@ -1199,7 +1480,7 @@ export class Runtime {
           const clientToolCalls: ToolCallInfo[] = [];
 
           for (const tc of result.toolCalls) {
-            const tool = allTools.find((t) => t.name === tc.name);
+            const tool = selectedToolMap.get(tc.name);
             if (tool?.location === "server" && tool.handler) {
               serverToolCalls.push(tc);
             } else {
@@ -1213,7 +1494,7 @@ export class Runtime {
 
           // Emit tool call events
           for (const tc of result.toolCalls) {
-            const tool = allTools.find((t) => t.name === tc.name);
+            const tool = selectedToolMap.get(tc.name);
             yield {
               type: "action:start",
               id: tc.id,
@@ -1241,7 +1522,7 @@ export class Runtime {
             "toolContext" in this.config ? this.config.toolContext : undefined;
 
           for (const tc of serverToolCalls) {
-            const tool = allTools.find((t) => t.name === tc.name);
+            const tool = selectedToolMap.get(tc.name);
             if (tool?.handler) {
               if (debug) {
                 console.log(`[Copilot SDK] Executing tool: ${tc.name}`);
@@ -1268,6 +1549,7 @@ export class Runtime {
                 yield {
                   type: "action:end",
                   id: tc.id,
+                  name: tc.name,
                   result: toolResult,
                 } as StreamEvent;
               } catch (error) {
@@ -1288,6 +1570,7 @@ export class Runtime {
                 yield {
                   type: "action:end",
                   id: tc.id,
+                  name: tc.name,
                   error:
                     error instanceof Error
                       ? error.message
@@ -1344,6 +1627,13 @@ export class Runtime {
                 Record<string, unknown>
               >),
             ];
+            toolSearchState = this.extendLoadedToolNames(
+              toolSearchState,
+              serverToolResults.map((toolResult) => ({
+                name: toolResult.name,
+                result: toolResult.result,
+              })),
+            );
 
             // Continue loop
             continue;
diff --git a/packages/llm-sdk/src/server/tool-selection.ts b/packages/llm-sdk/src/server/tool-selection.ts
new file mode 100644
index 0000000..a12cd3a
--- /dev/null
+++ b/packages/llm-sdk/src/server/tool-selection.ts
@@ -0,0 +1,587 @@
+import type {
+  AnthropicProviderToolOptions,
+  OpenAIProviderToolOptions,
+  ProviderToolRuntimeOptions,
+  ToolDefinition,
+  ToolSearchConfig,
+  ToolSelectionConfig,
+} from "../core/stream-events";
+
+type ToolSelectionMessage = {
+  role: string;
+  content?: unknown;
+};
+
+export interface ToolSearchMatch {
+  name: string;
+  description: string;
+  location?: ToolDefinition["location"];
+  category?: string;
+  group?: string;
+  profiles?: string[];
+  searchKeywords?: string[];
+  score: number;
+}
+
+export interface ResolvedNativeToolSearch {
+  provider: "anthropic" | "openai";
+  variant?: "bm25" | "regex";
+  useResponsesApi?: boolean;
+}
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+
+function unique<T>(values: T[]): T[] {
+  return [...new Set(values)];
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9_\s-]/g, " ")
+    .split(/\s+/)
+    .filter((token) => token.length > 1);
+}
+
+function stringifyContent(content: unknown): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!content) {
+    return "";
+  }
+  try {
+    return JSON.stringify(content);
+  } catch {
+    return String(content);
+  }
+}
+
+function buildToolQuery(messages: ToolSelectionMessage[]): string {
+  return messages
+    .filter(
+      (message) => message.role === "user" || message.role === "assistant",
+    )
+    .slice(-3)
+    .map((message) => stringifyContent(message.content))
+    .filter(Boolean)
+    .join(" ");
+}
+
+function buildSearchText(tool: ToolDefinition): string {
+  return [
+    tool.name.replace(/_/g, " "),
+    tool.description,
+    tool.category ?? "",
+    tool.group ?? "",
+    ...(tool.profiles ?? []),
+    ...(tool.searchKeywords ?? []),
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+function matchesSelector(
+  tool: ToolDefinition,
+  selector: string,
+  activeProfile?: string,
+): boolean {
+  const normalized = selector.trim().toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+
+  if (normalized === "*" || normalized === "all") {
+    return true;
+  }
+  if (normalized === tool.name.toLowerCase()) {
+    return true;
+  }
+  if (normalized.startsWith("group:")) {
+    return (tool.group ?? "").toLowerCase() === normalized.slice(6);
+  }
+  if (normalized.startsWith("category:")) {
+    return (tool.category ?? "").toLowerCase() === normalized.slice(9);
+  }
+  if (normalized.startsWith("profile:")) {
+    return (tool.profiles ?? [])
+      .map((value) => value.toLowerCase())
+      .includes(normalized.slice(8));
+  }
+  if (activeProfile && normalized === activeProfile.toLowerCase()) {
+    return (tool.profiles ?? [])
+      .map((value) => value.toLowerCase())
+      .includes(normalized);
+  }
+  return false;
+}
+
+function scoreTool(
+  tool: ToolDefinition,
+  queryTokens: string[],
+  activeProfile?: string,
+): number {
+  const haystack = [
+    tool.name,
+    tool.description,
+    tool.category,
+    tool.group,
+    ...(tool.profiles ?? []),
+    ...(tool.searchKeywords ?? []),
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+
+  let score = tool.deferLoading ? 0 : 2;
+  if (activeProfile && tool.profiles?.includes(activeProfile)) {
+    score += 2;
+  }
+
+  for (const token of queryTokens) {
+    if (tool.name.toLowerCase() === token) {
+      score += 6;
+    } else if (tool.name.toLowerCase().includes(token)) {
+      score += 4;
+    } else if (haystack.includes(token)) {
+      score += 2;
+    }
+  }
+
+  return score;
+}
+
+export function filterToolsByProfile(params: {
+  tools: ToolDefinition[];
+  config?: ToolSelectionConfig;
+  activeProfile?: string;
+}): ToolDefinition[] {
+  const available = params.tools.filter((tool) => tool.available !== false);
+  const config = params.config;
+  if (!config?.enabled) {
+    return available;
+  }
+
+  const activeProfile = params.activeProfile ?? config.defaultProfile;
+  const includeUnprofiled = config.includeUnprofiled ?? true;
+  const profile = activeProfile ? config.profiles?.[activeProfile] : undefined;
+  let filtered = available;
+
+  if (profile?.include?.length) {
+    filtered = filtered.filter(
+      (tool) =>
+        profile.include!.some((selector) =>
+          matchesSelector(tool, selector, activeProfile),
+        ) ||
+        (!!activeProfile && tool.profiles?.includes(activeProfile)),
+    );
+  } else if (activeProfile) {
+    filtered = filtered.filter((tool) => {
+      if (tool.profiles?.length) {
+        return tool.profiles.includes(activeProfile);
+      }
+      return includeUnprofiled;
+    });
+  }
+
+  if (profile?.exclude?.length) {
+    filtered = filtered.filter(
+      (tool) =>
+        !profile.exclude!.some((selector) =>
+          matchesSelector(tool, selector, activeProfile),
+        ),
+    );
+  }
+
+  return filtered;
+}
+
+function calculateBM25Score(
+  tool: ToolDefinition,
+  queryTerms: string[],
+  idf: Map<string, number>,
+  avgDocLength: number,
+  activeProfile?: string,
+): number {
+  const text = buildSearchText(tool);
+  const tokens = tokenize(text);
+  const docLength = Math.max(1, tokens.length);
+
+  let score = 0;
+
+  for (const term of queryTerms) {
+    const termFreq = tokens.filter((token) => token === term).length;
+    if (termFreq === 0) {
+      continue;
+    }
+
+    const termIDF = idf.get(term) ?? 0;
+    const numerator = termFreq * (BM25_K1 + 1);
+    const denominator =
+      termFreq + BM25_K1 * (1 - BM25_B + BM25_B * (docLength / avgDocLength));
+    score += termIDF * (numerator / denominator);
+  }
+
+  const nameLower = tool.name.toLowerCase();
+  for (const term of queryTerms) {
+    if (nameLower === term) {
+      score += 3;
+    } else if (nameLower.includes(term)) {
+      score += 1.5;
+    }
+  }
+
+  if (activeProfile && tool.profiles?.includes(activeProfile)) {
+    score += 0.75;
+  }
+
+  return score;
+}
+
+export function selectTools(params: {
+  tools: ToolDefinition[];
+  messages: ToolSelectionMessage[];
+  config?: ToolSelectionConfig;
+  activeProfile?: string;
+  forceIncludeNames?: string[];
+}): ToolDefinition[] {
+  const config = params.config;
+  const available = filterToolsByProfile({
+    tools: params.tools,
+    config,
+    activeProfile: params.activeProfile,
+  });
+  if (!config?.enabled) {
+    return available;
+  }
+  const activeProfile = params.activeProfile ?? config.defaultProfile;
+  const forceIncludeNames = new Set(params.forceIncludeNames ?? []);
+  let filtered = available;
+  const strictDeferredLoading =
+    config.search?.enabled && config.search.strictDeferredLoading === true;
+
+  if (strictDeferredLoading) {
+    filtered = filtered.filter(
+      (tool) => !tool.deferLoading || forceIncludeNames.has(tool.name),
+    );
+  }
+
+  if (!config.dynamicSelection?.enabled) {
+    if (forceIncludeNames.size === 0) {
+      return filtered;
+    }
+    const merged = new Map(filtered.map((tool) => [tool.name, tool]));
+    for (const tool of available) {
+      if (forceIncludeNames.has(tool.name)) {
+        merged.set(tool.name, tool);
+      }
+    }
+    return [...merged.values()];
+  }
+
+  if (filtered.length === 0) {
+    return filtered;
+  }
+
+  const maxTools = Math.max(
+    1,
+    Math.min(
+      config.dynamicSelection.maxTools ?? filtered.length,
+      filtered.length,
+    ),
+  );
+  const queryTokens = unique(tokenize(buildToolQuery(params.messages)));
+  const ranked = [...filtered].sort((left, right) => {
+    const scoreDiff =
+      scoreTool(right, queryTokens, activeProfile) -
+      scoreTool(left, queryTokens, activeProfile);
+    if (scoreDiff !== 0) {
+      return scoreDiff;
+    }
+    return left.name.localeCompare(right.name);
+  });
+
+  if (forceIncludeNames.size === 0) {
+    return ranked.slice(0, maxTools);
+  }
+
+  const forced = ranked.filter((tool) => forceIncludeNames.has(tool.name));
+  const others = ranked.filter((tool) => !forceIncludeNames.has(tool.name));
+  const remainingSlots = Math.max(0, maxTools - forced.length);
+  return [...forced, ...others.slice(0, remainingSlots)];
+}
+
+export function searchTools(params: {
+  tools: ToolDefinition[];
+  query: string;
+  config?: ToolSelectionConfig;
+  activeProfile?: string;
+  limit?: number;
+  excludeNames?: string[];
+  includeSelected?: boolean;
+}): ToolSearchMatch[] {
+  const queryTerms = unique(tokenize(params.query));
+  if (queryTerms.length === 0) {
+    return [];
+  }
+
+  const candidates = filterToolsByProfile({
+    tools: params.tools,
+    config: params.config,
+    activeProfile: params.activeProfile,
+  }).filter((tool) => {
+    if ((params.excludeNames ?? []).includes(tool.name)) {
+      return false;
+    }
+    if (params.includeSelected) {
+      return true;
+    }
+    return tool.deferLoading === true;
+  });
+
+  if (candidates.length === 0) {
+    return [];
+  }
+
+  const docs = candidates.map((tool) => tokenize(buildSearchText(tool)));
+  const avgDocLength =
+    docs.reduce((sum, tokens) => sum + Math.max(1, tokens.length), 0) /
+    docs.length;
+  const idf = new Map<string, number>();
+
+  for (const term of queryTerms) {
+    const docFreq = docs.reduce(
+      (count, tokens) => count + (tokens.includes(term) ? 1 : 0),
+      0,
+    );
+    idf.set(
+      term,
+      Math.log((docs.length - docFreq + 0.5) / (docFreq + 0.5) + 1),
+    );
+  }
+
+  const minScore = params.config?.search?.minScore ?? 0.1;
+  const limit = Math.max(
+    1,
+    params.limit ?? params.config?.search?.maxResults ?? 5,
+  );
+  const activeProfile = params.activeProfile ?? params.config?.defaultProfile;
+
+  return candidates
+    .map((tool) => ({
+      tool,
+      score: calculateBM25Score(
+        tool,
+        queryTerms,
+        idf,
+        avgDocLength,
+        activeProfile,
+      ),
+    }))
+    .filter((entry) => entry.score >= minScore)
+    .sort((left, right) => {
+      const scoreDiff = right.score - left.score;
+      if (scoreDiff !== 0) {
+        return scoreDiff;
+      }
+      return left.tool.name.localeCompare(right.tool.name);
+    })
+    .slice(0, limit)
+    .map(({ tool, score }) => ({
+      name: tool.name,
+      description: tool.description,
+      location: tool.location,
+      category: tool.category,
+      group: tool.group,
+      profiles: tool.profiles,
+      searchKeywords: tool.searchKeywords,
+      score: Number(score.toFixed(4)),
+    }));
+}
+
+function normalizeModelName(modelName?: string): string {
+  return (modelName ?? "").trim().toLowerCase();
+}
+
+export function supportsAnthropicNativeToolSearch(modelName?: string): boolean {
+  const model = normalizeModelName(modelName);
+  if (!model) {
+    return false;
+  }
+
+  if (model.includes("haiku")) {
+    return false;
+  }
+
+  return (
+    /(?:^|[-_ ])(?:sonnet|opus)[-_ ]?4(?:$|[-_. ])/.test(model) ||
+    /claude[-_ ](?:sonnet|opus)[-_ ]?4/.test(model) ||
+    /claude[-_ ]?4[-_ ](?:sonnet|opus)/.test(model)
+  );
+}
+
+export function supportsOpenAINativeToolSearch(modelName?: string): boolean {
+  const model = normalizeModelName(modelName);
+  if (!model) {
+    return false;
+  }
+
+  const match = model.match(/^gpt-5(?:[._-](\d+))?(?:$|[._-])/);
+  if (!match) {
+    return false;
+  }
+
+  const minorVersion = match[1] ? Number.parseInt(match[1], 10) : Number.NaN;
+  if (!Number.isFinite(minorVersion)) {
+    return false;
+  }
+
+  return minorVersion >= 4;
+}
+
+export function resolveNativeToolSearch(params: {
+  providerName: string;
+  modelName?: string;
+  config?: ToolSelectionConfig;
+}): ResolvedNativeToolSearch | null {
+  const searchConfig = params.config?.search;
+  if (!searchConfig?.enabled) {
+    return null;
+  }
+
+  const mode = searchConfig.mode ?? "auto";
+  if (mode === "manual") {
+    return null;
+  }
+
+  if (
+    params.providerName === "anthropic" &&
+    supportsAnthropicNativeToolSearch(params.modelName)
+  ) {
+    return {
+      provider: "anthropic",
+      variant: searchConfig.anthropicVariant ?? "bm25",
+    };
+  }
+
+  if (
+    params.providerName === "openai" &&
+    supportsOpenAINativeToolSearch(params.modelName)
+  ) {
+    return {
+      provider: "openai",
+      useResponsesApi: true,
+    };
+  }
+
+  return mode === "native" ? null : null;
+}
+
+export function shouldExposeToolSearch(params: {
+  tools: ToolDefinition[];
+  selectedTools: ToolDefinition[];
+  config?: ToolSelectionConfig;
+}): boolean {
+  const searchConfig = params.config?.search;
+  if (!searchConfig?.enabled) {
+    return false;
+  }
+
+  const deferredCount = params.tools.filter((tool) => tool.deferLoading).length;
+  if (deferredCount === 0) {
+    return false;
+  }
+
+  const threshold = searchConfig.exposeWhenToolCountExceeds ?? 8;
+  return (
+    params.tools.length >= threshold ||
+    deferredCount > Math.max(0, params.selectedTools.length)
+  );
+}
+
+export function buildProviderToolOptions(params: {
+  providerName: string;
+  modelName?: string;
+  selectedTools: ToolDefinition[];
+  config?: ToolSelectionConfig;
+  metaToolName?: string;
+}): ProviderToolRuntimeOptions | undefined {
+  const nativeHints = params.config?.nativeProviderHints;
+  const resolvedNativeSearch = resolveNativeToolSearch({
+    providerName: params.providerName,
+    modelName: params.modelName,
+    config: params.config,
+  });
+  const effectiveTools = params.metaToolName
+    ? params.selectedTools.filter((tool) => tool.name !== params.metaToolName)
+    : params.selectedTools;
+
+  if (params.providerName === "openai") {
+    const hints = nativeHints?.openai;
+    if (!hints && !resolvedNativeSearch) {
+      return undefined;
+    }
+
+    let toolChoice: OpenAIProviderToolOptions["toolChoice"];
+    if (hints?.toolChoice === "required") {
+      toolChoice = "required";
+    } else if (hints?.toolChoice === "single" && effectiveTools.length === 1) {
+      toolChoice = {
+        type: "function",
+        name: effectiveTools[0].name,
+      };
+    } else if (hints?.toolChoice === "auto") {
+      toolChoice = "auto";
+    }
+
+    return {
+      openai: {
+        toolChoice,
+        parallelToolCalls: hints?.parallelToolCalls,
+        nativeToolSearch:
+          resolvedNativeSearch?.provider === "openai"
+            ? {
+                enabled: true,
+                useResponsesApi: resolvedNativeSearch.useResponsesApi,
+              }
+            : undefined,
+      },
+    };
+  }
+
+  if (params.providerName === "anthropic") {
+    const hints = nativeHints?.anthropic;
+    if (!hints && !resolvedNativeSearch) {
+      return undefined;
+    }
+
+    let toolChoice: AnthropicProviderToolOptions["toolChoice"];
+    if (hints?.toolChoice === "any") {
+      toolChoice = "any";
+    } else if (hints?.toolChoice === "single" && effectiveTools.length === 1) {
+      toolChoice = {
+        type: "tool",
+        name: effectiveTools[0].name,
+      };
+    } else if (hints?.toolChoice === "auto") {
+      toolChoice = "auto";
+    }
+
+    return {
+      anthropic: {
+        toolChoice,
+        disableParallelToolUse: hints?.disableParallelToolUse,
+        nativeToolSearch:
+          resolvedNativeSearch?.provider === "anthropic"
+            ? {
+                enabled: true,
+                variant: resolvedNativeSearch.variant ?? "bm25",
+              }
+            : undefined,
+      },
+    };
+  }
+
+  return undefined;
+}
diff --git a/packages/llm-sdk/src/server/types.ts b/packages/llm-sdk/src/server/types.ts
index af720d0..7ca15ed 100644
--- a/packages/llm-sdk/src/server/types.ts
+++ b/packages/llm-sdk/src/server/types.ts
@@ -143,12 +143,34 @@ export interface ChatRequest {
   tools?: Array<{
     name: string;
     description: string;
+    category?: string;
+    group?: string;
+    deferLoading?: boolean;
+    profiles?: string[];
+    searchKeywords?: string[];
     inputSchema: {
       type: "object";
       properties: Record<string, unknown>;
       required?: string[];
     };
   }>;
+  /** Full client tool catalog used for server-side tool selection and deferred search. */
+  toolCatalog?: Array<{
+    name: string;
+    description: string;
+    category?: string;
+    group?: string;
+    deferLoading?: boolean;
+    profiles?: string[];
+    searchKeywords?: string[];
+    inputSchema: {
+      type: "object";
+      properties: Record<string, unknown>;
+      required?: string[];
+    };
+  }>;
+  /** Active tool profile to apply when agentLoop.toolSelection is enabled. */
+  toolProfile?: string;
   /** Enable agentic loop mode */
   useAgentLoop?: boolean;
   /** Enable streaming responses (default: true). Set to false for non-streaming mode. */
diff --git a/tool-search-implementation.md b/tool-search-implementation.md
new file mode 100644
index 0000000..2dd6941
--- /dev/null
+++ b/tool-search-implementation.md
@@ -0,0 +1,253 @@
+# Tool Management Branch Summary
+
+Branch: `codex/tool-management-core`
+
+## Scope
+
+This branch adds the first full tool-management stack across `copilot-sdk`, `llm-sdk`, and the experimental demos.
+
+It covers:
+
+- tool profiles and selective loading
+- deferred tool loading
+- manual tool search fallback
+- native provider tool search hooks for Anthropic and OpenAI
+- prompt-side tool result truncation and context compaction groundwork
+- mixed client/server tool catalog support
+- provider payload debug logging
+- experimental scale-testing demo with 100 tools
+
+## Main Features Added
+
+### 1. Framework-agnostic prompt/tool optimization (`copilot-sdk`)
+
+Added shared optimization support in the chat/core layer:
+
+- tool profile selection
+- dynamic tool narrowing
+- tool result truncation controls
+- context budget reporting
+- history compaction with continuity summaries
+
+Public APIs added:
+
+- `setOptimizationConfig(...)`
+- `setToolProfile(...)`
+- `getContextUsage()`
+
+Main files:
+
+- `packages/copilot-sdk/src/chat/optimizations.ts`
+- `packages/copilot-sdk/src/chat/ChatWithTools.ts`
+- `packages/copilot-sdk/src/chat/classes/AbstractChat.ts`
+- `packages/copilot-sdk/src/core/types/tools.ts`
+
+### 2. Tool metadata and selection pipeline (`llm-sdk`)
+
+Added richer tool metadata and request-time selection:
+
+- `category`
+- `group`
+- `profiles`
+- `searchKeywords`
+- `deferLoading`
+
+Selection features:
+
+- profile-based filtering
+- include/exclude selectors
+- dynamic ranking by recent query/context
+- strict deferred loading mode
+- request-level `toolProfile`
+
+Main files:
+
+- `packages/llm-sdk/src/core/stream-events.ts`
+- `packages/llm-sdk/src/server/tool-selection.ts`
+- `packages/llm-sdk/src/server/runtime.ts`
+- `packages/llm-sdk/src/server/agent-loop.ts`
+
+### 3. Manual deferred tool search fallback
+
+Added SDK-managed `search_tools` fallback for providers/models without native search support.
+
+Behavior:
+
+- full tool catalog stays on the server
+- deferred tools stay out of the initial model-facing tool list
+- model can call `search_tools`
+- runtime loads matching deferred tools into the next loop iteration
+
+Supports:
+
+- mixed server tools + client tools
+- profile-aware search
+- BM25-style ranking
+
+Main files:
+
+- `packages/llm-sdk/src/server/tool-selection.ts`
+- `packages/llm-sdk/src/server/runtime.ts`
+
+### 4. Native provider tool search support
+
+Added provider-aware search mode selection:
+
+- `search.mode = "auto" | "native" | "manual"`
+
+Current behavior:
+
+- Anthropic Sonnet 4 / Opus 4 supported models -> native Anthropic search path
+- OpenAI `gpt-5.4+` supported models -> internal OpenAI Responses-based native path
+- all other providers/models -> manual `search_tools` fallback
+
+Anthropic native path:
+
+- adds `tool_search_tool_bm25_20251119` or regex variant
+- passes deferred tools with `defer_loading: true`
+
+OpenAI native path:
+
+- uses internal Responses-based adapter branch
+- keeps public SDK/frontend usage unchanged
+
+Main files:
+
+- `packages/llm-sdk/src/adapters/anthropic.ts`
+- `packages/llm-sdk/src/adapters/openai.ts`
+- `packages/llm-sdk/src/server/tool-selection.ts`
+
+### 5. Mixed client/server catalog support
+
+Added `toolCatalog` transport support so the runtime can search/select from the full catalog:
+
+- server tools from runtime config
+- client tools registered in the browser
+
+This allows deferred client tools to be discovered by search even when they are not initially exposed to the model.
+
+Main files:
+
+- `packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts`
+- `packages/copilot-sdk/src/chat/adapters/HttpTransport.ts`
+- `packages/copilot-sdk/src/chat/classes/AbstractChat.ts`
+- `packages/llm-sdk/src/server/types.ts`
+- `packages/llm-sdk/src/server/runtime.ts`
+
+### 6. Provider payload logging
+
+Added adapter-level debug payload logging for request/response inspection.
+
+Supported across:
+
+- OpenAI
+- Anthropic
+- Azure
+- Google
+- xAI
+- Ollama
+
+Current behavior:
+
+- logs request payloads
+- logs final provider responses
+- suppresses per-event stream spam
+
+Main file:
+
+- `packages/llm-sdk/src/adapters/base.ts`
+
+### 7. Experimental Tool Scale Lab
+
+Added a dedicated experimental demo for scale testing:
+
+- 100 tools total
+- 30 server tools
+- 70 client tools
+- profile switching
+- deferred loading
+- manual/native search path testing
+- provider behavior testing
+
+Main files:
+
+- `examples/experimental/app/tool-scale/page.tsx`
+- `examples/experimental/app/api/chat/tool-scale/route.ts`
+- `examples/experimental/lib/tool-scale/catalog.ts`
+- `examples/experimental/lib/tool-scale/server-tools.ts`
+- `examples/experimental/lib/tool-scale/client-tools.ts`
+
+## Config Examples
+
+### Runtime tool selection
+
+```ts
+agentLoop: {
+  enabled: true,
+  toolSelection: {
+    enabled: true,
+    defaultProfile: "support",
+    includeUnprofiled: false,
+    dynamicSelection: {
+      enabled: true,
+      maxTools: 6,
+    },
+    search: {
+      enabled: true,
+      mode: "auto",
+      strictDeferredLoading: true,
+      maxResults: 6,
+      metaToolName: "search_tools",
+      anthropicVariant: "bm25",
+    },
+  },
+}
+```
+
+### Client-side optimization
+
+```ts
+optimization: {
+  toolProfiles: {
+    enabled: true,
+    defaultProfile: "support",
+  },
+  toolResultConfig: {
+    truncation: {
+      enabled: true,
+      strategy: "smart",
+      hardMaxChars: 12000,
+    },
+  },
+  contextManagement: {
+    enabled: true,
+    history: {
+      maxMessages: 20,
+      pruneStrategy: "summarize",
+    },
+  },
+  contextBudget: {
+    enabled: true,
+    budget: {
+      contextWindowTokens: 128000,
+      toolResultsShare: 0.3,
+    },
+  },
+}
+```
+
+## Current Known Caveats
+
+These are not fully closed out yet:
+
+- mixed same-turn server + client tool calls still need more hardening in the runtime loop
+- OpenAI manual fallback + continuation path needs more validation
+- OpenAI native Responses path currently preserves the SDK contract, but is not full event-by-event Responses streaming yet
+- no dedicated automated tests were added in this branch yet
+
+## Suggested Next Steps
+
+- add tests for tool selection, deferred loading, and continuation ordering
+- tighten manual search scoring so profile-only matches do not leak through
+- harden mixed same-turn server/client tool execution ordering
+- improve OpenAI Responses-native streaming parity

From a4ff7339ad79c5be72975bf2244e728765603136 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Thu, 12 Mar 2026 12:22:26 +0530
Subject: [PATCH 06/72] refactor(sdk): flatten agentLoop API, auto-detect
 deferred tools, unified tool search

Breaking: removed agentLoop config block (use flat maxIterations + toolSearch),
removed toolCatalog from ChatRequest (use tools only), removed AgentLoopConfig /
ToolSelectionConfig / ToolDynamicSelectionConfig from public API, removed
strictDeferredLoading and providerHints (use flat toolChoice/parallelCalls in ToolSearchConfig).

New: auto-detection of deferred tools (zero config, deferLoading flag on tool is
enough), flat ToolSearchConfig with description/name/maxEagerTools/maxResults/
exposeWhenExceeds/toolChoice/parallelCalls/defaultProfile/profiles/includeUnprofiled,
native provider tool search auto-detected for Anthropic Sonnet/Opus 4+ and GPT-5.4+,
ToolSearchConfig now exported from server index, full BM25 rewrite in tool-selection.ts
(selectTools, searchTools, filterToolsByProfile, shouldExposeToolSearch,
resolveNativeToolSearch, buildProviderToolOptions), AgentLoopOptions flattened to
maxIterations/debug/toolSelectionConfig.

copilot-sdk: useTool hook gains deferLoading/profiles/searchKeywords/group/category/
resultConfig/title/executingTitle/completedTitle/aiResponseMode/aiContext props;
CopilotProvider maxIterations promoted to top-level; AbstractChat.buildRequest sends full
tools array with deferLoading flags intact for server-side deferred management;
HttpTransport drops toolCatalog from request body.

Examples: express-demo migrated to flat API with profiles and debug payload capture;
tool-scale example updated for 100-tool deferred loading; other routes updated.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../experimental/app/api/chat/openai/route.ts |   4 +-
 .../app/api/chat/test-server-tools/route.ts   |   4 +-
 .../app/api/chat/tool-scale/route.ts          | 104 +++---
 examples/experimental/app/tool-scale/page.tsx |  19 +-
 examples/express-demo/src/index.ts            | 209 +++++++++--
 .../src/chat/adapters/HttpTransport.ts        |   1 -
 .../src/chat/classes/AbstractChat.ts          |  90 +----
 .../src/chat/interfaces/ChatTransport.ts      |   2 -
 .../copilot-sdk/src/react/hooks/useTool.ts    |  37 ++
 .../src/react/provider/CopilotProvider.tsx    |   5 +
 packages/llm-sdk/src/core/stream-events.ts    |  50 ---
 packages/llm-sdk/src/index.ts                 |   4 -
 packages/llm-sdk/src/server/agent-loop.ts     |  32 +-
 packages/llm-sdk/src/server/index.ts          |   1 +
 packages/llm-sdk/src/server/runtime.ts        | 100 ++++--
 packages/llm-sdk/src/server/tool-selection.ts | 339 ++++++------------
 packages/llm-sdk/src/server/types.ts          |  96 +++--
 17 files changed, 531 insertions(+), 566 deletions(-)

diff --git a/examples/experimental/app/api/chat/openai/route.ts b/examples/experimental/app/api/chat/openai/route.ts
index 402408d..f19714a 100644
--- a/examples/experimental/app/api/chat/openai/route.ts
+++ b/examples/experimental/app/api/chat/openai/route.ts
@@ -12,9 +12,7 @@ const runtime = createRuntime({
     "You are a helpful assistant powered by OpenAI GPT-4o. Be concise and helpful.",
   debug: process.env.NODE_ENV === "development",
   // For testing max iterations - set to 2 to easily trigger the limit
-  agentLoop: {
-    maxIterations: 2,
-  },
+  maxIterations: 2,
 });
 
 export async function POST(request: Request) {
diff --git a/examples/experimental/app/api/chat/test-server-tools/route.ts b/examples/experimental/app/api/chat/test-server-tools/route.ts
index de2e4f3..dbfaca8 100644
--- a/examples/experimental/app/api/chat/test-server-tools/route.ts
+++ b/examples/experimental/app/api/chat/test-server-tools/route.ts
@@ -43,9 +43,7 @@ const runtime = createRuntime({
     "You are a helpful assistant. Use the get_random_number tool when asked for random numbers.",
   debug: true,
   tools: serverTools,
-  agentLoop: {
-    maxIterations: 2, // Low limit for testing
-  },
+  maxIterations: 2, // Low limit for testing
 });
 
 export async function POST(request: Request) {
diff --git a/examples/experimental/app/api/chat/tool-scale/route.ts b/examples/experimental/app/api/chat/tool-scale/route.ts
index 12d9cc6..be8c8ea 100644
--- a/examples/experimental/app/api/chat/tool-scale/route.ts
+++ b/examples/experimental/app/api/chat/tool-scale/route.ts
@@ -45,74 +45,52 @@ Use tools sparingly and intentionally.
 When tools are missing, rely on the search_tools meta-tool to discover deferred tools rather than guessing.
 Keep answers short and explain which class of tools you used when it helps the user understand tool selection behavior.`,
   tools: toolScaleServerTools,
-  agentLoop: {
-    enabled: true,
-    maxIterations: 6,
-    debug: process.env.NODE_ENV === "development",
-    toolSelection: {
-      enabled: true,
-      defaultProfile: "support",
-      includeUnprofiled: false,
-      search: {
-        enabled: true,
-        maxResults: 6,
-        minScore: 0.15,
-        exposeWhenToolCountExceeds: 12,
-        metaToolName: "search_tools",
-        strictDeferredLoading: true,
+  maxIterations: 6,
+  toolSearch: {
+    maxResults: 6,
+    exposeWhenExceeds: 12,
+    maxEagerTools: 6,
+    defaultProfile: "support",
+    includeUnprofiled: false,
+    profiles: {
+      support: {
+        include: [
+          "profile:support",
+          "category:knowledge",
+          "category:billing",
+          "category:browser",
+          "category:utility",
+        ],
+        exclude: ["group:admin"],
       },
-      dynamicSelection: {
-        enabled: true,
-        maxTools: 6,
+      workspace: {
+        include: [
+          "profile:workspace",
+          "category:workspace",
+          "category:browser",
+          "category:analytics",
+          "category:utility",
+        ],
       },
-      profiles: {
-        support: {
-          include: [
-            "profile:support",
-            "category:knowledge",
-            "category:billing",
-            "category:browser",
-            "category:utility",
-          ],
-          exclude: ["group:admin"],
-        },
-        workspace: {
-          include: [
-            "profile:workspace",
-            "category:workspace",
-            "category:browser",
-            "category:analytics",
-            "category:utility",
-          ],
-        },
-        commerce: {
-          include: [
-            "profile:commerce",
-            "category:commerce",
-            "category:billing",
-            "group:actions",
-          ],
-        },
-        admin: {
-          include: [
-            "profile:admin",
-            "category:operations",
-            "category:analytics",
-            "category:utility",
-          ],
-        },
+      commerce: {
+        include: [
+          "profile:commerce",
+          "category:commerce",
+          "category:billing",
+          "group:actions",
+        ],
       },
-      nativeProviderHints: {
-        anthropic: {
-          toolChoice: "auto",
-          disableParallelToolUse: true,
-        },
-        openai: {
-          toolChoice: "auto",
-          parallelToolCalls: false,
-        },
+      admin: {
+        include: [
+          "profile:admin",
+          "category:operations",
+          "category:analytics",
+          "category:utility",
+        ],
       },
     },
+    toolChoice: "auto",
+    parallelCalls: false,
   },
 });
 
diff --git a/examples/experimental/app/tool-scale/page.tsx b/examples/experimental/app/tool-scale/page.tsx
index 4178a3f..2c4a6ae 100644
--- a/examples/experimental/app/tool-scale/page.tsx
+++ b/examples/experimental/app/tool-scale/page.tsx
@@ -47,20 +47,15 @@ const requestSnippet = `{
   ]
 }`;
 
-const selectionSnippet = `toolSelection: {
-  enabled: true,
+const selectionSnippet = `toolSearch: {
+  maxResults: 6,
+  exposeWhenExceeds: 12,
+  maxEagerTools: 6,
   defaultProfile: "support",
   includeUnprofiled: false,
-  search: {
-    enabled: true,
-    maxResults: 6,
-    exposeWhenToolCountExceeds: 12,
-    metaToolName: "search_tools",
-    strictDeferredLoading: true,
-  },
-  dynamicSelection: {
-    enabled: true,
-    maxTools: 6,
+  profiles: {
+    support: { include: ["profile:support", "category:knowledge"] },
+    workspace: { include: ["profile:workspace", "category:workspace"] },
   },
 }`;
 
diff --git a/examples/express-demo/src/index.ts b/examples/express-demo/src/index.ts
index 88ba6c7..2a28d85 100644
--- a/examples/express-demo/src/index.ts
+++ b/examples/express-demo/src/index.ts
@@ -197,43 +197,23 @@ IMPORTANT: When the user asks about YourGPT, the SDK, pricing, or any product-re
 Be helpful, concise, and accurate. If the knowledge base doesn't have the answer, say so.`,
   debug: true,
   tools: serverTools,
-  agentLoop: {
-    enabled: true,
-    maxIterations: 5,
-    debug: true,
-    toolSelection: {
-      enabled: true,
-      defaultProfile: "support",
-      includeUnprofiled: true,
-      search: {
-        enabled: true,
-        maxResults: 3,
-        exposeWhenToolCountExceeds: 1,
+  maxIterations: 5,
+  toolSearch: {
+    maxResults: 3,
+    exposeWhenExceeds: 1,
+    maxEagerTools: 2,
+    defaultProfile: "support",
+    includeUnprofiled: true,
+    profiles: {
+      support: {
+        include: ["category:knowledge", "search_knowledge_base"],
+        exclude: ["group:time"],
       },
-      dynamicSelection: {
-        enabled: true,
-        maxTools: 2,
-      },
-      profiles: {
-        support: {
-          include: ["category:knowledge", "search_knowledge_base"],
-          exclude: ["group:time"],
-        },
-        utility: {
-          include: ["category:utility", "get_current_time"],
-        },
-      },
-      nativeProviderHints: {
-        anthropic: {
-          toolChoice: "single",
-          disableParallelToolUse: true,
-        },
-        openai: {
-          toolChoice: "single",
-          parallelToolCalls: false,
-        },
+      utility: {
+        include: ["category:utility", "get_current_time"],
       },
     },
+    parallelCalls: false,
   },
 });
 
@@ -242,28 +222,179 @@ Be helpful, concise, and accurate. If the knowledge base doesn't have the answer
 // ============================================
 
 const minimalRuntime = createRuntime({
-  provider,
-  model,
+  // provider: openai,
+  provider: anthropic,
+  model: "claude-haiku-4-5",
+  // model: "gpt-5.4",
   systemPrompt: "You are a helpful AI assistant.",
+  debug: true, // enables logProviderPayload() calls in adapters
 });
 
+// ============================================
+// PER-REQUEST DEBUG LOG CAPTURE
+// Captures what the SDK sends to Anthropic/OpenAI
+// ============================================
+
+interface CapturedLog {
+  label: string;
+  payload: unknown;
+}
+
+function captureProviderLogs(fn: () => Promise<void>): Promise<CapturedLog[]> {
+  const captured: CapturedLog[] = [];
+  const origLog = console.log;
+
+  console.log = (...args: unknown[]) => {
+    origLog(...args); // still print to terminal
+    const line = args.map((a) => (typeof a === "string" ? a : "")).join(" ");
+    // SDK logs format: "[llm-sdk:anthropic] request payload\n{...json...}"
+    const match = line.match(/^\[llm-sdk:[^\]]+\] (.+?)\n([\s\S]*)$/);
+    if (match) {
+      const label = match[1].trim();
+      const raw = match[2].trim();
+      try {
+        captured.push({ label, payload: JSON.parse(raw) });
+      } catch {
+        captured.push({ label, payload: raw });
+      }
+    }
+  };
+
+  return fn()
+    .catch((err) => {
+      throw err;
+    })
+    .finally(() => {
+      console.log = origLog;
+    })
+    .then(() => captured);
+}
+
 // ============================================
 // MINIMAL COPILOT RESPONSE ENDPOINT
 // ============================================
 
+// ============================================
+// LOGGING HELPERS
+// ============================================
+
+function logRequest(endpoint: string, body: Record<string, unknown>) {
+  const { tools, messages, systemPrompt, ...rest } = body;
+  console.log(`\n${"═".repeat(60)}`);
+  console.log(`▶ REQUEST  ${endpoint}`);
+  console.log(`${"─".repeat(60)}`);
+  if (systemPrompt) {
+    console.log(`[systemPrompt]\n${systemPrompt}`);
+    console.log(`${"─".repeat(60)}`);
+  }
+  if (Array.isArray(messages)) {
+    console.log(`[messages] (${messages.length})`);
+    for (const m of messages as Record<string, unknown>[]) {
+      const role = String(m.role ?? "?").padEnd(10);
+      const content =
+        typeof m.content === "string"
+          ? m.content.slice(0, 300) + (m.content.length > 300 ? "…" : "")
+          : JSON.stringify(m.content ?? "").slice(0, 300);
+      console.log(`  ${role} ${content}`);
+    }
+    console.log(`${"─".repeat(60)}`);
+  }
+  if (Array.isArray(tools) && tools.length > 0) {
+    const toolNames = (tools as Record<string, unknown>[]).map(
+      (t) => t.name ?? "?",
+    );
+    console.log(`[tools] (${tools.length}): ${toolNames.join(", ")}`);
+    console.log(`${"─".repeat(60)}`);
+  }
+  if (Object.keys(rest).length > 0) {
+    console.log(`[config] ${JSON.stringify(rest, null, 2)}`);
+    console.log(`${"─".repeat(60)}`);
+  }
+}
+
+function logResponse(result: Record<string, unknown>) {
+  console.log(`${"─".repeat(60)}`);
+  console.log(`◀ RESPONSE`);
+  console.log(`${"─".repeat(60)}`);
+  if (result.text) {
+    const text = String(result.text);
+    console.log(
+      `[text]\n${text.slice(0, 800)}${text.length > 800 ? "\n…(truncated)" : ""}`,
+    );
+  }
+  if (Array.isArray(result.toolCalls) && result.toolCalls.length > 0) {
+    console.log(`[toolCalls]`);
+    console.log(JSON.stringify(result.toolCalls, null, 2));
+  }
+  if (result.usage) {
+    console.log(`[usage] ${JSON.stringify(result.usage)}`);
+  }
+  console.log(`${"═".repeat(60)}\n`);
+}
+
 /**
  * Minimal streaming endpoint - no tools, simple prompt
  */
 app.post("/api/copilot-response", async (req, res) => {
-  await minimalRuntime.stream(req.body).pipeToResponse(res);
+  logRequest("/api/copilot-response (stream)", req.body);
+
+  let fullText = "";
+  const stream = minimalRuntime.stream(req.body);
+  stream.on("text", (chunk: string) => {
+    fullText += chunk;
+  });
+  stream.on("error", (err: Error) => {
+    console.error(`[/api/copilot-response] Stream error:`, err.message);
+  });
+
+  await stream.pipeToResponse(res);
+
+  // Log assembled response after stream completes
+  logResponse({ text: fullText });
 });
 
 /**
  * Minimal non-streaming endpoint - no tools, simple prompt
  */
 app.post("/api/copilot-response/chat", async (req, res) => {
-  const result = await minimalRuntime.chat(req.body);
-  res.json(result);
+  logRequest("/api/copilot-response/chat", req.body);
+
+  let result: Awaited<ReturnType<typeof minimalRuntime.chat>>;
+  const { tools, messages, systemPrompt, ...restConfig } = req.body;
+
+  const providerLogs = await captureProviderLogs(async () => {
+    result = await minimalRuntime.chat(req.body);
+  });
+
+  logResponse(result! as unknown as Record<string, unknown>);
+
+  // Split captured logs into request/response pairs
+  const aiRequest =
+    providerLogs.find((l) => l.label.includes("request payload"))?.payload ??
+    null;
+  const aiResponse =
+    providerLogs.find((l) => l.label.includes("response"))?.payload ?? null;
+
+  res.json({
+    ...result!,
+    _debug: {
+      // What the SDK client sent to this server
+      sdkRequest: {
+        systemPrompt: systemPrompt ?? null,
+        messageCount: Array.isArray(messages) ? messages.length : 0,
+        messages: messages ?? [],
+        toolCount: Array.isArray(tools) ? tools.length : 0,
+        toolNames: Array.isArray(tools)
+          ? (tools as { name?: string }[]).map((t) => t.name)
+          : [],
+        config: restConfig,
+      },
+      // Raw payload this server sent to Anthropic/OpenAI
+      aiProviderRequest: aiRequest,
+      // Raw response back from Anthropic/OpenAI
+      aiProviderResponse: aiResponse,
+    },
+  });
 });
 
 // ============================================
diff --git a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
index 3e74624..63a500a 100644
--- a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
+++ b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
@@ -90,7 +90,6 @@ export class HttpTransport implements ChatTransport {
           systemPrompt: request.systemPrompt,
           llm: request.llm,
           tools: request.tools,
-          toolCatalog: request.toolCatalog,
           actions: request.actions,
           streaming: this.config.streaming,
           ...(resolved.configBody as Record<string, unknown>),
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 859f19c..3a242b2 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -13,8 +13,6 @@
 import type {
   ContextUsage,
   MessageAttachment,
-  AIResponseMode,
-  ToolResponse,
   ToolDefinition,
   ToolOptimizationConfig,
 } from "../../core";
@@ -46,89 +44,6 @@ import {
 import { SimpleChatState } from "../interfaces/ChatState";
 import { ChatContextOptimizer } from "../optimizations";
 
-// ============================================
-// AI Response Control Helper
-// ============================================
-
-/**
- * Tool definition with AI response control fields
- */
-interface ToolWithAIConfig {
-  name: string;
-  aiResponseMode?: AIResponseMode;
-  aiContext?:
-    | string
-    | ((result: ToolResponse, args: Record<string, unknown>) => string);
-}
-
-/**
- * Build tool result content for AI based on aiResponseMode and aiContext
- * This transforms client-side tool results before sending to the LLM
- *
- * Priority for responseMode: result._aiResponseMode > tool.aiResponseMode > "full"
- * Priority for context: result._aiContext > tool.aiContext > undefined
- *
- * @param result - The tool result (may include _aiResponseMode, _aiContext, _aiContent)
- * @param tool - Optional tool definition with aiResponseMode and aiContext
- * @param args - Tool arguments (for dynamic aiContext functions)
- * @returns The content string to send to the AI
- */
-function buildToolResultContentForAI(
-  result: unknown,
-  tool?: ToolWithAIConfig,
-  args?: Record<string, unknown>,
-): string {
-  if (typeof result === "string") return result;
-
-  const typedResult = result as ToolResponse | null;
-
-  // Priority: result._aiResponseMode > tool.aiResponseMode > "full"
-  const responseMode =
-    typedResult?._aiResponseMode ?? tool?.aiResponseMode ?? "full";
-
-  // Check for multimodal content
-  if (typedResult?._aiContent) {
-    return JSON.stringify(typedResult._aiContent);
-  }
-
-  // Get AI context: result._aiContext > tool.aiContext (string or function)
-  let aiContext: string | undefined = typedResult?._aiContext;
-  if (!aiContext && tool?.aiContext) {
-    aiContext =
-      typeof tool.aiContext === "function"
-        ? tool.aiContext(typedResult as ToolResponse, args ?? {})
-        : tool.aiContext;
-  }
-
-  switch (responseMode) {
-    case "none":
-      return aiContext ?? "[Result displayed to user]";
-
-    case "brief":
-      return aiContext ?? "[Tool executed successfully]";
-
-    case "full":
-    default:
-      if (aiContext) {
-        // Include context as prefix, then full data (without the control fields)
-        const {
-          _aiResponseMode,
-          _aiContext,
-          _aiContent,
-          _uiResources,
-          ...dataOnly
-        } = typedResult ?? {};
-        return `${aiContext}\n\nFull data: ${JSON.stringify(dataOnly)}`;
-      }
-      // Strip UI resources from full result - they're for rendering, not for AI
-      if (typedResult?._uiResources) {
-        const { _uiResources, ...dataOnly } = typedResult;
-        return JSON.stringify(dataOnly);
-      }
-      return JSON.stringify(result);
-  }
-}
-
 /**
  * Event types emitted by AbstractChat
  */
@@ -663,8 +578,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       threadId: this.config.threadId,
       systemPrompt,
       llm: this.config.llm,
-      tools: optimized.tools?.length ? optimized.tools : undefined,
-      toolCatalog: this.config.tools?.length
+      tools: this.config.tools?.length
         ? this.config.tools.map((tool) => ({
             name: tool.name,
             description: tool.description,
@@ -699,7 +613,6 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     this.debug("handleStreamResponse", "Starting to process stream");
 
     let chunkCount = 0;
-    let hasError = false;
     let toolCallsEmitted = false; // Guard to prevent emitting toolCalls twice
 
     // Process stream chunks
@@ -709,7 +622,6 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
 
       // Handle error chunks immediately
       if (chunk.type === "error") {
-        hasError = true;
         const error = new Error(chunk.message || "Stream error");
         this.handleError(error);
         return;
diff --git a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
index 9ea76f4..59e8b31 100644
--- a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
+++ b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
@@ -28,8 +28,6 @@ export interface ChatRequest {
   llm?: Record<string, unknown>;
   /** Tool definitions */
   tools?: unknown[];
-  /** Full client-side tool catalog for server-side selection/search */
-  toolCatalog?: unknown[];
   /** Action definitions */
   actions?: unknown[];
   /** Additional body properties */
diff --git a/packages/copilot-sdk/src/react/hooks/useTool.ts b/packages/copilot-sdk/src/react/hooks/useTool.ts
index 028833d..49e6c04 100644
--- a/packages/copilot-sdk/src/react/hooks/useTool.ts
+++ b/packages/copilot-sdk/src/react/hooks/useTool.ts
@@ -8,6 +8,8 @@ import type {
   ToolRenderProps,
   ToolSet,
   ToolInputSchema,
+  AIResponseMode,
+  ToolResultConfig,
 } from "../../core";
 import { zodToJsonSchema } from "../../core";
 import { useCopilot } from "../provider/CopilotProvider";
@@ -61,6 +63,30 @@ export 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, args: Record<string, unknown>) => string);
 }
 
 /**
@@ -137,6 +163,17 @@ export function useTool<TParams = Record<string, unknown>>(
       approvalMessage:
         config.approvalMessage as ToolDefinition["approvalMessage"],
       hidden: config.hidden,
+      deferLoading: config.deferLoading,
+      profiles: config.profiles,
+      searchKeywords: config.searchKeywords,
+      group: config.group,
+      category: config.category,
+      resultConfig: config.resultConfig,
+      title: config.title as ToolDefinition["title"],
+      executingTitle: config.executingTitle as ToolDefinition["executingTitle"],
+      completedTitle: config.completedTitle as ToolDefinition["completedTitle"],
+      aiResponseMode: config.aiResponseMode,
+      aiContext: config.aiContext as ToolDefinition["aiContext"],
     };
 
     // Register tool
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 531d697..1ea9439 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -25,6 +25,7 @@ import type {
   ActionDefinition,
   MessageAttachment,
   PermissionLevel,
+  ToolOptimizationConfig,
 } from "../../core";
 
 import type { MCPServerConfig } from "../../mcp/types";
@@ -104,6 +105,8 @@ export interface CopilotProviderProps {
   maxIterationsMessage?: string;
   /** MCP servers to connect to automatically */
   mcpServers?: MCPServerConfig[];
+  /** Optional prompt/tool optimization controls (tool profiles, context budgets, etc.) */
+  optimization?: ToolOptimizationConfig;
 }
 
 export interface CopilotContextValue {
@@ -196,6 +199,7 @@ export function CopilotProvider({
   maxIterations,
   maxIterationsMessage,
   mcpServers,
+  optimization,
 }: CopilotProviderProps) {
   // Debug logger
   const debugLog = useCallback(
@@ -261,6 +265,7 @@ export function CopilotProvider({
         debug,
         maxIterations,
         maxIterationsMessage,
+        optimization,
       },
       {
         onToolExecutionsChange: (executions) => {
diff --git a/packages/llm-sdk/src/core/stream-events.ts b/packages/llm-sdk/src/core/stream-events.ts
index 9611dad..a6bcba3 100644
--- a/packages/llm-sdk/src/core/stream-events.ts
+++ b/packages/llm-sdk/src/core/stream-events.ts
@@ -467,33 +467,6 @@ export interface ToolProfile {
   exclude?: string[];
 }
 
-export interface ToolDynamicSelectionConfig {
-  enabled?: boolean;
-  maxTools?: number;
-}
-
-export interface ToolSearchConfig {
-  enabled?: boolean;
-  /**
-   * Search execution mode.
-   * - auto: use native provider search when supported, otherwise fall back to manual search_tools
-   * - native: require provider-native search when supported, otherwise fall back to manual search_tools
-   * - manual: always use the SDK-managed search_tools fallback
-   */
-  mode?: "auto" | "native" | "manual";
-  metaToolName?: string;
-  maxResults?: number;
-  minScore?: number;
-  exposeWhenToolCountExceeds?: number;
-  /** Anthropic native tool search variant. Defaults to bm25. */
-  anthropicVariant?: "bm25" | "regex";
-  /**
-   * When true, tools marked with deferLoading stay hidden from the initial
-   * selected tool list and are only introduced after search_tools loads them.
-   */
-  strictDeferredLoading?: boolean;
-}
-
 export interface OpenAIToolSelectionHints {
   /**
    * "single" forces the selected tool when exactly one tool remains after selection.
@@ -519,19 +492,6 @@ export interface ToolNativeProviderHints {
   anthropic?: AnthropicToolSelectionHints;
 }
 
-export interface ToolSelectionConfig {
-  enabled?: boolean;
-  defaultProfile?: string;
-  profiles?: Record<string, ToolProfile>;
-  /** When false, active profiles exclude tools without explicit profile membership. */
-  includeUnprofiled?: boolean;
-  dynamicSelection?: ToolDynamicSelectionConfig;
-  /** Optional indexed search over deferred tools. */
-  search?: ToolSearchConfig;
-  /** Optional provider-native hints layered on top of local tool selection. */
-  nativeProviderHints?: ToolNativeProviderHints;
-}
-
 export interface OpenAIProviderToolOptions {
   toolChoice?:
     | "auto"
@@ -567,16 +527,6 @@ export interface ProviderToolRuntimeOptions {
   anthropic?: AnthropicProviderToolOptions;
 }
 
-/**
- * Agent loop configuration
- */
-export interface AgentLoopConfig {
-  maxIterations?: number;
-  debug?: boolean;
-  enabled?: boolean;
-  toolSelection?: ToolSelectionConfig;
-}
-
 /**
  * Web search configuration for native provider search
  *
diff --git a/packages/llm-sdk/src/index.ts b/packages/llm-sdk/src/index.ts
index cc22c30..507f1d7 100644
--- a/packages/llm-sdk/src/index.ts
+++ b/packages/llm-sdk/src/index.ts
@@ -190,14 +190,10 @@ export type {
   UnifiedToolCall,
   UnifiedToolResult,
   ToolExecution,
-  AgentLoopConfig,
   ToolProfile,
-  ToolDynamicSelectionConfig,
-  ToolSearchConfig,
   OpenAIToolSelectionHints,
   AnthropicToolSelectionHints,
   ToolNativeProviderHints,
-  ToolSelectionConfig,
   OpenAIProviderToolOptions,
   AnthropicProviderToolOptions,
   ProviderToolRuntimeOptions,
diff --git a/packages/llm-sdk/src/server/agent-loop.ts b/packages/llm-sdk/src/server/agent-loop.ts
index 0363770..959a759 100644
--- a/packages/llm-sdk/src/server/agent-loop.ts
+++ b/packages/llm-sdk/src/server/agent-loop.ts
@@ -16,7 +16,6 @@ import type {
   UnifiedToolCall,
   UnifiedToolResult,
   ToolResponse,
-  AgentLoopConfig,
   Message,
 } from "../core/stream-events";
 import type { AIProvider } from "../providers/types";
@@ -27,6 +26,7 @@ import {
   searchTools,
   selectTools,
   shouldExposeToolSearch,
+  type InternalToolSelectionConfig,
 } from "./tool-selection";
 
 // ========================================
@@ -54,8 +54,12 @@ export interface AgentLoopOptions {
   provider: AIProvider;
   /** Abort signal for cancellation */
   signal?: AbortSignal;
-  /** Loop configuration */
-  config?: AgentLoopConfig;
+  /** Max agent loop iterations (default: 20) */
+  maxIterations?: number;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Internal tool selection config (from resolveEffectiveToolSelectionConfig) */
+  toolSelectionConfig?: InternalToolSelectionConfig;
   /** Optional active tool profile for selective loading. */
   toolProfile?: string;
   /**
@@ -114,18 +118,19 @@ export async function* runAgentLoop(
     systemPrompt,
     provider,
     signal,
-    config,
+    maxIterations: optMaxIterations,
+    debug: optDebug,
+    toolSelectionConfig,
     toolProfile,
     callLLM,
     executeServerTool,
     waitForClientToolResult,
   } = options;
 
-  const maxIterations = config?.maxIterations ?? DEFAULT_MAX_ITERATIONS;
-  const debug = config?.debug ?? false;
+  const maxIterations = optMaxIterations ?? DEFAULT_MAX_ITERATIONS;
+  const debug = optDebug ?? false;
   const formatter = getFormatter(provider.name);
-  const toolSearchMetaToolName =
-    config?.toolSelection?.search?.metaToolName ?? "search_tools";
+  const toolSearchMetaToolName = "search_tools";
 
   // Separate server and client tools
   const serverTools = tools.filter((t) => t.location === "server");
@@ -147,7 +152,7 @@ export async function* runAgentLoop(
       availableToolCount: allTools.length,
       serverToolCount: serverTools.length,
       clientToolCount: clientTools.length,
-      activeProfile: toolProfile ?? config?.toolSelection?.defaultProfile,
+      activeProfile: toolProfile ?? toolSelectionConfig?.defaultProfile,
       maxIterations,
     });
   }
@@ -176,14 +181,13 @@ export async function* runAgentLoop(
     const selectedTools = selectTools({
       tools: allTools,
       messages,
-      config: config?.toolSelection,
+      config: toolSelectionConfig,
       activeProfile: toolProfile,
       forceIncludeNames: [...loadedToolNames],
     });
     const toolSearchTool = shouldExposeToolSearch({
       tools: allTools,
-      selectedTools,
-      config: config?.toolSelection,
+      config: toolSelectionConfig,
     })
       ? ({
           name: toolSearchMetaToolName,
@@ -212,7 +216,7 @@ export async function* runAgentLoop(
             const results = searchTools({
               tools: allTools,
               query,
-              config: config?.toolSelection,
+              config: toolSelectionConfig,
               activeProfile: toolProfile,
               limit,
               excludeNames: selectedTools.map((tool) => tool.name),
@@ -232,7 +236,7 @@ export async function* runAgentLoop(
     const providerToolOptions = buildProviderToolOptions({
       providerName: provider.name,
       selectedTools: effectiveSelectedTools,
-      config: config?.toolSelection,
+      config: toolSelectionConfig,
       metaToolName: toolSearchMetaToolName,
     });
     const providerTools = formatter.transformTools(effectiveSelectedTools);
diff --git a/packages/llm-sdk/src/server/index.ts b/packages/llm-sdk/src/server/index.ts
index c7258fc..9ed321f 100644
--- a/packages/llm-sdk/src/server/index.ts
+++ b/packages/llm-sdk/src/server/index.ts
@@ -2,6 +2,7 @@
 export { Runtime, createRuntime } from "./runtime";
 export type {
   RuntimeConfig,
+  ToolSearchConfig,
   ChatRequest,
   ActionRequest,
   RequestContext,
diff --git a/packages/llm-sdk/src/server/runtime.ts b/packages/llm-sdk/src/server/runtime.ts
index 23c0c52..48a63ac 100644
--- a/packages/llm-sdk/src/server/runtime.ts
+++ b/packages/llm-sdk/src/server/runtime.ts
@@ -33,6 +33,7 @@ import {
   searchTools,
   selectTools,
   shouldExposeToolSearch,
+  type InternalToolSelectionConfig,
 } from "./tool-selection";
 
 type ToolSearchState = {
@@ -345,7 +346,6 @@ export class Runtime {
         console.log("[Copilot SDK] Request:", {
           messageCount: body.messages?.length ?? 0,
           toolCount: body.tools?.length ?? 0,
-          toolCatalogCount: body.toolCatalog?.length ?? 0,
           hasSystemPrompt: Boolean(body.systemPrompt),
           threadId: body.threadId,
           streaming: body.streaming !== false,
@@ -356,10 +356,10 @@ export class Runtime {
       // Create abort controller from request signal
       const signal = request.signal;
 
-      // Use agent loop if tools are present or explicitly enabled
+      // Use agent loop if tools are present
       const hasTools =
         (body.tools && body.tools.length > 0) || this.tools.size > 0;
-      const useAgentLoop = hasTools || this.config.agentLoop?.enabled;
+      const useAgentLoop = hasTools;
 
       // NON-STREAMING: Return JSON response instead of SSE
       if (body.streaming === false) {
@@ -683,17 +683,41 @@ export class Runtime {
     return undefined;
   }
 
+  /**
+   * Resolve effective tool selection config for a request.
+   */
+  private resolveEffectiveToolSelectionConfig(
+    request: ChatRequest,
+  ): InternalToolSelectionConfig | undefined {
+    const toolSearch =
+      "toolSearch" in this.config ? this.config.toolSearch : undefined;
+
+    const hasDeferredServerTool = [...this.tools.values()].some(
+      (t) => t.deferLoading,
+    );
+    const hasDeferredInRequest = request.tools?.some((t) => t.deferLoading);
+
+    if (!hasDeferredServerTool && !hasDeferredInRequest && !toolSearch) {
+      return undefined;
+    }
+
+    return {
+      maxEagerTools: toolSearch?.maxEagerTools ?? 20,
+      maxResults: toolSearch?.maxResults ?? 8,
+      exposeWhenExceeds: toolSearch?.exposeWhenExceeds ?? 8,
+      toolChoice: toolSearch?.toolChoice,
+      parallelCalls: toolSearch?.parallelCalls,
+      defaultProfile: toolSearch?.defaultProfile,
+      profiles: toolSearch?.profiles,
+      includeUnprofiled: toolSearch?.includeUnprofiled,
+    };
+  }
+
   private collectToolsForRequest(request: ChatRequest): ToolDefinition[] {
     const allTools: ToolDefinition[] = [...this.tools.values()];
 
-    const clientTools =
-      this.config.agentLoop?.toolSelection?.enabled &&
-      request.toolCatalog?.length
-        ? request.toolCatalog
-        : request.tools;
-
-    if (clientTools) {
-      for (const tool of clientTools) {
+    if (request.tools) {
+      for (const tool of request.tools) {
         allTools.push({
           name: tool.name,
           description: tool.description,
@@ -719,17 +743,19 @@ export class Runtime {
     return selectTools({
       tools: allTools,
       messages: request.messages,
-      config: this.config.agentLoop?.toolSelection,
+      config: this.resolveEffectiveToolSelectionConfig(request),
       activeProfile: request.toolProfile,
       forceIncludeNames: toolSearchState?.loadedToolNames,
     });
   }
 
-  private resolveNativeToolSearchForRequest(): NativeToolSearchState {
+  private resolveNativeToolSearchForRequest(
+    request: ChatRequest,
+  ): NativeToolSearchState {
     return resolveNativeToolSearch({
       providerName: this.adapter.provider,
       modelName: this.getModel(),
-      config: this.config.agentLoop?.toolSelection,
+      config: this.resolveEffectiveToolSelectionConfig(request),
     });
   }
 
@@ -739,26 +765,28 @@ export class Runtime {
   ): ToolDefinition[] {
     return filterToolsByProfile({
       tools: allTools,
-      config: this.config.agentLoop?.toolSelection,
+      config: this.resolveEffectiveToolSelectionConfig(request),
       activeProfile: request.toolProfile,
     });
   }
 
-  private buildProviderToolOptionsForRequest(selectedTools: ToolDefinition[]) {
+  private buildProviderToolOptionsForRequest(
+    selectedTools: ToolDefinition[],
+    request: ChatRequest,
+  ) {
     return buildProviderToolOptions({
       providerName: this.adapter.provider,
       modelName: this.getModel(),
       selectedTools,
-      config: this.config.agentLoop?.toolSelection,
+      config: this.resolveEffectiveToolSelectionConfig(request),
       metaToolName: this.getToolSearchMetaToolName(),
     });
   }
 
   private getToolSearchMetaToolName(): string {
-    return (
-      this.config.agentLoop?.toolSelection?.search?.metaToolName ??
-      "search_tools"
-    );
+    const toolSearch =
+      "toolSearch" in this.config ? this.config.toolSearch : undefined;
+    return toolSearch?.name ?? "search_tools";
   }
 
   private createToolSearchTool(
@@ -769,8 +797,7 @@ export class Runtime {
     if (
       !shouldExposeToolSearch({
         tools: allTools,
-        selectedTools,
-        config: this.config.agentLoop?.toolSelection,
+        config: this.resolveEffectiveToolSelectionConfig(request),
       })
     ) {
       return null;
@@ -782,6 +809,7 @@ export class Runtime {
     return {
       name: toolName,
       description:
+        ("toolSearch" in this.config && this.config.toolSearch?.description) ||
         "Search available deferred tools and load the most relevant ones for the next step when the right tool is not currently exposed.",
       location: "server",
       hidden: true,
@@ -804,18 +832,16 @@ export class Runtime {
         const results = searchTools({
           tools: allTools,
           query: args.query,
-          config: this.config.agentLoop?.toolSelection,
+          config: this.resolveEffectiveToolSelectionConfig(request),
           activeProfile: request.toolProfile,
           limit: args.limit,
           excludeNames: excludedNames,
         });
 
-        if (this.config.debug || this.config.agentLoop?.debug) {
+        if (this.config.debug) {
           console.log("[Copilot SDK] search_tools result:", {
             query: args.query,
-            activeProfile:
-              request.toolProfile ??
-              this.config.agentLoop?.toolSelection?.defaultProfile,
+            activeProfile: request.toolProfile,
             selectedToolCount: selectedTools.length,
             catalogCount: allTools.length,
             loadedTools: results.map((result) => result.name),
@@ -893,7 +919,7 @@ export class Runtime {
     _httpRequest?: Request,
     _toolSearchState?: ToolSearchState,
   ): AsyncGenerator<StreamEvent> {
-    const debug = this.config.debug || this.config.agentLoop?.debug;
+    const debug = this.config.debug;
 
     // Check if non-streaming mode is requested
     // Use non-streaming for better comparison with original studio-ai behavior
@@ -917,10 +943,10 @@ export class Runtime {
 
     // Track new messages created during this request
     const newMessages: DoneEventMessage[] = _accumulatedMessages || [];
-    const maxIterations = this.config.agentLoop?.maxIterations || 20;
+    const maxIterations = this.config.maxIterations ?? 20;
 
     const allTools = this.collectToolsForRequest(request);
-    const nativeToolSearch = this.resolveNativeToolSearchForRequest();
+    const nativeToolSearch = this.resolveNativeToolSearchForRequest(request);
     const nativeToolCatalog = nativeToolSearch
       ? this.buildNativeToolCatalogForRequest(request, allTools)
       : null;
@@ -937,6 +963,7 @@ export class Runtime {
         : selectedTools;
     const providerToolOptions = this.buildProviderToolOptionsForRequest(
       effectiveSelectedTools,
+      request,
     );
     const selectedToolMap = new Map(
       effectiveSelectedTools.map((tool) => [tool.name, tool] as const),
@@ -950,9 +977,7 @@ export class Runtime {
         console.log(
           `[Copilot SDK] Tool selection active: ${effectiveSelectedTools.length}/${allTools.length} tools`,
           {
-            activeProfile:
-              request.toolProfile ??
-              this.config.agentLoop?.toolSelection?.defaultProfile,
+            activeProfile: request.toolProfile,
             nativeSearch: nativeToolSearch?.provider ?? null,
           },
         );
@@ -1343,8 +1368,8 @@ export class Runtime {
     _toolSearchState?: ToolSearchState,
   ): AsyncGenerator<StreamEvent> {
     const newMessages: DoneEventMessage[] = _accumulatedMessages || [];
-    const debug = this.config.debug || this.config.agentLoop?.debug;
-    const maxIterations = this.config.agentLoop?.maxIterations || 20;
+    const debug = this.config.debug;
+    const maxIterations = this.config.maxIterations ?? 20;
     // Track accumulated usage across iterations (for onFinish callback)
     let accumulatedUsage: {
       prompt_tokens: number;
@@ -1353,7 +1378,7 @@ export class Runtime {
     } = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
 
     const allTools = this.collectToolsForRequest(request);
-    const nativeToolSearch = this.resolveNativeToolSearchForRequest();
+    const nativeToolSearch = this.resolveNativeToolSearchForRequest(request);
     let toolSearchState = _toolSearchState;
 
     // Build system prompt
@@ -1421,6 +1446,7 @@ export class Runtime {
           : selectedTools;
       const providerToolOptions = this.buildProviderToolOptionsForRequest(
         effectiveSelectedTools,
+        request,
       );
       const selectedToolMap = new Map(
         effectiveSelectedTools.map((tool) => [tool.name, tool] as const),
diff --git a/packages/llm-sdk/src/server/tool-selection.ts b/packages/llm-sdk/src/server/tool-selection.ts
index a12cd3a..616e423 100644
--- a/packages/llm-sdk/src/server/tool-selection.ts
+++ b/packages/llm-sdk/src/server/tool-selection.ts
@@ -1,10 +1,9 @@
 import type {
+  ToolDefinition,
+  ToolProfile,
   AnthropicProviderToolOptions,
   OpenAIProviderToolOptions,
   ProviderToolRuntimeOptions,
-  ToolDefinition,
-  ToolSearchConfig,
-  ToolSelectionConfig,
 } from "../core/stream-events";
 
 type ToolSelectionMessage = {
@@ -29,8 +28,25 @@ export interface ResolvedNativeToolSearch {
   useResponsesApi?: boolean;
 }
 
+/**
+ * Internal tool selection configuration.
+ * Built by resolveEffectiveToolSelectionConfig in runtime.ts.
+ * Not part of the public API.
+ */
+export interface InternalToolSelectionConfig {
+  maxEagerTools: number;
+  maxResults: number;
+  exposeWhenExceeds: number;
+  defaultProfile?: string;
+  profiles?: Record<string, ToolProfile>;
+  includeUnprofiled?: boolean;
+  toolChoice?: "auto" | "required";
+  parallelCalls?: boolean;
+}
+
 const BM25_K1 = 1.2;
 const BM25_B = 0.75;
+const MIN_SCORE = 0.1;
 
 function unique<T>(values: T[]): T[] {
   return [...new Set(values)];
@@ -45,12 +61,8 @@ function tokenize(text: string): string[] {
 }
 
 function stringifyContent(content: unknown): string {
-  if (typeof content === "string") {
-    return content;
-  }
-  if (!content) {
-    return "";
-  }
+  if (typeof content === "string") return content;
+  if (!content) return "";
   try {
     return JSON.stringify(content);
   } catch {
@@ -60,11 +72,9 @@ function stringifyContent(content: unknown): string {
 
 function buildToolQuery(messages: ToolSelectionMessage[]): string {
   return messages
-    .filter(
-      (message) => message.role === "user" || message.role === "assistant",
-    )
+    .filter((m) => m.role === "user" || m.role === "assistant")
     .slice(-3)
-    .map((message) => stringifyContent(message.content))
+    .map((m) => stringifyContent(m.content))
     .filter(Boolean)
     .join(" ");
 }
@@ -88,16 +98,9 @@ function matchesSelector(
   activeProfile?: string,
 ): boolean {
   const normalized = selector.trim().toLowerCase();
-  if (!normalized) {
-    return false;
-  }
-
-  if (normalized === "*" || normalized === "all") {
-    return true;
-  }
-  if (normalized === tool.name.toLowerCase()) {
-    return true;
-  }
+  if (!normalized) return false;
+  if (normalized === "*" || normalized === "all") return true;
+  if (normalized === tool.name.toLowerCase()) return true;
   if (normalized.startsWith("group:")) {
     return (tool.group ?? "").toLowerCase() === normalized.slice(6);
   }
@@ -106,12 +109,12 @@ function matchesSelector(
   }
   if (normalized.startsWith("profile:")) {
     return (tool.profiles ?? [])
-      .map((value) => value.toLowerCase())
+      .map((v) => v.toLowerCase())
       .includes(normalized.slice(8));
   }
   if (activeProfile && normalized === activeProfile.toLowerCase()) {
     return (tool.profiles ?? [])
-      .map((value) => value.toLowerCase())
+      .map((v) => v.toLowerCase())
       .includes(normalized);
   }
   return false;
@@ -135,18 +138,12 @@ function scoreTool(
     .toLowerCase();
 
   let score = tool.deferLoading ? 0 : 2;
-  if (activeProfile && tool.profiles?.includes(activeProfile)) {
-    score += 2;
-  }
+  if (activeProfile && tool.profiles?.includes(activeProfile)) score += 2;
 
   for (const token of queryTokens) {
-    if (tool.name.toLowerCase() === token) {
-      score += 6;
-    } else if (tool.name.toLowerCase().includes(token)) {
-      score += 4;
-    } else if (haystack.includes(token)) {
-      score += 2;
-    }
+    if (tool.name.toLowerCase() === token) score += 6;
+    else if (tool.name.toLowerCase().includes(token)) score += 4;
+    else if (haystack.includes(token)) score += 2;
   }
 
   return score;
@@ -154,14 +151,12 @@ function scoreTool(
 
 export function filterToolsByProfile(params: {
   tools: ToolDefinition[];
-  config?: ToolSelectionConfig;
+  config?: InternalToolSelectionConfig;
   activeProfile?: string;
 }): ToolDefinition[] {
   const available = params.tools.filter((tool) => tool.available !== false);
   const config = params.config;
-  if (!config?.enabled) {
-    return available;
-  }
+  if (!config) return available;
 
   const activeProfile = params.activeProfile ?? config.defaultProfile;
   const includeUnprofiled = config.includeUnprofiled ?? true;
@@ -178,9 +173,7 @@ export function filterToolsByProfile(params: {
     );
   } else if (activeProfile) {
     filtered = filtered.filter((tool) => {
-      if (tool.profiles?.length) {
-        return tool.profiles.includes(activeProfile);
-      }
+      if (tool.profiles?.length) return tool.profiles.includes(activeProfile);
       return includeUnprofiled;
     });
   }
@@ -209,13 +202,9 @@ function calculateBM25Score(
   const docLength = Math.max(1, tokens.length);
 
   let score = 0;
-
   for (const term of queryTerms) {
-    const termFreq = tokens.filter((token) => token === term).length;
-    if (termFreq === 0) {
-      continue;
-    }
-
+    const termFreq = tokens.filter((t) => t === term).length;
+    if (termFreq === 0) continue;
     const termIDF = idf.get(term) ?? 0;
     const numerator = termFreq * (BM25_K1 + 1);
     const denominator =
@@ -225,16 +214,11 @@ function calculateBM25Score(
 
   const nameLower = tool.name.toLowerCase();
   for (const term of queryTerms) {
-    if (nameLower === term) {
-      score += 3;
-    } else if (nameLower.includes(term)) {
-      score += 1.5;
-    }
+    if (nameLower === term) score += 3;
+    else if (nameLower.includes(term)) score += 1.5;
   }
 
-  if (activeProfile && tool.profiles?.includes(activeProfile)) {
-    score += 0.75;
-  }
+  if (activeProfile && tool.profiles?.includes(activeProfile)) score += 0.75;
 
   return score;
 }
@@ -242,7 +226,7 @@ function calculateBM25Score(
 export function selectTools(params: {
   tools: ToolDefinition[];
   messages: ToolSelectionMessage[];
-  config?: ToolSelectionConfig;
+  config?: InternalToolSelectionConfig;
   activeProfile?: string;
   forceIncludeNames?: string[];
 }): ToolDefinition[] {
@@ -252,97 +236,60 @@ export function selectTools(params: {
     config,
     activeProfile: params.activeProfile,
   });
-  if (!config?.enabled) {
-    return available;
-  }
+
+  // No config means no selection — return all available tools
+  if (!config) return available;
+
   const activeProfile = params.activeProfile ?? config.defaultProfile;
   const forceIncludeNames = new Set(params.forceIncludeNames ?? []);
-  let filtered = available;
-  const strictDeferredLoading =
-    config.search?.enabled && config.search.strictDeferredLoading === true;
 
-  if (strictDeferredLoading) {
-    filtered = filtered.filter(
-      (tool) => !tool.deferLoading || forceIncludeNames.has(tool.name),
-    );
-  }
-
-  if (!config.dynamicSelection?.enabled) {
-    if (forceIncludeNames.size === 0) {
-      return filtered;
-    }
-    const merged = new Map(filtered.map((tool) => [tool.name, tool]));
-    for (const tool of available) {
-      if (forceIncludeNames.has(tool.name)) {
-        merged.set(tool.name, tool);
-      }
-    }
-    return [...merged.values()];
-  }
+  // Always strip deferred tools from initial context (they're loaded via search)
+  let filtered = available.filter(
+    (tool) => !tool.deferLoading || forceIncludeNames.has(tool.name),
+  );
 
-  if (filtered.length === 0) {
-    return filtered;
-  }
+  if (filtered.length === 0) return filtered;
 
-  const maxTools = Math.max(
-    1,
-    Math.min(
-      config.dynamicSelection.maxTools ?? filtered.length,
-      filtered.length,
-    ),
-  );
+  const maxTools = Math.max(1, Math.min(config.maxEagerTools, filtered.length));
   const queryTokens = unique(tokenize(buildToolQuery(params.messages)));
-  const ranked = [...filtered].sort((left, right) => {
-    const scoreDiff =
-      scoreTool(right, queryTokens, activeProfile) -
-      scoreTool(left, queryTokens, activeProfile);
-    if (scoreDiff !== 0) {
-      return scoreDiff;
-    }
-    return left.name.localeCompare(right.name);
+  const ranked = [...filtered].sort((a, b) => {
+    const diff =
+      scoreTool(b, queryTokens, activeProfile) -
+      scoreTool(a, queryTokens, activeProfile);
+    return diff !== 0 ? diff : a.name.localeCompare(b.name);
   });
 
-  if (forceIncludeNames.size === 0) {
-    return ranked.slice(0, maxTools);
-  }
+  if (forceIncludeNames.size === 0) return ranked.slice(0, maxTools);
 
-  const forced = ranked.filter((tool) => forceIncludeNames.has(tool.name));
-  const others = ranked.filter((tool) => !forceIncludeNames.has(tool.name));
-  const remainingSlots = Math.max(0, maxTools - forced.length);
-  return [...forced, ...others.slice(0, remainingSlots)];
+  const forced = ranked.filter((t) => forceIncludeNames.has(t.name));
+  const others = ranked.filter((t) => !forceIncludeNames.has(t.name));
+  const remaining = Math.max(0, maxTools - forced.length);
+  return [...forced, ...others.slice(0, remaining)];
 }
 
 export function searchTools(params: {
   tools: ToolDefinition[];
   query: string;
-  config?: ToolSelectionConfig;
+  config?: InternalToolSelectionConfig;
   activeProfile?: string;
   limit?: number;
   excludeNames?: string[];
   includeSelected?: boolean;
 }): ToolSearchMatch[] {
   const queryTerms = unique(tokenize(params.query));
-  if (queryTerms.length === 0) {
-    return [];
-  }
+  if (queryTerms.length === 0) return [];
 
   const candidates = filterToolsByProfile({
     tools: params.tools,
     config: params.config,
     activeProfile: params.activeProfile,
   }).filter((tool) => {
-    if ((params.excludeNames ?? []).includes(tool.name)) {
-      return false;
-    }
-    if (params.includeSelected) {
-      return true;
-    }
+    if ((params.excludeNames ?? []).includes(tool.name)) return false;
+    if (params.includeSelected) return true;
     return tool.deferLoading === true;
   });
 
-  if (candidates.length === 0) {
-    return [];
-  }
+  if (candidates.length === 0) return [];
 
   const docs = candidates.map((tool) => tokenize(buildSearchText(tool)));
   const avgDocLength =
@@ -361,11 +308,7 @@ export function searchTools(params: {
     );
   }
 
-  const minScore = params.config?.search?.minScore ?? 0.1;
-  const limit = Math.max(
-    1,
-    params.limit ?? params.config?.search?.maxResults ?? 5,
-  );
+  const limit = Math.max(1, params.limit ?? params.config?.maxResults ?? 8);
   const activeProfile = params.activeProfile ?? params.config?.defaultProfile;
 
   return candidates
@@ -379,13 +322,10 @@ export function searchTools(params: {
         activeProfile,
       ),
     }))
-    .filter((entry) => entry.score >= minScore)
-    .sort((left, right) => {
-      const scoreDiff = right.score - left.score;
-      if (scoreDiff !== 0) {
-        return scoreDiff;
-      }
-      return left.tool.name.localeCompare(right.tool.name);
+    .filter((entry) => entry.score >= MIN_SCORE)
+    .sort((a, b) => {
+      const diff = b.score - a.score;
+      return diff !== 0 ? diff : a.tool.name.localeCompare(b.tool.name);
     })
     .slice(0, limit)
     .map(({ tool, score }) => ({
@@ -406,14 +346,7 @@ function normalizeModelName(modelName?: string): string {
 
 export function supportsAnthropicNativeToolSearch(modelName?: string): boolean {
   const model = normalizeModelName(modelName);
-  if (!model) {
-    return false;
-  }
-
-  if (model.includes("haiku")) {
-    return false;
-  }
-
+  if (!model || model.includes("haiku")) return false;
   return (
     /(?:^|[-_ ])(?:sonnet|opus)[-_ ]?4(?:$|[-_. ])/.test(model) ||
     /claude[-_ ](?:sonnet|opus)[-_ ]?4/.test(model) ||
@@ -423,122 +356,79 @@ export function supportsAnthropicNativeToolSearch(modelName?: string): boolean {
 
 export function supportsOpenAINativeToolSearch(modelName?: string): boolean {
   const model = normalizeModelName(modelName);
-  if (!model) {
-    return false;
-  }
-
+  if (!model) return false;
   const match = model.match(/^gpt-5(?:[._-](\d+))?(?:$|[._-])/);
-  if (!match) {
-    return false;
-  }
-
+  if (!match) return false;
   const minorVersion = match[1] ? Number.parseInt(match[1], 10) : Number.NaN;
-  if (!Number.isFinite(minorVersion)) {
-    return false;
-  }
-
+  if (!Number.isFinite(minorVersion)) return false;
   return minorVersion >= 4;
 }
 
 export function resolveNativeToolSearch(params: {
   providerName: string;
   modelName?: string;
-  config?: ToolSelectionConfig;
+  config?: InternalToolSelectionConfig;
 }): ResolvedNativeToolSearch | null {
-  const searchConfig = params.config?.search;
-  if (!searchConfig?.enabled) {
-    return null;
-  }
-
-  const mode = searchConfig.mode ?? "auto";
-  if (mode === "manual") {
-    return null;
-  }
+  // No config means no deferred tools — no need for native search
+  if (!params.config) return null;
 
   if (
     params.providerName === "anthropic" &&
     supportsAnthropicNativeToolSearch(params.modelName)
   ) {
-    return {
-      provider: "anthropic",
-      variant: searchConfig.anthropicVariant ?? "bm25",
-    };
+    return { provider: "anthropic", variant: "bm25" };
   }
 
   if (
     params.providerName === "openai" &&
     supportsOpenAINativeToolSearch(params.modelName)
   ) {
-    return {
-      provider: "openai",
-      useResponsesApi: true,
-    };
+    return { provider: "openai", useResponsesApi: true };
   }
 
-  return mode === "native" ? null : null;
+  return null;
 }
 
 export function shouldExposeToolSearch(params: {
   tools: ToolDefinition[];
-  selectedTools: ToolDefinition[];
-  config?: ToolSelectionConfig;
+  config?: InternalToolSelectionConfig;
 }): boolean {
-  const searchConfig = params.config?.search;
-  if (!searchConfig?.enabled) {
-    return false;
-  }
-
-  const deferredCount = params.tools.filter((tool) => tool.deferLoading).length;
-  if (deferredCount === 0) {
-    return false;
-  }
-
-  const threshold = searchConfig.exposeWhenToolCountExceeds ?? 8;
-  return (
-    params.tools.length >= threshold ||
-    deferredCount > Math.max(0, params.selectedTools.length)
-  );
+  if (!params.config) return false;
+  const deferredCount = params.tools.filter((t) => t.deferLoading).length;
+  if (deferredCount === 0) return false;
+  return params.tools.length >= params.config.exposeWhenExceeds;
 }
 
 export function buildProviderToolOptions(params: {
   providerName: string;
   modelName?: string;
   selectedTools: ToolDefinition[];
-  config?: ToolSelectionConfig;
+  config?: InternalToolSelectionConfig;
   metaToolName?: string;
 }): ProviderToolRuntimeOptions | undefined {
-  const nativeHints = params.config?.nativeProviderHints;
+  const { toolChoice, parallelCalls } = params.config ?? {};
   const resolvedNativeSearch = resolveNativeToolSearch({
     providerName: params.providerName,
     modelName: params.modelName,
     config: params.config,
   });
-  const effectiveTools = params.metaToolName
-    ? params.selectedTools.filter((tool) => tool.name !== params.metaToolName)
-    : params.selectedTools;
 
   if (params.providerName === "openai") {
-    const hints = nativeHints?.openai;
-    if (!hints && !resolvedNativeSearch) {
+    if (
+      toolChoice === undefined &&
+      parallelCalls === undefined &&
+      !resolvedNativeSearch
+    ) {
       return undefined;
     }
-
-    let toolChoice: OpenAIProviderToolOptions["toolChoice"];
-    if (hints?.toolChoice === "required") {
-      toolChoice = "required";
-    } else if (hints?.toolChoice === "single" && effectiveTools.length === 1) {
-      toolChoice = {
-        type: "function",
-        name: effectiveTools[0].name,
-      };
-    } else if (hints?.toolChoice === "auto") {
-      toolChoice = "auto";
-    }
+    let oaiToolChoice: OpenAIProviderToolOptions["toolChoice"];
+    if (toolChoice === "required") oaiToolChoice = "required";
+    else if (toolChoice === "auto") oaiToolChoice = "auto";
 
     return {
       openai: {
-        toolChoice,
-        parallelToolCalls: hints?.parallelToolCalls,
+        toolChoice: oaiToolChoice,
+        parallelToolCalls: parallelCalls,
         nativeToolSearch:
           resolvedNativeSearch?.provider === "openai"
             ? {
@@ -551,33 +441,26 @@ export function buildProviderToolOptions(params: {
   }
 
   if (params.providerName === "anthropic") {
-    const hints = nativeHints?.anthropic;
-    if (!hints && !resolvedNativeSearch) {
+    if (
+      toolChoice === undefined &&
+      parallelCalls === undefined &&
+      !resolvedNativeSearch
+    ) {
       return undefined;
     }
-
-    let toolChoice: AnthropicProviderToolOptions["toolChoice"];
-    if (hints?.toolChoice === "any") {
-      toolChoice = "any";
-    } else if (hints?.toolChoice === "single" && effectiveTools.length === 1) {
-      toolChoice = {
-        type: "tool",
-        name: effectiveTools[0].name,
-      };
-    } else if (hints?.toolChoice === "auto") {
-      toolChoice = "auto";
-    }
+    let anthropicToolChoice: AnthropicProviderToolOptions["toolChoice"];
+    // "required" maps to Anthropic's "any" (force tool use)
+    if (toolChoice === "required") anthropicToolChoice = "any";
+    else if (toolChoice === "auto") anthropicToolChoice = "auto";
 
     return {
       anthropic: {
-        toolChoice,
-        disableParallelToolUse: hints?.disableParallelToolUse,
+        toolChoice: anthropicToolChoice,
+        // parallelCalls: false → disableParallelToolUse: true
+        disableParallelToolUse: parallelCalls === false ? true : undefined,
         nativeToolSearch:
           resolvedNativeSearch?.provider === "anthropic"
-            ? {
-                enabled: true,
-                variant: resolvedNativeSearch.variant ?? "bm25",
-              }
+            ? { enabled: true, variant: resolvedNativeSearch.variant ?? "bm25" }
             : undefined,
       },
     };
diff --git a/packages/llm-sdk/src/server/types.ts b/packages/llm-sdk/src/server/types.ts
index 7ca15ed..a438de4 100644
--- a/packages/llm-sdk/src/server/types.ts
+++ b/packages/llm-sdk/src/server/types.ts
@@ -2,12 +2,67 @@ import type {
   ActionDefinition,
   KnowledgeBaseConfig,
   ToolDefinition,
-  AgentLoopConfig,
+  ToolProfile,
   WebSearchConfig,
 } from "../core/stream-events";
 import type { LLMAdapter } from "../adapters";
 import type { AIProvider } from "../providers/types";
 
+/**
+ * Tool search/discovery configuration.
+ * Controls the `search_tools` meta-tool that lets the AI discover deferred tools.
+ *
+ * Tools marked with `deferLoading: true` are excluded from the default context
+ * and loaded on demand when the AI calls `search_tools`.
+ */
+export interface ToolSearchConfig {
+  /**
+   * Custom description for the search_tools meta-tool shown to the AI.
+   */
+  description?: string;
+  /**
+   * Custom name for the search meta-tool (default: "search_tools").
+   */
+  name?: string;
+  /**
+   * Max eager tools sent to the AI per request (default: 20).
+   * Tools beyond this limit are deferred and discoverable via search.
+   */
+  maxEagerTools?: number;
+  /**
+   * Max deferred tools returned per search query (default: 8).
+   */
+  maxResults?: number;
+  /**
+   * Expose the search tool when total tool count exceeds this number (default: 8).
+   */
+  exposeWhenExceeds?: number;
+  /**
+   * How the AI should choose tools.
+   * - "auto": model decides whether to use a tool (default)
+   * - "required": model must call at least one tool
+   */
+  toolChoice?: "auto" | "required";
+  /**
+   * Allow the model to call multiple tools in a single turn (default: true).
+   * Set false to force one tool call at a time.
+   */
+  parallelCalls?: boolean;
+  /**
+   * Default active profile when none is provided in the request.
+   */
+  defaultProfile?: string;
+  /**
+   * Named tool profiles with include/exclude selectors.
+   * Profiles filter which tools are visible to the AI per request.
+   */
+  profiles?: Record<string, ToolProfile>;
+  /**
+   * When a profile is active, include tools with no profile membership (default: true).
+   */
+  includeUnprofiled?: boolean;
+}
+
 /**
  * Runtime configuration with adapter (advanced usage)
  */
@@ -20,8 +75,15 @@ export interface RuntimeConfigWithAdapter {
   actions?: ActionDefinition[];
   /** Available tools (new - supports location: server/client) */
   tools?: ToolDefinition[];
-  /** Agent loop configuration */
-  agentLoop?: AgentLoopConfig;
+  /**
+   * Max agent loop iterations before stopping (default: 20).
+   */
+  maxIterations?: number;
+  /**
+   * Configure deferred tool discovery. Tools with `deferLoading: true` are
+   * excluded from the default context and discoverable via the search meta-tool.
+   */
+  toolSearch?: ToolSearchConfig;
   /** Knowledge base configuration (enables search_knowledge tool) */
   knowledgeBase?: KnowledgeBaseConfig;
   /** Enable debug logging */
@@ -60,8 +122,15 @@ export interface RuntimeConfigWithProvider {
   actions?: ActionDefinition[];
   /** Available tools (new - supports location: server/client) */
   tools?: ToolDefinition[];
-  /** Agent loop configuration */
-  agentLoop?: AgentLoopConfig;
+  /**
+   * Max agent loop iterations before stopping (default: 20).
+   */
+  maxIterations?: number;
+  /**
+   * Configure deferred tool discovery. Tools with `deferLoading: true` are
+   * excluded from the default context and discoverable via the search meta-tool.
+   */
+  toolSearch?: ToolSearchConfig;
   /** Knowledge base configuration (enables search_knowledge tool) */
   knowledgeBase?: KnowledgeBaseConfig;
   /** Enable debug logging */
@@ -154,22 +223,7 @@ export interface ChatRequest {
       required?: string[];
     };
   }>;
-  /** Full client tool catalog used for server-side tool selection and deferred search. */
-  toolCatalog?: Array<{
-    name: string;
-    description: string;
-    category?: string;
-    group?: string;
-    deferLoading?: boolean;
-    profiles?: string[];
-    searchKeywords?: string[];
-    inputSchema: {
-      type: "object";
-      properties: Record<string, unknown>;
-      required?: string[];
-    };
-  }>;
-  /** Active tool profile to apply when agentLoop.toolSelection is enabled. */
+  /** Active tool profile to apply (filters tools by profile when toolSearch is configured). */
   toolProfile?: string;
   /** Enable agentic loop mode */
   useAgentLoop?: boolean;

From 154e904bc7c31e3a6ca5164f45cd4ad53b8c16b8 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Thu, 12 Mar 2026 13:53:02 +0530
Subject: [PATCH 07/72] feat(sdk): add client-side skills system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add skill-system/ (types, registry, load-skills, frontmatter) for defining and resolving skills
- Add react/skill/ (SkillProvider, SkillContext, define-skill) for React integration
- Add useSkill hook for per-component skill registration/unregistration
- Add useSkillStatus hook for querying registered skill state
- Add setInlineSkills to ChatWithTools (delegates to AbstractChat)
- Add setInlineSkills + skills prop to CopilotProvider
- Export all skills APIs from react/index.ts
- Rename from skills/ to skill-system/ and react/skill/ to avoid .gitignore conflict with Claude Code skill folders
- Fix source type mapping in SkillProvider (inline→client-inline, url→remote-url, file→server-dir)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../copilot-sdk/src/chat/ChatWithTools.ts     |  14 +
 .../src/chat/classes/AbstractChat.ts          |  26 ++
 packages/copilot-sdk/src/react/hooks/index.ts |   4 +
 .../copilot-sdk/src/react/hooks/useSkill.ts   |  78 +++++
 .../src/react/hooks/useSkillStatus.ts         |  51 +++
 packages/copilot-sdk/src/react/index.ts       |  16 +
 .../src/react/provider/CopilotProvider.tsx    |  44 ++-
 .../src/react/skill/SkillContext.tsx          |  34 ++
 .../src/react/skill/SkillProvider.tsx         | 230 +++++++++++++
 .../src/react/skill/define-skill.ts           |  29 ++
 .../src/skill-system/frontmatter.ts           |  98 ++++++
 .../copilot-sdk/src/skill-system/index.ts     |  21 ++
 .../src/skill-system/load-skills.ts           | 316 ++++++++++++++++++
 .../copilot-sdk/src/skill-system/registry.ts  | 109 ++++++
 .../copilot-sdk/src/skill-system/types.ts     |  94 ++++++
 15 files changed, 1163 insertions(+), 1 deletion(-)
 create mode 100644 packages/copilot-sdk/src/react/hooks/useSkill.ts
 create mode 100644 packages/copilot-sdk/src/react/hooks/useSkillStatus.ts
 create mode 100644 packages/copilot-sdk/src/react/skill/SkillContext.tsx
 create mode 100644 packages/copilot-sdk/src/react/skill/SkillProvider.tsx
 create mode 100644 packages/copilot-sdk/src/react/skill/define-skill.ts
 create mode 100644 packages/copilot-sdk/src/skill-system/frontmatter.ts
 create mode 100644 packages/copilot-sdk/src/skill-system/index.ts
 create mode 100644 packages/copilot-sdk/src/skill-system/load-skills.ts
 create mode 100644 packages/copilot-sdk/src/skill-system/registry.ts
 create mode 100644 packages/copilot-sdk/src/skill-system/types.ts

diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index 501c6cd..1cc6eb4 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -492,6 +492,20 @@ export class ChatWithTools {
     this.chat.setBody(body);
   }
 
+  /**
+   * Set inline skills (forwarded to underlying chat instance)
+   */
+  setInlineSkills(
+    skills: Array<{
+      name: string;
+      description: string;
+      content: string;
+      strategy?: string;
+    }>,
+  ): void {
+    this.chat.setInlineSkills(skills);
+  }
+
   // ============================================
   // Tool Registration
   // ============================================
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 3a242b2..0a6bb0b 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -500,6 +500,31 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     return this.lastContextUsage;
   }
 
+  /**
+   * 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 {
+    this.inlineSkills = skills;
+    this.debug("Inline skills updated", { count: skills.length });
+  }
+
   /**
    * Dynamic context from useAIContext hook
    */
@@ -590,6 +615,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
             inputSchema: tool.inputSchema,
           }))
         : undefined,
+      __skills: this.inlineSkills.length ? this.inlineSkills : undefined,
     };
   }
 
diff --git a/packages/copilot-sdk/src/react/hooks/index.ts b/packages/copilot-sdk/src/react/hooks/index.ts
index 52581c7..4f85820 100644
--- a/packages/copilot-sdk/src/react/hooks/index.ts
+++ b/packages/copilot-sdk/src/react/hooks/index.ts
@@ -96,3 +96,7 @@ export {
   type UseMCPUIIntentsConfig,
   type UseMCPUIIntentsReturn,
 } from "./useMCPUIIntents";
+
+// Skills Hooks
+export { useSkill } from "./useSkill";
+export { useSkillStatus, type UseSkillStatusReturn } from "./useSkillStatus";
diff --git a/packages/copilot-sdk/src/react/hooks/useSkill.ts b/packages/copilot-sdk/src/react/hooks/useSkill.ts
new file mode 100644
index 0000000..1e17bdc
--- /dev/null
+++ b/packages/copilot-sdk/src/react/hooks/useSkill.ts
@@ -0,0 +1,78 @@
+"use client";
+
+/**
+ * useSkill — register a skill from a React component
+ *
+ * Registers the skill on mount, unregisters on unmount.
+ * Must be used inside <SkillProvider>.
+ *
+ * Only inline skills are supported client-side.
+ * For file/url skills use loadSkills() on the server.
+ *
+ * @example
+ * ```tsx
+ * function CheckoutPage() {
+ *   useSkill({
+ *     name: "checkout-flow",
+ *     description: "Guides the user through checkout",
+ *     strategy: "auto",
+ *     source: {
+ *       type: "inline",
+ *       content: "When helping with checkout...",
+ *     },
+ *   });
+ *
+ *   return <CheckoutUI />;
+ * }
+ * ```
+ */
+
+import { useEffect } from "react";
+import { useSkillContext } from "../skill/SkillContext";
+import type { SkillDefinition, ResolvedSkill } from "../../skill-system/types";
+
+const DEV_CONTENT_WARN_THRESHOLD = 2000;
+
+export function useSkill(skill: SkillDefinition): void {
+  const { register, unregister } = useSkillContext();
+
+  // Warn in development if inline content is too large
+  if (
+    process.env.NODE_ENV !== "production" &&
+    skill.source.type === "inline" &&
+    skill.source.content.length > DEV_CONTENT_WARN_THRESHOLD
+  ) {
+    console.warn(
+      `[copilot-sdk/skills] Inline skill "${skill.name}" has ${skill.source.content.length} characters. ` +
+        `Inline skills are sent on every request — keep them under ${DEV_CONTENT_WARN_THRESHOLD} characters. ` +
+        `Consider using a file or URL skill instead.`,
+    );
+  }
+
+  useEffect(() => {
+    if (skill.source.type !== "inline") {
+      console.warn(
+        `[copilot-sdk/skills] useSkill only supports inline skills client-side. ` +
+          `Skill "${skill.name}" has source type "${skill.source.type}" and will be skipped.`,
+      );
+      return;
+    }
+
+    const resolved: ResolvedSkill = {
+      ...skill,
+      content: skill.source.content,
+    };
+
+    register(resolved);
+
+    return () => {
+      unregister(skill.name);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    skill.name,
+    skill.source.type === "inline" ? skill.source.content : "",
+    skill.strategy,
+    skill.description,
+  ]);
+}
diff --git a/packages/copilot-sdk/src/react/hooks/useSkillStatus.ts b/packages/copilot-sdk/src/react/hooks/useSkillStatus.ts
new file mode 100644
index 0000000..151da64
--- /dev/null
+++ b/packages/copilot-sdk/src/react/hooks/useSkillStatus.ts
@@ -0,0 +1,51 @@
+"use client";
+
+/**
+ * useSkillStatus — observe the current skill registry state
+ *
+ * Returns a reactive snapshot of registered skills.
+ * Must be used inside <SkillProvider>.
+ *
+ * @example
+ * ```tsx
+ * function DebugPanel() {
+ *   const { skills, count, has } = useSkillStatus();
+ *
+ *   return (
+ *     <div>
+ *       <p>{count} skill(s) registered</p>
+ *       {has("code-review") && <p>Code review skill active</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+import { useCallback } from "react";
+import { useSkillContext } from "../skill/SkillContext";
+import type { ResolvedSkill } from "../../skill-system/types";
+
+export 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;
+}
+
+export function useSkillStatus(): UseSkillStatusReturn {
+  const { skills, registry } = useSkillContext();
+
+  const has = useCallback(
+    (name: string) => registry.has(name),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [skills],
+  );
+
+  return {
+    skills,
+    count: skills.length,
+    has,
+  };
+}
diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index ed433b4..dfc6d88 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -202,3 +202,19 @@ export type {
 
 // Re-export tool helper function (Vercel AI SDK pattern)
 export { tool } from "../core";
+
+// Skills System
+export { SkillProvider, type SkillProviderProps } from "./skill/SkillProvider";
+export { defineSkill } from "./skill/define-skill";
+export { useSkill } from "./hooks/useSkill";
+export {
+  useSkillStatus,
+  type UseSkillStatusReturn,
+} from "./hooks/useSkillStatus";
+export type {
+  SkillDefinition,
+  SkillSource,
+  SkillStrategy,
+  ResolvedSkill,
+  ClientInlineSkill,
+} from "../skill-system/types";
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 1ea9439..35d2150 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -44,6 +44,8 @@ import {
   type ContextTreeNode,
 } from "../utils/context-tree";
 import { useMCPTools } from "../hooks/useMCPTools";
+import { SkillProvider } from "../skill/SkillProvider";
+import type { SkillDefinition } from "../../skill-system/types";
 
 // ============================================
 // Internal MCP Connection Component
@@ -107,6 +109,12 @@ export interface CopilotProviderProps {
   mcpServers?: MCPServerConfig[];
   /** Optional prompt/tool optimization controls (tool profiles, context budgets, etc.) */
   optimization?: ToolOptimizationConfig;
+  /**
+   * 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[];
 }
 
 export interface CopilotContextValue {
@@ -155,6 +163,16 @@ export interface CopilotContextValue {
   // System Prompt
   setSystemPrompt: (prompt: string) => void;
 
+  // Skills (for SkillProvider — sends inline skills to server on every request)
+  setInlineSkills: (
+    skills: Array<{
+      name: string;
+      description: string;
+      content: string;
+      strategy?: string;
+    }>,
+  ) => void;
+
   // Config
   threadId?: string;
   /**
@@ -200,6 +218,7 @@ export function CopilotProvider({
   maxIterationsMessage,
   mcpServers,
   optimization,
+  skills,
 }: CopilotProviderProps) {
   // Debug logger
   const debugLog = useCallback(
@@ -448,6 +467,21 @@ export function CopilotProvider({
     [debugLog],
   );
 
+  const setInlineSkills = useCallback(
+    (
+      skills: Array<{
+        name: string;
+        description: string;
+        content: string;
+        strategy?: string;
+      }>,
+    ): void => {
+      chatRef.current?.setInlineSkills(skills);
+      debugLog("Inline skills updated", { count: skills.length });
+    },
+    [debugLog],
+  );
+
   // ============================================
   // Chat Actions
   // ============================================
@@ -552,6 +586,9 @@ export function CopilotProvider({
       // System Prompt
       setSystemPrompt,
 
+      // Skills
+      setInlineSkills,
+
       // Config
       threadId,
       runtimeUrl,
@@ -580,6 +617,7 @@ export function CopilotProvider({
       addContext,
       removeContext,
       setSystemPrompt,
+      setInlineSkills,
       threadId,
       runtimeUrl,
       toolsConfig,
@@ -591,7 +629,11 @@ export function CopilotProvider({
       {mcpServers?.map((config) => (
         <MCPConnection key={config.name} config={config} />
       ))}
-      {children}
+      {skills ? (
+        <SkillProvider skills={skills}>{children}</SkillProvider>
+      ) : (
+        children
+      )}
     </CopilotContext.Provider>
   );
 }
diff --git a/packages/copilot-sdk/src/react/skill/SkillContext.tsx b/packages/copilot-sdk/src/react/skill/SkillContext.tsx
new file mode 100644
index 0000000..c948a92
--- /dev/null
+++ b/packages/copilot-sdk/src/react/skill/SkillContext.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+/**
+ * SkillContext — React context holding the client-side SkillRegistry
+ */
+
+import { createContext, useContext } from "react";
+import type { SkillRegistry } from "../../skill-system/registry";
+import type { ResolvedSkill } from "../../skill-system/types";
+
+export interface SkillContextValue {
+  registry: SkillRegistry;
+  /** Register a skill and trigger re-render */
+  register: (skill: ResolvedSkill) => void;
+  /** Unregister a skill by name and trigger re-render */
+  unregister: (name: string) => void;
+  /** Reactive snapshot of all registered skills */
+  skills: ResolvedSkill[];
+}
+
+export const SkillContext = createContext<SkillContextValue | null>(null);
+
+export function useSkillContext(): SkillContextValue {
+  const ctx = useContext(SkillContext);
+  if (!ctx) {
+    throw new Error("useSkillContext must be used within <SkillProvider>");
+  }
+  return ctx;
+}
+
+/** Returns null instead of throwing when used outside SkillProvider */
+export function useSkillContextOptional(): SkillContextValue | null {
+  return useContext(SkillContext);
+}
diff --git a/packages/copilot-sdk/src/react/skill/SkillProvider.tsx b/packages/copilot-sdk/src/react/skill/SkillProvider.tsx
new file mode 100644
index 0000000..160707b
--- /dev/null
+++ b/packages/copilot-sdk/src/react/skill/SkillProvider.tsx
@@ -0,0 +1,230 @@
+"use client";
+
+/**
+ * SkillProvider — React provider for the client-side skill system
+ *
+ * Responsibilities:
+ * 1. Creates and holds a client SkillRegistry
+ * 2. Pre-registers skills passed as props
+ * 3. Injects skill catalog into AI context (useAIContext)
+ * 4. Registers the load_skill tool (useTool)
+ * 5. Exposes SkillContext for useSkill() hooks
+ *
+ * Must be placed inside <CopilotProvider>.
+ */
+
+import React, {
+  useRef,
+  useState,
+  useCallback,
+  useEffect,
+  useMemo,
+} from "react";
+import { SkillRegistry } from "../../skill-system/registry";
+import type { SkillDefinition, ResolvedSkill } from "../../skill-system/types";
+import { SkillContext } from "./SkillContext";
+import { useAIContext } from "../hooks/useAIContext";
+import { useTool } from "../hooks/useTool";
+import { useCopilot } from "../provider/CopilotProvider";
+
+// ============================================
+// Types
+// ============================================
+
+export interface SkillProviderProps {
+  children: React.ReactNode;
+  /** Pre-register skills (eager or auto strategies) */
+  skills?: SkillDefinition[];
+  /**
+   * Future: URL to fetch a remote skill manifest
+   * @experimental
+   */
+  remoteManifest?: string;
+}
+
+// ============================================
+// Internal: Context injectors and tool registrar
+// Must be separate components to call hooks at top level
+// ============================================
+
+function SkillContextInjector({
+  registry,
+  skills,
+}: {
+  registry: SkillRegistry;
+  skills: ResolvedSkill[];
+}) {
+  const catalog = useMemo(() => registry.buildCatalog(), [skills]);
+  const eagerContent = useMemo(() => registry.buildEagerContent(), [skills]);
+
+  // Inject auto skill catalog into AI context
+  useAIContext({
+    key: "__skill_catalog__",
+    description: "Skills the AI can load on demand",
+    data: catalog
+      ? `You have access to specialized skills. Call load_skill({ name }) when relevant.\n\n${catalog}`
+      : "",
+  });
+
+  // Inject eager skill content (always active)
+  useAIContext({
+    key: "__skill_eager__",
+    description: "Always-active skill instructions",
+    data: eagerContent,
+  });
+
+  return null;
+}
+
+function SkillRequestSync({ skills }: { skills: ResolvedSkill[] }) {
+  const { setInlineSkills } = useCopilot();
+
+  useEffect(() => {
+    const inlineSkills = skills
+      .filter((s) => s.source.type === "inline")
+      .map((s) => ({
+        name: s.name,
+        description: s.description,
+        content: s.content,
+        strategy: s.strategy,
+      }));
+    setInlineSkills(inlineSkills);
+  }, [skills, setInlineSkills]);
+
+  return null;
+}
+
+function SkillToolRegistrar({
+  registry,
+  skills,
+}: {
+  registry: SkillRegistry;
+  skills: ResolvedSkill[];
+}) {
+  useTool(
+    {
+      name: "load_skill",
+      description:
+        "Load a skill by name to get full instructions for a specialized task.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "The name of the skill to load.",
+          },
+        },
+        required: ["name"],
+      },
+      handler: async ({ name }: { name: string }) => {
+        const skill = registry.get(name);
+        if (!skill) {
+          const available =
+            registry
+              .getAuto()
+              .map((s) => s.name)
+              .join(", ") || "none";
+          return {
+            success: false,
+            error: `Skill "${name}" not found. Available skills: ${available}`,
+          };
+        }
+        const sourceTypeMap = {
+          inline: "client-inline",
+          url: "remote-url",
+          file: "server-dir",
+        } as const;
+        return {
+          success: true,
+          name: skill.name,
+          description: skill.description,
+          strategy: skill.strategy ?? "auto",
+          content: skill.content,
+          source: sourceTypeMap[skill.source.type],
+        };
+      },
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [skills],
+  );
+
+  return null;
+}
+
+// ============================================
+// Main SkillProvider
+// ============================================
+
+export function SkillProvider({
+  children,
+  skills: skillsProp,
+}: SkillProviderProps) {
+  // Stable registry instance
+  const registryRef = useRef<SkillRegistry | null>(null);
+  if (registryRef.current === null) {
+    registryRef.current = new SkillRegistry();
+  }
+  const registry = registryRef.current;
+
+  // Reactive skills snapshot (triggers re-renders when skills change)
+  const [skills, setSkills] = useState<ResolvedSkill[]>([]);
+
+  // Register skills passed as props
+  useEffect(() => {
+    if (!skillsProp?.length) return;
+
+    for (const def of skillsProp) {
+      if (def.source.type !== "inline") {
+        // url/file skills need content resolved — not supported client-side
+        console.warn(
+          `[copilot-sdk/skills] Client-side SkillProvider only supports inline skills. ` +
+            `Skill "${def.name}" has source type "${def.source.type}" and will be skipped. ` +
+            `Use loadSkills() on the server for file/url skills.`,
+        );
+        continue;
+      }
+
+      const resolved: ResolvedSkill = {
+        ...def,
+        content: def.source.content,
+      };
+
+      registry.register(resolved);
+    }
+
+    setSkills(registry.getAll());
+
+    // Cleanup prop-provided skills on unmount or prop change
+    return () => {
+      for (const def of skillsProp ?? []) {
+        registry.unregister(def.name);
+      }
+      setSkills(registry.getAll());
+    };
+  }, [skillsProp]);
+
+  // Context-exposed register/unregister (for useSkill hook)
+  const register = useCallback((skill: ResolvedSkill) => {
+    registry.register(skill);
+    setSkills(registry.getAll());
+  }, []);
+
+  const unregister = useCallback((name: string) => {
+    registry.unregister(name);
+    setSkills(registry.getAll());
+  }, []);
+
+  const contextValue = useMemo(
+    () => ({ registry, register, unregister, skills }),
+    [register, unregister, skills],
+  );
+
+  return (
+    <SkillContext.Provider value={contextValue}>
+      <SkillContextInjector registry={registry} skills={skills} />
+      <SkillToolRegistrar registry={registry} skills={skills} />
+      <SkillRequestSync skills={skills} />
+      {children}
+    </SkillContext.Provider>
+  );
+}
diff --git a/packages/copilot-sdk/src/react/skill/define-skill.ts b/packages/copilot-sdk/src/react/skill/define-skill.ts
new file mode 100644
index 0000000..4b865fa
--- /dev/null
+++ b/packages/copilot-sdk/src/react/skill/define-skill.ts
@@ -0,0 +1,29 @@
+/**
+ * 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>
+ * ```
+ */
+
+import type { SkillDefinition } from "../../skill-system/types";
+
+export function defineSkill(def: SkillDefinition): SkillDefinition {
+  return def;
+}
diff --git a/packages/copilot-sdk/src/skill-system/frontmatter.ts b/packages/copilot-sdk/src/skill-system/frontmatter.ts
new file mode 100644
index 0000000..18dbbc0
--- /dev/null
+++ b/packages/copilot-sdk/src/skill-system/frontmatter.ts
@@ -0,0 +1,98 @@
+/**
+ * Frontmatter parser for skill .md files
+ *
+ * Parses YAML-like frontmatter blocks delimited by ---
+ * Supports single-line scalars only (no external YAML dependency).
+ *
+ * Example skill file:
+ * ---
+ * name: code-review
+ * description: Performs thorough code reviews
+ * strategy: auto
+ * version: 1.0.0
+ * ---
+ *
+ * ## Instructions
+ * When reviewing code...
+ */
+
+export interface ParsedFrontmatter {
+  name?: string;
+  description?: string;
+  strategy?: string;
+  version?: string;
+}
+
+export interface ParsedSkillFile {
+  frontmatter: ParsedFrontmatter;
+  content: string;
+}
+
+/**
+ * Parse a skill markdown file.
+ * Extracts frontmatter fields and returns the body content (without --- block).
+ */
+export function parseSkillFile(raw: string): ParsedSkillFile {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---/;
+  const match = frontmatterRegex.exec(raw);
+
+  if (!match) {
+    return { frontmatter: {}, content: raw.trim() };
+  }
+
+  const frontmatterBlock = match[1];
+  const frontmatter = parseFrontmatterBlock(frontmatterBlock);
+
+  // Content is everything after the closing ---
+  const afterFrontmatter = raw.slice(match.index + match[0].length);
+  const content = afterFrontmatter.replace(/^\r?\n/, "").trim();
+
+  return { frontmatter, content };
+}
+
+/**
+ * Parse individual frontmatter key: value pairs (single-line scalars only).
+ */
+function parseFrontmatterBlock(block: string): ParsedFrontmatter {
+  const result: ParsedFrontmatter = {};
+  const lines = block.split(/\r?\n/);
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) continue;
+
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+
+    if (!key || !value) continue;
+
+    // Only accept known keys, ignore others
+    switch (key) {
+      case "name":
+        result.name = stripQuotes(value);
+        break;
+      case "description":
+        result.description = stripQuotes(value);
+        break;
+      case "strategy":
+        result.strategy = stripQuotes(value);
+        break;
+      case "version":
+        result.version = stripQuotes(value);
+        break;
+    }
+  }
+
+  return result;
+}
+
+/** Strip optional surrounding quotes from a YAML scalar value */
+function stripQuotes(value: string): string {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
diff --git a/packages/copilot-sdk/src/skill-system/index.ts b/packages/copilot-sdk/src/skill-system/index.ts
new file mode 100644
index 0000000..040c38f
--- /dev/null
+++ b/packages/copilot-sdk/src/skill-system/index.ts
@@ -0,0 +1,21 @@
+/**
+ * Skills — framework-agnostic core
+ * Re-exported via @yourgpt/copilot-sdk/server entry point
+ */
+
+export { loadSkills } from "./load-skills";
+export { SkillRegistry } from "./registry";
+export { parseSkillFile } from "./frontmatter";
+export type {
+  SkillDefinition,
+  SkillSource,
+  SkillStrategy,
+  ResolvedSkill,
+  SkillDiagnostic,
+  SkillDiagnosticWinner,
+  ClientInlineSkill,
+  LoadSkillsOptions,
+  LoadSkillsResult,
+  LoadSkillResult,
+  LoadSkillError,
+} from "./types";
diff --git a/packages/copilot-sdk/src/skill-system/load-skills.ts b/packages/copilot-sdk/src/skill-system/load-skills.ts
new file mode 100644
index 0000000..11a7031
--- /dev/null
+++ b/packages/copilot-sdk/src/skill-system/load-skills.ts
@@ -0,0 +1,316 @@
+/**
+ * loadSkills() — Server-side skill loader
+ *
+ * Loads skills from three sources with precedence:
+ *   server-dir > remote-url > client-inline
+ *
+ * Returns skills, diagnostics, buildSystemPrompt(), and the load_skill tool.
+ *
+ * Node.js only — uses fs and fetch.
+ */
+
+import type {
+  LoadSkillsOptions,
+  LoadSkillsResult,
+  ResolvedSkill,
+  SkillDiagnostic,
+  SkillDiagnosticWinner,
+  SkillStrategy,
+} from "./types";
+import { parseSkillFile } from "./frontmatter";
+import { SkillRegistry } from "./registry";
+
+const VALID_STRATEGIES = new Set<SkillStrategy>(["eager", "auto", "manual"]);
+
+function isValidStrategy(s: string): s is SkillStrategy {
+  return VALID_STRATEGIES.has(s as SkillStrategy);
+}
+
+/**
+ * Load skills from server directory, remote URLs, and/or inline client skills.
+ *
+ * @example
+ * ```typescript
+ * import { loadSkills } from '@yourgpt/copilot-sdk/server';
+ *
+ * const { skills, buildSystemPrompt, tools } = await loadSkills({
+ *   dir: path.join(process.cwd(), 'skills'),
+ * });
+ *
+ * // Use in your API route
+ * const systemPrompt = buildSystemPrompt('You are a helpful assistant.');
+ * ```
+ */
+export async function loadSkills(
+  options: LoadSkillsOptions = {},
+): Promise<LoadSkillsResult> {
+  const registry = new SkillRegistry();
+  const diagnostics: SkillDiagnostic[] = [];
+
+  // Track which names came from which source (for collision detection)
+  const sourceMap = new Map<string, SkillDiagnosticWinner>();
+
+  // ──────────────────────────────────────────────────
+  // Source 1: Server directory (highest precedence)
+  // ──────────────────────────────────────────────────
+  if (options.dir) {
+    const dirSkills = await loadFromDir(options.dir);
+    for (const skill of dirSkills) {
+      registry.register(skill);
+      sourceMap.set(skill.name, "server-dir");
+    }
+  }
+
+  // ──────────────────────────────────────────────────
+  // Source 2: Remote URLs (medium precedence)
+  // ──────────────────────────────────────────────────
+  if (options.remoteUrls?.length) {
+    const urlSkills = await loadFromUrls(options.remoteUrls);
+    for (const skill of urlSkills) {
+      const existingSource = sourceMap.get(skill.name);
+      if (existingSource) {
+        diagnostics.push({
+          type: "collision",
+          name: skill.name,
+          winner: existingSource,
+          loser: "remote-url",
+        });
+        continue; // Skip — lower precedence source loses
+      }
+      registry.register(skill);
+      sourceMap.set(skill.name, "remote-url");
+    }
+  }
+
+  // ──────────────────────────────────────────────────
+  // Source 3: Client inline (lowest precedence)
+  // ──────────────────────────────────────────────────
+  if (options.clientSkills?.length) {
+    for (const inline of options.clientSkills) {
+      const existingSource = sourceMap.get(inline.name);
+      if (existingSource) {
+        diagnostics.push({
+          type: "collision",
+          name: inline.name,
+          winner: existingSource,
+          loser: "client-inline",
+        });
+        continue;
+      }
+
+      const skill: ResolvedSkill = {
+        name: inline.name,
+        description: inline.description,
+        content: inline.content,
+        strategy: inline.strategy ?? "auto",
+        source: { type: "inline", content: inline.content },
+      };
+      registry.register(skill);
+      sourceMap.set(inline.name, "client-inline");
+    }
+  }
+
+  // ──────────────────────────────────────────────────
+  // Build result
+  // ──────────────────────────────────────────────────
+  return {
+    skills: registry.getAll(),
+    diagnostics,
+
+    buildSystemPrompt(basePrompt?: string): string {
+      const parts: string[] = [];
+
+      if (basePrompt) {
+        parts.push(basePrompt);
+      }
+
+      // Prepend eager skill content (always active)
+      const eagerContent = registry.buildEagerContent();
+      if (eagerContent) {
+        parts.push(eagerContent);
+      }
+
+      // Append auto catalog (discoverable via load_skill)
+      const catalog = registry.buildCatalog();
+      if (catalog) {
+        parts.push(
+          `You have access to specialized skills. Call load_skill({ name }) when relevant.\n\n${catalog}`,
+        );
+      }
+
+      return parts.join("\n\n").trim();
+    },
+
+    tools: {
+      load_skill: {
+        description:
+          "Load a skill by name to get full instructions for a specialized task.",
+        parameters: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "The name of the skill to load.",
+            },
+          },
+          required: ["name"],
+        },
+        execute: async ({ name }: { name: string }) => {
+          const skill = registry.get(name);
+          if (!skill) {
+            return {
+              error: `Skill "${name}" not found. Available skills: ${
+                registry
+                  .getAuto()
+                  .map((s) => s.name)
+                  .join(", ") || "none"
+              }`,
+            };
+          }
+          const sourceTypeMap = {
+            inline: "client-inline",
+            url: "remote-url",
+            file: "server-dir",
+          } as const;
+          return {
+            name: skill.name,
+            description: skill.description,
+            strategy: skill.strategy ?? "auto",
+            content: skill.content,
+            source: sourceTypeMap[skill.source.type],
+          };
+        },
+      },
+    },
+  };
+}
+
+// ──────────────────────────────────────────────────
+// Internal helpers
+// ──────────────────────────────────────────────────
+
+async function loadFromDir(dir: string): Promise<ResolvedSkill[]> {
+  // Dynamic import to avoid bundling fs in browser builds
+  const { readdir, readFile } = await import("fs/promises");
+  const path = await import("path");
+
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    // Directory doesn't exist or unreadable — not an error
+    return [];
+  }
+
+  const skills: ResolvedSkill[] = [];
+
+  for (const entry of entries) {
+    const entryPath = path.join(dir, entry);
+
+    if (entry.endsWith(".md")) {
+      // Flat .md file
+      const skill = await loadSkillFromFile(entryPath, readFile, path);
+      if (skill) skills.push(skill);
+    } else {
+      // Check for folder-based skill: entry/SKILL.md
+      const skillMdPath = path.join(entryPath, "SKILL.md");
+      try {
+        const skill = await loadSkillFromFile(skillMdPath, readFile, path);
+        if (skill) skills.push(skill);
+      } catch {
+        // Not a skill folder — skip
+      }
+    }
+  }
+
+  return skills;
+}
+
+async function loadSkillFromFile(
+  filePath: string,
+  readFile: (path: string, encoding: "utf-8") => Promise<string>,
+  path: { basename: (p: string, ext?: string) => string },
+): Promise<ResolvedSkill | null> {
+  let raw: string;
+  try {
+    raw = await readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const { frontmatter, content } = parseSkillFile(raw);
+
+  // Derive name from frontmatter or filename
+  const fileName = path.basename(filePath, ".md");
+  const name =
+    frontmatter.name ?? (fileName === "SKILL" ? undefined : fileName);
+
+  if (!name) {
+    console.warn(
+      `[copilot-sdk/skills] Skipping skill at ${filePath}: no name in frontmatter and could not derive from filename`,
+    );
+    return null;
+  }
+
+  const strategy =
+    frontmatter.strategy && isValidStrategy(frontmatter.strategy)
+      ? frontmatter.strategy
+      : "auto";
+
+  return {
+    name,
+    description: frontmatter.description ?? `Skill: ${name}`,
+    content,
+    strategy,
+    version: frontmatter.version,
+    source: { type: "file", path: filePath },
+  };
+}
+
+async function loadFromUrls(urls: string[]): Promise<ResolvedSkill[]> {
+  const skills: ResolvedSkill[] = [];
+
+  await Promise.allSettled(
+    urls.map(async (url) => {
+      try {
+        const res = await fetch(url);
+        if (!res.ok) {
+          console.warn(
+            `[copilot-sdk/skills] Failed to fetch skill from ${url}: HTTP ${res.status}`,
+          );
+          return;
+        }
+        const raw = await res.text();
+        const { frontmatter, content } = parseSkillFile(raw);
+
+        if (!frontmatter.name) {
+          console.warn(
+            `[copilot-sdk/skills] Skipping remote skill at ${url}: no name in frontmatter`,
+          );
+          return;
+        }
+
+        const strategy =
+          frontmatter.strategy && isValidStrategy(frontmatter.strategy)
+            ? frontmatter.strategy
+            : "auto";
+
+        skills.push({
+          name: frontmatter.name,
+          description: frontmatter.description ?? `Skill: ${frontmatter.name}`,
+          content,
+          strategy,
+          version: frontmatter.version,
+          source: { type: "url", url },
+        });
+      } catch (err) {
+        console.warn(
+          `[copilot-sdk/skills] Error loading remote skill from ${url}:`,
+          err,
+        );
+      }
+    }),
+  );
+
+  return skills;
+}
diff --git a/packages/copilot-sdk/src/skill-system/registry.ts b/packages/copilot-sdk/src/skill-system/registry.ts
new file mode 100644
index 0000000..e65f82e
--- /dev/null
+++ b/packages/copilot-sdk/src/skill-system/registry.ts
@@ -0,0 +1,109 @@
+/**
+ * SkillRegistry — manages registered skills
+ *
+ * Shared between server (loadSkills) and client (SkillProvider).
+ * Framework-agnostic — no React dependencies.
+ */
+
+import type { ResolvedSkill, SkillStrategy } from "./types";
+
+export class SkillRegistry {
+  private skills = new Map<string, ResolvedSkill>();
+
+  /**
+   * Register a skill. Silently overwrites if name already exists.
+   * Use collision detection in loadSkills() instead.
+   */
+  register(skill: ResolvedSkill): void {
+    this.skills.set(skill.name, skill);
+  }
+
+  /**
+   * Unregister a skill by name.
+   */
+  unregister(name: string): void {
+    this.skills.delete(name);
+  }
+
+  /**
+   * Get a skill by name.
+   */
+  get(name: string): ResolvedSkill | undefined {
+    return this.skills.get(name);
+  }
+
+  /**
+   * Get all registered skills.
+   */
+  getAll(): ResolvedSkill[] {
+    return Array.from(this.skills.values());
+  }
+
+  /**
+   * Get all skills with strategy === "eager".
+   * These are injected directly into the system prompt.
+   */
+  getEager(): ResolvedSkill[] {
+    return this.getAll().filter((s) => this.resolveStrategy(s) === "eager");
+  }
+
+  /**
+   * Get all skills with strategy === "auto".
+   * These appear in the catalog and are loadable on demand.
+   */
+  getAuto(): ResolvedSkill[] {
+    return this.getAll().filter((s) => this.resolveStrategy(s) === "auto");
+  }
+
+  /**
+   * Check if a skill is registered.
+   */
+  has(name: string): boolean {
+    return this.skills.has(name);
+  }
+
+  /**
+   * Number of registered skills.
+   */
+  get count(): number {
+    return this.skills.size;
+  }
+
+  /**
+   * Build a skill catalog string for "auto" skills.
+   * Appended to the system prompt so the AI can discover available skills.
+   */
+  buildCatalog(): string {
+    const autoSkills = this.getAuto();
+    if (autoSkills.length === 0) return "";
+
+    const lines = autoSkills.map((s) => `- ${s.name}: ${s.description}`);
+    return `Available skills:\n${lines.join("\n")}`;
+  }
+
+  /**
+   * Concatenate content of all "eager" skills.
+   * These instructions are always active without requiring load_skill.
+   */
+  buildEagerContent(): string {
+    const eagerSkills = this.getEager();
+    if (eagerSkills.length === 0) return "";
+
+    return eagerSkills
+      .map((s) => `## Skill: ${s.name}\n\n${s.content}`)
+      .join("\n\n---\n\n");
+  }
+
+  /**
+   * Resolve content for a skill by name.
+   * For inline/file/url skills, content is already resolved at registration time.
+   */
+  async resolveContent(name: string): Promise<string | undefined> {
+    const skill = this.skills.get(name);
+    return skill?.content;
+  }
+
+  private resolveStrategy(skill: ResolvedSkill): SkillStrategy {
+    return skill.strategy ?? "auto";
+  }
+}
diff --git a/packages/copilot-sdk/src/skill-system/types.ts b/packages/copilot-sdk/src/skill-system/types.ts
new file mode 100644
index 0000000..9975e4f
--- /dev/null
+++ b/packages/copilot-sdk/src/skill-system/types.ts
@@ -0,0 +1,94 @@
+/**
+ * Skills System — Type Definitions
+ *
+ * Skills are instruction playbooks the AI loads on demand.
+ * Separate from Tools (execution layer) — skills shape behavior, tools do work.
+ */
+
+export type SkillStrategy = "eager" | "auto" | "manual";
+
+export type SkillSource =
+  | { type: "inline"; content: string }
+  | { type: "url"; url: string }
+  | { type: "file"; path: string };
+
+export interface SkillDefinition {
+  name: string;
+  description: string;
+  source: SkillSource;
+  /** @default "auto" */
+  strategy?: SkillStrategy;
+  version?: string;
+}
+
+export interface ResolvedSkill extends SkillDefinition {
+  /** Fully resolved content string */
+  content: string;
+}
+
+export type SkillDiagnosticWinner =
+  | "server-dir"
+  | "remote-url"
+  | "client-inline";
+
+export interface SkillDiagnostic {
+  type: "collision";
+  name: string;
+  winner: SkillDiagnosticWinner;
+  loser: SkillDiagnosticWinner;
+}
+
+export interface ClientInlineSkill {
+  name: string;
+  description: string;
+  content: string;
+  strategy?: SkillStrategy;
+}
+
+export interface LoadSkillsOptions {
+  /** Path to /skills directory (server-only) */
+  dir?: string;
+  /** Remote .md URLs to fetch */
+  remoteUrls?: string[];
+  /** Inline skills from useSkill() hooks */
+  clientSkills?: ClientInlineSkill[];
+}
+
+export 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>;
+    };
+  };
+}
+
+export interface LoadSkillResult {
+  name: string;
+  description: string;
+  strategy: SkillStrategy;
+  content: string;
+  source: "server-dir" | "remote-url" | "client-inline";
+}
+
+export interface LoadSkillError {
+  error: string;
+}

From 2ba987ab72b3f009006a55d794489b9d38958a1e Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Thu, 12 Mar 2026 13:54:33 +0530
Subject: [PATCH 08/72] feat(sdk): add server entry point and wire __skills
 through transport

- Add server/index.ts entry (loadSkills, SkillRegistry, parseSkillFile + all types)
- Add ./server subpath export to package.json
- Add server/index build entry to tsup.config.ts
- Add __skills field to ChatRequest interface (ChatTransport.ts)
- Pass __skills in HttpTransport request body so server receives inline client skills

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/copilot-sdk/package.json             |  5 +++
 .../src/chat/adapters/HttpTransport.ts        |  1 +
 .../src/chat/interfaces/ChatTransport.ts      | 10 +++++
 packages/copilot-sdk/src/server/index.ts      | 37 +++++++++++++++++++
 packages/copilot-sdk/tsup.config.ts           |  3 ++
 5 files changed, 56 insertions(+)
 create mode 100644 packages/copilot-sdk/src/server/index.ts

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index 205fa35..f7e0066 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -78,6 +78,11 @@
       "types": "./dist/tools/anthropic/index.d.ts",
       "import": "./dist/tools/anthropic/index.js",
       "require": "./dist/tools/anthropic/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.cjs"
     }
   },
   "files": [
diff --git a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
index 63a500a..42af442 100644
--- a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
+++ b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
@@ -92,6 +92,7 @@ export class HttpTransport implements ChatTransport {
           tools: request.tools,
           actions: request.actions,
           streaming: this.config.streaming,
+          __skills: request.__skills,
           ...(resolved.configBody as Record<string, unknown>),
           ...request.body,
         }),
diff --git a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
index 59e8b31..1675cde 100644
--- a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
+++ b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
@@ -32,6 +32,16 @@ export 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;
+  }>;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/server/index.ts b/packages/copilot-sdk/src/server/index.ts
new file mode 100644
index 0000000..5acc8a4
--- /dev/null
+++ b/packages/copilot-sdk/src/server/index.ts
@@ -0,0 +1,37 @@
+/**
+ * @yourgpt/copilot-sdk/server
+ *
+ * Server-only exports for the Skills System.
+ * Do NOT import this in browser/React code — it uses Node.js fs module.
+ *
+ * @example
+ * ```typescript
+ * import { loadSkills } from '@yourgpt/copilot-sdk/server';
+ * import path from 'path';
+ *
+ * const { skills, buildSystemPrompt, tools } = await loadSkills({
+ *   dir: path.join(process.cwd(), 'skills'),
+ * });
+ *
+ * // In your API route handler:
+ * const systemPrompt = buildSystemPrompt('You are a helpful assistant.');
+ * ```
+ */
+
+export { loadSkills } from "../skill-system/load-skills";
+export { SkillRegistry } from "../skill-system/registry";
+export { parseSkillFile } from "../skill-system/frontmatter";
+
+export type {
+  SkillDefinition,
+  SkillSource,
+  SkillStrategy,
+  ResolvedSkill,
+  SkillDiagnostic,
+  SkillDiagnosticWinner,
+  ClientInlineSkill,
+  LoadSkillsOptions,
+  LoadSkillsResult,
+  LoadSkillResult,
+  LoadSkillError,
+} from "../skill-system/types";
diff --git a/packages/copilot-sdk/tsup.config.ts b/packages/copilot-sdk/tsup.config.ts
index c0e0e93..1bd65f2 100644
--- a/packages/copilot-sdk/tsup.config.ts
+++ b/packages/copilot-sdk/tsup.config.ts
@@ -9,6 +9,9 @@ export default defineConfig({
     "ui/index": "src/ui/index.ts",
     "mcp/index": "src/mcp/index.ts",
 
+    // Server-only entry (Node.js skills loader)
+    "server/index": "src/server/index.ts",
+
     // Tool subpath exports (tree-shakeable)
     "tools/web-search/index": "src/tools/web-search/index.ts",
     "tools/tavily/index": "src/tools/tavily/index.ts",

From c51a9897f823bc147ffbbd2ef7d3d38ad6d1837e Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Thu, 12 Mar 2026 15:38:25 +0530
Subject: [PATCH 09/72] =?UTF-8?q?feat(sdk):=20Phase=201=20=E2=80=94=20dual?=
 =?UTF-8?q?-layer=20message=20store=20foundation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add react/message-history/types.ts: DisplayMessage (extends UIMessage),
  CompactionMarker, LLMMessage, CompactedToolResult, SessionCompactionState,
  TokenUsage, CompactionEvent, CompactionStrategy, MessageHistoryConfig,
  UseMessageHistoryOptions, UseMessageHistoryReturn
- Add react/message-history/message-utils.ts: toDisplayMessage(), toLLMMessage(),
  toLLMMessages(), keepToolPairsAtomic(), findSafeWindowStart(), type guards
- Add react/message-history/context.ts: MessageHistoryContext + defaults
- Add react/message-history/useMessageHistory.ts: Phase 1 skeleton — promotes
  UIMessages to DisplayMessages, builds llmMessages (no compaction yet)
- Export all from react/index.ts

Strategy 'none' (default) preserves 100% backward-compat.
Phases 2-5 add compaction strategies on top of this foundation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/copilot-sdk/src/react/index.ts       |  27 +++
 .../src/react/message-history/context.ts      |  74 ++++++
 .../src/react/message-history/index.ts        |  30 +++
 .../react/message-history/message-utils.ts    | 139 +++++++++++
 .../src/react/message-history/types.ts        | 215 ++++++++++++++++++
 .../message-history/useMessageHistory.ts      | 131 +++++++++++
 6 files changed, 616 insertions(+)
 create mode 100644 packages/copilot-sdk/src/react/message-history/context.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/index.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/message-utils.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/types.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/useMessageHistory.ts

diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index ed433b4..86ebf24 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -202,3 +202,30 @@ export type {
 
 // Re-export tool helper function (Vercel AI SDK pattern)
 export { tool } from "../core";
+
+// Message History (Context Management)
+export {
+  useMessageHistory,
+  MessageHistoryContext,
+  useMessageHistoryContext,
+  defaultMessageHistoryConfig,
+  toDisplayMessage,
+  toLLMMessage,
+  toLLMMessages,
+  keepToolPairsAtomic,
+  isCompactionMarker,
+} from "./message-history";
+export type {
+  DisplayMessage,
+  CompactionMarker,
+  LLMMessage,
+  CompactedToolResult,
+  SessionCompactionState,
+  TokenUsage,
+  CompactionEvent,
+  CompactionStrategy,
+  MessageHistoryConfig,
+  UseMessageHistoryOptions,
+  UseMessageHistoryReturn,
+  MessageHistoryContextValue,
+} from "./message-history";
diff --git a/packages/copilot-sdk/src/react/message-history/context.ts b/packages/copilot-sdk/src/react/message-history/context.ts
new file mode 100644
index 0000000..802e1ea
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/context.ts
@@ -0,0 +1,74 @@
+/**
+ * MessageHistoryContext
+ *
+ * React context for sharing MessageHistory config and state
+ * across the component tree. Optional — useMessageHistory() works
+ * standalone without this provider.
+ */
+
+import { createContext, useContext } from "react";
+import type {
+  MessageHistoryConfig,
+  SessionCompactionState,
+  TokenUsage,
+} from "./types";
+
+export 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;
+}
+
+const defaultTokenUsage: TokenUsage = {
+  current: 0,
+  max: 128000,
+  percentage: 0,
+  isApproaching: false,
+};
+
+const defaultCompactionState: SessionCompactionState = {
+  rollingSummary: null,
+  lastCompactionAt: null,
+  compactionCount: 0,
+  totalTokensSaved: 0,
+  workingMemory: [],
+  displayMessageCount: 0,
+  llmMessageCount: 0,
+};
+
+export const defaultMessageHistoryConfig = {
+  strategy: "none" as const,
+  maxContextTokens: 128000,
+  reserveForResponse: 4096,
+  compactionThreshold: 0.75,
+  recentBuffer: 10,
+  toolResultMaxChars: 10000,
+  persistSession: false,
+  storageKey: "copilot-session",
+};
+
+export const MessageHistoryContext = createContext<MessageHistoryContextValue>({
+  config: defaultMessageHistoryConfig,
+  tokenUsage: defaultTokenUsage,
+  compactionState: defaultCompactionState,
+});
+
+export function useMessageHistoryContext(): MessageHistoryContextValue {
+  return useContext(MessageHistoryContext);
+}
diff --git a/packages/copilot-sdk/src/react/message-history/index.ts b/packages/copilot-sdk/src/react/message-history/index.ts
new file mode 100644
index 0000000..58bb955
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/index.ts
@@ -0,0 +1,30 @@
+export { useMessageHistory } from "./useMessageHistory";
+export {
+  MessageHistoryContext,
+  useMessageHistoryContext,
+  defaultMessageHistoryConfig,
+} from "./context";
+export type { MessageHistoryContextValue } from "./context";
+export {
+  toDisplayMessage,
+  toLLMMessage,
+  toLLMMessages,
+  keepToolPairsAtomic,
+  findSafeWindowStart,
+  isCompactionMarker,
+  isToolMessage,
+  isAssistantWithToolCalls,
+} from "./message-utils";
+export type {
+  DisplayMessage,
+  CompactionMarker,
+  LLMMessage,
+  CompactedToolResult,
+  SessionCompactionState,
+  TokenUsage,
+  CompactionEvent,
+  CompactionStrategy,
+  MessageHistoryConfig,
+  UseMessageHistoryOptions,
+  UseMessageHistoryReturn,
+} from "./types";
diff --git a/packages/copilot-sdk/src/react/message-history/message-utils.ts b/packages/copilot-sdk/src/react/message-history/message-utils.ts
new file mode 100644
index 0000000..06ec527
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/message-utils.ts
@@ -0,0 +1,139 @@
+/**
+ * Message Utilities
+ *
+ * Conversion helpers between UIMessage / DisplayMessage / LLMMessage.
+ * Core invariant: tool-call pairs are always kept atomic.
+ */
+
+import type { UIMessage } from "../../chat/types/message";
+import type { DisplayMessage, LLMMessage, CompactionMarker } from "./types";
+
+// ── Conversion ────────────────────────────────────────────────────
+
+/**
+ * Promote a UIMessage to a DisplayMessage.
+ * Safe to call on an existing DisplayMessage (idempotent).
+ */
+export function toDisplayMessage(msg: UIMessage): DisplayMessage {
+  return {
+    ...msg,
+    timestamp:
+      msg.createdAt instanceof Date ? msg.createdAt.getTime() : Date.now(),
+  };
+}
+
+/**
+ * Convert a DisplayMessage to the LLMMessage format sent to the model.
+ * CompactionMarkers are converted to system messages with the rolling summary.
+ */
+export function toLLMMessage(msg: DisplayMessage): LLMMessage {
+  // CompactionMarkers become system messages in LLM context
+  if (isCompactionMarker(msg)) {
+    return {
+      role: "system",
+      content: `[Previous conversation summary]\n${msg.content}`,
+    };
+  }
+
+  const base: LLMMessage = {
+    role: msg.role,
+    content: msg.content,
+  };
+
+  if (msg.toolCalls?.length) {
+    base.tool_calls = msg.toolCalls;
+  }
+
+  if (msg.toolCallId) {
+    base.tool_call_id = msg.toolCallId;
+  }
+
+  return base;
+}
+
+/**
+ * Convert an array of DisplayMessages to LLMMessages.
+ */
+export function toLLMMessages(messages: DisplayMessage[]): LLMMessage[] {
+  return messages.map(toLLMMessage);
+}
+
+// ── Atomic tool-call pair enforcement ────────────────────────────
+
+/**
+ * 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.
+ */
+export function keepToolPairsAtomic(
+  messages: DisplayMessage[],
+): DisplayMessage[] {
+  if (messages.length === 0) return messages;
+
+  // Find the first message that has pending tool-call results following it
+  const firstIdx = messages.findIndex((msg, i) => {
+    if (msg.role !== "assistant" || !msg.toolCalls?.length) return false;
+    const toolCallIds = new Set(msg.toolCalls.map((tc) => tc.id));
+    // Check if ALL tool results for this message are present in the slice
+    const resultIds = new Set(
+      messages
+        .slice(i + 1)
+        .filter((m) => m.role === "tool" && m.toolCallId)
+        .map((m) => m.toolCallId as string),
+    );
+    return [...toolCallIds].some((id) => !resultIds.has(id));
+  });
+
+  // No orphaned tool calls
+  if (firstIdx === -1) return messages;
+
+  // Drop back to before the split assistant message
+  return messages.slice(firstIdx);
+}
+
+/**
+ * Find the safe window boundary — the index after which all tool-call
+ * pairs are complete. Used by sliding-window to avoid splits.
+ *
+ * Returns the earliest index we can safely start a window from.
+ */
+export function findSafeWindowStart(
+  messages: DisplayMessage[],
+  desiredStart: number,
+): number {
+  // Walk backward from desiredStart to find an assistant message with tool_calls
+  // whose results fall inside the window
+  for (let i = desiredStart; i < messages.length; i++) {
+    const msg = messages[i];
+    if (
+      msg.role === "user" ||
+      (msg.role === "assistant" && !msg.toolCalls?.length)
+    ) {
+      return i;
+    }
+  }
+  return desiredStart;
+}
+
+// ── Type guards ───────────────────────────────────────────────────
+
+export function isCompactionMarker(
+  msg: DisplayMessage,
+): msg is CompactionMarker {
+  return (
+    msg.role === "system" &&
+    (msg as CompactionMarker).type === "compaction-marker"
+  );
+}
+
+export function isToolMessage(msg: DisplayMessage): boolean {
+  return msg.role === "tool";
+}
+
+export function isAssistantWithToolCalls(msg: DisplayMessage): boolean {
+  return msg.role === "assistant" && !!msg.toolCalls?.length;
+}
diff --git a/packages/copilot-sdk/src/react/message-history/types.ts b/packages/copilot-sdk/src/react/message-history/types.ts
new file mode 100644
index 0000000..cc4babb
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/types.ts
@@ -0,0 +1,215 @@
+/**
+ * Message History Types
+ *
+ * Core types for the dual-layer context management system.
+ * DisplayMessage extends UIMessage for full backward-compat.
+ */
+
+import type { UIMessage } from "../../chat/types/message";
+import type { ToolCall } from "../../core";
+
+// ── Display Layer ─────────────────────────────────────────────────
+
+/**
+ * DisplayMessage — what the UI renders, never shrinks.
+ * Extends UIMessage so it can be used anywhere UIMessage is accepted.
+ */
+export 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".
+ */
+export 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;
+}
+
+// ── LLM Context Layer ─────────────────────────────────────────────
+
+/**
+ * LLMMessage — the compacted form sent to the model on each request.
+ * Derived from DisplayMessages; never persisted directly.
+ */
+export 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.
+ */
+export 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;
+}
+
+// ── Session State ─────────────────────────────────────────────────
+
+/**
+ * SessionCompactionState — persisted to localStorage between reloads.
+ */
+export 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;
+}
+
+// ── Token Usage ───────────────────────────────────────────────────
+
+/**
+ * TokenUsage — live token estimate after each AI response.
+ */
+export 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;
+}
+
+// ── Events ────────────────────────────────────────────────────────
+
+/**
+ * CompactionEvent — fired via onCompaction callback after each compaction.
+ */
+export interface CompactionEvent {
+  /** 'auto' = threshold triggered, 'manual' = compactSession() called */
+  type: "auto" | "manual";
+  compactionCount: number;
+  messagesSummarized: number;
+  tokensSaved: number;
+  timestamp: number;
+}
+
+// ── Strategy ──────────────────────────────────────────────────────
+
+export type CompactionStrategy =
+  | "none"
+  | "sliding-window"
+  | "summary-buffer"
+  | "selective-prune";
+
+// ── Config ────────────────────────────────────────────────────────
+
+/**
+ * MessageHistoryConfig — passed as messageHistory prop to CopilotProvider
+ * or directly to useMessageHistory().
+ */
+export 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;
+}
+
+// ── Hook return ───────────────────────────────────────────────────
+
+export 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>;
+}
+
+export 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;
+  /** 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;
+}
diff --git a/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts b/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts
new file mode 100644
index 0000000..60e1fe3
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts
@@ -0,0 +1,131 @@
+/**
+ * useMessageHistory
+ *
+ * Phase 1 skeleton — returns displayMessages and llmMessages from
+ * the current CopilotProvider messages with no compaction applied.
+ *
+ * Strategy: 'none' (default) — identical to current SDK behaviour.
+ * Future phases add compaction strategies on top of this foundation.
+ */
+
+import { useMemo } from "react";
+import { useCopilot } from "../provider/CopilotProvider";
+import { toDisplayMessage, toLLMMessages } from "./message-utils";
+import {
+  useMessageHistoryContext,
+  defaultMessageHistoryConfig,
+} from "./context";
+import type {
+  UseMessageHistoryOptions,
+  UseMessageHistoryReturn,
+  DisplayMessage,
+  SessionCompactionState,
+  TokenUsage,
+} from "./types";
+
+const DEFAULT_TOKEN_USAGE: TokenUsage = {
+  current: 0,
+  max: 128000,
+  percentage: 0,
+  isApproaching: false,
+};
+
+const DEFAULT_COMPACTION_STATE: SessionCompactionState = {
+  rollingSummary: null,
+  lastCompactionAt: null,
+  compactionCount: 0,
+  totalTokensSaved: 0,
+  workingMemory: [],
+  displayMessageCount: 0,
+  llmMessageCount: 0,
+};
+
+/**
+ * useMessageHistory — dual-layer message access.
+ *
+ * Phase 1: strategy='none' — no compaction, just type promotion.
+ *
+ * @example
+ * ```tsx
+ * const { displayMessages, llmMessages, tokenUsage } = useMessageHistory();
+ * // displayMessages: pass to CopilotChat
+ * // llmMessages: pass to your API route (Phase 2+ adds compaction)
+ * ```
+ */
+export function useMessageHistory(
+  options: UseMessageHistoryOptions = {},
+): UseMessageHistoryReturn {
+  const { messages } = useCopilot();
+  const ctx = useMessageHistoryContext();
+
+  // Merge: hook options override provider context which overrides defaults
+  const config = useMemo(
+    () => ({ ...defaultMessageHistoryConfig, ...ctx.config, ...options }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      ctx.config,
+      options.strategy,
+      options.maxContextTokens,
+      options.recentBuffer,
+    ],
+  );
+
+  // Promote UIMessages to DisplayMessages (adds timestamp field)
+  const displayMessages: DisplayMessage[] = useMemo(
+    () => messages.map(toDisplayMessage),
+    [messages],
+  );
+
+  // Phase 1: no compaction — llmMessages === displayMessages converted
+  // Future phases will apply sliding-window / summary-buffer here
+  const llmMessages = useMemo(
+    () => toLLMMessages(displayMessages),
+    [displayMessages],
+  );
+
+  const tokenUsage: TokenUsage = useMemo(
+    () => ({
+      ...DEFAULT_TOKEN_USAGE,
+      max: config.maxContextTokens,
+      // Phase 2 will compute real token estimates
+    }),
+    [config.maxContextTokens],
+  );
+
+  const compactionState: SessionCompactionState = useMemo(
+    () => ({
+      ...DEFAULT_COMPACTION_STATE,
+      displayMessageCount: displayMessages.length,
+      llmMessageCount: llmMessages.length,
+    }),
+    [displayMessages.length, llmMessages.length],
+  );
+
+  // Phase 3 will implement these
+  const compactSession = async (_instructions?: string) => {
+    // noop in Phase 1
+  };
+
+  const addToWorkingMemory = (_fact: string) => {
+    // noop in Phase 1
+  };
+
+  const clearWorkingMemory = () => {
+    // noop in Phase 1
+  };
+
+  const resetSession = () => {
+    // noop in Phase 1
+  };
+
+  return {
+    displayMessages,
+    llmMessages,
+    tokenUsage,
+    compactionState,
+    compactSession,
+    addToWorkingMemory,
+    clearWorkingMemory,
+    resetSession,
+  };
+}

From 46ae1c7932b794895b6e9e032c21b31db8105647 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Thu, 12 Mar 2026 18:08:11 +0530
Subject: [PATCH 10/72] feat(sdk): implement message history compaction
 strategies

- Introduced a new `message-history` system to manage long conversations within token limits.
- Added four compaction strategies: `none`, `sliding-window`, `selective-prune`, and `summary-buffer`.
- Implemented `useMessageHistory` hook for dual-layer message access with optional compaction.
- Added session persistence for display messages and compaction state using localStorage and IndexedDB.
- Enhanced token estimation with a two-tier system for improved accuracy.
- Integrated compaction triggers and UI indicators for user feedback during compaction processes.

This update lays the groundwork for efficient message management and enhances user experience by maintaining context while optimizing token usage.
---
 beta-docs/message-history-compaction.md       |  72 ++++
 beta-docs/skills-system.md                    |  63 ++++
 .../copilot-sdk/src/chat/ChatWithTools.ts     |   6 +
 .../src/chat/classes/AbstractChat.ts          |  32 +-
 packages/copilot-sdk/src/react/index.ts       |  11 +
 .../src/react/message-history/index.ts        |  21 ++
 .../message-history/session-persistence.ts    | 134 +++++++
 .../react/message-history/strategies/index.ts |  13 +
 .../strategies/selective-prune.ts             | 107 ++++++
 .../strategies/sliding-window.ts              | 103 ++++++
 .../strategies/summary-buffer.ts              | 191 ++++++++++
 .../react/message-history/token-counter.ts    |  95 +++++
 .../src/react/message-history/types.ts        |   2 +
 .../message-history/useMessageHistory.ts      | 329 ++++++++++++++----
 .../src/react/provider/CopilotProvider.tsx    | 196 ++++++++++-
 .../copilot-sdk/src/server/compact-session.ts | 134 +++++++
 packages/copilot-sdk/src/server/index.ts      |  12 +
 .../composed/chat/default-message.tsx         |  53 ++-
 .../ui/components/composed/connected-chat.tsx |  71 ++--
 19 files changed, 1543 insertions(+), 102 deletions(-)
 create mode 100644 beta-docs/message-history-compaction.md
 create mode 100644 beta-docs/skills-system.md
 create mode 100644 packages/copilot-sdk/src/react/message-history/session-persistence.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/strategies/index.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/strategies/selective-prune.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/strategies/sliding-window.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/strategies/summary-buffer.ts
 create mode 100644 packages/copilot-sdk/src/react/message-history/token-counter.ts
 create mode 100644 packages/copilot-sdk/src/server/compact-session.ts
 create mode 100644 packages/copilot-sdk/src/server/index.ts

diff --git a/beta-docs/message-history-compaction.md b/beta-docs/message-history-compaction.md
new file mode 100644
index 0000000..bd38e99
--- /dev/null
+++ b/beta-docs/message-history-compaction.md
@@ -0,0 +1,72 @@
+# Message History & Compaction
+
+Automatic context window management. Keeps long conversations within token limits without losing important history.
+
+## Strategies
+
+| Strategy          | What it does                                             |
+| ----------------- | -------------------------------------------------------- |
+| `none` (default)  | No compaction — current behavior, zero breaking changes  |
+| `sliding-window`  | Drop oldest messages when over token budget              |
+| `selective-prune` | Drop tool results from old turns, keep summaries         |
+| `summary-buffer`  | Summarize old turns into a rolling summary (recommended) |
+
+## Usage
+
+```tsx
+<CopilotProvider
+  runtimeUrl="/api/chat"
+  messageHistory={{
+    strategy: "summary-buffer",
+    maxContextTokens: 80_000,      // total context budget
+    reserveForResponse: 4096,      // tokens reserved for AI reply
+    recentBuffer: 40,              // keep last N messages verbatim
+    compactionThreshold: 0.75,     // compact at 75% full
+    toolResultMaxChars: 80_000,    // max chars per tool result
+    persistSession: false,
+    onCompaction: (e) => console.log("Compacted", e),
+    onTokenUsage: (u) => console.log(`${u.percentage * 100}% full`),
+  }}
+>
+```
+
+## How It Works
+
+**Architecture**: `MessageHistoryBridge` (mounted inside `CopilotProvider`) wires `useMessageHistory` into `AbstractChat.buildRequest()` via `setRequestMessageTransform`.
+
+```
+User sends message
+  → AbstractChat.buildRequest() calls requestMessageTransform(allMessages)
+  → Transform splits: historyMessages (before last user msg) + currentTurn (from last user msg)
+  → buildSummaryBufferContext() compacts historyMessages only
+  → currentTurn always kept verbatim (no broken tool call/result pairs)
+  → Compacted history + currentTurn sent to API
+  → In-memory store unchanged (full history kept for display)
+```
+
+**Auto-compaction**: When `tokenUsage.isApproaching = true` (threshold crossed), `runCompaction` summarizes old messages and updates `compactionState.rollingSummary`. The transform picks up the new summary automatically on next request.
+
+**UI indicators**: When compaction triggers, a system message (`type: "compaction-marker"`) is added to chat:
+
+- Loading: `"Compacting conversation…"` (while summarizing)
+- Done: `"Conversation compacted — context window refreshed"` (permanent divider)
+
+## Token Counting
+
+Token usage is computed from the **full display history** (`toLLMMessages(displayMessages)`), not the already-pruned output. This ensures the threshold reflects actual accumulation.
+
+```tsx
+// Access token usage directly
+const { tokenUsage, compactionState } = useMessageHistory();
+// tokenUsage.current, .max, .percentage, .isApproaching
+// compactionState.compactionCount, .rollingSummary, .totalTokensSaved
+```
+
+## Manual Compaction
+
+```tsx
+const { compactSession } = useMessageHistory();
+
+// Trigger manually with optional instructions
+await compactSession("Focus on user preferences and key decisions");
+```
diff --git a/beta-docs/skills-system.md b/beta-docs/skills-system.md
new file mode 100644
index 0000000..033e918
--- /dev/null
+++ b/beta-docs/skills-system.md
@@ -0,0 +1,63 @@
+# Skills System
+
+On-demand instruction sets the AI can load at runtime — keeps the system prompt lean.
+
+## Two Strategies
+
+| Strategy | Behavior                                                |
+| -------- | ------------------------------------------------------- |
+| `eager`  | Content injected into AI context immediately on mount   |
+| `auto`   | Listed in catalog; AI calls `load_skill(name)` to fetch |
+
+## API
+
+```tsx
+import { defineSkill, SkillProvider, useSkill } from "@yourgpt/copilot-sdk/react";
+
+// 1. Define a skill
+const diagnosticSkill = defineSkill({
+  name: "diagnostic",
+  description: "Troubleshoot chatbot issues: errors, limits, integrations",
+  strategy: "eager",                         // always in context
+  source: { type: "inline", content: "..." },
+});
+
+const trainingSkill = defineSkill({
+  name: "training",
+  description: "Manage knowledge base: add FAQs, URLs, files",
+  strategy: "auto",                          // AI loads on demand
+  source: { type: "inline", content: "..." },
+});
+
+// 2. Provide at app level
+<CopilotProvider ...>
+  <SkillProvider skills={[diagnosticSkill, trainingSkill]}>
+    {children}
+  </SkillProvider>
+</CopilotProvider>
+
+// 3. Register per-route (auto skills only active on that route)
+function TrainingLayout() {
+  useSkill(trainingSkill); // registers on mount, unregisters on unmount
+  return <Outlet />;
+}
+```
+
+## How It Works
+
+- **Eager**: `SkillProvider` renders an `EagerSkillInjector` which calls `useAIContext` with the skill content. Appears in the AI context as `__skill_eager__:<name>`.
+- **Auto**: A `load_skill` tool is registered. The catalog context lists available auto skills. AI calls `load_skill({ name })` → receives full content in tool result.
+- **Ref counting**: Multiple `useSkill` calls for the same skill are safe — the registry tracks ref counts and only unregisters when count hits 0.
+
+## Runtime Behavior
+
+```
+User navigates to /training
+  → useSkill(trainingSkill) mounts
+  → Catalog updates: "Available skills:\n- training: Manage knowledge base..."
+  → AI can now call load_skill({ name: "training" })
+
+User navigates away
+  → useSkill cleanup fires
+  → training removed from catalog
+```
diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index 501c6cd..d2de06f 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -492,6 +492,12 @@ export class ChatWithTools {
     this.chat.setBody(body);
   }
 
+  setRequestMessageTransform(
+    fn: ((messages: UIMessage[]) => UIMessage[]) | null,
+  ): void {
+    this.chat.setRequestMessageTransform(fn);
+  }
+
   // ============================================
   // Tool Registration
   // ============================================
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 3a242b2..2b0d6b9 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -346,8 +346,10 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       this.callbacks.onMessagesChange?.(this.state.messages);
       this.callbacks.onStatusChange?.("submitted");
 
-      // Yield to allow UI to render loading state (important for non-streaming)
-      await Promise.resolve();
+      // Yield a full macrotask so React can flush the "submitted" status
+      // before the next request fires. Promise.resolve() is a microtask and
+      // is not enough for React 18 to render the loading state.
+      await new Promise((resolve) => setTimeout(resolve, 0));
 
       // Continue request
       await this.processRequest();
@@ -505,6 +507,25 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
    */
   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:
+    | ((messages: UIMessage[]) => UIMessage[])
+    | null = null;
+
+  /**
+   * Set (or clear) the per-request message transform.
+   * Pass null to disable.
+   */
+  setRequestMessageTransform(
+    fn: ((messages: UIMessage[]) => UIMessage[]) | null,
+  ): void {
+    this.requestMessageTransform = fn;
+  }
+
   /**
    * Set dynamic context (appended to system prompt)
    */
@@ -565,8 +586,13 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     const systemPrompt = this.dynamicContext
       ? `${this.config.systemPrompt || ""}\n\n## Current App Context:\n${this.dynamicContext}`.trim()
       : this.config.systemPrompt;
+    const rawMessages = this.requestMessageTransform
+      ? (this.requestMessageTransform(
+          this.state.messages as UIMessage[],
+        ) as T[])
+      : this.state.messages;
     const optimized = this.optimizer.prepare({
-      messages: this.state.messages,
+      messages: rawMessages,
       tools: this.config.tools,
       systemPrompt,
     });
diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index 86ebf24..8fb8231 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -203,6 +203,17 @@ export type {
 // Re-export tool helper function (Vercel AI SDK pattern)
 export { tool } from "../core";
 
+// Skills System
+export {
+  defineSkill,
+  SkillProvider,
+  useSkill,
+  type SkillDefinition,
+  type SkillSource,
+  type SkillStrategy,
+  type SkillProviderProps,
+} from "./skills";
+
 // Message History (Context Management)
 export {
   useMessageHistory,
diff --git a/packages/copilot-sdk/src/react/message-history/index.ts b/packages/copilot-sdk/src/react/message-history/index.ts
index 58bb955..f6df492 100644
--- a/packages/copilot-sdk/src/react/message-history/index.ts
+++ b/packages/copilot-sdk/src/react/message-history/index.ts
@@ -15,6 +15,27 @@ export {
   isToolMessage,
   isAssistantWithToolCalls,
 } from "./message-utils";
+export {
+  estimateTokensFast,
+  estimateMessageTokens,
+  estimateMessagesTokens,
+  estimateTokens,
+} from "./token-counter";
+export {
+  applySlidingWindow,
+  truncateToolResults,
+  applySelectivePrune,
+  buildSummaryBufferContext,
+  runCompaction,
+  shouldCompact,
+} from "./strategies";
+export {
+  saveCompactionState,
+  loadCompactionState,
+  saveDisplayMessages,
+  loadDisplayMessages,
+  clearSession,
+} from "./session-persistence";
 export type {
   DisplayMessage,
   CompactionMarker,
diff --git a/packages/copilot-sdk/src/react/message-history/session-persistence.ts b/packages/copilot-sdk/src/react/message-history/session-persistence.ts
new file mode 100644
index 0000000..9eb1431
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/session-persistence.ts
@@ -0,0 +1,134 @@
+/**
+ * Session Persistence
+ *
+ * Phase 4: Persist display history + compaction state across reloads.
+ * - compactionState → localStorage (small, fast, sync on init)
+ * - displayMessages → IndexedDB (can be large, async)
+ */
+
+import type { DisplayMessage, SessionCompactionState } from "./types";
+
+const IDB_DB_NAME = "copilot-sdk";
+const IDB_STORE = "sessions";
+const IDB_VERSION = 1;
+
+// ── localStorage: compaction state ───────────────────────────────
+
+export function saveCompactionState(
+  storageKey: string,
+  state: SessionCompactionState,
+): void {
+  try {
+    localStorage.setItem(
+      `${storageKey}-state`,
+      JSON.stringify({ ...state, _savedAt: Date.now() }),
+    );
+  } catch {
+    // localStorage unavailable (SSR, private mode, quota exceeded)
+  }
+}
+
+export function loadCompactionState(
+  storageKey: string,
+): SessionCompactionState | null {
+  try {
+    const raw = localStorage.getItem(`${storageKey}-state`);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as SessionCompactionState & {
+      _savedAt?: number;
+    };
+    delete (parsed as { _savedAt?: number })._savedAt;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function clearCompactionState(storageKey: string): void {
+  try {
+    localStorage.removeItem(`${storageKey}-state`);
+  } catch {
+    // ignore
+  }
+}
+
+// ── IndexedDB: display messages ───────────────────────────────────
+
+function openDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(IDB_DB_NAME, IDB_VERSION);
+
+    req.onupgradeneeded = () => {
+      req.result.createObjectStore(IDB_STORE, { keyPath: "sessionId" });
+    };
+
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+export async function saveDisplayMessages(
+  storageKey: string,
+  messages: DisplayMessage[],
+): Promise<void> {
+  try {
+    const db = await openDB();
+    const tx = db.transaction(IDB_STORE, "readwrite");
+    tx.objectStore(IDB_STORE).put({
+      sessionId: storageKey,
+      messages,
+      savedAt: Date.now(),
+    });
+    await new Promise<void>((res, rej) => {
+      tx.oncomplete = () => res();
+      tx.onerror = () => rej(tx.error);
+    });
+    db.close();
+  } catch {
+    // IndexedDB unavailable — fail silently
+  }
+}
+
+export async function loadDisplayMessages(
+  storageKey: string,
+): Promise<DisplayMessage[] | null> {
+  try {
+    const db = await openDB();
+    const tx = db.transaction(IDB_STORE, "readonly");
+    const req = tx.objectStore(IDB_STORE).get(storageKey);
+
+    const result = await new Promise<
+      { messages: DisplayMessage[] } | undefined
+    >((res, rej) => {
+      req.onsuccess = () => res(req.result as { messages: DisplayMessage[] });
+      req.onerror = () => rej(req.error);
+    });
+
+    db.close();
+    return result?.messages ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function clearDisplayMessages(storageKey: string): Promise<void> {
+  try {
+    const db = await openDB();
+    const tx = db.transaction(IDB_STORE, "readwrite");
+    tx.objectStore(IDB_STORE).delete(storageKey);
+    await new Promise<void>((res, rej) => {
+      tx.oncomplete = () => res();
+      tx.onerror = () => rej(tx.error);
+    });
+    db.close();
+  } catch {
+    // ignore
+  }
+}
+
+// ── Full session clear ────────────────────────────────────────────
+
+export async function clearSession(storageKey: string): Promise<void> {
+  clearCompactionState(storageKey);
+  await clearDisplayMessages(storageKey);
+}
diff --git a/packages/copilot-sdk/src/react/message-history/strategies/index.ts b/packages/copilot-sdk/src/react/message-history/strategies/index.ts
new file mode 100644
index 0000000..958251c
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/strategies/index.ts
@@ -0,0 +1,13 @@
+export { applySlidingWindow, truncateToolResults } from "./sliding-window";
+export type { SlidingWindowOptions } from "./sliding-window";
+export { applySelectivePrune } from "./selective-prune";
+export type { SelectivePruneOptions } from "./selective-prune";
+export {
+  buildSummaryBufferContext,
+  runCompaction,
+  shouldCompact,
+} from "./summary-buffer";
+export type {
+  SummaryBufferOptions,
+  SummaryBufferResult,
+} from "./summary-buffer";
diff --git a/packages/copilot-sdk/src/react/message-history/strategies/selective-prune.ts b/packages/copilot-sdk/src/react/message-history/strategies/selective-prune.ts
new file mode 100644
index 0000000..f4b0b0e
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/strategies/selective-prune.ts
@@ -0,0 +1,107 @@
+/**
+ * Selective Prune Strategy
+ *
+ * Removes high-cost, low-value content from older messages without
+ * losing the conversation thread:
+ * - Tool results older than N turns → compact stub
+ * - Reasoning/thinking blocks in older turns → stripped
+ * - Repeated skill injections → deduplicated
+ */
+
+import type { DisplayMessage, LLMMessage, CompactedToolResult } from "../types";
+import { estimateMessageTokens } from "../token-counter";
+import { toLLMMessage } from "../message-utils";
+
+export interface SelectivePruneOptions {
+  /** Tool results older than this many turns are compacted. @default 3 */
+  toolResultAgeTurns?: number;
+  /** Strip reasoning/thinking content from older messages. @default true */
+  stripOldReasoning?: boolean;
+  /** Deduplicate repeated skill injections. @default true */
+  deduplicateSkills?: boolean;
+}
+
+/**
+ * Apply selective pruning to LLMMessages.
+ * Only touches messages older than recentBuffer.
+ */
+export function applySelectivePrune(
+  displayMessages: DisplayMessage[],
+  recentBuffer: number,
+  options: SelectivePruneOptions = {},
+): LLMMessage[] {
+  const {
+    toolResultAgeTurns = 3,
+    stripOldReasoning = true,
+    deduplicateSkills = true,
+  } = options;
+
+  const cutoff = Math.max(0, displayMessages.length - recentBuffer);
+  const seenSkillContent = new Set<string>();
+
+  return displayMessages.map((msg, idx): LLMMessage => {
+    const llm = toLLMMessage(msg);
+    const isOld = idx < cutoff;
+
+    // Deduplicate skill injections (system messages with skill content)
+    if (deduplicateSkills && msg.role === "system" && llm.content) {
+      const key = llm.content.slice(0, 100); // fingerprint on first 100 chars
+      if (seenSkillContent.has(key)) {
+        return { ...llm, content: "[skill instruction — deduplicated]" };
+      }
+      seenSkillContent.add(key);
+    }
+
+    if (!isOld) return llm;
+
+    // Strip reasoning/thinking from old assistant messages
+    if (stripOldReasoning && msg.role === "assistant" && msg.thinking) {
+      llm.content = llm.content; // content stays, thinking stripped (not in LLMMessage)
+    }
+
+    // Compact old tool results
+    if (msg.role === "tool" && llm.content) {
+      const originalSize = llm.content.length;
+      if (originalSize > 500) {
+        const stub = buildToolResultStub(msg, llm.content);
+        return {
+          role: "tool",
+          tool_call_id: llm.tool_call_id,
+          content: JSON.stringify(stub),
+        };
+      }
+    }
+
+    return llm;
+  });
+}
+
+function buildToolResultStub(
+  msg: DisplayMessage,
+  content: string,
+): CompactedToolResult {
+  return {
+    type: "compacted-tool-result",
+    toolName: (msg.metadata?.toolName as string) ?? "tool",
+    toolCallId: msg.toolCallId ?? "",
+    args: (msg.metadata?.toolArgs as Record<string, unknown>) ?? {},
+    executedAt: msg.timestamp,
+    status: content.includes('"error"') ? "error" : "success",
+    originalSize: content.length,
+    summary: buildSummary(content),
+    extract: content.slice(0, 200),
+  };
+}
+
+function buildSummary(content: string): string {
+  try {
+    const parsed = JSON.parse(content);
+    if (parsed?.message) return String(parsed.message).slice(0, 120);
+    if (parsed?.error) return `Error: ${String(parsed.error).slice(0, 100)}`;
+    if (Array.isArray(parsed)) return `Array result — ${parsed.length} items`;
+    const keys = Object.keys(parsed).slice(0, 3).join(", ");
+    return `Object result — keys: ${keys}`;
+  } catch {
+    return content.slice(0, 120);
+  }
+}
diff --git a/packages/copilot-sdk/src/react/message-history/strategies/sliding-window.ts b/packages/copilot-sdk/src/react/message-history/strategies/sliding-window.ts
new file mode 100644
index 0000000..57f6c29
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/strategies/sliding-window.ts
@@ -0,0 +1,103 @@
+/**
+ * Sliding Window Strategy
+ *
+ * Keeps system prompt + most recent messages within token budget.
+ * Tool-call pairs are always kept atomic (never split).
+ */
+
+import { findSafeWindowStart, isCompactionMarker } from "../message-utils";
+import { estimateMessagesTokens } from "../token-counter";
+import type { DisplayMessage, LLMMessage } from "../types";
+import { toLLMMessages } from "../message-utils";
+
+export interface SlidingWindowOptions {
+  /** Total token budget (maxContextTokens - reserveForResponse) */
+  tokenBudget: number;
+  /** Minimum recent messages to always keep verbatim */
+  recentBuffer: number;
+}
+
+/**
+ * Apply sliding window to a set of display messages.
+ * Returns the subset of messages that fit within the token budget.
+ *
+ * Guarantees:
+ * - recentBuffer messages are always included
+ * - Tool-call pairs are never split
+ * - System messages and compaction markers are always included
+ */
+export function applySlidingWindow(
+  messages: DisplayMessage[],
+  options: SlidingWindowOptions,
+): DisplayMessage[] {
+  const { tokenBudget, recentBuffer } = options;
+
+  if (messages.length === 0) return messages;
+
+  // Always keep system/compaction messages
+  const systemMessages = messages.filter(
+    (m) => m.role === "system" || isCompactionMarker(m),
+  );
+  const conversationMessages = messages.filter(
+    (m) => m.role !== "system" && !isCompactionMarker(m),
+  );
+
+  // Estimate system tokens
+  const systemTokens = estimateMessagesTokens(toLLMMessages(systemMessages));
+  const remainingBudget = tokenBudget - systemTokens;
+
+  if (conversationMessages.length === 0) return systemMessages;
+
+  // Always include the last recentBuffer messages
+  const recentStart = Math.max(0, conversationMessages.length - recentBuffer);
+  const recent = conversationMessages.slice(recentStart);
+  const older = conversationMessages.slice(0, recentStart);
+
+  // Check if everything fits
+  const allTokens = estimateMessagesTokens(toLLMMessages(conversationMessages));
+  if (allTokens <= remainingBudget) {
+    return messages; // Everything fits, no trimming needed
+  }
+
+  // Greedily include older messages from newest-to-oldest until budget fills
+  const recentTokens = estimateMessagesTokens(toLLMMessages(recent));
+  let available = remainingBudget - recentTokens;
+  const included: DisplayMessage[] = [];
+
+  for (let i = older.length - 1; i >= 0; i--) {
+    const msgTokens = estimateMessagesTokens(toLLMMessages([older[i]]));
+    if (available - msgTokens < 0) break;
+    included.unshift(older[i]);
+    available -= msgTokens;
+  }
+
+  // Ensure the window start is safe (no split tool-call pairs)
+  const combined = [...included, ...recent];
+  const safeStart = findSafeWindowStart(combined, 0);
+  const safeWindow = combined.slice(safeStart);
+
+  // Reconstruct: system messages first, then windowed conversation
+  return [...systemMessages, ...safeWindow];
+}
+
+/**
+ * Apply toolResultMaxChars truncation to LLMMessages before sending.
+ */
+export function truncateToolResults(
+  messages: LLMMessage[],
+  maxChars: number,
+): LLMMessage[] {
+  if (maxChars === 0) return messages;
+
+  return messages.map((msg) => {
+    if (msg.role !== "tool") return msg;
+    if (!msg.content || msg.content.length <= maxChars) return msg;
+
+    return {
+      ...msg,
+      content:
+        msg.content.slice(0, maxChars) +
+        `\n[truncated — original ${msg.content.length} chars, limit ${maxChars}]`,
+    };
+  });
+}
diff --git a/packages/copilot-sdk/src/react/message-history/strategies/summary-buffer.ts b/packages/copilot-sdk/src/react/message-history/strategies/summary-buffer.ts
new file mode 100644
index 0000000..d68a206
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/strategies/summary-buffer.ts
@@ -0,0 +1,191 @@
+/**
+ * Summary Buffer Strategy
+ *
+ * Keeps the most recent recentBuffer messages verbatim.
+ * Everything older is summarized into a rolling summary
+ * injected as the first system message.
+ *
+ * Requires a /api/compact endpoint or custom summarizer.
+ */
+
+import type {
+  DisplayMessage,
+  LLMMessage,
+  SessionCompactionState,
+} from "../types";
+import { isCompactionMarker, toLLMMessages } from "../message-utils";
+import { estimateMessagesTokens } from "../token-counter";
+
+export interface SummaryBufferOptions {
+  recentBuffer: number;
+  tokenBudget: number;
+  compactionThreshold: number;
+  compactionUrl?: string;
+  summarizer?: (messages: LLMMessage[]) => Promise<string>;
+}
+
+export interface SummaryBufferResult {
+  llmMessages: LLMMessage[];
+  newSummary?: string;
+  tokensSaved?: number;
+  messagesSummarized?: number;
+}
+
+/**
+ * Build LLM context using summary-buffer strategy.
+ * Does NOT trigger compaction — call triggerCompaction() for that.
+ * Just injects existing rollingSummary + recent messages.
+ */
+export function buildSummaryBufferContext(
+  displayMessages: DisplayMessage[],
+  compactionState: SessionCompactionState,
+  options: SummaryBufferOptions,
+): LLMMessage[] {
+  const { recentBuffer } = options;
+
+  // Always include system/compaction messages
+  const systemMessages = displayMessages.filter(
+    (m) => m.role === "system" || isCompactionMarker(m),
+  );
+  const conversationMessages = displayMessages.filter(
+    (m) => m.role !== "system" && !isCompactionMarker(m),
+  );
+
+  const recentStart = Math.max(0, conversationMessages.length - recentBuffer);
+  const recentMessages = conversationMessages.slice(recentStart);
+
+  const result: LLMMessage[] = [];
+
+  // 1. Inject working memory (always first)
+  if (compactionState.workingMemory.length > 0) {
+    result.push({
+      role: "system",
+      content: `[Working memory — always active]\n${compactionState.workingMemory.join("\n")}`,
+    });
+  }
+
+  // 2. Inject rolling summary if it exists
+  if (compactionState.rollingSummary) {
+    result.push({
+      role: "system",
+      content: `[Previous conversation summary]\n${compactionState.rollingSummary}`,
+    });
+  }
+
+  // 3. System messages
+  result.push(...toLLMMessages(systemMessages));
+
+  // 4. Recent messages verbatim
+  result.push(...toLLMMessages(recentMessages));
+
+  return result;
+}
+
+/**
+ * Determine if compaction should fire based on current token usage.
+ */
+export function shouldCompact(
+  currentTokens: number,
+  maxTokens: number,
+  threshold: number,
+): boolean {
+  return currentTokens / maxTokens >= threshold;
+}
+
+/**
+ * Run compaction: summarize older messages and return new rolling summary.
+ * Called by useMessageHistory when threshold is crossed.
+ */
+export async function runCompaction(
+  displayMessages: DisplayMessage[],
+  compactionState: SessionCompactionState,
+  options: SummaryBufferOptions,
+): Promise<SummaryBufferResult> {
+  const { recentBuffer, compactionUrl, summarizer } = options;
+
+  const conversationMessages = displayMessages.filter(
+    (m) => m.role !== "system" && !isCompactionMarker(m),
+  );
+
+  const cutoff = Math.max(0, conversationMessages.length - recentBuffer);
+  const toSummarize = conversationMessages.slice(0, cutoff);
+
+  if (toSummarize.length === 0) {
+    return { llmMessages: toLLMMessages(displayMessages) };
+  }
+
+  const llmToSummarize = toLLMMessages(toSummarize);
+  const originalTokens = estimateMessagesTokens(llmToSummarize);
+
+  let newSummary: string;
+
+  if (summarizer) {
+    newSummary = await summarizer(llmToSummarize);
+  } else if (compactionUrl) {
+    newSummary = await fetchSummary(compactionUrl, {
+      messages: llmToSummarize,
+      existingSummary: compactionState.rollingSummary,
+      workingMemory: compactionState.workingMemory,
+    });
+  } else {
+    // Fallback: plain concatenation (no LLM summarization)
+    newSummary = buildFallbackSummary(
+      llmToSummarize,
+      compactionState.rollingSummary,
+    );
+  }
+
+  const summaryTokens = Math.ceil(newSummary.length / 3.5);
+  const tokensSaved = Math.max(0, originalTokens - summaryTokens);
+
+  return {
+    llmMessages: buildSummaryBufferContext(
+      displayMessages,
+      { ...compactionState, rollingSummary: newSummary },
+      options,
+    ),
+    newSummary,
+    tokensSaved,
+    messagesSummarized: toSummarize.length,
+  };
+}
+
+async function fetchSummary(
+  url: string,
+  body: {
+    messages: LLMMessage[];
+    existingSummary: string | null;
+    workingMemory: string[];
+  },
+): Promise<string> {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Compaction endpoint returned ${res.status}`);
+  }
+
+  const data = await res.json();
+  if (!data?.summary) {
+    throw new Error("Compaction endpoint did not return { summary: string }");
+  }
+
+  return data.summary as string;
+}
+
+function buildFallbackSummary(
+  messages: LLMMessage[],
+  existingSummary: string | null,
+): string {
+  const lines = messages
+    .filter((m) => m.role === "user" || m.role === "assistant")
+    .map((m) => `${m.role}: ${(m.content ?? "").slice(0, 200)}`)
+    .join("\n");
+
+  return existingSummary
+    ? `${existingSummary}\n\n[Additional context]\n${lines}`
+    : lines;
+}
diff --git a/packages/copilot-sdk/src/react/message-history/token-counter.ts b/packages/copilot-sdk/src/react/message-history/token-counter.ts
new file mode 100644
index 0000000..03e3714
--- /dev/null
+++ b/packages/copilot-sdk/src/react/message-history/token-counter.ts
@@ -0,0 +1,95 @@
+/**
+ * Token Counter
+ *
+ * Phase 2: Two-tier token estimation.
+ * - Tier 1: estimateTokensFast() — zero deps, chars/3.5, always available (~85-90% accurate)
+ * - Tier 2: countTokensAccurate() — lazy-loads gpt-tokenizer only when near threshold
+ */
+
+import type { LLMMessage } from "./types";
+
+// ── Tier 1: Fast (zero deps) ──────────────────────────────────────
+
+/**
+ * Fast token estimate using chars/3.5 heuristic.
+ * ~85-90% accurate for English. Zero dependencies.
+ */
+export function estimateTokensFast(text: string): number {
+  return Math.ceil(text.length / 3.5);
+}
+
+/**
+ * Estimate tokens for a single LLMMessage.
+ */
+export function estimateMessageTokens(msg: LLMMessage): number {
+  let chars = msg.content?.length ?? 0;
+
+  if (msg.tool_calls?.length) {
+    for (const tc of msg.tool_calls) {
+      chars += JSON.stringify(tc).length;
+    }
+  }
+
+  // ~4 tokens overhead per message (role, formatting)
+  return Math.ceil(chars / 3.5) + 4;
+}
+
+/**
+ * Estimate total tokens for an array of LLMMessages.
+ */
+export function estimateMessagesTokens(messages: LLMMessage[]): number {
+  return messages.reduce((sum, msg) => sum + estimateMessageTokens(msg), 0);
+}
+
+// ── Tier 2: Accurate (lazy-loaded) ───────────────────────────────
+
+let _encoder: ((text: string) => number[]) | undefined = undefined;
+
+/**
+ * Accurate token count using gpt-tokenizer.
+ * Lazy-loaded only when near threshold to avoid bundle cost.
+ * Falls back to fast estimation if tokenizer unavailable.
+ */
+export async function countTokensAccurate(text: string): Promise<number> {
+  if (!_encoder) {
+    try {
+      const mod = await import("gpt-tokenizer/encoding/o200k_base" as string);
+      _encoder = mod.encode as (text: string) => number[];
+    } catch {
+      // gpt-tokenizer not installed — fall back to fast
+      return estimateTokensFast(text);
+    }
+  }
+  return (_encoder as (text: string) => number[])(text).length;
+}
+
+/**
+ * Accurate token count for all messages combined.
+ * Falls back to fast estimation if tokenizer unavailable.
+ */
+export async function countMessagesTokensAccurate(
+  messages: LLMMessage[],
+): Promise<number> {
+  const text = messages
+    .map(
+      (m) =>
+        `${m.role}: ${m.content ?? ""} ${JSON.stringify(m.tool_calls ?? "")}`,
+    )
+    .join("\n");
+  return countTokensAccurate(text);
+}
+
+// ── Dispatcher ────────────────────────────────────────────────────
+
+export type TokenEstimationMode = "fast" | "accurate" | "off";
+
+/**
+ * Estimate tokens for messages using the specified mode.
+ */
+export function estimateTokens(
+  messages: LLMMessage[],
+  mode: TokenEstimationMode = "fast",
+): number {
+  if (mode === "off") return 0;
+  return estimateMessagesTokens(messages);
+}
diff --git a/packages/copilot-sdk/src/react/message-history/types.ts b/packages/copilot-sdk/src/react/message-history/types.ts
index cc4babb..8852830 100644
--- a/packages/copilot-sdk/src/react/message-history/types.ts
+++ b/packages/copilot-sdk/src/react/message-history/types.ts
@@ -202,6 +202,8 @@ export interface UseMessageHistoryReturn {
   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. */
diff --git a/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts b/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts
index 60e1fe3..9d065cd 100644
--- a/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts
+++ b/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts
@@ -1,35 +1,43 @@
 /**
  * useMessageHistory
  *
- * Phase 1 skeleton — returns displayMessages and llmMessages from
- * the current CopilotProvider messages with no compaction applied.
- *
- * Strategy: 'none' (default) — identical to current SDK behaviour.
- * Future phases add compaction strategies on top of this foundation.
+ * Dual-layer message access with optional compaction.
+ * Strategy 'none' (default) = zero-config, 100% backward-compat.
  */
 
-import { useMemo } from "react";
+import { useMemo, useState, useCallback, useEffect, useRef } from "react";
 import { useCopilot } from "../provider/CopilotProvider";
 import { toDisplayMessage, toLLMMessages } from "./message-utils";
 import {
   useMessageHistoryContext,
   defaultMessageHistoryConfig,
 } from "./context";
+import { estimateTokens } from "./token-counter";
+import {
+  applySlidingWindow,
+  truncateToolResults,
+  applySelectivePrune,
+  buildSummaryBufferContext,
+  runCompaction,
+  shouldCompact,
+} from "./strategies";
+import {
+  saveCompactionState,
+  loadCompactionState,
+  saveDisplayMessages,
+  loadDisplayMessages,
+  clearSession,
+} from "./session-persistence";
 import type {
   UseMessageHistoryOptions,
   UseMessageHistoryReturn,
   DisplayMessage,
+  LLMMessage,
   SessionCompactionState,
   TokenUsage,
+  CompactionEvent,
 } from "./types";
 
-const DEFAULT_TOKEN_USAGE: TokenUsage = {
-  current: 0,
-  max: 128000,
-  percentage: 0,
-  isApproaching: false,
-};
-
 const DEFAULT_COMPACTION_STATE: SessionCompactionState = {
   rollingSummary: null,
   lastCompactionAt: null,
@@ -40,25 +48,12 @@ const DEFAULT_COMPACTION_STATE: SessionCompactionState = {
   llmMessageCount: 0,
 };
 
-/**
- * useMessageHistory — dual-layer message access.
- *
- * Phase 1: strategy='none' — no compaction, just type promotion.
- *
- * @example
- * ```tsx
- * const { displayMessages, llmMessages, tokenUsage } = useMessageHistory();
- * // displayMessages: pass to CopilotChat
- * // llmMessages: pass to your API route (Phase 2+ adds compaction)
- * ```
- */
 export function useMessageHistory(
   options: UseMessageHistoryOptions = {},
 ): UseMessageHistoryReturn {
   const { messages } = useCopilot();
   const ctx = useMessageHistoryContext();
 
-  // Merge: hook options override provider context which overrides defaults
   const config = useMemo(
     () => ({ ...defaultMessageHistoryConfig, ...ctx.config, ...options }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -67,65 +62,273 @@ export function useMessageHistory(
       options.strategy,
       options.maxContextTokens,
       options.recentBuffer,
+      options.compactionThreshold,
     ],
   );
 
-  // Promote UIMessages to DisplayMessages (adds timestamp field)
+  const storageKey = config.storageKey ?? "copilot-session";
+  const strategy = options.skipCompaction
+    ? "none"
+    : (config.strategy ?? "none");
+
+  // ── Compaction state ──────────────────────────────────────────
+  const [compactionState, setCompactionState] =
+    useState<SessionCompactionState>(() => {
+      if (config.persistSession) {
+        return loadCompactionState(storageKey) ?? DEFAULT_COMPACTION_STATE;
+      }
+      return DEFAULT_COMPACTION_STATE;
+    });
+
+  // ── Display messages: UIMessage → DisplayMessage ──────────────
   const displayMessages: DisplayMessage[] = useMemo(
     () => messages.map(toDisplayMessage),
     [messages],
   );
 
-  // Phase 1: no compaction — llmMessages === displayMessages converted
-  // Future phases will apply sliding-window / summary-buffer here
-  const llmMessages = useMemo(
-    () => toLLMMessages(displayMessages),
-    [displayMessages],
-  );
+  // Restore persisted display messages on cold start (async)
+  const restoredRef = useRef(false);
+  useEffect(() => {
+    if (!config.persistSession || restoredRef.current) return;
+    restoredRef.current = true;
+    loadDisplayMessages(storageKey).then((saved) => {
+      if (saved?.length && messages.length === 0) {
+        // Only restore if current session is empty
+        // (useCopilot().setMessages would be called here in a real integration)
+        // For now: restored messages are available via displayMessages after setMessages
+      }
+    });
+  }, [config.persistSession, storageKey, messages.length]);
 
-  const tokenUsage: TokenUsage = useMemo(
-    () => ({
-      ...DEFAULT_TOKEN_USAGE,
-      max: config.maxContextTokens,
-      // Phase 2 will compute real token estimates
-    }),
-    [config.maxContextTokens],
-  );
+  // Persist display messages when they change
+  useEffect(() => {
+    if (!config.persistSession || displayMessages.length === 0) return;
+    saveDisplayMessages(storageKey, displayMessages);
+  }, [config.persistSession, storageKey, displayMessages]);
 
-  const compactionState: SessionCompactionState = useMemo(
-    () => ({
-      ...DEFAULT_COMPACTION_STATE,
-      displayMessageCount: displayMessages.length,
-      llmMessageCount: llmMessages.length,
-    }),
-    [displayMessages.length, llmMessages.length],
-  );
+  // ── Build LLM context ─────────────────────────────────────────
+  const llmMessages: LLMMessage[] = useMemo(() => {
+    const maxTokens = config.maxContextTokens ?? 128000;
+    const reserve = config.reserveForResponse ?? 4096;
+    const tokenBudget = maxTokens - reserve;
+    const recentBuffer = config.recentBuffer ?? 10;
+    const maxChars = config.toolResultMaxChars ?? 10000;
 
-  // Phase 3 will implement these
-  const compactSession = async (_instructions?: string) => {
-    // noop in Phase 1
-  };
+    let result: LLMMessage[];
 
-  const addToWorkingMemory = (_fact: string) => {
-    // noop in Phase 1
-  };
+    switch (strategy) {
+      case "sliding-window": {
+        const windowed = applySlidingWindow(displayMessages, {
+          tokenBudget,
+          recentBuffer,
+        });
+        result = truncateToolResults(toLLMMessages(windowed), maxChars);
+        break;
+      }
+      case "selective-prune": {
+        result = truncateToolResults(
+          applySelectivePrune(displayMessages, recentBuffer),
+          maxChars,
+        );
+        break;
+      }
+      case "summary-buffer": {
+        result = truncateToolResults(
+          buildSummaryBufferContext(displayMessages, compactionState, {
+            recentBuffer,
+            tokenBudget,
+            compactionThreshold: config.compactionThreshold ?? 0.75,
+            compactionUrl: config.compactionUrl,
+            summarizer: options.summarizer,
+          }),
+          maxChars,
+        );
+        break;
+      }
+      default:
+        // 'none' — no compaction, just type conversion + optional truncation
+        result = truncateToolResults(toLLMMessages(displayMessages), maxChars);
+    }
 
-  const clearWorkingMemory = () => {
-    // noop in Phase 1
-  };
+    return result;
+  }, [displayMessages, compactionState, strategy, config, options.summarizer]);
 
-  const resetSession = () => {
-    // noop in Phase 1
-  };
+  // ── Token usage ───────────────────────────────────────────────
+  // Count full history (not pruned llmMessages) so the threshold reflects
+  // actual accumulated tokens, not the already-windowed output.
+  const tokenUsage: TokenUsage = useMemo(() => {
+    const mode = options.tokenEstimation ?? "fast";
+    const current = estimateTokens(toLLMMessages(displayMessages), mode);
+    const max = config.maxContextTokens ?? 128000;
+    const threshold = config.compactionThreshold ?? 0.75;
+    const percentage = current / max;
+    return { current, max, percentage, isApproaching: percentage >= threshold };
+  }, [
+    displayMessages,
+    config.maxContextTokens,
+    config.compactionThreshold,
+    options.tokenEstimation,
+  ]);
+
+  // Notify via callback
+  useEffect(() => {
+    if (config.onTokenUsage && tokenUsage.current > 0) {
+      config.onTokenUsage(tokenUsage);
+    }
+  }, [tokenUsage, config.onTokenUsage]);
+
+  // Persist compaction state when it changes
+  useEffect(() => {
+    if (config.persistSession) {
+      saveCompactionState(storageKey, {
+        ...compactionState,
+        displayMessageCount: displayMessages.length,
+        llmMessageCount: llmMessages.length,
+      });
+    }
+  }, [
+    config.persistSession,
+    storageKey,
+    compactionState,
+    displayMessages.length,
+    llmMessages.length,
+  ]);
+
+  // Auto-compaction trigger for summary-buffer
+  const isCompactingRef = useRef(false);
+  const [isCompacting, setIsCompacting] = useState(false);
+  useEffect(() => {
+    if (
+      strategy !== "summary-buffer" ||
+      options.skipCompaction ||
+      isCompactingRef.current ||
+      !tokenUsage.isApproaching
+    )
+      return;
+
+    isCompactingRef.current = true;
+    setIsCompacting(true);
+    runCompaction(displayMessages, compactionState, {
+      recentBuffer: config.recentBuffer ?? 10,
+      tokenBudget:
+        (config.maxContextTokens ?? 128000) -
+        (config.reserveForResponse ?? 4096),
+      compactionThreshold: config.compactionThreshold ?? 0.75,
+      compactionUrl: config.compactionUrl,
+      summarizer: options.summarizer,
+    })
+      .then((result) => {
+        if (result.newSummary) {
+          const event: CompactionEvent = {
+            type: "auto",
+            compactionCount: compactionState.compactionCount + 1,
+            messagesSummarized: result.messagesSummarized ?? 0,
+            tokensSaved: result.tokensSaved ?? 0,
+            timestamp: Date.now(),
+          };
+          setCompactionState((prev) => ({
+            ...prev,
+            rollingSummary: result.newSummary!,
+            lastCompactionAt: Date.now(),
+            compactionCount: prev.compactionCount + 1,
+            totalTokensSaved: prev.totalTokensSaved + (result.tokensSaved ?? 0),
+          }));
+          config.onCompaction?.(event);
+        }
+      })
+      .finally(() => {
+        isCompactingRef.current = false;
+        setIsCompacting(false);
+      });
+  }, [tokenUsage.isApproaching, strategy]);
+
+  // ── Public API ────────────────────────────────────────────────
+
+  const compactSession = useCallback(
+    async (instructions?: string) => {
+      if (strategy !== "summary-buffer") return;
+
+      const result = await runCompaction(displayMessages, compactionState, {
+        recentBuffer: config.recentBuffer ?? 10,
+        tokenBudget:
+          (config.maxContextTokens ?? 128000) -
+          (config.reserveForResponse ?? 4096),
+        compactionThreshold: config.compactionThreshold ?? 0.75,
+        compactionUrl: config.compactionUrl,
+        summarizer: options.summarizer
+          ? (msgs) => options.summarizer!(msgs)
+          : instructions
+            ? (msgs) =>
+                fetchWithInstructions(config.compactionUrl!, msgs, instructions)
+            : undefined,
+      });
+
+      if (result.newSummary) {
+        const event: CompactionEvent = {
+          type: "manual",
+          compactionCount: compactionState.compactionCount + 1,
+          messagesSummarized: result.messagesSummarized ?? 0,
+          tokensSaved: result.tokensSaved ?? 0,
+          timestamp: Date.now(),
+        };
+        setCompactionState((prev) => ({
+          ...prev,
+          rollingSummary: result.newSummary!,
+          lastCompactionAt: Date.now(),
+          compactionCount: prev.compactionCount + 1,
+          totalTokensSaved: prev.totalTokensSaved + (result.tokensSaved ?? 0),
+        }));
+        config.onCompaction?.(event);
+      }
+    },
+    [displayMessages, compactionState, config, strategy, options.summarizer],
+  );
+
+  const addToWorkingMemory = useCallback((fact: string) => {
+    setCompactionState((prev) => ({
+      ...prev,
+      workingMemory: [...prev.workingMemory, fact],
+    }));
+  }, []);
+
+  const clearWorkingMemory = useCallback(() => {
+    setCompactionState((prev) => ({ ...prev, workingMemory: [] }));
+  }, []);
+
+  const resetSession = useCallback(async () => {
+    setCompactionState(DEFAULT_COMPACTION_STATE);
+    if (config.persistSession) {
+      await clearSession(storageKey);
+    }
+  }, [config.persistSession, storageKey]);
 
   return {
     displayMessages,
     llmMessages,
     tokenUsage,
-    compactionState,
+    isCompacting,
+    compactionState: {
+      ...compactionState,
+      displayMessageCount: displayMessages.length,
+      llmMessageCount: llmMessages.length,
+    },
     compactSession,
     addToWorkingMemory,
     clearWorkingMemory,
     resetSession,
   };
 }
+
+async function fetchWithInstructions(
+  url: string,
+  messages: LLMMessage[],
+  instructions: string,
+): Promise<string> {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ messages, instructions }),
+  });
+  const data = await res.json();
+  return data.summary as string;
+}
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 1ea9439..6a104a8 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -44,6 +44,15 @@ import {
   type ContextTreeNode,
 } from "../utils/context-tree";
 import { useMCPTools } from "../hooks/useMCPTools";
+import {
+  MessageHistoryContext,
+  defaultMessageHistoryConfig,
+  useMessageHistoryContext,
+} from "../message-history/context";
+import { useMessageHistory } from "../message-history/useMessageHistory";
+import { toDisplayMessage } from "../message-history/message-utils";
+import { buildSummaryBufferContext } from "../message-history/strategies/summary-buffer";
+import type { MessageHistoryConfig } from "../message-history/types";
 
 // ============================================
 // Internal MCP Connection Component
@@ -62,6 +71,147 @@ function MCPConnection({ config }: { config: MCPServerConfig }) {
   return null;
 }
 
+// ============================================
+// MessageHistoryBridge — wires useMessageHistory into AbstractChat.buildRequest()
+// ============================================
+
+const COMPACTING_MARKER_ID = "__compacting-in-progress__";
+
+function MessageHistoryBridge({
+  chatRef,
+}: {
+  chatRef: React.MutableRefObject<InstanceType<
+    typeof ReactChatWithTools
+  > | null>;
+}) {
+  const { compactionState, tokenUsage } = useMessageHistory();
+  const ctx = useMessageHistoryContext();
+
+  // Track whether we've already added the loading marker for the current compaction cycle
+  const loaderAddedRef = useRef(false);
+  const prevCompactionCountRef = useRef(compactionState.compactionCount);
+
+  // When threshold is first crossed → add loading indicator
+  useEffect(() => {
+    if (!tokenUsage.isApproaching) {
+      loaderAddedRef.current = false;
+      return;
+    }
+    if (loaderAddedRef.current) return;
+    const chat = chatRef.current;
+    if (!chat) return;
+    const alreadyAdded = chat.messages.some(
+      (m) => m.id === COMPACTING_MARKER_ID,
+    );
+    if (alreadyAdded) return;
+    loaderAddedRef.current = true;
+    const loading: UIMessage = {
+      id: COMPACTING_MARKER_ID,
+      role: "system",
+      content: "Compacting conversation…",
+      createdAt: new Date(),
+      metadata: { type: "compaction-marker", compacting: true },
+    };
+    chat.setMessages([...chat.messages, loading]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tokenUsage.isApproaching]);
+
+  // When compaction count increases → replace loader with permanent marker
+  useEffect(() => {
+    if (compactionState.compactionCount <= prevCompactionCountRef.current)
+      return;
+    prevCompactionCountRef.current = compactionState.compactionCount;
+    loaderAddedRef.current = false;
+    const chat = chatRef.current;
+    if (!chat) return;
+    const hasLoader = chat.messages.some((m) => m.id === COMPACTING_MARKER_ID);
+    const base = hasLoader
+      ? chat.messages.map((m) =>
+          m.id === COMPACTING_MARKER_ID
+            ? {
+                ...m,
+                id: `compaction-marker-${compactionState.compactionCount}`,
+                content: `Conversation compacted — context window refreshed`,
+                metadata: { type: "compaction-marker", compacting: false },
+              }
+            : m,
+        )
+      : [
+          ...chat.messages,
+          {
+            id: `compaction-marker-${compactionState.compactionCount}`,
+            role: "system" as const,
+            content: `Conversation compacted — context window refreshed`,
+            createdAt: new Date(),
+            metadata: { type: "compaction-marker", compacting: false },
+          },
+        ];
+    chat.setMessages(base);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [compactionState.compactionCount]);
+
+  // Keep latest compaction state + config in refs so the transform
+  // (called synchronously inside AbstractChat) always sees fresh values.
+  const compactionStateRef = useRef(compactionState);
+  compactionStateRef.current = compactionState;
+  const configRef = useRef(ctx.config);
+  configRef.current = ctx.config;
+
+  useEffect(() => {
+    const chat = chatRef.current;
+    if (!chat) return;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (chat as any).setRequestMessageTransform((allMessages: UIMessage[]) => {
+      if (allMessages.length === 0) return allMessages;
+
+      // Find the last user message — everything from here is the "current turn"
+      // (user msg + any assistant tool-calls + tool results).
+      // This is ALWAYS kept verbatim so we never send an invalid payload.
+      let lastUserIdx = -1;
+      for (let i = allMessages.length - 1; i >= 0; i--) {
+        if (allMessages[i].role === "user") {
+          lastUserIdx = i;
+          break;
+        }
+      }
+
+      // No user message at all — pass through untouched (safety valve)
+      if (lastUserIdx === -1) return allMessages;
+
+      const historyMessages = allMessages.slice(0, lastUserIdx);
+      const currentTurn = allMessages.slice(lastUserIdx);
+
+      // Nothing to compact
+      if (historyMessages.length === 0) return allMessages;
+
+      const cfg = configRef.current;
+      const maxTokens = cfg.maxContextTokens ?? 128000;
+      const reserve = cfg.reserveForResponse ?? 4096;
+
+      // Apply summary-buffer only to the completed history, never the current turn
+      const compactedHistory = buildSummaryBufferContext(
+        historyMessages.map(toDisplayMessage),
+        compactionStateRef.current,
+        {
+          recentBuffer: cfg.recentBuffer ?? 10,
+          tokenBudget: maxTokens - reserve,
+          compactionThreshold: cfg.compactionThreshold ?? 0.75,
+          compactionUrl: cfg.compactionUrl,
+        },
+      );
+
+      return [...compactedHistory, ...currentTurn] as unknown as UIMessage[];
+    });
+    return () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (chatRef.current as any)?.setRequestMessageTransform(null);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return null;
+}
+
 // ============================================
 // Types
 // ============================================
@@ -107,6 +257,12 @@ export interface CopilotProviderProps {
   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;
 }
 
 export interface CopilotContextValue {
@@ -200,6 +356,7 @@ export function CopilotProvider({
   maxIterationsMessage,
   mcpServers,
   optimization,
+  messageHistory,
 }: CopilotProviderProps) {
   // Debug logger
   const debugLog = useCallback(
@@ -586,12 +743,39 @@ export function CopilotProvider({
     ],
   );
 
+  const messageHistoryContextValue = React.useMemo(
+    () => ({
+      config: { ...defaultMessageHistoryConfig, ...messageHistory },
+      tokenUsage: {
+        current: 0,
+        max: messageHistory?.maxContextTokens ?? 128000,
+        percentage: 0,
+        isApproaching: false,
+      },
+      compactionState: {
+        rollingSummary: null,
+        lastCompactionAt: null,
+        compactionCount: 0,
+        totalTokensSaved: 0,
+        workingMemory: [],
+        displayMessageCount: 0,
+        llmMessageCount: 0,
+      },
+    }),
+    [messageHistory],
+  );
+
   return (
-    <CopilotContext.Provider value={contextValue}>
-      {mcpServers?.map((config) => (
-        <MCPConnection key={config.name} config={config} />
-      ))}
-      {children}
-    </CopilotContext.Provider>
+    <MessageHistoryContext.Provider value={messageHistoryContextValue}>
+      <CopilotContext.Provider value={contextValue}>
+        {mcpServers?.map((config) => (
+          <MCPConnection key={config.name} config={config} />
+        ))}
+        {messageHistory?.strategy && messageHistory.strategy !== "none" && (
+          <MessageHistoryBridge chatRef={chatRef} />
+        )}
+        {children}
+      </CopilotContext.Provider>
+    </MessageHistoryContext.Provider>
   );
 }
diff --git a/packages/copilot-sdk/src/server/compact-session.ts b/packages/copilot-sdk/src/server/compact-session.ts
new file mode 100644
index 0000000..d0b8d96
--- /dev/null
+++ b/packages/copilot-sdk/src/server/compact-session.ts
@@ -0,0 +1,134 @@
+/**
+ * compactSession — server-side summarization helper
+ *
+ * Call this in your /api/compact route handler.
+ * Uses a structured prompt that preserves all semantically important content.
+ *
+ * @example
+ * ```ts
+ * // app/api/compact/route.ts
+ * import { compactSession } from '@yourgpt/copilot-sdk/server';
+ *
+ * export async function POST(req: Request) {
+ *   const { messages, existingSummary, workingMemory } = await req.json();
+ *   const summary = await compactSession({ messages, existingSummary, workingMemory });
+ *   return Response.json({ summary });
+ * }
+ * ```
+ */
+
+export interface CompactSessionOptions {
+  messages: Array<{ role: string; content?: string | null }>;
+  existingSummary?: string | null;
+  workingMemory?: string[];
+  /**
+   * Model to use for summarization.
+   * @default 'claude-haiku-4-5' (cheaper model fine for summaries)
+   */
+  model?: string;
+  /** Max tokens for the summary output. @default 1024 */
+  maxSummaryTokens?: number;
+  /** Custom fetch implementation (for non-browser environments). */
+  fetchImpl?: typeof fetch;
+  /** Anthropic API key. Falls back to process.env.ANTHROPIC_API_KEY. */
+  apiKey?: string;
+  /** Base URL for Anthropic API. @default 'https://api.anthropic.com' */
+  apiBaseUrl?: string;
+}
+
+export interface CompactSessionResult {
+  summary: string;
+}
+
+const COMPACTION_PROMPT = `You are summarizing a conversation to preserve its key context while reducing token usage. Create a structured summary that includes:
+
+1. **User's primary goals and requests** — what the user is trying to accomplish
+2. **Technical decisions made** — libraries chosen, schemas designed, approaches selected
+3. **Tool call outcomes** — what tools were called, key arguments, result status and brief outcome
+4. **Errors encountered** — what went wrong and how it was resolved
+5. **User messages** — verbatim if short (<50 words), paraphrased if long
+6. **Pending tasks** — unresolved questions or next steps mentioned
+7. **Current work state** — what was in progress when this summary was created
+
+Rules:
+- Preserve ALL specific values: file names, variable names, URLs, error messages, IDs
+- Be detailed on recent work, more concise on earlier work
+- Output structured prose (not bullet JSON)
+- Do NOT include meta-commentary about the summarization itself`;
+
+export async function compactSession(
+  options: CompactSessionOptions,
+): Promise<CompactSessionResult> {
+  const {
+    messages,
+    existingSummary,
+    workingMemory = [],
+    model = "claude-haiku-4-5-20251001",
+    maxSummaryTokens = 1024,
+    fetchImpl = fetch,
+    apiKey = typeof process !== "undefined"
+      ? process.env.ANTHROPIC_API_KEY
+      : undefined,
+    apiBaseUrl = "https://api.anthropic.com",
+  } = options;
+
+  if (!apiKey) {
+    throw new Error(
+      "compactSession: No API key provided. Set ANTHROPIC_API_KEY or pass options.apiKey.",
+    );
+  }
+
+  // Build the content to summarize
+  const parts: string[] = [];
+
+  if (workingMemory.length > 0) {
+    parts.push(
+      `[Working memory — always preserve these facts]\n${workingMemory.join("\n")}`,
+    );
+  }
+
+  if (existingSummary) {
+    parts.push(`[Previous summary — extend/update this]\n${existingSummary}`);
+  }
+
+  const conversationText = messages
+    .map((m) => `${m.role.toUpperCase()}: ${m.content ?? "(no content)"}`)
+    .join("\n\n");
+
+  parts.push(`[Conversation to summarize]\n${conversationText}`);
+
+  const userContent = parts.join("\n\n---\n\n");
+
+  const response = await fetchImpl(`${apiBaseUrl}/v1/messages`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxSummaryTokens,
+      system: COMPACTION_PROMPT,
+      messages: [{ role: "user", content: userContent }],
+    }),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(
+      `compactSession: Anthropic API error ${response.status}: ${err}`,
+    );
+  }
+
+  const data = (await response.json()) as {
+    content: Array<{ type: string; text: string }>;
+  };
+
+  const summary = data.content
+    .filter((b) => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+
+  return { summary };
+}
diff --git a/packages/copilot-sdk/src/server/index.ts b/packages/copilot-sdk/src/server/index.ts
new file mode 100644
index 0000000..9858c6c
--- /dev/null
+++ b/packages/copilot-sdk/src/server/index.ts
@@ -0,0 +1,12 @@
+/**
+ * @yourgpt/copilot-sdk/server
+ *
+ * Server-only exports. Do NOT import in browser/React code.
+ */
+
+// Context Management — server-side compaction
+export { compactSession } from "./compact-session";
+export type {
+  CompactSessionOptions,
+  CompactSessionResult,
+} from "./compact-session";
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index e2d31c2..c4435fc 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -105,8 +105,41 @@ export function DefaultMessage({
   citations = { enabled: true },
 }: DefaultMessageProps) {
   const isUser = message.role === "user";
+  const isCompactionMarker =
+    message.role === "system" &&
+    (message.metadata as Record<string, unknown>)?.type === "compaction-marker";
   const isStreaming = isLastMessage && isLoading;
 
+  // Render compaction marker divider
+  if (isCompactionMarker) {
+    const tokensSaved = (message.metadata as Record<string, unknown>)
+      ?.tokensSaved as number | undefined;
+    return (
+      <div className="flex items-center gap-3 py-2 px-1 my-1">
+        <div className="flex-1 h-px bg-border" />
+        <span className="text-[11px] text-muted-foreground whitespace-nowrap flex items-center gap-1.5">
+          <svg
+            className="size-3 opacity-60"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={2}
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M19 9l-7 7-7-7"
+            />
+          </svg>
+          {tokensSaved
+            ? `Earlier conversation summarized · ~${tokensSaved.toLocaleString()} tokens saved`
+            : "Earlier conversation summarized"}
+        </span>
+        <div className="flex-1 h-px bg-border" />
+      </div>
+    );
+  }
+
   // Parse follow-up questions from assistant messages
   const { cleanContent: contentWithoutFollowUps, followUps } =
     React.useMemo(() => {
@@ -357,11 +390,13 @@ export function DefaultMessage({
           />
         )}
 
-        {/* Show loader when processing after tool execution (only for last message) */}
-        {isLastMessage && isProcessing ? (
-          <div className="rounded-lg bg-muted px-4 py-2 flex items-center gap-2">
+        {/* Show loader when processing after tool execution (only for last message with no tools yet) */}
+        {isLastMessage &&
+        isProcessing &&
+        !completedTools?.length &&
+        !pendingApprovalTools?.length ? (
+          <div className="rounded-lg bg-muted px-4 py-2">
             <Loader variant="dots" size="sm" />
-            <span className="text-sm text-muted-foreground">Continuing...</span>
           </div>
         ) : /* Show streaming loader when loading with no content and no tools */
         isLastMessage &&
@@ -504,6 +539,16 @@ export function DefaultMessage({
                 );
               })}
 
+            {/* Processing indicator below completed tools (AI is continuing after tool execution) */}
+            {isLastMessage &&
+              isProcessing &&
+              completedTools &&
+              completedTools.length > 0 && (
+                <div className="mt-2 rounded-lg bg-muted px-4 py-2">
+                  <Loader variant="dots" size="sm" />
+                </div>
+              )}
+
             {/* Tool Approval Confirmations - Priority: toolRenderers > tool.render > default */}
             {pendingApprovalTools && pendingApprovalTools.length > 0 && (
               <div className="mt-2 space-y-2">
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index cb3e0a3..647e538 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -350,8 +350,15 @@ function CopilotChatBase(
     });
 
   // Filter out tool messages and merge results into parent assistant messages
+  // Keep compaction-markers (system messages with type='compaction-marker') visible
   const visibleMessages = messages
-    .filter((m: UIMessage) => m.role !== "tool") // Hide tool messages - results merged into assistant
+    .filter(
+      (m: UIMessage) =>
+        m.role !== "tool" &&
+        (m.role !== "system" ||
+          (m.metadata as Record<string, unknown>)?.type ===
+            "compaction-marker"),
+    ) // Hide tool/system messages except compaction markers
     .map((m: UIMessage) => {
       // For assistant messages with tool_calls, merge results
       let messageToolExecutions: ToolExecutionData[] | undefined;
@@ -491,37 +498,49 @@ function CopilotChatBase(
       ? chatProps.suggestions
       : [];
 
-  // isProcessing: Show "Continuing..." loader ONLY when we're in an active tool flow
-  // Condition: Last message must be assistant with tool_calls (not user starting new request)
+  // isProcessing: Show "Continuing..." loader when tools finished and AI is about to respond
   const lastMessage = messages[messages.length - 1];
+
+  // Find the last assistant message with tool calls (may not be the very last message
+  // since tool result messages follow it)
+  const lastAssistantWithTools = [...messages]
+    .reverse()
+    .find(
+      (m) => m.role === "assistant" && (m as UIMessage).toolCalls?.length,
+    ) as UIMessage | undefined;
+
+  // In tool flow when: last msg is a tool result (tools ran, waiting for AI),
+  // OR last msg is assistant with tool calls (tools still executing)
   const isInToolFlow =
-    lastMessage?.role === "assistant" &&
-    (lastMessage as UIMessage).toolCalls?.length;
+    lastMessage?.role === "tool" ||
+    (lastMessage?.role === "assistant" &&
+      (lastMessage as UIMessage).toolCalls?.length);
 
   let isProcessingToolResults = false;
 
   if (isLoading && isInToolFlow) {
-    const currentToolCallIds = new Set(
-      (lastMessage as UIMessage).toolCalls?.map(
-        (tc: { id: string }) => tc.id,
-      ) || [],
-    );
-    const currentExecutions = toolExecutions.filter((exec) =>
-      currentToolCallIds.has(exec.id),
-    );
-
-    const hasCompletedTools = currentExecutions.some(
-      (exec) =>
-        exec.status === "completed" ||
-        exec.status === "error" ||
-        exec.status === "failed",
-    );
-    const hasExecutingTools = currentExecutions.some(
-      (exec) => exec.status === "executing" || exec.status === "pending",
-    );
-
-    // Show "Continuing..." only when tools completed and waiting for AI to continue
-    isProcessingToolResults = hasCompletedTools && !hasExecutingTools;
+    // Last message is a tool result → all tools for this turn are done, AI is continuing
+    if (lastMessage?.role === "tool") {
+      isProcessingToolResults = true;
+    } else if (lastAssistantWithTools) {
+      const currentToolCallIds = new Set(
+        lastAssistantWithTools.toolCalls?.map((tc: { id: string }) => tc.id) ||
+          [],
+      );
+      const currentExecutions = toolExecutions.filter((exec) =>
+        currentToolCallIds.has(exec.id),
+      );
+      const hasCompletedTools = currentExecutions.some(
+        (exec) =>
+          exec.status === "completed" ||
+          exec.status === "error" ||
+          exec.status === "failed",
+      );
+      const hasExecutingTools = currentExecutions.some(
+        (exec) => exec.status === "executing" || exec.status === "pending",
+      );
+      isProcessingToolResults = hasCompletedTools && !hasExecutingTools;
+    }
   }
 
   // Extract chat classNames (without thread picker classes)

From b85256dc03c8e7c516d21110552591c2808143b6 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Thu, 12 Mar 2026 23:43:33 +0530
Subject: [PATCH 11/72] refactor(sdk): enhance logging and streamline tool
 execution

- Introduced a new logging utility to improve debug output with scoped logging capabilities.
- Updated the `ChatWithTools` and `AbstractChat` classes to utilize the new logger for better debugging.
- Refactored the `AbstractAgentLoop` to execute tool calls in parallel, improving performance and responsiveness.
- Enhanced message handling in `CopilotProvider` to support new logging features.
- Cleaned up code by removing unnecessary line breaks and comments for better readability.

These changes aim to improve the overall debugging experience and performance of the SDK.
---
 .../copilot-sdk/src/chat/AbstractAgentLoop.ts |  31 +-
 .../copilot-sdk/src/chat/ChatWithTools.ts     |  10 +-
 .../src/chat/classes/AbstractChat.ts          | 297 ++++++++++++++++--
 packages/copilot-sdk/src/chat/types/chat.ts   |   2 +-
 packages/copilot-sdk/src/core/index.ts        |   6 +
 packages/copilot-sdk/src/core/utils/logger.ts | 115 +++++++
 .../src/react/provider/CopilotProvider.tsx    |  73 +++--
 7 files changed, 467 insertions(+), 67 deletions(-)
 create mode 100644 packages/copilot-sdk/src/core/utils/logger.ts

diff --git a/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts b/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
index 470cdaf..81622d8 100644
--- a/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
+++ b/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
@@ -277,23 +277,22 @@ export class AbstractAgentLoop implements AgentLoopActions {
     this._isProcessing = true;
 
     this.setIteration(this._iteration + 1);
-    const results: ToolResponse[] = [];
 
-    for (const toolCall of toolCalls) {
-      // Check if cancelled before each tool
-      if (this._isCancelled || this.abortController.signal.aborted) {
-        // Mark remaining tools as cancelled
-        results.push({
-          toolCallId: toolCall.id,
-          success: false,
-          error: "Tool execution cancelled",
-        });
-        continue;
-      }
-
-      const result = await this.executeSingleTool(toolCall);
-      results.push(result);
-    }
+    // Run all tools in parallel so approval-required tools don't block
+    // non-approval tools. All results are still collected together before
+    // returning (Anthropic API requires results for every tool_use block).
+    const results = await Promise.all(
+      toolCalls.map((toolCall) => {
+        if (this._isCancelled || this.abortController!.signal.aborted) {
+          return Promise.resolve<ToolResponse>({
+            toolCallId: toolCall.id,
+            success: false,
+            error: "Tool execution cancelled",
+          });
+        }
+        return this.executeSingleTool(toolCall);
+      }),
+    );
 
     this._isProcessing = false;
     return results;
diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index d2de06f..772bdcd 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -18,6 +18,7 @@ import type {
   PermissionLevel,
 } from "../core";
 import type { Resolvable } from "../core/utils/resolvable";
+import { createLogger } from "../core/utils/logger";
 import { AbstractChat } from "./classes/AbstractChat";
 import { AbstractAgentLoop } from "./AbstractAgentLoop";
 import type { ChatConfig, ChatCallbacks } from "./types";
@@ -47,7 +48,7 @@ export interface ChatWithToolsConfig {
   body?: Resolvable<Record<string, unknown>>;
   /** Thread ID for conversation persistence */
   threadId?: string;
-  /** Debug mode */
+  /** Enable debug logging */
   debug?: boolean;
   /** Initial messages */
   initialMessages?: UIMessage[];
@@ -601,9 +602,10 @@ export class ChatWithTools {
   // ============================================
 
   private debug(message: string, ...args: unknown[]): void {
-    if (this.config.debug) {
-      console.log(`[ChatWithTools] ${message}`, ...args);
-    }
+    createLogger("tools", () => this.config.debug ?? false)(
+      message,
+      args.length === 1 ? args[0] : args.length > 1 ? args : undefined,
+    );
   }
 }
 
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 2b0d6b9..6bcd59f 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -43,6 +43,7 @@ import {
 } from "../functions/stream";
 import { SimpleChatState } from "../interfaces/ChatState";
 import { ChatContextOptimizer } from "../optimizations";
+import { createLogger } from "../../core/utils/logger";
 
 /**
  * Event types emitted by AbstractChat
@@ -462,13 +463,29 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     // Build request
     const request = this.buildRequest();
 
+    // For streaming: pre-push an empty assistant message BEFORE the HTTP
+    // round-trip so the UI shows a loading bubble immediately (e.g. between
+    // tool execution and the continuation stream starting).
+    let preCreatedMessageId: string | undefined;
+    if (this.config.streaming !== false) {
+      const preMsg = createEmptyAssistantMessage() as T;
+      this.state.pushMessage(preMsg);
+      this.callbacks.onMessagesChange?.(this.state.messages);
+      preCreatedMessageId = preMsg.id;
+    }
+
     // Send request
     const response = await this.transport.send(request);
 
     // Check if streaming or JSON
     if (this.isAsyncIterable(response)) {
-      await this.handleStreamResponse(response);
+      await this.handleStreamResponse(response, preCreatedMessageId);
     } else {
+      // Non-streaming: remove the pre-pushed placeholder (not needed)
+      if (preCreatedMessageId) {
+        const id = preCreatedMessageId;
+        this.state.setMessages(this.state.messages.filter((m) => m.id !== id));
+      }
       this.handleJsonResponse(response);
     }
   }
@@ -531,7 +548,6 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
    */
   setContext(context: string): void {
     this.dynamicContext = context;
-    this.debug("Context updated", { length: context.length });
   }
 
   /**
@@ -540,7 +556,6 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
    */
   setSystemPrompt(prompt: string): void {
     this.config.systemPrompt = prompt;
-    this.debug("System prompt updated", { length: prompt.length });
   }
 
   /**
@@ -552,7 +567,6 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     if (this.transport.setHeaders && headers !== undefined) {
       this.transport.setHeaders(headers);
     }
-    this.debug("Headers config updated");
   }
 
   /**
@@ -564,7 +578,6 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     if (this.transport.setUrl) {
       this.transport.setUrl(url);
     }
-    this.debug("URL config updated");
   }
 
   /**
@@ -576,7 +589,6 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     if (this.transport.setBody && body !== undefined) {
       this.transport.setBody(body);
     }
-    this.debug("Body config updated");
   }
 
   /**
@@ -624,27 +636,51 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
    */
   protected async handleStreamResponse(
     stream: AsyncIterable<StreamChunk>,
+    preCreatedMessageId?: string,
   ): Promise<void> {
     this.state.status = "streaming";
     this.callbacks.onStatusChange?.("streaming");
 
-    // Create empty assistant message for streaming
-    const assistantMessage = createEmptyAssistantMessage() as T;
-    this.state.pushMessage(assistantMessage);
+    // Reuse the pre-pushed empty assistant message (created in processRequest
+    // before the HTTP round-trip) so there's no blank gap waiting for stream start.
+    // Fall back to pushing a new one if not provided.
+    let assistantMessage: T;
+    if (preCreatedMessageId) {
+      const existing = this.state.messages.find(
+        (m) => m.id === preCreatedMessageId,
+      );
+      if (existing) {
+        assistantMessage = existing;
+      } else {
+        assistantMessage = createEmptyAssistantMessage() as T;
+        this.state.pushMessage(assistantMessage);
+      }
+    } else {
+      assistantMessage = createEmptyAssistantMessage() as T;
+      this.state.pushMessage(assistantMessage);
+    }
 
     // Initialize stream state
     this.streamState = createStreamState(assistantMessage.id);
     this.callbacks.onMessageStart?.(assistantMessage.id);
 
-    this.debug("handleStreamResponse", "Starting to process stream");
+    this.debugGroup("handleStreamResponse");
+    this.debug("Starting to process stream");
 
     let chunkCount = 0;
     let toolCallsEmitted = false; // Guard to prevent emitting toolCalls twice
+    // Holds client tool calls received via a tool_calls chunk AFTER a
+    // mid-stream message:end nulled streamState.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let pendingClientToolCalls: any[] | undefined;
 
     // Process stream chunks
     for await (const chunk of stream) {
       chunkCount++;
-      this.debug("chunk", { count: chunkCount, type: chunk.type });
+      // Skip high-frequency delta chunks from the chunk log to reduce noise
+      if (chunk.type !== "message:delta") {
+        this.debug("chunk", { count: chunkCount, type: chunk.type });
+      }
 
       // Handle error chunks immediately
       if (chunk.type === "error") {
@@ -656,7 +692,12 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       // Handle message:end mid-stream (server-side agent loop turn completed)
       // This creates separate messages for each turn instead of combining them
       if (chunk.type === "message:end" && this.streamState?.content) {
-        this.debug("message:end mid-stream - finalizing current turn");
+        this.debug("message:end mid-stream", {
+          messageId: this.streamState.messageId,
+          contentLength: this.streamState.content.length,
+          toolCallsInState: this.streamState.toolCalls?.length ?? 0,
+          chunkCount,
+        });
 
         // Finalize current message with its content and tool calls
         const turnMessage = streamStateToMessage(this.streamState) as T;
@@ -702,8 +743,128 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       }
 
       // Update stream state (pure function)
-      // Skip if streamState is null (shouldn't happen but be safe)
+      // Skip most chunks if streamState is null.
+      // EXCEPTION: after a mid-stream message:end the server can still send
+      // tool_calls + done for client-side tool dispatch. Handle those directly.
       if (!this.streamState) {
+        if (chunk.type === "tool_calls") {
+          // Store for emission when done arrives. Do NOT update message state
+          // here — done.messages carries the assistant message with tool_calls
+          // in proper OpenAI format, which we use in the done handler below.
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          pendingClientToolCalls = (chunk as { toolCalls: any[] }).toolCalls;
+          this.debug("tool_calls (post-message:end, stored as pending)", {
+            count: pendingClientToolCalls?.length,
+            ids: pendingClientToolCalls?.map((tc: { id?: string }) => tc.id),
+          });
+          continue;
+        }
+
+        if (chunk.type === "done") {
+          this.debug("done (post-message:end)", {
+            hasPendingToolCalls: !!pendingClientToolCalls?.length,
+            pendingCount: pendingClientToolCalls?.length ?? 0,
+            doneMessagesCount: chunk.messages?.length ?? 0,
+            requiresAction: (chunk as { requiresAction?: boolean })
+              .requiresAction,
+            toolCallsEmitted,
+          });
+          // Process done.messages to:
+          // 1. Insert any server-side tool results missing from state
+          // 2. Merge OpenAI-format tool_calls into the finalized assistant message
+          if (chunk.messages?.length) {
+            const pendingIds = new Set(
+              ((pendingClientToolCalls ?? []) as Array<{ id?: string }>)
+                .filter((tc) => tc?.id)
+                .map((tc) => tc.id as string),
+            );
+            const messagesToInsert: T[] = [];
+            let clientAssistantToolCalls: unknown[] | undefined;
+
+            for (const msg of chunk.messages) {
+              // This is the client-tool assistant message already in state
+              // (finalized by message:end but without toolCalls).
+              // Capture its OpenAI-format tool_calls to merge into state.
+              if (
+                msg.role === "assistant" &&
+                msg.tool_calls?.length &&
+                pendingIds.size > 0 &&
+                (msg.tool_calls as Array<{ id?: string }>).every((tc) =>
+                  pendingIds.has(tc?.id ?? ""),
+                )
+              ) {
+                clientAssistantToolCalls = msg.tool_calls as unknown[];
+                continue; // Already in state — don't insert a duplicate
+              }
+              // Skip plain assistant text — already streamed
+              if (msg.role === "assistant" && !msg.tool_calls?.length) continue;
+              // Everything else (server tool results) needs inserting
+              messagesToInsert.push({
+                id: generateMessageId(),
+                role: msg.role as T["role"],
+                content: msg.content ?? "",
+                toolCalls: msg.tool_calls as T["toolCalls"],
+                toolCallId: msg.tool_call_id,
+                createdAt: new Date(),
+              } as T);
+            }
+
+            // Merge OpenAI-format tool_calls into the existing last assistant message
+            if (clientAssistantToolCalls) {
+              const currentMessages = this.state.messages;
+              for (let i = currentMessages.length - 1; i >= 0; i--) {
+                if (currentMessages[i].role === "assistant") {
+                  this.state.updateMessageById(
+                    currentMessages[i].id,
+                    (m) =>
+                      ({
+                        ...m,
+                        toolCalls: clientAssistantToolCalls,
+                      }) as T,
+                  );
+                  break;
+                }
+              }
+            }
+
+            if (messagesToInsert.length > 0) {
+              // Insert server tool results before the last assistant message
+              const currentMessages = this.state.messages;
+              let insertIdx = currentMessages.length;
+              for (let i = currentMessages.length - 1; i >= 0; i--) {
+                if (currentMessages[i].role === "assistant") {
+                  insertIdx = i;
+                  break;
+                }
+              }
+              this.state.setMessages([
+                ...currentMessages.slice(0, insertIdx),
+                ...messagesToInsert,
+                ...currentMessages.slice(insertIdx),
+              ]);
+            }
+          }
+
+          // Emit client tool calls so ChatWithTools executes them
+          if (!toolCallsEmitted && pendingClientToolCalls?.length) {
+            toolCallsEmitted = true;
+            this.debug("emit toolCalls (post-message:end path)", {
+              count: pendingClientToolCalls.length,
+              names: pendingClientToolCalls.map(
+                (tc: { function?: { name: string }; name?: string }) =>
+                  tc.function?.name ?? tc.name,
+              ),
+            });
+            this.emit("toolCalls", { toolCalls: pendingClientToolCalls });
+          } else {
+            this.debug("skip emit toolCalls (post-message:end path)", {
+              toolCallsEmitted,
+              hasPending: !!pendingClientToolCalls?.length,
+            });
+          }
+          continue;
+        }
+
         this.debug("warning", "streamState is null, skipping chunk");
         continue;
       }
@@ -757,13 +918,26 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
 
       // Check for completion
       if (isStreamDone(chunk)) {
-        this.debug("streamDone", { chunk });
+        this.debug("streamDone", {
+          chunkType: chunk.type,
+          requiresAction: (chunk as { requiresAction?: boolean })
+            .requiresAction,
+          doneMessagesCount:
+            (chunk as { messages?: unknown[] }).messages?.length ?? 0,
+          streamToolCallsCount: this.streamState?.toolCalls?.length ?? 0,
+          toolCallsEmitted,
+          chunkCount,
+        });
 
         // CRITICAL: Process messages from done event (server-side tool results)
         // Without this, tool_call_id is lost and causes Anthropic API errors
         if (chunk.type === "done" && chunk.messages?.length) {
           this.debug("processDoneMessages", {
             count: chunk.messages.length,
+            roles: chunk.messages.map(
+              (m) =>
+                `${m.role}${m.tool_calls?.length ? `[${(m.tool_calls as unknown[]).length}tc]` : ""}`,
+            ),
           });
 
           const currentStreamToolCallIds = new Set(
@@ -851,14 +1025,57 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
           // merged into local state. Emitting earlier on the first tool_calls
           // chunk can race with recursive server-tool turns and produce an
           // invalid continuation order for OpenAI-compatible providers.
-          if (
-            chunk.requiresAction &&
-            !toolCallsEmitted &&
-            updatedMessage.toolCalls?.length
-          ) {
-            toolCallsEmitted = true;
-            this.debug("toolCalls", { toolCalls: updatedMessage.toolCalls });
-            this.emit("toolCalls", { toolCalls: updatedMessage.toolCalls });
+          this.debug("requiresAction check", {
+            requiresAction: chunk.requiresAction,
+            toolCallsEmitted,
+            updatedMessageToolCallsCount: updatedMessage.toolCalls?.length ?? 0,
+            messagesToInsertCount: messagesToInsert.length,
+          });
+
+          if (chunk.requiresAction && !toolCallsEmitted) {
+            // When the server runs a multi-turn agent loop before handing off
+            // to the client, the client tool calls arrive via done.messages
+            // (messagesToInsert), NOT in the current streaming message's
+            // toolCalls (which is always empty because action:start/args/end
+            // chunks only fire callbacks and never update streamState.toolCalls).
+            // Find the last assistant message in the inserted batch that carries
+            // tool calls — that is the pending client tool dispatch.
+            let clientToolCalls = updatedMessage.toolCalls;
+            if (!clientToolCalls?.length && messagesToInsert.length > 0) {
+              for (let i = messagesToInsert.length - 1; i >= 0; i--) {
+                const m = messagesToInsert[i];
+                if (m.role === "assistant" && m.toolCalls?.length) {
+                  clientToolCalls = m.toolCalls;
+                  this.debug("clientToolCalls from messagesToInsert", {
+                    index: i,
+                    count: clientToolCalls?.length,
+                  });
+                  break;
+                }
+              }
+            }
+
+            if (clientToolCalls?.length) {
+              toolCallsEmitted = true;
+              this.debug("emit toolCalls (normal done path)", {
+                count: clientToolCalls.length,
+                names: (
+                  clientToolCalls as Array<{
+                    function?: { name: string };
+                    name?: string;
+                  }>
+                ).map((tc) => tc.function?.name ?? tc.name),
+              });
+              this.emit("toolCalls", { toolCalls: clientToolCalls });
+            } else {
+              this.debug("requiresAction=true but no clientToolCalls found", {
+                updatedMessageToolCalls: updatedMessage.toolCalls,
+                messagesToInsert: messagesToInsert.map((m) => ({
+                  role: m.role,
+                  hasToolCalls: !!m.toolCalls?.length,
+                })),
+              });
+            }
           }
         }
 
@@ -914,9 +1131,17 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
 
     this.callbacks.onMessagesChange?.(this.state.messages);
 
+    // Close the stream group opened at the start of handleStreamResponse
+    this.debugGroupEnd();
+
     // Only set status to "ready" if NO tool calls were emitted
     // If tool calls were emitted, the async handler will manage status
     // (it will set "submitted" then "streaming" for the continuation)
+    this.debug("stream end", {
+      toolCallsEmitted,
+      totalChunks: chunkCount,
+      messagesInState: this.state.messages.length,
+    });
     if (!toolCallsEmitted) {
       this.state.status = "ready";
       this.callbacks.onStatusChange?.("ready");
@@ -1010,15 +1235,33 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     this.emit("error", { error });
   }
 
-  /**
-   * Debug logging
-   */
+  // ─── Debug helpers ────────────────────────────────────────────────────────
+
+  private _log?: import("../../core/utils/logger").ScopedLogger;
+
+  private get log(): import("../../core/utils/logger").ScopedLogger {
+    if (!this._log) {
+      this._log = createLogger("streaming", () => this.config.debug ?? false);
+    }
+    return this._log;
+  }
+
   protected debug(action: string, data?: unknown): void {
-    if (this.config.debug) {
-      console.log(`[AbstractChat] ${action}`, data);
+    this.log(action, data);
+  }
+
+  protected debugGroup(label: string, collapsed = true): void {
+    if (collapsed) {
+      this.log.groupCollapsed(label);
+    } else {
+      this.log.group(label);
     }
   }
 
+  protected debugGroupEnd(): void {
+    this.log.groupEnd();
+  }
+
   /**
    * Type guard for async iterable
    */
diff --git a/packages/copilot-sdk/src/chat/types/chat.ts b/packages/copilot-sdk/src/chat/types/chat.ts
index 1c536ae..8070461 100644
--- a/packages/copilot-sdk/src/chat/types/chat.ts
+++ b/packages/copilot-sdk/src/chat/types/chat.ts
@@ -54,7 +54,7 @@ export 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[];
diff --git a/packages/copilot-sdk/src/core/index.ts b/packages/copilot-sdk/src/core/index.ts
index dcc7d36..dd53ae9 100644
--- a/packages/copilot-sdk/src/core/index.ts
+++ b/packages/copilot-sdk/src/core/index.ts
@@ -97,6 +97,12 @@ export type {
   WebSearchProviderInterface,
 } from "./tools";
 
+// ============================================
+// Logger
+// ============================================
+export { createLogger, logOnce } from "./utils/logger";
+export type { ScopedLogger, DebugConfig } from "./utils/logger";
+
 // ============================================
 // Core Types
 // ============================================
diff --git a/packages/copilot-sdk/src/core/utils/logger.ts b/packages/copilot-sdk/src/core/utils/logger.ts
new file mode 100644
index 0000000..b44f7af
--- /dev/null
+++ b/packages/copilot-sdk/src/core/utils/logger.ts
@@ -0,0 +1,115 @@
+/**
+ * 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
+ */
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/** 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. */
+export type DebugConfig = boolean;
+
+declare global {
+  interface Window {
+    __COPILOT_DEBUG?: boolean;
+  }
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+function isEnabled(getEnabled: () => boolean): boolean {
+  if (typeof window !== "undefined" && window.__COPILOT_DEBUG !== undefined) {
+    return !!window.__COPILOT_DEBUG;
+  }
+  return getEnabled();
+}
+
+// ─── Factory ───────────────────────────────────────────────────────────────
+
+export 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.
+ */
+export function logOnce(
+  scope: LogScope,
+  enabled: boolean,
+  action: string,
+  data?: unknown,
+): void {
+  if (!isEnabled(() => enabled)) return;
+  const prefix = `[${scope}]`;
+  if (data !== undefined) {
+    console.log(prefix, action, data);
+  } else {
+    console.log(prefix, action);
+  }
+}
+
+export function createLogger(
+  scope: LogScope,
+  getEnabled: () => boolean,
+): ScopedLogger {
+  const prefix = `[${scope}]`;
+
+  function log(action: string, data?: unknown): void {
+    if (!isEnabled(getEnabled)) return;
+    if (data !== undefined) {
+      console.log(prefix, action, data);
+    } else {
+      console.log(prefix, action);
+    }
+  }
+
+  log.group = function (label: string): void {
+    if (!isEnabled(getEnabled)) return;
+    console.group(`${prefix} ${label}`);
+  };
+
+  log.groupCollapsed = function (label: string): void {
+    if (!isEnabled(getEnabled)) return;
+    console.groupCollapsed(`${prefix} ${label}`);
+  };
+
+  log.groupEnd = function (): void {
+    if (!isEnabled(getEnabled)) return;
+    console.groupEnd();
+  };
+
+  return log;
+}
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 6a104a8..fbf77e9 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -30,6 +30,7 @@ import type {
 
 import type { MCPServerConfig } from "../../mcp/types";
 import type { Resolvable } from "../../core/utils/resolvable";
+import { createLogger } from "../../core/utils/logger";
 
 import type { UIMessage, ToolExecution } from "../../chat";
 
@@ -50,8 +51,6 @@ import {
   useMessageHistoryContext,
 } from "../message-history/context";
 import { useMessageHistory } from "../message-history/useMessageHistory";
-import { toDisplayMessage } from "../message-history/message-utils";
-import { buildSummaryBufferContext } from "../message-history/strategies/summary-buffer";
 import type { MessageHistoryConfig } from "../message-history/types";
 
 // ============================================
@@ -185,22 +184,58 @@ function MessageHistoryBridge({
       if (historyMessages.length === 0) return allMessages;
 
       const cfg = configRef.current;
-      const maxTokens = cfg.maxContextTokens ?? 128000;
-      const reserve = cfg.reserveForResponse ?? 4096;
-
-      // Apply summary-buffer only to the completed history, never the current turn
-      const compactedHistory = buildSummaryBufferContext(
-        historyMessages.map(toDisplayMessage),
-        compactionStateRef.current,
-        {
-          recentBuffer: cfg.recentBuffer ?? 10,
-          tokenBudget: maxTokens - reserve,
-          compactionThreshold: cfg.compactionThreshold ?? 0.75,
-          compactionUrl: cfg.compactionUrl,
-        },
+
+      // Apply summary-buffer windowing to history, keeping UIMessage format.
+      //
+      // WHY NOT buildSummaryBufferContext here:
+      // buildSummaryBufferContext returns LLMMessage[] (snake_case: tool_calls,
+      // tool_call_id). The optimizer's transformMessages() only reads camelCase
+      // (toolCalls, toolCallId), so mixing LLMMessage into this array causes it
+      // to silently strip tool call data → "Missing call_id" API errors.
+      // The optimizer must own the UIMessage → RequestMessage conversion.
+      const cs = compactionStateRef.current;
+      const recentBuffer = cfg.recentBuffer ?? 10;
+
+      // Identify compaction marker messages (UI-only, already represented by rollingSummary)
+      const isCompactionMsg = (m: UIMessage) =>
+        m.metadata?.["type"] === "compaction-marker";
+
+      const windowedHistory: UIMessage[] = [];
+
+      // 1. Working memory (always first)
+      if (cs.workingMemory.length > 0) {
+        windowedHistory.push({
+          id: "working-memory",
+          role: "system",
+          content: `[Working memory — always active]\n${cs.workingMemory.join("\n")}`,
+          createdAt: new Date(),
+        } as UIMessage);
+      }
+
+      // 2. Rolling summary replaces older history
+      if (cs.rollingSummary) {
+        windowedHistory.push({
+          id: "rolling-summary",
+          role: "system",
+          content: `[Previous conversation summary]\n${cs.rollingSummary}`,
+          createdAt: new Date(),
+        } as UIMessage);
+      }
+
+      // 3. Non-compaction system messages (e.g. injected context)
+      const systemMsgs = historyMessages.filter(
+        (m) => m.role === "system" && !isCompactionMsg(m),
+      );
+      windowedHistory.push(...systemMsgs);
+
+      // 4. Recent conversation messages (windowed to recentBuffer)
+      const conversationMsgs = historyMessages.filter(
+        (m) => m.role !== "system",
       );
+      const recentStart = Math.max(0, conversationMsgs.length - recentBuffer);
+      windowedHistory.push(...conversationMsgs.slice(recentStart));
 
-      return [...compactedHistory, ...currentTurn] as unknown as UIMessage[];
+      return [...windowedHistory, ...currentTurn];
     });
     return () => {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -358,10 +393,10 @@ export function CopilotProvider({
   optimization,
   messageHistory,
 }: CopilotProviderProps) {
-  // Debug logger
+  // Debug logger — scoped to "provider" namespace
   const debugLog = useCallback(
-    (...args: unknown[]) => {
-      if (debug) console.log("[Copilot SDK]", ...args);
+    (action: string, data?: unknown) => {
+      createLogger("provider", () => debug ?? false)(action, data);
     },
     [debug],
   );

From 80aa1bef23f5ae9067bd5d78093bb31697c17cd0 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 14 Mar 2026 17:11:04 +0530
Subject: [PATCH 12/72] feat(sdk): add support for fallback tool renderer and
 message grouping

- Introduced a `fallbackToolRenderer` prop to the `Chat` and `DefaultMessage` components, allowing for a catch-all rendering option for unmatched tools.
- Implemented `groupConsecutiveMessages` functionality to hide avatars for consecutive messages from the same role, enhancing message display in chat.
- Updated type definitions to include new props and ensure proper usage across components.

These enhancements improve the flexibility of tool rendering and the visual organization of chat messages.
---
 .../src/ui/components/composed/chat/chat.tsx  | 53 ++++++++++++++++++-
 .../composed/chat/default-message.tsx         | 38 +++++++++++--
 .../src/ui/components/composed/chat/types.ts  | 17 ++++++
 3 files changed, 102 insertions(+), 6 deletions(-)

diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 0e26989..11e0219 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -523,6 +523,7 @@ function ChatComponent({
   registeredTools,
   toolRenderers,
   mcpToolRenderer,
+  fallbackToolRenderer,
   onApproveToolExecution,
   onRejectToolExecution,
   // Follow-up Questions
@@ -535,6 +536,8 @@ function ChatComponent({
   renderMessage,
   renderInput,
   renderHeader,
+  // Avatar grouping
+  groupConsecutiveMessages = false,
   // Styling
   className,
   classNames = {},
@@ -910,6 +913,43 @@ function ChatComponent({
                   {/* Messages */}
                   {messages.map((message, index) => {
                     const isLastMessage = index === messages.length - 1;
+
+                    const GROUP_THRESHOLD_MS = 5 * 60 * 1000;
+                    const shouldHideAvatar = (() => {
+                      if (!groupConsecutiveMessages || index === 0)
+                        return false;
+                      let prevIdx = index - 1;
+                      while (prevIdx >= 0) {
+                        const prev = messages[prevIdx];
+                        const isToolMsg = prev.role === "tool";
+                        const isInvisibleSystem =
+                          prev.role === "system" &&
+                          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                          (prev.metadata as Record<string, unknown>)?.type !==
+                            "compaction-marker";
+                        if (!isToolMsg && !isInvisibleSystem) break;
+                        prevIdx--;
+                      }
+                      if (prevIdx < 0) return false;
+                      const prevVisible = messages[prevIdx];
+                      if (prevVisible.role !== message.role) return false;
+                      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                      const curTs = (message as any).timestamp as
+                        | number
+                        | undefined;
+                      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                      const prevTs = (prevVisible as any).timestamp as
+                        | number
+                        | undefined;
+                      if (
+                        curTs &&
+                        prevTs &&
+                        curTs - prevTs > GROUP_THRESHOLD_MS
+                      )
+                        return false;
+                      return true;
+                    })();
+
                     const isEmptyAssistant =
                       message.role === "assistant" && !message.content?.trim();
 
@@ -967,8 +1007,16 @@ function ChatComponent({
                       <DefaultMessage
                         key={message.id}
                         message={messageWithExecutions}
-                        userAvatar={userAvatar}
-                        assistantAvatar={assistantAvatar}
+                        userAvatar={
+                          shouldHideAvatar && message.role === "user"
+                            ? { ...userAvatar, className: "invisible" }
+                            : userAvatar
+                        }
+                        assistantAvatar={
+                          shouldHideAvatar && message.role === "assistant"
+                            ? { ...assistantAvatar, className: "invisible" }
+                            : assistantAvatar
+                        }
                         showUserAvatar={showUserAvatar}
                         userMessageClassName={classNames.userMessage}
                         assistantMessageClassName={classNames.assistantMessage}
@@ -980,6 +1028,7 @@ function ChatComponent({
                         registeredTools={registeredTools}
                         toolRenderers={toolRenderers}
                         mcpToolRenderer={mcpToolRenderer}
+                        fallbackToolRenderer={fallbackToolRenderer}
                         onApproveToolExecution={onApproveToolExecution}
                         onRejectToolExecution={onRejectToolExecution}
                         showFollowUps={showFollowUps}
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index c4435fc..f6b0b67 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -25,11 +25,17 @@ import { SourceGroup, type SourceItem } from "../../ui/source";
 
 type DefaultMessageProps = {
   message: ChatMessage;
-  userAvatar: { src?: string; fallback?: string; component?: React.ReactNode };
+  userAvatar: {
+    src?: string;
+    fallback?: string;
+    component?: React.ReactNode;
+    className?: string;
+  };
   assistantAvatar: {
     src?: string;
     fallback?: string;
     component?: React.ReactNode;
+    className?: string;
   };
   showUserAvatar?: boolean;
   userMessageClassName?: string;
@@ -57,6 +63,8 @@ type DefaultMessageProps = {
   toolRenderers?: ToolRenderers;
   /** Catch-all renderer for MCP tools (tools with source: "mcp") */
   mcpToolRenderer?: React.ComponentType<ToolRendererProps>;
+  /** Catch-all renderer for any tool not matched by toolRenderers */
+  fallbackToolRenderer?: React.ComponentType<ToolRendererProps>;
   /** Called when user approves a tool execution */
   onApproveToolExecution?: (
     executionId: string,
@@ -96,6 +104,7 @@ export function DefaultMessage({
   registeredTools,
   toolRenderers,
   mcpToolRenderer,
+  fallbackToolRenderer,
   onApproveToolExecution,
   onRejectToolExecution,
   showFollowUps = true,
@@ -300,6 +309,7 @@ export function DefaultMessage({
             src={userAvatar.src}
             alt="User"
             fallback={userAvatar.fallback}
+            className={userAvatar.className}
           >
             {userAvatar.component}
           </MessageAvatar>
@@ -326,13 +336,14 @@ export function DefaultMessage({
     (exec) => exec.approvalStatus !== "required" && !isToolHidden(exec),
   );
 
-  // Helper: check if tool has any custom render (toolRenderers, mcpToolRenderer, or tool.render)
+  // Helper: check if tool has any custom render (toolRenderers, mcpToolRenderer, fallbackToolRenderer, or tool.render)
   const hasCustomRender = (toolName: string, execSource?: string): boolean => {
     if (toolRenderers?.[toolName]) return true;
     const toolDef = registeredTools?.find((t) => t.name === toolName);
     // Check if mcpToolRenderer applies (MCP tool with catch-all renderer)
     if (mcpToolRenderer && (execSource === "mcp" || toolDef?.source === "mcp"))
       return true;
+    if (fallbackToolRenderer) return true;
     if (toolDef?.render) return true;
     return false;
   };
@@ -376,7 +387,7 @@ export function DefaultMessage({
             <CopilotSDKLogo className="size-5" />
           ) : undefined
         }
-        className="bg-muted"
+        className={cn("bg-muted", assistantAvatar.className)}
       >
         {assistantAvatar.component}
       </MessageAvatar>
@@ -473,7 +484,26 @@ export function DefaultMessage({
                     );
                   }
 
-                  // PRIORITY 3: tool's own render function
+                  // PRIORITY 3: fallbackToolRenderer (catch-all for any unmatched tool)
+                  if (fallbackToolRenderer) {
+                    const FallbackRenderer = fallbackToolRenderer;
+                    return (
+                      <FallbackRenderer
+                        key={exec.id}
+                        execution={{
+                          id: exec.id,
+                          name: exec.name,
+                          args: exec.args,
+                          status: exec.status,
+                          result: exec.result,
+                          error: exec.error,
+                          source: exec.source,
+                        }}
+                      />
+                    );
+                  }
+
+                  // PRIORITY 4: tool's own render function
                   // toolDef already defined above for MCP check
                   const toolDefForRender =
                     toolDef ??
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
index 428426b..e903df6 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
@@ -403,6 +403,19 @@ export type ChatProps = {
    */
   mcpToolRenderer?: React.ComponentType<ToolRendererProps>;
 
+  /**
+   * Catch-all renderer for ALL tools not matched by `toolRenderers`.
+   * Applied regardless of tool source (native, custom, or MCP).
+   *
+   * Priority: toolRenderers[name] > mcpToolRenderer (mcp only) > fallbackToolRenderer > tool.render > default
+   *
+   * @example
+   * ```tsx
+   * <Chat fallbackToolRenderer={DefaultToolCard} />
+   * ```
+   */
+  fallbackToolRenderer?: React.ComponentType<ToolRendererProps>;
+
   // === Tool Approval (Human-in-the-loop) ===
   /**
    * Called when user approves a tool execution.
@@ -430,6 +443,10 @@ export type ChatProps = {
   /** Custom header renderer (replaces entire header) */
   renderHeader?: () => React.ReactNode;
 
+  /** Group consecutive messages from same role — hides avatar on non-first messages in a run.
+   *  Resets on role change or if messages are > 5 minutes apart. */
+  groupConsecutiveMessages?: boolean;
+
   // === Styling ===
   /** Class name for root container (use for sizing) */
   className?: string;

From 07ff53b59d612a495496731367cc104abb76f7b0 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 14 Mar 2026 20:49:57 +0530
Subject: [PATCH 13/72] feat(sdk): introduce useContextStats hook for context
 window usage tracking

- Added the `useContextStats` hook to provide live statistics on the AI copilot's context window usage, including token counts and percentages.
- Updated `CopilotProvider` to manage context characters and usage, ensuring reactive updates during message interactions.
- Re-exported relevant types and hooks for better accessibility in the SDK.

These enhancements improve the monitoring of context usage, aiding in efficient resource management during interactions.
---
 packages/copilot-sdk/src/react/hooks/index.ts |   7 +
 .../src/react/hooks/useContextStats.ts        | 131 ++++++++++++++++++
 packages/copilot-sdk/src/react/index.ts       |  10 ++
 .../src/react/provider/CopilotProvider.tsx    |  22 +++
 4 files changed, 170 insertions(+)
 create mode 100644 packages/copilot-sdk/src/react/hooks/useContextStats.ts

diff --git a/packages/copilot-sdk/src/react/hooks/index.ts b/packages/copilot-sdk/src/react/hooks/index.ts
index 52581c7..6f11565 100644
--- a/packages/copilot-sdk/src/react/hooks/index.ts
+++ b/packages/copilot-sdk/src/react/hooks/index.ts
@@ -96,3 +96,10 @@ export {
   type UseMCPUIIntentsConfig,
   type UseMCPUIIntentsReturn,
 } from "./useMCPUIIntents";
+
+// Context Stats (context window usage, token estimates, tool count)
+export {
+  useContextStats,
+  type ContextStats,
+  type MessageTokenUsage,
+} from "./useContextStats";
diff --git a/packages/copilot-sdk/src/react/hooks/useContextStats.ts b/packages/copilot-sdk/src/react/hooks/useContextStats.ts
new file mode 100644
index 0000000..91287d9
--- /dev/null
+++ b/packages/copilot-sdk/src/react/hooks/useContextStats.ts
@@ -0,0 +1,131 @@
+"use client";
+
+import { useMemo } from "react";
+import { useCopilot } from "../provider/CopilotProvider";
+import type { UIMessage } from "../../chat";
+import type { ContextUsage } from "../../core";
+
+/**
+ * Per-message token usage returned by the LLM provider.
+ */
+export interface MessageTokenUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+}
+
+/**
+ * Context window stats — updated reactively as messages are sent and contexts change.
+ */
+export 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;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function getLastResponseUsage(messages: UIMessage[]): MessageTokenUsage | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role === "assistant" && msg.metadata?.usage) {
+      const u = msg.metadata.usage as {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+      };
+      const prompt = u.prompt_tokens ?? 0;
+      const completion = u.completion_tokens ?? 0;
+      return {
+        prompt_tokens: prompt,
+        completion_tokens: completion,
+        total_tokens: u.total_tokens ?? prompt + completion,
+      };
+    }
+  }
+  return null;
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
+/**
+ * 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)
+ * ```
+ */
+export function useContextStats(): ContextStats {
+  const { contextChars, contextUsage, registeredTools, messages } =
+    useCopilot();
+
+  const toolCount = useMemo(() => registeredTools.length, [registeredTools]);
+
+  const messageCount = useMemo(
+    () => messages.filter((m) => m.role !== "system").length,
+    [messages],
+  );
+
+  const totalTokens = useMemo(() => {
+    if (contextUsage) return contextUsage.total.tokens;
+    // fallback before first send: estimate from context chars
+    return Math.ceil(contextChars / 3.5);
+  }, [contextUsage, contextChars]);
+
+  const usagePercent = useMemo(() => {
+    if (contextUsage) return contextUsage.total.percent;
+    return 0;
+  }, [contextUsage]);
+
+  const lastResponseUsage = useMemo(
+    () => getLastResponseUsage(messages),
+    [messages],
+  );
+
+  return {
+    contextUsage,
+    totalTokens,
+    usagePercent,
+    contextChars,
+    toolCount,
+    messageCount,
+    lastResponseUsage,
+  };
+}
diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index 8fb8231..6c08f55 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -240,3 +240,13 @@ export type {
   UseMessageHistoryReturn,
   MessageHistoryContextValue,
 } from "./message-history";
+
+// Context Stats Hook
+export {
+  useContextStats,
+  type ContextStats,
+  type MessageTokenUsage,
+} from "./hooks/useContextStats";
+
+// Re-export ContextUsage for useContextStats consumers
+export type { ContextUsage, ContextUsagePart } from "../core";
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index fbf77e9..ed51868 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -26,6 +26,7 @@ import type {
   MessageAttachment,
   PermissionLevel,
   ToolOptimizationConfig,
+  ContextUsage,
 } from "../../core";
 
 import type { MCPServerConfig } from "../../mcp/types";
@@ -346,6 +347,16 @@ export interface CopilotContextValue {
   // System Prompt
   setSystemPrompt: (prompt: string) => void;
 
+  // Context stats (reactive — updates when useAIContext adds/removes context)
+  /** 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;
+
   // Config
   threadId?: string;
   /**
@@ -467,6 +478,9 @@ export function CopilotProvider({
         onApprovalRequired: (execution) => {
           debugLog("Tool approval required:", execution.name);
         },
+        onContextUsageChange: (usage) => {
+          setContextUsage(usage);
+        },
         onError: (error) => {
           if (error) onError?.(error);
         },
@@ -599,6 +613,8 @@ export function CopilotProvider({
 
   const contextTreeRef = useRef<ContextTreeNode[]>([]);
   const contextIdCounter = useRef(0);
+  const [contextChars, setContextChars] = useState(0);
+  const [contextUsage, setContextUsage] = useState<ContextUsage | null>(null);
 
   const addContext = useCallback(
     (context: string, parentId?: string): string => {
@@ -611,6 +627,7 @@ export function CopilotProvider({
       // Update chat's context
       const contextString = printTree(contextTreeRef.current);
       chatRef.current?.setContext(contextString);
+      setContextChars(contextString.length);
       debugLog("Context added:", id);
       return id;
     },
@@ -623,6 +640,7 @@ export function CopilotProvider({
       // Update chat's context
       const contextString = printTree(contextTreeRef.current);
       chatRef.current?.setContext(contextString);
+      setContextChars(contextString.length);
       debugLog("Context removed:", id);
     },
     [debugLog],
@@ -740,6 +758,8 @@ export function CopilotProvider({
       // AI Context
       addContext,
       removeContext,
+      contextChars,
+      contextUsage,
 
       // System Prompt
       setSystemPrompt,
@@ -771,6 +791,8 @@ export function CopilotProvider({
       registeredActions,
       addContext,
       removeContext,
+      contextChars,
+      contextUsage,
       setSystemPrompt,
       threadId,
       runtimeUrl,

From c21fb42c87068cbd5aa9bdc441eaebb6674e004e Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 14 Mar 2026 19:40:50 +0530
Subject: [PATCH 14/72] feat(sdk): implement conversation branching (Phases
 1-3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- MessageTree: bidirectional flat-map tree (parentId + childrenIds[] + activeChildMap)
- ReactChatState: backed by MessageTree; messages getter = visible path; getAllMessages() = all branches
- AbstractChat: branch-aware regenerate() (setCurrentLeaf instead of slice); sendMessage({editMessageId}) fork support
- ChatWithTools + ReactChat + ReactChatWithTools: switchBranch/getBranchInfo/editMessage/hasBranches pass-throughs
- useChat/CopilotProvider/CopilotContext: branching methods wired into context
- BranchNavigator: ← N/M → presentational component
- default-message: inline edit (pencil on hover, textarea, submit), BranchNavigator below user bubbles
- connected-chat: switchBranch/getBranchInfo/editMessage wired from useCopilot to Chat
- BranchInfo/MessageTree exported from chat/index + react/index (framework-agnostic)
- All new fields optional — zero breaking changes for linear conversations

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../copilot-sdk/src/chat/ChatWithTools.ts     |   6 +-
 .../src/chat/branching/MessageTree.ts         | 384 ++++++++++++++++++
 .../copilot-sdk/src/chat/branching/index.ts   |   1 +
 .../src/chat/classes/AbstractChat.ts          |  74 +++-
 .../chat/functions/message/createMessage.ts   |  14 +-
 packages/copilot-sdk/src/chat/index.ts        |   6 +
 .../src/chat/interfaces/ChatState.ts          |  34 ++
 .../copilot-sdk/src/chat/types/message.ts     |   9 +
 .../copilot-sdk/src/core/types/message.ts     |  15 +
 .../src/react/context/CopilotContext.tsx      |  19 +-
 packages/copilot-sdk/src/react/index.ts       |   3 +
 .../src/react/internal/ReactChat.ts           |  34 ++
 .../src/react/internal/ReactChatState.ts      | 123 ++++--
 .../src/react/internal/ReactChatWithTools.ts  |  33 ++
 .../copilot-sdk/src/react/internal/useChat.ts |  67 ++-
 .../src/react/provider/CopilotProvider.tsx    |  40 ++
 .../src/ui/components/composed/chat/chat.tsx  |  11 +
 .../composed/chat/default-message.tsx         | 198 +++++++--
 .../src/ui/components/composed/chat/types.ts  |  28 ++
 .../ui/components/composed/connected-chat.tsx |   7 +
 .../src/ui/components/ui/branch-navigator.tsx | 125 ++++++
 packages/copilot-sdk/src/ui/index.ts          |   6 +
 22 files changed, 1165 insertions(+), 72 deletions(-)
 create mode 100644 packages/copilot-sdk/src/chat/branching/MessageTree.ts
 create mode 100644 packages/copilot-sdk/src/chat/branching/index.ts
 create mode 100644 packages/copilot-sdk/src/ui/components/ui/branch-navigator.tsx

diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index 772bdcd..6f28165 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -375,10 +375,14 @@ export class ChatWithTools {
   /**
    * Send a message
    * Returns false if a request is already in progress
+   *
+   * @param options.editMessageId - Edit flow: new message branches from the
+   *   same parent as this message ID
    */
   async sendMessage(
     content: string,
     attachments?: MessageAttachment[],
+    options?: { editMessageId?: string },
   ): Promise<boolean> {
     // Guard: Don't send if already processing
     if (this.isLoading) {
@@ -388,7 +392,7 @@ export class ChatWithTools {
 
     // Reset iteration counter so user can continue after max iterations
     this.agentLoop.resetIterations();
-    return await this.chat.sendMessage(content, attachments);
+    return await this.chat.sendMessage(content, attachments, options);
   }
 
   /**
diff --git a/packages/copilot-sdk/src/chat/branching/MessageTree.ts b/packages/copilot-sdk/src/chat/branching/MessageTree.ts
new file mode 100644
index 0000000..634affa
--- /dev/null
+++ b/packages/copilot-sdk/src/chat/branching/MessageTree.ts
@@ -0,0 +1,384 @@
+/**
+ * MessageTree — Bidirectional flat-map message tree for conversation branching.
+ *
+ * Industry-standard data structure used by ChatGPT, Claude.ai, and Gemini:
+ * - parentId + childrenIds[] for O(1) navigation
+ * - activeChildMap tracks the active path through the tree
+ *
+ * Zero React dependency — pure TypeScript, works in any environment.
+ */
+
+import type { UIMessage } from "../types/message";
+
+// ============================================
+// Types
+// ============================================
+
+/**
+ * Branch navigation info for the UI navigator (← N/M →)
+ */
+export interface BranchInfo {
+  /** 0-based index of this message among its siblings */
+  siblingIndex: number;
+  /** Total number of sibling variants at this fork */
+  totalSiblings: number;
+  /** Ordered IDs of all siblings (oldest-first) */
+  siblingIds: string[];
+  hasPrevious: boolean;
+  hasNext: boolean;
+}
+
+// ============================================
+// MessageTree
+// ============================================
+
+export class MessageTree<T extends UIMessage = UIMessage> {
+  /** All messages by ID */
+  private nodeMap: Map<string, T> = new Map();
+  /** parentKey → ordered list of child IDs (insertion order = oldest-first) */
+  private childrenOf: Map<string, string[]> = new Map();
+  /** parentKey → currently-active child ID */
+  private activeChildMap: Map<string, string> = new Map();
+  /** Current leaf message ID (tip of the active path) */
+  private _currentLeafId: string | null = null;
+
+  /** Sentinel key used for root-level messages (parentId === null) */
+  static readonly ROOT_KEY = "__root__";
+
+  constructor(messages?: T[]) {
+    if (messages?.length) {
+      this._buildFromMessages(messages);
+    }
+  }
+
+  // ============================================
+  // Static Migration Helpers
+  // ============================================
+
+  /**
+   * Convert a legacy flat array (no parentId) to a tree-linked array.
+   *
+   * Rules:
+   * - Tool messages get parentId = the owning assistant message's id
+   *   (matched via toolCallId → toolCall.id).
+   * - All other messages get parentId of the previous non-tool message
+   *   (or null for the first message).
+   *
+   * Returns a new array with parentId/childrenIds filled in.
+   * Does NOT mutate the original messages.
+   */
+  static fromFlatArray<T extends UIMessage>(messages: T[]): T[] {
+    if (messages.length === 0) return messages;
+
+    // If already tree-linked (any message has parentId defined), return as-is
+    const alreadyLinked = messages.some((m) => m.parentId !== undefined);
+    if (alreadyLinked) return messages;
+
+    const result: T[] = [];
+    // Track linear parent chain (skip tool messages for parent tracking)
+    let prevNonToolId: string | null = null;
+
+    // Build assistant id → assistant message map for tool pairing
+    const assistantById = new Map<string, T>();
+    for (const msg of messages) {
+      if (msg.role === "assistant") {
+        assistantById.set(msg.id, msg);
+      }
+    }
+
+    for (const msg of messages) {
+      if (msg.role === "tool" && msg.toolCallId) {
+        // Find owning assistant message by matching toolCallId → toolCall.id
+        let ownerAssistantId: string | null = null;
+        for (const [, assistant] of assistantById) {
+          if (assistant.toolCalls?.some((tc) => tc.id === msg.toolCallId)) {
+            ownerAssistantId = assistant.id;
+            break;
+          }
+        }
+        result.push({
+          ...msg,
+          parentId: ownerAssistantId ?? prevNonToolId,
+          childrenIds: [],
+        });
+      } else {
+        result.push({
+          ...msg,
+          parentId: prevNonToolId,
+          childrenIds: [],
+        });
+        prevNonToolId = msg.id;
+      }
+    }
+
+    // Second pass: fill in childrenIds based on parentId assignments
+    const childrenMap = new Map<string, string[]>();
+    for (const msg of result) {
+      const parentKey =
+        msg.parentId == null ? MessageTree.ROOT_KEY : msg.parentId;
+      if (!childrenMap.has(parentKey)) {
+        childrenMap.set(parentKey, []);
+      }
+      childrenMap.get(parentKey)!.push(msg.id);
+    }
+
+    return result.map((msg) => ({
+      ...msg,
+      childrenIds: childrenMap.get(msg.id) ?? [],
+    }));
+  }
+
+  // ============================================
+  // Core Queries
+  // ============================================
+
+  /**
+   * Returns the visible path (root → current leaf) — what the UI renders
+   * and what gets sent to the API.
+   *
+   * Backward-compat: if NO message has parentId set (all undefined),
+   * falls back to insertion order (legacy linear mode).
+   */
+  getVisibleMessages(): T[] {
+    if (this.nodeMap.size === 0) return [];
+
+    // Legacy linear fallback: no parentId on any message
+    const hasTreeStructure = Array.from(this.nodeMap.values()).some(
+      (m) => m.parentId !== undefined,
+    );
+    if (!hasTreeStructure) {
+      return Array.from(this.nodeMap.values());
+    }
+
+    return this._getActivePath().map((id) => this.nodeMap.get(id)!);
+  }
+
+  /**
+   * Returns ALL messages across every branch (for persistence / ThreadManager).
+   */
+  getAllMessages(): T[] {
+    return Array.from(this.nodeMap.values());
+  }
+
+  /**
+   * Branch navigation info for the UI navigator.
+   * Returns null if the message has no siblings (only child).
+   */
+  getBranchInfo(messageId: string): BranchInfo | null {
+    const msg = this.nodeMap.get(messageId);
+    if (!msg) return null;
+
+    const parentKey = this._parentKey(msg.parentId);
+    const siblings = this.childrenOf.get(parentKey) ?? [];
+
+    if (siblings.length <= 1) return null;
+
+    const siblingIndex = siblings.indexOf(messageId);
+    return {
+      siblingIndex,
+      totalSiblings: siblings.length,
+      siblingIds: [...siblings],
+      hasPrevious: siblingIndex > 0,
+      hasNext: siblingIndex < siblings.length - 1,
+    };
+  }
+
+  get currentLeafId(): string | null {
+    return this._currentLeafId;
+  }
+
+  get hasBranches(): boolean {
+    for (const children of this.childrenOf.values()) {
+      if (children.length > 1) return true;
+    }
+    return false;
+  }
+
+  // ============================================
+  // Mutations
+  // ============================================
+
+  /**
+   * Insert a new message.
+   * - Updates childrenOf and nodeMap.
+   * - New branch becomes active (activeChildMap updated).
+   * - Updates current leaf.
+   */
+  addMessage(message: T): T {
+    this.nodeMap.set(message.id, message);
+
+    const parentKey = this._parentKey(message.parentId);
+    if (!this.childrenOf.has(parentKey)) {
+      this.childrenOf.set(parentKey, []);
+    }
+    const siblings = this.childrenOf.get(parentKey)!;
+    if (!siblings.includes(message.id)) {
+      siblings.push(message.id);
+    }
+
+    // New message becomes active at its parent fork
+    this.activeChildMap.set(parentKey, message.id);
+
+    // Update current leaf (walk forward from this message)
+    this._currentLeafId = this._walkToLeaf(message.id);
+
+    return message;
+  }
+
+  /**
+   * Navigate: make messageId the active child at its parent fork,
+   * then walk to its leaf and update currentLeafId.
+   */
+  switchBranch(messageId: string): void {
+    const msg = this.nodeMap.get(messageId);
+    if (!msg) return;
+
+    const parentKey = this._parentKey(msg.parentId);
+    this.activeChildMap.set(parentKey, messageId);
+    this._currentLeafId = this._walkToLeaf(messageId);
+  }
+
+  /**
+   * Update message content in-place (streaming updates).
+   * No tree structure change.
+   */
+  updateMessage(id: string, updater: (msg: T) => T): boolean {
+    const existing = this.nodeMap.get(id);
+    if (!existing) return false;
+    this.nodeMap.set(id, updater(existing));
+    return true;
+  }
+
+  /**
+   * Set current leaf explicitly.
+   * Used by regenerate() to rewind the active path before pushing a new message.
+   */
+  setCurrentLeaf(leafId: string | null): void {
+    this._currentLeafId = leafId;
+
+    if (leafId === null) return;
+
+    // Ensure the active path points to this leaf
+    const msg = this.nodeMap.get(leafId);
+    if (!msg) return;
+
+    // Walk up and set activeChildMap entries so getVisibleMessages() is consistent
+    let current: T | undefined = msg;
+    while (current) {
+      const parentKey = this._parentKey(current.parentId);
+      this.activeChildMap.set(parentKey, current.id);
+      if (current.parentId == null || current.parentId === undefined) break;
+      current = this.nodeMap.get(current.parentId);
+    }
+  }
+
+  /**
+   * Rebuild entire tree from a message array.
+   * Used by setMessages().
+   */
+  reset(messages: T[]): void {
+    this.nodeMap.clear();
+    this.childrenOf.clear();
+    this.activeChildMap.clear();
+    this._currentLeafId = null;
+
+    if (messages.length > 0) {
+      this._buildFromMessages(messages);
+    }
+  }
+
+  // ============================================
+  // Private Helpers
+  // ============================================
+
+  private _buildFromMessages(messages: T[]): void {
+    // Auto-migrate legacy flat arrays
+    const linked = messages.some((m) => m.parentId !== undefined)
+      ? messages
+      : MessageTree.fromFlatArray(messages);
+
+    for (const msg of linked) {
+      this.nodeMap.set(msg.id, msg);
+
+      const parentKey = this._parentKey(msg.parentId);
+      if (!this.childrenOf.has(parentKey)) {
+        this.childrenOf.set(parentKey, []);
+      }
+      const siblings = this.childrenOf.get(parentKey)!;
+      if (!siblings.includes(msg.id)) {
+        siblings.push(msg.id);
+      }
+    }
+
+    // Build activeChildMap: default to last child at each fork
+    // (last child = most recently added = what was active when saved)
+    for (const [parentKey, children] of this.childrenOf) {
+      if (children.length > 0) {
+        this.activeChildMap.set(parentKey, children[children.length - 1]);
+      }
+    }
+
+    // Set current leaf by walking the active path from root
+    const path = this._getActivePath();
+    this._currentLeafId = path.length > 0 ? path[path.length - 1] : null;
+  }
+
+  private _parentKey(parentId: string | null | undefined): string {
+    if (parentId == null || parentId === undefined) {
+      return MessageTree.ROOT_KEY;
+    }
+    return parentId;
+  }
+
+  /**
+   * Walk forward from a message along active children to find the leaf.
+   */
+  private _walkToLeaf(fromId: string): string {
+    let current = fromId;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const children = this.childrenOf.get(current);
+      if (!children || children.length === 0) break;
+      const activeChild = this.activeChildMap.get(current);
+      if (!activeChild) break;
+      if (!this.nodeMap.has(activeChild)) break;
+      current = activeChild;
+    }
+    return current;
+  }
+
+  /**
+   * Walk the active path from root to the current leaf.
+   */
+  private _getActivePath(): string[] {
+    const path: string[] = [];
+    const visited = new Set<string>();
+
+    // Start from root children
+    const rootChildren = this.childrenOf.get(MessageTree.ROOT_KEY) ?? [];
+    if (rootChildren.length === 0) return path;
+
+    // Pick active root child
+    let activeId = this.activeChildMap.get(MessageTree.ROOT_KEY);
+    if (!activeId) {
+      // Fall back to last root child
+      activeId = rootChildren[rootChildren.length - 1];
+    }
+
+    // Walk forward along active children
+    let current: string | undefined = activeId;
+    while (current && !visited.has(current)) {
+      if (!this.nodeMap.has(current)) break;
+      visited.add(current);
+      path.push(current);
+
+      // Check if this message has an override active child set
+      // (used when setCurrentLeaf rewinds the active path)
+      const activeChild = this.activeChildMap.get(current);
+      if (!activeChild || !this.nodeMap.has(activeChild)) break;
+      current = activeChild;
+    }
+
+    return path;
+  }
+}
diff --git a/packages/copilot-sdk/src/chat/branching/index.ts b/packages/copilot-sdk/src/chat/branching/index.ts
new file mode 100644
index 0000000..12bd694
--- /dev/null
+++ b/packages/copilot-sdk/src/chat/branching/index.ts
@@ -0,0 +1 @@
+export { MessageTree, type BranchInfo } from "./MessageTree";
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 6bcd59f..98c13a4 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -170,10 +170,19 @@ export 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
    */
   async sendMessage(
     content: string,
     attachments?: MessageAttachment[],
+    options?: {
+      editMessageId?: string;
+    },
   ): Promise<boolean> {
     // Guard: Don't send if already processing
     if (this.isBusy) {
@@ -181,15 +190,34 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       return false;
     }
 
-    this.debug("sendMessage", { content, attachments });
+    this.debug("sendMessage", { content, attachments, options });
 
     try {
       // IMPORTANT: Resolve any pending tool_calls before sending
       // This prevents Anthropic API errors: "tool_use without tool_result"
       this.resolveUnresolvedToolCalls();
 
-      // Create user message
-      const userMessage = createUserMessage(content, attachments) as T;
+      // Edit flow: branch from the same parent as the edited message
+      let newParentId: string | null | undefined;
+      if (options?.editMessageId && this.state.setCurrentLeaf) {
+        const allMessages =
+          this.state.getAllMessages?.() ?? this.state.messages;
+        const target = allMessages.find(
+          (m) => m.id === options.editMessageId,
+        );
+        if (target && target.parentId !== undefined) {
+          newParentId = target.parentId;
+          // Rewind active path to just before the original message
+          this.state.setCurrentLeaf(
+            typeof target.parentId === "string" ? target.parentId : null,
+          );
+        }
+      }
+
+      // Create user message (with optional parentId for branching)
+      const userMessage = createUserMessage(content, attachments, {
+        parentId: newParentId,
+      }) as T;
 
       // Add to state
       this.state.pushMessage(userMessage);
@@ -385,31 +413,51 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
   }
 
   /**
-   * 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.
    */
   async regenerate(messageId?: string): Promise<void> {
-    // Remove messages from the specified ID (or last assistant message)
-    const messages = this.state.messages;
-    let targetIndex = messages.length - 1;
+    if (this.isBusy) return;
+
+    const messages = this.state.messages; // visible path
+    let targetMessage: T | undefined;
 
     if (messageId) {
-      targetIndex = messages.findIndex((m) => m.id === messageId);
+      targetMessage = messages.find((m) => m.id === messageId);
     } else {
-      // Find last assistant message
+      // Find last assistant message in the visible path
       for (let i = messages.length - 1; i >= 0; i--) {
         if (messages[i].role === "assistant") {
-          targetIndex = i;
+          targetMessage = messages[i];
           break;
         }
       }
     }
 
+    if (!targetMessage) return;
+
+    // Branch-aware regenerate: preserve old response as inactive sibling
+    if (targetMessage.parentId !== undefined && this.state.setCurrentLeaf) {
+      // Rewind active path to target's parent
+      // The new assistant response will be pushed as a new child (sibling)
+      this.state.setCurrentLeaf(targetMessage.parentId ?? null);
+      this.callbacks.onMessagesChange?.(this.state.messages);
+      this.state.status = "submitted";
+      await Promise.resolve();
+      await this.processRequest();
+      return;
+    }
+
+    // Legacy fallback: old slice() behavior for non-tree-aware state
+    const targetIndex = messages.indexOf(targetMessage);
     if (targetIndex > 0) {
-      // Remove from target onwards
       this.state.setMessages(messages.slice(0, targetIndex));
       this.callbacks.onMessagesChange?.(this.state.messages);
-
-      // Resend
       await this.processRequest();
     }
   }
diff --git a/packages/copilot-sdk/src/chat/functions/message/createMessage.ts b/packages/copilot-sdk/src/chat/functions/message/createMessage.ts
index e198e16..0cdab2a 100644
--- a/packages/copilot-sdk/src/chat/functions/message/createMessage.ts
+++ b/packages/copilot-sdk/src/chat/functions/message/createMessage.ts
@@ -19,11 +19,15 @@ export function generateMessageId(): string {
  *
  * @param content - Message content
  * @param attachments - Optional attachments
+ * @param options - Optional branching options
  * @returns New user message
  */
 export function createUserMessage(
   content: string,
   attachments?: MessageAttachment[],
+  options?: {
+    parentId?: string | null;
+  },
 ): UIMessage {
   return {
     id: generateMessageId(),
@@ -31,6 +35,7 @@ export function createUserMessage(
     content,
     attachments,
     createdAt: new Date(),
+    ...(options?.parentId !== undefined ? { parentId: options.parentId } : {}),
   };
 }
 
@@ -156,13 +161,20 @@ export function streamStateToMessage(state: StreamingMessageState): UIMessage {
  * Create an empty assistant message (for streaming)
  *
  * @param id - Optional message ID
+ * @param options - Optional branching options
  * @returns Empty assistant message
  */
-export function createEmptyAssistantMessage(id?: string): UIMessage {
+export function createEmptyAssistantMessage(
+  id?: string,
+  options?: {
+    parentId?: string | null;
+  },
+): UIMessage {
   return {
     id: id ?? generateMessageId(),
     role: "assistant",
     content: "",
     createdAt: new Date(),
+    ...(options?.parentId !== undefined ? { parentId: options.parentId } : {}),
   };
 }
diff --git a/packages/copilot-sdk/src/chat/index.ts b/packages/copilot-sdk/src/chat/index.ts
index eddc84b..13c4805 100644
--- a/packages/copilot-sdk/src/chat/index.ts
+++ b/packages/copilot-sdk/src/chat/index.ts
@@ -85,6 +85,12 @@ export {
   type ChatWithToolsCallbacks,
 } from "./ChatWithTools";
 
+// ============================================
+// Branching
+// ============================================
+
+export { MessageTree, type BranchInfo } from "./branching";
+
 // ============================================
 // Pure Functions
 // ============================================
diff --git a/packages/copilot-sdk/src/chat/interfaces/ChatState.ts b/packages/copilot-sdk/src/chat/interfaces/ChatState.ts
index 9693a00..577c927 100644
--- a/packages/copilot-sdk/src/chat/interfaces/ChatState.ts
+++ b/packages/copilot-sdk/src/chat/interfaces/ChatState.ts
@@ -6,6 +6,7 @@
  */
 
 import type { UIMessage, ChatStatus } from "../types/index";
+import type { BranchInfo } from "../branching";
 
 /**
  * ChatState interface - Framework adapters implement this
@@ -128,6 +129,39 @@ export interface ChatState<T extends UIMessage = UIMessage> {
    * Get error snapshot
    */
   getErrorSnapshot?(): Error | undefined;
+
+  // ============================================
+  // Branching Extensions (optional — only ReactChatState implements these)
+  // ============================================
+
+  /**
+   * 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;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/chat/types/message.ts b/packages/copilot-sdk/src/chat/types/message.ts
index 514b141..ac5fcbb 100644
--- a/packages/copilot-sdk/src/chat/types/message.ts
+++ b/packages/copilot-sdk/src/chat/types/message.ts
@@ -40,6 +40,15 @@ export interface UIMessage {
   createdAt: Date;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
+  /**
+   * Parent message ID for branching support.
+   * - null = root message (no parent)
+   * - undefined = legacy linear message (no branch awareness)
+   * - string = ID of parent message
+   */
+  parentId?: string | null;
+  /** Direct children IDs for O(1) sibling lookup */
+  childrenIds?: string[];
 }
 
 /**
diff --git a/packages/copilot-sdk/src/core/types/message.ts b/packages/copilot-sdk/src/core/types/message.ts
index 8cb9c46..ec46b99 100644
--- a/packages/copilot-sdk/src/core/types/message.ts
+++ b/packages/copilot-sdk/src/core/types/message.ts
@@ -146,6 +146,17 @@ export interface Message {
 
   /** 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[];
 }
 
 /**
@@ -195,6 +206,8 @@ export function createMessage(
     tool_call_id: partial.tool_call_id,
     metadata: partial.metadata,
     created_at: partial.created_at ?? new Date(),
+    ...(partial.parent_id !== undefined ? { parent_id: partial.parent_id } : {}),
+    ...(partial.children_ids !== undefined ? { children_ids: partial.children_ids } : {}),
   };
 }
 
@@ -207,6 +220,7 @@ export function createUserMessage(
     id?: string;
     thread_id?: string;
     attachments?: MessageAttachment[];
+    parent_id?: string | null;
   },
 ): Message {
   return createMessage({
@@ -217,6 +231,7 @@ export function createUserMessage(
     metadata: options?.attachments
       ? { attachments: options.attachments }
       : undefined,
+    ...(options?.parent_id !== undefined ? { parent_id: options.parent_id } : {}),
   });
 }
 
diff --git a/packages/copilot-sdk/src/react/context/CopilotContext.tsx b/packages/copilot-sdk/src/react/context/CopilotContext.tsx
index 52c26d3..62255e6 100644
--- a/packages/copilot-sdk/src/react/context/CopilotContext.tsx
+++ b/packages/copilot-sdk/src/react/context/CopilotContext.tsx
@@ -19,6 +19,7 @@ import type {
   ToolPermission,
 } from "../../core";
 import type { ContextTreeNode } from "../utils/context-tree";
+import type { BranchInfo } from "../../chat/branching";
 
 /**
  * Chat UI state interface (UI-only state, not message data)
@@ -96,7 +97,7 @@ export 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;
@@ -106,6 +107,22 @@ export interface ChatActions {
    * - Free: converts to base64
    */
   processAttachment: (file: File) => Promise<MessageAttachment>;
+
+  // ============================================
+  // Branching Actions
+  // ============================================
+
+  /** 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;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index 6c08f55..935b6dd 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -250,3 +250,6 @@ export {
 
 // Re-export ContextUsage for useContextStats consumers
 export type { ContextUsage, ContextUsagePart } from "../core";
+
+// Branching
+export { MessageTree, type BranchInfo } from "../chat/branching";
diff --git a/packages/copilot-sdk/src/react/internal/ReactChat.ts b/packages/copilot-sdk/src/react/internal/ReactChat.ts
index cb4d486..803e2c3 100644
--- a/packages/copilot-sdk/src/react/internal/ReactChat.ts
+++ b/packages/copilot-sdk/src/react/internal/ReactChat.ts
@@ -16,6 +16,7 @@ import {
   type ChatEventHandler,
 } from "../../chat";
 import { ReactChatState } from "./ReactChatState";
+import type { BranchInfo } from "../../chat/branching";
 
 /**
  * Chat status for UI state
@@ -132,6 +133,39 @@ export class ReactChat extends AbstractChat<UIMessage> {
     return this.on("error", handler);
   }
 
+  // ============================================
+  // Branching API — pass-throughs to ReactChatState
+  // ============================================
+
+  /**
+   * Navigate to a sibling branch (makes it the active path).
+   */
+  switchBranch(messageId: string): void {
+    this.reactState.switchBranch(messageId);
+  }
+
+  /**
+   * Get branch navigation info for a message.
+   * Returns null if the message has no siblings.
+   */
+  getBranchInfo(messageId: string): BranchInfo | null {
+    return this.reactState.getBranchInfo(messageId);
+  }
+
+  /**
+   * Get all messages across all branches (for persistence).
+   */
+  getAllMessages(): UIMessage[] {
+    return this.reactState.getAllMessages();
+  }
+
+  /**
+   * Whether any message has siblings (branching has occurred).
+   */
+  get hasBranches(): boolean {
+    return this.reactState.hasBranches;
+  }
+
   // ============================================
   // Override dispose to clean up state
   // ============================================
diff --git a/packages/copilot-sdk/src/react/internal/ReactChatState.ts b/packages/copilot-sdk/src/react/internal/ReactChatState.ts
index 31554ae..df4090e 100644
--- a/packages/copilot-sdk/src/react/internal/ReactChatState.ts
+++ b/packages/copilot-sdk/src/react/internal/ReactChatState.ts
@@ -1,16 +1,19 @@
 /**
  * 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.
  */
 
 import type { ChatState, UIMessage, ChatStatus } from "../../chat";
+import { MessageTree, type BranchInfo } from "../../chat/branching";
 
 /**
  * ReactChatState implements ChatState with callback-based reactivity
+ * and full conversation branching support via MessageTree.
  *
  * @example
  * ```tsx
@@ -21,14 +24,17 @@ import type { ChatState, UIMessage, ChatStatus } from "../../chat";
  *   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();
  * ```
  */
 export class ReactChatState<
   T extends UIMessage = UIMessage,
 > implements ChatState<T> {
-  private _messages: T[] = [];
+  private tree: MessageTree<T>;
   private _status: ChatStatus = "ready";
   private _error: Error | undefined = undefined;
 
@@ -36,17 +42,21 @@ export class ReactChatState<
   private subscribers = new Set<() => void>();
 
   constructor(initialMessages?: T[]) {
-    if (initialMessages) {
-      this._messages = initialMessages;
-    }
+    this.tree = new MessageTree<T>(initialMessages);
   }
 
   // ============================================
-  // Getters
+  // Getters — visible path only
   // ============================================
 
+  /**
+   * 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[] {
-    return this._messages;
+    return this.tree.getVisibleMessages();
   }
 
   get status(): ChatStatus {
@@ -62,7 +72,7 @@ export class ReactChatState<
   // ============================================
 
   set messages(value: T[]) {
-    this._messages = value;
+    this.tree.reset(value);
     this.notify();
   }
 
@@ -81,53 +91,104 @@ export class ReactChatState<
   // ============================================
 
   pushMessage(message: T): void {
-    this._messages = [...this._messages, message];
+    this.tree.addMessage(message);
     this.notify();
   }
 
   popMessage(): void {
-    this._messages = this._messages.slice(0, -1);
+    // Remove current leaf from tree
+    const leafId = this.tree.currentLeafId;
+    if (!leafId) return;
+
+    const allMessages = this.tree.getAllMessages().filter((m) => m.id !== leafId);
+    // Walk up to the parent to set it as new leaf
+    const leaf = this.tree.getAllMessages().find((m) => m.id === leafId);
+    const newLeafId =
+      leaf && leaf.parentId !== undefined && leaf.parentId !== null
+        ? leaf.parentId
+        : null;
+
+    this.tree.reset(allMessages);
+    if (newLeafId) {
+      this.tree.setCurrentLeaf(newLeafId);
+    }
     this.notify();
   }
 
   replaceMessage(index: number, message: T): void {
-    this._messages = this._messages.map((m, i) => (i === index ? message : m));
+    // replaceMessage operates on the visible path
+    const visible = this.tree.getVisibleMessages();
+    const target = visible[index];
+    if (!target) return;
+    this.tree.updateMessage(target.id, () => message);
     this.notify();
   }
 
   updateLastMessage(updater: (message: T) => T): void {
-    if (this._messages.length === 0) return;
-
-    const lastIndex = this._messages.length - 1;
-    const lastMessage = this._messages[lastIndex];
-    this._messages = [
-      ...this._messages.slice(0, lastIndex),
-      updater(lastMessage),
-    ];
+    const leafId = this.tree.currentLeafId;
+    if (!leafId) return;
+    this.tree.updateMessage(leafId, updater);
     this.notify();
   }
 
   updateMessageById(id: string, updater: (message: T) => T): boolean {
-    const index = this._messages.findIndex((m) => m.id === id);
-    if (index === -1) return false;
-
-    this._messages = this._messages.map((m, i) =>
-      i === index ? updater(m) : m,
-    );
-    this.notify();
-    return true;
+    const updated = this.tree.updateMessage(id, updater);
+    if (updated) this.notify();
+    return updated;
   }
 
   setMessages(messages: T[]): void {
-    this._messages = messages;
+    this.tree.reset(messages);
     this.notify();
   }
 
   clearMessages(): void {
-    this._messages = [];
+    this.tree.reset([]);
     this.notify();
   }
 
+  // ============================================
+  // Branching API
+  // ============================================
+
+  /**
+   * Returns ALL messages across all branches.
+   * Use this for persistence (ThreadManager save).
+   */
+  getAllMessages(): T[] {
+    return this.tree.getAllMessages();
+  }
+
+  /**
+   * Get branch navigation info for a message.
+   * Returns null if the message has no siblings.
+   */
+  getBranchInfo(messageId: string): BranchInfo | null {
+    return this.tree.getBranchInfo(messageId);
+  }
+
+  /**
+   * Navigate to a sibling branch.
+   * Triggers re-render via notify().
+   */
+  switchBranch(messageId: string): void {
+    this.tree.switchBranch(messageId);
+    this.notify();
+  }
+
+  /**
+   * Set the current leaf (used by regenerate() to rewind active path).
+   * Triggers re-render via notify().
+   */
+  setCurrentLeaf(leafId: string | null): void {
+    this.tree.setCurrentLeaf(leafId);
+    this.notify();
+  }
+
+  get hasBranches(): boolean {
+    return this.tree.hasBranches;
+  }
+
   // ============================================
   // Subscription (for useSyncExternalStore)
   // ============================================
diff --git a/packages/copilot-sdk/src/react/internal/ReactChatWithTools.ts b/packages/copilot-sdk/src/react/internal/ReactChatWithTools.ts
index 7773fa5..8e382b8 100644
--- a/packages/copilot-sdk/src/react/internal/ReactChatWithTools.ts
+++ b/packages/copilot-sdk/src/react/internal/ReactChatWithTools.ts
@@ -12,6 +12,7 @@ import {
   type ToolExecution,
 } from "../../chat";
 import { ReactChatState } from "./ReactChatState";
+import type { BranchInfo } from "../../chat/branching";
 
 /**
  * React-specific configuration
@@ -60,6 +61,38 @@ export class ReactChatWithTools extends ChatWithTools {
     return this.reactState.subscribe(callback);
   };
 
+  // ============================================
+  // Branching API — pass-throughs to ReactChatState
+  // ============================================
+
+  /**
+   * Navigate to a sibling branch.
+   */
+  switchBranch(messageId: string): void {
+    this.reactState.switchBranch(messageId);
+  }
+
+  /**
+   * Get branch navigation info for a message.
+   */
+  getBranchInfo(messageId: string): BranchInfo | null {
+    return this.reactState.getBranchInfo(messageId);
+  }
+
+  /**
+   * Get all messages across all branches (for persistence).
+   */
+  getAllMessages(): UIMessage[] {
+    return this.reactState.getAllMessages();
+  }
+
+  /**
+   * Whether any message has siblings (branching has occurred).
+   */
+  get hasBranches(): boolean {
+    return this.reactState.hasBranches;
+  }
+
   /**
    * Dispose and cleanup
    */
diff --git a/packages/copilot-sdk/src/react/internal/useChat.ts b/packages/copilot-sdk/src/react/internal/useChat.ts
index e18a9c3..c64b602 100644
--- a/packages/copilot-sdk/src/react/internal/useChat.ts
+++ b/packages/copilot-sdk/src/react/internal/useChat.ts
@@ -17,6 +17,7 @@ import {
 import { ReactChat, createReactChat, type ReactChatConfig } from "./ReactChat";
 import type { UIMessage, ChatStatus } from "../../chat";
 import type { MessageAttachment } from "../../core";
+import type { BranchInfo } from "../../chat/branching";
 
 /**
  * Hook configuration
@@ -36,7 +37,7 @@ export interface UseChatConfig extends Omit<ReactChatConfig, "callbacks"> {
  * Hook return type
  */
 export interface UseChatReturn {
-  /** All messages */
+  /** All messages (visible path — active branch only) */
   messages: UIMessage[];
   /** Current status */
   status: ChatStatus;
@@ -59,7 +60,7 @@ export 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: (
@@ -67,6 +68,35 @@ export interface UseChatReturn {
   ) => Promise<void>;
   /** Reference to the ReactChat instance */
   chatRef: React.RefObject<ReactChat | null>;
+
+  // ============================================
+  // Branching API
+  // ============================================
+
+  /**
+   * 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;
 }
 
 /**
@@ -140,6 +170,12 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     () => undefined, // Server snapshot
   );
 
+  const hasBranches = useSyncExternalStore(
+    chatRef.current.subscribe,
+    () => chatRef.current!.hasBranches,
+    () => false,
+  );
+
   // Derived state
   const isLoading = status === "streaming" || status === "submitted";
 
@@ -175,6 +211,28 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     [],
   );
 
+  // Branching actions
+  const switchBranch = useCallback((messageId: string) => {
+    chatRef.current?.switchBranch(messageId);
+  }, []);
+
+  const getBranchInfo = useCallback(
+    (messageId: string): BranchInfo | null => {
+      return chatRef.current?.getBranchInfo(messageId) ?? null;
+    },
+    [],
+  );
+
+  const editMessage = useCallback(
+    async (messageId: string, newContent: string) => {
+      await chatRef.current?.sendMessage(newContent, undefined, {
+        editMessageId: messageId,
+      });
+      setInput("");
+    },
+    [],
+  );
+
   // Cleanup on unmount
   useEffect(() => {
     return () => {
@@ -196,5 +254,10 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     regenerate,
     continueWithToolResults,
     chatRef,
+    // Branching
+    switchBranch,
+    getBranchInfo,
+    editMessage,
+    hasBranches,
   };
 }
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index ed51868..56b0e50 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -318,6 +318,12 @@ export interface CopilotContextValue {
   setMessages: (messages: UIMessage[]) => void;
   regenerate: (messageId?: string) => Promise<void>;
 
+  // Branching actions
+  switchBranch: (messageId: string) => void;
+  getBranchInfo: (messageId: string) => import("../../chat/branching").BranchInfo | null;
+  editMessage: (messageId: string, newContent: string) => Promise<void>;
+  hasBranches: boolean;
+
   // Tool execution
   registerTool: (tool: ToolDefinition) => void;
   unregisterTool: (name: string) => void;
@@ -686,6 +692,30 @@ export function CopilotProvider({
     await chatRef.current?.regenerate(messageId);
   }, []);
 
+  const switchBranch = useCallback((messageId: string) => {
+    chatRef.current?.switchBranch(messageId);
+  }, []);
+
+  const getBranchInfo = useCallback(
+    (messageId: string) => chatRef.current?.getBranchInfo(messageId) ?? null,
+    [],
+  );
+
+  const editMessage = useCallback(
+    async (messageId: string, newContent: string) => {
+      await chatRef.current?.sendMessage(newContent, undefined, {
+        editMessageId: messageId,
+      });
+    },
+    [],
+  );
+
+  const hasBranches = useSyncExternalStore(
+    chatRef.current.subscribe,
+    () => chatRef.current!.hasBranches,
+    () => false,
+  );
+
   // ============================================
   // Callbacks
   // ============================================
@@ -741,6 +771,12 @@ export function CopilotProvider({
       setMessages,
       regenerate,
 
+      // Branching
+      switchBranch,
+      getBranchInfo,
+      editMessage,
+      hasBranches,
+
       // Tool execution
       registerTool,
       unregisterTool,
@@ -779,6 +815,10 @@ export function CopilotProvider({
       clearMessages,
       setMessages,
       regenerate,
+      switchBranch,
+      getBranchInfo,
+      editMessage,
+      hasBranches,
       registerTool,
       unregisterTool,
       registeredTools,
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 11e0219..4b27402 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -547,6 +547,10 @@ function ChatComponent({
   currentThreadId,
   onSwitchThread,
   isThreadBusy,
+  // Branching
+  getBranchInfo,
+  onSwitchBranch,
+  onEditMessage,
 }: ChatProps) {
   // Merge avatar props with defaults (so user can pass partial config)
   const userAvatar = { fallback: "U", ...userAvatarProp };
@@ -1038,6 +1042,13 @@ function ChatComponent({
                         citations={
                           citations === false ? { enabled: false } : citations
                         }
+                        branchInfo={
+                          message.role === "user"
+                            ? getBranchInfo?.(message.id) ?? null
+                            : null
+                        }
+                        onSwitchBranch={onSwitchBranch}
+                        onEditMessage={onEditMessage}
                       />
                     );
                   })}
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index f6b0b67..2fc5252 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -22,6 +22,8 @@ import type {
 import type { ToolDefinition, ToolRenderProps } from "../../../../core";
 import CopilotSDKLogo from "../../icons/copilot-sdk-logo";
 import { SourceGroup, type SourceItem } from "../../ui/source";
+import { BranchNavigator } from "../../ui/branch-navigator";
+import type { BranchInfo } from "../../../../chat/branching";
 
 type DefaultMessageProps = {
   message: ChatMessage;
@@ -87,6 +89,26 @@ type DefaultMessageProps = {
   followUpButtonClassName?: string;
   /** Citation/Sources configuration */
   citations?: CitationConfig;
+
+  // ============================================
+  // Branching
+  // ============================================
+
+  /**
+   * Branch navigation info for this message.
+   * When non-null and totalSiblings > 1, the BranchNavigator is shown.
+   */
+  branchInfo?: BranchInfo | null;
+  /**
+   * Called when the user navigates to a sibling branch.
+   * Receives the message ID to switch to.
+   */
+  onSwitchBranch?: (messageId: string) => void;
+  /**
+   * Called when the user submits an edited message.
+   * Triggers a new branch from the same parent as messageId.
+   */
+  onEditMessage?: (messageId: string, newContent: string) => void;
 };
 
 export function DefaultMessage({
@@ -112,6 +134,9 @@ export function DefaultMessage({
   followUpClassName,
   followUpButtonClassName,
   citations = { enabled: true },
+  branchInfo,
+  onSwitchBranch,
+  onEditMessage,
 }: DefaultMessageProps) {
   const isUser = message.role === "user";
   const isCompactionMarker =
@@ -119,6 +144,47 @@ export function DefaultMessage({
     (message.metadata as Record<string, unknown>)?.type === "compaction-marker";
   const isStreaming = isLastMessage && isLoading;
 
+  // Inline-edit state (user messages only)
+  const [isEditing, setIsEditing] = React.useState(false);
+  const [editValue, setEditValue] = React.useState(message.content ?? "");
+  const editRef = React.useRef<HTMLTextAreaElement>(null);
+
+  const startEdit = React.useCallback(() => {
+    setEditValue(message.content ?? "");
+    setIsEditing(true);
+    // Focus textarea on next frame
+    requestAnimationFrame(() => editRef.current?.focus());
+  }, [message.content]);
+
+  const cancelEdit = React.useCallback(() => {
+    setIsEditing(false);
+  }, []);
+
+  const submitEdit = React.useCallback(() => {
+    const trimmed = editValue.trim();
+    if (!trimmed || !onEditMessage) return;
+    onEditMessage(message.id, trimmed);
+    setIsEditing(false);
+  }, [editValue, message.id, onEditMessage]);
+
+  const handleEditKeyDown = React.useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        submitEdit();
+      }
+      if (e.key === "Escape") {
+        cancelEdit();
+      }
+    },
+    [submitEdit, cancelEdit],
+  );
+
+  // Whether branching UI should be shown for this message
+  const showBranchNav =
+    isUser && branchInfo && branchInfo.totalSiblings > 1 && onSwitchBranch;
+  const showEditBtn = isUser && !!onEditMessage && !isLoading;
+
   // Render compaction marker divider
   if (isCompactionMarker) {
     const tokensSaved = (message.metadata as Record<string, unknown>)
@@ -276,32 +342,118 @@ export function DefaultMessage({
 
     return (
       <Message
-        className={cn(
-          "flex gap-2",
-          showUserAvatar ? "justify-end" : "justify-end",
-        )}
+        className={cn("flex gap-2 group/user-msg justify-end")}
       >
         <div className="flex flex-col items-end max-w-[80%] min-w-0">
-          {/* Text content */}
-          {message.content && (
-            <MessageContent
-              className={cn(
-                "csdk-message-user rounded-lg px-4 py-2 bg-primary text-primary-foreground",
-                userMessageClassName,
-              )}
-              markdown
-              size={size}
-            >
-              {message.content}
-            </MessageContent>
-          )}
-          {/* Image Attachments */}
-          {hasAttachments && (
-            <div className="mt-2 flex flex-wrap gap-2 justify-end">
-              {message.attachments!.map((attachment, index) => (
-                <AttachmentPreview key={index} attachment={attachment} />
-              ))}
+          {/* Edit mode: inline textarea */}
+          {isEditing ? (
+            <div className="flex flex-col gap-1.5 w-full min-w-[200px]">
+              <textarea
+                ref={editRef}
+                value={editValue}
+                onChange={(e) => setEditValue(e.target.value)}
+                onKeyDown={handleEditKeyDown}
+                rows={Math.max(2, (editValue.match(/\n/g) || []).length + 1)}
+                className={cn(
+                  "csdk-edit-textarea w-full rounded-lg px-3 py-2 text-sm resize-none",
+                  "bg-primary text-primary-foreground placeholder:text-primary-foreground/50",
+                  "focus:outline-none focus:ring-2 focus:ring-primary-foreground/30",
+                  userMessageClassName,
+                )}
+              />
+              <div className="flex gap-1.5 justify-end">
+                <button
+                  type="button"
+                  onClick={cancelEdit}
+                  className="csdk-edit-cancel px-3 py-1 text-xs rounded-md bg-muted text-muted-foreground hover:bg-muted/80 transition-colors"
+                >
+                  Cancel
+                </button>
+                <button
+                  type="button"
+                  onClick={submitEdit}
+                  disabled={!editValue.trim()}
+                  className="csdk-edit-submit px-3 py-1 text-xs rounded-md bg-primary text-primary-foreground hover:bg-primary/90 disabled:opacity-50 transition-colors"
+                >
+                  Send
+                </button>
+              </div>
             </div>
+          ) : (
+            <>
+              {/* Text content */}
+              {message.content && (
+                <div className="relative">
+                  <MessageContent
+                    className={cn(
+                      "csdk-message-user rounded-lg px-4 py-2 bg-primary text-primary-foreground",
+                      userMessageClassName,
+                    )}
+                    markdown
+                    size={size}
+                  >
+                    {message.content}
+                  </MessageContent>
+                  {/* Edit button — hover reveal */}
+                  {showEditBtn && (
+                    <button
+                      type="button"
+                      onClick={startEdit}
+                      aria-label="Edit message"
+                      className={cn(
+                        "csdk-edit-btn absolute -left-7 top-1/2 -translate-y-1/2",
+                        "size-6 flex items-center justify-center rounded-full",
+                        "text-muted-foreground bg-background border border-border shadow-sm",
+                        "opacity-0 group-hover/user-msg:opacity-100 transition-opacity",
+                        "hover:text-foreground hover:bg-muted",
+                      )}
+                    >
+                      <svg
+                        width="12"
+                        height="12"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth={2}
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                      >
+                        <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" />
+                        <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z" />
+                      </svg>
+                    </button>
+                  )}
+                </div>
+              )}
+              {/* Image Attachments */}
+              {hasAttachments && (
+                <div className="mt-2 flex flex-wrap gap-2 justify-end">
+                  {message.attachments!.map((attachment, index) => (
+                    <AttachmentPreview key={index} attachment={attachment} />
+                  ))}
+                </div>
+              )}
+              {/* Branch Navigator */}
+              {showBranchNav && (
+                <BranchNavigator
+                  siblingIndex={branchInfo!.siblingIndex}
+                  totalSiblings={branchInfo!.totalSiblings}
+                  hasPrevious={branchInfo!.hasPrevious}
+                  hasNext={branchInfo!.hasNext}
+                  onPrevious={() =>
+                    onSwitchBranch!(
+                      branchInfo!.siblingIds[branchInfo!.siblingIndex - 1],
+                    )
+                  }
+                  onNext={() =>
+                    onSwitchBranch!(
+                      branchInfo!.siblingIds[branchInfo!.siblingIndex + 1],
+                    )
+                  }
+                  className="mt-1"
+                />
+              )}
+            </>
           )}
         </div>
         {showUserAvatar && (
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
index e903df6..cf4efdb 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
@@ -3,6 +3,7 @@ import type { ToolExecutionData, ToolApprovalStatus } from "../tools";
 import type { PermissionLevel } from "../../ui/permission-confirmation";
 import type { ToolDefinition } from "../../../../core";
 import type { Thread } from "../../../../core/types/thread";
+import type { BranchInfo } from "../../../../chat/branching";
 
 // ============================================
 // Citation Configuration
@@ -70,6 +71,14 @@ export type ChatMessage = {
   }>;
   /** Additional metadata (citations, etc.) */
   metadata?: Record<string, unknown>;
+  /**
+   * Parent message ID for branching support.
+   * - null = root message (no parent)
+   * - undefined = legacy linear message (no branch awareness)
+   */
+  parent_id?: string | null;
+  /** Direct children IDs for O(1) sibling lookup */
+  children_ids?: string[];
 };
 
 export type { ToolApprovalStatus, PermissionLevel };
@@ -482,4 +491,23 @@ export type ChatProps = {
   onSwitchThread?: (threadId: string) => void;
   /** Whether a thread operation is in progress (disables controls) */
   isThreadBusy?: boolean;
+
+  // === Branching (conversation variants) ===
+  /**
+   * Returns branch navigation info for a message ID.
+   * Provide this to enable the ← N/M → navigator below edited user messages.
+   * Wire from `useChat().getBranchInfo` or `useCopilot().actions.getBranchInfo`.
+   */
+  getBranchInfo?: (messageId: string) => BranchInfo | null;
+  /**
+   * Called when the user clicks ← or → in the branch navigator.
+   * Wire from `useChat().switchBranch` or `useCopilot().actions.switchBranch`.
+   */
+  onSwitchBranch?: (messageId: string) => void;
+  /**
+   * Called when the user submits an edit to a user message.
+   * Creates a new branch from the same parent as the original message.
+   * Wire from `useChat().editMessage` or `useCopilot().actions.editMessage`.
+   */
+  onEditMessage?: (messageId: string, newContent: string) => void;
 };
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index 647e538..23cad4b 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -324,6 +324,9 @@ function CopilotChatBase(
     approveToolExecution,
     rejectToolExecution,
     registeredTools,
+    switchBranch,
+    getBranchInfo,
+    editMessage,
   } = useCopilot();
 
   // Convert tool executions to the expected format
@@ -630,6 +633,10 @@ function CopilotChatBase(
       currentThreadId={threadManager.currentThreadId}
       onSwitchThread={isPersistenceEnabled ? handleSwitchThread : undefined}
       isThreadBusy={isBusy}
+      // Branching (auto-wired from context)
+      getBranchInfo={getBranchInfo}
+      onSwitchBranch={switchBranch}
+      onEditMessage={editMessage}
     >
       {children}
     </Chat>
diff --git a/packages/copilot-sdk/src/ui/components/ui/branch-navigator.tsx b/packages/copilot-sdk/src/ui/components/ui/branch-navigator.tsx
new file mode 100644
index 0000000..81dd10a
--- /dev/null
+++ b/packages/copilot-sdk/src/ui/components/ui/branch-navigator.tsx
@@ -0,0 +1,125 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../../lib/utils";
+
+// ============================================
+// Types
+// ============================================
+
+export interface BranchNavigatorProps {
+  /** 0-based index of the current sibling */
+  siblingIndex: number;
+  /** Total number of sibling variants at this fork */
+  totalSiblings: number;
+  /** Whether there is a previous sibling to navigate to */
+  hasPrevious: boolean;
+  /** Whether there is a next sibling to navigate to */
+  hasNext: boolean;
+  /** Navigate to the previous sibling */
+  onPrevious: () => void;
+  /** Navigate to the next sibling */
+  onNext: () => void;
+  /** Additional class names */
+  className?: string;
+}
+
+// ============================================
+// BranchNavigator
+// ============================================
+
+/**
+ * BranchNavigator — ← N/M → variant navigator shown below user messages
+ * when a conversation has been branched (via edit or regenerate).
+ *
+ * Purely presentational — no SDK dependency.
+ *
+ * @example
+ * ```tsx
+ * <BranchNavigator
+ *   siblingIndex={1}
+ *   totalSiblings={3}
+ *   hasPrevious={true}
+ *   hasNext={true}
+ *   onPrevious={() => switchBranch(siblings[0])}
+ *   onNext={() => switchBranch(siblings[2])}
+ * />
+ * ```
+ */
+export function BranchNavigator({
+  siblingIndex,
+  totalSiblings,
+  hasPrevious,
+  hasNext,
+  onPrevious,
+  onNext,
+  className,
+}: BranchNavigatorProps) {
+  return (
+    <div
+      className={cn(
+        "csdk-branch-navigator flex items-center gap-1 text-xs text-muted-foreground select-none",
+        className,
+      )}
+    >
+      {/* ← Previous */}
+      <button
+        type="button"
+        onClick={onPrevious}
+        disabled={!hasPrevious}
+        aria-label="Previous version"
+        className={cn(
+          "p-0.5 rounded transition-colors",
+          hasPrevious
+            ? "hover:text-foreground hover:bg-muted cursor-pointer"
+            : "opacity-30 cursor-default",
+        )}
+      >
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2.5}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M15 18l-6-6 6-6" />
+        </svg>
+      </button>
+
+      {/* N / M */}
+      <span className="tabular-nums leading-none">
+        {siblingIndex + 1}&thinsp;/&thinsp;{totalSiblings}
+      </span>
+
+      {/* → Next */}
+      <button
+        type="button"
+        onClick={onNext}
+        disabled={!hasNext}
+        aria-label="Next version"
+        className={cn(
+          "p-0.5 rounded transition-colors",
+          hasNext
+            ? "hover:text-foreground hover:bg-muted cursor-pointer"
+            : "opacity-30 cursor-default",
+        )}
+      >
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2.5}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M9 18l6-6-6-6" />
+        </svg>
+      </button>
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/src/ui/index.ts b/packages/copilot-sdk/src/ui/index.ts
index 7a90093..e21b9cf 100644
--- a/packages/copilot-sdk/src/ui/index.ts
+++ b/packages/copilot-sdk/src/ui/index.ts
@@ -159,6 +159,12 @@ export {
   type FollowUpProps,
 } from "./components/ui/follow-up";
 
+// Branch navigator (← N/M → variant navigation for branched conversations)
+export {
+  BranchNavigator,
+  type BranchNavigatorProps,
+} from "./components/ui/branch-navigator";
+
 // DevLogger (Development debugging tool)
 export {
   DevLogger,

From a2273898927eddc5c3eba0263d94e08dee625212 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 14 Mar 2026 19:41:00 +0530
Subject: [PATCH 15/72] =?UTF-8?q?feat(sdk):=20fix=20branch=20persistence?=
 =?UTF-8?q?=20=E2=80=94=20save/load=20all=20branches=20via=20getAllMessage?=
 =?UTF-8?q?s?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CopilotProvider: add getAllMessages() to CopilotContextValue; onMessagesChange effect
  now uses chatRef.current.getAllMessages() so all branches (not just visible path) are
  passed to external callbacks; adds parent_id/children_ids to Message mapping
- useInternalThreadManager: destructure getAllMessages from useCopilot(); save effect
  now persists getAllMessages() instead of visible-path messages; convertToCore includes
  parent_id/children_ids; both load paths (switchThread + auto-restore) now map
  parent_id→parentId and children_ids→childrenIds so branches survive page reload

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/react/provider/CopilotProvider.tsx        | 15 ++++++++++++++-
 .../src/ui/hooks/useInternalThreadManager.ts      | 15 +++++++++++++--
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 56b0e50..ca9dbd3 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -323,6 +323,8 @@ export interface CopilotContextValue {
   getBranchInfo: (messageId: string) => import("../../chat/branching").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[];
 
   // Tool execution
   registerTool: (tool: ToolDefinition) => void;
@@ -716,6 +718,11 @@ export function CopilotProvider({
     () => false,
   );
 
+  const getAllMessages = useCallback(
+    () => chatRef.current?.getAllMessages?.() ?? [],
+    [],
+  );
+
   // ============================================
   // Callbacks
   // ============================================
@@ -723,13 +730,17 @@ export function CopilotProvider({
   // Notify external callbacks
   useEffect(() => {
     if (onMessagesChange && messages.length > 0) {
-      const coreMessages: Message[] = messages.map((m) => ({
+      // Use getAllMessages() to persist all branches, not just the visible path
+      const allUIMessages = chatRef.current?.getAllMessages?.() ?? messages;
+      const coreMessages: Message[] = allUIMessages.map((m) => ({
         id: m.id,
         role: m.role,
         content: m.content,
         created_at: m.createdAt,
         tool_calls: m.toolCalls,
         tool_call_id: m.toolCallId,
+        parent_id: m.parentId,
+        children_ids: m.childrenIds,
         metadata: {
           attachments: m.attachments,
           thinking: m.thinking,
@@ -776,6 +787,7 @@ export function CopilotProvider({
       getBranchInfo,
       editMessage,
       hasBranches,
+      getAllMessages,
 
       // Tool execution
       registerTool,
@@ -819,6 +831,7 @@ export function CopilotProvider({
       getBranchInfo,
       editMessage,
       hasBranches,
+      getAllMessages,
       registerTool,
       unregisterTool,
       registeredTools,
diff --git a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
index e5fc662..ff24f7d 100644
--- a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
+++ b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
@@ -81,7 +81,7 @@ export function useInternalThreadManager(
   } = threadManager;
 
   // Get copilot context for setMessages and status
-  const { messages, setMessages, status, isLoading } = useCopilot();
+  const { messages, setMessages, status, isLoading, getAllMessages } = useCopilot();
 
   // Track if we're in the middle of loading messages from a thread switch
   const isLoadingMessagesRef = useRef(false);
@@ -113,6 +113,8 @@ export function useInternalThreadManager(
       created_at: m.createdAt,
       tool_calls: m.toolCalls,
       tool_call_id: m.toolCallId,
+      parent_id: m.parentId,
+      children_ids: m.childrenIds,
       // Preserve full metadata including citations, toolExecutions, etc.
       metadata: {
         ...m.metadata,
@@ -136,6 +138,8 @@ export function useInternalThreadManager(
           createdAt: m.created_at ?? new Date(),
           toolCalls: m.tool_calls,
           toolCallId: m.tool_call_id,
+          parentId: m.parent_id,
+          childrenIds: m.children_ids,
           attachments: m.metadata?.attachments,
         }));
         lastSavedSnapshotRef.current = getMessageSnapshot(uiMessages);
@@ -197,6 +201,8 @@ export function useInternalThreadManager(
         createdAt: m.created_at ?? new Date(),
         toolCalls: m.tool_calls,
         toolCallId: m.tool_call_id,
+        parentId: m.parent_id,
+        childrenIds: m.children_ids,
         attachments: m.metadata?.attachments,
         thinking: m.metadata?.thinking as string | undefined,
         // Preserve full metadata including citations, toolExecutions, etc.
@@ -241,7 +247,11 @@ export function useInternalThreadManager(
       return;
     }
 
-    const coreMessages = convertToCore(messages);
+    // Use getAllMessages() so all branches are persisted, not just the visible path
+    const allUIMessages = getAllMessages();
+    const coreMessages = convertToCore(
+      allUIMessages.length > 0 ? allUIMessages : messages,
+    );
 
     // If no thread exists, create one with these messages
     if (!currentThreadId && !savingToThreadRef.current) {
@@ -276,6 +286,7 @@ export function useInternalThreadManager(
     refreshThreads,
     getMessageSnapshot,
     convertToCore,
+    getAllMessages,
     onThreadChange,
   ]);
 

From 4551c6d1c7034088602e2d49f5ef127dfd82a86a Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 14 Mar 2026 21:03:16 +0530
Subject: [PATCH 16/72] feat(sdk): branching edge case fixes, docs, and
 experimental demo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- AbstractChat: _allMessages() helper — onMessagesChange callbacks now pass
  all branches (not just visible path) for framework-agnostic persistence
- AbstractChat: regenerate(messageId) falls back to getAllMessages() when
  target is on an inactive branch (was silently failing before)
- BRANCHING.md: full feature doc — APIs, DB changes, adoption guide,
  how-it-works, live demo reference
- examples/experimental: /branching demo route — BranchTreePanel live tree
  visualization + CopilotChat side-by-side inside one CopilotProvider

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../app/api/chat/branching/route.ts           |  21 +
 examples/experimental/app/branching/page.tsx  |  52 ++
 examples/experimental/app/page.tsx            |   5 +
 .../components/branching/BranchTreePanel.tsx  | 182 +++++++
 packages/copilot-sdk/BRANCHING.md             | 448 ++++++++++++++++++
 .../src/chat/classes/AbstractChat.ts          |  31 +-
 6 files changed, 731 insertions(+), 8 deletions(-)
 create mode 100644 examples/experimental/app/api/chat/branching/route.ts
 create mode 100644 examples/experimental/app/branching/page.tsx
 create mode 100644 examples/experimental/components/branching/BranchTreePanel.tsx
 create mode 100644 packages/copilot-sdk/BRANCHING.md

diff --git a/examples/experimental/app/api/chat/branching/route.ts b/examples/experimental/app/api/chat/branching/route.ts
new file mode 100644
index 0000000..29c75e8
--- /dev/null
+++ b/examples/experimental/app/api/chat/branching/route.ts
@@ -0,0 +1,21 @@
+import { createRuntime } from "@yourgpt/llm-sdk";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
+
+const anthropic = createAnthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+const runtime = createRuntime({
+  provider: anthropic,
+  model: "claude-haiku-4-5",
+  systemPrompt:
+    "You are a helpful assistant. Keep all replies to 1-2 sentences so branching is easy to demonstrate.",
+});
+
+export async function POST(request: Request) {
+  return runtime.handleRequest(request);
+}
+
+export async function GET() {
+  return Response.json({ status: "ok", provider: "anthropic", demo: "branching" });
+}
diff --git a/examples/experimental/app/branching/page.tsx b/examples/experimental/app/branching/page.tsx
new file mode 100644
index 0000000..6d53fa9
--- /dev/null
+++ b/examples/experimental/app/branching/page.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import { CopilotProvider } from "@yourgpt/copilot-sdk/react";
+import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
+import { BranchTreePanel } from "@/components/branching/BranchTreePanel";
+import Link from "next/link";
+import "@yourgpt/copilot-sdk/ui/styles.css";
+
+export default function BranchingPage() {
+  return (
+    <div className="h-screen flex flex-col bg-background">
+      {/* Header */}
+      <header className="flex items-center gap-4 px-4 py-3 border-b shrink-0">
+        <Link
+          href="/"
+          className="text-sm text-muted-foreground hover:text-foreground transition-colors"
+        >
+          ← Back
+        </Link>
+        <h1 className="text-sm font-semibold">Conversation Branching Demo</h1>
+        <span className="text-xs bg-violet-100 dark:bg-violet-900/40 text-violet-700 dark:text-violet-300 px-2 py-0.5 rounded-full font-mono">
+          feat/branching
+        </span>
+        <p className="text-xs text-muted-foreground ml-auto hidden sm:block">
+          Edit a message ✏ or regenerate to branch · Click nodes in the tree to
+          switch variants
+        </p>
+      </header>
+
+      {/* Two-panel layout inside a single CopilotProvider */}
+      <div className="flex-1 flex min-h-0">
+        <CopilotProvider runtimeUrl="/api/chat/branching">
+          {/* Left: Branch Tree Visualization */}
+          <div className="w-72 shrink-0 border-r flex flex-col overflow-hidden bg-card">
+            <BranchTreePanel />
+          </div>
+
+          {/* Right: CopilotChat with full branching UI */}
+          <div className="flex-1 min-w-0">
+            <CopilotChat
+              className="h-full"
+              placeholder="Send a message, then edit ✏ or regenerate to branch…"
+              showHeader
+              header={{ name: "Branching Chat" }}
+              showUserAvatar
+            />
+          </div>
+        </CopilotProvider>
+      </div>
+    </div>
+  );
+}
diff --git a/examples/experimental/app/page.tsx b/examples/experimental/app/page.tsx
index fa3a9a7..0cff1b9 100644
--- a/examples/experimental/app/page.tsx
+++ b/examples/experimental/app/page.tsx
@@ -1,6 +1,11 @@
 import Link from "next/link";
 
 const demos = [
+  {
+    name: "Conversation Branching",
+    href: "/branching",
+    description: "Edit & regenerate to branch — live tree visualization",
+  },
   {
     name: "Non-Streaming",
     href: "/non-streaming",
diff --git a/examples/experimental/components/branching/BranchTreePanel.tsx b/examples/experimental/components/branching/BranchTreePanel.tsx
new file mode 100644
index 0000000..339092f
--- /dev/null
+++ b/examples/experimental/components/branching/BranchTreePanel.tsx
@@ -0,0 +1,182 @@
+"use client";
+
+import { useCopilot } from "@yourgpt/copilot-sdk/react";
+import { cn } from "@/lib/utils";
+import type { UIMessage } from "@yourgpt/copilot-sdk/react";
+import type { BranchInfo } from "@yourgpt/copilot-sdk";
+
+// ============================================
+// BranchTreePanel
+// ============================================
+
+/**
+ * Live branch tree visualization.
+ *
+ * Renders all messages across all branches (not just the visible path).
+ * Active path nodes are highlighted green; inactive nodes are dimmed.
+ * Clicking any node calls switchBranch() to navigate to that branch.
+ */
+export function BranchTreePanel() {
+  const { messages, getAllMessages, getBranchInfo, switchBranch, hasBranches } =
+    useCopilot();
+
+  const allMessages = getAllMessages();
+  const visibleIds = new Set(messages.map((m) => m.id));
+
+  return (
+    <div className="h-full flex flex-col text-xs">
+      {/* Header */}
+      <div className="px-3 py-2.5 border-b shrink-0">
+        <div className="font-semibold text-sm">Branch Tree</div>
+        <div className="text-muted-foreground mt-0.5 flex items-center gap-1.5 flex-wrap">
+          <span>{allMessages.length} total</span>
+          <span>·</span>
+          <span>{messages.length} visible</span>
+          {hasBranches && (
+            <>
+              <span>·</span>
+              <span className="text-violet-600 dark:text-violet-400 font-medium">
+                branched ✦
+              </span>
+            </>
+          )}
+        </div>
+      </div>
+
+      {/* Tree */}
+      <div className="flex-1 overflow-y-auto p-2 space-y-0.5">
+        {allMessages.length === 0 ? (
+          <p className="text-center text-muted-foreground p-6 leading-relaxed">
+            Send a message to see the tree.
+            <br />
+            <span className="opacity-60">
+              Edit or regenerate to create branches.
+            </span>
+          </p>
+        ) : (
+          <TreeNodes
+            allMessages={allMessages}
+            parentId={null}
+            depth={0}
+            visibleIds={visibleIds}
+            getBranchInfo={getBranchInfo}
+            switchBranch={switchBranch}
+          />
+        )}
+      </div>
+
+      {/* Legend */}
+      <div className="px-3 py-2 border-t shrink-0 text-muted-foreground flex gap-4">
+        <span className="flex items-center gap-1.5">
+          <span className="w-2 h-2 rounded-full bg-green-500 inline-block shrink-0" />
+          active
+        </span>
+        <span className="flex items-center gap-1.5 opacity-50">
+          <span className="w-2 h-2 rounded-full bg-zinc-400 inline-block shrink-0" />
+          inactive
+        </span>
+      </div>
+    </div>
+  );
+}
+
+// ============================================
+// TreeNodes — recursive renderer
+// ============================================
+
+interface TreeNodesProps {
+  allMessages: UIMessage[];
+  parentId: string | null;
+  depth: number;
+  visibleIds: Set<string>;
+  getBranchInfo: (id: string) => BranchInfo | null;
+  switchBranch: (id: string) => void;
+}
+
+function TreeNodes({
+  allMessages,
+  parentId,
+  depth,
+  visibleIds,
+  getBranchInfo,
+  switchBranch,
+}: TreeNodesProps) {
+  const children = allMessages.filter((m) =>
+    parentId === null
+      ? m.parentId === null || m.parentId === undefined
+      : m.parentId === parentId,
+  );
+
+  if (children.length === 0) return null;
+
+  return (
+    <>
+      {children.map((msg) => {
+        const isActive = visibleIds.has(msg.id);
+        const branchInfo = getBranchInfo(msg.id);
+        const content = msg.content ?? "";
+        const preview = content.slice(0, 28);
+        const truncated = content.length > 28;
+
+        return (
+          <div key={msg.id}>
+            <button
+              onClick={() => switchBranch(msg.id)}
+              className={cn(
+                "w-full text-left rounded px-2 py-1 transition-colors font-mono leading-snug",
+                "hover:bg-muted",
+                isActive ? "text-foreground" : "text-muted-foreground opacity-50",
+              )}
+              style={{ paddingLeft: `${8 + depth * 14}px` }}
+              title={content}
+            >
+              {/* Active indicator dot */}
+              <span
+                className={cn(
+                  "inline-block w-1.5 h-1.5 rounded-full mr-1.5 align-middle shrink-0",
+                  isActive ? "bg-green-500" : "bg-zinc-400",
+                )}
+              />
+
+              {/* Role badge */}
+              <span
+                className={cn(
+                  "text-[10px] uppercase font-bold mr-1",
+                  msg.role === "user"
+                    ? "text-blue-500"
+                    : "text-orange-500",
+                  !isActive && "opacity-60",
+                )}
+              >
+                {msg.role === "user" ? "U" : "A"}
+              </span>
+
+              {/* Content preview */}
+              <span className="text-[11px]">
+                {preview || "(empty)"}
+                {truncated ? "…" : ""}
+              </span>
+
+              {/* Sibling count badge */}
+              {branchInfo && (
+                <span className="ml-1 text-[10px] text-violet-500 font-medium">
+                  ×{branchInfo.totalSiblings}
+                </span>
+              )}
+            </button>
+
+            {/* Recurse into this message's children */}
+            <TreeNodes
+              allMessages={allMessages}
+              parentId={msg.id}
+              depth={depth + 1}
+              visibleIds={visibleIds}
+              getBranchInfo={getBranchInfo}
+              switchBranch={switchBranch}
+            />
+          </div>
+        );
+      })}
+    </>
+  );
+}
diff --git a/packages/copilot-sdk/BRANCHING.md b/packages/copilot-sdk/BRANCHING.md
new file mode 100644
index 0000000..282c4a1
--- /dev/null
+++ b/packages/copilot-sdk/BRANCHING.md
@@ -0,0 +1,448 @@
+# Conversation Branching
+
+> Branch `feat/branching` — implements the same UX pattern as ChatGPT, Claude.ai, and Gemini:
+> editing a user message creates a parallel conversation path, preserving the original,
+> with `← N/M →` navigation between variants.
+
+---
+
+## Table of Contents
+
+1. [Live Demo](#live-demo)
+2. [What Was Built](#what-was-built)
+3. [Breaking Changes](#breaking-changes)
+4. [New APIs](#new-apis)
+5. [Database / Persistence Changes](#database--persistence-changes)
+6. [User Adoption](#user-adoption)
+7. [Framework-Agnostic Usage](#framework-agnostic-usage)
+8. [How It Works Internally](#how-it-works-internally)
+
+---
+
+## Live Demo
+
+A full working demo is in the **experimental** examples project.
+
+**Location:** `examples/experimental/`
+**Route:** `/branching`
+
+```bash
+cd examples/experimental
+pnpm dev
+# → http://localhost:3000/branching
+```
+
+### What the demo shows
+
+Two-panel layout inside a single `CopilotProvider`:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  ← Back   Conversation Branching Demo   [feat/branching]    │
+├──────────────────────────┬──────────────────────────────────┤
+│  Branch Tree             │  CopilotChat                    │
+│                          │                                  │
+│  Branch Tree             │  [user: Hello]  ← 1/2 →         │
+│  4 total · 3 visible     │  [assistant: Hi there]          │
+│  branched ✦              │                                  │
+│                          │  [user: Tell me more] ✏         │
+│  ● U Hello               │  [assistant: Sure…]             │
+│  ├── ● A Hi there  ×2   │                                  │
+│  └── · A Hey             │  ────────────────────────────── │
+│      └── ● U Tell me…   │  [input field]                  │
+│          └── ● A Sure…  │                                  │
+└──────────────────────────┴──────────────────────────────────┘
+```
+
+- **Left panel** (`BranchTreePanel`) — reads `getAllMessages()` live. Green dot = on active path, grey = inactive branch. `×N` badge = sibling count. Click any node to call `switchBranch()`.
+- **Right panel** — standard `CopilotChat`. Edit ✏ button appears on hover over user messages. `← N/M →` navigator appears below user messages when variants exist.
+
+### Demo source files
+
+| File | Purpose |
+|------|---------|
+| `examples/experimental/app/branching/page.tsx` | Page: `CopilotProvider` + two-panel layout |
+| `examples/experimental/components/branching/BranchTreePanel.tsx` | Live tree visualization component |
+| `examples/experimental/app/api/chat/branching/route.ts` | Anthropic API route (haiku, short replies) |
+
+### Key code pattern in the demo
+
+```tsx
+// page.tsx — both panels share one CopilotProvider
+<CopilotProvider runtimeUrl="/api/chat/branching">
+  <BranchTreePanel />   {/* reads getAllMessages(), calls switchBranch() */}
+  <CopilotChat ... />   {/* edit button + BranchNavigator built-in */}
+</CopilotProvider>
+
+// BranchTreePanel.tsx — the core hook usage
+const { messages, getAllMessages, getBranchInfo, switchBranch, hasBranches } = useCopilot();
+const allMessages = getAllMessages();          // all branches
+const visibleIds = new Set(messages.map(m => m.id)); // active path
+```
+
+---
+
+## What Was Built
+
+### Core Data Layer
+
+| File | What Changed |
+|------|-------------|
+| `src/chat/branching/MessageTree.ts` | **New.** Pure TypeScript tree utility. Bidirectional flat-map: `parentId` + `childrenIds[]` + `activeChildMap`. No React dependency. |
+| `src/chat/branching/index.ts` | **New.** Barrel export. |
+| `src/chat/types/message.ts` | Added `parentId?: string \| null` and `childrenIds?: string[]` to `UIMessage`. |
+| `src/core/types/message.ts` | Added `parent_id?: string \| null` and `children_ids?: string[]` to `Message` (persistence layer). |
+| `src/chat/interfaces/ChatState.ts` | Added 5 optional branching methods: `setCurrentLeaf`, `getAllMessages`, `getBranchInfo`, `switchBranch`, `hasBranches`. |
+| `src/react/internal/ReactChatState.ts` | Replaced `_messages: T[]` array with `MessageTree<T>`. `messages` getter = visible path only. |
+| `src/chat/classes/AbstractChat.ts` | `regenerate()` rewritten to be branch-aware (creates sibling instead of destroying). `sendMessage()` extended with `options.editMessageId`. `onMessagesChange` callback now passes all branches via `_allMessages()`. |
+| `src/chat/ChatWithTools.ts` | `sendMessage()` passes through `options.editMessageId`. |
+
+### React Layer
+
+| File | What Changed |
+|------|-------------|
+| `src/react/internal/ReactChat.ts` | Added `switchBranch`, `getBranchInfo`, `getAllMessages`, `hasBranches` pass-throughs. |
+| `src/react/internal/ReactChatWithTools.ts` | Same pass-throughs. |
+| `src/react/internal/useChat.ts` | Added `switchBranch`, `getBranchInfo`, `editMessage`, `hasBranches` to `UseChatReturn`. |
+| `src/react/context/CopilotContext.tsx` | Added branching methods to `ChatActions`. |
+| `src/react/provider/CopilotProvider.tsx` | Wired branching methods into context. `onMessagesChange` effect uses `getAllMessages()`. Added `getAllMessages` to `CopilotContextValue`. |
+| `src/react/index.ts` | Re-exports `MessageTree`, `BranchInfo`. |
+| `src/chat/index.ts` | Re-exports `MessageTree`, `BranchInfo`. |
+
+### UI Layer
+
+| File | What Changed |
+|------|-------------|
+| `src/ui/components/ui/branch-navigator.tsx` | **New.** `← N/M →` purely presentational component. |
+| `src/ui/components/composed/chat/types.ts` | Added `getBranchInfo`, `onSwitchBranch`, `onEditMessage` to `ChatProps`. |
+| `src/ui/components/composed/chat/default-message.tsx` | User messages: pencil edit button on hover, inline textarea edit, `BranchNavigator` shown when siblings exist. |
+| `src/ui/components/composed/chat/chat.tsx` | Passes branch props through to each message. |
+| `src/ui/components/composed/connected-chat.tsx` | Pulls `switchBranch`, `getBranchInfo`, `editMessage` from `useCopilot()` and passes to `<Chat />`. |
+| `src/ui/hooks/useInternalThreadManager.ts` | Save path uses `getAllMessages()`. Load paths restore `parentId`/`childrenIds`. `convertToCore` includes `parent_id`/`children_ids`. |
+| `src/ui/index.ts` | Exports `BranchNavigator`, `BranchNavigatorProps`. |
+
+---
+
+## Breaking Changes
+
+**None.**
+
+All new fields and methods are optional. Every existing usage continues to work without modification:
+
+| Scenario | Behavior |
+|----------|----------|
+| Messages with no `parentId` | `getVisibleMessages()` falls back to insertion order (legacy linear) |
+| `regenerate()` called without arguments | Finds last assistant on visible path — identical to before |
+| `sendMessage()` with no third argument | Identical to before |
+| `useChat()` / `useCopilot()` consumers | All branching fields available but optional — no existing destructuring breaks |
+| `onMessagesChange` callback consumers | Now receives all branches instead of visible path only — **payload size may increase** if branches exist, but shape is identical (`Message[]`) |
+| DB rows with no `parent_id` column | Auto-migrated via `fromFlatArray()` on load — no manual migration script needed for existing data |
+
+> **Note on `onMessagesChange` payload:** If a user has branched the conversation, the callback now receives all messages across all branches (not just the active path). The shape is the same `Message[]` type. If your persistence layer deduplicates by message ID, no change is needed. If it blindly appends, you may want to upsert by ID instead.
+
+---
+
+## New APIs
+
+### `useCopilot()` / `CopilotProvider`
+
+```typescript
+const {
+  switchBranch,   // (messageId: string) => void
+  getBranchInfo,  // (messageId: string) => BranchInfo | null
+  editMessage,    // (messageId: string, newContent: string) => Promise<void>
+  hasBranches,    // boolean — true if any fork exists
+  getAllMessages,  // () => UIMessage[] — all branches, not just visible path
+} = useCopilot();
+```
+
+### `useChat()`
+
+```typescript
+const {
+  switchBranch,   // (messageId: string) => void
+  getBranchInfo,  // (messageId: string) => BranchInfo | null
+  editMessage,    // (messageId: string, newContent: string) => Promise<void>
+  hasBranches,    // boolean
+} = useChat({ ... });
+```
+
+### `<Chat />` props
+
+```typescript
+<Chat
+  getBranchInfo={(messageId) => BranchInfo | null}
+  onSwitchBranch={(messageId) => void}
+  onEditMessage={(messageId, newContent) => void}
+/>
+```
+
+### `BranchInfo` type
+
+```typescript
+interface BranchInfo {
+  siblingIndex: number;    // 0-based — which variant this is
+  totalSiblings: number;   // how many variants exist at this fork
+  siblingIds: string[];    // ordered oldest-first
+  hasPrevious: boolean;
+  hasNext: boolean;
+}
+```
+
+### `BranchNavigator` component (UI primitives)
+
+```tsx
+import { BranchNavigator } from '@yourgpt/copilot-sdk-ui';
+
+<BranchNavigator
+  siblingIndex={info.siblingIndex}
+  totalSiblings={info.totalSiblings}
+  hasPrevious={info.hasPrevious}
+  hasNext={info.hasNext}
+  onPrevious={() => switchBranch(info.siblingIds[info.siblingIndex - 1])}
+  onNext={() => switchBranch(info.siblingIds[info.siblingIndex + 1])}
+/>
+```
+
+### `MessageTree` (framework-agnostic)
+
+```typescript
+import { MessageTree, type BranchInfo } from '@yourgpt/copilot-sdk';
+
+const tree = new MessageTree(messages);
+tree.getVisibleMessages();     // active path only
+tree.getAllMessages();          // all branches
+tree.getBranchInfo(messageId); // BranchInfo | null
+tree.switchBranch(messageId);
+tree.hasBranches;              // boolean
+```
+
+---
+
+## Database / Persistence Changes
+
+### New columns needed
+
+Two new optional columns on your messages table:
+
+```sql
+ALTER TABLE messages
+  ADD COLUMN parent_id TEXT REFERENCES messages(id),
+  ADD COLUMN children_ids JSONB DEFAULT '[]';
+```
+
+| Column | Type | Nullable | Description |
+|--------|------|----------|-------------|
+| `parent_id` | `TEXT` / `VARCHAR` | YES | ID of parent message. `NULL` = root. Missing = legacy linear. |
+| `children_ids` | `JSON` array of strings | YES | Ordered child IDs for O(1) sibling lookup. |
+
+> **These columns are optional.** Existing rows without them are auto-migrated to a linear tree on load via `fromFlatArray()`. No data loss. No required migration for existing rows.
+
+### What gets saved now
+
+When `onMessagesChange` fires (or the thread manager auto-saves), the payload contains **all messages across all branches**, not just the visible path. Each message carries:
+
+```json
+{
+  "id": "msg-abc",
+  "role": "assistant",
+  "content": "...",
+  "parent_id": "msg-xyz",
+  "children_ids": []
+}
+```
+
+### What gets loaded
+
+When a thread is loaded (auto-restore or `switchThread`), the SDK maps:
+
+```
+DB row.parent_id     → UIMessage.parentId
+DB row.children_ids  → UIMessage.childrenIds
+```
+
+The `MessageTree` is rebuilt from these fields. The last child at each fork becomes the active path (matches what was active when saved).
+
+### localStorage (built-in persistence)
+
+No changes needed. The SDK's `localStorageAdapter` serializes the full `Thread` object including messages. The new fields are automatically included when present.
+
+### Server persistence (`serverAdapter`)
+
+Your API endpoints that receive `PUT /threads/:id` payloads will now see `parent_id` and `children_ids` on each message object. Store them as-is. If your schema doesn't have these columns yet, the fields are simply ignored — no error.
+
+### Upsert strategy (recommended)
+
+Since branched conversations can have multiple messages with the same `parent_id`, always **upsert by message ID** rather than replacing the array:
+
+```typescript
+// ✅ Safe for branching
+await db.messages.upsert({ id: msg.id, ...msg });
+
+// ⚠️ Loses inactive branches
+await db.threads.update({ messages: visibleMessages });
+```
+
+---
+
+## User Adoption
+
+### Zero-config (CopilotChat users)
+
+If you use `<CopilotChat />`, branching is **already active**. No code changes needed.
+
+- Edit button appears on hover over any user message
+- `← 1/2 →` navigator appears below user messages when variants exist
+- Regenerate creates a branch instead of overwriting
+
+### Manual wiring (`<Chat />` users)
+
+Wire the three props from `useCopilot()`:
+
+```tsx
+function MyChat() {
+  const { switchBranch, getBranchInfo, editMessage } = useCopilot();
+
+  return (
+    <Chat
+      getBranchInfo={getBranchInfo}
+      onSwitchBranch={switchBranch}
+      onEditMessage={editMessage}
+    />
+  );
+}
+```
+
+### Custom message renderers
+
+If you render messages manually, use `getBranchInfo` + `BranchNavigator`:
+
+```tsx
+function MyMessage({ message }) {
+  const { switchBranch, getBranchInfo } = useCopilot();
+  const info = message.role === 'user' ? getBranchInfo(message.id) : null;
+
+  return (
+    <div>
+      <p>{message.content}</p>
+      {info && (
+        <BranchNavigator
+          {...info}
+          onPrevious={() => switchBranch(info.siblingIds[info.siblingIndex - 1])}
+          onNext={() => switchBranch(info.siblingIds[info.siblingIndex + 1])}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+### Programmatic branching
+
+```typescript
+// Edit a message (creates new branch from same parent)
+await editMessage('msg-abc', 'Updated question text');
+
+// Navigate between variants
+switchBranch('msg-xyz');
+
+// Check if branches exist
+if (hasBranches) {
+  const info = getBranchInfo('msg-abc');
+  // info.totalSiblings, info.siblingIndex, etc.
+}
+
+// Persist all branches (not just visible path)
+const allMessages = getAllMessages();
+await saveToServer(allMessages);
+```
+
+---
+
+## Framework-Agnostic Usage
+
+All branching primitives are exported from the core package (no React required):
+
+```typescript
+import { MessageTree, type BranchInfo } from '@yourgpt/copilot-sdk';
+
+// Build a tree from saved messages
+const tree = new MessageTree(savedMessages);
+
+// Get what to send to the AI (active path only)
+const apiMessages = tree.getVisibleMessages();
+
+// Get everything to persist
+const allMessages = tree.getAllMessages();
+
+// Navigate
+tree.switchBranch(messageId);
+const info = tree.getBranchInfo(messageId); // BranchInfo | null
+
+// Migrate legacy flat arrays
+const linked = MessageTree.fromFlatArray(legacyMessages);
+```
+
+---
+
+## How It Works Internally
+
+### Data structure
+
+Each message carries two optional fields:
+
+```
+parentId: string | null | undefined
+  null      = root message (first in conversation)
+  undefined = legacy linear message (pre-branching)
+  string    = ID of parent message
+
+childrenIds: string[]
+  Ordered list of direct child IDs (oldest-first)
+```
+
+The `MessageTree` maintains three maps:
+
+| Map | Key | Value | Purpose |
+|-----|-----|-------|---------|
+| `nodeMap` | messageId | Message | O(1) message lookup |
+| `childrenOf` | parentId (or `__root__`) | `string[]` | All children at a fork |
+| `activeChildMap` | parentId | active child ID | Which branch is currently visible |
+
+### Regenerate flow
+
+```
+Before:  user → assistant-A
+                    ↑ currentLeaf
+
+1. setCurrentLeaf(user.id)   → rewind to user
+2. processRequest()          → AI generates assistant-B
+3. addMessage(assistant-B)   → becomes active child of user
+
+After:   user → assistant-A  (inactive, navigable via ←)
+              ↘ assistant-B  (active)
+```
+
+### Edit flow
+
+```
+Before:  user-A → assistant-A
+
+1. sendMessage("new text", { editMessageId: "user-A" })
+2. newParentId = user-A.parentId (= null, root)
+3. setCurrentLeaf(null)          → rewind to before user-A
+4. create user-B with parentId=null
+5. processRequest()              → AI generates assistant-B
+
+After:  user-A → assistant-A  (inactive)
+        user-B → assistant-B  (active)
+```
+
+### Visible path vs all messages
+
+```
+getAllMessages()       → every message across every branch (for persistence)
+getVisibleMessages()  → root → currentLeaf along activeChildMap (for UI + API)
+```
+
+The API always receives `getVisibleMessages()`. Inactive branches are never sent to the model.
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 98c13a4..384114f 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -225,7 +225,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       this.state.error = undefined;
 
       // Notify callbacks
-      this.callbacks.onMessagesChange?.(this.state.messages);
+      this.callbacks.onMessagesChange?.(this._allMessages());
       this.callbacks.onStatusChange?.("submitted");
 
       // Yield to allow UI to render loading state (important for non-streaming)
@@ -291,7 +291,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         this.state.pushMessage(toolMessage);
       }
 
-      this.callbacks.onMessagesChange?.(this.state.messages);
+      this.callbacks.onMessagesChange?.(this._allMessages());
     }
   }
 
@@ -372,7 +372,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       }
 
       this.state.status = "submitted";
-      this.callbacks.onMessagesChange?.(this.state.messages);
+      this.callbacks.onMessagesChange?.(this._allMessages());
       this.callbacks.onStatusChange?.("submitted");
 
       // Yield a full macrotask so React can flush the "submitted" status
@@ -429,6 +429,12 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
 
     if (messageId) {
       targetMessage = messages.find((m) => m.id === messageId);
+      // Not on visible path — check inactive branches too
+      if (!targetMessage) {
+        targetMessage = this.state.getAllMessages?.().find(
+          (m) => m.id === messageId,
+        );
+      }
     } else {
       // Find last assistant message in the visible path
       for (let i = messages.length - 1; i >= 0; i--) {
@@ -446,7 +452,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       // Rewind active path to target's parent
       // The new assistant response will be pushed as a new child (sibling)
       this.state.setCurrentLeaf(targetMessage.parentId ?? null);
-      this.callbacks.onMessagesChange?.(this.state.messages);
+      this.callbacks.onMessagesChange?.(this._allMessages());
       this.state.status = "submitted";
       await Promise.resolve();
       await this.processRequest();
@@ -457,7 +463,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     const targetIndex = messages.indexOf(targetMessage);
     if (targetIndex > 0) {
       this.state.setMessages(messages.slice(0, targetIndex));
-      this.callbacks.onMessagesChange?.(this.state.messages);
+      this.callbacks.onMessagesChange?.(this._allMessages());
       await this.processRequest();
     }
   }
@@ -466,6 +472,15 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
   // Event Handling
   // ============================================
 
+  /**
+   * 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(): T[] {
+    return this.state.getAllMessages?.() ?? this.state.messages;
+  }
+
   /**
    * Subscribe to events
    */
@@ -518,7 +533,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     if (this.config.streaming !== false) {
       const preMsg = createEmptyAssistantMessage() as T;
       this.state.pushMessage(preMsg);
-      this.callbacks.onMessagesChange?.(this.state.messages);
+      this.callbacks.onMessagesChange?.(this._allMessages());
       preCreatedMessageId = preMsg.id;
     }
 
@@ -1177,7 +1192,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       }
     }
 
-    this.callbacks.onMessagesChange?.(this.state.messages);
+    this.callbacks.onMessagesChange?.(this._allMessages());
 
     // Close the stream group opened at the start of handleStreamResponse
     this.debugGroupEnd();
@@ -1249,7 +1264,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       this.state.pushMessage(message);
     }
 
-    this.callbacks.onMessagesChange?.(this.state.messages);
+    this.callbacks.onMessagesChange?.(this._allMessages());
 
     // Check for tool calls BEFORE setting status to ready
     // If tool calls exist, the async handler will manage status

From c0231cefa02a021b800bc2f208b4d9c3560bd815 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 14 Mar 2026 21:29:03 +0530
Subject: [PATCH 17/72] feat(sdk): add context management and skills system
 documentation

- Introduced comprehensive documentation for the new context management features, detailing dual-layer message storage, message history compaction strategies, and token counting.
- Added a skills system section explaining the use of skills as instruction playbooks, including client-side and server-side implementations, skill file formats, and the `defineSkill` helper.
- Enhanced the overall structure and clarity of the documentation to facilitate better understanding and usage of the SDK's capabilities.
---
 packages/copilot-sdk/CONTEXT-MANAGEMENT.md | 733 +++++++++++++++++++++
 packages/copilot-sdk/SKILLS.md             | 518 +++++++++++++++
 2 files changed, 1251 insertions(+)
 create mode 100644 packages/copilot-sdk/CONTEXT-MANAGEMENT.md
 create mode 100644 packages/copilot-sdk/SKILLS.md

diff --git a/packages/copilot-sdk/CONTEXT-MANAGEMENT.md b/packages/copilot-sdk/CONTEXT-MANAGEMENT.md
new file mode 100644
index 0000000..78bb8a4
--- /dev/null
+++ b/packages/copilot-sdk/CONTEXT-MANAGEMENT.md
@@ -0,0 +1,733 @@
+# Context Management
+
+Advanced context window management for the YourGPT Copilot SDK. These features give you full control over what the AI sees, how long conversations stay alive, and how tokens are tracked and budgeted.
+
+---
+
+## Table of Contents
+
+1. [Dual-Layer Message Store](#1-dual-layer-message-store)
+2. [Message History & Compaction](#2-message-history--compaction)
+   - [Compaction Strategies](#compaction-strategies)
+   - [Config Reference](#config-reference)
+3. [Token Counting](#3-token-counting)
+4. [Session Persistence](#4-session-persistence)
+5. [useContextStats](#5-usecontextstats)
+6. [AgentLoop API](#6-agentloop-api)
+7. [Tools — useTool / useTools / ToolDefinition](#7-tools--usetool--usetools--tooldefinition)
+   - [Deferred Tools](#deferred-tools)
+   - [Hidden Tools](#hidden-tools)
+   - [Fallback Tool Renderer](#fallback-tool-renderer)
+8. [Message Grouping](#8-message-grouping)
+9. [Server: compactSession](#9-server-compactsession)
+
+---
+
+## 1. Dual-Layer Message Store
+
+Every conversation maintains two parallel views of the message history.
+
+| Layer                 | Type               | Purpose                                                                           |
+| --------------------- | ------------------ | --------------------------------------------------------------------------------- |
+| **Display layer**     | `DisplayMessage[]` | Full immutable history. Rendered in the UI. Never shrinks.                        |
+| **LLM context layer** | `LLMMessage[]`     | Compacted/pruned form sent to the model on each request. Rebuilt on every render. |
+
+### Types
+
+```typescript
+// Display layer — extends UIMessage for full backward-compat
+interface DisplayMessage extends UIMessage {
+  timestamp: number; // Unix ms
+}
+
+// Injected into displayMessages when compaction fires
+interface CompactionMarker extends DisplayMessage {
+  role: "system";
+  type: "compaction-marker";
+  content: string; // Human-readable summary
+  summarizedMessageIds: string[];
+  tokensSaved: number;
+}
+
+// LLM context layer — what the model actually sees
+interface LLMMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  tool_calls?: ToolCall[];
+  tool_call_id?: string;
+}
+
+// Replaces a full tool result when old enough to prune
+interface CompactedToolResult {
+  type: "compacted-tool-result";
+  toolName: string;
+  toolCallId: string;
+  args: Record<string, unknown>;
+  executedAt: number;
+  status: "success" | "error";
+  originalSize: number;
+  summary: string;
+  extract?: string; // First 200 chars if no LLM summary
+}
+```
+
+### Conversion helpers
+
+```typescript
+import {
+  toDisplayMessage,
+  toLLMMessage,
+  toLLMMessages,
+  keepToolPairsAtomic,
+} from "@yourgpt/copilot-sdk-react";
+```
+
+`keepToolPairsAtomic` ensures that when you slice a window, an `assistant` message with `tool_calls` is never separated from its corresponding tool-result messages.
+
+---
+
+## 2. Message History & Compaction
+
+### useMessageHistory
+
+```typescript
+import { useMessageHistory } from "@yourgpt/copilot-sdk-react";
+
+function MyChat() {
+  const {
+    displayMessages, // Full UI history
+    llmMessages, // Compacted LLM context
+    tokenUsage, // Live token estimate
+    isCompacting, // true while auto-compaction runs
+    compactionState, // Metadata & rolling summary
+    compactSession, // Manual trigger
+    addToWorkingMemory,
+    clearWorkingMemory,
+    resetSession,
+  } = useMessageHistory({
+    strategy: "summary-buffer",
+    maxContextTokens: 128000,
+    compactionThreshold: 0.75,
+    compactionUrl: "/api/compact",
+    persistSession: true,
+  });
+}
+```
+
+#### Return type
+
+```typescript
+interface UseMessageHistoryReturn {
+  displayMessages: DisplayMessage[];
+  llmMessages: LLMMessage[];
+  tokenUsage: TokenUsage;
+  isCompacting: boolean;
+  compactionState: SessionCompactionState;
+  compactSession: (instructions?: string) => Promise<void>;
+  addToWorkingMemory: (fact: string) => void;
+  clearWorkingMemory: () => void;
+  resetSession: () => void;
+}
+```
+
+### Compaction Strategies
+
+Four strategies are available via the `strategy` config field.
+
+#### `"none"` (default)
+
+No compaction. Zero-config, 100% backward-compatible. All messages sent verbatim.
+
+```typescript
+useMessageHistory({ strategy: "none" });
+```
+
+#### `"sliding-window"`
+
+Keeps only the most recent N tokens of history. Oldest messages are dropped when the token budget is exceeded.
+
+```typescript
+useMessageHistory({
+  strategy: "sliding-window",
+  maxContextTokens: 128000,
+  reserveForResponse: 4096,
+  recentBuffer: 10, // Always keep at least 10 recent messages
+  toolResultMaxChars: 10000, // Truncate large tool results
+});
+```
+
+#### `"selective-prune"`
+
+Removes tool-result messages that are older than `recentBuffer`, keeping the conversation skeleton (user/assistant turns) intact. Lighter than sliding-window — no token counting required.
+
+```typescript
+useMessageHistory({
+  strategy: "selective-prune",
+  recentBuffer: 10,
+});
+```
+
+#### `"summary-buffer"`
+
+Summarizes old messages into a rolling summary when usage exceeds `compactionThreshold`. The summary is injected into the LLM context as a system message. Requires a `/api/compact` endpoint (or custom `summarizer`).
+
+```typescript
+useMessageHistory({
+  strategy: "summary-buffer",
+  compactionThreshold: 0.75, // Compact at 75% of maxContextTokens
+  compactionUrl: "/api/compact",
+  recentBuffer: 10,
+  onCompaction: (event) => {
+    console.log(
+      `Compacted ${event.messagesSummarized} messages, saved ~${event.tokensSaved} tokens`,
+    );
+  },
+});
+```
+
+Custom summarizer (skip the HTTP round-trip):
+
+```typescript
+useMessageHistory({
+  strategy: "summary-buffer",
+  summarizer: async (messages) => {
+    const res = await myLLM.summarize(messages);
+    return res.text;
+  },
+});
+```
+
+### Config Reference
+
+```typescript
+interface MessageHistoryConfig {
+  strategy?: "none" | "sliding-window" | "summary-buffer" | "selective-prune";
+  maxContextTokens?: number; // default: 128000
+  reserveForResponse?: number; // default: 4096
+  compactionThreshold?: number; // default: 0.75
+  recentBuffer?: number; // default: 10
+  toolResultMaxChars?: number; // default: 10000 (0 = no cap)
+  compactionUrl?: string; // required for summary-buffer
+  persistSession?: boolean; // default: false
+  storageKey?: string; // default: "copilot-session"
+  onCompaction?: (event: CompactionEvent) => void;
+  onTokenUsage?: (usage: TokenUsage) => void;
+}
+```
+
+#### Per-call options
+
+```typescript
+interface UseMessageHistoryOptions extends MessageHistoryConfig {
+  skipCompaction?: boolean;
+  tokenEstimation?: "fast" | "accurate" | "off"; // default: "fast"
+  summarizer?: (messages: LLMMessage[]) => Promise<string>;
+}
+```
+
+### Provider-level config
+
+Set defaults once in `<CopilotProvider>` instead of each `useMessageHistory` call:
+
+```tsx
+<CopilotProvider
+  messageHistory={{
+    strategy: "summary-buffer",
+    maxContextTokens: 128000,
+    compactionUrl: "/api/compact",
+    persistSession: true,
+  }}
+>
+  <App />
+</CopilotProvider>
+```
+
+### Working Memory
+
+Pin facts that survive all future compactions:
+
+```typescript
+const { addToWorkingMemory, clearWorkingMemory } = useMessageHistory({ ... });
+
+// Survives compaction
+addToWorkingMemory("User is on the Pro plan. Account ID: acct_123");
+
+// Remove all pinned facts
+clearWorkingMemory();
+```
+
+### Compaction event & token usage types
+
+```typescript
+interface CompactionEvent {
+  type: "auto" | "manual";
+  compactionCount: number;
+  messagesSummarized: number;
+  tokensSaved: number;
+  timestamp: number;
+}
+
+interface TokenUsage {
+  current: number; // Estimated tokens in LLM context
+  max: number; // maxContextTokens
+  percentage: number; // current / max (0–1)
+  isApproaching: boolean; // percentage >= compactionThreshold
+}
+
+interface SessionCompactionState {
+  rollingSummary: string | null;
+  lastCompactionAt: number | null;
+  compactionCount: number;
+  totalTokensSaved: number;
+  workingMemory: string[];
+  displayMessageCount: number;
+  llmMessageCount: number;
+}
+```
+
+---
+
+## 3. Token Counting
+
+Two-tier estimation — pick the right trade-off between speed and accuracy.
+
+### Tier 1: Fast (zero dependencies)
+
+Uses a `chars / 3.5` heuristic. ~85–90% accurate for English. Always available, no bundle cost.
+
+```typescript
+import {
+  estimateTokensFast,
+  estimateMessageTokens,
+  estimateMessagesTokens,
+} from "@yourgpt/copilot-sdk-react";
+
+const tokens = estimateTokensFast("Hello world"); // fast, synchronous
+const msgTokens = estimateMessagesTokens(llmMessages);
+```
+
+### Tier 2: Accurate (lazy-loaded)
+
+Uses `gpt-tokenizer` with the `o200k_base` encoding. Lazy-loaded only when called — no upfront bundle cost. Falls back to Tier 1 if `gpt-tokenizer` is not installed.
+
+```typescript
+import {
+  countTokensAccurate,
+  countMessagesTokensAccurate,
+} from "@yourgpt/copilot-sdk-react";
+
+// Only loads gpt-tokenizer on first call
+const tokens = await countTokensAccurate("Hello world");
+const msgTokens = await countMessagesTokensAccurate(llmMessages);
+```
+
+### Dispatcher
+
+```typescript
+import { estimateTokens } from "@yourgpt/copilot-sdk-react";
+import type { TokenEstimationMode } from "@yourgpt/copilot-sdk-react";
+
+// mode: "fast" | "accurate" | "off"
+const tokens = estimateTokens(llmMessages, "fast");
+```
+
+Set via `tokenEstimation` in `useMessageHistory`:
+
+```typescript
+useMessageHistory({ tokenEstimation: "accurate" });
+```
+
+---
+
+## 4. Session Persistence
+
+Survive page reloads with zero extra code.
+
+```typescript
+useMessageHistory({
+  persistSession: true,
+  storageKey: "my-app-chat", // default: "copilot-session"
+});
+```
+
+| What is persisted                  | Where                                                      |
+| ---------------------------------- | ---------------------------------------------------------- |
+| `compactionState` (small metadata) | `localStorage` — sync, available immediately on cold start |
+| `displayMessages` (can be large)   | `IndexedDB` — async, avoids localStorage quota issues      |
+
+Both are keyed by `storageKey`. Multiple chat instances can coexist with different keys.
+
+Clear everything (including storage) with:
+
+```typescript
+const { resetSession } = useMessageHistory({ persistSession: true });
+await resetSession();
+```
+
+---
+
+## 5. useContextStats
+
+Live snapshot of context window usage. Updates reactively on every message send.
+
+```typescript
+import { useContextStats } from "@yourgpt/copilot-sdk-react";
+
+function ContextMonitor() {
+  const {
+    contextUsage,        // Full breakdown by bucket (richest field)
+    totalTokens,         // Convenience: total estimated tokens
+    usagePercent,        // Convenience: window fill 0–1
+    contextChars,        // Characters contributed by AI context injections
+    toolCount,           // Number of currently registered tools
+    messageCount,        // Visible (non-system) messages
+    lastResponseUsage,   // Token usage from last assistant message
+  } = useContextStats();
+
+  // Breakdown by bucket
+  const historyTokens = contextUsage?.breakdown.history.tokens;
+  const systemPercent = contextUsage?.breakdown.systemPrompt.percent;
+
+  return (
+    <div>
+      <p>{Math.round(usagePercent * 100)}% of context used</p>
+      <p>{totalTokens} tokens / {toolCount} tools</p>
+      {lastResponseUsage && (
+        <p>Last turn: {lastResponseUsage.total_tokens} tokens</p>
+      )}
+    </div>
+  );
+}
+```
+
+### Return type
+
+```typescript
+interface ContextStats {
+  contextUsage: ContextUsage | null; // null until first message
+  totalTokens: number;
+  usagePercent: number; // 0 until first message
+  contextChars: number;
+  toolCount: number;
+  messageCount: number;
+  lastResponseUsage: MessageTokenUsage | null;
+}
+
+interface MessageTokenUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+}
+```
+
+---
+
+## 6. AgentLoop API
+
+`AbstractAgentLoop` is the framework-agnostic core that manages the tool execution loop, approvals, and cancellation.
+
+```typescript
+import { AbstractAgentLoop } from "@yourgpt/copilot-sdk";
+
+const loop = new AbstractAgentLoop(
+  {
+    maxIterations: 20,
+    tools: [myTool],
+  },
+  {
+    onToolExecutionsChange: (executions) => setExecutions(executions),
+    onToolApprovalRequired: (execution) => showApprovalModal(execution),
+  },
+);
+
+// Register/unregister tools at runtime
+loop.registerTool(weatherTool);
+loop.unregisterTool("old_tool");
+
+// Execute tool calls returned by the LLM
+const results = await loop.executeToolCalls(toolCallsFromLLM);
+
+// Cancel in-flight execution
+loop.cancel();
+```
+
+### Config
+
+```typescript
+interface AgentLoopConfig {
+  maxIterations?: number; // default: 20
+  maxExecutionHistory?: number; // default: 100
+  tools?: ToolDefinition[];
+}
+```
+
+Tools use reference counting so React StrictMode double-invocations don't leave orphaned registrations.
+
+---
+
+## 7. Tools — useTool / useTools / ToolDefinition
+
+### useTool
+
+Register a single client-side tool from a React component. Accepts both Zod schemas and JSON Schema.
+
+```typescript
+import { useTool } from "@yourgpt/copilot-sdk-react";
+import { z } from "zod";
+
+function MyComponent() {
+  useTool({
+    name: "navigate_to_page",
+    description: "Navigate to a page in the app",
+    inputSchema: z.object({
+      path: z.string().describe("Route path to navigate to"),
+    }),
+    handler: async ({ path }) => {
+      router.push(path);
+      return { success: true };
+    },
+    // Optional UI rendering
+    render: ({ args, result }) => <NavigationCard path={args.path} />,
+  });
+}
+```
+
+### useTools (ToolSet pattern)
+
+Register multiple tools at once using the Vercel AI SDK `ToolSet` pattern:
+
+```typescript
+import { useTools, tool } from "@yourgpt/copilot-sdk-react";
+
+function MyApp() {
+  useTools({
+    get_weather: tool({
+      description: "Get weather for a location",
+      inputSchema: {
+        type: "object",
+        properties: { location: { type: "string" } },
+        required: ["location"],
+      },
+      handler: async ({ location }) => fetchWeather(location),
+    }),
+    open_modal: tool({
+      description: "Open a UI modal",
+      inputSchema: z.object({ id: z.string() }),
+      handler: async ({ id }) => {
+        openModal(id);
+        return { success: true };
+      },
+    }),
+  });
+}
+```
+
+### UseToolConfig reference
+
+```typescript
+interface UseToolConfig<TParams> {
+  name: string;
+  description: string;
+  inputSchema: ZodSchema | JSONSchema; // Both accepted
+  handler: (
+    params: TParams,
+    context?: ToolContext,
+  ) => Promise<ToolResponse> | ToolResponse;
+
+  // UI
+  render?: (props: ToolRenderProps<TParams>) => React.ReactNode;
+  title?: string | ((args: TParams) => string);
+  executingTitle?: string | ((args: TParams) => string);
+  completedTitle?: string | ((args: TParams) => string);
+
+  // Behaviour
+  available?: boolean; // default: true
+  needsApproval?: boolean;
+  approvalMessage?: string | ((params: TParams) => string);
+  hidden?: boolean; // default: false — see Hidden Tools
+  aiResponseMode?: AIResponseMode;
+  aiContext?: string | ((result, args) => string);
+  resultConfig?: ToolResultConfig;
+
+  // Loading strategy
+  deferLoading?: boolean; // see Deferred Tools
+  profiles?: string[];
+  searchKeywords?: string[];
+  group?: string;
+  category?: string;
+}
+```
+
+### Deferred Tools
+
+Large tool registries can bloat the LLM request payload. Mark tools with `deferLoading: true` to keep them out of the default request — they are auto-detected and injected only when the user's query semantically matches the tool.
+
+```typescript
+useTool({
+  name: "run_sql_query",
+  description: "Execute a SQL query against the database",
+  deferLoading: true, // Not sent on every request
+  searchKeywords: ["sql", "query", "database", "table"],
+  inputSchema: z.object({ query: z.string() }),
+  handler: async ({ query }) => db.execute(query),
+});
+```
+
+Auto-detection uses `description` + `searchKeywords` to score relevance against the current message. No configuration required.
+
+### Hidden Tools
+
+Register tools that execute silently — they run when called by the AI but are never shown in the tool execution UI.
+
+```typescript
+useTool({
+  name: "log_analytics_event",
+  description: "Log a UI analytics event",
+  hidden: true, // Never rendered in chat UI
+  inputSchema: z.object({ event: z.string(), data: z.record(z.unknown()) }),
+  handler: async ({ event, data }) => {
+    analytics.track(event, data);
+    return {};
+  },
+});
+```
+
+### Fallback Tool Renderer
+
+The `<CopilotChat>` component resolves a renderer for each tool execution using this priority chain:
+
+1. **`toolRenderers[toolName]`** — per-tool renderer map passed to `<CopilotChat>`
+2. **`tool.render`** — render function attached to the `ToolDefinition` via `useTool`
+3. **`mcpToolRenderer`** — catch-all for tools with `source: "mcp"`
+4. **`fallbackToolRenderer`** — catch-all for any tool not matched above
+5. **Built-in default** — generic tool execution card
+
+```tsx
+<CopilotChat
+  // Highest priority — per-tool
+  toolRenderers={{
+    get_weather: ({ args, result }) => <WeatherCard {...result} />,
+  }}
+  // MCP catch-all
+  mcpToolRenderer={({ toolName, args, result }) => <MCPCard name={toolName} />}
+  // Universal catch-all
+  fallbackToolRenderer={({ toolName, args, result }) => (
+    <pre>{JSON.stringify(result, null, 2)}</pre>
+  )}
+/>
+```
+
+---
+
+## 8. Message Grouping
+
+`groupConsecutiveMessages` groups consecutive messages of the same role into visual clusters. Useful for building custom chat UIs where adjacent user or assistant messages should appear as one block.
+
+Available from the message-utils module:
+
+```typescript
+import {
+  toLLMMessages,
+  toLLMMessage,
+  keepToolPairsAtomic,
+} from "@yourgpt/copilot-sdk-react";
+```
+
+Core invariant: **tool-call pairs are always atomic.** An assistant message with `tool_calls` is never separated from its corresponding tool-result messages during any windowing or pruning operation.
+
+---
+
+## 9. Server: compactSession
+
+The `compactSession` utility powers the `/api/compact` endpoint for `summary-buffer` compaction. It calls Claude (defaults to `claude-haiku-4-5`) to produce a structured summary that preserves:
+
+- User goals and requests
+- Technical decisions and chosen approaches
+- Tool call outcomes (name, key args, result status)
+- Errors and resolutions
+- Pending tasks and current work state
+
+```typescript
+// app/api/compact/route.ts
+import { compactSession } from "@yourgpt/copilot-sdk/server";
+
+export async function POST(req: Request) {
+  const { messages, existingSummary, workingMemory } = await req.json();
+
+  const { summary } = await compactSession({
+    messages,
+    existingSummary, // Passed in subsequent compactions for rolling summaries
+    workingMemory, // User-pinned facts (addToWorkingMemory)
+    model: "claude-haiku-4-5", // default
+    maxSummaryTokens: 1024, // default
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  });
+
+  return Response.json({ summary });
+}
+```
+
+### CompactSessionOptions
+
+```typescript
+interface CompactSessionOptions {
+  messages: Array<{ role: string; content?: string | null }>;
+  existingSummary?: string | null;
+  workingMemory?: string[];
+  model?: string; // default: "claude-haiku-4-5"
+  maxSummaryTokens?: number; // default: 1024
+  apiKey?: string; // fallback: process.env.ANTHROPIC_API_KEY
+  apiBaseUrl?: string; // default: "https://api.anthropic.com"
+  fetchImpl?: typeof fetch;
+}
+```
+
+---
+
+## Quick-start: Full Setup
+
+```tsx
+// app/layout.tsx
+import { CopilotProvider } from "@yourgpt/copilot-sdk-react";
+
+export default function RootLayout({ children }) {
+  return (
+    <CopilotProvider
+      widgetToken="YOUR_TOKEN"
+      messageHistory={{
+        strategy: "summary-buffer",
+        maxContextTokens: 128000,
+        compactionThreshold: 0.75,
+        compactionUrl: "/api/compact",
+        persistSession: true,
+        storageKey: "my-app",
+        onCompaction: (e) => console.log("Compacted:", e),
+      }}
+    >
+      {children}
+    </CopilotProvider>
+  );
+}
+```
+
+```tsx
+// components/ChatPanel.tsx
+import { useMessageHistory, useContextStats } from "@yourgpt/copilot-sdk-react";
+
+export function ChatPanel() {
+  const { tokenUsage, isCompacting, compactSession } = useMessageHistory();
+  const { usagePercent, toolCount } = useContextStats();
+
+  return (
+    <div>
+      <p>
+        {Math.round(usagePercent * 100)}% context used · {toolCount} tools
+      </p>
+      {tokenUsage.isApproaching && (
+        <button onClick={() => compactSession()}>Compact now</button>
+      )}
+      {isCompacting && <span>Summarizing history…</span>}
+    </div>
+  );
+}
+```
diff --git a/packages/copilot-sdk/SKILLS.md b/packages/copilot-sdk/SKILLS.md
new file mode 100644
index 0000000..d2e02aa
--- /dev/null
+++ b/packages/copilot-sdk/SKILLS.md
@@ -0,0 +1,518 @@
+# Skills System
+
+Skills are instruction playbooks the AI loads on demand. They shape the model's **behavior** — separate from Tools, which perform actions.
+
+A skill is a Markdown file (or inline string) containing instructions. Skills can be:
+
+- **eager** — always injected into the system prompt
+- **auto** — listed in a catalog; the AI calls `load_skill` to retrieve them when relevant
+- **manual** — available via `load_skill` but not advertised in the catalog
+
+---
+
+## Table of Contents
+
+1. [Concepts](#1-concepts)
+2. [Client-side: SkillProvider + useSkill](#2-client-side-skillprovider--useskill)
+3. [Server-side: loadSkills](#3-server-side-loadskills)
+4. [Skill File Format](#4-skill-file-format)
+5. [defineSkill helper](#5-defineskill-helper)
+6. [useSkillStatus](#6-useskillstatus)
+7. [Source precedence & collision detection](#7-source-precedence--collision-detection)
+8. [Type Reference](#8-type-reference)
+9. [Full Example](#9-full-example)
+
+---
+
+## 1. Concepts
+
+| Strategy | Behavior                                                                                            |
+| -------- | --------------------------------------------------------------------------------------------------- |
+| `eager`  | Content prepended to system prompt on every request. Always active.                                 |
+| `auto`   | Listed in the skill catalog appended to the system prompt. AI calls `load_skill({ name })` to load. |
+| `manual` | Accessible via `load_skill` but not advertised — for internal/conditional skills.                   |
+
+The `load_skill` tool is automatically registered when a `<SkillProvider>` is present (client) or when `loadSkills()` builds the tools object (server). No manual wiring required.
+
+---
+
+## 2. Client-side: SkillProvider + useSkill
+
+### SkillProvider
+
+Wrap your app (inside `<CopilotProvider>`) to enable client-side skills:
+
+```tsx
+import { SkillProvider, defineSkill } from "@yourgpt/copilot-sdk-react";
+
+const brandVoice = defineSkill({
+  name: "brand-voice",
+  description: "Ensures responses match our brand tone and terminology",
+  strategy: "eager",
+  source: {
+    type: "inline",
+    content:
+      "Always respond in a friendly, concise tone. Use 'we' not 'I'. Avoid jargon.",
+  },
+});
+
+const codeReview = defineSkill({
+  name: "code-review",
+  description: "Performs structured code reviews with actionable feedback",
+  strategy: "auto", // AI loads this on demand
+  source: {
+    type: "inline",
+    content: "When reviewing code: 1) Check for bugs first...",
+  },
+});
+
+export default function App() {
+  return (
+    <CopilotProvider widgetToken="...">
+      <SkillProvider skills={[brandVoice, codeReview]}>
+        <YourApp />
+      </SkillProvider>
+    </CopilotProvider>
+  );
+}
+```
+
+> **Note:** `<SkillProvider>` only supports `inline` source skills client-side. For `file` or `url` sources, use `loadSkills()` on the server.
+
+### useSkill
+
+Register a skill from deep inside the component tree — it activates on mount and cleans up on unmount.
+
+```tsx
+import { useSkill } from "@yourgpt/copilot-sdk-react";
+
+function CheckoutPage() {
+  useSkill({
+    name: "checkout-flow",
+    description: "Guides the user through the checkout process step by step",
+    strategy: "auto",
+    source: {
+      type: "inline",
+      content: `
+## Checkout Assistant
+
+When the user asks about checkout:
+1. Confirm their cart items
+2. Check for applicable promo codes
+3. Walk through shipping options
+4. Confirm payment method before submitting
+      `,
+    },
+  });
+
+  return <CheckoutUI />;
+}
+```
+
+The skill is automatically unregistered when `CheckoutPage` unmounts.
+
+**Dev warning:** If an inline skill exceeds 2000 characters in development, a console warning is shown. Large inline skills are sent on every request — consider using a server-side file skill instead.
+
+---
+
+## 3. Server-side: loadSkills
+
+For `file` and `url` sources, or when you want server-controlled skill loading:
+
+```typescript
+// app/api/chat/route.ts
+import path from "path";
+import { loadSkills } from "@yourgpt/copilot-sdk/server";
+
+export async function POST(req: Request) {
+  const { messages, __skills } = await req.json();
+
+  const { skills, buildSystemPrompt, tools, diagnostics } = await loadSkills({
+    // Source 1: .md files from a local directory (highest precedence)
+    dir: path.join(process.cwd(), "skills"),
+
+    // Source 2: Remote .md URLs
+    remoteUrls: ["https://cdn.myapp.com/skills/support-policy.md"],
+
+    // Source 3: Inline skills forwarded from client (lowest precedence)
+    clientSkills: __skills ?? [],
+  });
+
+  // Log any name collisions
+  if (diagnostics.length) {
+    console.warn("Skill collisions:", diagnostics);
+  }
+
+  const systemPrompt = buildSystemPrompt(
+    "You are a helpful assistant for Acme Corp.",
+  );
+
+  // Pass tools.load_skill to your AI provider
+  return streamText({
+    model: anthropic("claude-sonnet-4-6"),
+    system: systemPrompt,
+    messages,
+    tools: {
+      ...tools, // includes load_skill
+      ...myOtherTools,
+    },
+  });
+}
+```
+
+### loadSkills options
+
+```typescript
+interface LoadSkillsOptions {
+  dir?: string; // Path to /skills directory (Node.js only)
+  remoteUrls?: string[]; // Remote .md URLs to fetch
+  clientSkills?: ClientInlineSkill[]; // Forwarded from useSkill() hooks
+}
+```
+
+### loadSkills result
+
+```typescript
+interface LoadSkillsResult {
+  skills: ResolvedSkill[];
+  diagnostics: SkillDiagnostic[];
+
+  // Build system prompt: prepends eager content, appends auto catalog
+  buildSystemPrompt(basePrompt?: string): string;
+
+  // Ready-to-use load_skill tool definition
+  tools: {
+    load_skill: {
+      description: string;
+      parameters: { ... };
+      execute: (args: { name: string }) => Promise<LoadSkillResult | LoadSkillError>;
+    };
+  };
+}
+```
+
+### Forwarding client skills to the server
+
+`<SkillProvider>` automatically syncs inline skills to `CopilotProvider`, which includes them in every API request as `__skills`. Read them in your route handler:
+
+```typescript
+const { messages, __skills } = await req.json();
+
+const { buildSystemPrompt, tools } = await loadSkills({
+  dir: path.join(process.cwd(), "skills"),
+  clientSkills: __skills ?? [], // Inline skills from useSkill() hooks
+});
+```
+
+---
+
+## 4. Skill File Format
+
+Skill files are Markdown with an optional YAML frontmatter block.
+
+```markdown
+---
+name: code-review
+description: Performs structured code reviews with actionable feedback
+strategy: auto
+version: 1.2.0
+---
+
+## Code Review Instructions
+
+When asked to review code, follow this structure:
+
+1. **Correctness** — Check for logic errors and edge cases
+2. **Security** — Flag injection risks, exposed secrets, insecure defaults
+3. **Performance** — Note O(n²) loops, unnecessary re-renders, missing indexes
+4. **Style** — Suggest naming and structure improvements (non-blocking)
+
+Always include a summary section with an overall assessment.
+```
+
+### Frontmatter fields
+
+| Field         | Required    | Description                                                                           |
+| ------------- | ----------- | ------------------------------------------------------------------------------------- |
+| `name`        | Recommended | Skill name. Derived from filename if omitted (e.g. `code-review.md` → `code-review`). |
+| `description` | Recommended | One-line description shown in the AI's skill catalog.                                 |
+| `strategy`    | No          | `eager`, `auto`, or `manual`. Default: `auto`.                                        |
+| `version`     | No          | Informational version string.                                                         |
+
+### Directory layout
+
+```
+skills/
+├── brand-voice.md          # Flat .md file
+├── code-review.md
+└── sql-expert/
+    └── SKILL.md            # Folder-based skill (use for multi-file skills)
+```
+
+For folder-based skills, place the main skill file at `<folder>/SKILL.md`. The folder name is used as the skill name unless overridden by frontmatter.
+
+---
+
+## 5. defineSkill helper
+
+Type-safe factory for creating skill definitions. An identity function with TypeScript inference — same pattern as `useTool`.
+
+```typescript
+import { defineSkill } from "@yourgpt/copilot-sdk-react";
+// or from server:
+import { defineSkill } from "@yourgpt/copilot-sdk/server";
+
+const mySkill = defineSkill({
+  name: "api-docs-helper",
+  description: "Helps users understand and use the Acme API",
+  strategy: "auto",
+  version: "2.0.0",
+  source: {
+    type: "inline",
+    content: "When explaining API endpoints, always include example requests...",
+  },
+});
+
+// Reuse in multiple providers
+<SkillProvider skills={[mySkill]} />
+```
+
+---
+
+## 6. useSkillStatus
+
+Observe the live skill registry state from any component inside `<SkillProvider>`:
+
+```tsx
+import { useSkillStatus } from "@yourgpt/copilot-sdk-react";
+
+function DebugPanel() {
+  const { skills, count, has } = useSkillStatus();
+
+  return (
+    <div>
+      <p>{count} skill(s) active</p>
+      {has("code-review") && <Badge>Code Review</Badge>}
+      <ul>
+        {skills.map((s) => (
+          <li key={s.name}>
+            {s.name} ({s.strategy ?? "auto"})
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### Return type
+
+```typescript
+interface UseSkillStatusReturn {
+  skills: ResolvedSkill[]; // All currently registered skills
+  count: number; // Number of registered skills
+  has: (name: string) => boolean; // Check if a named skill is active
+}
+```
+
+---
+
+## 7. Source Precedence & Collision Detection
+
+When the same skill name appears in multiple sources, the higher-precedence source wins and a diagnostic is recorded.
+
+```
+server-dir  >  remote-url  >  client-inline
+```
+
+```typescript
+const { diagnostics } = await loadSkills({ ... });
+
+// diagnostics: SkillDiagnostic[]
+// [{
+//   type: "collision",
+//   name: "code-review",
+//   winner: "server-dir",
+//   loser: "client-inline",
+// }]
+```
+
+This lets you safely override client-provided skills with authoritative server versions — for example, preventing users from injecting their own `brand-voice` skill that conflicts with your official one.
+
+---
+
+## 8. Type Reference
+
+```typescript
+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;
+  strategy?: SkillStrategy; // default: "auto"
+  version?: string;
+}
+
+interface ResolvedSkill extends SkillDefinition {
+  content: string; // Fully resolved content string
+}
+
+interface ClientInlineSkill {
+  name: string;
+  description: string;
+  content: string;
+  strategy?: SkillStrategy;
+}
+
+interface SkillDiagnostic {
+  type: "collision";
+  name: string;
+  winner: "server-dir" | "remote-url" | "client-inline";
+  loser: "server-dir" | "remote-url" | "client-inline";
+}
+
+interface LoadSkillResult {
+  name: string;
+  description: string;
+  strategy: SkillStrategy;
+  content: string;
+  source: "server-dir" | "remote-url" | "client-inline";
+}
+
+interface LoadSkillError {
+  error: string;
+}
+```
+
+---
+
+## 9. Full Example
+
+### Project structure
+
+```
+skills/
+├── brand-voice.md     # eager — always active
+└── sql-expert.md      # auto — loaded on demand
+```
+
+```markdown
+## <!-- skills/brand-voice.md -->
+
+name: brand-voice
+description: Acme Corp tone and style guide
+strategy: eager
+
+---
+
+Always respond in a friendly, professional tone.
+Refer to the product as "Acme" (not "the platform").
+Use metric units. Avoid passive voice.
+```
+
+```markdown
+## <!-- skills/sql-expert.md -->
+
+name: sql-expert
+description: Writes and explains SQL queries for our PostgreSQL schema
+strategy: auto
+
+---
+
+## SQL Expert
+
+Our database uses PostgreSQL 15. Key tables:
+
+- users(id, email, plan, created_at)
+- orders(id, user_id, total, status, created_at)
+- products(id, name, price, stock)
+
+When writing queries:
+
+1. Always use parameterized queries ($1, $2...)
+2. Add LIMIT clauses to SELECT queries
+3. Explain the query in plain English after writing it
+```
+
+### API route
+
+```typescript
+// app/api/chat/route.ts
+import path from "path";
+import { loadSkills } from "@yourgpt/copilot-sdk/server";
+import { streamText } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export async function POST(req: Request) {
+  const { messages, __skills } = await req.json();
+
+  const { buildSystemPrompt, tools } = await loadSkills({
+    dir: path.join(process.cwd(), "skills"),
+    clientSkills: __skills ?? [],
+  });
+
+  return streamText({
+    model: anthropic("claude-sonnet-4-6"),
+    system: buildSystemPrompt("You are a helpful assistant for Acme Corp."),
+    messages,
+    tools,
+  }).toDataStreamResponse();
+}
+```
+
+### React app
+
+```tsx
+// app/layout.tsx
+import { CopilotProvider } from "@yourgpt/copilot-sdk-react";
+import { SkillProvider, defineSkill } from "@yourgpt/copilot-sdk-react";
+
+// Extra client-only skill (e.g. page-specific context)
+const checkoutSkill = defineSkill({
+  name: "checkout-helper",
+  description: "Helps with the checkout flow",
+  strategy: "auto",
+  source: { type: "inline", content: "When helping with checkout..." },
+});
+
+export default function Layout({ children }) {
+  return (
+    <CopilotProvider widgetToken="YOUR_TOKEN" apiUrl="/api/chat">
+      <SkillProvider skills={[checkoutSkill]}>{children}</SkillProvider>
+    </CopilotProvider>
+  );
+}
+```
+
+```tsx
+// app/dashboard/page.tsx — add a page-scoped skill
+import { useSkill, useSkillStatus } from "@yourgpt/copilot-sdk-react";
+
+export default function DashboardPage() {
+  useSkill({
+    name: "dashboard-context",
+    description: "Knows about the current dashboard state",
+    strategy: "eager",
+    source: {
+      type: "inline",
+      content:
+        "The user is viewing the analytics dashboard. Current date range: last 30 days.",
+    },
+  });
+
+  const { count } = useSkillStatus();
+
+  return (
+    <div>
+      <p>{count} skills active</p>
+      <Dashboard />
+    </div>
+  );
+}
+```

From 595ab9a1d1a41108a31ad35ef71d513e8165ea21 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 15 Mar 2026 13:59:09 +0530
Subject: [PATCH 18/72] fix(sdk): fix branch tree corruption in streaming and
 non-streaming modes

Streaming fixes (AbstractChat.ts):
- All three updateMessageById calls now preserve parentId/childrenIds from
  the pre-pushed placeholder so the branch tree is not corrupted when
  setCurrentLeaf() walks up the chain. Root cause was the final finalization
  block running after the per-chunk fix and re-discarding parentId.

Non-streaming fixes (AbstractChat.ts):
- handleJsonResponse now chains parentId correctly so AI messages are
  placed as children of the current leaf, not at root level.
- Placeholder removal now uses getAllMessages() instead of visible-only
  messages so inactive branches are preserved across tree.reset().
- Active path is captured before tree.reset() and restored after so edits
  on any branch land on the correct parent node.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../docs/alpha-docs}/BRANCHING.md             | 142 ++--
 apps/docs/alpha-docs/CONTEXT-MANAGEMENT.md    | 733 ++++++++++++++++++
 apps/docs/alpha-docs/SKILLS.md                | 518 +++++++++++++
 .../src/chat/branching/MessageTree.ts         |  26 +-
 .../src/chat/classes/AbstractChat.ts          | 101 ++-
 .../src/react/provider/CopilotProvider.tsx    |  40 +-
 6 files changed, 1459 insertions(+), 101 deletions(-)
 rename {packages/copilot-sdk => apps/docs/alpha-docs}/BRANCHING.md (53%)
 create mode 100644 apps/docs/alpha-docs/CONTEXT-MANAGEMENT.md
 create mode 100644 apps/docs/alpha-docs/SKILLS.md

diff --git a/packages/copilot-sdk/BRANCHING.md b/apps/docs/alpha-docs/BRANCHING.md
similarity index 53%
rename from packages/copilot-sdk/BRANCHING.md
rename to apps/docs/alpha-docs/BRANCHING.md
index 282c4a1..efd266a 100644
--- a/packages/copilot-sdk/BRANCHING.md
+++ b/apps/docs/alpha-docs/BRANCHING.md
@@ -59,11 +59,11 @@ Two-panel layout inside a single `CopilotProvider`:
 
 ### Demo source files
 
-| File | Purpose |
-|------|---------|
-| `examples/experimental/app/branching/page.tsx` | Page: `CopilotProvider` + two-panel layout |
-| `examples/experimental/components/branching/BranchTreePanel.tsx` | Live tree visualization component |
-| `examples/experimental/app/api/chat/branching/route.ts` | Anthropic API route (haiku, short replies) |
+| File                                                             | Purpose                                    |
+| ---------------------------------------------------------------- | ------------------------------------------ |
+| `examples/experimental/app/branching/page.tsx`                   | Page: `CopilotProvider` + two-panel layout |
+| `examples/experimental/components/branching/BranchTreePanel.tsx` | Live tree visualization component          |
+| `examples/experimental/app/api/chat/branching/route.ts`          | Anthropic API route (haiku, short replies) |
 
 ### Key code pattern in the demo
 
@@ -86,40 +86,40 @@ const visibleIds = new Set(messages.map(m => m.id)); // active path
 
 ### Core Data Layer
 
-| File | What Changed |
-|------|-------------|
-| `src/chat/branching/MessageTree.ts` | **New.** Pure TypeScript tree utility. Bidirectional flat-map: `parentId` + `childrenIds[]` + `activeChildMap`. No React dependency. |
-| `src/chat/branching/index.ts` | **New.** Barrel export. |
-| `src/chat/types/message.ts` | Added `parentId?: string \| null` and `childrenIds?: string[]` to `UIMessage`. |
-| `src/core/types/message.ts` | Added `parent_id?: string \| null` and `children_ids?: string[]` to `Message` (persistence layer). |
-| `src/chat/interfaces/ChatState.ts` | Added 5 optional branching methods: `setCurrentLeaf`, `getAllMessages`, `getBranchInfo`, `switchBranch`, `hasBranches`. |
-| `src/react/internal/ReactChatState.ts` | Replaced `_messages: T[]` array with `MessageTree<T>`. `messages` getter = visible path only. |
-| `src/chat/classes/AbstractChat.ts` | `regenerate()` rewritten to be branch-aware (creates sibling instead of destroying). `sendMessage()` extended with `options.editMessageId`. `onMessagesChange` callback now passes all branches via `_allMessages()`. |
-| `src/chat/ChatWithTools.ts` | `sendMessage()` passes through `options.editMessageId`. |
+| File                                   | What Changed                                                                                                                                                                                                          |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/chat/branching/MessageTree.ts`    | **New.** Pure TypeScript tree utility. Bidirectional flat-map: `parentId` + `childrenIds[]` + `activeChildMap`. No React dependency.                                                                                  |
+| `src/chat/branching/index.ts`          | **New.** Barrel export.                                                                                                                                                                                               |
+| `src/chat/types/message.ts`            | Added `parentId?: string \| null` and `childrenIds?: string[]` to `UIMessage`.                                                                                                                                        |
+| `src/core/types/message.ts`            | Added `parent_id?: string \| null` and `children_ids?: string[]` to `Message` (persistence layer).                                                                                                                    |
+| `src/chat/interfaces/ChatState.ts`     | Added 5 optional branching methods: `setCurrentLeaf`, `getAllMessages`, `getBranchInfo`, `switchBranch`, `hasBranches`.                                                                                               |
+| `src/react/internal/ReactChatState.ts` | Replaced `_messages: T[]` array with `MessageTree<T>`. `messages` getter = visible path only.                                                                                                                         |
+| `src/chat/classes/AbstractChat.ts`     | `regenerate()` rewritten to be branch-aware (creates sibling instead of destroying). `sendMessage()` extended with `options.editMessageId`. `onMessagesChange` callback now passes all branches via `_allMessages()`. |
+| `src/chat/ChatWithTools.ts`            | `sendMessage()` passes through `options.editMessageId`.                                                                                                                                                               |
 
 ### React Layer
 
-| File | What Changed |
-|------|-------------|
-| `src/react/internal/ReactChat.ts` | Added `switchBranch`, `getBranchInfo`, `getAllMessages`, `hasBranches` pass-throughs. |
-| `src/react/internal/ReactChatWithTools.ts` | Same pass-throughs. |
-| `src/react/internal/useChat.ts` | Added `switchBranch`, `getBranchInfo`, `editMessage`, `hasBranches` to `UseChatReturn`. |
-| `src/react/context/CopilotContext.tsx` | Added branching methods to `ChatActions`. |
-| `src/react/provider/CopilotProvider.tsx` | Wired branching methods into context. `onMessagesChange` effect uses `getAllMessages()`. Added `getAllMessages` to `CopilotContextValue`. |
-| `src/react/index.ts` | Re-exports `MessageTree`, `BranchInfo`. |
-| `src/chat/index.ts` | Re-exports `MessageTree`, `BranchInfo`. |
+| File                                       | What Changed                                                                                                                              |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/react/internal/ReactChat.ts`          | Added `switchBranch`, `getBranchInfo`, `getAllMessages`, `hasBranches` pass-throughs.                                                     |
+| `src/react/internal/ReactChatWithTools.ts` | Same pass-throughs.                                                                                                                       |
+| `src/react/internal/useChat.ts`            | Added `switchBranch`, `getBranchInfo`, `editMessage`, `hasBranches` to `UseChatReturn`.                                                   |
+| `src/react/context/CopilotContext.tsx`     | Added branching methods to `ChatActions`.                                                                                                 |
+| `src/react/provider/CopilotProvider.tsx`   | Wired branching methods into context. `onMessagesChange` effect uses `getAllMessages()`. Added `getAllMessages` to `CopilotContextValue`. |
+| `src/react/index.ts`                       | Re-exports `MessageTree`, `BranchInfo`.                                                                                                   |
+| `src/chat/index.ts`                        | Re-exports `MessageTree`, `BranchInfo`.                                                                                                   |
 
 ### UI Layer
 
-| File | What Changed |
-|------|-------------|
-| `src/ui/components/ui/branch-navigator.tsx` | **New.** `← N/M →` purely presentational component. |
-| `src/ui/components/composed/chat/types.ts` | Added `getBranchInfo`, `onSwitchBranch`, `onEditMessage` to `ChatProps`. |
-| `src/ui/components/composed/chat/default-message.tsx` | User messages: pencil edit button on hover, inline textarea edit, `BranchNavigator` shown when siblings exist. |
-| `src/ui/components/composed/chat/chat.tsx` | Passes branch props through to each message. |
-| `src/ui/components/composed/connected-chat.tsx` | Pulls `switchBranch`, `getBranchInfo`, `editMessage` from `useCopilot()` and passes to `<Chat />`. |
-| `src/ui/hooks/useInternalThreadManager.ts` | Save path uses `getAllMessages()`. Load paths restore `parentId`/`childrenIds`. `convertToCore` includes `parent_id`/`children_ids`. |
-| `src/ui/index.ts` | Exports `BranchNavigator`, `BranchNavigatorProps`. |
+| File                                                  | What Changed                                                                                                                         |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/ui/components/ui/branch-navigator.tsx`           | **New.** `← N/M →` purely presentational component.                                                                                  |
+| `src/ui/components/composed/chat/types.ts`            | Added `getBranchInfo`, `onSwitchBranch`, `onEditMessage` to `ChatProps`.                                                             |
+| `src/ui/components/composed/chat/default-message.tsx` | User messages: pencil edit button on hover, inline textarea edit, `BranchNavigator` shown when siblings exist.                       |
+| `src/ui/components/composed/chat/chat.tsx`            | Passes branch props through to each message.                                                                                         |
+| `src/ui/components/composed/connected-chat.tsx`       | Pulls `switchBranch`, `getBranchInfo`, `editMessage` from `useCopilot()` and passes to `<Chat />`.                                   |
+| `src/ui/hooks/useInternalThreadManager.ts`            | Save path uses `getAllMessages()`. Load paths restore `parentId`/`childrenIds`. `convertToCore` includes `parent_id`/`children_ids`. |
+| `src/ui/index.ts`                                     | Exports `BranchNavigator`, `BranchNavigatorProps`.                                                                                   |
 
 ---
 
@@ -129,14 +129,14 @@ const visibleIds = new Set(messages.map(m => m.id)); // active path
 
 All new fields and methods are optional. Every existing usage continues to work without modification:
 
-| Scenario | Behavior |
-|----------|----------|
-| Messages with no `parentId` | `getVisibleMessages()` falls back to insertion order (legacy linear) |
-| `regenerate()` called without arguments | Finds last assistant on visible path — identical to before |
-| `sendMessage()` with no third argument | Identical to before |
-| `useChat()` / `useCopilot()` consumers | All branching fields available but optional — no existing destructuring breaks |
-| `onMessagesChange` callback consumers | Now receives all branches instead of visible path only — **payload size may increase** if branches exist, but shape is identical (`Message[]`) |
-| DB rows with no `parent_id` column | Auto-migrated via `fromFlatArray()` on load — no manual migration script needed for existing data |
+| Scenario                                | Behavior                                                                                                                                       |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Messages with no `parentId`             | `getVisibleMessages()` falls back to insertion order (legacy linear)                                                                           |
+| `regenerate()` called without arguments | Finds last assistant on visible path — identical to before                                                                                     |
+| `sendMessage()` with no third argument  | Identical to before                                                                                                                            |
+| `useChat()` / `useCopilot()` consumers  | All branching fields available but optional — no existing destructuring breaks                                                                 |
+| `onMessagesChange` callback consumers   | Now receives all branches instead of visible path only — **payload size may increase** if branches exist, but shape is identical (`Message[]`) |
+| DB rows with no `parent_id` column      | Auto-migrated via `fromFlatArray()` on load — no manual migration script needed for existing data                                              |
 
 > **Note on `onMessagesChange` payload:** If a user has branched the conversation, the callback now receives all messages across all branches (not just the active path). The shape is the same `Message[]` type. If your persistence layer deduplicates by message ID, no change is needed. If it blindly appends, you may want to upsert by ID instead.
 
@@ -148,11 +148,11 @@ All new fields and methods are optional. Every existing usage continues to work
 
 ```typescript
 const {
-  switchBranch,   // (messageId: string) => void
-  getBranchInfo,  // (messageId: string) => BranchInfo | null
-  editMessage,    // (messageId: string, newContent: string) => Promise<void>
-  hasBranches,    // boolean — true if any fork exists
-  getAllMessages,  // () => UIMessage[] — all branches, not just visible path
+  switchBranch, // (messageId: string) => void
+  getBranchInfo, // (messageId: string) => BranchInfo | null
+  editMessage, // (messageId: string, newContent: string) => Promise<void>
+  hasBranches, // boolean — true if any fork exists
+  getAllMessages, // () => UIMessage[] — all branches, not just visible path
 } = useCopilot();
 ```
 
@@ -181,9 +181,9 @@ const {
 
 ```typescript
 interface BranchInfo {
-  siblingIndex: number;    // 0-based — which variant this is
-  totalSiblings: number;   // how many variants exist at this fork
-  siblingIds: string[];    // ordered oldest-first
+  siblingIndex: number; // 0-based — which variant this is
+  totalSiblings: number; // how many variants exist at this fork
+  siblingIds: string[]; // ordered oldest-first
   hasPrevious: boolean;
   hasNext: boolean;
 }
@@ -192,7 +192,7 @@ interface BranchInfo {
 ### `BranchNavigator` component (UI primitives)
 
 ```tsx
-import { BranchNavigator } from '@yourgpt/copilot-sdk-ui';
+import { BranchNavigator } from "@yourgpt/copilot-sdk-ui";
 
 <BranchNavigator
   siblingIndex={info.siblingIndex}
@@ -201,20 +201,20 @@ import { BranchNavigator } from '@yourgpt/copilot-sdk-ui';
   hasNext={info.hasNext}
   onPrevious={() => switchBranch(info.siblingIds[info.siblingIndex - 1])}
   onNext={() => switchBranch(info.siblingIds[info.siblingIndex + 1])}
-/>
+/>;
 ```
 
 ### `MessageTree` (framework-agnostic)
 
 ```typescript
-import { MessageTree, type BranchInfo } from '@yourgpt/copilot-sdk';
+import { MessageTree, type BranchInfo } from "@yourgpt/copilot-sdk";
 
 const tree = new MessageTree(messages);
-tree.getVisibleMessages();     // active path only
-tree.getAllMessages();          // all branches
+tree.getVisibleMessages(); // active path only
+tree.getAllMessages(); // all branches
 tree.getBranchInfo(messageId); // BranchInfo | null
 tree.switchBranch(messageId);
-tree.hasBranches;              // boolean
+tree.hasBranches; // boolean
 ```
 
 ---
@@ -231,10 +231,10 @@ ALTER TABLE messages
   ADD COLUMN children_ids JSONB DEFAULT '[]';
 ```
 
-| Column | Type | Nullable | Description |
-|--------|------|----------|-------------|
-| `parent_id` | `TEXT` / `VARCHAR` | YES | ID of parent message. `NULL` = root. Missing = legacy linear. |
-| `children_ids` | `JSON` array of strings | YES | Ordered child IDs for O(1) sibling lookup. |
+| Column         | Type                    | Nullable | Description                                                   |
+| -------------- | ----------------------- | -------- | ------------------------------------------------------------- |
+| `parent_id`    | `TEXT` / `VARCHAR`      | YES      | ID of parent message. `NULL` = root. Missing = legacy linear. |
+| `children_ids` | `JSON` array of strings | YES      | Ordered child IDs for O(1) sibling lookup.                    |
 
 > **These columns are optional.** Existing rows without them are auto-migrated to a linear tree on load via `fromFlatArray()`. No data loss. No required migration for existing rows.
 
@@ -320,7 +320,7 @@ If you render messages manually, use `getBranchInfo` + `BranchNavigator`:
 ```tsx
 function MyMessage({ message }) {
   const { switchBranch, getBranchInfo } = useCopilot();
-  const info = message.role === 'user' ? getBranchInfo(message.id) : null;
+  const info = message.role === "user" ? getBranchInfo(message.id) : null;
 
   return (
     <div>
@@ -328,7 +328,9 @@ function MyMessage({ message }) {
       {info && (
         <BranchNavigator
           {...info}
-          onPrevious={() => switchBranch(info.siblingIds[info.siblingIndex - 1])}
+          onPrevious={() =>
+            switchBranch(info.siblingIds[info.siblingIndex - 1])
+          }
           onNext={() => switchBranch(info.siblingIds[info.siblingIndex + 1])}
         />
       )}
@@ -341,14 +343,14 @@ function MyMessage({ message }) {
 
 ```typescript
 // Edit a message (creates new branch from same parent)
-await editMessage('msg-abc', 'Updated question text');
+await editMessage("msg-abc", "Updated question text");
 
 // Navigate between variants
-switchBranch('msg-xyz');
+switchBranch("msg-xyz");
 
 // Check if branches exist
 if (hasBranches) {
-  const info = getBranchInfo('msg-abc');
+  const info = getBranchInfo("msg-abc");
   // info.totalSiblings, info.siblingIndex, etc.
 }
 
@@ -364,7 +366,7 @@ await saveToServer(allMessages);
 All branching primitives are exported from the core package (no React required):
 
 ```typescript
-import { MessageTree, type BranchInfo } from '@yourgpt/copilot-sdk';
+import { MessageTree, type BranchInfo } from "@yourgpt/copilot-sdk";
 
 // Build a tree from saved messages
 const tree = new MessageTree(savedMessages);
@@ -403,11 +405,11 @@ childrenIds: string[]
 
 The `MessageTree` maintains three maps:
 
-| Map | Key | Value | Purpose |
-|-----|-----|-------|---------|
-| `nodeMap` | messageId | Message | O(1) message lookup |
-| `childrenOf` | parentId (or `__root__`) | `string[]` | All children at a fork |
-| `activeChildMap` | parentId | active child ID | Which branch is currently visible |
+| Map              | Key                      | Value           | Purpose                           |
+| ---------------- | ------------------------ | --------------- | --------------------------------- |
+| `nodeMap`        | messageId                | Message         | O(1) message lookup               |
+| `childrenOf`     | parentId (or `__root__`) | `string[]`      | All children at a fork            |
+| `activeChildMap` | parentId                 | active child ID | Which branch is currently visible |
 
 ### Regenerate flow
 
diff --git a/apps/docs/alpha-docs/CONTEXT-MANAGEMENT.md b/apps/docs/alpha-docs/CONTEXT-MANAGEMENT.md
new file mode 100644
index 0000000..78bb8a4
--- /dev/null
+++ b/apps/docs/alpha-docs/CONTEXT-MANAGEMENT.md
@@ -0,0 +1,733 @@
+# Context Management
+
+Advanced context window management for the YourGPT Copilot SDK. These features give you full control over what the AI sees, how long conversations stay alive, and how tokens are tracked and budgeted.
+
+---
+
+## Table of Contents
+
+1. [Dual-Layer Message Store](#1-dual-layer-message-store)
+2. [Message History & Compaction](#2-message-history--compaction)
+   - [Compaction Strategies](#compaction-strategies)
+   - [Config Reference](#config-reference)
+3. [Token Counting](#3-token-counting)
+4. [Session Persistence](#4-session-persistence)
+5. [useContextStats](#5-usecontextstats)
+6. [AgentLoop API](#6-agentloop-api)
+7. [Tools — useTool / useTools / ToolDefinition](#7-tools--usetool--usetools--tooldefinition)
+   - [Deferred Tools](#deferred-tools)
+   - [Hidden Tools](#hidden-tools)
+   - [Fallback Tool Renderer](#fallback-tool-renderer)
+8. [Message Grouping](#8-message-grouping)
+9. [Server: compactSession](#9-server-compactsession)
+
+---
+
+## 1. Dual-Layer Message Store
+
+Every conversation maintains two parallel views of the message history.
+
+| Layer                 | Type               | Purpose                                                                           |
+| --------------------- | ------------------ | --------------------------------------------------------------------------------- |
+| **Display layer**     | `DisplayMessage[]` | Full immutable history. Rendered in the UI. Never shrinks.                        |
+| **LLM context layer** | `LLMMessage[]`     | Compacted/pruned form sent to the model on each request. Rebuilt on every render. |
+
+### Types
+
+```typescript
+// Display layer — extends UIMessage for full backward-compat
+interface DisplayMessage extends UIMessage {
+  timestamp: number; // Unix ms
+}
+
+// Injected into displayMessages when compaction fires
+interface CompactionMarker extends DisplayMessage {
+  role: "system";
+  type: "compaction-marker";
+  content: string; // Human-readable summary
+  summarizedMessageIds: string[];
+  tokensSaved: number;
+}
+
+// LLM context layer — what the model actually sees
+interface LLMMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  tool_calls?: ToolCall[];
+  tool_call_id?: string;
+}
+
+// Replaces a full tool result when old enough to prune
+interface CompactedToolResult {
+  type: "compacted-tool-result";
+  toolName: string;
+  toolCallId: string;
+  args: Record<string, unknown>;
+  executedAt: number;
+  status: "success" | "error";
+  originalSize: number;
+  summary: string;
+  extract?: string; // First 200 chars if no LLM summary
+}
+```
+
+### Conversion helpers
+
+```typescript
+import {
+  toDisplayMessage,
+  toLLMMessage,
+  toLLMMessages,
+  keepToolPairsAtomic,
+} from "@yourgpt/copilot-sdk-react";
+```
+
+`keepToolPairsAtomic` ensures that when you slice a window, an `assistant` message with `tool_calls` is never separated from its corresponding tool-result messages.
+
+---
+
+## 2. Message History & Compaction
+
+### useMessageHistory
+
+```typescript
+import { useMessageHistory } from "@yourgpt/copilot-sdk-react";
+
+function MyChat() {
+  const {
+    displayMessages, // Full UI history
+    llmMessages, // Compacted LLM context
+    tokenUsage, // Live token estimate
+    isCompacting, // true while auto-compaction runs
+    compactionState, // Metadata & rolling summary
+    compactSession, // Manual trigger
+    addToWorkingMemory,
+    clearWorkingMemory,
+    resetSession,
+  } = useMessageHistory({
+    strategy: "summary-buffer",
+    maxContextTokens: 128000,
+    compactionThreshold: 0.75,
+    compactionUrl: "/api/compact",
+    persistSession: true,
+  });
+}
+```
+
+#### Return type
+
+```typescript
+interface UseMessageHistoryReturn {
+  displayMessages: DisplayMessage[];
+  llmMessages: LLMMessage[];
+  tokenUsage: TokenUsage;
+  isCompacting: boolean;
+  compactionState: SessionCompactionState;
+  compactSession: (instructions?: string) => Promise<void>;
+  addToWorkingMemory: (fact: string) => void;
+  clearWorkingMemory: () => void;
+  resetSession: () => void;
+}
+```
+
+### Compaction Strategies
+
+Four strategies are available via the `strategy` config field.
+
+#### `"none"` (default)
+
+No compaction. Zero-config, 100% backward-compatible. All messages sent verbatim.
+
+```typescript
+useMessageHistory({ strategy: "none" });
+```
+
+#### `"sliding-window"`
+
+Keeps only the most recent N tokens of history. Oldest messages are dropped when the token budget is exceeded.
+
+```typescript
+useMessageHistory({
+  strategy: "sliding-window",
+  maxContextTokens: 128000,
+  reserveForResponse: 4096,
+  recentBuffer: 10, // Always keep at least 10 recent messages
+  toolResultMaxChars: 10000, // Truncate large tool results
+});
+```
+
+#### `"selective-prune"`
+
+Removes tool-result messages that are older than `recentBuffer`, keeping the conversation skeleton (user/assistant turns) intact. Lighter than sliding-window — no token counting required.
+
+```typescript
+useMessageHistory({
+  strategy: "selective-prune",
+  recentBuffer: 10,
+});
+```
+
+#### `"summary-buffer"`
+
+Summarizes old messages into a rolling summary when usage exceeds `compactionThreshold`. The summary is injected into the LLM context as a system message. Requires a `/api/compact` endpoint (or custom `summarizer`).
+
+```typescript
+useMessageHistory({
+  strategy: "summary-buffer",
+  compactionThreshold: 0.75, // Compact at 75% of maxContextTokens
+  compactionUrl: "/api/compact",
+  recentBuffer: 10,
+  onCompaction: (event) => {
+    console.log(
+      `Compacted ${event.messagesSummarized} messages, saved ~${event.tokensSaved} tokens`,
+    );
+  },
+});
+```
+
+Custom summarizer (skip the HTTP round-trip):
+
+```typescript
+useMessageHistory({
+  strategy: "summary-buffer",
+  summarizer: async (messages) => {
+    const res = await myLLM.summarize(messages);
+    return res.text;
+  },
+});
+```
+
+### Config Reference
+
+```typescript
+interface MessageHistoryConfig {
+  strategy?: "none" | "sliding-window" | "summary-buffer" | "selective-prune";
+  maxContextTokens?: number; // default: 128000
+  reserveForResponse?: number; // default: 4096
+  compactionThreshold?: number; // default: 0.75
+  recentBuffer?: number; // default: 10
+  toolResultMaxChars?: number; // default: 10000 (0 = no cap)
+  compactionUrl?: string; // required for summary-buffer
+  persistSession?: boolean; // default: false
+  storageKey?: string; // default: "copilot-session"
+  onCompaction?: (event: CompactionEvent) => void;
+  onTokenUsage?: (usage: TokenUsage) => void;
+}
+```
+
+#### Per-call options
+
+```typescript
+interface UseMessageHistoryOptions extends MessageHistoryConfig {
+  skipCompaction?: boolean;
+  tokenEstimation?: "fast" | "accurate" | "off"; // default: "fast"
+  summarizer?: (messages: LLMMessage[]) => Promise<string>;
+}
+```
+
+### Provider-level config
+
+Set defaults once in `<CopilotProvider>` instead of each `useMessageHistory` call:
+
+```tsx
+<CopilotProvider
+  messageHistory={{
+    strategy: "summary-buffer",
+    maxContextTokens: 128000,
+    compactionUrl: "/api/compact",
+    persistSession: true,
+  }}
+>
+  <App />
+</CopilotProvider>
+```
+
+### Working Memory
+
+Pin facts that survive all future compactions:
+
+```typescript
+const { addToWorkingMemory, clearWorkingMemory } = useMessageHistory({ ... });
+
+// Survives compaction
+addToWorkingMemory("User is on the Pro plan. Account ID: acct_123");
+
+// Remove all pinned facts
+clearWorkingMemory();
+```
+
+### Compaction event & token usage types
+
+```typescript
+interface CompactionEvent {
+  type: "auto" | "manual";
+  compactionCount: number;
+  messagesSummarized: number;
+  tokensSaved: number;
+  timestamp: number;
+}
+
+interface TokenUsage {
+  current: number; // Estimated tokens in LLM context
+  max: number; // maxContextTokens
+  percentage: number; // current / max (0–1)
+  isApproaching: boolean; // percentage >= compactionThreshold
+}
+
+interface SessionCompactionState {
+  rollingSummary: string | null;
+  lastCompactionAt: number | null;
+  compactionCount: number;
+  totalTokensSaved: number;
+  workingMemory: string[];
+  displayMessageCount: number;
+  llmMessageCount: number;
+}
+```
+
+---
+
+## 3. Token Counting
+
+Two-tier estimation — pick the right trade-off between speed and accuracy.
+
+### Tier 1: Fast (zero dependencies)
+
+Uses a `chars / 3.5` heuristic. ~85–90% accurate for English. Always available, no bundle cost.
+
+```typescript
+import {
+  estimateTokensFast,
+  estimateMessageTokens,
+  estimateMessagesTokens,
+} from "@yourgpt/copilot-sdk-react";
+
+const tokens = estimateTokensFast("Hello world"); // fast, synchronous
+const msgTokens = estimateMessagesTokens(llmMessages);
+```
+
+### Tier 2: Accurate (lazy-loaded)
+
+Uses `gpt-tokenizer` with the `o200k_base` encoding. Lazy-loaded only when called — no upfront bundle cost. Falls back to Tier 1 if `gpt-tokenizer` is not installed.
+
+```typescript
+import {
+  countTokensAccurate,
+  countMessagesTokensAccurate,
+} from "@yourgpt/copilot-sdk-react";
+
+// Only loads gpt-tokenizer on first call
+const tokens = await countTokensAccurate("Hello world");
+const msgTokens = await countMessagesTokensAccurate(llmMessages);
+```
+
+### Dispatcher
+
+```typescript
+import { estimateTokens } from "@yourgpt/copilot-sdk-react";
+import type { TokenEstimationMode } from "@yourgpt/copilot-sdk-react";
+
+// mode: "fast" | "accurate" | "off"
+const tokens = estimateTokens(llmMessages, "fast");
+```
+
+Set via `tokenEstimation` in `useMessageHistory`:
+
+```typescript
+useMessageHistory({ tokenEstimation: "accurate" });
+```
+
+---
+
+## 4. Session Persistence
+
+Survive page reloads with zero extra code.
+
+```typescript
+useMessageHistory({
+  persistSession: true,
+  storageKey: "my-app-chat", // default: "copilot-session"
+});
+```
+
+| What is persisted                  | Where                                                      |
+| ---------------------------------- | ---------------------------------------------------------- |
+| `compactionState` (small metadata) | `localStorage` — sync, available immediately on cold start |
+| `displayMessages` (can be large)   | `IndexedDB` — async, avoids localStorage quota issues      |
+
+Both are keyed by `storageKey`. Multiple chat instances can coexist with different keys.
+
+Clear everything (including storage) with:
+
+```typescript
+const { resetSession } = useMessageHistory({ persistSession: true });
+await resetSession();
+```
+
+---
+
+## 5. useContextStats
+
+Live snapshot of context window usage. Updates reactively on every message send.
+
+```typescript
+import { useContextStats } from "@yourgpt/copilot-sdk-react";
+
+function ContextMonitor() {
+  const {
+    contextUsage,        // Full breakdown by bucket (richest field)
+    totalTokens,         // Convenience: total estimated tokens
+    usagePercent,        // Convenience: window fill 0–1
+    contextChars,        // Characters contributed by AI context injections
+    toolCount,           // Number of currently registered tools
+    messageCount,        // Visible (non-system) messages
+    lastResponseUsage,   // Token usage from last assistant message
+  } = useContextStats();
+
+  // Breakdown by bucket
+  const historyTokens = contextUsage?.breakdown.history.tokens;
+  const systemPercent = contextUsage?.breakdown.systemPrompt.percent;
+
+  return (
+    <div>
+      <p>{Math.round(usagePercent * 100)}% of context used</p>
+      <p>{totalTokens} tokens / {toolCount} tools</p>
+      {lastResponseUsage && (
+        <p>Last turn: {lastResponseUsage.total_tokens} tokens</p>
+      )}
+    </div>
+  );
+}
+```
+
+### Return type
+
+```typescript
+interface ContextStats {
+  contextUsage: ContextUsage | null; // null until first message
+  totalTokens: number;
+  usagePercent: number; // 0 until first message
+  contextChars: number;
+  toolCount: number;
+  messageCount: number;
+  lastResponseUsage: MessageTokenUsage | null;
+}
+
+interface MessageTokenUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+}
+```
+
+---
+
+## 6. AgentLoop API
+
+`AbstractAgentLoop` is the framework-agnostic core that manages the tool execution loop, approvals, and cancellation.
+
+```typescript
+import { AbstractAgentLoop } from "@yourgpt/copilot-sdk";
+
+const loop = new AbstractAgentLoop(
+  {
+    maxIterations: 20,
+    tools: [myTool],
+  },
+  {
+    onToolExecutionsChange: (executions) => setExecutions(executions),
+    onToolApprovalRequired: (execution) => showApprovalModal(execution),
+  },
+);
+
+// Register/unregister tools at runtime
+loop.registerTool(weatherTool);
+loop.unregisterTool("old_tool");
+
+// Execute tool calls returned by the LLM
+const results = await loop.executeToolCalls(toolCallsFromLLM);
+
+// Cancel in-flight execution
+loop.cancel();
+```
+
+### Config
+
+```typescript
+interface AgentLoopConfig {
+  maxIterations?: number; // default: 20
+  maxExecutionHistory?: number; // default: 100
+  tools?: ToolDefinition[];
+}
+```
+
+Tools use reference counting so React StrictMode double-invocations don't leave orphaned registrations.
+
+---
+
+## 7. Tools — useTool / useTools / ToolDefinition
+
+### useTool
+
+Register a single client-side tool from a React component. Accepts both Zod schemas and JSON Schema.
+
+```typescript
+import { useTool } from "@yourgpt/copilot-sdk-react";
+import { z } from "zod";
+
+function MyComponent() {
+  useTool({
+    name: "navigate_to_page",
+    description: "Navigate to a page in the app",
+    inputSchema: z.object({
+      path: z.string().describe("Route path to navigate to"),
+    }),
+    handler: async ({ path }) => {
+      router.push(path);
+      return { success: true };
+    },
+    // Optional UI rendering
+    render: ({ args, result }) => <NavigationCard path={args.path} />,
+  });
+}
+```
+
+### useTools (ToolSet pattern)
+
+Register multiple tools at once using the Vercel AI SDK `ToolSet` pattern:
+
+```typescript
+import { useTools, tool } from "@yourgpt/copilot-sdk-react";
+
+function MyApp() {
+  useTools({
+    get_weather: tool({
+      description: "Get weather for a location",
+      inputSchema: {
+        type: "object",
+        properties: { location: { type: "string" } },
+        required: ["location"],
+      },
+      handler: async ({ location }) => fetchWeather(location),
+    }),
+    open_modal: tool({
+      description: "Open a UI modal",
+      inputSchema: z.object({ id: z.string() }),
+      handler: async ({ id }) => {
+        openModal(id);
+        return { success: true };
+      },
+    }),
+  });
+}
+```
+
+### UseToolConfig reference
+
+```typescript
+interface UseToolConfig<TParams> {
+  name: string;
+  description: string;
+  inputSchema: ZodSchema | JSONSchema; // Both accepted
+  handler: (
+    params: TParams,
+    context?: ToolContext,
+  ) => Promise<ToolResponse> | ToolResponse;
+
+  // UI
+  render?: (props: ToolRenderProps<TParams>) => React.ReactNode;
+  title?: string | ((args: TParams) => string);
+  executingTitle?: string | ((args: TParams) => string);
+  completedTitle?: string | ((args: TParams) => string);
+
+  // Behaviour
+  available?: boolean; // default: true
+  needsApproval?: boolean;
+  approvalMessage?: string | ((params: TParams) => string);
+  hidden?: boolean; // default: false — see Hidden Tools
+  aiResponseMode?: AIResponseMode;
+  aiContext?: string | ((result, args) => string);
+  resultConfig?: ToolResultConfig;
+
+  // Loading strategy
+  deferLoading?: boolean; // see Deferred Tools
+  profiles?: string[];
+  searchKeywords?: string[];
+  group?: string;
+  category?: string;
+}
+```
+
+### Deferred Tools
+
+Large tool registries can bloat the LLM request payload. Mark tools with `deferLoading: true` to keep them out of the default request — they are auto-detected and injected only when the user's query semantically matches the tool.
+
+```typescript
+useTool({
+  name: "run_sql_query",
+  description: "Execute a SQL query against the database",
+  deferLoading: true, // Not sent on every request
+  searchKeywords: ["sql", "query", "database", "table"],
+  inputSchema: z.object({ query: z.string() }),
+  handler: async ({ query }) => db.execute(query),
+});
+```
+
+Auto-detection uses `description` + `searchKeywords` to score relevance against the current message. No configuration required.
+
+### Hidden Tools
+
+Register tools that execute silently — they run when called by the AI but are never shown in the tool execution UI.
+
+```typescript
+useTool({
+  name: "log_analytics_event",
+  description: "Log a UI analytics event",
+  hidden: true, // Never rendered in chat UI
+  inputSchema: z.object({ event: z.string(), data: z.record(z.unknown()) }),
+  handler: async ({ event, data }) => {
+    analytics.track(event, data);
+    return {};
+  },
+});
+```
+
+### Fallback Tool Renderer
+
+The `<CopilotChat>` component resolves a renderer for each tool execution using this priority chain:
+
+1. **`toolRenderers[toolName]`** — per-tool renderer map passed to `<CopilotChat>`
+2. **`tool.render`** — render function attached to the `ToolDefinition` via `useTool`
+3. **`mcpToolRenderer`** — catch-all for tools with `source: "mcp"`
+4. **`fallbackToolRenderer`** — catch-all for any tool not matched above
+5. **Built-in default** — generic tool execution card
+
+```tsx
+<CopilotChat
+  // Highest priority — per-tool
+  toolRenderers={{
+    get_weather: ({ args, result }) => <WeatherCard {...result} />,
+  }}
+  // MCP catch-all
+  mcpToolRenderer={({ toolName, args, result }) => <MCPCard name={toolName} />}
+  // Universal catch-all
+  fallbackToolRenderer={({ toolName, args, result }) => (
+    <pre>{JSON.stringify(result, null, 2)}</pre>
+  )}
+/>
+```
+
+---
+
+## 8. Message Grouping
+
+`groupConsecutiveMessages` groups consecutive messages of the same role into visual clusters. Useful for building custom chat UIs where adjacent user or assistant messages should appear as one block.
+
+Available from the message-utils module:
+
+```typescript
+import {
+  toLLMMessages,
+  toLLMMessage,
+  keepToolPairsAtomic,
+} from "@yourgpt/copilot-sdk-react";
+```
+
+Core invariant: **tool-call pairs are always atomic.** An assistant message with `tool_calls` is never separated from its corresponding tool-result messages during any windowing or pruning operation.
+
+---
+
+## 9. Server: compactSession
+
+The `compactSession` utility powers the `/api/compact` endpoint for `summary-buffer` compaction. It calls Claude (defaults to `claude-haiku-4-5`) to produce a structured summary that preserves:
+
+- User goals and requests
+- Technical decisions and chosen approaches
+- Tool call outcomes (name, key args, result status)
+- Errors and resolutions
+- Pending tasks and current work state
+
+```typescript
+// app/api/compact/route.ts
+import { compactSession } from "@yourgpt/copilot-sdk/server";
+
+export async function POST(req: Request) {
+  const { messages, existingSummary, workingMemory } = await req.json();
+
+  const { summary } = await compactSession({
+    messages,
+    existingSummary, // Passed in subsequent compactions for rolling summaries
+    workingMemory, // User-pinned facts (addToWorkingMemory)
+    model: "claude-haiku-4-5", // default
+    maxSummaryTokens: 1024, // default
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  });
+
+  return Response.json({ summary });
+}
+```
+
+### CompactSessionOptions
+
+```typescript
+interface CompactSessionOptions {
+  messages: Array<{ role: string; content?: string | null }>;
+  existingSummary?: string | null;
+  workingMemory?: string[];
+  model?: string; // default: "claude-haiku-4-5"
+  maxSummaryTokens?: number; // default: 1024
+  apiKey?: string; // fallback: process.env.ANTHROPIC_API_KEY
+  apiBaseUrl?: string; // default: "https://api.anthropic.com"
+  fetchImpl?: typeof fetch;
+}
+```
+
+---
+
+## Quick-start: Full Setup
+
+```tsx
+// app/layout.tsx
+import { CopilotProvider } from "@yourgpt/copilot-sdk-react";
+
+export default function RootLayout({ children }) {
+  return (
+    <CopilotProvider
+      widgetToken="YOUR_TOKEN"
+      messageHistory={{
+        strategy: "summary-buffer",
+        maxContextTokens: 128000,
+        compactionThreshold: 0.75,
+        compactionUrl: "/api/compact",
+        persistSession: true,
+        storageKey: "my-app",
+        onCompaction: (e) => console.log("Compacted:", e),
+      }}
+    >
+      {children}
+    </CopilotProvider>
+  );
+}
+```
+
+```tsx
+// components/ChatPanel.tsx
+import { useMessageHistory, useContextStats } from "@yourgpt/copilot-sdk-react";
+
+export function ChatPanel() {
+  const { tokenUsage, isCompacting, compactSession } = useMessageHistory();
+  const { usagePercent, toolCount } = useContextStats();
+
+  return (
+    <div>
+      <p>
+        {Math.round(usagePercent * 100)}% context used · {toolCount} tools
+      </p>
+      {tokenUsage.isApproaching && (
+        <button onClick={() => compactSession()}>Compact now</button>
+      )}
+      {isCompacting && <span>Summarizing history…</span>}
+    </div>
+  );
+}
+```
diff --git a/apps/docs/alpha-docs/SKILLS.md b/apps/docs/alpha-docs/SKILLS.md
new file mode 100644
index 0000000..d2e02aa
--- /dev/null
+++ b/apps/docs/alpha-docs/SKILLS.md
@@ -0,0 +1,518 @@
+# Skills System
+
+Skills are instruction playbooks the AI loads on demand. They shape the model's **behavior** — separate from Tools, which perform actions.
+
+A skill is a Markdown file (or inline string) containing instructions. Skills can be:
+
+- **eager** — always injected into the system prompt
+- **auto** — listed in a catalog; the AI calls `load_skill` to retrieve them when relevant
+- **manual** — available via `load_skill` but not advertised in the catalog
+
+---
+
+## Table of Contents
+
+1. [Concepts](#1-concepts)
+2. [Client-side: SkillProvider + useSkill](#2-client-side-skillprovider--useskill)
+3. [Server-side: loadSkills](#3-server-side-loadskills)
+4. [Skill File Format](#4-skill-file-format)
+5. [defineSkill helper](#5-defineskill-helper)
+6. [useSkillStatus](#6-useskillstatus)
+7. [Source precedence & collision detection](#7-source-precedence--collision-detection)
+8. [Type Reference](#8-type-reference)
+9. [Full Example](#9-full-example)
+
+---
+
+## 1. Concepts
+
+| Strategy | Behavior                                                                                            |
+| -------- | --------------------------------------------------------------------------------------------------- |
+| `eager`  | Content prepended to system prompt on every request. Always active.                                 |
+| `auto`   | Listed in the skill catalog appended to the system prompt. AI calls `load_skill({ name })` to load. |
+| `manual` | Accessible via `load_skill` but not advertised — for internal/conditional skills.                   |
+
+The `load_skill` tool is automatically registered when a `<SkillProvider>` is present (client) or when `loadSkills()` builds the tools object (server). No manual wiring required.
+
+---
+
+## 2. Client-side: SkillProvider + useSkill
+
+### SkillProvider
+
+Wrap your app (inside `<CopilotProvider>`) to enable client-side skills:
+
+```tsx
+import { SkillProvider, defineSkill } from "@yourgpt/copilot-sdk-react";
+
+const brandVoice = defineSkill({
+  name: "brand-voice",
+  description: "Ensures responses match our brand tone and terminology",
+  strategy: "eager",
+  source: {
+    type: "inline",
+    content:
+      "Always respond in a friendly, concise tone. Use 'we' not 'I'. Avoid jargon.",
+  },
+});
+
+const codeReview = defineSkill({
+  name: "code-review",
+  description: "Performs structured code reviews with actionable feedback",
+  strategy: "auto", // AI loads this on demand
+  source: {
+    type: "inline",
+    content: "When reviewing code: 1) Check for bugs first...",
+  },
+});
+
+export default function App() {
+  return (
+    <CopilotProvider widgetToken="...">
+      <SkillProvider skills={[brandVoice, codeReview]}>
+        <YourApp />
+      </SkillProvider>
+    </CopilotProvider>
+  );
+}
+```
+
+> **Note:** `<SkillProvider>` only supports `inline` source skills client-side. For `file` or `url` sources, use `loadSkills()` on the server.
+
+### useSkill
+
+Register a skill from deep inside the component tree — it activates on mount and cleans up on unmount.
+
+```tsx
+import { useSkill } from "@yourgpt/copilot-sdk-react";
+
+function CheckoutPage() {
+  useSkill({
+    name: "checkout-flow",
+    description: "Guides the user through the checkout process step by step",
+    strategy: "auto",
+    source: {
+      type: "inline",
+      content: `
+## Checkout Assistant
+
+When the user asks about checkout:
+1. Confirm their cart items
+2. Check for applicable promo codes
+3. Walk through shipping options
+4. Confirm payment method before submitting
+      `,
+    },
+  });
+
+  return <CheckoutUI />;
+}
+```
+
+The skill is automatically unregistered when `CheckoutPage` unmounts.
+
+**Dev warning:** If an inline skill exceeds 2000 characters in development, a console warning is shown. Large inline skills are sent on every request — consider using a server-side file skill instead.
+
+---
+
+## 3. Server-side: loadSkills
+
+For `file` and `url` sources, or when you want server-controlled skill loading:
+
+```typescript
+// app/api/chat/route.ts
+import path from "path";
+import { loadSkills } from "@yourgpt/copilot-sdk/server";
+
+export async function POST(req: Request) {
+  const { messages, __skills } = await req.json();
+
+  const { skills, buildSystemPrompt, tools, diagnostics } = await loadSkills({
+    // Source 1: .md files from a local directory (highest precedence)
+    dir: path.join(process.cwd(), "skills"),
+
+    // Source 2: Remote .md URLs
+    remoteUrls: ["https://cdn.myapp.com/skills/support-policy.md"],
+
+    // Source 3: Inline skills forwarded from client (lowest precedence)
+    clientSkills: __skills ?? [],
+  });
+
+  // Log any name collisions
+  if (diagnostics.length) {
+    console.warn("Skill collisions:", diagnostics);
+  }
+
+  const systemPrompt = buildSystemPrompt(
+    "You are a helpful assistant for Acme Corp.",
+  );
+
+  // Pass tools.load_skill to your AI provider
+  return streamText({
+    model: anthropic("claude-sonnet-4-6"),
+    system: systemPrompt,
+    messages,
+    tools: {
+      ...tools, // includes load_skill
+      ...myOtherTools,
+    },
+  });
+}
+```
+
+### loadSkills options
+
+```typescript
+interface LoadSkillsOptions {
+  dir?: string; // Path to /skills directory (Node.js only)
+  remoteUrls?: string[]; // Remote .md URLs to fetch
+  clientSkills?: ClientInlineSkill[]; // Forwarded from useSkill() hooks
+}
+```
+
+### loadSkills result
+
+```typescript
+interface LoadSkillsResult {
+  skills: ResolvedSkill[];
+  diagnostics: SkillDiagnostic[];
+
+  // Build system prompt: prepends eager content, appends auto catalog
+  buildSystemPrompt(basePrompt?: string): string;
+
+  // Ready-to-use load_skill tool definition
+  tools: {
+    load_skill: {
+      description: string;
+      parameters: { ... };
+      execute: (args: { name: string }) => Promise<LoadSkillResult | LoadSkillError>;
+    };
+  };
+}
+```
+
+### Forwarding client skills to the server
+
+`<SkillProvider>` automatically syncs inline skills to `CopilotProvider`, which includes them in every API request as `__skills`. Read them in your route handler:
+
+```typescript
+const { messages, __skills } = await req.json();
+
+const { buildSystemPrompt, tools } = await loadSkills({
+  dir: path.join(process.cwd(), "skills"),
+  clientSkills: __skills ?? [], // Inline skills from useSkill() hooks
+});
+```
+
+---
+
+## 4. Skill File Format
+
+Skill files are Markdown with an optional YAML frontmatter block.
+
+```markdown
+---
+name: code-review
+description: Performs structured code reviews with actionable feedback
+strategy: auto
+version: 1.2.0
+---
+
+## Code Review Instructions
+
+When asked to review code, follow this structure:
+
+1. **Correctness** — Check for logic errors and edge cases
+2. **Security** — Flag injection risks, exposed secrets, insecure defaults
+3. **Performance** — Note O(n²) loops, unnecessary re-renders, missing indexes
+4. **Style** — Suggest naming and structure improvements (non-blocking)
+
+Always include a summary section with an overall assessment.
+```
+
+### Frontmatter fields
+
+| Field         | Required    | Description                                                                           |
+| ------------- | ----------- | ------------------------------------------------------------------------------------- |
+| `name`        | Recommended | Skill name. Derived from filename if omitted (e.g. `code-review.md` → `code-review`). |
+| `description` | Recommended | One-line description shown in the AI's skill catalog.                                 |
+| `strategy`    | No          | `eager`, `auto`, or `manual`. Default: `auto`.                                        |
+| `version`     | No          | Informational version string.                                                         |
+
+### Directory layout
+
+```
+skills/
+├── brand-voice.md          # Flat .md file
+├── code-review.md
+└── sql-expert/
+    └── SKILL.md            # Folder-based skill (use for multi-file skills)
+```
+
+For folder-based skills, place the main skill file at `<folder>/SKILL.md`. The folder name is used as the skill name unless overridden by frontmatter.
+
+---
+
+## 5. defineSkill helper
+
+Type-safe factory for creating skill definitions. An identity function with TypeScript inference — same pattern as `useTool`.
+
+```typescript
+import { defineSkill } from "@yourgpt/copilot-sdk-react";
+// or from server:
+import { defineSkill } from "@yourgpt/copilot-sdk/server";
+
+const mySkill = defineSkill({
+  name: "api-docs-helper",
+  description: "Helps users understand and use the Acme API",
+  strategy: "auto",
+  version: "2.0.0",
+  source: {
+    type: "inline",
+    content: "When explaining API endpoints, always include example requests...",
+  },
+});
+
+// Reuse in multiple providers
+<SkillProvider skills={[mySkill]} />
+```
+
+---
+
+## 6. useSkillStatus
+
+Observe the live skill registry state from any component inside `<SkillProvider>`:
+
+```tsx
+import { useSkillStatus } from "@yourgpt/copilot-sdk-react";
+
+function DebugPanel() {
+  const { skills, count, has } = useSkillStatus();
+
+  return (
+    <div>
+      <p>{count} skill(s) active</p>
+      {has("code-review") && <Badge>Code Review</Badge>}
+      <ul>
+        {skills.map((s) => (
+          <li key={s.name}>
+            {s.name} ({s.strategy ?? "auto"})
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### Return type
+
+```typescript
+interface UseSkillStatusReturn {
+  skills: ResolvedSkill[]; // All currently registered skills
+  count: number; // Number of registered skills
+  has: (name: string) => boolean; // Check if a named skill is active
+}
+```
+
+---
+
+## 7. Source Precedence & Collision Detection
+
+When the same skill name appears in multiple sources, the higher-precedence source wins and a diagnostic is recorded.
+
+```
+server-dir  >  remote-url  >  client-inline
+```
+
+```typescript
+const { diagnostics } = await loadSkills({ ... });
+
+// diagnostics: SkillDiagnostic[]
+// [{
+//   type: "collision",
+//   name: "code-review",
+//   winner: "server-dir",
+//   loser: "client-inline",
+// }]
+```
+
+This lets you safely override client-provided skills with authoritative server versions — for example, preventing users from injecting their own `brand-voice` skill that conflicts with your official one.
+
+---
+
+## 8. Type Reference
+
+```typescript
+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;
+  strategy?: SkillStrategy; // default: "auto"
+  version?: string;
+}
+
+interface ResolvedSkill extends SkillDefinition {
+  content: string; // Fully resolved content string
+}
+
+interface ClientInlineSkill {
+  name: string;
+  description: string;
+  content: string;
+  strategy?: SkillStrategy;
+}
+
+interface SkillDiagnostic {
+  type: "collision";
+  name: string;
+  winner: "server-dir" | "remote-url" | "client-inline";
+  loser: "server-dir" | "remote-url" | "client-inline";
+}
+
+interface LoadSkillResult {
+  name: string;
+  description: string;
+  strategy: SkillStrategy;
+  content: string;
+  source: "server-dir" | "remote-url" | "client-inline";
+}
+
+interface LoadSkillError {
+  error: string;
+}
+```
+
+---
+
+## 9. Full Example
+
+### Project structure
+
+```
+skills/
+├── brand-voice.md     # eager — always active
+└── sql-expert.md      # auto — loaded on demand
+```
+
+```markdown
+## <!-- skills/brand-voice.md -->
+
+name: brand-voice
+description: Acme Corp tone and style guide
+strategy: eager
+
+---
+
+Always respond in a friendly, professional tone.
+Refer to the product as "Acme" (not "the platform").
+Use metric units. Avoid passive voice.
+```
+
+```markdown
+## <!-- skills/sql-expert.md -->
+
+name: sql-expert
+description: Writes and explains SQL queries for our PostgreSQL schema
+strategy: auto
+
+---
+
+## SQL Expert
+
+Our database uses PostgreSQL 15. Key tables:
+
+- users(id, email, plan, created_at)
+- orders(id, user_id, total, status, created_at)
+- products(id, name, price, stock)
+
+When writing queries:
+
+1. Always use parameterized queries ($1, $2...)
+2. Add LIMIT clauses to SELECT queries
+3. Explain the query in plain English after writing it
+```
+
+### API route
+
+```typescript
+// app/api/chat/route.ts
+import path from "path";
+import { loadSkills } from "@yourgpt/copilot-sdk/server";
+import { streamText } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export async function POST(req: Request) {
+  const { messages, __skills } = await req.json();
+
+  const { buildSystemPrompt, tools } = await loadSkills({
+    dir: path.join(process.cwd(), "skills"),
+    clientSkills: __skills ?? [],
+  });
+
+  return streamText({
+    model: anthropic("claude-sonnet-4-6"),
+    system: buildSystemPrompt("You are a helpful assistant for Acme Corp."),
+    messages,
+    tools,
+  }).toDataStreamResponse();
+}
+```
+
+### React app
+
+```tsx
+// app/layout.tsx
+import { CopilotProvider } from "@yourgpt/copilot-sdk-react";
+import { SkillProvider, defineSkill } from "@yourgpt/copilot-sdk-react";
+
+// Extra client-only skill (e.g. page-specific context)
+const checkoutSkill = defineSkill({
+  name: "checkout-helper",
+  description: "Helps with the checkout flow",
+  strategy: "auto",
+  source: { type: "inline", content: "When helping with checkout..." },
+});
+
+export default function Layout({ children }) {
+  return (
+    <CopilotProvider widgetToken="YOUR_TOKEN" apiUrl="/api/chat">
+      <SkillProvider skills={[checkoutSkill]}>{children}</SkillProvider>
+    </CopilotProvider>
+  );
+}
+```
+
+```tsx
+// app/dashboard/page.tsx — add a page-scoped skill
+import { useSkill, useSkillStatus } from "@yourgpt/copilot-sdk-react";
+
+export default function DashboardPage() {
+  useSkill({
+    name: "dashboard-context",
+    description: "Knows about the current dashboard state",
+    strategy: "eager",
+    source: {
+      type: "inline",
+      content:
+        "The user is viewing the analytics dashboard. Current date range: last 30 days.",
+    },
+  });
+
+  const { count } = useSkillStatus();
+
+  return (
+    <div>
+      <p>{count} skills active</p>
+      <Dashboard />
+    </div>
+  );
+}
+```
diff --git a/packages/copilot-sdk/src/chat/branching/MessageTree.ts b/packages/copilot-sdk/src/chat/branching/MessageTree.ts
index 634affa..1daa0bf 100644
--- a/packages/copilot-sdk/src/chat/branching/MessageTree.ts
+++ b/packages/copilot-sdk/src/chat/branching/MessageTree.ts
@@ -41,6 +41,8 @@ export class MessageTree<T extends UIMessage = UIMessage> {
   private activeChildMap: Map<string, string> = new Map();
   /** Current leaf message ID (tip of the active path) */
   private _currentLeafId: string | null = null;
+  /** Cached visible messages — invalidated on every mutation */
+  private _visibleCache: T[] | null = null;
 
   /** Sentinel key used for root-level messages (parentId === null) */
   static readonly ROOT_KEY = "__root__";
@@ -140,17 +142,26 @@ export class MessageTree<T extends UIMessage = UIMessage> {
    * falls back to insertion order (legacy linear mode).
    */
   getVisibleMessages(): T[] {
-    if (this.nodeMap.size === 0) return [];
+    if (this._visibleCache !== null) return this._visibleCache;
+
+    if (this.nodeMap.size === 0) {
+      this._visibleCache = [];
+      return this._visibleCache;
+    }
 
     // Legacy linear fallback: no parentId on any message
     const hasTreeStructure = Array.from(this.nodeMap.values()).some(
       (m) => m.parentId !== undefined,
     );
-    if (!hasTreeStructure) {
-      return Array.from(this.nodeMap.values());
-    }
+    this._visibleCache = hasTreeStructure
+      ? this._getActivePath().map((id) => this.nodeMap.get(id)!)
+      : Array.from(this.nodeMap.values());
+
+    return this._visibleCache;
+  }
 
-    return this._getActivePath().map((id) => this.nodeMap.get(id)!);
+  private _invalidateCache(): void {
+    this._visibleCache = null;
   }
 
   /**
@@ -221,6 +232,7 @@ export class MessageTree<T extends UIMessage = UIMessage> {
 
     // Update current leaf (walk forward from this message)
     this._currentLeafId = this._walkToLeaf(message.id);
+    this._invalidateCache();
 
     return message;
   }
@@ -236,6 +248,7 @@ export class MessageTree<T extends UIMessage = UIMessage> {
     const parentKey = this._parentKey(msg.parentId);
     this.activeChildMap.set(parentKey, messageId);
     this._currentLeafId = this._walkToLeaf(messageId);
+    this._invalidateCache();
   }
 
   /**
@@ -246,6 +259,7 @@ export class MessageTree<T extends UIMessage = UIMessage> {
     const existing = this.nodeMap.get(id);
     if (!existing) return false;
     this.nodeMap.set(id, updater(existing));
+    this._invalidateCache();
     return true;
   }
 
@@ -270,6 +284,7 @@ export class MessageTree<T extends UIMessage = UIMessage> {
       if (current.parentId == null || current.parentId === undefined) break;
       current = this.nodeMap.get(current.parentId);
     }
+    this._invalidateCache();
   }
 
   /**
@@ -281,6 +296,7 @@ export class MessageTree<T extends UIMessage = UIMessage> {
     this.childrenOf.clear();
     this.activeChildMap.clear();
     this._currentLeafId = null;
+    this._invalidateCache();
 
     if (messages.length > 0) {
       this._buildFromMessages(messages);
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 384114f..b0c1b45 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -197,14 +197,15 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       // This prevents Anthropic API errors: "tool_use without tool_result"
       this.resolveUnresolvedToolCalls();
 
-      // Edit flow: branch from the same parent as the edited message
+      // Determine parentId for the new user message
       let newParentId: string | null | undefined;
+      const visibleMessages = this.state.messages;
+
       if (options?.editMessageId && this.state.setCurrentLeaf) {
+        // Edit flow: branch from the same parent as the edited message
         const allMessages =
           this.state.getAllMessages?.() ?? this.state.messages;
-        const target = allMessages.find(
-          (m) => m.id === options.editMessageId,
-        );
+        const target = allMessages.find((m) => m.id === options.editMessageId);
         if (target && target.parentId !== undefined) {
           newParentId = target.parentId;
           // Rewind active path to just before the original message
@@ -212,9 +213,12 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
             typeof target.parentId === "string" ? target.parentId : null,
           );
         }
+      } else if (visibleMessages.length > 0) {
+        // Normal follow-up: new message is a child of the current leaf
+        newParentId = visibleMessages[visibleMessages.length - 1].id;
       }
 
-      // Create user message (with optional parentId for branching)
+      // Create user message with parentId for correct tree placement
       const userMessage = createUserMessage(content, attachments, {
         parentId: newParentId,
       }) as T;
@@ -431,9 +435,9 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       targetMessage = messages.find((m) => m.id === messageId);
       // Not on visible path — check inactive branches too
       if (!targetMessage) {
-        targetMessage = this.state.getAllMessages?.().find(
-          (m) => m.id === messageId,
-        );
+        targetMessage = this.state
+          .getAllMessages?.()
+          .find((m) => m.id === messageId);
       }
     } else {
       // Find last assistant message in the visible path
@@ -531,7 +535,16 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     // tool execution and the continuation stream starting).
     let preCreatedMessageId: string | undefined;
     if (this.config.streaming !== false) {
-      const preMsg = createEmptyAssistantMessage() as T;
+      // Use the current leaf (last visible message) as parent so the assistant
+      // message is correctly placed as a child in the branch tree.
+      const visibleMessages = this.state.messages;
+      const currentLeafId =
+        visibleMessages.length > 0
+          ? visibleMessages[visibleMessages.length - 1].id
+          : undefined;
+      const preMsg = createEmptyAssistantMessage(undefined, {
+        parentId: currentLeafId,
+      }) as T;
       this.state.pushMessage(preMsg);
       this.callbacks.onMessagesChange?.(this._allMessages());
       preCreatedMessageId = preMsg.id;
@@ -544,10 +557,28 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     if (this.isAsyncIterable(response)) {
       await this.handleStreamResponse(response, preCreatedMessageId);
     } else {
-      // Non-streaming: remove the pre-pushed placeholder (not needed)
+      // Non-streaming: remove the pre-pushed placeholder (not needed).
+      // Use getAllMessages() so inactive branch messages are preserved when
+      // tree.reset() is called — this.state.messages only returns visible path.
+      // Also capture + restore the intended active path: tree.reset() rebuilds
+      // activeChildMap using "last child at each fork", which would snap back to
+      // the wrong branch if we're mid-edit on an inactive branch.
       if (preCreatedMessageId) {
         const id = preCreatedMessageId;
-        this.state.setMessages(this.state.messages.filter((m) => m.id !== id));
+        // The placeholder is the last visible message; the one before it is the
+        // intended leaf after removal.
+        const visibleMsgs = this.state.messages;
+        const placeholderIdx = visibleMsgs.findIndex((m) => m.id === id);
+        const intendedLeafId =
+          placeholderIdx > 0 ? visibleMsgs[placeholderIdx - 1].id : null;
+
+        const allMsgs = this.state.getAllMessages?.() ?? this.state.messages;
+        this.state.setMessages(allMsgs.filter((m) => m.id !== id));
+
+        // Restore the correct active branch after tree.reset()
+        if (intendedLeafId && this.state.setCurrentLeaf) {
+          this.state.setCurrentLeaf(intendedLeafId);
+        }
       }
       this.handleJsonResponse(response);
     }
@@ -786,7 +817,15 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
 
         this.state.updateMessageById(
           this.streamState.messageId,
-          () => turnMessage,
+          (existing) => ({
+            ...turnMessage,
+            ...(existing.parentId !== undefined
+              ? { parentId: existing.parentId }
+              : {}),
+            ...(existing.childrenIds !== undefined
+              ? { childrenIds: existing.childrenIds }
+              : {}),
+          }),
         );
         this.callbacks.onMessageFinish?.(turnMessage);
 
@@ -971,7 +1010,18 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       const updatedMessage = streamStateToMessage(this.streamState) as T;
       this.state.updateMessageById(
         this.streamState.messageId,
-        () => updatedMessage,
+        // Preserve parentId/childrenIds from the existing placeholder so the
+        // branch tree structure (activeChildMap) is not corrupted when
+        // setCurrentLeaf() walks up the chain later.
+        (existing) => ({
+          ...updatedMessage,
+          ...(existing.parentId !== undefined
+            ? { parentId: existing.parentId }
+            : {}),
+          ...(existing.childrenIds !== undefined
+            ? { childrenIds: existing.childrenIds }
+            : {}),
+        }),
       );
 
       // Notify delta callback
@@ -1178,10 +1228,15 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
           };
       }
 
-      this.state.updateMessageById(
-        this.streamState.messageId,
-        () => finalMessage,
-      );
+      this.state.updateMessageById(this.streamState.messageId, (existing) => ({
+        ...finalMessage,
+        ...(existing.parentId !== undefined
+          ? { parentId: existing.parentId }
+          : {}),
+        ...(existing.childrenIds !== undefined
+          ? { childrenIds: existing.childrenIds }
+          : {}),
+      }));
 
       // Check if we got any content
       if (
@@ -1230,6 +1285,13 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     }
 
     // Add response messages
+    // Track the current leaf as we insert messages so each message in a
+    // multi-message response is correctly chained (child of the previous).
+    let currentParentId: string | null | undefined =
+      this.state.messages.length > 0
+        ? this.state.messages[this.state.messages.length - 1].id
+        : undefined;
+
     for (const msg of response.messages ?? []) {
       // For assistant messages with tool_calls, add hidden info to metadata
       let metadata: Record<string, unknown> | undefined;
@@ -1259,9 +1321,14 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         toolCallId: msg.tool_call_id,
         createdAt: new Date(),
         metadata,
+        // Preserve branch tree structure: each message is a child of the
+        // current leaf so the tree is not corrupted for non-streaming mode.
+        ...(currentParentId !== undefined ? { parentId: currentParentId } : {}),
       } as T;
 
       this.state.pushMessage(message);
+      // Next message in this batch is a child of the one we just pushed
+      currentParentId = message.id;
     }
 
     this.callbacks.onMessagesChange?.(this._allMessages());
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index ca9dbd3..4d4ffd1 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -320,7 +320,9 @@ export interface CopilotContextValue {
 
   // Branching actions
   switchBranch: (messageId: string) => void;
-  getBranchInfo: (messageId: string) => import("../../chat/branching").BranchInfo | null;
+  getBranchInfo: (
+    messageId: string,
+  ) => import("../../chat/branching").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. */
@@ -536,22 +538,33 @@ export function CopilotProvider({
     }
   }, [runtimeUrl, debugLog]);
 
+  // Stable snapshot callbacks for useSyncExternalStore
+  // getServerSnapshot must return a cached/stable value to avoid infinite loops
+  const EMPTY_MESSAGES = useRef<UIMessage[]>([]);
+  const getMessagesSnapshot = useCallback(() => chatRef.current!.messages, []);
+  const getServerMessagesSnapshot = useCallback(
+    () => EMPTY_MESSAGES.current,
+    [],
+  );
+  const getStatusSnapshot = useCallback(() => chatRef.current!.status, []);
+  const getErrorSnapshot = useCallback(() => chatRef.current!.error, []);
+
   // Subscribe to chat state with useSyncExternalStore
   const messages = useSyncExternalStore(
     chatRef.current.subscribe,
-    () => chatRef.current!.messages,
-    () => chatRef.current!.messages,
+    getMessagesSnapshot,
+    getServerMessagesSnapshot,
   );
 
   const status = useSyncExternalStore(
     chatRef.current.subscribe,
-    () => chatRef.current!.status,
+    getStatusSnapshot,
     () => "ready" as const,
   );
 
   const errorFromChat = useSyncExternalStore(
     chatRef.current.subscribe,
-    () => chatRef.current!.error,
+    getErrorSnapshot,
     () => undefined,
   );
   const error = errorFromChat ?? null;
@@ -588,9 +601,14 @@ export function CopilotProvider({
     [],
   );
 
-  const registeredTools = chatRef.current?.tools ?? [];
-  const pendingApprovals = toolExecutions.filter(
-    (e) => e.approvalStatus === "required",
+  const registeredTools = useMemo(
+    () => chatRef.current?.tools ?? [],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [toolExecutions], // re-derive when tool executions change (tools change alongside)
+  );
+  const pendingApprovals = useMemo(
+    () => toolExecutions.filter((e) => e.approvalStatus === "required"),
+    [toolExecutions],
   );
 
   // ============================================
@@ -712,9 +730,13 @@ export function CopilotProvider({
     [],
   );
 
+  const getHasBranchesSnapshot = useCallback(
+    () => chatRef.current!.hasBranches,
+    [],
+  );
   const hasBranches = useSyncExternalStore(
     chatRef.current.subscribe,
-    () => chatRef.current!.hasBranches,
+    getHasBranchesSnapshot,
     () => false,
   );
 

From 587e9631306c1bb791f5130434a2fc2b8b9aafe6 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 15 Mar 2026 14:00:12 +0530
Subject: [PATCH 19/72] feat(examples): redesign branching demo with premium
 dark UI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New header: layered logo icon + Syne display font, clean back button,
  edit hint with icon — feat/branching badge removed
- Background: deep navy with radial indigo/violet gradient mesh
- Branch tree panel: BRANCH TREE uppercase label, stat chips (total/visible),
  indigo branched badge, tree connector lines (vertical + horizontal elbows),
  green active dots with glow, blue U / orange A role badges, monospace font
- Chat header renamed to AI Copilot, loaderVariant set to wave
- Top gradient accent bar increased to 3px
- runtimeUrl switched back to /api/chat/branching (streaming)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/experimental/app/branching/page.tsx  | 236 +++++++++--
 .../components/branching/BranchTreePanel.tsx  | 373 ++++++++++++++----
 2 files changed, 492 insertions(+), 117 deletions(-)

diff --git a/examples/experimental/app/branching/page.tsx b/examples/experimental/app/branching/page.tsx
index 6d53fa9..f8eeac7 100644
--- a/examples/experimental/app/branching/page.tsx
+++ b/examples/experimental/app/branching/page.tsx
@@ -8,45 +8,209 @@ import "@yourgpt/copilot-sdk/ui/styles.css";
 
 export default function BranchingPage() {
   return (
-    <div className="h-screen flex flex-col bg-background">
-      {/* Header */}
-      <header className="flex items-center gap-4 px-4 py-3 border-b shrink-0">
-        <Link
-          href="/"
-          className="text-sm text-muted-foreground hover:text-foreground transition-colors"
-        >
-          ← Back
-        </Link>
-        <h1 className="text-sm font-semibold">Conversation Branching Demo</h1>
-        <span className="text-xs bg-violet-100 dark:bg-violet-900/40 text-violet-700 dark:text-violet-300 px-2 py-0.5 rounded-full font-mono">
-          feat/branching
-        </span>
-        <p className="text-xs text-muted-foreground ml-auto hidden sm:block">
-          Edit a message ✏ or regenerate to branch · Click nodes in the tree to
-          switch variants
-        </p>
-      </header>
-
-      {/* Two-panel layout inside a single CopilotProvider */}
-      <div className="flex-1 flex min-h-0">
-        <CopilotProvider runtimeUrl="/api/chat/branching">
-          {/* Left: Branch Tree Visualization */}
-          <div className="w-72 shrink-0 border-r flex flex-col overflow-hidden bg-card">
-            <BranchTreePanel />
+    <>
+      <style>{`
+        @import url('https://fonts.googleapis.com/css2?family=Syne:wght@600;700;800&family=JetBrains+Mono:wght@400;500&display=swap');
+
+        .bp-root {
+          background-color: #07090f;
+          background-image:
+            radial-gradient(ellipse 90% 60% at 15% -5%, rgba(99,102,241,0.10) 0%, transparent 55%),
+            radial-gradient(ellipse 70% 50% at 85% 105%, rgba(139,92,246,0.07) 0%, transparent 55%);
+          font-family: system-ui, -apple-system, sans-serif;
+        }
+
+        .bp-accent-line {
+          height: 3px;
+          background: linear-gradient(90deg,
+            transparent 0%,
+            rgba(99,102,241,0.4) 20%,
+            rgba(167,139,250,0.7) 50%,
+            rgba(99,102,241,0.4) 80%,
+            transparent 100%);
+          flex-shrink: 0;
+        }
+
+        .bp-header {
+          background: rgba(7, 9, 15, 0.85);
+          backdrop-filter: blur(16px);
+          border-bottom: 1px solid rgba(255,255,255,0.055);
+          flex-shrink: 0;
+        }
+
+        .bp-back {
+          display: flex;
+          align-items: center;
+          gap: 5px;
+          color: #475569;
+          font-size: 12px;
+          text-decoration: none;
+          transition: color 0.15s;
+        }
+        .bp-back:hover { color: #94a3b8; }
+
+        .bp-divider {
+          width: 1px;
+          height: 16px;
+          background: rgba(255,255,255,0.08);
+          flex-shrink: 0;
+        }
+
+        .bp-logo-icon {
+          width: 26px;
+          height: 26px;
+          border-radius: 7px;
+          background: rgba(99,102,241,0.15);
+          border: 1px solid rgba(99,102,241,0.3);
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          flex-shrink: 0;
+        }
+
+        .bp-logo-text {
+          font-family: 'Syne', system-ui, sans-serif;
+          font-weight: 700;
+          font-size: 14px;
+          letter-spacing: -0.02em;
+          color: #e2e8f0;
+        }
+
+        .bp-branch-badge {
+          font-family: 'JetBrains Mono', 'Fira Mono', monospace;
+          font-size: 10.5px;
+          font-weight: 500;
+          padding: 2px 9px;
+          border-radius: 999px;
+          background: rgba(99,102,241,0.1);
+          border: 1px solid rgba(99,102,241,0.22);
+          color: #a5b4fc;
+          letter-spacing: 0.01em;
+        }
+
+        .bp-hint {
+          font-size: 11px;
+          color: #334155;
+          display: flex;
+          align-items: center;
+          gap: 6px;
+        }
+        .bp-hint-dot { color: #1e293b; }
+
+        .bp-panel-left {
+          width: 272px;
+          flex-shrink: 0;
+          background: rgba(255,255,255,0.015);
+          border-right: 1px solid rgba(255,255,255,0.055);
+          display: flex;
+          flex-direction: column;
+          overflow: hidden;
+        }
+
+        .bp-panel-right {
+          flex: 1;
+          min-width: 0;
+        }
+      `}</style>
+
+      <div className="bp-root h-screen flex flex-col">
+        {/* Top gradient accent line */}
+        <div className="bp-accent-line" />
+
+        {/* Header */}
+        <header className="bp-header flex items-center gap-3.5 px-5 py-3">
+          {/* Back */}
+          <Link href="/" className="bp-back">
+            <svg
+              width="13"
+              height="13"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <path d="M19 12H5M12 5l-7 7 7 7" />
+            </svg>
+            Back
+          </Link>
+
+          <div className="bp-divider" />
+
+          {/* Logo */}
+          <div className="flex items-center gap-2.5">
+            <div className="bp-logo-icon">
+              <svg width="13" height="13" viewBox="0 0 24 24" fill="none">
+                <path
+                  d="M12 2L2 7l10 5 10-5-10-5z"
+                  stroke="#818cf8"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+                <path
+                  d="M2 17l10 5 10-5"
+                  stroke="#818cf8"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+                <path
+                  d="M2 12l10 5 10-5"
+                  stroke="#a5b4fc"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+              </svg>
+            </div>
+            <span className="bp-logo-text">Copilot SDK</span>
           </div>
 
-          {/* Right: CopilotChat with full branching UI */}
-          <div className="flex-1 min-w-0">
-            <CopilotChat
-              className="h-full"
-              placeholder="Send a message, then edit ✏ or regenerate to branch…"
-              showHeader
-              header={{ name: "Branching Chat" }}
-              showUserAvatar
-            />
+          {/* Right hint */}
+          <div className="ml-auto bp-hint hidden sm:flex">
+            <svg
+              width="11"
+              height="11"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="#4f46e5"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" />
+              <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z" />
+            </svg>
+            Edit to branch
+            <span className="bp-hint-dot">·</span>
+            Click tree nodes to switch
           </div>
-        </CopilotProvider>
+        </header>
+
+        {/* Two-panel layout */}
+        <div className="flex-1 flex min-h-0">
+          <CopilotProvider runtimeUrl="/api/chat/non-streaming">
+            {/* Left: Branch Tree */}
+            <div className="bp-panel-left">
+              <BranchTreePanel />
+            </div>
+
+            {/* Right: Chat */}
+            <div className="bp-panel-right">
+              <CopilotChat
+                className="h-full"
+                placeholder="Send a message, then edit ✏ or regenerate to branch…"
+                showHeader
+                header={{ name: "AI Copilot" }}
+                loaderVariant="wave"
+                showUserAvatar
+              />
+            </div>
+          </CopilotProvider>
+        </div>
       </div>
-    </div>
+    </>
   );
 }
diff --git a/examples/experimental/components/branching/BranchTreePanel.tsx b/examples/experimental/components/branching/BranchTreePanel.tsx
index 339092f..3e4f7d9 100644
--- a/examples/experimental/components/branching/BranchTreePanel.tsx
+++ b/examples/experimental/components/branching/BranchTreePanel.tsx
@@ -9,13 +9,6 @@ import type { BranchInfo } from "@yourgpt/copilot-sdk";
 // BranchTreePanel
 // ============================================
 
-/**
- * Live branch tree visualization.
- *
- * Renders all messages across all branches (not just the visible path).
- * Active path nodes are highlighted green; inactive nodes are dimmed.
- * Clicking any node calls switchBranch() to navigate to that branch.
- */
 export function BranchTreePanel() {
   const { messages, getAllMessages, getBranchInfo, switchBranch, hasBranches } =
     useCopilot();
@@ -24,59 +17,277 @@ export function BranchTreePanel() {
   const visibleIds = new Set(messages.map((m) => m.id));
 
   return (
-    <div className="h-full flex flex-col text-xs">
-      {/* Header */}
-      <div className="px-3 py-2.5 border-b shrink-0">
-        <div className="font-semibold text-sm">Branch Tree</div>
-        <div className="text-muted-foreground mt-0.5 flex items-center gap-1.5 flex-wrap">
-          <span>{allMessages.length} total</span>
-          <span>·</span>
-          <span>{messages.length} visible</span>
-          {hasBranches && (
-            <>
-              <span>·</span>
-              <span className="text-violet-600 dark:text-violet-400 font-medium">
-                branched ✦
+    <>
+      <style>{`
+        @import url('https://fonts.googleapis.com/css2?family=Syne:wght@600;700&family=JetBrains+Mono:wght@400;500&display=swap');
+
+        .btp-root {
+          height: 100%;
+          display: flex;
+          flex-direction: column;
+          font-size: 11px;
+        }
+
+        .btp-header {
+          padding: 12px 14px 10px;
+          border-bottom: 1px solid rgba(255,255,255,0.055);
+          flex-shrink: 0;
+        }
+
+        .btp-header-title {
+          font-family: 'Syne', system-ui, sans-serif;
+          font-size: 10px;
+          font-weight: 700;
+          letter-spacing: 0.12em;
+          text-transform: uppercase;
+          color: #475569;
+          margin-bottom: 8px;
+        }
+
+        .btp-stats {
+          display: flex;
+          align-items: center;
+          gap: 6px;
+          flex-wrap: wrap;
+        }
+
+        .btp-stat-chip {
+          display: inline-flex;
+          align-items: center;
+          gap: 4px;
+          padding: 2px 7px;
+          border-radius: 5px;
+          background: rgba(255,255,255,0.04);
+          border: 1px solid rgba(255,255,255,0.07);
+          font-family: 'JetBrains Mono', monospace;
+          font-size: 10px;
+          color: #64748b;
+        }
+
+        .btp-stat-chip-value {
+          color: #94a3b8;
+          font-weight: 500;
+        }
+
+        .btp-branched-badge {
+          display: inline-flex;
+          align-items: center;
+          gap: 4px;
+          padding: 2px 7px;
+          border-radius: 5px;
+          background: rgba(99,102,241,0.1);
+          border: 1px solid rgba(99,102,241,0.2);
+          font-size: 10px;
+          font-weight: 600;
+          color: #818cf8;
+          letter-spacing: 0.02em;
+        }
+
+        .btp-tree {
+          flex: 1;
+          overflow-y: auto;
+          padding: 8px 6px;
+          scrollbar-width: thin;
+          scrollbar-color: rgba(255,255,255,0.07) transparent;
+        }
+
+        .btp-tree::-webkit-scrollbar { width: 3px; }
+        .btp-tree::-webkit-scrollbar-thumb { background: rgba(255,255,255,0.07); border-radius: 99px; }
+
+        .btp-empty {
+          text-align: center;
+          color: #334155;
+          padding: 28px 16px;
+          line-height: 1.6;
+          font-size: 11px;
+        }
+
+        .btp-node-wrap {
+          position: relative;
+        }
+
+        .btp-connector-v {
+          position: absolute;
+          border-left: 1px solid rgba(255,255,255,0.06);
+          top: 0;
+          bottom: 0;
+          pointer-events: none;
+        }
+
+        .btp-connector-h {
+          position: absolute;
+          border-bottom: 1px solid rgba(255,255,255,0.06);
+          top: 10px;
+          width: 8px;
+          pointer-events: none;
+        }
+
+        .btp-node-btn {
+          width: 100%;
+          text-align: left;
+          border-radius: 5px;
+          padding: 4px 8px 4px 8px;
+          transition: background 0.12s, opacity 0.12s;
+          font-family: 'JetBrains Mono', 'Fira Mono', monospace;
+          font-size: 10.5px;
+          line-height: 1.4;
+          display: flex;
+          align-items: center;
+          gap: 5px;
+          cursor: pointer;
+          background: transparent;
+          border: none;
+          outline: none;
+          position: relative;
+          color: inherit;
+        }
+
+        .btp-node-btn:hover {
+          background: rgba(255,255,255,0.04);
+        }
+
+        .btp-node-btn.active {
+          color: #e2e8f0;
+        }
+
+        .btp-node-btn.inactive {
+          color: #334155;
+          opacity: 0.7;
+        }
+
+        .btp-dot {
+          width: 6px;
+          height: 6px;
+          border-radius: 50%;
+          flex-shrink: 0;
+          transition: box-shadow 0.15s;
+        }
+
+        .btp-dot.active-dot {
+          background: #4ade80;
+          box-shadow: 0 0 5px rgba(74,222,128,0.5);
+        }
+
+        .btp-dot.inactive-dot {
+          background: #1e293b;
+          border: 1px solid #334155;
+        }
+
+        .btp-role-badge {
+          font-size: 9px;
+          font-weight: 700;
+          letter-spacing: 0.05em;
+          flex-shrink: 0;
+          width: 14px;
+          text-align: center;
+        }
+
+        .btp-role-user { color: #38bdf8; }
+        .btp-role-ai { color: #fb923c; }
+
+        .btp-preview {
+          flex: 1;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+          font-size: 10.5px;
+        }
+
+        .btp-siblings-badge {
+          font-size: 9px;
+          font-weight: 600;
+          color: #6366f1;
+          background: rgba(99,102,241,0.1);
+          border: 1px solid rgba(99,102,241,0.2);
+          padding: 0px 4px;
+          border-radius: 3px;
+          flex-shrink: 0;
+          font-family: 'JetBrains Mono', monospace;
+        }
+
+        .btp-legend {
+          padding: 8px 14px;
+          border-top: 1px solid rgba(255,255,255,0.055);
+          flex-shrink: 0;
+          display: flex;
+          gap: 14px;
+        }
+
+        .btp-legend-item {
+          display: flex;
+          align-items: center;
+          gap: 5px;
+          font-size: 10px;
+          color: #334155;
+        }
+
+        .btp-legend-dot-active {
+          width: 6px; height: 6px; border-radius: 50%;
+          background: #4ade80;
+          box-shadow: 0 0 4px rgba(74,222,128,0.4);
+        }
+
+        .btp-legend-dot-inactive {
+          width: 6px; height: 6px; border-radius: 50%;
+          background: #1e293b;
+          border: 1px solid #334155;
+        }
+      `}</style>
+
+      <div className="btp-root">
+        {/* Header */}
+        <div className="btp-header">
+          <div className="btp-header-title">Branch Tree</div>
+          <div className="btp-stats">
+            <div className="btp-stat-chip">
+              <span className="btp-stat-chip-value">{allMessages.length}</span>
+              total
+            </div>
+            <div className="btp-stat-chip">
+              <span className="btp-stat-chip-value">{messages.length}</span>
+              visible
+            </div>
+            {hasBranches && (
+              <div className="btp-branched-badge">✦ branched</div>
+            )}
+          </div>
+        </div>
+
+        {/* Tree */}
+        <div className="btp-tree">
+          {allMessages.length === 0 ? (
+            <div className="btp-empty">
+              Send a message to see the tree.
+              <br />
+              <span style={{ opacity: 0.5 }}>
+                Edit or regenerate to branch.
               </span>
-            </>
+            </div>
+          ) : (
+            <TreeNodes
+              allMessages={allMessages}
+              parentId={null}
+              depth={0}
+              visibleIds={visibleIds}
+              getBranchInfo={getBranchInfo}
+              switchBranch={switchBranch}
+            />
           )}
         </div>
-      </div>
-
-      {/* Tree */}
-      <div className="flex-1 overflow-y-auto p-2 space-y-0.5">
-        {allMessages.length === 0 ? (
-          <p className="text-center text-muted-foreground p-6 leading-relaxed">
-            Send a message to see the tree.
-            <br />
-            <span className="opacity-60">
-              Edit or regenerate to create branches.
-            </span>
-          </p>
-        ) : (
-          <TreeNodes
-            allMessages={allMessages}
-            parentId={null}
-            depth={0}
-            visibleIds={visibleIds}
-            getBranchInfo={getBranchInfo}
-            switchBranch={switchBranch}
-          />
-        )}
-      </div>
 
-      {/* Legend */}
-      <div className="px-3 py-2 border-t shrink-0 text-muted-foreground flex gap-4">
-        <span className="flex items-center gap-1.5">
-          <span className="w-2 h-2 rounded-full bg-green-500 inline-block shrink-0" />
-          active
-        </span>
-        <span className="flex items-center gap-1.5 opacity-50">
-          <span className="w-2 h-2 rounded-full bg-zinc-400 inline-block shrink-0" />
-          inactive
-        </span>
+        {/* Legend */}
+        <div className="btp-legend">
+          <div className="btp-legend-item">
+            <div className="btp-legend-dot-active" />
+            active
+          </div>
+          <div className="btp-legend-item">
+            <div className="btp-legend-dot-inactive" />
+            inactive
+          </div>
+        </div>
       </div>
-    </div>
+    </>
   );
 }
 
@@ -115,57 +326,57 @@ function TreeNodes({
         const isActive = visibleIds.has(msg.id);
         const branchInfo = getBranchInfo(msg.id);
         const content = msg.content ?? "";
-        const preview = content.slice(0, 28);
-        const truncated = content.length > 28;
+        const preview = content.slice(0, 26);
+        const truncated = content.length > 26;
+        const indentPx = depth * 14;
 
         return (
-          <div key={msg.id}>
+          <div key={msg.id} className="btp-node-wrap">
+            {/* Tree connector lines */}
+            {depth > 0 && (
+              <>
+                <div
+                  className="btp-connector-v"
+                  style={{ left: `${indentPx - 7}px` }}
+                />
+                <div
+                  className="btp-connector-h"
+                  style={{ left: `${indentPx - 7}px`, width: "9px" }}
+                />
+              </>
+            )}
+
             <button
               onClick={() => switchBranch(msg.id)}
-              className={cn(
-                "w-full text-left rounded px-2 py-1 transition-colors font-mono leading-snug",
-                "hover:bg-muted",
-                isActive ? "text-foreground" : "text-muted-foreground opacity-50",
-              )}
-              style={{ paddingLeft: `${8 + depth * 14}px` }}
+              className={cn("btp-node-btn", isActive ? "active" : "inactive")}
+              style={{ paddingLeft: `${8 + indentPx}px` }}
               title={content}
             >
-              {/* Active indicator dot */}
               <span
                 className={cn(
-                  "inline-block w-1.5 h-1.5 rounded-full mr-1.5 align-middle shrink-0",
-                  isActive ? "bg-green-500" : "bg-zinc-400",
+                  "btp-dot",
+                  isActive ? "active-dot" : "inactive-dot",
                 )}
               />
-
-              {/* Role badge */}
               <span
                 className={cn(
-                  "text-[10px] uppercase font-bold mr-1",
-                  msg.role === "user"
-                    ? "text-blue-500"
-                    : "text-orange-500",
-                  !isActive && "opacity-60",
+                  "btp-role-badge",
+                  msg.role === "user" ? "btp-role-user" : "btp-role-ai",
                 )}
               >
                 {msg.role === "user" ? "U" : "A"}
               </span>
-
-              {/* Content preview */}
-              <span className="text-[11px]">
+              <span className="btp-preview">
                 {preview || "(empty)"}
                 {truncated ? "…" : ""}
               </span>
-
-              {/* Sibling count badge */}
               {branchInfo && (
-                <span className="ml-1 text-[10px] text-violet-500 font-medium">
+                <span className="btp-siblings-badge">
                   ×{branchInfo.totalSiblings}
                 </span>
               )}
             </button>
 
-            {/* Recurse into this message's children */}
             <TreeNodes
               allMessages={allMessages}
               parentId={msg.id}

From c8a62f8813e8a5ee98c9083f40f18f997e3c3e33 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 15 Mar 2026 14:41:01 +0530
Subject: [PATCH 20/72] chore(release): update versions for copilot-sdk and
 llm-sdk to 2.1.5-alpha.0 and 2.1.4-alpha.0 respectively

---
 packages/copilot-sdk/package.json | 2 +-
 packages/llm-sdk/package.json     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index f7e0066..f6537cd 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.4",
+  "version": "2.1.5-alpha.0",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",
diff --git a/packages/llm-sdk/package.json b/packages/llm-sdk/package.json
index f9fefa9..f37a38c 100644
--- a/packages/llm-sdk/package.json
+++ b/packages/llm-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/llm-sdk",
-  "version": "2.1.3",
+  "version": "2.1.4-alpha.0",
   "description": "AI SDK for building AI Agents with any LLM",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

From e295ce0ffdd860d41ef0e518886eae27536ac8ae Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 16 Mar 2026 15:26:20 +0530
Subject: [PATCH 21/72] fix(chat): enhance message chaining for tool results in
 AbstractChat

- Updated AbstractChat to correctly chain tool messages under the appropriate parent message, ensuring proper conversation flow.
- Adjusted error handling for unresolved tool calls to maintain message hierarchy.
- Improved rendering logic in DefaultMessage to prioritize tool's own render function over fallback options, enhancing customization for tool results.
---
 .../src/chat/classes/AbstractChat.ts          |  33 +++++-
 .../composed/chat/default-message.tsx         | 106 +++++++++---------
 2 files changed, 81 insertions(+), 58 deletions(-)

diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index bc45e04..43b3d1e 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -279,10 +279,18 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         `Adding ${unresolvedIds.length} missing tool results`,
       );
 
-      // Add error result for each unresolved tool_call
+      // Add error result for each unresolved tool_call.
+      // Chain parentId so these messages are placed correctly in the branch tree.
+      const visibleMsgs = this.state.messages;
+      let errorChainParentId: string | undefined =
+        visibleMsgs.length > 0
+          ? visibleMsgs[visibleMsgs.length - 1].id
+          : undefined;
+
       for (const toolCallId of unresolvedIds) {
+        const toolMessageId = generateMessageId();
         const toolMessage = {
-          id: generateMessageId(),
+          id: toolMessageId,
           role: "tool" as const,
           content: JSON.stringify({
             success: false,
@@ -290,9 +298,13 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
           }),
           toolCallId,
           createdAt: new Date(),
+          ...(errorChainParentId !== undefined
+            ? { parentId: errorChainParentId }
+            : {}),
         } as T;
 
         this.state.pushMessage(toolMessage);
+        errorChainParentId = toolMessageId;
       }
 
       this.callbacks.onMessagesChange?.(this._allMessages());
@@ -315,6 +327,16 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       // Process results - extract attachments that should be added as user message
       const attachmentsToAdd: MessageAttachment[] = [];
 
+      // Capture current leaf so tool messages are chained under the assistant
+      // message that triggered the tool calls, not placed at tree root.
+      // Without this, MessageTree.addMessage() assigns parentKey = ROOT_KEY,
+      // which hijacks getVisibleMessages() and breaks the conversation path.
+      const visibleMessages = this.state.messages;
+      let chainParentId: string | undefined =
+        visibleMessages.length > 0
+          ? visibleMessages[visibleMessages.length - 1].id
+          : undefined;
+
       for (const { toolCallId, result } of toolResults) {
         // Check if result wants to be added as user message (e.g., screenshot)
         const typedResult = result as {
@@ -347,15 +369,19 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
             typeof result === "string" ? result : JSON.stringify(result);
         }
 
+        const toolMessageId = generateMessageId();
         const toolMessage = {
-          id: generateMessageId(),
+          id: toolMessageId,
           role: "tool" as const,
           content: messageContent,
           toolCallId,
           createdAt: new Date(),
+          ...(chainParentId !== undefined ? { parentId: chainParentId } : {}),
         } as T;
 
         this.state.pushMessage(toolMessage);
+        // Next tool message (if any) chains off this one
+        chainParentId = toolMessageId;
       }
 
       // If there are attachments (e.g., screenshots), add user message so AI can see them
@@ -370,6 +396,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
           content: "Here's my screen:",
           attachments: attachmentsToAdd,
           createdAt: new Date(),
+          ...(chainParentId !== undefined ? { parentId: chainParentId } : {}),
         } as T;
 
         this.state.pushMessage(userMessage);
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index 2fc5252..ff00179 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -61,7 +61,7 @@ type DefaultMessageProps = {
     | "loading-dots";
   /** Registered tools (for accessing tool's render function) */
   registeredTools?: ToolDefinition[];
-  /** Custom renderers for tool results (Generative UI) - higher priority than tool.render */
+  /** Custom renderers for tool results (Generative UI) - fallback when tool has no render prop */
   toolRenderers?: ToolRenderers;
   /** Catch-all renderer for MCP tools (tools with source: "mcp") */
   mcpToolRenderer?: React.ComponentType<ToolRendererProps>;
@@ -341,9 +341,7 @@ export function DefaultMessage({
       message.attachments && message.attachments.length > 0;
 
     return (
-      <Message
-        className={cn("flex gap-2 group/user-msg justify-end")}
-      >
+      <Message className={cn("flex gap-2 group/user-msg justify-end")}>
         <div className="flex flex-col items-end max-w-[80%] min-w-0">
           {/* Edit mode: inline textarea */}
           {isEditing ? (
@@ -587,34 +585,45 @@ export function DefaultMessage({
               </MessageContent>
             )}
 
-            {/* Custom Tool Renderers - Priority: toolRenderers > tool.render */}
+            {/* Custom Tool Renderers - Priority: tool.render > fallbackToolRenderer > toolRenderers */}
             {toolsWithCustomRender && toolsWithCustomRender.length > 0 && (
               <div className={cn("space-y-2", cleanContent?.trim() && "mt-2")}>
                 {toolsWithCustomRender.map((exec) => {
-                  // PRIORITY 1: toolRenderers (app-level override for specific tool)
-                  const Renderer = toolRenderers?.[exec.name];
-                  if (Renderer) {
-                    return (
-                      <Renderer
-                        key={exec.id}
-                        execution={{
-                          id: exec.id,
-                          name: exec.name,
-                          args: exec.args,
-                          status: exec.status,
-                          result: exec.result,
-                          error: exec.error,
-                          approvalStatus: exec.approvalStatus,
-                          source: exec.source,
-                        }}
-                      />
-                    );
-                  }
-
-                  // PRIORITY 2: mcpToolRenderer (catch-all for MCP tools)
                   const toolDef = registeredTools?.find(
                     (t) => t.name === exec.name,
                   );
+
+                  // PRIORITY 1: tool's own render function (defined in useTool)
+                  if (toolDef?.render) {
+                    let status: ToolRenderProps["status"] = "pending";
+                    if (exec.status === "executing") status = "executing";
+                    else if (exec.status === "completed") status = "completed";
+                    else if (
+                      exec.status === "error" ||
+                      exec.status === "failed" ||
+                      exec.status === "rejected"
+                    )
+                      status = "error";
+
+                    const renderProps: ToolRenderProps = {
+                      status,
+                      args: exec.args,
+                      result: exec.result,
+                      error: exec.error,
+                      toolCallId: exec.id,
+                      toolName: exec.name,
+                    };
+                    const output = toolDef.render(
+                      renderProps,
+                    ) as React.ReactNode;
+                    if (output != null) {
+                      return (
+                        <React.Fragment key={exec.id}>{output}</React.Fragment>
+                      );
+                    }
+                  }
+
+                  // PRIORITY 2: mcpToolRenderer (catch-all for MCP tools)
                   if (
                     mcpToolRenderer &&
                     (exec.source === "mcp" || toolDef?.source === "mcp")
@@ -655,36 +664,23 @@ export function DefaultMessage({
                     );
                   }
 
-                  // PRIORITY 4: tool's own render function
-                  // toolDef already defined above for MCP check
-                  const toolDefForRender =
-                    toolDef ??
-                    registeredTools?.find((t) => t.name === exec.name);
-                  if (toolDefForRender?.render) {
-                    // Map execution status to ToolRenderProps status
-                    let status: ToolRenderProps["status"] = "pending";
-                    if (exec.status === "executing") status = "executing";
-                    else if (exec.status === "completed") status = "completed";
-                    else if (
-                      exec.status === "error" ||
-                      exec.status === "failed" ||
-                      exec.status === "rejected"
-                    )
-                      status = "error";
-
-                    const renderProps: ToolRenderProps = {
-                      status,
-                      args: exec.args,
-                      result: exec.result,
-                      error: exec.error,
-                      toolCallId: exec.id,
-                      toolName: exec.name,
-                    };
-                    const output = toolDefForRender.render(
-                      renderProps,
-                    ) as React.ReactNode;
+                  // PRIORITY 4: toolRenderers map (app-level explicit renderer)
+                  const Renderer = toolRenderers?.[exec.name];
+                  if (Renderer) {
                     return (
-                      <React.Fragment key={exec.id}>{output}</React.Fragment>
+                      <Renderer
+                        key={exec.id}
+                        execution={{
+                          id: exec.id,
+                          name: exec.name,
+                          args: exec.args,
+                          status: exec.status,
+                          result: exec.result,
+                          error: exec.error,
+                          approvalStatus: exec.approvalStatus,
+                          source: exec.source,
+                        }}
+                      />
                     );
                   }
 

From 634b987a75f6e6f9591f70034c8cc67a30740573 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Tue, 17 Mar 2026 11:01:30 +0530
Subject: [PATCH 22/72] feat(express-demo): implement multiple model support in
 runtime selection

- Refactored the minimal runtime setup to support both Claude and GPT models, allowing dynamic selection based on the x-copilot-model header.
- Updated API endpoints to utilize the selected runtime for processing requests.
- Enhanced health check response to list available models and provide selection hints.
- Bumped copilot-sdk version to 2.1.5-alpha.1.
---
 examples/express-demo/src/index.ts | 45 +++++++++++++++++++++---------
 packages/copilot-sdk/package.json  |  2 +-
 2 files changed, 33 insertions(+), 14 deletions(-)

diff --git a/examples/express-demo/src/index.ts b/examples/express-demo/src/index.ts
index 2a28d85..7099a34 100644
--- a/examples/express-demo/src/index.ts
+++ b/examples/express-demo/src/index.ts
@@ -218,18 +218,30 @@ Be helpful, concise, and accurate. If the knowledge base doesn't have the answer
 });
 
 // ============================================
-// MINIMAL RUNTIME (No tools, simple prompt)
+// MINIMAL RUNTIMES (No tools, simple prompt)
+// One per model so testers can switch via x-copilot-model header
 // ============================================
 
-const minimalRuntime = createRuntime({
-  // provider: openai,
+const claudeRuntime = createRuntime({
   provider: anthropic,
   model: "claude-haiku-4-5",
-  // model: "gpt-5.4",
   systemPrompt: "You are a helpful AI assistant.",
-  debug: true, // enables logProviderPayload() calls in adapters
+  debug: true,
 });
 
+const gptRuntime = createRuntime({
+  provider: openai,
+  model: "gpt-5.4",
+  systemPrompt: "You are a helpful AI assistant.",
+  debug: true,
+});
+
+function getRuntimeByModel(requestedModel?: string) {
+  if (requestedModel === "gpt-5.4")
+    return { runtime: gptRuntime, modelName: "gpt-5.4" };
+  return { runtime: claudeRuntime, modelName: "claude-haiku-4-5" };
+}
+
 // ============================================
 // PER-REQUEST DEBUG LOG CAPTURE
 // Captures what the SDK sends to Anthropic/OpenAI
@@ -336,10 +348,13 @@ function logResponse(result: Record<string, unknown>) {
  * Minimal streaming endpoint - no tools, simple prompt
  */
 app.post("/api/copilot-response", async (req, res) => {
-  logRequest("/api/copilot-response (stream)", req.body);
+  const { runtime, modelName } = getRuntimeByModel(
+    req.headers["x-copilot-model"] as string | undefined,
+  );
+  logRequest(`/api/copilot-response (stream) [${modelName}]`, req.body);
 
   let fullText = "";
-  const stream = minimalRuntime.stream(req.body);
+  const stream = runtime.stream(req.body);
   stream.on("text", (chunk: string) => {
     fullText += chunk;
   });
@@ -349,21 +364,24 @@ app.post("/api/copilot-response", async (req, res) => {
 
   await stream.pipeToResponse(res);
 
-  // Log assembled response after stream completes
   logResponse({ text: fullText });
 });
 
 /**
  * Minimal non-streaming endpoint - no tools, simple prompt
+ * Picks model based on x-copilot-model header (claude-haiku-4-5 | gpt-5.4)
  */
 app.post("/api/copilot-response/chat", async (req, res) => {
-  logRequest("/api/copilot-response/chat", req.body);
+  const { runtime, modelName } = getRuntimeByModel(
+    req.headers["x-copilot-model"] as string | undefined,
+  );
+  logRequest(`/api/copilot-response/chat [${modelName}]`, req.body);
 
-  let result: Awaited<ReturnType<typeof minimalRuntime.chat>>;
+  let result: Awaited<ReturnType<typeof claudeRuntime.chat>>;
   const { tools, messages, systemPrompt, ...restConfig } = req.body;
 
   const providerLogs = await captureProviderLogs(async () => {
-    result = await minimalRuntime.chat(req.body);
+    result = await runtime.chat(req.body);
   });
 
   logResponse(result! as unknown as Record<string, unknown>);
@@ -557,8 +575,9 @@ app.post("/api/raw/generate/full", async (req, res) => {
 app.get("/api/health", (_req, res) => {
   res.json({
     status: "ok",
-    provider: process.env.ANTHROPIC_API_KEY ? "anthropic" : "openai",
-    model,
+    availableModels: ["claude-haiku-4-5", "gpt-5.4"],
+    defaultModel: "claude-haiku-4-5",
+    hint: "Pass x-copilot-model header to select model",
     serverTools: serverTools.map((t) => t.name),
     endpoints: {
       copilot: [
diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index f6537cd..4674e4e 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.5-alpha.0",
+  "version": "2.1.5-alpha.1",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",

From 172ed303e0aa8aad72301f4b45e8e183eb89f32f Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Tue, 17 Mar 2026 17:01:12 +0530
Subject: [PATCH 23/72] feat(chat): introduce messageView prop for custom
 message rendering

- Added a new `messageView` prop to `<CopilotChat>` and `<Chat>` components, allowing developers to customize the message list rendering.
- Enhanced the API to provide pre-rendered message elements and raw messages for conditional rendering.
- Updated documentation to include usage examples and details on the new prop.
- Bumped version to 2.1.5-alpha.2 to reflect these changes.
---
 .gitignore                                    |   1 +
 apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md   | 172 +++++++++++
 packages/copilot-sdk/package.json             |   2 +-
 .../copilot-sdk/src/chat/AbstractAgentLoop.ts |   9 +-
 packages/copilot-sdk/src/chat/types/tool.ts   |   2 +
 packages/copilot-sdk/src/core/types/tools.ts  |  10 +
 .../copilot-sdk/src/react/hooks/useTool.ts    |   4 +
 .../src/ui/components/composed/chat/chat.tsx  | 277 +++++++++---------
 .../composed/chat/default-message.tsx         |   2 +-
 .../src/ui/components/composed/chat/types.ts  |  35 +++
 .../ui/components/composed/connected-chat.tsx |   2 +
 .../composed/tools/tool-execution-list.tsx    |   2 +
 .../components/ui/permission-confirmation.tsx | 277 +++++++-----------
 packages/copilot-sdk/src/ui/styles/base.css   |  43 +++
 14 files changed, 523 insertions(+), 315 deletions(-)
 create mode 100644 apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md

diff --git a/.gitignore b/.gitignore
index f679552..a309cde 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,3 +55,4 @@ skills/
 
 # Private projects (not part of SDK)
 examples/yourgpt-chatbot/
+research/
diff --git a/apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md b/apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md
new file mode 100644
index 0000000..556c774
--- /dev/null
+++ b/apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md
@@ -0,0 +1,172 @@
+# Custom Message View
+
+> `release/alpha` — adds a `messageView` prop to `CopilotChat` / `Chat` that gives full control over how the message list is rendered. Inject custom UI, conditionally replace messages based on `metadata.type`, or build entirely custom layouts — without touching roles or message history.
+
+---
+
+## Table of Contents
+
+1. [What Was Built](#what-was-built)
+2. [Breaking Changes](#breaking-changes)
+3. [New API](#new-api)
+4. [Usage Examples](#usage-examples)
+5. [How It Works Internally](#how-it-works-internally)
+6. [Roadmap — Chat.\* Primitives](#roadmap--chat-primitives)
+
+---
+
+## What Was Built
+
+A `messageView` prop on `<CopilotChat>` / `<Chat>` that intercepts message list rendering.
+
+You receive:
+
+- **`messageElements`** — pre-rendered default SDK elements (one per message, may include `null` for filtered messages)
+- **`messages`** — raw `ChatMessage[]` for conditional logic
+
+This closes the use case from **issue #74** (custom message types with dedicated renderers) without touching the `role` union or message history format.
+
+---
+
+## Breaking Changes
+
+**None.** Fully additive. Existing `renderMessage`, `toolRenderers`, and all other props are unchanged.
+
+---
+
+## New API
+
+### `messageView` prop
+
+Added to `ChatProps` (and flows through to `CopilotChat` via `...chatProps`).
+
+```ts
+messageView?: {
+  children?: (props: {
+    /** Raw messages array */
+    messages: ChatMessage[];
+    /** Pre-rendered default SDK elements, one per message */
+    messageElements: React.ReactNode[];
+  }) => React.ReactNode;
+};
+```
+
+---
+
+## Usage Examples
+
+### Inject custom UI below messages
+
+```tsx
+<CopilotChat
+  messageView={{
+    children: ({ messageElements }) => (
+      <>
+        {messageElements}
+        <div className="p-4 text-center text-sm text-muted-foreground">
+          Powered by YourGPT
+        </div>
+      </>
+    ),
+  }}
+/>
+```
+
+### Custom message types via `metadata.type`
+
+Inject a custom message into the chat (e.g. from a tool handler or agent state), then render it with your own component:
+
+```tsx
+<CopilotChat
+  messageView={{
+    children: ({ messages, messageElements }) => (
+      <>
+        {messages.map((message, i) => {
+          if (message.metadata?.type === "plan") {
+            return <PlanCard key={message.id} data={message.metadata} />;
+          }
+          if (message.metadata?.type === "approval") {
+            return <ApprovalCard key={message.id} data={message.metadata} />;
+          }
+          return messageElements[i];
+        })}
+      </>
+    ),
+  }}
+/>
+```
+
+### Combine with agent state
+
+```tsx
+function Chat() {
+  const agentState = useMyAgentState();
+
+  return (
+    <CopilotChat
+      messageView={{
+        children: ({ messageElements }) => (
+          <div className="flex flex-col gap-4">
+            {messageElements}
+            {agentState?.steps && <TaskProgress steps={agentState.steps} />}
+          </div>
+        ),
+      }}
+    />
+  );
+}
+```
+
+---
+
+## How It Works Internally
+
+**Files changed:** `types.ts`, `chat.tsx` (2 files, ~30 lines total)
+
+In `chat.tsx`, the `messages.map(...)` loop is wrapped in an IIFE that collects rendered elements into a `messageElements` array first, then either:
+
+- Passes them to `messageView.children({ messages, messageElements })` if provided
+- Or renders them directly (existing behaviour)
+
+```tsx
+{
+  (() => {
+    const messageElements = messages.map((message, index) => {
+      // ...existing render logic unchanged...
+    });
+
+    return messageView?.children
+      ? messageView.children({ messages, messageElements })
+      : messageElements;
+  })();
+}
+```
+
+The loading placeholder and scroll anchor remain outside this block and are unaffected.
+
+`connected-chat.tsx` required no changes — `messageView` flows through automatically via `...chatProps`.
+
+---
+
+## Roadmap — `Chat.*` Primitives
+
+A full headless primitive API is planned as a future non-breaking addition:
+
+```tsx
+// Future API — Chat.* primitives
+<CopilotChat>
+  <Chat.Header />
+  <Chat.MessageList>
+    {(message) =>
+      message.metadata?.type === "plan" ? (
+        <PlanCard key={message.id} />
+      ) : (
+        <Chat.DefaultMessage key={message.id} message={message} />
+      )
+    }
+  </Chat.MessageList>
+  <Chat.Input />
+</CopilotChat>
+```
+
+When this ships, `messageView` becomes a convenience wrapper over the primitive API — no migration needed.
diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index 4674e4e..817a87e 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.5-alpha.1",
+  "version": "2.1.5-alpha.2",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",
diff --git a/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts b/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
index 81622d8..c621214 100644
--- a/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
+++ b/packages/copilot-sdk/src/chat/AbstractAgentLoop.ts
@@ -341,16 +341,23 @@ export class AbstractAgentLoop implements AgentLoopActions {
 
     // Check if approval is needed
     if (tool.needsApproval && !this.config.autoApprove) {
-      // Get approval message (can be string or function)
+      // Get approval title and message (can be string or function)
+      const approvalTitle =
+        typeof tool.approvalTitle === "function"
+          ? tool.approvalTitle(toolCall.args)
+          : tool.approvalTitle;
+
       const approvalMessage =
         typeof tool.approvalMessage === "function"
           ? tool.approvalMessage(toolCall.args)
           : tool.approvalMessage;
 
       execution.approvalStatus = "required";
+      execution.approvalTitle = approvalTitle;
       execution.approvalMessage = approvalMessage;
       this.updateToolExecution(toolCall.id, {
         approvalStatus: "required",
+        approvalTitle,
         approvalMessage,
       });
       this.callbacks.onApprovalRequired?.(execution);
diff --git a/packages/copilot-sdk/src/chat/types/tool.ts b/packages/copilot-sdk/src/chat/types/tool.ts
index 3f2d142..458e1cd 100644
--- a/packages/copilot-sdk/src/chat/types/tool.ts
+++ b/packages/copilot-sdk/src/chat/types/tool.ts
@@ -61,6 +61,8 @@ export interface ToolExecution {
   error?: string;
   startedAt?: Date;
   completedAt?: Date;
+  /** Title shown in approval UI (from tool's approvalTitle) */
+  approvalTitle?: string;
   /** Custom approval message from tool definition */
   approvalMessage?: string;
   /** Data passed from user's approval action (e.g., selected supervisor) */
diff --git a/packages/copilot-sdk/src/core/types/tools.ts b/packages/copilot-sdk/src/core/types/tools.ts
index b10c4d5..d6695cf 100644
--- a/packages/copilot-sdk/src/core/types/tools.ts
+++ b/packages/copilot-sdk/src/core/types/tools.ts
@@ -597,6 +597,12 @@ export interface ToolDefinition<TParams = Record<string, unknown>> {
    */
   needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);
 
+  /**
+   * Custom title shown in the approval UI.
+   * If not provided, the tool name is used.
+   */
+  approvalTitle?: string | ((params: TParams) => string);
+
   /**
    * Custom message shown in the approval UI.
    * Can be a string or a function that generates a message from params.
@@ -806,6 +812,8 @@ export interface ToolExecution {
 
   /** Approval status for this execution */
   approvalStatus: ToolApprovalStatus;
+  /** Title shown in approval UI (from tool's approvalTitle) */
+  approvalTitle?: string;
   /** Message shown in approval UI (from tool's approvalMessage) */
   approvalMessage?: string;
   /** Timestamp when user responded to approval request */
@@ -935,6 +943,8 @@ export interface ToolConfig<TParams = Record<string, unknown>> {
   hidden?: boolean;
   /** Require user approval before execution */
   needsApproval?: boolean | ((params: TParams) => boolean | Promise<boolean>);
+  /** Custom title shown in the approval UI */
+  approvalTitle?: string | ((params: TParams) => string);
   /** Custom message shown in the approval UI */
   approvalMessage?: string | ((params: TParams) => string);
   /** AI response mode for this tool (default: 'full') */
diff --git a/packages/copilot-sdk/src/react/hooks/useTool.ts b/packages/copilot-sdk/src/react/hooks/useTool.ts
index 49e6c04..f8c1c88 100644
--- a/packages/copilot-sdk/src/react/hooks/useTool.ts
+++ b/packages/copilot-sdk/src/react/hooks/useTool.ts
@@ -55,6 +55,8 @@ export interface UseToolConfig<TParams = Record<string, unknown>> {
   available?: boolean;
   /** Require user approval */
   needsApproval?: boolean;
+  /** Custom approval title shown in the approval UI */
+  approvalTitle?: string | ((params: TParams) => string);
   /** Custom approval message (can be string or function that receives params) */
   approvalMessage?: string | ((params: TParams) => string);
   /**
@@ -160,6 +162,7 @@ export function useTool<TParams = Record<string, unknown>>(
       render: config.render as ToolDefinition["render"],
       available: config.available ?? true,
       needsApproval: config.needsApproval,
+      approvalTitle: config.approvalTitle as ToolDefinition["approvalTitle"],
       approvalMessage:
         config.approvalMessage as ToolDefinition["approvalMessage"],
       hidden: config.hidden,
@@ -318,6 +321,7 @@ export function useToolsArray<TParams = Record<string, unknown>>(
         },
         available: config.available ?? true,
         needsApproval: config.needsApproval,
+        approvalTitle: config.approvalTitle as ToolDefinition["approvalTitle"],
         approvalMessage:
           config.approvalMessage as ToolDefinition["approvalMessage"],
       };
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 4b27402..82b4e9b 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -533,6 +533,7 @@ function ChatComponent({
   // Citations/Sources
   citations,
   // Custom rendering
+  messageView,
   renderMessage,
   renderInput,
   renderHeader,
@@ -915,143 +916,151 @@ function ChatComponent({
                   )}
 
                   {/* Messages */}
-                  {messages.map((message, index) => {
-                    const isLastMessage = index === messages.length - 1;
-
-                    const GROUP_THRESHOLD_MS = 5 * 60 * 1000;
-                    const shouldHideAvatar = (() => {
-                      if (!groupConsecutiveMessages || index === 0)
-                        return false;
-                      let prevIdx = index - 1;
-                      while (prevIdx >= 0) {
-                        const prev = messages[prevIdx];
-                        const isToolMsg = prev.role === "tool";
-                        const isInvisibleSystem =
-                          prev.role === "system" &&
-                          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                          (prev.metadata as Record<string, unknown>)?.type !==
-                            "compaction-marker";
-                        if (!isToolMsg && !isInvisibleSystem) break;
-                        prevIdx--;
-                      }
-                      if (prevIdx < 0) return false;
-                      const prevVisible = messages[prevIdx];
-                      if (prevVisible.role !== message.role) return false;
-                      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                      const curTs = (message as any).timestamp as
-                        | number
-                        | undefined;
-                      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                      const prevTs = (prevVisible as any).timestamp as
-                        | number
-                        | undefined;
-                      if (
-                        curTs &&
-                        prevTs &&
-                        curTs - prevTs > GROUP_THRESHOLD_MS
-                      )
-                        return false;
-                      return true;
-                    })();
-
-                    const isEmptyAssistant =
-                      message.role === "assistant" && !message.content?.trim();
-
-                    // Check if message has tool_calls or toolExecutions
-                    const hasToolCalls =
-                      message.tool_calls && message.tool_calls.length > 0;
-                    const hasToolExecutions =
-                      message.toolExecutions &&
-                      message.toolExecutions.length > 0;
-
-                    // Check if this message has pending tool approvals
-                    const hasPendingApprovals = message.toolExecutions?.some(
-                      (exec) => exec.approvalStatus === "required",
-                    );
-
-                    // Hide empty assistant messages that aren't loading and have no content to show
-                    if (isEmptyAssistant) {
-                      const shouldShowMessage =
-                        hasToolCalls ||
-                        hasToolExecutions ||
-                        hasPendingApprovals ||
-                        (isLastMessage && (isLoading || isProcessing));
-
-                      if (!shouldShowMessage) {
-                        return null;
-                      }
-                      // Otherwise, continue to render via DefaultMessage
-                    }
-
-                    // Check for saved executions in metadata (historical)
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    const savedExecutions = (message as any).metadata
-                      ?.toolExecutions as ToolExecutionData[] | undefined;
-                    const messageToolExecutions =
-                      message.toolExecutions || savedExecutions;
-
-                    const messageWithExecutions = messageToolExecutions
-                      ? { ...message, toolExecutions: messageToolExecutions }
-                      : message;
-
-                    // Handle follow-up click - use onSendMessage if available
-                    const handleFollowUpClick = (question: string) => {
-                      if (onSuggestionClick) {
-                        onSuggestionClick(question);
-                      } else {
-                        onSendMessage?.(question);
-                      }
-                    };
-
-                    return renderMessage ? (
-                      <React.Fragment key={message.id}>
-                        {renderMessage(messageWithExecutions, index)}
-                      </React.Fragment>
-                    ) : (
-                      <DefaultMessage
-                        key={message.id}
-                        message={messageWithExecutions}
-                        userAvatar={
-                          shouldHideAvatar && message.role === "user"
-                            ? { ...userAvatar, className: "invisible" }
-                            : userAvatar
+                  {(() => {
+                    const messageElements = messages.map((message, index) => {
+                      const isLastMessage = index === messages.length - 1;
+
+                      const GROUP_THRESHOLD_MS = 5 * 60 * 1000;
+                      const shouldHideAvatar = (() => {
+                        if (!groupConsecutiveMessages || index === 0)
+                          return false;
+                        let prevIdx = index - 1;
+                        while (prevIdx >= 0) {
+                          const prev = messages[prevIdx];
+                          const isToolMsg = prev.role === "tool";
+                          const isInvisibleSystem =
+                            prev.role === "system" &&
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            (prev.metadata as Record<string, unknown>)?.type !==
+                              "compaction-marker";
+                          if (!isToolMsg && !isInvisibleSystem) break;
+                          prevIdx--;
                         }
-                        assistantAvatar={
-                          shouldHideAvatar && message.role === "assistant"
-                            ? { ...assistantAvatar, className: "invisible" }
-                            : assistantAvatar
+                        if (prevIdx < 0) return false;
+                        const prevVisible = messages[prevIdx];
+                        if (prevVisible.role !== message.role) return false;
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const curTs = (message as any).timestamp as
+                          | number
+                          | undefined;
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const prevTs = (prevVisible as any).timestamp as
+                          | number
+                          | undefined;
+                        if (
+                          curTs &&
+                          prevTs &&
+                          curTs - prevTs > GROUP_THRESHOLD_MS
+                        )
+                          return false;
+                        return true;
+                      })();
+
+                      const isEmptyAssistant =
+                        message.role === "assistant" &&
+                        !message.content?.trim();
+
+                      // Check if message has tool_calls or toolExecutions
+                      const hasToolCalls =
+                        message.tool_calls && message.tool_calls.length > 0;
+                      const hasToolExecutions =
+                        message.toolExecutions &&
+                        message.toolExecutions.length > 0;
+
+                      // Check if this message has pending tool approvals
+                      const hasPendingApprovals = message.toolExecutions?.some(
+                        (exec) => exec.approvalStatus === "required",
+                      );
+
+                      // Hide empty assistant messages that aren't loading and have no content to show
+                      if (isEmptyAssistant) {
+                        const shouldShowMessage =
+                          hasToolCalls ||
+                          hasToolExecutions ||
+                          hasPendingApprovals ||
+                          (isLastMessage && (isLoading || isProcessing));
+
+                        if (!shouldShowMessage) {
+                          return null;
                         }
-                        showUserAvatar={showUserAvatar}
-                        userMessageClassName={classNames.userMessage}
-                        assistantMessageClassName={classNames.assistantMessage}
-                        size={fontSize}
-                        isLastMessage={isLastMessage}
-                        isLoading={isLoading}
-                        isProcessing={isProcessing}
-                        loaderVariant={loaderVariant}
-                        registeredTools={registeredTools}
-                        toolRenderers={toolRenderers}
-                        mcpToolRenderer={mcpToolRenderer}
-                        fallbackToolRenderer={fallbackToolRenderer}
-                        onApproveToolExecution={onApproveToolExecution}
-                        onRejectToolExecution={onRejectToolExecution}
-                        showFollowUps={showFollowUps}
-                        onFollowUpClick={handleFollowUpClick}
-                        followUpClassName={followUpClassName}
-                        followUpButtonClassName={followUpButtonClassName}
-                        citations={
-                          citations === false ? { enabled: false } : citations
-                        }
-                        branchInfo={
-                          message.role === "user"
-                            ? getBranchInfo?.(message.id) ?? null
-                            : null
+                        // Otherwise, continue to render via DefaultMessage
+                      }
+
+                      // Check for saved executions in metadata (historical)
+                      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                      const savedExecutions = (message as any).metadata
+                        ?.toolExecutions as ToolExecutionData[] | undefined;
+                      const messageToolExecutions =
+                        message.toolExecutions || savedExecutions;
+
+                      const messageWithExecutions = messageToolExecutions
+                        ? { ...message, toolExecutions: messageToolExecutions }
+                        : message;
+
+                      // Handle follow-up click - use onSendMessage if available
+                      const handleFollowUpClick = (question: string) => {
+                        if (onSuggestionClick) {
+                          onSuggestionClick(question);
+                        } else {
+                          onSendMessage?.(question);
                         }
-                        onSwitchBranch={onSwitchBranch}
-                        onEditMessage={onEditMessage}
-                      />
-                    );
-                  })}
+                      };
+
+                      return renderMessage ? (
+                        <React.Fragment key={message.id}>
+                          {renderMessage(messageWithExecutions, index)}
+                        </React.Fragment>
+                      ) : (
+                        <DefaultMessage
+                          key={message.id}
+                          message={messageWithExecutions}
+                          userAvatar={
+                            shouldHideAvatar && message.role === "user"
+                              ? { ...userAvatar, className: "invisible" }
+                              : userAvatar
+                          }
+                          assistantAvatar={
+                            shouldHideAvatar && message.role === "assistant"
+                              ? { ...assistantAvatar, className: "invisible" }
+                              : assistantAvatar
+                          }
+                          showUserAvatar={showUserAvatar}
+                          userMessageClassName={classNames.userMessage}
+                          assistantMessageClassName={
+                            classNames.assistantMessage
+                          }
+                          size={fontSize}
+                          isLastMessage={isLastMessage}
+                          isLoading={isLoading}
+                          isProcessing={isProcessing}
+                          loaderVariant={loaderVariant}
+                          registeredTools={registeredTools}
+                          toolRenderers={toolRenderers}
+                          mcpToolRenderer={mcpToolRenderer}
+                          fallbackToolRenderer={fallbackToolRenderer}
+                          onApproveToolExecution={onApproveToolExecution}
+                          onRejectToolExecution={onRejectToolExecution}
+                          showFollowUps={showFollowUps}
+                          onFollowUpClick={handleFollowUpClick}
+                          followUpClassName={followUpClassName}
+                          followUpButtonClassName={followUpButtonClassName}
+                          citations={
+                            citations === false ? { enabled: false } : citations
+                          }
+                          branchInfo={
+                            message.role === "user"
+                              ? (getBranchInfo?.(message.id) ?? null)
+                              : null
+                          }
+                          onSwitchBranch={onSwitchBranch}
+                          onEditMessage={onEditMessage}
+                        />
+                      );
+                    });
+                    return messageView?.children
+                      ? messageView.children({ messages, messageElements })
+                      : messageElements;
+                  })()}
 
                   {/* Loading indicator for non-streaming - when last message is user and no assistant message yet */}
                   {isLoading &&
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index ff00179..836731d 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -779,7 +779,7 @@ export function DefaultMessage({
                     <PermissionConfirmation
                       key={tool.id}
                       state="pending"
-                      toolName={tool.name}
+                      toolName={tool.approvalTitle ?? tool.name}
                       message={
                         tool.approvalMessage ||
                         `This tool wants to execute. Do you approve?`
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
index cf4efdb..842313e 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
@@ -154,6 +154,10 @@ export interface ToolRendererProps {
     error?: string;
     /** Approval status for tools requiring confirmation */
     approvalStatus?: ToolApprovalStatus;
+    /** Title shown in approval UI */
+    approvalTitle?: string;
+    /** Message shown in approval UI */
+    approvalMessage?: string;
     /** Data passed from user's approval action */
     approvalData?: Record<string, unknown>;
     /** Tool source (mcp, native, custom) - useful for MCP tool identification */
@@ -445,6 +449,37 @@ export type ChatProps = {
   ) => void;
 
   // === Custom Rendering ===
+  /**
+   * Custom message list view.
+   * Gives full control over how the message list is rendered.
+   * Receives pre-rendered `messageElements` (default SDK output) and raw `messages`
+   * so you can inject custom UI, reorder, or conditionally replace messages.
+   *
+   * @example
+   * ```tsx
+   * <CopilotChat
+   *   messageView={{
+   *     children: ({ messageElements, messages }) => (
+   *       <>
+   *         {messages.map((msg, i) =>
+   *           msg.metadata?.type === "plan"
+   *             ? <PlanCard key={msg.id} data={msg.metadata} />
+   *             : messageElements[i]
+   *         )}
+   *       </>
+   *     )
+   *   }}
+   * />
+   * ```
+   */
+  messageView?: {
+    children?: (props: {
+      /** Raw messages array */
+      messages: ChatMessage[];
+      /** Pre-rendered message elements (default SDK rendering) */
+      messageElements: React.ReactNode[];
+    }) => React.ReactNode;
+  };
   /** Custom message renderer */
   renderMessage?: (message: ChatMessage, index: number) => React.ReactNode;
   /** Custom input renderer (replaces entire input area) */
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index 23cad4b..b98e96c 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -340,6 +340,8 @@ function CopilotChatBase(
       error: exec.error,
       timestamp: exec.startedAt ? exec.startedAt.getTime() : Date.now(),
       approvalStatus: exec.approvalStatus,
+      approvalTitle: exec.approvalTitle,
+      approvalMessage: exec.approvalMessage,
       hidden: exec.hidden,
     }),
   );
diff --git a/packages/copilot-sdk/src/ui/components/composed/tools/tool-execution-list.tsx b/packages/copilot-sdk/src/ui/components/composed/tools/tool-execution-list.tsx
index e24f91f..765d311 100644
--- a/packages/copilot-sdk/src/ui/components/composed/tools/tool-execution-list.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/tools/tool-execution-list.tsx
@@ -75,6 +75,8 @@ export interface ToolExecutionData {
   duration?: number;
   /** Approval status for human-in-the-loop tools */
   approvalStatus?: ToolApprovalStatus;
+  /** Title shown in approval UI */
+  approvalTitle?: string;
   /** Message shown in approval UI */
   approvalMessage?: string;
   /** Data passed from user's approval action (e.g., selected item) */
diff --git a/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx b/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
index e2924fb..35c5b20 100644
--- a/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
@@ -1,35 +1,24 @@
 "use client";
 
-import * as React from "react";
 import { cn } from "../../lib/utils";
-import { Button } from "./button";
 import { CheckIcon, XIcon, AlertTriangleIcon } from "../icons";
 
 // ============================================
 // Types
 // ============================================
 
-/**
- * Permission level for tool execution
- */
 export type PermissionLevel =
   | "ask"
   | "allow_always"
   | "deny_always"
   | "session";
 
-/**
- * Permission option for dropdown/selection
- */
 export interface PermissionOption {
   value: PermissionLevel;
   label: string;
   description?: string;
 }
 
-/**
- * Default permission options
- */
 export const DEFAULT_PERMISSION_OPTIONS: PermissionOption[] = [
   {
     value: "ask",
@@ -60,191 +49,118 @@ export type ConfirmationState = "pending" | "approved" | "rejected";
 // ============================================
 
 export interface PermissionConfirmationProps {
-  /** Current state: pending, approved, or rejected */
   state: ConfirmationState;
-  /** Tool name */
   toolName?: string;
-  /** Message to display */
   message?: string;
-  /** Called when user approves with permission level */
   onApprove?: (permissionLevel: PermissionLevel) => void;
-  /** Called when user rejects with permission level */
   onReject?: (permissionLevel?: PermissionLevel) => void;
-  /** Show permission options (default: true) */
-  showPermissionOptions?: boolean;
-  /** Available permission options */
-  permissionOptions?: PermissionOption[];
-  /** Additional class name */
+  // showPermissionOptions disabled for now — causes issues
+  // showPermissionOptions?: boolean;
+  // permissionOptions?: PermissionOption[];
   className?: string;
 }
 
-/**
- * PermissionConfirmation - Enhanced confirmation with permission level selection
- *
- * Shows a confirmation dialog for tool approval with options to remember the choice.
- *
- * @example
- * ```tsx
- * <PermissionConfirmation
- *   state="pending"
- *   toolName="capture_screenshot"
- *   message="Take a screenshot of the current screen?"
- *   onApprove={(level) => approveToolExecution(tool.id, level)}
- *   onReject={(level) => rejectToolExecution(tool.id, undefined, level)}
- * />
- * ```
- */
 export function PermissionConfirmation({
   state,
   toolName,
   message,
   onApprove,
   onReject,
-  showPermissionOptions = true,
-  permissionOptions = DEFAULT_PERMISSION_OPTIONS,
   className,
 }: PermissionConfirmationProps) {
-  const [selectedPermission, setSelectedPermission] =
-    React.useState<PermissionLevel>("ask");
-  const [showOptions, setShowOptions] = React.useState(false);
-
   const handleApprove = () => {
-    onApprove?.(selectedPermission);
+    onApprove?.("ask");
   };
 
   const handleReject = () => {
-    // Only pass permission level if it's "deny_always"
-    onReject?.(
-      selectedPermission === "deny_always" ? "deny_always" : undefined,
-    );
+    onReject?.(undefined);
   };
 
-  // Approved state
   if (state === "approved") {
     return (
       <div
         className={cn(
-          "flex items-center gap-2 px-4 py-2 text-sm text-green-600 dark:text-green-400 rounded-lg border bg-green-50 dark:bg-green-950/20",
+          "csdk-confirm-result",
+          "inline-flex items-center gap-2 px-3 py-1.5 text-sm",
+          "rounded-2xl border border-green-200/70 dark:border-green-900/40",
+          "bg-green-50 dark:bg-green-950/20 text-green-700 dark:text-green-400",
           className,
         )}
       >
-        <CheckIcon className="h-4 w-4" />
+        <CheckIcon className="h-3.5 w-3.5 shrink-0" />
         <span>Approved</span>
       </div>
     );
   }
 
-  // Rejected state
   if (state === "rejected") {
     return (
       <div
         className={cn(
-          "flex items-center gap-2 px-4 py-2 text-sm text-red-600 dark:text-red-400 rounded-lg border bg-red-50 dark:bg-red-950/20",
+          "csdk-confirm-result",
+          "inline-flex items-center gap-2 px-3 py-1.5 text-sm",
+          "rounded-2xl border border-red-200/70 dark:border-red-900/40",
+          "bg-red-50 dark:bg-red-950/20 text-red-700 dark:text-red-400",
           className,
         )}
       >
-        <XIcon className="h-4 w-4" />
+        <XIcon className="h-3.5 w-3.5 shrink-0" />
         <span>Rejected</span>
       </div>
     );
   }
 
-  // Pending state - show confirmation UI
   return (
     <div
       className={cn(
-        "rounded-lg border bg-card text-card-foreground p-4",
+        "csdk-confirm-card",
+        "w-full rounded-2xl border border-border/60 bg-card text-card-foreground shadow-sm overflow-hidden",
         className,
       )}
     >
-      {/* Header with tool name */}
-      <div className="flex items-start gap-3 mb-3">
-        <AlertTriangleIcon className="mt-0.5 h-5 w-5 flex-shrink-0 text-amber-500" />
-        <div className="flex-1 min-w-0">
+      {/* Body */}
+      <div className="flex items-start gap-3 p-4">
+        <div className="mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50">
+          <AlertTriangleIcon className="h-3.5 w-3.5 text-amber-600 dark:text-amber-400" />
+        </div>
+        <div className="flex-1 min-w-0 pt-0.5">
           {toolName && (
-            <p className="text-sm font-medium text-foreground">{toolName}</p>
+            <p className="text-[10px] font-semibold uppercase tracking-widest text-muted-foreground mb-1">
+              {toolName}
+            </p>
           )}
-          <p className="text-sm text-muted-foreground">
+          <p className="text-sm text-foreground leading-snug">
             {message || "This tool requires your approval to execute."}
           </p>
         </div>
       </div>
 
-      {/* Permission options */}
-      {showPermissionOptions && (
-        <div className="mb-4">
-          <button
-            type="button"
-            onClick={() => setShowOptions(!showOptions)}
-            className="flex items-center gap-2 text-sm text-muted-foreground hover:text-foreground transition-colors"
-          >
-            <span>
-              {
-                permissionOptions.find((o) => o.value === selectedPermission)
-                  ?.label
-              }
-            </span>
-            <svg
-              className={cn(
-                "h-4 w-4 transition-transform",
-                showOptions && "rotate-180",
-              )}
-              fill="none"
-              viewBox="0 0 24 24"
-              stroke="currentColor"
-              strokeWidth={2}
-            >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                d="M19 9l-7 7-7-7"
-              />
-            </svg>
-          </button>
-
-          {showOptions && (
-            <div className="mt-2 space-y-1 pl-1">
-              {permissionOptions.map((option) => (
-                <label
-                  key={option.value}
-                  className={cn(
-                    "flex items-start gap-2 p-2 rounded-md cursor-pointer transition-colors",
-                    selectedPermission === option.value
-                      ? "bg-primary/10"
-                      : "hover:bg-muted/50",
-                  )}
-                >
-                  <input
-                    type="radio"
-                    name="permission"
-                    value={option.value}
-                    checked={selectedPermission === option.value}
-                    onChange={() => setSelectedPermission(option.value)}
-                    className="mt-0.5"
-                  />
-                  <div>
-                    <div className="text-sm font-medium">{option.label}</div>
-                    {option.description && (
-                      <div className="text-xs text-muted-foreground">
-                        {option.description}
-                      </div>
-                    )}
-                  </div>
-                </label>
-              ))}
-            </div>
+      {/* Actions */}
+      <div className="flex items-center justify-end gap-2 px-4 pb-4">
+        <button
+          type="button"
+          onClick={handleReject}
+          className={cn(
+            "csdk-confirm-btn",
+            "px-4 py-1.5 text-sm font-medium rounded-xl",
+            "border border-border bg-transparent text-muted-foreground",
+            "hover:bg-muted/60 hover:text-foreground",
           )}
-        </div>
-      )}
-
-      {/* Action buttons */}
-      <div className="flex justify-end gap-2">
-        <Button variant="outline" size="sm" onClick={handleReject}>
+        >
           Deny
-        </Button>
-        <Button variant="default" size="sm" onClick={handleApprove}>
+        </button>
+        <button
+          type="button"
+          onClick={handleApprove}
+          className={cn(
+            "csdk-confirm-btn",
+            "px-4 py-1.5 text-sm font-medium rounded-xl",
+            "bg-primary text-primary-foreground",
+            "hover:opacity-90",
+          )}
+        >
           Allow
-        </Button>
+        </button>
       </div>
     </div>
   );
@@ -255,31 +171,13 @@ export function PermissionConfirmation({
 // ============================================
 
 export interface CompactPermissionConfirmationProps {
-  /** Current state: pending, approved, or rejected */
   state: ConfirmationState;
-  /** Message to display */
   message?: string;
-  /** Called when user approves */
   onApprove?: (permissionLevel: PermissionLevel) => void;
-  /** Called when user rejects */
   onReject?: (permissionLevel?: PermissionLevel) => void;
-  /** Additional class name */
   className?: string;
 }
 
-/**
- * CompactPermissionConfirmation - Simpler version with "Don't ask again" checkbox
- *
- * @example
- * ```tsx
- * <CompactPermissionConfirmation
- *   state="pending"
- *   message="Take a screenshot?"
- *   onApprove={(level) => approveToolExecution(tool.id, level)}
- *   onReject={(level) => rejectToolExecution(tool.id, undefined, level)}
- * />
- * ```
- */
 export function CompactPermissionConfirmation({
   state,
   message,
@@ -287,63 +185,71 @@ export function CompactPermissionConfirmation({
   onReject,
   className,
 }: CompactPermissionConfirmationProps) {
-  const [rememberChoice, setRememberChoice] = React.useState(false);
+  // "Don't ask again" checkbox disabled for now
+  // const [rememberChoice, setRememberChoice] = React.useState(false);
 
   const handleApprove = () => {
-    onApprove?.(rememberChoice ? "allow_always" : "ask");
+    onApprove?.("ask");
   };
 
   const handleReject = () => {
-    onReject?.(rememberChoice ? "deny_always" : undefined);
+    onReject?.(undefined);
   };
 
-  // Approved state
   if (state === "approved") {
     return (
       <div
         className={cn(
-          "flex items-center gap-2 px-4 py-2 text-sm text-green-600 dark:text-green-400",
+          "csdk-confirm-result",
+          "inline-flex items-center gap-2 px-3 py-1.5 text-sm",
+          "rounded-2xl border border-green-200/70 dark:border-green-900/40",
+          "bg-green-50 dark:bg-green-950/20 text-green-700 dark:text-green-400",
           className,
         )}
       >
-        <CheckIcon className="h-4 w-4" />
+        <CheckIcon className="h-3.5 w-3.5 shrink-0" />
         <span>Approved</span>
       </div>
     );
   }
 
-  // Rejected state
   if (state === "rejected") {
     return (
       <div
         className={cn(
-          "flex items-center gap-2 px-4 py-2 text-sm text-red-600 dark:text-red-400",
+          "csdk-confirm-result",
+          "inline-flex items-center gap-2 px-3 py-1.5 text-sm",
+          "rounded-2xl border border-red-200/70 dark:border-red-900/40",
+          "bg-red-50 dark:bg-red-950/20 text-red-700 dark:text-red-400",
           className,
         )}
       >
-        <XIcon className="h-4 w-4" />
+        <XIcon className="h-3.5 w-3.5 shrink-0" />
         <span>Rejected</span>
       </div>
     );
   }
 
-  // Pending state
   return (
     <div
       className={cn(
-        "rounded-lg border bg-card text-card-foreground p-4",
+        "csdk-confirm-card",
+        "w-full rounded-2xl border border-border/60 bg-card text-card-foreground shadow-sm overflow-hidden",
         className,
       )}
     >
-      <div className="flex items-start gap-3 mb-3">
-        <AlertTriangleIcon className="mt-0.5 h-5 w-5 flex-shrink-0 text-amber-500" />
-        <p className="text-sm text-foreground">
+      <div className="flex items-start gap-3 p-4">
+        <div className="mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50">
+          <AlertTriangleIcon className="h-3.5 w-3.5 text-amber-600 dark:text-amber-400" />
+        </div>
+        <p className="flex-1 min-w-0 pt-0.5 text-sm text-foreground leading-snug">
           {message || "This action requires your approval."}
         </p>
       </div>
 
-      <div className="flex items-center justify-between">
-        <label className="flex items-center gap-2 text-sm text-muted-foreground cursor-pointer">
+      <div className="flex items-center justify-end gap-2 px-4 pb-4">
+        {/* Don't ask again — disabled for now */}
+        {/* <label className="flex items-center gap-2 text-sm text-muted-foreground cursor-pointer mr-auto">
           <input
             type="checkbox"
             checked={rememberChoice}
@@ -351,16 +257,31 @@ export function CompactPermissionConfirmation({
             className="rounded border-gray-300"
           />
           Don't ask again
-        </label>
-
-        <div className="flex gap-2">
-          <Button variant="outline" size="sm" onClick={handleReject}>
-            Deny
-          </Button>
-          <Button variant="default" size="sm" onClick={handleApprove}>
-            Allow
-          </Button>
-        </div>
+        </label> */}
+        <button
+          type="button"
+          onClick={handleReject}
+          className={cn(
+            "csdk-confirm-btn",
+            "px-4 py-1.5 text-sm font-medium rounded-xl",
+            "border border-border bg-transparent text-muted-foreground",
+            "hover:bg-muted/60 hover:text-foreground",
+          )}
+        >
+          Deny
+        </button>
+        <button
+          type="button"
+          onClick={handleApprove}
+          className={cn(
+            "csdk-confirm-btn",
+            "px-4 py-1.5 text-sm font-medium rounded-xl",
+            "bg-primary text-primary-foreground",
+            "hover:opacity-90",
+          )}
+        >
+          Allow
+        </button>
       </div>
     </div>
   );
diff --git a/packages/copilot-sdk/src/ui/styles/base.css b/packages/copilot-sdk/src/ui/styles/base.css
index 247c545..f505826 100644
--- a/packages/copilot-sdk/src/ui/styles/base.css
+++ b/packages/copilot-sdk/src/ui/styles/base.css
@@ -60,6 +60,49 @@
   }
 }
 
+/* Confirmation Card Animations */
+/* Uses @starting-style for reliable first-paint entry in React (more robust than @keyframes) */
+
+.csdk-confirm-card {
+  opacity: 1;
+  transform: scale(1) translateY(0);
+  transition: opacity 220ms cubic-bezier(0.23, 1, 0.32, 1),
+              transform 220ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+@starting-style {
+  .csdk-confirm-card {
+    opacity: 0;
+    transform: scale(0.96) translateY(6px);
+  }
+}
+
+.csdk-confirm-result {
+  opacity: 1;
+  transform: translateY(0);
+  transition: opacity 180ms cubic-bezier(0.23, 1, 0.32, 1),
+              transform 180ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+@starting-style {
+  .csdk-confirm-result {
+    opacity: 0;
+    transform: translateY(3px);
+  }
+}
+
+.csdk-confirm-btn {
+  transition: transform 140ms cubic-bezier(0.23, 1, 0.32, 1),
+              opacity 140ms ease,
+              background-color 120ms ease,
+              color 120ms ease,
+              border-color 120ms ease;
+}
+
+.csdk-confirm-btn:active {
+  transform: scale(0.97);
+}
+
 /* Loader Animations */
 @keyframes csdk-spinner-fade {
   0%, 100% { opacity: 1; }

From e0155046ef8620e438a18af22e4a7918642161ef Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Tue, 17 Mar 2026 17:55:59 +0530
Subject: [PATCH 24/72] feat(chat): introduce ChatPrimitives for customizable
 chat layouts

- Shipped the headless primitive API for chat components, allowing developers to build custom chat layouts using `ChatPrimitives`.
- Updated documentation to reflect the new API and provide usage examples.
- Added message actions support with floating action buttons for user and assistant messages.
- Enhanced the `DefaultMessage` component to integrate floating actions and improve message rendering flexibility.
---
 apps/docs/alpha-docs/CHAT-PRIMITIVES.md       | 219 +++++
 apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md   |  15 +-
 apps/docs/alpha-docs/MESSAGE-ACTIONS.md       | 247 ++++++
 .../src/ui/components/composed/chat/chat.tsx  | 818 +++++++++---------
 .../composed/chat/default-message.tsx         |  89 +-
 .../src/ui/components/composed/chat/index.ts  |  17 +
 .../chat/message-actions-compound.tsx         | 291 +++++++
 .../composed/chat/message-actions-context.tsx |  68 ++
 .../components/composed/chat/message-list.tsx |  60 ++
 packages/copilot-sdk/src/ui/index.ts          |  75 ++
 10 files changed, 1496 insertions(+), 403 deletions(-)
 create mode 100644 apps/docs/alpha-docs/CHAT-PRIMITIVES.md
 create mode 100644 apps/docs/alpha-docs/MESSAGE-ACTIONS.md
 create mode 100644 packages/copilot-sdk/src/ui/components/composed/chat/message-actions-compound.tsx
 create mode 100644 packages/copilot-sdk/src/ui/components/composed/chat/message-actions-context.tsx
 create mode 100644 packages/copilot-sdk/src/ui/components/composed/chat/message-list.tsx

diff --git a/apps/docs/alpha-docs/CHAT-PRIMITIVES.md b/apps/docs/alpha-docs/CHAT-PRIMITIVES.md
new file mode 100644
index 0000000..d63ac02
--- /dev/null
+++ b/apps/docs/alpha-docs/CHAT-PRIMITIVES.md
@@ -0,0 +1,219 @@
+# Chat Primitives
+
+> `release/alpha` — ships two complementary APIs for headless chat customization: the `ChatPrimitives` namespace (low-level building blocks) and compound components on `CopilotChat.*` (MessageActions, MessageList, DefaultMessage, etc.). Both are non-breaking additive exports.
+
+---
+
+## Table of Contents
+
+1. [What Was Built](#what-was-built)
+2. [Breaking Changes](#breaking-changes)
+3. [ChatPrimitives Namespace](#chatprimitives-namespace)
+4. [CopilotChat Compound Components](#copilotchat-compound-components)
+5. [Usage Examples](#usage-examples)
+6. [How It Works Internally](#how-it-works-internally)
+7. [Relation to `messageView`](#relation-to-messageview)
+
+---
+
+## What Was Built
+
+Two exports that let you compose custom chat UIs at any level of abstraction while the SDK handles all state, streaming, and context internally.
+
+**`ChatPrimitives`** — a named export of individual low-level components. Useful when you import under an alias and want to pick specific pieces.
+
+**`CopilotChat.*` compound extensions** — the same primitives accessible directly on the `CopilotChat` component for inline composition without extra imports.
+
+---
+
+## Breaking Changes
+
+**None.** Both are purely additive. Existing `<CopilotChat />` usage is untouched.
+
+---
+
+## ChatPrimitives Namespace
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+```
+
+### All Primitives
+
+| Primitive             | Description                                               |
+| --------------------- | --------------------------------------------------------- |
+| `Chat.MessageList`    | Render-prop message list — reads `messages` from context  |
+| `Chat.DefaultMessage` | Full SDK message bubble — use as fallback in custom lists |
+| `Chat.Header`         | Chat header bar                                           |
+| `Chat.Welcome`        | Welcome screen shown when there are no messages           |
+| `Chat.Input`          | Composer / input box                                      |
+| `Chat.ScrollAnchor`   | Auto-scroll anchor, place at end of message list          |
+| `Chat.Message`        | Low-level message row wrapper                             |
+| `Chat.MessageAvatar`  | Avatar with fallback initials                             |
+| `Chat.MessageContent` | Content bubble — renders markdown, supports streaming     |
+| `Chat.MessageActions` | Action bar layout primitive (wraps action buttons)        |
+| `Chat.MessageAction`  | Single action icon button with tooltip                    |
+| `Chat.Loader`         | Streaming / thinking indicator                            |
+
+### `Chat.MessageList` props
+
+```ts
+interface MessageListProps {
+  children?: (message: ChatMessage, index: number) => React.ReactNode;
+  className?: string;
+}
+```
+
+When `children` is provided, called once per message — return your custom component or fall back to `Chat.DefaultMessage`. When omitted, renders all messages with `DefaultMessage`.
+
+---
+
+## CopilotChat Compound Components
+
+The `ChatPrimitives` are also mounted on the `CopilotChat` export:
+
+```tsx
+import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
+
+CopilotChat.MessageActions; // compound action registrar (see MESSAGE-ACTIONS.md)
+CopilotChat.CopyAction; // built-in copy button
+CopilotChat.EditAction; // built-in inline edit button
+CopilotChat.FeedbackAction; // built-in thumbs up/down
+CopilotChat.Action; // custom action button
+```
+
+These are the action-registration compound components — see [MESSAGE-ACTIONS.md](./MESSAGE-ACTIONS.md) for full docs.
+
+---
+
+## Usage Examples
+
+### Custom message type with fallback
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
+<CopilotChat>
+  <Chat.MessageList>
+    {(message) =>
+      message.metadata?.type === "plan" ? (
+        <PlanCard key={message.id} message={message} />
+      ) : (
+        <Chat.DefaultMessage key={message.id} message={message} />
+      )
+    }
+  </Chat.MessageList>
+</CopilotChat>;
+```
+
+---
+
+### Fully custom layout — compose from scratch
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
+<CopilotChat>
+  <div className="flex flex-col h-full">
+    <Chat.Header />
+    <Chat.Welcome />
+
+    <div className="flex-1 overflow-y-auto px-4">
+      <Chat.MessageList>
+        {(message) => (
+          <Chat.Message key={message.id} message={message}>
+            <Chat.MessageAvatar message={message} />
+            <Chat.MessageContent message={message} />
+          </Chat.Message>
+        )}
+      </Chat.MessageList>
+      <Chat.Loader />
+      <Chat.ScrollAnchor />
+    </div>
+
+    <Chat.Input />
+  </div>
+</CopilotChat>;
+```
+
+---
+
+### Mix primitives with message actions
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
+<CopilotChat>
+  {/* Register floating action buttons */}
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.FeedbackAction onFeedback={(msg, type) => log(msg.id, type)} />
+  </CopilotChat.MessageActions>
+
+  {/* Custom message list */}
+  <Chat.MessageList>
+    {(message) =>
+      message.metadata?.type === "approval" ? (
+        <ApprovalCard key={message.id} message={message} />
+      ) : (
+        <Chat.DefaultMessage key={message.id} message={message} />
+      )
+    }
+  </Chat.MessageList>
+</CopilotChat>;
+```
+
+---
+
+### Per-message action buttons (using primitives directly)
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
+<Chat.MessageList>
+  {(message) => (
+    <Chat.Message key={message.id} message={message}>
+      <Chat.MessageAvatar message={message} />
+      <div className="flex flex-col gap-1">
+        <Chat.MessageContent message={message} />
+        <Chat.MessageActions>
+          <Chat.MessageAction
+            icon={<CopyIcon />}
+            tooltip="Copy"
+            onClick={() => navigator.clipboard.writeText(message.content ?? "")}
+          />
+        </Chat.MessageActions>
+      </div>
+    </Chat.Message>
+  )}
+</Chat.MessageList>;
+```
+
+---
+
+## How It Works Internally
+
+**State access:** `Chat.MessageList` reads `messages` and `registeredTools` from `CopilotChatInternalContext` — the same context `chat.tsx` already provides. No extra wiring needed.
+
+**`messages` + `registeredTools` in context:** Added to `CopilotChatInternalContext` so primitives can access them without prop drilling. `connected-chat.tsx` was unchanged — values flow through the existing context setup in `chat.tsx`.
+
+**Files created/modified:**
+
+- `message-list.tsx` _(new)_ — `Chat.MessageList` component
+- `chat.tsx` — added `messages` + `registeredTools` to `CopilotChatInternalContext`; extended `Chat` compound object with `MessageActions`, `CopyAction`, `EditAction`, `FeedbackAction`, `Action`
+- `ui/index.ts` — added `ChatPrimitives` export
+- `chat/index.ts` — added `MessageList`, all action compound types
+
+---
+
+## Relation to `messageView`
+
+`messageView` prop (see [CUSTOM-MESSAGE-VIEW.md](./CUSTOM-MESSAGE-VIEW.md)) and `Chat.MessageList` solve the same use case — custom message rendering — at different abstraction levels:
+
+|             | `messageView`                                            | `Chat.MessageList`                            |
+| ----------- | -------------------------------------------------------- | --------------------------------------------- |
+| Style       | Prop on `<CopilotChat>`                                  | Child component inside `<CopilotChat>`        |
+| Access      | `messages[]` + pre-rendered `messageElements[]`          | `messages[]` via render-prop                  |
+| When to use | Quick overrides, inject extra UI around existing renders | Full layout control, building from primitives |
+
+Both are non-breaking and can coexist. `messageView` remains the simpler option for most cases.
diff --git a/apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md b/apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md
index 556c774..824804d 100644
--- a/apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md
+++ b/apps/docs/alpha-docs/CUSTOM-MESSAGE-VIEW.md
@@ -148,14 +148,14 @@ The loading placeholder and scroll anchor remain outside this block and are unaf
 
 ---
 
-## Roadmap — `Chat.*` Primitives
+## `Chat.*` Primitives — Now Shipped
 
-A full headless primitive API is planned as a future non-breaking addition:
+The headless primitive API described here as a roadmap item has shipped in this same alpha. You can use it today:
 
 ```tsx
-// Future API — Chat.* primitives
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
 <CopilotChat>
-  <Chat.Header />
   <Chat.MessageList>
     {(message) =>
       message.metadata?.type === "plan" ? (
@@ -165,8 +165,9 @@ A full headless primitive API is planned as a future non-breaking addition:
       )
     }
   </Chat.MessageList>
-  <Chat.Input />
-</CopilotChat>
+</CopilotChat>;
 ```
 
-When this ships, `messageView` becomes a convenience wrapper over the primitive API — no migration needed.
+`messageView` remains the simpler option for quick overrides. `Chat.MessageList` is the lower-level primitive when you need full layout control. Both work — no migration needed between them.
+
+→ Full primitives docs: [CHAT-PRIMITIVES.md](./CHAT-PRIMITIVES.md)
diff --git a/apps/docs/alpha-docs/MESSAGE-ACTIONS.md b/apps/docs/alpha-docs/MESSAGE-ACTIONS.md
new file mode 100644
index 0000000..7759157
--- /dev/null
+++ b/apps/docs/alpha-docs/MESSAGE-ACTIONS.md
@@ -0,0 +1,247 @@
+# Message Actions
+
+> `release/alpha` — adds a compound component API for registering floating action buttons on chat messages. Declarative, role-based, fully composable — same pattern as shadcn/Radix.
+
+---
+
+## Table of Contents
+
+1. [What Was Built](#what-was-built)
+2. [Breaking Changes](#breaking-changes)
+3. [New APIs](#new-apis)
+4. [Usage Examples](#usage-examples)
+5. [How It Works Internally](#how-it-works-internally)
+6. [Also Shipped — ChatPrimitives Namespace](#also-shipped--chatprimitives-namespace)
+
+---
+
+## What Was Built
+
+A compound component API for adding floating action buttons to chat messages — copy, edit, feedback, or fully custom actions — declared as children of `<CopilotChat>`.
+
+Actions appear on hover, floating below the message bubble. Role-based — configure `assistant` and `user` separately.
+
+---
+
+## Breaking Changes
+
+**None.** If no `<CopilotChat.MessageActions>` children are declared, nothing changes. Existing chat UI looks and behaves identically.
+
+---
+
+## New APIs
+
+### Compound components
+
+```
+CopilotChat.MessageActions   — registers actions for a role
+CopilotChat.CopyAction       — built-in copy to clipboard (with check feedback)
+CopilotChat.EditAction       — built-in edit (user messages, wired to inline edit)
+CopilotChat.FeedbackAction   — built-in thumbs up/down
+CopilotChat.Action           — fully custom action
+```
+
+### Props
+
+```tsx
+// MessageActions
+role: "user" | "assistant"
+
+// CopyAction
+tooltip?: string
+className?: string
+
+// EditAction
+tooltip?: string
+className?: string
+
+// FeedbackAction
+onFeedback?: (message: ChatMessage, type: "helpful" | "not-helpful") => void
+tooltip?: string
+className?: string
+
+// Action
+id?: string
+icon: ReactNode
+tooltip: string
+onClick: (props: { message: ChatMessage }) => void
+hidden?: boolean | ((props: { message: ChatMessage }) => boolean)
+className?: string
+```
+
+---
+
+## Usage Examples
+
+### Zero config — no actions (default)
+
+```tsx
+<CopilotChat />
+// No action buttons shown — clean slate
+```
+
+---
+
+### Copy on assistant, Edit on user
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+  </CopilotChat.MessageActions>
+
+  <CopilotChat.MessageActions role="user">
+    <CopilotChat.EditAction />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+---
+
+### Copy + Feedback on assistant
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.FeedbackAction
+      onFeedback={(message, type) => {
+        sendFeedback({ messageId: message.id, type });
+      }}
+    />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+---
+
+### Custom action
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.Action
+      icon={<ShareIcon />}
+      tooltip="Share"
+      onClick={({ message }) => share(message.content)}
+    />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+---
+
+### Conditional action (hide based on message)
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.Action
+      icon={<FlagIcon />}
+      tooltip="Report"
+      hidden={({ message }) => !message.content}
+      onClick={({ message }) => report(message.id)}
+    />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+---
+
+### Disable all actions for a role
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    {/* empty — no actions for assistant */}
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+---
+
+### Full setup — both roles
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.FeedbackAction onFeedback={(msg, type) => log(msg.id, type)} />
+    <CopilotChat.Action
+      icon={<BookmarkIcon />}
+      tooltip="Save"
+      onClick={({ message }) => save(message)}
+    />
+  </CopilotChat.MessageActions>
+
+  <CopilotChat.MessageActions role="user">
+    <CopilotChat.EditAction />
+    <CopilotChat.Action
+      icon={<DeleteIcon />}
+      tooltip="Delete"
+      onClick={({ message }) => deleteMessage(message.id)}
+    />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+---
+
+## How It Works Internally
+
+**Files created/modified:**
+
+- `message-actions-context.tsx` _(new)_ — React context storing registered actions per role
+- `message-actions-compound.tsx` _(new)_ — compound components (`MessageActions`, `CopyAction`, `EditAction`, `FeedbackAction`, `Action`)
+- `chat.tsx` — wrapped with `MessageActionsProvider`, compound components added to `Chat.*` namespace
+- `default-message.tsx` — `FloatingActions` helper reads from context, renders on `group-hover/message`
+
+**Flow:**
+
+1. `<CopilotChat.MessageActions role="assistant">` scans its children's props via `React.Children.forEach`, builds a `RegisteredAction[]`
+2. `useLayoutEffect` registers them into `MessageActionsContext`
+3. `DefaultMessage` renders `<FloatingActions>` for each message
+4. `FloatingActions` calls `ctx.getActions(role)` — if empty, renders nothing
+
+**Copy action** has local state (`copiedId`) — switches icon to ✓ for 1.5s then reverts.
+
+**Edit action** routes to the existing `startEdit()` function already in `DefaultMessage` — no duplication.
+
+---
+
+## Also Shipped — `ChatPrimitives` Namespace
+
+A `ChatPrimitives` export was also added for headless composition:
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk-ui";
+
+<CopilotChat>
+  <Chat.MessageList>
+    {(message) =>
+      message.metadata?.type === "plan" ? (
+        <PlanCard key={message.id} />
+      ) : (
+        <Chat.DefaultMessage key={message.id} message={message} />
+      )
+    }
+  </Chat.MessageList>
+</CopilotChat>;
+```
+
+| Primitive             | Description                                  |
+| --------------------- | -------------------------------------------- |
+| `Chat.MessageList`    | Render-prop message list, reads from context |
+| `Chat.DefaultMessage` | Full SDK message bubble, use as fallback     |
+| `Chat.Header`         | Chat header bar                              |
+| `Chat.Welcome`        | Welcome screen (no messages)                 |
+| `Chat.Input`          | Composer / input box                         |
+| `Chat.ScrollAnchor`   | Auto-scroll anchor                           |
+| `Chat.Message`        | Low-level row wrapper                        |
+| `Chat.MessageAvatar`  | Avatar with fallback                         |
+| `Chat.MessageContent` | Content bubble, supports markdown            |
+| `Chat.MessageActions` | Action bar layout primitive                  |
+| `Chat.MessageAction`  | Single action button with tooltip            |
+| `Chat.Loader`         | Streaming indicator                          |
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 82b4e9b..27f11dd 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -38,6 +38,14 @@ import type { ChatProps, PendingAttachment, MessageAttachment } from "./types";
 import type { ToolExecutionData } from "../tools";
 import type { Thread } from "../../../../core/types/thread";
 import { ThreadPicker, type ThreadPickerProps } from "../../ui/thread-picker";
+import { MessageActionsProvider } from "./message-actions-context";
+import {
+  MessageActions,
+  CopyAction,
+  EditAction,
+  FeedbackAction,
+  Action as MessageAction,
+} from "./message-actions-compound";
 
 // ============================================================================
 // Internal Context for Compound Components
@@ -50,6 +58,9 @@ interface CopilotChatInternalContext {
   onStop?: () => void;
   attachmentsEnabled: boolean;
   placeholder: string;
+  // Messages (for Chat.MessageList primitive)
+  messages: import("./types").ChatMessage[];
+  registeredTools?: import("../../../../core").ToolDefinition[];
   // Thread management
   onNewChat?: () => void;
   threads?: Thread[];
@@ -807,6 +818,9 @@ function ChatComponent({
       onStop,
       attachmentsEnabled,
       placeholder,
+      // Messages for Chat.MessageList primitive
+      messages,
+      registeredTools,
       // Thread management - passed from connected-chat
       onNewChat,
       threads,
@@ -822,6 +836,8 @@ function ChatComponent({
       onStop,
       attachmentsEnabled,
       placeholder,
+      messages,
+      registeredTools,
       onNewChat,
       threads,
       currentThreadId,
@@ -832,419 +848,427 @@ function ChatComponent({
   );
 
   return (
-    <CopilotChatContext.Provider value={contextValue}>
-      <div
-        className={cn(
-          "flex h-full flex-col bg-background relative",
-          className,
-          classNames.root,
-        )}
-        onDragOver={handleDragOver}
-        onDragLeave={handleDragLeave}
-        onDrop={handleDrop}
-      >
-        {/* Drag overlay */}
-        {isDragging && (
-          <div className="absolute inset-0 z-50 bg-primary/10 border-2 border-dashed border-primary flex items-center justify-center">
-            <div className="text-primary font-medium text-lg">
-              Drop files here
+    <MessageActionsProvider>
+      <CopilotChatContext.Provider value={contextValue}>
+        <div
+          className={cn(
+            "flex h-full flex-col bg-background relative",
+            className,
+            classNames.root,
+          )}
+          onDragOver={handleDragOver}
+          onDragLeave={handleDragLeave}
+          onDrop={handleDrop}
+        >
+          {/* Drag overlay */}
+          {isDragging && (
+            <div className="absolute inset-0 z-50 bg-primary/10 border-2 border-dashed border-primary flex items-center justify-center">
+              <div className="text-primary font-medium text-lg">
+                Drop files here
+              </div>
             </div>
-          </div>
-        )}
-        {/* Built-in Header (from showHeader prop) */}
-        {showHeader &&
-          (renderHeader ? (
-            renderHeader()
-          ) : (
-            <ChatHeader
-              logo={header?.logo ?? logo}
-              name={header?.name ?? name}
-              title={title}
-              threadPicker={threadPicker}
-              onClose={header?.onClose ?? onClose}
-              className={classNames.header}
+          )}
+          {/* Built-in Header (from showHeader prop) */}
+          {showHeader &&
+            (renderHeader ? (
+              renderHeader()
+            ) : (
+              <ChatHeader
+                logo={header?.logo ?? logo}
+                name={header?.name ?? name}
+                title={title}
+                threadPicker={threadPicker}
+                onClose={header?.onClose ?? onClose}
+                className={classNames.header}
+              />
+            ))}
+
+          {/* Root-level custom Header (shows in both views) */}
+          {rootHeader}
+
+          {/* Custom compound children - view components self-filter based on current view */}
+          {hasCustomLayout && viewChildren}
+
+          {showDefaultWelcome ? (
+            /* Default Welcome Screen (centered input) */
+            <ChatWelcome
+              config={welcomeConfig}
+              suggestions={suggestions}
+              recentThreads={recentThreads}
+              onSendMessage={(msg, attachments) =>
+                onSendMessage?.(msg, attachments)
+              }
+              onSelectThread={onSelectThread}
+              onDeleteThread={onDeleteThread}
+              onViewMoreThreads={onViewMoreThreads}
+              isLoading={isLoading}
+              onStop={onStop}
+              placeholder={placeholder}
+              attachmentsEnabled={attachmentsEnabled}
+              attachmentsDisabledTooltip={attachmentsDisabledTooltip}
+              maxFileSize={maxFileSize}
+              allowedFileTypes={allowedFileTypes}
+              processAttachment={processAttachmentProp}
             />
-          ))}
-
-        {/* Root-level custom Header (shows in both views) */}
-        {rootHeader}
-
-        {/* Custom compound children - view components self-filter based on current view */}
-        {hasCustomLayout && viewChildren}
-
-        {showDefaultWelcome ? (
-          /* Default Welcome Screen (centered input) */
-          <ChatWelcome
-            config={welcomeConfig}
-            suggestions={suggestions}
-            recentThreads={recentThreads}
-            onSendMessage={(msg, attachments) =>
-              onSendMessage?.(msg, attachments)
-            }
-            onSelectThread={onSelectThread}
-            onDeleteThread={onDeleteThread}
-            onViewMoreThreads={onViewMoreThreads}
-            isLoading={isLoading}
-            onStop={onStop}
-            placeholder={placeholder}
-            attachmentsEnabled={attachmentsEnabled}
-            attachmentsDisabledTooltip={attachmentsDisabledTooltip}
-            maxFileSize={maxFileSize}
-            allowedFileTypes={allowedFileTypes}
-            processAttachment={processAttachmentProp}
-          />
-        ) : null}
-
-        {/* Normal Chat UI (messages + input at bottom) - show when there are messages */}
-        {/* Renders when: view is chat AND (no explicit ChatView OR ChatView needs default content) */}
-        {view === "chat" && (!hasCustomChatView || chatViewNeedsDefault) && (
-          <>
-            {/* Messages wrapper - relative for scroll button positioning */}
-            <div className="flex-1 min-h-0 flex flex-col">
-              <ChatContainerRoot
-                className={cn("flex-1 relative", classNames.container)}
-              >
-                <ChatContainerContent
-                  className={cn("gap-4 p-4", classNames.messageList)}
+          ) : null}
+
+          {/* Normal Chat UI (messages + input at bottom) - show when there are messages */}
+          {/* Renders when: view is chat AND (no explicit ChatView OR ChatView needs default content) */}
+          {view === "chat" && (!hasCustomChatView || chatViewNeedsDefault) && (
+            <>
+              {/* Messages wrapper - relative for scroll button positioning */}
+              <div className="flex-1 min-h-0 flex flex-col">
+                <ChatContainerRoot
+                  className={cn("flex-1 relative", classNames.container)}
                 >
-                  {/* Welcome message */}
-                  {messages.length === 0 && (
-                    <div className="py-8 text-center text-muted-foreground">
-                      {welcomeMessage ||
-                        "Send a message to start the conversation"}
-                    </div>
-                  )}
+                  <ChatContainerContent
+                    className={cn("gap-4 p-4", classNames.messageList)}
+                  >
+                    {/* Welcome message */}
+                    {messages.length === 0 && (
+                      <div className="py-8 text-center text-muted-foreground">
+                        {welcomeMessage ||
+                          "Send a message to start the conversation"}
+                      </div>
+                    )}
 
-                  {/* Messages */}
-                  {(() => {
-                    const messageElements = messages.map((message, index) => {
-                      const isLastMessage = index === messages.length - 1;
-
-                      const GROUP_THRESHOLD_MS = 5 * 60 * 1000;
-                      const shouldHideAvatar = (() => {
-                        if (!groupConsecutiveMessages || index === 0)
-                          return false;
-                        let prevIdx = index - 1;
-                        while (prevIdx >= 0) {
-                          const prev = messages[prevIdx];
-                          const isToolMsg = prev.role === "tool";
-                          const isInvisibleSystem =
-                            prev.role === "system" &&
-                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                            (prev.metadata as Record<string, unknown>)?.type !==
-                              "compaction-marker";
-                          if (!isToolMsg && !isInvisibleSystem) break;
-                          prevIdx--;
+                    {/* Messages */}
+                    {(() => {
+                      const messageElements = messages.map((message, index) => {
+                        const isLastMessage = index === messages.length - 1;
+
+                        const GROUP_THRESHOLD_MS = 5 * 60 * 1000;
+                        const shouldHideAvatar = (() => {
+                          if (!groupConsecutiveMessages || index === 0)
+                            return false;
+                          let prevIdx = index - 1;
+                          while (prevIdx >= 0) {
+                            const prev = messages[prevIdx];
+                            const isToolMsg = prev.role === "tool";
+                            const isInvisibleSystem =
+                              prev.role === "system" &&
+                              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                              (prev.metadata as Record<string, unknown>)
+                                ?.type !== "compaction-marker";
+                            if (!isToolMsg && !isInvisibleSystem) break;
+                            prevIdx--;
+                          }
+                          if (prevIdx < 0) return false;
+                          const prevVisible = messages[prevIdx];
+                          if (prevVisible.role !== message.role) return false;
+                          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                          const curTs = (message as any).timestamp as
+                            | number
+                            | undefined;
+                          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                          const prevTs = (prevVisible as any).timestamp as
+                            | number
+                            | undefined;
+                          if (
+                            curTs &&
+                            prevTs &&
+                            curTs - prevTs > GROUP_THRESHOLD_MS
+                          )
+                            return false;
+                          return true;
+                        })();
+
+                        const isEmptyAssistant =
+                          message.role === "assistant" &&
+                          !message.content?.trim();
+
+                        // Check if message has tool_calls or toolExecutions
+                        const hasToolCalls =
+                          message.tool_calls && message.tool_calls.length > 0;
+                        const hasToolExecutions =
+                          message.toolExecutions &&
+                          message.toolExecutions.length > 0;
+
+                        // Check if this message has pending tool approvals
+                        const hasPendingApprovals =
+                          message.toolExecutions?.some(
+                            (exec) => exec.approvalStatus === "required",
+                          );
+
+                        // Hide empty assistant messages that aren't loading and have no content to show
+                        if (isEmptyAssistant) {
+                          const shouldShowMessage =
+                            hasToolCalls ||
+                            hasToolExecutions ||
+                            hasPendingApprovals ||
+                            (isLastMessage && (isLoading || isProcessing));
+
+                          if (!shouldShowMessage) {
+                            return null;
+                          }
+                          // Otherwise, continue to render via DefaultMessage
                         }
-                        if (prevIdx < 0) return false;
-                        const prevVisible = messages[prevIdx];
-                        if (prevVisible.role !== message.role) return false;
-                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                        const curTs = (message as any).timestamp as
-                          | number
-                          | undefined;
+
+                        // Check for saved executions in metadata (historical)
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                        const prevTs = (prevVisible as any).timestamp as
-                          | number
-                          | undefined;
-                        if (
-                          curTs &&
-                          prevTs &&
-                          curTs - prevTs > GROUP_THRESHOLD_MS
-                        )
-                          return false;
-                        return true;
-                      })();
-
-                      const isEmptyAssistant =
-                        message.role === "assistant" &&
-                        !message.content?.trim();
-
-                      // Check if message has tool_calls or toolExecutions
-                      const hasToolCalls =
-                        message.tool_calls && message.tool_calls.length > 0;
-                      const hasToolExecutions =
-                        message.toolExecutions &&
-                        message.toolExecutions.length > 0;
-
-                      // Check if this message has pending tool approvals
-                      const hasPendingApprovals = message.toolExecutions?.some(
-                        (exec) => exec.approvalStatus === "required",
-                      );
-
-                      // Hide empty assistant messages that aren't loading and have no content to show
-                      if (isEmptyAssistant) {
-                        const shouldShowMessage =
-                          hasToolCalls ||
-                          hasToolExecutions ||
-                          hasPendingApprovals ||
-                          (isLastMessage && (isLoading || isProcessing));
-
-                        if (!shouldShowMessage) {
-                          return null;
-                        }
-                        // Otherwise, continue to render via DefaultMessage
-                      }
-
-                      // Check for saved executions in metadata (historical)
-                      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                      const savedExecutions = (message as any).metadata
-                        ?.toolExecutions as ToolExecutionData[] | undefined;
-                      const messageToolExecutions =
-                        message.toolExecutions || savedExecutions;
-
-                      const messageWithExecutions = messageToolExecutions
-                        ? { ...message, toolExecutions: messageToolExecutions }
-                        : message;
-
-                      // Handle follow-up click - use onSendMessage if available
-                      const handleFollowUpClick = (question: string) => {
-                        if (onSuggestionClick) {
-                          onSuggestionClick(question);
-                        } else {
-                          onSendMessage?.(question);
-                        }
-                      };
+                        const savedExecutions = (message as any).metadata
+                          ?.toolExecutions as ToolExecutionData[] | undefined;
+                        const messageToolExecutions =
+                          message.toolExecutions || savedExecutions;
+
+                        const messageWithExecutions = messageToolExecutions
+                          ? {
+                              ...message,
+                              toolExecutions: messageToolExecutions,
+                            }
+                          : message;
+
+                        // Handle follow-up click - use onSendMessage if available
+                        const handleFollowUpClick = (question: string) => {
+                          if (onSuggestionClick) {
+                            onSuggestionClick(question);
+                          } else {
+                            onSendMessage?.(question);
+                          }
+                        };
 
-                      return renderMessage ? (
-                        <React.Fragment key={message.id}>
-                          {renderMessage(messageWithExecutions, index)}
-                        </React.Fragment>
-                      ) : (
+                        return renderMessage ? (
+                          <React.Fragment key={message.id}>
+                            {renderMessage(messageWithExecutions, index)}
+                          </React.Fragment>
+                        ) : (
+                          <DefaultMessage
+                            key={message.id}
+                            message={messageWithExecutions}
+                            userAvatar={
+                              shouldHideAvatar && message.role === "user"
+                                ? { ...userAvatar, className: "invisible" }
+                                : userAvatar
+                            }
+                            assistantAvatar={
+                              shouldHideAvatar && message.role === "assistant"
+                                ? { ...assistantAvatar, className: "invisible" }
+                                : assistantAvatar
+                            }
+                            showUserAvatar={showUserAvatar}
+                            userMessageClassName={classNames.userMessage}
+                            assistantMessageClassName={
+                              classNames.assistantMessage
+                            }
+                            size={fontSize}
+                            isLastMessage={isLastMessage}
+                            isLoading={isLoading}
+                            isProcessing={isProcessing}
+                            loaderVariant={loaderVariant}
+                            registeredTools={registeredTools}
+                            toolRenderers={toolRenderers}
+                            mcpToolRenderer={mcpToolRenderer}
+                            fallbackToolRenderer={fallbackToolRenderer}
+                            onApproveToolExecution={onApproveToolExecution}
+                            onRejectToolExecution={onRejectToolExecution}
+                            showFollowUps={showFollowUps}
+                            onFollowUpClick={handleFollowUpClick}
+                            followUpClassName={followUpClassName}
+                            followUpButtonClassName={followUpButtonClassName}
+                            citations={
+                              citations === false
+                                ? { enabled: false }
+                                : citations
+                            }
+                            branchInfo={
+                              message.role === "user"
+                                ? (getBranchInfo?.(message.id) ?? null)
+                                : null
+                            }
+                            onSwitchBranch={onSwitchBranch}
+                            onEditMessage={onEditMessage}
+                          />
+                        );
+                      });
+                      return messageView?.children
+                        ? messageView.children({ messages, messageElements })
+                        : messageElements;
+                    })()}
+
+                    {/* Loading indicator for non-streaming - when last message is user and no assistant message yet */}
+                    {isLoading &&
+                      !isProcessing &&
+                      messages.length > 0 &&
+                      messages[messages.length - 1]?.role === "user" && (
                         <DefaultMessage
-                          key={message.id}
-                          message={messageWithExecutions}
-                          userAvatar={
-                            shouldHideAvatar && message.role === "user"
-                              ? { ...userAvatar, className: "invisible" }
-                              : userAvatar
-                          }
-                          assistantAvatar={
-                            shouldHideAvatar && message.role === "assistant"
-                              ? { ...assistantAvatar, className: "invisible" }
-                              : assistantAvatar
-                          }
-                          showUserAvatar={showUserAvatar}
-                          userMessageClassName={classNames.userMessage}
-                          assistantMessageClassName={
-                            classNames.assistantMessage
-                          }
+                          message={{
+                            id: "loading-placeholder",
+                            role: "assistant",
+                            content: "",
+                          }}
+                          userAvatar={userAvatar}
+                          assistantAvatar={assistantAvatar}
+                          showUserAvatar={false}
                           size={fontSize}
-                          isLastMessage={isLastMessage}
-                          isLoading={isLoading}
-                          isProcessing={isProcessing}
+                          isLastMessage={true}
+                          isLoading={true}
+                          isProcessing={false}
                           loaderVariant={loaderVariant}
-                          registeredTools={registeredTools}
-                          toolRenderers={toolRenderers}
-                          mcpToolRenderer={mcpToolRenderer}
-                          fallbackToolRenderer={fallbackToolRenderer}
-                          onApproveToolExecution={onApproveToolExecution}
-                          onRejectToolExecution={onRejectToolExecution}
-                          showFollowUps={showFollowUps}
-                          onFollowUpClick={handleFollowUpClick}
-                          followUpClassName={followUpClassName}
-                          followUpButtonClassName={followUpButtonClassName}
-                          citations={
-                            citations === false ? { enabled: false } : citations
-                          }
-                          branchInfo={
-                            message.role === "user"
-                              ? (getBranchInfo?.(message.id) ?? null)
-                              : null
-                          }
-                          onSwitchBranch={onSwitchBranch}
-                          onEditMessage={onEditMessage}
                         />
-                      );
-                    });
-                    return messageView?.children
-                      ? messageView.children({ messages, messageElements })
-                      : messageElements;
-                  })()}
-
-                  {/* Loading indicator for non-streaming - when last message is user and no assistant message yet */}
-                  {isLoading &&
-                    !isProcessing &&
-                    messages.length > 0 &&
-                    messages[messages.length - 1]?.role === "user" && (
-                      <DefaultMessage
-                        message={{
-                          id: "loading-placeholder",
-                          role: "assistant",
-                          content: "",
-                        }}
-                        userAvatar={userAvatar}
-                        assistantAvatar={assistantAvatar}
-                        showUserAvatar={false}
-                        size={fontSize}
-                        isLastMessage={true}
-                        isLoading={true}
-                        isProcessing={false}
-                        loaderVariant={loaderVariant}
-                      />
-                    )}
-
-                  <ChatContainerScrollAnchor />
-                </ChatContainerContent>
-
-                {/* Scroll to bottom button - inside ChatContainerRoot for context, outside ChatContainerContent so it doesn't scroll */}
-                <div className="absolute inset-0 pointer-events-none z-10 flex items-end justify-end p-4">
-                  <ScrollButton className="shadow-md pointer-events-auto" />
-                </div>
-              </ChatContainerRoot>
-            </div>
+                      )}
 
-            {/* Suggestions */}
-            {suggestions.length > 0 && !isLoading && (
-              <Suggestions
-                suggestions={suggestions}
-                onSuggestionClick={handleSuggestionClick}
-                className={classNames.suggestions}
-              />
-            )}
+                    <ChatContainerScrollAnchor />
+                  </ChatContainerContent>
 
-            {/* Input */}
-            {renderInput ? (
-              renderInput()
-            ) : (
-              <div className={cn("p-2 pt-0", classNames.input)}>
-                {/* Pending Attachments Preview */}
-                {pendingAttachments.length > 0 && (
-                  <div className="flex flex-wrap gap-2 p-2 mb-2 bg-muted/30 rounded-lg">
-                    {pendingAttachments.map((att) => (
-                      <div key={att.id} className="relative group">
-                        {att.attachment.type === "image" ? (
-                          <img
-                            src={att.previewUrl}
-                            alt={att.file.name}
-                            className="w-16 h-16 object-cover rounded-lg border"
-                          />
-                        ) : (
-                          <div className="w-16 h-16 bg-muted rounded-lg border flex flex-col items-center justify-center p-1">
-                            <svg
-                              className="w-6 h-6 text-muted-foreground"
-                              fill="none"
-                              viewBox="0 0 24 24"
-                              stroke="currentColor"
-                            >
-                              <path
-                                strokeLinecap="round"
-                                strokeLinejoin="round"
-                                strokeWidth={1.5}
-                                d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
-                              />
-                            </svg>
-                            <span className="text-[10px] text-muted-foreground truncate w-full text-center mt-1">
-                              {att.file.name.length > 10
-                                ? att.file.name.slice(0, 8) + "..."
-                                : att.file.name}
-                            </span>
-                          </div>
-                        )}
-                        {/* Loading overlay */}
-                        {att.status === "processing" && (
-                          <div className="absolute inset-0 bg-background/80 rounded-lg flex items-center justify-center">
-                            <Loader variant="dots" size="sm" />
-                          </div>
-                        )}
-                        {/* Error overlay */}
-                        {att.status === "error" && (
-                          <div className="absolute inset-0 bg-destructive/20 rounded-lg flex items-center justify-center">
-                            <span className="text-destructive text-xs">
-                              Error
-                            </span>
-                          </div>
-                        )}
-                        {/* Remove button */}
-                        <button
-                          onClick={() => removePendingAttachment(att.id)}
-                          className="absolute -top-1.5 -right-1.5 bg-destructive text-destructive-foreground rounded-full p-0.5 opacity-0 group-hover:opacity-100 transition-opacity"
-                          type="button"
-                        >
-                          <XIcon className="w-3 h-3" />
-                        </button>
-                      </div>
-                    ))}
+                  {/* Scroll to bottom button - inside ChatContainerRoot for context, outside ChatContainerContent so it doesn't scroll */}
+                  <div className="absolute inset-0 pointer-events-none z-10 flex items-end justify-end p-4">
+                    <ScrollButton className="shadow-md pointer-events-auto" />
                   </div>
-                )}
-
-                <PromptInput
-                  value={input}
-                  onValueChange={setInput}
-                  isLoading={isLoading}
-                  onSubmit={handleSubmit}
-                  className=""
-                >
-                  <PromptInputTextarea placeholder={placeholder} />
-                  <PromptInputActions className="flex justify-between">
-                    <div>
-                      <PromptInputAction
-                        tooltip={
-                          attachmentsEnabled
-                            ? "Attach files"
-                            : attachmentsDisabledTooltip
-                        }
-                      >
-                        <label
-                          htmlFor={fileInputId}
-                          className={cn(
-                            "csdk-button-attach flex h-8 w-8 items-center justify-center rounded-2xl",
-                            attachmentsEnabled
-                              ? "hover:bg-secondary-foreground/10 cursor-pointer"
-                              : "opacity-50 cursor-not-allowed",
+                </ChatContainerRoot>
+              </div>
+
+              {/* Suggestions */}
+              {suggestions.length > 0 && !isLoading && (
+                <Suggestions
+                  suggestions={suggestions}
+                  onSuggestionClick={handleSuggestionClick}
+                  className={classNames.suggestions}
+                />
+              )}
+
+              {/* Input */}
+              {renderInput ? (
+                renderInput()
+              ) : (
+                <div className={cn("p-2 pt-0", classNames.input)}>
+                  {/* Pending Attachments Preview */}
+                  {pendingAttachments.length > 0 && (
+                    <div className="flex flex-wrap gap-2 p-2 mb-2 bg-muted/30 rounded-lg">
+                      {pendingAttachments.map((att) => (
+                        <div key={att.id} className="relative group">
+                          {att.attachment.type === "image" ? (
+                            <img
+                              src={att.previewUrl}
+                              alt={att.file.name}
+                              className="w-16 h-16 object-cover rounded-lg border"
+                            />
+                          ) : (
+                            <div className="w-16 h-16 bg-muted rounded-lg border flex flex-col items-center justify-center p-1">
+                              <svg
+                                className="w-6 h-6 text-muted-foreground"
+                                fill="none"
+                                viewBox="0 0 24 24"
+                                stroke="currentColor"
+                              >
+                                <path
+                                  strokeLinecap="round"
+                                  strokeLinejoin="round"
+                                  strokeWidth={1.5}
+                                  d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+                                />
+                              </svg>
+                              <span className="text-[10px] text-muted-foreground truncate w-full text-center mt-1">
+                                {att.file.name.length > 10
+                                  ? att.file.name.slice(0, 8) + "..."
+                                  : att.file.name}
+                              </span>
+                            </div>
                           )}
-                        >
-                          <input
-                            ref={fileInputRef}
-                            type="file"
-                            multiple
-                            accept={acceptString}
-                            onChange={handleInputChange}
-                            className="hidden"
-                            id={fileInputId}
-                            disabled={!attachmentsEnabled}
-                          />
-                          <PlusIcon className="text-primary size-5" />
-                        </label>
-                      </PromptInputAction>
+                          {/* Loading overlay */}
+                          {att.status === "processing" && (
+                            <div className="absolute inset-0 bg-background/80 rounded-lg flex items-center justify-center">
+                              <Loader variant="dots" size="sm" />
+                            </div>
+                          )}
+                          {/* Error overlay */}
+                          {att.status === "error" && (
+                            <div className="absolute inset-0 bg-destructive/20 rounded-lg flex items-center justify-center">
+                              <span className="text-destructive text-xs">
+                                Error
+                              </span>
+                            </div>
+                          )}
+                          {/* Remove button */}
+                          <button
+                            onClick={() => removePendingAttachment(att.id)}
+                            className="absolute -top-1.5 -right-1.5 bg-destructive text-destructive-foreground rounded-full p-0.5 opacity-0 group-hover:opacity-100 transition-opacity"
+                            type="button"
+                          >
+                            <XIcon className="w-3 h-3" />
+                          </button>
+                        </div>
+                      ))}
                     </div>
-                    <PromptInputAction tooltip={isLoading ? "Stop" : "Send"}>
-                      {isLoading ? (
-                        <Button
-                          size="sm"
-                          variant="destructive"
-                          className="csdk-button-stop rounded-full size-9"
-                          onClick={onStop}
-                        >
-                          <StopIcon className="h-4 w-4" />
-                        </Button>
-                      ) : (
-                        <Button
-                          size="sm"
-                          className="csdk-button-send rounded-full size-9"
-                          onClick={handleSubmit}
-                          disabled={
-                            !input.trim() &&
-                            !pendingAttachments.some(
-                              (att) => att.status === "ready",
-                            )
+                  )}
+
+                  <PromptInput
+                    value={input}
+                    onValueChange={setInput}
+                    isLoading={isLoading}
+                    onSubmit={handleSubmit}
+                    className=""
+                  >
+                    <PromptInputTextarea placeholder={placeholder} />
+                    <PromptInputActions className="flex justify-between">
+                      <div>
+                        <PromptInputAction
+                          tooltip={
+                            attachmentsEnabled
+                              ? "Attach files"
+                              : attachmentsDisabledTooltip
                           }
                         >
-                          <ArrowUpIcon className="h-4 w-4" />
-                        </Button>
-                      )}
-                    </PromptInputAction>
-                  </PromptInputActions>
-                </PromptInput>
-              </div>
-            )}
-          </>
-        )}
+                          <label
+                            htmlFor={fileInputId}
+                            className={cn(
+                              "csdk-button-attach flex h-8 w-8 items-center justify-center rounded-2xl",
+                              attachmentsEnabled
+                                ? "hover:bg-secondary-foreground/10 cursor-pointer"
+                                : "opacity-50 cursor-not-allowed",
+                            )}
+                          >
+                            <input
+                              ref={fileInputRef}
+                              type="file"
+                              multiple
+                              accept={acceptString}
+                              onChange={handleInputChange}
+                              className="hidden"
+                              id={fileInputId}
+                              disabled={!attachmentsEnabled}
+                            />
+                            <PlusIcon className="text-primary size-5" />
+                          </label>
+                        </PromptInputAction>
+                      </div>
+                      <PromptInputAction tooltip={isLoading ? "Stop" : "Send"}>
+                        {isLoading ? (
+                          <Button
+                            size="sm"
+                            variant="destructive"
+                            className="csdk-button-stop rounded-full size-9"
+                            onClick={onStop}
+                          >
+                            <StopIcon className="h-4 w-4" />
+                          </Button>
+                        ) : (
+                          <Button
+                            size="sm"
+                            className="csdk-button-send rounded-full size-9"
+                            onClick={handleSubmit}
+                            disabled={
+                              !input.trim() &&
+                              !pendingAttachments.some(
+                                (att) => att.status === "ready",
+                              )
+                            }
+                          >
+                            <ArrowUpIcon className="h-4 w-4" />
+                          </Button>
+                        )}
+                      </PromptInputAction>
+                    </PromptInputActions>
+                  </PromptInput>
+                </div>
+              )}
+            </>
+          )}
 
-        {/* Root-level custom Footer (shows in both views) */}
-        {rootFooter}
-      </div>
-    </CopilotChatContext.Provider>
+          {/* Root-level custom Footer (shows in both views) */}
+          {rootFooter}
+        </div>
+      </CopilotChatContext.Provider>
+    </MessageActionsProvider>
   );
 }
 
@@ -1310,6 +1334,12 @@ export const Chat = Object.assign(ChatComponent, {
   Suggestions: SuggestionsCompound,
   BackButton, // Navigation: start new chat
   ThreadPicker: ThreadPickerCompound, // Thread switching
+  // Message actions compound components
+  MessageActions,
+  CopyAction,
+  EditAction,
+  FeedbackAction,
+  Action: MessageAction,
 });
 
 // Re-export compound components for direct access and TypeScript declarations
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index 836731d..ca26f04 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -24,6 +24,79 @@ import CopilotSDKLogo from "../../icons/copilot-sdk-logo";
 import { SourceGroup, type SourceItem } from "../../ui/source";
 import { BranchNavigator } from "../../ui/branch-navigator";
 import type { BranchInfo } from "../../../../chat/branching";
+import { useMessageActionsContext } from "./message-actions-context";
+import { CheckIcon, CopyIcon } from "./message-actions-compound";
+
+// ─── FloatingActions ──────────────────────────────────────────────────────────
+
+function FloatingActions({
+  message,
+  role,
+  align = "left",
+  onEdit,
+}: {
+  message: ChatMessage;
+  role: "user" | "assistant";
+  align?: "left" | "right";
+  onEdit?: () => void;
+}) {
+  const ctx = useMessageActionsContext();
+  const [copiedId, setCopiedId] = React.useState<string | null>(null);
+
+  if (!ctx) return null;
+  const actions = ctx.getActions(role);
+  if (actions.length === 0) return null;
+
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-0.5 mt-1",
+        "opacity-0 group-hover/message:opacity-100 transition-opacity duration-150",
+        align === "right" ? "justify-end" : "justify-start",
+      )}
+    >
+      {actions.map((action) => {
+        const isHidden =
+          typeof action.hidden === "function"
+            ? action.hidden({ message })
+            : action.hidden;
+        if (isHidden) return null;
+
+        const isCopied = copiedId === action.id;
+
+        return (
+          <button
+            key={action.id}
+            type="button"
+            title={action.tooltip}
+            aria-label={action.tooltip}
+            className={cn(
+              "flex items-center justify-center size-6 rounded-md",
+              "text-muted-foreground hover:text-foreground hover:bg-muted",
+              "transition-colors",
+              action.className,
+            )}
+            onClick={() => {
+              if (action.id === "edit" && onEdit) {
+                onEdit();
+                return;
+              }
+              if (action.id === "copy") {
+                navigator.clipboard.writeText(message.content ?? "");
+                setCopiedId("copy");
+                setTimeout(() => setCopiedId(null), 1500);
+                return;
+              }
+              action.onClick({ message });
+            }}
+          >
+            {action.id === "copy" && isCopied ? <CheckIcon /> : action.icon}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
 
 type DefaultMessageProps = {
   message: ChatMessage;
@@ -341,7 +414,9 @@ export function DefaultMessage({
       message.attachments && message.attachments.length > 0;
 
     return (
-      <Message className={cn("flex gap-2 group/user-msg justify-end")}>
+      <Message
+        className={cn("flex gap-2 group/user-msg group/message justify-end")}
+      >
         <div className="flex flex-col items-end max-w-[80%] min-w-0">
           {/* Edit mode: inline textarea */}
           {isEditing ? (
@@ -451,6 +526,13 @@ export function DefaultMessage({
                   className="mt-1"
                 />
               )}
+              {/* Floating actions for user messages */}
+              <FloatingActions
+                message={message}
+                role="user"
+                align="right"
+                onEdit={onEditMessage ? startEdit : undefined}
+              />
             </>
           )}
         </div>
@@ -525,7 +607,7 @@ export function DefaultMessage({
 
   // Assistant message - left aligned with avatar
   return (
-    <Message className="flex gap-2">
+    <Message className="flex gap-2 group/message">
       <MessageAvatar
         src={assistantAvatar.src}
         alt="Assistant"
@@ -834,6 +916,9 @@ export function DefaultMessage({
                 buttonClassName={followUpButtonClassName}
               />
             )}
+
+            {/* Floating actions for assistant messages */}
+            <FloatingActions message={message} role="assistant" align="left" />
           </>
         )}
       </div>
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/index.ts b/packages/copilot-sdk/src/ui/components/composed/chat/index.ts
index c6745c5..32ba090 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/index.ts
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/index.ts
@@ -1,4 +1,21 @@
 export { Chat, useCopilotChatContext } from "./chat";
+export { MessageList } from "./message-list";
+export type { MessageListProps } from "./message-list";
+export {
+  MessageActions,
+  CopyAction,
+  EditAction,
+  FeedbackAction,
+  Action as MessageActionItem,
+} from "./message-actions-compound";
+export type {
+  MessageActionsProps,
+  CopyActionProps,
+  EditActionProps,
+  FeedbackActionProps,
+  ActionProps,
+} from "./message-actions-compound";
+export type { RegisteredAction } from "./message-actions-context";
 export type {
   HomeViewProps,
   HomeProps,
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-compound.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-compound.tsx
new file mode 100644
index 0000000..cd155f2
--- /dev/null
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-compound.tsx
@@ -0,0 +1,291 @@
+"use client";
+
+import React, {
+  useLayoutEffect,
+  useMemo,
+  createContext,
+  useContext,
+} from "react";
+import {
+  useMessageActionsContext,
+  type RegisteredAction,
+} from "./message-actions-context";
+import type { ChatMessage } from "./types";
+
+// ─── Role sub-context ────────────────────────────────────────────────────────
+
+const RoleContext = createContext<"user" | "assistant" | null>(null);
+
+// ─── Built-in action icons ────────────────────────────────────────────────────
+
+function CopyIcon() {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+      <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+    </svg>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M20 6L9 17l-5-5" />
+    </svg>
+  );
+}
+
+function EditIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" />
+      <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z" />
+    </svg>
+  );
+}
+
+function ThumbsUpIcon() {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M7 10v12" />
+      <path d="M15 5.88 14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H4a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L12 2a3.13 3.13 0 0 1 3 3.88Z" />
+    </svg>
+  );
+}
+
+function ThumbsDownIcon() {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M17 14V2" />
+      <path d="M9 18.12 10 14H4.17a2 2 0 0 1-1.92-2.56l2.33-8A2 2 0 0 1 6.5 2H20a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-2.76a2 2 0 0 0-1.79 1.11L12 22a3.13 3.13 0 0 1-3-3.88Z" />
+    </svg>
+  );
+}
+
+// ─── CopyAction ───────────────────────────────────────────────────────────────
+
+export interface CopyActionProps {
+  tooltip?: string;
+  className?: string;
+}
+
+/** Built-in copy-to-clipboard action. Use inside CopilotChat.MessageActions. */
+export function CopyAction({ tooltip = "Copy", className }: CopyActionProps) {
+  return null; // declarative marker — rendered by MessageActions
+}
+CopyAction.displayName = "CopyAction";
+
+// ─── EditAction ───────────────────────────────────────────────────────────────
+
+export interface EditActionProps {
+  tooltip?: string;
+  className?: string;
+}
+
+/** Built-in edit action for user messages. Use inside CopilotChat.MessageActions role="user". */
+export function EditAction({ tooltip = "Edit", className }: EditActionProps) {
+  return null;
+}
+EditAction.displayName = "EditAction";
+
+// ─── FeedbackAction ───────────────────────────────────────────────────────────
+
+export interface FeedbackActionProps {
+  onFeedback?: (message: ChatMessage, type: "helpful" | "not-helpful") => void;
+  tooltip?: string;
+  className?: string;
+}
+
+/** Built-in thumbs up/down feedback action. Use inside CopilotChat.MessageActions. */
+export function FeedbackAction({
+  onFeedback,
+  tooltip = "Feedback",
+  className,
+}: FeedbackActionProps) {
+  return null;
+}
+FeedbackAction.displayName = "FeedbackAction";
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export interface ActionProps {
+  id?: string;
+  icon: React.ReactNode;
+  tooltip: string;
+  onClick: (props: { message: ChatMessage }) => void;
+  hidden?: boolean | ((props: { message: ChatMessage }) => boolean);
+  className?: string;
+}
+
+/** Custom action button. Use inside CopilotChat.MessageActions. */
+export function Action({
+  icon,
+  tooltip,
+  onClick,
+  hidden,
+  className,
+}: ActionProps) {
+  return null;
+}
+Action.displayName = "Action";
+
+// ─── MessageActions ───────────────────────────────────────────────────────────
+
+export interface MessageActionsProps {
+  role: "user" | "assistant";
+  children?: React.ReactNode;
+}
+
+/**
+ * Registers message actions for a specific role.
+ * Place inside <CopilotChat> as a direct child.
+ *
+ * @example
+ * ```tsx
+ * <CopilotChat>
+ *   <CopilotChat.MessageActions role="assistant">
+ *     <CopilotChat.CopyAction />
+ *     <CopilotChat.FeedbackAction onFeedback={(msg, type) => log(type)} />
+ *     <CopilotChat.Action icon={<ShareIcon />} tooltip="Share" onClick={({ message }) => share(message)} />
+ *   </CopilotChat.MessageActions>
+ *
+ *   <CopilotChat.MessageActions role="user">
+ *     <CopilotChat.EditAction />
+ *   </CopilotChat.MessageActions>
+ * </CopilotChat>
+ * ```
+ */
+export function MessageActions({ role, children }: MessageActionsProps) {
+  const ctx = useMessageActionsContext();
+
+  // Extract action definitions from declarative children
+  const actions = useMemo<RegisteredAction[]>(() => {
+    const result: RegisteredAction[] = [];
+
+    React.Children.forEach(children, (child) => {
+      if (!React.isValidElement(child)) return;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const props = child.props as any;
+      const type = child.type;
+
+      if (
+        type === CopyAction ||
+        (child.type as { displayName?: string })?.displayName === "CopyAction"
+      ) {
+        // Copy — stateful, rendered specially in DefaultMessage
+        result.push({
+          id: "copy",
+          icon: <CopyIcon />,
+          tooltip: props.tooltip ?? "Copy",
+          onClick: ({ message }) => {
+            navigator.clipboard.writeText(message.content ?? "");
+          },
+          className: props.className,
+        });
+      } else if (
+        type === EditAction ||
+        (child.type as { displayName?: string })?.displayName === "EditAction"
+      ) {
+        result.push({
+          id: "edit",
+          icon: <EditIcon />,
+          tooltip: props.tooltip ?? "Edit",
+          onClick: () => {}, // handled internally by DefaultMessage via onEditMessage
+          className: props.className,
+        });
+      } else if (
+        type === FeedbackAction ||
+        (child.type as { displayName?: string })?.displayName ===
+          "FeedbackAction"
+      ) {
+        const onFeedback = props.onFeedback;
+        result.push(
+          {
+            id: "feedback-up",
+            icon: <ThumbsUpIcon />,
+            tooltip: "Helpful",
+            onClick: ({ message }) => onFeedback?.(message, "helpful"),
+            className: props.className,
+          },
+          {
+            id: "feedback-down",
+            icon: <ThumbsDownIcon />,
+            tooltip: "Not helpful",
+            onClick: ({ message }) => onFeedback?.(message, "not-helpful"),
+            className: props.className,
+          },
+        );
+      } else if (
+        type === Action ||
+        (child.type as { displayName?: string })?.displayName === "Action"
+      ) {
+        result.push({
+          id: props.id ?? props.tooltip,
+          icon: props.icon,
+          tooltip: props.tooltip,
+          onClick: props.onClick,
+          hidden: props.hidden,
+          className: props.className,
+        });
+      }
+    });
+
+    return result;
+  }, [children]);
+
+  useLayoutEffect(() => {
+    if (!ctx) return;
+    ctx.registerActions(role, actions);
+    return () => ctx.clearActions(role);
+  }, [ctx, role, actions]);
+
+  return null;
+}
+
+// Re-export CheckIcon for DefaultMessage copy state
+export { CopyIcon, CheckIcon, EditIcon };
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-context.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-context.tsx
new file mode 100644
index 0000000..4cf32ff
--- /dev/null
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-context.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import React, { createContext, useContext, useState, useCallback } from "react";
+import type { ChatMessage } from "./types";
+
+export interface RegisteredAction {
+  id: string;
+  icon: React.ReactNode;
+  tooltip: string;
+  onClick: (props: { message: ChatMessage }) => void;
+  hidden?: boolean | ((props: { message: ChatMessage }) => boolean);
+  className?: string;
+}
+
+interface MessageActionsContextType {
+  getActions: (role: "user" | "assistant") => RegisteredAction[];
+  registerActions: (
+    role: "user" | "assistant",
+    actions: RegisteredAction[],
+  ) => void;
+  clearActions: (role: "user" | "assistant") => void;
+}
+
+const MessageActionsContext = createContext<MessageActionsContextType | null>(
+  null,
+);
+
+export function MessageActionsProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const [registry, setRegistry] = useState<Record<string, RegisteredAction[]>>(
+    {},
+  );
+
+  const registerActions = useCallback(
+    (role: "user" | "assistant", actions: RegisteredAction[]) => {
+      setRegistry((prev) => ({ ...prev, [role]: actions }));
+    },
+    [],
+  );
+
+  const clearActions = useCallback((role: "user" | "assistant") => {
+    setRegistry((prev) => {
+      const next = { ...prev };
+      delete next[role];
+      return next;
+    });
+  }, []);
+
+  const getActions = useCallback(
+    (role: "user" | "assistant") => registry[role] ?? [],
+    [registry],
+  );
+
+  return (
+    <MessageActionsContext.Provider
+      value={{ getActions, registerActions, clearActions }}
+    >
+      {children}
+    </MessageActionsContext.Provider>
+  );
+}
+
+export function useMessageActionsContext() {
+  return useContext(MessageActionsContext);
+}
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/message-list.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/message-list.tsx
new file mode 100644
index 0000000..e18d0c7
--- /dev/null
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/message-list.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import * as React from "react";
+import { useCopilotChatContext } from "./chat";
+import { DefaultMessage } from "./default-message";
+import type { ChatMessage } from "./types";
+
+export interface MessageListProps {
+  /**
+   * Render function called for each message.
+   * Return your own component or fall back to <Chat.DefaultMessage />.
+   *
+   * @example
+   * ```tsx
+   * <Chat.MessageList>
+   *   {(message) =>
+   *     message.metadata?.type === "plan"
+   *       ? <PlanCard key={message.id} data={message.metadata} />
+   *       : <Chat.DefaultMessage key={message.id} message={message} />
+   *   }
+   * </Chat.MessageList>
+   * ```
+   */
+  children?: (message: ChatMessage, index: number) => React.ReactNode;
+  className?: string;
+}
+
+/**
+ * Chat.MessageList — renders the message list using a render-prop pattern.
+ * Must be used inside <CopilotChat>.
+ *
+ * If no children are provided, renders all messages with the default SDK layout.
+ */
+export function MessageList({ children, className }: MessageListProps) {
+  const { messages, registeredTools } = useCopilotChatContext();
+
+  return (
+    <div className={className}>
+      {messages.map((message, index) => {
+        if (children) {
+          return (
+            <React.Fragment key={message.id}>
+              {children(message, index)}
+            </React.Fragment>
+          );
+        }
+        return (
+          <DefaultMessage
+            key={message.id}
+            message={message}
+            userAvatar={{ fallback: "U" }}
+            assistantAvatar={{ fallback: "AI" }}
+            registeredTools={registeredTools}
+            isLastMessage={index === messages.length - 1}
+          />
+        );
+      })}
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/src/ui/index.ts b/packages/copilot-sdk/src/ui/index.ts
index e21b9cf..b816373 100644
--- a/packages/copilot-sdk/src/ui/index.ts
+++ b/packages/copilot-sdk/src/ui/index.ts
@@ -291,3 +291,78 @@ export type { MCPUIFrameProps } from "../mcp/ui/types";
 // Utilities
 // ============================================
 export { cn } from "./lib/utils";
+
+// ============================================
+// Chat Primitives (headless composition API)
+// ============================================
+import { DefaultMessage } from "./components/composed/chat/default-message";
+import { ChatHeader } from "./components/composed/chat/chat-header";
+import { ChatWelcome } from "./components/composed/chat/chat-welcome";
+import { MessageList } from "./components/composed/chat/message-list";
+import {
+  Message,
+  MessageAvatar as MsgAvatar,
+  MessageContent as MsgContent,
+  MessageActions,
+  MessageAction,
+} from "./components/ui/message";
+import { PromptInput } from "./components/ui/prompt-input";
+import { Loader } from "./components/ui/loader";
+import { ChatContainerScrollAnchor } from "./components/ui/chat-container";
+
+/**
+ * ChatPrimitives — composable primitives for building custom chat layouts.
+ * Must be used inside <CopilotChat>.
+ *
+ * @example
+ * ```tsx
+ * import { ChatPrimitives as Chat } from '@yourgpt/copilot-sdk-ui';
+ *
+ * <CopilotChat>
+ *   <Chat.Header />
+ *   <Chat.MessageList>
+ *     {(message) =>
+ *       message.metadata?.type === "plan"
+ *         ? <PlanCard key={message.id} />
+ *         : <Chat.DefaultMessage key={message.id} message={message} />
+ *     }
+ *   </Chat.MessageList>
+ *   <Chat.Input />
+ * </CopilotChat>
+ * ```
+ */
+export const ChatPrimitives = {
+  // ── List ──────────────────────────────────────────────
+  /** Renders the message list via render-prop. Falls back to DefaultMessage if no children. */
+  MessageList,
+
+  // ── Messages ──────────────────────────────────────────
+  /** Full SDK message bubble (user + assistant + tools). Use as fallback inside MessageList. */
+  DefaultMessage,
+  /** Low-level message row wrapper (flex layout + avatar slot) */
+  Message,
+  /** Message avatar — image with fallback text/icon */
+  MessageAvatar: MsgAvatar,
+  /** Message content bubble — supports markdown */
+  MessageContent: MsgContent,
+  /** Action bar below a message (copy, feedback, etc.) */
+  MessageActions,
+  /** Single action button with tooltip inside MessageActions */
+  MessageAction,
+
+  // ── Layout ────────────────────────────────────────────
+  /** Chat header bar with title and controls */
+  Header: ChatHeader,
+  /** Welcome screen shown when there are no messages */
+  Welcome: ChatWelcome,
+  /** Chat input / composer */
+  Input: PromptInput,
+  /** Scroll anchor — keeps the view pinned to the latest message */
+  ScrollAnchor: ChatContainerScrollAnchor,
+
+  // ── Indicators ────────────────────────────────────────
+  /** Loading / streaming indicator (dots, wave, typing variants) */
+  Loader,
+};
+
+export type { MessageListProps } from "./components/composed/chat/message-list";

From 5805a5ab127d1aad87a60a0aa370d34b3196098e Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Tue, 17 Mar 2026 18:48:22 +0530
Subject: [PATCH 25/72] feat(thread): enhance thread management with
 activeLeafId and persistence controls

- Updated the thread data structure to include an optional activeLeafId for preserving branch selection across reloads.
- Enhanced the ThreadManager to handle activeLeafId during thread creation and updates.
- Modified CopilotProvider and internal thread manager to support parentId and childrenIds for improved message hierarchy.
- Added an enabled flag to control thread management effects based on persistence settings, preventing unwanted interactions in non-persistent instances.
- Bumped version to 2.1.5-alpha.3 to reflect these changes.
---
 packages/copilot-sdk/package.json             |  2 +-
 packages/copilot-sdk/src/core/types/thread.ts |  5 ++
 .../src/react/provider/CopilotProvider.tsx    |  2 +
 .../copilot-sdk/src/thread/ThreadManager.ts   |  3 +
 .../ui/components/composed/connected-chat.tsx |  7 ++-
 .../src/ui/hooks/useInternalThreadManager.ts  | 55 +++++++++++++++++--
 6 files changed, 66 insertions(+), 8 deletions(-)

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index 817a87e..3ece582 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.5-alpha.2",
+  "version": "2.1.5-alpha.4",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",
diff --git a/packages/copilot-sdk/src/core/types/thread.ts b/packages/copilot-sdk/src/core/types/thread.ts
index dc4029f..52b1bc8 100644
--- a/packages/copilot-sdk/src/core/types/thread.ts
+++ b/packages/copilot-sdk/src/core/types/thread.ts
@@ -26,6 +26,11 @@ export interface ThreadData extends Thread {
   messages: Message[];
   /** Sources from knowledge base for this thread */
   sources: Source[];
+  /**
+   * ID of the active leaf message (tip of the active branch path).
+   * Saved so the correct branch is restored after a page reload.
+   */
+  activeLeafId?: string;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 676c2e0..809b3c5 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -482,6 +482,8 @@ export function CopilotProvider({
         attachments: m.metadata?.attachments as MessageAttachment[] | undefined,
         toolCalls: m.tool_calls,
         toolCallId: m.tool_call_id,
+        parentId: m.parent_id,
+        childrenIds: m.children_ids,
       }),
     );
 
diff --git a/packages/copilot-sdk/src/thread/ThreadManager.ts b/packages/copilot-sdk/src/thread/ThreadManager.ts
index fc3330f..65b5597 100644
--- a/packages/copilot-sdk/src/thread/ThreadManager.ts
+++ b/packages/copilot-sdk/src/thread/ThreadManager.ts
@@ -103,6 +103,8 @@ export interface CreateThreadOptions {
   title?: string;
   /** Initial messages */
   messages?: Message[];
+  /** Active leaf message ID — preserves branch selection across reloads */
+  activeLeafId?: string;
 }
 
 /**
@@ -318,6 +320,7 @@ export class ThreadManager {
           )
         : undefined,
       messageCount: options?.messages?.length ?? 0,
+      activeLeafId: options?.activeLeafId,
     };
 
     // Use optimized create if available
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index b98e96c..76fa564 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -307,9 +307,12 @@ function CopilotChatBase(
   // Parse persistence config
   const persistenceConfig = parsePersistenceConfig(persistence, onThreadChange);
 
-  // Use internal thread manager when persistence is enabled
+  // Use internal thread manager when persistence is enabled.
+  // When persistence is disabled, pass enabled:false so no sync/restore effects
+  // fire — prevents the shared singleton from being touched by a no-persistence instance
+  // and avoids stale async createThread calls overwriting messages on navigation.
   const threadManagerResult = useInternalThreadManager(
-    persistenceConfig ?? { autoRestoreLastThread: false },
+    persistenceConfig ?? { autoRestoreLastThread: false, enabled: false },
   );
 
   const isPersistenceEnabled = !!persistence;
diff --git a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
index ff24f7d..7e3d5d0 100644
--- a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
+++ b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
@@ -33,6 +33,13 @@ export interface UseInternalThreadManagerConfig {
   autoRestoreLastThread?: boolean;
   /** Callback when thread changes */
   onThreadChange?: (threadId: string | null) => void;
+  /**
+   * Whether thread management is active.
+   * When false, all sync/restore effects are skipped.
+   * Used by CopilotChat when persistence is disabled to avoid touching the shared singleton.
+   * @default true
+   */
+  enabled?: boolean;
 }
 
 export interface UseInternalThreadManagerReturn {
@@ -60,6 +67,7 @@ export function useInternalThreadManager(
     saveDebounce = 1000,
     autoRestoreLastThread = true,
     onThreadChange,
+    enabled = true,
   } = config;
 
   // Thread management
@@ -81,7 +89,14 @@ export function useInternalThreadManager(
   } = threadManager;
 
   // Get copilot context for setMessages and status
-  const { messages, setMessages, status, isLoading, getAllMessages } = useCopilot();
+  const {
+    messages,
+    setMessages,
+    status,
+    isLoading,
+    getAllMessages,
+    switchBranch,
+  } = useCopilot();
 
   // Track if we're in the middle of loading messages from a thread switch
   const isLoadingMessagesRef = useRef(false);
@@ -145,6 +160,10 @@ export function useInternalThreadManager(
         lastSavedSnapshotRef.current = getMessageSnapshot(uiMessages);
         savingToThreadRef.current = threadId;
         setMessages(uiMessages);
+        // Restore active branch after tree is rebuilt
+        if (thread.activeLeafId) {
+          switchBranch(thread.activeLeafId);
+        }
       } else {
         lastSavedSnapshotRef.current = "";
         savingToThreadRef.current = threadId;
@@ -159,7 +178,13 @@ export function useInternalThreadManager(
         isLoadingMessagesRef.current = false;
       });
     },
-    [switchThread, setMessages, getMessageSnapshot, onThreadChange],
+    [
+      switchThread,
+      setMessages,
+      switchBranch,
+      getMessageSnapshot,
+      onThreadChange,
+    ],
   );
 
   // Handle new thread - just clear messages, thread is created lazily on first message
@@ -183,6 +208,8 @@ export function useInternalThreadManager(
 
   // Auto-restore: load messages when thread is restored from storage
   useEffect(() => {
+    // Skip if persistence is disabled
+    if (!enabled) return;
     // Skip if already initialized or no thread restored yet
     if (hasInitializedRef.current || !currentThread) {
       return;
@@ -211,6 +238,10 @@ export function useInternalThreadManager(
       lastSavedSnapshotRef.current = getMessageSnapshot(uiMessages);
       savingToThreadRef.current = currentThread.id;
       setMessages(uiMessages);
+      // Restore active branch after tree is rebuilt
+      if (currentThread.activeLeafId) {
+        switchBranch(currentThread.activeLeafId);
+      }
     } else {
       lastSavedSnapshotRef.current = "";
       savingToThreadRef.current = currentThread.id;
@@ -222,10 +253,20 @@ export function useInternalThreadManager(
     requestAnimationFrame(() => {
       isLoadingMessagesRef.current = false;
     });
-  }, [adapter, currentThread, setMessages, getMessageSnapshot, onThreadChange]);
+  }, [
+    enabled,
+    adapter,
+    currentThread,
+    setMessages,
+    switchBranch,
+    getMessageSnapshot,
+    onThreadChange,
+  ]);
 
   // Sync messages to storage when streaming completes
   useEffect(() => {
+    // Skip if persistence is disabled
+    if (!enabled) return;
     // Skip if we're loading messages from a thread switch
     if (isLoadingMessagesRef.current) {
       return;
@@ -253,11 +294,14 @@ export function useInternalThreadManager(
       allUIMessages.length > 0 ? allUIMessages : messages,
     );
 
+    // Active leaf = last message on the visible path — persisted so reload restores the right branch
+    const activeLeafId = messages[messages.length - 1]?.id;
+
     // If no thread exists, create one with these messages
     if (!currentThreadId && !savingToThreadRef.current) {
       // Set ref immediately to prevent race condition with rapid messages
       savingToThreadRef.current = "creating";
-      createThread({ messages: coreMessages }).then((thread) => {
+      createThread({ messages: coreMessages, activeLeafId }).then((thread) => {
         lastSavedSnapshotRef.current = currentSnapshot;
         savingToThreadRef.current = thread.id;
         onThreadChange?.(thread.id);
@@ -274,9 +318,10 @@ export function useInternalThreadManager(
     }
 
     // Update existing thread
-    updateCurrentThread({ messages: coreMessages });
+    updateCurrentThread({ messages: coreMessages, activeLeafId });
     lastSavedSnapshotRef.current = currentSnapshot;
   }, [
+    enabled,
     adapter,
     messages,
     currentThreadId,

From 90767d600743f68e12c33b0831317d10158370d5 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Fri, 20 Mar 2026 00:22:02 +0530
Subject: [PATCH 26/72] feat(alpha): document and demo all alpha features
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docs (apps/docs):
- Convert chat.mdx → chat/ folder with branching + message-actions sub-pages
- Convert smart-ai-context.mdx → context/ folder with compaction, token-tracking, session sub-pages
- Convert customizations.mdx → customizations/ folder with chat-primitives + custom-message-view sub-pages
- Add skills/ section (index, client, server)
- Add tools/deferred-tools.mdx and tools/hidden-tools.mdx
- All new alpha pages marked Beta in sidebar badge and page callout

Playground (examples/playground):
- Add AlphaConfig type with message actions, branching, skills, context management, tools, custom message view
- Add AlphaFeaturesSection control panel accordion with all toggles
- Add ContextStatsBar (useContextStats token usage display)
- Add HiddenAnalyticsTool (hidden: true demo) and DeferredSearchTool (deferLoading: true demo)
- Wire SkillProvider with brand-voice (eager) and code-review (auto) skills
- Add CopilotChat.MessageActions (Copy, Edit, Feedback) to all three layouts
- Add messageView custom footer demo
- All alpha config persisted to localStorage

SDK (packages/copilot-sdk):
- Forward MessageActions, CopyAction, EditAction, FeedbackAction onto CopilotChat export in connected-chat.tsx

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/docs/content/docs/chat/branching.mdx     | 210 ++++++++++++++
 .../content/docs/{chat.mdx => chat/index.mdx} |   3 +-
 .../content/docs/chat/message-actions.mdx     | 158 +++++++++++
 apps/docs/content/docs/chat/meta.json         |   9 +
 apps/docs/content/docs/context/compaction.mdx | 205 ++++++++++++++
 .../index.mdx}                                | 206 ++------------
 apps/docs/content/docs/context/meta.json      |  10 +
 apps/docs/content/docs/context/session.mdx    |  99 +++++++
 .../content/docs/context/token-tracking.mdx   | 130 +++++++++
 .../docs/customizations/chat-primitives.mdx   | 174 ++++++++++++
 .../customizations/custom-message-view.mdx    | 116 ++++++++
 .../index.mdx}                                |   3 +-
 .../content/docs/customizations/meta.json     |   9 +
 apps/docs/content/docs/meta.json              |   3 +-
 .../content/docs/tools/deferred-tools.mdx     |  96 +++++++
 apps/docs/content/docs/tools/hidden-tools.mdx |  70 +++++
 apps/docs/content/docs/tools/meta.json        |   9 +-
 examples/playground/app/page.tsx              |   5 +
 .../playground/AlphaFeaturesSection.tsx       | 265 ++++++++++++++++++
 .../components/playground/ContextStatsBar.tsx |  41 +++
 .../components/playground/ControlPanel.tsx    |  38 +++
 .../components/playground/CopilotPanel.tsx    |  68 ++++-
 .../components/playground/CopilotSidebar.tsx  |   4 +
 .../components/playground/DashboardTools.tsx  | 111 ++++++++
 .../playground/layouts/DefaultLayout.tsx      |  61 +++-
 .../playground/layouts/SaasLayout.tsx         |  26 +-
 .../playground/layouts/SupportLayout.tsx      |  30 +-
 .../playground/hooks/usePlaygroundConfig.ts   |  20 ++
 examples/playground/lib/constants.ts          |  18 ++
 examples/playground/lib/types.ts              |  27 ++
 examples/playground/package.json              |   4 +-
 .../ui/components/composed/connected-chat.tsx |   6 +
 .../src/ui/components/ui/message.tsx          |   4 +-
 pnpm-lock.yaml                                | 195 ++++---------
 34 files changed, 2100 insertions(+), 333 deletions(-)
 create mode 100644 apps/docs/content/docs/chat/branching.mdx
 rename apps/docs/content/docs/{chat.mdx => chat/index.mdx} (96%)
 create mode 100644 apps/docs/content/docs/chat/message-actions.mdx
 create mode 100644 apps/docs/content/docs/chat/meta.json
 create mode 100644 apps/docs/content/docs/context/compaction.mdx
 rename apps/docs/content/docs/{smart-ai-context.mdx => context/index.mdx} (51%)
 create mode 100644 apps/docs/content/docs/context/meta.json
 create mode 100644 apps/docs/content/docs/context/session.mdx
 create mode 100644 apps/docs/content/docs/context/token-tracking.mdx
 create mode 100644 apps/docs/content/docs/customizations/chat-primitives.mdx
 create mode 100644 apps/docs/content/docs/customizations/custom-message-view.mdx
 rename apps/docs/content/docs/{customizations.mdx => customizations/index.mdx} (97%)
 create mode 100644 apps/docs/content/docs/customizations/meta.json
 create mode 100644 apps/docs/content/docs/tools/deferred-tools.mdx
 create mode 100644 apps/docs/content/docs/tools/hidden-tools.mdx
 create mode 100644 examples/playground/components/playground/AlphaFeaturesSection.tsx
 create mode 100644 examples/playground/components/playground/ContextStatsBar.tsx

diff --git a/apps/docs/content/docs/chat/branching.mdx b/apps/docs/content/docs/chat/branching.mdx
new file mode 100644
index 0000000..2f659de
--- /dev/null
+++ b/apps/docs/content/docs/chat/branching.mdx
@@ -0,0 +1,210 @@
+---
+title: Conversation Branching
+description: Edit messages to create parallel conversation paths, just like ChatGPT and Claude.ai
+icon: GitBranch
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+Edit any user message to create a parallel conversation path, preserving the original. Navigate between variants with `← N/M →` — the same UX as ChatGPT, Claude.ai, and Gemini.
+
+---
+
+## Zero-Config Usage
+
+If you use `<CopilotChat />`, branching is **already active**. No code changes needed.
+
+- Edit button (✏) appears on hover over any user message
+- `← 1/2 →` navigator appears below user messages when variants exist
+- Regenerate creates a new branch instead of overwriting
+
+```tsx
+// Nothing to add — branching works out of the box
+<CopilotChat className="h-[600px]" />
+```
+
+---
+
+## New APIs
+
+### `useCopilot()` / `useCopilotProvider`
+
+```typescript
+const {
+  switchBranch,   // (messageId: string) => void
+  getBranchInfo,  // (messageId: string) => BranchInfo | null
+  editMessage,    // (messageId: string, newContent: string) => Promise<void>
+  hasBranches,    // boolean — true if any fork exists
+  getAllMessages,  // () => UIMessage[] — all branches, not just visible path
+} = useCopilot();
+```
+
+### `BranchInfo` type
+
+```typescript
+interface BranchInfo {
+  siblingIndex: number;    // 0-based — which variant this is
+  totalSiblings: number;   // how many variants exist at this fork
+  siblingIds: string[];    // ordered oldest-first
+  hasPrevious: boolean;
+  hasNext: boolean;
+}
+```
+
+### `BranchNavigator` component
+
+Standalone navigator for custom message renderers:
+
+```tsx
+import { BranchNavigator } from "@yourgpt/copilot-sdk/ui";
+
+<BranchNavigator
+  siblingIndex={info.siblingIndex}
+  totalSiblings={info.totalSiblings}
+  hasPrevious={info.hasPrevious}
+  hasNext={info.hasNext}
+  onPrevious={() => switchBranch(info.siblingIds[info.siblingIndex - 1])}
+  onNext={() => switchBranch(info.siblingIds[info.siblingIndex + 1])}
+/>
+```
+
+### `MessageTree` (framework-agnostic)
+
+```typescript
+import { MessageTree, type BranchInfo } from "@yourgpt/copilot-sdk";
+
+const tree = new MessageTree(messages);
+tree.getVisibleMessages(); // active path only (sent to AI)
+tree.getAllMessages();     // all branches (for persistence)
+tree.getBranchInfo(messageId); // BranchInfo | null
+tree.switchBranch(messageId);
+tree.hasBranches; // boolean
+```
+
+---
+
+## Manual Wiring (`<Chat />` users)
+
+Wire the three props from `useCopilot()`:
+
+```tsx
+function MyChat() {
+  const { switchBranch, getBranchInfo, editMessage } = useCopilot();
+
+  return (
+    <Chat
+      getBranchInfo={getBranchInfo}
+      onSwitchBranch={switchBranch}
+      onEditMessage={editMessage}
+    />
+  );
+}
+```
+
+---
+
+## Custom Message Renderers
+
+Use `getBranchInfo` + `BranchNavigator` in your own message components:
+
+```tsx
+function MyMessage({ message }) {
+  const { switchBranch, getBranchInfo } = useCopilot();
+  const info = message.role === "user" ? getBranchInfo(message.id) : null;
+
+  return (
+    <div>
+      <p>{message.content}</p>
+      {info && (
+        <BranchNavigator
+          {...info}
+          onPrevious={() => switchBranch(info.siblingIds[info.siblingIndex - 1])}
+          onNext={() => switchBranch(info.siblingIds[info.siblingIndex + 1])}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Programmatic Branching
+
+```typescript
+// Edit a message (creates new branch from same parent)
+await editMessage("msg-abc", "Updated question text");
+
+// Navigate between variants
+switchBranch("msg-xyz");
+
+// Check if branches exist
+if (hasBranches) {
+  const info = getBranchInfo("msg-abc");
+  console.log(info.totalSiblings, info.siblingIndex);
+}
+
+// Persist all branches (not just visible path)
+const allMessages = getAllMessages();
+await saveToServer(allMessages);
+```
+
+---
+
+## Persistence
+
+### New DB columns (optional)
+
+Two new optional columns on your messages table:
+
+```sql
+ALTER TABLE messages
+  ADD COLUMN parent_id TEXT REFERENCES messages(id),
+  ADD COLUMN children_ids JSONB DEFAULT '[]';
+```
+
+<Callout type="info">
+These columns are **optional**. Existing rows without them are auto-migrated to a linear tree on load — no data loss, no required migration script.
+</Callout>
+
+### What gets saved
+
+When `onMessagesChange` fires, the payload now contains **all messages across all branches**. Each message carries:
+
+```json
+{
+  "id": "msg-abc",
+  "role": "assistant",
+  "content": "...",
+  "parent_id": "msg-xyz",
+  "children_ids": []
+}
+```
+
+### Upsert strategy (recommended)
+
+```typescript
+// ✅ Safe for branching — upsert by ID
+await db.messages.upsert({ id: msg.id, ...msg });
+
+// ⚠️ Loses inactive branches
+await db.threads.update({ messages: visibleMessages });
+```
+
+---
+
+## Breaking Changes
+
+**None.** All new fields and methods are optional. Existing usage is untouched.
+
+| Scenario | Behavior |
+|----------|----------|
+| Messages with no `parentId` | Falls back to insertion order (legacy linear) |
+| `regenerate()` with no args | Identical to before |
+| `sendMessage()` with no options | Identical to before |
+| `onMessagesChange` consumers | Payload now includes all branches — shape unchanged |
diff --git a/apps/docs/content/docs/chat.mdx b/apps/docs/content/docs/chat/index.mdx
similarity index 96%
rename from apps/docs/content/docs/chat.mdx
rename to apps/docs/content/docs/chat/index.mdx
index d244973..527460b 100644
--- a/apps/docs/content/docs/chat.mdx
+++ b/apps/docs/content/docs/chat/index.mdx
@@ -228,4 +228,5 @@ The chat component uses Tailwind CSS. Override styles with className:
 ## Next Steps
 
 - [Tools](/docs/tools) - Add AI capabilities
-- [Custom Tools](/docs/custom-tools) - Build your own tools
+- [Branching](/docs/chat/branching) - Conversation branching like ChatGPT
+- [Message Actions](/docs/chat/message-actions) - Add copy, edit, feedback buttons
diff --git a/apps/docs/content/docs/chat/message-actions.mdx b/apps/docs/content/docs/chat/message-actions.mdx
new file mode 100644
index 0000000..ef6a6ea
--- /dev/null
+++ b/apps/docs/content/docs/chat/message-actions.mdx
@@ -0,0 +1,158 @@
+---
+title: Message Actions
+description: Add floating copy, edit, feedback, and custom action buttons to chat messages
+icon: MousePointerClick
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+A compound component API for registering floating action buttons on chat messages — copy, edit, feedback, or fully custom actions. Actions appear on hover, floating below the message bubble. Declarative, role-based, fully composable.
+
+---
+
+## Quick Start
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.FeedbackAction
+      onFeedback={(message, type) => sendFeedback({ messageId: message.id, type })}
+    />
+  </CopilotChat.MessageActions>
+
+  <CopilotChat.MessageActions role="user">
+    <CopilotChat.EditAction />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+<Callout type="info">
+If no `<CopilotChat.MessageActions>` children are declared, nothing changes — existing chat UI looks and behaves identically.
+</Callout>
+
+---
+
+## Compound Components
+
+| Component | Description |
+|-----------|-------------|
+| `CopilotChat.MessageActions` | Registers actions for a role (`user` or `assistant`) |
+| `CopilotChat.CopyAction` | Copy message to clipboard (with ✓ feedback) |
+| `CopilotChat.EditAction` | Inline edit for user messages (wired to branching) |
+| `CopilotChat.FeedbackAction` | Thumbs up / down |
+| `CopilotChat.Action` | Fully custom action button |
+
+---
+
+## Props Reference
+
+```tsx
+// MessageActions
+role: "user" | "assistant"
+
+// CopyAction
+tooltip?: string
+className?: string
+
+// EditAction
+tooltip?: string
+className?: string
+
+// FeedbackAction
+onFeedback?: (message: ChatMessage, type: "helpful" | "not-helpful") => void
+tooltip?: string
+className?: string
+
+// Action (custom)
+id?: string
+icon: ReactNode
+tooltip: string
+onClick: (props: { message: ChatMessage }) => void
+hidden?: boolean | ((props: { message: ChatMessage }) => boolean)
+className?: string
+```
+
+---
+
+## Examples
+
+### Copy + Feedback on assistant
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.FeedbackAction
+      onFeedback={(message, type) => {
+        sendFeedback({ messageId: message.id, type });
+      }}
+    />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+### Custom action
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.Action
+      icon={<ShareIcon />}
+      tooltip="Share"
+      onClick={({ message }) => share(message.content)}
+    />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+### Conditional action (hide based on message content)
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.Action
+      icon={<FlagIcon />}
+      tooltip="Report"
+      hidden={({ message }) => !message.content}
+      onClick={({ message }) => report(message.id)}
+    />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+### Full setup — both roles
+
+```tsx
+<CopilotChat>
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.FeedbackAction onFeedback={(msg, type) => log(msg.id, type)} />
+    <CopilotChat.Action
+      icon={<BookmarkIcon />}
+      tooltip="Save"
+      onClick={({ message }) => save(message)}
+    />
+  </CopilotChat.MessageActions>
+
+  <CopilotChat.MessageActions role="user">
+    <CopilotChat.EditAction />
+    <CopilotChat.Action
+      icon={<DeleteIcon />}
+      tooltip="Delete"
+      onClick={({ message }) => deleteMessage(message.id)}
+    />
+  </CopilotChat.MessageActions>
+</CopilotChat>
+```
+
+---
+
+## Breaking Changes
+
+**None.** Purely additive. If no `MessageActions` children are declared, the chat UI is identical to before.
diff --git a/apps/docs/content/docs/chat/meta.json b/apps/docs/content/docs/chat/meta.json
new file mode 100644
index 0000000..89022d6
--- /dev/null
+++ b/apps/docs/content/docs/chat/meta.json
@@ -0,0 +1,9 @@
+{
+  "title": "Chat",
+  "icon": "MessageSquare",
+  "pages": [
+    "index",
+    { "type": "page", "name": "branching", "badge": "Beta" },
+    { "type": "page", "name": "message-actions", "badge": "Beta" }
+  ]
+}
diff --git a/apps/docs/content/docs/context/compaction.mdx b/apps/docs/content/docs/context/compaction.mdx
new file mode 100644
index 0000000..707786e
--- /dev/null
+++ b/apps/docs/content/docs/context/compaction.mdx
@@ -0,0 +1,205 @@
+---
+title: Message History Compaction
+description: Auto-summarize old messages to keep long conversations within the AI's context window
+icon: Archive
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+Keep long conversations alive without hitting token limits. The SDK maintains two parallel views of message history — a full display layer for the UI, and a compacted layer sent to the model.
+
+---
+
+## How It Works
+
+Every conversation maintains two parallel views:
+
+| Layer | Type | Purpose |
+|-------|------|---------|
+| **Display layer** | `DisplayMessage[]` | Full immutable history. Rendered in the UI. Never shrinks. |
+| **LLM context layer** | `LLMMessage[]` | Compacted/pruned form sent to the model on each request. |
+
+When compaction fires, a `CompactionMarker` is injected into the display layer so users can see where summarization happened — but the full history is never deleted.
+
+---
+
+## useMessageHistory
+
+```typescript
+import { useMessageHistory } from "@yourgpt/copilot-sdk/react";
+
+function MyChat() {
+  const {
+    displayMessages,      // Full UI history
+    llmMessages,          // Compacted LLM context
+    tokenUsage,           // Live token estimate
+    isCompacting,         // true while auto-compaction runs
+    compactionState,      // Metadata & rolling summary
+    compactSession,       // Manual trigger
+    addToWorkingMemory,
+    clearWorkingMemory,
+    resetSession,
+  } = useMessageHistory({
+    strategy: "summary-buffer",
+    maxContextTokens: 128000,
+    compactionThreshold: 0.75,
+    compactionUrl: "/api/compact",
+    persistSession: true,
+  });
+}
+```
+
+---
+
+## Compaction Strategies
+
+### `"none"` (default)
+
+No compaction. Zero-config, 100% backward-compatible.
+
+```typescript
+useMessageHistory({ strategy: "none" });
+```
+
+### `"sliding-window"`
+
+Keeps only the most recent N tokens of history. Oldest messages are dropped when the token budget is exceeded.
+
+```typescript
+useMessageHistory({
+  strategy: "sliding-window",
+  maxContextTokens: 128000,
+  reserveForResponse: 4096,
+  recentBuffer: 10,        // Always keep at least 10 recent messages
+  toolResultMaxChars: 10000, // Truncate large tool results
+});
+```
+
+### `"selective-prune"`
+
+Removes old tool-result messages while keeping the user/assistant conversation skeleton. Lighter than sliding-window — no token counting required.
+
+```typescript
+useMessageHistory({
+  strategy: "selective-prune",
+  recentBuffer: 10,
+});
+```
+
+### `"summary-buffer"`
+
+Summarizes old messages into a rolling summary when usage exceeds `compactionThreshold`. The summary is injected as a system message. Requires a `/api/compact` endpoint.
+
+```typescript
+useMessageHistory({
+  strategy: "summary-buffer",
+  compactionThreshold: 0.75, // Compact at 75% of maxContextTokens
+  compactionUrl: "/api/compact",
+  recentBuffer: 10,
+  onCompaction: (event) => {
+    console.log(`Compacted ${event.messagesSummarized} messages, saved ~${event.tokensSaved} tokens`);
+  },
+});
+```
+
+Custom summarizer (skip the HTTP round-trip):
+
+```typescript
+useMessageHistory({
+  strategy: "summary-buffer",
+  summarizer: async (messages) => {
+    const res = await myLLM.summarize(messages);
+    return res.text;
+  },
+});
+```
+
+---
+
+## Provider-level Config
+
+Set defaults once in `<CopilotProvider>`:
+
+```tsx
+<CopilotProvider
+  messageHistory={{
+    strategy: "summary-buffer",
+    maxContextTokens: 128000,
+    compactionUrl: "/api/compact",
+    persistSession: true,
+  }}
+>
+  <App />
+</CopilotProvider>
+```
+
+---
+
+## Working Memory
+
+Pin facts that survive all future compactions:
+
+```typescript
+const { addToWorkingMemory, clearWorkingMemory } = useMessageHistory({ ... });
+
+// Survives compaction
+addToWorkingMemory("User is on the Pro plan. Account ID: acct_123");
+
+// Remove all pinned facts
+clearWorkingMemory();
+```
+
+---
+
+## Config Reference
+
+```typescript
+interface MessageHistoryConfig {
+  strategy?: "none" | "sliding-window" | "summary-buffer" | "selective-prune";
+  maxContextTokens?: number;       // default: 128000
+  reserveForResponse?: number;     // default: 4096
+  compactionThreshold?: number;    // default: 0.75
+  recentBuffer?: number;           // default: 10
+  toolResultMaxChars?: number;     // default: 10000 (0 = no cap)
+  compactionUrl?: string;          // required for summary-buffer
+  persistSession?: boolean;        // default: false
+  storageKey?: string;             // default: "copilot-session"
+  onCompaction?: (event: CompactionEvent) => void;
+  onTokenUsage?: (usage: TokenUsage) => void;
+}
+```
+
+---
+
+## Server: `/api/compact` Endpoint
+
+The `compactSession` utility powers the compaction endpoint. It calls Claude (defaults to `claude-haiku-4-5`) to produce a structured summary.
+
+```typescript
+// app/api/compact/route.ts
+import { compactSession } from "@yourgpt/copilot-sdk/server";
+
+export async function POST(req: Request) {
+  const { messages, existingSummary, workingMemory } = await req.json();
+
+  const { summary } = await compactSession({
+    messages,
+    existingSummary,  // For rolling summaries on subsequent compactions
+    workingMemory,    // User-pinned facts (addToWorkingMemory)
+    model: "claude-haiku-4-5",
+    maxSummaryTokens: 1024,
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  });
+
+  return Response.json({ summary });
+}
+```
+
+<Callout type="info">
+The summary preserves: user goals, technical decisions, tool call outcomes, errors and resolutions, pending tasks.
+</Callout>
diff --git a/apps/docs/content/docs/smart-ai-context.mdx b/apps/docs/content/docs/context/index.mdx
similarity index 51%
rename from apps/docs/content/docs/smart-ai-context.mdx
rename to apps/docs/content/docs/context/index.mdx
index 9329fd4..2e5df51 100644
--- a/apps/docs/content/docs/smart-ai-context.mdx
+++ b/apps/docs/content/docs/context/index.mdx
@@ -1,25 +1,27 @@
 ---
-title: Smart AI Context
-description: Make AI aware of your application state
+title: Context Management
+description: Make AI aware of your application state and manage the context window
 icon: Lightbulb
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-Give the AI awareness of your application state so it can provide relevant, contextual responses.
+Give the AI awareness of your application state so it can provide relevant, contextual responses. The SDK also provides advanced context window management for long conversations.
 
 ---
 
-## Overview
+## Application Context
 
-Without context, AI doesn't know what's happening in your app:
+Inject your app state into the AI's context so it can answer questions about what's happening in your app.
+
+### Without context
 
 ```
 User: "Is this in stock?"
 AI: "I don't know what product you're referring to."
 ```
 
-With context:
+### With context
 
 ```tsx
 useAIContext({
@@ -125,13 +127,9 @@ Create parent-child relationships for complex data:
 
 ```tsx
 function TeamDashboard({ team }) {
-  // Parent context
   const teamContextId = useAIContext({
     key: 'team',
-    data: {
-      name: team.name,
-      memberCount: team.members.length,
-    },
+    data: { name: team.name, memberCount: team.members.length },
     description: 'The team being viewed',
   });
 
@@ -139,27 +137,18 @@ function TeamDashboard({ team }) {
     <div>
       <h1>{team.name}</h1>
       {team.members.map(member => (
-        <MemberCard
-          key={member.id}
-          member={member}
-          parentId={teamContextId}
-        />
+        <MemberCard key={member.id} member={member} parentId={teamContextId} />
       ))}
     </div>
   );
 }
 
 function MemberCard({ member, parentId }) {
-  // Child context - linked to team
   useAIContext({
     key: `member-${member.id}`,
-    data: {
-      name: member.name,
-      role: member.role,
-      tasks: member.tasks,
-    },
+    data: { name: member.name, role: member.role, tasks: member.tasks },
     description: `Team member: ${member.name}`,
-    parentId, // Links to team context
+    parentId,
   });
 
   return <div>{member.name}</div>;
@@ -167,7 +156,7 @@ function MemberCard({ member, parentId }) {
 ```
 
 <Callout type="info">
-Hierarchical contexts help AI understand relationships. When user asks about "John's tasks", AI knows John is part of the team context.
+Hierarchical contexts help AI understand relationships. When a user asks about "John's tasks", AI knows John is part of the team context.
 </Callout>
 
 ---
@@ -207,7 +196,6 @@ Contexts are automatically removed when components unmount:
 
 ```tsx
 function ConditionalContext({ showDetails }) {
-  // This context only exists when showDetails is true
   if (showDetails) {
     return <DetailedContext />;
   }
@@ -228,66 +216,8 @@ function DetailedContext() {
 
 ## What to Include in Context
 
-### Good Context Data
-
 ```tsx
-// User state
-{
-  name: 'John',
-  plan: 'pro',
-  permissions: ['read', 'write'],
-}
-
-// Current view
-{
-  page: 'checkout',
-  step: 2,
-  items: cart.items,
-}
-
-// Form state
-{
-  formType: 'contact',
-  fields: Object.keys(formData),
-  hasErrors: errors.length > 0,
-}
-```
-
-### Avoid Including
-
-```tsx
-// Too much data (token waste)
-{
-  allProducts: products, // Could be thousands
-  fullUserHistory: history, // Unnecessary detail
-}
-
-// Sensitive data
-{
-  password: user.password, // Never!
-  creditCard: payment.card, // Never!
-  apiKeys: config.keys, // Never!
-}
-
-// Irrelevant data
-{
-  buildHash: process.env.BUILD_ID, // AI doesn't need this
-  internalIds: uuids, // No user value
-}
-```
-
-<Callout type="warning">
-Never include sensitive data in AI context. The context is sent to the LLM provider.
-</Callout>
-
----
-
-## Best Practices
-
-### 1. Keep Context Focused
-
-```tsx
-// ✅ Good - relevant, scoped data
+// ✅ Good — relevant, scoped data
 useAIContext({
   key: 'order-details',
   data: {
@@ -297,113 +227,25 @@ useAIContext({
     total: order.total,
   },
 });
-
-// ❌ Bad - too much unnecessary detail
-useAIContext({
-  key: 'order',
-  data: order, // Full order object with internal fields
-});
-```
-
-### 2. Use Descriptive Keys
-
-```tsx
-// ✅ Good
-useAIContext({ key: 'current-product', data });
-useAIContext({ key: 'user-preferences', data });
-useAIContext({ key: 'checkout-cart', data });
-
-// ❌ Bad
-useAIContext({ key: 'data1', data });
-useAIContext({ key: 'ctx', data });
-```
-
-### 3. Add Helpful Descriptions
-
-```tsx
-useAIContext({
-  key: 'filters',
-  data: { category: 'electronics', priceRange: [0, 500] },
-  description: 'Active product filters the user has applied',
-});
 ```
 
-### 4. Structure for AI Understanding
-
-```tsx
-// ✅ Good - clear structure
-useAIContext({
-  key: 'selected-item',
-  data: {
-    name: 'Widget Pro',
-    canPurchase: true,
-    reasonIfNot: null,
-  },
-});
-
-// ❌ Bad - ambiguous
-useAIContext({
-  key: 'item',
-  data: {
-    n: 'Widget Pro',
-    p: true,
-  },
-});
-```
+<Callout type="warning">
+Never include sensitive data (passwords, API keys, credit cards) in AI context. The context is sent to the LLM provider.
+</Callout>
 
 ---
 
-## Full Example
+## Advanced Context Window Management
 
-```tsx
-function EcommercePage({ product, user, cart }) {
-  // Global contexts (in layout/provider)
-  useAIContexts([
-    {
-      key: 'user',
-      data: {
-        name: user.name,
-        memberSince: user.createdAt,
-        tier: user.loyaltyTier,
-      },
-      description: 'Logged-in user',
-    },
-    {
-      key: 'cart',
-      data: {
-        itemCount: cart.items.length,
-        subtotal: cart.subtotal,
-        hasDiscount: cart.discount > 0,
-      },
-      description: 'Shopping cart summary',
-    },
-  ]);
-
-  // Page-specific context
-  useAIContext({
-    key: 'viewing-product',
-    data: {
-      name: product.name,
-      price: product.price,
-      rating: product.rating,
-      inStock: product.stock > 0,
-      stockLevel: product.stock > 10 ? 'high' : product.stock > 0 ? 'low' : 'none',
-    },
-    description: 'Product the user is currently viewing',
-  });
-
-  return <ProductPage product={product} />;
-}
-```
+For long conversations, the SDK provides tools to control what the AI sees and how history is managed.
 
-Now AI can answer:
-- "Is this in stock?" → Uses viewing-product context
-- "What's in my cart?" → Uses cart context
-- "Am I eligible for member discounts?" → Uses user context
+- **[Compaction](/docs/context/compaction)** — auto-summarize old messages to stay within token limits
+- **[Token Tracking](/docs/context/token-tracking)** — monitor context window usage with `useContextStats`
+- **[Session Persistence](/docs/context/session)** — survive page reloads and compact on the server
 
 ---
 
 ## Next Steps
 
-- [Custom Tools](/docs/custom-tools) - Build tools that use context
-- [Agentic Loop](/docs/agentic-loop) - Multi-step AI reasoning
+- [Custom Tools](/docs/tools) - Build tools that use context
+- [Compaction](/docs/context/compaction) - Manage long conversation history
diff --git a/apps/docs/content/docs/context/meta.json b/apps/docs/content/docs/context/meta.json
new file mode 100644
index 0000000..8f1ae34
--- /dev/null
+++ b/apps/docs/content/docs/context/meta.json
@@ -0,0 +1,10 @@
+{
+  "title": "Context Management",
+  "icon": "Lightbulb",
+  "pages": [
+    "index",
+    { "type": "page", "name": "compaction", "badge": "Beta" },
+    { "type": "page", "name": "token-tracking", "badge": "Beta" },
+    { "type": "page", "name": "session", "badge": "Beta" }
+  ]
+}
diff --git a/apps/docs/content/docs/context/session.mdx b/apps/docs/content/docs/context/session.mdx
new file mode 100644
index 0000000..9f68416
--- /dev/null
+++ b/apps/docs/content/docs/context/session.mdx
@@ -0,0 +1,99 @@
+---
+title: Session Persistence
+description: Survive page reloads and persist conversation state across sessions
+icon: HardDrive
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+Persist the full conversation state — including compaction metadata and message history — across page reloads with zero extra code.
+
+---
+
+## Basic Setup
+
+```typescript
+useMessageHistory({
+  persistSession: true,
+  storageKey: "my-app-chat", // default: "copilot-session"
+});
+```
+
+### What gets persisted
+
+| Data | Where | Notes |
+|------|-------|-------|
+| `compactionState` (small metadata) | `localStorage` | Sync, available immediately on cold start |
+| `displayMessages` (can be large) | `IndexedDB` | Async, avoids localStorage quota issues |
+
+Both are keyed by `storageKey`. Multiple chat instances can coexist with different keys.
+
+---
+
+## Clear Everything
+
+```typescript
+const { resetSession } = useMessageHistory({ persistSession: true });
+
+// Clears state AND storage
+await resetSession();
+```
+
+---
+
+## Multiple Chat Instances
+
+```tsx
+// Support chat — separate session
+<CopilotProvider widgetToken="...">
+  <SupportChat>
+    {/* useMessageHistory({ storageKey: "support-chat" }) */}
+  </SupportChat>
+</CopilotProvider>
+
+// Sales chat — separate session
+<CopilotProvider widgetToken="...">
+  <SalesChat>
+    {/* useMessageHistory({ storageKey: "sales-chat" }) */}
+  </SalesChat>
+</CopilotProvider>
+```
+
+---
+
+## Full Setup Example
+
+```tsx
+// app/layout.tsx
+import { CopilotProvider } from "@yourgpt/copilot-sdk/react";
+
+export default function RootLayout({ children }) {
+  return (
+    <CopilotProvider
+      widgetToken="YOUR_TOKEN"
+      messageHistory={{
+        strategy: "summary-buffer",
+        maxContextTokens: 128000,
+        compactionThreshold: 0.75,
+        compactionUrl: "/api/compact",
+        persistSession: true,
+        storageKey: "my-app",
+        onCompaction: (e) => console.log("Compacted:", e),
+      }}
+    >
+      {children}
+    </CopilotProvider>
+  );
+}
+```
+
+---
+
+## Related
+
+- [Compaction](/docs/context/compaction) — how the session is summarized
+- [Token Tracking](/docs/context/token-tracking) — monitor context window usage
diff --git a/apps/docs/content/docs/context/token-tracking.mdx b/apps/docs/content/docs/context/token-tracking.mdx
new file mode 100644
index 0000000..dc9bed9
--- /dev/null
+++ b/apps/docs/content/docs/context/token-tracking.mdx
@@ -0,0 +1,130 @@
+---
+title: Token Tracking
+description: Monitor context window usage in real time with useContextStats
+icon: BarChart2
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+Monitor how much of the AI's context window is being used — broken down by message history, system prompt, tools, and injected context.
+
+---
+
+## useContextStats
+
+```typescript
+import { useContextStats } from "@yourgpt/copilot-sdk/react";
+
+function ContextMonitor() {
+  const {
+    contextUsage,       // Full breakdown by bucket
+    totalTokens,        // Convenience: total estimated tokens
+    usagePercent,       // Convenience: window fill 0–1
+    contextChars,       // Characters contributed by AI context injections
+    toolCount,          // Number of currently registered tools
+    messageCount,       // Visible (non-system) messages
+    lastResponseUsage,  // Token usage from last assistant message
+  } = useContextStats();
+
+  return (
+    <div>
+      <p>{Math.round(usagePercent * 100)}% of context used</p>
+      <p>{totalTokens} tokens / {toolCount} tools</p>
+      {lastResponseUsage && (
+        <p>Last turn: {lastResponseUsage.total_tokens} tokens</p>
+      )}
+    </div>
+  );
+}
+```
+
+### Return type
+
+```typescript
+interface ContextStats {
+  contextUsage: ContextUsage | null;        // null until first message
+  totalTokens: number;
+  usagePercent: number;                     // 0 until first message
+  contextChars: number;
+  toolCount: number;
+  messageCount: number;
+  lastResponseUsage: MessageTokenUsage | null;
+}
+
+interface MessageTokenUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+}
+```
+
+---
+
+## Token Counting Utilities
+
+Two tiers — pick the right trade-off between speed and accuracy.
+
+### Tier 1: Fast (zero dependencies)
+
+Uses a `chars / 3.5` heuristic. ~85–90% accurate for English. Always available, no bundle cost.
+
+```typescript
+import {
+  estimateTokensFast,
+  estimateMessageTokens,
+  estimateMessagesTokens,
+} from "@yourgpt/copilot-sdk/react";
+
+const tokens = estimateTokensFast("Hello world");        // fast, synchronous
+const msgTokens = estimateMessagesTokens(llmMessages);
+```
+
+### Tier 2: Accurate (lazy-loaded)
+
+Uses `gpt-tokenizer` with the `o200k_base` encoding. Lazy-loaded only when called — no upfront bundle cost.
+
+```typescript
+import {
+  countTokensAccurate,
+  countMessagesTokensAccurate,
+} from "@yourgpt/copilot-sdk/react";
+
+// Only loads gpt-tokenizer on first call
+const tokens = await countTokensAccurate("Hello world");
+const msgTokens = await countMessagesTokensAccurate(llmMessages);
+```
+
+### Set estimation mode in `useMessageHistory`
+
+```typescript
+useMessageHistory({ tokenEstimation: "accurate" }); // "fast" | "accurate" | "off"
+```
+
+---
+
+## Example: Context Usage Indicator
+
+```tsx
+import { useContextStats, useMessageHistory } from "@yourgpt/copilot-sdk/react";
+
+export function ChatPanel() {
+  const { tokenUsage, isCompacting, compactSession } = useMessageHistory();
+  const { usagePercent, toolCount } = useContextStats();
+
+  return (
+    <div>
+      <p>
+        {Math.round(usagePercent * 100)}% context used · {toolCount} tools
+      </p>
+      {tokenUsage.isApproaching && (
+        <button onClick={() => compactSession()}>Compact now</button>
+      )}
+      {isCompacting && <span>Summarizing history…</span>}
+    </div>
+  );
+}
+```
diff --git a/apps/docs/content/docs/customizations/chat-primitives.mdx b/apps/docs/content/docs/customizations/chat-primitives.mdx
new file mode 100644
index 0000000..74a54ec
--- /dev/null
+++ b/apps/docs/content/docs/customizations/chat-primitives.mdx
@@ -0,0 +1,174 @@
+---
+title: Chat Primitives
+description: Headless building blocks for composing fully custom chat UIs
+icon: Layers
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+Low-level building blocks for composing custom chat UIs. The SDK handles all state, streaming, and context — you control the layout.
+
+Two complementary APIs:
+- **`ChatPrimitives`** — named export of individual components, import under any alias
+- **`CopilotChat.*`** — same primitives mounted directly on `CopilotChat` for inline composition
+
+---
+
+## All Primitives
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+```
+
+| Primitive | Description |
+|-----------|-------------|
+| `Chat.MessageList` | Render-prop message list — reads `messages` from context |
+| `Chat.DefaultMessage` | Full SDK message bubble — use as fallback in custom lists |
+| `Chat.Header` | Chat header bar |
+| `Chat.Welcome` | Welcome screen shown when there are no messages |
+| `Chat.Input` | Composer / input box |
+| `Chat.ScrollAnchor` | Auto-scroll anchor, place at end of message list |
+| `Chat.Message` | Low-level message row wrapper |
+| `Chat.MessageAvatar` | Avatar with fallback initials |
+| `Chat.MessageContent` | Content bubble — renders markdown, supports streaming |
+| `Chat.MessageActions` | Action bar layout primitive (wraps action buttons) |
+| `Chat.MessageAction` | Single action icon button with tooltip |
+| `Chat.Loader` | Streaming / thinking indicator |
+
+---
+
+## `Chat.MessageList` props
+
+```ts
+interface MessageListProps {
+  children?: (message: ChatMessage, index: number) => React.ReactNode;
+  className?: string;
+}
+```
+
+When `children` is provided, called once per message — return your custom component or fall back to `Chat.DefaultMessage`. When omitted, renders all messages with `DefaultMessage`.
+
+---
+
+## Examples
+
+### Custom message type with fallback
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
+<CopilotChat>
+  <Chat.MessageList>
+    {(message) =>
+      message.metadata?.type === "plan" ? (
+        <PlanCard key={message.id} message={message} />
+      ) : (
+        <Chat.DefaultMessage key={message.id} message={message} />
+      )
+    }
+  </Chat.MessageList>
+</CopilotChat>
+```
+
+### Fully custom layout — compose from scratch
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
+<CopilotChat>
+  <div className="flex flex-col h-full">
+    <Chat.Header />
+    <Chat.Welcome />
+
+    <div className="flex-1 overflow-y-auto px-4">
+      <Chat.MessageList>
+        {(message) => (
+          <Chat.Message key={message.id} message={message}>
+            <Chat.MessageAvatar message={message} />
+            <Chat.MessageContent message={message} />
+          </Chat.Message>
+        )}
+      </Chat.MessageList>
+      <Chat.Loader />
+      <Chat.ScrollAnchor />
+    </div>
+
+    <Chat.Input />
+  </div>
+</CopilotChat>
+```
+
+### Mix primitives with message actions
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
+<CopilotChat>
+  {/* Register floating action buttons */}
+  <CopilotChat.MessageActions role="assistant">
+    <CopilotChat.CopyAction />
+    <CopilotChat.FeedbackAction onFeedback={(msg, type) => log(msg.id, type)} />
+  </CopilotChat.MessageActions>
+
+  {/* Custom message list */}
+  <Chat.MessageList>
+    {(message) =>
+      message.metadata?.type === "approval" ? (
+        <ApprovalCard key={message.id} message={message} />
+      ) : (
+        <Chat.DefaultMessage key={message.id} message={message} />
+      )
+    }
+  </Chat.MessageList>
+</CopilotChat>
+```
+
+### Per-message action buttons using primitives directly
+
+```tsx
+import { ChatPrimitives as Chat } from "@yourgpt/copilot-sdk/ui";
+
+<Chat.MessageList>
+  {(message) => (
+    <Chat.Message key={message.id} message={message}>
+      <Chat.MessageAvatar message={message} />
+      <div className="flex flex-col gap-1">
+        <Chat.MessageContent message={message} />
+        <Chat.MessageActions>
+          <Chat.MessageAction
+            icon={<CopyIcon />}
+            tooltip="Copy"
+            onClick={() => navigator.clipboard.writeText(message.content ?? "")}
+          />
+        </Chat.MessageActions>
+      </div>
+    </Chat.Message>
+  )}
+</Chat.MessageList>
+```
+
+---
+
+## `messageView` vs `Chat.MessageList`
+
+Two ways to customize message rendering at different abstraction levels:
+
+| | `messageView` prop | `Chat.MessageList` |
+|--|--------------------|--------------------|
+| Style | Prop on `<CopilotChat>` | Child component inside `<CopilotChat>` |
+| Access | `messages[]` + pre-rendered `messageElements[]` | `messages[]` via render-prop |
+| When to use | Quick overrides, inject extra UI around existing renders | Full layout control, building from primitives |
+
+Both are non-breaking and can coexist.
+
+→ See [Custom Message View](/docs/customizations/custom-message-view) for the `messageView` API.
+
+---
+
+## Breaking Changes
+
+**None.** Both are purely additive. Existing `<CopilotChat />` usage is untouched.
diff --git a/apps/docs/content/docs/customizations/custom-message-view.mdx b/apps/docs/content/docs/customizations/custom-message-view.mdx
new file mode 100644
index 0000000..840da7c
--- /dev/null
+++ b/apps/docs/content/docs/customizations/custom-message-view.mdx
@@ -0,0 +1,116 @@
+---
+title: Custom Message View
+description: Full control over how the message list is rendered via the messageView prop
+icon: LayoutList
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+The `messageView` prop on `<CopilotChat>` intercepts message list rendering. Inject custom UI, conditionally replace messages based on `metadata.type`, or build entirely custom layouts — without touching roles or message history.
+
+---
+
+## API
+
+```ts
+messageView?: {
+  children?: (props: {
+    /** Raw messages array */
+    messages: ChatMessage[];
+    /** Pre-rendered default SDK elements, one per message */
+    messageElements: React.ReactNode[];
+  }) => React.ReactNode;
+};
+```
+
+You receive:
+- **`messageElements`** — pre-rendered default SDK elements (one per message, may include `null` for filtered messages)
+- **`messages`** — raw `ChatMessage[]` for conditional logic
+
+---
+
+## Examples
+
+### Inject custom UI below messages
+
+```tsx
+<CopilotChat
+  messageView={{
+    children: ({ messageElements }) => (
+      <>
+        {messageElements}
+        <div className="p-4 text-center text-sm text-muted-foreground">
+          Powered by YourGPT
+        </div>
+      </>
+    ),
+  }}
+/>
+```
+
+### Custom message types via `metadata.type`
+
+Inject a custom message type (e.g. from a tool handler), then render it with your own component:
+
+```tsx
+<CopilotChat
+  messageView={{
+    children: ({ messages, messageElements }) => (
+      <>
+        {messages.map((message, i) => {
+          if (message.metadata?.type === "plan") {
+            return <PlanCard key={message.id} data={message.metadata} />;
+          }
+          if (message.metadata?.type === "approval") {
+            return <ApprovalCard key={message.id} data={message.metadata} />;
+          }
+          return messageElements[i];
+        })}
+      </>
+    ),
+  }}
+/>
+```
+
+### Combine with agent state
+
+```tsx
+function Chat() {
+  const agentState = useMyAgentState();
+
+  return (
+    <CopilotChat
+      messageView={{
+        children: ({ messageElements }) => (
+          <div className="flex flex-col gap-4">
+            {messageElements}
+            {agentState?.steps && <TaskProgress steps={agentState.steps} />}
+          </div>
+        ),
+      }}
+    />
+  );
+}
+```
+
+---
+
+## `messageView` vs `Chat.MessageList`
+
+| | `messageView` | `Chat.MessageList` |
+|--|---------------|---------------------|
+| Style | Prop on `<CopilotChat>` | Child component inside `<CopilotChat>` |
+| Access | `messages[]` + pre-rendered `messageElements[]` | `messages[]` via render-prop |
+| When to use | Quick overrides, inject UI around existing renders | Full layout control, building from scratch |
+
+`messageView` is the simpler option for most cases. Use [Chat Primitives](/docs/customizations/chat-primitives) when you need full layout control.
+
+---
+
+## Breaking Changes
+
+**None.** Fully additive. Existing `renderMessage`, `toolRenderers`, and all other props are unchanged.
diff --git a/apps/docs/content/docs/customizations.mdx b/apps/docs/content/docs/customizations/index.mdx
similarity index 97%
rename from apps/docs/content/docs/customizations.mdx
rename to apps/docs/content/docs/customizations/index.mdx
index ba074b9..360e05a 100644
--- a/apps/docs/content/docs/customizations.mdx
+++ b/apps/docs/content/docs/customizations/index.mdx
@@ -352,4 +352,5 @@ import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
 
 - [UI Components](/docs/ui) - Pre-built components and themes
 - [Generative UI](/docs/generative-ui) - Render custom components from AI
-- [Chat](/docs/chat) - Full chat component API
+- [Chat Primitives](/docs/customizations/chat-primitives) - Headless building blocks
+- [Custom Message View](/docs/customizations/custom-message-view) - Full control over message rendering
diff --git a/apps/docs/content/docs/customizations/meta.json b/apps/docs/content/docs/customizations/meta.json
new file mode 100644
index 0000000..51cf9fd
--- /dev/null
+++ b/apps/docs/content/docs/customizations/meta.json
@@ -0,0 +1,9 @@
+{
+  "title": "Customizations",
+  "icon": "Paintbrush",
+  "pages": [
+    "index",
+    { "type": "page", "name": "chat-primitives", "badge": "Beta" },
+    { "type": "page", "name": "custom-message-view", "badge": "Beta" }
+  ]
+}
diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json
index c13a3f6..73201ef 100644
--- a/apps/docs/content/docs/meta.json
+++ b/apps/docs/content/docs/meta.json
@@ -11,8 +11,9 @@
     "overview",
     "ui",
     "chat",
-    "smart-ai-context",
+    "context",
     "tools",
+    "skills",
     "mcp",
     "chat-history",
     "server",
diff --git a/apps/docs/content/docs/tools/deferred-tools.mdx b/apps/docs/content/docs/tools/deferred-tools.mdx
new file mode 100644
index 0000000..f6fd6aa
--- /dev/null
+++ b/apps/docs/content/docs/tools/deferred-tools.mdx
@@ -0,0 +1,96 @@
+---
+title: Deferred Tools
+description: Keep large tool registries lean by loading tools only when semantically relevant
+icon: Clock
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+Large tool registries bloat the LLM request payload and consume valuable context tokens. Mark tools with `deferLoading: true` to exclude them from the default request — they are auto-injected only when the user's query semantically matches the tool.
+
+---
+
+## Usage
+
+```typescript
+import { useTool } from "@yourgpt/copilot-sdk/react";
+import { z } from "zod";
+
+useTool({
+  name: "run_sql_query",
+  description: "Execute a SQL query against the database",
+  deferLoading: true,                              // Not sent on every request
+  searchKeywords: ["sql", "query", "database", "table"],
+  inputSchema: z.object({ query: z.string() }),
+  handler: async ({ query }) => db.execute(query),
+});
+```
+
+Auto-detection uses `description` + `searchKeywords` to score relevance against the current message. No configuration required.
+
+---
+
+## `useTools` (ToolSet pattern)
+
+Register multiple tools at once:
+
+```typescript
+import { useTools, tool } from "@yourgpt/copilot-sdk/react";
+
+function MyApp() {
+  useTools({
+    get_weather: tool({
+      description: "Get weather for a location",
+      inputSchema: {
+        type: "object",
+        properties: { location: { type: "string" } },
+        required: ["location"],
+      },
+      handler: async ({ location }) => fetchWeather(location),
+    }),
+    run_sql_query: tool({
+      description: "Execute a SQL query",
+      deferLoading: true,
+      searchKeywords: ["sql", "query", "database"],
+      inputSchema: z.object({ query: z.string() }),
+      handler: async ({ query }) => db.execute(query),
+    }),
+  });
+}
+```
+
+---
+
+## UseToolConfig — Deferred Fields
+
+```typescript
+interface UseToolConfig<TParams> {
+  // ...other fields...
+
+  // Loading strategy
+  deferLoading?: boolean;       // Exclude from default request payload
+  searchKeywords?: string[];    // Extra keywords for relevance matching
+  group?: string;               // Logical group for batch deferred loading
+  category?: string;            // Category tag
+  profiles?: string[];          // Named profiles for conditional activation
+}
+```
+
+---
+
+## When to Use
+
+| Scenario | Use deferred? |
+|----------|---------------|
+| Tools used in every message (e.g. `navigate_to`) | No |
+| Heavy/specialized tools (e.g. `run_sql_query`) | Yes |
+| Tools with large input schemas | Yes |
+| You have 10+ tools registered | Consider it |
+
+<Callout type="info">
+Deferred tools are still available to the AI — they're just not included in the initial request payload. When the user's message matches, they're injected automatically before the request is sent.
+</Callout>
diff --git a/apps/docs/content/docs/tools/hidden-tools.mdx b/apps/docs/content/docs/tools/hidden-tools.mdx
new file mode 100644
index 0000000..205ca52
--- /dev/null
+++ b/apps/docs/content/docs/tools/hidden-tools.mdx
@@ -0,0 +1,70 @@
+---
+title: Hidden Tools & Fallback Renderer
+description: Run tools silently without showing them in the chat UI, and catch-all renderers for unregistered tools
+icon: EyeOff
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+---
+
+## Hidden Tools
+
+Register tools that execute silently — they run when called by the AI but are never shown in the tool execution UI.
+
+```typescript
+import { useTool } from "@yourgpt/copilot-sdk/react";
+
+useTool({
+  name: "log_analytics_event",
+  description: "Log a UI analytics event",
+  hidden: true,   // Never rendered in chat UI
+  inputSchema: z.object({ event: z.string(), data: z.record(z.unknown()) }),
+  handler: async ({ event, data }) => {
+    analytics.track(event, data);
+    return {};
+  },
+});
+```
+
+Use hidden tools for:
+- Analytics and logging
+- Background state updates
+- Internal bookkeeping the user doesn't need to see
+
+---
+
+## Fallback Tool Renderer
+
+The `<CopilotChat>` component resolves a renderer for each tool execution using this priority chain:
+
+| Priority | Source | Description |
+|----------|--------|-------------|
+| 1 | `toolRenderers[toolName]` | Per-tool renderer map on `<CopilotChat>` |
+| 2 | `tool.render` | Render function on the `ToolDefinition` |
+| 3 | `mcpToolRenderer` | Catch-all for tools with `source: "mcp"` |
+| 4 | `fallbackToolRenderer` | Catch-all for any unmatched tool |
+| 5 | Built-in default | Generic tool execution card |
+
+```tsx
+<CopilotChat
+  // Highest priority — per-tool
+  toolRenderers={{
+    get_weather: ({ args, result }) => <WeatherCard {...result} />,
+  }}
+  // MCP catch-all
+  mcpToolRenderer={({ toolName, args, result }) => (
+    <MCPCard name={toolName} />
+  )}
+  // Universal catch-all
+  fallbackToolRenderer={({ toolName, args, result }) => (
+    <pre>{JSON.stringify(result, null, 2)}</pre>
+  )}
+/>
+```
+
+The `fallbackToolRenderer` is useful when you have dynamically registered tools or MCP tools whose names you don't know at render time.
diff --git a/apps/docs/content/docs/tools/meta.json b/apps/docs/content/docs/tools/meta.json
index 59cbf0e..fca3c21 100644
--- a/apps/docs/content/docs/tools/meta.json
+++ b/apps/docs/content/docs/tools/meta.json
@@ -1,5 +1,12 @@
 {
   "title": "Tools",
   "icon": "Wrench",
-  "pages": ["built-in", "frontend-tools", "backend-tools", "agentic-loop"]
+  "pages": [
+    "built-in",
+    "frontend-tools",
+    "backend-tools",
+    "agentic-loop",
+    { "type": "page", "name": "deferred-tools", "badge": "Beta" },
+    { "type": "page", "name": "hidden-tools", "badge": "Beta" }
+  ]
 }
diff --git a/examples/playground/app/page.tsx b/examples/playground/app/page.tsx
index 87b852e..ba2d863 100644
--- a/examples/playground/app/page.tsx
+++ b/examples/playground/app/page.tsx
@@ -40,6 +40,7 @@ export default function PlaygroundPage() {
     sdkConfig,
     selectedProvider,
     selectedOpenRouterModel,
+    alphaConfig,
     updateTheme,
     updateLayoutTemplate,
     updateSystemPrompt,
@@ -48,6 +49,7 @@ export default function PlaygroundPage() {
     updateSDKConfig,
     updateProvider,
     updateOpenRouterModel,
+    updateAlphaConfig,
   } = usePlaygroundConfig();
 
   // Local state
@@ -159,6 +161,8 @@ export default function PlaygroundPage() {
               onSelectPerson={handleSelectPerson}
               sdkConfig={sdkConfig}
               onUpdateSDKConfig={updateSDKConfig}
+              alphaConfig={alphaConfig}
+              onUpdateAlpha={updateAlphaConfig}
             />
           </div>
         </div>
@@ -177,6 +181,7 @@ export default function PlaygroundPage() {
           selectedOpenRouterModel={selectedOpenRouterModel}
           apiKeys={apiKeys}
           loaderVariant={sdkConfig.loaderVariant}
+          alphaConfig={alphaConfig}
         />
       </div>
 
diff --git a/examples/playground/components/playground/AlphaFeaturesSection.tsx b/examples/playground/components/playground/AlphaFeaturesSection.tsx
new file mode 100644
index 0000000..b27deec
--- /dev/null
+++ b/examples/playground/components/playground/AlphaFeaturesSection.tsx
@@ -0,0 +1,265 @@
+"use client";
+
+import {
+  GitBranch,
+  MessageSquare,
+  BookOpen,
+  Archive,
+  HardDrive,
+  EyeOff,
+  Zap,
+  LayoutList,
+  BarChart2,
+  ChevronRight,
+} from "lucide-react";
+import { Switch } from "@/components/ui/switch";
+import { Label } from "@/components/ui/label";
+import { Badge } from "@/components/ui/badge";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import type { AlphaConfig, CompactionStrategy } from "@/lib/types";
+
+interface AlphaFeaturesSectionProps {
+  alphaConfig: AlphaConfig;
+  onUpdate: <K extends keyof AlphaConfig>(
+    key: K,
+    value: AlphaConfig[K],
+  ) => void;
+}
+
+function FeatureRow({
+  icon: Icon,
+  label,
+  description,
+  checked,
+  onCheckedChange,
+  id,
+}: {
+  icon: React.ComponentType<{ className?: string }>;
+  label: string;
+  description: string;
+  checked: boolean;
+  onCheckedChange: (v: boolean) => void;
+  id: string;
+}) {
+  return (
+    <div className="flex items-start justify-between gap-3 py-2">
+      <div className="flex items-start gap-2 min-w-0">
+        <div className="mt-0.5 w-6 h-6 rounded-md bg-zinc-100 dark:bg-zinc-800 flex items-center justify-center flex-shrink-0">
+          <Icon className="w-3.5 h-3.5 text-zinc-500 dark:text-zinc-400" />
+        </div>
+        <div className="min-w-0">
+          <Label
+            htmlFor={id}
+            className="text-xs font-medium cursor-pointer leading-tight"
+          >
+            {label}
+          </Label>
+          <p className="text-[10px] text-zinc-400 dark:text-zinc-500 mt-0.5 leading-snug">
+            {description}
+          </p>
+        </div>
+      </div>
+      <Switch
+        id={id}
+        checked={checked}
+        onCheckedChange={onCheckedChange}
+        className="flex-shrink-0 mt-0.5 scale-90"
+      />
+    </div>
+  );
+}
+
+export function AlphaFeaturesSection({
+  alphaConfig,
+  onUpdate,
+}: AlphaFeaturesSectionProps) {
+  return (
+    <div className="space-y-1">
+      {/* Header badge */}
+      <div className="flex items-center gap-2 pb-2 border-b border-zinc-100 dark:border-zinc-800 mb-3">
+        <Badge
+          variant="secondary"
+          className="text-[10px] px-1.5 py-0 h-4 bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400 border-0"
+        >
+          Beta
+        </Badge>
+        <span className="text-[10px] text-zinc-400">
+          These features are in active development
+        </span>
+      </div>
+
+      {/* Message Actions */}
+      <p className="text-[10px] font-semibold text-zinc-500 dark:text-zinc-400 uppercase tracking-wide mb-1 flex items-center gap-1">
+        <MessageSquare className="w-3 h-3" /> Message Actions
+      </p>
+      <FeatureRow
+        id="alpha-copy"
+        icon={ChevronRight}
+        label="Copy Action"
+        description="Copy button on assistant messages"
+        checked={alphaConfig.messageActions.copyEnabled}
+        onCheckedChange={(v) =>
+          onUpdate("messageActions", {
+            ...alphaConfig.messageActions,
+            copyEnabled: v,
+          })
+        }
+      />
+      <FeatureRow
+        id="alpha-edit"
+        icon={ChevronRight}
+        label="Edit Action"
+        description="Edit button on user messages (creates branch)"
+        checked={alphaConfig.messageActions.editEnabled}
+        onCheckedChange={(v) =>
+          onUpdate("messageActions", {
+            ...alphaConfig.messageActions,
+            editEnabled: v,
+          })
+        }
+      />
+      <FeatureRow
+        id="alpha-feedback"
+        icon={ChevronRight}
+        label="Feedback Action"
+        description="Thumbs up/down on assistant messages"
+        checked={alphaConfig.messageActions.feedbackEnabled}
+        onCheckedChange={(v) =>
+          onUpdate("messageActions", {
+            ...alphaConfig.messageActions,
+            feedbackEnabled: v,
+          })
+        }
+      />
+
+      <div className="h-px bg-zinc-100 dark:bg-zinc-800 my-2" />
+
+      {/* Branching */}
+      <p className="text-[10px] font-semibold text-zinc-500 dark:text-zinc-400 uppercase tracking-wide mb-1 flex items-center gap-1">
+        <GitBranch className="w-3 h-3" /> Branching
+      </p>
+      <FeatureRow
+        id="alpha-branching"
+        icon={GitBranch}
+        label="Conversation Branching"
+        description="Edit messages to create parallel conversation paths"
+        checked={alphaConfig.branchingEnabled}
+        onCheckedChange={(v) => onUpdate("branchingEnabled", v)}
+      />
+
+      <div className="h-px bg-zinc-100 dark:bg-zinc-800 my-2" />
+
+      {/* Skills */}
+      <p className="text-[10px] font-semibold text-zinc-500 dark:text-zinc-400 uppercase tracking-wide mb-1 flex items-center gap-1">
+        <BookOpen className="w-3 h-3" /> Skills
+      </p>
+      <FeatureRow
+        id="alpha-brand-voice"
+        icon={BookOpen}
+        label="Brand Voice"
+        description="Eager skill — always active, sets response tone"
+        checked={alphaConfig.brandVoiceSkill}
+        onCheckedChange={(v) => onUpdate("brandVoiceSkill", v)}
+      />
+      <FeatureRow
+        id="alpha-code-review"
+        icon={BookOpen}
+        label="Code Review"
+        description="Auto skill — AI loads when code review is requested"
+        checked={alphaConfig.codeReviewSkill}
+        onCheckedChange={(v) => onUpdate("codeReviewSkill", v)}
+      />
+
+      <div className="h-px bg-zinc-100 dark:bg-zinc-800 my-2" />
+
+      {/* Context Management */}
+      <p className="text-[10px] font-semibold text-zinc-500 dark:text-zinc-400 uppercase tracking-wide mb-1 flex items-center gap-1">
+        <Archive className="w-3 h-3" /> Context Management
+      </p>
+      <div className="space-y-1.5">
+        <Label className="text-[10px] text-zinc-500">Compaction Strategy</Label>
+        <Select
+          value={alphaConfig.compactionStrategy}
+          onValueChange={(v) =>
+            onUpdate("compactionStrategy", v as CompactionStrategy)
+          }
+        >
+          <SelectTrigger className="h-7 text-xs">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="none" className="text-xs">
+              None (default)
+            </SelectItem>
+            <SelectItem value="sliding-window" className="text-xs">
+              Sliding Window
+            </SelectItem>
+            <SelectItem value="selective-prune" className="text-xs">
+              Selective Prune
+            </SelectItem>
+          </SelectContent>
+        </Select>
+      </div>
+      <FeatureRow
+        id="alpha-session"
+        icon={HardDrive}
+        label="Session Persistence"
+        description="Survive page reloads via IndexedDB"
+        checked={alphaConfig.sessionPersistence}
+        onCheckedChange={(v) => onUpdate("sessionPersistence", v)}
+      />
+      <FeatureRow
+        id="alpha-ctx-stats"
+        icon={BarChart2}
+        label="Context Stats"
+        description="Show token usage bar in the chat sidebar"
+        checked={alphaConfig.contextStats}
+        onCheckedChange={(v) => onUpdate("contextStats", v)}
+      />
+
+      <div className="h-px bg-zinc-100 dark:bg-zinc-800 my-2" />
+
+      {/* Tools */}
+      <p className="text-[10px] font-semibold text-zinc-500 dark:text-zinc-400 uppercase tracking-wide mb-1 flex items-center gap-1">
+        <Zap className="w-3 h-3" /> Advanced Tools
+      </p>
+      <FeatureRow
+        id="alpha-hidden"
+        icon={EyeOff}
+        label="Hidden Analytics Tool"
+        description="Silent tool — runs without showing in chat UI"
+        checked={alphaConfig.hiddenAnalytics}
+        onCheckedChange={(v) => onUpdate("hiddenAnalytics", v)}
+      />
+      <FeatureRow
+        id="alpha-deferred"
+        icon={Zap}
+        label="Deferred Search Tool"
+        description="Only injected when query is relevant (saves tokens)"
+        checked={alphaConfig.deferredSearch}
+        onCheckedChange={(v) => onUpdate("deferredSearch", v)}
+      />
+
+      <div className="h-px bg-zinc-100 dark:bg-zinc-800 my-2" />
+
+      {/* Custom Message View */}
+      <p className="text-[10px] font-semibold text-zinc-500 dark:text-zinc-400 uppercase tracking-wide mb-1 flex items-center gap-1">
+        <LayoutList className="w-3 h-3" /> Custom Message View
+      </p>
+      <FeatureRow
+        id="alpha-msg-view"
+        icon={LayoutList}
+        label="Custom messageView"
+        description="Inject custom footer below message list"
+        checked={alphaConfig.customMessageView}
+        onCheckedChange={(v) => onUpdate("customMessageView", v)}
+      />
+    </div>
+  );
+}
diff --git a/examples/playground/components/playground/ContextStatsBar.tsx b/examples/playground/components/playground/ContextStatsBar.tsx
new file mode 100644
index 0000000..302fdb7
--- /dev/null
+++ b/examples/playground/components/playground/ContextStatsBar.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import { useContextStats } from "@yourgpt/copilot-sdk/react";
+import { BarChart2 } from "lucide-react";
+
+export function ContextStatsBar() {
+  const { totalTokens, usagePercent, toolCount, messageCount } =
+    useContextStats();
+
+  const percent = Math.round(usagePercent * 100);
+  const barColor =
+    percent > 80
+      ? "bg-red-500"
+      : percent > 60
+        ? "bg-amber-500"
+        : "bg-emerald-500";
+
+  return (
+    <div className="px-3 py-2 border-b border-zinc-200 dark:border-zinc-800 bg-zinc-50 dark:bg-zinc-900/50">
+      <div className="flex items-center justify-between mb-1">
+        <div className="flex items-center gap-1 text-[10px] text-zinc-500">
+          <BarChart2 className="w-3 h-3" />
+          <span>Context</span>
+        </div>
+        <div className="flex items-center gap-2 text-[10px] text-zinc-400">
+          <span>{totalTokens.toLocaleString()} tokens</span>
+          <span>·</span>
+          <span>{toolCount} tools</span>
+          <span>·</span>
+          <span>{messageCount} msgs</span>
+        </div>
+      </div>
+      <div className="h-1 bg-zinc-200 dark:bg-zinc-700 rounded-full overflow-hidden">
+        <div
+          className={`h-full rounded-full transition-all duration-500 ${barColor}`}
+          style={{ width: `${Math.max(2, percent)}%` }}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/examples/playground/components/playground/ControlPanel.tsx b/examples/playground/components/playground/ControlPanel.tsx
index fbe5534..563921b 100644
--- a/examples/playground/components/playground/ControlPanel.tsx
+++ b/examples/playground/components/playground/ControlPanel.tsx
@@ -38,6 +38,7 @@ import {
   ExternalLink,
   Check,
   ChevronsUpDown,
+  FlaskConical,
 } from "lucide-react";
 import {
   Command,
@@ -64,6 +65,7 @@ import type {
   ProviderId,
   SDKConfig,
   LoaderVariant,
+  AlphaConfig,
 } from "@/lib/types";
 import {
   themes,
@@ -79,6 +81,7 @@ import { StockModule } from "./modules/StockModule";
 import { AlertModule } from "./modules/AlertModule";
 import { ToolInfoHoverCard } from "./ToolInfoHoverCard";
 import { ConfigInfoHoverCard } from "./ConfigInfoHoverCard";
+import { AlphaFeaturesSection } from "./AlphaFeaturesSection";
 import { toolMetadata } from "@/lib/tool-metadata";
 import { configMetadata } from "@/lib/config-metadata";
 
@@ -336,6 +339,11 @@ interface ControlPanelProps {
     key: K,
     value: SDKConfig[K],
   ) => void;
+  alphaConfig: AlphaConfig;
+  onUpdateAlpha: <K extends keyof AlphaConfig>(
+    key: K,
+    value: AlphaConfig[K],
+  ) => void;
 }
 
 function ControlPanelComponent({
@@ -363,6 +371,8 @@ function ControlPanelComponent({
   onSelectPerson,
   sdkConfig,
   onUpdateSDKConfig,
+  alphaConfig,
+  onUpdateAlpha,
 }: ControlPanelProps) {
   const activeToolCount = Object.values(toolsEnabled).filter(Boolean).length;
   const selectedTheme = themes.find((t) => t.id === copilotTheme);
@@ -1074,6 +1084,34 @@ function ControlPanelComponent({
             </div>
           </AccordionContent>
         </AccordionItem>
+
+        {/* Alpha Features */}
+        <AccordionItem
+          value="alpha"
+          className="border border-zinc-200 dark:border-zinc-800 rounded-xl bg-white dark:bg-zinc-900/50"
+        >
+          <AccordionTrigger className="px-5 py-4 hover:no-underline hover:bg-zinc-50 dark:hover:bg-zinc-800/30">
+            <div className="flex items-center gap-4">
+              <div className="flex items-center justify-center w-8 h-8 rounded-lg bg-orange-500/10 ring-1 ring-orange-500/20">
+                <FlaskConical className="h-4 w-4 text-orange-500" />
+              </div>
+              <div className="text-left">
+                <p className="text-sm font-medium text-zinc-900 dark:text-zinc-100">
+                  Alpha Features
+                </p>
+                <p className="text-[10px] text-zinc-500 font-mono">
+                  experimental · in development
+                </p>
+              </div>
+            </div>
+          </AccordionTrigger>
+          <AccordionContent className="px-5 pt-1 pb-5">
+            <AlphaFeaturesSection
+              alphaConfig={alphaConfig}
+              onUpdate={onUpdateAlpha}
+            />
+          </AccordionContent>
+        </AccordionItem>
       </Accordion>
     </div>
   );
diff --git a/examples/playground/components/playground/CopilotPanel.tsx b/examples/playground/components/playground/CopilotPanel.tsx
index abc06a2..47af306 100644
--- a/examples/playground/components/playground/CopilotPanel.tsx
+++ b/examples/playground/components/playground/CopilotPanel.tsx
@@ -8,10 +8,13 @@ import type {
   ToolsEnabledConfig,
   GenerativeUIConfig,
   LoaderVariant,
+  AlphaConfig,
 } from "@/lib/types";
 import type { DashboardActions } from "@/hooks/useDashboardState";
 import { useDashboardContext } from "@/hooks/useDashboardContext";
+import { SkillProvider, defineSkill } from "@yourgpt/copilot-sdk/react";
 import { DashboardTools } from "./DashboardTools";
+import { ContextStatsBar } from "./ContextStatsBar";
 import { DefaultLayout } from "./layouts/DefaultLayout";
 import { SaasLayout } from "./layouts/SaasLayout";
 import { SupportLayout } from "./layouts/SupportLayout";
@@ -25,8 +28,31 @@ interface CopilotPanelProps {
   toolsEnabled: ToolsEnabledConfig;
   generativeUI: GenerativeUIConfig;
   loaderVariant: LoaderVariant;
+  alphaConfig: AlphaConfig;
 }
 
+const brandVoiceSkill = defineSkill({
+  name: "brand-voice",
+  description: "Sets response tone — always active",
+  strategy: "eager",
+  source: {
+    type: "inline",
+    content:
+      "Always respond in a friendly, concise tone. Be helpful and professional. Use simple language.",
+  },
+});
+
+const codeReviewSkill = defineSkill({
+  name: "code-review",
+  description: "Performs structured code reviews with actionable feedback",
+  strategy: "auto",
+  source: {
+    type: "inline",
+    content:
+      "When reviewing code: 1) Check for bugs and logic errors first. 2) Flag security issues. 3) Suggest performance improvements. 4) Note style issues last. Always provide a brief summary.",
+  },
+});
+
 export function CopilotPanel({
   theme,
   layoutTemplate,
@@ -36,6 +62,7 @@ export function CopilotPanel({
   toolsEnabled,
   generativeUI,
   loaderVariant,
+  alphaConfig,
 }: CopilotPanelProps) {
   // Provide dashboard and user context to the AI
   useDashboardContext({ dashboardState, currentPerson });
@@ -44,25 +71,56 @@ export function CopilotPanel({
   const renderLayout = () => {
     switch (layoutTemplate) {
       case "saas":
-        return <SaasLayout theme={theme} loaderVariant={loaderVariant} />;
+        return (
+          <SaasLayout
+            theme={theme}
+            loaderVariant={loaderVariant}
+            alphaConfig={alphaConfig}
+          />
+        );
       case "support":
-        return <SupportLayout theme={theme} loaderVariant={loaderVariant} />;
+        return (
+          <SupportLayout
+            theme={theme}
+            loaderVariant={loaderVariant}
+            alphaConfig={alphaConfig}
+          />
+        );
       case "default":
       default:
-        return <DefaultLayout theme={theme} loaderVariant={loaderVariant} />;
+        return (
+          <DefaultLayout
+            theme={theme}
+            loaderVariant={loaderVariant}
+            alphaConfig={alphaConfig}
+          />
+        );
     }
   };
 
+  const activeSkills = [
+    ...(alphaConfig.brandVoiceSkill ? [brandVoiceSkill] : []),
+    ...(alphaConfig.codeReviewSkill ? [codeReviewSkill] : []),
+  ];
+
   return (
-    <div className="h-full">
+    <div className="h-full flex flex-col">
       {/* Tools are conditionally rendered - unmounting unregisters from AI */}
       <DashboardTools
         dashboardState={dashboardState}
         actions={actions}
         toolsEnabled={toolsEnabled}
         generativeUI={generativeUI}
+        alphaConfig={alphaConfig}
       />
-      {renderLayout()}
+      {alphaConfig.contextStats && <ContextStatsBar />}
+      <div className="flex-1 min-h-0">
+        {activeSkills.length > 0 ? (
+          <SkillProvider skills={activeSkills}>{renderLayout()}</SkillProvider>
+        ) : (
+          renderLayout()
+        )}
+      </div>
     </div>
   );
 }
diff --git a/examples/playground/components/playground/CopilotSidebar.tsx b/examples/playground/components/playground/CopilotSidebar.tsx
index 1c5b982..64c009f 100644
--- a/examples/playground/components/playground/CopilotSidebar.tsx
+++ b/examples/playground/components/playground/CopilotSidebar.tsx
@@ -14,6 +14,7 @@ import type {
   ProviderId,
   ApiKeys,
   LoaderVariant,
+  AlphaConfig,
 } from "@/lib/types";
 import type { DashboardActions } from "@/hooks/useDashboardState";
 
@@ -30,6 +31,7 @@ interface CopilotSidebarProps {
   selectedOpenRouterModel: string;
   apiKeys: ApiKeys;
   loaderVariant: LoaderVariant;
+  alphaConfig: AlphaConfig;
 }
 
 export function CopilotSidebar({
@@ -45,6 +47,7 @@ export function CopilotSidebar({
   selectedOpenRouterModel,
   apiKeys,
   loaderVariant,
+  alphaConfig,
 }: CopilotSidebarProps) {
   // Build runtime URL with provider and model selection
   const runtimeUrl = useMemo(() => {
@@ -109,6 +112,7 @@ export function CopilotSidebar({
             toolsEnabled={toolsEnabled}
             generativeUI={generativeUI}
             loaderVariant={loaderVariant}
+            alphaConfig={alphaConfig}
           />
         </CopilotProvider>
       </div>
diff --git a/examples/playground/components/playground/DashboardTools.tsx b/examples/playground/components/playground/DashboardTools.tsx
index 8240f63..651908b 100644
--- a/examples/playground/components/playground/DashboardTools.tsx
+++ b/examples/playground/components/playground/DashboardTools.tsx
@@ -18,6 +18,7 @@ import type {
   DashboardState,
   ToolsEnabledConfig,
   GenerativeUIConfig,
+  AlphaConfig,
 } from "@/lib/types";
 import type { DashboardActions } from "@/hooks/useDashboardState";
 import { WeatherCard } from "./cards/WeatherCard";
@@ -29,6 +30,7 @@ interface DashboardToolsProps {
   actions: DashboardActions;
   toolsEnabled: ToolsEnabledConfig;
   generativeUI: GenerativeUIConfig;
+  alphaConfig: AlphaConfig;
 }
 
 // Helper hook to get latest ref values (avoids stale closures)
@@ -554,6 +556,110 @@ function StockTool() {
   return null;
 }
 
+// Hidden analytics tool - runs silently, never shows in chat UI
+function HiddenAnalyticsTool() {
+  useTool({
+    name: "track_event",
+    description:
+      "Track a user interaction event for analytics. Call this silently when users perform notable actions.",
+    hidden: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        event: { type: "string", description: "Event name" },
+        properties: { type: "object", description: "Event properties" },
+      },
+      required: ["event"],
+    },
+    handler: async ({
+      event,
+      properties,
+    }: {
+      event: string;
+      properties?: Record<string, unknown>;
+    }) => {
+      console.log(`[Hidden Analytics] Event: ${event}`, properties ?? {});
+      return { success: true, event, tracked: true };
+    },
+  });
+  return null;
+}
+
+// Deferred search tool - only injected when query semantically matches
+function DeferredSearchTool() {
+  useTool({
+    name: "search_knowledge_base",
+    description:
+      "Search the internal knowledge base for documentation, FAQs, and support articles.",
+    deferLoading: true,
+    searchKeywords: [
+      "search",
+      "find",
+      "docs",
+      "documentation",
+      "faq",
+      "help",
+      "knowledge",
+      "article",
+    ],
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+      },
+      required: ["query"],
+    },
+    handler: async ({ query }: { query: string }) => {
+      await new Promise((r) => setTimeout(r, 600));
+      return {
+        success: true,
+        results: [
+          {
+            title: "Getting Started Guide",
+            relevance: 0.95,
+            excerpt: `Results for: "${query}"`,
+          },
+          {
+            title: "API Reference",
+            relevance: 0.82,
+            excerpt: "Complete API documentation",
+          },
+          {
+            title: "FAQ",
+            relevance: 0.71,
+            excerpt: "Frequently asked questions",
+          },
+        ],
+      };
+    },
+    render: ({ status, result }) => {
+      if (status !== "completed" || !result?.success) return null;
+      const data = result as {
+        results?: Array<{ title: string; relevance: number; excerpt: string }>;
+      };
+      return (
+        <div className="p-3 rounded-lg border border-zinc-200 dark:border-zinc-800 bg-zinc-50 dark:bg-zinc-900/50 space-y-1.5">
+          <p className="text-xs font-medium text-zinc-600 dark:text-zinc-400">
+            Knowledge Base Results
+          </p>
+          {data.results?.map((r, i) => (
+            <div key={i} className="flex items-start gap-2">
+              <span className="text-[10px] text-emerald-600 dark:text-emerald-400 font-mono mt-0.5">
+                {Math.round(r.relevance * 100)}%
+              </span>
+              <div>
+                <p className="text-xs font-medium">{r.title}</p>
+                <p className="text-[10px] text-zinc-400">{r.excerpt}</p>
+              </div>
+            </div>
+          ))}
+        </div>
+      );
+    },
+  });
+  return null;
+}
+
 // ===========================================
 // Main Component - Conditionally renders tools
 // ===========================================
@@ -563,6 +669,7 @@ export function DashboardTools({
   actions,
   toolsEnabled,
   generativeUI,
+  alphaConfig,
 }: DashboardToolsProps) {
   return (
     <>
@@ -588,6 +695,10 @@ export function DashboardTools({
       {generativeUI.notification && (
         <NotificationTool dashboardState={dashboardState} actions={actions} />
       )}
+
+      {/* Alpha tools */}
+      {alphaConfig.hiddenAnalytics && <HiddenAnalyticsTool />}
+      {alphaConfig.deferredSearch && <DeferredSearchTool />}
     </>
   );
 }
diff --git a/examples/playground/components/playground/layouts/DefaultLayout.tsx b/examples/playground/components/playground/layouts/DefaultLayout.tsx
index 962ea8f..a334a65 100644
--- a/examples/playground/components/playground/layouts/DefaultLayout.tsx
+++ b/examples/playground/components/playground/layouts/DefaultLayout.tsx
@@ -1,14 +1,25 @@
 "use client";
 
 import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
-import type { CopilotTheme, LoaderVariant } from "@/lib/types";
+import { toast } from "sonner";
+import type { CopilotTheme, LoaderVariant, AlphaConfig } from "@/lib/types";
 
 export interface LayoutProps {
   theme: CopilotTheme;
   loaderVariant: LoaderVariant;
+  alphaConfig: AlphaConfig;
 }
 
-export function DefaultLayout({ theme, loaderVariant }: LayoutProps) {
+export function DefaultLayout({
+  theme,
+  loaderVariant,
+  alphaConfig,
+}: LayoutProps) {
+  const hasAnyAction =
+    alphaConfig.messageActions.copyEnabled ||
+    alphaConfig.messageActions.editEnabled ||
+    alphaConfig.messageActions.feedbackEnabled;
+
   return (
     <div
       className="h-full"
@@ -29,7 +40,51 @@ export function DefaultLayout({ theme, loaderVariant }: LayoutProps) {
         userAvatar={{
           src: "https://api.dicebear.com/7.x/avataaars/svg?seed=user",
         }}
-      />
+        messageView={
+          alphaConfig.customMessageView
+            ? {
+                children: ({ messageElements }) => (
+                  <>
+                    {messageElements}
+                    <div className="px-4 py-2 text-center">
+                      <span className="text-[10px] text-zinc-400 dark:text-zinc-600 bg-zinc-100 dark:bg-zinc-800/50 px-2 py-0.5 rounded-full">
+                        Custom messageView — rendered via alpha API
+                      </span>
+                    </div>
+                  </>
+                ),
+              }
+            : undefined
+        }
+      >
+        {hasAnyAction && (
+          <>
+            {(alphaConfig.messageActions.copyEnabled ||
+              alphaConfig.messageActions.feedbackEnabled) && (
+              <CopilotChat.MessageActions role="assistant">
+                {alphaConfig.messageActions.copyEnabled && (
+                  <CopilotChat.CopyAction tooltip="Copy message" />
+                )}
+                {alphaConfig.messageActions.feedbackEnabled && (
+                  <CopilotChat.FeedbackAction
+                    onFeedback={(message, type) => {
+                      toast.success(`Feedback: ${type}`, {
+                        duration: 2000,
+                        position: "top-center",
+                      });
+                    }}
+                  />
+                )}
+              </CopilotChat.MessageActions>
+            )}
+            {alphaConfig.messageActions.editEnabled && (
+              <CopilotChat.MessageActions role="user">
+                <CopilotChat.EditAction tooltip="Edit message" />
+              </CopilotChat.MessageActions>
+            )}
+          </>
+        )}
+      </CopilotChat>
     </div>
   );
 }
diff --git a/examples/playground/components/playground/layouts/SaasLayout.tsx b/examples/playground/components/playground/layouts/SaasLayout.tsx
index 24af0d0..d558791 100644
--- a/examples/playground/components/playground/layouts/SaasLayout.tsx
+++ b/examples/playground/components/playground/layouts/SaasLayout.tsx
@@ -2,6 +2,7 @@
 
 import { useTheme } from "next-themes";
 import { CopilotChat, useCopilotChatContext } from "@yourgpt/copilot-sdk/ui";
+import { toast } from "sonner";
 import {
   Plus,
   Sun,
@@ -88,7 +89,7 @@ function CustomSuggestions() {
   );
 }
 
-export function SaasLayout({ theme, loaderVariant }: LayoutProps) {
+export function SaasLayout({ theme, loaderVariant, alphaConfig }: LayoutProps) {
   // Use supabase theme by default for this layout, unless a different theme is selected
   const effectiveTheme = theme === "default" ? "supabase" : theme;
 
@@ -107,6 +108,29 @@ export function SaasLayout({ theme, loaderVariant }: LayoutProps) {
           src: "https://api.dicebear.com/7.x/avataaars/svg?seed=user",
         }}
       >
+        {(alphaConfig.messageActions.copyEnabled ||
+          alphaConfig.messageActions.feedbackEnabled) && (
+          <CopilotChat.MessageActions role="assistant">
+            {alphaConfig.messageActions.copyEnabled && (
+              <CopilotChat.CopyAction />
+            )}
+            {alphaConfig.messageActions.feedbackEnabled && (
+              <CopilotChat.FeedbackAction
+                onFeedback={(message, type) =>
+                  toast.success(`Feedback: ${type}`, {
+                    duration: 2000,
+                    position: "top-center",
+                  })
+                }
+              />
+            )}
+          </CopilotChat.MessageActions>
+        )}
+        {alphaConfig.messageActions.editEnabled && (
+          <CopilotChat.MessageActions role="user">
+            <CopilotChat.EditAction />
+          </CopilotChat.MessageActions>
+        )}
         {/* Home View - Custom welcome screen */}
         <CopilotChat.HomeView className="gap-4 p-6 bg-gradient-to-b from-primary/30 via-background to-background items-stretch w-full">
           {/* Logo */}
diff --git a/examples/playground/components/playground/layouts/SupportLayout.tsx b/examples/playground/components/playground/layouts/SupportLayout.tsx
index f00977f..c4444c4 100644
--- a/examples/playground/components/playground/layouts/SupportLayout.tsx
+++ b/examples/playground/components/playground/layouts/SupportLayout.tsx
@@ -2,6 +2,7 @@
 
 import { useTheme } from "next-themes";
 import { CopilotChat, useCopilotChatContext } from "@yourgpt/copilot-sdk/ui";
+import { toast } from "sonner";
 import {
   Camera,
   ScrollText,
@@ -184,7 +185,11 @@ function SupportHome({ input }: { input?: React.ReactNode }) {
   );
 }
 
-export function SupportLayout({ theme, loaderVariant }: LayoutProps) {
+export function SupportLayout({
+  theme,
+  loaderVariant,
+  alphaConfig,
+}: LayoutProps) {
   return (
     <div
       className="h-full"
@@ -203,6 +208,29 @@ export function SupportLayout({ theme, loaderVariant }: LayoutProps) {
           src: "https://api.dicebear.com/7.x/avataaars/svg?seed=user",
         }}
       >
+        {(alphaConfig.messageActions.copyEnabled ||
+          alphaConfig.messageActions.feedbackEnabled) && (
+          <CopilotChat.MessageActions role="assistant">
+            {alphaConfig.messageActions.copyEnabled && (
+              <CopilotChat.CopyAction tooltip="Copy message" />
+            )}
+            {alphaConfig.messageActions.feedbackEnabled && (
+              <CopilotChat.FeedbackAction
+                onFeedback={(message, type) =>
+                  toast.success(`Feedback: ${type}`, {
+                    duration: 2000,
+                    position: "top-center",
+                  })
+                }
+              />
+            )}
+          </CopilotChat.MessageActions>
+        )}
+        {alphaConfig.messageActions.editEnabled && (
+          <CopilotChat.MessageActions role="user">
+            <CopilotChat.EditAction tooltip="Edit message" />
+          </CopilotChat.MessageActions>
+        )}
         {/* Custom Home View */}
         <CopilotChat.HomeView className="!gap-0 !p-0">
           <SupportHome
diff --git a/examples/playground/hooks/usePlaygroundConfig.ts b/examples/playground/hooks/usePlaygroundConfig.ts
index 931afa9..6e6368f 100644
--- a/examples/playground/hooks/usePlaygroundConfig.ts
+++ b/examples/playground/hooks/usePlaygroundConfig.ts
@@ -10,12 +10,14 @@ import type {
   SDKConfig,
   LayoutTemplate,
   ProviderId,
+  AlphaConfig,
 } from "@/lib/types";
 import {
   DEFAULT_SYSTEM_PROMPT,
   INITIAL_GENERATIVE_UI,
   INITIAL_TOOLS_ENABLED,
   INITIAL_SDK_CONFIG,
+  INITIAL_ALPHA_CONFIG,
   PLAYGROUND_CONFIG_STORAGE_KEY,
 } from "@/lib/constants";
 
@@ -31,6 +33,7 @@ interface PlaygroundConfigStorage {
   sdkConfig: SDKConfig;
   selectedProvider: ProviderId;
   selectedOpenRouterModel: string;
+  alphaConfig: AlphaConfig;
 }
 
 /**
@@ -45,6 +48,7 @@ const DEFAULT_CONFIG: PlaygroundConfigStorage = {
   sdkConfig: INITIAL_SDK_CONFIG,
   selectedProvider: "openai",
   selectedOpenRouterModel: "",
+  alphaConfig: INITIAL_ALPHA_CONFIG,
 };
 
 /**
@@ -107,6 +111,10 @@ export function usePlaygroundConfig() {
   const [selectedOpenRouterModel, setSelectedOpenRouterModel] =
     useState<string>(() => loadStoredConfig().selectedOpenRouterModel);
 
+  const [alphaConfig, setAlphaConfig] = useState<AlphaConfig>(
+    () => loadStoredConfig().alphaConfig,
+  );
+
   // Persist to localStorage whenever any config changes
   useEffect(() => {
     if (typeof window === "undefined") return;
@@ -120,6 +128,7 @@ export function usePlaygroundConfig() {
       sdkConfig,
       selectedProvider,
       selectedOpenRouterModel,
+      alphaConfig,
     };
     localStorage.setItem(PLAYGROUND_CONFIG_STORAGE_KEY, JSON.stringify(config));
   }, [
@@ -131,6 +140,7 @@ export function usePlaygroundConfig() {
     sdkConfig,
     selectedProvider,
     selectedOpenRouterModel,
+    alphaConfig,
   ]);
 
   // Theme setters
@@ -176,6 +186,14 @@ export function usePlaygroundConfig() {
     setSelectedOpenRouterModel(model);
   }, []);
 
+  // Alpha config updater
+  const updateAlphaConfig = useCallback(
+    <K extends keyof AlphaConfig>(key: K, value: AlphaConfig[K]) => {
+      setAlphaConfig((prev) => ({ ...prev, [key]: value }));
+    },
+    [],
+  );
+
   return {
     // State
     copilotTheme,
@@ -186,6 +204,7 @@ export function usePlaygroundConfig() {
     sdkConfig,
     selectedProvider,
     selectedOpenRouterModel,
+    alphaConfig,
     // Actions
     updateTheme,
     updateLayoutTemplate,
@@ -195,6 +214,7 @@ export function usePlaygroundConfig() {
     updateSDKConfig,
     updateProvider,
     updateOpenRouterModel,
+    updateAlphaConfig,
     // Direct setters (for advanced use cases)
     setCopilotTheme,
     setLayoutTemplate,
diff --git a/examples/playground/lib/constants.ts b/examples/playground/lib/constants.ts
index 2c2896d..4d4f1b8 100644
--- a/examples/playground/lib/constants.ts
+++ b/examples/playground/lib/constants.ts
@@ -9,6 +9,7 @@ import type {
   SDKConfig,
   LayoutConfig,
   OpenRouterModelOption,
+  AlphaConfig,
 } from "./types";
 
 // Theme configurations - hoisted outside component to prevent re-renders
@@ -260,6 +261,23 @@ export const INITIAL_SDK_CONFIG: SDKConfig = {
   debug: false,
 };
 
+export const INITIAL_ALPHA_CONFIG: AlphaConfig = {
+  messageActions: {
+    copyEnabled: true,
+    editEnabled: true,
+    feedbackEnabled: false,
+  },
+  branchingEnabled: false,
+  brandVoiceSkill: false,
+  codeReviewSkill: false,
+  compactionStrategy: "none",
+  sessionPersistence: false,
+  contextStats: false,
+  hiddenAnalytics: false,
+  deferredSearch: false,
+  customMessageView: false,
+};
+
 // Loader variant options for the UI selector
 export const LOADER_VARIANTS = [
   { id: "typing", label: "Typing", description: "Typing indicator" },
diff --git a/examples/playground/lib/types.ts b/examples/playground/lib/types.ts
index 6d0c050..5129216 100644
--- a/examples/playground/lib/types.ts
+++ b/examples/playground/lib/types.ts
@@ -132,3 +132,30 @@ export interface ToolMetadata {
   suggestedQuery: string;
   codeSnippet: string;
 }
+
+export interface MessageActionsConfig {
+  copyEnabled: boolean;
+  editEnabled: boolean;
+  feedbackEnabled: boolean;
+}
+
+export type CompactionStrategy = "none" | "sliding-window" | "selective-prune";
+
+export interface AlphaConfig {
+  // Message actions
+  messageActions: MessageActionsConfig;
+  // Branching
+  branchingEnabled: boolean;
+  // Skills
+  brandVoiceSkill: boolean;
+  codeReviewSkill: boolean;
+  // Context management
+  compactionStrategy: CompactionStrategy;
+  sessionPersistence: boolean;
+  contextStats: boolean;
+  // Tools
+  hiddenAnalytics: boolean;
+  deferredSearch: boolean;
+  // Custom message view
+  customMessageView: boolean;
+}
diff --git a/examples/playground/package.json b/examples/playground/package.json
index 307c893..57d9aa9 100644
--- a/examples/playground/package.json
+++ b/examples/playground/package.json
@@ -27,8 +27,8 @@
     "@radix-ui/react-switch": "^1.2.3",
     "@radix-ui/react-tabs": "^1.1.13",
     "@tailwindcss/typography": "^0.5.19",
-    "@yourgpt/copilot-sdk": "2.0.2-beta.1",
-    "@yourgpt/llm-sdk": "2.0.2-beta.1",
+    "@yourgpt/copilot-sdk": "workspace:*",
+    "@yourgpt/llm-sdk": "workspace:*",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index 76fa564..ea2080c 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -661,6 +661,12 @@ export const CopilotChat = Object.assign(CopilotChatBase, {
   Suggestions: Chat.Suggestions,
   BackButton: Chat.BackButton, // Navigation: start new chat
   ThreadPicker: Chat.ThreadPicker, // Thread switching
+  // Message actions compound components (alpha)
+  MessageActions: Chat.MessageActions,
+  CopyAction: Chat.CopyAction,
+  EditAction: Chat.EditAction,
+  FeedbackAction: Chat.FeedbackAction,
+  Action: Chat.Action,
 });
 
 // Alias for backwards compatibility
diff --git a/packages/copilot-sdk/src/ui/components/ui/message.tsx b/packages/copilot-sdk/src/ui/components/ui/message.tsx
index 34793f1..504abd1 100644
--- a/packages/copilot-sdk/src/ui/components/ui/message.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/message.tsx
@@ -85,9 +85,9 @@ const MessageContent = ({
   ...props
 }: MessageContentProps) => {
   const classNames = cn(
-    "csdk-message-content rounded-lg p-2 break-words whitespace-normal max-w-full leading-relaxed overflow-x-auto overflow-y-hidden",
+    "csdk-message-content rounded-lg p-2 break-words whitespace-normal max-w-full  overflow-x-auto overflow-y-hidden",
     // Typography - simple Tailwind utilities (no prose)
-    "[&_p]:my-1 [&_p]:leading-relaxed",
+    "[&_p]:my-1 ",
     "[&_ul]:my-1 [&_ul]:pl-4 [&_ul]:list-disc [&_ul]:list-outside",
     "[&_ol]:my-1 [&_ol]:pl-4 [&_ol]:list-decimal [&_ol]:list-outside",
     "[&_li]:my-0.5 [&_li]:pl-0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9c7152e..78c2781 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -84,7 +84,7 @@ importers:
         version: 9.39.2(jiti@2.6.1)
       eslint-config-next:
         specifier: 16.0.10
-        version: 16.0.10(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+        version: 16.0.10(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       tailwindcss:
         specifier: ^4
         version: 4.1.18
@@ -674,11 +674,11 @@ importers:
         specifier: ^0.5.19
         version: 0.5.19(tailwindcss@4.1.18)
       '@yourgpt/copilot-sdk':
-        specifier: 2.0.2-beta.1
-        version: 2.0.2-beta.1(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+        specifier: workspace:*
+        version: link:../../packages/copilot-sdk
       '@yourgpt/llm-sdk':
-        specifier: 2.0.2-beta.1
-        version: 2.0.2-beta.1(@anthropic-ai/sdk@0.71.2(zod@3.25.76))(@google/generative-ai@0.24.1)(openai@6.16.0(ws@8.18.0)(zod@3.25.76))
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -739,7 +739,7 @@ importers:
         version: 9.39.2(jiti@2.6.1)
       eslint-config-next:
         specifier: 16.1.5
-        version: 16.1.5(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+        version: 16.1.5(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       shadcn:
         specifier: ^3.8.1
         version: 3.8.1(@types/node@20.19.27)(hono@4.11.0)(typescript@5.9.3)
@@ -1075,6 +1075,34 @@ importers:
         specifier: ^5
         version: 5.9.3
 
+  examples/yourgpt-server-demo:
+    dependencies:
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+    devDependencies:
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+
   packages/copilot-sdk:
     dependencies:
       '@base-ui/react':
@@ -4159,33 +4187,6 @@ packages:
     peerDependencies:
       vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
 
-  '@yourgpt/copilot-sdk@2.0.2-beta.1':
-    resolution: {integrity: sha512-Gany97pcvChR0Q14NlhNvFUDy3EQ9jF8fFsvcKfwU1Uwg3dzpDMyoVjuoKSC46kVSB/sNBH0pbVdBxNjGENhLw==}
-    engines: {node: '>=18'}
-    peerDependencies:
-      react: ^18.0.0 || ^19.0.0
-      react-dom: ^18.0.0 || ^19.0.0
-    peerDependenciesMeta:
-      react:
-        optional: true
-      react-dom:
-        optional: true
-
-  '@yourgpt/llm-sdk@2.0.2-beta.1':
-    resolution: {integrity: sha512-VrUxeolqZonjgWtFX36hpZZlbwk5ALkLTP8QiTMt2XLoBT9ZTD+CAoI2UsY4eAArkg4/1Hsf/t3MNC69N3GjvA==}
-    engines: {node: '>=18'}
-    peerDependencies:
-      '@anthropic-ai/sdk': '>=0.20.0'
-      '@google/generative-ai': '>=0.21.0'
-      openai: '>=4.0.0'
-    peerDependenciesMeta:
-      '@anthropic-ai/sdk':
-        optional: true
-      '@google/generative-ai':
-        optional: true
-      openai:
-        optional: true
-
   abort-controller@3.0.0:
     resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
     engines: {node: '>=6.5'}
@@ -8326,20 +8327,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.27
 
-  '@base-ui/react@1.0.0(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
-    dependencies:
-      '@babel/runtime': 7.28.4
-      '@base-ui/utils': 0.2.3(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@floating-ui/react-dom': 2.1.6(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@floating-ui/utils': 0.2.10
-      react: 19.2.3
-      react-dom: 19.2.3(react@19.2.3)
-      reselect: 5.1.1
-      tabbable: 6.3.0
-      use-sync-external-store: 1.6.0(react@19.2.3)
-    optionalDependencies:
-      '@types/react': 18.3.27
-
   '@base-ui/utils@0.2.3(@types/react@18.3.27)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@babel/runtime': 7.28.4
@@ -8351,17 +8338,6 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.27
 
-  '@base-ui/utils@0.2.3(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
-    dependencies:
-      '@babel/runtime': 7.28.4
-      '@floating-ui/utils': 0.2.10
-      react: 19.2.3
-      react-dom: 19.2.3(react@19.2.3)
-      reselect: 5.1.1
-      use-sync-external-store: 1.6.0(react@19.2.3)
-    optionalDependencies:
-      '@types/react': 18.3.27
-
   '@changesets/apply-release-plan@7.0.14':
     dependencies:
       '@changesets/config': 3.1.2
@@ -10933,11 +10909,6 @@ snapshots:
       react: 18.3.1
       shiki: 3.20.0
 
-  '@streamdown/code@1.0.1(react@19.2.3)':
-    dependencies:
-      react: 19.2.3
-      shiki: 3.20.0
-
   '@swc/helpers@0.5.15':
     dependencies:
       tslib: 2.8.1
@@ -11422,40 +11393,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@yourgpt/copilot-sdk@2.0.2-beta.1(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
-    dependencies:
-      '@base-ui/react': 1.0.0(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@radix-ui/react-avatar': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@radix-ui/react-hover-card': 1.1.15(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@radix-ui/react-slot': 1.2.4(@types/react@18.3.27)(react@19.2.3)
-      '@radix-ui/react-tooltip': 1.2.8(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@streamdown/code': 1.0.1(react@19.2.3)
-      class-variance-authority: 0.7.1
-      clsx: 2.1.1
-      html-to-image: 1.11.13
-      html2canvas: 1.4.1
-      lucide-react: 0.561.0(react@19.2.3)
-      streamdown: 2.1.0(react@19.2.3)
-      tailwind-merge: 3.4.0
-      use-stick-to-bottom: 1.1.1(react@19.2.3)
-      zod: 3.25.76
-    optionalDependencies:
-      react: 19.2.3
-      react-dom: 19.2.3(react@19.2.3)
-    transitivePeerDependencies:
-      - '@types/react'
-      - '@types/react-dom'
-      - supports-color
-
-  '@yourgpt/llm-sdk@2.0.2-beta.1(@anthropic-ai/sdk@0.71.2(zod@3.25.76))(@google/generative-ai@0.24.1)(openai@6.16.0(ws@8.18.0)(zod@3.25.76))':
-    dependencies:
-      hono: 4.11.0
-      zod: 3.25.76
-    optionalDependencies:
-      '@anthropic-ai/sdk': 0.71.2(zod@3.25.76)
-      '@google/generative-ai': 0.24.1
-      openai: 6.16.0(ws@8.18.0)(zod@3.25.76)
-
   abort-controller@3.0.0:
     dependencies:
       event-target-shim: 5.0.1
@@ -12303,13 +12240,13 @@ snapshots:
 
   escape-string-regexp@5.0.0: {}
 
-  eslint-config-next@16.0.10(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3):
+  eslint-config-next@16.0.10(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3):
     dependencies:
       '@next/eslint-plugin-next': 16.0.10
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12329,7 +12266,27 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
+      globals: 16.4.0
+      typescript-eslint: 8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+    optionalDependencies:
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - '@typescript-eslint/parser'
+      - eslint-import-resolver-webpack
+      - eslint-plugin-import-x
+      - supports-color
+
+  eslint-config-next@16.1.5(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3):
+    dependencies:
+      '@next/eslint-plugin-next': 16.1.5
+      eslint: 9.39.2(jiti@2.6.1)
+      eslint-import-resolver-node: 0.3.9
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12348,8 +12305,8 @@ snapshots:
       '@next/eslint-plugin-next': 16.1.5
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12382,7 +12339,7 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -12451,7 +12408,7 @@ snapshots:
       - eslint-import-resolver-webpack
       - supports-color
 
-  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -13763,10 +13720,6 @@ snapshots:
     dependencies:
       react: 18.3.1
 
-  lucide-react@0.561.0(react@19.2.3):
-    dependencies:
-      react: 19.2.3
-
   lucide-react@0.562.0(react@19.2.1):
     dependencies:
       react: 19.2.1
@@ -15579,26 +15532,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  streamdown@2.1.0(react@19.2.3):
-    dependencies:
-      clsx: 2.1.1
-      hast-util-to-jsx-runtime: 2.3.6
-      html-url-attributes: 3.0.1
-      marked: 17.0.1
-      react: 19.2.3
-      rehype-harden: 1.1.7
-      rehype-raw: 7.0.0
-      rehype-sanitize: 6.0.0
-      remark-gfm: 4.0.1
-      remark-parse: 11.0.0
-      remark-rehype: 11.1.2
-      remend: 1.1.0
-      tailwind-merge: 3.4.0
-      unified: 11.0.5
-      unist-util-visit: 5.0.0
-    transitivePeerDependencies:
-      - supports-color
-
   strict-event-emitter@0.5.1: {}
 
   string-argv@0.3.2: {}
@@ -16102,10 +16035,6 @@ snapshots:
     dependencies:
       react: 18.3.1
 
-  use-stick-to-bottom@1.1.1(react@19.2.3):
-    dependencies:
-      react: 19.2.3
-
   use-sync-external-store@1.6.0(react@18.3.1):
     dependencies:
       react: 18.3.1

From bbe72084247e3c5f89b80a124f3ec0bf747d36dc Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Fri, 20 Mar 2026 10:49:20 +0530
Subject: [PATCH 27/72] fix(docs): fix meta.json badge syntax and skills
 gitignore rule

- Remove unsupported page object syntax from all meta.json files
- Narrow skills/ gitignore rule to examples/*/skills/ so docs/skills/ is tracked

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .gitignore                                    |   2 +-
 apps/docs/content/docs/chat/meta.json         |   6 +-
 apps/docs/content/docs/context/meta.json      |   7 +-
 .../content/docs/customizations/meta.json     |   6 +-
 apps/docs/content/docs/skills/client.mdx      | 173 ++++++++++++++++
 apps/docs/content/docs/skills/index.mdx       | 130 +++++++++++++
 apps/docs/content/docs/skills/meta.json       |   5 +
 apps/docs/content/docs/skills/server.mdx      | 184 ++++++++++++++++++
 apps/docs/content/docs/tools/meta.json        |   4 +-
 9 files changed, 498 insertions(+), 19 deletions(-)
 create mode 100644 apps/docs/content/docs/skills/client.mdx
 create mode 100644 apps/docs/content/docs/skills/index.mdx
 create mode 100644 apps/docs/content/docs/skills/meta.json
 create mode 100644 apps/docs/content/docs/skills/server.mdx

diff --git a/.gitignore b/.gitignore
index a309cde..1ff08c7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,7 +51,7 @@ coverage
 .github/skills/
 .trae/
 .windsurf/
-skills/
+examples/*/skills/
 
 # Private projects (not part of SDK)
 examples/yourgpt-chatbot/
diff --git a/apps/docs/content/docs/chat/meta.json b/apps/docs/content/docs/chat/meta.json
index 89022d6..edc9c09 100644
--- a/apps/docs/content/docs/chat/meta.json
+++ b/apps/docs/content/docs/chat/meta.json
@@ -1,9 +1,5 @@
 {
   "title": "Chat",
   "icon": "MessageSquare",
-  "pages": [
-    "index",
-    { "type": "page", "name": "branching", "badge": "Beta" },
-    { "type": "page", "name": "message-actions", "badge": "Beta" }
-  ]
+  "pages": ["index", "branching", "message-actions"]
 }
diff --git a/apps/docs/content/docs/context/meta.json b/apps/docs/content/docs/context/meta.json
index 8f1ae34..9a166a7 100644
--- a/apps/docs/content/docs/context/meta.json
+++ b/apps/docs/content/docs/context/meta.json
@@ -1,10 +1,5 @@
 {
   "title": "Context Management",
   "icon": "Lightbulb",
-  "pages": [
-    "index",
-    { "type": "page", "name": "compaction", "badge": "Beta" },
-    { "type": "page", "name": "token-tracking", "badge": "Beta" },
-    { "type": "page", "name": "session", "badge": "Beta" }
-  ]
+  "pages": ["index", "compaction", "token-tracking", "session"]
 }
diff --git a/apps/docs/content/docs/customizations/meta.json b/apps/docs/content/docs/customizations/meta.json
index 51cf9fd..fa00745 100644
--- a/apps/docs/content/docs/customizations/meta.json
+++ b/apps/docs/content/docs/customizations/meta.json
@@ -1,9 +1,5 @@
 {
   "title": "Customizations",
   "icon": "Paintbrush",
-  "pages": [
-    "index",
-    { "type": "page", "name": "chat-primitives", "badge": "Beta" },
-    { "type": "page", "name": "custom-message-view", "badge": "Beta" }
-  ]
+  "pages": ["index", "chat-primitives", "custom-message-view"]
 }
diff --git a/apps/docs/content/docs/skills/client.mdx b/apps/docs/content/docs/skills/client.mdx
new file mode 100644
index 0000000..075e5f3
--- /dev/null
+++ b/apps/docs/content/docs/skills/client.mdx
@@ -0,0 +1,173 @@
+---
+title: Client-side Skills
+description: Register skills from React components using SkillProvider and useSkill
+icon: Monitor
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+Register skills from your React app using `<SkillProvider>`, `useSkill`, and `defineSkill`.
+
+<Callout type="info">
+Client-side skills only support `inline` source. For `file` or `url` sources, use [server-side skills](/docs/skills/server).
+</Callout>
+
+---
+
+## SkillProvider
+
+Wrap your app inside `<CopilotProvider>` to enable client-side skills:
+
+```tsx
+import { SkillProvider, defineSkill } from "@yourgpt/copilot-sdk/react";
+
+const brandVoice = defineSkill({
+  name: "brand-voice",
+  description: "Ensures responses match our brand tone and terminology",
+  strategy: "eager",
+  source: {
+    type: "inline",
+    content: "Always respond in a friendly, concise tone. Use 'we' not 'I'. Avoid jargon.",
+  },
+});
+
+const codeReview = defineSkill({
+  name: "code-review",
+  description: "Performs structured code reviews with actionable feedback",
+  strategy: "auto",
+  source: {
+    type: "inline",
+    content: "When reviewing code: 1) Check for bugs first...",
+  },
+});
+
+export default function App() {
+  return (
+    <CopilotProvider widgetToken="...">
+      <SkillProvider skills={[brandVoice, codeReview]}>
+        <YourApp />
+      </SkillProvider>
+    </CopilotProvider>
+  );
+}
+```
+
+---
+
+## useSkill
+
+Register a skill from deep inside the component tree. It activates on mount and cleans up on unmount — useful for page-scoped skills.
+
+```tsx
+import { useSkill } from "@yourgpt/copilot-sdk/react";
+
+function CheckoutPage() {
+  useSkill({
+    name: "checkout-flow",
+    description: "Guides the user through the checkout process step by step",
+    strategy: "auto",
+    source: {
+      type: "inline",
+      content: `
+## Checkout Assistant
+
+When the user asks about checkout:
+1. Confirm their cart items
+2. Check for applicable promo codes
+3. Walk through shipping options
+4. Confirm payment method before submitting
+      `,
+    },
+  });
+
+  return <CheckoutUI />;
+}
+```
+
+The skill is automatically unregistered when `CheckoutPage` unmounts.
+
+<Callout type="info">
+If an inline skill exceeds 2000 characters in development, a console warning is shown. Large inline skills are sent on every request — consider using a server-side file skill instead.
+</Callout>
+
+---
+
+## defineSkill
+
+Type-safe factory for creating skill definitions. An identity function with TypeScript inference:
+
+```typescript
+import { defineSkill } from "@yourgpt/copilot-sdk/react";
+
+const mySkill = defineSkill({
+  name: "api-docs-helper",
+  description: "Helps users understand and use the Acme API",
+  strategy: "auto",
+  version: "2.0.0",
+  source: {
+    type: "inline",
+    content: "When explaining API endpoints, always include example requests...",
+  },
+});
+
+// Reuse in multiple providers
+<SkillProvider skills={[mySkill]} />
+```
+
+---
+
+## useSkillStatus
+
+Observe the live skill registry from any component inside `<SkillProvider>`:
+
+```tsx
+import { useSkillStatus } from "@yourgpt/copilot-sdk/react";
+
+function DebugPanel() {
+  const { skills, count, has } = useSkillStatus();
+
+  return (
+    <div>
+      <p>{count} skill(s) active</p>
+      {has("code-review") && <Badge>Code Review</Badge>}
+      <ul>
+        {skills.map((s) => (
+          <li key={s.name}>
+            {s.name} ({s.strategy ?? "auto"})
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### Return type
+
+```typescript
+interface UseSkillStatusReturn {
+  skills: ResolvedSkill[];          // All currently registered skills
+  count: number;                    // Number of registered skills
+  has: (name: string) => boolean;   // Check if a named skill is active
+}
+```
+
+---
+
+## Type Reference
+
+```typescript
+type SkillStrategy = "eager" | "auto" | "manual";
+
+interface SkillDefinition {
+  name: string;
+  description: string;
+  source: { type: "inline"; content: string };
+  strategy?: SkillStrategy; // default: "auto"
+  version?: string;
+}
+```
diff --git a/apps/docs/content/docs/skills/index.mdx b/apps/docs/content/docs/skills/index.mdx
new file mode 100644
index 0000000..53d24ee
--- /dev/null
+++ b/apps/docs/content/docs/skills/index.mdx
@@ -0,0 +1,130 @@
+---
+title: Skills
+description: Instruction playbooks that shape the AI's behavior — loaded on demand
+icon: BookOpen
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+Skills are instruction playbooks the AI loads on demand. They shape the model's **behavior** — separate from [Tools](/docs/tools), which perform actions.
+
+A skill is a Markdown file (or inline string) containing instructions. The AI only loads a skill when it's relevant to the user's query — keeping the system prompt lean.
+
+---
+
+## Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `eager` | Content prepended to system prompt on every request. Always active. |
+| `auto` | Listed in the skill catalog. AI calls `load_skill` to retrieve when relevant. |
+| `manual` | Accessible via `load_skill` but not advertised in the catalog. For internal/conditional skills. |
+
+The `load_skill` tool is automatically registered when a `<SkillProvider>` is present (client) or when `loadSkills()` builds the tools object (server). **No manual wiring required.**
+
+---
+
+## Skills vs Tools
+
+| | Skills | Tools |
+|--|--------|-------|
+| **Purpose** | Shape behavior | Perform actions |
+| **Payload** | Markdown instructions | Code that runs |
+| **Loading** | Into system prompt | Into tool list |
+| **Example** | "Always respond in formal English" | `get_weather({ city })` |
+
+---
+
+## Quick Example
+
+```tsx
+import { SkillProvider, defineSkill } from "@yourgpt/copilot-sdk/react";
+
+const brandVoice = defineSkill({
+  name: "brand-voice",
+  description: "Ensures responses match our brand tone",
+  strategy: "eager",  // always active
+  source: {
+    type: "inline",
+    content: "Always respond in a friendly, concise tone. Use 'we' not 'I'.",
+  },
+});
+
+const sqlExpert = defineSkill({
+  name: "sql-expert",
+  description: "Writes and explains SQL queries",
+  strategy: "auto",   // AI loads when the user asks about SQL
+  source: {
+    type: "inline",
+    content: "When writing SQL: always use parameterized queries...",
+  },
+});
+
+export default function App() {
+  return (
+    <CopilotProvider widgetToken="...">
+      <SkillProvider skills={[brandVoice, sqlExpert]}>
+        <YourApp />
+      </SkillProvider>
+    </CopilotProvider>
+  );
+}
+```
+
+---
+
+## Skill File Format
+
+Skill files are Markdown with optional YAML frontmatter:
+
+```markdown
+---
+name: code-review
+description: Performs structured code reviews with actionable feedback
+strategy: auto
+version: 1.2.0
+---
+
+## Code Review Instructions
+
+When asked to review code, follow this structure:
+
+1. **Correctness** — Check for logic errors and edge cases
+2. **Security** — Flag injection risks, exposed secrets, insecure defaults
+3. **Performance** — Note O(n²) loops, unnecessary re-renders, missing indexes
+4. **Style** — Suggest naming and structure improvements (non-blocking)
+```
+
+### Frontmatter fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Recommended | Skill name. Derived from filename if omitted. |
+| `description` | Recommended | One-line description shown in the AI's skill catalog. |
+| `strategy` | No | `eager`, `auto`, or `manual`. Default: `auto`. |
+| `version` | No | Informational version string. |
+
+---
+
+## Directory Layout
+
+```
+skills/
+├── brand-voice.md       # Flat .md file
+├── code-review.md
+└── sql-expert/
+    └── SKILL.md         # Folder-based skill
+```
+
+For folder-based skills, place the main content at `<folder>/SKILL.md`. The folder name is used as the skill name unless overridden by frontmatter.
+
+---
+
+## Next Steps
+
+- [Client-side Skills](/docs/skills/client) — `SkillProvider`, `useSkill`, `useSkillStatus`
+- [Server-side Skills](/docs/skills/server) — `loadSkills()`, file/URL sources, collision detection
diff --git a/apps/docs/content/docs/skills/meta.json b/apps/docs/content/docs/skills/meta.json
new file mode 100644
index 0000000..0eefaaa
--- /dev/null
+++ b/apps/docs/content/docs/skills/meta.json
@@ -0,0 +1,5 @@
+{
+  "title": "Skills",
+  "icon": "BookOpen",
+  "pages": ["index", "client", "server"]
+}
diff --git a/apps/docs/content/docs/skills/server.mdx b/apps/docs/content/docs/skills/server.mdx
new file mode 100644
index 0000000..e293a85
--- /dev/null
+++ b/apps/docs/content/docs/skills/server.mdx
@@ -0,0 +1,184 @@
+---
+title: Server-side Skills
+description: Load skills from files and URLs on the server with loadSkills()
+icon: Server
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+<Callout type="warn">
+**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+</Callout>
+
+For `file` and `url` skill sources, or when you need server-controlled skill loading, use `loadSkills()` in your API route.
+
+---
+
+## Basic Setup
+
+```typescript
+// app/api/chat/route.ts
+import path from "path";
+import { loadSkills } from "@yourgpt/copilot-sdk/server";
+
+export async function POST(req: Request) {
+  const { messages, __skills } = await req.json();
+
+  const { buildSystemPrompt, tools } = await loadSkills({
+    // Source 1: .md files from a local directory (highest precedence)
+    dir: path.join(process.cwd(), "skills"),
+
+    // Source 2: Remote .md URLs
+    remoteUrls: ["https://cdn.myapp.com/skills/support-policy.md"],
+
+    // Source 3: Inline skills forwarded from client (lowest precedence)
+    clientSkills: __skills ?? [],
+  });
+
+  return streamText({
+    model: anthropic("claude-sonnet-4-6"),
+    system: buildSystemPrompt("You are a helpful assistant for Acme Corp."),
+    messages,
+    tools: {
+      ...tools,         // includes load_skill automatically
+      ...myOtherTools,
+    },
+  }).toDataStreamResponse();
+}
+```
+
+---
+
+## loadSkills Options
+
+```typescript
+interface LoadSkillsOptions {
+  dir?: string;                     // Path to /skills directory (Node.js only)
+  remoteUrls?: string[];            // Remote .md URLs to fetch
+  clientSkills?: ClientInlineSkill[]; // Forwarded from useSkill() hooks
+}
+```
+
+## loadSkills Result
+
+```typescript
+interface LoadSkillsResult {
+  skills: ResolvedSkill[];
+  diagnostics: SkillDiagnostic[];
+
+  // Build system prompt: prepends eager content, appends auto catalog
+  buildSystemPrompt(basePrompt?: string): string;
+
+  // Ready-to-use load_skill tool definition
+  tools: {
+    load_skill: ToolDefinition;
+  };
+}
+```
+
+---
+
+## Forwarding Client Skills
+
+`<SkillProvider>` automatically syncs inline skills to `CopilotProvider`, which includes them in every API request as `__skills`. Read them in your route:
+
+```typescript
+const { messages, __skills } = await req.json();
+
+const { buildSystemPrompt, tools } = await loadSkills({
+  dir: path.join(process.cwd(), "skills"),
+  clientSkills: __skills ?? [],
+});
+```
+
+---
+
+## Source Precedence & Collision Detection
+
+When the same skill name appears in multiple sources, the higher-precedence source wins:
+
+```
+server-dir  >  remote-url  >  client-inline
+```
+
+```typescript
+const { diagnostics } = await loadSkills({ ... });
+
+// [{
+//   type: "collision",
+//   name: "code-review",
+//   winner: "server-dir",
+//   loser: "client-inline",
+// }]
+if (diagnostics.length) {
+  console.warn("Skill collisions:", diagnostics);
+}
+```
+
+This lets you safely override client-provided skills with authoritative server versions.
+
+---
+
+## Full Example
+
+### Project structure
+
+```
+skills/
+├── brand-voice.md     # eager — always active
+└── sql-expert.md      # auto — loaded on demand
+```
+
+### API route
+
+```typescript
+// app/api/chat/route.ts
+import path from "path";
+import { loadSkills } from "@yourgpt/copilot-sdk/server";
+import { streamText } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export async function POST(req: Request) {
+  const { messages, __skills } = await req.json();
+
+  const { buildSystemPrompt, tools } = await loadSkills({
+    dir: path.join(process.cwd(), "skills"),
+    clientSkills: __skills ?? [],
+  });
+
+  return streamText({
+    model: anthropic("claude-sonnet-4-6"),
+    system: buildSystemPrompt("You are a helpful assistant for Acme Corp."),
+    messages,
+    tools,
+  }).toDataStreamResponse();
+}
+```
+
+---
+
+## Type Reference
+
+```typescript
+type SkillStrategy = "eager" | "auto" | "manual";
+
+type SkillSource =
+  | { type: "inline"; content: string }
+  | { type: "url"; url: string }
+  | { type: "file"; path: string };
+
+interface ResolvedSkill {
+  name: string;
+  description: string;
+  content: string;
+  strategy?: SkillStrategy;
+  version?: string;
+}
+
+interface SkillDiagnostic {
+  type: "collision";
+  name: string;
+  winner: "server-dir" | "remote-url" | "client-inline";
+  loser: "server-dir" | "remote-url" | "client-inline";
+}
+```
diff --git a/apps/docs/content/docs/tools/meta.json b/apps/docs/content/docs/tools/meta.json
index fca3c21..6d2dca9 100644
--- a/apps/docs/content/docs/tools/meta.json
+++ b/apps/docs/content/docs/tools/meta.json
@@ -6,7 +6,7 @@
     "frontend-tools",
     "backend-tools",
     "agentic-loop",
-    { "type": "page", "name": "deferred-tools", "badge": "Beta" },
-    { "type": "page", "name": "hidden-tools", "badge": "Beta" }
+    "deferred-tools",
+    "hidden-tools"
   ]
 }

From 77c5e65cd403fbb2d12edc245a420479840f3057 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Fri, 20 Mar 2026 10:59:00 +0530
Subject: [PATCH 28/72] feat(skills): add SkillProvider and context for dynamic
 skill management

- Introduced a new SkillProvider component to manage skills dynamically.
- Implemented context for registering, unregistering, and retrieving skills.
- Added eager and auto skill strategies for on-demand instruction sets.
- Updated .gitignore to include the new yourgpt-server-demo example.
- Modified .env.example to include a new line for configuration.
---
 .gitignore                                    |   1 +
 examples/express-demo/.env.example            |   1 +
 .../copilot-sdk/src/react/skills/index.tsx    | 274 ++++++++++++++++++
 3 files changed, 276 insertions(+)
 create mode 100644 packages/copilot-sdk/src/react/skills/index.tsx

diff --git a/.gitignore b/.gitignore
index 1ff08c7..282c651 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,4 +55,5 @@ examples/*/skills/
 
 # Private projects (not part of SDK)
 examples/yourgpt-chatbot/
+examples/yourgpt-server-demo/
 research/
diff --git a/examples/express-demo/.env.example b/examples/express-demo/.env.example
index a3947e3..f0007e4 100644
--- a/examples/express-demo/.env.example
+++ b/examples/express-demo/.env.example
@@ -3,3 +3,4 @@ ANTHROPIC_API_KEY=sk-ant-your-key-here
 OPENAI_API_KEY=sk-your-key-here
 
 PORT=3001
+
diff --git a/packages/copilot-sdk/src/react/skills/index.tsx b/packages/copilot-sdk/src/react/skills/index.tsx
new file mode 100644
index 0000000..3034b6d
--- /dev/null
+++ b/packages/copilot-sdk/src/react/skills/index.tsx
@@ -0,0 +1,274 @@
+"use client";
+
+/**
+ * Skills System
+ *
+ * Skills are on-demand instruction sets that the AI can load at runtime.
+ * - "eager" skills inject their content immediately into AI context
+ * - "auto" skills appear in a catalog; AI calls load_skill() to fetch content
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useRef,
+  useCallback,
+  useEffect,
+} from "react";
+import { useCopilot } from "../provider/CopilotProvider";
+import { logOnce } from "../../core/utils/logger";
+import { useAIContext } from "../hooks/useAIContext";
+import { useTool } from "../hooks/useTool";
+
+// ============================================================
+// Types
+// ============================================================
+
+export interface SkillSource {
+  type: "inline";
+  content: string;
+}
+
+export type SkillStrategy = "eager" | "auto";
+
+export interface SkillDefinition {
+  name: string;
+  description: string;
+  strategy: SkillStrategy;
+  source: SkillSource;
+}
+
+// ============================================================
+// defineSkill — pure factory
+// ============================================================
+
+export function defineSkill(config: SkillDefinition): SkillDefinition {
+  return config;
+}
+
+// ============================================================
+// SkillContext — shared registry inside SkillProvider
+// ============================================================
+
+interface SkillRegistryEntry {
+  skill: SkillDefinition;
+  /** reference count — multiple useSkill calls for same skill */
+  count: number;
+}
+
+interface SkillContextValue {
+  registerSkill: (skill: SkillDefinition) => void;
+  unregisterSkill: (name: string) => void;
+  getSkill: (name: string) => SkillDefinition | undefined;
+}
+
+const SkillContext = createContext<SkillContextValue | null>(null);
+
+function useSkillContext(): SkillContextValue {
+  const ctx = useContext(SkillContext);
+  if (!ctx) throw new Error("useSkill must be used within SkillProvider");
+  return ctx;
+}
+
+// ============================================================
+// SkillContextInjector — injects skill content into AI context
+// (one per skill, rendered inside SkillProvider)
+// ============================================================
+
+function EagerSkillInjector({ skill }: { skill: SkillDefinition }) {
+  useAIContext({
+    key: `__skill_eager__:${skill.name}`,
+    data: skill.source.content,
+    description: `Skill [${skill.name}]`,
+  });
+  return null;
+}
+
+// ============================================================
+// LoadSkillTool — registers the load_skill tool when there are
+// any "auto" skills in the registry
+// ============================================================
+
+function LoadSkillTool({
+  registryRef,
+  registryVersion,
+}: {
+  registryRef: React.MutableRefObject<Map<string, SkillRegistryEntry>>;
+  registryVersion: number;
+}) {
+  const { addContext, removeContext } = useCopilot();
+  const catalogContextIdRef = useRef<string | null>(null);
+
+  // Build catalog string from current auto skills
+  const buildCatalog = useCallback((): string => {
+    const autoSkills = Array.from(registryRef.current.values())
+      .map((e) => e.skill)
+      .filter((s) => s.strategy === "auto");
+    if (autoSkills.length === 0) return "";
+    const lines = autoSkills
+      .map((s) => `- ${s.name}: ${s.description}`)
+      .join("\n");
+    return `You have access to specialized skills. Call load_skill with the skill name to load instructions.\nAvailable skills:\n${lines}`;
+  }, [registryRef]);
+
+  // Refresh catalog context whenever registry changes
+  const refreshCatalog = useCallback(() => {
+    if (catalogContextIdRef.current) {
+      removeContext(catalogContextIdRef.current);
+      catalogContextIdRef.current = null;
+    }
+    const catalog = buildCatalog();
+    if (catalog) {
+      catalogContextIdRef.current = addContext(catalog);
+    }
+  }, [addContext, removeContext, buildCatalog]);
+
+  // Re-run whenever registry changes (registryVersion increments on register/unregister)
+  useEffect(() => {
+    refreshCatalog();
+    return () => {
+      if (catalogContextIdRef.current) {
+        removeContext(catalogContextIdRef.current);
+        catalogContextIdRef.current = null;
+      }
+    };
+  }, [registryVersion, refreshCatalog, removeContext]);
+
+  // Register load_skill tool
+  useTool({
+    name: "load_skill",
+    description:
+      "Load specialized instructions for a task. Call this when you need detailed guidance on a specific domain.",
+    hidden: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Name of the skill to load",
+        },
+      },
+      required: ["name"],
+    },
+    handler: async ({ name }: { name: string }) => {
+      const registryKeys = Array.from(registryRef.current.keys());
+      logOnce("skills", true, `load_skill called: ${name}`, {
+        registry: registryKeys,
+      });
+      const entry = registryRef.current.get(name);
+      if (!entry) {
+        const available = registryKeys.join(", ");
+        logOnce("skills", true, `load_skill NOT FOUND: ${name}`, {
+          size: registryRef.current.size,
+          keys: registryKeys,
+        });
+        return {
+          success: false,
+          error: `Skill "${name}" not found. Available: ${available || "none"}`,
+        };
+      }
+      return {
+        success: true,
+        name: entry.skill.name,
+        description: entry.skill.description,
+        result: entry.skill.source.content,
+      };
+    },
+  });
+
+  return null;
+}
+
+// ============================================================
+// SkillProvider
+// ============================================================
+
+export interface SkillProviderProps {
+  children: React.ReactNode;
+  /** Skills to register at mount (typically eager ones) */
+  skills?: SkillDefinition[];
+}
+
+export function SkillProvider({ children, skills = [] }: SkillProviderProps) {
+  const registryRef = useRef<Map<string, SkillRegistryEntry>>(new Map());
+  const [registryVersion, setRegistryVersion] = React.useState(0);
+  const rerender = useCallback(() => setRegistryVersion((n) => n + 1), []);
+
+  const registerSkill = useCallback(
+    (skill: SkillDefinition) => {
+      const existing = registryRef.current.get(skill.name);
+      if (existing) {
+        existing.count += 1;
+      } else {
+        registryRef.current.set(skill.name, { skill, count: 1 });
+        rerender();
+      }
+    },
+    [rerender],
+  );
+
+  const unregisterSkill = useCallback(
+    (name: string) => {
+      const existing = registryRef.current.get(name);
+      if (!existing) return;
+      existing.count -= 1;
+      if (existing.count <= 0) {
+        registryRef.current.delete(name);
+        rerender();
+      }
+    },
+    [rerender],
+  );
+
+  const getSkill = useCallback((name: string) => {
+    return registryRef.current.get(name)?.skill;
+  }, []);
+
+  // Register initial skills on mount
+  useEffect(() => {
+    for (const skill of skills) {
+      registerSkill(skill);
+    }
+    return () => {
+      for (const skill of skills) {
+        unregisterSkill(skill.name);
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Collect current registry snapshot for rendering
+  const entries = Array.from(registryRef.current.values());
+  const eagerSkills = entries.filter((e) => e.skill.strategy === "eager");
+
+  return (
+    <SkillContext.Provider value={{ registerSkill, unregisterSkill, getSkill }}>
+      {/* Inject eager skill content into AI context */}
+      {eagerSkills.map((e) => (
+        <EagerSkillInjector key={e.skill.name} skill={e.skill} />
+      ))}
+      {/* Register load_skill tool + catalog context */}
+      <LoadSkillTool
+        registryRef={registryRef}
+        registryVersion={registryVersion}
+      />
+      {children}
+    </SkillContext.Provider>
+  );
+}
+
+// ============================================================
+// useSkill — register a skill on mount, unregister on unmount
+// ============================================================
+
+export function useSkill(skill: SkillDefinition): void {
+  const { registerSkill, unregisterSkill } = useSkillContext();
+
+  useEffect(() => {
+    registerSkill(skill);
+    return () => {
+      unregisterSkill(skill.name);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [skill.name]);
+}

From e472ebf5ff9c9715cfc0305b6bd993e727a69308 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 21 Mar 2026 15:47:25 +0530
Subject: [PATCH 29/72] feat(generative-ui): add generative UI demo with chart
 and card rendering

- Introduced a new generative UI demo that allows rendering of various UI components including charts, tables, stats, and cards.
- Implemented a new API route for handling generative UI requests, supporting dynamic rendering based on user input.
- Added a ChartRenderer component for visualizing data using Recharts.
- Created a CardRenderer for displaying key-value pairs and call-to-action links.
- Updated the main page to include a user-friendly interface for interacting with the generative UI features.
- Enhanced the SDK with experimental types and schemas for better integration and validation.
- Bumped version to reflect the addition of these features.
---
 .../app/api/chat/generative-ui/route.ts       |  84 +++++
 .../app/generative-ui/chart-renderer.tsx      | 184 ++++++++++
 .../experimental/app/generative-ui/page.tsx   | 232 ++++++++++++
 examples/experimental/app/page.tsx            |   5 +
 packages/copilot-sdk/package.json             |   5 +
 packages/copilot-sdk/src/core/types/tools.ts  |  10 +-
 .../src/core/utils/zod-to-json-schema.ts      |  48 ++-
 .../src/experimental/generativeUITool.ts      | 156 +++++++++
 .../copilot-sdk/src/experimental/index.ts     |  54 +++
 .../experimental/renderers/CardRenderer.tsx   |  72 ++++
 .../experimental/renderers/HtmlRenderer.tsx   |  70 ++++
 .../experimental/renderers/StatRenderer.tsx   |  65 ++++
 .../experimental/renderers/TableRenderer.tsx  |  86 +++++
 .../copilot-sdk/src/experimental/types.ts     | 175 ++++++++++
 .../src/experimental/useGenerativeUI.tsx      | 330 ++++++++++++++++++
 packages/copilot-sdk/tsup.config.ts           |   3 +
 16 files changed, 1573 insertions(+), 6 deletions(-)
 create mode 100644 examples/experimental/app/api/chat/generative-ui/route.ts
 create mode 100644 examples/experimental/app/generative-ui/chart-renderer.tsx
 create mode 100644 examples/experimental/app/generative-ui/page.tsx
 create mode 100644 packages/copilot-sdk/src/experimental/generativeUITool.ts
 create mode 100644 packages/copilot-sdk/src/experimental/index.ts
 create mode 100644 packages/copilot-sdk/src/experimental/renderers/CardRenderer.tsx
 create mode 100644 packages/copilot-sdk/src/experimental/renderers/HtmlRenderer.tsx
 create mode 100644 packages/copilot-sdk/src/experimental/renderers/StatRenderer.tsx
 create mode 100644 packages/copilot-sdk/src/experimental/renderers/TableRenderer.tsx
 create mode 100644 packages/copilot-sdk/src/experimental/types.ts
 create mode 100644 packages/copilot-sdk/src/experimental/useGenerativeUI.tsx

diff --git a/examples/experimental/app/api/chat/generative-ui/route.ts b/examples/experimental/app/api/chat/generative-ui/route.ts
new file mode 100644
index 0000000..61da603
--- /dev/null
+++ b/examples/experimental/app/api/chat/generative-ui/route.ts
@@ -0,0 +1,84 @@
+import { createRuntime } from "@yourgpt/llm-sdk";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
+import { createOpenAI } from "@yourgpt/llm-sdk/openai";
+
+function resolveProvider() {
+  if (process.env.ANTHROPIC_API_KEY) {
+    return {
+      provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+      model: "claude-haiku-4-5",
+      providerName: "Anthropic",
+    };
+  }
+  if (process.env.OPENAI_API_KEY) {
+    return {
+      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+      model: "gpt-4o-mini",
+      providerName: "OpenAI",
+    };
+  }
+  throw new Error(
+    "Set ANTHROPIC_API_KEY or OPENAI_API_KEY to run the generative UI demo.",
+  );
+}
+
+const { provider, model, providerName } = resolveProvider();
+
+const runtime = createRuntime({
+  provider,
+  model,
+  systemPrompt: `You are a data-rich assistant that always renders visual UI components instead of plain text.
+
+You have a render_ui tool. Use it proactively based on the request:
+
+- "table" — any list of items, comparisons, records
+- "stat"  — numbers, KPIs, metrics with deltas
+- "card"  — single entity details (person, product, place)
+- "chart" — trends and distributions (bar, line, pie, area, scatter)
+- "html"  — rich, fully custom layouts (see below)
+
+━━━ HTML TYPE CAPABILITIES ━━━
+The html iframe has TWO libraries pre-loaded:
+1. Tailwind CSS (Play CDN) — use any utility class freely
+2. Chart.js — create inline charts with <canvas> + new Chart(...)
+
+Design in a shadcn/ui style:
+- Cards:    bg-white rounded-xl border border-gray-200 shadow-sm p-6
+- Headings: text-gray-900 font-semibold text-lg
+- Muted:    text-gray-500 text-sm
+- Badges:   bg-blue-50 text-blue-700 px-2.5 py-0.5 rounded-full text-xs font-medium
+- Buttons:  bg-gray-900 text-white rounded-lg px-4 py-2 text-sm font-medium hover:bg-gray-700
+- Grid:     grid grid-cols-3 gap-4 (or 2-col for cards)
+- Dividers: border-t border-gray-100 mt-4 pt-4
+
+Chart.js usage in html — inline script after canvas:
+<canvas id="c" height="220"></canvas>
+<script>
+new Chart(document.getElementById('c'), {
+  type: 'bar', // bar | line | pie | doughnut | radar | polarArea
+  data: {
+    labels: ['Jan','Feb','Mar'],
+    datasets: [{ label: 'Revenue', data: [120,190,170], backgroundColor: '#6366f1' }]
+  },
+  options: { responsive: true, plugins: { legend: { position: 'top' } } }
+});
+</script>
+
+Use html when asked for dashboards, interactive layouts, shadcn-style components, or anything combining charts + stats + cards in one view.
+For html, set the "height" field to fit the content — e.g. "600px" for dashboards, "320px" for a small card.
+Always prefer a structured type (table, stat, card) over html when the data fits a single type.`,
+  maxIterations: 3,
+});
+
+export async function POST(request: Request) {
+  return runtime.handleRequest(request);
+}
+
+export async function GET() {
+  return Response.json({
+    status: "ok",
+    provider: providerName,
+    model,
+    demo: "generative-ui",
+  });
+}
diff --git a/examples/experimental/app/generative-ui/chart-renderer.tsx b/examples/experimental/app/generative-ui/chart-renderer.tsx
new file mode 100644
index 0000000..0da026d
--- /dev/null
+++ b/examples/experimental/app/generative-ui/chart-renderer.tsx
@@ -0,0 +1,184 @@
+"use client";
+
+import {
+  BarChart,
+  Bar,
+  LineChart,
+  Line,
+  PieChart,
+  Pie,
+  Cell,
+  AreaChart,
+  Area,
+  ScatterChart,
+  Scatter,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+} from "recharts";
+import type { ChartRendererProps } from "@yourgpt/copilot-sdk/experimental";
+
+const COLORS = [
+  "hsl(var(--chart-1, 221 83% 53%))",
+  "hsl(var(--chart-2, 161 94% 30%))",
+  "hsl(var(--chart-3, 45 93% 47%))",
+  "hsl(var(--chart-4, 142 71% 45%))",
+  "hsl(var(--chart-5, 280 68% 60%))",
+];
+
+// Reshape datasets + labels → recharts data format
+function toRechartsData(
+  labels: string[],
+  datasets: { label: string; data: number[] }[],
+) {
+  return labels.map((label, i) => {
+    const point: Record<string, string | number> = { name: label };
+    for (const ds of datasets) {
+      point[ds.label] = ds.data[i] ?? 0;
+    }
+    return point;
+  });
+}
+
+export function ChartRenderer({ payload }: ChartRendererProps) {
+  const { chartType, labels, datasets, title, xLabel, yLabel } = payload;
+  const data = toRechartsData(labels, datasets);
+  const dataKeys = datasets.map((ds) => ds.label);
+
+  return (
+    <div className="rounded-lg border border-border bg-card p-4">
+      {title && (
+        <p className="mb-3 text-sm font-semibold text-foreground">{title}</p>
+      )}
+      <ResponsiveContainer width="100%" height={220}>
+        {chartType === "pie" ? (
+          <PieChart>
+            <Pie
+              data={data.map((d, i) => ({
+                name: d.name,
+                value: Number(d[dataKeys[0]] ?? 0),
+              }))}
+              dataKey="value"
+              nameKey="name"
+              cx="50%"
+              cy="50%"
+              outerRadius={80}
+              label={({ name, percent }) =>
+                `${name} ${(percent * 100).toFixed(0)}%`
+              }
+            >
+              {data.map((_, i) => (
+                <Cell key={i} fill={COLORS[i % COLORS.length]} />
+              ))}
+            </Pie>
+            <Tooltip />
+            <Legend />
+          </PieChart>
+        ) : chartType === "line" ? (
+          <LineChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" className="stroke-border" />
+            <XAxis
+              dataKey="name"
+              tick={{ fontSize: 11 }}
+              label={
+                xLabel
+                  ? { value: xLabel, position: "insideBottom", offset: -5 }
+                  : undefined
+              }
+            />
+            <YAxis
+              tick={{ fontSize: 11 }}
+              label={
+                yLabel
+                  ? { value: yLabel, angle: -90, position: "insideLeft" }
+                  : undefined
+              }
+            />
+            <Tooltip />
+            {dataKeys.length > 1 && <Legend />}
+            {dataKeys.map((key, i) => (
+              <Line
+                key={key}
+                type="monotone"
+                dataKey={key}
+                stroke={COLORS[i % COLORS.length]}
+                strokeWidth={2}
+                dot={false}
+              />
+            ))}
+          </LineChart>
+        ) : chartType === "area" ? (
+          <AreaChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" className="stroke-border" />
+            <XAxis dataKey="name" tick={{ fontSize: 11 }} />
+            <YAxis tick={{ fontSize: 11 }} />
+            <Tooltip />
+            {dataKeys.length > 1 && <Legend />}
+            {dataKeys.map((key, i) => (
+              <Area
+                key={key}
+                type="monotone"
+                dataKey={key}
+                stroke={COLORS[i % COLORS.length]}
+                fill={COLORS[i % COLORS.length]}
+                fillOpacity={0.15}
+                strokeWidth={2}
+              />
+            ))}
+          </AreaChart>
+        ) : chartType === "scatter" ? (
+          <ScatterChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" className="stroke-border" />
+            <XAxis
+              dataKey={dataKeys[0]}
+              tick={{ fontSize: 11 }}
+              name={dataKeys[0]}
+            />
+            <YAxis
+              dataKey={dataKeys[1] ?? dataKeys[0]}
+              tick={{ fontSize: 11 }}
+              name={dataKeys[1] ?? dataKeys[0]}
+            />
+            <Tooltip cursor={{ strokeDasharray: "3 3" }} />
+            <Scatter data={data} fill={COLORS[0]} />
+          </ScatterChart>
+        ) : (
+          // Default: bar
+          <BarChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" className="stroke-border" />
+            <XAxis
+              dataKey="name"
+              tick={{ fontSize: 11 }}
+              label={
+                xLabel
+                  ? { value: xLabel, position: "insideBottom", offset: -5 }
+                  : undefined
+              }
+            />
+            <YAxis
+              tick={{ fontSize: 11 }}
+              label={
+                yLabel
+                  ? { value: yLabel, angle: -90, position: "insideLeft" }
+                  : undefined
+              }
+            />
+            <Tooltip />
+            {dataKeys.length > 1 && <Legend />}
+            {dataKeys.map((key, i) => (
+              <Bar
+                key={key}
+                dataKey={key}
+                fill={COLORS[i % COLORS.length]}
+                radius={[3, 3, 0, 0]}
+              />
+            ))}
+          </BarChart>
+        )}
+      </ResponsiveContainer>
+    </div>
+  );
+}
diff --git a/examples/experimental/app/generative-ui/page.tsx b/examples/experimental/app/generative-ui/page.tsx
new file mode 100644
index 0000000..60eedd3
--- /dev/null
+++ b/examples/experimental/app/generative-ui/page.tsx
@@ -0,0 +1,232 @@
+"use client";
+
+import { CopilotProvider } from "@yourgpt/copilot-sdk/react";
+import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
+import { useGenerativeUI } from "@yourgpt/copilot-sdk/experimental";
+import { ChartRenderer } from "./chart-renderer";
+import Link from "next/link";
+import "@yourgpt/copilot-sdk/ui/styles.css";
+
+const PROMPT_SUGGESTIONS = [
+  "Build a shadcn-style analytics dashboard with a Chart.js bar chart of monthly revenue and 3 KPI stat cards",
+  "Show a shadcn card grid of the top 5 programming languages with usage %, trend badge, and color",
+  "Render a Chart.js doughnut chart of browser market share with a legend",
+  "Give me a stat dashboard of key web metrics",
+  "Show me a table of the top 10 S&P 500 companies by market cap",
+  "Create a card for Elon Musk with key facts",
+  "Build a shadcn pricing page with 3 tiers, feature lists, and a highlighted popular plan",
+  "Show a line chart of BTC price over the last 6 months",
+  "Render a Chart.js radar chart comparing React, Vue, Angular, and Svelte across 5 metrics",
+];
+
+function GenerativeUIChatInner() {
+  useGenerativeUI({
+    name: "render_ui",
+    chartRenderer: ChartRenderer,
+  });
+
+  return (
+    <CopilotChat
+      className="h-full"
+      placeholder="Ask for data, stats, charts, cards…"
+      showHeader
+      header={{ name: "Generative UI" }}
+      loaderVariant="wave"
+      showUserAvatar
+    />
+  );
+}
+
+export default function GenerativeUIPage() {
+  return (
+    <>
+      <style>{`
+        .gui-root {
+          background-color: #080b12;
+          background-image:
+            radial-gradient(ellipse 80% 50% at 10% -10%, rgba(16,185,129,0.08) 0%, transparent 55%),
+            radial-gradient(ellipse 70% 45% at 90% 110%, rgba(59,130,246,0.07) 0%, transparent 55%);
+          font-family: system-ui, -apple-system, sans-serif;
+        }
+        .gui-accent-line {
+          height: 3px;
+          background: linear-gradient(90deg,
+            transparent 0%,
+            rgba(16,185,129,0.35) 20%,
+            rgba(52,211,153,0.65) 50%,
+            rgba(59,130,246,0.4) 80%,
+            transparent 100%);
+          flex-shrink: 0;
+        }
+        .gui-header {
+          background: rgba(8,11,18,0.85);
+          backdrop-filter: blur(16px);
+          border-bottom: 1px solid rgba(255,255,255,0.055);
+          flex-shrink: 0;
+        }
+        .gui-back {
+          display: flex;
+          align-items: center;
+          gap: 5px;
+          color: #475569;
+          font-size: 12px;
+          text-decoration: none;
+          transition: color 0.15s;
+        }
+        .gui-back:hover { color: #94a3b8; }
+        .gui-divider {
+          width: 1px;
+          height: 16px;
+          background: rgba(255,255,255,0.08);
+          flex-shrink: 0;
+        }
+        .gui-badge {
+          font-size: 10px;
+          font-weight: 600;
+          padding: 2px 8px;
+          border-radius: 999px;
+          background: rgba(16,185,129,0.1);
+          border: 1px solid rgba(16,185,129,0.25);
+          color: #34d399;
+          letter-spacing: 0.04em;
+          text-transform: uppercase;
+        }
+        .gui-sidebar {
+          width: 256px;
+          flex-shrink: 0;
+          background: rgba(255,255,255,0.015);
+          border-right: 1px solid rgba(255,255,255,0.055);
+          display: flex;
+          flex-direction: column;
+          gap: 0;
+          overflow-y: auto;
+        }
+        .gui-sidebar-title {
+          font-size: 10px;
+          font-weight: 600;
+          letter-spacing: 0.08em;
+          text-transform: uppercase;
+          color: #334155;
+          padding: 16px 16px 8px;
+        }
+        .gui-prompt-btn {
+          width: 100%;
+          text-align: left;
+          padding: 9px 16px;
+          font-size: 12px;
+          color: #64748b;
+          background: transparent;
+          border: none;
+          cursor: pointer;
+          border-bottom: 1px solid rgba(255,255,255,0.03);
+          transition: background 0.1s, color 0.1s;
+          line-height: 1.4;
+        }
+        .gui-prompt-btn:hover {
+          background: rgba(255,255,255,0.03);
+          color: #94a3b8;
+        }
+      `}</style>
+
+      <div className="gui-root h-screen flex flex-col">
+        <div className="gui-accent-line" />
+
+        {/* Header */}
+        <header className="gui-header flex items-center gap-3.5 px-5 py-3">
+          <Link href="/" className="gui-back">
+            <svg
+              width="13"
+              height="13"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <path d="M19 12H5M12 5l-7 7 7 7" />
+            </svg>
+            Back
+          </Link>
+
+          <div className="gui-divider" />
+
+          <div className="flex items-center gap-2.5">
+            <svg
+              width="15"
+              height="15"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="#34d399"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <rect x="3" y="3" width="7" height="7" rx="1" />
+              <rect x="14" y="3" width="7" height="7" rx="1" />
+              <rect x="3" y="14" width="7" height="7" rx="1" />
+              <rect x="14" y="14" width="7" height="7" rx="1" />
+            </svg>
+            <span
+              style={{
+                fontWeight: 700,
+                fontSize: 14,
+                letterSpacing: "-0.02em",
+                color: "#e2e8f0",
+              }}
+            >
+              Generative UI
+            </span>
+          </div>
+
+          <span className="gui-badge ml-1">Experimental</span>
+
+          <div className="ml-auto" style={{ fontSize: 11, color: "#334155" }}>
+            Tables · Stats · Cards · Charts · HTML
+          </div>
+        </header>
+
+        {/* Two-panel layout */}
+        <div className="flex-1 flex min-h-0">
+          <CopilotProvider runtimeUrl="/api/chat/generative-ui">
+            {/* Left: Prompt suggestions */}
+            <div className="gui-sidebar hidden lg:flex flex-col">
+              <p className="gui-sidebar-title">Try asking…</p>
+              {PROMPT_SUGGESTIONS.map((prompt) => (
+                <button
+                  key={prompt}
+                  className="gui-prompt-btn"
+                  onClick={() => {
+                    // Find the CopilotChat input and populate it
+                    const input = document.querySelector<HTMLTextAreaElement>(
+                      "textarea[placeholder]",
+                    );
+                    if (input) {
+                      const nativeInputValueSetter =
+                        Object.getOwnPropertyDescriptor(
+                          window.HTMLTextAreaElement.prototype,
+                          "value",
+                        )?.set;
+                      nativeInputValueSetter?.call(input, prompt);
+                      input.dispatchEvent(
+                        new Event("input", { bubbles: true }),
+                      );
+                      input.focus();
+                    }
+                  }}
+                >
+                  {prompt}
+                </button>
+              ))}
+            </div>
+
+            {/* Right: Chat */}
+            <div className="flex-1 min-w-0">
+              <GenerativeUIChatInner />
+            </div>
+          </CopilotProvider>
+        </div>
+      </div>
+    </>
+  );
+}
diff --git a/examples/experimental/app/page.tsx b/examples/experimental/app/page.tsx
index 0cff1b9..2b988b3 100644
--- a/examples/experimental/app/page.tsx
+++ b/examples/experimental/app/page.tsx
@@ -1,6 +1,11 @@
 import Link from "next/link";
 
 const demos = [
+  {
+    name: "Generative UI",
+    href: "/generative-ui",
+    description: "LLM renders tables, stats, cards, charts & HTML inline",
+  },
   {
     name: "Conversation Branching",
     href: "/branching",
diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index 3ece582..ee35e72 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -83,6 +83,11 @@
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js",
       "require": "./dist/server/index.cjs"
+    },
+    "./experimental": {
+      "types": "./dist/experimental/index.d.ts",
+      "import": "./dist/experimental/index.js",
+      "require": "./dist/experimental/index.cjs"
     }
   },
   "files": [
diff --git a/packages/copilot-sdk/src/core/types/tools.ts b/packages/copilot-sdk/src/core/types/tools.ts
index d6695cf..67d907c 100644
--- a/packages/copilot-sdk/src/core/types/tools.ts
+++ b/packages/copilot-sdk/src/core/types/tools.ts
@@ -41,7 +41,7 @@ export type ToolSource = "mcp" | "native" | "custom";
  * JSON Schema property definition
  */
 export interface JSONSchemaProperty {
-  type:
+  type?:
     | "string"
     | "number"
     | "boolean"
@@ -60,16 +60,20 @@ export interface JSONSchemaProperty {
   minimum?: number;
   maximum?: number;
   pattern?: string;
+  oneOf?: JSONSchemaProperty[];
+  anyOf?: JSONSchemaProperty[];
 }
 
 /**
  * JSON Schema for tool input
  */
 export interface ToolInputSchema {
-  type: "object";
-  properties: Record<string, JSONSchemaProperty>;
+  type?: "object";
+  properties?: Record<string, JSONSchemaProperty>;
   required?: string[];
   additionalProperties?: boolean;
+  oneOf?: JSONSchemaProperty[];
+  anyOf?: JSONSchemaProperty[];
 }
 
 /**
diff --git a/packages/copilot-sdk/src/core/utils/zod-to-json-schema.ts b/packages/copilot-sdk/src/core/utils/zod-to-json-schema.ts
index 01f9ff3..9a64152 100644
--- a/packages/copilot-sdk/src/core/utils/zod-to-json-schema.ts
+++ b/packages/copilot-sdk/src/core/utils/zod-to-json-schema.ts
@@ -203,7 +203,14 @@ function getZodEnumValues(
  */
 export function zodToJsonSchema(schema: unknown): ToolInputSchema {
   const result = _zodToJsonSchemaInternal(schema);
-  // Cast to ToolInputSchema - callers should only pass z.object() schemas for tool inputs
+  // If it's a oneOf/anyOf (discriminated union) without a type, wrap in type:object
+  // so LLMs receive a valid top-level object schema instead of inventing a wrapper property
+  if (!result.type && (result.oneOf || result.anyOf)) {
+    return {
+      type: "object",
+      ...(result.oneOf ? { oneOf: result.oneOf } : { anyOf: result.anyOf }),
+    } as unknown as ToolInputSchema;
+  }
   return result as unknown as ToolInputSchema;
 }
 
@@ -348,8 +355,40 @@ function _zodToJsonSchemaInternal(schema: unknown): JSONSchemaProperty {
       return { type: "string", description };
     }
 
+    case "ZodDiscriminatedUnion": {
+      const obj = schema as Record<string, unknown>;
+      let options: unknown[] | undefined;
+
+      if ("_zod" in obj) {
+        const zod = obj._zod as Record<string, unknown>;
+        const def = zod.def as Record<string, unknown> | undefined;
+        // Zod 4: options may be a Map or array
+        const raw = def?.options;
+        options =
+          raw instanceof Map
+            ? Array.from(raw.values())
+            : (raw as unknown[] | undefined);
+      }
+      if (!options) {
+        const def = obj._def as Record<string, unknown>;
+        const raw = def?.options;
+        options =
+          raw instanceof Map
+            ? Array.from(raw.values())
+            : (raw as unknown[] | undefined);
+      }
+
+      if (options && options.length > 0) {
+        const oneOf = options.map((opt) => _zodToJsonSchemaInternal(opt));
+        const result: JSONSchemaProperty = { oneOf };
+        if (description) result.description = description;
+        return result;
+      }
+      return { type: "object", description };
+    }
+
     case "ZodUnion": {
-      // For unions, we take the first option for simplicity
+      // For unions, generate oneOf with all options
       const obj = schema as Record<string, unknown>;
       let options: unknown[] | undefined;
 
@@ -364,7 +403,10 @@ function _zodToJsonSchemaInternal(schema: unknown): JSONSchemaProperty {
       }
 
       if (options && options.length > 0) {
-        return _zodToJsonSchemaInternal(options[0]);
+        const oneOf = options.map((opt) => _zodToJsonSchemaInternal(opt));
+        const result: JSONSchemaProperty = { oneOf };
+        if (description) result.description = description;
+        return result;
       }
       return { type: "string", description };
     }
diff --git a/packages/copilot-sdk/src/experimental/generativeUITool.ts b/packages/copilot-sdk/src/experimental/generativeUITool.ts
new file mode 100644
index 0000000..6ef7e0b
--- /dev/null
+++ b/packages/copilot-sdk/src/experimental/generativeUITool.ts
@@ -0,0 +1,156 @@
+// Flat JSON schema — GenerativeUIPayloadSchema is used only in the client handler for validation — same structure as RENDER_UI_SCHEMA in useGenerativeUI.
+// Flat object schemas with a discriminator field work reliably across all LLMs.
+export const RENDER_UI_PARAMETERS = {
+  type: "object" as const,
+  properties: {
+    type: {
+      type: "string" as const,
+      enum: ["html", "chart", "table", "stat", "card"],
+      description: "UI component type to render",
+    },
+    html: {
+      type: "string" as const,
+      description: "Raw HTML with Tailwind classes (type=html)",
+    },
+    height: { type: "string" as const },
+    chartType: {
+      type: "string" as const,
+      enum: ["bar", "line", "pie", "area", "scatter"],
+      description: "Chart variant (type=chart)",
+    },
+    labels: {
+      type: "array" as const,
+      items: { type: "string" as const },
+      description: "X-axis category labels (type=chart)",
+    },
+    datasets: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        properties: {
+          label: { type: "string" as const },
+          data: { type: "array" as const, items: { type: "number" as const } },
+        },
+        required: ["label", "data"],
+      },
+      description: "Data series (type=chart)",
+    },
+    xLabel: { type: "string" as const },
+    yLabel: { type: "string" as const },
+    columns: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        properties: {
+          key: { type: "string" as const },
+          label: { type: "string" as const },
+          align: { type: "string" as const },
+        },
+        required: ["key", "label"],
+      },
+      description:
+        "Column definitions — key matches row property names (type=table)",
+    },
+    rows: {
+      type: "array" as const,
+      items: { type: "object" as const },
+      description: "Array of row objects keyed by column.key (type=table)",
+    },
+    caption: { type: "string" as const },
+    stats: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        properties: {
+          label: { type: "string" as const },
+          value: { type: "string" as const },
+          change: { type: "string" as const },
+          changeDirection: {
+            type: "string" as const,
+            enum: ["positive", "negative", "neutral"],
+          },
+          description: { type: "string" as const },
+        },
+        required: ["label", "value"],
+      },
+      description: "KPI stats array (type=stat)",
+    },
+    title: {
+      type: "string" as const,
+      description: "Title shown above the component",
+    },
+    subtitle: { type: "string" as const },
+    body: { type: "string" as const },
+    fields: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        properties: {
+          label: { type: "string" as const },
+          value: { type: "string" as const },
+          badge: { type: "boolean" as const },
+        },
+        required: ["label", "value"],
+      },
+      description: "Key-value fields (type=card)",
+    },
+    cta: {
+      type: "object" as const,
+      properties: {
+        label: { type: "string" as const },
+        url: { type: "string" as const },
+      },
+      required: ["label", "url"],
+      description: "Call-to-action link (type=card)",
+    },
+  },
+  required: ["type"],
+};
+
+export interface GenerativeUIToolConfig {
+  /**
+   * Override the default LLM description.
+   * The default instructs the model when to use each UI type.
+   */
+  description?: string;
+}
+
+/**
+ * Returns a tool definition compatible with `streamText` for use in your backend route.
+ *
+ * Pass the returned object as a value in the `tools` map of `streamText`.
+ * The key you use becomes the tool name — use the same name in `useGenerativeUI({ name })` on the frontend.
+ *
+ * @example
+ * ```ts
+ * import { streamText } from "@yourgpt/llm-sdk";
+ * import { generativeUITool } from "@yourgpt/copilot-sdk/experimental";
+ *
+ * const result = await streamText({
+ *   model: openai("gpt-4o"),
+ *   messages,
+ *   tools: {
+ *     render_ui: generativeUITool(),
+ *     // ...your other tools
+ *   },
+ * });
+ * ```
+ */
+export function generativeUITool(config: GenerativeUIToolConfig = {}) {
+  return {
+    description:
+      config.description ??
+      `Render a rich visual UI component directly in the chat. Use this tool whenever the user's request is best answered with a visual instead of text.
+
+Choose the type based on what fits best:
+- "table": structured rows of data (comparisons, lists, records)
+- "stat": KPI metrics, numbers with labels, dashboards with change deltas
+- "card": entity summaries — profiles, products, results, structured key-value info
+- "chart": graphs and visualizations — bar, line, pie, area, scatter — pass raw data only, not markup
+- "html": anything that requires custom layout, rich formatting, or doesn't fit the above types — use Tailwind CSS classes freely
+
+Always prefer a structured type (table, stat, card) over html when the data fits.
+Only use html as a last resort for truly freeform content.`,
+    parameters: RENDER_UI_PARAMETERS,
+  };
+}
diff --git a/packages/copilot-sdk/src/experimental/index.ts b/packages/copilot-sdk/src/experimental/index.ts
new file mode 100644
index 0000000..9b6dc7e
--- /dev/null
+++ b/packages/copilot-sdk/src/experimental/index.ts
@@ -0,0 +1,54 @@
+/**
+ * @yourgpt/copilot-sdk/experimental
+ *
+ * Experimental generative UI — lets the LLM render typed UI components
+ * (charts, tables, stats, cards, raw HTML) inline in the chat.
+ *
+ * APIs in this module may change without a semver major bump.
+ *
+ * @experimental
+ *
+ * @example
+ * ```tsx
+ * // Backend (route handler)
+ * import { generativeUITool } from "@yourgpt/copilot-sdk/experimental";
+ * tools: { render_ui: generativeUITool() }
+ *
+ * // Frontend
+ * import { useGenerativeUI } from "@yourgpt/copilot-sdk/experimental";
+ * useGenerativeUI({ chartRenderer: MyChartComponent });
+ * ```
+ */
+
+// ── Backend helper ────────────────────────────────────────────────────────────
+export { generativeUITool } from "./generativeUITool";
+export type { GenerativeUIToolConfig } from "./generativeUITool";
+
+// ── Frontend hook ─────────────────────────────────────────────────────────────
+export { useGenerativeUI } from "./useGenerativeUI";
+
+// ── Types & schemas ───────────────────────────────────────────────────────────
+export {
+  GenerativeUIPayloadSchema,
+  HtmlPayloadSchema,
+  ChartPayloadSchema,
+  TablePayloadSchema,
+  StatPayloadSchema,
+  CardPayloadSchema,
+} from "./types";
+export type {
+  GenerativeUIPayload,
+  HtmlPayload,
+  ChartPayload,
+  TablePayload,
+  StatPayload,
+  CardPayload,
+  ChartRendererProps,
+  UseGenerativeUIConfig,
+} from "./types";
+
+// ── Individual renderers (for override / advanced usage) ──────────────────────
+export { HtmlRenderer } from "./renderers/HtmlRenderer";
+export { TableRenderer } from "./renderers/TableRenderer";
+export { StatRenderer } from "./renderers/StatRenderer";
+export { CardRenderer } from "./renderers/CardRenderer";
diff --git a/packages/copilot-sdk/src/experimental/renderers/CardRenderer.tsx b/packages/copilot-sdk/src/experimental/renderers/CardRenderer.tsx
new file mode 100644
index 0000000..94b200e
--- /dev/null
+++ b/packages/copilot-sdk/src/experimental/renderers/CardRenderer.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../../ui/lib/utils";
+import type { CardPayload } from "../types";
+
+interface CardRendererProps {
+  payload: CardPayload;
+  className?: string;
+}
+
+export function CardRenderer({ payload, className }: CardRendererProps) {
+  const { title, subtitle, fields, body, cta } = payload;
+
+  return (
+    <div
+      className={cn(
+        "csdk-genui-card flex flex-col gap-3 rounded-lg border border-border bg-card p-4",
+        className,
+      )}
+    >
+      {/* Header */}
+      <div>
+        <p className="text-sm font-semibold leading-snug text-foreground">
+          {title}
+        </p>
+        {subtitle && (
+          <p className="mt-0.5 text-xs text-muted-foreground">{subtitle}</p>
+        )}
+      </div>
+
+      {/* Key-value fields */}
+      {fields && fields.length > 0 && (
+        <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1.5">
+          {fields.map((field, i) => (
+            <React.Fragment key={i}>
+              <dt className="self-center whitespace-nowrap text-xs text-muted-foreground">
+                {field.label}
+              </dt>
+              <dd className="text-xs text-foreground">
+                {field.badge ? (
+                  <span className="inline-flex items-center rounded-full border border-border bg-muted px-2 py-0.5 font-medium text-foreground">
+                    {String(field.value)}
+                  </span>
+                ) : (
+                  String(field.value)
+                )}
+              </dd>
+            </React.Fragment>
+          ))}
+        </dl>
+      )}
+
+      {/* Body */}
+      {body && (
+        <p className="text-xs leading-relaxed text-muted-foreground">{body}</p>
+      )}
+
+      {/* CTA */}
+      {cta && (
+        <a
+          href={cta.url}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="mt-1 inline-flex items-center gap-1 text-xs font-medium text-primary underline-offset-2 hover:underline"
+        >
+          {cta.label} ↗
+        </a>
+      )}
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/src/experimental/renderers/HtmlRenderer.tsx b/packages/copilot-sdk/src/experimental/renderers/HtmlRenderer.tsx
new file mode 100644
index 0000000..9a8584a
--- /dev/null
+++ b/packages/copilot-sdk/src/experimental/renderers/HtmlRenderer.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../../ui/lib/utils";
+import type { HtmlPayload } from "../types";
+
+interface HtmlRendererProps {
+  payload: HtmlPayload;
+  className?: string;
+}
+
+/**
+ * Strip only external script src= tags (e.g. duplicate CDN loads the AI might add).
+ * Inline <script> blocks are kept — they're needed for Chart.js initialization
+ * and are safe inside the sandboxed iframe.
+ * Inline event handlers (onclick=, onerror=) are stripped as defense-in-depth.
+ */
+function sanitizeHtml(html: string): string {
+  return html
+    .replace(/<script\b[^>]*\bsrc=["'][^"']*["'][^>]*><\/script>/gi, "")
+    .replace(/\s*on\w+="[^"]*"/gi, "")
+    .replace(/\s*on\w+='[^']*'/gi, "");
+}
+
+/**
+ * Renders AI-generated HTML inside an isolated iframe.
+ * Tailwind CSS is loaded via CDN — iframes provide a full document context
+ * so the Tailwind Play CDN can scan and style classes correctly.
+ */
+export function HtmlRenderer({ payload, className }: HtmlRendererProps) {
+  const clean = sanitizeHtml(payload.html);
+
+  const srcdoc = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <script src="https://cdn.tailwindcss.com"><\/script>
+  <script src="https://cdn.jsdelivr.net/npm/chart.js"><\/script>
+  <style>
+    body { margin: 0; padding: 4px; font-family: ui-sans-serif, system-ui, sans-serif; }
+    * { box-sizing: border-box; }
+  </style>
+</head>
+<body>${clean}</body>
+</html>`;
+
+  return (
+    <div
+      className={cn("csdk-genui-html", className)}
+      style={{ width: "min(700px, calc(100vw - 320px))", minWidth: "320px" }}
+    >
+      {payload.title && (
+        <p className="mb-1.5 text-xs font-medium text-muted-foreground">
+          {payload.title}
+        </p>
+      )}
+      <iframe
+        srcDoc={srcdoc}
+        sandbox="allow-scripts"
+        style={{
+          height: payload.height ?? "520px",
+          minHeight: "120px",
+          width: "100%",
+        }}
+        className="rounded-md border border-border bg-white"
+        title={payload.title ?? "Rendered HTML"}
+      />
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/src/experimental/renderers/StatRenderer.tsx b/packages/copilot-sdk/src/experimental/renderers/StatRenderer.tsx
new file mode 100644
index 0000000..fffd868
--- /dev/null
+++ b/packages/copilot-sdk/src/experimental/renderers/StatRenderer.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../../ui/lib/utils";
+import type { StatPayload } from "../types";
+
+interface StatRendererProps {
+  payload: StatPayload;
+  className?: string;
+}
+
+export function StatRenderer({ payload, className }: StatRendererProps) {
+  const { stats, title } = payload;
+
+  return (
+    <div className={cn("csdk-genui-stat", className)}>
+      {title && (
+        <p className="mb-2 text-sm font-semibold text-foreground">{title}</p>
+      )}
+      <div
+        className={cn(
+          "grid gap-2",
+          stats.length === 1 && "grid-cols-1",
+          stats.length === 2 && "grid-cols-2",
+          stats.length >= 3 && "grid-cols-2 sm:grid-cols-3",
+        )}
+      >
+        {stats.map((stat, i) => (
+          <div
+            key={i}
+            className="flex flex-col gap-0.5 rounded-lg border border-border bg-card p-3"
+          >
+            <span className="truncate text-xs text-muted-foreground">
+              {stat.label}
+            </span>
+            <span className="text-xl font-bold tabular-nums leading-tight text-foreground">
+              {stat.value}
+            </span>
+            {stat.change && (
+              <span
+                className={cn(
+                  "text-xs font-medium",
+                  stat.changeDirection === "positive" &&
+                    "text-green-600 dark:text-green-400",
+                  stat.changeDirection === "negative" &&
+                    "text-red-500 dark:text-red-400",
+                  (!stat.changeDirection ||
+                    stat.changeDirection === "neutral") &&
+                    "text-muted-foreground",
+                )}
+              >
+                {stat.change}
+              </span>
+            )}
+            {stat.description && (
+              <span className="text-xs leading-snug text-muted-foreground">
+                {stat.description}
+              </span>
+            )}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/src/experimental/renderers/TableRenderer.tsx b/packages/copilot-sdk/src/experimental/renderers/TableRenderer.tsx
new file mode 100644
index 0000000..9f81310
--- /dev/null
+++ b/packages/copilot-sdk/src/experimental/renderers/TableRenderer.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../../ui/lib/utils";
+import type { TablePayload } from "../types";
+
+interface TableRendererProps {
+  payload: TablePayload;
+  className?: string;
+}
+
+export function TableRenderer({ payload, className }: TableRendererProps) {
+  const { columns, rows, caption } = payload;
+
+  return (
+    <div
+      className={cn(
+        "csdk-genui-table w-full overflow-x-auto rounded-md border border-border",
+        className,
+      )}
+    >
+      <table className="w-full min-w-full text-sm">
+        {caption && (
+          <caption className="px-3 pt-2 pb-1 text-left text-xs text-muted-foreground">
+            {caption}
+          </caption>
+        )}
+        <thead>
+          <tr className="border-b border-border bg-muted/40">
+            {columns.map((col) => (
+              <th
+                key={col.key}
+                className={cn(
+                  "whitespace-nowrap px-3 py-2 font-medium text-foreground",
+                  col.align === "right" && "text-right",
+                  col.align === "center" && "text-center",
+                  (!col.align || col.align === "left") && "text-left",
+                )}
+              >
+                {col.label}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.length === 0 ? (
+            <tr>
+              <td
+                colSpan={columns.length}
+                className="px-3 py-4 text-center text-sm text-muted-foreground"
+              >
+                No data
+              </td>
+            </tr>
+          ) : (
+            rows.map((row, i) => (
+              <tr
+                key={i}
+                className={cn(
+                  "border-b border-border last:border-0",
+                  i % 2 === 1 && "bg-muted/20",
+                )}
+              >
+                {columns.map((col) => (
+                  <td
+                    key={col.key}
+                    className={cn(
+                      "px-3 py-2 text-foreground/90",
+                      col.align === "right" && "text-right tabular-nums",
+                      col.align === "center" && "text-center",
+                      (!col.align || col.align === "left") && "text-left",
+                    )}
+                  >
+                    {row[col.key] === null || row[col.key] === undefined
+                      ? "—"
+                      : String(row[col.key])}
+                  </td>
+                ))}
+              </tr>
+            ))
+          )}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/src/experimental/types.ts b/packages/copilot-sdk/src/experimental/types.ts
new file mode 100644
index 0000000..cdeabd1
--- /dev/null
+++ b/packages/copilot-sdk/src/experimental/types.ts
@@ -0,0 +1,175 @@
+import { z } from "zod";
+import type React from "react";
+
+// ─── Payload Schemas ──────────────────────────────────────────────────────────
+
+export const HtmlPayloadSchema = z
+  .object({
+    type: z.literal("html"),
+    html: z
+      .string()
+      .describe(
+        "Raw HTML string rendered in an isolated Shadow DOM with Tailwind CSS",
+      ),
+    title: z
+      .string()
+      .optional()
+      .describe("Optional label shown above the component"),
+    height: z
+      .string()
+      .optional()
+      .describe("CSS height value e.g. '300px'. Defaults to auto."),
+  })
+  .passthrough();
+
+export const ChartPayloadSchema = z
+  .object({
+    type: z.literal("chart"),
+    chartType: z
+      .enum(["bar", "line", "pie", "area", "scatter"])
+      .describe("Chart visualization type"),
+    title: z.string().optional(),
+    labels: z.array(z.string()).describe("X-axis labels or category names"),
+    datasets: z
+      .array(
+        z.object({
+          label: z.string(),
+          data: z.array(z.number()),
+          color: z
+            .string()
+            .optional()
+            .describe("Hex or CSS color for this series"),
+        }),
+      )
+      .describe("One or more data series"),
+    xLabel: z.string().optional().describe("X-axis label"),
+    yLabel: z.string().optional().describe("Y-axis label"),
+  })
+  .passthrough();
+
+export const TablePayloadSchema = z
+  .object({
+    type: z.literal("table"),
+    title: z.string().optional(),
+    columns: z
+      .array(
+        z
+          .object({
+            key: z.string(),
+            label: z.string(),
+            align: z.enum(["left", "right", "center"]).optional(),
+          })
+          .passthrough(),
+      )
+      .describe("Column definitions — order controls render order"),
+    rows: z
+      .array(z.record(z.string(), z.unknown()))
+      .describe("Row data keyed by column.key"),
+    caption: z.string().optional(),
+  })
+  .passthrough();
+
+export const StatPayloadSchema = z
+  .object({
+    type: z.literal("stat"),
+    title: z.string().optional(),
+    stats: z.array(
+      z
+        .object({
+          label: z.string(),
+          value: z.union([z.string(), z.number()]),
+          change: z.string().optional().describe("e.g. '+12%' or '-3.4%'"),
+          changeDirection: z
+            .enum(["positive", "negative", "neutral"])
+            .optional(),
+          description: z.string().optional().describe("Sub-text below value"),
+        })
+        .passthrough(),
+    ),
+  })
+  .passthrough();
+
+export const CardPayloadSchema = z
+  .object({
+    type: z.literal("card"),
+    title: z.string(),
+    subtitle: z.string().optional(),
+    body: z.string().optional(),
+    fields: z
+      .array(
+        z.object({
+          label: z.string(),
+          value: z.union([z.string(), z.number(), z.boolean()]),
+          badge: z
+            .boolean()
+            .optional()
+            .describe("Render value as a badge pill"),
+        }),
+      )
+      .optional(),
+    cta: z
+      .object({
+        label: z.string().optional(),
+        text: z.string().optional(), // LLMs sometimes use "text" instead of "label"
+        url: z.string().describe("URL for the call-to-action link"),
+      })
+      .transform((c) => ({ ...c, label: c.label ?? c.text ?? "" }))
+      .optional(),
+  })
+  .passthrough();
+
+/** Full discriminated union of all generative UI payload types */
+export const GenerativeUIPayloadSchema = z.discriminatedUnion("type", [
+  HtmlPayloadSchema,
+  ChartPayloadSchema,
+  TablePayloadSchema,
+  StatPayloadSchema,
+  CardPayloadSchema,
+]);
+
+// ─── TypeScript Types ──────────────────────────────────────────────────────────
+
+export type HtmlPayload = z.infer<typeof HtmlPayloadSchema>;
+export type ChartPayload = z.infer<typeof ChartPayloadSchema>;
+export type TablePayload = z.infer<typeof TablePayloadSchema>;
+export type StatPayload = z.infer<typeof StatPayloadSchema>;
+export type CardPayload = z.infer<typeof CardPayloadSchema>;
+export type GenerativeUIPayload = z.infer<typeof GenerativeUIPayloadSchema>;
+
+/** Props passed to user-supplied chart renderer */
+export interface ChartRendererProps {
+  payload: ChartPayload;
+}
+
+/** Config for useGenerativeUI hook */
+export interface UseGenerativeUIConfig {
+  /**
+   * Tool name — must match the key used in generativeUITool() on the server.
+   * @default "render_ui"
+   */
+  name?: string;
+  /**
+   * Renderer for chart payloads. The SDK does not bundle a chart library.
+   * Pass your own Recharts / Chart.js / Victory component here.
+   * If omitted, chart results show a JSON data fallback.
+   *
+   * @example
+   * ```tsx
+   * chartRenderer={({ payload }) => (
+   *   <BarChart data={payload.datasets} xLabels={payload.labels} />
+   * )}
+   * ```
+   */
+  chartRenderer?: React.ComponentType<ChartRendererProps>;
+  /**
+   * Override any built-in renderer per type.
+   * Useful when you want custom styling while keeping the SDK's schema validation.
+   */
+  overrideRenderers?: Partial<{
+    html: React.ComponentType<{ payload: HtmlPayload }>;
+    chart: React.ComponentType<ChartRendererProps>;
+    table: React.ComponentType<{ payload: TablePayload }>;
+    stat: React.ComponentType<{ payload: StatPayload }>;
+    card: React.ComponentType<{ payload: CardPayload }>;
+  }>;
+}
diff --git a/packages/copilot-sdk/src/experimental/useGenerativeUI.tsx b/packages/copilot-sdk/src/experimental/useGenerativeUI.tsx
new file mode 100644
index 0000000..b7a7049
--- /dev/null
+++ b/packages/copilot-sdk/src/experimental/useGenerativeUI.tsx
@@ -0,0 +1,330 @@
+"use client";
+
+import * as React from "react";
+import { useTool } from "../react/hooks/useTool";
+import type { ToolRenderProps } from "../core/types/tools";
+import { DotsLoader } from "../ui/components/ui/loader";
+import { HtmlRenderer } from "./renderers/HtmlRenderer";
+import { TableRenderer } from "./renderers/TableRenderer";
+import { StatRenderer } from "./renderers/StatRenderer";
+import { CardRenderer } from "./renderers/CardRenderer";
+import { GenerativeUIPayloadSchema } from "./types";
+import type {
+  GenerativeUIPayload,
+  ChartPayload,
+  UseGenerativeUIConfig,
+} from "./types";
+
+/**
+ * Flat JSON schema for the render_ui tool.
+ * Using a flat object with a discriminator `type` field works reliably across all LLMs.
+ * The Zod schema (GenerativeUIPayloadSchema) is still used for server-side validation.
+ */
+const RENDER_UI_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    type: {
+      type: "string" as const,
+      enum: ["html", "chart", "table", "stat", "card"],
+      description: "The UI component type to render",
+    },
+    // html
+    html: {
+      type: "string" as const,
+      description: "Raw HTML with Tailwind classes (type=html only)",
+    },
+    height: {
+      type: "string" as const,
+      description: "Optional CSS height (type=html only)",
+    },
+    // chart
+    chartType: {
+      type: "string" as const,
+      enum: ["bar", "line", "pie", "area", "scatter"],
+      description: "Chart variant (type=chart only)",
+    },
+    labels: {
+      type: "array" as const,
+      items: { type: "string" as const },
+      description: "X-axis labels (type=chart only)",
+    },
+    datasets: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        properties: {
+          label: { type: "string" as const },
+          data: { type: "array" as const, items: { type: "number" as const } },
+        },
+        required: ["label", "data"],
+      },
+      description: "Data series array (type=chart only)",
+    },
+    xLabel: { type: "string" as const },
+    yLabel: { type: "string" as const },
+    // table
+    columns: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        properties: {
+          key: { type: "string" as const },
+          label: { type: "string" as const },
+          align: { type: "string" as const, enum: ["left", "right", "center"] },
+        },
+        required: ["key", "label"],
+      },
+      description:
+        "Column definitions — key matches row property names (type=table only)",
+    },
+    rows: {
+      type: "array" as const,
+      items: { type: "object" as const },
+      description: "Row objects keyed by column.key values (type=table only)",
+    },
+    caption: { type: "string" as const },
+    // stat
+    stats: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        properties: {
+          label: { type: "string" as const },
+          value: { type: "string" as const },
+          change: { type: "string" as const },
+          changeDirection: {
+            type: "string" as const,
+            enum: ["positive", "negative", "neutral"],
+          },
+          description: { type: "string" as const },
+        },
+        required: ["label", "value"],
+      },
+      description: "KPI stats array (type=stat only)",
+    },
+    // card
+    title: { type: "string" as const, description: "Card or table title" },
+    subtitle: { type: "string" as const },
+    body: { type: "string" as const },
+    fields: {
+      type: "array" as const,
+      items: {
+        type: "object" as const,
+        properties: {
+          label: { type: "string" as const },
+          value: { type: "string" as const },
+          badge: { type: "boolean" as const },
+        },
+        required: ["label", "value"],
+      },
+      description: "Key-value fields (type=card only)",
+    },
+    cta: {
+      type: "object" as const,
+      properties: {
+        label: { type: "string" as const },
+        url: { type: "string" as const },
+      },
+      required: ["label", "url"],
+      description: "Call-to-action link (type=card only)",
+    },
+  },
+  required: ["type"],
+};
+
+/**
+ * Register the generative UI tool and attach built-in renderers for all payload types.
+ *
+ * Must be called inside a `CopilotProvider`. The `name` must match
+ * the key used for `generativeUITool()` in your backend `streamText` tools map.
+ *
+ * @example
+ * ```tsx
+ * import { useGenerativeUI } from "@yourgpt/copilot-sdk/experimental";
+ *
+ * function App() {
+ *   useGenerativeUI({
+ *     chartRenderer: ({ payload }) => (
+ *       <BarChart labels={payload.labels} datasets={payload.datasets} />
+ *     ),
+ *   });
+ *   return <CopilotChat />;
+ * }
+ * ```
+ *
+ * @experimental This API may change without a semver major bump.
+ */
+export function useGenerativeUI(config: UseGenerativeUIConfig = {}): void {
+  const toolName = config.name ?? "render_ui";
+
+  // Keep config in a ref so the render function always has the latest without
+  // triggering useTool re-registration on every render
+  const configRef = React.useRef(config);
+  configRef.current = config;
+
+  useTool<GenerativeUIPayload>({
+    name: toolName,
+    description:
+      "Renders a rich UI component inline in the chat. Handled automatically by the SDK.",
+    inputSchema: RENDER_UI_SCHEMA,
+    hidden: false,
+    aiResponseMode: "none",
+    aiContext: (_, args) => {
+      const type = (args as GenerativeUIPayload)?.type ?? "ui";
+      return `[Rendered ${type} component to user]`;
+    },
+    handler: async (params) => {
+      // Some LLMs wrap the payload in a `data` key — unwrap if needed
+      const raw =
+        params && typeof params === "object" && "data" in params
+          ? (params as Record<string, unknown>).data
+          : params;
+      const parsed = GenerativeUIPayloadSchema.safeParse(raw);
+      if (!parsed.success) {
+        return {
+          success: false,
+          error: `Invalid generative UI payload: ${parsed.error.message}`,
+        };
+      }
+      return {
+        success: true,
+        data: parsed.data,
+        _aiContext: `[Rendered ${parsed.data.type} component to user]`,
+        _aiResponseMode: "none" as const,
+      };
+    },
+    render: (props: ToolRenderProps<GenerativeUIPayload>) => (
+      <GenerativeUIRenderer props={props} configRef={configRef} />
+    ),
+  });
+}
+
+// ─── Internal renderer ────────────────────────────────────────────────────────
+
+interface InternalRendererProps {
+  props: ToolRenderProps<GenerativeUIPayload>;
+  configRef: React.MutableRefObject<UseGenerativeUIConfig>;
+}
+
+function GenerativeUIRenderer({
+  props: renderProps,
+  configRef,
+}: InternalRendererProps) {
+  const { status, result, error } = renderProps;
+  const config = configRef.current;
+
+  // Loading
+  if (status === "pending" || status === "executing") {
+    return (
+      <div className="flex items-center gap-2 py-1.5 text-sm text-muted-foreground">
+        <DotsLoader size="sm" />
+        <span>Preparing response…</span>
+      </div>
+    );
+  }
+
+  // Error
+  if (status === "error") {
+    return (
+      <div className="rounded-md border border-destructive/30 bg-destructive/5 px-3 py-2 text-sm text-destructive">
+        {error ?? "Failed to render UI component."}
+      </div>
+    );
+  }
+
+  // Completed — parse payload from result.data
+  if (status !== "completed") return null;
+
+  const rawPayload = result?.data as GenerativeUIPayload | undefined;
+  const parsed = GenerativeUIPayloadSchema.safeParse(rawPayload);
+
+  if (!parsed.success) {
+    return (
+      <div className="overflow-auto rounded-md border border-border bg-muted/30 px-3 py-2">
+        <pre className="whitespace-pre-wrap text-xs text-muted-foreground">
+          {JSON.stringify(rawPayload, null, 2)}
+        </pre>
+      </div>
+    );
+  }
+
+  const payload = parsed.data;
+
+  switch (payload.type) {
+    case "html": {
+      const Override = config.overrideRenderers?.html;
+      return Override ? (
+        <Override payload={payload} />
+      ) : (
+        <HtmlRenderer payload={payload} />
+      );
+    }
+
+    case "chart": {
+      const ChartComp = config.overrideRenderers?.chart ?? config.chartRenderer;
+      return ChartComp ? (
+        <ChartComp payload={payload} />
+      ) : (
+        <ChartFallback payload={payload} />
+      );
+    }
+
+    case "table": {
+      const Override = config.overrideRenderers?.table;
+      return Override ? (
+        <Override payload={payload} />
+      ) : (
+        <TableRenderer payload={payload} />
+      );
+    }
+
+    case "stat": {
+      const Override = config.overrideRenderers?.stat;
+      return Override ? (
+        <Override payload={payload} />
+      ) : (
+        <StatRenderer payload={payload} />
+      );
+    }
+
+    case "card": {
+      const Override = config.overrideRenderers?.card;
+      return Override ? (
+        <Override payload={payload} />
+      ) : (
+        <CardRenderer payload={payload} />
+      );
+    }
+
+    default:
+      return null;
+  }
+}
+
+/** Shown when no chartRenderer is provided */
+function ChartFallback({ payload }: { payload: ChartPayload }) {
+  return (
+    <div className="rounded-md border border-border bg-muted/20 p-3">
+      {payload.title && (
+        <p className="mb-1.5 text-sm font-medium text-foreground">
+          {payload.title}
+        </p>
+      )}
+      <p className="mb-2 text-xs text-muted-foreground">
+        Chart type:{" "}
+        <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">
+          {payload.chartType}
+        </code>
+        . Pass a <code className="font-mono">chartRenderer</code> prop to{" "}
+        <code className="font-mono">useGenerativeUI()</code> to render this.
+      </p>
+      <pre className="max-h-40 overflow-auto whitespace-pre-wrap text-xs text-muted-foreground font-mono">
+        {JSON.stringify(
+          { labels: payload.labels, datasets: payload.datasets },
+          null,
+          2,
+        )}
+      </pre>
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/tsup.config.ts b/packages/copilot-sdk/tsup.config.ts
index 1bd65f2..c5f9fa5 100644
--- a/packages/copilot-sdk/tsup.config.ts
+++ b/packages/copilot-sdk/tsup.config.ts
@@ -12,6 +12,9 @@ export default defineConfig({
     // Server-only entry (Node.js skills loader)
     "server/index": "src/server/index.ts",
 
+    // Experimental features
+    "experimental/index": "src/experimental/index.ts",
+
     // Tool subpath exports (tree-shakeable)
     "tools/web-search/index": "src/tools/web-search/index.ts",
     "tools/tavily/index": "src/tools/tavily/index.ts",

From 1a5f4fd3236f294b1d7aff80e075f9f08e6784f4 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 21 Mar 2026 19:07:26 +0530
Subject: [PATCH 30/72] fix(sdk): persist parent_id in localStorage and fix
 tool-use/result ordering
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- localStorageAdapter: save/restore parent_id, children_ids, activeLeafId so
  the MessageTree branch structure survives page reloads. Without this, all
  parentIds were lost on reload and fromFlatArray reconstructed wrong parents,
  causing tool_result messages to land in inactive branches → consecutive
  assistant messages sent to Anthropic → 400 invalid_request_error.

- MessageTree.fromFlatArray: fix legacy (no parentId) reconstruction so that
  the message after a tool result becomes its child, not a sibling. Also chain
  consecutive tool results from the same assistant turn correctly.

- chat.tsx / types.ts: add wrapMessage prop to CopilotChat — wraps
  DefaultMessage output without replacing it, preserving toolRenderers and
  loading states while allowing custom bubble UI.

- default-message.tsx: fix tool renderer priority — toolRenderers map (named
  renderers) now checked before fallbackToolRenderer, preventing FallbackToolCard
  from intercepting named tool renders on reload before useTool() hooks re-register.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/chat/branching/MessageTree.ts         | 31 ++++++++++++++-----
 .../thread/adapters/localStorageAdapter.ts    | 12 +++++++
 .../src/ui/components/composed/chat/chat.tsx  | 27 +++++++++++++---
 .../composed/chat/default-message.tsx         | 18 +++++------
 .../src/ui/components/composed/chat/types.ts  |  7 +++++
 5 files changed, 73 insertions(+), 22 deletions(-)

diff --git a/packages/copilot-sdk/src/chat/branching/MessageTree.ts b/packages/copilot-sdk/src/chat/branching/MessageTree.ts
index 1daa0bf..e093d98 100644
--- a/packages/copilot-sdk/src/chat/branching/MessageTree.ts
+++ b/packages/copilot-sdk/src/chat/branching/MessageTree.ts
@@ -62,9 +62,10 @@ export class MessageTree<T extends UIMessage = UIMessage> {
    *
    * Rules:
    * - Tool messages get parentId = the owning assistant message's id
-   *   (matched via toolCallId → toolCall.id).
-   * - All other messages get parentId of the previous non-tool message
-   *   (or null for the first message).
+   *   (matched via toolCallId → toolCall.id), chained in sequence.
+   * - All other messages get parentId = the previous message in the linear
+   *   chain (including tool messages, so the next non-tool after tool results
+   *   is a child of the last tool result, not a sibling).
    *
    * Returns a new array with parentId/childrenIds filled in.
    * Does NOT mutate the original messages.
@@ -77,8 +78,9 @@ export class MessageTree<T extends UIMessage = UIMessage> {
     if (alreadyLinked) return messages;
 
     const result: T[] = [];
-    // Track linear parent chain (skip tool messages for parent tracking)
-    let prevNonToolId: string | null = null;
+    // Track the previous message id for linear chain (includes tool messages
+    // so that the next non-tool message becomes a child of the last tool result)
+    let prevId: string | null = null;
 
     // Build assistant id → assistant message map for tool pairing
     const assistantById = new Map<string, T>();
@@ -88,6 +90,10 @@ export class MessageTree<T extends UIMessage = UIMessage> {
       }
     }
 
+    // Track the last tool message id per owning assistant, so consecutive tool
+    // results from the same turn are chained (tool_result_1 → tool_result_2).
+    const lastToolIdByAssistant = new Map<string, string>();
+
     for (const msg of messages) {
       if (msg.role === "tool" && msg.toolCallId) {
         // Find owning assistant message by matching toolCallId → toolCall.id
@@ -98,18 +104,27 @@ export class MessageTree<T extends UIMessage = UIMessage> {
             break;
           }
         }
+        // Chain multiple tool results for the same assistant turn
+        const chainParent = ownerAssistantId
+          ? (lastToolIdByAssistant.get(ownerAssistantId) ?? ownerAssistantId)
+          : (prevId ?? null);
         result.push({
           ...msg,
-          parentId: ownerAssistantId ?? prevNonToolId,
+          parentId: chainParent,
           childrenIds: [],
         });
+        if (ownerAssistantId) {
+          lastToolIdByAssistant.set(ownerAssistantId, msg.id);
+        }
+        // Advance prevId so the next non-tool message is a child of this result
+        prevId = msg.id;
       } else {
         result.push({
           ...msg,
-          parentId: prevNonToolId,
+          parentId: prevId,
           childrenIds: [],
         });
-        prevNonToolId = msg.id;
+        prevId = msg.id;
       }
     }
 
diff --git a/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts b/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
index 3843e48..128db06 100644
--- a/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
+++ b/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
@@ -35,6 +35,8 @@ interface SerializedThreadData {
   updatedAt: string;
   messages: SerializedMessage[];
   sources: unknown[];
+  /** ID of the active leaf message for branch restoration */
+  activeLeafId?: string;
 }
 
 /**
@@ -48,6 +50,10 @@ interface SerializedMessage {
   tool_calls?: unknown;
   tool_call_id?: string;
   metadata?: unknown;
+  /** Parent message ID for branch tree reconstruction */
+  parent_id?: string | null;
+  /** Child message IDs for branch tree reconstruction */
+  children_ids?: string[];
 }
 
 /**
@@ -99,6 +105,7 @@ function serializeThread(thread: ThreadData): SerializedThreadData {
     createdAt: thread.createdAt.toISOString(),
     updatedAt: thread.updatedAt.toISOString(),
     sources: thread.sources || [],
+    activeLeafId: thread.activeLeafId,
     messages: thread.messages.map((m) => ({
       id: m.id,
       role: m.role,
@@ -110,6 +117,8 @@ function serializeThread(thread: ThreadData): SerializedThreadData {
       tool_calls: m.tool_calls,
       tool_call_id: m.tool_call_id,
       metadata: m.metadata,
+      parent_id: m.parent_id,
+      children_ids: m.children_ids,
     })),
   };
 }
@@ -126,6 +135,7 @@ function deserializeThread(data: SerializedThreadData): ThreadData {
     createdAt: new Date(data.createdAt),
     updatedAt: new Date(data.updatedAt),
     sources: (data.sources || []) as ThreadData["sources"],
+    activeLeafId: data.activeLeafId,
     messages: (data.messages || []).map((m) => ({
       id: m.id,
       role: m.role as "user" | "assistant" | "system" | "tool",
@@ -134,6 +144,8 @@ function deserializeThread(data: SerializedThreadData): ThreadData {
       tool_calls: m.tool_calls as ThreadData["messages"][0]["tool_calls"],
       tool_call_id: m.tool_call_id,
       metadata: m.metadata as ThreadData["messages"][0]["metadata"],
+      parent_id: m.parent_id,
+      children_ids: m.children_ids,
     })),
   };
 }
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 27f11dd..4b208e8 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -546,6 +546,7 @@ function ChatComponent({
   // Custom rendering
   messageView,
   renderMessage,
+  wrapMessage,
   renderInput,
   renderHeader,
   // Avatar grouping
@@ -1027,11 +1028,15 @@ function ChatComponent({
                           }
                         };
 
-                        return renderMessage ? (
-                          <React.Fragment key={message.id}>
-                            {renderMessage(messageWithExecutions, index)}
-                          </React.Fragment>
-                        ) : (
+                        if (renderMessage) {
+                          return (
+                            <React.Fragment key={message.id}>
+                              {renderMessage(messageWithExecutions, index)}
+                            </React.Fragment>
+                          );
+                        }
+
+                        const defaultMsg = (
                           <DefaultMessage
                             key={message.id}
                             message={messageWithExecutions}
@@ -1079,6 +1084,18 @@ function ChatComponent({
                             onEditMessage={onEditMessage}
                           />
                         );
+
+                        return wrapMessage ? (
+                          <React.Fragment key={message.id}>
+                            {wrapMessage(
+                              defaultMsg,
+                              messageWithExecutions,
+                              index,
+                            )}
+                          </React.Fragment>
+                        ) : (
+                          defaultMsg
+                        );
                       });
                       return messageView?.children
                         ? messageView.children({ messages, messageElements })
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index ca26f04..e132b51 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -727,11 +727,11 @@ export function DefaultMessage({
                     );
                   }
 
-                  // PRIORITY 3: fallbackToolRenderer (catch-all for any unmatched tool)
-                  if (fallbackToolRenderer) {
-                    const FallbackRenderer = fallbackToolRenderer;
+                  // PRIORITY 3: toolRenderers map (app-level explicit renderer — static, always available)
+                  const Renderer = toolRenderers?.[exec.name];
+                  if (Renderer) {
                     return (
-                      <FallbackRenderer
+                      <Renderer
                         key={exec.id}
                         execution={{
                           id: exec.id,
@@ -740,17 +740,18 @@ export function DefaultMessage({
                           status: exec.status,
                           result: exec.result,
                           error: exec.error,
+                          approvalStatus: exec.approvalStatus,
                           source: exec.source,
                         }}
                       />
                     );
                   }
 
-                  // PRIORITY 4: toolRenderers map (app-level explicit renderer)
-                  const Renderer = toolRenderers?.[exec.name];
-                  if (Renderer) {
+                  // PRIORITY 4: fallbackToolRenderer (catch-all for any unmatched tool)
+                  if (fallbackToolRenderer) {
+                    const FallbackRenderer = fallbackToolRenderer;
                     return (
-                      <Renderer
+                      <FallbackRenderer
                         key={exec.id}
                         execution={{
                           id: exec.id,
@@ -759,7 +760,6 @@ export function DefaultMessage({
                           status: exec.status,
                           result: exec.result,
                           error: exec.error,
-                          approvalStatus: exec.approvalStatus,
                           source: exec.source,
                         }}
                       />
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
index 842313e..7754344 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
@@ -482,6 +482,13 @@ export type ChatProps = {
   };
   /** Custom message renderer */
   renderMessage?: (message: ChatMessage, index: number) => React.ReactNode;
+  /** Wrap each DefaultMessage in a custom container — for animations, hover effects, etc.
+   *  Unlike renderMessage, this preserves all SDK defaults (toolRenderers, loading, avatars, approval). */
+  wrapMessage?: (
+    content: React.ReactNode,
+    message: ChatMessage,
+    index: number,
+  ) => React.ReactNode;
   /** Custom input renderer (replaces entire input area) */
   renderInput?: () => React.ReactNode;
   /** Custom header renderer (replaces entire header) */

From a775b03c15f3a3cc65099026dc04e0a1a79aafed Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 13:46:52 +0530
Subject: [PATCH 31/72] feat: agent iteration tracking, allowEdit prop,
 checkpoint exports, action fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix infinite retry loop when maxIterations reached: replaced continueWithToolResults
  with new addToolResultMessages() that closes tool_use blocks without triggering a
  new LLM request
- Add addToolResultMessages() to AbstractChat for closing tool history without new request
- Add agentIteration to CopilotProvider context (resets on sendMessage, increments
  per tool batch executeToolCalls call)
- Export useMessageCheckpoints + types from react/hooks public API
- Add allowEdit prop to CopilotChat (default false — opt-in, previously always on)
- Fix MessageActions infinite re-registration loop via ctxRef pattern in useLayoutEffect
- Fix message action context value stability with useMemo
- Add behaviorChildren logic so MessageActions registrars always mount in Chat
- Add csdk-message/csdk-user-message/csdk-assistant-message CSS classes for targeting
- Add @starting-style entrance animation for chat messages

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../copilot-sdk/src/chat/ChatWithTools.ts     |  16 +-
 .../src/chat/classes/AbstractChat.ts          |  51 +++++
 packages/copilot-sdk/src/react/hooks/index.ts |   7 +
 .../src/react/hooks/useMessageCheckpoints.ts  | 181 ++++++++++++++++++
 packages/copilot-sdk/src/react/index.ts       |   7 +
 .../src/react/provider/CopilotProvider.tsx    |  10 +
 .../src/ui/components/composed/chat/chat.tsx  |  14 ++
 .../composed/chat/default-message.tsx         |   6 +-
 .../chat/message-actions-compound.tsx         |  18 +-
 .../composed/chat/message-actions-context.tsx |  17 +-
 .../ui/components/composed/connected-chat.tsx |   9 +-
 packages/copilot-sdk/src/ui/styles/base.css   |  18 ++
 12 files changed, 339 insertions(+), 15 deletions(-)
 create mode 100644 packages/copilot-sdk/src/react/hooks/useMessageCheckpoints.ts

diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index 48ccf7d..a858854 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -277,9 +277,15 @@ export class ChatWithTools {
           this.agentLoop.maxIterationsReached &&
           toolCallInfos.length > 0
         ) {
-          // Max iterations reached - still need to add tool_result to prevent API errors
-          // Without this, the conversation has tool_use without tool_result
-          this.debug("Max iterations reached, adding blocked tool results");
+          // Max iterations reached — close out the pending tool_use blocks (so the
+          // conversation history stays valid for the next request) but do NOT trigger
+          // another LLM call.  Previously we called continueWithToolResults() here,
+          // which sent the error to the AI and started a new LLM request; the AI
+          // responded "let me retry" + new tool_use blocks → the same limit fired
+          // again → continueWithToolResults again → infinite loop.
+          this.debug(
+            "Max iterations reached, stopping loop without new LLM request",
+          );
 
           const errorMessage =
             this.config.maxIterationsMessage ||
@@ -293,7 +299,9 @@ export class ChatWithTools {
             },
           }));
 
-          await this.chat.continueWithToolResults(blockedResults);
+          // Adds tool_result messages + a final assistant stop-message, then sets
+          // status → "ready".  No new API request is made.
+          await this.chat.addToolResultMessages(blockedResults, errorMessage);
         }
       } catch (error) {
         this.debug("Error executing tools:", error);
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 43b3d1e..451b7df 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -418,6 +418,57 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     }
   }
 
+  /**
+   * Add tool result messages to history and stop — does NOT trigger a new LLM request.
+   *
+   * Use this instead of continueWithToolResults when you want to close out pending
+   * tool_use blocks (so the history stays valid) without letting the AI continue.
+   * Optionally appends a final assistant message (e.g. an iteration-limit notice).
+   */
+  async addToolResultMessages(
+    toolResults: Array<{ toolCallId: string; result: unknown }>,
+    finalAssistantContent?: string,
+  ): Promise<void> {
+    const visibleMessages = this.state.messages;
+    let chainParentId: string | undefined =
+      visibleMessages.length > 0
+        ? visibleMessages[visibleMessages.length - 1].id
+        : undefined;
+
+    for (const { toolCallId, result } of toolResults) {
+      const messageContent =
+        typeof result === "string" ? result : JSON.stringify(result);
+
+      const toolMessageId = generateMessageId();
+      const toolMessage = {
+        id: toolMessageId,
+        role: "tool" as const,
+        content: messageContent,
+        toolCallId,
+        createdAt: new Date(),
+        ...(chainParentId !== undefined ? { parentId: chainParentId } : {}),
+      } as T;
+
+      this.state.pushMessage(toolMessage);
+      chainParentId = toolMessageId;
+    }
+
+    if (finalAssistantContent) {
+      const assistantMsg = {
+        id: generateMessageId(),
+        role: "assistant" as const,
+        content: finalAssistantContent,
+        createdAt: new Date(),
+        ...(chainParentId !== undefined ? { parentId: chainParentId } : {}),
+      } as T;
+      this.state.pushMessage(assistantMsg);
+    }
+
+    this.callbacks.onMessagesChange?.(this._allMessages());
+    this.state.status = "ready";
+    this.callbacks.onStatusChange?.("ready");
+  }
+
   /**
    * Stop generation
    */
diff --git a/packages/copilot-sdk/src/react/hooks/index.ts b/packages/copilot-sdk/src/react/hooks/index.ts
index 197f6e5..945a825 100644
--- a/packages/copilot-sdk/src/react/hooks/index.ts
+++ b/packages/copilot-sdk/src/react/hooks/index.ts
@@ -107,3 +107,10 @@ export {
 // Skills Hooks
 export { useSkill } from "./useSkill";
 export { useSkillStatus, type UseSkillStatusReturn } from "./useSkillStatus";
+
+// Message Checkpoints (undo / restore to before a user message)
+export {
+  useMessageCheckpoints,
+  type MessageCheckpoint,
+  type UseMessageCheckpointsReturn,
+} from "./useMessageCheckpoints";
diff --git a/packages/copilot-sdk/src/react/hooks/useMessageCheckpoints.ts b/packages/copilot-sdk/src/react/hooks/useMessageCheckpoints.ts
new file mode 100644
index 0000000..b680984
--- /dev/null
+++ b/packages/copilot-sdk/src/react/hooks/useMessageCheckpoints.ts
@@ -0,0 +1,181 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useReducer, useRef } from "react";
+import { useCopilot } from "../provider/CopilotProvider";
+import type { UIMessage } from "../../chat";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface MessageCheckpoint {
+  /** Unique checkpoint ID */
+  id: string;
+  /** ID of the user message that triggered this checkpoint */
+  messageId: string;
+  /** When this checkpoint was created */
+  timestamp: number;
+  /** Optional human-readable label */
+  label?: string;
+  /** Full message list BEFORE the user message was processed */
+  messages: UIMessage[];
+}
+
+export interface UseMessageCheckpointsReturn {
+  /** All saved checkpoints, oldest first */
+  checkpoints: MessageCheckpoint[];
+  /** True if a checkpoint exists for the given user message ID */
+  hasCheckpoint: (messageId: string) => boolean;
+  /** Get the checkpoint for a user message ID, or undefined */
+  getCheckpoint: (messageId: string) => MessageCheckpoint | undefined;
+  /**
+   * Restore chat to the state before the user message with the given ID.
+   * Returns the checkpoint if found, undefined otherwise.
+   * Checkpoints created after this one are pruned.
+   */
+  restore: (messageId: string) => MessageCheckpoint | undefined;
+  /**
+   * Manually save a checkpoint for a message ID.
+   * Auto-save already runs on every new user message — use this for
+   * programmatic checkpoints (e.g. before a destructive tool call).
+   */
+  save: (messageId: string, label?: string) => MessageCheckpoint | undefined;
+  /** Clear all saved checkpoints */
+  clear: () => void;
+}
+
+// ─── Hook ─────────────────────────────────────────────────────────────────────
+
+/**
+ * useMessageCheckpoints
+ *
+ * Automatically saves a checkpoint before each user message is sent to the
+ * agent. Each checkpoint captures the full chat state that existed BEFORE
+ * that user message, so restoring it rolls the conversation back to exactly
+ * that point.
+ *
+ * Generic — works for any agentic app (flow builders, code editors, document
+ * assistants, etc.). App-specific side effects (e.g. restoring a canvas or
+ * database state) can be layered on top via the returned `restore` value.
+ *
+ * @example
+ * ```tsx
+ * // Inside <CopilotChat> children
+ * function MyCheckpointActions() {
+ *   const { hasCheckpoint, restore } = useMessageCheckpoints();
+ *   return (
+ *     <CopilotChat.MessageActions role="user">
+ *       <CopilotChat.Action
+ *         icon={<RotateCcw className="size-3.5" />}
+ *         tooltip="Restore to before this message"
+ *         onClick={({ message }) => restore(message.id)}
+ *         hidden={({ message }) => !hasCheckpoint(message.id)}
+ *       />
+ *     </CopilotChat.MessageActions>
+ *   );
+ * }
+ * ```
+ */
+export function useMessageCheckpoints(): UseMessageCheckpointsReturn {
+  const { messages, setMessages } = useCopilot();
+
+  // messageId → checkpoint
+  const checkpointMapRef = useRef<Map<string, MessageCheckpoint>>(new Map());
+  // How many user messages we've seen so far
+  const prevUserMsgCountRef = useRef(0);
+  // Revision counter drives re-renders of consumers
+  const [revision, bump] = useReducer((n: number) => n + 1, 0);
+
+  // ── Auto-save on new user message ──────────────────────────────────────────
+  useEffect(() => {
+    const userMessages = messages.filter((m) => m.role === "user");
+    const count = userMessages.length;
+
+    if (count > prevUserMsgCountRef.current) {
+      const newUserMsg = userMessages[count - 1];
+
+      if (!checkpointMapRef.current.has(newUserMsg.id)) {
+        const msgIndex = messages.findIndex((m) => m.id === newUserMsg.id);
+        checkpointMapRef.current.set(newUserMsg.id, {
+          id: `cp_${newUserMsg.id}`,
+          messageId: newUserMsg.id,
+          timestamp: Date.now(),
+          messages: structuredClone(messages.slice(0, msgIndex)),
+        });
+        bump();
+      }
+
+      prevUserMsgCountRef.current = count;
+    }
+  }, [messages]);
+
+  // ── API ────────────────────────────────────────────────────────────────────
+
+  const hasCheckpoint = useCallback(
+    (messageId: string) => checkpointMapRef.current.has(messageId),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [revision],
+  );
+
+  const getCheckpoint = useCallback(
+    (messageId: string) => checkpointMapRef.current.get(messageId),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [revision],
+  );
+
+  const restore = useCallback(
+    (messageId: string): MessageCheckpoint | undefined => {
+      const cp = checkpointMapRef.current.get(messageId);
+      if (!cp) return undefined;
+
+      // Roll back chat messages
+      setMessages(cp.messages);
+
+      // Prune checkpoints that came after this point
+      checkpointMapRef.current.forEach((c, k) => {
+        if (c.timestamp > cp.timestamp) checkpointMapRef.current.delete(k);
+      });
+      prevUserMsgCountRef.current = cp.messages.filter(
+        (m) => m.role === "user",
+      ).length;
+
+      bump();
+      return cp;
+    },
+    [setMessages],
+  );
+
+  const save = useCallback(
+    (messageId: string, label?: string): MessageCheckpoint | undefined => {
+      const msgIndex = messages.findIndex((m) => m.id === messageId);
+      if (msgIndex === -1) return undefined;
+
+      const cp: MessageCheckpoint = {
+        id: `cp_${messageId}`,
+        messageId,
+        timestamp: Date.now(),
+        label,
+        messages: structuredClone(messages.slice(0, msgIndex)),
+      };
+      checkpointMapRef.current.set(messageId, cp);
+      bump();
+      return cp;
+    },
+    [messages],
+  );
+
+  const clear = useCallback(() => {
+    checkpointMapRef.current.clear();
+    prevUserMsgCountRef.current = 0;
+    bump();
+  }, []);
+
+  const checkpoints = useMemo(
+    () =>
+      Array.from(checkpointMapRef.current.values()).sort(
+        (a, b) => a.timestamp - b.timestamp,
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [revision],
+  );
+
+  return { checkpoints, hasCheckpoint, getCheckpoint, restore, save, clear };
+}
diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index d8dc701..64a66ea 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -160,6 +160,13 @@ export {
   type UseMCPUIIntentsReturn,
 } from "./hooks";
 
+// Message Checkpoints — undo / restore conversation to before any user message
+export {
+  useMessageCheckpoints,
+  type MessageCheckpoint,
+  type UseMessageCheckpointsReturn,
+} from "./hooks";
+
 // Re-export core types for convenience
 export type {
   Message,
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 809b3c5..df08159 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -385,6 +385,9 @@ export interface CopilotContextValue {
     }>,
   ) => void;
 
+  // Agent loop iteration (increments each time the AI calls a tool batch; resets on sendMessage)
+  agentIteration: number;
+
   // Config
   threadId?: string;
   /**
@@ -457,6 +460,7 @@ export function CopilotProvider({
   // Tool Executions State (for React reactivity)
   // ============================================
   const [toolExecutions, setToolExecutions] = useState<ToolExecution[]>([]);
+  const [agentIteration, setAgentIteration] = useState(0);
 
   // ============================================
   // ChatWithTools Instance
@@ -505,6 +509,9 @@ export function CopilotProvider({
         onToolExecutionsChange: (executions) => {
           debugLog("Tool executions changed:", executions.length);
           setToolExecutions(executions);
+          // Sync the agent loop iteration count at the same time — it increments
+          // once per executeToolCalls() call, which is what triggers this callback.
+          setAgentIteration(chatRef.current?.iteration ?? 0);
         },
         onApprovalRequired: (execution) => {
           debugLog("Tool approval required:", execution.name);
@@ -727,6 +734,7 @@ export function CopilotProvider({
   const sendMessage = useCallback(
     async (content: string, attachments?: MessageAttachment[]) => {
       debugLog("Sending message:", content);
+      setAgentIteration(0); // reset before each new user message
       await chatRef.current?.sendMessage(content, attachments);
     },
     [debugLog],
@@ -855,6 +863,7 @@ export function CopilotProvider({
       pendingApprovals,
       approveToolExecution,
       rejectToolExecution,
+      agentIteration,
 
       // Actions
       registerAction,
@@ -900,6 +909,7 @@ export function CopilotProvider({
       pendingApprovals,
       approveToolExecution,
       rejectToolExecution,
+      agentIteration,
       registerAction,
       unregisterAction,
       registeredActions,
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 4b208e8..28a32c7 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -788,6 +788,17 @@ function ChatComponent({
     ChatView,
   );
 
+  // Behavior children: non-layout compound types (MessageActions registrars, custom hook components)
+  // These always mount so their useLayoutEffect registrations run regardless of view state.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const layoutTypes: any[] = [HomeView, Home, ChatView, Header, Footer];
+  const behaviorChildren = React.Children.toArray(children).filter(
+    (child) =>
+      React.isValidElement(child) &&
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      !layoutTypes.includes(child.type as any),
+  ) as React.ReactElement[];
+
   // Check if ChatView has no children or only Header/Footer children (should render default)
   const chatViewElement = findCompoundChild(children, ChatView);
   const chatViewNeedsDefault =
@@ -887,6 +898,9 @@ function ChatComponent({
           {/* Root-level custom Header (shows in both views) */}
           {rootHeader}
 
+          {/* Behavior children — always mounted (MessageActions registrars, hook components) */}
+          {behaviorChildren.length > 0 && behaviorChildren}
+
           {/* Custom compound children - view components self-filter based on current view */}
           {hasCustomLayout && viewChildren}
 
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index e132b51..cd5752b 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -415,7 +415,9 @@ export function DefaultMessage({
 
     return (
       <Message
-        className={cn("flex gap-2 group/user-msg group/message justify-end")}
+        className={cn(
+          "csdk-message csdk-user-message flex gap-2 group/user-msg group/message justify-end",
+        )}
       >
         <div className="flex flex-col items-end max-w-[80%] min-w-0">
           {/* Edit mode: inline textarea */}
@@ -607,7 +609,7 @@ export function DefaultMessage({
 
   // Assistant message - left aligned with avatar
   return (
-    <Message className="flex gap-2 group/message">
+    <Message className="csdk-message csdk-assistant-message flex gap-2 group/message">
       <MessageAvatar
         src={assistantAvatar.src}
         alt="Assistant"
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-compound.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-compound.tsx
index cd155f2..9372170 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-compound.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-compound.tsx
@@ -3,6 +3,7 @@
 import React, {
   useLayoutEffect,
   useMemo,
+  useRef,
   createContext,
   useContext,
 } from "react";
@@ -202,6 +203,11 @@ export interface MessageActionsProps {
  */
 export function MessageActions({ role, children }: MessageActionsProps) {
   const ctx = useMessageActionsContext();
+  // Use ref so ctx is never a useLayoutEffect dependency — prevents infinite
+  // loop when setRegistry fires → context value changes → useLayoutEffect
+  // cleanup runs → clearActions → setRegistry → repeat.
+  const ctxRef = useRef(ctx);
+  ctxRef.current = ctx;
 
   // Extract action definitions from declarative children
   const actions = useMemo<RegisteredAction[]>(() => {
@@ -279,10 +285,14 @@ export function MessageActions({ role, children }: MessageActionsProps) {
   }, [children]);
 
   useLayoutEffect(() => {
-    if (!ctx) return;
-    ctx.registerActions(role, actions);
-    return () => ctx.clearActions(role);
-  }, [ctx, role, actions]);
+    const c = ctxRef.current;
+    if (!c) return;
+    c.registerActions(role, actions);
+    return () => c.clearActions(role);
+    // ctx accessed via ref — NOT in deps — to prevent the setState→re-render→
+    // new ctx ref→useLayoutEffect→clearActions→setState infinite loop.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [role, actions]);
 
   return null;
 }
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-context.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-context.tsx
index 4cf32ff..4378b95 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-context.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/message-actions-context.tsx
@@ -1,6 +1,12 @@
 "use client";
 
-import React, { createContext, useContext, useState, useCallback } from "react";
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useMemo,
+} from "react";
 import type { ChatMessage } from "./types";
 
 export interface RegisteredAction {
@@ -54,10 +60,13 @@ export function MessageActionsProvider({
     [registry],
   );
 
+  const contextValue = useMemo(
+    () => ({ getActions, registerActions, clearActions }),
+    [getActions, registerActions, clearActions],
+  );
+
   return (
-    <MessageActionsContext.Provider
-      value={{ getActions, registerActions, clearActions }}
-    >
+    <MessageActionsContext.Provider value={contextValue}>
       {children}
     </MessageActionsContext.Provider>
   );
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index ea2080c..8b8662e 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -187,6 +187,12 @@ export type CopilotChatProps = Omit<
    * Granular class names for sub-components including thread picker
    */
   classNames?: CopilotChatClassNames;
+
+  /**
+   * Allow inline editing of user messages.
+   * @default false
+   */
+  allowEdit?: boolean;
 };
 
 /**
@@ -301,6 +307,7 @@ function CopilotChatBase(
     classNames,
     header,
     children,
+    allowEdit = false,
     ...chatProps
   } = props;
 
@@ -641,7 +648,7 @@ function CopilotChatBase(
       // Branching (auto-wired from context)
       getBranchInfo={getBranchInfo}
       onSwitchBranch={switchBranch}
-      onEditMessage={editMessage}
+      onEditMessage={allowEdit ? editMessage : undefined}
     >
       {children}
     </Chat>
diff --git a/packages/copilot-sdk/src/ui/styles/base.css b/packages/copilot-sdk/src/ui/styles/base.css
index f505826..63da214 100644
--- a/packages/copilot-sdk/src/ui/styles/base.css
+++ b/packages/copilot-sdk/src/ui/styles/base.css
@@ -60,6 +60,24 @@
   }
 }
 
+/* Message entrance animation — fires on React DOM mount via @starting-style.
+   csdk-message: applied to every message row (user + assistant + tool).
+   Consumers can override via .csdk-user-message / .csdk-assistant-message selectors. */
+
+.csdk-message {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+  transition: opacity 0.22s cubic-bezier(0, 0, 0.2, 1),
+              transform 0.22s cubic-bezier(0, 0, 0.2, 1);
+}
+
+@starting-style {
+  .csdk-message {
+    opacity: 0;
+    transform: translateY(8px) scale(0.97);
+  }
+}
+
 /* Confirmation Card Animations */
 /* Uses @starting-style for reliable first-paint entry in React (more robust than @keyframes) */
 

From 8b56221de4ce6c6a2ab416ec7fdc3695503a5742 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 14:05:40 +0530
Subject: [PATCH 32/72] =?UTF-8?q?ui:=20redesign=20confirm=20card=20?=
 =?UTF-8?q?=E2=80=94=20amber=20border,=20icon=20ring,=20divider,=20better?=
 =?UTF-8?q?=20buttons?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/ui/components/ui/confirmation.tsx     | 66 +++++++++++----
 .../components/ui/permission-confirmation.tsx | 80 ++++++++++---------
 2 files changed, 90 insertions(+), 56 deletions(-)

diff --git a/packages/copilot-sdk/src/ui/components/ui/confirmation.tsx b/packages/copilot-sdk/src/ui/components/ui/confirmation.tsx
index cb0711f..09128f1 100644
--- a/packages/copilot-sdk/src/ui/components/ui/confirmation.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/confirmation.tsx
@@ -2,7 +2,6 @@
 
 import * as React from "react";
 import { cn } from "../../lib/utils";
-import { Button } from "./button";
 import { CheckIcon, XIcon, AlertTriangleIcon } from "../icons";
 
 // ============================================
@@ -92,7 +91,10 @@ export function Confirmation({
     >
       <div
         className={cn(
-          "confirmation rounded-lg border bg-card text-card-foreground",
+          "csdk-confirm-card",
+          "confirmation rounded-2xl overflow-hidden",
+          "border border-amber-200/50 dark:border-amber-900/30",
+          "bg-card text-card-foreground shadow-sm",
           className,
         )}
       >
@@ -121,7 +123,7 @@ export function ConfirmationPending({
   const { state } = useConfirmationContext();
   if (state !== "pending") return null;
 
-  return <div className={cn("p-4", className)}>{children}</div>;
+  return <div className={cn("pl-5 pr-4 pt-4 pb-3", className)}>{children}</div>;
 }
 
 export interface ConfirmationApprovedProps {
@@ -142,11 +144,14 @@ export function ConfirmationApproved({
   return (
     <div
       className={cn(
-        "flex items-center gap-2 px-4 py-2 text-sm text-green-600 dark:text-green-400",
+        "csdk-confirm-result",
+        "inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium",
+        "rounded-2xl border border-green-200/60 dark:border-green-800/40",
+        "bg-green-50/80 dark:bg-green-950/20 text-green-700 dark:text-green-400",
         className,
       )}
     >
-      <CheckIcon className="h-4 w-4" />
+      <CheckIcon className="h-3.5 w-3.5 shrink-0" />
       {children || <span>Approved</span>}
     </div>
   );
@@ -170,11 +175,14 @@ export function ConfirmationRejected({
   return (
     <div
       className={cn(
-        "flex items-center gap-2 px-4 py-2 text-sm text-red-600 dark:text-red-400",
+        "csdk-confirm-result",
+        "inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium",
+        "rounded-2xl border border-red-200/60 dark:border-red-800/40",
+        "bg-red-50/80 dark:bg-red-950/20 text-red-700 dark:text-red-400",
         className,
       )}
     >
-      <XIcon className="h-4 w-4" />
+      <XIcon className="h-3.5 w-3.5 shrink-0" />
       {children || <span>Rejected</span>}
     </div>
   );
@@ -200,8 +208,10 @@ export function ConfirmationMessage({
 
   return (
     <div className={cn("flex items-start gap-3", className)}>
-      <AlertTriangleIcon className="mt-0.5 h-5 w-5 flex-shrink-0 text-amber-500" />
-      <p className="text-sm text-foreground">
+      <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50 ring-1 ring-amber-200/60 dark:ring-amber-800/40">
+        <AlertTriangleIcon className="h-4 w-4 text-amber-600 dark:text-amber-400" />
+      </div>
+      <p className="flex-1 min-w-0 pt-0.5 text-sm text-foreground leading-snug">
         {children || message || "This action requires your approval."}
       </p>
     </div>
@@ -238,14 +248,36 @@ export function ConfirmationActions({
   }
 
   return (
-    <div className={cn("mt-3 flex justify-end gap-2", className)}>
-      <Button variant="outline" size="sm" onClick={onReject}>
-        {rejectLabel}
-      </Button>
-      <Button variant="default" size="sm" onClick={onApprove}>
-        {approveLabel}
-      </Button>
-    </div>
+    <>
+      <div className="mx-0 border-t border-border/40 mt-3" />
+      <div className={cn("flex justify-end gap-2 pt-3", className)}>
+        <button
+          type="button"
+          onClick={onReject}
+          className={cn(
+            "csdk-confirm-btn",
+            "px-4 py-1.5 text-sm font-medium rounded-xl",
+            "border border-border/80 bg-transparent text-muted-foreground",
+            "hover:bg-muted/80 hover:text-foreground hover:border-border",
+          )}
+        >
+          {rejectLabel}
+        </button>
+        <button
+          type="button"
+          onClick={onApprove}
+          className={cn(
+            "csdk-confirm-btn",
+            "px-4 py-1.5 text-sm font-medium rounded-xl",
+            "bg-primary text-primary-foreground",
+            "hover:bg-primary/90",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+          )}
+        >
+          {approveLabel}
+        </button>
+      </div>
+    </>
   );
 }
 
diff --git a/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx b/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
index 35c5b20..817e51b 100644
--- a/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
@@ -81,9 +81,9 @@ export function PermissionConfirmation({
       <div
         className={cn(
           "csdk-confirm-result",
-          "inline-flex items-center gap-2 px-3 py-1.5 text-sm",
-          "rounded-2xl border border-green-200/70 dark:border-green-900/40",
-          "bg-green-50 dark:bg-green-950/20 text-green-700 dark:text-green-400",
+          "inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium",
+          "rounded-2xl border border-green-200/60 dark:border-green-800/40",
+          "bg-green-50/80 dark:bg-green-950/20 text-green-700 dark:text-green-400",
           className,
         )}
       >
@@ -98,9 +98,9 @@ export function PermissionConfirmation({
       <div
         className={cn(
           "csdk-confirm-result",
-          "inline-flex items-center gap-2 px-3 py-1.5 text-sm",
-          "rounded-2xl border border-red-200/70 dark:border-red-900/40",
-          "bg-red-50 dark:bg-red-950/20 text-red-700 dark:text-red-400",
+          "inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium",
+          "rounded-2xl border border-red-200/60 dark:border-red-800/40",
+          "bg-red-50/80 dark:bg-red-950/20 text-red-700 dark:text-red-400",
           className,
         )}
       >
@@ -114,18 +114,20 @@ export function PermissionConfirmation({
     <div
       className={cn(
         "csdk-confirm-card",
-        "w-full rounded-2xl border border-border/60 bg-card text-card-foreground shadow-sm overflow-hidden",
+        "w-full rounded-2xl overflow-hidden",
+        "border border-amber-200/50 dark:border-amber-900/30",
+        "bg-card text-card-foreground shadow-sm",
         className,
       )}
     >
       {/* Body */}
-      <div className="flex items-start gap-3 p-4">
-        <div className="mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50">
-          <AlertTriangleIcon className="h-3.5 w-3.5 text-amber-600 dark:text-amber-400" />
+      <div className="flex items-start gap-3 p-4 pb-3">
+        <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50 ring-1 ring-amber-200/60 dark:ring-amber-800/40">
+          <AlertTriangleIcon className="h-4 w-4 text-amber-600 dark:text-amber-400" />
         </div>
         <div className="flex-1 min-w-0 pt-0.5">
           {toolName && (
-            <p className="text-[10px] font-semibold uppercase tracking-widest text-muted-foreground mb-1">
+            <p className="text-[10px] font-semibold uppercase tracking-widest text-amber-600/80 dark:text-amber-400/70 mb-1">
               {toolName}
             </p>
           )}
@@ -135,16 +137,19 @@ export function PermissionConfirmation({
         </div>
       </div>
 
+      {/* Divider */}
+      <div className="mx-4 border-t border-border/40" />
+
       {/* Actions */}
-      <div className="flex items-center justify-end gap-2 px-4 pb-4">
+      <div className="flex items-center justify-end gap-2 px-4 py-3">
         <button
           type="button"
           onClick={handleReject}
           className={cn(
             "csdk-confirm-btn",
             "px-4 py-1.5 text-sm font-medium rounded-xl",
-            "border border-border bg-transparent text-muted-foreground",
-            "hover:bg-muted/60 hover:text-foreground",
+            "border border-border/80 bg-transparent text-muted-foreground",
+            "hover:bg-muted/80 hover:text-foreground hover:border-border",
           )}
         >
           Deny
@@ -156,7 +161,8 @@ export function PermissionConfirmation({
             "csdk-confirm-btn",
             "px-4 py-1.5 text-sm font-medium rounded-xl",
             "bg-primary text-primary-foreground",
-            "hover:opacity-90",
+            "hover:bg-primary/90",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
           )}
         >
           Allow
@@ -201,9 +207,9 @@ export function CompactPermissionConfirmation({
       <div
         className={cn(
           "csdk-confirm-result",
-          "inline-flex items-center gap-2 px-3 py-1.5 text-sm",
-          "rounded-2xl border border-green-200/70 dark:border-green-900/40",
-          "bg-green-50 dark:bg-green-950/20 text-green-700 dark:text-green-400",
+          "inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium",
+          "rounded-2xl border border-green-200/60 dark:border-green-800/40",
+          "bg-green-50/80 dark:bg-green-950/20 text-green-700 dark:text-green-400",
           className,
         )}
       >
@@ -218,9 +224,9 @@ export function CompactPermissionConfirmation({
       <div
         className={cn(
           "csdk-confirm-result",
-          "inline-flex items-center gap-2 px-3 py-1.5 text-sm",
-          "rounded-2xl border border-red-200/70 dark:border-red-900/40",
-          "bg-red-50 dark:bg-red-950/20 text-red-700 dark:text-red-400",
+          "inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium",
+          "rounded-2xl border border-red-200/60 dark:border-red-800/40",
+          "bg-red-50/80 dark:bg-red-950/20 text-red-700 dark:text-red-400",
           className,
         )}
       >
@@ -234,38 +240,33 @@ export function CompactPermissionConfirmation({
     <div
       className={cn(
         "csdk-confirm-card",
-        "w-full rounded-2xl border border-border/60 bg-card text-card-foreground shadow-sm overflow-hidden",
+        "w-full rounded-2xl overflow-hidden",
+        "border border-amber-200/50 dark:border-amber-900/30",
+        "bg-card text-card-foreground shadow-sm",
         className,
       )}
     >
-      <div className="flex items-start gap-3 p-4">
-        <div className="mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50">
-          <AlertTriangleIcon className="h-3.5 w-3.5 text-amber-600 dark:text-amber-400" />
+      <div className="flex items-start gap-3 p-4 pb-3">
+        <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50 ring-1 ring-amber-200/60 dark:ring-amber-800/40">
+          <AlertTriangleIcon className="h-4 w-4 text-amber-600 dark:text-amber-400" />
         </div>
         <p className="flex-1 min-w-0 pt-0.5 text-sm text-foreground leading-snug">
           {message || "This action requires your approval."}
         </p>
       </div>
 
-      <div className="flex items-center justify-end gap-2 px-4 pb-4">
-        {/* Don't ask again — disabled for now */}
-        {/* <label className="flex items-center gap-2 text-sm text-muted-foreground cursor-pointer mr-auto">
-          <input
-            type="checkbox"
-            checked={rememberChoice}
-            onChange={(e) => setRememberChoice(e.target.checked)}
-            className="rounded border-gray-300"
-          />
-          Don't ask again
-        </label> */}
+      {/* Divider */}
+      <div className="mx-4 border-t border-border/40" />
+
+      <div className="flex items-center justify-end gap-2 px-4 py-3">
         <button
           type="button"
           onClick={handleReject}
           className={cn(
             "csdk-confirm-btn",
             "px-4 py-1.5 text-sm font-medium rounded-xl",
-            "border border-border bg-transparent text-muted-foreground",
-            "hover:bg-muted/60 hover:text-foreground",
+            "border border-border/80 bg-transparent text-muted-foreground",
+            "hover:bg-muted/80 hover:text-foreground hover:border-border",
           )}
         >
           Deny
@@ -277,7 +278,8 @@ export function CompactPermissionConfirmation({
             "csdk-confirm-btn",
             "px-4 py-1.5 text-sm font-medium rounded-xl",
             "bg-primary text-primary-foreground",
-            "hover:opacity-90",
+            "hover:bg-primary/90",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
           )}
         >
           Allow

From 95f659d8da603012b66827282247391ae7ef3ca0 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 14:27:13 +0530
Subject: [PATCH 33/72] docs: css class reference page, sidebar cleanup, csdk-*
 classes on all overlays
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add css-classes.mdx with complete csdk-* class reference
- Remove index duplication and icons from customizations, skills, context dropdowns
- Rename Chat Primitives → UI Primitives
- Add csdk-* classes to all overlays/layers in SDK components
- Fix confirmation card border to use theme-aware border-border/60

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/docs/content/docs/context/compaction.mdx |   1 -
 apps/docs/content/docs/context/meta.json      |   2 +-
 apps/docs/content/docs/context/session.mdx    |   1 -
 .../content/docs/context/token-tracking.mdx   |   1 -
 .../docs/customizations/chat-primitives.mdx   |   3 +-
 .../docs/customizations/css-classes.mdx       | 306 ++++++++++++++++++
 .../customizations/custom-message-view.mdx    |   1 -
 .../content/docs/customizations/index.mdx     |  45 +--
 .../content/docs/customizations/meta.json     |   2 +-
 apps/docs/content/docs/skills/client.mdx      |   1 -
 apps/docs/content/docs/skills/meta.json       |   2 +-
 apps/docs/content/docs/skills/server.mdx      |   1 -
 .../components/composed/chat/chat-welcome.tsx |   4 +-
 .../src/ui/components/composed/chat/chat.tsx  |   8 +-
 .../composed/chat/default-message.tsx         |   4 +-
 .../src/ui/components/ui/confirmation.tsx     |   2 +-
 .../src/ui/components/ui/dev-logger.tsx       |   4 +-
 .../src/ui/components/ui/mcp-ui-frame.tsx     |   2 +-
 .../src/ui/components/ui/model-selector.tsx   |   2 +-
 .../components/ui/permission-confirmation.tsx |   4 +-
 20 files changed, 329 insertions(+), 67 deletions(-)
 create mode 100644 apps/docs/content/docs/customizations/css-classes.mdx

diff --git a/apps/docs/content/docs/context/compaction.mdx b/apps/docs/content/docs/context/compaction.mdx
index 707786e..f384d7f 100644
--- a/apps/docs/content/docs/context/compaction.mdx
+++ b/apps/docs/content/docs/context/compaction.mdx
@@ -1,7 +1,6 @@
 ---
 title: Message History Compaction
 description: Auto-summarize old messages to keep long conversations within the AI's context window
-icon: Archive
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/apps/docs/content/docs/context/meta.json b/apps/docs/content/docs/context/meta.json
index 9a166a7..00cb426 100644
--- a/apps/docs/content/docs/context/meta.json
+++ b/apps/docs/content/docs/context/meta.json
@@ -1,5 +1,5 @@
 {
   "title": "Context Management",
   "icon": "Lightbulb",
-  "pages": ["index", "compaction", "token-tracking", "session"]
+  "pages": ["compaction", "token-tracking", "session"]
 }
diff --git a/apps/docs/content/docs/context/session.mdx b/apps/docs/content/docs/context/session.mdx
index 9f68416..ba5afd5 100644
--- a/apps/docs/content/docs/context/session.mdx
+++ b/apps/docs/content/docs/context/session.mdx
@@ -1,7 +1,6 @@
 ---
 title: Session Persistence
 description: Survive page reloads and persist conversation state across sessions
-icon: HardDrive
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/apps/docs/content/docs/context/token-tracking.mdx b/apps/docs/content/docs/context/token-tracking.mdx
index dc9bed9..50a5c41 100644
--- a/apps/docs/content/docs/context/token-tracking.mdx
+++ b/apps/docs/content/docs/context/token-tracking.mdx
@@ -1,7 +1,6 @@
 ---
 title: Token Tracking
 description: Monitor context window usage in real time with useContextStats
-icon: BarChart2
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/apps/docs/content/docs/customizations/chat-primitives.mdx b/apps/docs/content/docs/customizations/chat-primitives.mdx
index 74a54ec..9ddc722 100644
--- a/apps/docs/content/docs/customizations/chat-primitives.mdx
+++ b/apps/docs/content/docs/customizations/chat-primitives.mdx
@@ -1,7 +1,6 @@
 ---
-title: Chat Primitives
+title: UI Primitives
 description: Headless building blocks for composing fully custom chat UIs
-icon: Layers
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/apps/docs/content/docs/customizations/css-classes.mdx b/apps/docs/content/docs/customizations/css-classes.mdx
new file mode 100644
index 0000000..06f9cda
--- /dev/null
+++ b/apps/docs/content/docs/customizations/css-classes.mdx
@@ -0,0 +1,306 @@
+---
+title: CSS Class Reference
+description: Complete list of all csdk-* CSS classes exposed by the SDK for targeting and customization
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Every structural element in the SDK has a `csdk-*` class. Target any of them in your own CSS to override colors, spacing, borders, animations, or layout — no specificity hacks needed.
+
+<Callout type="info">
+All `csdk-*` classes are **additive only** — they never carry layout-breaking styles on their own. The SDK's visual defaults come from Tailwind utility classes alongside them, which you can override freely.
+</Callout>
+
+---
+
+## Messages
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-message` | Every message row (user + assistant + tool) | Entry animation, row spacing |
+| `csdk-user-message` | User message row wrapper | Row-level alignment |
+| `csdk-assistant-message` | Assistant message row wrapper | Row-level alignment |
+| `csdk-message-user` | User message bubble | Background, border radius, padding |
+| `csdk-message-assistant` | Assistant message bubble | Background, border, padding |
+| `csdk-message-content` | Text content inside a bubble | Font size, line height, color |
+| `csdk-message-actions` | Hover-reveal action button bar | Positioning, visibility timing |
+
+```css
+/* Example: custom user bubble */
+.csdk-message-user {
+  background: linear-gradient(135deg, #6366f1, #8b5cf6);
+  border-radius: 1rem 1rem 0.25rem 1rem;
+}
+
+/* Example: tighten row spacing */
+.csdk-message {
+  margin-bottom: 0.25rem;
+}
+```
+
+---
+
+## Avatars
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-avatar` | Avatar container (user & assistant) | Size, border, shadow |
+| `csdk-avatar-fallback` | Fallback initials shown when no image | Color, font |
+
+```css
+.csdk-avatar {
+  width: 2rem;
+  height: 2rem;
+  border: 2px solid var(--primary);
+}
+```
+
+---
+
+## Input
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-input` | Input container (the whole bar) | Border, background, border-radius |
+| `csdk-input-textarea` | The `<textarea>` inside the input | Font size, color, placeholder style |
+| `csdk-button` | All buttons in the chat | Base button reset |
+| `csdk-button-send` | Send message button | Color, size, icon |
+| `csdk-button-stop` | Stop generation button | Color, icon |
+| `csdk-button-attach` | Attachment picker button | Color, icon |
+| `csdk-compound-input` | Compound input wrapper | Outer border, padding |
+| `csdk-compound-suggestions` | Suggestions dropdown inside compound input | Background, shadow, border |
+
+```css
+/* Example: pill-shaped input */
+.csdk-input {
+  border-radius: 999px;
+  padding: 0.25rem 0.75rem;
+}
+
+/* Example: custom send button color */
+.csdk-button-send {
+  background: #10b981;
+  color: white;
+}
+```
+
+---
+
+## Inline Edit
+
+These appear when a user edits a sent message.
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-edit-btn` | Edit trigger button (hover-reveal, left of message) | Position, opacity timing |
+| `csdk-edit-textarea` | Textarea shown during edit mode | Border, background |
+| `csdk-edit-cancel` | Cancel edit button | Color, border |
+| `csdk-edit-submit` | Submit edit button | Color, background |
+
+```css
+/* Always show edit button instead of hover-only */
+.csdk-edit-btn {
+  opacity: 1 !important;
+}
+```
+
+---
+
+## Confirmation Card
+
+Used for tool approval prompts (`PermissionConfirmation`, `SimpleConfirmation`).
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-confirm-card` | The pending confirmation card | Border, background, border-radius |
+| `csdk-confirm-btn` | Deny / Allow buttons | Padding, border-radius, hover state |
+| `csdk-confirm-result` | Approved / Rejected result pill | Background, border, color |
+
+```css
+/* Example: match your brand on the Allow button */
+.csdk-confirm-btn:last-child {
+  background: #6366f1;
+}
+
+/* Example: custom approved pill */
+.csdk-confirm-result {
+  border-radius: 0.375rem;
+}
+```
+
+---
+
+## Layout
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-chat-header` | Chat view header bar | Height, background, border |
+| `csdk-chat-footer` | Chat view footer area | Background, padding, border |
+| `csdk-chat-home-view` | Home/welcome view container | Background, padding |
+| `csdk-chat-view` | Active conversation view container | Background |
+| `csdk-back-button` | Back / New chat button in header | Size, icon color |
+| `csdk-scroll-btn-layer` | Invisible layer that positions the scroll-to-bottom button | `pointer-events: none` layer — adjust padding to reposition button |
+
+```css
+/* Example: transparent footer */
+.csdk-chat-footer {
+  background: transparent;
+  border-top: none;
+}
+```
+
+---
+
+## Overlays
+
+These are absolutely or fixed-positioned layers. Target them to change colors, z-index, or backdrop styles.
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-image-backdrop` | Fullscreen backdrop behind expanded image | Background color, z-index |
+| `csdk-image-close` | Close button inside the image lightbox | Position, background, size |
+| `csdk-dropzone-overlay` | Drag-and-drop overlay shown while dragging files | Border color, background tint |
+| `csdk-attachment-loading` | Loading overlay on attachment thumbnail | Background opacity |
+| `csdk-attachment-error` | Error overlay on failed attachment | Background tint |
+| `csdk-mcp-loading` | Loading overlay inside an MCP UI frame | Background, z-index |
+
+```css
+/* Example: darker image backdrop */
+.csdk-image-backdrop {
+  background: rgba(0, 0, 0, 0.92);
+}
+
+/* Example: brand-colored drop zone */
+.csdk-dropzone-overlay {
+  background: color-mix(in srgb, var(--primary) 10%, transparent);
+  border-color: var(--primary);
+}
+```
+
+---
+
+## Follow-up Suggestions
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-followup` | Follow-up suggestions container | Layout, spacing, max-width |
+| `csdk-followup-button` | Individual suggestion chip buttons | Color, border, hover state |
+
+```css
+.csdk-followup-button {
+  border-radius: 999px;
+  font-size: 0.75rem;
+}
+```
+
+---
+
+## Navigation
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-branch-navigator` | Branch/version navigator between message variants | Visibility, sizing |
+
+---
+
+## Model Selector
+
+| Class | Element | Example override |
+|---|---|---|
+| `csdk-model-dropdown` | Dropdown list shown when picking a model | Width, max-height, shadow, border |
+
+```css
+.csdk-model-dropdown {
+  border-radius: 0.75rem;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
+}
+```
+
+---
+
+## Dev Tools
+
+These classes are on the `DevLogger` component, which is only rendered in development mode.
+
+| Class | Element |
+|---|---|
+| `csdk-devlogger-backdrop` | Modal backdrop overlay |
+| `csdk-devlogger-modal` | Modal content panel |
+
+---
+
+## CSS Custom Properties
+
+A few SDK-specific CSS variables complement the standard shadcn/ui variables:
+
+| Variable | Default | Used for |
+|---|---|---|
+| `--csdk-link-color` | `#2563eb` (light) / `#60a5fa` (dark) | Hyperlink color inside message content |
+| `--csdk-dialog-foreground` | Inherited from `--foreground` | Text color inside SDK-rendered dialogs |
+| `--csdk-dialog-muted-foreground` | Inherited from `--muted-foreground` | Muted text inside SDK-rendered dialogs |
+
+```css
+:root {
+  --csdk-link-color: #7c3aed; /* purple links */
+}
+```
+
+---
+
+## Animation Classes (Internal)
+
+These classes are applied internally for loader animations. You can target them to adjust timing or disable animations, but they are not intended as customization hooks.
+
+`csdk-spinner-fade` · `csdk-thin-pulse` · `csdk-pulse-dot` · `csdk-bounce-dots` · `csdk-typing` · `csdk-wave` · `csdk-blink` · `csdk-text-blink` · `csdk-shimmer` · `csdk-loading-dots`
+
+```css
+/* Example: disable all SDK loader animations for reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  [class*="csdk-loader"] {
+    animation: none;
+  }
+}
+```
+
+---
+
+## Full Theme Example
+
+Combining CSS variables + class overrides to create a fully custom look:
+
+```css title="themes/my-brand.css"
+[data-csdk-theme="mybrand"] {
+  --primary: hsl(258 90% 60%);
+  --primary-foreground: hsl(0 0% 100%);
+  --background: hsl(258 20% 98%);
+  --border: hsl(258 20% 88%);
+  --radius: 0.75rem;
+  --csdk-link-color: hsl(258 90% 55%);
+}
+
+/* Pill-shaped input */
+[data-csdk-theme="mybrand"] .csdk-input {
+  border-radius: 999px;
+}
+
+/* Gradient user bubbles */
+[data-csdk-theme="mybrand"] .csdk-message-user {
+  background: linear-gradient(135deg, hsl(258 90% 60%), hsl(280 80% 60%));
+  color: white;
+}
+
+/* Rounded suggestion chips */
+[data-csdk-theme="mybrand"] .csdk-followup-button {
+  border-radius: 999px;
+  border-color: hsl(258 60% 80%);
+  color: hsl(258 90% 50%);
+}
+```
+
+```tsx
+import "./themes/my-brand.css";
+
+<div data-csdk-theme="mybrand">
+  <CopilotChat />
+</div>
+```
diff --git a/apps/docs/content/docs/customizations/custom-message-view.mdx b/apps/docs/content/docs/customizations/custom-message-view.mdx
index 840da7c..e6aa1a4 100644
--- a/apps/docs/content/docs/customizations/custom-message-view.mdx
+++ b/apps/docs/content/docs/customizations/custom-message-view.mdx
@@ -1,7 +1,6 @@
 ---
 title: Custom Message View
 description: Full control over how the message list is rendered via the messageView prop
-icon: LayoutList
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/apps/docs/content/docs/customizations/index.mdx b/apps/docs/content/docs/customizations/index.mdx
index 360e05a..e236ed7 100644
--- a/apps/docs/content/docs/customizations/index.mdx
+++ b/apps/docs/content/docs/customizations/index.mdx
@@ -68,47 +68,9 @@ The SDK uses standard shadcn/ui CSS variables. Override these to customize the l
 
 ## Semantic CSS Classes
 
-Target specific components with these CSS classes:
-
-### Message Components
-
-| Class | Element |
-|-------|---------|
-| `csdk-message` | Message container |
-| `csdk-message-user` | User message bubble |
-| `csdk-message-assistant` | Assistant message bubble |
-| `csdk-message-content` | Message text content |
-| `csdk-avatar` | Avatar container |
-
-### Input Components
-
-| Class | Element |
-|-------|---------|
-| `csdk-input` | Input container |
-| `csdk-input-textarea` | Text input field |
-| `csdk-button` | All buttons |
-| `csdk-button-send` | Send button |
-| `csdk-button-stop` | Stop generation button |
-| `csdk-button-attach` | Attachment button |
-
-### Layout Components
-
-| Class | Element |
-|-------|---------|
-| `csdk-chat-header` | Header slot |
-| `csdk-chat-footer` | Footer slot |
-| `csdk-chat-home-view` | Home view container |
-| `csdk-chat-view` | Chat view container |
-| `csdk-back-button` | Back/New chat button |
-
-### Other Components
-
-| Class | Element |
-|-------|---------|
-| `csdk-followup` | Follow-up suggestions container |
-| `csdk-followup-button` | Follow-up suggestion buttons |
-| `csdk-compound-input` | Compound input wrapper |
-| `csdk-compound-suggestions` | Compound suggestions wrapper |
+Every structural element in the SDK exposes a `csdk-*` class for CSS targeting. See the full reference:
+
+➜ [CSS Class Reference](/docs/customizations/css-classes) — complete list of all `csdk-*` classes with descriptions and override examples.
 
 ---
 
@@ -350,6 +312,7 @@ import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
 
 ## Next Steps
 
+- [CSS Class Reference](/docs/customizations/css-classes) - All `csdk-*` classes with override examples
 - [UI Components](/docs/ui) - Pre-built components and themes
 - [Generative UI](/docs/generative-ui) - Render custom components from AI
 - [Chat Primitives](/docs/customizations/chat-primitives) - Headless building blocks
diff --git a/apps/docs/content/docs/customizations/meta.json b/apps/docs/content/docs/customizations/meta.json
index fa00745..df28bea 100644
--- a/apps/docs/content/docs/customizations/meta.json
+++ b/apps/docs/content/docs/customizations/meta.json
@@ -1,5 +1,5 @@
 {
   "title": "Customizations",
   "icon": "Paintbrush",
-  "pages": ["index", "chat-primitives", "custom-message-view"]
+  "pages": ["css-classes", "chat-primitives", "custom-message-view"]
 }
diff --git a/apps/docs/content/docs/skills/client.mdx b/apps/docs/content/docs/skills/client.mdx
index 075e5f3..d255573 100644
--- a/apps/docs/content/docs/skills/client.mdx
+++ b/apps/docs/content/docs/skills/client.mdx
@@ -1,7 +1,6 @@
 ---
 title: Client-side Skills
 description: Register skills from React components using SkillProvider and useSkill
-icon: Monitor
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/apps/docs/content/docs/skills/meta.json b/apps/docs/content/docs/skills/meta.json
index 0eefaaa..0d18a59 100644
--- a/apps/docs/content/docs/skills/meta.json
+++ b/apps/docs/content/docs/skills/meta.json
@@ -1,5 +1,5 @@
 {
   "title": "Skills",
   "icon": "BookOpen",
-  "pages": ["index", "client", "server"]
+  "pages": ["client", "server"]
 }
diff --git a/apps/docs/content/docs/skills/server.mdx b/apps/docs/content/docs/skills/server.mdx
index e293a85..94deec8 100644
--- a/apps/docs/content/docs/skills/server.mdx
+++ b/apps/docs/content/docs/skills/server.mdx
@@ -1,7 +1,6 @@
 ---
 title: Server-side Skills
 description: Load skills from files and URLs on the server with loadSkills()
-icon: Server
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat-welcome.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat-welcome.tsx
index 7c82af9..d0d7550 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat-welcome.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat-welcome.tsx
@@ -376,13 +376,13 @@ export function ChatWelcome({
                 )}
                 {/* Loading overlay */}
                 {att.status === "processing" && (
-                  <div className="absolute inset-0 bg-background/80 rounded-lg flex items-center justify-center">
+                  <div className="csdk-attachment-loading absolute inset-0 bg-background/80 rounded-lg flex items-center justify-center">
                     <Loader variant="dots" size="sm" />
                   </div>
                 )}
                 {/* Error overlay */}
                 {att.status === "error" && (
-                  <div className="absolute inset-0 bg-destructive/20 rounded-lg flex items-center justify-center">
+                  <div className="csdk-attachment-error absolute inset-0 bg-destructive/20 rounded-lg flex items-center justify-center">
                     <span className="text-destructive text-xs">Error</span>
                   </div>
                 )}
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 28a32c7..4ee041d 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -874,7 +874,7 @@ function ChatComponent({
         >
           {/* Drag overlay */}
           {isDragging && (
-            <div className="absolute inset-0 z-50 bg-primary/10 border-2 border-dashed border-primary flex items-center justify-center">
+            <div className="csdk-dropzone-overlay absolute inset-0 z-50 bg-primary/10 border-2 border-dashed border-primary flex items-center justify-center">
               <div className="text-primary font-medium text-lg">
                 Drop files here
               </div>
@@ -1142,7 +1142,7 @@ function ChatComponent({
                   </ChatContainerContent>
 
                   {/* Scroll to bottom button - inside ChatContainerRoot for context, outside ChatContainerContent so it doesn't scroll */}
-                  <div className="absolute inset-0 pointer-events-none z-10 flex items-end justify-end p-4">
+                  <div className="csdk-scroll-btn-layer absolute inset-0 pointer-events-none z-10 flex items-end justify-end p-4">
                     <ScrollButton className="shadow-md pointer-events-auto" />
                   </div>
                 </ChatContainerRoot>
@@ -1197,13 +1197,13 @@ function ChatComponent({
                           )}
                           {/* Loading overlay */}
                           {att.status === "processing" && (
-                            <div className="absolute inset-0 bg-background/80 rounded-lg flex items-center justify-center">
+                            <div className="csdk-attachment-loading absolute inset-0 bg-background/80 rounded-lg flex items-center justify-center">
                               <Loader variant="dots" size="sm" />
                             </div>
                           )}
                           {/* Error overlay */}
                           {att.status === "error" && (
-                            <div className="absolute inset-0 bg-destructive/20 rounded-lg flex items-center justify-center">
+                            <div className="csdk-attachment-error absolute inset-0 bg-destructive/20 rounded-lg flex items-center justify-center">
                               <span className="text-destructive text-xs">
                                 Error
                               </span>
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index cd5752b..f64e3ee 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -974,7 +974,7 @@ function AttachmentPreview({ attachment }: { attachment: MessageAttachment }) {
       {/* Fullscreen modal */}
       {expanded && (
         <div
-          className="fixed inset-0 z-50 flex items-center justify-center bg-black/80"
+          className="csdk-image-backdrop fixed inset-0 z-50 flex items-center justify-center bg-black/80"
           onClick={() => setExpanded(false)}
         >
           <div className="relative max-w-[90vw] max-h-[90vh]">
@@ -985,7 +985,7 @@ function AttachmentPreview({ attachment }: { attachment: MessageAttachment }) {
             />
             <button
               type="button"
-              className="absolute top-2 right-2 bg-white/90 rounded-full p-2 hover:bg-white transition-colors"
+              className="csdk-image-close absolute top-2 right-2 bg-white/90 rounded-full p-2 hover:bg-white transition-colors"
               onClick={(e) => {
                 e.stopPropagation();
                 setExpanded(false);
diff --git a/packages/copilot-sdk/src/ui/components/ui/confirmation.tsx b/packages/copilot-sdk/src/ui/components/ui/confirmation.tsx
index 09128f1..8b03a52 100644
--- a/packages/copilot-sdk/src/ui/components/ui/confirmation.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/confirmation.tsx
@@ -93,7 +93,7 @@ export function Confirmation({
         className={cn(
           "csdk-confirm-card",
           "confirmation rounded-2xl overflow-hidden",
-          "border border-amber-200/50 dark:border-amber-900/30",
+          "border border-border/60",
           "bg-card text-card-foreground shadow-sm",
           className,
         )}
diff --git a/packages/copilot-sdk/src/ui/components/ui/dev-logger.tsx b/packages/copilot-sdk/src/ui/components/ui/dev-logger.tsx
index 35fb8e4..ac600de 100644
--- a/packages/copilot-sdk/src/ui/components/ui/dev-logger.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/dev-logger.tsx
@@ -117,12 +117,12 @@ export function DevLogger({
       {/* Modal Overlay */}
       {isOpen && (
         <div
-          className="fixed inset-0 z-[10000] flex items-center justify-center bg-black/50"
+          className="csdk-devlogger-backdrop fixed inset-0 z-[10000] flex items-center justify-center bg-black/50"
           onClick={() => setIsOpen(false)}
         >
           {/* Modal Content */}
           <div
-            className="bg-background border rounded-lg shadow-xl w-[600px] max-h-[80vh] overflow-hidden"
+            className="csdk-devlogger-modal bg-background border rounded-lg shadow-xl w-[600px] max-h-[80vh] overflow-hidden"
             onClick={(e) => e.stopPropagation()}
           >
             {/* Header */}
diff --git a/packages/copilot-sdk/src/ui/components/ui/mcp-ui-frame.tsx b/packages/copilot-sdk/src/ui/components/ui/mcp-ui-frame.tsx
index 32a987e..76329d6 100644
--- a/packages/copilot-sdk/src/ui/components/ui/mcp-ui-frame.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/mcp-ui-frame.tsx
@@ -206,7 +206,7 @@ export function MCPUIFrame({
 
       {/* Loading overlay */}
       {showLoading && isLoading && (
-        <div className="absolute inset-0 z-10 flex items-center justify-center bg-background/80">
+        <div className="csdk-mcp-loading absolute inset-0 z-10 flex items-center justify-center bg-background/80">
           <Loader variant="dots" size="md" />
         </div>
       )}
diff --git a/packages/copilot-sdk/src/ui/components/ui/model-selector.tsx b/packages/copilot-sdk/src/ui/components/ui/model-selector.tsx
index 95d044e..d9a5844 100644
--- a/packages/copilot-sdk/src/ui/components/ui/model-selector.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/model-selector.tsx
@@ -214,7 +214,7 @@ export function ModelSelector({
       {isOpen && (
         <div
           className={cn(
-            "absolute z-50 top-full left-0 right-0 mt-1",
+            "csdk-model-dropdown absolute z-50 top-full left-0 right-0 mt-1",
             "max-h-[300px] overflow-auto",
             "rounded-md border bg-popover text-popover-foreground shadow-md",
             "animate-in fade-in-0 zoom-in-95",
diff --git a/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx b/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
index 817e51b..3eafae0 100644
--- a/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
@@ -115,7 +115,7 @@ export function PermissionConfirmation({
       className={cn(
         "csdk-confirm-card",
         "w-full rounded-2xl overflow-hidden",
-        "border border-amber-200/50 dark:border-amber-900/30",
+        "border border-border/60",
         "bg-card text-card-foreground shadow-sm",
         className,
       )}
@@ -241,7 +241,7 @@ export function CompactPermissionConfirmation({
       className={cn(
         "csdk-confirm-card",
         "w-full rounded-2xl overflow-hidden",
-        "border border-amber-200/50 dark:border-amber-900/30",
+        "border border-border/60",
         "bg-card text-card-foreground shadow-sm",
         className,
       )}

From 038f5eb66a885cfae7e23a42f90c7a04e0fcafd7 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 14:59:36 +0530
Subject: [PATCH 34/72] fix: preserve message tree chain when inserting
 server-side messages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When the server runs a multi-turn agent loop and returns intermediate
messages via done.messages, those messages were inserted into the
MessageTree without parentId set. This caused them to become orphan
root-level children, which corrupted the active-path walk so subsequent
turns saw a shorter (or wrong) message chain — visibly glitching the
chat history and causing request message counts to drop backwards.

Fix: assign proper parentId chains to messagesToInsert before calling
setMessages, and re-parent the message at the insertion point to chain
from the last inserted message. Applied to both insertion sites in
handleStreamResponse.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/chat/classes/AbstractChat.ts          | 58 ++++++++++++++++---
 1 file changed, 51 insertions(+), 7 deletions(-)

diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 451b7df..6a3ef43 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -1043,10 +1043,26 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
                   break;
                 }
               }
+              // Assign parentIds so inserted messages form a proper chain in the
+              // MessageTree. Without this they become orphan root-level children,
+              // which breaks the active-path walk and causes the visible message
+              // count to drop on subsequent turns.
+              const insertParentId =
+                insertIdx > 0 ? currentMessages[insertIdx - 1].id : undefined;
+              const linkedToInsert = messagesToInsert.map((msg, i) => ({
+                ...msg,
+                parentId: i === 0 ? insertParentId : messagesToInsert[i - 1].id,
+              }));
+              const lastInsertedId =
+                linkedToInsert[linkedToInsert.length - 1].id;
+              // Re-parent the message at insertIdx to chain from the last inserted
+              const updatedCurrent = currentMessages.map((m, idx) =>
+                idx === insertIdx ? { ...m, parentId: lastInsertedId } : m,
+              );
               this.state.setMessages([
-                ...currentMessages.slice(0, insertIdx),
-                ...messagesToInsert,
-                ...currentMessages.slice(insertIdx),
+                ...updatedCurrent.slice(0, insertIdx),
+                ...linkedToInsert,
+                ...updatedCurrent.slice(insertIdx),
               ]);
             }
           }
@@ -1228,12 +1244,40 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
               : -1;
 
             if (currentStreamIndex === -1) {
-              this.state.setMessages([...currentMessages, ...messagesToInsert]);
+              // Append at end — chain from the last existing message
+              const appendParentId =
+                currentMessages.length > 0
+                  ? currentMessages[currentMessages.length - 1].id
+                  : undefined;
+              const linkedToInsert = messagesToInsert.map((msg, i) => ({
+                ...msg,
+                parentId: i === 0 ? appendParentId : messagesToInsert[i - 1].id,
+              }));
+              this.state.setMessages([...currentMessages, ...linkedToInsert]);
             } else {
+              // Insert before the current streaming message — chain from the
+              // message immediately before it, then re-parent the streaming
+              // message to chain from the last inserted.
+              const insertParentId =
+                currentStreamIndex > 0
+                  ? currentMessages[currentStreamIndex - 1].id
+                  : undefined;
+              const linkedToInsert = messagesToInsert.map((msg, i) => ({
+                ...msg,
+                parentId: i === 0 ? insertParentId : messagesToInsert[i - 1].id,
+              }));
+              const lastInsertedId =
+                linkedToInsert[linkedToInsert.length - 1].id;
+              // Re-parent the streaming message to chain from the last inserted
+              const updatedCurrent = currentMessages.map((m, idx) =>
+                idx === currentStreamIndex
+                  ? { ...m, parentId: lastInsertedId }
+                  : m,
+              );
               this.state.setMessages([
-                ...currentMessages.slice(0, currentStreamIndex),
-                ...messagesToInsert,
-                ...currentMessages.slice(currentStreamIndex),
+                ...updatedCurrent.slice(0, currentStreamIndex),
+                ...linkedToInsert,
+                ...updatedCurrent.slice(currentStreamIndex),
               ]);
             }
           }

From 1a36a69bf51d03fb278652a0310740fcba674516 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 15:23:29 +0530
Subject: [PATCH 35/72] fix: chain mid-stream continuation messages to prevent
 history loss
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When the server runs a multi-turn agentic loop (e.g. search_tools →
investigate_response), the stream emits multiple message:start/message:end
pairs. After the first message:end, streamState is set to null. The
subsequent message:start handler created a new assistant message without
a parentId, making it a ROOT-level orphan in the MessageTree.

This caused getVisibleMessages() to pick the orphan as the active path,
completely discarding the prior conversation from every subsequent
buildRequest() call — explaining the "5 messages → 4 messages" regression.

Fix: capture the current leaf (last visible message) before pushing the
new continuation message and set it as the parentId, keeping the full
conversation chain intact.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../copilot-sdk/src/chat/classes/AbstractChat.ts   | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 6a3ef43..bb11fc7 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -941,7 +941,19 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       // Handle message:start after a mid-stream finalization
       if (chunk.type === "message:start" && this.streamState === null) {
         this.debug("message:start after mid-stream end - creating new message");
-        const newMessage = createEmptyAssistantMessage() as T;
+        // Capture the current leaf BEFORE pushing the new message so the
+        // continuation turn is chained as a child in the branch tree.
+        // Without this parentId the new message becomes a ROOT orphan, which
+        // hijacks getVisibleMessages() and wipes the prior conversation from
+        // the active path on every subsequent buildRequest() call.
+        const currentLeaf = this.state.messages;
+        const currentLeafId =
+          currentLeaf.length > 0
+            ? currentLeaf[currentLeaf.length - 1].id
+            : undefined;
+        const newMessage = createEmptyAssistantMessage(undefined, {
+          parentId: currentLeafId,
+        }) as T;
         this.state.pushMessage(newMessage);
         this.streamState = createStreamState(newMessage.id);
         this.callbacks.onMessageStart?.(newMessage.id);

From 4e9f594558a9d19aa68e5642652844bd96fdd0ac Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 17:38:34 +0530
Subject: [PATCH 36/72] fix(sdk): localStorage auto-eviction, success flag,
 metadata preservation

- localStorageAdapter: evict oldest thread on QuotaExceededError instead of logging
- connected-chat: return success: false on error paths; use message.createdAt timestamp
- useInternalThreadManager: preserve thinking and full metadata across thread rebuilds

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../thread/adapters/localStorageAdapter.ts    | 25 ++++++++++++++++---
 .../ui/components/composed/connected-chat.tsx |  9 ++++---
 .../src/ui/hooks/useInternalThreadManager.ts  |  3 +++
 3 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts b/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
index 128db06..f6ea36c 100644
--- a/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
+++ b/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
@@ -201,11 +201,28 @@ function writeStore(storageKey: string, store: CopilotStore): void {
     const serialized = JSON.stringify(store);
     localStorage.setItem(storageKey, serialized);
   } catch (e) {
-    // Handle quota exceeded
     if (e instanceof DOMException && e.name === "QuotaExceededError") {
-      console.error(
-        "[CopilotSDK] localStorage quota exceeded. Consider clearing old threads.",
-      );
+      // Evict the oldest thread and retry once
+      if (store.threads.length > 1) {
+        const evicted = [...store.threads].sort(
+          (a, b) =>
+            new Date(a.updatedAt).getTime() - new Date(b.updatedAt).getTime(),
+        );
+        const trimmed = { ...store, threads: evicted.slice(1) };
+        console.warn(
+          "[CopilotSDK] localStorage quota exceeded — evicting oldest thread:",
+          evicted[0].id,
+        );
+        try {
+          localStorage.setItem(storageKey, JSON.stringify(trimmed));
+        } catch {
+          console.error("[CopilotSDK] localStorage still full after eviction.");
+        }
+      } else {
+        console.error(
+          "[CopilotSDK] localStorage quota exceeded and only one thread remains. Cannot evict.",
+        );
+      }
     } else {
       console.warn("[CopilotSDK] Failed to write store:", e);
     }
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index 8b8662e..7ec5760 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -399,7 +399,7 @@ function CopilotChatBase(
                 } catch {
                   return {
                     ...exec,
-                    result: { success: true, message: resultContent },
+                    result: { success: false, message: resultContent },
                   };
                 }
               }
@@ -424,7 +424,7 @@ function CopilotChatBase(
                 try {
                   result = JSON.parse(resultContent);
                 } catch {
-                  result = { success: true, message: resultContent };
+                  result = { success: false, message: resultContent };
                 }
               }
               let args: Record<string, unknown> = {};
@@ -450,7 +450,10 @@ function CopilotChatBase(
                   ? "completed"
                   : "pending") as ToolExecutionData["status"],
                 result,
-                timestamp: Date.now(), // Historical - use current time
+                timestamp:
+                  m.createdAt instanceof Date
+                    ? m.createdAt.getTime()
+                    : Date.now(),
                 hidden,
               };
             },
diff --git a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
index 7e3d5d0..93c53ed 100644
--- a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
+++ b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
@@ -156,6 +156,9 @@ export function useInternalThreadManager(
           parentId: m.parent_id,
           childrenIds: m.children_ids,
           attachments: m.metadata?.attachments,
+          thinking: m.metadata?.thinking as string | undefined,
+          // Preserve full metadata including citations, toolCallsHidden, toolExecutions, etc.
+          metadata: m.metadata,
         }));
         lastSavedSnapshotRef.current = getMessageSnapshot(uiMessages);
         savingToThreadRef.current = threadId;

From ac2a01183762c37e880524886b3786db00934f6c Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 17:38:40 +0530
Subject: [PATCH 37/72] fix(playground): stable schemas to prevent infinite
 re-render, layout updates

- DashboardTools: move inline JSON schemas to module-level constants (fixes re-render loop)
- DefaultLayout, SaasLayout, SupportLayout, CopilotSidebar: alpha feature updates
- next.config.ts: config update

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../components/playground/CopilotSidebar.tsx  |   5 +
 .../components/playground/DashboardTools.tsx  | 216 ++++++++++--------
 .../playground/layouts/DefaultLayout.tsx      |  10 +-
 .../playground/layouts/SaasLayout.tsx         |   5 +-
 .../playground/layouts/SupportLayout.tsx      |   5 +-
 examples/playground/next.config.ts            |   1 +
 6 files changed, 137 insertions(+), 105 deletions(-)

diff --git a/examples/playground/components/playground/CopilotSidebar.tsx b/examples/playground/components/playground/CopilotSidebar.tsx
index 64c009f..102c3a4 100644
--- a/examples/playground/components/playground/CopilotSidebar.tsx
+++ b/examples/playground/components/playground/CopilotSidebar.tsx
@@ -102,6 +102,11 @@ export function CopilotSidebar({
           systemPrompt={systemPrompt}
           maxIterations={5}
           onError={handleError}
+          messageHistory={
+            alphaConfig.compactionStrategy !== "none"
+              ? { strategy: alphaConfig.compactionStrategy }
+              : undefined
+          }
         >
           <CopilotPanel
             theme={copilotTheme}
diff --git a/examples/playground/components/playground/DashboardTools.tsx b/examples/playground/components/playground/DashboardTools.tsx
index 651908b..70bf99f 100644
--- a/examples/playground/components/playground/DashboardTools.tsx
+++ b/examples/playground/components/playground/DashboardTools.tsx
@@ -40,6 +40,116 @@ function useLatest<T>(value: T) {
   return ref;
 }
 
+// ===========================================
+// Stable schema constants (module-level so references never change between renders)
+// Inline objects inside useTool() create new references every render → infinite loop
+// ===========================================
+
+const COUNTER_SCHEMA = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      enum: ["increment", "decrement", "reset"],
+      description:
+        "The action to perform: increment adds 1, decrement subtracts 1, reset sets to 0",
+    },
+  },
+  required: ["action"],
+} as const;
+
+const PREFERENCE_SCHEMA = {
+  type: "object",
+  properties: {
+    preference: {
+      type: "string",
+      enum: ["dark", "light", "system"],
+      description: "The theme preference: dark, light, or system",
+    },
+  },
+  required: ["preference"],
+} as const;
+
+const NOTIFICATION_SCHEMA = {
+  type: "object",
+  properties: {
+    message: {
+      type: "string",
+      description: "The notification message to display",
+    },
+  },
+  required: ["message"],
+} as const;
+
+const CART_SCHEMA = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      enum: ["add", "remove", "clear"],
+      description:
+        "The cart action: add increases count, remove decreases count, clear empties cart",
+    },
+    count: {
+      type: "number",
+      description:
+        "Number of items to add or remove (defaults to 1 if not specified)",
+    },
+  },
+  required: ["action"],
+} as const;
+
+const NAVIGATION_SCHEMA = {
+  type: "object",
+  properties: {
+    section: {
+      type: "string",
+      enum: ["counter", "cart", "settings", "tools"],
+      description: "The dashboard section to navigate to",
+    },
+  },
+  required: ["section"],
+} as const;
+
+const WEATHER_SCHEMA = {
+  type: "object",
+  properties: {
+    location: {
+      type: "string",
+      description: "City name or location (e.g., 'San Francisco', 'New York')",
+    },
+  },
+  required: ["location"],
+} as const;
+
+const STOCK_SCHEMA = {
+  type: "object",
+  properties: {
+    symbol: {
+      type: "string",
+      description: "Stock ticker symbol (e.g., 'AAPL', 'GOOGL', 'TSLA')",
+    },
+  },
+  required: ["symbol"],
+} as const;
+
+const ANALYTICS_SCHEMA = {
+  type: "object",
+  properties: {
+    event: { type: "string", description: "Event name" },
+    properties: { type: "object", description: "Event properties" },
+  },
+  required: ["event"],
+} as const;
+
+const SEARCH_SCHEMA = {
+  type: "object",
+  properties: {
+    query: { type: "string", description: "Search query" },
+  },
+  required: ["query"],
+} as const;
+
 // ===========================================
 // Individual Tool Components
 // When these unmount, useTool cleanup runs
@@ -60,18 +170,7 @@ function CounterTool({
     name: "updateCounter",
     description:
       "Update the dashboard counter. Use this to increment, decrement, or reset the counter value.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        action: {
-          type: "string",
-          enum: ["increment", "decrement", "reset"],
-          description:
-            "The action to perform: increment adds 1, decrement subtracts 1, reset sets to 0",
-        },
-      },
-      required: ["action"],
-    },
+    inputSchema: COUNTER_SCHEMA,
     handler: async ({
       action,
     }: {
@@ -148,17 +247,7 @@ function PreferenceTool({ actions }: { actions: DashboardActions }) {
     name: "updatePreference",
     description:
       "Update the app theme/preference. Use 'dark' for dark mode, 'light' for light mode, or 'system' for system preference.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        preference: {
-          type: "string",
-          enum: ["dark", "light", "system"],
-          description: "The theme preference: dark, light, or system",
-        },
-      },
-      required: ["preference"],
-    },
+    inputSchema: PREFERENCE_SCHEMA,
     handler: async ({ preference }: { preference: string }) => {
       // Update dashboard state
       actionsRef.current.setPreference(preference);
@@ -214,16 +303,7 @@ function NotificationTool({
     name: "addNotification",
     description:
       "Add a notification message to the dashboard notification queue.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        message: {
-          type: "string",
-          description: "The notification message to display",
-        },
-      },
-      required: ["message"],
-    },
+    inputSchema: NOTIFICATION_SCHEMA,
     handler: async ({ message }: { message: string }) => {
       const queueSize = dashboardStateRef.current.notifications.length + 1;
       actionsRef.current.addNotification(message);
@@ -263,23 +343,7 @@ function CartTool({
     name: "updateCart",
     description:
       "Update shopping cart items. Can add items, remove items, or clear the entire cart.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        action: {
-          type: "string",
-          enum: ["add", "remove", "clear"],
-          description:
-            "The cart action: add increases count, remove decreases count, clear empties cart",
-        },
-        count: {
-          type: "number",
-          description:
-            "Number of items to add or remove (defaults to 1 if not specified)",
-        },
-      },
-      required: ["action"],
-    },
+    inputSchema: CART_SCHEMA,
     handler: async ({
       action,
       count,
@@ -383,17 +447,7 @@ function NavigationTool() {
     description:
       "Navigate to a page section on the dashboard. Use this to help users find features.",
     // hidden: true, // This tool won't show in the chat UI
-    inputSchema: {
-      type: "object",
-      properties: {
-        section: {
-          type: "string",
-          enum: ["counter", "cart", "settings", "tools"],
-          description: "The dashboard section to navigate to",
-        },
-      },
-      required: ["section"],
-    },
+    inputSchema: NAVIGATION_SCHEMA,
     handler: async ({ section }: { section: string }) => {
       // In a real app, this would scroll to or highlight the section
       console.log(`[Hidden Tool] Navigating to: ${section}`);
@@ -435,17 +489,7 @@ function WeatherTool() {
     name: "getWeather",
     description:
       "Get current weather information for a location. Returns temperature, conditions, and forecast.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        location: {
-          type: "string",
-          description:
-            "City name or location (e.g., 'San Francisco', 'New York')",
-        },
-      },
-      required: ["location"],
-    },
+    inputSchema: WEATHER_SCHEMA,
     handler: async ({ location }: { location: string }) => {
       await new Promise((resolve) => setTimeout(resolve, 1000));
       const conditions = ["Sunny", "Partly Cloudy", "Cloudy", "Rainy", "Clear"];
@@ -492,16 +536,7 @@ function StockTool() {
   useTool({
     name: "getStockPrice",
     description: "Get current stock price and market data for a ticker symbol.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        symbol: {
-          type: "string",
-          description: "Stock ticker symbol (e.g., 'AAPL', 'GOOGL', 'TSLA')",
-        },
-      },
-      required: ["symbol"],
-    },
+    inputSchema: STOCK_SCHEMA,
     handler: async ({ symbol }: { symbol: string }) => {
       await new Promise((resolve) => setTimeout(resolve, 1000));
       const basePrice =
@@ -563,14 +598,7 @@ function HiddenAnalyticsTool() {
     description:
       "Track a user interaction event for analytics. Call this silently when users perform notable actions.",
     hidden: true,
-    inputSchema: {
-      type: "object",
-      properties: {
-        event: { type: "string", description: "Event name" },
-        properties: { type: "object", description: "Event properties" },
-      },
-      required: ["event"],
-    },
+    inputSchema: ANALYTICS_SCHEMA,
     handler: async ({
       event,
       properties,
@@ -602,13 +630,7 @@ function DeferredSearchTool() {
       "knowledge",
       "article",
     ],
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Search query" },
-      },
-      required: ["query"],
-    },
+    inputSchema: SEARCH_SCHEMA,
     handler: async ({ query }: { query: string }) => {
       await new Promise((r) => setTimeout(r, 600));
       return {
diff --git a/examples/playground/components/playground/layouts/DefaultLayout.tsx b/examples/playground/components/playground/layouts/DefaultLayout.tsx
index a334a65..79e5592 100644
--- a/examples/playground/components/playground/layouts/DefaultLayout.tsx
+++ b/examples/playground/components/playground/layouts/DefaultLayout.tsx
@@ -15,9 +15,11 @@ export function DefaultLayout({
   loaderVariant,
   alphaConfig,
 }: LayoutProps) {
+  const showEdit =
+    alphaConfig.messageActions.editEnabled || alphaConfig.branchingEnabled;
   const hasAnyAction =
     alphaConfig.messageActions.copyEnabled ||
-    alphaConfig.messageActions.editEnabled ||
+    showEdit ||
     alphaConfig.messageActions.feedbackEnabled;
 
   return (
@@ -30,8 +32,8 @@ export function DefaultLayout({
         className="h-full"
         showHeader
         header={{ name: "AI Copilot" }}
-        showThreadPicker
-        persistence
+        showThreadPicker={alphaConfig.sessionPersistence}
+        persistence={alphaConfig.sessionPersistence || undefined}
         loaderVariant={loaderVariant}
         assistantAvatar={{
           src: "https://api.dicebear.com/7.x/bottts/svg?seed=assistant",
@@ -77,7 +79,7 @@ export function DefaultLayout({
                 )}
               </CopilotChat.MessageActions>
             )}
-            {alphaConfig.messageActions.editEnabled && (
+            {showEdit && (
               <CopilotChat.MessageActions role="user">
                 <CopilotChat.EditAction tooltip="Edit message" />
               </CopilotChat.MessageActions>
diff --git a/examples/playground/components/playground/layouts/SaasLayout.tsx b/examples/playground/components/playground/layouts/SaasLayout.tsx
index d558791..9786072 100644
--- a/examples/playground/components/playground/layouts/SaasLayout.tsx
+++ b/examples/playground/components/playground/layouts/SaasLayout.tsx
@@ -96,7 +96,7 @@ export function SaasLayout({ theme, loaderVariant, alphaConfig }: LayoutProps) {
   return (
     <div className="h-full" data-csdk-theme={effectiveTheme}>
       <CopilotChat.Root
-        persistence
+        persistence={alphaConfig.sessionPersistence || undefined}
         className="h-full"
         showPoweredBy={false}
         loaderVariant={loaderVariant}
@@ -126,7 +126,8 @@ export function SaasLayout({ theme, loaderVariant, alphaConfig }: LayoutProps) {
             )}
           </CopilotChat.MessageActions>
         )}
-        {alphaConfig.messageActions.editEnabled && (
+        {(alphaConfig.messageActions.editEnabled ||
+          alphaConfig.branchingEnabled) && (
           <CopilotChat.MessageActions role="user">
             <CopilotChat.EditAction />
           </CopilotChat.MessageActions>
diff --git a/examples/playground/components/playground/layouts/SupportLayout.tsx b/examples/playground/components/playground/layouts/SupportLayout.tsx
index c4444c4..fd4d8a4 100644
--- a/examples/playground/components/playground/layouts/SupportLayout.tsx
+++ b/examples/playground/components/playground/layouts/SupportLayout.tsx
@@ -196,7 +196,7 @@ export function SupportLayout({
       data-csdk-theme={theme === "default" ? undefined : theme}
     >
       <CopilotChat.Root
-        persistence
+        persistence={alphaConfig.sessionPersistence || undefined}
         className="h-full"
         showPoweredBy={false}
         loaderVariant={loaderVariant}
@@ -226,7 +226,8 @@ export function SupportLayout({
             )}
           </CopilotChat.MessageActions>
         )}
-        {alphaConfig.messageActions.editEnabled && (
+        {(alphaConfig.messageActions.editEnabled ||
+          alphaConfig.branchingEnabled) && (
           <CopilotChat.MessageActions role="user">
             <CopilotChat.EditAction tooltip="Edit message" />
           </CopilotChat.MessageActions>
diff --git a/examples/playground/next.config.ts b/examples/playground/next.config.ts
index e876bad..c2810f7 100644
--- a/examples/playground/next.config.ts
+++ b/examples/playground/next.config.ts
@@ -2,6 +2,7 @@ import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   basePath: "/playground",
+  allowedDevOrigins: ["*.trycloudflare.com"],
 };
 
 export default nextConfig;

From 3629fd254200a358d1d965470703a817dff66b46 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 17:38:47 +0530
Subject: [PATCH 38/72] docs: add agentIteration, success flag guidance,
 localStorage eviction docs; fix husky PATH

- agentic-loop.mdx: document agentIteration tracking, useMessageCheckpoints, allowEdit prop
- frontend-tools.mdx: explain success: false behavior for AI reasoning
- chat-history.mdx: document localStorage auto-eviction on QuotaExceededError
- .husky/pre-commit: add $HOME/.local/bin to PATH (Linux); fix &> to >/dev/null 2>&1 (POSIX sh compat)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .husky/pre-commit                             |  6 +-
 apps/docs/content/docs/chat-history.mdx       | 19 ++++++
 apps/docs/content/docs/tools/agentic-loop.mdx | 59 +++++++++++++++++++
 .../content/docs/tools/frontend-tools.mdx     | 17 ++++++
 4 files changed, 98 insertions(+), 3 deletions(-)

diff --git a/.husky/pre-commit b/.husky/pre-commit
index 5c6a0d8..9af5433 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -3,13 +3,13 @@
 # Gitleaks + Lint-Staged Pre-Commit Hook
 #
 
-# Add homebrew to PATH for non-interactive shells
-export PATH="/opt/homebrew/bin:$PATH"
+# Add common install paths for non-interactive shells (macOS + Linux)
+export PATH="/opt/homebrew/bin:/usr/local/bin:$HOME/.local/bin:$PATH"
 
 echo "🔍 Running Gitleaks to check for secrets..."
 
 # Check if gitleaks is installed
-if ! command -v gitleaks &> /dev/null; then
+if ! command -v gitleaks >/dev/null 2>&1; then
     echo ""
     echo "❌ ERROR: Gitleaks is not installed!"
     echo ""
diff --git a/apps/docs/content/docs/chat-history.mdx b/apps/docs/content/docs/chat-history.mdx
index 9588b84..9061439 100644
--- a/apps/docs/content/docs/chat-history.mdx
+++ b/apps/docs/content/docs/chat-history.mdx
@@ -25,6 +25,25 @@ For simple browser-level persistence without server setup:
 
 Data is stored in localStorage (~5MB limit, single device only).
 
+### Storage quota and auto-eviction
+
+When the browser's localStorage quota is exceeded (typically after many long conversations), the SDK automatically evicts the oldest threads to make room for new ones. The most recent threads are always preserved.
+
+This eviction happens silently — users won't see an error. If you need to monitor or control this behavior, you can listen to the `onStorageEviction` callback:
+
+```tsx
+<CopilotChat
+  persistence={true}
+  onStorageEviction={(evictedThreadIds) => {
+    console.log('Evicted old threads:', evictedThreadIds);
+  }}
+/>
+```
+
+<Callout type="info">
+  Auto-eviction only applies to browser localStorage. Server persistence has no such limit — use it when conversation history must be retained long-term.
+</Callout>
+
 ---
 
 ## Server Persistence
diff --git a/apps/docs/content/docs/tools/agentic-loop.mdx b/apps/docs/content/docs/tools/agentic-loop.mdx
index 2fed6db..216a949 100644
--- a/apps/docs/content/docs/tools/agentic-loop.mdx
+++ b/apps/docs/content/docs/tools/agentic-loop.mdx
@@ -374,6 +374,65 @@ useTools({
 
 ---
 
+## Tracking Iteration Progress
+
+Use `agentIteration` from `useCopilot()` to show which reasoning step the AI is on in real time:
+
+```tsx
+function AgentStatus() {
+  const { isLoading, agentIteration } = useCopilot();
+
+  if (!isLoading) return null;
+
+  return (
+    <div className="text-sm text-muted-foreground">
+      {agentIteration > 0
+        ? `Reasoning... (step ${agentIteration})`
+        : 'Thinking...'}
+    </div>
+  );
+}
+```
+
+`agentIteration` increments by 1 each time the AI completes a tool call and continues reasoning. It resets to `0` at the start of each new user message.
+
+### Checkpoints
+
+`useMessageCheckpoints` lets you save and restore specific points in the conversation — useful for letting users branch off mid-task or undo multi-step AI actions:
+
+```tsx
+import { useMessageCheckpoints } from '@yourgpt/copilot-sdk/react';
+
+function CheckpointControls() {
+  const { saveCheckpoint, restoreCheckpoint, checkpoints } = useMessageCheckpoints();
+
+  return (
+    <div>
+      <button onClick={() => saveCheckpoint('before-bulk-edit')}>
+        Save checkpoint
+      </button>
+      {checkpoints.map((cp) => (
+        <button key={cp.id} onClick={() => restoreCheckpoint(cp.id)}>
+          Restore: {cp.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### Inline Editing
+
+Pass `allowEdit` to `CopilotChat` to let users edit any AI message and re-run from that point:
+
+```tsx
+<CopilotChat allowEdit />
+```
+
+Editing an AI message discards all subsequent messages in the thread and re-sends from the edited content, effectively branching the conversation from that point.
+
+---
+
 ## Callbacks (Advanced)
 
 Listen to agentic loop events:
diff --git a/apps/docs/content/docs/tools/frontend-tools.mdx b/apps/docs/content/docs/tools/frontend-tools.mdx
index d1188dd..6322dac 100644
--- a/apps/docs/content/docs/tools/frontend-tools.mdx
+++ b/apps/docs/content/docs/tools/frontend-tools.mdx
@@ -195,6 +195,23 @@ handler: async ({ query }) => {
 }
 ```
 
+### The `success` flag
+
+The `success` field is read by the AI to decide how to continue reasoning after a tool call. Returning `success: false` tells the AI the tool did not accomplish its goal — it can then retry with different parameters, try an alternative tool, or explain the failure to the user.
+
+```tsx
+// ✅ Good — AI understands what went wrong and can adapt
+return {
+  success: false,
+  error: 'No results found for that date range. Try a wider range.',
+};
+
+// ❌ Avoid — throwing an exception stops the agentic loop entirely
+throw new Error('No results found');
+```
+
+Always include a descriptive `error` string alongside `success: false`. The AI uses this message to reason about its next step, so vague errors like `"Unknown error"` reduce its ability to recover gracefully.
+
 ---
 
 ## Best Practices

From e8e25f6226e4161efe7eb67608a8138e3f8e9bf7 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 17:40:07 +0530
Subject: [PATCH 39/72] revert(husky): restore pre-commit hook to original

Reverts machine-specific PATH and redirect changes pushed by mistake.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .husky/pre-commit | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.husky/pre-commit b/.husky/pre-commit
index 9af5433..e2fc3f1 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -3,13 +3,13 @@
 # Gitleaks + Lint-Staged Pre-Commit Hook
 #
 
-# Add common install paths for non-interactive shells (macOS + Linux)
-export PATH="/opt/homebrew/bin:/usr/local/bin:$HOME/.local/bin:$PATH"
+# Add homebrew to PATH for non-interactive shells
+export PATH="/opt/homebrew/bin:$PATH"
 
 echo "🔍 Running Gitleaks to check for secrets..."
 
 # Check if gitleaks is installed
-if ! command -v gitleaks >/dev/null 2>&1; then
+if ! command -v gitleaks &> /dev/null; then
     echo ""
     echo "❌ ERROR: Gitleaks is not installed!"
     echo ""
@@ -39,4 +39,4 @@ echo "✅ Gitleaks scan passed!"
 echo ""
 
 # Run lint-staged
-pnpm exec lint-staged
\ No newline at end of file
+pnpm exec lint-staged

From 2df493c76accdff177ab077cf526d88d35755b3b Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 22 Mar 2026 17:50:51 +0530
Subject: [PATCH 40/72] feat(chat): enhance streaming experience with
 placeholder messages and pre-created IDs

- Updated AbstractChat to push a placeholder assistant message immediately when streaming is enabled, improving the user experience by reducing blank-state flashes.
- Modified processRequest to accept an optional preCreatedMessageId, allowing for better message handling during streaming.
- Updated UI components to use a consistent muted background for permission confirmation alerts.
- Added CSS for avatar animations in assistant messages to enhance visual feedback during message entry.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../src/chat/classes/AbstractChat.ts          | 32 +++++++++++++++----
 .../components/ui/permission-confirmation.tsx |  4 +--
 packages/copilot-sdk/src/ui/styles/base.css   | 22 +++++++++++++
 3 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index bb11fc7..2a14101 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -228,15 +228,32 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       this.state.status = "submitted";
       this.state.error = undefined;
 
-      // Notify callbacks
+      // For streaming: push placeholder assistant message NOW (before microtask yield)
+      // so the loader appears immediately with zero blank-state flash between user
+      // message submission and the first stream event arriving.
+      let preCreatedMessageId: string | undefined;
+      if (this.config.streaming !== false) {
+        const visibleMessages = this.state.messages;
+        const currentLeafId =
+          visibleMessages.length > 0
+            ? visibleMessages[visibleMessages.length - 1].id
+            : undefined;
+        const preMsg = createEmptyAssistantMessage(undefined, {
+          parentId: currentLeafId,
+        }) as T;
+        this.state.pushMessage(preMsg);
+        preCreatedMessageId = preMsg.id;
+      }
+
+      // Notify callbacks (single batch: user message + status + optional placeholder)
       this.callbacks.onMessagesChange?.(this._allMessages());
       this.callbacks.onStatusChange?.("submitted");
 
       // Yield to allow UI to render loading state (important for non-streaming)
       await Promise.resolve();
 
-      // Send request
-      await this.processRequest();
+      // Send request — pass pre-created ID so processRequest reuses it
+      await this.processRequest({ preCreatedMessageId });
       return true;
     } catch (error) {
       this.handleError(error as Error);
@@ -604,15 +621,18 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
   /**
    * Process a chat request
    */
-  protected async processRequest(): Promise<void> {
+  protected async processRequest(options?: {
+    preCreatedMessageId?: string;
+  }): Promise<void> {
     // Build request
     const request = this.buildRequest();
 
     // For streaming: pre-push an empty assistant message BEFORE the HTTP
     // round-trip so the UI shows a loading bubble immediately (e.g. between
     // tool execution and the continuation stream starting).
-    let preCreatedMessageId: string | undefined;
-    if (this.config.streaming !== false) {
+    // Skip if sendMessage already pushed a placeholder (preCreatedMessageId set).
+    let preCreatedMessageId = options?.preCreatedMessageId;
+    if (this.config.streaming !== false && !preCreatedMessageId) {
       // Use the current leaf (last visible message) as parent so the assistant
       // message is correctly placed as a child in the branch tree.
       const visibleMessages = this.state.messages;
diff --git a/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx b/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
index 3eafae0..929477a 100644
--- a/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/permission-confirmation.tsx
@@ -122,7 +122,7 @@ export function PermissionConfirmation({
     >
       {/* Body */}
       <div className="flex items-start gap-3 p-4 pb-3">
-        <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50 ring-1 ring-amber-200/60 dark:ring-amber-800/40">
+        <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-muted">
           <AlertTriangleIcon className="h-4 w-4 text-amber-600 dark:text-amber-400" />
         </div>
         <div className="flex-1 min-w-0 pt-0.5">
@@ -247,7 +247,7 @@ export function CompactPermissionConfirmation({
       )}
     >
       <div className="flex items-start gap-3 p-4 pb-3">
-        <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-amber-100 dark:bg-amber-950/50 ring-1 ring-amber-200/60 dark:ring-amber-800/40">
+        <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-muted">
           <AlertTriangleIcon className="h-4 w-4 text-amber-600 dark:text-amber-400" />
         </div>
         <p className="flex-1 min-w-0 pt-0.5 text-sm text-foreground leading-snug">
diff --git a/packages/copilot-sdk/src/ui/styles/base.css b/packages/copilot-sdk/src/ui/styles/base.css
index 63da214..75edc29 100644
--- a/packages/copilot-sdk/src/ui/styles/base.css
+++ b/packages/copilot-sdk/src/ui/styles/base.css
@@ -78,6 +78,28 @@
   }
 }
 
+/* Avatar pop-in — independent scale spring, fires alongside the message row entry.
+   Scoped to assistant messages so user-side layout stays clean.
+   The parent .csdk-message handles fade + translateY; this adds a separate scale
+   with a slight spring overshoot so the avatar feels "alive" on arrival. */
+.csdk-assistant-message .csdk-avatar {
+  transform-origin: center;
+  transform: scale(1);
+  transition: transform 320ms cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+
+@starting-style {
+  .csdk-assistant-message .csdk-avatar {
+    transform: scale(0.35);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .csdk-assistant-message .csdk-avatar {
+    transition: none;
+  }
+}
+
 /* Confirmation Card Animations */
 /* Uses @starting-style for reliable first-paint entry in React (more robust than @keyframes) */
 

From 8ef3ec2a893be15fdadf695caaef9660bd242573 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 23 Mar 2026 16:40:39 +0530
Subject: [PATCH 41/72] fix(ui): override link color inside user message bubble
 for visibility

Links inside .csdk-message-user now use --primary-foreground via
a scoped CSS variable override, preventing them from blending into
the primary background color.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/copilot-sdk/src/ui/styles/base.css | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/copilot-sdk/src/ui/styles/base.css b/packages/copilot-sdk/src/ui/styles/base.css
index 75edc29..adbf1e9 100644
--- a/packages/copilot-sdk/src/ui/styles/base.css
+++ b/packages/copilot-sdk/src/ui/styles/base.css
@@ -60,6 +60,11 @@
   }
 }
 
+/* Links inside user message bubble — override link color for visibility on primary background */
+.csdk-message-user {
+  --csdk-link-color: hsl(var(--primary-foreground) / 0.9);
+}
+
 /* Message entrance animation — fires on React DOM mount via @starting-style.
    csdk-message: applied to every message row (user + assistant + tool).
    Consumers can override via .csdk-user-message / .csdk-assistant-message selectors. */

From 5ecd52e3d2c5fb1a52c12a68b641c9078adb6d9e Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 23 Mar 2026 17:00:43 +0530
Subject: [PATCH 42/72] =?UTF-8?q?feat(sdk):=20add=20headless=20primitives?=
 =?UTF-8?q?=20=E2=80=94=20useCopilotEvent=20&=20useMessageMeta?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add onStreamChunk callback to ChatCallbacks, fired for every StreamChunk
  with messageId attached during the streaming loop in AbstractChat
- Add MessageMetaStore — reactive per-message key-value store backed by
  useSyncExternalStore
- Add useCopilotEvent hook — subscribe to raw stream chunks by type or '*',
  handler identity stable via ref pattern
- Add useMessageMeta hook — read/write per-message metadata reactively
- Export all new types and hooks from @yourgpt/copilot-sdk/react
- Add headless docs section (index, use-copilot-event, use-message-meta)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/docs/content/docs/headless/index.mdx     | 192 +++++++++++++++
 apps/docs/content/docs/headless/meta.json     |   5 +
 .../docs/headless/use-copilot-event.mdx       | 176 ++++++++++++++
 .../docs/headless/use-message-meta.mdx        | 230 ++++++++++++++++++
 apps/docs/content/docs/meta.json              |   1 +
 .../src/chat/classes/AbstractChat.ts          |   6 +
 packages/copilot-sdk/src/chat/types/chat.ts   |  11 +
 .../src/react/hooks/useCopilotEvent.ts        |  79 ++++++
 .../src/react/hooks/useMessageMeta.ts         | 101 ++++++++
 packages/copilot-sdk/src/react/index.ts       |  27 ++
 .../src/react/provider/CopilotProvider.tsx    |  98 +++++++-
 11 files changed, 925 insertions(+), 1 deletion(-)
 create mode 100644 apps/docs/content/docs/headless/index.mdx
 create mode 100644 apps/docs/content/docs/headless/meta.json
 create mode 100644 apps/docs/content/docs/headless/use-copilot-event.mdx
 create mode 100644 apps/docs/content/docs/headless/use-message-meta.mdx
 create mode 100644 packages/copilot-sdk/src/react/hooks/useCopilotEvent.ts
 create mode 100644 packages/copilot-sdk/src/react/hooks/useMessageMeta.ts

diff --git a/apps/docs/content/docs/headless/index.mdx b/apps/docs/content/docs/headless/index.mdx
new file mode 100644
index 0000000..3f0e9dc
--- /dev/null
+++ b/apps/docs/content/docs/headless/index.mdx
@@ -0,0 +1,192 @@
+---
+title: Headless Copilot
+description: Build fully custom chat UIs using raw SDK primitives — no built-in components required
+icon: Code
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+The Copilot SDK ships two layers:
+
+| Layer | What it is | When to use |
+|---|---|---|
+| **UI layer** | `<CopilotChat>`, `<CopilotProvider>`, built-in components | Get up and running fast |
+| **Headless layer** | Raw hooks, stream events, per-message state | Build your own UI from scratch |
+
+The headless layer gives you full control — your own message bubbles, your own tool indicators, your own thinking step visualiser, your own artifact previews — without forking or overriding SDK internals.
+
+---
+
+## Philosophy
+
+The headless API follows a **primitives, not patterns** approach. Rather than shipping opinionated hooks like `useThinkingSteps()` that bake in a specific data shape, the SDK exposes two low-level primitives that let you compose anything:
+
+- **[`useCopilotEvent`](/docs/headless/use-copilot-event)** — subscribe to every raw stream chunk as it arrives
+- **[`useMessageMeta`](/docs/headless/use-message-meta)** — a reactive per-message key-value store you shape yourself
+
+With just these two, you can build thinking step trackers, artifact stores, tool progress badges, plan approval flows, clarifying question UIs — entirely in your own code, with your own types.
+
+---
+
+## Architecture
+
+```
+CopilotProvider
+├── sends messages → runtime API
+├── streams chunks → fires onStreamChunk for each
+│     message:delta, thinking:delta, tool:status,
+│     action:start/end, loop:iteration, loop:complete …
+│
+├── useCopilotEvent('thinking:delta', handler)
+│     └── your handler runs for each thinking chunk
+│
+└── useMessageMeta(messageId)
+      └── reactive store — write anything, read anywhere
+```
+
+---
+
+## Getting started
+
+Install the SDK if you haven't already:
+
+```bash
+npm install @yourgpt/copilot-sdk
+```
+
+Wrap your app with `CopilotProvider` as normal — the headless hooks work inside any component under the provider:
+
+```tsx
+import { CopilotProvider } from '@yourgpt/copilot-sdk/react'
+
+export default function App() {
+  return (
+    <CopilotProvider runtimeUrl="/api/copilot">
+      <YourCustomChatUI />
+    </CopilotProvider>
+  )
+}
+```
+
+Then use `useCopilotEvent` and `useMessageMeta` anywhere inside to build whatever you need.
+
+---
+
+## Full example — custom streaming chat
+
+A complete headless chat UI using only SDK primitives:
+
+```tsx
+import {
+  useCopilot,
+  useCopilotEvent,
+  useMessageMeta,
+} from '@yourgpt/copilot-sdk/react'
+
+// ── Message component ─────────────────────────────────────────────
+interface MyMeta {
+  thinkingText?: string
+  toolsRunning?: string[]
+}
+
+function Message({ message }) {
+  // Read custom metadata we wrote during streaming
+  const { meta } = useMessageMeta<MyMeta>(message.id)
+
+  return (
+    <div className={`message ${message.role}`}>
+      {/* Thinking indicator */}
+      {meta.thinkingText && (
+        <div className="thinking">{meta.thinkingText}</div>
+      )}
+
+      {/* Active tool badges */}
+      {meta.toolsRunning?.map(name => (
+        <span key={name} className="tool-badge">⚙ {name}</span>
+      ))}
+
+      {/* Message content */}
+      <p>{message.content}</p>
+    </div>
+  )
+}
+
+// ── Chat component ────────────────────────────────────────────────
+function MyChat() {
+  const { messages, sendMessage, status } = useCopilot()
+  const [input, setInput] = useState('')
+
+  // Track which message is currently streaming
+  const activeMessageId = useRef<string | null>(null)
+
+  // Capture message start
+  useCopilotEvent('message:start', (e) => {
+    activeMessageId.current = e.id
+  })
+
+  // Build thinking text per message
+  const { updateMeta: updateActiveMeta } = useMessageMeta(activeMessageId.current ?? undefined)
+
+  useCopilotEvent('thinking:delta', (e) => {
+    useMessageMeta — see pattern below for per-message writes
+  })
+
+  // Track tool execution
+  useCopilotEvent('action:start', (e) => {
+    if (!e.messageId) return
+    // write to the message's meta store via a child component or ref pattern
+  })
+
+  return (
+    <div>
+      {messages.map(m => <Message key={m.id} message={m} />)}
+      <input value={input} onChange={e => setInput(e.target.value)} />
+      <button onClick={() => sendMessage(input)}>Send</button>
+    </div>
+  )
+}
+```
+
+<Callout type="info">
+For writing metadata from event handlers that fire before a component mounts,
+use the `messageMeta` store directly from `useCopilot()`:
+
+```tsx
+const { messageMeta } = useCopilot()
+useCopilotEvent('thinking:delta', (e) => {
+  messageMeta.updateMeta(e.messageId!, prev => ({
+    ...prev,
+    thinkingText: (prev.thinkingText ?? '') + e.content
+  }))
+})
+```
+</Callout>
+
+---
+
+## Available stream events
+
+| Event | When it fires | Key fields |
+|---|---|---|
+| `message:start` | New assistant message begins | `id` |
+| `message:delta` | Text token arrives | `content`, `messageId` |
+| `message:end` | Message turn complete | `messageId` |
+| `thinking:delta` | Thinking/reasoning token | `content`, `messageId` |
+| `action:start` | Server tool begins | `id`, `name`, `messageId` |
+| `action:args` | Tool args streamed | `id`, `args`, `messageId` |
+| `action:end` | Server tool completes | `id`, `name`, `result`, `messageId` |
+| `tool:status` | Client tool status change | `id`, `name`, `status`, `messageId` |
+| `tool:result` | Client tool result | `id`, `name`, `result`, `messageId` |
+| `source:add` | Knowledge base source cited | `source`, `messageId` |
+| `loop:iteration` | Agent loop step | `iteration`, `maxIterations`, `messageId` |
+| `loop:complete` | Agent loop finished | `iterations`, `maxIterationsReached`, `messageId` |
+| `*` | Every event | (all fields) |
+
+---
+
+## Next steps
+
+- [`useCopilotEvent`](/docs/headless/use-copilot-event) — full API reference and recipes
+- [`useMessageMeta`](/docs/headless/use-message-meta) — full API reference and recipes
+- [Custom Message View](/docs/customizations/custom-message-view) — intercept rendering inside `<CopilotChat>`
+- [Chat Primitives](/docs/customizations/chat-primitives) — lower-level layout components
diff --git a/apps/docs/content/docs/headless/meta.json b/apps/docs/content/docs/headless/meta.json
new file mode 100644
index 0000000..2271489
--- /dev/null
+++ b/apps/docs/content/docs/headless/meta.json
@@ -0,0 +1,5 @@
+{
+  "title": "Headless",
+  "icon": "Code",
+  "pages": ["index", "use-copilot-event", "use-message-meta"]
+}
diff --git a/apps/docs/content/docs/headless/use-copilot-event.mdx b/apps/docs/content/docs/headless/use-copilot-event.mdx
new file mode 100644
index 0000000..1c802b8
--- /dev/null
+++ b/apps/docs/content/docs/headless/use-copilot-event.mdx
@@ -0,0 +1,176 @@
+---
+title: useCopilotEvent
+description: Subscribe to raw stream chunks as they arrive — build any custom real-time UI
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+`useCopilotEvent` subscribes to the raw stream chunks flowing through the SDK pipeline. Every token, tool call, thinking delta, and loop iteration fires an event — your handler decides what to do with it.
+
+```ts
+import { useCopilotEvent } from '@yourgpt/copilot-sdk/react'
+```
+
+---
+
+## Signature
+
+```ts
+function useCopilotEvent<T extends StreamChunkType | '*'>(
+  eventType: T,
+  handler: (chunk: ChunkOfType<T>) => void
+): void
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `eventType` | `StreamChunkType \| '*'` | The event type to listen for, or `'*'` for all |
+| `handler` | `(chunk) => void` | Called for each matching chunk. Handler identity is stable via ref — no re-subscription on re-render |
+
+<Callout type="info">
+The handler is always called with the **latest** version via a ref — you don't need to wrap it in `useCallback`. The hook only resubscribes when `eventType` changes.
+</Callout>
+
+---
+
+## Event types
+
+```ts
+type StreamChunkType =
+  | 'message:start'      // assistant message begins — { id }
+  | 'message:delta'      // text token — { content }
+  | 'message:end'        // message turn complete
+  | 'thinking:delta'     // reasoning token — { content }
+  | 'action:start'       // server tool starts — { id, name, hidden? }
+  | 'action:args'        // server tool args streamed — { id, args }
+  | 'action:end'         // server tool finishes — { id, name, result?, error? }
+  | 'tool:status'        // client tool status — { id, name, status }
+  | 'tool:result'        // client tool result — { id, name, result }
+  | 'source:add'         // knowledge source cited — { source }
+  | 'loop:iteration'     // agent loop step — { iteration, maxIterations }
+  | 'loop:complete'      // agent loop done — { iterations, maxIterationsReached? }
+  | '*'                  // every event
+```
+
+All chunks also include `messageId?: string` — the ID of the assistant message being streamed.
+
+---
+
+## Examples
+
+### Thinking text accumulator
+
+```tsx
+function ThinkingDisplay({ messageId }: { messageId: string }) {
+  const [thinking, setThinking] = useState('')
+
+  useCopilotEvent('thinking:delta', (e) => {
+    if (e.messageId !== messageId) return
+    setThinking(prev => prev + e.content)
+  })
+
+  if (!thinking) return null
+  return <div className="thinking-box">{thinking}</div>
+}
+```
+
+---
+
+### Tool execution badge
+
+Show a live "Searching…" indicator while a tool runs:
+
+```tsx
+function ToolBadge() {
+  const [activeTool, setActiveTool] = useState<string | null>(null)
+
+  useCopilotEvent('action:start', (e) => setActiveTool(e.name))
+  useCopilotEvent('action:end',   (e) => setActiveTool(null))
+
+  if (!activeTool) return null
+  return (
+    <div className="tool-badge">
+      <Spinner /> {activeTool.replace(/_/g, ' ')}
+    </div>
+  )
+}
+```
+
+---
+
+### Agent loop progress bar
+
+```tsx
+function LoopProgress() {
+  const [progress, setProgress] = useState(0)
+
+  useCopilotEvent('loop:iteration', (e) => {
+    setProgress(e.iteration / e.maxIterations)
+  })
+
+  useCopilotEvent('loop:complete', () => setProgress(0))
+
+  if (!progress) return null
+  return <progress value={progress} max={1} />
+}
+```
+
+---
+
+### Artifact tracking
+
+Parse `create_artifact` tool results and store them per message:
+
+```tsx
+function useArtifactTracker() {
+  const { messageMeta } = useCopilot()
+
+  useCopilotEvent('action:end', (e) => {
+    if (e.name !== 'create_artifact' || !e.result || !e.messageId) return
+    messageMeta.updateMeta(e.messageId, prev => ({
+      ...prev,
+      artifacts: [...((prev.artifacts as unknown[]) ?? []), e.result]
+    }))
+  })
+}
+```
+
+---
+
+### Catch-all debug logger
+
+```tsx
+useCopilotEvent('*', (e) => {
+  console.log(`[stream] ${e.type}`, e)
+})
+```
+
+---
+
+### Writing to message meta from event handlers
+
+For writing metadata while streaming (before the message component mounts), use the `messageMeta` store directly from `useCopilot()`:
+
+```tsx
+const { messageMeta } = useCopilot()
+
+useCopilotEvent('thinking:delta', (e) => {
+  if (!e.messageId) return
+  messageMeta.updateMeta(e.messageId, prev => ({
+    ...prev,
+    thinking: ((prev.thinking as string) ?? '') + e.content
+  }))
+})
+```
+
+Then read it in your message component with [`useMessageMeta`](/docs/headless/use-message-meta).
+
+---
+
+## Notes
+
+- Handlers run **synchronously** during the streaming loop — keep them fast. Defer expensive work with `setTimeout` or `startTransition` if needed.
+- The hook is a no-op outside of a `CopilotProvider`.
+- Multiple components can subscribe to the same event type independently.
diff --git a/apps/docs/content/docs/headless/use-message-meta.mdx b/apps/docs/content/docs/headless/use-message-meta.mdx
new file mode 100644
index 0000000..3a5fee0
--- /dev/null
+++ b/apps/docs/content/docs/headless/use-message-meta.mdx
@@ -0,0 +1,230 @@
+---
+title: useMessageMeta
+description: Reactive per-message custom metadata — attach any data to a message ID and react to changes
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+`useMessageMeta` is a reactive per-message key-value store. Attach any shape of data to a message ID — any component reading that message ID will re-render when the data changes.
+
+```ts
+import { useMessageMeta } from '@yourgpt/copilot-sdk/react'
+```
+
+It's the storage layer for the headless system. Pair it with [`useCopilotEvent`](/docs/headless/use-copilot-event) to write data during streaming, then read it in your message components.
+
+---
+
+## Signature
+
+```ts
+function useMessageMeta<T extends Record<string, unknown>>(
+  messageId: string | undefined
+): UseMessageMetaReturn<T>
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `messageId` | `string \| undefined` | The message to attach metadata to. Pass `undefined` for a no-op instance (safe for conditional calls) |
+
+### Returns
+
+```ts
+interface UseMessageMetaReturn<T> {
+  /** Current metadata. Empty object if nothing set yet. */
+  meta: T
+
+  /** Replace metadata entirely */
+  setMeta: (meta: T) => void
+
+  /** Update metadata with an updater function */
+  updateMeta: (updater: (prev: T) => T) => void
+}
+```
+
+---
+
+## Examples
+
+### Thinking steps
+
+Define your own shape — the SDK doesn't dictate it:
+
+```tsx
+interface MyMeta {
+  thinking?: string
+  isThinking?: boolean
+}
+
+// Writer — inside useCopilotEvent handler
+const { messageMeta } = useCopilot()
+
+useCopilotEvent('thinking:delta', (e) => {
+  if (!e.messageId) return
+  messageMeta.updateMeta(e.messageId, prev => ({
+    ...prev,
+    thinking: ((prev.thinking as string) ?? '') + e.content,
+    isThinking: true,
+  }))
+})
+
+useCopilotEvent('message:end', (e) => {
+  messageMeta.updateMeta(e.messageId!, prev => ({
+    ...prev,
+    isThinking: false,
+  }))
+})
+
+// Reader — in your message component
+function AssistantMessage({ message }) {
+  const { meta } = useMessageMeta<MyMeta>(message.id)
+
+  return (
+    <div>
+      {meta.isThinking && <ThinkingIndicator text={meta.thinking} />}
+      <p>{message.content}</p>
+    </div>
+  )
+}
+```
+
+---
+
+### Artifact storage
+
+```tsx
+interface MyMeta {
+  artifacts?: Array<{ type: string; title: string; content: unknown }>
+}
+
+// Writer
+useCopilotEvent('action:end', (e) => {
+  if (e.name !== 'create_artifact' || !e.messageId) return
+  messageMeta.updateMeta(e.messageId, prev => ({
+    ...prev,
+    artifacts: [...((prev.artifacts as unknown[]) ?? []), e.result]
+  }))
+})
+
+// Reader
+function Message({ message }) {
+  const { meta } = useMessageMeta<MyMeta>(message.id)
+
+  return (
+    <div>
+      <p>{message.content}</p>
+      {meta.artifacts?.map((a, i) => (
+        <ArtifactPreview key={i} artifact={a} />
+      ))}
+    </div>
+  )
+}
+```
+
+---
+
+### Plan approval state
+
+```tsx
+interface MyMeta {
+  planStatus?: 'pending' | 'approved' | 'rejected'
+  plan?: { summary: string; steps: Step[] }
+}
+
+// Writer — called from your tool render function
+const { updateMeta } = useMessageMeta<MyMeta>(messageId)
+updateMeta(prev => ({ ...prev, planStatus: 'pending', plan: planData }))
+
+// Reader
+function Message({ message }) {
+  const { meta, updateMeta } = useMessageMeta<MyMeta>(message.id)
+
+  if (meta.planStatus === 'pending') {
+    return (
+      <PlanCard
+        plan={meta.plan}
+        onApprove={() => updateMeta(p => ({ ...p, planStatus: 'approved' }))}
+        onReject={() => updateMeta(p => ({ ...p, planStatus: 'rejected' }))}
+      />
+    )
+  }
+
+  return <p>{message.content}</p>
+}
+```
+
+---
+
+### Tool progress per message
+
+```tsx
+interface MyMeta {
+  activeTools?: Record<string, 'running' | 'done' | 'error'>
+}
+
+useCopilotEvent('action:start', (e) => {
+  if (!e.messageId) return
+  messageMeta.updateMeta(e.messageId, prev => ({
+    ...prev,
+    activeTools: { ...((prev.activeTools as object) ?? {}), [e.name]: 'running' }
+  }))
+})
+
+useCopilotEvent('action:end', (e) => {
+  if (!e.messageId) return
+  messageMeta.updateMeta(e.messageId, prev => ({
+    ...prev,
+    activeTools: {
+      ...((prev.activeTools as object) ?? {}),
+      [e.name]: e.error ? 'error' : 'done'
+    }
+  }))
+})
+
+// Reader
+function Message({ message }) {
+  const { meta } = useMessageMeta<MyMeta>(message.id)
+  const running = Object.entries(meta.activeTools ?? {}).filter(([, v]) => v === 'running')
+
+  return (
+    <div>
+      {running.map(([name]) => <ToolBadge key={name} name={name} />)}
+      <p>{message.content}</p>
+    </div>
+  )
+}
+```
+
+---
+
+## Using `messageMeta` directly
+
+For writing from event handlers (where a hook can't be called), access the store directly from `useCopilot()`:
+
+```tsx
+const { messageMeta } = useCopilot()
+
+// Read
+const meta = messageMeta.getMeta(messageId)
+
+// Write
+messageMeta.setMeta(messageId, { myKey: 'value' })
+
+// Update
+messageMeta.updateMeta(messageId, prev => ({ ...prev, count: (prev.count as number ?? 0) + 1 }))
+```
+
+<Callout type="info">
+`messageMeta` is the same store instance that `useMessageMeta` reads from — writing via `messageMeta.updateMeta()` will cause all `useMessageMeta(messageId)` consumers for that ID to re-render.
+</Callout>
+
+---
+
+## Notes
+
+- `meta` is always an object — never `null` or `undefined`. It starts as `{}`.
+- Metadata is **in-memory only** — it resets when the provider unmounts. For persistence, sync to your own storage inside event handlers.
+- Passing `undefined` as `messageId` returns a no-op instance — safe to call unconditionally.
+- Multiple components can read the same `messageId` — all will re-render on any write.
diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json
index 73201ef..676d8ff 100644
--- a/apps/docs/content/docs/meta.json
+++ b/apps/docs/content/docs/meta.json
@@ -19,6 +19,7 @@
     "server",
     "customizations",
     "generative-ui",
+    "headless",
     "multimodal",
     "---AI---",
     "llm-sdk",
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 2a14101..0b37bdd 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -1176,6 +1176,12 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         }),
       );
 
+      // Fire raw stream chunk callback — powers useCopilotEvent hook
+      this.callbacks.onStreamChunk?.({
+        ...chunk,
+        messageId: assistantMessage.id,
+      });
+
       // Notify delta callback
       if (chunk.type === "message:delta") {
         this.callbacks.onMessageDelta?.(assistantMessage.id, chunk.content);
diff --git a/packages/copilot-sdk/src/chat/types/chat.ts b/packages/copilot-sdk/src/chat/types/chat.ts
index 8070461..318027e 100644
--- a/packages/copilot-sdk/src/chat/types/chat.ts
+++ b/packages/copilot-sdk/src/chat/types/chat.ts
@@ -114,6 +114,17 @@ export interface ChatCallbacks<T extends UIMessage = UIMessage> {
   onServerToolEnd?: (
     info: ServerToolInfo & { result?: unknown; error?: string },
   ) => void;
+  /**
+   * Called for every raw stream chunk as it arrives.
+   * Use this to build custom real-time UI on top of the SDK — e.g. thinking
+   * step parsers, tool progress trackers, loop iteration counters.
+   * The `messageId` field is the ID of the assistant message being streamed.
+   */
+  onStreamChunk?: (
+    chunk: import("../interfaces/ChatTransport").StreamChunk & {
+      messageId?: string;
+    },
+  ) => void;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/react/hooks/useCopilotEvent.ts b/packages/copilot-sdk/src/react/hooks/useCopilotEvent.ts
new file mode 100644
index 0000000..d1e2e9a
--- /dev/null
+++ b/packages/copilot-sdk/src/react/hooks/useCopilotEvent.ts
@@ -0,0 +1,79 @@
+"use client";
+
+/**
+ * useCopilotEvent — subscribe to raw stream events from the SDK
+ *
+ * Gives headless consumers direct access to every chunk that flows through
+ * the streaming pipeline. Use this to build custom real-time UI without
+ * depending on any built-in SDK components.
+ *
+ * @example — custom thinking step parser
+ * ```tsx
+ * useCopilotEvent('thinking:delta', (e) => {
+ *   setThinking(prev => prev + e.content)
+ * })
+ * ```
+ *
+ * @example — tool execution badge
+ * ```tsx
+ * useCopilotEvent('action:start', (e) => setActiveTool(e.name))
+ * useCopilotEvent('action:end',   (e) => setActiveTool(null))
+ * ```
+ *
+ * @example — loop iteration counter
+ * ```tsx
+ * useCopilotEvent('loop:iteration', (e) => {
+ *   setProgress(e.iteration / e.maxIterations)
+ * })
+ * ```
+ *
+ * @example — catch-all (every chunk type)
+ * ```tsx
+ * useCopilotEvent('*', (e) => console.log(e.type, e))
+ * ```
+ */
+
+import { useEffect, useRef } from "react";
+import { useCopilot } from "../provider/CopilotProvider";
+import type { StreamChunkWithMessageId } from "../provider/CopilotProvider";
+import type { StreamChunk } from "../../chat";
+
+// Extract the 'type' discriminant from StreamChunk
+type StreamChunkType = StreamChunk["type"];
+
+// Map from event type → the specific chunk shape for that type
+type ChunkOfType<T extends StreamChunkType | "*"> = T extends "*"
+  ? StreamChunkWithMessageId
+  : Extract<StreamChunk, { type: T }> & { messageId?: string };
+
+/**
+ * Subscribe to a specific stream event type (or all events with '*').
+ *
+ * The handler is called synchronously during streaming — keep it fast.
+ * Handler identity doesn't need to be stable; the hook re-subscribes
+ * automatically when it changes.
+ *
+ * @param eventType - Stream chunk type to listen for, or '*' for all
+ * @param handler   - Callback invoked for each matching chunk
+ */
+export function useCopilotEvent<T extends StreamChunkType | "*">(
+  eventType: T,
+  handler: (chunk: ChunkOfType<T>) => void,
+): void {
+  const { subscribeToStreamEvents } = useCopilot();
+
+  // Always use latest handler without resubscribing
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const unsub = subscribeToStreamEvents((chunk) => {
+      if (eventType === "*" || chunk.type === eventType) {
+        handlerRef.current(chunk as ChunkOfType<T>);
+      }
+    });
+    return unsub;
+    // eventType changes → resubscribe; handler changes → ref updated, no resubscribe
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [subscribeToStreamEvents, eventType]);
+}
diff --git a/packages/copilot-sdk/src/react/hooks/useMessageMeta.ts b/packages/copilot-sdk/src/react/hooks/useMessageMeta.ts
new file mode 100644
index 0000000..03d048c
--- /dev/null
+++ b/packages/copilot-sdk/src/react/hooks/useMessageMeta.ts
@@ -0,0 +1,101 @@
+"use client";
+
+/**
+ * useMessageMeta — reactive per-message custom metadata store
+ *
+ * Attach any data to a message ID and have all components reading that
+ * message ID re-render automatically. The SDK has zero opinion on the shape —
+ * consumers define their own types via the generic parameter.
+ *
+ * This is the companion to useCopilotEvent(): events flow in, you store what
+ * you need here, and your UI reacts.
+ *
+ * @example — store thinking steps parsed from stream events
+ * ```tsx
+ * interface MyMeta {
+ *   thinkingSteps?: ThinkingStep[]
+ *   artifacts?: Artifact[]
+ *   planStatus?: 'pending' | 'approved' | 'rejected'
+ * }
+ *
+ * // Writer — anywhere in your app (e.g. inside useCopilotEvent handler)
+ * const { updateMeta } = useMessageMeta<MyMeta>(messageId)
+ * updateMeta(prev => ({
+ *   ...prev,
+ *   thinkingSteps: [...(prev.thinkingSteps ?? []), newStep]
+ * }))
+ *
+ * // Reader — in your message component
+ * const { meta } = useMessageMeta<MyMeta>(message.id)
+ * const steps = meta.thinkingSteps ?? []
+ * ```
+ *
+ * @example — artifact tracking
+ * ```tsx
+ * useCopilotEvent('action:end', (e) => {
+ *   if (e.name === 'create_artifact' && e.result) {
+ *     updateMeta(e.messageId!, prev => ({
+ *       ...prev,
+ *       artifacts: [...(prev.artifacts ?? []), e.result]
+ *     }))
+ *   }
+ * })
+ * ```
+ */
+
+import { useSyncExternalStore, useCallback } from "react";
+import { useCopilot } from "../provider/CopilotProvider";
+
+export interface UseMessageMetaReturn<T extends Record<string, unknown>> {
+  /** Current metadata for this message. Empty object if nothing set yet. */
+  meta: T;
+  /**
+   * Replace metadata entirely.
+   */
+  setMeta: (meta: T) => void;
+  /**
+   * Merge/update metadata using an updater function.
+   * Receives previous meta, return next meta.
+   */
+  updateMeta: (updater: (prev: T) => T) => void;
+}
+
+/**
+ * Read and write custom metadata for a specific message ID.
+ *
+ * @param messageId - The message to attach metadata to.
+ *                   Pass undefined to get a no-op instance (safe for conditional use).
+ */
+export function useMessageMeta<
+  T extends Record<string, unknown> = Record<string, unknown>,
+>(messageId: string | undefined): UseMessageMetaReturn<T> {
+  const { messageMeta } = useCopilot();
+
+  // Subscribe to store changes — only re-render when this messageId's data changes
+  const meta = useSyncExternalStore(
+    messageMeta.subscribe,
+    () => (messageId ? (messageMeta.getMeta(messageId) as T) : ({} as T)),
+    () => ({}) as T,
+  );
+
+  const setMeta = useCallback(
+    (next: T) => {
+      if (!messageId) return;
+      messageMeta.setMeta(messageId, next as Record<string, unknown>);
+    },
+    [messageMeta, messageId],
+  );
+
+  const updateMeta = useCallback(
+    (updater: (prev: T) => T) => {
+      if (!messageId) return;
+      messageMeta.updateMeta(
+        messageId,
+        (prev) => updater(prev as T) as Record<string, unknown>,
+      );
+    },
+    [messageMeta, messageId],
+  );
+
+  return { meta, setMeta, updateMeta };
+}
diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index 64a66ea..2dc7792 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -265,3 +265,30 @@ export type { ContextUsage, ContextUsagePart } from "../core";
 
 // Branching
 export { MessageTree, type BranchInfo } from "../chat/branching";
+
+// ── Headless primitives ───────────────────────────────────────────────────────
+
+/**
+ * useCopilotEvent — subscribe to raw stream chunks as they arrive.
+ * Build any custom real-time UI (thinking steps, tool badges, loop counters)
+ * without depending on built-in SDK components.
+ */
+export { useCopilotEvent } from "./hooks/useCopilotEvent";
+
+/**
+ * useMessageMeta — reactive per-message custom metadata store.
+ * Attach any shape of data to a message ID; all readers react automatically.
+ * Pair with useCopilotEvent to build thinking steps, artifact tracking,
+ * plan state, or any other per-message feature.
+ */
+export {
+  useMessageMeta,
+  type UseMessageMetaReturn,
+} from "./hooks/useMessageMeta";
+
+// Types for advanced consumers building on top of headless primitives
+export type {
+  StreamChunkWithMessageId,
+  StreamEventHandler,
+  MessageMetaStore,
+} from "./provider/CopilotProvider";
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index df08159..cdebb6c 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -33,7 +33,7 @@ import type { MCPServerConfig } from "../../mcp/types";
 import type { Resolvable } from "../../core/utils/resolvable";
 import { createLogger } from "../../core/utils/logger";
 
-import type { UIMessage, ToolExecution } from "../../chat";
+import type { UIMessage, ToolExecution, StreamChunk } from "../../chat";
 
 import {
   ReactChatWithTools,
@@ -309,6 +309,52 @@ export interface CopilotProviderProps {
   skills?: SkillDefinition[];
 }
 
+// ============================================
+// MessageMetaStore — reactive per-message key-value store
+// ============================================
+
+export type StreamChunkWithMessageId = StreamChunk & { messageId?: string };
+export type StreamEventHandler = (chunk: StreamChunkWithMessageId) => void;
+
+/**
+ * Reactive store for custom per-message metadata.
+ * Powers useMessageMeta() — consumers write any shape they want,
+ * all components reading the same messageId react automatically.
+ */
+export class MessageMetaStore {
+  private store = new Map<string, Record<string, unknown>>();
+  private listeners = new Set<() => void>();
+
+  subscribe = (cb: () => void): (() => void) => {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  };
+
+  getSnapshot = (): Map<string, Record<string, unknown>> => this.store;
+
+  getMeta = (messageId: string): Record<string, unknown> =>
+    this.store.get(messageId) ?? {};
+
+  setMeta = (messageId: string, meta: Record<string, unknown>): void => {
+    this.store.set(messageId, meta);
+    this.listeners.forEach((cb) => cb());
+  };
+
+  updateMeta = (
+    messageId: string,
+    updater: (prev: Record<string, unknown>) => Record<string, unknown>,
+  ): void => {
+    const prev = this.store.get(messageId) ?? {};
+    this.store.set(messageId, updater(prev));
+    this.listeners.forEach((cb) => cb());
+  };
+
+  clear = (): void => {
+    this.store.clear();
+    this.listeners.forEach((cb) => cb());
+  };
+}
+
 export interface CopilotContextValue {
   // Chat state
   messages: UIMessage[];
@@ -396,6 +442,28 @@ export interface CopilotContextValue {
    */
   runtimeUrl: Resolvable<string>;
   toolsConfig?: ToolsConfig;
+
+  // ── Headless primitives ──────────────────────────────────────────────────
+
+  /**
+   * Subscribe to raw stream chunks as they arrive.
+   * Returns an unsubscribe function. Use useCopilotEvent() for the hook API.
+   *
+   * @example
+   * ```ts
+   * const unsub = subscribeToStreamEvents((chunk) => {
+   *   if (chunk.type === 'thinking:delta') { ... }
+   * })
+   * return unsub // cleanup
+   * ```
+   */
+  subscribeToStreamEvents: (handler: StreamEventHandler) => () => void;
+
+  /**
+   * Reactive per-message metadata store.
+   * Use useMessageMeta(messageId) for the hook API.
+   */
+  messageMeta: MessageMetaStore;
 }
 
 // ============================================
@@ -436,6 +504,22 @@ export function CopilotProvider({
   messageHistory,
   skills,
 }: CopilotProviderProps) {
+  // ── Headless primitives ──────────────────────────────────────────────────
+
+  // Stream event listeners — Set of handlers subscribed via useCopilotEvent()
+  const streamListenersRef = useRef<Set<StreamEventHandler>>(new Set());
+
+  const subscribeToStreamEvents = useCallback(
+    (handler: StreamEventHandler): (() => void) => {
+      streamListenersRef.current.add(handler);
+      return () => streamListenersRef.current.delete(handler);
+    },
+    [],
+  );
+
+  // Per-message metadata store — stable instance, never re-created
+  const messageMetaStoreRef = useRef<MessageMetaStore>(new MessageMetaStore());
+
   // Debug logger — scoped to "provider" namespace
   const debugLog = useCallback(
     (action: string, data?: unknown) => {
@@ -522,6 +606,14 @@ export function CopilotProvider({
         onError: (error) => {
           if (error) onError?.(error);
         },
+        onStreamChunk: (chunk) => {
+          // Broadcast to all useCopilotEvent() subscribers
+          if (streamListenersRef.current.size > 0) {
+            for (const handler of streamListenersRef.current) {
+              handler(chunk);
+            }
+          }
+        },
       },
     );
   }
@@ -886,6 +978,10 @@ export function CopilotProvider({
       threadId,
       runtimeUrl,
       toolsConfig,
+
+      // Headless primitives
+      subscribeToStreamEvents,
+      messageMeta: messageMetaStoreRef.current,
     }),
     [
       messages,

From 2437c28b303e7213fa4c3ffac8ed8e95eea73b98 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 23 Mar 2026 17:17:58 +0530
Subject: [PATCH 43/72] docs: trim headless to single flat page, fix
 release/alpha badge mentions

- Consolidate headless docs from 3 pages into one flat headless.mdx
- Remove headless/ folder (no more sidebar dropdown)
- Replace "available in release/alpha" with "in alpha" across 12 doc pages
- Use Layers icon for headless page

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/docs/content/docs/chat/branching.mdx     |   2 +-
 .../content/docs/chat/message-actions.mdx     |   2 +-
 apps/docs/content/docs/context/compaction.mdx |   2 +-
 apps/docs/content/docs/context/session.mdx    |   2 +-
 .../content/docs/context/token-tracking.mdx   |   2 +-
 .../docs/customizations/chat-primitives.mdx   |   2 +-
 .../customizations/custom-message-view.mdx    |   2 +-
 apps/docs/content/docs/headless.mdx           | 145 +++++++++++
 apps/docs/content/docs/headless/index.mdx     | 192 ---------------
 apps/docs/content/docs/headless/meta.json     |   5 -
 .../docs/headless/use-copilot-event.mdx       | 176 --------------
 .../docs/headless/use-message-meta.mdx        | 230 ------------------
 apps/docs/content/docs/skills/client.mdx      |   2 +-
 apps/docs/content/docs/skills/index.mdx       |   2 +-
 apps/docs/content/docs/skills/server.mdx      |   2 +-
 .../content/docs/tools/deferred-tools.mdx     |   2 +-
 apps/docs/content/docs/tools/hidden-tools.mdx |   2 +-
 17 files changed, 157 insertions(+), 615 deletions(-)
 create mode 100644 apps/docs/content/docs/headless.mdx
 delete mode 100644 apps/docs/content/docs/headless/index.mdx
 delete mode 100644 apps/docs/content/docs/headless/meta.json
 delete mode 100644 apps/docs/content/docs/headless/use-copilot-event.mdx
 delete mode 100644 apps/docs/content/docs/headless/use-message-meta.mdx

diff --git a/apps/docs/content/docs/chat/branching.mdx b/apps/docs/content/docs/chat/branching.mdx
index 2f659de..9c0f3d5 100644
--- a/apps/docs/content/docs/chat/branching.mdx
+++ b/apps/docs/content/docs/chat/branching.mdx
@@ -8,7 +8,7 @@ import { Callout } from 'fumadocs-ui/components/callout';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 Edit any user message to create a parallel conversation path, preserving the original. Navigate between variants with `← N/M →` — the same UX as ChatGPT, Claude.ai, and Gemini.
diff --git a/apps/docs/content/docs/chat/message-actions.mdx b/apps/docs/content/docs/chat/message-actions.mdx
index ef6a6ea..2ee635e 100644
--- a/apps/docs/content/docs/chat/message-actions.mdx
+++ b/apps/docs/content/docs/chat/message-actions.mdx
@@ -7,7 +7,7 @@ icon: MousePointerClick
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 A compound component API for registering floating action buttons on chat messages — copy, edit, feedback, or fully custom actions. Actions appear on hover, floating below the message bubble. Declarative, role-based, fully composable.
diff --git a/apps/docs/content/docs/context/compaction.mdx b/apps/docs/content/docs/context/compaction.mdx
index f384d7f..d872699 100644
--- a/apps/docs/content/docs/context/compaction.mdx
+++ b/apps/docs/content/docs/context/compaction.mdx
@@ -7,7 +7,7 @@ import { Callout } from 'fumadocs-ui/components/callout';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 Keep long conversations alive without hitting token limits. The SDK maintains two parallel views of message history — a full display layer for the UI, and a compacted layer sent to the model.
diff --git a/apps/docs/content/docs/context/session.mdx b/apps/docs/content/docs/context/session.mdx
index ba5afd5..9cb70c8 100644
--- a/apps/docs/content/docs/context/session.mdx
+++ b/apps/docs/content/docs/context/session.mdx
@@ -6,7 +6,7 @@ description: Survive page reloads and persist conversation state across sessions
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 Persist the full conversation state — including compaction metadata and message history — across page reloads with zero extra code.
diff --git a/apps/docs/content/docs/context/token-tracking.mdx b/apps/docs/content/docs/context/token-tracking.mdx
index 50a5c41..7e42c80 100644
--- a/apps/docs/content/docs/context/token-tracking.mdx
+++ b/apps/docs/content/docs/context/token-tracking.mdx
@@ -6,7 +6,7 @@ description: Monitor context window usage in real time with useContextStats
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 Monitor how much of the AI's context window is being used — broken down by message history, system prompt, tools, and injected context.
diff --git a/apps/docs/content/docs/customizations/chat-primitives.mdx b/apps/docs/content/docs/customizations/chat-primitives.mdx
index 9ddc722..e8ba49e 100644
--- a/apps/docs/content/docs/customizations/chat-primitives.mdx
+++ b/apps/docs/content/docs/customizations/chat-primitives.mdx
@@ -6,7 +6,7 @@ description: Headless building blocks for composing fully custom chat UIs
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 Low-level building blocks for composing custom chat UIs. The SDK handles all state, streaming, and context — you control the layout.
diff --git a/apps/docs/content/docs/customizations/custom-message-view.mdx b/apps/docs/content/docs/customizations/custom-message-view.mdx
index e6aa1a4..7a3c56f 100644
--- a/apps/docs/content/docs/customizations/custom-message-view.mdx
+++ b/apps/docs/content/docs/customizations/custom-message-view.mdx
@@ -6,7 +6,7 @@ description: Full control over how the message list is rendered via the messageV
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 The `messageView` prop on `<CopilotChat>` intercepts message list rendering. Inject custom UI, conditionally replace messages based on `metadata.type`, or build entirely custom layouts — without touching roles or message history.
diff --git a/apps/docs/content/docs/headless.mdx b/apps/docs/content/docs/headless.mdx
new file mode 100644
index 0000000..40e99fa
--- /dev/null
+++ b/apps/docs/content/docs/headless.mdx
@@ -0,0 +1,145 @@
+---
+title: Headless Copilot
+description: Build fully custom chat UIs using raw SDK primitives — no built-in components required
+icon: Layers
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+The SDK ships two layers. The **headless layer** lets you build your own UI from scratch using two low-level primitives — no built-in components involved.
+
+| Layer | What it is | When to use |
+|---|---|---|
+| UI layer | `<CopilotChat>`, built-in components | Get running fast |
+| **Headless layer** | Raw hooks + stream events | Build your own UI |
+
+---
+
+## Primitives
+
+### `useCopilotEvent`
+
+Subscribe to raw stream chunks as they flow through the pipeline.
+
+```ts
+import { useCopilotEvent } from '@yourgpt/copilot-sdk/react'
+
+function useCopilotEvent<T extends StreamChunkType | '*'>(
+  eventType: T,
+  handler: (chunk: ChunkOfType<T>) => void
+): void
+```
+
+The handler is always called with its **latest** version via a ref — no `useCallback` needed. Resubscribes only when `eventType` changes.
+
+#### Event types
+
+| Event | When | Key fields |
+|---|---|---|
+| `message:start` | New assistant message begins | `id` |
+| `message:delta` | Text token arrives | `content`, `messageId` |
+| `message:end` | Message turn complete | `messageId` |
+| `thinking:delta` | Reasoning token | `content`, `messageId` |
+| `action:start` | Server tool begins | `id`, `name`, `messageId` |
+| `action:args` | Tool args streamed | `id`, `args`, `messageId` |
+| `action:end` | Server tool completes | `id`, `name`, `result`, `messageId` |
+| `tool:status` | Client tool status change | `id`, `name`, `status`, `messageId` |
+| `tool:result` | Client tool result | `id`, `name`, `result`, `messageId` |
+| `source:add` | Knowledge source cited | `source`, `messageId` |
+| `loop:iteration` | Agent loop step | `iteration`, `maxIterations`, `messageId` |
+| `loop:complete` | Agent loop finished | `iterations`, `maxIterationsReached`, `messageId` |
+| `*` | Every event | all fields |
+
+---
+
+### `useMessageMeta`
+
+A reactive per-message key-value store. Attach any shape of data to a message ID — every component reading that ID re-renders on write.
+
+```ts
+import { useMessageMeta } from '@yourgpt/copilot-sdk/react'
+
+function useMessageMeta<T extends Record<string, unknown>>(
+  messageId: string | undefined
+): {
+  meta: T
+  setMeta: (meta: T) => void
+  updateMeta: (updater: (prev: T) => T) => void
+}
+```
+
+Passing `undefined` as `messageId` returns a no-op instance — safe for conditional use. `meta` is always an object, never `null`.
+
+---
+
+## Usage pattern
+
+Write metadata from event handlers, read it in message components:
+
+```tsx
+// 1. Write during streaming — use messageMeta store directly from useCopilot()
+const { messageMeta } = useCopilot()
+
+useCopilotEvent('thinking:delta', (e) => {
+  if (!e.messageId) return
+  messageMeta.updateMeta(e.messageId, prev => ({
+    ...prev,
+    thinking: ((prev.thinking as string) ?? '') + e.content,
+  }))
+})
+
+useCopilotEvent('action:start', (e) => {
+  if (!e.messageId) return
+  messageMeta.updateMeta(e.messageId, prev => ({
+    ...prev,
+    activeTools: { ...(prev.activeTools as object ?? {}), [e.name]: 'running' }
+  }))
+})
+
+// 2. Read in your message component
+interface MyMeta {
+  thinking?: string
+  activeTools?: Record<string, 'running' | 'done'>
+}
+
+function Message({ message }) {
+  const { meta } = useMessageMeta<MyMeta>(message.id)
+
+  return (
+    <div>
+      {meta.thinking && <div className="thinking">{meta.thinking}</div>}
+      {Object.entries(meta.activeTools ?? {})
+        .filter(([, v]) => v === 'running')
+        .map(([name]) => <span key={name}>⚙ {name}</span>)
+      }
+      <p>{message.content}</p>
+    </div>
+  )
+}
+```
+
+<Callout type="info">
+Use `messageMeta` from `useCopilot()` inside event handlers (where React hooks can't be called). Use `useMessageMeta(id)` inside components for reactive reads.
+</Callout>
+
+---
+
+## Direct store access
+
+For non-component code, access the store imperatively:
+
+```tsx
+const { messageMeta } = useCopilot()
+
+messageMeta.getMeta(messageId)
+messageMeta.setMeta(messageId, { key: 'value' })
+messageMeta.updateMeta(messageId, prev => ({ ...prev, count: (prev.count as number ?? 0) + 1 }))
+```
+
+---
+
+## Notes
+
+- Metadata is **in-memory only** — resets when the provider unmounts. Sync to your own storage in event handlers if you need persistence.
+- Multiple components can read the same `messageId` — all re-render on any write.
+- Handlers in `useCopilotEvent` run synchronously during streaming — keep them fast.
diff --git a/apps/docs/content/docs/headless/index.mdx b/apps/docs/content/docs/headless/index.mdx
deleted file mode 100644
index 3f0e9dc..0000000
--- a/apps/docs/content/docs/headless/index.mdx
+++ /dev/null
@@ -1,192 +0,0 @@
----
-title: Headless Copilot
-description: Build fully custom chat UIs using raw SDK primitives — no built-in components required
-icon: Code
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-The Copilot SDK ships two layers:
-
-| Layer | What it is | When to use |
-|---|---|---|
-| **UI layer** | `<CopilotChat>`, `<CopilotProvider>`, built-in components | Get up and running fast |
-| **Headless layer** | Raw hooks, stream events, per-message state | Build your own UI from scratch |
-
-The headless layer gives you full control — your own message bubbles, your own tool indicators, your own thinking step visualiser, your own artifact previews — without forking or overriding SDK internals.
-
----
-
-## Philosophy
-
-The headless API follows a **primitives, not patterns** approach. Rather than shipping opinionated hooks like `useThinkingSteps()` that bake in a specific data shape, the SDK exposes two low-level primitives that let you compose anything:
-
-- **[`useCopilotEvent`](/docs/headless/use-copilot-event)** — subscribe to every raw stream chunk as it arrives
-- **[`useMessageMeta`](/docs/headless/use-message-meta)** — a reactive per-message key-value store you shape yourself
-
-With just these two, you can build thinking step trackers, artifact stores, tool progress badges, plan approval flows, clarifying question UIs — entirely in your own code, with your own types.
-
----
-
-## Architecture
-
-```
-CopilotProvider
-├── sends messages → runtime API
-├── streams chunks → fires onStreamChunk for each
-│     message:delta, thinking:delta, tool:status,
-│     action:start/end, loop:iteration, loop:complete …
-│
-├── useCopilotEvent('thinking:delta', handler)
-│     └── your handler runs for each thinking chunk
-│
-└── useMessageMeta(messageId)
-      └── reactive store — write anything, read anywhere
-```
-
----
-
-## Getting started
-
-Install the SDK if you haven't already:
-
-```bash
-npm install @yourgpt/copilot-sdk
-```
-
-Wrap your app with `CopilotProvider` as normal — the headless hooks work inside any component under the provider:
-
-```tsx
-import { CopilotProvider } from '@yourgpt/copilot-sdk/react'
-
-export default function App() {
-  return (
-    <CopilotProvider runtimeUrl="/api/copilot">
-      <YourCustomChatUI />
-    </CopilotProvider>
-  )
-}
-```
-
-Then use `useCopilotEvent` and `useMessageMeta` anywhere inside to build whatever you need.
-
----
-
-## Full example — custom streaming chat
-
-A complete headless chat UI using only SDK primitives:
-
-```tsx
-import {
-  useCopilot,
-  useCopilotEvent,
-  useMessageMeta,
-} from '@yourgpt/copilot-sdk/react'
-
-// ── Message component ─────────────────────────────────────────────
-interface MyMeta {
-  thinkingText?: string
-  toolsRunning?: string[]
-}
-
-function Message({ message }) {
-  // Read custom metadata we wrote during streaming
-  const { meta } = useMessageMeta<MyMeta>(message.id)
-
-  return (
-    <div className={`message ${message.role}`}>
-      {/* Thinking indicator */}
-      {meta.thinkingText && (
-        <div className="thinking">{meta.thinkingText}</div>
-      )}
-
-      {/* Active tool badges */}
-      {meta.toolsRunning?.map(name => (
-        <span key={name} className="tool-badge">⚙ {name}</span>
-      ))}
-
-      {/* Message content */}
-      <p>{message.content}</p>
-    </div>
-  )
-}
-
-// ── Chat component ────────────────────────────────────────────────
-function MyChat() {
-  const { messages, sendMessage, status } = useCopilot()
-  const [input, setInput] = useState('')
-
-  // Track which message is currently streaming
-  const activeMessageId = useRef<string | null>(null)
-
-  // Capture message start
-  useCopilotEvent('message:start', (e) => {
-    activeMessageId.current = e.id
-  })
-
-  // Build thinking text per message
-  const { updateMeta: updateActiveMeta } = useMessageMeta(activeMessageId.current ?? undefined)
-
-  useCopilotEvent('thinking:delta', (e) => {
-    useMessageMeta — see pattern below for per-message writes
-  })
-
-  // Track tool execution
-  useCopilotEvent('action:start', (e) => {
-    if (!e.messageId) return
-    // write to the message's meta store via a child component or ref pattern
-  })
-
-  return (
-    <div>
-      {messages.map(m => <Message key={m.id} message={m} />)}
-      <input value={input} onChange={e => setInput(e.target.value)} />
-      <button onClick={() => sendMessage(input)}>Send</button>
-    </div>
-  )
-}
-```
-
-<Callout type="info">
-For writing metadata from event handlers that fire before a component mounts,
-use the `messageMeta` store directly from `useCopilot()`:
-
-```tsx
-const { messageMeta } = useCopilot()
-useCopilotEvent('thinking:delta', (e) => {
-  messageMeta.updateMeta(e.messageId!, prev => ({
-    ...prev,
-    thinkingText: (prev.thinkingText ?? '') + e.content
-  }))
-})
-```
-</Callout>
-
----
-
-## Available stream events
-
-| Event | When it fires | Key fields |
-|---|---|---|
-| `message:start` | New assistant message begins | `id` |
-| `message:delta` | Text token arrives | `content`, `messageId` |
-| `message:end` | Message turn complete | `messageId` |
-| `thinking:delta` | Thinking/reasoning token | `content`, `messageId` |
-| `action:start` | Server tool begins | `id`, `name`, `messageId` |
-| `action:args` | Tool args streamed | `id`, `args`, `messageId` |
-| `action:end` | Server tool completes | `id`, `name`, `result`, `messageId` |
-| `tool:status` | Client tool status change | `id`, `name`, `status`, `messageId` |
-| `tool:result` | Client tool result | `id`, `name`, `result`, `messageId` |
-| `source:add` | Knowledge base source cited | `source`, `messageId` |
-| `loop:iteration` | Agent loop step | `iteration`, `maxIterations`, `messageId` |
-| `loop:complete` | Agent loop finished | `iterations`, `maxIterationsReached`, `messageId` |
-| `*` | Every event | (all fields) |
-
----
-
-## Next steps
-
-- [`useCopilotEvent`](/docs/headless/use-copilot-event) — full API reference and recipes
-- [`useMessageMeta`](/docs/headless/use-message-meta) — full API reference and recipes
-- [Custom Message View](/docs/customizations/custom-message-view) — intercept rendering inside `<CopilotChat>`
-- [Chat Primitives](/docs/customizations/chat-primitives) — lower-level layout components
diff --git a/apps/docs/content/docs/headless/meta.json b/apps/docs/content/docs/headless/meta.json
deleted file mode 100644
index 2271489..0000000
--- a/apps/docs/content/docs/headless/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
-  "title": "Headless",
-  "icon": "Code",
-  "pages": ["index", "use-copilot-event", "use-message-meta"]
-}
diff --git a/apps/docs/content/docs/headless/use-copilot-event.mdx b/apps/docs/content/docs/headless/use-copilot-event.mdx
deleted file mode 100644
index 1c802b8..0000000
--- a/apps/docs/content/docs/headless/use-copilot-event.mdx
+++ /dev/null
@@ -1,176 +0,0 @@
----
-title: useCopilotEvent
-description: Subscribe to raw stream chunks as they arrive — build any custom real-time UI
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-`useCopilotEvent` subscribes to the raw stream chunks flowing through the SDK pipeline. Every token, tool call, thinking delta, and loop iteration fires an event — your handler decides what to do with it.
-
-```ts
-import { useCopilotEvent } from '@yourgpt/copilot-sdk/react'
-```
-
----
-
-## Signature
-
-```ts
-function useCopilotEvent<T extends StreamChunkType | '*'>(
-  eventType: T,
-  handler: (chunk: ChunkOfType<T>) => void
-): void
-```
-
-### Parameters
-
-| Parameter | Type | Description |
-|---|---|---|
-| `eventType` | `StreamChunkType \| '*'` | The event type to listen for, or `'*'` for all |
-| `handler` | `(chunk) => void` | Called for each matching chunk. Handler identity is stable via ref — no re-subscription on re-render |
-
-<Callout type="info">
-The handler is always called with the **latest** version via a ref — you don't need to wrap it in `useCallback`. The hook only resubscribes when `eventType` changes.
-</Callout>
-
----
-
-## Event types
-
-```ts
-type StreamChunkType =
-  | 'message:start'      // assistant message begins — { id }
-  | 'message:delta'      // text token — { content }
-  | 'message:end'        // message turn complete
-  | 'thinking:delta'     // reasoning token — { content }
-  | 'action:start'       // server tool starts — { id, name, hidden? }
-  | 'action:args'        // server tool args streamed — { id, args }
-  | 'action:end'         // server tool finishes — { id, name, result?, error? }
-  | 'tool:status'        // client tool status — { id, name, status }
-  | 'tool:result'        // client tool result — { id, name, result }
-  | 'source:add'         // knowledge source cited — { source }
-  | 'loop:iteration'     // agent loop step — { iteration, maxIterations }
-  | 'loop:complete'      // agent loop done — { iterations, maxIterationsReached? }
-  | '*'                  // every event
-```
-
-All chunks also include `messageId?: string` — the ID of the assistant message being streamed.
-
----
-
-## Examples
-
-### Thinking text accumulator
-
-```tsx
-function ThinkingDisplay({ messageId }: { messageId: string }) {
-  const [thinking, setThinking] = useState('')
-
-  useCopilotEvent('thinking:delta', (e) => {
-    if (e.messageId !== messageId) return
-    setThinking(prev => prev + e.content)
-  })
-
-  if (!thinking) return null
-  return <div className="thinking-box">{thinking}</div>
-}
-```
-
----
-
-### Tool execution badge
-
-Show a live "Searching…" indicator while a tool runs:
-
-```tsx
-function ToolBadge() {
-  const [activeTool, setActiveTool] = useState<string | null>(null)
-
-  useCopilotEvent('action:start', (e) => setActiveTool(e.name))
-  useCopilotEvent('action:end',   (e) => setActiveTool(null))
-
-  if (!activeTool) return null
-  return (
-    <div className="tool-badge">
-      <Spinner /> {activeTool.replace(/_/g, ' ')}
-    </div>
-  )
-}
-```
-
----
-
-### Agent loop progress bar
-
-```tsx
-function LoopProgress() {
-  const [progress, setProgress] = useState(0)
-
-  useCopilotEvent('loop:iteration', (e) => {
-    setProgress(e.iteration / e.maxIterations)
-  })
-
-  useCopilotEvent('loop:complete', () => setProgress(0))
-
-  if (!progress) return null
-  return <progress value={progress} max={1} />
-}
-```
-
----
-
-### Artifact tracking
-
-Parse `create_artifact` tool results and store them per message:
-
-```tsx
-function useArtifactTracker() {
-  const { messageMeta } = useCopilot()
-
-  useCopilotEvent('action:end', (e) => {
-    if (e.name !== 'create_artifact' || !e.result || !e.messageId) return
-    messageMeta.updateMeta(e.messageId, prev => ({
-      ...prev,
-      artifacts: [...((prev.artifacts as unknown[]) ?? []), e.result]
-    }))
-  })
-}
-```
-
----
-
-### Catch-all debug logger
-
-```tsx
-useCopilotEvent('*', (e) => {
-  console.log(`[stream] ${e.type}`, e)
-})
-```
-
----
-
-### Writing to message meta from event handlers
-
-For writing metadata while streaming (before the message component mounts), use the `messageMeta` store directly from `useCopilot()`:
-
-```tsx
-const { messageMeta } = useCopilot()
-
-useCopilotEvent('thinking:delta', (e) => {
-  if (!e.messageId) return
-  messageMeta.updateMeta(e.messageId, prev => ({
-    ...prev,
-    thinking: ((prev.thinking as string) ?? '') + e.content
-  }))
-})
-```
-
-Then read it in your message component with [`useMessageMeta`](/docs/headless/use-message-meta).
-
----
-
-## Notes
-
-- Handlers run **synchronously** during the streaming loop — keep them fast. Defer expensive work with `setTimeout` or `startTransition` if needed.
-- The hook is a no-op outside of a `CopilotProvider`.
-- Multiple components can subscribe to the same event type independently.
diff --git a/apps/docs/content/docs/headless/use-message-meta.mdx b/apps/docs/content/docs/headless/use-message-meta.mdx
deleted file mode 100644
index 3a5fee0..0000000
--- a/apps/docs/content/docs/headless/use-message-meta.mdx
+++ /dev/null
@@ -1,230 +0,0 @@
----
-title: useMessageMeta
-description: Reactive per-message custom metadata — attach any data to a message ID and react to changes
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-`useMessageMeta` is a reactive per-message key-value store. Attach any shape of data to a message ID — any component reading that message ID will re-render when the data changes.
-
-```ts
-import { useMessageMeta } from '@yourgpt/copilot-sdk/react'
-```
-
-It's the storage layer for the headless system. Pair it with [`useCopilotEvent`](/docs/headless/use-copilot-event) to write data during streaming, then read it in your message components.
-
----
-
-## Signature
-
-```ts
-function useMessageMeta<T extends Record<string, unknown>>(
-  messageId: string | undefined
-): UseMessageMetaReturn<T>
-```
-
-### Parameters
-
-| Parameter | Type | Description |
-|---|---|---|
-| `messageId` | `string \| undefined` | The message to attach metadata to. Pass `undefined` for a no-op instance (safe for conditional calls) |
-
-### Returns
-
-```ts
-interface UseMessageMetaReturn<T> {
-  /** Current metadata. Empty object if nothing set yet. */
-  meta: T
-
-  /** Replace metadata entirely */
-  setMeta: (meta: T) => void
-
-  /** Update metadata with an updater function */
-  updateMeta: (updater: (prev: T) => T) => void
-}
-```
-
----
-
-## Examples
-
-### Thinking steps
-
-Define your own shape — the SDK doesn't dictate it:
-
-```tsx
-interface MyMeta {
-  thinking?: string
-  isThinking?: boolean
-}
-
-// Writer — inside useCopilotEvent handler
-const { messageMeta } = useCopilot()
-
-useCopilotEvent('thinking:delta', (e) => {
-  if (!e.messageId) return
-  messageMeta.updateMeta(e.messageId, prev => ({
-    ...prev,
-    thinking: ((prev.thinking as string) ?? '') + e.content,
-    isThinking: true,
-  }))
-})
-
-useCopilotEvent('message:end', (e) => {
-  messageMeta.updateMeta(e.messageId!, prev => ({
-    ...prev,
-    isThinking: false,
-  }))
-})
-
-// Reader — in your message component
-function AssistantMessage({ message }) {
-  const { meta } = useMessageMeta<MyMeta>(message.id)
-
-  return (
-    <div>
-      {meta.isThinking && <ThinkingIndicator text={meta.thinking} />}
-      <p>{message.content}</p>
-    </div>
-  )
-}
-```
-
----
-
-### Artifact storage
-
-```tsx
-interface MyMeta {
-  artifacts?: Array<{ type: string; title: string; content: unknown }>
-}
-
-// Writer
-useCopilotEvent('action:end', (e) => {
-  if (e.name !== 'create_artifact' || !e.messageId) return
-  messageMeta.updateMeta(e.messageId, prev => ({
-    ...prev,
-    artifacts: [...((prev.artifacts as unknown[]) ?? []), e.result]
-  }))
-})
-
-// Reader
-function Message({ message }) {
-  const { meta } = useMessageMeta<MyMeta>(message.id)
-
-  return (
-    <div>
-      <p>{message.content}</p>
-      {meta.artifacts?.map((a, i) => (
-        <ArtifactPreview key={i} artifact={a} />
-      ))}
-    </div>
-  )
-}
-```
-
----
-
-### Plan approval state
-
-```tsx
-interface MyMeta {
-  planStatus?: 'pending' | 'approved' | 'rejected'
-  plan?: { summary: string; steps: Step[] }
-}
-
-// Writer — called from your tool render function
-const { updateMeta } = useMessageMeta<MyMeta>(messageId)
-updateMeta(prev => ({ ...prev, planStatus: 'pending', plan: planData }))
-
-// Reader
-function Message({ message }) {
-  const { meta, updateMeta } = useMessageMeta<MyMeta>(message.id)
-
-  if (meta.planStatus === 'pending') {
-    return (
-      <PlanCard
-        plan={meta.plan}
-        onApprove={() => updateMeta(p => ({ ...p, planStatus: 'approved' }))}
-        onReject={() => updateMeta(p => ({ ...p, planStatus: 'rejected' }))}
-      />
-    )
-  }
-
-  return <p>{message.content}</p>
-}
-```
-
----
-
-### Tool progress per message
-
-```tsx
-interface MyMeta {
-  activeTools?: Record<string, 'running' | 'done' | 'error'>
-}
-
-useCopilotEvent('action:start', (e) => {
-  if (!e.messageId) return
-  messageMeta.updateMeta(e.messageId, prev => ({
-    ...prev,
-    activeTools: { ...((prev.activeTools as object) ?? {}), [e.name]: 'running' }
-  }))
-})
-
-useCopilotEvent('action:end', (e) => {
-  if (!e.messageId) return
-  messageMeta.updateMeta(e.messageId, prev => ({
-    ...prev,
-    activeTools: {
-      ...((prev.activeTools as object) ?? {}),
-      [e.name]: e.error ? 'error' : 'done'
-    }
-  }))
-})
-
-// Reader
-function Message({ message }) {
-  const { meta } = useMessageMeta<MyMeta>(message.id)
-  const running = Object.entries(meta.activeTools ?? {}).filter(([, v]) => v === 'running')
-
-  return (
-    <div>
-      {running.map(([name]) => <ToolBadge key={name} name={name} />)}
-      <p>{message.content}</p>
-    </div>
-  )
-}
-```
-
----
-
-## Using `messageMeta` directly
-
-For writing from event handlers (where a hook can't be called), access the store directly from `useCopilot()`:
-
-```tsx
-const { messageMeta } = useCopilot()
-
-// Read
-const meta = messageMeta.getMeta(messageId)
-
-// Write
-messageMeta.setMeta(messageId, { myKey: 'value' })
-
-// Update
-messageMeta.updateMeta(messageId, prev => ({ ...prev, count: (prev.count as number ?? 0) + 1 }))
-```
-
-<Callout type="info">
-`messageMeta` is the same store instance that `useMessageMeta` reads from — writing via `messageMeta.updateMeta()` will cause all `useMessageMeta(messageId)` consumers for that ID to re-render.
-</Callout>
-
----
-
-## Notes
-
-- `meta` is always an object — never `null` or `undefined`. It starts as `{}`.
-- Metadata is **in-memory only** — it resets when the provider unmounts. For persistence, sync to your own storage inside event handlers.
-- Passing `undefined` as `messageId` returns a no-op instance — safe to call unconditionally.
-- Multiple components can read the same `messageId` — all will re-render on any write.
diff --git a/apps/docs/content/docs/skills/client.mdx b/apps/docs/content/docs/skills/client.mdx
index d255573..392a358 100644
--- a/apps/docs/content/docs/skills/client.mdx
+++ b/apps/docs/content/docs/skills/client.mdx
@@ -6,7 +6,7 @@ description: Register skills from React components using SkillProvider and useSk
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 Register skills from your React app using `<SkillProvider>`, `useSkill`, and `defineSkill`.
diff --git a/apps/docs/content/docs/skills/index.mdx b/apps/docs/content/docs/skills/index.mdx
index 53d24ee..ec4afb3 100644
--- a/apps/docs/content/docs/skills/index.mdx
+++ b/apps/docs/content/docs/skills/index.mdx
@@ -7,7 +7,7 @@ icon: BookOpen
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 Skills are instruction playbooks the AI loads on demand. They shape the model's **behavior** — separate from [Tools](/docs/tools), which perform actions.
diff --git a/apps/docs/content/docs/skills/server.mdx b/apps/docs/content/docs/skills/server.mdx
index 94deec8..817d532 100644
--- a/apps/docs/content/docs/skills/server.mdx
+++ b/apps/docs/content/docs/skills/server.mdx
@@ -6,7 +6,7 @@ description: Load skills from files and URLs on the server with loadSkills()
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 For `file` and `url` skill sources, or when you need server-controlled skill loading, use `loadSkills()` in your API route.
diff --git a/apps/docs/content/docs/tools/deferred-tools.mdx b/apps/docs/content/docs/tools/deferred-tools.mdx
index f6fd6aa..7828c0e 100644
--- a/apps/docs/content/docs/tools/deferred-tools.mdx
+++ b/apps/docs/content/docs/tools/deferred-tools.mdx
@@ -7,7 +7,7 @@ icon: Clock
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 Large tool registries bloat the LLM request payload and consume valuable context tokens. Mark tools with `deferLoading: true` to exclude them from the default request — they are auto-injected only when the user's query semantically matches the tool.
diff --git a/apps/docs/content/docs/tools/hidden-tools.mdx b/apps/docs/content/docs/tools/hidden-tools.mdx
index 205ca52..0751e1c 100644
--- a/apps/docs/content/docs/tools/hidden-tools.mdx
+++ b/apps/docs/content/docs/tools/hidden-tools.mdx
@@ -7,7 +7,7 @@ icon: EyeOff
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is available in `release/alpha`. APIs may change before stable release.
+**Beta** — This feature is in **alpha**. APIs may change before stable release.
 </Callout>
 
 ---

From 8a0307dca7c0b7516dc77ce0138729ef3ba19460 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 23 Mar 2026 17:32:27 +0530
Subject: [PATCH 44/72] fix(sdk): stable snapshot reference in useMessageMeta
 to prevent infinite re-render
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- MessageMetaStore.getMeta returns a static EMPTY sentinel instead of
  creating a new {} on every call for unknown message IDs
- useMessageMeta getSnapshot uses a module-level EMPTY_META constant
  instead of {} as T — fixes "getSnapshot should be cached" warning
  and Maximum update depth exceeded crash

feat(examples): add headless-slack-demo — Vite + React Slack-like chat
using useCopilotEvent + useMessageMeta headless primitives

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/headless-slack-demo/.env.example     |   1 +
 examples/headless-slack-demo/index.html       |  12 ++
 examples/headless-slack-demo/package.json     |  37 +++++
 .../headless-slack-demo/postcss.config.mjs    |   5 +
 examples/headless-slack-demo/server/index.ts  |  42 +++++
 examples/headless-slack-demo/src/App.tsx      |  95 +++++++++++
 .../src/components/Message.tsx                | 144 +++++++++++++++++
 .../src/components/MessageInput.tsx           |  94 +++++++++++
 .../src/components/MessageList.tsx            |  58 +++++++
 .../src/components/Sidebar.tsx                | 149 ++++++++++++++++++
 examples/headless-slack-demo/src/index.css    |  33 ++++
 examples/headless-slack-demo/src/main.tsx     |  10 ++
 .../headless-slack-demo/tsconfig.app.json     |  18 +++
 examples/headless-slack-demo/tsconfig.json    |   7 +
 .../headless-slack-demo/tsconfig.node.json    |  15 ++
 examples/headless-slack-demo/vite.config.ts   |  12 ++
 .../src/react/hooks/useMessageMeta.ts         |   8 +-
 .../src/react/provider/CopilotProvider.tsx    |   5 +-
 pnpm-lock.yaml                                | 145 ++++++++++-------
 19 files changed, 828 insertions(+), 62 deletions(-)
 create mode 100644 examples/headless-slack-demo/.env.example
 create mode 100644 examples/headless-slack-demo/index.html
 create mode 100644 examples/headless-slack-demo/package.json
 create mode 100644 examples/headless-slack-demo/postcss.config.mjs
 create mode 100644 examples/headless-slack-demo/server/index.ts
 create mode 100644 examples/headless-slack-demo/src/App.tsx
 create mode 100644 examples/headless-slack-demo/src/components/Message.tsx
 create mode 100644 examples/headless-slack-demo/src/components/MessageInput.tsx
 create mode 100644 examples/headless-slack-demo/src/components/MessageList.tsx
 create mode 100644 examples/headless-slack-demo/src/components/Sidebar.tsx
 create mode 100644 examples/headless-slack-demo/src/index.css
 create mode 100644 examples/headless-slack-demo/src/main.tsx
 create mode 100644 examples/headless-slack-demo/tsconfig.app.json
 create mode 100644 examples/headless-slack-demo/tsconfig.json
 create mode 100644 examples/headless-slack-demo/tsconfig.node.json
 create mode 100644 examples/headless-slack-demo/vite.config.ts

diff --git a/examples/headless-slack-demo/.env.example b/examples/headless-slack-demo/.env.example
new file mode 100644
index 0000000..11b2b32
--- /dev/null
+++ b/examples/headless-slack-demo/.env.example
@@ -0,0 +1 @@
+OPENAI_API_KEY=your_api_key_here
diff --git a/examples/headless-slack-demo/index.html b/examples/headless-slack-demo/index.html
new file mode 100644
index 0000000..e67c814
--- /dev/null
+++ b/examples/headless-slack-demo/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Headless Slack Demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/examples/headless-slack-demo/package.json b/examples/headless-slack-demo/package.json
new file mode 100644
index 0000000..be25df2
--- /dev/null
+++ b/examples/headless-slack-demo/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "headless-slack-demo",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently \"pnpm dev:server\" \"pnpm dev:client\"",
+    "dev:client": "vite",
+    "dev:server": "tsx watch server/index.ts",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@yourgpt/copilot-sdk": "workspace:*",
+    "@yourgpt/llm-sdk": "workspace:*",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0",
+    "lucide-react": "^0.563.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^4.3.4",
+    "concurrently": "^9.0.0",
+    "tailwindcss": "^4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0"
+  }
+}
diff --git a/examples/headless-slack-demo/postcss.config.mjs b/examples/headless-slack-demo/postcss.config.mjs
new file mode 100644
index 0000000..a7f73a2
--- /dev/null
+++ b/examples/headless-slack-demo/postcss.config.mjs
@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
diff --git a/examples/headless-slack-demo/server/index.ts b/examples/headless-slack-demo/server/index.ts
new file mode 100644
index 0000000..a488275
--- /dev/null
+++ b/examples/headless-slack-demo/server/index.ts
@@ -0,0 +1,42 @@
+import "dotenv/config";
+import express from "express";
+import cors from "cors";
+import { createRuntime } from "@yourgpt/llm-sdk";
+import { createOpenAI } from "@yourgpt/llm-sdk/openai";
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+const runtime = createRuntime({
+  provider: openai,
+  model: "gpt-4o-mini",
+  systemPrompt:
+    "You are a helpful AI assistant in a team chat. Be concise, friendly, and helpful. Occasionally use markdown formatting.",
+});
+
+app.get("/api/copilot", (_req, res) => {
+  res.json({ status: "ok", provider: "openai" });
+});
+
+app.post("/api/copilot", async (req, res) => {
+  // createRuntime.handleRequest expects a web Request — adapt from Express
+  const url = `http://localhost:${PORT}/api/copilot`;
+  const webReq = new Request(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(req.body),
+  });
+  const response = await runtime.handleRequest(webReq);
+  res.status(response.status);
+  response.headers.forEach((val, key) => res.setHeader(key, val));
+  const body = await response.text();
+  res.send(body);
+});
+
+const PORT = 3010;
+app.listen(PORT, () =>
+  console.log(`Copilot server running on http://localhost:${PORT}`),
+);
diff --git a/examples/headless-slack-demo/src/App.tsx b/examples/headless-slack-demo/src/App.tsx
new file mode 100644
index 0000000..6db1c72
--- /dev/null
+++ b/examples/headless-slack-demo/src/App.tsx
@@ -0,0 +1,95 @@
+import {
+  CopilotProvider,
+  useCopilot,
+  useCopilotEvent,
+} from "@yourgpt/copilot-sdk/react";
+import Sidebar from "./components/Sidebar";
+import MessageList from "./components/MessageList";
+import MessageInput from "./components/MessageInput";
+import { useState } from "react";
+
+// Channels
+const CHANNELS = [
+  { id: "general", name: "general" },
+  { id: "random", name: "random" },
+  { id: "ai-assistant", name: "ai-assistant" },
+];
+
+function ChatApp() {
+  const [activeChannel, setActiveChannel] = useState("ai-assistant");
+  const { messageMeta } = useCopilot();
+
+  // Write thinking text to messageMeta during streaming
+  useCopilotEvent("thinking:delta", (e) => {
+    if (!e.messageId) return;
+    messageMeta.updateMeta(e.messageId, (prev) => ({
+      ...prev,
+      thinking: ((prev.thinking as string) ?? "") + e.content,
+      isThinking: true,
+    }));
+  });
+
+  useCopilotEvent("message:end", (e) => {
+    if (!e.messageId) return;
+    messageMeta.updateMeta(e.messageId, (prev) => ({
+      ...prev,
+      isThinking: false,
+    }));
+  });
+
+  // Track active tools per message
+  useCopilotEvent("action:start", (e) => {
+    if (!e.messageId) return;
+    messageMeta.updateMeta(e.messageId, (prev) => ({
+      ...prev,
+      tools: {
+        ...((prev.tools as object) ?? {}),
+        [e.name]: "running",
+      },
+    }));
+  });
+
+  useCopilotEvent("action:end", (e) => {
+    if (!e.messageId) return;
+    messageMeta.updateMeta(e.messageId, (prev) => ({
+      ...prev,
+      tools: {
+        ...((prev.tools as object) ?? {}),
+        [e.name]: e.error ? "error" : "done",
+      },
+    }));
+  });
+
+  return (
+    <div className="flex h-screen bg-white overflow-hidden">
+      <Sidebar
+        channels={CHANNELS}
+        activeChannel={activeChannel}
+        onChannelSelect={setActiveChannel}
+      />
+      <div className="flex flex-col flex-1 min-w-0">
+        {/* Channel header */}
+        <div className="flex items-center gap-2 px-4 py-3 border-b border-gray-200 bg-white shadow-sm shrink-0">
+          <span className="text-gray-500 text-lg">#</span>
+          <span className="font-bold text-gray-900 text-base">
+            {activeChannel}
+          </span>
+          <span className="text-gray-400 text-sm ml-2 hidden sm:block">
+            AI-powered channel — ask anything
+          </span>
+        </div>
+
+        <MessageList />
+        <MessageInput />
+      </div>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <CopilotProvider runtimeUrl="/api/copilot">
+      <ChatApp />
+    </CopilotProvider>
+  );
+}
diff --git a/examples/headless-slack-demo/src/components/Message.tsx b/examples/headless-slack-demo/src/components/Message.tsx
new file mode 100644
index 0000000..65cac5f
--- /dev/null
+++ b/examples/headless-slack-demo/src/components/Message.tsx
@@ -0,0 +1,144 @@
+import { useMessageMeta } from "@yourgpt/copilot-sdk/react";
+import {
+  Bot,
+  User,
+  Loader2,
+  Wrench,
+  CheckCircle2,
+  XCircle,
+} from "lucide-react";
+
+interface MessageProps {
+  message: {
+    id: string;
+    role: "user" | "assistant";
+    content: string;
+    createdAt?: Date;
+  };
+}
+
+interface MyMeta {
+  thinking?: string;
+  isThinking?: boolean;
+  tools?: Record<string, "running" | "done" | "error">;
+}
+
+function formatTime(date?: Date) {
+  if (!date) return "";
+  return new Intl.DateTimeFormat("en", {
+    hour: "numeric",
+    minute: "2-digit",
+    hour12: true,
+  }).format(date);
+}
+
+export default function Message({ message }: MessageProps) {
+  const { meta } = useMessageMeta<MyMeta>(message.id);
+  const isAssistant = message.role === "assistant";
+  const tools = meta.tools ?? {};
+  const runningTools = Object.entries(tools).filter(([, v]) => v === "running");
+  const doneTools = Object.entries(tools).filter(([, v]) => v === "done");
+  const errorTools = Object.entries(tools).filter(([, v]) => v === "error");
+
+  return (
+    <div className="flex gap-3 px-4 py-1.5 hover:bg-[var(--message-hover)] group rounded-lg mx-2">
+      {/* Avatar */}
+      <div className="shrink-0 mt-0.5">
+        {isAssistant ? (
+          <div className="w-9 h-9 rounded-lg bg-gradient-to-br from-purple-500 to-blue-600 flex items-center justify-center">
+            <Bot size={18} className="text-white" />
+          </div>
+        ) : (
+          <div className="w-9 h-9 rounded-lg bg-gradient-to-br from-green-400 to-teal-500 flex items-center justify-center">
+            <User size={18} className="text-white" />
+          </div>
+        )}
+      </div>
+
+      {/* Content */}
+      <div className="flex-1 min-w-0">
+        {/* Name + time */}
+        <div className="flex items-baseline gap-2 mb-0.5">
+          <span className="font-bold text-gray-900 text-sm">
+            {isAssistant ? "AI Assistant" : "You"}
+          </span>
+          <span className="text-gray-400 text-xs opacity-0 group-hover:opacity-100 transition-opacity">
+            {formatTime(message.createdAt ?? new Date())}
+          </span>
+        </div>
+
+        {/* Thinking indicator */}
+        {meta.isThinking && (
+          <div className="flex items-center gap-1.5 text-xs text-purple-600 mb-1 bg-purple-50 rounded px-2 py-1 w-fit">
+            <Loader2 size={11} className="animate-spin" />
+            <span>Thinking…</span>
+            {meta.thinking && (
+              <span className="text-purple-400 truncate max-w-48">
+                {meta.thinking.slice(-60)}
+              </span>
+            )}
+          </div>
+        )}
+
+        {/* Running tools */}
+        {runningTools.map(([name]) => (
+          <div
+            key={name}
+            className="flex items-center gap-1.5 text-xs text-blue-600 mb-1 bg-blue-50 rounded px-2 py-1 w-fit"
+          >
+            <Loader2 size={11} className="animate-spin" />
+            <Wrench size={11} />
+            <span>{name.replace(/_/g, " ")}</span>
+          </div>
+        ))}
+
+        {/* Done tools */}
+        {doneTools.map(([name]) => (
+          <div
+            key={name}
+            className="flex items-center gap-1.5 text-xs text-green-600 mb-1 bg-green-50 rounded px-2 py-1 w-fit"
+          >
+            <CheckCircle2 size={11} />
+            <span>{name.replace(/_/g, " ")}</span>
+          </div>
+        ))}
+
+        {/* Error tools */}
+        {errorTools.map(([name]) => (
+          <div
+            key={name}
+            className="flex items-center gap-1.5 text-xs text-red-600 mb-1 bg-red-50 rounded px-2 py-1 w-fit"
+          >
+            <XCircle size={11} />
+            <span>{name.replace(/_/g, " ")} failed</span>
+          </div>
+        ))}
+
+        {/* Message text */}
+        {message.content && (
+          <p className="text-gray-800 text-sm leading-relaxed whitespace-pre-wrap">
+            {message.content}
+          </p>
+        )}
+
+        {/* Streaming placeholder */}
+        {!message.content && !meta.isThinking && isAssistant && (
+          <div className="flex gap-1 items-center h-5">
+            <span
+              className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+              style={{ animationDelay: "0ms" }}
+            />
+            <span
+              className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+              style={{ animationDelay: "150ms" }}
+            />
+            <span
+              className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+              style={{ animationDelay: "300ms" }}
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/examples/headless-slack-demo/src/components/MessageInput.tsx b/examples/headless-slack-demo/src/components/MessageInput.tsx
new file mode 100644
index 0000000..7bbbd66
--- /dev/null
+++ b/examples/headless-slack-demo/src/components/MessageInput.tsx
@@ -0,0 +1,94 @@
+import { useState, useRef, KeyboardEvent } from "react";
+import { useCopilot } from "@yourgpt/copilot-sdk/react";
+import { Send, Paperclip, Smile } from "lucide-react";
+
+export default function MessageInput() {
+  const [input, setInput] = useState("");
+  const { sendMessage, status } = useCopilot();
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  const handleSend = () => {
+    const text = input.trim();
+    if (!text || status === "streaming") return;
+    sendMessage(text);
+    setInput("");
+    if (textareaRef.current) {
+      textareaRef.current.style.height = "auto";
+    }
+  };
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      handleSend();
+    }
+  };
+
+  const handleInput = () => {
+    const el = textareaRef.current;
+    if (!el) return;
+    el.style.height = "auto";
+    el.style.height = `${Math.min(el.scrollHeight, 160)}px`;
+  };
+
+  return (
+    <div className="px-4 pb-4 pt-2 shrink-0">
+      <div className="border border-gray-300 rounded-lg overflow-hidden focus-within:border-gray-400 focus-within:ring-1 focus-within:ring-gray-300 transition-all">
+        {/* Toolbar */}
+        <div className="flex items-center gap-1 px-3 pt-2 pb-1 border-b border-gray-100">
+          <button className="p-1 rounded hover:bg-gray-100 text-gray-400 hover:text-gray-600 transition-colors">
+            <Paperclip size={15} />
+          </button>
+          <button className="p-1 rounded hover:bg-gray-100 text-gray-400 hover:text-gray-600 transition-colors">
+            <Smile size={15} />
+          </button>
+        </div>
+
+        {/* Textarea */}
+        <div className="flex items-end gap-2 px-3 py-2">
+          <textarea
+            ref={textareaRef}
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            onKeyDown={handleKeyDown}
+            onInput={handleInput}
+            placeholder="Message #ai-assistant"
+            rows={1}
+            disabled={status === "streaming"}
+            className="flex-1 resize-none bg-transparent text-sm text-gray-800 placeholder-gray-400 outline-none leading-5 max-h-40 disabled:opacity-50"
+            style={{ minHeight: "20px" }}
+          />
+          <button
+            onClick={handleSend}
+            disabled={!input.trim() || status === "streaming"}
+            className="shrink-0 w-7 h-7 rounded flex items-center justify-center transition-colors disabled:opacity-30 disabled:cursor-not-allowed"
+            style={{
+              backgroundColor:
+                input.trim() && status !== "streaming" ? "#007a5a" : undefined,
+              color: input.trim() && status !== "streaming" ? "white" : "#aaa",
+            }}
+          >
+            <Send size={14} />
+          </button>
+        </div>
+
+        {/* Hint */}
+        <div className="px-3 pb-2 flex items-center justify-between">
+          <span className="text-xs text-gray-400">
+            <kbd className="bg-gray-100 px-1 rounded text-[10px]">Enter</kbd> to
+            send &nbsp;·&nbsp;
+            <kbd className="bg-gray-100 px-1 rounded text-[10px]">
+              Shift+Enter
+            </kbd>{" "}
+            for new line
+          </span>
+          {status === "streaming" && (
+            <span className="text-xs text-purple-500 animate-pulse">
+              AI is typing…
+            </span>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/examples/headless-slack-demo/src/components/MessageList.tsx b/examples/headless-slack-demo/src/components/MessageList.tsx
new file mode 100644
index 0000000..0066cec
--- /dev/null
+++ b/examples/headless-slack-demo/src/components/MessageList.tsx
@@ -0,0 +1,58 @@
+import { useEffect, useRef } from "react";
+import { useCopilot } from "@yourgpt/copilot-sdk/react";
+import Message from "./Message";
+import { Bot } from "lucide-react";
+
+export default function MessageList() {
+  const { messages, status } = useCopilot();
+  const bottomRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [messages.length]);
+
+  if (messages.length === 0) {
+    return (
+      <div className="flex-1 flex flex-col items-center justify-center text-center px-8 gap-4">
+        <div className="w-16 h-16 rounded-2xl bg-gradient-to-br from-purple-500 to-blue-600 flex items-center justify-center">
+          <Bot size={32} className="text-white" />
+        </div>
+        <div>
+          <h2 className="font-bold text-gray-900 text-xl mb-1">AI Assistant</h2>
+          <p className="text-gray-500 text-sm max-w-xs">
+            This is the beginning of your conversation. Ask anything — I'm here
+            to help.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex-1 overflow-y-auto py-4 slack-scroll">
+      {messages.map((m) => (
+        <Message key={m.id} message={m} />
+      ))}
+      {status === "streaming" &&
+        messages[messages.length - 1]?.role !== "assistant" && (
+          <div className="px-4 py-1.5">
+            <div className="flex gap-1 items-center h-5 ml-12">
+              <span
+                className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+                style={{ animationDelay: "0ms" }}
+              />
+              <span
+                className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+                style={{ animationDelay: "150ms" }}
+              />
+              <span
+                className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+                style={{ animationDelay: "300ms" }}
+              />
+            </div>
+          </div>
+        )}
+      <div ref={bottomRef} />
+    </div>
+  );
+}
diff --git a/examples/headless-slack-demo/src/components/Sidebar.tsx b/examples/headless-slack-demo/src/components/Sidebar.tsx
new file mode 100644
index 0000000..3d207d4
--- /dev/null
+++ b/examples/headless-slack-demo/src/components/Sidebar.tsx
@@ -0,0 +1,149 @@
+import { Hash, ChevronDown, Plus, Bell } from "lucide-react";
+
+interface Channel {
+  id: string;
+  name: string;
+}
+
+interface SidebarProps {
+  channels: Channel[];
+  activeChannel: string;
+  onChannelSelect: (id: string) => void;
+}
+
+export default function Sidebar({
+  channels,
+  activeChannel,
+  onChannelSelect,
+}: SidebarProps) {
+  return (
+    <div
+      className="w-64 shrink-0 flex flex-col overflow-hidden"
+      style={{ backgroundColor: "var(--sidebar-bg)" }}
+    >
+      {/* Workspace header */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-white/10">
+        <div className="flex items-center gap-1 cursor-pointer group">
+          <span className="text-white font-bold text-base tracking-tight">
+            YourGPT
+          </span>
+          <ChevronDown
+            size={14}
+            className="text-white/60 group-hover:text-white transition-colors"
+          />
+        </div>
+        <button className="w-7 h-7 rounded-full bg-white/10 hover:bg-white/20 flex items-center justify-center transition-colors">
+          <Plus size={16} className="text-white" />
+        </button>
+      </div>
+
+      {/* Scrollable area */}
+      <div className="flex-1 overflow-y-auto py-2 slack-scroll">
+        {/* Browsed channels */}
+        <div className="mb-1">
+          <SidebarSection label="Channels" />
+          {channels.map((ch) => (
+            <SidebarItem
+              key={ch.id}
+              icon={<Hash size={15} />}
+              label={ch.name}
+              active={ch.id === activeChannel}
+              onClick={() => onChannelSelect(ch.id)}
+            />
+          ))}
+          <button
+            className="flex items-center gap-2 w-full px-3 py-1 text-sm hover:bg-white/10 rounded mx-1 transition-colors"
+            style={{ color: "var(--sidebar-text)" }}
+          >
+            <Plus size={15} />
+            <span>Add channels</span>
+          </button>
+        </div>
+
+        {/* DMs */}
+        <div className="mt-2">
+          <SidebarSection label="Direct messages" />
+          {["Alice", "Bob", "Carol"].map((name) => (
+            <SidebarItem
+              key={name}
+              icon={
+                <span className="w-4 h-4 rounded-sm bg-green-400 text-white text-[9px] flex items-center justify-center font-bold shrink-0">
+                  {name[0]}
+                </span>
+              }
+              label={name}
+              active={false}
+              onClick={() => {}}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Bottom user bar */}
+      <div className="flex items-center gap-2 px-3 py-2 border-t border-white/10">
+        <div className="w-8 h-8 rounded-lg bg-purple-400 flex items-center justify-center text-white text-xs font-bold shrink-0">
+          Y
+        </div>
+        <div className="flex-1 min-w-0">
+          <p className="text-white text-sm font-semibold truncate">You</p>
+          <p className="text-white/50 text-xs">Active</p>
+        </div>
+        <Bell
+          size={16}
+          className="text-white/50 hover:text-white cursor-pointer"
+        />
+      </div>
+    </div>
+  );
+}
+
+function SidebarSection({ label }: { label: string }) {
+  return (
+    <div className="flex items-center gap-1 px-3 py-1 mb-0.5">
+      <ChevronDown size={12} style={{ color: "var(--sidebar-text)" }} />
+      <span
+        className="text-xs font-semibold uppercase tracking-wide"
+        style={{ color: "var(--sidebar-text)" }}
+      >
+        {label}
+      </span>
+    </div>
+  );
+}
+
+function SidebarItem({
+  icon,
+  label,
+  active,
+  onClick,
+}: {
+  icon: React.ReactNode;
+  label: string;
+  active: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      className="flex items-center gap-2 w-full px-3 py-1 rounded mx-1 text-sm transition-colors"
+      style={{
+        color: active ? "var(--sidebar-text-active)" : "var(--sidebar-text)",
+        backgroundColor: active ? "var(--sidebar-active)" : "transparent",
+        width: "calc(100% - 8px)",
+      }}
+      onMouseEnter={(e) => {
+        if (!active)
+          (e.currentTarget as HTMLElement).style.backgroundColor =
+            "var(--sidebar-hover)";
+      }}
+      onMouseLeave={(e) => {
+        if (!active)
+          (e.currentTarget as HTMLElement).style.backgroundColor =
+            "transparent";
+      }}
+    >
+      <span className="shrink-0">{icon}</span>
+      <span className="truncate">{label}</span>
+    </button>
+  );
+}
diff --git a/examples/headless-slack-demo/src/index.css b/examples/headless-slack-demo/src/index.css
new file mode 100644
index 0000000..8f10794
--- /dev/null
+++ b/examples/headless-slack-demo/src/index.css
@@ -0,0 +1,33 @@
+@import "tailwindcss";
+
+:root {
+  --sidebar-bg: #3f0e40;
+  --sidebar-active: #1164a3;
+  --sidebar-hover: rgba(255,255,255,0.1);
+  --sidebar-text: rgba(255,255,255,0.7);
+  --sidebar-text-active: #ffffff;
+  --message-hover: #f8f8f8;
+}
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  height: 100vh;
+  overflow: hidden;
+}
+
+#root {
+  height: 100vh;
+}
+
+/* Scrollbar styling */
+.slack-scroll::-webkit-scrollbar {
+  width: 6px;
+}
+.slack-scroll::-webkit-scrollbar-track {
+  background: transparent;
+}
+.slack-scroll::-webkit-scrollbar-thumb {
+  background: #ccc;
+  border-radius: 3px;
+}
diff --git a/examples/headless-slack-demo/src/main.tsx b/examples/headless-slack-demo/src/main.tsx
new file mode 100644
index 0000000..15753af
--- /dev/null
+++ b/examples/headless-slack-demo/src/main.tsx
@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
diff --git a/examples/headless-slack-demo/tsconfig.app.json b/examples/headless-slack-demo/tsconfig.app.json
new file mode 100644
index 0000000..4537585
--- /dev/null
+++ b/examples/headless-slack-demo/tsconfig.app.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true
+  },
+  "include": ["src"]
+}
diff --git a/examples/headless-slack-demo/tsconfig.json b/examples/headless-slack-demo/tsconfig.json
new file mode 100644
index 0000000..1ffef60
--- /dev/null
+++ b/examples/headless-slack-demo/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
diff --git a/examples/headless-slack-demo/tsconfig.node.json b/examples/headless-slack-demo/tsconfig.node.json
new file mode 100644
index 0000000..1f27c41
--- /dev/null
+++ b/examples/headless-slack-demo/tsconfig.node.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true
+  },
+  "include": ["vite.config.ts", "server"]
+}
diff --git a/examples/headless-slack-demo/vite.config.ts b/examples/headless-slack-demo/vite.config.ts
new file mode 100644
index 0000000..2a6cd9d
--- /dev/null
+++ b/examples/headless-slack-demo/vite.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 3011,
+    proxy: {
+      "/api": "http://localhost:3010",
+    },
+  },
+});
diff --git a/packages/copilot-sdk/src/react/hooks/useMessageMeta.ts b/packages/copilot-sdk/src/react/hooks/useMessageMeta.ts
index 03d048c..d9a0b90 100644
--- a/packages/copilot-sdk/src/react/hooks/useMessageMeta.ts
+++ b/packages/copilot-sdk/src/react/hooks/useMessageMeta.ts
@@ -46,6 +46,9 @@
 import { useSyncExternalStore, useCallback } from "react";
 import { useCopilot } from "../provider/CopilotProvider";
 
+// Stable empty object for messageId=undefined — avoids new reference each render
+const EMPTY_META: Record<string, unknown> = {};
+
 export interface UseMessageMetaReturn<T extends Record<string, unknown>> {
   /** Current metadata for this message. Empty object if nothing set yet. */
   meta: T;
@@ -74,8 +77,9 @@ export function useMessageMeta<
   // Subscribe to store changes — only re-render when this messageId's data changes
   const meta = useSyncExternalStore(
     messageMeta.subscribe,
-    () => (messageId ? (messageMeta.getMeta(messageId) as T) : ({} as T)),
-    () => ({}) as T,
+    () =>
+      messageId ? (messageMeta.getMeta(messageId) as T) : (EMPTY_META as T),
+    () => EMPTY_META as T,
   );
 
   const setMeta = useCallback(
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index cdebb6c..58a9460 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -324,6 +324,9 @@ export type StreamEventHandler = (chunk: StreamChunkWithMessageId) => void;
 export class MessageMetaStore {
   private store = new Map<string, Record<string, unknown>>();
   private listeners = new Set<() => void>();
+  // Stable empty object — returned for unknown messageIds so useSyncExternalStore
+  // sees the same reference and doesn't trigger infinite re-renders.
+  private static readonly EMPTY: Record<string, unknown> = {};
 
   subscribe = (cb: () => void): (() => void) => {
     this.listeners.add(cb);
@@ -333,7 +336,7 @@ export class MessageMetaStore {
   getSnapshot = (): Map<string, Record<string, unknown>> => this.store;
 
   getMeta = (messageId: string): Record<string, unknown> =>
-    this.store.get(messageId) ?? {};
+    this.store.get(messageId) ?? MessageMetaStore.EMPTY;
 
   setMeta = (messageId: string, meta: Record<string, unknown>): void => {
     this.store.set(messageId, meta);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 78c2781..e116fb0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -84,7 +84,7 @@ importers:
         version: 9.39.2(jiti@2.6.1)
       eslint-config-next:
         specifier: 16.0.10
-        version: 16.0.10(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+        version: 16.0.10(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       tailwindcss:
         specifier: ^4
         version: 4.1.18
@@ -418,6 +418,70 @@ importers:
         specifier: ^5.6.0
         version: 5.9.3
 
+  examples/headless-slack-demo:
+    dependencies:
+      '@yourgpt/copilot-sdk':
+        specifier: workspace:*
+        version: link:../../packages/copilot-sdk
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+      lucide-react:
+        specifier: ^0.563.0
+        version: 0.563.0(react@19.2.3)
+      react:
+        specifier: ^19.0.0
+        version: 19.2.3
+      react-dom:
+        specifier: ^19.0.0
+        version: 19.2.3(react@19.2.3)
+    devDependencies:
+      '@tailwindcss/postcss':
+        specifier: ^4
+        version: 4.1.18
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      '@types/node':
+        specifier: ^20
+        version: 20.19.27
+      '@types/react':
+        specifier: ^18.2.0
+        version: 18.3.27
+      '@types/react-dom':
+        specifier: ^18.2.0
+        version: 18.3.7(@types/react@18.3.27)
+      '@vitejs/plugin-react':
+        specifier: ^4.3.4
+        version: 4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+      concurrently:
+        specifier: ^9.0.0
+        version: 9.2.1
+      tailwindcss:
+        specifier: ^4
+        version: 4.2.1
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+      vite:
+        specifier: ^6.0.0
+        version: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+
   examples/mcp-demo:
     dependencies:
       '@tailwindcss/typography':
@@ -739,7 +803,7 @@ importers:
         version: 9.39.2(jiti@2.6.1)
       eslint-config-next:
         specifier: 16.1.5
-        version: 16.1.5(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+        version: 16.1.5(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       shadcn:
         specifier: ^3.8.1
         version: 3.8.1(@types/node@20.19.27)(hono@4.11.0)(typescript@5.9.3)
@@ -1075,34 +1139,6 @@ importers:
         specifier: ^5
         version: 5.9.3
 
-  examples/yourgpt-server-demo:
-    dependencies:
-      '@yourgpt/llm-sdk':
-        specifier: workspace:*
-        version: link:../../packages/llm-sdk
-      cors:
-        specifier: ^2.8.5
-        version: 2.8.6
-      dotenv:
-        specifier: ^16.4.0
-        version: 16.6.1
-      express:
-        specifier: ^4.21.0
-        version: 4.22.1
-    devDependencies:
-      '@types/cors':
-        specifier: ^2.8.17
-        version: 2.8.19
-      '@types/express':
-        specifier: ^5.0.0
-        version: 5.0.6
-      tsx:
-        specifier: ^4.19.0
-        version: 4.21.0
-      typescript:
-        specifier: ^5.6.0
-        version: 5.9.3
-
   packages/copilot-sdk:
     dependencies:
       '@base-ui/react':
@@ -11381,6 +11417,18 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
     optional: true
 
+  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.5)
+      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.28.5)
+      '@rolldown/pluginutils': 1.0.0-beta.27
+      '@types/babel__core': 7.20.5
+      react-refresh: 0.17.0
+      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+    transitivePeerDependencies:
+      - supports-color
+
   '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@babel/core': 7.28.5
@@ -12240,13 +12288,13 @@ snapshots:
 
   escape-string-regexp@5.0.0: {}
 
-  eslint-config-next@16.0.10(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3):
+  eslint-config-next@16.0.10(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3):
     dependencies:
       '@next/eslint-plugin-next': 16.0.10
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12266,27 +12314,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
-      globals: 16.4.0
-      typescript-eslint: 8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
-    optionalDependencies:
-      typescript: 5.9.3
-    transitivePeerDependencies:
-      - '@typescript-eslint/parser'
-      - eslint-import-resolver-webpack
-      - eslint-plugin-import-x
-      - supports-color
-
-  eslint-config-next@16.1.5(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3):
-    dependencies:
-      '@next/eslint-plugin-next': 16.1.5
-      eslint: 9.39.2(jiti@2.6.1)
-      eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12305,8 +12333,8 @@ snapshots:
       '@next/eslint-plugin-next': 16.1.5
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12339,7 +12367,7 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -12408,7 +12436,7 @@ snapshots:
       - eslint-import-resolver-webpack
       - supports-color
 
-  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -16103,7 +16131,6 @@ snapshots:
       sass: 1.97.0
       tsx: 4.21.0
       yaml: 2.8.2
-    optional: true
 
   vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:

From 20b4ea784975fb478cc2ee0e49b6cd5aa9c3d32d Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 23 Mar 2026 18:10:32 +0530
Subject: [PATCH 45/72] =?UTF-8?q?feat(example):=20headless-slack-demo=20?=
 =?UTF-8?q?=E2=80=94=20tools,=20routing,=20persistence?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add server tools: get_weather, search_web, create_poll (with mock handlers)
- Add client tools: calculate, get_time (registered via useTools hooks)
- Render tool result cards: WeatherCard, SearchCard, PollCard, CalculatorCard, TimeCard
- Add React Router per-channel routing with CopilotProvider key remount
- Add localStorage persistence with initialCount guard (only saves new messages,
  prevents overwriting metadata-bearing restored messages with stripped versions)
- Filter role=tool messages and empty no-content assistant tool-calling turns
  from MessageList display
- Fix streaming placeholder visibility during tool execution turns
- Add GET /api/copilot health endpoint (SDK capability probe)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/headless-slack-demo/package.json     |   3 +-
 examples/headless-slack-demo/server/index.ts  | 112 ++++++++-
 examples/headless-slack-demo/src/App.tsx      | 136 ++++++++---
 .../src/components/Message.tsx                |  89 ++++++--
 .../src/components/MessageList.tsx            |  16 +-
 .../src/components/Sidebar.tsx                |  85 ++++++-
 .../src/components/ToolCards.tsx              | 215 ++++++++++++++++++
 .../headless-slack-demo/src/hooks/useTools.ts |  65 ++++++
 .../headless-slack-demo/src/lib/storage.ts    |  22 ++
 pnpm-lock.yaml                                |  87 +++++--
 10 files changed, 742 insertions(+), 88 deletions(-)
 create mode 100644 examples/headless-slack-demo/src/components/ToolCards.tsx
 create mode 100644 examples/headless-slack-demo/src/hooks/useTools.ts
 create mode 100644 examples/headless-slack-demo/src/lib/storage.ts

diff --git a/examples/headless-slack-demo/package.json b/examples/headless-slack-demo/package.json
index be25df2..f523c8b 100644
--- a/examples/headless-slack-demo/package.json
+++ b/examples/headless-slack-demo/package.json
@@ -18,7 +18,8 @@
     "express": "^4.21.0",
     "lucide-react": "^0.563.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.0.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
diff --git a/examples/headless-slack-demo/server/index.ts b/examples/headless-slack-demo/server/index.ts
index a488275..c649782 100644
--- a/examples/headless-slack-demo/server/index.ts
+++ b/examples/headless-slack-demo/server/index.ts
@@ -14,7 +14,117 @@ const runtime = createRuntime({
   provider: openai,
   model: "gpt-4o-mini",
   systemPrompt:
-    "You are a helpful AI assistant in a team chat. Be concise, friendly, and helpful. Occasionally use markdown formatting.",
+    "You are a helpful AI assistant in a team Slack-like chat. Be concise and friendly.\n\nYou have access to these tools — use them when relevant:\n- get_weather: get weather for any city\n- search_web: search the web for information\n- create_poll: create a team poll with voting options\n- calculate: evaluate a math expression (client-side)\n- get_time: get current time/date for any timezone (client-side)\n\nAlways use tools when the user's request clearly calls for one.",
+  tools: [
+    {
+      name: "get_weather",
+      description: "Get current weather for a city",
+      location: "server" as const,
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          city: { type: "string", description: "City name" },
+        },
+        required: ["city"],
+      },
+      handler: async ({ city }: { city: string }) => {
+        // Mock weather data
+        const conditions = [
+          "Sunny",
+          "Cloudy",
+          "Rainy",
+          "Partly cloudy",
+          "Windy",
+        ];
+        const temp = Math.floor(Math.random() * 25) + 10;
+        const condition =
+          conditions[Math.floor(Math.random() * conditions.length)];
+        return {
+          success: true,
+          data: {
+            city,
+            temperature: temp,
+            unit: "celsius",
+            condition,
+            humidity: Math.floor(Math.random() * 40) + 40,
+            wind: Math.floor(Math.random() * 20) + 5,
+          },
+        };
+      },
+    },
+    {
+      name: "search_web",
+      description: "Search the web for information on a topic",
+      location: "server" as const,
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          query: { type: "string", description: "Search query" },
+        },
+        required: ["query"],
+      },
+      handler: async ({ query }: { query: string }) => {
+        // Mock search results
+        return {
+          success: true,
+          data: {
+            query,
+            results: [
+              {
+                title: `${query} — Overview`,
+                url: "https://example.com/1",
+                snippet: `Comprehensive overview of ${query} with latest updates and insights.`,
+              },
+              {
+                title: `Understanding ${query}`,
+                url: "https://example.com/2",
+                snippet: `Deep dive into ${query}: history, current state, and future outlook.`,
+              },
+              {
+                title: `${query} Guide 2025`,
+                url: "https://example.com/3",
+                snippet: `Complete guide to ${query} for beginners and advanced users alike.`,
+              },
+            ],
+          },
+        };
+      },
+    },
+    {
+      name: "create_poll",
+      description: "Create a team poll with options for voting",
+      location: "server" as const,
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          question: { type: "string", description: "Poll question" },
+          options: {
+            type: "array",
+            items: { type: "string" },
+            description: "Poll options",
+          },
+        },
+        required: ["question", "options"],
+      },
+      handler: async ({
+        question,
+        options,
+      }: {
+        question: string;
+        options: string[];
+      }) => {
+        return {
+          success: true,
+          data: {
+            id: `poll_${Date.now()}`,
+            question,
+            options: options.map((o, i) => ({ id: i, text: o, votes: 0 })),
+            createdAt: new Date().toISOString(),
+          },
+        };
+      },
+    },
+  ],
 });
 
 app.get("/api/copilot", (_req, res) => {
diff --git a/examples/headless-slack-demo/src/App.tsx b/examples/headless-slack-demo/src/App.tsx
index 6db1c72..ff9cbaa 100644
--- a/examples/headless-slack-demo/src/App.tsx
+++ b/examples/headless-slack-demo/src/App.tsx
@@ -1,25 +1,54 @@
+import {
+  BrowserRouter,
+  Routes,
+  Route,
+  Navigate,
+  useParams,
+  useNavigate,
+} from "react-router-dom";
 import {
   CopilotProvider,
   useCopilot,
   useCopilotEvent,
 } from "@yourgpt/copilot-sdk/react";
+import { useEffect, useRef } from "react";
 import Sidebar from "./components/Sidebar";
 import MessageList from "./components/MessageList";
 import MessageInput from "./components/MessageInput";
-import { useState } from "react";
+import { useCalculatorTool, useTimeTool } from "./hooks/useTools";
+import { loadMessages, saveMessages } from "./lib/storage";
 
-// Channels
 const CHANNELS = [
   { id: "general", name: "general" },
   { id: "random", name: "random" },
   { id: "ai-assistant", name: "ai-assistant" },
+  { id: "design", name: "design" },
+  { id: "engineering", name: "engineering" },
 ];
 
-function ChatApp() {
-  const [activeChannel, setActiveChannel] = useState("ai-assistant");
-  const { messageMeta } = useCopilot();
+// Inner component — mounted per channel, has access to useCopilot()
+function ChannelChat({ channelId }: { channelId: string }) {
+  const { messages, messageMeta } = useCopilot();
+
+  // Register client tools
+  useCalculatorTool();
+  useTimeTool();
+
+  // Only save when new messages arrive beyond what was restored from localStorage.
+  // Prevents overwriting with metadata-stripped versions of restored messages.
+  const initialCount = useRef(messages.length);
+
+  useEffect(() => {
+    if (messages.length <= initialCount.current) return;
+    const complete = messages.filter(
+      (m) => !(m.role === "assistant" && !m.content),
+    );
+    if (complete.length > 0) {
+      saveMessages(channelId, complete);
+    }
+  }, [messages, channelId]);
 
-  // Write thinking text to messageMeta during streaming
+  // Write thinking/tool state into messageMeta during streaming
   useCopilotEvent("thinking:delta", (e) => {
     if (!e.messageId) return;
     messageMeta.updateMeta(e.messageId, (prev) => ({
@@ -37,15 +66,11 @@ function ChatApp() {
     }));
   });
 
-  // Track active tools per message
   useCopilotEvent("action:start", (e) => {
     if (!e.messageId) return;
     messageMeta.updateMeta(e.messageId, (prev) => ({
       ...prev,
-      tools: {
-        ...((prev.tools as object) ?? {}),
-        [e.name]: "running",
-      },
+      tools: { ...((prev.tools as object) ?? {}), [e.name]: "running" },
     }));
   });
 
@@ -57,39 +82,82 @@ function ChatApp() {
         ...((prev.tools as object) ?? {}),
         [e.name]: e.error ? "error" : "done",
       },
+      toolResults: {
+        ...((prev.toolResults as object) ?? {}),
+        ...(e.result ? { [e.name]: e.result } : {}),
+      },
+    }));
+  });
+
+  useCopilotEvent("tool:result", (e) => {
+    if (!e.messageId) return;
+    messageMeta.updateMeta(e.messageId, (prev) => ({
+      ...prev,
+      toolResults: {
+        ...((prev.toolResults as object) ?? {}),
+        [e.name]: e.result,
+      },
     }));
   });
 
   return (
-    <div className="flex h-screen bg-white overflow-hidden">
-      <Sidebar
-        channels={CHANNELS}
-        activeChannel={activeChannel}
-        onChannelSelect={setActiveChannel}
-      />
-      <div className="flex flex-col flex-1 min-w-0">
-        {/* Channel header */}
-        <div className="flex items-center gap-2 px-4 py-3 border-b border-gray-200 bg-white shadow-sm shrink-0">
-          <span className="text-gray-500 text-lg">#</span>
-          <span className="font-bold text-gray-900 text-base">
-            {activeChannel}
-          </span>
-          <span className="text-gray-400 text-sm ml-2 hidden sm:block">
-            AI-powered channel — ask anything
-          </span>
-        </div>
+    <>
+      <MessageList />
+      <MessageInput />
+    </>
+  );
+}
+
+// Route component — creates CopilotProvider per channel with threadId + initialMessages
+function ChannelRoute() {
+  const { channelId } = useParams<{ channelId: string }>();
+  const navigate = useNavigate();
+  const channel = CHANNELS.find((c) => c.id === channelId);
 
-        <MessageList />
-        <MessageInput />
+  if (!channel) {
+    navigate("/channel/general", { replace: true });
+    return null;
+  }
+
+  const initialMessages = loadMessages(channelId!);
+
+  return (
+    <CopilotProvider
+      key={channelId}
+      runtimeUrl="/api/copilot"
+      threadId={channelId}
+      initialMessages={initialMessages}
+    >
+      <div className="flex h-screen bg-white overflow-hidden">
+        <Sidebar channels={CHANNELS} activeChannel={channelId!} />
+        <div className="flex flex-col flex-1 min-w-0">
+          {/* Channel header */}
+          <div className="flex items-center gap-2 px-4 py-3 border-b border-gray-200 bg-white shadow-sm shrink-0">
+            <span className="text-gray-500 text-lg">#</span>
+            <span className="font-bold text-gray-900 text-base">
+              {channel.name}
+            </span>
+            <span className="text-gray-400 text-sm ml-2 hidden sm:block">
+              AI-powered channel
+            </span>
+          </div>
+          <ChannelChat channelId={channelId!} />
+        </div>
       </div>
-    </div>
+    </CopilotProvider>
   );
 }
 
 export default function App() {
   return (
-    <CopilotProvider runtimeUrl="/api/copilot">
-      <ChatApp />
-    </CopilotProvider>
+    <BrowserRouter>
+      <Routes>
+        <Route
+          path="/"
+          element={<Navigate to="/channel/ai-assistant" replace />}
+        />
+        <Route path="/channel/:channelId" element={<ChannelRoute />} />
+      </Routes>
+    </BrowserRouter>
   );
 }
diff --git a/examples/headless-slack-demo/src/components/Message.tsx b/examples/headless-slack-demo/src/components/Message.tsx
index 65cac5f..d822ee9 100644
--- a/examples/headless-slack-demo/src/components/Message.tsx
+++ b/examples/headless-slack-demo/src/components/Message.tsx
@@ -7,13 +7,35 @@ import {
   CheckCircle2,
   XCircle,
 } from "lucide-react";
+import {
+  WeatherCard,
+  SearchCard,
+  PollCard,
+  CalculatorCard,
+  TimeCard,
+} from "./ToolCards";
+import type {
+  WeatherData,
+  SearchData,
+  PollData,
+  CalcData,
+  TimeData,
+} from "./ToolCards";
+
+interface ToolExecution {
+  id: string;
+  name: string;
+  status: string;
+  result?: { success: boolean; data?: unknown };
+}
 
 interface MessageProps {
   message: {
     id: string;
-    role: "user" | "assistant";
+    role: string;
     content: string;
     createdAt?: Date;
+    metadata?: { toolExecutions?: ToolExecution[] };
   };
 }
 
@@ -21,6 +43,7 @@ interface MyMeta {
   thinking?: string;
   isThinking?: boolean;
   tools?: Record<string, "running" | "done" | "error">;
+  toolResults?: Record<string, { success: boolean; data?: unknown }>;
 }
 
 function formatTime(date?: Date) {
@@ -114,6 +137,33 @@ export default function Message({ message }: MessageProps) {
           </div>
         ))}
 
+        {/* Tool result cards — read from message.metadata (persistent across remounts) */}
+        {(message.metadata?.toolExecutions ?? [])
+          .filter(
+            (t) =>
+              t.status === "completed" && t.result?.success && t.result?.data,
+          )
+          .map((t) => {
+            const data = t.result!.data as Record<string, unknown>;
+            if (t.name === "get_weather")
+              return (
+                <WeatherCard key={t.id} data={data as unknown as WeatherData} />
+              );
+            if (t.name === "search_web")
+              return (
+                <SearchCard key={t.id} data={data as unknown as SearchData} />
+              );
+            if (t.name === "create_poll")
+              return <PollCard key={t.id} data={data as unknown as PollData} />;
+            if (t.name === "calculate")
+              return (
+                <CalculatorCard key={t.id} data={data as unknown as CalcData} />
+              );
+            if (t.name === "get_time")
+              return <TimeCard key={t.id} data={data as unknown as TimeData} />;
+            return null;
+          })}
+
         {/* Message text */}
         {message.content && (
           <p className="text-gray-800 text-sm leading-relaxed whitespace-pre-wrap">
@@ -121,23 +171,26 @@ export default function Message({ message }: MessageProps) {
           </p>
         )}
 
-        {/* Streaming placeholder */}
-        {!message.content && !meta.isThinking && isAssistant && (
-          <div className="flex gap-1 items-center h-5">
-            <span
-              className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
-              style={{ animationDelay: "0ms" }}
-            />
-            <span
-              className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
-              style={{ animationDelay: "150ms" }}
-            />
-            <span
-              className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
-              style={{ animationDelay: "300ms" }}
-            />
-          </div>
-        )}
+        {/* Streaming placeholder — only when no tool cards to show */}
+        {!message.content &&
+          !meta.isThinking &&
+          isAssistant &&
+          !message.metadata?.toolExecutions?.length && (
+            <div className="flex gap-1 items-center h-5">
+              <span
+                className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+                style={{ animationDelay: "0ms" }}
+              />
+              <span
+                className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+                style={{ animationDelay: "150ms" }}
+              />
+              <span
+                className="w-2 h-2 rounded-full bg-gray-400 animate-bounce"
+                style={{ animationDelay: "300ms" }}
+              />
+            </div>
+          )}
       </div>
     </div>
   );
diff --git a/examples/headless-slack-demo/src/components/MessageList.tsx b/examples/headless-slack-demo/src/components/MessageList.tsx
index 0066cec..9bf32c2 100644
--- a/examples/headless-slack-demo/src/components/MessageList.tsx
+++ b/examples/headless-slack-demo/src/components/MessageList.tsx
@@ -30,9 +30,19 @@ export default function MessageList() {
 
   return (
     <div className="flex-1 overflow-y-auto py-4 slack-scroll">
-      {messages.map((m) => (
-        <Message key={m.id} message={m} />
-      ))}
+      {messages
+        .filter((m) => m.role !== "tool")
+        .filter(
+          (m) =>
+            !(
+              m.role === "assistant" &&
+              !m.content &&
+              !(m as any).metadata?.toolExecutions?.length
+            ),
+        )
+        .map((m) => (
+          <Message key={m.id} message={m} />
+        ))}
       {status === "streaming" &&
         messages[messages.length - 1]?.role !== "assistant" && (
           <div className="px-4 py-1.5">
diff --git a/examples/headless-slack-demo/src/components/Sidebar.tsx b/examples/headless-slack-demo/src/components/Sidebar.tsx
index 3d207d4..0e1ba1b 100644
--- a/examples/headless-slack-demo/src/components/Sidebar.tsx
+++ b/examples/headless-slack-demo/src/components/Sidebar.tsx
@@ -1,4 +1,6 @@
-import { Hash, ChevronDown, Plus, Bell } from "lucide-react";
+import { Hash, ChevronDown, Plus, Bell, Trash2 } from "lucide-react";
+import { useNavigate } from "react-router-dom";
+import { clearMessages, loadMessages } from "../lib/storage";
 
 interface Channel {
   id: string;
@@ -8,14 +10,11 @@ interface Channel {
 interface SidebarProps {
   channels: Channel[];
   activeChannel: string;
-  onChannelSelect: (id: string) => void;
 }
 
-export default function Sidebar({
-  channels,
-  activeChannel,
-  onChannelSelect,
-}: SidebarProps) {
+export default function Sidebar({ channels, activeChannel }: SidebarProps) {
+  const navigate = useNavigate();
+
   return (
     <div
       className="w-64 shrink-0 flex flex-col overflow-hidden"
@@ -39,16 +38,19 @@ export default function Sidebar({
 
       {/* Scrollable area */}
       <div className="flex-1 overflow-y-auto py-2 slack-scroll">
-        {/* Browsed channels */}
+        {/* Channels */}
         <div className="mb-1">
           <SidebarSection label="Channels" />
           {channels.map((ch) => (
-            <SidebarItem
+            <ChannelItem
               key={ch.id}
-              icon={<Hash size={15} />}
-              label={ch.name}
+              channel={ch}
               active={ch.id === activeChannel}
-              onClick={() => onChannelSelect(ch.id)}
+              onClick={() => navigate(`/channel/${ch.id}`)}
+              onClear={() => {
+                clearMessages(ch.id);
+                window.location.reload();
+              }}
             />
           ))}
           <button
@@ -97,6 +99,65 @@ export default function Sidebar({
   );
 }
 
+function ChannelItem({
+  channel,
+  active,
+  onClick,
+  onClear,
+}: {
+  channel: Channel;
+  active: boolean;
+  onClick: () => void;
+  onClear: () => void;
+}) {
+  const hasMessages = loadMessages(channel.id).length > 0;
+
+  return (
+    <div className="group/item relative mx-1">
+      <button
+        onClick={onClick}
+        className="flex items-center gap-2 w-full px-3 py-1 rounded text-sm transition-colors"
+        style={{
+          color: active ? "var(--sidebar-text-active)" : "var(--sidebar-text)",
+          backgroundColor: active ? "var(--sidebar-active)" : "transparent",
+        }}
+        onMouseEnter={(e) => {
+          if (!active)
+            (e.currentTarget as HTMLElement).style.backgroundColor =
+              "var(--sidebar-hover)";
+        }}
+        onMouseLeave={(e) => {
+          if (!active)
+            (e.currentTarget as HTMLElement).style.backgroundColor =
+              "transparent";
+        }}
+      >
+        <span className="shrink-0">
+          <Hash size={15} />
+        </span>
+        <span className="truncate flex-1 text-left">{channel.name}</span>
+        {hasMessages && (
+          <span
+            className="w-2 h-2 rounded-full bg-green-400 shrink-0"
+            title="Has saved messages"
+          />
+        )}
+      </button>
+      <button
+        onClick={(e) => {
+          e.stopPropagation();
+          onClear();
+        }}
+        title="Clear history"
+        className="absolute right-2 top-1/2 -translate-y-1/2 opacity-0 group-hover/item:opacity-100 transition-opacity p-0.5 rounded hover:bg-white/20"
+        style={{ color: "var(--sidebar-text)" }}
+      >
+        <Trash2 size={13} />
+      </button>
+    </div>
+  );
+}
+
 function SidebarSection({ label }: { label: string }) {
   return (
     <div className="flex items-center gap-1 px-3 py-1 mb-0.5">
diff --git a/examples/headless-slack-demo/src/components/ToolCards.tsx b/examples/headless-slack-demo/src/components/ToolCards.tsx
new file mode 100644
index 0000000..04286a1
--- /dev/null
+++ b/examples/headless-slack-demo/src/components/ToolCards.tsx
@@ -0,0 +1,215 @@
+import {
+  Cloud,
+  Sun,
+  Wind,
+  Search,
+  BarChart3,
+  Calculator,
+  Clock,
+  ThumbsUp,
+} from "lucide-react";
+import { useState } from "react";
+
+// ── Weather Card ──────────────────────────────────────────────────
+
+export interface WeatherData {
+  city: string;
+  temperature: number;
+  unit: string;
+  condition: string;
+  humidity: number;
+  wind: number;
+}
+
+export function WeatherCard({ data }: { data: WeatherData }) {
+  const iconMap: Record<string, React.ReactNode> = {
+    Sunny: <Sun size={32} className="text-yellow-400" />,
+    Cloudy: <Cloud size={32} className="text-gray-400" />,
+    Rainy: <Cloud size={32} className="text-blue-400" />,
+    Windy: <Wind size={32} className="text-teal-400" />,
+    "Partly cloudy": <Cloud size={32} className="text-gray-300" />,
+  };
+
+  return (
+    <div className="border border-gray-200 rounded-xl p-4 bg-gradient-to-br from-blue-50 to-sky-50 w-64 mt-2">
+      <div className="flex items-center justify-between mb-3">
+        <div>
+          <p className="font-bold text-gray-900 text-base">{data.city}</p>
+          <p className="text-gray-500 text-xs">{data.condition}</p>
+        </div>
+        {iconMap[data.condition] ?? (
+          <Sun size={32} className="text-yellow-400" />
+        )}
+      </div>
+      <p className="text-4xl font-bold text-gray-900 mb-3">
+        {data.temperature}°{data.unit === "celsius" ? "C" : "F"}
+      </p>
+      <div className="flex gap-4 text-xs text-gray-500">
+        <span>💧 {data.humidity}%</span>
+        <span>💨 {data.wind} km/h</span>
+      </div>
+    </div>
+  );
+}
+
+// ── Search Results Card ───────────────────────────────────────────
+
+interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+export interface SearchData {
+  query: string;
+  results: SearchResult[];
+}
+
+export function SearchCard({ data }: { data: SearchData }) {
+  return (
+    <div className="border border-gray-200 rounded-xl p-3 bg-white mt-2 w-80">
+      <div className="flex items-center gap-2 mb-3 pb-2 border-b border-gray-100">
+        <Search size={14} className="text-blue-500" />
+        <span className="text-sm font-semibold text-gray-700">
+          Results for &quot;{data.query}&quot;
+        </span>
+      </div>
+      <div className="flex flex-col gap-3">
+        {data.results.map((r, i) => (
+          <div key={i}>
+            <p className="text-blue-600 text-sm font-medium hover:underline cursor-pointer">
+              {r.title}
+            </p>
+            <p className="text-green-700 text-xs">{r.url}</p>
+            <p className="text-gray-600 text-xs mt-0.5 leading-relaxed">
+              {r.snippet}
+            </p>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ── Poll Card ─────────────────────────────────────────────────────
+
+interface PollOption {
+  id: number;
+  text: string;
+  votes: number;
+}
+
+export interface PollData {
+  id: string;
+  question: string;
+  options: PollOption[];
+}
+
+export function PollCard({ data }: { data: PollData }) {
+  const [votes, setVotes] = useState<Record<number, number>>(
+    Object.fromEntries(data.options.map((o) => [o.id, o.votes])),
+  );
+  const [voted, setVoted] = useState<number | null>(null);
+  const total = Object.values(votes).reduce((a, b) => a + b, 0);
+
+  const vote = (id: number) => {
+    if (voted !== null) return;
+    setVotes((v) => ({ ...v, [id]: v[id] + 1 }));
+    setVoted(id);
+  };
+
+  return (
+    <div className="border border-gray-200 rounded-xl p-4 bg-white mt-2 w-72">
+      <div className="flex items-center gap-2 mb-3">
+        <BarChart3 size={15} className="text-purple-500" />
+        <p className="font-semibold text-gray-900 text-sm">{data.question}</p>
+      </div>
+      <div className="flex flex-col gap-2">
+        {data.options.map((o) => {
+          const count = votes[o.id];
+          const pct = total > 0 ? Math.round((count / total) * 100) : 0;
+          const isWinner =
+            voted !== null && count === Math.max(...Object.values(votes));
+          return (
+            <button
+              key={o.id}
+              onClick={() => vote(o.id)}
+              disabled={voted !== null}
+              className="relative text-left rounded-lg border border-gray-200 overflow-hidden disabled:cursor-default"
+            >
+              <div
+                className="absolute inset-0 transition-all duration-500"
+                style={{
+                  width: voted !== null ? `${pct}%` : "0%",
+                  backgroundColor: voted === o.id ? "#e0e7ff" : "#f3f4f6",
+                }}
+              />
+              <div className="relative flex items-center justify-between px-3 py-2">
+                <span className="text-sm text-gray-800">{o.text}</span>
+                <div className="flex items-center gap-1">
+                  {isWinner && voted !== null && (
+                    <ThumbsUp size={11} className="text-purple-500" />
+                  )}
+                  {voted !== null && (
+                    <span className="text-xs text-gray-500">{pct}%</span>
+                  )}
+                </div>
+              </div>
+            </button>
+          );
+        })}
+      </div>
+      {voted !== null && (
+        <p className="text-xs text-gray-400 mt-2 text-center">
+          {total} vote{total !== 1 ? "s" : ""}
+        </p>
+      )}
+    </div>
+  );
+}
+
+// ── Calculator Card ───────────────────────────────────────────────
+
+export interface CalcData {
+  expression: string;
+  result: number;
+}
+
+export function CalculatorCard({ data }: { data: CalcData }) {
+  return (
+    <div className="border border-gray-200 rounded-xl p-4 bg-gradient-to-br from-gray-50 to-gray-100 mt-2 w-56">
+      <div className="flex items-center gap-2 mb-2">
+        <Calculator size={14} className="text-gray-500" />
+        <span className="text-xs text-gray-500 font-medium">Calculator</span>
+      </div>
+      <p className="text-gray-400 text-sm font-mono">{data.expression}</p>
+      <p className="text-3xl font-bold text-gray-900 font-mono mt-1">
+        = {data.result}
+      </p>
+    </div>
+  );
+}
+
+// ── Time Card ─────────────────────────────────────────────────────
+
+export interface TimeData {
+  formatted: string;
+  iso: string;
+  timezone: string;
+}
+
+export function TimeCard({ data }: { data: TimeData }) {
+  return (
+    <div className="border border-gray-200 rounded-xl p-4 bg-gradient-to-br from-indigo-50 to-purple-50 mt-2 w-64">
+      <div className="flex items-center gap-2 mb-2">
+        <Clock size={14} className="text-indigo-500" />
+        <span className="text-xs text-indigo-500 font-medium">
+          {data.timezone}
+        </span>
+      </div>
+      <p className="text-gray-800 text-sm font-medium leading-relaxed">
+        {data.formatted}
+      </p>
+    </div>
+  );
+}
diff --git a/examples/headless-slack-demo/src/hooks/useTools.ts b/examples/headless-slack-demo/src/hooks/useTools.ts
new file mode 100644
index 0000000..5359418
--- /dev/null
+++ b/examples/headless-slack-demo/src/hooks/useTools.ts
@@ -0,0 +1,65 @@
+import { useTool } from "@yourgpt/copilot-sdk/react";
+
+export function useCalculatorTool() {
+  useTool({
+    name: "calculate",
+    description: "Perform a mathematical calculation",
+    inputSchema: {
+      type: "object",
+      properties: {
+        expression: {
+          type: "string",
+          description: 'Math expression to evaluate, e.g. "2 + 2 * 10"',
+        },
+      },
+      required: ["expression"],
+    },
+    handler: async ({ expression }: { expression: string }) => {
+      try {
+        // Safe eval using Function (client-side only)
+        const result = Function(`"use strict"; return (${expression})`)();
+        return { success: true, data: { expression, result } };
+      } catch {
+        return { success: false, error: `Invalid expression: ${expression}` };
+      }
+    },
+  });
+}
+
+export function useTimeTool() {
+  useTool({
+    name: "get_time",
+    description: "Get the current time and date, optionally for a timezone",
+    inputSchema: {
+      type: "object",
+      properties: {
+        timezone: {
+          type: "string",
+          description: 'Timezone (e.g. "America/New_York"). Defaults to local.',
+        },
+      },
+    },
+    handler: async ({ timezone }: { timezone?: string }) => {
+      const now = new Date();
+      const formatted = now.toLocaleString("en-US", {
+        timeZone: timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+      });
+      return {
+        success: true,
+        data: {
+          formatted,
+          iso: now.toISOString(),
+          timezone:
+            timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+        },
+      };
+    },
+  });
+}
diff --git a/examples/headless-slack-demo/src/lib/storage.ts b/examples/headless-slack-demo/src/lib/storage.ts
new file mode 100644
index 0000000..98a0d34
--- /dev/null
+++ b/examples/headless-slack-demo/src/lib/storage.ts
@@ -0,0 +1,22 @@
+import type { Message } from "@yourgpt/copilot-sdk/react";
+
+const PREFIX = "slack-demo:";
+
+export function loadMessages(channelId: string): Message[] {
+  try {
+    const raw = localStorage.getItem(`${PREFIX}${channelId}`);
+    return raw ? JSON.parse(raw) : [];
+  } catch {
+    return [];
+  }
+}
+
+export function saveMessages(channelId: string, messages: Message[]): void {
+  try {
+    localStorage.setItem(`${PREFIX}${channelId}`, JSON.stringify(messages));
+  } catch {}
+}
+
+export function clearMessages(channelId: string): void {
+  localStorage.removeItem(`${PREFIX}${channelId}`);
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e116fb0..6d17fe1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -41,13 +41,13 @@ importers:
         version: 2.1.1
       fumadocs-core:
         specifier: ^16.2.5
-        version: 16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(zod@4.3.6)
+        version: 16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6)
       fumadocs-mdx:
         specifier: ^14.1.1
-        version: 14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       fumadocs-ui:
         specifier: ^16.2.5
-        version: 16.2.5(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(tailwindcss@4.1.18)(zod@4.3.6)
+        version: 16.2.5(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(tailwindcss@4.1.18)(zod@4.3.6)
       lucide-react:
         specifier: ^0.562.0
         version: 0.562.0(react@19.2.1)
@@ -444,6 +444,9 @@ importers:
       react-dom:
         specifier: ^19.0.0
         version: 19.2.3(react@19.2.3)
+      react-router-dom:
+        specifier: ^7.0.0
+        version: 7.13.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
     devDependencies:
       '@tailwindcss/postcss':
         specifier: ^4
@@ -7006,6 +7009,23 @@ packages:
       '@types/react':
         optional: true
 
+  react-router-dom@7.13.1:
+    resolution: {integrity: sha512-UJnV3Rxc5TgUPJt2KJpo1Jpy0OKQr0AjgbZzBFjaPJcFOb2Y8jA5H3LT8HUJAiRLlWrEXWHbF1Z4SCZaQjWDHw==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
+  react-router@7.13.1:
+    resolution: {integrity: sha512-td+xP4X2/6BJvZoX6xw++A2DdEi++YypA69bJUV5oVvqf6/9/9nNlD70YO1e9d3MyamJEBQFEzk6mbfDYbqrSA==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+
   react-smooth@4.0.4:
     resolution: {integrity: sha512-gnGKTpYwqL0Iii09gHobNolvX4Kiq4PKx6eWBCYYix+8cdw+cGo3do906l1NBPKkSWx1DghC1dlWG9L2uGd61Q==}
     peerDependencies:
@@ -7261,6 +7281,9 @@ packages:
     resolution: {integrity: sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==}
     engines: {node: '>= 18'}
 
+  set-cookie-parser@2.7.2:
+    resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==}
+
   set-function-length@1.2.2:
     resolution: {integrity: sha512-pgRc4hJ4/sNjWCSS9AmnS40x3bNMDTknHgL5UaMBTMyJnU90EgWh1Rz+MC9eFu4BuN/UwZjKQuY/1v3rM7HMfg==}
     engines: {node: '>= 0.4'}
@@ -12293,7 +12316,7 @@ snapshots:
       '@next/eslint-plugin-next': 16.0.10
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
@@ -12314,7 +12337,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12334,7 +12357,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12356,7 +12379,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -12367,11 +12390,11 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1)):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -12382,18 +12405,18 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
-  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
+  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       debug: 3.2.7
     optionalDependencies:
       '@typescript-eslint/parser': 8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -12418,7 +12441,7 @@ snapshots:
       doctrine: 2.1.0
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
       hasown: 2.0.2
       is-core-module: 2.16.1
       is-glob: 4.0.3
@@ -12436,7 +12459,7 @@ snapshots:
       - eslint-import-resolver-webpack
       - supports-color
 
-  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -12893,7 +12916,7 @@ snapshots:
   fsevents@2.3.3:
     optional: true
 
-  fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(zod@4.3.6):
+  fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6):
     dependencies:
       '@formatjs/intl-localematcher': 0.6.2
       '@orama/orama': 3.1.17
@@ -12919,18 +12942,19 @@ snapshots:
       next: 16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0)
       react: 19.2.1
       react-dom: 19.2.1(react@19.2.1)
+      react-router: 7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1)
       zod: 4.3.6
     transitivePeerDependencies:
       - supports-color
 
-  fumadocs-mdx@14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)):
+  fumadocs-mdx@14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       '@mdx-js/mdx': 3.1.1
       '@standard-schema/spec': 1.1.0
       chokidar: 5.0.0
       esbuild: 0.27.1
       estree-util-value-to-estree: 3.5.0
-      fumadocs-core: 16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(zod@4.3.6)
+      fumadocs-core: 16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6)
       js-yaml: 4.1.1
       mdast-util-to-markdown: 2.1.2
       picocolors: 1.1.1
@@ -12950,7 +12974,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  fumadocs-ui@16.2.5(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(tailwindcss@4.1.18)(zod@4.3.6):
+  fumadocs-ui@16.2.5(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(tailwindcss@4.1.18)(zod@4.3.6):
     dependencies:
       '@radix-ui/react-accordion': 1.2.12(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.1(react@19.2.1))(react@19.2.1)
       '@radix-ui/react-collapsible': 1.1.12(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.1(react@19.2.1))(react@19.2.1)
@@ -12963,7 +12987,7 @@ snapshots:
       '@radix-ui/react-slot': 1.2.4(@types/react@18.3.27)(react@19.2.1)
       '@radix-ui/react-tabs': 1.1.13(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.1(react@19.2.1))(react@19.2.1)
       class-variance-authority: 0.7.1
-      fumadocs-core: 16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(zod@4.3.6)
+      fumadocs-core: 16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6)
       lodash.merge: 4.6.2
       next-themes: 0.4.6(react-dom@19.2.1(react@19.2.1))(react@19.2.1)
       postcss-selector-parser: 7.1.1
@@ -14902,6 +14926,29 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.27
 
+  react-router-dom@7.13.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3):
+    dependencies:
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+      react-router: 7.13.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+
+  react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1):
+    dependencies:
+      cookie: 1.1.1
+      react: 19.2.1
+      set-cookie-parser: 2.7.2
+    optionalDependencies:
+      react-dom: 19.2.1(react@19.2.1)
+    optional: true
+
+  react-router@7.13.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3):
+    dependencies:
+      cookie: 1.1.1
+      react: 19.2.3
+      set-cookie-parser: 2.7.2
+    optionalDependencies:
+      react-dom: 19.2.3(react@19.2.3)
+
   react-smooth@4.0.4(react-dom@19.2.3(react@19.2.3))(react@19.2.3):
     dependencies:
       fast-equals: 5.4.0
@@ -15308,6 +15355,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  set-cookie-parser@2.7.2: {}
+
   set-function-length@1.2.2:
     dependencies:
       define-data-property: 1.1.4

From a8a8e54e34cdd501bcec48f28b9d49fe21c099af Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 23 Mar 2026 18:24:05 +0530
Subject: [PATCH 46/72] fix(build): resolve all TypeScript and static-gen
 errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CopilotProvider.initialMessages: Message[] → UIMessage[] (aligns with
  useCopilot().messages return type; removes manual snake_case conversion)
- storage.ts: updated to use UIMessage accordingly
- Message.tsx MyMeta: extend Record<string, unknown> to satisfy generic constraint
- BranchTreePanel.tsx: fix bare @yourgpt/copilot-sdk import → /react subpath
- generative-ui/route.ts + tool-scale/route.ts: lazy-init runtime inside
  getRuntime() instead of module scope — prevents Next.js static page
  collection from throwing when API key env vars are absent

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../app/api/chat/generative-ui/route.ts       |  20 ++--
 .../app/api/chat/tool-scale/route.ts          | 113 +++++++++---------
 .../components/branching/BranchTreePanel.tsx  |   2 +-
 .../src/components/Message.tsx                |   2 +-
 .../headless-slack-demo/src/lib/storage.ts    |   6 +-
 .../src/react/provider/CopilotProvider.tsx    |  17 +--
 6 files changed, 77 insertions(+), 83 deletions(-)

diff --git a/examples/experimental/app/api/chat/generative-ui/route.ts b/examples/experimental/app/api/chat/generative-ui/route.ts
index 61da603..22b00c2 100644
--- a/examples/experimental/app/api/chat/generative-ui/route.ts
+++ b/examples/experimental/app/api/chat/generative-ui/route.ts
@@ -22,12 +22,12 @@ function resolveProvider() {
   );
 }
 
-const { provider, model, providerName } = resolveProvider();
-
-const runtime = createRuntime({
-  provider,
-  model,
-  systemPrompt: `You are a data-rich assistant that always renders visual UI components instead of plain text.
+function getRuntime() {
+  const { provider, model } = resolveProvider();
+  return createRuntime({
+    provider,
+    model,
+    systemPrompt: `You are a data-rich assistant that always renders visual UI components instead of plain text.
 
 You have a render_ui tool. Use it proactively based on the request:
 
@@ -67,14 +67,16 @@ new Chart(document.getElementById('c'), {
 Use html when asked for dashboards, interactive layouts, shadcn-style components, or anything combining charts + stats + cards in one view.
 For html, set the "height" field to fit the content — e.g. "600px" for dashboards, "320px" for a small card.
 Always prefer a structured type (table, stat, card) over html when the data fits a single type.`,
-  maxIterations: 3,
-});
+    maxIterations: 3,
+  });
+}
 
 export async function POST(request: Request) {
-  return runtime.handleRequest(request);
+  return getRuntime().handleRequest(request);
 }
 
 export async function GET() {
+  const { providerName, model } = resolveProvider();
   return Response.json({
     status: "ok",
     provider: providerName,
diff --git a/examples/experimental/app/api/chat/tool-scale/route.ts b/examples/experimental/app/api/chat/tool-scale/route.ts
index be8c8ea..3968e8e 100644
--- a/examples/experimental/app/api/chat/tool-scale/route.ts
+++ b/examples/experimental/app/api/chat/tool-scale/route.ts
@@ -31,72 +31,76 @@ function resolveProvider() {
   );
 }
 
-const { providerName, provider, model } = resolveProvider();
+// Suppress unused import warning — kept for commented-out OPENAI_API_KEY block above
+void createOpenAI;
 
-const runtime = createRuntime({
-  provider,
-  model,
-  debug: process.env.NODE_ENV === "development",
-  systemPrompt: `You are the Tool Scale Lab assistant.
+function getRuntime() {
+  const { provider, model } = resolveProvider();
+  return createRuntime({
+    provider,
+    model,
+    debug: process.env.NODE_ENV === "development",
+    systemPrompt: `You are the Tool Scale Lab assistant.
 
 You are testing a project with 100 tools: 30 server-side and 70 client-side.
 Use tools sparingly and intentionally.
 
 When tools are missing, rely on the search_tools meta-tool to discover deferred tools rather than guessing.
 Keep answers short and explain which class of tools you used when it helps the user understand tool selection behavior.`,
-  tools: toolScaleServerTools,
-  maxIterations: 6,
-  toolSearch: {
-    maxResults: 6,
-    exposeWhenExceeds: 12,
-    maxEagerTools: 6,
-    defaultProfile: "support",
-    includeUnprofiled: false,
-    profiles: {
-      support: {
-        include: [
-          "profile:support",
-          "category:knowledge",
-          "category:billing",
-          "category:browser",
-          "category:utility",
-        ],
-        exclude: ["group:admin"],
-      },
-      workspace: {
-        include: [
-          "profile:workspace",
-          "category:workspace",
-          "category:browser",
-          "category:analytics",
-          "category:utility",
-        ],
-      },
-      commerce: {
-        include: [
-          "profile:commerce",
-          "category:commerce",
-          "category:billing",
-          "group:actions",
-        ],
-      },
-      admin: {
-        include: [
-          "profile:admin",
-          "category:operations",
-          "category:analytics",
-          "category:utility",
-        ],
+    tools: toolScaleServerTools,
+    maxIterations: 6,
+    toolSearch: {
+      maxResults: 6,
+      exposeWhenExceeds: 12,
+      maxEagerTools: 6,
+      defaultProfile: "support",
+      includeUnprofiled: false,
+      profiles: {
+        support: {
+          include: [
+            "profile:support",
+            "category:knowledge",
+            "category:billing",
+            "category:browser",
+            "category:utility",
+          ],
+          exclude: ["group:admin"],
+        },
+        workspace: {
+          include: [
+            "profile:workspace",
+            "category:workspace",
+            "category:browser",
+            "category:analytics",
+            "category:utility",
+          ],
+        },
+        commerce: {
+          include: [
+            "profile:commerce",
+            "category:commerce",
+            "category:billing",
+            "group:actions",
+          ],
+        },
+        admin: {
+          include: [
+            "profile:admin",
+            "category:operations",
+            "category:analytics",
+            "category:utility",
+          ],
+        },
       },
+      toolChoice: "auto",
+      parallelCalls: false,
     },
-    toolChoice: "auto",
-    parallelCalls: false,
-  },
-});
+  });
+}
 
 export async function POST(request: Request) {
   try {
-    return await runtime.handleRequest(request);
+    return await getRuntime().handleRequest(request);
   } catch (error) {
     return Response.json(
       {
@@ -108,6 +112,7 @@ export async function POST(request: Request) {
 }
 
 export async function GET() {
+  const { providerName, model } = resolveProvider();
   return Response.json({
     status: "ok",
     provider: providerName,
diff --git a/examples/experimental/components/branching/BranchTreePanel.tsx b/examples/experimental/components/branching/BranchTreePanel.tsx
index 3e4f7d9..441c84e 100644
--- a/examples/experimental/components/branching/BranchTreePanel.tsx
+++ b/examples/experimental/components/branching/BranchTreePanel.tsx
@@ -3,7 +3,7 @@
 import { useCopilot } from "@yourgpt/copilot-sdk/react";
 import { cn } from "@/lib/utils";
 import type { UIMessage } from "@yourgpt/copilot-sdk/react";
-import type { BranchInfo } from "@yourgpt/copilot-sdk";
+import type { BranchInfo } from "@yourgpt/copilot-sdk/react";
 
 // ============================================
 // BranchTreePanel
diff --git a/examples/headless-slack-demo/src/components/Message.tsx b/examples/headless-slack-demo/src/components/Message.tsx
index d822ee9..5e3ab46 100644
--- a/examples/headless-slack-demo/src/components/Message.tsx
+++ b/examples/headless-slack-demo/src/components/Message.tsx
@@ -39,7 +39,7 @@ interface MessageProps {
   };
 }
 
-interface MyMeta {
+interface MyMeta extends Record<string, unknown> {
   thinking?: string;
   isThinking?: boolean;
   tools?: Record<string, "running" | "done" | "error">;
diff --git a/examples/headless-slack-demo/src/lib/storage.ts b/examples/headless-slack-demo/src/lib/storage.ts
index 98a0d34..bfcb53e 100644
--- a/examples/headless-slack-demo/src/lib/storage.ts
+++ b/examples/headless-slack-demo/src/lib/storage.ts
@@ -1,8 +1,8 @@
-import type { Message } from "@yourgpt/copilot-sdk/react";
+import type { UIMessage } from "@yourgpt/copilot-sdk/react";
 
 const PREFIX = "slack-demo:";
 
-export function loadMessages(channelId: string): Message[] {
+export function loadMessages(channelId: string): UIMessage[] {
   try {
     const raw = localStorage.getItem(`${PREFIX}${channelId}`);
     return raw ? JSON.parse(raw) : [];
@@ -11,7 +11,7 @@ export function loadMessages(channelId: string): Message[] {
   }
 }
 
-export function saveMessages(channelId: string, messages: Message[]): void {
+export function saveMessages(channelId: string, messages: UIMessage[]): void {
   try {
     localStorage.setItem(`${PREFIX}${channelId}`, JSON.stringify(messages));
   } catch {}
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 58a9460..19795e9 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -268,7 +268,7 @@ export interface CopilotProviderProps {
   /** Thread ID for conversation persistence */
   threadId?: string;
   /** Initial messages to populate the chat */
-  initialMessages?: Message[];
+  initialMessages?: UIMessage[];
   /** Callback when messages change */
   onMessagesChange?: (messages: Message[]) => void;
   /** Callback when an error occurs */
@@ -563,20 +563,7 @@ export function CopilotProvider({
   }
 
   if (chatRef.current === null) {
-    // Convert initial messages to UIMessage format
-    const uiInitialMessages: UIMessage[] | undefined = initialMessages?.map(
-      (m) => ({
-        id: m.id,
-        role: m.role,
-        content: m.content ?? "",
-        createdAt: m.created_at ?? new Date(),
-        attachments: m.metadata?.attachments as MessageAttachment[] | undefined,
-        toolCalls: m.tool_calls,
-        toolCallId: m.tool_call_id,
-        parentId: m.parent_id,
-        childrenIds: m.children_ids,
-      }),
-    );
+    const uiInitialMessages = initialMessages;
 
     chatRef.current = new ReactChatWithTools(
       {

From 211eb7b6340e5753828e68e8657fda5c1350fd4e Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 23 Mar 2026 18:25:01 +0530
Subject: [PATCH 47/72] feat: update package versions and add dependencies for
 yourgpt-server-demo example

- Bump version of @yourgpt/copilot-sdk to 2.1.5-alpha.5 and @yourgpt/llm-sdk to 2.1.4-alpha.1.
- Add new example project 'yourgpt-server-demo' with dependencies including @yourgpt/llm-sdk, cors, dotenv, and express, along with relevant devDependencies.
---
 packages/copilot-sdk/package.json |  2 +-
 packages/llm-sdk/package.json     |  2 +-
 pnpm-lock.yaml                    | 28 ++++++++++++++++++++++++++++
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index ee35e72..a444c4e 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.5-alpha.4",
+  "version": "2.1.5-alpha.5",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",
diff --git a/packages/llm-sdk/package.json b/packages/llm-sdk/package.json
index f37a38c..eabf3f2 100644
--- a/packages/llm-sdk/package.json
+++ b/packages/llm-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/llm-sdk",
-  "version": "2.1.4-alpha.0",
+  "version": "2.1.4-alpha.1",
   "description": "AI SDK for building AI Agents with any LLM",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e116fb0..187ceb4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1139,6 +1139,34 @@ importers:
         specifier: ^5
         version: 5.9.3
 
+  examples/yourgpt-server-demo:
+    dependencies:
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+    devDependencies:
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+
   packages/copilot-sdk:
     dependencies:
       '@base-ui/react':

From a562379d440be029ef244b892a552b96b993f6a0 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 23 Mar 2026 22:44:13 +0530
Subject: [PATCH 48/72] feat(chat): add className prop to ChatProps for custom
 avatar styling

---
 packages/copilot-sdk/src/ui/components/composed/chat/types.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
index 7754344..e480fa2 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
@@ -316,6 +316,8 @@ export type ChatProps = {
     fallback?: string;
     /** Custom avatar component - when provided, replaces the default avatar */
     component?: React.ReactNode;
+    /** Additional className applied to the avatar wrapper (e.g. "!bg-transparent") */
+    className?: string;
   };
   /** Loader variant for typing indicator */
   loaderVariant?:

From 5a44af9c38e5766bf306bfd9a7af470444fc7d17 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Wed, 25 Mar 2026 15:53:38 +0530
Subject: [PATCH 49/72] feat(chat): enhance session management with YourGPT
 integration

- Added YourGPT configuration support for automatic session creation.
- Introduced onCreateSession callback for custom session handling.
- Implemented methods for managing thread/session state: setActiveThread, renewSession, and getSessionStatus.
- Updated ChatWithTools and AbstractChat classes to utilize new session management features.
- Added useThread hook for simplified thread/session management in React components.
---
 .../copilot-sdk/src/chat/ChatWithTools.ts     |  36 +++-
 .../src/chat/classes/AbstractChat.ts          | 144 +++++++++++++-
 packages/copilot-sdk/src/chat/index.ts        |   1 +
 packages/copilot-sdk/src/chat/types/chat.ts   |  56 ++++++
 packages/copilot-sdk/src/chat/types/index.ts  |   1 +
 packages/copilot-sdk/src/react/hooks/index.ts |   3 +
 .../copilot-sdk/src/react/hooks/useThread.ts  |  83 ++++++++
 packages/copilot-sdk/src/react/index.ts       |   3 +
 .../src/react/internal/ReactChat.ts           |   7 +
 .../copilot-sdk/src/react/internal/useChat.ts |  44 ++++-
 .../message-history/session-persistence.ts    |  82 ++------
 .../message-history/useMessageHistory.ts      |  18 +-
 .../src/react/provider/CopilotProvider.tsx    | 174 ++++++++++++++---
 packages/llm-sdk/package.json                 |   5 +
 packages/llm-sdk/src/yourgpt/index.ts         | 178 ++++++++++++++++++
 packages/llm-sdk/tsup.config.ts               |   3 +
 16 files changed, 735 insertions(+), 103 deletions(-)
 create mode 100644 packages/copilot-sdk/src/react/hooks/useThread.ts
 create mode 100644 packages/llm-sdk/src/yourgpt/index.ts

diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index a858854..4b3b12d 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -21,7 +21,7 @@ import type { Resolvable } from "../core/utils/resolvable";
 import { createLogger } from "../core/utils/logger";
 import { AbstractChat } from "./classes/AbstractChat";
 import { AbstractAgentLoop } from "./AbstractAgentLoop";
-import type { ChatConfig, ChatCallbacks } from "./types";
+import type { ChatConfig, ChatCallbacks, YourGPTConfig } from "./types";
 import type { UIMessage } from "./types/message";
 import type { ToolExecution, AgentLoopCallbacks } from "./types/tool";
 import type { ChatState } from "./interfaces/ChatState";
@@ -48,6 +48,13 @@ export interface ChatWithToolsConfig {
   body?: Resolvable<Record<string, unknown>>;
   /** Thread ID for conversation persistence */
   threadId?: string;
+  /**
+   * Called once before the first message on a new thread to create a session.
+   * The returned value IS the thread ID. Only called when threadId is not set.
+   */
+  onCreateSession?: () => string | Promise<string>;
+  /** YourGPT config — enables automatic session creation */
+  yourgptConfig?: YourGPTConfig;
   /** Enable debug logging */
   debug?: boolean;
   /** Initial messages */
@@ -140,6 +147,8 @@ export class ChatWithTools {
       body: config.body,
       optimization: config.optimization,
       threadId: config.threadId,
+      onCreateSession: config.onCreateSession,
+      yourgptConfig: config.yourgptConfig,
       debug: config.debug,
       initialMessages: config.initialMessages,
       state: config.state,
@@ -154,6 +163,8 @@ export class ChatWithTools {
         onToolCalls: callbacks.onToolCalls,
         onFinish: callbacks.onFinish,
         onContextUsageChange: callbacks.onContextUsageChange,
+        onThreadChange: callbacks.onThreadChange,
+        onSessionStatusChange: callbacks.onSessionStatusChange,
         // Server-side tool callbacks - track in agentLoop for UI display
         // IMPORTANT: Only track tools that are NOT registered client-side
         // Client-side tools are tracked via executeToolCalls() path
@@ -474,6 +485,29 @@ export class ChatWithTools {
     this.chat.setContext(context);
   }
 
+  /**
+   * Switch to a different thread (or start a new one).
+   * Pass the session/thread ID from persistence to reuse it, or null to start fresh.
+   */
+  setActiveThread(id: string | null): void {
+    this.chat.setActiveThread(id);
+  }
+
+  /**
+   * Force a new session on the next sendMessage.
+   * Call this when the current session has expired or credits are exhausted.
+   */
+  renewSession(): void {
+    this.chat.renewSession();
+  }
+
+  /**
+   * Current session creation status.
+   */
+  getSessionStatus(): "idle" | "creating" | "ready" | "error" {
+    return this.chat.getSessionStatus();
+  }
+
   /**
    * Set system prompt dynamically
    */
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 0b37bdd..51b2de7 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -36,6 +36,8 @@ import {
   generateMessageId,
   streamStateToMessage,
 } from "../functions/message";
+import { generateThreadId } from "../../core/utils/id";
+import { resolveValue } from "../../core/utils/resolvable";
 import {
   createStreamState,
   processStreamChunk,
@@ -85,6 +87,9 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
   protected callbacks: ChatCallbacks<T>;
   protected optimizer: ChatContextOptimizer;
   protected lastContextUsage: ContextUsage | null = null;
+  private onCreateSession?: () => string | Promise<string>;
+  private sessionInitPromise: Promise<string> | null = null;
+  private sessionStatus: "idle" | "creating" | "ready" | "error" = "idle";
 
   // Event handlers
   private eventHandlers = new Map<
@@ -106,6 +111,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       threadId: init.threadId,
       debug: init.debug,
       optimization: init.optimization,
+      yourgptConfig: init.yourgptConfig,
     };
 
     // Use provided state or create default
@@ -127,6 +133,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     // Store callbacks
     this.callbacks = init.callbacks ?? {};
     this.optimizer = new ChatContextOptimizer(init.optimization);
+    this.onCreateSession = init.onCreateSession;
 
     // Set initial messages
     if (init.initialMessages?.length) {
@@ -223,7 +230,9 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         parentId: newParentId,
       }) as T;
 
-      // Add to state
+      // Add user message + placeholder to state FIRST so the UI transitions to
+      // chat view immediately — session init (createSession network request) runs
+      // concurrently while the user already sees their message and the loader.
       this.state.pushMessage(userMessage);
       this.state.status = "submitted";
       this.state.error = undefined;
@@ -249,6 +258,48 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       this.callbacks.onMessagesChange?.(this._allMessages());
       this.callbacks.onStatusChange?.("submitted");
 
+      // Lazy session init — only when threadId is not set AND session config is present.
+      // threadId IS the session ID: if it's set (from setActiveThread or a previous session),
+      // it is trusted as-is and no session creation call is made.
+      const needsSession =
+        !this.config.threadId &&
+        (!!this.config.yourgptConfig || !!this.onCreateSession);
+      if (needsSession) {
+        if (!this.sessionInitPromise) {
+          this.setSessionStatus("creating");
+          this.sessionInitPromise = (
+            this.onCreateSession
+              ? Promise.resolve(this.onCreateSession())
+              : this._defaultCreateSession()
+          )
+            .then((id) => {
+              this.callbacks.onThreadChange?.(id);
+              this.setSessionStatus("ready");
+              return id;
+            })
+            .catch((err) => {
+              this.setSessionStatus("error");
+              this.sessionInitPromise = null;
+              throw err;
+            });
+        }
+        this.config.threadId = await this.sessionInitPromise;
+        this.debug("sendMessage", { threadId: this.config.threadId });
+      }
+      // No session config and no threadId — generate a local ID (no network call).
+      // Skip this when onCreateSession/yourgptConfig is provided: if we reach here
+      // without a threadId it means session creation was not triggered (threadId was
+      // just cleared by setActiveThread) — proceed without one and let the next
+      // sendMessage pick it up after the session is assigned.
+      if (
+        !this.config.threadId &&
+        !this.onCreateSession &&
+        !this.config.yourgptConfig
+      ) {
+        this.config.threadId = generateThreadId();
+        this.setSessionStatus("ready");
+      }
+
       // Yield to allow UI to render loading state (important for non-streaming)
       await Promise.resolve();
 
@@ -767,6 +818,48 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     this.dynamicContext = context;
   }
 
+  /**
+   * Switch to a different thread (or start a new one).
+   *
+   * - Pass the session/thread ID from persistence → used as-is, no session creation call.
+   * - Pass null → threadId cleared, new session created on first sendMessage.
+   *
+   * The session ID IS the thread ID: whatever is stored in persistence is passed here directly.
+   */
+  setActiveThread(id: string | null): void {
+    this.config.threadId = id ?? undefined;
+    this.sessionInitPromise = null;
+    this.setSessionStatus(id ? "ready" : "idle");
+  }
+
+  /**
+   * Force a new session to be created on the next sendMessage.
+   * Call this when the current session has expired or credits are exhausted.
+   * After calling this, the next sendMessage will invoke onCreateSession/yourgptConfig
+   * again and onThreadChange will fire with the new session ID.
+   */
+  renewSession(): void {
+    this.config.threadId = undefined;
+    this.sessionInitPromise = null;
+    this.setSessionStatus("idle");
+  }
+
+  private setSessionStatus(
+    status: "idle" | "creating" | "ready" | "error",
+  ): void {
+    if (this.sessionStatus !== status) {
+      this.sessionStatus = status;
+      this.callbacks.onSessionStatusChange?.(status);
+    }
+  }
+
+  /**
+   * Get the current session creation status.
+   */
+  getSessionStatus(): "idle" | "creating" | "ready" | "error" {
+    return this.sessionStatus;
+  }
+
   /**
    * Set system prompt dynamically
    * This allows updating the system prompt after initialization
@@ -808,6 +901,55 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
     }
   }
 
+  /**
+   * Default session creation via yourgptConfig.
+   * Only called when yourgptConfig is set and no onCreateSession is provided.
+   * The returned session_uid IS the thread ID going forward.
+   */
+  private async _defaultCreateSession(): Promise<string> {
+    if (!this.config.yourgptConfig) {
+      throw new Error(
+        "[copilot-sdk] _defaultCreateSession called without yourgptConfig",
+      );
+    }
+    const {
+      apiKey,
+      widgetUid,
+      endpoint = "https://api.yourgpt.ai",
+    } = this.config.yourgptConfig;
+    const base = endpoint.replace(/\/$/, "");
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10_000);
+    try {
+      const res = await fetch(`${base}/chatbot/v1/copilot-sdk/createSession`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "api-key": apiKey,
+        },
+        body: JSON.stringify({ widget_uid: widgetUid }),
+        signal: controller.signal,
+      });
+      const data = await res.json();
+      const d = data?.data ?? data;
+      const id = d?.session_uid ?? d?.id;
+      if (!id)
+        throw new Error(
+          "[copilot-sdk] createSession failed: " + JSON.stringify(data),
+        );
+      return String(id);
+    } catch (err) {
+      if ((err as Error)?.name === "AbortError") {
+        throw new Error(
+          "[copilot-sdk] createSession timed out after 10s — check your endpoint/network",
+        );
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
   /**
    * Build the request payload
    */
diff --git a/packages/copilot-sdk/src/chat/index.ts b/packages/copilot-sdk/src/chat/index.ts
index 13c4805..4398cdc 100644
--- a/packages/copilot-sdk/src/chat/index.ts
+++ b/packages/copilot-sdk/src/chat/index.ts
@@ -30,6 +30,7 @@ export type {
   ChatCallbacks,
   ChatInit,
   SendMessageOptions,
+  YourGPTConfig,
   // Tool types
   ToolCallInfo,
   RawToolCall,
diff --git a/packages/copilot-sdk/src/chat/types/chat.ts b/packages/copilot-sdk/src/chat/types/chat.ts
index 318027e..195543f 100644
--- a/packages/copilot-sdk/src/chat/types/chat.ts
+++ b/packages/copilot-sdk/src/chat/types/chat.ts
@@ -19,6 +19,18 @@ import type { UIMessage } from "./message";
  */
 export type ChatStatus = "ready" | "submitted" | "streaming" | "error";
 
+/**
+ * YourGPT configuration for automatic session management
+ */
+export interface YourGPTConfig {
+  /** YourGPT API key (sent as api-key header) */
+  apiKey: string;
+  /** Widget UID to scope sessions to */
+  widgetUid: string;
+  /** API base URL (default: https://api.yourgpt.ai) */
+  endpoint?: string;
+}
+
 /**
  * Chat configuration
  *
@@ -54,6 +66,37 @@ export interface ChatConfig {
   body?: Resolvable<Record<string, unknown>>;
   /** Thread ID for conversation persistence */
   threadId?: string;
+  /**
+   * Called once before the first message on a new thread to obtain a session/thread ID.
+   * The returned value IS the thread ID — session and thread are the same identity.
+   *
+   * Only called when `config.threadId` is not set (new thread).
+   * If `threadId` is already provided, this is skipped entirely.
+   * Takes priority over `yourgptConfig` when both are provided.
+   *
+   * @example Async server session
+   * ```ts
+   * onCreateSession={async () => {
+   *   const res = await fetch('/api/sessions', { method: 'POST' })
+   *   return (await res.json()).id
+   * }}
+   * ```
+   */
+  onCreateSession?: () => string | Promise<string>;
+  /**
+   * YourGPT config — enables automatic session creation with zero boilerplate.
+   * When provided, the SDK calls YourGPT's createSession API before the first
+   * message and uses the returned session_uid as `threadId`.
+   *
+   * @example
+   * ```tsx
+   * yourgptConfig={{
+   *   apiKey: process.env.YOURGPT_API_KEY,
+   *   widgetUid: widgetUid,
+   * }}
+   * ```
+   */
+  yourgptConfig?: YourGPTConfig;
   /** Enable debug logging */
   debug?: boolean;
   /** Available tools (passed to LLM) */
@@ -106,6 +149,19 @@ export interface ChatCallbacks<T extends UIMessage = UIMessage> {
   onFinish?: (messages: T[]) => void;
   /** Called when prompt context usage changes */
   onContextUsageChange?: (usage: ContextUsage) => void;
+  /**
+   * Called once when a new session/thread ID is assigned (null → sessionId transition).
+   * Use this to persist the session ID in your storage layer.
+   * The returned ID is the same as the threadId that will be used for all subsequent requests.
+   */
+  onThreadChange?: (id: string) => void;
+  /**
+   * Called when the session creation status changes.
+   * Use this to show/hide a spinner while the session is being created.
+   */
+  onSessionStatusChange?: (
+    status: "idle" | "creating" | "ready" | "error",
+  ) => 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) */
diff --git a/packages/copilot-sdk/src/chat/types/index.ts b/packages/copilot-sdk/src/chat/types/index.ts
index 2b78396..d163c19 100644
--- a/packages/copilot-sdk/src/chat/types/index.ts
+++ b/packages/copilot-sdk/src/chat/types/index.ts
@@ -20,6 +20,7 @@ export type {
   ChatInit,
   SendMessageOptions,
   ServerToolInfo,
+  YourGPTConfig,
 } from "./chat";
 
 // Tool types
diff --git a/packages/copilot-sdk/src/react/hooks/index.ts b/packages/copilot-sdk/src/react/hooks/index.ts
index 945a825..9e10779 100644
--- a/packages/copilot-sdk/src/react/hooks/index.ts
+++ b/packages/copilot-sdk/src/react/hooks/index.ts
@@ -75,6 +75,9 @@ export {
   type UseThreadManagerReturn,
 } from "./useThreadManager";
 
+// Thread/Session hook
+export { useThread, type UseThreadReturn } from "./useThread";
+
 // MCP (Model Context Protocol) Hooks
 export {
   useMCPClient,
diff --git a/packages/copilot-sdk/src/react/hooks/useThread.ts b/packages/copilot-sdk/src/react/hooks/useThread.ts
new file mode 100644
index 0000000..60846ff
--- /dev/null
+++ b/packages/copilot-sdk/src/react/hooks/useThread.ts
@@ -0,0 +1,83 @@
+/**
+ * useThread — Session/thread management hook
+ *
+ * Provides clean semantics for managing the active session/thread.
+ * When yourgptConfig or onCreateSession is configured, the session ID
+ * IS the thread ID — they are the same identity.
+ *
+ * Use this hook instead of calling setActiveThread/renewSession directly.
+ */
+
+import { useCopilot } from "../provider/CopilotProvider";
+
+export interface UseThreadReturn {
+  /**
+   * Current session/thread ID.
+   * undefined until the first session is created (new thread not yet sent).
+   */
+  threadId: string | undefined;
+
+  /**
+   * Current session creation status.
+   * - "idle"     — no session config, or threadId already set
+   * - "creating" — session creation request in flight
+   * - "ready"    — threadId is set and usable
+   * - "error"    — session creation failed
+   */
+  sessionStatus: "idle" | "creating" | "ready" | "error";
+
+  /**
+   * Switch to an existing thread/session.
+   * Pass the session ID from your persistence layer — it is used as-is,
+   * no new session creation call is made.
+   */
+  switchThread: (sessionId: string) => void;
+
+  /**
+   * Start a fresh thread.
+   * Clears the current session; a new session is created on the next sendMessage.
+   * onThreadChange fires with the new session ID once it is assigned.
+   */
+  newThread: () => void;
+
+  /**
+   * Force a new session to be created on the next sendMessage.
+   * Call this when the current session has expired or credits are exhausted.
+   * onThreadChange fires with the new session ID once it is assigned.
+   */
+  renewSession: () => void;
+}
+
+/**
+ * useThread — Clean hook for session/thread management
+ *
+ * @example
+ * ```tsx
+ * function ChatHeader() {
+ *   const { threadId, sessionStatus, newThread, switchThread, renewSession } = useThread();
+ *
+ *   const loadThread = (stored: { sessionId: string }) => {
+ *     switchThread(stored.sessionId);   // session ID IS the thread ID
+ *   };
+ *
+ *   return (
+ *     <>
+ *       {sessionStatus === "creating" && <Spinner />}
+ *       <button onClick={newThread}>New Chat</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useThread(): UseThreadReturn {
+  const { threadId, setActiveThread, renewSession, sessionStatus } =
+    useCopilot();
+
+  return {
+    threadId,
+    sessionStatus,
+    switchThread: setActiveThread,
+    newThread: () => setActiveThread(null),
+    renewSession,
+  };
+}
diff --git a/packages/copilot-sdk/src/react/index.ts b/packages/copilot-sdk/src/react/index.ts
index 2dc7792..84142e2 100644
--- a/packages/copilot-sdk/src/react/index.ts
+++ b/packages/copilot-sdk/src/react/index.ts
@@ -53,6 +53,9 @@ export {
   type UseToolConfig,
   type UseToolWithSchemaConfig,
   type UseToolExecutorReturn,
+  // Thread/Session
+  useThread,
+  type UseThreadReturn,
 } from "./hooks";
 
 // Knowledge Base
diff --git a/packages/copilot-sdk/src/react/internal/ReactChat.ts b/packages/copilot-sdk/src/react/internal/ReactChat.ts
index 803e2c3..2b498a3 100644
--- a/packages/copilot-sdk/src/react/internal/ReactChat.ts
+++ b/packages/copilot-sdk/src/react/internal/ReactChat.ts
@@ -14,6 +14,7 @@ import {
   type UIMessage,
   type ChatInit,
   type ChatEventHandler,
+  type YourGPTConfig,
 } from "../../chat";
 import { ReactChatState } from "./ReactChatState";
 import type { BranchInfo } from "../../chat/branching";
@@ -35,6 +36,10 @@ export interface ReactChatConfig {
   llm?: ChatConfig["llm"];
   /** Thread ID */
   threadId?: string;
+  /** Called once before first message to obtain a session/thread ID */
+  onCreateSession?: () => string | Promise<string>;
+  /** YourGPT config — enables automatic session creation */
+  yourgptConfig?: YourGPTConfig;
   /** Enable streaming (default: true) */
   streaming?: boolean;
   /** Request headers */
@@ -76,6 +81,8 @@ export class ReactChat extends AbstractChat<UIMessage> {
       systemPrompt: config.systemPrompt,
       llm: config.llm,
       threadId: config.threadId,
+      onCreateSession: config.onCreateSession,
+      yourgptConfig: config.yourgptConfig,
       streaming: config.streaming ?? true,
       headers: config.headers,
       initialMessages: config.initialMessages,
diff --git a/packages/copilot-sdk/src/react/internal/useChat.ts b/packages/copilot-sdk/src/react/internal/useChat.ts
index c64b602..6e3b703 100644
--- a/packages/copilot-sdk/src/react/internal/useChat.ts
+++ b/packages/copilot-sdk/src/react/internal/useChat.ts
@@ -122,6 +122,17 @@ export interface UseChatReturn {
 export function useChat(config: UseChatConfig): UseChatReturn {
   // Create and store ReactChat instance
   const chatRef = useRef<ReactChat | null>(null);
+  const isThreadIdControlled = Object.prototype.hasOwnProperty.call(
+    config,
+    "threadId",
+  );
+  const lastControlledThreadIdRef = useRef<{
+    controlled: boolean;
+    value: string | undefined;
+  }>({
+    controlled: isThreadIdControlled,
+    value: config.threadId,
+  });
 
   // Local input state (UI concern)
   const [input, setInput] = useState("");
@@ -138,6 +149,8 @@ export function useChat(config: UseChatConfig): UseChatReturn {
       systemPrompt: config.systemPrompt,
       llm: config.llm,
       threadId: config.threadId,
+      onCreateSession: config.onCreateSession,
+      yourgptConfig: config.yourgptConfig,
       streaming: config.streaming,
       headers: config.headers,
       initialMessages: config.initialMessages,
@@ -151,6 +164,28 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     });
   }
 
+  // Keep the chat instance aligned with controlled threadId prop changes.
+  useEffect(() => {
+    const prev = lastControlledThreadIdRef.current;
+    const controlChanged = prev.controlled !== isThreadIdControlled;
+    const valueChanged = prev.value !== config.threadId;
+
+    if (!controlChanged && !valueChanged) {
+      return;
+    }
+
+    lastControlledThreadIdRef.current = {
+      controlled: isThreadIdControlled,
+      value: config.threadId,
+    };
+
+    if (!isThreadIdControlled) {
+      return;
+    }
+
+    chatRef.current?.setActiveThread(config.threadId ?? null);
+  }, [config.threadId, isThreadIdControlled]);
+
   // Subscribe to all state changes with useSyncExternalStore
   const messages = useSyncExternalStore(
     chatRef.current.subscribe,
@@ -216,12 +251,9 @@ export function useChat(config: UseChatConfig): UseChatReturn {
     chatRef.current?.switchBranch(messageId);
   }, []);
 
-  const getBranchInfo = useCallback(
-    (messageId: string): BranchInfo | null => {
-      return chatRef.current?.getBranchInfo(messageId) ?? null;
-    },
-    [],
-  );
+  const getBranchInfo = useCallback((messageId: string): BranchInfo | null => {
+    return chatRef.current?.getBranchInfo(messageId) ?? null;
+  }, []);
 
   const editMessage = useCallback(
     async (messageId: string, newContent: string) => {
diff --git a/packages/copilot-sdk/src/react/message-history/session-persistence.ts b/packages/copilot-sdk/src/react/message-history/session-persistence.ts
index 9eb1431..2787acf 100644
--- a/packages/copilot-sdk/src/react/message-history/session-persistence.ts
+++ b/packages/copilot-sdk/src/react/message-history/session-persistence.ts
@@ -1,17 +1,12 @@
 /**
  * Session Persistence
  *
- * Phase 4: Persist display history + compaction state across reloads.
- * - compactionState → localStorage (small, fast, sync on init)
- * - displayMessages → IndexedDB (can be large, async)
+ * Persist display history + compaction state across reloads.
+ * Everything uses localStorage — no IndexedDB.
  */
 
 import type { DisplayMessage, SessionCompactionState } from "./types";
 
-const IDB_DB_NAME = "copilot-sdk";
-const IDB_STORE = "sessions";
-const IDB_VERSION = 1;
-
 // ── localStorage: compaction state ───────────────────────────────
 
 export function saveCompactionState(
@@ -52,75 +47,38 @@ export function clearCompactionState(storageKey: string): void {
   }
 }
 
-// ── IndexedDB: display messages ───────────────────────────────────
-
-function openDB(): Promise<IDBDatabase> {
-  return new Promise((resolve, reject) => {
-    const req = indexedDB.open(IDB_DB_NAME, IDB_VERSION);
-
-    req.onupgradeneeded = () => {
-      req.result.createObjectStore(IDB_STORE, { keyPath: "sessionId" });
-    };
-
-    req.onsuccess = () => resolve(req.result);
-    req.onerror = () => reject(req.error);
-  });
-}
+// ── localStorage: display messages ───────────────────────────────
 
-export async function saveDisplayMessages(
+export function saveDisplayMessages(
   storageKey: string,
   messages: DisplayMessage[],
-): Promise<void> {
+): void {
   try {
-    const db = await openDB();
-    const tx = db.transaction(IDB_STORE, "readwrite");
-    tx.objectStore(IDB_STORE).put({
-      sessionId: storageKey,
-      messages,
-      savedAt: Date.now(),
-    });
-    await new Promise<void>((res, rej) => {
-      tx.oncomplete = () => res();
-      tx.onerror = () => rej(tx.error);
-    });
-    db.close();
+    localStorage.setItem(
+      `${storageKey}-messages`,
+      JSON.stringify({ messages, savedAt: Date.now() }),
+    );
   } catch {
-    // IndexedDB unavailable — fail silently
+    // localStorage unavailable or quota exceeded — fail silently
   }
 }
 
-export async function loadDisplayMessages(
+export function loadDisplayMessages(
   storageKey: string,
-): Promise<DisplayMessage[] | null> {
+): DisplayMessage[] | null {
   try {
-    const db = await openDB();
-    const tx = db.transaction(IDB_STORE, "readonly");
-    const req = tx.objectStore(IDB_STORE).get(storageKey);
-
-    const result = await new Promise<
-      { messages: DisplayMessage[] } | undefined
-    >((res, rej) => {
-      req.onsuccess = () => res(req.result as { messages: DisplayMessage[] });
-      req.onerror = () => rej(req.error);
-    });
-
-    db.close();
-    return result?.messages ?? null;
+    const raw = localStorage.getItem(`${storageKey}-messages`);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as { messages: DisplayMessage[] };
+    return parsed?.messages ?? null;
   } catch {
     return null;
   }
 }
 
-export async function clearDisplayMessages(storageKey: string): Promise<void> {
+export function clearDisplayMessages(storageKey: string): void {
   try {
-    const db = await openDB();
-    const tx = db.transaction(IDB_STORE, "readwrite");
-    tx.objectStore(IDB_STORE).delete(storageKey);
-    await new Promise<void>((res, rej) => {
-      tx.oncomplete = () => res();
-      tx.onerror = () => rej(tx.error);
-    });
-    db.close();
+    localStorage.removeItem(`${storageKey}-messages`);
   } catch {
     // ignore
   }
@@ -128,7 +86,7 @@ export async function clearDisplayMessages(storageKey: string): Promise<void> {
 
 // ── Full session clear ────────────────────────────────────────────
 
-export async function clearSession(storageKey: string): Promise<void> {
+export function clearSession(storageKey: string): void {
   clearCompactionState(storageKey);
-  await clearDisplayMessages(storageKey);
+  clearDisplayMessages(storageKey);
 }
diff --git a/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts b/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts
index 9d065cd..3f1ff56 100644
--- a/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts
+++ b/packages/copilot-sdk/src/react/message-history/useMessageHistory.ts
@@ -86,18 +86,16 @@ export function useMessageHistory(
     [messages],
   );
 
-  // Restore persisted display messages on cold start (async)
+  // Restore persisted display messages on cold start
   const restoredRef = useRef(false);
   useEffect(() => {
     if (!config.persistSession || restoredRef.current) return;
     restoredRef.current = true;
-    loadDisplayMessages(storageKey).then((saved) => {
-      if (saved?.length && messages.length === 0) {
-        // Only restore if current session is empty
-        // (useCopilot().setMessages would be called here in a real integration)
-        // For now: restored messages are available via displayMessages after setMessages
-      }
-    });
+    const saved = loadDisplayMessages(storageKey);
+    if (saved?.length && messages.length === 0) {
+      // Only restore if current session is empty
+      // (useCopilot().setMessages would be called here in a real integration)
+    }
   }, [config.persistSession, storageKey, messages.length]);
 
   // Persist display messages when they change
@@ -295,10 +293,10 @@ export function useMessageHistory(
     setCompactionState((prev) => ({ ...prev, workingMemory: [] }));
   }, []);
 
-  const resetSession = useCallback(async () => {
+  const resetSession = useCallback(() => {
     setCompactionState(DEFAULT_COMPACTION_STATE);
     if (config.persistSession) {
-      await clearSession(storageKey);
+      clearSession(storageKey);
     }
   }, [config.persistSession, storageKey]);
 
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 19795e9..230875f 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -33,7 +33,12 @@ import type { MCPServerConfig } from "../../mcp/types";
 import type { Resolvable } from "../../core/utils/resolvable";
 import { createLogger } from "../../core/utils/logger";
 
-import type { UIMessage, ToolExecution, StreamChunk } from "../../chat";
+import type {
+  UIMessage,
+  ToolExecution,
+  StreamChunk,
+  YourGPTConfig,
+} from "../../chat";
 
 import {
   ReactChatWithTools,
@@ -267,6 +272,37 @@ export interface CopilotProviderProps {
   tools?: ToolsConfig;
   /** Thread ID for conversation persistence */
   threadId?: string;
+  /**
+   * Called once before the first message on a new thread to create a session.
+   * The returned value IS the thread ID — session and thread are the same identity.
+   * Only called when `threadId` is not set. If `threadId` is provided, this is skipped.
+   * Takes priority over `yourgptConfig`.
+   *
+   * @example
+   * ```tsx
+   * onCreateSession={async () => {
+   *   const res = await fetch('/api/sessions', { method: 'POST', headers })
+   *   return (await res.json()).id
+   * }}
+   * ```
+   */
+  onCreateSession?: () => string | Promise<string>;
+  /**
+   * Called when a new session/thread ID is assigned (new thread created).
+   * Use this to persist the session ID in your storage layer.
+   */
+  onThreadChange?: (id: string) => void;
+  /**
+   * YourGPT config — enables automatic session creation with zero boilerplate.
+   * The SDK calls YourGPT's createSession API before the first message and
+   * uses the returned session_uid as `threadId`.
+   *
+   * @example
+   * ```tsx
+   * yourgptConfig={{ apiKey: "your-api-key", widgetUid: widgetUid }}
+   * ```
+   */
+  yourgptConfig?: YourGPTConfig;
   /** Initial messages to populate the chat */
   initialMessages?: UIMessage[];
   /** Callback when messages change */
@@ -439,6 +475,19 @@ export interface CopilotContextValue {
 
   // Config
   threadId?: string;
+  /**
+   * Switch to a different thread (or start a new one).
+   * Pass the session/thread ID from persistence to reuse it (no new session call),
+   * or null to start a fresh thread (new session created on first sendMessage).
+   */
+  setActiveThread: (id: string | null) => void;
+  /**
+   * Force a new session to be created on the next sendMessage.
+   * Call when the current session has expired or credits are exhausted.
+   */
+  renewSession: () => void;
+  /** Current session creation status */
+  sessionStatus: "idle" | "creating" | "ready" | "error";
   /**
    * Runtime URL configuration.
    * Can be a static string or getter function (matches what was passed to provider).
@@ -487,26 +536,35 @@ export function useCopilot(): CopilotContextValue {
 // Provider Component
 // ============================================
 
-export function CopilotProvider({
-  children,
-  runtimeUrl,
-  systemPrompt,
-  tools: toolsConfig,
-  threadId,
-  initialMessages,
-  onMessagesChange,
-  onError,
-  streaming,
-  headers,
-  body,
-  debug = false,
-  maxIterations,
-  maxIterationsMessage,
-  mcpServers,
-  optimization,
-  messageHistory,
-  skills,
-}: CopilotProviderProps) {
+export function CopilotProvider(props: CopilotProviderProps) {
+  const {
+    children,
+    runtimeUrl,
+    systemPrompt,
+    tools: toolsConfig,
+    threadId,
+    onCreateSession,
+    onThreadChange,
+    yourgptConfig,
+    initialMessages,
+    onMessagesChange,
+    onError,
+    streaming,
+    headers,
+    body,
+    debug = false,
+    maxIterations,
+    maxIterationsMessage,
+    mcpServers,
+    optimization,
+    messageHistory,
+    skills,
+  } = props;
+  const isThreadIdControlled = Object.prototype.hasOwnProperty.call(
+    props,
+    "threadId",
+  );
+
   // ── Headless primitives ──────────────────────────────────────────────────
 
   // Stream event listeners — Set of handlers subscribed via useCopilotEvent()
@@ -547,7 +605,23 @@ export function CopilotProvider({
   // Tool Executions State (for React reactivity)
   // ============================================
   const [toolExecutions, setToolExecutions] = useState<ToolExecution[]>([]);
+  const [sessionStatus, setSessionStatus] = useState<
+    "idle" | "creating" | "ready" | "error"
+  >(() => (threadId ? "ready" : "idle"));
   const [agentIteration, setAgentIteration] = useState(0);
+  // Track the ACTUAL thread/session ID assigned by the chat instance.
+  // This is different from the `threadId` prop — it updates reactively when
+  // onCreateSession fires and a new session ID is assigned.
+  const [actualThreadId, setActualThreadId] = useState<string | undefined>(
+    threadId,
+  );
+  const lastControlledThreadIdRef = useRef<{
+    controlled: boolean;
+    value: string | undefined;
+  }>({
+    controlled: isThreadIdControlled,
+    value: threadId,
+  });
 
   // ============================================
   // ChatWithTools Instance
@@ -570,6 +644,8 @@ export function CopilotProvider({
         runtimeUrl,
         systemPrompt,
         threadId,
+        onCreateSession,
+        yourgptConfig,
         initialMessages: uiInitialMessages,
         streaming,
         headers,
@@ -596,6 +672,15 @@ export function CopilotProvider({
         onError: (error) => {
           if (error) onError?.(error);
         },
+        onThreadChange: (id) => {
+          debugLog("Thread/session ID assigned:", id);
+          setActualThreadId(id);
+          onThreadChange?.(id);
+        },
+        onSessionStatusChange: (status) => {
+          debugLog("Session status:", status);
+          setSessionStatus(status);
+        },
         onStreamChunk: (chunk) => {
           // Broadcast to all useCopilotEvent() subscribers
           if (streamListenersRef.current.size > 0) {
@@ -648,6 +733,31 @@ export function CopilotProvider({
     }
   }, [runtimeUrl, debugLog]);
 
+  // Keep the chat instance aligned with controlled threadId prop changes.
+  useEffect(() => {
+    const prev = lastControlledThreadIdRef.current;
+    const controlChanged = prev.controlled !== isThreadIdControlled;
+    const valueChanged = prev.value !== threadId;
+
+    if (!controlChanged && !valueChanged) {
+      return;
+    }
+
+    lastControlledThreadIdRef.current = {
+      controlled: isThreadIdControlled,
+      value: threadId,
+    };
+
+    if (!isThreadIdControlled) {
+      return;
+    }
+
+    chatRef.current?.setActiveThread(threadId ?? null);
+    setActualThreadId(threadId);
+    setSessionStatus(threadId ? "ready" : "idle");
+    debugLog("Thread/session synced from prop", { threadId });
+  }, [debugLog, isThreadIdControlled, threadId]);
+
   // Stable snapshot callbacks for useSyncExternalStore
   // getServerSnapshot must return a cached/stable value to avoid infinite loops
   const EMPTY_MESSAGES = useRef<UIMessage[]>([]);
@@ -685,6 +795,18 @@ export function CopilotProvider({
   // Actions
   // ============================================
 
+  const setActiveThread = useCallback((id: string | null) => {
+    chatRef.current?.setActiveThread(id);
+    // Sync React state: known ID → expose it; null (new thread) → clear until onThreadChange fires
+    setActualThreadId(id ?? undefined);
+  }, []);
+
+  const renewSession = useCallback(() => {
+    chatRef.current?.renewSession();
+    setActualThreadId(undefined);
+    setSessionStatus("idle");
+  }, []);
+
   const registerTool = useCallback((tool: ToolDefinition) => {
     chatRef.current?.registerTool(tool);
   }, []);
@@ -965,7 +1087,10 @@ export function CopilotProvider({
       setInlineSkills,
 
       // Config
-      threadId,
+      threadId: actualThreadId,
+      setActiveThread,
+      renewSession,
+      sessionStatus,
       runtimeUrl,
       toolsConfig,
 
@@ -1005,7 +1130,10 @@ export function CopilotProvider({
       contextUsage,
       setSystemPrompt,
       setInlineSkills,
-      threadId,
+      actualThreadId,
+      setActiveThread,
+      renewSession,
+      sessionStatus,
       runtimeUrl,
       toolsConfig,
     ],
diff --git a/packages/llm-sdk/package.json b/packages/llm-sdk/package.json
index eabf3f2..d75934d 100644
--- a/packages/llm-sdk/package.json
+++ b/packages/llm-sdk/package.json
@@ -50,6 +50,11 @@
       "types": "./dist/adapters/index.d.ts",
       "import": "./dist/adapters/index.mjs",
       "require": "./dist/adapters/index.js"
+    },
+    "./yourgpt": {
+      "types": "./dist/yourgpt/index.d.ts",
+      "import": "./dist/yourgpt/index.mjs",
+      "require": "./dist/yourgpt/index.js"
     }
   },
   "homepage": "https://copilot-sdk.yourgpt.ai",
diff --git a/packages/llm-sdk/src/yourgpt/index.ts b/packages/llm-sdk/src/yourgpt/index.ts
new file mode 100644
index 0000000..12b5ca0
--- /dev/null
+++ b/packages/llm-sdk/src/yourgpt/index.ts
@@ -0,0 +1,178 @@
+/**
+ * @yourgpt/llm-sdk/yourgpt
+ *
+ * Server-side YourGPT session & message persistence adapter.
+ * Use this in your backend alongside createRuntime.
+ *
+ * @example
+ * ```ts
+ * import { createYourGPTAdapter } from '@yourgpt/llm-sdk/yourgpt'
+ *
+ * const storage = createYourGPTAdapter({ apiKey, widgetUid })
+ *
+ * const session = await storage.createSession({ title: 'New chat' })
+ * await storage.saveMessages(session.id, [userMessage])
+ * stream.on('done', async (result) => {
+ *   await storage.saveMessages(session.id, [{ role: 'assistant', content: result.text }])
+ * })
+ * ```
+ */
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface YourGPTAdapterConfig {
+  /** Your YourGPT API key — server-side only, never expose to browser */
+  apiKey: string;
+  /** Widget UID — scopes all sessions to this project */
+  widgetUid: string;
+  /** Override API base URL. Defaults to https://api.yourgpt.ai */
+  endpoint?: string;
+}
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface YourGPTSession {
+  /** Use this as threadId in subsequent chat requests */
+  id: string;
+  title?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface NewYourGPTMessage {
+  role: "user" | "assistant" | "system" | "tool";
+  content: string;
+  toolCalls?: unknown[];
+  toolCallId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CreateSessionData {
+  title?: string;
+  metadata?: Record<string, unknown>;
+}
+
+// ─── Adapter ──────────────────────────────────────────────────────────────────
+
+export interface YourGPTAdapter {
+  /** Create a new session. Returns session_uid — store as threadId on frontend. */
+  createSession(data?: CreateSessionData): Promise<YourGPTSession>;
+  /** Append messages to a session */
+  saveMessages(sessionId: string, messages: NewYourGPTMessage[]): Promise<void>;
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+export function createYourGPTAdapter(
+  config: YourGPTAdapterConfig,
+): YourGPTAdapter {
+  const base = (config.endpoint ?? "https://api.yourgpt.ai").replace(/\/$/, "");
+  const headers = {
+    "Content-Type": "application/json",
+    "api-key": config.apiKey,
+  };
+
+  async function call<T = unknown>(
+    path: string,
+    body: object = {},
+  ): Promise<T> {
+    const payload = { widget_uid: config.widgetUid, ...body };
+    console.log(`[yourgpt] POST ${base}${path}`, JSON.stringify(payload));
+    const res = await fetch(`${base}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => res.statusText);
+      throw new Error(`YourGPT API [${res.status}] ${path}: ${text}`);
+    }
+    return res.json() as Promise<T>;
+  }
+
+  return {
+    async createSession(data = {}) {
+      const raw = await call<any>(
+        "/chatbot/v1/copilot-sdk/createSession",
+        data,
+      );
+      const d = raw.data ?? raw;
+      return {
+        id: String(d.session_uid ?? d.id),
+        title: d.title ?? undefined,
+        createdAt: new Date(d.createdAt ?? d.created_at),
+        updatedAt: new Date(d.updatedAt ?? d.updated_at),
+      };
+    },
+
+    async saveMessages(sessionId, messages) {
+      // Keep as string if too large for JS safe integer (avoids precision loss)
+      const num = Number(sessionId);
+      const sessionUid = Number.isSafeInteger(num) ? num : sessionId;
+
+      // Build a lookup: tool_call_id → tool result content (for merging dispatch + result)
+      const toolResults = new Map<string, string>();
+      for (const msg of messages) {
+        if (msg.role === "tool" && msg.toolCallId) {
+          toolResults.set(msg.toolCallId, msg.content ?? "");
+        }
+      }
+
+      for (const msg of messages) {
+        if (msg.role === "tool") {
+          // Tool results are merged into the dispatch record below — skip standalone save
+          continue;
+        } else if (msg.role === "assistant" && msg.toolCalls?.length) {
+          // Assistant dispatching tool calls — one completed record per call (cold storage)
+          for (const tc of msg.toolCalls as Array<{
+            id?: string;
+            function?: { name?: string; arguments?: string };
+          }>) {
+            const toolName = tc.function?.name ?? "unknown";
+            let toolArgs: unknown = {};
+            try {
+              toolArgs =
+                typeof tc.function?.arguments === "string"
+                  ? JSON.parse(tc.function.arguments)
+                  : (tc.function?.arguments ?? {});
+            } catch {
+              /* leave as empty object */
+            }
+
+            // Merge: find matching tool result by call ID
+            const response = tc.id ? (toolResults.get(tc.id) ?? null) : null;
+
+            await call("/chatbot/v1/copilot-sdk/createToolMessage", {
+              session_uid: sessionUid,
+              skill: "copilot-tool",
+              extra_data: {
+                tool_name: toolName,
+                tool_arguments: toolArgs,
+                tool_call_id: tc.id ?? null,
+                status: "completed",
+                tool_response: response,
+              },
+            });
+          }
+
+          // Also save the assistant text content if present alongside tool calls
+          if (msg.content) {
+            await call("/chatbot/v1/copilot-sdk/createMessage", {
+              session_uid: sessionUid,
+              message: msg.content,
+              send_by: "assistant",
+            });
+          }
+        } else if (msg.role === "user" || msg.role === "assistant") {
+          // Regular user / assistant message
+          await call("/chatbot/v1/copilot-sdk/createMessage", {
+            session_uid: sessionUid,
+            message: msg.content,
+            send_by: msg.role === "user" ? "user" : "assistant",
+          });
+        }
+        // system messages are skipped — not stored
+      }
+    },
+  };
+}
diff --git a/packages/llm-sdk/tsup.config.ts b/packages/llm-sdk/tsup.config.ts
index 36c2d71..418863c 100644
--- a/packages/llm-sdk/tsup.config.ts
+++ b/packages/llm-sdk/tsup.config.ts
@@ -16,6 +16,9 @@ export default defineConfig({
 
     // Legacy adapters
     "adapters/index": "src/adapters/index.ts",
+
+    // YourGPT storage adapter
+    "yourgpt/index": "src/yourgpt/index.ts",
   },
   format: ["cjs", "esm"],
   dts: true,

From 2cf3c857ae34739f03b85fcc45feec4b3929eb28 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Wed, 25 Mar 2026 18:19:13 +0530
Subject: [PATCH 50/72] feat(storage): introduce Storage Adapter for automatic
 session management and message persistence

- Added a new Storage Adapter interface for custom backend implementations.
- Implemented automatic session creation and message persistence in the runtime.
- Enhanced chat components to support file uploads via the new upload prop.
- Updated documentation to include usage examples and configuration details for the Storage Adapter.
- Refactored existing chat logic to adopt thread IDs from the server when using a storage adapter.
---
 apps/docs/alpha-docs/STORAGE-ADAPTER.md       | 152 +++++++++
 apps/docs/content/docs/multimodal.mdx         |  89 ++++-
 apps/docs/content/docs/server/meta.json       |   2 +-
 apps/docs/content/docs/server/storage.mdx     | 309 ++++++++++++++++++
 .../src/chat/classes/AbstractChat.ts          |  47 ++-
 .../src/chat/interfaces/ChatTransport.ts      |   4 +
 .../src/core/tools/builtin/network.ts         |   8 +
 .../copilot-sdk/src/core/tools/console.ts     |   7 +-
 .../src/ui/components/composed/chat/chat.tsx  |  57 +++-
 .../src/ui/components/composed/chat/types.ts  |  38 ++-
 .../src/ui/hooks/useInternalThreadManager.ts  |  12 +-
 packages/llm-sdk/src/core/index.ts            |   4 +
 packages/llm-sdk/src/core/stream-events.ts    |   2 +
 packages/llm-sdk/src/core/types.ts            |  67 ++++
 packages/llm-sdk/src/index.ts                 |   7 +
 packages/llm-sdk/src/server/index.ts          |   3 +
 packages/llm-sdk/src/server/runtime.ts        |  85 ++++-
 .../llm-sdk/src/server/storage-helpers.ts     |  83 +++++
 packages/llm-sdk/src/server/stream-result.ts  |   9 +
 packages/llm-sdk/src/server/types.ts          |  23 ++
 packages/llm-sdk/src/yourgpt/index.ts         |  82 +++--
 pnpm-lock.yaml                                |  35 +-
 22 files changed, 1051 insertions(+), 74 deletions(-)
 create mode 100644 apps/docs/alpha-docs/STORAGE-ADAPTER.md
 create mode 100644 apps/docs/content/docs/server/storage.mdx
 create mode 100644 packages/llm-sdk/src/server/storage-helpers.ts

diff --git a/apps/docs/alpha-docs/STORAGE-ADAPTER.md b/apps/docs/alpha-docs/STORAGE-ADAPTER.md
new file mode 100644
index 0000000..8df3158
--- /dev/null
+++ b/apps/docs/alpha-docs/STORAGE-ADAPTER.md
@@ -0,0 +1,152 @@
+# Storage Adapter (Alpha)
+
+> **Status**: Alpha — API may change. Available since `@yourgpt/llm-sdk@1.5.0-alpha`.
+
+## Quick Start
+
+```ts
+import { createRuntime } from "@yourgpt/llm-sdk";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
+import { createYourGPT } from "@yourgpt/llm-sdk/yourgpt";
+
+// 1. Create adapter (server-side only)
+const yourgpt = createYourGPT({
+  apiKey: process.env.YOURGPT_API_KEY,
+  widgetUid: process.env.YOURGPT_WIDGET_UID,
+  // endpoint defaults to https://api.yourgpt.ai
+  // Override for dev: endpoint: 'http://localhost:3000'
+});
+
+// 2. Plug into runtime
+const runtime = createRuntime({
+  provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  model: "claude-haiku-4-5",
+  storage: yourgpt, // ← enables automatic persistence
+});
+
+// 3. Endpoints are one-liners
+app.post("/api/copilot/chat", async (req, res) => {
+  const result = await runtime.chat(req.body);
+  res.json(result); // includes threadId
+});
+
+app.post("/api/copilot/stream", async (req, res) => {
+  await runtime.stream(req.body).pipeToResponse(res);
+});
+
+// 4. Optional: file upload
+app.post("/api/copilot/upload", async (req, res) => {
+  const result = await yourgpt.uploadFile(req.body);
+  res.json(result);
+});
+```
+
+## What Happens Automatically
+
+| Event                       | Without storage         | With storage                                   |
+| --------------------------- | ----------------------- | ---------------------------------------------- |
+| First message (no threadId) | Uses local thread ID    | Creates session via API, returns real threadId |
+| User sends message          | Just forwarded to LLM   | Saved to session, then forwarded               |
+| LLM responds                | Just returned to client | Saved to session, then returned                |
+| Tool calls + results        | Not persisted           | Saved as tool messages                         |
+| File attachment             | Base64 in payload       | Uploaded to storage, URL in payload            |
+| Session creation fails      | N/A                     | Fallback local ID, chat continues              |
+
+## Configuration
+
+### `createYourGPT(config)`
+
+| Option      | Required | Default                  | Description                |
+| ----------- | -------- | ------------------------ | -------------------------- |
+| `apiKey`    | Yes      | —                        | YourGPT API key            |
+| `widgetUid` | Yes      | —                        | Widget UID (project scope) |
+| `endpoint`  | No       | `https://api.yourgpt.ai` | API base URL               |
+
+### `createRuntime({ storage })`
+
+The `storage` option accepts any `StorageAdapter`. The runtime calls:
+
+- `storage.createSession()` — when request has no threadId
+- `storage.saveMessages()` — before + after LLM call
+- `storage.uploadFile()` — not called by runtime (used via upload endpoint)
+
+### Environment Variables (Server)
+
+```env
+# Required
+YOURGPT_API_KEY=apk-your-key-here
+YOURGPT_WIDGET_UID=your-widget-uid-here
+
+# Optional (defaults to production)
+YOURGPT_API_ENDPOINT=https://api.yourgpt.ai
+
+# LLM provider
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Client Setup
+
+No special client configuration needed for sessions. The client SDK automatically:
+
+1. Reads `threadId` from server response
+2. Uses it for subsequent requests
+3. Uses it as the local thread ID (single ID system)
+
+### File uploads (client)
+
+The `upload` prop handles all upload modes — string, object, or function:
+
+```tsx
+// Simple — just a URL:
+<CopilotChat upload="/api/copilot/upload" attachmentsEnabled />
+
+// With auth headers:
+<CopilotChat upload={{
+  url: "/api/copilot/upload",
+  headers: () => ({ Authorization: `Bearer ${token}` }),
+}} />
+
+// Full custom:
+<CopilotChat upload={async (file) => {
+  const url = await myS3Upload(file);
+  return { type: 'image', url, mimeType: file.type, filename: file.name };
+}} />
+```
+
+## Custom StorageAdapter
+
+Implement the interface for any backend:
+
+```ts
+import type { StorageAdapter } from "@yourgpt/llm-sdk";
+
+const myStorage: StorageAdapter = {
+  async createSession(data) {
+    // Your DB call
+    return { id: "session-123" };
+  },
+  async saveMessages(sessionId, messages) {
+    // Your DB call
+  },
+  // Optional:
+  async uploadFile(file) {
+    // Your storage call
+    return { url: "https://..." };
+  },
+};
+
+const runtime = createRuntime({ provider, model, storage: myStorage });
+```
+
+## Error Handling
+
+- `createSession` failure → Fallback local ID, storage skipped, chat works
+- `saveMessages` failure → Logged, chat continues (fire-and-forget)
+- `uploadFile` failure → Error returned to client (4xx/5xx)
+- All errors are logged with `[Runtime]` prefix
+
+## Alpha Notes
+
+- The `endpoint` option in `createYourGPT` will become internal in GA (defaults to production API)
+- `getSessions()` and `getMessages()` on StorageAdapter are reserved for future thread sync
+- File upload API contract (`/copilot-sdk/uploadMedia`) may change
diff --git a/apps/docs/content/docs/multimodal.mdx b/apps/docs/content/docs/multimodal.mdx
index c038646..82b3734 100644
--- a/apps/docs/content/docs/multimodal.mdx
+++ b/apps/docs/content/docs/multimodal.mdx
@@ -103,19 +103,93 @@ interface MessageAttachment {
 | `attachmentsEnabled` | `boolean` | `false` | Enable attachment button |
 | `maxFileSize` | `number` | `5MB` | Maximum file size in bytes |
 | `allowedFileTypes` | `string[]` | All | Allowed MIME types or extensions |
-| `processAttachment` | `function` | - | Custom upload handler |
+| `upload` | `string \| object \| function` | - | Upload handler (see below) |
 
 ---
 
-## Custom Upload Handler
+## The `upload` Prop
 
-Upload to your own storage:
+One prop, three modes — from simple to full control:
+
+```tsx
+// 1. URL string — server handles the upload
+<CopilotChat upload="/api/copilot/upload" />
+
+// 2. Object — URL + custom headers/body
+<CopilotChat upload={{
+  url: "/api/copilot/upload",
+  headers: () => ({ Authorization: `Bearer ${token}` }),
+  body: { projectId: "abc" },
+}} />
+
+// 3. Function — full custom logic
+<CopilotChat upload={async (file) => {
+  const url = await myS3Upload(file);
+  return { type: 'image', url, mimeType: file.type, filename: file.name };
+}} />
+```
+
+Without `upload`, files are embedded as base64 in the message body (works but heavier payload).
+
+---
+
+## Server Upload (Recommended)
+
+Point `upload` to your server endpoint. Files are uploaded there, and the returned URL is sent with the message.
 
 ```tsx
 <CopilotChat
   attachmentsEnabled={true}
-  processAttachment={async (file: File) => {
-    // Upload to S3, Cloudinary, etc.
+  upload="/api/copilot/upload"
+/>
+```
+
+### With YourGPT
+
+If your server uses the YourGPT adapter, the upload endpoint uses the same credentials:
+
+```ts title="server.ts"
+import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt';
+
+const yourgpt = createYourGPT({ apiKey, widgetUid });
+
+app.post('/api/copilot/upload', async (req, res) => {
+  const result = await yourgpt.uploadFile(req.body);
+  res.json(result);
+});
+```
+
+### With Custom Storage
+
+```ts title="server.ts"
+app.post('/api/copilot/upload', async (req, res) => {
+  const { data, mimeType, filename } = req.body;
+  const url = await myStorage.upload(Buffer.from(data, 'base64'), mimeType);
+  res.json({ url });
+});
+```
+
+### With Auth Headers
+
+```tsx
+<CopilotChat
+  upload={{
+    url: "/api/copilot/upload",
+    headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+  }}
+/>
+```
+
+---
+
+## Custom Upload Function
+
+For complete control — handle the file however you want:
+
+```tsx
+<CopilotChat
+  attachmentsEnabled={true}
+  upload={async (file: File) => {
     const formData = new FormData();
     formData.append('file', file);
 
@@ -123,12 +197,11 @@ Upload to your own storage:
       method: 'POST',
       body: formData,
     });
-
     const { url } = await response.json();
 
     return {
       type: 'image',
-      url,  // Cloud URL instead of base64
+      url,
       mimeType: file.type,
       filename: file.name,
     };
@@ -137,7 +210,7 @@ Upload to your own storage:
 ```
 
 <Callout type="info">
-Cloud storage is recommended for production. Base64 embedding works but increases message size.
+Cloud storage is recommended for production. Base64 embedding works but increases message size significantly.
 </Callout>
 
 ---
diff --git a/apps/docs/content/docs/server/meta.json b/apps/docs/content/docs/server/meta.json
index 40d9bec..f030ac9 100644
--- a/apps/docs/content/docs/server/meta.json
+++ b/apps/docs/content/docs/server/meta.json
@@ -1,5 +1,5 @@
 {
   "title": "Server",
   "icon": "Wrench",
-  "pages": ["deployment"]
+  "pages": ["storage", "deployment"]
 }
diff --git a/apps/docs/content/docs/server/storage.mdx b/apps/docs/content/docs/server/storage.mdx
new file mode 100644
index 0000000..26df0d9
--- /dev/null
+++ b/apps/docs/content/docs/server/storage.mdx
@@ -0,0 +1,309 @@
+---
+title: Storage & Persistence
+description: Automatic session creation and message persistence with pluggable storage adapters
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+## Overview
+
+The Storage Adapter system provides **automatic session creation and message persistence** for your copilot. When configured, the runtime handles everything — no manual save calls needed.
+
+```ts
+import { createRuntime } from '@yourgpt/llm-sdk';
+import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt';
+
+const runtime = createRuntime({
+  provider: anthropic,
+  model: 'claude-haiku-4-5',
+  storage: createYourGPT({ apiKey, widgetUid }),
+});
+
+// That's it. Sessions are created automatically.
+// Messages are persisted automatically.
+app.post('/api/copilot/chat', async (req, res) => {
+  const result = await runtime.chat(req.body);
+  res.json(result); // result.threadId is included
+});
+```
+
+---
+
+## YourGPT Adapter
+
+The built-in adapter for the YourGPT platform. Handles session creation, message persistence, and file uploads.
+
+### Setup
+
+```ts
+import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt';
+
+const yourgpt = createYourGPT({
+  apiKey: process.env.YOURGPT_API_KEY,
+  widgetUid: process.env.YOURGPT_WIDGET_UID,
+  // endpoint is optional — defaults to https://api.yourgpt.ai
+  // Override for dev/staging:
+  // endpoint: 'https://your-dev-server.example.com',
+});
+```
+
+### Configuration
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `apiKey` | Yes | — | YourGPT API key (server-side only, never expose to browser) |
+| `widgetUid` | Yes | — | Widget UID — scopes sessions to your project |
+| `endpoint` | No | `https://api.yourgpt.ai` | API base URL (override for dev/staging) |
+
+<Callout type="warn">
+  **Never expose `apiKey` to the browser.** The YourGPT adapter runs on your server only. The client communicates through your server endpoints.
+</Callout>
+
+### What it does automatically
+
+When plugged into `createRuntime({ storage: yourgpt })`:
+
+1. **First message (no threadId)** → Creates a session via YourGPT API → Returns `threadId` to client
+2. **Before LLM call** → Saves user message to the session
+3. **After LLM response** → Saves assistant response + tool calls to the session
+4. **File uploads** → Uploads media to YourGPT storage, returns URL
+
+### API Endpoints Used
+
+| Action | Endpoint | When |
+|--------|----------|------|
+| Create session | `/chatbot/v1/copilot-sdk/createSession` | First message without threadId |
+| Save message | `/chatbot/v1/copilot-sdk/createMessage` | Every user/assistant message |
+| Save tool call | `/chatbot/v1/copilot-sdk/createToolMessage` | Tool dispatches + results |
+| Upload file | `/chatbot/v1/copilot-sdk/uploadMedia` | File attachments |
+
+---
+
+## Custom Storage Adapter
+
+Build your own adapter for any backend — Supabase, Firebase, your own database, etc.
+
+### Interface
+
+```ts
+import type { StorageAdapter, StorageMessage, StorageFile } from '@yourgpt/llm-sdk';
+
+const myStorage: StorageAdapter = {
+  async createSession(data) {
+    const session = await db.sessions.create({ title: data?.title });
+    return { id: session.id };
+  },
+
+  async saveMessages(sessionId, messages) {
+    await db.messages.insertMany(
+      messages.map(msg => ({
+        sessionId,
+        role: msg.role,
+        content: msg.content,
+        toolCalls: msg.toolCalls,
+        toolCallId: msg.toolCallId,
+      }))
+    );
+  },
+
+  // Optional: file uploads
+  async uploadFile(file) {
+    const blob = Buffer.from(file.data, 'base64');
+    const url = await s3.upload(blob, file.mimeType, file.filename);
+    return { url };
+  },
+};
+
+const runtime = createRuntime({
+  provider: anthropic,
+  model: 'claude-haiku-4-5',
+  storage: myStorage,
+});
+```
+
+### StorageAdapter Interface
+
+```ts
+interface StorageAdapter {
+  /** Create a new session. Returns session ID. */
+  createSession(data?: {
+    title?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<{ id: string }>;
+
+  /** Append messages to a session. */
+  saveMessages(sessionId: string, messages: StorageMessage[]): Promise<void>;
+
+  /** Upload a file. Returns URL. (Optional) */
+  uploadFile?(file: StorageFile): Promise<{ url: string }>;
+
+  /** List sessions. (Optional — future use) */
+  getSessions?(): Promise<{ id: string; title?: string; updatedAt?: Date }[]>;
+
+  /** Get messages for a session. (Optional — future use) */
+  getMessages?(sessionId: string): Promise<StorageMessage[]>;
+}
+```
+
+### StorageMessage
+
+```ts
+interface StorageMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  toolCalls?: unknown[];
+  toolCallId?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+---
+
+## How It Works
+
+### Session Creation Flow
+
+```
+Client sends first message (no threadId)
+  → Server runtime: storage.createSession()
+  → Server runtime: storage.saveMessages(threadId, [userMsg])
+  → LLM processes message
+  → Server runtime: storage.saveMessages(threadId, [assistantMsg])
+  → Response includes threadId
+  → Client adopts threadId for future requests
+```
+
+### Subsequent Messages
+
+```
+Client sends message (with threadId)
+  → Server runtime: storage.saveMessages(threadId, [userMsg])
+  → LLM processes message
+  → Server runtime: storage.saveMessages(threadId, [assistantMsg])
+```
+
+### Error Handling
+
+If `createSession` fails, the runtime:
+- Generates a fallback local thread ID (`local_xxx`)
+- Skips all storage calls for that request
+- Chat continues working normally (graceful degradation)
+- Error is logged once
+
+---
+
+## File Uploads
+
+When the storage adapter has `uploadFile`, expose an upload endpoint on your server:
+
+```ts
+app.post('/api/copilot/upload', async (req, res) => {
+  const { data, mimeType, filename } = req.body;
+  const result = await yourgpt.uploadFile({ data, mimeType, filename });
+  res.json(result);
+});
+```
+
+Then on the client, use the `upload` prop:
+
+```tsx
+<CopilotChat upload="/api/copilot/upload" />
+```
+
+Files are uploaded to the server, which forwards them to the storage adapter. The returned URL is sent with the message instead of base64 data.
+
+See [Multimodal](/docs/multimodal) for more on file attachments.
+
+---
+
+## Complete Example
+
+<Tabs items={['YourGPT', 'Custom (Supabase)']}>
+  <Tab value="YourGPT">
+    ```ts title="server.ts"
+    import { createRuntime } from '@yourgpt/llm-sdk';
+    import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+    import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt';
+    import express from 'express';
+
+    const app = express();
+    app.use(express.json({ limit: '10mb' }));
+
+    const yourgpt = createYourGPT({
+      apiKey: process.env.YOURGPT_API_KEY!,
+      widgetUid: process.env.YOURGPT_WIDGET_UID!,
+    });
+
+    const runtime = createRuntime({
+      provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+      model: 'claude-haiku-4-5',
+      storage: yourgpt,
+    });
+
+    // Chat — sessions + messages handled automatically
+    app.post('/api/copilot/chat', async (req, res) => {
+      const result = await runtime.chat(req.body);
+      res.json(result);
+    });
+
+    // Stream — same automatic handling
+    app.post('/api/copilot/stream', async (req, res) => {
+      await runtime.stream(req.body).pipeToResponse(res);
+    });
+
+    // File upload — uses same YourGPT credentials
+    app.post('/api/copilot/upload', async (req, res) => {
+      const result = await yourgpt.uploadFile(req.body);
+      res.json(result);
+    });
+
+    app.listen(3001);
+    ```
+  </Tab>
+  <Tab value="Custom (Supabase)">
+    ```ts title="server.ts"
+    import { createRuntime, type StorageAdapter } from '@yourgpt/llm-sdk';
+    import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+    import { createClient } from '@supabase/supabase-js';
+    import express from 'express';
+
+    const supabase = createClient(
+      process.env.SUPABASE_URL!,
+      process.env.SUPABASE_KEY!,
+    );
+
+    const storage: StorageAdapter = {
+      async createSession(data) {
+        const { data: session } = await supabase
+          .from('sessions')
+          .insert({ title: data?.title })
+          .select('id')
+          .single();
+        return { id: session!.id };
+      },
+      async saveMessages(sessionId, messages) {
+        await supabase.from('messages').insert(
+          messages.map(m => ({ session_id: sessionId, ...m }))
+        );
+      },
+    };
+
+    const runtime = createRuntime({
+      provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+      model: 'claude-haiku-4-5',
+      storage,
+    });
+
+    const app = express();
+    app.use(express.json());
+
+    app.post('/api/copilot/chat', async (req, res) => {
+      const result = await runtime.chat(req.body);
+      res.json(result);
+    });
+
+    app.listen(3001);
+    ```
+  </Tab>
+</Tabs>
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 51b2de7..cc6c2de 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -286,19 +286,12 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         this.config.threadId = await this.sessionInitPromise;
         this.debug("sendMessage", { threadId: this.config.threadId });
       }
-      // No session config and no threadId — generate a local ID (no network call).
-      // Skip this when onCreateSession/yourgptConfig is provided: if we reach here
-      // without a threadId it means session creation was not triggered (threadId was
-      // just cleared by setActiveThread) — proceed without one and let the next
-      // sendMessage pick it up after the session is assigned.
-      if (
-        !this.config.threadId &&
-        !this.onCreateSession &&
-        !this.config.yourgptConfig
-      ) {
-        this.config.threadId = generateThreadId();
-        this.setSessionStatus("ready");
-      }
+      // No threadId at this point — that's OK.
+      // If the server has a storage adapter, it will create a session and return
+      // the threadId in the response. The SDK adopts it automatically via
+      // handleJsonResponse / handleStreamResponse.
+      // Local thread IDs for CopilotChat persistence are managed independently
+      // by useInternalThreadManager.
 
       // Yield to allow UI to render loading state (important for non-streaming)
       await Promise.resolve();
@@ -1342,6 +1335,23 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
           chunkCount,
         });
 
+        // Adopt threadId from server storage adapter (if present)
+        if (
+          chunk.type === "done" &&
+          (chunk as { threadId?: string }).threadId
+        ) {
+          const serverThreadId = (chunk as { threadId?: string }).threadId!;
+          if (
+            !this.config.threadId ||
+            this.config.threadId !== serverThreadId
+          ) {
+            this.config.threadId = serverThreadId;
+            this.sessionInitPromise = null;
+            this.setSessionStatus("ready");
+            this.callbacks.onThreadChange?.(serverThreadId);
+          }
+        }
+
         // CRITICAL: Process messages from done event (server-side tool results)
         // Without this, tool_call_id is lost and causes Anthropic API errors
         if (chunk.type === "done" && chunk.messages?.length) {
@@ -1602,6 +1612,17 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
    * Handle JSON (non-streaming) response
    */
   protected handleJsonResponse(response: ChatResponse): void {
+    // Adopt threadId from server storage adapter (if present)
+    if (
+      response.threadId &&
+      (!this.config.threadId || this.config.threadId !== response.threadId)
+    ) {
+      this.config.threadId = response.threadId;
+      this.sessionInitPromise = null;
+      this.setSessionStatus("ready");
+      this.callbacks.onThreadChange?.(response.threadId);
+    }
+
     // Build a map of tool call hidden flags from response.toolCalls
     const toolCallHiddenMap = new Map<string, boolean>();
     if (response.toolCalls) {
diff --git a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
index 1675cde..2275ebc 100644
--- a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
+++ b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
@@ -56,6 +56,8 @@ export interface ChatResponse {
     /** Tool call ID for tool result messages */
     tool_call_id?: string;
   }>;
+  /** Session ID — present when server storage adapter created/resolved a session */
+  threadId?: string;
   /** Whether client needs to execute tools */
   requiresAction?: boolean;
   /** Tool calls with metadata (includes hidden flag for server-side tools) */
@@ -115,6 +117,8 @@ export type StreamChunk =
         tool_call_id?: string;
       }>;
       requiresAction?: boolean;
+      /** Session ID from server storage adapter */
+      threadId?: string;
     }
   // Tool action events (from llm-sdk agent-loop)
   | { type: "action:start"; id: string; name: string; hidden?: boolean }
diff --git a/packages/copilot-sdk/src/core/tools/builtin/network.ts b/packages/copilot-sdk/src/core/tools/builtin/network.ts
index df8d3ff..2307276 100644
--- a/packages/copilot-sdk/src/core/tools/builtin/network.ts
+++ b/packages/copilot-sdk/src/core/tools/builtin/network.ts
@@ -13,6 +13,14 @@ import {
   startNetworkCapture,
 } from "../network";
 
+// Auto-start network capture when this module is imported
+// This ensures requests are captured from the beginning of the app lifecycle
+const isBrowser = typeof window !== "undefined" && typeof fetch !== "undefined";
+
+if (isBrowser && !isNetworkCaptureActive()) {
+  startNetworkCapture();
+}
+
 /**
  * Network requests tool - retrieves browser network activity
  *
diff --git a/packages/copilot-sdk/src/core/tools/console.ts b/packages/copilot-sdk/src/core/tools/console.ts
index 76715bc..f60f7d2 100644
--- a/packages/copilot-sdk/src/core/tools/console.ts
+++ b/packages/copilot-sdk/src/core/tools/console.ts
@@ -193,7 +193,12 @@ export function stopConsoleCapture(): void {
 export function getConsoleLogs(
   options: ConsoleLogOptions = {},
 ): ConsoleLogResult {
-  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const opts = {
+    ...DEFAULT_OPTIONS,
+    ...options,
+    types: options.types ?? DEFAULT_OPTIONS.types,
+    limit: options.limit ?? DEFAULT_OPTIONS.limit,
+  };
 
   let logs = [...capturedLogs];
 
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 4ee041d..f302629 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -519,7 +519,8 @@ function ChatComponent({
   allowedFileTypes = DEFAULT_ALLOWED_TYPES,
   attachmentsEnabled = true,
   attachmentsDisabledTooltip = "Attachments not supported by this model",
-  processAttachment: processAttachmentProp,
+  upload: uploadProp,
+  processAttachment: deprecatedProcessAttachment,
   // Suggestions
   suggestions = [],
   onSuggestionClick,
@@ -642,9 +643,43 @@ function ChatComponent({
             filename?: string;
           };
 
-          if (processAttachmentProp) {
-            // Use provided processor (e.g., cloud storage upload)
-            attachment = await processAttachmentProp(file);
+          // Resolve upload handler: upload prop > deprecated processAttachment > base64 fallback
+          const uploader = uploadProp ?? deprecatedProcessAttachment;
+
+          if (typeof uploader === "function") {
+            // Function — full custom handler
+            attachment = await uploader(file);
+          } else if (uploader) {
+            // String or object — server upload endpoint
+            const config =
+              typeof uploader === "string" ? { url: uploader } : uploader;
+            const extraHeaders =
+              typeof config.headers === "function"
+                ? config.headers()
+                : config.headers;
+            const extraBody =
+              typeof config.body === "function" ? config.body() : config.body;
+            const data = await fileToBase64(file);
+            const res = await fetch(config.url, {
+              method: "POST",
+              headers: { "Content-Type": "application/json", ...extraHeaders },
+              body: JSON.stringify({
+                data,
+                mimeType: file.type,
+                filename: file.name,
+                ...extraBody,
+              }),
+            });
+            if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
+            const result = await res.json();
+            const url = result.url ?? result.data?.url;
+            if (!url) throw new Error("Upload returned no URL");
+            attachment = {
+              type: getAttachmentType(file.type),
+              url,
+              mimeType: file.type,
+              filename: file.name,
+            };
           } else {
             // Default: convert to base64
             const data = await fileToBase64(file);
@@ -678,7 +713,13 @@ function ChatComponent({
         }
       }
     },
-    [attachmentsEnabled, maxFileSize, isFileTypeAllowed, processAttachmentProp],
+    [
+      attachmentsEnabled,
+      maxFileSize,
+      isFileTypeAllowed,
+      uploadProp,
+      deprecatedProcessAttachment,
+    ],
   );
 
   // Handle file input change
@@ -923,7 +964,11 @@ function ChatComponent({
               attachmentsDisabledTooltip={attachmentsDisabledTooltip}
               maxFileSize={maxFileSize}
               allowedFileTypes={allowedFileTypes}
-              processAttachment={processAttachmentProp}
+              processAttachment={
+                typeof uploadProp === "function"
+                  ? uploadProp
+                  : deprecatedProcessAttachment
+              }
             />
           ) : null}
 
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
index e480fa2..c081e52 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
@@ -341,11 +341,41 @@ export type ChatProps = {
   /** Tooltip text when attachments are disabled */
   attachmentsDisabledTooltip?: string;
   /**
-   * Custom attachment processor (e.g., for cloud storage upload)
-   * If provided, uses this instead of default base64 conversion.
-   * @param file - The file to process
-   * @returns Promise<MessageAttachment> - The processed attachment (URL-based or base64)
+   * File upload handler. Determines how attachments are uploaded.
+   *
+   * - `string` — Server upload URL. Files are POSTed as JSON `{ data, mimeType, filename }`.
+   * - `object` — URL + headers/body options for the upload request.
+   * - `function` — Full custom handler. Receives `File`, returns `MessageAttachment`.
+   * - `undefined` — Falls back to base64 (embedded in message, no upload).
+   *
+   * @example
+   * ```tsx
+   * // Simple — just a URL:
+   * <CopilotChat upload="/api/copilot/upload" />
+   *
+   * // With auth headers:
+   * <CopilotChat upload={{
+   *   url: "/api/copilot/upload",
+   *   headers: () => ({ Authorization: `Bearer ${token}` }),
+   * }} />
+   *
+   * // Full custom:
+   * <CopilotChat upload={async (file) => {
+   *   const url = await myS3Upload(file);
+   *   return { type: 'image', url, mimeType: file.type, filename: file.name };
+   * }} />
+   * ```
    */
+  upload?:
+    | string
+    | {
+        url: string;
+        headers?: Record<string, string> | (() => Record<string, string>);
+        body?: Record<string, unknown> | (() => Record<string, unknown>);
+      }
+    | ((file: File) => Promise<MessageAttachment>);
+
+  /** @deprecated Use `upload` instead */
   processAttachment?: (file: File) => Promise<MessageAttachment>;
 
   // === Suggestions ===
diff --git a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
index 93c53ed..d8e1475 100644
--- a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
+++ b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
@@ -96,6 +96,7 @@ export function useInternalThreadManager(
     isLoading,
     getAllMessages,
     switchBranch,
+    threadId: sdkThreadId,
   } = useCopilot();
 
   // Track if we're in the middle of loading messages from a thread switch
@@ -301,10 +302,19 @@ export function useInternalThreadManager(
     const activeLeafId = messages[messages.length - 1]?.id;
 
     // If no thread exists, create one with these messages
+    // Use the SDK's threadId (server session ID) as the local thread ID when available
+    // so both systems share the same ID — no mapping layer needed.
     if (!currentThreadId && !savingToThreadRef.current) {
       // Set ref immediately to prevent race condition with rapid messages
       savingToThreadRef.current = "creating";
-      createThread({ messages: coreMessages, activeLeafId }).then((thread) => {
+      // Mark as initialized so auto-restore doesn't fire when createThread
+      // sets currentThread — the messages are already in the chat state.
+      hasInitializedRef.current = true;
+      createThread({
+        id: sdkThreadId ?? undefined,
+        messages: coreMessages,
+        activeLeafId,
+      }).then((thread) => {
         lastSavedSnapshotRef.current = currentSnapshot;
         savingToThreadRef.current = thread.id;
         onThreadChange?.(thread.id);
diff --git a/packages/llm-sdk/src/core/index.ts b/packages/llm-sdk/src/core/index.ts
index be4c02b..36c0d09 100644
--- a/packages/llm-sdk/src/core/index.ts
+++ b/packages/llm-sdk/src/core/index.ts
@@ -59,6 +59,10 @@ export type {
   TokenUsage,
   FinishReason,
   ResponseOptions,
+  // Storage
+  StorageAdapter,
+  StorageMessage,
+  StorageFile,
 } from "./types";
 
 export { DEFAULT_CAPABILITIES } from "./types";
diff --git a/packages/llm-sdk/src/core/stream-events.ts b/packages/llm-sdk/src/core/stream-events.ts
index a6bcba3..c3d0b12 100644
--- a/packages/llm-sdk/src/core/stream-events.ts
+++ b/packages/llm-sdk/src/core/stream-events.ts
@@ -242,6 +242,8 @@ export interface DoneEvent extends BaseEvent {
   messages?: DoneEventMessage[];
   /** Token usage (server-side only, stripped before sending to client) */
   usage?: TokenUsageRaw;
+  /** Session ID — present when storage adapter created a session for this request */
+  threadId?: string;
 }
 
 /**
diff --git a/packages/llm-sdk/src/core/types.ts b/packages/llm-sdk/src/core/types.ts
index 35ab3f6..599fcc9 100644
--- a/packages/llm-sdk/src/core/types.ts
+++ b/packages/llm-sdk/src/core/types.ts
@@ -412,3 +412,70 @@ export interface ResponseOptions {
   /** Response status (default: 200) */
   status?: number;
 }
+
+// ============================================
+// Storage Adapter
+// ============================================
+
+/**
+ * Message format for storage adapters.
+ * Intentionally simpler than LLM-specific formats — adapters convert as needed.
+ */
+export interface StorageMessage {
+  role: "user" | "assistant" | "system" | "tool";
+  content: string;
+  toolCalls?: unknown[];
+  toolCallId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Generic storage adapter interface for session + message persistence.
+ *
+ * `createYourGPT()` is the default implementation for YourGPT platform.
+ * Third-party developers can implement this interface for custom backends.
+ *
+ * @example
+ * ```ts
+ * import { createRuntime } from '@yourgpt/llm-sdk'
+ * import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt'
+ *
+ * const runtime = createRuntime({
+ *   provider: anthropic,
+ *   model: 'claude-haiku-4-5',
+ *   storage: createYourGPT({ apiKey, widgetUid }),
+ * })
+ * // runtime.chat() and runtime.stream() now auto-persist messages
+ * ```
+ */
+export interface StorageAdapter {
+  /** Create a new session. Returns session ID to use as threadId. */
+  createSession(data?: {
+    title?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<{ id: string }>;
+  /** Append messages to a session (called sequentially — input before output). */
+  saveMessages(sessionId: string, messages: StorageMessage[]): Promise<void>;
+  /** List sessions (optional — used for thread picker sync in future). */
+  getSessions?(): Promise<{ id: string; title?: string; updatedAt?: Date }[]>;
+  /** Get messages for a session (optional — used for thread restore in future). */
+  getMessages?(sessionId: string): Promise<StorageMessage[]>;
+  /**
+   * Upload a file to storage. Returns a URL the LLM can reference.
+   * When present, the server exposes a /upload endpoint and the client
+   * uses it instead of embedding base64 in the message body.
+   */
+  uploadFile?(file: StorageFile): Promise<{ url: string }>;
+}
+
+/**
+ * File data for upload via StorageAdapter.uploadFile()
+ */
+export interface StorageFile {
+  /** Base64-encoded file data (with or without data URI prefix) */
+  data: string;
+  /** MIME type (e.g., "image/png", "application/pdf") */
+  mimeType: string;
+  /** Original filename */
+  filename?: string;
+}
diff --git a/packages/llm-sdk/src/index.ts b/packages/llm-sdk/src/index.ts
index 507f1d7..a5af166 100644
--- a/packages/llm-sdk/src/index.ts
+++ b/packages/llm-sdk/src/index.ts
@@ -77,6 +77,10 @@ export type {
   TokenUsage,
   FinishReason,
   ResponseOptions,
+  // Storage
+  StorageAdapter,
+  StorageMessage,
+  StorageFile,
 } from "./core/types";
 
 export { DEFAULT_CAPABILITIES } from "./core/types";
@@ -108,6 +112,9 @@ export {
   type CollectedResult,
 } from "./server";
 
+// Storage helpers
+export { extractInputMessages, mapOutputMessages } from "./server";
+
 // GenerateResult (Non-streaming)
 export {
   GenerateResult,
diff --git a/packages/llm-sdk/src/server/index.ts b/packages/llm-sdk/src/server/index.ts
index 9ed321f..ffbca00 100644
--- a/packages/llm-sdk/src/server/index.ts
+++ b/packages/llm-sdk/src/server/index.ts
@@ -62,3 +62,6 @@ export {
   buildProviderToolOptions,
 } from "./tool-selection";
 export type { ToolSearchMatch } from "./tool-selection";
+
+// Storage helpers (used internally by Runtime, exposed for custom server setups)
+export { extractInputMessages, mapOutputMessages } from "./storage-helpers";
diff --git a/packages/llm-sdk/src/server/runtime.ts b/packages/llm-sdk/src/server/runtime.ts
index 48a63ac..563259d 100644
--- a/packages/llm-sdk/src/server/runtime.ts
+++ b/packages/llm-sdk/src/server/runtime.ts
@@ -23,6 +23,8 @@ import type {
   HandleRequestResult,
   GenerateOptions,
 } from "./types";
+import type { StorageAdapter } from "../core/types";
+import { extractInputMessages, mapOutputMessages } from "./storage-helpers";
 import { createSSEResponse } from "./streaming";
 import { StreamResult, type CollectedResult } from "./stream-result";
 import { GenerateResult } from "./generate-result";
@@ -198,11 +200,13 @@ function buildToolContext(
 export class Runtime {
   private adapter: LLMAdapter;
   private config: RuntimeConfig;
+  private storage: StorageAdapter | undefined;
   private actions: Map<string, ActionDefinition> = new Map();
   private tools: Map<string, ToolDefinition> = new Map();
 
   constructor(config: RuntimeConfig) {
     this.config = config;
+    this.storage = config.storage;
 
     // Create adapter based on configuration type
     if ("provider" in config && config.provider) {
@@ -1879,6 +1883,7 @@ export class Runtime {
        */
       onFinish?: (result: {
         messages: DoneEventMessage[];
+        threadId?: string;
         usage?: {
           promptTokens: number;
           completionTokens: number;
@@ -1887,8 +1892,84 @@ export class Runtime {
       }) => Promise<void> | void;
     },
   ): StreamResult {
-    const generator = this.processChatWithLoop(request, options?.signal);
-    return new StreamResult(generator, { onFinish: options?.onFinish });
+    const storage = this.storage;
+
+    if (!storage) {
+      // No storage — original behavior
+      const generator = this.processChatWithLoop(request, options?.signal);
+      return new StreamResult(generator, { onFinish: options?.onFinish });
+    }
+
+    // With storage: wrap generator to auto-create session + save input before streaming
+    let resolvedThreadId: string | undefined = request.threadId;
+    const self = this;
+
+    // Track whether storage is healthy for this request
+    let storageHealthy = true;
+
+    async function* storageWrappedGenerator(): AsyncGenerator<StreamEvent> {
+      // Auto-create session if no threadId
+      if (!resolvedThreadId) {
+        try {
+          const session = await storage!.createSession();
+          resolvedThreadId = session.id;
+        } catch (err) {
+          console.error(
+            "[Runtime] storage.createSession failed — generating fallback threadId:",
+            err,
+          );
+          // Fallback: generate a local thread ID so the system doesn't break
+          resolvedThreadId = `local_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+          storageHealthy = false;
+        }
+      }
+
+      // Save input messages (user message / tool results)
+      if (resolvedThreadId && storageHealthy) {
+        try {
+          const inputMsgs = extractInputMessages(request.messages);
+          if (inputMsgs.length) {
+            await storage!.saveMessages(resolvedThreadId, inputMsgs);
+          }
+        } catch (err) {
+          console.error("[Runtime] storage.saveMessages (input) failed:", err);
+        }
+      }
+
+      // Delegate to the real chat generator
+      for await (const event of self.processChatWithLoop(
+        request,
+        options?.signal,
+      )) {
+        if (event.type === "done" && resolvedThreadId) {
+          // Inject threadId into done event so client can adopt it
+          yield { ...event, threadId: resolvedThreadId } as StreamEvent;
+        } else {
+          yield event;
+        }
+      }
+    }
+
+    return new StreamResult(storageWrappedGenerator(), {
+      onFinish: async (result) => {
+        // Save output messages after stream completes (skip if storage failed on createSession)
+        if (resolvedThreadId && storageHealthy && result.messages.length > 0) {
+          try {
+            const outputMsgs = mapOutputMessages(result.messages);
+            await storage.saveMessages(resolvedThreadId, outputMsgs);
+          } catch (err) {
+            console.error(
+              "[Runtime] storage.saveMessages (output) failed:",
+              err,
+            );
+          }
+        }
+        // Call user's onFinish
+        if (options?.onFinish) {
+          await options.onFinish({ ...result, threadId: resolvedThreadId });
+        }
+      },
+    });
   }
 
   /**
diff --git a/packages/llm-sdk/src/server/storage-helpers.ts b/packages/llm-sdk/src/server/storage-helpers.ts
new file mode 100644
index 0000000..b181077
--- /dev/null
+++ b/packages/llm-sdk/src/server/storage-helpers.ts
@@ -0,0 +1,83 @@
+/**
+ * Storage Helpers
+ *
+ * Extract input/output messages from request/response for storage adapters.
+ * Used internally by Runtime when `storage` is configured.
+ */
+
+import type { StorageMessage } from "../core/types";
+import type { DoneEventMessage } from "../core/stream-events";
+
+/**
+ * Extract new INPUT messages from a request's message array.
+ *
+ * The SDK sends the full conversation history on each request. This function
+ * picks only the NEW messages the user just added:
+ * - New user turn (last meaningful msg = "user"): returns [userMsg]
+ * - Tool continuation (last meaningful msg = "tool"): returns tool results after last assistant
+ * - Otherwise: returns []
+ *
+ * Skips empty assistant placeholders the SDK pushes before sending.
+ */
+export function extractInputMessages(reqMessages: unknown[]): StorageMessage[] {
+  if (!reqMessages?.length) return [];
+
+  // Walk backwards — skip empty assistant placeholders
+  let lastMeaningful: any = null;
+  for (let i = reqMessages.length - 1; i >= 0; i--) {
+    const m = reqMessages[i] as any;
+    if (m.role === "assistant" && (!m.content || m.content === "")) continue;
+    lastMeaningful = m;
+    break;
+  }
+  if (!lastMeaningful) return [];
+
+  if (lastMeaningful.role === "user") {
+    return [
+      {
+        role: "user",
+        content:
+          typeof lastMeaningful.content === "string"
+            ? lastMeaningful.content
+            : JSON.stringify(lastMeaningful.content),
+      },
+    ];
+  }
+
+  if (lastMeaningful.role === "tool" || lastMeaningful.role === "function") {
+    const msgs = reqMessages as any[];
+    const lastAssistantIdx = msgs
+      .map((m: any) => m.role)
+      .lastIndexOf("assistant");
+    return msgs
+      .slice(lastAssistantIdx + 1)
+      .filter(
+        (m: any) =>
+          !(m.role === "assistant" && (!m.content || m.content === "")),
+      )
+      .map((m: any) => ({
+        role: m.role as StorageMessage["role"],
+        content:
+          typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+        toolCallId: m.tool_call_id,
+      }));
+  }
+
+  return [];
+}
+
+/**
+ * Map LLM output messages (DoneEventMessage format) to StorageMessage format.
+ *
+ * Converts from snake_case API format to camelCase storage format.
+ */
+export function mapOutputMessages(
+  resultMessages: DoneEventMessage[],
+): StorageMessage[] {
+  return resultMessages.map((m) => ({
+    role: m.role,
+    content: m.content ?? "",
+    toolCalls: m.tool_calls,
+    toolCallId: m.tool_call_id,
+  }));
+}
diff --git a/packages/llm-sdk/src/server/stream-result.ts b/packages/llm-sdk/src/server/stream-result.ts
index f02edd2..cf245bd 100644
--- a/packages/llm-sdk/src/server/stream-result.ts
+++ b/packages/llm-sdk/src/server/stream-result.ts
@@ -64,6 +64,8 @@ export interface OnFinishResult {
     completionTokens: number;
     totalTokens: number;
   };
+  /** Session ID — present when storage adapter created/resolved a session */
+  threadId?: string;
 }
 
 /**
@@ -91,6 +93,8 @@ export interface CollectedResult {
   requiresAction: boolean;
   /** Token usage for billing/tracking */
   usage?: TokenUsageRaw;
+  /** Session ID — present when storage adapter created/resolved a session */
+  threadId?: string;
   /** Raw events (for debugging) */
   events: StreamEvent[];
 }
@@ -510,6 +514,7 @@ export class StreamResult {
       toolCalls: [],
       requiresAction: false,
       usage: undefined,
+      threadId: undefined,
       events: [],
     };
   }
@@ -564,6 +569,9 @@ export class StreamResult {
           this.capturedUsage = event.usage;
           collected.usage = event.usage;
         }
+        if (event.threadId) {
+          collected.threadId = event.threadId;
+        }
         break;
     }
   }
@@ -577,6 +585,7 @@ export class StreamResult {
         const usage = this.capturedUsage;
         await this.onFinishCallback({
           messages: collected.messages,
+          threadId: collected.threadId,
           usage: usage
             ? {
                 promptTokens: usage.prompt_tokens,
diff --git a/packages/llm-sdk/src/server/types.ts b/packages/llm-sdk/src/server/types.ts
index a438de4..a2c0d8e 100644
--- a/packages/llm-sdk/src/server/types.ts
+++ b/packages/llm-sdk/src/server/types.ts
@@ -7,6 +7,7 @@ import type {
 } from "../core/stream-events";
 import type { LLMAdapter } from "../adapters";
 import type { AIProvider } from "../providers/types";
+import type { StorageAdapter } from "../core/types";
 
 /**
  * Tool search/discovery configuration.
@@ -95,6 +96,17 @@ export interface RuntimeConfigWithAdapter {
    * Set to true for defaults, or pass WebSearchConfig for customization.
    */
   webSearch?: boolean | WebSearchConfig;
+  /**
+   * Storage adapter for automatic session creation and message persistence.
+   * When provided, runtime.chat() and runtime.stream() auto-save messages.
+   *
+   * @example
+   * ```ts
+   * import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt'
+   * storage: createYourGPT({ apiKey, widgetUid })
+   * ```
+   */
+  storage?: StorageAdapter;
 }
 
 /**
@@ -142,6 +154,17 @@ export interface RuntimeConfigWithProvider {
    * Set to true for defaults, or pass WebSearchConfig for customization.
    */
   webSearch?: boolean | WebSearchConfig;
+  /**
+   * Storage adapter for automatic session creation and message persistence.
+   * When provided, runtime.chat() and runtime.stream() auto-save messages.
+   *
+   * @example
+   * ```ts
+   * import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt'
+   * storage: createYourGPT({ apiKey, widgetUid })
+   * ```
+   */
+  storage?: StorageAdapter;
 }
 
 /**
diff --git a/packages/llm-sdk/src/yourgpt/index.ts b/packages/llm-sdk/src/yourgpt/index.ts
index 12b5ca0..4461272 100644
--- a/packages/llm-sdk/src/yourgpt/index.ts
+++ b/packages/llm-sdk/src/yourgpt/index.ts
@@ -1,26 +1,31 @@
 /**
  * @yourgpt/llm-sdk/yourgpt
  *
- * Server-side YourGPT session & message persistence adapter.
- * Use this in your backend alongside createRuntime.
+ * YourGPT platform integration — session & message persistence.
+ * Implements the generic StorageAdapter interface.
  *
  * @example
  * ```ts
- * import { createYourGPTAdapter } from '@yourgpt/llm-sdk/yourgpt'
+ * import { createRuntime } from '@yourgpt/llm-sdk'
+ * import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt'
  *
- * const storage = createYourGPTAdapter({ apiKey, widgetUid })
+ * const yourgpt = createYourGPT({ apiKey, widgetUid })
+ * const runtime = createRuntime({ provider, model, storage: yourgpt })
  *
- * const session = await storage.createSession({ title: 'New chat' })
- * await storage.saveMessages(session.id, [userMessage])
- * stream.on('done', async (result) => {
- *   await storage.saveMessages(session.id, [{ role: 'assistant', content: result.text }])
- * })
+ * // That's it — runtime auto-creates sessions and persists messages.
+ * app.post('/api/copilot/chat', runtime.expressHandler())
  * ```
  */
 
+import type {
+  StorageAdapter,
+  StorageMessage,
+  StorageFile,
+} from "../core/types";
+
 // ─── Config ───────────────────────────────────────────────────────────────────
 
-export interface YourGPTAdapterConfig {
+export interface YourGPTConfig {
   /** Your YourGPT API key — server-side only, never expose to browser */
   apiKey: string;
   /** Widget UID — scopes all sessions to this project */
@@ -29,6 +34,9 @@ export interface YourGPTAdapterConfig {
   endpoint?: string;
 }
 
+/** @deprecated Use `YourGPTConfig` instead */
+export type YourGPTAdapterConfig = YourGPTConfig;
+
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export interface YourGPTSession {
@@ -39,33 +47,32 @@ export interface YourGPTSession {
   updatedAt: Date;
 }
 
-export interface NewYourGPTMessage {
-  role: "user" | "assistant" | "system" | "tool";
-  content: string;
-  toolCalls?: unknown[];
-  toolCallId?: string;
-  metadata?: Record<string, unknown>;
-}
+/** @deprecated Use `StorageMessage` from `@yourgpt/llm-sdk` instead */
+export type NewYourGPTMessage = StorageMessage;
 
 export interface CreateSessionData {
   title?: string;
   metadata?: Record<string, unknown>;
 }
 
-// ─── Adapter ──────────────────────────────────────────────────────────────────
+// ─── YourGPT interface ───────────────────────────────────────────────────────
 
-export interface YourGPTAdapter {
-  /** Create a new session. Returns session_uid — store as threadId on frontend. */
+/**
+ * YourGPT platform adapter.
+ * Extends StorageAdapter with richer session return type.
+ */
+export interface YourGPT extends StorageAdapter {
   createSession(data?: CreateSessionData): Promise<YourGPTSession>;
-  /** Append messages to a session */
-  saveMessages(sessionId: string, messages: NewYourGPTMessage[]): Promise<void>;
+  saveMessages(sessionId: string, messages: StorageMessage[]): Promise<void>;
+  uploadFile(file: StorageFile): Promise<{ url: string }>;
 }
 
-// ─── Factory ──────────────────────────────────────────────────────────────────
+/** @deprecated Use `YourGPT` instead */
+export type YourGPTAdapter = YourGPT;
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
 
-export function createYourGPTAdapter(
-  config: YourGPTAdapterConfig,
-): YourGPTAdapter {
+export function createYourGPT(config: YourGPTConfig): YourGPT {
   const base = (config.endpoint ?? "https://api.yourgpt.ai").replace(/\/$/, "");
   const headers = {
     "Content-Type": "application/json",
@@ -77,7 +84,6 @@ export function createYourGPTAdapter(
     body: object = {},
   ): Promise<T> {
     const payload = { widget_uid: config.widgetUid, ...body };
-    console.log(`[yourgpt] POST ${base}${path}`, JSON.stringify(payload));
     const res = await fetch(`${base}${path}`, {
       method: "POST",
       headers,
@@ -174,5 +180,27 @@ export function createYourGPTAdapter(
         // system messages are skipped — not stored
       }
     },
+
+    async uploadFile(file: StorageFile) {
+      // Strip data URI prefix if present (e.g., "data:image/png;base64,...")
+      let rawData = file.data;
+      const dataUriMatch = rawData.match(/^data:[^;]+;base64,(.+)$/);
+      if (dataUriMatch) rawData = dataUriMatch[1];
+
+      const raw = await call<any>("/chatbot/v1/copilot-sdk/uploadMedia", {
+        file_data: rawData,
+        mime_type: file.mimeType,
+        filename: file.filename,
+      });
+      const url = raw.data?.url ?? raw.url;
+      if (!url)
+        throw new Error(
+          "uploadFile failed: no URL in response — " + JSON.stringify(raw),
+        );
+      return { url };
+    },
   };
 }
+
+/** @deprecated Use `createYourGPT` instead */
+export const createYourGPTAdapter = createYourGPT;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a7572b3..2eb1776 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1156,6 +1156,9 @@ importers:
       express:
         specifier: ^4.21.0
         version: 4.22.1
+      ws:
+        specifier: ^8.18.0
+        version: 8.18.0
     devDependencies:
       '@types/cors':
         specifier: ^2.8.17
@@ -1163,6 +1166,9 @@ importers:
       '@types/express':
         specifier: ^5.0.0
         version: 5.0.6
+      '@types/ws':
+        specifier: ^8.5.13
+        version: 8.18.1
       tsx:
         specifier: ^4.19.0
         version: 4.21.0
@@ -4091,6 +4097,9 @@ packages:
   '@types/validate-npm-package-name@4.0.2':
     resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
 
+  '@types/ws@8.18.1':
+    resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
+
   '@typescript-eslint/eslint-plugin@8.50.0':
     resolution: {integrity: sha512-O7QnmOXYKVtPrfYzMolrCTfkezCJS9+ljLdKW/+DCvRsc3UAz+sbH6Xcsv7p30+0OwUbeWfUDAQE0vpabZ3QLg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -11316,6 +11325,10 @@ snapshots:
 
   '@types/validate-npm-package-name@4.0.2': {}
 
+  '@types/ws@8.18.1':
+    dependencies:
+      '@types/node': 20.19.27
+
   '@typescript-eslint/eslint-plugin@8.50.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@eslint-community/regexpp': 4.12.2
@@ -12344,7 +12357,7 @@ snapshots:
       '@next/eslint-plugin-next': 16.0.10
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
@@ -12365,7 +12378,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12385,7 +12398,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12407,7 +12420,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -12418,11 +12431,11 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -12433,18 +12446,18 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
-  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       debug: 3.2.7
     optionalDependencies:
       '@typescript-eslint/parser': 8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -12469,7 +12482,7 @@ snapshots:
       doctrine: 2.1.0
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       hasown: 2.0.2
       is-core-module: 2.16.1
       is-glob: 4.0.3
@@ -12487,7 +12500,7 @@ snapshots:
       - eslint-import-resolver-webpack
       - supports-color
 
-  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9

From dc1cdf9dcf846e67ed891d98a8d6572a91237c80 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Wed, 25 Mar 2026 20:10:33 +0530
Subject: [PATCH 51/72] feat(attachments): add attachment handling and media
 display in chat

- Introduced new hooks and components for managing attachments, including useAttachments and AttachmentStrip.
- Enhanced DefaultMessage component to support combined media and text display, improving user experience with attachments.
- Implemented ImageLightbox for fullscreen image viewing with animations.
- Updated attachment rendering logic to streamline the display of images and files in chat messages.
---
 .../src/ui/components/attachment-strip.tsx    | 248 ++++++++
 .../composed/chat/default-message.tsx         | 576 ++++++++++++++----
 .../src/ui/components/drop-zone-overlay.tsx   |  52 ++
 .../src/ui/hooks/useAttachments.ts            | 452 ++++++++++++++
 packages/copilot-sdk/src/ui/index.ts          |  15 +
 5 files changed, 1237 insertions(+), 106 deletions(-)
 create mode 100644 packages/copilot-sdk/src/ui/components/attachment-strip.tsx
 create mode 100644 packages/copilot-sdk/src/ui/components/drop-zone-overlay.tsx
 create mode 100644 packages/copilot-sdk/src/ui/hooks/useAttachments.ts

diff --git a/packages/copilot-sdk/src/ui/components/attachment-strip.tsx b/packages/copilot-sdk/src/ui/components/attachment-strip.tsx
new file mode 100644
index 0000000..18df43c
--- /dev/null
+++ b/packages/copilot-sdk/src/ui/components/attachment-strip.tsx
@@ -0,0 +1,248 @@
+"use client";
+
+/**
+ * AttachmentStrip — Displays pending attachments above the chat input.
+ *
+ * Minimal, Linear/Notion-inspired design.
+ * Shows thumbnail, filename, progress, and remove/retry actions.
+ */
+
+import type { PendingAttachment } from "../hooks/useAttachments";
+
+// ── Inline SVG icons (Lucide) ──────────────────────────────────────────────
+
+const svgProps = {
+  xmlns: "http://www.w3.org/2000/svg",
+  viewBox: "0 0 24 24",
+  fill: "none",
+  stroke: "currentColor",
+  strokeWidth: 2,
+  strokeLinecap: "round" as const,
+  strokeLinejoin: "round" as const,
+};
+
+function ImageIcon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <rect width="18" height="18" x="3" y="3" rx="2" ry="2" />
+      <circle cx="9" cy="9" r="2" />
+      <path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21" />
+    </svg>
+  );
+}
+function FileTextIcon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z" />
+      <path d="M14 2v4a2 2 0 0 0 2 2h4" />
+      <path d="M10 9H8" />
+      <path d="M16 13H8" />
+      <path d="M16 17H8" />
+    </svg>
+  );
+}
+function MusicIcon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <path d="M9 18V5l12-2v13" />
+      <circle cx="6" cy="18" r="3" />
+      <circle cx="18" cy="16" r="3" />
+    </svg>
+  );
+}
+function VideoIcon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <path d="m16 13 5.223 3.482a.5.5 0 0 0 .777-.416V7.934a.5.5 0 0 0-.777-.416L16 11" />
+      <rect width="14" height="12" x="2" y="6" rx="2" />
+    </svg>
+  );
+}
+function XIcon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <path d="M18 6 6 18" />
+      <path d="m6 6 12 12" />
+    </svg>
+  );
+}
+function RefreshCwIcon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" />
+      <path d="M21 3v5h-5" />
+      <path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" />
+      <path d="M8 16H3v5" />
+    </svg>
+  );
+}
+function Loader2Icon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+    </svg>
+  );
+}
+function CheckIcon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <path d="M20 6 9 17l-5-5" />
+    </svg>
+  );
+}
+
+// ── File type icon ─────────────────────────────────────────────────────────
+
+function FileTypeIcon({ mimeType }: { mimeType: string }) {
+  const cls = "size-3.5";
+  if (mimeType.startsWith("image/")) return <ImageIcon className={cls} />;
+  if (mimeType.startsWith("audio/")) return <MusicIcon className={cls} />;
+  if (mimeType.startsWith("video/")) return <VideoIcon className={cls} />;
+  return <FileTextIcon className={cls} />;
+}
+
+// ── Status indicator ───────────────────────────────────────────────────────
+
+function StatusBadge({ status }: { status: PendingAttachment["status"] }) {
+  if (status === "uploading") {
+    return <Loader2Icon className="size-3 animate-spin text-blue-400" />;
+  }
+  if (status === "ready") {
+    return <CheckIcon className="size-3 text-emerald-400" />;
+  }
+  return null; // error shows retry button instead
+}
+
+// ── Single attachment card ─────────────────────────────────────────────────
+
+function AttachmentCard({
+  attachment,
+  onRemove,
+  onRetry,
+}: {
+  attachment: PendingAttachment;
+  onRemove: (id: string) => void;
+  onRetry: (id: string) => void;
+}) {
+  const { id, file, preview, status, progress, error } = attachment;
+  const isError = status === "error";
+
+  return (
+    <div
+      className={`
+        csdk-attachment-card group relative flex items-center gap-1.5
+        rounded-lg border px-2 py-1.5 min-w-0 max-w-[160px]
+        transition-colors duration-150
+        ${
+          isError
+            ? "border-red-500/30 bg-red-500/5"
+            : "border-border/60 bg-muted/40 hover:bg-muted/60"
+        }
+      `}
+    >
+      {/* Thumbnail or icon */}
+      <div className="size-7 rounded shrink-0 overflow-hidden bg-muted/60 flex items-center justify-center">
+        {preview ? (
+          <img
+            src={preview}
+            alt={file.name}
+            className="size-full object-cover"
+          />
+        ) : (
+          <FileTypeIcon mimeType={file.type} />
+        )}
+      </div>
+
+      {/* Name + status */}
+      <div className="min-w-0 flex-1">
+        <p className="text-[10px] font-medium truncate leading-tight text-foreground/80">
+          {file.name}
+        </p>
+        <div className="flex items-center gap-1 mt-0.5">
+          {isError ? (
+            <button
+              onClick={() => onRetry(id)}
+              className="flex items-center gap-0.5 text-[9px] text-red-400 hover:text-red-300 cursor-pointer"
+            >
+              <RefreshCwIcon className="size-2.5" />
+              Retry
+            </button>
+          ) : (
+            <>
+              <StatusBadge status={status} />
+              <span className="text-[9px] text-muted-foreground">
+                {status === "uploading"
+                  ? `${progress}%`
+                  : formatBytes(file.size)}
+              </span>
+            </>
+          )}
+        </div>
+      </div>
+
+      {/* Progress bar (uploading only) */}
+      {status === "uploading" && (
+        <div className="absolute bottom-0 left-0 right-0 h-[2px] rounded-b-lg overflow-hidden bg-muted/40">
+          <div
+            className="h-full bg-blue-500 transition-[width] duration-300 ease-out"
+            style={{ width: `${progress}%` }}
+          />
+        </div>
+      )}
+
+      {/* Remove button */}
+      <button
+        onClick={() => onRemove(id)}
+        className="
+          size-4 rounded-full shrink-0 flex items-center justify-center
+          text-muted-foreground/50 hover:text-foreground hover:bg-muted
+          transition-colors cursor-pointer
+        "
+        aria-label="Remove attachment"
+      >
+        <XIcon className="size-2.5" />
+      </button>
+    </div>
+  );
+}
+
+// ── Bytes formatter ────────────────────────────────────────────────────────
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+// ── Main strip ─────────────────────────────────────────────────────────────
+
+export interface AttachmentStripProps {
+  attachments: PendingAttachment[];
+  onRemove: (id: string) => void;
+  onRetry: (id: string) => void;
+  className?: string;
+}
+
+export function AttachmentStrip({
+  attachments,
+  onRemove,
+  onRetry,
+  className = "",
+}: AttachmentStripProps) {
+  if (attachments.length === 0) return null;
+
+  return (
+    <div
+      className={`csdk-attachment-strip flex gap-1.5 overflow-x-auto px-1 py-1.5 scrollbar-none ${className}`}
+    >
+      {attachments.map((att) => (
+        <AttachmentCard
+          key={att.id}
+          attachment={att}
+          onRemove={onRemove}
+          onRetry={onRetry}
+        />
+      ))}
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index f64e3ee..484ea01 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import * as React from "react";
+import * as ReactDOM from "react-dom";
 import { cn } from "../../../lib/utils";
 import { Message, MessageAvatar, MessageContent } from "../../ui/message";
 import { SimpleReasoning } from "../../ui/reasoning";
@@ -456,12 +457,30 @@ export function DefaultMessage({
             </div>
           ) : (
             <>
-              {/* Text content */}
-              {message.content && (
-                <div className="relative">
+              {/* Combined media + text bubble (WhatsApp/Telegram style) */}
+              <div className="relative">
+                {/* Images (if any) — in their own bubble */}
+                {hasAttachments && (
+                  <div
+                    className={cn(
+                      "csdk-message-media rounded-2xl overflow-hidden bg-primary p-[2px]",
+                      !message.content && "max-w-[260px]",
+                      message.content && "max-w-[280px] mb-[3px]",
+                      userMessageClassName,
+                    )}
+                  >
+                    <MessageMedia
+                      attachments={message.attachments!}
+                      hasText={!!message.content}
+                      align="end"
+                    />
+                  </div>
+                )}
+                {/* Text content — same style as original, padding on MessageContent */}
+                {message.content && (
                   <MessageContent
                     className={cn(
-                      "csdk-message-user rounded-lg px-4 py-2 bg-primary text-primary-foreground",
+                      "csdk-message-user rounded-2xl px-4 py-2 bg-primary text-primary-foreground",
                       userMessageClassName,
                     )}
                     markdown
@@ -469,45 +488,37 @@ export function DefaultMessage({
                   >
                     {message.content}
                   </MessageContent>
-                  {/* Edit button — hover reveal */}
-                  {showEditBtn && (
-                    <button
-                      type="button"
-                      onClick={startEdit}
-                      aria-label="Edit message"
-                      className={cn(
-                        "csdk-edit-btn absolute -left-7 top-1/2 -translate-y-1/2",
-                        "size-6 flex items-center justify-center rounded-full",
-                        "text-muted-foreground bg-background border border-border shadow-sm",
-                        "opacity-0 group-hover/user-msg:opacity-100 transition-opacity",
-                        "hover:text-foreground hover:bg-muted",
-                      )}
+                )}
+                {/* Edit button — hover reveal */}
+                {showEditBtn && (
+                  <button
+                    type="button"
+                    onClick={startEdit}
+                    aria-label="Edit message"
+                    className={cn(
+                      "csdk-edit-btn absolute -left-7 top-1/2 -translate-y-1/2",
+                      "size-6 flex items-center justify-center rounded-full",
+                      "text-muted-foreground bg-background border border-border shadow-sm",
+                      "opacity-0 group-hover/user-msg:opacity-100 transition-opacity",
+                      "hover:text-foreground hover:bg-muted cursor-pointer",
+                    )}
+                  >
+                    <svg
+                      width="12"
+                      height="12"
+                      viewBox="0 0 24 24"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth={2}
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
                     >
-                      <svg
-                        width="12"
-                        height="12"
-                        viewBox="0 0 24 24"
-                        fill="none"
-                        stroke="currentColor"
-                        strokeWidth={2}
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                      >
-                        <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" />
-                        <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z" />
-                      </svg>
-                    </button>
-                  )}
-                </div>
-              )}
-              {/* Image Attachments */}
-              {hasAttachments && (
-                <div className="mt-2 flex flex-wrap gap-2 justify-end">
-                  {message.attachments!.map((attachment, index) => (
-                    <AttachmentPreview key={index} attachment={attachment} />
-                  ))}
-                </div>
-              )}
+                      <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" />
+                      <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z" />
+                    </svg>
+                  </button>
+                )}
+              </div>
               {/* Branch Navigator */}
               {showBranchNav && (
                 <BranchNavigator
@@ -888,12 +899,14 @@ export function DefaultMessage({
               </div>
             )}
 
-            {/* Image Attachments */}
+            {/* Attachments (images + files) */}
             {message.attachments && message.attachments.length > 0 && (
-              <div className="mt-2 flex flex-wrap gap-2">
-                {message.attachments.map((attachment, index) => (
-                  <AttachmentPreview key={index} attachment={attachment} />
-                ))}
+              <div className="csdk-assistant-attachments mt-2">
+                <MessageMedia
+                  attachments={message.attachments}
+                  hasText={!!message.content}
+                  align="start"
+                />
               </div>
             )}
 
@@ -928,84 +941,435 @@ export function DefaultMessage({
   );
 }
 
+// ── Attachment helpers ──────────────────────────────────────────────────────
+
+function getAttachmentSrc(attachment: MessageAttachment): string | null {
+  if (attachment.url) return attachment.url;
+  if (attachment.data) {
+    return attachment.data.startsWith("data:")
+      ? attachment.data
+      : `data:${attachment.mimeType};base64,${attachment.data}`;
+  }
+  return null;
+}
+
 /**
- * Attachment preview component
+ * Image lightbox — fullscreen view with CSS animation.
+ * Uses portal to render at document root for proper z-index.
+ *
+ * Animation: backdrop fade-in 200ms ease-out, image scale 0.92→1 + fade.
+ * Exit: backdrop fade-out 180ms ease-in, image scale 1→0.95 + fade.
+ * Follows: staging-dim-background, easing-entrance-ease-out, easing-exit-ease-in, duration-small-state
  */
-function AttachmentPreview({ attachment }: { attachment: MessageAttachment }) {
-  const [expanded, setExpanded] = React.useState(false);
+function ImageLightbox({
+  src,
+  alt,
+  onClose,
+}: {
+  src: string;
+  alt: string;
+  onClose: () => void;
+}) {
+  const [closing, setClosing] = React.useState(false);
+  const backdropRef = React.useRef<HTMLDivElement>(null);
+
+  const handleClose = React.useCallback(() => {
+    setClosing(true);
+    // Wait for exit animation (180ms ease-in)
+    setTimeout(onClose, 180);
+  }, [onClose]);
+
+  // Close on Escape
+  React.useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === "Escape") handleClose();
+    };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [handleClose]);
+
+  // Prevent body scroll
+  React.useEffect(() => {
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = prev;
+    };
+  }, []);
 
-  if (attachment.type !== "image") {
-    // For non-image attachments, show a simple file indicator
-    return (
-      <div className="flex items-center gap-2 rounded-lg border bg-muted/50 px-3 py-2 text-sm">
-        <span className="text-muted-foreground">{attachment.type}</span>
-        <span>{attachment.filename || "Attachment"}</span>
+  const portal = (
+    <div
+      ref={backdropRef}
+      className="csdk-lightbox csdk-lightbox-backdrop fixed inset-0 z-[9999] flex items-center justify-center cursor-zoom-out"
+      onClick={handleClose}
+      style={{
+        animation: closing
+          ? "csdk-lightbox-backdrop-out 180ms ease-in forwards"
+          : "csdk-lightbox-backdrop-in 200ms ease-out forwards",
+      }}
+    >
+      {/* Scrim — hardcoded dark, no theme vars */}
+      <div
+        className="csdk-lightbox-scrim absolute inset-0"
+        style={{
+          backgroundColor: "rgba(0, 0, 0, 0.88)",
+          backdropFilter: "blur(12px)",
+          WebkitBackdropFilter: "blur(12px)",
+          animation: closing
+            ? "csdk-lightbox-fade-out 180ms ease-in forwards"
+            : "csdk-lightbox-fade-in 200ms ease-out forwards",
+        }}
+      />
+
+      {/* Image */}
+      <div
+        className="csdk-lightbox-content relative z-10 max-w-[90vw] max-h-[90vh]"
+        style={{
+          animation: closing
+            ? "csdk-lightbox-img-out 180ms ease-in forwards"
+            : "csdk-lightbox-img-in 220ms cubic-bezier(0.22, 1, 0.36, 1) forwards",
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <img
+          src={src}
+          alt={alt}
+          className="csdk-lightbox-image max-w-full max-h-[90vh] object-contain rounded-xl"
+          style={{ boxShadow: "0 25px 50px -12px rgba(0,0,0,0.5)" }}
+          draggable={false}
+        />
+        {/* Close button */}
+        <button
+          type="button"
+          className="csdk-lightbox-close absolute -top-3 -right-3 size-8 flex items-center justify-center rounded-full shadow-lg transition-[background,transform] duration-150 cursor-pointer active:scale-95"
+          style={{ backgroundColor: "rgba(255,255,255,0.9)" }}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.backgroundColor = "rgba(255,255,255,1)";
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.backgroundColor = "rgba(255,255,255,0.9)";
+          }}
+          onClick={handleClose}
+        >
+          <svg
+            className="size-4"
+            style={{ color: "#333" }}
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2.5}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+        </button>
       </div>
-    );
-  }
 
-  // Image preview - use URL if available, otherwise use base64 data
-  let src: string;
-  if (attachment.url) {
-    src = attachment.url;
-  } else if (attachment.data) {
-    src = attachment.data.startsWith("data:")
-      ? attachment.data
-      : `data:${attachment.mimeType};base64,${attachment.data}`;
-  } else {
-    // No source available - shouldn't happen but handle gracefully
-    return null;
-  }
+      {/* Keyframe styles (injected once) */}
+      <style>{`
+        @keyframes csdk-lightbox-fade-in { from { opacity: 0; } to { opacity: 1; } }
+        @keyframes csdk-lightbox-fade-out { from { opacity: 1; } to { opacity: 0; } }
+        @keyframes csdk-lightbox-img-in { from { opacity: 0; transform: scale(0.92); } to { opacity: 1; transform: scale(1); } }
+        @keyframes csdk-lightbox-img-out { from { opacity: 1; transform: scale(1); } to { opacity: 0; transform: scale(0.95); } }
+        @keyframes csdk-lightbox-backdrop-in { from { opacity: 0; } to { opacity: 1; } }
+        @keyframes csdk-lightbox-backdrop-out { from { opacity: 1; } to { opacity: 0; } }
+      `}</style>
+    </div>
+  );
 
+  // Portal to body
+  return typeof document !== "undefined"
+    ? ReactDOM.createPortal(portal, document.body)
+    : null;
+}
+
+/**
+ * Single image thumbnail — auto-sized, clickable, opens lightbox.
+ * Preserves aspect ratio. Max width constrained by bubble, height auto.
+ * active:scale-[0.98] for press feedback (physics-active-state).
+ */
+function ImageThumb({
+  src,
+  alt,
+  className,
+}: {
+  src: string;
+  alt: string;
+  className?: string;
+}) {
+  const [expanded, setExpanded] = React.useState(false);
   return (
     <>
       <button
         type="button"
         onClick={() => setExpanded(true)}
-        className="relative rounded-lg overflow-hidden border bg-muted/50 hover:opacity-90 transition-opacity"
+        className={cn(
+          "csdk-attachment-image relative overflow-hidden cursor-zoom-in",
+          "transition-[opacity,transform] duration-150 hover:opacity-90 active:scale-[0.98]",
+          className,
+        )}
+        style={{ backgroundColor: "#000" }}
       >
         <img
           src={src}
-          alt={attachment.filename || "Image"}
-          className="max-w-[200px] max-h-[150px] object-cover"
+          alt={alt}
+          className="w-full h-full object-cover"
+          loading="lazy"
+          draggable={false}
         />
       </button>
-
-      {/* Fullscreen modal */}
       {expanded && (
+        <ImageLightbox src={src} alt={alt} onClose={() => setExpanded(false)} />
+      )}
+    </>
+  );
+}
+
+/**
+ * File attachment card — compact, non-image files
+ */
+function FileCard({ attachment }: { attachment: MessageAttachment }) {
+  const iconType =
+    attachment.type === "audio"
+      ? "audio"
+      : attachment.type === "video"
+        ? "video"
+        : "file";
+  const colors = {
+    audio: "text-emerald-500 bg-emerald-500/10",
+    video: "text-purple-500 bg-purple-500/10",
+    file: "text-blue-500 bg-blue-500/10",
+  };
+  const icons = {
+    audio: (
+      <path d="M9 18V5l12-2v13M6 18a3 3 0 1 0 0-6 3 3 0 0 0 0 6ZM18 16a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z" />
+    ),
+    video: (
+      <>
+        <path d="m16 13 5.223 3.482a.5.5 0 0 0 .777-.416V7.934a.5.5 0 0 0-.777-.416L16 11" />
+        <rect width="14" height="12" x="2" y="6" rx="2" />
+      </>
+    ),
+    file: (
+      <>
+        <path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z" />
+        <path d="M14 2v4a2 2 0 0 0 2 2h4" />
+      </>
+    ),
+  };
+
+  const href =
+    attachment.url ||
+    (attachment.data?.startsWith("data:") ? attachment.data : null);
+
+  return (
+    <div
+      className={cn(
+        "csdk-attachment-file flex items-center gap-2 rounded-lg border border-border/50 bg-muted/30 px-2.5 py-2 min-w-0 max-w-full",
+      )}
+    >
+      <div
+        className={cn(
+          "size-8 rounded-md flex items-center justify-center shrink-0",
+          colors[iconType],
+        )}
+      >
+        <svg
+          className="size-4"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          {icons[iconType]}
+        </svg>
+      </div>
+      <div className="min-w-0 flex-1">
+        <p className="text-xs font-medium truncate">
+          {attachment.filename || "Attachment"}
+        </p>
+        <p className="text-[10px] text-muted-foreground uppercase">
+          {attachment.mimeType?.split("/")[1] || attachment.type}
+        </p>
+      </div>
+      {href && (
+        <a
+          href={href}
+          target="_blank"
+          rel="noopener noreferrer"
+          download={attachment.filename}
+          className="shrink-0 text-muted-foreground/50 hover:text-foreground transition-colors"
+        >
+          <svg
+            className="size-3.5"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={2}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+            <polyline points="7 10 12 15 17 10" />
+            <line x1="12" x2="12" y1="15" y2="3" />
+          </svg>
+        </a>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Image grid — WhatsApp/Telegram-style layout
+ * 1 image: full width
+ * 2 images: side by side
+ * 3 images: 2 top + 1 bottom
+ * 4+ images: 2x2 grid with +N overlay
+ */
+function ImageGrid({
+  images,
+  bubbleRadius,
+}: {
+  images: MessageAttachment[];
+  bubbleRadius?: string;
+}) {
+  const srcs = images
+    .map((img) => getAttachmentSrc(img))
+    .filter(Boolean) as string[];
+  if (srcs.length === 0) return null;
+
+  // Concentric radius: inner = outer bubble radius (16px) minus padding (2px) = 14px
+  const innerRadius = bubbleRadius ? `calc(${bubbleRadius} - 2px)` : "0.875rem";
+
+  if (srcs.length === 1) {
+    return (
+      <div
+        className="csdk-attachment-grid"
+        style={{ borderRadius: innerRadius, overflow: "hidden" }}
+      >
+        <ImageThumb
+          src={srcs[0]}
+          alt={images[0].filename || "Image"}
+          className="w-full"
+        />
+      </div>
+    );
+  }
+
+  if (srcs.length === 2) {
+    return (
+      <div
+        className="csdk-attachment-grid grid grid-cols-2 gap-[2px]"
+        style={{ borderRadius: innerRadius, overflow: "hidden" }}
+      >
+        {srcs.map((src, i) => (
+          <ImageThumb
+            key={i}
+            src={src}
+            alt={images[i].filename || "Image"}
+            className="aspect-square"
+          />
+        ))}
+      </div>
+    );
+  }
+
+  if (srcs.length === 3) {
+    return (
+      <div
+        className="csdk-attachment-grid grid grid-cols-2 gap-[2px]"
+        style={{ borderRadius: innerRadius, overflow: "hidden" }}
+      >
+        <ImageThumb
+          src={srcs[0]}
+          alt={images[0].filename || "Image"}
+          className="col-span-2 max-h-[180px] min-h-[100px]"
+        />
+        <ImageThumb
+          src={srcs[1]}
+          alt={images[1].filename || "Image"}
+          className="aspect-square"
+        />
+        <ImageThumb
+          src={srcs[2]}
+          alt={images[2].filename || "Image"}
+          className="aspect-square"
+        />
+      </div>
+    );
+  }
+
+  // 4+ images: 2x2 grid, last cell shows +N if more
+  const showOverlay = srcs.length > 4;
+  const gridSrcs = srcs.slice(0, 4);
+
+  return (
+    <div
+      className="csdk-attachment-grid grid grid-cols-2 gap-[2px]"
+      style={{ borderRadius: innerRadius, overflow: "hidden" }}
+    >
+      {gridSrcs.map((src, i) => (
+        <div key={i} className="relative aspect-square">
+          <ImageThumb
+            src={src}
+            alt={images[i].filename || "Image"}
+            className="w-full h-full"
+          />
+          {i === 3 && showOverlay && (
+            <div className="absolute inset-0 bg-black/50 flex items-center justify-center pointer-events-none">
+              <span className="text-white text-lg font-semibold">
+                +{srcs.length - 4}
+              </span>
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * MessageMedia — renders attachments in a message bubble.
+ * Handles image-only, image+text, file cards, and mixed content.
+ *
+ * Layout follows WhatsApp/Telegram pattern:
+ * - Images at top of bubble (no padding), text below with padding
+ * - Files shown as compact cards below text
+ */
+function MessageMedia({
+  attachments,
+  hasText,
+  align = "end",
+}: {
+  attachments: MessageAttachment[];
+  hasText: boolean;
+  align?: "start" | "end";
+}) {
+  const images = attachments.filter((a) => a.type === "image");
+  const files = attachments.filter((a) => a.type !== "image");
+
+  return (
+    <>
+      {images.length > 0 && (
+        <div className={cn("csdk-attachment-images", hasText ? "mb-0" : "")}>
+          <ImageGrid images={images} bubbleRadius="0.5rem" />
+        </div>
+      )}
+      {files.length > 0 && (
         <div
-          className="csdk-image-backdrop fixed inset-0 z-50 flex items-center justify-center bg-black/80"
-          onClick={() => setExpanded(false)}
+          className={cn(
+            "csdk-attachment-files flex flex-col gap-1",
+            hasText || images.length > 0 ? "px-3 pb-2 pt-1" : "p-1.5",
+            align === "end" ? "items-end" : "items-start",
+          )}
         >
-          <div className="relative max-w-[90vw] max-h-[90vh]">
-            <img
-              src={src}
-              alt={attachment.filename || "Image (expanded)"}
-              className="max-w-full max-h-full object-contain rounded-lg"
-            />
-            <button
-              type="button"
-              className="csdk-image-close absolute top-2 right-2 bg-white/90 rounded-full p-2 hover:bg-white transition-colors"
-              onClick={(e) => {
-                e.stopPropagation();
-                setExpanded(false);
-              }}
-            >
-              <svg
-                className="w-4 h-4"
-                fill="none"
-                viewBox="0 0 24 24"
-                stroke="currentColor"
-                strokeWidth={2}
-              >
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  d="M6 18L18 6M6 6l12 12"
-                />
-              </svg>
-            </button>
-          </div>
+          {files.map((file, i) => (
+            <FileCard key={i} attachment={file} />
+          ))}
         </div>
       )}
     </>
diff --git a/packages/copilot-sdk/src/ui/components/drop-zone-overlay.tsx b/packages/copilot-sdk/src/ui/components/drop-zone-overlay.tsx
new file mode 100644
index 0000000..1d5344b
--- /dev/null
+++ b/packages/copilot-sdk/src/ui/components/drop-zone-overlay.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+/**
+ * DropZoneOverlay — Shows when files are dragged over the chat area.
+ */
+
+const svgProps = {
+  xmlns: "http://www.w3.org/2000/svg",
+  viewBox: "0 0 24 24",
+  fill: "none",
+  stroke: "currentColor",
+  strokeWidth: 2,
+  strokeLinecap: "round" as const,
+  strokeLinejoin: "round" as const,
+};
+function PaperclipIcon({ className }: { className?: string }) {
+  return (
+    <svg {...svgProps} className={className}>
+      <path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l8.57-8.57A4 4 0 1 1 18 8.84l-8.59 8.57a2 2 0 0 1-2.83-2.83l8.49-8.48" />
+    </svg>
+  );
+}
+
+export interface DropZoneOverlayProps {
+  isDragging: boolean;
+  className?: string;
+}
+
+export function DropZoneOverlay({
+  isDragging,
+  className = "",
+}: DropZoneOverlayProps) {
+  if (!isDragging) return null;
+
+  return (
+    <div
+      className={`
+        csdk-drop-zone absolute inset-0 z-50 flex items-center justify-center
+        bg-background/80 backdrop-blur-sm border-2 border-dashed border-primary/40
+        rounded-xl pointer-events-none
+        ${className}
+      `}
+    >
+      <div className="flex flex-col items-center gap-2 text-primary/70">
+        <div className="size-10 rounded-xl bg-primary/10 flex items-center justify-center">
+          <PaperclipIcon className="size-5" />
+        </div>
+        <p className="text-sm font-medium">Drop files to attach</p>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/copilot-sdk/src/ui/hooks/useAttachments.ts b/packages/copilot-sdk/src/ui/hooks/useAttachments.ts
new file mode 100644
index 0000000..7a3aed8
--- /dev/null
+++ b/packages/copilot-sdk/src/ui/hooks/useAttachments.ts
@@ -0,0 +1,452 @@
+"use client";
+
+/**
+ * useAttachments — Core hook for file upload management in chat inputs.
+ *
+ * Works with both the SDK's default input and custom user inputs.
+ * Handles file validation, upload progress, cancellation, and drag-drop.
+ *
+ * @example
+ * ```tsx
+ * const { attachments, addFiles, removeAttachment, getReadyAttachments, dragHandlers } =
+ *   useAttachments({ upload: "/api/copilot/upload", maxFiles: 5 });
+ * ```
+ */
+
+import { useState, useCallback, useRef, useMemo } from "react";
+import type { MessageAttachment } from "../../core/types/message";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type AttachmentStatus = "uploading" | "ready" | "error";
+
+export interface PendingAttachment {
+  id: string;
+  file: File;
+  /** Object URL for image preview */
+  preview?: string;
+  status: AttachmentStatus;
+  /** Upload progress 0-100 */
+  progress: number;
+  error?: string;
+  /** Final attachment data when ready */
+  attachment?: MessageAttachment;
+}
+
+export type UploadConfig =
+  | string
+  | {
+      url: string;
+      headers?: Record<string, string> | (() => Record<string, string>);
+      body?: Record<string, unknown> | (() => Record<string, unknown>);
+    }
+  | ((file: File) => Promise<MessageAttachment>);
+
+export interface UseAttachmentsConfig {
+  /** Upload handler — string (URL), object (URL+options), or function (custom) */
+  upload?: UploadConfig;
+  /** Maximum number of files (default: 5) */
+  maxFiles?: number;
+  /** Maximum file size in bytes (default: 10MB) */
+  maxFileSize?: number;
+  /** Allowed MIME types (default: images + PDF) */
+  allowedFileTypes?: string[];
+}
+
+export interface UseAttachmentsReturn {
+  /** Current pending attachments */
+  attachments: PendingAttachment[];
+  /** Whether files are being dragged over the drop zone */
+  isDragging: boolean;
+  /** Add files (from file picker or drop) */
+  addFiles: (files: FileList | File[]) => void;
+  /** Remove a pending attachment */
+  removeAttachment: (id: string) => void;
+  /** Cancel an in-progress upload */
+  cancelUpload: (id: string) => void;
+  /** Retry a failed upload */
+  retryUpload: (id: string) => void;
+  /** Clear all attachments */
+  clearAll: () => void;
+  /** Get ready attachments as MessageAttachment[] for sending */
+  getReadyAttachments: () => MessageAttachment[];
+  /** Whether any attachments exist */
+  hasAttachments: boolean;
+  /** Whether any upload is in progress */
+  isUploading: boolean;
+  /** Whether message can be sent (has ready attachments, none still uploading) */
+  canSend: boolean;
+  /** Drag-drop event handlers — spread on the container element */
+  dragHandlers: {
+    onDragEnter: (e: React.DragEvent) => void;
+    onDragOver: (e: React.DragEvent) => void;
+    onDragLeave: (e: React.DragEvent) => void;
+    onDrop: (e: React.DragEvent) => void;
+  };
+  /** Open native file picker */
+  openFilePicker: () => void;
+  /** Ref for hidden file input */
+  fileInputRef: React.RefObject<HTMLInputElement | null>;
+  /** Handler for file input change */
+  onFileInputChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+}
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_FILES = 5;
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+const DEFAULT_ALLOWED_TYPES = ["image/*", "application/pdf"];
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function generateId(): string {
+  return `att_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+}
+
+function getAttachmentType(mimeType: string): MessageAttachment["type"] {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("video/")) return "video";
+  return "file";
+}
+
+function isTypeAllowed(file: File, allowedTypes: string[]): boolean {
+  for (const type of allowedTypes) {
+    if (type === file.type) return true;
+    if (type.endsWith("/*") && file.type.startsWith(type.slice(0, -1)))
+      return true;
+    if (type.startsWith(".") && file.name.toLowerCase().endsWith(type))
+      return true;
+  }
+  return false;
+}
+
+function fileToBase64(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string);
+    reader.onerror = () => reject(new Error("Failed to read file"));
+    reader.readAsDataURL(file);
+  });
+}
+
+function createPreview(file: File): string | undefined {
+  if (file.type.startsWith("image/")) {
+    return URL.createObjectURL(file);
+  }
+  return undefined;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+export function useAttachments(
+  config: UseAttachmentsConfig = {},
+): UseAttachmentsReturn {
+  const {
+    upload,
+    maxFiles = DEFAULT_MAX_FILES,
+    maxFileSize = DEFAULT_MAX_FILE_SIZE,
+    allowedFileTypes = DEFAULT_ALLOWED_TYPES,
+  } = config;
+
+  const [attachments, setAttachments] = useState<PendingAttachment[]>([]);
+  const [isDragging, setIsDragging] = useState(false);
+  const abortControllers = useRef(new Map<string, AbortController>());
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const dragCounter = useRef(0);
+
+  // ── Upload a single file ─────────────────────────────────────────────
+
+  const uploadFile = useCallback(
+    async (id: string, file: File) => {
+      const updateProgress = (progress: number) => {
+        setAttachments((prev) =>
+          prev.map((a) => (a.id === id ? { ...a, progress } : a)),
+        );
+      };
+
+      const markReady = (attachment: MessageAttachment) => {
+        setAttachments((prev) =>
+          prev.map((a) =>
+            a.id === id
+              ? { ...a, status: "ready" as const, progress: 100, attachment }
+              : a,
+          ),
+        );
+      };
+
+      const markError = (error: string) => {
+        setAttachments((prev) =>
+          prev.map((a) =>
+            a.id === id ? { ...a, status: "error" as const, error } : a,
+          ),
+        );
+      };
+
+      try {
+        const controller = new AbortController();
+        abortControllers.current.set(id, controller);
+
+        let result: MessageAttachment;
+
+        if (typeof upload === "function") {
+          // Custom function — no progress tracking (user handles it)
+          updateProgress(50);
+          result = await upload(file);
+        } else if (upload) {
+          // URL string or object — upload to server with progress
+          const uploadConfig =
+            typeof upload === "string" ? { url: upload } : upload;
+          const extraHeaders =
+            typeof uploadConfig.headers === "function"
+              ? uploadConfig.headers()
+              : uploadConfig.headers;
+          const extraBody =
+            typeof uploadConfig.body === "function"
+              ? uploadConfig.body()
+              : uploadConfig.body;
+
+          const base64 = await fileToBase64(file);
+          updateProgress(30);
+
+          const body = JSON.stringify({
+            data: base64,
+            mimeType: file.type,
+            filename: file.name,
+            ...extraBody,
+          });
+
+          const res = await fetch(uploadConfig.url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...extraHeaders },
+            body,
+            signal: controller.signal,
+          });
+
+          updateProgress(90);
+
+          if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
+          const json = await res.json();
+          const url = json.url ?? json.data?.url;
+          if (!url) throw new Error("Upload returned no URL");
+
+          result = {
+            type: getAttachmentType(file.type),
+            url,
+            mimeType: file.type,
+            filename: file.name,
+          };
+        } else {
+          // No upload config — fallback to base64
+          updateProgress(50);
+          const data = await fileToBase64(file);
+          result = {
+            type: getAttachmentType(file.type),
+            data,
+            mimeType: file.type,
+            filename: file.name,
+          };
+        }
+
+        markReady(result);
+      } catch (err) {
+        if ((err as Error)?.name === "AbortError") return; // cancelled
+        markError((err as Error)?.message ?? "Upload failed");
+      } finally {
+        abortControllers.current.delete(id);
+      }
+    },
+    [upload],
+  );
+
+  // ── Add files ────────────────────────────────────────────────────────
+
+  const addFiles = useCallback(
+    (files: FileList | File[]) => {
+      const fileArray = Array.from(files);
+      const remaining = maxFiles - attachments.length;
+      if (remaining <= 0) return;
+
+      const toAdd = fileArray.slice(0, remaining);
+
+      const newAttachments: PendingAttachment[] = [];
+
+      for (const file of toAdd) {
+        // Validate type
+        if (!isTypeAllowed(file, allowedFileTypes)) continue;
+        // Validate size
+        if (file.size > maxFileSize) continue;
+
+        const id = generateId();
+        const preview = createPreview(file);
+
+        newAttachments.push({
+          id,
+          file,
+          preview,
+          status: "uploading",
+          progress: 0,
+        });
+      }
+
+      if (newAttachments.length === 0) return;
+
+      setAttachments((prev) => [...prev, ...newAttachments]);
+
+      // Start uploads
+      for (const att of newAttachments) {
+        uploadFile(att.id, att.file);
+      }
+    },
+    [attachments.length, maxFiles, maxFileSize, allowedFileTypes, uploadFile],
+  );
+
+  // ── Remove ───────────────────────────────────────────────────────────
+
+  const removeAttachment = useCallback((id: string) => {
+    setAttachments((prev) => {
+      const att = prev.find((a) => a.id === id);
+      if (att?.preview) URL.revokeObjectURL(att.preview);
+      return prev.filter((a) => a.id !== id);
+    });
+    // Cancel if still uploading
+    const controller = abortControllers.current.get(id);
+    if (controller) {
+      controller.abort();
+      abortControllers.current.delete(id);
+    }
+  }, []);
+
+  // ── Cancel upload ────────────────────────────────────────────────────
+
+  const cancelUpload = useCallback(
+    (id: string) => {
+      removeAttachment(id);
+    },
+    [removeAttachment],
+  );
+
+  // ── Retry ────────────────────────────────────────────────────────────
+
+  const retryUpload = useCallback(
+    (id: string) => {
+      setAttachments((prev) =>
+        prev.map((a) =>
+          a.id === id
+            ? {
+                ...a,
+                status: "uploading" as const,
+                progress: 0,
+                error: undefined,
+              }
+            : a,
+        ),
+      );
+      const att = attachments.find((a) => a.id === id);
+      if (att) uploadFile(id, att.file);
+    },
+    [attachments, uploadFile],
+  );
+
+  // ── Clear all ────────────────────────────────────────────────────────
+
+  const clearAll = useCallback(() => {
+    for (const att of attachments) {
+      if (att.preview) URL.revokeObjectURL(att.preview);
+    }
+    for (const controller of abortControllers.current.values()) {
+      controller.abort();
+    }
+    abortControllers.current.clear();
+    setAttachments([]);
+  }, [attachments]);
+
+  // ── Get ready attachments ────────────────────────────────────────────
+
+  const getReadyAttachments = useCallback((): MessageAttachment[] => {
+    return attachments
+      .filter((a) => a.status === "ready" && a.attachment)
+      .map((a) => a.attachment!);
+  }, [attachments]);
+
+  // ── Derived state ────────────────────────────────────────────────────
+
+  const hasAttachments = attachments.length > 0;
+  const isUploading = attachments.some((a) => a.status === "uploading");
+  const canSend =
+    hasAttachments &&
+    attachments.some((a) => a.status === "ready") &&
+    !isUploading;
+
+  // ── Drag-drop handlers ───────────────────────────────────────────────
+
+  const dragHandlers = useMemo(
+    () => ({
+      onDragEnter: (e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        dragCounter.current++;
+        if (e.dataTransfer.types.includes("Files")) {
+          setIsDragging(true);
+        }
+      },
+      onDragOver: (e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+      },
+      onDragLeave: (e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        dragCounter.current--;
+        if (dragCounter.current === 0) {
+          setIsDragging(false);
+        }
+      },
+      onDrop: (e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        dragCounter.current = 0;
+        setIsDragging(false);
+        if (e.dataTransfer.files?.length) {
+          addFiles(e.dataTransfer.files);
+        }
+      },
+    }),
+    [addFiles],
+  );
+
+  // ── File input helpers ───────────────────────────────────────────────
+
+  const openFilePicker = useCallback(() => {
+    fileInputRef.current?.click();
+  }, []);
+
+  const onFileInputChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      if (e.target.files?.length) {
+        addFiles(e.target.files);
+      }
+      // Reset so same file can be selected again
+      if (fileInputRef.current) fileInputRef.current.value = "";
+    },
+    [addFiles],
+  );
+
+  return {
+    attachments,
+    isDragging,
+    addFiles,
+    removeAttachment,
+    cancelUpload,
+    retryUpload,
+    clearAll,
+    getReadyAttachments,
+    hasAttachments,
+    isUploading,
+    canSend,
+    dragHandlers,
+    openFilePicker,
+    fileInputRef,
+    onFileInputChange,
+  };
+}
diff --git a/packages/copilot-sdk/src/ui/index.ts b/packages/copilot-sdk/src/ui/index.ts
index b816373..408900e 100644
--- a/packages/copilot-sdk/src/ui/index.ts
+++ b/packages/copilot-sdk/src/ui/index.ts
@@ -366,3 +366,18 @@ export const ChatPrimitives = {
 };
 
 export type { MessageListProps } from "./components/composed/chat/message-list";
+
+// ============================================
+// Attachments
+// ============================================
+export { useAttachments } from "./hooks/useAttachments";
+export type {
+  PendingAttachment,
+  UseAttachmentsConfig,
+  UseAttachmentsReturn,
+  UploadConfig,
+} from "./hooks/useAttachments";
+export { AttachmentStrip } from "./components/attachment-strip";
+export type { AttachmentStripProps } from "./components/attachment-strip";
+export { DropZoneOverlay } from "./components/drop-zone-overlay";
+export type { DropZoneOverlayProps } from "./components/drop-zone-overlay";

From 025532d36dbbb8b38767651f794702979fd0cc26 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Thu, 26 Mar 2026 13:47:28 +0530
Subject: [PATCH 52/72] feat(attachments): enhance attachment functionality and
 error handling

- Added `onError` callback to `createYourGPT` for improved error monitoring during adapter operations.
- Introduced new documentation for handling attachments, including examples for enabling and sending messages with attachments.
- Updated `AbstractChat` to inline text file attachments into message content for better integration with LLMs.
- Enhanced `useAttachments` hook to support additional file types and local reading of text files without upload.
- Refactored attachment rendering in chat components for a more cohesive user experience.
---
 apps/docs/alpha-docs/STORAGE-ADAPTER.md       |  16 +-
 .../docs/{multimodal.mdx => attachments.mdx}  |   6 +-
 apps/docs/content/docs/headless.mdx           | 112 ++++++++
 apps/docs/content/docs/meta.json              |   2 +-
 apps/docs/content/docs/overview.mdx           |   2 +-
 apps/docs/content/docs/server/storage.mdx     |  29 +-
 .../src/chat/classes/AbstractChat.ts          |  52 +++-
 .../composed/chat/default-message.tsx         | 200 +++++++------
 .../src/ui/hooks/useAttachments.ts            |  52 +++-
 .../src/ui/hooks/useInternalThreadManager.ts  |   8 +
 packages/llm-sdk/src/core/types.ts            |   4 +
 .../llm-sdk/src/server/storage-helpers.ts     |  32 ++-
 packages/llm-sdk/src/yourgpt/index.ts         | 272 ++++++++++++------
 13 files changed, 596 insertions(+), 191 deletions(-)
 rename apps/docs/content/docs/{multimodal.mdx => attachments.mdx} (99%)

diff --git a/apps/docs/alpha-docs/STORAGE-ADAPTER.md b/apps/docs/alpha-docs/STORAGE-ADAPTER.md
index 8df3158..d17b9e5 100644
--- a/apps/docs/alpha-docs/STORAGE-ADAPTER.md
+++ b/apps/docs/alpha-docs/STORAGE-ADAPTER.md
@@ -145,8 +145,22 @@ const runtime = createRuntime({ provider, model, storage: myStorage });
 - `uploadFile` failure → Error returned to client (4xx/5xx)
 - All errors are logged with `[Runtime]` prefix
 
+### `onError` callback
+
+```ts
+const yourgpt = createYourGPT({
+  apiKey,
+  widgetUid,
+  onError: (error, operation, params) => {
+    // operation: "createSession" | "saveMessages" | "uploadFile"
+    // params: { sessionId, messageCount, roles, filename, mimeType, ... }
+    logger.error(`[YourGPT:${operation}]`, error.message, params);
+  },
+});
+```
+
 ## Alpha Notes
 
 - The `endpoint` option in `createYourGPT` will become internal in GA (defaults to production API)
 - `getSessions()` and `getMessages()` on StorageAdapter are reserved for future thread sync
-- File upload API contract (`/copilot-sdk/uploadMedia`) may change
+- File upload uses pre-signed URLs via `/copilot-sdk/getSignedUrl` — contract may change
diff --git a/apps/docs/content/docs/multimodal.mdx b/apps/docs/content/docs/attachments.mdx
similarity index 99%
rename from apps/docs/content/docs/multimodal.mdx
rename to apps/docs/content/docs/attachments.mdx
index 82b3734..4edd12d 100644
--- a/apps/docs/content/docs/multimodal.mdx
+++ b/apps/docs/content/docs/attachments.mdx
@@ -1,7 +1,7 @@
 ---
-title: Multimodal
-description: Send images, files, and documents with messages
-icon: Image
+title: Attachments
+description: Send images, PDFs, and files alongside chat messages
+icon: Paperclip
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
diff --git a/apps/docs/content/docs/headless.mdx b/apps/docs/content/docs/headless.mdx
index 40e99fa..32eed7d 100644
--- a/apps/docs/content/docs/headless.mdx
+++ b/apps/docs/content/docs/headless.mdx
@@ -143,3 +143,115 @@ messageMeta.updateMeta(messageId, prev => ({ ...prev, count: (prev.count as numb
 - Metadata is **in-memory only** — resets when the provider unmounts. Sync to your own storage in event handlers if you need persistence.
 - Multiple components can read the same `messageId` — all re-render on any write.
 - Handlers in `useCopilotEvent` run synchronously during streaming — keep them fast.
+
+---
+
+## Attachment Primitives
+
+Build custom file upload UIs with the `useAttachments` hook and companion components.
+
+### `useAttachments`
+
+Core hook for file upload management — handles validation, upload progress, cancellation, retry, and drag-drop.
+
+```tsx
+import { useAttachments, AttachmentStrip, DropZoneOverlay } from "@yourgpt/copilot-sdk/ui";
+
+function MyCustomInput() {
+  const { send } = useCopilotChatContext();
+
+  const {
+    attachments,           // PendingAttachment[] — current files
+    addFiles,              // (files: FileList | File[]) => void
+    removeAttachment,      // (id: string) => void
+    cancelUpload,          // (id: string) => void
+    retryUpload,           // (id: string) => void
+    clearAll,              // () => void
+    getReadyAttachments,   // () => MessageAttachment[]
+    hasAttachments,        // boolean
+    isUploading,           // boolean
+    canSend,               // boolean (has ready files, none uploading)
+    dragHandlers,          // spread on container for drag-drop
+    isDragging,            // boolean
+    openFilePicker,        // () => void
+    fileInputRef,          // ref for hidden <input type="file">
+    onFileInputChange,     // onChange handler for file input
+  } = useAttachments({
+    // Server upload URL (string), URL + options (object), or custom handler (function)
+    upload: "/api/copilot/upload",
+    maxFiles: 5,                                    // default: 5
+    maxFileSize: 10 * 1024 * 1024,                  // default: 10MB
+    allowedFileTypes: ["image/*", "application/pdf"], // default
+  });
+
+  const handleSend = (text: string) => {
+    const files = getReadyAttachments();
+    send(text, files.length ? files : undefined);
+    clearAll();
+  };
+
+  return (
+    <div {...dragHandlers} className="relative">
+      <DropZoneOverlay isDragging={isDragging} />
+      <AttachmentStrip
+        attachments={attachments}
+        onRemove={removeAttachment}
+        onRetry={retryUpload}
+      />
+      <textarea ... />
+      <button onClick={openFilePicker}>Attach</button>
+      <input ref={fileInputRef} type="file" hidden multiple onChange={onFileInputChange} />
+      <button onClick={() => handleSend(text)}>Send</button>
+    </div>
+  );
+}
+```
+
+#### Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `upload` | `string \| object \| function` | — | Upload handler (see [Attachments](/docs/attachments)) |
+| `maxFiles` | `number` | `5` | Maximum concurrent files |
+| `maxFileSize` | `number` | `10MB` | Max file size in bytes |
+| `allowedFileTypes` | `string[]` | `["image/*", "application/pdf", ...]` | Allowed MIME types |
+
+#### PendingAttachment
+
+Each item in the `attachments` array:
+
+```ts
+{
+  id: string;
+  file: File;
+  preview?: string;       // object URL for image thumbnails
+  status: "uploading" | "ready" | "error";
+  progress: number;       // 0-100
+  error?: string;
+  attachment?: MessageAttachment; // final result when ready
+}
+```
+
+### `AttachmentStrip`
+
+Compact horizontal strip showing pending attachments. Each file shows a thumbnail (images) or type icon, filename, upload progress bar, and remove/retry button.
+
+```tsx
+<AttachmentStrip
+  attachments={attachments}
+  onRemove={removeAttachment}
+  onRetry={retryUpload}
+  className="mb-2"
+/>
+```
+
+### `DropZoneOverlay`
+
+Overlay that appears when files are dragged over the container. Spread `dragHandlers` from `useAttachments` on the parent element.
+
+```tsx
+<div {...dragHandlers} className="relative">
+  <DropZoneOverlay isDragging={isDragging} />
+  {/* your input */}
+</div>
+```
diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json
index 676d8ff..e019d96 100644
--- a/apps/docs/content/docs/meta.json
+++ b/apps/docs/content/docs/meta.json
@@ -20,7 +20,7 @@
     "customizations",
     "generative-ui",
     "headless",
-    "multimodal",
+    "attachments",
     "---AI---",
     "llm-sdk",
     "providers",
diff --git a/apps/docs/content/docs/overview.mdx b/apps/docs/content/docs/overview.mdx
index 99f45c1..9ba7712 100644
--- a/apps/docs/content/docs/overview.mdx
+++ b/apps/docs/content/docs/overview.mdx
@@ -81,7 +81,7 @@ AI calls `search_products({ query: "wireless headphones" })` → Shows results.
 | [**Generative UI**](/docs/generative-ui) | Render React components as tool results |
 | [**Smart AI Context**](/docs/smart-ai-context) | AI understands your app state |
 | [**Agentic Loop**](/docs/tools/agentic-loop) | Multi-step reasoning and tool chains |
-| [**Multimodal**](/docs/multimodal) | Images, PDFs, and files in chat |
+| [**Attachments**](/docs/attachments) | Images, PDFs, and files in chat |
 | [**4+ Providers**](/docs/providers) | OpenAI, Anthropic, Google, xAI... |
 | [**Backend Tools**](/docs/tools/backend-tools) | Secure backend tool execution |
 | [**Chat History**](/docs/chat-history) | Persist conversations across sessions |
diff --git a/apps/docs/content/docs/server/storage.mdx b/apps/docs/content/docs/server/storage.mdx
index 26df0d9..0590f9d 100644
--- a/apps/docs/content/docs/server/storage.mdx
+++ b/apps/docs/content/docs/server/storage.mdx
@@ -191,6 +191,33 @@ If `createSession` fails, the runtime:
 - Chat continues working normally (graceful degradation)
 - Error is logged once
 
+### Error Callback
+
+Register an `onError` handler to monitor all adapter operations:
+
+```ts
+const yourgpt = createYourGPT({
+  apiKey: process.env.YOURGPT_API_KEY,
+  widgetUid: process.env.YOURGPT_WIDGET_UID,
+  onError: (error, operation, params) => {
+    console.error(`[YourGPT:${operation}]`, error.message, params);
+    // Send to Sentry, Datadog, etc.
+    Sentry.captureException(error, {
+      tags: { operation },
+      extra: params,
+    });
+  },
+});
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `error` | `Error` | The error that occurred |
+| `operation` | `string` | `"createSession"` \| `"saveMessages"` \| `"uploadFile"` |
+| `params` | `object` | Context — varies by operation (sessionId, messageCount, filename, etc.) |
+
+The error is still re-thrown after `onError` runs, so the runtime's graceful degradation continues to work.
+
 ---
 
 ## File Uploads
@@ -213,7 +240,7 @@ Then on the client, use the `upload` prop:
 
 Files are uploaded to the server, which forwards them to the storage adapter. The returned URL is sent with the message instead of base64 data.
 
-See [Multimodal](/docs/multimodal) for more on file attachments.
+See [Attachments](/docs/attachments) for more on file attachments.
 
 ---
 
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index cc6c2de..9582997 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -226,6 +226,8 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       }
 
       // Create user message with parentId for correct tree placement
+      // Text file attachments (CSV, TXT, etc.) are kept as attachments for UI display.
+      // The optimizer inlines their content into the message text before sending to the LLM.
       const userMessage = createUserMessage(content, attachments, {
         parentId: newParentId,
       }) as T;
@@ -946,6 +948,51 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
   /**
    * Build the request payload
    */
+  /** Inline text-file attachments into message content for the LLM */
+  private inlineTextAttachments(messages: T[]): T[] {
+    const textMimeTypes = new Set([
+      "text/csv",
+      "text/plain",
+      "text/markdown",
+      "text/x-markdown",
+      "application/json",
+      "application/csv",
+    ]);
+    const textExts = new Set(["csv", "txt", "md", "json"]);
+
+    return messages.map((msg) => {
+      if (msg.role !== "user" || !msg.attachments?.length) return msg;
+
+      const textFiles: MessageAttachment[] = [];
+      const binaryFiles: MessageAttachment[] = [];
+
+      for (const att of msg.attachments) {
+        const ext = att.filename?.toLowerCase().split(".").pop();
+        const isText =
+          textMimeTypes.has(att.mimeType) || (ext && textExts.has(ext));
+        if (isText && att.data && !att.url) {
+          textFiles.push(att);
+        } else {
+          binaryFiles.push(att);
+        }
+      }
+
+      if (textFiles.length === 0) return msg;
+
+      // Inline text file contents into the message
+      const fileParts = textFiles.map((f) => {
+        const ext = f.filename?.split(".").pop()?.toLowerCase() || "txt";
+        return `\n\n--- ${f.filename || "file"} ---\n\`\`\`${ext}\n${f.data}\n\`\`\``;
+      });
+
+      return {
+        ...msg,
+        content: (msg.content || "") + fileParts.join(""),
+        attachments: binaryFiles.length > 0 ? binaryFiles : undefined,
+      };
+    });
+  }
+
   protected buildRequest() {
     const systemPrompt = this.dynamicContext
       ? `${this.config.systemPrompt || ""}\n\n## Current App Context:\n${this.dynamicContext}`.trim()
@@ -955,8 +1002,11 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
           this.state.messages as UIMessage[],
         ) as T[])
       : this.state.messages;
+
+    // Inline text-file attachments before optimization
+    const processedMessages = this.inlineTextAttachments(rawMessages);
     const optimized = this.optimizer.prepare({
-      messages: rawMessages,
+      messages: processedMessages,
       tools: this.config.tools,
       systemPrompt,
     });
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
index 484ea01..eacc9ee 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/default-message.tsx
@@ -457,38 +457,36 @@ export function DefaultMessage({
             </div>
           ) : (
             <>
-              {/* Combined media + text bubble (WhatsApp/Telegram style) */}
               <div className="relative">
-                {/* Images (if any) — in their own bubble */}
-                {hasAttachments && (
-                  <div
-                    className={cn(
-                      "csdk-message-media rounded-2xl overflow-hidden bg-primary p-[2px]",
-                      !message.content && "max-w-[260px]",
-                      message.content && "max-w-[280px] mb-[3px]",
-                      userMessageClassName,
-                    )}
-                  >
+                <div
+                  className={cn(
+                    "csdk-message-user rounded-2xl overflow-hidden bg-primary text-primary-foreground",
+                    hasAttachments && "p-[3px]",
+                    hasAttachments && !message.content && "max-w-[260px]",
+                    hasAttachments && message.content && "max-w-[280px]",
+                    !hasAttachments && "",
+                    userMessageClassName,
+                  )}
+                >
+                  {/* Media (images + files) */}
+                  {hasAttachments && (
                     <MessageMedia
                       attachments={message.attachments!}
                       hasText={!!message.content}
                       align="end"
                     />
-                  </div>
-                )}
-                {/* Text content — same style as original, padding on MessageContent */}
-                {message.content && (
-                  <MessageContent
-                    className={cn(
-                      "csdk-message-user rounded-2xl px-4 py-2 bg-primary text-primary-foreground",
-                      userMessageClassName,
-                    )}
-                    markdown
-                    size={size}
-                  >
-                    {message.content}
-                  </MessageContent>
-                )}
+                  )}
+                  {/* Text — px-4 py-2 passed to MessageContent, tailwind-merge overrides its internal p-2 */}
+                  {message.content && (
+                    <MessageContent
+                      className={cn("px-4 py-2")}
+                      markdown
+                      size={size}
+                    >
+                      {message.content}
+                    </MessageContent>
+                  )}
+                </div>
                 {/* Edit button — hover reveal */}
                 {showEditBtn && (
                   <button
@@ -1128,101 +1126,128 @@ function ImageThumb({
 }
 
 /**
- * File attachment card — compact, non-image files
+ * File attachment card — inline within message bubble.
+ * Compact row: colored icon + filename + download/open button.
+ * Styled to sit inside the bubble bg (slightly darker inner card).
+ *
+ * PDF gets red accent, audio green, video purple, generic blue.
  */
 function FileCard({ attachment }: { attachment: MessageAttachment }) {
-  const iconType =
-    attachment.type === "audio"
-      ? "audio"
-      : attachment.type === "video"
-        ? "video"
-        : "file";
-  const colors = {
-    audio: "text-emerald-500 bg-emerald-500/10",
-    video: "text-purple-500 bg-purple-500/10",
-    file: "text-blue-500 bg-blue-500/10",
-  };
-  const icons = {
-    audio: (
-      <path d="M9 18V5l12-2v13M6 18a3 3 0 1 0 0-6 3 3 0 0 0 0 6ZM18 16a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z" />
-    ),
-    video: (
-      <>
-        <path d="m16 13 5.223 3.482a.5.5 0 0 0 .777-.416V7.934a.5.5 0 0 0-.777-.416L16 11" />
-        <rect width="14" height="12" x="2" y="6" rx="2" />
-      </>
-    ),
-    file: (
-      <>
-        <path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z" />
-        <path d="M14 2v4a2 2 0 0 0 2 2h4" />
-      </>
-    ),
-  };
-
+  const isPdfFile = isPdf(attachment);
+  const isAudio = attachment.type === "audio";
+  const isVideo = attachment.type === "video";
+
+  // Accent colors per type
+  const accent = isPdfFile
+    ? { color: "#ef4444", bg: "rgba(239,68,68,0.12)" }
+    : isAudio
+      ? { color: "#10b981", bg: "rgba(16,185,129,0.12)" }
+      : isVideo
+        ? { color: "#8b5cf6", bg: "rgba(139,92,246,0.12)" }
+        : { color: "#3b82f6", bg: "rgba(59,130,246,0.12)" };
+
+  const label = isPdfFile
+    ? "PDF"
+    : attachment.mimeType?.split("/")[1]?.toUpperCase() ||
+      attachment.type?.toUpperCase() ||
+      "FILE";
+  const filename = attachment.filename || "Attachment";
   const href =
     attachment.url ||
     (attachment.data?.startsWith("data:") ? attachment.data : null);
+  const cssClass = isPdfFile ? "csdk-attachment-pdf" : "csdk-attachment-file";
 
   return (
-    <div
+    <a
+      href={href ?? undefined}
+      target="_blank"
+      rel="noopener noreferrer"
+      download={isPdfFile ? undefined : attachment.filename}
       className={cn(
-        "csdk-attachment-file flex items-center gap-2 rounded-lg border border-border/50 bg-muted/30 px-2.5 py-2 min-w-0 max-w-full",
+        cssClass,
+        "flex items-center gap-2 rounded-lg min-w-0 w-full",
+        "px-2 py-1.5 cursor-pointer transition-opacity duration-150 hover:opacity-80",
+        "no-underline",
       )}
+      style={{ backgroundColor: "rgba(255,255,255,0.92)", color: "#1a1a1a" }}
+      onClick={(e) => {
+        if (!href) e.preventDefault();
+      }}
     >
+      {/* Icon */}
       <div
-        className={cn(
-          "size-8 rounded-md flex items-center justify-center shrink-0",
-          colors[iconType],
-        )}
+        className="size-8 rounded-md flex items-center justify-center shrink-0"
+        style={{ backgroundColor: accent.bg }}
       >
         <svg
           className="size-4"
           viewBox="0 0 24 24"
           fill="none"
-          stroke="currentColor"
-          strokeWidth={2}
+          stroke={accent.color}
+          strokeWidth={1.8}
           strokeLinecap="round"
           strokeLinejoin="round"
         >
-          {icons[iconType]}
+          {isPdfFile || (!isAudio && !isVideo) ? (
+            <>
+              <path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z" />
+              <path d="M14 2v4a2 2 0 0 0 2 2h4" />
+            </>
+          ) : isAudio ? (
+            <>
+              <path d="M9 18V5l12-2v13" />
+              <circle cx="6" cy="18" r="3" />
+              <circle cx="18" cy="16" r="3" />
+            </>
+          ) : (
+            <>
+              <path d="m16 13 5.223 3.482a.5.5 0 0 0 .777-.416V7.934a.5.5 0 0 0-.777-.416L16 11" />
+              <rect width="14" height="12" x="2" y="6" rx="2" />
+            </>
+          )}
         </svg>
       </div>
+      {/* Name + type */}
       <div className="min-w-0 flex-1">
-        <p className="text-xs font-medium truncate">
-          {attachment.filename || "Attachment"}
+        <p className="text-[11px] font-medium truncate leading-tight">
+          {filename}
         </p>
-        <p className="text-[10px] text-muted-foreground uppercase">
-          {attachment.mimeType?.split("/")[1] || attachment.type}
+        <p
+          className="text-[9px] font-semibold uppercase tracking-wider leading-tight mt-0.5"
+          style={{ color: accent.color }}
+        >
+          {label}
         </p>
       </div>
+      {/* Download / open icon */}
       {href && (
-        <a
-          href={href}
-          target="_blank"
-          rel="noopener noreferrer"
-          download={attachment.filename}
-          className="shrink-0 text-muted-foreground/50 hover:text-foreground transition-colors"
+        <div
+          className="size-6 rounded-md flex items-center justify-center shrink-0"
+          style={{ backgroundColor: "rgba(0,0,0,0.05)" }}
         >
           <svg
-            className="size-3.5"
+            className="size-3"
             viewBox="0 0 24 24"
             fill="none"
             stroke="currentColor"
-            strokeWidth={2}
+            strokeWidth={2.5}
             strokeLinecap="round"
             strokeLinejoin="round"
+            style={{ opacity: 0.35 }}
           >
             <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
             <polyline points="7 10 12 15 17 10" />
             <line x1="12" x2="12" y1="15" y2="3" />
           </svg>
-        </a>
+        </div>
       )}
-    </div>
+    </a>
   );
 }
 
+/** @deprecated Use FileCard which now handles all types including PDF */
+const PdfCard = FileCard;
+
 /**
  * Image grid — WhatsApp/Telegram-style layout
  * 1 image: full width
@@ -1340,6 +1365,13 @@ function ImageGrid({
  * - Images at top of bubble (no padding), text below with padding
  * - Files shown as compact cards below text
  */
+function isPdf(a: MessageAttachment): boolean {
+  return (
+    a.mimeType === "application/pdf" ||
+    a.filename?.toLowerCase().endsWith(".pdf") === true
+  );
+}
+
 function MessageMedia({
   attachments,
   hasText,
@@ -1350,7 +1382,8 @@ function MessageMedia({
   align?: "start" | "end";
 }) {
   const images = attachments.filter((a) => a.type === "image");
-  const files = attachments.filter((a) => a.type !== "image");
+  const pdfs = attachments.filter((a) => isPdf(a));
+  const files = attachments.filter((a) => a.type !== "image" && !isPdf(a));
 
   return (
     <>
@@ -1359,15 +1392,14 @@ function MessageMedia({
           <ImageGrid images={images} bubbleRadius="0.5rem" />
         </div>
       )}
-      {files.length > 0 && (
+      {(pdfs.length > 0 || files.length > 0) && (
         <div
           className={cn(
             "csdk-attachment-files flex flex-col gap-1",
-            hasText || images.length > 0 ? "px-3 pb-2 pt-1" : "p-1.5",
-            align === "end" ? "items-end" : "items-start",
+            hasText || images.length > 0 ? "px-1.5 pb-1.5 pt-1" : "p-1.5",
           )}
         >
-          {files.map((file, i) => (
+          {[...pdfs, ...files].map((file, i) => (
             <FileCard key={i} attachment={file} />
           ))}
         </div>
diff --git a/packages/copilot-sdk/src/ui/hooks/useAttachments.ts b/packages/copilot-sdk/src/ui/hooks/useAttachments.ts
index 7a3aed8..b43e6d5 100644
--- a/packages/copilot-sdk/src/ui/hooks/useAttachments.ts
+++ b/packages/copilot-sdk/src/ui/hooks/useAttachments.ts
@@ -95,7 +95,43 @@ export interface UseAttachmentsReturn {
 
 const DEFAULT_MAX_FILES = 5;
 const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
-const DEFAULT_ALLOWED_TYPES = ["image/*", "application/pdf"];
+const DEFAULT_ALLOWED_TYPES = [
+  "image/*",
+  "application/pdf",
+  "text/csv",
+  "text/plain",
+  "text/markdown",
+  "application/json",
+  ".csv",
+  ".txt",
+  ".md",
+  ".json",
+];
+
+/** MIME types that are text-based — read as text, no upload needed */
+const TEXT_MIME_TYPES = new Set([
+  "text/csv",
+  "text/plain",
+  "text/markdown",
+  "text/x-markdown",
+  "application/json",
+  "application/csv",
+]);
+
+function isTextFile(file: File): boolean {
+  if (TEXT_MIME_TYPES.has(file.type)) return true;
+  const ext = file.name.toLowerCase().split(".").pop();
+  return ext === "csv" || ext === "txt" || ext === "md" || ext === "json";
+}
+
+function readFileAsText(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string);
+    reader.onerror = () => reject(new Error("Failed to read file"));
+    reader.readAsText(file);
+  });
+}
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
@@ -189,6 +225,20 @@ export function useAttachments(
 
         let result: MessageAttachment;
 
+        // Text files: read content locally, no upload needed
+        if (isTextFile(file)) {
+          updateProgress(50);
+          const textContent = await readFileAsText(file);
+          result = {
+            type: "file",
+            data: textContent,
+            mimeType: file.type || "text/plain",
+            filename: file.name,
+          };
+          markReady(result);
+          return;
+        }
+
         if (typeof upload === "function") {
           // Custom function — no progress tracking (user handles it)
           updateProgress(50);
diff --git a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
index d8e1475..41ddcfc 100644
--- a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
+++ b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
@@ -305,6 +305,14 @@ export function useInternalThreadManager(
     // Use the SDK's threadId (server session ID) as the local thread ID when available
     // so both systems share the same ID — no mapping layer needed.
     if (!currentThreadId && !savingToThreadRef.current) {
+      // If the SDK is expected to have a threadId from the server but doesn't yet
+      // (React state batching delay), skip this render — it'll fire again when
+      // sdkThreadId updates. This prevents creating a local thread_xxx that
+      // conflicts with the server session ID.
+      if (!sdkThreadId && status === "ready" && messages.length <= 2) {
+        // First message just completed — sdkThreadId may arrive next render
+        return;
+      }
       // Set ref immediately to prevent race condition with rapid messages
       savingToThreadRef.current = "creating";
       // Mark as initialized so auto-restore doesn't fire when createThread
diff --git a/packages/llm-sdk/src/core/types.ts b/packages/llm-sdk/src/core/types.ts
index 599fcc9..ae9dad7 100644
--- a/packages/llm-sdk/src/core/types.ts
+++ b/packages/llm-sdk/src/core/types.ts
@@ -426,6 +426,10 @@ export interface StorageMessage {
   content: string;
   toolCalls?: unknown[];
   toolCallId?: string;
+  /** Content type for the message — determines how it's stored in the backend */
+  contentType?: "text" | "image" | "file";
+  /** URL for image/file attachments */
+  url?: string;
   metadata?: Record<string, unknown>;
 }
 
diff --git a/packages/llm-sdk/src/server/storage-helpers.ts b/packages/llm-sdk/src/server/storage-helpers.ts
index b181077..37a533b 100644
--- a/packages/llm-sdk/src/server/storage-helpers.ts
+++ b/packages/llm-sdk/src/server/storage-helpers.ts
@@ -33,15 +33,29 @@ export function extractInputMessages(reqMessages: unknown[]): StorageMessage[] {
   if (!lastMeaningful) return [];
 
   if (lastMeaningful.role === "user") {
-    return [
-      {
-        role: "user",
-        content:
-          typeof lastMeaningful.content === "string"
-            ? lastMeaningful.content
-            : JSON.stringify(lastMeaningful.content),
-      },
-    ];
+    const textContent =
+      typeof lastMeaningful.content === "string"
+        ? lastMeaningful.content
+        : JSON.stringify(lastMeaningful.content);
+
+    const attachments = lastMeaningful.attachments as
+      | Array<{ type?: string; url?: string; filename?: string }>
+      | undefined;
+    const imageAtt = attachments?.find((a) => a.type === "image" && a.url);
+    const fileAtt = attachments?.find((a) => a.type === "file" && a.url);
+
+    // Single message — text + attachment info combined
+    const msg: StorageMessage = { role: "user", content: textContent || "" };
+
+    if (imageAtt?.url) {
+      msg.contentType = "image";
+      msg.url = imageAtt.url;
+    } else if (fileAtt?.url) {
+      msg.contentType = "file";
+      msg.url = fileAtt.url;
+    }
+
+    return [msg];
   }
 
   if (lastMeaningful.role === "tool" || lastMeaningful.role === "function") {
diff --git a/packages/llm-sdk/src/yourgpt/index.ts b/packages/llm-sdk/src/yourgpt/index.ts
index 4461272..3b5e327 100644
--- a/packages/llm-sdk/src/yourgpt/index.ts
+++ b/packages/llm-sdk/src/yourgpt/index.ts
@@ -32,6 +32,24 @@ export interface YourGPTConfig {
   widgetUid: string;
   /** Override API base URL. Defaults to https://api.yourgpt.ai */
   endpoint?: string;
+  /**
+   * Error handler — called when any adapter operation fails.
+   * Receives the error and the operation name (createSession, saveMessages, uploadFile).
+   * If not provided, errors are thrown to the caller.
+   *
+   * @example
+   * ```ts
+   * onError: (error, operation, params) => {
+   *   logger.error(`[YourGPT] ${operation} failed:`, error, params);
+   *   Sentry.captureException(error, { tags: { operation }, extra: params });
+   * }
+   * ```
+   */
+  onError?: (
+    error: Error,
+    operation: string,
+    params?: Record<string, unknown>,
+  ) => void;
 }
 
 /** @deprecated Use `YourGPTConfig` instead */
@@ -78,6 +96,7 @@ export function createYourGPT(config: YourGPTConfig): YourGPT {
     "Content-Type": "application/json",
     "api-key": config.apiKey,
   };
+  const onError = config.onError;
 
   async function call<T = unknown>(
     path: string,
@@ -96,108 +115,183 @@ export function createYourGPT(config: YourGPTConfig): YourGPT {
     return res.json() as Promise<T>;
   }
 
+  /** Wrap an operation with onError handler + param logging */
+  async function safe<T>(
+    operation: string,
+    params: Record<string, unknown>,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    try {
+      return await fn();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (onError) {
+        onError(error, operation, params);
+      }
+      throw error;
+    }
+  }
+
   return {
     async createSession(data = {}) {
-      const raw = await call<any>(
-        "/chatbot/v1/copilot-sdk/createSession",
-        data,
-      );
-      const d = raw.data ?? raw;
-      return {
-        id: String(d.session_uid ?? d.id),
-        title: d.title ?? undefined,
-        createdAt: new Date(d.createdAt ?? d.created_at),
-        updatedAt: new Date(d.updatedAt ?? d.updated_at),
-      };
+      return safe("createSession", { title: data.title }, async () => {
+        const raw = await call<any>(
+          "/chatbot/v1/copilot-sdk/createSession",
+          data,
+        );
+        const d = raw.data ?? raw;
+        return {
+          id: String(d.session_uid ?? d.id),
+          title: d.title ?? undefined,
+          createdAt: new Date(d.createdAt ?? d.created_at),
+          updatedAt: new Date(d.updatedAt ?? d.updated_at),
+        };
+      });
     },
 
     async saveMessages(sessionId, messages) {
-      // Keep as string if too large for JS safe integer (avoids precision loss)
-      const num = Number(sessionId);
-      const sessionUid = Number.isSafeInteger(num) ? num : sessionId;
-
-      // Build a lookup: tool_call_id → tool result content (for merging dispatch + result)
-      const toolResults = new Map<string, string>();
-      for (const msg of messages) {
-        if (msg.role === "tool" && msg.toolCallId) {
-          toolResults.set(msg.toolCallId, msg.content ?? "");
-        }
-      }
+      return safe(
+        "saveMessages",
+        {
+          sessionId,
+          messageCount: messages.length,
+          roles: messages.map((m) => m.role),
+        },
+        async () => {
+          // Keep as string if too large for JS safe integer (avoids precision loss)
+          const num = Number(sessionId);
+          const sessionUid = Number.isSafeInteger(num) ? num : sessionId;
 
-      for (const msg of messages) {
-        if (msg.role === "tool") {
-          // Tool results are merged into the dispatch record below — skip standalone save
-          continue;
-        } else if (msg.role === "assistant" && msg.toolCalls?.length) {
-          // Assistant dispatching tool calls — one completed record per call (cold storage)
-          for (const tc of msg.toolCalls as Array<{
-            id?: string;
-            function?: { name?: string; arguments?: string };
-          }>) {
-            const toolName = tc.function?.name ?? "unknown";
-            let toolArgs: unknown = {};
-            try {
-              toolArgs =
-                typeof tc.function?.arguments === "string"
-                  ? JSON.parse(tc.function.arguments)
-                  : (tc.function?.arguments ?? {});
-            } catch {
-              /* leave as empty object */
+          // Build a lookup: tool_call_id → tool result content (for merging dispatch + result)
+          const toolResults = new Map<string, string>();
+          for (const msg of messages) {
+            if (msg.role === "tool" && msg.toolCallId) {
+              toolResults.set(msg.toolCallId, msg.content ?? "");
             }
-
-            // Merge: find matching tool result by call ID
-            const response = tc.id ? (toolResults.get(tc.id) ?? null) : null;
-
-            await call("/chatbot/v1/copilot-sdk/createToolMessage", {
-              session_uid: sessionUid,
-              skill: "copilot-tool",
-              extra_data: {
-                tool_name: toolName,
-                tool_arguments: toolArgs,
-                tool_call_id: tc.id ?? null,
-                status: "completed",
-                tool_response: response,
-              },
-            });
           }
 
-          // Also save the assistant text content if present alongside tool calls
-          if (msg.content) {
-            await call("/chatbot/v1/copilot-sdk/createMessage", {
-              session_uid: sessionUid,
-              message: msg.content,
-              send_by: "assistant",
-            });
+          for (const msg of messages) {
+            if (msg.role === "tool") {
+              // Tool results are merged into the dispatch record below — skip standalone save
+              continue;
+            } else if (msg.role === "assistant" && msg.toolCalls?.length) {
+              // Save assistant text FIRST (before tool calls) to preserve display order
+              if (msg.content) {
+                await call("/chatbot/v1/copilot-sdk/createMessage", {
+                  session_uid: sessionUid,
+                  message: msg.content,
+                  send_by: "assistant",
+                  content_type: "text",
+                });
+              }
+
+              // Then save tool calls — one completed record per call (cold storage)
+              for (const tc of msg.toolCalls as Array<{
+                id?: string;
+                function?: { name?: string; arguments?: string };
+              }>) {
+                const toolName = tc.function?.name ?? "unknown";
+                let toolArgs: unknown = {};
+                try {
+                  toolArgs =
+                    typeof tc.function?.arguments === "string"
+                      ? JSON.parse(tc.function.arguments)
+                      : (tc.function?.arguments ?? {});
+                } catch {
+                  /* leave as empty object */
+                }
+
+                // Merge: find matching tool result by call ID
+                const response = tc.id
+                  ? (toolResults.get(tc.id) ?? null)
+                  : null;
+
+                await call("/chatbot/v1/copilot-sdk/createToolMessage", {
+                  session_uid: sessionUid,
+                  skill: "copilot-tool",
+                  extra_data: {
+                    tool_name: toolName,
+                    tool_arguments: toolArgs,
+                    tool_call_id: tc.id ?? null,
+                    status: "completed",
+                    tool_response: response,
+                  },
+                });
+              }
+            } else if (msg.role === "user" || msg.role === "assistant") {
+              // Regular user / assistant message — include content_type + url if present
+              await call("/chatbot/v1/copilot-sdk/createMessage", {
+                session_uid: sessionUid,
+                message: msg.content,
+                send_by: msg.role === "user" ? "user" : "assistant",
+                content_type: msg.contentType || "text",
+                ...(msg.url ? { url: msg.url } : {}),
+              });
+            }
+            // system messages are skipped — not stored
           }
-        } else if (msg.role === "user" || msg.role === "assistant") {
-          // Regular user / assistant message
-          await call("/chatbot/v1/copilot-sdk/createMessage", {
-            session_uid: sessionUid,
-            message: msg.content,
-            send_by: msg.role === "user" ? "user" : "assistant",
-          });
-        }
-        // system messages are skipped — not stored
-      }
+        },
+      );
     },
 
     async uploadFile(file: StorageFile) {
-      // Strip data URI prefix if present (e.g., "data:image/png;base64,...")
-      let rawData = file.data;
-      const dataUriMatch = rawData.match(/^data:[^;]+;base64,(.+)$/);
-      if (dataUriMatch) rawData = dataUriMatch[1];
-
-      const raw = await call<any>("/chatbot/v1/copilot-sdk/uploadMedia", {
-        file_data: rawData,
-        mime_type: file.mimeType,
-        filename: file.filename,
-      });
-      const url = raw.data?.url ?? raw.url;
-      if (!url)
-        throw new Error(
-          "uploadFile failed: no URL in response — " + JSON.stringify(raw),
-        );
-      return { url };
+      return safe(
+        "uploadFile",
+        {
+          filename: file.filename,
+          mimeType: file.mimeType,
+          dataLength: file.data?.length,
+        },
+        async () => {
+          // Step 1: Get pre-signed upload URL from YourGPT
+          const raw = await call<any>("/chatbot/v1/copilot-sdk/getSignedUrl", {
+            file_name: file.filename || `upload_${Date.now()}`,
+          });
+          const signedUrl = raw.data?.upload_url ?? raw.data?.url ?? raw.url;
+          const successUrl =
+            raw.data?.file_url ?? raw.data?.success_url ?? raw.success_url;
+          if (!signedUrl) {
+            throw new Error(
+              "uploadFile: no signed URL in response — " + JSON.stringify(raw),
+            );
+          }
+
+          // Step 2: Upload file directly to cloud storage via signed URL
+          let body: Blob | Buffer;
+          let rawData = file.data;
+          // Strip data URI prefix if present
+          const dataUriMatch = rawData.match(/^data:[^;]+;base64,(.+)$/);
+          if (dataUriMatch) rawData = dataUriMatch[1];
+
+          if (typeof Buffer !== "undefined") {
+            // Node.js
+            body = Buffer.from(rawData, "base64");
+          } else {
+            // Browser
+            const binary = atob(rawData);
+            const bytes = new Uint8Array(binary.length);
+            for (let i = 0; i < binary.length; i++)
+              bytes[i] = binary.charCodeAt(i);
+            body = new Blob([bytes], { type: file.mimeType });
+          }
+
+          const uploadRes = await fetch(signedUrl, {
+            method: "PUT",
+            headers: { "Content-Type": file.mimeType },
+            body,
+          });
+
+          if (!uploadRes.ok) {
+            throw new Error(
+              `uploadFile: PUT to signed URL failed with ${uploadRes.status}`,
+            );
+          }
+
+          // Step 3: Return the CDN/success URL
+          const finalUrl = successUrl || signedUrl.split("?")[0];
+          return { url: finalUrl };
+        },
+      );
     },
   };
 }

From 01bfdadd61a77284bd9d7c5d35a790df0d74cb8a Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Thu, 26 Mar 2026 14:00:11 +0530
Subject: [PATCH 53/72] chore: bump package versions for copilot-sdk and
 llm-sdk

- Updated @yourgpt/copilot-sdk to version 2.1.5-alpha.6.
- Updated @yourgpt/llm-sdk to version 2.1.4-alpha.2.
---
 packages/copilot-sdk/package.json | 2 +-
 packages/llm-sdk/package.json     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index a444c4e..f45c929 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.5-alpha.5",
+  "version": "2.1.5-alpha.6",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",
diff --git a/packages/llm-sdk/package.json b/packages/llm-sdk/package.json
index d75934d..5a914f6 100644
--- a/packages/llm-sdk/package.json
+++ b/packages/llm-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/llm-sdk",
-  "version": "2.1.4-alpha.1",
+  "version": "2.1.4-alpha.2",
   "description": "AI SDK for building AI Agents with any LLM",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

From 4dd665c802c39d579550aa8d084b8e2be273e3dc Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Fri, 27 Mar 2026 13:36:27 +0530
Subject: [PATCH 54/72] feat(localStorage): enhance localStorage availability
 check and integrate custom adapter

- Improved localStorage availability check by caching the result to avoid repeated checks.
- Updated `connected-chat` component to support a custom localStorage key for isolating thread storage.
- Introduced memoization for the localStorage adapter to prevent unnecessary re-renders.
- Enhanced `useInternalThreadManager` to manage local-only threads alongside server-managed sessions.
---
 .../thread/adapters/localStorageAdapter.ts    |  12 +-
 .../ui/components/composed/connected-chat.tsx |  30 +-
 .../src/ui/hooks/useInternalThreadManager.ts  | 562 ++++++++++--------
 3 files changed, 348 insertions(+), 256 deletions(-)

diff --git a/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts b/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
index f6ea36c..1515d5a 100644
--- a/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
+++ b/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
@@ -70,15 +70,17 @@ export interface LocalStorageAdapterConfig {
 /**
  * Check if localStorage is available (SSR-safe)
  */
+let _localStorageAvailable: boolean | null = null;
 function isLocalStorageAvailable(): boolean {
-  if (typeof window === "undefined") return false;
+  if (_localStorageAvailable !== null) return _localStorageAvailable;
+  if (typeof window === "undefined") return (_localStorageAvailable = false);
   try {
-    const testKey = "__copilot_test__";
-    window.localStorage.setItem(testKey, testKey);
+    const testKey = "__copilot_ls_check__";
+    window.localStorage.setItem(testKey, "1");
     window.localStorage.removeItem(testKey);
-    return true;
+    return (_localStorageAvailable = true);
   } catch {
-    return false;
+    return (_localStorageAvailable = false);
   }
 }
 
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index 7ec5760..3e42ff9 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import React from "react";
+import React, { useMemo } from "react";
 import {
   useCopilot,
   type UIMessage,
@@ -17,7 +17,10 @@ import type {
   ThreadStorageAdapter,
   AsyncThreadStorageAdapter,
 } from "../../../thread/adapters";
-import { createServerAdapter } from "../../../thread/adapters";
+import {
+  createServerAdapter,
+  createLocalStorageAdapter,
+} from "../../../thread/adapters";
 
 // ============================================
 // Persistence Configuration Types
@@ -28,6 +31,9 @@ import { createServerAdapter } from "../../../thread/adapters";
  */
 export interface LocalPersistenceConfig {
   type: "local";
+  /** Custom localStorage key to isolate thread storage between copilot instances.
+   *  Default: "copilot-sdk-store" */
+  localStorageKey?: string;
   /** Debounce delay for auto-save (ms). Default: 1000 */
   saveDebounce?: number;
   /** Whether to auto-restore the last active thread. Default: true */
@@ -311,8 +317,28 @@ function CopilotChatBase(
     ...chatProps
   } = props;
 
+  // Create custom adapter once for localStorageKey (stable reference to avoid render loops)
+  const localStorageKey =
+    typeof persistence === "object" &&
+    "type" in persistence &&
+    persistence.type === "local"
+      ? persistence.localStorageKey
+      : undefined;
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const customAdapter = useMemo(
+    () =>
+      localStorageKey
+        ? createLocalStorageAdapter({ storageKey: localStorageKey })
+        : undefined,
+    [localStorageKey],
+  );
+
   // Parse persistence config
   const persistenceConfig = parsePersistenceConfig(persistence, onThreadChange);
+  // Inject memoized adapter if localStorageKey was provided
+  if (persistenceConfig && customAdapter) {
+    persistenceConfig.adapter = customAdapter;
+  }
 
   // Use internal thread manager when persistence is enabled.
   // When persistence is disabled, pass enabled:false so no sync/restore effects
diff --git a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
index 41ddcfc..ece89e7 100644
--- a/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
+++ b/packages/copilot-sdk/src/ui/hooks/useInternalThreadManager.ts
@@ -3,17 +3,16 @@
 /**
  * useInternalThreadManager - Internal hook for CopilotChat persistence
  *
- * Encapsulates all thread management logic:
- * - Message format conversion (UIMessage ↔ Message)
- * - Auto-save on streaming complete
- * - Auto-restore last thread on mount
- * - Thread switch/create handlers
- * - Refs to prevent duplicate saves
+ * Uses a reducer-based state machine with clear phases:
+ *   idle → awaiting_server_id → creating → active
+ *   active → switching → active
+ *   active → idle (new thread)
  *
- * This is an internal hook used by CopilotChat when persistence is enabled.
+ * Handles both server-managed sessions (threadId from response) and
+ * local-only threads (no server storage) with the same flow.
  */
 
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useReducer, useRef } from "react";
 import { useCopilot, type UIMessage } from "../../react";
 import {
   useThreadManager,
@@ -24,41 +23,180 @@ import type {
   AsyncThreadStorageAdapter,
 } from "../../thread/adapters";
 
+// ── Config & Return types ────────────────────────────────────────────────────
+
 export interface UseInternalThreadManagerConfig {
-  /** Storage adapter for persistence */
   adapter?: ThreadStorageAdapter | AsyncThreadStorageAdapter;
-  /** Debounce delay for auto-save (ms) */
   saveDebounce?: number;
-  /** Whether to auto-restore the last active thread */
   autoRestoreLastThread?: boolean;
-  /** Callback when thread changes */
   onThreadChange?: (threadId: string | null) => void;
-  /**
-   * Whether thread management is active.
-   * When false, all sync/restore effects are skipped.
-   * Used by CopilotChat when persistence is disabled to avoid touching the shared singleton.
-   * @default true
-   */
   enabled?: boolean;
 }
 
 export interface UseInternalThreadManagerReturn {
-  /** Thread manager state and actions */
   threadManager: ReturnType<typeof useThreadManager>;
-  /** Handler for switching threads */
   handleSwitchThread: (threadId: string) => Promise<void>;
-  /** Handler for creating new threads */
   handleNewThread: () => Promise<void>;
-  /** Whether thread operations should be disabled (during streaming) */
   isBusy: boolean;
 }
 
-/**
- * Internal thread manager hook for CopilotChat
- *
- * This hook manages the synchronization between CopilotProvider's messages
- * and the thread storage system.
- */
+// ── State machine ────────────────────────────────────────────────────────────
+
+type Phase =
+  | "idle" // No thread, waiting for first message
+  | "awaiting_server_id" // First response complete, waiting for sdkThreadId
+  | "creating" // Creating local thread
+  | "active" // Thread active, syncing messages
+  | "switching" // Switching to a different thread
+  | "restoring"; // Auto-restoring last thread on mount
+
+interface ThreadSyncState {
+  phase: Phase;
+  threadId: string | null; // Active local thread ID
+  lastSnapshot: string; // Last saved message snapshot
+  initialized: boolean; // Whether initial restore has run
+}
+
+type ThreadAction =
+  | { type: "FIRST_RESPONSE_COMPLETE" }
+  | { type: "SERVER_ID_RECEIVED"; threadId: string }
+  | { type: "CREATE_WITH_LOCAL_ID" }
+  | { type: "THREAD_CREATED"; threadId: string; snapshot: string }
+  | { type: "MESSAGES_SAVED"; snapshot: string }
+  | { type: "START_SWITCH" }
+  | { type: "SWITCH_COMPLETE"; threadId: string; snapshot: string }
+  | { type: "NEW_THREAD" }
+  | { type: "RESTORE_START" }
+  | { type: "RESTORE_COMPLETE"; threadId: string; snapshot: string }
+  | { type: "SKIP_RESTORE" };
+
+const INITIAL_STATE: ThreadSyncState = {
+  phase: "idle",
+  threadId: null,
+  lastSnapshot: "",
+  initialized: false,
+};
+
+function threadReducer(
+  state: ThreadSyncState,
+  action: ThreadAction,
+): ThreadSyncState {
+  switch (action.type) {
+    case "FIRST_RESPONSE_COMPLETE":
+      if (state.phase !== "idle") return state;
+      // Mark initialized so auto-restore doesn't interfere when
+      // createThread() later updates currentThread in the manager.
+      return { ...state, phase: "awaiting_server_id", initialized: true };
+
+    case "SERVER_ID_RECEIVED":
+      if (state.phase !== "awaiting_server_id") return state;
+      return { ...state, phase: "creating" };
+
+    case "CREATE_WITH_LOCAL_ID":
+      if (state.phase !== "awaiting_server_id") return state;
+      return { ...state, phase: "creating" };
+
+    case "THREAD_CREATED":
+      return {
+        ...state,
+        phase: "active",
+        threadId: action.threadId,
+        lastSnapshot: action.snapshot,
+        initialized: true,
+      };
+
+    case "MESSAGES_SAVED":
+      if (state.phase !== "active") return state;
+      return { ...state, lastSnapshot: action.snapshot };
+
+    case "START_SWITCH":
+      if (state.phase !== "active" && state.phase !== "idle") return state;
+      return { ...state, phase: "switching" };
+
+    case "SWITCH_COMPLETE":
+      return {
+        ...state,
+        phase: "active",
+        threadId: action.threadId,
+        lastSnapshot: action.snapshot,
+      };
+
+    case "NEW_THREAD":
+      return {
+        ...INITIAL_STATE,
+        initialized: true,
+      };
+
+    case "RESTORE_START":
+      if (state.initialized) return state;
+      if (state.phase === "creating" || state.phase === "awaiting_server_id")
+        return state;
+      return { ...state, phase: "restoring" };
+
+    case "RESTORE_COMPLETE":
+      return {
+        ...state,
+        phase: "active",
+        threadId: action.threadId,
+        lastSnapshot: action.snapshot,
+        initialized: true,
+      };
+
+    case "SKIP_RESTORE":
+      return { ...state, initialized: true };
+
+    default:
+      return state;
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function getMessageSnapshot(msgs: UIMessage[]): string {
+  return msgs
+    .map((m) => {
+      const preview = (m.content ?? "").slice(0, 20);
+      return `${m.id}:${preview}:${m.content?.length ?? 0}`;
+    })
+    .join("|");
+}
+
+function convertToCore(msgs: UIMessage[]) {
+  return msgs.map((m) => ({
+    id: m.id,
+    role: m.role,
+    content: m.content,
+    created_at: m.createdAt,
+    tool_calls: m.toolCalls,
+    tool_call_id: m.toolCallId,
+    parent_id: m.parentId,
+    children_ids: m.childrenIds,
+    metadata: {
+      ...m.metadata,
+      attachments: m.attachments,
+      thinking: m.thinking,
+    },
+  }));
+}
+
+function coreToUI(m: any): UIMessage {
+  return {
+    id: m.id,
+    role: m.role,
+    content: m.content ?? "",
+    createdAt: m.created_at ?? new Date(),
+    toolCalls: m.tool_calls,
+    toolCallId: m.tool_call_id,
+    parentId: m.parent_id,
+    childrenIds: m.children_ids,
+    attachments: m.metadata?.attachments,
+    thinking: m.metadata?.thinking as string | undefined,
+    metadata: m.metadata,
+  };
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
 export function useInternalThreadManager(
   config: UseInternalThreadManagerConfig = {},
 ): UseInternalThreadManagerReturn {
@@ -70,14 +208,15 @@ export function useInternalThreadManager(
     enabled = true,
   } = config;
 
-  // Thread management
-  const threadManagerConfig: UseThreadManagerConfig = {
+  const [state, dispatch] = useReducer(threadReducer, INITIAL_STATE);
+  const isLoadingRef = useRef(false);
+
+  // Thread manager (handles localStorage / server adapter)
+  const threadManager = useThreadManager({
     adapter,
     saveDebounce,
     autoRestoreLastThread,
-  };
-
-  const threadManager = useThreadManager(threadManagerConfig);
+  });
   const {
     currentThread,
     currentThreadId,
@@ -85,10 +224,9 @@ export function useInternalThreadManager(
     switchThread,
     updateCurrentThread,
     clearCurrentThread,
-    refreshThreads,
   } = threadManager;
 
-  // Get copilot context for setMessages and status
+  // Copilot context
   const {
     messages,
     setMessages,
@@ -97,266 +235,192 @@ export function useInternalThreadManager(
     getAllMessages,
     switchBranch,
     threadId: sdkThreadId,
+    setActiveThread,
   } = useCopilot();
 
-  // Track if we're in the middle of loading messages from a thread switch
-  const isLoadingMessagesRef = useRef(false);
-  // Track the thread ID we're saving to (to prevent saving to wrong thread)
-  const savingToThreadRef = useRef<string | null>(null);
-  // Track last saved message snapshot (IDs + content hash) to prevent duplicate saves
-  const lastSavedSnapshotRef = useRef<string>("");
-  // Track if initial load has happened (for auto-restore)
-  const hasInitializedRef = useRef(false);
-
-  // Generate a snapshot key from messages for comparison
-  // Uses ID + content hash to detect actual changes
-  const getMessageSnapshot = useCallback((msgs: typeof messages) => {
-    return msgs
-      .map((m) => {
-        // Simple hash: first 20 chars + length for uniqueness without full comparison
-        const contentPreview = (m.content ?? "").slice(0, 20);
-        return `${m.id}:${contentPreview}:${m.content?.length ?? 0}`;
-      })
-      .join("|");
-  }, []);
-
-  // Convert UIMessage to core Message format
-  const convertToCore = useCallback((msgs: typeof messages) => {
-    return msgs.map((m) => ({
-      id: m.id,
-      role: m.role,
-      content: m.content,
-      created_at: m.createdAt,
-      tool_calls: m.toolCalls,
-      tool_call_id: m.toolCallId,
-      parent_id: m.parentId,
-      children_ids: m.childrenIds,
-      // Preserve full metadata including citations, toolExecutions, etc.
-      metadata: {
-        ...m.metadata,
-        attachments: m.attachments,
-        thinking: m.thinking,
-      },
-    }));
-  }, []);
-
-  // Handle thread switch - load saved messages
-  const handleSwitchThread = useCallback(
-    async (threadId: string) => {
-      isLoadingMessagesRef.current = true;
-
-      const thread = await switchThread(threadId);
-      if (thread?.messages) {
-        const uiMessages: UIMessage[] = thread.messages.map((m) => ({
-          id: m.id,
-          role: m.role,
-          content: m.content ?? "",
-          createdAt: m.created_at ?? new Date(),
-          toolCalls: m.tool_calls,
-          toolCallId: m.tool_call_id,
-          parentId: m.parent_id,
-          childrenIds: m.children_ids,
-          attachments: m.metadata?.attachments,
-          thinking: m.metadata?.thinking as string | undefined,
-          // Preserve full metadata including citations, toolCallsHidden, toolExecutions, etc.
-          metadata: m.metadata,
-        }));
-        lastSavedSnapshotRef.current = getMessageSnapshot(uiMessages);
-        savingToThreadRef.current = threadId;
-        setMessages(uiMessages);
-        // Restore active branch after tree is rebuilt
-        if (thread.activeLeafId) {
-          switchBranch(thread.activeLeafId);
-        }
-      } else {
-        lastSavedSnapshotRef.current = "";
-        savingToThreadRef.current = threadId;
-        setMessages([]);
-      }
+  // ── Auto-restore on mount ──────────────────────────────────────────────
 
-      // Notify thread change
-      onThreadChange?.(threadId);
-
-      // Reset loading flag after React processes the state update
-      requestAnimationFrame(() => {
-        isLoadingMessagesRef.current = false;
-      });
-    },
-    [
-      switchThread,
-      setMessages,
-      switchBranch,
-      getMessageSnapshot,
-      onThreadChange,
-    ],
-  );
-
-  // Handle new thread - just clear messages, thread is created lazily on first message
-  const handleNewThread = useCallback(async () => {
-    isLoadingMessagesRef.current = true;
-
-    // Don't create thread yet - it will be created automatically when first message is sent
-    // This prevents empty threads from being created
-    clearCurrentThread();
-    lastSavedSnapshotRef.current = "";
-    savingToThreadRef.current = null;
-    setMessages([]);
-
-    // Notify thread change (null = new unsaved thread)
-    onThreadChange?.(null);
-
-    requestAnimationFrame(() => {
-      isLoadingMessagesRef.current = false;
-    });
-  }, [clearCurrentThread, setMessages, onThreadChange]);
-
-  // Auto-restore: load messages when thread is restored from storage
   useEffect(() => {
-    // Skip if persistence is disabled
-    if (!enabled) return;
-    // Skip if already initialized or no thread restored yet
-    if (hasInitializedRef.current || !currentThread) {
-      return;
-    }
+    if (!enabled || state.initialized || !currentThread) return;
 
-    // Mark as initialized
-    hasInitializedRef.current = true;
+    dispatch({ type: "RESTORE_START" });
+    isLoadingRef.current = true;
 
-    // Load messages from the restored thread
-    isLoadingMessagesRef.current = true;
     if (currentThread.messages && currentThread.messages.length > 0) {
-      const uiMessages: UIMessage[] = currentThread.messages.map((m) => ({
-        id: m.id,
-        role: m.role,
-        content: m.content ?? "",
-        createdAt: m.created_at ?? new Date(),
-        toolCalls: m.tool_calls,
-        toolCallId: m.tool_call_id,
-        parentId: m.parent_id,
-        childrenIds: m.children_ids,
-        attachments: m.metadata?.attachments,
-        thinking: m.metadata?.thinking as string | undefined,
-        // Preserve full metadata including citations, toolExecutions, etc.
-        metadata: m.metadata,
-      }));
-      lastSavedSnapshotRef.current = getMessageSnapshot(uiMessages);
-      savingToThreadRef.current = currentThread.id;
+      const uiMessages = currentThread.messages.map(coreToUI);
+      const snapshot = getMessageSnapshot(uiMessages);
       setMessages(uiMessages);
-      // Restore active branch after tree is rebuilt
-      if (currentThread.activeLeafId) {
-        switchBranch(currentThread.activeLeafId);
-      }
+      if (currentThread.activeLeafId) switchBranch(currentThread.activeLeafId);
+      onThreadChange?.(currentThread.id);
+      dispatch({
+        type: "RESTORE_COMPLETE",
+        threadId: currentThread.id,
+        snapshot,
+      });
     } else {
-      lastSavedSnapshotRef.current = "";
-      savingToThreadRef.current = currentThread.id;
+      onThreadChange?.(currentThread.id);
+      dispatch({
+        type: "RESTORE_COMPLETE",
+        threadId: currentThread.id,
+        snapshot: "",
+      });
     }
 
-    // Notify thread change
-    onThreadChange?.(currentThread.id);
-
     requestAnimationFrame(() => {
-      isLoadingMessagesRef.current = false;
+      isLoadingRef.current = false;
     });
   }, [
     enabled,
-    adapter,
     currentThread,
+    state.initialized,
     setMessages,
     switchBranch,
-    getMessageSnapshot,
     onThreadChange,
   ]);
 
-  // Sync messages to storage when streaming completes
+  // Mark initialized if no thread to restore
   useEffect(() => {
-    // Skip if persistence is disabled
-    if (!enabled) return;
-    // Skip if we're loading messages from a thread switch
-    if (isLoadingMessagesRef.current) {
+    if (!enabled) {
+      dispatch({ type: "SKIP_RESTORE" });
       return;
     }
-
-    // Skip if still streaming - wait for completion
-    if (status === "streaming" || status === "submitted") {
-      return;
+    // If autoRestore is off or no thread loaded after mount, skip
+    if (!autoRestoreLastThread && !state.initialized) {
+      dispatch({ type: "SKIP_RESTORE" });
     }
+  }, [enabled, autoRestoreLastThread, state.initialized]);
 
-    // Skip if no messages
-    if (messages.length === 0) {
-      return;
-    }
+  // ── Phase: idle → awaiting_server_id ───────────────────────────────────
 
-    // Check if messages actually changed
-    const currentSnapshot = getMessageSnapshot(messages);
-    if (currentSnapshot === lastSavedSnapshotRef.current) {
-      return;
+  useEffect(() => {
+    if (!enabled) return;
+    if (state.phase !== "idle") return;
+    if (isLoadingRef.current) return;
+    if (status === "streaming" || status === "submitted") return;
+    if (messages.length === 0) return;
+    if (currentThreadId) return; // Already have a thread
+
+    // First message response just completed
+    dispatch({ type: "FIRST_RESPONSE_COMPLETE" });
+  }, [enabled, state.phase, status, messages.length, currentThreadId]);
+
+  // ── Phase: awaiting_server_id → creating ───────────────────────────────
+
+  useEffect(() => {
+    if (state.phase !== "awaiting_server_id") return;
+
+    if (sdkThreadId) {
+      // Server provided a threadId — use it
+      dispatch({ type: "SERVER_ID_RECEIVED", threadId: sdkThreadId });
+    } else {
+      // No server ID available — create thread with a local ID.
+      dispatch({ type: "CREATE_WITH_LOCAL_ID" });
     }
+  }, [state.phase, sdkThreadId]);
+
+  // ── Phase: creating → active ───────────────────────────────────────────
+
+  useEffect(() => {
+    if (state.phase !== "creating") return;
 
-    // Use getAllMessages() so all branches are persisted, not just the visible path
     const allUIMessages = getAllMessages();
     const coreMessages = convertToCore(
       allUIMessages.length > 0 ? allUIMessages : messages,
     );
-
-    // Active leaf = last message on the visible path — persisted so reload restores the right branch
     const activeLeafId = messages[messages.length - 1]?.id;
+    const snapshot = getMessageSnapshot(messages);
+
+    createThread({
+      id: sdkThreadId ?? undefined,
+      messages: coreMessages,
+      activeLeafId,
+    }).then((thread) => {
+      dispatch({ type: "THREAD_CREATED", threadId: thread.id, snapshot });
+      onThreadChange?.(thread.id);
+    });
+  }, [state.phase]); // eslint-disable-line react-hooks/exhaustive-deps
 
-    // If no thread exists, create one with these messages
-    // Use the SDK's threadId (server session ID) as the local thread ID when available
-    // so both systems share the same ID — no mapping layer needed.
-    if (!currentThreadId && !savingToThreadRef.current) {
-      // If the SDK is expected to have a threadId from the server but doesn't yet
-      // (React state batching delay), skip this render — it'll fire again when
-      // sdkThreadId updates. This prevents creating a local thread_xxx that
-      // conflicts with the server session ID.
-      if (!sdkThreadId && status === "ready" && messages.length <= 2) {
-        // First message just completed — sdkThreadId may arrive next render
-        return;
-      }
-      // Set ref immediately to prevent race condition with rapid messages
-      savingToThreadRef.current = "creating";
-      // Mark as initialized so auto-restore doesn't fire when createThread
-      // sets currentThread — the messages are already in the chat state.
-      hasInitializedRef.current = true;
-      createThread({
-        id: sdkThreadId ?? undefined,
-        messages: coreMessages,
-        activeLeafId,
-      }).then((thread) => {
-        lastSavedSnapshotRef.current = currentSnapshot;
-        savingToThreadRef.current = thread.id;
-        onThreadChange?.(thread.id);
-      });
-      return;
-    }
+  // ── Phase: active — sync messages on change ────────────────────────────
 
-    // Make sure we're saving to the correct thread
-    if (
-      savingToThreadRef.current &&
-      savingToThreadRef.current !== currentThreadId
-    ) {
-      return;
-    }
+  useEffect(() => {
+    if (!enabled) return;
+    if (state.phase !== "active") return;
+    if (isLoadingRef.current) return;
+    if (status === "streaming" || status === "submitted") return;
+    if (messages.length === 0) return;
+
+    const snapshot = getMessageSnapshot(messages);
+    if (snapshot === state.lastSnapshot) return;
+
+    // Verify we're saving to the right thread
+    if (state.threadId && state.threadId !== currentThreadId) return;
+
+    const allUIMessages = getAllMessages();
+    const coreMessages = convertToCore(
+      allUIMessages.length > 0 ? allUIMessages : messages,
+    );
+    const activeLeafId = messages[messages.length - 1]?.id;
 
-    // Update existing thread
     updateCurrentThread({ messages: coreMessages, activeLeafId });
-    lastSavedSnapshotRef.current = currentSnapshot;
+    dispatch({ type: "MESSAGES_SAVED", snapshot });
   }, [
     enabled,
-    adapter,
+    state.phase,
+    state.lastSnapshot,
+    state.threadId,
     messages,
-    currentThreadId,
     status,
+    currentThreadId,
     updateCurrentThread,
-    createThread,
-    refreshThreads,
-    getMessageSnapshot,
-    convertToCore,
     getAllMessages,
-    onThreadChange,
   ]);
 
-  // Check if chat is busy (disable thread switching during streaming)
+  // ── Switch thread ──────────────────────────────────────────────────────
+
+  const handleSwitchThread = useCallback(
+    async (threadId: string) => {
+      dispatch({ type: "START_SWITCH" });
+      isLoadingRef.current = true;
+
+      const thread = await switchThread(threadId);
+      if (thread?.messages) {
+        const uiMessages = thread.messages.map(coreToUI);
+        const snapshot = getMessageSnapshot(uiMessages);
+        setMessages(uiMessages);
+        if (thread.activeLeafId) switchBranch(thread.activeLeafId);
+        onThreadChange?.(threadId);
+        dispatch({ type: "SWITCH_COMPLETE", threadId, snapshot });
+      } else {
+        setMessages([]);
+        onThreadChange?.(threadId);
+        dispatch({ type: "SWITCH_COMPLETE", threadId, snapshot: "" });
+      }
+
+      requestAnimationFrame(() => {
+        isLoadingRef.current = false;
+      });
+    },
+    [switchThread, setMessages, switchBranch, onThreadChange],
+  );
+
+  // ── New thread ─────────────────────────────────────────────────────────
+
+  const handleNewThread = useCallback(async () => {
+    isLoadingRef.current = true;
+
+    clearCurrentThread();
+    setMessages([]);
+    setActiveThread(null); // Clear SDK session so next message creates a new one
+    onThreadChange?.(null);
+    dispatch({ type: "NEW_THREAD" });
+
+    requestAnimationFrame(() => {
+      isLoadingRef.current = false;
+    });
+  }, [clearCurrentThread, setMessages, setActiveThread, onThreadChange]);
+
+  // ── Return ─────────────────────────────────────────────────────────────
+
   const isBusy = isLoading || status === "streaming" || status === "submitted";
 
   return {

From 803127fb24ce91a70473683bf4777b66c481bf2a Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Fri, 27 Mar 2026 15:03:24 +0530
Subject: [PATCH 55/72] feat(thread): enhance localStorage adapter and thread
 picker functionality

- Updated localStorage adapter to return AsyncThreadStorageAdapter, enabling asynchronous operations.
- Added deleteThread method to localStorage adapter for thread removal.
- Modified ThreadPicker component to optimistically update displayed threads upon deletion, improving user experience.
- Introduced useEffect to synchronize displayed threads with external changes.
---
 .../thread/adapters/localStorageAdapter.ts    | 10 ++++++--
 .../src/ui/components/ui/thread-picker.tsx    | 23 +++++++++++++++----
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts b/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
index 1515d5a..ed74aaa 100644
--- a/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
+++ b/packages/copilot-sdk/src/thread/adapters/localStorageAdapter.ts
@@ -6,7 +6,7 @@
  */
 
 import type { ThreadData } from "../../core/types/thread";
-import type { ThreadStorageAdapter } from "./types";
+import type { ThreadStorageAdapter, AsyncThreadStorageAdapter } from "./types";
 
 const DEFAULT_STORAGE_KEY = "copilot-sdk-store";
 const STORE_VERSION = 1;
@@ -265,7 +265,7 @@ function updateStore(
  */
 export function createLocalStorageAdapter(
   config?: LocalStorageAdapterConfig,
-): ThreadStorageAdapter {
+): AsyncThreadStorageAdapter {
   const storageKey = config?.storageKey ?? DEFAULT_STORAGE_KEY;
 
   return {
@@ -300,6 +300,12 @@ export function createLocalStorageAdapter(
         lastActiveThreadId: threadId,
       }));
     },
+
+    deleteThread: async (id: string): Promise<void> => {
+      updateStore(storageKey, (store) => ({
+        threads: store.threads.filter((t) => t.id !== id),
+      }));
+    },
   };
 }
 
diff --git a/packages/copilot-sdk/src/ui/components/ui/thread-picker.tsx b/packages/copilot-sdk/src/ui/components/ui/thread-picker.tsx
index 17a814c..f3c3617 100644
--- a/packages/copilot-sdk/src/ui/components/ui/thread-picker.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/thread-picker.tsx
@@ -187,12 +187,19 @@ export function ThreadPicker({
   newButtonClassName,
 }: ThreadPickerProps) {
   const [isOpen, setIsOpen] = React.useState(false);
+  // Optimistic local list — immediately reflects deletions without waiting for async state
+  const [displayedThreads, setDisplayedThreads] = React.useState(threads);
+
+  // Sync when external threads prop changes (e.g. after async store update or new thread)
+  React.useEffect(() => {
+    setDisplayedThreads(threads);
+  }, [threads]);
 
   // Find selected thread
   const selectedThread = React.useMemo(() => {
     if (!value) return null;
-    return threads.find((t) => t.id === value) ?? null;
-  }, [value, threads]);
+    return displayedThreads.find((t) => t.id === value) ?? null;
+  }, [value, displayedThreads]);
 
   const handleSelect = (threadId: string) => {
     onSelect?.(threadId);
@@ -204,6 +211,12 @@ export function ThreadPicker({
     setIsOpen(false);
   };
 
+  const handleDelete = (threadId: string) => {
+    // Optimistically remove from local list immediately
+    setDisplayedThreads((prev) => prev.filter((t) => t.id !== threadId));
+    onDeleteThread?.(threadId);
+  };
+
   return (
     <Popover open={isOpen} onOpenChange={setIsOpen}>
       <PopoverTrigger
@@ -261,8 +274,8 @@ export function ThreadPicker({
         )}
 
         {/* Thread list */}
-        {threads.length > 0 ? (
-          threads.map((thread) => (
+        {displayedThreads.length > 0 ? (
+          displayedThreads.map((thread) => (
             <div
               key={thread.id}
               className={cn(
@@ -308,7 +321,7 @@ export function ThreadPicker({
                   type="button"
                   onClick={(e) => {
                     e.stopPropagation();
-                    onDeleteThread(thread.id);
+                    handleDelete(thread.id);
                   }}
                   className="flex-shrink-0 p-1 rounded opacity-0 group-hover:opacity-100 text-muted-foreground hover:text-destructive hover:bg-destructive/10 transition-all focus:opacity-100 focus:outline-none"
                   aria-label="Delete thread"

From 9cad35f08be91778d9e8fd34ec5d0777e8c52e14 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Fri, 27 Mar 2026 16:31:01 +0530
Subject: [PATCH 56/72] fix(chat): refine drag overlay logic in ChatComponent

- Updated drag overlay rendering to only display when not using a custom renderInput, ensuring consistent behavior across different input types.
---
 packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index f302629..10ae4b5 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -913,8 +913,8 @@ function ChatComponent({
           onDragLeave={handleDragLeave}
           onDrop={handleDrop}
         >
-          {/* Drag overlay */}
-          {isDragging && (
+          {/* Drag overlay — only for built-in input; custom renderInput handles its own */}
+          {isDragging && !renderInput && (
             <div className="csdk-dropzone-overlay absolute inset-0 z-50 bg-primary/10 border-2 border-dashed border-primary flex items-center justify-center">
               <div className="text-primary font-medium text-lg">
                 Drop files here

From d84ee2873b3ddef69dee6cd303585525e5dc079d Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 28 Mar 2026 15:02:42 +0530
Subject: [PATCH 57/72] chore: bump @yourgpt/copilot-sdk version to
 2.1.5-alpha.7

---
 packages/copilot-sdk/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index f45c929..7d4908a 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.5-alpha.6",
+  "version": "2.1.5-alpha.7",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",

From 04528674f7ca35f73e9a283e32e6c3b3df4ff7b1 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 28 Mar 2026 19:31:13 +0530
Subject: [PATCH 58/72] feat(docs): add documentation for message history
 compaction and skills system

- Introduced new documentation for message history compaction strategies, including usage examples and architecture details.
- Added documentation for the skills system, outlining on-demand instruction sets and API usage.
- Enhanced error handling documentation in the chat component, detailing how to manage server errors and display error messages.
---
 .../alpha-docs}/message-history-compaction.md |   0
 .../docs/alpha-docs}/skills-system.md         |   0
 .../docs/api-reference/react/components.mdx   |   2 +
 apps/docs/content/docs/chat/index.mdx         |  29 +++
 .../copilot-sdk/src/chat/ChatWithTools.ts     |   3 +
 .../src/chat/adapters/HttpTransport.ts        |  17 +-
 .../src/chat/classes/AbstractChat.ts          |  28 +++
 .../src/chat/interfaces/ChatTransport.ts      |  17 ++
 packages/copilot-sdk/src/chat/types/chat.ts   |   5 +
 .../src/react/provider/CopilotProvider.tsx    |  11 +
 .../src/ui/components/composed/chat/chat.tsx  |  69 ++++++
 .../src/ui/components/composed/chat/types.ts  |   2 +
 .../ui/components/composed/connected-chat.tsx |   2 +
 .../src/ui/components/ui/popover.tsx          |   6 +-
 .../src/ui/components/ui/thread-picker.tsx    | 213 +++++++++---------
 packages/copilot-sdk/src/ui/styles/base.css   |  26 +++
 provider-notes/tool_result_requirements.md    | 152 +++++++++++++
 17 files changed, 471 insertions(+), 111 deletions(-)
 rename {beta-docs => apps/docs/alpha-docs}/message-history-compaction.md (100%)
 rename {beta-docs => apps/docs/alpha-docs}/skills-system.md (100%)
 create mode 100644 provider-notes/tool_result_requirements.md

diff --git a/beta-docs/message-history-compaction.md b/apps/docs/alpha-docs/message-history-compaction.md
similarity index 100%
rename from beta-docs/message-history-compaction.md
rename to apps/docs/alpha-docs/message-history-compaction.md
diff --git a/beta-docs/skills-system.md b/apps/docs/alpha-docs/skills-system.md
similarity index 100%
rename from beta-docs/skills-system.md
rename to apps/docs/alpha-docs/skills-system.md
diff --git a/apps/docs/content/docs/api-reference/react/components.mdx b/apps/docs/content/docs/api-reference/react/components.mdx
index 02e3f82..84bcb1e 100644
--- a/apps/docs/content/docs/api-reference/react/components.mdx
+++ b/apps/docs/content/docs/api-reference/react/components.mdx
@@ -42,6 +42,7 @@ function App() {
 | `initialMessages` | `Message[]` | No | Initial messages to populate the chat |
 | `onMessagesChange` | `(messages: Message[]) => void` | No | Callback when messages change |
 | `onError` | `(error: Error) => void` | No | Callback when an error occurs |
+| `parseError` | `(status: number, body: unknown) => string \| null` | No | Extract message from custom server error formats |
 | `streaming` | `boolean` | No | Enable/disable streaming (default: true) |
 | `debug` | `boolean` | No | Enable debug logging |
 
@@ -136,3 +137,4 @@ function ChatApp() {
   <CopilotChat />
 </CopilotProvider>
 ```
+
diff --git a/apps/docs/content/docs/chat/index.mdx b/apps/docs/content/docs/chat/index.mdx
index 527460b..2d68742 100644
--- a/apps/docs/content/docs/chat/index.mdx
+++ b/apps/docs/content/docs/chat/index.mdx
@@ -207,6 +207,35 @@ function CustomChat() {
 
 ---
 
+## Error Handling
+
+When the server returns a non-2xx response, the SDK removes the loading placeholder and surfaces the error via `state.error`. The built-in `CopilotChat` shows a dismissible banner — errors are **never written into message history**.
+
+Handle errors via `CopilotProvider` props:
+
+```tsx
+<CopilotProvider
+  runtimeUrl="/api/chat"
+  onError={(error) => toast.error(error.message)}
+  parseError={(status, body: any) => {
+    // Return null to fall back to SDK default (body.message or body.error)
+    return body?.errors?.[0]?.message ?? body?.detail ?? null;
+  }}
+>
+```
+
+Or read error state directly from `useCopilot()`:
+
+```tsx
+const { error, status } = useCopilot();
+// error → null when idle, Error object on failure
+// status → 'ready' | 'streaming' | 'submitted' | 'error'
+```
+
+The error clears automatically when the user sends the next message.
+
+---
+
 ## Styling
 
 The chat component uses Tailwind CSS. Override styles with className:
diff --git a/packages/copilot-sdk/src/chat/ChatWithTools.ts b/packages/copilot-sdk/src/chat/ChatWithTools.ts
index 4b3b12d..66a7126 100644
--- a/packages/copilot-sdk/src/chat/ChatWithTools.ts
+++ b/packages/copilot-sdk/src/chat/ChatWithTools.ts
@@ -71,6 +71,8 @@ export interface ChatWithToolsConfig {
   state?: ChatState<UIMessage>;
   /** Transport implementation */
   transport?: ChatTransport;
+  /** Custom error message extractor for non-2xx API responses */
+  parseError?: (status: number, body: unknown) => string | null | undefined;
 }
 
 /**
@@ -153,6 +155,7 @@ export class ChatWithTools {
       initialMessages: config.initialMessages,
       state: config.state,
       transport: config.transport,
+      parseError: config.parseError,
       callbacks: {
         onMessagesChange: callbacks.onMessagesChange,
         onStatusChange: callbacks.onStatusChange,
diff --git a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
index 42af442..1367fed 100644
--- a/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
+++ b/packages/copilot-sdk/src/chat/adapters/HttpTransport.ts
@@ -100,8 +100,21 @@ export class HttpTransport implements ChatTransport {
       });
 
       if (!response.ok) {
-        const error = await response.text();
-        throw new Error(`HTTP ${response.status}: ${error}`);
+        let errorMessage = `HTTP ${response.status}`;
+        try {
+          const errorBody = await response.json();
+          // Try user-provided parser first, then fall back to default extraction
+          const custom = this.config.parseError?.(response.status, errorBody);
+          errorMessage =
+            custom ??
+            errorBody?.message ??
+            errorBody?.error ??
+            JSON.stringify(errorBody);
+        } catch {
+          const text = await response.text();
+          if (text) errorMessage = text;
+        }
+        throw new Error(errorMessage);
       }
 
       const contentType = response.headers.get("content-type") || "";
diff --git a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
index 9582997..3fa471c 100644
--- a/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
+++ b/packages/copilot-sdk/src/chat/classes/AbstractChat.ts
@@ -100,6 +100,12 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
   // Current streaming state
   private streamState: StreamingMessageState | null = null;
 
+  // ID of the pending assistant placeholder pushed before a request.
+  // Used by handleError() to pop (remove) the placeholder on failure so it
+  // doesn't stay frozen. Error is surfaced via state.error only — never written
+  // into message history.
+  private _activePlaceholderMessageId: string | undefined = undefined;
+
   constructor(init: ChatInit<T>) {
     this.config = {
       runtimeUrl: init.runtimeUrl,
@@ -128,6 +134,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         headers: init.headers,
         body: init.body,
         streaming: init.streaming ?? true,
+        parseError: init.parseError,
       });
 
     // Store callbacks
@@ -254,6 +261,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
         }) as T;
         this.state.pushMessage(preMsg);
         preCreatedMessageId = preMsg.id;
+        this._activePlaceholderMessageId = preMsg.id;
       }
 
       // Notify callbacks (single batch: user message + status + optional placeholder)
@@ -466,6 +474,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       }
 
       this.state.status = "submitted";
+      this.state.error = undefined;
       this.callbacks.onMessagesChange?.(this._allMessages());
       this.callbacks.onStatusChange?.("submitted");
 
@@ -692,6 +701,7 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
       this.state.pushMessage(preMsg);
       this.callbacks.onMessagesChange?.(this._allMessages());
       preCreatedMessageId = preMsg.id;
+      this._activePlaceholderMessageId = preMsg.id;
     }
 
     // Send request
@@ -699,6 +709,9 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
 
     // Check if streaming or JSON
     if (this.isAsyncIterable(response)) {
+      // _activePlaceholderMessageId stays set throughout streaming so that
+      // handleError() can pop the placeholder if an error chunk arrives mid-stream.
+      // handleStreamResponse clears it on successful completion.
       await this.handleStreamResponse(response, preCreatedMessageId);
     } else {
       // Non-streaming: remove the pre-pushed placeholder (not needed).
@@ -724,6 +737,8 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
           this.state.setCurrentLeaf(intendedLeafId);
         }
       }
+      // Placeholder removed — clear the tracker before handling the response
+      this._activePlaceholderMessageId = undefined;
       this.handleJsonResponse(response);
     }
   }
@@ -1637,6 +1652,9 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
 
     this.callbacks.onMessagesChange?.(this._allMessages());
 
+    // Stream completed successfully — placeholder is now a real message, clear tracker
+    this._activePlaceholderMessageId = undefined;
+
     // Close the stream group opened at the start of handleStreamResponse
     this.debugGroupEnd();
 
@@ -1757,6 +1775,16 @@ export class AbstractChat<T extends UIMessage = UIMessage> {
    */
   protected handleError(error: Error): void {
     this.debug("error", error);
+
+    // Remove the pending loading placeholder so it doesn't stay frozen.
+    // The error is surfaced through state.error → UI banner only —
+    // never written into the message history.
+    if (this._activePlaceholderMessageId) {
+      this.state.popMessage();
+      this._activePlaceholderMessageId = undefined;
+      this.callbacks.onMessagesChange?.(this._allMessages());
+    }
+
     this.state.error = error;
     this.state.status = "error";
     this.callbacks.onError?.(error);
diff --git a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
index 2275ebc..17f5fa4 100644
--- a/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
+++ b/packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts
@@ -238,4 +238,21 @@ export interface TransportConfig {
   streaming?: boolean;
   /** Request timeout in ms */
   timeout?: number;
+  /**
+   * Custom error message extractor for non-2xx responses.
+   * Receives the HTTP status code and the parsed response body.
+   * Return a string to use as the error message, or null/undefined to fall back to the default extraction.
+   *
+   * @example
+   * ```ts
+   * // Handle nested or array error formats
+   * parseError: (status, body) => {
+   *   if (Array.isArray(body?.errors)) return body.errors[0]?.message;
+   *   if (body?.detail) return body.detail;       // Django-style
+   *   if (body?.data?.message) return body.data.message; // nested
+   *   return null; // fall back to default (body.message || body.error)
+   * }
+   * ```
+   */
+  parseError?: (status: number, body: unknown) => string | null | undefined;
 }
diff --git a/packages/copilot-sdk/src/chat/types/chat.ts b/packages/copilot-sdk/src/chat/types/chat.ts
index 195543f..898c40a 100644
--- a/packages/copilot-sdk/src/chat/types/chat.ts
+++ b/packages/copilot-sdk/src/chat/types/chat.ts
@@ -103,6 +103,11 @@ export interface ChatConfig {
   tools?: ToolDefinition[];
   /** Optional prompt/tool optimization controls */
   optimization?: ToolOptimizationConfig;
+  /**
+   * Custom error message extractor for non-2xx API responses.
+   * Receives HTTP status and parsed body — return a string or null to fall back to default.
+   */
+  parseError?: (status: number, body: unknown) => string | null | undefined;
 }
 
 /**
diff --git a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
index 230875f..2bc0dd3 100644
--- a/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
+++ b/packages/copilot-sdk/src/react/provider/CopilotProvider.tsx
@@ -309,6 +309,15 @@ export interface CopilotProviderProps {
   onMessagesChange?: (messages: Message[]) => void;
   /** Callback when an error occurs */
   onError?: (error: Error) => void;
+  /**
+   * Custom error message extractor for non-2xx API responses.
+   * Receives the HTTP status and parsed response body.
+   * Return a string to override the default message, or null to use the default.
+   *
+   * @example
+   * parseError: (status, body) => body?.errors?.[0]?.message ?? body?.detail ?? null
+   */
+  parseError?: (status: number, body: unknown) => string | null | undefined;
   /** Enable/disable streaming (default: true) */
   streaming?: boolean;
   /**
@@ -549,6 +558,7 @@ export function CopilotProvider(props: CopilotProviderProps) {
     initialMessages,
     onMessagesChange,
     onError,
+    parseError,
     streaming,
     headers,
     body,
@@ -650,6 +660,7 @@ export function CopilotProvider(props: CopilotProviderProps) {
         streaming,
         headers,
         body,
+        parseError,
         debug,
         maxIterations,
         maxIterationsMessage,
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
index 10ae4b5..33832c3 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/chat.tsx
@@ -493,6 +493,7 @@ function ChatComponent({
   onSendMessage,
   onStop,
   isLoading = false,
+  error,
   // Compound children
   children,
   // Labels
@@ -575,6 +576,19 @@ function ChatComponent({
     PendingAttachment[]
   >([]);
   const [isDragging, setIsDragging] = useState(false);
+  const [isDismissed, setIsDismissed] = useState(false);
+  const [displayedError, setDisplayedError] = useState<Error | null>(null);
+
+  // Track error changes: new error → show it; error clears → keep displayedError for exit animation
+  React.useEffect(() => {
+    if (error) {
+      setDisplayedError(error);
+      setIsDismissed(false);
+    }
+  }, [error]);
+
+  // Banner is visible when: there's an error prop AND not dismissed
+  const showErrorBanner = !!error && !isDismissed;
   const fileInputRef = useRef<HTMLInputElement>(null);
   const fileInputId = useId(); // Unique ID for this Chat instance's file input
 
@@ -1202,6 +1216,61 @@ function ChatComponent({
                 />
               )}
 
+              {/* Error banner — always in DOM while displayedError exists, animated via max-height/opacity */}
+              {displayedError && (
+                <div
+                  className={cn(
+                    "mx-2 mb-1 overflow-hidden transition-all duration-200 ease-in-out",
+                    showErrorBanner
+                      ? "max-h-20 opacity-100"
+                      : "max-h-0 opacity-0 mb-0",
+                  )}
+                  onTransitionEnd={() => {
+                    // Clean up displayedError after exit animation finishes
+                    if (!showErrorBanner) setDisplayedError(null);
+                  }}
+                >
+                  <div className="flex items-start gap-2 rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-xs text-destructive">
+                    <svg
+                      className="mt-0.5 h-3.5 w-3.5 flex-shrink-0"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                      strokeWidth={2}
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        d="M12 9v2m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"
+                      />
+                    </svg>
+                    <span className="flex-1 leading-relaxed">
+                      {displayedError.message}
+                    </span>
+                    <button
+                      type="button"
+                      onClick={() => setIsDismissed(true)}
+                      className="flex-shrink-0 opacity-60 hover:opacity-100"
+                      aria-label="Dismiss error"
+                    >
+                      <svg
+                        className="h-3 w-3"
+                        fill="none"
+                        viewBox="0 0 24 24"
+                        stroke="currentColor"
+                        strokeWidth={2}
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          d="M6 18L18 6M6 6l12 12"
+                        />
+                      </svg>
+                    </button>
+                  </div>
+                </div>
+              )}
+
               {/* Input */}
               {renderInput ? (
                 renderInput()
diff --git a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
index c081e52..ba4849a 100644
--- a/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
+++ b/packages/copilot-sdk/src/ui/components/composed/chat/types.ts
@@ -253,6 +253,8 @@ export type ChatProps = {
   onStop?: () => void;
   /** Whether AI is currently generating */
   isLoading?: boolean;
+  /** Current error from the AI (shown as a dismissible banner above the input) */
+  error?: Error | null;
 
   // === Compound Components ===
   /**
diff --git a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
index 3e42ff9..6598f30 100644
--- a/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
+++ b/packages/copilot-sdk/src/ui/components/composed/connected-chat.tsx
@@ -363,6 +363,7 @@ function CopilotChatBase(
     switchBranch,
     getBranchInfo,
     editMessage,
+    error: chatError,
   } = useCopilot();
 
   // Convert tool executions to the expected format
@@ -653,6 +654,7 @@ function CopilotChatBase(
       onSendMessage={sendMessage}
       onStop={stop}
       isLoading={isLoading}
+      error={chatError}
       showPoweredBy={chatProps.showPoweredBy ?? true}
       suggestions={suggestions}
       isProcessing={isProcessingToolResults}
diff --git a/packages/copilot-sdk/src/ui/components/ui/popover.tsx b/packages/copilot-sdk/src/ui/components/ui/popover.tsx
index 298fb74..6222460 100644
--- a/packages/copilot-sdk/src/ui/components/ui/popover.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/popover.tsx
@@ -80,12 +80,8 @@ function PopoverContent({
       <BasePopover.Positioner side={side} align={align} sideOffset={sideOffset}>
         <BasePopover.Popup
           className={cn(
+            "csdk-popover-popup",
             "z-50 w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none",
-            "data-[state=open]:animate-in data-[state=closed]:animate-out",
-            "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
-            "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
-            "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2",
-            "data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
             className,
           )}
         >
diff --git a/packages/copilot-sdk/src/ui/components/ui/thread-picker.tsx b/packages/copilot-sdk/src/ui/components/ui/thread-picker.tsx
index f3c3617..b9a7e72 100644
--- a/packages/copilot-sdk/src/ui/components/ui/thread-picker.tsx
+++ b/packages/copilot-sdk/src/ui/components/ui/thread-picker.tsx
@@ -218,125 +218,130 @@ export function ThreadPicker({
   };
 
   return (
-    <Popover open={isOpen} onOpenChange={setIsOpen}>
-      <PopoverTrigger
-        disabled={disabled || loading}
-        className={cn(
-          "flex items-center gap-1 w-full",
-          disabled && "opacity-50 cursor-not-allowed",
-          className,
-          buttonClassName,
-        )}
-      >
-        <div className="flex items-center gap-1 text-xs ">
-          {loading ? (
-            <span className="text-muted-foreground">Loading...</span>
-          ) : selectedThread ? (
-            <span className="truncate font-medium text-muted-foreground hover:text-foreground">
-              {selectedThread.title || "Untitled conversation"}
-            </span>
-          ) : (
-            <span className="text-muted-foreground">{placeholder}</span>
-          )}
-        </div>
-
-        <ChevronIcon
+    <div className={cn("relative w-44", className)}>
+      <Popover open={isOpen} onOpenChange={setIsOpen}>
+        <PopoverTrigger
+          disabled={disabled || loading}
           className={cn(
-            "flex-shrink-0 size-3 text-muted-foreground transition-transform",
-            isOpen && "rotate-180",
+            "flex items-center gap-1.5 w-full rounded-md px-1.5 py-0.5",
+            "hover:bg-muted/70 transition-colors duration-150",
+            "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+            disabled && "opacity-50 cursor-not-allowed pointer-events-none",
+            buttonClassName,
           )}
-        />
-      </PopoverTrigger>
+        >
+          <div className="flex items-center gap-1 text-xs min-w-0 flex-1">
+            {loading ? (
+              <span className="text-muted-foreground truncate">Loading...</span>
+            ) : selectedThread ? (
+              <span className="truncate font-medium text-muted-foreground">
+                {selectedThread.title || "Untitled conversation"}
+              </span>
+            ) : (
+              <span className="text-muted-foreground/70 truncate">
+                {placeholder}
+              </span>
+            )}
+          </div>
 
-      <PopoverContent
-        align="start"
-        className={cn(
-          "w-[var(--anchor-width)] min-w-[250px] p-0 max-h-[300px] overflow-auto",
-          dropdownClassName,
-        )}
-      >
-        {/* New conversation button */}
-        {onNewThread && (
-          <button
-            type="button"
-            onClick={handleNewThread}
+          <ChevronIcon
             className={cn(
-              "flex items-center gap-2 w-full px-2.5 py-1.5 text-left",
-              "hover:bg-accent hover:text-accent-foreground",
-              "focus:bg-accent focus:text-accent-foreground focus:outline-none",
-              "border-b",
-              newButtonClassName,
+              "flex-shrink-0 size-3 text-muted-foreground/60 transition-transform duration-150",
+              isOpen && "rotate-180",
             )}
-          >
-            <PlusIcon className="text-primary size-3" />
-            <span className="font-medium text-xs">{newThreadLabel}</span>
-          </button>
-        )}
+          />
+        </PopoverTrigger>
 
-        {/* Thread list */}
-        {displayedThreads.length > 0 ? (
-          displayedThreads.map((thread) => (
-            <div
-              key={thread.id}
+        <PopoverContent
+          align="start"
+          className={cn(
+            "p-0 w-56 max-h-[280px] overflow-auto",
+            dropdownClassName,
+          )}
+        >
+          {/* New conversation button */}
+          {onNewThread && (
+            <button
+              type="button"
+              onClick={handleNewThread}
               className={cn(
-                "group flex items-center gap-1 w-full px-2.5 py-1.5",
+                "flex items-center gap-2 w-full px-2.5 py-1.5 text-left",
                 "hover:bg-accent hover:text-accent-foreground",
-                "focus-within:bg-accent focus-within:text-accent-foreground",
-                value === thread.id && "bg-accent",
-                itemClassName,
+                "focus:bg-accent focus:text-accent-foreground focus:outline-none",
+                "border-b",
+                newButtonClassName,
               )}
             >
-              <button
-                type="button"
-                onClick={() => handleSelect(thread.id)}
-                className="flex-1 flex flex-col gap-0.5 text-left focus:outline-none min-w-0"
+              <PlusIcon className="text-primary size-3" />
+              <span className="font-medium text-xs">{newThreadLabel}</span>
+            </button>
+          )}
+
+          {/* Thread list */}
+          {displayedThreads.length > 0 ? (
+            displayedThreads.map((thread) => (
+              <div
+                key={thread.id}
+                className={cn(
+                  "group flex items-center gap-1 w-full px-2.5 py-1.5",
+                  "hover:bg-accent hover:text-accent-foreground",
+                  "focus-within:bg-accent focus-within:text-accent-foreground",
+                  value === thread.id && "bg-accent",
+                  itemClassName,
+                )}
               >
-                <div className="flex items-center justify-between gap-2">
-                  <span className="font-medium text-xs truncate">
-                    {thread.title || "Untitled conversation"}
-                  </span>
-                  {value === thread.id && (
-                    <CheckIcon className="flex-shrink-0 text-primary size-3" />
-                  )}
-                </div>
-                <div className="flex items-center gap-1.5 text-[11px] text-muted-foreground">
-                  {thread.preview && (
-                    <span className="truncate max-w-[180px]">
-                      {thread.preview}
-                    </span>
-                  )}
-                  {thread.preview && thread.updatedAt && (
-                    <span className="flex-shrink-0">·</span>
-                  )}
-                  {thread.updatedAt && (
-                    <span className="flex-shrink-0">
-                      {formatDate(thread.updatedAt)}
-                    </span>
-                  )}
-                </div>
-              </button>
-              {/* Delete button - appears on hover */}
-              {onDeleteThread && (
                 <button
                   type="button"
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    handleDelete(thread.id);
-                  }}
-                  className="flex-shrink-0 p-1 rounded opacity-0 group-hover:opacity-100 text-muted-foreground hover:text-destructive hover:bg-destructive/10 transition-all focus:opacity-100 focus:outline-none"
-                  aria-label="Delete thread"
+                  onClick={() => handleSelect(thread.id)}
+                  className="flex-1 flex flex-col gap-0.5 text-left focus:outline-none min-w-0"
                 >
-                  <TrashIcon className="size-3" />
+                  <div className="flex items-center justify-between gap-2">
+                    <span className="font-medium text-xs truncate">
+                      {thread.title || "Untitled conversation"}
+                    </span>
+                    {value === thread.id && (
+                      <CheckIcon className="flex-shrink-0 text-primary size-3" />
+                    )}
+                  </div>
+                  <div className="flex items-center gap-1.5 text-[11px] text-muted-foreground">
+                    {thread.preview && (
+                      <span className="truncate max-w-[180px]">
+                        {thread.preview}
+                      </span>
+                    )}
+                    {thread.preview && thread.updatedAt && (
+                      <span className="flex-shrink-0">·</span>
+                    )}
+                    {thread.updatedAt && (
+                      <span className="flex-shrink-0">
+                        {formatDate(thread.updatedAt)}
+                      </span>
+                    )}
+                  </div>
                 </button>
-              )}
+                {/* Delete button - appears on hover */}
+                {onDeleteThread && (
+                  <button
+                    type="button"
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      handleDelete(thread.id);
+                    }}
+                    className="flex-shrink-0 p-1 rounded opacity-0 group-hover:opacity-100 text-muted-foreground hover:text-destructive hover:bg-destructive/10 transition-all focus:opacity-100 focus:outline-none"
+                    aria-label="Delete thread"
+                  >
+                    <TrashIcon className="size-3" />
+                  </button>
+                )}
+              </div>
+            ))
+          ) : (
+            <div className="px-2.5 py-3 text-center text-xs text-muted-foreground">
+              No conversations yet
             </div>
-          ))
-        ) : (
-          <div className="px-2.5 py-3 text-center text-xs text-muted-foreground">
-            No conversations yet
-          </div>
-        )}
-      </PopoverContent>
-    </Popover>
+          )}
+        </PopoverContent>
+      </Popover>
+    </div>
   );
 }
diff --git a/packages/copilot-sdk/src/ui/styles/base.css b/packages/copilot-sdk/src/ui/styles/base.css
index adbf1e9..baea8cc 100644
--- a/packages/copilot-sdk/src/ui/styles/base.css
+++ b/packages/copilot-sdk/src/ui/styles/base.css
@@ -148,6 +148,32 @@
   transform: scale(0.97);
 }
 
+/* Popover Popup — entry/exit animation driven by Base UI data attributes */
+.csdk-popover-popup {
+  opacity: 1;
+  transform: scale(1) translateY(0);
+  transition: opacity 180ms cubic-bezier(0, 0, 0.2, 1),
+              transform 180ms cubic-bezier(0, 0, 0.2, 1);
+}
+
+.csdk-popover-popup[data-starting-style] {
+  opacity: 0;
+  transform: scale(0.96) translateY(-6px);
+}
+
+.csdk-popover-popup[data-ending-style] {
+  opacity: 0;
+  transform: scale(0.96) translateY(-6px);
+  transition-duration: 130ms;
+  transition-timing-function: cubic-bezier(0.4, 0, 1, 1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .csdk-popover-popup {
+    transition: none;
+  }
+}
+
 /* Loader Animations */
 @keyframes csdk-spinner-fade {
   0%, 100% { opacity: 1; }
diff --git a/provider-notes/tool_result_requirements.md b/provider-notes/tool_result_requirements.md
new file mode 100644
index 0000000..d9744f4
--- /dev/null
+++ b/provider-notes/tool_result_requirements.md
@@ -0,0 +1,152 @@
+# Tool Result Formatting Requirements
+
+Rules to follow when returning tool results to avoid continuation errors — covering both Claude and OpenAI.
+
+---
+
+## Claude
+
+### Requirements
+
+1. **Immediate follow** — `tool_result` must appear in the very next message after the assistant's `tool_use`. No messages in between.
+2. **Correct role** — The message containing `tool_result` must have `role: "user"`.
+3. **tool_result first** — In the content array, all `tool_result` blocks must come **before** any `text` blocks.
+4. **Matching ID** — `tool_use_id` must exactly match the `id` from the corresponding `tool_use` block.
+5. **One result per call** — Every `tool_use` block must have exactly one corresponding `tool_result`.
+6. **Valid content types** — `tool_result` content supports `text`, `image`, and `document` types only.
+7. **Error flag** — If execution fails, set `is_error: true` instead of omitting the result.
+8. **No skipping** — Every `tool_use` must be returned, even for trivial tools.
+9. **Parallel results together** — All results for parallel tool calls go in a **single** user message, not separate ones.
+10. **No nesting** — `tool_result` blocks cannot be nested inside other content blocks.
+
+### Examples
+
+**❌ Wrong — text before tool_result**
+
+```json
+{
+  "role": "user",
+  "content": [
+    { "type": "text", "text": "Here are the results:" },
+    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." }
+  ]
+}
+```
+
+**✅ Correct**
+
+```json
+{
+  "role": "user",
+  "content": [
+    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." },
+    { "type": "text", "text": "What should I do next?" }
+  ]
+}
+```
+
+**✅ Parallel results — one message**
+
+```json
+{
+  "role": "user",
+  "content": [
+    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "15°C" },
+    { "type": "tool_result", "tool_use_id": "toolu_02", "content": "10:30 AM" }
+  ]
+}
+```
+
+**✅ Error result**
+
+```json
+{
+  "role": "user",
+  "content": [
+    {
+      "type": "tool_result",
+      "tool_use_id": "toolu_01",
+      "content": "Timeout",
+      "is_error": true
+    }
+  ]
+}
+```
+
+### Common Errors
+
+| Error                                                             | Fix                                                                      |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `tool_use ids found without tool_result blocks immediately after` | Next message must be a user message with all matching tool_result blocks |
+| `400: text block before tool_result`                              | Reorder content array — tool_result blocks always first                  |
+| Mismatched `tool_use_id`                                          | Copy the exact `id` string from the tool_use block                       |
+| Parallel results split across messages                            | Combine all results into one user message                                |
+
+---
+
+## OpenAI
+
+OpenAI calls this **function calling**. Functions are defined under a `tools` array param but the concept and naming is functions throughout. OpenAI has two APIs with slightly different mechanics.
+
+### Chat Completions API
+
+#### Requirements
+
+1. **Dedicated role** — Each function output is its own message with `role: "tool"` (OpenAI's term for the function result role). No mixing with user content.
+2. **Matching ID** — `tool_call_id` must match the `id` from the assistant's `tool_calls` entry.
+3. **One message per result** — Unlike Claude, parallel function results are appended as **separate** `role: "tool"` messages, one per call.
+4. **No ordering constraint** — Because results are isolated messages, there is no content array ordering issue.
+5. **Void functions** — If the function has no return value (e.g. `send_email`), return a string like `"success"` or `"error"`.
+6. **Append assistant message first** — Before appending function results, append the full assistant response (with `tool_calls`) to the message history.
+
+#### Example
+
+```json
+// 1. Append the assistant response that contained function calls
+{ "role": "assistant", "tool_calls": [...] }
+
+// 2. Append one function result message per call
+{ "role": "tool", "tool_call_id": "call_12345xyz", "content": "15°C" }
+{ "role": "tool", "tool_call_id": "call_67890abc", "content": "10:30 AM" }
+```
+
+---
+
+### Responses API (newer)
+
+#### Requirements
+
+1. **Type field** — Function outputs use `type: "function_call_output"`.
+2. **Matching ID** — `call_id` must match the `call_id` from the `function_call` item in the model's output.
+3. **Append model output first** — Add the full `response.output` array to your input list before appending function outputs.
+4. **One item per result** — One `function_call_output` item per function call.
+5. **Reasoning items** — For reasoning models (GPT-5, o4-mini), any reasoning items in the response output **must also be included** when sending back results.
+
+#### Example
+
+```json
+// 1. Append the model's output (including function_call items)
+{ "type": "function_call", "call_id": "call_12345xyz", "name": "get_weather", "arguments": "..." }
+
+// 2. Append function output
+{ "type": "function_call_output", "call_id": "call_12345xyz", "output": "15°C" }
+```
+
+---
+
+## Side-by-Side Comparison
+
+|                              | Claude                      | OpenAI Chat Completions        | OpenAI Responses API                |
+| ---------------------------- | --------------------------- | ------------------------------ | ----------------------------------- |
+| Naming                       | Tool use                    | Function calling               | Function calling                    |
+| Result container             | `role: "user"` message      | `role: "tool"` message         | `type: "function_call_output"` item |
+| ID field                     | `tool_use_id`               | `tool_call_id`                 | `call_id`                           |
+| Parallel results             | Single user message         | Separate messages per call     | Separate items per call             |
+| Ordering constraint          | Yes — results before text   | No                             | No                                  |
+| Error flag                   | `is_error: true`            | Return error string as content | Return error string as output       |
+| Void functions               | Return empty string or omit | Return `"success"` string      | Return `"success"` string           |
+| Must append model turn first | Yes                         | Yes                            | Yes                                 |
+
+---
+
+_Refs: [Claude — Implement Tool Use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use) · [OpenAI — Function Calling](https://developers.openai.com/api/docs/guides/function-calling)_

From 25025f7bc1decfe60275e5cd574d4b0ce7cb7ec4 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 28 Mar 2026 20:54:30 +0530
Subject: [PATCH 59/72] chore: bump @yourgpt/copilot-sdk version to
 2.1.5-alpha.8

---
 packages/copilot-sdk/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/copilot-sdk/package.json b/packages/copilot-sdk/package.json
index 7d4908a..1d6891d 100644
--- a/packages/copilot-sdk/package.json
+++ b/packages/copilot-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yourgpt/copilot-sdk",
-  "version": "2.1.5-alpha.7",
+  "version": "2.1.5-alpha.8",
   "description": "Copilot SDK for building Production-ready AI Copilots for any product. Connect any LLM, deploy on your infrastructure, own your data.",
   "type": "module",
   "types": "./dist/core/index.d.ts",

From 3eab362ea13d4426e2097849b4d65015327446bd Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 28 Mar 2026 21:20:26 +0530
Subject: [PATCH 60/72] docs: add experimental docs for tool profiles, context
 budget, and tool result truncation

- Mark compaction, deferred-tools, token-tracking pages as Experimental
- Add Tool Profiles section to deferred-tools.mdx
- Add Context Budget Enforcement section to token-tracking.mdx
- Add Tool Result Truncation section to token-tracking.mdx

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/docs/content/docs/context/compaction.mdx |  2 +-
 .../content/docs/context/token-tracking.mdx   | 81 ++++++++++++++++++-
 .../content/docs/tools/deferred-tools.mdx     | 77 +++++++++++++++++-
 3 files changed, 157 insertions(+), 3 deletions(-)

diff --git a/apps/docs/content/docs/context/compaction.mdx b/apps/docs/content/docs/context/compaction.mdx
index d872699..e548058 100644
--- a/apps/docs/content/docs/context/compaction.mdx
+++ b/apps/docs/content/docs/context/compaction.mdx
@@ -7,7 +7,7 @@ import { Callout } from 'fumadocs-ui/components/callout';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 
 <Callout type="warn">
-**Beta** — This feature is in **alpha**. APIs may change before stable release.
+**Experimental** — This feature is under active development. APIs may change before stable release.
 </Callout>
 
 Keep long conversations alive without hitting token limits. The SDK maintains two parallel views of message history — a full display layer for the UI, and a compacted layer sent to the model.
diff --git a/apps/docs/content/docs/context/token-tracking.mdx b/apps/docs/content/docs/context/token-tracking.mdx
index 7e42c80..18a54b1 100644
--- a/apps/docs/content/docs/context/token-tracking.mdx
+++ b/apps/docs/content/docs/context/token-tracking.mdx
@@ -6,7 +6,7 @@ description: Monitor context window usage in real time with useContextStats
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is in **alpha**. APIs may change before stable release.
+**Experimental** — This feature is under active development. APIs may change before stable release.
 </Callout>
 
 Monitor how much of the AI's context window is being used — broken down by message history, system prompt, tools, and injected context.
@@ -105,6 +105,85 @@ useMessageHistory({ tokenEstimation: "accurate" }); // "fast" | "accurate" | "of
 
 ---
 
+## Context Budget Enforcement
+
+<Callout type="warn">
+**Experimental** — APIs may change before stable release.
+</Callout>
+
+Automatically enforce per-bucket token limits so the prompt never overflows. Configured via `optimization.contextBudget` on `<CopilotProvider>`.
+
+```tsx
+<CopilotProvider
+  optimization={{
+    contextBudget: {
+      enabled: true,
+      budget: {
+        contextWindowTokens: 128000,   // Total window size
+        inputHeadroomRatio: 0.75,      // Use 75% for input, reserve rest for output
+        systemPromptShare: 0.15,       // 15% of input budget for system prompt
+        historyShare: 0.50,            // 50% for conversation history
+        toolResultsShare: 0.30,        // 30% for tool results
+        toolDefinitionsShare: 0.05,    // 5% for tool definitions
+      },
+      enforcement: {
+        mode: "truncate",              // "warn" | "truncate" | "error"
+        onBudgetExceeded: (usage) => {
+          console.warn("Budget exceeded", usage.total.percent);
+        },
+      },
+      monitoring: {
+        enabled: true,
+        onUsageUpdate: (usage) => trackMetrics(usage),
+      },
+    },
+  }}
+>
+```
+
+| `enforcement.mode` | Behaviour |
+|--------------------|-----------|
+| `"warn"` | Logs a warning, sends full payload |
+| `"truncate"` | Trims content to fit — history first, then tool results |
+| `"error"` | Throws before sending if budget is exceeded |
+
+---
+
+## Tool Result Truncation
+
+<Callout type="warn">
+**Experimental** — APIs may change before stable release.
+</Callout>
+
+Prevent a single large tool response from consuming the entire context. Configure under `optimization.toolResultConfig`:
+
+```tsx
+<CopilotProvider
+  optimization={{
+    toolResultConfig: {
+      truncation: {
+        enabled: true,
+        strategy: "head-tail",     // Keep first + last chunk, drop middle
+        maxContextShare: 0.3,      // Tool results can use at most 30% of context
+        hardMaxChars: 40000,       // Absolute cap regardless of context size
+        minKeepChars: 2000,        // Always keep at least this much per result
+        preserveErrors: true,      // Never truncate error results
+      },
+    },
+  }}
+>
+```
+
+| `strategy` | Behaviour |
+|------------|-----------|
+| `"head-tail"` | Keeps the beginning and end of the result; drops the middle |
+| `"head"` | Keeps only the beginning |
+| `"tail"` | Keeps only the end |
+
+A truncation notice is appended so the model knows the result was trimmed.
+
+---
+
 ## Example: Context Usage Indicator
 
 ```tsx
diff --git a/apps/docs/content/docs/tools/deferred-tools.mdx b/apps/docs/content/docs/tools/deferred-tools.mdx
index 7828c0e..125fd65 100644
--- a/apps/docs/content/docs/tools/deferred-tools.mdx
+++ b/apps/docs/content/docs/tools/deferred-tools.mdx
@@ -7,7 +7,7 @@ icon: Clock
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="warn">
-**Beta** — This feature is in **alpha**. APIs may change before stable release.
+**Experimental** — This feature is under active development. APIs may change before stable release.
 </Callout>
 
 Large tool registries bloat the LLM request payload and consume valuable context tokens. Mark tools with `deferLoading: true` to exclude them from the default request — they are auto-injected only when the user's query semantically matches the tool.
@@ -94,3 +94,78 @@ interface UseToolConfig<TParams> {
 <Callout type="info">
 Deferred tools are still available to the AI — they're just not included in the initial request payload. When the user's message matches, they're injected automatically before the request is sent.
 </Callout>
+
+---
+
+## Tool Profiles
+
+<Callout type="warn">
+**Experimental** — APIs may change before stable release.
+</Callout>
+
+Group tools into named profiles and activate only the relevant set per use case. Useful when different parts of your app need different tool subsets.
+
+Tag tools with the profiles they belong to:
+
+```typescript
+useTool({
+  name: "run_migration",
+  description: "Run a database migration",
+  profiles: ["admin"],        // Only active when "admin" profile is selected
+  inputSchema: z.object({ migrationId: z.string() }),
+  handler: async ({ migrationId }) => runMigration(migrationId),
+});
+
+useTool({
+  name: "search_docs",
+  description: "Search documentation",
+  profiles: ["support", "default"],
+  inputSchema: z.object({ query: z.string() }),
+  handler: async ({ query }) => searchDocs(query),
+});
+```
+
+Configure profiles on `<CopilotProvider>`:
+
+```tsx
+<CopilotProvider
+  optimization={{
+    toolProfiles: {
+      enabled: true,
+      defaultProfile: "default",
+      includeUnprofiled: true,      // Tools with no profiles[] are always included
+      profiles: {
+        admin: {
+          include: ["run_migration", "manage_users"],
+        },
+        support: {
+          include: ["search_docs", "get_ticket"],
+          exclude: ["run_migration"],
+        },
+      },
+    },
+  }}
+>
+```
+
+Switch the active profile at runtime:
+
+```typescript
+// Switch to admin tools when user elevates privileges
+chat.setOptimizationConfig({
+  toolProfiles: { defaultProfile: "admin" },
+});
+```
+
+### `ToolProfileConfig` reference
+
+```typescript
+interface ToolProfileConfig {
+  enabled?: boolean;
+  defaultProfile?: string;
+  profiles?: Record<string, {
+    include?: string[];    // Tool names to include
+    exclude?: string[];    // Tool names to exclude
+  }>;
+  includeUnprofiled?: boolean;   // default: true — tools with no profiles[] always load
+}

From 82d1fbfc15cf73bf513b2431dca4d15df34449ec Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 28 Mar 2026 21:40:24 +0530
Subject: [PATCH 61/72] feat(examples): add generative-ui-demo and skills-demo
 as standalone Vite 8 examples

- generative-ui-demo: port of experimental generative UI to Vite+Express, recharts, dark UI with prompt suggestions sidebar
- skills-demo: new demo for server-side skills system with loadSkills(), 3 skill files (code-review/concise-mode/customer-support), branching toggle via allowEdit prop

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/generative-ui-demo/.env.example      |   3 +
 examples/generative-ui-demo/index.html        |  12 +
 examples/generative-ui-demo/package.json      |  38 +++
 .../generative-ui-demo/postcss.config.mjs     |   5 +
 examples/generative-ui-demo/server/index.ts   | 109 +++++++
 examples/generative-ui-demo/src/App.tsx       | 201 ++++++++++++
 .../generative-ui-demo/src/ChartRenderer.tsx  | 176 +++++++++++
 examples/generative-ui-demo/src/index.css     |   1 +
 examples/generative-ui-demo/src/main.tsx      |  10 +
 examples/generative-ui-demo/tsconfig.app.json |  22 ++
 examples/generative-ui-demo/tsconfig.json     |   7 +
 .../generative-ui-demo/tsconfig.node.json     |  15 +
 examples/generative-ui-demo/vite.config.ts    |  18 ++
 examples/skills-demo/.env.example             |   3 +
 examples/skills-demo/index.html               |  13 +
 examples/skills-demo/package.json             |  38 +++
 examples/skills-demo/postcss.config.mjs       |   5 +
 examples/skills-demo/server/index.ts          | 149 +++++++++
 examples/skills-demo/src/App.tsx              | 295 ++++++++++++++++++
 examples/skills-demo/src/index.css            |   1 +
 examples/skills-demo/src/main.tsx             |  10 +
 examples/skills-demo/tsconfig.json            |  22 ++
 examples/skills-demo/tsconfig.node.json       |  15 +
 examples/skills-demo/vite.config.ts           |  18 ++
 24 files changed, 1186 insertions(+)
 create mode 100644 examples/generative-ui-demo/.env.example
 create mode 100644 examples/generative-ui-demo/index.html
 create mode 100644 examples/generative-ui-demo/package.json
 create mode 100644 examples/generative-ui-demo/postcss.config.mjs
 create mode 100644 examples/generative-ui-demo/server/index.ts
 create mode 100644 examples/generative-ui-demo/src/App.tsx
 create mode 100644 examples/generative-ui-demo/src/ChartRenderer.tsx
 create mode 100644 examples/generative-ui-demo/src/index.css
 create mode 100644 examples/generative-ui-demo/src/main.tsx
 create mode 100644 examples/generative-ui-demo/tsconfig.app.json
 create mode 100644 examples/generative-ui-demo/tsconfig.json
 create mode 100644 examples/generative-ui-demo/tsconfig.node.json
 create mode 100644 examples/generative-ui-demo/vite.config.ts
 create mode 100644 examples/skills-demo/.env.example
 create mode 100644 examples/skills-demo/index.html
 create mode 100644 examples/skills-demo/package.json
 create mode 100644 examples/skills-demo/postcss.config.mjs
 create mode 100644 examples/skills-demo/server/index.ts
 create mode 100644 examples/skills-demo/src/App.tsx
 create mode 100644 examples/skills-demo/src/index.css
 create mode 100644 examples/skills-demo/src/main.tsx
 create mode 100644 examples/skills-demo/tsconfig.json
 create mode 100644 examples/skills-demo/tsconfig.node.json
 create mode 100644 examples/skills-demo/vite.config.ts

diff --git a/examples/generative-ui-demo/.env.example b/examples/generative-ui-demo/.env.example
new file mode 100644
index 0000000..afe6c89
--- /dev/null
+++ b/examples/generative-ui-demo/.env.example
@@ -0,0 +1,3 @@
+ANTHROPIC_API_KEY=sk-ant-...
+# or
+OPENAI_API_KEY=sk-...
diff --git a/examples/generative-ui-demo/index.html b/examples/generative-ui-demo/index.html
new file mode 100644
index 0000000..163a1d2
--- /dev/null
+++ b/examples/generative-ui-demo/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Generative UI Demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/examples/generative-ui-demo/package.json b/examples/generative-ui-demo/package.json
new file mode 100644
index 0000000..988bfca
--- /dev/null
+++ b/examples/generative-ui-demo/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "generative-ui-demo",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently \"pnpm dev:server\" \"pnpm dev:client\"",
+    "dev:client": "vite --port 3031",
+    "dev:server": "tsx watch server/index.ts",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@yourgpt/copilot-sdk": "workspace:*",
+    "@yourgpt/llm-sdk": "workspace:*",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0",
+    "lucide-react": "^0.563.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "recharts": "^2.13.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "6.0.1",
+    "concurrently": "^9.0.0",
+    "tailwindcss": "^4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vite": "8.0.3"
+  }
+}
diff --git a/examples/generative-ui-demo/postcss.config.mjs b/examples/generative-ui-demo/postcss.config.mjs
new file mode 100644
index 0000000..a7f73a2
--- /dev/null
+++ b/examples/generative-ui-demo/postcss.config.mjs
@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
diff --git a/examples/generative-ui-demo/server/index.ts b/examples/generative-ui-demo/server/index.ts
new file mode 100644
index 0000000..134e8c9
--- /dev/null
+++ b/examples/generative-ui-demo/server/index.ts
@@ -0,0 +1,109 @@
+import "dotenv/config";
+import express from "express";
+import cors from "cors";
+import { createRuntime } from "@yourgpt/llm-sdk";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
+import { createOpenAI } from "@yourgpt/llm-sdk/openai";
+
+function resolveProvider() {
+  if (process.env.ANTHROPIC_API_KEY) {
+    return {
+      provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+      model: "claude-haiku-4-5",
+      providerName: "Anthropic",
+    };
+  }
+  if (process.env.OPENAI_API_KEY) {
+    return {
+      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+      model: "gpt-4o-mini",
+      providerName: "OpenAI",
+    };
+  }
+  throw new Error(
+    "Set ANTHROPIC_API_KEY or OPENAI_API_KEY to run the generative UI demo.",
+  );
+}
+
+const { provider, model, providerName } = resolveProvider();
+
+const runtime = createRuntime({
+  provider,
+  model,
+  systemPrompt: `You are a data-rich assistant that always renders visual UI components instead of plain text.
+
+You have a render_ui tool. Use it proactively based on the request:
+
+- "table" — any list of items, comparisons, records
+- "stat"  — numbers, KPIs, metrics with deltas
+- "card"  — single entity details (person, product, place)
+- "chart" — trends and distributions (bar, line, pie, area, scatter)
+- "html"  — rich, fully custom layouts (see below)
+
+━━━ HTML TYPE CAPABILITIES ━━━
+The html iframe has TWO libraries pre-loaded:
+1. Tailwind CSS (Play CDN) — use any utility class freely
+2. Chart.js — create inline charts with <canvas> + new Chart(...)
+
+Design in a shadcn/ui style:
+- Cards:    bg-white rounded-xl border border-gray-200 shadow-sm p-6
+- Headings: text-gray-900 font-semibold text-lg
+- Muted:    text-gray-500 text-sm
+- Badges:   bg-blue-50 text-blue-700 px-2.5 py-0.5 rounded-full text-xs font-medium
+- Buttons:  bg-gray-900 text-white rounded-lg px-4 py-2 text-sm font-medium hover:bg-gray-700
+- Grid:     grid grid-cols-3 gap-4 (or 2-col for cards)
+- Dividers: border-t border-gray-100 mt-4 pt-4
+
+Chart.js usage in html — inline script after canvas:
+<canvas id="c" height="220"></canvas>
+<script>
+new Chart(document.getElementById('c'), {
+  type: 'bar', // bar | line | pie | doughnut | radar | polarArea
+  data: {
+    labels: ['Jan','Feb','Mar'],
+    datasets: [{ label: 'Revenue', data: [120,190,170], backgroundColor: '#6366f1' }]
+  },
+  options: { responsive: true, plugins: { legend: { position: 'top' } } }
+});
+</script>
+
+Use html when asked for dashboards, interactive layouts, shadcn-style components, or anything combining charts + stats + cards in one view.
+For html, set the "height" field to fit the content — e.g. "600px" for dashboards, "320px" for a small card.
+Always prefer a structured type (table, stat, card) over html when the data fits a single type.`,
+  maxIterations: 3,
+});
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+app.get("/api/chat", (_req, res) => {
+  res.json({
+    status: "ok",
+    provider: providerName,
+    model,
+    demo: "generative-ui",
+  });
+});
+
+app.post("/api/chat", async (req, res) => {
+  const PORT_NUM = process.env.PORT || 3030;
+  const url = `http://localhost:${PORT_NUM}/api/chat`;
+  const webReq = new Request(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(req.body),
+  });
+  const response = await runtime.handleRequest(webReq);
+  res.status(response.status);
+  response.headers.forEach((val, key) => res.setHeader(key, val));
+  const body = await response.text();
+  res.send(body);
+});
+
+const PORT = process.env.PORT ? Number(process.env.PORT) : 3030;
+app.listen(PORT, () =>
+  console.log(
+    `Generative UI server running on http://localhost:${PORT} (${providerName} / ${model})`,
+  ),
+);
diff --git a/examples/generative-ui-demo/src/App.tsx b/examples/generative-ui-demo/src/App.tsx
new file mode 100644
index 0000000..6e47cdb
--- /dev/null
+++ b/examples/generative-ui-demo/src/App.tsx
@@ -0,0 +1,201 @@
+import { CopilotProvider } from "@yourgpt/copilot-sdk/react";
+import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
+import { useGenerativeUI } from "@yourgpt/copilot-sdk/experimental";
+import { ChartRenderer } from "./ChartRenderer";
+import "@yourgpt/copilot-sdk/ui/styles.css";
+
+const PROMPT_SUGGESTIONS = [
+  "Build a shadcn-style analytics dashboard with a Chart.js bar chart of monthly revenue and 3 KPI stat cards",
+  "Show a shadcn card grid of the top 5 programming languages with usage %, trend badge, and color",
+  "Render a Chart.js doughnut chart of browser market share with a legend",
+  "Give me a stat dashboard of key web metrics",
+  "Show me a table of the top 10 S&P 500 companies by market cap",
+  "Create a card for Elon Musk with key facts",
+  "Build a shadcn pricing page with 3 tiers, feature lists, and a highlighted popular plan",
+  "Show a line chart of BTC price over the last 6 months",
+  "Render a Chart.js radar chart comparing React, Vue, Angular, and Svelte across 5 metrics",
+];
+
+function GenerativeUIChatInner() {
+  useGenerativeUI({
+    name: "render_ui",
+    chartRenderer: ChartRenderer,
+  });
+
+  return (
+    <CopilotChat
+      className="h-full"
+      placeholder="Ask for data, stats, charts, cards…"
+      showHeader
+      header={{ name: "Generative UI" }}
+      loaderVariant="wave"
+      showUserAvatar
+    />
+  );
+}
+
+export default function App() {
+  return (
+    <>
+      <style>{`
+        .gui-root {
+          background-color: #080b12;
+          background-image:
+            radial-gradient(ellipse 80% 50% at 10% -10%, rgba(16,185,129,0.08) 0%, transparent 55%),
+            radial-gradient(ellipse 70% 45% at 90% 110%, rgba(59,130,246,0.07) 0%, transparent 55%);
+          font-family: system-ui, -apple-system, sans-serif;
+        }
+        .gui-accent-line {
+          height: 3px;
+          background: linear-gradient(90deg,
+            transparent 0%,
+            rgba(16,185,129,0.35) 20%,
+            rgba(52,211,153,0.65) 50%,
+            rgba(59,130,246,0.4) 80%,
+            transparent 100%);
+          flex-shrink: 0;
+        }
+        .gui-header {
+          background: rgba(8,11,18,0.85);
+          backdrop-filter: blur(16px);
+          border-bottom: 1px solid rgba(255,255,255,0.055);
+          flex-shrink: 0;
+        }
+        .gui-divider {
+          width: 1px;
+          height: 16px;
+          background: rgba(255,255,255,0.08);
+          flex-shrink: 0;
+        }
+        .gui-badge {
+          font-size: 10px;
+          font-weight: 600;
+          padding: 2px 8px;
+          border-radius: 999px;
+          background: rgba(16,185,129,0.1);
+          border: 1px solid rgba(16,185,129,0.25);
+          color: #34d399;
+          letter-spacing: 0.04em;
+          text-transform: uppercase;
+        }
+        .gui-sidebar {
+          width: 256px;
+          flex-shrink: 0;
+          background: rgba(255,255,255,0.015);
+          border-right: 1px solid rgba(255,255,255,0.055);
+          display: flex;
+          flex-direction: column;
+          gap: 0;
+          overflow-y: auto;
+        }
+        .gui-sidebar-title {
+          font-size: 10px;
+          font-weight: 600;
+          letter-spacing: 0.08em;
+          text-transform: uppercase;
+          color: #334155;
+          padding: 16px 16px 8px;
+        }
+        .gui-prompt-btn {
+          width: 100%;
+          text-align: left;
+          padding: 9px 16px;
+          font-size: 12px;
+          color: #64748b;
+          background: transparent;
+          border: none;
+          cursor: pointer;
+          border-bottom: 1px solid rgba(255,255,255,0.03);
+          transition: background 0.1s, color 0.1s;
+          line-height: 1.4;
+        }
+        .gui-prompt-btn:hover {
+          background: rgba(255,255,255,0.03);
+          color: #94a3b8;
+        }
+      `}</style>
+
+      <div className="gui-root h-screen flex flex-col">
+        <div className="gui-accent-line" />
+
+        {/* Header */}
+        <header className="gui-header flex items-center gap-3.5 px-5 py-3">
+          <div className="flex items-center gap-2.5">
+            <svg
+              width="15"
+              height="15"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="#34d399"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <rect x="3" y="3" width="7" height="7" rx="1" />
+              <rect x="14" y="3" width="7" height="7" rx="1" />
+              <rect x="3" y="14" width="7" height="7" rx="1" />
+              <rect x="14" y="14" width="7" height="7" rx="1" />
+            </svg>
+            <span
+              style={{
+                fontWeight: 700,
+                fontSize: 14,
+                letterSpacing: "-0.02em",
+                color: "#e2e8f0",
+              }}
+            >
+              Generative UI
+            </span>
+          </div>
+
+          <span className="gui-badge ml-1">Experimental</span>
+
+          <div className="ml-auto" style={{ fontSize: 11, color: "#334155" }}>
+            Tables · Stats · Cards · Charts · HTML
+          </div>
+        </header>
+
+        {/* Two-panel layout */}
+        <div className="flex-1 flex min-h-0">
+          <CopilotProvider runtimeUrl="/api/chat">
+            {/* Left: Prompt suggestions */}
+            <div className="gui-sidebar hidden lg:flex flex-col">
+              <p className="gui-sidebar-title">Try asking…</p>
+              {PROMPT_SUGGESTIONS.map((prompt) => (
+                <button
+                  key={prompt}
+                  className="gui-prompt-btn"
+                  onClick={() => {
+                    // Find the CopilotChat input and populate it
+                    const input = document.querySelector<HTMLTextAreaElement>(
+                      "textarea[placeholder]",
+                    );
+                    if (input) {
+                      const nativeInputValueSetter =
+                        Object.getOwnPropertyDescriptor(
+                          window.HTMLTextAreaElement.prototype,
+                          "value",
+                        )?.set;
+                      nativeInputValueSetter?.call(input, prompt);
+                      input.dispatchEvent(
+                        new Event("input", { bubbles: true }),
+                      );
+                      input.focus();
+                    }
+                  }}
+                >
+                  {prompt}
+                </button>
+              ))}
+            </div>
+
+            {/* Right: Chat */}
+            <div className="flex-1 min-w-0">
+              <GenerativeUIChatInner />
+            </div>
+          </CopilotProvider>
+        </div>
+      </div>
+    </>
+  );
+}
diff --git a/examples/generative-ui-demo/src/ChartRenderer.tsx b/examples/generative-ui-demo/src/ChartRenderer.tsx
new file mode 100644
index 0000000..1b810be
--- /dev/null
+++ b/examples/generative-ui-demo/src/ChartRenderer.tsx
@@ -0,0 +1,176 @@
+import {
+  BarChart,
+  Bar,
+  LineChart,
+  Line,
+  PieChart,
+  Pie,
+  Cell,
+  AreaChart,
+  Area,
+  ScatterChart,
+  Scatter,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+} from "recharts";
+import type { ChartRendererProps } from "@yourgpt/copilot-sdk/experimental";
+
+const COLORS = ["#6366f1", "#10b981", "#f59e0b", "#3b82f6", "#8b5cf6"];
+
+// Reshape datasets + labels → recharts data format
+function toRechartsData(
+  labels: string[],
+  datasets: { label: string; data: number[] }[],
+) {
+  return labels.map((label, i) => {
+    const point: Record<string, string | number> = { name: label };
+    for (const ds of datasets) {
+      point[ds.label] = ds.data[i] ?? 0;
+    }
+    return point;
+  });
+}
+
+export function ChartRenderer({ payload }: ChartRendererProps) {
+  const { chartType, labels, datasets, title, xLabel, yLabel } = payload;
+  const data = toRechartsData(labels, datasets);
+  const dataKeys = datasets.map((ds) => ds.label);
+
+  return (
+    <div className="rounded-lg border border-border bg-card p-4">
+      {title && (
+        <p className="mb-3 text-sm font-semibold text-foreground">{title}</p>
+      )}
+      <ResponsiveContainer width="100%" height={220}>
+        {chartType === "pie" ? (
+          <PieChart>
+            <Pie
+              data={data.map((d) => ({
+                name: d.name,
+                value: Number(d[dataKeys[0]] ?? 0),
+              }))}
+              dataKey="value"
+              nameKey="name"
+              cx="50%"
+              cy="50%"
+              outerRadius={80}
+              label={({ name, percent }) =>
+                `${name} ${(percent * 100).toFixed(0)}%`
+              }
+            >
+              {data.map((_, i) => (
+                <Cell key={i} fill={COLORS[i % COLORS.length]} />
+              ))}
+            </Pie>
+            <Tooltip />
+            <Legend />
+          </PieChart>
+        ) : chartType === "line" ? (
+          <LineChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" className="stroke-border" />
+            <XAxis
+              dataKey="name"
+              tick={{ fontSize: 11 }}
+              label={
+                xLabel
+                  ? { value: xLabel, position: "insideBottom", offset: -5 }
+                  : undefined
+              }
+            />
+            <YAxis
+              tick={{ fontSize: 11 }}
+              label={
+                yLabel
+                  ? { value: yLabel, angle: -90, position: "insideLeft" }
+                  : undefined
+              }
+            />
+            <Tooltip />
+            {dataKeys.length > 1 && <Legend />}
+            {dataKeys.map((key, i) => (
+              <Line
+                key={key}
+                type="monotone"
+                dataKey={key}
+                stroke={COLORS[i % COLORS.length]}
+                strokeWidth={2}
+                dot={false}
+              />
+            ))}
+          </LineChart>
+        ) : chartType === "area" ? (
+          <AreaChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" className="stroke-border" />
+            <XAxis dataKey="name" tick={{ fontSize: 11 }} />
+            <YAxis tick={{ fontSize: 11 }} />
+            <Tooltip />
+            {dataKeys.length > 1 && <Legend />}
+            {dataKeys.map((key, i) => (
+              <Area
+                key={key}
+                type="monotone"
+                dataKey={key}
+                stroke={COLORS[i % COLORS.length]}
+                fill={COLORS[i % COLORS.length]}
+                fillOpacity={0.15}
+                strokeWidth={2}
+              />
+            ))}
+          </AreaChart>
+        ) : chartType === "scatter" ? (
+          <ScatterChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" className="stroke-border" />
+            <XAxis
+              dataKey={dataKeys[0]}
+              tick={{ fontSize: 11 }}
+              name={dataKeys[0]}
+            />
+            <YAxis
+              dataKey={dataKeys[1] ?? dataKeys[0]}
+              tick={{ fontSize: 11 }}
+              name={dataKeys[1] ?? dataKeys[0]}
+            />
+            <Tooltip cursor={{ strokeDasharray: "3 3" }} />
+            <Scatter data={data} fill={COLORS[0]} />
+          </ScatterChart>
+        ) : (
+          // Default: bar
+          <BarChart data={data}>
+            <CartesianGrid strokeDasharray="3 3" className="stroke-border" />
+            <XAxis
+              dataKey="name"
+              tick={{ fontSize: 11 }}
+              label={
+                xLabel
+                  ? { value: xLabel, position: "insideBottom", offset: -5 }
+                  : undefined
+              }
+            />
+            <YAxis
+              tick={{ fontSize: 11 }}
+              label={
+                yLabel
+                  ? { value: yLabel, angle: -90, position: "insideLeft" }
+                  : undefined
+              }
+            />
+            <Tooltip />
+            {dataKeys.length > 1 && <Legend />}
+            {dataKeys.map((key, i) => (
+              <Bar
+                key={key}
+                dataKey={key}
+                fill={COLORS[i % COLORS.length]}
+                radius={[3, 3, 0, 0]}
+              />
+            ))}
+          </BarChart>
+        )}
+      </ResponsiveContainer>
+    </div>
+  );
+}
diff --git a/examples/generative-ui-demo/src/index.css b/examples/generative-ui-demo/src/index.css
new file mode 100644
index 0000000..f1d8c73
--- /dev/null
+++ b/examples/generative-ui-demo/src/index.css
@@ -0,0 +1 @@
+@import "tailwindcss";
diff --git a/examples/generative-ui-demo/src/main.tsx b/examples/generative-ui-demo/src/main.tsx
new file mode 100644
index 0000000..15753af
--- /dev/null
+++ b/examples/generative-ui-demo/src/main.tsx
@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
diff --git a/examples/generative-ui-demo/tsconfig.app.json b/examples/generative-ui-demo/tsconfig.app.json
new file mode 100644
index 0000000..4d0f4fb
--- /dev/null
+++ b/examples/generative-ui-demo/tsconfig.app.json
@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"]
+}
diff --git a/examples/generative-ui-demo/tsconfig.json b/examples/generative-ui-demo/tsconfig.json
new file mode 100644
index 0000000..1ffef60
--- /dev/null
+++ b/examples/generative-ui-demo/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
diff --git a/examples/generative-ui-demo/tsconfig.node.json b/examples/generative-ui-demo/tsconfig.node.json
new file mode 100644
index 0000000..1f27c41
--- /dev/null
+++ b/examples/generative-ui-demo/tsconfig.node.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true
+  },
+  "include": ["vite.config.ts", "server"]
+}
diff --git a/examples/generative-ui-demo/vite.config.ts b/examples/generative-ui-demo/vite.config.ts
new file mode 100644
index 0000000..940d76f
--- /dev/null
+++ b/examples/generative-ui-demo/vite.config.ts
@@ -0,0 +1,18 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "path";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  server: {
+    port: 3031,
+    proxy: {
+      "/api": "http://localhost:3030",
+    },
+  },
+});
diff --git a/examples/skills-demo/.env.example b/examples/skills-demo/.env.example
new file mode 100644
index 0000000..afe6c89
--- /dev/null
+++ b/examples/skills-demo/.env.example
@@ -0,0 +1,3 @@
+ANTHROPIC_API_KEY=sk-ant-...
+# or
+OPENAI_API_KEY=sk-...
diff --git a/examples/skills-demo/index.html b/examples/skills-demo/index.html
new file mode 100644
index 0000000..5208e48
--- /dev/null
+++ b/examples/skills-demo/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Skills Demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/examples/skills-demo/package.json b/examples/skills-demo/package.json
new file mode 100644
index 0000000..da1ec08
--- /dev/null
+++ b/examples/skills-demo/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "skills-demo",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently \"pnpm dev:server\" \"pnpm dev:client\"",
+    "dev:client": "vite --port 3033",
+    "dev:server": "tsx watch server/index.ts",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@yourgpt/copilot-sdk": "workspace:*",
+    "@yourgpt/llm-sdk": "workspace:*",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0",
+    "lucide-react": "^0.563.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "6.0.1",
+    "concurrently": "^9.0.0",
+    "path": "^0.12.7",
+    "tailwindcss": "^4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vite": "8.0.3"
+  }
+}
diff --git a/examples/skills-demo/postcss.config.mjs b/examples/skills-demo/postcss.config.mjs
new file mode 100644
index 0000000..a7f73a2
--- /dev/null
+++ b/examples/skills-demo/postcss.config.mjs
@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
diff --git a/examples/skills-demo/server/index.ts b/examples/skills-demo/server/index.ts
new file mode 100644
index 0000000..0a12863
--- /dev/null
+++ b/examples/skills-demo/server/index.ts
@@ -0,0 +1,149 @@
+import "dotenv/config";
+import express from "express";
+import cors from "cors";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createRuntime } from "@yourgpt/llm-sdk";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
+import { createOpenAI } from "@yourgpt/llm-sdk/openai";
+import { loadSkills } from "@yourgpt/copilot-sdk/server";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const app = express();
+app.use(cors());
+app.use(express.json({ limit: "10mb" }));
+
+// ============================================
+// LOAD SKILLS FROM /skills DIRECTORY
+// ============================================
+
+const { skills, buildSystemPrompt, tools } = await loadSkills({
+  dir: path.join(__dirname, "../skills"),
+});
+
+console.log(`\nLoaded ${skills.length} skill(s):`);
+for (const skill of skills) {
+  console.log(
+    `  - ${skill.name} [${skill.strategy ?? "auto"}]: ${skill.description}`,
+  );
+}
+
+// ============================================
+// CREATE PROVIDERS
+// ============================================
+
+const anthropic = createAnthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const provider = process.env.ANTHROPIC_API_KEY ? anthropic : openai;
+const model = process.env.ANTHROPIC_API_KEY
+  ? "claude-haiku-4-5"
+  : "gpt-4o-mini";
+
+console.log(
+  `\nUsing provider: ${process.env.ANTHROPIC_API_KEY ? "Anthropic" : "OpenAI"}`,
+);
+console.log(`Using model: ${model}`);
+
+// ============================================
+// CREATE RUNTIME WITH SKILL TOOL
+// ============================================
+
+const systemPrompt = buildSystemPrompt(
+  "You are a helpful assistant. Use available skills to tailor your responses.",
+);
+
+const runtime = createRuntime({
+  provider,
+  model,
+  systemPrompt,
+  debug: true,
+});
+
+// Register the load_skill tool with the runtime
+runtime.registerTool({
+  name: "load_skill",
+  description: tools.load_skill.description,
+  location: "server",
+  inputSchema: tools.load_skill.parameters,
+  handler: async (params: { name: string }) => {
+    return tools.load_skill.execute(params);
+  },
+});
+
+// ============================================
+// ROUTES
+// ============================================
+
+/**
+ * POST /api/chat — Main chat endpoint for CopilotProvider
+ */
+app.post("/api/chat", async (req, res) => {
+  const url = `http://localhost:${PORT}/api/chat`;
+  const webReq = new Request(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(req.body),
+  });
+  const response = await runtime.handleRequest(webReq);
+  res.status(response.status);
+  response.headers.forEach((val, key) => res.setHeader(key, val));
+  const body = await response.text();
+  res.send(body);
+});
+
+/**
+ * GET /api/skills — Returns skill metadata for the UI sidebar
+ */
+app.get("/api/skills", (_req, res) => {
+  const skillList = skills.map((skill) => ({
+    name: skill.name,
+    description: skill.description,
+    strategy: skill.strategy ?? "auto",
+    version: skill.version,
+  }));
+  res.json(skillList);
+});
+
+/**
+ * GET /api/health — Health check
+ */
+app.get("/api/health", (_req, res) => {
+  res.json({
+    status: "ok",
+    provider: process.env.ANTHROPIC_API_KEY ? "anthropic" : "openai",
+    model,
+    skillCount: skills.length,
+  });
+});
+
+// ============================================
+// SERVER START
+// ============================================
+
+const PORT = parseInt(process.env.PORT ?? "3032", 10);
+
+app.listen(PORT, () => {
+  console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║              Skills Demo — Express Server                     ║
+╠══════════════════════════════════════════════════════════════╣
+║  Server:   http://localhost:${PORT}                              ║
+║  Provider: ${(process.env.ANTHROPIC_API_KEY ? "Anthropic" : "OpenAI").padEnd(47)}║
+║  Model:    ${model.padEnd(47)}║
+║  Skills:   ${String(skills.length).padEnd(47)}║
+╚══════════════════════════════════════════════════════════════╝
+
+Endpoints:
+  POST /api/chat    — CopilotProvider chat endpoint
+  GET  /api/skills  — Skill metadata for the UI
+  GET  /api/health  — Health check
+`);
+});
diff --git a/examples/skills-demo/src/App.tsx b/examples/skills-demo/src/App.tsx
new file mode 100644
index 0000000..68d9b5b
--- /dev/null
+++ b/examples/skills-demo/src/App.tsx
@@ -0,0 +1,295 @@
+import { useState, useEffect } from "react";
+import { GitBranch, Zap, Bot, ChevronRight } from "lucide-react";
+import { CopilotProvider, CopilotChat } from "@yourgpt/copilot-sdk/ui";
+import "@yourgpt/copilot-sdk/ui/styles.css";
+
+// ============================================
+// Types
+// ============================================
+
+interface SkillInfo {
+  name: string;
+  description: string;
+  strategy: "eager" | "auto" | "manual";
+  version?: string;
+}
+
+// ============================================
+// Helpers
+// ============================================
+
+function formatSkillName(name: string): string {
+  return name
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+function StrategyBadge({ strategy }: { strategy: SkillInfo["strategy"] }) {
+  const config: Record<
+    SkillInfo["strategy"],
+    { label: string; className: string }
+  > = {
+    eager: {
+      label: "eager",
+      className:
+        "bg-emerald-500/15 text-emerald-400 border border-emerald-500/25",
+    },
+    auto: {
+      label: "auto",
+      className: "bg-blue-500/15 text-blue-400 border border-blue-500/25",
+    },
+    manual: {
+      label: "manual",
+      className: "bg-amber-500/15 text-amber-400 border border-amber-500/25",
+    },
+  };
+
+  const { label, className } = config[strategy];
+
+  return (
+    <span
+      className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${className}`}
+    >
+      {label}
+    </span>
+  );
+}
+
+// ============================================
+// Toggle Switch
+// ============================================
+
+function ToggleSwitch({
+  checked,
+  onChange,
+  id,
+}: {
+  checked: boolean;
+  onChange: (v: boolean) => void;
+  id: string;
+}) {
+  return (
+    <button
+      id={id}
+      role="switch"
+      aria-checked={checked}
+      onClick={() => onChange(!checked)}
+      className={`relative inline-flex h-5 w-9 flex-shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-200 ease-in-out focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-zinc-900 ${
+        checked ? "bg-blue-500" : "bg-zinc-700"
+      }`}
+    >
+      <span
+        className={`pointer-events-none inline-block h-4 w-4 transform rounded-full bg-white shadow ring-0 transition duration-200 ease-in-out ${
+          checked ? "translate-x-4" : "translate-x-0"
+        }`}
+      />
+    </button>
+  );
+}
+
+// ============================================
+// Skill Card
+// ============================================
+
+function SkillCard({ skill }: { skill: SkillInfo }) {
+  return (
+    <div className="group rounded-lg border border-zinc-800 bg-zinc-900/50 p-3 transition-colors hover:border-zinc-700 hover:bg-zinc-900">
+      <div className="flex items-start justify-between gap-2">
+        <span className="text-sm font-medium text-zinc-100 leading-tight">
+          {formatSkillName(skill.name)}
+        </span>
+        <StrategyBadge strategy={skill.strategy} />
+      </div>
+      <p className="mt-1.5 text-xs text-zinc-500 leading-relaxed line-clamp-2">
+        {skill.description}
+      </p>
+    </div>
+  );
+}
+
+// ============================================
+// Sidebar
+// ============================================
+
+function Sidebar({
+  branchingEnabled,
+  onBranchingChange,
+}: {
+  branchingEnabled: boolean;
+  onBranchingChange: (v: boolean) => void;
+}) {
+  const [skills, setSkills] = useState<SkillInfo[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetch("/api/skills")
+      .then((res) => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json() as Promise<SkillInfo[]>;
+      })
+      .then((data) => {
+        setSkills(data);
+        setLoading(false);
+      })
+      .catch((err: unknown) => {
+        setError(err instanceof Error ? err.message : "Failed to load skills");
+        setLoading(false);
+      });
+  }, []);
+
+  return (
+    <aside className="flex h-full w-[280px] flex-shrink-0 flex-col border-r border-zinc-800 bg-zinc-900">
+      {/* Header */}
+      <div className="border-b border-zinc-800 px-4 py-4">
+        <div className="flex items-center gap-2.5">
+          <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-blue-500/15 border border-blue-500/25">
+            <Zap className="h-4 w-4 text-blue-400" />
+          </div>
+          <div>
+            <h1 className="text-sm font-semibold text-zinc-100">Skills Demo</h1>
+            <p className="text-xs text-zinc-500">
+              Server-side skill management
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {/* Skills section */}
+      <div className="flex-1 overflow-y-auto px-3 py-4">
+        <div className="mb-3 flex items-center gap-1.5 px-1">
+          <Bot className="h-3.5 w-3.5 text-zinc-500" />
+          <span className="text-xs font-medium uppercase tracking-wider text-zinc-500">
+            Available Skills
+          </span>
+        </div>
+
+        {loading && (
+          <div className="space-y-2">
+            {[1, 2, 3].map((i) => (
+              <div
+                key={i}
+                className="h-16 rounded-lg border border-zinc-800 bg-zinc-900/50 animate-pulse"
+              />
+            ))}
+          </div>
+        )}
+
+        {error && (
+          <div className="rounded-lg border border-red-500/25 bg-red-500/10 px-3 py-2.5">
+            <p className="text-xs text-red-400">
+              Failed to load skills — is the server running?
+            </p>
+            <p className="mt-0.5 text-xs text-red-500/70">{error}</p>
+          </div>
+        )}
+
+        {!loading && !error && skills.length === 0 && (
+          <p className="px-1 text-xs text-zinc-600">No skills found.</p>
+        )}
+
+        {!loading && !error && skills.length > 0 && (
+          <div className="space-y-2">
+            {skills.map((skill) => (
+              <SkillCard key={skill.name} skill={skill} />
+            ))}
+          </div>
+        )}
+
+        {/* Strategy legend */}
+        {!loading && !error && skills.length > 0 && (
+          <div className="mt-4 rounded-lg border border-zinc-800 bg-zinc-950/50 px-3 py-2.5">
+            <p className="mb-2 text-xs font-medium text-zinc-500">
+              Strategy legend
+            </p>
+            <div className="space-y-1.5">
+              <div className="flex items-center gap-2">
+                <StrategyBadge strategy="eager" />
+                <span className="text-xs text-zinc-500">Always injected</span>
+              </div>
+              <div className="flex items-center gap-2">
+                <StrategyBadge strategy="auto" />
+                <span className="text-xs text-zinc-500">
+                  AI decides when to load
+                </span>
+              </div>
+              <div className="flex items-center gap-2">
+                <StrategyBadge strategy="manual" />
+                <span className="text-xs text-zinc-500">
+                  Explicit invocation only
+                </span>
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+
+      {/* Branching section */}
+      <div className="border-t border-zinc-800 px-3 py-4">
+        <div className="mb-2 flex items-center gap-1.5 px-1">
+          <GitBranch className="h-3.5 w-3.5 text-zinc-500" />
+          <span className="text-xs font-medium uppercase tracking-wider text-zinc-500">
+            Branching
+          </span>
+        </div>
+        <div className="rounded-lg border border-zinc-800 bg-zinc-950/50 px-3 py-3">
+          <div className="flex items-center justify-between gap-3">
+            <label htmlFor="branching-toggle" className="flex-1 cursor-pointer">
+              <span className="block text-sm font-medium text-zinc-200">
+                Conversation Branching
+              </span>
+              <span className="block text-xs text-zinc-500 mt-0.5">
+                Edit messages to create branches
+              </span>
+            </label>
+            <ToggleSwitch
+              id="branching-toggle"
+              checked={branchingEnabled}
+              onChange={onBranchingChange}
+            />
+          </div>
+          {branchingEnabled && (
+            <div className="mt-2.5 flex items-start gap-1.5 rounded-md bg-blue-500/10 border border-blue-500/20 px-2.5 py-2">
+              <ChevronRight className="mt-0.5 h-3 w-3 flex-shrink-0 text-blue-400" />
+              <p className="text-xs text-blue-400 leading-relaxed">
+                Click the edit icon on any user message to branch the
+                conversation.
+              </p>
+            </div>
+          )}
+        </div>
+      </div>
+    </aside>
+  );
+}
+
+// ============================================
+// App
+// ============================================
+
+export default function App() {
+  const [branchingEnabled, setBranchingEnabled] = useState(false);
+
+  return (
+    <div className="flex h-screen w-full overflow-hidden bg-zinc-950">
+      <Sidebar
+        branchingEnabled={branchingEnabled}
+        onBranchingChange={setBranchingEnabled}
+      />
+
+      {/* Chat panel */}
+      <main className="flex flex-1 flex-col overflow-hidden">
+        <CopilotProvider runtimeUrl="/api/chat">
+          <CopilotChat
+            allowEdit={branchingEnabled}
+            header={{
+              title: "Skills Chat",
+            }}
+            className="h-full"
+          />
+        </CopilotProvider>
+      </main>
+    </div>
+  );
+}
diff --git a/examples/skills-demo/src/index.css b/examples/skills-demo/src/index.css
new file mode 100644
index 0000000..f1d8c73
--- /dev/null
+++ b/examples/skills-demo/src/index.css
@@ -0,0 +1 @@
+@import "tailwindcss";
diff --git a/examples/skills-demo/src/main.tsx b/examples/skills-demo/src/main.tsx
new file mode 100644
index 0000000..15753af
--- /dev/null
+++ b/examples/skills-demo/src/main.tsx
@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
diff --git a/examples/skills-demo/tsconfig.json b/examples/skills-demo/tsconfig.json
new file mode 100644
index 0000000..7901e30
--- /dev/null
+++ b/examples/skills-demo/tsconfig.json
@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
diff --git a/examples/skills-demo/tsconfig.node.json b/examples/skills-demo/tsconfig.node.json
new file mode 100644
index 0000000..1f27c41
--- /dev/null
+++ b/examples/skills-demo/tsconfig.node.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true
+  },
+  "include": ["vite.config.ts", "server"]
+}
diff --git a/examples/skills-demo/vite.config.ts b/examples/skills-demo/vite.config.ts
new file mode 100644
index 0000000..f765d45
--- /dev/null
+++ b/examples/skills-demo/vite.config.ts
@@ -0,0 +1,18 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "path";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  server: {
+    port: 3033,
+    proxy: {
+      "/api": "http://localhost:3032",
+    },
+  },
+});

From 27b921bfa7362cc0f2c754648307e5dc2dcf26fb Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sat, 28 Mar 2026 21:52:33 +0530
Subject: [PATCH 62/72] feat(skills-demo): redesign as Dash SaaS dashboard with
 animated skill activation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace generic skills with SaaS-focused: revenue-intelligence, customer-health, incident-runbook
- Full dark dashboard UI (Bricolage Grotesque + JetBrains Mono, navy/indigo palette)
- Live metrics bar, nav with module links, AI Copilot badge
- Skill cards animate on load: scan line sweep → expand → capability reveal with staggered fade-in
- Skill state detection via load_skill toolRenderer watching for tool call completion
- Branching toggle, demo prompt injectors for demo recording
- Updated server system prompt for SaaS context

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/skills-demo/index.html               |   5 +-
 examples/skills-demo/server/index.ts          |  11 +-
 .../skills-demo/skills/customer-health.md     |  54 ++
 .../skills-demo/skills/incident-runbook.md    |  57 ++
 .../skills/revenue-intelligence.md            |  41 +
 examples/skills-demo/src/App.tsx              | 776 ++++++++++++------
 6 files changed, 691 insertions(+), 253 deletions(-)
 create mode 100644 examples/skills-demo/skills/customer-health.md
 create mode 100644 examples/skills-demo/skills/incident-runbook.md
 create mode 100644 examples/skills-demo/skills/revenue-intelligence.md

diff --git a/examples/skills-demo/index.html b/examples/skills-demo/index.html
index 5208e48..e272c21 100644
--- a/examples/skills-demo/index.html
+++ b/examples/skills-demo/index.html
@@ -4,7 +4,10 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Skills Demo</title>
+    <title>Dash — AI Copilot</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,300;12..96,400;12..96,500;12..96,600;12..96,700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
   </head>
   <body>
     <div id="root"></div>
diff --git a/examples/skills-demo/server/index.ts b/examples/skills-demo/server/index.ts
index 0a12863..c54db60 100644
--- a/examples/skills-demo/server/index.ts
+++ b/examples/skills-demo/server/index.ts
@@ -57,7 +57,16 @@ console.log(`Using model: ${model}`);
 // ============================================
 
 const systemPrompt = buildSystemPrompt(
-  "You are a helpful assistant. Use available skills to tailor your responses.",
+  `You are the AI Copilot for Dash, a SaaS analytics and operations platform.
+You assist the team with revenue analysis, customer health monitoring, and incident response.
+
+When a user asks about:
+- Revenue, MRR, churn, growth, or financial metrics → load the "revenue-intelligence" skill
+- Customer risk, health scores, at-risk accounts, or engagement → load the "customer-health" skill
+- Incidents, outages, production issues, or on-call → load the "incident-runbook" skill
+
+Always load the relevant skill before responding to ensure you follow the correct protocol.
+Be concise, data-focused, and action-oriented.`,
 );
 
 const runtime = createRuntime({
diff --git a/examples/skills-demo/skills/customer-health.md b/examples/skills-demo/skills/customer-health.md
new file mode 100644
index 0000000..f4dfe59
--- /dev/null
+++ b/examples/skills-demo/skills/customer-health.md
@@ -0,0 +1,54 @@
+---
+name: customer-health
+description: Score account health, surface at-risk customers, and identify engagement drop-off patterns
+strategy: auto
+version: 1.0.0
+---
+
+## Customer Health Scoring Protocol
+
+You are now operating in Customer Health mode. Apply this framework when asked about customer risk, churn signals, account health, NPS, or engagement.
+
+### Health Score Dimensions
+
+Each account is scored 0–100 across five dimensions:
+
+| Dimension | Weight | Signal |
+|-----------|--------|--------|
+| Product Engagement | 30% | DAU/MAU ratio, feature adoption depth |
+| Support Sentiment | 20% | Ticket volume, CSAT score, escalations |
+| Contract Health | 20% | Renewal proximity, payment history |
+| Growth Trajectory | 15% | Seat growth, usage expansion |
+| Champion Strength | 15% | Stakeholder seniority, internal advocates |
+
+**Score Tiers:**
+- 🟢 **Healthy** (75–100): Expansion candidate
+- 🟡 **Neutral** (50–74): Monitor closely
+- 🔴 **At Risk** (0–49): Immediate intervention required
+
+### At-Risk Detection Patterns
+
+Flag accounts showing:
+- Login frequency drop > 30% over 14 days
+- No new features adopted in 30+ days
+- Ticket escalations in last 7 days
+- Key champion changed roles or left
+- Usage below 40% of contracted capacity
+
+### Intervention Playbooks
+
+**Red Account Playbook:**
+1. CSM outreach within 24 hours
+2. Executive business review within 2 weeks
+3. Success plan refresh with clear milestones
+4. Executive sponsor engagement if needed
+
+**Yellow Account Playbook:**
+1. Check-in call within 1 week
+2. Feature adoption webinar invitation
+3. QBR scheduling
+
+### Output Format
+- **Risk Summary** — headline risk level with reason
+- **Top At-Risk Accounts** — ranked list with scores and key risk factor
+- **Recommended Interventions** — specific next steps per account tier
diff --git a/examples/skills-demo/skills/incident-runbook.md b/examples/skills-demo/skills/incident-runbook.md
new file mode 100644
index 0000000..a381ec4
--- /dev/null
+++ b/examples/skills-demo/skills/incident-runbook.md
@@ -0,0 +1,57 @@
+---
+name: incident-runbook
+description: Production incident response protocol with severity classification, checklists, and communication templates
+strategy: manual
+version: 1.0.0
+---
+
+## Incident Response Runbook
+
+You are now in Incident Commander mode. Follow this protocol precisely for all production incidents. Speed and clarity save SLA.
+
+### Severity Classification
+
+| Level | Criteria | Response SLA | Example |
+|-------|----------|-------------|---------|
+| **P0** | Full outage, data loss risk | 15 min | Payments down, DB unavailable |
+| **P1** | Core feature broken, >20% users affected | 30 min | Login failures, API errors |
+| **P2** | Degraded performance, workaround exists | 2 hours | Slow queries, non-critical API |
+| **P3** | Minor issue, cosmetic, < 5% users | 24 hours | UI glitch, edge-case bug |
+
+### Immediate Response Checklist (First 15 Minutes)
+
+**[ ] 1. Declare the incident** — post to #incidents with: severity, what is broken, first seen time
+**[ ] 2. Assign roles** — Incident Commander, Technical Lead, Communications Lead
+**[ ] 3. Start a war room** — Zoom / Slack huddle, record the link in the incident thread
+**[ ] 4. Initial diagnosis** — check dashboards: error rate, latency, infra health
+**[ ] 5. Scope assessment** — how many users affected? What regions? Which services?
+**[ ] 6. Initial customer communication** — post status page update within 15 min of declaration
+
+### Diagnosis Checklist
+
+- Recent deploys in last 2 hours? → Roll back as first mitigation if yes
+- Infrastructure alerts firing? → Check cloud provider status page
+- Dependency failures? → Third-party APIs, payment processors, CDN
+- Database issues? → Query performance, connection pool, replication lag
+- Memory / CPU spikes? → Check K8s pods, auto-scaling events
+
+### Communication Templates
+
+**Status Page Update (initial):**
+> We are investigating reports of [brief description]. Our engineering team is actively working on a resolution. We will provide an update within [X] minutes.
+
+**Customer Notification (P0/P1):**
+> We are currently experiencing [service impact] affecting [scope]. This has been active since approximately [time]. We have identified the cause and are deploying a fix. Estimated resolution: [ETA].
+
+**All-Clear:**
+> This incident has been resolved as of [time]. Affected service: [name]. Root cause: [1 sentence]. Duration: [X min]. A full post-mortem will be shared within 48 hours.
+
+### Post-Incident Requirements
+
+Within 48 hours of resolution:
+1. Write post-mortem document (timeline, root cause, contributing factors)
+2. 5 Whys analysis
+3. Action items with owners and due dates
+4. Update runbook if gaps were found
+
+Always lead with facts. Give clear, time-stamped guidance. Panic spreads when information is absent.
diff --git a/examples/skills-demo/skills/revenue-intelligence.md b/examples/skills-demo/skills/revenue-intelligence.md
new file mode 100644
index 0000000..fe259ea
--- /dev/null
+++ b/examples/skills-demo/skills/revenue-intelligence.md
@@ -0,0 +1,41 @@
+---
+name: revenue-intelligence
+description: Analyze MRR trends, churn impact, and expansion revenue signals with structured insights
+strategy: auto
+version: 1.0.0
+---
+
+## Revenue Intelligence Protocol
+
+You are now operating in Revenue Intelligence mode. Apply this protocol when the user asks about revenue, MRR, churn, growth, or financial metrics.
+
+### Analysis Framework
+
+**1. Trend Identification**
+- Identify the direction and velocity of MRR change
+- Segment by New MRR, Expansion MRR, Contraction MRR, and Churned MRR
+- Flag month-over-month deviations greater than ±5%
+
+**2. Churn Impact Assessment**
+- Quantify the revenue impact of churned accounts
+- Identify the top churned segments (plan tier, industry, company size)
+- Separate voluntary vs involuntary churn (failed payments)
+
+**3. Expansion Revenue Signals**
+- Identify accounts trending toward a plan upgrade based on usage patterns
+- Score accounts by expansion probability (High / Medium / Low)
+- Recommend specific upsell timing based on usage milestones
+
+**4. Forecast Guidance**
+- Project next-90-day MRR based on current growth rate and churn
+- Highlight key assumptions and risks in the forecast
+- Suggest growth levers ranked by expected impact
+
+### Output Format
+Always structure your response as:
+- **Summary** (2–3 sentences with the key insight)
+- **Breakdown** (structured data or bullets)
+- **Recommended Actions** (top 2–3, ranked by impact)
+- **Watch List** (metrics or accounts to monitor)
+
+Be specific with numbers. Reference the user's actual data when available.
diff --git a/examples/skills-demo/src/App.tsx b/examples/skills-demo/src/App.tsx
index 68d9b5b..f8b2994 100644
--- a/examples/skills-demo/src/App.tsx
+++ b/examples/skills-demo/src/App.tsx
@@ -1,295 +1,569 @@
-import { useState, useEffect } from "react";
-import { GitBranch, Zap, Bot, ChevronRight } from "lucide-react";
-import { CopilotProvider, CopilotChat } from "@yourgpt/copilot-sdk/ui";
+import { useState, useCallback, useEffect, useRef, useMemo } from "react";
+import { CopilotProvider } from "@yourgpt/copilot-sdk/react";
+import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
 import "@yourgpt/copilot-sdk/ui/styles.css";
 
-// ============================================
-// Types
-// ============================================
+// ─── Skill definitions (client-side metadata) ─────────────────────────────────
 
-interface SkillInfo {
+interface SkillMeta {
+  id: string;
   name: string;
-  description: string;
+  icon: string;
+  shortDesc: string;
   strategy: "eager" | "auto" | "manual";
-  version?: string;
-}
-
-// ============================================
-// Helpers
-// ============================================
-
-function formatSkillName(name: string): string {
-  return name
-    .split("-")
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(" ");
-}
-
-function StrategyBadge({ strategy }: { strategy: SkillInfo["strategy"] }) {
-  const config: Record<
-    SkillInfo["strategy"],
-    { label: string; className: string }
-  > = {
-    eager: {
-      label: "eager",
-      className:
-        "bg-emerald-500/15 text-emerald-400 border border-emerald-500/25",
-    },
-    auto: {
-      label: "auto",
-      className: "bg-blue-500/15 text-blue-400 border border-blue-500/25",
-    },
-    manual: {
-      label: "manual",
-      className: "bg-amber-500/15 text-amber-400 border border-amber-500/25",
-    },
-  };
+  capabilities: string[];
+  color: string;
+}
 
-  const { label, className } = config[strategy];
+type SkillState = "idle" | "scanning" | "loaded";
 
-  return (
-    <span
-      className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${className}`}
-    >
-      {label}
-    </span>
-  );
-}
+const SKILLS: SkillMeta[] = [
+  {
+    id: "revenue-intelligence",
+    name: "Revenue Intelligence",
+    icon: "◈",
+    shortDesc: "MRR trends, churn analysis & expansion signals",
+    strategy: "auto",
+    capabilities: [
+      "Monthly recurring revenue breakdown",
+      "Churn forecasting & root cause",
+      "Expansion revenue opportunity scoring",
+    ],
+    color: "#818cf8",
+  },
+  {
+    id: "customer-health",
+    name: "Customer Health",
+    icon: "◉",
+    shortDesc: "Account risk scoring & engagement signals",
+    strategy: "auto",
+    capabilities: [
+      "Health score calculation (0–100)",
+      "At-risk account early warning",
+      "Engagement drop-off detection",
+    ],
+    color: "#34d399",
+  },
+  {
+    id: "incident-runbook",
+    name: "Incident Runbook",
+    icon: "◬",
+    shortDesc: "Production incident response protocol",
+    strategy: "manual",
+    capabilities: [
+      "Severity classification P0–P3",
+      "Step-by-step response checklist",
+      "Stakeholder communication templates",
+    ],
+    color: "#fb923c",
+  },
+];
 
-// ============================================
-// Toggle Switch
-// ============================================
+const METRICS = [
+  { label: "MRR", value: "$124.8k", change: "+12%", up: true },
+  { label: "Churn", value: "2.3%", change: "−0.4%", up: true },
+  { label: "DAU", value: "8,429", change: "+5%", up: true },
+  { label: "Open P1s", value: "2", change: "+2", up: false },
+];
 
-function ToggleSwitch({
-  checked,
-  onChange,
-  id,
+const DEMO_PROMPTS = [
+  "Analyze our MRR growth and top churn risks this month",
+  "Which enterprise accounts are most at risk right now?",
+  "We have a P1 — payment API is returning 503 errors",
+];
+
+// ─── Skill load notifier (invisible, watches for load_skill tool calls) ───────
+
+function SkillLoadNotifier({
+  args,
+  status,
+  onLoaded,
 }: {
-  checked: boolean;
-  onChange: (v: boolean) => void;
-  id: string;
+  args: Record<string, unknown>;
+  status: string;
+  result?: unknown;
+  toolCallId: string;
+  onLoaded: (name: string) => void;
 }) {
-  return (
-    <button
-      id={id}
-      role="switch"
-      aria-checked={checked}
-      onClick={() => onChange(!checked)}
-      className={`relative inline-flex h-5 w-9 flex-shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-200 ease-in-out focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-zinc-900 ${
-        checked ? "bg-blue-500" : "bg-zinc-700"
-      }`}
-    >
-      <span
-        className={`pointer-events-none inline-block h-4 w-4 transform rounded-full bg-white shadow ring-0 transition duration-200 ease-in-out ${
-          checked ? "translate-x-4" : "translate-x-0"
-        }`}
-      />
-    </button>
-  );
+  const firedRef = useRef(false);
+  useEffect(() => {
+    if (status === "success" && args?.name && !firedRef.current) {
+      firedRef.current = true;
+      onLoaded(args.name as string);
+    }
+  }, [status, args?.name, onLoaded]);
+  return null;
 }
 
-// ============================================
-// Skill Card
-// ============================================
+// ─── Individual skill card ────────────────────────────────────────────────────
+
+function SkillCard({ skill, state }: { skill: SkillMeta; state: SkillState }) {
+  const isLoaded = state === "loaded";
+  const isScanning = state === "scanning";
+  const strategyLabel = {
+    eager: "ALWAYS ON",
+    auto: "AUTO",
+    manual: "ON DEMAND",
+  };
 
-function SkillCard({ skill }: { skill: SkillInfo }) {
   return (
-    <div className="group rounded-lg border border-zinc-800 bg-zinc-900/50 p-3 transition-colors hover:border-zinc-700 hover:bg-zinc-900">
-      <div className="flex items-start justify-between gap-2">
-        <span className="text-sm font-medium text-zinc-100 leading-tight">
-          {formatSkillName(skill.name)}
+    <div
+      className="skill-card"
+      data-state={state}
+      style={{ "--sc": skill.color } as React.CSSProperties}
+    >
+      {isScanning && <div className="scan-line" />}
+
+      <div className="sc-header">
+        <span className="sc-icon" data-scanning={isScanning}>
+          {skill.icon}
         </span>
-        <StrategyBadge strategy={skill.strategy} />
+        <div className="sc-title-group">
+          <span className="sc-name">{skill.name}</span>
+          <span className={`sc-badge sc-badge--${skill.strategy}`}>
+            {strategyLabel[skill.strategy]}
+          </span>
+        </div>
+        <span className="sc-dot" data-active={isLoaded} />
+      </div>
+
+      <p className="sc-desc">{skill.shortDesc}</p>
+
+      <div className="sc-expanded" data-open={isLoaded}>
+        <div className="sc-divider" />
+        <p className="sc-active-label">✦ Skill active</p>
+        <ul className="sc-caps">
+          {skill.capabilities.map((cap, i) => (
+            <li
+              key={cap}
+              className="sc-cap"
+              data-visible={isLoaded}
+              style={{
+                transitionDelay: isLoaded ? `${0.12 + i * 0.09}s` : "0s",
+              }}
+            >
+              <span className="sc-cap-dot" />
+              {cap}
+            </li>
+          ))}
+        </ul>
       </div>
-      <p className="mt-1.5 text-xs text-zinc-500 leading-relaxed line-clamp-2">
-        {skill.description}
-      </p>
     </div>
   );
 }
 
-// ============================================
-// Sidebar
-// ============================================
+// ─── Main app ─────────────────────────────────────────────────────────────────
 
-function Sidebar({
-  branchingEnabled,
-  onBranchingChange,
-}: {
-  branchingEnabled: boolean;
-  onBranchingChange: (v: boolean) => void;
-}) {
-  const [skills, setSkills] = useState<SkillInfo[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+export default function App() {
+  const [skillStates, setSkillStates] = useState<Record<string, SkillState>>(
+    () => Object.fromEntries(SKILLS.map((s) => [s.id, "idle"])),
+  );
+  const [branchingEnabled, setBranchingEnabled] = useState(false);
 
-  useEffect(() => {
-    fetch("/api/skills")
-      .then((res) => {
-        if (!res.ok) throw new Error(`HTTP ${res.status}`);
-        return res.json() as Promise<SkillInfo[]>;
-      })
-      .then((data) => {
-        setSkills(data);
-        setLoading(false);
-      })
-      .catch((err: unknown) => {
-        setError(err instanceof Error ? err.message : "Failed to load skills");
-        setLoading(false);
-      });
+  const handleSkillLoaded = useCallback((skillName: string) => {
+    if (!SKILLS.find((s) => s.id === skillName)) return;
+    setSkillStates((prev) =>
+      prev[skillName] === "loaded"
+        ? prev
+        : { ...prev, [skillName]: "scanning" },
+    );
+    setTimeout(() => {
+      setSkillStates((prev) => ({ ...prev, [skillName]: "loaded" }));
+    }, 1500);
   }, []);
 
-  return (
-    <aside className="flex h-full w-[280px] flex-shrink-0 flex-col border-r border-zinc-800 bg-zinc-900">
-      {/* Header */}
-      <div className="border-b border-zinc-800 px-4 py-4">
-        <div className="flex items-center gap-2.5">
-          <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-blue-500/15 border border-blue-500/25">
-            <Zap className="h-4 w-4 text-blue-400" />
-          </div>
-          <div>
-            <h1 className="text-sm font-semibold text-zinc-100">Skills Demo</h1>
-            <p className="text-xs text-zinc-500">
-              Server-side skill management
-            </p>
-          </div>
-        </div>
-      </div>
+  const toolRenderers = useMemo(
+    () => ({
+      load_skill: (props: {
+        args: Record<string, unknown>;
+        status: string;
+        result?: unknown;
+        toolCallId: string;
+      }) => <SkillLoadNotifier {...props} onLoaded={handleSkillLoaded} />,
+    }),
+    [handleSkillLoaded],
+  );
 
-      {/* Skills section */}
-      <div className="flex-1 overflow-y-auto px-3 py-4">
-        <div className="mb-3 flex items-center gap-1.5 px-1">
-          <Bot className="h-3.5 w-3.5 text-zinc-500" />
-          <span className="text-xs font-medium uppercase tracking-wider text-zinc-500">
-            Available Skills
-          </span>
-        </div>
+  const injectPrompt = (text: string) => {
+    const ta = document.querySelector<HTMLTextAreaElement>(
+      "textarea[placeholder]",
+    );
+    if (!ta) return;
+    const setter = Object.getOwnPropertyDescriptor(
+      window.HTMLTextAreaElement.prototype,
+      "value",
+    )?.set;
+    setter?.call(ta, text);
+    ta.dispatchEvent(new Event("input", { bubbles: true }));
+    ta.focus();
+  };
 
-        {loading && (
-          <div className="space-y-2">
-            {[1, 2, 3].map((i) => (
-              <div
-                key={i}
-                className="h-16 rounded-lg border border-zinc-800 bg-zinc-900/50 animate-pulse"
-              />
-            ))}
+  return (
+    <>
+      <style>{CSS}</style>
+      <div className="d-root">
+        {/* Top nav */}
+        <header className="d-nav">
+          <div className="d-nav__brand">
+            <span className="d-nav__logo">⬡</span>
+            <span className="d-nav__name">Dash</span>
+            <span className="d-nav__platform">Operations Platform</span>
           </div>
-        )}
-
-        {error && (
-          <div className="rounded-lg border border-red-500/25 bg-red-500/10 px-3 py-2.5">
-            <p className="text-xs text-red-400">
-              Failed to load skills — is the server running?
-            </p>
-            <p className="mt-0.5 text-xs text-red-500/70">{error}</p>
+          <nav className="d-nav__links">
+            {["Overview", "Revenue", "Customers", "Incidents", "Settings"].map(
+              (l) => (
+                <span key={l} className="d-nav__link">
+                  {l}
+                </span>
+              ),
+            )}
+          </nav>
+          <div className="d-nav__copilot">
+            <span className="d-nav__pulse" />
+            AI Copilot
           </div>
-        )}
+        </header>
 
-        {!loading && !error && skills.length === 0 && (
-          <p className="px-1 text-xs text-zinc-600">No skills found.</p>
-        )}
+        <div className="d-body">
+          {/* Sidebar */}
+          <aside className="d-sidebar">
+            {/* Metrics */}
+            <section className="d-section">
+              <h3 className="d-section__label">Live Metrics</h3>
+              <div className="d-metrics">
+                {METRICS.map((m) => (
+                  <div key={m.label} className="d-metric">
+                    <span className="d-metric__label">{m.label}</span>
+                    <span className="d-metric__val">{m.value}</span>
+                    <span className={`d-metric__chg ${m.up ? "up" : "dn"}`}>
+                      {m.change}
+                    </span>
+                  </div>
+                ))}
+              </div>
+            </section>
 
-        {!loading && !error && skills.length > 0 && (
-          <div className="space-y-2">
-            {skills.map((skill) => (
-              <SkillCard key={skill.name} skill={skill} />
-            ))}
-          </div>
-        )}
-
-        {/* Strategy legend */}
-        {!loading && !error && skills.length > 0 && (
-          <div className="mt-4 rounded-lg border border-zinc-800 bg-zinc-950/50 px-3 py-2.5">
-            <p className="mb-2 text-xs font-medium text-zinc-500">
-              Strategy legend
-            </p>
-            <div className="space-y-1.5">
-              <div className="flex items-center gap-2">
-                <StrategyBadge strategy="eager" />
-                <span className="text-xs text-zinc-500">Always injected</span>
+            {/* Skills */}
+            <section className="d-section d-section--skills">
+              <div className="d-section__header-row">
+                <h3 className="d-section__label">Copilot Skills</h3>
+                <span className="d-section__count">{SKILLS.length}</span>
               </div>
-              <div className="flex items-center gap-2">
-                <StrategyBadge strategy="auto" />
-                <span className="text-xs text-zinc-500">
-                  AI decides when to load
-                </span>
+              <div className="d-skills">
+                {SKILLS.map((skill) => (
+                  <SkillCard
+                    key={skill.id}
+                    skill={skill}
+                    state={skillStates[skill.id] ?? "idle"}
+                  />
+                ))}
               </div>
-              <div className="flex items-center gap-2">
-                <StrategyBadge strategy="manual" />
-                <span className="text-xs text-zinc-500">
-                  Explicit invocation only
-                </span>
+            </section>
+
+            {/* Branching */}
+            <section className="d-section d-section--branch">
+              <div className="d-branch">
+                <div>
+                  <p className="d-branch__label">Conversation Branching</p>
+                  <p className="d-branch__desc">
+                    Edit messages to explore alternatives
+                  </p>
+                </div>
+                <button
+                  className={`d-toggle ${branchingEnabled ? "d-toggle--on" : ""}`}
+                  onClick={() => setBranchingEnabled((v) => !v)}
+                />
               </div>
-            </div>
-          </div>
-        )}
-      </div>
+            </section>
 
-      {/* Branching section */}
-      <div className="border-t border-zinc-800 px-3 py-4">
-        <div className="mb-2 flex items-center gap-1.5 px-1">
-          <GitBranch className="h-3.5 w-3.5 text-zinc-500" />
-          <span className="text-xs font-medium uppercase tracking-wider text-zinc-500">
-            Branching
-          </span>
-        </div>
-        <div className="rounded-lg border border-zinc-800 bg-zinc-950/50 px-3 py-3">
-          <div className="flex items-center justify-between gap-3">
-            <label htmlFor="branching-toggle" className="flex-1 cursor-pointer">
-              <span className="block text-sm font-medium text-zinc-200">
-                Conversation Branching
-              </span>
-              <span className="block text-xs text-zinc-500 mt-0.5">
-                Edit messages to create branches
-              </span>
-            </label>
-            <ToggleSwitch
-              id="branching-toggle"
-              checked={branchingEnabled}
-              onChange={onBranchingChange}
-            />
-          </div>
-          {branchingEnabled && (
-            <div className="mt-2.5 flex items-start gap-1.5 rounded-md bg-blue-500/10 border border-blue-500/20 px-2.5 py-2">
-              <ChevronRight className="mt-0.5 h-3 w-3 flex-shrink-0 text-blue-400" />
-              <p className="text-xs text-blue-400 leading-relaxed">
-                Click the edit icon on any user message to branch the
-                conversation.
-              </p>
-            </div>
-          )}
+            {/* Demo prompts */}
+            <section className="d-section d-section--prompts">
+              <h3 className="d-section__label">Try asking…</h3>
+              <div className="d-prompts">
+                {DEMO_PROMPTS.map((p) => (
+                  <button
+                    key={p}
+                    className="d-prompt"
+                    onClick={() => injectPrompt(p)}
+                  >
+                    {p}
+                  </button>
+                ))}
+              </div>
+            </section>
+          </aside>
+
+          {/* Chat */}
+          <main className="d-chat">
+            <CopilotProvider runtimeUrl="/api/chat">
+              <CopilotChat
+                className="d-copilot"
+                placeholder="Ask about revenue, customers, or incidents…"
+                showHeader
+                header={{ name: "Dash Copilot" }}
+                loaderVariant="typing"
+                showUserAvatar
+                allowEdit={branchingEnabled}
+                toolRenderers={toolRenderers as never}
+              />
+            </CopilotProvider>
+          </main>
         </div>
       </div>
-    </aside>
+    </>
   );
 }
 
-// ============================================
-// App
-// ============================================
+// ─── All styles ───────────────────────────────────────────────────────────────
 
-export default function App() {
-  const [branchingEnabled, setBranchingEnabled] = useState(false);
+const CSS = `
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
 
-  return (
-    <div className="flex h-screen w-full overflow-hidden bg-zinc-950">
-      <Sidebar
-        branchingEnabled={branchingEnabled}
-        onBranchingChange={setBranchingEnabled}
-      />
-
-      {/* Chat panel */}
-      <main className="flex flex-1 flex-col overflow-hidden">
-        <CopilotProvider runtimeUrl="/api/chat">
-          <CopilotChat
-            allowEdit={branchingEnabled}
-            header={{
-              title: "Skills Chat",
-            }}
-            className="h-full"
-          />
-        </CopilotProvider>
-      </main>
-    </div>
+:root {
+  --bg:       #07090f;
+  --s1:       #0b0e1a;
+  --s2:       #0f1320;
+  --s3:       #141929;
+  --bd:       rgba(255,255,255,0.055);
+  --bd2:      rgba(255,255,255,0.10);
+  --t1:       #e8eaf6;
+  --t2:       #7b82a8;
+  --t3:       #3d4468;
+  --ok:       #34d399;
+  --err:      #f87171;
+  --acc:      #818cf8;
+  --font:     'Bricolage Grotesque', system-ui, sans-serif;
+  --mono:     'JetBrains Mono', monospace;
+}
+
+body {
+  background: var(--bg);
+  font-family: var(--font);
+  color: var(--t1);
+  -webkit-font-smoothing: antialiased;
+}
+
+/* ── Root ── */
+.d-root { display: flex; flex-direction: column; height: 100vh; overflow: hidden; }
+
+/* ── Nav ── */
+.d-nav {
+  display: flex; align-items: center; gap: 20px;
+  padding: 0 20px; height: 50px; flex-shrink: 0;
+  background: var(--s1);
+  border-bottom: 1px solid var(--bd);
+}
+.d-nav__brand  { display: flex; align-items: center; gap: 8px; }
+.d-nav__logo   { font-size: 19px; color: var(--acc); }
+.d-nav__name   { font-weight: 700; font-size: 15px; letter-spacing: -0.04em; }
+.d-nav__platform { font-size: 11px; color: var(--t3); margin-left: 1px; }
+.d-nav__links  { display: flex; gap: 1px; margin-left: auto; }
+.d-nav__link   {
+  padding: 4px 11px; border-radius: 6px;
+  font-size: 12px; color: var(--t2); cursor: pointer;
+  transition: all 0.12s;
+}
+.d-nav__link:hover { background: var(--s2); color: var(--t1); }
+.d-nav__copilot {
+  display: flex; align-items: center; gap: 7px;
+  padding: 4px 12px; border-radius: 20px;
+  background: rgba(129,140,248,0.08);
+  border: 1px solid rgba(129,140,248,0.2);
+  font-size: 11px; font-weight: 600; color: var(--acc);
+  letter-spacing: 0.05em; text-transform: uppercase;
+}
+.d-nav__pulse {
+  width: 6px; height: 6px; border-radius: 50%; background: var(--acc);
+  animation: nav-pulse 2.2s ease-in-out infinite;
+}
+@keyframes nav-pulse {
+  0%,100% { opacity:.5; transform:scale(1); }
+  50%      { opacity:1;  transform:scale(1.35); }
+}
+
+/* ── Body ── */
+.d-body { display: flex; flex: 1; min-height: 0; }
+
+/* ── Sidebar ── */
+.d-sidebar {
+  width: 296px; flex-shrink: 0;
+  background: var(--s1); border-right: 1px solid var(--bd);
+  overflow-y: auto; display: flex; flex-direction: column;
+  scrollbar-width: thin; scrollbar-color: var(--bd2) transparent;
+}
+
+.d-section {
+  padding: 14px 14px;
+  border-bottom: 1px solid var(--bd);
+}
+.d-section__label {
+  font-size: 10px; font-weight: 600; letter-spacing: 0.1em;
+  text-transform: uppercase; color: var(--t3); margin-bottom: 10px;
+}
+.d-section__header-row {
+  display: flex; align-items: center; justify-content: space-between; margin-bottom: 10px;
+}
+.d-section__count {
+  font-family: var(--mono); font-size: 10px; color: var(--t3);
+  background: var(--s2); padding: 1px 6px; border-radius: 8px;
+  border: 1px solid var(--bd);
+}
+
+/* ── Metrics ── */
+.d-metrics { display: grid; grid-template-columns: 1fr 1fr; gap: 7px; }
+.d-metric {
+  background: var(--s2); border: 1px solid var(--bd);
+  border-radius: 8px; padding: 9px 10px 7px;
+  display: flex; flex-direction: column; gap: 1px;
+}
+.d-metric__label { font-size: 9.5px; color: var(--t3); font-weight: 500; text-transform: uppercase; letter-spacing: 0.06em; }
+.d-metric__val   { font-family: var(--mono); font-size: 16px; font-weight: 500; color: var(--t1); line-height: 1.2; }
+.d-metric__chg   { font-family: var(--mono); font-size: 10px; font-weight: 500; }
+.d-metric__chg.up { color: var(--ok); }
+.d-metric__chg.dn { color: var(--err); }
+
+/* ── Skills ── */
+.d-skills { display: flex; flex-direction: column; gap: 7px; }
+
+.skill-card {
+  position: relative; overflow: hidden;
+  border-radius: 10px; padding: 11px;
+  background: var(--s2); border: 1px solid var(--bd);
+  transition: border-color 0.45s ease, background 0.45s ease, box-shadow 0.45s ease;
+}
+.skill-card[data-state="scanning"] {
+  border-color: rgba(255,255,255,0.13);
+  background: var(--s3);
+}
+.skill-card[data-state="loaded"] {
+  border-color: color-mix(in srgb, var(--sc) 38%, transparent);
+  background: color-mix(in srgb, var(--sc) 6%, var(--s2));
+  box-shadow: 0 0 22px -4px color-mix(in srgb, var(--sc) 22%, transparent);
+  animation: card-pop 0.55s cubic-bezier(0.22,1,0.36,1);
+}
+@keyframes card-pop {
+  0%   { box-shadow: 0 0 0 0 color-mix(in srgb, var(--sc) 55%, transparent); }
+  45%  { box-shadow: 0 0 28px 5px color-mix(in srgb, var(--sc) 32%, transparent); }
+  100% { box-shadow: 0 0 22px -4px color-mix(in srgb, var(--sc) 22%, transparent); }
+}
+
+/* Scan line */
+.scan-line {
+  position: absolute; inset: 0; pointer-events: none; z-index: 10;
+  background: linear-gradient(
+    to bottom,
+    transparent 0%,
+    rgba(255,255,255,0.03) 40%,
+    rgba(255,255,255,0.11) 50%,
+    rgba(255,255,255,0.03) 60%,
+    transparent 100%
   );
+  animation: scan 1.5s cubic-bezier(0.4,0,0.2,1) forwards;
+}
+@keyframes scan {
+  0%   { transform: translateY(-110%); opacity: 1; }
+  80%  { opacity: 1; }
+  100% { transform: translateY(210%);  opacity: 0; }
+}
+
+.sc-header { display: flex; align-items: center; gap: 8px; margin-bottom: 5px; }
+.sc-icon {
+  font-size: 17px; line-height: 1; flex-shrink: 0;
+  color: var(--sc);
+  transition: transform 0.3s ease;
+}
+.skill-card[data-state="loaded"] .sc-icon { transform: scale(1.12); }
+.sc-icon[data-scanning="true"] { animation: icon-spin 1.5s ease-in-out; }
+@keyframes icon-spin {
+  0%   { transform: rotate(0deg)   scale(1); }
+  50%  { transform: rotate(180deg) scale(1.2); }
+  100% { transform: rotate(360deg) scale(1); }
+}
+
+.sc-title-group { display: flex; flex-direction: column; gap: 2px; flex: 1; min-width: 0; }
+.sc-name { font-size: 12.5px; font-weight: 600; color: var(--t1); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+
+.sc-badge {
+  font-size: 9px; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase;
+  padding: 1px 5px; border-radius: 4px; width: fit-content;
+}
+.sc-badge--eager  { background: rgba(52,211,153,.12); color: #34d399; border: 1px solid rgba(52,211,153,.2); }
+.sc-badge--auto   { background: rgba(129,140,248,.12); color: #818cf8; border: 1px solid rgba(129,140,248,.2); }
+.sc-badge--manual { background: rgba(251,146,60,.12);  color: #fb923c; border: 1px solid rgba(251,146,60,.2); }
+
+.sc-dot {
+  width: 7px; height: 7px; border-radius: 50%; flex-shrink: 0;
+  background: var(--t3);
+  transition: background 0.35s, box-shadow 0.35s;
+}
+.sc-dot[data-active="true"] {
+  background: var(--sc);
+  box-shadow: 0 0 7px 1px color-mix(in srgb, var(--sc) 55%, transparent);
+  animation: dot-breathe 2s ease-in-out infinite;
 }
+@keyframes dot-breathe {
+  0%,100% { box-shadow: 0 0 7px 1px color-mix(in srgb, var(--sc) 45%, transparent); }
+  50%      { box-shadow: 0 0 11px 3px color-mix(in srgb, var(--sc) 65%, transparent); }
+}
+
+.sc-desc { font-size: 11px; color: var(--t2); line-height: 1.4; padding-left: 25px; }
+
+.sc-expanded {
+  max-height: 0; overflow: hidden;
+  transition: max-height 0.55s cubic-bezier(0.16,1,0.3,1);
+}
+.sc-expanded[data-open="true"] { max-height: 200px; }
+
+.sc-divider { height: 1px; background: color-mix(in srgb, var(--sc) 25%, transparent); margin: 10px 0 8px; }
+.sc-active-label {
+  font-size: 10px; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase;
+  color: var(--sc); margin-bottom: 7px; padding-left: 25px;
+}
+
+.sc-caps  { list-style: none; display: flex; flex-direction: column; gap: 5px; }
+.sc-cap {
+  display: flex; align-items: center; gap: 7px;
+  font-size: 11px; color: var(--t2); padding-left: 25px;
+  opacity: 0; transform: translateX(-8px);
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+.sc-cap[data-visible="true"] { opacity: 1; transform: translateX(0); }
+.sc-cap-dot {
+  width: 4px; height: 4px; border-radius: 50%; flex-shrink: 0;
+  background: var(--sc);
+}
+
+/* ── Branching ── */
+.d-branch {
+  display: flex; align-items: center; justify-content: space-between; gap: 12px;
+}
+.d-branch__label { font-size: 12px; font-weight: 600; color: var(--t1); }
+.d-branch__desc  { font-size: 10px; color: var(--t3); margin-top: 2px; }
+.d-toggle {
+  width: 36px; height: 20px; border-radius: 10px; flex-shrink: 0; cursor: pointer;
+  background: var(--s3); border: 1px solid var(--bd2); position: relative;
+  transition: background 0.2s, border-color 0.2s;
+}
+.d-toggle::after {
+  content: ''; position: absolute; top: 2px; left: 2px;
+  width: 14px; height: 14px; border-radius: 50%; background: var(--t3);
+  transition: transform 0.2s, background 0.2s;
+}
+.d-toggle--on { background: rgba(129,140,248,.2); border-color: rgba(129,140,248,.4); }
+.d-toggle--on::after { transform: translateX(16px); background: var(--acc); }
+
+/* ── Demo prompts ── */
+.d-prompts { display: flex; flex-direction: column; gap: 6px; }
+.d-prompt {
+  text-align: left; background: var(--s2); border: 1px solid var(--bd);
+  border-radius: 8px; padding: 8px 10px;
+  font-size: 11px; font-family: var(--font); color: var(--t2);
+  cursor: pointer; line-height: 1.4;
+  transition: background 0.12s, border-color 0.12s, color 0.12s;
+}
+.d-prompt:hover { background: var(--s3); border-color: var(--bd2); color: var(--t1); }
+
+/* ── Chat ── */
+.d-chat { flex: 1; min-width: 0; display: flex; flex-direction: column; background: var(--bg); }
+.d-copilot { height: 100% !important; }
+`;

From c75c2b4e0866a89c1ce203e0f025275ec773b000 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 12:12:24 +0530
Subject: [PATCH 63/72] feat(llm-sdk): add fallback chain & routing strategies

Adds @yourgpt/llm-sdk/fallback subpath export:
- createFallbackChain() with priority and round-robin routing
- Per-model retries with exponential/fixed backoff before fallback
- FallbackExhaustedError with per-model failure breakdown
- MemoryRoutingStore (default) + pluggable RoutingStore interface
- onRetry / onFallback observability callbacks
- Two-tier error detection (class-based for complete(), message-regex for stream())

Includes fallback-demo example and docs page.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/docs/content/docs/providers/fallback.mdx | 314 +++++++++++++
 apps/docs/content/docs/providers/index.mdx    |  23 +
 apps/docs/content/docs/providers/meta.json    |  10 +-
 examples/fallback-demo/README.md              | 119 +++++
 examples/fallback-demo/package.json           |  24 +
 examples/fallback-demo/src/index.ts           | 419 +++++++++++++++++
 examples/fallback-demo/tsconfig.json          |  12 +
 packages/llm-sdk/package.json                 |   5 +
 packages/llm-sdk/src/fallback/chain.ts        | 425 ++++++++++++++++++
 packages/llm-sdk/src/fallback/errors.ts       |  43 ++
 packages/llm-sdk/src/fallback/index.ts        |  43 ++
 .../llm-sdk/src/fallback/routing-store.ts     |  36 ++
 packages/llm-sdk/src/fallback/types.ts        | 236 ++++++++++
 packages/llm-sdk/src/index.ts                 |  14 +
 packages/llm-sdk/tsup.config.ts               |   3 +
 pnpm-lock.yaml                                |  75 ++--
 16 files changed, 1759 insertions(+), 42 deletions(-)
 create mode 100644 apps/docs/content/docs/providers/fallback.mdx
 create mode 100644 examples/fallback-demo/README.md
 create mode 100644 examples/fallback-demo/package.json
 create mode 100644 examples/fallback-demo/src/index.ts
 create mode 100644 examples/fallback-demo/tsconfig.json
 create mode 100644 packages/llm-sdk/src/fallback/chain.ts
 create mode 100644 packages/llm-sdk/src/fallback/errors.ts
 create mode 100644 packages/llm-sdk/src/fallback/index.ts
 create mode 100644 packages/llm-sdk/src/fallback/routing-store.ts
 create mode 100644 packages/llm-sdk/src/fallback/types.ts

diff --git a/apps/docs/content/docs/providers/fallback.mdx b/apps/docs/content/docs/providers/fallback.mdx
new file mode 100644
index 0000000..25dac37
--- /dev/null
+++ b/apps/docs/content/docs/providers/fallback.mdx
@@ -0,0 +1,314 @@
+---
+title: Fallback
+description: Automatic failover and load distribution across LLM providers
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+Automatically retry failed requests with backup models. When your primary provider returns a `5xx` error, rate limit (`429`), or times out — the SDK silently tries the next model in your chain. Your application code doesn't change.
+
+```ts
+import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+
+const chain = createFallbackChain({
+  models: [
+    createOpenAI({ apiKey: '...' }).languageModel('gpt-5.4'),
+    createAnthropic({ apiKey: '...' }).languageModel('claude-haiku-4-5'),
+  ],
+});
+
+const runtime = createRuntime({ adapter: chain });
+```
+
+---
+
+## Installation
+
+```bash
+npm install @yourgpt/llm-sdk openai @anthropic-ai/sdk
+```
+
+---
+
+## Basic Usage
+
+Pass `createFallbackChain()` as the `adapter` in `createRuntime()`. The rest of your server code — streaming, tools, sessions — stays exactly the same.
+
+```ts title="server.ts"
+import { createRuntime } from '@yourgpt/llm-sdk';
+import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+const runtime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel('gpt-5.4'),            // tried first
+      anthropic.languageModel('claude-haiku-4-5'), // tried if OpenAI fails
+    ],
+  }),
+  systemPrompt: 'You are a helpful assistant.',
+});
+
+// Use exactly as normal — no other changes
+app.post('/api/chat', async (req, res) => {
+  await runtime.stream(req.body).pipeToResponse(res);
+});
+```
+
+---
+
+## What Triggers Fallback
+
+| Error type | Triggers fallback? |
+|---|---|
+| `5xx` server errors | ✅ Yes |
+| `429` rate limit | ✅ Yes |
+| Network timeout / connection refused | ✅ Yes |
+| `4xx` client errors (bad key, bad request) | ❌ No — these are your bugs, not provider failures |
+
+<Callout type="info">
+Once content has started streaming to the client, fallback is not attempted. You cannot restart a stream mid-flight.
+</Callout>
+
+---
+
+## Routing Strategies
+
+Control which model is tried first on each request.
+
+<Tabs items={['Priority (default)', 'Round-Robin']}>
+  <Tab value="Priority (default)">
+    Always tries models in the order defined. First model handles all traffic until it fails.
+
+    ```ts
+    createFallbackChain({
+      models: [primaryModel, backupModel],
+      strategy: 'priority', // default — can be omitted
+    });
+    ```
+  </Tab>
+  <Tab value="Round-Robin">
+    Distributes load evenly. Request 1 starts at model A, request 2 starts at model B, and so on. If the starting model fails, the chain falls through to the next one as usual.
+
+    ```ts
+    createFallbackChain({
+      models: [openaiModel, anthropicModel],
+      strategy: 'round-robin',
+    });
+    ```
+
+    <Callout type="info">
+    **Multi-instance deployments:** Round-robin state is in-memory by default and resets on restart. For shared state across instances, plug in a custom store (Redis, Upstash, etc.) via the `store` option.
+    </Callout>
+  </Tab>
+</Tabs>
+
+---
+
+## Per-Model Retries
+
+Retry the same model before moving to the next one. Useful for transient errors like brief rate limits or flaky connections.
+
+```ts
+createFallbackChain({
+  models: [openaiModel, anthropicModel],
+  retries: 2,                  // retry each model up to 2 times
+  retryDelay: 500,             // base delay: 500ms
+  retryBackoff: 'exponential', // 500ms → 1000ms → 2000ms (default)
+  onRetry: ({ model, retryAttempt, maxRetries, delayMs, error }) => {
+    console.warn(`[retry] ${model} attempt ${retryAttempt}/${maxRetries} — waiting ${delayMs}ms`);
+  },
+});
+```
+
+**Backoff options:**
+
+| `retryBackoff` | Pattern (retryDelay=500) |
+|---|---|
+| `exponential` (default) | 500ms → 1000ms → 2000ms |
+| `fixed` | 500ms → 500ms → 500ms |
+
+<Callout type="info">
+With `retries: 2`, each model gets 3 total attempts (1 initial + 2 retries) before the chain moves to the next model.
+</Callout>
+
+---
+
+## Observability Callbacks
+
+Two callbacks give you visibility into what the chain is doing.
+
+```ts
+createFallbackChain({
+  models: [openaiModel, anthropicModel, googleModel],
+
+  // Fires on each per-model retry (before the wait delay)
+  onRetry: ({ model, provider, error, retryAttempt, maxRetries, delayMs }) => {
+    console.warn(`[retry] ${provider}/${model} — attempt ${retryAttempt}/${maxRetries}`);
+    metrics.increment('llm.retry', { provider, model });
+  },
+
+  // Fires when a model is abandoned and the next one is tried
+  onFallback: ({ attemptedModel, nextModel, error, attempt }) => {
+    console.warn(`[fallback] ${attemptedModel} → ${nextModel}: ${error.message}`);
+    metrics.increment('llm.fallback', { from: attemptedModel, to: nextModel });
+  },
+});
+```
+
+---
+
+## Handling Full Failure
+
+When every model in the chain fails, `FallbackExhaustedError` is thrown. It includes a per-model breakdown of what failed.
+
+```ts
+import { FallbackExhaustedError } from '@yourgpt/llm-sdk/fallback';
+
+try {
+  await runtime.stream(req.body).pipeToResponse(res);
+} catch (err) {
+  if (err instanceof FallbackExhaustedError) {
+    // Per-model breakdown
+    for (const f of err.failures) {
+      console.error(
+        `${f.provider}/${f.model} failed after ${f.retriesAttempted} retries: ${f.error.message}`
+      );
+    }
+    res.status(503).json({ error: 'All models unavailable. Try again later.' });
+  }
+}
+```
+
+---
+
+## Custom Error Filtering
+
+By default the chain uses sensible rules (5xx, 429, network errors trigger fallback; 4xx does not). Override with `retryableErrors` for custom logic.
+
+```ts
+createFallbackChain({
+  models: [openaiModel, anthropicModel],
+
+  // Fall back on any error at all
+  retryableErrors: () => true,
+
+  // Or — only fall back on rate limits
+  retryableErrors: (err) => {
+    return err instanceof Error && /429|rate.?limit/i.test(err.message);
+  },
+});
+```
+
+---
+
+## Shared Routing Store (Multi-Instance)
+
+For round-robin to work correctly across multiple server instances or serverless functions, plug in a shared store.
+
+```ts
+import { createFallbackChain, type RoutingStore } from '@yourgpt/llm-sdk/fallback';
+
+// Implement RoutingStore with any backend — Redis, Upstash, Cloudflare KV, etc.
+// The SDK ships the interface. You own the implementation.
+const redisStore: RoutingStore = {
+  async get(key) {
+    const val = await redis.get(key);
+    return val ? Number(val) : undefined;
+  },
+  async set(key, value) {
+    await redis.set(key, String(value));
+  },
+};
+
+createFallbackChain({
+  models: [openaiModel, anthropicModel],
+  strategy: 'round-robin',
+  store: redisStore,
+});
+```
+
+<Callout type="info">
+The default `MemoryRoutingStore` is zero-config and works for single-process apps. No store configuration is needed unless you run multiple instances.
+</Callout>
+
+---
+
+## With Tools
+
+Tools work transparently across fallback providers. Define your tools once — whichever provider handles the request formats them natively.
+
+```ts
+const runtime = createRuntime({
+  adapter: createFallbackChain({
+    models: [openaiModel, anthropicModel],
+  }),
+  tools: [
+    {
+      name: 'get_weather',
+      description: 'Get current weather for a city',
+      location: 'server',
+      inputSchema: {
+        type: 'object',
+        properties: { city: { type: 'string' } },
+        required: ['city'],
+      },
+      handler: async ({ city }) => fetchWeather(city),
+    },
+  ],
+});
+```
+
+OpenAI receives tools as function-calling JSON. Anthropic receives them as `tool_use` blocks. **Your handler always runs on your server regardless of which provider responded.**
+
+---
+
+## Full Configuration Reference
+
+```ts
+import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+
+createFallbackChain({
+  // Required: adapters to try in order
+  models: LLMAdapter[],
+
+  // Routing strategy (default: 'priority')
+  strategy?: 'priority' | 'round-robin',
+
+  // Pluggable store for round-robin state (default: MemoryRoutingStore)
+  store?: RoutingStore,
+
+  // Retries per model before moving to next (default: 0)
+  retries?: number,
+
+  // Base delay between retries in ms (default: 500)
+  retryDelay?: number,
+
+  // Backoff strategy (default: 'exponential')
+  retryBackoff?: 'exponential' | 'fixed',
+
+  // Called on each per-model retry attempt
+  onRetry?: (info: RetryInfo) => void,
+
+  // Called when a model is abandoned and next one is tried
+  onFallback?: (info: FallbackInfo) => void,
+
+  // Custom predicate to decide which errors trigger fallback/retry
+  retryableErrors?: (error: unknown) => boolean,
+})
+```
+
+---
+
+## Next Steps
+
+- [OpenAI](/docs/providers/openai) — Configure your primary provider
+- [Anthropic](/docs/providers/anthropic) — Add a Claude fallback
+- [Server Storage](/docs/server/storage) — Persist sessions alongside fallback chains
diff --git a/apps/docs/content/docs/providers/index.mdx b/apps/docs/content/docs/providers/index.mdx
index 7d5b8ac..3d31231 100644
--- a/apps/docs/content/docs/providers/index.mdx
+++ b/apps/docs/content/docs/providers/index.mdx
@@ -162,3 +162,26 @@ Google and xAI use OpenAI-compatible endpoints. Ollama runs locally and needs no
 | Google | Fast | Very Good | $ | Multimodal |
 | xAI | Ultra Fast | Excellent | $ | Speed-critical apps |
 | Ollama | Varies | Good-Excellent | Free | Privacy, offline, development |
+
+---
+
+## Fallback Chain
+
+Use multiple providers together for automatic failover and load distribution.
+
+```ts
+import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+
+const runtime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel('gpt-5.4'),
+      anthropic.languageModel('claude-haiku-4-5'),
+    ],
+    strategy: 'round-robin',
+    retries: 2,
+  }),
+});
+```
+
+[Fallback Chain docs →](/docs/providers/fallback)
diff --git a/apps/docs/content/docs/providers/meta.json b/apps/docs/content/docs/providers/meta.json
index e0a5f18..31e4c3f 100644
--- a/apps/docs/content/docs/providers/meta.json
+++ b/apps/docs/content/docs/providers/meta.json
@@ -1,5 +1,13 @@
 {
   "title": "Providers",
   "icon": "Brain",
-  "pages": ["openai", "anthropic", "google", "xai", "ollama", "custom-provider"]
+  "pages": [
+    "openai",
+    "anthropic",
+    "google",
+    "xai",
+    "ollama",
+    "custom-provider",
+    "fallback"
+  ]
 }
diff --git a/examples/fallback-demo/README.md b/examples/fallback-demo/README.md
new file mode 100644
index 0000000..4538060
--- /dev/null
+++ b/examples/fallback-demo/README.md
@@ -0,0 +1,119 @@
+# Fallback Demo
+
+> Demonstrates `createFallbackChain()` from `@yourgpt/llm-sdk/fallback` — automatic failover, round-robin load distribution, per-model retries, and tools across multiple LLM providers.
+
+## Features Showcased
+
+- **Priority fallback** — OpenAI first, Anthropic if it fails
+- **Round-robin** — distributes load evenly across providers
+- **4xx does NOT trigger fallback** — bad API key throws immediately
+- **Forced fallback** — dead primary URL → Anthropic picks up
+- **Per-model retries** — retry same model N times before falling back
+- **Tools in streaming mode** — tools work transparently across providers
+- **Tools in non-streaming mode** — full JSON response with tool results
+- **FallbackExhaustedError** — structured error when all models fail
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- **pnpm** (required for workspace setup)
+- OpenAI API key
+- Anthropic API key
+
+### Installation
+
+```bash
+# From the monorepo root
+pnpm install
+
+# Set up environment
+cp examples/fallback-demo/.env.example examples/fallback-demo/.env
+# Edit .env and add your keys
+
+# Run the demo
+cd examples/fallback-demo
+pnpm dev
+```
+
+Server runs on [http://localhost:3000](http://localhost:3000)
+
+## Environment Variables
+
+```bash
+OPENAI_API_KEY=your-openai-key
+ANTHROPIC_API_KEY=your-anthropic-key
+```
+
+## API Endpoints
+
+| Endpoint                         | Description                                 |
+| -------------------------------- | ------------------------------------------- |
+| `POST /chat/priority`            | OpenAI first, Anthropic fallback            |
+| `POST /chat/round-robin`         | Alternates OpenAI / Anthropic per request   |
+| `POST /chat/bad-key`             | 4xx error — fallback NOT triggered          |
+| `POST /chat/fallback-test`       | Dead primary URL → Anthropic picks up       |
+| `POST /chat/stream/tools`        | Streaming with 3 server-side tools          |
+| `POST /chat/tools`               | Non-streaming JSON with tool results        |
+| `POST /chat/fallback-test/tools` | Forced fallback + tools (Anthropic handles) |
+| `POST /chat/retry-test`          | 2 retries on dead model before fallback     |
+
+## Test Commands
+
+### Basic fallback
+
+```bash
+curl -s -X POST http://localhost:3000/chat/priority \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Say hello"}]}'
+```
+
+### Forced fallback (dead primary → Anthropic)
+
+```bash
+curl -s -X POST http://localhost:3000/chat/fallback-test \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Which model are you?"}]}'
+```
+
+### Tools via streaming
+
+```bash
+curl -s -X POST http://localhost:3000/chat/stream/tools \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"What is the weather in Tokyo and what time is it?"}]}'
+```
+
+### Non-streaming with tools
+
+```bash
+curl -s -X POST http://localhost:3000/chat/tools \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Calculate 42 * 7 and get the weather in London"}]}'
+```
+
+### Retries before fallback (watch server logs)
+
+```bash
+curl -s -X POST http://localhost:3000/chat/retry-test \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## Project Structure
+
+```
+fallback-demo/
+├── src/
+│   └── index.ts    # Express server with all routes
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Important Notes
+
+> **Workspace Dependency**: Uses `workspace:*` dependencies. Run `pnpm install` from the monorepo root — `npm install` will not work.
+
+> **Tools are provider-agnostic**: Tool definitions are written once. Whichever provider handles the request formats them natively (OpenAI function-calling JSON or Anthropic `tool_use` blocks). Tool handlers always run on your server.
diff --git a/examples/fallback-demo/package.json b/examples/fallback-demo/package.json
new file mode 100644
index 0000000..1f38b05
--- /dev/null
+++ b/examples/fallback-demo/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "fallback-demo",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@yourgpt/llm-sdk": "workspace:*",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0",
+    "openai": "^4.77.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}
diff --git a/examples/fallback-demo/src/index.ts b/examples/fallback-demo/src/index.ts
new file mode 100644
index 0000000..dc5a6aa
--- /dev/null
+++ b/examples/fallback-demo/src/index.ts
@@ -0,0 +1,419 @@
+/**
+ * Fallback Chain Demo
+ *
+ * Tests FallbackChain across:
+ *   - Priority fallback (normal)
+ *   - Round-robin load distribution
+ *   - 4xx does NOT trigger fallback (bad key)
+ *   - Forced fallback (dead primary URL → Anthropic picks up)
+ *   - Tools in streaming mode
+ *   - Tools in non-streaming (chat) mode
+ *
+ * Run:
+ *   pnpm dev
+ *
+ * Test:
+ *   curl -s -X POST http://localhost:3000/chat/stream/tools \
+ *     -H "Content-Type: application/json" \
+ *     -d '{"messages":[{"role":"user","content":"What is the weather in Tokyo and what time is it?"}]}'
+ */
+
+import "dotenv/config";
+import express from "express";
+import cors from "cors";
+import { createRuntime, type ToolDefinition } from "@yourgpt/llm-sdk";
+import { createOpenAI } from "@yourgpt/llm-sdk/openai";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
+import {
+  createFallbackChain,
+  FallbackExhaustedError,
+  MemoryRoutingStore,
+  type RoutingStore,
+  type RetryInfo,
+} from "@yourgpt/llm-sdk/fallback";
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+// ─── Providers ────────────────────────────────────────────────────────────────
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+const brokenOpenAI = createOpenAI({ apiKey: "sk-INVALID_KEY_FOR_TESTING" }); // gitleaks:allow
+const deadOpenAI = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseUrl: "http://localhost:19999/v1", // nothing here → ECONNREFUSED
+});
+
+// ─── Tools ────────────────────────────────────────────────────────────────────
+//
+// These are server-side tools. The fallback chain wraps the LLM adapter only —
+// tools always run on our server regardless of which provider is active.
+// The tool definitions are sent to whichever provider ends up handling the request,
+// each formatted in that provider's native format by the adapter.
+
+const WEATHER_DATA: Record<string, { temp: string; condition: string }> = {
+  tokyo: { temp: "18°C", condition: "Partly cloudy" },
+  london: { temp: "12°C", condition: "Rainy" },
+  new_york: { temp: "22°C", condition: "Sunny" },
+  paris: { temp: "15°C", condition: "Overcast" },
+  sydney: { temp: "25°C", condition: "Clear" },
+};
+
+const serverTools: ToolDefinition[] = [
+  {
+    name: "get_weather",
+    description: "Get current weather for a city",
+    location: "server",
+    inputSchema: {
+      type: "object",
+      properties: {
+        city: {
+          type: "string",
+          description: "City name (e.g. Tokyo, London, New York)",
+        },
+      },
+      required: ["city"],
+    },
+    handler: async (params) => {
+      const { city } = params as { city: string };
+      const key = city.toLowerCase().replace(/\s+/g, "_");
+      const data = WEATHER_DATA[key] ?? { temp: "20°C", condition: "Unknown" };
+      console.log(
+        `[tool:get_weather] city=${city} → ${data.temp}, ${data.condition}`,
+      );
+      return { city, temperature: data.temp, condition: data.condition };
+    },
+  },
+  {
+    name: "get_server_time",
+    description: "Get the current server date and time",
+    location: "server",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+    handler: async () => {
+      const now = new Date().toISOString();
+      console.log(`[tool:get_server_time] → ${now}`);
+      return { time: now };
+    },
+  },
+  {
+    name: "calculate",
+    description: "Evaluate a simple math expression and return the result",
+    location: "server",
+    inputSchema: {
+      type: "object",
+      properties: {
+        expression: {
+          type: "string",
+          description: "Math expression to evaluate, e.g. '12 * 7 + 5'",
+        },
+      },
+      required: ["expression"],
+    },
+    handler: async (params) => {
+      const { expression } = params as { expression: string };
+      // Safe eval: only allow numbers and basic operators
+      if (!/^[\d\s+\-*/().]+$/.test(expression)) {
+        return { error: "Invalid expression — only basic math allowed" };
+      }
+      // eslint-disable-next-line no-eval
+      const result = Function(`"use strict"; return (${expression})`)();
+      console.log(`[tool:calculate] ${expression} = ${result}`);
+      return { expression, result };
+    },
+  },
+];
+
+// ─── Helper: fallback chain factory ──────────────────────────────────────────
+
+function onFallbackLog(label: string) {
+  return ({
+    attemptedModel,
+    nextModel,
+    error,
+    attempt,
+  }: {
+    attemptedModel: string;
+    nextModel: string;
+    error: Error;
+    attempt: number;
+  }) => {
+    console.warn(
+      `[fallback:${label}] attempt ${attempt}: "${attemptedModel}" → "${nextModel}" | ${error.message}`,
+    );
+  };
+}
+
+// ─── Route 1: Priority (no tools) ────────────────────────────────────────────
+
+const priorityRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("priority"),
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/priority", async (req, res) => {
+  try {
+    await priorityRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 2: Round-robin (no tools) ─────────────────────────────────────────
+
+const rrStore: RoutingStore = new MemoryRoutingStore();
+
+const roundRobinRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "round-robin",
+    store: rrStore,
+    onFallback: onFallbackLog("round-robin"),
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/round-robin", async (req, res) => {
+  try {
+    await roundRobinRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 3: 4xx does NOT trigger fallback ───────────────────────────────────
+
+const badKeyRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      brokenOpenAI.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: () => {
+      console.warn(
+        "[fallback:bad-key] UNEXPECTED — fallback triggered for 4xx!",
+      );
+    },
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/bad-key", async (req, res) => {
+  try {
+    await badKeyRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 4: Forced fallback (dead primary URL) ──────────────────────────────
+
+const forcedFallbackRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      deadOpenAI.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("forced"),
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/fallback-test", async (req, res) => {
+  try {
+    await forcedFallbackRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 5: Tools + STREAMING ──────────────────────────────────────────────
+//
+// Primary: OpenAI (gpt-5.4) — formats tools as OpenAI function-calling JSON
+// Fallback: Anthropic (claude-haiku-4-5) — formats tools as Anthropic tool_use JSON
+//
+// The adapter for whichever provider runs transforms the shared ToolDefinition[]
+// into that provider's native format. Tools always execute on our server.
+
+const streamToolsRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("tools-stream"),
+  }),
+  systemPrompt:
+    "You are a helpful assistant with access to weather, time, and calculator tools. Use tools when relevant.",
+  tools: serverTools,
+});
+
+app.post("/chat/stream/tools", async (req, res) => {
+  try {
+    await streamToolsRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 6: Tools + NON-STREAMING (chat) ───────────────────────────────────
+//
+// Same chain and tools as above but using runtime.chat() which
+// collects the full response before returning JSON.
+
+const chatToolsRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("tools-chat"),
+  }),
+  systemPrompt:
+    "You are a helpful assistant with access to weather, time, and calculator tools. Use tools when relevant.",
+  tools: serverTools,
+});
+
+app.post("/chat/tools", async (req, res) => {
+  try {
+    const result = await chatToolsRuntime.chat(req.body);
+    res.json(result);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 8: Retries before fallback ────────────────────────────────────────
+//
+// retries: 2  → tries dead primary 3 times total (initial + 2 retries) before
+//              giving up and falling back to Anthropic.
+// retryDelay: 300ms, retryBackoff: 'exponential' → 300ms, 600ms waits
+// onRetry fires on each retry attempt so you can see it in the server log.
+
+const retriesRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      deadOpenAI.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    retries: 2,
+    retryDelay: 300,
+    retryBackoff: "exponential",
+    onRetry: ({
+      model,
+      retryAttempt,
+      maxRetries,
+      delayMs,
+      error,
+    }: RetryInfo) => {
+      console.warn(
+        `[retry] ${model} — attempt ${retryAttempt}/${maxRetries}, waiting ${delayMs}ms | ${error.message}`,
+      );
+    },
+    onFallback: ({ attemptedModel, nextModel, attempt }) => {
+      console.warn(
+        `[fallback:retries] ${attemptedModel} exhausted all retries (attempt ${attempt}) → ${nextModel}`,
+      );
+    },
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/retry-test", async (req, res) => {
+  try {
+    await retriesRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 7: Tools + FORCED FALLBACK (dead primary) ─────────────────────────
+//
+// Same tools, but primary is a dead URL.
+// Anthropic picks up and handles tool calls in its own format.
+
+const forcedToolsRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      deadOpenAI.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("tools-forced"),
+  }),
+  systemPrompt:
+    "You are a helpful assistant with access to weather, time, and calculator tools. Use tools when relevant.",
+  tools: serverTools,
+});
+
+app.post("/chat/fallback-test/tools", async (req, res) => {
+  try {
+    await forcedToolsRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Error helper ─────────────────────────────────────────────────────────────
+
+function handleError(err: unknown, res: express.Response) {
+  if (err instanceof FallbackExhaustedError) {
+    res.status(503).json({
+      error: "All models in fallback chain failed",
+      detail: err.failures.map(
+        (f) => `${f.provider}/${f.model}: ${f.error.message}`,
+      ),
+    });
+  } else {
+    res.status(500).json({ error: String(err) });
+  }
+}
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`\nFallback Demo running at http://localhost:${PORT}\n`);
+  console.log("── Basic routes ──────────────────────────────────────────────");
+  console.log(
+    "  POST /chat/priority            — OpenAI first, Claude fallback",
+  );
+  console.log("  POST /chat/round-robin         — Alternates OpenAI / Claude");
+  console.log("  POST /chat/bad-key             — 4xx: fallback NOT triggered");
+  console.log(
+    "  POST /chat/fallback-test       — Dead primary → Claude picks up",
+  );
+  console.log(
+    "\n── Tool routes ───────────────────────────────────────────────",
+  );
+  console.log(
+    "  POST /chat/stream/tools        — Tools via streaming (OpenAI primary)",
+  );
+  console.log(
+    "  POST /chat/tools               — Tools via non-streaming JSON",
+  );
+  console.log(
+    "  POST /chat/fallback-test/tools — Tools via streaming (forced fallback → Claude)",
+  );
+  console.log(
+    "  POST /chat/retry-test          — Retries dead model 2x before falling back to Claude",
+  );
+});
diff --git a/examples/fallback-demo/tsconfig.json b/examples/fallback-demo/tsconfig.json
new file mode 100644
index 0000000..12a87ac
--- /dev/null
+++ b/examples/fallback-demo/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}
diff --git a/packages/llm-sdk/package.json b/packages/llm-sdk/package.json
index 5a914f6..d9a5b25 100644
--- a/packages/llm-sdk/package.json
+++ b/packages/llm-sdk/package.json
@@ -55,6 +55,11 @@
       "types": "./dist/yourgpt/index.d.ts",
       "import": "./dist/yourgpt/index.mjs",
       "require": "./dist/yourgpt/index.js"
+    },
+    "./fallback": {
+      "types": "./dist/fallback/index.d.ts",
+      "import": "./dist/fallback/index.mjs",
+      "require": "./dist/fallback/index.js"
     }
   },
   "homepage": "https://copilot-sdk.yourgpt.ai",
diff --git a/packages/llm-sdk/src/fallback/chain.ts b/packages/llm-sdk/src/fallback/chain.ts
new file mode 100644
index 0000000..aada23c
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/chain.ts
@@ -0,0 +1,425 @@
+import type {
+  LLMAdapter,
+  ChatCompletionRequest,
+  CompletionResult,
+} from "../adapters/base";
+import type { StreamEvent } from "../core/stream-events";
+import type { FallbackChainConfig, FallbackFailure, RetryInfo } from "./types";
+import { FallbackExhaustedError } from "./errors";
+import { MemoryRoutingStore } from "./routing-store";
+
+// Stable key used for round-robin state in the store
+const ROUND_ROBIN_KEY = "ygpt_fallback_rr_index";
+
+/**
+ * Determine whether an error should trigger a retry or fallback.
+ *
+ * Covers all error shapes across provider SDKs:
+ *
+ * OpenAI SDK (@openai/openai-node):
+ *   RateLimitError          → status=429
+ *   InternalServerError     → status>=500
+ *   APIConnectionError      → status=undefined, message="Connection error."
+ *   APIConnectionTimeoutError → status=undefined, message="Request timed out."
+ *   APIUserAbortError       → status=undefined, message="Aborted"  ← NOT retryable
+ *   BadRequestError etc     → status=4xx                          ← NOT retryable
+ *
+ * Anthropic SDK (@anthropic-ai/sdk) — identical class/message shapes to OpenAI SDK.
+ *
+ * Google SDK & Ollama — fall through to message-based detection.
+ *
+ * In streaming mode: adapters swallow thrown errors and yield { type:"error", message }.
+ * The fallback chain creates `new Error(message)` from those, so only message survives.
+ * Message-based detection handles that path.
+ *
+ * In complete() mode: real SDK class instances are thrown, so constructor.name + status checks fire.
+ */
+function defaultIsRetryable(error: unknown): boolean {
+  if (typeof error === "object" && error !== null) {
+    const ctorName = (error as object).constructor?.name ?? "";
+
+    // ── Explicit NOT-retryable classes ────────────────────────────────────
+    // User aborted the request — never retry, never fall back
+    if (ctorName === "APIUserAbortError") return false;
+
+    // ── Explicit retryable classes (no status property) ───────────────────
+    // Both OpenAI and Anthropic SDKs use these exact class names.
+    if (ctorName === "APIConnectionError") return true;
+    if (ctorName === "APIConnectionTimeoutError") return true;
+
+    // ── HTTP status code check (OpenAI, Anthropic, Google, etc.) ──────────
+    // Both SDKs expose the numeric HTTP status on `.status`.
+    // `.statusCode` covers some older / third-party adapters.
+    const status =
+      (error as { status?: unknown }).status ??
+      (error as { statusCode?: unknown }).statusCode;
+
+    if (typeof status === "number") {
+      if (status === 429) return true; // rate limit
+      if (status >= 500) return true; // 500, 502, 503, 504, 520-527 (Cloudflare), etc.
+      if (status >= 400) return false; // 400-428, 430-499 — caller bug, don't retry
+    }
+  }
+
+  // ── Message-based detection ───────────────────────────────────────────────
+  // Used when errors have been serialised to plain Error objects:
+  //   • stream mode — adapters yield { type:"error", message } instead of throwing
+  //   • Google SDK / Ollama — don't use OpenAI/Anthropic SDK class names
+  if (error instanceof Error) {
+    const msg = error.message;
+
+    // Hard-stop: user-initiated abort.
+    // Node.js AbortController: "The operation was aborted"
+    // Browser fetch AbortController: "The user aborted a request"
+    // These must never trigger a retry or fallback.
+    if (/the operation was aborted/i.test(msg)) return false;
+    if (/the user aborted a request/i.test(msg)) return false;
+
+    // Hard-stop: any 4xx that is NOT 429.
+    // e.g. "401 Incorrect API key", "403 Forbidden", "404 Not found"
+    if (/\b4[0-9]{2}\b/.test(msg) && !/\b429\b/.test(msg)) return false;
+
+    // ── Retryable: rate limit ──────────────────────────────────────────────
+    // OpenAI stream error event: "429 You exceeded your current quota…"
+    // Anthropic stream error event: "429 {"error":{"type":"rate_limit_error"…}}"
+    if (/\b429\b/.test(msg)) return true;
+    if (/rate[\s_-]?limit/i.test(msg)) return true;
+    if (/too many requests/i.test(msg)) return true;
+    if (/quota exceeded/i.test(msg)) return true; // Google
+
+    // ── Retryable: 5xx server errors ──────────────────────────────────────
+    if (/\b5[0-9]{2}\b/.test(msg)) return true; // any 5xx in message
+    if (/internal server error/i.test(msg)) return true;
+    if (/service unavailable/i.test(msg)) return true;
+    if (/bad gateway/i.test(msg)) return true;
+    if (/gateway timeout/i.test(msg)) return true;
+    if (/overloaded/i.test(msg)) return true; // Anthropic "overloaded_error"
+
+    // ── Retryable: connection / timeout ───────────────────────────────────
+    // OpenAI SDK APIConnectionError exact message:
+    if (/^connection error\.?$/i.test(msg)) return true;
+    // OpenAI SDK APIConnectionTimeoutError exact message:
+    if (/^request timed out\.?$/i.test(msg)) return true;
+    // General timeout patterns (Google SDK, Ollama, custom adapters)
+    if (/timed?\s*out/i.test(msg)) return true;
+    if (/timeout/i.test(msg)) return true;
+    // fetch() failure (browser + Node.js undici)
+    if (/fetch failed/i.test(msg)) return true;
+
+    // ── Retryable: Node.js network error codes ────────────────────────────
+    // These appear in the message when a raw network error bubbles up.
+    if (/ECONNREFUSED/.test(msg)) return true; // connection refused
+    if (/ECONNRESET/.test(msg)) return true; // connection reset by peer
+    if (/ETIMEDOUT/.test(msg)) return true; // TCP timeout
+    if (/ENOTFOUND/.test(msg)) return true; // DNS lookup failure
+    if (/ENETUNREACH/.test(msg)) return true; // no route to host
+    if (/EHOSTUNREACH/.test(msg)) return true; // host unreachable
+  }
+
+  return false;
+}
+
+/** Calculate delay for a given retry attempt */
+function calcDelay(
+  base: number,
+  attempt: number,
+  backoff: "exponential" | "fixed",
+): number {
+  if (backoff === "fixed") return base;
+  return base * Math.pow(2, attempt - 1); // exponential: base, base*2, base*4...
+}
+
+/** Sleep helper */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Internal resolved config type ───────────────────────────────────────────
+
+type ResolvedConfig = Required<
+  Omit<FallbackChainConfig, "onFallback" | "onRetry" | "retryableErrors">
+> &
+  Pick<FallbackChainConfig, "onFallback" | "onRetry" | "retryableErrors">;
+
+// ─── FallbackChain ────────────────────────────────────────────────────────────
+
+class FallbackChain implements LLMAdapter {
+  private readonly _config: ResolvedConfig;
+
+  constructor(config: FallbackChainConfig) {
+    if (config.models.length === 0) {
+      throw new Error("FallbackChain requires at least one model.");
+    }
+
+    this._config = {
+      models: config.models,
+      strategy: config.strategy ?? "priority",
+      store: config.store ?? new MemoryRoutingStore(),
+      retries: config.retries ?? 0,
+      retryDelay: config.retryDelay ?? 500,
+      retryBackoff: config.retryBackoff ?? "exponential",
+      onFallback: config.onFallback,
+      onRetry: config.onRetry,
+      retryableErrors: config.retryableErrors,
+    };
+  }
+
+  get provider(): string {
+    return "fallback-chain";
+  }
+
+  get model(): string {
+    return this._config.models.map((m) => `${m.provider}/${m.model}`).join(",");
+  }
+
+  private async _startIndex(): Promise<number> {
+    if (this._config.strategy !== "round-robin") return 0;
+    const stored = await this._config.store.get(ROUND_ROBIN_KEY);
+    return typeof stored === "number" ? stored % this._config.models.length : 0;
+  }
+
+  private async _advanceIndex(successfulIndex: number): Promise<void> {
+    if (this._config.strategy !== "round-robin") return;
+    const next = (successfulIndex + 1) % this._config.models.length;
+    await this._config.store.set(ROUND_ROBIN_KEY, next);
+  }
+
+  private _isRetryable(error: unknown): boolean {
+    return this._config.retryableErrors
+      ? this._config.retryableErrors(error)
+      : defaultIsRetryable(error);
+  }
+
+  /**
+   * Try streaming from a single adapter, with per-model retries.
+   *
+   * Returns an async generator that either:
+   *   - yields all chunks on success, then returns
+   *   - throws the final error if all retries exhausted or error is non-retryable
+   *
+   * The `retriesAttempted` out-param is filled via the returned object so callers
+   * can record it in FallbackFailure.
+   */
+  private async *_streamWithRetries(
+    adapter: LLMAdapter,
+    request: ChatCompletionRequest,
+    out: { retriesAttempted: number },
+  ): AsyncGenerator<StreamEvent> {
+    const { retries, retryDelay, retryBackoff, onRetry } = this._config;
+    const maxAttempts = retries + 1; // initial attempt + retries
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      let contentStarted = false;
+      let failureError: Error | null = null;
+
+      try {
+        for await (const chunk of adapter.stream(request)) {
+          if (chunk.type === "error") {
+            if (!contentStarted) {
+              const msg =
+                (chunk as { type: "error"; message?: string }).message ??
+                "Unknown error";
+              failureError = new Error(msg);
+              break;
+            }
+            yield chunk;
+            return;
+          }
+
+          if (chunk.type === "message:start") continue;
+
+          contentStarted = true;
+          yield chunk;
+        }
+      } catch (error) {
+        if (contentStarted) throw error;
+        if (!this._isRetryable(error)) throw error;
+        failureError =
+          error instanceof Error ? error : new Error(String(error));
+      }
+
+      if (failureError === null) return; // success
+
+      // Non-retryable (4xx) — checked in catch above, but also check error-event path
+      if (!this._isRetryable(failureError)) throw failureError;
+
+      out.retriesAttempted = attempt - 1; // attempts so far beyond initial
+
+      // If we have more retries left, wait then retry the same model
+      if (attempt < maxAttempts) {
+        const delayMs = calcDelay(retryDelay, attempt, retryBackoff);
+        const retryInfo: RetryInfo = {
+          model: adapter.model,
+          provider: adapter.provider,
+          error: failureError,
+          retryAttempt: attempt,
+          maxRetries: retries,
+          delayMs,
+        };
+        onRetry?.(retryInfo);
+        await sleep(delayMs);
+        continue;
+      }
+
+      // All retries for this model exhausted — throw so the outer loop can try next model
+      out.retriesAttempted = retries;
+      throw failureError;
+    }
+  }
+
+  async *stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent> {
+    const { models, onFallback } = this._config;
+    const startIndex = await this._startIndex();
+    const failures: FallbackFailure[] = [];
+
+    for (let i = 0; i < models.length; i++) {
+      const index = (startIndex + i) % models.length;
+      const adapter = models[index];
+      const out = { retriesAttempted: 0 };
+
+      try {
+        yield* this._streamWithRetries(adapter, request, out);
+        // Success
+        await this._advanceIndex(index);
+        return;
+      } catch (error) {
+        // Non-retryable (4xx) — rethrow immediately, don't try next model
+        if (!this._isRetryable(error)) throw error;
+
+        const failure: FallbackFailure = {
+          model: adapter.model,
+          provider: adapter.provider,
+          error: error instanceof Error ? error : new Error(String(error)),
+          attempt: i + 1,
+          retriesAttempted: out.retriesAttempted,
+        };
+        failures.push(failure);
+
+        const nextOffset = i + 1;
+        if (nextOffset < models.length && onFallback) {
+          const nextIndex = (startIndex + nextOffset) % models.length;
+          onFallback({
+            attemptedModel: adapter.model,
+            nextModel: models[nextIndex].model,
+            error: failure.error,
+            attempt: failure.attempt,
+          });
+        }
+      }
+    }
+
+    throw new FallbackExhaustedError(failures);
+  }
+
+  async complete(request: ChatCompletionRequest): Promise<CompletionResult> {
+    const { models, onFallback, retries, retryDelay, retryBackoff, onRetry } =
+      this._config;
+    const startIndex = await this._startIndex();
+    const failures: FallbackFailure[] = [];
+
+    for (let i = 0; i < models.length; i++) {
+      const index = (startIndex + i) % models.length;
+      const adapter = models[index];
+
+      if (!adapter.complete) {
+        failures.push({
+          model: adapter.model,
+          provider: adapter.provider,
+          error: new Error(
+            `Adapter ${adapter.provider}/${adapter.model} does not implement complete()`,
+          ),
+          attempt: i + 1,
+          retriesAttempted: 0,
+        });
+        continue;
+      }
+
+      const maxAttempts = retries + 1;
+      let lastError: Error | null = null;
+      let retriesAttempted = 0;
+
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          const result = await adapter.complete(request);
+          await this._advanceIndex(index);
+          return result;
+        } catch (error) {
+          if (!this._isRetryable(error)) throw error;
+
+          lastError = error instanceof Error ? error : new Error(String(error));
+          retriesAttempted = attempt - 1;
+
+          if (attempt < maxAttempts) {
+            const delayMs = calcDelay(retryDelay, attempt, retryBackoff);
+            onRetry?.({
+              model: adapter.model,
+              provider: adapter.provider,
+              error: lastError,
+              retryAttempt: attempt,
+              maxRetries: retries,
+              delayMs,
+            });
+            await sleep(delayMs);
+          }
+        }
+      }
+
+      const failure: FallbackFailure = {
+        model: adapter.model,
+        provider: adapter.provider,
+        error: lastError!,
+        attempt: i + 1,
+        retriesAttempted,
+      };
+      failures.push(failure);
+
+      const nextOffset = i + 1;
+      if (nextOffset < models.length && onFallback) {
+        const nextIndex = (startIndex + nextOffset) % models.length;
+        onFallback({
+          attemptedModel: adapter.model,
+          nextModel: models[nextIndex].model,
+          error: failure.error,
+          attempt: failure.attempt,
+        });
+      }
+    }
+
+    throw new FallbackExhaustedError(failures);
+  }
+}
+
+/**
+ * Create a fallback chain that tries each model in order, with optional
+ * per-model retries before moving to the next model.
+ *
+ * @example
+ * ```typescript
+ * import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+ * import { createRuntime } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+ * import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+ *
+ * const chain = createFallbackChain({
+ *   models: [
+ *     createOpenAI({ apiKey: '...' }).languageModel('gpt-5.4'),
+ *     createAnthropic({ apiKey: '...' }).languageModel('claude-haiku-4-5'),
+ *   ],
+ *   retries: 2,              // retry each model up to 2 times before moving on
+ *   retryDelay: 500,         // 500ms → 1000ms (exponential)
+ *   retryBackoff: 'exponential',
+ *   strategy: 'round-robin',
+ *   onRetry: ({ model, retryAttempt, maxRetries, delayMs, error }) => {
+ *     console.warn(`[retry] ${model} attempt ${retryAttempt}/${maxRetries} — waiting ${delayMs}ms`);
+ *   },
+ *   onFallback: ({ attemptedModel, nextModel, attempt }) => {
+ *     console.warn(`[fallback] ${attemptedModel} gave up after retries → ${nextModel}`);
+ *   },
+ * });
+ *
+ * const runtime = createRuntime({ adapter: chain });
+ * ```
+ */
+export function createFallbackChain(config: FallbackChainConfig): LLMAdapter {
+  return new FallbackChain(config);
+}
diff --git a/packages/llm-sdk/src/fallback/errors.ts b/packages/llm-sdk/src/fallback/errors.ts
new file mode 100644
index 0000000..b6a00eb
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/errors.ts
@@ -0,0 +1,43 @@
+import type { FallbackFailure } from "./types";
+
+/**
+ * Thrown when every model in the fallback chain has failed.
+ *
+ * The `failures` array provides a per-model breakdown of what failed
+ * and why, so you can log or surface the full picture.
+ *
+ * @example
+ * ```typescript
+ * import { FallbackExhaustedError } from '@yourgpt/llm-sdk/fallback';
+ *
+ * try {
+ *   const result = await runtime.chat(request);
+ * } catch (err) {
+ *   if (err instanceof FallbackExhaustedError) {
+ *     for (const f of err.failures) {
+ *       console.error(`${f.provider}/${f.model} (attempt ${f.attempt}): ${f.error.message}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class FallbackExhaustedError extends Error {
+  /** Per-model breakdown of every failed attempt */
+  readonly failures: FallbackFailure[];
+
+  constructor(failures: FallbackFailure[]) {
+    const summary = failures
+      .map((f) => `${f.provider}/${f.model}: ${f.error.message}`)
+      .join("; ");
+
+    super(
+      `All ${failures.length} model(s) in the fallback chain failed. ${summary}`,
+    );
+
+    this.name = "FallbackExhaustedError";
+    this.failures = failures;
+
+    // Preserve prototype chain in transpiled environments
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
diff --git a/packages/llm-sdk/src/fallback/index.ts b/packages/llm-sdk/src/fallback/index.ts
new file mode 100644
index 0000000..e1bce5d
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/index.ts
@@ -0,0 +1,43 @@
+/**
+ * @yourgpt/llm-sdk/fallback
+ *
+ * Fallback Chain & Routing Strategies
+ *
+ * Automatically retries failed LLM requests with backup models.
+ * Supports priority (default) and round-robin routing strategies.
+ *
+ * @example
+ * ```typescript
+ * import { createFallbackChain, MemoryRoutingStore } from '@yourgpt/llm-sdk/fallback';
+ * import { createRuntime } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+ * import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+ *
+ * const chain = createFallbackChain({
+ *   models: [
+ *     createOpenAI({ apiKey: '...' }).languageModel('gpt-4o'),
+ *     createAnthropic({ apiKey: '...' }).languageModel('claude-3-5-sonnet-20241022'),
+ *   ],
+ *   strategy: 'round-robin',
+ *   onFallback: ({ attemptedModel, nextModel, error, attempt }) => {
+ *     console.warn(`Attempt ${attempt}: ${attemptedModel} failed, trying ${nextModel}`);
+ *   },
+ * });
+ *
+ * const runtime = createRuntime({ adapter: chain });
+ * ```
+ */
+
+export { createFallbackChain } from "./chain";
+export { FallbackExhaustedError } from "./errors";
+export { MemoryRoutingStore } from "./routing-store";
+
+export type {
+  RoutingStore,
+  RoutingStrategy,
+  RetryBackoff,
+  FallbackChainConfig,
+  FallbackFailure,
+  FallbackInfo,
+  RetryInfo,
+} from "./types";
diff --git a/packages/llm-sdk/src/fallback/routing-store.ts b/packages/llm-sdk/src/fallback/routing-store.ts
new file mode 100644
index 0000000..95b9ea8
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/routing-store.ts
@@ -0,0 +1,36 @@
+import type { RoutingStore } from "./types";
+
+/**
+ * Built-in in-memory routing store.
+ *
+ * Works out of the box for single-process applications.
+ * State resets on restart and is NOT shared across instances.
+ *
+ * For production multi-instance or serverless deployments,
+ * implement your own RoutingStore backed by Redis, Upstash,
+ * Cloudflare KV, DynamoDB, or any other persistent store.
+ *
+ * @example
+ * ```typescript
+ * // Default — created automatically by createFallbackChain
+ * const chain = createFallbackChain({ models: [...] });
+ *
+ * // Explicit — pass your own store
+ * const chain = createFallbackChain({
+ *   models: [...],
+ *   strategy: 'round-robin',
+ *   store: new MemoryRoutingStore(),
+ * });
+ * ```
+ */
+export class MemoryRoutingStore implements RoutingStore {
+  private readonly _map = new Map<string, number>();
+
+  async get(key: string): Promise<number | undefined> {
+    return this._map.get(key);
+  }
+
+  async set(key: string, value: number): Promise<void> {
+    this._map.set(key, value);
+  }
+}
diff --git a/packages/llm-sdk/src/fallback/types.ts b/packages/llm-sdk/src/fallback/types.ts
new file mode 100644
index 0000000..59f3fc8
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/types.ts
@@ -0,0 +1,236 @@
+/**
+ * Fallback Chain & Routing Strategy Types
+ */
+
+import type { LLMAdapter } from "../adapters/base";
+
+// ============================================
+// Routing Store Interface
+// ============================================
+
+/**
+ * Pluggable state store for routing strategies.
+ *
+ * Round-robin and other stateful strategies use this to persist
+ * which model was last used. The default implementation is in-memory.
+ *
+ * For multi-instance or serverless deployments, plug in your own:
+ * Redis, Upstash, Cloudflare KV, DynamoDB, etc.
+ *
+ * @example
+ * ```typescript
+ * // Redis-backed store (example — bring your own client)
+ * const redisStore: RoutingStore = {
+ *   async get(key) {
+ *     const val = await redis.get(key);
+ *     return val ? Number(val) : undefined;
+ *   },
+ *   async set(key, value) {
+ *     await redis.set(key, value);
+ *   },
+ * };
+ * ```
+ */
+export interface RoutingStore {
+  /** Get the stored value for a key */
+  get(key: string): Promise<number | undefined>;
+  /** Set the stored value for a key */
+  set(key: string, value: number): Promise<void>;
+}
+
+// ============================================
+// Failure & Callback Types
+// ============================================
+
+/**
+ * A single failed model in the fallback chain (after all retries exhausted)
+ */
+export interface FallbackFailure {
+  /** Model ID that failed */
+  model: string;
+  /** Provider name */
+  provider: string;
+  /** The last error from this model */
+  error: Error;
+  /** Which model in the chain this was (1-based) */
+  attempt: number;
+  /** How many times this model was retried before giving up */
+  retriesAttempted: number;
+}
+
+/**
+ * Passed to the onFallback callback when a model is abandoned and the next one is tried
+ */
+export interface FallbackInfo {
+  /** Model that just failed (after all its retries) */
+  attemptedModel: string;
+  /** Model that will be tried next */
+  nextModel: string;
+  /** The last error from the failed model */
+  error: Error;
+  /** Which model in the chain this was (1-based) */
+  attempt: number;
+}
+
+/**
+ * Passed to the onRetry callback on each per-model retry attempt
+ */
+export interface RetryInfo {
+  /** Model being retried */
+  model: string;
+  /** Provider name */
+  provider: string;
+  /** The error that triggered this retry */
+  error: Error;
+  /** Which retry attempt this is (1-based: 1 = first retry after initial failure) */
+  retryAttempt: number;
+  /** Total retries configured for this chain */
+  maxRetries: number;
+  /** How long (ms) we will wait before retrying */
+  delayMs: number;
+}
+
+// ============================================
+// Strategy & Config
+// ============================================
+
+/**
+ * How the chain decides which model to try first.
+ *
+ * - `priority` — always try models in defined order (default)
+ * - `round-robin` — rotate starting model evenly across calls
+ */
+export type RoutingStrategy = "priority" | "round-robin";
+
+/**
+ * Backoff strategy between per-model retries.
+ *
+ * - `exponential` — delay doubles on each retry: 500ms → 1000ms → 2000ms (default)
+ * - `fixed`       — same delay every retry: 500ms → 500ms → 500ms
+ */
+export type RetryBackoff = "exponential" | "fixed";
+
+/**
+ * Configuration for createFallbackChain()
+ */
+export interface FallbackChainConfig {
+  /**
+   * Ordered list of adapters to try.
+   * On failure, the chain moves to the next adapter in this list.
+   *
+   * @example
+   * ```typescript
+   * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+   * import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+   *
+   * const openai = createOpenAI({ apiKey: '...' });
+   * const anthropic = createAnthropic({ apiKey: '...' });
+   *
+   * const chain = createFallbackChain({
+   *   models: [
+   *     openai.languageModel('gpt-4o'),
+   *     anthropic.languageModel('claude-3-5-sonnet-20241022'),
+   *   ],
+   * });
+   * ```
+   */
+  models: LLMAdapter[];
+
+  /**
+   * Routing strategy controlling which model is tried first.
+   * @default 'priority'
+   */
+  strategy?: RoutingStrategy;
+
+  /**
+   * State store for strategies that require persistence (e.g., round-robin).
+   * Defaults to an in-memory store (MemoryRoutingStore).
+   *
+   * Replace with a shared store (Redis, Upstash, etc.) for multi-instance
+   * or serverless deployments where round-robin state must be shared.
+   */
+  store?: RoutingStore;
+
+  /**
+   * Number of times to retry the same model before moving to the next one.
+   *
+   * LiteLLM equivalent: `num_retries`
+   *
+   * @default 0  (no retries — fail immediately and move to next model)
+   *
+   * @example
+   * ```typescript
+   * // Try each model up to 3 times before falling back
+   * createFallbackChain({ models: [...], retries: 3 })
+   * ```
+   */
+  retries?: number;
+
+  /**
+   * Base delay in milliseconds between per-model retries.
+   *
+   * With `retryBackoff: 'exponential'` (default):
+   *   retry 1 → retryDelay ms
+   *   retry 2 → retryDelay * 2 ms
+   *   retry 3 → retryDelay * 4 ms
+   *
+   * With `retryBackoff: 'fixed'`:
+   *   every retry → retryDelay ms
+   *
+   * @default 500
+   */
+  retryDelay?: number;
+
+  /**
+   * Backoff strategy between per-model retries.
+   * @default 'exponential'
+   */
+  retryBackoff?: RetryBackoff;
+
+  /**
+   * Called on each per-model retry attempt (before the delay).
+   * Use for logging, metrics, or alerting per retry.
+   *
+   * @example
+   * ```typescript
+   * onRetry: ({ model, retryAttempt, maxRetries, delayMs, error }) => {
+   *   console.warn(`[retry] ${model} attempt ${retryAttempt}/${maxRetries} — waiting ${delayMs}ms | ${error.message}`);
+   * }
+   * ```
+   */
+  onRetry?: (info: RetryInfo) => void;
+
+  /**
+   * Called each time a model is abandoned and the next one is tried.
+   * Use for logging, metrics, or alerting.
+   *
+   * @example
+   * ```typescript
+   * onFallback: ({ attemptedModel, nextModel, error, attempt }) => {
+   *   console.warn(`[fallback] attempt ${attempt}: ${attemptedModel} failed → ${nextModel}`, error.message);
+   * }
+   * ```
+   */
+  onFallback?: (info: FallbackInfo) => void;
+
+  /**
+   * Custom predicate to decide whether an error should trigger a fallback.
+   *
+   * By default, the following trigger fallback:
+   * - HTTP 5xx server errors
+   * - HTTP 429 rate limit errors
+   * - Network timeouts and connection failures
+   *
+   * The following do NOT trigger fallback by default:
+   * - HTTP 4xx client errors (bad request, invalid API key, etc.)
+   *
+   * Override this to extend or restrict fallback behavior.
+   *
+   * @example
+   * ```typescript
+   * // Also fall back on any error
+   * retryableErrors: () => true,
+   * ```
+   */
+  retryableErrors?: (error: unknown) => boolean;
+}
diff --git a/packages/llm-sdk/src/index.ts b/packages/llm-sdk/src/index.ts
index a5af166..4218f5b 100644
--- a/packages/llm-sdk/src/index.ts
+++ b/packages/llm-sdk/src/index.ts
@@ -218,3 +218,17 @@ export {
   generateToolCallId,
   generateThreadId,
 } from "./core/utils";
+
+// ============================================
+// Fallback Chain & Routing (types only from root)
+// ============================================
+// Full implementation: import from '@yourgpt/llm-sdk/fallback'
+export type {
+  RoutingStore,
+  RoutingStrategy,
+  RetryBackoff,
+  FallbackChainConfig,
+  FallbackFailure,
+  FallbackInfo,
+  RetryInfo,
+} from "./fallback/types";
diff --git a/packages/llm-sdk/tsup.config.ts b/packages/llm-sdk/tsup.config.ts
index 418863c..78f76db 100644
--- a/packages/llm-sdk/tsup.config.ts
+++ b/packages/llm-sdk/tsup.config.ts
@@ -19,6 +19,9 @@ export default defineConfig({
 
     // YourGPT storage adapter
     "yourgpt/index": "src/yourgpt/index.ts",
+
+    // Fallback chain & routing
+    "fallback/index": "src/fallback/index.ts",
   },
   format: ["cjs", "esm"],
   dts: true,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2eb1776..b44c66f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -418,6 +418,40 @@ importers:
         specifier: ^5.6.0
         version: 5.9.3
 
+  examples/fallback-demo:
+    dependencies:
+      '@anthropic-ai/sdk':
+        specifier: ^0.39.0
+        version: 0.39.0
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+      openai:
+        specifier: ^4.77.0
+        version: 4.104.0(ws@8.18.0)(zod@3.25.76)
+    devDependencies:
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+
   examples/headless-slack-demo:
     dependencies:
       '@yourgpt/copilot-sdk':
@@ -1142,40 +1176,6 @@ importers:
         specifier: ^5
         version: 5.9.3
 
-  examples/yourgpt-server-demo:
-    dependencies:
-      '@yourgpt/llm-sdk':
-        specifier: workspace:*
-        version: link:../../packages/llm-sdk
-      cors:
-        specifier: ^2.8.5
-        version: 2.8.6
-      dotenv:
-        specifier: ^16.4.0
-        version: 16.6.1
-      express:
-        specifier: ^4.21.0
-        version: 4.22.1
-      ws:
-        specifier: ^8.18.0
-        version: 8.18.0
-    devDependencies:
-      '@types/cors':
-        specifier: ^2.8.17
-        version: 2.8.19
-      '@types/express':
-        specifier: ^5.0.0
-        version: 5.0.6
-      '@types/ws':
-        specifier: ^8.5.13
-        version: 8.18.1
-      tsx:
-        specifier: ^4.19.0
-        version: 4.21.0
-      typescript:
-        specifier: ^5.6.0
-        version: 5.9.3
-
   packages/copilot-sdk:
     dependencies:
       '@base-ui/react':
@@ -4097,9 +4097,6 @@ packages:
   '@types/validate-npm-package-name@4.0.2':
     resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
 
-  '@types/ws@8.18.1':
-    resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
-
   '@typescript-eslint/eslint-plugin@8.50.0':
     resolution: {integrity: sha512-O7QnmOXYKVtPrfYzMolrCTfkezCJS9+ljLdKW/+DCvRsc3UAz+sbH6Xcsv7p30+0OwUbeWfUDAQE0vpabZ3QLg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -11325,10 +11322,6 @@ snapshots:
 
   '@types/validate-npm-package-name@4.0.2': {}
 
-  '@types/ws@8.18.1':
-    dependencies:
-      '@types/node': 20.19.27
-
   '@typescript-eslint/eslint-plugin@8.50.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@eslint-community/regexpp': 4.12.2

From da36c482349f61755f1201c8a5665e122c204734 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 12:12:24 +0530
Subject: [PATCH 64/72] feat(llm-sdk): add fallback chain & routing strategies

Adds @yourgpt/llm-sdk/fallback subpath export:
- createFallbackChain() with priority and round-robin routing
- Per-model retries with exponential/fixed backoff before fallback
- FallbackExhaustedError with per-model failure breakdown
- MemoryRoutingStore (default) + pluggable RoutingStore interface
- onRetry / onFallback observability callbacks
- Two-tier error detection (class-based for complete(), message-regex for stream())

Includes fallback-demo example and docs page.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/docs/content/docs/providers/fallback.mdx | 314 +++++++++++++
 apps/docs/content/docs/providers/index.mdx    |  23 +
 apps/docs/content/docs/providers/meta.json    |  10 +-
 examples/fallback-demo/README.md              | 119 +++++
 examples/fallback-demo/package.json           |  24 +
 examples/fallback-demo/src/index.ts           | 419 +++++++++++++++++
 examples/fallback-demo/tsconfig.json          |  12 +
 packages/llm-sdk/package.json                 |   5 +
 packages/llm-sdk/src/fallback/chain.ts        | 425 ++++++++++++++++++
 packages/llm-sdk/src/fallback/errors.ts       |  43 ++
 packages/llm-sdk/src/fallback/index.ts        |  43 ++
 .../llm-sdk/src/fallback/routing-store.ts     |  36 ++
 packages/llm-sdk/src/fallback/types.ts        | 236 ++++++++++
 packages/llm-sdk/src/index.ts                 |  14 +
 packages/llm-sdk/tsup.config.ts               |   3 +
 pnpm-lock.yaml                                |  75 ++--
 16 files changed, 1759 insertions(+), 42 deletions(-)
 create mode 100644 apps/docs/content/docs/providers/fallback.mdx
 create mode 100644 examples/fallback-demo/README.md
 create mode 100644 examples/fallback-demo/package.json
 create mode 100644 examples/fallback-demo/src/index.ts
 create mode 100644 examples/fallback-demo/tsconfig.json
 create mode 100644 packages/llm-sdk/src/fallback/chain.ts
 create mode 100644 packages/llm-sdk/src/fallback/errors.ts
 create mode 100644 packages/llm-sdk/src/fallback/index.ts
 create mode 100644 packages/llm-sdk/src/fallback/routing-store.ts
 create mode 100644 packages/llm-sdk/src/fallback/types.ts

diff --git a/apps/docs/content/docs/providers/fallback.mdx b/apps/docs/content/docs/providers/fallback.mdx
new file mode 100644
index 0000000..25dac37
--- /dev/null
+++ b/apps/docs/content/docs/providers/fallback.mdx
@@ -0,0 +1,314 @@
+---
+title: Fallback
+description: Automatic failover and load distribution across LLM providers
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+Automatically retry failed requests with backup models. When your primary provider returns a `5xx` error, rate limit (`429`), or times out — the SDK silently tries the next model in your chain. Your application code doesn't change.
+
+```ts
+import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+
+const chain = createFallbackChain({
+  models: [
+    createOpenAI({ apiKey: '...' }).languageModel('gpt-5.4'),
+    createAnthropic({ apiKey: '...' }).languageModel('claude-haiku-4-5'),
+  ],
+});
+
+const runtime = createRuntime({ adapter: chain });
+```
+
+---
+
+## Installation
+
+```bash
+npm install @yourgpt/llm-sdk openai @anthropic-ai/sdk
+```
+
+---
+
+## Basic Usage
+
+Pass `createFallbackChain()` as the `adapter` in `createRuntime()`. The rest of your server code — streaming, tools, sessions — stays exactly the same.
+
+```ts title="server.ts"
+import { createRuntime } from '@yourgpt/llm-sdk';
+import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+const runtime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel('gpt-5.4'),            // tried first
+      anthropic.languageModel('claude-haiku-4-5'), // tried if OpenAI fails
+    ],
+  }),
+  systemPrompt: 'You are a helpful assistant.',
+});
+
+// Use exactly as normal — no other changes
+app.post('/api/chat', async (req, res) => {
+  await runtime.stream(req.body).pipeToResponse(res);
+});
+```
+
+---
+
+## What Triggers Fallback
+
+| Error type | Triggers fallback? |
+|---|---|
+| `5xx` server errors | ✅ Yes |
+| `429` rate limit | ✅ Yes |
+| Network timeout / connection refused | ✅ Yes |
+| `4xx` client errors (bad key, bad request) | ❌ No — these are your bugs, not provider failures |
+
+<Callout type="info">
+Once content has started streaming to the client, fallback is not attempted. You cannot restart a stream mid-flight.
+</Callout>
+
+---
+
+## Routing Strategies
+
+Control which model is tried first on each request.
+
+<Tabs items={['Priority (default)', 'Round-Robin']}>
+  <Tab value="Priority (default)">
+    Always tries models in the order defined. First model handles all traffic until it fails.
+
+    ```ts
+    createFallbackChain({
+      models: [primaryModel, backupModel],
+      strategy: 'priority', // default — can be omitted
+    });
+    ```
+  </Tab>
+  <Tab value="Round-Robin">
+    Distributes load evenly. Request 1 starts at model A, request 2 starts at model B, and so on. If the starting model fails, the chain falls through to the next one as usual.
+
+    ```ts
+    createFallbackChain({
+      models: [openaiModel, anthropicModel],
+      strategy: 'round-robin',
+    });
+    ```
+
+    <Callout type="info">
+    **Multi-instance deployments:** Round-robin state is in-memory by default and resets on restart. For shared state across instances, plug in a custom store (Redis, Upstash, etc.) via the `store` option.
+    </Callout>
+  </Tab>
+</Tabs>
+
+---
+
+## Per-Model Retries
+
+Retry the same model before moving to the next one. Useful for transient errors like brief rate limits or flaky connections.
+
+```ts
+createFallbackChain({
+  models: [openaiModel, anthropicModel],
+  retries: 2,                  // retry each model up to 2 times
+  retryDelay: 500,             // base delay: 500ms
+  retryBackoff: 'exponential', // 500ms → 1000ms → 2000ms (default)
+  onRetry: ({ model, retryAttempt, maxRetries, delayMs, error }) => {
+    console.warn(`[retry] ${model} attempt ${retryAttempt}/${maxRetries} — waiting ${delayMs}ms`);
+  },
+});
+```
+
+**Backoff options:**
+
+| `retryBackoff` | Pattern (retryDelay=500) |
+|---|---|
+| `exponential` (default) | 500ms → 1000ms → 2000ms |
+| `fixed` | 500ms → 500ms → 500ms |
+
+<Callout type="info">
+With `retries: 2`, each model gets 3 total attempts (1 initial + 2 retries) before the chain moves to the next model.
+</Callout>
+
+---
+
+## Observability Callbacks
+
+Two callbacks give you visibility into what the chain is doing.
+
+```ts
+createFallbackChain({
+  models: [openaiModel, anthropicModel, googleModel],
+
+  // Fires on each per-model retry (before the wait delay)
+  onRetry: ({ model, provider, error, retryAttempt, maxRetries, delayMs }) => {
+    console.warn(`[retry] ${provider}/${model} — attempt ${retryAttempt}/${maxRetries}`);
+    metrics.increment('llm.retry', { provider, model });
+  },
+
+  // Fires when a model is abandoned and the next one is tried
+  onFallback: ({ attemptedModel, nextModel, error, attempt }) => {
+    console.warn(`[fallback] ${attemptedModel} → ${nextModel}: ${error.message}`);
+    metrics.increment('llm.fallback', { from: attemptedModel, to: nextModel });
+  },
+});
+```
+
+---
+
+## Handling Full Failure
+
+When every model in the chain fails, `FallbackExhaustedError` is thrown. It includes a per-model breakdown of what failed.
+
+```ts
+import { FallbackExhaustedError } from '@yourgpt/llm-sdk/fallback';
+
+try {
+  await runtime.stream(req.body).pipeToResponse(res);
+} catch (err) {
+  if (err instanceof FallbackExhaustedError) {
+    // Per-model breakdown
+    for (const f of err.failures) {
+      console.error(
+        `${f.provider}/${f.model} failed after ${f.retriesAttempted} retries: ${f.error.message}`
+      );
+    }
+    res.status(503).json({ error: 'All models unavailable. Try again later.' });
+  }
+}
+```
+
+---
+
+## Custom Error Filtering
+
+By default the chain uses sensible rules (5xx, 429, network errors trigger fallback; 4xx does not). Override with `retryableErrors` for custom logic.
+
+```ts
+createFallbackChain({
+  models: [openaiModel, anthropicModel],
+
+  // Fall back on any error at all
+  retryableErrors: () => true,
+
+  // Or — only fall back on rate limits
+  retryableErrors: (err) => {
+    return err instanceof Error && /429|rate.?limit/i.test(err.message);
+  },
+});
+```
+
+---
+
+## Shared Routing Store (Multi-Instance)
+
+For round-robin to work correctly across multiple server instances or serverless functions, plug in a shared store.
+
+```ts
+import { createFallbackChain, type RoutingStore } from '@yourgpt/llm-sdk/fallback';
+
+// Implement RoutingStore with any backend — Redis, Upstash, Cloudflare KV, etc.
+// The SDK ships the interface. You own the implementation.
+const redisStore: RoutingStore = {
+  async get(key) {
+    const val = await redis.get(key);
+    return val ? Number(val) : undefined;
+  },
+  async set(key, value) {
+    await redis.set(key, String(value));
+  },
+};
+
+createFallbackChain({
+  models: [openaiModel, anthropicModel],
+  strategy: 'round-robin',
+  store: redisStore,
+});
+```
+
+<Callout type="info">
+The default `MemoryRoutingStore` is zero-config and works for single-process apps. No store configuration is needed unless you run multiple instances.
+</Callout>
+
+---
+
+## With Tools
+
+Tools work transparently across fallback providers. Define your tools once — whichever provider handles the request formats them natively.
+
+```ts
+const runtime = createRuntime({
+  adapter: createFallbackChain({
+    models: [openaiModel, anthropicModel],
+  }),
+  tools: [
+    {
+      name: 'get_weather',
+      description: 'Get current weather for a city',
+      location: 'server',
+      inputSchema: {
+        type: 'object',
+        properties: { city: { type: 'string' } },
+        required: ['city'],
+      },
+      handler: async ({ city }) => fetchWeather(city),
+    },
+  ],
+});
+```
+
+OpenAI receives tools as function-calling JSON. Anthropic receives them as `tool_use` blocks. **Your handler always runs on your server regardless of which provider responded.**
+
+---
+
+## Full Configuration Reference
+
+```ts
+import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+
+createFallbackChain({
+  // Required: adapters to try in order
+  models: LLMAdapter[],
+
+  // Routing strategy (default: 'priority')
+  strategy?: 'priority' | 'round-robin',
+
+  // Pluggable store for round-robin state (default: MemoryRoutingStore)
+  store?: RoutingStore,
+
+  // Retries per model before moving to next (default: 0)
+  retries?: number,
+
+  // Base delay between retries in ms (default: 500)
+  retryDelay?: number,
+
+  // Backoff strategy (default: 'exponential')
+  retryBackoff?: 'exponential' | 'fixed',
+
+  // Called on each per-model retry attempt
+  onRetry?: (info: RetryInfo) => void,
+
+  // Called when a model is abandoned and next one is tried
+  onFallback?: (info: FallbackInfo) => void,
+
+  // Custom predicate to decide which errors trigger fallback/retry
+  retryableErrors?: (error: unknown) => boolean,
+})
+```
+
+---
+
+## Next Steps
+
+- [OpenAI](/docs/providers/openai) — Configure your primary provider
+- [Anthropic](/docs/providers/anthropic) — Add a Claude fallback
+- [Server Storage](/docs/server/storage) — Persist sessions alongside fallback chains
diff --git a/apps/docs/content/docs/providers/index.mdx b/apps/docs/content/docs/providers/index.mdx
index 7d5b8ac..3d31231 100644
--- a/apps/docs/content/docs/providers/index.mdx
+++ b/apps/docs/content/docs/providers/index.mdx
@@ -162,3 +162,26 @@ Google and xAI use OpenAI-compatible endpoints. Ollama runs locally and needs no
 | Google | Fast | Very Good | $ | Multimodal |
 | xAI | Ultra Fast | Excellent | $ | Speed-critical apps |
 | Ollama | Varies | Good-Excellent | Free | Privacy, offline, development |
+
+---
+
+## Fallback Chain
+
+Use multiple providers together for automatic failover and load distribution.
+
+```ts
+import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+
+const runtime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel('gpt-5.4'),
+      anthropic.languageModel('claude-haiku-4-5'),
+    ],
+    strategy: 'round-robin',
+    retries: 2,
+  }),
+});
+```
+
+[Fallback Chain docs →](/docs/providers/fallback)
diff --git a/apps/docs/content/docs/providers/meta.json b/apps/docs/content/docs/providers/meta.json
index e0a5f18..31e4c3f 100644
--- a/apps/docs/content/docs/providers/meta.json
+++ b/apps/docs/content/docs/providers/meta.json
@@ -1,5 +1,13 @@
 {
   "title": "Providers",
   "icon": "Brain",
-  "pages": ["openai", "anthropic", "google", "xai", "ollama", "custom-provider"]
+  "pages": [
+    "openai",
+    "anthropic",
+    "google",
+    "xai",
+    "ollama",
+    "custom-provider",
+    "fallback"
+  ]
 }
diff --git a/examples/fallback-demo/README.md b/examples/fallback-demo/README.md
new file mode 100644
index 0000000..4538060
--- /dev/null
+++ b/examples/fallback-demo/README.md
@@ -0,0 +1,119 @@
+# Fallback Demo
+
+> Demonstrates `createFallbackChain()` from `@yourgpt/llm-sdk/fallback` — automatic failover, round-robin load distribution, per-model retries, and tools across multiple LLM providers.
+
+## Features Showcased
+
+- **Priority fallback** — OpenAI first, Anthropic if it fails
+- **Round-robin** — distributes load evenly across providers
+- **4xx does NOT trigger fallback** — bad API key throws immediately
+- **Forced fallback** — dead primary URL → Anthropic picks up
+- **Per-model retries** — retry same model N times before falling back
+- **Tools in streaming mode** — tools work transparently across providers
+- **Tools in non-streaming mode** — full JSON response with tool results
+- **FallbackExhaustedError** — structured error when all models fail
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- **pnpm** (required for workspace setup)
+- OpenAI API key
+- Anthropic API key
+
+### Installation
+
+```bash
+# From the monorepo root
+pnpm install
+
+# Set up environment
+cp examples/fallback-demo/.env.example examples/fallback-demo/.env
+# Edit .env and add your keys
+
+# Run the demo
+cd examples/fallback-demo
+pnpm dev
+```
+
+Server runs on [http://localhost:3000](http://localhost:3000)
+
+## Environment Variables
+
+```bash
+OPENAI_API_KEY=your-openai-key
+ANTHROPIC_API_KEY=your-anthropic-key
+```
+
+## API Endpoints
+
+| Endpoint                         | Description                                 |
+| -------------------------------- | ------------------------------------------- |
+| `POST /chat/priority`            | OpenAI first, Anthropic fallback            |
+| `POST /chat/round-robin`         | Alternates OpenAI / Anthropic per request   |
+| `POST /chat/bad-key`             | 4xx error — fallback NOT triggered          |
+| `POST /chat/fallback-test`       | Dead primary URL → Anthropic picks up       |
+| `POST /chat/stream/tools`        | Streaming with 3 server-side tools          |
+| `POST /chat/tools`               | Non-streaming JSON with tool results        |
+| `POST /chat/fallback-test/tools` | Forced fallback + tools (Anthropic handles) |
+| `POST /chat/retry-test`          | 2 retries on dead model before fallback     |
+
+## Test Commands
+
+### Basic fallback
+
+```bash
+curl -s -X POST http://localhost:3000/chat/priority \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Say hello"}]}'
+```
+
+### Forced fallback (dead primary → Anthropic)
+
+```bash
+curl -s -X POST http://localhost:3000/chat/fallback-test \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Which model are you?"}]}'
+```
+
+### Tools via streaming
+
+```bash
+curl -s -X POST http://localhost:3000/chat/stream/tools \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"What is the weather in Tokyo and what time is it?"}]}'
+```
+
+### Non-streaming with tools
+
+```bash
+curl -s -X POST http://localhost:3000/chat/tools \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Calculate 42 * 7 and get the weather in London"}]}'
+```
+
+### Retries before fallback (watch server logs)
+
+```bash
+curl -s -X POST http://localhost:3000/chat/retry-test \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## Project Structure
+
+```
+fallback-demo/
+├── src/
+│   └── index.ts    # Express server with all routes
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Important Notes
+
+> **Workspace Dependency**: Uses `workspace:*` dependencies. Run `pnpm install` from the monorepo root — `npm install` will not work.
+
+> **Tools are provider-agnostic**: Tool definitions are written once. Whichever provider handles the request formats them natively (OpenAI function-calling JSON or Anthropic `tool_use` blocks). Tool handlers always run on your server.
diff --git a/examples/fallback-demo/package.json b/examples/fallback-demo/package.json
new file mode 100644
index 0000000..1f38b05
--- /dev/null
+++ b/examples/fallback-demo/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "fallback-demo",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@yourgpt/llm-sdk": "workspace:*",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0",
+    "openai": "^4.77.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}
diff --git a/examples/fallback-demo/src/index.ts b/examples/fallback-demo/src/index.ts
new file mode 100644
index 0000000..dc5a6aa
--- /dev/null
+++ b/examples/fallback-demo/src/index.ts
@@ -0,0 +1,419 @@
+/**
+ * Fallback Chain Demo
+ *
+ * Tests FallbackChain across:
+ *   - Priority fallback (normal)
+ *   - Round-robin load distribution
+ *   - 4xx does NOT trigger fallback (bad key)
+ *   - Forced fallback (dead primary URL → Anthropic picks up)
+ *   - Tools in streaming mode
+ *   - Tools in non-streaming (chat) mode
+ *
+ * Run:
+ *   pnpm dev
+ *
+ * Test:
+ *   curl -s -X POST http://localhost:3000/chat/stream/tools \
+ *     -H "Content-Type: application/json" \
+ *     -d '{"messages":[{"role":"user","content":"What is the weather in Tokyo and what time is it?"}]}'
+ */
+
+import "dotenv/config";
+import express from "express";
+import cors from "cors";
+import { createRuntime, type ToolDefinition } from "@yourgpt/llm-sdk";
+import { createOpenAI } from "@yourgpt/llm-sdk/openai";
+import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
+import {
+  createFallbackChain,
+  FallbackExhaustedError,
+  MemoryRoutingStore,
+  type RoutingStore,
+  type RetryInfo,
+} from "@yourgpt/llm-sdk/fallback";
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+// ─── Providers ────────────────────────────────────────────────────────────────
+
+const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+const brokenOpenAI = createOpenAI({ apiKey: "sk-INVALID_KEY_FOR_TESTING" }); // gitleaks:allow
+const deadOpenAI = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseUrl: "http://localhost:19999/v1", // nothing here → ECONNREFUSED
+});
+
+// ─── Tools ────────────────────────────────────────────────────────────────────
+//
+// These are server-side tools. The fallback chain wraps the LLM adapter only —
+// tools always run on our server regardless of which provider is active.
+// The tool definitions are sent to whichever provider ends up handling the request,
+// each formatted in that provider's native format by the adapter.
+
+const WEATHER_DATA: Record<string, { temp: string; condition: string }> = {
+  tokyo: { temp: "18°C", condition: "Partly cloudy" },
+  london: { temp: "12°C", condition: "Rainy" },
+  new_york: { temp: "22°C", condition: "Sunny" },
+  paris: { temp: "15°C", condition: "Overcast" },
+  sydney: { temp: "25°C", condition: "Clear" },
+};
+
+const serverTools: ToolDefinition[] = [
+  {
+    name: "get_weather",
+    description: "Get current weather for a city",
+    location: "server",
+    inputSchema: {
+      type: "object",
+      properties: {
+        city: {
+          type: "string",
+          description: "City name (e.g. Tokyo, London, New York)",
+        },
+      },
+      required: ["city"],
+    },
+    handler: async (params) => {
+      const { city } = params as { city: string };
+      const key = city.toLowerCase().replace(/\s+/g, "_");
+      const data = WEATHER_DATA[key] ?? { temp: "20°C", condition: "Unknown" };
+      console.log(
+        `[tool:get_weather] city=${city} → ${data.temp}, ${data.condition}`,
+      );
+      return { city, temperature: data.temp, condition: data.condition };
+    },
+  },
+  {
+    name: "get_server_time",
+    description: "Get the current server date and time",
+    location: "server",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+    handler: async () => {
+      const now = new Date().toISOString();
+      console.log(`[tool:get_server_time] → ${now}`);
+      return { time: now };
+    },
+  },
+  {
+    name: "calculate",
+    description: "Evaluate a simple math expression and return the result",
+    location: "server",
+    inputSchema: {
+      type: "object",
+      properties: {
+        expression: {
+          type: "string",
+          description: "Math expression to evaluate, e.g. '12 * 7 + 5'",
+        },
+      },
+      required: ["expression"],
+    },
+    handler: async (params) => {
+      const { expression } = params as { expression: string };
+      // Safe eval: only allow numbers and basic operators
+      if (!/^[\d\s+\-*/().]+$/.test(expression)) {
+        return { error: "Invalid expression — only basic math allowed" };
+      }
+      // eslint-disable-next-line no-eval
+      const result = Function(`"use strict"; return (${expression})`)();
+      console.log(`[tool:calculate] ${expression} = ${result}`);
+      return { expression, result };
+    },
+  },
+];
+
+// ─── Helper: fallback chain factory ──────────────────────────────────────────
+
+function onFallbackLog(label: string) {
+  return ({
+    attemptedModel,
+    nextModel,
+    error,
+    attempt,
+  }: {
+    attemptedModel: string;
+    nextModel: string;
+    error: Error;
+    attempt: number;
+  }) => {
+    console.warn(
+      `[fallback:${label}] attempt ${attempt}: "${attemptedModel}" → "${nextModel}" | ${error.message}`,
+    );
+  };
+}
+
+// ─── Route 1: Priority (no tools) ────────────────────────────────────────────
+
+const priorityRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("priority"),
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/priority", async (req, res) => {
+  try {
+    await priorityRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 2: Round-robin (no tools) ─────────────────────────────────────────
+
+const rrStore: RoutingStore = new MemoryRoutingStore();
+
+const roundRobinRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "round-robin",
+    store: rrStore,
+    onFallback: onFallbackLog("round-robin"),
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/round-robin", async (req, res) => {
+  try {
+    await roundRobinRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 3: 4xx does NOT trigger fallback ───────────────────────────────────
+
+const badKeyRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      brokenOpenAI.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: () => {
+      console.warn(
+        "[fallback:bad-key] UNEXPECTED — fallback triggered for 4xx!",
+      );
+    },
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/bad-key", async (req, res) => {
+  try {
+    await badKeyRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 4: Forced fallback (dead primary URL) ──────────────────────────────
+
+const forcedFallbackRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      deadOpenAI.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("forced"),
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/fallback-test", async (req, res) => {
+  try {
+    await forcedFallbackRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 5: Tools + STREAMING ──────────────────────────────────────────────
+//
+// Primary: OpenAI (gpt-5.4) — formats tools as OpenAI function-calling JSON
+// Fallback: Anthropic (claude-haiku-4-5) — formats tools as Anthropic tool_use JSON
+//
+// The adapter for whichever provider runs transforms the shared ToolDefinition[]
+// into that provider's native format. Tools always execute on our server.
+
+const streamToolsRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("tools-stream"),
+  }),
+  systemPrompt:
+    "You are a helpful assistant with access to weather, time, and calculator tools. Use tools when relevant.",
+  tools: serverTools,
+});
+
+app.post("/chat/stream/tools", async (req, res) => {
+  try {
+    await streamToolsRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 6: Tools + NON-STREAMING (chat) ───────────────────────────────────
+//
+// Same chain and tools as above but using runtime.chat() which
+// collects the full response before returning JSON.
+
+const chatToolsRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      openai.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("tools-chat"),
+  }),
+  systemPrompt:
+    "You are a helpful assistant with access to weather, time, and calculator tools. Use tools when relevant.",
+  tools: serverTools,
+});
+
+app.post("/chat/tools", async (req, res) => {
+  try {
+    const result = await chatToolsRuntime.chat(req.body);
+    res.json(result);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 8: Retries before fallback ────────────────────────────────────────
+//
+// retries: 2  → tries dead primary 3 times total (initial + 2 retries) before
+//              giving up and falling back to Anthropic.
+// retryDelay: 300ms, retryBackoff: 'exponential' → 300ms, 600ms waits
+// onRetry fires on each retry attempt so you can see it in the server log.
+
+const retriesRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      deadOpenAI.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    retries: 2,
+    retryDelay: 300,
+    retryBackoff: "exponential",
+    onRetry: ({
+      model,
+      retryAttempt,
+      maxRetries,
+      delayMs,
+      error,
+    }: RetryInfo) => {
+      console.warn(
+        `[retry] ${model} — attempt ${retryAttempt}/${maxRetries}, waiting ${delayMs}ms | ${error.message}`,
+      );
+    },
+    onFallback: ({ attemptedModel, nextModel, attempt }) => {
+      console.warn(
+        `[fallback:retries] ${attemptedModel} exhausted all retries (attempt ${attempt}) → ${nextModel}`,
+      );
+    },
+  }),
+  systemPrompt: "You are a helpful assistant.",
+});
+
+app.post("/chat/retry-test", async (req, res) => {
+  try {
+    await retriesRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Route 7: Tools + FORCED FALLBACK (dead primary) ─────────────────────────
+//
+// Same tools, but primary is a dead URL.
+// Anthropic picks up and handles tool calls in its own format.
+
+const forcedToolsRuntime = createRuntime({
+  adapter: createFallbackChain({
+    models: [
+      deadOpenAI.languageModel("gpt-5.4"),
+      anthropic.languageModel("claude-haiku-4-5"),
+    ],
+    strategy: "priority",
+    onFallback: onFallbackLog("tools-forced"),
+  }),
+  systemPrompt:
+    "You are a helpful assistant with access to weather, time, and calculator tools. Use tools when relevant.",
+  tools: serverTools,
+});
+
+app.post("/chat/fallback-test/tools", async (req, res) => {
+  try {
+    await forcedToolsRuntime.stream(req.body).pipeToResponse(res);
+  } catch (err) {
+    handleError(err, res);
+  }
+});
+
+// ─── Error helper ─────────────────────────────────────────────────────────────
+
+function handleError(err: unknown, res: express.Response) {
+  if (err instanceof FallbackExhaustedError) {
+    res.status(503).json({
+      error: "All models in fallback chain failed",
+      detail: err.failures.map(
+        (f) => `${f.provider}/${f.model}: ${f.error.message}`,
+      ),
+    });
+  } else {
+    res.status(500).json({ error: String(err) });
+  }
+}
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`\nFallback Demo running at http://localhost:${PORT}\n`);
+  console.log("── Basic routes ──────────────────────────────────────────────");
+  console.log(
+    "  POST /chat/priority            — OpenAI first, Claude fallback",
+  );
+  console.log("  POST /chat/round-robin         — Alternates OpenAI / Claude");
+  console.log("  POST /chat/bad-key             — 4xx: fallback NOT triggered");
+  console.log(
+    "  POST /chat/fallback-test       — Dead primary → Claude picks up",
+  );
+  console.log(
+    "\n── Tool routes ───────────────────────────────────────────────",
+  );
+  console.log(
+    "  POST /chat/stream/tools        — Tools via streaming (OpenAI primary)",
+  );
+  console.log(
+    "  POST /chat/tools               — Tools via non-streaming JSON",
+  );
+  console.log(
+    "  POST /chat/fallback-test/tools — Tools via streaming (forced fallback → Claude)",
+  );
+  console.log(
+    "  POST /chat/retry-test          — Retries dead model 2x before falling back to Claude",
+  );
+});
diff --git a/examples/fallback-demo/tsconfig.json b/examples/fallback-demo/tsconfig.json
new file mode 100644
index 0000000..12a87ac
--- /dev/null
+++ b/examples/fallback-demo/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}
diff --git a/packages/llm-sdk/package.json b/packages/llm-sdk/package.json
index 5a914f6..d9a5b25 100644
--- a/packages/llm-sdk/package.json
+++ b/packages/llm-sdk/package.json
@@ -55,6 +55,11 @@
       "types": "./dist/yourgpt/index.d.ts",
       "import": "./dist/yourgpt/index.mjs",
       "require": "./dist/yourgpt/index.js"
+    },
+    "./fallback": {
+      "types": "./dist/fallback/index.d.ts",
+      "import": "./dist/fallback/index.mjs",
+      "require": "./dist/fallback/index.js"
     }
   },
   "homepage": "https://copilot-sdk.yourgpt.ai",
diff --git a/packages/llm-sdk/src/fallback/chain.ts b/packages/llm-sdk/src/fallback/chain.ts
new file mode 100644
index 0000000..aada23c
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/chain.ts
@@ -0,0 +1,425 @@
+import type {
+  LLMAdapter,
+  ChatCompletionRequest,
+  CompletionResult,
+} from "../adapters/base";
+import type { StreamEvent } from "../core/stream-events";
+import type { FallbackChainConfig, FallbackFailure, RetryInfo } from "./types";
+import { FallbackExhaustedError } from "./errors";
+import { MemoryRoutingStore } from "./routing-store";
+
+// Stable key used for round-robin state in the store
+const ROUND_ROBIN_KEY = "ygpt_fallback_rr_index";
+
+/**
+ * Determine whether an error should trigger a retry or fallback.
+ *
+ * Covers all error shapes across provider SDKs:
+ *
+ * OpenAI SDK (@openai/openai-node):
+ *   RateLimitError          → status=429
+ *   InternalServerError     → status>=500
+ *   APIConnectionError      → status=undefined, message="Connection error."
+ *   APIConnectionTimeoutError → status=undefined, message="Request timed out."
+ *   APIUserAbortError       → status=undefined, message="Aborted"  ← NOT retryable
+ *   BadRequestError etc     → status=4xx                          ← NOT retryable
+ *
+ * Anthropic SDK (@anthropic-ai/sdk) — identical class/message shapes to OpenAI SDK.
+ *
+ * Google SDK & Ollama — fall through to message-based detection.
+ *
+ * In streaming mode: adapters swallow thrown errors and yield { type:"error", message }.
+ * The fallback chain creates `new Error(message)` from those, so only message survives.
+ * Message-based detection handles that path.
+ *
+ * In complete() mode: real SDK class instances are thrown, so constructor.name + status checks fire.
+ */
+function defaultIsRetryable(error: unknown): boolean {
+  if (typeof error === "object" && error !== null) {
+    const ctorName = (error as object).constructor?.name ?? "";
+
+    // ── Explicit NOT-retryable classes ────────────────────────────────────
+    // User aborted the request — never retry, never fall back
+    if (ctorName === "APIUserAbortError") return false;
+
+    // ── Explicit retryable classes (no status property) ───────────────────
+    // Both OpenAI and Anthropic SDKs use these exact class names.
+    if (ctorName === "APIConnectionError") return true;
+    if (ctorName === "APIConnectionTimeoutError") return true;
+
+    // ── HTTP status code check (OpenAI, Anthropic, Google, etc.) ──────────
+    // Both SDKs expose the numeric HTTP status on `.status`.
+    // `.statusCode` covers some older / third-party adapters.
+    const status =
+      (error as { status?: unknown }).status ??
+      (error as { statusCode?: unknown }).statusCode;
+
+    if (typeof status === "number") {
+      if (status === 429) return true; // rate limit
+      if (status >= 500) return true; // 500, 502, 503, 504, 520-527 (Cloudflare), etc.
+      if (status >= 400) return false; // 400-428, 430-499 — caller bug, don't retry
+    }
+  }
+
+  // ── Message-based detection ───────────────────────────────────────────────
+  // Used when errors have been serialised to plain Error objects:
+  //   • stream mode — adapters yield { type:"error", message } instead of throwing
+  //   • Google SDK / Ollama — don't use OpenAI/Anthropic SDK class names
+  if (error instanceof Error) {
+    const msg = error.message;
+
+    // Hard-stop: user-initiated abort.
+    // Node.js AbortController: "The operation was aborted"
+    // Browser fetch AbortController: "The user aborted a request"
+    // These must never trigger a retry or fallback.
+    if (/the operation was aborted/i.test(msg)) return false;
+    if (/the user aborted a request/i.test(msg)) return false;
+
+    // Hard-stop: any 4xx that is NOT 429.
+    // e.g. "401 Incorrect API key", "403 Forbidden", "404 Not found"
+    if (/\b4[0-9]{2}\b/.test(msg) && !/\b429\b/.test(msg)) return false;
+
+    // ── Retryable: rate limit ──────────────────────────────────────────────
+    // OpenAI stream error event: "429 You exceeded your current quota…"
+    // Anthropic stream error event: "429 {"error":{"type":"rate_limit_error"…}}"
+    if (/\b429\b/.test(msg)) return true;
+    if (/rate[\s_-]?limit/i.test(msg)) return true;
+    if (/too many requests/i.test(msg)) return true;
+    if (/quota exceeded/i.test(msg)) return true; // Google
+
+    // ── Retryable: 5xx server errors ──────────────────────────────────────
+    if (/\b5[0-9]{2}\b/.test(msg)) return true; // any 5xx in message
+    if (/internal server error/i.test(msg)) return true;
+    if (/service unavailable/i.test(msg)) return true;
+    if (/bad gateway/i.test(msg)) return true;
+    if (/gateway timeout/i.test(msg)) return true;
+    if (/overloaded/i.test(msg)) return true; // Anthropic "overloaded_error"
+
+    // ── Retryable: connection / timeout ───────────────────────────────────
+    // OpenAI SDK APIConnectionError exact message:
+    if (/^connection error\.?$/i.test(msg)) return true;
+    // OpenAI SDK APIConnectionTimeoutError exact message:
+    if (/^request timed out\.?$/i.test(msg)) return true;
+    // General timeout patterns (Google SDK, Ollama, custom adapters)
+    if (/timed?\s*out/i.test(msg)) return true;
+    if (/timeout/i.test(msg)) return true;
+    // fetch() failure (browser + Node.js undici)
+    if (/fetch failed/i.test(msg)) return true;
+
+    // ── Retryable: Node.js network error codes ────────────────────────────
+    // These appear in the message when a raw network error bubbles up.
+    if (/ECONNREFUSED/.test(msg)) return true; // connection refused
+    if (/ECONNRESET/.test(msg)) return true; // connection reset by peer
+    if (/ETIMEDOUT/.test(msg)) return true; // TCP timeout
+    if (/ENOTFOUND/.test(msg)) return true; // DNS lookup failure
+    if (/ENETUNREACH/.test(msg)) return true; // no route to host
+    if (/EHOSTUNREACH/.test(msg)) return true; // host unreachable
+  }
+
+  return false;
+}
+
+/** Calculate delay for a given retry attempt */
+function calcDelay(
+  base: number,
+  attempt: number,
+  backoff: "exponential" | "fixed",
+): number {
+  if (backoff === "fixed") return base;
+  return base * Math.pow(2, attempt - 1); // exponential: base, base*2, base*4...
+}
+
+/** Sleep helper */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Internal resolved config type ───────────────────────────────────────────
+
+type ResolvedConfig = Required<
+  Omit<FallbackChainConfig, "onFallback" | "onRetry" | "retryableErrors">
+> &
+  Pick<FallbackChainConfig, "onFallback" | "onRetry" | "retryableErrors">;
+
+// ─── FallbackChain ────────────────────────────────────────────────────────────
+
+class FallbackChain implements LLMAdapter {
+  private readonly _config: ResolvedConfig;
+
+  constructor(config: FallbackChainConfig) {
+    if (config.models.length === 0) {
+      throw new Error("FallbackChain requires at least one model.");
+    }
+
+    this._config = {
+      models: config.models,
+      strategy: config.strategy ?? "priority",
+      store: config.store ?? new MemoryRoutingStore(),
+      retries: config.retries ?? 0,
+      retryDelay: config.retryDelay ?? 500,
+      retryBackoff: config.retryBackoff ?? "exponential",
+      onFallback: config.onFallback,
+      onRetry: config.onRetry,
+      retryableErrors: config.retryableErrors,
+    };
+  }
+
+  get provider(): string {
+    return "fallback-chain";
+  }
+
+  get model(): string {
+    return this._config.models.map((m) => `${m.provider}/${m.model}`).join(",");
+  }
+
+  private async _startIndex(): Promise<number> {
+    if (this._config.strategy !== "round-robin") return 0;
+    const stored = await this._config.store.get(ROUND_ROBIN_KEY);
+    return typeof stored === "number" ? stored % this._config.models.length : 0;
+  }
+
+  private async _advanceIndex(successfulIndex: number): Promise<void> {
+    if (this._config.strategy !== "round-robin") return;
+    const next = (successfulIndex + 1) % this._config.models.length;
+    await this._config.store.set(ROUND_ROBIN_KEY, next);
+  }
+
+  private _isRetryable(error: unknown): boolean {
+    return this._config.retryableErrors
+      ? this._config.retryableErrors(error)
+      : defaultIsRetryable(error);
+  }
+
+  /**
+   * Try streaming from a single adapter, with per-model retries.
+   *
+   * Returns an async generator that either:
+   *   - yields all chunks on success, then returns
+   *   - throws the final error if all retries exhausted or error is non-retryable
+   *
+   * The `retriesAttempted` out-param is filled via the returned object so callers
+   * can record it in FallbackFailure.
+   */
+  private async *_streamWithRetries(
+    adapter: LLMAdapter,
+    request: ChatCompletionRequest,
+    out: { retriesAttempted: number },
+  ): AsyncGenerator<StreamEvent> {
+    const { retries, retryDelay, retryBackoff, onRetry } = this._config;
+    const maxAttempts = retries + 1; // initial attempt + retries
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      let contentStarted = false;
+      let failureError: Error | null = null;
+
+      try {
+        for await (const chunk of adapter.stream(request)) {
+          if (chunk.type === "error") {
+            if (!contentStarted) {
+              const msg =
+                (chunk as { type: "error"; message?: string }).message ??
+                "Unknown error";
+              failureError = new Error(msg);
+              break;
+            }
+            yield chunk;
+            return;
+          }
+
+          if (chunk.type === "message:start") continue;
+
+          contentStarted = true;
+          yield chunk;
+        }
+      } catch (error) {
+        if (contentStarted) throw error;
+        if (!this._isRetryable(error)) throw error;
+        failureError =
+          error instanceof Error ? error : new Error(String(error));
+      }
+
+      if (failureError === null) return; // success
+
+      // Non-retryable (4xx) — checked in catch above, but also check error-event path
+      if (!this._isRetryable(failureError)) throw failureError;
+
+      out.retriesAttempted = attempt - 1; // attempts so far beyond initial
+
+      // If we have more retries left, wait then retry the same model
+      if (attempt < maxAttempts) {
+        const delayMs = calcDelay(retryDelay, attempt, retryBackoff);
+        const retryInfo: RetryInfo = {
+          model: adapter.model,
+          provider: adapter.provider,
+          error: failureError,
+          retryAttempt: attempt,
+          maxRetries: retries,
+          delayMs,
+        };
+        onRetry?.(retryInfo);
+        await sleep(delayMs);
+        continue;
+      }
+
+      // All retries for this model exhausted — throw so the outer loop can try next model
+      out.retriesAttempted = retries;
+      throw failureError;
+    }
+  }
+
+  async *stream(request: ChatCompletionRequest): AsyncGenerator<StreamEvent> {
+    const { models, onFallback } = this._config;
+    const startIndex = await this._startIndex();
+    const failures: FallbackFailure[] = [];
+
+    for (let i = 0; i < models.length; i++) {
+      const index = (startIndex + i) % models.length;
+      const adapter = models[index];
+      const out = { retriesAttempted: 0 };
+
+      try {
+        yield* this._streamWithRetries(adapter, request, out);
+        // Success
+        await this._advanceIndex(index);
+        return;
+      } catch (error) {
+        // Non-retryable (4xx) — rethrow immediately, don't try next model
+        if (!this._isRetryable(error)) throw error;
+
+        const failure: FallbackFailure = {
+          model: adapter.model,
+          provider: adapter.provider,
+          error: error instanceof Error ? error : new Error(String(error)),
+          attempt: i + 1,
+          retriesAttempted: out.retriesAttempted,
+        };
+        failures.push(failure);
+
+        const nextOffset = i + 1;
+        if (nextOffset < models.length && onFallback) {
+          const nextIndex = (startIndex + nextOffset) % models.length;
+          onFallback({
+            attemptedModel: adapter.model,
+            nextModel: models[nextIndex].model,
+            error: failure.error,
+            attempt: failure.attempt,
+          });
+        }
+      }
+    }
+
+    throw new FallbackExhaustedError(failures);
+  }
+
+  async complete(request: ChatCompletionRequest): Promise<CompletionResult> {
+    const { models, onFallback, retries, retryDelay, retryBackoff, onRetry } =
+      this._config;
+    const startIndex = await this._startIndex();
+    const failures: FallbackFailure[] = [];
+
+    for (let i = 0; i < models.length; i++) {
+      const index = (startIndex + i) % models.length;
+      const adapter = models[index];
+
+      if (!adapter.complete) {
+        failures.push({
+          model: adapter.model,
+          provider: adapter.provider,
+          error: new Error(
+            `Adapter ${adapter.provider}/${adapter.model} does not implement complete()`,
+          ),
+          attempt: i + 1,
+          retriesAttempted: 0,
+        });
+        continue;
+      }
+
+      const maxAttempts = retries + 1;
+      let lastError: Error | null = null;
+      let retriesAttempted = 0;
+
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          const result = await adapter.complete(request);
+          await this._advanceIndex(index);
+          return result;
+        } catch (error) {
+          if (!this._isRetryable(error)) throw error;
+
+          lastError = error instanceof Error ? error : new Error(String(error));
+          retriesAttempted = attempt - 1;
+
+          if (attempt < maxAttempts) {
+            const delayMs = calcDelay(retryDelay, attempt, retryBackoff);
+            onRetry?.({
+              model: adapter.model,
+              provider: adapter.provider,
+              error: lastError,
+              retryAttempt: attempt,
+              maxRetries: retries,
+              delayMs,
+            });
+            await sleep(delayMs);
+          }
+        }
+      }
+
+      const failure: FallbackFailure = {
+        model: adapter.model,
+        provider: adapter.provider,
+        error: lastError!,
+        attempt: i + 1,
+        retriesAttempted,
+      };
+      failures.push(failure);
+
+      const nextOffset = i + 1;
+      if (nextOffset < models.length && onFallback) {
+        const nextIndex = (startIndex + nextOffset) % models.length;
+        onFallback({
+          attemptedModel: adapter.model,
+          nextModel: models[nextIndex].model,
+          error: failure.error,
+          attempt: failure.attempt,
+        });
+      }
+    }
+
+    throw new FallbackExhaustedError(failures);
+  }
+}
+
+/**
+ * Create a fallback chain that tries each model in order, with optional
+ * per-model retries before moving to the next model.
+ *
+ * @example
+ * ```typescript
+ * import { createFallbackChain } from '@yourgpt/llm-sdk/fallback';
+ * import { createRuntime } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+ * import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+ *
+ * const chain = createFallbackChain({
+ *   models: [
+ *     createOpenAI({ apiKey: '...' }).languageModel('gpt-5.4'),
+ *     createAnthropic({ apiKey: '...' }).languageModel('claude-haiku-4-5'),
+ *   ],
+ *   retries: 2,              // retry each model up to 2 times before moving on
+ *   retryDelay: 500,         // 500ms → 1000ms (exponential)
+ *   retryBackoff: 'exponential',
+ *   strategy: 'round-robin',
+ *   onRetry: ({ model, retryAttempt, maxRetries, delayMs, error }) => {
+ *     console.warn(`[retry] ${model} attempt ${retryAttempt}/${maxRetries} — waiting ${delayMs}ms`);
+ *   },
+ *   onFallback: ({ attemptedModel, nextModel, attempt }) => {
+ *     console.warn(`[fallback] ${attemptedModel} gave up after retries → ${nextModel}`);
+ *   },
+ * });
+ *
+ * const runtime = createRuntime({ adapter: chain });
+ * ```
+ */
+export function createFallbackChain(config: FallbackChainConfig): LLMAdapter {
+  return new FallbackChain(config);
+}
diff --git a/packages/llm-sdk/src/fallback/errors.ts b/packages/llm-sdk/src/fallback/errors.ts
new file mode 100644
index 0000000..b6a00eb
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/errors.ts
@@ -0,0 +1,43 @@
+import type { FallbackFailure } from "./types";
+
+/**
+ * Thrown when every model in the fallback chain has failed.
+ *
+ * The `failures` array provides a per-model breakdown of what failed
+ * and why, so you can log or surface the full picture.
+ *
+ * @example
+ * ```typescript
+ * import { FallbackExhaustedError } from '@yourgpt/llm-sdk/fallback';
+ *
+ * try {
+ *   const result = await runtime.chat(request);
+ * } catch (err) {
+ *   if (err instanceof FallbackExhaustedError) {
+ *     for (const f of err.failures) {
+ *       console.error(`${f.provider}/${f.model} (attempt ${f.attempt}): ${f.error.message}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class FallbackExhaustedError extends Error {
+  /** Per-model breakdown of every failed attempt */
+  readonly failures: FallbackFailure[];
+
+  constructor(failures: FallbackFailure[]) {
+    const summary = failures
+      .map((f) => `${f.provider}/${f.model}: ${f.error.message}`)
+      .join("; ");
+
+    super(
+      `All ${failures.length} model(s) in the fallback chain failed. ${summary}`,
+    );
+
+    this.name = "FallbackExhaustedError";
+    this.failures = failures;
+
+    // Preserve prototype chain in transpiled environments
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
diff --git a/packages/llm-sdk/src/fallback/index.ts b/packages/llm-sdk/src/fallback/index.ts
new file mode 100644
index 0000000..e1bce5d
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/index.ts
@@ -0,0 +1,43 @@
+/**
+ * @yourgpt/llm-sdk/fallback
+ *
+ * Fallback Chain & Routing Strategies
+ *
+ * Automatically retries failed LLM requests with backup models.
+ * Supports priority (default) and round-robin routing strategies.
+ *
+ * @example
+ * ```typescript
+ * import { createFallbackChain, MemoryRoutingStore } from '@yourgpt/llm-sdk/fallback';
+ * import { createRuntime } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+ * import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+ *
+ * const chain = createFallbackChain({
+ *   models: [
+ *     createOpenAI({ apiKey: '...' }).languageModel('gpt-4o'),
+ *     createAnthropic({ apiKey: '...' }).languageModel('claude-3-5-sonnet-20241022'),
+ *   ],
+ *   strategy: 'round-robin',
+ *   onFallback: ({ attemptedModel, nextModel, error, attempt }) => {
+ *     console.warn(`Attempt ${attempt}: ${attemptedModel} failed, trying ${nextModel}`);
+ *   },
+ * });
+ *
+ * const runtime = createRuntime({ adapter: chain });
+ * ```
+ */
+
+export { createFallbackChain } from "./chain";
+export { FallbackExhaustedError } from "./errors";
+export { MemoryRoutingStore } from "./routing-store";
+
+export type {
+  RoutingStore,
+  RoutingStrategy,
+  RetryBackoff,
+  FallbackChainConfig,
+  FallbackFailure,
+  FallbackInfo,
+  RetryInfo,
+} from "./types";
diff --git a/packages/llm-sdk/src/fallback/routing-store.ts b/packages/llm-sdk/src/fallback/routing-store.ts
new file mode 100644
index 0000000..95b9ea8
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/routing-store.ts
@@ -0,0 +1,36 @@
+import type { RoutingStore } from "./types";
+
+/**
+ * Built-in in-memory routing store.
+ *
+ * Works out of the box for single-process applications.
+ * State resets on restart and is NOT shared across instances.
+ *
+ * For production multi-instance or serverless deployments,
+ * implement your own RoutingStore backed by Redis, Upstash,
+ * Cloudflare KV, DynamoDB, or any other persistent store.
+ *
+ * @example
+ * ```typescript
+ * // Default — created automatically by createFallbackChain
+ * const chain = createFallbackChain({ models: [...] });
+ *
+ * // Explicit — pass your own store
+ * const chain = createFallbackChain({
+ *   models: [...],
+ *   strategy: 'round-robin',
+ *   store: new MemoryRoutingStore(),
+ * });
+ * ```
+ */
+export class MemoryRoutingStore implements RoutingStore {
+  private readonly _map = new Map<string, number>();
+
+  async get(key: string): Promise<number | undefined> {
+    return this._map.get(key);
+  }
+
+  async set(key: string, value: number): Promise<void> {
+    this._map.set(key, value);
+  }
+}
diff --git a/packages/llm-sdk/src/fallback/types.ts b/packages/llm-sdk/src/fallback/types.ts
new file mode 100644
index 0000000..59f3fc8
--- /dev/null
+++ b/packages/llm-sdk/src/fallback/types.ts
@@ -0,0 +1,236 @@
+/**
+ * Fallback Chain & Routing Strategy Types
+ */
+
+import type { LLMAdapter } from "../adapters/base";
+
+// ============================================
+// Routing Store Interface
+// ============================================
+
+/**
+ * Pluggable state store for routing strategies.
+ *
+ * Round-robin and other stateful strategies use this to persist
+ * which model was last used. The default implementation is in-memory.
+ *
+ * For multi-instance or serverless deployments, plug in your own:
+ * Redis, Upstash, Cloudflare KV, DynamoDB, etc.
+ *
+ * @example
+ * ```typescript
+ * // Redis-backed store (example — bring your own client)
+ * const redisStore: RoutingStore = {
+ *   async get(key) {
+ *     const val = await redis.get(key);
+ *     return val ? Number(val) : undefined;
+ *   },
+ *   async set(key, value) {
+ *     await redis.set(key, value);
+ *   },
+ * };
+ * ```
+ */
+export interface RoutingStore {
+  /** Get the stored value for a key */
+  get(key: string): Promise<number | undefined>;
+  /** Set the stored value for a key */
+  set(key: string, value: number): Promise<void>;
+}
+
+// ============================================
+// Failure & Callback Types
+// ============================================
+
+/**
+ * A single failed model in the fallback chain (after all retries exhausted)
+ */
+export interface FallbackFailure {
+  /** Model ID that failed */
+  model: string;
+  /** Provider name */
+  provider: string;
+  /** The last error from this model */
+  error: Error;
+  /** Which model in the chain this was (1-based) */
+  attempt: number;
+  /** How many times this model was retried before giving up */
+  retriesAttempted: number;
+}
+
+/**
+ * Passed to the onFallback callback when a model is abandoned and the next one is tried
+ */
+export interface FallbackInfo {
+  /** Model that just failed (after all its retries) */
+  attemptedModel: string;
+  /** Model that will be tried next */
+  nextModel: string;
+  /** The last error from the failed model */
+  error: Error;
+  /** Which model in the chain this was (1-based) */
+  attempt: number;
+}
+
+/**
+ * Passed to the onRetry callback on each per-model retry attempt
+ */
+export interface RetryInfo {
+  /** Model being retried */
+  model: string;
+  /** Provider name */
+  provider: string;
+  /** The error that triggered this retry */
+  error: Error;
+  /** Which retry attempt this is (1-based: 1 = first retry after initial failure) */
+  retryAttempt: number;
+  /** Total retries configured for this chain */
+  maxRetries: number;
+  /** How long (ms) we will wait before retrying */
+  delayMs: number;
+}
+
+// ============================================
+// Strategy & Config
+// ============================================
+
+/**
+ * How the chain decides which model to try first.
+ *
+ * - `priority` — always try models in defined order (default)
+ * - `round-robin` — rotate starting model evenly across calls
+ */
+export type RoutingStrategy = "priority" | "round-robin";
+
+/**
+ * Backoff strategy between per-model retries.
+ *
+ * - `exponential` — delay doubles on each retry: 500ms → 1000ms → 2000ms (default)
+ * - `fixed`       — same delay every retry: 500ms → 500ms → 500ms
+ */
+export type RetryBackoff = "exponential" | "fixed";
+
+/**
+ * Configuration for createFallbackChain()
+ */
+export interface FallbackChainConfig {
+  /**
+   * Ordered list of adapters to try.
+   * On failure, the chain moves to the next adapter in this list.
+   *
+   * @example
+   * ```typescript
+   * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+   * import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
+   *
+   * const openai = createOpenAI({ apiKey: '...' });
+   * const anthropic = createAnthropic({ apiKey: '...' });
+   *
+   * const chain = createFallbackChain({
+   *   models: [
+   *     openai.languageModel('gpt-4o'),
+   *     anthropic.languageModel('claude-3-5-sonnet-20241022'),
+   *   ],
+   * });
+   * ```
+   */
+  models: LLMAdapter[];
+
+  /**
+   * Routing strategy controlling which model is tried first.
+   * @default 'priority'
+   */
+  strategy?: RoutingStrategy;
+
+  /**
+   * State store for strategies that require persistence (e.g., round-robin).
+   * Defaults to an in-memory store (MemoryRoutingStore).
+   *
+   * Replace with a shared store (Redis, Upstash, etc.) for multi-instance
+   * or serverless deployments where round-robin state must be shared.
+   */
+  store?: RoutingStore;
+
+  /**
+   * Number of times to retry the same model before moving to the next one.
+   *
+   * LiteLLM equivalent: `num_retries`
+   *
+   * @default 0  (no retries — fail immediately and move to next model)
+   *
+   * @example
+   * ```typescript
+   * // Try each model up to 3 times before falling back
+   * createFallbackChain({ models: [...], retries: 3 })
+   * ```
+   */
+  retries?: number;
+
+  /**
+   * Base delay in milliseconds between per-model retries.
+   *
+   * With `retryBackoff: 'exponential'` (default):
+   *   retry 1 → retryDelay ms
+   *   retry 2 → retryDelay * 2 ms
+   *   retry 3 → retryDelay * 4 ms
+   *
+   * With `retryBackoff: 'fixed'`:
+   *   every retry → retryDelay ms
+   *
+   * @default 500
+   */
+  retryDelay?: number;
+
+  /**
+   * Backoff strategy between per-model retries.
+   * @default 'exponential'
+   */
+  retryBackoff?: RetryBackoff;
+
+  /**
+   * Called on each per-model retry attempt (before the delay).
+   * Use for logging, metrics, or alerting per retry.
+   *
+   * @example
+   * ```typescript
+   * onRetry: ({ model, retryAttempt, maxRetries, delayMs, error }) => {
+   *   console.warn(`[retry] ${model} attempt ${retryAttempt}/${maxRetries} — waiting ${delayMs}ms | ${error.message}`);
+   * }
+   * ```
+   */
+  onRetry?: (info: RetryInfo) => void;
+
+  /**
+   * Called each time a model is abandoned and the next one is tried.
+   * Use for logging, metrics, or alerting.
+   *
+   * @example
+   * ```typescript
+   * onFallback: ({ attemptedModel, nextModel, error, attempt }) => {
+   *   console.warn(`[fallback] attempt ${attempt}: ${attemptedModel} failed → ${nextModel}`, error.message);
+   * }
+   * ```
+   */
+  onFallback?: (info: FallbackInfo) => void;
+
+  /**
+   * Custom predicate to decide whether an error should trigger a fallback.
+   *
+   * By default, the following trigger fallback:
+   * - HTTP 5xx server errors
+   * - HTTP 429 rate limit errors
+   * - Network timeouts and connection failures
+   *
+   * The following do NOT trigger fallback by default:
+   * - HTTP 4xx client errors (bad request, invalid API key, etc.)
+   *
+   * Override this to extend or restrict fallback behavior.
+   *
+   * @example
+   * ```typescript
+   * // Also fall back on any error
+   * retryableErrors: () => true,
+   * ```
+   */
+  retryableErrors?: (error: unknown) => boolean;
+}
diff --git a/packages/llm-sdk/src/index.ts b/packages/llm-sdk/src/index.ts
index a5af166..4218f5b 100644
--- a/packages/llm-sdk/src/index.ts
+++ b/packages/llm-sdk/src/index.ts
@@ -218,3 +218,17 @@ export {
   generateToolCallId,
   generateThreadId,
 } from "./core/utils";
+
+// ============================================
+// Fallback Chain & Routing (types only from root)
+// ============================================
+// Full implementation: import from '@yourgpt/llm-sdk/fallback'
+export type {
+  RoutingStore,
+  RoutingStrategy,
+  RetryBackoff,
+  FallbackChainConfig,
+  FallbackFailure,
+  FallbackInfo,
+  RetryInfo,
+} from "./fallback/types";
diff --git a/packages/llm-sdk/tsup.config.ts b/packages/llm-sdk/tsup.config.ts
index 418863c..78f76db 100644
--- a/packages/llm-sdk/tsup.config.ts
+++ b/packages/llm-sdk/tsup.config.ts
@@ -19,6 +19,9 @@ export default defineConfig({
 
     // YourGPT storage adapter
     "yourgpt/index": "src/yourgpt/index.ts",
+
+    // Fallback chain & routing
+    "fallback/index": "src/fallback/index.ts",
   },
   format: ["cjs", "esm"],
   dts: true,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2eb1776..b44c66f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -418,6 +418,40 @@ importers:
         specifier: ^5.6.0
         version: 5.9.3
 
+  examples/fallback-demo:
+    dependencies:
+      '@anthropic-ai/sdk':
+        specifier: ^0.39.0
+        version: 0.39.0
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+      openai:
+        specifier: ^4.77.0
+        version: 4.104.0(ws@8.18.0)(zod@3.25.76)
+    devDependencies:
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+
   examples/headless-slack-demo:
     dependencies:
       '@yourgpt/copilot-sdk':
@@ -1142,40 +1176,6 @@ importers:
         specifier: ^5
         version: 5.9.3
 
-  examples/yourgpt-server-demo:
-    dependencies:
-      '@yourgpt/llm-sdk':
-        specifier: workspace:*
-        version: link:../../packages/llm-sdk
-      cors:
-        specifier: ^2.8.5
-        version: 2.8.6
-      dotenv:
-        specifier: ^16.4.0
-        version: 16.6.1
-      express:
-        specifier: ^4.21.0
-        version: 4.22.1
-      ws:
-        specifier: ^8.18.0
-        version: 8.18.0
-    devDependencies:
-      '@types/cors':
-        specifier: ^2.8.17
-        version: 2.8.19
-      '@types/express':
-        specifier: ^5.0.0
-        version: 5.0.6
-      '@types/ws':
-        specifier: ^8.5.13
-        version: 8.18.1
-      tsx:
-        specifier: ^4.19.0
-        version: 4.21.0
-      typescript:
-        specifier: ^5.6.0
-        version: 5.9.3
-
   packages/copilot-sdk:
     dependencies:
       '@base-ui/react':
@@ -4097,9 +4097,6 @@ packages:
   '@types/validate-npm-package-name@4.0.2':
     resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
 
-  '@types/ws@8.18.1':
-    resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
-
   '@typescript-eslint/eslint-plugin@8.50.0':
     resolution: {integrity: sha512-O7QnmOXYKVtPrfYzMolrCTfkezCJS9+ljLdKW/+DCvRsc3UAz+sbH6Xcsv7p30+0OwUbeWfUDAQE0vpabZ3QLg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -11325,10 +11322,6 @@ snapshots:
 
   '@types/validate-npm-package-name@4.0.2': {}
 
-  '@types/ws@8.18.1':
-    dependencies:
-      '@types/node': 20.19.27
-
   '@typescript-eslint/eslint-plugin@8.50.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@eslint-community/regexpp': 4.12.2

From 3bb78d5c3dc9326bb8a123123d5f41eaf8d6ea1a Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 12:18:59 +0530
Subject: [PATCH 65/72] fix: update pnpm lockfile for generative-ui-demo
 dependencies

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 pnpm-lock.yaml | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b44c66f..bc23ab7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -424,8 +424,8 @@ importers:
         specifier: ^0.39.0
         version: 0.39.0
       '@yourgpt/llm-sdk':
-        specifier: workspace:*
-        version: link:../../packages/llm-sdk
+        specifier: 2.1.4-alpha.2
+        version: 2.1.4-alpha.2(@anthropic-ai/sdk@0.39.0)(@google/generative-ai@0.24.1)(openai@4.104.0(ws@8.18.0)(zod@3.25.76))
       cors:
         specifier: ^2.8.5
         version: 2.8.6
@@ -4260,6 +4260,21 @@ packages:
     peerDependencies:
       vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
 
+  '@yourgpt/llm-sdk@2.1.4-alpha.2':
+    resolution: {integrity: sha512-0m9ZtwSOxxJdG3Bx0S81StoDqVTqzKw7wTg7Lgnp4ofk388ZqtAdaAMUhNz6E5Y2DH8w3eCDx9M63MgUUWOO9Q==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@anthropic-ai/sdk': '>=0.20.0'
+      '@google/generative-ai': '>=0.21.0'
+      openai: '>=4.0.0'
+    peerDependenciesMeta:
+      '@anthropic-ai/sdk':
+        optional: true
+      '@google/generative-ai':
+        optional: true
+      openai:
+        optional: true
+
   abort-controller@3.0.0:
     resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
     engines: {node: '>=6.5'}
@@ -11498,6 +11513,15 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@yourgpt/llm-sdk@2.1.4-alpha.2(@anthropic-ai/sdk@0.39.0)(@google/generative-ai@0.24.1)(openai@4.104.0(ws@8.18.0)(zod@3.25.76))':
+    dependencies:
+      hono: 4.11.0
+      zod: 3.25.76
+    optionalDependencies:
+      '@anthropic-ai/sdk': 0.39.0
+      '@google/generative-ai': 0.24.1
+      openai: 4.104.0(ws@8.18.0)(zod@3.25.76)
+
   abort-controller@3.0.0:
     dependencies:
       event-target-shim: 5.0.1

From 33199e8cbe7ecc0731aa9e1b2183d9995ddd5f52 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 12:22:35 +0530
Subject: [PATCH 66/72] fix(playground): replace workspace:* with pinned alpha
 versions for Vercel deploy

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/playground/package.json |   4 +-
 pnpm-lock.yaml                   | 113 ++++++++++++++++++++++++++++---
 2 files changed, 106 insertions(+), 11 deletions(-)

diff --git a/examples/playground/package.json b/examples/playground/package.json
index 57d9aa9..2cf8ef5 100644
--- a/examples/playground/package.json
+++ b/examples/playground/package.json
@@ -27,8 +27,8 @@
     "@radix-ui/react-switch": "^1.2.3",
     "@radix-ui/react-tabs": "^1.1.13",
     "@tailwindcss/typography": "^0.5.19",
-    "@yourgpt/copilot-sdk": "workspace:*",
-    "@yourgpt/llm-sdk": "workspace:*",
+    "@yourgpt/copilot-sdk": "2.1.5-alpha.8",
+    "@yourgpt/llm-sdk": "2.1.4-alpha.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bc23ab7..134fb50 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -424,8 +424,8 @@ importers:
         specifier: ^0.39.0
         version: 0.39.0
       '@yourgpt/llm-sdk':
-        specifier: 2.1.4-alpha.2
-        version: 2.1.4-alpha.2(@anthropic-ai/sdk@0.39.0)(@google/generative-ai@0.24.1)(openai@4.104.0(ws@8.18.0)(zod@3.25.76))
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
       cors:
         specifier: ^2.8.5
         version: 2.8.6
@@ -775,11 +775,11 @@ importers:
         specifier: ^0.5.19
         version: 0.5.19(tailwindcss@4.1.18)
       '@yourgpt/copilot-sdk':
-        specifier: workspace:*
-        version: link:../../packages/copilot-sdk
+        specifier: 2.1.5-alpha.8
+        version: 2.1.5-alpha.8(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@yourgpt/llm-sdk':
-        specifier: workspace:*
-        version: link:../../packages/llm-sdk
+        specifier: 2.1.4-alpha.2
+        version: 2.1.4-alpha.2(@anthropic-ai/sdk@0.71.2(zod@3.25.76))(@google/generative-ai@0.24.1)(openai@6.16.0(ws@8.18.0)(zod@3.25.76))
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -4260,6 +4260,18 @@ packages:
     peerDependencies:
       vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
 
+  '@yourgpt/copilot-sdk@2.1.5-alpha.8':
+    resolution: {integrity: sha512-5dtH/F8rmlv+V78xTnMoEBAMQYAr1YGCxNWyX+2V004xTHzgqTsdgZCNaYlFkNbv0PMNCwTfH9hfabhBEviVkQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      react:
+        optional: true
+      react-dom:
+        optional: true
+
   '@yourgpt/llm-sdk@2.1.4-alpha.2':
     resolution: {integrity: sha512-0m9ZtwSOxxJdG3Bx0S81StoDqVTqzKw7wTg7Lgnp4ofk388ZqtAdaAMUhNz6E5Y2DH8w3eCDx9M63MgUUWOO9Q==}
     engines: {node: '>=18'}
@@ -8435,6 +8447,20 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.27
 
+  '@base-ui/react@1.0.0(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+    dependencies:
+      '@babel/runtime': 7.28.4
+      '@base-ui/utils': 0.2.3(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@floating-ui/react-dom': 2.1.6(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@floating-ui/utils': 0.2.10
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+      reselect: 5.1.1
+      tabbable: 6.3.0
+      use-sync-external-store: 1.6.0(react@19.2.3)
+    optionalDependencies:
+      '@types/react': 18.3.27
+
   '@base-ui/utils@0.2.3(@types/react@18.3.27)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
       '@babel/runtime': 7.28.4
@@ -8446,6 +8472,17 @@ snapshots:
     optionalDependencies:
       '@types/react': 18.3.27
 
+  '@base-ui/utils@0.2.3(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+    dependencies:
+      '@babel/runtime': 7.28.4
+      '@floating-ui/utils': 0.2.10
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+      reselect: 5.1.1
+      use-sync-external-store: 1.6.0(react@19.2.3)
+    optionalDependencies:
+      '@types/react': 18.3.27
+
   '@changesets/apply-release-plan@7.0.14':
     dependencies:
       '@changesets/config': 3.1.2
@@ -11017,6 +11054,11 @@ snapshots:
       react: 18.3.1
       shiki: 3.20.0
 
+  '@streamdown/code@1.0.1(react@19.2.3)':
+    dependencies:
+      react: 19.2.3
+      shiki: 3.20.0
+
   '@swc/helpers@0.5.15':
     dependencies:
       tslib: 2.8.1
@@ -11513,14 +11555,39 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@yourgpt/llm-sdk@2.1.4-alpha.2(@anthropic-ai/sdk@0.39.0)(@google/generative-ai@0.24.1)(openai@4.104.0(ws@8.18.0)(zod@3.25.76))':
+  '@yourgpt/copilot-sdk@2.1.5-alpha.8(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+    dependencies:
+      '@base-ui/react': 1.0.0(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@radix-ui/react-avatar': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@radix-ui/react-hover-card': 1.1.15(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@radix-ui/react-slot': 1.2.4(@types/react@18.3.27)(react@19.2.3)
+      '@radix-ui/react-tooltip': 1.2.8(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@streamdown/code': 1.0.1(react@19.2.3)
+      class-variance-authority: 0.7.1
+      clsx: 2.1.1
+      html-to-image: 1.11.13
+      html2canvas: 1.4.1
+      lucide-react: 0.561.0(react@19.2.3)
+      streamdown: 2.1.0(react@19.2.3)
+      tailwind-merge: 3.4.0
+      use-stick-to-bottom: 1.1.1(react@19.2.3)
+      zod: 3.25.76
+    optionalDependencies:
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
+      - supports-color
+
+  '@yourgpt/llm-sdk@2.1.4-alpha.2(@anthropic-ai/sdk@0.71.2(zod@3.25.76))(@google/generative-ai@0.24.1)(openai@6.16.0(ws@8.18.0)(zod@3.25.76))':
     dependencies:
       hono: 4.11.0
       zod: 3.25.76
     optionalDependencies:
-      '@anthropic-ai/sdk': 0.39.0
+      '@anthropic-ai/sdk': 0.71.2(zod@3.25.76)
       '@google/generative-ai': 0.24.1
-      openai: 4.104.0(ws@8.18.0)(zod@3.25.76)
+      openai: 6.16.0(ws@8.18.0)(zod@3.25.76)
 
   abort-controller@3.0.0:
     dependencies:
@@ -13830,6 +13897,10 @@ snapshots:
     dependencies:
       react: 18.3.1
 
+  lucide-react@0.561.0(react@19.2.3):
+    dependencies:
+      react: 19.2.3
+
   lucide-react@0.562.0(react@19.2.1):
     dependencies:
       react: 19.2.1
@@ -15667,6 +15738,26 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  streamdown@2.1.0(react@19.2.3):
+    dependencies:
+      clsx: 2.1.1
+      hast-util-to-jsx-runtime: 2.3.6
+      html-url-attributes: 3.0.1
+      marked: 17.0.1
+      react: 19.2.3
+      rehype-harden: 1.1.7
+      rehype-raw: 7.0.0
+      rehype-sanitize: 6.0.0
+      remark-gfm: 4.0.1
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      remend: 1.1.0
+      tailwind-merge: 3.4.0
+      unified: 11.0.5
+      unist-util-visit: 5.0.0
+    transitivePeerDependencies:
+      - supports-color
+
   strict-event-emitter@0.5.1: {}
 
   string-argv@0.3.2: {}
@@ -16170,6 +16261,10 @@ snapshots:
     dependencies:
       react: 18.3.1
 
+  use-stick-to-bottom@1.1.1(react@19.2.3):
+    dependencies:
+      react: 19.2.3
+
   use-sync-external-store@1.6.0(react@18.3.1):
     dependencies:
       react: 18.3.1

From 391b195cd4ca77583110afebcb5bd9e3e7bc5d61 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 12:24:06 +0530
Subject: [PATCH 67/72] fix: sync pnpm lockfile with generative-ui-demo and
 skills-demo packages

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 pnpm-lock.yaml | 625 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 598 insertions(+), 27 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 134fb50..bd7fad4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -44,7 +44,7 @@ importers:
         version: 16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6)
       fumadocs-mdx:
         specifier: ^14.1.1
-        version: 14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       fumadocs-ui:
         specifier: ^16.2.5
         version: 16.2.5(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(tailwindcss@4.1.18)(zod@4.3.6)
@@ -452,6 +452,73 @@ importers:
         specifier: ^5.6.0
         version: 5.9.3
 
+  examples/generative-ui-demo:
+    dependencies:
+      '@yourgpt/copilot-sdk':
+        specifier: workspace:*
+        version: link:../../packages/copilot-sdk
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+      lucide-react:
+        specifier: ^0.563.0
+        version: 0.563.0(react@19.2.3)
+      react:
+        specifier: ^19.0.0
+        version: 19.2.3
+      react-dom:
+        specifier: ^19.0.0
+        version: 19.2.3(react@19.2.3)
+      recharts:
+        specifier: ^2.13.0
+        version: 2.15.4(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+    devDependencies:
+      '@tailwindcss/postcss':
+        specifier: ^4
+        version: 4.1.18
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      '@types/node':
+        specifier: ^20
+        version: 20.19.27
+      '@types/react':
+        specifier: ^18.2.0
+        version: 18.3.27
+      '@types/react-dom':
+        specifier: ^18.2.0
+        version: 18.3.7(@types/react@18.3.27)
+      '@vitejs/plugin-react':
+        specifier: 6.0.1
+        version: 6.0.1(vite@8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+      concurrently:
+        specifier: ^9.0.0
+        version: 9.2.1
+      tailwindcss:
+        specifier: ^4
+        version: 4.2.1
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+      vite:
+        specifier: 8.0.3
+        version: 8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+
   examples/headless-slack-demo:
     dependencies:
       '@yourgpt/copilot-sdk':
@@ -502,7 +569,7 @@ importers:
         version: 18.3.7(@types/react@18.3.27)
       '@vitejs/plugin-react':
         specifier: ^4.3.4
-        version: 4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       concurrently:
         specifier: ^9.0.0
         version: 9.2.1
@@ -517,7 +584,7 @@ importers:
         version: 5.9.3
       vite:
         specifier: ^6.0.0
-        version: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+        version: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
 
   examples/mcp-demo:
     dependencies:
@@ -603,7 +670,7 @@ importers:
     devDependencies:
       '@tailwindcss/vite':
         specifier: ^4.0.0
-        version: 4.2.1(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 4.2.1(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       '@types/react':
         specifier: ^18.2.0
         version: 18.3.27
@@ -612,7 +679,7 @@ importers:
         version: 18.3.7(@types/react@18.3.27)
       '@vitejs/plugin-react':
         specifier: ^4.3.0
-        version: 4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       tailwindcss:
         specifier: ^4.0.0
         version: 4.1.18
@@ -621,7 +688,7 @@ importers:
         version: 5.9.3
       vite:
         specifier: ^6.0.0
-        version: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+        version: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
 
   examples/ollama-demo/server:
     dependencies:
@@ -1060,6 +1127,73 @@ importers:
         specifier: ^5
         version: 5.9.3
 
+  examples/skills-demo:
+    dependencies:
+      '@yourgpt/copilot-sdk':
+        specifier: workspace:*
+        version: link:../../packages/copilot-sdk
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+      lucide-react:
+        specifier: ^0.563.0
+        version: 0.563.0(react@19.2.3)
+      react:
+        specifier: ^19.0.0
+        version: 19.2.3
+      react-dom:
+        specifier: ^19.0.0
+        version: 19.2.3(react@19.2.3)
+    devDependencies:
+      '@tailwindcss/postcss':
+        specifier: ^4
+        version: 4.1.18
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      '@types/node':
+        specifier: ^20
+        version: 20.19.27
+      '@types/react':
+        specifier: ^18.2.0
+        version: 18.3.27
+      '@types/react-dom':
+        specifier: ^18.2.0
+        version: 18.3.7(@types/react@18.3.27)
+      '@vitejs/plugin-react':
+        specifier: 6.0.1
+        version: 6.0.1(vite@8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+      concurrently:
+        specifier: ^9.0.0
+        version: 9.2.1
+      path:
+        specifier: ^0.12.7
+        version: 0.12.7
+      tailwindcss:
+        specifier: ^4
+        version: 4.2.1
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+      vite:
+        specifier: 8.0.3
+        version: 8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+
   examples/support-tickets-demo:
     dependencies:
       '@radix-ui/react-slot':
@@ -1244,7 +1378,7 @@ importers:
         version: 18.3.1(react@18.3.1)
       tsup:
         specifier: ^8.0.2
-        version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       typescript:
         specifier: ^5.4.0
         version: 5.9.3
@@ -1269,7 +1403,7 @@ importers:
         version: 22.19.3
       tsup:
         specifier: ^8.3.5
-        version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       typescript:
         specifier: ^5.7.2
         version: 5.9.3
@@ -1278,7 +1412,7 @@ importers:
     devDependencies:
       tsup:
         specifier: ^8.0.2
-        version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       typescript:
         specifier: ^5.4.0
         version: 5.9.3
@@ -1306,7 +1440,7 @@ importers:
         version: 4.104.0(ws@8.18.0)(zod@3.25.76)
       tsup:
         specifier: ^8.0.2
-        version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       typescript:
         specifier: ^5.4.0
         version: 5.9.3
@@ -2555,6 +2689,12 @@ packages:
   '@napi-rs/wasm-runtime@0.2.12':
     resolution: {integrity: sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==}
 
+  '@napi-rs/wasm-runtime@1.1.2':
+    resolution: {integrity: sha512-sNXv5oLJ7ob93xkZ1XnxisYhGYXfaG9f65/ZgYuAu3qt7b3NadcOEhLvx28hv31PgX8SZJRYrAIPQilQmFpLVw==}
+    peerDependencies:
+      '@emnapi/core': ^1.7.1
+      '@emnapi/runtime': ^1.7.1
+
   '@next/env@16.0.10':
     resolution: {integrity: sha512-8tuaQkyDVgeONQ1MeT9Mkk8pQmZapMKFh5B+OrFUlG3rVmYTXcXlBetBgTurKXGaIZvkoqRT9JL5K3phXcgang==}
 
@@ -2758,6 +2898,9 @@ packages:
     resolution: {integrity: sha512-APwpZ+FTGMryo4QEeD6ti+Ei8suBkvxe8PeWdUcQHVfJDpjpt4c1dKojjNswcBmdeWSiiTYcnkKKH+yuo6727g==}
     engines: {node: '>= 20.0.0'}
 
+  '@oxc-project/types@0.122.0':
+    resolution: {integrity: sha512-oLAl5kBpV4w69UtFZ9xqcmTi+GENWOcPF7FCrczTiBbmC0ibXxCwyvZGbO39rCVEuLGAZM84DH0pUIyyv/YJzA==}
+
   '@parcel/watcher-android-arm64@2.5.1':
     resolution: {integrity: sha512-KF8+j9nNbUN8vzOFDpRMsaKBHZ/mcjEjMToVMJOhTozkDonQFFrRcfdLWn6yWKCmJKmdVxSgHiYvTCef4/qcBA==}
     engines: {node: '>= 10.0.0'}
@@ -3600,9 +3743,104 @@ packages:
   '@radix-ui/rect@1.1.1':
     resolution: {integrity: sha512-HPwpGIzkl28mWyZqG52jiqDJ12waP11Pa1lGoiyUkIEuMLBP0oeK/C89esbXrxsky5we7dfd8U58nm0SgAWpVw==}
 
+  '@rolldown/binding-android-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-pv1y2Fv0JybcykuiiD3qBOBdz6RteYojRFY1d+b95WVuzx211CRh+ytI/+9iVyWQ6koTh5dawe4S/yRfOFjgaA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-cFYr6zTG/3PXXF3pUO+umXxt1wkRK/0AYT8lDwuqvRC+LuKYWSAQAQZjCWDQpAH172ZV6ieYrNnFzVVcnSflAg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.0.0-rc.12':
+    resolution: {integrity: sha512-ZCsYknnHzeXYps0lGBz8JrF37GpE9bFVefrlmDrAQhOEi4IOIlcoU1+FwHEtyXGx2VkYAvhu7dyBf75EJQffBw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.0.0-rc.12':
+    resolution: {integrity: sha512-dMLeprcVsyJsKolRXyoTH3NL6qtsT0Y2xeuEA8WQJquWFXkEC4bcu1rLZZSnZRMtAqwtrF/Ib9Ddtpa/Gkge9Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.12':
+    resolution: {integrity: sha512-YqWjAgGC/9M1lz3GR1r1rP79nMgo3mQiiA+Hfo+pvKFK1fAJ1bCi0ZQVh8noOqNacuY1qIcfyVfP6HoyBRZ85Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-/I5AS4cIroLpslsmzXfwbe5OmWvSsrFuEw3mwvbQ1kDxJ822hFHIx+vsN/TAzNVyepI/j/GSzrtCIwQPeKCLIg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.12':
+    resolution: {integrity: sha512-V6/wZztnBqlx5hJQqNWwFdxIKN0m38p8Jas+VoSfgH54HSj9tKTt1dZvG6JRHcjh6D7TvrJPWFGaY9UBVOaWPw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-AP3E9BpcUYliZCxa3w5Kwj9OtEVDYK6sVoUzy4vTOJsjPOgdaJZKFmN4oOlX0Wp0RPV2ETfmIra9x1xuayFB7g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-nWwpvUSPkoFmZo0kQazZYOrT7J5DGOJ/+QHHzjvNlooDZED8oH82Yg67HvehPPLAg5fUff7TfWFHQS8IV1n3og==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-RNrafz5bcwRy+O9e6P8Z/OCAJW/A+qtBczIqVYwTs14pf4iV1/+eKEjdOUta93q2TsT/FI0XYDP3TCky38LMAg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@rolldown/binding-linux-x64-musl@1.0.0-rc.12':
+    resolution: {integrity: sha512-Jpw/0iwoKWx3LJ2rc1yjFrj+T7iHZn2JDg1Yny1ma0luviFS4mhAIcd1LFNxK3EYu3DHWCps0ydXQ5i/rrJ2ig==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@rolldown/binding-openharmony-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-vRugONE4yMfVn0+7lUKdKvN4D5YusEiPilaoO2sgUWpCvrncvWgPMzK00ZFFJuiPgLwgFNP5eSiUlv2tfc+lpA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.12':
+    resolution: {integrity: sha512-ykGiLr/6kkiHc0XnBfmFJuCjr5ZYKKofkx+chJWDjitX+KsJuAmrzWhwyOMSHzPhzOHOy7u9HlFoa5MoAOJ/Zg==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.12':
+    resolution: {integrity: sha512-5eOND4duWkwx1AzCxadcOrNeighiLwMInEADT0YM7xeEOOFcovWZCq8dadXgcRHSf3Ulh1kFo/qvzoFiCLOL1Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.12':
+    resolution: {integrity: sha512-PyqoipaswDLAZtot351MLhrlrh6lcZPo2LSYE+VDxbVk24LVKAGOuE4hb8xZQmrPAuEtTZW8E6D2zc5EUZX4Lw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
   '@rolldown/pluginutils@1.0.0-beta.27':
     resolution: {integrity: sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==}
 
+  '@rolldown/pluginutils@1.0.0-rc.12':
+    resolution: {integrity: sha512-HHMwmarRKvoFsJorqYlFeFRzXZqCt2ETQlEDOb9aqssrnVBB1/+xgTGtuTrIk5vzLNX1MjMtTf7W9z3tsSbrxw==}
+
+  '@rolldown/pluginutils@1.0.0-rc.7':
+    resolution: {integrity: sha512-qujRfC8sFVInYSPPMLQByRh7zhwkGFS4+tyMQ83srV1qrxL4g8E2tyxVVyxd0+8QeBM1mIk9KbWxkegRr76XzA==}
+
   '@rollup/rollup-android-arm-eabi@4.53.3':
     resolution: {integrity: sha512-mRSi+4cBjrRLoaal2PnqH82Wqyb+d3HsPUN/W+WslCXsZsyHa9ZeQQX/pQsZaVIWDkPcpV6jJ+3KLbTbgnwv8w==}
     cpu: [arm]
@@ -4260,6 +4498,19 @@ packages:
     peerDependencies:
       vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
 
+  '@vitejs/plugin-react@6.0.1':
+    resolution: {integrity: sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      '@rolldown/plugin-babel': ^0.1.7 || ^0.2.0
+      babel-plugin-react-compiler: ^1.0.0
+      vite: ^8.0.0
+    peerDependenciesMeta:
+      '@rolldown/plugin-babel':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+
   '@yourgpt/copilot-sdk@2.1.5-alpha.8':
     resolution: {integrity: sha512-5dtH/F8rmlv+V78xTnMoEBAMQYAr1YGCxNWyX+2V004xTHzgqTsdgZCNaYlFkNbv0PMNCwTfH9hfabhBEviVkQ==}
     engines: {node: '>=18'}
@@ -5723,6 +5974,9 @@ packages:
     resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
     engines: {node: '>=0.8.19'}
 
+  inherits@2.0.3:
+    resolution: {integrity: sha512-x00IRNXNy63jwGkJmzPigoySHbaqpNuzKbBOmzK+g2OdZpQ9w+sxCN+VSB3ja7IAge2OP2qpfxTjeNcyjmW1uw==}
+
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
@@ -6050,6 +6304,12 @@ packages:
     cpu: [arm64]
     os: [android]
 
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
   lightningcss-darwin-arm64@1.30.2:
     resolution: {integrity: sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==}
     engines: {node: '>= 12.0.0'}
@@ -6062,6 +6322,12 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
   lightningcss-darwin-x64@1.30.2:
     resolution: {integrity: sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==}
     engines: {node: '>= 12.0.0'}
@@ -6074,6 +6340,12 @@ packages:
     cpu: [x64]
     os: [darwin]
 
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
   lightningcss-freebsd-x64@1.30.2:
     resolution: {integrity: sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==}
     engines: {node: '>= 12.0.0'}
@@ -6086,6 +6358,12 @@ packages:
     cpu: [x64]
     os: [freebsd]
 
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
   lightningcss-linux-arm-gnueabihf@1.30.2:
     resolution: {integrity: sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==}
     engines: {node: '>= 12.0.0'}
@@ -6098,6 +6376,12 @@ packages:
     cpu: [arm]
     os: [linux]
 
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
   lightningcss-linux-arm64-gnu@1.30.2:
     resolution: {integrity: sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==}
     engines: {node: '>= 12.0.0'}
@@ -6110,6 +6394,12 @@ packages:
     cpu: [arm64]
     os: [linux]
 
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
   lightningcss-linux-arm64-musl@1.30.2:
     resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==}
     engines: {node: '>= 12.0.0'}
@@ -6122,6 +6412,12 @@ packages:
     cpu: [arm64]
     os: [linux]
 
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
   lightningcss-linux-x64-gnu@1.30.2:
     resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==}
     engines: {node: '>= 12.0.0'}
@@ -6134,6 +6430,12 @@ packages:
     cpu: [x64]
     os: [linux]
 
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
   lightningcss-linux-x64-musl@1.30.2:
     resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==}
     engines: {node: '>= 12.0.0'}
@@ -6146,6 +6448,12 @@ packages:
     cpu: [x64]
     os: [linux]
 
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
   lightningcss-win32-arm64-msvc@1.30.2:
     resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==}
     engines: {node: '>= 12.0.0'}
@@ -6158,6 +6466,12 @@ packages:
     cpu: [arm64]
     os: [win32]
 
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
   lightningcss-win32-x64-msvc@1.30.2:
     resolution: {integrity: sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==}
     engines: {node: '>= 12.0.0'}
@@ -6170,6 +6484,12 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
   lightningcss@1.30.2:
     resolution: {integrity: sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==}
     engines: {node: '>= 12.0.0'}
@@ -6178,6 +6498,10 @@ packages:
     resolution: {integrity: sha512-l51N2r93WmGUye3WuFoN5k10zyvrVs0qfKBhyC5ogUQ6Ew6JUSswh78mbSO+IU3nTWsyOArqPCcShdQSadghBQ==}
     engines: {node: '>= 12.0.0'}
 
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
   lilconfig@3.1.3:
     resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==}
     engines: {node: '>=14'}
@@ -6863,6 +7187,9 @@ packages:
     resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
     engines: {node: '>=8'}
 
+  path@0.12.7:
+    resolution: {integrity: sha512-aXXC6s+1w7otVF9UletFkFcDsJeO7lSZBPUQhtb5O0xJe8LtYhj/GxldoL09bBj9+ZmE2hNoHqQSFMN5fikh4Q==}
+
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
 
@@ -6877,6 +7204,10 @@ packages:
     resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
     engines: {node: '>=12'}
 
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
+    engines: {node: '>=12'}
+
   pidtree@0.6.0:
     resolution: {integrity: sha512-eG2dWTVw5bzqGRztnHExczNxt5VGsE6OwTeCG3fdUf9KBsZzO3R5OIIIzWR+iZA0NtZ+RDVdaoE2dK1cn6jH4g==}
     engines: {node: '>=0.10'}
@@ -6935,6 +7266,10 @@ packages:
     resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
     engines: {node: ^10 || ^12 || >=14}
 
+  postcss@8.5.8:
+    resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==}
+    engines: {node: ^10 || ^12 || >=14}
+
   powershell-utils@0.1.0:
     resolution: {integrity: sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A==}
     engines: {node: '>=20'}
@@ -6960,6 +7295,10 @@ packages:
   printable-characters@1.0.42:
     resolution: {integrity: sha512-dKp+C4iXWK4vVYZmYSd0KBH5F/h1HoZRsbJ82AVKRO3PEo8L4lBS/vLwhVtpwwuYcoIsVY+1JYKR268yn480uQ==}
 
+  process@0.11.10:
+    resolution: {integrity: sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==}
+    engines: {node: '>= 0.6.0'}
+
   prompts@2.4.2:
     resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
     engines: {node: '>= 6'}
@@ -7256,6 +7595,11 @@ packages:
   rfdc@1.4.1:
     resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
 
+  rolldown@1.0.0-rc.12:
+    resolution: {integrity: sha512-yP4USLIMYrwpPHEFB5JGH1uxhcslv6/hL0OyvTuY+3qlOSJvZ7ntYnoWpehBxufkgN0cvXxppuTu5hHa/zPh+A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
   rollup-plugin-inject@3.0.2:
     resolution: {integrity: sha512-ptg9PQwzs3orn4jkgXJ74bfs5vYz1NCZlSQMBUA0wKcGp5i5pA1AO3fOUEte8enhGUC+iapTCzEWw2jEFFUO/w==}
     deprecated: This package has been deprecated and is no longer maintained. Please use @rollup/plugin-inject.
@@ -7912,6 +8256,9 @@ packages:
   util-deprecate@1.0.2:
     resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
 
+  util@0.10.4:
+    resolution: {integrity: sha512-0Pm9hTQ3se5ll1XihRic3FDIku70C+iHUdT/W926rSgHV5QgXsYbKZN8MSC3tJtSkhuROzvsQjAaFENRXr+19A==}
+
   utils-merge@1.0.1:
     resolution: {integrity: sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==}
     engines: {node: '>= 0.4.0'}
@@ -7979,6 +8326,49 @@ packages:
       yaml:
         optional: true
 
+  vite@8.0.3:
+    resolution: {integrity: sha512-B9ifbFudT1TFhfltfaIPgjo9Z3mDynBTJSUYxTjOQruf/zHH+ezCQKcoqO+h7a9Pw9Nm/OtlXAiGT1axBgwqrQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.1.0
+      esbuild: ^0.27.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
   web-namespaces@2.0.1:
     resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
 
@@ -9359,6 +9749,13 @@ snapshots:
       '@tybys/wasm-util': 0.10.1
     optional: true
 
+  '@napi-rs/wasm-runtime@1.1.2(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)':
+    dependencies:
+      '@emnapi/core': 1.7.1
+      '@emnapi/runtime': 1.7.1
+      '@tybys/wasm-util': 0.10.1
+    optional: true
+
   '@next/env@16.0.10': {}
 
   '@next/env@16.1.1': {}
@@ -9482,6 +9879,8 @@ snapshots:
 
   '@orama/orama@3.1.17': {}
 
+  '@oxc-project/types@0.122.0': {}
+
   '@parcel/watcher-android-arm64@2.5.1':
     optional: true
 
@@ -10924,8 +11323,62 @@ snapshots:
 
   '@radix-ui/rect@1.1.1': {}
 
+  '@rolldown/binding-android-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.12(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)':
+    dependencies:
+      '@napi-rs/wasm-runtime': 1.1.2(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.12':
+    optional: true
+
   '@rolldown/pluginutils@1.0.0-beta.27': {}
 
+  '@rolldown/pluginutils@1.0.0-rc.12': {}
+
+  '@rolldown/pluginutils@1.0.0-rc.7': {}
+
   '@rollup/rollup-android-arm-eabi@4.53.3':
     optional: true
 
@@ -11198,12 +11651,12 @@ snapshots:
       postcss-selector-parser: 6.0.10
       tailwindcss: 4.1.18
 
-  '@tailwindcss/vite@4.2.1(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@tailwindcss/vite@4.2.1(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@tailwindcss/node': 4.2.1
       '@tailwindcss/oxide': 4.2.1
       tailwindcss: 4.2.1
-      vite: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
 
   '@ts-morph/common@0.27.0':
     dependencies:
@@ -11531,7 +11984,7 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
     optional: true
 
-  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@babel/core': 7.28.5
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.5)
@@ -11539,11 +11992,11 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
-  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@babel/core': 7.28.5
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.5)
@@ -11551,10 +12004,15 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
+  '@vitejs/plugin-react@6.0.1(vite@8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+    dependencies:
+      '@rolldown/pluginutils': 1.0.0-rc.7
+      vite: 8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+
   '@yourgpt/copilot-sdk@2.1.5-alpha.8(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       '@base-ui/react': 1.0.0(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -13072,7 +13530,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  fumadocs-mdx@14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)):
+  fumadocs-mdx@14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       '@mdx-js/mdx': 3.1.1
       '@standard-schema/spec': 1.1.0
@@ -13095,7 +13553,7 @@ snapshots:
     optionalDependencies:
       next: 16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0)
       react: 19.2.1
-      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
@@ -13454,6 +13912,8 @@ snapshots:
 
   imurmurhash@0.1.4: {}
 
+  inherits@2.0.3: {}
+
   inherits@2.0.4: {}
 
   inline-style-parser@0.2.7: {}
@@ -13739,66 +14199,99 @@ snapshots:
   lightningcss-android-arm64@1.31.1:
     optional: true
 
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
   lightningcss-darwin-arm64@1.30.2:
     optional: true
 
   lightningcss-darwin-arm64@1.31.1:
     optional: true
 
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
   lightningcss-darwin-x64@1.30.2:
     optional: true
 
   lightningcss-darwin-x64@1.31.1:
     optional: true
 
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
   lightningcss-freebsd-x64@1.30.2:
     optional: true
 
   lightningcss-freebsd-x64@1.31.1:
     optional: true
 
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
   lightningcss-linux-arm-gnueabihf@1.30.2:
     optional: true
 
   lightningcss-linux-arm-gnueabihf@1.31.1:
     optional: true
 
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
   lightningcss-linux-arm64-gnu@1.30.2:
     optional: true
 
   lightningcss-linux-arm64-gnu@1.31.1:
     optional: true
 
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
   lightningcss-linux-arm64-musl@1.30.2:
     optional: true
 
   lightningcss-linux-arm64-musl@1.31.1:
     optional: true
 
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
   lightningcss-linux-x64-gnu@1.30.2:
     optional: true
 
   lightningcss-linux-x64-gnu@1.31.1:
     optional: true
 
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
   lightningcss-linux-x64-musl@1.30.2:
     optional: true
 
   lightningcss-linux-x64-musl@1.31.1:
     optional: true
 
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
   lightningcss-win32-arm64-msvc@1.30.2:
     optional: true
 
   lightningcss-win32-arm64-msvc@1.31.1:
     optional: true
 
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
   lightningcss-win32-x64-msvc@1.30.2:
     optional: true
 
   lightningcss-win32-x64-msvc@1.31.1:
     optional: true
 
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
   lightningcss@1.30.2:
     dependencies:
       detect-libc: 2.1.2
@@ -13831,6 +14324,22 @@ snapshots:
       lightningcss-win32-arm64-msvc: 1.31.1
       lightningcss-win32-x64-msvc: 1.31.1
 
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
   lilconfig@3.1.3: {}
 
   lines-and-columns@1.2.4: {}
@@ -14810,6 +15319,11 @@ snapshots:
 
   path-type@4.0.0: {}
 
+  path@0.12.7:
+    dependencies:
+      process: 0.11.10
+      util: 0.10.4
+
   pathe@2.0.3: {}
 
   picocolors@1.1.1: {}
@@ -14818,6 +15332,8 @@ snapshots:
 
   picomatch@4.0.3: {}
 
+  picomatch@4.0.4: {}
+
   pidtree@0.6.0: {}
 
   pify@4.0.1: {}
@@ -14834,12 +15350,12 @@ snapshots:
 
   possible-typed-array-names@1.1.0: {}
 
-  postcss-load-config@6.0.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.8.2):
+  postcss-load-config@6.0.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       lilconfig: 3.1.3
     optionalDependencies:
       jiti: 2.6.1
-      postcss: 8.5.6
+      postcss: 8.5.8
       tsx: 4.21.0
       yaml: 2.8.2
 
@@ -14865,6 +15381,12 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  postcss@8.5.8:
+    dependencies:
+      nanoid: 3.3.11
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
   powershell-utils@0.1.0: {}
 
   prelude-ls@1.2.1: {}
@@ -14879,6 +15401,8 @@ snapshots:
 
   printable-characters@1.0.42: {}
 
+  process@0.11.10: {}
+
   prompts@2.4.2:
     dependencies:
       kleur: 3.0.3
@@ -15324,6 +15848,30 @@ snapshots:
 
   rfdc@1.4.1: {}
 
+  rolldown@1.0.0-rc.12(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1):
+    dependencies:
+      '@oxc-project/types': 0.122.0
+      '@rolldown/pluginutils': 1.0.0-rc.12
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.0.0-rc.12
+      '@rolldown/binding-darwin-arm64': 1.0.0-rc.12
+      '@rolldown/binding-darwin-x64': 1.0.0-rc.12
+      '@rolldown/binding-freebsd-x64': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm-gnueabihf': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm64-musl': 1.0.0-rc.12
+      '@rolldown/binding-linux-ppc64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-s390x-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-x64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-x64-musl': 1.0.0-rc.12
+      '@rolldown/binding-openharmony-arm64': 1.0.0-rc.12
+      '@rolldown/binding-wasm32-wasi': 1.0.0-rc.12(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)
+      '@rolldown/binding-win32-arm64-msvc': 1.0.0-rc.12
+      '@rolldown/binding-win32-x64-msvc': 1.0.0-rc.12
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+
   rollup-plugin-inject@3.0.2:
     dependencies:
       estree-walker: 0.6.1
@@ -15987,7 +16535,7 @@ snapshots:
 
   tslib@2.8.1: {}
 
-  tsup@8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2):
+  tsup@8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2):
     dependencies:
       bundle-require: 5.1.0(esbuild@0.27.1)
       cac: 6.7.14
@@ -15998,7 +16546,7 @@ snapshots:
       fix-dts-default-cjs-exports: 1.0.1
       joycon: 3.1.1
       picocolors: 1.1.1
-      postcss-load-config: 6.0.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.8.2)
+      postcss-load-config: 6.0.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(yaml@2.8.2)
       resolve-from: 5.0.0
       rollup: 4.53.3
       source-map: 0.7.6
@@ -16007,7 +16555,7 @@ snapshots:
       tinyglobby: 0.2.15
       tree-kill: 1.2.2
     optionalDependencies:
-      postcss: 8.5.6
+      postcss: 8.5.8
       typescript: 5.9.3
     transitivePeerDependencies:
       - jiti
@@ -16275,6 +16823,10 @@ snapshots:
 
   util-deprecate@1.0.2: {}
 
+  util@0.10.4:
+    dependencies:
+      inherits: 2.0.3
+
   utils-merge@1.0.1: {}
 
   utrie@1.0.2:
@@ -16317,7 +16869,7 @@ snapshots:
       d3-time: 3.1.0
       d3-timer: 3.0.1
 
-  vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
+  vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       esbuild: 0.25.12
       fdir: 6.5.0(picomatch@4.0.3)
@@ -16329,12 +16881,12 @@ snapshots:
       '@types/node': 20.19.27
       fsevents: 2.3.3
       jiti: 2.6.1
-      lightningcss: 1.31.1
+      lightningcss: 1.32.0
       sass: 1.97.0
       tsx: 4.21.0
       yaml: 2.8.2
 
-  vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
+  vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       esbuild: 0.25.12
       fdir: 6.5.0(picomatch@4.0.3)
@@ -16346,11 +16898,30 @@ snapshots:
       '@types/node': 22.19.3
       fsevents: 2.3.3
       jiti: 2.6.1
-      lightningcss: 1.31.1
+      lightningcss: 1.32.0
       sass: 1.97.0
       tsx: 4.21.0
       yaml: 2.8.2
 
+  vite@8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.4
+      postcss: 8.5.8
+      rolldown: 1.0.0-rc.12(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)
+      tinyglobby: 0.2.15
+    optionalDependencies:
+      '@types/node': 20.19.27
+      esbuild: 0.27.1
+      fsevents: 2.3.3
+      jiti: 2.6.1
+      sass: 1.97.0
+      tsx: 4.21.0
+      yaml: 2.8.2
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+
   web-namespaces@2.0.1: {}
 
   web-streams-polyfill@3.3.3: {}

From bae84197cbc95691aeab1c076e8f3a1a1eb4bdcb Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 12:27:36 +0530
Subject: [PATCH 68/72] fix(examples): add composite:true to tsconfig.node.json
 in skills-demo and generative-ui-demo

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/generative-ui-demo/tsconfig.node.json | 2 +-
 examples/skills-demo/tsconfig.node.json        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/generative-ui-demo/tsconfig.node.json b/examples/generative-ui-demo/tsconfig.node.json
index 1f27c41..f8aea3b 100644
--- a/examples/generative-ui-demo/tsconfig.node.json
+++ b/examples/generative-ui-demo/tsconfig.node.json
@@ -9,7 +9,7 @@
     "allowImportingTsExtensions": true,
     "isolatedModules": true,
     "moduleDetection": "force",
-    "noEmit": true
+    "composite": true
   },
   "include": ["vite.config.ts", "server"]
 }
diff --git a/examples/skills-demo/tsconfig.node.json b/examples/skills-demo/tsconfig.node.json
index 1f27c41..f8aea3b 100644
--- a/examples/skills-demo/tsconfig.node.json
+++ b/examples/skills-demo/tsconfig.node.json
@@ -9,7 +9,7 @@
     "allowImportingTsExtensions": true,
     "isolatedModules": true,
     "moduleDetection": "force",
-    "noEmit": true
+    "composite": true
   },
   "include": ["vite.config.ts", "server"]
 }

From 421ebf51444bff05d38f978bf01e1d80ecafcc39 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 12:31:20 +0530
Subject: [PATCH 69/72] fix(examples): add emitDeclarationOnly to satisfy
 allowImportingTsExtensions with composite

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/generative-ui-demo/tsconfig.node.json | 3 ++-
 examples/skills-demo/tsconfig.node.json        | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/examples/generative-ui-demo/tsconfig.node.json b/examples/generative-ui-demo/tsconfig.node.json
index f8aea3b..211e1d8 100644
--- a/examples/generative-ui-demo/tsconfig.node.json
+++ b/examples/generative-ui-demo/tsconfig.node.json
@@ -9,7 +9,8 @@
     "allowImportingTsExtensions": true,
     "isolatedModules": true,
     "moduleDetection": "force",
-    "composite": true
+    "composite": true,
+    "emitDeclarationOnly": true
   },
   "include": ["vite.config.ts", "server"]
 }
diff --git a/examples/skills-demo/tsconfig.node.json b/examples/skills-demo/tsconfig.node.json
index f8aea3b..211e1d8 100644
--- a/examples/skills-demo/tsconfig.node.json
+++ b/examples/skills-demo/tsconfig.node.json
@@ -9,7 +9,8 @@
     "allowImportingTsExtensions": true,
     "isolatedModules": true,
     "moduleDetection": "force",
-    "composite": true
+    "composite": true,
+    "emitDeclarationOnly": true
   },
   "include": ["vite.config.ts", "server"]
 }

From 2874d1604798772f5db87c5f14954243d925d4a1 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 19:19:18 +0530
Subject: [PATCH 70/72] feat(skills-demo): enhance skills system with dynamic
 skill registration and UI improvements

- Added support for dynamic skills registration via API, allowing skills to be registered at runtime.
- Updated server to handle dynamic skills, including new endpoints for skill management.
- Introduced a new skill for frontend design with detailed guidelines.
- Improved UI with new font styles (DM Sans and DM Mono) and animations for skill activation.
- Enhanced the skills panel to display both static and dynamic skills, improving user experience.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 examples/skills-demo/index.html               |    2 +-
 examples/skills-demo/package.json             |    4 +-
 examples/skills-demo/server/index.ts          |  147 +-
 .../skills-demo/skills/frontend-design.md     |   57 +
 examples/skills-demo/src/App.tsx              | 1237 ++++++++++-------
 examples/skills-demo/src/index.css            |  752 ++++++++++
 examples/skills-demo/vite.config.ts           |    3 +
 pnpm-lock.yaml                                |  687 ++++++++-
 8 files changed, 2316 insertions(+), 573 deletions(-)
 create mode 100644 examples/skills-demo/skills/frontend-design.md

diff --git a/examples/skills-demo/index.html b/examples/skills-demo/index.html
index e272c21..fbeeca4 100644
--- a/examples/skills-demo/index.html
+++ b/examples/skills-demo/index.html
@@ -7,7 +7,7 @@
     <title>Dash — AI Copilot</title>
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,300;12..96,400;12..96,500;12..96,600;12..96,700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+    <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=DM+Mono:wght@400;500&display=swap" rel="stylesheet" />
   </head>
   <body>
     <div id="root"></div>
diff --git a/examples/skills-demo/package.json b/examples/skills-demo/package.json
index da1ec08..42b15b6 100644
--- a/examples/skills-demo/package.json
+++ b/examples/skills-demo/package.json
@@ -18,7 +18,8 @@
     "express": "^4.21.0",
     "lucide-react": "^0.563.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "vaul": "^1.1.2"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
@@ -32,6 +33,7 @@
     "path": "^0.12.7",
     "tailwindcss": "^4",
     "tsx": "^4.19.0",
+    "tw-animate-css": "^1.4.0",
     "typescript": "^5.6.0",
     "vite": "8.0.3"
   }
diff --git a/examples/skills-demo/server/index.ts b/examples/skills-demo/server/index.ts
index c54db60..565c225 100644
--- a/examples/skills-demo/server/index.ts
+++ b/examples/skills-demo/server/index.ts
@@ -2,6 +2,7 @@ import "dotenv/config";
 import express from "express";
 import cors from "cors";
 import path from "path";
+import { Readable } from "stream";
 import { fileURLToPath } from "url";
 import { createRuntime } from "@yourgpt/llm-sdk";
 import { createAnthropic } from "@yourgpt/llm-sdk/anthropic";
@@ -30,6 +31,19 @@ for (const skill of skills) {
   );
 }
 
+// ============================================
+// DYNAMIC SKILLS (registered at runtime)
+// ============================================
+
+interface DynamicSkill {
+  name: string;
+  description: string;
+  content: string;
+  strategy: string;
+}
+
+const dynamicSkills: DynamicSkill[] = [];
+
 // ============================================
 // CREATE PROVIDERS
 // ============================================
@@ -65,8 +79,7 @@ When a user asks about:
 - Customer risk, health scores, at-risk accounts, or engagement → load the "customer-health" skill
 - Incidents, outages, production issues, or on-call → load the "incident-runbook" skill
 
-Always load the relevant skill before responding to ensure you follow the correct protocol.
-Be concise, data-focused, and action-oriented.`,
+Always load the relevant skill before responding.`,
 );
 
 const runtime = createRuntime({
@@ -83,6 +96,19 @@ runtime.registerTool({
   location: "server",
   inputSchema: tools.load_skill.parameters,
   handler: async (params: { name: string }) => {
+    // Delay so the shimmer animation is visible in the UI
+    await new Promise((r) => setTimeout(r, 2200));
+    // Check dynamicSkills first before falling back to file-based skills
+    const dynamic = dynamicSkills.find((s) => s.name === params.name);
+    if (dynamic) {
+      return {
+        name: dynamic.name,
+        description: dynamic.description,
+        content: dynamic.content,
+        strategy: dynamic.strategy,
+        source: "dynamic",
+      };
+    }
     return tools.load_skill.execute(params);
   },
 });
@@ -93,32 +119,128 @@ runtime.registerTool({
 
 /**
  * POST /api/chat — Main chat endpoint for CopilotProvider
+ * Rebuilds system prompt per-request to include any dynamically registered skills.
  */
 app.post("/api/chat", async (req, res) => {
   const url = `http://localhost:${PORT}/api/chat`;
+
+  // Inject dynamic skills into the system prompt so the AI knows they exist
+  const body = { ...req.body };
+  if (dynamicSkills.length > 0) {
+    const dynamicSection = dynamicSkills
+      .map(
+        (s) =>
+          `- "${s.name}" [${s.strategy}]: ${s.description} → load with load_skill("${s.name}")`,
+      )
+      .join("\n");
+    body.systemPrompt =
+      systemPrompt +
+      `\n\n## Additional Skills (dropped at runtime)\n${dynamicSection}`;
+  }
+
   const webReq = new Request(url, {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify(req.body),
+    body: JSON.stringify(body),
   });
   const response = await runtime.handleRequest(webReq);
   res.status(response.status);
   response.headers.forEach((val, key) => res.setHeader(key, val));
-  const body = await response.text();
-  res.send(body);
+  if (response.body) {
+    Readable.fromWeb(
+      response.body as Parameters<typeof Readable.fromWeb>[0],
+    ).pipe(res);
+  } else {
+    res.send(await response.text());
+  }
 });
 
 /**
- * GET /api/skills — Returns skill metadata for the UI sidebar
+ * GET /api/skills — Returns skill metadata for the UI sidebar (static + dynamic)
  */
 app.get("/api/skills", (_req, res) => {
-  const skillList = skills.map((skill) => ({
+  const staticList = skills.map((skill) => ({
     name: skill.name,
     description: skill.description,
     strategy: skill.strategy ?? "auto",
     version: skill.version,
+    source: "file",
   }));
-  res.json(skillList);
+
+  const dynamicList = dynamicSkills.map((skill) => ({
+    name: skill.name,
+    description: skill.description,
+    strategy: skill.strategy,
+    source: "dropped",
+  }));
+
+  res.json([...staticList, ...dynamicList]);
+});
+
+/**
+ * GET /api/skills/:name — Returns full content of a skill (reuses load_skill handler)
+ */
+app.get("/api/skills/:name", async (req, res) => {
+  const { name } = req.params;
+  try {
+    // Reuse the same handler registered with the runtime — covers both file and dynamic skills
+    const dynamic = dynamicSkills.find((s) => s.name === name);
+    const result = dynamic
+      ? {
+          name: dynamic.name,
+          description: dynamic.description,
+          content: dynamic.content,
+          strategy: dynamic.strategy,
+          source: "dynamic",
+        }
+      : await tools.load_skill.execute({ name });
+    res.json(result);
+  } catch {
+    res.status(404).json({ error: "Skill not found" });
+  }
+});
+
+/**
+ * POST /api/skills/register — Register a new dynamic skill from a dropped file
+ */
+app.post("/api/skills/register", (req, res) => {
+  const { name, description, content, strategy } = req.body as {
+    name?: string;
+    description?: string;
+    content?: string;
+    strategy?: string;
+  };
+
+  if (!name || !content) {
+    res.status(400).json({ error: "name and content are required" });
+    return;
+  }
+
+  const skill: DynamicSkill = {
+    name,
+    description: description ?? "",
+    content,
+    strategy: strategy ?? "auto",
+  };
+
+  // Deduplicate by name — replace existing if present
+  const existingIdx = dynamicSkills.findIndex((s) => s.name === name);
+  if (existingIdx !== -1) {
+    dynamicSkills[existingIdx] = skill;
+  } else {
+    dynamicSkills.push(skill);
+  }
+
+  console.log(`  + Dynamic skill registered: ${name} [${skill.strategy}]`);
+  res.json({ ok: true, name, strategy: skill.strategy });
+});
+
+/**
+ * DELETE /api/skills/dynamic — Clears all dropped skills (called on client load)
+ */
+app.delete("/api/skills/dynamic", (_req, res) => {
+  dynamicSkills.length = 0;
+  res.json({ ok: true });
 });
 
 /**
@@ -129,7 +251,7 @@ app.get("/api/health", (_req, res) => {
     status: "ok",
     provider: process.env.ANTHROPIC_API_KEY ? "anthropic" : "openai",
     model,
-    skillCount: skills.length,
+    skillCount: skills.length + dynamicSkills.length,
   });
 });
 
@@ -151,8 +273,9 @@ app.listen(PORT, () => {
 ╚══════════════════════════════════════════════════════════════╝
 
 Endpoints:
-  POST /api/chat    — CopilotProvider chat endpoint
-  GET  /api/skills  — Skill metadata for the UI
-  GET  /api/health  — Health check
+  POST /api/chat             — CopilotProvider chat endpoint
+  GET  /api/skills           — Skill metadata for the UI
+  POST /api/skills/register  — Register a dynamic skill from dropped file
+  GET  /api/health           — Health check
 `);
 });
diff --git a/examples/skills-demo/skills/frontend-design.md b/examples/skills-demo/skills/frontend-design.md
new file mode 100644
index 0000000..ac479b5
--- /dev/null
+++ b/examples/skills-demo/skills/frontend-design.md
@@ -0,0 +1,57 @@
+---
+name: frontend-design
+description: Design and render beautiful UI components — payment cards, dashboards, stat grids, forms — using Tailwind CSS via the render_ui tool
+strategy: auto
+version: 1.0.0
+---
+
+This skill guides creation of distinctive, production-grade UI components rendered via the `render_ui` tool. Avoid generic aesthetics. Every component should have a clear visual identity.
+
+## Output Format
+
+Always use the `render_ui` tool with `type: "html"` for UI components.
+- Tailwind CSS (Play CDN) is pre-loaded in the iframe — use any utility class freely
+- Chart.js is also available for embedded charts
+- Set `height` to fit the content: `"240px"` for cards, `"500px"` for dashboards
+
+## Design Thinking
+
+Before generating, commit to a BOLD aesthetic direction:
+- **Tone**: Pick an extreme — luxury/refined, brutally minimal, glassmorphism, editorial, retro-futuristic, art deco. Never default to generic.
+- **Typography**: Use Google Fonts via `<link>` tag. Distinctive choices only — no Inter, Roboto, or Arial.
+- **Color**: Dominant background with sharp accent. Dark, rich palettes outperform washed-out light themes for cards and dashboards.
+- **Details**: Grain overlays, gradient meshes, subtle borders, layered shadows — atmosphere beats flatness.
+
+## Component Guidance
+
+### Payment Cards
+- Deep, rich background: navy, dark slate, charcoal, or gradient (never plain white)
+- Chip icon (SVG or CSS), masked card number `•••• •••• •••• 4242`, cardholder name, expiry
+- Network logo area (VISA / Mastercard wordmark in text is fine)
+- Glassmorphism with `backdrop-filter: blur` works well
+- Add subtle noise texture via SVG `feTurbulence` filter or CSS `background-image`
+- Height: ~220–260px
+
+### Dashboards
+- Dark base (`#0a0d14` or similar), grid of stat cards + chart
+- Stat cards: metric label (uppercase, muted), large mono value, colored delta badge
+- Use Chart.js inline for any charts
+- Height: 480–600px
+
+### Stat Grids
+- 3–4 column grid, each card: icon, value, label, trend
+- Subtle borders, hover lift effect with CSS transition
+- Height: ~180–200px
+
+### Forms / Auth Screens
+- Single-column centered layout, generous padding
+- Input fields with clear focus rings, matching aesthetic
+- Height: ~380–440px
+
+## Style Rules
+
+NEVER use: Inter, Roboto, Arial, system-ui as primary fonts. NEVER use purple gradients on white. NEVER produce cookie-cutter shadcn defaults without a distinct personality on top.
+
+DO use: unexpected font pairings, asymmetric layouts, deliberate negative space, micro-animations via CSS `@keyframes`, decorative borders, and color that feels intentional.
+
+Every component should be something the user would screenshot and share.
diff --git a/examples/skills-demo/src/App.tsx b/examples/skills-demo/src/App.tsx
index f8b2994..6282381 100644
--- a/examples/skills-demo/src/App.tsx
+++ b/examples/skills-demo/src/App.tsx
@@ -1,569 +1,788 @@
-import { useState, useCallback, useEffect, useRef, useMemo } from "react";
-import { CopilotProvider } from "@yourgpt/copilot-sdk/react";
-import { CopilotChat } from "@yourgpt/copilot-sdk/ui";
+import {
+  useState,
+  useEffect,
+  useContext,
+  createContext,
+  useCallback,
+} from "react";
+import { Drawer } from "vaul";
+import { CopilotProvider, useCopilot } from "@yourgpt/copilot-sdk/react";
+import {
+  CopilotChat,
+  PromptInput,
+  PromptInputTextarea,
+  PromptInputActions,
+  PromptInputAction,
+  SendIcon,
+  StopIcon,
+} from "@yourgpt/copilot-sdk/ui";
+import type { ToolRendererProps } from "@yourgpt/copilot-sdk/ui";
 import "@yourgpt/copilot-sdk/ui/styles.css";
 
-// ─── Skill definitions (client-side metadata) ─────────────────────────────────
+// ─── Skill Activity Context ───────────────────────────────────────────────────
 
-interface SkillMeta {
-  id: string;
-  name: string;
-  icon: string;
-  shortDesc: string;
-  strategy: "eager" | "auto" | "manual";
-  capabilities: string[];
-  color: string;
+interface SkillActivity {
+  executingSkill: string | null;
+  loadedSkills: Set<string>;
+  setExecutingSkill: (name: string | null) => void;
+  addLoadedSkill: (name: string) => void;
 }
 
-type SkillState = "idle" | "scanning" | "loaded";
+const SkillActivityContext = createContext<SkillActivity>({
+  executingSkill: null,
+  loadedSkills: new Set(),
+  setExecutingSkill: () => {},
+  addLoadedSkill: () => {},
+});
 
-const SKILLS: SkillMeta[] = [
-  {
-    id: "revenue-intelligence",
-    name: "Revenue Intelligence",
-    icon: "◈",
-    shortDesc: "MRR trends, churn analysis & expansion signals",
-    strategy: "auto",
-    capabilities: [
-      "Monthly recurring revenue breakdown",
-      "Churn forecasting & root cause",
-      "Expansion revenue opportunity scoring",
-    ],
-    color: "#818cf8",
+// ─── Skill Domain Icons ───────────────────────────────────────────────────────
+
+function RevenueIcon() {
+  return (
+    <svg width="18" height="18" viewBox="0 0 20 20" fill="none">
+      <path
+        d="M2.5 14L7 8.5L10.5 12L15.5 5"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M13 5H15.5V7.5"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M2 16.5H18"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        opacity="0.3"
+      />
+    </svg>
+  );
+}
+
+function HealthIcon() {
+  return (
+    <svg width="18" height="18" viewBox="0 0 20 20" fill="none">
+      <path
+        d="M10 16.5C10 16.5 2.5 12 2.5 6.75C2.5 4.68 4.18 3 6.25 3C7.76 3 9.06 3.9 10 5C10.94 3.9 12.24 3 13.75 3C15.82 3 17.5 4.68 17.5 6.75C17.5 12 10 16.5 10 16.5Z"
+        fill="currentColor"
+        opacity="0.15"
+        stroke="currentColor"
+        strokeWidth="1.75"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M6.5 9.5H8.5L10 7L12 12L13.5 9.5H14.5"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+function IncidentIcon() {
+  return (
+    <svg width="18" height="18" viewBox="0 0 20 20" fill="none">
+      <path
+        d="M10 2.5L2 17H18L10 2.5Z"
+        fill="currentColor"
+        opacity="0.12"
+        stroke="currentColor"
+        strokeWidth="1.75"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M10 8.5V11.5"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+      />
+      <circle cx="10" cy="14.5" r="0.875" fill="currentColor" />
+    </svg>
+  );
+}
+
+function DefaultSkillIcon() {
+  return (
+    <svg width="18" height="18" viewBox="0 0 20 20" fill="none">
+      <circle
+        cx="10"
+        cy="10"
+        r="7"
+        stroke="currentColor"
+        strokeWidth="1.75"
+        opacity="0.35"
+      />
+      <path
+        d="M10 7V10.5L12.5 13"
+        stroke="currentColor"
+        strokeWidth="1.75"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+// ─── Skill Config Map ─────────────────────────────────────────────────────────
+
+interface SkillConfig {
+  color: string;
+  bg: string;
+  Icon: () => JSX.Element;
+}
+
+const SKILL_CONFIGS: Record<string, SkillConfig> = {
+  "revenue-intelligence": {
+    color: "#0d9488",
+    bg: "rgba(13, 148, 136, 0.08)",
+    Icon: RevenueIcon,
   },
-  {
-    id: "customer-health",
-    name: "Customer Health",
-    icon: "◉",
-    shortDesc: "Account risk scoring & engagement signals",
-    strategy: "auto",
-    capabilities: [
-      "Health score calculation (0–100)",
-      "At-risk account early warning",
-      "Engagement drop-off detection",
-    ],
-    color: "#34d399",
+  "customer-health": {
+    color: "#f59e0b",
+    bg: "rgba(245, 158, 11, 0.08)",
+    Icon: HealthIcon,
   },
-  {
-    id: "incident-runbook",
-    name: "Incident Runbook",
-    icon: "◬",
-    shortDesc: "Production incident response protocol",
-    strategy: "manual",
-    capabilities: [
-      "Severity classification P0–P3",
-      "Step-by-step response checklist",
-      "Stakeholder communication templates",
-    ],
-    color: "#fb923c",
+  "incident-runbook": {
+    color: "#ef4444",
+    bg: "rgba(239, 68, 68, 0.08)",
+    Icon: IncidentIcon,
   },
-];
+};
 
-const METRICS = [
-  { label: "MRR", value: "$124.8k", change: "+12%", up: true },
-  { label: "Churn", value: "2.3%", change: "−0.4%", up: true },
-  { label: "DAU", value: "8,429", change: "+5%", up: true },
-  { label: "Open P1s", value: "2", change: "+2", up: false },
-];
+// ─── General Icons ────────────────────────────────────────────────────────────
 
-const DEMO_PROMPTS = [
-  "Analyze our MRR growth and top churn risks this month",
-  "Which enterprise accounts are most at risk right now?",
-  "We have a P1 — payment API is returning 503 errors",
-];
+function AiIdeaIcon({ className = "" }: { className?: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      className={className}
+    >
+      <path
+        fillRule="evenodd"
+        clipRule="evenodd"
+        d="M11.5 1.25C12.5375 1.25 13.5302 1.4415 14.4448 1.79107L14.3664 2.00295C14.1817 2.50197 14.0537 2.81903 13.9797 2.97966C13.819 3.05365 13.502 3.18172 13.003 3.36637L12.3059 3.6243C11.5211 3.91472 11 4.66312 11 5.5C11 6.33688 11.5211 7.08527 12.3059 7.3757L13.003 7.63363C13.502 7.81828 13.819 7.94635 13.9797 8.02034C14.0537 8.18097 14.1817 8.49803 14.3664 8.99705L14.6243 9.69407C14.9147 10.4789 15.6631 11 16.5 11C17.3369 11 18.0853 10.4789 18.3757 9.69407L18.6336 8.99705C18.8183 8.49803 18.9463 8.18097 19.0203 8.02034C19.1296 7.97001 19.3112 7.89466 19.5733 7.7935C19.6891 8.34411 19.75 8.91495 19.75 9.5C19.75 12.6019 18.0381 15.304 15.5075 16.713L15.398 17.37C15.2172 18.4549 14.2785 19.2501 13.1786 19.2501H9.72003C8.62014 19.2501 7.68146 18.4549 7.50064 17.37L7.38056 16.6495C4.91156 15.2238 3.25 12.556 3.25 9.5C3.25 4.94365 6.94365 1.25 11.5 1.25ZM16.5 1.25C16.8138 1.25 17.0945 1.4454 17.2034 1.73972L17.4613 2.43675C17.8233 3.4151 17.9388 3.68091 18.1289 3.87106C18.3191 4.06121 18.5849 4.17667 19.5633 4.53869L20.2603 4.79661C20.5546 4.90552 20.75 5.18617 20.75 5.5C20.75 5.81383 20.5546 6.09448 20.2603 6.20339L19.5633 6.46131C18.5849 6.82333 18.3191 6.93879 18.1289 7.12894C17.9388 7.31909 17.8233 7.5849 17.4613 8.56325L17.2034 9.26028C17.0945 9.5546 16.8138 9.75 16.5 9.75C16.1862 9.75 15.9055 9.5546 15.7966 9.26028L15.5387 8.56325C15.1767 7.5849 15.0612 7.31909 14.8711 7.12894C14.6809 6.93879 14.4151 6.82333 13.4367 6.46131L12.7397 6.20339C12.4454 6.09448 12.25 5.81383 12.25 5.5C12.25 5.18617 12.4454 4.90552 12.7397 4.79661L13.4367 4.53869C14.4151 4.17667 14.6809 4.06121 14.8711 3.87106C15.0612 3.68091 15.1767 7.5849 15.5387 2.43675L15.7966 1.73972C15.9055 1.4454 16.1862 1.25 16.5 1.25ZM8.75 20.5V20.9999C8.75 21.9664 9.5335 22.7499 10.5 22.7499H12.5C13.4665 22.7499 14.25 21.9664 14.25 20.9999V20.5H8.75Z"
+      />
+    </svg>
+  );
+}
+
+function CheckCircleIcon({ className = "" }: { className?: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      className={className}
+    >
+      <path
+        fillRule="evenodd"
+        clipRule="evenodd"
+        d="M12 22.75C6.06294 22.75 1.25 17.9371 1.25 12C1.25 6.06294 6.06294 1.25 12 1.25C17.9371 1.25 22.75 6.06294 22.75 12C22.75 17.9371 17.9371 22.75 12 22.75ZM16.48 9.37756C16.9645 9.11257 17.1425 8.50493 16.8775 8.02038C16.6125 7.53582 16.0049 7.35782 15.5204 7.62282C13.6917 8.62286 12.1796 10.5529 11.1629 12.1096C10.7872 12.685 10.4662 13.2297 10.2094 13.6911C9.96984 13.4587 9.73258 13.257 9.52038 13.0892C9.2427 12.8697 8.99282 12.6965 8.81063 12.5772L8.49559 12.3815C8.01585 12.1079 7.40513 12.275 7.13152 12.7548C6.85797 13.2344 7.02493 13.8449 7.50442 14.1187L7.71471 14.2502C7.85752 14.3437 8.05764 14.4823 8.27997 14.6581C8.73753 15.0198 9.23126 15.494 9.54198 16.0135C9.73267 16.3323 10.0844 16.5191 10.4553 16.4987C10.8261 16.4782 11.1551 16.2536 11.3096 15.9159L11.4079 15.7105C11.4756 15.5721 11.577 15.3697 11.709 15.1204C11.9735 14.6207 12.3581 13.9372 12.8374 13.2032C13.8208 11.6975 15.1086 10.1275 16.48 9.37756Z"
+      />
+    </svg>
+  );
+}
 
-// ─── Skill load notifier (invisible, watches for load_skill tool calls) ───────
+// ─── TextShimmer ──────────────────────────────────────────────────────────────
 
-function SkillLoadNotifier({
-  args,
-  status,
-  onLoaded,
+function TextShimmer({
+  children,
+  duration = 1.8,
 }: {
-  args: Record<string, unknown>;
-  status: string;
-  result?: unknown;
-  toolCallId: string;
-  onLoaded: (name: string) => void;
+  children: string;
+  duration?: number;
 }) {
-  const firedRef = useRef(false);
-  useEffect(() => {
-    if (status === "success" && args?.name && !firedRef.current) {
-      firedRef.current = true;
-      onLoaded(args.name as string);
-    }
-  }, [status, args?.name, onLoaded]);
-  return null;
+  return (
+    <span
+      className="text-shimmer"
+      style={{ animationDuration: `${duration}s` }}
+    >
+      {children}
+    </span>
+  );
 }
 
-// ─── Individual skill card ────────────────────────────────────────────────────
+// ─── Tool Renderers ───────────────────────────────────────────────────────────
 
-function SkillCard({ skill, state }: { skill: SkillMeta; state: SkillState }) {
-  const isLoaded = state === "loaded";
-  const isScanning = state === "scanning";
-  const strategyLabel = {
-    eager: "ALWAYS ON",
-    auto: "AUTO",
-    manual: "ON DEMAND",
-  };
+function SkillLoadedCard({ execution }: ToolRendererProps) {
+  const { setExecutingSkill, addLoadedSkill } =
+    useContext(SkillActivityContext);
 
-  return (
-    <div
-      className="skill-card"
-      data-state={state}
-      style={{ "--sc": skill.color } as React.CSSProperties}
-    >
-      {isScanning && <div className="scan-line" />}
+  const skillName = (execution.args?.name ??
+    execution.args?.skill_name ??
+    execution.args?.skill ??
+    "skill") as string;
 
-      <div className="sc-header">
-        <span className="sc-icon" data-scanning={isScanning}>
-          {skill.icon}
-        </span>
-        <div className="sc-title-group">
-          <span className="sc-name">{skill.name}</span>
-          <span className={`sc-badge sc-badge--${skill.strategy}`}>
-            {strategyLabel[skill.strategy]}
-          </span>
-        </div>
-        <span className="sc-dot" data-active={isLoaded} />
+  // Sync state to skills panel — must be before any early return (Rules of Hooks)
+  useEffect(() => {
+    if (execution.status === "pending" || execution.status === "executing") {
+      setExecutingSkill(skillName);
+    } else if (execution.status === "completed" && execution.result) {
+      addLoadedSkill(skillName);
+      const t = setTimeout(() => setExecutingSkill(null), 600);
+      return () => clearTimeout(t);
+    }
+  }, [
+    execution.status,
+    execution.result,
+    skillName,
+    setExecutingSkill,
+    addLoadedSkill,
+  ]);
+
+  // Guard phantom completed-without-result double-fire from SDK
+  if (execution.status === "completed" && !execution.result) return null;
+
+  if (execution.status === "pending" || execution.status === "executing") {
+    return (
+      <div className="flex items-center gap-1.5 px-0.5 py-1">
+        <AiIdeaIcon className="size-4 shrink-0 text-primary" />
+        <span className="text-xs text-muted-foreground">Reading from:</span>
+        <TextShimmer duration={1.8}>{skillName}</TextShimmer>
       </div>
+    );
+  }
 
-      <p className="sc-desc">{skill.shortDesc}</p>
-
-      <div className="sc-expanded" data-open={isLoaded}>
-        <div className="sc-divider" />
-        <p className="sc-active-label">✦ Skill active</p>
-        <ul className="sc-caps">
-          {skill.capabilities.map((cap, i) => (
-            <li
-              key={cap}
-              className="sc-cap"
-              data-visible={isLoaded}
-              style={{
-                transitionDelay: isLoaded ? `${0.12 + i * 0.09}s` : "0s",
-              }}
-            >
-              <span className="sc-cap-dot" />
-              {cap}
-            </li>
-          ))}
-        </ul>
+  if (execution.status === "error" || execution.status === "failed") {
+    return (
+      <div className="flex items-center gap-1.5 px-0.5 py-1">
+        <span className="text-xs text-destructive">
+          Failed to load skill: {skillName}
+        </span>
       </div>
+    );
+  }
+
+  // Completed with result — show a distinct "read" confirmation
+  return (
+    <div className="flex items-center gap-1.5 px-0.5 py-1">
+      <AiIdeaIcon className="size-4 shrink-0 text-primary" />
+      <p className="text-xs text-muted-foreground">
+        Reading from:{" "}
+        <span className="font-medium text-foreground">{skillName}</span>
+      </p>
     </div>
   );
 }
 
-// ─── Main app ─────────────────────────────────────────────────────────────────
+function FallbackToolCard({ execution }: ToolRendererProps) {
+  const label = execution.name
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
 
-export default function App() {
-  const [skillStates, setSkillStates] = useState<Record<string, SkillState>>(
-    () => Object.fromEntries(SKILLS.map((s) => [s.id, "idle"])),
-  );
-  const [branchingEnabled, setBranchingEnabled] = useState(false);
-
-  const handleSkillLoaded = useCallback((skillName: string) => {
-    if (!SKILLS.find((s) => s.id === skillName)) return;
-    setSkillStates((prev) =>
-      prev[skillName] === "loaded"
-        ? prev
-        : { ...prev, [skillName]: "scanning" },
+  if (execution.status === "pending" || execution.status === "executing") {
+    return (
+      <div className="px-0.5 py-1">
+        <TextShimmer>{`Running ${label}…`}</TextShimmer>
+      </div>
     );
-    setTimeout(() => {
-      setSkillStates((prev) => ({ ...prev, [skillName]: "loaded" }));
-    }, 1500);
-  }, []);
+  }
 
-  const toolRenderers = useMemo(
-    () => ({
-      load_skill: (props: {
-        args: Record<string, unknown>;
-        status: string;
-        result?: unknown;
-        toolCallId: string;
-      }) => <SkillLoadNotifier {...props} onLoaded={handleSkillLoaded} />,
-    }),
-    [handleSkillLoaded],
+  const isError = execution.status === "error" || execution.status === "failed";
+  return (
+    <div className="flex items-center gap-1.5 px-0.5 py-1">
+      {isError ? (
+        <span className="size-4 text-destructive shrink-0 text-sm">✕</span>
+      ) : (
+        <CheckCircleIcon className="size-4 text-emerald-500 shrink-0" />
+      )}
+      <span className="text-xs text-muted-foreground">{label}</span>
+    </div>
   );
+}
 
-  const injectPrompt = (text: string) => {
-    const ta = document.querySelector<HTMLTextAreaElement>(
-      "textarea[placeholder]",
-    );
-    if (!ta) return;
-    const setter = Object.getOwnPropertyDescriptor(
-      window.HTMLTextAreaElement.prototype,
-      "value",
-    )?.set;
-    setter?.call(ta, text);
-    ta.dispatchEvent(new Event("input", { bubbles: true }));
-    ta.focus();
+const toolRenderers = { load_skill: SkillLoadedCard };
+
+// ─── Custom Fixed Input ───────────────────────────────────────────────────────
+// Uses useCopilot() (CopilotProvider-level) instead of useCopilotChatContext()
+// so it can live as a sibling to CopilotChat without being inside renderInput.
+// This lets the SDK's use-stick-to-bottom auto-scroll work correctly.
+
+function CustomInput() {
+  const { sendMessage, stop, isLoading } = useCopilot();
+  const [value, setValue] = useState("");
+
+  const submit = () => {
+    if (!value.trim() || isLoading) return;
+    sendMessage(value);
+    setValue("");
   };
 
   return (
-    <>
-      <style>{CSS}</style>
-      <div className="d-root">
-        {/* Top nav */}
-        <header className="d-nav">
-          <div className="d-nav__brand">
-            <span className="d-nav__logo">⬡</span>
-            <span className="d-nav__name">Dash</span>
-            <span className="d-nav__platform">Operations Platform</span>
-          </div>
-          <nav className="d-nav__links">
-            {["Overview", "Revenue", "Customers", "Incidents", "Settings"].map(
-              (l) => (
-                <span key={l} className="d-nav__link">
-                  {l}
-                </span>
-              ),
-            )}
-          </nav>
-          <div className="d-nav__copilot">
-            <span className="d-nav__pulse" />
-            AI Copilot
-          </div>
-        </header>
-
-        <div className="d-body">
-          {/* Sidebar */}
-          <aside className="d-sidebar">
-            {/* Metrics */}
-            <section className="d-section">
-              <h3 className="d-section__label">Live Metrics</h3>
-              <div className="d-metrics">
-                {METRICS.map((m) => (
-                  <div key={m.label} className="d-metric">
-                    <span className="d-metric__label">{m.label}</span>
-                    <span className="d-metric__val">{m.value}</span>
-                    <span className={`d-metric__chg ${m.up ? "up" : "dn"}`}>
-                      {m.change}
-                    </span>
-                  </div>
-                ))}
-              </div>
-            </section>
-
-            {/* Skills */}
-            <section className="d-section d-section--skills">
-              <div className="d-section__header-row">
-                <h3 className="d-section__label">Copilot Skills</h3>
-                <span className="d-section__count">{SKILLS.length}</span>
-              </div>
-              <div className="d-skills">
-                {SKILLS.map((skill) => (
-                  <SkillCard
-                    key={skill.id}
-                    skill={skill}
-                    state={skillStates[skill.id] ?? "idle"}
-                  />
-                ))}
-              </div>
-            </section>
-
-            {/* Branching */}
-            <section className="d-section d-section--branch">
-              <div className="d-branch">
-                <div>
-                  <p className="d-branch__label">Conversation Branching</p>
-                  <p className="d-branch__desc">
-                    Edit messages to explore alternatives
-                  </p>
-                </div>
-                <button
-                  className={`d-toggle ${branchingEnabled ? "d-toggle--on" : ""}`}
-                  onClick={() => setBranchingEnabled((v) => !v)}
-                />
-              </div>
-            </section>
-
-            {/* Demo prompts */}
-            <section className="d-section d-section--prompts">
-              <h3 className="d-section__label">Try asking…</h3>
-              <div className="d-prompts">
-                {DEMO_PROMPTS.map((p) => (
-                  <button
-                    key={p}
-                    className="d-prompt"
-                    onClick={() => injectPrompt(p)}
-                  >
-                    {p}
-                  </button>
-                ))}
-              </div>
-            </section>
-          </aside>
-
-          {/* Chat */}
-          <main className="d-chat">
-            <CopilotProvider runtimeUrl="/api/chat">
-              <CopilotChat
-                className="d-copilot"
-                placeholder="Ask about revenue, customers, or incidents…"
-                showHeader
-                header={{ name: "Dash Copilot" }}
-                loaderVariant="typing"
-                showUserAvatar
-                allowEdit={branchingEnabled}
-                toolRenderers={toolRenderers as never}
-              />
-            </CopilotProvider>
-          </main>
-        </div>
-      </div>
-    </>
+    <div className="custom-input-fixed">
+      <PromptInput
+        value={value}
+        onValueChange={setValue}
+        onSubmit={submit}
+        isLoading={isLoading}
+        className="custom-prompt-input"
+      >
+        <PromptInputTextarea
+          placeholder="Ask about revenue, customers, incidents… or say 'design me a payment card'"
+          className="custom-prompt-textarea"
+        />
+        <PromptInputActions className="custom-prompt-actions">
+          <PromptInputAction tooltip={isLoading ? "Stop" : "Send"}>
+            <button
+              onClick={isLoading ? stop : submit}
+              className="custom-send-btn"
+            >
+              {isLoading ? (
+                <StopIcon className="size-3.5" />
+              ) : (
+                <SendIcon className="size-3.5" />
+              )}
+            </button>
+          </PromptInputAction>
+        </PromptInputActions>
+      </PromptInput>
+    </div>
   );
 }
 
-// ─── All styles ───────────────────────────────────────────────────────────────
-
-const CSS = `
-*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-
-:root {
-  --bg:       #07090f;
-  --s1:       #0b0e1a;
-  --s2:       #0f1320;
-  --s3:       #141929;
-  --bd:       rgba(255,255,255,0.055);
-  --bd2:      rgba(255,255,255,0.10);
-  --t1:       #e8eaf6;
-  --t2:       #7b82a8;
-  --t3:       #3d4468;
-  --ok:       #34d399;
-  --err:      #f87171;
-  --acc:      #818cf8;
-  --font:     'Bricolage Grotesque', system-ui, sans-serif;
-  --mono:     'JetBrains Mono', monospace;
-}
+// ─── Welcome message (bypasses home screen; shown on load) ───────────────────
 
-body {
-  background: var(--bg);
-  font-family: var(--font);
-  color: var(--t1);
-  -webkit-font-smoothing: antialiased;
-}
+const INITIAL_MESSAGES = [
+  {
+    id: "welcome-1",
+    role: "assistant" as const,
+    content:
+      "Hey! I'm **Dash Copilot** — your AI assistant for this analytics platform.\n\nI can help you with:\n- **Revenue & MRR** — trends, churn, growth metrics\n- **Customer health** — at-risk accounts, engagement scores\n- **Incidents** — response runbooks, severity triage\n- **UI design** — render payment cards, dashboards, stat grids\n\nJust ask me anything to get started.",
+    createdAt: new Date(),
+  },
+];
 
-/* ── Root ── */
-.d-root { display: flex; flex-direction: column; height: 100vh; overflow: hidden; }
+// ─── Logo avatar ─────────────────────────────────────────────────────────────
 
-/* ── Nav ── */
-.d-nav {
-  display: flex; align-items: center; gap: 20px;
-  padding: 0 20px; height: 50px; flex-shrink: 0;
-  background: var(--s1);
-  border-bottom: 1px solid var(--bd);
-}
-.d-nav__brand  { display: flex; align-items: center; gap: 8px; }
-.d-nav__logo   { font-size: 19px; color: var(--acc); }
-.d-nav__name   { font-weight: 700; font-size: 15px; letter-spacing: -0.04em; }
-.d-nav__platform { font-size: 11px; color: var(--t3); margin-left: 1px; }
-.d-nav__links  { display: flex; gap: 1px; margin-left: auto; }
-.d-nav__link   {
-  padding: 4px 11px; border-radius: 6px;
-  font-size: 12px; color: var(--t2); cursor: pointer;
-  transition: all 0.12s;
-}
-.d-nav__link:hover { background: var(--s2); color: var(--t1); }
-.d-nav__copilot {
-  display: flex; align-items: center; gap: 7px;
-  padding: 4px 12px; border-radius: 20px;
-  background: rgba(129,140,248,0.08);
-  border: 1px solid rgba(129,140,248,0.2);
-  font-size: 11px; font-weight: 600; color: var(--acc);
-  letter-spacing: 0.05em; text-transform: uppercase;
-}
-.d-nav__pulse {
-  width: 6px; height: 6px; border-radius: 50%; background: var(--acc);
-  animation: nav-pulse 2.2s ease-in-out infinite;
-}
-@keyframes nav-pulse {
-  0%,100% { opacity:.5; transform:scale(1); }
-  50%      { opacity:1;  transform:scale(1.35); }
+function LogoAvatar() {
+  return (
+    <svg
+      width="22"
+      height="22"
+      viewBox="0 0 28 28"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        opacity="0.4"
+        d="M17.3887 1.87109C17.7844 1.87109 18.1273 2.14532 18.2143 2.53134L18.8221 5.22971C19.2659 7.19972 20.8043 8.73814 22.7743 9.1819L25.4727 9.78974C25.8588 9.8767 26.1329 10.2196 26.1329 10.6153C26.1329 11.011 25.8588 11.3538 25.4727 11.4408L22.7743 12.0486C20.8043 12.4924 19.2659 14.0308 18.8221 16.0008L18.2143 18.6992C18.1273 19.0853 17.7844 19.3594 17.3887 19.3594C16.993 19.3594 16.6502 19.0853 16.5632 18.6992L15.9554 16.0008C15.5116 14.0308 13.9732 12.4924 12.0032 12.0486L9.30478 11.4408C8.91876 11.3538 8.64453 11.011 8.64453 10.6153C8.64453 10.2196 8.91876 9.8767 9.30478 9.78974L12.0032 9.1819C13.9732 8.73814 15.5116 7.19972 15.9554 5.22971L16.5632 2.53134C16.6502 2.14532 16.993 1.87109 17.3887 1.87109Z"
+        fill="#007676"
+      />
+      <path
+        d="M8.36264 13.1523C8.75834 13.1523 9.10121 13.4265 9.18817 13.8126L9.62233 15.7401C9.9188 17.0561 10.9465 18.0838 12.2626 18.3802L14.19 18.8144C14.5761 18.9014 14.8503 19.2443 14.8503 19.64C14.8503 20.0356 14.5761 20.3785 14.19 20.4655L12.2626 20.8997C10.9465 21.1961 9.9188 22.2238 9.62233 23.5399L9.18817 25.4673C9.10121 25.8534 8.75834 26.1276 8.36264 26.1276C7.96694 26.1276 7.62406 25.8534 7.53711 25.4673L7.10294 23.5399C6.80647 22.2238 5.77873 21.1961 4.46266 20.8997L2.53525 20.4655C2.14923 20.3785 1.875 20.0356 1.875 19.64C1.875 19.2443 2.14923 18.9014 2.53525 18.8144L4.46266 18.3802C5.77873 18.0838 6.80647 17.0561 7.10294 15.7401L7.53711 13.8126C7.62406 13.4265 7.96694 13.1523 8.36264 13.1523Z"
+        fill="#007676"
+      />
+    </svg>
+  );
 }
 
-/* ── Body ── */
-.d-body { display: flex; flex: 1; min-height: 0; }
+// ─── Chat Inner ───────────────────────────────────────────────────────────────
 
-/* ── Sidebar ── */
-.d-sidebar {
-  width: 296px; flex-shrink: 0;
-  background: var(--s1); border-right: 1px solid var(--bd);
-  overflow-y: auto; display: flex; flex-direction: column;
-  scrollbar-width: thin; scrollbar-color: var(--bd2) transparent;
+function ChatInner() {
+  return (
+    <div className="h-[600px] my-auto">
+      <CopilotChat
+        className=""
+        loaderVariant="typing"
+        placeholder="Ask about revenue, customers, incidents…"
+        toolRenderers={toolRenderers}
+        fallbackToolRenderer={FallbackToolCard}
+        attachmentsEnabled={false}
+        assistantAvatar={{
+          component: <LogoAvatar />,
+          className:
+            "!bg-white !rounded-full shadow-sm flex items-center justify-center",
+        }}
+      />
+    </div>
+  );
 }
 
-.d-section {
-  padding: 14px 14px;
-  border-bottom: 1px solid var(--bd);
-}
-.d-section__label {
-  font-size: 10px; font-weight: 600; letter-spacing: 0.1em;
-  text-transform: uppercase; color: var(--t3); margin-bottom: 10px;
-}
-.d-section__header-row {
-  display: flex; align-items: center; justify-content: space-between; margin-bottom: 10px;
-}
-.d-section__count {
-  font-family: var(--mono); font-size: 10px; color: var(--t3);
-  background: var(--s2); padding: 1px 6px; border-radius: 8px;
-  border: 1px solid var(--bd);
-}
+// ─── Skills Panel ─────────────────────────────────────────────────────────────
 
-/* ── Metrics ── */
-.d-metrics { display: grid; grid-template-columns: 1fr 1fr; gap: 7px; }
-.d-metric {
-  background: var(--s2); border: 1px solid var(--bd);
-  border-radius: 8px; padding: 9px 10px 7px;
-  display: flex; flex-direction: column; gap: 1px;
-}
-.d-metric__label { font-size: 9.5px; color: var(--t3); font-weight: 500; text-transform: uppercase; letter-spacing: 0.06em; }
-.d-metric__val   { font-family: var(--mono); font-size: 16px; font-weight: 500; color: var(--t1); line-height: 1.2; }
-.d-metric__chg   { font-family: var(--mono); font-size: 10px; font-weight: 500; }
-.d-metric__chg.up { color: var(--ok); }
-.d-metric__chg.dn { color: var(--err); }
-
-/* ── Skills ── */
-.d-skills { display: flex; flex-direction: column; gap: 7px; }
-
-.skill-card {
-  position: relative; overflow: hidden;
-  border-radius: 10px; padding: 11px;
-  background: var(--s2); border: 1px solid var(--bd);
-  transition: border-color 0.45s ease, background 0.45s ease, box-shadow 0.45s ease;
-}
-.skill-card[data-state="scanning"] {
-  border-color: rgba(255,255,255,0.13);
-  background: var(--s3);
-}
-.skill-card[data-state="loaded"] {
-  border-color: color-mix(in srgb, var(--sc) 38%, transparent);
-  background: color-mix(in srgb, var(--sc) 6%, var(--s2));
-  box-shadow: 0 0 22px -4px color-mix(in srgb, var(--sc) 22%, transparent);
-  animation: card-pop 0.55s cubic-bezier(0.22,1,0.36,1);
-}
-@keyframes card-pop {
-  0%   { box-shadow: 0 0 0 0 color-mix(in srgb, var(--sc) 55%, transparent); }
-  45%  { box-shadow: 0 0 28px 5px color-mix(in srgb, var(--sc) 32%, transparent); }
-  100% { box-shadow: 0 0 22px -4px color-mix(in srgb, var(--sc) 22%, transparent); }
-}
+interface Skill {
+  name: string;
+  description: string;
+  strategy: string;
+  version?: string;
+  source?: string;
+}
+
+function slugToTitle(slug: string): string {
+  return slug.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function parseFrontmatter(content: string): Record<string, string> {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const result: Record<string, string> = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const val = line
+      .slice(colonIdx + 1)
+      .trim()
+      .replace(/^["']|["']$/g, "");
+    if (key) result[key] = val;
+  }
+  return result;
+}
+
+function SkillCard({ skill }: { skill: Skill }) {
+  const { executingSkill, loadedSkills } = useContext(SkillActivityContext);
+  const isExecuting = executingSkill === skill.name;
+  const isLoaded = loadedSkills.has(skill.name);
+  const isActive = isExecuting || isLoaded;
+
+  const config = SKILL_CONFIGS[skill.name];
+  const Icon = config?.Icon ?? DefaultSkillIcon;
+  const color = config?.color ?? "#6b7280";
+  const bg = config?.bg ?? "rgba(107, 114, 128, 0.08)";
+  const displayName = slugToTitle(skill.name);
+
+  const [open, setOpen] = useState(false);
+  const [content, setContent] = useState<string | null>(null);
+
+  const handleOpen = (val: boolean) => {
+    setOpen(val);
+    if (val && content === null) {
+      fetch(`/api/skills/${skill.name}`)
+        .then((r) => r.json())
+        .then((d) => {
+          // Strip frontmatter block
+          const raw: string = d.content ?? "";
+          const stripped = raw.replace(/^---[\s\S]*?---\r?\n/, "").trim();
+          setContent(stripped);
+        })
+        .catch(() => setContent("Could not load skill content."));
+    }
+  };
 
-/* Scan line */
-.scan-line {
-  position: absolute; inset: 0; pointer-events: none; z-index: 10;
-  background: linear-gradient(
-    to bottom,
-    transparent 0%,
-    rgba(255,255,255,0.03) 40%,
-    rgba(255,255,255,0.11) 50%,
-    rgba(255,255,255,0.03) 60%,
-    transparent 100%
+  const cardEl = (
+    <div
+      className={`skill-card${isActive ? " skill-card--active" : ""}${isExecuting ? " skill-card--executing" : ""}`}
+      style={
+        isActive
+          ? ({
+              "--skill-color": color,
+              "--skill-bg": bg,
+            } as React.CSSProperties)
+          : undefined
+      }
+    >
+      <div className="skill-card-body">
+        <div
+          className="skill-icon-wrap"
+          style={{
+            background: isActive ? bg : "rgba(0,0,0,0.04)",
+            color: isActive ? color : "#9ca3af",
+          }}
+        >
+          <Icon />
+        </div>
+        <div className="skill-card-content">
+          <div className="skill-card-header">
+            <span
+              className="skill-card-title"
+              style={isActive ? { color } : undefined}
+            >
+              {displayName}
+            </span>
+            <div className="skill-card-right">
+              {isExecuting && !isLoaded && (
+                <span
+                  className="skill-loaded-badge"
+                  style={{ color, background: bg, borderColor: color + "40" }}
+                >
+                  Loading…
+                </span>
+              )}
+              {isLoaded && !isExecuting && (
+                <span
+                  className="skill-loaded-badge"
+                  style={{ color, background: bg, borderColor: color + "40" }}
+                >
+                  ✓ Loaded
+                </span>
+              )}
+              {!isActive && (
+                <span
+                  className={`skill-badge ${skill.source === "dropped" ? "skill-badge--dropped" : "skill-badge--file"}`}
+                >
+                  {skill.source === "dropped" ? "Dropped" : "Skill"}
+                </span>
+              )}
+            </div>
+          </div>
+          <p className="skill-card-desc">{skill.description}</p>
+        </div>
+      </div>
+      {isLoaded && (
+        <div className="skill-loaded-section" style={{ color }}>
+          <svg width="10" height="10" viewBox="0 0 12 12" fill="none">
+            <circle
+              cx="6"
+              cy="6"
+              r="5.5"
+              fill={color}
+              opacity="0.18"
+              stroke={color}
+              strokeWidth="1"
+            />
+            <path
+              d="M3.5 6L5 7.5L8.5 4"
+              stroke={color}
+              strokeWidth="1.25"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+          <span>Loaded by Copilot</span>
+        </div>
+      )}
+    </div>
   );
-  animation: scan 1.5s cubic-bezier(0.4,0,0.2,1) forwards;
-}
-@keyframes scan {
-  0%   { transform: translateY(-110%); opacity: 1; }
-  80%  { opacity: 1; }
-  100% { transform: translateY(210%);  opacity: 0; }
-}
 
-.sc-header { display: flex; align-items: center; gap: 8px; margin-bottom: 5px; }
-.sc-icon {
-  font-size: 17px; line-height: 1; flex-shrink: 0;
-  color: var(--sc);
-  transition: transform 0.3s ease;
-}
-.skill-card[data-state="loaded"] .sc-icon { transform: scale(1.12); }
-.sc-icon[data-scanning="true"] { animation: icon-spin 1.5s ease-in-out; }
-@keyframes icon-spin {
-  0%   { transform: rotate(0deg)   scale(1); }
-  50%  { transform: rotate(180deg) scale(1.2); }
-  100% { transform: rotate(360deg) scale(1); }
+  return (
+    <Drawer.Root open={open} onOpenChange={handleOpen} shouldScaleBackground>
+      <Drawer.Trigger asChild>{cardEl}</Drawer.Trigger>
+      <Drawer.Portal>
+        <Drawer.Overlay className="skill-drawer-overlay" />
+        <Drawer.Content className="skill-drawer-content">
+          {/* Drag handle */}
+          <div className="skill-drawer-handle" />
+
+          {/* Header */}
+          <div
+            className="skill-drawer-header"
+            style={{ borderColor: color + "22" }}
+          >
+            <div
+              className="skill-drawer-icon"
+              style={{ background: bg, color }}
+            >
+              <Icon />
+            </div>
+            <div className="skill-drawer-header-text">
+              <Drawer.Title className="skill-drawer-title" style={{ color }}>
+                {displayName}
+              </Drawer.Title>
+              <p className="skill-drawer-subtitle">{skill.description}</p>
+            </div>
+            <div className="skill-drawer-meta">
+              <span
+                className="skill-drawer-badge"
+                style={{ background: bg, color, borderColor: color + "30" }}
+              >
+                {skill.strategy}
+              </span>
+              {skill.version && (
+                <span className="skill-drawer-version">v{skill.version}</span>
+              )}
+            </div>
+          </div>
+
+          {/* Content */}
+          <div className="skill-drawer-body">
+            {content === null ? (
+              <p className="skill-drawer-loading">Loading…</p>
+            ) : (
+              <pre className="skill-drawer-text">{content}</pre>
+            )}
+          </div>
+        </Drawer.Content>
+      </Drawer.Portal>
+    </Drawer.Root>
+  );
 }
 
-.sc-title-group { display: flex; flex-direction: column; gap: 2px; flex: 1; min-width: 0; }
-.sc-name { font-size: 12.5px; font-weight: 600; color: var(--t1); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+function SkillsPanel() {
+  const [skills, setSkills] = useState<Skill[]>([]);
+  const [isDragging, setIsDragging] = useState(false);
 
-.sc-badge {
-  font-size: 9px; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase;
-  padding: 1px 5px; border-radius: 4px; width: fit-content;
-}
-.sc-badge--eager  { background: rgba(52,211,153,.12); color: #34d399; border: 1px solid rgba(52,211,153,.2); }
-.sc-badge--auto   { background: rgba(129,140,248,.12); color: #818cf8; border: 1px solid rgba(129,140,248,.2); }
-.sc-badge--manual { background: rgba(251,146,60,.12);  color: #fb923c; border: 1px solid rgba(251,146,60,.2); }
-
-.sc-dot {
-  width: 7px; height: 7px; border-radius: 50%; flex-shrink: 0;
-  background: var(--t3);
-  transition: background 0.35s, box-shadow 0.35s;
-}
-.sc-dot[data-active="true"] {
-  background: var(--sc);
-  box-shadow: 0 0 7px 1px color-mix(in srgb, var(--sc) 55%, transparent);
-  animation: dot-breathe 2s ease-in-out infinite;
-}
-@keyframes dot-breathe {
-  0%,100% { box-shadow: 0 0 7px 1px color-mix(in srgb, var(--sc) 45%, transparent); }
-  50%      { box-shadow: 0 0 11px 3px color-mix(in srgb, var(--sc) 65%, transparent); }
-}
+  useEffect(() => {
+    // Clear any dropped skills from previous session on page load
+    fetch("/api/skills/dynamic", { method: "DELETE" }).catch(() => {});
+    fetch("/api/skills")
+      .then((r) => r.json())
+      .then((data: Skill[]) => setSkills(data))
+      .catch(() => {});
+  }, []);
 
-.sc-desc { font-size: 11px; color: var(--t2); line-height: 1.4; padding-left: 25px; }
+  // Window-level drag — whole page is the drop target
+  useEffect(() => {
+    let depth = 0;
+
+    const onDragEnter = (e: DragEvent) => {
+      if (!e.dataTransfer?.types.includes("Files")) return;
+      depth++;
+      if (depth === 1) setIsDragging(true);
+    };
+
+    const onDragLeave = () => {
+      depth = Math.max(0, depth - 1);
+      if (depth === 0) setIsDragging(false);
+    };
+
+    const onDragOver = (e: DragEvent) => {
+      e.preventDefault();
+    };
+
+    const onDrop = async (e: DragEvent) => {
+      e.preventDefault();
+      depth = 0;
+      setIsDragging(false);
+
+      const files = Array.from(e.dataTransfer?.files ?? []).filter(
+        (f) => f.name.endsWith(".md") || f.name.endsWith(".txt"),
+      );
+      if (!files.length) return;
+
+      for (const file of files) {
+        const content = await file.text();
+        const frontmatter = parseFrontmatter(content);
+        const baseName = file.name.replace(/\.(md|txt)$/, "");
+        const name = frontmatter.name || baseName;
+        const description =
+          frontmatter.description || `Skill loaded from ${file.name}`;
+        const strategy = frontmatter.strategy || "auto";
+
+        try {
+          await fetch("/api/skills/register", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ name, description, content, strategy }),
+          });
+          setSkills((prev) => {
+            const filtered = prev.filter((s) => s.name !== name);
+            return [
+              ...filtered,
+              { name, description, strategy, source: "dropped" },
+            ];
+          });
+        } catch {
+          // silently ignore
+        }
+      }
+    };
+
+    window.addEventListener("dragenter", onDragEnter);
+    window.addEventListener("dragleave", onDragLeave);
+    window.addEventListener("dragover", onDragOver);
+    window.addEventListener("drop", onDrop);
+
+    return () => {
+      window.removeEventListener("dragenter", onDragEnter);
+      window.removeEventListener("dragleave", onDragLeave);
+      window.removeEventListener("dragover", onDragOver);
+      window.removeEventListener("drop", onDrop);
+    };
+  }, []);
 
-.sc-expanded {
-  max-height: 0; overflow: hidden;
-  transition: max-height 0.55s cubic-bezier(0.16,1,0.3,1);
-}
-.sc-expanded[data-open="true"] { max-height: 200px; }
+  return (
+    <aside className="skills-panel">
+      {isDragging && (
+        <div className="skills-drop-overlay">
+          <div className="skills-drop-overlay-inner">
+            <svg
+              width="26"
+              height="26"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M12 16v-8m0 0-3 3m3-3 3 3M6.5 19.5h11"
+              />
+            </svg>
+            <span>Add skill</span>
+          </div>
+        </div>
+      )}
 
-.sc-divider { height: 1px; background: color-mix(in srgb, var(--sc) 25%, transparent); margin: 10px 0 8px; }
-.sc-active-label {
-  font-size: 10px; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase;
-  color: var(--sc); margin-bottom: 7px; padding-left: 25px;
-}
+      {/* Header */}
+      <div className="skills-panel-heading">
+        <div className="skills-panel-eyebrow">
+          <span className="skills-panel-live-dot" />
+          Live Skills
+        </div>
+        <h1 className="skills-panel-title">Copilot Skills</h1>
+        <p className="skills-panel-subtitle">
+          {skills.length} skill{skills.length !== 1 ? "s" : ""} · loads
+          automatically when relevant
+        </p>
+      </div>
 
-.sc-caps  { list-style: none; display: flex; flex-direction: column; gap: 5px; }
-.sc-cap {
-  display: flex; align-items: center; gap: 7px;
-  font-size: 11px; color: var(--t2); padding-left: 25px;
-  opacity: 0; transform: translateX(-8px);
-  transition: opacity 0.3s ease, transform 0.3s ease;
-}
-.sc-cap[data-visible="true"] { opacity: 1; transform: translateX(0); }
-.sc-cap-dot {
-  width: 4px; height: 4px; border-radius: 50%; flex-shrink: 0;
-  background: var(--sc);
-}
+      <div className="skills-panel-hint">
+        Drop a <code>.md</code> or <code>.txt</code> anywhere to add a skill.
+      </div>
 
-/* ── Branching ── */
-.d-branch {
-  display: flex; align-items: center; justify-content: space-between; gap: 12px;
-}
-.d-branch__label { font-size: 12px; font-weight: 600; color: var(--t1); }
-.d-branch__desc  { font-size: 10px; color: var(--t3); margin-top: 2px; }
-.d-toggle {
-  width: 36px; height: 20px; border-radius: 10px; flex-shrink: 0; cursor: pointer;
-  background: var(--s3); border: 1px solid var(--bd2); position: relative;
-  transition: background 0.2s, border-color 0.2s;
-}
-.d-toggle::after {
-  content: ''; position: absolute; top: 2px; left: 2px;
-  width: 14px; height: 14px; border-radius: 50%; background: var(--t3);
-  transition: transform 0.2s, background 0.2s;
-}
-.d-toggle--on { background: rgba(129,140,248,.2); border-color: rgba(129,140,248,.4); }
-.d-toggle--on::after { transform: translateX(16px); background: var(--acc); }
-
-/* ── Demo prompts ── */
-.d-prompts { display: flex; flex-direction: column; gap: 6px; }
-.d-prompt {
-  text-align: left; background: var(--s2); border: 1px solid var(--bd);
-  border-radius: 8px; padding: 8px 10px;
-  font-size: 11px; font-family: var(--font); color: var(--t2);
-  cursor: pointer; line-height: 1.4;
-  transition: background 0.12s, border-color 0.12s, color 0.12s;
+      <div className="skills-list">
+        {skills.length === 0 ? (
+          <p className="skills-empty">No skills found.</p>
+        ) : (
+          skills.map((skill) => <SkillCard key={skill.name} skill={skill} />)
+        )}
+      </div>
+    </aside>
+  );
 }
-.d-prompt:hover { background: var(--s3); border-color: var(--bd2); color: var(--t1); }
 
-/* ── Chat ── */
-.d-chat { flex: 1; min-width: 0; display: flex; flex-direction: column; background: var(--bg); }
-.d-copilot { height: 100% !important; }
-`;
+// ─── App ──────────────────────────────────────────────────────────────────────
+
+export default function App() {
+  const [executingSkill, setExecutingSkill] = useState<string | null>(null);
+  const [loadedSkills, setLoadedSkills] = useState<Set<string>>(new Set());
+
+  const addLoadedSkill = useCallback((name: string) => {
+    setLoadedSkills((prev) => {
+      const next = new Set(prev);
+      next.add(name);
+      return next;
+    });
+  }, []);
+
+  return (
+    <SkillActivityContext.Provider
+      value={{
+        executingSkill,
+        loadedSkills,
+        setExecutingSkill,
+        addLoadedSkill,
+      }}
+    >
+      <div
+        data-vaul-drawer-wrapper
+        className="root data-[vaul-drawer-wrapper=true]:!rounded-[16px]"
+      >
+        <div className="app max-w-5xl mx-auto">
+          <SkillsPanel />
+          <main className="chat-panel">
+            <CopilotProvider
+              runtimeUrl="/api/chat"
+              initialMessages={INITIAL_MESSAGES}
+            >
+              <ChatInner />
+            </CopilotProvider>
+          </main>
+        </div>
+      </div>
+    </SkillActivityContext.Provider>
+  );
+}
diff --git a/examples/skills-demo/src/index.css b/examples/skills-demo/src/index.css
index f1d8c73..0835172 100644
--- a/examples/skills-demo/src/index.css
+++ b/examples/skills-demo/src/index.css
@@ -1 +1,753 @@
 @import "tailwindcss";
+@import "tw-animate-css";
+
+/* Include SDK package for Tailwind class detection */
+@source "../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+}
+
+/* ── Light theme — shadcn CSS variables ── */
+:root {
+  --radius: 0.75rem;
+  --background: #ffffff;
+  --foreground: #0d1117;
+  --card: #ffffff;
+  --card-foreground: #0d1117;
+  --popover: #ffffff;
+  --popover-foreground: #0d1117;
+  --primary: #0d9488;
+  --primary-foreground: #ffffff;
+  --secondary: #f0faf9;
+  --secondary-foreground: #0d1117;
+  --muted: #f4faf9;
+  --muted-foreground: #6b7280;
+  --accent: #e6faf7;
+  --accent-foreground: #0d1117;
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: rgba(0, 0, 0, 0.08);
+  --input: rgba(0, 0, 0, 0.06);
+  --ring: #0d9488;
+
+  /* ── App design tokens ── */
+  --app-font: "DM Sans", system-ui, sans-serif;
+  --app-mono: "DM Mono", monospace;
+  --app-teal: #0d9488;
+  --app-teal-light: #99f6e4;
+  --app-bg-top: #ffffff;
+  --app-bg-bottom: #dcfffe;
+}
+
+@layer base {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+  * {
+    @apply border-border outline-ring/50;
+  }
+  html,
+  body,
+  #root {
+    height: 100%;
+  }
+  body {
+    font-family: var(--app-font);
+    color: var(--foreground);
+    background: linear-gradient(160deg, var(--app-bg-top) 0%, var(--app-bg-bottom) 100%);
+    background-attachment: fixed;
+    min-height: 100vh;
+    -webkit-font-smoothing: antialiased;
+  }
+}
+
+/* ── TextShimmer ── */
+@keyframes shimmer-text {
+  from {
+    background-position: 200% center;
+  }
+  to {
+    background-position: -200% center;
+  }
+}
+.text-shimmer {
+  background: linear-gradient(to right, rgba(13, 148, 136, 0.5) 0%, rgba(13, 148, 136, 1) 30%, rgba(5, 200, 180, 1) 50%, rgba(13, 148, 136, 1) 70%, rgba(13, 148, 136, 0.5) 100%);
+  background-size: 200% auto;
+  background-clip: text;
+  -webkit-background-clip: text;
+  color: transparent;
+  animation: shimmer-text linear infinite;
+  font-weight: 500;
+  font-size: 0.75rem;
+}
+
+/* ── Layout — 50/50 split ── */
+
+.root {
+  background: linear-gradient(160deg, var(--app-bg-top) 0%, var(--app-bg-bottom) 100%);
+}
+
+.app {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  height: 100vh;
+  overflow: hidden;
+  /* Required for Vaul shouldScaleBackground — needs a background to show the scale transform */
+}
+
+.chat-panel {
+  height: 100%;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+}
+
+/* ── SDK overrides: transparent backgrounds ── */
+.chat-panel {
+  --background: transparent;
+  --card: transparent;
+  --muted: rgba(255, 255, 255, 0.72);
+  --border: rgba(0, 0, 0, 0.07);
+}
+
+/* CopilotChat must fill the chat panel so its internal scroll container is bounded */
+.chat-panel .copilot-fill {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+
+/* Header: transparent, no bottom border */
+.copilot-fill > div:first-child {
+  background: transparent !important;
+  border-bottom: none !important;
+}
+
+/* Messages area: pad bottom so content clears the fixed input */
+.copilot-fill > div:nth-child(2) {
+  padding-bottom: 110px !important;
+}
+
+/* Fade-out gradient above fixed input — only covers the right chat column */
+
+/* ── AI message bubble: subtle card style ── */
+.csdk-assistant-message .csdk-message-content {
+  background: rgba(255, 255, 255, 0.65);
+  border-radius: 0.875rem;
+  box-shadow:
+    0 1px 6px rgba(0, 0, 0, 0.06),
+    0 0 0 1px rgba(0, 0, 0, 0.04);
+  padding: 0.625rem 0.875rem !important;
+}
+
+/* ── Custom input (via renderInput prop) ── */
+.custom-input-fixed {
+  position: fixed;
+  bottom: 20px;
+  left: 75vw;
+  transform: translateX(-50%);
+  width: min(600px, calc(50vw - 48px));
+  z-index: 50;
+}
+
+.custom-prompt-input {
+  background: #ffffff;
+  border-radius: 1.25rem;
+  border: 1px solid rgba(0, 0, 0, 0.08);
+  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08);
+  padding: 0.5rem 0.5rem 0.5rem 1rem;
+  display: flex;
+  align-items: flex-end;
+  gap: 0.5rem;
+  cursor: text;
+}
+
+.custom-prompt-textarea {
+  flex: 1;
+  border: none !important;
+  outline: none !important;
+  box-shadow: none !important;
+  background: transparent !important;
+  resize: none;
+  font-family: var(--app-font);
+  font-size: 0.9rem;
+  color: var(--foreground);
+  line-height: 1.5;
+  padding: 0.35rem 0 !important;
+  max-height: 160px;
+}
+
+.custom-prompt-textarea::placeholder {
+  color: #9ca3af;
+}
+
+.custom-prompt-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  flex-shrink: 0;
+  padding-bottom: 0.1rem;
+}
+
+.custom-send-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  border-radius: 50%;
+  background: var(--app-teal);
+  color: #ffffff;
+  border: none;
+  cursor: pointer;
+  transition: background 0.15s ease;
+}
+
+.custom-send-btn:hover {
+  background: color-mix(in srgb, var(--app-teal) 80%, #000);
+}
+
+/* ── Skills Panel — transparent, gradient shows through ── */
+.skills-panel {
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  overflow-y: auto;
+  padding: 56px 52px;
+  scrollbar-width: thin;
+  scrollbar-color: rgba(0, 0, 0, 0.08) transparent;
+  /* No background — gradient bleeds through */
+}
+
+/* Webkit scrollbar for skills panel */
+.skills-panel::-webkit-scrollbar {
+  width: 4px;
+}
+.skills-panel::-webkit-scrollbar-track {
+  background: transparent;
+}
+.skills-panel::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.1);
+  border-radius: 4px;
+}
+
+.skills-panel-heading {
+  margin-bottom: 28px;
+}
+
+.skills-panel-eyebrow {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  color: var(--app-teal);
+  text-transform: uppercase;
+  margin-bottom: 20px;
+}
+
+@keyframes livePulse {
+  0%,
+  100% {
+    opacity: 1;
+    box-shadow: 0 0 0 0 rgba(13, 148, 136, 0.4);
+  }
+  50% {
+    opacity: 0.7;
+    box-shadow: 0 0 0 4px rgba(13, 148, 136, 0);
+  }
+}
+.skills-panel-live-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--app-teal);
+  animation: livePulse 2s ease-in-out infinite;
+  flex-shrink: 0;
+}
+
+.skills-panel-title {
+  font-size: clamp(1.75rem, 2.8vw, 2.6rem);
+  font-weight: 700;
+  color: var(--foreground);
+  line-height: 1.15;
+  letter-spacing: -0.03em;
+  margin: 0 0 12px;
+  text-wrap: balance;
+}
+
+.skills-panel-subtitle {
+  font-size: 0.875rem;
+  color: #9ca3af;
+  margin: 0 0 0;
+  font-weight: 400;
+  line-height: 1.5;
+}
+
+.skills-panel-hint {
+  font-size: 0.72rem;
+  color: #aab5c0;
+  margin-top: 14px;
+  margin-bottom: 20px;
+  line-height: 1.5;
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  flex-wrap: wrap;
+  max-width: 380px;
+}
+
+.skills-panel-hint::before {
+  content: "";
+  display: inline-block;
+  width: 14px;
+  height: 14px;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none'%3E%3Cpath d='M8 2v7M5.5 6 8 3l2.5 3M3 12.5h10' stroke='%2300b5a8' stroke-width='1.4' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-size: contain;
+  flex-shrink: 0;
+  opacity: 0.7;
+}
+
+.skills-panel-hint code {
+  font-family: var(--app-mono);
+  font-size: 0.7rem;
+  background: rgba(13, 148, 136, 0.07);
+  border-radius: 3px;
+  padding: 1px 4px;
+  color: var(--app-teal);
+}
+
+.skills-list {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  max-width: 380px;
+}
+
+.skills-empty {
+  font-size: 0.8125rem;
+  color: #9ca3af;
+  text-align: center;
+  padding: 24px 0;
+}
+
+/* ── Skill card ── */
+.skill-card {
+  background: rgba(255, 255, 255, 0.45);
+  border-radius: 12px;
+  border: 1px solid rgba(0, 0, 0, 0.05);
+  box-shadow: none;
+  padding: 13px 14px;
+  overflow: hidden;
+  transition:
+    box-shadow 0.18s ease,
+    border-color 0.2s ease,
+    background 0.2s ease,
+    transform 0.18s cubic-bezier(0.34, 1.56, 0.64, 1);
+  cursor: pointer;
+  will-change: transform;
+}
+
+/* Hover: same feel as active — opaque bg + lift */
+.skill-card:hover {
+  background: rgba(255, 255, 255, 0.88);
+  border-color: rgba(0, 0, 0, 0.07);
+  box-shadow:
+    0 2px 8px rgba(0, 0, 0, 0.05),
+    0 4px 16px rgba(0, 0, 0, 0.04);
+  transform: translateY(-1px);
+}
+
+/* Press: scale down — physics-active-state */
+.skill-card:active {
+  transform: scale(0.97);
+  box-shadow: none;
+  transition: transform 0.1s ease, box-shadow 0.1s ease;
+}
+
+/* Active/loaded state — white bg + same shadow as hover, colored border accent */
+.skill-card--active {
+  background: rgba(255, 255, 255, 0.88);
+  border-color: color-mix(in srgb, var(--skill-color) 22%, transparent);
+  box-shadow:
+    0 2px 8px rgba(0, 0, 0, 0.05),
+    0 4px 16px rgba(0, 0, 0, 0.04);
+}
+
+/* Executing: colored glow pulse */
+@keyframes skillPulse {
+  0%, 100% { box-shadow: 0 0 0 1px color-mix(in srgb, var(--skill-color) 14%, transparent), 0 2px 8px rgba(0,0,0,0.05); }
+  50%       { box-shadow: 0 0 0 1px color-mix(in srgb, var(--skill-color) 28%, transparent), 0 4px 20px color-mix(in srgb, var(--skill-color) 16%, transparent); }
+}
+.skill-card--executing {
+  animation: skillPulse 1.6s ease-in-out infinite;
+}
+
+/* Card layout: icon on left, content on right */
+.skill-card-body {
+  display: flex;
+  align-items: flex-start;
+  gap: 11px;
+}
+
+.skill-icon-wrap {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border-radius: 9px;
+  flex-shrink: 0;
+  transition:
+    background 0.22s ease,
+    color 0.22s ease;
+}
+
+.skill-card-content {
+  flex: 1;
+  min-width: 0;
+}
+
+.skill-card-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 6px;
+  margin-bottom: 5px;
+}
+
+.skill-card-title {
+  font-size: 13.5px;
+  font-weight: 600;
+  color: var(--foreground);
+  line-height: 1.3;
+  min-width: 0;
+  flex: 1;
+  transition: color 0.22s ease;
+}
+
+.skill-card-right {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  flex-shrink: 0;
+}
+
+/* Pulsing dot while executing */
+@keyframes dotPulse {
+  0%,
+  100% {
+    opacity: 1;
+    transform: scale(1);
+  }
+  50% {
+    opacity: 0.45;
+    transform: scale(0.75);
+  }
+}
+.skill-executing-dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  animation: dotPulse 1s ease-in-out infinite;
+  flex-shrink: 0;
+}
+
+/* "✓ Active" badge shown when loaded */
+.skill-loaded-badge {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.03em;
+  border-radius: 5px;
+  padding: 2px 6px;
+  border: 1px solid transparent;
+  white-space: nowrap;
+}
+
+.skill-badge {
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0.02em;
+  border-radius: 5px;
+  padding: 2px 6px;
+  white-space: nowrap;
+}
+
+.skill-badge--file {
+  background: rgba(0, 0, 0, 0.05);
+  border: 1px solid rgba(0, 0, 0, 0.07);
+  color: #9ca3af;
+}
+
+.skill-badge--dropped {
+  background: rgba(13, 148, 136, 0.08);
+  border: 1px solid rgba(13, 148, 136, 0.2);
+  color: var(--app-teal);
+}
+
+.skill-card-desc {
+  font-size: 11.5px;
+  color: #6b7280;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  line-height: 1.45;
+}
+
+/* "Loaded by Copilot" strip — slides in */
+@keyframes slideIn {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+    max-height: 0;
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    max-height: 40px;
+  }
+}
+.skill-loaded-section {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  margin-top: 10px;
+  padding-top: 9px;
+  border-top: 1px solid rgba(0, 0, 0, 0.06);
+  font-size: 10.5px;
+  font-weight: 500;
+  animation: slideIn 0.3s ease forwards;
+  overflow: hidden;
+}
+
+/* ── Drop overlay — frosted glass, no dashed border ── */
+@keyframes overlayFadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+/* Spring-like entrance: cubic-bezier overshoot — physics-spring-for-overshoot */
+@keyframes dropPillEnter {
+  from {
+    opacity: 0;
+    transform: translateY(14px) scale(0.93);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+.skills-drop-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  background: rgba(220, 253, 252, 0.28);
+  backdrop-filter: blur(5px) saturate(1.1);
+  -webkit-backdrop-filter: blur(5px) saturate(1.1);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 100;
+  pointer-events: none;
+  /* easing-entrance-ease-out */
+  animation: overlayFadeIn 0.18s ease-out forwards;
+}
+
+.skills-drop-overlay-inner {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  color: var(--app-teal);
+  font-size: 13.5px;
+  font-weight: 600;
+  /* White pill with layered shadow — visual-layered-shadows */
+  background: rgba(255, 255, 255, 0.9);
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
+  border-radius: 18px;
+  border: 1px solid rgba(255, 255, 255, 0.95);
+  padding: 22px 36px;
+  box-shadow:
+    0 8px 32px rgba(13, 148, 136, 0.14),
+    0 2px 8px rgba(0, 0, 0, 0.06),
+    0 0 0 0.5px rgba(13, 148, 136, 0.08);
+  /* Spring overshoot entrance — timing-under-300ms: 260ms */
+  animation: dropPillEnter 0.26s cubic-bezier(0.34, 1.56, 0.64, 1) forwards;
+}
+
+.skills-drop-overlay-inner svg {
+  opacity: 0.85;
+}
+
+.csdk-input {
+  background: white;
+}
+
+/* ── Skill Drawer (Vaul) ── */
+
+/* staging-dim-background: 40% overlay */
+.skill-drawer-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.32);
+  z-index: 200;
+}
+
+/* Bottom sheet — spring physics handled by Vaul internally */
+.skill-drawer-content {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  z-index: 201;
+  background: #ffffff;
+  border-radius: 20px 20px 0 0;
+  /* visual-layered-shadows */
+  box-shadow:
+    0 -1px 0 rgba(0, 0, 0, 0.06),
+    0 -8px 32px rgba(0, 0, 0, 0.1),
+    0 -2px 8px rgba(0, 0, 0, 0.05);
+  max-height: 82vh;
+  display: flex;
+  flex-direction: column;
+  outline: none;
+}
+
+/* Drag handle — visual-concentric-radius: inside 20px rounded corner */
+.skill-drawer-handle {
+  width: 40px;
+  height: 4px;
+  border-radius: 2px;
+  background: rgba(0, 0, 0, 0.12);
+  margin: 14px auto 0;
+  flex-shrink: 0;
+}
+
+/* Header row */
+.skill-drawer-header {
+  display: flex;
+  align-items: flex-start;
+  gap: 14px;
+  padding: 20px 24px 18px;
+  border-bottom: 1px solid;
+  flex-shrink: 0;
+}
+
+.skill-drawer-icon {
+  width: 42px;
+  height: 42px;
+  border-radius: 11px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.skill-drawer-header-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.skill-drawer-title {
+  font-size: 15px;
+  font-weight: 700;
+  line-height: 1.3;
+  letter-spacing: -0.02em;
+  margin: 0 0 4px;
+}
+
+.skill-drawer-subtitle {
+  font-size: 12px;
+  color: #6b7280;
+  line-height: 1.45;
+  margin: 0;
+}
+
+.skill-drawer-meta {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 5px;
+  flex-shrink: 0;
+}
+
+.skill-drawer-badge {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  border-radius: 5px;
+  padding: 3px 7px;
+  border: 1px solid;
+  white-space: nowrap;
+}
+
+.skill-drawer-version {
+  font-size: 10px;
+  color: #9ca3af;
+  font-family: var(--app-mono);
+}
+
+/* Scrollable body */
+.skill-drawer-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 20px 24px 36px;
+  scrollbar-width: thin;
+  scrollbar-color: rgba(0, 0, 0, 0.08) transparent;
+}
+
+.skill-drawer-loading {
+  font-size: 12px;
+  color: #9ca3af;
+}
+
+/* Plain text — type-text-wrap-pretty for body text */
+.skill-drawer-text {
+  font-family: var(--app-font);
+  font-size: 12px;
+  color: #374151;
+  line-height: 1.65;
+  white-space: pre-wrap;
+  word-break: break-word;
+  margin: 0;
+  text-wrap: pretty;
+}
diff --git a/examples/skills-demo/vite.config.ts b/examples/skills-demo/vite.config.ts
index f765d45..a4b9481 100644
--- a/examples/skills-demo/vite.config.ts
+++ b/examples/skills-demo/vite.config.ts
@@ -7,7 +7,10 @@ export default defineConfig({
   resolve: {
     alias: {
       "@": path.resolve(__dirname, "./src"),
+      react: path.resolve(__dirname, "./node_modules/react"),
+      "react-dom": path.resolve(__dirname, "./node_modules/react-dom"),
     },
+    dedupe: ["react", "react-dom"],
   },
   server: {
     port: 3033,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2eb1776..5d18830 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -44,7 +44,7 @@ importers:
         version: 16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6)
       fumadocs-mdx:
         specifier: ^14.1.1
-        version: 14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       fumadocs-ui:
         specifier: ^16.2.5
         version: 16.2.5(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(tailwindcss@4.1.18)(zod@4.3.6)
@@ -418,6 +418,73 @@ importers:
         specifier: ^5.6.0
         version: 5.9.3
 
+  examples/generative-ui-demo:
+    dependencies:
+      '@yourgpt/copilot-sdk':
+        specifier: workspace:*
+        version: link:../../packages/copilot-sdk
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+      lucide-react:
+        specifier: ^0.563.0
+        version: 0.563.0(react@19.2.3)
+      react:
+        specifier: ^19.0.0
+        version: 19.2.3
+      react-dom:
+        specifier: ^19.0.0
+        version: 19.2.3(react@19.2.3)
+      recharts:
+        specifier: ^2.13.0
+        version: 2.15.4(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+    devDependencies:
+      '@tailwindcss/postcss':
+        specifier: ^4
+        version: 4.1.18
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      '@types/node':
+        specifier: ^20
+        version: 20.19.27
+      '@types/react':
+        specifier: ^18.2.0
+        version: 18.3.27
+      '@types/react-dom':
+        specifier: ^18.2.0
+        version: 18.3.7(@types/react@18.3.27)
+      '@vitejs/plugin-react':
+        specifier: 6.0.1
+        version: 6.0.1(vite@8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+      concurrently:
+        specifier: ^9.0.0
+        version: 9.2.1
+      tailwindcss:
+        specifier: ^4
+        version: 4.2.1
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+      vite:
+        specifier: 8.0.3
+        version: 8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+
   examples/headless-slack-demo:
     dependencies:
       '@yourgpt/copilot-sdk':
@@ -468,7 +535,7 @@ importers:
         version: 18.3.7(@types/react@18.3.27)
       '@vitejs/plugin-react':
         specifier: ^4.3.4
-        version: 4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       concurrently:
         specifier: ^9.0.0
         version: 9.2.1
@@ -483,7 +550,7 @@ importers:
         version: 5.9.3
       vite:
         specifier: ^6.0.0
-        version: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+        version: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
 
   examples/mcp-demo:
     dependencies:
@@ -569,7 +636,7 @@ importers:
     devDependencies:
       '@tailwindcss/vite':
         specifier: ^4.0.0
-        version: 4.2.1(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 4.2.1(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       '@types/react':
         specifier: ^18.2.0
         version: 18.3.27
@@ -578,7 +645,7 @@ importers:
         version: 18.3.7(@types/react@18.3.27)
       '@vitejs/plugin-react':
         specifier: ^4.3.0
-        version: 4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
       tailwindcss:
         specifier: ^4.0.0
         version: 4.1.18
@@ -587,7 +654,7 @@ importers:
         version: 5.9.3
       vite:
         specifier: ^6.0.0
-        version: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+        version: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
 
   examples/ollama-demo/server:
     dependencies:
@@ -1026,6 +1093,79 @@ importers:
         specifier: ^5
         version: 5.9.3
 
+  examples/skills-demo:
+    dependencies:
+      '@yourgpt/copilot-sdk':
+        specifier: workspace:*
+        version: link:../../packages/copilot-sdk
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+      lucide-react:
+        specifier: ^0.563.0
+        version: 0.563.0(react@19.2.3)
+      react:
+        specifier: ^19.0.0
+        version: 19.2.3
+      react-dom:
+        specifier: ^19.0.0
+        version: 19.2.3(react@19.2.3)
+      vaul:
+        specifier: ^1.1.2
+        version: 1.1.2(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+    devDependencies:
+      '@tailwindcss/postcss':
+        specifier: ^4
+        version: 4.1.18
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      '@types/node':
+        specifier: ^20
+        version: 20.19.27
+      '@types/react':
+        specifier: ^18.2.0
+        version: 18.3.27
+      '@types/react-dom':
+        specifier: ^18.2.0
+        version: 18.3.7(@types/react@18.3.27)
+      '@vitejs/plugin-react':
+        specifier: 6.0.1
+        version: 6.0.1(vite@8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))
+      concurrently:
+        specifier: ^9.0.0
+        version: 9.2.1
+      path:
+        specifier: ^0.12.7
+        version: 0.12.7
+      tailwindcss:
+        specifier: ^4
+        version: 4.2.1
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      tw-animate-css:
+        specifier: ^1.4.0
+        version: 1.4.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+      vite:
+        specifier: 8.0.3
+        version: 8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+
   examples/support-tickets-demo:
     dependencies:
       '@radix-ui/react-slot':
@@ -1244,7 +1384,7 @@ importers:
         version: 18.3.1(react@18.3.1)
       tsup:
         specifier: ^8.0.2
-        version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       typescript:
         specifier: ^5.4.0
         version: 5.9.3
@@ -1269,7 +1409,7 @@ importers:
         version: 22.19.3
       tsup:
         specifier: ^8.3.5
-        version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       typescript:
         specifier: ^5.7.2
         version: 5.9.3
@@ -1278,7 +1418,7 @@ importers:
     devDependencies:
       tsup:
         specifier: ^8.0.2
-        version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       typescript:
         specifier: ^5.4.0
         version: 5.9.3
@@ -1306,7 +1446,7 @@ importers:
         version: 4.104.0(ws@8.18.0)(zod@3.25.76)
       tsup:
         specifier: ^8.0.2
-        version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       typescript:
         specifier: ^5.4.0
         version: 5.9.3
@@ -2555,6 +2695,12 @@ packages:
   '@napi-rs/wasm-runtime@0.2.12':
     resolution: {integrity: sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==}
 
+  '@napi-rs/wasm-runtime@1.1.2':
+    resolution: {integrity: sha512-sNXv5oLJ7ob93xkZ1XnxisYhGYXfaG9f65/ZgYuAu3qt7b3NadcOEhLvx28hv31PgX8SZJRYrAIPQilQmFpLVw==}
+    peerDependencies:
+      '@emnapi/core': ^1.7.1
+      '@emnapi/runtime': ^1.7.1
+
   '@next/env@16.0.10':
     resolution: {integrity: sha512-8tuaQkyDVgeONQ1MeT9Mkk8pQmZapMKFh5B+OrFUlG3rVmYTXcXlBetBgTurKXGaIZvkoqRT9JL5K3phXcgang==}
 
@@ -2758,6 +2904,9 @@ packages:
     resolution: {integrity: sha512-APwpZ+FTGMryo4QEeD6ti+Ei8suBkvxe8PeWdUcQHVfJDpjpt4c1dKojjNswcBmdeWSiiTYcnkKKH+yuo6727g==}
     engines: {node: '>= 20.0.0'}
 
+  '@oxc-project/types@0.122.0':
+    resolution: {integrity: sha512-oLAl5kBpV4w69UtFZ9xqcmTi+GENWOcPF7FCrczTiBbmC0ibXxCwyvZGbO39rCVEuLGAZM84DH0pUIyyv/YJzA==}
+
   '@parcel/watcher-android-arm64@2.5.1':
     resolution: {integrity: sha512-KF8+j9nNbUN8vzOFDpRMsaKBHZ/mcjEjMToVMJOhTozkDonQFFrRcfdLWn6yWKCmJKmdVxSgHiYvTCef4/qcBA==}
     engines: {node: '>= 10.0.0'}
@@ -3600,9 +3749,104 @@ packages:
   '@radix-ui/rect@1.1.1':
     resolution: {integrity: sha512-HPwpGIzkl28mWyZqG52jiqDJ12waP11Pa1lGoiyUkIEuMLBP0oeK/C89esbXrxsky5we7dfd8U58nm0SgAWpVw==}
 
+  '@rolldown/binding-android-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-pv1y2Fv0JybcykuiiD3qBOBdz6RteYojRFY1d+b95WVuzx211CRh+ytI/+9iVyWQ6koTh5dawe4S/yRfOFjgaA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@rolldown/binding-darwin-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-cFYr6zTG/3PXXF3pUO+umXxt1wkRK/0AYT8lDwuqvRC+LuKYWSAQAQZjCWDQpAH172ZV6ieYrNnFzVVcnSflAg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rolldown/binding-darwin-x64@1.0.0-rc.12':
+    resolution: {integrity: sha512-ZCsYknnHzeXYps0lGBz8JrF37GpE9bFVefrlmDrAQhOEi4IOIlcoU1+FwHEtyXGx2VkYAvhu7dyBf75EJQffBw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rolldown/binding-freebsd-x64@1.0.0-rc.12':
+    resolution: {integrity: sha512-dMLeprcVsyJsKolRXyoTH3NL6qtsT0Y2xeuEA8WQJquWFXkEC4bcu1rLZZSnZRMtAqwtrF/Ib9Ddtpa/Gkge9Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.12':
+    resolution: {integrity: sha512-YqWjAgGC/9M1lz3GR1r1rP79nMgo3mQiiA+Hfo+pvKFK1fAJ1bCi0ZQVh8noOqNacuY1qIcfyVfP6HoyBRZ85Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-/I5AS4cIroLpslsmzXfwbe5OmWvSsrFuEw3mwvbQ1kDxJ822hFHIx+vsN/TAzNVyepI/j/GSzrtCIwQPeKCLIg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.12':
+    resolution: {integrity: sha512-V6/wZztnBqlx5hJQqNWwFdxIKN0m38p8Jas+VoSfgH54HSj9tKTt1dZvG6JRHcjh6D7TvrJPWFGaY9UBVOaWPw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-AP3E9BpcUYliZCxa3w5Kwj9OtEVDYK6sVoUzy4vTOJsjPOgdaJZKFmN4oOlX0Wp0RPV2ETfmIra9x1xuayFB7g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-nWwpvUSPkoFmZo0kQazZYOrT7J5DGOJ/+QHHzjvNlooDZED8oH82Yg67HvehPPLAg5fUff7TfWFHQS8IV1n3og==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.12':
+    resolution: {integrity: sha512-RNrafz5bcwRy+O9e6P8Z/OCAJW/A+qtBczIqVYwTs14pf4iV1/+eKEjdOUta93q2TsT/FI0XYDP3TCky38LMAg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@rolldown/binding-linux-x64-musl@1.0.0-rc.12':
+    resolution: {integrity: sha512-Jpw/0iwoKWx3LJ2rc1yjFrj+T7iHZn2JDg1Yny1ma0luviFS4mhAIcd1LFNxK3EYu3DHWCps0ydXQ5i/rrJ2ig==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+
+  '@rolldown/binding-openharmony-arm64@1.0.0-rc.12':
+    resolution: {integrity: sha512-vRugONE4yMfVn0+7lUKdKvN4D5YusEiPilaoO2sgUWpCvrncvWgPMzK00ZFFJuiPgLwgFNP5eSiUlv2tfc+lpA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.12':
+    resolution: {integrity: sha512-ykGiLr/6kkiHc0XnBfmFJuCjr5ZYKKofkx+chJWDjitX+KsJuAmrzWhwyOMSHzPhzOHOy7u9HlFoa5MoAOJ/Zg==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.12':
+    resolution: {integrity: sha512-5eOND4duWkwx1AzCxadcOrNeighiLwMInEADT0YM7xeEOOFcovWZCq8dadXgcRHSf3Ulh1kFo/qvzoFiCLOL1Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.12':
+    resolution: {integrity: sha512-PyqoipaswDLAZtot351MLhrlrh6lcZPo2LSYE+VDxbVk24LVKAGOuE4hb8xZQmrPAuEtTZW8E6D2zc5EUZX4Lw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
   '@rolldown/pluginutils@1.0.0-beta.27':
     resolution: {integrity: sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==}
 
+  '@rolldown/pluginutils@1.0.0-rc.12':
+    resolution: {integrity: sha512-HHMwmarRKvoFsJorqYlFeFRzXZqCt2ETQlEDOb9aqssrnVBB1/+xgTGtuTrIk5vzLNX1MjMtTf7W9z3tsSbrxw==}
+
+  '@rolldown/pluginutils@1.0.0-rc.7':
+    resolution: {integrity: sha512-qujRfC8sFVInYSPPMLQByRh7zhwkGFS4+tyMQ83srV1qrxL4g8E2tyxVVyxd0+8QeBM1mIk9KbWxkegRr76XzA==}
+
   '@rollup/rollup-android-arm-eabi@4.53.3':
     resolution: {integrity: sha512-mRSi+4cBjrRLoaal2PnqH82Wqyb+d3HsPUN/W+WslCXsZsyHa9ZeQQX/pQsZaVIWDkPcpV6jJ+3KLbTbgnwv8w==}
     cpu: [arm]
@@ -4263,6 +4507,19 @@ packages:
     peerDependencies:
       vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
 
+  '@vitejs/plugin-react@6.0.1':
+    resolution: {integrity: sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      '@rolldown/plugin-babel': ^0.1.7 || ^0.2.0
+      babel-plugin-react-compiler: ^1.0.0
+      vite: ^8.0.0
+    peerDependenciesMeta:
+      '@rolldown/plugin-babel':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+
   abort-controller@3.0.0:
     resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
     engines: {node: '>=6.5'}
@@ -4926,10 +5183,6 @@ packages:
     resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
     engines: {node: '>= 0.8'}
 
-  enhanced-resolve@5.18.4:
-    resolution: {integrity: sha512-LgQMM4WXU3QI+SYgEc2liRgznaD5ojbmY3sb8LxyguVkIg5FxdpTkvk72te2R38/TGKxH634oLxXRGY6d7AP+Q==}
-    engines: {node: '>=10.13.0'}
-
   enhanced-resolve@5.19.0:
     resolution: {integrity: sha512-phv3E1Xl4tQOShqSte26C7Fl84EwUdZsyOuSSk9qtAGyyQs2s3jJzComh+Abf4g187lUUAvH+H26omrqia2aGg==}
     engines: {node: '>=10.13.0'}
@@ -5699,6 +5952,9 @@ packages:
     resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
     engines: {node: '>=0.8.19'}
 
+  inherits@2.0.3:
+    resolution: {integrity: sha512-x00IRNXNy63jwGkJmzPigoySHbaqpNuzKbBOmzK+g2OdZpQ9w+sxCN+VSB3ja7IAge2OP2qpfxTjeNcyjmW1uw==}
+
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
@@ -6026,6 +6282,12 @@ packages:
     cpu: [arm64]
     os: [android]
 
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
   lightningcss-darwin-arm64@1.30.2:
     resolution: {integrity: sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==}
     engines: {node: '>= 12.0.0'}
@@ -6038,6 +6300,12 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
   lightningcss-darwin-x64@1.30.2:
     resolution: {integrity: sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==}
     engines: {node: '>= 12.0.0'}
@@ -6050,6 +6318,12 @@ packages:
     cpu: [x64]
     os: [darwin]
 
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
   lightningcss-freebsd-x64@1.30.2:
     resolution: {integrity: sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==}
     engines: {node: '>= 12.0.0'}
@@ -6062,6 +6336,12 @@ packages:
     cpu: [x64]
     os: [freebsd]
 
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
   lightningcss-linux-arm-gnueabihf@1.30.2:
     resolution: {integrity: sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==}
     engines: {node: '>= 12.0.0'}
@@ -6074,6 +6354,12 @@ packages:
     cpu: [arm]
     os: [linux]
 
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
   lightningcss-linux-arm64-gnu@1.30.2:
     resolution: {integrity: sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==}
     engines: {node: '>= 12.0.0'}
@@ -6086,6 +6372,12 @@ packages:
     cpu: [arm64]
     os: [linux]
 
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
   lightningcss-linux-arm64-musl@1.30.2:
     resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==}
     engines: {node: '>= 12.0.0'}
@@ -6098,6 +6390,12 @@ packages:
     cpu: [arm64]
     os: [linux]
 
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
   lightningcss-linux-x64-gnu@1.30.2:
     resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==}
     engines: {node: '>= 12.0.0'}
@@ -6110,6 +6408,12 @@ packages:
     cpu: [x64]
     os: [linux]
 
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
   lightningcss-linux-x64-musl@1.30.2:
     resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==}
     engines: {node: '>= 12.0.0'}
@@ -6122,6 +6426,12 @@ packages:
     cpu: [x64]
     os: [linux]
 
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
   lightningcss-win32-arm64-msvc@1.30.2:
     resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==}
     engines: {node: '>= 12.0.0'}
@@ -6134,6 +6444,12 @@ packages:
     cpu: [arm64]
     os: [win32]
 
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
   lightningcss-win32-x64-msvc@1.30.2:
     resolution: {integrity: sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==}
     engines: {node: '>= 12.0.0'}
@@ -6146,6 +6462,12 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
   lightningcss@1.30.2:
     resolution: {integrity: sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==}
     engines: {node: '>= 12.0.0'}
@@ -6154,6 +6476,10 @@ packages:
     resolution: {integrity: sha512-l51N2r93WmGUye3WuFoN5k10zyvrVs0qfKBhyC5ogUQ6Ew6JUSswh78mbSO+IU3nTWsyOArqPCcShdQSadghBQ==}
     engines: {node: '>= 12.0.0'}
 
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
   lilconfig@3.1.3:
     resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==}
     engines: {node: '>=14'}
@@ -6839,6 +7165,9 @@ packages:
     resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
     engines: {node: '>=8'}
 
+  path@0.12.7:
+    resolution: {integrity: sha512-aXXC6s+1w7otVF9UletFkFcDsJeO7lSZBPUQhtb5O0xJe8LtYhj/GxldoL09bBj9+ZmE2hNoHqQSFMN5fikh4Q==}
+
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
 
@@ -6853,6 +7182,10 @@ packages:
     resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
     engines: {node: '>=12'}
 
+  picomatch@4.0.4:
+    resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
+    engines: {node: '>=12'}
+
   pidtree@0.6.0:
     resolution: {integrity: sha512-eG2dWTVw5bzqGRztnHExczNxt5VGsE6OwTeCG3fdUf9KBsZzO3R5OIIIzWR+iZA0NtZ+RDVdaoE2dK1cn6jH4g==}
     engines: {node: '>=0.10'}
@@ -6911,6 +7244,10 @@ packages:
     resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
     engines: {node: ^10 || ^12 || >=14}
 
+  postcss@8.5.8:
+    resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==}
+    engines: {node: ^10 || ^12 || >=14}
+
   powershell-utils@0.1.0:
     resolution: {integrity: sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A==}
     engines: {node: '>=20'}
@@ -6936,6 +7273,10 @@ packages:
   printable-characters@1.0.42:
     resolution: {integrity: sha512-dKp+C4iXWK4vVYZmYSd0KBH5F/h1HoZRsbJ82AVKRO3PEo8L4lBS/vLwhVtpwwuYcoIsVY+1JYKR268yn480uQ==}
 
+  process@0.11.10:
+    resolution: {integrity: sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==}
+    engines: {node: '>= 0.6.0'}
+
   prompts@2.4.2:
     resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
     engines: {node: '>= 6'}
@@ -7232,6 +7573,11 @@ packages:
   rfdc@1.4.1:
     resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
 
+  rolldown@1.0.0-rc.12:
+    resolution: {integrity: sha512-yP4USLIMYrwpPHEFB5JGH1uxhcslv6/hL0OyvTuY+3qlOSJvZ7ntYnoWpehBxufkgN0cvXxppuTu5hHa/zPh+A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
   rollup-plugin-inject@3.0.2:
     resolution: {integrity: sha512-ptg9PQwzs3orn4jkgXJ74bfs5vYz1NCZlSQMBUA0wKcGp5i5pA1AO3fOUEte8enhGUC+iapTCzEWw2jEFFUO/w==}
     deprecated: This package has been deprecated and is no longer maintained. Please use @rollup/plugin-inject.
@@ -7888,6 +8234,9 @@ packages:
   util-deprecate@1.0.2:
     resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
 
+  util@0.10.4:
+    resolution: {integrity: sha512-0Pm9hTQ3se5ll1XihRic3FDIku70C+iHUdT/W926rSgHV5QgXsYbKZN8MSC3tJtSkhuROzvsQjAaFENRXr+19A==}
+
   utils-merge@1.0.1:
     resolution: {integrity: sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==}
     engines: {node: '>= 0.4.0'}
@@ -7903,6 +8252,12 @@ packages:
     resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
     engines: {node: '>= 0.8'}
 
+  vaul@1.1.2:
+    resolution: {integrity: sha512-ZFkClGpWyI2WUQjdLJ/BaGuV6AVQiJ3uELGk3OYtP+B6yCO7Cmn9vPFXVJkRaGkOJu3m8bQMgtyzNHixULceQA==}
+    peerDependencies:
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+
   vfile-location@5.0.3:
     resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
 
@@ -7955,6 +8310,49 @@ packages:
       yaml:
         optional: true
 
+  vite@8.0.3:
+    resolution: {integrity: sha512-B9ifbFudT1TFhfltfaIPgjo9Z3mDynBTJSUYxTjOQruf/zHH+ezCQKcoqO+h7a9Pw9Nm/OtlXAiGT1axBgwqrQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      '@vitejs/devtools': ^0.1.0
+      esbuild: ^0.27.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      '@vitejs/devtools':
+        optional: true
+      esbuild:
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
   web-namespaces@2.0.1:
     resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
 
@@ -9310,6 +9708,13 @@ snapshots:
       '@tybys/wasm-util': 0.10.1
     optional: true
 
+  '@napi-rs/wasm-runtime@1.1.2(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)':
+    dependencies:
+      '@emnapi/core': 1.7.1
+      '@emnapi/runtime': 1.7.1
+      '@tybys/wasm-util': 0.10.1
+    optional: true
+
   '@next/env@16.0.10': {}
 
   '@next/env@16.1.1': {}
@@ -9433,6 +9838,8 @@ snapshots:
 
   '@orama/orama@3.1.17': {}
 
+  '@oxc-project/types@0.122.0': {}
+
   '@parcel/watcher-android-arm64@2.5.1':
     optional: true
 
@@ -10875,8 +11282,62 @@ snapshots:
 
   '@radix-ui/rect@1.1.1': {}
 
+  '@rolldown/binding-android-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-darwin-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-darwin-x64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-freebsd-x64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-linux-x64-musl@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-openharmony-arm64@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-wasm32-wasi@1.0.0-rc.12(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)':
+    dependencies:
+      '@napi-rs/wasm-runtime': 1.1.2(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+    optional: true
+
+  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.12':
+    optional: true
+
+  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.12':
+    optional: true
+
   '@rolldown/pluginutils@1.0.0-beta.27': {}
 
+  '@rolldown/pluginutils@1.0.0-rc.12': {}
+
+  '@rolldown/pluginutils@1.0.0-rc.7': {}
+
   '@rollup/rollup-android-arm-eabi@4.53.3':
     optional: true
 
@@ -11012,7 +11473,7 @@ snapshots:
   '@tailwindcss/node@4.1.18':
     dependencies:
       '@jridgewell/remapping': 2.3.5
-      enhanced-resolve: 5.18.4
+      enhanced-resolve: 5.19.0
       jiti: 2.6.1
       lightningcss: 1.30.2
       magic-string: 0.30.21
@@ -11144,12 +11605,12 @@ snapshots:
       postcss-selector-parser: 6.0.10
       tailwindcss: 4.1.18
 
-  '@tailwindcss/vite@4.2.1(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@tailwindcss/vite@4.2.1(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@tailwindcss/node': 4.2.1
       '@tailwindcss/oxide': 4.2.1
       tailwindcss: 4.2.1
-      vite: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
 
   '@ts-morph/common@0.27.0':
     dependencies:
@@ -11481,7 +11942,7 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
     optional: true
 
-  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@babel/core': 7.28.5
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.5)
@@ -11489,11 +11950,11 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
-  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@babel/core': 7.28.5
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.5)
@@ -11501,10 +11962,15 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
+  '@vitejs/plugin-react@6.0.1(vite@8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2))':
+    dependencies:
+      '@rolldown/pluginutils': 1.0.0-rc.7
+      vite: 8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+
   abort-controller@3.0.0:
     dependencies:
       event-target-shim: 5.0.1
@@ -12121,11 +12587,6 @@ snapshots:
 
   encodeurl@2.0.0: {}
 
-  enhanced-resolve@5.18.4:
-    dependencies:
-      graceful-fs: 4.2.11
-      tapable: 2.3.0
-
   enhanced-resolve@5.19.0:
     dependencies:
       graceful-fs: 4.2.11
@@ -12357,7 +12818,7 @@ snapshots:
       '@next/eslint-plugin-next': 16.0.10
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
@@ -12378,7 +12839,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12398,7 +12859,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12420,7 +12881,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -12431,11 +12892,11 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1)):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -12446,18 +12907,18 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
-  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
+  eslint-module-utils@2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       debug: 3.2.7
     optionalDependencies:
       '@typescript-eslint/parser': 8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0)(eslint@9.39.2(jiti@2.6.1))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -12482,7 +12943,7 @@ snapshots:
       doctrine: 2.1.0
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
-      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
+      eslint-module-utils: 2.12.1(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
       hasown: 2.0.2
       is-core-module: 2.16.1
       is-glob: 4.0.3
@@ -12500,7 +12961,7 @@ snapshots:
       - eslint-import-resolver-webpack
       - supports-color
 
-  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -12844,6 +13305,10 @@ snapshots:
     optionalDependencies:
       picomatch: 4.0.3
 
+  fdir@6.5.0(picomatch@4.0.4):
+    optionalDependencies:
+      picomatch: 4.0.4
+
   fetch-blob@3.2.0:
     dependencies:
       node-domexception: 1.0.0
@@ -12988,7 +13453,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  fumadocs-mdx@14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)):
+  fumadocs-mdx@14.1.1(fumadocs-core@16.2.5(@types/react@18.3.27)(lucide-react@0.562.0(react@19.2.1))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react-dom@19.2.1(react@19.2.1))(react-router@7.13.1(react-dom@19.2.1(react@19.2.1))(react@19.2.1))(react@19.2.1)(zod@4.3.6))(next@16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0))(react@19.2.1)(vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       '@mdx-js/mdx': 3.1.1
       '@standard-schema/spec': 1.1.0
@@ -13011,7 +13476,7 @@ snapshots:
     optionalDependencies:
       next: 16.0.10(react-dom@19.2.1(react@19.2.1))(react@19.2.1)(sass@1.97.0)
       react: 19.2.1
-      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
@@ -13370,6 +13835,8 @@ snapshots:
 
   imurmurhash@0.1.4: {}
 
+  inherits@2.0.3: {}
+
   inherits@2.0.4: {}
 
   inline-style-parser@0.2.7: {}
@@ -13655,66 +14122,99 @@ snapshots:
   lightningcss-android-arm64@1.31.1:
     optional: true
 
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
   lightningcss-darwin-arm64@1.30.2:
     optional: true
 
   lightningcss-darwin-arm64@1.31.1:
     optional: true
 
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
   lightningcss-darwin-x64@1.30.2:
     optional: true
 
   lightningcss-darwin-x64@1.31.1:
     optional: true
 
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
   lightningcss-freebsd-x64@1.30.2:
     optional: true
 
   lightningcss-freebsd-x64@1.31.1:
     optional: true
 
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
   lightningcss-linux-arm-gnueabihf@1.30.2:
     optional: true
 
   lightningcss-linux-arm-gnueabihf@1.31.1:
     optional: true
 
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
   lightningcss-linux-arm64-gnu@1.30.2:
     optional: true
 
   lightningcss-linux-arm64-gnu@1.31.1:
     optional: true
 
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
   lightningcss-linux-arm64-musl@1.30.2:
     optional: true
 
   lightningcss-linux-arm64-musl@1.31.1:
     optional: true
 
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
   lightningcss-linux-x64-gnu@1.30.2:
     optional: true
 
   lightningcss-linux-x64-gnu@1.31.1:
     optional: true
 
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
   lightningcss-linux-x64-musl@1.30.2:
     optional: true
 
   lightningcss-linux-x64-musl@1.31.1:
     optional: true
 
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
   lightningcss-win32-arm64-msvc@1.30.2:
     optional: true
 
   lightningcss-win32-arm64-msvc@1.31.1:
     optional: true
 
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
   lightningcss-win32-x64-msvc@1.30.2:
     optional: true
 
   lightningcss-win32-x64-msvc@1.31.1:
     optional: true
 
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
   lightningcss@1.30.2:
     dependencies:
       detect-libc: 2.1.2
@@ -13747,6 +14247,22 @@ snapshots:
       lightningcss-win32-arm64-msvc: 1.31.1
       lightningcss-win32-x64-msvc: 1.31.1
 
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
   lilconfig@3.1.3: {}
 
   lines-and-columns@1.2.4: {}
@@ -14722,6 +15238,11 @@ snapshots:
 
   path-type@4.0.0: {}
 
+  path@0.12.7:
+    dependencies:
+      process: 0.11.10
+      util: 0.10.4
+
   pathe@2.0.3: {}
 
   picocolors@1.1.1: {}
@@ -14730,6 +15251,8 @@ snapshots:
 
   picomatch@4.0.3: {}
 
+  picomatch@4.0.4: {}
+
   pidtree@0.6.0: {}
 
   pify@4.0.1: {}
@@ -14746,12 +15269,12 @@ snapshots:
 
   possible-typed-array-names@1.1.0: {}
 
-  postcss-load-config@6.0.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.8.2):
+  postcss-load-config@6.0.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       lilconfig: 3.1.3
     optionalDependencies:
       jiti: 2.6.1
-      postcss: 8.5.6
+      postcss: 8.5.8
       tsx: 4.21.0
       yaml: 2.8.2
 
@@ -14777,6 +15300,12 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  postcss@8.5.8:
+    dependencies:
+      nanoid: 3.3.11
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
   powershell-utils@0.1.0: {}
 
   prelude-ls@1.2.1: {}
@@ -14791,6 +15320,8 @@ snapshots:
 
   printable-characters@1.0.42: {}
 
+  process@0.11.10: {}
+
   prompts@2.4.2:
     dependencies:
       kleur: 3.0.3
@@ -15236,6 +15767,30 @@ snapshots:
 
   rfdc@1.4.1: {}
 
+  rolldown@1.0.0-rc.12(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1):
+    dependencies:
+      '@oxc-project/types': 0.122.0
+      '@rolldown/pluginutils': 1.0.0-rc.12
+    optionalDependencies:
+      '@rolldown/binding-android-arm64': 1.0.0-rc.12
+      '@rolldown/binding-darwin-arm64': 1.0.0-rc.12
+      '@rolldown/binding-darwin-x64': 1.0.0-rc.12
+      '@rolldown/binding-freebsd-x64': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm-gnueabihf': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-arm64-musl': 1.0.0-rc.12
+      '@rolldown/binding-linux-ppc64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-s390x-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-x64-gnu': 1.0.0-rc.12
+      '@rolldown/binding-linux-x64-musl': 1.0.0-rc.12
+      '@rolldown/binding-openharmony-arm64': 1.0.0-rc.12
+      '@rolldown/binding-wasm32-wasi': 1.0.0-rc.12(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)
+      '@rolldown/binding-win32-arm64-msvc': 1.0.0-rc.12
+      '@rolldown/binding-win32-x64-msvc': 1.0.0-rc.12
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+
   rollup-plugin-inject@3.0.2:
     dependencies:
       estree-walker: 0.6.1
@@ -15824,8 +16379,8 @@ snapshots:
 
   tinyglobby@0.2.15:
     dependencies:
-      fdir: 6.5.0(picomatch@4.0.3)
-      picomatch: 4.0.3
+      fdir: 6.5.0(picomatch@4.0.4)
+      picomatch: 4.0.4
 
   tldts-core@7.0.19: {}
 
@@ -15879,7 +16434,7 @@ snapshots:
 
   tslib@2.8.1: {}
 
-  tsup@8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2):
+  tsup@8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2):
     dependencies:
       bundle-require: 5.1.0(esbuild@0.27.1)
       cac: 6.7.14
@@ -15890,7 +16445,7 @@ snapshots:
       fix-dts-default-cjs-exports: 1.0.1
       joycon: 3.1.1
       picocolors: 1.1.1
-      postcss-load-config: 6.0.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.8.2)
+      postcss-load-config: 6.0.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(yaml@2.8.2)
       resolve-from: 5.0.0
       rollup: 4.53.3
       source-map: 0.7.6
@@ -15899,7 +16454,7 @@ snapshots:
       tinyglobby: 0.2.15
       tree-kill: 1.2.2
     optionalDependencies:
-      postcss: 8.5.6
+      postcss: 8.5.8
       typescript: 5.9.3
     transitivePeerDependencies:
       - jiti
@@ -16163,6 +16718,10 @@ snapshots:
 
   util-deprecate@1.0.2: {}
 
+  util@0.10.4:
+    dependencies:
+      inherits: 2.0.3
+
   utils-merge@1.0.1: {}
 
   utrie@1.0.2:
@@ -16173,6 +16732,15 @@ snapshots:
 
   vary@1.1.2: {}
 
+  vaul@1.1.2(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3):
+    dependencies:
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
+
   vfile-location@5.0.3:
     dependencies:
       '@types/unist': 3.0.3
@@ -16205,7 +16773,7 @@ snapshots:
       d3-time: 3.1.0
       d3-timer: 3.0.1
 
-  vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
+  vite@6.4.1(@types/node@20.19.27)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       esbuild: 0.25.12
       fdir: 6.5.0(picomatch@4.0.3)
@@ -16217,12 +16785,12 @@ snapshots:
       '@types/node': 20.19.27
       fsevents: 2.3.3
       jiti: 2.6.1
-      lightningcss: 1.31.1
+      lightningcss: 1.32.0
       sass: 1.97.0
       tsx: 4.21.0
       yaml: 2.8.2
 
-  vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.31.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
+  vite@6.4.1(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.32.0)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       esbuild: 0.25.12
       fdir: 6.5.0(picomatch@4.0.3)
@@ -16234,10 +16802,29 @@ snapshots:
       '@types/node': 22.19.3
       fsevents: 2.3.3
       jiti: 2.6.1
-      lightningcss: 1.31.1
+      lightningcss: 1.32.0
+      sass: 1.97.0
+      tsx: 4.21.0
+      yaml: 2.8.2
+
+  vite@8.0.3(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)(@types/node@20.19.27)(esbuild@0.27.1)(jiti@2.6.1)(sass@1.97.0)(tsx@4.21.0)(yaml@2.8.2):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.4
+      postcss: 8.5.8
+      rolldown: 1.0.0-rc.12(@emnapi/core@1.7.1)(@emnapi/runtime@1.7.1)
+      tinyglobby: 0.2.15
+    optionalDependencies:
+      '@types/node': 20.19.27
+      esbuild: 0.27.1
+      fsevents: 2.3.3
+      jiti: 2.6.1
       sass: 1.97.0
       tsx: 4.21.0
       yaml: 2.8.2
+    transitivePeerDependencies:
+      - '@emnapi/core'
+      - '@emnapi/runtime'
 
   web-namespaces@2.0.1: {}
 

From b324ba52cf43e7e92694d300a152d88d74250931 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Sun, 29 Mar 2026 19:21:19 +0530
Subject: [PATCH 71/72] chore: update pnpm-lock.yaml with new dependencies and
 versions

- Added 'vaul' version 1.1.2 and 'tw-animate-css' version 1.4.0 to dependencies.
- Updated 'yourgpt-server-demo' with new dependencies including 'cors', 'dotenv', 'express', and 'ws'.
- Updated devDependencies for 'yourgpt-server-demo' with '@types/cors', '@types/express', '@types/ws', 'tsx', and 'typescript'.
- Updated integrity checks for '@types/ws' and 'vaul' in the lockfile.
---
 pnpm-lock.yaml | 70 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 66 insertions(+), 4 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bd7fad4..f5c0b7c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1153,6 +1153,9 @@ importers:
       react-dom:
         specifier: ^19.0.0
         version: 19.2.3(react@19.2.3)
+      vaul:
+        specifier: ^1.1.2
+        version: 1.1.2(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
     devDependencies:
       '@tailwindcss/postcss':
         specifier: ^4
@@ -1187,6 +1190,9 @@ importers:
       tsx:
         specifier: ^4.19.0
         version: 4.21.0
+      tw-animate-css:
+        specifier: ^1.4.0
+        version: 1.4.0
       typescript:
         specifier: ^5.6.0
         version: 5.9.3
@@ -1310,6 +1316,40 @@ importers:
         specifier: ^5
         version: 5.9.3
 
+  examples/yourgpt-server-demo:
+    dependencies:
+      '@yourgpt/llm-sdk':
+        specifier: workspace:*
+        version: link:../../packages/llm-sdk
+      cors:
+        specifier: ^2.8.5
+        version: 2.8.6
+      dotenv:
+        specifier: ^16.4.0
+        version: 16.6.1
+      express:
+        specifier: ^4.21.0
+        version: 4.22.1
+      ws:
+        specifier: ^8.18.0
+        version: 8.18.0
+    devDependencies:
+      '@types/cors':
+        specifier: ^2.8.17
+        version: 2.8.19
+      '@types/express':
+        specifier: ^5.0.0
+        version: 5.0.6
+      '@types/ws':
+        specifier: ^8.5.13
+        version: 8.18.1
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+
   packages/copilot-sdk:
     dependencies:
       '@base-ui/react':
@@ -4335,6 +4375,9 @@ packages:
   '@types/validate-npm-package-name@4.0.2':
     resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
 
+  '@types/ws@8.18.1':
+    resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
+
   '@typescript-eslint/eslint-plugin@8.50.0':
     resolution: {integrity: sha512-O7QnmOXYKVtPrfYzMolrCTfkezCJS9+ljLdKW/+DCvRsc3UAz+sbH6Xcsv7p30+0OwUbeWfUDAQE0vpabZ3QLg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -8274,6 +8317,12 @@ packages:
     resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
     engines: {node: '>= 0.8'}
 
+  vaul@1.1.2:
+    resolution: {integrity: sha512-ZFkClGpWyI2WUQjdLJ/BaGuV6AVQiJ3uELGk3OYtP+B6yCO7Cmn9vPFXVJkRaGkOJu3m8bQMgtyzNHixULceQA==}
+    peerDependencies:
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+
   vfile-location@5.0.3:
     resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
 
@@ -11832,6 +11881,10 @@ snapshots:
 
   '@types/validate-npm-package-name@4.0.2': {}
 
+  '@types/ws@8.18.1':
+    dependencies:
+      '@types/node': 20.19.27
+
   '@typescript-eslint/eslint-plugin@8.50.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@eslint-community/regexpp': 4.12.2
@@ -12920,7 +12973,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12940,7 +12993,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -12973,7 +13026,7 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -13042,7 +13095,7 @@ snapshots:
       - eslint-import-resolver-webpack
       - supports-color
 
-  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -16837,6 +16890,15 @@ snapshots:
 
   vary@1.1.2: {}
 
+  vaul@1.1.2(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3):
+    dependencies:
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@18.3.7(@types/react@18.3.27))(@types/react@18.3.27)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
+
   vfile-location@5.0.3:
     dependencies:
       '@types/unist': 3.0.3

From fea0899d703391cffdf1f497dbb3c17e4e0c8047 Mon Sep 17 00:00:00 2001
From: Sahil <sk950121@gmail.com>
Date: Mon, 30 Mar 2026 15:06:29 +0530
Subject: [PATCH 72/72] chore: remove tool-search-implementation.md file

- Deleted the comprehensive documentation for the tool management branch, which included details on features, configurations, and known issues related to the tool management stack across copilot-sdk and llm-sdk.
---
 tool-search-implementation.md | 253 ----------------------------------
 1 file changed, 253 deletions(-)
 delete mode 100644 tool-search-implementation.md

diff --git a/tool-search-implementation.md b/tool-search-implementation.md
deleted file mode 100644
index 2dd6941..0000000
--- a/tool-search-implementation.md
+++ /dev/null
@@ -1,253 +0,0 @@
-# Tool Management Branch Summary
-
-Branch: `codex/tool-management-core`
-
-## Scope
-
-This branch adds the first full tool-management stack across `copilot-sdk`, `llm-sdk`, and the experimental demos.
-
-It covers:
-
-- tool profiles and selective loading
-- deferred tool loading
-- manual tool search fallback
-- native provider tool search hooks for Anthropic and OpenAI
-- prompt-side tool result truncation and context compaction groundwork
-- mixed client/server tool catalog support
-- provider payload debug logging
-- experimental scale-testing demo with 100 tools
-
-## Main Features Added
-
-### 1. Framework-agnostic prompt/tool optimization (`copilot-sdk`)
-
-Added shared optimization support in the chat/core layer:
-
-- tool profile selection
-- dynamic tool narrowing
-- tool result truncation controls
-- context budget reporting
-- history compaction with continuity summaries
-
-Public APIs added:
-
-- `setOptimizationConfig(...)`
-- `setToolProfile(...)`
-- `getContextUsage()`
-
-Main files:
-
-- `packages/copilot-sdk/src/chat/optimizations.ts`
-- `packages/copilot-sdk/src/chat/ChatWithTools.ts`
-- `packages/copilot-sdk/src/chat/classes/AbstractChat.ts`
-- `packages/copilot-sdk/src/core/types/tools.ts`
-
-### 2. Tool metadata and selection pipeline (`llm-sdk`)
-
-Added richer tool metadata and request-time selection:
-
-- `category`
-- `group`
-- `profiles`
-- `searchKeywords`
-- `deferLoading`
-
-Selection features:
-
-- profile-based filtering
-- include/exclude selectors
-- dynamic ranking by recent query/context
-- strict deferred loading mode
-- request-level `toolProfile`
-
-Main files:
-
-- `packages/llm-sdk/src/core/stream-events.ts`
-- `packages/llm-sdk/src/server/tool-selection.ts`
-- `packages/llm-sdk/src/server/runtime.ts`
-- `packages/llm-sdk/src/server/agent-loop.ts`
-
-### 3. Manual deferred tool search fallback
-
-Added SDK-managed `search_tools` fallback for providers/models without native search support.
-
-Behavior:
-
-- full tool catalog stays on the server
-- deferred tools stay out of the initial model-facing tool list
-- model can call `search_tools`
-- runtime loads matching deferred tools into the next loop iteration
-
-Supports:
-
-- mixed server tools + client tools
-- profile-aware search
-- BM25-style ranking
-
-Main files:
-
-- `packages/llm-sdk/src/server/tool-selection.ts`
-- `packages/llm-sdk/src/server/runtime.ts`
-
-### 4. Native provider tool search support
-
-Added provider-aware search mode selection:
-
-- `search.mode = "auto" | "native" | "manual"`
-
-Current behavior:
-
-- Anthropic Sonnet 4 / Opus 4 supported models -> native Anthropic search path
-- OpenAI `gpt-5.4+` supported models -> internal OpenAI Responses-based native path
-- all other providers/models -> manual `search_tools` fallback
-
-Anthropic native path:
-
-- adds `tool_search_tool_bm25_20251119` or regex variant
-- passes deferred tools with `defer_loading: true`
-
-OpenAI native path:
-
-- uses internal Responses-based adapter branch
-- keeps public SDK/frontend usage unchanged
-
-Main files:
-
-- `packages/llm-sdk/src/adapters/anthropic.ts`
-- `packages/llm-sdk/src/adapters/openai.ts`
-- `packages/llm-sdk/src/server/tool-selection.ts`
-
-### 5. Mixed client/server catalog support
-
-Added `toolCatalog` transport support so the runtime can search/select from the full catalog:
-
-- server tools from runtime config
-- client tools registered in the browser
-
-This allows deferred client tools to be discovered by search even when they are not initially exposed to the model.
-
-Main files:
-
-- `packages/copilot-sdk/src/chat/interfaces/ChatTransport.ts`
-- `packages/copilot-sdk/src/chat/adapters/HttpTransport.ts`
-- `packages/copilot-sdk/src/chat/classes/AbstractChat.ts`
-- `packages/llm-sdk/src/server/types.ts`
-- `packages/llm-sdk/src/server/runtime.ts`
-
-### 6. Provider payload logging
-
-Added adapter-level debug payload logging for request/response inspection.
-
-Supported across:
-
-- OpenAI
-- Anthropic
-- Azure
-- Google
-- xAI
-- Ollama
-
-Current behavior:
-
-- logs request payloads
-- logs final provider responses
-- suppresses per-event stream spam
-
-Main file:
-
-- `packages/llm-sdk/src/adapters/base.ts`
-
-### 7. Experimental Tool Scale Lab
-
-Added a dedicated experimental demo for scale testing:
-
-- 100 tools total
-- 30 server tools
-- 70 client tools
-- profile switching
-- deferred loading
-- manual/native search path testing
-- provider behavior testing
-
-Main files:
-
-- `examples/experimental/app/tool-scale/page.tsx`
-- `examples/experimental/app/api/chat/tool-scale/route.ts`
-- `examples/experimental/lib/tool-scale/catalog.ts`
-- `examples/experimental/lib/tool-scale/server-tools.ts`
-- `examples/experimental/lib/tool-scale/client-tools.ts`
-
-## Config Examples
-
-### Runtime tool selection
-
-```ts
-agentLoop: {
-  enabled: true,
-  toolSelection: {
-    enabled: true,
-    defaultProfile: "support",
-    includeUnprofiled: false,
-    dynamicSelection: {
-      enabled: true,
-      maxTools: 6,
-    },
-    search: {
-      enabled: true,
-      mode: "auto",
-      strictDeferredLoading: true,
-      maxResults: 6,
-      metaToolName: "search_tools",
-      anthropicVariant: "bm25",
-    },
-  },
-}
-```
-
-### Client-side optimization
-
-```ts
-optimization: {
-  toolProfiles: {
-    enabled: true,
-    defaultProfile: "support",
-  },
-  toolResultConfig: {
-    truncation: {
-      enabled: true,
-      strategy: "smart",
-      hardMaxChars: 12000,
-    },
-  },
-  contextManagement: {
-    enabled: true,
-    history: {
-      maxMessages: 20,
-      pruneStrategy: "summarize",
-    },
-  },
-  contextBudget: {
-    enabled: true,
-    budget: {
-      contextWindowTokens: 128000,
-      toolResultsShare: 0.3,
-    },
-  },
-}
-```
-
-## Current Known Caveats
-
-These are not fully closed out yet:
-
-- mixed same-turn server + client tool calls still need more hardening in the runtime loop
-- OpenAI manual fallback + continuation path needs more validation
-- OpenAI native Responses path currently preserves the SDK contract, but is not full event-by-event Responses streaming yet
-- no dedicated automated tests were added in this branch yet
-
-## Suggested Next Steps
-
-- add tests for tool selection, deferred loading, and continuation ordering
-- tighten manual search scoring so profile-only matches do not leak through
-- harden mixed same-turn server/client tool execution ordering
-- improve OpenAI Responses-native streaming parity