@jrkropp/codex-js 0.1.4 → 0.3.0

package/dist/internal/codex/core/src/rendered-thread.d.ts

@@ -0,0 +1,30 @@
+import type { ThreadId } from "./ids.js";
+import type { DynamicToolCallRequest, EventMsg, RolloutItem } from "./protocol.js";
+import type { RequestPermissionsEvent } from "./request_permissions.js";
+import type { RequestUserInputEvent } from "./request_user_input.js";
+import type { StoredThreadHistory } from "./thread-store/index.js";
+import { type Turn } from "./thread-history-builder.js";
+import type { TurnItem } from "./items.js";
+export type RenderedThreadConnectionStatus = "idle" | "connecting" | "connected" | "reconnecting" | "closed" | "error";
+export type RenderedThreadState = {
+    thread_id: ThreadId;
+    turns: Turn[];
+    items: TurnItem[];
+    pending_request_user_input: RequestUserInputEvent | null;
+    pending_request_permissions: RequestPermissionsEvent | null;
+    pending_dynamic_tool_call_requests: DynamicToolCallRequest[];
+    running_turn_ids: string[];
+    warnings: string[];
+    errors: string[];
+    last_history_fingerprint: string | null;
+    connection_status: RenderedThreadConnectionStatus;
+};
+export type ApplyEventOptions = {
+    event_id?: string;
+};
+export declare function createRenderedThreadState(threadId: ThreadId): RenderedThreadState;
+export declare function renderThreadFromHistory(history: StoredThreadHistory): RenderedThreadState;
+export declare function applyRolloutItemToRenderedThread(state: RenderedThreadState, item: RolloutItem, index?: number): RenderedThreadState;
+export declare function applyEventMsgToRenderedThread(state: RenderedThreadState, msg: EventMsg, options?: ApplyEventOptions): RenderedThreadState;
+export declare function setRenderedThreadConnectionStatus(state: RenderedThreadState, connectionStatus: RenderedThreadConnectionStatus): RenderedThreadState;
+export declare function fingerprintRolloutItems(items: readonly RolloutItem[]): string;

package/dist/internal/codex/core/src/request_permissions.d.ts

@@ -0,0 +1,52 @@
+import type { ToolSpec } from "./tools/tool_spec.js";
+export declare const REQUEST_PERMISSIONS_TOOL_NAME = "request_permissions";
+export declare const PermissionGrantScope: {
+    readonly Turn: "turn";
+    readonly Session: "session";
+};
+export type PermissionGrantScope = (typeof PermissionGrantScope)[keyof typeof PermissionGrantScope];
+export declare const ReviewDecision: {
+    readonly Approved: "approved";
+    readonly ApprovedForSession: "approved_for_session";
+    readonly Denied: "denied";
+    readonly Abort: "abort";
+    readonly TimedOut: "timed_out";
+};
+export type ReviewDecision = (typeof ReviewDecision)[keyof typeof ReviewDecision];
+export type NetworkPermissions = {
+    enabled?: boolean | null;
+    [key: string]: unknown;
+};
+export type FileSystemPermissions = {
+    entries?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+};
+export type RequestPermissionProfile = {
+    network?: NetworkPermissions | null;
+    file_system?: FileSystemPermissions | null;
+};
+export type RequestPermissionsArgs = {
+    reason?: string | null;
+    permissions: RequestPermissionProfile;
+};
+export type RequestPermissionsResponse = {
+    permissions: RequestPermissionProfile;
+    scope?: PermissionGrantScope;
+    strict_auto_review?: boolean;
+};
+export type RequestPermissionsEvent = {
+    /** Responses API call id for the associated tool call, if available. */
+    call_id: string;
+    /** Turn id that this request belongs to. */
+    turn_id: string;
+    reason?: string | null;
+    permissions: RequestPermissionProfile;
+    cwd?: string | null;
+};
+export declare function createRequestPermissionsTool(description: string): ToolSpec;
+export declare function requestPermissionsToolDescription(): string;
+export declare function normalizeRequestPermissionsArgs(args: RequestPermissionsArgs): RequestPermissionsArgs;
+export declare function emptyRequestPermissionsResponse(): RequestPermissionsResponse;
+export declare function deniedRequestPermissionsResponse(): RequestPermissionsResponse;
+export declare function isEmptyRequestPermissionProfile(permissions: RequestPermissionProfile | null | undefined): boolean;
+export declare function cloneRequestPermissionProfile(permissions: RequestPermissionProfile): RequestPermissionProfile;

