Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.7 KB
Raw Blame
/**
 * The warm CLI socket's wire format: newline-delimited JSON on a Unix socket,
 * one exchange per connection. The CLI sends one request; the serve answers a
 * handshake line (accepted, or refused with a reason) and then, when accepted,
 * one result line. Both directions are size-bounded.
 */
import type { Notice } from '../agent-output.ts';
import { OperationError, opError } from '../ops/contract.ts';
import { isCliSocketIdentity, type CliSocketIdentity } from './identity.ts';

export const CLI_SOCKET_PROTOCOL = 1;
export const MAX_REQUEST_BYTES = 256 * 1024;
export const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
export const MAX_CAPTURED_OUTPUT_BYTES = 1024 * 1024;
export const CONNECT_TIMEOUT_MS = 150;
export const HANDSHAKE_TIMEOUT_MS = 1_000;
export const REQUEST_READ_TIMEOUT_MS = 2_000;
/** The cold path's read wallclock (src/cli/main.ts READ_OP_TIMEOUT_MS) when --timeout is not given. */
export const DEFAULT_READ_WALLCLOCK_MS = 180_000;
/** The longest a CLI waits on one whole exchange (or its --timeout, when shorter) before running the call itself. */
export const MAX_ROUND_TRIP_MS = 30_000;

/**
 * GBRA-156: a warm call that reached its round-trip cap answers with this retryable `timeout` error instead of
 * running the call again on the cold path. The serve sends it after cancelling the request's remaining work; the CLI
 * builds the same error when the serve never answered in time.
 */
export function warmRoundTripTimeout(command: string, ms: number, side: 'serve' | 'cli'): OperationError {
  return opError('timeout', `gbrain ${command} did not finish within ${ms} ms on the warm CLI socket${side === 'serve' ? '; the serve cancelled it' : ' (the serve did not answer)'}.`,
    'Retry the same command; pass --timeout <ms> to bound it. If it keeps timing out, look in the serve\'s stderr log for a request still running.',
    { reason: 'cli_socket_round_trip_cap', retryable: true, docs: 'docs/guides/cli-socket.md',
      why: `The warm CLI socket caps one call at ${ms} ms so a caller never waits on a request without a bound; the call returned this error instead of starting over on the slower cold path.` });
}

/** The read operations a serve answers over the socket. Everything else keeps the cold path. */
export const CLI_SOCKET_OPS = ['search', 'query', 'get_page'] as const;
export type CliSocketOp = typeof CLI_SOCKET_OPS[number];

export interface CliSocketRouting {
  /** The CLI's working directory (dotfile walk and registered-path tiers). */
  cwd: string;
  /** The CLI's GBRAIN_SOURCE; null when unset. */
  source_env: string | null;
}

export type CliSocketRequest = {
  v: 1;
  identity: CliSocketIdentity;
  /** The command word the cold path would print in its timeout line. */
  command: string;
  routing: CliSocketRouting;
  cli: { quiet: boolean; timeout_ms: number | null };
} & ({ kind: 'op'; op: CliSocketOp; params: Record<string, unknown> } | { kind: 'recall'; args: string[] });

/**
 * GBRA-175: a handshake-only probe. The serve checks the identity exactly as for a request and answers the handshake
 * line alone, running nothing, so `gbrain upgrade` can prove after a restart that the serve accepts this build.
 */
export interface CliSocketProbe { v: 1; kind: 'probe'; identity: CliSocketIdentity }

export function isCliSocketProbe(value: unknown): value is CliSocketProbe {
  return record(value) && value.v === CLI_SOCKET_PROTOCOL && value.kind === 'probe' && isCliSocketIdentity(value.identity);
}

/** A refusal for `identity_mismatch` names the identity part that differed in `mismatch` (cliSocketIdentityMismatch), never its value. */
export type HandshakeFrame = { v: 1; accepted: true } | { v: 1; accepted: false; reason: string; mismatch?: string };

export type OutputChunk = ['stdout' | 'stderr', string];

/** What every answered frame carries: the output to replay and the first source resolved (pinned in fix commands). */
interface Answered { output: OutputChunk[]; source?: string | null }

export type ResultFrame =
  | { v: 1; kind: 'result'; result: unknown; meta: Record<string, unknown> | null; notices: Notice[] } & Answered
  | { v: 1; kind: 'error'; error: Record<string, unknown> } & Answered
  | { v: 1; kind: 'fallback'; reason: string };

