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.

21.7 KB
Raw Blame
/**
 * Connected services, given to each agent as an MCP server on the local bridge. Agent configs hold only the command of a stdio
 * shim to the bridge's 0600 socket or, on Windows, its proven pipe (mcpShimSource.ts), or where neither can be (a folder too long for a socket) a 127.0.0.1
 * address with this user's capability in it; the bridge adds the credential to each request (Grid's design). A renewed token
 * needs no config change, and an agent already running keeps working.
 *
 * Only entries Harness made are changed or removed: their names are recorded in projections.json, so a
 * server the person added by hand keeps its name and contents. A config that is not plain JSON (comments)
 * is left exactly as it is. Configs are replaced through a symlink, as engines/kit/folderTrust.ts does.
 */
import { randomBytes } from 'node:crypto'
import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync, mkdirSync, statSync } from 'node:fs'
import { homedir } from 'node:os'
import { delimiter, dirname, isAbsolute, join, resolve, sep } from 'node:path'
import { defaultCodexHome, listCodexProfiles } from '../codexProfiles.js'
import { managedNodePath } from '../nodeRuntime.js'
import { MCP_SHIM_SOURCE } from './mcpShimSource.js'
import { CODE, locked, writePrivate, type Store } from './store.js'
import { transport } from './rest.js'
import { socketPathIn } from '../localSocket.js'
import { isPipePath } from '../windows/pipeAuth.js'
import type { PipeTarget } from '../windows/pipeClient.js'
import { BRIDGE_PIPE_FILE } from './bridge.js'

const validPort = (port: unknown): port is number => typeof port === 'number' && Number.isInteger(port) && port >= 0 && port < 65536

/**
 * The bridge's address, which every agent entry names: 51793, or the port [vault] saved because another account held
 * that one (saveBridgePort). HARNESS_CONNECTIONS_PORT fixes it (tests).
 */
export function bridgePort(env: NodeJS.ProcessEnv = process.env, vault?: Store): number {
  if (env.HARNESS_CONNECTIONS_PORT !== undefined) {
    const port = Number(env.HARNESS_CONNECTIONS_PORT)
    return validPort(port) ? port : 51793
  }
  const saved = vault?.file('bridge.json').port
  return validPort(saved) && saved > 0 ? saved : 51793
}

/**
 * Remember the port the bridge moved to. A Team account's daemon starts at boot and this user's only at login, so that
 * account can hold 51793 before this bridge ever starts (audit H1), and it then would hear every agent's tool calls.
 */
export function saveBridgePort(vault: Store, port: number): void {
  locked(vault.root, () => { writePrivate(join(vault.root, 'bridge.json'), { ...vault.file('bridge.json'), port }) })
}

/** The capability in every bridge address, so only this user's agents can use it. */
export function bridgeKey(vault: Store): string {
  return locked(vault.root, () => {
    const key = vault.file('bridge.json').key
    if (typeof key === 'string' && key.length >= 32) return key
    const fresh = randomBytes(32).toString('base64url')
    writePrivate(join(vault.root, 'bridge.json'), { ...vault.file('bridge.json'), key: fresh })
    return fresh
  })
}

/**
 * The capability for Harness's own calls through the bridge (its cloud agents, services/cloud.ts): a second key,
 * in `harness-key.json`, never written into an agent's configuration. The bridge's key is in every agent's MCP
 * entry, so an agent (one a page talked into it) could otherwise list the connections and spend a Devin or
 * Cursor key through the `/api/` route.
 */
export function harnessKey(vault: Store): string {
  return locked(vault.root, () => {
    const key = vault.file('harness-key.json').key
    if (typeof key === 'string' && key.length >= 32) return key
    const fresh = randomBytes(32).toString('base64url')
    writePrivate(join(vault.root, 'harness-key.json'), { ...vault.file('harness-key.json'), key: fresh })
    return fresh
  })
}

/** How long the agents' key still opens the port once its entries have moved to the shim: running agents keep the address they read. */
export const KEY_GRACE_MS = 24 * 60 * 60_000

/**
 * The agents' key where a socket can be, for the port's listener to compare against, or '' once it is retired. It has crossed the
 * port, so a holder may have heard it (audit H1). It lasts [KEY_GRACE_MS] from the first time this is asked, then goes for good.
 * Agents' entries no longer hold it; one still running from an old address answers "unknown" until it restarts.
 */