package/dist/internal/codex/core/src/request_user_input.d.ts

@@ -0,0 +1,47 @@
+import { ModeKind, type CollaborationMode } from "./config-types.js";
+import type { ToolSpec } from "./tools/tool_spec.js";
+export declare const REQUEST_USER_INPUT_TOOL_NAME = "request_user_input";
+export type RequestUserInputQuestionOption = {
+    label: string;
+    description: string;
+};
+export type RequestUserInputQuestion = {
+    id: string;
+    header: string;
+    question: string;
+    isOther?: boolean;
+    isSecret?: boolean;
+    options?: RequestUserInputQuestionOption[];
+};
+export type NormalizedRequestUserInputQuestion = {
+    id: string;
+    header: string;
+    question: string;
+    isOther: boolean;
+    isSecret: boolean;
+    options: RequestUserInputQuestionOption[];
+};
+export type RequestUserInputArgs = {
+    questions: RequestUserInputQuestion[];
+};
+export type NormalizedRequestUserInputArgs = {
+    questions: NormalizedRequestUserInputQuestion[];
+};
+export type RequestUserInputAnswer = {
+    answers: string[];
+};
+export type RequestUserInputResponse = {
+    answers: Record<string, RequestUserInputAnswer>;
+};
+export type RequestUserInputEvent = {
+    /** Responses API call id for the associated tool call, if available. */
+    call_id: string;
+    /** Turn id that this request belongs to. */
+    turn_id: string;
+    questions: NormalizedRequestUserInputQuestion[];
+};
+export declare function normalizeRequestUserInputArgs(args: RequestUserInputArgs): NormalizedRequestUserInputArgs;
+export declare function requestUserInputAvailableModes(): ModeKind[];
+export declare function createRequestUserInputTool(description: string): ToolSpec;
+export declare function requestUserInputUnavailableMessage(mode: CollaborationMode["mode"], availableModes: readonly ModeKind[]): string | null;
+export declare function requestUserInputToolDescription(availableModes: readonly ModeKind[]): string;

package/dist/internal/codex/core/src/session/rollout-reconstruction.d.ts

@@ -0,0 +1,11 @@
+import type { ResponseItem, RolloutItem, TurnContextItem } from "../protocol.js";
+export type PreviousTurnSettings = {
+    model?: string | null;
+    realtime_active?: boolean | null;
+};
+export type RolloutReconstruction = {
+    history: ResponseItem[];
+    previous_turn_settings: PreviousTurnSettings | null;
+    reference_context_item: TurnContextItem | null;
+};
+export declare function reconstructHistoryFromRollout(rolloutItems: RolloutItem[]): RolloutReconstruction;

package/dist/internal/codex/core/src/session/session-settings.d.ts

@@ -0,0 +1,29 @@
+import { type CollaborationMode } from "../config-types.js";
+import type { ActivePermissionProfile, ApprovalsReviewer, AskForApproval, PermissionProfile, Personality, ReasoningEffortConfig, ReasoningSummaryConfig, SandboxPolicy, ServiceTier, TurnEnvironmentSelection, UserInputOp, UserInputWithTurnContextOp, UserTurnOp, OverrideTurnContextOp, WindowsSandboxLevel } from "../protocol.js";
+import type { SessionConfiguration } from "./session.js";
+export type SessionSettingsUpdate = {
+    cwd?: string;
+    approval_policy?: AskForApproval;
+    approvals_reviewer?: ApprovalsReviewer | null;
+    sandbox_policy?: SandboxPolicy;
+    permission_profile?: PermissionProfile | null;
+    active_permission_profile?: ActivePermissionProfile | null;
+    windows_sandbox_level?: WindowsSandboxLevel | null;
+    model?: string;
+    effort?: ReasoningEffortConfig | null;
+    summary?: ReasoningSummaryConfig;
+    service_tier?: ServiceTier | null;
+    collaboration_mode?: CollaborationMode;
+    personality?: Personality | null;
+    environments?: TurnEnvironmentSelection[];
+    persist_environments?: boolean;
+    final_output_json_schema?: unknown;
+};
+export declare class SessionSettingsUpdateError extends Error {
+    constructor(message: string);
+}
+export declare function sessionSettingsUpdateFromUserTurn(op: UserTurnOp): SessionSettingsUpdate;
+export declare function sessionSettingsUpdateFromUserInput(op: UserInputOp): SessionSettingsUpdate;
+export declare function sessionSettingsUpdateFromUserInputWithTurnContext(op: UserInputWithTurnContextOp, current: SessionConfiguration): SessionSettingsUpdate;
+export declare function sessionSettingsUpdateFromOverrideTurnContext(op: OverrideTurnContextOp, current: SessionConfiguration): SessionSettingsUpdate;
+export declare function applySessionSettingsUpdate(configuration: SessionConfiguration, updates: SessionSettingsUpdate): SessionConfiguration;

