Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.9 KB
Raw Blame
/**
 * Interaction primitive (agent operator contract v1, A5): whether a human can
 * answer a prompt, prompt reads that treat EOF/timeout as a decline, and
 * bounded payload reads from stdin. Neither GBRAIN_INTERACTIVE nor
 * GBRAIN_NON_INTERACTIVE implies consent.
 *
 * Also the one home of the legacy prompt helpers (`promptLine`,
 * `promptLineStderr`, `promptYesNo`); `src/core/cli-util.ts` and
 * `src/core/confirm-prompt.ts` re-export them for one release.
 */

import { fstatSync, readFileSync } from 'node:fs';
import { createInterface } from 'node:readline';
import { PAGE_MAX_BYTES } from './page-size-policy.ts';

export interface InteractiveProbe {
  env?: NodeJS.ProcessEnv;
  stdinIsTTY?: boolean; stdoutIsTTY?: boolean;
}

/** Process-scoped markers only: a variable set inside an agent's child process, never a user-level home dir. */
const AGENT_MARKERS = ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CODEX_SANDBOX', 'CODEX_CI', 'OPENCODE', 'OPENCODE_PID'] as const;

/** The first agent-process marker present in env, or null. Never CODEX_HOME (a human's shell sets it). */
export function agentProcessMarker(env: NodeJS.ProcessEnv = process.env): string | null {
  for (const k of AGENT_MARKERS) if (env[k]) return k;
  return null;
}

const truthy = (v: string | undefined) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';

let forcedNoticePrinted = false;

/** One stderr line per process when an agent marker or CI turns off prompts on two TTYs. */
function noteForcedNonInteractive(cause: string): void {
  if (forcedNoticePrinted) return;
  forcedNoticePrinted = true;
  process.stderr.write(
    `[gbrain] prompts are off: ${cause} is set, so confirmations decline by default. ` +
    `A human at this terminal can set GBRAIN_INTERACTIVE=1 to answer prompts.\n`,
  );
}

export function isInteractive(probe: InteractiveProbe = {}): boolean {
  const env = probe.env ?? process.env;
  const stdinTTY = probe.stdinIsTTY ?? process.stdin.isTTY === true;
  const stdoutTTY = probe.stdoutIsTTY ?? process.stdout.isTTY === true;
  if (!stdinTTY || !stdoutTTY) return false;
  if (truthy(env.GBRAIN_INTERACTIVE)) return true;
  if (truthy(env.GBRAIN_NON_INTERACTIVE)) return false;
  const cause = truthy(env.CI) ? 'CI' : agentProcessMarker(env);
  if (cause === null) return true;
  noteForcedNonInteractive(cause);
  return false;
}

export type LineRead = { kind: 'line'; text: string } | { kind: 'eof' } | { kind: 'timeout' };

interface LineSource {
  prompt: string;
  timeoutMs?: number;
  input?: NodeJS.ReadableStream;
  output?: NodeJS.WritableStream;
}

/** An earlier reader already saw EOF (or the stream was destroyed): 'end' will never fire again. */
function streamFinished(stream: NodeJS.ReadableStream): boolean {
  const r = stream as NodeJS.ReadableStream & { readableEnded?: boolean; destroyed?: boolean };
  return r.readableEnded === true || r.destroyed === true;
}

/**
 * Read one line (trimmed) from `input`. EOF without a newline yields the
 * buffered text as the line, or `eof` when nothing arrived. Bytes after the
 * newline are pushed back so the next prompt sees them. Always removes its
 * listeners and pauses the stream, so the process can exit afterwards.
 */
function readLineFrom(src: LineSource): Promise<LineRead> {
  const input = (src.input ?? process.stdin) as NodeJS.ReadableStream & { unshift?(chunk: Buffer): void };
  const timeoutMs = src.timeoutMs ?? 300_000;
  (src.output ?? process.stderr).write(src.prompt);
  if (streamFinished(input)) return Promise.resolve({ kind: 'eof' });
  return new Promise(resolve => {
    let buf = Buffer.alloc(0);
    let timer: ReturnType<typeof setTimeout> | null = null;
    let settled = false;
    const done = (r: LineRead, rest?: Buffer) => {
      if (settled) return;
      settled = true;
      input.removeListener('data', onData);
      input.removeListener('end', onEnd);
      input.removeListener('error', onEnd);
      if (timer) clearTimeout(timer);
      input.pause();
      if (rest?.length) { try { input.unshift?.(rest); } catch { /* best effort */ } }
      resolve(r);
    };
    const onData = (chunk: string | Buffer) => {
      buf = Buffer.concat([buf, typeof chunk === 'string' ? Buffer.from(chunk) : chunk]);
      const nl = buf.indexOf(0x0a);
      if (nl >= 0) done({ kind: 'line', text: buf.subarray(0, nl).toString('utf8').trim() }, buf.subarray(nl + 1));
    };
    const onEnd = () => done(buf.length ? { kind: 'line', text: buf.toString('utf8').trim() } : { kind: 'eof' });
    if (timeoutMs > 0) timer = setTimeout(() => done({ kind: 'timeout' }), timeoutMs);
    input.on('data', onData);
    input.once('end', onEnd);
    input.once('error', onEnd);
    input.resume();
  });
}

