ai-sdk-provider-codex-cli 1.3.0 → 2.0.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ProviderV3, LanguageModelV3, UnsupportedFunctionalityError } from '@ai-sdk/provider';
+import { ProviderV4, LanguageModelV4, UnsupportedFunctionalityError } from '@ai-sdk/provider';
 import { ZodType } from 'zod';
 
 /**
@@ -123,12 +123,24 @@ interface JsonRpcNotification {
     params?: Record<string, unknown>;
 }
 type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcErrorResponse | JsonRpcNotification;
+/**
+ * Vendored subset of the codex 0.142.5 `Model` wire type (renamed upstream
+ * from `ModelInfo`), plus fields only pre-0.142 servers return.
+ */
 interface ModelInfo {
     id: string;
-    name?: string | null;
-    modelProvider?: string | null;
+    /** Underlying model slug (codex >= 0.142). */
+    model?: string;
+    /** Display name; replaces the pre-0.142 `name` field (codex >= 0.142). */
+    displayName?: string;
     description?: string | null;
+    /** Whether the model is hidden from the default picker list (codex >= 0.142). */
+    hidden?: boolean;
     isDefault?: boolean | null;
+    /** External contract: only pre-0.142 servers return `name`. */
+    name?: string | null;
+    /** External contract: only pre-0.142 servers return `modelProvider`. */
+    modelProvider?: string | null;
     [k: string]: unknown;
 }
 interface Thread {
@@ -149,8 +161,12 @@ interface ThreadStartParams {
     developerInstructions?: string | null;
     personality?: 'none' | 'friendly' | 'pragmatic' | null;
     ephemeral?: boolean | null;
-    experimentalRawEvents: boolean;
-    persistExtendedHistory: boolean;
+    experimentalRawEvents?: boolean;
+    /**
+     * External contract: consumed by pre-0.142 servers only. Codex 0.142.5
+     * removed this param and ignores it when sent (verified empirically).
+     */
+    persistExtendedHistory?: boolean;
 }
 interface ThreadStartResponse {
     thread: Thread;
@@ -174,7 +190,11 @@ interface ThreadResumeParams {
     baseInstructions?: string | null;
     developerInstructions?: string | null;
     personality?: 'none' | 'friendly' | 'pragmatic' | null;
-    persistExtendedHistory: boolean;
+    /**
+     * External contract: consumed by pre-0.142 servers only. Codex 0.142.5
+     * removed this param and ignores it when sent.
+     */
+    persistExtendedHistory?: boolean;
 }
 type ThreadResumeResponse = ThreadStartResponse;
 type UserInput = {
@@ -183,11 +203,16 @@ type UserInput = {
     text_elements: unknown[];
 } | {
     type: 'image';
-    url?: string;
+    url: string;
+    /** Optional rendering detail hint (codex >= 0.142). */
+    detail?: 'auto' | 'low' | 'high' | 'original';
+    /** External contract: pre-0.142 servers read `imageUrl`; codex 0.142.5 only reads `url`. */
     imageUrl?: string;
 } | {
     type: 'localImage';
     path: string;
+    /** Optional rendering detail hint (codex >= 0.142). */
+    detail?: 'auto' | 'low' | 'high' | 'original';
 } | {
     type: 'skill';
     name: string;
@@ -204,13 +229,18 @@ interface TurnStartParams {
     approvalPolicy?: unknown;
     sandboxPolicy?: unknown;
     model?: string | null;
-    effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | null;
+    /**
+     * Reasoning effort. Open-ended string upstream (`ReasoningEffort = string`
+     * in codex 0.142.5); known values include 'none', 'minimal', 'low',
+     * 'medium', 'high', 'xhigh', and 'ultra'.
+     */
+    effort?: string | 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' | {
+type CodexErrorInfo = 'contextWindowExceeded' | 'usageLimitExceeded' | 'serverOverloaded' | 'cyberPolicy' | 'internalServerError' | 'unauthorized' | 'badRequest' | 'threadRollbackFailed' | 'sandboxError' | 'other' | {
     httpConnectionFailed: {
         httpStatusCode: number | null;
     };
@@ -226,6 +256,10 @@ type CodexErrorInfo = 'contextWindowExceeded' | 'usageLimitExceeded' | 'serverOv
     responseTooManyFailedAttempts: {
         httpStatusCode: number | null;
     };
+} | {
+    activeTurnNotSteerable: {
+        turnKind: 'review' | 'compact';
+    };
 };
 interface TurnError {
     message: string;
@@ -236,6 +270,8 @@ type TurnStatus = 'completed' | 'interrupted' | 'failed' | 'inProgress';
 type UserMessageItem = {
     type: 'userMessage';
     id: string;
+    /** Client-supplied message id echoed back by the server (codex >= 0.142). */
+    clientId?: string | null;
     content: UserInput[];
 };
 type AgentMessageItem = {
@@ -243,6 +279,8 @@ type AgentMessageItem = {
     id: string;
     text: string;
     phase: string | null;
+    /** Memory citation metadata (codex >= 0.142). */
+    memoryCitation?: unknown | null;
 };
 type PlanItem = {
     type: 'plan';
@@ -261,6 +299,8 @@ type CommandExecutionItem = {
     command: string;
     cwd: string;
     processId: string | null;
+    /** 'agent' | 'userShell' | 'unifiedExecStartup' | 'unifiedExecInteraction' (codex >= 0.142). */
+    source?: string;
     status: string;
     commandActions: unknown[];
     aggregatedOutput: string | null;
@@ -280,6 +320,10 @@ type McpToolCallItem = {
     tool: string;
     status: string;
     arguments: unknown;
+    /** MCP app context; replaces `mcpAppResourceUri` (codex >= 0.142). */
+    appContext?: unknown | null;
+    mcpAppResourceUri?: string;
+    pluginId?: string | null;
     result: unknown | null;
     error: unknown | null;
     durationMs: number | null;
@@ -292,6 +336,10 @@ type CollabAgentToolCallItem = {
     senderThreadId: string;
     receiverThreadIds: string[];
     prompt: string | null;
+    /** Model requested for the spawned agent, when applicable (codex >= 0.142). */
+    model?: string | null;
+    /** Reasoning effort requested for the spawned agent, when applicable (codex >= 0.142). */
+    reasoningEffort?: string | null;
     agentsStates: Record<string, unknown>;
 };
 type WebSearchItem = {
@@ -319,12 +367,58 @@ type ContextCompactionItem = {
     type: 'contextCompaction';
     id: string;
 };
-type ThreadItem = UserMessageItem | AgentMessageItem | PlanItem | ReasoningItem | CommandExecutionItem | FileChangeItem | McpToolCallItem | CollabAgentToolCallItem | WebSearchItem | ImageViewItem | EnteredReviewModeItem | ExitedReviewModeItem | ContextCompactionItem;
+/** codex >= 0.142. */
+type HookPromptItem = {
+    type: 'hookPrompt';
+    id: string;
+    fragments: unknown[];
+};
+/** SDK-registered dynamic tool call surfaced as a thread item (codex >= 0.142). */
+type DynamicToolCallItem = {
+    type: 'dynamicToolCall';
+    id: string;
+    namespace: string | null;
+    tool: string;
+    arguments: unknown;
+    status: string;
+    contentItems: unknown[] | null;
+    success: boolean | null;
+    durationMs: number | null;
+};
+/** codex >= 0.142. */
+type SubAgentActivityItem = {
+    type: 'subAgentActivity';
+    id: string;
+    kind: string;
+    agentThreadId: string;
+    agentPath: string;
+};
+/** codex >= 0.142. */
+type SleepItem = {
+    type: 'sleep';
+    id: string;
+    durationMs: number;
+};
+/** codex >= 0.142. */
+type ImageGenerationItem = {
+    type: 'imageGeneration';
+    id: string;
+    status: string;
+    revisedPrompt: string | null;
+    result: string;
+    savedPath?: string;
+};
+type ThreadItem = UserMessageItem | AgentMessageItem | PlanItem | ReasoningItem | CommandExecutionItem | FileChangeItem | McpToolCallItem | DynamicToolCallItem | CollabAgentToolCallItem | HookPromptItem | SubAgentActivityItem | SleepItem | ImageGenerationItem | WebSearchItem | ImageViewItem | EnteredReviewModeItem | ExitedReviewModeItem | ContextCompactionItem;
 interface Turn {
     id: string;
     items: ThreadItem[];
+    /** 'notLoaded' | 'summary' | 'full' (codex >= 0.142). */
+    itemsView?: string;
     status: TurnStatus;
     error: TurnError | null;
+    startedAt?: number | null;
+    completedAt?: number | null;
+    durationMs?: number | null;
 }
 interface TurnStartResponse {
     turn: Turn;
@@ -349,11 +443,15 @@ interface ItemStartedNotification {
     item: ThreadItem;
     threadId: string;
     turnId: string;
+    /** Unix timestamp (ms) when this item lifecycle started (codex >= 0.142). */
+    startedAtMs?: number;
 }
 interface ItemCompletedNotification {
     item: ThreadItem;
     threadId: string;
     turnId: string;
+    /** Unix timestamp (ms) when this item lifecycle completed (codex >= 0.142). */
+    completedAtMs?: number;
 }
 interface ErrorNotification {
     error: TurnError;
@@ -366,35 +464,59 @@ interface CommandExecutionRequestApprovalParams {
     threadId: string;
     turnId: string;
     itemId: string;
+    /** Unix timestamp (ms) when this approval request started (codex >= 0.142). */
+    startedAtMs?: number;
     approvalId?: string | null;
+    /** Environment in which the command will run (codex >= 0.142). */
+    environmentId?: string | null;
     reason?: string | null;
     networkApprovalContext?: unknown | null;
     command?: string | null;
     cwd?: string | null;
     commandActions?: unknown[] | null;
+    /** Additional permissions requested for this command (codex >= 0.142). */
+    additionalPermissions?: unknown | null;
     proposedExecpolicyAmendment?: unknown | null;
+    /** Proposed network policy amendments for future requests (codex >= 0.142). */
+    proposedNetworkPolicyAmendments?: unknown[] | null;
+    /** Ordered decisions the client may present for this prompt (codex >= 0.142). */
+    availableDecisions?: unknown[] | null;
 }
 interface CommandExecutionRequestApprovalResponse {
     decision: 'accept' | 'acceptForSession' | 'decline' | 'cancel' | {
         acceptWithExecpolicyAmendment: {
             execpolicy_amendment: unknown;
         };
+    } | {
+        applyNetworkPolicyAmendment: {
+            network_policy_amendment: unknown;
+        };
     };
 }
 interface FileChangeRequestApprovalParams {
     threadId: string;
     turnId: string;
     itemId: string;
+    /** Unix timestamp (ms) when this approval request started (codex >= 0.142). */
+    startedAtMs?: number;
     reason?: string | null;
     grantRoot?: string | null;
 }
 interface FileChangeRequestApprovalResponse {
     decision: 'accept' | 'acceptForSession' | 'decline' | 'cancel';
 }
+/**
+ * External contract: `skill/requestApproval` was removed from the codex
+ * 0.142.5 server-request surface; only pre-0.142 servers send it.
+ */
 interface SkillRequestApprovalParams {
     itemId: string;
     skillName: string;
 }
+/**
+ * External contract: `skill/requestApproval` was removed from the codex
+ * 0.142.5 server-request surface; only pre-0.142 servers send it.
+ */
 interface SkillRequestApprovalResponse {
     decision: 'approve' | 'decline';
 }
@@ -403,6 +525,8 @@ interface ToolRequestUserInputParams {
     turnId: string;
     itemId: string;
     questions: unknown[];
+    /** Auto-resolution deadline in milliseconds, when set (codex >= 0.142). */
+    autoResolutionMs?: number | null;
 }
 interface ToolRequestUserInputResponse {
     answers: Record<string, unknown>;
@@ -413,7 +537,10 @@ interface McpServerElicitationRequestParams {
     /** Nullable: the elicitation may arrive outside of an active turn. */
     turnId?: string | null;
     serverName: string;
-    /** 'form' requests carry message/requestedSchema; 'url' requests carry url/elicitationId. */
+    /**
+     * 'form' and 'openai/form' (codex >= 0.142) requests carry
+     * message/requestedSchema; 'url' requests carry url/elicitationId.
+     */
     mode?: string;
     message?: string;
     requestedSchema?: unknown;
@@ -429,11 +556,15 @@ interface McpServerElicitationRequestResponse {
     action: McpServerElicitationAction;
     /** Structured user input for accepted elicitations; null for decline/cancel. */
     content?: Record<string, unknown> | null;
+    /** Optional client metadata for form-mode action handling (codex >= 0.142). */
+    _meta?: Record<string, unknown> | null;
 }
 interface DynamicToolCallParams {
     threadId: string;
     turnId: string;
     callId: string;
+    /** Dynamic tool namespace (codex >= 0.142). */
+    namespace?: string | null;
     tool: string;
     arguments: unknown;
 }
@@ -442,6 +573,7 @@ interface DynamicToolCallResponse {
     success: boolean;
 }
 interface ChatgptAuthTokensRefreshParams {
+    /** Codex 0.142.5 only sends 'unauthorized'; kept open for forward compat. */
     reason: string;
     previousAccountId?: string | null;
 }
@@ -682,10 +814,10 @@ interface CodexAppServerProviderOptions {
     onSessionCreated?: (session: CodexAppServerSession) => void | Promise<void>;
 }
 
-interface CodexExecProvider extends ProviderV3 {
-    (modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV3;
-    languageModel(modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV3;
-    chat(modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV3;
+interface CodexExecProvider extends ProviderV4 {
+    (modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV4;
+    languageModel(modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV4;
+    chat(modelId: CodexModelId, settings?: CodexExecSettings): LanguageModelV4;
     embeddingModel(modelId: string): never;
     imageModel(modelId: string): never;
 }
@@ -702,10 +834,10 @@ interface CodexAppServerModelListResult {
  *
  * 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;
+interface CodexAppServerProvider extends ProviderV4 {
+    (modelId: CodexModelId, settings?: CodexAppServerSettings): LanguageModelV4;
+    languageModel(modelId: CodexModelId, settings?: CodexAppServerSettings): LanguageModelV4;
+    chat(modelId: CodexModelId, settings?: CodexAppServerSettings): LanguageModelV4;
     embeddingModel(modelId: string): never;
     imageModel(modelId: string): never;
     close(): Promise<void>;
@@ -722,7 +854,7 @@ interface CodexAppServerProvider extends ProviderV3 {
  * @example
  * ```ts
  * const provider = createCodexAppServer({
- *   defaultSettings: { minCodexVersion: '0.144.0' },
+ *   defaultSettings: { minCodexVersion: '0.142.5' },
  * });
  *
  * try {
@@ -756,13 +888,10 @@ interface ExecLanguageModelOptions {
     id: CodexModelId;
     settings?: CodexExecSettings;
 }
-declare class ExecLanguageModel implements LanguageModelV3 {
-    readonly specificationVersion: "v3";
+declare class ExecLanguageModel implements LanguageModelV4 {
+    readonly specificationVersion: "v4";
     readonly provider = "codex-cli";
-    readonly defaultObjectGenerationMode: "json";
-    readonly supportsImageUrls = false;
     readonly supportedUrls: {};
-    readonly supportsStructuredOutputs = true;
     readonly modelId: string;
     readonly settings: CodexExecSettings;
     private logger;
@@ -785,8 +914,8 @@ declare class ExecLanguageModel implements LanguageModelV3 {
     private emitToolInvocation;
     private emitToolResult;
     private handleSpawnError;
-    doGenerate(options: Parameters<LanguageModelV3['doGenerate']>[0]): Promise<Awaited<ReturnType<LanguageModelV3['doGenerate']>>>;
-    doStream(options: Parameters<LanguageModelV3['doStream']>[0]): Promise<Awaited<ReturnType<LanguageModelV3['doStream']>>>;
+    doGenerate(options: Parameters<LanguageModelV4['doGenerate']>[0]): Promise<Awaited<ReturnType<LanguageModelV4['doGenerate']>>>;
+    doStream(options: Parameters<LanguageModelV4['doStream']>[0]): Promise<Awaited<ReturnType<LanguageModelV4['doStream']>>>;
 }
 
 declare class UnsupportedFeatureError extends UnsupportedFunctionalityError {