Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
27.0 KB
Raw Blame
/**
 * host-specs.ts — dated spec-targets for external host formats
 * (agent-bootstrap plan: ENG-7, ENG-1, CX2-17).
 *
 * THE ONE MODULE that owns host-format assumptions. Every writer that
 * touches a host's config surface (settings.local.json hooks, `claude mcp
 * add` / `codex mcp add` argv) consumes the shapes exported here, and every
 * assumption is pinned to a DATED spec target with a status + references —
 * so when a host ships a breaking format change, the blast radius is one
 * TARGETS entry and the writers that import from it, not a grep across the
 * tree. (Pattern imported from the codex-as-agent plugin-spec
 * one-file-owns-format rule; see the plan's port map.)
 *
 * Verification discipline: `status: 'verified'` means the referenced
 * behavior was checked against the host's published docs (or binary) on
 * `verifiedAt`. `'provisional'` means the shape is believed-correct from
 * docs/precedent but has not been re-verified against a live host — treat a
 * provisional writer's failure as "re-verify the spec" before debugging
 * gbrain code.
 */

import { existsSync, readdirSync } from 'node:fs';
import { homedir } from 'node:os';
import { basename, dirname, join } from 'node:path';

// ── Spec-target registry [ENG-7] ────────────────────────────────────────────

export interface HostSpecTarget {
  /** Dated spec id, e.g. 'claude-code-2026-08'. */
  id: string;
  status: 'verified' | 'provisional';
  /** ISO date the referenced behavior was last checked. */
  verifiedAt: string;
  /** Docs / precedent the assumptions trace to. */
  references: string[];
  /** What this target asserts about the host, in one place. */
  note: string;
}

export const CLAUDE_CODE_SPEC_ID = 'claude-code-2026-08';
export const CODEX_SPEC_ID = 'codex-2026-08';
export const OPENCODE_SPEC_ID = 'opencode-2026-08';

