Skip to content

Commit df00648

Browse files
committed
fix(codex): broken Codex versions fail with an update hint instead of a decode error
1 parent 6185b08 commit df00648

6 files changed

Lines changed: 105 additions & 8 deletions

File tree

‎apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import {
2222
type ProviderApprovalDecision,
2323
ProviderInstanceId,
2424
ProviderSessionId,
25+
ProviderSetupError,
2526
ProviderThreadId,
2627
ProviderTurnId,
2728
RunAttemptId,
@@ -66,6 +67,8 @@ import * as Orchestrator from "../Orchestrator.ts";
6667
import * as ProviderReplayHarness from "../testkit/ProviderReplayHarness.ts";
6768
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
6869
import type * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
70+
import * as ModelManifest from "../../provider/ModelManifest.ts";
71+
import { resolveProviderCompatibility } from "../../provider/providerCompatibility.ts";
6972
import * as CodexAdapterV2 from "./CodexAdapterV2.ts";
7073
import { withCodexReplayChildMetadata } from "./CodexAdapterV2.testkit.ts";
7174
import * as CodexAdapterV2Testkit from "./CodexAdapterV2.testkit.ts";
@@ -875,6 +878,7 @@ describe("CodexAdapterV2 session initialize", () => {
875878
const openReplaySession = (
876879
transcript: CodexReplay.CodexAppServerReplayTranscript,
877880
beforeEmitInbound?: CodexReplay.CodexAppServerReplayDriver["beforeEmitInbound"],
881+
compatibility?: CodexAdapterV2.CodexAdapterV2Options["compatibility"],
878882
) =>
879883
Effect.gen(function* () {
880884
const driver = yield* CodexReplay.makeReplayDriver(
@@ -886,6 +890,7 @@ describe("CodexAdapterV2 session initialize", () => {
886890
instanceId: CodexAdapterV2.CODEX_DEFAULT_INSTANCE_ID,
887891
settings: DEFAULT_CODEX_SETTINGS,
888892
environment: {},
893+
...(compatibility === undefined ? {} : { compatibility }),
889894
clientFactory: {
890895
open: (openInput) =>
891896
Layer.build(CodexReplay.layerReplayWithDriver(driver)).pipe(
@@ -1017,6 +1022,54 @@ describe("CodexAdapterV2 session initialize", () => {
10171022
),
10181023
);
10191024

1025+
it.effect("refuses to open a session on a Codex version marked broken", () =>
1026+
Effect.gen(function* () {
1027+
const [initialize] = replayPreamble("broken-version");
1028+
const failure = yield* openReplaySession(
1029+
makeCodexReplayTranscript({
1030+
scenario: "broken-version",
1031+
entries: [
1032+
initialize!,
1033+
{
1034+
type: "emit_inbound",
1035+
label: "initialize",
1036+
frame: {
1037+
id: 1,
1038+
result: {
1039+
userAgent: "T3 Code/0.144.3 (Mac OS 15.5.0; x86_64) unknown (T3 Code; 0.1.5)",
1040+
codexHome: "/tmp/codex-home",
1041+
platformFamily: "unix",
1042+
platformOs: "macos",
1043+
},
1044+
},
1045+
},
1046+
],
1047+
}),
1048+
undefined,
1049+
(version) =>
1050+
Effect.succeed(
1051+
resolveProviderCompatibility(
1052+
ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility,
1053+
CodexAdapterV2.CODEX_DRIVER_KIND,
1054+
version,
1055+
),
1056+
),
1057+
).pipe(Effect.flip);
1058+
1059+
assert.instanceOf(failure, ProviderAdapter.ProviderAdapterOpenSessionError);
1060+
assert.instanceOf(failure.cause, ProviderSetupError);
1061+
assert.equal(
1062+
failure.cause.message,
1063+
"Codex 0.144.3 does not work with this T3 Code release. Update Codex to >=0.159.0, then retry.",
1064+
);
1065+
}).pipe(
1066+
Effect.scoped,
1067+
Effect.provide(
1068+
Layer.mergeAll(IdAllocator.layer, McpProviderSessions.layer, NodeServices.layer),
1069+
),
1070+
),
1071+
);
1072+
10201073
it.effect("completes the handshake after a caller is interrupted mid-initialize", () =>
10211074
Effect.gen(function* () {
10221075
const initializeAwaitingResponse = yield* Deferred.make<void>();

‎apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,8 @@ import {
3636
OrchestrationV2ProviderGoal,
3737
parseGoalCommand,
3838
ProviderDriverKind,
39-
type ProviderSetupError,
39+
ProviderSetupError,
40+
type ServerProviderCompatibilityAdvisory,
4041
} from "@t3tools/contracts";
4142
import { SKILL_MENTION_PATTERN } from "@t3tools/shared/composerInlineTokens";
4243
import { AgentScope } from "@t3tools/shared/AgentScope";
@@ -1548,7 +1549,7 @@ export type CodexAdapterV2DriverEnv =
15481549

15491550
export const createCodexAdapterV2 = Effect.fn("CodexAdapterV2.createCodexAdapterV2")(function* (
15501551
{ instanceId, environment, enabled, config }: ProviderAdapterDriverCreateInput<CodexSettings>,
1551-
hooks: Pick<CodexAdapterV2Options, "onUsageLimits" | "resolveRuntime"> = {},
1552+
hooks: Pick<CodexAdapterV2Options, "onUsageLimits" | "resolveRuntime" | "compatibility"> = {},
15521553
) {
15531554
const clientFactory = yield* CodexAppServerClientFactory;
15541555
const continuationRequests = yield* ProviderContinuationRequests.ProviderContinuationRequests;
@@ -1599,6 +1600,9 @@ export interface CodexAdapterV2Options {
15991600
readonly clientFactory: CodexAppServerClientFactoryShape;
16001601
readonly onUsageLimits?: ManagedServerProvider["applyUsageLimits"];
16011602
readonly resolveRuntime?: Effect.Effect<CodexEffectiveRuntime, ProviderSetupError, Scope.Scope>;
1603+
readonly compatibility?: (
1604+
version: string,
1605+
) => Effect.Effect<ServerProviderCompatibilityAdvisory | undefined>;
16021606
readonly crypto: Crypto.Crypto;
16031607
readonly fileSystem: FileSystem.FileSystem;
16041608
readonly idAllocator: IdAllocator.IdAllocatorV2["Service"];
@@ -1705,24 +1709,41 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
17051709
return;
17061710
}
17071711

1708-
yield* client
1712+
const userAgent = yield* client
17091713
.request("initialize", {
17101714
clientInfo: buildCodexInitializeParams().clientInfo,
17111715
capabilities: CODEX_CLIENT_CAPABILITIES,
17121716
})
17131717
.pipe(
1718+
Effect.map((response) => response.userAgent),
17141719
Effect.catchTags({
17151720
// Interruption can leave Codex initialized before the local flag is set.
17161721
CodexAppServerRequestError: (error) =>
17171722
error.code === -32600 && error.errorMessage === "Already initialized"
1718-
? Effect.void
1723+
? Effect.succeed(null)
17191724
: Effect.fail(error),
17201725
}),
17211726
);
1727+
const version = userAgent && /\/(\d+\.\d+\.\d+)/u.exec(userAgent)?.[1];
1728+
const advisory =
1729+
version && adapterOptions.compatibility
1730+
? yield* adapterOptions.compatibility(version)
1731+
: undefined;
1732+
if (advisory?.status === "broken") {
1733+
const target =
1734+
advisory.recommendedVersion ?? advisory.recommendedRange ?? "a newer version";
1735+
return yield* new ProviderSetupError({
1736+
instanceId: adapterOptions.instanceId,
1737+
operation: "runtime",
1738+
detail: `Codex ${version} does not work with this T3 Code release. Update Codex to ${target}, then retry.`,
1739+
});
1740+
}
17221741
yield* client.notify("initialized", undefined);
17231742
yield* Ref.set(initialized, true);
17241743
}),
17251744
);
1745+
// A failed open is discarded, so the next turn spawns the updated binary.
1746+
if (adapterOptions.compatibility !== undefined) yield* ensureInitialized;
17261747
const now = yield* DateTime.now;
17271748
const session = providerSession({
17281749
providerSessionId: input.providerSessionId,

‎apps/server/src/provider/CodexInstallation.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
// @effect-diagnostics nodeBuiltinImport:off - Effect has no incremental digest.
2-
import { ProviderDriverKind, type ProviderInstallState } from "@t3tools/contracts";
2+
import {
3+
ProviderDriverKind,
4+
type ProviderInstallState,
5+
type ServerProviderCompatibilityAdvisory,
6+
} from "@t3tools/contracts";
37
import { cliArchiveTarCommand } from "@t3tools/shared/cliRelease";
48
import * as HostProcess from "@t3tools/shared/HostProcess";
59
import { resolveCommandPath, resolveSpawnCommand } from "@t3tools/shared/shell";
@@ -125,6 +129,9 @@ interface CodexInstallationService {
125129
readonly managedDirectory: string;
126130
readonly resolve: () => Effect.Effect<CodexExecutable, CodexInstallationError>;
127131
readonly acquire: () => Effect.Effect<CodexExecutable, CodexInstallationError, Scope.Scope>;
132+
readonly compatibility: (
133+
version: string,
134+
) => Effect.Effect<ServerProviderCompatibilityAdvisory | undefined>;
128135
readonly start: Effect.Effect<ProviderInstallState, CodexInstallationError>;
129136
readonly cancel: (
130137
operationId: string,
@@ -796,6 +803,7 @@ export const makeCodexInstallation = Effect.fn("makeCodexInstallation")(function
796803
managedDirectory,
797804
resolve,
798805
acquire,
806+
compatibility,
799807
start,
800808
cancel,
801809
state: SubscriptionRef.get(state),

‎apps/server/src/provider/Drivers/CodexDriver.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@ export const CodexDriver: ProviderDriver<
147147
const pathService = yield* Path.Path;
148148
const httpClient = yield* HttpClient.HttpClient;
149149
const latestVersions = yield* ProviderLatestVersions.ProviderLatestVersions;
150+
const installation = yield* CodexInstallation.CodexInstallation;
150151
const modelCatalog = yield* ModelCatalog.ModelCatalog;
151152
const currentCatalog = modelCatalog.current(DRIVER_KIND);
152153
const processEnv = yield* mergeProviderInstanceEnvironment(environment);
@@ -199,7 +200,10 @@ export const CodexDriver: ProviderDriver<
199200
enabled,
200201
config,
201202
},
202-
{ onUsageLimits: (update) => snapshot.applyUsageLimits(update) },
203+
{
204+
onUsageLimits: (update) => snapshot.applyUsageLimits(update),
205+
compatibility: installation.compatibility,
206+
},
203207
).pipe(
204208
Effect.mapError(
205209
(cause) =>

‎packages/provider-core/src/server/failure.test.ts‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ import { assert, it } from "@effect/vitest";
22
import {
33
NodeId,
44
ProviderDriverKind,
5+
ProviderInstanceId,
6+
ProviderSetupError,
57
ProviderThreadId,
68
ProviderTurnId,
79
RunId,
@@ -83,8 +85,16 @@ it("does not expose arbitrary cause messages and preserves explicit messages", (
8385
}
8486
});
8587

86-
it("preserves actionable handoff errors wrapped by turn startup", () => {
87-
for (const error of [new ContextHandoffBudgetError(), new ContextHandoffBackgroundWorkError()]) {
88+
it("preserves actionable T3 errors wrapped by turn startup", () => {
89+
for (const error of [
90+
new ContextHandoffBudgetError(),
91+
new ContextHandoffBackgroundWorkError(),
92+
new ProviderSetupError({
93+
instanceId: ProviderInstanceId.make("codex"),
94+
operation: "runtime",
95+
detail: "Codex 0.144.3 does not work with this T3 Code release.",
96+
}),
97+
]) {
8898
const cause = new ProviderAdapter.ProviderAdapterTurnStartError({
8999
driver: ProviderDriverKind.make("codex"),
90100
threadId: ThreadId.make("thread:handoff-error"),

‎packages/provider-core/src/server/failure.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ function curatedCauseMessages(cause: unknown): {
108108
case "ClaudeSettingsLaunchArgError":
109109
case "ClaudeMcpRegistrationTimeoutError":
110110
case "CursorModelUnavailableError":
111+
case "ProviderSetupError":
111112
return { known: stringField(cause, "message"), category: categoryMessage() };
112113
case "ContextHandoffDeliveryUncertainError":
113114
return {

0 commit comments

Comments
 (0)