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
Running Swarm agents pick up new skill text after an update (#1585)
0xken15574e72674515
diff --git a/cli/src/lib/swarmSkills.spec.ts b/cli/src/lib/swarmSkills.spec.tsindex 062b0d837..8c0c33d63 100644--- a/cli/src/lib/swarmSkills.spec.ts+++ b/cli/src/lib/swarmSkills.spec.ts@@ -4,7 +4,7 @@ import { mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSyncimport { tmpdir } from 'node:os'import { dirname, join } from 'node:path'import { afterEach, describe, expect, it } from 'vitest'-import { prepareSwarmSkill, parseSwarmSkill } from './swarmSkills.js'+import { prepareSwarmSkill, parseSwarmSkill, recordSwarmSkillNotice, refreshSwarmSkill } from './swarmSkills.js'import { agentLaunchArgs } from './agentAttribution.js'import { buildLaunchOverrides } from './launchOverrides.js'import { gridLaunchInProcess } from '../testing/gridLaunchInProcess.js'@@ -53,6 +53,52 @@ describe('built-in Swarm skills', () => {expect(createHash('sha256').update(text).digest('hex')).toBe(sha256)})+ describe('a running session after a CLI update', () => {+ const skill = { role: 'dev' as const, key: 'running' }+ // What an older CLI left: its own text, and either no record (before records) or a record of that text.+ const older = (workspace: string, recorded: boolean) => {+ const { file } = prepareSwarmSkill(workspace, skill)+ const text = '---\nname: swarm-dev\n---\nAn older release of this skill.\n', version = createHash('sha256').update(text).digest('hex')+ writeFileSync(file, text)+ if (recorded) writeFileSync(join(dirname(file), 'version.json'), JSON.stringify({ text: version, notified: version }))+ else rmSync(join(dirname(file), 'version.json'))+ return file+ }+ it.each([false, true])('rewrites an older skill file and owes one notice until it is recorded (recorded before: %s)', recorded => {+ const workspace = fixture(), file = older(workspace, recorded)+ const sync = refreshSwarmSkill(workspace, skill)!+ expect(sync).toMatchObject({ file, owed: true })+ expect(readFileSync(file, 'utf8')).toBe(readFileSync(prepareSwarmSkill(fixture(), skill).file, 'utf8'))+ // Not yet recorded: a later pass, or another daemon, still owes the same notice for the same text.+ expect(refreshSwarmSkill(workspace, skill)).toEqual(sync)+ recordSwarmSkillNotice(workspace, skill, sync.version)+ expect(refreshSwarmSkill(workspace, skill)).toMatchObject({ file, owed: false })+ // The agent's own edits after the update are its own: the record says the file already holds this text.+ writeFileSync(file, 'edited')+ expect(refreshSwarmSkill(workspace, skill)).toMatchObject({ owed: false })+ expect(readFileSync(file, 'utf8')).toBe('edited')+ })+ it('owes nothing for a file already on the built-in text, new or from before records', () => {+ const fresh = fixture()+ prepareSwarmSkill(fresh, skill)+ expect(refreshSwarmSkill(fresh, skill)).toMatchObject({ owed: false })+ const legacy = fixture(), { file } = prepareSwarmSkill(legacy, skill)+ rmSync(join(dirname(file), 'version.json'))+ expect(refreshSwarmSkill(legacy, skill)).toMatchObject({ owed: false })+ })+ it('does nothing for a session whose skill was never prepared in this workspace', () => {+ expect(refreshSwarmSkill(fixture(), skill)).toBeNull()+ expect(refreshSwarmSkill(join(fixture(), 'removed-worktree'), skill)).toBeNull()+ })+ it('never writes through a redirected skill file', () => {+ const workspace = fixture(), file = older(workspace, false), target = join(fixture(), 'elsewhere.md')+ writeFileSync(target, 'kept')+ rmSync(file); symlinkSync(target, file)+ expect(() => refreshSwarmSkill(workspace, skill)).toThrow('plain file')+ expect(readFileSync(target, 'utf8')).toBe('kept')+ })+ })+it('keeps standalone session skills out of Git, including git add -A', () => {const workspace = fixture()execFileSync('git', ['init', '-q', workspace])diff --git a/cli/src/lib/swarmSkills.ts b/cli/src/lib/swarmSkills.tsindex 8b41e75f7..f82605620 100644--- a/cli/src/lib/swarmSkills.ts+++ b/cli/src/lib/swarmSkills.ts@@ -1,7 +1,7 @@/** Built into the CLI so contributed machines need no separately installed plugin. */import { ignoreHarnessRuntime } from './harnessRuntimeIgnore.js'-import { createHash } from 'node:crypto'-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'+import { createHash, randomUUID } from 'node:crypto'+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs'import { join, relative, sep } from 'node:path'export type SwarmRole = 'lead' | 'dev' | 'review'@@ -335,11 +335,67 @@ Mark your review assignment done with the verdict and revision. Print little.`,}-/** A session owns these bytes; retries and CLI upgrades cannot change a running session's skill.+/** Launch and relaunch keep a session's saved bytes; only refreshSwarmSkill moves a running session to new built-in text.* No project-wide native skill links: two roles may share a workspace. */export function prepareSwarmSkill(workspace: string, saved: SwarmSkill): { file: string; instructions: string } {if (!parseSwarmSkill(saved)) throw new Error('A Swarm skill needs a role and session key')const root = realpathSync(workspace)+ const dir = skillDirectory(root, saved, true)!+ ignoreHarnessRuntime(root)+ const file = join(dir, 'SKILL.md')+ if (existsSync(file)) {+ plainFile(file)+ // Read now so an unreadable saved skill refuses launch, rather than silently dropping the role.+ readFileSync(file, 'utf8')+ } else {+ writeFileSync(file, skills[saved.role], { flag: 'wx', mode: 0o600 })+ const version = textVersion(skills[saved.role])+ writeRecord(dir, { text: version, notified: version })+ }+ return { file, instructions: `Use the built-in swarm-${saved.role} skill for this session. Before working, read ${JSON.stringify(file)} with your file or shell tool.` }+}++/** Which built-in text a session's skill file holds, and which text its agent was last told to re-read. A file from before+ * this record counts as holding its own content, already told. */+interface SkillRecord { text: string; notified: string }+export interface SkillRefresh { file: string; version: string; owed: boolean }++/** A CLI update ships new skill text while Swarm sessions run (owner, 2026-10-22). Rewrite a session's file to the+ * built-in text and say whether its agent still owes a re-read notice for it; recordSwarmSkillNotice clears that once+ * the notice is sent. A file from before records gets its record first, and the record moves to the new text only after+ * the file is replaced, so an interrupted pass rewrites again and the notice stays owed until it is recorded. Null when+ * this workspace never prepared the session's skill. */+export function refreshSwarmSkill(workspace: string, saved: SwarmSkill): SkillRefresh | null {+ if (!parseSwarmSkill(saved)) throw new Error('A Swarm skill needs a role and session key')+ // A removed worktree has nothing to refresh; the host would otherwise retry and log it every minute.+ if (!existsSync(workspace)) return null+ const dir = skillDirectory(realpathSync(workspace), saved, false)+ const file = dir && join(dir, 'SKILL.md')+ if (!dir || !file || !existsSync(file)) return null+ plainFile(file)+ const text = skills[saved.role], version = textVersion(text)+ let record = readRecord(dir)+ if (!record) {+ const held = textVersion(readFileSync(file, 'utf8'))+ record = { text: held, notified: held }+ if (held !== version) writeRecord(dir, record)+ }+ if (record.text !== version) {+ replaceFile(file, text)+ record = { ...record, text: version }+ writeRecord(dir, record)+ }+ return { file, version, owed: record.notified !== version }+}+export function recordSwarmSkillNotice(workspace: string, saved: SwarmSkill, version: string): void {+ const dir = skillDirectory(realpathSync(workspace), saved, false)+ const record = dir && readRecord(dir)+ if (dir && record) writeRecord(dir, { ...record, notified: version })+}++const textVersion = (text: string) => createHash('sha256').update(text).digest('hex')+/** Every part under the workspace is a plain directory; `create` makes missing ones, otherwise a missing one is null. */+function skillDirectory(root: string, saved: SwarmSkill, create: boolean): string | null {const dir = join(root, '.harness', 'runtime', createHash('sha256').update(saved.key).digest('hex'), 'swarm', 'skills', `swarm-${saved.role}`)let path = rootfor (const part of relative(root, dir).split(sep)) {@@ -349,16 +405,29 @@ export function prepareSwarmSkill(workspace: string, saved: SwarmSkill): { file:if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Swarm skill directory is not a plain directory: ${path}`)} catch (error) {if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error+ if (!create) return nullmkdirSync(path, { mode: 0o700 })}}- ignoreHarnessRuntime(root)- const file = join(dir, 'SKILL.md')- if (existsSync(file)) {- const stat = lstatSync(file)- if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Swarm skill is not a plain file: ${file}`)- // Read now so an unreadable saved skill refuses launch, rather than silently dropping the role.- readFileSync(file, 'utf8')- } else writeFileSync(file, skills[saved.role], { flag: 'wx', mode: 0o600 })- return { file, instructions: `Use the built-in swarm-${saved.role} skill for this session. Before working, read ${JSON.stringify(file)} with your file or shell tool.` }+ return dir+}+function plainFile(file: string): void {+ const stat = lstatSync(file)+ if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Swarm skill is not a plain file: ${file}`)+}+function readRecord(dir: string): SkillRecord | null {+ const file = join(dir, 'version.json')+ if (!existsSync(file)) return null+ plainFile(file)+ const record = JSON.parse(readFileSync(file, 'utf8')) as Partial<SkillRecord>+ return typeof record.text === 'string' && typeof record.notified === 'string' ? { text: record.text, notified: record.notified } : null+}+function writeRecord(dir: string, record: SkillRecord): void {+ replaceFile(join(dir, 'version.json'), JSON.stringify(record))+}+/** A fresh temporary name created exclusively, so nothing planted at a fixed name is written through (as native.ts does). */+function replaceFile(file: string, text: string): void {+ const temporary = `${file}.${randomUUID()}.next`+ writeFileSync(temporary, text, { mode: 0o600, flush: true, flag: 'wx' })+ renameSync(temporary, file)}diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.tsindex edf66dd7e..35ae767e9 100644--- a/cli/src/superTabs/host.spec.ts+++ b/cli/src/superTabs/host.spec.ts@@ -1,6 +1,7 @@import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'-import { join } from 'node:path'+import { dirname, join } from 'node:path'+import { prepareSwarmSkill } from '../lib/swarmSkills.js'import { afterEach, describe, expect, it, vi } from 'vitest'import type { CoreApi, TurnDelivery } from '../core/api.js'import { fakeCore } from '../testing/fakeCore.js'@@ -948,3 +949,102 @@ describe('adding the machine its own Lead runs on to the Swarm', () => {expect(t.prepare).toHaveBeenCalledTimes(2)})})++describe('built-in skill text after a CLI update', () => {+ const older = '---\nname: swarm-dev\n---\nAn older release of this skill.\n'+ function syncFixture(stale = true) {+ const t = setup(), workspace = mkdtempSync(join(tmpdir(), 'super-tab-skills-')); roots.push(workspace)+ const roles = { lead: 'lead', builder: 'dev', reviewer: 'review' } as const+ const sessions = Object.fromEntries([...Object.entries(roles).map(([name, role]) => [`h-${name}`,+ { agentId: `h-${name}`, cwd: workspace, swarmSkill: { role, key: `key-${name}` } }]),+ ['h-personal', { agentId: 'h-personal', cwd: workspace }]])+ const files = Object.fromEntries(Object.entries(roles).map(([name, role]) => {+ const { file } = prepareSwarmSkill(workspace, { role, key: `key-${name}` })+ // What an older CLI left: its own text and no record of which text it was.+ if (stale) { writeFileSync(file, older); rmSync(join(dirname(file), 'version.json')) }+ return [name, file]+ }))+ const agents = [...Object.keys(roles), 'personal'].map(name => ({ id: `a-${name}`, harnessId: `h-${name}`, machineId: 'machine-1' }))+ let groups: Array<Record<string, unknown>> = [+ { id: 'lead-group', leadId: 'a-lead', agentIds: ['a-lead', 'a-builder', 'a-reviewer'] },+ { id: 'work', leadId: 'a-lead', agentIds: ['a-lead', 'a-builder'], assignment: { agentId: 'a-builder', status: 'working' } },+ ]+ const sent: Array<{ operationId: string; asAgentId: string; command: Record<string, any> }> = []+ const receipts = new Map<string, string>()+ let inFlight = 0+ t.core.agents.byAgent = vi.fn(id => sessions[id] as never)+ t.core.agents.terminalAvailable = vi.fn(() => true)+ t.core.account.backend = vi.fn(async (method, path, body) => {+ inFlight+++ await Promise.resolve()+ inFlight--+ const request = body as any+ if (path.includes('/hosts/')) return { status: 200, body: { data: agents.map(agent => ({ tabId: 'tab', agent })) } }+ if (path.endsWith('/deliveries')) return { status: 200, body: { data: [] } }+ if (request?.command?.type === 'message.send') {+ // As the backend does: a repeated operation gets its first receipt; the same id for a different request is refused.+ const prior = receipts.get(request.operationId), same = JSON.stringify(request.command)+ if (prior !== undefined && prior !== same) return { status: 409, body: { success: false, error: { code: 'OPERATION_REUSED', message: 'Use a new operation ID for a different request.' } } }+ if (prior === undefined) { receipts.set(request.operationId, same); sent.push(request) }+ return { status: 200, body: { data: {} } }+ }+ return { status: 200, body: { data: { state: { agents, conversations: groups } } } }+ })+ // The refresh runs beside the poll: wait until no backend call is in flight and the host's own work has had its turn.+ const pass = async (host = t.open(), advance = 0) => {+ t.wait(advance); await host.tick()+ for (let idle = 0; idle < 3;) { await new Promise(resolve => setImmediate(resolve)); idle = inFlight ? 0 : idle + 1 }+ return host+ }+ return { t, files, sent, pass, setGroups: (next: typeof groups) => { groups = next } }+ }++ it('rewrites each running Lead, Builder and Reviewer skill once and tells each agent once, never a personal session', async () => {+ const f = syncFixture()+ const host = await f.pass()+ for (const file of Object.values(f.files)) expect(readFileSync(file, 'utf8')).not.toBe(older)+ expect(f.sent.map(s => [s.asAgentId, s.command.recipientIds, s.command.conversationId]).sort()).toEqual([+ ['a-builder', ['a-builder'], 'work'], ['a-lead', ['a-lead'], 'lead-group'], ['a-reviewer', ['a-reviewer'], 'lead-group']])+ for (const s of f.sent) expect(s.command.text).toContain(f.files[s.asAgentId.slice(2)]!)+ expect(f.sent.find(s => s.asAgentId === 'a-reviewer')!.command.text).toContain('swarm-review skill')+ // A second pass and a restarted host find the files current and say nothing more.+ await f.pass(host, 5_000)+ await f.pass()+ expect(f.sent).toHaveLength(3)+ })++ it('records a notice that was sent before its record was lost, even after its group changed', async () => {+ const f = syncFixture()+ await f.pass()+ const lead = join(dirname(f.files.lead!), 'version.json'), record = JSON.parse(readFileSync(lead, 'utf8'))+ // The send succeeded, the record did not survive, and the Lead's group was archived meanwhile.+ writeFileSync(lead, JSON.stringify({ ...record, notified: 'older' }))+ f.setGroups([{ id: 'lead-group', archived: true, leadId: 'a-lead', agentIds: ['a-lead'] }, { id: 'next', leadId: 'a-lead', agentIds: ['a-lead'] }])+ await f.pass()+ expect(JSON.parse(readFileSync(lead, 'utf8')).notified).toBe(record.notified)+ expect(f.t.log).not.toHaveBeenCalled()+ const calls = vi.mocked(f.t.core.account.backend).mock.calls.length+ await f.pass()+ expect(vi.mocked(f.t.core.account.backend).mock.calls.slice(calls).some(([, , body]) => (body as any)?.command?.type === 'message.send')).toBe(false)+ expect(f.sent).toHaveLength(3)+ })++ it('says nothing when the skill files already hold the built-in text', async () => {+ const f = syncFixture(false)+ await f.pass()+ expect(f.sent).toEqual([])+ })++ it('rewrites the file of a session in no open group at once and tells it once it joins one', async () => {+ const f = syncFixture()+ f.setGroups([{ id: 'old', archived: true, leadId: 'a-lead', agentIds: ['a-lead', 'a-builder', 'a-reviewer'] }])+ const host = await f.pass()+ for (const file of Object.values(f.files)) expect(readFileSync(file, 'utf8')).not.toBe(older)+ expect(f.sent).toEqual([])+ f.setGroups([{ id: 'next', leadId: 'a-lead', agentIds: ['a-lead', 'a-builder', 'a-reviewer'] }])+ await f.pass(host, 60_000)+ expect(f.sent.map(s => s.asAgentId).sort()).toEqual(['a-builder', 'a-lead', 'a-reviewer'])+ await f.pass(host, 60_000)+ expect(f.sent).toHaveLength(3)+ })+})diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.tsindex cdbbabaee..ea82f2728 100644--- a/cli/src/superTabs/host.ts+++ b/cli/src/superTabs/host.ts@@ -23,7 +23,7 @@ export class SuperTabHostError extends Error {}export { identifier, object } from './wire.js'import { ENDED_WORK, identifier, object } from './wire.js'-import type { SwarmRole } from '../lib/swarmSkills.js'+import { recordSwarmSkillNotice, refreshSwarmSkill, type SwarmRole, type SwarmSkill } from '../lib/swarmSkills.js'/** The core signs each request. Neither the service nor its journal holds an account credential. */export async function backend(core: CoreApi, method: string, path: string, body?: unknown): Promise<unknown> {@@ -91,6 +91,8 @@ export const hostJournalFile = (dataDir: string, machineId: string) => join(data* failed one. Each try probes every engine's account (about 14 login shells), so the wait doubles up to half an hour:* a refusal such as a dispatched start that never reports, or no signed-in engine, can last for days. */const JOIN_RETRY_MS = 60_000+/** How long a skill re-read notice that could not be sent (no open group yet, or the backend failed) waits to retry. */+const SKILL_RETRY_MS = 60_000const JOIN_RETRY_MAX_MS = 30 * 60_000/** Refusals no retry can change while this host runs: the Swarm has all its machines, or this account does not own it. */const JOIN_FINAL = new Set(['MACHINES_FULL', 'OWNER_REQUIRED'])@@ -158,6 +160,10 @@ export class SuperTabHost {private attention: string | null = null/** The harnesses last handed over waiting, and since when each has been missing from the core's live agents. */private waiting = new Set<string>()+ /** When each running Swarm session's skill is next compared with the built-in text: once per host, and again while+ * its re-read notice is still owed. */+ private readonly skillChecks = new Map<string, number>()+ private skillsRunning: Promise<void> | null = nullprivate missing = new Map<string, number>()constructor(private readonly core: CoreApi, readonly machineId: string, options: SuperTabHostOptions = {}) {@@ -446,6 +452,7 @@ export class SuperTabHost {const stopKeys = new Set(data.filter(item => object(item).stopRequested === true).map(item => { const row = object(item); return `${row.tabId}:${object(row.agent).id}` }))for (const key of this.releaseAttempts.keys()) if (!stopKeys.has(key)) this.releaseAttempts.delete(key)const seen = new Set<string>()+ const running: HostAgent[] = []for (const item of data) {const row = object(item), agent = object(row.agent)if (!identifier(row.tabId) || !identifier(agent.id) || !identifier(agent.harnessId) || agent.machineId !== this.machineId) continue@@ -457,6 +464,7 @@ export class SuperTabHost {}// Never adopt another live session as a replacement for the recorded harness.if (!this.core.agents.byAgent(target.agent.harnessId) || !this.core.agents.terminalAvailable(target.agent.harnessId)) continue+ running.push(target)const path = `/api/super-tabs/${target.tabId}/agents/${target.agent.id}/deliveries`try {const deliveries = await backend(this.core, 'GET', path)@@ -493,6 +501,50 @@ export class SuperTabHost {}}await this.leases()+ // Off the poll, so the backend calls of a notice never delay the next lease renewal. Owed at most once per text release.+ this.skillsRunning ??= (async () => { for (const target of running) await this.refreshSkill(target) })()+ .finally(() => { this.skillsRunning = null })+ }++ /** A CLI update can ship new built-in skill text while Swarm sessions run; until now a running agent kept the text it+ * read at start, so a skill release reached nobody until each agent restarted (owner, 2026-10-22). Rewrite a role+ * session's file at once; tell its agent through the Swarm, as any delivery, once it is in an open group. The+ * operation id names the agent and the text, so a retry, a restart or a second daemon never sends it twice. */+ private async refreshSkill(target: HostAgent): Promise<void> {+ const session = this.core.agents.byAgent(target.agent.harnessId)+ const skill = session?.swarmSkill+ const due = this.skillChecks.get(target.agent.harnessId) ?? 0+ if (!skill || !session.cwd || this.now() < due) return+ this.skillChecks.set(target.agent.harnessId, Infinity)+ try {+ const refresh = refreshSwarmSkill(session.cwd, skill)+ if (!refresh?.owed) return+ if (await this.tellSkill(target, skill, refresh)) recordSwarmSkillNotice(session.cwd, skill, refresh.version)+ else this.skillChecks.set(target.agent.harnessId, this.now() + SKILL_RETRY_MS)+ } catch (error) {+ this.log(error instanceof Error ? error.message : String(error))+ this.skillChecks.set(target.agent.harnessId, this.now() + SKILL_RETRY_MS)+ }+ }+ private async tellSkill(target: HostAgent, skill: SwarmSkill, refresh: { file: string; version: string }): Promise<boolean> {+ const id = target.agent.id+ const answer = object(await backend(this.core, 'GET', `/api/super-tabs/${target.tabId}?asAgentId=${id}`))+ const groups = (Array.isArray(object(answer.state).conversations) ? object(answer.state).conversations as unknown[] : []).map(object)+ .filter(group => group.archived !== true && identifier(group.id) && Array.isArray(group.agentIds) && group.agentIds.includes(id))+ const group = groups.find(g => g.leadId === id) ?? groups.find(g => object(g.assignment).agentId === id) ?? groups[0]+ if (!group) return false+ try {+ await backend(this.core, 'POST', `/api/super-tabs/${target.tabId}/commands`, {+ operationId: `skill-${id}-${refresh.version.slice(0, 32)}`, asAgentId: id,+ command: { type: 'message.send', conversationId: group.id, replyTo: null, recipientIds: [id],+ text: `Harness updated your built-in swarm-${skill.role} skill. Before your next step, read ${JSON.stringify(refresh.file)} again with your file or shell tool and follow the new version.` },+ })+ } catch (error) {+ // The notice was sent, but its record was lost (a crash, a restart, another daemon) and its group has changed since:+ // the same operation id now names a different request. It was delivered once; record it rather than retry forever.+ if (!(error instanceof SuperTabHostError) || error.code !== 'OPERATION_REUSED') throw error+ }+ return true}/** The roster marks a Swarm whose Lead runs on this machine of its owner while the machine is not one of the Swarm's