Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.5 KB
Raw Blame
/** CLI-only commands may parse/read input before lazily connecting to a local engine. */
import type { BrainEngine } from '../core/engine.ts';
import type { GBrainConfig } from '../core/config.ts';
import type { EngineConnectOptions } from '../core/engine-connect.ts';
import { OperationError } from '../core/ops/contract.ts';
import { finishCliTeardown, noteRenderedErrorCode, setCliExitVerdict, writeStdoutFinal } from '../core/cli-force-exit.ts';
import { maybeDelegateLocalOperation } from '../core/persistence/local-client.ts';
import { PersistenceIpcTransportError } from '../core/persistence/ipc.ts';
import { RemoteMcpError } from '../core/remote-mcp-error.ts';
import { getCliOptions } from '../core/cli-options.ts';
import { PENDING_WRITE_EXIT_CODE } from '../core/exit-codes.ts';
import { acceptPendingCovers, acceptPendingRequested, pendingReceiptOf, pollCommand, WRITE_EXIT_DOCS, writeErrorExitCode } from '../core/persistence/write-wait.ts';
import { cliRenderContext, toAgentError } from '../core/agent-output.ts';
import { cliCommandOf } from '../cli/cli-error.ts';

export async function reportPersistenceCliError(error: unknown, json = false,
  out: (payload: string) => Promise<void> = writeStdoutFinal): Promise<boolean> {
  if (!(error instanceof OperationError || error instanceof PersistenceIpcTransportError
    || error instanceof RemoteMcpError && (error.detail?.request_id || error.detail?.write_request))) return false;
  const detail = error.toJSON();
  // #5232: an admitted pending write is not a failure; it exits
  // PENDING_WRITE_EXIT_CODE (0 with --accept-pending) and names how to poll.
  const pending = pendingReceiptOf(error);
  const acceptPending = acceptPendingRequested(getCliOptions().acceptPending);
  const render = cliRenderContext();
  const envelope = toAgentError(error, { transport: 'cli', command: cliCommandOf(), render, ...(pending ? { mutating: true, outcome: 'pending' as const } : {}) });
  // #6255: one source for the poll command: the envelope's receipt fix, pinned like every CLI fix.
  const poll = pending ? pollCommand(pending.request_id, envelope.fix, render.routing) : undefined;
  if (json) {
    // Legacy keys lead and keep their values; the v1 envelope fields (code, fix, docs_cmd, class, retryable,
    // notices, contract_version) come from the shared renderer, as renderCliError writes them (cli-error.ts pattern).
    const legacy: Record<string, unknown> = pending ? { ...detail, request_id: pending.request_id, state: pending.state,
      poll_command: poll } : { ...detail };
    noteRenderedErrorCode(envelope.code);
    const doc = { ...legacy, ...Object.fromEntries(Object.entries(envelope).filter(([, v]) => v !== undefined)), ...legacy };
    await out(JSON.stringify(doc, null, 2) + '\n');
  }
  console.error(pending ? `Pending [write_pending]: ${detail.message} It may still commit.`
    : error instanceof OperationError || error instanceof RemoteMcpError
      ? `Error [${'write_error' in detail && detail.write_error || detail.error}]: ${detail.message}` : error.message);
  if (detail.suggestion) console.error(`Fix: ${detail.suggestion}`);
  const receipt = 'write_request' in detail ? detail.write_request : undefined;
  const requestId = receipt?.request_id ?? ('request_id' in detail ? detail.request_id : undefined);
  if (requestId) console.error(`Request: ${requestId}${receipt ? ` (${receipt.state})` : ''}`);
  if (pending) {
    console.error(`Poll: ${poll}`);
    if (!acceptPending) console.error(`Exit ${PENDING_WRITE_EXIT_CODE}: accepted, not yet committed. Wait longer with --wait <seconds>, or pass --accept-pending to exit 0 (${WRITE_EXIT_DOCS}).`);
    else if (!acceptPendingCovers(pending)) console.error(`Exit ${PENDING_WRITE_EXIT_CODE}: accepted, but queued for an owner host that runs no consumer and has been quiet past the stale window (the receipt's diagnostic.owner); --accept-pending does not cover it. Run gbrain doctor --only owner_host_stale --json (${WRITE_EXIT_DOCS}).`);
  }
  setCliExitVerdict(writeErrorExitCode(error, acceptPending));
  return true;
}

