@janole/ai-sdk-provider-codex-asp 0.4.1 → 0.4.3

package/dist/index.d.cts

@@ -15,10 +15,20 @@ type JsonValue = number | string | boolean | Array<JsonValue> | {
     [key in string]?: JsonValue;
 } | null;
 
+/**
+ * Configures who approval requests are routed to for review. Examples
+ * include sandbox escapes, blocked network access, MCP approval prompts, and
+ * ARC escalations. Defaults to `user`. `guardian_subagent` uses a carefully
+ * prompted subagent to gather relevant context and apply a risk-based
+ * decision framework before approving or denying the request.
+ */
+type ApprovalsReviewer = "user" | "guardian_subagent";
+
 type AskForApproval = "untrusted" | "on-failure" | "on-request" | {
-    "reject": {
+    "granular": {
         sandbox_approval: boolean;
         rules: boolean;
+        skill_approval: boolean;
         request_permissions: boolean;
         mcp_elicitations: boolean;
     };
@@ -63,13 +73,18 @@ type MacOsAutomationPermission = "none" | "all" | {
     "bundle_ids": Array<string>;
 };
 
+type MacOsContactsPermission = "none" | "read_only" | "read_write";
+
 type MacOsPreferencesPermission = "none" | "read_only" | "read_write";
 
 type AdditionalMacOsPermissions = {
     preferences: MacOsPreferencesPermission;
     automations: MacOsAutomationPermission;
+    launchServices: boolean;
     accessibility: boolean;
     calendar: boolean;
+    reminders: boolean;
+    contacts: MacOsContactsPermission;
 };
 
 type AdditionalNetworkPermissions = {
@@ -231,7 +246,12 @@ type SandboxPolicy = {
  */
 type MessagePhase = "commentary" | "final_answer";
 
-type CollabAgentStatus = "pendingInit" | "running" | "completed" | "errored" | "shutdown" | "notFound";
+/**
+ * See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning
+ */
+type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+type CollabAgentStatus = "pendingInit" | "running" | "interrupted" | "completed" | "errored" | "shutdown" | "notFound";
 
 type CollabAgentState = {
     status: CollabAgentStatus;
@@ -242,6 +262,8 @@ type CollabAgentTool = "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "cl
 
 type CollabAgentToolCallStatus = "inProgress" | "completed" | "failed";
 
+type CommandExecutionSource = "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+
 type CommandExecutionStatus = "inProgress" | "completed" | "failed" | "declined";
 
 type DynamicToolCallOutputContentItem = {
@@ -269,6 +291,11 @@ type FileUpdateChange = {
     diff: string;
 };
 
+type HookPromptFragment = {
+    text: string;
+    hookRunId: string;
+};
+
 type McpToolCallError = {
     message: string;
 };
@@ -280,6 +307,18 @@ type McpToolCallResult = {
 
 type McpToolCallStatus = "inProgress" | "completed" | "failed";
 
+type MemoryCitationEntry = {
+    path: string;
+    lineStart: number;
+    lineEnd: number;
+    note: string;
+};
+
+type MemoryCitation = {
+    entries: Array<MemoryCitationEntry>;
+    threadIds: Array<string>;
+};
+
 type PatchApplyStatus = "inProgress" | "completed" | "failed" | "declined";
 
 type ByteRange = {
@@ -340,11 +379,16 @@ type ThreadItem = {
     "type": "userMessage";
     id: string;
     content: Array<UserInput>;
+} | {
+    "type": "hookPrompt";
+    id: string;
+    fragments: Array<HookPromptFragment>;
 } | {
     "type": "agentMessage";
     id: string;
     text: string;
     phase: MessagePhase | null;
+    memoryCitation: MemoryCitation | null;
 } | {
     "type": "plan";
     id: string;
@@ -369,6 +413,7 @@ type ThreadItem = {
      * Identifier for the underlying PTY process (when available).
      */
     processId: string | null;
+    source: CommandExecutionSource;
     status: CommandExecutionStatus;
     /**
      * A best-effort parsing of the command to understand the action(s) it will perform.
@@ -445,6 +490,14 @@ type ThreadItem = {
      * Prompt text sent as part of the collab tool call, when available.
      */
     prompt: string | null;
+    /**
+     * Model requested for the spawned agent, when applicable.
+     */
+    model: string | null;
+    /**
+     * Reasoning effort requested for the spawned agent, when applicable.
+     */
+    reasoningEffort: ReasoningEffort | null;
     /**
      * Last known status of the target agents, when available.
      */
@@ -466,6 +519,7 @@ type ThreadItem = {
     status: string;
     revisedPrompt: string | null;
     result: string;
+    savedPath?: string;
 } | {
     "type": "enteredReviewMode";
     id: string;
@@ -509,17 +563,6 @@ type FunctionCallOutputContentItem = {
 
 type FunctionCallOutputBody = string | Array<FunctionCallOutputContentItem>;
 
-/**
- * The payload we send back to OpenAI when reporting a tool call result.
- *
- * `body` serializes directly as the wire value for `function_call_output.output`.
- * `success` remains internal metadata for downstream handling.
- */
-type FunctionCallOutputPayload = {
-    body: FunctionCallOutputBody;
-    success: boolean | null;
-};
-
 /**
  * Details of a ghost commit created from a repository state.
  */
@@ -596,12 +639,19 @@ type ResponseItem = {
 } | {
     "type": "function_call";
     name: string;
+    namespace?: string;
     arguments: string;
     call_id: string;
+} | {
+    "type": "tool_search_call";
+    call_id: string | null;
+    status?: string;
+    execution: string;
+    arguments: unknown;
 } | {
     "type": "function_call_output";
     call_id: string;
-    output: FunctionCallOutputPayload;
+    output: FunctionCallOutputBody;
 } | {
     "type": "custom_tool_call";
     status?: string;
@@ -611,7 +661,14 @@ type ResponseItem = {
 } | {
     "type": "custom_tool_call_output";
     call_id: string;
-    output: FunctionCallOutputPayload;
+    name?: string;
+    output: FunctionCallOutputBody;
+} | {
+    "type": "tool_search_output";
+    call_id: string | null;
+    status: string;
+    execution: string;
+    tools: unknown[];
 } | {
     "type": "web_search_call";
     status?: string;
@@ -666,6 +723,11 @@ type ThreadResumeParams = {
     serviceTier?: ServiceTier | null | null;
     cwd?: string | null;
     approvalPolicy?: AskForApproval | null;
+    /**
+     * Override where approval requests are routed for review on this thread
+     * and subsequent turns.
+     */
+    approvalsReviewer?: ApprovalsReviewer | null;
     sandbox?: SandboxMode | null;
     config?: {
         [key in string]?: JsonValue;
@@ -680,23 +742,21 @@ type ThreadResumeParams = {
     persistExtendedHistory: boolean;
 };
 
-/**
- * See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning
- */
-type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
-
 type GitInfo = {
     sha: string | null;
     branch: string | null;
     originUrl: string | null;
 };
 
+type AgentPath = string;
+
 type ThreadId = string;
 
 type SubAgentSource = "review" | "compact" | {
     "thread_spawn": {
         parent_thread_id: ThreadId;
         depth: number;
+        agent_path: AgentPath | null;
         agent_nickname: string | null;
         agent_role: string | null;
     };
@@ -705,6 +765,8 @@ type SubAgentSource = "review" | "compact" | {
 };
 
 type SessionSource = "cli" | "vscode" | "exec" | "appServer" | {
+    "custom": string;
+} | {
     "subAgent": SubAgentSource;
 } | "unknown";
 
@@ -721,6 +783,8 @@ type ThreadStatus = {
     activeFlags: Array<ThreadActiveFlag>;
 };
 
+type NonSteerableTurnKind = "review" | "compact";
+
 /**
  * This translation layer make sure that we expose codex error code in camel case.
  *
@@ -743,6 +807,10 @@ type CodexErrorInfo = "contextWindowExceeded" | "usageLimitExceeded" | "serverOv
     "responseTooManyFailedAttempts": {
         httpStatusCode: number | null;
     };
+} | {
+    "activeTurnNotSteerable": {
+        turnKind: NonSteerableTurnKind;
+    };
 } | "other";
 
 type TurnError = {
@@ -842,6 +910,10 @@ type ThreadResumeResponse = {
     serviceTier: ServiceTier | null;
     cwd: string;
     approvalPolicy: AskForApproval;
+    /**
+     * Reviewer currently used for approval requests on this thread.
+     */
+    approvalsReviewer: ApprovalsReviewer;
     sandbox: SandboxPolicy;
     reasoningEffort: ReasoningEffort | null;
 };
@@ -886,6 +958,11 @@ type TurnStartParams = {
      * Override the approval policy for this turn and subsequent turns.
      */
     approvalPolicy?: AskForApproval | null;
+    /**
+     * Override where approval requests are routed for review on this turn and
+     * subsequent turns.
+     */
+    approvalsReviewer?: ApprovalsReviewer | null;
     /**
      * Override the sandbox policy for this turn and subsequent turns.
      */
@@ -1026,6 +1103,7 @@ interface CodexThreadStartParams {
     model?: string;
     cwd?: string;
     approvalPolicy?: AskForApproval;
+    approvalsReviewer?: ApprovalsReviewer;
     sandbox?: SandboxMode;
     config?: Record<string, JsonValue | undefined>;
     dynamicTools?: CodexDynamicToolDefinition[];
@@ -1366,8 +1444,10 @@ interface TransportContext {
 interface CodexThreadDefaults {
     /** Working directory for the thread. */
     cwd?: string;
-    /** Tool-use approval policy — `"never"` | `"on-failure"` | `"on-request"` | `"untrusted"` | `{ reject: … }`. See {@link AskForApproval}. */
+    /** Tool-use approval policy — `"never"` | `"on-failure"` | `"on-request"` | `"untrusted"` | `{ granular: … }`. See {@link AskForApproval}. */
     approvalPolicy?: AskForApproval;
+    /** Routes approval requests for the thread to `"user"` or `"guardian_subagent"`. */
+    approvalsReviewer?: ApprovalsReviewer;
     /** Sandbox mode — `"read-only"` | `"workspace-write"` | `"danger-full-access"`. See {@link SandboxMode}. */
     sandbox?: SandboxMode;
 }
@@ -1377,6 +1457,8 @@ interface CodexTurnDefaults {
     cwd?: string;
     /** Tool-use approval policy for this turn. */
     approvalPolicy?: AskForApproval;
+    /** Routes approval requests for this turn to `"user"` or `"guardian_subagent"`. */
+    approvalsReviewer?: ApprovalsReviewer;
     /** Fine-grained sandbox policy — `{ type: "dangerFullAccess" }` | `{ type: "readOnly", … }` | `{ type: "workspaceWrite", … }` | `{ type: "externalSandbox", … }`. See {@link SandboxPolicy}. */
     sandboxPolicy?: SandboxPolicy;
     /** Model to use for this turn (overrides provider-level `defaultModel`). */
@@ -1394,8 +1476,10 @@ interface CodexTurnDefaults {
 interface CodexCallOptions {
     /** Working directory for this call. Also sent as turn-level `cwd`. */
     cwd?: string;
-    /** Tool-use approval policy — `"never"` | `"on-failure"` | `"on-request"` | `"untrusted"` | `{ reject: … }`. See {@link AskForApproval}. */
+    /** Tool-use approval policy — `"never"` | `"on-failure"` | `"on-request"` | `"untrusted"` | `{ granular: … }`. See {@link AskForApproval}. */
     approvalPolicy?: AskForApproval;
+    /** Routes approval requests to `"user"` or `"guardian_subagent"`. */
+    approvalsReviewer?: ApprovalsReviewer;
     /** Sandbox mode — `"read-only"` | `"workspace-write"` | `"danger-full-access"`. See {@link SandboxMode}. */
     sandbox?: SandboxMode;
     /** How much effort the model should spend on the response. */
@@ -1406,6 +1490,11 @@ interface CodexCallOptions {
     sandboxPolicy?: SandboxPolicy;
     /** Controls turn summary generation. */
     summary?: "auto" | "concise" | "detailed" | "none";
+    /** Approval callbacks for this call; falls back to provider-level `approvals`. */
+    approvals?: {
+        onCommandApproval?: CommandApprovalHandler;
+        onFileChangeApproval?: FileChangeApprovalHandler;
+    };
 }
 interface CodexCompactionSettings {
     /**
@@ -1500,7 +1589,7 @@ interface CodexProviderSettings {
     persistent?: {
         /** Number of worker processes to keep in the pool. */
         poolSize?: number;
-        /** Time (ms) before an idle worker is shut down. */
+        /** Time (ms) before an idle worker is shut down. Set to `0` to disable (worker stays alive indefinitely). */
         idleTimeoutMs?: number;
         /** `"provider"` = pool per provider instance; `"global"` = shared across all instances. */
         scope?: "provider" | "global";
@@ -1752,4 +1841,4 @@ declare class PromptFileResolver {
     private resolveFresh;
 }
 
-export { type AgentMessageDeltaNotification, AppServerClient, type AppServerClientSettings, ApprovalsDispatcher, type ApprovalsDispatcherSettings, type AskForApproval, CODEX_PROVIDER_ID, type CodexCallOptions, type CodexCommandApprovalRequest, type CodexDynamicToolDefinition, CodexEventMapper, type CodexEventMapperInput, type CodexEventMapperOptions, type CodexFileChangeApprovalRequest, type CodexInitializeParams, type CodexInitializeResult, type CodexInitializedNotification, CodexLanguageModel, type CodexLanguageModelSettings, type Model as CodexModel, type CodexModelConfig, CodexNotImplementedError, type CodexNotification, type CodexProvider, CodexProviderError, type CodexProviderSettings, type CodexSession, type CodexThreadDefaults, type CodexThreadResumeParams, type CodexThreadResumeResult, type CodexThreadStartParams, type CodexThreadStartResult, type CodexToolCallDeltaNotification, type CodexToolCallFinishedNotification, type CodexToolCallRequestParams, type CodexToolCallResult, type CodexToolCallStartedNotification, type CodexToolResultContentItem, type CodexTransport, type CodexTransportEventMap, type CodexTurnInputImage, type CodexTurnInputItem, type CodexTurnInputLocalImage, type CodexTurnInputMention, type CodexTurnInputSkill, type CodexTurnInputText, type CodexTurnStartParams, type CodexTurnStartResult, CodexWorker, CodexWorkerPool, type CodexWorkerPoolSettings, type CodexWorkerSettings, type CommandApprovalHandler, type CommandExecutionApprovalDecision, type CommandExecutionRequestApprovalParams, type CommandExecutionRequestApprovalResponse, type DynamicToolDefinition, type DynamicToolExecutionContext, type DynamicToolHandler, DynamicToolsDispatcher, type DynamicToolsDispatcherSettings, type FileChangeApprovalDecision, type FileChangeApprovalHandler, type FileChangeRequestApprovalParams, type FileChangeRequestApprovalResponse, type FileWriter, type ItemCompletedNotification, type ItemStartedNotification, JsonRpcError, type JsonRpcErrorResponse, type JsonRpcId, type JsonRpcMessage, type JsonRpcMessageBase, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type JsonRpcSuccessResponse, LocalFileWriter, type McpServerConfig, PACKAGE_NAME, PACKAGE_VERSION, type PendingToolCall, PersistentTransport, type PersistentTransportSettings, PromptFileResolver, type SandboxMode, StdioTransport, type StdioTransportSettings, type ThreadItem, type ThreadTokenUsageUpdatedNotification, type TransportContext, type TurnCompletedNotification, type TurnStartedNotification, WebSocketTransport, type WebSocketTransportSettings, codexAppServer, codexCallOptions, codexProviderMetadata, createCodexAppServer, createCodexProvider, mapSystemPrompt, withProviderMetadata };
+export { type AgentMessageDeltaNotification, AppServerClient, type AppServerClientSettings, ApprovalsDispatcher, type ApprovalsDispatcherSettings, type ApprovalsReviewer, type AskForApproval, CODEX_PROVIDER_ID, type CodexCallOptions, type CodexCommandApprovalRequest, type CodexDynamicToolDefinition, CodexEventMapper, type CodexEventMapperInput, type CodexEventMapperOptions, type CodexFileChangeApprovalRequest, type CodexInitializeParams, type CodexInitializeResult, type CodexInitializedNotification, CodexLanguageModel, type CodexLanguageModelSettings, type Model as CodexModel, type CodexModelConfig, CodexNotImplementedError, type CodexNotification, type CodexProvider, CodexProviderError, type CodexProviderSettings, type CodexSession, type CodexThreadDefaults, type CodexThreadResumeParams, type CodexThreadResumeResult, type CodexThreadStartParams, type CodexThreadStartResult, type CodexToolCallDeltaNotification, type CodexToolCallFinishedNotification, type CodexToolCallRequestParams, type CodexToolCallResult, type CodexToolCallStartedNotification, type CodexToolResultContentItem, type CodexTransport, type CodexTransportEventMap, type CodexTurnInputImage, type CodexTurnInputItem, type CodexTurnInputLocalImage, type CodexTurnInputMention, type CodexTurnInputSkill, type CodexTurnInputText, type CodexTurnStartParams, type CodexTurnStartResult, CodexWorker, CodexWorkerPool, type CodexWorkerPoolSettings, type CodexWorkerSettings, type CommandApprovalHandler, type CommandExecutionApprovalDecision, type CommandExecutionRequestApprovalParams, type CommandExecutionRequestApprovalResponse, type DynamicToolDefinition, type DynamicToolExecutionContext, type DynamicToolHandler, DynamicToolsDispatcher, type DynamicToolsDispatcherSettings, type FileChangeApprovalDecision, type FileChangeApprovalHandler, type FileChangeRequestApprovalParams, type FileChangeRequestApprovalResponse, type FileWriter, type ItemCompletedNotification, type ItemStartedNotification, JsonRpcError, type JsonRpcErrorResponse, type JsonRpcId, type JsonRpcMessage, type JsonRpcMessageBase, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type JsonRpcSuccessResponse, LocalFileWriter, type McpServerConfig, PACKAGE_NAME, PACKAGE_VERSION, type PendingToolCall, PersistentTransport, type PersistentTransportSettings, PromptFileResolver, type SandboxMode, StdioTransport, type StdioTransportSettings, type ThreadItem, type ThreadTokenUsageUpdatedNotification, type TransportContext, type TurnCompletedNotification, type TurnStartedNotification, WebSocketTransport, type WebSocketTransportSettings, codexAppServer, codexCallOptions, codexProviderMetadata, createCodexAppServer, createCodexProvider, mapSystemPrompt, withProviderMetadata };