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
/**
* A Buddy's machine carrying out the model switch its owner asked the Swarm for (task #2354,
* docs/plans/2026-11-03-buddy-model-switch-design.md; backend superTabs/buddyModel.ts). It moves the Buddy, and then each of its
* thread sessions, through this machine's own daemon's `agent_retarget`, the move a pane's model picker makes: the pane relaunches
* Claude Code in place and reopens the same conversation. A conversation too long for the model's window starts fresh there
* instead; the daemon keeps the one it left, which the way home reopens.
*
* Each request is carried out once: its outcome is written before it is reported, so a restart reports it rather than moving the
* Buddy again.
*/
import { createHash } from 'node:crypto'
import { existsSync, renameSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import type { Daemon } from '../agentClient/daemon.js'
import { readPrivateStateFile, secureStateDirectory } from '../lib/secureState.js'
import { BUDDY_NOT_HERE, BUDDY_START_AGAIN } from '../lib/swarmSkills.js'
import { identifier, object } from './wire.js'
/** A conversation this share of the model's window or more starts fresh: the rest is the room its next turns need. */
export const FRESH_SHARE = 0.8
/** How long a move may take: the daemon stops the engine, relaunches it and waits for it to come up. */
const MOVE_TIMEOUT_MS = 120_000
/** How soon a request that waits (a Buddy sent home mid-turn) or a report that failed is tried again. */
const RETRY_MS = 15_000
/** How long the Swarm keeps a request before dropping it unanswered (backend superTabs/buddyModel.ts BUDDY_MODEL_LEASE_MS). */
const LEASE_MS = 10 * 60_000
/** A thread session the request moves (task #3810), by harness id, at most: the Swarm's own limit on what it records. */
const MAX_STAYED = 64
interface ModelRequest { id: string; gridModel: string | null; gridName?: string; name?: string; servedBy?: string[]; contextWindow?: number; reason?: string
/** When the Swarm asked, in ms: a busy thread session is waited for only within the request's lease. */
at?: number
/** Only the thread sessions move: the Buddy is already there (backend superTabs/buddyModel.ts, task #3810). */
sessionsOnly?: true }
/** A Buddy agent's row as this machine's host reads it (backend read/hostRows.ts). */
export interface BuddyModelRow {
tabId: string
agent: { id: string; harnessId: string; buddyOf?: unknown; buddySession?: unknown; modelRequest?: unknown }
}
/** `stayed`: the thread sessions that could not move, by harness id, so the Swarm records them where they still run (#3810). */
interface Outcome { ok: boolean; fresh?: true; error?: string; stayed?: string[] }
export interface BuddyModelDeps {
dataDir: string
now: () => number
log: (message: string) => void
open: () => Promise<Pick<Daemon, 'request' | 'close'>>
post: (tabId: string, agentId: string, operationId: string, command: Record<string, unknown>) => Promise<unknown>
/** The Claude Code transcript of this machine's session [harnessId], when it has one. */
transcript: (harnessId: string) => string | null | undefined
/** How long that conversation is now, in tokens (lib/conversationSize.ts). */
tokens: (transcriptPath: string) => Promise<number | null>
}
function requestOf(value: unknown): ModelRequest | null {
const r = object(value)
if (!identifier(r.id) || !(r.gridModel === null || typeof r.gridModel === 'string')) return null
return { id: r.id, gridModel: r.gridModel, ...(typeof r.gridName === 'string' ? { gridName: r.gridName } : {}),
...(typeof r.name === 'string' ? { name: r.name } : {}),
...(Array.isArray(r.servedBy) ? { servedBy: r.servedBy.filter((s): s is string => typeof s === 'string') } : {}),
...(typeof r.contextWindow === 'number' && r.contextWindow > 0 ? { contextWindow: r.contextWindow } : {}),
...(typeof r.reason === 'string' ? { reason: r.reason } : {}),
...(typeof r.at === 'string' && Number.isFinite(Date.parse(r.at)) ? { at: Date.parse(r.at) } : {}),
...(r.sessionsOnly === true ? { sessionsOnly: true as const } : {}) }
}
/** Why a move was refused, in words its owner can act on: never the daemon's detail, which can name paths on this machine.
* The detail is only read for the Buddy guard's two holds (lib/swarmSkills.ts prepareBuddyFolder), which every relaunch runs
* and the launch reports as SWARM_SKILL_FAILED with the guard's own sentence (lib/launchOverrides.ts). Task #3256: Scholes's
* switch to his saved API, on a Buddy started before its owner was recorded, said only the code. */
function refusal(code: string, request: ModelRequest, detail?: string): string {
if (code === 'AGENT_BUSY') return 'Your Buddy is answering. Try again when it has finished'
if (code === 'SWARM_SKILL_FAILED' && detail?.includes(BUDDY_START_AGAIN)) return 'Start your Buddy again to switch its model'
if (code === 'SWARM_SKILL_FAILED' && detail?.includes(BUDDY_NOT_HERE)) return 'Your Buddy runs only on your own computer, signed in as you'
if ((code === 'GRID_UNAVAILABLE' || code === 'API_UNAVAILABLE') && request.gridModel) {
const name = request.name ?? request.gridModel
return request.servedBy?.length ? `${request.servedBy.join(', ')} isn't serving ${name} now` : `Nobody serves ${name} now`
}
return `its computer could not switch it (${code.replace(/[^A-Z0-9_]/g, '').slice(0, 60) || 'FAILED'})`
}
export class BuddyModelRequests {
/** Requests reported, or settled elsewhere: never carried out again by this process. */
private readonly done = new Set<string>()
private readonly waiting = new Map<string, { busy: boolean; retryAt: number }>()
/** What a request that waits has already moved, so a retry never moves the Buddy twice (task #3810). */
private readonly progress = new Map<string, { moved: Set<string>; fresh: boolean; since: number }>()
constructor(private readonly deps: BuddyModelDeps) {}
/** One poll of a main Buddy row of this machine, with its thread sessions' rows. */
async serve(row: BuddyModelRow, sessions: readonly BuddyModelRow[]): Promise<void> {
const request = requestOf(row.agent.modelRequest)
if (!request || this.done.has(request.id)) return
const now = this.deps.now(), held = this.waiting.get(request.id)
if (held && (held.busy || now < held.retryAt)) return
this.waiting.set(request.id, { busy: true, retryAt: 0 })
try {
const recorded = this.recorded(row.agent.id)
let outcome = recorded?.requestId === request.id ? recorded.outcome : undefined
if (!outcome) {
const carried = await this.carryOut(row, sessions, request, now)
if (carried === 'wait') { this.waiting.set(request.id, { busy: false, retryAt: now + RETRY_MS }); return }
outcome = carried
this.progress.delete(request.id)
this.record(row.agent.id, { requestId: request.id, outcome })
}
try {
await this.deps.post(row.tabId, row.agent.id, `buddy-model-${request.id}`.slice(0, 160),
{ type: 'buddy.modelResult', agentId: row.agent.id, requestId: request.id, ...outcome })
} catch (failure) {
// A request the Swarm already settled (its lease ran out) is done; any other failure is reported again later.
if (object(failure).code !== 'STALE_SWITCH') { this.waiting.set(request.id, { busy: false, retryAt: now + RETRY_MS }); return }
}
this.done.add(request.id)
this.waiting.delete(request.id)
} catch (error) {
this.deps.log(`Buddy model: ${error instanceof Error ? error.name : typeof error}`)
this.waiting.set(request.id, { busy: false, retryAt: now + RETRY_MS })
}
}
private async carryOut(row: BuddyModelRow, sessions: readonly BuddyModelRow[], request: ModelRequest, now: number): Promise<Outcome | 'wait'> {
const progress = this.progress.get(request.id) ?? { moved: new Set<string>(), fresh: false, since: now }
this.progress.set(request.id, progress)
const daemon = await this.deps.open()
try {
const move = async (harnessId: string): Promise<{ error?: string; detail?: string; fresh: boolean }> => {
const fresh = await this.tooLong(harnessId, request)
const frame = request.gridModel === null ? { agentId: harnessId, clearGrid: true }
: { agentId: harnessId, gridModel: request.gridModel, gridName: request.gridName, ...(fresh ? { fresh: true } : {}) }
const reply = await daemon.request('agent_retarget', frame, MOVE_TIMEOUT_MS).catch((): Record<string, unknown> => ({ error: 'TIMEOUT' }))
return { ...(typeof reply.error === 'string' ? { error: reply.error } : {}),
...(typeof reply.detail === 'string' ? { detail: reply.detail } : {}), fresh }
}
if (!request.sessionsOnly && !progress.moved.has(row.agent.harnessId)) {
const moved = await move(row.agent.harnessId)
if (moved.error) {
// Sent home by the Swarm (a limit, a model gone) while it answers: moved once the turn ends, within the request's lease.
if (moved.error === 'AGENT_BUSY' && request.reason) return 'wait'
return { ok: false, error: refusal(moved.error, request, moved.detail) }
}
progress.moved.add(row.agent.harnessId)
progress.fresh = moved.fresh
}
// A thread session that is answering never holds up the Buddy's own result: it is reported as stayed, and the Swarm records
// the Buddy where it now runs at once (Linux test of #3393). The sessions-only follow-up the Swarm then asks for waits
// for its turn to end, until shortly before the Swarm drops the request; then it is reported as stayed again (#3810).
const deadline = (request.at ?? progress.since) + LEASE_MS - 2 * RETRY_MS
const stayed: Array<{ harnessId: string; why: string }> = []
let busy = false
for (const session of sessions) {
const harnessId = session.agent.harnessId
if (progress.moved.has(harnessId)) continue
const result = await move(harnessId)
if (!result.error) { progress.moved.add(harnessId); continue }
if (result.error === 'AGENT_BUSY' && request.sessionsOnly && now < deadline) { busy = true; continue }
stayed.push({ harnessId, why: result.error === 'AGENT_BUSY' ? 'it was answering' : refusal(result.error, request, result.detail) })
}
if (busy) return 'wait'
return { ok: true, ...(progress.fresh ? { fresh: true as const } : {}),
...(stayed.length ? { stayed: stayed.slice(0, MAX_STAYED).map(s => s.harnessId) } : {}),
...(stayed.length === 1 ? { error: `A thread session stayed where it was: ${stayed[0]!.why}` }
: stayed.length ? { error: `${stayed.length} thread sessions stayed where they were: ${stayed[0]!.why}` } : {}) }
} finally { daemon.close() }
}
/** Whether [harnessId]'s conversation is too long for the model it moves onto. Unknown counts as fitting: it resumes, as a
* pane's switch does. */
private async tooLong(harnessId: string, request: ModelRequest): Promise<boolean> {
if (request.gridModel === null || !request.contextWindow) return false
const path = this.deps.transcript(harnessId)
const tokens = path ? await this.deps.tokens(path).catch(() => null) : null
return tokens !== null && tokens >= FRESH_SHARE * request.contextWindow
}
private file(agentId: string): string {
return join(this.deps.dataDir, 'super-tabs', 'buddy-model', `${createHash('sha256').update(agentId).digest('hex')}.json`)
}
/** The last request carried out for this Buddy (one per Buddy, replaced by the next). */
private recorded(agentId: string): { requestId: string; outcome: Outcome } | null {
const file = this.file(agentId)
if (!existsSync(file)) return null
try {
const row = object(JSON.parse(readPrivateStateFile(file, 4_096))), outcome = object(row.outcome)
if (!identifier(row.requestId) || typeof outcome.ok !== 'boolean') return null
const stayed = Array.isArray(outcome.stayed) ? outcome.stayed.filter(identifier).slice(0, MAX_STAYED) : []
return { requestId: row.requestId, outcome: { ok: outcome.ok, ...(outcome.fresh === true ? { fresh: true } : {}),
...(typeof outcome.error === 'string' ? { error: outcome.error.slice(0, 300) } : {}), ...(stayed.length ? { stayed } : {}) } }
} catch { return null }
}
private record(agentId: string, value: { requestId: string; outcome: Outcome }): void {
const file = this.file(agentId)
secureStateDirectory(join(this.deps.dataDir, 'super-tabs', 'buddy-model'))
writeFileSync(`${file}.tmp`, JSON.stringify(value), { mode: 0o600 })
renameSync(`${file}.tmp`, file)
}
}