Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
39.9 KB
Raw Blame
import { harnessAdapter } from '../core/harness/registry.ts';
/**
 * `gbrain connect` — one-command coding-agent onboarding from a bearer token
 * (or OAuth 2.1 client credentials).
 *
 * Turns an MCP URL + credential into a paste-ready block (or wires it up
 * directly with --install) that connects a coding agent straight to a remote
 * `gbrain serve --http` and teaches it to self-orient via `get_brain_identity`
 * + `list_skills`. Direct HTTP MCP — no local install or thin-client config
 * needed for the connection.
 *
 *   gbrain connect <mcp-url> [--token <bearer>] [--name gbrain]
 *                  [--agent claude-code|codex|opencode|perplexity|generic]
 *                  [--oauth [--register | --client-id ID --client-secret SECRET] [--scopes "read write"]]
 *                  [--install] [--yes] [--json] [--show-token] [--force]
 *                  [--timeout-ms N]
 *
 * Auth:
 *   - Bearer (default): a `gbrain auth create` token. Simple; long-lived +
 *     full-access. Best for local/personal use.
 *   - OAuth 2.1 client credentials (`--oauth`, perplexity/generic only): the
 *     correct path for anything exposed to a third-party cloud — least-privilege
 *     scopes + short-lived rotating access tokens. The connector is given an
 *     issuer URL + client_id + client_secret; it mints its own tokens.
 *
 * Per-agent shape:
 *   - claude-code: `claude mcp add ... -H "Authorization: Bearer <tok>"` (bearer
 *     only; --install runs it).
 *   - codex: `codex mcp add <name> --url <url> --bearer-token-env-var
 *     GBRAIN_REMOTE_TOKEN` (bearer via env var; --install runs it).
 *   - opencode: `opencode mcp add <name> --url <url> --header
 *     "Authorization=Bearer {env:GBRAIN_REMOTE_TOKEN}"` (the interpolation is
 *     stored literally; --install writes the entry directly via
 *     opencode-json.ts — no binary needed).
 *   - perplexity: GUI connector (Settings → Connectors). Supports bearer or
 *     OAuth; no --install.
 *   - generic: prints the connector fields for any other MCP client.
 */

import { execFileSync } from '../core/spawn.ts';
import { mkdirSync } from 'node:fs';
import { dirname } from 'node:path';
import type { ConnectProbeResult } from '../core/connect-probe.ts';
import { probeBrainIdentity, DEFAULT_PROBE_TIMEOUT_MS } from '../core/connect-probe.ts';
import { opencodeGlobalConfigPath } from '../core/bootstrap/host-specs.ts';
import { acquireBootstrapLock } from '../core/bootstrap/lock.ts';
import { brainFirstTarget, describeBrainFirstOutcome, installerBrainFirst, isBrainFirstHarness, priorBrainFirst } from '../core/setup/brain-first.ts';
import { describeTurnHookOutcome } from '../core/setup/turn-hook.ts';
import { installerTurnHook, TURN_HOOK_NATIVE_INSPECT, turnHookFix } from '../core/setup/turn-hook-check.ts';
import { resolveGbrainBin } from '../core/gbrain-bin.ts';
import { describeSkillsBlockOutcome, indexLauncher, installerSkillsBlock, isSkillLoading, skillsOutcomeFailed, skillsOutcomeShown, type SkillLoading } from '../core/setup/skills-block.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import {
  GBRAIN_REMOTE_TOKEN_ENV,
  reconcileOpencodeSiblingGlobal,
  writeOpencodeMcpEntry,
} from '../core/bootstrap/opencode-json.ts';
import { promptLine } from '../core/cli-util.ts';
import { consentGateOrExit } from '../core/consent-cli.ts';
import {
  NAME_RE,
  OAUTH_SECRET_NOTE,
  REDACTED,
  buildClaudeMcpAddArgv,
  buildCodexMcpAddArgv,
  buildOpencodeMcpAddArgv,
  cmdString,
  isValidName,
  issuerFromMcpUrl,
  normalizeMcpUrl,
  redactToken,
  shellQuote,
  validateToken,
} from '../core/mcp-registration.ts';

// The pure registration helpers moved to src/core/mcp-registration.ts for
// #4043 (the bootstrap harness lane consumes them; core must not import from
// commands). Re-exported so this module's public surface — and every test
// that imports from it — is unchanged.
export {
  OAUTH_SECRET_NOTE,
  REDACTED,
  buildClaudeMcpAddArgv,
  buildCodexMcpAddArgv,
  buildOpencodeMcpAddArgv,
  cmdString,
  isLinkLocalOrMetadata,
  issuerFromMcpUrl,
  isValidName,
  normalizeMcpUrl,
  redactToken,
  validateToken,
  type TokenValidation,
  type UrlResult,
} from '../core/mcp-registration.ts';

// Defined from the writer's exported constant so the printed interpolation and
// the ownership fingerprint literal ({env:GBRAIN_REMOTE_TOKEN}) cannot drift.
export const ENV_VAR = GBRAIN_REMOTE_TOKEN_ENV;
export const PLACEHOLDER_TOKEN = '<paste-your-token>';
export const PLACEHOLDER_SECRET = '<paste-your-client-secret>';
export const DEFAULT_NAME = 'gbrain';
export const DEFAULT_SCOPES = 'read write';
// Single source of truth shared with the probe (was a duplicated 15_000 literal).
const DEFAULT_TIMEOUT_MS = DEFAULT_PROBE_TIMEOUT_MS;