/**
 * Prompt read: stderr prompt; EOF/timeout = decline. Returns {kind:'eof'} at once when !isInteractive().
 * `input`/`output`/`probe` are injection seams for tests and embedders; the default is process stdin/stderr.
 */
export async function readLine(
  opts: { prompt: string; timeoutMs?: number; input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream; probe?: InteractiveProbe },
): Promise<LineRead> {
  if (!isInteractive(opts.probe)) return { kind: 'eof' };
  return readLineFrom(opts);
}

/**
 * Legacy prompt (stdout prompt, no interactivity gate). Resolves the trimmed
 * line; '' on EOF or timeout (it used to hang forever on a closed stdin).
 * @deprecated use readLine.
 */
export async function promptLine(prompt: string): Promise<string> {
  const r = await readLineFrom({ prompt, output: process.stdout });
  return r.kind === 'line' ? r.text : '';
}

/**
 * Legacy prompt that keeps stdout clean (stderr prompt, no interactivity
 * gate). Resolves the trimmed line, or `null` on EOF or after `timeoutMs`
 * (default 5 minutes). `null` is NOT the empty string ('' = user pressed Enter).
 * @deprecated use readLine.
 */
export async function promptLineStderr(prompt: string, opts: { timeoutMs?: number } = {}): Promise<string | null> {
  const r = await readLineFrom({ prompt, timeoutMs: opts.timeoutMs, output: process.stderr });
  return r.kind === 'line' ? r.text : null;
}

export interface ConfirmStreams {
  input?: NodeJS.ReadableStream;
  output?: NodeJS.WritableStream;
}

/**
 * Interactive [y/N] prompt. Resolves true on y/yes; false on anything else or EOF.
 * #4318: resolve the ANSWER first, then close the interface; the 'close'
 * listener declines only when no answer arrived (true EOF / Ctrl-D).
 */
export async function promptYesNo(question: string, streams: ConfirmStreams = {}): Promise<boolean> {
  return new Promise((resolve) => {
    const rl = createInterface({
      input: streams.input ?? process.stdin,
      output: streams.output ?? process.stdout,
    });
    let answered = false;
    rl.question(question, (answer) => {
      answered = true;
      const a = answer.trim().toLowerCase();
      resolve(a === 'y' || a === 'yes');
      rl.close();
    });
    rl.on('close', () => {
      if (!answered) resolve(false);
    });
  });
}

export type StdinRead =
  /** `raw` (only with `StdinReadOptions.raw`): the undecoded bytes, for callers that inspect binary input before decoding. */
  | { kind: 'data'; text: string; raw?: Buffer }
  | { kind: 'empty' }
  | { kind: 'timeout'; phase: 'first_byte' | 'inactivity'; bytes: number }
  | { kind: 'cancelled'; bytes: number }
  | { kind: 'error'; error: Error; bytes: number };

export interface StdinReadOptions {
  /** First-byte deadline. Default: GBRAIN_STDIN_TIMEOUT_MS, else 30 s. */
  firstByteMs?: number;
  /** Silence allowed between chunks once data flows; reset on every chunk. Default 60 s. */
  inactivityMs?: number;
  /** Byte cap; more input is an error, never a truncated success. Default: the 24 MiB page ceiling. */
  maxBytes?: number;
  signal?: AbortSignal;
  /** Also return the undecoded bytes as `raw` on a `data` result. */
  raw?: boolean;
  /** Injection seam (tests, embedders). Default: process.stdin, with a direct read for files and /dev/null. */
  stream?: NodeJS.ReadableStream;
}

const DEFAULT_FIRST_BYTE_MS = 30_000;
const FIRST_BYTE_NOTICE_MS = 5_000;
const DEFAULT_INACTIVITY_MS = 60_000;
export const DEFAULT_STDIN_MAX_BYTES = PAGE_MAX_BYTES;

function firstByteDeadlineMs(explicit: number | undefined): number {
  if (explicit !== undefined) return explicit;
  const n = Number(process.env.GBRAIN_STDIN_TIMEOUT_MS);
  return Number.isFinite(n) && n > 0 ? n : DEFAULT_FIRST_BYTE_MS;
}

const tooLarge = (maxBytes: number, bytes: number): StdinRead =>
  ({ kind: 'error', error: new Error(`stdin exceeds ${maxBytes} bytes, the most this command reads from stdin; nothing was read`), bytes });

/**
 * fd 0 as a regular file or a non-TTY character device (`< file`, `< /dev/null`)
 * never blocks, so read it directly. Returns null when fd 0 needs the stream path.
 */
