Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.8 KB
Raw Blame
/**
 * Vendor-neutral content guardrail seams.
 *
 * GBrain ingests content (markdown, code) into its retrieval layer and routes
 * queries/tool-inputs through an LLM gateway. A guardrail is an external
 * classifier — a content firewall, a PII scrubber, a prompt-injection detector —
 * that wants to *observe* the content flowing across those boundaries.
 *
 * This module exposes the seams without binding GBrain to any specific vendor.
 * Zero guardrails are registered by default; the OSS distribution ships inert.
 * Operators (or vendor plugins) register a {@link GuardrailProvider} via
 * {@link registerGuardrailProvider}, and the five hook points below await it
 * inline.
 *
 * ## Hard invariants (do not weaken these without an RFC)
 *
 * - **Observe-only.** `runGuardrails` returns `void`. Callers MUST NOT branch
 *   on any provider verdict. A guardrail cannot block, rewrite, drop, retry, or
 *   reorder GBrain behavior through this interface. Enforcement, if ever added,
 *   gets its own explicitly-named seam and its own RFC.
 * - **Fail open.** Missing config, provider throw, timeout, network error, and
 *   malformed responses are all swallowed. A broken guardrail never breaks an
 *   ingest, a query, or a tool call.
 * - **Inline await, no enqueue.** These hooks await the provider before
 *   proceeding so the classifier sees content at the exact pre-persist /
 *   pre-inference moment. Providers that want async fan-out own their own queue.
 * - **No verdict persistence.** GBrain does not write guardrail results to the
 *   DB. Providers own their own audit trail.
 * - **Content boundaries.** Hooks pass the user/ingest-facing payload only:
 *   the markdown/code body, the last user message, the expansion query, the
 *   tool input. They never pass system prompts, full chat history, tool
 *   OUTPUT, LLM output, embeddings, or multimodal/OCR/rerank payloads.
 *
 * @module guardrails
 */
import { homedir } from 'node:os';
import { isAbsolute, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import { CWD_DOTENV_REMEDIATION, cwdDotenvAssignsKey } from './env-trust.ts';

/**
 * The boundary at which a guardrail is being consulted. Stable string union so
 * providers can route/score per-surface without parsing free text.
 */
export type GuardrailHook =
  /** Markdown/text body before chunking, embedding, and page persistence. */
  | 'file_storage.markdown'
  /** Code body before code-chunking, embedding, and page persistence. */
  | 'file_storage.code'
  /** Latest user message before LLM inference (chat). */
  | 'ai_gateway.chat'
  /** Search-expansion query before the expansion model call. */
  | 'ai_gateway.expand'
  /** Tool input before pending-persist and before tool execution. */
  | 'ai_gateway.tool_input';

/**
 * One guardrail invocation. `content` is the raw text the boundary handles;
 * `metadata` is provider-opaque, JSON-compatible context (slug, source kind,
 * tool name, model id, etc.). Neither field is mutated by GBrain.
 */
export interface GuardrailInput {
  hook: GuardrailHook;
  content: string;
  metadata?: Record<string, unknown>;
}

/**
 * A registered guardrail backend. `classify` is awaited inline. Its return
 * value is intentionally `unknown` and intentionally ignored by GBrain — the
 * type exists only so providers can return a typed verdict to *their own*
 * logging/audit code. GBrain never reads it.
 */
export interface GuardrailProvider {
  /** Stable id for logs and dedupe (e.g. `"silmaril"`). */
  readonly id: string;
  classify(input: GuardrailInput): Promise<unknown> | unknown;
}

const providers = new Map<string, GuardrailProvider>();

/**
 * Register (or replace, by id) a guardrail provider. Idempotent per id so a
 * plugin re-init doesn't double-fire. No-op safe to call before any ingest.
 */
export function registerGuardrailProvider(provider: GuardrailProvider): void {
  if (!provider || typeof provider.classify !== 'function' || !provider.id) return;
  providers.set(provider.id, provider);
  // #3688 residual: the env loader counts registration EVENTS, not map
  // growth — a same-id replacement (explicitly supported above) keeps
  // providers.size constant and a size delta would misread it as zero.
  registrationEvents++;
}

/** Monotonic count of accepted registerGuardrailProvider calls (see above). */
let registrationEvents = 0;

/** Remove a previously-registered provider. Returns true if one was removed. */
export function unregisterGuardrailProvider(id: string): boolean {
  return providers.delete(id);
}

/** Test/whole-reset helper. Clears all registered providers. */
export function __resetGuardrailProvidersForTests(): void {
  providers.clear();
}

/** Whether any guardrail is registered. Lets hot paths skip work cheaply. */
export function hasGuardrails(): boolean {
  return providers.size > 0;
}

/**
 * Consult every registered guardrail for this boundary. Returns `void` — the
 * result is never surfaced to the caller, by design (observe-only invariant).
 *
 * Fail-open: a provider that throws or rejects is isolated; its failure is
 * swallowed so the ingest/inference/tool path proceeds unchanged. Empty/blank
 * content short-circuits before any provider runs.
 *
 * Inline await: when guardrails are registered, the caller awaits this. The
 * cost is bounded by each provider's own timeout discipline; GBrain does not
 * impose one here so providers can tune per-deployment latency budgets.
 */
/**
 * Thrown by {@link loadGuardrailProvidersFromEnv} when GBRAIN_GUARDRAILS_MODULE
 * is SET but unusable. Deliberately fail-CLOSED (unlike the classify path,
 * which fails open): an operator who configured a guardrail module expects a
 * firewall to be standing — silently running without it would defeat the
 * point. Callers (cli.ts) abort the process on this error.
 */
export class GuardrailLoadError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'GuardrailLoadError';
  }
}

