Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
#!/usr/bin/env node
import { readFile } from 'node:fs/promises';
import { spawn } from 'node:child_process';
import {
buildContextInjection,
checkCircuitBreaker,
pruneLedger,
summarizeAttempts,
DEFAULT_BREAKER,
DEFAULT_PRUNE,
assertSimilarityThreshold,
type Ledger,
type CircuitBreakerConfig,
type PruneConfig,
type BreakerDecision,
} from './context-manager.js';
import {
assertValidBudgetScenario,
resolveTokenBudgetFromPattern,
resolveDailyBudgetFromPattern,
type BudgetScenario,
} from './budget-resolver.js';
import { recordDailySpend } from './daily-spend.js';
type Op = 'check' | 'prune' | 'inject' | 'summary' | 'status';
interface Args {
help: boolean;
op: Op;
ledger?: string;
json: boolean;
breaker: CircuitBreakerConfig;
prune: PruneConfig;
budgetFromPattern?: string;
budgetLevel: string;
budgetScenario: BudgetScenario;
budgetCadence?: string;
budgetConservative: boolean;
dailyBudgetFromPattern?: string;
dailyStateDir: string;
onExceed?: string;
}
/** Reject NaN/0/floats so a bad flag cannot silently disable the breaker. */
function parsePositiveIntFlag(raw: string | undefined, flag: string): number {
if (raw === undefined || raw === '') {
throw new Error(`${flag} requires a positive integer value.`);
}
const n = Number(raw);
if (!Number.isInteger(n) || n < 1) {
throw new Error(`${flag} must be a positive integer; got "${raw}".`);
}
return n;
}
/**
* A similarity threshold is a fraction in (0, 1]. "95" (meant as 95%) used to
* be accepted and silently switched off the stagnation rule, because no two
* errors are ever more than 1.0 similar.
*/
function parseFractionFlag(raw: string | undefined, flag: string): number {
if (raw === undefined || raw === '') {
throw new Error(`${flag} requires a value between 0 and 1 (e.g. 0.85).`);
}
const n = Number(raw);
// Report "abc" rather than NaN when the value is not a number at all.
assertSimilarityThreshold(Number.isNaN(n) ? raw : n, flag);
return n;
}
function parseArgs(argv: string[]): Args {
const breaker: CircuitBreakerConfig = { ...DEFAULT_BREAKER };
const prune: PruneConfig = { ...DEFAULT_PRUNE };
let op: Op = 'status';
let ledger: string | undefined;
let json = false;
let budgetFromPattern: string | undefined;
let budgetLevel = 'L1';
let budgetScenario: BudgetScenario = 'realistic';
let budgetCadence: string | undefined;
let budgetConservative = false;
let dailyBudgetFromPattern: string | undefined;
let dailyStateDir = '.loop-context';
let onExceed: string | undefined;
const base = () => ({
op, json, breaker, prune,
budgetFromPattern, budgetLevel, budgetScenario, budgetCadence, budgetConservative,
dailyBudgetFromPattern, dailyStateDir, onExceed,
});
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (a === '--help' || a === '-h') return { help: true, ...base() };
else if (a === '--ledger' || a === '-f') ledger = argv[++i];
else if (a === '--check') op = 'check';
else if (a === '--prune') op = 'prune';
else if (a === '--inject') op = 'inject';
else if (a === '--summary') op = 'summary';
else if (a === '--status') op = 'status';
else if (a === '--json') json = true;
else if (a === '--max-iterations') breaker.maxIterations = parsePositiveIntFlag(argv[++i], '--max-iterations');
else if (a === '--stagnation') breaker.stagnationThreshold = parsePositiveIntFlag(argv[++i], '--stagnation');
else if (a === '--no-progress') breaker.noProgressThreshold = parsePositiveIntFlag(argv[++i], '--no-progress');
else if (a === '--token-budget') breaker.tokenBudget = parsePositiveIntFlag(argv[++i], '--token-budget');
else if (a === '--budget-from-pattern') budgetFromPattern = argv[++i];
else if (a === '--budget-level') budgetLevel = argv[++i];
else if (a === '--budget-scenario') budgetScenario = argv[++i] as BudgetScenario;
else if (a === '--budget-cadence') budgetCadence = argv[++i];
else if (a === '--budget-conservative') budgetConservative = true;
else if (a === '--daily-budget-from-pattern') dailyBudgetFromPattern = argv[++i];
else if (a === '--daily-state-dir') dailyStateDir = argv[++i];
else if (a === '--on-exceed') onExceed = argv[++i];
else if (a === '--window') prune.window = parsePositiveIntFlag(argv[++i], '--window');
else if (a === '--max-trace-lines') prune.maxTraceLines = parsePositiveIntFlag(argv[++i], '--max-trace-lines');
else if (a === '--similarity-threshold') {
const val = parseFractionFlag(argv[++i], '--similarity-threshold');
breaker.similarityThreshold = val;
prune.similarityThreshold = val;
}
}
return { help: false, ledger, ...base() };
}
async function readLedger(pathArg?: string): Promise<Ledger> {
const raw = pathArg
? await readFile(pathArg, 'utf8')
: await readStdin();
if (!raw.trim()) {
throw new Error('No ledger provided. Pass --ledger <file.json> or pipe JSON on stdin.');
}
const parsed = JSON.parse(raw) as Ledger;
if (typeof parsed.goal !== 'string' || !Array.isArray(parsed.attempts)) {
throw new Error('Invalid ledger: expected { goal: string, attempts: Attempt[] }.');
}
return parsed;
}
function readStdin(): Promise<string> {
return new Promise((resolve, reject) => {
let data = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', (c) => (data += c));
process.stdin.on('end', () => resolve(data));
process.stdin.on('error', reject);
});
}
const HELP = `loop-context — stateful memory manager for agent loops
Keeps a loop's context window clean and stops runaway loops. Reads a run ledger
(JSON) and summarizes, prunes, injects, or applies the circuit breaker.
Usage:
loop-context [operation] [--ledger <file.json>] [options]
cat ledger.json | loop-context --check
loop-context --check --ledger run.json --budget-from-pattern ci-sweeper --budget-level L2
loop-context --check --ledger run.json --daily-budget-from-pattern ci-sweeper --on-exceed ./on-exceed.sh
Operations (default: --status):
--check Run the circuit breaker. Exit 0 = continue, 2 = escalate.
--prune Emit a pruned ledger (recent window, trimmed traces, collapsed).
--inject Emit the compact context block for the next prompt.
--summary Emit a factual rollup of the run.
--status Human-readable overview (summary + breaker decision).
Options:
-f, --ledger <file> Ledger JSON file (default: stdin)
--json Machine-readable output where applicable
--max-iterations <n> Iteration cap (default: ${DEFAULT_BREAKER.maxIterations})
--stagnation <n> Same-error repeat limit (default: ${DEFAULT_BREAKER.stagnationThreshold})
--no-progress <n> Consecutive-failure limit (default: ${DEFAULT_BREAKER.noProgressThreshold})
--token-budget <n> Total token cap (default: none)
--budget-from-pattern <id>
Resolve the token cap from loop-cost's registry
estimate instead of typing a number. Ignored if
--token-budget is also given (explicit wins).
--budget-level <L1|L2|L3> Readiness level for --budget-from-pattern (default: L1)
--budget-scenario <realistic|action|report|caching>
Which loop-cost scenario to use (default: realistic).
caching requires stable_fraction set on the pattern
in registry.yaml (see loop-cost --with-caching).
--budget-cadence <spec> Cadence override passed through to loop-cost
--budget-conservative Use the slower cadence in a range (loop-cost flag)
--daily-budget-from-pattern <id>
Track cumulative daily spend for this pattern
across separate --check calls/runs and escalate
(trigger: daily-budget) once it reaches loop-cost's
suggested daily cap. Ignored if a per-run trigger
already escalated. Uses --budget-level/-cadence/
-conservative for the lookup.
--daily-state-dir <dir> Where daily-spend.<pattern>.json is kept (default: .loop-context)
--on-exceed <script> On escalate, pipe the decision as JSON to this
script's stdin (fire-and-forget; its exit code
is not checked and does not change --check's own).
--similarity-threshold <f> Fraction in (0, 1] to cluster similar errors (default: ${DEFAULT_BREAKER.similarityThreshold}).
A fraction, not a percentage: 0.95, not 95
--window <n> Attempts kept when pruning (default: ${DEFAULT_PRUNE.window})
--max-trace-lines <n> Stack-trace lines kept (default: ${DEFAULT_PRUNE.maxTraceLines})
-h, --help This help
Ledger shape:
{ "goal": "...", "attempts": [ { "iteration": 1, "action": "...",
"outcome": "failure", "error": "...", "tokensUsed": 1200 } ] }
Exit codes: 0 continue · 2 escalate · 1 error
`;
async function main() {
const args = parseArgs(process.argv.slice(2));
if (args.help) {
console.log(HELP);
return;
}
if (args.budgetFromPattern && args.breaker.tokenBudget === undefined) {
args.breaker.tokenBudget = await resolveTokenBudgetFromPattern({
pattern: args.budgetFromPattern,
level: args.budgetLevel,
scenario: args.budgetScenario,
cadence: args.budgetCadence,
conservative: args.budgetConservative,
});
}
const ledger = await readLedger(args.ledger);
switch (args.op) {
case 'check': {
let decision = checkCircuitBreaker(ledger, args.breaker);
if (args.dailyBudgetFromPattern) {
decision = await applyDailyBudget(decision, ledger, args);
}
if (decision.escalate && args.onExceed) {
await runOnExceedHook(args.onExceed, decision);
}
if (args.json) console.log(JSON.stringify(decision, null, 2));
else console.log(`${decision.escalate ? 'ESCALATE' : 'CONTINUE'} [${decision.trigger}] — ${decision.reason}`);
process.exitCode = decision.escalate ? 2 : 0;
return;
}
case 'prune':
console.log(JSON.stringify(pruneLedger(ledger, args.prune), null, 2));
return;
case 'summary': {
const summary = summarizeAttempts(ledger);
if (args.json) console.log(JSON.stringify(summary, null, 2));
else console.log(formatSummary(summary));
return;
}
case 'inject':
console.log(buildContextInjection(ledger, args.breaker, args.prune));
return;
case 'status':
default: {
const summary = summarizeAttempts(ledger);
const decision = checkCircuitBreaker(ledger, args.breaker);
console.log(formatSummary(summary));
console.log('');
console.log(`Circuit breaker: ${decision.escalate ? 'ESCALATE' : 'CONTINUE'} [${decision.trigger}]`);
console.log(` ${decision.reason}`);
process.exitCode = decision.escalate ? 2 : 0;
return;
}
}
}
/**
* Add the newest attempt's tokensUsed to the pattern's running daily total
* (rolling over on UTC date change) and, if that total reaches loop-cost's
* suggested daily cap, override the decision to escalate — but only when no
* per-run trigger already fired.
*/
async function applyDailyBudget(decision: BreakerDecision, ledger: Ledger, args: Args): Promise<BreakerDecision> {
const pattern = args.dailyBudgetFromPattern as string;
const latest = ledger.attempts[ledger.attempts.length - 1];
const tokensDelta = latest?.tokensUsed ?? 0;
const state = await recordDailySpend(args.dailyStateDir, pattern, tokensDelta);
if (decision.escalate) return decision;
const dailyCap = await resolveDailyBudgetFromPattern({
pattern,
level: args.budgetLevel,
cadence: args.budgetCadence,
conservative: args.budgetConservative,
});
if (state.tokensUsedToday >= dailyCap) {
return {
...decision,
shouldContinue: false,
escalate: true,
trigger: 'daily-budget',
reason: `Daily token spend for pattern "${pattern}" reached ${state.tokensUsedToday} (cap ${dailyCap}). Escalating to avoid cost blowup.`,
};
}
return decision;
}
/** Pipe the escalation decision as JSON to an operator-provided script's stdin. Fire-and-forget. */
function runOnExceedHook(script: string, decision: BreakerDecision): Promise<void> {
return new Promise((resolve) => {
const child = spawn(script, [], { stdio: ['pipe', 'inherit', 'inherit'], shell: true });
child.on('error', (err) => {
console.error(`loop-context: --on-exceed hook failed to start: ${err.message}`);
resolve();
});
child.on('close', () => resolve());
// The hook script may exit without ever reading stdin (e.g. a notify
// script that ignores its input). Writing to that already-closed pipe
// then raises an 'error' event (EPIPE on POSIX, EOF on Windows) on the
// stream itself; left unhandled, Node treats that as an uncaught
// exception and crashes the whole process. This hook is documented as
// fire-and-forget, so a write failure here must not escalate past the
// 'close' handler above, which resolves regardless.
child.stdin.on('error', () => {});
child.stdin.write(JSON.stringify(decision));
child.stdin.end();
});
}
function formatSummary(s: ReturnType<typeof summarizeAttempts>): string {
const lines: string[] = [];
lines.push(`Attempts: ${s.totalAttempts} (${s.successes} ok · ${s.failures} failed · ${s.noops} no-op)`);
if (s.tokensUsed) lines.push(`Tokens used: ${s.tokensUsed}`);
if (s.distinctErrors.length) {
lines.push('Distinct errors (most frequent first):');
for (const g of s.distinctErrors) lines.push(` (${g.count}×) ${g.sample}`);
}
if (s.actionsTried.length) {
lines.push('Actions tried:');
for (const a of s.actionsTried) lines.push(` - ${a}`);
}
return lines.join('\n');
}
main().catch((err: unknown) => {
const msg = err instanceof Error ? err.message : String(err);
console.error('loop-context failed:', msg);
process.exit(1);
});