export type AgentId = 'claude-code' | 'codex' | 'opencode' | 'perplexity' | 'generic';

interface AgentSpec {
  id: AgentId;
  label: string;       // human label for messages
  binary?: string;     // CLI binary backing --install ('claude' | 'codex'; opencode installs via the direct JSONC writer)
  installable: boolean;
  supportsOAuth: boolean; // accepts OAuth client-credentials connector fields
}

export const AGENT_IDS: AgentId[] = ['claude-code', 'codex', 'opencode', 'perplexity', 'generic'];

// Preserve the legacy command surface while deriving adapter facts centrally.
export const AGENT_SPECS = Object.fromEntries(AGENT_IDS.map(id => {
  const adapter = harnessAdapter(id);
  const binary = adapter.connection === 'codex-toml' ? 'codex' : adapter.connection === 'claude-json' ? 'claude' : undefined;
  return [id, { id, label: adapter.label, binary, installable: adapter.connection !== 'manual', supportsOAuth: adapter.renewable }];
})) as Record<AgentId, AgentSpec>;

// The named tools MUST be real MCP-exposed ops (verified by the round-trip
// E2E). `capture` earned its slot in the CLI→MCP gap-closure wave (D2A):
// it is a starter-surface op now — prefer it for quick notes (auto-slug +
// dedupe), `put_page` for full-control writes.
export const LEARN_INSTRUCTION =
  'Once connected, call the `get_brain_identity` tool (whose brain this is), then ' +
  '`list_skills` (everything it can do; if it errors, the host has not enabled skill ' +
  'publishing — these core tools still work: search, query, get_page, put_page, ' +
  'capture, think, find_experts). Then call `list_brain_skillpack`: if this brain ships ' +
  'a skillpack, ask the user whether to install it (gbrain skillpack scaffold <spec>). ' +
  'Prefer `capture` for quick notes (auto-slug + dedupe) and `put_page` for ' +
  'full-control writes. Always search the brain before answering or writing.';

const SECRET_NOTE =
  'Note: that bearer token is a long-lived secret that carries whatever its grant allows (whoami shows its scopes) — ' +
  'keep it private and prefer a scoped/short-lived token if your host supports one.';

// OAUTH_SECRET_NOTE moved to src/core/mcp-registration.ts (imported +
// re-exported above; text unchanged).

const PERPLEXITY_REMOTE_NOTE = [
  'Perplexity connects remotely, so the brain must be reachable over HTTPS. On the',
  'host run: gbrain serve --http --bind 0.0.0.0 --public-url <your-https-url> (the',
  'default 127.0.0.1 bind refuses tunneled connections). See docs/mcp/PERPLEXITY.md.',
].join('\n');

const HELP = `gbrain connect — wire a coding agent to a remote gbrain over MCP

Usage:
  gbrain connect <mcp-url> --harness <id> --credentials-file <private-file> --install
  gbrain connect <mcp-url> [--token <bearer>] [flags]

The private-handoff path separates host provisioning from installation here.
Thin CLI adapters require --root <absolute-persistent-root>. See gbrain mcp --help.

Prints a copy-paste setup block for your agent, or wires it up directly with
--install (claude-code, codex + opencode). The MCP URL is your remote
'gbrain serve --http' endpoint; a bare host is rejected — pass an explicit
https:// URL.

Auth:
  Bearer token (default)         simple, long-lived; carries its grant's scopes — best local/personal
                                 (a member key from setup's member-keys/ folder works here)
  --oauth                        OAuth 2.1 client credentials (perplexity/generic):
                                 least-privilege scopes + short-lived tokens — best for
                                 anything exposed to a third-party cloud

Flags:
  --token <bearer>     Bearer token (else $${ENV_VAR}; from 'gbrain auth create')
  --name <id>          MCP server name in the agent (default: ${DEFAULT_NAME})
  --agent <kind>       claude-code (default) | codex | opencode | perplexity | generic
  --oauth              Use OAuth client credentials instead of a bearer token
  --register           With --oauth: mint a client on the host (gbrain auth register-client)
  --client-id <id>     With --oauth: use an existing OAuth client id
  --client-secret <s>  With --oauth: use an existing OAuth client secret
  --scopes "<s>"       With --oauth --register: client scopes (default: "${DEFAULT_SCOPES}")
  --install            Run the agent's MCP-add command, then smoke-test the token
                       (claude-code + codex + opencode; opencode installs via a direct
                       config write — no binary needed, token stays out of the file).
                       Also writes the brain-first instruction block into the agent's
                       own instruction file (CLAUDE.md / AGENTS.md)
  --no-instructions    With --install, skip (and remove) the brain-first block
  --skill-loading M    With --install: off (default) or spring, a compact index of
                       gbrain's bundled skills beside that block, each loaded on
                       demand with gbrain bundled-skill <name>. Remembered.
  --gbrain-bin PATH    With --skill-loading spring: the absolute gbrain the index
                       names (default: this gbrain, else the one on PATH).
  --yes                The user's approval for --install (writes a credential-
                       bearing MCP entry); without it a non-interactive run exits 3
  --force              On --install, replace an existing server of the same name
  --json               Emit machine-readable JSON (secret redacted)
  --show-token         With --json, include the literal token/secret (avoid in logs)
  --timeout-ms <n>     Smoke-test timeout for --install (default: ${DEFAULT_TIMEOUT_MS})

Examples:
  gbrain connect https://brain.example.com/mcp --token gbrain_xxx
  gbrain connect https://brain.example.com:3131 --install --yes
  gbrain connect https://brain.example.com/mcp --token gbrain_xxx --agent codex
  gbrain connect https://brain.example.com/mcp --token gbrain_xxx --agent opencode --install
  gbrain connect https://brain.example.com/mcp --agent perplexity --oauth --register
  gbrain connect https://brain.example.com/mcp --agent perplexity --oauth \\
    --client-id gbrain_cl_xxx --client-secret gbrain_cs_xxx
`;