export const TARGETS: Record<string, HostSpecTarget> = {
  [CLAUDE_CODE_SPEC_ID]: {
    id: CLAUDE_CODE_SPEC_ID,
    status: 'verified',
    verifiedAt: '2026-08-12',
    references: [
      'https://code.claude.com/docs/en/hooks',
      'https://code.claude.com/docs/en/hooks-guide',
      'https://code.claude.com/docs/en/settings',
    ],
    note:
      'Hook events used: SessionStart / UserPromptSubmit / Stop / SessionEnd / ' +
      'PreCompact. Hooks are written to <workspace>/.claude/settings.local.json ' +
      '(gitignored by Claude Code by default) as hooks.<Event> → [{matcher?, ' +
      'hooks: [{type:"command", command, timeout}]}] with timeout in SECONDS. ' +
      'Hook commands are shell strings (no env map) — env vars are embedded via ' +
      'an `env K=V …` prefix. Unknown properties on the command object are ' +
      'tolerated at run time, but a host rewrite of settings.json can drop them, ' +
      'so the `_gbrain` marker key is advisory and the harness lane also ' +
      'recognizes its own exact command. UserPromptSubmit context injection: stdout JSON ' +
      '{hookSpecificOutput: {hookEventName: "UserPromptSubmit", ' +
      'additionalContext}}; SessionStart plain stdout becomes context. Hook ' +
      'stdout is capped at 10000 chars — overflow is diverted to a file and ' +
      'NOT injected [ENG-1]. Transcripts live under ~/.claude/projects/ as ' +
      '.jsonl (transcript_path in the hook stdin payload). PreCompact stdin ' +
      '(verified against the published hooks reference, not live capture): the ' +
      'common fields (session_id, transcript_path, cwd, hook_event_name) plus ' +
      'trigger:"manual"|"auto" and custom_instructions (the /compact argument ' +
      'for manual, empty for auto). PreCompact stdout is never context-injected ' +
      '— only UserPromptSubmit and SessionStart stdout reach the model — and ' +
      'exit 2 blocks compaction, so the v0.45.7 banking hook must exit 0. ' +
      'SessionStart stdin carries source:"startup"|"resume"|"clear"|"compact" ' +
      '(+"fork" since Claude Code v2.1.214); source:"compact" fires after auto ' +
      'or manual compaction and is the rehydration re-entry the PreCompact ' +
      'bank serves a warm pack through. Skills: user-scope native SKILL.md ' +
      'discovery reads CLAUDE_CONFIG_DIR-else-HOME /.claude/skills ' +
      '(claudeUserSkillsDir — the harness-bridge install target, attested by ' +
      'the gstack convention + plugin lane); project-scope ' +
      '<workspace>/.claude/skills is provisional-from-docs.',
  },
  [CODEX_SPEC_ID]: {
    id: CODEX_SPEC_ID,
    status: 'verified',
    verifiedAt: '2026-08-12',
    references: [
      'docs/mcp/CODEX.md',
      'https://developers.openai.com/codex/mcp',
      'codex-cli 0.147.0 (binary serde field scan + live inline bearer_token wiring, issue #4043)',
      'codex-cli 0.149.1 (reporter 3-variant probe in issue #4574: inline bearer_token is REJECTED ' +
        'at config load for streamable_http; http_headers inline table loads on 0.147.x and 0.149.x)',
    ],
    note:
      'Local stdio MCP registration: `codex mcp add <name> [--env K=V]... -- ' +
      '<command> [args...]`, which writes [mcp_servers.<name>] into ' +
      '(CODEX_HOME || ~/.codex)/config.toml — codex resolves CODEX_HOME as ' +
      'the config dir itself. Streamable-HTTP servers are configured with ' +
      '`url` plus an inline `http_headers = { Authorization = "Bearer <t>" }` ' +
      'table or `bearer_token_env_var` — inline `bearer_token` was accepted ' +
      'by 0.147.x but is REJECTED AT CONFIG LOAD by >=0.149 (#4574, bricking ' +
      'every codex session on the machine); the http_headers shape loads on ' +
      'both. The config parser uses deny-unknown-fields, so writers must emit ' +
      'ONLY verified keys and `KEY = "value"` spacing. The CX2-17 revisit ' +
      'trigger FIRED (#4043): `codex mcp add` cannot express an inline ' +
      'credential (verified against codex-cli 0.147.0 --help), so the harness ' +
      'lane owns a managed marker-delimited TOML block (codex-toml.ts) — the ' +
      'ONE direct config.toml writer. One owner per server name: `codex mcp ' +
      'remove` rewrites config.toml wholesale and drops comments, so the ' +
      'stdio lane (runHooks) must never manage a name the harness block ' +
      'owns, and vice versa. Codex 0.147.0 also ships a real hook system ' +
      '(hooks.json; PreToolUse…SessionEnd) — bootstrap wires SessionEnd; ' +
      '`gbrain setup codex` also wires SessionStart/UserPromptSubmit, hash-owned ' +
      '(CODEX_HAS_HOOKS=true; codex-hooks.ts owns the two-file write incl. ' +
      'the config.toml trust entry, see CODEX_HOOKS_SPEC_TARGET there). ' +
      'Some codex builds gate HTTP MCP servers behind ' +
      '`experimental_use_rmcp_client = true` — probe at wiring time. Skills: ' +
      'no attested native skills DIR for direct file installs (the plugin ' +
      'lane serves codex skills); a direct-copy target needs an observation ' +
      'run before a default ships (harness-bridge requires an explicit dest).',
  },
  [OPENCODE_SPEC_ID]: {
    id: OPENCODE_SPEC_ID,
    status: 'verified',
    verifiedAt: '2026-08-15',
    references: [
      'docs/mcp/OPENCODE-CLI-PIN.md',
      'https://opencode.ai/docs/mcp-servers/',
      'opencode-ai 1.18.18 (hermetic observation run, macOS arm64, 2026-08-15)',
    ],
    note:
      'opencode (SST, opencode.ai — not OpenClaw). Config is JSONC everywhere: ' +
      'comments parse in .json-named files, and global opencode.json AND ' +
      'opencode.jsonc are BOTH read (merged) when both exist; `opencode mcp ' +
      'add` writes the user-global opencode.jsonc via a comment-preserving ' +
      'editor, so gbrain writes match that bar (jsonc-parser surgical edits, ' +
      'opencode-json.ts). MCP entries: {type:"local", command[], environment, ' +
      'enabled?} / {type:"remote", url, headers} — header values keep ' +
      '`{env:VAR}` interpolation verbatim; unknown keys tolerated in 1.18.18 ' +
      'but gbrain writes NO marker key (ownership is a structural ' +
      'fingerprint — a future strict-schema flip must not brick the host). ' +
      '`mcp add` has no scope flag (always user-global); project opencode.json ' +
      'is read but a project-defined LOCAL server spawns with NO trust gate ' +
      '(verified) — so gbrain defaults registration to USER scope and treats ' +
      'project scope as explicit opt-in with a sharing warning. `mcp list` is ' +
      'the honest discriminator (spawns servers; ✓/✗ text; exit 0 regardless); ' +
      '`mcp debug` is OAuth-only. Keyless anonymous free tier answers headless ' +
      '`run` AND drives MCP tool calls without --auto (load-bearing for the ' +
      'door SMOKE). DOCS-CONTRADICTION pinned: OPENCODE_CONFIG / _CONFIG_DIR / ' +
      '_CONFIG_CONTENT observed INERT in 1.18.18 — only HOME/XDG_CONFIG_HOME ' +
      'move the config; path helpers resolve via XDG only. opencode sets ' +
      'OPENCODE=1 (+OPENCODE_PID) in bash-tool children — detectHarness ' +
      'probes OPENCODE. AGENTS.md loads natively; CLAUDE.md is NOT ' +
      'double-loaded. opencode ships a JS plugin/event system — ' +
      'OPENCODE_HAS_HOOKS=false means "gbrain does not wire it yet" (follow-up ' +
      'filed), NOT "opencode has no hooks"; probes run with --pure + ' +
      'OPENCODE_DISABLE_AUTOUPDATE=1 because mcp list autoloads plugins. ' +
      'Skills: no attested native skills DIR for direct file installs; a ' +
      'direct-copy target needs an observation run before a default ships ' +
      '(harness-bridge requires an explicit dest).',
  },
};

