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.

18.9 KB
Raw Blame
/**
 * A person switches their Buddy between their own subscription and a model the Swarm's grid serves, and back (task #2354,
 * docs/plans/2026-11-03-buddy-model-switch-design.md). The person asks here; the Buddy's machine carries it out through its
 * own daemon's model switch (cli superTabs/buddyModel.ts) and reports; the outcome is one line in the person's Buddy chat.
 *
 * The models offered are exactly those a routed start may run on (machines.ts servedLocalModels): on this Swarm's grid, in a
 * fresh reading of a machine in its Machines list. Never a model of another grid a member reads, which only that member's
 * machine can reach.
 *
 * Whoever serves the model is told whose Buddy runs on it, and their limits hold (AGENTS.md, contributed capacity): a model that
 * hits a limit, keeps failing or is no longer served sends the Buddy back to its owner's subscription.
 */
import { buddyChatOf, buddyChatsOf, defaultBuddy, defaultBuddyChat, isSwarmBuddy, swarmBuddyChatId } from './buddies.js'
import { mainBuddyOf, sessionAgentsOf } from './buddySessions.js'
import { machineOffline, servedLocalModels } from './machines.js'
import { fail, person, type Actor, type Agent, type SuperTabState } from './model.js'
import { usernameOf } from './usernames.js'

/** What a host that switches a Buddy's model says it does (cli superTabs/machines.ts CAPABILITIES). */
export const BUDDY_MODEL_CAPABILITY = 'buddyModel'
/** A switch the Buddy's machine never reported within this long is dropped: the Buddy stays where it was. */
export const BUDDY_MODEL_LEASE_MS = 10 * 60_000
/** How long nobody serves the model a Buddy runs on before it is sent home: a machine's reading may lapse for a moment. */
export const BUDDY_MODEL_GONE_MS = 2 * 60_000
/** How many times a thread session may stay on a shared model when sent home before its owner is told to end it (#3810). */
export const HOME_TRIES = 3

/** One line the switch writes: in a Buddy chat, naming the machines a Buddy reading it must not learn (store.ts
 *  withoutMachineNames). */
export interface ModelLine { conversationId: string; text: string; machines: string[] }

const personName = (state: SuperTabState, id: string) =>
  usernameOf(state, id) ?? state.people.find(p => p.id === id)?.email ?? 'A member'

/** Who serves [gridModel] now on the Swarm's grid: each serving machine's name and its member, and whether it is an API. */
function servers(state: SuperTabState, gridModel: string, now: number) {
  return servedLocalModels(state, now).filter(l => l.model === gridModel).map(l => {
    const pool = state.machines!.find(m => m.machineId === l.machineId)!
    // As Desktop names it (identity.dart superTabMachineName), so the picker and the chat line agree.
    return { reading: l, machine: (pool.name ?? 'a machine').replace(/(.)\.local$/i, '$1'), personId: pool.contributorId, api: l.kind === 'api' }
  })
}

/** A model as the person was shown it: its name, who serves it (machines by name, a saved API by its member), and the smallest
 *  window a serving machine reported, so the conversation is measured against the tightest one the grid may pick. */
function served(state: SuperTabState, gridModel: string, now: number) {
  const found = servers(state, gridModel, now)
  if (!found.length) return null
  const servedBy = [...new Set(found.map(s => s.api ? `${personName(state, s.personId)}'s saved API` : s.machine))]
  const machines = [...new Set(found.filter(s => !s.api).map(s => s.machine))]
  const windows = found.flatMap(s => typeof s.reading.contextWindow === 'number' ? [s.reading.contextWindow] : [])
  return { name: found.find(s => s.reading.name)?.reading.name ?? gridModel, servedBy, machines,
    ...(windows.length ? { contextWindow: Math.min(...windows) } : {}) }
}

/** The person's own running Buddy for the Swarm: never a thread session, never someone else's. With several (task #3818), the
 *  one whose chat [conversationId] names, one of theirs, else their default. */
