Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
#!/usr/bin/env bun
/**
* Agent operator contract scanner (docs/designs/AGENT_OPERATOR_WAVE.md, B9).
*
* Syntax-only TypeScript AST walk over src/**\/*.ts. Every rule counts hits
* per file; per-rule baselines under scripts/agent-contract-baselines/<rule>.tsv
* (`path<TAB>count`, sorted) are SHRINK-ONLY: a file over its baseline fails
* (new violation), a file under it fails until the baseline is lowered
* (`--update` rewrites baselines and refuses any increase). Rules with no
* baseline file must have zero hits.
*
* Rules:
* suggestionless-operation-error new OperationError(code, msg) without a suggestion (use opError)
* throw-new-error-in-ops `throw new Error` in src/core/ops/**, src/mcp/** or an op `handler:` body
* hand-built-command a `fix` / `next_action` value written as a 'gbrain …' string (build argv; shellQuote renders)
* legacy-advice-key a legacy advice key (next_action, fix_argv, hint, docs_url, …) outside the alias allowlist
* interactive-io raw stdin/readline/raw-mode reads outside interaction.ts / consent.ts and INTERACTIVE_IO_ALLOW (streams/TUI, with a reason)
* yes-rerun-string a raw "re-run with --yes" string outside consent.ts
* stdio-inherit `stdio: 'inherit'` outside spawnCliChild (cli-force-exit.ts)
* marker-literal [AGENT] / [SHOW USER] / "ACTION FOR THE AGENT:" outside agent-output.ts / agent-markers.ts
* verify-not-read-only a fix `verify.argv` naming a command not declared read_only
* flag-in-mcp-text a bare `--flag` in MCP-visible error text or an op description (src/core/ops, src/mcp)
* outside a full `gbrain …` command; render per surface with paramUse()/invalidParam()
* in-scope-placeholder a `<placeholder>` in a fix argv without declared `inputs`, or in an error suggestion
* (fill the value from scope; only genuinely unknown values are `inputs`;
* an op's `cliOnly.argv` template is exempt: cliOnlyRefusal declares its inputs)
* retry-on-mutating "retry" advice in an error raised by a mutating, non-idempotent op handler
* (say "inspect state before resubmitting"; retry only with the same request identity)
* defaulted-suggestion a function that builds an error (opError, new OperationError, usageError, invalidParam,
* hostOnlyError) from a suggestion/hint parameter that has a default, is optional or is
* `??`-defaulted: each call site names its own next step (never baselined)
* generic-suggestion a suggestion whose whole text is boilerplate ("see --help", "try again", "check your
* input"), at an error constructor or a funnel call site; name the exact usage (never baselined)
* unregistered-code a literal error code thrown in src/ missing from src/core/error-registry.ts (never baselined)
* code-naming a registry code that is not snake_case or carries a transport prefix (never baselined)
*
* Seam: GBRAIN_GUARD_ROOT (fixture tree; baselines read from <root>/baselines/).
*/
import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
import { join, relative, sep } from 'node:path';
import ts from 'typescript';
const FIXTURE_ROOT = process.env.GBRAIN_GUARD_ROOT;
const ROOT = FIXTURE_ROOT ?? join(import.meta.dir, '..');
const BASELINE_DIR = FIXTURE_ROOT ? join(FIXTURE_ROOT, 'baselines') : join(ROOT, 'scripts', 'agent-contract-baselines');
const DOCS = 'docs/designs/AGENT_OPERATOR_WAVE.md (B9)';
export type Rule =
| 'suggestionless-operation-error' | 'throw-new-error-in-ops' | 'hand-built-command' | 'legacy-advice-key'
| 'interactive-io' | 'yes-rerun-string' | 'stdio-inherit' | 'marker-literal' | 'verify-not-read-only'
| 'flag-in-mcp-text' | 'in-scope-placeholder' | 'retry-on-mutating'
| 'defaulted-suggestion' | 'generic-suggestion' | 'unregistered-code' | 'code-naming';
export const BASELINED_RULES: readonly Rule[] = [
'suggestionless-operation-error', 'throw-new-error-in-ops', 'hand-built-command', 'legacy-advice-key',
'interactive-io', 'yes-rerun-string', 'stdio-inherit', 'marker-literal', 'verify-not-read-only',
'flag-in-mcp-text', 'in-scope-placeholder', 'retry-on-mutating',
];
export interface Hit { rule: Rule; file: string; line: number; text: string }
/**
* interactive-io reads that are data streams or terminal UI, not prompts:
* path → call → one-line reason. A prompt (a question the user answers) never
* belongs here; it goes through interaction.ts (readLine / promptYesNo).
*/
export const INTERACTIVE_IO_ALLOW: Readonly<Record<string, Readonly<Record<string, string>>>> = {
'src/commands/hook.ts': {
'process.stdin.on': 'harness hook payload: bounded, fail-open stream read with its own hard timeout (a hook never blocks the agent)',
},
'src/commands/watch.ts': {
createInterface: 'stdin IS the data: transcript turns streamed line by line until EOF or SIGINT',
},
'src/commands/jobs-watch.ts': {
'process.stdin.setRawMode': "TTY-only dashboard: raw mode so a single 'q' keypress quits",
'process.stdin.on': "TTY-only dashboard: the 'q' / Ctrl-C keypress listener",
},
'src/mcp/server.ts': {
'process.stdin.on': 'stdio MCP transport lifecycle: shut down when the client closes stdin',
},
};
const LEGACY_ADVICE_KEYS = new Set(['next_action', 'fix_argv', 'agent_action', 'recovery_action', 'docs_url', 'hint', 'remediation', 'next_step']);
const MARKER_RE = /\[\/?AGENT\]|\[\/?SHOW USER\]|ACTION FOR THE AGENT:/;
const YES_RERUN_RE = /re-?run\b[^.\n]{0,40}--yes/i;
const TRANSPORT_PREFIX = /^(mcp|http|cli|stdio)_/;
const ERROR_CALLEE = /^(OperationError|verbError|opError|OperationError\.bare|hostOnlyError)$/;
const FLAG_RE = /(?:^|[\s(`'"])--[a-z][a-z0-9-]*/;
const PLACEHOLDER_RE = /<(?:source|source[-_]id|slug|id|request[-_]id|client[-_]id|page|uuid|brain|name)>/;
const RETRY_RE = /\bretry\b/i;
const SAFE_RETRY_RE = /(?:do not|don't|never) retry|same request_id|same request identity/i;
const SUGGESTION_PARAM = /(?:suggestion|hint)$/i;
const SUGGESTION_SINK = /^(opError|OperationError|usageError|invalidParam|hostOnlyError)$/;
const SUGGESTION_ARG: Readonly<Record<string, number>> = { opError: 2, OperationError: 2, verbError: 2, usageError: 1 };
const GENERIC_SUGGESTION: readonly RegExp[] = [
/^(?:please )?(?:see|check|read|consult|run|use)(?: with)?(?: the)? (?:gbrain(?: [a-z][a-z0-9-]*)* )?--help(?: (?:output|for usage|for details|for options))?$/,
/^(?:please )?(?:check|verify|fix|correct|review) (?:your|the) (?:input|arguments|parameters|params|request|options)$/,
/^(?:please )?(?:try again|retry)(?: later)?$/,
/^(?:please )?(?:see|check|read) (?:the )?(?:docs|documentation)$/,
];
/** True when a suggestion names no next step: empty, or only a generic denylist phrase. */
export function isGenericSuggestion(text: string): boolean {
const t = text.replace(/[`'"]/g, '').replace(/\s+/g, ' ').trim().toLowerCase().replace(/[.!]+$/, '');
return t === '' || GENERIC_SUGGESTION.some(re => re.test(t));
}
type FnLike = ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction;
const isFnLike = (n: ts.Node): n is FnLike => ts.isFunctionDeclaration(n) || ts.isFunctionExpression(n) || ts.isArrowFunction(n);
function fnName(fn: FnLike): string | undefined {
if (ts.isFunctionDeclaration(fn)) return fn.name?.text;
return ts.isVariableDeclaration(fn.parent) && ts.isIdentifier(fn.parent.name) ? fn.parent.name.text : undefined;
}
/** Error-constructor calls in a function body (the `defaulted-suggestion` sinks). */
function sinkCalls(fn: FnLike, sf: ts.SourceFile): Array<ts.CallExpression | ts.NewExpression> {
const out: Array<ts.CallExpression | ts.NewExpression> = [];
const visit = (n: ts.Node) => {
if ((ts.isCallExpression(n) || ts.isNewExpression(n)) && SUGGESTION_SINK.test(n.expression.getText(sf))) out.push(n);
ts.forEachChild(n, visit);
};
if (fn.body) visit(fn.body);
return out;
}
function nullishDefaulted(fn: FnLike, name: string): boolean {
let found = false;
const visit = (n: ts.Node) => {
if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken
&& ts.isIdentifier(n.left) && n.left.text === name) found = true;
if (!found) ts.forEachChild(n, visit);
};
if (fn.body) visit(fn.body);
return found;
}
/** A file-local function that forwards one of its parameters as an error's suggestion. */
interface Funnel { name: string; index: number }
export interface FunnelSite { file: string; line: number; funnel: string; texts: string[] | undefined; expr: string }
/** File-level `const NAME = <string literal>` bindings, so a shared suggestion constant counts as literal text. */
function literalConsts(sf: ts.SourceFile): Map<string, string> {
const out = new Map<string, string>();
for (const statement of sf.statements) {
if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const)) continue;
for (const d of statement.declarationList.declarations) {
const t = ts.isIdentifier(d.name) && d.initializer ? flatText(d.initializer, sf) : undefined;
if (t !== undefined) out.set((d.name as ts.Identifier).text, t);
}
}
return out;
}
/** Literal texts of a suggestion expression (each branch of a conditional); undefined when any branch is not literal. */
function suggestionTexts(n: ts.Expression, sf: ts.SourceFile, consts: Map<string, string>): string[] | undefined {
if (ts.isParenthesizedExpression(n)) return suggestionTexts(n.expression, sf, consts);
if (ts.isConditionalExpression(n)) {
const a = suggestionTexts(n.whenTrue, sf, consts); const b = suggestionTexts(n.whenFalse, sf, consts);
return a && b ? [...a, ...b] : undefined;
}
const t = ts.isIdentifier(n) ? consts.get(n.text) : flatText(n, sf);
return t === undefined ? undefined : [t];
}
function fileFunnels(sf: ts.SourceFile): Funnel[] {
const fns: FnLike[] = [];
const collect = (n: ts.Node) => { if (isFnLike(n)) fns.push(n); ts.forEachChild(n, collect); };
collect(sf);
const out: Funnel[] = [];
const forwards = (fn: FnLike, param: string): boolean => {
let found = false;
const visit = (n: ts.Node) => {
if (found) return;
if (ts.isCallExpression(n) || ts.isNewExpression(n)) {
const callee = n.expression.getText(sf);
const args = n.arguments ?? [];
if (SUGGESTION_SINK.test(callee) && args.some(a => ts.isIdentifier(a) && a.text === param)) found = true;
for (const f of out) if (f.name === callee && ts.isIdentifier(args[f.index] ?? n) && (args[f.index] as ts.Identifier).text === param) found = true;
}
ts.forEachChild(n, visit);
};
if (fn.body) visit(fn.body);
return found;
};
for (let grew = true; grew;) {
grew = false;
for (const fn of fns) {
const name = fnName(fn);
if (!name) continue;
fn.parameters.forEach((p, index) => {
if (!ts.isIdentifier(p.name) || !SUGGESTION_PARAM.test(p.name.text) || out.some(f => f.name === name && f.index === index)) return;
if (forwards(fn, p.name.text)) { out.push({ name, index }); grew = true; }
});
}
}
return out;
}
/** The suggestion parameter names of the function enclosing `n` (a forwarding call is not a call site). */
function enclosingSuggestionParams(n: ts.Node): Set<string> {
for (let p = n.parent; p; p = p.parent) {
if (isFnLike(p)) return new Set(p.parameters.flatMap(q => ts.isIdentifier(q.name) && SUGGESTION_PARAM.test(q.name.text) ? [q.name.text] : []));
}
return new Set();
}
function funnelCallSites(sf: ts.SourceFile, path: string): FunnelSite[] {
const funnels = fileFunnels(sf);
if (!funnels.length) return [];
const out: FunnelSite[] = [];
const consts = literalConsts(sf);
const visit = (n: ts.Node) => {
if (ts.isCallExpression(n) && ts.isIdentifier(n.expression)) {
for (const f of funnels) {
if (f.name !== n.expression.text) continue;
const arg = n.arguments[f.index];
if (arg && ts.isIdentifier(arg) && enclosingSuggestionParams(n).has(arg.text)) continue;
out.push({
file: path, line: sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1, funnel: f.name,
texts: arg ? suggestionTexts(arg, sf, consts) : undefined, expr: arg ? arg.getText(sf) : '',
});
}
}
ts.forEachChild(n, visit);
};
visit(sf);
return out;
}
/** Every call site of a suggestion-forwarding funnel (`invalid`, `fail`, `usage`, …) under src/, or in the named files. */
export function funnelSites(files?: readonly string[], root: string = ROOT): FunnelSite[] {
const paths = files ? files.map(f => join(root, f)) : tsFiles(join(root, 'src'));
return paths.flatMap(file => funnelCallSites(ts.createSourceFile(file, readFileSync(file, 'utf8'), ts.ScriptTarget.Latest, true), rel(file)));
}
/** Text args of an error constructor call: message (1) and suggestion (2); hostOnlyError's message is arg 2. */
function errorTextArgs(n: ts.CallExpression | ts.NewExpression, sf: ts.SourceFile): ts.Expression[] {
const callee = n.expression.getText(sf);
const args = n.arguments ?? [];
return callee === 'hostOnlyError' ? args.slice(2, 3) : args.slice(1, 3);
}
/** The op object literal (has `mutating:` and `handler:`) whose handler encloses `n`, if any. */
function enclosingOp(n: ts.Node): ts.ObjectLiteralExpression | undefined {
for (let p = n.parent; p; p = p.parent) {
if (ts.isPropertyAssignment(p) && propName(p) === 'handler' && ts.isObjectLiteralExpression(p.parent)) return p.parent;
}
return undefined;
}
function literalProp(obj: ts.ObjectLiteralExpression, name: string): string | undefined {
for (const p of obj.properties) {
if (ts.isPropertyAssignment(p) && propName(p) === name) return p.initializer.getText();
}
return undefined;
}
/** Read-only invocations a verify step may always name (doctor --only is the canonical one). */
const STATIC_READ_ONLY = new Set(['doctor', 'errors', 'status', 'get', 'search', 'query', 'list', 'write-request', 'write-requests', 'whoami', 'stats']);
/** Read-only subcommands of otherwise-mutating commands. */
const READ_ONLY_SUBCOMMANDS = new Set(['config get', 'sources list', 'sources status', 'files list', 'jobs get', 'jobs stats', 'jobs list', 'auth list', 'auth clients', 'backup status', 'engine status',
// Engine graduation: --status and --plan are zero-mutation (pre-connect; no schema migration, no target DDL).
'migrate --status', 'migrate --plan',
// Reads the pack resolution only; never connects without a configured brain (#6090).
'schema active',
// #6317: trusted-local writer administration reads (owners, running claims, consumers, movement); `sources writer claim|transfer|deactivate` stay mutating.
'sources writer status', 'sources writer movement',
// #8662: the commit-push dry run resolves the checkout, branch and lock and prints them; it stages and commits nothing.
'git commit-push --dry-run',
// #6650: the terminal-failure drill-down and the sync operator status only read receipts and cursors.
'sources writer failures', 'sync status',
// GBRA-218: the member listing only reads the members table (the verify step of access_member_* refusals).
'access member list',
// GST-363: the serves view only reads members and config (the verify step of setup_serves_several); `access serves several` stays mutating.
'access serves --json',
// GBRA-218 A2: folder-rule status and listing only read the policy tables and the committed file.
'access rule status', 'access rule list',
// GBRA-130 A-25: `--failed` lists held propose_takes pages from the failure ledger; it never extracts or writes.
'takes propose --failed',
// #6466: `--list` returns before the orchestration lock and never runs an orchestrator or writes the ledger.
'apply-migrations --list',
// #6661: [X12] --status takes no lock, makes no home dir and writes no receipt; it probes the serve over HTTP.
'bootstrap harness --status',
// #6803: the stale-extraction preview returns before any write and reports the terminal counts (actionable, mention_due).
'extract --stale --dry-run',
// #7179: per-page search state; reads page, chunk, budget and hold rows plus Git objects, writes nothing.
'pages status',
// G1/G7a: the git-gap census reads pages and Git objects in read-only transactions and writes nothing.
'sources git-gap']);
function tsFiles(dir: string): string[] {
if (!existsSync(dir)) return [];
const out: string[] = [];
for (const e of readdirSync(dir).sort()) {
const full = join(dir, e);
if (statSync(full).isDirectory()) out.push(...tsFiles(full));
else if (e.endsWith('.ts') && !e.endsWith('.generated.ts')) out.push(full);
}
return out;
}
const rel = (f: string) => relative(ROOT, f).split(sep).join('/');
function stringText(n: ts.Node): string | undefined {
if (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n)) return n.text;
if (ts.isTemplateExpression(n)) return n.head.text + n.templateSpans.map(s => s.literal.text).join('');
return undefined;
}
/** String text of a literal or a `'a' + 'b'` concatenation of literals. */
function flatText(n: ts.Node, sf: ts.SourceFile): string | undefined {
if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.PlusToken) {
const l = flatText(n.left, sf); const r = flatText(n.right, sf);
return l !== undefined && r !== undefined ? l + r : undefined;
}
if (ts.isParenthesizedExpression(n)) return flatText(n.expression, sf);
return stringText(n);
}
function literalCodes(n: ts.Node): string[] {
if (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n)) return [n.text];
if (ts.isConditionalExpression(n)) return [...literalCodes(n.whenTrue), ...literalCodes(n.whenFalse)];
if (ts.isParenthesizedExpression(n)) return literalCodes(n.expression);
return [];
}
function propName(n: ts.ObjectLiteralElementLike): string | undefined {
if (!n.name) return undefined;
if (ts.isIdentifier(n.name) || ts.isStringLiteral(n.name)) return n.name.text;
return undefined;
}
function insideHandler(n: ts.Node): boolean {
for (let p = n.parent; p; p = p.parent) {
if (ts.isPropertyAssignment(p) && propName(p) === 'handler') return true;
}
return false;
}
/** Every literal error code thrown in one file (OperationError family, StructuredError builders, CredentialError). */
export function collectThrownCodes(sf: ts.SourceFile): Array<{ code: string; line: number }> {
const out: Array<{ code: string; line: number }> = [];
const visit = (n: ts.Node) => {
if ((ts.isNewExpression(n) || ts.isCallExpression(n)) && n.arguments?.length) {
const callee = n.expression.getText(sf);
const line = sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1;
if (/^(OperationError|verbError|opError|OperationError\.bare|CredentialError)$/.test(callee)) {
for (const code of literalCodes(n.arguments[0])) out.push({ code, line });
} else if (/^(errorFor|buildError)$/.test(callee) && ts.isObjectLiteralExpression(n.arguments[0])) {
for (const p of n.arguments[0].properties) {
if (ts.isPropertyAssignment(p) && propName(p) === 'code') for (const code of literalCodes(p.initializer)) out.push({ code, line });
}
}
}
ts.forEachChild(n, visit);
};
visit(sf);
return out;
}
/** Registered codes, parsed syntactically from the registry module (fixture-safe). */
export function registeredCodes(root: string = ROOT): Set<string> | null {
const path = join(root, 'src', 'core', 'error-registry.ts');
if (!existsSync(path)) return null;
const text = readFileSync(path, 'utf8');
const body = text.slice(text.indexOf('export const CODES'));
return new Set([...body.matchAll(/^ {2}([a-z0-9_]+): \{/gm)].map(m => m[1]!));
}
function readOnlyCommands(root: string): Set<string> {
const set = new Set(STATIC_READ_ONLY);
const table = join(root, 'src', 'cli', 'command-table.ts');
if (existsSync(table)) {
for (const m of readFileSync(table, 'utf8').matchAll(/\{ name: '([a-z0-9-]+)'[^\n]*read_only: true/g)) set.add(m[1]!);
}
return set;
}
export function scan(root: string = ROOT): Hit[] {
const hits: Hit[] = [];
const readOnly = readOnlyCommands(root);
const registry = registeredCodes(root);
for (const file of tsFiles(join(root, 'src'))) {
const path = rel(file);
const text = readFileSync(file, 'utf8');
const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
const isOpsOrMcp = path.startsWith('src/core/ops/') || path.startsWith('src/mcp/');
const ioExempt = path === 'src/core/interaction.ts' || path === 'src/core/consent.ts';
const markerExempt = path === 'src/core/agent-output.ts' || path === 'src/core/agent-markers.ts';
const add = (rule: Rule, n: ts.Node) => hits.push({
rule, file: path, line: sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1,
text: n.getText(sf).split('\n')[0]!.slice(0, 120),
});
const visit = (n: ts.Node) => {
if (ts.isNewExpression(n) && n.expression.getText(sf) === 'OperationError' && path !== 'src/core/ops/contract.ts') {
const args = n.arguments ?? [];
if (args.length < 3 || args[2]!.getText(sf) === 'undefined') add('suggestionless-operation-error', n);
}
if (isFnLike(n) && sinkCalls(n, sf).length) {
for (const p of n.parameters) {
if (!ts.isIdentifier(p.name) || !SUGGESTION_PARAM.test(p.name.text)) continue;
if (p.initializer || p.questionToken || nullishDefaulted(n, p.name.text)) add('defaulted-suggestion', p);
}
}
if ((ts.isCallExpression(n) || ts.isNewExpression(n)) && SUGGESTION_ARG[n.expression.getText(sf)] !== undefined) {
const arg = (n.arguments ?? [])[SUGGESTION_ARG[n.expression.getText(sf)]!];
const t = arg ? flatText(arg, sf) : undefined;
if (t !== undefined && isGenericSuggestion(t)) add('generic-suggestion', arg!);
}
if ((ts.isCallExpression(n) || ts.isNewExpression(n)) && ERROR_CALLEE.test(n.expression.getText(sf))) {
const texts = errorTextArgs(n, sf);
for (const arg of texts) {
const t = stringText(arg);
if (t === undefined) continue;
if (isOpsOrMcp && FLAG_RE.test(t) && !t.includes('gbrain ')) add('flag-in-mcp-text', arg);
}
const suggestion = n.expression.getText(sf) === 'hostOnlyError' ? undefined : stringText((n.arguments ?? [])[2] ?? n);
if (suggestion !== undefined && (n.arguments ?? [])[2] && PLACEHOLDER_RE.test(suggestion)) add('in-scope-placeholder', n.arguments![2]!);
const op = enclosingOp(n);
if (op && suggestion !== undefined && (n.arguments ?? [])[2] && literalProp(op, 'mutating') === 'true' && literalProp(op, 'idempotent') !== 'true'
&& RETRY_RE.test(suggestion) && !SAFE_RETRY_RE.test(suggestion)) add('retry-on-mutating', n.arguments![2]!);
}
if (ts.isArrayLiteralExpression(n) && ts.isPropertyAssignment(n.parent) && propName(n.parent) === 'argv'
&& ts.isObjectLiteralExpression(n.parent.parent) && literalProp(n.parent.parent, 'inputs') === undefined
&& !(ts.isPropertyAssignment(n.parent.parent.parent) && propName(n.parent.parent.parent) === 'cliOnly')
&& n.elements.some(e => /^<[^>]+>$/.test(stringText(e) ?? ''))) add('in-scope-placeholder', n);
if (isOpsOrMcp && path.startsWith('src/core/ops/') && ts.isPropertyAssignment(n) && propName(n) === 'description'
&& ts.isObjectLiteralExpression(n.parent) && literalProp(n.parent, 'handler') !== undefined) {
const t = flatText(n.initializer, sf);
if (t !== undefined && FLAG_RE.test(t) && !t.includes('gbrain ')) add('flag-in-mcp-text', n);
}
if (ts.isThrowStatement(n) && n.expression && ts.isNewExpression(n.expression) && n.expression.expression.getText(sf) === 'Error'
&& (isOpsOrMcp || insideHandler(n))) add('throw-new-error-in-ops', n);
if (ts.isPropertyAssignment(n)) {
const name = propName(n);
const value = stringText(n.initializer);
if ((name === 'fix' || name === 'next_action') && value !== undefined && /(^|`|\s)gbrain /.test(value)) add('hand-built-command', n);
if (name && LEGACY_ADVICE_KEYS.has(name)) add('legacy-advice-key', n);
if (name === 'stdio' && value === 'inherit' && path !== 'src/core/cli-force-exit.ts') add('stdio-inherit', n);
if (name === 'verify' && ts.isObjectLiteralExpression(n.initializer)) {
for (const p of n.initializer.properties) {
if (!ts.isPropertyAssignment(p) || propName(p) !== 'argv' || !ts.isArrayLiteralExpression(p.initializer)) continue;
const words = p.initializer.elements.map(e => stringText(e));
if (words[0] !== 'gbrain' || words[1] === undefined) continue;
if (!readOnly.has(words[1]!) && !READ_ONLY_SUBCOMMANDS.has(`${words[1]} ${words[2]}`) && !READ_ONLY_SUBCOMMANDS.has(`${words[1]} ${words[2]} ${words[3]}`)) add('verify-not-read-only', p);
}
}
}
if (ts.isShorthandPropertyAssignment(n) && LEGACY_ADVICE_KEYS.has(n.name.text)) add('legacy-advice-key', n);
if (!ioExempt) {
if (ts.isCallExpression(n)) {
const callee = n.expression.getText(sf);
if ((/(^|\.)createInterface$/.test(callee) || /^process\.stdin\.(on|once)$/.test(callee) || /\.setRawMode$/.test(callee))
&& !INTERACTIVE_IO_ALLOW[path]?.[callee]) add('interactive-io', n);
if (/(^|\.)readFileSync$/.test(callee) && n.arguments[0] && stringText(n.arguments[0]) === '/dev/stdin') add('interactive-io', n);
}
if (ts.isForOfStatement(n) && n.awaitModifier && n.expression.getText(sf) === 'process.stdin') add('interactive-io', n);
}
const lit = stringText(n);
if (lit !== undefined && (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n) || ts.isTemplateExpression(n))) {
if (!markerExempt && MARKER_RE.test(lit)) add('marker-literal', n);
if (path !== 'src/core/consent.ts' && YES_RERUN_RE.test(lit)) add('yes-rerun-string', n);
}
ts.forEachChild(n, visit);
};
visit(sf);
for (const site of funnelCallSites(sf, path)) {
if (site.texts?.some(isGenericSuggestion)) {
hits.push({ rule: 'generic-suggestion', file: path, line: site.line, text: `${site.funnel}(…, ${site.expr.slice(0, 100)})` });
}
}
if (registry) {
for (const { code, line } of collectThrownCodes(sf)) {
if (!registry.has(code)) hits.push({ rule: 'unregistered-code', file: path, line, text: code });
}
}
}
if (registry) {
for (const code of registry) {
if (!/^[a-z][a-z0-9_]*$/.test(code) || TRANSPORT_PREFIX.test(code)) {
hits.push({ rule: 'code-naming', file: 'src/core/error-registry.ts', line: 0, text: code });
}
}
}
return hits;
}
function readBaseline(rule: Rule): Map<string, number> | null {
const path = join(BASELINE_DIR, `${rule}.tsv`);
if (!existsSync(path)) return null;
const m = new Map<string, number>();
for (const line of readFileSync(path, 'utf8').split('\n')) {
if (!line || line.startsWith('#')) continue;
const [file, count] = line.split('\t');
m.set(file!, Number(count));
}
return m;
}
function countsByFile(hits: Hit[], rule: Rule): Map<string, number> {
const m = new Map<string, number>();
for (const h of hits) if (h.rule === rule) m.set(h.file, (m.get(h.file) ?? 0) + 1);
return m;
}
function writeBaseline(rule: Rule, counts: Map<string, number>): void {
mkdirSync(BASELINE_DIR, { recursive: true });
const lines = [...counts.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([f, c]) => `${f}\t${c}`);
writeFileSync(join(BASELINE_DIR, `${rule}.tsv`),
`# shrink-only baseline for scripts/check-agent-contract.ts rule ${rule}: path<TAB>count\n${lines.join('\n')}${lines.length ? '\n' : ''}`);
}
function main(): number {
const update = process.argv.includes('--update');
const started = performance.now();
const hits = scan();
const failures: string[] = [];
for (const h of hits) {
if (h.rule === 'unregistered-code') failures.push(`${h.file}:${h.line} [unregistered-code] '${h.text}' is thrown but not registered — add a row to src/core/error-registry.ts, then bun run build:error-codes`);
if (h.rule === 'defaulted-suggestion') failures.push(`${h.file}:${h.line} [defaulted-suggestion] ${h.text}: a default suggestion lets call sites skip their next step — make it required and pass one at every call site`);
if (h.rule === 'generic-suggestion') failures.push(`${h.file}:${h.line} [generic-suggestion] ${h.text}: name the exact next step (the flag usage, the command, the value to pass), not a generic phrase`);
if (h.rule === 'code-naming') failures.push(`[code-naming] registry code '${h.text}' must be snake_case with no transport prefix`);
}
for (const rule of BASELINED_RULES) {
const counts = countsByFile(hits, rule);
const baseline = readBaseline(rule) ?? new Map<string, number>();
if (update) {
const grew = [...counts].filter(([f, c]) => c > (baseline.get(f) ?? 0));
if (grew.length && !process.argv.includes('--allow-grow')) {
for (const [f, c] of grew) failures.push(`${f} [${rule}] ${c} > baseline ${baseline.get(f) ?? 0}: --update only shrinks baselines`);
} else {
writeBaseline(rule, counts);
}
continue;
}
for (const [file, count] of counts) {
const allowed = baseline.get(file) ?? 0;
if (count > allowed) {
const where = hits.filter(h => h.rule === rule && h.file === file).map(h => ` ${h.file}:${h.line} ${h.text}`).join('\n');
failures.push(`${file} [${rule}] ${count} hit(s), baseline ${allowed}. New violation(s):\n${where}`);
}
}
for (const [file, allowed] of baseline) {
const count = counts.get(file) ?? 0;
if (count < allowed) failures.push(`${file} [${rule}] shrank to ${count} (baseline ${allowed}): lower the baseline with bun scripts/check-agent-contract.ts --update`);
}
}
const ms = Math.round(performance.now() - started);
if (failures.length) {
for (const f of failures) console.error(`FAIL ${f}`);
console.error(`check-agent-contract: ${failures.length} failure(s) in ${ms}ms. See ${DOCS}.`);
return 1;
}
console.log(`check-agent-contract: OK (${hits.length} baselined hits, ${ms}ms)`);
return 0;
}
if (import.meta.main) process.exit(main());