// ── Claude Code shapes the writers consume ──────────────────────────────────

/** Settings file the hook writer targets, relative to the workspace root. */
export const CLAUDE_SETTINGS_FILE_RELPATH = join('.claude', 'settings.local.json');

/** The COMMITTED hook carrier [D12]. Cloud sessions clone the repo fresh and
 * snapshot hook config at session start — the gitignored settings.local.json
 * never exists there, and hooks written mid-session never activate. Cloud and
 * attach installs therefore write hooks into the repo-committed
 * `.claude/settings.json` with a PATH-resolved fail-open command (no absolute
 * paths — the file travels between machines). Local installs keep
 * settings.local.json; the writers enforce that one event never fires from
 * both files. */
export const CLAUDE_COMMITTED_SETTINGS_FILE_RELPATH = join('.claude', 'settings.json');

/** Hook events bootstrap wires (plan D5 + hook events table).
 * v0.45.7 ambient recall adds PreCompact: it BANKS the window's standing
 * entities into session_context_state so the post-compaction SessionStart
 * (source=compact — Claude Code's actual rehydration re-entry point) can
 * serve a warm context pack. PreCompact stdout is NOT context-injected by
 * the harness; the banking write is the point. */
export const CLAUDE_HOOK_EVENTS = [
  'SessionStart',
  'UserPromptSubmit',
  'Stop',
  'SessionEnd',
  'PreCompact',
] as const;
export type ClaudeHookEvent = (typeof CLAUDE_HOOK_EVENTS)[number];

/** `gbrain hook <subcommand>` per event (src/commands/hook.ts dispatch). */
export const CLAUDE_HOOK_SUBCOMMAND: Record<ClaudeHookEvent, string> = {
  SessionStart: 'session-start',
  UserPromptSubmit: 'user-prompt',
  Stop: 'stop',
  SessionEnd: 'session-end',
  PreCompact: 'compact',
};

/**
 * Harness-side cap on hook stdout / additionalContext [ENG-1]: overflow is
 * diverted to a file and NOT injected, so every producer budgets below this.
 */
export const CLAUDE_HOOK_OUTPUT_CAP_CHARS = 10000;