package/dist/internal/codex/core/src/session/session.d.ts

@@ -0,0 +1,226 @@
+import { type CollaborationMode } from "../config-types.js";
+import { type ResolvedConfig } from "../../../config/src/index.js";
+import type { ThreadId } from "../ids.js";
+import type { LiveThread } from "../thread-store/live-thread.js";
+import type { ActivePermissionProfile, ApprovalsReviewer, AskForApproval, BaseInstructions, DynamicToolResponse, DynamicToolSpec, EventMsg, Op, PermissionProfile, Personality, RateLimitSnapshot, ReasoningEffortConfig, ReasoningSummaryConfig, ResponseItem, RolloutItem, SandboxPolicy, ServiceTier, SessionSource, Submission, TokenUsage, TokenUsageInfo, TurnContextItem, ThreadGoal, TruncationPolicy, TurnEnvironmentSelection, UserInput, WindowsSandboxLevel, CompactedItem } from "../protocol.js";
+import { type CreateGoalRequest, type ThreadGoalStore } from "../goals.js";
+import { Hooks } from "../hooks/index.js";
+import { AgentControl } from "../agent/mod.js";
+import { ActiveTurn, type PendingDynamicTool, type PendingRequestPermissions, type PendingUserInput } from "../state/turn.js";
+import { TaskKind, type RunningTask, type SessionTask, type SessionTaskResult } from "../tasks/mod.js";
+import type { NormalizedRequestUserInputArgs, RequestUserInputResponse } from "../request_user_input.js";
+import { type RequestPermissionProfile, type RequestPermissionsArgs, type RequestPermissionsResponse } from "../request_permissions.js";
+import { TurnContext } from "./turn-context.js";
+import { type SessionSettingsUpdate } from "./session-settings.js";
+import type { ToolsConfig } from "../tools/spec_plan_types.js";
+import { type McpConnectionManager, type McpResourceListParams, type McpResourceListResponse, type McpResourceReadParams, type McpResourceReadResponse, type McpResourceTemplateListResponse, type McpRuntimeEnvironment, type McpServerElicitationRequest, type McpServerElicitationResponse, type McpServerRefreshConfig, type McpServerToolCallParams, type McpServerToolCallResponse, type McpServerStatus, type McpToolInfo, type McpRequestId } from "../mcp.js";
+import { type ModelInfo } from "../model-provider.js";
+export type Event = {
+    id: string;
+    msg: EventMsg;
+};
+export type SessionConfiguration = {
+    provider: string;
+    model: string;
+    model_info?: ModelInfo | null;
+    collaboration_mode: CollaborationMode;
+    reasoning_effort?: ReasoningEffortConfig | null;
+    reasoning_summary: ReasoningSummaryConfig;
+    service_tier?: ServiceTier | null;
+    base_instructions: BaseInstructions;
+    developer_instructions?: string | null;
+    user_instructions?: string | null;
+    personality?: Personality | null;
+    cwd: string;
+    approval_policy: AskForApproval;
+    approvals_reviewer?: ApprovalsReviewer | null;
+    sandbox_policy: SandboxPolicy;
+    permission_profile: PermissionProfile;
+    active_permission_profile?: ActivePermissionProfile | null;
+    windows_sandbox_level?: WindowsSandboxLevel | null;
+    environments: TurnEnvironmentSelection[];
+    session_source: SessionSource;
+    dynamic_tools: DynamicToolSpec[];
+    tools: ToolsConfig;
+    final_output_json_schema?: unknown;
+    truncation_policy?: TruncationPolicy | null;
+};
+export type SessionParams = {
+    threadId: ThreadId;
+    configuration: SessionConfiguration;
+    liveThread?: LiveThread | null;
+    idGenerator?: () => string;
+    eventSink?: (event: Event) => void;
+    now?: () => number;
+    initialHistory?: RolloutItem[] | null;
+    rolloutPath?: string | null;
+    forkedFromId?: ThreadId | null;
+    threadName?: string | null;
+    threadSource?: string | null;
+    hooks?: Hooks;
+    threadGoalStore?: ThreadGoalStore | null;
+    mcpConnectionManager?: McpConnectionManager | null;
+    agentControl?: AgentControl | null;
+};
+export type SessionConfigurationFromConfigOptions = {
+    previous_base_instructions?: BaseInstructions | null;
+    model_info?: ModelInfo | null;
+};
+export declare const SteerInputErrorKind: {
+    readonly EmptyInput: "empty_input";
+    readonly NoActiveTurn: "no_active_turn";
+    readonly ExpectedTurnMismatch: "expected_turn_mismatch";
+    readonly ActiveTurnNotSteerable: "active_turn_not_steerable";
+};
+export type SteerInputErrorKind = (typeof SteerInputErrorKind)[keyof typeof SteerInputErrorKind];
+export declare class SteerInputError extends Error {
+    readonly kind: SteerInputErrorKind;
+    readonly input: UserInput[];
+    private constructor();
+    static emptyInput(): SteerInputError;
+    static noActiveTurn(input: UserInput[]): SteerInputError;
+    static expectedTurnMismatch(input: {
+        expected: string;
+        actual: string;
+        items: UserInput[];
+    }): SteerInputError;
+    static activeTurnNotSteerable(input: {
+        kind: TaskKind;
+        items: UserInput[];
+    }): SteerInputError;
+}
+export declare function defaultSessionConfiguration(overrides?: Partial<SessionConfiguration>): SessionConfiguration;
+export declare function session_configuration_from_config(config: ResolvedConfig, options?: SessionConfigurationFromConfigOptions): SessionConfiguration;
+export declare function resolve_session_base_instructions(config: ResolvedConfig, options?: SessionConfigurationFromConfigOptions): BaseInstructions;
+export declare function sessionConfigurationPermissionProfile(configuration: SessionConfiguration): PermissionProfile;
+export declare function sessionConfigurationActivePermissionProfile(configuration: SessionConfiguration): ActivePermissionProfile | null;
+export declare function sessionConfigurationSandboxPolicy(configuration: SessionConfiguration): SandboxPolicy;
+export declare function turn_context_from_config(config: ResolvedConfig, submissionId: string, trace?: Submission["trace"]): TurnContext;
+export declare class Session {
+    readonly threadId: ThreadId;
+    readonly emittedEvents: Event[];
+    private readonly liveThread;
+    private readonly idGenerator;
+    private readonly eventSink?;
+    private readonly now;
+    private configuration;
+    private readonly rolloutPath;
+    private readonly forkedFromId;
+    private readonly threadName;
+    private readonly threadSource;
+    private readonly initialMessages;
+    private readonly hook_runtime;
+    private readonly agent_control;
+    private readonly goal_runtime;
+    private readonly mcp_connection_manager;
+    private readonly state;
+    private sessionConfiguredSent;
+    private sessionStartHooksRan;
+    private readonly idle_pending_input;
+    private readonly session_permission_grants;
+    activeTurn: ActiveTurn | null;
+    constructor(params: SessionParams);
+    private get token_info();
+    private set token_info(value);
+    private get latest_rate_limits();
+    private set latest_rate_limits(value);
+    private get reference_context_item();
+    private set reference_context_item(value);
+    private get previous_turn_settings();
+    private set previous_turn_settings(value);
+    submit(op: Op): Promise<string>;
+    submit_with_id(submission: Submission): Promise<void>;
+    insertPendingUserInput(key: string, pending: PendingUserInput): void;
+    insertPendingDynamicTool(key: string, pending: PendingDynamicTool): void;
+    insertPendingRequestPermissions(key: string, pending: PendingRequestPermissions): void;
+    steer_input(input: UserInput[], expected_turn_id?: string | null): Promise<string>;
+    inject_response_items(input: UserInput[]): Promise<boolean>;
+    prepend_pending_input(input: UserInput[]): Promise<boolean>;
+    get_pending_input(): Promise<UserInput[]>;
+    has_pending_input(): Promise<boolean>;
+    queue_response_items_for_next_turn(items: UserInput[]): Promise<void>;
+    take_queued_response_items_for_next_turn(): Promise<UserInput[]>;
+    collaboration_mode(): CollaborationMode;
+    granted_session_permissions(): RequestPermissionProfile[];
+    hooks(): Hooks;
+    agentControl(): AgentControl;
+    configure_session(initialMessages?: EventMsg[] | null): Promise<void>;
+    strict_auto_review_enabled_for_turn(): boolean;
+    request_user_input(turnContext: TurnContext, callId: string, args: NormalizedRequestUserInputArgs): Promise<RequestUserInputResponse | null>;
+    request_permissions(turnContext: TurnContext, callId: string, args: RequestPermissionsArgs): Promise<RequestPermissionsResponse | null>;
+    refresh_mcp_servers_now(turnContext: TurnContext, config: McpServerRefreshConfig, environment?: McpRuntimeEnvironment): Promise<void>;
+    refresh_mcp_servers_if_requested(turnContext: TurnContext, config?: McpServerRefreshConfig | null): Promise<void>;
+    list_mcp_server_statuses(): Promise<McpServerStatus[]>;
+    list_mcp_tools(): Promise<McpToolInfo[]>;
+    list_resources(params: McpResourceListParams): Promise<McpResourceListResponse>;
+    list_resource_templates(params: McpResourceListParams): Promise<McpResourceTemplateListResponse>;
+    read_resource(_paramsTurnContext: TurnContext | null, params: McpResourceReadParams): Promise<McpResourceReadResponse>;
+    call_tool(turnContext: TurnContext, params: McpServerToolCallParams): Promise<McpServerToolCallResponse>;
+    resolve_mcp_tool_info(toolName: string): Promise<McpToolInfo | null>;
+    request_mcp_server_elicitation(turnContext: TurnContext, serverName: string, id: McpRequestId, request: McpServerElicitationRequest): Promise<McpServerElicitationResponse | null>;
+    request_dynamic_tool(turnContext: TurnContext, callId: string, toolName: string, argumentsValue: unknown): Promise<DynamicToolResponse | null>;
+    startTurn(submission: Submission): Promise<TurnContext>;
+    startCompactTurn(submission: Submission): Promise<TurnContext>;
+    start_task(input: {
+        turnContext: TurnContext;
+        task?: SessionTask;
+        kind?: TaskKind;
+        abortController?: AbortController;
+    }): Promise<RunningTask>;
+    spawn_task(input: {
+        turnContext: TurnContext;
+        task: SessionTask;
+        input: UserInput[];
+        abortController?: AbortController;
+    }): Promise<SessionTaskResult>;
+    recordCompactedItem(item: CompactedItem): Promise<void>;
+    record_into_history(turnContext: TurnContext, items: readonly ResponseItem[]): void;
+    record_conversation_items(turnContext: TurnContext, items: readonly ResponseItem[]): Promise<void>;
+    completeTurn(turnContext: TurnContext, lastAgentMessage?: string | null): Promise<void>;
+    on_task_finished(turnContext: TurnContext, result: SessionTaskResult): Promise<void>;
+    failTurn(turnContext: TurnContext, error: unknown): Promise<void>;
+    abortActiveTurn(reason?: "interrupted"): Promise<void>;
+    abort_all_tasks(reason?: "interrupted"): Promise<void>;
+    markFirstToken(turnContext: TurnContext): void;
+    update_token_usage_info(turnContext: TurnContext, tokenUsage?: TokenUsage | null): Promise<void>;
+    update_rate_limits(turnContext: TurnContext, newRateLimits: RateLimitSnapshot): Promise<void>;
+    token_usage_info(): TokenUsageInfo | null;
+    clone_history(): import("../index.js").ContextManager;
+    replace_history(items: ResponseItem[], referenceContextItem?: TurnContextItem | null): void;
+    replace_compacted_history(turnContext: TurnContext, items: ResponseItem[], referenceContextItem?: TurnContextItem | null): Promise<void>;
+    get_total_token_usage_breakdown(): import("../index.js").TotalTokenUsageBreakdown;
+    get_total_token_usage(): number;
+    get_thread_goal(): Promise<ThreadGoal | null>;
+    create_thread_goal(turnContext: TurnContext, request: CreateGoalRequest): Promise<ThreadGoal>;
+    update_thread_goal_complete(turnContext: TurnContext): Promise<ThreadGoal>;
+    note_tool_completed(turnContext: TurnContext, toolName: string): Promise<void>;
+    thread_goal_steering_items(): Promise<ResponseItem[]>;
+    latest_rate_limit_snapshot(): RateLimitSnapshot | null;
+    private send_token_count_event;
+    private send_thread_goal_update_if_needed;
+    private send_thread_goal_updated;
+    private userInputOrTurn;
+    private createTurnContext;
+    new_turn_with_sub_id(submissionId: string, updates: SessionSettingsUpdate, trace?: Submission["trace"]): Promise<TurnContext>;
+    new_default_turn_with_sub_id(submissionId: string, trace?: Submission["trace"]): Promise<TurnContext>;
+    turn_context_from_config(config: ResolvedConfig, submissionId: string, trace?: Submission["trace"]): TurnContext;
+    private turnContextFromConfiguration;
+    private overrideTurnContext;
+    private sessionSettingsUpdateFromOp;
+    private notifyUserInputResponse;
+    notify_request_permissions_response(callId: string, response: RequestPermissionsResponse): void;
+    resolve_elicitation(serverName: string, id: McpRequestId, response: McpServerElicitationResponse): Promise<void>;
+    private record_granted_request_permissions;
+    notify_dynamic_tool_response(callId: string, response: DynamicToolResponse): void;
+    private setThreadMemoryMode;
+    private shutdown;
+    private interrupt;
+    private threadRollback;
+    private compactWithoutModel;
+    send_event(turnContext: TurnContext, msg: EventMsg): Promise<void>;
+    recordResponseItem(turnContext: TurnContext, item: ResponseItem): Promise<void>;
+    record_context_updates_and_set_reference_context_item(turnContext: TurnContext): Promise<void>;
+    send_event_raw(event: Event): Promise<void>;
+    private deliver_event_raw;
+    private persist_rollout_items;
+}

