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
feat(agents): choose the default gateway model
Darren Kattan99dc8bb01529
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.tsindex 3b325f845..e691c42dc 100644--- a/src/core/pty-manager.ts+++ b/src/core/pty-manager.ts@@ -2768,14 +2768,20 @@ export class PtyManager {// historical Claude fallback does not apply here: gateway access is an explicit agent// capability, not a terminal default.//- // "Restart on subscription" / `vanillaLaunchDefault`: strip the gateway + inherited provider env+ // "Restart on subscription" / launch mode: strip the gateway + inherited provider env// so the agent runs against its OWN default provider (Claude's subscription, Copilot's GitHub- // routing). `vanillaEnvStripPattern` resolves through the base harness; null ⇒ the agent has no- // strip set ⇒ no-op (gemini/grok/opencode are left alone). `buildPtyEnv` runs only in `spawnNew`- // (a fresh session), never on a warm reattach, so toggling the setting never strips an- // already-running session — only the next fresh launch.+ // routing). `vanillaEnvStripPattern` resolves through the base harness (`capabilityAgentId` of+ // the agent id, so a custom agent inheriting a builtin gets the builtin's strip set); null ⇒ the+ // agent has no strip set ⇒ no-op (gemini/grok/opencode are left alone). `buildPtyEnv` runs only+ // in `spawnNew` (a fresh session), never on a warm reattach, so toggling the setting never strips+ // an already-running session — only the next fresh launch.+ // The launch mode is a tri-state (`agentLaunchMode`); a per-node one-shot `clearEnv` (the+ // "Restart on subscription" action) forces the subscription/vanilla path for THIS spawn. The+ // old boolean `vanillaLaunchDefault` is now a migration mirror kept in lockstep with the mode+ // by the settings read/write paths, so reading the mode here is sufficient.+ const launchMode = options.clearEnv ? 'subscription' : this.getSettings().agentLaunchModeconst stripRe =- options.clearEnv || this.getSettings().vanillaLaunchDefault+ launchMode === 'subscription'? options.agentId? vanillaEnvStripPattern(options.agentId): nulldiff --git a/src/core/pty-single-user.test.ts b/src/core/pty-single-user.test.tsindex fdd17a8e5..b592cd063 100644--- a/src/core/pty-single-user.test.ts+++ b/src/core/pty-single-user.test.ts@@ -407,6 +407,7 @@ describe('SINGLE-USER REGRESSION: co-attach must not change the solo path', () =const m = new PtyManager()m.init(() => ({...DEFAULT_SETTINGS,+ agentLaunchMode: mode.vanillaLaunchDefault ? 'subscription' : 'gateway',vanillaLaunchDefault: mode.vanillaLaunchDefault,modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }}))@@ -528,7 +529,7 @@ describe('SINGLE-USER REGRESSION: co-attach must not change the solo path', () =// recycle: read LIVE at spawn, so a fresh launch strips the gateway + inherited provider env// WITHOUT a per-node flag (and survives a reboot, since the setting is the source of truth, not// a one-shot data field that is cleared after its single use).- it('vanillaLaunchDefault strips the gateway + inherited env on a fresh spawn (no per-node clearEnv)', async () => {+ it('subscription launch mode strips the gateway + inherited env on a fresh spawn', async () => {const inheritedBase = process.env.ANTHROPIC_BASE_URLconst inheritedDir = process.env.CLAUDE_CONFIG_DIRprocess.env.ANTHROPIC_BASE_URL = 'https://launchagent-gateway.example.test'@@ -538,6 +539,9 @@ describe('SINGLE-USER REGRESSION: co-attach must not change the solo path', () =const m = new PtyManager()m.init(() => ({...DEFAULT_SETTINGS,+ // The three-way successor to the boolean. (`vanillaLaunchDefault` is now a mirror kept in+ // lockstep by the settings read path; tests that build settings inline must set the mode.)+ agentLaunchMode: 'subscription',vanillaLaunchDefault: true,modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }}))@@ -565,11 +569,12 @@ describe('SINGLE-USER REGRESSION: co-attach must not change the solo path', () =}})- it('vanillaLaunchDefault is a no-op for an agent with no strip pattern, and off keeps the gateway', async () => {+ it('subscription is a no-op without a strip pattern, while both gateway modes keep the gateway', async () => {const { PtyManager } = await import('./pty-manager')const m = new PtyManager()m.init(() => ({...DEFAULT_SETTINGS,+ agentLaunchMode: 'subscription',vanillaLaunchDefault: true,modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }}))@@ -587,6 +592,7 @@ describe('SINGLE-USER REGRESSION: co-attach must not change the solo path', () =const m2 = new PtyManager()m2.init(() => ({...DEFAULT_SETTINGS,+ agentLaunchMode: 'gateway',vanillaLaunchDefault: false,modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }}))@@ -594,6 +600,18 @@ describe('SINGLE-USER REGRESSION: co-attach must not change the solo path', () =await create(80, 24, 'gateway-claude-default-off', { agentId: 'claude' })expect(spawnArgs[1].env.ANTHROPIC_BASE_URL).toBe('https://bifrost.example.test/anthropic')expect(spawnArgs[1].env.ANTHROPIC_AUTH_TOKEN).toBe('vk-gateway')++ // Gateway (default model) changes the renderer's launch command, not PTY credential injection.+ const m3 = new PtyManager()+ m3.init(() => ({+ ...DEFAULT_SETTINGS,+ agentLaunchMode: 'gateway-model',+ modelGateway: { baseUrl: 'https://bifrost.example.test', apiKey: 'vk-gateway' }+ }))+ m3.registerIpc()+ await create(80, 24, 'gateway-claude-default-model', { agentId: 'claude' })+ expect(spawnArgs[2].env.ANTHROPIC_BASE_URL).toBe('https://bifrost.example.test/anthropic')+ expect(spawnArgs[2].env.ANTHROPIC_AUTH_TOKEN).toBe('vk-gateway')})// ── `fresh` drives scrollback replay + agent resume: it must still be computed from tmux ──diff --git a/src/core/settings-store.test.ts b/src/core/settings-store.test.tsindex 485e49574..ba0c16f89 100644--- a/src/core/settings-store.test.ts+++ b/src/core/settings-store.test.ts@@ -182,6 +182,43 @@ describe('SettingsStore nested-default merge', () => {})})+ describe('agent launch mode migration', () => {+ const loadWith = (saved: Record<string, unknown>): Settings => {+ writeFileSync(path.join(dir, 'settings.json'), JSON.stringify(saved), 'utf-8')+ const store = new SettingsStore()+ store.init()+ return store.get()+ }++ it('migrates the legacy vanilla boolean and keeps its downgrade mirror synchronized', () => {+ expect(loadWith({ vanillaLaunchDefault: true })).toMatchObject({+ agentLaunchMode: 'subscription',+ vanillaLaunchDefault: true+ })+ expect(loadWith({ vanillaLaunchDefault: false })).toMatchObject({+ agentLaunchMode: 'gateway',+ vanillaLaunchDefault: false+ })+ expect(loadWith({})).toMatchObject({+ agentLaunchMode: 'gateway',+ vanillaLaunchDefault: false+ })+ })++ it('keeps each valid mode authoritative and normalizes invalid values to the default', () => {+ expect(+ loadWith({ agentLaunchMode: 'gateway-model', vanillaLaunchDefault: true })+ ).toMatchObject({ agentLaunchMode: 'gateway-model', vanillaLaunchDefault: false })+ expect(+ loadWith({ agentLaunchMode: 'subscription', vanillaLaunchDefault: false })+ ).toMatchObject({ agentLaunchMode: 'subscription', vanillaLaunchDefault: true })+ expect(loadWith({ agentLaunchMode: 'unknown', vanillaLaunchDefault: false })).toMatchObject({+ agentLaunchMode: 'gateway',+ vanillaLaunchDefault: false+ })+ })+ })+describe('dictation chord seed (one-shot migration)', () => {// Same disk fixture as the sibling describes: write a settings.json, load it through the real// store, read the merged result back.diff --git a/src/core/settings-store.ts b/src/core/settings-store.tsindex a30c1a077..90de7d882 100644--- a/src/core/settings-store.ts+++ b/src/core/settings-store.ts@@ -70,6 +70,27 @@ function mergeSettings(saved: Partial<Settings> | null | undefined): Settings {if (gpu === false) merged.terminalGpuRendering = "off";else if (gpu !== "on" && gpu !== "off" && gpu !== "auto" && gpu !== "shared")merged.terminalGpuRendering = "auto";+ // `agentLaunchMode` is the three-way successor to the `vanillaLaunchDefault` boolean. A saved+ // file from before this field existed carries only the boolean: `true` was an explicit opt into+ // subscription/vanilla, so it migrates to `'subscription'`; `false` (or absent) is the default+ // and maps to `'gateway'`. Once `agentLaunchMode` is present it is the truth and the boolean is+ // only a downgrade mirror (the renderer write path keeps it in sync for an older build).+ // Validate to the default for an unrecognized value — settings.json is hand-editable.+ const savedLaunchMode = (saved as { agentLaunchMode?: unknown } | null | undefined)+ ?.agentLaunchMode;+ if (+ savedLaunchMode === "gateway" ||+ savedLaunchMode === "gateway-model" ||+ savedLaunchMode === "subscription"+ ) {+ merged.agentLaunchMode = savedLaunchMode;+ } else if (merged.vanillaLaunchDefault === true) {+ merged.agentLaunchMode = "subscription";+ } else {+ merged.agentLaunchMode = DEFAULT_SETTINGS.agentLaunchMode;+ }+ // Keep the mirror in lockstep with the resolved mode so an older build still honors the choice.+ merged.vanillaLaunchDefault = merged.agentLaunchMode === "subscription";return merged;}diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex af905ca6a..25829c3cd 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -4767,6 +4767,17 @@ export function Canvas() {`[nodeterm] node-create agent=${agentId} project=${targetProjectId} group=${groupId ?? '-'} cwd=${cwd ?? '-'}`)setNodes((ns) => {+ // The default gateway model applies ONLY when the launch mode asks for it+ // (`agentLaunchMode === 'gateway-model'`). 'gateway' launches with the CLI's own default+ // model, and 'subscription' strips the gateway entirely so its model is moot. Gated on+ // `canSwitchModel` (base-resolved) so a non-capable agent is left model-less.+ const settings = useSettings.getState().settings+ const model =+ settings.agentLaunchMode === 'gateway-model' &&+ settings.modelGatewayDefaultModel &&+ canSwitchModel(agentId)+ ? settings.modelGatewayDefaultModel+ : undefinedconst node = createAgentNode(agentId,ns.length,@@ -4778,7 +4789,8 @@ export function Canvas() {activePermissionMode(agentId),// Same funnel as the account above: the active project owns the node, so its own// `.nodeterm/settings.json` launch command layers over the global one.- targetProjectId+ targetProjectId,+ model)return [...ns, groupId ? parentInto(node, groupId) : node]})diff --git a/src/renderer/components/settings/sections/AgentsSection.tsx b/src/renderer/components/settings/sections/AgentsSection.tsxindex 2f7c64927..ff2393f1f 100644--- a/src/renderer/components/settings/sections/AgentsSection.tsx+++ b/src/renderer/components/settings/sections/AgentsSection.tsx@@ -13,7 +13,7 @@ import {setDefaultAgent} from '../../../state/agentAvailability'import { ensureClaudeCliCaps } from '../../../state/permissionMode'-import type { ClaudeCliCaps } from '@shared/types'+import type { AgentLaunchMode, ClaudeCliCaps } from '@shared/types'import {AGENT_CONFIG,ALL_PERMISSION_MODES,@@ -73,13 +73,16 @@ const ROWS = {]},vanillaLaunch: {- title: 'Launch on subscription',+ title: 'Launch mode',keywords: [+ 'launch mode','subscription','vanilla','gateway',+ 'gateway model','provider','default',+ 'default model','anthropic','openai','copilot',@@ -459,14 +462,24 @@ export function AgentsSection({ isActive }: { isActive: boolean }): React.JSX.El</SearchableRow><SearchableRow {...ROWS.vanillaLaunch}><FieldRow- label="Launch on subscription"- description="Spawn every fresh agent session with gateway and inherited provider env stripped, so it runs against its OWN default provider — Claude's subscription, Copilot's GitHub routing — instead of a configured model gateway or a LaunchAgent-set override. The per-node “Restart on subscription” action does the same for one node; this is its global counterpart. The managed-account config dir is kept, so account isolation survives. Off by default — it changes which provider every agent node uses."+ label="Launch mode"+ description="The default provider behavior for a fresh canvas agent session. “Gateway (CLI default)” injects the model gateway but lets the CLI pick its own default model. “Gateway (default model)” additionally launches on the default model chosen in Settings → Model gateway. “Subscription” strips the gateway + inherited provider env so the agent runs against its OWN provider (Claude’s subscription, Copilot’s GitHub routing) — the global counterpart of the per-node “Restart on subscription” action. The managed-account config dir is kept, so account isolation survives."control={- <Switch- checked={settings.vanillaLaunchDefault}- ariaLabel="Launch on subscription by default"- onChange={(on) => update({ vanillaLaunchDefault: on })}- />+ <Select+ aria-label="Agent launch mode"+ value={settings.agentLaunchMode}+ onChange={(e) =>+ update({ agentLaunchMode: e.target.value as AgentLaunchMode })+ }+ >+ <option value="gateway">Gateway (CLI default model)</option>+ <option value="gateway-model">+ {settings.modelGatewayDefaultModel+ ? `Gateway (default model: ${settings.modelGatewayDefaultModel})`+ : 'Gateway (default model — none configured)'}+ </option>+ <option value="subscription">Subscription (own provider credentials)</option>+ </Select>}/></SearchableRow>diff --git a/src/renderer/components/settings/sections/ModelGatewaySection.tsx b/src/renderer/components/settings/sections/ModelGatewaySection.tsxindex 94b4b4888..3c4ca94fc 100644--- a/src/renderer/components/settings/sections/ModelGatewaySection.tsx+++ b/src/renderer/components/settings/sections/ModelGatewaySection.tsx@@ -30,6 +30,21 @@ const ROWS = {title: 'Available models',description: 'Refresh the model catalogue used by agent-node context menus.',keywords: ['discover', 'refresh', 'switch model', 'catalogue']+ },+ defaultModel: {+ title: 'Default model',+ description:+ 'A model new canvas agent sessions launch on when the Agents “Launch mode” is set to “Gateway (default model)”.',+ keywords: [+ 'default',+ 'model',+ 'launch',+ 'gateway model',+ 'new session',+ 'claude',+ 'codex',+ 'copilot'+ ]}}const ENTRIES = Object.values(ROWS)@@ -48,6 +63,7 @@ function credentialMessage(error: unknown): string {export function ModelGatewaySection({ isActive }: { isActive: boolean }): React.JSX.Element {const gateway = useSettings((s) => s.settings.modelGateway)+ const defaultModel = useSettings((s) => s.settings.modelGatewayDefaultModel)const update = useSettings((s) => s.update)const models = useModelGateway((s) => s.models)const status = useModelGateway((s) => s.status)@@ -328,6 +344,34 @@ export function ModelGatewaySection({ isActive }: { isActive: boolean }): React.</div>) : null}</SearchableRow>++ <SearchableRow {...ROWS.defaultModel}>+ <FieldRow+ label="Default model"+ description="New canvas agent sessions launch on this model when Settings → Agents → Launch mode is “Gateway (default model)”. Picked from the discovered catalogue — discover models first."+ control={+ <Select+ aria-label="Default gateway model"+ value={defaultModel ?? ''}+ disabled={!models.length}+ onChange={(e) => {+ const id = e.target.value+ // An empty value is the one spelling of "no default" (absent), matching how the+ // launch-commands fields above treat a cleared input. A non-empty id is stored+ // verbatim — it is the discovered catalogue id, not a credential.+ update({ modelGatewayDefaultModel: id || undefined })+ }}+ >+ <option value="">(none — CLI default model)</option>+ {models.map((model) => (+ <option key={model.id} value={model.id}>+ {model.id}+ </option>+ ))}+ </Select>+ }+ />+ </SearchableRow></SettingsSection>)}diff --git a/src/renderer/state/settings.test.ts b/src/renderer/state/settings.test.tsnew file mode 100644index 000000000..085908afb--- /dev/null+++ b/src/renderer/state/settings.test.ts@@ -0,0 +1,20 @@+import { beforeEach, describe, expect, it } from 'vitest'+import { DEFAULT_SETTINGS } from '@shared/types'+import { useSettings } from './settings'++describe('agent launch mode settings mirror', () => {+ beforeEach(() => {+ useSettings.setState({ settings: { ...DEFAULT_SETTINGS }, hydrated: false })+ })++ it('keeps the legacy boolean synchronized with every launch mode update', () => {+ useSettings.getState().update({ agentLaunchMode: 'subscription' })+ expect(useSettings.getState().settings.vanillaLaunchDefault).toBe(true)++ useSettings.getState().update({ agentLaunchMode: 'gateway' })+ expect(useSettings.getState().settings.vanillaLaunchDefault).toBe(false)++ useSettings.getState().update({ agentLaunchMode: 'gateway-model' })+ expect(useSettings.getState().settings.vanillaLaunchDefault).toBe(false)+ })+})diff --git a/src/renderer/state/settings.ts b/src/renderer/state/settings.tsindex 04433bd8d..cb885d773 100644--- a/src/renderer/state/settings.ts+++ b/src/renderer/state/settings.ts@@ -48,6 +48,13 @@ export const useSettings = create<SettingsState>((set, get) => ({update(patch) {const next = { ...get().settings, ...patch }+ // `vanillaLaunchDefault` is the one-release downgrade mirror for `agentLaunchMode`: an older+ // build reads the boolean, so when the user picks a mode here the mirror must follow. (The+ // read path in core settings-store keeps them in lockstep on load; this keeps them in lockstep+ // on write.) `'subscription'` ⇒ true (strip env), anything else ⇒ false.+ if ('agentLaunchMode' in patch) {+ next.vanillaLaunchDefault = patch.agentLaunchMode === 'subscription'+ }set({ settings: next })scheduleSave(next)}diff --git a/src/shared/types.ts b/src/shared/types.tsindex 5a14b6457..12957c6f0 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -20,6 +20,25 @@ import type {ModelGatewaySettings} from './agents/model-gateway'+/**+ * The default provider behavior for a FRESH agent spawn — the three-way successor to the old+ * `vanillaLaunchDefault` boolean. Read by `pty-manager`'s spawn-site strip gate and by the+ * renderer's new-node creation (`addAgentNode`):+ * - `'gateway'` — inject the model gateway env; the agent uses the CLI's OWN default model+ * (no `--model`). Today's behavior for a gateway node with no per-node model.+ * - `'gateway-model'` — inject the gateway env AND launch with the configured default gateway+ * model (`settings.modelGatewayDefaultModel`), so a new canvas session+ * opens on a chosen model without a per-node "Switch model" click.+ * - `'subscription'` — strip the gateway + inherited provider env so the agent runs against its+ * OWN default provider (Claude's subscription, Copilot's GitHub routing).+ * The former `vanillaLaunchDefault: true`. Wins even when a default model is+ * set (vanilla = no gateway at all, so the gateway model is moot).+ *+ * `vanillaLaunchDefault` is kept for one release as a migration MIRROR (an older build still honors+ * the choice); `agentLaunchMode === 'subscription'` ⇒ `vanillaLaunchDefault = true`, else `false`.+ */+export type AgentLaunchMode = 'gateway' | 'gateway-model' | 'subscription'+/** Profile-switch replacement intent. The trusted core validates and re-resolves it before teardown. */export interface PtyRecycleTarget {profileId: string@@ -1525,6 +1544,10 @@ export interface Settings {customAgents: CustomAgent[]/** One gateway root + non-secret credential reference used by model-switch-capable harnesses. */modelGateway: ModelGatewaySettings+ /** The default gateway model id (from discovery) applied to a fresh canvas agent spawn when+ * `agentLaunchMode === 'gateway-model'`. A separate field from `modelGateway` (it is NOT a+ * credential). Absent/empty = no default ⇒ `'gateway-model'` behaves like `'gateway'`. */+ modelGatewayDefaultModel?: string/** Per-builtin-agent launch command overrides (Settings → Agents → Launch commands). The value* replaces the bare CLI name everywhere a launch line is built — new sessions, cold-restore* relaunches and in-place restarts, with the usual flags (`--resume`, `--permission-mode`, the@@ -1577,6 +1600,9 @@ export interface Settings {* `CLAUDE_CONFIG_DIR` (account isolation survives). See `vanillaEnvStripPattern`.*/vanillaLaunchDefault: boolean+ /** The default provider behavior for a fresh agent spawn (the three-way successor to+ * `vanillaLaunchDefault`). See `AgentLaunchMode`. Default `'gateway'` = today's behavior. */+ agentLaunchMode: AgentLaunchMode/** "Eco": exit the agent CLI of a session that has been idle AND offscreen for* `agentHibernationIdleMinutes`, reclaiming its RAM; the conversation is resumed automatically* when the node is viewed again. Default OFF — opt-in, because it stops a real process.@@ -1753,6 +1779,9 @@ export const DEFAULT_SETTINGS: Settings = {soundVolume: 0.5,customAgents: [],modelGateway: { baseUrl: '', apiKey: '' },+ // No default gateway model until the user picks one in Settings → Model gateway. Absent ⇒+ // `'gateway-model'` behaves like `'gateway'` (no --model on a fresh spawn).+ modelGatewayDefaultModel: undefined,agentLaunchCommands: {},claudeAccounts: [],codexAccounts: [],@@ -1775,6 +1804,9 @@ export const DEFAULT_SETTINGS: Settings = {// Opt-in: strips the gateway/inherited provider env on every fresh launch so agents run against// their own default provider. Off by default — changes which provider every agent node uses.vanillaLaunchDefault: false,+ // The three-way successor to the boolean above. `'gateway'` = inject gateway env, CLI default+ // model (today's behavior). `vanillaLaunchDefault` is now its migration mirror.+ agentLaunchMode: 'gateway',// Opt-in: hibernation exits a live CLI, so nobody gets it without asking. The 30-minute floor// is deliberately long — shorter windows exit sessions the user is between turns on.agentHibernationEnabled: false,