Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.5 KB
Raw Blame
/**
 * CLI half of the warm CLI socket. Before a read (search, query, get, recall)
 * opens its own database connection, the CLI looks for a serve's socket in
 * `$GBRAIN_HOME/.gbrain/run/`; when a serve bound to the same brain identity
 * answers, the CLI prints that answer with the cold path's own renderer and
 * exit codes. A missing, unsafe, stale, busy, refusing or dying socket returns
 * false and the cold path runs as if the socket did not exist (a note goes to
 * stderr only with GBRAIN_DEBUG=1, except an identity refusal, which always
 * prints a degraded notice). GBRAIN_CLI_SOCKET=0 skips the socket.
 */
import net from 'node:net';
import { format } from 'node:util';
import { loadConfig, configDir, configPath, isThinClient } from '../core/config.ts';
import { getCliOptions } from '../core/cli-options.ts';
import { resolveBrainId } from '../core/brain-resolver.ts';
import { VERSION } from '../version.ts';
import type { OperationMeta } from '../core/ops/contract.ts';
import { cliSocketDir, cliSocketPath, connectProblem } from '../core/cli-socket/fs-guard.ts';
import { cliSocketIdentity } from '../core/cli-socket/identity.ts';
import { peerCredSupport, peerUid, type PeerCredSupport } from '../core/cli-socket/peer-cred.ts';
import {
  CONNECT_TIMEOUT_MS, DEFAULT_READ_WALLCLOCK_MS, FrameReader, HANDSHAKE_TIMEOUT_MS, isHandshakeFrame, isResultFrame, MAX_RESPONSE_BYTES,
  MAX_ROUND_TRIP_MS, reviveOperationError, warmRoundTripTimeout, type CliSocketOp, type CliSocketRequest, type OutputChunk, type ResultFrame,
} from '../core/cli-socket/protocol.ts';
import type { OperationError } from '../core/ops/contract.ts';

export const CLI_SOCKET_COMMANDS: readonly string[] = ['search', 'query', 'get', 'recall'];
const SOCKET_OPS: Record<string, CliSocketOp> = { search: 'search', query: 'query', get_page: 'get_page' };

function debug(reason: string): void {
  if (process.env.GBRAIN_DEBUG === '1') process.stderr.write(`[cli-socket] cold path: ${reason}\n`);
}

/**
 * A refusal by identity is never silent (GBRA-156): every call from an environment that differs from the serve's
 * takes the slower cold path until that part matches, so the CLI prints a degraded notice naming the part (never its
 * value) whether or not GBRAIN_DEBUG is set. The serve counts the refusal for doctor `cli_socket_refusals`.
 */
export async function noteCliSocketRefusal(reason: string): Promise<void> {
  const refused = /^refused \(identity_mismatch\)(?:: (.+))?$/.exec(reason);
  if (!refused) return;
  const part = refused[1] ?? 'its identity';
  const { writeCliNotices } = await import('../core/interop-notices.ts');
  writeCliNotices([{ code: 'socket_identity_mismatch', kind: 'degraded',
    why: `The running serve's warm CLI socket refused this call because ${part} differs from the serve's (the value is never shown), so it ran on the slower cold path. Every call from this environment does until that part matches the serve's.`,
    fix: { argv: ['gbrain', 'doctor', '--only', 'cli_socket_refusals', '--json'], consent: [], actor: 'agent', requires_exclusive: false, docs: 'docs/guides/cli-socket.md',
      why: 'Read-only: names each identity part the serve refused and how often; run the caller with the serve\'s value, or restart the serve with the caller\'s.' } }]);
}

const isRoundTripTimeout = (fields: Record<string, unknown>) => fields.code === 'timeout' && fields.reason === 'cli_socket_round_trip_cap';

/**
 * GBRA-156: a warm call that reached its round-trip cap prints a retryable `timeout` error and exits 124 instead of
 * starting over on the cold path. The envelope goes to stdout under --json and the human line to stderr, as every CLI
 * error does; without --json an [AGENT] block also goes to stdout, so a caller that discards stderr still sees why.
 */
export async function writeWarmTimeout(error: OperationError, command: string): Promise<true> {
  const { writeCliError } = await import('./cli-error.ts');
  const { setCliExitVerdict, jsonRequested } = await import('../core/cli-force-exit.ts');
  const { agentBlock } = await import('../core/agent-markers.ts');
  const exit = writeCliError(error, command);
  if (!jsonRequested(process.argv.slice(2))) process.stdout.write(agentBlock({ why: `[timeout] ${error.message}`, next: 'wait: retry the same command' }));
  setCliExitVerdict(exit);
  return true;
}

