Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.3 KB
Raw Blame
/**
 * Agent workspace format — the `agent.json` manifest and the machine-local
 * install receipt.
 *
 * `agent.json` is the ladder contract (docs/designs/AGENT_BOOTSTRAP_DESIGN.md):
 * any consumer (the desktop bootstrap, a hosted mount) validates a workspace
 * against this manifest. `format_version: 1` is PROVISIONAL — consumers must
 * tolerate unknown fields; a breaking layout change bumps the version with a
 * migration note.
 *
 * Two identity artifacts, deliberately distinct [CX2-1, CX2-12]:
 *  - `agent.json` travels IN the repo. `initialized: false` marks a template
 *    clone that has never been bootstrapped; `bootstrap render` flips it true
 *    atomically. Presence alone can NEVER discriminate a template clone from a
 *    machine-two clone — the sentinel does.
 *  - The install receipt lives OUTSIDE the repo (under the gbrain home) and
 *    proves that THIS MACHINE ran bootstrap. Uninstall is keyed to the receipt,
 *    never to the repo manifest, because template/attach clones inherit the
 *    manifest but not the receipt.
 */

import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';

export const FORMAT_VERSION = 1;
export const AGENT_MANIFEST_FILENAME = 'agent.json';

export interface AgentManifest {
  format_version: number;
  /** false in the published template repo; render flips it true atomically. */
  initialized: boolean;
  agent_name: string;
  /** gbrain version that created/last-rendered this workspace. */
  created_by: string;
  /** ISO date of first successful render. Canonical placeholder in templates [CX2-14]. */
  created_at: string;
  /** Source id this workspace's brain/ dir registers as. */
  source_id: string;
  /** Registered entry surfaces (informational). */
  surfaces?: string[];
  /** Tolerated, preserved, round-tripped: unknown fields from newer writers. */
  [key: string]: unknown;
}

/** Canonical placeholder values used by the template-repo generator so two
 * independent renders are byte-identical [CX2-14]. */
export const TEMPLATE_PLACEHOLDER_MANIFEST: AgentManifest = {
  format_version: FORMAT_VERSION,
  initialized: false,
  agent_name: '{{AGENT_NAME}}',
  created_by: 'template',
  created_at: '1970-01-01T00:00:00.000Z',
  source_id: 'workspace',
};

export type ManifestState =
  | { state: 'absent' }
  | { state: 'invalid'; reason: string }
  | { state: 'template'; manifest: AgentManifest }
  | { state: 'initialized'; manifest: AgentManifest }
  | { state: 'newer_format'; manifest: AgentManifest };

export function manifestPath(workspaceDir: string): string {
  return join(workspaceDir, AGENT_MANIFEST_FILENAME);
}

/**
 * Read + classify a workspace manifest. Never throws: the callers (attach,
 * render, uninstall, verify) branch on the state and must produce
 * agent-readable errors, not stack traces.
 */
export function readManifest(workspaceDir: string): ManifestState {
  const path = manifestPath(workspaceDir);
  if (!existsSync(path)) return { state: 'absent' };
  let raw: string;
  try {
    raw = readFileSync(path, 'utf8');
  } catch (e) {
    return { state: 'invalid', reason: `unreadable: ${(e as Error).message}` };
  }
  if (raw.includes('<<<<<<<') || raw.includes('>>>>>>>')) {
    return { state: 'invalid', reason: 'contains git conflict markers — resolve the merge in agent.json first' };
  }
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch (e) {
    return { state: 'invalid', reason: `not valid JSON: ${(e as Error).message}` };
  }
  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
    return { state: 'invalid', reason: 'manifest must be a JSON object' };
  }
  const m = parsed as Record<string, unknown>;
  if (typeof m.format_version !== 'number') {
    return { state: 'invalid', reason: 'missing numeric format_version' };
  }
  const manifest = m as unknown as AgentManifest;
  if (manifest.format_version > FORMAT_VERSION) {
    return { state: 'newer_format', manifest };
  }
  if (manifest.initialized !== true) {
    return { state: 'template', manifest };
  }
  return { state: 'initialized', manifest };
}

