@witqq/agent-sdk 0.7.0 → 0.8.0

package/README.md

@@ -53,6 +53,24 @@ agent.dispose();
 await service.dispose();
 ```
 
+### Retry on Transient Errors
+
+`BaseAgent` supports automatic retry for transient failures:
+
+```typescript
+const agent = service.createAgent({ systemPrompt: "..." });
+const result = await agent.run("prompt", {
+  model: "gpt-5-mini",
+  retry: {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    backoffMultiplier: 2,
+  },
+});
+```
+
+Retries on transient error codes: `TIMEOUT`, `RATE_LIMIT`, `NETWORK`, `MODEL_OVERLOADED`. Never retries `AbortError`, `ReentrancyError`, or `DisposedError`.
+
 ## Tool Definition
 
 Tools are defined with a Zod schema for parameters and an `execute` function:
@@ -161,6 +179,8 @@ interface IPermissionStore {
 }
 ```
 
+Built-in stores: `InMemoryPermissionStore` (session-scoped), `FilePermissionStore` (persists to JSON file), `CompositePermissionStore` (chains multiple stores — first match wins, writes to the store matching the scope). `createDefaultPermissionStore(projectDir)` returns a `CompositePermissionStore` combining project-level and global `FilePermissionStore` instances.
+
 ## Structured Output
 
 Extract typed data from LLM responses using `runStructured`:
@@ -541,32 +561,92 @@ manager.start();
 
 Higher-level primitives for building AI chat applications on top of agent-sdk.
 
+### Composable Architecture
+
+The SDK is layered — use only what you need:
+
+**Standalone agent** (no server, no UI):
+
+```typescript
+import { createAgentService } from "@witqq/agent-sdk";
+const service = await createAgentService("copilot", { useLoggedInUser: true });
+const agent = service.createAgent({ systemPrompt: "You are helpful." });
+const result = await agent.run("Hello");
+```
+
+**Server with runtime** (add HTTP layer):
+
+```typescript
+import * as http from "node:http";
+import { createAgentService } from "@witqq/agent-sdk";
+import type { AuthToken } from "@witqq/agent-sdk/auth";
+import { CopilotAuth } from "@witqq/agent-sdk/auth";
+import { CopilotChatAdapter } from "@witqq/agent-sdk/chat/backends";
+import { createChatRuntime } from "@witqq/agent-sdk/chat/runtime";
+import { createChatServer } from "@witqq/agent-sdk/chat/server";
+import { createSQLiteStorage } from "@witqq/agent-sdk/chat/sqlite";
+
+const { sessionStore, providerStore, tokenStore } = createSQLiteStorage("chat.db");
+
+const runtime = createChatRuntime({
+  backends: {
+    copilot: async (credentials: AuthToken) => {
+      const svc = await createAgentService("copilot", { githubToken: credentials.accessToken });
+      return new CopilotChatAdapter({ agentConfig: { systemPrompt: "Hello" }, agentService: svc });
+    },
+  },
+  defaultBackend: "copilot", sessionStore,
+});
+
+const handler = createChatServer({
+  runtime,
+  auth: { tokenStore, createCopilotAuth: () => new CopilotAuth() },
+  providers: { providerStore },
+});
+http.createServer(handler).listen(3000);
+```
+
+**Full-stack with React** (add frontend):
+
+```typescript
+// frontend — 4 lines
+import { ChatUI, RemoteChatClient } from "@witqq/agent-sdk/chat/react";
+
+const runtime = new RemoteChatClient({ baseUrl: "/api/chat" });
+<ChatUI runtime={runtime} authBaseUrl="/api" />
+```
+
 ### Barrel Import
 
