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.

22.4 KB
Raw Blame
import { createHash, randomUUID } from 'node:crypto'
import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { basename, dirname, join } from 'node:path'
import { buddyAccountFile } from './buddyAccount.js'
import { PASTE_DROPS_DIR } from './pasteDropFiles.js'
import { env } from '../config/env.js'

/**
 * What is left of a Buddy's guard (task #2832). Until Ken's decision of 11-04 a Buddy ran read-only, behind a PreToolUse hook
 * that answered every tool call (security reviews of #1992, #2092, #2310). A Buddy is its owner's right hand now: on their own
 * machine it launches like their own session, in full mode (superTabs/start.ts), and the hook, its wide reads and their
 * "run:" approvals, the lists of files sent to it and the read-only folder are gone.
 *
 * What stays is the proof its owner is here: at each message its owner sends it in their own Buddy chat, signed in on this
 * machine, the host grants the Buddy session for this launch, for an hour (superTabs/host.ts). A relay to its owner's own
 * sessions holds only while that grant does (messages/service.ts, #2626). Each session's grant is kept in a list of its own in
 * Harness's data folder, which the Swarm's end of the session removes (`forgetBuddyReads`).
 */

/** Where a Buddy session's list is: its grant. */
export interface BuddyReads { file: string }

/** Where every Buddy session's list is kept: Harness's data folder, never a Buddy's own folder, where a commit or a pull
 *  could put one. */
const listsDir = () => join(env.ADAPTER_DATA_DIR, 'buddy-reads')

const sha256 = (text: string) => createHash('sha256').update(text).digest('hex')

/** Lists that nothing has written to for a day, of sessions ended or quiet, hold no grant still live: best-effort, at each
 *  write. A mark goes once its list has, and not before: its session's end still finds the list by it. A listed file lasts
 *  as long, as Harness keeps a download a day (lib/pasteDropFiles.ts). */
const KEPT_MS = 24 * 60 * 60 * 1000

/** The list for one Buddy session, by its Swarm skill's key. */
export function buddyReadsOf(key: string): BuddyReads {
  return { file: join(listsDir(), `${sha256(key)}.json`) }
}

/**
 * The mark beside [list] that [session] listed in it: an empty file, read by its name alone. The end of a session finds its
 * own lists by these even where a list cannot be read, and so leaves every other session's alone. Follow-up to #2248 (Lead,
 * 10-30): whose a list was that could not be read could not be told, so it held back the end of every Buddy on the machine.
 */
const markOf = (list: string, session: string) => `${list.replace(/\.json$/, '')}.${sha256(session)}.owner`
const MARK = /\.[0-9a-f]{64}\.owner$/

/** The grant: to this session, at this launch, for this account, at this time (delta reviews of #2310). */
interface Grant { session: string; account: string; launch: string; at: number }
/** `session`: the native session the host delivered to, whose list goes when the Swarm ends it (`forgetBuddyReads`). `files`
 *  and `links`: what its person sent it, for a Buddy still running the guard of a release before #2832 (`listSentToOldGuard`);
 *  kept through every write, as that guard reads them. An older list's approvals are not kept: nothing records them now. */
interface List { version: 1; session: string; wide?: Grant | false; files?: ListedFile[]; links?: ListedLink[] }
interface ListedFile { path: string; dev: string; ino: string; size: string; sha256: string; at: number }
interface ListedLink { url: string; at: number }

/** What [file] holds for [session]: nothing another session listed under the same key, nor anything unreadable. Listed files
 *  and links from the last day only, as long as Harness keeps a download. */
function heldList(file: string, session: string, now = Date.now()): List {
  const none: List = { version: 1, session }
  try {
    const held = JSON.parse(readFileSync(file, 'utf8')) as { session?: unknown; wide?: unknown; files?: unknown; links?: unknown }
    if (held.session !== session) return none
    const grant = held.wide === false ? false : held.wide && typeof held.wide === 'object' ? held.wide as Grant : undefined
    const fresh = (value: unknown) => (Array.isArray(value) ? value : []).filter((entry): entry is Record<string, unknown> => !!entry
      && typeof entry === 'object' && Number.isFinite(entry.at) && now - (entry.at as number) < KEPT_MS)
    const files = fresh(held.files).filter((entry): entry is Record<string, unknown> & ListedFile => ['path', 'dev', 'ino', 'size', 'sha256']
      .every(field => typeof entry[field] === 'string'))
    const links = fresh(held.links).filter((entry): entry is Record<string, unknown> & ListedLink => typeof entry.url === 'string')
    return { version: 1, session, ...(grant !== undefined ? { wide: grant } : {}),
      ...(files.length ? { files: files.map(({ path, dev, ino, size, sha256, at }) => ({ path, dev, ino, size, sha256, at })) } : {}),
      ...(links.length ? { links: links.map(({ url, at }) => ({ url, at })) } : {}) }
  } catch { return none }
}