// ---------------------------------------------------------------------------
// Pure helpers (unit-tested in test/connect.test.ts; registration helpers
// live in src/core/mcp-registration.ts and are re-exported above)
// ---------------------------------------------------------------------------

export type TokenResolution =
  | { kind: 'literal'; token: string }
  | { kind: 'placeholder' }
  | { kind: 'error'; error: string };

export function resolveToken(opts: { tokenFlag?: string | null; env?: string | null; mode: 'print' | 'install' }): TokenResolution {
  const t = opts.tokenFlag ?? opts.env ?? null;
  if (t != null && t !== '') {
    const v = validateToken(t);
    if (!v.ok) return { kind: 'error', error: v.error };
    return { kind: 'literal', token: t };
  }
  if (opts.mode === 'print') return { kind: 'placeholder' };
  return {
    kind: 'error',
    error: `No token. Pass --token <bearer> or set ${ENV_VAR}. Create one on the host with: gbrain auth create "<name>"`,
  };
}

export interface OAuthCreds {
  issuer: string;
  clientId: string;
  clientSecret: string | null;
}

function claudeBlock(p: { name: string; url: string; token: string | null }): string {
  const headerToken = p.token ?? PLACEHOLDER_TOKEN;
  const cmd = cmdString('claude', buildClaudeMcpAddArgv({ name: p.name, url: p.url, headerToken }));
  const lines = ['# Paste into Claude Code:', '', 'Connect my knowledge brain, then learn what it can do:', '', `  ${cmd}`, ''];
  if (!p.token) lines.push(`Replace ${PLACEHOLDER_TOKEN} with a token from \`gbrain auth create "claude-code"\` on the host.`, '');
  lines.push(LEARN_INSTRUCTION, '', SECRET_NOTE);
  return lines.join('\n');
}

function codexBlock(p: { name: string; url: string; token: string | null }): string {
  const tokenValue = p.token ?? PLACEHOLDER_TOKEN;
  const cmd = cmdString('codex', buildCodexMcpAddArgv({ name: p.name, url: p.url, envVar: ENV_VAR }));
  const lines = [
    '# Paste into Codex:',
    '',
    'Connect my knowledge brain, then learn what it can do:',
    '',
    `  export ${ENV_VAR}=${shellQuote(tokenValue)}`,
    `  ${cmd}`,
    '',
  ];
  if (!p.token) lines.push(`Replace ${PLACEHOLDER_TOKEN} with a token from \`gbrain auth create "codex"\` on the host.`, '');
  lines.push(
    `Codex reads the token from $${ENV_VAR} at runtime — keep that variable set in your shell profile so new Codex sessions can reach the brain.`,
    '',
    LEARN_INSTRUCTION,
    '',
    SECRET_NOTE,
  );
  return lines.join('\n');
}

function opencodeBlock(p: { name: string; url: string; token: string | null }): string {
  const tokenValue = p.token ?? PLACEHOLDER_TOKEN;
  const cmd = cmdString('opencode', buildOpencodeMcpAddArgv({ name: p.name, url: p.url, envVar: ENV_VAR }));
  const lines = [
    '# Paste into opencode:',
    '',
    'Connect my knowledge brain, then learn what it can do:',
    '',
    `  export ${ENV_VAR}=${shellQuote(tokenValue)}`,
    `  ${cmd}`,
    '',
  ];
  if (!p.token) lines.push(`Replace ${PLACEHOLDER_TOKEN} with a token from \`gbrain auth create "opencode"\` on the host.`, '');
  lines.push(
    `The config stores the literal \`{env:${ENV_VAR}}\` interpolation — opencode resolves it at read time, ` +
      `so keep that variable exported in your shell profile; the token never lands in the config file. ` +
      `Restart opencode after registering (config is read at session start).`,
    '',
    LEARN_INSTRUCTION,
    '',
    SECRET_NOTE,
  );
  return lines.join('\n');
}

function perplexityBearerBlock(p: { url: string; token: string | null }): string {
  const tokenValue = p.token ?? PLACEHOLDER_TOKEN;
  return [
    '# In Perplexity (Pro): Settings → Connectors → add a remote MCP server:',
    `#   URL:    ${p.url}`,
    '#   Auth:   Bearer token (API key)',
    `#   Token:  ${tokenValue}`,
    '',
    PERPLEXITY_REMOTE_NOTE,
    '',
    LEARN_INSTRUCTION,
    '',
    SECRET_NOTE,
  ].join('\n');
}