export function retireBridgeKey(vault: Store, now: number = Date.now()): string {
  const seen = vault.file('bridge.json')
  if (typeof seen.key !== 'string') return ''
  if (typeof seen.keyRetiresAt === 'number' && now < seen.keyRetiresAt) return seen.key
  return locked(vault.root, () => {
    const { key, keyRetiresAt, ...rest } = vault.file('bridge.json')
    if (typeof key !== 'string') return ''
    if (typeof keyRetiresAt === 'number' && now >= keyRetiresAt) {
      writePrivate(join(vault.root, 'bridge.json'), rest)
      return ''
    }
    if (typeof keyRetiresAt !== 'number') writePrivate(join(vault.root, 'bridge.json'), { ...rest, key, keyRetiresAt: now + KEY_GRACE_MS })
    return key
  })
}

/** Replaces Harness's own key once where a socket can be: it crossed the port until now, and from here on it never does. */
export function rotateHarnessKey(vault: Store): void {
  locked(vault.root, () => {
    if (vault.file('harness-key.json').socketOnly === true) return
    writePrivate(join(vault.root, 'harness-key.json'), { key: randomBytes(32).toString('base64url'), socketOnly: true })
  })
}

export function bridgeUrl(key: string, code: string, port = bridgePort()): string {
  return `http://127.0.0.1:${port}/${key}/${code}/mcp`
}

/** The bridge's 0600 socket for MCP clients, in the vault's private folder or its short one, or null where there is none. */
export function bridgeSocketPath(vault: Store, platform: NodeJS.Platform = process.platform): string | null {
  return platform === 'win32' ? null : socketPathIn(vault.root, 'bridge.sock')
}

/** Where the bridge records its pipe on Windows (bridge.ts `serveBridgePipe`): the shim and Harness's own route read it. */
export function bridgePipeRecord(vault: Store): string {
  return join(vault.root, BRIDGE_PIPE_FILE)
}

/**
 * Whether this account's process [pid] runs. The bridge is this account's, so a pid that answers EPERM is another account's
 * process, one that took the pid since the bridge exited and could have made a pipe of its name: no bridge.
 */
function ownProcessRuns(pid: number): boolean {
  try { process.kill(pid, 0); return true } catch { return false }
}

/**
 * The bridge's pipe and token on Windows, or null when there is nothing to dial: no record, a name that is not a local Harness
 * pipe (`isPipePath`: never another computer's), a token that is not 32 bytes, or a recorded process that no longer runs as
 * this account. Read for each request, so a bridge that restarted under a new name is followed.
 */
export function readBridgePipe(vault: Store, runs: (pid: number) => boolean = ownProcessRuns, platform: NodeJS.Platform = process.platform): PipeTarget | null {
  let record: Record<string, unknown>
  try { record = vault.file(BRIDGE_PIPE_FILE) } catch { return null }
  const { pipe, pid, token } = record
  if (typeof pipe !== 'string' || !isPipePath(pipe, platform)) return null
  if (typeof token !== 'string' || !/^[0-9a-f]{64}$/.test(token)) return null
  if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0 || !runs(pid)) return null
  return { pipe, token: Buffer.from(token, 'hex') }
}

/** How an MCP client reaches one connection. */
export type McpEntry = { url: string } | { command: string; args: string[] }

/**
 * The shim, written fresh into the vault's private folder (mcpShimSource.ts). Its node is Harness's managed one, as an agent started
 * outside Harness may have neither `harness` nor a node on its PATH. That path names a version, or this process's node where no runtime
 * is recorded: the daemon's next start writes the entries again.
 */
function writeShim(vault: Store): string {
  const path = join(vault.root, 'mcp-shim.mjs')
  mkdirSync(vault.root, { recursive: true, mode: 0o700 })
  if (!existsSync(path) || readFileSync(path, 'utf8') !== MCP_SHIM_SOURCE) {
    const staged = `${path}.${process.pid}.tmp`
    writeFileSync(staged, MCP_SHIM_SOURCE, { mode: 0o600 })
    renameSync(staged, path)
  }
  return path
}

function home(env: NodeJS.ProcessEnv): string { return env.HOME || homedir() }

function onPath(binary: string, env: NodeJS.ProcessEnv): boolean {
  const names = process.platform === 'win32' ? [binary + '.cmd', binary + '.exe', binary] : [binary]
  return (env.PATH ?? '').split(delimiter).some(dir => dir && names.some(name => existsSync(join(dir, name))))
}