function sweep(dir: string, now: number): void {
  try {
    const names = readdirSync(dir), present = new Set(names)
    for (const name of names) {
      try {
        if (MARK.test(name)) { if (!present.has(name.replace(MARK, '.json'))) rmSync(join(dir, name), { force: true }) }
        else if ((name.endsWith('.json') || name.endsWith('.tmp')) && now - statSync(join(dir, name)).mtimeMs >= KEPT_MS) rmSync(join(dir, name), { force: true })
      } catch { /* raced: ignore */ }
    }
  } catch { /* unreadable: nothing to sweep */ }
}

/** A claude.ai Artifact link, or null. */
function artifactLink(text: string): string | null {
  let url: URL
  try { url = new URL(text) } catch { return null }
  const path = /^\/((?:code\/)?artifact\/[A-Za-z0-9_-]{1,100})\/?$/.exec(url.pathname)
  if (!path || url.protocol !== 'https:' || !['claude.ai', 'preview.claude.ai'].includes(url.hostname) || url.port || url.username
    || url.password || url.search || url.hash) return null
  return `https://${url.hostname}/${path[1]}`
}

/** The claude.ai Artifact links in a message's text, each as the artifact's own link: a query or fragment the person's
 *  link carried is dropped, so the Buddy is told the artifact's one link (superTabs/host.ts). */
export function artifactLinks(text: string): string[] {
  const found = new Set<string>()
  for (const [candidate] of text.matchAll(/https:\/\/[^\s<>()[\]{}"'`]+/gi)) {
    let url: URL
    try { url = new URL(candidate.replace(/[.,;:!?]+$/, '')) } catch { continue }
    url.search = ''; url.hash = ''
    const link = artifactLink(url.href)
    if (link) found.add(link)
  }
  return [...found].slice(0, 50)
}

/**
 * Writes [list] as [session]'s: every writer of a session's list comes here (security reviews of #2261, folded into #2310,
 * Lead 10-30). Its mark first, so a list that cannot be read still holds back its own session's end and no other
 * (`forgetBuddyReads`): created only as a file of its own, never through a link, and one already there must be a plain
 * file. Other sessions' marks beside the list go, as the list is no longer theirs. Then the list, as one rename. Throws
 * when it cannot, so the host tries the delivery again.
 */
function writeList(file: string, session: string, list: List): void {
  const dir = dirname(file), own = markOf(file, session)
  mkdirSync(dir, { recursive: true, mode: 0o700 })
  let fd: number | undefined
  try { fd = openSync(own, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600) } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== 'EEXIST' || !lstatSync(own).isFile()) throw error
  } finally { if (fd !== undefined) closeSync(fd) }
  const prefix = `${basename(file).replace(/\.json$/, '')}.`
  for (const name of readdirSync(dir)) {
    if (name.startsWith(prefix) && MARK.test(name) && name.length === prefix.length + 70 && join(dir, name) !== own) rmSync(join(dir, name), { force: true })
  }
  writeWhole(file, list)
}

/** Writes [value] to [file] as one rename, mode 600: a reader sees a whole old file or a whole new one, never a part. */
function writeWhole(file: string, value: unknown): void {
  const temporary = `${file}.${randomUUID()}.tmp`
  try {
    writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx' })
    renameSync(temporary, file)
  } catch (error) {
    rmSync(temporary, { force: true })
    throw error
  }
}

/**
 * Whether the Buddy folder [root] is still locked by the guard of a release before #2832: its guard script, and the local
 * settings that run it, naming it by this folder's own path, which no commit can know (security review 2 of #2832). A Buddy
 * launched then keeps running that guard until it starts again (lib/swarmSkills.ts removes the lock at its next launch).
 */
export function heldByOldGuard(root: string): boolean {
  const guard = join(root, '.claude', 'buddy-guard.mjs'), settings = join(root, '.claude', 'settings.local.json')
  try {
    const plain = (path: string) => { const stat = lstatSync(path); return stat.isFile() && !stat.isSymbolicLink() }
    return plain(guard) && plain(settings) && readFileSync(settings, 'utf8').includes(guard)
  } catch { return false }
}

