Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat: run a harness on a saved API's models

bitcoinbuilder2e0fee3bab4a
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 86e11ff07..fc9ad7a23 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -35,8 +35,9 @@ import { linkCodexProfile, listCodexProfiles } from './lib/codexProfiles.js'
import { gridCliPresence } from './lib/gridExec.js'
import { GridFleetRpc, GRID_FLEET_PROTOCOL, GRID_FLEET_MAX_TIMEOUT_MS, parseGridFleetRequest } from './lib/gridFleetRpc.js'
import { LocalModels } from './lib/localModels.js'
-import { ApiConnections, apiConnectionsRequest } from './lib/apiConnections.js'
-import { gridCapableEngines, parseGridLaunchOverride, type GridLaunchOverride } from './lib/gridLaunch.js'
+import { ApiConnectionError, ApiConnections, apiConnectionsRequest } from './lib/apiConnections.js'
+import { apiModelsRequest, rememberSavedApis, resolveApiTarget } from './lib/apiModels.js'
+import { gridCapableEngines, isApiLaunch, parseGridLaunchOverride, type GridLaunchOverride } from './lib/gridLaunch.js'
import {
forgetGridModels, gridInventory, listAllGridModels, onGridModelsChanged, presentGridSections, retargetPrewarm, type GridSection,
} from './lib/gridModels.js'
@@ -1644,7 +1645,12 @@ export class BackendSocket {
if (type === 'api_connections') {
if (!local) { reply(type, requestId, { error: 'LOCAL_ONLY', detail: 'Manage APIs on this computer.' }); return }
+ if (payload.action === 'models') {
+ reply(type, requestId, await apiModelsRequest(this.apiConnections, payload))
+ return
+ }
reply(type, requestId, apiConnectionsRequest(this.apiConnections, payload))
+ if (payload.action === 'save') rememberSavedApis(this.apiConnections)
return
}
@@ -2514,6 +2520,26 @@ export class BackendSocket {
// ever crosses the relay and the app cannot be the source of truth for an address it does
// not know. A client that sends the full `grid` object still works unchanged.
const picked = typeof payload.gridModel === 'string' ? payload.gridModel : ''
+ // `apiConnection` + `apiModel`: a model of an API saved on this computer. Same rule as a grid
+ // model — the app names it, and the endpoint and key are read here, from the store — and
+ // only from this computer, where the key is kept and its owner is the one asking.
+ const api = typeof payload.apiConnection === 'string' ? payload.apiConnection : ''
+ if (api && (picked || payload.grid !== undefined || clear)) {
+ reply(type, requestId, { error: 'INVALID_GRID', detail: 'Choose an API model, a grid model or the own login, not several.' })
+ return
+ }
+ if (api) {
+ if (!local) { reply(type, requestId, { error: 'LOCAL_ONLY', detail: 'Use saved APIs on this computer.' }); return }
+ try {
+ payload.grid = await resolveApiTarget(this.apiConnections, api, typeof payload.apiModel === 'string' ? payload.apiModel.trim() : '')
+ } catch (error) {
+ reply(type, requestId, {
+ error: 'API_UNAVAILABLE',
+ detail: error instanceof ApiConnectionError ? error.message : 'This API could not be used. Try again.',
+ })
+ return
+ }
+ }
if (picked && payload.grid === undefined && !clear) {
// The grid the model was picked FROM, when the picker says (a shared grid's section);
// the account's own grid otherwise, as before.
@@ -2552,7 +2578,8 @@ export class BackendSocket {
// The agent is on a grid model now and its pane is restarting: start that grid meanwhile if it
// sleeps, so the first message rarely waits on a boot (issue 03). Detached — the move is done
// and answered — and it decides for itself whether a wake is worth it.
- if (override) void retargetPrewarm(override).catch(() => {})
+ // An API has no sleep to wake it from, and is not a grid to look up.
+ if (override && !isApiLaunch(override)) void retargetPrewarm(override).catch(() => {})
return
}
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index c4fed14b5..0011d0840 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -77,7 +77,7 @@ import { isTerminalEngine, type AgentEngine } from './engines/types.js'
import { engineInstallRecipe } from './lib/engineInstall.js'
import { buildEngineCommandArgv, buildEngineLaunchArgv, commandAvailableInInteractiveShell, dropPermissionFlagIfUnsupported, namedAgentArgs, permissionModeApproves, permissionModeFlags, refusePermissionFlagIfUnsupported, supportsFirstPrompt } from './lib/engineLaunch.js'
import { workspaceMissing } from './lib/workspaceCheck.js'
-import { buildGridEngineLaunch, describeGridLaunch, gridConflictingEnvToClear, gridEnvVarNames, type GridLaunchMachine, type GridWebSearchStatus } from './lib/gridLaunch.js'
+import { buildGridEngineLaunch, describeGridLaunch, gridConflictingEnvToClear, gridEnvVarNames, isApiLaunch, type GridLaunchMachine, type GridWebSearchStatus } from './lib/gridLaunch.js'
import { HERMES_SYSTEM_MANAGED_DIR } from './lib/gridWebMcp.js'
import { writeGridConfigDir } from './lib/gridConfigDir.js'
import { tmuxSupportsSessionEnv, TMUX_SESSION_ENV_MIN } from './lib/tmuxVersion.js'
@@ -121,7 +121,8 @@ import { DshViewerManager } from './dsh/viewer.js'
import { ViewerLedger } from './dsh/viewerLedger.js'
import { DshVerdictWatcher, type DshVerdict } from './dsh/verdict.js'
import { dshCommand, dshUsage } from './dsh/command.js'
-import { ApiConnections } from './lib/apiConnections.js'
+import { ApiConnectionError, ApiConnections } from './lib/apiConnections.js'
+import { refreshApiLaunch, rememberSavedApis } from './lib/apiModels.js'
import { apiCommand, apiUsage } from './lib/apiCommand.js'
import { prepareApiInstructions } from './lib/apiInstructions.js'
import type { AgentDshContext } from './lib/agentFrame.js'
@@ -1438,6 +1439,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
}
const savedApis = new ApiConnections(env.ADAPTER_DATA_DIR)
+ // Before any agent is probed: one already running on a saved API's model reports that model.
+ rememberSavedApis(savedApis)
const prepareApiTools = (cwd: string | null | undefined, engine: string): void => {
if (!cwd) return
try { prepareApiInstructions(savedApis, cwd, engine) }
@@ -4438,9 +4441,23 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// Whatever the source (the row itself, or a grid override the desktop just sent), the agent's DSH,
// workspace and named agent come from the row: a retarget must not silently drop the harness the
// agent is, or bring a pane opened as `harness-compute` back as a general session.
- const relaunchOverrides = (session: RegisteredSession, source: LaunchSource = session): Promise<LaunchOverridesResult> => {
+ // An agent on a saved API's model relaunches with that API's endpoint and key as saved now, so a key
+ // pasted since takes effect, and a removed API is refused rather than kept on its old key.
+ const relaunchOverrides = async (session: RegisteredSession, source: LaunchSource = session): Promise<LaunchOverridesResult> => {
prepareApiTools(session.cwd, session.engine)
- return buildLaunchOverrides(launchOverridesDeps, session.engine, { dsh: session.dsh ?? null, dshRuntime: session.dshRuntime ?? null, cwd: session.cwd, agent: session.agent ?? null, ...source }, session.agentId)
+ let gridLaunch = source.gridLaunch ?? null
+ if (gridLaunch && isApiLaunch(gridLaunch)) {
+ try {
+ gridLaunch = refreshApiLaunch(savedApis, gridLaunch)
+ } catch (error) {
+ return {
+ ok: false,
+ error: 'API_UNAVAILABLE',
+ detail: error instanceof ApiConnectionError ? error.message : `${gridLaunch.networkName} could not be read from saved APIs.`,
+ }
+ }
+ }
+ return buildLaunchOverrides(launchOverridesDeps, session.engine, { dsh: session.dsh ?? null, dshRuntime: session.dshRuntime ?? null, cwd: session.cwd, agent: session.agent ?? null, ...source, gridLaunch }, session.agentId)
}
/**
diff --git a/cli/src/lib/apiConnections.ts b/cli/src/lib/apiConnections.ts
index c4ba55aa5..ec04c311b 100644
--- a/cli/src/lib/apiConnections.ts
+++ b/cli/src/lib/apiConnections.ts
@@ -44,6 +44,12 @@ export class ApiConnectionError extends Error {}
const message = (value: string): never => { throw new ApiConnectionError(value) }
const publicConnection = (value: StoredConnection): ApiConnection => metadata.parse(value)
+/** Whether coding agents can run on this API's models. Every engine authenticates to a custom
+ * endpoint as `Authorization: Bearer <key>` and takes no other header or prefix (`gridLaunch.ts`). */
+export function servesModels(connection: Pick<ApiConnection, 'authHeader' | 'authPrefix'>): boolean {
+ return connection.authHeader.toLowerCase() === 'authorization' && connection.authPrefix.toLowerCase() === 'bearer'
+}
+
export class ApiConnections {
private readonly dir: string
private readonly file: string
@@ -126,6 +132,14 @@ export class ApiConnections {
return this.read().find(row => row.id === connectionId) ?? message('This API is not saved. Add it in Models → APIs.')
}
+ /** The settings and key a model launch needs (`apiModels.ts`). The key goes only into the one
+ * engine process the person moved onto this API, never into argv, a log line or a reply. */
+ modelAccess(connectionId: string): { connection: ApiConnection; apiKey: string } {
+ const connection = this.connection(connectionId)
+ if (!servesModels(connection)) return message(`${connection.name} does not take a Bearer key, so coding agents cannot run on it.`)
+ return { connection: publicConnection(connection), apiKey: connection.apiKey }
+ }
+
/** Never merge this into an agent's global environment: a vendor key can override its subscription.
* It belongs ONLY to the explicitly requested tool process (harness api run). */
toolEnvironment(connectionId: string): Record<string, string> {
diff --git a/cli/src/lib/apiModels.spec.ts b/cli/src/lib/apiModels.spec.ts
new file mode 100644
index 000000000..c743dac71
--- /dev/null
+++ b/cli/src/lib/apiModels.spec.ts
@@ -0,0 +1,196 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { BackendSocket } from '../backendSocket.js'
+import { ApiConnections } from './apiConnections.js'
+import { apiModelsRequest, chatModels, forgetApiModels, listApiModels, refreshApiLaunch, resolveApiTarget } from './apiModels.js'
+import { classifyGridAssignment } from './gridAssignment.js'
+import { buildGridEngineLaunch } from './gridLaunch.js'
+
+const secret = 'fixture-openrouter-key'
+const newSecret = 'fixture-rotated-key'
+let directory: string, store: ApiConnections
+
+const listing = {
+ data: [
+ { id: 'anthropic/claude-sonnet-4.6', name: 'Anthropic: Claude Sonnet 4.6', context_length: 1_000_000, supported_parameters: ['tools', 'temperature'], architecture: { output_modalities: ['text'] } },
+ { id: 'z-ai/glm-5', context_length: 202_752, supported_parameters: ['tools'] },
+ { id: 'small/no-room', context_length: 32_768, supported_parameters: ['tools'] },
+ { id: 'plain/no-tools', context_length: 262_144, supported_parameters: ['temperature'] },
+ { id: 'images/only', context_length: 262_144, supported_parameters: ['tools'], architecture: { output_modalities: ['image'] } },
+ ],
+}
+
+function answering(body: unknown, status = 200) {
+ return vi.fn(async (_url: string | URL | Request, _init?: RequestInit) =>
+ new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } }))
+}
+
+beforeEach(() => {
+ directory = mkdtempSync(join(tmpdir(), 'harness-api-models-'))
+ store = new ApiConnections(directory)
+ forgetApiModels()
+})
+afterEach(() => {
+ vi.restoreAllMocks()
+ rmSync(directory, { recursive: true, force: true })
+})
+
+describe('an API as a model source', () => {
+ it('keeps the models a coding agent can run on, and every row of an API that says nothing', () => {
+ expect(chatModels(listing).map((model) => model.id)).toEqual(['anthropic/claude-sonnet-4.6', 'z-ai/glm-5'])
+ expect(chatModels(listing)[0]).toEqual({ id: 'anthropic/claude-sonnet-4.6', name: 'Anthropic: Claude Sonnet 4.6', contextWindow: 1_000_000 })
+ expect(chatModels({ data: [{ id: 'deepseek-chat', object: 'model' }, { id: 'deepseek-chat' }, { id: '' }, 'x'] }))
+ .toEqual([{ id: 'deepseek-chat' }])
+ // Replicate's `/models` is not an OpenAI list: it has no chat models to offer.
+ expect(chatModels({ results: [{ name: 'flux' }] })).toEqual([])
+ expect(chatModels(null)).toEqual([])
+ })
+
+ it('reads the list with the saved Bearer key, keeps it, and reads again when the key changes', async () => {
+ const saved = store.save({ provider: 'openrouter', apiKey: secret })
+ const fetch = answering(listing)
+ expect((await listApiModels(store, saved.id, { fetch })).length).toBe(2)
+ await listApiModels(store, saved.id, { fetch })
+ expect(fetch).toHaveBeenCalledTimes(1)
+ const [url, init] = fetch.mock.calls[0]!
+ expect(url).toBe('https://openrouter.ai/api/v1/models')
+ expect((init?.headers as Record<string, string>).authorization).toBe(`Bearer ${secret}`)
+ store.save({ id: saved.id, provider: 'openrouter', apiKey: newSecret })
+ await listApiModels(store, saved.id, { fetch })
+ expect(fetch).toHaveBeenCalledTimes(2)
+ expect((fetch.mock.calls[1]![1]?.headers as Record<string, string>).authorization).toBe(`Bearer ${newSecret}`)
+ })
+
+ it('says why a list failed, never with the key, and refuses an API agents cannot authenticate to', async () => {
+ const saved = store.save({ provider: 'openrouter', apiKey: secret })
+ const refused = await apiModelsRequest(store, { id: saved.id }, { fetch: answering({ error: 'no' }, 401) })
+ expect(refused).toEqual({ error: 'API_MODELS_FAILED', detail: 'OpenRouter did not accept the saved key. Edit the connection and paste a new key.' })
+ const fal = store.save({ provider: 'fal', apiKey: secret })
+ const fetch = answering(listing)
+ const answer = await apiModelsRequest(store, { id: fal.id }, { fetch })
+ expect(answer).toEqual({ error: 'API_MODELS_FAILED', detail: 'fal.ai does not take a Bearer key, so coding agents cannot run on it.' })
+ expect(fetch).not.toHaveBeenCalled()
+ const listed = await apiModelsRequest(store, { id: saved.id }, { fetch })
+ expect(listed).toMatchObject({ id: saved.id, models: [{ id: 'anthropic/claude-sonnet-4.6' }, { id: 'z-ai/glm-5' }] })
+ expect(JSON.stringify([refused, answer, listed])).not.toContain(secret)
+ })
+
+ it('builds the launch every engine reaches OpenRouter through, and refuses a model it does not list', async () => {
+ const saved = store.save({ provider: 'openrouter', apiKey: secret })
+ const fetch = answering(listing)
+ const target = await resolveApiTarget(store, saved.id, 'anthropic/claude-sonnet-4.6', { fetch })
+ expect(target).toEqual({
+ networkId: 'api:openrouter',
+ networkName: 'OpenRouter',
+ baseUrl: 'https://openrouter.ai/api/v1',
+ apiKey: secret,
+ model: 'anthropic/claude-sonnet-4.6',
+ contextWindow: 1_000_000,
+ })
+ await expect(resolveApiTarget(store, saved.id, 'plain/no-tools', { fetch }))
+ .rejects.toThrow('OpenRouter does not list plain/no-tools for coding agents.')
+
+ // OpenRouter's documented Claude Code setup: `ANTHROPIC_BASE_URL=https://openrouter.ai/api`.
+ const claude = buildGridEngineLaunch('claude', target, { hermesSystemManaged: false })
+ expect(claude.ok && claude.launch.env).toMatchObject({
+ ANTHROPIC_BASE_URL: 'https://openrouter.ai/api',
+ ANTHROPIC_AUTH_TOKEN: secret,
+ ANTHROPIC_MODEL: 'anthropic/claude-sonnet-4.6',
+ CLAUDE_CODE_MAX_CONTEXT_TOKENS: '1000000',
+ })
+ const codex = buildGridEngineLaunch('codex', target, { hermesSystemManaged: false })
+ expect(codex.ok && codex.launch.args).toEqual(expect.arrayContaining(['model_providers.grid.base_url="https://openrouter.ai/api/v1"', 'model_providers.grid.wire_api="responses"']))
+ expect(JSON.stringify(codex.ok && codex.launch.args)).not.toContain(secret)
+ // Its own provider id: OpenCode merges a block named `openrouter` into its built-in provider.
+ const opencode = buildGridEngineLaunch('opencode', target, { hermesSystemManaged: false })
+ expect(opencode.ok && opencode.launch.args).toEqual(['-m', 'api-openrouter/anthropic/claude-sonnet-4.6'])
+ expect(opencode.ok && opencode.launch.configDir!.files[0]!.content).not.toContain(secret)
+ })
+
+ it('reports an agent moved onto a saved API as on its model, and a stranger endpoint as not', async () => {
+ const env = { ANTHROPIC_BASE_URL: 'https://openrouter.ai/api', ANTHROPIC_MODEL: 'z-ai/glm-5' }
+ const saved = store.save({ provider: 'openrouter', apiKey: secret })
+ expect(classifyGridAssignment('claude', { ...env, ANTHROPIC_BASE_URL: 'https://other.example.test/api' })).toBeNull()
+ await resolveApiTarget(store, saved.id, 'z-ai/glm-5', { fetch: answering(listing) })
+ expect(classifyGridAssignment('claude', env)).toEqual({ baseUrl: 'https://openrouter.ai/api', model: 'z-ai/glm-5' })
+ expect(classifyGridAssignment('codex', {}, '-c model_providers.grid.base_url="https://openrouter.ai/api/v1" -m z-ai/glm-5'))
+ .toEqual({ baseUrl: 'https://openrouter.ai/api/v1', model: 'z-ai/glm-5' })
+ })
+
+ it('relaunches with the key saved now, and refuses once the API is removed', async () => {
+ const saved = store.save({ provider: 'openrouter', apiKey: secret })
+ const launch = await resolveApiTarget(store, saved.id, 'z-ai/glm-5', { fetch: answering(listing) })
+ store.save({ id: saved.id, provider: 'openrouter', apiKey: newSecret })
+ expect(refreshApiLaunch(store, launch)).toEqual({ ...launch, apiKey: newSecret })
+ const grid = { networkId: 'grid-1', networkName: 'home', baseUrl: 'https://grid.example.test/relay/v1', apiKey: 'grid-key' }
+ expect(refreshApiLaunch(store, grid)).toBe(grid)
+ store.remove(saved.id)
+ expect(() => refreshApiLaunch(store, launch)).toThrow('This API is not saved. Add it in Models → APIs.')
+ })
+})
+
+describe('agent_retarget onto an API model', () => {
+ function retarget(socket: BackendSocket, payload: Record<string, unknown>, connId = 'local:apis') {
+ return (socket as any).dispatchDown({ type: 'agent_retarget', payload: { requestId: 'r', agentId: 'agent-1', ...payload } }, connId, connId === 'remote' ? 'relay' : 'local')
+ }
+
+ it('resolves the endpoint and key on this computer and hands the engine launch that override', async () => {
+ const socket = new BackendSocket('fixture')
+ const reply = vi.spyOn(socket as any, 'emitReply').mockImplementation(() => {})
+ const saved = store.save({ provider: 'openrouter', apiKey: secret })
+ const access = vi.spyOn(ApiConnections.prototype, 'modelAccess').mockImplementation(() => ({
+ connection: saved,
+ apiKey: secret,
+ }))
+ vi.spyOn(globalThis, 'fetch').mockImplementation(answering(listing))
+ const moved = vi.fn(async () => ({ ok: true as const }))
+ socket.onRetargetAgent = moved
+ await retarget(socket, { apiConnection: 'openrouter', apiModel: 'z-ai/glm-5' })
+ expect(access).toHaveBeenCalledWith('openrouter')
+ expect(moved).toHaveBeenCalledWith({
+ agentId: 'agent-1',
+ grid: {
+ networkId: 'api:openrouter',
+ networkName: 'OpenRouter',
+ baseUrl: 'https://openrouter.ai/api/v1',
+ apiKey: secret,
+ model: 'z-ai/glm-5',
+ contextWindow: 202_752,
+ },
+ })
+ expect(reply).toHaveBeenCalledWith('local:apis', 'agent_retarget', 'r', { retargeted: true })
+ await socket.stop()
+ })
+
+ it('refuses a remote client, and a frame naming an API with anything else', async () => {
+ const socket = new BackendSocket('fixture')
+ const reply = vi.spyOn(socket as any, 'emitReply').mockImplementation(() => {})
+ const moved = vi.fn(async () => ({ ok: true as const }))
+ socket.onRetargetAgent = moved
+ // Authenticated and encrypted, and still refused: the key stays with its owner on this computer.
+ vi.spyOn((socket as any).e2ee, 'unwrapDown').mockReturnValueOnce({
+ type: 'agent_retarget', payload: { requestId: 'r', agentId: 'agent-1', apiConnection: 'openrouter', apiModel: 'z-ai/glm-5' },
+ })
+ await (socket as any).dispatchDown({ type: 'agent_retarget', payload: { __e2e: { v: 1, k: 'p', n: 1, ct: 'fixture' } } }, 'remote')
+ expect(reply).toHaveBeenLastCalledWith('remote', 'agent_retarget', 'r', { error: 'LOCAL_ONLY', detail: 'Use saved APIs on this computer.' })
+ await retarget(socket, { apiConnection: 'openrouter', apiModel: 'z-ai/glm-5', gridModel: 'Qwen' })
+ expect(reply).toHaveBeenLastCalledWith('local:apis', 'agent_retarget', 'r', expect.objectContaining({ error: 'INVALID_GRID' }))
+ await retarget(socket, { apiConnection: 'openrouter', clearGrid: true })
+ expect(reply).toHaveBeenLastCalledWith('local:apis', 'agent_retarget', 'r', expect.objectContaining({ error: 'INVALID_GRID' }))
+ expect(moved).not.toHaveBeenCalled()
+ await socket.stop()
+ })
+
+ it('answers why an API cannot be used, without touching the pane', async () => {
+ const socket = new BackendSocket('fixture')
+ const reply = vi.spyOn(socket as any, 'emitReply').mockImplementation(() => {})
+ const moved = vi.fn(async () => ({ ok: true as const }))
+ socket.onRetargetAgent = moved
+ await retarget(socket, { apiConnection: 'never-saved', apiModel: 'z-ai/glm-5' })
+ expect(reply).toHaveBeenLastCalledWith('local:apis', 'agent_retarget', 'r', expect.objectContaining({ error: 'API_UNAVAILABLE' }))
+ expect(moved).not.toHaveBeenCalled()
+ await socket.stop()
+ })
+})
diff --git a/cli/src/lib/apiModels.ts b/cli/src/lib/apiModels.ts
new file mode 100644
index 000000000..8ea7f2e3a
--- /dev/null
+++ b/cli/src/lib/apiModels.ts
@@ -0,0 +1,170 @@
+/**
+ * A saved API as a place to run a harness: an OpenAI-compatible API (OpenRouter, or a Custom API) lists
+ * its chat models, and a person can move a pane's agent onto one of them.
+ *
+ * The move is a grid move in everything but where the endpoint comes from. The same per-engine launch
+ * contracts run it (`gridLaunch.ts`) — OpenRouter documents exactly those variables for Claude Code
+ * (`ANTHROPIC_BASE_URL=https://openrouter.ai/api`), Codex (`wire_api = "responses"`) and OpenCode — and
+ * the endpoint and key are read HERE, from this computer's store, so the app never holds the key.
+ *
+ * Listing a model list is a free read; nothing here makes a paid request.
+ */
+import { createHash } from 'node:crypto'
+import { ApiConnectionError, type ApiConnections } from './apiConnections.js'
+import { rememberApiBase } from './gridAssignment.js'
+import { API_NETWORK_PREFIX, contextWindowHint, isApiLaunch, type GridLaunchOverride } from './gridLaunch.js'
+import { MIN_CODING_CONTEXT } from './localModels.js'
+
+export interface ApiModel {
+ id: string
+ /** The API's display name for it, when it gives one (OpenRouter: "Anthropic: Claude Sonnet 4.6"). */
+ name?: string
+ /** Its context window in tokens, when listed — what the engine is told to compact inside. */
+ contextWindow?: number
+}
+
+/** A list is re-read after this long, or at once when the connection's URL or key changed. */
+const LIST_FRESH_MS = 10 * 60_000
+const LIST_TIMEOUT_MS = 15_000
+/** More than any API lists; an answer past it is cut. */
+const MAX_MODELS = 2000
+const MODEL_ID = /^[^\s\x00-\x1f\x7f]{1,256}$/
+
+interface Listed { fingerprint: string; at: number; models: ApiModel[] }
+const lists = new Map<string, Listed>()
+
+/** Forget every list read, so the next ask reads each API again. */
+export function forgetApiModels(): void {
+ lists.clear()
+}
+
+export interface ApiModelDeps {
+ fetch?: typeof fetch
+ now?: () => number
+}
+
+/** The models in an OpenAI-shaped `/models` answer that a coding agent can run on.
+ *
+ * A field an API does not send says nothing: a Custom API's rows are usually just `{id}` and are all
+ * kept. Where the API does say (OpenRouter), a model that takes no tools, answers in no text, or has a
+ * window under the smallest a coding agent can work in (64K, as for local models) is left out. */
+export function chatModels(body: unknown): ApiModel[] {
+ const rows = body && typeof body === 'object' && Array.isArray((body as { data?: unknown }).data)
+ ? (body as { data: unknown[] }).data
+ : []
+ const seen = new Set<string>()
+ const models: ApiModel[] = []
+ for (const raw of rows.slice(0, MAX_MODELS)) {
+ if (!raw || typeof raw !== 'object') continue
+ const row = raw as Record<string, unknown>
+ const id = typeof row.id === 'string' ? row.id.trim() : ''
+ if (!MODEL_ID.test(id) || seen.has(id)) continue
+ const parameters = row.supported_parameters
+ if (Array.isArray(parameters) && !parameters.includes('tools')) continue
+ const outputs = (row.architecture as { output_modalities?: unknown } | undefined)?.output_modalities
+ if (Array.isArray(outputs) && !outputs.includes('text')) continue
+ const listed = typeof row.context_length === 'number' ? row.context_length : row.context_window
+ if (typeof listed === 'number' && listed < MIN_CODING_CONTEXT) continue
+ const contextWindow = contextWindowHint(listed)
+ const name = typeof row.name === 'string' && row.name.trim() && row.name.length <= 200 ? row.name.trim() : undefined
+ seen.add(id)
+ models.push({ id, ...(name && name !== id ? { name } : {}), ...(contextWindow ? { contextWindow } : {}) })
+ }
+ return models.sort((a, b) => a.id.localeCompare(b.id))
+}
+
+/** The chat models `connectionId` lists, read with its saved key and kept for [LIST_FRESH_MS]. */
+export async function listApiModels(
+ store: ApiConnections,
+ connectionId: string,
+ options: ApiModelDeps & { refresh?: boolean } = {},
+): Promise<ApiModel[]> {
+ const { connection, apiKey } = store.modelAccess(connectionId)
+ const now = options.now ?? Date.now
+ const fingerprint = createHash('sha256').update(`${connection.baseUrl}\n${apiKey}`).digest('hex')
+ const kept = lists.get(connection.id)
+ if (!options.refresh && kept?.fingerprint === fingerprint && now() - kept.at < LIST_FRESH_MS) return kept.models
+ let response: Response
+ try {
+ response = await (options.fetch ?? fetch)(`${connection.baseUrl.replace(/\/+$/, '')}/models`, {
+ method: 'GET',
+ headers: { authorization: `Bearer ${apiKey}`, accept: 'application/json' },
+ redirect: 'manual',
+ signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
+ })
+ } catch {
+ throw new ApiConnectionError(`${connection.name} did not answer. Check your connection and try again.`)
+ }
+ if (!response.ok) {
+ await response.body?.cancel().catch(() => {})
+ throw new ApiConnectionError(response.status === 401 || response.status === 403
+ ? `${connection.name} did not accept the saved key. Edit the connection and paste a new key.`
+ : `${connection.name} could not list its models (HTTP ${response.status}). Try again.`)
+ }
+ const models = chatModels(await response.json().catch(() => null))
+ lists.set(connection.id, { fingerprint, at: now(), models })
+ return models
+}
+
+/**
+ * The launch that puts an agent on `model` of the saved API `connectionId`.
+ *
+ * ⚠️ The answer carries the live key; it travels only through `gridLaunch.ts`, into the engine's
+ * environment. A model the API does not list is refused rather than launched into an engine that
+ * would fail on its first message.
+ */
+export async function resolveApiTarget(
+ store: ApiConnections,
+ connectionId: string,
+ model: string,
+ deps: ApiModelDeps = {},
+): Promise<GridLaunchOverride> {
+ const { connection, apiKey } = store.modelAccess(connectionId)
+ if (!MODEL_ID.test(model)) throw new ApiConnectionError('Choose a model.')
+ const listed = (await listApiModels(store, connectionId, deps)).find((row) => row.id === model)
+ if (!listed) throw new ApiConnectionError(`${connection.name} does not list ${model} for coding agents.`)
+ rememberApiBase(connection.baseUrl)
+ return {
+ networkId: `${API_NETWORK_PREFIX}${connection.id}`,
+ networkName: connection.name,
+ baseUrl: connection.baseUrl,
+ apiKey,
+ model,
+ ...(listed.contextWindow ? { contextWindow: listed.contextWindow } : {}),
+ }
+}
+
+/**
+ * [launch] with the endpoint and key as saved NOW. A restart, a restore or a resume repeats the row's
+ * launch, and the person may have pasted a new key since; a launch that is not onto an API comes back
+ * unchanged. Throws when the connection was removed: its key must not keep being used.
+ */
+export function refreshApiLaunch(store: ApiConnections, launch: GridLaunchOverride): GridLaunchOverride {
+ if (!isApiLaunch(launch)) return launch
+ const { connection, apiKey } = store.modelAccess(launch.networkId.slice(API_NETWORK_PREFIX.length))
+ rememberApiBase(connection.baseUrl)
+ return { ...launch, networkName: connection.name, baseUrl: connection.baseUrl, apiKey }
+}
+
+/** Every saved API's endpoint, so agents already running on one are recognised (`gridAssignment.ts`). */
+export function rememberSavedApis(store: ApiConnections): void {
+ try {
+ for (const connection of store.list()) rememberApiBase(connection.baseUrl)
+ } catch {
+ // An unreadable store is reported where it is managed; recognising agents is best effort.
+ }
+}
+
+/** `api_connections {action: 'models', id}`: one API's chat models. No key in any reply. */
+export async function apiModelsRequest(
+ store: ApiConnections,
+ payload: Record<string, unknown>,
+ deps: ApiModelDeps = {},
+): Promise<Record<string, unknown>> {
+ if (typeof payload.id !== 'string' || !payload.id) return { error: 'API_MODELS_FAILED', detail: 'Choose a saved API.' }
+ try {
+ return { id: payload.id, models: await listApiModels(store, payload.id, { ...deps, refresh: payload.refresh === true }) }
+ } catch (error) {
+ return { error: 'API_MODELS_FAILED', detail: error instanceof ApiConnectionError ? error.message : 'Models are unavailable. Try again.' }
+ }
+}
diff --git a/cli/src/lib/gridAssignment.ts b/cli/src/lib/gridAssignment.ts
index c0fd92933..3f3a32b4b 100644
--- a/cli/src/lib/gridAssignment.ts
+++ b/cli/src/lib/gridAssignment.ts
@@ -21,7 +21,7 @@
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import type { AgentEngine } from '../engines/types.js'
-import { GRID_ROUTER_MODEL } from './gridLaunch.js'
+import { anthropicBaseUrl, GRID_ROUTER_MODEL, relayBaseUrl } from './gridLaunch.js'
import { readProcessEnv } from './processEnv.js'
import type { ProcessIdentity } from './registry.js'
@@ -73,6 +73,18 @@ const PI_ARGV_MODEL = /(?:^|\s)--model\s+([A-Za-z0-9_-]+)\/(\S+)/
const CODEX_BASE_URL = /model_providers\.[A-Za-z0-9_-]+\.base_url=(?:"([^"]+)"|(\S+))/
const ARGV_MODEL = /(?:^|\s)-m\s+(\S+)/
+/**
+ * Endpoints of the APIs saved on this computer (`apiModels.ts`), in both forms an engine is handed
+ * (`relayBaseUrl` and `anthropicBaseUrl`). An agent the person moved onto one of them was sent there
+ * deliberately, so it reports that model like a grid agent does. Only added to: an agent left on an
+ * API after its connection is removed is still on it.
+ */
+const apiBases = new Set<string>()
+
+export function rememberApiBase(baseUrl: string): void {
+ for (const form of [relayBaseUrl(baseUrl), anthropicBaseUrl(baseUrl)]) apiBases.add(form)
+}
+
/**
* A base URL that is not a grid is not an assignment.
*
@@ -81,6 +93,7 @@ const ARGV_MODEL = /(?:^|\s)-m\s+(\S+)/
* away from a place the user deliberately sent it.
*/
function isGridUrl(value: string): boolean {
+ if (apiBases.has(value.trim().replace(/\/+$/, ''))) return true
try {
// The relay always lives under `/relay`, whatever host serves it — that is the one part of the
// shape the control plane and both CLIs agree on (`<grid>/relay` for Messages, `/relay/v1` for
diff --git a/cli/src/lib/gridLaunch.ts b/cli/src/lib/gridLaunch.ts
index cadc1b363..8b26b4dd7 100644
--- a/cli/src/lib/gridLaunch.ts
+++ b/cli/src/lib/gridLaunch.ts
@@ -126,6 +126,17 @@ export interface GridLaunchOverride {
contextWindow?: number
}
+/**
+ * The `networkId` of a launch onto a saved API (`apiModels.ts`) rather than a grid: `api:<connection id>`.
+ * The same contracts below run it — an OpenAI-compatible API such as OpenRouter is reached exactly the
+ * way a grid's relay is — but nothing grid-specific (waking, the grid's picture) applies to it.
+ */
+export const API_NETWORK_PREFIX = 'api:'
+
+export function isApiLaunch(launch: Pick<GridLaunchOverride, 'networkId'> | null | undefined): boolean {
+ return !!launch?.networkId.startsWith(API_NETWORK_PREFIX)
+}
+
/** The smallest window believed. Anything below it is not a model a coding agent can run on, and a
* value that small is likelier a misreport than a real engine — better to say nothing than to have
* an agent compact every turn. */
@@ -277,6 +288,19 @@ export function gridProviderId(networkName: string): string {
return slug || 'grid'
}
+/**
+ * The provider id OpenCode's generated config declares for [override].
+ *
+ * A saved API is `api-<connection id>`, never its bare name: OpenCode ships built-in providers under
+ * names like `openrouter`, and a config block with the same id is merged into the built-in one rather
+ * than replacing it.
+ */
+function opencodeProviderId(override: GridLaunchOverride): string {
+ return isApiLaunch(override)
+ ? `api-${gridProviderId(override.networkId.slice(API_NETWORK_PREFIX.length))}`
+ : gridProviderId(override.networkName)
+}
+
/**
* The provider block OpenCode reads, as JSON.
*
@@ -716,7 +740,7 @@ const GRID_ENGINE_CONTRACTS: Partial<Record<AgentEngine, GridEngineContract>> =
// models are the grid's own ids. The user's `~/.config/opencode/opencode.json` is never opened.
opencode: {
build: (override) => {
- const provider = gridProviderId(override.networkName)
+ const provider = opencodeProviderId(override)
// No model chosen means the grid routes — `Auto` is the router's own id, and the relay serves
// it (verified: 200). It is a real id to OpenCode either way, which is what matters: the
// provider block has to name something, and leaving the model out entirely puts OpenCode back
diff --git a/desktop/design/terminal-dialogs.md b/desktop/design/terminal-dialogs.md
index 6f8aee505..9c14e8e5c 100644
--- a/desktop/design/terminal-dialogs.md
+++ b/desktop/design/terminal-dialogs.md
@@ -140,8 +140,14 @@ models first, followed by models served on the user's machines. Keep the
undownloaded catalog collapsed behind **[ Get models ]**; Enter expands it in
place and selects the first catalog row. **[ Hide catalog ]** collapses it.
Explicit searches also include matching catalog models. Shared rows show only
-the model and sharing machine's label, separated by ` · `. Filtering preserves
-the groups.
+the model and sharing machine's label, separated by ` · `. An API heads its models:
+`▸`/`▾` before its name says whether they are listed, and the end of its row says
+how many (`378 models`) or `Tools` for one no harness can run on. Its models
+stay folded until Enter on its row, and explicit searches include matching ones,
+always under their own API and never interleaved with another's. Model rows are
+indented under the API's name, show only the model, and say **Use** for a
+harness on this computer. Filtering
+preserves the groups.
A plain right-aligned **Use** identifies a model the current pane can use;
**Get** identifies a model that can be downloaded. Other model rows are dimmed,
@@ -169,7 +175,10 @@ uses it, on a Get row gets it, on a machine enters management, and on a harness
opens it. Arrow keys walk controls while the right pane owns focus; they must
not change the resource behind them. Left/Right retain normal cursor movement
in text fields, and move between adjacent buttons. Enter/Space activate focused
-buttons. Escape backs out of an inline form, then returns to search while
+buttons. An inline form with text fields (Cmd-P's API editor) is the one place
+Tab stays inside the pane: it walks the fields, then reaches the buttons, and
+the next Tab leaves for the list; Shift-Tab walks back and leaves from the
+first field. Escape backs out of an inline form, then returns to search while
preserving the query and selection. Hints use the live keymap. Only the active
pane shows a selection highlight.
Typing selects the first match and replaces the hints with its preview. Arrows
diff --git a/desktop/lib/core/models.dart b/desktop/lib/core/models.dart
index 25eecf1f4..228da6e02 100644
--- a/desktop/lib/core/models.dart
+++ b/desktop/lib/core/models.dart
@@ -318,6 +318,10 @@ class Agent {
/// reconnect or a restart without anything being replayed.
final GridWebSearch? gridWebSearch;
+ /// Where [gridModel] is served — the endpoint the engine was handed (a grid's relay, or a saved
+ /// API such as `https://openrouter.ai/api`). Null with no [gridModel], or from an older daemon.
+ final String? gridBaseUrl;
+
/// How the daemon's picture has the grid this agent's model is on (`grid.state`), or null when
/// it did not say — an agent on its own login, or an older daemon. Asleep or waking is what puts
/// the "Starting up…" chip on its pane between a message and the first answer.
@@ -432,6 +436,7 @@ class Agent {
this.modelName,
this.gridModel,
this.gridWebSearch,
+ this.gridBaseUrl,
this.gridState,
this.gridNote,
this.parentAgentId,
@@ -565,6 +570,7 @@ class Agent {
),
gridModel: _safeLabel(grid?['model']),
gridWebSearch: GridWebSearch.fromWire(grid?['webSearch']),
+ gridBaseUrl: _safeUrl(grid?['baseUrl']),
gridState: GridSectionState.parse(grid?['state']),
gridNote: GridNote.fromWire(grid?['note']),
parentAgentId: _safeLabel(j['parentAgentId'] ?? j['parentId']),
@@ -628,6 +634,7 @@ class Agent {
modelName: modelName,
gridModel: gridModel,
gridWebSearch: gridWebSearch,
+ gridBaseUrl: gridBaseUrl,
gridState: gridState,
gridNote: gridNote,
parentAgentId: parentAgentId,
@@ -716,6 +723,14 @@ class Agent {
return raw;
}
+ static String? _safeUrl(Object? raw) {
+ if (raw is! String || raw.isEmpty || raw.length > 2048) return null;
+ final uri = Uri.tryParse(raw);
+ return uri != null && (uri.scheme == 'https' || uri.scheme == 'http')
+ ? raw
+ : null;
+ }
+
static String? _safeLabel(Object? raw) {
if (raw is! String || raw.isEmpty) return null;
return raw.length <= 80 ? raw : raw.substring(0, 80);
diff --git a/desktop/lib/models/api_connections_controller.dart b/desktop/lib/models/api_connections_controller.dart
index f3add784e..cdd91e952 100644
--- a/desktop/lib/models/api_connections_controller.dart
+++ b/desktop/lib/models/api_connections_controller.dart
@@ -20,6 +20,12 @@ class ApiConnection {
String get authHeader => data['authHeader'] as String? ?? 'Authorization';
String get authPrefix => data['authPrefix'] as String? ?? 'Bearer';
String? get keyUrl => data['keyUrl'] as String?;
+
+ /// Coding agents authenticate to a custom endpoint only as `Authorization: Bearer <key>`, so only
+ /// such an API can list models to run a harness on (the CLI's `servesModels`).
+ bool get servesModels =>
+ authHeader.toLowerCase() == 'authorization' &&
+ authPrefix.toLowerCase() == 'bearer';
bool matches(String query) =>
'$name $baseUrl'.toLowerCase().contains(query.toLowerCase());
@@ -39,6 +45,35 @@ class ApiConnection {
});
}
+/// One chat model a saved API lists — no key, only what the API says about the model.
+class ApiModel {
+ const ApiModel({required this.id, this.name, this.contextWindow});
+ final String id;
+ final String? name;
+ final int? contextWindow;
+
+ static ApiModel? fromJson(Object? json) {
+ if (json is! Map<String, dynamic>) return null;
+ final id = json['id'];
+ if (id is! String || id.trim().isEmpty) return null;
+ final name = json['name'];
+ final window = json['contextWindow'];
+ return ApiModel(
+ id: id,
+ name: name is String && name.trim().isNotEmpty ? name : null,
+ contextWindow: window is int && window > 0 ? window : null,
+ );
+ }
+}
+
+/// What reading one API's models answered: the list, or why there is none.
+class ApiModels {
+ const ApiModels({this.models = const [], this.loading = false, this.error});
+ final List<ApiModel> models;
+ final bool loading;
+ final String? error;
+}
+
class ApiConnectionsController extends ChangeNotifier {
ApiConnectionsController(this.app) {
app.addListener(_observe);
@@ -54,6 +89,12 @@ class ApiConnectionsController extends ChangeNotifier {
bool loading = false, saving = false, loaded = false;
String? error;
+ /// Each saved API's chat models, by connection id, read while a model list is on screen
+ /// ([loadModels]). An API that takes no Bearer key has no entry: it is for tools only.
+ final Map<String, ApiModels> models = {};
+ bool _modelsWanted = false;
+ int _modelsRevision = 0;
+
bool get available => _owner?.connectionStatus == ConnectionStatus.connected;
void _changed() {
if (!_disposed) notifyListeners();
@@ -72,13 +113,86 @@ class ApiConnectionsController extends ChangeNotifier {
_owner = app.localMachineState;
_connected = available;
_revision++;
+ _modelsRevision++;
connections = [];
presets = [];
+ models.clear();
loading = saving = loaded = false;
error = null;
unawaited(refresh());
}
+ /// Read the models of every saved API that can run a harness, and keep reading them as APIs are
+ /// saved while [wanted] — a model list is on screen. Lists the CLI already holds come back at once.
+ void loadModels({bool wanted = true, bool reread = false}) {
+ _modelsWanted = wanted;
+ if (!wanted) return;
+ // The picker can open before anything read the saved APIs; that read loads models when it lands.
+ if (!loaded) {
+ if (!loading && available) unawaited(refresh());
+ return;
+ }
+ for (final connection in connections) {
+ if (!connection.servesModels) continue;
+ final known = models[connection.id];
+ if (!reread && known != null && (known.loading || known.error == null)) {
+ continue;
+ }
+ unawaited(_loadModels(connection, reread: reread));
+ }
+ }
+
+ Future<void> _loadModels(
+ ApiConnection connection, {
+ required bool reread,
+ }) async {
+ final owner = _owner;
+ if (_disposed || owner == null || !available) return;
+ final revision = _modelsRevision;
+ final previous = models[connection.id]?.models ?? const <ApiModel>[];
+ models[connection.id] = ApiModels(models: previous, loading: true);
+ _changed();
+ ApiModels answer;
+ try {
+ final reply = await app.apiConnections(owner.machine.machineId, {
+ 'action': 'models',
+ 'id': connection.id,
+ if (reread) 'refresh': true,
+ }, timeout: const Duration(seconds: 25));
+ final rows = reply['models'];
+ answer = rows is List
+ ? ApiModels(
+ models: rows
+ .map(ApiModel.fromJson)
+ .whereType<ApiModel>()
+ .toList(),
+ )
+ : const ApiModels(
+ error: 'Update Harness on this computer to use API models.',
+ );
+ } on WsRequestFailure catch (failure) {
+ answer = ApiModels(
+ models: previous,
+ // An older CLI answers the unknown action with its generic failure.
+ error: failure.code == 'API_CONNECTIONS_FAILED'
+ ? 'Update Harness on this computer to use API models.'
+ : failure.detail ?? 'Models are unavailable. Try again.',
+ );
+ } catch (_) {
+ answer = ApiModels(
+ models: previous,
+ error: 'Models are unavailable. Try again.',
+ );
+ }
+ if (_disposed ||
+ revision != _modelsRevision ||
+ !connections.any((row) => row.id == connection.id)) {
+ return;
+ }
+ models[connection.id] = answer;
+ _changed();
+ }
+
Future<bool> refresh() => _request({'action': 'list'});
Future<bool> save(Map<String, dynamic> connection) =>
_request({'action': 'save', 'connection': connection});
@@ -121,6 +235,22 @@ class ApiConnectionsController extends ChangeNotifier {
connections = rows('connections');
presets = rows('presets');
loaded = true;
+ // A saved key or URL may list different models; the CLI answers unchanged APIs from memory.
+ if (mutation) {
+ _modelsRevision++;
+ models.clear();
+ } else {
+ models.removeWhere(
+ (id, _) =>
+ !connections.any((row) => row.id == id && row.servesModels),
+ );
+ }
+ // After this request settles: [_loadModels] waits for no request, but reads [connections].
+ if (_modelsWanted) {
+ scheduleMicrotask(() {
+ if (!_disposed && _modelsWanted) loadModels();
+ });
+ }
return true;
} on WsRequestFailure catch (failure) {
if (current()) {
@@ -149,3 +279,45 @@ class ApiConnectionsController extends ChangeNotifier {
super.dispose();
}
}
+
+/// Whether [agent] already runs on [modelId] through [api]: its model, at that API's endpoint in
+/// either form an engine is handed (with `/v1`, or without it for Claude Code).
+bool agentOnApiModel(Agent? agent, ApiConnection api, String modelId) {
+ final base = agent?.gridBaseUrl;
+ if (agent?.gridModel != modelId || base == null) return false;
+ String root(String url) =>
+ url.replaceFirst(RegExp(r'/+$'), '').replaceFirst(RegExp(r'/v1$'), '');
+ return root(base) == root(api.baseUrl);
+}
+
+/// A context window as people say it: `64K`, `128K` (binary sizes), `200K`, `1M`.
+String contextWindowLabel(int tokens) {
+ if (tokens >= 1000000) {
+ final millions = (tokens / 1000000).toStringAsFixed(1);
+ return '${millions.endsWith('.0') ? millions.substring(0, millions.length - 2) : millions}M';
+ }
+ return tokens % 1024 == 0
+ ? '${tokens ~/ 1024}K'
+ : '${(tokens / 1000).round()}K';
+}
+
+/// What is wrong with [text] as an API's URL, in words that say how to fix it, or null when it is
+/// one: a full `http(s)` address with a host, and nothing the key or a request belongs in.
+String? apiUrlProblem(String text) {
+ final value = text.trim();
+ if (value.isEmpty) return "Enter the API's URL.";
+ final url = Uri.tryParse(value);
+ if (url == null ||
+ !['http', 'https'].contains(url.scheme) ||
+ url.host.isEmpty) {
+ return 'Enter the full URL, starting with https://, '
+ 'for example https://openrouter.ai/api/v1.';
+ }
+ if (url.userInfo.isNotEmpty) {
+ return 'Take the username or password out of the URL. The key has its own field.';
+ }
+ if (url.hasQuery || url.hasFragment) {
+ return 'Take the ? or # part off the end of the URL.';
+ }
+ return null;
+}
diff --git a/desktop/lib/models/api_connections_panel.dart b/desktop/lib/models/api_connections_panel.dart
index a2ff83024..41b05ea84 100644
--- a/desktop/lib/models/api_connections_panel.dart
+++ b/desktop/lib/models/api_connections_panel.dart
@@ -388,17 +388,7 @@ class _ApiEditorState extends State<_ApiEditor> {
_url,
'Base URL',
hint: 'https://api.example.com/v1',
- validator: (value) {
- final url = Uri.tryParse(value?.trim() ?? '');
- return url == null ||
- !['https', 'http'].contains(url.scheme) ||
- url.host.isEmpty ||
- url.userInfo.isNotEmpty ||
- url.hasQuery ||
- url.hasFragment
- ? 'Enter an API URL without credentials or query parameters.'
- : null;
- },
+ validator: (value) => apiUrlProblem(value ?? ''),
),
],
_field(
diff --git a/desktop/lib/models/model_search_catalog.dart b/desktop/lib/models/model_search_catalog.dart
index 667ac46b7..047610b4f 100644
--- a/desktop/lib/models/model_search_catalog.dart
+++ b/desktop/lib/models/model_search_catalog.dart
@@ -30,6 +30,7 @@ class ModelSearchEntry {
required this.status,
this.local,
this.api,
+ this.apiModel,
this.subscription,
this.node,
this.searchAliases = const [],
@@ -42,6 +43,10 @@ class ModelSearchEntry {
final String? node;
final LocalModel? local;
final ApiConnection? api;
+
+ /// One of [api]'s chat models: a row a harness can run on through that API ([api] is its API).
+ /// Null on the API's own row.
+ final ApiModel? apiModel;
final Map<String, Object?>? subscription;
final List<String> searchAliases;
final ModelManagerController? controller;
@@ -73,6 +78,7 @@ class ModelSearchEntry {
late final destination = SwarmDestination(
id: id,
modelId: id,
+ // An API's model is listed under its API's row, so it is named alone.
title: sharedBy?.isNotEmpty == true ? '$name · $sharedBy' : name,
detail: [source, node, status].whereType<String>().join(' · '),
swarmId: null,
@@ -85,11 +91,17 @@ class ModelSearchEntry {
status,
local?.id,
api?.host,
+ api?.name,
+ apiModel?.name,
...searchAliases,
],
);
}
+/// The row id of [modelId] on the API saved as [connectionId].
+String apiModelRowId(String connectionId, String modelId) =>
+ 'model:apimodel:$connectionId:$modelId';
+
class ModelSearchCatalog extends ChangeNotifier {
ModelSearchCatalog(
this.manager,
@@ -114,6 +126,7 @@ class ModelSearchCatalog extends ChangeNotifier {
void setVisible(bool visible) {
if (_visible == visible) return;
_visible = visible;
+ manager.apis.loadModels(wanted: visible);
_machinesChanged();
for (final controller in _hosts.values) {
controller.setPanelVisible(visible);
@@ -156,6 +169,7 @@ class ModelSearchCatalog extends ChangeNotifier {
Future<void> refresh({bool force = false}) async {
_machinesChanged();
+ if (_visible) manager.apis.loadModels(reread: force);
await Future.wait([
manager.refresh(force: force),
for (final controller in _hosts.values) controller.refresh(force: force),
@@ -296,7 +310,7 @@ class ModelSearchCatalog extends ChangeNotifier {
status: '${row['status'] ?? 'Usage unavailable'}',
subscription: row,
),
- for (final api in manager.apis.connections)
+ for (final api in manager.apis.connections) ...[
ModelSearchEntry(
id: 'model:api:${api.id}',
name: api.name,
@@ -304,6 +318,18 @@ class ModelSearchCatalog extends ChangeNotifier {
status: api.host,
api: api,
),
+ // Straight after their API, in the API's order: the list keeps a section's rows as built.
+ for (final model
+ in manager.apis.models[api.id]?.models ?? const <ApiModel>[])
+ ModelSearchEntry(
+ id: apiModelRowId(api.id, model.id),
+ name: model.id,
+ source: 'API',
+ status: api.name,
+ api: api,
+ apiModel: model,
+ ),
+ ],
];
final order = {for (final (index, entry) in all.indexed) entry.id: index};
all.sort((a, b) {
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 2e547605d..4bea3eea3 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -17,6 +17,7 @@ import '../core/harness_file_store.dart';
import '../core/project_folder.dart';
import '../core/test_run.dart';
import '../logging/debug_surface.dart';
+import '../models/api_connections_controller.dart' show agentOnApiModel;
import '../models/models_panel.dart';
import '../models/model_search_catalog.dart';
import '../widgets/resting_section.dart' show confirmSwitchAnyway;
@@ -3294,6 +3295,24 @@ class _SwarmScreenState extends State<SwarmScreen> {
}
if (!current()) return;
+ // A saved API's model. Decided first: the rest of this branch reads "no grid model" as the
+ // pane's own login, and would move the agent there.
+ if (search.selectableApiModel(choice.destination) case (
+ :final api,
+ :final model,
+ )) {
+ final now = WorkspacePaneContext.focused(app)!;
+ _closeSearch();
+ if (!agentOnApiModel(now.agent, api, model.id)) {
+ await app.retargetAgentToApiModel(
+ now.pane.machineId,
+ now.agentId!,
+ connectionId: api.id,
+ modelId: model.id,
+ );
+ }
+ return;
+ }
var selected = search.selectableGridModel(choice.destination);
if (selected == null && search.canStartModelForUse(choice.destination)) {
selected = await search.startModelForUse(
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 50dd6fbe1..b6af06ff6 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -5265,12 +5265,23 @@ class AppNotifier extends ChangeNotifier {
/// model, a busy agent, a machine that cannot resolve its Local models — so nothing in the
/// terminal ever says why, and until this existed the click simply did nothing. One sentence, in
/// the app's own words (`retargetRefusalMessage`); the daemon's detail names the grid.
- void _reportRetargetRefusal(String machineId, String agentId, String code) {
+ void _reportRetargetRefusal(
+ String machineId,
+ String agentId,
+ String code, {
+ bool api = false,
+ String? detail,
+ }) {
final agent = machineStates[machineId]?.agents
.where((a) => a.id == agentId)
.firstOrNull;
final label = engineIdentity(agent?.engine).label;
- _lastError = retargetRefusalMessage(code, engineLabel: label);
+ _lastError = retargetRefusalMessage(
+ code,
+ engineLabel: label,
+ api: api,
+ detail: detail,
+ );
_lastErrorRetryable = false;
notifyListeners();
}
@@ -5306,6 +5317,40 @@ class AppNotifier extends ChangeNotifier {
}
}
+ /// Point one agent at [modelId] of the API saved as [connectionId] on this computer.
+ ///
+ /// Same rule as [retargetAgentToGridModel]: the app names the model, and the daemon reads the
+ /// endpoint and key from its own store — the key never reaches the app. Only an agent on this
+ /// computer can use its saved APIs; the daemon refuses any other.
+ Future<void> retargetAgentToApiModel(
+ String machineId,
+ String agentId, {
+ required String connectionId,
+ required String modelId,
+ }) async {
+ try {
+ await _conn(machineId).request(
+ 'agent_retarget',
+ payload: {
+ 'agentId': agentId,
+ 'apiConnection': connectionId,
+ 'apiModel': modelId,
+ },
+ timeout: const Duration(seconds: 40),
+ );
+ } on WsRequestFailure catch (failure) {
+ _reportRetargetRefusal(
+ machineId,
+ agentId,
+ failure.code,
+ api: true,
+ detail: failure.detail,
+ );
+ } catch (_) {
+ // See `clearAgentGrid`: a transport failure is not a refusal, and the next frame is the truth.
+ }
+ }
+
/// One `grid_models_list` read of [machineId]'s daemon, as it answered — the raw read behind
/// [refreshGridModels], which keeps the result as the app's one picture ([gridPictures]).
///
@@ -5476,12 +5521,11 @@ class AppNotifier extends ChangeNotifier {
Future<Map<String, dynamic>> apiConnections(
String machineId,
- Map<String, dynamic> payload,
- ) => _conn(machineId).request(
- 'api_connections',
- payload: payload,
- timeout: const Duration(seconds: 10),
- );
+ Map<String, dynamic> payload, {
+ Duration timeout = const Duration(seconds: 10),
+ }) =>
+ _conn(machineId)
+ .request('api_connections', payload: payload, timeout: timeout);
Future<Map<String, dynamic>> controlLocalModel(
String machineId,
diff --git a/desktop/lib/state/retarget_refusal.dart b/desktop/lib/state/retarget_refusal.dart
index f1ebca52e..28e4ddd6c 100644
--- a/desktop/lib/state/retarget_refusal.dart
+++ b/desktop/lib/state/retarget_refusal.dart
@@ -10,8 +10,20 @@
/// says why. Until this existed, picking a Local model for a Cursor agent simply did nothing.
library;
-String retargetRefusalMessage(String code, {required String engineLabel}) {
+/// A move onto a saved API's model ([api]) is refused in its own words: its `API_UNAVAILABLE` detail
+/// is written for the person (the API's name and what to do), and its models are not Local ones.
+String retargetRefusalMessage(
+ String code, {
+ required String engineLabel,
+ bool api = false,
+ String? detail,
+}) {
return switch (code) {
+ 'API_UNAVAILABLE' => detail ?? "Couldn't use this API. Try again.",
+ 'LOCAL_ONLY' when api =>
+ 'Saved APIs can run only the harnesses on this computer.',
+ 'GRID_ENGINE_UNSUPPORTED' when api =>
+ '$engineLabel can only run on its own login, not an API model.',
'GRID_ENGINE_UNSUPPORTED' =>
'$engineLabel can only run on its own login, not a Local model.',
'GRID_MODEL_REQUIRED' =>
diff --git a/desktop/lib/state/swarm_search.dart b/desktop/lib/state/swarm_search.dart
index 79ae96e0f..6df3fecc8 100644
--- a/desktop/lib/state/swarm_search.dart
+++ b/desktop/lib/state/swarm_search.dart
@@ -3,6 +3,7 @@ import 'dart:async';
import 'package:flutter/foundation.dart';
import 'package:collection/collection.dart' show compareNatural;
+import '../models/api_connections_controller.dart' show ApiConnection, ApiModel;
import '../models/model_search_catalog.dart';
import '../core/dsh_catalog.dart';
import '../core/machine_resources.dart';
@@ -95,6 +96,76 @@ class SwarmSearchController extends ChangeNotifier {
bool modelDownloadsVisible = false;
bool isModelDownloadsRow(SwarmDestination? row) =>
isModelMode && row?.id == 'model:downloads';
+
+ /// Saved APIs whose models are shown under them. An API such as OpenRouter lists hundreds, so
+ /// they stay folded until Enter on the API's row — or a search that matches them.
+ final expandedApis = <String>{};
+
+ /// [row] is a saved API's own row (not one of its models).
+ bool isApiRow(SwarmDestination? row) {
+ final entry = models?.entries[row?.modelId];
+ return entry?.api != null && entry?.apiModel == null;
+ }
+
+ /// [row] is one of a saved API's models, listed under the API's row.
+ bool isApiModelRow(SwarmDestination? row) =>
+ models?.entries[row?.modelId]?.apiModel != null;
+
+ /// Whether [row]'s API has its models shown under it, and the words at the end of its row: how
+ /// many models it lists, or that it is for tools. Null for any other row.
+ ({bool open, String hint})? apiRowState(SwarmDestination? row) {
+ if (!isModelMode || !isApiRow(row)) return null;
+ final api = models!.entries[row!.modelId]!.api!;
+ final listed = models!.manager.apis.models[api.id];
+ final count = listed?.models.length ?? 0;
+ return (
+ // Open while any of its models is listed under it: unfolded, or found by a search.
+ open: rows.any(
+ (shown) =>
+ models!.entries[shown.modelId]?.apiModel != null &&
+ models!.entries[shown.modelId]!.api!.id == api.id,
+ ),
+ hint: !api.servesModels
+ ? 'Tools'
+ : listed?.loading == true && count == 0
+ ? 'Loading…'
+ : count > 0
+ ? '$count ${count == 1 ? 'model' : 'models'}'
+ : 'Tools',
+ );
+ }
+
+ /// Enter on [row] shows or hides its API's models: it lists some, or is still reading them.
+ bool canExpandApi(SwarmDestination? row) {
+ if (!isModelMode || !isApiRow(row)) return false;
+ final api = models!.entries[row!.modelId]!.api!;
+ final listed = models!.manager.apis.models[api.id];
+ return api.servesModels &&
+ listed != null &&
+ (listed.models.isNotEmpty || listed.loading);
+ }
+
+ /// The API model [row] offers the focused harness, or null when it cannot run on it: only a
+ /// harness on this computer, where the API's key is kept, on an engine that can be re-pointed.
+ ({ApiConnection api, ApiModel model})? selectableApiModel(
+ SwarmDestination? row,
+ ) {
+ if (!isModelMode || modelSelectionEngine == null) return null;
+ final entry = models?.entries[row?.modelId];
+ final api = entry?.api, model = entry?.apiModel;
+ if (api == null || model == null || !api.servesModels) return null;
+ if (_modelChoices?.canRunLocally(modelSelectionEngine) == false) {
+ return null;
+ }
+ final machine = app.stateOf(_modelSelectionMachineId ?? '');
+ if (machine == null ||
+ !machine.isLocalMachine ||
+ machine.connectionStatus != ConnectionStatus.connected) {
+ return null;
+ }
+ return (api: api, model: model);
+ }
+
late final _showDownloadsRow = SwarmDestination(
id: 'model:downloads',
modelId: 'model:downloads',
@@ -164,7 +235,14 @@ class SwarmSearchController extends ChangeNotifier {
if (subscription['status'] == 'Not signed in') return 'Not signed in';
return 'Other account';
}
- if (entry.api != null) return 'Tools only';
+ if (entry.apiModel != null) {
+ final machine = app.stateOf(_modelSelectionMachineId ?? '');
+ if (machine != null && !machine.isLocalMachine) {
+ return 'This computer only';
+ }
+ return 'Not available to this harness';
+ }
+ if (entry.api != null) return canExpandApi(row) ? null : 'Tools only';
if (entry.gridModel?.unavailable != null) return 'Offline';
if (entry.needsDownload) return 'Download first';
if (entry.local case final local?) {
@@ -298,7 +376,9 @@ class SwarmSearchController extends ChangeNotifier {
available['status'] != 'Not signed in' &&
available['account'] == subscription['account'];
}
- return selectableGridModel(row) != null || canStartModelForUse(row);
+ return selectableGridModel(row) != null ||
+ selectableApiModel(row) != null ||
+ canStartModelForUse(row);
}
bool canStartModelForUse(SwarmDestination? row) {
@@ -580,7 +660,10 @@ class SwarmSearchController extends ChangeNotifier {
String get createDescription => isMachineMode
? 'On the other computer:\n\n1. Install the app or CLI.\n2. Sign in to the same account.\n3. Set its password.\n\nThen select it here and Connect.'
: isModelMode
- ? 'Connect an API. Select a local model to download or start it.'
+ ? 'Add an API key\n\n'
+ 'OpenRouter or a Custom API: Use its models to run a harness.\n'
+ 'fal.ai or Replicate: harness agents can call it as a tool.\n\n'
+ 'The key stays on this computer.'
: 'Choose a harness, machine, and project.';
SwarmGroupScope? _groupScope;
bool get canGoBack => _groupScope != null;
@@ -876,6 +959,10 @@ class SwarmSearchController extends ChangeNotifier {
? modelDownloadsVisible
? 'Hide catalog'
: 'Get models'
+ : canExpandApi(row)
+ ? expandedApis.contains(models!.entries[row!.modelId]!.api!.id)
+ ? 'Hide models'
+ : 'Show models'
: canSelectModel(row)
? 'Use'
: canGetModel(row)
@@ -1160,6 +1247,12 @@ class SwarmSearchController extends ChangeNotifier {
.where((row) => models?.entries[row.modelId]?.needsDownload != true)
.toList();
}
+ if (isModelMode && matchQuery.trim().isEmpty) {
+ candidates = candidates.where((row) {
+ final entry = models?.entries[row.modelId];
+ return entry?.apiModel == null || expandedApis.contains(entry!.api!.id);
+ }).toList();
+ }
if (scopedBranch case final branch?) {
candidates = candidates.where((row) {
final machine = app.stateOf(row.machineId ?? '');
@@ -1346,13 +1439,38 @@ class SwarmSearchController extends ChangeNotifier {
modelDownloadsVisible ? _hideDownloadsRow : _showDownloadsRow,
];
}
+ // An API's models are listed under its row, as a group: a search that matches a model and not
+ // its API still shows the API above it, and the models of two APIs never interleave.
+ final shown = {for (final row in rows) row.modelId};
+ for (final row in [...rows]) {
+ final entry = models?.entries[row.modelId];
+ final heading = entry?.apiModel == null
+ ? null
+ : models!.entries['model:api:${entry!.api!.id}']?.destination;
+ if (heading != null && shown.add(heading.modelId)) rows.add(heading);
+ }
+ final apiOrder = {
+ for (final (index, row) in (models?.rows ?? const []).indexed)
+ if (isApiRow(row)) models!.entries[row.modelId]!.api!.id: index,
+ };
+ int apiGroup(SwarmDestination row) =>
+ apiOrder[models?.entries[row.modelId]?.api?.id] ?? 0;
final order = {for (final (index, row) in rows.indexed) row.id: index};
rows.sort((a, b) {
final section = modelSection(a).index.compareTo(modelSection(b).index);
if (section != 0) return section;
if (modelSection(a) != ModelSearchSection.local) {
final create = (a.isCreate ? 1 : 0).compareTo(b.isCreate ? 1 : 0);
- return create != 0 ? create : order[a.id]!.compareTo(order[b.id]!);
+ if (create != 0) return create;
+ if (modelSection(a) == ModelSearchSection.apis && !a.isCreate) {
+ final group = apiGroup(a).compareTo(apiGroup(b));
+ if (group != 0) return group;
+ final heading = (isApiRow(a) ? 0 : 1).compareTo(
+ isApiRow(b) ? 0 : 1,
+ );
+ if (heading != 0) return heading;
+ }
+ return order[a.id]!.compareTo(order[b.id]!);
}
final installed = (models?.entries[a.modelId]?.localRank ?? 1)
.compareTo(models?.entries[b.modelId]?.localRank ?? 1);
@@ -1469,6 +1587,24 @@ class SwarmSearchController extends ChangeNotifier {
SwarmSearchSelection? submit([SwarmDestination? row]) {
final destination = row ?? selected;
if (destination == null || !canSubmit(destination)) return null;
+ if (canExpandApi(destination)) {
+ final api = models!.entries[destination.modelId]!.api!;
+ final opening = expandedApis.add(api.id);
+ if (!opening) expandedApis.remove(api.id);
+ _filter();
+ final index = opening
+ ? rows.indexWhere(
+ (row) =>
+ row.modelId?.startsWith(apiModelRowId(api.id, '')) == true,
+ )
+ : rows.indexWhere((row) => row.id == destination.id);
+ if (index >= 0) {
+ cursor = index;
+ _selectedId = selected!.id;
+ }
+ notifyListeners();
+ return null;
+ }
if (isModelDownloadsRow(destination)) {
modelDownloadsVisible = !modelDownloadsVisible;
_filter();
diff --git a/desktop/lib/widgets/api_picker_form.dart b/desktop/lib/widgets/api_picker_form.dart
index 0486e0ec0..6d977a47f 100644
--- a/desktop/lib/widgets/api_picker_form.dart
+++ b/desktop/lib/widgets/api_picker_form.dart
@@ -45,6 +45,9 @@ class ApiPickerFormState extends State<ApiPickerForm> {
ApiConnection? _editing;
bool _advanced = false, _visible = false;
String? _error;
+
+ /// The field [_error] is about, drawn under it; null for an error about the whole form.
+ String? _errorField;
ApiConnectionsController get controller => widget.controller;
bool get _existing => _editing?.id.isNotEmpty == true;
bool get _enabled => controller.available && !controller.saving;
@@ -102,7 +105,7 @@ class ApiPickerFormState extends State<ApiPickerForm> {
}
_advanced = false;
_visible = false;
- _error = null;
+ _error = _errorField = null;
}
void _choose(ApiConnection connection) {
@@ -181,7 +184,7 @@ class ApiPickerFormState extends State<ApiPickerForm> {
setState(() {
_fields['key']?.clear();
_editing = null;
- _error = null;
+ _error = _errorField = null;
});
focus();
},
@@ -226,6 +229,36 @@ class ApiPickerFormState extends State<ApiPickerForm> {
}
}
+ /// Tab walks the fields as any form does, then the buttons as one stop, then leaves for the
+ /// other pane; Shift-Tab walks back, leaving from the first field. With no fields (the provider
+ /// choices), Tab leaves at once — the picker's usual pane switch.
+ void _tab(bool forward) {
+ final fields = [for (final id in _visibleFields) _inputs[id]!];
+ final at = fields.indexWhere((node) => node.hasFocus);
+ final onButtons = _buttons.values.any((node) => node.hasFocus);
+ FocusNode? next;
+ if (forward && at >= 0) {
+ next = at < fields.length - 1
+ ? fields[at + 1]
+ : _actions
+ .where((action) => action.run != null)
+ .map((action) => _buttons[action.id])
+ .nonNulls
+ .firstOrNull;
+ } else if (!forward && at > 0) {
+ next = fields[at - 1];
+ } else if (!forward && onButtons) {
+ next = fields.lastOrNull;
+ }
+ if (next != null) {
+ next.requestFocus();
+ } else if (widget.onSwitchPane != null) {
+ widget.onSwitchPane!();
+ } else {
+ _move(forward);
+ }
+ }
+
bool handle(String command) {
if (_composing) return true;
switch (command) {
@@ -234,9 +267,9 @@ class ApiPickerFormState extends State<ApiPickerForm> {
case 'picker.accept':
_scope.hasFocus ? _accept() : focus();
case 'picker.complete':
- widget.onSwitchPane != null ? widget.onSwitchPane!() : _move(true);
+ _tab(true);
case 'picker.complete_back':
- widget.onSwitchPane != null ? widget.onSwitchPane!() : _move(false);
+ _tab(false);
case 'picker.next':
if (!_scope.hasFocus) return false;
_move(true);
@@ -263,32 +296,37 @@ class ApiPickerFormState extends State<ApiPickerForm> {
Future<void> _save() async {
if (!_enabled || _composing) return;
- final url = Uri.tryParse(_fields['url']!.text.trim());
- final invalid = _fields['name']!.text.trim().isEmpty
- ? 'Enter a name.'
- : url == null ||
- !['http', 'https'].contains(url.scheme) ||
- url.host.isEmpty ||
- url.userInfo.isNotEmpty ||
- url.hasQuery ||
- url.hasFragment
- ? 'Enter an API URL without credentials or query parameters.'
+ // The first field that is wrong: its sentence goes under it, and the cursor into it.
+ final urlProblem = apiUrlProblem(_fields['url']!.text);
+ final (String field, String problem)? invalid =
+ _fields['name']!.text.trim().isEmpty
+ ? ('name', 'Enter a name for this API.')
+ : urlProblem != null
+ ? ('url', urlProblem)
: !_existing && _fields['key']!.text.trim().isEmpty
- ? 'Enter an API key.'
+ ? ('key', 'Paste the API key.')
: _fields['header']!.text.trim().isEmpty
- ? 'Enter an authentication header.'
+ ? ('header', 'Enter an authentication header, such as Authorization.')
: null;
- if (invalid != null) {
- setState(() => _error = invalid);
+ if (invalid case (final field, final problem)) {
+ final shown = _visibleFields.contains(field);
+ setState(() {
+ _error = problem;
+ _errorField = shown ? field : null;
+ });
+ if (shown) _inputs[field]!.requestFocus();
return;
}
final editing = _editing!;
if (_existing &&
!controller.connections.any((row) => row.id == editing.id)) {
- setState(() => _error = 'This API was removed. Return to the list.');
+ setState(() {
+ _error = 'This API was removed. Return to the list.';
+ _errorField = null;
+ });
return;
}
- setState(() => _error = null);
+ setState(() => _error = _errorField = null);
final name = _fields['name']!.text.trim();
final saved = await controller.save({
if (_existing) 'id': editing.id,
@@ -463,7 +501,7 @@ class ApiPickerFormState extends State<ApiPickerForm> {
enabled: !controller.saving,
onChanged: (_) {
if (_error != null) {
- setState(() => _error = null);
+ setState(() => _error = _errorField = null);
}
},
child: TextField(
@@ -491,11 +529,21 @@ class ApiPickerFormState extends State<ApiPickerForm> {
onEditingComplete: () {},
onChanged: (_) {
if (_error != null) {
- setState(() => _error = null);
+ setState(
+ () => _error = _errorField = null,
+ );
}
},
),
),
+ if (_errorField == id && _error != null)
+ Text(
+ _error!,
+ key: ValueKey('api-form-error:$id'),
+ style: terminalContentStyle(
+ color: theme.yellow,
+ ),
+ ),
],
),
),
@@ -503,7 +551,9 @@ class ApiPickerFormState extends State<ApiPickerForm> {
Text('Stored on this computer.', style: muted),
SizedBox(height: cell.height),
],
- if (_error ?? controller.error case final error?) ...[
+ if ((_errorField == null ? _error : null) ??
+ controller.error
+ case final error?) ...[
Text(
error,
style: terminalContentStyle(color: theme.yellow),
@@ -555,7 +605,9 @@ class ApiPickerFormState extends State<ApiPickerForm> {
),
(
'picker.complete',
- widget.onSwitchPane != null ? 'pane' : 'next',
+ widget.onSwitchPane == null || _visibleFields.isNotEmpty
+ ? 'next'
+ : 'pane',
),
('picker.cancel', 'back'),
])
diff --git a/desktop/lib/widgets/swarm_resource_preview.dart b/desktop/lib/widgets/swarm_resource_preview.dart
index bba0c5867..afff23083 100644
--- a/desktop/lib/widgets/swarm_resource_preview.dart
+++ b/desktop/lib/widgets/swarm_resource_preview.dart
@@ -7,6 +7,8 @@ import '../core/models.dart';
import '../core/test_run.dart';
import '../shortcuts/app_keymap.dart';
import '../shortcuts/keymap.dart';
+import '../models/api_connections_controller.dart'
+ show ApiModels, contextWindowLabel;
import '../models/model_search_catalog.dart';
import '../shared/theme/app_theme.dart' as grid;
import '../state/app_state.dart';
@@ -329,7 +331,8 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
return true;
}
if (widget.search.canSelectModel(row) ||
- widget.search.isModelDownloadsRow(row)) {
+ widget.search.isModelDownloadsRow(row) ||
+ widget.search.canExpandApi(row)) {
_open();
return true;
}
@@ -635,14 +638,15 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
row?.isModel != true ||
widget.search.canSelectModel(row) ||
widget.search.canGetModel(row) ||
- widget.search.isModelDownloadsRow(row))
+ widget.search.isModelDownloadsRow(row) ||
+ widget.search.canExpandApi(row))
'$enter ${managing
? 'select'
: widget.search.canSelectModel(row)
? 'Use'
: widget.search.canGetModel(row)
? 'Get'
- : widget.search.isModelDownloadsRow(row)
+ : widget.search.isModelDownloadsRow(row) || widget.search.canExpandApi(row)
? widget.search.actionLabel(row)
: _isManagement
? _machineSetup
@@ -776,8 +780,23 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
),
];
}
+ if (model?.apiModel != null) {
+ return [
+ _ResourceAction(
+ 'Use',
+ !busy && search.canSelectModel(selected) ? _open : null,
+ command: 'picker.accept',
+ ),
+ ];
+ }
if (api != null) {
return [
+ if (search.canExpandApi(selected))
+ _ResourceAction(
+ search.actionLabel(selected),
+ _open,
+ command: 'picker.accept',
+ ),
_ResourceAction(
'Edit',
busy ? null : () => _editApi(api.id),
@@ -883,6 +902,9 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
_apiFormOpen = false;
_apiResource = null;
});
+ // The editor owned the keys, and a removed widget reports no focus change: hand them back to
+ // the list, or arrows keep acting for a pane that is no longer there.
+ widget.search.setManaging(false);
if (id?.isNotEmpty == true) {
final search = widget.search;
if (!search.rows.any((row) => row.modelId == 'model:api:$id')) {
@@ -1030,6 +1052,7 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
: seconds % 3600 == 0
? '${(seconds / 3600).toInt()}h'
: '${seconds.toInt()}s';
+ if (entry.api != null) return _apiPreview(entry);
return _details([
entry.name,
if (widget.search.modelUseErrorId == entry.id)
@@ -1072,6 +1095,8 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
'Other account' =>
'This account is not signed in on the harness’s machine.',
'Not serving' => 'Not serving on ${entry.node ?? 'its host'}.',
+ 'This computer only' =>
+ 'Saved APIs run the harnesses on this computer only.',
_ => reason,
},
if (entry.own && local == null && owner.scanning)
@@ -1082,11 +1107,6 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
else
?owner.error,
],
- if (entry.api case final api?) ...[
- api.baseUrl,
- api.keyEnv,
- 'Available to harness tools on this computer.',
- ],
if (entry.subscription case final subscription?) ...[
...((subscription['details'] as List?) ?? const [])
.map((detail) => '$detail')
@@ -1095,6 +1115,63 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
], controls: true);
}
+ static const _kDetailLabelColumns = 9;
+
+ /// A saved API, or one of its models: a summary line, then labelled facts, then what it is for.
+ Widget _apiPreview(ModelSearchEntry entry) {
+ final api = entry.api!;
+ final listed = widget.search.models!.manager.apis.models[api.id];
+ final model = entry.apiModel;
+ if (model != null) {
+ final reason = widget.search.modelUseReason(row);
+ return _details([
+ entry.name,
+ [
+ api.name,
+ if (model.contextWindow case final window?)
+ '${contextWindowLabel(window)} context',
+ ].join(' · '),
+ '',
+ if (model.name case final name?) ('Name', name),
+ ('Via', '${api.name} · ${api.host}'),
+ '',
+ if (reason == null)
+ 'Use runs this harness on it, with the key saved on this computer.'
+ else if (reason == 'This computer only')
+ 'Saved APIs run the harnesses on this computer only.'
+ else
+ reason,
+ ], controls: true);
+ }
+ final count = listed?.models.length ?? 0;
+ // One line for what the API is for: a harness runs on its models (Use), or harness agents call
+ // it (Tools) — fal.ai, Replicate, and any API that lists no models a coding agent can run on.
+ final summary = !api.servesModels || count > 0
+ ? null
+ : switch (listed) {
+ ApiModels(loading: true) => 'Loading models…',
+ ApiModels(error: _?) => 'Models unavailable',
+ _ => null,
+ };
+ return _details([
+ entry.name,
+ ['API', ?summary].join(' · '),
+ '',
+ ('URL', api.baseUrl),
+ if (count > 0)
+ (
+ 'Use',
+ 'pick one of its $count ${count == 1 ? 'model' : 'models'} to run a harness on it',
+ )
+ else if (summary == null)
+ (
+ 'Tools',
+ 'harness agents on this computer can call it with the saved key',
+ ),
+ if (listed?.error case final error?) ...['', error],
+ ], controls: true);
+ }
+
Widget _machinePreview() {
final machine = app.stateOf(row!.machineId!);
if (machine == null) return _details([row!.title, 'Unavailable']);
@@ -1133,12 +1210,17 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
], controls: true);
}
- Widget _details(List<String> lines, {bool controls = false}) {
+ /// The preview's lines: the first is the title, `''` is a blank row, and a `(label, value)`
+ /// pair is a labelled row — [_kDetailLabelColumns] columns of label, the value wrapping beside it.
+ Widget _details(List<Object> lines, {bool controls = false}) {
final cell = terminalCellSizeOf(context);
final theme = terminalThemeFor(
grid.AppTheme.palette.value,
terminalThemeStore.value,
);
+ final muted = terminalContentStyle(
+ color: theme.foreground.withValues(alpha: .54),
+ );
return ListView(
controller: _scroll,
padding: EdgeInsets.symmetric(
@@ -1147,17 +1229,30 @@ class _SwarmResourcePreviewState extends State<SwarmResourcePreview> {
),
children: [
for (var i = 0; i < lines.length; i++)
- if (lines[i].isEmpty)
- SizedBox(height: cell.height)
- else
- Text(
- lines[i],
- style: terminalContentStyle(
- color: i == 0
- ? theme.foreground
- : theme.foreground.withValues(alpha: .54),
- ),
+ switch (lines[i]) {
+ '' => SizedBox(height: cell.height),
+ (final String label, final String value) => Row(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ SizedBox(
+ width: cell.width * _kDetailLabelColumns,
+ child: Text(label, style: muted),
+ ),
+ Expanded(
+ child: Text(
+ value,
+ style: terminalContentStyle(color: theme.foreground),
+ ),
+ ),
+ ],
+ ),
+ final line => Text(
+ '$line',
+ style: i == 0
+ ? terminalContentStyle(color: theme.foreground)
+ : muted,
),
+ },
if (controls) ...[SizedBox(height: cell.height), _actionButtons()],
],
);
diff --git a/desktop/lib/widgets/swarm_switcher.dart b/desktop/lib/widgets/swarm_switcher.dart
index e09dd1799..a42a1a54b 100644
--- a/desktop/lib/widgets/swarm_switcher.dart
+++ b/desktop/lib/widgets/swarm_switcher.dart
@@ -1331,11 +1331,16 @@ class _SearchRowContentState extends State<_SearchRowContent> {
final modelAction = row.isModel
? widget.search.modelRowAction(row)
: null;
+ // A saved API heads its models: a marker says whether they are listed under it, and the end
+ // of its row how many there are. Its models sit one step in, under its name.
+ final apiRow = row.isModel ? widget.search.apiRowState(row) : null;
+ final underApi = row.isModel && widget.search.isApiModelRow(row);
final style = terminalContentStyle(
color:
!widget.enabled ||
(row.isModel &&
!widget.search.isModelDownloadsRow(row) &&
+ !widget.search.canExpandApi(row) &&
!widget.search.canSelectModel(row) &&
!widget.search.canGetModel(row))
? theme.foreground.withValues(alpha: .28)
@@ -1379,6 +1384,21 @@ class _SearchRowContentState extends State<_SearchRowContent> {
children: [
// Match Cmd-N's empty two-cell gutter.
SizedBox(width: cell.width * 2),
+ if (apiRow != null)
+ SizedBox(
+ width: cell.width * 2,
+ child: Text(
+ apiRow.hint == 'Tools'
+ ? ''
+ : apiRow.open
+ ? '▾'
+ : '▸',
+ key: ValueKey('api-row-marker:${row.id}'),
+ style: style,
+ ),
+ )
+ else if (underApi)
+ SizedBox(width: cell.width * 4),
if (widget.singleLine && snippet != null) ...[
// One line per result: the name, then where the words
// were said, the way fzf shows the matching line.
@@ -1409,7 +1429,15 @@ class _SearchRowContentState extends State<_SearchRowContent> {
style: style,
),
),
- if (modelAction != null) ...[
+ if (apiRow != null) ...[
+ SizedBox(width: cell.width * 2),
+ Text(
+ apiRow.hint,
+ key: ValueKey('api-row-hint:${row.id}'),
+ maxLines: 1,
+ style: terminalContentStyle(color: muted),
+ ),
+ ] else if (modelAction != null) ...[
SizedBox(width: cell.width * 2),
Text(
modelAction,
diff --git a/desktop/test/api_connections_test.dart b/desktop/test/api_connections_test.dart
index 7a09a2119..8be4cd0d9 100644
--- a/desktop/test/api_connections_test.dart
+++ b/desktop/test/api_connections_test.dart
@@ -41,8 +41,9 @@ class _ApiApp extends ModelManagerTestApp {
@override
Future<Map<String, dynamic>> apiConnections(
String machineId,
- Map<String, dynamic> payload,
- ) async {
+ Map<String, dynamic> payload, {
+ Duration timeout = const Duration(seconds: 10),
+ }) async {
expect(machineId, 'm');
requests.add(payload);
if (failure != null) throw failure!;
@@ -205,7 +206,7 @@ void main() {
await tester.sendKeyEvent(LogicalKeyboardKey.enter);
await tester.pumpAndSettle();
expect(
- find.textContaining('without credentials or query parameters'),
+ find.text('Take the ? or # part off the end of the URL.'),
findsOneWidget,
);
expect(app.requests.where((row) => row['action'] == 'save'), isEmpty);
@@ -1095,7 +1096,10 @@ void main() {
await tester.tap(find.text('Save'));
await tester.pumpAndSettle();
expect(
- find.text('Enter an API URL without credentials or query parameters.'),
+ find.text(
+ 'Enter the full URL, starting with https://, '
+ 'for example https://openrouter.ai/api/v1.',
+ ),
findsOneWidget,
);
expect(tester.takeException(), isNull);
diff --git a/desktop/test/api_model_picker_test.dart b/desktop/test/api_model_picker_test.dart
new file mode 100644
index 000000000..55ca71f43
--- /dev/null
+++ b/desktop/test/api_model_picker_test.dart
@@ -0,0 +1,646 @@
+// A saved API as a place to run a harness (Cmd-I / Cmd-P `:`): an API that takes a Bearer key lists
+// its chat models folded under its row, Enter shows them, and Use moves the focused pane's agent onto
+// one through the daemon — which reads the endpoint and key itself. Only this computer's harnesses
+// can use its APIs, and an API that takes no Bearer key stays tools-only.
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/models.dart';
+import 'package:harness/models/api_connections_controller.dart';
+import 'package:harness/models/model_search_catalog.dart';
+import 'package:harness/state/app_state.dart';
+import 'package:harness/state/retarget_refusal.dart';
+import 'package:harness/state/swarm_navigation.dart';
+import 'package:harness/state/swarm_search.dart';
+import 'package:harness/widgets/swarm_resource_preview.dart';
+import 'package:harness/widgets/swarm_switcher.dart';
+import 'package:harness/ws/local_cli_discovery.dart';
+
+import 'keymap_host_test.dart' show MemoryKeymap, key;
+import 'keymap_runtime_test.dart' as configured;
+import 'resource_picker_test.dart' show fixture;
+import 'support/model_manager.dart';
+import 'support/real_fonts.dart';
+
+final field = find.byKey(const ValueKey('swarm-search-input'));
+SwarmSearchController search(WidgetTester tester) =>
+ tester.widget<SwarmSearchResults>(find.byType(SwarmSearchResults)).search;
+
+const openRouter = ApiConnection({
+ 'id': 'openrouter',
+ 'provider': 'openrouter',
+ 'name': 'OpenRouter',
+ 'baseUrl': 'https://openrouter.ai/api/v1',
+ 'keyEnv': 'OPENROUTER_API_KEY',
+ 'authHeader': 'Authorization',
+ 'authPrefix': 'Bearer',
+});
+const customDs = ApiConnection({
+ 'id': 'custom-ds',
+ 'provider': 'custom',
+ 'name': 'custom ds',
+ 'baseUrl': 'https://relay.example.test/v1',
+ 'keyEnv': 'CUSTOM_DS_API_KEY',
+ 'authHeader': 'Authorization',
+ 'authPrefix': 'Bearer',
+});
+const fal = ApiConnection({
+ 'id': 'fal-ai',
+ 'provider': 'fal',
+ 'name': 'fal.ai',
+ 'baseUrl': 'https://queue.fal.run',
+ 'keyEnv': 'FAL_KEY',
+ 'authHeader': 'Authorization',
+ 'authPrefix': 'Key',
+});
+
+class _ApiApp extends ModelManagerTestApp {
+ _ApiApp() : super(ModelManagerConnection());
+ final modelReads = <String>[];
+ final moves = <({String machine, String agent, String api, String model})>[];
+ Map<String, dynamic> Function(String id)? answer;
+
+ @override
+ Future<Map<String, dynamic>> apiConnections(
+ String machineId,
+ Map<String, dynamic> payload, {
+ Duration timeout = const Duration(seconds: 10),
+ }) async {
+ if (payload['action'] == 'models') {
+ final id = payload['id'] as String;
+ modelReads.add(id);
+ return answer?.call(id) ??
+ {
+ 'id': id,
+ 'models': [
+ {
+ 'id': 'anthropic/claude-sonnet-4.6',
+ 'name': 'Anthropic: Claude Sonnet 4.6',
+ 'contextWindow': 1000000,
+ },
+ {'id': 'z-ai/glm-5', 'contextWindow': 202752},
+ ],
+ };
+ }
+ if (payload['action'] == 'save') {
+ final input = Map<String, dynamic>.from(payload['connection'] as Map)
+ ..remove('apiKey');
+ input['id'] = '${input['name']}'.toLowerCase().replaceAll(
+ RegExp('[^a-z0-9]+'),
+ '-',
+ );
+ listed = [...listed.where((row) => row['id'] != input['id']), input];
+ }
+ return {'connections': listed, 'presets': const <Object>[]};
+ }
+
+ /// The APIs the CLI would list: the fixture's, then any saved through the editor.
+ List<Map<String, dynamic>> listed = [openRouter.data, fal.data];
+
+ @override
+ Future<void> retargetAgentToApiModel(
+ String machineId,
+ String agentId, {
+ required String connectionId,
+ required String modelId,
+ }) async {
+ moves.add((
+ machine: machineId,
+ agent: agentId,
+ api: connectionId,
+ model: modelId,
+ ));
+ }
+}
+
+Future<_ApiApp> _apiFixture({String agentMachine = 'm', Agent? agent}) async {
+ final app = _ApiApp()
+ ..inventory = const GridModels(
+ gridName: 'home',
+ models: [],
+ grids: [GridSection(name: 'home', own: true, models: [])],
+ );
+ await fixture(provided: app);
+ app.modelManager.apis.connections = [openRouter, fal];
+ final machine = app.machineStates[agentMachine]!
+ ..localEndpoint = LocalCliEndpoint(
+ computerId: 'fixture',
+ wsUri: Uri.parse('ws://fixture.invalid'),
+ protocolVersion: 1,
+ terminalProtocolVersion: 3,
+ )
+ ..connectionStatus = ConnectionStatus.connected
+ ..agentLoadStatus = AgentLoadStatus.loaded;
+ machine.agents.add(
+ agent ??
+ const Agent(
+ id: 'a69',
+ name: 'Current harness',
+ engine: 'claude',
+ terminalAvailable: true,
+ ),
+ );
+ return app;
+}
+
+String rowTitle(SwarmDestination row) => row.title;
+
+Finder inPreview(String text) => find.descendant(
+ of: find.byType(SwarmResourcePreview),
+ matching: find.text(text),
+);
+
+void main() {
+ setUpAll(loadRealFonts);
+
+ testWidgets(
+ "an API's models stay folded until Enter on its row, and Use moves the pane onto one",
+ (tester) async {
+ final app = await _apiFixture();
+ final map = MemoryKeymap();
+ try {
+ await configured.mount(tester, app, map);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ final picker = search(tester);
+ expect(picker.modelSelectionEngine, 'claude');
+ // Read once for the API that takes a Bearer key; fal.ai is for tools only.
+ expect(app.modelReads, ['openrouter']);
+ expect(
+ picker.rows.where(
+ (row) => row.modelId?.startsWith('model:apimodel:') == true,
+ ),
+ isEmpty,
+ );
+ final apiRow = picker.rows.singleWhere(
+ (row) => row.modelId == 'model:api:openrouter',
+ );
+ expect(picker.canExpandApi(apiRow), isTrue);
+ expect(
+ picker.canExpandApi(
+ picker.rows.singleWhere((row) => row.modelId == 'model:api:fal-ai'),
+ ),
+ isFalse,
+ );
+ // fal.ai lists no models to run a harness on: its preview says what it is for instead.
+ final falRow = picker.rows.singleWhere(
+ (row) => row.modelId == 'model:api:fal-ai',
+ );
+ picker.move(picker.rows.indexOf(falRow) - picker.cursor);
+ await tester.pump();
+ expect(inPreview('Tools'), findsOneWidget);
+ expect(
+ find.text(
+ 'harness agents on this computer can call it with the saved key',
+ ),
+ findsOneWidget,
+ );
+ expect(find.textContaining('models to run a harness'), findsNothing);
+
+ // Folded: a marker to open it, and how many models it has at the end of its row.
+ expect(
+ tester
+ .widget<Text>(
+ find.byKey(
+ const ValueKey('api-row-marker:model:api:openrouter'),
+ ),
+ )
+ .data,
+ '▸',
+ );
+ expect(
+ tester
+ .widget<Text>(
+ find.byKey(const ValueKey('api-row-hint:model:api:openrouter')),
+ )
+ .data,
+ '2 models',
+ );
+ expect(
+ tester
+ .widget<Text>(
+ find.byKey(const ValueKey('api-row-hint:model:api:fal-ai')),
+ )
+ .data,
+ 'Tools',
+ );
+ picker.move(picker.rows.indexOf(apiRow) - picker.cursor);
+ await tester.pump();
+ expect(
+ find.text('pick one of its 2 models to run a harness on it'),
+ findsOneWidget,
+ );
+ expect(find.text('Use'), findsWidgets);
+ expect(find.text('https://openrouter.ai/api/v1'), findsOneWidget);
+ expect(inPreview('Key'), findsNothing);
+ expect(find.textContaining('OPENROUTER_API_KEY'), findsNothing);
+ expect(inPreview('Tools'), findsNothing);
+ expect(picker.actionLabel(apiRow), 'Show models');
+
+ await key(tester, LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(picker.expandedApis, {'openrouter'});
+ expect(
+ picker.selected!.modelId,
+ apiModelRowId('openrouter', 'anthropic/claude-sonnet-4.6'),
+ );
+ // Named alone, one step in under its API, which now says it is open.
+ expect(picker.selected!.title, 'anthropic/claude-sonnet-4.6');
+ final marker = find.byKey(
+ const ValueKey('api-row-marker:model:api:openrouter'),
+ );
+ expect(tester.widget<Text>(marker).data, '▾');
+ expect(
+ tester
+ .getTopLeft(
+ find.descendant(
+ of: find.byKey(
+ ValueKey(
+ 'swarm-search-line:${apiModelRowId('openrouter', 'anthropic/claude-sonnet-4.6')}',
+ ),
+ ),
+ matching: find.text('anthropic/claude-sonnet-4.6'),
+ ),
+ )
+ .dx,
+ greaterThan(
+ tester
+ .getTopLeft(
+ find.descendant(
+ of: find.byKey(
+ const ValueKey('swarm-search-line:model:api:openrouter'),
+ ),
+ matching: find.text('OpenRouter'),
+ ),
+ )
+ .dx,
+ ),
+ );
+ expect(picker.modelRowAction(picker.selected!), 'Use');
+ expect(find.text('OpenRouter · 1M context'), findsOneWidget);
+ expect(find.text('Anthropic: Claude Sonnet 4.6'), findsOneWidget);
+ expect(app.moves, isEmpty);
+
+ await key(tester, LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+ expect(app.moves, [
+ (
+ machine: 'm',
+ agent: 'a69',
+ api: 'openrouter',
+ model: 'anthropic/claude-sonnet-4.6',
+ ),
+ ]);
+ expect(find.byType(SwarmSearchResults), findsNothing);
+ expect(tester.takeException(), isNull);
+ } finally {
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ map.dispose();
+ }
+ },
+ );
+
+ testWidgets(
+ '[ Add ] under APIs says what an API is for, and nothing about local models',
+ (tester) async {
+ final app = await _apiFixture();
+ final map = MemoryKeymap();
+ try {
+ await configured.mount(tester, app, map);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ final picker = search(tester);
+ final add = picker.rows.singleWhere((row) => row.isCreate);
+ picker.move(picker.rows.indexOf(add) - picker.cursor);
+ await tester.pump();
+ expect(find.text('Add an API key'), findsOneWidget);
+ expect(
+ find.text(
+ 'OpenRouter or a Custom API: Use its models to run a harness.',
+ ),
+ findsOneWidget,
+ );
+ expect(
+ find.text(
+ 'fal.ai or Replicate: harness agents can call it as a tool.',
+ ),
+ findsOneWidget,
+ );
+ expect(find.textContaining('local model'), findsNothing);
+ } finally {
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ map.dispose();
+ }
+ },
+ );
+
+ testWidgets(
+ 'a search finds API models without unfolding them, each under its own API',
+ (tester) async {
+ final app = await _apiFixture();
+ app.modelManager.apis.connections = [openRouter, customDs, fal];
+ final map = MemoryKeymap();
+ try {
+ await configured.mount(tester, app, map);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ await tester.enterText(field, ':glm');
+ await tester.pumpAndSettle();
+ final picker = search(tester);
+ final apis = picker.rows
+ .where((row) => picker.isApiRow(row) || picker.isApiModelRow(row))
+ .map((row) => row.modelId)
+ .toList();
+ // Both APIs list the model: each copy sits under its own API, and neither API unfolded.
+ expect(apis, [
+ 'model:api:openrouter',
+ apiModelRowId('openrouter', 'z-ai/glm-5'),
+ 'model:api:custom-ds',
+ apiModelRowId('custom-ds', 'z-ai/glm-5'),
+ ]);
+ expect(picker.expandedApis, isEmpty);
+ expect(find.text('z-ai/glm-5'), findsNWidgets(2));
+ expect(find.textContaining('· OpenRouter'), findsNothing);
+ } finally {
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ map.dispose();
+ }
+ },
+ );
+
+ testWidgets('Save returns to the list on the new API, ready to open it', (
+ tester,
+ ) async {
+ final app = await _apiFixture();
+ final map = MemoryKeymap();
+ try {
+ await configured.mount(tester, app, map);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ final picker = search(tester);
+ final add = picker.rows.singleWhere((row) => row.isCreate);
+ picker.move(picker.rows.indexOf(add) - picker.cursor);
+ await tester.pump();
+ await key(tester, LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+ await tester.tap(find.byKey(const ValueKey('api-form:provider:custom')));
+ await tester.pumpAndSettle();
+ await tester.enterText(
+ find.byKey(const ValueKey('api-form-input:name')),
+ 'haha cust',
+ );
+ await key(tester, LogicalKeyboardKey.tab);
+ expect(
+ tester
+ .widget<TextField>(find.byKey(const ValueKey('api-form-input:url')))
+ .focusNode!
+ .hasFocus,
+ isTrue,
+ );
+ await tester.enterText(
+ find.byKey(const ValueKey('api-form-input:url')),
+ 'https://relay.example.test/v1',
+ );
+ await tester.enterText(
+ find.byKey(const ValueKey('api-form-input:key')),
+ 'fixture-key',
+ );
+ // Tab from the last field reaches Save; Enter presses it.
+ await key(tester, LogicalKeyboardKey.tab);
+ await key(tester, LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+
+ // Back on the list, on the API just saved, with the keys in the list rather than the pane.
+ expect(find.byKey(const ValueKey('api-form:save')), findsNothing);
+ expect(picker.selected?.modelId, 'model:api:haha-cust');
+ expect(picker.managing, isFalse);
+ expect(tester.widget<TextField>(field).focusNode!.hasFocus, isTrue);
+ await tester.pumpAndSettle();
+ // Enter opens its models straight away.
+ await key(tester, LogicalKeyboardKey.enter);
+ await tester.pump();
+ expect(picker.expandedApis, contains('haha-cust'));
+ expect(
+ picker.selected?.modelId,
+ apiModelRowId('haha-cust', 'anthropic/claude-sonnet-4.6'),
+ );
+ } finally {
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ map.dispose();
+ }
+ });
+
+ testWidgets('a URL that is not one says how to fix it, under the URL', (
+ tester,
+ ) async {
+ final app = await _apiFixture();
+ final map = MemoryKeymap();
+ try {
+ await configured.mount(tester, app, map);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ final picker = search(tester);
+ final add = picker.rows.singleWhere((row) => row.isCreate);
+ picker.move(picker.rows.indexOf(add) - picker.cursor);
+ await tester.pump();
+ await key(tester, LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+ await tester.tap(find.byKey(const ValueKey('api-form:provider:custom')));
+ await tester.pumpAndSettle();
+ Finder input(String id) => find.byKey(ValueKey('api-form-input:$id'));
+ await tester.enterText(input('name'), 'fdafd');
+ await tester.enterText(input('url'), 'fdfd');
+ await tester.enterText(input('key'), 'fixture-key');
+ await tester.tap(find.byKey(const ValueKey('api-form:save')));
+ await tester.pumpAndSettle();
+
+ final error = find.byKey(const ValueKey('api-form-error:url'));
+ expect(
+ tester.widget<Text>(error).data,
+ 'Enter the full URL, starting with https://, '
+ 'for example https://openrouter.ai/api/v1.',
+ );
+ // Under the URL, above the next field — and nothing was saved.
+ expect(
+ tester.getTopLeft(error).dy,
+ greaterThan(tester.getTopLeft(input('url')).dy),
+ );
+ expect(
+ tester.getTopLeft(error).dy,
+ lessThan(tester.getTopLeft(input('key')).dy),
+ );
+ expect(
+ tester.widget<TextField>(input('url')).focusNode!.hasFocus,
+ isTrue,
+ );
+ expect(find.byKey(const ValueKey('api-form:save')), findsOneWidget);
+ expect(app.listed.map((row) => row['name']), isNot(contains('fdafd')));
+ // Typing a fix takes the sentence away.
+ await tester.enterText(input('url'), 'https://relay.example.test/v1');
+ await tester.pump();
+ expect(error, findsNothing);
+ } finally {
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ map.dispose();
+ }
+ });
+
+ testWidgets('the model the pane is already on moves nothing', (tester) async {
+ final app = await _apiFixture(
+ agent: const Agent(
+ id: 'a69',
+ name: 'Current harness',
+ engine: 'claude',
+ terminalAvailable: true,
+ gridModel: 'z-ai/glm-5',
+ // What the daemon reads off Claude Code: the endpoint without `/v1`.
+ gridBaseUrl: 'https://openrouter.ai/api',
+ ),
+ );
+ final map = MemoryKeymap();
+ try {
+ await configured.mount(tester, app, map);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ await tester.enterText(field, ':glm');
+ await tester.pumpAndSettle();
+ final picker = search(tester);
+ final row = picker.rows.singleWhere(
+ (row) => row.modelId == apiModelRowId('openrouter', 'z-ai/glm-5'),
+ );
+ picker.move(picker.rows.indexOf(row) - picker.cursor);
+ await tester.pump();
+ await key(tester, LogicalKeyboardKey.enter);
+ await tester.pumpAndSettle();
+ expect(app.moves, isEmpty);
+ expect(find.byType(SwarmSearchResults), findsNothing);
+ } finally {
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ map.dispose();
+ }
+ });
+
+ testWidgets('a harness on another computer cannot use this one’s APIs', (
+ tester,
+ ) async {
+ final app = await _apiFixture();
+ app.machineStates['other']!
+ ..connectionStatus = ConnectionStatus.connected
+ ..nodeOnline = true;
+ final map = MemoryKeymap();
+ try {
+ await configured.mount(tester, app, map);
+ await key(tester, LogicalKeyboardKey.keyI, cmd: true);
+ await tester.pumpAndSettle();
+ final picker = search(tester);
+ final row = picker
+ .models!
+ .entries[apiModelRowId('openrouter', 'z-ai/glm-5')]!
+ .destination;
+ expect(picker.canSelectModel(row), isTrue);
+ // The same list, opened for a harness on the other computer: shown, and says why not.
+ picker.setModelSelection('claude', app.inventory, machineId: 'other');
+ expect(picker.canSelectModel(row), isFalse);
+ expect(picker.modelUseReason(row), 'This computer only');
+ // And an engine the daemon cannot re-point is refused here too.
+ picker.setModelSelection(
+ 'cursor',
+ const GridModels(
+ gridName: 'home',
+ models: [],
+ localModelEngines: {'claude'},
+ ),
+ machineId: 'm',
+ );
+ expect(picker.canSelectModel(row), isFalse);
+ expect(picker.modelUseReason(row), 'Not available to this harness');
+ } finally {
+ await tester.pumpWidget(const SizedBox());
+ app.dispose();
+ map.dispose();
+ }
+ });
+
+ group('the words', () {
+ test('each thing wrong with an API URL has its own fix', () {
+ expect(apiUrlProblem(''), "Enter the API's URL.");
+ const full =
+ 'Enter the full URL, starting with https://, '
+ 'for example https://openrouter.ai/api/v1.';
+ expect(apiUrlProblem('fdfd'), full);
+ expect(apiUrlProblem('openrouter.ai/api/v1'), full);
+ expect(apiUrlProblem('file:///not-an-api'), full);
+ expect(
+ apiUrlProblem('https://me:[email protected]/v1'),
+ 'Take the username or password out of the URL. The key has its own field.',
+ );
+ expect(
+ apiUrlProblem('https://api.example.test/v1?key=1'),
+ 'Take the ? or # part off the end of the URL.',
+ );
+ expect(apiUrlProblem(' https://openrouter.ai/api/v1 '), isNull);
+ expect(apiUrlProblem('http://localhost:8080/v1'), isNull);
+ });
+
+ test('context windows read the way people say them', () {
+ expect(contextWindowLabel(65536), '64K');
+ expect(contextWindowLabel(131072), '128K');
+ expect(contextWindowLabel(200000), '200K');
+ expect(contextWindowLabel(1000000), '1M');
+ expect(contextWindowLabel(1048576), '1M');
+ expect(contextWindowLabel(2000000), '2M');
+ });
+
+ test('an API refusal says what the daemon said, in API terms', () {
+ expect(
+ retargetRefusalMessage(
+ 'API_UNAVAILABLE',
+ engineLabel: 'Claude Code',
+ api: true,
+ detail: 'OpenRouter did not accept the saved key.',
+ ),
+ 'OpenRouter did not accept the saved key.',
+ );
+ expect(
+ retargetRefusalMessage(
+ 'GRID_ENGINE_UNSUPPORTED',
+ engineLabel: 'Cursor',
+ api: true,
+ ),
+ 'Cursor can only run on its own login, not an API model.',
+ );
+ expect(
+ retargetRefusalMessage(
+ 'GRID_ENGINE_UNSUPPORTED',
+ engineLabel: 'Cursor',
+ ),
+ 'Cursor can only run on its own login, not a Local model.',
+ );
+ });
+
+ test('an agent is on an API model only at that API’s endpoint', () {
+ const onIt = Agent(
+ id: 'a',
+ name: 'a',
+ gridModel: 'z-ai/glm-5',
+ gridBaseUrl: 'https://openrouter.ai/api/v1',
+ );
+ expect(agentOnApiModel(onIt, openRouter, 'z-ai/glm-5'), isTrue);
+ expect(agentOnApiModel(onIt, openRouter, 'other'), isFalse);
+ const grid = Agent(
+ id: 'a',
+ name: 'a',
+ gridModel: 'z-ai/glm-5',
+ gridBaseUrl: 'https://grid.example.test/relay/v1',
+ );
+ expect(agentOnApiModel(grid, openRouter, 'z-ai/glm-5'), isFalse);
+ expect(agentOnApiModel(null, openRouter, 'z-ai/glm-5'), isFalse);
+ });
+ });
+}
diff --git a/desktop/test/resource_picker_test.dart b/desktop/test/resource_picker_test.dart
index e5ea79802..6370f8d47 100644
--- a/desktop/test/resource_picker_test.dart
+++ b/desktop/test/resource_picker_test.dart
@@ -1627,7 +1627,30 @@ void main() {
expect(find.text('https://api.deepseek.com'), findsWidgets);
expect(find.byType(Dialog), findsNothing);
final name = find.byKey(const ValueKey('api-form-input:name'));
+ bool focused(Finder input) =>
+ tester.widget<TextField>(input).focusNode!.hasFocus;
await tester.enterText(name, 'Draft API');
+ // Tab walks the form as any form does: its fields, then its buttons, then out to the list.
+ await key(tester, LogicalKeyboardKey.tab);
+ expect(focused(find.byKey(const ValueKey('api-form-input:url'))), isTrue);
+ await key(tester, LogicalKeyboardKey.tab);
+ expect(focused(find.byKey(const ValueKey('api-form-input:key'))), isTrue);
+ await key(tester, LogicalKeyboardKey.tab);
+ expect(
+ tester
+ .widget<Focus>(
+ find
+ .descendant(
+ of: find.byKey(const ValueKey('api-form:save')),
+ matching: find.byType(Focus),
+ )
+ .first,
+ )
+ .focusNode!
+ .hasFocus,
+ isTrue,
+ );
+ expect(controller.managing, isTrue);
await key(tester, LogicalKeyboardKey.tab);
expect(tester.widget<TextField>(field).focusNode!.hasFocus, isTrue);
expect(controller.managing, isFalse);
diff --git a/desktop/test/resource_preview_actions_test.dart b/desktop/test/resource_preview_actions_test.dart
index 944f12717..3604809ce 100644
--- a/desktop/test/resource_preview_actions_test.dart
+++ b/desktop/test/resource_preview_actions_test.dart
@@ -42,8 +42,9 @@ class _App extends ModelManagerTestApp {
@override
Future<Map<String, dynamic>> apiConnections(
String machineId,
- Map<String, dynamic> payload,
- ) async {
+ Map<String, dynamic> payload, {
+ Duration timeout = const Duration(seconds: 10),
+ }) async {
final action = payload['action'] as String;
apiCalls.add(action);
if (action == 'remove') {
diff --git a/docs/api-connections.md b/docs/api-connections.md
index b73eb150b..30dba710e 100644
--- a/docs/api-connections.md
+++ b/docs/api-connections.md
@@ -13,8 +13,9 @@ variable, authentication header, and optional prefix.
![API connections in Models](images/models-apis.png)
-Connections are available to every local harness's tools. They do not change
-the harness's selected model or subscription. Saving stores the connection;
+Connections are available to every local harness's tools. Saving one does not change
+the harness's selected model or subscription; to run a harness on an API's model, see
+[Running a harness on an API model](#running-a-harness-on-an-api-model). Saving stores the connection;
it does not call the provider, validate account credit, or make a paid request.
To edit a connection, select its pencil icon. Leave the key blank to keep the
@@ -55,6 +56,35 @@ Header-based JSON APIs work with `request`. Other protocols and authentication
schemes can use their own SDK/tool through `run`; Harness does not provide OAuth
sign-in or provider-specific polling and file-upload interfaces.
+## Running a harness on an API model
+
+An API that takes a Bearer key — OpenRouter, or a Custom API with an
+OpenAI-compatible `/models` list (DeepSeek, Groq, Together, …) — is also a place
+to run a harness. In the model picker (Cmd-I, or Cmd-P then `:`), its chat
+models are folded under the API's row: **Enter** on the row shows or hides
+them, and a search matches them without unfolding. Where the API describes its
+models, only those a coding agent can run are listed: they take tools, answer
+in text, and have at least a 64K context window. **Use** moves the focused
+harness onto the model, restarting its engine in the same pane and resuming the
+conversation, exactly like moving it onto a local model.
+
+The app sends only the API's ID and the model. The daemon on this computer reads
+the endpoint and key from its store and launches the engine the way the
+provider documents: Claude Code gets `ANTHROPIC_BASE_URL` (`https://openrouter.ai/api`)
+and `ANTHROPIC_AUTH_TOKEN`; Codex gets a `responses` provider at `…/api/v1`;
+OpenCode and Pi get a provider block that references the key through an
+environment variable. The key goes only into that engine's environment, never
+into argv or files. Each engine is told the model's context window, so it
+compacts before the API refuses a request. A restart, a restore, or a resume
+reads the key again, so a pasted replacement takes effect then. Once the API is
+removed, the harness cannot relaunch on it.
+
+Listing models is a free read of the API's `/models`, kept for ten minutes, or
+re-read at once after a key change or **Refresh models**. Only harnesses on this
+computer can use its APIs; fal.ai and Replicate stay tools-only. Claude Code
+is built for Anthropic models; others may not work fully through it
+([OpenRouter's note](https://openrouter.ai/docs/guides/guides/claude-code-integration)).
+
## Storage and scope
The local CLI stores keys in `api-connections/connections.json` inside its data
@@ -63,9 +93,10 @@ directory (`~/.harness/cli/data` by default), with owner-only directory/file per
atomic, and unreadable/corrupt storage is never silently replaced.
Management requests use the local daemon connection; remote requests are refused.
-Keys are not returned to the UI, included in connection lists, copied into project
-instructions, or exported into an engine's environment. An explicitly invoked
-tool receives the selected credential. Connections do not sync between machines.
+Keys are not returned to the UI, included in connection lists, or copied into project
+instructions. An explicitly invoked tool receives the selected credential, and so does
+the one engine a person moved onto that API's model — no other engine's environment
+gets a key. Connections do not sync between machines.
Preset defaults come from the providers' documentation:
[OpenRouter](https://openrouter.ai/docs/api/reference/authentication),
@@ -77,10 +108,10 @@ Preset defaults come from the providers' documentation:
```sh
cd cli
npm run typecheck
-npx vitest run src/lib/apiConnections.spec.ts src/lib/apiCommand.spec.ts src/lib/apiConnectionsRpc.spec.ts
+npx vitest run src/lib/apiConnections.spec.ts src/lib/apiCommand.spec.ts src/lib/apiConnectionsRpc.spec.ts src/lib/apiModels.spec.ts
cd ../desktop
-flutter test --coverage test/api_connections_test.dart test/models_panel_test.dart test/model_mark_test.dart test/model_manager_controller_test.dart
+flutter test --coverage test/api_connections_test.dart test/api_model_picker_test.dart test/models_panel_test.dart test/model_mark_test.dart test/model_manager_controller_test.dart
node tool/check_models_coverage.mjs
```