function perplexityOAuthBlock(p: { oauth: OAuthCreds }): string {
  const secret = p.oauth.clientSecret ?? PLACEHOLDER_SECRET;
  return [
    '# In Perplexity (Pro): Settings → Connectors → add a remote MCP server:',
    `#   URL:           ${p.oauth.issuer}/mcp`,
    '#   Auth:          OAuth 2.1 (client credentials)',
    `#   Issuer URL:    ${p.oauth.issuer}`,
    `#   Client ID:     ${p.oauth.clientId}`,
    `#   Client Secret: ${secret}`,
    '',
    'OAuth is the recommended path for Perplexity (a cloud service): the connector',
    'mints short-lived, scoped access tokens instead of holding a long-lived secret.',
    '',
    PERPLEXITY_REMOTE_NOTE,
    '',
    LEARN_INSTRUCTION,
    '',
    OAUTH_SECRET_NOTE,
  ].join('\n');
}

function genericBearerBlock(p: { url: string; token: string | null }): string {
  const headerToken = p.token ?? PLACEHOLDER_TOKEN;
  return [
    '# Add an HTTP MCP server pointed at your gbrain:',
    `#   URL:    ${p.url}`,
    `#   Header: Authorization: Bearer ${headerToken}`,
    '',
    LEARN_INSTRUCTION,
  ].join('\n');
}

function genericOAuthBlock(p: { oauth: OAuthCreds }): string {
  const secret = p.oauth.clientSecret ?? PLACEHOLDER_SECRET;
  return [
    '# Add an OAuth 2.1 (client-credentials) MCP server pointed at your gbrain:',
    `#   URL:           ${p.oauth.issuer}/mcp`,
    `#   Issuer URL:    ${p.oauth.issuer}`,
    `#   Client ID:     ${p.oauth.clientId}`,
    `#   Client Secret: ${secret}`,
    '',
    LEARN_INSTRUCTION,
    '',
    OAUTH_SECRET_NOTE,
  ].join('\n');
}

export function buildConnectBlock(p: { agent: AgentId; name: string; url: string; token: string | null; oauth?: OAuthCreds }): string {
  if (p.oauth) {
    // OAuth is only emitted for connector-style agents (gated upstream).
    return p.agent === 'generic' ? genericOAuthBlock({ oauth: p.oauth }) : perplexityOAuthBlock({ oauth: p.oauth });
  }
  switch (p.agent) {
    case 'claude-code': return claudeBlock(p);
    case 'codex': return codexBlock(p);
    case 'opencode': return opencodeBlock(p);
    case 'perplexity': return perplexityBearerBlock(p);
    case 'generic': return genericBearerBlock(p);
  }
}

export function buildJson(p: { url: string; name: string; agent: AgentId; token: string | null; showToken: boolean; oauth?: OAuthCreds; scopes?: string }): Record<string, unknown> {
  if (p.oauth) {
    const secret = p.oauth.clientSecret;
    return {
      schema_version: 1,
      agent: p.agent,
      mcp_url: p.url,
      name: p.name,
      auth: 'oauth',
      issuer_url: p.oauth.issuer,
      client_id: p.oauth.clientId,
      client_secret: secret == null ? null : (p.showToken ? secret : REDACTED),
      secret_redacted: secret != null && !p.showToken,
      scopes: p.scopes ?? DEFAULT_SCOPES,
      command: null,
      command_argv: null,
      learn_instruction: LEARN_INSTRUCTION,
    };
  }
  const shownToken = p.token ? (p.showToken ? p.token : REDACTED) : PLACEHOLDER_TOKEN;
  let command_argv: string[] | null = null;
  let command: string | null = null;
  if (p.agent === 'claude-code') {
    command_argv = buildClaudeMcpAddArgv({ name: p.name, url: p.url, headerToken: shownToken });
    command = cmdString('claude', command_argv);
  } else if (p.agent === 'codex') {
    // Codex command carries no token (env-var name only), so it's safe verbatim.
    command_argv = buildCodexMcpAddArgv({ name: p.name, url: p.url, envVar: ENV_VAR });
    command = cmdString('codex', command_argv);
  } else if (p.agent === 'opencode') {
    // The literal {env:VAR} interpolation, not a token — safe verbatim.
    command_argv = buildOpencodeMcpAddArgv({ name: p.name, url: p.url, envVar: ENV_VAR });
    command = cmdString('opencode', command_argv);
  }
  return {
    schema_version: 1,
    agent: p.agent,
    mcp_url: p.url,
    name: p.name,
    auth: 'bearer',
    env_var: ENV_VAR,
    token_present: p.token != null,
    token_redacted: p.token != null && !p.showToken,
    header: `Authorization: Bearer ${shownToken}`,
    command, // runnable CLI command; null for perplexity/generic (UI/manual setup)
    command_argv,
    learn_instruction: LEARN_INSTRUCTION,
  };
}

// ---------------------------------------------------------------------------
// --install / --register dependencies (injectable for tests)
// ---------------------------------------------------------------------------

export type RegisterResult =
  | { ok: true; clientId: string; clientSecret: string }
  | { ok: false; message: string };