export interface GuardrailEnvLoadResult {
  /** Providers registered by this call (0 when the env var is unset). */
  loaded: number;
  /** The module specifier that was loaded, or null when unset. */
  modulePath: string | null;
}

/**
 * #3688 — the operator wiring path. Loads guardrail providers from the module
 * named by `GBRAIN_GUARDRAILS_MODULE`: an ABSOLUTE file path or a `~/` path.
 * Accepted module shapes, all additive:
 *
 *   - `export default provider` (a single {@link GuardrailProvider})
 *   - `export default [providerA, providerB]`
 *   - `export const guardrailProviders = [...]`
 *   - `export function register(registerGuardrailProvider) { ... }` (sync or async)
 *
 * Unset env var → no-op (the OSS distribution stays inert). Set-but-broken —
 * import failure, or a module that registers zero providers — throws
 * {@link GuardrailLoadError} (fail-closed; see class doc).
 *
 * Origin checks (all throw {@link GuardrailLoadError} BEFORE any import):
 *   - cwd-relative specs (`./x`, `../x`, bare `.`) are refused — they would
 *     resolve against whatever directory the process happens to run in.
 *   - bare package specifiers (`some-pkg`, `@scope/pkg`, `pkg/sub`) are
 *     refused — in the compiled binary Bun's module walk-up starts at the
 *     CURRENT DIRECTORY, so a hostile checkout's `node_modules/<name>/` is
 *     what would load. Only an absolute or `~/` path names a module the
 *     operator chose.
 *   - when `env` is `process.env` (or `opts.cwd` is given), a spec that a cwd
 *     `.env` file assigns is refused whatever its value: Bun auto-loads those
 *     files and expands `${VAR}` inside them, so a cloned repository could
 *     otherwise pick the module. The CLI already quarantines the variable at
 *     startup (`cli-preflight.ts` → `env-trust.ts`); this is belt-and-braces
 *     for `gbrain/core/guardrails` library callers. `opts.skipCwdCheck` is
 *     for the one legitimate collision — the cwd IS the operator's config
 *     dir, so the "cwd .env" is `~/.gbrain/.env` itself (preflight decides).
 */
