Skip to content

Commit 72fb98c

Browse files
fix(providers): allow a separate CLI path for updates
Codex and Claude launchers can configure routing or accounts without owning the underlying CLI installation. Resolving maintenance from the launcher can disable updates or invoke the wrong executable. Add an optional maintenance binary path and resolve installation ownership and update advisories from that CLI. Keep session launch paths, snapshot versions and post-update verification tied to the session executable. Clearing the override restores the existing behavior. Bind Bun global updates to the proven package and binary directories, with an installation-specific lock. Leave unproven installations manual-only.
1 parent 7da0ef0 commit 72fb98c

9 files changed

Lines changed: 274 additions & 35 deletions

File tree

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,9 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
123123
} satisfies ClaudeSettings;
124124
const resolveMaintenance = yield* makeClaudeMaintenanceResolution({
125125
binaryPath: effectiveConfig.binaryPath,
126+
maintenanceBinaryPath: config.maintenanceBinaryPath
127+
? expandHomePath(config.maintenanceBinaryPath, yield* HostProcess.HomeDirectory)
128+
: null,
126129
env: processEnv,
127130
}).pipe(
128131
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
@@ -285,6 +288,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
285288
Effect.flatMap((maintenanceCapabilities) =>
286289
enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities, {
287290
enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
291+
useMaintenanceVersion: true,
288292
}),
289293
),
290294
Effect.provideService(HttpClient.HttpClient, httpClient),

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,9 @@ export const CodexDriver: ProviderDriver<
195195
makeCodexMaintenanceResolver(homeLayout.sharedHomePath),
196196
{
197197
binaryPath: effectiveConfig.binaryPath,
198+
maintenanceBinaryPath: config.maintenanceBinaryPath
199+
? expandHomePath(config.maintenanceBinaryPath, yield* HostProcess.HomeDirectory)
200+
: null,
198201
env: processEnv,
199202
},
200203
).pipe(
@@ -262,6 +265,7 @@ export const CodexDriver: ProviderDriver<
262265
Effect.flatMap((maintenanceCapabilities) =>
263266
enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities, {
264267
enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
268+
useMaintenanceVersion: true,
265269
}),
266270
),
267271
Effect.provideService(HttpClient.HttpClient, httpClient),