/** Atomic write (tmp + rename) — a killed bootstrap never leaves a torn manifest. */
export function writeManifest(workspaceDir: string, manifest: AgentManifest): void {
  const path = manifestPath(workspaceDir);
  const tmp = `${path}.tmp-${process.pid}`;
  writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
  renameSync(tmp, path);
}

// ---------------------------------------------------------------------------
// Machine-local install receipt [CX2-12]
// ---------------------------------------------------------------------------

export interface InstallReceipt {
  receipt_version: 1;
  workspace_dir: string;
  source_id: string;
  agent_name: string;
  created_at: string;
  created_by: string;
  /** True when bootstrap ran `gbrain init` itself (vs adopting a pre-existing
   * brain). Uninstall may only offer --delete-brain when this is true [G2]. */
  brain_created_by_bootstrap: boolean;
  /** Absolute paths bootstrap created OUTSIDE the workspace (hook wiring,
   * corpus dir, …). Uninstall removes exactly these, nothing else. */
  created_paths: string[];
  /** Host registrations bootstrap performed (for marker-keyed removal). */
  registrations: Array<{ host: 'claude-code' | 'codex' | 'opencode'; scope: string; detail?: string }>;
  /**
   * Private-repo URL, recorded by `bootstrap repo` ONLY after a successful
   * push (repo.ts recordRepoInReceipt). Optional: absent until the repo phase
   * completes. Typed here so consumers (bootstrap/status.ts, backup/coverage)
   * stop re-declaring it as an inline cast.
   */
  repo_url?: string;
}

export function receiptPath(gbrainHomeDir: string): string {
  return join(gbrainHomeDir, 'bootstrap', 'receipt.json');
}

export function readReceipt(gbrainHomeDir: string): InstallReceipt | null {
  const path = receiptPath(gbrainHomeDir);
  if (!existsSync(path)) return null;
  try {
    const parsed = JSON.parse(readFileSync(path, 'utf8')) as InstallReceipt;
    return parsed.receipt_version === 1 ? parsed : null;
  } catch {
    return null;
  }
}

/** Discriminated receipt state — writers must not treat "newer" or "invalid"
 * the same as "absent" (silently clobbering created_paths/registrations
 * strands uninstall) [CX2-12]. */
export type ReceiptReadState =
  | { state: 'absent' }
  | { state: 'ok'; receipt: InstallReceipt }
  | { state: 'newer'; receiptVersion: number }
  | { state: 'invalid' };

export function readReceiptState(gbrainHomeDir: string): ReceiptReadState {
  const path = receiptPath(gbrainHomeDir);
  if (!existsSync(path)) return { state: 'absent' };
  try {
    const parsed = JSON.parse(readFileSync(path, 'utf8')) as InstallReceipt;
    if (parsed.receipt_version === 1) return { state: 'ok', receipt: parsed };
    if (typeof parsed.receipt_version === 'number' && parsed.receipt_version > 1) {
      return { state: 'newer', receiptVersion: parsed.receipt_version };
    }
    return { state: 'invalid' };
  } catch {
    return { state: 'invalid' };
  }
}

/**
 * Pre-write guard every receipt WRITER runs before overwriting: a
 * newer-format receipt (written by a newer gbrain) refuses with an
 * upgrade-first error; an unreadable receipt is backed up loudly (never
 * silently discarded) so `created_paths`/`registrations` remain recoverable.
 * Returns the backup path when an invalid receipt was moved aside.
 */
export function guardReceiptOverwrite(gbrainHomeDir: string): { brokenBackupPath?: string } {
  const state = readReceiptState(gbrainHomeDir);
  if (state.state === 'newer') {
    throw new Error(
      `the install receipt at ${receiptPath(gbrainHomeDir)} was written by a newer gbrain ` +
        `(receipt_version ${state.receiptVersion}) — upgrade gbrain before re-running bootstrap.`,
    );
  }
  if (state.state === 'invalid') {
    const path = receiptPath(gbrainHomeDir);
    const backup = `${path}.broken-${Date.now()}`;
    renameSync(path, backup);
    return { brokenBackupPath: backup };
  }
  return {};
}