-For most consumer apps, import common types from a single path:
+For most consumer apps, import common types from the barrel:
 
 ```typescript
+// Core types and runtime (barrel export)
 import {
   ChatMessage, ChatSession, ChatEvent, IChatRuntime,
   createChatRuntime, ChatError, classifyError,
+  MessageAccumulator, SSEChatTransport,
+} from "@witqq/agent-sdk/chat";
+
+// React hooks and components (separate import — not in barrel)
+import {
   useChat, useRemoteChat, useRemoteAuth,
   ChatProvider, Thread, Composer,
-  RemoteChatRuntime, SSEChatTransport,
-} from "@witqq/agent-sdk/chat";
+} from "@witqq/agent-sdk/chat/react";
 ```
 
 ### Individual Module Imports
 
 ```typescript
-import { ChatMessage, ChatSession, IChatProvider, isChatMessage } from "@witqq/agent-sdk/chat/core";
+import { ChatMessage, ChatSession, isChatMessage } from "@witqq/agent-sdk/chat/core";
+import type { IChatBackend } from "@witqq/agent-sdk/chat/backends";
 import {
   classifyError, withRetry, isRetryable,
-  ChatSDKError, NetworkError, RateLimitError,
+  ChatError, ErrorCode,
   ExponentialBackoffStrategy
 } from "@witqq/agent-sdk/chat/errors";
-import {
-  ChatEventBus, filterEvents, collectText
-} from "@witqq/agent-sdk/chat/events";
+import { ChatEventBus } from "@witqq/agent-sdk/chat/events";
+import { filterEvents, collectText } from "@witqq/agent-sdk/chat/events";
 import {
   InMemoryStorage, FileStorage,
   type IStorageAdapter, StorageError
@@ -582,7 +662,7 @@ import {
   CopilotChatAdapter, VercelAIChatAdapter, BaseBackendAdapter,
   SSEChatTransport, WsChatTransport, InProcessChatTransport,
   streamToTransport, withInterceptors,
-  type IBackendAdapter, type BackendAdapterOptions, type IChatTransport
+  type IResumableBackend, type BackendAdapterOptions, type IChatTransport
 } from "@witqq/agent-sdk/chat/backends";
 ```
 
