@devries-cameron20 / t3code-1 / commits / 90aa7669a8
Fork 0

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

fix(server): one compatibility lookup and one refusal for broken provider versions (#39427)

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>

Julius Marminge committed Nov 19, 2026 at 16:58 UTC 90aa7669a898cb4548663d4dedc63f215083e2bb
20 files changed +189 -85
apps/server/src/orchestration-v2/Adapters/AntigravityAdapterV2.ts
+1
@@ -286,6 +286,7 @@ export function makeAntigravityAcpAdapterFlavor(
286 supportsImagePrompts: true,
287 compactViaAdvertisedCommand: true,
288 requiresSignIn: isAntigravitySignInRequiredError,
289 + checksVersionAtHandshake: true,
290 // Antigravity can leave a prompt open without updates; long tools and approvals pause this.
291 promptInactivityTimeout: "15 minutes",
292 reportsPerTurnPromptUsage: true,
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
+9 -7
@@ -1,5 +1,6 @@
1 import { pipe } from "effect/Function";
2 import * as DocumentText from "../../provider/DocumentText.ts";
3 +import { brokenRuntimeError } from "../../provider/providerCompatibility.ts";
4 import { revertCodexThread } from "../../provider/CodexThreadRevert.ts";
5 import { historyResponseItems } from "@t3tools/provider-core/server/handoffBudget";
6 import { makeProviderTextDeltaCoalescer } from "./ProviderTextDeltaCoalescer.ts";
@@ -1947,6 +1948,7 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
1948 return ProviderAdapter.ProviderAdapterV2.of({
1949 instanceId: adapterOptions.instanceId,
1950 driver: CODEX_PROVIDER,
1951 + checksVersionAtHandshake: adapterOptions.compatibility !== undefined,
1952 getCapabilities: Effect.fn("CodexAdapterV2.getCapabilities")(function () {
1953 return Effect.succeed(CodexProviderCapabilitiesV2);
1954 }),
@@ -2074,15 +2076,15 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
2076 version && adapterOptions.compatibility
2077 ? yield* adapterOptions.compatibility(version)
2078 : undefined;
2077 - if (advisory?.status === "broken") {
2078 - const target =
2079 - advisory.recommendedVersion ?? advisory.recommendedRange ?? "a newer version";
2080 - return yield* new ProviderSetupError({
2079 + const refused =
2080 + version &&
2081 + brokenRuntimeError({
2082 instanceId: adapterOptions.instanceId,
2082 - operation: "runtime",
2083 - detail: `Codex ${version} does not work with this T3 Code release. Update Codex to ${target}, then retry.`,
2083 + name: "Codex",
2084 + version,
2085 + advisory,
2086 });
2085 - }
2087 + if (refused) return yield* refused;
2088 yield* client.notify("initialized", undefined);
2089 yield* Ref.set(initialized, true);
2090 }),
apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts
+5 -4
@@ -40,6 +40,7 @@ import * as SqlitePersistence from "../persistence/Sqlite.ts";
40 import * as ProjectEnrichmentService from "../project/ProjectEnrichmentService.ts";
41 import * as ProjectService from "../project/ProjectService.ts";
42 import type { ProviderInstance } from "@t3tools/provider-core/server/driver";
43 +import * as ModelManifest from "../provider/ModelManifest.ts";
44 import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
45 import * as ServerSettings from "../serverSettings.ts";
46 import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
@@ -108,16 +109,16 @@ const providerInstance = {
109 textGeneration: {} as ProviderInstance["textGeneration"],
110 } satisfies ProviderInstance;
111
111 -const layerTestProviderInstanceRegistry = Layer.succeed(
112 - ProviderInstanceRegistry.ProviderInstanceRegistry,
113 - {
112 +const layerTestProviderInstanceRegistry = Layer.merge(
113 + ModelManifest.layerTest,
114 + Layer.succeed(ProviderInstanceRegistry.ProviderInstanceRegistry, {
115 getInstance: (instanceId) =>
116 Effect.succeed(instanceId === providerInstance.instanceId ? providerInstance : undefined),
117 listInstances: Effect.succeed([providerInstance]),
118 listUnavailable: Effect.succeed([]),
119 streamChanges: Stream.empty,
120 subscribeChanges: Effect.never,
120 - },
121 + }),
122 );
123
124 const layerTest = Layer.mergeAll(
apps/server/src/orchestration-v2/ProjectSettingsUpgrade.integration.test.ts
+2
@@ -21,6 +21,7 @@ import * as SqlitePersistence from "../persistence/Sqlite.ts";
21 import { runMigrations } from "../persistence/Migrations.ts";
22 import * as ProjectEnrichmentService from "../project/ProjectEnrichmentService.ts";
23 import * as ProjectService from "../project/ProjectService.ts";
24 +import * as ModelManifest from "../provider/ModelManifest.ts";
25 import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
26 import * as ServerSettings from "../serverSettings.ts";
27 import * as SourceControlProviderRegistry from "../sourceControl/SourceControlProviderRegistry.ts";
@@ -156,6 +157,7 @@ const layerRuntime = (dbPath: string) => {
157 Layer.provide(layerCheckpointStore),
158 Layer.provide(layerServerConfig),
159 Layer.provide(ServerSettings.layerTest()),
160 + Layer.provide(ModelManifest.layerTest),
161 Layer.provide(
162 Layer.succeed(ProviderInstanceRegistry.ProviderInstanceRegistry, {
163 getInstance: () => Effect.undefined,
apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts
+51 -7
@@ -18,6 +18,7 @@ import * as Stream from "effect/Stream";
18 import * as ProviderAuthFlow from "@t3tools/provider-core/server/providerAuthFlow";
19 import type { ProviderAuthController } from "../provider/ProviderAuthService.ts";
20 import type { ProviderInstance } from "@t3tools/provider-core/server/driver";
21 +import * as ModelManifest from "../provider/ModelManifest.ts";
22 import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
23 import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts";
24 import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
@@ -40,6 +41,8 @@ const makeAdapter = (
41 const makeInstance = (
42 instanceId: ProviderInstanceId,
43 orchestrationAdapter: ProviderAdapter.ProviderAdapterV2["Service"],
44 + version: string | null = null,
45 + refreshedVersion = version,
46 ): ProviderInstance => ({
47 instanceId,
48 driverKind: driver,
@@ -49,7 +52,10 @@ const makeInstance = (
52 },
53 displayName: String(instanceId),
54 enabled: true,
52 - snapshot: {} as ProviderInstance["snapshot"],
55 + snapshot: {
56 + getSnapshot: Effect.succeed({ version }),
57 + refresh: Effect.succeed({ version: refreshedVersion }),
58 + } as unknown as ProviderInstance["snapshot"],
59 orchestrationAdapter,
60 textGeneration: {} as ProviderInstance["textGeneration"],
61 });
@@ -68,20 +74,58 @@ const layerInstanceRegistry = Layer.succeed(ProviderInstanceRegistry.ProviderIns
74 streamChanges: Stream.empty,
75 subscribeChanges: Effect.never,
76 });
71 -const layerTest = ProviderAdapterRegistry.layerFromProviderInstanceRegistry.pipe(
72 - Layer.provide(layerInstanceRegistry),
77 +const layerRegistry = ProviderAdapterRegistry.layerFromProviderInstanceRegistry.pipe(
78 + Layer.provide(ModelManifest.layerTest),
79 );
80 +const layerTest = layerRegistry.pipe(Layer.provide(layerInstanceRegistry));
81
82 it.effect("routes two configured instances of the same driver independently", () =>
83 Effect.gen(function* () {
84 const registry = yield* ProviderAdapterRegistry.ProviderAdapterRegistryV2;
85
79 - assert.strictEqual(yield* registry.get(personalId), personalAdapter);
80 - assert.strictEqual(yield* registry.get(workId), workAdapter);
86 + assert.strictEqual((yield* registry.get(personalId)).instanceId, personalId);
87 + assert.strictEqual((yield* registry.get(workId)).instanceId, workId);
88 assert.deepEqual(yield* registry.list(), [personalId, workId]);
89 }).pipe(Effect.provide(layerTest)),
90 );
91
92 +const openOn = Effect.fn("openOn")(function* (instance: ProviderInstance) {
93 + const registry = yield* Effect.service(ProviderAdapterRegistry.ProviderAdapterRegistryV2).pipe(
94 + Effect.provide(
95 + layerRegistry.pipe(
96 + Layer.provide(
97 + Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({
98 + getInstance: () => Effect.succeed(instance),
99 + }),
100 + ),
101 + ),
102 + ),
103 + );
104 + return yield* (yield* registry.get(instance.instanceId))
105 + .openSession({
106 + threadId: ThreadId.make("gated-thread"),
107 + providerSessionId: ProviderSessionId.make("gated-session"),
108 + modelSelection: { instanceId: instance.instanceId, model: "test-model" },
109 + runtimePolicy: { runtimeMode: "full-access", interactionMode: "default", cwd: "/workspace" },
110 + })
111 + .pipe(Effect.exit);
112 +});
113 +
114 +it.effect("refuses a session only when a fresh probe still rates the version broken", () =>
115 + Effect.gen(function* () {
116 + const opened = { ...personalAdapter, openSession: () => Effect.succeed({} as never) };
117 + const refused = yield* openOn(makeInstance(personalId, opened, "0.100.0"));
118 + assert.include(JSON.stringify(refused), "0.100.0 does not work with this T3 Code release");
119 + // Updated since the last probe.
120 + assert.isTrue(
121 + Exit.isSuccess(yield* openOn(makeInstance(personalId, opened, "0.100.0", "0.200.0"))),
122 + );
123 + // An adapter that rates the handshake version is not judged on the probe.
124 + const handshake = { ...opened, checksVersionAtHandshake: true };
125 + assert.isTrue(Exit.isSuccess(yield* openOn(makeInstance(personalId, handshake, "0.100.0"))));
126 + }),
127 +);
128 +
129 it.effect(
130 "blocks a new session while another instance changes their shared provider credentials",
131 () =>
@@ -104,7 +148,7 @@ it.effect(
148 ProviderAdapterRegistry.ProviderAdapterRegistryV2,
149 ).pipe(
150 Effect.provide(
107 - ProviderAdapterRegistry.layerFromProviderInstanceRegistry.pipe(
151 + layerRegistry.pipe(
152 Layer.provide(
153 Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({
154 getInstance: (id) =>
@@ -166,7 +210,7 @@ it.effect("interrupts admitted session startup when a shared peer signs out", ()
210 ];
211 const registry = yield* Effect.service(ProviderAdapterRegistry.ProviderAdapterRegistryV2).pipe(
212 Effect.provide(
169 - ProviderAdapterRegistry.layerFromProviderInstanceRegistry.pipe(
213 + layerRegistry.pipe(
214 Layer.provide(
215 Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({
216 getInstance: (id) =>
apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts
+26 -2
@@ -2,6 +2,7 @@ import {
2 ProviderInstanceId,
3 ProviderSetupError,
4 type OrchestrationV2ProviderCapabilities,
5 + type ServerProvider,
6 } from "@t3tools/contracts";
7 import * as Context from "effect/Context";
8 import * as Effect from "effect/Effect";
@@ -9,6 +10,8 @@ import * as Layer from "effect/Layer";
10 import * as Schema from "effect/Schema";
11 import * as Scope from "effect/Scope";
12
13 +import * as ModelManifest from "../provider/ModelManifest.ts";
14 +import { brokenRuntimeError } from "../provider/providerCompatibility.ts";
15 import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
16 import { ProviderAdapterDriverCreateError } from "@t3tools/provider-core/server/adapterDriver";
17 import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
@@ -62,11 +65,12 @@ export class ProviderAdapterRegistryV2 extends Context.Service<
65 export const layerFromProviderInstanceRegistry: Layer.Layer<
66 ProviderAdapterRegistryV2,
67 never,
65 - ProviderInstanceRegistry.ProviderInstanceRegistry
68 + ProviderInstanceRegistry.ProviderInstanceRegistry | ModelManifest.ModelManifest
69 > = Layer.effect(
70 ProviderAdapterRegistryV2,
71 Effect.gen(function* () {
72 const instances = yield* ProviderInstanceRegistry.ProviderInstanceRegistry;
73 + const manifest = yield* ModelManifest.ModelManifest;
74 return ProviderAdapterRegistryV2.of({
75 get: Effect.fn("ProviderAdapterRegistryV2.get")(function (instanceId) {
76 return instances.getInstance(instanceId).pipe(
@@ -75,11 +79,31 @@ export const layerFromProviderInstanceRegistry: Layer.Layer<
79 return new ProviderAdapterRegistryLookupError({ instanceId });
80 const adapter = instance.orchestrationAdapter;
81 const auth = instance.auth;
78 - if (!auth) return Effect.succeed(adapter);
82 + const refuseBroken = Effect.fnUntraced(function* (snapshot: ServerProvider) {
83 + return snapshot.version
84 + ? brokenRuntimeError({
85 + instanceId,
86 + name: snapshot.displayName ?? instance.displayName ?? adapter.driver,
87 + version: snapshot.version,
88 + advisory: ModelManifest.providerCompatibility(
89 + yield* manifest.current,
90 + adapter.driver,
91 + snapshot.version,
92 + ),
93 + })
94 + : undefined;
95 + });
96 return Effect.succeed({
97 ...adapter,
98 openSession: (input) => {
99 const open = Effect.gen(function* () {
100 + if (!adapter.checksVersionAtHandshake) {
101 + let refused = yield* refuseBroken(yield* instance.snapshot.getSnapshot);
102 + // The last probe may predate an update, so look again before refusing.
103 + if (refused) refused = yield* refuseBroken(yield* instance.snapshot.refresh);
104 + if (refused) return yield* refused;
105 + }
106 + if (!auth) return yield* adapter.openSession(input);
107 const binding = auth.credentialBinding;
108 const related = binding
109 ? (yield* instances.listInstances).filter(
apps/server/src/orchestration-v2/runtimeLayer.test.ts
+5 -4
@@ -66,6 +66,7 @@ import * as ProjectEnrichmentService from "../project/ProjectEnrichmentService.t
66 import * as ProjectService from "../project/ProjectService.ts";
67 import * as ServerSettings from "../serverSettings.ts";
68 import * as McpSessionRegistryTestkit from "../mcp/McpSessionRegistry.testkit.ts";
69 +import * as ModelManifest from "../provider/ModelManifest.ts";
70 import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts";
71 import type { ProviderInstance } from "@t3tools/provider-core/server/driver";
72 import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
@@ -209,9 +210,9 @@ const antigravityProviderInstance = {
210 },
211 } satisfies ProviderInstance;
212
212 -const layerTestProviderInstanceRegistry = Layer.succeed(
213 - ProviderInstanceRegistry.ProviderInstanceRegistry,
214 - {
213 +const layerTestProviderInstanceRegistry = Layer.merge(
214 + ModelManifest.layerTest,
215 + Layer.succeed(ProviderInstanceRegistry.ProviderInstanceRegistry, {
216 getInstance: (instanceId) =>
217 Effect.succeed(
218 [
@@ -230,7 +231,7 @@ const layerTestProviderInstanceRegistry = Layer.succeed(
231 listUnavailable: Effect.succeed([]),
232 streamChanges: Stream.empty,
233 subscribeChanges: Effect.never,
233 - },
234 + }),
235 );
236
237 const watchedPullRequestDetail = (input: {
apps/server/src/provider/AntigravityInstallation.ts
+1 -10
@@ -1,7 +1,6 @@
1 // @effect-diagnostics nodeBuiltinImport:off - Effect has no incremental digest or free-space query.
2 import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
3 import * as ModelManifest from "./ModelManifest.ts";
4 -import { resolveProviderCompatibility } from "./providerCompatibility.ts";
4 import { cliArchiveTarCommand } from "@t3tools/shared/cliRelease";
5 import { compareSemverVersions } from "@t3tools/shared/semver";
6 import {
@@ -231,15 +230,7 @@ export const makeAntigravityInstallation = Effect.fn("AntigravityInstallation.ma
230 const compatibility = Effect.fn("AntigravityInstallation.compatibility")(function* (
231 version: string,
232 ) {
234 - const manifest = yield* manifestService.current;
235 - return (
236 - resolveProviderCompatibility(manifest.compatibility, DRIVER, version) ??
237 - resolveProviderCompatibility(
238 - ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility,
239 - DRIVER,
240 - version,
241 - )
242 - );
233 + return ModelManifest.providerCompatibility(yield* manifestService.current, DRIVER, version);
234 });
235 const isWithdrawn = Effect.fn("AntigravityInstallation.isWithdrawn")(function* (version: string) {
236 const status = (yield* compatibility(version))?.status;
apps/server/src/provider/CodexInstallation.ts
+1 -10
@@ -31,7 +31,6 @@ import * as NodeCrypto from "node:crypto";
31 import * as ServerConfig from "../config.ts";
32 import { selectManagedRelease } from "./managedRelease.ts";
33 import * as ModelManifest from "./ModelManifest.ts";
34 -import { resolveProviderCompatibility } from "./providerCompatibility.ts";
34
35 const DRIVER = ProviderDriverKind.make("codex");
36 const STAGING_STALE_AFTER_MS = 24 * 60 * 60_000;
@@ -299,15 +298,7 @@ export const makeCodexInstallation = Effect.fn("makeCodexInstallation")(function
298 return yield* fromDirectory(directory, version, record.target);
299 });
300 const compatibility = Effect.fn("CodexInstallation.compatibility")(function* (version: string) {
302 - const manifest = yield* manifestService.current;
303 - return (
304 - resolveProviderCompatibility(manifest.compatibility, DRIVER, version) ??
305 - resolveProviderCompatibility(
306 - ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility,
307 - DRIVER,
308 - version,
309 - )
310 - );
301 + return ModelManifest.providerCompatibility(yield* manifestService.current, DRIVER, version);
302 });
303 const isSupported = (version: string) =>
304 compatibility(version).pipe(Effect.map((advisory) => advisory?.status === "supported"));
apps/server/src/provider/Drivers/AntigravityDriver.ts
+13 -11
@@ -34,6 +34,7 @@ import {
34 } from "../../textGeneration/AntigravityTextGeneration.ts";
35 import { makeAntigravityAuth, type AntigravityAuth } from "../AntigravityAuth.ts";
36 import * as AntigravityInstallation from "../AntigravityInstallation.ts";
37 +import { brokenRuntimeError } from "../providerCompatibility.ts";
38 import * as AntigravityUsage from "./AntigravityUsage.ts";
39 import {
40 antigravityAuthConfigIssue,
@@ -317,19 +318,20 @@ export const AntigravityDriver: ProviderDriver<
318 const startCompatible = Effect.fn("AntigravityDriver.startCompatible")(function* () {
319 const version = (yield* runtime.initialize()).agentInfo?.version;
320 const advisory = version ? yield* installation.compatibility(version) : undefined;
320 - if (advisory?.status === "broken") {
321 - const target =
322 - advisory.recommendedVersion ?? advisory.recommendedRange ?? "a newer version";
323 - const update =
324 - executable.source === "managed"
325 - ? `Update it in Antigravity setup to ${target}`
326 - : `Update the Antigravity executable at ${executable.executablePath} to ${target}`;
327 - const cause = new ProviderSetupError({
321 + const refused =
322 + version &&
323 + brokenRuntimeError({
324 instanceId,
329 - operation: "runtime",
330 - detail: `Antigravity ${version} does not work with this T3 Code release. ${update}, then retry.`,
325 + name: "Antigravity",
326 + version,
327 + advisory,
328 + action:
329 + executable.source === "managed"
330 + ? "Update it in Antigravity setup"
331 + : `Update the Antigravity executable at ${executable.executablePath}`,
332 });
332 - return yield* new AcpErrors.AcpTransportError({ detail: cause.detail, cause });
333 + if (refused) {
334 + return yield* new AcpErrors.AcpTransportError({ detail: refused.detail, cause: refused });
335 }
336 return yield* runtime.start();
337 });
apps/server/src/provider/ModelManifest.ts
+13 -1
@@ -19,7 +19,10 @@ import { ServerConfig } from "../config.ts";
19 import * as ServerSettings from "../serverSettings.ts";
20 import { hasValidClaudeManifestAdapters } from "./ClaudeModelManifest.ts";
21 import bundledManifestJson from "./model-manifest.json" with { type: "json" };
22 -import { ProviderCompatibilityPolicy } from "./providerCompatibility.ts";
22 +import {
23 + ProviderCompatibilityPolicy,
24 + resolveProviderCompatibility,
25 +} from "./providerCompatibility.ts";
26 import * as ModelCatalog from "@t3tools/provider-core/server/ModelCatalog";
27
28 const MODEL_MANIFEST_URL =
@@ -107,6 +110,15 @@ const decodeManifest = Schema.decodeUnknownEffect(ModelManifestSchema);
110 export const BUNDLED_MODEL_MANIFEST: ModelManifestData =
111 Schema.decodeUnknownSync(ModelManifestSchema)(bundledManifestJson);
112
113 +/** A manifest with no policy for this driver and release falls back to the bundled one. */
114 +export const providerCompatibility = (
115 + manifest: ModelManifestData,
116 + driver: ProviderDriverKind,
117 + version: string | null,
118 +) =>
119 + resolveProviderCompatibility(manifest.compatibility, driver, version) ??
120 + resolveProviderCompatibility(BUNDLED_MODEL_MANIFEST.compatibility, driver, version);
121 +
122 function manifestUpdatedAtMs(manifest: ModelManifestData): number {
123 if (manifest.updatedAt === undefined) return 0;
124 const parsed = Date.parse(manifest.updatedAt);
apps/server/src/provider/antigravityCliRelease.test.ts
-1
@@ -38,7 +38,6 @@ describe("Antigravity CLI release manifests", () => {
38
39 it.each([
40 { sha512: "invalid" },
41 - { version: "1.4.5" },
41 { url: manifest.url.replace("https:", "http:") },
42 { url: manifest.url.replace("storage.googleapis.com", "storage.googleapis.com.evil.test") },
43 { url: manifest.url.replace("antigravity-public", "another-bucket") },
apps/server/src/provider/antigravityCliRelease.ts
-2
@@ -1,5 +1,4 @@
1 import * as Schema from "effect/Schema";
2 -import { compareSemverVersions } from "@t3tools/shared/semver";
2
3 export const ANTIGRAVITY_CLI_MANIFEST_BASE =
4 "https://antigravity-cli-auto-updater-974169037036.us-central1.run.app/manifests";
@@ -36,7 +35,6 @@ export function parseAntigravityCliRelease(
35 const decoded = decodeManifest(value);
36 if (decoded._tag === "None" || antigravityCliTarget(platform, arch, musl) === null) return null;
37 const manifest = decoded.value;
39 - if (compareSemverVersions(manifest.version, "1.5.0") < 0) return null;
38 const os = platform === "darwin" ? "mac" : platform === "win32" ? "windows" : "linux";
39 const cpu = arch === "x64" ? "x64" : "arm64";
40 const suffix = platform === "linux" && musl ? "_musl" : "";
apps/server/src/provider/model-manifest.json
+5 -1
@@ -1,6 +1,6 @@
1 {
2 "version": 1,
3 - "updatedAt": "2026-11-19T00:00:00Z",
3 + "updatedAt": "2026-11-19T23:30:00Z",
4 "compatibility": [
5 {
6 "driver": "codex",
@@ -35,6 +35,7 @@
35 {
36 "driver": "cursor",
37 "t3CodeRange": ">=0.0.42",
38 + "versionPattern": "^(\\d{4}\\.\\d{2}\\.\\d{2})-[a-f0-9]+$",
39 "recommendedRange": ">=2026.05.09",
40 "ranges": [
41 { "range": ">=2026.05.09", "status": "supported" },
@@ -75,6 +76,7 @@
76 {
77 "driver": "antigravity",
78 "t3CodeRange": ">=0.0.42 <0.1.10",
79 + "versionPattern": "^(?:agy_acp_server_)?(\\d+\\.\\d+\\.\\d+)(?:-[0-9A-Za-z.-]+)?$",
80 "recommendedRange": "=1.4.5 || =1.4.1",
81 "ranges": [
82 { "range": "=1.4.5", "status": "supported" },
@@ -86,6 +88,7 @@
88 {
89 "driver": "antigravity",
90 "t3CodeRange": ">=0.1.10",
91 + "versionPattern": "^(?:agy_acp_server_)?(\\d+\\.\\d+\\.\\d+)(?:-[0-9A-Za-z.-]+)?$",
92 "recommendedRange": ">=1.5.12 <2",
93 "ranges": [
94 { "range": ">=1.5.0 <2", "status": "supported" },
@@ -110,6 +113,7 @@
113 {
114 "driver": "muse",
115 "t3CodeRange": ">=0.0.46",
116 + "versionPattern": "^(\\d+\\.\\d+\\.\\d+)-R\\d+(?:\\.\\d+)?$",
117 "recommendedRange": ">=1.4.2",
118 "ranges": [
119 { "range": ">=1.4.2", "status": "supported" },
apps/server/src/provider/providerCompatibility.test.ts
+1
@@ -88,6 +88,7 @@ describe("provider compatibility", () => {
88 const cursorPolicy: ProviderCompatibilityPolicy = {
89 driver: cursor,
90 t3CodeRange: policy.t3CodeRange,
91 + versionPattern: "^(\\d{4}\\.\\d{2}\\.\\d{2})-[a-f0-9]+$",
92 ranges: [
93 { range: "<2026.05.09", status: "unsupported" },
94 { range: ">=2026.05.09", status: "supported" },
apps/server/src/provider/providerCompatibility.ts
+41 -17
@@ -1,7 +1,9 @@
1 import {
2 + ProviderSetupError,
3 TrimmedNonEmptyString,
4 ServerProviderCompatibilityStatus,
5 type ProviderDriverKind,
6 + type ProviderInstanceId,
7 type ServerProvider,
8 type ServerProviderCompatibilityAdvisory,
9 } from "@t3tools/contracts";
@@ -22,9 +24,22 @@ const VersionRange = TrimmedNonEmptyString.pipe(
24 ),
25 ),
26 );
27 +const compilePattern = (pattern: string) => {
28 + try {
29 + return new RegExp(pattern, "u");
30 + } catch {
31 + return undefined;
32 + }
33 +};
34 const Policy = Schema.Struct({
35 driver: TrimmedNonEmptyString,
36 t3CodeRange: VersionRange,
37 + /** Matches a reported version that is not plain `X.Y.Z`; its first group is the version to rate. */
38 + versionPattern: Schema.optionalKey(
39 + TrimmedNonEmptyString.pipe(
40 + Schema.check(Schema.makeFilter((value) => compilePattern(value) !== undefined)),
41 + ),
42 + ),
43 recommendedRange: Schema.optionalKey(VersionRange),
44 recommendedVersion: Schema.optionalKey(StableVersion),
45 ranges: Schema.Array(
@@ -65,16 +80,9 @@ export function resolveProviderCompatibility(
80 );
81 if (!policy) return undefined;
82 const unprefixed = version?.replace(/^v/, "");
68 - // Strip Cursor build hashes and Muse revisions; leave other prereleases unknown. Antigravity
69 - // drops its pre-CLI prefix and prerelease suffix, so a custom launcher below 1.5 resolves broken.
70 - const stable =
71 - driver === "cursor"
72 - ? unprefixed?.replace(/^(\d{4}\.\d{2}\.\d{2})-[a-f0-9]+$/, "$1")
73 - : driver === "muse"
74 - ? unprefixed?.replace(/^(\d+\.\d+\.\d+)-R\d+(?:\.\d+)?$/, "$1")
75 - : driver === "antigravity"
76 - ? unprefixed?.replace(/^(?:agy_acp_server_)?(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?$/, "$1")
77 - : unprefixed;
83 + // Without a pattern, build hashes, revisions and prereleases stay unknown.
84 + const pattern = policy.versionPattern ? compilePattern(policy.versionPattern) : undefined;
85 + const stable = (pattern && unprefixed?.match(pattern)?.[1]) || unprefixed;
86 const status =
87 stable && /^\d+\.\d+\.\d+$/.test(stable)
88 ? (policy.ranges.find((entry) => satisfiesSemverRange(stable, entry.range))?.status ??
@@ -99,6 +107,24 @@ export function resolveProviderCompatibility(
107 };
108 }
109
110 +/** The one refusal for a runtime the policy rates `broken`; `action` names how this runtime is updated. */
111 +export function brokenRuntimeError(input: {
112 + readonly instanceId: ProviderInstanceId;
113 + readonly name: string;
114 + readonly version: string;
115 + readonly advisory: ServerProviderCompatibilityAdvisory | undefined;
116 + readonly action?: string;
117 +}): ProviderSetupError | undefined {
118 + if (input.advisory?.status !== "broken") return undefined;
119 + const target =
120 + input.advisory.recommendedVersion ?? input.advisory.recommendedRange ?? "a newer version";
121 + return new ProviderSetupError({
122 + instanceId: input.instanceId,
123 + operation: "runtime",
124 + detail: `${input.name} ${input.version} does not work with this T3 Code release. ${input.action ?? `Update ${input.name}`} to ${target}, then retry.`,
125 + });
126 +}
127 +
128 export function applyProviderCompatibility(
129 snapshot: ServerProvider,
130 policies: ReadonlyArray<ProviderCompatibilityPolicy> | undefined,
@@ -106,14 +132,12 @@ export function applyProviderCompatibility(
132 ): ServerProvider {
133 const { compatibilityAdvisory: _previous, ...base } = snapshot;
134 if (!snapshot.enabled || !snapshot.installed) return base;
109 - const advisory =
110 - resolveProviderCompatibility(policies, snapshot.driver, snapshot.version) ??
111 - resolveProviderCompatibility(fallback, snapshot.driver, snapshot.version);
135 + const resolve = (version: string | null) =>
136 + resolveProviderCompatibility(policies, snapshot.driver, version) ??
137 + resolveProviderCompatibility(fallback, snapshot.driver, version);
138 + const advisory = resolve(snapshot.version);
139 const latestVersion = snapshot.versionAdvisory?.latestVersion;
113 - const latestAdvisory = latestVersion
114 - ? (resolveProviderCompatibility(policies, snapshot.driver, latestVersion) ??
115 - resolveProviderCompatibility(fallback, snapshot.driver, latestVersion))
116 - : undefined;
140 + const latestAdvisory = latestVersion ? resolve(latestVersion) : undefined;
141 const updateCommand = snapshot.versionAdvisory?.updateCommand;
142 // The maintenance resolver emits this command only for confirmed Homebrew installs.
143 const needsHomebrewRefresh =
apps/server/src/provider/providerMaintenanceRunner.ts
+5 -8
@@ -24,7 +24,6 @@ import { ChildProcess, ChildProcessSpawner } from "effect/process";
24 import * as NodeUtil from "node:util";
25
26 import * as ModelManifest from "./ModelManifest.ts";
27 -import { resolveProviderCompatibility } from "./providerCompatibility.ts";
27 import * as ProviderInstallationGate from "./ProviderInstallationGate.ts";
28 import * as ProviderRegistry from "./ProviderRegistry.ts";
29 import { makeProviderMaintenanceCommandCoordinator } from "./providerMaintenanceCommandCoordinator.ts";
@@ -515,13 +514,11 @@ export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () {
514 latestVersions,
515 ),
516 ));
518 - const advisory =
519 - resolveProviderCompatibility(manifest.compatibility, provider, candidateVersion) ??
520 - resolveProviderCompatibility(
521 - ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility,
522 - provider,
523 - candidateVersion,
524 - );
517 + const advisory = ModelManifest.providerCompatibility(
518 + manifest,
519 + provider,
520 + candidateVersion,
521 + );
522 const command =
523 targetVersion !== undefined
524 ? makeTargetedProviderUpdateAction(fresh, targetVersion)
docs/internals/adding-a-provider.md
+2
@@ -121,6 +121,8 @@ A provider lives in its own `packages/provider-<name>` package, with
121 adapter driver. Also its position in the [status order](../../apps/server/src/provider/providerStatusCache.ts), a
122 compatibility policy in [`model-manifest.json`](../../apps/server/src/provider/model-manifest.json)
123 (bump `updatedAt`; see [model manifest](./model-manifest.md)), and its default model in contracts.
124 + A `broken` range refuses new sessions for that driver, so declare a minimum there, not as a
125 + constant in the driver. A version that is not plain `X.Y.Z` needs the policy's `versionPattern`.
126 - **Client registration:** the client definition in the web and mobile provider registries, and
127 settings search terms. Clients draw the package icon; do not add a per-driver icon branch.
128 - **Docs:** a `docs/user/providers-<name>.md` guide in the product's voice, a row in the
packages/provider-acp/src/server/adapter.ts
+3
@@ -380,6 +380,8 @@ export interface AcpAdapterV2Flavor {
380 readonly promptCapabilities: EffectAcpSchema.AgentCapabilities["promptCapabilities"];
381 }) => Effect.Effect<ReadonlyArray<EffectAcpSchema.ContentBlock>, EffectAcpErrors.AcpError>;
382 readonly promptFailure?: (cause: unknown) => OrchestrationV2ProviderFailure;
383 + /** The flavor's runtime refuses a version the policy rates broken when it starts. */
384 + readonly checksVersionAtHandshake?: boolean;
385 /**
386 * Runs before `session/prompt`. The returned check sees a prompt the agent ended
387 * without an error or cancel, and reports a failure its stop reason hid. A reported
@@ -2001,6 +2003,7 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
2003 return ProviderAdapter.ProviderAdapterV2.of({
2004 instanceId: options.instanceId,
2005 driver,
2006 + checksVersionAtHandshake: flavor.checksVersionAtHandshake === true,
2007 getCapabilities: Effect.fn("AcpAdapter.getCapabilities")(function* () {
2008 return yield* readCapabilities;
2009 }),
packages/provider-core/src/server/ProviderAdapter.ts
+5
@@ -817,6 +817,11 @@ export class ProviderAdapterV2 extends Context.Service<
817 {
818 readonly instanceId: ProviderInstanceId;
819 readonly driver: ProviderDriverKind;
820 + /**
821 + * Set when `openSession` rates the version the runtime reports at its handshake. The host then
822 + * skips its own check, which only knows the version from the last status probe.
823 + */
824 + readonly checksVersionAtHandshake?: boolean;
825 readonly getCapabilities: () => Effect.Effect<
826 OrchestrationV2ProviderCapabilities,
827 ProviderAdapterV2Error