Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The content-repair lane (#6377): the repair kinds that clear managed-sync
* content holds, run as one bounded pass under one paid-model allowance.
*
* `CONTENT_REPAIR_KINDS` is the lane in dependency order; `gbrain repair
* content`, the `content_repair` maintenance phase (src/core/cycle/
* content-repair.ts) and `gbrain sync unblock --apply` all read it, so a new
* kind plugs in with one entry here. Today it holds `fences`; the GBRA-72
* integration appends `slug-conflicts` (Lane B, src/core/repair/
* slug-conflicts.ts). `CONTENT_REPAIR_HOLD_KINDS` maps a hold code to the kind
* that clears it (`null`: no kind yet, the surfaces keep today's refusal text).
*
* `runContentLane` has no rule logic of its own: it runs each kind through
* the shared trusted `repairRunner`, so every kind keeps its own census, owner
* checks, caps, ledger, memo and gates. What the lane adds is the contract
* between kinds: the run's paid allowance (`maxLlmUsd`) flows from one kind to
* the next minus what the earlier kinds spent (read from each result's
* `cost.llm_usd`; the daily ledger is shared by every kind, `FENCE_REPAIR_LEDGER`),
* and one absolute deadline bounds the whole pass. A preview builds every
* component plan before any mutation and returns each kind's own preview
* hash; `--apply --expect <h1>[,<h2>]` applies exactly those sets, one hash
* per kind in lane order, so the operator's approval binds both concrete plans
* (Codex #10). There is no combined hash. A bare apply (the cycle, `sync
* unblock`, `--apply` alone) applies each kind's current plan the way
* `gbrain repair <kind> --apply` does: the kind plans and applies in one run,
* each item bound to the bytes its plan read (`changed_since_read`), and
* records on every hold it leaves why (a preview records nothing).
*
* `contentHoldDisposition` is the one place that reads a hold's stored repair
* state (a fence hold's `fenceHoldStatus`, a slug-conflict hold's
* `meta.content_repair.action`) to say whether unattended surfaces may run the
* kind on it or must list it for a person. Output is counts, codes, hashes
* and paths only: never a claim, a cell or a frontmatter value.
*/
import type { BrainEngine } from '../engine.ts';
import type { OperationContext } from '../ops/contract.ts';
import { opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { shellQuote } from '../agent-output.ts';
import { fenceHoldStatus, type FenceAutoRepair } from '../fence-repair/hold-fix.ts';
import type { GitHoldRecord } from '../persistence/sync-holds.ts';
import { contentRepairLaneCurrent } from '../persistence/sync-fault-class.ts';
import type { RepairFailedItem, RepairKind, RepairResult, RepairScope } from './core.ts';
import { repairRunner, type RepairKindSpec } from './registry.ts';
import { kindErrorResult } from '../remediation/repairs.ts';
import { ItemRun } from '../item-failure.ts';
/** The lane, in run order: fences first (a merged or closed fence can change what a slug conflict's page looks like), then slug conflicts. */
export const CONTENT_REPAIR_KINDS: readonly RepairKind[] = ['fences', 'slug-conflicts'];
/** Which lane kind clears a hold code; a code with `null` is refused by `sync unblock` with the fix it names. */
export const CONTENT_REPAIR_HOLD_KINDS: Readonly<Partial<Record<GitHoldRecord['code'], RepairKind | null>>> = {
invalid_fence: 'fences',
frontmatter_slug_conflict: 'slug-conflicts',
};
/** A hold's stored repair decision, when the lane recorded one (Lane B writes it; read loosely so either lane lands first). */
function storedContentAction(meta: GitHoldRecord['meta']): string | undefined {
const action = (meta as { content_repair?: { action?: unknown } }).content_repair?.action;
return typeof action === 'string' ? action : undefined;
}
export type ContentHoldDisposition =
/** An unattended run may run `kind` on this hold now. */
| { action: 'repair'; kind: RepairKind }
/** The hold waits on a person (`needs_human`), the user's spend decision (`paid`) or the owner host (`owner`); list it, never retry it. */
| { action: 'listed'; kind: RepairKind; state: 'needs_human' | 'paid' | 'owner'; reason: string }
/** No lane kind clears this code yet. */
| { action: 'unsupported' };
/**
* What an unattended surface (`sync unblock --apply`, the cycle) may do with
* one hold. `auto` is what the caller read about the maintenance run
* (`fenceAutoRepairFor`); it decides a fence hold's state exactly as the
* hold's own fix does.
*/
export function contentHoldDisposition(record: Pick<GitHoldRecord, 'code' | 'meta'>, auto?: FenceAutoRepair): ContentHoldDisposition {
const kind = CONTENT_REPAIR_HOLD_KINDS[record.code];
if (!kind) return { action: 'unsupported' };
if (record.code === 'invalid_fence') {
const status = fenceHoldStatus(record.meta, auto);
if (status.state === 'manual' || status.state === 'approval') return { action: 'listed', kind, state: 'needs_human', reason: status.reason };
if (status.state === 'paid' || status.state === 'owner') return { action: 'listed', kind, state: status.state, reason: status.reason };
return { action: 'repair', kind };
}
const stored = storedContentAction(record.meta);
// #6865: a verdict an older lane recorded is rechecked once; the recheck records this lane's version, so it is listed again after that.
if (!contentRepairLaneCurrent(record.meta.content_repair)) return { action: 'repair', kind };
if (stored === 'merge_into') return { action: 'listed', kind, state: 'needs_human', reason: 'merge_recommended' };
if (stored === 'needs_human') return { action: 'listed', kind, state: 'needs_human', reason: 'content_repair_needs_human' };
return { action: 'repair', kind };
}
export interface ContentLaneOptions {
apply: boolean;
/** The kinds to run, in order (default: the whole lane). */
kinds?: readonly RepairKind[];
/** Source-relative file selection, handed to every kind (its hash covers it). */
only?: string[];
skip?: string[];
/** One preview hash per kind in `kinds` order; the apply binds each kind to exactly that set. */
expect?: readonly string[];
/** Free tiers only, for every kind. */
noLlm?: boolean;
/** The run's paid-model allowance in USD for the whole lane; what one kind spends is gone for the next. */
maxLlmUsd?: number;
/** Absolute deadline (epoch ms) for the whole lane; a kind stopped `time_budget` ends the pass. */
deadline?: number;
limit?: number;
noEmbed?: boolean;
/** `--source <id>` as the operator wrote it, for the printed commands. */
sourceFlag?: string;
/** Replaces the registered kinds (tests pass stub specs). */
registry?: readonly RepairKindSpec[];
/** The caller's cancellation: a kind that throws after it fired is rethrown, never recorded as that kind's error.
* A kind bound to its `--expect` hash is rethrown too: the operator approved that set, so a refusal answers the command. */
signal?: AbortSignal;
logger?: OperationContext['logger'];
}
export interface ContentLaneResult {
mode: 'dry_run' | 'apply';
scope: RepairScope;
/** The kinds the lane ran, in order; one `results` entry each. */
kinds: RepairKind[];
results: RepairResult[];
/** Each kind's own preview hash on a dry run, the hash each apply was bound to with `expect` (null: the kind printed none, or a bare apply). */
preview_hashes: Partial<Record<RepairKind, string | null>>;
/** Paid-model spend across the lane: the estimate on a dry run, the actual spend on an apply; the allowance left under `maxLlmUsd` (null: no run cap). */
cost: { llm_usd: number; llm_allowance_remaining_usd: number | null };
/** Every kind that stopped, with its reason (`time_budget` ends the lane; the rest let the next kind run). A kind whose plan or apply threw item-scoped stops with reason `error` and its preview as the fix (GBRA-130); a run-scoped error is thrown. */
stopped: Array<{ kind: RepairKind } & NonNullable<RepairResult['stopped']>>;
/** Every item a kind refused per item and left unchanged (the kinds' `failed[]`, with the kind); the next full scan retries them. */
failed: Array<{ kind: RepairKind } & RepairFailedItem>;
/** The command that applies exactly these plans (dry run), or reruns the lane (apply). */
apply_command: string;
}
/** `gbrain repair content [--source <id>] [--only <p>]... [--skip <p>]... [--no-llm] [--max-usd <n>] [--apply [--expect <h1>,<h2>]]`. */
export function contentLaneArgv(opts: { source?: string; only?: readonly string[]; skip?: readonly string[]; noLlm?: boolean; maxLlmUsd?: number; apply?: boolean; expect?: readonly string[] }): string[] {
return ['gbrain', 'repair', 'content', ...(opts.source ? ['--source', opts.source] : []), ...(opts.only ?? []).flatMap(path => ['--only', path]),
...(opts.skip ?? []).flatMap(path => ['--skip', path]), ...(opts.noLlm ? ['--no-llm'] : []), ...(opts.maxLlmUsd !== undefined ? ['--max-usd', String(opts.maxLlmUsd)] : []),
...(opts.apply ? ['--apply'] : []), ...(opts.expect?.length ? ['--expect', opts.expect.join(',')] : [])];
}
/**
* `--expect <h1>[,<h2>]` → one hash per kind, in order. Refuses a count that
* does not match the kinds the lane runs: the operator previewed a different
* lane, so no hash can be matched to a kind.
*/
export function parseContentLaneExpect(text: string, kinds: readonly RepairKind[], previewArgv: string[]): string[] {
const hashes = text.split(',').map(hash => hash.trim()).filter(Boolean);
if (hashes.length === kinds.length) return hashes;
throw opError('invalid_params', `--expect takes one preview hash per kind of the content lane, comma-separated in lane order (${kinds.join(', ')}); got ${hashes.length} hash(es) for ${kinds.length} kind(s), so nothing ran.`,
`Preview the lane again and pass the hashes it prints: ${shellQuote(previewArgv)} prints each kind's own hash and the exact apply command.`,
{ fix: readFix('Previews every lane kind; it writes nothing and calls no model.', { argv: previewArgv }) });
}
export async function runContentLane(engine: BrainEngine, scope: RepairScope, opts: ContentLaneOptions): Promise<ContentLaneResult> {
const kinds = [...(opts.kinds ?? CONTENT_REPAIR_KINDS)];
const previewArgv = contentLaneArgv({ source: opts.sourceFlag, only: opts.only, skip: opts.skip, noLlm: opts.noLlm, maxLlmUsd: opts.maxLlmUsd });
if (opts.expect && opts.expect.length !== kinds.length) parseContentLaneExpect(opts.expect.join(','), kinds, previewArgv);
const runner = await repairRunner(engine, { apply: opts.apply, noEmbed: opts.noEmbed, ...(opts.logger ? { logger: opts.logger } : {}), ...(opts.registry ? { registry: opts.registry } : {}) });
const hashes: ContentLaneResult['preview_hashes'] = {};
const stopped: ContentLaneResult['stopped'] = [];
const failed: ContentLaneResult['failed'] = [];
const results: RepairResult[] = [];
let spent = 0;
const allowance = () => opts.maxLlmUsd === undefined ? undefined : Math.max(0, opts.maxLlmUsd - spent);
const kindRun = new ItemRun('repair.content_lane_kinds');
for (const [index, kind] of kinds.entries()) {
const expect = opts.expect?.[index];
let result: RepairResult;
try {
result = await runner.run(kind, scope, { explicit: true, limit: opts.limit, sourceFlag: opts.sourceFlag, only: opts.only, skip: opts.skip, noLlm: opts.noLlm,
maxLlmUsd: allowance(), deadline: opts.deadline, ...(expect ? { expect } : {}) });
kindRun.succeed();
} catch (error) {
if (opts.signal?.aborted || expect) throw error;
kindRun.fail(kind, error);
result = kindErrorResult(kind, scope, { apply: opts.apply, error, source: opts.sourceFlag });
}
hashes[kind] = expect ?? result.preview_hash ?? null;
spent += result.cost.llm_usd ?? 0;
results.push(result);
if (result.stopped) stopped.push({ kind, ...result.stopped });
for (const item of result.failed) failed.push({ kind, ...item });
if (result.stopped?.reason === 'time_budget') break;
}
const expect = kinds.map(kind => hashes[kind] ?? null);
return { mode: opts.apply ? 'apply' : 'dry_run', scope, kinds, results, preview_hashes: hashes, cost: { llm_usd: spent, llm_allowance_remaining_usd: allowance() ?? null }, stopped, failed,
apply_command: shellQuote(contentLaneArgv({ source: opts.sourceFlag, only: opts.only, skip: opts.skip, noLlm: opts.noLlm, maxLlmUsd: opts.maxLlmUsd, apply: true,
expect: expect.every((hash): hash is string => hash !== null) ? expect : undefined })) };
}