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.

37.6 KB
Raw Blame
import { modelsAssignments } from './modelsAssignments.js'
/**
 * Models: grid, how Harness runs local AI models with Codex, Claude Code and the other engines
 * (docs/design/2026-10-03-harnessd.md, "Models"). Grid access on first use, the managed grid's pin, the
 * model pictures an agent's frame carries, starting a sleeping grid while someone types to its agent,
 * where an agent on a grid model sends its inference, and what the apps ask about models: the picker's
 * list, an agent's Model/Effort choices, the Model Manager's local models and its grid commands.
 *
 * A service on the core boundary: it reads the core only through `CoreApi`, the core reaches it only
 * through `ports.models`, and the apps through the requests it answers. It runs in a process of its own
 * (services/modelsProcess.ts, docs/design/2026-10-06-core-boundary-next.md step 7): its downloads, its
 * installs and the `grid` children it runs cost that process, never the core's.
 */
import { join } from 'node:path'
import { baseNode } from '../harnessd/baseNode.js'
import type { CoreApi, CorePorts, ModelsPort, ServiceRequest, ServiceRequests } from '../core/api.js'
import { MODEL_MANAGER_ID } from '../dsh/builtinIds.js'
import { installedDsh } from '../dsh/installed.js'
import { ApiConnections, apiConnectionsRequest } from '../lib/apiConnections.js'
import { apiModelsRequest, apiTargetAnswer, refreshApiFor, rememberSavedApis } from '../lib/apiModels.js'
import { appEngineOps, scanAppModels } from '../lib/appModels.js'
import { linkClaudeProfile, listClaudeProfiles, profileId, offerAccount } from '../lib/claudeProfiles.js'
import { defaultCodexHome, linkCodexProfile, listCodexProfiles } from '../lib/codexProfiles.js'
import { createGridAccess, gridNamesLocal, reconcileGridAttach } from '../lib/gridAttach.js'
import { deriveHarnessGridName, resetGridDeriveMemo, signedInGridEmail } from '../lib/gridDerive.js'
import { ensureHarnessGrid } from '../lib/gridEnsure.js'
import { gridAvailable, gridExec, managedGridPath } from '../lib/gridExec.js'
import { GridFleetRpc, parseGridFleetRequest } from '../lib/gridFleetRpc.js'
import { handOffToGrid } from '../lib/gridHandoff.js'
import { ensureGridInstalled } from '../lib/gridInstall.js'
import { answerGridLaunch, type GridLaunchOverride } from '../lib/gridLaunch.js'
import { clearGridMcpUrlCache } from '../lib/gridMcpUrl.js'
import {
  forgetGridModels, gridAnnotation, gridInventory, gridServingNodes, keystrokePrewarm, listAllGridModels, listGridModels, observeMachineList, onGridModelsChanged,
  retargetPrewarm, warmGridModels, type GridSection,
} from '../lib/gridModels.js'
import { gridModelsPayload } from '../lib/gridModelsPayload.js'
import { resolveGridTarget } from '../lib/gridTarget.js'
import { LocalModels } from '../lib/localModels.js'
import { nvidiaComputeApps } from '../lib/gpuProcesses.js'
import type { NewAgentModel } from '../lib/newAgentModel.js'
import type { RuntimeModelOption } from '../lib/runtimeProfile.js'
import { parseRuntimeProfile } from '../lib/runtimeProfileWire.js'
import { ensureManagedGrid, startGridPinRecheck } from '../lib/runtimeInstall.js'
import type * as SwarmServicesEntry from '../superTabs/inServices.js'
import { internalOnThrow } from './requestErrors.js'

/** The requests models answers for the apps, declared in core/api.ts for the core to route. */
export { MODELS_REQUESTS } from '../core/api.js'

/** What grid's set-up for an act needs of models: have grid ready, and whether it is set up at all. */
interface GridSetUp {
  ensure: ModelsPort['ensure']
  /** Offline, for every list read: is there a `grid` here holding a sign-in? What decides whether the
   *  picker offers local and shared models or a Set up row. */
  setUp(): boolean
}

/** What models runs of the Swarm while it is on (superTabs/inServices.ts, docs/plans/2026-10-23-swarm-local-models.md):
 *  a Swarm's grid, the APIs and models shared with it, and the check that keeps them there. Absent while the Swarm is
 *  off (`HARNESS_SWARM`): none of it is loaded, no API is served to a Swarm, and its requests are answered unavailable. */
export type SwarmModels = Pick<typeof SwarmServicesEntry, 'syncSwarmGrid' | 'SwarmApiShares' | 'SwarmHeal' | 'liveModels' | 'SwarmOffers'>