/** At most as many entries as the guard before #2832 kept: ten messages' worth of files, and as many links. */
const MAX_FILES = 100, MAX_LINKS = 50
/** A download's limit (superTabs/attachments.ts): no larger file is listed. */
const MAX_BYTES = 256 * 1024 * 1024

/** [path] as a listed file: one regular file with no other name, at most a download's size, by its device, inode, size and
 *  the SHA-256 of its bytes, all read from the one file opened (never through a link); null for anything else. What the
 *  guard before #2832 checks again when the Buddy opens it (security reviews 1 and 2 of #2248). */
function listedFile(path: string, at: number): ListedFile | null {
  let fd: number | undefined
  try {
    const named = lstatSync(path, { bigint: true })
    if (!named.isFile() || named.nlink !== 1n || named.size > MAX_BYTES) return null
    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
    const stat = fstatSync(fd, { bigint: true })
    if (!stat.isFile() || stat.nlink !== 1n || stat.dev !== named.dev || stat.ino !== named.ino || stat.size > MAX_BYTES) return null
    // No more than the size it opened at: a file still being written to is not read on.
    const hash = createHash('sha256'), chunk = Buffer.alloc(64 * 1024)
    let total = 0n
    for (let read; (read = readSync(fd, chunk, 0, chunk.length, null)) > 0;) {
      total += BigInt(read)
      if (total > stat.size) return null
      hash.update(chunk.subarray(0, read))
    }
    return { path, dev: String(stat.dev), ino: String(stat.ino), size: String(stat.size), sha256: hash.digest('hex'), at }
  } catch { return null } finally { if (fd !== undefined) closeSync(fd) }
}

/**
 * Lists for a Buddy session still running the guard of a release before #2832 (`heldByOldGuard`) the files and Artifact
 * links its own person sent it in their own Buddy chat, as that release's host did (task #3159: once #2832 stopped listing,
 * that guard refused every screenshot Scholes sent his Buddy). The host decides whose a message is (superTabs/host.ts); this
 * lists only files Harness downloaded into paste-drops, each by its exact path, device, inode, size and SHA-256, which the
 * guard checks again when the Buddy opens it. Throws when it cannot write, so the host tries the delivery again.
 * Remove after 2026-12-04, with the older saved mode in engines/claude/launch.ts, once every such Buddy has started again.
 */
export function listSentToOldGuard(reads: BuddyReads, sent: { session: string; files: readonly string[]; links: readonly string[] },
  now = Date.now(), drops: string = PASTE_DROPS_DIR): void {
  const files = sent.files.flatMap(path => {
    const file = dirname(path) === drops ? listedFile(path, now) : null
    return file ? [file] : []
  })
  const links = sent.links.flatMap((url): ListedLink[] => artifactLink(url) === url ? [{ url, at: now }] : [])
  if (!files.length && !links.length) return
  mkdirSync(dirname(reads.file), { recursive: true, mode: 0o700 })
  sweep(dirname(reads.file), now)
  const held = heldList(reads.file, sent.session, now)
  writeList(reads.file, sent.session, { ...held,
    files: [...(held.files ?? []).filter(entry => !files.some(file => file.path === entry.path)), ...files].slice(-MAX_FILES),
    links: [...(held.links ?? []).filter(entry => !links.some(link => link.url === entry.url)), ...links].slice(-MAX_LINKS) })
}

/**
 * Grants a Buddy session its owner's presence, or takes it back ([wide]), in its list ([reads]). The
 * host decides at each of its person's own messages: theirs, in their own Buddy chat, on their own machine, and the account
 * signed in on this machine (superTabs/host.ts). Throws when it cannot write, so the host tries the delivery again.
 */
export function grantBuddyWide(reads: BuddyReads, input: { session: string; wide: false } | { session: string; wide: true; account: string; launch: string },
  now = Date.now()): void {
  const wide: Grant | false = input.wide ? { session: input.session, account: input.account, launch: input.launch, at: now } : false
  mkdirSync(dirname(reads.file), { recursive: true, mode: 0o700 })
  sweep(dirname(reads.file), now)
  writeList(reads.file, input.session, { ...heldList(reads.file, input.session, now), wide })
}

