Skip to content

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

9.0 KB
Raw Blame
/**
 * 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 './codingContext.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 }
}

/**
 * `refreshApiLaunch` as the models service's grid launch asks it (lib/gridLaunch.ts `answerGridLaunch`): the
 * launch as saved now and the endpoint it read, or why the API cannot be used, in the words a relaunch always gave.
 */
export function refreshApiFor(store: ApiConnections) {
  return (launch: GridLaunchOverride): { override: GridLaunchOverride; apiBase?: string } | { error: string; detail: string } => {
    if (!isApiLaunch(launch)) return { override: launch }
    try {
      const override = refreshApiLaunch(store, launch)
      return { override, apiBase: override.baseUrl }
    } catch (error) {
      return { error: 'API_UNAVAILABLE', detail: error instanceof ApiConnectionError ? error.message : `${launch.networkName} could not be read from saved APIs.` }
    }
  }
}

/** `resolveApiTarget` as the core asks it (`ModelsPort.apiTarget`): the launch and the endpoint it read, or the
 *  sentence a person reads, as the socket always answered it. */
export async function apiTargetAnswer(store: ApiConnections, connectionId: string, model: string, deps: ApiModelDeps = {}): Promise<{ target: GridLaunchOverride; apiBase: string } | { detail: string }> {
  try {
    const target = await resolveApiTarget(store, connectionId, model, deps)
    return { target, apiBase: target.baseUrl }
  } catch (error) {
    return { detail: error instanceof ApiConnectionError ? error.message : 'This API could not be used. Try again.' }
  }
}

export { rememberSavedApis } from './gridAssignment.js'

/** `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.' }
  }
}