function debugWarm(command: string, path: string): void {
  if (process.env.GBRAIN_DEBUG === '1') process.stderr.write(`[cli-socket] warm: ${command} answered by the serve socket at ${path}\n`);
}

type Exchange = { frame: ResultFrame } | { reason: string };

/**
 * One request on one connection: connect, verify the serve's uid, send, read
 * the handshake, then the result. `totalTimeoutMs` bounds the whole exchange;
 * the connect and handshake keep their own shorter bounds inside it. Without a
 * peer-credential reader on this platform the CLI never connects.
 */
export function exchangeCliSocket(path: string, request: CliSocketRequest, totalTimeoutMs: number, peerCred: PeerCredSupport = peerCredSupport()): Promise<Exchange> {
  if (!peerCred.ok) return Promise.resolve({ reason: `peer_credentials_unsupported (${peerCred.reason})` });
  const support = peerCred;
  return new Promise(resolve => {
    const deadline = performance.now() + totalTimeoutMs;
    const socket = net.createConnection(path);
    const reader = new FrameReader(MAX_RESPONSE_BYTES);
    let accepted = false;
    let settled = false;
    let timer: ReturnType<typeof setTimeout> | undefined;
    const finish = (outcome: Exchange) => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      socket.destroy();
      resolve(outcome);
    };
    const arm = (ms: number, reason: string) => {
      clearTimeout(timer);
      const remaining = deadline - performance.now();
      timer = setTimeout(() => finish({ reason: remaining <= ms ? 'round_trip_timeout' : reason }), Math.max(0, Math.min(ms, remaining)));
    };
    arm(CONNECT_TIMEOUT_MS, 'connect_timeout');
    socket.once('error', error => finish({ reason: `${accepted ? 'lost' : 'connect_failed'} (${(error as NodeJS.ErrnoException).code ?? error.message})` }));
    socket.once('close', () => finish({ reason: accepted ? 'serve_closed_mid_request' : 'serve_closed' }));
    socket.once('connect', () => {
      if (peerUid(socket, support.read) !== process.getuid?.()) { finish({ reason: 'serve_uid_mismatch' }); return; }
      arm(HANDSHAKE_TIMEOUT_MS, 'handshake_timeout');
      socket.write(JSON.stringify(request) + '\n');
    });
    socket.on('data', data => {
      const frames = reader.push(typeof data === 'string' ? Buffer.from(data) : data);
      if (frames === 'overflow') { finish({ reason: 'response_too_large' }); return; }
      for (const text of frames) {
        let value: unknown;
        try { value = JSON.parse(text); } catch { finish({ reason: 'malformed_response' }); return; }
        if (!accepted) {
          if (!isHandshakeFrame(value)) { finish({ reason: 'malformed_response' }); return; }
          if (!value.accepted) { finish({ reason: `refused (${value.reason})${value.mismatch ? `: ${value.mismatch}` : ''}` }); return; }
          accepted = true;
          arm(Number.POSITIVE_INFINITY, 'round_trip_timeout');
          continue;
        }
        finish(isResultFrame(value) ? { frame: value } : { reason: 'malformed_response' });
        return;
      }
    });
  });
}

/** The longest the CLI waits on one whole exchange: MAX_ROUND_TRIP_MS, or the call's --timeout when shorter. */
export function cliSocketRoundTripMs(timeoutMs: number | null): number {
  return Math.min(MAX_ROUND_TRIP_MS, timeoutMs ?? DEFAULT_READ_WALLCLOCK_MS);
}

/** The source the serve resolved for this call, pinned in fix commands exactly as the cold process would have noted it (before anything renders). */
async function noteSource(frame: { source?: string | null }): Promise<void> {
  if (frame.source) (await import('../core/fix-routing.ts')).noteResolvedSource(frame.source);
}

/** Prints the operation's own output, as the cold process would have by now. */
async function replay(frame: { output: OutputChunk[] }): Promise<void> {
  for (const [stream, text] of frame.output) {
    if (stream === 'stdout') process.stdout.write(text);
    else process.stderr.write(text);
  }
}

async function opRequest(command: string, args: string[]): Promise<{ op: OperationMeta; params: Record<string, unknown> } | string> {
  const { cliOps } = await import('./op-manifest.ts');
  const { cliAliases, parseOpArgs } = await import('./main.ts');
  const op = cliOps.get(command) ?? cliAliases.get(command);
  if (!op || !SOCKET_OPS[op.name]) return 'not_a_socket_op';
  const params = parseOpArgs(op, args);
  if (op.cliHints?.stdin && !params[op.cliHints.stdin]) return 'stdin_input';
  if (typeof params.image === 'string' && params.image.length > 0) return 'image_query';
  if (Object.entries(op.params).some(([key, def]) => def.required && params[key] === undefined)) return 'missing_param';
  if (typeof params.source === 'string' && params.source.length > 0 && (params.source_id !== undefined || params.all_sources === true)) return 'conflicting_scope';
  return { op, params };
}