/**
 * Default per-event `timeout` (SECONDS — the settings-file unit) written by
 * the hook installer. Each sits above the command's own self-deadline
 * (session-start ≤1.5s, user-prompt ≤800ms) so the harness timeout is the
 * backstop, never the primary limiter; session-end parses a full transcript
 * and may push, so it gets the widest budget.
 */
export const CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS: Record<ClaudeHookEvent, number> = {
  SessionStart: 5,
  UserPromptSubmit: 3,
  Stop: 10,
  SessionEnd: 60,
  PreCompact: 5,
};

/**
 * Marker property carried by every hook command object bootstrap writes
 * [G5, CX2-17]. The structural JSON merger keys removal/dedupe on this —
 * NEVER on command-string equality (which breaks when the binary path or
 * env values change between runs).
 */
export const GBRAIN_HOOK_MARKER_KEY = '_gbrain';
export const GBRAIN_HOOK_MARKER_VALUE = 'bootstrap-v1';

/**
 * Marker VALUE for harness-mode installs (`gbrain bootstrap harness`, #4043).
 * Same `_gbrain` key, distinct value: a box can carry a workspace bootstrap
 * install (bootstrap-v1 in settings.local.json) AND a harness install
 * (bootstrap-harness-v1 in user settings.json or a project settings.local.json)
 * — each removal path strips only its own entries.
 *
 * The marker is advisory on Claude Code settings: when the host rewrites
 * settings.json through its own schema it can drop keys it does not know,
 * keeping only type/command/timeout. The harness lane therefore also owns an
 * UNMARKED entry whose command is exactly the one it writes for that event
 * and whose launcher/source/seat match the install or its receipt
 * (hooks.ts classifyHarnessHook); the command string is the durable carrier.
 * The workspace lane (bootstrap-v1) still keys on the marker alone.
 */
export const GBRAIN_HARNESS_MARKER_VALUE = 'bootstrap-harness-v1';

/**
 * Marker VALUE for `gbrain setup` installs. Advisory only: setup owns an
 * entry by the exact hash its connection receipt recorded
 * (hooks.ts hookEntryHash), so an edited marked entry is never replaced or
 * removed, and two installs on one machine each keep their own entries.
 */
export const GBRAIN_SETUP_MARKER_VALUE = 'setup-v1';

/**
 * User-scope Claude Code settings file (harness-mode hook + permissions
 * target). Resolution mirrors Claude Code itself: CLAUDE_CONFIG_DIR (its
 * documented config-dir override, which the real-claude e2e harness sets)
 * else $HOME/.claude — checked explicitly because Bun's homedir() reads the
 * password database, NOT the HOME env var, so a sandboxed test that remaps
 * HOME would otherwise write into the operator's REAL settings file (this
 * bit us; the write-ahead receipt's remove path self-healed it).
 */
/**
 * The one CLAUDE_CONFIG_DIR-else-HOME-env-else-homedir() resolution (Bun's
 * homedir() reads the password DB, not $HOME — the sandboxed-test hazard
 * documented on claudeUserSettingsPath). Returns the directory that plays
 * the role of `~/.claude` for paths that live INSIDE it (settings.json,
 * skills/). NOT for claudeUserMcpConfigPath — its default lives at the HOME
 * level (`~/.claude.json`), a genuinely different shape.
 */
function claudeConfigBase(): string {
  const configDir = process.env.CLAUDE_CONFIG_DIR?.trim();
  if (configDir) return configDir;
  const home = process.env.HOME?.trim();
  return join(home || homedir(), '.claude');
}

export function claudeUserSettingsPath(): string {
  return join(claudeConfigBase(), 'settings.json');
}

function claudeManagedSettingsDir(): string {
  if (process.platform === 'darwin') return '/Library/Application Support/ClaudeCode';
  if (process.platform === 'win32') return 'C:\\Program Files\\ClaudeCode';
  return '/etc/claude-code';
}

/**
 * #8057: Claude Code's managed settings, which apply to every session on the
 * machine: managed-settings.json, then its managed-settings.d/*.json drop-ins
 * in name order. `dir` defaults to the platform's system directory.
 */