export function startModels(core: CoreApi, ports: CorePorts, swarm?: SwarmModels): ServiceRequests {
  // A managed grid already here follows its pin on EVERY start of this service — the daemon's, and the
  // restart a self-update ends in — not only on `--repair`: the pin is expected to move, and a machine
  // installed last month has to notice. A machine with none gets none from a start: grid is an add-on,
  // installed the first time a grid feature is used (`ensure`, below). Not awaited, and asynchronous
  // throughout (`runtimeInstall.ts`): every grid call resolves the binary afresh (`gridBinaryPath`), so
  // whatever lands is picked up as it lands. It keeps following it while this runs: a pin moved after
  // the start reaches it within ten minutes rather than at the next restart (`startGridPinRecheck`). Windows has no
  // managed grid: there the grid installed already follows the pin (`lib/gridWindowsPin.ts`).
  const followGridPin = (): Promise<unknown> => managedGridPath() || (process.platform === 'win32' && gridAvailable())
    ? ensureManagedGrid((m) => console.log(`[grid-runtime] ${m}`))
    : Promise.resolve(null)
  void followGridPin()
  startGridPinRecheck({ ensure: followGridPin })

  // Grid is an add-on (`lib/gridAttach.ts`): nothing on this path installs `grid`, signs this machine in
  // to it or creates a grid. The first grid feature a person uses — the models picker's Set up, a local
  // model's Get or Use, an agent moved onto a grid model, the Model Manager — asks `ports.models.ensure`,
  // which does it then, with this machine's harness token (no second browser) and, only for what needs
  // one, the account's own grid. It used to run here on every start and every reconnect.
  const gridLog = (line: string): void => console.log(`[grid-attach] ${line}`)
  const gridAccess = createGridAccess({
    signedIn: () => signedInGridEmail() !== null,
    log: gridLog,
    attempt: ({ ownGrid, signedInThisRun }) => reconcileGridAttach({
      // The pinned managed runtime first; grid's own installer when there is none to follow.
      installCli: async () => {
        await ensureManagedGrid((m) => console.log(`[grid-runtime] ${m}`))
        if (gridAvailable()) return
        const installed = await ensureGridInstalled()
        if (installed.status !== 'present') gridLog(installed.message)
      },
      gridAvailable: () => gridAvailable(),
      // The backend mints and remembers the name, through the core, which holds the sign-in.
      mintName: () => core.account.mintGridName(),
      accessToken: () => core.account.accessToken(),
      signedInEmail: () => signedInGridEmail(),
      gridNames: () => gridNamesLocal(),
      handoff: (token) => handOffToGrid(token, { json: true }),
      ensure: (name) => ensureHarnessGrid(name),
      onName: (name) => {
        // Answer the picker with this account's grid at once, and drop the memos a stale or absent
        // sign-in may have filled — the model list, the derived name, and the web-tools URL.
        core.clients.gridNamed(name)
        forgetGridModels()
        resetGridDeriveMemo()
        clearGridMcpUrlCache()
      },
      log: gridLog,
    }, { ownGrid, signedInThisRun }),
  })
  const grid: GridSetUp = {
    ensure: (request) => gridAccess.ensure(request),
    setUp: () => gridAvailable() && signedInGridEmail() !== null,
  }

  /**
   * The account's private grid: the backend's word when it gave one, else what this machine can work out
   * for itself (`lib/gridDerive.ts`). A backend that predates `machine_meta.gridName` left every picker
   * empty while `grid models` listed the model fine; the derivation is the skill's own rule, so the
   * daemon and the agent it opens agree on which grid is "yours".
   */
  const privateGridName = async (): Promise<string | null> => (await core.account.privateGridName()) ?? await deriveHarnessGridName()

  // An agent's frame says what its grid's picture says (`grid.state`, and a `grid.note` when its model
  // will not answer). The picture changes on reads nobody waited for, so the frames of the agents whose
  // annotation moved are pushed again — only those, and only when it moved — and the windows are pushed
  // the list. In a process of its own the core reads the notes from what it is told
  // (services/modelsProcess.ts) and the core API there has no agents to push: the core does that itself.
  const announcedGrid = new Map<string, string>()
  onGridModelsChanged(() => {
    core.clients.gridModelsChanged()
    const onGrid = core.agents.advertised().filter((s) => s.grid)
    const present = new Set(onGrid.map((s) => s.agentId))
    for (const agentId of [...announcedGrid.keys()]) if (!present.has(agentId)) announcedGrid.delete(agentId)
    for (const s of onGrid) {
      const said = JSON.stringify(gridAnnotation(s.grid))
      if (announcedGrid.get(s.agentId) === said) continue
      announcedGrid.set(s.agentId, said)
      core.agents.sync(s)
    }
  })
  // The pictures saved before this start, back in memory with nothing read from any grid: an agent's
  // frame carries its grid's state and note, and a keystroke can start its grid, before any window asks
  // for the list (after a self-update, a phone may be the only one typing).
  void warmGridModels().catch(() => {})

  // The saved APIs, a file in the data folder (lib/apiConnections.ts), read afresh by every launch on one.
  const savedApis = new ApiConnections(core.dataDir)
  rememberSavedApis(savedApis)
  ports.models = {
    ensure: grid.ensure,
    annotation: (target) => gridAnnotation(target),
    // The keystroke prewarm (grid-reads-without-waking issue 03): typing into a pane whose agent runs on
    // a sleeping grid starts that grid while the person types.
    prewarm: (target) => { void keystrokePrewarm(target).catch(() => {}) },
    launchTarget: (selection) => SWARM_GRID.test(selection.grid) ? swarmLaunchTarget(grid, selection) : launchTarget(selection),
    moveTarget: (request) => moveTarget(grid, privateGridName, core, request),
    // 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). It decides for itself whether a wake is
    // worth it.
    moved: (launch) => { void retargetPrewarm(launch).catch(() => {}) },
    // The launch that points an engine at a grid or a saved API, built here for the core, which builds none
    // (docs/design/2026-10-08-launch-port.md): a relaunch's saved API with its endpoint and key as saved now.
    gridAssignments: modelsAssignments(savedApis),
    gridLaunch: async (request) => answerGridLaunch(request, refreshApiFor(savedApis)),
    apiTarget: (request) => apiTargetAnswer(savedApis, request.connectionId, request.model),
    privateGridName,
    // `grid_models_changed` to the windows: the same payload `grid_models_list` answers, built from the
    // pictures as they stand — no read is started to build it, so a push never causes one. Each window
    // gets it in the form it asked for (`gridModelsPayload`).
    lists: async () => {
      const gridName = await privateGridName()
      const grids = await listAllGridModels(gridName, { refresh: false })
      return { plain: gridModelsPayload(gridName, grids, false), rowState: gridModelsPayload(gridName, grids, true) }
    },
    // Which of the owner's other computers have been reading offline — a label on the models only they
    // serve on a sleeping grid, never a removal (grid-reads-without-waking issue 03).
    machines: (body, computerId) => observeMachineList(body, computerId),
    // The web-tools cache lives exactly as long as the sign-in.
    signedOut: () => clearGridMcpUrlCache(),
  }
  return modelsRequests(core, grid, privateGridName, swarm)
}