/** How long a grant holds after its person's last message. */
export const BUDDY_GRANT_MS = 60 * 60 * 1000

/**
 * Whether the Buddy session whose list is [reads], launched in [folder], holds its person's grant now (messages/service.ts,
 * #2626). The host wrote it at its person's last message, theirs,
 * in their own Buddy chat, signed in on this machine; it holds for this launch, the account signed in here now, and an
 * hour. A list, launch file or account file that cannot be read is no grant.
 */
export function buddyGrantLive(reads: BuddyReads, folder: string, now = Date.now(), accountFile: string = buddyAccountFile()): boolean {
  try {
    const list = JSON.parse(readFileSync(reads.file, 'utf8')) as { session?: unknown; wide?: unknown }
    const grant = list.wide as Partial<Grant> | false | undefined
    const launch = buddyLaunchOf(folder)
    if (!grant || typeof grant !== 'object' || typeof list.session !== 'string' || grant.session !== list.session || !launch || grant.launch !== launch) return false
    const account = (JSON.parse(readFileSync(accountFile, 'utf8')) as { accountId?: unknown }).accountId
    const age = now - Number(grant.at)
    return typeof account === 'string' && account.length > 0 && grant.account === account && Number.isFinite(age) && age > -60_000 && age < BUDDY_GRANT_MS
  } catch { return false }
}

/** Takes back the grant in [reads]'s list, whoever's session it names: at each launch (delta reviews of #2310). */
export function revokeBuddyWide(reads: BuddyReads): void {
  let session: unknown
  try { session = (JSON.parse(readFileSync(reads.file, 'utf8')) as { session?: unknown }).session } catch { return }
  if (typeof session === 'string') writeList(reads.file, session, { ...heldList(reads.file, session), wide: false })
}

export { buddyAccountFile, writeBuddyAccount } from './buddyAccount.js'

/** Where a Buddy's launch keeps its launch id in its folder, and what it says there now. */
export const buddyLaunchFile = (folder: string): string => join(folder, '.claude', 'buddy-launch')
export function buddyLaunchOf(folder: string): string | null {
  try { return readFileSync(buddyLaunchFile(folder), 'utf8').trim() || null } catch { return null }
}

/**
 * Deletes the lists of [session], once the Swarm has ended it: its Buddy removed, its person gone from the Swarm, or its
 * chat purged with its project (Lead, 10-30). A session no longer running here is found too. Its own lists are those its
 * mark is beside (`markOf`), unless another session has listed under the same key since, and, beside no mark of its own,
 * those that name it (a list written before lists were marked). Nothing else is touched or holds its end back: another
 * session's list, or one that names no session beside no mark, which the host never writes and the day's sweep removes.
 * Follow-up to #2248 (Lead, 10-30): one list that could not be read held back the end of every Buddy on the machine. So
 * a list is read only for the session it names: one that cannot be read names none. Its own is removed unread, by its
 * mark; another session's is skipped, and is that session's to remove.
 *
 * What it cannot finish throws, so the host tries again and does not acknowledge the end meanwhile (re-check 2 of #2248):
 * an own list it cannot delete (a folder it cannot write to), which it empties in place where it can, needing only the
 * file, so it grants nothing meanwhile, keeping that list's mark and its session so the next try finds it; and a
 * mark it cannot delete. A list that went between the folder's read and its own counts as gone.
 *
 * It fails by fixed codes alone (`SentListsError`), never with the error it caught: the host logs what it failed with, and
 * a filesystem error's message names its path, in the person's home (follow-up to #2389's security re-check 2).
 */