export interface ConnectDeps {
  isTTY(): boolean;
  promptYesNo(question: string): Promise<boolean>;
  hasBinary(binary: string): boolean;
  runBinary(binary: string, argv: string[]): { code: number; stdout: string; stderr: string };
  probe(url: string, token: string, timeoutMs: number): Promise<ConnectProbeResult>;
  env(name: string): string | undefined;
  registerOAuthClient(name: string, scopes: string): RegisterResult;
  /** opencode --install lane: direct JSONC write of a remote entry carrying
   * the literal `{env:GBRAIN_REMOTE_TOKEN}` interpolation (no binary execed,
   * no token on disk). Throws on a foreign same-name entry; an OURS entry at
   * a different url refuses unless `allowReplaceOtherSource` (connect maps
   * --force onto it). May be async: the default impl serializes on the
   * config-dir bootstrap lock (the writer contract); sync test fakes remain
   * assignable. */
  writeOpencodeRemoteEntry(
    name: string,
    url: string,
    opts?: { allowReplaceOtherSource?: boolean },
  ): { configPath: string; replacedPrior: boolean } | Promise<{ configPath: string; replacedPrior: boolean }>;
  /** After a successful registration: the brain-first block in the agent's own instruction file. Returns the line to print. */
  writeInstructions(agent: AgentId, name: string, optOut: boolean, skillLoading?: SkillLoading, gbrainBin?: string): string | null;
  /** After the block: the per-turn hook that puts the rule next to every turn (src/core/setup/turn-hook.ts). `ok: false` fails the install loudly. */
  writeTurnHook(agent: AgentId): { lines: string[]; ok: boolean };
}

async function defaultPromptYesNo(question: string): Promise<boolean> {
  // Reuse the shared prompt helper so stdin pause/resume lifecycle matches the
  // rest of the interactive CLI flows (init, apply-migrations, ...).
  const answer = (await promptLine(`${question} (y/N): `)).toLowerCase();
  return answer === 'y' || answer === 'yes';
}

