Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.5 KB
Raw Blame
/**
 * Shared resolve-IPC listener wiring for BOTH serve transports (#4474).
 *
 * Retrieval Reflex (#1981, D9=C): on a PGLite brain, serve owns the single
 * connection, so the context engine (and the per-prompt hook command)
 * resolve salient entities THROUGH the serve over a local unix socket
 * rather than opening a second (impossible) connection. Engine-uniform
 * since #4245: Postgres brains listen too (the hook lane is engine-free by
 * design, so IPC through a serve is its only DB path there) — socket +
 * secret key off hash12(database_url) under ~/.gbrain/run via
 * resolveSocketPathForConfig.
 *
 * Pre-#4474 this block lived inline in the STDIO path (src/mcp/server.ts)
 * only, so `gbrain serve --http` — the exact posture `gbrain bootstrap
 * harness` targets — never bound the socket and every wired lifecycle hook
 * degraded to `no_serve` forever (with serve-delegated sync losing its
 * rung too). Both transports now bind through this helper.
 *
 * Best-effort by contract: failure to bind never blocks the serve.
 */
import { readPressureGate } from '../core/context/pressure.ts';
import type { Server } from 'node:net';
import type { BrainEngine } from '../core/engine.ts';
import { loadConfig } from '../core/config.ts';
import {
  resolveSocketPathForConfig,
  startResolveIpcServer,
  ensureIpcSecretForConfig,
  type IpcHandlers,
  type IpcServerOpts,
  type TurnContextRequest,
} from '../core/context/resolve-ipc.ts';
import { resolveEntitiesToPointers, logDeliveredReflexPointers } from '../core/context/retrieval-reflex.ts';
import { lexicalArmsEnabled } from '../core/context/reflex.ts';
import { VOLUNTEER_MAX_PAGES_CAP } from '../core/context/volunteer.ts';
import { assembleTurnContext, TURN_CONTEXT_DEFAULT_MAX_BYTES, type TurnContextResult } from '../core/context/turn-context.ts';
import { attachBrief, briefEnabled, BRIEF_MAX_BYTES, recordBriefDelivered, turnBrief, TURN_BRIEF_CUTOFF_MS, withBriefDeadline, type BriefClock } from '../core/context/proactive-brief.ts';

const turnBriefClock = (now = Date.now()): BriefClock => ({ now, stopAt: now + TURN_BRIEF_CUTOFF_MS });
import { proactiveEligibility } from '../core/eligibility/registry.ts';
import { readHotMemorySessionOnly } from '../core/facts/meta-hook.ts';
import { makeContextPackIpcHandler } from './context-pack-handler.ts';
import { logBriefDeliveryFireAndForget, logTurnContextDeliveryFireAndForget } from '../core/context/volunteer-events.ts';
import { persistenceSocketPathForConfig, startPersistenceIpcServer, type PersistenceIpcProvider, type PersistenceIpcBinding } from '../core/persistence/ipc.ts';
import { residentPersistenceConfig } from '../core/persistence/local-client.ts';
import { findIpcPathTooLong, ipcPathTooLongMessage } from '../core/context/ipc-path-too-long.ts';

export interface ResolveIpcBinding {
  /** The bound listener for this serve's own resolve socket, or null while it is not bound (best-effort). */
  readonly server: Server | null;
  /** The socket path the listener bound (null while not bound). */
  readonly socketPath: string | null;
  /** Dedicated persistence listener; its larger frames never enter hook handlers. */
  persistence?: PersistenceIpcBinding;
  /** Idempotent teardown: close the listener + reap the socket file. */
  close(): void;
}

const NULL_BINDING: ResolveIpcBinding = { server: null, socketPath: null, close: () => {} };

/** #6647: a serve that could not bind a resolve socket retries it this often (plus jitter). */
export const RESOLVE_IPC_REBIND_INTERVAL_MS = 30_000;
const RESOLVE_IPC_REBIND_JITTER_MS = 5_000;

