import { pipe } from "effect/Function";
import * as DocumentText from "../../provider/DocumentText.ts";
import { revertCodexThread } from "../../provider/CodexThreadRevert.ts";
import { historyResponseItems } from "@t3tools/provider-core/server/handoffBudget";
import { makeProviderTextDeltaCoalescer } from "./ProviderTextDeltaCoalescer.ts";
import {
mcpToolPresentation,
type McpToolPresentation,
} from "../../provider/CodexToolPresentation.ts";
import {
makeCodexTurnTokenUsageState,
getCodexTurnAccumulator,
accumulateCodexTurnTokenUsage,
completeCodexTurnTokenUsage,
type CodexTurnTokenUsageState,
} from "../../provider/CodexTurnTokenUsage.ts";
import type { ManagedServerProvider } from "@t3tools/provider-core/server/snapshot";
import type { CodexEffectiveRuntime } from "../../provider/CodexManagedRuntime.ts";
import { classifyCodexManagedError } from "../../provider/CodexManagedErrors.ts";
import {
buildCodexInitializeParams,
codexAppServerEnvironment,
codexDefaultReasoningEffortOverride,
} from "../../provider/CodexProvider.ts";
import {
codexRateLimitsToUpdate,
mergeCodexRateLimits,
codexUsageLimitResetAt,
type CodexRateLimitSnapshot,
} from "../../provider/codexUsageLimits.ts";
import {
CodexSettings,
defaultInstanceIdForDriver,
isOrchestrationV2WorkActive,
type OrchestrationV2GoalCommand,
OrchestrationV2ProviderGoal,
parseGoalCommand,
ProviderDriverKind,
ProviderSetupError,
type ServerProviderCompatibilityAdvisory,
} from "@t3tools/contracts";
import { SKILL_MENTION_PATTERN } from "@t3tools/shared/composerInlineTokens";
import { AgentScope } from "@t3tools/shared/AgentScope";
import * as HostProcess from "@t3tools/shared/HostProcess";
import {
COMPUTER_USE_TOOL_SOURCE,
dynamicToolSurface,
dynamicToolTitle,
} from "@t3tools/shared/toolActivity";
import { getModelSelectionStringOptionValue, modelSelectionsEqual } from "@t3tools/shared/model";
import { appendGeneratedImageEmbeds } from "@t3tools/shared/generatedImageMarkdown";
import { resolveSpawnCommand } from "@t3tools/shared/shell";
import { mcpToolResultOutput } from "@t3tools/shared/toolOutput";
import type {
ChatAttachment,
OrchestrationV2AppThread,
OrchestrationV2ConversationMessage,
OrchestrationV2ExecutionNode,
ModelSelection,
OrchestrationV2PlanArtifact,
OrchestrationV2ProviderCapabilities,
OrchestrationV2ProviderFailure,
OrchestrationV2ProviderRetry,
OrchestrationV2ProviderSession,
OrchestrationV2ProviderThread,
OrchestrationV2ProviderTurn,
OrchestrationV2PlanStep,
OrchestrationV2RuntimeRequest,
OrchestrationV2Subagent,
OrchestrationV2TurnItem,
ProviderUserInputAnswers,
ProviderApprovalDecision,
ProviderApprovalOption,
ProviderRequestKind,
ProviderThreadId,
ProviderTurnId,
ProviderInstanceId,
RuntimeMode,
ThreadId,
} from "@t3tools/contracts";
import * as CodexClient from "effect-codex-app-server/client";
import * as CodexErrors from "effect-codex-app-server/errors";
import * as CodexSchema from "effect-codex-app-server/schema";
import * as Cause from "effect/Cause";
import * as Context from "effect/Context";
import * as Digest from "effect/crypto/Digest";
import * as DateTime from "effect/DateTime";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as FileSystem from "effect/FileSystem";
import * as Function from "effect/Function";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";
import { ChildProcess, ChildProcessSpawner } from "effect/process";
import { resolveAttachmentPath, resolveAttachmentPathById } from "../../attachmentStore.ts";
import * as PortScanner from "../../preview/PortScanner.ts";
import { getCodexServiceTierOptionValue } from "../../codexModelOptions.ts";
import { ServerConfig } from "../../config.ts";
import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
import { buildCodexAdditionalContext } from "../../provider/CodexDeveloperInstructions.ts";
import {
describeMcpElicitation,
toMcpElicitationResponse,
} from "../../provider/CodexMcpElicitation.ts";
import {
materializeCodexShadowHome,
resolveCodexHomeLayout,
} from "../../provider/Drivers/CodexHomeLayout.ts";
import {
boundProviderEventForLogging,
shouldPersistProviderEvent,
} from "../../provider/EventNdjsonLogger.ts";
import * as ProviderEventLoggers from "@t3tools/provider-core/server/ProviderEventLoggers";
import { codexAppServerArgs, resolveCodexLaunchArgs } from "../../provider/codexLaunchArgs.ts";
import { mergeProviderInstanceEnvironment } from "@t3tools/provider-core/server/instanceEnvironment";
import * as McpProviderSession from "@t3tools/provider-core/server/mcpSession";
import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
import {
MCP_APP_EXTENSION_ID,
MCP_APP_MIME_TYPE,
MCP_APP_OUTPUT_KEY,
MCP_APP_RESOURCE_SCHEME,
} from "@t3tools/shared/mcpApp";
import { snapshotMcpApp } from "../../mcpApps/McpAppSnapshot.ts";
import {
ProviderAdapterDriverCreateError,
type ProviderAdapterDriverCreateInput,
} from "@t3tools/provider-core/server/adapterDriver";
import * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
import { backgroundWorkNotification } from "@t3tools/provider-core/server/notification";
import {
makeProviderFailure,
makeProviderFailureTurnItem,
makeProviderRetryTurnItem,
} from "@t3tools/provider-core/server/failure";
import { turnScopedSelectionTransition } from "@t3tools/provider-core/server/selectionTransition";
import {
isProviderNativeImageAttachment,
providerMessageTextWithAttachmentPaths,
} from "@t3tools/provider-core/server/attachmentPrompt";
import {
makeSubagentChildThread,
makeSubagentConversationArtifacts,
subagentThreadTitle,
} from "@t3tools/provider-core/server/subagentProjection";
import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
const CODEX_PROVIDER = ProviderDriverKind.make("codex");
const CODEX_CAPACITY_MAX_RETRIES = 5;
export const CODEX_DRIVER_KIND = CODEX_PROVIDER;
export const CODEX_DEFAULT_INSTANCE_ID = defaultInstanceIdForDriver(CODEX_DRIVER_KIND);
type CodexFileChangeKinds = Readonly<
Record<string, CodexSchema.V2ItemStartedNotification__PatchChangeKind>
>;
function codexFileChangeApprovalPrompt(input: {
readonly reason?: string | null;
readonly grantRoot?: string | null;
readonly fileChanges?: CodexFileChangeKinds;
}): string | undefined {
const reason = input.reason?.trim();
if (reason) return reason;
const entries = Object.entries(input.fileChanges ?? {}).toSorted(([left], [right]) =>
left.localeCompare(right),
);
if (entries.length > 0) {
const described = entries.slice(0, 20).map(([path, change]) => {
const movePath = change.type === "update" ? change.move_path : undefined;
return movePath ? `${change.type} ${path} -> ${movePath}` : `${change.type} ${path}`;
});
const remaining = entries.length - described.length;
return remaining > 0 ? `${described.join("\n")}\n+${remaining} more` : described.join("\n");
}
return input.grantRoot?.trim() || undefined;
}
// Reasoning-effort changes preserve the tokenizer and context window; other changes need fresh telemetry.
export function canReuseCodexContextUsage(previous: ModelSelection, next: ModelSelection): boolean {
return modelSelectionsEqual(
{
...previous,
options: (previous.options ?? []).filter((option) => option.id !== "reasoningEffort"),
},
{ ...next, options: (next.options ?? []).filter((option) => option.id !== "reasoningEffort") },
);
}
export function codexProviderTurnTokenUsage(
tokenUsage: CodexSchema.V2ThreadTokenUsageUpdatedNotification["tokenUsage"],
updatedAt: string,
) {
return {
usedTokens: Math.max(0, tokenUsage.last.totalTokens),
maxTokens: tokenUsage.modelContextWindow ?? null,
inputTokens: Math.max(0, tokenUsage.last.inputTokens),
cachedInputTokens: Math.max(0, tokenUsage.last.cachedInputTokens),
outputTokens: Math.max(0, tokenUsage.last.outputTokens),
reasoningOutputTokens: Math.max(0, tokenUsage.last.reasoningOutputTokens),
updatedAt,
};
}
const CODEX_ASSISTANT_DELTA_FLUSH_INTERVAL_MS = 50;
// Plan flushes store three copies; use the client's assistant-text cadence.
const CODEX_PLAN_DELTA_FLUSH_INTERVAL_MS = 400;
const CodexBackgroundTerminalTerminateResponse = Schema.Struct({
terminated: Schema.Boolean,
});
const CodexBackgroundTerminalsListResponse = Schema.Struct({
data: Schema.Array(
Schema.Struct({
processId: Schema.String,
}),
),
nextCursor: Schema.NullOr(Schema.String),
});
type CodexBackgroundTerminalsListPage = typeof CodexBackgroundTerminalsListResponse.Type;
const decodeCodexBackgroundTerminalTerminateResponse = Schema.decodeUnknownEffect(
CodexBackgroundTerminalTerminateResponse,
);
const decodeCodexBackgroundTerminalsListResponse = Schema.decodeUnknownEffect(
CodexBackgroundTerminalsListResponse,
);
const CODEX_CLIENT_CAPABILITIES = {
experimentalApi: true,
optOutNotificationMethods: ["turn/diff/updated"],
extensions: { [MCP_APP_EXTENSION_ID]: { mimeTypes: [MCP_APP_MIME_TYPE] } },
} as const;
export const CodexProviderCapabilitiesV2 = {
sessions: {
supportsMultipleProviderThreadsPerSession: true,
supportsModelSwitchInSession: true,
supportsProviderSwitchingViaHandoff: true,
supportsRuntimeModeSwitchInSession: true,
pendingRequestsSurviveRestart: false,
},
threads: {
canCreateEmptyThread: true,
canReadThreadSnapshot: true,
canRollbackThread: true,
canForkThread: true,
canForkFromTurn: true,
canForkFromSubagentThread: true,
exposesNativeThreadId: true,
},
turns: {
exposesNativeTurnId: true,
emitsTurnStarted: true,
emitsTurnCompleted: true,
supportsInterrupt: true,
supportsActiveSteering: true,
supportsSteeringByInterruptRestart: true,
supportsQueuedMessages: true,
terminalStatusQuality: "strong",
},
streaming: {
streamsAssistantText: true,
streamsReasoning: true,
streamsToolOutput: true,
streamsPlanText: true,
emitsMessageCompleted: true,
},
tools: {
exposesToolItemIds: true,
emitsToolStarted: true,
emitsToolCompleted: true,
emitsToolOutput: true,
supportsMcpTools: true,
supportsDynamicToolCallbacks: true,
},
approvals: {
supportsCommandApproval: true,
supportsFileReadApproval: true,
supportsFileChangeApproval: true,
supportsApplyPatchApproval: true,
approvalsHaveNativeRequestIds: true,
approvalCallbacksAreLiveOnly: true,
approvalsCanOriginateFromSubagents: true,
},
planning: {
emitsPlanUpdated: true,
emitsTodoList: true,
emitsProposedPlan: true,
supportsStructuredQuestions: true,
planDeltasHaveItemIds: true,
},
subagents: {
supportsSubagents: true,
exposesSubagentThreadIds: true,
emitsSubagentLifecycle: true,
canWaitForSubagents: true,
canCloseSubagents: true,
canForkSubagentThread: true,
},
context: {
acceptsSystemContext: true,
acceptsDeveloperContext: true,
acceptsSyntheticUserContext: true,
canGenerateSummaries: true,
canConsumeHandoffSummaries: true,
supportsDeltaHandoff: true,
supportsFullThreadHandoff: true,
maxRecommendedHandoffChars: null,
},
checkpointing: {
appCanCheckpointFilesystem: true,
supportsNestedCheckpointScopes: true,
providerCanRollbackConversation: true,
providerRollbackReturnsSnapshot: true,
providerCanReadConversationSnapshot: true,
},
identity: {
nativeThreadIds: "strong",
nativeTurnIds: "strong",
nativeItemIds: "strong",
nativeRequestIds: "strong",
},
runtimePolicy: {
enforcement: "native",
},
} satisfies OrchestrationV2ProviderCapabilities;
function toProtocolError(
detail: string,
payload?: unknown,
): ProviderAdapter.ProviderAdapterProtocolError {
return new ProviderAdapter.ProviderAdapterProtocolError({
driver: CODEX_PROVIDER,
detail,
...(payload === undefined ? {} : { payload }),
});
}
const CODEX_THREAD_IN_USE_MESSAGE =
"This conversation is open in another Codex client, such as the Codex app, the Codex CLI, or an IDE extension. Codex lets one client write to a conversation at a time. Quit that client, then send your message again.";
const isCodexAppServerRequestError = Schema.is(CodexErrors.CodexAppServerRequestError);
// Codex holds a per-thread writer lock for as long as a thread stays loaded in
// any app-server sharing the same CODEX_HOME, and reports a conflict this way.
function isCodexActiveWriterError(error: unknown): boolean {
return (
isCodexAppServerRequestError(error) &&
error.code === -32600 &&
error.errorMessage.includes("already has an active writer")
);
}
function codexTimestamp(seconds: number | null | undefined): DateTime.Utc {
return seconds === null || seconds === undefined
? DateTime.nowUnsafe()
: DateTime.makeUnsafe(seconds * 1000);
}
function codexUserMessageText(
content: ReadonlyArray<CodexSchema.V2ItemCompletedNotification__UserInput>,
): string {
return content
.flatMap((item) => (item.type === "text" ? [item.text] : []))
.join("\n")
.trim();
}
function mapCodexTurnStatus(
status: CodexSchema.V2TurnCompletedNotification__TurnStatus,
): OrchestrationV2ProviderTurn["status"] {
switch (status) {
case "completed":
return "completed";
case "interrupted":
return "interrupted";
case "failed":
return "failed";
case "inProgress":
return "running";
}
}
function providerTurnStatusToTerminal(
status: OrchestrationV2ProviderTurn["status"],
): Extract<ProviderAdapter.ProviderAdapterV2Event, { type: "turn.terminal" }>["status"] {
switch (status) {
case "completed":
return "completed";
case "interrupted":
return "interrupted";
case "failed":
return "failed";
case "cancelled":
return "cancelled";
case "pending":
case "running":
return "failed";
}
}
function codexItemStatus(status: "inProgress" | "completed" | "failed" | "declined"): {
readonly node: OrchestrationV2ExecutionNode["status"];
readonly turnItem: OrchestrationV2TurnItem["status"];
readonly completed: boolean;
} {
switch (status) {
case "inProgress":
return { node: "running", turnItem: "running", completed: false };
case "completed":
return {
node: "completed",
turnItem: "completed",
completed: true,
};
case "failed":
return { node: "failed", turnItem: "failed", completed: true };
case "declined":
return {
node: "cancelled",
turnItem: "cancelled",
completed: true,
};
}
}
/**
* The composers let a skill be typed with any currency sigil (`€review`), but
* Codex only parses `$name` as a skill mention.
*/
function codexSkillMentionText(text: string): string {
return text.replace(SKILL_MENTION_PATTERN, "$1$$2");
}
const BACKGROUND_COMMAND_DETAIL_COMMAND_MAX_LENGTH = 200;
const BACKGROUND_COMMAND_DETAIL_OUTPUT_TAIL_MAX_LENGTH = 1_000;
function codexBackgroundCommandDetail(item: {
readonly command: string;
readonly exitCode?: number | null | undefined;
readonly aggregatedOutput?: string | null | undefined;
}): string {
// Codex rejects a turn/start with a lone surrogate and never answers it, so cut on code points.
let commandEnd = BACKGROUND_COMMAND_DETAIL_COMMAND_MAX_LENGTH;
const finalCommandUnit = item.command.charCodeAt(commandEnd - 1);
if (finalCommandUnit >= 0xd800 && finalCommandUnit <= 0xdbff) commandEnd -= 1;
const command =
item.command.length > BACKGROUND_COMMAND_DETAIL_COMMAND_MAX_LENGTH
? `${item.command.slice(0, commandEnd)}...`
: item.command;
const exit =
item.exitCode === null || item.exitCode === undefined ? "" : ` (exit ${item.exitCode})`;
const output = (item.aggregatedOutput ?? "").trimEnd();
let outputStart = output.length - BACKGROUND_COMMAND_DETAIL_OUTPUT_TAIL_MAX_LENGTH;
const firstOutputUnit = output.charCodeAt(outputStart);
if (firstOutputUnit >= 0xdc00 && firstOutputUnit <= 0xdfff) outputStart += 1;
const outputTail = outputStart > 0 ? `...${output.slice(outputStart)}` : output;
const header = `Background command completed${exit}: ${command}`;
return outputTail.length === 0 ? header : `${header}\n\nOutput tail:\n${outputTail}`;
}
// Codex spawns can omit the prompt, which registers as an empty string.
function codexNativeSubagentLabel(task: OrchestrationV2Subagent): string | undefined {
return task.title?.trim() || task.prompt.trim() || undefined;
}
function codexNativeSubagentDetail(task: OrchestrationV2Subagent): string {
const header = `Subagent ${task.status}: ${codexNativeSubagentLabel(task) ?? task.id}`;
return task.result == null || task.result.length === 0
? header
: `${header}\n\nResult:\n${task.result}`;
}
export interface CodexDynamicToolProjection extends McpToolPresentation {
readonly toolName: string;
readonly title?: string;
readonly input: unknown;
readonly output?: unknown;
readonly status: OrchestrationV2TurnItem["status"];
}
function codexMcpToolOutput(
item: Extract<CodexDynamicToolItem, { readonly type: "mcpToolCall" }>,
): unknown | undefined {
const resultOutput =
item.result === null || item.result === undefined
? undefined
: mcpToolResultOutput(item.result);
if (item.error === null || item.error === undefined) {
return resultOutput;
}
return resultOutput === undefined
? { error: item.error.message }
: { error: item.error.message, result: resultOutput };
}
// A hung MCP resource read must not hold run ingestion open.
const MCP_APP_CAPTURE_TIMEOUT = "20 seconds";
function codexMcpAppResourceUri(item: CodexDynamicToolItem): string | undefined {
if (item.type !== "mcpToolCall") return undefined;
const uri = item.mcpAppUi?.resourceUri ?? item.mcpAppResourceUri ?? item.appContext?.resourceUri;
return typeof uri === "string" && uri.startsWith(MCP_APP_RESOURCE_SCHEME) ? uri : undefined;
}
const CODEX_IMAGE_DATA_URL = /^data:(image\/[a-z0-9.+-]+);base64,([A-Za-z0-9+/=]+)$/i;
export function codexDynamicToolOutput(
item: Extract<CodexDynamicToolItem, { readonly type: "dynamicToolCall" }>,
): unknown | undefined {
if (item.contentItems !== null && item.contentItems !== undefined) {
return item.contentItems.map((content) => {
if (content.type !== "inputImage") return content;
const match = CODEX_IMAGE_DATA_URL.exec(content.imageUrl);
return match?.[1] && match[2]
? { type: "image", mimeType: match[1].toLowerCase(), data: match[2] }
: content;
});
}
return item.success === false ? { success: false } : undefined;
}
const projectCodexDynamicToolItem = Effect.fn("CodexAdapterV2.projectDynamicToolItem")(function* (
item: CodexDynamicToolItem,
): Effect.fn.Return<CodexDynamicToolProjection, never, Digest.Digest> {
const output =
item.type === "mcpToolCall" ? codexMcpToolOutput(item) : codexDynamicToolOutput(item);
const toolName =
item.type === "mcpToolCall"
? `${item.server}.${item.tool}`
: [trimText(item.namespace), item.tool].filter(Boolean).join(".");
const presentation: McpToolPresentation =
item.type === "mcpToolCall" ? yield* mcpToolPresentation(item) : {};
const title =
dynamicToolTitle(toolName, item.arguments, presentation.title) ?? presentation.title;
const toolSurface = presentation.toolSurface ?? dynamicToolSurface(toolName, item.arguments);
const toolSource =
toolSurface === "computer" && presentation.toolSource?.kind !== "computer"
? COMPUTER_USE_TOOL_SOURCE
: presentation.toolSource;
const projection: CodexDynamicToolProjection = {
...presentation,
...(toolSurface ? { toolSurface } : {}),
...(toolSource ? { toolSource } : {}),
toolName,
...(title ? { title } : {}),
input: item.arguments,
status: codexItemStatus(item.status).turnItem,
};
return output === undefined ? projection : { ...projection, output };
});
function codexNativeItemRef(nativeItemId: string) {
return {
driver: CODEX_PROVIDER,
nativeId: nativeItemId,
strength: "strong" as const,
};
}
function trimText(value: string | null | undefined): string | undefined {
const trimmed = value?.trim();
return trimmed && trimmed.length > 0 ? trimmed : undefined;
}
function nonEmptyText(value: string | null | undefined, fallback: string): string {
return trimText(value) ?? fallback;
}
function codexPlanStepStatus(
status: CodexSchema.V2TurnPlanUpdatedNotification__TurnPlanStepStatus,
): OrchestrationV2PlanStep["status"] {
switch (status) {
case "completed":
return "completed";
case "inProgress":
return "running";
case "pending":
return "pending";
}
}
function approvalDecisionToLegacyReviewDecision(
decision: ProviderApprovalDecision,
): CodexSchema.ExecCommandApprovalResponse__ReviewDecision {
switch (decision) {
case "accept":
return "approved";
case "acceptForSession":
case "acceptAlways":
return "approved_for_session";
case "decline":
return { denied: { rejection: "User declined the request." } };
case "cancel":
return "abort";
}
}
function providerRequestKindFromPermissions(
permissions: CodexSchema.PermissionsRequestApprovalParams["permissions"],
): ProviderRequestKind {
// Codex leaves the legacy `read`/`write` lists out when a path is a glob or
// special path, and is replacing them with `entries`.
const requests = (access: "read" | "write") =>
(permissions.fileSystem?.[access]?.length ?? 0) > 0 ||
permissions.fileSystem?.entries?.some((entry) => entry.access === access);
if (requests("write")) {
return "file-change";
}
if (requests("read")) {
return "file-read";
}
return "command";
}
function permissionsResponseFromDecision(input: {
readonly decision: ProviderApprovalDecision;
readonly permissions: CodexSchema.PermissionsRequestApprovalParams["permissions"];
}): CodexSchema.PermissionsRequestApprovalResponse {
if (input.decision !== "accept" && input.decision !== "acceptForSession") {
return { permissions: {}, scope: "turn" };
}
return {
permissions: input.permissions,
scope: input.decision === "acceptForSession" ? "session" : "turn",
};
}
function answerValueToStrings(value: unknown): ReadonlyArray<string> {
if (Array.isArray(value)) {
return value.map((item) => String(item));
}
if (typeof value === "string") {
return [value];
}
if (value === null || value === undefined) {
return [];
}
if (typeof value === "number" || typeof value === "boolean") {
return [String(value)];
}
return [JSON.stringify(value)];
}
function toCodexUserInputAnswers(
answers: ProviderUserInputAnswers,
allowedQuestionIds: ReadonlySet<string>,
): CodexSchema.ToolRequestUserInputResponse["answers"] {
return Object.fromEntries(
Object.entries(answers).flatMap(([questionId, value]) =>
allowedQuestionIds.has(questionId)
? [[questionId, { answers: [...answerValueToStrings(value)] }]]
: [],
),
);
}
function compactStrings(values: ReadonlyArray<string | null | undefined>): ReadonlyArray<string> {
return values.flatMap((value) => {
const trimmed = trimText(value);
return trimmed === undefined ? [] : [trimmed];
});
}
function webSearchPatterns(item: CodexWebSearchItem): ReadonlyArray<string> {
if (item.action === null || item.action === undefined) {
return compactStrings([item.query]);
}
switch (item.action.type) {
case "search":
return compactStrings([...(item.action.queries ?? []), item.action.query, item.query]);
case "openPage":
return compactStrings([item.action.url, item.query]);
case "findInPage":
return compactStrings([item.action.pattern, item.action.url, item.query]);
case "other":
return compactStrings([item.query]);
}
}
const decodeTurnApprovalPolicy = Schema.decodeUnknownEffect(
Schema.Union([CodexSchema.V2TurnStartParams__AskForApproval, Schema.Null]),
);
const decodeTurnSandboxPolicy = Schema.decodeUnknownEffect(
Schema.Union([CodexSchema.V2TurnStartParams__SandboxPolicy, Schema.Null]),
);
const decodeTurnReasoningEffort = Schema.decodeUnknownEffect(
Schema.Union([CodexSchema.V2TurnStartParams__ReasoningEffort, Schema.Null]),
);
const CodexTurnStartParamsWithCollaborationMode = CodexSchema.V2TurnStartParams.pipe(
Schema.fieldsAssign({
collaborationMode: Schema.optionalKey(CodexSchema.ClientRequest__CollaborationMode),
additionalContext: Schema.optionalKey(
Schema.Record(Schema.String, CodexSchema.V2TurnStartParams__AdditionalContextEntry),
),
}),
);
type CodexTurnStartParamsWithCollaborationMode =
typeof CodexTurnStartParamsWithCollaborationMode.Type;
const decodeCodexTurnStartParamsWithCollaborationMode = Schema.decodeUnknownEffect(
CodexTurnStartParamsWithCollaborationMode,
);
const isProviderAdapterRuntimeRequestResponseError = Schema.is(
ProviderAdapter.ProviderAdapterRuntimeRequestResponseError,
);
function codexRuntimeModeTurnDefaults(runtimeMode: RuntimeMode): {
readonly approvalPolicy: CodexSchema.V2TurnStartParams__AskForApproval;
readonly approvalsReviewer: CodexSchema.V2TurnStartParams__ApprovalsReviewer;
readonly sandboxPolicy: CodexSchema.V2TurnStartParams__SandboxPolicy;
} {
switch (runtimeMode) {
case "approval-required":
return {
approvalPolicy: "untrusted",
approvalsReviewer: "user",
sandboxPolicy: {
type: "readOnly",
},
};
case "auto-accept-edits":
return {
approvalPolicy: "on-request",
approvalsReviewer: "user",
sandboxPolicy: {
type: "workspaceWrite",
},
};
case "auto":
return {
approvalPolicy: "on-request",
approvalsReviewer: "auto_review",
sandboxPolicy: {
type: "workspaceWrite",
},
};
case "full-access":
return {
approvalPolicy: "never",
approvalsReviewer: "user",
sandboxPolicy: {
type: "dangerFullAccess",
},
};
}
}
export const buildCodexTurnStartParams = Effect.fn("CodexAdapterV2.buildCodexTurnStartParams")(
function* (input: {
readonly nativeThreadId: string;
readonly codexInput: ReadonlyArray<CodexSchema.V2TurnStartParams__UserInput>;
readonly runtimePolicy: ProviderAdapter.ProviderAdapterV2RuntimePolicy;
readonly modelSelection: ModelSelection;
readonly hasT3Mcp?: boolean;
readonly browserToolsAvailable?: boolean;
readonly deviceToolsAvailable?: boolean;
/** ChatGPT token sharing does not accept service tiers. */
readonly omitServiceTier?: boolean;
readonly appContext?: ProviderAdapter.ProviderAdapterV2TurnInput["appContext"];
}) {
const runtimeModeDefaults = codexRuntimeModeTurnDefaults(input.runtimePolicy.runtimeMode);
const approvalPolicy =
input.runtimePolicy.approvalPolicy === undefined
? runtimeModeDefaults.approvalPolicy
: yield* decodeTurnApprovalPolicy(input.runtimePolicy.approvalPolicy);
const sandboxPolicy =
input.runtimePolicy.sandboxPolicy === undefined
? runtimeModeDefaults.sandboxPolicy
: yield* decodeTurnSandboxPolicy(input.runtimePolicy.sandboxPolicy);
const selectedEffort =
getModelSelectionStringOptionValue(input.modelSelection, "reasoningEffort") ??
codexDefaultReasoningEffortOverride(input.modelSelection.model);
const effort =
selectedEffort === undefined ? undefined : yield* decodeTurnReasoningEffort(selectedEffort);
const serviceTier =
input.omitServiceTier === true
? undefined
: getCodexServiceTierOptionValue(input.modelSelection);
// MCP-written app context must be quoted user input, not developer instructions.
const appContext = Object.fromEntries(
(input.appContext ?? []).map((entry) => [
entry.key,
{ kind: "untrusted" as const, value: entry.text },
]),
);
const t3Context =
input.hasT3Mcp === true
? buildCodexAdditionalContext(
{ model: input.modelSelection.model, reasoningEffort: effort ?? undefined },
{
browser: input.browserToolsAvailable ?? true,
device: input.deviceToolsAvailable ?? false,
},
)
: undefined;
const additionalContext =
t3Context === undefined && Object.keys(appContext).length === 0
? undefined
: { ...t3Context, ...appContext };
return yield* decodeCodexTurnStartParamsWithCollaborationMode({
threadId: input.nativeThreadId,
input: input.codexInput,
...(additionalContext ? { additionalContext } : {}),
cwd: input.runtimePolicy.cwd,
model: input.modelSelection.model,
// Catalogues can default summaries to "none"; request them explicitly on every turn.
summary: "detailed",
// Omitting the reviewer on resume preserves the previous Auto reviewer.
approvalsReviewer: runtimeModeDefaults.approvalsReviewer,
...(approvalPolicy === undefined ? {} : { approvalPolicy }),
...(sandboxPolicy === undefined ? {} : { sandboxPolicy }),
...(effort === undefined ? {} : { effort }),
...(serviceTier === undefined ? {} : { serviceTier }),
// Codex supplies its own mode instructions; send both modes to clear Plan on exit.
collaborationMode: {
mode: input.runtimePolicy.interactionMode,
settings: {
model: input.modelSelection.model,
...(effort === undefined ? {} : { reasoning_effort: effort }),
},
},
});
},
);
function providerSession(input: {
readonly providerSessionId: OrchestrationV2ProviderSession["id"];
readonly providerInstanceId: ProviderInstanceId;
readonly cwd: string | null;
readonly model: string;
readonly now: DateTime.Utc;
}): OrchestrationV2ProviderSession {
return {
id: input.providerSessionId,
driver: CODEX_PROVIDER,
providerInstanceId: input.providerInstanceId,
status: "ready",
cwd: input.cwd ?? process.cwd(),
model: input.model,
capabilities: CodexProviderCapabilitiesV2,
createdAt: input.now,
updatedAt: input.now,
lastError: null,
};
}
const getNativeThreadId = Effect.fn("CodexAdapterV2.getNativeThreadId")(function* (
providerThread: OrchestrationV2ProviderThread,
) {
const nativeThreadId = providerThread.nativeThreadRef?.nativeId;
if (nativeThreadId === undefined || nativeThreadId === null) {
return yield* toProtocolError(
`Provider thread ${providerThread.id} is missing a native Codex thread id.`,
);
}
return nativeThreadId;
});
function providerThreadFromCodexThread(input: {
readonly appThreadId: ThreadId | null;
readonly idAllocator: IdAllocator.IdAllocatorV2["Service"];
readonly ownerNodeId: OrchestrationV2ProviderThread["ownerNodeId"];
readonly providerSessionId: OrchestrationV2ProviderThread["providerSessionId"];
readonly providerInstanceId: ProviderInstanceId;
readonly thread: {
readonly createdAt: number;
readonly forkedFromId?: string | null;
readonly id: string;
readonly updatedAt: number;
};
readonly forkedFrom?: OrchestrationV2ProviderThread["forkedFrom"];
}): OrchestrationV2ProviderThread {
return {
id: input.idAllocator.derive.providerThread({
driver: CODEX_PROVIDER,
nativeThreadId: input.thread.id,
}),
driver: CODEX_PROVIDER,
providerInstanceId: input.providerInstanceId,
providerSessionId: input.providerSessionId,
appThreadId: input.appThreadId,
ownerNodeId: input.ownerNodeId,
nativeThreadRef: {
driver: CODEX_PROVIDER,
nativeId: input.thread.id,
strength: "strong" as const,
},
nativeConversationHeadRef: null,
status: "idle",
firstRunOrdinal: null,
lastRunOrdinal: null,
handoffIds: [],
forkedFrom: input.forkedFrom ?? null,
createdAt: codexTimestamp(input.thread.createdAt),
updatedAt: codexTimestamp(input.thread.updatedAt),
};
}
// /goal control turns never reach Codex and must not count toward native rollback.
const isTerminalProviderTurn = (turn: OrchestrationV2ProviderTurn): boolean =>
turn.nativeTurnRef !== null &&
(turn.status === "completed" ||
turn.status === "interrupted" ||
turn.status === "failed" ||
turn.status === "cancelled");
class CodexGoalObjectiveTooLongError extends Schema.TaggedError<CodexGoalObjectiveTooLongError>()(
"CodexGoalObjectiveTooLongError",
{ length: Schema.Number, limit: Schema.Number },
) {
override get message() {
return `The goal objective is ${this.length} characters; Codex supports at most ${this.limit}. Shorten it and send /goal again. The current goal was not changed.`;
}
}
function validateCodexGoalObjective(objective: string) {
let length = 0;
for (const _ of objective) length++;
return length > CodexSchema.MAX_THREAD_GOAL_OBJECTIVE_CHARS
? Effect.fail(
new CodexGoalObjectiveTooLongError({
length,
limit: CodexSchema.MAX_THREAD_GOAL_OBJECTIVE_CHARS,
}),
)
: Effect.void;
}
type CodexThreadGoal = CodexSchema.V2ThreadGoalUpdatedNotification["goal"];
const CODEX_GOAL_STATUSES = {
active: "active",
paused: "paused",
blocked: "blocked",
usageLimited: "usage_limited",
budgetLimited: "budget_limited",
complete: "complete",
} as const satisfies Record<CodexThreadGoal["status"], OrchestrationV2ProviderGoal["status"]>;
function providerGoalFromCodex(goal: CodexThreadGoal): OrchestrationV2ProviderGoal | null {
const objective = goal.objective.trim();
if (objective.length === 0) return null;
return {
objective,
status: CODEX_GOAL_STATUSES[goal.status],
tokensUsed: Math.max(0, goal.tokensUsed),
tokenBudget: goal.tokenBudget ?? null,
timeUsedSeconds: Math.max(0, goal.timeUsedSeconds),
};
}
const providerGoalsEqual = Schema.toEquivalence(Schema.NullOr(OrchestrationV2ProviderGoal));
function describeCodexGoal(goal: OrchestrationV2ProviderGoal): string {
return `Goal ${goal.status.replace("_", " ")}: ${goal.objective}`;
}
// Codex starts the next goal turn milliseconds after the last one completes.
const CODEX_GOAL_CONTINUATION_GRACE = "5 seconds";
const providerTurnsForThread = (
providerTurns: ReadonlyArray<OrchestrationV2ProviderTurn>,
providerThread: OrchestrationV2ProviderThread,
): ReadonlyArray<OrchestrationV2ProviderTurn> =>
providerTurns.filter((turn) => turn.providerThreadId === providerThread.id);
const countTerminalTurnsAfterBoundary = (
providerTurns: ReadonlyArray<OrchestrationV2ProviderTurn>,
providerTurnId: ProviderTurnId,
): number | null => {
const boundaryTurn = providerTurns.find((turn) => turn.id === providerTurnId);
if (boundaryTurn === undefined) {
return null;
}
return providerTurns.filter(
(turn) => turn.ordinal > boundaryTurn.ordinal && isTerminalProviderTurn(turn),
).length;
};
const resolveCodexForkRollbackTurnCount = Effect.fn("CodexAdapterV2.resolveForkRollbackTurnCount")(
function* (input: ProviderAdapter.ProviderAdapterV2ForkThreadInput) {
if (input.providerTurnId === undefined || input.sourceProviderTurns === undefined) {
return 0;
}
const rollbackTurnCount = countTerminalTurnsAfterBoundary(
providerTurnsForThread(input.sourceProviderTurns, input.sourceProviderThread),
input.providerTurnId,
);
if (rollbackTurnCount === null) {
return yield* new ProviderAdapter.ProviderAdapterForkThreadError({
driver: CODEX_PROVIDER,
providerThreadId: input.sourceProviderThread.id,
cause: `Cannot fork Codex thread from provider turn ${input.providerTurnId}: source turn was not found in provider thread ${input.sourceProviderThread.id}.`,
});
}
return rollbackTurnCount;
},
);
/** Codex lastTurnId is inclusive, atomically omitting later turns even in paginated threads. */
export const resolveCodexForkBoundary = Effect.fn("CodexAdapterV2.resolveForkBoundary")(function* (
input: ProviderAdapter.ProviderAdapterV2ForkThreadInput,
) {
const rollbackTurnCount = yield* resolveCodexForkRollbackTurnCount(input);
if (input.providerTurnId === undefined || input.sourceProviderTurns === undefined) {
return { lastTurnId: undefined, rollbackTurnCount };
}
const boundaryTurn = providerTurnsForThread(
input.sourceProviderTurns,
input.sourceProviderThread,
).find((turn) => turn.id === input.providerTurnId);
const nativeTurnId = boundaryTurn?.nativeTurnRef?.nativeId;
if (nativeTurnId === null || nativeTurnId === undefined) {
return { lastTurnId: undefined, rollbackTurnCount };
}
return { lastTurnId: nativeTurnId, rollbackTurnCount: 0 };
});
/** Generated thread/read schemas omit historyMode; probe through the raw request channel. */
const CodexThreadHistoryMetadata = Schema.Struct({
thread: Schema.Struct({
historyMode: Schema.optionalKey(Schema.Literals(["legacy", "paginated"])),
status: Schema.optionalKey(Schema.Struct({ type: Schema.String })),
}),
});
const decodeCodexThreadHistoryMetadata = Schema.decodeUnknownEffect(CodexThreadHistoryMetadata);
const readCodexThreadHistoryMetadata = Effect.fn("CodexAdapterV2.readThreadHistoryMetadata")(
function* (
raw: Pick<CodexClient.CodexAppServerClient["Service"]["raw"], "request">,
threadId: string,
) {
const response = yield* raw.request("thread/read", { threadId, includeTurns: false });
const metadata = yield* decodeCodexThreadHistoryMetadata(response).pipe(
Effect.mapError((error) =>
CodexErrors.CodexAppServerRequestError.invalidPayload(
"thread/read",
"decode-payload",
error,
),
),
);
return {
historyMode: metadata.thread.historyMode,
loaded: metadata.thread.status?.type !== "notLoaded",
};
},
);
export const resolveCodexRollbackTurnCount = Effect.fn("CodexAdapterV2.resolveRollbackTurnCount")(
function* (input: ProviderAdapter.ProviderAdapterV2RollbackThreadInput) {
const providerTurns = input.providerThreadTurns;
switch (input.target.type) {
case "thread_start":
return providerTurns.filter(isTerminalProviderTurn).length;
case "provider_turn": {
if (input.target.providerTurn.providerThreadId !== input.providerThread.id) {
return yield* new ProviderAdapter.ProviderAdapterRollbackThreadError({
driver: CODEX_PROVIDER,
providerThreadId: input.providerThread.id,
cause: `Cannot roll back Codex thread ${input.providerThread.id} to provider turn ${input.target.providerTurn.id}: target turn belongs to provider thread ${input.target.providerTurn.providerThreadId}.`,
});
}
const rollbackTurnCount = countTerminalTurnsAfterBoundary(
providerTurns,
input.target.providerTurn.id,
);
if (rollbackTurnCount === null) {
return yield* new ProviderAdapter.ProviderAdapterRollbackThreadError({
driver: CODEX_PROVIDER,
providerThreadId: input.providerThread.id,
cause: `Cannot roll back Codex thread ${input.providerThread.id} to provider turn ${input.target.providerTurn.id}: target turn was not found in durable provider turn history.`,
});
}
return rollbackTurnCount;
}
}
},
);
function parseCodexRetryProgress(
message: string,
): Pick<OrchestrationV2ProviderRetry, "attempt" | "maxAttempts"> | null {
const match = /\b(\d+)\s*\/\s*(\d+)\b/u.exec(message);
if (match?.[1] === undefined || match[2] === undefined) {
return null;
}
const attempt = Number.parseInt(match[1], 10);
const maxAttempts = Number.parseInt(match[2], 10);
if (attempt < 1 || maxAttempts < 1) {
return null;
}
return { attempt, maxAttempts };
}
function codexErrorInfoCode(value: unknown): string | null {
if (typeof value === "string") {
return value;
}
if (typeof value !== "object" || value === null) {
return null;
}
return Object.keys(value)[0] ?? null;
}
type CodexErrorInfo = CodexSchema.ServerNotification__CodexErrorInfo;
/**
* Retry exhaustion only says why it failed through the last attempt's HTTP
* status. Exhaustion on 429 is a usage or rate limit, so it keeps the Limited
* state and resume controls; other statuses stay provider or transport errors.
*/
function codexExhaustionHttpStatus(errorInfo: CodexErrorInfo | null | undefined): number | null {
return typeof errorInfo === "object" &&
errorInfo !== null &&
"responseTooManyFailedAttempts" in errorInfo
? (errorInfo.responseTooManyFailedAttempts.httpStatusCode ?? null)
: null;
}
function codexUsageLimitError(
code: string | null,
errorInfo: CodexErrorInfo | null | undefined,
): boolean {
return (
code === "usageLimitExceeded" ||
code === "rateLimitExceeded" ||
codexExhaustionHttpStatus(errorInfo) === 429
);
}
/**
* ChatGPT sharing reports its own reason inside Codex's generic turn error, so
* the code it names replaces Codex's, and clients pick a recovery from it. Its
* allowance limits get the usage-limit recovery; other sharing failures keep their class.
*/
function withCodexManagedFailure(
failure: OrchestrationV2ProviderFailure,
nativeError: unknown,
): OrchestrationV2ProviderFailure {
const managed = classifyCodexManagedError(nativeError);
return managed === undefined
? failure
: {
...failure,
message: managed.message,
code: managed.code,
...(managed.usageLimit ? { class: "usage_limit" } : {}),
};
}
function failureResetAt(
failure: OrchestrationV2ProviderFailure,
snapshot: CodexRateLimitSnapshot | undefined,
) {
// Sharing caps have no reset timestamp in the ordinary Codex allowance snapshot.
return classifyCodexManagedError(failure.code)?.usageLimit
? null
: codexUsageLimitResetAt(snapshot);
}
interface ActiveCodexTurnContext {
hookStopReason?: string;
capacityRetryAttempt?: number;
capacityRetryPending?: Deferred.Deferred<ActiveCodexTurnContext | undefined>;
closedCommandItemIds?: ReadonlySet<string>;
latestProviderFailure?: {
readonly nativeMessage: string;
readonly nativeCode: string | null;
readonly failure: OrchestrationV2ProviderFailure;
};
readonly nativeStartReady?: Deferred.Deferred<void>;
readonly input: ProviderAdapter.ProviderAdapterV2TurnInput;
readonly projectionAppThread: OrchestrationV2AppThread;
readonly projectionThreadId: ThreadId;
readonly projectionRunId: ProviderAdapter.ProviderAdapterV2TurnInput["runId"] | null;
readonly nativeTurnId: string;
readonly providerThread: OrchestrationV2ProviderThread;
readonly providerTurnId: ProviderTurnId;
readonly providerTurnOrdinal: number;
readonly providerNodeId: OrchestrationV2ExecutionNode["id"];
readonly providerNodeStartedAt: DateTime.Utc | null;
readonly itemParentNodeId: OrchestrationV2ExecutionNode["id"];
readonly rootNodeId: OrchestrationV2ExecutionNode["id"];
readonly subagent: CodexSubagentThreadContext | null;
readonly startedAt: DateTime.Utc;
readonly runningCompactionItemIds: Set<string>;
// Modern approval requests omit paths; keep the kinds without retaining patch bodies.
readonly fileChangeKindsByItem: Map<string, CodexFileChangeKinds>;
readonly itemPositions: Map<
string,
{ readonly ordinal: number; readonly startedAt: DateTime.Utc }
>;
}
interface ActiveCodexProviderRetry {
readonly context?: ActiveCodexTurnContext;
readonly nativeMessage: string;
readonly nativeCode: string | null;
readonly retry: OrchestrationV2ProviderRetry;
readonly failure: OrchestrationV2ProviderFailure;
readonly startedAt: DateTime.Utc;
readonly itemOrdinal: number;
}
function codexRetryTurnItem(
activeContext: ActiveCodexTurnContext,
state: ActiveCodexProviderRetry,
status: Parameters<typeof makeProviderRetryTurnItem>[0]["status"],
updatedAt: DateTime.Utc,
) {
// A continuation keeps the retry row attached to the native turn that failed.
const context = state.context ?? activeContext;
return makeProviderRetryTurnItem({
driver: CODEX_PROVIDER,
threadId: context.projectionThreadId,
runId: context.projectionRunId,
nodeId: context.providerNodeId,
providerThreadId: context.providerThread.id,
providerTurnId: context.providerTurnId,
itemOrdinal: state.itemOrdinal,
failure: state.failure,
retry: state.retry,
status,
startedAt: state.startedAt,
updatedAt,
});
}
interface TrackedRunningCommandItem {
readonly id: string;
readonly command: string;
readonly aggregatedOutput?: string;
readonly processId?: string;
}
function isPersistentCodexDynamicTool(item: CodexDynamicToolItem): boolean {
const input = item.arguments;
if (input === null || typeof input !== "object" || Array.isArray(input)) {
return false;
}
return Reflect.get(input, "persistent") === true;
}
type CodexRootTerminalEvent = Extract<
ProviderAdapter.ProviderAdapterV2Event,
{ readonly type: "turn.terminal" }
>;
interface CodexGoalHold {
readonly context: ActiveCodexTurnContext;
readonly event: Extract<CodexRootTerminalEvent, { readonly failure: null }>;
readonly completedTurn: OrchestrationV2ProviderTurn;
readonly next: Deferred.Deferred<ActiveCodexTurnContext | undefined>;
}
interface DeferredCodexRootTerminal {
readonly context: ActiveCodexTurnContext;
readonly event: CodexRootTerminalEvent;
}
interface CodexSubagentThreadContext {
parentContext: ActiveCodexTurnContext;
readonly providerThread: OrchestrationV2ProviderThread;
readonly childThread: OrchestrationV2AppThread;
readonly subagentNodeId: OrchestrationV2ExecutionNode["id"];
readonly childRootNodeId: OrchestrationV2ExecutionNode["id"];
readonly childThreadId: ThreadId;
readonly nativeTurnIds: Set<string>;
startedAt: DateTime.Utc;
readonly turnItemId: OrchestrationV2TurnItem["id"];
readonly turnItemOrdinal: number;
task: OrchestrationV2Subagent;
}
const approvalOwnerCodexTurn = (
context: ActiveCodexTurnContext,
): {
readonly owner: ActiveCodexTurnContext;
readonly subagent: CodexSubagentThreadContext | null;
} => {
let owner = context;
let subagent: CodexSubagentThreadContext | null = null;
while (owner.subagent !== null) {
subagent = owner.subagent;
owner = owner.subagent.parentContext;
}
return { owner, subagent };
};
const isDescendantCodexTurn = (
candidate: ActiveCodexTurnContext,
ancestor: ActiveCodexTurnContext,
): boolean => {
let parent = candidate.subagent?.parentContext;
while (parent !== undefined) {
if (parent === ancestor) {
return true;
}
parent = parent.subagent?.parentContext;
}
return false;
};
interface PendingCodexSubagentTurnStarted {
readonly nativeTurnId: string;
readonly startedAt: DateTime.Utc;
}
type PendingCodexRuntimeRequest =
| {
readonly type: "approval";
readonly requestKind: ProviderRequestKind;
readonly decision: Deferred.Deferred<ProviderApprovalDecision, never>;
}
| {
readonly type: "user_input";
readonly answers: Deferred.Deferred<ProviderUserInputAnswers, never>;
};
type CodexWebSearchItem = {
readonly id: string;
readonly type: "webSearch";
readonly query?: string | null;
readonly action?:
| CodexSchema.V2ItemStartedNotification__WebSearchAction
| CodexSchema.V2ItemCompletedNotification__WebSearchAction
| null;
};
export type CodexDynamicToolItem = Extract<
| CodexSchema.V2ItemStartedNotification__ThreadItem
| CodexSchema.V2ItemCompletedNotification__ThreadItem,
{ readonly type: "mcpToolCall" | "dynamicToolCall" }
>;
type CodexCollabAgentToolCallItem = Extract<
CodexSchema.V2ItemCompletedNotification__ThreadItem,
{ readonly type: "collabAgentToolCall" }
>;
type CodexSubAgentActivityItem = Extract<
| CodexSchema.V2ItemStartedNotification__ThreadItem
| CodexSchema.V2ItemCompletedNotification__ThreadItem,
{ readonly type: "subAgentActivity" }
>;
export interface CodexAppServerClientFactoryShape {
readonly open: (input: {
readonly instanceId: ProviderInstanceId;
readonly threadId: ThreadId;
readonly providerSessionId: OrchestrationV2ProviderSession["id"];
readonly runtimePolicy: ProviderAdapter.ProviderAdapterV2RuntimePolicy;
readonly settings: CodexSettings;
readonly environment: NodeJS.ProcessEnv;
}) => Effect.Effect<
CodexClient.CodexAppServerClient["Service"],
ProviderAdapter.ProviderAdapterOpenSessionError,
Scope.Scope
>;
}
export class CodexAppServerClientFactory extends Context.Service<
CodexAppServerClientFactory,
CodexAppServerClientFactoryShape
>()("t3/orchestration-v2/Adapters/CodexAdapterV2/CodexAppServerClientFactory") {}
/** MCP startup grace in milliseconds; the 1 s default excludes cold npx/uvx servers from the first model request. */
export const CODEX_THREAD_CONFIG = {
"tools.update_plan.enabled": true,
mcp_optional_startup_grace_ms: 10_000,
} as const;
// T3 waits can block for an hour; keep Codex's MCP timeout above that.
const CODEX_T3_MCP_TOOL_TIMEOUT_SEC = 65 * 60;
// Holds T3 tools Codex must call directly, never from Code Mode. Calls arrive as
// `t3-code-direct.<tool>`; t3McpToolPresentation.ts must keep resolving that form.
const CODEX_T3_DIRECT_MCP_SERVER = "t3-code-direct";
const CODEX_DIRECT_ONLY_T3_TOOL = "t3_thread_wait";
function codexThreadRuntimeParams(input: {
readonly threadId: ThreadId | null;
readonly mcpSession: McpProviderSession.McpProviderSessionConfig | undefined;
readonly modelSelection?: { readonly model: string };
readonly runtimePolicy?: ProviderAdapter.ProviderAdapterV2RuntimePolicy;
}): {
readonly cwd?: string;
readonly model?: string;
readonly config: Readonly<Record<string, Schema.Json>>;
} {
const { mcpSession } = input;
const t3Server =
mcpSession === undefined
? undefined
: {
url: mcpSession.endpoint,
tool_timeout_sec: CODEX_T3_MCP_TOOL_TIMEOUT_SEC,
http_headers: { Authorization: mcpSession.authorizationHeader },
};
return {
...(input.runtimePolicy?.cwd == null ? {} : { cwd: input.runtimePolicy.cwd }),
...(input.modelSelection === undefined ? {} : { model: input.modelSelection.model }),
config: {
...CODEX_THREAD_CONFIG,
// One app-server serves many threads, so the id goes in per-thread shell config, not its env.
...(input.threadId === null
? {}
: { [`shell_environment_policy.set.${PortScanner.AGENT_THREAD_ENV}`]: input.threadId }),
...(t3Server === undefined
? {}
: {
// Override only T3's servers so launch-argument MCP servers survive.
"mcp_servers.t3-code": { ...t3Server, disabled_tools: [CODEX_DIRECT_ONLY_T3_TOOL] },
// Code Mode runs a blocking wait as a nested call, and the model keeps working
// around it. A second, direct-only registration makes it a plain tool call.
[`mcp_servers.${CODEX_T3_DIRECT_MCP_SERVER}`]: {
...t3Server,
enabled_tools: [CODEX_DIRECT_ONLY_T3_TOOL],
omit_tools_from: ["code_mode", "deferred"],
},
}),
},
};
}
const decodeCodexResumeMetadata = Schema.decodeUnknownEffect(
Schema.Struct({ thread: Schema.Struct({ id: Schema.String, updatedAt: Schema.Number }) }),
);
const CodexChildSelection = Schema.Struct({
thread: Schema.Struct({ id: Schema.String }),
model: Schema.NullOr(Schema.String),
reasoningEffort: Schema.optional(Schema.NullOr(Schema.String)),
serviceTier: Schema.optional(Schema.NullOr(Schema.String)),
});
const decodeCodexChildModel = Schema.decodeUnknownEffect(CodexChildSelection);
const decodeCodexChildThread = Schema.decodeUnknownEffect(
Schema.Struct({
thread: Schema.Struct({
id: Schema.String,
model: Schema.optional(Schema.NullOr(Schema.String)),
reasoningEffort: Schema.optional(Schema.NullOr(Schema.String)),
}),
}),
);
export const makeCodexAppServerSpawnCommand = Effect.fn(
"CodexAdapterV2.makeCodexAppServerSpawnCommand",
)(function* (input: {
readonly command: string;
readonly args: ReadonlyArray<string>;
readonly cwd?: string | undefined;
readonly env?: NodeJS.ProcessEnv | undefined;
readonly extendEnv?: boolean | undefined;
readonly threadId?: string | undefined;
}) {
const launch = yield* (yield* AgentScope).wrap({
command: input.command,
args: input.args,
name: "codex",
threadId: input.threadId,
env: input.env,
shared: true,
});
const spawnCommand = yield* resolveSpawnCommand(launch.command, launch.args, {
...(input.env === undefined ? {} : { env: input.env }),
...(input.extendEnv === undefined ? {} : { extendEnv: input.extendEnv }),
});
return ChildProcess.make(spawnCommand.command, spawnCommand.args, {
...(input.cwd === undefined ? {} : { cwd: input.cwd }),
...(input.env === undefined ? {} : { env: input.env }),
...(input.extendEnv === undefined ? {} : { extendEnv: input.extendEnv }),
shell: spawnCommand.shell,
});
});
export function makeCodexAppServerProtocolLogger(input: {
readonly nativeEventLogger: ProviderEventLoggers.EventNdjsonLogger | undefined;
readonly threadId: ThreadId;
readonly providerSessionId: OrchestrationV2ProviderSession["id"];
}): CodexClient.CodexAppServerClientOptions["logger"] | undefined {
const { nativeEventLogger } = input;
if (nativeEventLogger === undefined) {
return undefined;
}
return (event) => {
if (!shouldPersistProviderEvent("native", event)) return Effect.void;
return nativeEventLogger
.write(
{
provider: CODEX_PROVIDER,
protocol: "codex.app-server",
kind: "protocol",
providerSessionId: input.providerSessionId,
event: redactCodexProtocolValue(boundProviderEventForLogging(event)),
},
input.threadId,
)
.pipe(Effect.ignore);
};
}
function redactCodexProtocolValue(value: unknown): unknown {
if (Array.isArray(value)) {
return value.map(redactCodexProtocolValue);
}
if (value === null || typeof value !== "object") {
if (typeof value !== "string") {
return value;
}
if (/^Bearer\s+/i.test(value)) {
return "[REDACTED]";
}
const trimmed = value.trim();
if (
!(
(trimmed.startsWith("{") && trimmed.endsWith("}")) ||
(trimmed.startsWith("[") && trimmed.endsWith("]"))
)
) {
return value;
}
try {
return pipe(
JSON.parse(trimmed) as unknown,
boundProviderEventForLogging,
redactCodexProtocolValue,
JSON.stringify,
);
} catch {
return value;
}
}
return Object.fromEntries(
Object.entries(value).map(([key, nested]) => [
key,
isSensitiveCodexProtocolKey(key) ? "[REDACTED]" : redactCodexProtocolValue(nested),
]),
);
}
function isSensitiveCodexProtocolKey(key: string): boolean {
const normalized = key.replace(/[^a-z0-9]/gi, "").toLowerCase();
return (
normalized.endsWith("authorization") ||
normalized.endsWith("apikey") ||
normalized.endsWith("token") ||
normalized.endsWith("password") ||
normalized.endsWith("secret")
);
}
export const layerAppServerClientFactory: Layer.Layer<
CodexAppServerClientFactory,
never,
| ChildProcessSpawner.ChildProcessSpawner
| PortScanner.PortDiscovery
| ProviderEventLoggers.ProviderEventLoggers
> = Layer.effect(
CodexAppServerClientFactory,
Effect.gen(function* () {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const { native: nativeEventLogger } = yield* ProviderEventLoggers.ProviderEventLoggers;
const agentScope = yield* AgentScope;
const portDiscovery = yield* PortScanner.PortDiscovery;
return CodexAppServerClientFactory.of({
open: Effect.fn("CodexAdapterV2.open")(function* (input) {
const scope = yield* Scope.Scope;
const environment = {
...codexAppServerEnvironment(input.environment),
...(input.settings.homePath ? { CODEX_HOME: input.settings.homePath } : {}),
};
const command = yield* makeCodexAppServerSpawnCommand({
command: input.settings.binaryPath || "codex",
args: codexAppServerArgs(
resolveCodexLaunchArgs(input.settings.launchArgs, input.environment),
),
env: environment,
threadId: input.threadId,
}).pipe(Effect.provideService(AgentScope, agentScope));
const handle = yield* spawner.spawn(command).pipe(
Effect.provideService(Scope.Scope, scope),
Effect.mapError(
(cause) =>
new ProviderAdapter.ProviderAdapterOpenSessionError({
driver: CODEX_PROVIDER,
providerSessionId: input.providerSessionId,
cause,
}),
),
);
// Its shells carry each thread's T3CODE_THREAD_ID, so port discovery reads listeners' threads.
yield* Effect.acquireRelease(Effect.sync(portDiscovery.trackAgent), (release) =>
Effect.sync(release),
);
const protocolLogger = makeCodexAppServerProtocolLogger({
nativeEventLogger,
threadId: input.threadId,
providerSessionId: input.providerSessionId,
});
const clientOptions: CodexClient.CodexAppServerClientOptions =
protocolLogger === undefined
? {}
: {
logIncoming: true,
logOutgoing: true,
logger: protocolLogger,
};
const context = yield* Layer.build(CodexClient.layerChildProcess(handle, clientOptions));
return yield* Effect.service(CodexClient.CodexAppServerClient).pipe(
Effect.provide(context),
);
}),
});
}),
);
export type CodexAdapterV2DriverEnv =
| CodexAppServerClientFactory
| Digest.Digest
| FileSystem.FileSystem
| IdAllocator.IdAllocatorV2
| McpProviderSessions.McpProviderSessions
| Path.Path
| ServerConfig;
export const createCodexAdapterV2 = Effect.fn("CodexAdapterV2.createCodexAdapterV2")(function* (
{ instanceId, environment, enabled, config }: ProviderAdapterDriverCreateInput<CodexSettings>,
hooks: Pick<CodexAdapterV2Options, "onUsageLimits" | "resolveRuntime" | "compatibility"> = {},
) {
const clientFactory = yield* CodexAppServerClientFactory;
const continuationRequests = yield* ProviderContinuationRequests.ProviderContinuationRequests;
const digest = yield* Digest.Digest;
const fileSystem = yield* FileSystem.FileSystem;
const hostEnvironment = yield* HostProcess.Environment;
const idAllocator = yield* IdAllocator.IdAllocatorV2;
const serverConfig = yield* ServerConfig;
const homeLayout = yield* resolveCodexHomeLayout(config);
yield* materializeCodexShadowHome(homeLayout).pipe(
Effect.mapError(
(cause) =>
new ProviderAdapterDriverCreateError({
driver: CODEX_DRIVER_KIND,
instanceId,
detail: "Failed to materialize the Codex shadow home.",
cause,
}),
),
);
const settings = {
...config,
enabled,
binaryPath: expandHomePath(config.binaryPath, yield* HostProcess.HomeDirectory),
homePath: homeLayout.effectiveHomePath ?? "",
} satisfies CodexSettings;
return yield* makeCodexAdapterV2({
instanceId,
settings,
environment: yield* mergeProviderInstanceEnvironment(environment, hostEnvironment),
clientFactory,
digest,
fileSystem,
idAllocator,
serverConfig,
continuationRequests,
...hooks,
});
});
export interface CodexAdapterV2Options {
readonly instanceId: ProviderInstanceId;
readonly settings: CodexSettings;
readonly environment: NodeJS.ProcessEnv;
readonly clientFactory: CodexAppServerClientFactoryShape;
readonly onUsageLimits?: ManagedServerProvider["applyUsageLimits"];
readonly resolveRuntime?: Effect.Effect<CodexEffectiveRuntime, ProviderSetupError, Scope.Scope>;
readonly compatibility?: (
version: string,
) => Effect.Effect<ServerProviderCompatibilityAdvisory | undefined>;
readonly digest: Digest.Digest["Service"];
readonly fileSystem: FileSystem.FileSystem;
readonly idAllocator: IdAllocator.IdAllocatorV2["Service"];
readonly serverConfig: ServerConfig["Service"];
/** Omitting this leaves late completions projection-only. */
readonly continuationRequests?: {
readonly offer: (
request: ProviderContinuationRequests.ProviderContinuationRequest,
) => Effect.Effect<void>;
};
}
export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
adapterOptions: CodexAdapterV2Options,
) {
const mcpSessions = yield* McpProviderSessions.McpProviderSessions;
const readMcpSession = (threadId: ThreadId | null) =>
threadId === null ? Effect.undefined : mcpSessions.read(threadId);
const { clientFactory, digest, fileSystem, idAllocator, serverConfig } = adapterOptions;
const continuationRequests = adapterOptions.continuationRequests;
return ProviderAdapter.ProviderAdapterV2.of({
instanceId: adapterOptions.instanceId,
driver: CODEX_PROVIDER,
getCapabilities: Effect.fn("CodexAdapterV2.getCapabilities")(function () {
return Effect.succeed(CodexProviderCapabilitiesV2);
}),
planSelectionTransition: Effect.fn("CodexAdapterV2.planSelectionTransition")(function () {
return Effect.succeed(turnScopedSelectionTransition());
}),
openSession: Effect.fn("CodexAdapterV2.openSession")(
function* (input) {
const scope = yield* Scope.Scope;
const resolvedRuntime =
adapterOptions.resolveRuntime === undefined
? undefined
: yield* adapterOptions.resolveRuntime.pipe(
Effect.mapError(
(cause) =>
new ProviderAdapter.ProviderAdapterOpenSessionError({
driver: CODEX_PROVIDER,
providerSessionId: input.providerSessionId,
cause,
}),
),
);
const client = yield* clientFactory.open({
instanceId: adapterOptions.instanceId,
threadId: input.threadId,
providerSessionId: input.providerSessionId,
runtimePolicy: input.runtimePolicy,
settings: resolvedRuntime?.config ?? adapterOptions.settings,
environment: resolvedRuntime?.environment ?? adapterOptions.environment,
});
const additionalContextByThread = yield* Ref.make(
new Map<
string,
NonNullable<CodexTurnStartParamsWithCollaborationMode["additionalContext"]>
>(),
);
// Codex drops client developer messages during compaction but only
// resends additionalContext when it changes.
const restoreAdditionalContext = Effect.fn("CodexAdapterV2.restoreAdditionalContext")(
function* (threadId: string) {
const context = (yield* Ref.get(additionalContextByThread)).get(threadId);
if (!context) return;
yield* client.request("thread/inject_items", {
threadId,
items: Object.entries(context).map(([key, entry]) =>
entry.kind === "untrusted"
? {
type: "message",
role: "user",
content: [
{
type: "input_text",
text: `<external_${key}>${entry.value}</external_${key}>`,
},
],
}
: {
type: "message",
role: "developer",
content: [{ type: "input_text", text: `<${key}>${entry.value}</${key}>` }],
},
),
});
},
Effect.timeout("10 seconds"),
Effect.catch((cause) =>
Effect.logWarning("Failed to restore Codex additional context after compaction.", {
cause,
}),
),
);
const initialized = yield* Ref.make(false);
// Codex rejects a second initialize on the shared app-server.
const initializePermit = yield* Semaphore.make(1);
const ensureInitialized = initializePermit.withPermit(
Effect.gen(function* () {
const alreadyInitialized = yield* Ref.get(initialized);
if (alreadyInitialized) {
return;
}
const userAgent = yield* client
.request("initialize", {