/** Replace a config atomically, through a symlink, keeping its permissions. */
function replace(file: string, text: string): void {
  if (!existsSync(file)) mkdirSync(dirname(file), { recursive: true })
  const target = existsSync(file) ? realpathSync(file) : file
  const mode = existsSync(target) ? statSync(target).mode & 0o777 : 0o600
  const tmp = `${target}.harness-${process.pid}.tmp`
  writeFileSync(tmp, text, { mode })
  renameSync(tmp, target)
}

/** The real path of [path], or its absolute form where it does not exist yet. */
function real(path: string): string {
  try { return realpathSync(path) } catch { return resolve(path) }
}

/**
 * Whether the config [file] is inside the profile [folder] once symlinks are followed. A person's dotfiles in the default home
 * may be links elsewhere; a profile home is only that profile's own, and a link out of it is not written through.
 */
function within(folder: string, file: string): boolean {
  const root = real(folder)
  const target = existsSync(file) ? real(file) : join(real(dirname(file)), file.slice(dirname(file).length + 1))
  return target.startsWith(root + sep)
}

export interface Agent {
  name: string
  installed(): boolean
  /** Make `wanted` (name → how to reach it) the Harness entries; returns the names now Harness's. */
  apply(wanted: Record<string, McpEntry>, owned: string[]): string[]
}

class JsonAgent implements Agent {
  constructor(readonly name: string, private readonly binary: string, private readonly path: string,
    private readonly env: NodeJS.ProcessEnv, private readonly key: string, private readonly entry: (reach: McpEntry) => Record<string, unknown>,
    private readonly profile: string | null = null) {}

  installed(): boolean { return !!this.profile || existsSync(this.path) || onPath(this.binary, this.env) }

  apply(wanted: Record<string, McpEntry>, owned: string[]): string[] {
    if (this.profile && !within(this.profile, this.path)) return owned
    let data: Record<string, unknown> = {}
    if (existsSync(this.path)) {
      try { data = JSON.parse(readFileSync(this.path, 'utf8')) } catch { return owned }
      if (!data || typeof data !== 'object' || Array.isArray(data)) return owned
    }
    const current = data[this.key]
    if (current !== undefined && (typeof current !== 'object' || current === null || Array.isArray(current))) return owned
    const servers = { ...(current as Record<string, unknown> | undefined) }
    for (const name of owned) if (!(name in wanted)) delete servers[name]
    const result: string[] = []
    for (const [name, reach] of Object.entries(wanted)) {
      if (name in servers && !owned.includes(name)) continue // The person's own server with this name.
      servers[name] = this.entry(reach)
      result.push(name)
    }
    if (Object.keys(servers).length) data[this.key] = servers
    else delete data[this.key]
    replace(this.path, JSON.stringify(data, null, 2) + '\n')
    return result.sort()
  }
}

/** Codex's config.toml, edited as text: Harness's tables are removed whole and written again at the end. */
class CodexAgent implements Agent {
  constructor(private readonly path: string, private readonly env: NodeJS.ProcessEnv, readonly name = 'codex', private readonly profile: string | null = null) {}

  installed(): boolean { return !!this.profile || existsSync(this.path) || onPath('codex', this.env) }

  private static header(name: string): RegExp {
    const escaped = name.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')
    return new RegExp(`^\\s*\\[\\s*mcp_servers\\s*\\.\\s*(?:${escaped}|"${escaped}")\\s*(?:\\.[^\\]]*)?\\]\\s*$`)
  }

  apply(wanted: Record<string, McpEntry>, owned: string[]): string[] {
    if (this.profile && !within(this.profile, this.path)) return owned
    let lines: string[] = []
    if (existsSync(this.path)) {
      try { lines = readFileSync(this.path, 'utf8').split('\n') } catch { return owned }
      if (lines.at(-1) === '') lines.pop()
    }
    const kept: string[] = []
    let skipping = false
    for (const line of lines) {
      if (line.trimStart().startsWith('[')) skipping = owned.some(name => CodexAgent.header(name).test(line))
      if (!skipping) kept.push(line)
    }
    while (kept.length && !kept.at(-1)!.trim()) kept.pop()
    const result: string[] = []
    for (const [name, reach] of Object.entries(wanted).sort(([a], [b]) => a.localeCompare(b))) {
      if (kept.some(line => CodexAgent.header(name).test(line))) continue // The person's own server.
      // JSON's strings and arrays of them are TOML's too.
      kept.push('', `[mcp_servers.${name}]`, ...'url' in reach ? [`url = ${JSON.stringify(reach.url)}`]
        : [`command = ${JSON.stringify(reach.command)}`, `args = ${JSON.stringify(reach.args)}`])
      result.push(name)
    }
    while (kept.length && !kept[0].trim()) kept.shift()
    replace(this.path, kept.length ? kept.join('\n') + '\n' : '')
    return result
  }
}