type Buffered<T> = { value: T; flush: () => void } | { error: unknown };

/**
 * Runs a renderer with stdout, stderr and console held in memory, so a frame
 * the renderer cannot handle throws before anything reaches the terminal and
 * the caller can still take the cold path. `flush` writes what it printed.
 */
async function buffered<T>(render: () => T | Promise<T>): Promise<Buffered<T>> {
  const chunks: Array<['stdout' | 'stderr', string]> = [];
  const hold = (stream: 'stdout' | 'stderr') => (chunk: unknown, ...rest: unknown[]): boolean => {
    chunks.push([stream, typeof chunk === 'string' ? chunk : Buffer.from(chunk as Uint8Array).toString()]);
    const callback = rest.find(arg => typeof arg === 'function') as (() => void) | undefined;
    if (callback) queueMicrotask(callback);
    return true;
  };
  const saved = { out: process.stdout.write, err: process.stderr.write, log: console.log, info: console.info, warn: console.warn, error: console.error, debug: console.debug };
  process.stdout.write = hold('stdout') as typeof process.stdout.write;
  process.stderr.write = hold('stderr') as typeof process.stderr.write;
  for (const [method, stream] of [['log', 'stdout'], ['info', 'stdout'], ['debug', 'stdout'], ['warn', 'stderr'], ['error', 'stderr']] as const) {
    console[method] = (...args: unknown[]) => { chunks.push([stream, format(...args) + '\n']); };
  }
  try {
    const value = await render();
    return { value, flush: () => { for (const [stream, text] of chunks) (stream === 'stdout' ? process.stdout : process.stderr).write(text); } };
  } catch (error) {
    return { error };
  } finally {
    Object.assign(process.stdout, { write: saved.out });
    Object.assign(process.stderr, { write: saved.err });
    Object.assign(console, { log: saved.log, info: saved.info, warn: saved.warn, error: saved.error, debug: saved.debug });
  }
}

function renderFailed(error: unknown): false {
  debug(`render_failed (${error instanceof Error ? error.message : String(error)})`);
  return false;
}

/** Prints an answered op frame the way the cold path would; false (nothing printed) when the frame cannot be rendered. */
export async function renderOp(command: string, op: OperationMeta, params: Record<string, unknown>, frame: Exclude<ResultFrame, { kind: 'fallback' }>): Promise<boolean> {
  const { formatResult, captureRetrievalMeta, maybePrintConceptNudge } = await import('./main.ts');
  const { applyCliOpNotices, captureOpNotice } = await import('./op-notices.ts');
  const { setCliExitVerdict, writeStdoutFinal } = await import('../core/cli-force-exit.ts');
  await noteSource(frame);
  if (frame.kind === 'error' && isRoundTripTimeout(frame.error)) { await replay(frame); return writeWarmTimeout(reviveOperationError(frame.error), command); }
  if (frame.kind === 'error') {
    const { writeCliError } = await import('./cli-error.ts');
    const rendered = await buffered(() => writeCliError(reviveOperationError(frame.error), command));
    if ('error' in rendered) return renderFailed(rendered.error);
    await replay(frame);
    rendered.flush();
    setCliExitVerdict(rendered.value);
    return true;
  }
  const rendered = await buffered(() => {
    if (frame.meta) captureRetrievalMeta('retrieval', frame.meta);
    for (const notice of frame.notices) captureOpNotice(notice);
    const { result, stderr } = applyCliOpNotices(frame.result, params.json === true, { op: op.name, retrieval: frame.meta });
    return { result, noticeText: stderr, output: formatResult(op.name, result, params) };
  });
  if ('error' in rendered) {
    try { applyCliOpNotices(null, true); } catch { /* drains what the failed render captured */ }
    return renderFailed(rendered.error);
  }
  const { result, noticeText, output } = rendered.value;
  await replay(frame);
  rendered.flush();
  if (output) await writeStdoutFinal(output);
  if (noticeText) process.stderr.write(noticeText);
  if (typeof result === 'object' && result !== null && !Array.isArray(result) && (result as { status?: unknown }).status === 'error') {
    const detail = (result as { error?: unknown }).error;
    console.error(`gbrain ${command}: operation reported status 'error'` + (typeof detail === 'string' && detail ? ` — ${detail}` : '') + '.');
    setCliExitVerdict(1);
  }
  maybePrintConceptNudge(op.name, params);
  return true;
}