export function claudeManagedSettingsPaths(dir = claudeManagedSettingsDir()): string[] {
  const dropIns = join(dir, 'managed-settings.d');
  let names: string[] = [];
  try { names = readdirSync(dropIns).filter((n) => n.endsWith('.json')).sort(); } catch { /* no drop-in directory */ }
  return [join(dir, 'managed-settings.json'), ...names.map((n) => join(dropIns, n))];
}

/**
 * #4325: the config-dir base itself, exported for detection — a machine with
 * a `~/.claude` (or CLAUDE_CONFIG_DIR) directory has Claude Code configured
 * even when the `claude` binary isn't on the probing process's PATH (CI
 * runners, alias-only shells). Mirrors detectCodex's config-file fallback.
 */
export function claudeConfigDir(): string {
  return claudeConfigBase();
}

/** permissions.allow entry that pre-approves an MCP server's tools for headless runs. */
export function mcpPermissionEntry(serverName: string): string {
  return `mcp__${serverName}`;
}

/**
 * User-scope Claude Code MCP registration store (`claude mcp add` user scope
 * writes here). Same HOME-env-first discipline as claudeUserSettingsPath —
 * Bun's homedir() reads the password database, not $HOME, so a sandboxed
 * test that remaps HOME would otherwise read the operator's REAL config.
 */
export function claudeUserMcpConfigPath(): string {
  const configDir = process.env.CLAUDE_CONFIG_DIR?.trim();
  if (configDir) return join(configDir, '.claude.json');
  const home = process.env.HOME?.trim();
  return join(home || homedir(), '.claude.json');
}

/**
 * Where Claude Code stores session transcripts — the confinement root [S3#8].
 * Uses the same config-dir base as settings/skills so custom config dirs keep
 * legitimate transcript paths inside the allowed root.
 */
export function claudeProjectsDir(): string {
  return join(claudeConfigBase(), 'projects');
}

/**
 * User-scope Claude Code skills dir (native SKILL.md discovery — the
 * harness-bridge install target). Same CLAUDE_CONFIG_DIR-first then
 * HOME-env-first discipline as claudeUserSettingsPath: Bun's homedir()
 * reads the password database, not $HOME, so a sandboxed test that remaps
 * HOME would otherwise write into the operator's REAL skills dir.
 */
export function claudeUserSkillsDir(): string {
  return join(claudeConfigBase(), 'skills');
}

/**
 * Project-scope Claude Code skills dir (`<workspace>/.claude/skills`).
 * Provisional-from-docs: the user-scope dir is the attested location; the
 * project-scope layout mirrors Claude Code's settings precedence.
 */
export function claudeProjectSkillsDir(workspaceDir: string): string {
  return join(workspaceDir, '.claude', 'skills');
}

/**
 * User-scope Claude Code memory file (`~/.claude/CLAUDE.md` — loaded into
 * every session's context; the ambient-writeback managed block's install
 * target). PROVISIONAL-from-docs (https://code.claude.com/docs/en/memory,
 * noted 2026-09-01): the user-memory location is documented but has no
 * in-repo live-binary attestation yet — treat a writer failure as
 * "re-verify the spec" per the [ENG-7] discipline. Same
 * CLAUDE_CONFIG_DIR-else-HOME-env-else-homedir() resolution as
 * claudeUserSettingsPath (Bun's homedir() reads the password database, not
 * $HOME — the sandboxed-test hazard documented there).
 */
export function claudeUserMemoryPath(): string {
  return join(claudeConfigBase(), 'CLAUDE.md');
}

// ── Codex shapes ────────────────────────────────────────────────────────────

/**
 * Codex CLI config file (user-global). Real codex resolves CODEX_HOME as the
 * config DIRECTORY itself (config.toml sits directly inside it) — pinned by
 * test/e2e/bootstrap-real-codex.serial.test.ts and connect-bearer.test.ts,
 * which set CODEX_HOME to a temp dir and assert the real binary wrote there.
 * A homedir-only resolution here would make any CODEX_HOME-isolated test
 * clobber the operator's real ~/.codex/config.toml.
 */
export function codexConfigPath(): string {
  return join(codexHome(), 'config.toml');
}