const claudeEntry = (reach: McpEntry): Record<string, unknown> =>
  'url' in reach ? { type: 'http', url: reach.url } : { type: 'stdio', command: reach.command, args: reach.args }

const claudeFile = (env: NodeJS.ProcessEnv): string => join(env.CLAUDE_CONFIG_DIR || home(env), '.claude.json')
const codexFile = (env: NodeJS.ProcessEnv): string => join(env.CODEX_HOME || join(home(env), '.codex'), 'config.toml')

export function agents(env: NodeJS.ProcessEnv = process.env): Agent[] {
  const config = env.XDG_CONFIG_HOME || join(home(env), '.config')
  return [
    new JsonAgent('claude', 'claude', claudeFile(env), env, 'mcpServers', claudeEntry),
    new CodexAgent(codexFile(env), env),
    new JsonAgent('opencode', 'opencode', join(config, 'opencode', 'opencode.json'), env, 'mcp',
      reach => 'url' in reach ? { type: 'remote', url: reach.url, enabled: true } : { type: 'local', command: [reach.command, ...reach.args], enabled: true }),
  ]
}

let listedCodex: { key: string; at: number; folders: Set<string> } | null = null

/** The Codex profiles this machine lists (the real paths), read at most every 30 s: discovery reads shell startup files. */
function codexProfileFolders(env: NodeJS.ProcessEnv): Set<string> {
  const key = `${home(env)}\0${env.CODEX_HOME ?? ''}`
  if (!listedCodex || listedCodex.key !== key || Date.now() - listedCodex.at > 30_000) {
    const environment = Object.fromEntries(Object.entries(env).filter((entry): entry is [string, string] => typeof entry[1] === 'string'))
    listedCodex = { key, at: Date.now(), folders: new Set(listCodexProfiles([], { home: home(env), environment }).map(profile => profile.path)) }
  }
  return listedCodex.folders
}

/** Test seam: forget the Codex profiles read so far. */
export function resetProfileCache(): void { listedCodex = null }

/**
 * The agent for a Claude profile (CLAUDE_CONFIG_DIR) or Codex profile (CODEX_HOME) folder: the default homes' entries, in the
 * profile's own files. Its name carries the folder, so projections.json records what Harness wrote there apart from the default
 * home; an agent runs under the folder, so the engine counts as installed. It never writes through a link that leaves the folder.
 * Null for the default home (the default agent has it, wherever a link leads), for a folder that is not an absolute path and, with
 * [listed], for a Codex folder this machine does not list as a profile (a Claude folder is checked where the launch is asked for,
 * core/agents/launches.ts).
 */
function profileAgent(engine: 'claude' | 'codex', folder: string, env: NodeJS.ProcessEnv, listed = true): Agent | null {
  if (!isAbsolute(folder)) return null
  const name = `${engine}:${folder}`
  if (engine === 'claude') {
    if (real(folder) === real(dirname(claudeFile(env)))) return null
    return new JsonAgent(name, 'claude', join(folder, '.claude.json'), env, 'mcpServers', claudeEntry, folder)
  }
  if (real(folder) === defaultCodexHome(home(env), env)) return null
  if (listed && !codexProfileFolders(env).has(real(folder))) return null
  return new CodexAgent(join(folder, 'config.toml'), env, name, folder)
}

/**
 * The profile homes Harness has written entries into, from projections.json. A folder that is gone took its entries with it; one
 * that is no longer a profile of this machine has them taken out (`release`). Both are forgotten.
 */
function recordedProfiles(record: Record<string, unknown>, env: NodeJS.ProcessEnv): { gone: string[]; agents: Agent[]; release: Agent[] } {
  const found: { gone: string[]; agents: Agent[]; release: Agent[] } = { gone: [], agents: [], release: [] }
  for (const key of Object.keys(record)) {
    const match = /^(claude|codex):(.+)$/.exec(key)
    if (!match) continue
    const engine = match[1] as 'claude' | 'codex'
    const agent = existsSync(match[2]) ? profileAgent(engine, match[2], env) : null
    if (agent) { found.agents.push(agent); continue }
    const unlisted = existsSync(match[2]) ? profileAgent(engine, match[2], env, false) : null
    if (unlisted) found.release.push(unlisted)
    found.gone.push(key)
  }
  return found
}