‎apps/server/src/provider/providerMaintenanceRunner.test.ts‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -324,7 +324,22 @@ describe("providerMaintenanceRunner", () => {
324324
},
325325
{ name: "installed behind", probe: { installedVersion: "2.1.309" }, skip: false },
326326
{ name: "installed unknown", probe: { installedVersion: null }, skip: false },
327-
] as const)("only skips a successful fresh current probe: $name", ({ probe, skip }) => {
327+
{ name: "maintenance behind", probe: {}, maintenanceVersion: "2.1.309", skip: false },
328+
{
329+
name: "maintenance current",
330+
probe: { version: "2.1.309" },
331+
maintenanceVersion: "2.1.310",
332+
skip: true,
333+
},
334+
{
335+
name: "maintenance updated but session behind",
336+
probe: { version: "2.1.309" },
337+
maintenanceVersion: "2.1.309",
338+
skip: false,
339+
},
340+
] as const)("only skips a successful fresh current probe: $name", (fixture) => {
341+
const { probe, skip } = fixture;
342+
let maintenanceVersion = "maintenanceVersion" in fixture ? fixture.maintenanceVersion : null;
328343
const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
329344
const refreshedInstanceIds: Array<ProviderInstanceId> = [];
330345
return Effect.gen(function* () {
@@ -359,20 +374,29 @@ describe("providerMaintenanceRunner", () => {
359374
);
360375
},
361376
getProviderMaintenanceCapabilitiesForInstance: () =>
362-
Effect.succeed(
363-
makeProviderMaintenanceCapabilities({
377+
Effect.succeed({
378+
...makeProviderMaintenanceCapabilities({
364379
provider: CODEX_DRIVER,
365380
packageName: "@anthropic-ai/claude-code",
366381
updateExecutable: "claude",
367382
updateArgs: ["update"],
368383
updateLockKey: "claudeAgent-native",
369384
}),
370-
),
385+
...("maintenanceVersion" in fixture
386+
? { lookupMaintenanceVersion: Effect.sync(() => maintenanceVersion) }
387+
: {}),
388+
}),
371389
});
372390

373391
const result = yield* updater.updateProvider(CODEX_DRIVER);
374392
assert.deepStrictEqual(refreshedInstanceIds, [CODEX_INSTANCE_ID]);
375393
assert.deepStrictEqual(calls, skip ? [] : [{ command: "claude", args: ["update"] }]);
394+
if ("maintenanceVersion" in fixture && !skip) {
395+
assert.strictEqual(
396+
result.providers[0]?.updateState?.status,
397+
fixture.name === "maintenance updated but session behind" ? "unchanged" : "succeeded",
398+
);
399+
}
376400
if (!skip) return;
377401
assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
378402
assert.strictEqual(result.providers[0]?.updateState?.message, "Already up to date.");
@@ -391,6 +415,7 @@ describe("providerMaintenanceRunner", () => {
391415
layerLatestVersionHttpClient("2.1.310"),
392416
layerMockSpawner((command, args) => {
393417
calls.push({ command, args });
418+
maintenanceVersion = "2.1.310";
394419
return { stdout: "updated" };
395420
}),
396421
),

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,9 @@ export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () {
351351
enrichProviderSnapshotWithVersionAdvisory(
352352
refreshedProvider,
353353
maintenanceCapabilities,
354+
phase === "pre-update"
355+
? { enableProviderUpdateChecks: undefined, useMaintenanceVersion: true }
356+
: undefined,
354357
).pipe(
355358
Effect.provideService(HttpClient.HttpClient, httpClient),
356359
Effect.provideService(ProviderLatestVersions.ProviderLatestVersions, latestVersions),

‎docs/user/install.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,11 @@ Cursor and Antigravity update with T3 Code. Homebrew and Chocolatey installs
213213
compare against the version their package manager offers, which can trail the
214214
npm release; update Claude installed with Chocolatey through Chocolatey.
215215

216+
If Codex or Claude uses a launcher as its **Binary path**, set **Maintenance binary path**
217+
to the underlying CLI installation in web or desktop Settings. Sessions keep using the
218+
launcher; Update now uses the maintenance installation and still verifies the session
219+
binary's version afterward. Clear the maintenance path to update the session binary again.
220+
216221
Add another provider instance for a separate account or configuration. Each
217222
instance can have its own environment variables, such as API keys or a custom
218223
base URL. Mark secret values as sensitive; after saving, T3 Code does not display

‎packages/contracts/src/settings.ts‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -676,6 +676,15 @@ export function makeProviderSettingsSchema<const Fields extends Schema.Struct.Fi
676676
);
677677
}
678678

679+
const MaintenanceBinaryPath = Schema.optionalKey(TrimmedString).pipe(
680+
Schema.annotateKey({
681+
title: "Maintenance binary path",
682+
description:
683+
"Underlying CLI to update when Binary path is a launcher. Leave empty to update the session binary.",
684+
providerSettingsForm: { clearWhenEmpty: "omit" },
685+
}),
686+
);
687+
679688
export const CodexSettings = makeProviderSettingsSchema(
680689
{
681690
setupMode: Schema.optionalKey(Schema.Literals(["managed", "existing"])).pipe(
@@ -692,6 +701,7 @@ export const CodexSettings = makeProviderSettingsSchema(
692701
providerSettingsForm: { placeholder: "codex", clearWhenEmpty: "omit" },
693702
}),
694703
),
704+
maintenanceBinaryPath: MaintenanceBinaryPath,
695705
homePath: TrimmedString.pipe(
696706
Schema.withDecodingDefault(Effect.succeed("")),
697707
Schema.annotateKey({
@@ -728,7 +738,7 @@ export const CodexSettings = makeProviderSettingsSchema(
728738
),
729739
},
730740
{
731-
order: ["binaryPath", "homePath", "shadowHomePath", "launchArgs"],
741+
order: ["binaryPath", "maintenanceBinaryPath", "homePath", "shadowHomePath", "launchArgs"],
732742
},
733743
);
734744
export type CodexSettings = typeof CodexSettings.Type;
@@ -768,6 +778,7 @@ export const ClaudeSettings = makeProviderSettingsSchema(
768778
providerSettingsForm: { placeholder: "claude", clearWhenEmpty: "omit" },
769779
}),
770780
),
781+
maintenanceBinaryPath: MaintenanceBinaryPath,
771782
homePath: TrimmedString.pipe(
772783
Schema.withDecodingDefault(Effect.succeed("")),
773784
Schema.annotateKey({
@@ -821,7 +832,14 @@ export const ClaudeSettings = makeProviderSettingsSchema(
821832
),
822833
},
823834
{
824-
order: ["binaryPath", "homePath", "autoCompactWindow", "idleCompaction", "launchArgs"],
835+
order: [
836+
"binaryPath",
837+
"maintenanceBinaryPath",
838+
"homePath",
839+
"autoCompactWindow",
840+
"idleCompaction",
841+
"launchArgs",
842+
],
825843
},
826844
);
827845
export type ClaudeSettings = typeof ClaudeSettings.Type;

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ export interface ProviderMaintenanceCapabilities {
55
readonly provider: ProviderDriverKind;
66
readonly packageName: string | null;
77
readonly update: ProviderMaintenanceCommandAction | null;
8+
/** Selected maintenance CLI version; never replaces the session snapshot version. */
9+
readonly lookupMaintenanceVersion?: Effect.Effect<string | null>;
810
/** undefined defers to npm; null means the installer could not determine the latest version. */
911
readonly latestVersion?: string | null;
1012
/**

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

Lines changed: 154 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -307,6 +307,74 @@ it.layer(
307307
}),
308308
);
309309

310+
it.effect.each([
311+
{ output: "codex-cli 2.0.0", exitCode: 0, expected: "2.0.0" },
312+
{ output: "2.0.0 (Claude Code)", exitCode: 0, expected: "2.0.0" },
313+
{ output: "unavailable", exitCode: 0, expected: null },
314+
{ output: "codex-cli 2.0.0", exitCode: 1, expected: null },
315+
{ output: "missing executable", exitCode: 0, expected: null, missing: true },
316+
])(
317+
"uses the selected CLI version only for advisories ($output, exit $exitCode)",
318+
(fixture) =>
319+
Effect.gen(function* () {
320+
const tempDir = yield* makeTempDir("t3-maintenance-advisory");
321+
const maintenancePath = NodePath.join(tempDir, ".local", "bin", "native-package-tool");
322+
if (!fixture.missing) writeExecutable(maintenancePath);
323+
let probes = 0;
324+
const capabilities = {
325+
...(yield* resolveProviderMaintenanceCapabilitiesEffect(nativePackageToolUpdate, {
326+
binaryPath: NodePath.join(tempDir, "runtime-launcher"),
327+
maintenanceBinaryPath: maintenancePath,
328+
env: { PATH: "", SELECTED_INSTALL: "fixture" },
329+
}).pipe(
330+
Effect.provideService(
331+
ChildProcessSpawner.ChildProcessSpawner,
332+
stdoutSpawner(
333+
(command, args) => {
334+
expect(command).toBe(maintenancePath);
335+
expect(args).toEqual(["--version"]);
336+
probes++;
337+
return fixture.output;
338+
},
339+
() => fixture.exitCode,
340+
),
341+
),
342+
)),
343+
latestVersion: "3.0.0",
344+
};
345+
const snapshot = {
346+
...installedPackageToolProvider,
347+
version: "3.0.0",
348+
installedVersion: "3.0.0",
349+
};
350+
const enrich = (useMaintenanceVersion: boolean, enableProviderUpdateChecks = true) =>
351+
enrichProviderSnapshotWithVersionAdvisory(snapshot, capabilities, {
352+
enableProviderUpdateChecks,
353+
useMaintenanceVersion,
354+
});
355+
yield* enrich(true, false);
356+
expect(probes).toBe(0);
357+
const verification = yield* enrich(false);
358+
expect(verification.versionAdvisory?.currentVersion).toBe("3.0.0");
359+
expect(probes).toBe(0);
360+
const advisory = yield* enrich(true);
361+
expect(advisory.version).toBe("3.0.0");
362+
expect(advisory.installedVersion).toBe("3.0.0");
363+
expect(advisory.versionAdvisory).toMatchObject({
364+
currentVersion: fixture.expected,
365+
status: fixture.expected ? "behind_latest" : "unknown",
366+
});
367+
expect(probes).toBe(fixture.missing ? 0 : 1);
368+
}).pipe(
369+
Effect.provide(ProviderLatestVersions.layer),
370+
Effect.provideService(
371+
HttpClient.HttpClient,
372+
HttpClient.make(() => Effect.die("fixture latest version must not make an HTTP request")),
373+
),
374+
),
375+
{ skip: windowsHost },
376+
);
377+
310378
it.effect("does not fetch latest provider versions when update checks are disabled", () =>
311379
enrichProviderSnapshotWithVersionAdvisory(
312380
{ ...installedPackageToolProvider, installedVersion: "1.1.0" },
@@ -1159,29 +1227,100 @@ it.layer(
11591227
{ skip: !symlinksSupported || windowsHost },
11601228
);
11611229

1162-
it.effect.skipIf(windowsHost)(
1163-
"switches to bun updates when the resolved binary lives in bun's global bin",
1230+
it.effect.skipIf(windowsHost || !symlinksSupported)(
1231+
"binds bun updates to the selected global installation and rejects unproven ownership",
11641232
() =>
11651233
Effect.gen(function* () {
11661234
const tempDir = yield* makeTempDir("t3-bun-capabilities");
1167-
const bunBinDir = NodePath.join(tempDir, ".bun", "bin");
1168-
writeExecutable(NodePath.join(bunBinDir, "package-tool"));
1169-
1170-
const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
1171-
packageToolUpdate,
1172-
{
1173-
binaryPath: "package-tool",
1174-
env: { PATH: bunBinDir },
1175-
},
1176-
).pipe(
1177-
Effect.provideService(HostProcess.Platform, "darwin"),
1178-
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
1235+
const bunBinDir = NodePath.join(tempDir, "selected", ".bun", "bin");
1236+
const globalDir = NodePath.join(tempDir, "selected", ".bun", "install", "global");
1237+
const packagePath = NodePath.join(
1238+
globalDir,
1239+
"node_modules",
1240+
"@example",
1241+
"package-tool",
1242+
"bin",
1243+
"package-tool.js",
11791244
);
1245+
writeExecutable(packagePath);
1246+
const maintenancePath = NodePath.join(bunBinDir, "package-tool");
1247+
NodeFS.mkdirSync(bunBinDir, { recursive: true });
1248+
NodeFS.symlinkSync(packagePath, maintenancePath);
1249+
const runtimePath = NodePath.join(tempDir, "default", ".bun", "bin", "package-tool");
1250+
writeExecutable(runtimePath);
1251+
const env = {
1252+
PATH: NodePath.dirname(runtimePath),
1253+
BUN_INSTALL_GLOBAL_DIR: NodePath.join(tempDir, "default", ".bun", "install", "global"),
1254+
BUN_INSTALL_BIN: NodePath.dirname(runtimePath),
1255+
};
1256+
1257+
const resolve = () =>
1258+
resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
1259+
binaryPath: runtimePath,
1260+
maintenanceBinaryPath: maintenancePath,
1261+
env,
1262+
}).pipe(
1263+
Effect.provideService(HostProcess.Platform, "darwin"),
1264+
Effect.provideService(HostProcess.Environment, env),
1265+
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
1266+
);
11801267

1268+
const capabilities = yield* resolve();
11811269
expect(capabilities.update).toMatchObject({
11821270
command: "bun i -g @example/package-tool@latest",
1183-
lockKey: "bun-global",
1271+
lockKey: `bun-global:${normalizeCommandPath(globalDir)}`,
1272+
env: { ...env, BUN_INSTALL_GLOBAL_DIR: globalDir, BUN_INSTALL_BIN: bunBinDir },
1273+
});
1274+
expect(makeTargetedProviderUpdateAction(capabilities, "2.0.0")).toMatchObject({
1275+
args: ["i", "-g", "@example/[email protected]"],
1276+
env: capabilities.update?.env,
1277+
});
1278+
1279+
for (const target of [
1280+
NodePath.join(globalDir, "node_modules", "@example", "other-package", "bin", "tool"),
1281+
NodePath.join(
1282+
tempDir,
1283+
"project",
1284+
"node_modules",
1285+
"@example",
1286+
"package-tool",
1287+
"bin",
1288+
"tool",
1289+
),
1290+
maintenancePath,
1291+
]) {
1292+
NodeFS.unlinkSync(maintenancePath);
1293+
writeExecutable(target);
1294+
if (target !== maintenancePath) NodeFS.symlinkSync(target, maintenancePath);
1295+
expect(yield* resolve()).toMatchObject({ update: null, installPath: target });
1296+
}
1297+
}),
1298+
);
1299+
1300+
it.effect.skipIf(windowsHost)(
1301+
"updates the explicit maintenance installation while keeping the runtime wrapper separate",
1302+
() =>
1303+
Effect.gen(function* () {
1304+
const tempDir = yield* makeTempDir("t3-wrapper-maintenance");
1305+
const wrapper = NodePath.join(tempDir, "agentfleet-launcher");
1306+
const nativePath = NodePath.join(tempDir, ".local", "bin", "native-package-tool");
1307+
writeExecutable(wrapper);
1308+
writeExecutable(nativePath);
1309+
const resolve = (maintenanceBinaryPath: string) =>
1310+
resolveProviderMaintenanceCapabilitiesEffect(nativePackageToolUpdate, {
1311+
binaryPath: wrapper,
1312+
maintenanceBinaryPath,
1313+
env: { PATH: "" },
1314+
}).pipe(
1315+
Effect.provideService(HostProcess.Platform, "darwin"),
1316+
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
1317+
);
1318+
expect((yield* resolve(nativePath)).update).toMatchObject({
1319+
executable: nativePath,
1320+
args: ["update"],
11841321
});
1322+
expect((yield* resolve(NodePath.join(tempDir, "missing"))).update).toBeNull();
1323+
expect((yield* resolve(" ")).update?.executable).toBe(wrapper);
11851324
}),
11861325
);
11871326

0 commit comments

Comments
 (0)