/** THE one CODEX_HOME resolution (env override, else ~/.codex) — every codex
 * path below joins onto it so the discipline can never drift per-path. */
function codexHome(): string {
  return process.env.CODEX_HOME?.trim() || join(homedir(), '.codex');
}

/**
 * Codex rollout store — (CODEX_HOME || ~/.codex)/sessions/YYYY/MM/DD/
 * rollout-*.jsonl (same CODEX_HOME resolution discipline as codexConfigPath;
 * the spawner of a codex hook IS codex, which owns that env). This is the
 * confinement root for the codex hook lane's transcript_path [S3#8] and the
 * base of its discovery fallback — pinned here, never widenable by the
 * process that spawned the hook.
 */
export function codexSessionsDir(): string {
  return join(codexHome(), 'sessions');
}

/**
 * Codex ARCHIVED rollout store — (CODEX_HOME || ~/.codex)/archived_sessions/
 * rollout-*.jsonl. Codex moves a rollout here when a session is archived, and
 * the store is FLAT: no YYYY/MM/DD nesting, unlike codexSessionsDir (verified
 * on a live 0.147.0 host — 363 rollouts, zero subdirectories). It is the same
 * codex-owned trust boundary as the live store, so the hook lane confines to
 * BOTH; a moved rollout is otherwise refused as outside_projects_dir and is
 * invisible to the discovery fallback.
 */
export function codexArchivedSessionsDir(): string {
  return join(codexHome(), 'archived_sessions');
}

/**
 * Codex hooks file — (CODEX_HOME || ~/.codex)/hooks.json, USER-GLOBAL (no
 * per-project scope for the user layer gbrain writes). Written by
 * codex-hooks.ts together with its config.toml trust-state entry; see
 * CODEX_HOOKS_SPEC_TARGET there for the verified 0.147.0 facts.
 */
export function codexHooksPath(): string {
  return join(codexHome(), 'hooks.json');
}

/**
 * Codex user-global AGENTS.md — (CODEX_HOME || ~/.codex)/AGENTS.md, the
 * instruction file codex merges into every session; the ambient-writeback
 * managed block's install target. PROVISIONAL-from-docs
 * (https://developers.openai.com/codex/guides/agents-md, noted 2026-09-01):
 * no in-repo live-binary attestation for the user-global file yet — an
 * observation run promotes it (follow-up filed in the ambient-writeback
 * plan). The SAME doc pins an exclusivity rule: when AGENTS.override.md
 * exists in CODEX_HOME, codex loads IT INSTEAD and ignores AGENTS.md
 * entirely — writers must probe codexAgentsOverridePath() first or they
 * install a dead integration [OV-A4].
 */
export function codexGlobalAgentsPath(): string {
  return join(codexHome(), 'AGENTS.md');
}

/**
 * The exclusivity file for codexGlobalAgentsPath() (same dated PROVISIONAL
 * spec note, developers.openai.com/codex/guides/agents-md, 2026-09-01): its
 * presence means codex IGNORES AGENTS.md — probe it before writing there,
 * and report it in status so a dead integration never reads healthy.
 */
export function codexAgentsOverridePath(): string {
  return join(codexHome(), 'AGENTS.override.md');
}

/** Codex hook events the BOOTSTRAP lane wires: SessionEnd capture only. The
 * SessionStart and UserPromptSubmit context hooks belong to `gbrain setup
 * codex`'s hash-owned writer (codex-hooks.ts `CODEX_SETUP_EVENTS`); they bake
 * no source, and `gbrain hook` resolves it per session from the payload cwd
 * (#5941). */
export const CODEX_HOOK_EVENTS = ['SessionEnd'] as const;

/**
 * Whether gbrain WIRES codex hooks. True as of the Memorable wave: bootstrap
 * writes a SessionEnd entry into hooks.json plus its config.toml trust-state
 * entry (codex-hooks.ts — the 0.147.0 trust gate makes an untrusted entry
 * silently inert). The bootstrap lane wires SESSION-END CAPTURE ONLY;
 * per-turn context comes from `gbrain setup codex`'s SessionStart and
 * UserPromptSubmit hooks, or else the pull-protocol AGENTS.md gates (plan D5).
 */
