The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { |
| 2 | isProviderAvailable, |
| 3 | managedCapabilityDenial, |
| 4 | type ManagedPolicySummary, |
| 5 | type ProviderInstanceConfig, |
| 6 | ProviderDriverKind, |
| 7 | type ProviderInstanceId, |
| 8 | resolveProjectProviderInstanceEnabled, |
| 9 | type ServerProvider, |
| 10 | type ServerSettings, |
| 11 | } from "@t3tools/contracts"; |
| 12 | |
| 13 | import { getOnboardingProviderState } from "./providerReadiness.logic"; |
| 14 | |
| 15 | type ComputerSettings = Pick<ServerSettings, "providerInstances" | "projectSettingsOverrides">; |
| 16 | |
| 17 | // Ready agents first, then ones that need a sign-in or a look. Never ranked by vendor. |
| 18 | const FOUND_ORDER = { ready: 0, signIn: 1, attention: 2 } as const; |
| 19 | type FoundState = keyof typeof FOUND_ORDER; |
| 20 | |
| 21 | const isFoundState = (state: string): state is FoundState => state in FOUND_ORDER; |
| 22 | |
| 23 | const ACP_REGISTRY_DRIVER = ProviderDriverKind.make("acpRegistry"); |
| 24 | |
| 25 | /** |
| 26 | * An agent's state for new threads on this computer. The server also lists agents that only some |
| 27 | * projects turn on, lists an agent it could not load as off, which Turn on cannot fix, and can pass |
| 28 | * a CLI whose version it knows is broken. |
| 29 | */ |
| 30 | export function welcomeAgentState( |
| 31 | provider: ServerProvider, |
| 32 | settings: ComputerSettings | null | undefined, |
| 33 | ) { |
| 34 | if (!isProviderAvailable(provider)) return "attention"; |
| 35 | if (settings && !resolveProjectProviderInstanceEnabled(settings, null, provider.instanceId)) { |
| 36 | return "disabled"; |
| 37 | } |
| 38 | const state = getOnboardingProviderState(provider); |
| 39 | if (state === "ready" && provider.compatibilityAdvisory?.status === "broken") return "attention"; |
| 40 | // An ACP agent that is not prepared reports the same fields as one still being checked. |
| 41 | return state === "checking" && provider.driver === ACP_REGISTRY_DRIVER ? "attention" : state; |
| 42 | } |
| 43 | |
| 44 | /** |
| 45 | * Splits a computer's allowed providers into agents already on it and agents the user can add. |
| 46 | * Order inside each group is by state, then by the name the user sees. Agents still being |
| 47 | * checked are listed with the ones to add, so a slow check never drops an agent. |
| 48 | */ |
| 49 | export function groupWelcomeAgents( |
| 50 | providers: ReadonlyArray<ServerProvider> | null | undefined, |
| 51 | settings: ComputerSettings | null | undefined, |
| 52 | nameOf: (provider: ServerProvider) => string, |
| 53 | isAllowed: (provider: ServerProvider) => boolean, |
| 54 | ) { |
| 55 | const found: Array<{ readonly provider: ServerProvider; readonly state: FoundState }> = []; |
| 56 | const available: ServerProvider[] = []; |
| 57 | let checking = providers == null; |
| 58 | let readyCount = 0; |
| 59 | for (const provider of providers ?? []) { |
| 60 | if (!isAllowed(provider)) continue; |
| 61 | const state = welcomeAgentState(provider, settings); |
| 62 | if (state === "ready") readyCount += 1; |
| 63 | if (state === "checking") checking = true; |
| 64 | if (isFoundState(state)) found.push({ provider, state }); |
| 65 | else available.push(provider); |
| 66 | } |
| 67 | const byName = (a: ServerProvider, b: ServerProvider) => nameOf(a).localeCompare(nameOf(b)); |
| 68 | found.sort( |
| 69 | (a, b) => FOUND_ORDER[a.state] - FOUND_ORDER[b.state] || byName(a.provider, b.provider), |
| 70 | ); |
| 71 | available.sort(byName); |
| 72 | return { checking, readyCount, found: found.map((entry) => entry.provider), available }; |
| 73 | } |
| 74 | |
| 75 | /** Older settings can also keep `enabled: false` inside `config`, which still turns the agent off. */ |
| 76 | export function turnedOnInstance(instance: ProviderInstanceConfig): ProviderInstanceConfig { |
| 77 | const { config } = instance; |
| 78 | const configOff = |
| 79 | typeof config === "object" && |
| 80 | config !== null && |
| 81 | "enabled" in config && |
| 82 | config.enabled === false; |
| 83 | return { |
| 84 | ...instance, |
| 85 | enabled: true, |
| 86 | ...(configOff ? { config: { ...config, enabled: true } } : {}), |
| 87 | }; |
| 88 | } |
| 89 | |
| 90 | /** A CLI the server knows is too old or otherwise broken for T3 Code; Settings updates it. */ |
| 91 | export function isBrokenVersion(provider: ServerProvider) { |
| 92 | return provider.installed && provider.compatibilityAdvisory?.status === "broken"; |
| 93 | } |
| 94 | |
| 95 | /** |
| 96 | * What "Use existing CLI" does next for Codex: wait for the CLI's own check, open its terminal, |
| 97 | * or stop. Only the ChatGPT sign-in runtime reports `setup.canAuthenticate`. |
| 98 | */ |
| 99 | export function cliTerminalStep( |
| 100 | provider: ServerProvider, |
| 101 | settings: ComputerSettings | null | undefined, |
| 102 | ) { |
| 103 | if (provider.setup?.canAuthenticate === true) return "wait"; |
| 104 | const state = welcomeAgentState(provider, settings); |
| 105 | if (state === "checking") return "wait"; |
| 106 | // A broken version is updated from its row, and an installed, signed-in CLI needs no terminal. |
| 107 | if (isBrokenVersion(provider)) return "done"; |
| 108 | if (provider.installed && provider.auth.status === "authenticated") return "done"; |
| 109 | // The terminal shows the command first, so it also helps a CLI whose check failed. |
| 110 | const fixable = |
| 111 | state === "install" || |
| 112 | state === "signIn" || |
| 113 | (state === "attention" && isProviderAvailable(provider)); |
| 114 | return fixable ? "open" : "done"; |
| 115 | } |
| 116 | |
| 117 | /** |
| 118 | * Whether Codex's row opens its setup card, which offers ChatGPT sign-in or the CLI. A signed-in |
| 119 | * or broken Codex gets its plain row action instead, since the card has nothing left for it. |
| 120 | */ |
| 121 | export function codexNeedsSetup( |
| 122 | provider: ServerProvider, |
| 123 | settings: ComputerSettings | null | undefined, |
| 124 | ) { |
| 125 | if ( |
| 126 | provider.driver !== "codex" || |
| 127 | provider.auth.status === "authenticated" || |
| 128 | isBrokenVersion(provider) |
| 129 | ) { |
| 130 | return false; |
| 131 | } |
| 132 | const state = welcomeAgentState(provider, settings); |
| 133 | return ( |
| 134 | state === "install" || |
| 135 | state === "signIn" || |
| 136 | (state === "attention" && isProviderAvailable(provider)) |
| 137 | ); |
| 138 | } |
| 139 | |
| 140 | /** |
| 141 | * The phone joins by signing in to T3 Connect, which shares the primary computer. Another |
| 142 | * computer, a build without T3 Connect, or a policy that turns it off gets no Phone section. |
| 143 | */ |
| 144 | export function welcomeOffersPhone(input: { |
| 145 | readonly isPrimary: boolean; |
| 146 | readonly cloud: boolean; |
| 147 | // Relay read and write access, which sharing this computer through T3 Connect needs. |
| 148 | readonly canShare: boolean; |
| 149 | readonly policy: ManagedPolicySummary | undefined; |
| 150 | }) { |
| 151 | return ( |
| 152 | input.isPrimary && |
| 153 | input.cloud && |
| 154 | input.canShare && |
| 155 | managedCapabilityDenial(input.policy, "remoteClients") === undefined && |
| 156 | managedCapabilityDenial(input.policy, "connect") === undefined |
| 157 | ); |
| 158 | } |
| 159 | |
| 160 | /** |
| 161 | * The Codex instance the setup card shows, or null when the card is closed. A rebuild briefly |
| 162 | * drops an instance from the list, so the card keeps its last status meanwhile instead of |
| 163 | * unmounting and losing a sign-in in progress. |
| 164 | */ |
| 165 | export function codexCardProvider(input: { |
| 166 | readonly providers: ReadonlyArray<ServerProvider> | null | undefined; |
| 167 | readonly instanceId: ProviderInstanceId | null; |
| 168 | readonly last: ServerProvider | null; |
| 169 | readonly settings: ComputerSettings | null | undefined; |
| 170 | }) { |
| 171 | if (input.instanceId === null) return null; |
| 172 | const provider = |
| 173 | input.providers?.find((candidate) => candidate.instanceId === input.instanceId) ?? |
| 174 | (input.last?.instanceId === input.instanceId ? input.last : undefined); |
| 175 | if (provider === undefined) return null; |
| 176 | const open = |
| 177 | codexNeedsSetup(provider, input.settings) || |
| 178 | welcomeAgentState(provider, input.settings) === "checking"; |
| 179 | return open ? provider : null; |
| 180 | } |