type Targets = { agents: Agent[]; gone?: string[]; release?: Agent[]; remember?: string[] }

/** Give the agents in [list] exactly the connections that have MCP tools (their own, or REST served as MCP). */
function project(vault: Store, env: NodeJS.ProcessEnv, list: (record: Record<string, unknown>) => Targets, waitMs?: number,
  platform: NodeJS.Platform = process.platform): Record<string, string[]> {
  const codes = Object.entries(vault.tokens()).filter(([code, token]) => transport(token) !== 'none' && CODE.test(code)).map(([code]) => code)
  // On Windows the bridge's pipe, named in its record (task #2162); elsewhere its socket; the port only where neither can be.
  const socket = bridgeSocketPath(vault, platform)
  const local: string[] | null = socket ? ['--socket', socket] : platform === 'win32' ? ['--pipe', bridgePipeRecord(vault)] : null
  const shim = codes.length && local ? writeShim(vault) : ''
  const key = codes.length && !local ? bridgeKey(vault) : ''
  const wanted = Object.fromEntries(codes.map((code): [string, McpEntry] => [code, local
    ? { command: managedNodePath(), args: [shim, ...local, code] }
    : { url: bridgeUrl(key, code, bridgePort(env, vault)) }]))
  return locked(vault.root, () => {
    const record = vault.file('projections.json') as Record<string, unknown>
    const { agents: targets, gone = [], release = [], remember = [] } = list(record)
    const ownedBy = (agent: Agent): string[] => {
      const raw = record[agent.name]
      return Array.isArray(raw) ? raw.filter((name): name is string => typeof name === 'string' && CODE.test(name)) : []
    }
    // One agent whose config cannot be written (a read-only home) leaves the others, and what was recorded, as they are.
    const attempt = (agent: Agent, work: () => void): void => {
      try { work() } catch (error) { console.warn(`[connections] could not update ${agent.name}: ${error instanceof Error ? error.message : String(error)}`) }
    }
    const changed: Record<string, string[]> = {}
    for (const agent of targets) {
      const owned = ownedBy(agent)
      if ((!owned.length && !codes.length) || !agent.installed()) continue
      attempt(agent, () => { changed[agent.name] = agent.apply(wanted, owned) })
    }
    for (const agent of release) if (ownedBy(agent).length) attempt(agent, () => { agent.apply({}, ownedBy(agent)) })
    const kept = Object.fromEntries(Object.entries(record).filter(([name]) => !gone.includes(name)))
    // A profile home with nothing to write yet is still recorded, so a connection made later reaches it.
    for (const name of remember) if (!(name in changed) && !(name in kept)) kept[name] = []
    writePrivate(join(vault.root, 'projections.json'), { ...kept, ...changed })
    return changed
  }, waitMs)
}

/**
 * Give every installed agent exactly the connections that have MCP tools, in its default home and in each profile home an agent
 * was launched under (syncProfileHome), so a connection made or removed later reaches a running profile's config too.
 */
export function sync(vault: Store, env: NodeJS.ProcessEnv = process.env, list?: Agent[], platform: NodeJS.Platform = process.platform): Record<string, string[]> {
  return project(vault, env, record => {
    if (list) return { agents: list }
    const profiles = recordedProfiles(record, env)
    return { agents: [...agents(env), ...profiles.agents], gone: profiles.gone, release: profiles.release }
  }, undefined, platform)
}

/**
 * Give the agent about to run under [folder] (its Claude profile or Codex profile) the same entries the default home has. The
 * default home, a Codex folder this machine does not list as a profile and a link out of the folder change nothing. Called as an
 * agent launches, so it waits for the vault's lock for seconds, not the half minute a connection change may.
 */
export function syncProfileHome(vault: Store, engine: 'claude' | 'codex', folder: string, env: NodeJS.ProcessEnv = process.env): string[] {
  const agent = profileAgent(engine, folder, env)
  if (!agent) return []
  // Desktop's "Add Claude account" names the folder before Claude Code makes it.
  if (engine === 'claude') mkdirSync(folder, { recursive: true, mode: 0o700 })
  return project(vault, env, () => ({ agents: [agent], remember: [agent.name] }), 3_000)[agent.name] ?? []
}