/**
 * Where a new agent on a grid model sends its inference, resolved on this machine. Refreshed at launch: a
 * model stopped after the picker opened must not silently fall back to a subscription or to the grid's
 * default router. Only the semantic choice goes into the creation receipt, never this rotating key.
 */
export async function launchTarget(selection: NewAgentModel): Promise<GridLaunchOverride | null> {
  forgetGridModels()
  const models = await listGridModels(selection.grid)
  if (!models.some((model) => model.id === selection.model)) return null
  return resolveGridTarget(selection.grid, selection.model)
}

/**
 * A Builder on a model served on a Swarm's grid (docs/plans/2026-10-23-swarm-local-models.md) may start on a machine that
 * never used grid: it signs in first (the Harness sign-in handed to `grid login --harness`), then pulls the account's grids,
 * since the Swarm's grid is new to this machine until a sync lists it.
 */
export async function swarmLaunchTarget(grid: GridSetUp, selection: NewAgentModel, sync: () => Promise<unknown> = () => gridExec(['--remote', 'sync'])): Promise<GridLaunchOverride | null> {
  if (await notReady(grid, false)) return null
  await sync()
  return launchTarget(selection)
}

/**
 * Grid set up for an act, or the sentence saying why it could not be: null when it is ready. The
 * picker's Set up, a Get, a Use and a move onto a grid model each ask it.
 */
async function notReady(grid: GridSetUp, ownGrid: boolean): Promise<string | null> {
  const ready = await grid.ensure({ ownGrid })
  if (ready.status !== 'converged' && ready.status !== 'signed-in') {
    return ready.detail || 'Grid could not be set up on this computer. Try again.'
  }
  if (ownGrid && ready.ownGrid && !['created', 'existed', 'adopted'].includes(ready.ownGrid)) {
    return ready.detail || 'Your grid could not be created. Try again.'
  }
  return null
}