function ownBuddy(state: SuperTabState, actor: Actor, conversationId?: string): Agent {
  if (actor.kind !== 'person') fail('BUDDY_PERSON', 'A person switches their own Buddy.', 403)
  const me = person(state, actor.userId)
  const chat = conversationId ? buddyChatsOf(state, me).find(c => c.id === conversationId) ?? fail('NOT_FOUND', 'This conversation is unavailable.', 404) : undefined
  const buddy = chat ? mainBuddyOf(state, chat) : defaultBuddy(state, me.id) ?? mainBuddy(state, me.id, me.generation)
  return buddy ?? fail('NO_BUDDY', 'You have no Buddy running.', 404)
}
const mainBuddy = (state: SuperTabState, personId: string, generation: string) =>
  state.agents.find(a => isSwarmBuddy(a) && a.buddyOf!.personId === personId && a.buddyOf!.generation === generation && !a.buddySession)

/** Whether the Buddy's machine can carry a switch out now: in the Swarm's Machines list, reporting, and able to. */
function switchable(state: SuperTabState, buddy: Agent, now: number): { ok: true } | { ok: false; code: string; message: string } {
  const pool = state.machines?.find(m => m.machineId === buddy.machineId)
  const name = pool?.name ?? 'your computer'
  // A Buddy-only machine never joins the Swarm's grid (read/hostRows.ts), so nothing shared there can reach it.
  if (!pool || pool.buddyOnly) return { ok: false, code: 'BUDDY_MODEL_MACHINE', message: `Add ${name} to the Swarm's Machines to use shared models.` }
  if (machineOffline(pool, now)) return { ok: false, code: 'MACHINE_OFFLINE', message: `Wait for a fresh reading from ${name}.` }
  if (!pool.observation!.capabilities?.includes(BUDDY_MODEL_CAPABILITY)) return { ok: false, code: 'HOST_OUTDATED', message: `Update Harness on ${name} to switch your Buddy's model.` }
  return { ok: true }
}

export function askBuddyModel(state: SuperTabState, actor: Actor, gridModel: string | null, requestId: string, now: number, conversationId?: string): void {
  const buddy = ownBuddy(state, actor, conversationId)
  const can = switchable(state, buddy, now)
  if (!can.ok) fail(can.code, can.message, 409)
  if (buddy.modelRequest || buddy.switchRequest || buddy.switchLanded) fail('BUDDY_SWITCHING', 'Your Buddy is already switching.', 409)
  const shown = gridModel === null ? {} : served(state, gridModel, now)
  if (!shown) fail('BUDDY_MODEL_UNAVAILABLE', 'Nobody in the Swarm serves that model now.', 409)
  // The grid its machine moves it onto (agent_retarget's gridName): the Swarm's own, the one the models were checked on.
  buddy.modelRequest = { id: requestId, gridModel, ...(gridModel === null ? {} : { gridName: state.localModels!.grid }), ...shown,
    requestedBy: buddy.buddyOf!.personId, at: new Date(now).toISOString() }
}

/** Sends [buddy]'s main Buddy home to its owner's subscription by itself, unless it is on it, already switching, or its machine
 *  cannot carry it out (then its own lines say so: its model fails in its terminal, and the person can switch it). */
export function sendBuddyHome(state: SuperTabState, from: Agent, reason: 'limit' | 'failing' | 'gone', requestId: string, now: number): void {
  if (!from.buddyOf) return
  // The main Buddy of [from]'s own chat (task #3818: a person may have several), else theirs as before.
  const chat = buddyChatOf(state, from)
  const buddy = (chat && mainBuddyOf(state, chat)) ?? mainBuddy(state, from.buddyOf.personId, from.buddyOf.generation)
  if (!buddy?.gridModel || buddy.modelRequest || buddy.switchRequest || buddy.switchLanded || !switchable(state, buddy, now).ok) return
  buddy.modelRequest = { id: requestId, gridModel: null, name: current(state, buddy, now), reason,
    requestedBy: buddy.buddyOf!.personId, at: new Date(now).toISOString() }
}