export function writeReceipt(gbrainHomeDir: string, receipt: InstallReceipt): void {
  const path = receiptPath(gbrainHomeDir);
  const tmp = `${path}.tmp-${process.pid}`;
  writeFileSync(tmp, `${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
  renameSync(tmp, path);
}

// ---------------------------------------------------------------------------
// Machine-level harness receipt (#4043 `gbrain bootstrap harness`)
//
// A SEPARATE file from receipt.json on purpose: the install receipt is
// workspace-keyed (workspace_dir/source_id/agent_name are required — a
// harness-only box has none of those), and the two lifecycles differ
// (workspace uninstall vs harness --remove). Same CX2-12 discipline: typed
// read states, newer-format refusal, broken-file backup-aside, atomic write.
//
// WRITE-AHEAD contract [F1/C7]: the apply path persists this receipt right
// after minting — every planned target starts `pending` and flips to
// `confirmed` (or records its failure) as the wiring lands, and
// `token.previous_ids` carries every not-yet-revoked prior token until rotation
// completes. A crash at any step leaves a receipt --remove can consume.
// ---------------------------------------------------------------------------

// 'instructions' (the ambient-writeback managed block) is ADDITIVE under
// harness_receipt_version 1 — a version bump would make older binaries refuse
// the whole receipt (bricking --remove of EVERY target), so instead older
// binaries simply won't unwire this kind on --remove: a documented limitation.
export type HarnessTargetKind = 'mcp' | 'permission' | 'hooks' | 'instructions';
export type HarnessTargetState = 'pending' | 'confirmed' | 'failed';

export interface HarnessTarget {
  host: 'claude-code' | 'codex' | 'opencode';
  kind: HarnessTargetKind;
  state: HarnessTargetState;
  /** user scope or a --project dir (hooks); user for mcp/permission. */
  scope: string;
  /** Settings/config file the target writes (absent for CLI-mediated mcp). */
  path?: string;
  /** MCP server name (mcp targets). */
  name?: string;
  /** permissions.allow entry (permission targets). */
  entry?: string;
  /** Hook marker value (hooks targets). */
  marker?: string;
  /** Absolute gbrain launcher rendered into the hook commands (hooks targets;
   * absent on receipts written before it was recorded). */
  launcher?: string;
  /** Seat label rendered into the hook commands, '' for none (hooks targets;
   * absent on older receipts). */
  seat?: string;
  /** Write mechanism note, e.g. 'toml-block' vs 'claude-cli'. */
  mechanism?: string;
  /** One-line failure reason when state === 'failed'. */
  error?: string;
}

export interface HarnessReceipt {
  harness_receipt_version: 1;
  created_at: string;
  created_by: string;
  /** Normalized MCP endpoint the box is wired to. */
  url: string;
  /** Engine reported by /health at apply time (postgres → degraded per-turn). */
  engine?: string;
  /** Serve version at apply time — --status re-checks for skew [F7]. */
  serve_version?: string;
  source_id: string;
  /** False when the hooks carry NO `GBRAIN_SOURCE` pin (a live PGLite serve hid
   * which source it resolves, the --token lane proceeded unpinned and `source_id`
   * records the federated floor `default`). Absent = pinned to `source_id`. */
  source_pinned?: false;
  skills_policy?: 'follow' | 'memory-only';
  harness_tokens?: Partial<Record<HarnessTarget['host'], { id?: string; minted: boolean; name: string }>>;
  shared_skills?: Array<{
    host: HarnessTarget['host'];
    root: string;
    name: string;
    url: string;
    token_id?: string;
    status: string;
    reason?: string;
    retained_files?: string[];
  }>;
  token: {
    name: string;
    /** Row id — the only safe revocation key. */
    id?: string;
    /** False when --token supplied a pre-minted token (never revoke those). */
    minted: boolean;
    /**
     * EVERY prior minted-token id still awaiting revocation (mint-first
     * rotation [C7]). An array, not a slot [X4]: a failed rotation must not
     * forget the token before last, and a --token re-run must keep carrying
     * ids minted by earlier runs until they are revoked.
     */
    previous_ids?: string[];
  };
  targets: HarnessTarget[];
  /** #6661: a --token run on PGLite wired every target while no serve answered, so nothing verified the
   * wiring yet. Cleared by the next run whose smoke passes (each run writes a fresh receipt). */
  verify_pending?: { since: string; reason: 'serve_unreachable' };
}

export function harnessReceiptPath(gbrainHomeDir: string): string {
  return join(gbrainHomeDir, 'bootstrap', 'harness.json');
}

export type HarnessReceiptReadState =
  | { state: 'absent' }
  | { state: 'ok'; receipt: HarnessReceipt }
  | { state: 'newer'; receiptVersion: number }
  | { state: 'invalid' };

export function readHarnessReceiptState(gbrainHomeDir: string): HarnessReceiptReadState {
  const path = harnessReceiptPath(gbrainHomeDir);
  if (!existsSync(path)) return { state: 'absent' };
  try {
    const parsed = JSON.parse(readFileSync(path, 'utf8')) as HarnessReceipt;
    if (parsed.harness_receipt_version === 1) {
      // Version alone is not enough: every consumer dereferences targets[]
      // and token.name unchecked, so a hand-damaged version-1 receipt must
      // take the designed 'invalid' → backup-aside path, not a TypeError.
      const shapeOk =
        Array.isArray(parsed.targets) &&
        typeof parsed.token === 'object' &&
        parsed.token !== null &&
        typeof parsed.token.name === 'string' &&
        typeof parsed.url === 'string' &&
        (parsed.skills_policy === undefined || parsed.skills_policy === 'follow' || parsed.skills_policy === 'memory-only') &&
        (parsed.harness_tokens === undefined || (parsed.harness_tokens !== null && typeof parsed.harness_tokens === 'object' &&
          !Array.isArray(parsed.harness_tokens) && Object.entries(parsed.harness_tokens).every(([host, token]) =>
            ['claude-code', 'codex', 'opencode'].includes(host) && token && typeof token.name === 'string' &&
            typeof token.minted === 'boolean' && (token.id === undefined || typeof token.id === 'string')))) &&
        (parsed.shared_skills === undefined || (Array.isArray(parsed.shared_skills) && parsed.shared_skills.every(entry =>
          entry && ['claude-code', 'codex', 'opencode'].includes(entry.host) && typeof entry.root === 'string' &&
          typeof entry.url === 'string' && typeof entry.name === 'string' && typeof entry.status === 'string')));
      return shapeOk ? { state: 'ok', receipt: parsed } : { state: 'invalid' };
    }
    if (typeof parsed.harness_receipt_version === 'number' && parsed.harness_receipt_version > 1) {
      return { state: 'newer', receiptVersion: parsed.harness_receipt_version };
    }
    return { state: 'invalid' };
  } catch {
    return { state: 'invalid' };
  }
}

/**
 * Pre-write guard (mirror of guardReceiptOverwrite): newer-format refuses
 * with an upgrade-first error; an unreadable receipt is backed up loudly so
 * the recorded targets remain recoverable.
 */
export function guardHarnessReceiptOverwrite(gbrainHomeDir: string): { brokenBackupPath?: string } {
  const state = readHarnessReceiptState(gbrainHomeDir);
  if (state.state === 'newer') {
    throw new Error(
      `the harness receipt at ${harnessReceiptPath(gbrainHomeDir)} was written by a newer gbrain ` +
        `(harness_receipt_version ${state.receiptVersion}) — upgrade gbrain before re-running bootstrap harness.`,
    );
  }
  if (state.state === 'invalid') {
    const path = harnessReceiptPath(gbrainHomeDir);
    const backup = `${path}.broken-${Date.now()}`;
    renameSync(path, backup);
    return { brokenBackupPath: backup };
  }
  return {};
}

/** Atomic write, 0600 (records wiring topology + token ids, not plaintext). */
export function writeHarnessReceipt(gbrainHomeDir: string, receipt: HarnessReceipt): void {
  const path = harnessReceiptPath(gbrainHomeDir);
  mkdirSync(dirname(path), { recursive: true });
  const tmp = `${path}.tmp-${process.pid}`;
  writeFileSync(tmp, `${JSON.stringify(receipt, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
  renameSync(tmp, path);
}

/** Consume (delete) the harness receipt after a fully successful --remove. */
export function deleteHarnessReceipt(gbrainHomeDir: string): void {
  const path = harnessReceiptPath(gbrainHomeDir);
  if (existsSync(path)) rmSync(path);
}