Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { canSwitchModel, capabilityAgentId, hasGatewayModels, type AgentId } from './config'
import { shellSingleQuote } from '../shell-quote'
import { expandEnvVars } from './expansion'
/** One model gateway configured once for every supported agent harness. */
export interface ModelGatewaySettings {
/** Gateway root, before the OpenAI-compatible `/v1/models` discovery route. */
baseUrl: string
/** Literal legacy key, `${env:VAR}` reference, or `MODEL_GATEWAY_SECRET_REF`. */
apiKey: string
/** Path the discovery (Models API) request is sent to, appended to `baseUrl` — e.g.
* `/openai/v1/models` for a gateway that serves its model catalogue under a protocol prefix.
* Deliberately a PATH SUFFIX and never a full URL: discovery sends the resolved API key to the
* target, and a caller-chosen host would turn the pre-save/relay flow into a credential-exfil-
* tration oracle (the same reason `${env:VAR}` references resolve only for the saved baseUrl).
* Empty/absent = the conventional derived `/v1/models` (see `modelGatewayRoutes`). */
discoveryPath?: string
}
/** Characters a discovery path may contain, minus URL structure that could change WHERE the
* request goes: no query (`?`), fragment (`#`), dot-dot traversal, or second scheme. The value is
* hand-editable settings.json AND caller-supplied over IPC, so it is re-validated at the point it
* is appended to the root (the same rule as permission modes / model ids on a command line) — an
* unrecognized value yields the derived default path, never a guessed one. */
const GATEWAY_DISCOVERY_PATH = /^\/[A-Za-z0-9\-._~!$&'()*+,;=:@/]*$/
/** A validated discovery path, or null when absent/unsafe (null ⇒ use the derived default). */
export function sanitizedGatewayDiscoveryPath(path: string | undefined): string | null {
const value = path?.trim() ?? ''
if (!value) return null
if (value.length > 500 || value.includes('..') || !GATEWAY_DISCOVERY_PATH.test(value)) return null
return value.replace(/\/+$/, '') || null
}
/** Stored in settings.json when the literal credential lives in the shell's secret store. */
export const MODEL_GATEWAY_SECRET_REF = '${secret:model-gateway-api-key}'
export type ModelGatewayCredentialStorage = 'encrypted' | 'restricted-file' | 'unavailable'
export interface ModelGatewayCredentialStatus {
hasStoredKey: boolean
storage: ModelGatewayCredentialStorage
}
export interface ModelGatewayEnvReference {
name: string
}
const EXACT_ENV_REFERENCE = /^\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}$/
/** Parse the JSON representation used by the environment-variable credential mode. */
export function parseModelGatewayEnvReference(apiKey: string): ModelGatewayEnvReference | null {
const match = EXACT_ENV_REFERENCE.exec(apiKey.trim())
if (!match) return null
return { name: match[1] }
}
export type ModelGatewayCredentialKind = 'empty' | 'environment' | 'stored' | 'legacy-literal'
export function modelGatewayCredentialKind(apiKey: string): ModelGatewayCredentialKind {
const value = apiKey.trim()
if (!value) return 'empty'
if (value === MODEL_GATEWAY_SECRET_REF) return 'stored'
if (parseModelGatewayEnvReference(value)) return 'environment'
return 'legacy-literal'
}
/** The intentionally small model shape shared across IPC and renderer state. */
export interface GatewayModel {
id: string
name?: string
provider?: string
}
export interface ModelDiscoveryResult {
models: GatewayModel[]
error?: string
}
export interface ModelGatewayRoutes {
discovery: string
openai: string
anthropic: string
}
/**
* Resolve the stored gateway credential against the host process environment. Keeping this next
* to the route/env mapping gives model discovery and every supported harness the exact same
* `${env:VAR}` parser as custom agents, without ever resolving a secret in the renderer. Gateway
* credentials deliberately accept one exact reference rather than embedded/fallback expansion:
* a fallback API key would put the very secret this mode avoids back into settings.json.
*
* Whitespace around either a literal or expanded key is ignored. A caller must treat `missing` as
* a hard failure even when `value` is partly non-empty: sending a partial credential is both
* surprising and unsafe.
*/
export interface ModelGatewayApiKeyResolution {
value: string
missing: string[]
storedSecretMissing: boolean
}
export function resolveModelGatewayApiKey(
apiKey: string,
env: Record<string, string | undefined>,
storedSecret: string | null = null
): ModelGatewayApiKeyResolution {
if (apiKey.trim() === MODEL_GATEWAY_SECRET_REF) {
const value = storedSecret?.trim() ?? ''
return { value, missing: [], storedSecretMissing: !value }
}
const reference = parseModelGatewayEnvReference(apiKey)
if (!reference) {
return { value: apiKey.trim(), missing: [], storedSecretMissing: false }
}
const result = expandEnvVars(apiKey.trim(), env)
return { value: result.value.trim(), missing: result.missing, storedSecretMissing: false }
}
/**
* Derive every route from one user-entered root. Discovery is the OpenAI Models API convention;
* the provider-specific paths are the Bifrost layout requested by the launch mapping. Only http(s)
* URLs are accepted: this value is later handed to `fetch` and agent CLIs, and settings.json is
* hand-editable. Invalid input degrades to null, never to a guessed endpoint.
*
* `discoveryPath` (optional, from the same `ModelGatewaySettings`) replaces the conventional
* `/v1/models` suffix when it is present and passes `sanitizedGatewayDiscoveryPath`. It changes
* only WHICH path on the saved root the catalogue is read from — never the host — so the
* credential trust gate upstream (references resolve only for the saved baseUrl) is unaffected.
* An unsafe value falls back to the derived default rather than sending a fetch somewhere the
* user did not vet.
*/
export function modelGatewayRoutes(
baseUrl: string,
discoveryPath?: string
): ModelGatewayRoutes | null {
const raw = baseUrl.trim().replace(/\/+$/, '')
if (!raw) return null
try {
const parsed = new URL(raw)
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null
// Credentials in the URL would be copied into every derived endpoint and surfaced in the UI.
// The separate API-key field exists precisely so a secret never has to live there.
if (parsed.username || parsed.password || parsed.search || parsed.hash) return null
const root = parsed.toString().replace(/\/+$/, '')
const discoverySuffix = sanitizedGatewayDiscoveryPath(discoveryPath) ?? '/v1/models'
return {
discovery: `${root}${discoverySuffix}`,
openai: `${root}/openai/v1`,
anthropic: `${root}/anthropic`
}
} catch {
return null
}
}
/** Parse OpenAI-compatible model-list responses, dropping unsafe/empty/duplicate ids. */
export function parseGatewayModels(payload: unknown): GatewayModel[] {
if (!payload || typeof payload !== 'object') return []
const data = (payload as { data?: unknown }).data
if (!Array.isArray(data)) return []
const byId = new Map<string, GatewayModel>()
for (const raw of data) {
if (!raw || typeof raw !== 'object') continue
const row = raw as { id?: unknown; name?: unknown; provider?: unknown; owned_by?: unknown }
const id = typeof row.id === 'string' ? row.id.trim() : ''
if (!id || id.length > 500 || /[\u0000-\u001f\u007f]/.test(id)) continue
const prefix = id.includes('/') ? id.slice(0, id.indexOf('/')) : ''
const explicitProvider =
typeof row.provider === 'string'
? row.provider.trim()
: typeof row.owned_by === 'string'
? row.owned_by.trim()
: ''
byId.set(id, {
id,
...(typeof row.name === 'string' && row.name.trim() ? { name: row.name.trim() } : {}),
...(explicitProvider || prefix ? { provider: explicitProvider || prefix } : {})
})
}
return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id))
}
/**
* Models an agent can be offered. OpenAI-compatible gateways may expose provider-prefixed or
* administrator-defined aliases and route them through either harness protocol, so filtering by
* provider here would hide supported modes. The capability is the only UI gate; custom agents
* inherit it from their declared base harness.
*/
export function modelsForAgent(
models: GatewayModel[],
agentId: AgentId,
grokModels: readonly GatewayModel[] = [],
cursorModels: readonly GatewayModel[] = [],
antigravityModels: readonly GatewayModel[] = []
): GatewayModel[] {
if (!canSwitchModel(agentId)) return []
// grok, cursor and antigravity are offered THEIR OWN models, never the gateway's, and this is a
// correctness rule rather than a preference: none can be routed through the gateway env (see
// `modelGatewayEnv` below). Handing them the gateway catalogue would put ids on the menu that
// their CLIs reject at launch: a picker that looks like it worked and kills the node.
const capId = capabilityAgentId(agentId)
if (capId === 'grok') return [...grokModels]
if (capId === 'cursor') return [...cursorModels]
if (capId === 'antigravity') return [...antigravityModels]
if (!hasGatewayModels(agentId)) return []
return models
}
/**
* Parse `grok models` — the CLI's own list, so there is no allowlist to maintain and a model shipped
* tomorrow appears without a code change.
*
* MEASURED output (1.0.13, 2026-09-02):
*
* You are logged in with grok.com.
*
* Default model: grok-4.6
*
* Available models:
* * grok-4.6 (default)
* - grok-4.5
*
* Only the indented bullets under "Available models:" are read. The `Default model:` line is
* deliberately NOT a source: it repeats an entry that the bullet list already carries, and treating
* a prose line as data is how a login banner or a future footer becomes a fake model id.
*
* Anything unparseable yields an EMPTY list, which the UI reads as "no model switching" — the
* pre-feature behaviour. Never a partial list built from whatever happened to match.
*/
export function grokModelsFrom(stdout: string | null | undefined): GatewayModel[] {
const text = stdout ?? ''
const start = text.indexOf('Available models:')
if (start < 0) return []
const byId = new Map<string, GatewayModel>()
for (const raw of text.slice(start).split('\n').slice(1)) {
// An unindented line ends the block: the list is indented, anything flush left is prose again.
if (raw.trim() && !/^\s/.test(raw)) break
const m = /^\s+[*-]\s+(\S+)/.exec(raw)
if (!m) continue
const id = m[1]
// Same charset discipline as every other id that reaches a command line.
if (!/^[A-Za-z0-9][A-Za-z0-9._:\/-]*$/.test(id)) continue
if (!byId.has(id)) byId.set(id, { id })
}
return [...byId.values()]
}
/**
* Parse `cursor-agent models`. MEASURED (2026.09.28, 246 lines, all matching):
*
* Available models
*
* auto - Auto (default)
* gpt-5.3-codex-low - Codex 5.3 Low
* grok-4.7-low-fast - Grok 4.7 Low Fast<U+200B><U+200B>
*
* Tip: use --model <id> ...
*
* Only `<id> - <label>` lines are read: the id is a bare token from the charset every command-line
* id already uses, the label is the rest with zero-width spaces stripped and whitespace collapsed.
* The header and the trailing `Tip:` prose never match (`Tip:` has no ` - ` after its first word).
* The list is network-backed and account-scoped, so anything unparseable is an EMPTY list, which
* the UI reads as "no model switching".
*/
export function cursorModelsFrom(stdout: string | null | undefined): GatewayModel[] {
const byId = new Map<string, GatewayModel>()
for (const raw of (stdout ?? '').split('\n')) {
const m = /^([A-Za-z0-9][A-Za-z0-9._/-]*) - (\S.*)$/.exec(raw.replace(/[\u200b-\u200d\ufeff]/g, '').trimEnd())
if (!m || byId.has(m[1])) continue
byId.set(m[1], { id: m[1], name: m[2].replace(/\s+/g, ' ').trim() })
}
return [...byId.values()]
}
/**
* Parse `agy models` — Antigravity's own model list (`<id>\t<Display Name>` rows after the
* `Fetching available models...` header).
*
* MEASURED output (1.2.7, Windows 11, 2026-10-14):
*
* Fetching available models...
* gemini-4-argon-medium Gemini 4 Argon (Medium)
* gemini-4-argon-high Gemini 4 Argon (High)
* gemini-4-argon-low Gemini 4 Argon (Low)
* gemini-3.8-flash-high Gemini 3.8 Flash (High)
* claude-opus-5-5-high Claude Opus 5.5 (High)
* gpt-oss-120b-medium GPT-OSS 120B (Medium)
*
* Only tab-separated `<id>\t<label>` lines are accepted, with `id` validated by the same charset
* rule as `grokModelsFrom`. Prose banners or error lines without a tab are ignored.
*/
export function antigravityModelsFrom(stdout: string | null | undefined): GatewayModel[] {
const text = stdout ?? ''
const byId = new Map<string, GatewayModel>()
for (const raw of text.split(/\r?\n/)) {
const tab = raw.indexOf('\t')
if (tab <= 0) continue
const id = raw.slice(0, tab).trim()
const name = raw.slice(tab + 1).trim()
if (!/^[A-Za-z0-9][A-Za-z0-9._:\/-]*$/.test(id)) continue
if (!byId.has(id)) {
byId.set(id, name ? { id, name } : { id })
}
}
return [...byId.values()]
}
/**
* Environment applied to a terminal session before custom-agent env (custom values still win).
* Claude/Codex model selection stays a quoted CLI flag. Copilot's BYOK protocol instead carries
* its internal + wire model ids in environment variables. Credentials never enter a restart
* command, so none are exposed in the pane.
*/
/** Every env var name `modelGatewayEnv` can emit, in one place. The tmux confs bake this list
* into `update-environment`, which is HOW gateway credentials reach a pane without ever touching
* an argv: the values ride the tmux CLIENT's process environment (or a sourced 0600 file over
* SSH), and tmux copies the listed names into the session environment at create/attach. A key
* emitted here but missing from this list would silently fail to reach the agent on a shared
* tmux server — model-gateway.test.ts asserts the lockstep. */
export const MODEL_GATEWAY_ENV_KEYS = [
'ANTHROPIC_BASE_URL',
'ANTHROPIC_AUTH_TOKEN',
'OPENAI_BASE_URL',
'OPENAI_API_KEY',
'COPILOT_PROVIDER_BASE_URL',
'COPILOT_PROVIDER_TYPE',
'COPILOT_PROVIDER_API_KEY',
'COPILOT_PROVIDER_MODEL_ID',
'COPILOT_PROVIDER_WIRE_MODEL',
'COPILOT_PROVIDER_WIRE_API'
] as const
/** tmux's own stock `update-environment` entries (tmux 3.4 defaults, measured via
* `show-options -g`). Assigning the option as a whole REPLACES the array, so the defaults must be
* restated or SSH agent forwarding et al. silently break. */
const TMUX_STOCK_UPDATE_ENV = [
'DISPLAY',
'KRB5CCNAME',
'SSH_ASKPASS',
'SSH_AUTH_SOCK',
'SSH_AGENT_PID',
'SSH_CONNECTION',
'WINDOWID',
'XAUTHORITY'
]
/** The `update-environment` conf line both tmux confs (local + remote) bake in. This is the
* argv-free credential path: gateway values sit in the tmux CLIENT's process environment (never
* on a command line), and tmux copies the listed names into the session env on create/attach —
* MEASURED on tmux 3.4: the pane sees the value, a client withOUT the var strips it from its own
* session (no cross-session bleed into plain terminals), and re-sourcing the conf is idempotent.
*
* `extraNames` lets the LOCAL conf append the account-scope names (`ACCOUNT_SCOPE_UPDATE_ENV` in
* pty-manager — issue #419): the REMOTE conf must NOT get them, because a remote session's
* account env arrives only via `-e` (the ssh-exec'd tmux client's own env is the login shell's,
* so listing the names there would have the copy/strip run against the WRONG environment).
* Deduped so an overlap (e.g. ANTHROPIC_AUTH_TOKEN, in both the gateway list and the claude
* auth strip) cannot double an entry. */
export function tmuxUpdateEnvironmentLine(extraNames: readonly string[] = []): string {
const names = [...new Set([...TMUX_STOCK_UPDATE_ENV, ...MODEL_GATEWAY_ENV_KEYS, ...extraNames])]
return `set -g update-environment "${names.join(' ')}"`
}
/** Copilot selects the provider's internal model id; the gateway keeps the full wire id. */
function copilotModelParts(wireModel: string): { provider: string; modelId: string } {
const slash = wireModel.indexOf('/')
return slash > 0
? { provider: wireModel.slice(0, slash).toLowerCase(), modelId: wireModel.slice(slash + 1) }
: { provider: '', modelId: wireModel }
}
export function modelGatewayEnv(
settings: ModelGatewaySettings,
agentId: AgentId,
model?: string,
processEnv: Record<string, string | undefined> = {},
storedSecret: string | null = null
): Record<string, string> {
const routes = modelGatewayRoutes(settings.baseUrl)
const resolvedKey = resolveModelGatewayApiKey(settings.apiKey, processEnv, storedSecret)
const key = resolvedKey.value
if (
!routes ||
!key ||
resolvedKey.missing.length ||
resolvedKey.storedSecretMissing ||
!canSwitchModel(agentId)
)
return {}
switch (capabilityAgentId(agentId)) {
case 'claude':
return {
ANTHROPIC_BASE_URL: routes.anthropic,
ANTHROPIC_AUTH_TOKEN: key
}
case 'codex':
return {
OPENAI_BASE_URL: routes.openai,
OPENAI_API_KEY: key
}
case 'copilot': {
// Copilot's BYOK mode requires a model at startup. Keep an ordinary Copilot node on GitHub's
// own routing until the user actually selects one; otherwise merely configuring a gateway
// would activate an incomplete provider and make every new Copilot node fail to launch.
const wireModel = normalizedAgentModel(agentId, model)
if (!wireModel) return {}
const { provider, modelId } = copilotModelParts(wireModel)
const anthropic = provider === 'anthropic'
return {
COPILOT_PROVIDER_BASE_URL: anthropic ? routes.anthropic : routes.openai,
COPILOT_PROVIDER_TYPE: anthropic ? 'anthropic' : 'openai',
COPILOT_PROVIDER_API_KEY: key,
// Bifrost needs the provider-prefixed wire id; Copilot's internal catalogue wants the
// unprefixed well-known id for token limits/tool strategy. Its official BYOK grammar
// explicitly supports separating these two values.
COPILOT_PROVIDER_MODEL_ID: modelId,
COPILOT_PROVIDER_WIRE_MODEL: wireModel,
...(!anthropic && /^gpt-5(?:[.-]|$)/i.test(modelId)
? { COPILOT_PROVIDER_WIRE_API: 'responses' }
: {})
}
}
case 'grok':
// Deliberately EMPTY, and stated rather than omitted. grok's model gateway is not an
// environment: custom models are declared in `~/.grok/config.toml` with their own `base_url`
// and `api_key` (`~/.grok/docs/user-guide/11-custom-models.md`), and that file also says the
// environment-wide knobs it does accept CANNOT carry `model`/`base_url`/`api_key`. So there is
// no env for this function to emit, and emitting the OpenAI pair anyway would point grok's
// built-in models at a gateway they were never configured for.
//
// Writing into the user's `config.toml` to route grok through the gateway is a real feature
// and a separate decision — it edits a file the user owns, for a value they did not ask us to
// change. Not this PR.
return {}
default:
return {}
}
}
/** Re-validate a hand-editable/discovered model id at the point it reaches a launch command. */
export function normalizedAgentModel(agentId: AgentId, model: string | undefined): string | null {
const value = model?.trim()
if (
!value ||
value.length > 500 ||
/[\u0000-\u001f\u007f]/.test(value) ||
!canSwitchModel(agentId)
)
return null
return value
}
/** Append a safely quoted model flag only for harnesses whose CLI grammar supports it. */
export function withAgentModel(cmd: string, agentId: AgentId, model: string | undefined): string {
const value = normalizedAgentModel(agentId, model)
if (!value) return cmd
// COPILOT_PROVIDER_MODEL_ID/WIRE_MODEL describe the provider; Copilot still requires a startup
// selection via --model or COPILOT_MODEL. Use a flag so an in-place restart also selects it in
// an existing shell. Match the internal id above, keeping the gateway prefix in WIRE_MODEL only.
const modelId = capabilityAgentId(agentId) === 'copilot' ? copilotModelParts(value).modelId : value
return `${cmd} --model ${shellSingleQuote(modelId)}`
}