package/dist/internal/codex/core/src/session/turn-context.d.ts

@@ -0,0 +1,71 @@
+import type { CollaborationMode } from "../config-types.js";
+import type { ActivePermissionProfile, ApprovalsReviewer, AskForApproval, DynamicToolSpec, PermissionProfile, Personality, ReasoningEffortConfig, ReasoningSummaryConfig, SandboxPolicy, ServiceTier, SessionSource, TruncationPolicy, TurnContextItem, TurnEnvironmentSelection, W3cTraceContext, WindowsSandboxLevel } from "../protocol.js";
+import type { ToolsConfig } from "../tools/spec_plan_types.js";
+import { TurnTimingState } from "./turn-timing.js";
+import { type ModelInfo } from "../model-provider.js";
+export type TurnContextParams = {
+    sub_id: string;
+    trace?: W3cTraceContext;
+    cwd: string;
+    current_date?: string;
+    timezone?: string;
+    approval_policy: AskForApproval;
+    approvals_reviewer?: ApprovalsReviewer | null;
+    sandbox_policy: SandboxPolicy;
+    permission_profile?: PermissionProfile | null;
+    active_permission_profile?: ActivePermissionProfile | null;
+    windows_sandbox_level?: WindowsSandboxLevel | null;
+    model: string;
+    model_info?: ModelInfo | null;
+    personality?: Personality | null;
+    collaboration_mode?: CollaborationMode | null;
+    effort?: ReasoningEffortConfig | null;
+    summary: ReasoningSummaryConfig;
+    service_tier?: ServiceTier | null;
+    session_source: SessionSource;
+    environments: TurnEnvironmentSelection[];
+    base_instructions?: string | null;
+    user_instructions?: string | null;
+    developer_instructions?: string | null;
+    final_output_json_schema?: unknown;
+    truncation_policy?: TruncationPolicy | null;
+    dynamic_tools: DynamicToolSpec[];
+    tools: ToolsConfig;
+};
+export declare class TurnContext {
+    readonly sub_id: string;
+    readonly trace_id?: string;
+    readonly cwd: string;
+    readonly current_date?: string;
+    readonly timezone?: string;
+    readonly approval_policy: AskForApproval;
+    readonly approvals_reviewer?: ApprovalsReviewer | null;
+    readonly sandbox_policy: SandboxPolicy;
+    readonly permission_profile?: PermissionProfile | null;
+    readonly active_permission_profile?: ActivePermissionProfile | null;
+    readonly windows_sandbox_level?: WindowsSandboxLevel | null;
+    readonly model: string;
+    readonly model_info: ModelInfo;
+    readonly personality?: Personality | null;
+    readonly collaboration_mode?: CollaborationMode | null;
+    readonly effort?: ReasoningEffortConfig | null;
+    readonly summary: ReasoningSummaryConfig;
+    readonly service_tier?: ServiceTier | null;
+    readonly session_source: SessionSource;
+    readonly environments: TurnEnvironmentSelection[];
+    readonly base_instructions?: string | null;
+    readonly user_instructions?: string | null;
+    readonly developer_instructions?: string | null;
+    readonly final_output_json_schema?: unknown;
+    readonly truncation_policy?: TruncationPolicy | null;
+    readonly dynamic_tools: DynamicToolSpec[];
+    readonly tools: ToolsConfig;
+    readonly turn_timing_state: TurnTimingState;
+    constructor(params: TurnContextParams);
+    toTurnContextItem(): TurnContextItem;
+    effectivePermissionProfile(): PermissionProfile;
+    effectiveSandboxPolicy(): SandboxPolicy;
+    model_context_window(): number | null;
+    auto_compact_token_limit(): number | null;
+    effectiveReasoningEffort(): ReasoningEffortConfig | null;
+}

