ai-sdk-provider-codex-cli 1.0.4 → 1.1.0

package/dist/index.d.ts

@@ -1,265 +1,727 @@
-import { ProviderV3, LanguageModelV3 } from '@ai-sdk/provider';
+import { ProviderV3, LanguageModelV3, UnsupportedFunctionalityError } from '@ai-sdk/provider';
+import { ZodType } from 'zod';
 
 /**
  * Logger interface for custom logging.
- * Allows consumers to provide their own logging implementation
- * or disable logging entirely.
- *
- * @example
- * ```typescript
- * const customLogger: Logger = {
- *   debug: (message) => myLoggingService.debug(message),
- *   info: (message) => myLoggingService.info(message),
- *   warn: (message) => myLoggingService.warn(message),
- *   error: (message) => myLoggingService.error(message),
- * };
- * ```
  */
 interface Logger {
-    /**
-     * Log a debug message. Only logged when verbose mode is enabled.
-     * Used for detailed execution tracing and troubleshooting.
-     */
     debug: (message: string) => void;
-    /**
-     * Log an informational message. Only logged when verbose mode is enabled.
-     * Used for general execution flow information.
-     */
     info: (message: string) => void;
-    /**
-     * Log a warning message.
-     */
     warn: (message: string) => void;
-    /**
-     * Log an error message.
-     */
     error: (message: string) => void;
 }
+/**
+ * Known Codex-capable model IDs with string fallback for forward compatibility.
+ */
+type CodexModelId = 'gpt-5.3-codex' | 'gpt-5.2-codex' | 'gpt-5.2-codex-max' | 'gpt-5.2-codex-mini' | 'gpt-5.1' | 'gpt-5.2' | (string & {});
 type ApprovalMode = 'untrusted' | 'on-failure' | 'on-request' | 'never';
 type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
 type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 /**
- * Reasoning summary detail level.
- * Note: The API error messages claim 'concise' and 'none' are valid, but they are
- * actually rejected with 400 errors. Only 'auto' and 'detailed' work in practice.
+ * Reasoning summary detail level for exec mode.
  */
 type ReasoningSummary = 'auto' | 'detailed';
 type ReasoningSummaryFormat = 'none' | 'experimental';
 type ModelVerbosity = 'low' | 'medium' | 'high';
 interface McpServerBase {
-    /**
-     * Enable/disable this MCP server without removing its definition.
-     * Maps to: `mcp_servers.<name>.enabled`
-     */
     enabled?: boolean;
-    /**
-     * Time allowed for the MCP server to start (in seconds).
-     * Maps to: `mcp_servers.<name>.startup_timeout_sec`
-     */
     startupTimeoutSec?: number;
-    /**
-     * Max time a single MCP tool call may run (in seconds).
-     * Maps to: `mcp_servers.<name>.tool_timeout_sec`
-     */
     toolTimeoutSec?: number;
-    /**
-     * Explicit allow/deny lists for tools exposed by the server.
-     * Maps to: `mcp_servers.<name>.enabled_tools` / `disabled_tools`
-     */
     enabledTools?: string[];
     disabledTools?: string[];
 }
 interface McpServerStdio extends McpServerBase {
-    /** Execute an MCP server over stdio */
     transport: 'stdio';
-    /** Command to start the MCP server (e.g., `node`, `python`, or a binary path). */
     command: string;
-    /** Arguments passed to the command. */
     args?: string[];
-    /** Environment variables passed to the MCP process. */
     env?: Record<string, string>;
-    /** Optional working directory for the MCP server process. */
     cwd?: string;
 }
 interface McpServerHttp extends McpServerBase {
-    /** Use an HTTP-based MCP server (RMCP). */
     transport: 'http';
-    /** Base URL for the MCP server. */
     url: string;
-    /** Bearer token supplied inline (use env var variant to avoid embedding secrets). */
     bearerToken?: string;
-    /** Name of env var that holds the bearer token. */
     bearerTokenEnvVar?: string;
-    /** Static HTTP headers to send with each MCP request. */
     httpHeaders?: Record<string, string>;
-    /** Names of env vars whose values should be sent as HTTP headers. */
     envHttpHeaders?: Record<string, string>;
 }
 type McpServerConfig = McpServerStdio | McpServerHttp;