function record(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

/** Shape check for the serve's handshake line. */
export function isHandshakeFrame(value: unknown): value is HandshakeFrame {
  if (!record(value) || value.v !== CLI_SOCKET_PROTOCOL) return false;
  return value.accepted === true
    || (value.accepted === false && typeof value.reason === 'string' && (value.mismatch === undefined || typeof value.mismatch === 'string'));
}

function isAnswered(value: Record<string, unknown>): boolean {
  return Array.isArray(value.output)
    && value.output.every(chunk => Array.isArray(chunk) && chunk.length === 2 && (chunk[0] === 'stdout' || chunk[0] === 'stderr') && typeof chunk[1] === 'string')
    && (value.source === undefined || value.source === null || typeof value.source === 'string');
}

/** Shape check for the serve's result line: every field the CLI reads, per kind; anything else is malformed. */
export function isResultFrame(value: unknown): value is ResultFrame {
  if (!record(value) || value.v !== CLI_SOCKET_PROTOCOL) return false;
  switch (value.kind) {
    case 'result':
      return 'result' in value && (value.meta === null || record(value.meta))
        && Array.isArray(value.notices) && value.notices.every(notice => record(notice) && typeof notice.code === 'string' && typeof notice.kind === 'string' && typeof notice.why === 'string')
        && isAnswered(value);
    case 'error':
      return record(value.error) && typeof value.error.code === 'string' && typeof value.error.message === 'string' && isAnswered(value);
    case 'fallback':
      return typeof value.reason === 'string';
    default:
      return false;
  }
}

/** Shape check for an inbound request; anything else is refused before it reaches the engine. */
export function isCliSocketRequest(value: unknown): value is CliSocketRequest {
  if (!record(value) || value.v !== CLI_SOCKET_PROTOCOL || !isCliSocketIdentity(value.identity) || typeof value.command !== 'string') return false;
  const routing = value.routing;
  if (!record(routing) || typeof routing.cwd !== 'string' || !routing.cwd.startsWith('/')
    || !(routing.source_env === null || typeof routing.source_env === 'string')) return false;
  const cli = value.cli;
  if (!record(cli) || typeof cli.quiet !== 'boolean'
    || !(cli.timeout_ms === null || typeof cli.timeout_ms === 'number' && Number.isFinite(cli.timeout_ms) && cli.timeout_ms > 0)) return false;
  if (value.kind === 'op') return (CLI_SOCKET_OPS as readonly unknown[]).includes(value.op) && record(value.params);
  if (value.kind === 'recall') return Array.isArray(value.args) && value.args.every(arg => typeof arg === 'string');
  return false;
}

/** An OperationError's own fields, so the CLI can rebuild the same error and render it with the cold path's renderer. */
export function serializeOperationError(error: OperationError): Record<string, unknown> {
  const { stack: _stack, ...own } = Object.assign({}, error) as unknown as Record<string, unknown>;
  return JSON.parse(JSON.stringify({ ...own, message: error.message }));
}

export function reviveOperationError(fields: Record<string, unknown>): OperationError {
  const { code, message, suggestion, docs, name: _name, ...rest } = fields;
  const error = new OperationError(code as OperationError['code'], String(message),
    typeof suggestion === 'string' ? suggestion : undefined, typeof docs === 'string' ? docs : undefined);
  return Object.assign(error, rest);
}

/** Accumulates one newline-terminated frame from a stream, refusing past `max` bytes. */
export class FrameReader {
  private chunks: Buffer[] = [];
  private bytes = 0;
  private rest: Buffer = Buffer.alloc(0);
  constructor(private readonly max: number) {}

  /** Feeds data; returns the completed frames' text, or 'overflow'. */
  push(data: Buffer): string[] | 'overflow' {
    let buffer = this.rest.length ? Buffer.concat([this.rest, data]) : data;
    this.rest = Buffer.alloc(0);
    const frames: string[] = [];
    for (;;) {
      const newline = buffer.indexOf(10);
      if (newline === -1) break;
      const piece = buffer.subarray(0, newline);
      this.bytes += piece.length;
      if (this.bytes > this.max) return 'overflow';
      this.chunks.push(piece);
      frames.push(Buffer.concat(this.chunks).toString('utf8'));
      this.chunks = [];
      this.bytes = 0;
      buffer = buffer.subarray(newline + 1);
    }
    this.bytes += buffer.length;
    if (this.bytes > this.max) return 'overflow';
    if (buffer.length) this.chunks.push(Buffer.from(buffer));
    return frames;
  }
}