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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat: run a harness on a saved API's models
bitcoinbuilder2e0fee3bab4a
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.tsindex 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.tsindex 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) returntry { 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.tsindex 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: stringprivate 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 truetry {// 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` fordiff --git a/cli/src/lib/gridLaunch.ts b/cli/src/lib/gridLaunch.tsindex 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 backdiff --git a/desktop/design/terminal-dialogs.md b/desktop/design/terminal-dialogs.mdindex 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 theundownloaded catalog collapsed behind **[ Get models ]**; Enter expands it inplace 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 harnessopens it. Arrow keys walk controls while the right pane owns focus; they mustnot change the resource behind them. Left/Right retain normal cursor movementin 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 whilepreserving the query and selection. Hints use the live keymap. Only the activepane shows a selection highlight.Typing selects the first match and replaces the hints with its preview. Arrowsdiff --git a/desktop/lib/core/models.dart b/desktop/lib/core/models.dartindex 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.dartindex 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.dartindex 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.dartindex 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.dartindex 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.dartindex 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.dartindex 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.dartindex 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.dartindex 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.dartindex 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.dartindex 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.dartindex 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 {@overrideFuture<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.dartnew file mode 100644index 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.dartindex 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.dartindex 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 {@overrideFuture<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.mdindex b73eb150b..30dba710e 100644--- a/docs/api-connections.md+++ b/docs/api-connections.md@@ -13,8 +13,9 @@ variable, authentication header, and optional prefix.-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 authenticationschemes can use their own SDK/tool through `run`; Harness does not provide OAuthsign-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 scopeThe 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 peratomic, 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:```shcd clinpm 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.tscd ../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.dartnode tool/check_models_coverage.mjs```