Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* A1 explicit routing for every CLI fix (docs/designs/AGENT_OPERATOR_WAVE.md,
* DX-7): a rendered `fix.argv` names the brain and source the failing call
* acted on, so the agent can run it later from another directory or under a
* different GBRAIN_BRAIN_ID / GBRAIN_SOURCE / .gbrain-mount / .gbrain-source
* and still act on the intended brain.
*
* The pin is applied once, at render time (`renderAction`), to every gbrain
* argv in the action (`argv`, `preview_argv`, `verify.argv`, `then`):
*
* - `--brain <id>` for commands that route through the brain axis: every
* shared op, and CLI-only commands that open their engine through the
* connect terminator or read the global brain option.
* - `--source <id>` for commands whose target source resolves through the
* ambient chain: every shared op (makeContext's resolver; ops that own a
* `source` param are excluded) and CLI-only commands whose command-table
* record declares `routes_source`.
*
* The CLI-only half is generated from the command table and each command's
* code (CLI_ROUTING_FLAGS, `bun run build:flag-registry`), so this module never
* imports the table (its lazy loaders would pull every command into any bundle
* that renders a fix); the op half is registered by src/core/operations.ts.
*
* Flags already present are kept as written; the pin goes before a bare `--`
* so it can never land in the positional lane. Over HTTP only the source id is
* pinned (a mount id is host topology; a thin client refuses `--brain`).
*/
import { CLI_FLAG_REGISTRY, CLI_ROUTING_FLAGS } from './cli-flag-registry.generated.ts';
import { ALL_SOURCES, SOURCE_ID_RE } from './source-id.ts';
export interface FixRouting { brain?: string; source?: string }
const BRAIN_ID_RE = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
const pinnableSource = (s: string) => SOURCE_ID_RE.test(s) || s === ALL_SOURCES;
const SOURCE_SELECTORS = ['--source', '--source-id', '--all-sources', '--sources'];
/** The flag a command's target source is routed through: `--source`, or `--source-id` where `--source` selects a mode (extract: fs|db). */
type SourceFlag = '--source' | '--source-id';
const SOURCE_FLAGS: readonly SourceFlag[] = ['--source', '--source-id'];
const opCommands = new Map<string, { ownsSource: boolean; scopesSourceId: boolean }>();
/**
* Shared-op CLI names (primary + aliases, hidden excluded): every op routes the brain, and `--source`
* unless the op owns a `source` param (provenance, not the target source). Called by src/core/operations.ts.
*/
export function registerOpRoutes(ops: Iterable<{ params: Record<string, unknown>; cliHints?: { name?: string; aliases?: readonly string[]; hidden?: boolean } }>): void {
for (const op of ops) {
if (!op.cliHints?.name || op.cliHints.hidden) continue;
for (const name of [op.cliHints.name, ...(op.cliHints.aliases ?? [])]) {
opCommands.set(name, { ownsSource: 'source' in op.params, scopesSourceId: 'source_id' in op.params });
}
}
}
/**
* The routing flags a command accepts AND routes through (see the module comment).
* `remote` (an HTTP render): a mount id is host topology, so `--brain` is never
* pinned there, and `--source` only where a thin client can send it (an op with a
* `source_id` scope, or a CLI command the brain host's operator runs).
*/
export function routingFlagsFor(command: string, opts: { remote?: boolean } = {}): { brain: boolean; source: SourceFlag | false } {
const accepted = CLI_FLAG_REGISTRY[command];
if (accepted) {
const routed = CLI_ROUTING_FLAGS[command] ?? [];
const source = SOURCE_FLAGS.find(flag => accepted.includes(flag) && routed.includes(flag)) ?? false;
return { brain: !opts.remote && accepted.includes('--brain') && routed.includes('--brain'), source };
}
const op = opCommands.get(command);
if (!op) return { brain: false, source: false };
return { brain: !opts.remote, source: !op.ownsSource && (!opts.remote || op.scopesSourceId) ? '--source' : false };
}
const hasFlag = (head: readonly string[], flag: string) => head.some(a => a === flag || a.startsWith(`${flag}=`));
/** Append the missing routing flags to one gbrain argv (before a bare `--`). Non-gbrain argv pass through. */
export function pinRouting(argv: readonly string[], routing: FixRouting | undefined, opts: { remote?: boolean } = {}): string[] {
if (!routing || argv[0] !== 'gbrain' || argv.length < 2) return [...argv];
const flags = routingFlagsFor(argv[1]!, opts);
const end = argv.indexOf('--');
const head = end === -1 ? argv : argv.slice(0, end);
const add: string[] = [];
if (flags.brain && routing.brain && BRAIN_ID_RE.test(routing.brain) && !hasFlag(head, '--brain')) add.push('--brain', routing.brain);
// Under `--source-id` a `--source` already present is that command's mode selector, not a source choice.
const selectors = flags.source === '--source-id' ? SOURCE_SELECTORS.filter(f => f !== '--source') : SOURCE_SELECTORS;
const pinnable = flags.source === '--source-id' ? SOURCE_ID_RE.test(routing.source ?? '') : pinnableSource(routing.source ?? '');
if (flags.source && routing.source && pinnable && !selectors.some(f => hasFlag(head, f))) {
add.push(flags.source, routing.source);
}
if (add.length === 0) return [...argv];
return end === -1 ? [...argv, ...add] : [...argv.slice(0, end), ...add, ...argv.slice(end)];
}
// ── the CLI process's resolved routing ─────────────────────────────────────
let cliProvider: (() => FixRouting | undefined) | null = null;
let resolvedSource: string | undefined;
let recording = false;
/**
* Installed by src/cli.ts once global flags are parsed: the default routing
* for every CLI-surface render in this process (cliRenderContext). Also turns
* on source recording, so the first source this invocation resolves through
* the ambient chain becomes the pinned source.
*/
export function installCliRouting(provider: () => FixRouting | undefined): void {
cliProvider = provider;
recording = true;
}
let sourceNoteScope: (() => { resolvedSource?: string } | undefined) | null = null;
/** A resident serve answering for a one-shot CLI (the warm CLI socket) records each request's first source for that CLI, not for itself. */
export function setSourceNoteScope(scope: () => { resolvedSource?: string } | undefined): void {
sourceNoteScope = scope;
}
/** Called by the source resolver: the first source an invocation resolves is the one its fixes pin. */
export function noteResolvedSource(sourceId: string): void {
const scoped = sourceNoteScope?.();
if (scoped) {
if (scoped.resolvedSource === undefined && pinnableSource(sourceId)) scoped.resolvedSource = sourceId;
return;
}
if (recording && resolvedSource === undefined && pinnableSource(sourceId)) resolvedSource = sourceId;
}
export function recordedSource(): string | undefined {
return resolvedSource;
}
export function cliRouting(): FixRouting | undefined {
try { return cliProvider?.(); } catch { return undefined; }
}
/** Test seam: drop the provider and the recorded source (registered command tables stay). */
export function __resetCliRoutingForTests(): void {
cliProvider = null;
resolvedSource = undefined;
recording = false;
}