Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

provider update advisories (#2312)

legs9b604bcae1e2
diff --git a/apps/desktop/src/clientPersistence.test.ts b/apps/desktop/src/clientPersistence.test.ts
index d4c4768d2..f0c7c30e2 100644
--- a/apps/desktop/src/clientPersistence.test.ts
+++ b/apps/desktop/src/clientPersistence.test.ts
@@ -52,6 +52,7 @@ const clientSettings: ClientSettings = {
autoOpenPlanSidebar: false,
confirmThreadArchive: true,
confirmThreadDelete: false,
+ dismissedProviderUpdateNotificationKeys: [],
diffIgnoreWhitespace: true,
diffWordWrap: true,
favorites: [],
diff --git a/apps/server/src/provider/Drivers/ClaudeDriver.ts b/apps/server/src/provider/Drivers/ClaudeDriver.ts
index 311f49586..eb287ad7e 100644
--- a/apps/server/src/provider/Drivers/ClaudeDriver.ts
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -14,6 +14,7 @@
*/
import { ClaudeSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
import { Cache, Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import { makeClaudeTextGeneration } from "../../textGeneration/ClaudeTextGeneration.ts";
@@ -34,15 +35,43 @@ import {
} from "../ProviderDriver.ts";
import type { ServerProviderDraft } from "../providerSnapshot.ts";
import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import {
+ enrichProviderSnapshotWithVersionAdvisory,
+ makePackageManagedProviderMaintenanceResolver,
+ normalizeCommandPath,
+ resolveProviderMaintenanceCapabilitiesEffect,
+} from "../providerMaintenance.ts";
import { makeClaudeCapabilitiesCacheKey, makeClaudeContinuationGroupKey } from "./ClaudeHome.ts";
const DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
const CAPABILITIES_PROBE_TTL = Duration.minutes(5);
+function isClaudeNativeCommandPath(commandPath: string): boolean {
+ const normalized = normalizeCommandPath(commandPath);
+ return (
+ normalized.endsWith("/.local/bin/claude") ||
+ normalized.endsWith("/.local/bin/claude.exe") ||
+ normalized.includes("/.local/share/claude/")
+ );
+}
+
+const UPDATE = makePackageManagedProviderMaintenanceResolver({
+ provider: DRIVER_KIND,
+ npmPackageName: "@anthropic-ai/claude-code",
+ homebrewFormula: "claude-code",
+ nativeUpdate: {
+ executable: "claude",
+ args: ["update"],
+ lockKey: "claude-native",
+ isCommandPath: isClaudeNativeCommandPath,
+ },
+});
+
export type ClaudeDriverEnv =
| ChildProcessSpawner.ChildProcessSpawner
| FileSystem.FileSystem
+ | HttpClient.HttpClient
| Path.Path
| ProviderEventLoggers
| ServerConfig;
@@ -75,6 +104,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
Effect.gen(function* () {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const path = yield* Path.Path;
+ const httpClient = yield* HttpClient.HttpClient;
const eventLoggers = yield* ProviderEventLoggers;
const processEnv = mergeProviderInstanceEnvironment(environment);
const fallbackContinuationIdentity = defaultProviderContinuationIdentity({
@@ -82,6 +112,10 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
instanceId,
});
const effectiveConfig = { ...config, enabled } satisfies ClaudeSettings;
+ const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+ binaryPath: effectiveConfig.binaryPath,
+ env: processEnv,
+ });
const continuationGroupKey = yield* makeClaudeContinuationGroupKey(effectiveConfig);
const stampIdentity = withInstanceIdentity({
instanceId,
@@ -121,11 +155,17 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
);
const snapshot = yield* makeManagedServerProvider<ClaudeSettings>({
+ maintenanceCapabilities,
getSettings: Effect.succeed(effectiveConfig),
streamSettings: Stream.never,
haveSettingsChanged: () => false,
initialSnapshot: (settings) => stampIdentity(makePendingClaudeProvider(settings)),
checkProvider,
+ enrichSnapshot: ({ snapshot, publishSnapshot }) =>
+ enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities).pipe(
+ Effect.provideService(HttpClient.HttpClient, httpClient),
+ Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
+ ),
refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
}).pipe(
Effect.mapError(
diff --git a/apps/server/src/provider/Drivers/CodexDriver.ts b/apps/server/src/provider/Drivers/CodexDriver.ts
index 26fffd5e2..cc849acc3 100644
--- a/apps/server/src/provider/Drivers/CodexDriver.ts
+++ b/apps/server/src/provider/Drivers/CodexDriver.ts
@@ -23,6 +23,7 @@
*/
import { CodexSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
import { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import { makeCodexTextGeneration } from "../../textGeneration/CodexTextGeneration.ts";
@@ -35,6 +36,11 @@ import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
import type { ProviderDriver, ProviderInstance } from "../ProviderDriver.ts";
import type { ServerProviderDraft } from "../providerSnapshot.ts";
import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import {
+ enrichProviderSnapshotWithVersionAdvisory,
+ makePackageManagedProviderMaintenanceResolver,
+ resolveProviderMaintenanceCapabilitiesEffect,
+} from "../providerMaintenance.ts";
import {
codexContinuationIdentity,
materializeCodexShadowHome,
@@ -43,6 +49,12 @@ import {
const DRIVER_KIND = ProviderDriverKind.make("codex");
const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+const UPDATE = makePackageManagedProviderMaintenanceResolver({
+ provider: DRIVER_KIND,
+ npmPackageName: "@openai/codex",
+ homebrewFormula: "codex",
+ nativeUpdate: null,
+});
/**
* Services the driver needs to materialize an instance. Surfaced as the
@@ -52,6 +64,7 @@ const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
export type CodexDriverEnv =
| ChildProcessSpawner.ChildProcessSpawner
| FileSystem.FileSystem
+ | HttpClient.HttpClient
| Path.Path
| ProviderEventLoggers
| ServerConfig;
@@ -89,6 +102,7 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
Effect.gen(function* () {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+ const httpClient = yield* HttpClient.HttpClient;
const eventLoggers = yield* ProviderEventLoggers;
const processEnv = mergeProviderInstanceEnvironment(environment);
const homeLayout = yield* resolveCodexHomeLayout(config);
@@ -115,6 +129,10 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
enabled,
homePath: homeLayout.effectiveHomePath ?? "",
} satisfies CodexSettings;
+ const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+ binaryPath: effectiveConfig.binaryPath,
+ env: processEnv,
+ });
// `makeCodexAdapter` and `makeCodexTextGeneration` have `never` error
// channels at construction time — their failure modes are all on the
@@ -138,11 +156,17 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
);
const snapshot = yield* makeManagedServerProvider<CodexSettings>({
+ maintenanceCapabilities,
getSettings: Effect.succeed(effectiveConfig),
streamSettings: Stream.never,
haveSettingsChanged: () => false,
initialSnapshot: (settings) => stampIdentity(makePendingCodexProvider(settings)),
checkProvider,
+ enrichSnapshot: ({ snapshot, publishSnapshot }) =>
+ enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities).pipe(
+ Effect.provideService(HttpClient.HttpClient, httpClient),
+ Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
+ ),
refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
}).pipe(
Effect.mapError(
diff --git a/apps/server/src/provider/Drivers/CursorDriver.ts b/apps/server/src/provider/Drivers/CursorDriver.ts
index cd058800f..72a6bae1f 100644
--- a/apps/server/src/provider/Drivers/CursorDriver.ts
+++ b/apps/server/src/provider/Drivers/CursorDriver.ts
@@ -14,6 +14,7 @@
*/
import { CursorSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
import { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import { ServerConfig } from "../../config.ts";
@@ -34,13 +35,28 @@ import {
} from "../ProviderDriver.ts";
import type { ServerProviderDraft } from "../providerSnapshot.ts";
import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import {
+ makeProviderMaintenanceCapabilities,
+ makeStaticProviderMaintenanceResolver,
+ resolveProviderMaintenanceCapabilitiesEffect,
+} from "../providerMaintenance.ts";
const DRIVER_KIND = ProviderDriverKind.make("cursor");
const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+const UPDATE = makeStaticProviderMaintenanceResolver(
+ makeProviderMaintenanceCapabilities({
+ provider: DRIVER_KIND,
+ packageName: null,
+ updateExecutable: "agent",
+ updateArgs: ["update"],
+ updateLockKey: "cursor-agent",
+ }),
+);
export type CursorDriverEnv =
| ChildProcessSpawner.ChildProcessSpawner
| FileSystem.FileSystem
+ | HttpClient.HttpClient
| Path.Path
| ProviderEventLoggers
| ServerConfig;
@@ -74,6 +90,7 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const fileSystem = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
+ const httpClient = yield* HttpClient.HttpClient;
const eventLoggers = yield* ProviderEventLoggers;
const processEnv = mergeProviderInstanceEnvironment(environment);
const continuationIdentity = defaultProviderContinuationIdentity({
@@ -87,6 +104,10 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
continuationGroupKey: continuationIdentity.continuationKey,
});
const effectiveConfig = { ...config, enabled } satisfies CursorSettings;
+ const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+ binaryPath: effectiveConfig.binaryPath,
+ env: processEnv,
+ });
const adapter = yield* makeCursorAdapter(effectiveConfig, {
environment: processEnv,
@@ -103,6 +124,7 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
);
const snapshot = yield* makeManagedServerProvider<CursorSettings>({
+ maintenanceCapabilities,
getSettings: Effect.succeed(effectiveConfig),
streamSettings: Stream.never,
haveSettingsChanged: () => false,
@@ -117,8 +139,10 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
settings,
environment: processEnv,
snapshot: currentSnapshot,
+ maintenanceCapabilities,
publishSnapshot,
stampIdentity,
+ httpClient,
}).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner)),
refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
}).pipe(
diff --git a/apps/server/src/provider/Drivers/OpenCodeDriver.ts b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
index 27f98a983..0452a3a73 100644
--- a/apps/server/src/provider/Drivers/OpenCodeDriver.ts
+++ b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
@@ -14,6 +14,7 @@
*/
import { OpenCodeSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
import { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { HttpClient } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import { makeOpenCodeTextGeneration } from "../../textGeneration/OpenCodeTextGeneration.ts";
@@ -34,13 +35,40 @@ import {
} from "../ProviderDriver.ts";
import type { ServerProviderDraft } from "../providerSnapshot.ts";
import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import {
+ enrichProviderSnapshotWithVersionAdvisory,
+ makePackageManagedProviderMaintenanceResolver,
+ normalizeCommandPath,
+ resolveProviderMaintenanceCapabilitiesEffect,
+} from "../providerMaintenance.ts";
const DRIVER_KIND = ProviderDriverKind.make("opencode");
const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+function isOpenCodeNativeCommandPath(commandPath: string): boolean {
+ const normalized = normalizeCommandPath(commandPath);
+ return (
+ normalized.endsWith("/.opencode/bin/opencode") ||
+ normalized.endsWith("/.opencode/bin/opencode.exe")
+ );
+}
+
+const UPDATE = makePackageManagedProviderMaintenanceResolver({
+ provider: DRIVER_KIND,
+ npmPackageName: "opencode-ai",
+ homebrewFormula: "anomalyco/tap/opencode",
+ nativeUpdate: {
+ executable: "opencode",
+ args: ["upgrade"],
+ lockKey: "opencode-native",
+ isCommandPath: isOpenCodeNativeCommandPath,
+ },
+});
+
export type OpenCodeDriverEnv =
| ChildProcessSpawner.ChildProcessSpawner
| FileSystem.FileSystem
+ | HttpClient.HttpClient
| OpenCodeRuntime
| Path.Path
| ProviderEventLoggers
@@ -74,6 +102,7 @@ export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv>
Effect.gen(function* () {
const openCodeRuntime = yield* OpenCodeRuntime;
const serverConfig = yield* ServerConfig;
+ const httpClient = yield* HttpClient.HttpClient;
const eventLoggers = yield* ProviderEventLoggers;
const processEnv = mergeProviderInstanceEnvironment(environment);
const continuationIdentity = defaultProviderContinuationIdentity({
@@ -87,6 +116,10 @@ export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv>
continuationGroupKey: continuationIdentity.continuationKey,
});
const effectiveConfig = { ...config, enabled } satisfies OpenCodeSettings;
+ const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+ binaryPath: effectiveConfig.binaryPath,
+ env: processEnv,
+ });
const adapter = yield* makeOpenCodeAdapter(effectiveConfig, {
instanceId,
@@ -102,11 +135,17 @@ export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv>
).pipe(Effect.map(stampIdentity), Effect.provideService(OpenCodeRuntime, openCodeRuntime));
const snapshot = yield* makeManagedServerProvider<OpenCodeSettings>({
+ maintenanceCapabilities,
getSettings: Effect.succeed(effectiveConfig),
streamSettings: Stream.never,
haveSettingsChanged: () => false,
initialSnapshot: (settings) => stampIdentity(makePendingOpenCodeProvider(settings)),
checkProvider,
+ enrichSnapshot: ({ snapshot, publishSnapshot }) =>
+ enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities).pipe(
+ Effect.provideService(HttpClient.HttpClient, httpClient),
+ Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
+ ),
refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
}).pipe(
Effect.mapError(
diff --git a/apps/server/src/provider/Layers/CodexProvider.ts b/apps/server/src/provider/Layers/CodexProvider.ts
index 0917d842a..618103883 100644
--- a/apps/server/src/provider/Layers/CodexProvider.ts
+++ b/apps/server/src/provider/Layers/CodexProvider.ts
@@ -15,7 +15,6 @@ import type {
import { ServerSettingsError } from "@t3tools/contracts";
import { createModelCapabilities } from "@t3tools/shared/model";
-
import { buildServerProvider, type ServerProviderDraft } from "../providerSnapshot.ts";
import { expandHomePath } from "../../pathExpansion.ts";
import { scopedSafeTeardown } from "./scopedSafeTeardown.ts";
diff --git a/apps/server/src/provider/Layers/CursorProvider.ts b/apps/server/src/provider/Layers/CursorProvider.ts
index ad52f63fb..4a8b1cdcf 100644
--- a/apps/server/src/provider/Layers/CursorProvider.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.ts
@@ -12,6 +12,7 @@ import type {
import { ProviderDriverKind } from "@t3tools/contracts";
import type * as EffectAcpSchema from "effect-acp/schema";
import { Cause, Effect, Exit, FileSystem, Layer, Option, Path, Result } from "effect";
+import { HttpClient } from "effect/unstable/http";
import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
import {
createModelCapabilities,
@@ -29,6 +30,10 @@ import {
type CommandResult,
type ServerProviderDraft,
} from "../providerSnapshot.ts";
+import {
+ enrichProviderSnapshotWithVersionAdvisory,
+ type ProviderMaintenanceCapabilities,
+} from "../providerMaintenance.ts";
import { AcpSessionRuntime } from "../acp/AcpSessionRuntime.ts";
const PROVIDER = ProviderDriverKind.make("cursor");
@@ -1216,42 +1221,67 @@ export const enrichCursorSnapshot = (input: {
readonly settings: CursorSettings;
readonly environment?: NodeJS.ProcessEnv;
readonly snapshot: ServerProvider;
+ readonly maintenanceCapabilities: ProviderMaintenanceCapabilities;
readonly publishSnapshot: (snapshot: ServerProvider) => Effect.Effect<void>;
readonly stampIdentity?: (snapshot: ServerProvider) => ServerProvider;
+ readonly httpClient: HttpClient.HttpClient;
}): Effect.Effect<void, never, ChildProcessSpawner.ChildProcessSpawner> => {
const { settings, snapshot, publishSnapshot } = input;
const stampIdentity = input.stampIdentity ?? ((value) => value);
- if (
- !settings.enabled ||
- snapshot.auth.status === "unauthenticated" ||
- !hasUncapturedCursorModels(snapshot)
- ) {
- return Effect.void;
- }
+ const enrichVersionAdvisory = enrichProviderSnapshotWithVersionAdvisory(
+ snapshot,
+ input.maintenanceCapabilities,
+ ).pipe(
+ Effect.provideService(HttpClient.HttpClient, input.httpClient),
+ Effect.flatMap((enrichedSnapshot) =>
+ publishSnapshot(stampIdentity(enrichedSnapshot)).pipe(Effect.as(enrichedSnapshot)),
+ ),
+ Effect.catchCause((cause) =>
+ Effect.logWarning("Cursor version advisory enrichment failed", {
+ cause: Cause.pretty(cause),
+ }).pipe(Effect.as(snapshot)),
+ ),
+ );
- return discoverCursorModelCapabilitiesViaAcp(settings, snapshot.models, input.environment).pipe(
- Effect.flatMap((discoveredModels) => {
- if (discoveredModels.length === 0) {
+ return enrichVersionAdvisory.pipe(
+ Effect.flatMap((baseSnapshot) => {
+ if (
+ !settings.enabled ||
+ baseSnapshot.auth.status === "unauthenticated" ||
+ !hasUncapturedCursorModels(baseSnapshot)
+ ) {
return Effect.void;
}
- return publishSnapshot(
- stampIdentity({
- ...snapshot,
- models: providerModelsFromSettings(
- discoveredModels,
- PROVIDER,
- settings.customModels,
- EMPTY_CAPABILITIES,
- ),
+
+ return discoverCursorModelCapabilitiesViaAcp(
+ settings,
+ baseSnapshot.models,
+ input.environment,
+ ).pipe(
+ Effect.flatMap((discoveredModels) => {
+ if (discoveredModels.length === 0) {
+ return Effect.void;
+ }
+ return publishSnapshot(
+ stampIdentity({
+ ...baseSnapshot,
+ models: providerModelsFromSettings(
+ discoveredModels,
+ PROVIDER,
+ settings.customModels,
+ EMPTY_CAPABILITIES,
+ ),
+ }),
+ );
}),
+ Effect.catchCause((cause) =>
+ Effect.logWarning("Cursor ACP background capability enrichment failed", {
+ models: baseSnapshot.models.map((model) => model.slug),
+ cause: Cause.pretty(cause),
+ }).pipe(Effect.asVoid),
+ ),
);
}),
- Effect.catchCause((cause) =>
- Effect.logWarning("Cursor ACP background capability enrichment failed", {
- models: snapshot.models.map((model) => model.slug),
- cause: Cause.pretty(cause),
- }).pipe(Effect.asVoid),
- ),
);
};
diff --git a/apps/server/src/provider/Layers/OpenCodeProvider.ts b/apps/server/src/provider/Layers/OpenCodeProvider.ts
index c7487d7d5..6431282d6 100644
--- a/apps/server/src/provider/Layers/OpenCodeProvider.ts
+++ b/apps/server/src/provider/Layers/OpenCodeProvider.ts
@@ -7,7 +7,6 @@ import {
import { Cause, Data, Effect } from "effect";
import { createModelCapabilities } from "@t3tools/shared/model";
-
import {
buildServerProvider,
nonEmptyTrimmed,
diff --git a/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts b/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
index eeba158ab..a37eeae6b 100644
--- a/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
@@ -14,6 +14,7 @@ import type { OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
import { ProviderAdapterRegistry } from "../Services/ProviderAdapterRegistry.ts";
import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
import type { ProviderInstance } from "../ProviderDriver.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
import type { TextGenerationShape } from "../../textGeneration/TextGeneration.ts";
import { ProviderAdapterRegistryLive } from "./ProviderAdapterRegistry.ts";
import * as NodeServices from "@effect/platform-node/NodeServices";
@@ -111,6 +112,10 @@ const makeFakeInstance = (
displayName: undefined,
enabled: true,
snapshot: {
+ maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+ provider: driverKind,
+ packageName: null,
+ }),
getSnapshot: Effect.succeed({} as unknown as ServerProvider),
refresh: Effect.succeed({} as unknown as ServerProvider),
streamChanges: Stream.empty,
diff --git a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
index 2246a2ae4..0eeef1fe9 100644
--- a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
@@ -34,6 +34,7 @@ import {
ProviderInstanceId,
} from "@t3tools/contracts";
import { Effect, Layer } from "effect";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
import { ServerConfig } from "../../config.ts";
import { ClaudeDriver } from "../Drivers/ClaudeDriver.ts";
@@ -44,6 +45,13 @@ import { OpenCodeRuntimeLive } from "../opencodeRuntime.ts";
import { NoOpProviderEventLoggers, ProviderEventLoggers } from "./ProviderEventLoggers.ts";
import { makeProviderInstanceRegistry } from "./ProviderInstanceRegistryLive.ts";
+const TestHttpClientLive = Layer.succeed(
+ HttpClient.HttpClient,
+ HttpClient.make((request) =>
+ Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ version: "0.0.0" }))),
+ ),
+);
+
const makeCodexConfig = (overrides: Partial<CodexSettings>): CodexSettings => ({
enabled: false,
binaryPath: "codex",
@@ -89,6 +97,7 @@ describe("ProviderInstanceRegistryLive — multi-instance codex slice", () => {
prefix: "provider-instance-registry-test",
}).pipe(
Layer.provideMerge(NodeServices.layer),
+ Layer.provideMerge(TestHttpClientLive),
Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
);
@@ -225,6 +234,7 @@ describe("ProviderInstanceRegistryLive — all drivers slice", () => {
prefix: "provider-instance-registry-all-drivers-test",
}).pipe(
Layer.provideMerge(infraLayer),
+ Layer.provideMerge(TestHttpClientLive),
Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
);
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
index 75f9c4293..b599a9d1f 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
@@ -14,6 +14,7 @@ import {
type ServerSettings as ContractServerSettings,
} from "@t3tools/contracts";
import * as PlatformError from "effect/PlatformError";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
import { ChildProcessSpawner } from "effect/unstable/process";
import { deepMerge } from "@t3tools/shared/Struct";
import { createModelCapabilities } from "@t3tools/shared/model";
@@ -26,13 +27,17 @@ import { ProviderInstanceRegistryHydrationLive } from "./ProviderInstanceRegistr
import {
haveProvidersChanged,
mergeProviderSnapshot,
+ mergeProviderSnapshots,
ProviderRegistryLive,
+ selectProvidersByKind,
} from "./ProviderRegistry.ts";
import { ServerConfig } from "../../config.ts";
import { ServerSettingsService, type ServerSettingsShape } from "../../serverSettings.ts";
+import { readProviderStatusCache, resolveProviderStatusCachePath } from "../providerStatusCache.ts";
import type { ProviderInstance } from "../ProviderDriver.ts";
import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
import { ProviderRegistry } from "../Services/ProviderRegistry.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
const defaultClaudeSettings: ClaudeSettings = Schema.decodeSync(ClaudeSettings)({});
const defaultCodexSettings: CodexSettings = Schema.decodeSync(CodexSettings)({});
@@ -46,6 +51,13 @@ process.env.T3CODE_CURSOR_ENABLED = "1";
const encoder = new TextEncoder();
+const TestHttpClientLive = Layer.succeed(
+ HttpClient.HttpClient,
+ HttpClient.make((request) =>
+ Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ version: "0.0.0" }))),
+ ),
+);
+
function selectDescriptor(
id: string,
label: string,
@@ -246,7 +258,7 @@ function makeMutableServerSettingsService(
});
}
-it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
+it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest(), TestHttpClientLive))(
"ProviderRegistry",
(it) => {
describe("checkCodexProviderStatus", () => {
@@ -500,6 +512,182 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
]);
});
+ it("persists merged provider snapshots for the providers that were refreshed", () => {
+ const previousProviders = [
+ {
+ instanceId: ProviderInstanceId.make("cursor"),
+ driver: ProviderDriverKind.make("cursor"),
+ status: "ready",
+ enabled: true,
+ installed: true,
+ auth: { status: "authenticated" },
+ checkedAt: "2026-04-14T00:00:00.000Z",
+ version: "2026.04.09-f2b0fcd",
+ models: [
+ {
+ slug: "claude-opus-4-6",
+ name: "Opus 4.6",
+ isCustom: false,
+ capabilities: createModelCapabilities({
+ optionDescriptors: [
+ selectDescriptor("reasoning", "Reasoning", [
+ { id: "high", label: "High", isDefault: true },
+ ]),
+ booleanDescriptor("fastMode", "Fast Mode"),
+ booleanDescriptor("thinking", "Thinking"),
+ ],
+ }),
+ },
+ ],
+ slashCommands: [],
+ skills: [],
+ },
+ {
+ instanceId: ProviderInstanceId.make("codex"),
+ driver: ProviderDriverKind.make("codex"),
+ status: "ready",
+ enabled: true,
+ installed: true,
+ auth: { status: "authenticated" },
+ checkedAt: "2026-04-14T00:00:00.000Z",
+ version: "1.0.0",
+ models: [],
+ slashCommands: [],
+ skills: [],
+ },
+ ] as const satisfies ReadonlyArray<ServerProvider>;
+ const refreshedCursor = {
+ ...previousProviders[0],
+ checkedAt: "2026-04-14T00:01:00.000Z",
+ models: [],
+ } satisfies ServerProvider;
+
+ const mergedProviders = mergeProviderSnapshots(previousProviders, [refreshedCursor]);
+ const persistedProviders = selectProvidersByKind(
+ mergedProviders,
+ new Set([ProviderDriverKind.make("cursor")]),
+ );
+
+ assert.deepStrictEqual(persistedProviders, [
+ {
+ ...refreshedCursor,
+ models: [...previousProviders[0].models],
+ },
+ ]);
+ });
+
+ it.effect("persists the merged snapshot when a live update has empty models", () =>
+ Effect.gen(function* () {
+ const cursorDriver = ProviderDriverKind.make("cursor");
+ const cursorInstanceId = ProviderInstanceId.make("cursor");
+ const initialProvider = {
+ instanceId: cursorInstanceId,
+ driver: cursorDriver,
+ status: "ready",
+ enabled: true,
+ installed: true,
+ auth: { status: "authenticated" },
+ checkedAt: "2026-04-14T00:00:00.000Z",
+ version: "2026.04.09-f2b0fcd",
+ models: [
+ {
+ slug: "claude-opus-4-6",
+ name: "Opus 4.6",
+ isCustom: false,
+ capabilities: createModelCapabilities({
+ optionDescriptors: [
+ selectDescriptor("reasoning", "Reasoning", [
+ { id: "high", label: "High", isDefault: true },
+ ]),
+ ],
+ }),
+ },
+ ],
+ slashCommands: [],
+ skills: [],
+ } as const satisfies ServerProvider;
+ const refreshedProvider = {
+ ...initialProvider,
+ checkedAt: "2026-04-14T00:01:00.000Z",
+ models: [],
+ } satisfies ServerProvider;
+ const changes = yield* PubSub.unbounded<ServerProvider>();
+ const instance = {
+ instanceId: cursorInstanceId,
+ driverKind: cursorDriver,
+ continuationIdentity: {
+ driverKind: cursorDriver,
+ continuationKey: "cursor:instance:cursor",
+ },
+ displayName: undefined,
+ enabled: true,
+ snapshot: {
+ maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+ provider: cursorDriver,
+ packageName: null,
+ }),
+ getSnapshot: Effect.succeed(initialProvider),
+ refresh: Effect.succeed(refreshedProvider),
+ streamChanges: Stream.fromPubSub(changes),
+ },
+ adapter: {} as ProviderInstance["adapter"],
+ textGeneration: {} as ProviderInstance["textGeneration"],
+ } satisfies ProviderInstance;
+ const instanceRegistryLayer = Layer.succeed(ProviderInstanceRegistry, {
+ getInstance: (instanceId) =>
+ Effect.succeed(instanceId === cursorInstanceId ? instance : undefined),
+ listInstances: Effect.succeed([instance]),
+ listUnavailable: Effect.succeed([]),
+ streamChanges: Stream.empty,
+ subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) =>
+ PubSub.subscribe(pubsub),
+ ),
+ });
+ const scope = yield* Scope.make();
+ yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
+ const runtimeServices = yield* Layer.build(
+ ProviderRegistryLive.pipe(
+ Layer.provideMerge(instanceRegistryLayer),
+ Layer.provideMerge(
+ ServerConfig.layerTest(process.cwd(), {
+ prefix: "t3-provider-registry-merged-persist-",
+ }),
+ ),
+ Layer.provideMerge(NodeServices.layer),
+ ),
+ ).pipe(Scope.provide(scope));
+
+ yield* Effect.gen(function* () {
+ const registry = yield* ProviderRegistry;
+ const config = yield* ServerConfig;
+ const filePath = yield* resolveProviderStatusCachePath({
+ cacheDir: config.providerStatusCacheDir,
+ instanceId: cursorInstanceId,
+ });
+
+ assert.deepStrictEqual((yield* registry.getProviders)[0]?.models, [
+ ...initialProvider.models,
+ ]);
+ yield* PubSub.publish(changes, refreshedProvider);
+
+ let cachedProvider = yield* readProviderStatusCache(filePath);
+ for (
+ let attempt = 0;
+ attempt < 50 && cachedProvider?.checkedAt !== refreshedProvider.checkedAt;
+ attempt += 1
+ ) {
+ yield* Effect.sleep("10 millis");
+ cachedProvider = yield* readProviderStatusCache(filePath);
+ }
+
+ assert.deepStrictEqual(cachedProvider, {
+ ...refreshedProvider,
+ models: [...initialProvider.models],
+ });
+ }).pipe(Effect.provide(runtimeServices));
+ }),
+ );
+
it.effect("returns the cached provider list when a manual refresh fails", () =>
Effect.gen(function* () {
const codexDriver = ProviderDriverKind.make("codex");
@@ -527,6 +715,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
displayName: undefined,
enabled: true,
snapshot: {
+ maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+ provider: codexDriver,
+ packageName: null,
+ }),
getSnapshot: Effect.succeed(cachedProvider),
refresh: Effect.die(new Error("simulated refresh failure")),
streamChanges: Stream.empty,
@@ -612,6 +804,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
displayName: undefined,
enabled: true,
snapshot: {
+ maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+ provider: provider.driver,
+ packageName: null,
+ }),
getSnapshot: Effect.succeed(provider),
refresh: Effect.succeed(provider),
streamChanges: Stream.empty,
@@ -748,6 +944,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
prefix: "t3-provider-registry-",
}),
),
+ Layer.provideMerge(TestHttpClientLive),
Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
Layer.provideMerge(OpenCodeRuntimeLive),
// NO spawner mock — `ChildProcessSpawner` is supplied by the
@@ -832,6 +1029,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
prefix: "t3-provider-registry-",
}),
),
+ Layer.provideMerge(TestHttpClientLive),
Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
Layer.provideMerge(OpenCodeRuntimeLive),
// `it.live` does not inherit layers from the outer `it.layer`
@@ -936,6 +1134,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
prefix: "t3-provider-registry-",
}),
),
+ Layer.provideMerge(TestHttpClientLive),
Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
Layer.provideMerge(OpenCodeRuntimeLive),
Layer.provideMerge(NodeServices.layer),
@@ -986,6 +1185,7 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
prefix: "t3-provider-registry-",
}),
),
+ Layer.provideMerge(TestHttpClientLive),
Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
Layer.provideMerge(OpenCodeRuntimeLive),
Layer.provideMerge(
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.ts b/apps/server/src/provider/Layers/ProviderRegistry.ts
index 4f586d881..9018b6624 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.ts
@@ -27,6 +27,7 @@ import {
ProviderDriverKind,
type ProviderInstanceId,
type ServerProvider,
+ type ServerProviderUpdateState,
} from "@t3tools/contracts";
import { Cause, Effect, Equal, FileSystem, Layer, Path, PubSub, Ref, Stream } from "effect";
import * as Semaphore from "effect/Semaphore";
@@ -43,6 +44,7 @@ import {
writeProviderStatusCache,
} from "../providerStatusCache.ts";
import type { ProviderInstance } from "../ProviderDriver.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
import type { ProviderSnapshotSource } from "../builtInProviderCatalog.ts";
const loadProviders = (
@@ -59,6 +61,12 @@ const loadProviders = (
},
);
+const makeManualProviderMaintenanceCapabilities = (provider: ProviderDriverKind) =>
+ makeManualOnlyProviderMaintenanceCapabilities({
+ provider,
+ packageName: null,
+ });
+
const hasModelCapabilities = (model: ServerProvider["models"][number]): boolean =>
(model.capabilities?.optionDescriptors?.length ?? 0) > 0;
@@ -96,6 +104,30 @@ export const mergeProviderSnapshot = (
models: mergeProviderModels(previousProvider.models, nextProvider.models),
};
+export const mergeProviderSnapshots = (
+ previousProviders: ReadonlyArray<ServerProvider>,
+ nextProviders: ReadonlyArray<ServerProvider>,
+): ReadonlyArray<ServerProvider> => {
+ const mergedProviders = new Map(
+ previousProviders.map((provider) => [snapshotInstanceKey(provider), provider] as const),
+ );
+
+ for (const provider of nextProviders) {
+ mergedProviders.set(
+ snapshotInstanceKey(provider),
+ mergeProviderSnapshot(mergedProviders.get(snapshotInstanceKey(provider)), provider),
+ );
+ }
+
+ return orderProviderSnapshots([...mergedProviders.values()]);
+};
+
+export const selectProvidersByKind = (
+ providers: ReadonlyArray<ServerProvider>,
+ providerKinds: ReadonlySet<ProviderDriverKind>,
+): ReadonlyArray<ServerProvider> =>
+ providers.filter((provider) => providerKinds.has(provider.driver));
+
export const haveProvidersChanged = (
previousProviders: ReadonlyArray<ServerProvider>,
nextProviders: ReadonlyArray<ServerProvider>,
@@ -227,6 +259,9 @@ export const ProviderRegistryLive = Layer.effect(
),
);
const providersRef = yield* Ref.make<ReadonlyArray<ServerProvider>>(cachedProviders);
+ const maintenanceActionStatesRef = yield* Ref.make<
+ ReadonlyMap<ProviderInstanceId, { readonly update?: ServerProviderUpdateState | undefined }>
+ >(new Map());
// Live-source registry — the dynamic counterpart to the boot-time
// `bootSources`. Keyed by `instanceId`; the stored `ProviderInstance`
@@ -264,6 +299,21 @@ export const ProviderRegistryLive = Layer.effect(
);
});
+ const applyProviderUpdateState = Effect.fn("applyProviderUpdateState")(function* (
+ provider: ServerProvider,
+ ) {
+ const maintenanceActionStates = yield* Ref.get(maintenanceActionStatesRef);
+ const updateState = maintenanceActionStates.get(provider.instanceId)?.update;
+ if (!updateState) {
+ const { updateState: _updateState, ...providerWithoutUpdateState } = provider;
+ return providerWithoutUpdateState;
+ }
+ return {
+ ...provider,
+ updateState,
+ };
+ });
+
const upsertProviders = Effect.fn("upsertProviders")(function* (
nextProviders: ReadonlyArray<ServerProvider>,
options?: {
@@ -272,15 +322,24 @@ export const ProviderRegistryLive = Layer.effect(
readonly replace?: boolean;
},
) {
- const [previousProviders, providers] = yield* Ref.modify(
+ const nextProvidersWithUpdateState = yield* Effect.forEach(
+ nextProviders,
+ applyProviderUpdateState,
+ {
+ concurrency: "unbounded",
+ },
+ );
+ const [previousProviders, providers, providersToPersist] = yield* Ref.modify(
providersRef,
(previousProviders) => {
const mergedProviders = new Map(
previousProviders.map((provider) => [snapshotInstanceKey(provider), provider] as const),
);
+ const updatedKeys = new Set<ProviderInstanceId>();
- for (const provider of nextProviders) {
+ for (const provider of nextProvidersWithUpdateState) {
const key = snapshotInstanceKey(provider);
+ updatedKeys.add(key);
mergedProviders.set(
key,
options?.replace === true
@@ -290,13 +349,16 @@ export const ProviderRegistryLive = Layer.effect(
}
const providers = orderProviderSnapshots([...mergedProviders.values()]);
- return [[previousProviders, providers] as const, providers];
+ const providersToPersist = providers.filter((provider) =>
+ updatedKeys.has(snapshotInstanceKey(provider)),
+ );
+ return [[previousProviders, providers, providersToPersist] as const, providers];
},
);
if (haveProvidersChanged(previousProviders, providers)) {
if (options?.persist !== false) {
- yield* Effect.forEach(nextProviders, persistProvider, {
+ yield* Effect.forEach(providersToPersist, persistProvider, {
concurrency: "unbounded",
discard: true,
});
@@ -318,6 +380,45 @@ export const ProviderRegistryLive = Layer.effect(
return yield* upsertProviders([provider], options);
});
+ const setProviderMaintenanceActionState = Effect.fn("setProviderMaintenanceActionState")(
+ function* (input: {
+ readonly instanceId: ProviderInstanceId;
+ readonly action: "update";
+ readonly state: ServerProviderUpdateState | null;
+ }) {
+ yield* Ref.update(maintenanceActionStatesRef, (previous) => {
+ const previousActions = previous.get(input.instanceId);
+ const nextActions = { ...previousActions };
+ if (input.state === null || input.state.status === "idle") {
+ delete nextActions[input.action];
+ } else {
+ nextActions[input.action] = input.state;
+ }
+
+ const next = new Map(previous);
+ if (Object.keys(nextActions).length === 0) {
+ next.delete(input.instanceId);
+ } else {
+ next.set(input.instanceId, nextActions);
+ }
+ return next;
+ });
+
+ const existingProviders = yield* Ref.get(providersRef);
+ const matchingProvider = existingProviders.find(
+ (candidate) => candidate.instanceId === input.instanceId,
+ );
+ if (!matchingProvider) {
+ return existingProviders;
+ }
+
+ const nextProvider = yield* applyProviderUpdateState(matchingProvider);
+ return yield* upsertProviders([nextProvider], {
+ persist: false,
+ });
+ },
+ );
+
const refreshOneSource = Effect.fn("refreshOneSource")(function* (
providerSource: ProviderSnapshotSource,
) {
@@ -365,6 +466,18 @@ export const ProviderRegistryLive = Layer.effect(
return yield* refreshOneSource(providerSource);
});
+ const getProviderMaintenanceCapabilitiesForInstance = Effect.fn(
+ "getProviderMaintenanceCapabilitiesForInstance",
+ )(function* (instanceId: ProviderInstanceId, provider: ProviderDriverKind) {
+ const instance = Array.from((yield* Ref.get(liveSubsRef)).values()).find(
+ (candidate) => candidate.instanceId === instanceId,
+ );
+ return (
+ instance?.snapshot.maintenanceCapabilities ??
+ makeManualProviderMaintenanceCapabilities(provider)
+ );
+ });
+
/**
* Diff the aggregator's live-source set against the current
* `ProviderInstanceRegistry` and:
@@ -472,6 +585,15 @@ export const ProviderRegistryLive = Layer.effect(
if (haveProvidersChanged(previousProviders, providers)) {
yield* PubSub.publish(changesPubSub, providers);
}
+ yield* Ref.update(maintenanceActionStatesRef, (previous) => {
+ const next = new Map(previous);
+ for (const instanceId of previous.keys()) {
+ if (!knownInstanceIds.has(instanceId)) {
+ next.delete(instanceId);
+ }
+ }
+ return next;
+ });
}),
);
const syncLiveSourcesAndContinue = syncLiveSources.pipe(
@@ -555,6 +677,8 @@ export const ProviderRegistryLive = Layer.effect(
refresh(provider).pipe(Effect.catchCause(recoverRefreshFailure)),
refreshInstance: (instanceId: ProviderInstanceId) =>
refreshInstance(instanceId).pipe(Effect.catchCause(recoverRefreshFailure)),
+ getProviderMaintenanceCapabilitiesForInstance,
+ setProviderMaintenanceActionState,
get streamChanges() {
return Stream.fromPubSub(changesPubSub);
},
diff --git a/apps/server/src/provider/Services/ProviderRegistry.ts b/apps/server/src/provider/Services/ProviderRegistry.ts
index 13a87bd87..b131c1c5b 100644
--- a/apps/server/src/provider/Services/ProviderRegistry.ts
+++ b/apps/server/src/provider/Services/ProviderRegistry.ts
@@ -6,9 +6,17 @@
*
* @module ProviderRegistry
*/
-import type { ProviderInstanceId, ProviderDriverKind, ServerProvider } from "@t3tools/contracts";
+import type {
+ ProviderInstanceId,
+ ProviderDriverKind,
+ ServerProvider,
+ ServerProviderUpdateState,
+} from "@t3tools/contracts";
import { Context } from "effect";
import type { Effect, Stream } from "effect";
+import type { ProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
+
+export type ProviderMaintenanceActionKind = "update";
export interface ProviderRegistryShape {
/**
@@ -39,6 +47,27 @@ export interface ProviderRegistryShape {
instanceId: ProviderInstanceId,
) => Effect.Effect<ReadonlyArray<ServerProvider>>;
+ /**
+ * Resolve the maintenance capabilities owned by one live provider instance.
+ * Falls back to manual-only capabilities when the instance is not live.
+ */
+ readonly getProviderMaintenanceCapabilitiesForInstance: (
+ instanceId: ProviderInstanceId,
+ provider: ProviderDriverKind,
+ ) => Effect.Effect<ProviderMaintenanceCapabilities>;
+
+ /**
+ * Apply volatile maintenance-action state to one configured instance.
+ * This state is never persisted to disk. Today only update actions are
+ * projected onto `ServerProvider.updateState`; install/auth actions can
+ * extend this action map without adding driver-scoped APIs.
+ */
+ readonly setProviderMaintenanceActionState: (input: {
+ readonly instanceId: ProviderInstanceId;
+ readonly action: ProviderMaintenanceActionKind;
+ readonly state: ServerProviderUpdateState | null;
+ }) => Effect.Effect<ReadonlyArray<ServerProvider>>;
+
/**
* Stream of provider snapshot updates — one emission per aggregated
* change. The array contains the full current state.
diff --git a/apps/server/src/provider/Services/ServerProvider.ts b/apps/server/src/provider/Services/ServerProvider.ts
index 4df0bc8fc..fb52080d5 100644
--- a/apps/server/src/provider/Services/ServerProvider.ts
+++ b/apps/server/src/provider/Services/ServerProvider.ts
@@ -1,7 +1,9 @@
import type { ServerProvider } from "@t3tools/contracts";
import type { Effect, Stream } from "effect";
+import type { ProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
export interface ServerProviderShape {
+ readonly maintenanceCapabilities: ProviderMaintenanceCapabilities;
readonly getSnapshot: Effect.Effect<ServerProvider>;
readonly refresh: Effect.Effect<ServerProvider>;
readonly streamChanges: Stream.Stream<ServerProvider>;
diff --git a/apps/server/src/provider/makeManagedServerProvider.test.ts b/apps/server/src/provider/makeManagedServerProvider.test.ts
index ff6647638..8595a56d5 100644
--- a/apps/server/src/provider/makeManagedServerProvider.test.ts
+++ b/apps/server/src/provider/makeManagedServerProvider.test.ts
@@ -20,6 +20,20 @@ interface TestSettings {
readonly enabled: boolean;
}
+const maintenanceCapabilities = {
+ provider: ProviderDriverKind.make("codex"),
+ packageName: "@openai/codex",
+ update: {
+ command: "npm install -g @openai/codex@latest",
+
+ executable: "npm",
+
+ args: ["install", "-g", "@openai/codex@latest"],
+
+ lockKey: "npm-global",
+ },
+} as const;
+
const initialSnapshot: ServerProvider = {
instanceId: ProviderInstanceId.make("codex"),
driver: ProviderDriverKind.make("codex"),
@@ -90,6 +104,7 @@ describe("makeManagedServerProvider", () => {
const checkCalls = yield* Ref.make(0);
const releaseCheck = yield* Deferred.make<void>();
const provider = yield* makeManagedServerProvider<TestSettings>({
+ maintenanceCapabilities,
getSettings: Effect.succeed({ enabled: true }),
streamSettings: Stream.empty,
haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -131,6 +146,7 @@ describe("makeManagedServerProvider", () => {
const releaseInitialCheck = yield* Deferred.make<void>();
const releaseSettingsCheck = yield* Deferred.make<void>();
const provider = yield* makeManagedServerProvider<TestSettings>({
+ maintenanceCapabilities,
getSettings: Ref.get(settingsRef),
streamSettings: Stream.fromPubSub(settingsChanges),
haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -172,6 +188,7 @@ describe("makeManagedServerProvider", () => {
const releaseEnrichment = yield* Deferred.make<void>();
const releaseCheck = yield* Deferred.make<void>();
const provider = yield* makeManagedServerProvider<TestSettings>({
+ maintenanceCapabilities,
getSettings: Effect.succeed({ enabled: true }),
streamSettings: Stream.empty,
haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -212,6 +229,7 @@ describe("makeManagedServerProvider", () => {
const secondCallbackReady = yield* Deferred.make<void>();
const allowFirstRefresh = yield* Deferred.make<void>();
const provider = yield* makeManagedServerProvider<TestSettings>({
+ maintenanceCapabilities,
getSettings: Effect.succeed({ enabled: true }),
streamSettings: Stream.empty,
haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
diff --git a/apps/server/src/provider/makeManagedServerProvider.ts b/apps/server/src/provider/makeManagedServerProvider.ts
index 4787a9f9c..a6800da06 100644
--- a/apps/server/src/provider/makeManagedServerProvider.ts
+++ b/apps/server/src/provider/makeManagedServerProvider.ts
@@ -13,6 +13,7 @@ interface ProviderSnapshotState {
export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(function* <
Settings,
>(input: {
+ readonly maintenanceCapabilities: ServerProviderShape["maintenanceCapabilities"];
readonly getSettings: Effect.Effect<Settings>;
readonly streamSettings: Stream.Stream<Settings>;
readonly haveSettingsChanged: (previous: Settings, next: Settings) => boolean;
@@ -143,6 +144,7 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
);
return {
+ maintenanceCapabilities: input.maintenanceCapabilities,
getSnapshot: input.getSettings.pipe(
Effect.flatMap(applySnapshot),
Effect.tapError(Effect.logError),
diff --git a/apps/server/src/provider/providerMaintenance.test.ts b/apps/server/src/provider/providerMaintenance.test.ts
new file mode 100644
index 000000000..20c47dd5f
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenance.test.ts
@@ -0,0 +1,487 @@
+import { afterEach, describe, expect, it } from "@effect/vitest";
+import { chmodSync, mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import os from "node:os";
+import path from "node:path";
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { Effect, Random } from "effect";
+import {
+ clearLatestProviderVersionCacheForTests,
+ createProviderVersionAdvisory,
+ makePackageManagedProviderMaintenanceResolver,
+ makeProviderMaintenanceCapabilities,
+ makeStaticProviderMaintenanceResolver,
+ normalizeCommandPath,
+ resolveProviderMaintenanceCapabilitiesEffect,
+} from "./providerMaintenance.ts";
+
+const driver = (value: string) => ProviderDriverKind.make(value);
+const makeTempDir = Effect.fn("makeTempDir")(function* (name: string) {
+ const id = yield* Random.nextUUIDv4;
+ return path.join(os.tmpdir(), `${name}-${id}`);
+});
+const isNativeTestCommandPath =
+ (expectedPathSegment: string) =>
+ (commandPath: string): boolean =>
+ normalizeCommandPath(commandPath).includes(expectedPathSegment);
+const packageToolUpdate = makePackageManagedProviderMaintenanceResolver({
+ provider: driver("packageTool"),
+ npmPackageName: "@example/package-tool",
+ homebrewFormula: "package-tool",
+ nativeUpdate: null,
+});
+const nativePackageToolUpdate = makePackageManagedProviderMaintenanceResolver({
+ provider: driver("nativePackageTool"),
+ npmPackageName: "@example/native-package-tool",
+ homebrewFormula: "native-package-tool",
+ nativeUpdate: {
+ executable: "native-package-tool",
+ args: ["update"],
+ lockKey: "native-package-tool-native",
+ isCommandPath: isNativeTestCommandPath("/.local/bin/native-package-tool"),
+ },
+});
+const scopedPackageToolUpdate = makePackageManagedProviderMaintenanceResolver({
+ provider: driver("scopedPackageTool"),
+ npmPackageName: "@example/scoped-package-tool",
+ homebrewFormula: "example/tap/scoped-package-tool",
+ nativeUpdate: {
+ executable: "scoped-package-tool",
+ args: ["upgrade"],
+ lockKey: "scoped-package-tool-native",
+ isCommandPath: isNativeTestCommandPath("/.scoped-package-tool/bin/scoped-package-tool"),
+ },
+});
+const staticToolUpdate = makeStaticProviderMaintenanceResolver(
+ makeProviderMaintenanceCapabilities({
+ provider: driver("staticTool"),
+ packageName: null,
+ updateExecutable: "static-tool",
+ updateArgs: ["update"],
+ updateLockKey: "static-tool",
+ }),
+);
+
+afterEach(() => {
+ clearLatestProviderVersionCacheForTests();
+});
+
+describe("providerMaintenance", () => {
+ it("marks providers with unknown current versions as unknown", () => {
+ expect(
+ createProviderVersionAdvisory({
+ driver: driver("packageTool"),
+ currentVersion: null,
+ latestVersion: "9.9.9",
+ }),
+ ).toMatchObject({
+ status: "unknown",
+ currentVersion: null,
+ latestVersion: "9.9.9",
+ });
+ });
+
+ it("marks providers with unknown latest versions as unknown", () => {
+ expect(
+ createProviderVersionAdvisory({
+ driver: driver("packageTool"),
+ currentVersion: "1.0.0",
+ latestVersion: null,
+ }),
+ ).toMatchObject({
+ status: "unknown",
+ currentVersion: "1.0.0",
+ latestVersion: null,
+ message: null,
+ });
+ });
+
+ it("marks installed providers behind latest when a newer provider version is available", () => {
+ expect(
+ createProviderVersionAdvisory({
+ driver: driver("nativePackageTool"),
+ currentVersion: "2.1.110",
+ latestVersion: "2.1.117",
+ maintenanceCapabilities: nativePackageToolUpdate.resolve(),
+ }),
+ ).toMatchObject({
+ status: "behind_latest",
+ currentVersion: "2.1.110",
+ latestVersion: "2.1.117",
+ updateCommand: "npm install -g @example/native-package-tool@latest",
+ canUpdate: true,
+ message: "Install the update now or review provider settings.",
+ });
+ });
+
+ it("keeps update commands owned by provider maintenance capabilities", () => {
+ expect(staticToolUpdate.resolve()).toEqual({
+ provider: driver("staticTool"),
+ packageName: null,
+ update: {
+ command: "static-tool update",
+
+ executable: "static-tool",
+
+ args: ["update"],
+
+ lockKey: "static-tool",
+ },
+ });
+ });
+
+ it.effect(
+ "switches package-managed providers to vite-plus updates when the resolved binary lives in vite-plus global bin",
+ () =>
+ Effect.gen(function* () {
+ const tempDir = yield* makeTempDir("t3-vite-plus-capabilities");
+ const vitePlusBinDir = path.join(tempDir, ".vite-plus", "bin");
+ mkdirSync(vitePlusBinDir, { recursive: true });
+ const packageToolPath = path.join(vitePlusBinDir, "package-tool");
+ writeFileSync(packageToolPath, "#!/bin/sh\n");
+ chmodSync(packageToolPath, 0o755);
+
+ expect(
+ packageToolUpdate.resolve({
+ binaryPath: "package-tool",
+ platform: "darwin",
+ env: {
+ PATH: vitePlusBinDir,
+ },
+ }),
+ ).toEqual({
+ provider: driver("packageTool"),
+ packageName: "@example/package-tool",
+ update: {
+ command: "vp i -g @example/package-tool",
+
+ executable: "vp",
+
+ args: ["i", "-g", "@example/package-tool"],
+
+ lockKey: "vite-plus-global",
+ },
+ });
+ }),
+ );
+
+ it.effect(
+ "switches package-managed providers to bun updates when the resolved binary lives in bun's global bin",
+ () =>
+ Effect.gen(function* () {
+ const tempDir = yield* makeTempDir("t3-bun-capabilities");
+ const bunBinDir = path.join(tempDir, ".bun", "bin");
+ mkdirSync(bunBinDir, { recursive: true });
+ writeFileSync(path.join(bunBinDir, "native-package-tool.exe"), "MZ");
+
+ expect(
+ nativePackageToolUpdate.resolve({
+ binaryPath: "native-package-tool",
+ platform: "win32",
+ env: {
+ PATH: bunBinDir,
+ PATHEXT: ".COM;.EXE;.BAT;.CMD",
+ },
+ }),
+ ).toEqual({
+ provider: driver("nativePackageTool"),
+ packageName: "@example/native-package-tool",
+ update: {
+ command: "bun i -g @example/native-package-tool@latest",
+
+ executable: "bun",
+
+ args: ["i", "-g", "@example/native-package-tool@latest"],
+
+ lockKey: "bun-global",
+ },
+ });
+ }),
+ );
+
+ it.effect(
+ "switches package-managed providers to pnpm updates when the resolved binary lives in pnpm's global bin",
+ () =>
+ Effect.gen(function* () {
+ const tempDir = yield* makeTempDir("t3-pnpm-capabilities");
+ const pnpmHomeDir = path.join(tempDir, ".local", "share", "pnpm");
+ mkdirSync(pnpmHomeDir, { recursive: true });
+ const scopedPackageToolPath = path.join(pnpmHomeDir, "scoped-package-tool");
+ writeFileSync(scopedPackageToolPath, "#!/bin/sh\n");
+ chmodSync(scopedPackageToolPath, 0o755);
+
+ expect(
+ scopedPackageToolUpdate.resolve({
+ binaryPath: "scoped-package-tool",
+ platform: "darwin",
+ env: {
+ PATH: pnpmHomeDir,
+ },
+ }),
+ ).toEqual({
+ provider: driver("scopedPackageTool"),
+ packageName: "@example/scoped-package-tool",
+ update: {
+ command: "pnpm add -g @example/scoped-package-tool@latest",
+
+ executable: "pnpm",
+
+ args: ["add", "-g", "@example/scoped-package-tool@latest"],
+
+ lockKey: "pnpm-global",
+ },
+ });
+ }),
+ );
+
+ it("switches package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
+ expect(
+ packageToolUpdate.resolve({
+ binaryPath: "/opt/homebrew/bin/package-tool",
+ platform: "darwin",
+ env: {
+ PATH: "",
+ },
+ }),
+ ).toEqual({
+ provider: driver("packageTool"),
+ packageName: "@example/package-tool",
+ update: {
+ command: "brew upgrade package-tool",
+
+ executable: "brew",
+
+ args: ["upgrade", "package-tool"],
+
+ lockKey: "homebrew",
+ },
+ });
+ });
+
+ it.effect(
+ "switches native-package-tool to native updates when the binary resolves through the native installer",
+ () =>
+ Effect.gen(function* () {
+ const tempDir = yield* makeTempDir("t3-native-package-tool-native-capabilities");
+ const nativeBinDir = path.join(tempDir, ".local", "bin");
+ mkdirSync(nativeBinDir, { recursive: true });
+ const nativePackageToolPath = path.join(nativeBinDir, "native-package-tool");
+ writeFileSync(nativePackageToolPath, "#!/bin/sh\n");
+ chmodSync(nativePackageToolPath, 0o755);
+
+ expect(
+ nativePackageToolUpdate.resolve({
+ binaryPath: "native-package-tool",
+ platform: "darwin",
+ env: {
+ PATH: nativeBinDir,
+ },
+ }),
+ ).toEqual({
+ provider: driver("nativePackageTool"),
+ packageName: "@example/native-package-tool",
+ update: {
+ command: "native-package-tool update",
+
+ executable: "native-package-tool",
+
+ args: ["update"],
+
+ lockKey: "native-package-tool-native",
+ },
+ });
+ }),
+ );
+
+ it.effect(
+ "switches scoped-package-tool to native upgrades when the binary resolves through the standalone installer",
+ () =>
+ Effect.gen(function* () {
+ const tempDir = yield* makeTempDir("t3-scoped-package-tool-native-capabilities");
+ const nativeBinDir = path.join(tempDir, ".scoped-package-tool", "bin");
+ mkdirSync(nativeBinDir, { recursive: true });
+ const scopedPackageToolPath = path.join(nativeBinDir, "scoped-package-tool");
+ writeFileSync(scopedPackageToolPath, "#!/bin/sh\n");
+ chmodSync(scopedPackageToolPath, 0o755);
+
+ expect(
+ scopedPackageToolUpdate.resolve({
+ binaryPath: "scoped-package-tool",
+ platform: "darwin",
+ env: {
+ PATH: nativeBinDir,
+ },
+ }),
+ ).toEqual({
+ provider: driver("scopedPackageTool"),
+ packageName: "@example/scoped-package-tool",
+ update: {
+ command: "scoped-package-tool upgrade",
+
+ executable: "scoped-package-tool",
+
+ args: ["upgrade"],
+
+ lockKey: "scoped-package-tool-native",
+ },
+ });
+ }),
+ );
+
+ it("switches native-package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
+ expect(
+ nativePackageToolUpdate.resolve({
+ binaryPath: "/opt/homebrew/bin/native-package-tool",
+ platform: "darwin",
+ env: {
+ PATH: "",
+ },
+ }),
+ ).toEqual({
+ provider: driver("nativePackageTool"),
+ packageName: "@example/native-package-tool",
+ update: {
+ command: "brew upgrade native-package-tool",
+
+ executable: "brew",
+
+ args: ["upgrade", "native-package-tool"],
+
+ lockKey: "homebrew",
+ },
+ });
+ });
+
+ it("switches scoped-package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
+ expect(
+ scopedPackageToolUpdate.resolve({
+ binaryPath: "/opt/homebrew/bin/scoped-package-tool",
+ platform: "darwin",
+ env: {
+ PATH: "",
+ },
+ }),
+ ).toEqual({
+ provider: driver("scopedPackageTool"),
+ packageName: "@example/scoped-package-tool",
+ update: {
+ command: "brew upgrade example/tap/scoped-package-tool",
+
+ executable: "brew",
+
+ args: ["upgrade", "example/tap/scoped-package-tool"],
+
+ lockKey: "homebrew",
+ },
+ });
+ });
+
+ it.effect("keeps npm updates for binaries symlinked into npm's global node_modules tree", () =>
+ Effect.gen(function* () {
+ const tempDir = yield* makeTempDir("t3-npm-capabilities");
+ const binDir = path.join(tempDir, "bin");
+ const packageBinDir = path.join(
+ tempDir,
+ "lib",
+ "node_modules",
+ "@example",
+ "package-tool",
+ "bin",
+ );
+ mkdirSync(binDir, { recursive: true });
+ mkdirSync(packageBinDir, { recursive: true });
+ const packageBinPath = path.join(packageBinDir, "package-tool.js");
+ const symlinkPath = path.join(binDir, "package-tool");
+ writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
+ chmodSync(packageBinPath, 0o755);
+ symlinkSync(packageBinPath, symlinkPath);
+
+ const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
+ binaryPath: symlinkPath,
+ platform: "darwin",
+ env: {
+ PATH: "",
+ },
+ }).pipe(Effect.provide(NodeServices.layer));
+
+ expect(capabilities).toEqual({
+ provider: driver("packageTool"),
+ packageName: "@example/package-tool",
+ update: {
+ command: "npm install -g @example/package-tool@latest",
+
+ executable: "npm",
+
+ args: ["install", "-g", "@example/package-tool@latest"],
+
+ lockKey: "npm-global",
+ },
+ });
+ }),
+ );
+
+ it.effect("uses Effect FileSystem realPath when detecting pnpm global symlinks", () =>
+ Effect.gen(function* () {
+ const tempDir = yield* makeTempDir("t3-pnpm-realpath-capabilities");
+ const binDir = path.join(tempDir, "bin");
+ const packageBinDir = path.join(
+ tempDir,
+ ".local",
+ "share",
+ "pnpm",
+ "global",
+ "5",
+ "node_modules",
+ "@example",
+ "package-tool",
+ "bin",
+ );
+ mkdirSync(binDir, { recursive: true });
+ mkdirSync(packageBinDir, { recursive: true });
+ const packageBinPath = path.join(packageBinDir, "package-tool.js");
+ const symlinkPath = path.join(binDir, "package-tool");
+ writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
+ chmodSync(packageBinPath, 0o755);
+ symlinkSync(packageBinPath, symlinkPath);
+
+ const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
+ binaryPath: symlinkPath,
+ platform: "darwin",
+ env: {
+ PATH: "",
+ },
+ }).pipe(Effect.provide(NodeServices.layer));
+
+ expect(capabilities).toEqual({
+ provider: driver("packageTool"),
+ packageName: "@example/package-tool",
+ update: {
+ command: "pnpm add -g @example/package-tool@latest",
+
+ executable: "pnpm",
+
+ args: ["add", "-g", "@example/package-tool@latest"],
+
+ lockKey: "pnpm-global",
+ },
+ });
+ }),
+ );
+
+ it("disables one-click updates for explicit custom binary paths it cannot safely map", () => {
+ expect(
+ packageToolUpdate.resolve({
+ binaryPath: "C:\\Tools\\package-tool\\package-tool.exe",
+ platform: "win32",
+ env: {
+ PATH: "",
+ PATHEXT: ".COM;.EXE;.BAT;.CMD",
+ },
+ }),
+ ).toEqual({
+ provider: driver("packageTool"),
+ packageName: "@example/package-tool",
+ update: null,
+ });
+ });
+});
diff --git a/apps/server/src/provider/providerMaintenance.ts b/apps/server/src/provider/providerMaintenance.ts
new file mode 100644
index 000000000..5a44a5ec2
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenance.ts
@@ -0,0 +1,472 @@
+import {
+ ProviderDriverKind,
+ type ServerProvider,
+ type ServerProviderVersionAdvisory,
+} from "@t3tools/contracts";
+import { resolveCommandPath } from "@t3tools/shared/shell";
+import { DateTime, Effect, FileSystem, Option, Schema } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+
+import { compareCliVersions } from "./cliVersion.ts";
+
+const LATEST_VERSION_CACHE_TTL_MS = 60 * 60 * 1_000;
+const LATEST_VERSION_TIMEOUT_MS = 4_000;
+const PROVIDER_UPDATE_ACTION_TOAST_MESSAGE = "Install the update now or review provider settings.";
+
+export interface ProviderMaintenanceCapabilities {
+ readonly provider: ProviderDriverKind;
+ readonly packageName: string | null;
+ readonly update: ProviderMaintenanceCommandAction | null;
+}
+
+export interface ProviderMaintenanceCommandAction {
+ readonly command: string;
+ readonly executable: string;
+ readonly args: ReadonlyArray<string>;
+ readonly lockKey: string;
+}
+
+export interface ProviderMaintenanceCapabilityResolutionOptions {
+ readonly binaryPath?: string | null;
+ readonly env?: NodeJS.ProcessEnv;
+ readonly platform?: NodeJS.Platform;
+ readonly realCommandPath?: string | null;
+}
+
+export interface ProviderMaintenanceCapabilitiesResolver {
+ readonly resolve: (
+ options?: ProviderMaintenanceCapabilityResolutionOptions,
+ ) => ProviderMaintenanceCapabilities;
+}
+
+export interface PackageManagedProviderMaintenanceDefinition {
+ readonly provider: ProviderDriverKind;
+ readonly npmPackageName: string;
+ readonly homebrewFormula: string | null;
+ readonly nativeUpdate: {
+ readonly executable: string;
+ readonly args: ReadonlyArray<string>;
+ readonly lockKey: string;
+ readonly isCommandPath: (commandPath: string) => boolean;
+ } | null;
+}
+
+interface LatestVersionCacheEntry {
+ readonly expiresAt: number;
+ readonly version: string | null;
+}
+
+const latestVersionCache = new Map<string, LatestVersionCacheEntry>();
+const NpmLatestVersionResponse = Schema.Struct({
+ version: Schema.optional(Schema.String),
+});
+
+export function clearLatestProviderVersionCacheForTests(): void {
+ latestVersionCache.clear();
+}
+
+function nonEmptyString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function makeProviderMaintenanceCapabilities(input: {
+ readonly provider: ProviderDriverKind;
+ readonly packageName: string | null;
+ readonly updateExecutable: string | null;
+ readonly updateArgs: ReadonlyArray<string>;
+ readonly updateLockKey: string | null;
+}): ProviderMaintenanceCapabilities {
+ const update =
+ input.updateExecutable === null || input.updateLockKey === null
+ ? null
+ : {
+ command: [input.updateExecutable, ...input.updateArgs].join(" "),
+ executable: input.updateExecutable,
+ args: input.updateArgs,
+ lockKey: input.updateLockKey,
+ };
+ return {
+ provider: input.provider,
+ packageName: input.packageName,
+ update,
+ };
+}
+
+export function makeManualOnlyProviderMaintenanceCapabilities(input: {
+ readonly provider: ProviderDriverKind;
+ readonly packageName: string | null;
+}): ProviderMaintenanceCapabilities {
+ return makeProviderMaintenanceCapabilities({
+ provider: input.provider,
+ packageName: input.packageName,
+ updateExecutable: null,
+ updateArgs: [],
+ updateLockKey: null,
+ });
+}
+
+function makeNpmGlobalProviderMaintenanceCapabilities(
+ definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+ return makeProviderMaintenanceCapabilities({
+ provider: definition.provider,
+ packageName: definition.npmPackageName,
+ updateExecutable: "npm",
+ updateArgs: ["install", "-g", `${definition.npmPackageName}@latest`],
+ updateLockKey: "npm-global",
+ });
+}
+
+function makeBunGlobalProviderMaintenanceCapabilities(
+ definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+ return makeProviderMaintenanceCapabilities({
+ provider: definition.provider,
+ packageName: definition.npmPackageName,
+ updateExecutable: "bun",
+ updateArgs: ["i", "-g", `${definition.npmPackageName}@latest`],
+ updateLockKey: "bun-global",
+ });
+}
+
+function makePnpmGlobalProviderMaintenanceCapabilities(
+ definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+ return makeProviderMaintenanceCapabilities({
+ provider: definition.provider,
+ packageName: definition.npmPackageName,
+ updateExecutable: "pnpm",
+ updateArgs: ["add", "-g", `${definition.npmPackageName}@latest`],
+ updateLockKey: "pnpm-global",
+ });
+}
+
+function makeVitePlusGlobalProviderMaintenanceCapabilities(
+ definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+ return makeProviderMaintenanceCapabilities({
+ provider: definition.provider,
+ packageName: definition.npmPackageName,
+ updateExecutable: "vp",
+ updateArgs: ["i", "-g", definition.npmPackageName],
+ updateLockKey: "vite-plus-global",
+ });
+}
+
+function makeHomebrewProviderMaintenanceCapabilities(
+ definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+ if (!definition.homebrewFormula) {
+ return makeManualOnlyProviderMaintenanceCapabilities({
+ provider: definition.provider,
+ packageName: definition.npmPackageName,
+ });
+ }
+
+ return makeProviderMaintenanceCapabilities({
+ provider: definition.provider,
+ packageName: definition.npmPackageName,
+ updateExecutable: "brew",
+ updateArgs: ["upgrade", definition.homebrewFormula],
+ updateLockKey: "homebrew",
+ });
+}
+
+function makeNativeProviderMaintenanceCapabilities(
+ definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities | null {
+ if (!definition.nativeUpdate) {
+ return null;
+ }
+
+ return makeProviderMaintenanceCapabilities({
+ provider: definition.provider,
+ packageName: definition.npmPackageName,
+ updateExecutable: definition.nativeUpdate.executable,
+ updateArgs: definition.nativeUpdate.args,
+ updateLockKey: definition.nativeUpdate.lockKey,
+ });
+}
+
+export function hasPathSeparator(value: string): boolean {
+ return value.includes("/") || value.includes("\\");
+}
+
+export function normalizeCommandPath(commandPath: string): string {
+ return commandPath.replaceAll("\\", "/").toLowerCase();
+}
+
+function isBunGlobalCommandPath(commandPath: string): boolean {
+ return normalizeCommandPath(commandPath).includes("/.bun/bin/");
+}
+
+function isVitePlusGlobalCommandPath(commandPath: string): boolean {
+ return normalizeCommandPath(commandPath).includes("/.vite-plus/bin/");
+}
+
+function isPnpmGlobalCommandPath(commandPath: string): boolean {
+ const normalized = normalizeCommandPath(commandPath);
+ return (
+ normalized.includes("/.local/share/pnpm/") ||
+ normalized.includes("/library/pnpm/") ||
+ normalized.includes("/local/share/pnpm/") ||
+ normalized.includes("/appdata/local/pnpm/") ||
+ normalized.includes("/pnpm/global/")
+ );
+}
+
+function isNpmGlobalCommandPath(commandPath: string): boolean {
+ const normalized = normalizeCommandPath(commandPath);
+ return (
+ normalized.includes("/node_modules/.bin/") ||
+ normalized.includes("/lib/node_modules/") ||
+ normalized.includes("/npm/node_modules/")
+ );
+}
+
+function isHomebrewCommandPath(commandPath: string): boolean {
+ const normalized = normalizeCommandPath(commandPath);
+ return (
+ normalized.includes("/opt/homebrew/cellar/") ||
+ normalized.includes("/usr/local/cellar/") ||
+ normalized.includes("/homebrew/cellar/") ||
+ normalized.includes("/opt/homebrew/caskroom/") ||
+ normalized.includes("/usr/local/caskroom/") ||
+ normalized.includes("/homebrew/caskroom/") ||
+ normalized.startsWith("/opt/homebrew/bin/") ||
+ normalized.startsWith("/usr/local/bin/")
+ );
+}
+
+export function resolvePackageManagedProviderMaintenance(
+ definition: PackageManagedProviderMaintenanceDefinition,
+ options?: ProviderMaintenanceCapabilityResolutionOptions,
+): ProviderMaintenanceCapabilities {
+ const binaryPath = nonEmptyString(options?.binaryPath);
+ if (!binaryPath) {
+ return makeNpmGlobalProviderMaintenanceCapabilities(definition);
+ }
+
+ const resolvedCommandPath =
+ resolveCommandPath(binaryPath, {
+ ...(options?.platform ? { platform: options.platform } : {}),
+ ...(options?.env ? { env: options.env } : {}),
+ }) ?? (hasPathSeparator(binaryPath) ? binaryPath : null);
+
+ if (resolvedCommandPath) {
+ const commandPaths = [
+ resolvedCommandPath,
+ ...(options?.realCommandPath ? [options.realCommandPath] : []),
+ ];
+
+ const nativeUpdate = definition.nativeUpdate;
+ if (
+ nativeUpdate &&
+ commandPaths.some((commandPath) => nativeUpdate.isCommandPath(commandPath))
+ ) {
+ return (
+ makeNativeProviderMaintenanceCapabilities(definition) ??
+ makeNpmGlobalProviderMaintenanceCapabilities(definition)
+ );
+ }
+ if (commandPaths.some(isVitePlusGlobalCommandPath)) {
+ return makeVitePlusGlobalProviderMaintenanceCapabilities(definition);
+ }
+ if (commandPaths.some(isBunGlobalCommandPath)) {
+ return makeBunGlobalProviderMaintenanceCapabilities(definition);
+ }
+ if (commandPaths.some(isPnpmGlobalCommandPath)) {
+ return makePnpmGlobalProviderMaintenanceCapabilities(definition);
+ }
+ if (commandPaths.some(isNpmGlobalCommandPath)) {
+ return makeNpmGlobalProviderMaintenanceCapabilities(definition);
+ }
+ if (commandPaths.some(isHomebrewCommandPath)) {
+ return makeHomebrewProviderMaintenanceCapabilities(definition);
+ }
+ }
+
+ if (!hasPathSeparator(binaryPath)) {
+ return makeNpmGlobalProviderMaintenanceCapabilities(definition);
+ }
+
+ return makeManualOnlyProviderMaintenanceCapabilities({
+ provider: definition.provider,
+ packageName: definition.npmPackageName,
+ });
+}
+
+export function makePackageManagedProviderMaintenanceResolver(
+ definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilitiesResolver {
+ return {
+ resolve: (options) => resolvePackageManagedProviderMaintenance(definition, options),
+ };
+}
+
+export function makeStaticProviderMaintenanceResolver(
+ capabilities: ProviderMaintenanceCapabilities,
+): ProviderMaintenanceCapabilitiesResolver {
+ return {
+ resolve: () => capabilities,
+ };
+}
+
+function makeManualProviderMaintenanceCapabilities(
+ provider: ProviderDriverKind,
+): ProviderMaintenanceCapabilities {
+ return makeManualOnlyProviderMaintenanceCapabilities({
+ provider,
+ packageName: null,
+ });
+}
+
+export const resolveProviderMaintenanceCapabilitiesEffect = Effect.fn(
+ "resolveProviderMaintenanceCapabilitiesEffect",
+)(function* (
+ resolver: ProviderMaintenanceCapabilitiesResolver,
+ options?: Omit<ProviderMaintenanceCapabilityResolutionOptions, "realCommandPath">,
+) {
+ const binaryPath = nonEmptyString(options?.binaryPath);
+ if (!binaryPath) {
+ return resolver.resolve(options);
+ }
+
+ const resolvedCommandPath =
+ resolveCommandPath(binaryPath, {
+ ...(options?.platform ? { platform: options.platform } : {}),
+ ...(options?.env ? { env: options.env } : {}),
+ }) ?? (hasPathSeparator(binaryPath) ? binaryPath : null);
+ if (!resolvedCommandPath) {
+ return resolver.resolve(options);
+ }
+
+ const fileSystem = yield* FileSystem.FileSystem;
+ const realCommandPath = yield* fileSystem
+ .realPath(resolvedCommandPath)
+ .pipe(Effect.catch(() => Effect.succeed(resolvedCommandPath)));
+ return resolver.resolve({
+ ...options,
+ realCommandPath,
+ });
+});
+
+function deriveVersionAdvisory(input: {
+ readonly currentVersion: string | null;
+ readonly latestVersion: string | null;
+}): Pick<ServerProviderVersionAdvisory, "status" | "message"> {
+ if (!input.currentVersion) {
+ return { status: "unknown", message: null };
+ }
+ if (!input.latestVersion) {
+ return { status: "unknown", message: null };
+ }
+ if (compareCliVersions(input.currentVersion, input.latestVersion) < 0) {
+ return {
+ status: "behind_latest",
+ message: PROVIDER_UPDATE_ACTION_TOAST_MESSAGE,
+ };
+ }
+ return { status: "current", message: null };
+}
+
+export function createProviderVersionAdvisory(input: {
+ readonly driver: ProviderDriverKind;
+ readonly currentVersion: string | null;
+ readonly latestVersion?: string | null;
+ readonly checkedAt?: string | null;
+ readonly maintenanceCapabilities?: ProviderMaintenanceCapabilities;
+}): ServerProviderVersionAdvisory {
+ const capabilities =
+ input.maintenanceCapabilities ?? makeManualProviderMaintenanceCapabilities(input.driver);
+ const latestVersion = input.latestVersion ?? null;
+ const advisory = deriveVersionAdvisory({
+ currentVersion: input.currentVersion,
+ latestVersion,
+ });
+
+ return {
+ status: advisory.status,
+ currentVersion: input.currentVersion,
+ latestVersion,
+ updateCommand: capabilities.update?.command ?? null,
+ canUpdate: capabilities.update !== null,
+ checkedAt: input.checkedAt ?? null,
+ message: advisory.message,
+ };
+}
+
+const fetchNpmLatestVersion = Effect.fn("fetchNpmLatestVersion")(function* (packageName: string) {
+ const client = yield* HttpClient.HttpClient;
+ const request = HttpClientRequest.get(
+ `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`,
+ ).pipe(HttpClientRequest.setHeader("accept", "application/json"));
+ const response = yield* client.execute(request).pipe(
+ Effect.timeoutOption(LATEST_VERSION_TIMEOUT_MS),
+ Effect.catch(() => Effect.succeed(Option.none())),
+ );
+ if (Option.isNone(response)) {
+ return null;
+ }
+ const httpResponse = response.value;
+ if (httpResponse.status < 200 || httpResponse.status >= 300) {
+ return null;
+ }
+ const payload = yield* httpResponse.json.pipe(
+ Effect.flatMap(Schema.decodeUnknownEffect(NpmLatestVersionResponse)),
+ Effect.catch(() => Effect.succeed(null)),
+ );
+ return payload ? nonEmptyString(payload.version) : null;
+});
+
+export const resolveLatestProviderVersion = Effect.fn("resolveLatestProviderVersion")(function* (
+ maintenanceCapabilities: ProviderMaintenanceCapabilities,
+) {
+ const packageName = maintenanceCapabilities.packageName;
+ if (!packageName) {
+ return null;
+ }
+
+ const cached = latestVersionCache.get(packageName);
+ const now = DateTime.toEpochMillis(yield* DateTime.now);
+ if (cached && cached.expiresAt > now) {
+ return cached.version;
+ }
+
+ const version = yield* fetchNpmLatestVersion(packageName);
+ latestVersionCache.set(packageName, {
+ expiresAt: now + LATEST_VERSION_CACHE_TTL_MS,
+ version,
+ });
+ return version;
+});
+
+export const enrichProviderSnapshotWithVersionAdvisory = Effect.fn(
+ "enrichProviderSnapshotWithVersionAdvisory",
+)(function* (snapshot: ServerProvider, maintenanceCapabilities?: ProviderMaintenanceCapabilities) {
+ const capabilities =
+ maintenanceCapabilities ?? makeManualProviderMaintenanceCapabilities(snapshot.driver);
+ if (!snapshot.enabled || !snapshot.installed || !snapshot.version) {
+ return {
+ ...snapshot,
+ versionAdvisory: createProviderVersionAdvisory({
+ driver: snapshot.driver,
+ currentVersion: snapshot.version,
+ checkedAt: snapshot.checkedAt,
+ maintenanceCapabilities: capabilities,
+ }),
+ };
+ }
+
+ const latestVersion = yield* resolveLatestProviderVersion(capabilities);
+ return {
+ ...snapshot,
+ versionAdvisory: createProviderVersionAdvisory({
+ driver: snapshot.driver,
+ currentVersion: snapshot.version,
+ latestVersion,
+ checkedAt: DateTime.formatIso(yield* DateTime.now),
+ maintenanceCapabilities: capabilities,
+ }),
+ };
+});
diff --git a/apps/server/src/provider/providerMaintenanceCommandCoordinator.ts b/apps/server/src/provider/providerMaintenanceCommandCoordinator.ts
new file mode 100644
index 000000000..875102c83
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenanceCommandCoordinator.ts
@@ -0,0 +1,79 @@
+import { Effect, Ref } from "effect";
+import * as Semaphore from "effect/Semaphore";
+
+export interface ProviderMaintenanceCommandCoordinatorShape<E> {
+ readonly withCommandLock: <A, R>(input: {
+ readonly targetKey: string;
+ readonly lockKey: string;
+ readonly onQueued?: Effect.Effect<void, E, R>;
+ readonly run: Effect.Effect<A, E, R>;
+ }) => Effect.Effect<A, E, R>;
+}
+
+export const makeProviderMaintenanceCommandCoordinator = Effect.fn(
+ "makeProviderMaintenanceCommandCoordinator",
+)(function* <E>(input: { readonly makeAlreadyRunningError: (targetKey: string) => E }) {
+ const runningTargetsRef = yield* Ref.make<ReadonlySet<string>>(new Set());
+ const locksRef = yield* Ref.make<ReadonlyMap<string, Semaphore.Semaphore>>(new Map());
+
+ const acquireTarget = Effect.fn("acquireTarget")(function* (targetKey: string) {
+ return yield* Ref.modify(runningTargetsRef, (runningTargets) => {
+ if (runningTargets.has(targetKey)) {
+ return [false, runningTargets] as const;
+ }
+ const next = new Set(runningTargets);
+ next.add(targetKey);
+ return [true, next] as const;
+ });
+ });
+
+ const releaseTarget = (targetKey: string) =>
+ Ref.update(runningTargetsRef, (runningTargets) => {
+ const next = new Set(runningTargets);
+ next.delete(targetKey);
+ return next;
+ });
+
+ const getLock = Effect.fn("getProviderMaintenanceCommandLock")(function* (lockKey: string) {
+ const existing = (yield* Ref.get(locksRef)).get(lockKey);
+ if (existing) {
+ return existing;
+ }
+
+ const lock = yield* Semaphore.make(1);
+ return yield* Ref.modify(locksRef, (locks) => {
+ const current = locks.get(lockKey);
+ if (current) {
+ return [current, locks] as const;
+ }
+ const next = new Map(locks);
+ next.set(lockKey, lock);
+ return [lock, next] as const;
+ });
+ });
+
+ const withCommandLock: ProviderMaintenanceCommandCoordinatorShape<E>["withCommandLock"] = ({
+ targetKey,
+ lockKey,
+ onQueued,
+ run,
+ }) =>
+ Effect.gen(function* () {
+ const acquired = yield* acquireTarget(targetKey);
+ if (!acquired) {
+ return yield* Effect.fail(input.makeAlreadyRunningError(targetKey));
+ }
+
+ return yield* Effect.gen(function* () {
+ const lock = yield* getLock(lockKey);
+ if (onQueued) {
+ yield* onQueued;
+ }
+ return yield* lock.withPermits(1)(run);
+ }).pipe(Effect.ensuring(releaseTarget(targetKey)));
+ });
+
+ return {
+ withCommandLock,
+ } satisfies ProviderMaintenanceCommandCoordinatorShape<E>;
+});
diff --git a/apps/server/src/provider/providerMaintenanceRunner.test.ts b/apps/server/src/provider/providerMaintenanceRunner.test.ts
new file mode 100644
index 000000000..4c0a751a6
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenanceRunner.test.ts
@@ -0,0 +1,640 @@
+import { afterEach, describe, it, assert } from "@effect/vitest";
+import {
+ ProviderDriverKind,
+ ProviderInstanceId,
+ type ServerProvider,
+ type ServerProviderUpdateState,
+} from "@t3tools/contracts";
+import { ServerProviderUpdateError } from "@t3tools/contracts";
+import { Cause, Effect, Exit, Fiber, Layer, Ref, Schema, Sink, Stream } from "effect";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { ProviderRegistry, type ProviderRegistryShape } from "./Services/ProviderRegistry.ts";
+import * as ProviderMaintenanceRunner from "./providerMaintenanceRunner.ts";
+import {
+ clearLatestProviderVersionCacheForTests,
+ makeProviderMaintenanceCapabilities,
+ type ProviderMaintenanceCapabilities,
+} from "./providerMaintenance.ts";
+
+const CODEX_DRIVER = ProviderDriverKind.make("codex");
+const CURSOR_DRIVER = ProviderDriverKind.make("cursor");
+const OPENCODE_DRIVER = ProviderDriverKind.make("opencode");
+const CODEX_INSTANCE_ID = ProviderInstanceId.make("codex");
+const CURSOR_INSTANCE_ID = ProviderInstanceId.make("cursor");
+const OPENCODE_INSTANCE_ID = ProviderInstanceId.make("opencode");
+const encoder = new TextEncoder();
+
+afterEach(() => {
+ clearLatestProviderVersionCacheForTests();
+});
+
+function lifecycleFor(provider: ProviderDriverKind): ProviderMaintenanceCapabilities {
+ if (provider === CURSOR_DRIVER) {
+ return makeProviderMaintenanceCapabilities({
+ provider,
+ packageName: null,
+ updateExecutable: "agent",
+ updateArgs: ["update"],
+ updateLockKey: "cursor-agent",
+ });
+ }
+ return makeProviderMaintenanceCapabilities({
+ provider,
+ packageName: provider === OPENCODE_DRIVER ? "opencode-ai" : "@openai/codex",
+ updateExecutable: "npm",
+ updateArgs:
+ provider === OPENCODE_DRIVER
+ ? ["install", "-g", "opencode-ai@latest"]
+ : ["install", "-g", "@openai/codex@latest"],
+ updateLockKey: "npm-global",
+ });
+}
+
+const baseProvider: ServerProvider = {
+ instanceId: CODEX_INSTANCE_ID,
+ driver: CODEX_DRIVER,
+ enabled: true,
+ installed: true,
+ version: null,
+ status: "ready",
+ auth: { status: "authenticated" },
+ checkedAt: "2026-04-10T00:00:00.000Z",
+ models: [],
+ slashCommands: [],
+ skills: [],
+};
+
+const baseCursorProvider: ServerProvider = {
+ ...baseProvider,
+ instanceId: CURSOR_INSTANCE_ID,
+ driver: CURSOR_DRIVER,
+};
+
+const baseOpenCodeProvider: ServerProvider = {
+ ...baseProvider,
+ instanceId: OPENCODE_INSTANCE_ID,
+ driver: OPENCODE_DRIVER,
+};
+
+const latestVersionHttpClient = (version: string) =>
+ Layer.succeed(
+ HttpClient.HttpClient,
+ HttpClient.make((request) =>
+ Effect.succeed(
+ HttpClientResponse.fromWeb(
+ request,
+ Response.json({ version }, { headers: { "content-type": "application/json" } }),
+ ),
+ ),
+ ),
+ );
+
+function mockHandle(result: {
+ readonly stdout?: string;
+ readonly stderr?: string;
+ readonly code?: number;
+ readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
+}) {
+ return ChildProcessSpawner.makeHandle({
+ pid: ChildProcessSpawner.ProcessId(1),
+ exitCode: result.exitCode ?? Effect.succeed(ChildProcessSpawner.ExitCode(result.code ?? 0)),
+ isRunning: Effect.succeed(false),
+ kill: () => Effect.void,
+ unref: Effect.succeed(Effect.void),
+ stdin: Sink.drain,
+ stdout: Stream.make(encoder.encode(result.stdout ?? "")),
+ stderr: Stream.make(encoder.encode(result.stderr ?? "")),
+ all: Stream.empty,
+ getInputFd: () => Sink.drain,
+ getOutputFd: () => Stream.empty,
+ });
+}
+
+function mockSpawnerLayer(
+ handler: (
+ command: string,
+ args: ReadonlyArray<string>,
+ ) => {
+ readonly stdout?: string;
+ readonly stderr?: string;
+ readonly code?: number;
+ readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
+ },
+) {
+ return Layer.succeed(
+ ChildProcessSpawner.ChildProcessSpawner,
+ ChildProcessSpawner.make((command) => {
+ const childProcess = command as unknown as {
+ readonly command: string;
+ readonly args: ReadonlyArray<string>;
+ };
+ return Effect.succeed(mockHandle(handler(childProcess.command, childProcess.args)));
+ }),
+ );
+}
+
+function makeRegistry(
+ initialProviders: ServerProvider | ReadonlyArray<ServerProvider> = baseProvider,
+) {
+ return Effect.gen(function* () {
+ const providersRef = yield* Ref.make<ReadonlyArray<ServerProvider>>(
+ Array.isArray(initialProviders) ? initialProviders : [initialProviders],
+ );
+ const updateStatesRef = yield* Ref.make<ReadonlyArray<ServerProviderUpdateState>>([]);
+
+ const setProviderMaintenanceActionState = Effect.fn(
+ "providerMaintenanceRunner.test.setProviderMaintenanceActionState",
+ )(function* (input: {
+ readonly instanceId: ProviderInstanceId;
+ readonly action: "update";
+ readonly state: ServerProviderUpdateState | null;
+ }) {
+ const updateState = input.state;
+ if (updateState) {
+ yield* Ref.update(updateStatesRef, (states) => [...states, updateState]);
+ }
+ return yield* Ref.updateAndGet(providersRef, (providers) =>
+ providers.map((candidate) => {
+ if (candidate.instanceId !== input.instanceId) {
+ return candidate;
+ }
+ if (!updateState) {
+ const { updateState: _updateState, ...providerWithoutUpdateState } = candidate;
+ return providerWithoutUpdateState;
+ }
+ return {
+ ...candidate,
+ updateState,
+ };
+ }),
+ );
+ });
+
+ const registry: ProviderRegistryShape = {
+ getProviders: Ref.get(providersRef),
+ refresh: () => Ref.get(providersRef),
+ refreshInstance: () => Ref.get(providersRef),
+ getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+ Effect.succeed(lifecycleFor(provider)),
+ setProviderMaintenanceActionState,
+ streamChanges: Stream.empty,
+ };
+
+ return {
+ registry,
+ updateStatesRef,
+ };
+ });
+}
+
+const makeTestRunner = (registry: ProviderRegistryShape) =>
+ Effect.service(ProviderMaintenanceRunner.ProviderMaintenanceRunner).pipe(
+ Effect.provide(
+ ProviderMaintenanceRunner.layer.pipe(
+ Layer.provide(Layer.succeed(ProviderRegistry, registry)),
+ ),
+ ),
+ );
+
+describe("providerMaintenanceRunner", () => {
+ it.effect("runs the allowlisted provider update command and records success", () => {
+ const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+ return Effect.gen(function* () {
+ const { registry, updateStatesRef } = yield* makeRegistry(baseCursorProvider);
+ const updater = yield* makeTestRunner(registry);
+
+ const result = yield* updater.updateProvider(CURSOR_DRIVER);
+ assert.deepStrictEqual(calls, [
+ {
+ command: "agent",
+ args: ["update"],
+ },
+ ]);
+ assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+ assert.deepStrictEqual(
+ (yield* Ref.get(updateStatesRef)).map((state) => state.status),
+ ["queued", "running", "succeeded"],
+ );
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.0.0"),
+ mockSpawnerLayer((command, args) => {
+ calls.push({ command, args });
+ return { stdout: "updated" };
+ }),
+ ),
+ ),
+ );
+ });
+
+ it.effect("uses the resolved provider capabilities when choosing the update executable", () => {
+ const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+ return Effect.gen(function* () {
+ const { registry } = yield* makeRegistry({
+ ...baseProvider,
+ versionAdvisory: {
+ status: "behind_latest",
+ currentVersion: "2.0.14",
+ latestVersion: "2.1.123",
+ updateCommand: "bun i -g @anthropic-ai/claude-code@latest",
+ canUpdate: true,
+ checkedAt: "2026-04-30T12:00:00.000Z",
+ message: "Update available.",
+ },
+ });
+ const updater = yield* makeTestRunner({
+ ...registry,
+ getProviderMaintenanceCapabilitiesForInstance: () =>
+ Effect.succeed(
+ makeProviderMaintenanceCapabilities({
+ provider: CODEX_DRIVER,
+ packageName: "@openai/codex",
+ updateExecutable: "bun",
+ updateArgs: ["i", "-g", "@openai/codex@latest"],
+ updateLockKey: "bun-global",
+ }),
+ ),
+ });
+
+ yield* updater.updateProvider(CODEX_DRIVER);
+ assert.deepStrictEqual(calls, [
+ {
+ command: "bun",
+ args: ["i", "-g", "@openai/codex@latest"],
+ },
+ ]);
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.0.0"),
+ mockSpawnerLayer((command, args) => {
+ calls.push({ command, args });
+ return { stdout: "updated" };
+ }),
+ ),
+ ),
+ );
+ });
+
+ it.effect(
+ "runs update commands through Effect ChildProcess when no test runner is injected",
+ () => {
+ const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+ return Effect.gen(function* () {
+ const { registry } = yield* makeRegistry(baseProvider);
+ const runner = yield* makeTestRunner(registry);
+
+ const result = yield* runner.updateProvider(CODEX_DRIVER);
+
+ assert.deepStrictEqual(calls, [
+ {
+ command: "npm",
+ args: ["install", "-g", "@openai/codex@latest"],
+ },
+ ]);
+ assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.0.0"),
+ mockSpawnerLayer((command, args) => {
+ calls.push({ command, args });
+ return { stdout: "updated" };
+ }),
+ ),
+ ),
+ );
+ },
+ );
+
+ it.effect("updates a single provider instance without touching sibling instances", () => {
+ const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+ return Effect.gen(function* () {
+ const personalInstanceId = ProviderInstanceId.make("codex_personal");
+ const workInstanceId = ProviderInstanceId.make("codex_work");
+ const refreshedInstanceIds: Array<ProviderInstanceId> = [];
+ const { registry } = yield* makeRegistry([
+ {
+ ...baseProvider,
+ instanceId: personalInstanceId,
+ version: "0.124.0-alpha.3",
+ },
+ {
+ ...baseProvider,
+ instanceId: workInstanceId,
+ version: "0.124.0-alpha.3",
+ },
+ ]);
+ const updater = yield* makeTestRunner({
+ ...registry,
+ getProviderMaintenanceCapabilitiesForInstance: (instanceId, provider) =>
+ Effect.succeed(
+ makeProviderMaintenanceCapabilities({
+ provider,
+ packageName: "@openai/codex-instance-test",
+ updateExecutable: "vp",
+ updateArgs: ["i", "-g", "@openai/codex"],
+ updateLockKey: "vite-plus-global",
+ }),
+ ).pipe(
+ Effect.tap(() => Effect.sync(() => assert.strictEqual(instanceId, personalInstanceId))),
+ ),
+ refreshInstance: (instanceId) =>
+ registry.refreshInstance(instanceId).pipe(
+ Effect.tap(() =>
+ Effect.sync(() => {
+ refreshedInstanceIds.push(instanceId);
+ }),
+ ),
+ ),
+ });
+
+ const result = yield* updater.updateProvider({
+ provider: CODEX_DRIVER,
+ instanceId: personalInstanceId,
+ });
+
+ assert.deepStrictEqual(calls, [
+ {
+ command: "vp",
+ args: ["i", "-g", "@openai/codex"],
+ },
+ ]);
+ assert.deepStrictEqual(refreshedInstanceIds, [personalInstanceId]);
+ assert.strictEqual(result.providers[0]?.instanceId, personalInstanceId);
+ assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+ assert.strictEqual(result.providers[1]?.instanceId, workInstanceId);
+ assert.strictEqual(result.providers[1]?.updateState, undefined);
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.124.0-alpha.3"),
+ mockSpawnerLayer((command, args) => {
+ calls.push({ command, args });
+ return { stdout: "updated" };
+ }),
+ ),
+ ),
+ );
+ });
+
+ it.effect("records command failure output in provider update state", () =>
+ Effect.gen(function* () {
+ const { registry } = yield* makeRegistry();
+ const updater = yield* makeTestRunner(registry);
+
+ const result = yield* updater.updateProvider(CODEX_DRIVER);
+ const updateState = result.providers[0]?.updateState;
+
+ assert.strictEqual(updateState?.status, "failed");
+ assert.strictEqual(updateState?.message, "Update command exited with code 1.");
+ assert.include(updateState?.output ?? "", "permission denied");
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.0.0"),
+ mockSpawnerLayer(() => ({ stderr: "permission denied", code: 1 })),
+ ),
+ ),
+ ),
+ );
+
+ it.effect(
+ "marks successful commands as unchanged when the refreshed provider is still outdated",
+ () =>
+ Effect.gen(function* () {
+ const { registry } = yield* makeRegistry({
+ ...baseProvider,
+ installed: true,
+ version: "0.1.0",
+ });
+ const updater = yield* makeTestRunner(registry);
+
+ const result = yield* updater.updateProvider(CODEX_DRIVER);
+
+ assert.strictEqual(result.providers[0]?.updateState?.status, "unchanged");
+ assert.include(result.providers[0]?.updateState?.message ?? "", "still detects");
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("9.9.9"),
+ mockSpawnerLayer(() => ({ stdout: "updated" })),
+ ),
+ ),
+ ),
+ );
+
+ it.effect("prevents concurrent updates for the same provider", () => {
+ const startedLatch: { resolve: () => void } = { resolve: () => {} };
+ const releaseLatch: { resolve: () => void } = { resolve: () => {} };
+ const started = new Promise<void>((resolve) => {
+ startedLatch.resolve = resolve;
+ });
+ const release = new Promise<void>((resolve) => {
+ releaseLatch.resolve = resolve;
+ });
+ return Effect.gen(function* () {
+ const { registry } = yield* makeRegistry();
+ const updater = yield* makeTestRunner(registry);
+
+ const first = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.forkScoped);
+ yield* Effect.promise(() => started);
+
+ const second = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.exit);
+ assert.strictEqual(Exit.isFailure(second), true);
+ if (Exit.isFailure(second)) {
+ const error = Cause.squash(second.cause);
+ assert.strictEqual(Schema.is(ServerProviderUpdateError)(error), true);
+ if (Schema.is(ServerProviderUpdateError)(error)) {
+ assert.include(error.reason, "already running");
+ }
+ }
+
+ releaseLatch.resolve();
+ yield* Fiber.join(first);
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.0.0"),
+ mockSpawnerLayer(() => {
+ startedLatch.resolve();
+ return {
+ stdout: "updated",
+ exitCode: Effect.promise(() => release).pipe(
+ Effect.as(ChildProcessSpawner.ExitCode(0)),
+ ),
+ };
+ }),
+ ),
+ ),
+ );
+ });
+
+ it.effect("serializes different providers that share the same update lock key", () => {
+ const firstStartedLatch: { resolve: () => void } = { resolve: () => {} };
+ const releaseFirstLatch: { resolve: () => void } = { resolve: () => {} };
+ const firstStarted = new Promise<void>((resolve) => {
+ firstStartedLatch.resolve = resolve;
+ });
+ const releaseFirst = new Promise<void>((resolve) => {
+ releaseFirstLatch.resolve = resolve;
+ });
+ const calls: Array<string> = [];
+ return Effect.gen(function* () {
+ const { registry } = yield* makeRegistry([baseProvider, baseOpenCodeProvider]);
+ const updater = yield* makeTestRunner({
+ ...registry,
+ getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+ Effect.succeed(
+ makeProviderMaintenanceCapabilities({
+ provider,
+ packageName: provider === OPENCODE_DRIVER ? "opencode-ai" : "@openai/codex",
+ updateExecutable: "npm",
+ updateArgs:
+ provider === OPENCODE_DRIVER
+ ? ["install", "-g", "opencode-ai@latest"]
+ : ["install", "-g", "@openai/codex@latest"],
+ updateLockKey: "npm-global",
+ }),
+ ),
+ });
+
+ const first = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.forkScoped);
+ yield* Effect.promise(() => firstStarted);
+
+ const second = yield* updater.updateProvider(OPENCODE_DRIVER).pipe(Effect.forkScoped);
+ let providersWhileQueued: ReadonlyArray<ServerProvider> = [];
+ for (let attempt = 0; attempt < 20; attempt += 1) {
+ providersWhileQueued = yield* registry.getProviders;
+ const queuedStatus = providersWhileQueued.find(
+ (provider) => provider.instanceId === OPENCODE_INSTANCE_ID,
+ )?.updateState?.status;
+ if (queuedStatus === "queued") {
+ break;
+ }
+ yield* Effect.yieldNow;
+ }
+ assert.deepStrictEqual(calls, ["install -g @openai/codex@latest"]);
+ assert.strictEqual(
+ providersWhileQueued.find((provider) => provider.instanceId === OPENCODE_INSTANCE_ID)
+ ?.updateState?.status,
+ "queued",
+ );
+
+ releaseFirstLatch.resolve();
+ yield* Fiber.join(first);
+ yield* Fiber.join(second);
+ assert.deepStrictEqual(calls, [
+ "install -g @openai/codex@latest",
+ "install -g opencode-ai@latest",
+ ]);
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.0.0"),
+ mockSpawnerLayer((_command, args) => {
+ calls.push(args.join(" "));
+ if (calls.length === 1) {
+ firstStartedLatch.resolve();
+ return {
+ stdout: "updated",
+ exitCode: Effect.promise(() => releaseFirst).pipe(
+ Effect.as(ChildProcessSpawner.ExitCode(0)),
+ ),
+ };
+ }
+ return { stdout: "updated" };
+ }),
+ ),
+ ),
+ );
+ });
+
+ it.effect("accepts arbitrary driver-provided update lock keys", () => {
+ const calls: Array<string> = [];
+ return Effect.gen(function* () {
+ const { registry } = yield* makeRegistry(baseProvider);
+ const updater = yield* makeTestRunner({
+ ...registry,
+ getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+ Effect.succeed(
+ makeProviderMaintenanceCapabilities({
+ provider,
+ packageName: "@openai/codex",
+ updateExecutable: "npm",
+ updateArgs: ["install", "-g", "@openai/codex@latest"],
+ updateLockKey: "unknown-lock-key",
+ }),
+ ),
+ });
+
+ const result = yield* updater.updateProvider(CODEX_DRIVER);
+ assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+ assert.deepStrictEqual(calls, ["install -g @openai/codex@latest"]);
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.0.0"),
+ mockSpawnerLayer((_command, args) => {
+ calls.push(args.join(" "));
+ return { stdout: "updated" };
+ }),
+ ),
+ ),
+ );
+ });
+
+ it.effect(
+ "releases the running-provider marker when interrupted after queuing but before the lock run starts",
+ () =>
+ Effect.gen(function* () {
+ const { registry } = yield* makeRegistry(baseProvider);
+ let blockQueuedState = true;
+ const queuedStateWrittenLatch: { resolve: () => void } = { resolve: () => {} };
+ const releaseQueuedStateLatch: { resolve: () => void } = { resolve: () => {} };
+ const queuedStateWritten = new Promise<void>((resolve) => {
+ queuedStateWrittenLatch.resolve = resolve;
+ });
+ const releaseQueuedState = new Promise<void>((resolve) => {
+ releaseQueuedStateLatch.resolve = resolve;
+ });
+
+ const updater = yield* makeTestRunner({
+ ...registry,
+ setProviderMaintenanceActionState: Effect.fn(
+ "providerMaintenanceRunner.test.blockQueuedState",
+ )(function* (input) {
+ const providers = yield* registry.setProviderMaintenanceActionState(input);
+ if (input.state?.status === "queued" && blockQueuedState) {
+ queuedStateWrittenLatch.resolve();
+ yield* Effect.promise(() => releaseQueuedState);
+ }
+ return providers;
+ }),
+ });
+
+ const first = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.forkScoped);
+ yield* Effect.promise(() => queuedStateWritten);
+ blockQueuedState = false;
+
+ yield* Fiber.interrupt(first);
+ releaseQueuedStateLatch.resolve();
+
+ const second = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.exit);
+ assert.strictEqual(Exit.isSuccess(second), true);
+ if (Exit.isSuccess(second)) {
+ assert.strictEqual(second.value.providers[0]?.updateState?.status, "succeeded");
+ }
+ }).pipe(
+ Effect.provide(
+ Layer.mergeAll(
+ latestVersionHttpClient("0.0.0"),
+ mockSpawnerLayer(() => ({ stdout: "updated" })),
+ ),
+ ),
+ ),
+ );
+});
diff --git a/apps/server/src/provider/providerMaintenanceRunner.ts b/apps/server/src/provider/providerMaintenanceRunner.ts
new file mode 100644
index 000000000..36657bac9
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenanceRunner.ts
@@ -0,0 +1,395 @@
+import {
+ defaultInstanceIdForDriver,
+ ProviderDriverKind,
+ ServerProviderUpdateError,
+ type ProviderInstanceId,
+ type ServerProvider,
+ type ServerProviderUpdatedPayload,
+ type ServerProviderUpdateState,
+} from "@t3tools/contracts";
+import { Cause, Context, DateTime, Duration, Effect, Layer, Option, Ref, Schema } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { ProviderRegistry } from "./Services/ProviderRegistry.ts";
+import { makeProviderMaintenanceCommandCoordinator } from "./providerMaintenanceCommandCoordinator.ts";
+import { enrichProviderSnapshotWithVersionAdvisory } from "./providerMaintenance.ts";
+import type { ProviderMaintenanceCapabilities } from "./providerMaintenance.ts";
+import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
+
+const UPDATE_TIMEOUT_MS = 5 * 60_000;
+const UPDATE_OUTPUT_MAX_BYTES = 10_000;
+
+export interface ProviderMaintenanceCommandResult {
+ readonly stdout: string;
+ readonly stderr: string;
+ readonly exitCode: number | null;
+ readonly timedOut: boolean;
+ readonly stdoutTruncated: boolean;
+ readonly stderrTruncated: boolean;
+}
+
+export interface ProviderMaintenanceRunnerShape {
+ readonly updateProvider: (
+ target:
+ | ProviderDriverKind
+ | {
+ readonly provider: ProviderDriverKind;
+ readonly instanceId?: ProviderInstanceId | undefined;
+ },
+ ) => Effect.Effect<ServerProviderUpdatedPayload, ServerProviderUpdateError>;
+}
+
+export class ProviderMaintenanceRunner extends Context.Service<
+ ProviderMaintenanceRunner,
+ ProviderMaintenanceRunnerShape
+>()("t3/provider/ProviderMaintenanceRunner") {}
+
+interface VerifiedProviderRefresh {
+ readonly providers: ReadonlyArray<ServerProvider>;
+ readonly verifiedProviders: ReadonlyArray<ServerProvider>;
+}
+
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+
+const runProviderMaintenanceCommandWithSpawner = Effect.fn("ProviderMaintenanceRunner.runCommand")(
+ function* (input: {
+ readonly spawner: ChildProcessSpawner.ChildProcessSpawner["Service"];
+ readonly command: string;
+ readonly args: ReadonlyArray<string>;
+ }) {
+ const collectCommandResult = Effect.fn("ProviderMaintenanceRunner.collectCommandResult")(
+ function* () {
+ const child = yield* input.spawner
+ .spawn(ChildProcess.make(input.command, [...input.args]))
+ .pipe(
+ Effect.mapError(
+ (cause) =>
+ new Error(`Failed to run update command ${input.command}: ${cause.message}`),
+ ),
+ );
+ yield* Effect.addFinalizer(() => child.kill().pipe(Effect.ignore));
+
+ const [stdout, stderr, exitCode] = yield* Effect.all(
+ [
+ collectUint8StreamText({
+ stream: child.stdout,
+ maxBytes: UPDATE_OUTPUT_MAX_BYTES,
+ }),
+ collectUint8StreamText({
+ stream: child.stderr,
+ maxBytes: UPDATE_OUTPUT_MAX_BYTES,
+ }),
+ child.exitCode,
+ ],
+ { concurrency: "unbounded" },
+ ).pipe(
+ Effect.mapError(
+ (cause) =>
+ new Error(cause instanceof Error ? cause.message : "Update command failed to run."),
+ ),
+ );
+
+ return {
+ stdout: stdout.text,
+ stderr: stderr.text,
+ exitCode: Number(exitCode),
+ timedOut: false,
+ stdoutTruncated: stdout.truncated,
+ stderrTruncated: stderr.truncated,
+ } satisfies ProviderMaintenanceCommandResult;
+ },
+ );
+
+ return yield* collectCommandResult().pipe(
+ Effect.scoped,
+ Effect.timeoutOption(Duration.millis(UPDATE_TIMEOUT_MS)),
+ Effect.map((result) =>
+ Option.match(result, {
+ onSome: (value) => value,
+ onNone: () =>
+ ({
+ stdout: "",
+ stderr: "",
+ exitCode: null,
+ timedOut: true,
+ stdoutTruncated: false,
+ stderrTruncated: false,
+ }) satisfies ProviderMaintenanceCommandResult,
+ }),
+ ),
+ );
+ },
+);
+
+function trimNullable(value: string): string | null {
+ const trimmed = value.trim();
+ return trimmed.length > 0 ? trimmed : null;
+}
+
+function truncateText(value: string, maxLength: number): string {
+ return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
+
+function commandOutput(result: ProviderMaintenanceCommandResult): string | null {
+ const output = trimNullable([result.stderr, result.stdout].filter(Boolean).join("\n\n"));
+ if (!output) {
+ return null;
+ }
+ return truncateText(output, UPDATE_OUTPUT_MAX_BYTES);
+}
+
+function failureMessage(result: ProviderMaintenanceCommandResult): string {
+ if (result.timedOut) {
+ return "Update timed out.";
+ }
+ if (result.exitCode !== null && result.exitCode !== 0) {
+ return `Update command exited with code ${result.exitCode}.`;
+ }
+ return "Update command failed.";
+}
+
+function isOutdatedProvider(provider: ServerProvider | undefined): boolean {
+ return provider?.versionAdvisory?.status === "behind_latest";
+}
+
+function makeUpdateState(input: {
+ readonly status: ServerProviderUpdateState["status"];
+ readonly startedAt: string | null;
+ readonly finishedAt: string | null;
+ readonly message: string | null;
+ readonly output?: string | null;
+}): ServerProviderUpdateState {
+ return {
+ status: input.status,
+ startedAt: input.startedAt,
+ finishedAt: input.finishedAt,
+ message: input.message,
+ output: input.output ?? null,
+ };
+}
+
+export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () {
+ const providerRegistry = yield* ProviderRegistry;
+ const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+ const httpClient = yield* HttpClient.HttpClient;
+ const runMaintenanceCommand = (command: string, args: ReadonlyArray<string>) =>
+ runProviderMaintenanceCommandWithSpawner({
+ spawner,
+ command,
+ args,
+ });
+ const commandCoordinator = yield* makeProviderMaintenanceCommandCoordinator({
+ makeAlreadyRunningError: () =>
+ new ServerProviderUpdateError({
+ provider: ProviderDriverKind.make("unknown"),
+ reason: "An update is already running for this provider.",
+ }),
+ });
+
+ const verifyRefreshedProvider = (
+ provider: ProviderDriverKind,
+ maintenanceCapabilities: ProviderMaintenanceCapabilities,
+ instanceId: ProviderInstanceId,
+ ): Effect.Effect<VerifiedProviderRefresh> =>
+ providerRegistry.getProviders.pipe(
+ Effect.map((providers) =>
+ providers
+ .filter(
+ (candidate) => candidate.driver === provider && candidate.instanceId === instanceId,
+ )
+ .map((candidate) => candidate.instanceId),
+ ),
+ Effect.flatMap((instanceIds) =>
+ instanceIds.length === 0
+ ? providerRegistry.refreshInstance(instanceId)
+ : Effect.forEach(
+ instanceIds,
+ (instanceId) => providerRegistry.refreshInstance(instanceId),
+ {
+ concurrency: "unbounded",
+ discard: true,
+ },
+ ).pipe(Effect.andThen(providerRegistry.getProviders)),
+ ),
+ Effect.flatMap((providers) => {
+ const refreshedProviders = providers.filter(
+ (candidate) => candidate.driver === provider && candidate.instanceId === instanceId,
+ );
+ if (refreshedProviders.length === 0) {
+ return Effect.succeed<VerifiedProviderRefresh>({
+ providers,
+ verifiedProviders: [],
+ });
+ }
+ return Effect.forEach(
+ refreshedProviders,
+ (refreshedProvider) =>
+ enrichProviderSnapshotWithVersionAdvisory(
+ refreshedProvider,
+ maintenanceCapabilities,
+ ).pipe(Effect.provideService(HttpClient.HttpClient, httpClient)),
+ {
+ concurrency: "unbounded",
+ },
+ ).pipe(
+ Effect.map(
+ (verifiedProviders): VerifiedProviderRefresh => ({
+ providers,
+ verifiedProviders,
+ }),
+ ),
+ Effect.catchCause((cause) =>
+ Effect.logWarning("Provider post-update version verification failed", {
+ provider,
+ cause: Cause.pretty(cause),
+ }).pipe(
+ Effect.as<VerifiedProviderRefresh>({
+ providers,
+ verifiedProviders: refreshedProviders,
+ }),
+ ),
+ ),
+ );
+ }),
+ );
+
+ const updateProvider: ProviderMaintenanceRunnerShape["updateProvider"] = Effect.fn(
+ "ProviderMaintenanceRunner.updateProvider",
+ )(function* (target) {
+ const provider = typeof target === "string" ? target : target.provider;
+ const instanceId =
+ typeof target === "string"
+ ? defaultInstanceIdForDriver(provider)
+ : (target.instanceId ?? defaultInstanceIdForDriver(provider));
+ const targetKey = `instance:${instanceId}`;
+ const capabilities = yield* providerRegistry.getProviderMaintenanceCapabilitiesForInstance(
+ instanceId,
+ provider,
+ );
+ const update = capabilities.update;
+ if (!update) {
+ return yield* new ServerProviderUpdateError({
+ provider,
+ reason: "This provider does not support one-click updates.",
+ });
+ }
+
+ const setUpdateState = (state: ServerProviderUpdateState | null) =>
+ providerRegistry.setProviderMaintenanceActionState({
+ instanceId,
+ action: "update",
+ state,
+ });
+ const setQueuedState = setUpdateState(
+ makeUpdateState({
+ status: "queued",
+ startedAt: null,
+ finishedAt: null,
+ message: "Waiting for another provider update to finish.",
+ }),
+ ).pipe(Effect.asVoid);
+
+ const runProviderUpdate = Effect.fn("ProviderMaintenanceRunner.runProviderUpdate")(
+ function* () {
+ const finish = (state: ServerProviderUpdateState) =>
+ setUpdateState(state).pipe(Effect.map((providers) => ({ providers })));
+ const startedAtRef = yield* Ref.make<string | null>(null);
+
+ const runCommandAndVerify = Effect.fn("ProviderMaintenanceRunner.runCommandAndVerify")(
+ function* () {
+ const startedAt = yield* nowIso;
+ yield* Ref.set(startedAtRef, startedAt);
+ yield* setUpdateState(
+ makeUpdateState({
+ status: "running",
+ startedAt,
+ finishedAt: null,
+ message: "Updating provider.",
+ }),
+ );
+
+ const result = yield* runMaintenanceCommand(update.executable, update.args);
+ const finishedAt = yield* nowIso;
+ if (result.timedOut || result.exitCode !== 0) {
+ return yield* finish(
+ makeUpdateState({
+ status: "failed",
+ startedAt,
+ finishedAt,
+ message: failureMessage(result),
+ output: commandOutput(result),
+ }),
+ );
+ }
+
+ const { verifiedProviders } = yield* verifyRefreshedProvider(
+ provider,
+ capabilities,
+ instanceId,
+ );
+ const couldNotVerify = verifiedProviders.length === 0;
+ const stillOutdated =
+ couldNotVerify ||
+ verifiedProviders.some((verifiedProvider) => isOutdatedProvider(verifiedProvider));
+ return yield* finish(
+ makeUpdateState({
+ status: stillOutdated ? "unchanged" : "succeeded",
+ startedAt,
+ finishedAt,
+ message: couldNotVerify
+ ? "Update command completed, but T3 Code could not verify the provider version."
+ : stillOutdated
+ ? "Update command completed, but T3 Code still detects an outdated provider version."
+ : "Provider updated.",
+ output: commandOutput(result),
+ }),
+ );
+ },
+ );
+
+ const recordFailedUpdate = Effect.fn("ProviderMaintenanceRunner.recordFailedUpdate")(
+ function* (cause: Cause.Cause<unknown>) {
+ const failure = Cause.squash(cause);
+ const startedAt = yield* Ref.get(startedAtRef);
+ return yield* finish(
+ makeUpdateState({
+ status: "failed",
+ startedAt,
+ finishedAt: yield* nowIso,
+ message: failure instanceof Error ? failure.message : "Update command failed.",
+ output: null,
+ }),
+ );
+ },
+ );
+
+ return yield* runCommandAndVerify().pipe(Effect.catchCause(recordFailedUpdate));
+ },
+ );
+
+ return yield* commandCoordinator
+ .withCommandLock({
+ targetKey,
+ lockKey: update.lockKey,
+ onQueued: setQueuedState,
+ run: runProviderUpdate(),
+ })
+ .pipe(
+ Effect.mapError((error) =>
+ Schema.is(ServerProviderUpdateError)(error)
+ ? new ServerProviderUpdateError({
+ provider,
+ reason: error.reason,
+ })
+ : error,
+ ),
+ );
+ });
+
+ return ProviderMaintenanceRunner.of({
+ updateProvider,
+ });
+});
+
+export const layer = Layer.effect(ProviderMaintenanceRunner, make());
diff --git a/apps/server/src/provider/providerSnapshot.ts b/apps/server/src/provider/providerSnapshot.ts
index af0c91274..ce9eb950f 100644
--- a/apps/server/src/provider/providerSnapshot.ts
+++ b/apps/server/src/provider/providerSnapshot.ts
@@ -12,6 +12,8 @@ import { Effect, Stream } from "effect";
import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
import { normalizeModelSlug } from "@t3tools/shared/model";
import { isWindowsCommandNotFound } from "../processRunner.ts";
+import { createProviderVersionAdvisory } from "./providerMaintenance.ts";
+import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
export const DEFAULT_TIMEOUT_MS = 4_000;
// Auth status checks involve disk/network lookups and can be slow on first run (especially Windows)
@@ -182,6 +184,7 @@ export function buildBooleanOptionDescriptor(input: {
}
export function buildServerProvider(input: {
+ driver?: ProviderDriverKind;
presentation: ServerProviderPresentation;
enabled: boolean;
checkedAt: string;
@@ -190,6 +193,13 @@ export function buildServerProvider(input: {
skills?: ReadonlyArray<ServerProviderSkill>;
probe: ProviderProbeResult;
}): ServerProviderDraft {
+ const versionAdvisory = input.driver
+ ? createProviderVersionAdvisory({
+ driver: input.driver,
+ currentVersion: input.probe.version,
+ checkedAt: input.checkedAt,
+ })
+ : undefined;
return {
displayName: input.presentation.displayName,
...(input.presentation.badgeLabel ? { badgeLabel: input.presentation.badgeLabel } : {}),
@@ -206,16 +216,11 @@ export function buildServerProvider(input: {
models: input.models,
slashCommands: [...(input.slashCommands ?? [])],
skills: [...(input.skills ?? [])],
+ ...(versionAdvisory ? { versionAdvisory } : {}),
};
}
export const collectStreamAsString = <E>(
stream: Stream.Stream<Uint8Array, E>,
): Effect.Effect<string, E> =>
- stream.pipe(
- Stream.decodeText(),
- Stream.runFold(
- () => "",
- (acc, chunk) => acc + chunk,
- ),
- );
+ collectUint8StreamText({ stream }).pipe(Effect.map((collected) => collected.text));
diff --git a/apps/server/src/provider/providerStatusCache.ts b/apps/server/src/provider/providerStatusCache.ts
index d6c051fd5..db6c358c9 100644
--- a/apps/server/src/provider/providerStatusCache.ts
+++ b/apps/server/src/provider/providerStatusCache.ts
@@ -140,8 +140,10 @@ export const readProviderStatusCache = (filePath: string) =>
export const writeProviderStatusCache = (input: {
readonly filePath: string;
readonly provider: ServerProvider;
-}) =>
- writeFileStringAtomically({
+}) => {
+ const { updateState: _updateState, ...cacheableProvider } = input.provider;
+ return writeFileStringAtomically({
filePath: input.filePath,
- contents: `${JSON.stringify(input.provider, null, 2)}\n`,
+ contents: `${JSON.stringify(cacheableProvider, null, 2)}\n`,
});
+};
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index 65cb638f7..195667693 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -80,6 +80,7 @@ import {
ProviderRegistry,
type ProviderRegistryShape,
} from "./provider/Services/ProviderRegistry.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "./provider/providerMaintenance.ts";
import { ServerLifecycleEvents, type ServerLifecycleEventsShape } from "./serverLifecycleEvents.ts";
import { ServerRuntimeStartup, type ServerRuntimeStartupShape } from "./serverRuntimeStartup.ts";
import { ServerSettingsService, type ServerSettingsShape } from "./serverSettings.ts";
@@ -517,6 +518,12 @@ const buildAppUnderTest = (options?: {
Layer.mock(ProviderRegistry)({
getProviders: Effect.succeed([]),
refresh: () => Effect.succeed([]),
+ refreshInstance: () => Effect.succeed([]),
+ getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+ Effect.succeed(
+ makeManualOnlyProviderMaintenanceCapabilities({ provider, packageName: null }),
+ ),
+ setProviderMaintenanceActionState: () => Effect.succeed([]),
streamChanges: Stream.empty,
...options?.layers?.providerRegistry,
}),
diff --git a/apps/server/src/stream/collectUint8StreamText.test.ts b/apps/server/src/stream/collectUint8StreamText.test.ts
new file mode 100644
index 000000000..727d14dd0
--- /dev/null
+++ b/apps/server/src/stream/collectUint8StreamText.test.ts
@@ -0,0 +1,38 @@
+import { assert, describe, it } from "@effect/vitest";
+import { Effect, Stream } from "effect";
+
+import { collectUint8StreamText } from "./collectUint8StreamText.ts";
+
+const encoder = new TextEncoder();
+
+describe("collectUint8StreamText", () => {
+ it.effect("collects Uint8Array chunks into decoded text", () =>
+ Effect.gen(function* () {
+ const result = yield* collectUint8StreamText({
+ stream: Stream.make(encoder.encode("hello "), encoder.encode("world")),
+ });
+
+ assert.deepStrictEqual(result, {
+ text: "hello world",
+ bytes: 11,
+ truncated: false,
+ });
+ }),
+ );
+
+ it.effect("truncates by bytes and appends an optional marker once", () =>
+ Effect.gen(function* () {
+ const result = yield* collectUint8StreamText({
+ stream: Stream.make(encoder.encode("abcdef"), encoder.encode("ghij")),
+ maxBytes: 5,
+ truncatedMarker: "[truncated]",
+ });
+
+ assert.deepStrictEqual(result, {
+ text: "abcde[truncated]",
+ bytes: 5,
+ truncated: true,
+ });
+ }),
+ );
+});
diff --git a/apps/server/src/stream/collectUint8StreamText.ts b/apps/server/src/stream/collectUint8StreamText.ts
new file mode 100644
index 000000000..88f654908
--- /dev/null
+++ b/apps/server/src/stream/collectUint8StreamText.ts
@@ -0,0 +1,66 @@
+import { Effect, Stream } from "effect";
+
+export interface CollectedUint8StreamText {
+ readonly text: string;
+ readonly truncated: boolean;
+ readonly bytes: number;
+}
+
+interface CollectState {
+ readonly text: string;
+ readonly bytes: number;
+ readonly truncated: boolean;
+}
+
+export const collectUint8StreamText = <E>(input: {
+ readonly stream: Stream.Stream<Uint8Array, E>;
+ readonly maxBytes?: number | undefined;
+ readonly truncatedMarker?: string | null | undefined;
+}): Effect.Effect<CollectedUint8StreamText, E> => {
+ const decoder = new TextDecoder();
+ const maxBytes = input.maxBytes ?? Number.POSITIVE_INFINITY;
+ const truncatedMarker = input.truncatedMarker ?? "";
+
+ return input.stream.pipe(
+ Stream.runFold(
+ (): CollectState => ({
+ text: "",
+ bytes: 0,
+ truncated: false,
+ }),
+ (state, chunk): CollectState => {
+ if (state.truncated) {
+ return state;
+ }
+
+ const remainingBytes = maxBytes - state.bytes;
+ if (remainingBytes <= 0) {
+ return {
+ ...state,
+ text: `${state.text}${truncatedMarker}`,
+ truncated: true,
+ };
+ }
+
+ const nextChunk =
+ chunk.byteLength > remainingBytes ? chunk.slice(0, remainingBytes) : chunk;
+ const text = `${state.text}${decoder.decode(nextChunk, { stream: true })}`;
+ const bytes = state.bytes + nextChunk.byteLength;
+ const truncated = chunk.byteLength > remainingBytes;
+
+ return {
+ text: truncated ? `${text}${truncatedMarker}` : text,
+ bytes,
+ truncated,
+ };
+ },
+ ),
+ Effect.map(
+ (state): CollectedUint8StreamText => ({
+ text: state.truncated ? state.text : `${state.text}${decoder.decode()}`,
+ bytes: state.bytes,
+ truncated: state.truncated,
+ }),
+ ),
+ );
+};
diff --git a/apps/server/src/vcs/VcsProcess.ts b/apps/server/src/vcs/VcsProcess.ts
index 33e03a255..639621cee 100644
--- a/apps/server/src/vcs/VcsProcess.ts
+++ b/apps/server/src/vcs/VcsProcess.ts
@@ -8,6 +8,7 @@ import {
VcsProcessSpawnError,
VcsProcessTimeoutError,
} from "@t3tools/contracts";
+import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
export interface VcsProcessInput {
readonly operation: string;
@@ -86,44 +87,12 @@ export const collectText = Effect.fn("VcsProcess.collectText")(function* (input:
readonly maxOutputBytes?: number;
readonly truncateOutputAtMaxBytes?: boolean;
}) {
- const decoder = new TextDecoder();
- let text = "";
- let bytes = 0;
- let truncated = false;
const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
- const truncateOutputAtMaxBytes = input.truncateOutputAtMaxBytes ?? false;
-
- yield* Stream.runForEach(input.stream, (chunk) =>
- Effect.sync(() => {
- if (truncated) return;
-
- const remainingBytes = maxOutputBytes - bytes;
- if (remainingBytes <= 0) {
- truncated = true;
- if (truncateOutputAtMaxBytes) {
- text += OUTPUT_TRUNCATED_MARKER;
- }
- return;
- }
-
- const nextChunk = chunk.byteLength > remainingBytes ? chunk.slice(0, remainingBytes) : chunk;
- text += decoder.decode(nextChunk, { stream: true });
- bytes += nextChunk.byteLength;
-
- if (chunk.byteLength > remainingBytes) {
- truncated = true;
- if (truncateOutputAtMaxBytes) {
- text += OUTPUT_TRUNCATED_MARKER;
- }
- }
- }),
- );
-
- if (!truncated) {
- text += decoder.decode();
- }
-
- return { text, truncated } satisfies VcsProcessCollectedText;
+ return yield* collectUint8StreamText({
+ stream: input.stream,
+ maxBytes: maxOutputBytes,
+ truncatedMarker: input.truncateOutputAtMaxBytes ? OUTPUT_TRUNCATED_MARKER : null,
+ });
});
export const make = Effect.fn("makeVcsProcess")(function* () {
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 592097b6d..f25392268 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -40,6 +40,7 @@ import {
observeRpcStreamEffect,
} from "./observability/RpcInstrumentation.ts";
import { ProviderRegistry } from "./provider/Services/ProviderRegistry.ts";
+import * as ProviderMaintenanceRunner from "./provider/providerMaintenanceRunner.ts";
import { ServerLifecycleEvents } from "./serverLifecycleEvents.ts";
import { ServerRuntimeStartup } from "./serverRuntimeStartup.ts";
import { redactServerSettingsForClient, ServerSettingsService } from "./serverSettings.ts";
@@ -152,6 +153,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
const vcsStatusBroadcaster = yield* VcsStatusBroadcaster;
const terminalManager = yield* TerminalManager;
const providerRegistry = yield* ProviderRegistry;
+ const providerMaintenanceRunner = yield* ProviderMaintenanceRunner.ProviderMaintenanceRunner;
const config = yield* ServerConfig;
const lifecycleEvents = yield* ServerLifecycleEvents;
const serverSettings = yield* ServerSettingsService;
@@ -785,6 +787,14 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
).pipe(Effect.map((providers) => ({ providers }))),
{ "rpc.aggregate": "server" },
),
+ [WS_METHODS.serverUpdateProvider]: (input) =>
+ observeRpcEffect(
+ WS_METHODS.serverUpdateProvider,
+ providerMaintenanceRunner.updateProvider(input),
+ {
+ "rpc.aggregate": "server",
+ },
+ ),
[WS_METHODS.serverUpsertKeybinding]: (rule) =>
observeRpcEffect(
WS_METHODS.serverUpsertKeybinding,
@@ -1152,6 +1162,7 @@ export const websocketRpcRouteLayer = Layer.unwrap(
Effect.provide(
makeWsRpcLayer(session.sessionId).pipe(
Layer.provideMerge(RpcSerialization.layerJson),
+ Layer.provide(ProviderMaintenanceRunner.layer),
Layer.provide(
SourceControlDiscoveryLayer.layer.pipe(
Layer.provide(
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
new file mode 100644
index 000000000..defb6eb20
--- /dev/null
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
@@ -0,0 +1,673 @@
+import { describe, expect, it } from "vitest";
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+
+import {
+ canOneClickUpdateProviderCandidate,
+ collectProviderUpdateCandidates,
+ collectUpdatedProviderSnapshots,
+ firstRejectedProviderUpdateMessage,
+ getProviderUpdateInitialToastView,
+ getProviderUpdateProgressToastView,
+ getProviderUpdateRejectedToastView,
+ getProviderUpdateSidebarPillView,
+ getSingleProviderUpdateProgressToastView,
+ hasOneClickUpdateProviderCandidate,
+ isProviderUpdateCandidate,
+ providerUpdateNotificationKey,
+ type ProviderUpdateCandidate,
+} from "./ProviderUpdateLaunchNotification.logic";
+
+const checkedAt = "2026-04-23T10:00:00.000Z";
+const sessionStartedAt = "2026-04-23T09:59:00.000Z";
+const laterCheckedAt = "2026-04-23T10:01:00.000Z";
+
+const driver = (value: string) => ProviderDriverKind.make(value);
+const instanceId = (value: string) => ProviderInstanceId.make(value);
+
+function provider(input: {
+ readonly driver: ReturnType<typeof ProviderDriverKind.make>;
+ readonly instanceId?: ReturnType<typeof ProviderInstanceId.make>;
+ readonly enabled?: boolean;
+ readonly version?: string | null;
+ readonly latestVersion?: string | null;
+ readonly canUpdate?: boolean;
+ readonly updateCommand?: string | null;
+ readonly updateState?: ServerProvider["updateState"];
+ readonly advisoryStatus?: NonNullable<ServerProvider["versionAdvisory"]>["status"];
+}): ServerProvider {
+ const result: ServerProvider = {
+ instanceId: input.instanceId ?? instanceId(String(input.driver)),
+ driver: input.driver,
+ enabled: input.enabled ?? true,
+ installed: true,
+ version: input.version ?? "1.0.0",
+ status: "ready",
+ auth: { status: "authenticated" },
+ checkedAt,
+ models: [],
+ slashCommands: [],
+ skills: [],
+ versionAdvisory: {
+ status: input.advisoryStatus ?? "behind_latest",
+ currentVersion: input.version ?? "1.0.0",
+ latestVersion: "latestVersion" in input ? input.latestVersion : "1.1.0",
+ updateCommand: "updateCommand" in input ? input.updateCommand : "npm install -g provider",
+ canUpdate: input.canUpdate ?? true,
+ checkedAt,
+ message: "Update available.",
+ },
+ };
+
+ if (input.updateState) {
+ return { ...result, updateState: input.updateState };
+ }
+
+ return result;
+}
+
+function updateCandidate(input: Parameters<typeof provider>[0]): ProviderUpdateCandidate {
+ return provider(input) as ProviderUpdateCandidate;
+}
+
+describe("provider update launch notification logic", () => {
+ it("detects enabled providers with a latest-version advisory", () => {
+ expect(isProviderUpdateCandidate(provider({ driver: driver("codex") }))).toBe(true);
+ expect(isProviderUpdateCandidate(provider({ driver: driver("codex"), enabled: false }))).toBe(
+ false,
+ );
+ expect(
+ isProviderUpdateCandidate(
+ provider({ driver: driver("codex"), advisoryStatus: "current", latestVersion: null }),
+ ),
+ ).toBe(false);
+ expect(
+ isProviderUpdateCandidate(provider({ driver: driver("codex"), latestVersion: null })),
+ ).toBe(false);
+ });
+
+ it("deduplicates multi-instance provider candidates by driver", () => {
+ expect(
+ collectProviderUpdateCandidates([
+ provider({
+ driver: driver("codex"),
+ instanceId: instanceId("codex_personal"),
+ latestVersion: "1.1.0",
+ }),
+ provider({
+ driver: driver("codex"),
+ instanceId: instanceId("codex"),
+ latestVersion: "1.1.0",
+ }),
+ provider({ driver: driver("cursor"), latestVersion: "0.3.0" }),
+ ]),
+ ).toHaveLength(2);
+ });
+
+ it("disables one-click updates when provider instances disagree on the update command", () => {
+ const candidate = updateCandidate({
+ driver: driver("claudeAgent"),
+ instanceId: instanceId("claude_personal"),
+ latestVersion: "2.1.123",
+ });
+
+ expect(
+ canOneClickUpdateProviderCandidate(candidate, [
+ candidate,
+ provider({
+ driver: driver("claudeAgent"),
+ instanceId: instanceId("claude_work"),
+ latestVersion: "2.1.123",
+ canUpdate: true,
+ updateCommand: "bun add -g @anthropic-ai/claude-code@latest",
+ }),
+ ]),
+ ).toBe(false);
+ });
+
+ it("keeps one-click updates enabled when sibling instances are already current", () => {
+ const candidate = updateCandidate({
+ driver: driver("claudeAgent"),
+ instanceId: instanceId("claude_personal"),
+ latestVersion: "2.1.123",
+ updateCommand: "npm install -g @anthropic-ai/claude-code@latest",
+ });
+
+ expect(
+ hasOneClickUpdateProviderCandidate(candidate, [
+ candidate,
+ provider({
+ driver: driver("claudeAgent"),
+ instanceId: instanceId("claude_work"),
+ version: "2.1.123",
+ latestVersion: "2.1.123",
+ advisoryStatus: "current",
+ canUpdate: false,
+ updateCommand: null,
+ }),
+ ]),
+ ).toBe(true);
+ expect(
+ canOneClickUpdateProviderCandidate(candidate, [
+ candidate,
+ provider({
+ driver: driver("claudeAgent"),
+ instanceId: instanceId("claude_work"),
+ version: "2.1.123",
+ latestVersion: "2.1.123",
+ advisoryStatus: "current",
+ canUpdate: false,
+ updateCommand: null,
+ }),
+ ]),
+ ).toBe(true);
+ });
+
+ it("keeps the inline update action available while a provider update is already running", () => {
+ const candidate = updateCandidate({
+ driver: driver("codex"),
+ updateState: {
+ status: "running",
+ startedAt: checkedAt,
+ finishedAt: null,
+ message: "Updating provider.",
+ output: null,
+ },
+ });
+
+ expect(hasOneClickUpdateProviderCandidate(candidate, [candidate])).toBe(true);
+ expect(canOneClickUpdateProviderCandidate(candidate, [candidate])).toBe(false);
+ });
+
+ it("builds a notification key from provider latest versions", () => {
+ const codex = updateCandidate({
+ driver: driver("codex"),
+ version: "1.0.0",
+ latestVersion: "1.1.0",
+ });
+ const cursor = updateCandidate({
+ driver: driver("cursor"),
+ version: "0.2.0",
+ latestVersion: "0.3.0",
+ });
+
+ expect(providerUpdateNotificationKey([codex, cursor])).toBe("codex:1.1.0|cursor:0.3.0");
+ expect(providerUpdateNotificationKey([])).toBeNull();
+ });
+
+ it("keeps the same notification key while the published update version is unchanged", () => {
+ const first = updateCandidate({
+ driver: driver("codex"),
+ version: "1.0.0",
+ latestVersion: "1.2.0",
+ });
+ const second = updateCandidate({
+ driver: driver("codex"),
+ version: "1.1.0",
+ latestVersion: "1.2.0",
+ });
+ const nextPublishedVersion = updateCandidate({
+ driver: driver("codex"),
+ version: "1.1.0",
+ latestVersion: "1.3.0",
+ });
+
+ expect(providerUpdateNotificationKey([first])).toBe(providerUpdateNotificationKey([second]));
+ expect(providerUpdateNotificationKey([nextPublishedVersion])).not.toBe(
+ providerUpdateNotificationKey([first]),
+ );
+ });
+
+ it("tracks updated provider snapshots by instance instead of collapsing to a sibling driver", () => {
+ const targetInstanceId = instanceId("codex_personal");
+ const siblingInstanceId = instanceId("codex");
+ const updatedPersonal = provider({
+ driver: driver("codex"),
+ instanceId: targetInstanceId,
+ version: "1.1.0",
+ latestVersion: "1.1.0",
+ advisoryStatus: "current",
+ updateState: {
+ status: "succeeded",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "Provider updated.",
+ output: null,
+ },
+ });
+ const currentDefaultSibling = provider({
+ driver: driver("codex"),
+ instanceId: siblingInstanceId,
+ version: "1.1.0",
+ latestVersion: "1.1.0",
+ advisoryStatus: "current",
+ updateState: undefined,
+ });
+
+ expect(
+ collectUpdatedProviderSnapshots({
+ results: [
+ {
+ status: "fulfilled",
+ value: {
+ providers: [updatedPersonal, currentDefaultSibling],
+ },
+ },
+ ],
+ providerInstanceIds: new Set([targetInstanceId]),
+ }),
+ ).toEqual([updatedPersonal]);
+ });
+
+ it("describes a single one-click update", () => {
+ const view = getProviderUpdateInitialToastView({
+ updateProviders: [updateCandidate({ driver: driver("codex"), latestVersion: "1.1.0" })],
+ oneClickProviders: [updateCandidate({ driver: driver("codex"), latestVersion: "1.1.0" })],
+ });
+
+ expect(view).toMatchObject({
+ phase: "initial",
+ type: "warning",
+ title: "Update Available: Codex v1.1.0",
+ description: "Install the update now or review provider settings.",
+ });
+ });
+
+ it("describes settings-only updates without one-click support", () => {
+ const view = getProviderUpdateInitialToastView({
+ updateProviders: [
+ updateCandidate({ driver: driver("codex"), canUpdate: false }),
+ updateCandidate({ driver: driver("cursor"), canUpdate: false }),
+ ],
+ oneClickProviders: [],
+ });
+
+ expect(view.description).toBe("Codex and Cursor can be updated from provider settings.");
+ });
+
+ it("uses server update state for running progress", () => {
+ const view = getProviderUpdateProgressToastView({
+ providers: [
+ provider({
+ driver: driver("codex"),
+ updateState: {
+ status: "running",
+ startedAt: checkedAt,
+ finishedAt: null,
+ message: "Updating provider.",
+ output: null,
+ },
+ }),
+ ],
+ providerCount: 1,
+ });
+
+ expect(view).toMatchObject({
+ phase: "running",
+ type: "loading",
+ title: "Updating provider",
+ });
+ });
+
+ it("uses server failure state for failed progress", () => {
+ const view = getProviderUpdateProgressToastView({
+ providers: [
+ provider({
+ driver: driver("codex"),
+ updateState: {
+ status: "failed",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "command failed",
+ output: "stderr",
+ },
+ }),
+ ],
+ providerCount: 1,
+ });
+
+ expect(view).toMatchObject({
+ phase: "failed",
+ type: "error",
+ title: "Provider update failed",
+ description: "command failed",
+ });
+ });
+
+ it("resolves a single-provider completion view from the returned provider snapshot", () => {
+ const view = getSingleProviderUpdateProgressToastView(
+ provider({
+ driver: driver("codex"),
+ updateState: {
+ status: "failed",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "command failed",
+ output: "stderr",
+ },
+ }),
+ );
+
+ expect(view).toMatchObject({
+ phase: "failed",
+ type: "error",
+ title: "Codex v1.1.0 update failed",
+ description: "command failed",
+ });
+ });
+
+ it("keeps unchanged providers actionable from settings", () => {
+ const view = getProviderUpdateProgressToastView({
+ providers: [
+ provider({
+ driver: driver("cursor"),
+ updateState: {
+ status: "unchanged",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "still old",
+ output: null,
+ },
+ }),
+ ],
+ providerCount: 1,
+ });
+
+ expect(view).toMatchObject({
+ phase: "unchanged",
+ type: "warning",
+ title: "Provider still needs an update",
+ description: "Cursor still appears outdated. Check provider settings for details.",
+ });
+ });
+
+ it("marks progress succeeded once every attempted provider is no longer outdated", () => {
+ const view = getProviderUpdateProgressToastView({
+ providers: [
+ provider({
+ driver: driver("codex"),
+ version: "1.1.0",
+ latestVersion: "1.1.0",
+ advisoryStatus: "current",
+ updateState: {
+ status: "succeeded",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "Provider updated.",
+ output: null,
+ },
+ }),
+ ],
+ providerCount: 1,
+ });
+
+ expect(view).toMatchObject({
+ phase: "succeeded",
+ type: "success",
+ title: "Provider updated",
+ description: "New sessions will use the updated provider.",
+ dismissAfterVisibleMs: 3_000,
+ });
+ });
+
+ it("uses the updated version in the single-provider success toast title", () => {
+ const view = getSingleProviderUpdateProgressToastView(
+ provider({
+ driver: driver("codex"),
+ version: "1.1.0",
+ latestVersion: "1.1.0",
+ advisoryStatus: "current",
+ updateState: {
+ status: "succeeded",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "Provider updated.",
+ output: null,
+ },
+ }),
+ );
+
+ expect(view).toMatchObject({
+ phase: "succeeded",
+ type: "success",
+ title: "Codex updated: v1.1.0",
+ description: "New sessions will use the updated provider.",
+ });
+ });
+
+ it("falls back to a rejected RPC message for transport-level failures", () => {
+ const results: PromiseSettledResult<unknown>[] = [
+ { status: "rejected", reason: new Error("WebSocket closed") },
+ ];
+
+ expect(firstRejectedProviderUpdateMessage(results)).toBe("WebSocket closed");
+ expect(getProviderUpdateRejectedToastView(2, "WebSocket closed")).toMatchObject({
+ phase: "failed",
+ title: "Provider updates failed",
+ description: "WebSocket closed",
+ });
+ });
+
+ it("collects only attempted provider snapshots from update responses", () => {
+ const codex = provider({ driver: driver("codex") });
+ const cursor = provider({ driver: driver("cursor") });
+ const results: PromiseSettledResult<{ readonly providers: ReadonlyArray<ServerProvider> }>[] = [
+ { status: "fulfilled", value: { providers: [codex, cursor] } },
+ ];
+
+ expect(
+ collectUpdatedProviderSnapshots({
+ results,
+ providerInstanceIds: new Set([cursor.instanceId]),
+ }),
+ ).toEqual([cursor]);
+ });
+
+ it("summarizes active provider updates for the sidebar pill", () => {
+ const view = getProviderUpdateSidebarPillView([
+ provider({
+ driver: driver("codex"),
+ updateState: {
+ status: "running",
+ startedAt: checkedAt,
+ finishedAt: null,
+ message: "Updating provider.",
+ output: null,
+ },
+ }),
+ provider({
+ driver: driver("cursor"),
+ updateState: {
+ status: "queued",
+ startedAt: null,
+ finishedAt: null,
+ message: "Waiting for another provider update to finish.",
+ output: null,
+ },
+ }),
+ ]);
+
+ expect(view).toMatchObject({
+ tone: "loading",
+ title: "Updating 2 providers",
+ description: "Codex and Cursor updates are in progress.",
+ });
+ });
+
+ it("uses the provider name for single active sidebar pill updates", () => {
+ const view = getProviderUpdateSidebarPillView([
+ provider({
+ driver: driver("codex"),
+ updateState: {
+ status: "running",
+ startedAt: checkedAt,
+ finishedAt: null,
+ message: "Updating provider.",
+ output: null,
+ },
+ }),
+ ]);
+
+ expect(view).toMatchObject({
+ key: "loading:codex:running",
+ tone: "loading",
+ title: "Updating Codex",
+ description: "Codex update in progress.",
+ });
+ });
+
+ it("uses the provider name for single failed sidebar pill updates", () => {
+ const view = getProviderUpdateSidebarPillView(
+ [
+ provider({
+ driver: driver("claudeAgent"),
+ updateState: {
+ status: "failed",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "Update command exited with code 1.",
+ output: null,
+ },
+ }),
+ ],
+ { visibleAfterIso: sessionStartedAt },
+ );
+
+ expect(view).toMatchObject({
+ key: "failed:claudeAgent:2026-04-23T10:00:00.000Z:Update command exited with code 1.",
+ tone: "error",
+ title: "Claude v1.1.0 update failed",
+ description: "Update command exited with code 1.",
+ dismissible: true,
+ });
+ });
+
+ it("shows a short-lived success sidebar pill after a single provider update succeeds", () => {
+ const view = getProviderUpdateSidebarPillView(
+ [
+ provider({
+ driver: driver("codex"),
+ version: "1.1.0",
+ latestVersion: "1.1.0",
+ advisoryStatus: "current",
+ updateState: {
+ status: "succeeded",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "Provider updated.",
+ output: null,
+ },
+ }),
+ ],
+ { visibleAfterIso: sessionStartedAt },
+ );
+
+ expect(view).toMatchObject({
+ key: "succeeded:codex:2026-04-23T10:00:00.000Z:Provider updated.",
+ tone: "success",
+ title: "Codex updated: v1.1.0",
+ description: "New sessions will use the updated provider.",
+ dismissAfterVisibleMs: 3_000,
+ });
+ });
+
+ it("keeps unchanged sidebar pill states dismissible", () => {
+ const view = getProviderUpdateSidebarPillView(
+ [
+ provider({
+ driver: driver("cursor"),
+ updateState: {
+ status: "unchanged",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "still old",
+ output: null,
+ },
+ }),
+ ],
+ { visibleAfterIso: sessionStartedAt },
+ );
+
+ expect(view).toMatchObject({
+ key: "unchanged:cursor:2026-04-23T10:00:00.000Z:still old",
+ tone: "warning",
+ title: "Cursor still needs an update",
+ dismissible: true,
+ });
+ });
+
+ it("does not show sidebar terminal states from before the current app session", () => {
+ expect(
+ getProviderUpdateSidebarPillView(
+ [
+ provider({
+ driver: driver("codex"),
+ updateState: {
+ status: "failed",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "command failed",
+ output: "stderr",
+ },
+ }),
+ ],
+ { visibleAfterIso: "2026-04-23T10:00:01.000Z" },
+ ),
+ ).toBeNull();
+ });
+
+ it("shows a newer success before falling back to an older failure", () => {
+ const providers = [
+ provider({
+ driver: driver("claudeAgent"),
+ updateState: {
+ status: "failed",
+ startedAt: checkedAt,
+ finishedAt: checkedAt,
+ message: "Update command exited with code 1.",
+ output: null,
+ },
+ }),
+ provider({
+ driver: driver("codex"),
+ version: "1.2.0",
+ latestVersion: "1.2.0",
+ advisoryStatus: "current",
+ updateState: {
+ status: "succeeded",
+ startedAt: laterCheckedAt,
+ finishedAt: laterCheckedAt,
+ message: "Provider updated.",
+ output: null,
+ },
+ }),
+ ] satisfies ReadonlyArray<ServerProvider>;
+
+ const successView = getProviderUpdateSidebarPillView(providers, {
+ visibleAfterIso: sessionStartedAt,
+ });
+ expect(successView).toMatchObject({
+ key: "succeeded:codex:2026-04-23T10:01:00.000Z:Provider updated.",
+ tone: "success",
+ title: "Codex updated: v1.2.0",
+ });
+
+ const failureView = getProviderUpdateSidebarPillView(providers, {
+ visibleAfterIso: sessionStartedAt,
+ dismissedKeys: new Set(["succeeded:codex:2026-04-23T10:01:00.000Z:Provider updated."]),
+ });
+ expect(failureView).toMatchObject({
+ key: "failed:claudeAgent:2026-04-23T10:00:00.000Z:Update command exited with code 1.",
+ tone: "error",
+ title: "Claude v1.1.0 update failed",
+ });
+ });
+
+ it("does not show a sidebar pill for passive update availability", () => {
+ expect(
+ getProviderUpdateSidebarPillView([
+ provider({ driver: driver("codex"), canUpdate: true }),
+ provider({ driver: driver("cursor"), canUpdate: false }),
+ ]),
+ ).toBeNull();
+ });
+});
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
new file mode 100644
index 000000000..f45b2916c
--- /dev/null
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
@@ -0,0 +1,537 @@
+import {
+ defaultInstanceIdForDriver,
+ PROVIDER_DISPLAY_NAMES,
+ type ProviderDriverKind,
+ type ProviderInstanceId,
+ type ServerProvider,
+} from "@t3tools/contracts";
+
+export type ProviderUpdateCandidate = ServerProvider & {
+ readonly versionAdvisory: NonNullable<ServerProvider["versionAdvisory"]> & {
+ readonly status: "behind_latest";
+ readonly latestVersion: string;
+ };
+};
+
+export type ProviderUpdateToastType = "warning" | "loading" | "error" | "success";
+export type ProviderUpdateToastPhase = "initial" | "running" | "failed" | "unchanged" | "succeeded";
+
+export interface ProviderUpdateToastView {
+ readonly phase: ProviderUpdateToastPhase;
+ readonly type: ProviderUpdateToastType;
+ readonly title: string;
+ readonly description: string;
+ readonly dismissAfterVisibleMs?: number;
+}
+
+export type ProviderUpdateSidebarPillTone = "loading" | "warning" | "error" | "success";
+
+export interface ProviderUpdateSidebarPillView {
+ readonly key: string;
+ readonly tone: ProviderUpdateSidebarPillTone;
+ readonly title: string;
+ readonly description: string;
+ readonly dismissible?: boolean;
+ readonly dismissAfterVisibleMs?: number;
+}
+
+interface ProviderUpdateSidebarPillOptions {
+ readonly visibleAfterIso?: string;
+ readonly dismissedKeys?: ReadonlySet<string>;
+}
+
+const PROVIDER_UPDATE_SUCCESS_VISIBLE_MS = 3_000;
+
+function formatVersion(value: string): string {
+ return value.startsWith("v") ? value : `v${value}`;
+}
+
+function chooseRepresentativeProvider(
+ current: ServerProvider | undefined,
+ candidate: ServerProvider,
+): ServerProvider {
+ if (!current) {
+ return candidate;
+ }
+ const defaultInstanceId = defaultInstanceIdForDriver(candidate.driver);
+ if (candidate.instanceId === defaultInstanceId) {
+ return candidate;
+ }
+ if (current.instanceId === defaultInstanceId) {
+ return current;
+ }
+ return candidate.checkedAt.localeCompare(current.checkedAt) >= 0 ? candidate : current;
+}
+
+function dedupeProvidersByDriver<T extends ServerProvider>(providers: ReadonlyArray<T>): T[] {
+ const latestProviderByDriver = new Map<ProviderDriverKind, T>();
+
+ for (const provider of providers) {
+ latestProviderByDriver.set(
+ provider.driver,
+ chooseRepresentativeProvider(latestProviderByDriver.get(provider.driver), provider) as T,
+ );
+ }
+
+ return [...latestProviderByDriver.values()];
+}
+
+function dedupeProvidersByInstanceId<T extends ServerProvider>(providers: ReadonlyArray<T>): T[] {
+ const latestProviderByInstanceId = new Map<ProviderInstanceId, T>();
+
+ for (const provider of providers) {
+ const current = latestProviderByInstanceId.get(provider.instanceId);
+ if (!current || provider.checkedAt.localeCompare(current.checkedAt) >= 0) {
+ latestProviderByInstanceId.set(provider.instanceId, provider);
+ }
+ }
+
+ return [...latestProviderByInstanceId.values()];
+}
+
+function getProviderUpdatedTitle(provider: Pick<ServerProvider, "driver" | "version">): string {
+ const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
+ return provider.version
+ ? `${providerName} updated: ${formatVersion(provider.version)}`
+ : `${providerName} updated`;
+}
+
+function getProviderUpdatedDescription(providerCount: number): string {
+ return providerCount === 1
+ ? "New sessions will use the updated provider."
+ : "New sessions will use the updated providers.";
+}
+
+function getProviderFailedUpdateTitle(
+ provider: Pick<ServerProvider, "driver" | "versionAdvisory">,
+): string {
+ const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
+ const attemptedVersion = provider.versionAdvisory?.latestVersion;
+ return attemptedVersion
+ ? `${providerName} ${formatVersion(attemptedVersion)} update failed`
+ : `${providerName} update failed`;
+}
+
+export function isProviderUpdateCandidate(
+ provider: ServerProvider,
+): provider is ProviderUpdateCandidate {
+ return (
+ provider.enabled &&
+ provider.versionAdvisory?.status === "behind_latest" &&
+ provider.versionAdvisory.latestVersion !== null
+ );
+}
+
+export function isProviderUpdateActive(provider: Pick<ServerProvider, "updateState">): boolean {
+ return provider.updateState?.status === "queued" || provider.updateState?.status === "running";
+}
+
+export function collectProviderUpdateCandidates(
+ providers: ReadonlyArray<ServerProvider>,
+): ProviderUpdateCandidate[] {
+ return dedupeProvidersByDriver(providers.filter(isProviderUpdateCandidate));
+}
+
+export function hasOneClickUpdateProviderCandidate(
+ candidate: ProviderUpdateCandidate,
+ providers: ReadonlyArray<ServerProvider>,
+): boolean {
+ if (
+ candidate.versionAdvisory.canUpdate !== true ||
+ candidate.versionAdvisory.updateCommand === null
+ ) {
+ return false;
+ }
+
+ const driverProviders = providers.filter((provider) => provider.driver === candidate.driver);
+ if (driverProviders.length === 0) {
+ return false;
+ }
+
+ const updateCommands = new Set<string>();
+ for (const provider of driverProviders) {
+ if (!isProviderUpdateCandidate(provider)) {
+ continue;
+ }
+ const advisory = provider.versionAdvisory;
+ if (!advisory || advisory.canUpdate !== true || advisory.updateCommand === null) {
+ return false;
+ }
+ updateCommands.add(advisory.updateCommand);
+ }
+
+ return updateCommands.size === 1;
+}
+
+export function canOneClickUpdateProviderCandidate(
+ candidate: ProviderUpdateCandidate,
+ providers: ReadonlyArray<ServerProvider>,
+): boolean {
+ return (
+ !isProviderUpdateActive(candidate) && hasOneClickUpdateProviderCandidate(candidate, providers)
+ );
+}
+
+export function providerUpdateNotificationKey(
+ providers: ReadonlyArray<ProviderUpdateCandidate>,
+): string | null {
+ const parts = dedupeProvidersByDriver(providers)
+ .map((provider) => {
+ const advisory = provider.versionAdvisory;
+ return [provider.driver, advisory.latestVersion].join(":");
+ })
+ .toSorted();
+
+ return parts.length > 0 ? parts.join("|") : null;
+}
+
+export function providerUpdateCandidateKey(provider: ProviderUpdateCandidate): string {
+ return providerUpdateNotificationKey([provider])!;
+}
+
+export function formatProviderList(providers: ReadonlyArray<Pick<ServerProvider, "driver">>) {
+ const names = providers.map(
+ (provider) => PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver,
+ );
+ if (names.length <= 2) {
+ return names.join(" and ");
+ }
+ return `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`;
+}
+
+export function getProviderUpdateInitialToastView(input: {
+ readonly updateProviders: ReadonlyArray<ProviderUpdateCandidate>;
+ readonly oneClickProviders: ReadonlyArray<ProviderUpdateCandidate>;
+}): ProviderUpdateToastView {
+ return {
+ phase: "initial",
+ type: "warning",
+ title: getProviderUpdateInitialToastTitle(input.updateProviders),
+ description:
+ input.oneClickProviders.length > 0
+ ? "Install the update now or review provider settings."
+ : `${formatProviderList(input.updateProviders)} can be updated from provider settings.`,
+ };
+}
+
+export function getProviderUpdateRunningToastView(providerCount: number): ProviderUpdateToastView {
+ return {
+ phase: "running",
+ type: "loading",
+ title: providerCount === 1 ? "Updating provider" : "Updating providers",
+ description: "Running provider update command.",
+ };
+}
+
+export function getProviderUpdateRejectedToastView(
+ providerCount: number,
+ message: string,
+): ProviderUpdateToastView {
+ return {
+ phase: "failed",
+ type: "error",
+ title: providerCount === 1 ? "Provider update failed" : "Provider updates failed",
+ description: message,
+ };
+}
+
+export function getProviderUpdateProgressToastView(input: {
+ readonly providers: ReadonlyArray<ServerProvider>;
+ readonly providerCount: number;
+}): ProviderUpdateToastView {
+ const providers = dedupeProvidersByDriver(input.providers);
+ const failedProviders = providers.filter((provider) => provider.updateState?.status === "failed");
+ if (failedProviders.length > 0) {
+ return {
+ phase: "failed",
+ type: "error",
+ title: failedProviders.length === 1 ? "Provider update failed" : "Provider updates failed",
+ description: getFailedProviderUpdateDescription(failedProviders),
+ };
+ }
+
+ const unchangedProviders = providers.filter(
+ (provider) => provider.updateState?.status === "unchanged",
+ );
+ if (unchangedProviders.length > 0) {
+ return {
+ phase: "unchanged",
+ type: "warning",
+ title:
+ unchangedProviders.length === 1
+ ? "Provider still needs an update"
+ : "Providers still need updates",
+ description: `${formatProviderList(unchangedProviders)} ${
+ unchangedProviders.length === 1 ? "still appears" : "still appear"
+ } outdated. Check provider settings for details.`,
+ };
+ }
+
+ if (providers.some(isProviderUpdateActive)) {
+ return getProviderUpdateRunningToastView(input.providerCount);
+ }
+
+ const hasCompleteProviderSnapshots = providers.length >= input.providerCount;
+ const allProvidersUpdated =
+ hasCompleteProviderSnapshots &&
+ providers.every(
+ (provider) =>
+ provider.updateState?.status === "succeeded" || !isProviderUpdateCandidate(provider),
+ );
+ if (allProvidersUpdated) {
+ return {
+ phase: "succeeded",
+ type: "success",
+ title: input.providerCount === 1 ? "Provider updated" : "Provider updates finished",
+ description: getProviderUpdatedDescription(input.providerCount),
+ dismissAfterVisibleMs: PROVIDER_UPDATE_SUCCESS_VISIBLE_MS,
+ };
+ }
+
+ return getProviderUpdateRunningToastView(input.providerCount);
+}
+
+export function getSingleProviderUpdateProgressToastView(
+ provider: ServerProvider,
+): ProviderUpdateToastView {
+ const view = getProviderUpdateProgressToastView({
+ providers: [provider],
+ providerCount: 1,
+ });
+ const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
+
+ switch (view.phase) {
+ case "running":
+ return {
+ ...view,
+ title: `Updating ${providerName}`,
+ };
+ case "failed":
+ return {
+ ...view,
+ title: getProviderFailedUpdateTitle(provider),
+ };
+ case "unchanged":
+ return {
+ ...view,
+ title: `${providerName} still needs an update`,
+ };
+ case "succeeded":
+ return {
+ ...view,
+ title: getProviderUpdatedTitle(provider),
+ };
+ default:
+ return view;
+ }
+}
+
+export function collectUpdatedProviderSnapshots(input: {
+ readonly results: ReadonlyArray<
+ PromiseSettledResult<{ readonly providers: ReadonlyArray<ServerProvider> }>
+ >;
+ readonly providerInstanceIds: ReadonlySet<ProviderInstanceId>;
+}): ServerProvider[] {
+ const matchedProviders: ServerProvider[] = [];
+
+ for (const result of input.results) {
+ if (result.status !== "fulfilled") {
+ continue;
+ }
+ for (const provider of result.value.providers) {
+ if (input.providerInstanceIds.has(provider.instanceId)) {
+ matchedProviders.push(provider);
+ }
+ }
+ }
+
+ return dedupeProvidersByInstanceId(matchedProviders);
+}
+
+export function firstRejectedProviderUpdateMessage(
+ results: ReadonlyArray<PromiseSettledResult<unknown>>,
+): string | null {
+ const rejected = results.find((result) => result.status === "rejected");
+ if (!rejected) {
+ return null;
+ }
+ return rejected.reason instanceof Error ? rejected.reason.message : "Provider update failed.";
+}
+
+function getUpdateFinishedAt(provider: ServerProvider): string | null {
+ return provider.updateState?.finishedAt ?? null;
+}
+
+function isRecentTerminalProvider(
+ provider: ServerProvider,
+ visibleAfterIso: string | undefined,
+): boolean {
+ const status = provider.updateState?.status;
+ if (status !== "failed" && status !== "unchanged" && status !== "succeeded") {
+ return false;
+ }
+ if (visibleAfterIso === undefined) {
+ return true;
+ }
+ const finishedAt = getUpdateFinishedAt(provider);
+ return finishedAt !== null && finishedAt >= visibleAfterIso;
+}
+
+function latestFinishedAtForProviders(providers: ReadonlyArray<ServerProvider>): string | null {
+ return providers.reduce<string | null>((latest, provider) => {
+ const finishedAt = getUpdateFinishedAt(provider);
+ if (finishedAt === null) {
+ return latest;
+ }
+ return latest === null || finishedAt > latest ? finishedAt : latest;
+ }, null);
+}
+
+export function getProviderUpdateSidebarPillView(
+ providers: ReadonlyArray<ServerProvider>,
+ options?: ProviderUpdateSidebarPillOptions,
+): ProviderUpdateSidebarPillView | null {
+ const dedupedProviders = dedupeProvidersByDriver(providers);
+ const activeProviders = dedupedProviders.filter(isProviderUpdateActive);
+ if (activeProviders.length > 0) {
+ const activeProvider = activeProviders[0]!;
+ const activeProviderName =
+ PROVIDER_DISPLAY_NAMES[activeProvider.driver] ?? activeProvider.driver;
+ return {
+ key: `loading:${activeProviders
+ .map((provider) => `${provider.driver}:${provider.updateState?.status ?? "idle"}`)
+ .toSorted()
+ .join("|")}`,
+ tone: "loading",
+ title:
+ activeProviders.length === 1
+ ? `Updating ${activeProviderName}`
+ : `Updating ${activeProviders.length} providers`,
+ description:
+ activeProviders.length === 1
+ ? `${formatProviderList(activeProviders)} update in progress.`
+ : `${formatProviderList(activeProviders)} updates are in progress.`,
+ };
+ }
+
+ const recentTerminalProviders = dedupedProviders.filter((provider) =>
+ isRecentTerminalProvider(provider, options?.visibleAfterIso),
+ );
+ const terminalCandidates: ProviderUpdateSidebarPillView[] = [];
+
+ const failedProviders = recentTerminalProviders.filter(
+ (provider) => provider.updateState?.status === "failed",
+ );
+ if (failedProviders.length > 0) {
+ const failedProvider = failedProviders[0]!;
+ terminalCandidates.push({
+ key: `failed:${failedProviders
+ .map(
+ (provider) =>
+ `${provider.driver}:${provider.updateState?.finishedAt ?? "pending"}:${provider.updateState?.message ?? ""}`,
+ )
+ .toSorted()
+ .join("|")}`,
+ tone: "error",
+ title:
+ failedProviders.length === 1
+ ? getProviderFailedUpdateTitle(failedProvider)
+ : `${failedProviders.length} provider updates failed`,
+ description: getFailedProviderUpdateDescription(failedProviders),
+ dismissible: true,
+ });
+ }
+
+ const unchangedProviders = recentTerminalProviders.filter(
+ (provider) => provider.updateState?.status === "unchanged",
+ );
+ if (unchangedProviders.length > 0) {
+ const unchangedProvider = unchangedProviders[0]!;
+ const unchangedProviderName =
+ PROVIDER_DISPLAY_NAMES[unchangedProvider.driver] ?? unchangedProvider.driver;
+ terminalCandidates.push({
+ key: `unchanged:${unchangedProviders
+ .map(
+ (provider) =>
+ `${provider.driver}:${provider.updateState?.finishedAt ?? "pending"}:${provider.updateState?.message ?? ""}`,
+ )
+ .toSorted()
+ .join("|")}`,
+ tone: "warning",
+ title:
+ unchangedProviders.length === 1
+ ? `${unchangedProviderName} still needs an update`
+ : `${unchangedProviders.length} providers still need updates`,
+ description: `${formatProviderList(unchangedProviders)} ${
+ unchangedProviders.length === 1 ? "still appears" : "still appear"
+ } outdated. Review provider settings for details.`,
+ dismissible: true,
+ });
+ }
+
+ const succeededProviders = recentTerminalProviders.filter(
+ (provider) => provider.updateState?.status === "succeeded",
+ );
+ if (succeededProviders.length > 0) {
+ const succeededProvider = succeededProviders[0]!;
+ terminalCandidates.push({
+ key: `succeeded:${succeededProviders
+ .map(
+ (provider) =>
+ `${provider.driver}:${provider.updateState?.finishedAt ?? "pending"}:${provider.updateState?.message ?? ""}`,
+ )
+ .toSorted()
+ .join("|")}`,
+ tone: "success",
+ title:
+ succeededProviders.length === 1
+ ? getProviderUpdatedTitle(succeededProvider)
+ : `${succeededProviders.length} providers updated`,
+ description: getProviderUpdatedDescription(succeededProviders.length),
+ dismissAfterVisibleMs: PROVIDER_UPDATE_SUCCESS_VISIBLE_MS,
+ });
+ }
+
+ return (
+ terminalCandidates
+ .toSorted((left, right) => {
+ const leftProviders =
+ left.tone === "error"
+ ? failedProviders
+ : left.tone === "warning"
+ ? unchangedProviders
+ : succeededProviders;
+ const rightProviders =
+ right.tone === "error"
+ ? failedProviders
+ : right.tone === "warning"
+ ? unchangedProviders
+ : succeededProviders;
+ const leftFinishedAt = latestFinishedAtForProviders(leftProviders) ?? "";
+ const rightFinishedAt = latestFinishedAtForProviders(rightProviders) ?? "";
+ return rightFinishedAt.localeCompare(leftFinishedAt);
+ })
+ .find((candidate) => !options?.dismissedKeys?.has(candidate.key)) ?? null
+ );
+}
+
+function getProviderUpdateInitialToastTitle(
+ providers: ReadonlyArray<ProviderUpdateCandidate>,
+): string {
+ if (providers.length === 1) {
+ const provider = providers[0]!;
+ const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
+ return `Update Available: ${providerName} ${formatVersion(provider.versionAdvisory.latestVersion)}`;
+ }
+ return `Updates Available: ${providers.length} providers`;
+}
+
+function getFailedProviderUpdateDescription(providers: ReadonlyArray<ServerProvider>): string {
+ if (providers.length === 1) {
+ const provider = providers[0]!;
+ if (provider.updateState?.message) {
+ return provider.updateState.message;
+ }
+ }
+ return `${formatProviderList(providers)} failed to update. Check provider settings for details.`;
+}
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.tsx b/apps/web/src/components/ProviderUpdateLaunchNotification.tsx
new file mode 100644
index 000000000..69cd83bf8
--- /dev/null
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.tsx
@@ -0,0 +1,300 @@
+import { useNavigate } from "@tanstack/react-router";
+import { DownloadIcon } from "lucide-react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { type ProviderDriverKind, type ProviderInstanceId } from "@t3tools/contracts";
+
+import { ensureLocalApi } from "../localApi";
+import { useDismissedProviderUpdateNotificationKeys } from "../providerUpdateDismissal";
+import { useServerProviders } from "../rpc/serverState";
+import { PROVIDER_ICON_BY_PROVIDER } from "./chat/providerIconUtils";
+import {
+ canOneClickUpdateProviderCandidate,
+ collectProviderUpdateCandidates,
+ collectUpdatedProviderSnapshots,
+ firstRejectedProviderUpdateMessage,
+ getProviderUpdateInitialToastView,
+ getProviderUpdateProgressToastView,
+ getProviderUpdateRejectedToastView,
+ getProviderUpdateRunningToastView,
+ providerUpdateNotificationKey,
+ type ProviderUpdateToastView,
+} from "./ProviderUpdateLaunchNotification.logic";
+import { stackedThreadToast, toastManager } from "./ui/toast";
+
+const seenProviderUpdateNotificationKeys = new Set<string>();
+type ProviderUpdateToastId = ReturnType<typeof toastManager.add>;
+
+type ActiveProviderUpdateToast =
+ | { readonly kind: "prompt"; readonly key: string; readonly toastId: ProviderUpdateToastId }
+ | {
+ readonly kind: "update";
+ readonly key: string;
+ readonly toastId: ProviderUpdateToastId;
+ readonly providerInstanceIds: ReadonlySet<ProviderInstanceId>;
+ readonly providerCount: number;
+ };
+
+function ProviderUpdateToastIcon({ provider }: { provider: ProviderDriverKind }) {
+ const ProviderIcon = PROVIDER_ICON_BY_PROVIDER[provider];
+
+ if (!ProviderIcon) {
+ return (
+ <span className="relative inline-flex size-4 shrink-0 items-center justify-center">
+ <DownloadIcon aria-hidden="true" className="size-4 text-success" strokeWidth={2.5} />
+ </span>
+ );
+ }
+
+ return (
+ <span className="relative inline-flex size-4 shrink-0 items-center justify-center">
+ <ProviderIcon aria-hidden="true" className="size-4" />
+ <span className="absolute -right-1 -bottom-1 inline-flex size-3 items-center justify-center rounded-full bg-popover">
+ <DownloadIcon aria-hidden="true" className="size-2.5 text-success" strokeWidth={2.5} />
+ </span>
+ </span>
+ );
+}
+
+function updateProviderUpdateToast(input: {
+ readonly toastId: ProviderUpdateToastId;
+ readonly view: ProviderUpdateToastView;
+ readonly openSettings: () => void;
+}) {
+ if (input.view.type === "loading" || input.view.type === "success") {
+ toastManager.update(input.toastId, {
+ type: input.view.type,
+ title: input.view.title,
+ description: input.view.description,
+ timeout: 0,
+ data: {
+ hideCopyButton: true,
+ ...(input.view.dismissAfterVisibleMs !== undefined
+ ? { dismissAfterVisibleMs: input.view.dismissAfterVisibleMs }
+ : {}),
+ },
+ });
+ return;
+ }
+
+ toastManager.update(
+ input.toastId,
+ stackedThreadToast({
+ type: input.view.type,
+ title: input.view.title,
+ description: input.view.description,
+ timeout: 0,
+ actionProps: {
+ children: "Settings",
+ onClick: input.openSettings,
+ },
+ actionVariant: "outline",
+ data: {
+ hideCopyButton: true,
+ },
+ }),
+ );
+}
+
+function isTerminalProviderUpdateToastView(view: ProviderUpdateToastView) {
+ return view.phase === "failed" || view.phase === "unchanged" || view.phase === "succeeded";
+}
+
+export function ProviderUpdateLaunchNotification() {
+ const navigate = useNavigate();
+ const providers = useServerProviders();
+ const activeToastRef = useRef<ActiveProviderUpdateToast | null>(null);
+ const { dismissedNotificationKeys, dismissNotificationKey } =
+ useDismissedProviderUpdateNotificationKeys();
+
+ const updateProviders = useMemo(() => collectProviderUpdateCandidates(providers), [providers]);
+ const notificationKey = useMemo(
+ () => providerUpdateNotificationKey(updateProviders),
+ [updateProviders],
+ );
+ const oneClickProviders = useMemo(
+ () =>
+ updateProviders.filter((provider) => canOneClickUpdateProviderCandidate(provider, providers)),
+ [providers, updateProviders],
+ );
+
+ const openProviderSettings = useCallback(
+ (toastId?: ProviderUpdateToastId) => {
+ const activeToast = activeToastRef.current;
+ if (toastId !== undefined) {
+ toastManager.close(toastId);
+ } else if (activeToast) {
+ toastManager.close(activeToast.toastId);
+ }
+ if (activeToast && (toastId === undefined || activeToast.toastId === toastId)) {
+ activeToastRef.current = null;
+ }
+ void navigate({ to: "/settings/providers" });
+ },
+ [navigate],
+ );
+
+ useEffect(() => {
+ const activeToast = activeToastRef.current;
+ if (activeToast?.kind !== "update") {
+ return;
+ }
+
+ const activeProviders = providers.filter((provider) =>
+ activeToast.providerInstanceIds.has(provider.instanceId),
+ );
+ const view = getProviderUpdateProgressToastView({
+ providers: activeProviders,
+ providerCount: activeToast.providerCount,
+ });
+ updateProviderUpdateToast({
+ toastId: activeToast.toastId,
+ view,
+ openSettings: () => openProviderSettings(activeToast.toastId),
+ });
+
+ if (isTerminalProviderUpdateToastView(view)) {
+ activeToastRef.current = null;
+ }
+ }, [providers, openProviderSettings]);
+
+ useEffect(() => {
+ const activeToast = activeToastRef.current;
+ if (activeToast?.kind === "prompt" && activeToast.key !== notificationKey) {
+ toastManager.close(activeToast.toastId);
+ activeToastRef.current = null;
+ }
+
+ if (
+ !notificationKey ||
+ dismissedNotificationKeys.has(notificationKey) ||
+ seenProviderUpdateNotificationKeys.has(notificationKey) ||
+ activeToastRef.current
+ ) {
+ return;
+ }
+
+ seenProviderUpdateNotificationKeys.add(notificationKey);
+
+ const initialView = getProviderUpdateInitialToastView({ updateProviders, oneClickProviders });
+
+ let toastId!: ProviderUpdateToastId;
+ let updateStarted = false;
+ const openSettings = () => openProviderSettings(toastId);
+ const dismissPrompt = () => {
+ dismissNotificationKey(notificationKey);
+ };
+
+ const runUpdates = () => {
+ if (updateStarted || oneClickProviders.length === 0) {
+ return;
+ }
+ updateStarted = true;
+
+ const providerCount = oneClickProviders.length;
+ const providerInstanceIds = new Set(oneClickProviders.map((provider) => provider.instanceId));
+ activeToastRef.current = {
+ kind: "update",
+ key: notificationKey,
+ toastId,
+ providerInstanceIds,
+ providerCount,
+ };
+
+ updateProviderUpdateToast({
+ toastId,
+ view: getProviderUpdateRunningToastView(providerCount),
+ openSettings,
+ });
+
+ void Promise.allSettled(
+ oneClickProviders.map(async (provider) =>
+ ensureLocalApi().server.updateProvider({
+ provider: provider.driver,
+ instanceId: provider.instanceId,
+ }),
+ ),
+ ).then((results) => {
+ const activeUpdateToast = activeToastRef.current;
+ if (activeUpdateToast?.kind !== "update" || activeUpdateToast.toastId !== toastId) {
+ return;
+ }
+
+ const rejectedMessage = firstRejectedProviderUpdateMessage(results);
+ if (rejectedMessage) {
+ updateProviderUpdateToast({
+ toastId,
+ view: getProviderUpdateRejectedToastView(providerCount, rejectedMessage),
+ openSettings,
+ });
+ activeToastRef.current = null;
+ return;
+ }
+
+ const updatedProviderSnapshots = collectUpdatedProviderSnapshots({
+ results,
+ providerInstanceIds,
+ });
+ const view = getProviderUpdateProgressToastView({
+ providers: updatedProviderSnapshots,
+ providerCount,
+ });
+ updateProviderUpdateToast({
+ toastId,
+ view,
+ openSettings,
+ });
+
+ if (isTerminalProviderUpdateToastView(view)) {
+ activeToastRef.current = null;
+ }
+ });
+ };
+
+ toastId = toastManager.add(
+ stackedThreadToast({
+ type: initialView.type,
+ title: initialView.title,
+ description: initialView.description,
+ timeout: 0,
+ actionProps:
+ oneClickProviders.length > 0
+ ? {
+ children: "Update",
+ onClick: runUpdates,
+ }
+ : {
+ children: "Settings",
+ onClick: openSettings,
+ },
+ actionVariant: oneClickProviders.length > 0 ? "default" : "outline",
+ data: {
+ leadingIcon:
+ updateProviders.length === 1 ? (
+ <ProviderUpdateToastIcon provider={updateProviders[0]!.driver} />
+ ) : undefined,
+ hideCopyButton: true,
+ onClose: dismissPrompt,
+ ...(oneClickProviders.length > 0
+ ? {
+ secondaryActionProps: {
+ children: "Settings",
+ onClick: openSettings,
+ },
+ secondaryActionVariant: "outline" as const,
+ }
+ : {}),
+ },
+ }),
+ );
+ activeToastRef.current = { kind: "prompt", key: notificationKey, toastId };
+ }, [
+ dismissNotificationKey,
+ dismissedNotificationKeys,
+ notificationKey,
+ oneClickProviders,
+ openProviderSettings,
+ updateProviders,
+ ]);
+
+ return null;
+}
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 1e740e5f3..ccac14194 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -185,6 +185,7 @@ import {
type SidebarProjectGroupMember,
type SidebarProjectSnapshot,
} from "../sidebarProjectGrouping";
+import { SidebarProviderUpdatePill } from "./sidebar/SidebarProviderUpdatePill";
const THREAD_PREVIEW_LIMIT = 6;
const SIDEBAR_SORT_LABELS: Record<SidebarProjectSortOrder, string> = {
updated_at: "Last user message",
@@ -2434,6 +2435,7 @@ const SidebarChromeFooter = memo(function SidebarChromeFooter() {
return (
<SidebarFooter className="p-2">
+ <SidebarProviderUpdatePill />
<SidebarUpdatePill />
<SidebarMenu>
<SidebarMenuItem>
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.tsx b/apps/web/src/components/settings/ProviderInstanceCard.tsx
index 236e1db56..44ba09361 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.tsx
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -1,6 +1,15 @@
"use client";
-import { ChevronDownIcon, PlusIcon, Trash2Icon, XIcon } from "lucide-react";
+import {
+ ArrowUpCircleIcon,
+ ChevronDownIcon,
+ CopyIcon,
+ DownloadIcon,
+ LoaderIcon,
+ PlusIcon,
+ Trash2Icon,
+ XIcon,
+} from "lucide-react";
import { useEffect, useState, type ReactNode } from "react";
import {
isProviderDriverKind,
@@ -13,12 +22,15 @@ import {
} from "@t3tools/contracts";
import { cn } from "../../lib/utils";
+import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
import { normalizeProviderAccentColor } from "../../providerInstances";
import { Badge } from "../ui/badge";
import { Button } from "../ui/button";
import { Collapsible, CollapsibleContent } from "../ui/collapsible";
import { DraftInput } from "../ui/draft-input";
+import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
import { Switch } from "../ui/switch";
+import { stackedThreadToast, toastManager } from "../ui/toast";
import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
import type { DriverOption } from "./providerDriverMeta";
import { ProviderSettingsForm } from "./ProviderSettingsForm";
@@ -26,6 +38,7 @@ import { ProviderModelsSection } from "./ProviderModelsSection";
import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
import { RedactedSensitiveText } from "./RedactedSensitiveText";
import {
+ getProviderVersionAdvisoryPresentation,
PROVIDER_STATUS_STYLES,
getProviderSummary,
getProviderVersionLabel,
@@ -405,6 +418,8 @@ interface ProviderInstanceCardProps {
readonly onHiddenModelsChange: (next: ReadonlyArray<string>) => void;
readonly onFavoriteModelsChange: (next: ReadonlyArray<string>) => void;
readonly onModelOrderChange: (next: ReadonlyArray<string>) => void;
+ readonly onRunUpdate?: (() => void) | undefined;
+ readonly isUpdating?: boolean | undefined;
}
/**
@@ -447,6 +462,8 @@ export function ProviderInstanceCard({
onHiddenModelsChange,
onFavoriteModelsChange,
onModelOrderChange,
+ onRunUpdate,
+ isUpdating = false,
}: ProviderInstanceCardProps) {
const enabled = instance.enabled ?? true;
// The server-reported status wins when present; otherwise fall back to
@@ -464,10 +481,30 @@ export function ProviderInstanceCard({
: null;
const summary = rawSummary;
const versionLabel = getProviderVersionLabel(liveProvider?.version);
+ const versionAdvisory = getProviderVersionAdvisoryPresentation(liveProvider?.versionAdvisory);
+ const updateCommand = versionAdvisory?.updateCommand ?? null;
const FallbackIconComponent = driverOption?.icon;
const displayName =
instance.displayName?.trim() || driverOption?.label || String(instance.driver);
const accentColor = normalizeProviderAccentColor(instance.accentColor);
+ const { copyToClipboard } = useCopyToClipboard<{ providerName: string }>({
+ onCopy: ({ providerName }) => {
+ toastManager.add({
+ type: "success",
+ title: `${providerName} update command copied`,
+ description: "Run it in a terminal when you are ready to update.",
+ });
+ },
+ onError: (error, { providerName }) => {
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: `Could not copy ${providerName} update command`,
+ description: error.message,
+ }),
+ );
+ },
+ });
// Narrow `instance.driver` for callers that key on the closed
// `ProviderDriverKind` union (e.g. `normalizeModelSlug`'s alias table). Custom
@@ -535,97 +572,203 @@ export function ProviderInstanceCard({
);
};
+ const titleIconNode = driverKind ? (
+ <ProviderInstanceIcon
+ driverKind={driverKind}
+ displayName={displayName}
+ accentColor={accentColor}
+ showBadge={Boolean(accentColor)}
+ statusDotClassName={statusStyle.dot}
+ className="size-5"
+ iconClassName="size-4 text-foreground/80"
+ badgeClassName="right-[-0.125rem] bottom-[-0.125rem] h-3 min-w-3 text-[7px]"
+ />
+ ) : FallbackIconComponent ? (
+ <span className="relative inline-flex size-5 shrink-0 items-center justify-center">
+ <FallbackIconComponent className="size-4 text-foreground/80" aria-hidden />
+ <span
+ className={cn(
+ "pointer-events-none absolute -left-0.5 -top-0.5 size-2 rounded-full ring-2 ring-background",
+ statusStyle.dot,
+ )}
+ aria-hidden
+ />
+ </span>
+ ) : (
+ <span className={cn("size-2 shrink-0 rounded-full", statusStyle.dot)} />
+ );
+
+ const titleHeadNode = (
+ <>
+ {titleIconNode}
+ <h3 className="truncate text-[13px] font-semibold tracking-[-0.01em] text-foreground">
+ {displayName}
+ </h3>
+ {String(instanceId) !== String(instance.driver) ? (
+ <code className="truncate rounded bg-muted/60 px-1 py-0.5 text-[10px] text-muted-foreground">
+ {instanceId}
+ </code>
+ ) : null}
+ {driverOption?.badgeLabel ? (
+ <Badge variant="warning" size="sm" className="shrink-0">
+ {driverOption.badgeLabel}
+ </Badge>
+ ) : null}
+ </>
+ );
+
+ const titleTailNode = (
+ <>
+ {headerAction ? (
+ <span className="inline-flex h-5 w-5 shrink-0 items-center justify-center">
+ {headerAction}
+ </span>
+ ) : null}
+ {onDelete ? (
+ <span className="inline-flex h-5 w-5 shrink-0 items-center justify-center">
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <Button
+ size="icon-xs"
+ variant="ghost"
+ className="size-5 rounded-sm p-0 text-muted-foreground hover:text-destructive"
+ onClick={onDelete}
+ aria-label={`Delete provider instance ${instanceId}`}
+ >
+ <Trash2Icon className="size-3" />
+ </Button>
+ }
+ />
+ <TooltipPopup side="top">Delete instance</TooltipPopup>
+ </Tooltip>
+ </span>
+ ) : null}
+ </>
+ );
+
+ const authRowNode = (
+ <p className="flex min-w-0 flex-wrap items-center gap-x-1 text-xs text-muted-foreground">
+ {hasAuthenticatedEmail ? (
+ <>
+ <span>Authenticated as</span>
+ <ProviderAuthEmail email={authEmail} />
+ {authenticatedDetail ? <span>· {authenticatedDetail}</span> : null}
+ </>
+ ) : (
+ <>
+ <span>{summary.headline}</span>
+ <ProviderAuthEmail email={authEmail} separator prefix="Email" />
+ </>
+ )}
+ {summary.detail ? <span>- {summary.detail}</span> : null}
+ </p>
+ );
+
+ const versionCodeNode = versionLabel ? (
+ <code className="text-xs text-muted-foreground">{versionLabel}</code>
+ ) : null;
+
return (
- <div className="border-t border-border first:border-t-0">
- <div className="px-4 py-4 sm:px-5">
+ <div className="border-t border-border/60 first:border-t-0">
+ <div className="px-4 py-3.5 sm:px-5">
<div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
<div className="min-w-0 flex-1 space-y-1">
- <div className="flex min-h-5 items-center gap-1.5">
- {driverKind ? (
- <ProviderInstanceIcon
- driverKind={driverKind}
- displayName={displayName}
- accentColor={accentColor}
- showBadge={Boolean(accentColor)}
- statusDotClassName={statusStyle.dot}
- className="size-5"
- iconClassName="size-4 text-foreground/80"
- badgeClassName="right-[-0.125rem] bottom-[-0.125rem] h-3 min-w-3 text-[7px]"
- />
- ) : FallbackIconComponent ? (
- <span className="relative inline-flex size-5 shrink-0 items-center justify-center">
- <FallbackIconComponent className="size-4 text-foreground/80" aria-hidden />
- <span
- className={cn(
- "pointer-events-none absolute -left-0.5 -top-0.5 size-2 rounded-full ring-2 ring-background",
- statusStyle.dot,
- )}
- aria-hidden
+ <div className="flex min-w-0 flex-wrap items-center gap-2">
+ {titleHeadNode}
+ {versionCodeNode}
+ {versionAdvisory ? (
+ <Popover>
+ <PopoverTrigger
+ render={
+ <Button
+ type="button"
+ size="icon-xs"
+ variant="ghost"
+ className={cn(
+ "size-5 rounded-sm p-0",
+ versionAdvisory.emphasis === "strong"
+ ? "text-warning hover:text-warning"
+ : "text-primary hover:text-primary",
+ )}
+ aria-label="Update available — view details"
+ >
+ <ArrowUpCircleIcon className="size-3.5 [animation:bounce_2.4s_ease-in-out_infinite] motion-reduce:animate-none" />
+ </Button>
+ }
/>
- </span>
- ) : (
- <span className={cn("size-2 shrink-0 rounded-full", statusStyle.dot)} />
- )}
- <h3 className="truncate text-sm font-medium text-foreground">{displayName}</h3>
- {String(instanceId) !== String(instance.driver) ? (
- // Hide the id chip on a default slot whose id === the
- // driver slug — it's redundant with the driver icon +
- // label. Custom instances (and any instance the user has
- // since renamed) keep the chip so their slug stays
- // visible for copy/paste + disambiguation.
- <code className="truncate rounded bg-muted/60 px-1 py-0.5 text-[10px] text-muted-foreground">
- {instanceId}
- </code>
- ) : null}
- {driverOption?.badgeLabel ? (
- <Badge variant="warning" size="sm" className="shrink-0">
- {driverOption.badgeLabel}
- </Badge>
- ) : null}
- {versionLabel ? (
- <code className="text-xs text-muted-foreground">{versionLabel}</code>
- ) : null}
- {headerAction ? (
- <span className="inline-flex h-5 w-5 shrink-0 items-center justify-center">
- {headerAction}
- </span>
- ) : null}
- {onDelete ? (
- <span className="inline-flex h-5 w-5 shrink-0 items-center justify-center">
- <Tooltip>
- <TooltipTrigger
- render={
+ <PopoverPopup side="bottom" align="start" className="w-84">
+ <div className="grid gap-3">
+ <div className="grid gap-0.5">
+ <p className="text-[13px] font-semibold leading-tight text-foreground">
+ Update available
+ </p>
+ <p
+ className={cn(
+ "text-xs leading-snug",
+ versionAdvisory.emphasis === "strong"
+ ? "text-warning"
+ : "text-muted-foreground",
+ )}
+ >
+ {versionAdvisory.detail}
+ </p>
+ </div>
+ {onRunUpdate ? (
<Button
- size="icon-xs"
- variant="ghost"
- className="size-5 rounded-sm p-0 text-muted-foreground hover:text-destructive"
- onClick={onDelete}
- aria-label={`Delete provider instance ${instanceId}`}
+ type="button"
+ size="xs"
+ variant="default"
+ className="w-full"
+ disabled={isUpdating}
+ onClick={onRunUpdate}
>
- <Trash2Icon className="size-3" />
+ {isUpdating ? <LoaderIcon className="animate-spin" /> : <DownloadIcon />}
+ {isUpdating ? "Updating" : "Update now"}
</Button>
- }
- />
- <TooltipPopup side="top">Delete instance</TooltipPopup>
- </Tooltip>
- </span>
+ ) : null}
+ {onRunUpdate && updateCommand ? (
+ <div className="flex items-center gap-2 text-[10px] font-medium uppercase tracking-wider text-muted-foreground">
+ <span aria-hidden className="h-px flex-1 bg-border" />
+ or, update manually using
+ <span aria-hidden className="h-px flex-1 bg-border" />
+ </div>
+ ) : null}
+ {updateCommand ? (
+ <div className="flex items-center gap-1 rounded-md border border-border/70 bg-muted/40 py-0.5 pr-0.5 pl-2">
+ <code className="min-w-0 flex-1 overflow-x-auto whitespace-nowrap font-mono text-[11px] text-foreground [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
+ {updateCommand}
+ </code>
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <Button
+ type="button"
+ size="icon-xs"
+ variant="ghost"
+ className="size-6 shrink-0 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+ onClick={() =>
+ copyToClipboard(updateCommand, {
+ providerName: displayName,
+ })
+ }
+ aria-label="Copy update command"
+ >
+ <CopyIcon className="size-3" />
+ </Button>
+ }
+ />
+ <TooltipPopup side="top">Copy command</TooltipPopup>
+ </Tooltip>
+ </div>
+ ) : null}
+ </div>
+ </PopoverPopup>
+ </Popover>
) : null}
+ {titleTailNode}
</div>
- <p className="flex min-w-0 flex-wrap items-center gap-x-1 text-xs text-muted-foreground">
- {hasAuthenticatedEmail ? (
- <>
- <span>Authenticated as</span>
- <ProviderAuthEmail email={authEmail} />
- {authenticatedDetail ? <span>· {authenticatedDetail}</span> : null}
- </>
- ) : (
- <>
- <span>{summary.headline}</span>
- <ProviderAuthEmail email={authEmail} separator prefix="Email" />
- </>
- )}
- {summary.detail ? <span>- {summary.detail}</span> : null}
- </p>
+ {authRowNode}
</div>
<div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
<Button
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 85c16b701..9249ff697 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -10,7 +10,10 @@ import {
type DesktopUpdateChannel,
type DesktopUpdateState,
type LocalApi,
+ ProviderDriverKind,
+ ProviderInstanceId,
type ServerConfig,
+ type ServerProvider,
type SourceControlDiscoveryResult,
} from "@t3tools/contracts";
import { DateTime, Option } from "effect";
@@ -23,7 +26,7 @@ import { AppAtomRegistryProvider, resetAppAtomRegistryForTests } from "../../rpc
import { resetServerStateForTests, setServerConfigSnapshot } from "../../rpc/serverState";
import { useUiStateStore } from "../../uiStateStore";
import { ConnectionsSettings } from "./ConnectionsSettings";
-import { GeneralSettingsPanel } from "./SettingsPanels";
+import { GeneralSettingsPanel, ProviderSettingsPanel } from "./SettingsPanels";
import { SourceControlSettingsPanel } from "./SourceControlSettings";
const authAccessHarness = vi.hoisted(() => {
@@ -207,6 +210,31 @@ function createBaseServerConfig(): ServerConfig {
};
}
+function createOutdatedProvider(driver: string): ServerProvider {
+ return {
+ instanceId: ProviderInstanceId.make(driver),
+ driver: ProviderDriverKind.make(driver),
+ enabled: true,
+ installed: true,
+ version: "1.0.0",
+ status: "ready",
+ auth: { status: "authenticated" },
+ checkedAt: "2026-05-04T10:00:00.000Z",
+ models: [],
+ slashCommands: [],
+ skills: [],
+ versionAdvisory: {
+ status: "behind_latest",
+ currentVersion: "1.0.0",
+ latestVersion: "1.1.0",
+ message: "Update available.",
+ checkedAt: "2026-05-04T10:00:00.000Z",
+ updateCommand: "npm install -g openai/codex@latest",
+ canUpdate: true,
+ },
+ };
+}
+
function makeUtc(value: string) {
return DateTime.makeUnsafe(Date.parse(value));
}
@@ -1016,7 +1044,7 @@ describe("GeneralSettingsPanel observability", () => {
mounted = await render(
<AppAtomRegistryProvider>
- <GeneralSettingsPanel />
+ <ProviderSettingsPanel />
</AppAtomRegistryProvider>,
);
@@ -1031,6 +1059,41 @@ describe("GeneralSettingsPanel observability", () => {
await expect.element(page.getByText("Server password")).toBeInTheDocument();
await expect.element(page.getByPlaceholder("Optional")).toBeInTheDocument();
});
+
+ it("runs one-click provider updates from the provider card", async () => {
+ const updateProvider = vi.fn<LocalApi["server"]["updateProvider"]>().mockResolvedValue({
+ providers: [createOutdatedProvider("codex")],
+ });
+ window.nativeApi = {
+ persistence: {
+ getClientSettings: vi.fn().mockResolvedValue(null),
+ setClientSettings: vi.fn().mockResolvedValue(undefined),
+ },
+ server: {
+ updateProvider,
+ },
+ } as unknown as LocalApi;
+
+ setServerConfigSnapshot({
+ ...createBaseServerConfig(),
+ providers: [createOutdatedProvider("codex")],
+ });
+
+ mounted = await render(
+ <AppAtomRegistryProvider>
+ <ProviderSettingsPanel />
+ </AppAtomRegistryProvider>,
+ );
+
+ await page.getByRole("button", { name: "Update available — view details" }).click();
+ await expect.element(page.getByRole("button", { name: "Update now" })).toBeInTheDocument();
+ await page.getByRole("button", { name: "Update now" }).click();
+
+ expect(updateProvider).toHaveBeenCalledWith({
+ provider: ProviderDriverKind.make("codex"),
+ instanceId: ProviderInstanceId.make("codex"),
+ });
+ });
});
describe("SourceControlSettingsPanel discovery states", () => {
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 8fc36d4a3..89816ae47 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -4,6 +4,7 @@ import { useCallback, useMemo, useRef, useState } from "react";
import {
defaultInstanceIdForDriver,
type DesktopUpdateChannel,
+ PROVIDER_DISPLAY_NAMES,
ProviderDriverKind,
type ProviderInstanceConfig,
type ProviderInstanceId,
@@ -56,6 +57,13 @@ import { Switch } from "../ui/switch";
import { stackedThreadToast, toastManager } from "../ui/toast";
import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
import { AddProviderInstanceDialog } from "./AddProviderInstanceDialog";
+import {
+ canOneClickUpdateProviderCandidate,
+ collectProviderUpdateCandidates,
+ hasOneClickUpdateProviderCandidate,
+ isProviderUpdateActive,
+ type ProviderUpdateCandidate,
+} from "../ProviderUpdateLaunchNotification.logic";
import { ProviderInstanceCard } from "./ProviderInstanceCard";
import { DRIVER_OPTIONS, getDriverOption } from "./providerDriverMeta";
import { buildProviderInstanceUpdatePatch } from "./SettingsPanels.logic";
@@ -345,37 +353,12 @@ function AboutVersionSection() {
export function useSettingsRestore(onRestored?: () => void) {
const { theme, setTheme } = useTheme();
const settings = useSettings();
- const { resetSettings } = useUpdateSettings();
+ const { updateSettings } = useUpdateSettings();
const isGitWritingModelDirty = !Equal.equals(
settings.textGenerationModelSelection ?? null,
DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection ?? null,
);
- // A provider surface is "dirty" if either the legacy per-kind
- // `settings.providers[kind]` struct differs from defaults (for users
- // on pre-migration data) or the new `settings.providerInstances` map
- // has any entries (every edit to a default slot promotes it into an
- // explicit entry, so any key in that map represents user intent to
- // diverge from factory defaults). Checking both keeps the Restore
- // Defaults chip accurate throughout the legacy→instance migration.
- const areProviderSettingsDirty =
- PROVIDER_SETTINGS.some((providerSettings) => {
- type LegacyProviderSettings = (typeof settings.providers)[keyof typeof settings.providers];
- const currentProviders = settings.providers as Record<
- string,
- LegacyProviderSettings | undefined
- >;
- const defaultProviders = DEFAULT_UNIFIED_SETTINGS.providers as Record<
- string,
- LegacyProviderSettings | undefined
- >;
- const currentSettings = currentProviders[providerSettings.provider];
- const defaultSettings = defaultProviders[providerSettings.provider];
- return !Equal.equals(currentSettings, defaultSettings);
- }) ||
- Object.keys(settings.providerInstances ?? {}).length > 0 ||
- Object.keys(settings.providerModelPreferences ?? {}).length > 0 ||
- (settings.favorites ?? []).length > 0;
const changedSettingLabels = useMemo(
() => [
@@ -408,10 +391,8 @@ export function useSettingsRestore(onRestored?: () => void) {
? ["Delete confirmation"]
: []),
...(isGitWritingModelDirty ? ["Git writing model"] : []),
- ...(areProviderSettingsDirty ? ["Providers"] : []),
],
[
- areProviderSettingsDirty,
isGitWritingModelDirty,
settings.autoOpenPlanSidebar,
settings.confirmThreadArchive,
@@ -437,9 +418,20 @@ export function useSettingsRestore(onRestored?: () => void) {
if (!confirmed) return;
setTheme("system");
- resetSettings();
+ updateSettings({
+ timestampFormat: DEFAULT_UNIFIED_SETTINGS.timestampFormat,
+ diffWordWrap: DEFAULT_UNIFIED_SETTINGS.diffWordWrap,
+ diffIgnoreWhitespace: DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace,
+ autoOpenPlanSidebar: DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar,
+ enableAssistantStreaming: DEFAULT_UNIFIED_SETTINGS.enableAssistantStreaming,
+ defaultThreadEnvMode: DEFAULT_UNIFIED_SETTINGS.defaultThreadEnvMode,
+ addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
+ confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
+ confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
+ });
onRestored?.();
- }, [changedSettingLabels, onRestored, resetSettings, setTheme]);
+ }, [changedSettingLabels, onRestored, setTheme, updateSettings]);
return {
changedSettingLabels,
@@ -458,44 +450,10 @@ export function GeneralSettingsPanel() {
const [openPathErrorByTarget, setOpenPathErrorByTarget] = useState<
Partial<Record<"keybindings" | "logsDirectory", string | null>>
>({});
- const [isRefreshingProviders, setIsRefreshingProviders] = useState(false);
- const [isAddInstanceDialogOpen, setIsAddInstanceDialogOpen] = useState(false);
- // Collapsible state per provider-instance card, keyed by the instance id.
- // `Record<string, boolean>` so we don't need to preseed an entry for every
- // configured instance — an absent key reads as collapsed. Default-slot
- // rows share this state: their id is the driver slug
- // (`defaultInstanceIdForDriver(driver)`), which is also `ProviderDriverKind` at
- // runtime, so a pre-existing open key for e.g. "codex" persists across
- // the legacy/unified render swap.
- const [openInstanceDetails, setOpenInstanceDetails] = useState<Record<string, boolean>>({});
- const refreshingRef = useRef(false);
- const refreshProviders = useCallback(() => {
- if (refreshingRef.current) return;
- refreshingRef.current = true;
- setIsRefreshingProviders(true);
- void ensureLocalApi()
- .server.refreshProviders()
- .catch((error: unknown) => {
- console.warn("Failed to refresh providers", error);
- })
- .finally(() => {
- refreshingRef.current = false;
- setIsRefreshingProviders(false);
- });
- }, []);
-
const keybindingsConfigPath = useServerKeybindingsConfigPath();
const availableEditors = useServerAvailableEditors();
const observability = useServerObservability();
const serverProviders = useServerProviders();
- const visibleProviderSettings = PROVIDER_SETTINGS.filter(
- (providerSettings) =>
- providerSettings.provider !== "cursor" ||
- serverProviders.some(
- (provider) =>
- provider.instanceId === defaultInstanceIdForDriver(ProviderDriverKind.make("cursor")),
- ),
- );
const logsDirectoryPath = observability?.logsDirectoryPath ?? null;
const diagnosticsDescription = (() => {
const exports: string[] = [];
@@ -576,221 +534,6 @@ export function GeneralSettingsPanel() {
const isOpeningKeybindings = openingPathByTarget.keybindings;
const isOpeningLogsDirectory = openingPathByTarget.logsDirectory;
- const lastCheckedAt =
- serverProviders.length > 0
- ? serverProviders.reduce(
- (latest, provider) => (provider.checkedAt > latest ? provider.checkedAt : latest),
- serverProviders[0]!.checkedAt,
- )
- : null;
-
- /**
- * Build the list of rows to render, one per configured instance. Each
- * row carries enough context to drive `ProviderInstanceCard` without
- * threading storage concerns: whether it's a built-in default slot (in
- * which case `isDefault` is true, deletion is gated off, and the
- * effective envelope may have been synthesized from legacy just for
- * this render), the driver kind narrow for the in-card model-slug
- * normalization, and whether a reset-to-factory action is warranted.
- *
- * Ordering mirrors the prior split: visible built-in default slots
- * first (one per visible kind), then user-authored custom instances
- * grouped by driver after their default sibling, then orphan instances
- * whose driver isn't in the visible-defaults set.
- */
- interface InstanceRow {
- readonly instanceId: ProviderInstanceId;
- readonly instance: ProviderInstanceConfig;
- readonly driver: ProviderDriverKind;
- /** True for the slot whose id is `defaultInstanceIdForDriver(driver)`. */
- readonly isDefault: boolean;
- /**
- * True when this default slot differs from the factory defaults —
- * either through an explicit `providerInstances[defaultId]` entry,
- * or through a non-default legacy `settings.providers[kind]` struct
- * that we're still bridging. Used to show the reset-to-factory
- * affordance. Undefined for custom rows (they have a delete button
- * instead; "factory defaults" isn't meaningful).
- */
- readonly isDirty?: boolean;
- }
-
- const instancesByDriver = new Map<
- ProviderDriverKind,
- Array<[ProviderInstanceId, ProviderInstanceConfig]>
- >();
- for (const [rawId, instance] of Object.entries(settings.providerInstances ?? {})) {
- const driver = instance.driver;
- const list = instancesByDriver.get(driver) ?? [];
- list.push([rawId as ProviderInstanceId, instance]);
- instancesByDriver.set(driver, list);
- }
-
- const defaultSlotIdsBySource = new Set<string>(
- visibleProviderSettings.map((providerSettings) =>
- String(defaultInstanceIdForDriver(providerSettings.provider)),
- ),
- );
-
- const rows: InstanceRow[] = [];
- const visibleDriverKinds = new Set<ProviderDriverKind>(
- visibleProviderSettings.map((providerSettings) => providerSettings.provider),
- );
-
- for (const providerSettings of visibleProviderSettings) {
- type LegacyProviderSettings = (typeof settings.providers)[keyof typeof settings.providers];
- const legacyProviders = settings.providers as Record<string, LegacyProviderSettings>;
- const defaultLegacyProviders = DEFAULT_UNIFIED_SETTINGS.providers as Record<
- string,
- LegacyProviderSettings
- >;
- const driver = providerSettings.provider;
- const defaultInstanceId = defaultInstanceIdForDriver(driver);
- // Prefer an explicit `providerInstances[defaultId]` entry when one
- // exists (every edit via this UI promotes the default slot into
- // that map); fall back to synthesizing one from the legacy
- // `settings.providers[kind]` struct so first-time viewers still see
- // their persisted config.
- const explicitInstance = settings.providerInstances?.[defaultInstanceId];
- const legacyConfig = legacyProviders[providerSettings.provider]!;
- const defaultLegacyConfig = defaultLegacyProviders[providerSettings.provider]!;
- const effectiveInstance: ProviderInstanceConfig =
- explicitInstance ??
- ({
- driver,
- enabled: legacyConfig.enabled,
- config: legacyConfig,
- } satisfies ProviderInstanceConfig);
- const isDirty =
- explicitInstance !== undefined || !Equal.equals(legacyConfig, defaultLegacyConfig);
- rows.push({
- instanceId: defaultInstanceId,
- instance: effectiveInstance,
- driver,
- isDefault: true,
- isDirty,
- });
- // Non-default customs for this driver kind follow their default.
- for (const [id, instance] of instancesByDriver.get(providerSettings.provider) ?? []) {
- if (id === defaultInstanceId) continue;
- rows.push({ instanceId: id, instance, driver: instance.driver, isDefault: false });
- }
- }
- // Orphan instances: drivers the visible-defaults list doesn't cover
- // (e.g. Cursor when the server hasn't reported it but the user has
- // authored a Cursor instance anyway, or fork drivers not shipped by
- // this build). Preserve insertion order within each driver.
- for (const [driver, list] of instancesByDriver) {
- if (visibleDriverKinds.has(driver)) continue;
- for (const [id, instance] of list) {
- const isDefaultSlot = defaultSlotIdsBySource.has(String(id));
- rows.push({
- instanceId: id,
- instance,
- driver: instance.driver,
- isDefault: isDefaultSlot,
- });
- }
- }
-
- const updateProviderInstance = (
- row: InstanceRow,
- next: ProviderInstanceConfig,
- options?: {
- readonly textGenerationModelSelection?: Parameters<
- typeof buildProviderInstanceUpdatePatch
- >[0]["textGenerationModelSelection"];
- },
- ) => {
- updateSettings(
- buildProviderInstanceUpdatePatch({
- settings,
- instanceId: row.instanceId,
- instance: next,
- driver: row.driver,
- isDefault: row.isDefault,
- textGenerationModelSelection: options?.textGenerationModelSelection,
- }),
- );
- };
-
- const deleteProviderInstance = (id: ProviderInstanceId) => {
- updateSettings({
- providerInstances: withoutProviderInstanceKey(settings.providerInstances, id),
- providerModelPreferences: withoutProviderInstanceKey(settings.providerModelPreferences, id),
- favorites: withoutProviderInstanceFavorites(settings.favorites ?? [], id),
- });
- };
-
- const updateProviderModelPreferences = (
- instanceId: ProviderInstanceId,
- next: {
- readonly hiddenModels: ReadonlyArray<string>;
- readonly modelOrder: ReadonlyArray<string>;
- },
- ) => {
- const hiddenModels = [...new Set(next.hiddenModels.filter((slug) => slug.trim().length > 0))];
- const modelOrder = [...new Set(next.modelOrder.filter((slug) => slug.trim().length > 0))];
- const rest = withoutProviderInstanceKey(settings.providerModelPreferences, instanceId);
- updateSettings({
- providerModelPreferences:
- hiddenModels.length === 0 && modelOrder.length === 0
- ? rest
- : {
- ...rest,
- [instanceId]: {
- hiddenModels,
- modelOrder,
- },
- },
- });
- };
-
- const updateProviderFavoriteModels = (
- instanceId: ProviderInstanceId,
- nextFavoriteModels: ReadonlyArray<string>,
- ) => {
- const favoriteModels = [
- ...new Set(nextFavoriteModels.map((slug) => slug.trim()).filter((slug) => slug.length > 0)),
- ];
- updateSettings({
- favorites: [
- ...withoutProviderInstanceFavorites(settings.favorites ?? [], instanceId),
- ...favoriteModels.map((model) => ({ provider: instanceId, model })),
- ],
- });
- };
-
- /**
- * Reset a built-in default slot back to factory defaults. Clears both
- * the legacy `settings.providers[kind]` struct and any explicit
- * `providerInstances[defaultId]` entry that has promoted legacy into
- * the new map, so hydration re-synthesizes a clean envelope on next
- * load. Safe to call on drivers that have never been edited.
- */
- const resetDefaultInstance = (driverKind: ProviderDriverKind) => {
- type LegacyProviderSettings = (typeof settings.providers)[keyof typeof settings.providers];
- const defaultLegacyProviders = DEFAULT_UNIFIED_SETTINGS.providers as Record<
- string,
- LegacyProviderSettings | undefined
- >;
- const defaultInstanceId = defaultInstanceIdForDriver(driverKind);
- const defaultLegacyProvider = defaultLegacyProviders[driverKind];
- if (defaultLegacyProvider === undefined) return;
- updateSettings({
- providers: {
- ...settings.providers,
- [driverKind]: defaultLegacyProvider,
- } as typeof settings.providers,
- providerInstances: withoutProviderInstanceKey(settings.providerInstances, defaultInstanceId),
- providerModelPreferences: withoutProviderInstanceKey(
- settings.providerModelPreferences,
- defaultInstanceId,
- ),
- favorites: withoutProviderInstanceFavorites(settings.favorites ?? [], defaultInstanceId),
- });
- };
-
return (
<SettingsPageContainer>
<SettingsSection title="General">
@@ -1168,58 +911,406 @@ export function GeneralSettingsPanel() {
/>
</SettingsSection>
- <SettingsSection
- title="Providers"
- headerAction={
- <div className="flex items-center gap-1.5">
- <ProviderLastChecked lastCheckedAt={lastCheckedAt} />
- <Tooltip>
- <TooltipTrigger
- render={
- <Button
- size="icon-xs"
- variant="ghost"
- className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
- onClick={() => setIsAddInstanceDialogOpen(true)}
- aria-label="Add provider instance"
- >
- <PlusIcon className="size-3" />
- </Button>
- }
- />
- <TooltipPopup side="top">Add provider instance</TooltipPopup>
- </Tooltip>
- <Tooltip>
- <TooltipTrigger
- render={
- <Button
- size="icon-xs"
- variant="ghost"
- className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
- disabled={isRefreshingProviders}
- onClick={() => void refreshProviders()}
- aria-label="Refresh provider status"
- >
- {isRefreshingProviders ? (
- <LoaderIcon className="size-3 animate-spin" />
- ) : (
- <RefreshCwIcon className="size-3" />
- )}
- </Button>
- }
- />
- <TooltipPopup side="top">Refresh provider status</TooltipPopup>
- </Tooltip>
- </div>
- }
- >
- {rows.map((row) => {
- const driverOption = getDriverOption(row.driver);
- const liveProvider = serverProviders.find(
- (candidate) => candidate.instanceId === row.instanceId,
- );
- const modelPreferences = settings.providerModelPreferences?.[row.instanceId] ?? {
- hiddenModels: [],
+ <SettingsSection title="Advanced">
+ <SettingsRow
+ title="Keybindings"
+ description="Open the persisted `keybindings.json` file to edit advanced bindings directly."
+ status={
+ <>
+ <span className="block break-all font-mono text-[11px] text-foreground">
+ {keybindingsConfigPath ?? "Resolving keybindings path..."}
+ </span>
+ {openKeybindingsError ? (
+ <span className="mt-1 block text-destructive">{openKeybindingsError}</span>
+ ) : (
+ <span className="mt-1 block">Opens in your preferred editor.</span>
+ )}
+ </>
+ }
+ control={
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={!keybindingsConfigPath || isOpeningKeybindings}
+ onClick={openKeybindingsFile}
+ >
+ {isOpeningKeybindings ? "Opening..." : "Open file"}
+ </Button>
+ }
+ />
+ </SettingsSection>
+
+ <SettingsSection title="About">
+ {isElectron ? (
+ <AboutVersionSection />
+ ) : (
+ <SettingsRow
+ title={<AboutVersionTitle />}
+ description="Current version of the application."
+ />
+ )}
+ <SettingsRow
+ title="Diagnostics"
+ description={diagnosticsDescription}
+ status={
+ <>
+ <span className="block break-all font-mono text-[11px] text-foreground">
+ {logsDirectoryPath ?? "Resolving logs directory..."}
+ </span>
+ {openDiagnosticsError ? (
+ <span className="mt-1 block text-destructive">{openDiagnosticsError}</span>
+ ) : null}
+ </>
+ }
+ control={
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={!logsDirectoryPath || isOpeningLogsDirectory}
+ onClick={openLogsDirectory}
+ >
+ {isOpeningLogsDirectory ? "Opening..." : "Open logs folder"}
+ </Button>
+ }
+ />
+ </SettingsSection>
+ </SettingsPageContainer>
+ );
+}
+
+export function ProviderSettingsPanel() {
+ const settings = useSettings();
+ const { updateSettings } = useUpdateSettings();
+ const serverProviders = useServerProviders();
+ const [isRefreshingProviders, setIsRefreshingProviders] = useState(false);
+ const [isAddInstanceDialogOpen, setIsAddInstanceDialogOpen] = useState(false);
+ const [updatingProviderDrivers, setUpdatingProviderDrivers] = useState<
+ ReadonlySet<ProviderDriverKind>
+ >(() => new Set());
+ const [openInstanceDetails, setOpenInstanceDetails] = useState<Record<string, boolean>>({});
+ const refreshingRef = useRef(false);
+
+ const providerUpdateCandidates = useMemo(
+ () => collectProviderUpdateCandidates(serverProviders),
+ [serverProviders],
+ );
+ const providerUpdateCandidateByInstanceId = useMemo(
+ () => new Map(providerUpdateCandidates.map((candidate) => [candidate.instanceId, candidate])),
+ [providerUpdateCandidates],
+ );
+ const visibleProviderSettings = PROVIDER_SETTINGS.filter(
+ (providerSettings) =>
+ providerSettings.provider !== "cursor" ||
+ serverProviders.some(
+ (provider) =>
+ provider.instanceId === defaultInstanceIdForDriver(ProviderDriverKind.make("cursor")),
+ ),
+ );
+ const textGenerationModelSelection = resolveAppModelSelectionState(settings, serverProviders);
+ const textGenInstanceId = textGenerationModelSelection.instanceId;
+ const lastCheckedAt =
+ serverProviders.length > 0
+ ? serverProviders.reduce(
+ (latest, provider) => (provider.checkedAt > latest ? provider.checkedAt : latest),
+ serverProviders[0]!.checkedAt,
+ )
+ : null;
+
+ const refreshProviders = useCallback(() => {
+ if (refreshingRef.current) return;
+ refreshingRef.current = true;
+ setIsRefreshingProviders(true);
+ void ensureLocalApi()
+ .server.refreshProviders()
+ .catch((error: unknown) => {
+ console.warn("Failed to refresh providers", error);
+ })
+ .finally(() => {
+ refreshingRef.current = false;
+ setIsRefreshingProviders(false);
+ });
+ }, []);
+
+ const runProviderUpdate = useCallback(async (candidate: ProviderUpdateCandidate) => {
+ let started = false;
+ setUpdatingProviderDrivers((previous) => {
+ if (previous.has(candidate.driver)) {
+ return previous;
+ }
+ started = true;
+ const next = new Set(previous);
+ next.add(candidate.driver);
+ return next;
+ });
+ if (!started) {
+ return;
+ }
+
+ try {
+ await ensureLocalApi().server.updateProvider({
+ provider: candidate.driver,
+ instanceId: candidate.instanceId,
+ });
+ } catch (error) {
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: `Could not update ${PROVIDER_DISPLAY_NAMES[candidate.driver] ?? candidate.driver}`,
+ description:
+ error instanceof Error
+ ? error.message
+ : "The provider update command could not be started.",
+ }),
+ );
+ } finally {
+ setUpdatingProviderDrivers((previous) => {
+ if (!previous.has(candidate.driver)) {
+ return previous;
+ }
+ const next = new Set(previous);
+ next.delete(candidate.driver);
+ return next;
+ });
+ }
+ }, []);
+
+ interface InstanceRow {
+ readonly instanceId: ProviderInstanceId;
+ readonly instance: ProviderInstanceConfig;
+ readonly driver: ProviderDriverKind;
+ readonly isDefault: boolean;
+ readonly isDirty?: boolean;
+ }
+
+ const instancesByDriver = new Map<
+ ProviderDriverKind,
+ Array<[ProviderInstanceId, ProviderInstanceConfig]>
+ >();
+ for (const [rawId, instance] of Object.entries(settings.providerInstances ?? {})) {
+ const driver = instance.driver;
+ const list = instancesByDriver.get(driver) ?? [];
+ list.push([rawId as ProviderInstanceId, instance]);
+ instancesByDriver.set(driver, list);
+ }
+
+ const defaultSlotIdsBySource = new Set<string>(
+ visibleProviderSettings.map((providerSettings) =>
+ String(defaultInstanceIdForDriver(providerSettings.provider)),
+ ),
+ );
+
+ const rows: InstanceRow[] = [];
+ const visibleDriverKinds = new Set<ProviderDriverKind>(
+ visibleProviderSettings.map((providerSettings) => providerSettings.provider),
+ );
+
+ for (const providerSettings of visibleProviderSettings) {
+ type LegacyProviderSettings = (typeof settings.providers)[keyof typeof settings.providers];
+ const legacyProviders = settings.providers as Record<string, LegacyProviderSettings>;
+ const defaultLegacyProviders = DEFAULT_UNIFIED_SETTINGS.providers as Record<
+ string,
+ LegacyProviderSettings
+ >;
+ const driver = providerSettings.provider;
+ const defaultInstanceId = defaultInstanceIdForDriver(driver);
+ const explicitInstance = settings.providerInstances?.[defaultInstanceId];
+ const legacyConfig = legacyProviders[providerSettings.provider]!;
+ const defaultLegacyConfig = defaultLegacyProviders[providerSettings.provider]!;
+ const effectiveInstance: ProviderInstanceConfig =
+ explicitInstance ??
+ ({
+ driver,
+ enabled: legacyConfig.enabled,
+ config: legacyConfig,
+ } satisfies ProviderInstanceConfig);
+ const isDirty =
+ explicitInstance !== undefined || !Equal.equals(legacyConfig, defaultLegacyConfig);
+ rows.push({
+ instanceId: defaultInstanceId,
+ instance: effectiveInstance,
+ driver,
+ isDefault: true,
+ isDirty,
+ });
+ for (const [id, instance] of instancesByDriver.get(providerSettings.provider) ?? []) {
+ if (id === defaultInstanceId) continue;
+ rows.push({ instanceId: id, instance, driver: instance.driver, isDefault: false });
+ }
+ }
+ for (const [driver, list] of instancesByDriver) {
+ if (visibleDriverKinds.has(driver)) continue;
+ for (const [id, instance] of list) {
+ rows.push({
+ instanceId: id,
+ instance,
+ driver: instance.driver,
+ isDefault: defaultSlotIdsBySource.has(String(id)),
+ });
+ }
+ }
+
+ const updateProviderInstance = (
+ row: InstanceRow,
+ next: ProviderInstanceConfig,
+ options?: {
+ readonly textGenerationModelSelection?: Parameters<
+ typeof buildProviderInstanceUpdatePatch
+ >[0]["textGenerationModelSelection"];
+ },
+ ) => {
+ updateSettings(
+ buildProviderInstanceUpdatePatch({
+ settings,
+ instanceId: row.instanceId,
+ instance: next,
+ driver: row.driver,
+ isDefault: row.isDefault,
+ textGenerationModelSelection: options?.textGenerationModelSelection,
+ }),
+ );
+ };
+
+ const deleteProviderInstance = (id: ProviderInstanceId) => {
+ updateSettings({
+ providerInstances: withoutProviderInstanceKey(settings.providerInstances, id),
+ providerModelPreferences: withoutProviderInstanceKey(settings.providerModelPreferences, id),
+ favorites: withoutProviderInstanceFavorites(settings.favorites ?? [], id),
+ });
+ };
+
+ const updateProviderModelPreferences = (
+ instanceId: ProviderInstanceId,
+ next: {
+ readonly hiddenModels: ReadonlyArray<string>;
+ readonly modelOrder: ReadonlyArray<string>;
+ },
+ ) => {
+ const hiddenModels = [...new Set(next.hiddenModels.filter((slug) => slug.trim().length > 0))];
+ const modelOrder = [...new Set(next.modelOrder.filter((slug) => slug.trim().length > 0))];
+ const rest = withoutProviderInstanceKey(settings.providerModelPreferences, instanceId);
+ updateSettings({
+ providerModelPreferences:
+ hiddenModels.length === 0 && modelOrder.length === 0
+ ? rest
+ : {
+ ...rest,
+ [instanceId]: {
+ hiddenModels,
+ modelOrder,
+ },
+ },
+ });
+ };
+
+ const updateProviderFavoriteModels = (
+ instanceId: ProviderInstanceId,
+ nextFavoriteModels: ReadonlyArray<string>,
+ ) => {
+ const favoriteModels = [
+ ...new Set(nextFavoriteModels.map((slug) => slug.trim()).filter((slug) => slug.length > 0)),
+ ];
+ updateSettings({
+ favorites: [
+ ...withoutProviderInstanceFavorites(settings.favorites ?? [], instanceId),
+ ...favoriteModels.map((model) => ({ provider: instanceId, model })),
+ ],
+ });
+ };
+
+ const resetDefaultInstance = (driverKind: ProviderDriverKind) => {
+ type LegacyProviderSettings = (typeof settings.providers)[keyof typeof settings.providers];
+ const defaultLegacyProviders = DEFAULT_UNIFIED_SETTINGS.providers as Record<
+ string,
+ LegacyProviderSettings | undefined
+ >;
+ const defaultInstanceId = defaultInstanceIdForDriver(driverKind);
+ const defaultLegacyProvider = defaultLegacyProviders[driverKind];
+ if (defaultLegacyProvider === undefined) return;
+ updateSettings({
+ providers: {
+ ...settings.providers,
+ [driverKind]: defaultLegacyProvider,
+ } as typeof settings.providers,
+ providerInstances: withoutProviderInstanceKey(settings.providerInstances, defaultInstanceId),
+ providerModelPreferences: withoutProviderInstanceKey(
+ settings.providerModelPreferences,
+ defaultInstanceId,
+ ),
+ favorites: withoutProviderInstanceFavorites(settings.favorites ?? [], defaultInstanceId),
+ });
+ };
+
+ return (
+ <SettingsPageContainer>
+ <SettingsSection
+ title="Providers"
+ headerAction={
+ <div className="flex items-center gap-1.5">
+ <ProviderLastChecked lastCheckedAt={lastCheckedAt} />
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <Button
+ size="icon-xs"
+ variant="ghost"
+ className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+ onClick={() => setIsAddInstanceDialogOpen(true)}
+ aria-label="Add provider instance"
+ >
+ <PlusIcon className="size-3" />
+ </Button>
+ }
+ />
+ <TooltipPopup side="top">Add provider instance</TooltipPopup>
+ </Tooltip>
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <Button
+ size="icon-xs"
+ variant="ghost"
+ className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+ disabled={isRefreshingProviders}
+ onClick={() => void refreshProviders()}
+ aria-label="Refresh provider status"
+ >
+ {isRefreshingProviders ? (
+ <LoaderIcon className="size-3 animate-spin" />
+ ) : (
+ <RefreshCwIcon className="size-3" />
+ )}
+ </Button>
+ }
+ />
+ <TooltipPopup side="top">Refresh provider status</TooltipPopup>
+ </Tooltip>
+ </div>
+ }
+ >
+ {rows.map((row) => {
+ const driverOption = getDriverOption(row.driver);
+ const liveProvider = serverProviders.find(
+ (candidate) => candidate.instanceId === row.instanceId,
+ );
+ const updateCandidate = liveProvider
+ ? providerUpdateCandidateByInstanceId.get(liveProvider.instanceId)
+ : undefined;
+ const isDriverUpdateRunning =
+ updateCandidate !== undefined &&
+ (updatingProviderDrivers.has(updateCandidate.driver) ||
+ serverProviders.some(
+ (provider) =>
+ provider.driver === updateCandidate.driver && isProviderUpdateActive(provider),
+ ));
+ const showInlineUpdateButton =
+ updateCandidate !== undefined &&
+ hasOneClickUpdateProviderCandidate(updateCandidate, serverProviders);
+ const canRunInlineUpdate =
+ updateCandidate !== undefined &&
+ canOneClickUpdateProviderCandidate(updateCandidate, serverProviders) &&
+ !updatingProviderDrivers.has(updateCandidate.driver);
+ const modelPreferences = settings.providerModelPreferences?.[row.instanceId] ?? {
+ hiddenModels: [],
modelOrder: [],
};
const favoriteModels = (settings.favorites ?? [])
@@ -1248,13 +1339,6 @@ export function GeneralSettingsPanel() {
}))
}
onUpdate={(next) => {
- // When the user disables the exact instance the text-gen
- // selection points at, fall back to the global default so we
- // don't leave the selection dangling on a disabled instance.
- // Prior kind-level behavior cleared on any kind-matching
- // disable; instance-level addressing makes this narrower and
- // more accurate (other instances of the same kind stay
- // untouched).
const wasEnabled = row.instance.enabled ?? true;
const isDisabling = next.enabled === false && wasEnabled;
const shouldClearTextGen = isDisabling && textGenInstanceId === row.instanceId;
@@ -1287,6 +1371,17 @@ export function GeneralSettingsPanel() {
modelOrder,
})
}
+ onRunUpdate={
+ showInlineUpdateButton && updateCandidate
+ ? () => {
+ if (!canRunInlineUpdate) {
+ return;
+ }
+ void runProviderUpdate(updateCandidate);
+ }
+ : undefined
+ }
+ isUpdating={showInlineUpdateButton ? isDriverUpdateRunning : undefined}
/>
);
})}
@@ -1296,70 +1391,6 @@ export function GeneralSettingsPanel() {
open={isAddInstanceDialogOpen}
onOpenChange={setIsAddInstanceDialogOpen}
/>
-
- <SettingsSection title="Advanced">
- <SettingsRow
- title="Keybindings"
- description="Open the persisted `keybindings.json` file to edit advanced bindings directly."
- status={
- <>
- <span className="block break-all font-mono text-[11px] text-foreground">
- {keybindingsConfigPath ?? "Resolving keybindings path..."}
- </span>
- {openKeybindingsError ? (
- <span className="mt-1 block text-destructive">{openKeybindingsError}</span>
- ) : (
- <span className="mt-1 block">Opens in your preferred editor.</span>
- )}
- </>
- }
- control={
- <Button
- size="xs"
- variant="outline"
- disabled={!keybindingsConfigPath || isOpeningKeybindings}
- onClick={openKeybindingsFile}
- >
- {isOpeningKeybindings ? "Opening..." : "Open file"}
- </Button>
- }
- />
- </SettingsSection>
-
- <SettingsSection title="About">
- {isElectron ? (
- <AboutVersionSection />
- ) : (
- <SettingsRow
- title={<AboutVersionTitle />}
- description="Current version of the application."
- />
- )}
- <SettingsRow
- title="Diagnostics"
- description={diagnosticsDescription}
- status={
- <>
- <span className="block break-all font-mono text-[11px] text-foreground">
- {logsDirectoryPath ?? "Resolving logs directory..."}
- </span>
- {openDiagnosticsError ? (
- <span className="mt-1 block text-destructive">{openDiagnosticsError}</span>
- ) : null}
- </>
- }
- control={
- <Button
- size="xs"
- variant="outline"
- disabled={!logsDirectoryPath || isOpeningLogsDirectory}
- onClick={openLogsDirectory}
- >
- {isOpeningLogsDirectory ? "Opening..." : "Open logs folder"}
- </Button>
- }
- />
- </SettingsSection>
</SettingsPageContainer>
);
}
diff --git a/apps/web/src/components/settings/SettingsSidebarNav.tsx b/apps/web/src/components/settings/SettingsSidebarNav.tsx
index 88260355d..fc0e5a2b4 100644
--- a/apps/web/src/components/settings/SettingsSidebarNav.tsx
+++ b/apps/web/src/components/settings/SettingsSidebarNav.tsx
@@ -1,5 +1,12 @@
import { useCallback, type ComponentType } from "react";
-import { ArchiveIcon, ArrowLeftIcon, GitBranchIcon, Link2Icon, Settings2Icon } from "lucide-react";
+import {
+ ArchiveIcon,
+ ArrowLeftIcon,
+ BotIcon,
+ GitBranchIcon,
+ Link2Icon,
+ Settings2Icon,
+} from "lucide-react";
import { useCanGoBack, useNavigate } from "@tanstack/react-router";
import {
@@ -15,6 +22,7 @@ import {
export type SettingsSectionPath =
| "/settings/general"
+ | "/settings/providers"
| "/settings/source-control"
| "/settings/connections"
| "/settings/archived";
@@ -25,6 +33,7 @@ export const SETTINGS_NAV_ITEMS: ReadonlyArray<{
icon: ComponentType<{ className?: string }>;
}> = [
{ label: "General", to: "/settings/general", icon: Settings2Icon },
+ { label: "Providers", to: "/settings/providers", icon: BotIcon },
{ label: "Source Control", to: "/settings/source-control", icon: GitBranchIcon },
{ label: "Connections", to: "/settings/connections", icon: Link2Icon },
{ label: "Archive", to: "/settings/archived", icon: ArchiveIcon },
diff --git a/apps/web/src/components/settings/providerStatus.ts b/apps/web/src/components/settings/providerStatus.ts
index d437399da..06622a761 100644
--- a/apps/web/src/components/settings/providerStatus.ts
+++ b/apps/web/src/components/settings/providerStatus.ts
@@ -1,4 +1,4 @@
-import type { ServerProvider } from "@t3tools/contracts";
+import type { ServerProvider, ServerProviderVersionAdvisory } from "@t3tools/contracts";
/**
* Visual treatment for each server-reported provider status. Centralized so
@@ -89,3 +89,29 @@ export function getProviderVersionLabel(version: string | null | undefined) {
if (!version) return null;
return version.startsWith("v") ? version : `v${version}`;
}
+
+export function getProviderVersionAdvisoryPresentation(
+ advisory: ServerProviderVersionAdvisory | undefined,
+): {
+ readonly detail: string;
+ readonly updateCommand: string | null;
+ readonly emphasis: "normal" | "strong";
+} | null {
+ if (!advisory || advisory.status === "current" || advisory.status === "unknown") {
+ return null;
+ }
+
+ const label = "Update available";
+ const version = advisory.latestVersion;
+ const versionLabel = getProviderVersionLabel(version);
+
+ return {
+ detail:
+ advisory.message ??
+ (versionLabel
+ ? `${label}: install ${versionLabel}.`
+ : `${label}: install the latest provider version.`),
+ updateCommand: advisory.updateCommand,
+ emphasis: "normal" as const,
+ };
+}
diff --git a/apps/web/src/components/settings/settingsLayout.tsx b/apps/web/src/components/settings/settingsLayout.tsx
index c464165bb..34197e8d8 100644
--- a/apps/web/src/components/settings/settingsLayout.tsx
+++ b/apps/web/src/components/settings/settingsLayout.tsx
@@ -1,5 +1,5 @@
import { Undo2Icon } from "lucide-react";
-import { type ReactNode, useEffect, useState } from "react";
+import { type ComponentPropsWithoutRef, type ReactNode, useEffect, useState } from "react";
import { cn } from "../../lib/utils";
import { Button } from "../ui/button";
@@ -20,15 +20,17 @@ export function SettingsSection({
icon,
headerAction,
children,
-}: {
+ className,
+ ...sectionProps
+}: ComponentPropsWithoutRef<"section"> & {
title: string;
icon?: ReactNode;
headerAction?: ReactNode;
children: ReactNode;
}) {
return (
- <section className="space-y-2.5">
- <div className="flex h-5 items-center justify-between px-1">
+ <section {...sectionProps} className={cn("space-y-2.5", className)}>
+ <div className="flex items-center justify-between px-1">
<h2 className="flex items-center gap-2 text-[11px] font-semibold uppercase tracking-[0.08em] text-foreground/50">
<span className="inline-block h-px w-3 bg-border" aria-hidden />
{icon}
@@ -62,7 +64,7 @@ export function SettingsRow({
<div
className={cn(
"border-t border-border/60 px-4 first:border-t-0 sm:px-5",
- children ? "pt-4 pb-0" : "py-4",
+ children ? "pt-3.5 pb-0" : "py-3.5",
)}
>
<div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
@@ -75,7 +77,7 @@ export function SettingsRow({
{resetAction}
</span>
</div>
- <p className="text-xs leading-relaxed text-muted-foreground/80">{description}</p>
+ <p className="text-xs text-muted-foreground/80">{description}</p>
{status ? <div className="pt-0.5 text-[11px] text-muted-foreground">{status}</div> : null}
</div>
{control ? (
diff --git a/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx b/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx
new file mode 100644
index 000000000..d5b1b9bdd
--- /dev/null
+++ b/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx
@@ -0,0 +1,207 @@
+import { useNavigate } from "@tanstack/react-router";
+import type { ServerProvider } from "@t3tools/contracts";
+import { CircleCheckIcon, DownloadIcon, LoaderIcon, TriangleAlertIcon, XIcon } from "lucide-react";
+import { useCallback, useEffect, useState, type CSSProperties } from "react";
+
+import { useServerProviders } from "../../rpc/serverState";
+import {
+ getProviderUpdateSidebarPillView,
+ type ProviderUpdateSidebarPillView,
+} from "../ProviderUpdateLaunchNotification.logic";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+
+const PROVIDER_UPDATE_PILL_STYLES = {
+ loading:
+ "bg-primary/15 text-primary group-has-[button.provider-update-main:hover]/provider-update:bg-primary/22",
+ success:
+ "bg-success/12 text-success group-has-[button.provider-update-main:hover]/provider-update:bg-success/18",
+ warning:
+ "bg-warning/12 text-warning group-has-[button.provider-update-main:hover]/provider-update:bg-warning/18",
+ error:
+ "bg-destructive/12 text-destructive group-has-[button.provider-update-main:hover]/provider-update:bg-destructive/18",
+} as const;
+
+const PROVIDER_UPDATE_PILL_PROGRESS_STYLES = {
+ success: "bg-success/18",
+ warning: "bg-warning/14",
+ error: "bg-destructive/14",
+} as const;
+
+function latestProviderCheckedAt(
+ providers: ReadonlyArray<Pick<ServerProvider, "checkedAt">>,
+): string | undefined {
+ return providers.reduce<string | undefined>(
+ (latest, provider) =>
+ latest === undefined || provider.checkedAt > latest ? provider.checkedAt : latest,
+ undefined,
+ );
+}
+
+export function SidebarProviderUpdatePill() {
+ const navigate = useNavigate();
+ const providers = useServerProviders();
+ const [dismissedKeys, setDismissedKeys] = useState<ReadonlySet<string>>(() => new Set());
+ const [renderedView, setRenderedView] = useState<ProviderUpdateSidebarPillView | null>(null);
+ const [pendingView, setPendingView] = useState<ProviderUpdateSidebarPillView | null>(null);
+ const [exitingKey, setExitingKey] = useState<string | null>(null);
+ const [dismissAfterExitKey, setDismissAfterExitKey] = useState<string | null>(null);
+ const [visibleAfterIso, setVisibleAfterIso] = useState<string | undefined>();
+ const effectiveVisibleAfterIso = visibleAfterIso ?? latestProviderCheckedAt(providers);
+ const view = getProviderUpdateSidebarPillView(providers, {
+ ...(effectiveVisibleAfterIso !== undefined
+ ? { visibleAfterIso: effectiveVisibleAfterIso }
+ : {}),
+ dismissedKeys,
+ });
+
+ useEffect(() => {
+ if (visibleAfterIso === undefined && effectiveVisibleAfterIso !== undefined) {
+ setVisibleAfterIso(effectiveVisibleAfterIso);
+ }
+ }, [effectiveVisibleAfterIso, visibleAfterIso]);
+
+ const openProviderSettings = useCallback(() => {
+ void navigate({ to: "/settings/providers" });
+ }, [navigate]);
+ const displayedView = renderedView ?? view;
+ const dismissAfterVisibleMs = displayedView?.dismissAfterVisibleMs;
+ const viewKey = displayedView?.key ?? null;
+ const showDismissProgress =
+ dismissAfterVisibleMs !== undefined &&
+ displayedView?.tone !== "loading" &&
+ exitingKey !== viewKey;
+
+ const startExit = useCallback(
+ (key: string, nextView: ProviderUpdateSidebarPillView | null, dismissKey?: string) => {
+ if (exitingKey === key) {
+ return;
+ }
+ setPendingView(nextView);
+ setExitingKey(key);
+ setDismissAfterExitKey(dismissKey ?? null);
+ },
+ [exitingKey],
+ );
+
+ useEffect(() => {
+ if (exitingKey !== null) {
+ return;
+ }
+ if (!renderedView) {
+ if (view) {
+ setRenderedView(view);
+ }
+ return;
+ }
+ if (!view) {
+ startExit(renderedView.key, null);
+ return;
+ }
+ if (view.key !== renderedView.key) {
+ startExit(renderedView.key, view);
+ return;
+ }
+ }, [exitingKey, renderedView, startExit, view]);
+
+ useEffect(() => {
+ if (!dismissAfterVisibleMs || !viewKey) {
+ return;
+ }
+ if (exitingKey === viewKey) {
+ return;
+ }
+ const timeoutId = window.setTimeout(() => {
+ startExit(viewKey, null, viewKey);
+ }, dismissAfterVisibleMs);
+
+ return () => window.clearTimeout(timeoutId);
+ }, [dismissAfterVisibleMs, exitingKey, startExit, viewKey]);
+
+ if (!displayedView) {
+ return null;
+ }
+
+ return (
+ <div
+ className={`group/provider-update relative flex h-7 w-full items-center overflow-hidden rounded-lg text-xs font-medium transform-gpu transition-all duration-180 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform ${
+ PROVIDER_UPDATE_PILL_STYLES[displayedView.tone]
+ } ${
+ exitingKey === displayedView.key
+ ? "pointer-events-none translate-y-1.5 opacity-0"
+ : "translate-y-0 opacity-100"
+ }`}
+ onTransitionEnd={(event) => {
+ if (event.target !== event.currentTarget) {
+ return;
+ }
+ if (!displayedView || exitingKey !== displayedView.key) {
+ return;
+ }
+ if (dismissAfterExitKey === displayedView.key) {
+ setDismissedKeys((previous) => new Set(previous).add(displayedView.key));
+ }
+ setRenderedView(pendingView);
+ setPendingView(null);
+ setExitingKey(null);
+ setDismissAfterExitKey(null);
+ }}
+ >
+ {showDismissProgress ? (
+ <div
+ key={displayedView.key}
+ aria-hidden="true"
+ className={`provider-update-pill-progress pointer-events-none absolute inset-y-0 left-0 w-full origin-left border-r border-current/15 shadow-[inset_0_1px_0_rgb(255_255_255_/_0.08)] ${
+ PROVIDER_UPDATE_PILL_PROGRESS_STYLES[displayedView.tone]
+ }`}
+ style={
+ {
+ "--provider-update-pill-dismiss-ms": `${dismissAfterVisibleMs}ms`,
+ } as CSSProperties
+ }
+ />
+ ) : null}
+ <div className="pointer-events-none absolute inset-0 rounded-lg transition-colors" />
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <button
+ type="button"
+ aria-label={displayedView.description}
+ className="provider-update-main relative z-[1] flex h-full flex-1 items-center gap-2 px-2 text-left"
+ onClick={openProviderSettings}
+ >
+ {displayedView.tone === "loading" ? (
+ <LoaderIcon className="size-3.5 animate-spin" />
+ ) : displayedView.tone === "success" ? (
+ <CircleCheckIcon className="size-3.5" />
+ ) : displayedView.tone === "error" ? (
+ <TriangleAlertIcon className="size-3.5" />
+ ) : (
+ <DownloadIcon className="size-3.5" />
+ )}
+ <span>{displayedView.title}</span>
+ </button>
+ }
+ />
+ <TooltipPopup side="top">{displayedView.description}</TooltipPopup>
+ </Tooltip>
+ {displayedView.dismissible && (
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <button
+ type="button"
+ aria-label="Dismiss provider update notice"
+ className="relative z-[1] mr-1 inline-flex size-5 items-center justify-center rounded-md opacity-70 transition-opacity hover:opacity-100"
+ onClick={() => startExit(displayedView.key, null, displayedView.key)}
+ >
+ <XIcon className="size-3.5" />
+ </button>
+ }
+ />
+ <TooltipPopup side="top">Dismiss until provider status changes</TooltipPopup>
+ </Tooltip>
+ )}
+ </div>
+ );
+}
diff --git a/apps/web/src/components/ui/toast.tsx b/apps/web/src/components/ui/toast.tsx
index dd0eba432..0ebf0c8a7 100644
--- a/apps/web/src/components/ui/toast.tsx
+++ b/apps/web/src/components/ui/toast.tsx
@@ -6,6 +6,7 @@ import {
useMemo,
useState,
type CSSProperties,
+ type ComponentPropsWithoutRef,
type KeyboardEvent,
type ReactNode,
} from "react";
@@ -38,9 +39,20 @@ import {
export type ThreadToastData = {
threadRef?: ScopedThreadRef | null;
threadId?: ThreadId | null;
+ leadingIcon?: ReactNode;
tooltipStyle?: boolean;
+ onClose?: (() => void) | undefined;
dismissAfterVisibleMs?: number;
hideCopyButton?: boolean;
+ secondaryActionProps?: ComponentPropsWithoutRef<"button">;
+ secondaryActionVariant?:
+ | "default"
+ | "destructive"
+ | "destructive-outline"
+ | "ghost"
+ | "link"
+ | "outline"
+ | "secondary";
/** Optional extra body shown after toggling “Show details” (e.g. a list of pending RPCs). */
expandableContent?: ReactNode;
expandableLabels?: { expand?: string; collapse?: string };
@@ -90,6 +102,15 @@ const toastCornerOrbClass = cn(
"focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
);
+function handleToastDismissClick(
+ manager: typeof toastManager | typeof anchoredToastManager,
+ toastId: ToastId,
+ onClose: (() => void) | undefined,
+) {
+ onClose?.();
+ manager.close(toastId);
+}
+
function CopyErrorButton({ text }: { text: string }) {
const { copyToClipboard, isCopied } = useCopyToClipboard();
@@ -232,6 +253,7 @@ interface ToastBodyDescriptor {
readonly Icon: ToastIconComponent | null | undefined;
readonly stackedActionLayout: boolean;
readonly actionVariant: NonNullable<ThreadToastData["actionVariant"]>;
+ readonly secondaryActionVariant: NonNullable<ThreadToastData["secondaryActionVariant"]>;
readonly copyErrorText: string | null;
readonly hasTrailingControls: boolean;
readonly inlineContentEndPad: string;
@@ -248,16 +270,21 @@ function deriveToastBodyDescriptor(toast: {
toast.actionProps !== undefined && toast.data?.actionLayout === "stacked-end";
const actionVariant: NonNullable<ThreadToastData["actionVariant"]> =
toast.data?.actionVariant ?? "default";
+ const secondaryActionVariant: NonNullable<ThreadToastData["secondaryActionVariant"]> =
+ toast.data?.secondaryActionVariant ?? "outline";
const copyErrorText =
toast.type === "error" && typeof toast.description === "string" && !toast.data?.hideCopyButton
? toast.description
: null;
- const hasTrailingControls = copyErrorText !== null || toast.actionProps !== undefined;
+ const hasSecondaryAction = toast.data?.secondaryActionProps !== undefined;
+ const hasTrailingControls =
+ copyErrorText !== null || toast.actionProps !== undefined || hasSecondaryAction;
const inlineContentEndPad = hasTrailingControls ? "pr-6" : "pr-10";
return {
Icon,
stackedActionLayout,
actionVariant,
+ secondaryActionVariant,
copyErrorText,
hasTrailingControls,
inlineContentEndPad,
@@ -277,22 +304,35 @@ function ToastBodyContent({
copyErrorText,
actionProps,
actionVariant,
+ secondaryActionVariant,
hasTrailingControls,
toastData,
toastDescription,
toastType,
}: ToastBodyContentProps) {
+ const secondaryActionProps = toastData?.secondaryActionProps;
+ const leadingIcon = toastData?.leadingIcon;
+ const { className: secondaryActionClassName, ...secondaryActionRest } =
+ secondaryActionProps ?? {};
+
return (
<>
<div className={cn("flex min-w-0 gap-2", !stackedActionLayout && "flex-1")}>
- {Icon && (
+ {leadingIcon ? (
+ <div
+ className="flex h-lh w-4 shrink-0 items-center justify-center"
+ data-slot="toast-icon"
+ >
+ {leadingIcon}
+ </div>
+ ) : Icon ? (
<div
className="[&>svg]:h-lh [&>svg]:w-4 [&_svg]:pointer-events-none [&_svg]:shrink-0"
data-slot="toast-icon"
>
<Icon className="in-data-[type=loading]:animate-spin in-data-[type=error]:text-destructive in-data-[type=info]:text-info in-data-[type=success]:text-success in-data-[type=warning]:text-warning in-data-[type=loading]:opacity-80" />
</div>
- )}
+ ) : null}
<div
className={cn(
"flex min-h-0 min-w-0 flex-1 flex-col gap-0.5",
@@ -315,6 +355,16 @@ function ToastBodyContent({
)}
>
{copyErrorText !== null ? <CopyErrorButton text={copyErrorText} /> : null}
+ {secondaryActionProps ? (
+ <button
+ {...secondaryActionRest}
+ className={cn(
+ buttonVariants({ size: "xs", variant: secondaryActionVariant }),
+ secondaryActionClassName,
+ )}
+ type="button"
+ />
+ ) : null}
{actionProps ? (
<Toast.Action
className={cn(buttonVariants({ size: "xs", variant: actionVariant }), "shrink-0")}
@@ -579,7 +629,9 @@ function Toasts({ position = "top-right" }: { position: ToastPosition }) {
aria-label="Dismiss notification"
className={toastCornerOrbClass}
data-slot="toast-close"
- onClick={() => toastManager.close(toast.id)}
+ onClick={() =>
+ handleToastDismissClick(toastManager, toast.id, toast.data?.onClose)
+ }
type="button"
>
<XIcon className="size-3" strokeWidth={2.25} />
@@ -670,7 +722,13 @@ function AnchoredToasts() {
aria-label="Dismiss notification"
className={toastCornerOrbClass}
data-slot="toast-close"
- onClick={() => anchoredToastManager.close(toast.id)}
+ onClick={() =>
+ handleToastDismissClick(
+ anchoredToastManager,
+ toast.id,
+ toast.data?.onClose,
+ )
+ }
type="button"
>
<XIcon className="size-3" strokeWidth={2.25} />
diff --git a/apps/web/src/hooks/useSettings.ts b/apps/web/src/hooks/useSettings.ts
index 37a6872bd..6541bb7a8 100644
--- a/apps/web/src/hooks/useSettings.ts
+++ b/apps/web/src/hooks/useSettings.ts
@@ -26,6 +26,7 @@ import { applySettingsUpdated, getServerConfig, useServerSettings } from "~/rpc/
const CLIENT_SETTINGS_PERSISTENCE_ERROR_SCOPE = "[CLIENT_SETTINGS]";
const clientSettingsListeners = new Set<() => void>();
+const clientSettingsHydrationListeners = new Set<() => void>();
let clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
let clientSettingsHydrated = false;
let clientSettingsHydrationPromise: Promise<void> | null = null;
@@ -36,6 +37,12 @@ function emitClientSettingsChange() {
}
}
+function emitClientSettingsHydrationChange() {
+ for (const listener of clientSettingsHydrationListeners) {
+ listener();
+ }
+}
+
function getClientSettingsSnapshot(): ClientSettings {
return clientSettingsSnapshot;
}
@@ -45,6 +52,14 @@ function replaceClientSettingsSnapshot(settings: ClientSettings): void {
emitClientSettingsChange();
}
+function setClientSettingsHydrated(nextHydrated: boolean): void {
+ if (clientSettingsHydrated === nextHydrated) {
+ return;
+ }
+ clientSettingsHydrated = nextHydrated;
+ emitClientSettingsHydrationChange();
+}
+
function subscribeClientSettings(listener: () => void): () => void {
clientSettingsListeners.add(listener);
void hydrateClientSettings();
@@ -53,6 +68,18 @@ function subscribeClientSettings(listener: () => void): () => void {
};
}
+function getClientSettingsHydratedSnapshot(): boolean {
+ return clientSettingsHydrated;
+}
+
+function subscribeClientSettingsHydration(listener: () => void): () => void {
+ clientSettingsHydrationListeners.add(listener);
+ void hydrateClientSettings();
+ return () => {
+ clientSettingsHydrationListeners.delete(listener);
+ };
+}
+
async function hydrateClientSettings(): Promise<void> {
if (clientSettingsHydrated) {
return;
@@ -70,7 +97,7 @@ async function hydrateClientSettings(): Promise<void> {
} catch (error) {
console.error(`${CLIENT_SETTINGS_PERSISTENCE_ERROR_SCOPE} hydrate failed`, error);
} finally {
- clientSettingsHydrated = true;
+ setClientSettingsHydrated(true);
}
})();
@@ -132,6 +159,14 @@ export function getClientSettings(): ClientSettings {
return getClientSettingsSnapshot();
}
+export function useClientSettingsHydrated(): boolean {
+ return useSyncExternalStore(
+ subscribeClientSettingsHydration,
+ getClientSettingsHydratedSnapshot,
+ () => false,
+ );
+}
+
export function useSettings<T = UnifiedSettings>(selector?: (s: UnifiedSettings) => T): T {
const serverSettings = useServerSettings();
const clientSettings = useSyncExternalStore(
@@ -193,4 +228,5 @@ export function __resetClientSettingsPersistenceForTests(): void {
clientSettingsHydrated = false;
clientSettingsHydrationPromise = null;
clientSettingsListeners.clear();
+ clientSettingsHydrationListeners.clear();
}
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index edf71b675..0f0417d43 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -485,6 +485,19 @@ label:has(> select#reasoning-effort) select {
text-align: left;
}
+@keyframes provider-update-pill-countdown {
+ from {
+ transform: scaleX(1);
+ }
+ to {
+ transform: scaleX(0);
+ }
+}
+
+.provider-update-pill-progress {
+ animation: provider-update-pill-countdown var(--provider-update-pill-dismiss-ms) linear forwards;
+}
+
/* Diffs theme bridge (match diff surfaces to app palette) */
.diff-panel-viewport {
background: color-mix(in srgb, var(--background) 94%, var(--card));
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 895163cf1..a4dd3b825 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -85,6 +85,7 @@ const rpcClientMock = {
server: {
getConfig: vi.fn(),
refreshProviders: vi.fn(),
+ updateProvider: vi.fn(),
upsertKeybinding: vi.fn(),
getSettings: vi.fn(),
updateSettings: vi.fn(),
@@ -514,6 +515,34 @@ describe("wsApi", () => {
expect(rpcClientMock.server.refreshProviders).toHaveBeenCalledWith();
});
+ it("forwards provider updates directly to the RPC client", async () => {
+ const nextProviders: ReadonlyArray<ServerProvider> = [
+ {
+ ...defaultProviders[0]!,
+ updateState: {
+ status: "succeeded",
+ startedAt: "2026-01-03T00:00:00.000Z",
+ finishedAt: "2026-01-03T00:00:01.000Z",
+ message: "Provider updated.",
+ output: null,
+ },
+ },
+ ];
+ rpcClientMock.server.updateProvider.mockResolvedValue({ providers: nextProviders });
+ const { createLocalApi } = await import("./localApi");
+
+ const api = createLocalApi(rpcClientMock as never);
+
+ await expect(
+ api.server.updateProvider({ provider: ProviderDriverKind.make("codex") }),
+ ).resolves.toEqual({
+ providers: nextProviders,
+ });
+ expect(rpcClientMock.server.updateProvider).toHaveBeenCalledWith({
+ provider: ProviderDriverKind.make("codex"),
+ });
+ });
+
it("forwards server settings updates directly to the RPC client", async () => {
const nextSettings = {
...DEFAULT_SERVER_SETTINGS,
@@ -573,6 +602,7 @@ describe("wsApi", () => {
autoOpenPlanSidebar: false,
confirmThreadArchive: true,
confirmThreadDelete: false,
+ dismissedProviderUpdateNotificationKeys: [],
diffIgnoreWhitespace: true,
diffWordWrap: true,
favorites: [],
@@ -634,6 +664,7 @@ describe("wsApi", () => {
autoOpenPlanSidebar: false,
confirmThreadArchive: true,
confirmThreadDelete: false,
+ dismissedProviderUpdateNotificationKeys: [],
diffIgnoreWhitespace: true,
diffWordWrap: true,
favorites: [],
diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index c9120e53b..2dc140eac 100644
--- a/apps/web/src/localApi.ts
+++ b/apps/web/src/localApi.ts
@@ -125,6 +125,10 @@ function createBrowserLocalApi(rpcClient?: WsRpcClient): LocalApi {
rpcClient
? rpcClient.server.refreshProviders()
: Promise.reject(unavailableLocalBackendError()),
+ updateProvider: (input) =>
+ rpcClient
+ ? rpcClient.server.updateProvider(input)
+ : Promise.reject(unavailableLocalBackendError()),
upsertKeybinding: (input) =>
rpcClient
? rpcClient.server.upsertKeybinding(input)
diff --git a/apps/web/src/providerUpdateDismissal.test.ts b/apps/web/src/providerUpdateDismissal.test.ts
new file mode 100644
index 000000000..bb528b451
--- /dev/null
+++ b/apps/web/src/providerUpdateDismissal.test.ts
@@ -0,0 +1,23 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { removeLocalStorageItem } from "./hooks/useLocalStorage";
+import {
+ dismissProviderUpdateNotification,
+ isProviderUpdateNotificationDismissed,
+ PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY,
+} from "./providerUpdateDismissal";
+
+describe("providerUpdateDismissal", () => {
+ beforeEach(() => {
+ removeLocalStorageItem(PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY);
+ });
+
+ it("persists provider update dismissals by notification key", () => {
+ expect(isProviderUpdateNotificationDismissed("opencode:1.14.33")).toBe(false);
+
+ dismissProviderUpdateNotification("opencode:1.14.33");
+
+ expect(isProviderUpdateNotificationDismissed("opencode:1.14.33")).toBe(true);
+ expect(isProviderUpdateNotificationDismissed("opencode:1.14.34")).toBe(false);
+ });
+});
diff --git a/apps/web/src/providerUpdateDismissal.ts b/apps/web/src/providerUpdateDismissal.ts
new file mode 100644
index 000000000..7cce819cc
--- /dev/null
+++ b/apps/web/src/providerUpdateDismissal.ts
@@ -0,0 +1,92 @@
+import { useCallback, useMemo } from "react";
+import * as Schema from "effect/Schema";
+
+import { getLocalStorageItem, setLocalStorageItem, useLocalStorage } from "./hooks/useLocalStorage";
+
+export const PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY = "t3code:provider-update-dismissals:v1";
+
+const ProviderUpdateDismissalsSchema = Schema.Struct({
+ keys: Schema.Array(Schema.String),
+});
+
+type ProviderUpdateDismissals = typeof ProviderUpdateDismissalsSchema.Type;
+
+function readProviderUpdateDismissals(): ProviderUpdateDismissals {
+ try {
+ return (
+ getLocalStorageItem(
+ PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY,
+ ProviderUpdateDismissalsSchema,
+ ) ?? {
+ keys: [],
+ }
+ );
+ } catch {
+ return { keys: [] };
+ }
+}
+
+function writeProviderUpdateDismissals(document: ProviderUpdateDismissals): void {
+ try {
+ setLocalStorageItem(
+ PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY,
+ document,
+ ProviderUpdateDismissalsSchema,
+ );
+ } catch {
+ // Dismissal state is best-effort UI state; a storage failure should not block the toast.
+ }
+}
+
+export function isProviderUpdateNotificationDismissed(
+ dismissalKey: string | null | undefined,
+): boolean {
+ if (!dismissalKey) {
+ return false;
+ }
+ return readProviderUpdateDismissals().keys.includes(dismissalKey);
+}
+
+export function dismissProviderUpdateNotification(dismissalKey: string | null | undefined): void {
+ const trimmedKey = dismissalKey?.trim();
+ if (!trimmedKey) {
+ return;
+ }
+ const document = readProviderUpdateDismissals();
+ if (document.keys.includes(trimmedKey)) {
+ return;
+ }
+ writeProviderUpdateDismissals({
+ keys: [...document.keys, trimmedKey],
+ });
+}
+
+export function useDismissedProviderUpdateNotificationKeys() {
+ const [dismissals, setDismissals] = useLocalStorage(
+ PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY,
+ { keys: [] },
+ ProviderUpdateDismissalsSchema,
+ );
+ const dismissedKeys = dismissals.keys;
+
+ const dismissedKeySet = useMemo(() => new Set(dismissedKeys), [dismissedKeys]);
+
+ const dismissNotificationKey = useCallback(
+ (key: string) => {
+ const trimmedKey = key.trim();
+ if (trimmedKey.length === 0 || dismissedKeySet.has(trimmedKey)) {
+ return;
+ }
+
+ setDismissals({
+ keys: [...dismissedKeys, trimmedKey],
+ });
+ },
+ [dismissedKeySet, dismissedKeys, setDismissals],
+ );
+
+ return {
+ dismissedNotificationKeys: dismissedKeySet,
+ dismissNotificationKey,
+ };
+}
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index f5844f2c9..1f711ac7d 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -14,6 +14,7 @@ import { Route as PairRouteImport } from './routes/pair'
import { Route as ChatRouteImport } from './routes/_chat'
import { Route as ChatIndexRouteImport } from './routes/_chat.index'
import { Route as SettingsSourceControlRouteImport } from './routes/settings.source-control'
+import { Route as SettingsProvidersRouteImport } from './routes/settings.providers'
import { Route as SettingsGeneralRouteImport } from './routes/settings.general'
import { Route as SettingsConnectionsRouteImport } from './routes/settings.connections'
import { Route as SettingsArchivedRouteImport } from './routes/settings.archived'
@@ -44,6 +45,11 @@ const SettingsSourceControlRoute = SettingsSourceControlRouteImport.update({
path: '/source-control',
getParentRoute: () => SettingsRoute,
} as any)
+const SettingsProvidersRoute = SettingsProvidersRouteImport.update({
+ id: '/providers',
+ path: '/providers',
+ getParentRoute: () => SettingsRoute,
+} as any)
const SettingsGeneralRoute = SettingsGeneralRouteImport.update({
id: '/general',
path: '/general',
@@ -78,6 +84,7 @@ export interface FileRoutesByFullPath {
'/settings/archived': typeof SettingsArchivedRoute
'/settings/connections': typeof SettingsConnectionsRoute
'/settings/general': typeof SettingsGeneralRoute
+ '/settings/providers': typeof SettingsProvidersRoute
'/settings/source-control': typeof SettingsSourceControlRoute
'/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
'/draft/$draftId': typeof ChatDraftDraftIdRoute
@@ -88,6 +95,7 @@ export interface FileRoutesByTo {
'/settings/archived': typeof SettingsArchivedRoute
'/settings/connections': typeof SettingsConnectionsRoute
'/settings/general': typeof SettingsGeneralRoute
+ '/settings/providers': typeof SettingsProvidersRoute
'/settings/source-control': typeof SettingsSourceControlRoute
'/': typeof ChatIndexRoute
'/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
@@ -101,6 +109,7 @@ export interface FileRoutesById {
'/settings/archived': typeof SettingsArchivedRoute
'/settings/connections': typeof SettingsConnectionsRoute
'/settings/general': typeof SettingsGeneralRoute
+ '/settings/providers': typeof SettingsProvidersRoute
'/settings/source-control': typeof SettingsSourceControlRoute
'/_chat/': typeof ChatIndexRoute
'/_chat/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
@@ -115,6 +124,7 @@ export interface FileRouteTypes {
| '/settings/archived'
| '/settings/connections'
| '/settings/general'
+ | '/settings/providers'
| '/settings/source-control'
| '/$environmentId/$threadId'
| '/draft/$draftId'
@@ -125,6 +135,7 @@ export interface FileRouteTypes {
| '/settings/archived'
| '/settings/connections'
| '/settings/general'
+ | '/settings/providers'
| '/settings/source-control'
| '/'
| '/$environmentId/$threadId'
@@ -137,6 +148,7 @@ export interface FileRouteTypes {
| '/settings/archived'
| '/settings/connections'
| '/settings/general'
+ | '/settings/providers'
| '/settings/source-control'
| '/_chat/'
| '/_chat/$environmentId/$threadId'
@@ -186,6 +198,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof SettingsSourceControlRouteImport
parentRoute: typeof SettingsRoute
}
+ '/settings/providers': {
+ id: '/settings/providers'
+ path: '/providers'
+ fullPath: '/settings/providers'
+ preLoaderRoute: typeof SettingsProvidersRouteImport
+ parentRoute: typeof SettingsRoute
+ }
'/settings/general': {
id: '/settings/general'
path: '/general'
@@ -242,6 +261,7 @@ interface SettingsRouteChildren {
SettingsArchivedRoute: typeof SettingsArchivedRoute
SettingsConnectionsRoute: typeof SettingsConnectionsRoute
SettingsGeneralRoute: typeof SettingsGeneralRoute
+ SettingsProvidersRoute: typeof SettingsProvidersRoute
SettingsSourceControlRoute: typeof SettingsSourceControlRoute
}
@@ -249,6 +269,7 @@ const SettingsRouteChildren: SettingsRouteChildren = {
SettingsArchivedRoute: SettingsArchivedRoute,
SettingsConnectionsRoute: SettingsConnectionsRoute,
SettingsGeneralRoute: SettingsGeneralRoute,
+ SettingsProvidersRoute: SettingsProvidersRoute,
SettingsSourceControlRoute: SettingsSourceControlRoute,
}
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 58617589d..e848b4f05 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -14,6 +14,7 @@ import { APP_DISPLAY_NAME } from "../branding";
import { AppSidebarLayout } from "../components/AppSidebarLayout";
import { CommandPalette } from "../components/CommandPalette";
import { SshPasswordPromptDialog } from "../components/desktop/SshPasswordPromptDialog";
+import { ProviderUpdateLaunchNotification } from "../components/ProviderUpdateLaunchNotification";
import {
SlowRpcAckToastCoordinator,
WebSocketConnectionCoordinator,
@@ -136,6 +137,7 @@ function RootRouteView() {
<SshPasswordPromptDialog />
<HostedStaticEnvironmentBootstrap />
{primaryEnvironmentAuthenticated ? <EventRouter /> : null}
+ {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
{primaryEnvironmentAuthenticated ? <WebSocketConnectionCoordinator /> : null}
{primaryEnvironmentAuthenticated ? <SlowRpcAckToastCoordinator /> : null}
{primaryEnvironmentAuthenticated ? (
diff --git a/apps/web/src/routes/settings.general.tsx b/apps/web/src/routes/settings.general.tsx
index 7fb503e0a..c907a4915 100644
--- a/apps/web/src/routes/settings.general.tsx
+++ b/apps/web/src/routes/settings.general.tsx
@@ -2,6 +2,10 @@ import { createFileRoute } from "@tanstack/react-router";
import { GeneralSettingsPanel } from "../components/settings/SettingsPanels";
+function SettingsGeneralRoute() {
+ return <GeneralSettingsPanel />;
+}
+
export const Route = createFileRoute("/settings/general")({
- component: GeneralSettingsPanel,
+ component: SettingsGeneralRoute,
});
diff --git a/apps/web/src/routes/settings.providers.tsx b/apps/web/src/routes/settings.providers.tsx
new file mode 100644
index 000000000..a7a86c2b5
--- /dev/null
+++ b/apps/web/src/routes/settings.providers.tsx
@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { ProviderSettingsPanel } from "../components/settings/SettingsPanels";
+
+function SettingsProvidersRoute() {
+ return <ProviderSettingsPanel />;
+}
+
+export const Route = createFileRoute("/settings/providers")({
+ component: SettingsProvidersRoute,
+});
diff --git a/apps/web/src/rpc/wsRpcClient.ts b/apps/web/src/rpc/wsRpcClient.ts
index 8e5819032..21c6089ef 100644
--- a/apps/web/src/rpc/wsRpcClient.ts
+++ b/apps/web/src/rpc/wsRpcClient.ts
@@ -119,6 +119,7 @@ export interface WsRpcClient {
readonly refreshProviders: (
input?: RpcInput<typeof WS_METHODS.serverRefreshProviders>,
) => ReturnType<RpcUnaryMethod<typeof WS_METHODS.serverRefreshProviders>>;
+ readonly updateProvider: RpcUnaryMethod<typeof WS_METHODS.serverUpdateProvider>;
readonly upsertKeybinding: RpcUnaryMethod<typeof WS_METHODS.serverUpsertKeybinding>;
readonly getSettings: RpcUnaryNoArgMethod<typeof WS_METHODS.serverGetSettings>;
readonly updateSettings: (
@@ -234,6 +235,8 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
getConfig: () => transport.request((client) => client[WS_METHODS.serverGetConfig]({})),
refreshProviders: (input) =>
transport.request((client) => client[WS_METHODS.serverRefreshProviders](input ?? {})),
+ updateProvider: (input) =>
+ transport.request((client) => client[WS_METHODS.serverUpdateProvider](input)),
upsertKeybinding: (input) =>
transport.request((client) => client[WS_METHODS.serverUpsertKeybinding](input)),
getSettings: () => transport.request((client) => client[WS_METHODS.serverGetSettings]({})),
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index f48091292..ec8125926 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -28,6 +28,7 @@ import type {
import type { ProviderInstanceId } from "./providerInstance.ts";
import type {
ServerConfig,
+ ServerProviderUpdateInput,
ServerProviderUpdatedPayload,
ServerUpsertKeybindingResult,
} from "./server.ts";
@@ -296,6 +297,7 @@ export interface LocalApi {
refreshProviders: (input?: {
readonly instanceId?: ProviderInstanceId;
}) => Promise<ServerProviderUpdatedPayload>;
+ updateProvider: (input: ServerProviderUpdateInput) => Promise<ServerProviderUpdatedPayload>;
upsertKeybinding: (input: ServerUpsertKeybindingInput) => Promise<ServerUpsertKeybindingResult>;
getSettings: () => Promise<ServerSettings>;
updateSettings: (patch: ServerSettingsPatch) => Promise<ServerSettings>;
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index 4167bd0a7..fef6790ae 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -71,6 +71,8 @@ import {
import {
ServerConfigStreamEvent,
ServerConfig,
+ ServerProviderUpdateError,
+ ServerProviderUpdateInput,
ServerLifecycleStreamEvent,
ServerProviderUpdatedPayload,
ServerUpsertKeybindingInput,
@@ -129,6 +131,7 @@ export const WS_METHODS = {
// Server meta
serverGetConfig: "server.getConfig",
serverRefreshProviders: "server.refreshProviders",
+ serverUpdateProvider: "server.updateProvider",
serverUpsertKeybinding: "server.upsertKeybinding",
serverGetSettings: "server.getSettings",
serverUpdateSettings: "server.updateSettings",
@@ -172,6 +175,12 @@ export const WsServerRefreshProvidersRpc = Rpc.make(WS_METHODS.serverRefreshProv
success: ServerProviderUpdatedPayload,
});
+export const WsServerUpdateProviderRpc = Rpc.make(WS_METHODS.serverUpdateProvider, {
+ payload: ServerProviderUpdateInput,
+ success: ServerProviderUpdatedPayload,
+ error: ServerProviderUpdateError,
+});
+
export const WsServerGetSettingsRpc = Rpc.make(WS_METHODS.serverGetSettings, {
payload: Schema.Struct({}),
success: ServerSettings,
@@ -415,6 +424,7 @@ export const WsSubscribeAuthAccessRpc = Rpc.make(WS_METHODS.subscribeAuthAccess,
export const WsRpcGroup = RpcGroup.make(
WsServerGetConfigRpc,
WsServerRefreshProvidersRpc,
+ WsServerUpdateProviderRpc,
WsServerUpsertKeybindingRpc,
WsServerGetSettingsRpc,
WsServerUpdateSettingsRpc,
diff --git a/packages/contracts/src/server.test.ts b/packages/contracts/src/server.test.ts
index 149b0db20..cae68e1f6 100644
--- a/packages/contracts/src/server.test.ts
+++ b/packages/contracts/src/server.test.ts
@@ -23,6 +23,34 @@ describe("ServerProvider", () => {
expect(parsed.slashCommands).toEqual([]);
expect(parsed.skills).toEqual([]);
+ expect(parsed.versionAdvisory).toBeUndefined();
+ expect(parsed.updateState).toBeUndefined();
+ });
+
+ it("defaults one-click update support when decoding older advisory snapshots", () => {
+ const parsed = decodeServerProvider({
+ instanceId: "codex",
+ driver: "codex",
+ enabled: true,
+ installed: true,
+ version: "1.0.0",
+ status: "ready",
+ auth: {
+ status: "authenticated",
+ },
+ checkedAt: "2026-04-10T00:00:00.000Z",
+ models: [],
+ versionAdvisory: {
+ status: "behind_latest",
+ currentVersion: "1.0.0",
+ latestVersion: "1.0.1",
+ updateCommand: "npm install -g @openai/codex@latest",
+ checkedAt: "2026-04-10T00:00:00.000Z",
+ message: "Update available.",
+ },
+ });
+
+ expect(parsed.versionAdvisory?.canUpdate).toBe(false);
});
it("decodes continuation group metadata", () => {
diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts
index a3d07ea69..d2b034b20 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -109,6 +109,43 @@ export const ServerProviderContinuation = Schema.Struct({
});
export type ServerProviderContinuation = typeof ServerProviderContinuation.Type;
+export const ServerProviderVersionAdvisoryStatus = Schema.Literals([
+ "unknown",
+ "current",
+ "behind_latest",
+]);
+export type ServerProviderVersionAdvisoryStatus = typeof ServerProviderVersionAdvisoryStatus.Type;
+
+export const ServerProviderVersionAdvisory = Schema.Struct({
+ status: ServerProviderVersionAdvisoryStatus,
+ currentVersion: Schema.NullOr(TrimmedNonEmptyString),
+ latestVersion: Schema.NullOr(TrimmedNonEmptyString),
+ updateCommand: Schema.NullOr(TrimmedNonEmptyString),
+ canUpdate: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
+ checkedAt: Schema.NullOr(IsoDateTime),
+ message: Schema.NullOr(TrimmedNonEmptyString),
+});
+export type ServerProviderVersionAdvisory = typeof ServerProviderVersionAdvisory.Type;
+
+export const ServerProviderUpdateStatus = Schema.Literals([
+ "idle",
+ "queued",
+ "running",
+ "succeeded",
+ "failed",
+ "unchanged",
+]);
+export type ServerProviderUpdateStatus = typeof ServerProviderUpdateStatus.Type;
+
+export const ServerProviderUpdateState = Schema.Struct({
+ status: ServerProviderUpdateStatus,
+ startedAt: Schema.NullOr(IsoDateTime),
+ finishedAt: Schema.NullOr(IsoDateTime),
+ message: Schema.NullOr(TrimmedNonEmptyString),
+ output: Schema.NullOr(Schema.String.check(Schema.isMaxLength(10_000))),
+});
+export type ServerProviderUpdateState = typeof ServerProviderUpdateState.Type;
+
export const ServerProvider = Schema.Struct({
// Routing key for the configured instance this snapshot represents. This
// is the only stable identity consumers may use for provider routing.
@@ -142,6 +179,8 @@ export const ServerProvider = Schema.Struct({
Schema.withDecodingDefault(Effect.succeed([])),
),
skills: Schema.Array(ServerProviderSkill).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
+ versionAdvisory: Schema.optionalKey(ServerProviderVersionAdvisory),
+ updateState: Schema.optionalKey(ServerProviderUpdateState),
});
export type ServerProvider = typeof ServerProvider.Type;
@@ -294,3 +333,22 @@ export const ServerProviderUpdatedPayload = Schema.Struct({
providers: ServerProviders,
});
export type ServerProviderUpdatedPayload = typeof ServerProviderUpdatedPayload.Type;
+
+export const ServerProviderUpdateInput = Schema.Struct({
+ provider: ProviderDriverKind,
+ instanceId: Schema.optionalKey(ProviderInstanceId),
+});
+export type ServerProviderUpdateInput = typeof ServerProviderUpdateInput.Type;
+
+export class ServerProviderUpdateError extends Schema.TaggedErrorClass<ServerProviderUpdateError>()(
+ "ServerProviderUpdateError",
+ {
+ provider: ProviderDriverKind,
+ reason: TrimmedNonEmptyString,
+ cause: Schema.optional(Schema.Defect),
+ },
+) {
+ override get message(): string {
+ return `Provider update failed for ${this.provider}: ${this.reason}`;
+ }
+}
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 90b9099d1..a4805494d 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -32,6 +32,9 @@ export const ClientSettingsSchema = Schema.Struct({
autoOpenPlanSidebar: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
+ Schema.withDecodingDefault(Effect.succeed([])),
+ ),
diffIgnoreWhitespace: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
diffWordWrap: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
// Model favorites. Historically keyed by provider kind, now
diff --git a/packages/effect-acp/src/client.test.ts b/packages/effect-acp/src/client.test.ts
index b867231ad..5c9a6f833 100644
--- a/packages/effect-acp/src/client.test.ts
+++ b/packages/effect-acp/src/client.test.ts
@@ -24,7 +24,6 @@ const InitializeRequest = jsonRpcRequest("initialize", AcpSchema.InitializeReque
const InitializeResponse = jsonRpcResponse(AcpSchema.InitializeResponse);
const ExtRequest = jsonRpcRequest("x/test", Schema.Struct({ hello: Schema.String }));
const ExtResponse = jsonRpcResponse(Schema.Struct({ ok: Schema.Boolean }));
-
const mockPeerPath = Effect.map(Effect.service(Path.Path), (path) =>
path.join(import.meta.dirname, "../test/fixtures/acp-mock-peer.ts"),
);
diff --git a/packages/effect-acp/src/protocol.test.ts b/packages/effect-acp/src/protocol.test.ts
index 8aaa0810c..f6917d5b7 100644
--- a/packages/effect-acp/src/protocol.test.ts
+++ b/packages/effect-acp/src/protocol.test.ts
@@ -41,7 +41,6 @@ const RequestPermissionRequest = jsonRpcRequest(
const RequestPermissionResponse = jsonRpcResponse(AcpSchema.RequestPermissionResponse);
const ExtRequest = jsonRpcRequest("x/test", Schema.Struct({ hello: Schema.String }));
const ExtResponse = jsonRpcResponse(Schema.Struct({ ok: Schema.Boolean }));
-
const mockPeerPath = Effect.map(Effect.service(Path.Path), (path) =>
path.join(import.meta.dirname, "../test/fixtures/acp-mock-peer.ts"),
);
diff --git a/packages/shared/src/shell.test.ts b/packages/shared/src/shell.test.ts
index 3acc8b7b4..214c03a7e 100644
--- a/packages/shared/src/shell.test.ts
+++ b/packages/shared/src/shell.test.ts
@@ -10,6 +10,7 @@ import {
readEnvironmentFromWindowsShell,
readPathFromLaunchctl,
readPathFromLoginShell,
+ resolveCommandPath,
resolveKnownWindowsCliDirs,
resolveWindowsEnvironment,
} from "./shell.ts";
@@ -332,6 +333,17 @@ describe("isCommandAvailable", () => {
});
});
+describe("resolveCommandPath", () => {
+ it("returns the first executable resolved from PATH", () => {
+ expect(
+ resolveCommandPath("definitely-not-installed", {
+ platform: "win32",
+ env: { PATH: "", PATHEXT: ".COM;.EXE;.BAT;.CMD" },
+ }),
+ ).toBeNull();
+ });
+});
+
describe("resolveWindowsEnvironment", () => {
it("returns the baseline no-profile PATH patch when node is already available", () => {
const readEnvironment = vi.fn(
diff --git a/packages/shared/src/shell.ts b/packages/shared/src/shell.ts
index 6edfdcfff..ecb88f837 100644
--- a/packages/shared/src/shell.ts
+++ b/packages/shared/src/shell.ts
@@ -376,23 +376,26 @@ function isExecutableFile(
}
}
-export function isCommandAvailable(
+export function resolveCommandPath(
command: string,
options: CommandAvailabilityOptions = {},
-): boolean {
+): string | null {
const platform = options.platform ?? process.platform;
const env = options.env ?? process.env;
const windowsPathExtensions = platform === "win32" ? resolveWindowsPathExtensions(env) : [];
const commandCandidates = resolveCommandCandidates(command, platform, windowsPathExtensions);
if (command.includes("/") || command.includes("\\")) {
- return commandCandidates.some((candidate) =>
- isExecutableFile(candidate, platform, windowsPathExtensions),
- );
+ for (const candidate of commandCandidates) {
+ if (isExecutableFile(candidate, platform, windowsPathExtensions)) {
+ return candidate;
+ }
+ }
+ return null;
}
const pathValue = resolvePathEnvironmentVariable(env);
- if (pathValue.length === 0) return false;
+ if (pathValue.length === 0) return null;
const pathEntries = pathValue
.split(pathDelimiterForPlatform(platform))
.map((entry) => stripWrappingQuotes(entry.trim()))
@@ -400,12 +403,20 @@ export function isCommandAvailable(
for (const pathEntry of pathEntries) {
for (const candidate of commandCandidates) {
- if (isExecutableFile(join(pathEntry, candidate), platform, windowsPathExtensions)) {
- return true;
+ const candidatePath = join(pathEntry, candidate);
+ if (isExecutableFile(candidatePath, platform, windowsPathExtensions)) {
+ return candidatePath;
}
}
}
- return false;
+ return null;
+}
+
+export function isCommandAvailable(
+ command: string,
+ options: CommandAvailabilityOptions = {},
+): boolean {
+ return resolveCommandPath(command, options) !== null;
}
export function resolveKnownWindowsCliDirs(env: NodeJS.ProcessEnv): ReadonlyArray<string> {