const windowWords = (tokens: number) => `${Math.round(tokens / 1024)}K`
const clean = (text: string) => text.replace(/[\x00-\x1f\x7f]+/g, ' ').replace(/[.\s]+$/, '').trim()
const HOME_WORDS = { limit: 'hit a limit', failing: 'keeps failing' } as const

/** What the Buddy is on now, as its owner reads it. */
function current(state: SuperTabState, buddy: Agent, now: number): string {
  if (!buddy.gridModel) return 'your subscription'
  return served(state, buddy.gridModel, now)?.name ?? buddy.gridModelName ?? buddy.gridModel
}

/** The machines any line about [request] must keep from a Buddy reading it (store.ts withoutMachineNames): those the owner was
 *  shown when asking, which a host's refusal repeats, and those serving the request's model or the Buddy's own now. Worked out
 *  from the request too, since a machine may stop serving between the ask and the answer (security review 1 of #2787). */
function hiddenMachines(state: SuperTabState, buddy: Agent, request: NonNullable<Agent['modelRequest']>, now: number): string[] {
  const serving = [request.gridModel, buddy.gridModel].flatMap(model => model ? servers(state, model, now).filter(s => !s.api).map(s => s.machine) : [])
  return [...new Set([...(request.machines ?? []), ...serving])]
}

/** The Buddy's machine reports the switch it carried out: the Buddy is on the model, or stays where it was. The first line is
 *  the owner's; then one for each other member who serves the model it landed on. */