function readStdinFd(maxBytes: number, withRaw: boolean): StdinRead | null {
  try {
    const st = fstatSync(0);
    if (st.isFIFO() || st.isSocket() || process.stdin.isTTY) return null;
    if (st.isFile() && st.size > maxBytes) return tooLarge(maxBytes, 0);
    const raw = readFileSync(0, { encoding: null });
    if (raw.length > maxBytes) return tooLarge(maxBytes, raw.length);
    return raw.length ? { kind: 'data', text: raw.toString('utf-8'), ...(withRaw ? { raw } : {}) } : { kind: 'empty' };
  } catch (e) {
    return { kind: 'error', error: e instanceof Error ? e : new Error(String(e)), bytes: 0 };
  }
}

/**
 * Payload read: first-byte timeout 30 s (stderr notice at 5 s), 60 s inactivity reset on progress, no total time cap.
 * EOF, timeout, cancellation and stream error are distinct results; partial input is never returned as data.
 */
export async function readStdinBounded(opts: StdinReadOptions = {}): Promise<StdinRead> {
  const maxBytes = opts.maxBytes ?? DEFAULT_STDIN_MAX_BYTES;
  if (opts.signal?.aborted) return { kind: 'cancelled', bytes: 0 };
  if (!opts.stream) {
    const direct = readStdinFd(maxBytes, opts.raw === true);
    if (direct) return direct;
  }
  const ownsStdin = !opts.stream;
  const stream: NodeJS.ReadableStream = opts.stream ?? process.stdin;
  if (streamFinished(stream)) return { kind: 'error', error: new Error('stdin was already consumed or closed'), bytes: 0 };
  const firstByteMs = firstByteDeadlineMs(opts.firstByteMs);
  const inactivityMs = opts.inactivityMs ?? DEFAULT_INACTIVITY_MS;
  const armed = (ms: number) => Number.isFinite(ms) && ms > 0;

  return new Promise<StdinRead>(resolve => {
    const chunks: Buffer[] = [];
    let bytes = 0;
    let settled = false;
    let deadline: ReturnType<typeof setTimeout> | null = null;
    let notice: ReturnType<typeof setTimeout> | null = null;

    const finish = (r: StdinRead) => {
      if (settled) return;
      settled = true;
      if (deadline) clearTimeout(deadline);
      if (notice) clearTimeout(notice);
      stream.removeListener('data', onData);
      stream.removeListener('end', onEnd);
      stream.removeListener('error', onError);
      stream.removeListener('close', onClose);
      opts.signal?.removeEventListener('abort', onAbort);
      stream.pause();
      // A still-open process stdin would keep the event loop alive after a failed read.
      if (ownsStdin && r.kind !== 'data' && r.kind !== 'empty') process.stdin.destroy();
      resolve(r);
    };
    const arm = (phase: 'first_byte' | 'inactivity', ms: number) => {
      if (deadline) clearTimeout(deadline);
      deadline = armed(ms) ? setTimeout(() => finish({ kind: 'timeout', phase, bytes }), ms) : null;
    };
    const onData = (chunk: string | Buffer) => {
      const b = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
      if (b.length === 0) return;
      if (bytes === 0 && notice) { clearTimeout(notice); notice = null; }
      bytes += b.length;
      if (bytes > maxBytes) return finish(tooLarge(maxBytes, bytes));
      chunks.push(b);
      arm('inactivity', inactivityMs);
    };
    const onEnd = () => {
      const raw = Buffer.concat(chunks);
      finish(bytes ? { kind: 'data', text: raw.toString('utf8'), ...(opts.raw ? { raw } : {}) } : { kind: 'empty' });
    };
    const onError = (e: unknown) => finish({ kind: 'error', error: e instanceof Error ? e : new Error(String(e)), bytes });
    const onClose = () => finish({ kind: 'error', error: new Error('stdin closed before end of input'), bytes });
    const onAbort = () => finish({ kind: 'cancelled', bytes });

    arm('first_byte', firstByteMs);
    if (armed(firstByteMs) && firstByteMs > FIRST_BYTE_NOTICE_MS) {
      notice = setTimeout(() => {
        notice = null;
        process.stderr.write(
          `[gbrain] waiting for stdin: no input after ${FIRST_BYTE_NOTICE_MS / 1000}s; giving up after ${Math.round(firstByteMs / 1000)}s. ` +
          `Pipe the payload or close stdin; set GBRAIN_STDIN_TIMEOUT_MS=<ms> to wait longer for the first byte.\n`,
        );
      }, FIRST_BYTE_NOTICE_MS);
    }
    opts.signal?.addEventListener('abort', onAbort, { once: true });
    stream.on('data', onData);
    stream.once('end', onEnd);
    stream.once('error', onError);
    stream.once('close', onClose);
    stream.resume();
  });
}