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
/**
* What a Swarm agent is told about its project's instructions (task #4673): it reads them with the instructions command, and
* when the roster names a new revision, template or role name, its host tells it once to read them again. Nothing else is
* written for it. A session an older release launched kept skill files instead: it is told once that they are gone, and they
* are removed. The record, per session in its Swarm folder, says what the agent was last confirmed told, so a retry, a restart
* or a second daemon never tells it twice, and several changes before a notice make one notice.
*/
import { createHash } from 'node:crypto'
import { existsSync, lstatSync, readFileSync } from 'node:fs'
import { launchedAt, parseSwarmSkill, removeOlderSkills, replaceSkillFile, swarmFile, type SavedSwarmSkill } from '../lib/swarmSkills.js'
/** The instructions as the roster names them, and the newest revision's summary and save time (epoch ms) when the history
* answered (null otherwise). */
export interface InstructionsAt { tabId: string; projectId: string; revision: number; hash: string | null; roleName: string
summary: string | null; savedAt: number | null }
/** `version` names what the roster said and `change` counts its changes: the notice's operation id is made of both. */
export interface InstructionsNotice { version: string; owed: boolean; change: number; notice: string }
interface Seen { version: string; revision: number; roleName: string }
/** `told`: what its agent was last confirmed told, or null for a session an older release launched, before it was told. */
interface NoticeRecord extends Seen { change: number; told: (Seen & { change: number }) | null }
const RECORD = 'instructions.json'
/** Say whether the session's agent owes a notice for [at]; recordInstructionsNotice clears that once the notice is sent. Null
* when the workspace is gone or the session is a Buddy, which reads its projects' instructions when it needs them. */
export function refreshInstructionsNotice(workspace: string, saved: SavedSwarmSkill, at: InstructionsAt): InstructionsNotice | null {
const skill = parseSwarmSkill(saved)
if (!skill) 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 (skill.role === 'buddy' || !existsSync(workspace)) return null
const file = swarmFile(workspace, skill, RECORD, true)!
const now: Seen = { version: versionOf(at), revision: at.revision, roleName: at.roleName }
const old = readRecord(file)
let record: NoticeRecord
if (!old) {
const launch = launchedAt(workspace, skill)
let told: NoticeRecord['told'] = null
if (launch === null) removeOlderSkills(workspace, skill)
else {
// The launch line sent the agent to the instructions command: it read a revision saved by its launch (or the template,
// revision 0). A save after it, or one whose time the history could not say, is the first change to tell.
const read = at.revision === 0 || (at.savedAt !== null && at.savedAt <= launch)
told = read ? { ...now, change: 0 } : { version: '', revision: 0, roleName: now.roleName, change: 0 }
}
record = { ...now, change: told?.version === now.version ? 0 : 1, told }
replaceSkillFile(file, JSON.stringify(record))
} else if (old.version !== now.version) {
record = { ...now, change: old.change + 1, told: old.told }
replaceSkillFile(file, JSON.stringify(record))
} else record = old
return { version: record.version, owed: record.told?.change !== record.change, change: record.change, notice: noticeOf(record, at) }
}
/** The notice for that refresh was sent. Only a record still holding what it described is marked told: a later change stays
* owed, and its notice names everything since the last confirmed one. */
export function recordInstructionsNotice(workspace: string, saved: SavedSwarmSkill, sent: Pick<InstructionsNotice, 'version' | 'change'>): void {
if (!existsSync(workspace)) return
const file = swarmFile(workspace, saved, RECORD, false)
const record = file && readRecord(file)
if (!file || !record || record.change !== sent.change || record.version !== sent.version) return
const { told: _told, ...state } = record
replaceSkillFile(file, JSON.stringify({ ...state, told: { version: state.version, revision: state.revision, roleName: state.roleName, change: state.change } }))
}
function noticeOf(record: NoticeRecord, at: InstructionsAt): string {
const command = `harness super-tab --tab ${at.tabId} instructions`
if (!record.told) {
return 'Harness no longer gives you skill files: don\'t read your swarm-tools, swarm-instructions or role skill again. Before your next step, '
+ `read your project's instructions with ${command} and the manual with harness super-tab help tools, and work by them.`
}
const renamed = record.told.roleName !== record.roleName
// Anything else that moved (a revision, the template's hash) is a change of the instructions.
const changed = !renamed || record.told.revision !== record.revision
if (!changed) return `You are now this project's ${record.roleName}. Before your next step, read the project's instructions again with ${command} and work by them.`
const summary = record.told.revision !== record.revision ? at.summary?.trim().replace(/[.!?]$/, '') : ''
return [`The project's instructions changed${summary ? `: ${summary}` : ''}.`, ...(renamed ? [`You are now this project's ${record.roleName}.`] : []),
`Before your next step, read them again with ${command} and work by them.`].join(' ')
}
const versionOf = (at: InstructionsAt) => createHash('sha256').update(JSON.stringify([at.projectId, at.revision, at.hash, at.roleName])).digest('hex')
function readRecord(file: string): NoticeRecord | null {
let stat
try { stat = lstatSync(file) } catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
throw error
}
if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Swarm skill is not a plain file: ${file}`)
const value = JSON.parse(readFileSync(file, 'utf8')) as Partial<NoticeRecord>, told = value.told
const seen = (state: unknown): state is Seen & { change: number } => {
const s = (state ?? {}) as Partial<NoticeRecord>
return typeof s.version === 'string' && Number.isSafeInteger(s.revision) && typeof s.roleName === 'string' && Number.isSafeInteger(s.change)
}
if (!seen(value)) return null
return { version: value.version, revision: value.revision, roleName: value.roleName, change: value.change, told: seen(told) ? told : null }
}