/**
 * Where a running agent moved onto a grid model sends its inference (`agent_retarget`). The app names
 * the model, and the grid it was picked from when the picker says (a shared grid's section), the
 * account's own otherwise; the endpoint and the credential are resolved here, from this machine's own
 * signed-in `grid`, so neither ever crosses the relay. A move onto a grid model is a grid feature in
 * use: grid is signed in first, if it is not yet — and the account's own grid made sure of when that is
 * where the model is.
 */
async function moveTarget(
  grid: GridSetUp, privateGridName: () => Promise<string | null>, core: CoreApi, request: { gridName: string | null; model: string },
): Promise<{ target: GridLaunchOverride } | { detail: string }> {
  const named = request.gridName
  const unready = await notReady(grid, !named || named === await core.account.privateGridName())
  if (unready) return { detail: unready }
  const target = await resolveGridTarget(named ?? await privateGridName(), request.model)
  return target ? { target } : { detail: 'Could not read this machine\'s grid endpoint.' }
}

/** Sections one `grid_models_list` may ask to wake — a person presses one "Show models" at a time. */
const MAX_WAKES_PER_ASK = 8

/** The APIs this computer shares with Swarms: one set for the process, since each holds a live endpoint. */
function swarmApiShares(dataDir: string, swarm: SwarmModels): InstanceType<SwarmModels['SwarmApiShares']> {
  const saved = new ApiConnections(dataDir)
  const shares = new swarm.SwarmApiShares({ access: (id) => saved.modelAccess(id), exec: (args) => gridExec(args), stateFile: join(dataDir, 'swarm-api-shares.json') })
  void shares.restore().catch(() => {})
  return shares
}

/** A Swarm's grid name as the backend mints it (backend/src/superTabs/commands.ts `swarmGridName`). */
const SWARM_GRID = /^swarm-[0-9a-f]{12}$/

type LocalModelRequest = 'grid_fleet_models_list' | 'grid_fleet_model_download' | 'grid_fleet_model_start' | 'grid_fleet_model_stop'

/**
 * What the apps ask about models, on grid as this service holds it. Each request waits on grid, the
 * network or a model's process; the host replies when it is done and never holds the asking connection's
 * next request behind it (core/serviceHost.ts `route`), which is why the socket ran them detached when it
 * answered them itself. A failure is answered as the socket answered it, sentences included: the apps
 * show them.
 */
