Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.5 KB
Raw Blame
/**
 * #5232: how long a caller waits for an admitted write to commit, and the CLI
 * exit verdict when the wait ends first. Engine-free: the CLI resolves these
 * before it knows whether a resident owner, a remote server or its own engine
 * will run the write.
 */
import { loadConfig, type GBrainConfig } from '../config.ts';
import { getCliOptions } from '../cli-options.ts';
import { PENDING_WRITE_EXIT_CODE } from '../exit-codes.ts';
import { OperationError } from '../ops/contract.ts';
import { pinRouting, type FixRouting } from '../fix-routing.ts';
import { admittedPendingReceipt, type WriteReceipt } from './types.ts';
import { WIRE_WRITE_WAIT_MAX_MS } from './params.ts';
import { shellQuote } from '../shell-quote.ts';

/** Agent and server callers keep the historical bounded wait. */
export const AGENT_WRITE_WAIT_MS = 5_000;
/** CLI default: long enough for a normal commit over a remote pooler (#5232 measured ~8 s). */
export const CLI_WRITE_WAIT_MS = 30_000;
export const MAX_WRITE_WAIT_MS = 600_000;
/** Transport budget beyond the wait for identity checks and admission (O-DX-1). */
export const WRITE_ADMISSION_HEADROOM_MS = 15_000;
export const WRITE_WAIT_ENV = 'GBRAIN_WRITE_WAIT_MS';
export const WRITE_WAIT_CONFIG_KEY = 'persistence.write_wait_ms';
export const ACCEPT_PENDING_ENV = 'GBRAIN_ACCEPT_PENDING';

export const WRITE_EXIT_DOCS = 'docs/protocol/MEMORY_VERBS_v1.md#cli-exit-status-for-writes';

function invalidWriteWait(where: string, value: unknown): OperationError {
  return new OperationError('invalid_write_wait',
    `${where} must be a whole number of milliseconds from 0 to ${MAX_WRITE_WAIT_MS} (got ${JSON.stringify(value)}).`,
    where === WRITE_WAIT_ENV ? `unset ${WRITE_WAIT_ENV}, or set it to e.g. 30000` : `gbrain config set ${WRITE_WAIT_CONFIG_KEY} 30000`,
    'docs/guides/write-refusals.md#invalid_write_wait');
}

function parseMs(value: unknown, where: string): number | null {
  if (value === undefined || value === null || value === '') return null;
  const n = typeof value === 'number' ? value : typeof value === 'string' && /^\d+$/.test(value.trim()) ? Number(value) : NaN;
  if (!Number.isSafeInteger(n) || n < 0 || n > MAX_WRITE_WAIT_MS) throw invalidWriteWait(where, value);
  return n;
}

/**
 * #6007: a caller's `wait_ms` on a write (total reply deadline from arrival).
 * Absent → undefined (the context default applies). Outside 0-30000 → the
 * same invalid_write_wait refusal the CLI uses, before anything is admitted.
 */
export function parseWireWriteWaitMs(value: unknown): number | undefined {
  if (value === undefined || value === null) return undefined;
  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0 || value > WIRE_WRITE_WAIT_MAX_MS) {
    throw new OperationError('invalid_write_wait',
      `wait_ms must be a whole number of milliseconds from 0 to ${WIRE_WRITE_WAIT_MAX_MS} (got ${JSON.stringify(value)}); nothing was written.`,
      `Resubmit the same write with the same request_id and wait_ms between 0 and ${WIRE_WRITE_WAIT_MAX_MS} (for example 25000), or omit wait_ms for the 5000 ms default.`,
      'docs/guides/write-refusals.md#invalid_write_wait');
  }
  return value;
}

/** CLI write wait: `--wait <s>` > GBRAIN_WRITE_WAIT_MS > persistence.write_wait_ms (file plane) > 30 s. */
export function resolveCliWriteWaitMs(opts: {
  flagMs?: number | null; env?: NodeJS.ProcessEnv; config?: GBrainConfig | null;
} = {}): number {
  if (opts.flagMs !== undefined && opts.flagMs !== null) return opts.flagMs;
  const env = opts.env ?? process.env;
  return parseMs(env[WRITE_WAIT_ENV], WRITE_WAIT_ENV)
    ?? parseMs(opts.config?.persistence?.write_wait_ms, WRITE_WAIT_CONFIG_KEY)
    ?? CLI_WRITE_WAIT_MS;
}

/** An explicitly configured wait (`--wait`, GBRAIN_WRITE_WAIT_MS, persistence.write_wait_ms), else `fallbackMs`. */
export function configuredWriteWaitMs(fallbackMs: number): number {
  const flagMs = getCliOptions().writeWaitMs;
  if (flagMs !== undefined && flagMs !== null) return flagMs;
  return parseMs(process.env[WRITE_WAIT_ENV], WRITE_WAIT_ENV)
    ?? parseMs(loadConfig()?.persistence?.write_wait_ms, WRITE_WAIT_CONFIG_KEY)
    ?? fallbackMs;
}