package/dist/internal/codex/core/src/session/turn-timing.d.ts

@@ -0,0 +1,12 @@
+export type TurnTimingSnapshot = {
+    completed_at: number;
+    duration_ms: number;
+    time_to_first_token_ms: number | null;
+};
+export declare class TurnTimingState {
+    private started_at_ms;
+    private first_token_at_ms;
+    markTurnStarted(now: number): number;
+    markFirstToken(now: number): void;
+    completedAtAndDuration(now: number): TurnTimingSnapshot;
+}

package/dist/internal/codex/core/src/session/turn.d.ts

@@ -0,0 +1,35 @@
+import type { ResponseItem } from "../models.js";
+import type { RolloutItem, Submission } from "../protocol.js";
+import type { Session } from "./session.js";
+import type { TurnContext } from "./turn-context.js";
+import { ToolCallRuntime } from "../tools/parallel.js";
+import { ToolRouter } from "../tools/router.js";
+import type { ModelClient, ModelClientSessionHandle } from "../client.js";
+export type RunTurnParams = {
+    modelClient: ModelClient;
+    session: Session;
+    turn: TurnContext;
+    history: RolloutItem[];
+    submission: Submission;
+    signal?: AbortSignal;
+    completeTurn?: boolean;
+};
+export type SamplingRequestResult = {
+    turn: TurnContext;
+    modelInput: ResponseItem[];
+    lastAgentMessage: string | null;
+    steps: number;
+};
+export declare function runTurn(params: RunTurnParams): Promise<SamplingRequestResult>;
+export declare function run_sampling_request(params: {
+    session: Session;
+    turn: TurnContext;
+    router: ToolRouter;
+    toolRuntime?: ToolCallRuntime;
+    clientSession: ModelClientSessionHandle;
+    input: ResponseItem[];
+    maxSteps?: number;
+    signal?: AbortSignal;
+    completeTurn?: boolean;
+    includePromptContext?: boolean;
+}): Promise<SamplingRequestResult>;