@@ -593,8 +673,8 @@ try {
   await provider.send(message);
 } catch (err) {
   const classified = classifyError(err);
-  if (classified instanceof RateLimitError) {
-    console.log(`Rate limited, retry after ${classified.retryAfterSeconds}s`);
+  if (classified.code === ErrorCode.RATE_LIMIT) {
+    console.log(`Rate limited, retry after ${classified.retryAfter}ms`);
   }
 }
 ```
@@ -626,7 +706,7 @@ bus.use((ctx) => {
   else ctx.next();
 });
 
-bus.on("message_delta", (event) => console.log(event.text));
+bus.on("message:delta", (event) => console.log(event.text));
 ```
 
 ### Storage Adapters
@@ -659,8 +739,8 @@ const session = await store.createSession({
   tags: ["work"],
 });
 
-await store.addMessage(session.id, message);
-const page = await store.getMessages(session.id, { limit: 20, offset: 0 });
+await store.appendMessage(session.id, message);
+const page = await store.loadMessages(session.id, { limit: 20, offset: 0 });
 // page.messages, page.total, page.hasMore
 
 const results = await store.searchSessions({ query: "typescript" });
@@ -698,7 +778,7 @@ const tokens = estimateTokens(message); // ~chars/4
 
 ### Backend Adapters
 
-Backend adapters bridge `IAgentService` to `IChatProvider`, adding session management and resume support:
+Backend adapters bridge `IAgentService` to `IChatBackend`, adding session management and resume support:
 
 ```typescript
 import { CopilotChatAdapter } from "@witqq/agent-sdk/chat/backends";
@@ -725,7 +805,7 @@ if (adapter.canResume()) {
 adapter.dispose();
 ```
 
-`IBackendAdapter` extends `IChatProvider` with `canResume()`, `resume()`, `backendSessionId`, and `agentService` accessor. Built-in adapters: `CopilotChatAdapter`, `ClaudeChatAdapter`, `VercelAIChatAdapter` (stateless, no resume). Create custom adapters by extending `BaseBackendAdapter`.
+`IResumableBackend` extends `IChatBackend` with `canResume()`, `resume()`, and `backendSessionId`. Built-in adapters: `CopilotChatAdapter`, `ClaudeChatAdapter`, `VercelAIChatAdapter` (stateless, no resume). Create custom adapters by extending `BaseBackendAdapter`.
 
 Service ownership: when `agentService` is passed via options, the adapter does **not** dispose it — the caller retains ownership. When omitted, the adapter creates and owns its service internally.
 
@@ -780,12 +860,14 @@ import { createChatRuntime } from "@witqq/agent-sdk/chat/runtime";
 
 const runtime = createChatRuntime({
   backends: {
-    copilot: () => new CopilotChatAdapter({ agentService }),
-    claude: () => new ClaudeChatAdapter({ agentService: claudeService }),
+    copilot: async (credentials) => new CopilotChatAdapter({
+      agentConfig: { systemPrompt: "Hello" },
+      agentService: await createAgentService("copilot", { githubToken: credentials.accessToken }),
+    }),
   },
   defaultBackend: "copilot",
   sessionStore: new InMemorySessionStore(),
-  contextManager: new ContextWindowManager({ maxTokens: 8000 }),
+  context: { maxTokens: 8000 },
 });
 
 // Create session, send message, stream events
@@ -795,20 +877,20 @@ for await (const event of runtime.send(session.id, "Hello")) {
 }
 ```
 
-Key capabilities: session delegation (create/get/list/delete/archive/switch), backend/model switching with `switchBackend(name)` / `switchModel(model)`, tool registration via `addTool(def)` / `removeTool(name)` (persists across switches), middleware pipeline (`use(middleware)`), state machine (`status` property), abort support (`abort()`), pre-stream retry with `RetryConfig`, generic `<TMetadata>` for typed session metadata, and `dispose()`.
+Key capabilities: session delegation (create/get/list/delete), tool registration via `registerTool(def)` / `removeTool(name)` / `registeredTools` (readonly Map, persists across switches), middleware pipeline (`use(middleware)`), state machine (`status` property), abort support (`abort()`), pre-stream retry with `StreamRetryConfig`, session lifecycle events via `onSessionChange(callback)`, generic `<TMetadata>` for typed session metadata, context stats via `getContextStats(sessionId)`, and `dispose()`. Model and backend are passed per-call via `send(sessionId, msg, { model, backend, credentials })`.
 
 Context monitoring:
 
 ```typescript
 // Query context usage after send
 const stats = runtime.getContextStats(session.id);
-// stats: { totalTokens, removedCount, wasTruncated, availableBudget } | null
+// stats: { totalTokens, removedCount, wasTruncated, availableBudget, realPromptTokens?, realCompletionTokens?, modelContextWindow? } | null
 
-// Archive trimmed messages via callback
+// Handle trimmed messages via callback
 const runtime = createChatRuntime({
-  // ...backends, sessionStore, contextManager
+  // ...backends, sessionStore, context
   onContextTrimmed: (sessionId, removedMessages) => {
-    db.archiveMessages(sessionId, removedMessages);
+    db.saveRemovedMessages(sessionId, removedMessages);
   },
 });
 ```
@@ -844,11 +926,11 @@ const handler = createChatServer({
 });
 ```
 
-`createChatHandler` maps all 10 `RemoteChatRuntime` endpoints (session CRUD, send via SSE, abort, models, backend/model switch). `createAuthHandler` handles Copilot Device Flow, Claude OAuth+PKCE, and API key auth with persistent token storage via `ITokenStore`. `corsMiddleware` supports multi-origin configuration.
+`createChatHandler` maps all 10 `RemoteChatClient` endpoints (session CRUD, send via SSE, abort, models, backend/model switch). `createAuthHandler` handles Copilot Device Flow, Claude OAuth+PKCE, and API key auth with persistent token storage via `ITokenStore`. `corsMiddleware` supports multi-origin configuration.
 
 ## Interactive Demo
 
-Single-screen chat UI with inline provider/model selection and auth.
+Complete chat app showcasing the full SDK.
 
 ```bash
 npm run demo              # Build & start in Docker (http://localhost:3456)
@@ -858,7 +940,9 @@ npm run demo -- restart   # Rebuild & restart
 npm run demo -- dev       # Local dev without Docker
 ```
 
-Features: inline provider switching, auth via modal dialog (Copilot Device Flow, Claude OAuth+PKCE, Vercel AI API key), model dropdown with search, SSE streaming chat with thinking blocks, tool calls, and error rendering.
+Features: multi-backend auth (Copilot Device Flow, Claude OAuth+PKCE, Vercel AI API key), provider management, model selection, SSE streaming with thinking blocks, tool calls with approval, token usage display, error handling, session management, SQLite persistence.
+
+Server uses `createChatServer` for zero custom routing with stateless backend factories (credentials per-request). Frontend uses `ChatUI` for zero custom components. See [demo README](examples/demo/README.md) for details.
 
 ## React Bindings
 
@@ -900,12 +984,12 @@ function App() {
 }
 ```
 
-Or use `RemoteChatRuntime` directly for lower-level control:
+Or use `RemoteChatClient` directly for lower-level control:
 
 ```typescript
-import { RemoteChatRuntime } from "@witqq/agent-sdk/chat/react";
+import { RemoteChatClient } from "@witqq/agent-sdk/chat/react";
 
-const runtime = new RemoteChatRuntime({ baseUrl: "/api/chat" });
+const runtime = new RemoteChatClient({ baseUrl: "/api/chat" });
 ```
 
 Reactive session list (replaces manual polling):
@@ -915,7 +999,7 @@ import { useSessions } from "@witqq/agent-sdk/chat/react";
 
 function SessionList() {
   const { sessions, loading } = useSessions();
-  // Auto-updates on create, delete, archive, and message send
+  // Auto-updates on create, delete, and message send
   return sessions.map(s => <div key={s.id}>{s.title}</div>);
 }
 ```
@@ -929,6 +1013,30 @@ const auth = useRemoteAuth({ backend: "copilot", baseUrl: "/api" });
 // auth.startDeviceFlow(), auth.startOAuthFlow(), auth.submitApiKey()
 ```
 
+`ContextStatsDisplay` renders context window usage:
+
+```typescript
+import { ContextStatsDisplay } from "@witqq/agent-sdk/chat/react";
+
+// Headless component rendering context window stats
+// Props: { stats: ContextStats | null }
+// Data attributes: data-context-stats, data-context-tokens, data-context-budget,
+//   data-context-usage, data-context-removed, data-context-truncated
+<ContextStatsDisplay stats={runtime.getContextStats(sessionId)} />
+```
+
+`ThreadList` supports search:
+
+```typescript
+<ThreadList
+  sessions={sessions}
+  onSelect={handleSelect}
+  onDelete={handleDelete}
+  searchQuery={query}                // controlled search input
+  onSearchChange={setQuery}          // search input change handler
+/>
+```
+
 See [Chat SDK docs](docs/chat-sdk/README.md) for the full React API reference.
 
 ## Documentation
@@ -936,11 +1044,9 @@ See [Chat SDK docs](docs/chat-sdk/README.md) for the full React API reference.
 | Document | Description |
 |----------|-------------|
 | [Chat SDK Modules](docs/chat-sdk/README.md) | Module-by-module API docs for chat primitives |
-| [Chat SDK Architecture](docs/chat-sdk/ARCHITECTURE.md) | Architecture specification and design decisions |
 | [Custom Transports](docs/chat-sdk/custom-transports.md) | Guide to building custom IChatTransport implementations |
 | [Custom Renderers](docs/chat-sdk/custom-renderers.md) | Three approaches to customizing React UI components |
-| [Roadmap](docs/architecture/ROADMAP.md) | Module implementation roadmap (M1-M12) |
-| [Project Checklist](PROJECT_CHECKLIST.md) | Implementation checklist with completion status |
+| [Demo App](examples/demo/README.md) | Full-stack demo with architecture and API reference |
 | [Changelog](CHANGELOG.md) | Release history and breaking changes |
 
 ## License

package/dist/{types-CqvUAYxt.d.cts → agent-CW9XbmG_.d.ts}

@@ -1,34 +1,11 @@
 import { z } from 'zod';
-
-/** Pluggable store for persisting permission (scope) decisions across runs. */
-interface IPermissionStore {
-    /** Check if tool is already approved */
-    isApproved(toolName: string): Promise<boolean>;
-    /** Store an approval decision */
-    approve(toolName: string, scope: PermissionScope): Promise<void>;
-    /** Revoke approval for a tool */
-    revoke(toolName: string): Promise<void>;
-    /** Clear all approvals */
-    clear(): Promise<void>;
-    /** Dispose resources */
-    dispose(): Promise<void>;
-}
+import { E as ErrorCode } from './errors-C-so0M4t.js';
 
 /** JSON-serializable value used for tool arguments and results */
 type JSONValue = string | number | boolean | null | JSONValue[] | {
     [key: string]: JSONValue;
 };
-/** Message content — plain string or array of text/image parts */
-type MessageContent = string | Array<ContentPart>;
-/** Individual content part within a multi-part message */
-type ContentPart = {
-    type: "text";
-    text: string;
-} | {
-    type: "image";
-    data: string;
-    mimeType: string;
-};
+
 /** What the LLM sees — name, description, schema. Passed to all backends. */
 interface ToolDeclaration<TParams = unknown> {
     name: string;
@@ -46,7 +23,7 @@ interface ToolDeclaration<TParams = unknown> {
  *  The optional second parameter receives request-scoped context
  *  when invoked through ChatRuntime (session ID, user data, custom metadata). */
 interface ToolDefinition<TParams = unknown> extends ToolDeclaration<TParams> {
-    execute: (params: TParams, context?: ToolContext) => Promise<JSONValue> | JSONValue;
+    execute: (params: TParams, context?: ToolContext) => Promise<unknown> | unknown;
 }
 /** Request-scoped context passed to tool execute functions via ChatRuntime.
  *  Contains session identity and user-defined metadata from the current session. */
@@ -69,6 +46,18 @@ interface ToolResult {
     result: JSONValue;
     isError?: boolean;
 }
+
+/** Message content — plain string or array of text/image parts */
+type MessageContent = string | Array<ContentPart>;
+/** Individual content part within a multi-part message */
+type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
 /** Conversation message — discriminated union on `role` */
 type Message = {
     role: "user";
@@ -85,12 +74,15 @@ type Message = {
     role: "system";
     content: string;
 };
+
 /** Scope for "remember this decision" */
 type PermissionScope = "once" | "session" | "project" | "always";
 /** What the permission callback receives */
 interface PermissionRequest {
     toolName: string;
     toolArgs: Record<string, unknown>;
+    /** Unique identifier for this specific tool call */
+    toolCallId?: string;
     /** SDK-suggested scope (from Claude CLI's suggestions) */
     suggestedScope?: PermissionScope;
     /** Original SDK permission request (for pass-through) */
@@ -128,12 +120,32 @@ interface SupervisorHooks {
     onPermission?: PermissionCallback;
     onAskUser?: (request: UserInputRequest, signal: AbortSignal) => Promise<UserInputResponse>;
 }
-/** Configuration for typed structured output from LLM */
-interface StructuredOutputConfig<T = unknown> {
-    schema: z.ZodType<T>;
+
+/** Model metadata returned by listModels() */
+interface ModelInfo {
+    id: string;
     name?: string;
-    description?: string;
+    provider?: string;
+    /** Model tier for UI categorization and cost hints */
+    tier?: "fast" | "standard" | "premium";
+    /** Context window size in tokens */
+    contextWindow?: number;
+    /** Model capabilities (e.g. "vision", "tools", "structured") */
+    capabilities?: string[];
+}
+/** LLM model parameters */
+interface ModelParams {
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stopSequences?: string[];
+}
+/** Result of backend validation check */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
 }
+
 /** Usage data from LLM execution — tokens consumed plus optional metadata */
 interface UsageData {
     promptTokens: number;
@@ -192,24 +204,78 @@ type AgentEvent = {
     type: "error";
     error: string;
     recoverable: boolean;
+    code?: ErrorCode;
 } | {
     type: "done";
     finalOutput: string | null;
     structuredOutput?: unknown;
+    streamed?: boolean;
 };
-/** Options passed to agent.run() / agent.stream() */
-interface RunOptions {
-    /** AbortSignal for cancellation */
+
+/** Pluggable store for persisting permission (scope) decisions across runs. */
+interface IPermissionStore {
+    /** Check if tool is already approved */
+    isApproved(toolName: string): Promise<boolean>;
+    /** Store an approval decision */
+    approve(toolName: string, scope: PermissionScope): Promise<void>;
+    /** Revoke approval for a tool */
+    revoke(toolName: string): Promise<void>;
+    /** Clear all approvals */
+    clear(): Promise<void>;
+    /** Dispose resources */
+    dispose(): Promise<void>;
+}
+
+/** Per-call overrides passed to run(), stream(), runStructured().
+ *  Allows overriding the model, tools, signal, and other parameters
+ *  on a per-request basis without modifying the agent configuration. */
+interface CallOptions {
+    /** Override the default model for this call */
+    model?: string;
+    /** Override/extend tools for this call */
+    tools?: ToolDefinition[];
+    /** Per-call abort signal */
     signal?: AbortSignal;
+    /** Override system message for this call */
+    systemMessage?: string;
+    /** Provider-specific options passed through to the underlying SDK */
+    providerOptions?: Record<string, unknown>;
+    /** Per-call timeout in milliseconds */
+    timeout?: number;
+    /** Per-call token limit */
+    maxTokens?: number;
+    /** Retry configuration for this call */
+    retry?: RetryConfig;
+}
+/** Configuration for automatic retries on transient errors */
+interface RetryConfig {
+    /** Maximum number of retries (default: 0 — no retry) */
+    maxRetries?: number;
+    /** Initial delay in ms before first retry (default: 1000) */
+    initialDelayMs?: number;
+    /** Backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+    /** Which error codes to retry (default: all recoverable codes) */
+    retryableErrors?: ErrorCode[];
+}
+/** Configuration for typed structured output from LLM */
+interface StructuredOutputConfig<T = unknown> {
+    schema: z.ZodType<T>;
+    name?: string;
+    description?: string;
+}
+/** Options passed to agent.run() / agent.stream().
+ *  Extends CallOptions with run-specific fields (context, activityTimeoutMs).
+ *  model is REQUIRED — every agent call must specify the model explicitly. */
+interface RunOptions extends CallOptions {
+    /** Model to use for this call (required — no implicit defaults) */
+    model: string;
     /** Arbitrary context passed to the agent run */
     context?: Record<string, unknown>;
-}
-/** LLM model parameters */
-interface ModelParams {
-    temperature?: number;
-    maxTokens?: number;
-    topP?: number;
-    stopSequences?: string[];
+    /** Inactivity timeout for streaming (ms). When set, the stream aborts if no
+     *  event (including heartbeats/progress) arrives within this period. Resets on
+     *  every received event. Default: no timeout. Only affects stream()/streamWithContext(). */
+    activityTimeoutMs?: number;
 }
 /** Timeout configuration for agent operations */
 interface TimeoutConfig {
@@ -234,12 +300,10 @@ interface ErrorHandlingConfig {
         phase: "tool" | "llm" | "permission" | "ask-user";
     }) => void;
 }
-/** Configuration for creating an agent */
+/** Identity-only agent configuration — defines the agent's behavior, NOT per-call defaults.
+ *  For creating an agent with model/tools defaults, use FullAgentConfig. */
 interface AgentConfig {
-    model?: string;
-    modelParams?: ModelParams;
     systemPrompt: string;
-    tools: ToolDefinition[];
     supervisor?: SupervisorHooks;
     maxTurns?: number;
     timeout?: TimeoutConfig;
@@ -249,8 +313,14 @@ interface AgentConfig {
     /** How to apply systemPrompt: "append" adds to backend default, "replace" overrides it.
      *  Default: "append". Currently used by the Copilot backend. */
     systemMessageMode?: "append" | "replace";
-    /** Filter for backend built-in tools (e.g. ["web_search", "web_fetch"] for Copilot).
-     *  When set, only listed built-in tools are available. Backend-specific. */
+    /**
+     * Filter for backend built-in tools (e.g. `["web_search", "web_fetch"]` for Copilot).
+     * When set, only listed built-in tools are available. Backend-specific.
+     *
+     * **Security note**: This is a trust boundary — it controls which backend-native tools
+     * the AI agent can invoke. By default, backends expose ALL their built-in tools.
+     * Set this to restrict access (e.g. prevent file system access in a web-facing agent).
+     */
     availableTools?: string[];
     /** Callback invoked with usage data after run completion or during streaming.
      *  Fire-and-forget: errors are logged but not propagated. */
@@ -264,11 +334,24 @@ interface AgentConfig {
      *  "persistent": reuses the same CLI session across calls, preserving conversation
      *  history natively in the CLI backend. Session is destroyed on agent dispose(). */
     sessionMode?: "per-call" | "persistent";
+}
+/** Per-call defaults that can be provided at agent creation time.
+ *  Each field can also be overridden on individual calls via RunOptions. */
+interface CallDefaults {
+    /** Default model (overridable per-call via RunOptions.model) */
+    model?: string;
+    /** Default model parameters */
+    modelParams?: ModelParams;
+    /** Default tools (overridable per-call via RunOptions.tools) */
+    tools?: ToolDefinition[];
     /** Provider-specific options passed through to the underlying SDK.
      *  For Vercel AI: passed as providerOptions to generateText/streamText.
      *  Example: { google: { thinkingConfig: { thinkingBudget: 1024 } } } */
     providerOptions?: Record<string, Record<string, unknown>>;
 }
+/** Full agent configuration: identity + per-call defaults.
+ *  This is what createAgent() accepts. Backward-compatible with the old AgentConfig shape. */
+type FullAgentConfig = AgentConfig & CallDefaults;
 /** Result of an agent run, generic over structured output type T */
 interface AgentResult<T = void> {
     output: string | null;
@@ -290,15 +373,15 @@ interface IAgent {
      *  or before the first call. Can be stored externally for session resume. */
     readonly sessionId: string | undefined;
     /** Run a single prompt and return the result. Wraps prompt in a user message. */
-    run(prompt: MessageContent, options?: RunOptions): Promise<AgentResult>;
+    run(prompt: MessageContent, options: RunOptions): Promise<AgentResult>;
     /** Run with full conversation history. Messages are passed directly to the backend. */
-    runWithContext(messages: Message[], options?: RunOptions): Promise<AgentResult>;
+    runWithContext(messages: Message[], options: RunOptions): Promise<AgentResult>;
     /** Run with structured output validated against a Zod schema. */
-    runStructured<T>(prompt: MessageContent, schema: StructuredOutputConfig<T>, options?: RunOptions): Promise<AgentResult<T>>;
+    runStructured<T>(prompt: MessageContent, schema: StructuredOutputConfig<T>, options: RunOptions): Promise<AgentResult<T>>;
     /** Stream events for a single prompt. Wraps prompt in a user message. */
-    stream(prompt: MessageContent, options?: RunOptions): AsyncIterable<AgentEvent>;
+    stream(prompt: MessageContent, options: RunOptions): AsyncIterable<AgentEvent>;
     /** Stream events with full conversation history. Messages are passed directly to the backend. */
-    streamWithContext(messages: Message[], options?: RunOptions): AsyncIterable<AgentEvent>;
+    streamWithContext(messages: Message[], options: RunOptions): AsyncIterable<AgentEvent>;
     /** Abort the current operation. No-op if not running. */
     abort(): void;
     /** Gracefully interrupt the current operation. Resolves when the backend acknowledges. */
@@ -306,65 +389,17 @@ interface IAgent {
     /** Get current agent lifecycle state. */
     getState(): AgentState;
     /** Get frozen agent configuration. */
-    getConfig(): Readonly<AgentConfig>;
+    getConfig(): Readonly<FullAgentConfig>;
     /** Release resources. After dispose(), agent must not be used. */
     dispose(): void;
 }
-/** Model metadata returned by listModels() */
-interface ModelInfo {
-    id: string;
-    name?: string;
-    provider?: string;
-}
-/** Result of backend validation check */
-interface ValidationResult {
-    valid: boolean;
-    errors: string[];
-}
 /** Backend service interface — creates agents, lists models, validates config */
 interface IAgentService {
     readonly name: string;
-    createAgent(config: AgentConfig): IAgent;
+    createAgent(config: FullAgentConfig): IAgent;
     listModels(): Promise<ModelInfo[]>;
     validate(): Promise<ValidationResult>;
     dispose(): Promise<void>;
 }
-/** Options for Copilot CLI backend */
-interface CopilotBackendOptions {
-    cliPath?: string;
-    workingDirectory?: string;
-    githubToken?: string;
-    useLoggedInUser?: boolean;
-    /** Extra CLI arguments passed to the Copilot subprocess (e.g. ["--allow-all"]) */
-    cliArgs?: string[];
-    /** Timeout in milliseconds for sendAndWait() calls. When undefined, uses copilot-sdk default (60s). */
-    timeout?: number;
-    /** Timeout in milliseconds for CLI startup and auth check (default: 30000). */
-    startupTimeoutMs?: number;
-    /** Custom environment variables merged into the subprocess env */
-    env?: Record<string, string | undefined>;
-    /** Session ID to resume after server restart. On startup, the backend attempts
-     *  to resume this session before creating a new one. */
-    resumeSessionId?: string;
-}
-/** Options for Claude CLI backend */
-interface ClaudeBackendOptions {
-    cliPath?: string;
-    workingDirectory?: string;
-    maxTurns?: number;
-    /** OAuth token for Claude authentication (set as CLAUDE_CODE_OAUTH_TOKEN env var) */
-    oauthToken?: string;
-    /** Custom environment variables merged into the subprocess env */
-    env?: Record<string, string | undefined>;
-    /** Session ID to resume after server restart. On startup, the backend attempts
-     *  to resume this session before creating a new one. */
-    resumeSessionId?: string;
-}
-/** Options for Vercel AI SDK backend */
-interface VercelAIBackendOptions {
-    apiKey: string;
-    provider?: string;
-    baseUrl?: string;
-}
 
-export type { AgentEvent as A, CopilotBackendOptions as C, IAgentService as I, Message as M, ToolDefinition as T, UsageData as U, VercelAIBackendOptions as V, ClaudeBackendOptions as a, IAgent as b, AgentConfig as c, ModelInfo as d, ToolResult as e };
+export type { AgentEvent as A, FullAgentConfig as F, IAgentService as I, ModelInfo as M, RunOptions as R, ToolDefinition as T, UsageData as U, ValidationResult as V, MessageContent as a, AgentResult as b, IAgent as c, Message as d, ToolResult as e };