export function buddyModelResult(state: SuperTabState, actor: Actor,
  command: { agentId: string; requestId: string; ok: boolean; fresh?: boolean; error?: string; stayed?: string[] }, now: number): ModelLine[] {
  const buddy = state.agents.find(a => a.id === command.agentId)
  if (!buddy || actor.kind !== 'agent' || actor.agentId !== buddy.id || !isSwarmBuddy(buddy)) fail('BUDDY_FORBIDDEN', 'Only the Buddy\'s machine reports its switch.', 403)
  const request = buddy.modelRequest
  if (!request || request.id !== command.requestId) fail('STALE_SWITCH', 'This is not the switch your Buddy was asked for.', 409)
  const hidden = hiddenMachines(state, buddy, request, now)
  delete buddy.modelRequest
  const owner = buddy.buddyOf!
  // Its own chat (task #3818), where its owner talks with it.
  const chat = buddyChatOf(state, buddy)
  const conversationId = chat?.id ?? swarmBuddyChatId({ id: owner.personId, generation: owner.generation })
  const mine = (text: string): ModelLine[] => [{ conversationId, text, machines: hidden }]
  if (!command.ok) {
    return mine(`Couldn't switch your Buddy: ${clean(command.error ?? '') || 'it failed'}. It is still on ${current(state, buddy, now)}.`)
  }
  delete buddy.gridModelUnservedSince
  // Its machine moved its thread sessions with it (cli superTabs/buddyModel.ts): what they run on is recorded the same way, so
  // costs and the serving member's "Used by" read it right. One it could not move (`stayed`) runs where it was, and is
  // recorded there (task #3810); left on a shared model by a move home, it is owed one, which the liveness sweep asks for.
  const stayedIds = new Set(command.stayed ?? []), words = clean(command.error ?? '')
  const sessions = chat ? sessionAgentsOf(state, chat) : state.agents.filter(a => a.buddySession && a.buddyOf?.personId === owner.personId && a.buddyOf.generation === owner.generation)
  const gaveUp: Agent[] = []
  for (const session of sessions) {
    if (!stayedIds.has(session.harnessId)) {
      if (request.gridModel === null) delete session.gridModel
      else session.gridModel = request.gridModel
      delete session.homeOwed
    } else if (request.gridModel !== null || !session.gridModel) delete session.homeOwed
    else {
      const tries = (session.homeOwed?.tries ?? 0) + 1
      if (tries > HOME_TRIES) { delete session.homeOwed; gaveUp.push(session) }
      else session.homeOwed = { ...request.reason ? { reason: request.reason } : {}, tries }
    }
  }
  if (request.sessionsOnly) {
    if (gaveUp.length) {
      const on = gaveUp[0]!.gridModel!
      // The host's words name why (cli superTabs/buddyModel.ts), after its own lead-in, which this line says differently.
      const why = words.replace(/^(?:A thread session stayed where it was|\d+ thread sessions stayed where they were): /, '')
      return mine(stillOn(state, on, why || 'its computer could not move it', now, request.name))
    }
    // Another try is owed while one stays; its owner hears once it lands or gives up, not at every try.
    return stayedIds.size ? [] : mine('Your Buddy\'s thread sessions are back on your subscription too.')
  }
  if (request.gridModel === null) {
    delete buddy.gridModel
    delete buddy.gridModelName
    const left = request.name ?? 'Its model'
    return mine(request.reason === 'gone' ? `Nobody serves ${left} now, so your Buddy is back on your subscription.`
      : request.reason ? `${left} ${HOME_WORDS[request.reason]}, so your Buddy is back on your subscription.`
        : 'Your Buddy is back on your subscription.')
  }
  buddy.gridModel = request.gridModel
  const name = request.name ?? request.gridModel
  buddy.gridModelName = name
  const found = servers(state, request.gridModel, now)
  let text: string
  if (command.fresh) {
    const window = request.contextWindow ? ` (${windowWords(request.contextWindow)})` : ''
    text = `Your Buddy started a fresh session on ${name}: this conversation is too long for it${window}. Switch back to your subscription to continue the earlier one.`
  } else {
    const shown = request.servedBy ?? []
    const by = shown.every(s => s.endsWith("'s saved API")) ? shown.join(', ') : `served by ${shown.join(', ')}`
    text = `Your Buddy now runs on ${name}${shown.length ? `, ${by}` : ''}.`
  }
  // Seen (AGENTS.md, contributed capacity): each other member serving it hears whose Buddy runs on their capacity, in their own chat.
  const told = new Set<string>([owner.personId])
  const theirs: ModelLine[] = []
  for (const s of found) {
    if (told.has(s.personId)) continue
    told.add(s.personId)
    const member = state.people.find(p => p.id === s.personId)
    if (!member) continue
    // No machine named: their own Buddy reads this chat, and a Buddy reads no machines.
    theirs.push({ conversationId: defaultBuddyChat(state, member).id, machines: [],
      text: `${personName(state, owner.personId)}'s agent now runs on ${name}, ${s.api ? 'on your saved API' : 'which your machine serves'}.` })
  }
  // The Buddy moved; a thread session that could not is named, so its owner knows where that thread's answers come from.
  const stayed = clean(command.error ?? '')
  return [...mine(stayed ? `${text} ${stayed}.` : text), ...theirs]
}

/** Requests nobody answered within their lease, dropped, each with the line its owner reads. */
export function expiredModelRequests(state: SuperTabState, now: number): Array<{ buddy: Agent; requestId: string } & ModelLine> {
  const out: Array<{ buddy: Agent; requestId: string } & ModelLine> = []
  for (const buddy of state.agents) {
    const request = buddy.modelRequest
    if (!request || !buddy.buddyOf || now < Date.parse(request.at) + BUDDY_MODEL_LEASE_MS) continue
    delete buddy.modelRequest
    const conversationId = buddyChatOf(state, buddy)?.id ?? swarmBuddyChatId({ id: buddy.buddyOf.personId, generation: buddy.buddyOf.generation })
    // A sessions-only move home its machine never answered counts as a try, said only when it gives up (task #3810; review of
    // #3393: the last one gave up without a word).
    if (request.sessionsOnly) {
      const gaveUp = owedHome(state, buddy).filter(countTry)
      if (gaveUp.length) out.push({ buddy, requestId: request.id, machines: hiddenMachines(state, buddy, request, now), conversationId,
        text: stillOn(state, gaveUp[0]!.gridModel!, 'its computer didn\'t answer', now, request.name) })
      continue
    }
    out.push({ buddy, requestId: request.id, conversationId,
      machines: hiddenMachines(state, buddy, request, now),
      text: `Couldn't switch your Buddy: its computer didn't answer. It is still on ${current(state, buddy, now)}.` })
  }
  return out
}

