Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* gbrain capture — the single human-facing entrypoint for getting content
* into the brain. Replaces the confusion of "do I call put_page, commit
* a file, or wait for autopilot?" with one command that just works.
*
* gbrain capture "thought to remember"
* gbrain capture --file ./notes/2026-05-20.md
* echo "from stdin" | gbrain capture --stdin
* gbrain capture "..." --slug inbox/specific
* gbrain capture "..." --quiet # slug-only output for pipelines
*
* Behavior:
* - Local install: writes to ~/.gbrain/inbox/<slug>.md OR routes through
* put_page (which now writes through to disk via the v0.38 plumbing).
* Synchronous result with the slug, status, content_hash, and queue
* job id (when applicable).
* - Thin-client install: routes through callRemoteTool('put_page', ...)
* so the server's daemon handles ingestion. Same UX, transparent to
* the caller.
*
* Default slug: `inbox/YYYY-MM-DD-<sha8-of-content>`. Stable for same
* content (the daemon's 24h content-hash dedup will catch duplicates if
* you re-capture the same thought twice).
*
* Output:
* - Default: 5-line receipt block (slug, ingested_at, source_kind,
* content_hash, queue job id where applicable).
* - --quiet: just the slug on stdout for shell pipelines like
* `JOB=$(gbrain capture "..." --quiet)`.
* - --json: structured response for agents.
*/
import { readFileSync, statSync } from 'node:fs';
import { readStdinPayload } from '../core/stdin-read.ts';
import { resolve } from 'node:path';
import type { BrainEngine } from '../core/engine.ts';
import { loadConfig, isThinClient } from '../core/config.ts';
import { callRemoteTool, unpackToolResult, RemoteMcpError } from '../core/mcp-client.ts';
import { computeContentHash } from '../core/ingestion/types.ts';
import { operations, opError } from '../core/operations.ts';
import type { OperationContext } from '../core/operations.ts';
import { resolveSourceWithTier } from '../core/source-resolver.ts';
// Pure content helpers moved to core (shared with the capture MCP op — the
// core module also breaks the capture.ts→operations.ts static import cycle).
// Re-exported below so existing importers/tests keep their entry point.
import {
defaultSlug,
detectBinaryNullByte,
detectBinarySignature,
normalizeForHash,
deriveTitle,
explicitCaptureType,
mergeCaptureFrontmatter,
} from '../core/capture-content.ts';
import { randomUUID } from 'node:crypto';
import { parseMutationPrecondition } from '../core/persistence/preconditions.ts';
import { isWriteReceipt, type WriteReceipt } from '../core/persistence/types.ts';
import { currentCliWriteWait } from '../core/persistence/write-wait.ts';
import { maybeDelegateLocalOperation } from '../core/persistence/local-client.ts';
import { getCliOptions } from '../core/cli-options.ts';
import { reportPersistenceCliError } from './persistence-delegate.ts';
import { PAGE_MAX_BYTES } from '../core/page-size-policy.ts';
export { detectBinaryNullByte, normalizeForHash, mergeCaptureFrontmatter } from '../core/capture-content.ts';
interface RunOpts {
content?: string;
filePath?: string;
stdin?: boolean;
slug?: string;
type?: string;
source?: string;
quiet?: boolean;
json?: boolean;
expected_revision?: string;
request_id?: string;
force?: boolean;
// v0.42.x — Life Chronicle (#2390): manual `--type event` frontmatter sugar.
who?: string; // comma-separated entity slugs
what?: string;
where?: string;
kind?: string;
depth?: string; // the depth page this event backlinks
}
function parseArgs(args: string[]): RunOpts | { help: true; positional: string | undefined } {
const opts: RunOpts = {};
const positional: string[] = [];
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--help' || a === '-h') return { help: true, positional: undefined };
if (a === '--quiet' || a === '-q') { opts.quiet = true; continue; }
if (a === '--json') { opts.json = true; continue; }
if (a === '--stdin') { opts.stdin = true; continue; }
if (a === '--force') { opts.force = true; continue; }
const mutationFlag = /^--(request-id|expected-revision)(?:=(.*))?$/.exec(a);
if (mutationFlag) {
const value = mutationFlag[2] ?? args[++i];
if (!value || value.startsWith('--')) throw opError('invalid_params', `${mutationFlag[1]} requires a UUID.`, mutationFlag[1] === 'request-id'
? 'Give --request-id the UUID an earlier attempt of this capture printed (it replays that request), or omit it and gbrain generates one.'
: 'Give --expected-revision the revision gbrain get --json returned for the page, or omit it to capture without a revision check.');
if (mutationFlag[1] === 'request-id') opts.request_id = value;
else opts.expected_revision = value;
continue;
}
if (a === '--file') {
const v = args[++i];
if (v) opts.filePath = v;
continue;
}
if (a === '--slug') {
const v = args[++i];
if (v) opts.slug = v;
continue;
}
if (a === '--type') {
const v = args[++i];
if (v) opts.type = v;
continue;
}
if (a === '--source') {
const v = args[++i];
if (v) opts.source = v;
continue;
}
// v0.42.x — Life Chronicle event sugar.
if (a === '--who') { const v = args[++i]; if (v) opts.who = v; continue; }
if (a === '--what') { const v = args[++i]; if (v) opts.what = v; continue; }
if (a === '--where') { const v = args[++i]; if (v) opts.where = v; continue; }
if (a === '--kind') { const v = args[++i]; if (v) opts.kind = v; continue; }
if (a === '--depth') { const v = args[++i]; if (v) opts.depth = v; continue; }
if (a.startsWith('--')) throw opError('invalid_params', `Unsupported capture option '${a.split('=')[0]}'.`,
`Remove ${a.split('=')[0]}; gbrain capture accepts --file, --stdin, --slug, --type, --source, --who, --what, --where, --kind, --depth, --request-id, --expected-revision, --force, --json and --quiet.`,
{ fix: { argv: ['gbrain', 'capture', '--help'], consent: [], actor: 'agent', why: 'Prints the capture forms and flags.', requires_exclusive: false } });
positional.push(a);
}
if (positional.length > 0) {
opts.content = positional.join(' ');
}
return opts;
}
const HELP = `Usage: gbrain capture [content] [options]
The single entrypoint for getting content into the brain. One command,
local OR thin-client, synchronous receipt with the resulting page slug.
Modes (mutually exclusive — first match wins):
gbrain capture "thought" inline content
gbrain capture --file PATH read content from a file
gbrain capture --stdin read content from stdin (piped)
Options:
--slug SLUG Override the default inbox/YYYY-MM-DD-<hash6> slug
--type TYPE Override the page type (default: note)
--source ID Multi-source brains: write under a non-default source.
Resolution: --source flag > GBRAIN_SOURCE env >
.gbrain-source dotfile (walk-up) > local_path >
brain_default > 'default'. NOT supported on
thin-client installs (server-side OAuth client
registration scopes the source).
--quiet, -q Print just the slug on stdout (for shell pipelines)
--json JSON output for agents
--request-id UUID Retry the same logical capture with its original UUID
--expected-revision UUID Replace only this version of an existing page
--force Explicitly replace an existing page without a revision
--help, -h Show this help
Notes:
- Binary files (image/audio/video/pdf, anything with NUL bytes in the
first 8KB) are rejected with a friendly error. Use a content-type
processor skillpack for those when available.
- Capturing identical text twice produces the same slug and the same
content_hash (whitespace + line endings + Unicode form are normalized
before hashing). The daemon's 24h LRU dedup uses this hash.
- source_kind in the DB is ALWAYS 'capture-cli' for invocations of this
command. --source maps to the source_id DB column, NOT to source_kind.
Replacing an existing slug requires --expected-revision or --force.
Keep --request-id unchanged when retrying the same capture.
Examples:
gbrain capture "remember to follow up on the X deal"
echo "from a pipe" | gbrain capture --stdin
gbrain capture --file ./notes/today.md --slug daily/2026-05-20
JOB=$(gbrain capture "..." --quiet)
`;
/**
* v0.39.3.0 A2 + CV6 — detect Postgres FK violation on the sources table
* in an error message and return a friendly hint. Returns null when the
* error doesn't match. Used by BOTH the local-engine catch block AND
* the thin-client (callRemoteTool) catch block per T1.
*
* Pattern coverage:
* - Postgres SQLSTATE 23503 message: 'insert or update on table "pages" violates
* foreign key constraint "pages_source_id_fk"'
* - postgres.js may wrap with extra context; substring match is enough
* - The MCP error envelope passes the message through unchanged (the
* server-side put_page op converts to OperationError but the underlying
* PG message is in the .cause chain)
*/
export function maybeRewriteSourceFkError(err: unknown, sourceId: string | undefined): string | null {
if (!sourceId) return null;
const msg = err instanceof Error ? err.message : String(err);
// Match both the raw Postgres wording and OperationError-wrapped variants.
const matchesFk = msg.includes('pages_source_id_fk')
|| (msg.includes('foreign key constraint') && msg.includes('source'));
if (!matchesFk) return null;
return `source '${sourceId}' is not registered. Register it first:\n gbrain sources add ${sourceId} --path <path>\n\nList registered sources:\n gbrain sources list`;
}
/**
* Build the put_page content (frontmatter + body). The user's --type and
* the auto-stamped capture provenance go in the frontmatter so future
* tools (e.g. the inbox triage UI) can find captures.
*
* v0.39.3.0: delegates to `mergeCaptureFrontmatter` so files with existing
* frontmatter merge instead of double-wrap (BUG-1).
*/
function buildContent(rawBody: string, opts: RunOpts): string {
return mergeCaptureFrontmatter(rawBody, opts);
}
interface CaptureResult {
slug: string;
status?: string;
chunks?: number;
content_hash: string;
written?: boolean;
path?: string;
source_kind: string;
captured_at: string;
revision?: string;
write_request?: WriteReceipt;
}
function printReceipt(result: CaptureResult, quiet: boolean, json: boolean): void {
if (json) {
console.log(JSON.stringify(result, null, 2));
return;
}
if (quiet) {
console.log(result.slug);
return;
}
console.log('captured:');
console.log(` slug: ${result.slug}`);
console.log(` status: ${result.status ?? 'unknown'}`);
console.log(` content_hash: ${result.content_hash.slice(0, 16)}…`);
if (result.path) {
console.log(` file: ${result.path}`);
}
console.log(` captured_at: ${result.captured_at}`);
if (result.revision) console.log(` revision: ${result.revision}`);
if (result.write_request) console.log(` request_id: ${result.write_request.request_id}`);
}
/**
* The `capture` operation parameters one CLI invocation submits, on every
* transport (direct handler, resident-owner IPC, thin-client HTTP). The
* provenance trio (`source_kind`, `source_uri`, `ingested_via`) is trusted
* local CLI provenance: the owner stores it for a local caller and replaces it
* with `mcp:capture` for a remote one (page-mutations.ts), so a thin client
* sends none of it. #6524: every key here is declared on the op, which the
* dispatch unknown-parameter check requires of a write
* (test/capture-cli-params-contract-6524.test.ts).
*/
function captureParams(parsed: RunOpts, content: string, precondition: Record<string, unknown>, thinClient: boolean): Record<string, unknown> {
return {
content,
...precondition,
...(parsed.slug ? { slug: parsed.slug } : {}),
...(parsed.type ? { type: parsed.type } : {}),
...(parsed.who ? { who: parsed.who } : {}),
...(parsed.what ? { what: parsed.what } : {}),
...(parsed.where ? { where: parsed.where } : {}),
...(parsed.kind ? { kind: parsed.kind } : {}),
...(parsed.depth ? { depth: parsed.depth } : {}),
...(thinClient ? {} : {
source_kind: 'capture-cli',
// #5622: the owner maps a local file to its source-relative origin (or 'cli-file'); no file URI or home path is stored.
...(parsed.filePath ? { local_file: resolve(parsed.filePath) } : { source_uri: parsed.stdin ? 'stdin' : 'cli-positional' }),
ingested_via: 'capture-cli',
}),
};
}
export async function runCapture(engine: BrainEngine | null, args: string[], options: { getEngine?: () => Promise<BrainEngine> } = {}): Promise<void> {
const parsed = parseArgs(args);
if ('help' in parsed) {
console.log(HELP);
return;
}
// v0.39.3.0 CV7: thin-client installs cannot scope --source via put_page
// params. The server's auth/transport layer (OAuth client registration's
// source_id / federated_read) determines source scope. Reject early with
// a clear error pointing at the right fix; matches CV6 trust posture
// (server owns the source scope, client cannot override per-call).
const cfg = loadConfig();
if (parsed.source && isThinClient(cfg)) {
console.error(`gbrain capture: --source is not supported on thin-client installs.`);
console.error(`Server-side OAuth client registration determines source scope.`);
console.error(`On the server, run:`);
console.error(` gbrain auth register-client <name> --source ${parsed.source} --scopes "read write"`);
process.exit(1);
}
// v0.39.3.0 CV10 — resolve content as a Buffer FIRST so the binary guard
// sees real bytes (not UTF-8-decoded mojibake). Stdin uses the same
// Buffer path so --stdin gets the same protection as --file.
let rawBuffer: Buffer | null = null;
let inputLabel = ''; // for error messages
if (parsed.stdin) {
// Bounded read (C5): an open-but-silent pipe times out instead of hanging,
// and partial input is never captured. Raw bytes reach the binary guards.
const read = await readStdinPayload('echo "a thought" | gbrain capture --stdin');
if (!read.ok) {
console.error(`gbrain capture: ${read.message}`);
process.exit(1);
}
rawBuffer = read.raw;
inputLabel = 'stdin';
} else if (parsed.filePath) {
inputLabel = parsed.filePath;
// Wave B: a trusted local file over the page ceiling streams (src/cli/commands/append.ts streamLocalCapture).
if (!isThinClient(cfg) && (statSync(parsed.filePath, { throwIfNoEntry: false })?.size ?? 0) > PAGE_MAX_BYTES) {
try {
const streamed = await (await import('../cli/commands/append.ts')).streamLocalCapture(parsed.filePath, parsed, async () => engine ??= await options.getEngine!());
if (streamed) {
const { captured_at, ...receipt } = streamed;
return printReceipt({ ...receipt, written: false, source_kind: 'capture-cli', captured_at }, parsed.quiet ?? false, parsed.json ?? false);
}
} catch (error) {
if (await reportPersistenceCliError(error, parsed.json ?? false)) return;
console.error(`gbrain capture: ${error instanceof Error ? error.message : String(error)}`);
const { setCliExitVerdict } = await import('../core/cli-force-exit.ts');
return setCliExitVerdict(1);
}
}
try {
// No encoding => returns Buffer; binary guard sees raw bytes.
rawBuffer = readFileSync(parsed.filePath);
} catch (e) {
console.error(
`gbrain capture: failed to read ${parsed.filePath}: ${e instanceof Error ? e.message : String(e)}`,
);
process.exit(1);
}
} else if (parsed.content) {
// Positional content: already a JS string, but route through a Buffer
// for guard parity (a positional string with a literal `\x00` would
// also be rejected). Inline thoughts almost never trigger this; it's
// pure defense-in-depth.
rawBuffer = Buffer.from(parsed.content, 'utf8');
inputLabel = 'positional content';
} else {
console.error('gbrain capture: provide content positionally, --file PATH, or --stdin');
console.error('Run `gbrain capture --help` for examples.');
process.exit(1);
}
// #4022 magic-byte guard runs FIRST: it names the actual format, and it
// catches the containers the NUL scan structurally cannot (an ASCII-armored
// PDF has no NUL in its head, so pre-fix it was decoded to mojibake and
// stored as a page body with its real text silently dropped).
const binaryFormat = detectBinarySignature(rawBuffer!);
if (binaryFormat !== null) {
console.error(
`gbrain capture: refusing to capture ${binaryFormat} content from ${inputLabel}\n` +
` Detected by magic bytes. Storing it would write UTF-8 replacement characters as the\n` +
` page body — for container formats the real text is compressed, so it would be lost\n` +
` entirely while the command reported success.\n` +
` Extract the text first, then capture that. For a PDF:\n` +
` pdftotext ${inputLabel === 'stdin' ? 'input.pdf' : inputLabel} - | gbrain capture --stdin --slug <slug>`,
);
process.exit(1);
}
// CV10 binary guard. Scans the first 8KB for NUL bytes; rejects with a
// friendly message before UTF-8 decode mangles arbitrary bytes.
const nullByteOffset = detectBinaryNullByte(rawBuffer!);
if (nullByteOffset !== -1) {
console.error(
`gbrain capture: refusing to capture binary content from ${inputLabel}\n` +
` Found null byte at offset ${nullByteOffset} (first 8KB scan); ` +
`text files (including UTF-8 CJK/emoji/BOM) never contain NUL bytes.\n` +
` Binary content (image/audio/video/pdf) is not yet supported via capture — ` +
`install a content-type processor skillpack when available.`,
);
process.exit(1);
}
// Decode to UTF-8 string AFTER the binary guard.
const rawBody = rawBuffer!.toString('utf8');
// CV9: refuse empty content based on the normalized form (whitespace-only
// input is still empty), but preserve original bytes in storedBody for
// the put_page write so CRLF / BOM / trailing-newline tests pass.
const normalizedBody = normalizeForHash(rawBody);
if (normalizedBody.length === 0) {
console.error('gbrain capture: refusing to capture empty content');
process.exit(1);
}
// Raw input and explicit options are the idempotency intent. The owner
// materializes its default slug and capture timestamp once after admission;
// retrying a CLI invocation must not produce a different digest.
const contentHash = computeContentHash(normalizedBody);
const capturedAt = new Date().toISOString();
let resolvedSourceId = 'default';
let requestId: string | undefined;
try {
const precondition = parseMutationPrecondition(parsed as unknown as Record<string, unknown>);
requestId = precondition.request_id ?? randomUUID();
const params = captureParams(parsed, rawBody, { ...precondition, request_id: requestId }, isThinClient(cfg));
let result: Record<string, unknown>;
// Wave B: a file larger than one request goes through an upload session (src/cli/commands/append.ts).
const upload = parsed.filePath ? await import('../cli/commands/append.ts') : null;
if (upload?.captureNeedsUpload(params, isThinClient(cfg))) {
result = await upload.uploadCapture(rawBody, parsed, requestId, async () => engine ??= await options.getEngine!());
} else if (isThinClient(cfg)) {
const raw = await callRemoteTool(cfg!, 'capture', params, { timeoutMs: getCliOptions().timeoutMs ?? 30_000, writeWaitMs: currentCliWriteWait().waitMs });
result = unpackToolResult<Record<string, unknown>>(raw);
} else {
const cli = getCliOptions();
const delegated = await maybeDelegateLocalOperation('capture', params, cfg, {
brain: cli.brain, source: parsed.source ?? null, timeoutMs: cli.timeoutMs ?? undefined,
});
if (delegated.handled) result = delegated.result as Record<string, unknown>;
else {
if (!engine && options.getEngine) engine = await options.getEngine();
if (!engine) throw opError('owner_unavailable', 'Capture requires a connected engine or a local persistence owner.',
'Run gbrain capture from the CLI on the brain host, where it opens the brain itself or hands the capture to a running gbrain serve.',
{ fix: { argv: ['gbrain', 'doctor', '--json'], consent: [], actor: 'agent', why: 'Shows whether this machine resolves a brain and whether a serve owns it, read-only.', requires_exclusive: false } });
const resolved = await resolveSourceWithTier(engine, parsed.source ?? null);
resolvedSourceId = resolved.source_id;
const captureOp = operations.find(operation => operation.name === 'capture');
if (!captureOp) throw opError('unavailable', 'The capture operation is missing; upgrade this installation.',
'This gbrain build has no capture operation. Check for an update and, with the user\'s go-ahead, run gbrain upgrade, then capture again.',
{ fix: { argv: ['gbrain', 'check-update', '--json'], consent: [], actor: 'agent', why: 'Reports whether a newer gbrain is available, read-only.', requires_exclusive: false } });
const ctx: OperationContext = {
engine, config: cfg ?? { engine: 'pglite' }, sourceId: resolvedSourceId,
remote: false, dryRun: false, writeWaitMs: currentCliWriteWait().waitMs,
logger: {
info: (message: string) => process.stderr.write(`[capture] ${message}\n`),
warn: (message: string) => process.stderr.write(`[capture] WARN: ${message}\n`),
error: (message: string) => process.stderr.write(`[capture] ERROR: ${message}\n`),
},
};
result = await captureOp.handler(ctx, params) as Record<string, unknown>;
}
}
const receipt = isWriteReceipt(result.write_request) ? result.write_request : undefined;
if (receipt && receipt.state !== 'committed') {
// Accepted is a real receipt, but never a false claim that capture
// finished. Quiet pipelines must not receive a made-up page slug.
if (parsed.json) console.log(JSON.stringify(result, null, 2));
else console.error(`Capture ${receipt.state}; request_id ${receipt.request_id}. Retry the same request ID for its result.`);
return;
}
const persistence = result.persistence as { file_written?: boolean } | undefined;
const writeThrough = result.write_through as { written?: boolean; path?: string } | undefined;
printReceipt({
slug: result.slug as string,
status: result.status as string | undefined,
chunks: result.chunks as number | undefined,
content_hash: contentHash,
written: persistence?.file_written ?? writeThrough?.written ?? false,
path: writeThrough?.path,
source_kind: 'capture-cli',
captured_at: receipt?.created_at ?? capturedAt,
...(receipt ? { write_request: receipt } : {}),
...(typeof result.revision === 'string' ? { revision: result.revision } : {}),
}, parsed.quiet ?? false, parsed.json ?? false);
} catch (error) {
if (await reportPersistenceCliError(error, parsed.json ?? false)) return;
const hint = maybeRewriteSourceFkError(error, parsed.source ?? resolvedSourceId);
console.error(`gbrain capture: ${hint ?? (error instanceof Error ? error.message : String(error))}`);
if (requestId) console.error(`Retry the same capture with --request-id ${requestId}.`);
if (parsed.json && error instanceof RemoteMcpError && error.detail?.write_request) {
console.log(JSON.stringify({ ...error.detail, request_id: requestId }, null, 2));
}
const { setCliExitVerdict } = await import('../core/cli-force-exit.ts');
setCliExitVerdict(1);
}
}
/** Test seam. */
export const __testing = {
defaultSlug,
buildContent,
mergeCaptureFrontmatter,
deriveTitle,
explicitCaptureType,
parseArgs,
captureParams,
detectBinaryNullByte,
detectBinarySignature,
normalizeForHash,
maybeRewriteSourceFkError,
};