export function forgetBuddyReads(session: string, dir = listsDir()): void {
  let names: string[]
  try { names = readdirSync(dir) } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
    throw new SentListsError(['SENT_LISTS_UNREAD'])
  }
  const own = `.${sha256(session)}.owner`
  const marked = new Set(names.filter(name => name.endsWith(own)).map(name => `${name.slice(0, -own.length)}.json`))
  const kept = new Set<string>()
  const failed = new Set<SentListsFailure>()
  // Only a list's own name: a .tmp is a write not yet renamed, which no guard reads.
  for (const name of names) {
    if (!name.endsWith('.json')) continue
    const file = join(dir, name)
    let text: string | undefined, unreadable = false
    try { text = readFileSync(file, 'utf8') } catch (error) { unreadable = (error as NodeJS.ErrnoException).code !== 'ENOENT' }
    let named: unknown
    try { named = text === undefined ? undefined : (JSON.parse(text) as { session?: unknown } | null)?.session } catch { /* not JSON: it names no session */ }
    if (!marked.has(name)) {
      // Not its own by mark. One it cannot read is another session's to remove when that session's mark is beside it, and
      // otherwise whose it is cannot be told: kept, and the end fails so it is tried again, as before marks (review of #2261).
      if (unreadable) {
        const base = `${name.slice(0, -'.json'.length)}.`
        if (!names.some(other => other.startsWith(base) && MARK.test(other))) failed.add('SENT_LIST_UNREAD')
        continue
      }
      if (named !== session) continue
    } else if (typeof named === 'string' && named !== session) continue
    try { rmSync(file, { force: true }) } catch {
      const empty: List = { version: 1, session }
      try { writeFileSync(file, `${JSON.stringify(empty)}\n`) } catch { /* neither: the host's next try is all that is left */ }
      kept.add(name)
      failed.add('SENT_LIST_KEPT')
    }
  }
  for (const name of names) {
    if (!name.endsWith(own) || kept.has(`${name.slice(0, -own.length)}.json`)) continue
    try { rmSync(join(dir, name), { force: true }) } catch { failed.add('SENT_LIST_MARK_KEPT') }
  }
  if (failed.size) throw new SentListsError(SENT_LISTS_FAILURES.filter(code => failed.has(code)))
}

/** What kept an ended session's lists from all going, in the order they are named: its lists folder could not be read; a list
 *  whose session could not be told could not be read, and was kept; one of its own lists could not be deleted, and was emptied
 *  where it could be; or the mark beside one could not be deleted. */
const SENT_LISTS_FAILURES = ['SENT_LISTS_UNREAD', 'SENT_LIST_UNREAD', 'SENT_LIST_KEPT', 'SENT_LIST_MARK_KEPT'] as const
export type SentListsFailure = typeof SENT_LISTS_FAILURES[number]

/** `forgetBuddyReads`'s failure: its codes, each once, and nothing of the errors behind them, whose messages name paths. */
export class SentListsError extends Error {
  constructor(readonly codes: readonly SentListsFailure[]) {
    super(codes.join(', '))
    this.name = 'SentListsError'
  }
}

/**
 * Whose a Buddy's folder is, as the start that made it found (security review 2 of #2832). A Buddy runs with its owner's full
 * rights, and a relaunch (a restart, a model switch, a move) never passes the start's own-machine check (superTabs/start.ts
 * buddyOnOwnMachine). So that start records here, by the folder's name (its worktree named for the start, or its folder of
 * project copies), the owner it checked, before anything launches; every launch of a Buddy then requires that record
 * (lib/swarmSkills.ts). A Buddy saved before this record existed has none, and waits for its owner to start it again.
 * In Harness's data folder, never the Buddy's own folder, which it can write. One small file per Buddy start, removed with
 * the data folder; a start's folder name is never reused.
 */
export const buddyOwnerFile = (dataDir: string, leaf: string): string =>
  join(dataDir, 'buddy-owners', createHash('sha256').update(leaf).digest('hex').slice(0, 32))
export function markBuddyOwner(leaf: string, personId: string, dataDir: string = env.ADAPTER_DATA_DIR): void {
  const file = buddyOwnerFile(dataDir, leaf)
  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
  writeFileSync(file, `${JSON.stringify({ personId })}\n`, { mode: 0o600 })
}
/** The owner recorded for the Buddy folder [root]: by its name, or its name before a -2, -3 a taken one got
 *  (lib/gitProject.ts). Null when none was recorded or it cannot be read. */
export function buddyOwnerOf(root: string, dataDir: string = env.ADAPTER_DATA_DIR): string | null {
  const name = basename(root)
  for (const leaf of new Set([name, name.replace(/-\d+$/, '')])) {
    try {
      const personId = (JSON.parse(readFileSync(buddyOwnerFile(dataDir, leaf), 'utf8')) as { personId?: unknown }).personId
      if (typeof personId === 'string' && personId) return personId
    } catch { /* none for this name */ }
  }
  return null
}
/** The account the host last read as signed in here (lib/buddyAccount.ts), or null before it has read one. */
export function signedInAccount(file: string = buddyAccountFile()): string | null {
  try {
    const accountId = (JSON.parse(readFileSync(file, 'utf8')) as { accountId?: unknown }).accountId
    return typeof accountId === 'string' && accountId ? accountId : null
  } catch { return null }
}