function defaultRebindDelayMs(): number {
  return RESOLVE_IPC_REBIND_INTERVAL_MS + Math.floor(Math.random() * RESOLVE_IPC_REBIND_JITTER_MS);
}

/**
 * The turn_context assembly the serve answers with (minus the pressure gate).
 * Wave 5 D5 proactive brief (default off): the legacy block is assembled
 * first and stands on its own; when `context.proactive_brief` is on, the
 * brief runs in what is left of a request-start cutoff (its queries stop once
 * it passes; `clock` defaults to that cutoff from now), inside a byte reservation taken from the legacy block, and
 * leads the text. Off, this is the legacy assembly exactly. Always assembles
 * against the serve's OWN registered source [CX2-10].
 */
export async function turnContextWithBrief(engine: BrainEngine, sourceId: string, req: TurnContextRequest, clock: BriefClock = turnBriefClock()): Promise<TurnContextResult> {
  const briefOn = await briefEnabled(engine);
  const base = await assembleTurnContext(engine, {
    sourceId,
    window: req.window ?? [],
    priorContextText: req.priorContextText,
    sessionId: req.sessionId,
    sessionOnly: await readHotMemorySessionOnly(engine),
    maxBytes: briefOn ? Math.max(1024, (req.maxBytes ?? TURN_CONTEXT_DEFAULT_MAX_BYTES) - BRIEF_MAX_BYTES - 2) : req.maxBytes,
    // Per-request config read: `gbrain serve` is long-running, and the
    // lexical-arms switch reverts a false-fire regression on the NEXT turn
    // (adversarial F3).
    lexicalArms: lexicalArmsEnabled(loadConfig()),
  });
  const last = req.window?.at(-1);
  const prompt = last?.role === 'user' ? last.text : '';
  if (!briefOn || !prompt.trim()) return base;
  const brief = await withBriefDeadline(proactiveEligibility({ engine }, 'hook.user_prompt').then((eligibility) => turnBrief(engine, {
    sourceId, prompt, sessionId: req.sessionId, priorContextText: req.priorContextText, eligibility, clock,
  })), clock);
  return attachBrief(base, brief);
}

/** A delivered block's brief: record its ids for the session, then log them. No-op without a brief. */
export function briefDelivered(engine: BrainEngine, sourceId: string, result: TurnContextResult, sessionId: string | undefined): void {
  if (!result.brief) return;
  recordBriefDelivered(sourceId, sessionId, result.brief.items.map((i) => i.id));
  logBriefDeliveryFireAndForget(engine, result.brief, sessionId);
}

/**
 * Bind the resolve/turn_context/context_pack (+ delegated sync/sweep) IPC
 * listener for a running serve. `defaultSource` is the serve's bound source
 * (resolveMcpStdioSourceScope) — the IPC layer rejects requests naming any
 * other source ([CX2-10]).
 */
/**
 * 2026-08 fix wave (ship security review): the volunteer probe claim is a
 * WIRE FIELD, so it is honored only when the request is volunteer-SHAPED —
 * slug-only suppression + the wide ungated pool cap volunteerStage always
 * sends. A normal pointer resolve stamping probe:'volunteer' to evade
 * delivery telemetry keeps logging. Exported for direct unit testing.
 *
 * ADVISORY, not a control (adversarial review, 2026-09): the shape is
 * publicly reproducible, so a client that deliberately sends the full
 * volunteer shape receives up to the wide pool with no delivery log line.
 * Delivery logging is precision/recall telemetry — the caller already holds
 * read access to the same pages via ordinary ops — but treat the audit
 * trail as best-effort until the server-side volunteer-report IPC kind
 * (filed) closes it.
 */
export function isVolunteerProbeShaped(req: {
  probe?: string;
  suppression?: string;
  maxPointers?: number;
} | undefined): boolean {
  return (
    req?.probe === 'volunteer' &&
    req.suppression === 'slug-only' &&
    req.maxPointers === VOLUNTEER_MAX_PAGES_CAP * 2
  );
}