package/dist/internal/codex/core/src/state/session.d.ts

@@ -0,0 +1,40 @@
+import { ContextManager, type TotalTokenUsageBreakdown } from "../context_manager/history.js";
+import type { RateLimitSnapshot, ResponseItem, TokenUsage, TokenUsageInfo, TruncationPolicy, TurnContextItem } from "../protocol.js";
+import type { PreviousTurnSettings } from "../session/rollout-reconstruction.js";
+import type { SessionConfiguration } from "../session/session.js";
+export type SessionStateParams = {
+    session_configuration: SessionConfiguration;
+    history?: ContextManager | null;
+    latest_rate_limits?: RateLimitSnapshot | null;
+    server_reasoning_included?: boolean;
+    previous_turn_settings?: PreviousTurnSettings | null;
+    reference_context_item?: TurnContextItem | null;
+    token_info?: TokenUsageInfo | null;
+};
+export declare class SessionState {
+    readonly session_configuration: SessionConfiguration;
+    readonly history: ContextManager;
+    private latest_rate_limits_value;
+    private server_reasoning_included_value;
+    private previous_turn_settings_value;
+    constructor(params: SessionStateParams);
+    record_items(items: Iterable<ResponseItem>, policy?: TruncationPolicy | null): void;
+    previous_turn_settings(): PreviousTurnSettings | null;
+    set_previous_turn_settings(value: PreviousTurnSettings | null): void;
+    clone_history(): ContextManager;
+    replace_history(items: ResponseItem[], referenceContextItem: TurnContextItem | null): void;
+    set_token_info(info: TokenUsageInfo | null): void;
+    set_reference_context_item(item: TurnContextItem | null): void;
+    reference_context_item(): TurnContextItem | null;
+    update_token_info_from_usage(usage: TokenUsage, modelContextWindow?: number | null): void;
+    token_info(): TokenUsageInfo | null;
+    set_rate_limits(snapshot: RateLimitSnapshot): void;
+    set_latest_rate_limits(snapshot: RateLimitSnapshot | null): void;
+    latest_rate_limits(): RateLimitSnapshot | null;
+    token_info_and_rate_limits(): [TokenUsageInfo | null, RateLimitSnapshot | null];
+    set_token_usage_full(contextWindow: number): void;
+    get_total_token_usage(serverReasoningIncluded?: boolean): number;
+    get_total_token_usage_breakdown(): TotalTokenUsageBreakdown;
+    set_server_reasoning_included(included: boolean): void;
+    server_reasoning_included(): boolean;
+}