/** [buddy]'s thread sessions a move home left on a shared model (task #3810): those in its own chat, as buddyModelResult moves
 *  them (task #3818: a person may have several Buddies), else all of its owner's. */
function owedHome(state: SuperTabState, buddy: Agent): Agent[] {
  const chat = buddyChatOf(state, buddy)
  const sessions = chat ? sessionAgentsOf(state, chat)
    : state.agents.filter(a => a.buddySession && a.buddyOf?.personId === buddy.buddyOf!.personId && a.buddyOf.generation === buddy.buddyOf!.generation)
  return sessions.filter(a => a.homeOwed && a.gridModel)
}
/** One more try at moving [session] home; true when that was the last, and its follow-up is dropped. */
function countTry(session: Agent): boolean {
  const tries = session.homeOwed!.tries + 1
  if (tries <= HOME_TRIES) { session.homeOwed = { ...session.homeOwed!, tries }; return false }
  delete session.homeOwed
  return true
}
/** The owner's line when a thread session stays on [model] after its last try home: what to do about it. [known]: the name the
 *  request recorded, for when no machine serves the model by now. */
const stillOn = (state: SuperTabState, model: string, why: string, now: number, known?: string) =>
  `A thread session is still on ${served(state, model, now)?.name ?? known ?? model}: ${why}. End that thread's session to bring it back to your subscription.`

/** Buddies on a model nobody has served for BUDDY_MODEL_GONE_MS are sent home; one served again is unmarked. A Buddy at home
 *  whose thread session a move home left on a shared model asks its machine to move that session home (task #3810). */
export function unservedBuddyModels(state: SuperTabState, now: number, requestId: (buddy: Agent) => string): void {
  for (const buddy of state.agents) {
    if (!buddy.gridModel || buddy.buddySession || !isSwarmBuddy(buddy)) continue
    if (servers(state, buddy.gridModel, now).length) { delete buddy.gridModelUnservedSince; continue }
    buddy.gridModelUnservedSince ??= now
    if (now - buddy.gridModelUnservedSince < BUDDY_MODEL_GONE_MS) continue
    sendBuddyHome(state, buddy, 'gone', requestId(buddy), now)
    if (buddy.modelRequest) delete buddy.gridModelUnservedSince
  }
  for (const buddy of state.agents) {
    if (buddy.buddySession || !isSwarmBuddy(buddy) || buddy.gridModel || buddy.modelRequest) continue
    const owed = owedHome(state, buddy)[0]
    if (!owed || !switchable(state, buddy, now).ok) continue
    buddy.modelRequest = { id: requestId(buddy), gridModel: null, sessionsOnly: true, name: served(state, owed.gridModel!, now)?.name ?? owed.gridModel!,
      ...owed.homeOwed!.reason ? { reason: owed.homeOwed!.reason } : {}, requestedBy: buddy.buddyOf!.personId, at: new Date(now).toISOString() }
  }
}

/** A Buddy thread session's model (commands.ts message.send newSession): the shared one its Buddy runs on while it is served, or
 *  its owner's subscription with Claude Code's own default, never a grid model's name handed to Claude Code as its own. */
export function sessionModel(state: SuperTabState, main: Agent, now: number): { gridModel?: string; gridName?: string; model?: string; effort?: string } {
  if (main.gridModel) {
    return servers(state, main.gridModel, now).length ? { gridModel: main.gridModel, gridName: state.localModels!.grid } : {}
  }
  return { ...(main.configuration.model ? { model: main.configuration.model } : {}), ...(main.configuration.effort ? { effort: main.configuration.effort } : {}) }
}