export async function loadGuardrailProvidersFromEnv(
  env: Record<string, string | undefined> = process.env,
  opts: { cwd?: string; skipCwdCheck?: boolean } = {},
): Promise<GuardrailEnvLoadResult> {
  const spec = env.GBRAIN_GUARDRAILS_MODULE?.trim();
  if (!spec) return { loaded: 0, modulePath: null };

  if (spec.startsWith('.')) {
    throw new GuardrailLoadError(
      `GBRAIN_GUARDRAILS_MODULE=${spec} is a cwd-relative path and is not loaded; ` +
      `use an absolute path or a ~/ path.`,
    );
  }
  const homePath = spec.startsWith('~/') || spec.startsWith('~\\');
  if (!homePath && !isAbsolute(spec)) {
    throw new GuardrailLoadError(
      `GBRAIN_GUARDRAILS_MODULE=${spec} must be an absolute path or a ~/ path (package names ` +
      `resolve from the current directory's node_modules and are not loaded).`,
    );
  }
  if (!opts.skipCwdCheck && (env === process.env || opts.cwd !== undefined) &&
      cwdDotenvAssignsKey('GBRAIN_GUARDRAILS_MODULE', opts.cwd)) {
    throw new GuardrailLoadError(
      'GBRAIN_GUARDRAILS_MODULE is assigned by a .env file in the current directory and is ' +
      `not loaded — ${CWD_DOTENV_REMEDIATION}`,
    );
  }

  // Import via file:// URL so the spec is taken literally rather than
  // resolved against this module's location.
  const target = pathToFileURL(resolve(homePath ? homedir() + spec.slice(1) : spec)).href;

  // #3688 residual: snapshot BEFORE the import, not after. A module that
  // registers its providers as a top-level side effect (calling
  // registerGuardrailProvider at import time) does so DURING the import —
  // an after-import baseline counted those registrations as zero and the
  // fail-closed zero-provider check below then rejected a module whose
  // guardrails were in fact registered and active. Counting EVENTS (not
  // providers.size) also keeps a same-id replacement — supported by
  // registerGuardrailProvider — from reading as zero.
  const before = registrationEvents;
  let mod: Record<string, unknown>;
  try {
    mod = (await import(target)) as Record<string, unknown>;
  } catch (err) {
    throw new GuardrailLoadError(
      `GBRAIN_GUARDRAILS_MODULE=${spec} failed to load: ${(err as Error)?.message ?? String(err)}`,
    );
  }
  const candidates: unknown[] = [];
  if (Array.isArray(mod.default)) candidates.push(...mod.default);
  else if (mod.default) candidates.push(mod.default);
  if (Array.isArray(mod.guardrailProviders)) candidates.push(...(mod.guardrailProviders as unknown[]));
  for (const c of candidates) {
    registerGuardrailProvider(c as GuardrailProvider);
  }
  if (typeof mod.register === 'function') {
    await (mod.register as (r: typeof registerGuardrailProvider) => unknown)(registerGuardrailProvider);
  }

  const loaded = registrationEvents - before;
  if (loaded <= 0) {
    throw new GuardrailLoadError(
      `GBRAIN_GUARDRAILS_MODULE=${spec} loaded but registered no guardrail provider ` +
      `(expected a default-exported provider, a provider array, a guardrailProviders ` +
      `export, or a register() function).`,
    );
  }
  return { loaded, modulePath: spec };
}

export async function runGuardrails(input: GuardrailInput): Promise<void> {
  if (providers.size === 0) return;
  const content = typeof input.content === 'string' ? input.content : '';
  if (!content.trim()) return;

  // Snapshot so a provider registering/unregistering mid-flight can't mutate
  // the iteration set.
  const snapshot = Array.from(providers.values());
  await Promise.all(
    snapshot.map(async (provider) => {
      try {
        await provider.classify({
          hook: input.hook,
          content,
          metadata: input.metadata,
        });
      } catch {
        // Fail open. A guardrail provider MUST NOT be able to break GBrain.
        // Provider-side logging is the provider's responsibility; GBrain does
        // not log raw content here (could itself leak the classified payload).
      }
    }),
  );
}