@witqq/agent-sdk 0.7.0 → 0.8.0

package/dist/chat/react.d.ts

@@ -1,34 +1,35 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { IChatRuntime } from './runtime.js';
-import { ChatMessage, RuntimeStatus, SessionInfo, TextPart, ReasoningPart, ToolCallPart, SourcePart, FilePart, ChatSession, ChatEvent, ChatId, ChatIdLike, SendMessageOptions, ChatMiddleware } from './core.js';
-import { A as AuthToken } from '../types-Bh5AhqD-.js';
-import { d as ModelInfo$1, T as ToolDefinition } from '../types-CqvUAYxt.js';
-import { CreateSessionOptions, SessionListOptions } from './sessions.js';
+import { ReactNode, ComponentType } from 'react';
+import { IChatClient, BackendInfo, SelectionChangeCallback } from './runtime.js';
+import { c as ChatMessage, R as RuntimeStatus, r as SessionInfo, u as TextPart, q as ReasoningPart, v as ToolCallPart, t as SourcePart, F as FilePart, g as ChatSession, a as ChatEvent, b as ChatId, f as ChatIdLike, S as SendMessageOptions } from '../types-ajANVzf7.js';
+import { A as AuthToken } from '../types-BxggH0Yh.js';
+import { P as ProviderConfig } from '../provider-types-PTSlRPNB.js';
 import { ContextStats } from './context.js';
-import '../types-DLZzlJxt.js';
-import '../errors-BDLbNu9w.js';
+import { M as ModelInfo } from '../agent-CW9XbmG_.js';
+import { CreateSessionOptions, SessionListOptions } from './sessions.js';
+import '../errors-C-so0M4t.js';
 import 'zod';
 import './storage.js';
+import '../errors-CmVvczxZ.js';
 
 /** Props for ChatProvider. */
 interface ChatProviderProps {
-    /** The chat runtime instance to provide to descendants. */
-    runtime: IChatRuntime;
+    /** The chat runtime or client instance to provide to descendants. Accepts IChatClient (or any structurally compatible type). */
+    runtime: IChatClient;
     children: ReactNode;
 }
 /**
- * React context provider wrapping IChatRuntime.
+ * React context provider wrapping IChatClient.
  * All chat hooks must be used within a ChatProvider.
  */
-declare function ChatProvider({ runtime, children }: ChatProviderProps): react.FunctionComponentElement<react.ProviderProps<IChatRuntime<Record<string, unknown>> | null>>;
+declare function ChatProvider({ runtime, children }: ChatProviderProps): react.FunctionComponentElement<react.ProviderProps<IChatClient<Record<string, unknown>> | null>>;
 /**
- * Access the IChatRuntime from context.
+ * Access the IChatClient from context.
  * Must be used within a ChatProvider.
  *
  * @throws {Error} If used outside ChatProvider
  */