export const CODEX_HAS_HOOKS = true;

/**
 * Managed-block markers for the harness lane's direct config.toml writes
 * (codex-toml.ts — the CX2-17 revisit, fired by #4043). Full-line exact
 * match at column 0; the writer requires exactly one begin/end pair.
 */
export const CODEX_TOML_BLOCK_BEGIN =
  `# gbrain:${GBRAIN_HARNESS_MARKER_VALUE} begin - managed by \`gbrain bootstrap harness\`; do not edit inside`;
export const CODEX_TOML_BLOCK_END = `# gbrain:${GBRAIN_HARNESS_MARKER_VALUE} end`;

// ── opencode shapes ─────────────────────────────────────────────────────────

/**
 * opencode config DIRECTORY (user-global). Resolution mirrors what the real
 * binary was OBSERVED to do (OPENCODE-CLI-PIN.md §Path seams): XDG_CONFIG_HOME
 * else $HOME/.config, then /opencode. The OPENCODE_CONFIG / OPENCODE_CONFIG_DIR
 * / OPENCODE_CONFIG_CONTENT env vars are deliberately NOT honored here —
 * observed INERT in opencode 1.18.18 (probes registered through each were
 * invisible to `mcp list` while the XDG-resolved config was still read), so
 * honoring them would write registrations into a file opencode never reads (a
 * silent no-op install). HOME is read from the env explicitly because Bun's
 * homedir() reads the password database, not the HOME env var (the
 * claudeUserSettingsPath lesson).
 */
export function opencodeConfigDir(): string {
  const xdg = process.env.XDG_CONFIG_HOME?.trim();
  if (xdg) return join(xdg, 'opencode');
  const home = process.env.HOME?.trim();
  return join(home || homedir(), '.config', 'opencode');
}

/**
 * User-global opencode config FILE. Both `opencode.json` and `opencode.jsonc`
 * are read (merged) by the host when both exist; gbrain edits the file that
 * already carries content, preferring `.jsonc` (the name `opencode mcp add`
 * itself writes) when both or neither exist — one-owner-per-file keeps the
 * merge unambiguous for `mcp.gbrain`.
 */
export function opencodeGlobalConfigPath(): string {
  const dir = opencodeConfigDir();
  const jsonc = join(dir, 'opencode.jsonc');
  const json = join(dir, 'opencode.json');
  if (existsSync(jsonc)) return jsonc;
  if (existsSync(json)) return json;
  return jsonc;
}

/**
 * The OTHER member of the global filename pair for a given config path
 * (`opencode.json` ↔ `opencode.jsonc` in the same dir), or null when the
 * basename is not a pair member. opencode MERGES both files when both exist,
 * so global WRITERS must reconcile `mcp.<name>` across the pair — a same-name
 * entry left in the sibling survives as a shadow registration whose merge
 * winner is ambiguous (and a later removal of the primary "reveals" it).
 * Callers apply this to the USER-GLOBAL pair only; project-scope sibling
 * semantics are unobserved.
 */
export function opencodeGlobalSiblingPath(configPath: string): string | null {
  const dir = dirname(configPath);
  const base = basename(configPath);
  if (base === 'opencode.json') return join(dir, 'opencode.jsonc');
  if (base === 'opencode.jsonc') return join(dir, 'opencode.json');
  return null;
}

/** Project-scope opencode config (docs-canonical name; opencode's lookup
 * traverses up to the git root). Committed-file candidate — the writer's
 * PATH-resolved command + sharing-warning rules apply (OPENCODE.md). */
export function opencodeProjectConfigPath(workspaceDir: string): string {
  return join(workspaceDir, 'opencode.json');
}

/**
 * Whether gbrain WIRES opencode's hook/plugin system. False = not yet:
 * opencode ships a JS plugin/event system (and `--pure` to suppress it), but
 * gbrain's opencode plugin lane is a filed follow-up; per-turn context on
 * opencode rides the pull-protocol AGENTS.md gates, which opencode loads
 * natively (verified — and CLAUDE.md is NOT double-loaded alongside it).
 */
export const OPENCODE_HAS_HOOKS = false;