package/dist/internal/codex/core/src/state/turn.d.ts

@@ -0,0 +1,83 @@
+import type { RequestUserInputResponse } from "../request_user_input.js";
+import type { McpRequestId, McpServerElicitationResponse } from "../mcp.js";
+import type { RequestPermissionProfile, RequestPermissionsResponse } from "../request_permissions.js";
+import { type InterAgentCommunication } from "../agent/mod.js";
+import type { DynamicToolResponse, TokenUsage, UserInput } from "../protocol.js";
+import type { TurnContext } from "../session/turn-context.js";
+import type { RunningTask, TaskKind } from "../tasks/mod.js";
+export declare const MailboxDeliveryPhase: {
+    readonly CurrentTurn: "CurrentTurn";
+    readonly NextTurn: "NextTurn";
+};
+export type MailboxDeliveryPhase = (typeof MailboxDeliveryPhase)[keyof typeof MailboxDeliveryPhase];
+export type PendingUserInput = {
+    resolve(response: RequestUserInputResponse | null): void;
+};
+export type PendingDynamicTool = {
+    resolve(response: DynamicToolResponse | null): void;
+};
+export type PendingRequestPermissions = {
+    resolve(response: RequestPermissionsResponse | null): void;
+};
+export type PendingMcpElicitation = {
+    resolve(response: McpServerElicitationResponse | null): void;
+};
+export type RunningTaskPlaceholder = {
+    sub_id: string;
+    kind: TaskKind;
+    turn_context: TurnContext;
+};
+export type RemovedTask = {
+    active_turn_is_empty: boolean;
+    task: RunningTask;
+};
+export declare const emptyTokenUsage: TokenUsage;
+export declare class TurnState {
+    private readonly pending_user_input;
+    private readonly pending_dynamic_tools;
+    private readonly pending_request_permissions;
+    private readonly pending_mcp_elicitations;
+    private pending_input;
+    private readonly mailbox;
+    private mailbox_delivery_phase;
+    private readonly permission_grants;
+    tool_calls: number;
+    has_memory_citation: boolean;
+    token_usage_at_turn_start: TokenUsage;
+    insertPendingUserInput(key: string, pending: PendingUserInput): PendingUserInput | undefined;
+    removePendingUserInput(key: string): PendingUserInput | undefined;
+    insertPendingDynamicTool(key: string, pending: PendingDynamicTool): PendingDynamicTool | undefined;
+    removePendingDynamicTool(key: string): PendingDynamicTool | undefined;
+    insertPendingRequestPermissions(key: string, pending: PendingRequestPermissions): PendingRequestPermissions | undefined;
+    removePendingRequestPermissions(key: string): PendingRequestPermissions | undefined;
+    insertPendingMcpElicitation(serverName: string, id: McpRequestId, pending: PendingMcpElicitation): PendingMcpElicitation | undefined;
+    removePendingMcpElicitation(serverName: string, id: McpRequestId): PendingMcpElicitation | undefined;
+    recordPermissionGrant(response: RequestPermissionsResponse): void;
+    grantedPermissions(): RequestPermissionProfile[];
+    strictAutoReviewEnabled(): boolean;
+    pushPendingInput(input: UserInput): void;
+    prependPendingInput(input: UserInput[]): void;
+    takePendingInput(): UserInput[];
+    hasPendingInput(): boolean;
+    clearPending(): void;
+    cancelPending(): void;
+    sendMailboxMessage(communication: Omit<InterAgentCommunication, "seq">): number;
+    drainMailbox(): InterAgentCommunication[];
+    hasMailboxPending(): boolean;
+    hasMailboxPendingTriggerTurn(): boolean;
+    acceptMailboxDeliveryForCurrentTurn(): void;
+    acceptsMailboxDeliveryForCurrentTurn(): boolean;
+    setMailboxDeliveryPhase(phase: MailboxDeliveryPhase): void;
+}
+export declare class ActiveTurn {
+    private readonly tasks;
+    readonly turn_state: TurnState;
+    addTask(task: RunningTask): void;
+    removeTask(sub_id: string): RemovedTask | undefined;
+    drainTasks(): RunningTask[];
+    firstTask(): RunningTask | null;
+    hasTask(sub_id: string): boolean;
+    clearPending(): void;
+    cancelPending(): void;
+    get size(): number;
+}