-declare function useChatRuntime(): IChatRuntime;
+declare function useChatRuntime(): IChatClient;
 
 /** Options for the useChat hook. */
 interface UseChatOptions {
@@ -36,6 +37,15 @@ interface UseChatOptions {
     sessionId?: string;
     /** Called on error during send. */
     onError?: (error: Error) => void;
+    /** Auto-dismiss errors after this many ms (0 = disabled, default: 0). */
+    autoDismissMs?: number;
+}
+/** Token usage data from the last completed response. */
+interface ChatUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    model?: string;
 }
 /** Return value from useChat. */
 interface UseChatReturn {
@@ -55,8 +65,12 @@ interface UseChatReturn {
     error: Error | null;
     /** Clear the error state. */
     clearError: () => void;
+    /** Retry the last failed message. No-op if no error or no last user message. */
+    retryLastMessage: () => Promise<void>;
     /** Create a new session, resetting messages. */
     newSession: () => Promise<string>;
+    /** Token usage from the last completed response. */
+    usage: ChatUsage | null;
 }
 /**
  * Convenience hook for chat interaction.
@@ -107,7 +121,7 @@ interface UseSessionsReturn {
 /**
  * Reactive session list hook.
  * Subscribes to `runtime.onSessionChange()` and refreshes the list automatically
- * on create, delete, archive, and message send completion.
+ * on create, delete, and message send completion.
  */
 declare function useSessions(): UseSessionsReturn;
 
@@ -148,7 +162,7 @@ interface ToolCallViewProps {
 }
 /**
  * Headless tool call display component.
- * Shows tool name, status, args, result, and approval buttons when needed.
+ * Shows tool name, status, collapsible args/result, and approval buttons when needed.
  */
 declare function ToolCallView({ part, onApprove, onDeny, renderArgs, renderResult }: ToolCallViewProps): ReactNode;
 
@@ -202,6 +216,7 @@ interface ThreadProps {
 /**
  * Headless thread component wrapping a scrollable message list.
  * Auto-scrolls to bottom when new messages arrive unless user has scrolled up.
+ * Shows a scroll-to-bottom button when scrolled up and an empty state when no messages.
  */
 declare function Thread({ messages, isGenerating, autoScroll, className, }: ThreadProps): ReactNode;
 
@@ -270,6 +285,10 @@ declare function ThreadList({ sessions, activeSessionId, onSelect, onCreate, onD
 type SSEStatus = "idle" | "connecting" | "open" | "closed" | "error";
 /** Options for the useSSE hook. */
 interface UseSSEOptions {
+    /** HTTP method (default: "GET") */
+    method?: "GET" | "POST";
+    /** Request body for POST requests (JSON-serialized automatically) */
+    body?: unknown;
     headers?: Record<string, string>;
     onEvent?: (event: ChatEvent) => void;
     onError?: (error: Error) => void;
@@ -294,9 +313,9 @@ interface ModelOption {
     id: string;
     name: string;
     tier?: string;
+    /** Provider/backend name for multi-provider context. */
+    provider?: string;
 }
-/** @deprecated Use ModelOption instead — renamed to avoid collision with core ModelInfo */
-type ModelInfo = ModelOption;
 /** Return type for the useModels hook. */
 interface UseModelsReturn {
     models: ModelOption[];
@@ -317,55 +336,14 @@ interface ModelSelectorProps {
     onSelect: (modelId: string) => void;
     placeholder?: string;
     className?: string;
+    /** Allow free-text model input when models list is empty. Default: true. */
+    allowFreeText?: boolean;
 }
 /**
  * Dropdown model selector with search and keyboard navigation.
+ * Falls back to a free-text input when models list is empty.
  */
-declare function ModelSelector({ models, selectedModel, onSelect, placeholder, className, }: ModelSelectorProps): ReactNode;
-
-/** Supported auth backends. */
-type AuthBackend = "copilot" | "claude" | "api-key";
-/** Auth status state machine: idle → pending → authenticated | error. */
-type AuthStatus = "idle" | "pending" | "authenticated" | "error";
-/** Options for the useAuth hook. */
-interface UseAuthOptions {
-    backend: AuthBackend;
-    onAuthenticated?: (token: AuthToken) => void;
-}
-/** Return value from useAuth. */
-interface UseAuthReturn {
-    status: AuthStatus;
-    error: Error | null;
-    startDeviceFlow: () => Promise<void>;
-    deviceCode: string | null;
-    verificationUrl: string | null;
-    startOAuthFlow: () => Promise<void>;
-    authorizeUrl: string | null;
-    completeOAuth: (codeOrUrl: string) => Promise<void>;
-    submitApiKey: (key: string) => void;
-    token: AuthToken | null;
-    reset: () => void;
-}
-/**
- * Hook for multi-backend authentication.
- *
- * Wraps CopilotAuth (Device Flow), ClaudeAuth (OAuth+PKCE),
- * and plain API key validation into a unified React state machine.
- *
- * @deprecated Use `useRemoteAuth` instead for browser contexts.
- * `useAuth` directly instantiates auth classes which require `node:crypto`
- * (via ClaudeAuth). The `useRemoteAuth` hook delegates authentication to
- * server endpoints (createAuthHandler), avoiding browser crypto dependencies.
- *
- * Migration: replace `useAuth({ backend })` with
- * `useRemoteAuth({ backend, baseUrl: "/api/auth" })`.
- * Note: the `"api-key"` backend is renamed to `"vercel-ai"` in useRemoteAuth,
- * and `submitApiKey` is now async (returns Promise<void>).
- * The return interface is otherwise compatible — `startDeviceFlow`, `startOAuthFlow`,
- * `completeOAuth`, `submitApiKey`, `token`, `status`, `error`, `reset`
- * all work the same way.
- */
-declare function useAuth(options: UseAuthOptions): UseAuthReturn;
+declare function ModelSelector({ models, selectedModel, onSelect, placeholder, className, allowFreeText, }: ModelSelectorProps): ReactNode;
 
 /**
  * @witqq/agent-sdk/chat/react — useRemoteAuth
@@ -440,8 +418,8 @@ declare function useRemoteAuth(options: UseRemoteAuthOptions): UseRemoteAuthRetu
  * Lifecycle hook that orchestrates auth → runtime → session.
  *
  * On mount, checks for saved auth tokens and auto-restores.
- * Once authenticated, creates a RemoteChatRuntime and initial session.
- * Exposes readiness phase, the runtime instance, and the auth sub-hook.
+ * Once authenticated, creates a RemoteChatClient and initial session.
+ * Exposes readiness phase, the client instance, and the auth sub-hook.
  */
 
 /** Lifecycle phase for the useRemoteChat hook. */
@@ -460,15 +438,13 @@ interface UseRemoteChatOptions {
     fetch?: typeof globalThis.fetch;
     /** Optional headers for all requests. */
     headers?: Record<string, string>;
-    /** Auto-restore saved tokens on mount (default: true). */
-    autoRestore?: boolean;
 }
 /** Return value from useRemoteChat. */
 interface UseRemoteChatReturn {
     /** Current lifecycle phase. */
     phase: RemoteChatPhase;
-    /** Chat runtime (null until phase = "ready"). */
-    runtime: IChatRuntime | null;
+    /** Chat client (null until phase = "ready"). */
+    runtime: IChatClient | null;
     /** Initial session ID (null until phase = "ready"). */
     sessionId: string | null;
     /** Auth sub-hook for manual auth control. */
@@ -501,39 +477,415 @@ interface UseRemoteChatReturn {
  */
 declare function useRemoteChat(options: UseRemoteChatOptions): UseRemoteChatReturn;
 
-/** Props for the AuthDialog component. */
-interface AuthDialogProps {
-    backends: AuthBackend[];
-    selectedBackend?: AuthBackend;
-    onBackendChange?: (backend: AuthBackend) => void;
-    onAuthenticated?: (token: AuthToken) => void;
-    renderCopilotFlow?: (state: {
-        deviceCode: string;
-        verificationUrl: string;
-        status: AuthStatus;
-    }) => ReactNode;
-    renderClaudeFlow?: (state: {
-        authorizeUrl: string | null;
-        status: AuthStatus;
-        completeOAuth: (code: string) => Promise<void>;
-    }) => ReactNode;
-    renderApiKeyFlow?: (state: {
-        submitApiKey: (key: string) => void;
-        status: AuthStatus;
-    }) => ReactNode;
+/**
+ * Props passed to per-backend auth form components.
+ * Each backend implements its own form using these props.
+ */
+interface AuthFormProps {
+    /** The remote auth hook instance, pre-configured for this backend. */
+    auth: UseRemoteAuthReturn;
+    /** Called when authentication completes successfully. */
+    onAuthComplete: () => void;
+}
+/** A backend auth form component. */
+type AuthFormComponent = (props: AuthFormProps) => ReactNode;
+
+/**
+ * Copilot (GitHub) auth form — device flow.
+ *
+ * Shows "Authenticate with GitHub" button → device code + verification URL →
+ * "Waiting..." → "✓ Authenticated" + "Continue →".
+ *
+ * Co-located with the Copilot backend.
+ */
+declare function CopilotAuthForm({ auth, onAuthComplete }: AuthFormProps): ReactNode;
+
+/**
+ * Claude auth form — OAuth Authorization Code + PKCE.
+ *
+ * Shows "Authenticate with Claude" button → authorize URL link +
+ * paste-code input + "Submit" button.
+ *
+ * Co-located with the Claude backend.
+ */
+declare function ClaudeAuthForm({ auth, onAuthComplete }: AuthFormProps): ReactNode;
+
+/**
+ * Vercel AI auth form — API key + optional base URL.
+ *
+ * Shows base URL input + API key input + "Connect" button.
+ *
+ * Co-located with the Vercel AI backend.
+ */
+declare function VercelAIAuthForm({ auth, onAuthComplete }: AuthFormProps): ReactNode;
+
+/** Props for the BackendSelector component. */
+interface BackendSelectorProps {
+    backends: BackendInfo[];
+    onSelect: (name: string) => void;
+    className?: string;
+}
+/**
+ * Headless backend selector showing registered backends with active indicator.
+ * Uses data attributes for styling:
+ * - `[data-backend-selector]` on root
+ * - `[data-backend-item]` on each item
+ * - `[data-backend-active="true"]` on the active backend
+ * - `[data-backend-name]` with backend name value
+ */
+declare function BackendSelector({ backends, onSelect, className, }: BackendSelectorProps): ReactNode;
+
+/** Return type for the useBackends hook. */
+interface UseBackendsReturn {
+    backends: BackendInfo[];
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => void;
+}
+/**
+ * Hook for discovering registered backends and switching between them.
+ */
+declare function useBackends(): UseBackendsReturn;
+
+/** Return type for the useProviders hook. */
+interface UseProvidersReturn {
+    providers: ProviderConfig[];
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => void;
+    createProvider: (config: Omit<ProviderConfig, "id" | "createdAt">) => Promise<void>;
+    updateProvider: (id: string, changes: Partial<Omit<ProviderConfig, "id" | "createdAt">>) => Promise<void>;
+    deleteProvider: (id: string) => Promise<void>;
+    selectProvider: (id: string) => void;
+}
+/**
+ * Hook for managing providers (backend + model combos).
+ * Requires an IChatClient with provider methods (e.g. RemoteChatClient).
+ */
+declare function useProviders(): UseProvidersReturn;
+
+/** Props for the ProviderSelector component. */
+interface ProviderSelectorProps {
+    providers: ProviderConfig[];
+    activeProviderId?: string;
+    onSelect: (id: string) => void;
+    onSettingsClick?: () => void;
+    className?: string;
+}
+/**
+ * Headless dropdown for selecting a configured provider.
+ * Uses data attributes for styling hooks. Follows ModelSelector pattern.
+ */
+declare function ProviderSelector({ providers, activeProviderId, onSelect, onSettingsClick, className, }: ProviderSelectorProps): ReactNode;
+
+/** A unified item rendered in the ProviderModelSelector dropdown. */
+interface ProviderModelItem {
+    id: string;
+    label: string;
+    sublabel?: string;
+    tier?: string;
+    type: "provider" | "model";
+}
+/** Props for the ProviderModelSelector component. */
+interface ProviderModelSelectorProps {
+    /** Configured providers (backend + model combos). When non-empty, provider mode is used. */
+    providers?: ProviderConfig[];
+    /** Available models. Used when providers is empty or undefined. */
+    models?: ModelOption[];
+    /** Currently selected provider ID. */
+    activeProviderId?: string;
+    /** Currently selected model ID (fallback mode). */
+    selectedModel?: string;
+    /** Called when a provider is selected. */
+    onSelectProvider?: (id: string) => void;
+    /** Called when a model is selected (fallback mode). */
+    onSelectModel?: (modelId: string) => void;
+    /** Called when settings gear is clicked. */
+    onSettingsClick?: () => void;
+    /** Placeholder text for the trigger button. */
+    placeholder?: string;
+    className?: string;
+}
+/**
+ * Unified selector that shows providers when available, falls back to model list.
+ * Replaces the need for separate ProviderSelector + ModelSelector in ChatUI.
+ */
+declare function ProviderModelSelector({ providers, models, activeProviderId, selectedModel, onSelectProvider, onSelectModel, onSettingsClick, placeholder, className, }: ProviderModelSelectorProps): ReactNode;
+
+/** Props for the ProviderSettings component. */
+interface ProviderSettingsProps {
+    providers: ProviderConfig[];
+    onClose?: () => void;
+    onProviderCreated?: (p: ProviderConfig) => void;
+    onProviderDeleted?: (id: string) => void;
+    onProviderUpdated?: (id: string, changes: {
+        model?: string;
+        label?: string;
+    }) => void;
+    /** Called when authentication succeeds (before configure step). Parent should refresh providers. */
+    onAuthCompleted?: (backend: string) => void;
+    authBaseUrl?: string;
+    className?: string;
+}
+/**
+ * Headless settings panel for managing providers.
+ * States: list (all providers), add (new provider flow), edit (existing).
+ */
+declare function ProviderSettings({ providers, onClose, onProviderCreated, onProviderDeleted, onProviderUpdated, onAuthCompleted, authBaseUrl, className, }: ProviderSettingsProps): ReactNode;
+
+/** Props for the ContextStatsDisplay component. */
+interface ContextStatsDisplayProps {
+    /** Context stats from runtime.getContextStats(sessionId). Null = nothing to display. */
+    stats: ContextStats | null;
+    /** CSS class on the root element. */
+    className?: string;
+}
+/**
+ * Headless component displaying context window statistics.
+ *
+ * When real usage data is available (realPromptTokens + modelContextWindow),
+ * displays actual token usage and model context window size.
+ * When real data is not yet available (before first API response), returns null.
+ *
+ * All elements use `data-*` attributes for CSS styling — no inline styles.
+ */
+declare function ContextStatsDisplay({ stats, className }: ContextStatsDisplayProps): ReactNode;
+
+/**
+ * @witqq/agent-sdk/chat/react — ChatUI
+ *
+ * Composite component that wires Thread, Composer, ThreadList, ModelSelector,
+ * and ProviderSettings into a complete chat interface. Consumers get a full AI chat
+ * in ~3 lines:
+ *
+ *   import { ChatUI } from "@witqq/agent-sdk/chat/react";
+ *   <ChatUI runtime={myRuntime} />
+ *
+ * Slot system: replace any sub-component while keeping all others as defaults.
+ *
+ * Built from composable sub-components: ChatLayout, ChatHeader, ChatInputArea,
+ * ChatSettingsOverlay — each usable independently for custom layouts.
+ */
+
+/** Slot overrides for ChatUI sub-components. */
+interface ChatUISlots {
+    /** Replace the Thread component. */
+    thread?: ComponentType<ThreadProps>;
+    /** Replace the Composer component. */
+    composer?: ComponentType<ComposerProps>;
+    /** Replace the ThreadList (sidebar) component. */
+    threadList?: ComponentType<ThreadListProps>;
+    /** Replace the ModelSelector component (used in header when no providers). */
+    modelSelector?: ComponentType<ModelSelectorProps>;
+    /** Replace the BackendSelector component. */
+    backendSelector?: ComponentType<BackendSelectorProps>;
+    /** Replace the ProviderSelector component (legacy, use providerModelSelector). */
+    providerSelector?: ComponentType<ProviderSelectorProps>;
+    /** Replace the unified ProviderModelSelector component (near composer). */
+    providerModelSelector?: ComponentType<ProviderModelSelectorProps>;
+    /** Replace the ProviderSettings component. */
+    providerSettings?: ComponentType<ProviderSettingsProps>;
+    /** Replace the ContextStatsDisplay component. */
+    contextStats?: ComponentType<ContextStatsDisplayProps>;
+    /** Custom auth dialog element rendered when provided. */
+    authDialog?: ReactNode;
+    /** Custom message renderer (forwarded to ThreadProvider). */
+    renderMessage?: (message: ChatMessage, index: number) => ReactNode;
+    /** Custom tool call renderer (forwarded to ThreadProvider). */
+    renderToolCall?: (part: ToolCallPart, index: number) => ReactNode;
+    /** Custom thinking block renderer (forwarded to ThreadProvider). */
+    renderThinkingBlock?: (part: ReasoningPart, index: number) => ReactNode;
+}
+/** Props for the ChatUI composite component. */
+interface ChatUIProps {
+    /** The chat runtime or client instance. ChatUI wraps it in ChatProvider. Accepts IChatClient. */
+    runtime: IChatClient;
+    /** Slot overrides for sub-components. */
+    slots?: ChatUISlots;
+    /** CSS class on the root element. */
+    className?: string;
+    /** Show the session sidebar. Default: true. */
+    showSidebar?: boolean;
+    /** Show the model selector header. Default: true. */
+    showModelSelector?: boolean;
+    /** Show the backend selector in header. Default: false. */
+    showBackendSelector?: boolean;
+    /** Show the provider selector near composer. Default: auto (true when providers available). */
+    showProviderSelector?: boolean;
+    /** Base URL for auth API (needed by ProviderSettings). */
+    authBaseUrl?: string;
+    /** Placeholder text for the Composer textarea. */
+    placeholder?: string;
+}
+/**
+ * Composite chat component — complete AI chat interface in one import.
+ *
+ * ```tsx
+ * import { ChatUI } from "@witqq/agent-sdk/chat/react";
+ *
+ * function App() {
+ *   return <ChatUI runtime={myRuntime} />;
+ * }
+ * ```
+ */
+declare function ChatUI({ runtime, ...rest }: ChatUIProps): ReactNode;
+
+/**
+ * @witqq/agent-sdk/chat/react — ChatLayout
+ *
+ * Pure layout container for chat interfaces. Renders sidebar + main area
+ * without any logic or state. ChatUI uses this internally.
+ */
+
+/** Props for the ChatLayout component. */
+interface ChatLayoutProps {
+    /** Main chat content (thread, input area, etc.). */
+    children: ReactNode;
+    /** Sidebar content (thread list, session list, etc.). */
+    sidebar?: ReactNode;
+    /** Modal/overlay content. Accepts a single node or array of nodes. */
+    overlay?: ReactNode | ReactNode[];
+    /** CSS class on the root element. */
     className?: string;
 }
 /**
- * Multi-backend auth dialog component.
+ * Pure layout container — flex row with optional sidebar and overlay.
  *
- * Headless component that renders backend selector buttons and
- * per-backend auth flows. Uses data attributes for styling hooks.
- * Supports custom render props for each flow type.
+ * Renders `[data-chat-ui]` root with:
+ * - overlay (rendered first for z-index stacking)
+ * - sidebar (rendered before main content)
+ * - children (main chat area)
  */
-declare function AuthDialog({ backends, selectedBackend: controlledBackend, onBackendChange, onAuthenticated, renderCopilotFlow, renderClaudeFlow, renderApiKeyFlow, className, }: AuthDialogProps): ReactNode;
+declare function ChatLayout({ children, sidebar, overlay, className }: ChatLayoutProps): ReactNode;
 
 /**
- * Client-side runtime adapter that implements IChatRuntime by delegating
+ * @witqq/agent-sdk/chat/react — ChatHeader
+ *
+ * Selector composition for the chat header area. Renders backend selector,
+ * model selector, or nothing based on configuration.
+ */
+
+/** Props for the ChatHeader component. */
+interface ChatHeaderProps {
+    /** Whether to show backend selector. Default: false. */
+    showBackendSelector?: boolean;
+    /** Whether to show model selector. Default: true. */
+    showModelSelector?: boolean;
+    /** Whether providers are configured (hides model selector when true). */
+    hasProviders?: boolean;
+    /** Available backends list. */
+    backends?: BackendInfo[];
+    /** Available models list. */
+    models?: ModelOption[];
+    /** Currently selected model. */
+    selectedModel?: string;
+    /** Backend selection handler. */
+    onBackendSelect?: (name: string) => void;
+    /** Model selection handler. */
+    onModelSelect?: (modelId: string) => void;
+    /** Slot override for BackendSelector. */
+    BackendSelectorComponent?: ComponentType<BackendSelectorProps>;
+    /** Slot override for ModelSelector. */
+    ModelSelectorComponent?: ComponentType<ModelSelectorProps>;
+}
+/**
+ * Header area with backend and model selectors.
+ * Returns null when no selectors need to be shown.
+ */
+declare function ChatHeader({ showBackendSelector, showModelSelector, hasProviders, backends, models, selectedModel, onBackendSelect, onModelSelect, BackendSelectorComponent: BSC, ModelSelectorComponent: MSC, }: ChatHeaderProps): ReactNode;
+
+/**
+ * @witqq/agent-sdk/chat/react — ChatInputArea
+ *
+ * Input area combining the unified provider/model selector with the composer.
+ */
+
+/** Props for the ChatInputArea component. */
+interface ChatInputAreaProps {
+    /** Send message handler. */
+    onSend: (message: string) => void;
+    /** Stop generation handler. */
+    onStop?: () => void;
+    /** Whether generation is in progress. */
+    isGenerating?: boolean;
+    /** Placeholder text for the textarea. */
+    placeholder?: string;
+    /** Available providers. */
+    providers?: ProviderConfig[];
+    /** Available models. */
+    models?: ModelOption[];
+    /** Active provider ID. */
+    activeProviderId?: string;
+    /** Selected model. */
+    selectedModel?: string;
+    /** Provider selection handler. */
+    onSelectProvider?: (id: string) => void;
+    /** Model selection handler. */
+    onSelectModel?: (modelId: string) => void;
+    /** Settings button handler. */
+    onSettingsClick?: () => void;
+    /** Slot override for Composer. */
+    ComposerComponent?: ComponentType<ComposerProps>;
+    /** Slot override for ProviderModelSelector. */
+    ProviderModelSelectorComponent?: ComponentType<ProviderModelSelectorProps>;
+    /** Token usage data to display. */
+    usage?: ChatUsage | null;
+}
+/**
+ * Input area — unified selector + composer in a `[data-chat-input-area]` container.
+ */
+declare function ChatInputArea({ onSend, onStop, isGenerating, placeholder, providers, models, activeProviderId, selectedModel, onSelectProvider, onSelectModel, onSettingsClick, ComposerComponent: CC, ProviderModelSelectorComponent: PMSC, usage, }: ChatInputAreaProps): ReactNode;
+
+/**
+ * @witqq/agent-sdk/chat/react — ChatSettingsOverlay
+ *
+ * Modal overlay for provider settings management.
+ * Features: backdrop click-to-close, ESC key handler, focus trap.
+ */
+
+/** Props for the ChatSettingsOverlay component. */
+interface ChatSettingsOverlayProps {
+    /** Whether the overlay is visible. */
+    open: boolean;
+    /** Close handler. */
+    onClose: () => void;
+    /** Available providers. */
+    providers?: ProviderConfig[];
+    /** Auth API base URL. */
+    authBaseUrl?: string;
+    /** Provider created handler. */
+    onProviderCreated?: (provider: {
+        backend: string;
+        model: string;
+        label?: string;
+    }) => void;
+    /** Provider deleted handler. */
+    onProviderDeleted?: (id: string) => void;
+    /** Provider updated handler. */
+    onProviderUpdated?: (id: string, changes: Partial<ProviderConfig>) => void;
+    /** Called when authentication succeeds. Parent should refresh providers. */
+    onAuthCompleted?: (backend: string) => void;
+    /** Slot override for ProviderSettings. */
+    ProviderSettingsComponent?: ComponentType<ProviderSettingsProps>;
+}
+/**
+ * Settings modal — renders `[data-provider-settings-overlay]` when open.
+ * Returns null when closed.
+ * Backdrop click and Escape key close the overlay with exit animation.
+ * Focus is trapped within the overlay content.
+ */
+declare function ChatSettingsOverlay({ open, onClose, providers, authBaseUrl, onProviderCreated, onProviderDeleted, onProviderUpdated, onAuthCompleted, ProviderSettingsComponent: PSC, }: ChatSettingsOverlayProps): ReactNode;
+
+/** Props for the UsageBadge component. */
+interface UsageBadgeProps {
+    usage: ChatUsage | null;
+    className?: string;
+}
+/** Compact token usage display. Shows prompt/completion/total tokens. */
+declare function UsageBadge({ usage, className }: UsageBadgeProps): ReactNode;
+
+/**
+ * Client-side adapter that implements IChatClient by delegating
  * operations over HTTP/SSE to a remote server.
  *
  * Bridges the gap between SDK React hooks (which require an in-process runtime)
@@ -541,30 +893,35 @@ declare function AuthDialog({ backends, selectedBackend: controlledBackend, onBa
  *
  * @example
  * ```ts
- * import { RemoteChatRuntime } from "@witqq/agent-sdk/chat/react";
+ * import { RemoteChatClient } from "@witqq/agent-sdk/chat/react";
  * import { ChatProvider } from "@witqq/agent-sdk/chat/react";
  *
- * const runtime = new RemoteChatRuntime({ baseUrl: "/api" });
- * <ChatProvider runtime={runtime}> ... </ChatProvider>
+ * const client = new RemoteChatClient({ baseUrl: "/api" });
+ * <ChatProvider runtime={client}> ... </ChatProvider>
  * ```
  */
 
 /**
  * Standard server endpoint contract.
- * Server implementations expose these routes to work with RemoteChatRuntime.
+ * Server implementations expose these routes to work with RemoteChatClient.
  *
  * POST   {baseUrl}/sessions/create   — Create session
  * GET    {baseUrl}/sessions/{id}     — Get session
  * GET    {baseUrl}/sessions          — List sessions
  * DELETE {baseUrl}/sessions/{id}     — Delete session
- * POST   {baseUrl}/sessions/{id}/archive — Archive session
+ * GET    {baseUrl}/sessions/{id}/context-stats — Get context window stats
  * POST   {baseUrl}/send              — Send message (SSE stream response)
  * POST   {baseUrl}/abort             — Abort current stream
  * GET    {baseUrl}/models            — List models
- * POST   {baseUrl}/backend/switch    — Switch backend
+ * GET    {baseUrl}/backends          — List backends
  * POST   {baseUrl}/model/switch      — Switch model
+ * POST   {baseUrl}/provider/switch   — Switch provider (backend + model)
+ * GET    {baseUrl}/providers         — List providers
+ * POST   {baseUrl}/providers         — Create provider
+ * PUT    {baseUrl}/providers/{id}    — Update provider
+ * DELETE {baseUrl}/providers/{id}    — Delete provider
  */
-interface RemoteChatRuntimeOptions {
+interface RemoteChatClientOptions {
     /** Base URL for API endpoints (e.g. "/api" or "https://example.com/api") */
     baseUrl: string;
     /** Optional headers for all requests (e.g. auth tokens) */
@@ -572,48 +929,160 @@ interface RemoteChatRuntimeOptions {
     /** Custom fetch implementation for testability */
     fetch?: typeof globalThis.fetch;
 }
-declare class RemoteChatRuntime implements IChatRuntime {
+declare class RemoteChatClient implements IChatClient {
     private _status;
     private _activeSessionId;
-    private _currentBackend;
-    private _currentModel;
+    private _selectedProviderId;
     private _abortController;
-    private readonly _tools;
-    private readonly _middlewares;
     private readonly baseUrl;
     private readonly headers;
     private readonly _fetch;
-    constructor(options: RemoteChatRuntimeOptions);
+    private readonly _selectionListeners;
+    constructor(options: RemoteChatClientOptions);
     get status(): RuntimeStatus;
     dispose(): Promise<void>;
     private assertNotDisposed;
+    get selectedProviderId(): string | null;
+    selectProvider(providerId: string): void;
+    onSelectionChange(callback: SelectionChangeCallback): () => void;
+    private _notifySelectionChange;
     get activeSessionId(): ChatId | null;
     createSession(options: CreateSessionOptions): Promise<ChatSession>;
     getSession(id: ChatIdLike): Promise<ChatSession | null>;
     listSessions(_options?: SessionListOptions): Promise<ChatSession[]>;
     deleteSession(id: ChatIdLike): Promise<void>;
-    archiveSession(id: ChatIdLike): Promise<void>;
+    /**
+     * Fetch context window stats from server.
+     * Returns null if stats not available (e.g. no messages sent yet).
+     */
+    getContextStats(sessionId: ChatIdLike): Promise<ContextStats | null>;
     switchSession(id: ChatIdLike): Promise<ChatSession>;
     send(sessionId: ChatIdLike, message: string, options?: SendMessageOptions): AsyncIterable<ChatEvent>;
     abort(): void;
-    get currentBackend(): string;
-    get currentModel(): string | undefined;
-    switchBackend(name: string): Promise<void>;
-    switchModel(model: string): void;
-    listModels(): Promise<ModelInfo$1[]>;
-    get registeredTools(): ReadonlyMap<string, ToolDefinition>;
-    registerTool(tool: ToolDefinition): void;
-    removeTool(name: string): void;
-    use(middleware: ChatMiddleware): void;
-    removeMiddleware(middleware: ChatMiddleware): void;
-    getContextStats(_sessionId: ChatIdLike): ContextStats | null;
+    listModels(): Promise<ModelInfo[]>;
+    listBackends(): Promise<BackendInfo[]>;
+    listProviders(): Promise<ProviderConfig[]>;
+    createProvider(config: Omit<ProviderConfig, "id" | "createdAt">): Promise<ProviderConfig>;
+    updateProvider(id: string, changes: Partial<Omit<ProviderConfig, "id" | "createdAt">>): Promise<void>;
+    deleteProvider(id: string): Promise<void>;
     private readonly _sessionListeners;
     onSessionChange(callback: () => void): () => void;
     private _notifySessionChange;
     private _get;
     private _post;
     private _delete;
+    private _put;
     private _parseSSEStream;
 }
 
-export { type AuthBackend, AuthDialog, type AuthDialogProps, type AuthStatus, ChatProvider, Composer, type ComposerProps, MarkdownRenderer, type MarkdownRendererProps, Message, type MessageProps, type ModelInfo, type ModelOption, ModelSelector, type ModelSelectorProps, type PendingToolRequest, type RemoteAuthBackend, type RemoteAuthStatus, type RemoteChatPhase, RemoteChatRuntime, type RemoteChatRuntimeOptions, type SSEStatus, ThinkingBlock, type ThinkingBlockProps, Thread, ThreadList, type ThreadListProps, type ThreadProps, ThreadProvider, type ThreadProviderProps, type ThreadSlotOverrides, ToolCallView, type ToolCallViewProps, type UseAuthOptions, type UseAuthReturn, type UseChatOptions, type UseChatReturn, type UseMessagesOptions, type UseMessagesReturn, type UseModelsReturn, type UseRemoteAuthOptions, type UseRemoteAuthReturn, type UseRemoteChatOptions, type UseRemoteChatReturn, type UseSSEOptions, type UseSSEReturn, type UseSessionsReturn, type UseToolApprovalReturn, useAuth, useChat, useChatRuntime, useMessages, useModels, useOptionalThreadSlots, useRemoteAuth, useRemoteChat, useSSE, useSessions, useThreadSlots, useToolApproval };
+/**
+ * @witqq/agent-sdk/chat/react — useCopilotAuth
+ *
+ * Server-delegated Copilot Device Flow authentication hook.
+ * Independently usable — does not require useRemoteAuth orchestrator.
+ */
+
+/** Options for useCopilotAuth. */
+interface UseCopilotAuthOptions {
+    /** Base URL of the auth server (e.g. "/api/auth") */
+    baseUrl: string;
+    /** Called after successful authentication */
+    onAuthenticated?: (token: AuthToken) => void;
+    /** Called on authentication error */
+    onError?: (error: Error) => void;
+    /** Optional fetch override (for testing) */
+    fetch?: typeof globalThis.fetch;
+    /** Optional headers for all requests */
+    headers?: Record<string, string>;
+}
+/** Return value from useCopilotAuth. */
+interface UseCopilotAuthReturn {
+    status: "idle" | "pending" | "authenticated" | "error";
+    error: Error | null;
+    token: AuthToken | null;
+    deviceCode: string | null;
+    verificationUrl: string | null;
+    /** Start the device flow. Shows deviceCode and verificationUrl, then polls for completion. */
+    start: () => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Copilot Device Flow authentication.
+ * Starts device flow on server, provides code/URL for user, polls until complete.
+ */
+declare function useCopilotAuth(options: UseCopilotAuthOptions): UseCopilotAuthReturn;
+
+/**
+ * @witqq/agent-sdk/chat/react — useClaudeAuth
+ *
+ * Server-delegated Claude OAuth + PKCE authentication hook.
+ * Independently usable — does not require useRemoteAuth orchestrator.
+ */
+
+/** Options for useClaudeAuth. */
+interface UseClaudeAuthOptions {
+    /** Base URL of the auth server (e.g. "/api/auth") */
+    baseUrl: string;
+    /** Called after successful authentication */
+    onAuthenticated?: (token: AuthToken) => void;
+    /** Called on authentication error */
+    onError?: (error: Error) => void;
+    /** Optional fetch override (for testing) */
+    fetch?: typeof globalThis.fetch;
+    /** Optional headers for all requests */
+    headers?: Record<string, string>;
+}
+/** Return value from useClaudeAuth. */
+interface UseClaudeAuthReturn {
+    status: "idle" | "pending" | "authenticated" | "error";
+    error: Error | null;
+    token: AuthToken | null;
+    authorizeUrl: string | null;
+    /** Start OAuth flow. Sets authorizeUrl for user redirect. */
+    start: () => Promise<void>;
+    /** Complete OAuth after redirect. Pass the code or callback URL. */
+    complete: (codeOrUrl: string) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Claude OAuth + PKCE authentication.
+ * Two-step flow: start() gets authorizeUrl → user redirects → complete(code) finishes.
+ */
+declare function useClaudeAuth(options: UseClaudeAuthOptions): UseClaudeAuthReturn;
+
+/**
+ * @witqq/agent-sdk/chat/react — useApiKeyAuth
+ *
+ * Server-delegated API key authentication hook (for Vercel AI / OpenRouter / etc.).
+ * Independently usable — does not require useRemoteAuth orchestrator.
+ */
+
+/** Options for useApiKeyAuth. */
+interface UseApiKeyAuthOptions {
+    /** Base URL of the auth server (e.g. "/api/auth") */
+    baseUrl: string;
+    /** Called after successful authentication */
+    onAuthenticated?: (token: AuthToken) => void;
+    /** Called on authentication error */
+    onError?: (error: Error) => void;
+    /** Optional fetch override (for testing) */
+    fetch?: typeof globalThis.fetch;
+    /** Optional headers for all requests */
+    headers?: Record<string, string>;
+}
+/** Return value from useApiKeyAuth. */
+interface UseApiKeyAuthReturn {
+    status: "idle" | "pending" | "authenticated" | "error";
+    error: Error | null;
+    token: AuthToken | null;
+    /** Submit an API key (and optional provider base URL). */
+    submit: (key: string, apiBaseUrl?: string) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * API key authentication.
+ * Sends key to server for validation and storage.
+ */
+declare function useApiKeyAuth(options: UseApiKeyAuthOptions): UseApiKeyAuthReturn;
+
+export { type AuthFormComponent, type AuthFormProps, BackendSelector, type BackendSelectorProps, ChatHeader, type ChatHeaderProps, ChatInputArea, type ChatInputAreaProps, ChatLayout, type ChatLayoutProps, ChatProvider, ChatSettingsOverlay, type ChatSettingsOverlayProps, ChatUI, type ChatUIProps, type ChatUISlots, type ChatUsage, ClaudeAuthForm, Composer, type ComposerProps, ContextStatsDisplay, type ContextStatsDisplayProps, CopilotAuthForm, MarkdownRenderer, type MarkdownRendererProps, Message, type MessageProps, type ModelOption, ModelSelector, type ModelSelectorProps, type PendingToolRequest, type ProviderModelItem, ProviderModelSelector, type ProviderModelSelectorProps, ProviderSelector, type ProviderSelectorProps, ProviderSettings, type ProviderSettingsProps, type RemoteAuthBackend, type RemoteAuthStatus, RemoteChatClient, type RemoteChatClientOptions, type RemoteChatPhase, type SSEStatus, ThinkingBlock, type ThinkingBlockProps, Thread, ThreadList, type ThreadListProps, type ThreadProps, ThreadProvider, type ThreadProviderProps, type ThreadSlotOverrides, ToolCallView, type ToolCallViewProps, UsageBadge, type UsageBadgeProps, type UseApiKeyAuthOptions, type UseApiKeyAuthReturn, type UseBackendsReturn, type UseChatOptions, type UseChatReturn, type UseClaudeAuthOptions, type UseClaudeAuthReturn, type UseCopilotAuthOptions, type UseCopilotAuthReturn, type UseMessagesOptions, type UseMessagesReturn, type UseModelsReturn, type UseProvidersReturn, type UseRemoteAuthOptions, type UseRemoteAuthReturn, type UseRemoteChatOptions, type UseRemoteChatReturn, type UseSSEOptions, type UseSSEReturn, type UseSessionsReturn, type UseToolApprovalReturn, VercelAIAuthForm, useApiKeyAuth, useBackends, useChat, useChatRuntime, useClaudeAuth, useCopilotAuth, useMessages, useModels, useOptionalThreadSlots, useProviders, useRemoteAuth, useRemoteChat, useSSE, useSessions, useThreadSlots, useToolApproval };