From f7ee5dbd206d7c239759ae7d754b2bab5a9442ea Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Thu, 19 Nov 2026 15:27:40 -0800 Subject: [PATCH 1/3] refactor(server): one compatibility lookup and one refusal for broken provider versions Every provider session now opens through one check that refuses a version the manifest rates broken; Codex and Antigravity keep a second call of the same helper for versions only known at the handshake. The manifest lookup with bundled fallback is one function, per-driver version normalisation moves to the policy's versionPattern, and the Antigravity installer no longer hard-codes its 1.5.0 floor. Co-Authored-By: Claude Fable 5.2 --- apps/server/src/mcp/OrchestratorMcpService.ts | 5 ++ .../Adapters/CodexAdapterV2.ts | 15 ++--- .../DelegatedCompletionDelivery.test.ts | 9 +-- ...ProjectSettingsUpgrade.integration.test.ts | 2 + .../ProviderAdapterRegistry.test.ts | 50 +++++++++++++--- .../ProviderAdapterRegistry.ts | 22 ++++++- .../src/orchestration-v2/runtimeLayer.test.ts | 9 +-- .../src/provider/AntigravityInstallation.ts | 11 +--- apps/server/src/provider/CodexInstallation.ts | 11 +--- .../src/provider/Drivers/AntigravityDriver.ts | 24 ++++---- apps/server/src/provider/ModelManifest.ts | 14 ++++- .../src/provider/antigravityCliRelease.ts | 2 - apps/server/src/provider/model-manifest.json | 6 +- .../provider/providerCompatibility.test.ts | 1 + .../src/provider/providerCompatibility.ts | 58 +++++++++++++------ .../src/provider/providerMaintenanceRunner.ts | 13 ++--- docs/internals/adding-a-provider.md | 2 + 17 files changed, 170 insertions(+), 84 deletions(-) diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index c9009d6597671..23d914dcf4b7a 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -456,6 +456,11 @@ function providerConstraints( if (provider.auth.status === "unauthenticated") { constraints.push("Provider is not authenticated."); } + if (provider.compatibilityAdvisory?.status === "broken") { + constraints.push( + provider.compatibilityAdvisory.message ?? "Provider version does not work with T3 Code.", + ); + } return constraints; } diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts index 4474dd04273a0..4f894abdfd4bc 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts @@ -1,5 +1,6 @@ import { pipe } from "effect/Function"; import * as DocumentText from "../../provider/DocumentText.ts"; +import { brokenRuntimeError } from "../../provider/providerCompatibility.ts"; import { revertCodexThread } from "../../provider/CodexThreadRevert.ts"; import { historyResponseItems } from "@t3tools/provider-core/server/handoffBudget"; import { makeProviderTextDeltaCoalescer } from "./ProviderTextDeltaCoalescer.ts"; @@ -2049,15 +2050,15 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* ( version && adapterOptions.compatibility ? yield* adapterOptions.compatibility(version) : undefined; - if (advisory?.status === "broken") { - const target = - advisory.recommendedVersion ?? advisory.recommendedRange ?? "a newer version"; - return yield* new ProviderSetupError({ + const refused = + version && + brokenRuntimeError({ instanceId: adapterOptions.instanceId, - operation: "runtime", - detail: `Codex ${version} does not work with this T3 Code release. Update Codex to ${target}, then retry.`, + name: "Codex", + version, + advisory, }); - } + if (refused) return yield* refused; yield* client.notify("initialized", undefined); yield* Ref.set(initialized, true); }), diff --git a/apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts b/apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts index fd677a079d1d3..2edb8789337c9 100644 --- a/apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts +++ b/apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts @@ -40,6 +40,7 @@ import * as SqlitePersistence from "../persistence/Sqlite.ts"; import * as ProjectEnrichmentService from "../project/ProjectEnrichmentService.ts"; import * as ProjectService from "../project/ProjectService.ts"; import type { ProviderInstance } from "@t3tools/provider-core/server/driver"; +import * as ModelManifest from "../provider/ModelManifest.ts"; import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts"; @@ -108,16 +109,16 @@ const providerInstance = { textGeneration: {} as ProviderInstance["textGeneration"], } satisfies ProviderInstance; -const layerTestProviderInstanceRegistry = Layer.succeed( - ProviderInstanceRegistry.ProviderInstanceRegistry, - { +const layerTestProviderInstanceRegistry = Layer.merge( + ModelManifest.layerTest, + Layer.succeed(ProviderInstanceRegistry.ProviderInstanceRegistry, { getInstance: (instanceId) => Effect.succeed(instanceId === providerInstance.instanceId ? providerInstance : undefined), listInstances: Effect.succeed([providerInstance]), listUnavailable: Effect.succeed([]), streamChanges: Stream.empty, subscribeChanges: Effect.never, - }, + }), ); const layerTest = Layer.mergeAll( diff --git a/apps/server/src/orchestration-v2/ProjectSettingsUpgrade.integration.test.ts b/apps/server/src/orchestration-v2/ProjectSettingsUpgrade.integration.test.ts index b27b6604b1435..99378a88464ce 100644 --- a/apps/server/src/orchestration-v2/ProjectSettingsUpgrade.integration.test.ts +++ b/apps/server/src/orchestration-v2/ProjectSettingsUpgrade.integration.test.ts @@ -21,6 +21,7 @@ import * as SqlitePersistence from "../persistence/Sqlite.ts"; import { runMigrations } from "../persistence/Migrations.ts"; import * as ProjectEnrichmentService from "../project/ProjectEnrichmentService.ts"; import * as ProjectService from "../project/ProjectService.ts"; +import * as ModelManifest from "../provider/ModelManifest.ts"; import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as SourceControlProviderRegistry from "../sourceControl/SourceControlProviderRegistry.ts"; @@ -156,6 +157,7 @@ const layerRuntime = (dbPath: string) => { Layer.provide(layerCheckpointStore), Layer.provide(layerServerConfig), Layer.provide(ServerSettings.layerTest()), + Layer.provide(ModelManifest.layerTest), Layer.provide( Layer.succeed(ProviderInstanceRegistry.ProviderInstanceRegistry, { getInstance: () => Effect.undefined, diff --git a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts index 46ff8ea2c1aee..e48cb9390e567 100644 --- a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts +++ b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts @@ -18,6 +18,7 @@ import * as Stream from "effect/Stream"; import * as ProviderAuthFlow from "@t3tools/provider-core/server/providerAuthFlow"; import type { ProviderAuthController } from "../provider/ProviderAuthService.ts"; import type { ProviderInstance } from "@t3tools/provider-core/server/driver"; +import * as ModelManifest from "../provider/ModelManifest.ts"; import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts"; import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts"; import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter"; @@ -40,6 +41,7 @@ const makeAdapter = ( const makeInstance = ( instanceId: ProviderInstanceId, orchestrationAdapter: ProviderAdapter.ProviderAdapterV2["Service"], + version: string | null = null, ): ProviderInstance => ({ instanceId, driverKind: driver, @@ -49,7 +51,9 @@ const makeInstance = ( }, displayName: String(instanceId), enabled: true, - snapshot: {} as ProviderInstance["snapshot"], + snapshot: { + getSnapshot: Effect.succeed({ version }), + } as unknown as ProviderInstance["snapshot"], orchestrationAdapter, textGeneration: {} as ProviderInstance["textGeneration"], }); @@ -68,20 +72,52 @@ const layerInstanceRegistry = Layer.succeed(ProviderInstanceRegistry.ProviderIns streamChanges: Stream.empty, subscribeChanges: Effect.never, }); -const layerTest = ProviderAdapterRegistry.layerFromProviderInstanceRegistry.pipe( - Layer.provide(layerInstanceRegistry), +const layerRegistry = ProviderAdapterRegistry.layerFromProviderInstanceRegistry.pipe( + Layer.provide(ModelManifest.layerTest), ); +const layerTest = layerRegistry.pipe(Layer.provide(layerInstanceRegistry)); it.effect("routes two configured instances of the same driver independently", () => Effect.gen(function* () { const registry = yield* ProviderAdapterRegistry.ProviderAdapterRegistryV2; - assert.strictEqual(yield* registry.get(personalId), personalAdapter); - assert.strictEqual(yield* registry.get(workId), workAdapter); + assert.strictEqual((yield* registry.get(personalId)).instanceId, personalId); + assert.strictEqual((yield* registry.get(workId)).instanceId, workId); assert.deepEqual(yield* registry.list(), [personalId, workId]); }).pipe(Effect.provide(layerTest)), ); +it.effect("refuses a session on a provider version the policy rates broken", () => + Effect.gen(function* () { + const broken = makeInstance(personalId, personalAdapter, "0.100.0"); + const registry = yield* Effect.service(ProviderAdapterRegistry.ProviderAdapterRegistryV2).pipe( + Effect.provide( + layerRegistry.pipe( + Layer.provide( + Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({ + getInstance: () => Effect.succeed(broken), + }), + ), + ), + ), + ); + const error = yield* (yield* registry.get(personalId)) + .openSession({ + threadId: ThreadId.make("broken-thread"), + providerSessionId: ProviderSessionId.make("broken-session"), + modelSelection: { instanceId: personalId, model: "test-model" }, + runtimePolicy: { + runtimeMode: "full-access", + interactionMode: "default", + cwd: "/workspace", + }, + }) + .pipe(Effect.flip); + assert.instanceOf(error, ProviderAdapter.ProviderAdapterOpenSessionError); + assert.include(String(error.cause), "0.100.0 does not work with this T3 Code release"); + }), +); + it.effect( "blocks a new session while another instance changes their shared provider credentials", () => @@ -104,7 +140,7 @@ it.effect( ProviderAdapterRegistry.ProviderAdapterRegistryV2, ).pipe( Effect.provide( - ProviderAdapterRegistry.layerFromProviderInstanceRegistry.pipe( + layerRegistry.pipe( Layer.provide( Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({ getInstance: (id) => @@ -166,7 +202,7 @@ it.effect("interrupts admitted session startup when a shared peer signs out", () ]; const registry = yield* Effect.service(ProviderAdapterRegistry.ProviderAdapterRegistryV2).pipe( Effect.provide( - ProviderAdapterRegistry.layerFromProviderInstanceRegistry.pipe( + layerRegistry.pipe( Layer.provide( Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({ getInstance: (id) => diff --git a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts index a04c1df887277..610a4288c6fd2 100644 --- a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts +++ b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts @@ -9,6 +9,8 @@ import * as Layer from "effect/Layer"; import * as Schema from "effect/Schema"; import * as Scope from "effect/Scope"; +import * as ModelManifest from "../provider/ModelManifest.ts"; +import { brokenRuntimeError } from "../provider/providerCompatibility.ts"; import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts"; import { ProviderAdapterDriverCreateError } from "@t3tools/provider-core/server/adapterDriver"; import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter"; @@ -62,11 +64,12 @@ export class ProviderAdapterRegistryV2 extends Context.Service< export const layerFromProviderInstanceRegistry: Layer.Layer< ProviderAdapterRegistryV2, never, - ProviderInstanceRegistry.ProviderInstanceRegistry + ProviderInstanceRegistry.ProviderInstanceRegistry | ModelManifest.ModelManifest > = Layer.effect( ProviderAdapterRegistryV2, Effect.gen(function* () { const instances = yield* ProviderInstanceRegistry.ProviderInstanceRegistry; + const manifest = yield* ModelManifest.ModelManifest; return ProviderAdapterRegistryV2.of({ get: Effect.fn("ProviderAdapterRegistryV2.get")(function (instanceId) { return instances.getInstance(instanceId).pipe( @@ -75,11 +78,26 @@ export const layerFromProviderInstanceRegistry: Layer.Layer< return new ProviderAdapterRegistryLookupError({ instanceId }); const adapter = instance.orchestrationAdapter; const auth = instance.auth; - if (!auth) return Effect.succeed(adapter); return Effect.succeed({ ...adapter, openSession: (input) => { const open = Effect.gen(function* () { + // Every provider is refused here on a version the policy rates broken. + const snapshot = yield* instance.snapshot.getSnapshot; + const refused = + snapshot.version && + brokenRuntimeError({ + instanceId, + name: snapshot.displayName ?? instance.displayName ?? adapter.driver, + version: snapshot.version, + advisory: ModelManifest.providerCompatibility( + yield* manifest.current, + adapter.driver, + snapshot.version, + ), + }); + if (refused) return yield* refused; + if (!auth) return yield* adapter.openSession(input); const binding = auth.credentialBinding; const related = binding ? (yield* instances.listInstances).filter( diff --git a/apps/server/src/orchestration-v2/runtimeLayer.test.ts b/apps/server/src/orchestration-v2/runtimeLayer.test.ts index f7e6e03bb460f..9b928dceda591 100644 --- a/apps/server/src/orchestration-v2/runtimeLayer.test.ts +++ b/apps/server/src/orchestration-v2/runtimeLayer.test.ts @@ -66,6 +66,7 @@ import * as ProjectEnrichmentService from "../project/ProjectEnrichmentService.t import * as ProjectService from "../project/ProjectService.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as McpSessionRegistryTestkit from "../mcp/McpSessionRegistry.testkit.ts"; +import * as ModelManifest from "../provider/ModelManifest.ts"; import * as ProviderInstanceRegistry from "../provider/ProviderInstanceRegistry.ts"; import type { ProviderInstance } from "@t3tools/provider-core/server/driver"; import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts"; @@ -209,9 +210,9 @@ const antigravityProviderInstance = { }, } satisfies ProviderInstance; -const layerTestProviderInstanceRegistry = Layer.succeed( - ProviderInstanceRegistry.ProviderInstanceRegistry, - { +const layerTestProviderInstanceRegistry = Layer.merge( + ModelManifest.layerTest, + Layer.succeed(ProviderInstanceRegistry.ProviderInstanceRegistry, { getInstance: (instanceId) => Effect.succeed( [ @@ -230,7 +231,7 @@ const layerTestProviderInstanceRegistry = Layer.succeed( listUnavailable: Effect.succeed([]), streamChanges: Stream.empty, subscribeChanges: Effect.never, - }, + }), ); const watchedPullRequestDetail = (input: { diff --git a/apps/server/src/provider/AntigravityInstallation.ts b/apps/server/src/provider/AntigravityInstallation.ts index e179eb5020f46..dadf9e5be3366 100644 --- a/apps/server/src/provider/AntigravityInstallation.ts +++ b/apps/server/src/provider/AntigravityInstallation.ts @@ -1,7 +1,6 @@ // @effect-diagnostics nodeBuiltinImport:off - Effect has no incremental digest or free-space query. import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion"; import * as ModelManifest from "./ModelManifest.ts"; -import { resolveProviderCompatibility } from "./providerCompatibility.ts"; import { cliArchiveTarCommand } from "@t3tools/shared/cliRelease"; import { compareSemverVersions } from "@t3tools/shared/semver"; import { @@ -231,15 +230,7 @@ export const makeAntigravityInstallation = Effect.fn("AntigravityInstallation.ma const compatibility = Effect.fn("AntigravityInstallation.compatibility")(function* ( version: string, ) { - const manifest = yield* manifestService.current; - return ( - resolveProviderCompatibility(manifest.compatibility, DRIVER, version) ?? - resolveProviderCompatibility( - ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility, - DRIVER, - version, - ) - ); + return ModelManifest.providerCompatibility(yield* manifestService.current, DRIVER, version); }); const isWithdrawn = Effect.fn("AntigravityInstallation.isWithdrawn")(function* (version: string) { const status = (yield* compatibility(version))?.status; diff --git a/apps/server/src/provider/CodexInstallation.ts b/apps/server/src/provider/CodexInstallation.ts index 87660f0c41800..ec0514fba967d 100644 --- a/apps/server/src/provider/CodexInstallation.ts +++ b/apps/server/src/provider/CodexInstallation.ts @@ -31,7 +31,6 @@ import * as NodeCrypto from "node:crypto"; import * as ServerConfig from "../config.ts"; import { selectManagedRelease } from "./managedRelease.ts"; import * as ModelManifest from "./ModelManifest.ts"; -import { resolveProviderCompatibility } from "./providerCompatibility.ts"; const DRIVER = ProviderDriverKind.make("codex"); const STAGING_STALE_AFTER_MS = 24 * 60 * 60_000; @@ -299,15 +298,7 @@ export const makeCodexInstallation = Effect.fn("makeCodexInstallation")(function return yield* fromDirectory(directory, version, record.target); }); const compatibility = Effect.fn("CodexInstallation.compatibility")(function* (version: string) { - const manifest = yield* manifestService.current; - return ( - resolveProviderCompatibility(manifest.compatibility, DRIVER, version) ?? - resolveProviderCompatibility( - ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility, - DRIVER, - version, - ) - ); + return ModelManifest.providerCompatibility(yield* manifestService.current, DRIVER, version); }); const isSupported = (version: string) => compatibility(version).pipe(Effect.map((advisory) => advisory?.status === "supported")); diff --git a/apps/server/src/provider/Drivers/AntigravityDriver.ts b/apps/server/src/provider/Drivers/AntigravityDriver.ts index 4292da255b1d9..78cf9ca19579a 100644 --- a/apps/server/src/provider/Drivers/AntigravityDriver.ts +++ b/apps/server/src/provider/Drivers/AntigravityDriver.ts @@ -32,6 +32,7 @@ import { } from "../../textGeneration/AntigravityTextGeneration.ts"; import { makeAntigravityAuth, type AntigravityAuth } from "../AntigravityAuth.ts"; import * as AntigravityInstallation from "../AntigravityInstallation.ts"; +import { brokenRuntimeError } from "../providerCompatibility.ts"; import * as AntigravityUsage from "./AntigravityUsage.ts"; import { antigravityAuthConfigIssue, @@ -296,19 +297,20 @@ export const AntigravityDriver: ProviderDriver< const startCompatible = Effect.fn("AntigravityDriver.startCompatible")(function* () { const version = (yield* runtime.initialize()).agentInfo?.version; const advisory = version ? yield* installation.compatibility(version) : undefined; - if (advisory?.status === "broken") { - const target = - advisory.recommendedVersion ?? advisory.recommendedRange ?? "a newer version"; - const update = - executable.source === "managed" - ? `Update it in Antigravity setup to ${target}` - : `Update the Antigravity executable at ${executable.executablePath} to ${target}`; - const cause = new ProviderSetupError({ + const refused = + version && + brokenRuntimeError({ instanceId, - operation: "runtime", - detail: `Antigravity ${version} does not work with this T3 Code release. ${update}, then retry.`, + name: "Antigravity", + version, + advisory, + action: + executable.source === "managed" + ? "Update it in Antigravity setup" + : `Update the Antigravity executable at ${executable.executablePath}`, }); - return yield* new AcpErrors.AcpTransportError({ detail: cause.detail, cause }); + if (refused) { + return yield* new AcpErrors.AcpTransportError({ detail: refused.detail, cause: refused }); } return yield* runtime.start(); }); diff --git a/apps/server/src/provider/ModelManifest.ts b/apps/server/src/provider/ModelManifest.ts index bd1e08af91be5..7d790b472f6aa 100644 --- a/apps/server/src/provider/ModelManifest.ts +++ b/apps/server/src/provider/ModelManifest.ts @@ -19,7 +19,10 @@ import { ServerConfig } from "../config.ts"; import * as ServerSettings from "../serverSettings.ts"; import { hasValidClaudeManifestAdapters } from "./ClaudeModelManifest.ts"; import bundledManifestJson from "./model-manifest.json" with { type: "json" }; -import { ProviderCompatibilityPolicy } from "./providerCompatibility.ts"; +import { + ProviderCompatibilityPolicy, + resolveProviderCompatibility, +} from "./providerCompatibility.ts"; import * as ModelCatalog from "@t3tools/provider-core/server/ModelCatalog"; const MODEL_MANIFEST_URL = @@ -107,6 +110,15 @@ const decodeManifest = Schema.decodeUnknownEffect(ModelManifestSchema); export const BUNDLED_MODEL_MANIFEST: ModelManifestData = Schema.decodeUnknownSync(ModelManifestSchema)(bundledManifestJson); +/** A manifest with no policy for this driver and release falls back to the bundled one. */ +export const providerCompatibility = ( + manifest: ModelManifestData, + driver: ProviderDriverKind, + version: string | null, +) => + resolveProviderCompatibility(manifest.compatibility, driver, version) ?? + resolveProviderCompatibility(BUNDLED_MODEL_MANIFEST.compatibility, driver, version); + function manifestUpdatedAtMs(manifest: ModelManifestData): number { if (manifest.updatedAt === undefined) return 0; const parsed = Date.parse(manifest.updatedAt); diff --git a/apps/server/src/provider/antigravityCliRelease.ts b/apps/server/src/provider/antigravityCliRelease.ts index 3e033beb37ace..d53f8a820bf2e 100644 --- a/apps/server/src/provider/antigravityCliRelease.ts +++ b/apps/server/src/provider/antigravityCliRelease.ts @@ -1,5 +1,4 @@ import * as Schema from "effect/Schema"; -import { compareSemverVersions } from "@t3tools/shared/semver"; export const ANTIGRAVITY_CLI_MANIFEST_BASE = "https://antigravity-cli-auto-updater-974169037036.us-central1.run.app/manifests"; @@ -36,7 +35,6 @@ export function parseAntigravityCliRelease( const decoded = decodeManifest(value); if (decoded._tag === "None" || antigravityCliTarget(platform, arch, musl) === null) return null; const manifest = decoded.value; - if (compareSemverVersions(manifest.version, "1.5.0") < 0) return null; const os = platform === "darwin" ? "mac" : platform === "win32" ? "windows" : "linux"; const cpu = arch === "x64" ? "x64" : "arm64"; const suffix = platform === "linux" && musl ? "_musl" : ""; diff --git a/apps/server/src/provider/model-manifest.json b/apps/server/src/provider/model-manifest.json index c719c3755acd4..bb2e561e3f3ac 100644 --- a/apps/server/src/provider/model-manifest.json +++ b/apps/server/src/provider/model-manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "updatedAt": "2026-11-19T00:00:00Z", + "updatedAt": "2026-11-19T23:30:00Z", "compatibility": [ { "driver": "codex", @@ -35,6 +35,7 @@ { "driver": "cursor", "t3CodeRange": ">=0.0.42", + "versionPattern": "^(\\d{4}\\.\\d{2}\\.\\d{2})-[a-f0-9]+$", "recommendedRange": ">=2026.05.09", "ranges": [ { "range": ">=2026.05.09", "status": "supported" }, @@ -75,6 +76,7 @@ { "driver": "antigravity", "t3CodeRange": ">=0.0.42 <0.1.10", + "versionPattern": "^(?:agy_acp_server_)?(\\d+\\.\\d+\\.\\d+)(?:-[0-9A-Za-z.-]+)?$", "recommendedRange": "=1.4.5 || =1.4.1", "ranges": [ { "range": "=1.4.5", "status": "supported" }, @@ -86,6 +88,7 @@ { "driver": "antigravity", "t3CodeRange": ">=0.1.10", + "versionPattern": "^(?:agy_acp_server_)?(\\d+\\.\\d+\\.\\d+)(?:-[0-9A-Za-z.-]+)?$", "recommendedRange": ">=1.5.12 <2", "ranges": [ { "range": ">=1.5.0 <2", "status": "supported" }, @@ -110,6 +113,7 @@ { "driver": "muse", "t3CodeRange": ">=0.0.46", + "versionPattern": "^(\\d+\\.\\d+\\.\\d+)-R\\d+(?:\\.\\d+)?$", "recommendedRange": ">=1.4.2", "ranges": [ { "range": ">=1.4.2", "status": "supported" }, diff --git a/apps/server/src/provider/providerCompatibility.test.ts b/apps/server/src/provider/providerCompatibility.test.ts index 2c5be6d220b14..f0bf86feaec98 100644 --- a/apps/server/src/provider/providerCompatibility.test.ts +++ b/apps/server/src/provider/providerCompatibility.test.ts @@ -88,6 +88,7 @@ describe("provider compatibility", () => { const cursorPolicy: ProviderCompatibilityPolicy = { driver: cursor, t3CodeRange: policy.t3CodeRange, + versionPattern: "^(\\d{4}\\.\\d{2}\\.\\d{2})-[a-f0-9]+$", ranges: [ { range: "<2026.05.09", status: "unsupported" }, { range: ">=2026.05.09", status: "supported" }, diff --git a/apps/server/src/provider/providerCompatibility.ts b/apps/server/src/provider/providerCompatibility.ts index d825eb1b24342..7d8bed45c7b1c 100644 --- a/apps/server/src/provider/providerCompatibility.ts +++ b/apps/server/src/provider/providerCompatibility.ts @@ -1,7 +1,9 @@ import { + ProviderSetupError, TrimmedNonEmptyString, ServerProviderCompatibilityStatus, type ProviderDriverKind, + type ProviderInstanceId, type ServerProvider, type ServerProviderCompatibilityAdvisory, } from "@t3tools/contracts"; @@ -22,9 +24,22 @@ const VersionRange = TrimmedNonEmptyString.pipe( ), ), ); +const compilePattern = (pattern: string) => { + try { + return new RegExp(pattern, "u"); + } catch { + return undefined; + } +}; const Policy = Schema.Struct({ driver: TrimmedNonEmptyString, t3CodeRange: VersionRange, + /** Matches a reported version that is not plain `X.Y.Z`; its first group is the version to rate. */ + versionPattern: Schema.optionalKey( + TrimmedNonEmptyString.pipe( + Schema.check(Schema.makeFilter((value) => compilePattern(value) !== undefined)), + ), + ), recommendedRange: Schema.optionalKey(VersionRange), recommendedVersion: Schema.optionalKey(StableVersion), ranges: Schema.Array( @@ -65,16 +80,9 @@ export function resolveProviderCompatibility( ); if (!policy) return undefined; const unprefixed = version?.replace(/^v/, ""); - // Strip Cursor build hashes and Muse revisions; leave other prereleases unknown. Antigravity - // drops its pre-CLI prefix and prerelease suffix, so a custom launcher below 1.5 resolves broken. - const stable = - driver === "cursor" - ? unprefixed?.replace(/^(\d{4}\.\d{2}\.\d{2})-[a-f0-9]+$/, "$1") - : driver === "muse" - ? unprefixed?.replace(/^(\d+\.\d+\.\d+)-R\d+(?:\.\d+)?$/, "$1") - : driver === "antigravity" - ? unprefixed?.replace(/^(?:agy_acp_server_)?(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?$/, "$1") - : unprefixed; + // Without a pattern, build hashes, revisions and prereleases stay unknown. + const pattern = policy.versionPattern ? compilePattern(policy.versionPattern) : undefined; + const stable = (pattern && unprefixed?.match(pattern)?.[1]) || unprefixed; const status = stable && /^\d+\.\d+\.\d+$/.test(stable) ? (policy.ranges.find((entry) => satisfiesSemverRange(stable, entry.range))?.status ?? @@ -99,6 +107,24 @@ export function resolveProviderCompatibility( }; } +/** The one refusal for a runtime the policy rates `broken`; `action` names how this runtime is updated. */ +export function brokenRuntimeError(input: { + readonly instanceId: ProviderInstanceId; + readonly name: string; + readonly version: string; + readonly advisory: ServerProviderCompatibilityAdvisory | undefined; + readonly action?: string; +}): ProviderSetupError | undefined { + if (input.advisory?.status !== "broken") return undefined; + const target = + input.advisory.recommendedVersion ?? input.advisory.recommendedRange ?? "a newer version"; + return new ProviderSetupError({ + instanceId: input.instanceId, + operation: "runtime", + detail: `${input.name} ${input.version} does not work with this T3 Code release. ${input.action ?? `Update ${input.name}`} to ${target}, then retry.`, + }); +} + export function applyProviderCompatibility( snapshot: ServerProvider, policies: ReadonlyArray | undefined, @@ -106,14 +132,12 @@ export function applyProviderCompatibility( ): ServerProvider { const { compatibilityAdvisory: _previous, ...base } = snapshot; if (!snapshot.enabled || !snapshot.installed) return base; - const advisory = - resolveProviderCompatibility(policies, snapshot.driver, snapshot.version) ?? - resolveProviderCompatibility(fallback, snapshot.driver, snapshot.version); + const resolve = (version: string | null) => + resolveProviderCompatibility(policies, snapshot.driver, version) ?? + resolveProviderCompatibility(fallback, snapshot.driver, version); + const advisory = resolve(snapshot.version); const latestVersion = snapshot.versionAdvisory?.latestVersion; - const latestAdvisory = latestVersion - ? (resolveProviderCompatibility(policies, snapshot.driver, latestVersion) ?? - resolveProviderCompatibility(fallback, snapshot.driver, latestVersion)) - : undefined; + const latestAdvisory = latestVersion ? resolve(latestVersion) : undefined; const updateCommand = snapshot.versionAdvisory?.updateCommand; // The maintenance resolver emits this command only for confirmed Homebrew installs. const needsHomebrewRefresh = diff --git a/apps/server/src/provider/providerMaintenanceRunner.ts b/apps/server/src/provider/providerMaintenanceRunner.ts index 9ac62dca70419..014aa67c26df0 100644 --- a/apps/server/src/provider/providerMaintenanceRunner.ts +++ b/apps/server/src/provider/providerMaintenanceRunner.ts @@ -24,7 +24,6 @@ import { ChildProcess, ChildProcessSpawner } from "effect/process"; import * as NodeUtil from "node:util"; import * as ModelManifest from "./ModelManifest.ts"; -import { resolveProviderCompatibility } from "./providerCompatibility.ts"; import * as ProviderInstallationGate from "./ProviderInstallationGate.ts"; import * as ProviderRegistry from "./ProviderRegistry.ts"; import { makeProviderMaintenanceCommandCoordinator } from "./providerMaintenanceCommandCoordinator.ts"; @@ -515,13 +514,11 @@ export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () { latestVersions, ), )); - const advisory = - resolveProviderCompatibility(manifest.compatibility, provider, candidateVersion) ?? - resolveProviderCompatibility( - ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility, - provider, - candidateVersion, - ); + const advisory = ModelManifest.providerCompatibility( + manifest, + provider, + candidateVersion, + ); const command = targetVersion !== undefined ? makeTargetedProviderUpdateAction(fresh, targetVersion) diff --git a/docs/internals/adding-a-provider.md b/docs/internals/adding-a-provider.md index 821269954f8d3..5bf40a5296049 100644 --- a/docs/internals/adding-a-provider.md +++ b/docs/internals/adding-a-provider.md @@ -121,6 +121,8 @@ A provider lives in its own `packages/provider-` package, with adapter driver. Also its position in the [status order](../../apps/server/src/provider/providerStatusCache.ts), a compatibility policy in [`model-manifest.json`](../../apps/server/src/provider/model-manifest.json) (bump `updatedAt`; see [model manifest](./model-manifest.md)), and its default model in contracts. + A `broken` range refuses new sessions for that driver, so declare a minimum there, not as a + constant in the driver. A version that is not plain `X.Y.Z` needs the policy's `versionPattern`. - **Client registration:** the client definition in the web and mobile provider registries, and settings search terms. Clients draw the package icon; do not add a per-driver icon branch. - **Docs:** a `docs/user/providers-.md` guide in the product's voice, a row in the From 498acdd06382b22f04992f53d3bc9c611561c708 Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Thu, 19 Nov 2026 16:08:09 -0800 Subject: [PATCH 2/3] fix(server): the shared version gate re-probes before refusing The gate read the last status probe, so a provider updated since then was refused again with its old version. It now refreshes the snapshot once before refusing, and skips adapters that rate the live version at their handshake (Codex, Antigravity), whose remembered version can be stale. Co-Authored-By: Claude Fable 5.2 --- .../Adapters/AntigravityAdapterV2.ts | 1 + .../Adapters/CodexAdapterV2.ts | 1 + .../ProviderAdapterRegistry.test.ts | 58 +++++++++++-------- .../ProviderAdapterRegistry.ts | 36 +++++++----- packages/provider-acp/src/server/adapter.ts | 3 + .../src/server/ProviderAdapter.ts | 5 ++ 6 files changed, 64 insertions(+), 40 deletions(-) diff --git a/apps/server/src/orchestration-v2/Adapters/AntigravityAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/AntigravityAdapterV2.ts index 7c7c8fd8182aa..e2403604f7105 100644 --- a/apps/server/src/orchestration-v2/Adapters/AntigravityAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/AntigravityAdapterV2.ts @@ -286,6 +286,7 @@ export function makeAntigravityAcpAdapterFlavor( supportsImagePrompts: true, compactViaAdvertisedCommand: true, requiresSignIn: isAntigravitySignInRequiredError, + checksVersionAtHandshake: true, // Antigravity can leave a prompt open without updates; long tools and approvals pause this. promptInactivityTimeout: "15 minutes", reportsPerTurnPromptUsage: true, diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts index 3a1eec6f74a2f..68a87a5f0bed4 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts @@ -1948,6 +1948,7 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* ( return ProviderAdapter.ProviderAdapterV2.of({ instanceId: adapterOptions.instanceId, driver: CODEX_PROVIDER, + checksVersionAtHandshake: adapterOptions.compatibility !== undefined, getCapabilities: Effect.fn("CodexAdapterV2.getCapabilities")(function () { return Effect.succeed(CodexProviderCapabilitiesV2); }), diff --git a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts index e48cb9390e567..4b42df176f67f 100644 --- a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts +++ b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.test.ts @@ -42,6 +42,7 @@ const makeInstance = ( instanceId: ProviderInstanceId, orchestrationAdapter: ProviderAdapter.ProviderAdapterV2["Service"], version: string | null = null, + refreshedVersion = version, ): ProviderInstance => ({ instanceId, driverKind: driver, @@ -53,6 +54,7 @@ const makeInstance = ( enabled: true, snapshot: { getSnapshot: Effect.succeed({ version }), + refresh: Effect.succeed({ version: refreshedVersion }), } as unknown as ProviderInstance["snapshot"], orchestrationAdapter, textGeneration: {} as ProviderInstance["textGeneration"], @@ -87,34 +89,40 @@ it.effect("routes two configured instances of the same driver independently", () }).pipe(Effect.provide(layerTest)), ); -it.effect("refuses a session on a provider version the policy rates broken", () => - Effect.gen(function* () { - const broken = makeInstance(personalId, personalAdapter, "0.100.0"); - const registry = yield* Effect.service(ProviderAdapterRegistry.ProviderAdapterRegistryV2).pipe( - Effect.provide( - layerRegistry.pipe( - Layer.provide( - Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({ - getInstance: () => Effect.succeed(broken), - }), - ), +const openOn = Effect.fn("openOn")(function* (instance: ProviderInstance) { + const registry = yield* Effect.service(ProviderAdapterRegistry.ProviderAdapterRegistryV2).pipe( + Effect.provide( + layerRegistry.pipe( + Layer.provide( + Layer.mock(ProviderInstanceRegistry.ProviderInstanceRegistry)({ + getInstance: () => Effect.succeed(instance), + }), ), ), + ), + ); + return yield* (yield* registry.get(instance.instanceId)) + .openSession({ + threadId: ThreadId.make("gated-thread"), + providerSessionId: ProviderSessionId.make("gated-session"), + modelSelection: { instanceId: instance.instanceId, model: "test-model" }, + runtimePolicy: { runtimeMode: "full-access", interactionMode: "default", cwd: "/workspace" }, + }) + .pipe(Effect.exit); +}); + +it.effect("refuses a session only when a fresh probe still rates the version broken", () => + Effect.gen(function* () { + const opened = { ...personalAdapter, openSession: () => Effect.succeed({} as never) }; + const refused = yield* openOn(makeInstance(personalId, opened, "0.100.0")); + assert.include(JSON.stringify(refused), "0.100.0 does not work with this T3 Code release"); + // Updated since the last probe. + assert.isTrue( + Exit.isSuccess(yield* openOn(makeInstance(personalId, opened, "0.100.0", "0.200.0"))), ); - const error = yield* (yield* registry.get(personalId)) - .openSession({ - threadId: ThreadId.make("broken-thread"), - providerSessionId: ProviderSessionId.make("broken-session"), - modelSelection: { instanceId: personalId, model: "test-model" }, - runtimePolicy: { - runtimeMode: "full-access", - interactionMode: "default", - cwd: "/workspace", - }, - }) - .pipe(Effect.flip); - assert.instanceOf(error, ProviderAdapter.ProviderAdapterOpenSessionError); - assert.include(String(error.cause), "0.100.0 does not work with this T3 Code release"); + // An adapter that rates the handshake version is not judged on the probe. + const handshake = { ...opened, checksVersionAtHandshake: true }; + assert.isTrue(Exit.isSuccess(yield* openOn(makeInstance(personalId, handshake, "0.100.0")))); }), ); diff --git a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts index 610a4288c6fd2..dd0e8f8cb48e2 100644 --- a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts +++ b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts @@ -2,6 +2,7 @@ import { ProviderInstanceId, ProviderSetupError, type OrchestrationV2ProviderCapabilities, + type ServerProvider, } from "@t3tools/contracts"; import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; @@ -78,25 +79,30 @@ export const layerFromProviderInstanceRegistry: Layer.Layer< return new ProviderAdapterRegistryLookupError({ instanceId }); const adapter = instance.orchestrationAdapter; const auth = instance.auth; + const refuseBroken = Effect.fnUntraced(function* (snapshot: ServerProvider) { + return snapshot.version + ? brokenRuntimeError({ + instanceId, + name: snapshot.displayName ?? instance.displayName ?? adapter.driver, + version: snapshot.version, + advisory: ModelManifest.providerCompatibility( + yield* manifest.current, + adapter.driver, + snapshot.version, + ), + }) + : undefined; + }); return Effect.succeed({ ...adapter, openSession: (input) => { const open = Effect.gen(function* () { - // Every provider is refused here on a version the policy rates broken. - const snapshot = yield* instance.snapshot.getSnapshot; - const refused = - snapshot.version && - brokenRuntimeError({ - instanceId, - name: snapshot.displayName ?? instance.displayName ?? adapter.driver, - version: snapshot.version, - advisory: ModelManifest.providerCompatibility( - yield* manifest.current, - adapter.driver, - snapshot.version, - ), - }); - if (refused) return yield* refused; + if (!adapter.checksVersionAtHandshake) { + let refused = yield* refuseBroken(yield* instance.snapshot.getSnapshot); + // The last probe may predate an update, so look again before refusing. + if (refused) refused = yield* refuseBroken(yield* instance.snapshot.refresh); + if (refused) return yield* refused; + } if (!auth) return yield* adapter.openSession(input); const binding = auth.credentialBinding; const related = binding diff --git a/packages/provider-acp/src/server/adapter.ts b/packages/provider-acp/src/server/adapter.ts index 41572dcc0781d..4b456edc4526b 100644 --- a/packages/provider-acp/src/server/adapter.ts +++ b/packages/provider-acp/src/server/adapter.ts @@ -380,6 +380,8 @@ export interface AcpAdapterV2Flavor { readonly promptCapabilities: EffectAcpSchema.AgentCapabilities["promptCapabilities"]; }) => Effect.Effect, EffectAcpErrors.AcpError>; readonly promptFailure?: (cause: unknown) => OrchestrationV2ProviderFailure; + /** The flavor's runtime refuses a version the policy rates broken when it starts. */ + readonly checksVersionAtHandshake?: boolean; /** * Runs before `session/prompt`. The returned check sees a prompt the agent ended * 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* ( return ProviderAdapter.ProviderAdapterV2.of({ instanceId: options.instanceId, driver, + checksVersionAtHandshake: flavor.checksVersionAtHandshake === true, getCapabilities: Effect.fn("AcpAdapter.getCapabilities")(function* () { return yield* readCapabilities; }), diff --git a/packages/provider-core/src/server/ProviderAdapter.ts b/packages/provider-core/src/server/ProviderAdapter.ts index 62fe110dd5245..422722c584e23 100644 --- a/packages/provider-core/src/server/ProviderAdapter.ts +++ b/packages/provider-core/src/server/ProviderAdapter.ts @@ -817,6 +817,11 @@ export class ProviderAdapterV2 extends Context.Service< { readonly instanceId: ProviderInstanceId; readonly driver: ProviderDriverKind; + /** + * Set when `openSession` rates the version the runtime reports at its handshake. The host then + * skips its own check, which only knows the version from the last status probe. + */ + readonly checksVersionAtHandshake?: boolean; readonly getCapabilities: () => Effect.Effect< OrchestrationV2ProviderCapabilities, ProviderAdapterV2Error From dabefe6284c4daa60fa98ae43d2a5dca59a13090 Mon Sep 17 00:00:00 2001 From: Julius Marminge Date: Thu, 19 Nov 2026 16:34:31 -0800 Subject: [PATCH 3/3] fix(server): delegation no longer judges a provider on its cached version The broken-version constraint read the last status probe, so an agent could be told a just-updated provider was incompatible. The session gate re-probes and refuses at open instead. Co-Authored-By: Claude Fable 5.2 --- apps/server/src/mcp/OrchestratorMcpService.ts | 5 ----- apps/server/src/provider/antigravityCliRelease.test.ts | 1 - 2 files changed, 6 deletions(-) diff --git a/apps/server/src/mcp/OrchestratorMcpService.ts b/apps/server/src/mcp/OrchestratorMcpService.ts index 3b0ae28dd1285..bd57bebb3fc35 100644 --- a/apps/server/src/mcp/OrchestratorMcpService.ts +++ b/apps/server/src/mcp/OrchestratorMcpService.ts @@ -473,11 +473,6 @@ function providerConstraints( if (provider.auth.status === "unauthenticated") { constraints.push("Provider is not authenticated."); } - if (provider.compatibilityAdvisory?.status === "broken") { - constraints.push( - provider.compatibilityAdvisory.message ?? "Provider version does not work with T3 Code.", - ); - } return constraints; } diff --git a/apps/server/src/provider/antigravityCliRelease.test.ts b/apps/server/src/provider/antigravityCliRelease.test.ts index 2e1e0010c22c5..f268a7d9e9a4b 100644 --- a/apps/server/src/provider/antigravityCliRelease.test.ts +++ b/apps/server/src/provider/antigravityCliRelease.test.ts @@ -38,7 +38,6 @@ describe("Antigravity CLI release manifests", () => { it.each([ { sha512: "invalid" }, - { version: "1.4.5" }, { url: manifest.url.replace("https:", "http:") }, { url: manifest.url.replace("storage.googleapis.com", "storage.googleapis.com.evil.test") }, { url: manifest.url.replace("antigravity-public", "another-bucket") },