Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.1 KB
Raw Blame
/** Engine-free CLI routing to the process that already owns a PGLite brain. */
import { randomUUID } from 'node:crypto';
import { hookSessionCwd } from '../session-cwd.ts';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { configDir, type GBrainConfig } from '../config.ts';
import { resolveBrainId } from '../brain-resolver.ts';
import { getCliOptions } from '../cli-options.ts';
import { loadMounts, type MountEntry } from '../brain-registry.ts';
import { inspectLockHolder, type LockHolderInfo } from '../pglite-lock.ts';
import { resolveSourceIdEngineFree } from '../source-resolver.ts';
import { opError, opOwnsSource, OperationError } from '../ops/contract.ts';
import { readFix, trustedCliRequired } from '../ops/op-fix.ts';
import { parseWriteRequestId } from './preconditions.ts';
import { isWriteRequestId } from './types.ts';
import {
  isPersistenceIpcMutation, isPersistenceIpcOperation, isPersistenceIpcRegistration,
  persistenceSocketPathForConfig, requestPersistenceCapabilities, requestPersistenceOperation,
  PersistenceIpcTransportError, type PersistenceIpcCapabilities, type PersistenceIpcRegistration,
  requestPersistenceAdministration, ownerAdministers, PERSISTENCE_ROOM_MARKED_KEY, PERSISTENCE_ROOM_MAX_CHARS,
} from './ipc.ts';
import type { PersistenceAdminOperation } from './admin-contract.ts';
import { currentCliWriteWait, replayWhilePending, writeExchangeBudget } from './write-wait.ts';