function modelsRequests(core: CoreApi, grid: GridSetUp, privateGridName: () => Promise<string | null>, swarm?: SwarmModels): ServiceRequests {
  // The Model Manager reads the grid it runs on through the same credential-less reader as every picker
  // (never `grid engines`, which carries the grid credential and so wakes a sleeping grid on every tick),
  // and a start or stop it finishes makes every list read again — pushed to the window when it changes.
  const localModels = new LocalModels({
    stateDir: join(core.dataDir, 'local-models'),
    machineName: () => core.account.machineName(),
    inventory: gridInventory,
    servingNodes: gridServingNodes,
    onChanged: () => { forgetGridModels(); core.clients.gridModelsChanged() },
    // Models Ollama, LM Studio and llama.cpp downloaded here, found by the Model Manager's own scan (the
    // bundled harness), so the picker and that harness agree on what is here and what starts it.
    appModels: () => scanAppModels({ node: baseNode(process.execPath), packageDir: installedDsh(MODEL_MANAGER_ID)?.realDir ?? null, env: process.env }),
    appEngines: appEngineOps(process.env),
    gpuProcesses: nvidiaComputeApps,
  })
  // A Swarm's grid, the APIs and models shared with it and the check that keeps them there, while the Swarm is on.
  const swarmSide = swarm ? swarmGridRequests(grid, core.dataDir, swarm, localModels) : null
  /** The grid listing currently out, shared by every `grid_models_list` for the same own grid that lands
   *  meanwhile. */
  let listing: { gridName: string | null; grids: Promise<GridSection[]> } | null = null

  // A daemon-owned operation survives panel closure and a lost reply. Its hardware, catalog and network
  // reads stay off the connection's ordered queue: the host answers when they are done.
  //
  // Grid is set up here only for an ACT: the picker's Set up (a list read carrying `setup`), a Get, a
  // Use. The list read the app polls while a picker is open never sets anything up — it says whether it
  // is needed (`gridSetupNeeded`). A Get needs a sign-in (the catalog is grid's); a Use serves on the
  // account's own grid, and so does the Set up that offers it.
  const localModel = (type: LocalModelRequest): ServiceRequest => async (payload) => {
    try {
      const list = type === 'grid_fleet_models_list'
      const setup = list ? payload.setup === true : type !== 'grid_fleet_model_stop'
      // A start or stop for a Swarm runs on the Swarm's grid, which its owner's computer made: it needs grid signed in,
      // not the account's own grid. Asked to make that too, a Run for Swarm failed on an account at its plan's network
      // limit ("Free plan allows 5 networks") while the Swarm's grid stood ready (2026-10-26).
      const forSwarm = !list && type !== 'grid_fleet_model_download' && typeof payload.grid === 'string' && SWARM_GRID.test(payload.grid)
      const unready = setup ? await notReady(grid, type !== 'grid_fleet_model_download' && !forSwarm) : null
      const gridName = await privateGridName()
      if (list) {
        const snapshot = await localModels.list(gridName, payload.refresh === true || setup)
        const needed = !grid.setUp()
        if (setup && !unready) core.clients.gridModelsChanged()
        return { ...snapshot, ...(needed ? { gridSetupNeeded: true } : {}), ...(unready ? { gridSetupError: unready } : {}) }
      }
      if (unready) return { error: unready }
      // A start or stop for the community grid of this computer's OS (`osGrid`): run there, for its members. Or for a
      // Swarm's own grid (docs/plans/2026-10-23-swarm-local-models.md), named by the Swarm and checked by grid itself:
      // only its members may serve there.
      const community = payload.community === true && type !== 'grid_fleet_model_download'
      const swarm = type !== 'grid_fleet_model_download' && typeof payload.grid === 'string' && SWARM_GRID.test(payload.grid) ? payload.grid : null
      const target = swarm ?? (community ? await localModels.communityGrid() : gridName)
      if (community && !target) return { error: 'This computer is in no community grid.' }
      return { ...await localModels.act(target, payload.modelId, type === 'grid_fleet_model_download' ? 'download' : type === 'grid_fleet_model_start' ? 'start' : 'stop') }
    } catch {
      return { error: 'Models are unavailable. Try again.' }
    }
  }

  return {
    grid_models_list: async (payload) => {
      // Every grid this computer is signed into, in sections, the account's own first. `gridName`
      // and `models` keep naming the own grid alone, for an app that predates `grids`.
      //
      // Never held in line: it waits on a grid reconcile (up to 6s), then a `grid ls` spawn and — for a
      // grid this daemon has never read — up to 4s of its first read (`gridModels.ts`); every other grid
      // answers from its picture. The desktop asks for it in the same breath as `terminal_capabilities`
      // and `agents_list` on every connect, and awaited in line it held both behind it — with no
      // network, past the app's 10s request timeout, on which the app forces a reconnect and asks all
      // three again. Measured 2026-09-18, wifi off, daemon restarted: every local RPC timed out for as
      // long as the backend stayed unreachable; the terminal on the SAME computer sat on "offline" until
      // the wifi came back. Request ids make the reply safe to land out of order.
      //
      // One computation at a time: a second ask that lands while the first is still out (the app re-asks
      // on every connect) would spawn another `grid ls` for the same answer. Later askers share the one
      // in flight; each grid's reads are single-flight in `gridModels.ts`.
      //
      // `rowState: true` — a window that draws row state gets offline labels as `unavailable` (and the
      // socket pushes it the list's changes in that form); `wake: [name]` — a person pressed "Show
      // models" / "Wake now", and the answer (with those sections "waking") comes back at once while the
      // wake runs behind it (grid-reads-without-waking issue 03). A wake never joins a listing already
      // out: that one was built before the wake began, and would not say "waking".
      const rowState = payload.rowState === true
      const wake = Array.isArray(payload.wake)
        ? payload.wake.filter((name): name is string => typeof name === 'string' && !!name.trim()).map((name) => name.trim()).slice(0, MAX_WAKES_PER_ASK)
        : []
      try {
        const gridName = await privateGridName()
        const inFlight = listing
        const grids = wake.length
          ? listAllGridModels(gridName, { wake })
          : inFlight && inFlight.gridName === gridName
            ? inFlight.grids
            : (listing = {
                gridName,
                grids: listAllGridModels(gridName).finally(() => {
                  if (listing?.gridName === gridName) listing = null
                }),
              }).grids
        return gridModelsPayload(gridName, await grids, rowState)
      } catch {
        return { error: 'GRID_MODELS_FAILED' }
      }
    },

    // Runtime Model/Effort: the choices an agent's engine offers, or every live agent's.
    models_list: async (payload) => {
      const sessionId = typeof payload.agentId === 'string' && payload.agentId ? payload.agentId : undefined
      try {
        const models = await core.agents.runtimeModels(sessionId)
        return {
          // The device derives labels from the opaque runtime-v1 id. Omitting the duplicate
          // displayName keeps the encrypted picker response below its 16 KiB decrypt cap.
          models: payload.compact === true
            ? compactRuntimePickerModels(models, sessionId, payload.pickerMode, payload.selectedModel)
            : models,
        }
      } catch (error) {
        // Logged and answered as the socket did while this was a case of its own.
        console.error('[backend] dispatch models_list failed:', error)
        return { error: 'INTERNAL' }
      }
    },

    grid_fleet_models_list: localModel('grid_fleet_models_list'),
    grid_fleet_model_download: localModel('grid_fleet_model_download'),
    grid_fleet_model_start: localModel('grid_fleet_model_start'),
    grid_fleet_model_stop: localModel('grid_fleet_model_stop'),
    ...gridCommands(),
    ...(swarmSide?.requests ?? SWARM_OFF_REQUESTS),
    ...launchTargetRequests(core, async (id) => { await swarmSide?.shares.stopConnection(id) }),
  }
}