/** The wait and pending opt-in this CLI invocation resolved. */
export function currentCliWriteWait(): { waitMs: number; acceptPending: boolean } {
  const cli = getCliOptions();
  return { waitMs: resolveCliWriteWaitMs({ flagMs: cli.writeWaitMs, config: loadConfig() }), acceptPending: acceptPendingRequested(cli.acceptPending) };
}

/** A wire-requested wait is honored only within the documented bound. */
export function boundedWriteWaitMs(value: unknown): number | undefined {
  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
    ? Math.min(value, MAX_WRITE_WAIT_MS) : undefined;
}

/**
 * One transport exchange for a write: an explicit `--timeout` bounds the
 * exchange, so the owner is asked to stop waiting early enough to return a
 * pending receipt before that deadline. Otherwise the deadline is the wait
 * plus admission headroom, so a slow commit is never an unknown submission.
 */
export function writeExchangeBudget(waitMs: number, explicitTimeoutMs?: number | null): { waitMs: number; timeoutMs: number } {
  if (explicitTimeoutMs === undefined || explicitTimeoutMs === null) return { waitMs, timeoutMs: waitMs + WRITE_ADMISSION_HEADROOM_MS };
  return { waitMs: Math.max(0, Math.min(waitMs, explicitTimeoutMs - WRITE_ADMISSION_HEADROOM_MS)), timeoutMs: explicitTimeoutMs };
}

/** `--accept-pending` / `--no-accept-pending` beat GBRAIN_ACCEPT_PENDING=1. */
export function acceptPendingRequested(flag: boolean | null | undefined, env: NodeJS.ProcessEnv = process.env): boolean {
  if (flag !== undefined && flag !== null) return flag;
  return /^(1|true|yes|on)$/i.test(env[ACCEPT_PENDING_ENV]?.trim() ?? '');
}

/** The admitted, still-pending receipt carried by a thrown write error, if any. */
export function pendingReceiptOf(error: unknown): WriteReceipt | null {
  const json = (error as { toJSON?: () => unknown } | null)?.toJSON;
  if (typeof json !== 'function') return null;
  try { return admittedPendingReceipt(json.call(error)); } catch { return null; }
}

/**
 * GBRA-248: `--accept-pending` covers a write that will commit on its own, not
 * one queued for an owner host that runs no consumer and has been quiet past
 * the stale window (a moved or restored brain, a replaced container home).
 */
export function acceptPendingCovers(receipt: WriteReceipt | null | undefined): boolean {
  return !receipt?.diagnostic?.owner;
}

/**
 * The one CLI exit verdict for a failed write (O-DX-1/O-ENG-1): an admitted
 * pending receipt exits PENDING_WRITE_EXIT_CODE (0 with the opt-in, unless the
 * receipt names a stale owner); every other error, including a pre-admission
 * `unavailable`, exits 1.
 */
export function writeErrorExitCode(error: unknown, acceptPending: boolean): number {
  const receipt = pendingReceiptOf(error);
  if (!receipt) return 1;
  return acceptPending && acceptPendingCovers(receipt) ? 0 : PENDING_WRITE_EXIT_CODE;
}

/**
 * The copy-paste poll command for a pending receipt (#6255): the same
 * `gbrain write-request [--brain <id>] -- <request_id>` argv the error
 * envelope's `fix` carries. A `fix.argv` that reads this receipt wins, so the
 * two never disagree; otherwise the receipt command is pinned to `routing`.
 * Each argument is shell-quoted, so the line pastes as the argv it names.
 */
export function pollCommand(requestId: string, fix?: { argv?: readonly string[] }, routing?: FixRouting): string {
  const argv = fix?.argv?.[0] === 'gbrain' && fix.argv[1] === 'write-request' && fix.argv.includes(requestId)
    ? fix.argv : pinRouting(['gbrain', 'write-request', '--', requestId], routing);
  return argv.map(shellQuote).join(' ');
}

/**
 * Keep the caller's wait across transports that wait less than it (an older
 * owner, or a remote server's own bounded wait): replay the identical request
 * (same request_id, so nothing new is admitted) until it settles or the wait
 * is spent. Only an admitted pending receipt is replayed.
 */
export async function replayWhilePending<T>(send: () => Promise<T>, waitMs: number,
  sleep: (ms: number) => Promise<void> = ms => new Promise(resolve => setTimeout(resolve, ms))): Promise<T> {
  const deadline = Date.now() + waitMs;
  for (;;) {
    try { return await send(); }
    catch (error) {
      const receipt = pendingReceiptOf(error);
      const remaining = deadline - Date.now();
      if (!receipt || remaining <= 0) throw error;
      await sleep(Math.min(Math.max(receipt.retry_after_ms ?? 1000, 50), remaining));
    }
  }
}