function defaultRunBinary(binary: string, argv: string[]): { code: number; stdout: string; stderr: string } {
  try {
    const stdout = execFileSync(binary, argv, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
    return { code: 0, stdout: stdout ?? '', stderr: '' };
  } catch (e) {
    const err = e as { status?: number; stdout?: string | Buffer; stderr?: string | Buffer; message?: string };
    return {
      code: typeof err.status === 'number' ? err.status : 1,
      stdout: err.stdout ? String(err.stdout) : '',
      stderr: err.stderr ? String(err.stderr) : (err.message ?? ''),
    };
  }
}

/** Mint an OAuth client by shelling to the host's `gbrain auth register-client`. */
function defaultRegisterOAuthClient(name: string, scopes: string): RegisterResult {
  const r = defaultRunBinary('gbrain', [
    'auth', 'register-client', name,
    '--grant-types', 'client_credentials',
    '--scopes', scopes,
    '--token-endpoint-auth-method', 'client_secret_post',
  ]);
  if (r.code !== 0) {
    return { ok: false, message: r.stderr || r.stdout || 'gbrain auth register-client failed' };
  }
  const clientId = r.stdout.match(/Client ID:\s+(\S+)/)?.[1];
  const clientSecret = r.stdout.match(/Client Secret:\s+(\S+)/)?.[1];
  if (!clientId || !clientSecret) {
    return { ok: false, message: 'could not parse client_id/client_secret from register-client output' };
  }
  return { ok: true, clientId, clientSecret };
}

const defaultDeps: ConnectDeps = {
  isTTY: () => !!process.stdin.isTTY,
  promptYesNo: defaultPromptYesNo,
  hasBinary: (binary) => {
    try {
      execFileSync(binary, ['--version'], { stdio: 'ignore' });
      return true;
    } catch {
      return false;
    }
  },
  runBinary: defaultRunBinary,
  probe: (url, token, timeoutMs) => probeBrainIdentity(url, token, { timeoutMs }),
  env: (name) => process.env[name],
  registerOAuthClient: defaultRegisterOAuthClient,
  writeInstructions: (agent, name, optOut, skillLoading, gbrainBin) => {
    if (!isBrainFirstHarness(agent)) return null;
    const target = brainFirstTarget(agent);
    if ('error' in target) return null;
    const writer = `gbrain connect --agent ${agent} --install`;
    const o = installerBrainFirst({ target, access: { kind: 'mcp', server: name }, writer, instructions: optOut ? false : undefined });
    const skills = installerSkillsBlock({ target, launcher: gbrainBin ?? indexLauncher() ?? 'gbrain', writer, brainFirstDeclined: o.decision.value === 'declined', skillLoading, audience: 'downstream' });
    const lines = [`${describeBrainFirstOutcome(o, false).trim()}${o.decision.value === 'accepted' ? ' (opt out with --no-instructions)' : ''}`];
    if (skillsOutcomeShown(skills)) lines.push(describeSkillsBlockOutcome(skills, false).trim());
    if (skillsOutcomeFailed(skills)) setCliExitVerdict(1);
    return lines.join('\n');
  },
  writeTurnHook: (agent) => {
    const target = isBrainFirstHarness(agent) ? brainFirstTarget(agent) : null;
    const accepted = !!target && !('error' in target) && priorBrainFirst(agent, target.path)?.status === 'installed' && process.env.GBRAIN_AGENT_INSTRUCTIONS !== '0';
    const rerun = ['gbrain', 'setup', agent, '--instructions-only'];
    const { outcome, verdict } = installerTurnHook({ harness: agent, accepted, gbrainBin: resolveGbrainBin(), gbrainHome: process.env.GBRAIN_HOME?.trim() || undefined, rerun: rerun.join(' ') });
    const lines = [describeTurnHookOutcome(outcome).trim()];
    if (!verdict || verdict.ok) return { lines: verdict ? [...lines, `verify   turn hook ${verdict.message}`] : lines, ok: true };
    const fix = turnHookFix(agent, rerun);
    return { lines: [...lines, `error turn_hook_not_loaded (${verdict.reason}): the per-turn gbrain hook is not active: ${verdict.message}. Fix: ${rerun.join(' ')}. Verify: ${fix.verify?.argv?.join(' ')}${TURN_HOOK_NATIVE_INSPECT[agent] ? `; the harness's own check: ${TURN_HOOK_NATIVE_INSPECT[agent]}` : ''}.`], ok: false };
  },
  writeOpencodeRemoteEntry: async (name, url, opts) => {
    // The writer's contract: callers hold acquireBootstrapLock on the config
    // dir (harness.ts [X11] parity) — the user-global file is shared across
    // workspaces and homes, so concurrent gbrain writers serialize here.
    const configPath = opencodeGlobalConfigPath();
    const cfgDir = dirname(configPath);
    mkdirSync(cfgDir, { recursive: true }); // the lock needs the dir; the writer mkdirs later anyway
    const lock = await acquireBootstrapLock(cfgDir);
    try {
      // Two-filename merge blind spot: opencode merges BOTH user-global
      // filenames, so a same-name gbrain entry in the SIBLING file would
      // survive this write as a shadow registration (ours → removed with a
      // note; foreign → refuse loudly naming both files).
      const sib = reconcileOpencodeSiblingGlobal(configPath, name, { url });
      for (const note of sib.notes) console.error(note);
      const r = writeOpencodeMcpEntry(
        configPath,
        { kind: 'remote', name, url, tokenMode: 'env' },
        { expect: { url }, ...(opts?.allowReplaceOtherSource ? { allowReplaceOtherSource: true } : {}) },
      );
      return { configPath: r.configPath, replacedPrior: r.replacedPrior };
    } finally {
      lock.release();
    }
  },
};

// ---------------------------------------------------------------------------
// Orchestrator
// ---------------------------------------------------------------------------

interface ParsedFlags {
  url?: string;
  token?: string;
  name: string;
  agent: AgentId;
  oauth: boolean;
  register: boolean;
  clientId?: string;
  clientSecret?: string;
  scopes: string;
  install: boolean;
  yes: boolean;
  force: boolean;
  json: boolean;
  showToken: boolean;
  noInstructions: boolean;
  skillLoading?: SkillLoading;
  gbrainBin?: string;
  timeoutMs: number;
  help: boolean;
  agentError?: string;
  argError?: string;
}

function parseArgs(args: string[]): ParsedFlags {
  const out: ParsedFlags = {
    name: DEFAULT_NAME,
    agent: 'claude-code',
    oauth: false,
    register: false,
    scopes: DEFAULT_SCOPES,
    install: false,
    yes: false,
    force: false,
    json: false,
    showToken: false,
    noInstructions: false,
    timeoutMs: DEFAULT_TIMEOUT_MS,
    help: false,
  };
  // Read the value for a value-taking flag, refusing a missing value or one
  // that is itself a flag (e.g. `--token --install` would otherwise silently
  // consume `--install` as the token and leave install off). Shares `i` with
  // the loop below, so it is declared in the function body, not the for-header.
  let i = 0;
  const takeValue = (flag: string): string | undefined => {
    const v = args[i + 1];
    if (v === undefined || v.startsWith('--')) {
      out.argError = `${flag} requires a value.`;
      return undefined;
    }
    i++;
    return v;
  };
  for (; i < args.length; i++) {
    const a = args[i];
    switch (a) {
      case '--help': case '-h': out.help = true; break;
      case '--install': out.install = true; break;
      case '--oauth': out.oauth = true; break;
      case '--register': out.register = true; break;
      case '--yes': case '-y': out.yes = true; break;
      case '--force': out.force = true; break;
      case '--json': out.json = true; break;
      case '--show-token': out.showToken = true; break;
      case '--no-instructions': out.noInstructions = true; break;
      case '--gbrain-bin': { const v = takeValue('--gbrain-bin'); if (v !== undefined) out.gbrainBin = v; break; }
      case '--skill-loading': {
        const v = takeValue('--skill-loading');
        if (v === undefined) break;
        if (isSkillLoading(v)) out.skillLoading = v;
        else out.agentError = out.agentError ?? `Unknown --skill-loading '${v}'. Use off or spring.`;
        break;
      }
      case '--token': { const v = takeValue('--token'); if (v !== undefined) out.token = v; break; }
      case '--client-id': { const v = takeValue('--client-id'); if (v !== undefined) out.clientId = v; break; }
      case '--client-secret': { const v = takeValue('--client-secret'); if (v !== undefined) out.clientSecret = v; break; }
      case '--scopes': { const v = takeValue('--scopes'); if (v !== undefined) out.scopes = v; break; }
      case '--name': { const v = takeValue('--name'); if (v !== undefined) out.name = v; break; }
      case '--agent': {
        const v = takeValue('--agent');
        if (v === undefined) break;
        if ((AGENT_IDS as string[]).includes(v)) out.agent = v as AgentId;
        else out.agentError = `Unknown --agent '${v}'. Use one of: ${AGENT_IDS.join(', ')}.`;
        break;
      }
      case '--timeout-ms': {
        const raw = takeValue('--timeout-ms');
        if (raw === undefined) break;
        const n = parseInt(raw, 10);
        if (Number.isFinite(n) && n > 0) out.timeoutMs = n;
        break;
      }
      default:
        if (!a.startsWith('-') && out.url === undefined) out.url = a;
        break;
    }
  }
  return out;
}

function fail(msg: string): never {
  console.error(msg);
  process.exit(1);
}

/**
 * A4 consent for `--install`: it writes a credential-bearing MCP entry into
 * the agent's config (persistent_install) and sends the token to the remote
 * host (credentials). `--yes` or a TTY prompt (deps seams) authorizes it;
 * otherwise exit 3 with the consent payload. The approved argv never carries
 * the token value: it names GBRAIN_REMOTE_TOKEN instead.
 */
async function installConsent(args: string[], f: ParsedFlags, url: string, destination: string, deps: ConnectDeps): Promise<void> {
  const argv = ['gbrain', 'connect'];
  for (let i = 0; i < args.length; i++) {
    const a = args[i]!;
    if (a === '--yes' || a === '-y') continue;
    if (a === '--token') { i++; continue; }
    if (a.startsWith('--token=')) continue;
    argv.push(a);
  }
  await consentGateOrExit({
    command: 'connect --install',
    effects: ['credentials', 'persistent_install'],
    actor: 'agent',
    what: `Register the MCP server '${f.name}' -> ${url} in ${destination}`,
    why: 'Wires this agent to the remote brain so its memory tools are available in new sessions.',
    risk: `Writes a credential-bearing MCP entry into ${destination} and sends the token to ${url} for a smoke test. `
      + `Undo: remove the '${f.name}' MCP server from that agent. The approved command reads the token from GBRAIN_REMOTE_TOKEN (or the same --token).`,
    user_message: `Add the brain at ${url} to ${destination} as MCP server '${f.name}' (it stores an access token there)?`,
    argv,
    args,
  }, {
    json: f.json,
    env: { interactive: deps.isTTY(), readLine: async ({ prompt }) => ({ kind: 'line', text: (await deps.promptYesNo(prompt.replace(/ \[y\/N\] $/, ''))) ? 'y' : 'n' }) },
  });
}

/** Resolve OAuth creds from explicit flags or by registering a client on the host. */
function resolveOAuthCreds(f: ParsedFlags, url: string, deps: ConnectDeps): OAuthCreds {
  const issuer = issuerFromMcpUrl(url);
  if (f.clientId && f.clientSecret) {
    return { issuer, clientId: f.clientId, clientSecret: f.clientSecret };
  }
  if (f.clientId || f.clientSecret) {
    fail('--oauth needs BOTH --client-id and --client-secret (or use --register to mint a client).');
  }
  if (f.register) {
    const r = deps.registerOAuthClient(f.name, f.scopes);
    if (!r.ok) {
      fail(`Could not register an OAuth client (run this on the brain host where the DB lives): ${r.message}\n` +
        `Or mint one manually: gbrain auth register-client ${f.name} --grant-types client_credentials --scopes "${f.scopes}"`);
    }
    return { issuer, clientId: r.clientId, clientSecret: r.clientSecret };
  }
  return fail(
    '--oauth needs an OAuth client. Either:\n' +
    `  • --register  (mint one on the host: gbrain auth register-client ${f.name} --grant-types client_credentials --scopes "${f.scopes}")\n` +
    '  • --client-id <id> --client-secret <secret>  (use an existing client)',
  );
}

export async function runConnect(args: string[], deps: ConnectDeps = defaultDeps): Promise<void> {
  if (args.includes('--harness') || args.includes('--credentials-file')) {
    const { runHarnessConnect } = await import('./harness-connect.ts');
    return runHarnessConnect(args);
  }
  const f = parseArgs(args);
  if (f.help) {
    console.log(HELP);
    return;
  }
  if (f.argError) fail(f.argError);
  if (f.agentError) fail(f.agentError);
  if (!isValidName(f.name)) {
    fail(`Invalid --name '${f.name}'. Use a lowercase identifier matching ${NAME_RE}.`);
  }

  const norm = normalizeMcpUrl(f.url ?? '');
  if (!norm.ok) fail(norm.error);
  if (norm.warning) console.error(norm.warning);
  const url = norm.url;
  const spec = AGENT_SPECS[f.agent];

  // ---- OAuth path (connector-style agents only; no --install) ----
  if (f.oauth) {
    if (!spec.supportsOAuth) {
      fail(`--oauth (client credentials) is for connector-style agents (${AGENT_IDS.filter((a) => AGENT_SPECS[a].supportsOAuth).join(', ')}). ${spec.label} uses the bearer path — drop --oauth.`);
    }
    if (f.install) {
      fail(`--install is not supported with --oauth. ${spec.label} is configured through its UI; this prints the OAuth connector fields to paste.`);
    }
    const oauth = resolveOAuthCreds(f, url, deps);
    if (f.json) {
      console.log(JSON.stringify(buildJson({ url, name: f.name, agent: f.agent, token: null, showToken: f.showToken, oauth, scopes: f.scopes }), null, 2));
    } else {
      console.log(buildConnectBlock({ agent: f.agent, name: f.name, url, token: null, oauth }));
    }
    return;
  }

  const mode = f.install ? 'install' : 'print';
  const tok = resolveToken({ tokenFlag: f.token ?? null, env: deps.env(ENV_VAR) ?? null, mode });
  if (tok.kind === 'error') fail(tok.error);
  const token: string | null = tok.kind === 'literal' ? tok.token : null;

  if (!f.install) {
    if (f.json) {
      console.log(JSON.stringify(buildJson({ url, name: f.name, agent: f.agent, token, showToken: f.showToken }), null, 2));
    } else {
      console.log(buildConnectBlock({ agent: f.agent, name: f.name, url, token }));
    }
    return;
  }

  // --install path. token is guaranteed literal here (install mode resolveToken).
  const realToken = token as string;
  if (!spec.installable) {
    fail(`--install supports claude-code, codex, and opencode. ${spec.label} is set up through its own UI — drop --install to print the setup steps.`);
  }

  if (f.agent === 'opencode') {
    // Direct-writer lane: no opencode binary required (the JSONC write IS the
    // registration), and the config carries only the {env:VAR} interpolation
    // — the writer's fingerprint handles idempotent re-runs and refuses a
    // foreign same-name entry (--force cannot override THAT; pick --name).
    // --force maps to the writer's allowReplaceOtherSource so an OURS entry
    // at an old url (a rotated serve) is replaceable, mirroring the exec
    // lanes' documented --force semantics.
    await installConsent(args, f, url, 'the opencode user-global config', deps);
    let w: { configPath: string; replacedPrior: boolean };
    try {
      w = await deps.writeOpencodeRemoteEntry(f.name, url, { allowReplaceOtherSource: f.force });
    } catch (e) {
      fail(redactToken((e as Error).message, realToken));
    }
    console.error(
      `Added MCP entry '${f.name}' -> ${url} in ${w.configPath}` +
        `${w.replacedPrior ? ' (replaced the prior gbrain entry)' : ''}. Restart opencode (config is read at session start).`,
    );
    const ocInstructions = deps.writeInstructions(f.agent, f.name, f.noInstructions, f.skillLoading, f.gbrainBin);
    if (ocInstructions) console.error(ocInstructions);
    for (const line of deps.writeTurnHook(f.agent).lines) console.error(line);
    if (deps.env(ENV_VAR) !== realToken) {
      console.error(`opencode resolves {env:${ENV_VAR}} at read time. Add this to your shell profile so sessions can reach the brain:`);
      console.error(`  export ${ENV_VAR}=<your-token>`);
    }
    const ocProbe = await deps.probe(url, realToken, f.timeoutMs);
    if (ocProbe.ok) {
      console.error(`Verified: ${ocProbe.identity || 'brain reachable'}`);
      console.error('');
      console.error(LEARN_INSTRUCTION);
      return;
    }
    console.error(
      `Warning: registered '${f.name}', but the smoke-test did not verify (${ocProbe.reason}): ${redactToken(ocProbe.message, realToken)}`,
    );
    console.error('The agent will likely hit 401/errors until the token or URL is fixed.');
    process.exit(1);
  }

  const binary = spec.binary as string; // 'claude' | 'codex'
  if (!deps.hasBinary(binary)) {
    fail(`${spec.label} CLI ('${binary}') not found on PATH. Install ${spec.label}, or drop --install to print the command to run manually.`);
  }

  const exists = deps.runBinary(binary, ['mcp', 'get', f.name]).code === 0;
  if (exists && !f.force) {
    fail(`An MCP server named '${f.name}' already exists in ${spec.label}. Run '${binary} mcp remove ${f.name}' first, pass --name <other>, or --force to replace it.`);
  }

  await installConsent(args, f, url, spec.label, deps);

  let removedExisting = false;
  if (exists && f.force) {
    const rm = deps.runBinary(binary, ['mcp', 'remove', f.name]);
    if (rm.code !== 0) {
      fail(`Could not replace existing server '${f.name}': ${redactToken(rm.stderr || rm.stdout, realToken)}`);
    }
    removedExisting = true;
  }

  const addArgv = f.agent === 'codex'
    ? buildCodexMcpAddArgv({ name: f.name, url, envVar: ENV_VAR })
    : buildClaudeMcpAddArgv({ name: f.name, url, headerToken: realToken });
  const add = deps.runBinary(binary, addArgv);
  if (add.code !== 0) {
    const note = removedExisting ? ` (note: the previous '${f.name}' was already removed — re-run to restore it)` : '';
    fail(`'${binary} mcp add' failed${note}: ${redactToken(add.stderr || add.stdout, realToken)}`);
  }
  console.error(`Added MCP server '${f.name}' -> ${url}.`);
  const instructions = deps.writeInstructions(f.agent, f.name, f.noInstructions, f.skillLoading, f.gbrainBin);
  if (instructions) console.error(instructions);
  const turnHook = deps.writeTurnHook(f.agent);
  for (const line of turnHook.lines) console.error(line);

  // Codex reads the token from the env var at runtime, not from its config.
  // If the current env doesn't already carry it, the user must export it.
  if (f.agent === 'codex' && deps.env(ENV_VAR) !== realToken) {
    console.error(`Codex reads the token from $${ENV_VAR} at runtime. Add this to your shell profile so new sessions can reach the brain:`);
    console.error(`  export ${ENV_VAR}=<your-token>`);
  }

  // D4 smoke-test: prove the token actually authenticates a tool call now,
  // instead of failing silently on the agent's first request.
  const probe = await deps.probe(url, realToken, f.timeoutMs);
  if (probe.ok) {
    console.error(`Verified: ${probe.identity || 'brain reachable'}`);
    console.error('');
    console.error(LEARN_INSTRUCTION);
    if (!turnHook.ok) process.exit(1);
    return;
  }
  // Server is registered, but end-to-end auth did not verify. Exit non-zero so
  // scripts notice; the message never echoes the token.
  console.error(
    `Warning: registered '${f.name}', but the smoke-test did not verify (${probe.reason}): ${redactToken(probe.message, realToken)}`,
  );
  console.error('The agent will likely hit 401/errors until the token or URL is fixed.');
  process.exit(1);
}