/** The Swarm's requests to models (core/api.ts `MODELS_REQUESTS`), answered while it is off as its own service's are. */
const SWARM_MODELS_REQUESTS = ['grid_swarm_sync', 'grid_swarm_api_share', 'grid_swarm_api_shares', 'grid_swarm_offer', 'grid_swarm_offers', 'grid_swarm_heal'] as const
const SWARM_OFF_REQUESTS: ServiceRequests = Object.fromEntries(SWARM_MODELS_REQUESTS.map((type) =>
  [type, () => ({ error: 'SERVICE_UNAVAILABLE', service: 'superTabs', retryable: false })]))

/**
 * What models answers a Swarm while it is on: its own grid, kept in step with its people (lib/swarmGrid.ts), a saved API
 * or a model shared with it (lib/swarmApiShares.ts, lib/swarmOffers.ts), and what this computer serves there, checked
 * against what the grid lists (lib/swarmHeal.ts). One set of shared APIs for the process, since each holds a live
 * endpoint; its `stopConnection` takes a deleted API off every Swarm first.
 */
function swarmGridRequests(grid: GridSetUp, dataDir: string, swarm: SwarmModels, localModels: Pick<LocalModels, 'servedApps' | 'rejoinApp'>) {
  const shares = swarmApiShares(dataDir, swarm)
  const offers = new swarm.SwarmOffers(join(dataDir, 'swarm-offers.json'))
  const heal = new swarm.SwarmHeal({
    live: async (name) => {
      const answer = await gridExec(['--remote', 'models', name, '--json'])
      return answer.code === 'OK' ? swarm.liveModels(answer.stdout) : null
    },
    shares: { list: (name) => shares.list(name), rejoin: (name, connectionId, model) => shares.rejoin(name, connectionId, model) },
    apps: { served: (name) => localModels.servedApps(name), rejoin: (name) => localModels.rejoinApp(name) },
  })
  const requests: ServiceRequests = {
    // What this computer serves on a Swarm's grid that the grid really lists, joined again when it lost them: read by
    // every machine reading (superTabs/machines.ts).
    grid_swarm_heal: async (payload) => {
      if (typeof payload.grid !== 'string' || !SWARM_GRID.test(payload.grid)) return { error: 'INVALID_REQUEST' }
      return { ...await heal.check(payload.grid) }
    },
    // A Swarm's own grid, created and kept in step with its people by the owner's computer (lib/swarmGrid.ts).
    grid_swarm_sync: async (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      const members = Array.isArray(payload.members) ? payload.members.filter((m): m is string => typeof m === 'string' && /^[^\s@]+@[^\s@]+$/.test(m)) : null
      if (typeof payload.grid !== 'string' || !SWARM_GRID.test(payload.grid) || !members || members.length > 200) return { error: 'INVALID_REQUEST' }
      // Signed in first: the owner may never have used grid on this computer before turning the add-on on.
      const unready = await notReady(grid, false)
      if (unready) return { ready: false, error: unready, added: [], removed: [] }
      return { ...await swarm.syncSwarmGrid(payload.grid, members) }
    },
    // A saved API shared with a Swarm's grid, on this computer's key (lib/swarmApiShares.ts). This computer's own person
    // alone: the key is theirs, and so are the credits every Builder in the Swarm then spends.
    grid_swarm_api_share: async (payload, asker) => {
      if (!asker.local || !asker.owner) return { error: 'OWNER_REQUIRED' }
      const { grid: name, connectionId, model, action } = payload
      if (typeof name !== 'string' || !SWARM_GRID.test(name) || typeof connectionId !== 'string' || typeof model !== 'string'
        || !model || model.length > 200 || (action !== 'start' && action !== 'stop')) return { error: 'INVALID_REQUEST' }
      if (action === 'stop') return { ...await shares.stop(name, connectionId, model) }
      const unready = await notReady(grid, false)
      if (unready) return { error: unready }
      return { ...await shares.share(name, connectionId, model) }
    },
    grid_swarm_api_shares: (payload) => ({
      shares: shares.list(typeof payload.grid === 'string' ? payload.grid : undefined),
    }),
    // A model shared with this computer's person, offered to a Swarm or no longer (lib/swarmOffers.ts). Their choice
    // alone: Builders the Swarm starts here then run on someone else's model through their access.
    grid_swarm_offer: (payload, asker) => {
      if (!asker.local || !asker.owner) return { error: 'OWNER_REQUIRED' }
      const { grid: name, sharedGrid, model, action } = payload
      const text = (v: unknown) => typeof v === 'string' && v.length > 0 && v.length <= 200
      if (typeof name !== 'string' || !SWARM_GRID.test(name) || !text(sharedGrid) || !text(model) || (action !== 'start' && action !== 'stop')) {
        return { error: 'INVALID_REQUEST' }
      }
      try {
        return { offers: offers.set({ grid: name, sharedGrid: sharedGrid as string, model: model as string }, action === 'start') }
      } catch {
        return { error: 'The offer could not be saved on this computer.' }
      }
    },
    grid_swarm_offers: (payload) => ({
      offers: offers.list(typeof payload.grid === 'string' ? payload.grid : undefined),
    }),
  }
  return { requests, shares }
}