/**
 * Serves `command` from a warm serve when one is bound to this CLI's brain.
 * True means the output was printed and the exit verdict set; false means the
 * caller runs the normal cold path.
 */
export async function maybeServeFromCliSocket(command: string, args: string[]): Promise<boolean> {
  if (!CLI_SOCKET_COMMANDS.includes(command) || process.env.GBRAIN_CLI_SOCKET === '0' || process.env.GBRAIN_ENFORCED_MEMBER !== undefined) return false;
  const config = loadConfig();
  if (!config || config.engine !== 'postgres' || !config.database_url || isThinClient(config)) { debug('not a local postgres brain'); return false; }
  const cliOpts = getCliOptions();
  if (cliOpts.explain) { debug('--explain runs locally'); return false; }
  const home = configDir();
  const path = cliSocketPath(home);
  const problem = connectProblem(path, cliSocketDir(home));
  if (problem === 'missing') { debug(`no socket at ${path}; start the serve with gbrain serve --cli-socket or set serve.cli_socket true`); return false; }
  if (problem) { debug(`socket refused before connect (${problem})`); return false; }
  let brainId: string;
  try { brainId = resolveBrainId(cliOpts.brain); } catch { debug('brain did not resolve'); return false; }
  if (brainId !== 'host') { debug(`mount brain ${brainId}`); return false; }

  const base = {
    v: 1 as const,
    identity: cliSocketIdentity({ config, brainId, configDir: home, configFile: configPath(), version: VERSION, env: process.env }),
    command,
    routing: { cwd: process.cwd(), source_env: process.env.GBRAIN_SOURCE ?? null },
    cli: { quiet: cliOpts.quiet, timeout_ms: cliOpts.timeoutMs },
  };
  const resultTimeoutMs = cliSocketRoundTripMs(cliOpts.timeoutMs);

  if (command === 'recall') {
    const recall = await import('../commands/recall.ts');
    if (args.includes('--help') || args.includes('-h')) return false;
    let flags: ReturnType<typeof recall.parseFlags>;
    try { flags = recall.parseFlags(args); } catch { return false; }
    if (!recall.isRecallVerbForm(flags)) return false;
    if (!recall.isOneShotRecall(flags)) recall.validateAndNormalizeFlags(flags);
    const outcome = await exchangeCliSocket(path, { ...base, kind: 'recall', args }, resultTimeoutMs);
    if ('reason' in outcome) {
      await noteCliSocketRefusal(outcome.reason);
      if (outcome.reason === 'round_trip_timeout') return writeWarmTimeout(warmRoundTripTimeout(command, resultTimeoutMs, 'cli'), command);
      debug(outcome.reason);
      return false;
    }
    if (outcome.frame.kind === 'fallback') { debug(outcome.frame.reason); return false; }
    const frame = outcome.frame;
    debugWarm(command, path);
    await noteSource(frame);
    if (frame.kind === 'error' && isRoundTripTimeout(frame.error)) { await replay(frame); return writeWarmTimeout(reviveOperationError(frame.error), command); }
    if (frame.kind === 'error' && !recall.isOneShotRecall(flags)) { await replay(frame); throw reviveOperationError(frame.error); }
    const { writeCliNotices } = await import('../core/interop-notices.ts');
    const rendered = await buffered(async () => {
      if (frame.kind === 'error') { await recall.reportOneShotRecallError(reviveOperationError(frame.error), flags); return; }
      await recall.renderRecallVerbResult(flags, frame.result as Parameters<typeof recall.renderRecallVerbResult>[1]);
      if (frame.notices.length > 0) writeCliNotices(frame.notices);
    });
    if ('error' in rendered) return renderFailed(rendered.error);
    await replay(frame);
    rendered.flush();
    return true;
  }

  const prepared = await opRequest(command, args);
  if (typeof prepared === 'string') { debug(prepared); return false; }
  const outcome = await exchangeCliSocket(path, { ...base, kind: 'op', op: SOCKET_OPS[prepared.op.name]!, params: prepared.params }, resultTimeoutMs);
  if ('reason' in outcome) {
    await noteCliSocketRefusal(outcome.reason);
    if (outcome.reason === 'round_trip_timeout') return writeWarmTimeout(warmRoundTripTimeout(command, resultTimeoutMs, 'cli'), command);
    debug(outcome.reason);
    return false;
  }
  if (outcome.frame.kind === 'fallback') { debug(outcome.frame.reason); return false; }
  debugWarm(command, path);
  return renderOp(command, prepared.op, prepared.params, outcome.frame);
}