-interface CodexCliSettings {
-    codexPath?: string;
+type CodexConfigOverrideValue = string | number | boolean | object;
+interface CodexSharedSettings {
     cwd?: string;
-    addDirs?: string[];
     approvalMode?: ApprovalMode;
     sandboxMode?: SandboxMode;
-    fullAuto?: boolean;
-    dangerouslyBypassApprovalsAndSandbox?: boolean;
-    skipGitRepoCheck?: boolean;
-    color?: 'always' | 'never' | 'auto';
-    allowNpx?: boolean;
-    outputLastMessageFile?: string;
     env?: Record<string, string>;
     verbose?: boolean;
     logger?: Logger | false;
-    /**
-     * Controls reasoning effort for reasoning-capable models (o3, o4-mini, the GPT-5.1 family,
-     * and legacy GPT-5 slugs). Higher effort produces more thorough reasoning at the cost of latency.
-     *
-     * Codex CLI model presets currently expose `low`/`medium`/`high` for `gpt-5.1` and `gpt-5.1-codex`.
-     * Per OpenAI API docs, GPT‑5.1+ models support a `none` level (no extra reasoning); older GPT‑5 slugs used `minimal` instead.
-     * `gpt-5.1-codex-max` additionally supports `xhigh`. `gpt-5.1-codex-mini` only offers `medium`/`high`.
-     *
-     * Maps to: `-c model_reasoning_effort=<value>`
-     * @see https://platform.openai.com/docs/guides/reasoning
-     */
     reasoningEffort?: ReasoningEffort;
-    /**
-     * Controls reasoning summary detail level.
-     *
-     * Valid values: 'auto' | 'detailed'
-     * Note: Despite API error messages claiming 'concise' and 'none' are valid,
-     * they are rejected with 400 errors in practice.
-     *
-     * Maps to: `-c model_reasoning_summary=<value>`
-     * @see https://platform.openai.com/docs/guides/reasoning#reasoning-summaries
-     */
     reasoningSummary?: ReasoningSummary;
-    /**
-     * Controls reasoning summary format (experimental).
-     *
-     * Maps to: `-c model_reasoning_summary_format=<value>`
-     */
     reasoningSummaryFormat?: ReasoningSummaryFormat;
-    /**
-     * Controls output length/detail for GPT-5.1 (non-Codex) and legacy GPT-5 models.
-     * Codex-specific slugs ignore this flag because the CLI disables verbosity for them.
-     * Only applies to models using the Responses API.
-     *
-     * Maps to: `-c model_verbosity=<value>`
-     */
     modelVerbosity?: ModelVerbosity;
-    /**
-     * Configure MCP servers (stdio or HTTP/RMCP). Keys are server names.
-     * Each entry maps to the Codex CLI `mcp_servers.<name>` table.
-     */
     mcpServers?: Record<string, McpServerConfig>;
-    /**
-     * Enable the RMCP client so HTTP-based MCP servers can be contacted.
-     * Maps to: `-c features.rmcp_client=true`
-     */
     rmcpClient?: boolean;
-    /**
-     * Configuration profile from config.toml to specify default options.
-     *
-     * Maps to: `--profile <name>`
-     */
+    configOverrides?: Record<string, CodexConfigOverrideValue>;
+}
+interface CodexSharedProviderOptions {
+    reasoningEffort?: ReasoningEffort;
+    reasoningSummary?: ReasoningSummary;
+    reasoningSummaryFormat?: ReasoningSummaryFormat;
+    textVerbosity?: ModelVerbosity;
+    mcpServers?: Record<string, McpServerConfig>;
+    rmcpClient?: boolean;
+    configOverrides?: Record<string, CodexConfigOverrideValue>;
+}
+
+interface CodexExecSettings extends CodexSharedSettings {
+    codexPath?: string;
+    addDirs?: string[];
+    fullAuto?: boolean;
+    dangerouslyBypassApprovalsAndSandbox?: boolean;
+    skipGitRepoCheck?: boolean;
+    color?: 'always' | 'never' | 'auto';
+    allowNpx?: boolean;
+    outputLastMessageFile?: string;
     profile?: string;
-    /**
-     * Use OSS provider (experimental).
-     *
-     * Maps to: `--oss`
-     */
     oss?: boolean;
-    /**
-     * Enable web search tool for the model.
-     *
-     * Maps to: `-c tools.web_search=true`
-     */
     webSearch?: boolean;
-    /**
-     * Generic Codex CLI config overrides. Allows setting any config value
-     * without updating the provider.
-     *
-     * Each entry maps to: `-c <key>=<value>`
-     *
-     * Examples:
-     * - `{ experimental_resume: '/tmp/session.jsonl' }`
-     * - `{ 'model_providers.custom.base_url': 'http://localhost:8000' }`
-     * - `{ 'sandbox_workspace_write': { network_access: true } }`
-     *
-     * Values are serialized:
-     * - string → raw string
-     * - number/boolean → String(value)
-     * - plain objects → flattened recursively to dotted keys
-     * - arrays → JSON.stringify(value)
-     * - other objects (Date, RegExp, Map, etc.) → JSON.stringify(value)
-     */
-    configOverrides?: Record<string, string | number | boolean | object>;
+    configOverrides?: Record<string, CodexConfigOverrideValue>;
 }
-interface CodexCliProviderSettings {
-    defaultSettings?: CodexCliSettings;
+interface CodexExecProviderSettings {
+    defaultSettings?: CodexExecSettings;
 }
 /**
  * Per-call overrides supplied through AI SDK providerOptions.
- * These values take precedence over constructor-level CodexCliSettings.
  */
-interface CodexCliProviderOptions {
-    /**
-     * Per-call override for reasoning depth.
-     * Maps to `model_reasoning_effort`.
-     */
-    reasoningEffort?: ReasoningEffort;
-    /**
-     * Per-call override for reasoning summary detail level.
-     * Maps to `model_reasoning_summary`.
-     */
-    reasoningSummary?: ReasoningSummary;
-    /**
-     * Per-call override for reasoning summary format.
-     * Maps to `model_reasoning_summary_format`.
-     */
-    reasoningSummaryFormat?: ReasoningSummaryFormat;
-    /**
-     * AI SDK naming for per-call verbosity overrides.
-     * Maps to Codex `model_verbosity`.
-     */
-    textVerbosity?: ModelVerbosity;
-    /**
-     * Per-call override for extra directories Codex can access.
-     * Maps to repeated `--add-dir` flags.
-     */
+interface CodexExecProviderOptions extends CodexSharedProviderOptions {
     addDirs?: string[];
+}
+type CodexCliSettings = CodexExecSettings;
+type CodexCliProviderSettings = CodexExecProviderSettings;
+type CodexCliProviderOptions = CodexExecProviderOptions;
+
+type JsonRpcId = number | string;
+interface JsonRpcRequest {
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcResponse<T = unknown> {
+    id: JsonRpcId;
+    result: T;
+}
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface JsonRpcErrorResponse {
+    id: JsonRpcId | null;
+    error: JsonRpcError;
+}
+interface JsonRpcNotification {
+    method: string;
+    params?: Record<string, unknown>;
+}
+type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcErrorResponse | JsonRpcNotification;
+interface ModelInfo {
+    id: string;
+    name?: string | null;
+    modelProvider?: string | null;
+    description?: string | null;
+    isDefault?: boolean | null;
+    [k: string]: unknown;
+}
+interface Thread {
+    id: string;
+    preview?: string;
+    modelProvider?: string;
+    createdAt?: number;
+    [k: string]: unknown;
+}
+interface ThreadStartParams {
+    model?: string | null;
+    modelProvider?: string | null;
+    cwd?: string | null;
+    approvalPolicy?: unknown;
+    sandbox?: unknown;
+    config?: Record<string, unknown> | null;
+    baseInstructions?: string | null;
+    developerInstructions?: string | null;
+    personality?: 'none' | 'friendly' | 'pragmatic' | null;
+    ephemeral?: boolean | null;
+    experimentalRawEvents: boolean;
+    persistExtendedHistory: boolean;
+}
+interface ThreadStartResponse {
+    thread: Thread;
+    model: string;
+    modelProvider: string;
+    cwd: string;
+    approvalPolicy: unknown;
+    sandbox: unknown;
+    reasoningEffort: string | null;
+}
+interface ThreadResumeParams {
+    threadId: string;
+    history?: unknown[] | null;
+    path?: string | null;
+    model?: string | null;
+    modelProvider?: string | null;
+    cwd?: string | null;
+    approvalPolicy?: unknown;
+    sandbox?: unknown;
+    config?: Record<string, unknown> | null;
+    baseInstructions?: string | null;
+    developerInstructions?: string | null;
+    personality?: 'none' | 'friendly' | 'pragmatic' | null;
+    persistExtendedHistory: boolean;
+}
+type ThreadResumeResponse = ThreadStartResponse;
+type UserInput = {
+    type: 'text';
+    text: string;
+    text_elements: unknown[];
+} | {
+    type: 'image';
+    url?: string;
+    imageUrl?: string;
+} | {
+    type: 'localImage';
+    path: string;
+} | {
+    type: 'skill';
+    name: string;
+    path: string;
+} | {
+    type: 'mention';
+    name: string;
+    path: string;
+};
+interface TurnStartParams {
+    threadId: string;
+    input: UserInput[];
+    cwd?: string | null;
+    approvalPolicy?: unknown;
+    sandboxPolicy?: unknown;
+    model?: string | null;
+    effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | null;
+    summary?: 'auto' | 'concise' | 'detailed' | 'none' | null;
+    personality?: 'none' | 'friendly' | 'pragmatic' | null;
+    outputSchema?: unknown;
+    collaborationMode?: unknown;
+}
+type CodexErrorInfo = 'contextWindowExceeded' | 'usageLimitExceeded' | 'serverOverloaded' | 'internalServerError' | 'unauthorized' | 'badRequest' | 'threadRollbackFailed' | 'sandboxError' | 'other' | {
+    httpConnectionFailed: {
+        httpStatusCode: number | null;
+    };
+} | {
+    responseStreamConnectionFailed: {
+        httpStatusCode: number | null;
+    };
+} | {
+    responseStreamDisconnected: {
+        httpStatusCode: number | null;
+    };
+} | {
+    responseTooManyFailedAttempts: {
+        httpStatusCode: number | null;
+    };
+};
+interface TurnError {
+    message: string;
+    codexErrorInfo: CodexErrorInfo | null;
+    additionalDetails: string | null;
+}
+type TurnStatus = 'completed' | 'interrupted' | 'failed' | 'inProgress';
+type UserMessageItem = {
+    type: 'userMessage';
+    id: string;
+    content: UserInput[];
+};
+type AgentMessageItem = {
+    type: 'agentMessage';
+    id: string;
+    text: string;
+    phase: string | null;
+};
+type PlanItem = {
+    type: 'plan';
+    id: string;
+    text: string;
+};
+type ReasoningItem = {
+    type: 'reasoning';
+    id: string;
+    summary: string[];
+    content: string[];
+};
+type CommandExecutionItem = {
+    type: 'commandExecution';
+    id: string;
+    command: string;
+    cwd: string;
+    processId: string | null;
+    status: string;
+    commandActions: unknown[];
+    aggregatedOutput: string | null;
+    exitCode: number | null;
+    durationMs: number | null;
+};
+type FileChangeItem = {
+    type: 'fileChange';
+    id: string;
+    changes: unknown[];
+    status: string;
+};
+type McpToolCallItem = {
+    type: 'mcpToolCall';
+    id: string;
+    server: string;
+    tool: string;
+    status: string;
+    arguments: unknown;
+    result: unknown | null;
+    error: unknown | null;
+    durationMs: number | null;
+};
+type CollabAgentToolCallItem = {
+    type: 'collabAgentToolCall';
+    id: string;
+    tool: string;
+    status: string;
+    senderThreadId: string;
+    receiverThreadIds: string[];
+    prompt: string | null;
+    agentsStates: Record<string, unknown>;
+};
+type WebSearchItem = {
+    type: 'webSearch';
+    id: string;
+    query: string;
+    action: unknown | null;
+};
+type ImageViewItem = {
+    type: 'imageView';
+    id: string;
+    path: string;
+};
+type EnteredReviewModeItem = {
+    type: 'enteredReviewMode';
+    id: string;
+    review: string;
+};
+type ExitedReviewModeItem = {
+    type: 'exitedReviewMode';
+    id: string;
+    review: string;
+};
+type ContextCompactionItem = {
+    type: 'contextCompaction';
+    id: string;
+};
+type ThreadItem = UserMessageItem | AgentMessageItem | PlanItem | ReasoningItem | CommandExecutionItem | FileChangeItem | McpToolCallItem | CollabAgentToolCallItem | WebSearchItem | ImageViewItem | EnteredReviewModeItem | ExitedReviewModeItem | ContextCompactionItem;
+interface Turn {
+    id: string;
+    items: ThreadItem[];
+    status: TurnStatus;
+    error: TurnError | null;
+}
+interface TurnStartResponse {
+    turn: Turn;
+}
+interface TurnInterruptParams {
+    threadId: string;
+    turnId: string;
+}
+type TurnInterruptResponse = Record<string, never>;
+interface ThreadStartedNotification {
+    thread: Thread;
+}
+interface TurnStartedNotification {
+    threadId: string;
+    turn: Turn;
+}
+interface TurnCompletedNotification {
+    threadId: string;
+    turn: Turn;
+}
+interface ItemStartedNotification {
+    item: ThreadItem;
+    threadId: string;
+    turnId: string;
+}
+interface ItemCompletedNotification {
+    item: ThreadItem;
+    threadId: string;
+    turnId: string;
+}
+interface ErrorNotification {
+    error: TurnError;
+    willRetry: boolean;
+    threadId: string;
+    turnId: string;
+    [k: string]: unknown;
+}
+interface CommandExecutionRequestApprovalParams {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    approvalId?: string | null;
+    reason?: string | null;
+    networkApprovalContext?: unknown | null;
+    command?: string | null;
+    cwd?: string | null;
+    commandActions?: unknown[] | null;
+    proposedExecpolicyAmendment?: unknown | null;
+}
+interface CommandExecutionRequestApprovalResponse {
+    decision: 'accept' | 'acceptForSession' | 'decline' | 'cancel' | {
+        acceptWithExecpolicyAmendment: {
+            execpolicy_amendment: unknown;
+        };
+    };
+}
+interface FileChangeRequestApprovalParams {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    reason?: string | null;
+    grantRoot?: string | null;
+}
+interface FileChangeRequestApprovalResponse {
+    decision: 'accept' | 'acceptForSession' | 'decline' | 'cancel';
+}
+interface SkillRequestApprovalParams {
+    itemId: string;
+    skillName: string;
+}
+interface SkillRequestApprovalResponse {
+    decision: 'approve' | 'decline';
+}
+interface ToolRequestUserInputParams {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    questions: unknown[];
+}
+interface ToolRequestUserInputResponse {
+    answers: Record<string, unknown>;
+}
+interface DynamicToolCallParams {
+    threadId: string;
+    turnId: string;
+    callId: string;
+    tool: string;
+    arguments: unknown;
+}
+interface DynamicToolCallResponse {
+    contentItems: unknown[];
+    success: boolean;
+}
+interface ChatgptAuthTokensRefreshParams {
+    reason: string;
+    previousAccountId?: string | null;
+}
+interface ChatgptAuthTokensRefreshResponse {
+    accessToken: string;
+    chatgptAccountId: string;
+    chatgptPlanType: string | null;
+}
+
+interface LocalToolDefinition<TParams = unknown, TResult = unknown> {
+    name: string;
+    description: string;
+    parameters: ZodType<TParams>;
+    execute: (params: TParams) => Promise<TResult>;
+}
+interface LocalTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (params: unknown) => Promise<unknown>;
+}
+declare function tool<TParams, TResult>(definition: LocalToolDefinition<TParams, TResult>): LocalTool;
+
+interface LocalMcpServerOptions {
+    name: string;
+    tools: LocalTool[];
+    port?: number;
+    host?: string;
+    allowNonLoopbackHost?: boolean;
+}
+interface LocalMcpServer {
+    config: McpServerHttp;
+    url: string;
+    port: number;
+    stop: () => Promise<void>;
+}
+declare function createLocalMcpServer(options: LocalMcpServerOptions): Promise<LocalMcpServer>;
+
+declare const SDK_MCP_SERVER_MARKER: unique symbol;
+interface SdkMcpServer {
+    readonly [SDK_MCP_SERVER_MARKER]: true;
+    readonly name: string;
+    readonly cacheKey?: string;
+    readonly tools: LocalTool[];
+    _server?: LocalMcpServer;
+    _start(): Promise<LocalMcpServer['config']>;
+    _stop(): Promise<void>;
+}
+interface SdkMcpServerOptions {
+    name: string;
+    cacheKey?: string;
+    tools: LocalTool[];
+}
+declare function createSdkMcpServer(options: SdkMcpServerOptions): SdkMcpServer;
+
+type AppServerThreadMode = 'stateless' | 'persistent';
+type AppServerPersonality = 'none' | 'friendly' | 'pragmatic';
+type AppServerReasoningSummary = 'auto' | 'concise' | 'detailed' | 'none';
+type AppServerApprovalPolicy = 'untrusted' | 'on-failure' | 'on-request' | 'never' | {
+    reject: {
+        sandbox_approval: boolean;
+        rules: boolean;
+        mcp_elicitations: boolean;
+    };
+};
+type AppServerSandboxPolicy = 'read-only' | 'workspace-write' | 'danger-full-access' | {
+    type: 'dangerFullAccess';
+} | {
+    type: 'readOnly';
+    access?: unknown;
+} | {
+    type: 'externalSandbox';
+    networkAccess?: 'restricted' | 'enabled';
+} | {
+    type: 'workspaceWrite';
+    writableRoots?: string[];
+    readOnlyAccess?: unknown;
+    networkAccess?: boolean;
+    excludeTmpdirEnvVar?: boolean;
+    excludeSlashTmp?: boolean;
+};
+type AppServerUserInput = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    imageUrl: string;
+} | {
+    type: 'localImage';
+    path: string;
+};
+/**
+ * Live session handle for an active app-server thread.
+ *
+ * Session callbacks are most useful in streaming flows where you can inject
+ * follow-up instructions while a turn is still running.
+ */
+interface CodexAppServerSession {
+    readonly threadId: string;
+    readonly turnId: string | null;
     /**
-     * Per-call Codex CLI config overrides. These are merged with
-     * constructor-level overrides with per-call values taking precedence.
+     * Injects an additional user message into the current thread.
      */
-    configOverrides?: Record<string, string | number | boolean | object>;
+    injectMessage(content: string | AppServerUserInput[]): Promise<void>;
     /**
-     * Per-call MCP server definitions. Merged with constructor definitions
-     * (per-call servers and fields take precedence).
+     * Requests interruption of the currently running turn.
      */
-    mcpServers?: Record<string, McpServerConfig>;
+    interrupt(): Promise<void>;
     /**
-     * Per-call override for RMCP client enablement.
+     * Returns whether this session currently has an active turn.
      */
+    isActive(): boolean;
+}
+interface AppServerCommandExecutionApprovalRequest {
+    id: JsonRpcId;
+    method: 'item/commandExecution/requestApproval';
+    params: CommandExecutionRequestApprovalParams;
+}
+interface AppServerFileChangeApprovalRequest {
+    id: JsonRpcId;
+    method: 'item/fileChange/requestApproval';
+    params: FileChangeRequestApprovalParams;
+}
+interface AppServerSkillApprovalRequest {
+    id: JsonRpcId;
+    method: 'skill/requestApproval';
+    params: SkillRequestApprovalParams;
+}
+interface AppServerToolRequestUserInputRequest {
+    id: JsonRpcId;
+    method: 'item/tool/requestUserInput';
+    params: ToolRequestUserInputParams;
+}
+interface AppServerDynamicToolCallRequest {
+    id: JsonRpcId;
+    method: 'item/tool/call';
+    params: DynamicToolCallParams;
+}
+interface AppServerAuthRefreshRequest {
+    id: JsonRpcId;
+    method: 'account/chatgptAuthTokens/refresh';
+    params: ChatgptAuthTokensRefreshParams;
+}
+interface AppServerUnhandledRequest {
+    id: JsonRpcId;
+    method: string;
+    params: Record<string, unknown>;
+}
+/**
+ * Typed handlers for server-initiated JSON-RPC requests.
+ *
+ * Handler precedence:
+ * 1) per-call provider options
+ * 2) provider default settings
+ * 3) built-in defaults in the RPC client
+ * 4) `onUnhandled` fallback
+ */
+interface CodexAppServerRequestHandlers {
+    onCommandExecutionApproval?: (request: AppServerCommandExecutionApprovalRequest) => Promise<CommandExecutionRequestApprovalResponse | undefined>;
+    onFileChangeApproval?: (request: AppServerFileChangeApprovalRequest) => Promise<FileChangeRequestApprovalResponse | undefined>;
+    onSkillApproval?: (request: AppServerSkillApprovalRequest) => Promise<SkillRequestApprovalResponse | undefined>;
+    onToolRequestUserInput?: (request: AppServerToolRequestUserInputRequest) => Promise<ToolRequestUserInputResponse | undefined>;
+    onDynamicToolCall?: (request: AppServerDynamicToolCallRequest) => Promise<DynamicToolCallResponse | undefined>;
+    onAuthRefresh?: (request: AppServerAuthRefreshRequest) => Promise<ChatgptAuthTokensRefreshResponse | undefined>;
+    onUnhandled?: (request: AppServerUnhandledRequest) => Promise<unknown>;
+}
+type AppServerMcpServerConfig = McpServerConfig | SdkMcpServer;
+/**
+ * Provider-level and model-level settings for Codex app-server mode.
+ */
+interface CodexAppServerSettings {
+    codexPath?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    verbose?: boolean;
+    logger?: Logger | false;
+    personality?: AppServerPersonality;
+    effort?: ReasoningEffort;
+    summary?: AppServerReasoningSummary;
+    approvalPolicy?: AppServerApprovalPolicy;
+    sandboxPolicy?: AppServerSandboxPolicy;
+    baseInstructions?: string;
+    developerInstructions?: string;
+    mcpServers?: Record<string, AppServerMcpServerConfig>;
     rmcpClient?: boolean;
+    configOverrides?: Record<string, CodexConfigOverrideValue>;
+    autoApprove?: boolean;
+    persistExtendedHistory?: boolean;
+    connectionTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    idleTimeoutMs?: number;
+    minCodexVersion?: string;
+    threadMode?: AppServerThreadMode;
+    resume?: string;
+    includeRawChunks?: boolean;
+    serverRequests?: CodexAppServerRequestHandlers;
+    onSessionCreated?: (session: CodexAppServerSession) => void | Promise<void>;
+}
+/**
+ * Factory options passed to `createCodexAppServer`.
+ */
+interface CodexAppServerProviderSettings {
+    defaultSettings?: CodexAppServerSettings;
+}
+/**
+ * Per-request overrides passed via `providerOptions['codex-app-server']`.
+ */
+interface CodexAppServerProviderOptions {
+    threadId?: string;
+    resume?: string;
+    threadMode?: AppServerThreadMode;
+    includeRawChunks?: boolean;
+    personality?: AppServerPersonality;
+    effort?: ReasoningEffort;
+    summary?: AppServerReasoningSummary;
+    approvalPolicy?: AppServerApprovalPolicy;
+    sandboxPolicy?: AppServerSandboxPolicy;
+    baseInstructions?: string;
+    developerInstructions?: string;
+    mcpServers?: Record<string, AppServerMcpServerConfig>;
+    rmcpClient?: boolean;
+    configOverrides?: Record<string, CodexConfigOverrideValue>;
+    autoApprove?: boolean;
+    persistExtendedHistory?: boolean;
+    serverRequests?: Partial<CodexAppServerRequestHandlers>;
+    onSessionCreated?: (session: CodexAppServerSession) => void | Promise<void>;
 }
 
-interface CodexCliProvider extends ProviderV3 {
-    (modelId: string, settings?: CodexCliSettings): LanguageModelV3;
-    languageModel(modelId: string, settings?: CodexCliSettings): LanguageModelV3;
-    chat(modelId: string, settings?: CodexCliSettings): LanguageModelV3;
+interface CodexExecProvider extends ProviderV3 {
+    (modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV3;
+    languageModel(modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV3;
+    chat(modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV3;
     embeddingModel(modelId: string): never;
     imageModel(modelId: string): never;
 }
-declare function createCodexCli(options?: CodexCliProviderSettings): CodexCliProvider;
-declare const codexCli: CodexCliProvider;
+declare function createCodexExec(options?: CodexExecProviderSettings): CodexExecProvider;
+declare const codexExec: CodexExecProvider;
 
-interface CodexLanguageModelOptions {
-    id: string;
-    settings?: CodexCliSettings;
+interface CodexAppServerModelListResult {
+    models: ModelInfo[];
+    defaultModel?: ModelInfo;
+    nextCursor?: string | null;
+}
+/**
+ * Provider interface for the persistent Codex app-server transport.
+ *
+ * Use this via `createCodexAppServer()` or the default `codexAppServer` export.
+ */
+interface CodexAppServerProvider extends ProviderV3 {
+    (modelId: CodexModelId, settings?: CodexAppServerSettings): LanguageModelV3;
+    languageModel(modelId: CodexModelId, settings?: CodexAppServerSettings): LanguageModelV3;
+    chat(modelId: CodexModelId, settings?: CodexAppServerSettings): LanguageModelV3;
+    embeddingModel(modelId: string): never;
+    imageModel(modelId: string): never;
+    close(): Promise<void>;
+    dispose(): Promise<void>;
+    listModels(modelProviders?: string[]): Promise<CodexAppServerModelListResult>;
+}
+/**
+ * Creates a Codex app-server provider instance.
+ *
+ * The provider maintains a shared JSON-RPC client process and can be reused
+ * across many model calls. Always call `provider.close()` (or `dispose()`)
+ * when finished.
+ *
+ * @example
+ * ```ts
+ * const provider = createCodexAppServer({
+ *   defaultSettings: { minCodexVersion: '0.105.0-alpha.0' },
+ * });
+ *
+ * try {
+ *   const model = provider('gpt-5.3-codex');
+ *   // use with generateText / streamText / generateObject
+ * } finally {
+ *   await provider.close();
+ * }
+ * ```
+ */
+declare function createCodexAppServer(options?: CodexAppServerProviderSettings): CodexAppServerProvider;
+declare const codexAppServer: CodexAppServerProvider;
+
+interface ListModelsOptions {
+    codexPath?: string;
+    env?: Record<string, string>;
+    cwd?: string;
+    minCodexVersion?: string;
+    modelProviders?: string[];
+    connectionTimeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+interface ListModelsResult {
+    models: ModelInfo[];
+    defaultModel?: ModelInfo;
+    nextCursor?: string | null;
 }
-declare class CodexCliLanguageModel implements LanguageModelV3 {
+declare function listModels(options?: ListModelsOptions): Promise<ListModelsResult>;
+
+interface ExecLanguageModelOptions {
+    id: CodexModelId;
+    settings?: CodexExecSettings;
+}
+declare class ExecLanguageModel implements LanguageModelV3 {
     readonly specificationVersion: "v3";
     readonly provider = "codex-cli";
     readonly defaultObjectGenerationMode: "json";
@@ -267,14 +729,11 @@ declare class CodexCliLanguageModel implements LanguageModelV3 {
     readonly supportedUrls: {};
     readonly supportsStructuredOutputs = true;
     readonly modelId: string;
-    readonly settings: CodexCliSettings;
+    readonly settings: CodexExecSettings;
     private logger;
     private sessionId?;
-    constructor(options: CodexLanguageModelOptions);
+    constructor(options: ExecLanguageModelOptions);
     private mergeSettings;
-    private mergeMcpServers;
-    private mergeSingleMcpServer;
-    private mergeStringRecord;
     private getItemType;
     private buildArgs;
     private applyMcpSettings;
@@ -283,15 +742,11 @@ declare class CodexCliLanguageModel implements LanguageModelV3 {
      * Serialize a config override value into a CLI-safe string.
      */
     private serializeConfigValue;
-    private isPlainObject;
-    private sanitizeJsonSchema;
-    private mapWarnings;
     private parseExperimentalJsonEvent;
     private extractUsage;
     private getToolName;
     private buildToolInputPayload;
     private buildToolResultPayload;
-    private safeStringify;
     private emitToolInvocation;
     private emitToolResult;
     private handleSpawnError;
@@ -299,6 +754,18 @@ declare class CodexCliLanguageModel implements LanguageModelV3 {
     doStream(options: Parameters<LanguageModelV3['doStream']>[0]): Promise<Awaited<ReturnType<LanguageModelV3['doStream']>>>;
 }
 
+declare class UnsupportedFeatureError extends UnsupportedFunctionalityError {
+    readonly feature: string;
+    readonly minCodexVersion?: string;
+    readonly serverVersion?: string;
+    constructor({ feature, minCodexVersion, serverVersion, message, }: {
+        feature: string;
+        minCodexVersion?: string;
+        serverVersion?: string;
+        message?: string;
+    });
+}
 declare function isAuthenticationError(err: unknown): boolean;
+declare function isUnsupportedFeatureError(err: unknown): err is UnsupportedFeatureError;
 
-export { CodexCliLanguageModel, type CodexCliProvider, type CodexCliProviderOptions, type CodexCliProviderSettings, type CodexCliSettings, type Logger, type ModelVerbosity, type ReasoningEffort, type ReasoningSummary, type ReasoningSummaryFormat, codexCli, createCodexCli, isAuthenticationError };
+export { type AppServerThreadMode, type AppServerUserInput, type CodexAppServerModelListResult, type CodexAppServerProvider, type CodexAppServerProviderOptions, type CodexAppServerProviderSettings, type CodexAppServerRequestHandlers, type CodexAppServerSession, type CodexAppServerSettings, ExecLanguageModel as CodexCliLanguageModel, type CodexExecProvider as CodexCliProvider, type CodexCliProviderOptions, type CodexCliProviderSettings, type CodexCliSettings, type CodexExecProvider, type CodexExecProviderOptions, type CodexExecProviderSettings, type CodexExecSettings, type CodexModelId, type ErrorNotification, ExecLanguageModel, type ItemCompletedNotification, type ItemStartedNotification, type JsonRpcError, type JsonRpcErrorResponse, type JsonRpcId, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type ListModelsOptions, type ListModelsResult, type LocalMcpServer, type LocalMcpServerOptions, type LocalTool, type LocalToolDefinition, type Logger, type ModelVerbosity, type ReasoningEffort, type ReasoningSummary, type ReasoningSummaryFormat, type SdkMcpServer, type SdkMcpServerOptions, type Thread, type ThreadItem, type ThreadResumeParams, type ThreadResumeResponse, type ThreadStartParams, type ThreadStartResponse, type ThreadStartedNotification, type Turn, type TurnCompletedNotification, type TurnInterruptParams, type TurnInterruptResponse, type TurnStartParams, type TurnStartResponse, type TurnStartedNotification, UnsupportedFeatureError, type UserInput, codexAppServer, codexExec as codexCli, codexExec, createCodexAppServer, createCodexExec as createCodexCli, createCodexExec, createLocalMcpServer, createSdkMcpServer, isAuthenticationError, isUnsupportedFeatureError, listModels, tool };