/**
 * The Model Manager's grid commands: grid's own argv, run here (`lib/gridFleetRpc.ts`). A command is a job
 * of the connection that started it, keyed by that connection and the id it was asked under (`Asker`),
 * and a cancel stops only that connection's own. Run against grid AS IT STANDS — never set up first: a
 * Grid harness session issues these on its own the moment its viewer comes up (every open one, on every
 * daemon start), so setting grid up here signed a machine in to grid right after a Harness-only sign-in,
 * with nobody asking. Grid is set up by the picker's Set up, by making or opening a Model Manager, and by
 * that harness's own `harness grid setup`; until then grid answers these in its own words. Their
 * handshake, `grid_fleet_capabilities`, is the socket's (core/api.ts `MODELS_REQUESTS`).
 */
function gridCommands(): ServiceRequests {
  const fleet = new GridFleetRpc()
  return {
    // Pulls and builds can take minutes; the host answers when it is done and holds nothing else for it.
    grid_fleet_run: async (payload, asker) => {
      const request = parseGridFleetRequest(payload)
      if (!request || !asker.connection || !asker.requestId) return { error: 'INVALID_GRID_COMMAND' }
      try {
        return { ...await fleet.run(asker.connection, asker.requestId, request) }
      } catch {
        return { ok: false, code: 1, error: 'Grid command failed unexpectedly.' }
      }
    },
    grid_fleet_cancel: (payload, asker) => ({
      cancelled: !!asker.connection && typeof payload.commandId === 'string' && fleet.cancel(asker.connection, payload.commandId),
    }),
  }
}

/**
 * What an agent can be launched on besides a model: the saved APIs and the Codex profiles, moved out of the
 * socket's switch (docs/design/2026-10-06-core-boundary-next.md, step 4). Its own function so the socket's
 * specs can serve it alone behind the gates.
 */
