@devries-cameron20 / t3code Mirror · read-only / commits / 797bcb08e6
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 12:00 UTC

fix: Intel Mac installs and broken Codex versions fail with clear next steps (#27281)

maria committed Oct 30, 2026 at 20:28 UTC 797bcb08e689dba47441e10c77e4149741c8e826
7 files changed +110 -10
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts
+53
@@ -22,6 +22,7 @@ import {
22 type ProviderApprovalDecision,
23 ProviderInstanceId,
24 ProviderSessionId,
25 + ProviderSetupError,
26 ProviderThreadId,
27 ProviderTurnId,
28 RunAttemptId,
@@ -66,6 +67,8 @@ import * as Orchestrator from "../Orchestrator.ts";
67 import * as ProviderReplayHarness from "../testkit/ProviderReplayHarness.ts";
68 import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
69 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";
72 import * as CodexAdapterV2 from "./CodexAdapterV2.ts";
73 import { withCodexReplayChildMetadata } from "./CodexAdapterV2.testkit.ts";
74 import * as CodexAdapterV2Testkit from "./CodexAdapterV2.testkit.ts";
@@ -876,6 +879,7 @@ describe("CodexAdapterV2 session initialize", () => {
879 const openReplaySession = (
880 transcript: CodexReplay.CodexAppServerReplayTranscript,
881 beforeEmitInbound?: CodexReplay.CodexAppServerReplayDriver["beforeEmitInbound"],
882 + compatibility?: CodexAdapterV2.CodexAdapterV2Options["compatibility"],
883 ) =>
884 Effect.gen(function* () {
885 const driver = yield* CodexReplay.makeReplayDriver(
@@ -887,6 +891,7 @@ describe("CodexAdapterV2 session initialize", () => {
891 instanceId: CodexAdapterV2.CODEX_DEFAULT_INSTANCE_ID,
892 settings: DEFAULT_CODEX_SETTINGS,
893 environment: {},
894 + ...(compatibility === undefined ? {} : { compatibility }),
895 clientFactory: {
896 open: (openInput) =>
897 Layer.build(CodexReplay.layerReplayWithDriver(driver)).pipe(
@@ -1018,6 +1023,54 @@ describe("CodexAdapterV2 session initialize", () => {
1023 ),
1024 );
1025
1026 + it.effect("refuses to open a session on a Codex version marked broken", () =>
1027 + Effect.gen(function* () {
1028 + const [initialize] = replayPreamble("broken-version");
1029 + const failure = yield* openReplaySession(
1030 + makeCodexReplayTranscript({
1031 + scenario: "broken-version",
1032 + entries: [
1033 + initialize!,
1034 + {
1035 + type: "emit_inbound",
1036 + label: "initialize",
1037 + frame: {
1038 + id: 1,
1039 + result: {
1040 + userAgent: "T3 Code/0.144.3 (Mac OS 15.5.0; x86_64) unknown (T3 Code; 0.1.5)",
1041 + codexHome: "/tmp/codex-home",
1042 + platformFamily: "unix",
1043 + platformOs: "macos",
1044 + },
1045 + },
1046 + },
1047 + ],
1048 + }),
1049 + undefined,
1050 + (version) =>
1051 + Effect.succeed(
1052 + resolveProviderCompatibility(
1053 + ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility,
1054 + CodexAdapterV2.CODEX_DRIVER_KIND,
1055 + version,
1056 + ),
1057 + ),
1058 + ).pipe(Effect.flip);
1059 +
1060 + assert.instanceOf(failure, ProviderAdapter.ProviderAdapterOpenSessionError);
1061 + assert.instanceOf(failure.cause, ProviderSetupError);
1062 + assert.equal(
1063 + failure.cause.message,
1064 + "Codex 0.144.3 does not work with this T3 Code release. Update Codex to >=0.159.0, then retry.",
1065 + );
1066 + }).pipe(
1067 + Effect.scoped,
1068 + Effect.provide(
1069 + Layer.mergeAll(IdAllocator.layer, McpProviderSessions.layer, NodeServices.layer),
1070 + ),
1071 + ),
1072 + );
1073 +
1074 it.effect("completes the handshake after a caller is interrupted mid-initialize", () =>
1075 Effect.gen(function* () {
1076 const initializeAwaitingResponse = yield* Deferred.make<void>();
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
+25 -4
@@ -36,7 +36,8 @@ import {
36 OrchestrationV2ProviderGoal,
37 parseGoalCommand,
38 ProviderDriverKind,
39 - type ProviderSetupError,
39 + ProviderSetupError,
40 + type ServerProviderCompatibilityAdvisory,
41 } from "@t3tools/contracts";
42 import { SKILL_MENTION_PATTERN } from "@t3tools/shared/composerInlineTokens";
43 import { AgentScope } from "@t3tools/shared/AgentScope";
@@ -1549,7 +1550,7 @@ export type CodexAdapterV2DriverEnv =
1550
1551 export const createCodexAdapterV2 = Effect.fn("CodexAdapterV2.createCodexAdapterV2")(function* (
1552 { instanceId, environment, enabled, config }: ProviderAdapterDriverCreateInput<CodexSettings>,
1552 - hooks: Pick<CodexAdapterV2Options, "onUsageLimits" | "resolveRuntime"> = {},
1553 + hooks: Pick<CodexAdapterV2Options, "onUsageLimits" | "resolveRuntime" | "compatibility"> = {},
1554 ) {
1555 const clientFactory = yield* CodexAppServerClientFactory;
1556 const continuationRequests = yield* ProviderContinuationRequests.ProviderContinuationRequests;
@@ -1600,6 +1601,9 @@ export interface CodexAdapterV2Options {
1601 readonly clientFactory: CodexAppServerClientFactoryShape;
1602 readonly onUsageLimits?: ManagedServerProvider["applyUsageLimits"];
1603 readonly resolveRuntime?: Effect.Effect<CodexEffectiveRuntime, ProviderSetupError, Scope.Scope>;
1604 + readonly compatibility?: (
1605 + version: string,
1606 + ) => Effect.Effect<ServerProviderCompatibilityAdvisory | undefined>;
1607 readonly crypto: Crypto.Crypto;
1608 readonly fileSystem: FileSystem.FileSystem;
1609 readonly idAllocator: IdAllocator.IdAllocatorV2["Service"];
@@ -1706,24 +1710,41 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
1710 return;
1711 }
1712
1709 - yield* client
1713 + const userAgent = yield* client
1714 .request("initialize", {
1715 clientInfo: buildCodexInitializeParams().clientInfo,
1716 capabilities: CODEX_CLIENT_CAPABILITIES,
1717 })
1718 .pipe(
1719 + Effect.map((response) => response.userAgent),
1720 Effect.catchTags({
1721 // Interruption can leave Codex initialized before the local flag is set.
1722 CodexAppServerRequestError: (error) =>
1723 error.code === -32600 && error.errorMessage === "Already initialized"
1719 - ? Effect.void
1724 + ? Effect.succeed(null)
1725 : Effect.fail(error),
1726 }),
1727 );
1728 + const version = userAgent && /\/(\S+)/u.exec(userAgent)?.[1];
1729 + const advisory =
1730 + version && adapterOptions.compatibility
1731 + ? yield* adapterOptions.compatibility(version)
1732 + : undefined;
1733 + if (advisory?.status === "broken") {
1734 + const target =
1735 + advisory.recommendedVersion ?? advisory.recommendedRange ?? "a newer version";
1736 + return yield* new ProviderSetupError({
1737 + instanceId: adapterOptions.instanceId,
1738 + operation: "runtime",
1739 + detail: `Codex ${version} does not work with this T3 Code release. Update Codex to ${target}, then retry.`,
1740 + });
1741 + }
1742 yield* client.notify("initialized", undefined);
1743 yield* Ref.set(initialized, true);
1744 }),
1745 );
1746 + // A failed open is discarded, so the next turn spawns the updated binary.
1747 + if (adapterOptions.compatibility !== undefined) yield* ensureInitialized;
1748 const now = yield* DateTime.now;
1749 const session = providerSession({
1750 providerSessionId: input.providerSessionId,
apps/server/src/provider/CodexInstallation.ts
+9 -1
@@ -1,5 +1,9 @@
1 // @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";
7 import { cliArchiveTarCommand } from "@t3tools/shared/cliRelease";
8 import * as HostProcess from "@t3tools/shared/HostProcess";
9 import { resolveCommandPath, resolveSpawnCommand } from "@t3tools/shared/shell";
@@ -125,6 +129,9 @@ interface CodexInstallationService {
129 readonly managedDirectory: string;
130 readonly resolve: () => Effect.Effect<CodexExecutable, CodexInstallationError>;
131 readonly acquire: () => Effect.Effect<CodexExecutable, CodexInstallationError, Scope.Scope>;
132 + readonly compatibility: (
133 + version: string,
134 + ) => Effect.Effect<ServerProviderCompatibilityAdvisory | undefined>;
135 readonly start: Effect.Effect<ProviderInstallState, CodexInstallationError>;
136 readonly cancel: (
137 operationId: string,
@@ -796,6 +803,7 @@ export const makeCodexInstallation = Effect.fn("makeCodexInstallation")(function
803 managedDirectory,
804 resolve,
805 acquire,
806 + compatibility,
807 start,
808 cancel,
809 state: SubscriptionRef.get(state),
apps/server/src/provider/Drivers/CodexDriver.ts
+5 -1
@@ -147,6 +147,7 @@ export const CodexDriver: ProviderDriver<
147 const pathService = yield* Path.Path;
148 const httpClient = yield* HttpClient.HttpClient;
149 const latestVersions = yield* ProviderLatestVersions.ProviderLatestVersions;
150 + const installation = yield* CodexInstallation.CodexInstallation;
151 const modelCatalog = yield* ModelCatalog.ModelCatalog;
152 const currentCatalog = modelCatalog.current(DRIVER_KIND);
153 const processEnv = yield* mergeProviderInstanceEnvironment(environment);
@@ -199,7 +200,10 @@ export const CodexDriver: ProviderDriver<
200 enabled,
201 config,
202 },
202 - { onUsageLimits: (update) => snapshot.applyUsageLimits(update) },
203 + {
204 + onUsageLimits: (update) => snapshot.applyUsageLimits(update),
205 + compatibility: installation.compatibility,
206 + },
207 ).pipe(
208 Effect.mapError(
209 (cause) =>
packages/provider-core/src/server/failure.test.ts
+12 -2
@@ -2,6 +2,8 @@ import { assert, it } from "@effect/vitest";
2 import {
3 NodeId,
4 ProviderDriverKind,
5 + ProviderInstanceId,
6 + ProviderSetupError,
7 ProviderThreadId,
8 ProviderTurnId,
9 RunId,
@@ -83,8 +85,16 @@ it("does not expose arbitrary cause messages and preserves explicit messages", (
85 }
86 });
87
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 + ]) {
98 const cause = new ProviderAdapter.ProviderAdapterTurnStartError({
99 driver: ProviderDriverKind.make("codex"),
100 threadId: ThreadId.make("thread:handoff-error"),
packages/provider-core/src/server/failure.ts
+1
@@ -108,6 +108,7 @@ function curatedCauseMessages(cause: unknown): {
108 case "ClaudeSettingsLaunchArgError":
109 case "ClaudeMcpRegistrationTimeoutError":
110 case "CursorModelUnavailableError":
111 + case "ProviderSetupError":
112 return { known: stringField(cause, "message"), category: categoryMessage() };
113 case "ContextHandoffDeliveryUncertainError":
114 return {
scripts/install.sh
+5 -2
@@ -133,6 +133,9 @@ case "$(uname -m)" in
133 x86_64 | amd64) arch="x64" ;;
134 *) fail "unsupported architecture $(uname -m)" ;;
135 esac
136 +if [ "${platform}-${arch}" = darwin-x64 ]; then
137 + fail "there is no t3 CLI for Intel Macs. Install the desktop app from https://t3.codes/download, or run a server from source: https://github.com/${repo}/blob/main/docs/user/install.md#intel-macs"
138 +fi
139 command -v tar >/dev/null 2>&1 || fail "tar is required"
140 if command -v sha256sum >/dev/null 2>&1; then
141 checksum() { sha256sum "$1" | cut -d' ' -f1; }
@@ -206,11 +209,11 @@ else
209 elif [ "$fetch_status" -ne 0 ]; then
210 fail "could not download the release checksums"
211 fi
212 + expected="$(grep " \*\{0,1\}${archive}\$" "${staging}/SHA256SUMS" | cut -d' ' -f1)"
213 + [ -n "$expected" ] || fail "t3 ${version} has no release archive for ${platform}-${arch}"
214 download "${base_url}/v${version}/${archive}" "${staging}/${archive}"
215
216 step "Verifying the download..."
212 - expected="$(grep " \*\{0,1\}${archive}\$" "${staging}/SHA256SUMS" | cut -d' ' -f1)"
213 - [ -n "$expected" ] || fail "${archive} is not listed in SHA256SUMS"
217 actual="$(checksum "${staging}/${archive}")"
218 [ "$actual" = "$expected" ] || fail "checksum mismatch for ${archive}"
219