export async function bindResolveIpcForServe(
  engine: BrainEngine,
  defaultSource: string,
  persistenceProvider?: PersistenceIpcProvider,
  opts: {
    rememberCallable?: boolean | (() => boolean);
    /** #7599: a lean serve (a read-only stdio serve on Postgres, `readOnlyServeSkipsResidentDuties`) registers no delegated sync, nudge or sweep kind (clients get the polite refusal); PGLite keeps them. #7612: it binds only its read socket, never the source or legacy socket a read-write serve answers delegation on. */
    lean?: boolean;
    /** Delay before each re-bind attempt of a socket this serve does not hold; tests inject a short one. */
    rebindDelayMs?: () => number;
  } = {},
): Promise<ResolveIpcBinding> {
  let persistence: PersistenceIpcBinding | null = null;
  try {
    const cfg = loadConfig();
    // #5042: this serve's own source-keyed socket, plus the legacy URL-only
    // socket when it is free (older hooks and hooks naming no source).
    // #7612: a lean serve on Postgres binds its read socket alone, so it can
    // never hold either delegation-capable socket ahead of a read-write serve.
    const readSocket = opts.lean ? resolveSocketPathForConfig(cfg, 'read', defaultSource) : null;
    const resolveSocket = readSocket ?? resolveSocketPathForConfig(cfg, 'resolve', defaultSource);
    const legacySocket = readSocket ?? resolveSocketPathForConfig(cfg);
    if (!resolveSocket || !legacySocket) return NULL_BINDING;

    // #6573: a socket path the OS cannot bind (even after the per-user
    // run-dir fallback) is reported once, typed, and never retried.
    const tooLong = (path: string | null) => {
      const problem = findIpcPathTooLong([path]);
      if (problem) process.stderr.write(`[resolve-ipc] ${ipcPathTooLongMessage(problem)}\n`);
      return problem !== null;
    };

    // The owner socket follows the brain the engine opened, which may be a mount (#5237).
    const owner = residentPersistenceConfig(cfg);
    if (persistenceProvider && owner?.engine === 'pglite') {
      const persistenceSocket = persistenceSocketPathForConfig(owner);
      if (persistenceSocket && !tooLong(persistenceSocket)) {
        try { persistence = await startPersistenceIpcServer(persistenceSocket, persistenceProvider); }
        catch {
          process.stderr.write('[persistence-ipc] listener unavailable; local callers will receive owner_unavailable.\n');
        }
      }
    }

    // [S3#6] turn_context requires the shared secret from the config-keyed
    // path (created 0600 here if absent). If the secret can't be
    // provisioned, turn_context stays fail-closed ('unauthorized') while
    // the secret-free resolve kind keeps working.
    let ipcSecret: string | undefined;
    try {
      ipcSecret = ensureIpcSecretForConfig(cfg) ?? undefined;
    } catch { /* turn_context disabled; resolve unaffected */ }

    // Serve-delegated sync kinds — built in their OWN try/catch so a
    // runner import/registration failure can never take resolve /
    // turn_context / context_pack down with it (this whole block's shared
    // catch would otherwise swallow the error and start NO listener).
    // Kill switch: GBRAIN_SERVE_SYNC_IPC=0 → the kinds are simply not
    // registered and clients get 'unsupported_kind' (the polite refusal).
    const delegation = process.env.GBRAIN_SERVE_SYNC_IPC !== '0' && !opts.lean;
    let syncHandlers: Pick<IpcHandlers, 'sync_start' | 'sync_status' | 'sync_abort' | 'sync_nudge'> = {};
    if (delegation) {
      try {
        const runner = await import('../core/serve-sync-runner.ts');
        syncHandlers = {
          sync_start: (req) =>
            runner.startDelegatedSync(engine, req.options, req.clientToken, {
              boundSourceId: defaultSource,
              // #6317: the CLI's writer registration for a managed drain (verified by the runner, never here).
              registration: req.registration,
            }),
          sync_status: (req) => runner.getDelegatedSyncStatus(req.jobId, typeof req.afterLine === 'number' ? req.afterLine : 0),
          sync_abort: (req) => runner.abortDelegatedSync(req.jobId),
          // GBRA-133 PR 2a: a wanted marker recorded through this serve, acknowledged, and a nudge to its notifier.
          sync_nudge: async (req) => (await import('../core/notifier/nudge.ts')).recordSyncNudge(engine, req),
        };
      } catch (e) {
        process.stderr.write(
          `[serve-sync] handlers unavailable: ${e instanceof Error ? e.message : String(e)}\n`,
        );
      }
    }
    // Serve-delegated maintenance sweep (#677) — same posture, own
    // try/catch so a runner failure never takes the other kinds down.
    // Shares the GBRAIN_SERVE_SYNC_IPC kill switch (one delegation family).
    let sweepHandlers: Pick<IpcHandlers, 'sweep_start' | 'sweep_status'> = {};
    if (delegation) {
      try {
        const sweepRunner = await import('../core/serve-sweep-runner.ts');
        sweepHandlers = {
          sweep_start: (req) =>
            sweepRunner.startDelegatedSweep(engine, req.options, req.clientToken, {
              boundSourceId: defaultSource,
            }),
          sweep_status: (req) => sweepRunner.getDelegatedSweepStatus(req.jobId),
        };
      } catch (e) {
        process.stderr.write(
          `[serve-sweep] handlers unavailable: ${e instanceof Error ? e.message : String(e)}\n`,
        );
      }
    }

    const handlers: IpcHandlers = {
      // [CX2-10] Bound-source posture for BOTH kinds: the IPC layer
      // rejects any resolve/turn_context request naming a source other
      // than boundSourceId ('source_mismatch'), so the only sourceId that
      // reaches this handler is the bound one or absent — and the handler
      // resolves against the server's OWN registered source regardless.
      resolve: (req) =>
        resolveEntitiesToPointers(
          engine,
          defaultSource,
          req.candidates ?? [],
          {
            priorContextText: req.priorContextText,
            maxPointers: req.maxPointers,
            suppression: req.suppression,
            // v0.46.15 kill switch: either side may disable — a client
            // `false` wins, else the server's own file-config gate.
            // Config is re-read PER REQUEST (adversarial F3): `gbrain
            // serve` is long-running, and the switch's whole value is
            // reverting a false-fire regression on the NEXT TURN with a
            // config edit — a startup snapshot would freeze it until a
            // serve restart. loadConfig is a file read (~1ms) inside the
            // 400ms IPC budget.
            lexicalArms: req.lexicalArms === false ? false : lexicalArmsEnabled(loadConfig()),
          },
        ),
      // IPC v2 [ENG-3]: per-turn context assembly for the hook command.
      // [CX2-10] Always assembles against the server's OWN registered
      // source — cross-source requests are rejected in the IPC layer via
      // boundSourceId below, and the handler never honors a caller source.
      turn_context: async (req) => ({
        ...await turnContextWithBrief(engine, defaultSource, req),
        // Context-pressure gate for the harness hook (pressure.ts); a surface without remember never warns.
        pressure: await readPressureGate(engine, typeof opts.rememberCallable === 'function' ? opts.rememberCallable() : opts.rememberCallable ?? true),
      }),
      // v0.45.7 ambient recall: boundary context pack. Extracted to
      // context-pack-handler.ts (directly testable against a real engine);
      // the runtime owns entity merge, banking, the since-cursor, and the
      // complete-pack-only monotonic cursor advance.
      context_pack: makeContextPackIpcHandler(engine, defaultSource),
      ...syncHandlers,
      ...sweepHandlers,
    };
    const serverOpts: IpcServerOpts = {
      // The IPC resolve path IS the ambient reflex channel. Logging happens
      // at DELIVERY (post-write), not inside the resolver — a block the
      // client's 250ms budget abandoned was never injected, and counting it
      // would corrupt the volunteered-vs-used precision stats (red-team).
      // Volunteer-stage PROBE resolves (wide ungated pool) are skipped for
      // the same reason: the pool is not injected pointers. NOTE (ship
      // security review): on the PGLite/IPC rung the gated survivors are
      // NOT re-logged anywhere (the client has no engine handle) — openclaw
      // volunteer events cover the direct-Postgres rung only, see
      // reflex.ts. The probe claim is a WIRE FIELD, so it is honored only
      // when the request is volunteer-SHAPED (slug-only suppression + the
      // wide volunteer pool cap): a normal pointer resolve stamping
      // probe:'volunteer' to evade delivery telemetry still logs.
      onDelivered: (block, req) => {
        if (isVolunteerProbeShaped(req)) return;
        logDeliveredReflexPointers(engine, block.pointers);
      },
      // The hook lane's feedback loop (#2095 closed over turn_context):
      // the delivered block's post-trim volunteered pages + pointers land
      // in context_volunteer_events under the request's channel. Body
      // lives in volunteer-events.ts (logTurnContextDeliveryFireAndForget)
      // so the shipped wiring is unit-testable.
      // Wave 5 D5: a delivered brief (UserPromptSubmit or SessionStart) is
      // ledgered for repeat suppression and logged under channel 'brief'.
      onTurnContextDelivered: (result, req) => {
        logTurnContextDeliveryFireAndForget(engine, result, req);
        briefDelivered(engine, defaultSource, result, req.sessionId);
      },
      onContextPackDelivered: (result, req) => briefDelivered(engine, defaultSource, result, req.sessionId),
      boundSourceId: defaultSource,
      secret: ipcSecret,
    };
    // #6647: every socket this serve could not bind (its source socket, the
    // legacy socket) is retried on its own unref'd timer through the same
    // startResolveIpcServer, which still defers to a live or unknown owner
    // (#4896), so a surviving serve takes over only once the owner probes
    // dead. Bind attempts and close() run one at a time per serve; a bind
    // that completes after close() is closed at once. Persistence is never
    // re-set-up here.
    const slots = [resolveSocket, ...(legacySocket === resolveSocket ? [] : [legacySocket])]
      .filter(path => !tooLong(path))
      .map(path => ({ path, server: null as Server | null, timer: undefined as ReturnType<typeof setTimeout> | undefined }));
    const rebindDelayMs = opts.rebindDelayMs ?? defaultRebindDelayMs;
    let closed = false;
    let lifecycle: Promise<void> = Promise.resolve();
    const serialized = (step: () => Promise<void>): Promise<void> => (lifecycle = lifecycle.then(step, step));
    const bind = async (slot: (typeof slots)[number], retry: boolean): Promise<void> => {
      if (closed || slot.server) return;
      const server = await startResolveIpcServer(slot.path, handlers, serverOpts).catch(() => null);
      if (closed) { try { server?.close(); } catch { /* noop */ } return; }
      if (!server) { schedule(slot); return; }
      slot.server = server;
      if (retry) process.stderr.write(`[resolve-ipc] took over ${slot.path} after its previous owner exited\n`);
    };
    const schedule = (slot: (typeof slots)[number]): void => {
      if (closed) return;
      slot.timer = setTimeout(() => {
        slot.timer = undefined;
        void serialized(() => bind(slot, true));
      }, rebindDelayMs());
      slot.timer.unref?.();
    };
    await serialized(async () => { for (const slot of slots) await bind(slot, false); });

    const own = slots.find(slot => slot.path === resolveSocket);
    return {
      get server() { return own?.server ?? null; },
      get socketPath() { return own?.server ? resolveSocket : null; },
      ...(persistence ? { persistence } : {}),
      close: () => {
        if (closed) return;
        closed = true;
        for (const slot of slots) clearTimeout(slot.timer);
        // server.close() unlinks the pathname THIS listener bound; never
        // blind-unlink the path — it may belong to a newer live serve (#4896).
        for (const slot of slots) { try { slot.server?.close(); } catch { /* noop */ } }
        persistence?.close();
      },
    };
  } catch {
    if (persistence) {
      return { server: null, socketPath: null, persistence, close: () => persistence?.close() };
    }
    /* resolve IPC is best-effort; never block serve */
    return NULL_BINDING;
  }
}