/** Shared operation CLI lane; false alone authorizes the caller's normal connect path. */
export async function runDelegatedCliOperation(
  operation: string,
  params: Record<string, unknown>,
  config: GBrainConfig | null,
  options: { brain?: string | null; timeoutMs?: number; room?: string },
  render: (operation: string, result: unknown, params: Record<string, unknown>) => string,
): Promise<boolean> {
  try {
    const delegated = await maybeDelegateLocalOperation(operation, params, config, options);
    if (!delegated.handled) return false;
    if (options.room !== undefined) return await printDelegatedRoom(operation, delegated, options.room, params, render);
    const output = render(operation, delegated.result, params);
    if (output) await writeStdoutFinal(output);
    if ((delegated.result as { status?: unknown } | null)?.status === 'error') setCliExitVerdict(1);
    return true;
  } catch (error) {
    if (await reportPersistenceCliError(error, params.json === true)) return true;
    throw error;
  }
}

/** GBRA-498: a delegated answer for --room: the owner's marks (or every item unknown), the notices, then the room summary. */
async function printDelegatedRoom(operation: string, delegated: { result: unknown; room?: { meta: unknown; notices: unknown[] } }, room: string,
  params: Record<string, unknown>, render: (operation: string, result: unknown, params: Record<string, unknown>) => string): Promise<true> {
  const roomCli = await import('../cli/room.ts');
  const marked = await roomCli.delegatedRoom(operation, delegated, room);
  const { applyCliOpNotices } = await import('../cli/op-notices.ts');
  const { result, stderr } = applyCliOpNotices(roomCli.cliRoomResult(marked, params.json === true), params.json === true, { op: operation, retrieval: null });
  const output = render(operation, result, params);
  if (output) await writeStdoutFinal(output);
  if (stderr) process.stderr.write(stderr);
  if (params.json !== true) process.stderr.write(roomCli.roomSummaryLine(marked.meta));
  if ((marked.result as { status?: unknown } | null)?.status === 'error') setCliExitVerdict(1);
  return true;
}

export async function runDeferredPersistenceCommand(
  command: 'capture' | 'forget' | 'call' | 'sources' | 'takes',
  args: string[],
  connect: (opts?: EngineConnectOptions) => Promise<BrainEngine>,
): Promise<void> {
  // A3: refusing to remove or archive the default source is invalid input (exit 2), as on
  // the unmanaged lane; the write lane's verdict would be 1.
  if (command === 'sources' && ['remove', 'archive', 'purge'].includes(args[0] ?? '') && args[1] === 'default') {
    const { exitCliError, usageError } = await import('../cli/cli-error.ts');
    exitCliError(usageError('The default source cannot be removed or archived.',
      'The default source holds the brain\'s primary pages and always stays registered; remove or archive a named source instead.',
      { fix: { argv: ['gbrain', 'sources', 'list', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Lists the named sources that can be removed or archived.' } }), 'sources');
  }
  let connected: BrainEngine | null = null;
  const getEngine = async (opts?: EngineConnectOptions) => connected ??= await connect(opts);
  try {
    if (command === 'takes') {
      const { runTakesMutation, runTakesRebuild } = await import('./takes-mutation.ts');
      if (args[0] === 'rebuild') await runTakesRebuild(getEngine, args.slice(1));
      else await runTakesMutation(getEngine, args);
    } else if (command === 'sources') {
      if (args[0] === 'reconcile') {
        const { runReconcileCli } = await import('./source-reconcile.ts');
        await runReconcileCli(args.slice(1));
      } else if (args[0] === 'writer') {
        const { runPersistenceAdminCli } = await import('./persistence-admin.ts');
        await runPersistenceAdminCli('writer', args.slice(1));
      } else {
        const { runSourceLifecycleCli } = await import('./sources-lifecycle.ts');
        await runSourceLifecycleCli(args, getEngine);
      }
    } else if (command === 'capture') {
      const { runCapture } = await import('./capture.ts');
      await runCapture(null, args, { getEngine });
    } else if (command === 'forget') {
      const { runForget } = await import('./recall.ts');
      await runForget(getEngine, args);
    } else {
      const { runCall } = await import('./call.ts');
      await runCall(getEngine, args);
    }
  } finally {
    if (connected) await finishCliTeardown({ engine: connected, drainTimeoutMs: 1000 });
  }
}