function noDiscoveryPath(message: string, holder: LockHolderInfo, brainId?: string): OperationError {
  const who = holder.pid ? `process ${holder.pid}${holder.subcommand ? ` (gbrain ${holder.subcommand})` : ''}` : 'another process';
  return opError('owner_unavailable', message,
    `${who} holds ${brainId ? `brain ${brainId}'s` : 'this brain\'s'} PGLite lock but publishes no persistence socket, usually an older gbrain serve. Ask the user to stop or upgrade that process, then run the command again; nothing was sent to it.`,
    { fix: readFix('Shows the brain\'s lock holder and persistence state, read-only.', { argv: ['gbrain', 'doctor', ...(brainId ? ['--brain', brainId] : []), '--json'] }) });
}

/** The brain axis must be resolved before inspecting any host lock/socket. */
export function persistenceConfigForBrain(
  hostConfig: GBrainConfig | null,
  brainId: string,
  mounts: readonly MountEntry[],
): GBrainConfig | null {
  if (brainId === 'host') return hostConfig;
  const mount = mounts.find(candidate => candidate.id === brainId || candidate.alias === brainId);
  if (!mount || mount.enabled === false) {
    throw opError('invalid_params', `Brain '${brainId}' is not an enabled mount.`,
      'Pass --brain host or the id or alias of an enabled mount (`gbrain mounts list --json` shows them); re-enabling a disabled mount is the user\'s call.',
      { fix: readFix('Lists mounted brains with their ids, aliases and enabled state.', { argv: ['gbrain', 'mounts', 'list', '--json'] }) });
  }
  return { engine: mount.engine, database_path: mount.database_path, database_url: mount.database_url } as GBrainConfig;
}

/**
 * The persistence config of the brain a resident serve's engine opened, resolved
 * exactly as the CLI resolves it (--brain, GBRAIN_BRAIN_ID, .gbrain-mount, mount
 * path), so a mounted serve binds the owner socket the CLI probes (#5237).
 * Host-level settings stay; only the datastore identity follows the mount.
 */
export function residentPersistenceConfig(hostConfig: GBrainConfig | null, cwd = hookSessionCwd()): GBrainConfig | null {
  const brainId = resolveBrainId(getCliOptions().brain, cwd);
  if (brainId === 'host') return hostConfig;
  const brain = persistenceConfigForBrain(hostConfig, brainId, loadMounts())!;
  return { ...hostConfig, engine: brain.engine, database_path: brain.database_path, database_url: brain.database_url } as GBrainConfig;
}

/** Reads an existing registration only. Revocation/missing credentials never create a new principal. */
export function readPersistenceCliRegistration(brainId: string): PersistenceIpcRegistration {
  // Capability validation has already constrained this filename component to a UUID.
  const id = isWriteRequestId(brainId) ? brainId.toLowerCase() : undefined;
  if (!id) {
    throw opError('permission_denied', 'Missing durable brain identity.',
      'The resident owner reported no durable brain identity, so this CLI cannot select its writer registration. Check the brain\'s persistence state; if an older owner is running, the user restarts it after upgrading.',
      { fix: readFix('Shows the brain\'s persistence identity and lock holder, read-only.', { argv: ['gbrain', 'doctor', '--json'] }) });
  }
  let value: unknown;
  try { value = JSON.parse(readFileSync(join(configDir(), 'persistence', `${id}.cli.json`), 'utf8')); }
  catch { throw new OperationError('permission_denied', 'This CLI has no readable durable writer registration for the selected brain.',
    'Register or explicitly regrant the CLI writer on this brain, then retry the same request ID.'); }
  if (!isPersistenceIpcRegistration(value) || value.lane !== 'cli') {
    throw trustedCliRequired('The local CLI writer registration is invalid.');
  }
  return value;
}

/** `room`: the owner's marks for the room the request named (GBRA-498); absent when the owner predates room marks. */
export type LocalDelegationResult = { handled: false } | { handled: true; result: unknown; room?: { meta: unknown; notices: unknown[] } };

function delegatedResult(result: unknown, roomSent: boolean): LocalDelegationResult {
  const marked = roomSent && result !== null && typeof result === 'object' && !Array.isArray(result)
    ? (result as Record<string, unknown>)[PERSISTENCE_ROOM_MARKED_KEY] as { result?: unknown; meta?: unknown; notices?: unknown } | undefined : undefined;
  if (!marked || typeof marked !== 'object') return { handled: true, result };
  return { handled: true, result: marked.result, room: { meta: marked.meta, notices: Array.isArray(marked.notices) ? marked.notices : [] } };
}

/** How long a caller waits for a serve that already holds the datastore to bind its owner socket. */
export const OWNER_STARTUP_WAIT_MS = 3_000;

/**
 * The resident owner's capabilities. A `gbrain serve` takes the datastore lock before it binds its persistence
 * socket (the MCP handshake sits in between), so a call that lands in that window finds a serve holder and no
 * socket. That is an owner starting, not an owner gone: the probe is repeated for a bounded wait while the same
 * serve still holds the lock; a holder that is not a serve, a released lock or any answer other than "no socket"
 * ends the wait at once. Never falls through to the engine path.
 */
async function residentOwnerCapabilities(socketPath: string, databasePath: string, holder: ReturnType<typeof inspectLockHolder>,
  startupWaitMs = OWNER_STARTUP_WAIT_MS): Promise<PersistenceIpcCapabilities> {
  const deadline = Date.now() + startupWaitMs;
  for (;;) {
    try { return await requestPersistenceCapabilities(socketPath); }
    catch (error) {
      const starting = error instanceof PersistenceIpcTransportError && !error.sent && holder.serve === true && Date.now() < deadline;
      if (!starting) throw error;
      await new Promise(resolve => setTimeout(resolve, 100));
      const again = inspectLockHolder(databasePath);
      if (!again.held || again.serve !== true || again.pid !== holder.pid) throw error;
    }
  }
}

/** Administration uses a separate CLI-only envelope and never manufactures a new credential. */
export async function maybeDelegateLocalAdministration(
  operation: PersistenceAdminOperation, params: Record<string, unknown>, config: GBrainConfig,
  options: { timeoutMs?: number; startupWaitMs?: number } = {},
): Promise<LocalDelegationResult> {
  if (config.engine !== 'pglite' || !config.database_path || config.database_url) return { handled: false };
  const holder = inspectLockHolder(config.database_path);
  if (!holder.held) return { handled: false };
  const socketPath = persistenceSocketPathForConfig(config);
  if (!socketPath) throw noDiscoveryPath('The PGLite owner has no persistence discovery path.', holder);
  const capability = await residentOwnerCapabilities(socketPath, config.database_path, holder, options.startupWaitMs);
  if (!ownerAdministers(capability, operation)) throw new OperationError('owner_unavailable',
    'The running owner does not support this local administration command.', 'Upgrade and restart the owner before administering this brain.');
  const registration = readPersistenceCliRegistration(capability.brain_id);
  const result = await requestPersistenceAdministration(socketPath, {
    version: 1, kind: 'administration', brain_id: capability.brain_id, operation, params, registration,
  }, options.timeoutMs);
  return { handled: true, result };
}

/**
 * Mutates params only to retain a generated request ID across local/IPC paths.
 * False means no resident process owns this selected brain; the normal engine path
 * may connect. Once a resident owner is observed (a serve holder, or a socket
 * that answered), every failure is final here: never fall through after an
 * unavailable owner socket or a lost acknowledgment.
 */
async function operationOwnsSource(operation: string): Promise<boolean> {
  const { operationsByName } = await import('../operations.ts');
  const op = operationsByName[operation];
  return op !== undefined && opOwnsSource(op);
}

export async function maybeDelegateLocalOperation(
  operation: string,
  params: Record<string, unknown>,
  hostConfig: GBrainConfig | null,
  options: { brain?: string | null; source?: string | null; cwd?: string; timeoutMs?: number; writeWaitMs?: number; startupWaitMs?: number; room?: string } = {},
): Promise<LocalDelegationResult> {
  if (!isPersistenceIpcOperation(operation)) return { handled: false };
  if (isPersistenceIpcMutation(operation)) {
    params.request_id = parseWriteRequestId(params.request_id) ?? randomUUID();
  }
  const cwd = options.cwd ?? process.cwd();
  const brainId = resolveBrainId(options.brain, cwd);
  const config = persistenceConfigForBrain(hostConfig, brainId, brainId === 'host' ? [] : loadMounts());
  if (config?.engine !== 'pglite' || !config.database_path || config.database_url) return { handled: false };
  const holder = inspectLockHolder(config.database_path);
  if (!holder.held) return { handled: false };
  const socketPath = persistenceSocketPathForConfig(config);
  if (!socketPath) throw noDiscoveryPath('The selected PGLite owner has no persistence discovery path.', holder, brainId);

  // An op that owns `source` (claim or timeline provenance) gets it on the wire, never as routing scope.
  const sourceInParams = options.source === undefined && !(await operationOwnsSource(operation));
  // GBRA-585: a write's source_id is its target, so the owner builds the write's grant on that source, as the direct path does.
  const writeTarget = isPersistenceIpcMutation(operation) && typeof params.source_id === 'string' ? params.source_id : null;
  const explicit = options.source ?? (sourceInParams && typeof params.source === 'string' ? params.source : writeTarget);
  const source = resolveSourceIdEngineFree(explicit, cwd);
  const wireParams = { ...params };
  // These belong to the CLI context/renderer, not the operation schema.
  if (sourceInParams) delete wireParams.source;
  delete wireParams.json;
  let capability: PersistenceIpcCapabilities;
  try { capability = await residentOwnerCapabilities(socketPath, config.database_path, holder, options.startupWaitMs); }
  catch (error) {
    // A holder that is not a serve and answers no owner socket is another
    // command, such as a concurrent CLI call: the engine path waits for its lock.
    if (error instanceof PersistenceIpcTransportError && holder.serve === false) return { handled: false };
    throw error;
  }
  if (!capability.operations.includes(operation)) {
    throw new OperationError('owner_unavailable', `The running persistence owner does not support '${operation}'.`,
      'Upgrade and restart the owner, then retry with the same request ID.');
  }
  const registration = readPersistenceCliRegistration(capability.brain_id);
  const roomSent = options.room !== undefined && options.room.length <= PERSISTENCE_ROOM_MAX_CHARS && capability.room === true;
  const request = { version: 1 as const, kind: 'operation' as const, brain_id: capability.brain_id,
    operation, params: wireParams, registration, routing: { source, cwd }, ...(roomSent ? { room: options.room } : {}) };
  if (!isPersistenceIpcMutation(operation)) return delegatedResult(await requestPersistenceOperation(socketPath, request, options.timeoutMs), roomSent);
  // #5232: the owner waits the caller's wait within one transport deadline; an
  // owner without `write_wait` waits its own bound and the replay keeps the rest.
  const waitMs = options.writeWaitMs ?? currentCliWriteWait().waitMs;
  const deadline = Date.now() + waitMs;
  const result = await replayWhilePending(() => {
    const budget = writeExchangeBudget(Math.max(0, deadline - Date.now()), options.timeoutMs);
    return requestPersistenceOperation(socketPath,
      capability.write_wait ? { ...request, write_wait_ms: budget.waitMs } : request, budget.timeoutMs);
  }, waitMs);
  return delegatedResult(result, roomSent);
}