export function launchTargetRequests(core: CoreApi, onRemove: (connectionId: string) => Promise<void>): ServiceRequests {
  // The saved APIs, a file in the data folder (lib/apiConnections.ts): read afresh on every request.
  const apiConnections = new ApiConnections(core.dataDir)
  return {
    // The APIs saved on this machine (lib/apiConnections.ts): list, save and remove one, and one API's
    // models. Their keys stay here, so only the owner manages them: this machine's app, or its paired one.
    api_connections: internalOnThrow('api_connections', async (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      if (payload.action === 'models') return apiModelsRequest(apiConnections, payload)
      // A deleted API comes off every Swarm it is shared with first: its share holds the key and would go on serving.
      if (payload.action === 'remove' && typeof payload.id === 'string') await onRemove(payload.id)
      const reply = apiConnectionsRequest(apiConnections, payload)
      if (payload.action === 'save') rememberSavedApis(apiConnections)
      return reply
    }),

    // Which CODEX_HOME folders THIS machine can offer — answered here, on the machine in question, for
    // the same reason `engines_probe` is: a Codex profile is a folder on disk, and a folder on a Mac means
    // nothing on the Docker rig it was asked about instead.
    codex_profiles_list: internalOnThrow('codex_profiles_list', (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      const observed = Array.isArray(payload.observedPaths)
        ? payload.observedPaths.filter((p): p is string => typeof p === 'string')
        : []
      try {
        const machineId = core.daemon.machineId(), defaultHome = defaultCodexHome()
        // Each account's one id (the default's is shared with the machine report); the default is marked, as Claude's is.
        return { profiles: listCodexProfiles(observed).map((p) => p.path === defaultHome
          ? { ...p, id: profileId(machineId, 'codex', 'default'), default: true } : { ...p, id: profileId(machineId, 'codex', p.path) }) }
      } catch {
        return { error: 'CODEX_PROFILES_FAILED' }
      }
    }),

    codex_profile_link: internalOnThrow('codex_profile_link', (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      const path = typeof payload.path === 'string' ? payload.path : ''
      const result = linkCodexProfile(path)
      if ('error' in result) return { error: result.error }
      return { profile: result }
    }),

    // The Claude counterpart: CLAUDE_CONFIG_DIR folders, with the ids and labels the Swarm switch picks from.
    // Paths and account names are the owner's alone, so a guest gets nothing.
    claude_profiles_list: internalOnThrow('claude_profiles_list', (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      const observed = Array.isArray(payload.observedPaths)
        ? payload.observedPaths.filter((p): p is string => typeof p === 'string')
        : []
      try {
        return { profiles: listClaudeProfiles(observed, { machineId: core.daemon.machineId() }) }
      } catch {
        return { error: 'CLAUDE_PROFILES_FAILED' }
      }
    }),

    claude_profile_link: internalOnThrow('claude_profile_link', (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      return linkClaudeProfile(typeof payload.path === 'string' ? payload.path : '', core.daemon.machineId())
    }),

    // The owner's own choice to offer an account to the Swarm, or to take it back (lib/accountOffers.ts). Like the requests above it
    // is theirs alone, and not sealed for the relay: Desktop asks this computer's own daemon.
    swarm_account_offer: internalOnThrow('swarm_account_offer', (payload, asker) => {
      if (!asker.owner) return { error: 'OWNER_REQUIRED' }
      if (typeof payload.offered !== 'boolean') return { error: 'INVALID_OFFER' }
      return offerAccount(String(payload.engine), typeof payload.path === 'string' ? payload.path : '', payload.offered)
    }),
  }
}

/**
 * How many models the DEVICE picker may receive. It has room for 48 (`models[48]` in ui_habitat.c) and
 * is handed half of that, so the list it draws is never one it was not built for; the web picker is
 * unbounded and still gets everything.
 */
const DEVICE_PICKER_MAX_MODELS = 24

export function compactRuntimePickerModels(
  models: RuntimeModelOption[],
  sessionId: string | undefined,
  pickerMode: unknown,
  selectedModel: unknown,
): Array<{ id: string }> {
  const compact = models.map(({ id }) => ({ id }))
  if ((pickerMode !== 'model' && pickerMode !== 'effort') || !sessionId) return compact

  const profiles = models.flatMap((item) => {
    const profile = parseRuntimeProfile(item.id)
    return profile?.sessionId === sessionId ? [{ item, profile }] : []
  })
  const selected = parseRuntimeProfile(selectedModel)
  const current = selected?.sessionId === sessionId ? selected : null

  if (pickerMode === 'effort') {
    if (!current) return []
    const seen = new Set<string>()
    return profiles.flatMap(({ item, profile }) => {
      if (profile.model !== current.model || profile.effort === 'auto' || seen.has(profile.effort)) return []
      seen.add(profile.effort)
      return [{ id: item.id }]
    })
  }

  const byModel = new Map<string, typeof profiles>()
  for (const entry of profiles) {
    const group = byModel.get(entry.profile.model) ?? []
    group.push(entry)
    byModel.set(entry.profile.model, group)
  }
  const rows = [...byModel.values()].map((group) => {
    const target = group.find(({ profile }) => current && profile.effort === current.effort)
      ?? group.find(({ profile }) => profile.effort === 'auto')
      ?? group[0]
    return { id: target.item.id, model: target.profile.model }
  })
  // Top N only. The picker is a scroll wheel on a 1.9" round screen, and a 49-row one was enough to stall
  // the device's the device UI task into a task-watchdog reset; devin alone publishes 72
  // models. The catalog arrives in the engine's own order — its curated/most-used first — so "top" is that
  // order, with the model the agent is RUNNING pinned in front so the list can never hide it.
  const ordered = current
    ? [...rows].sort((a, b) => Number(b.model === current.model) - Number(a.model === current.model))
    : rows
  return ordered.slice(0, DEVICE_PICKER_MAX_MODELS).map(({ id }) => ({ id }))
}