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
feat(loop-context): resolve token budget from loop-cost pattern estimate (#258)
JonyT Agenticf12bd92ffaad
diff --git a/templates/SKILL.md.loop-guard b/templates/SKILL.md.loop-guardindex 7e6a9d3..d10aefb 100644--- a/templates/SKILL.md.loop-guard+++ b/templates/SKILL.md.loop-guard@@ -38,30 +38,27 @@ After every iteration, append what you just tried:`outcome` is `success | failure | noop`. Always include `error` on failures —that is how the breaker detects a repeated (stagnant) failure.-## Size the token budget from the pattern (once per run)+## Size the token budget from the pattern-Don't hand-type a token cap — derive it from the pattern's realistic per-run-cost so the breaker trips on genuine cost blowup, not a made-up number.-[`loop-cost`](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-cost)-already computes this from `patterns/registry.yaml`; read the loop's `pattern`-and `level` straight from the ledger:+Don't hand-type a token cap — `loop-context` can derive it directly from the+pattern's realistic per-run cost+([`loop-cost`](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-cost)+computes this from `patterns/registry.yaml`) so the breaker trips on genuine+cost blowup, not a made-up number. Substitute the ledger's own `pattern`/`level`+(here: `ci-sweeper` / `L2`):```bash-# Substitute the ledger's own pattern/level (here: ci-sweeper / L2).-BUDGET=$(npx @cobusgreyling/loop-cost --pattern ci-sweeper --level L2 --json \- | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>process.stdout.write(String(JSON.parse(d).scenarios.realistic.tokensPerRun)))')+npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \+ --budget-from-pattern ci-sweeper --budget-level L2```-`scenarios.realistic.tokensPerRun` is a rounded integer, so it feeds-`--token-budget` directly. The two tools stay independent — this is shell-wiring, not a code dependency.-## Before each iteration1. Append the previous attempt to `loop-ledger.json`.2. Run the breaker with the resolved budget:```bash- npx @cobusgreyling/loop-context --check --ledger loop-ledger.json --token-budget "$BUDGET"+ npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \+ --budget-from-pattern ci-sweeper --budget-level L2```3. Act on the exit code:- **0** → continue. Optionally trim the next prompt first:@@ -83,12 +80,13 @@ wiring, not a code dependency.- Never widen thresholds just to keep looping — escalation is a feature, not a failure.- Never edit the ledger to hide a repeated error; the breaker exists to catch it.- Defaults: 3× same error, 5 consecutive failures, 10 iterations. Tune with- `--stagnation`, `--no-progress`, `--max-iterations`, `--token-budget`.+ `--stagnation`, `--no-progress`, `--max-iterations`, or an explicit+ `--token-budget` (wins over `--budget-from-pattern` if both are given).## Interaction with other skills- `minimal-fix` / `ci-triage` — record each attempt's outcome + error in the ledger.- `loop-verifier` — a verifier rejection is a `failure`; log it so repeats trip the breaker.- `loop-constraints` — honors "escalate after N attempts"; this skill makes it mechanical.-- `loop-budget` — the per-run `--token-budget` here comes from loop-cost's- realistic estimate; loop-budget.md still governs the *daily* cap across runs.+- `loop-budget` — the per-run budget here comes from `--budget-from-pattern`;+ loop-budget.md still governs the *daily* cap across runs.diff --git a/tools/loop-context/README.md b/tools/loop-context/README.mdindex d5e8c14..e946e5d 100644--- a/tools/loop-context/README.md+++ b/tools/loop-context/README.md@@ -75,6 +75,31 @@ cat run.json | loop-context --checkExit codes: `0` continue · `2` escalate · `1` error.+## Resolving the token budget from a pattern++Typing `--token-budget <n>` by hand means guessing. [`loop-cost`](../loop-cost) already+computes a realistic per-run estimate for every pattern and readiness level, so resolve+the cap from there instead:++```bash+loop-context --check --ledger run.json --budget-from-pattern ci-sweeper --budget-level L2+```++| Flag | Default | Meaning |+|------|---------|---------|+| `--budget-from-pattern <id>` | none | Pattern id to look up in `loop-cost`'s registry |+| `--budget-level <L1\|L2\|L3>` | `L1` | Readiness level passed to `loop-cost` |+| `--budget-scenario <realistic\|action\|report>` | `realistic` | Which `loop-cost` scenario to use as the cap |+| `--budget-cadence <spec>` | pattern default | Cadence override passed through to `loop-cost` |+| `--budget-conservative` | off | Use the slower cadence in a range (`loop-cost`'s own flag) |++An explicit `--token-budget <n>` always wins over `--budget-from-pattern` — the derived+value only fills in when no number was typed. `loop-context` shells out to `loop-cost`'s+built CLI (monorepo sibling first, then an installed `@cobusgreyling/loop-cost`+dependency) — the same resolution `loop-init` already uses for `loop-audit` — so the two+packages stay independent at the source level; an unknown pattern id surfaces+`loop-cost`'s own error instead of failing silently.+## Populating the ledgerYour loop control script appends one object per iteration to `run.json` (or pipes the same shape on stdin):diff --git a/tools/loop-context/dist/budget-resolver.d.ts b/tools/loop-context/dist/budget-resolver.d.tsnew file mode 100644index 0000000..03a4ca0--- /dev/null+++ b/tools/loop-context/dist/budget-resolver.d.ts@@ -0,0 +1,19 @@+export type BudgetScenario = 'realistic' | 'action' | 'report';+export declare const VALID_BUDGET_SCENARIOS: BudgetScenario[];+export declare function assertValidBudgetScenario(scenario: string): asserts scenario is BudgetScenario;+export interface BudgetFromPatternInput {+ pattern: string;+ level?: string;+ scenario?: BudgetScenario;+ cadence?: string;+ conservative?: boolean;+}+/** Locate loop-cost's built CLI: monorepo sibling first, then an installed dependency. */+export declare function resolveCostCli(): Promise<string | null>;+/**+ * Resolve a token budget from loop-cost's realistic per-pattern estimate+ * instead of a hand-typed number. Shells out to loop-cost's built CLI+ * (same monorepo-then-installed-dependency resolution loop-init uses for+ * loop-audit) so the two tools stay independent at the source level.+ */+export declare function resolveTokenBudgetFromPattern(input: BudgetFromPatternInput): Promise<number>;diff --git a/tools/loop-context/dist/budget-resolver.js b/tools/loop-context/dist/budget-resolver.jsnew file mode 100644index 0000000..7f12e7f--- /dev/null+++ b/tools/loop-context/dist/budget-resolver.js@@ -0,0 +1,85 @@+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { access } from 'node:fs/promises';+import { spawn } from 'node:child_process';+const __dirname = path.dirname(fileURLToPath(import.meta.url));+const PACKAGE_ROOT = path.resolve(__dirname, '..');+export const VALID_BUDGET_SCENARIOS = ['realistic', 'action', 'report'];+export function assertValidBudgetScenario(scenario) {+ if (!VALID_BUDGET_SCENARIOS.includes(scenario)) {+ throw new Error(`Invalid --budget-scenario: ${scenario}. Valid: ${VALID_BUDGET_SCENARIOS.join(', ')}`);+ }+}+async function exists(p) {+ try {+ await access(p);+ return true;+ }+ catch {+ return false;+ }+}+/** Locate loop-cost's built CLI: monorepo sibling first, then an installed dependency. */+export async function resolveCostCli() {+ const monorepo = path.resolve(PACKAGE_ROOT, '../loop-cost/dist/cli.js');+ if (await exists(monorepo))+ return monorepo;+ try {+ const { createRequire } = await import('node:module');+ const require = createRequire(import.meta.url);+ const pkg = require.resolve('@cobusgreyling/loop-cost/package.json');+ return path.join(path.dirname(pkg), 'dist/cli.js');+ }+ catch {+ return null;+ }+}+function runCostCli(cli, args) {+ return new Promise((resolve, reject) => {+ const child = spawn('node', [cli, ...args, '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });+ let stdout = '';+ let stderr = '';+ child.stdout.on('data', (chunk) => (stdout += chunk.toString()));+ child.stderr.on('data', (chunk) => (stderr += chunk.toString()));+ child.on('error', reject);+ child.on('close', (code) => resolve({ stdout, stderr, code }));+ });+}+/**+ * Resolve a token budget from loop-cost's realistic per-pattern estimate+ * instead of a hand-typed number. Shells out to loop-cost's built CLI+ * (same monorepo-then-installed-dependency resolution loop-init uses for+ * loop-audit) so the two tools stay independent at the source level.+ */+export async function resolveTokenBudgetFromPattern(input) {+ const scenario = input.scenario ?? 'realistic';+ assertValidBudgetScenario(scenario);+ const cli = await resolveCostCli();+ if (!cli) {+ throw new Error('--budget-from-pattern requires @cobusgreyling/loop-cost. Install it, or run from the loop-engineering monorepo.');+ }+ const args = ['--pattern', input.pattern, '--level', input.level ?? 'L1'];+ if (input.cadence)+ args.push('--cadence', input.cadence);+ if (input.conservative)+ args.push('--conservative');+ const { stdout, stderr, code } = await runCostCli(cli, args);+ if (code !== 0) {+ throw new Error(stderr.trim() || `loop-cost exited with code ${code}.`);+ }+ if (!stdout.trim()) {+ throw new Error('loop-cost produced no output.');+ }+ let parsed;+ try {+ parsed = JSON.parse(stdout);+ }+ catch {+ throw new Error('loop-cost produced output that could not be parsed as JSON.');+ }+ const tokensPerRun = parsed.scenarios?.[scenario]?.tokensPerRun;+ if (typeof tokensPerRun !== 'number') {+ throw new Error(`loop-cost output missing scenarios.${scenario}.tokensPerRun.`);+ }+ return tokensPerRun;+}diff --git a/tools/loop-context/dist/cli.js b/tools/loop-context/dist/cli.jsindex 806b182..f1c8b70 100755--- a/tools/loop-context/dist/cli.js+++ b/tools/loop-context/dist/cli.js@@ -1,6 +1,7 @@#!/usr/bin/env nodeimport { readFile } from 'node:fs/promises';import { buildContextInjection, checkCircuitBreaker, pruneLedger, summarizeAttempts, DEFAULT_BREAKER, DEFAULT_PRUNE, } from './context-manager.js';+import { resolveTokenBudgetFromPattern, } from './budget-resolver.js';/** Reject NaN/0/floats so a bad flag cannot silently disable the breaker. */function parsePositiveIntFlag(raw, flag) {if (raw === undefined || raw === '') {@@ -18,10 +19,19 @@ function parseArgs(argv) {let op = 'status';let ledger;let json = false;+ let budgetFromPattern;+ let budgetLevel = 'L1';+ let budgetScenario = 'realistic';+ let budgetCadence;+ let budgetConservative = false;+ const base = () => ({+ op, json, breaker, prune,+ budgetFromPattern, budgetLevel, budgetScenario, budgetCadence, budgetConservative,+ });for (let i = 0; i < argv.length; i++) {const a = argv[i];if (a === '--help' || a === '-h')- return { help: true, op, json, breaker, prune };+ return { help: true, ...base() };else if (a === '--ledger' || a === '-f')ledger = argv[++i];else if (a === '--check')@@ -44,12 +54,22 @@ function parseArgs(argv) {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];+ else if (a === '--budget-cadence')+ budgetCadence = argv[++i];+ else if (a === '--budget-conservative')+ budgetConservative = true;else if (a === '--window')prune.window = parsePositiveIntFlag(argv[++i], '--window');else if (a === '--max-trace-lines')prune.maxTraceLines = parsePositiveIntFlag(argv[++i], '--max-trace-lines');}- return { help: false, op, ledger, json, breaker, prune };+ return { help: false, ledger, ...base() };}async function readLedger(pathArg) {const raw = pathArg@@ -81,6 +101,7 @@ Keeps a loop's context window clean and stops runaway loops. Reads a run ledgerUsage: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 L2Operations (default: --status):--check Run the circuit breaker. Exit 0 = continue, 2 = escalate.@@ -96,6 +117,15 @@ Options:--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>+ Which loop-cost scenario to use (default: realistic)+ --budget-cadence <spec> Cadence override passed through to loop-cost+ --budget-conservative Use the slower cadence in a range (loop-cost flag)--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@@ -112,6 +142,15 @@ async function main() {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': {diff --git a/tools/loop-context/package-lock.json b/tools/loop-context/package-lock.jsonindex b6db3e1..f9194d9 100644--- a/tools/loop-context/package-lock.json+++ b/tools/loop-context/package-lock.json@@ -1,13 +1,16 @@{"name": "@cobusgreyling/loop-context",- "version": "1.0.0",+ "version": "1.1.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@cobusgreyling/loop-context",- "version": "1.0.0",+ "version": "1.1.0","license": "MIT",+ "dependencies": {+ "@cobusgreyling/loop-cost": "^1.0.3"+ },"bin": {"loop-context": "dist/cli.js"},@@ -19,6 +22,21 @@"node": ">=18"}},+ "node_modules/@cobusgreyling/loop-cost": {+ "version": "1.0.3",+ "resolved": "https://registry.npmjs.org/@cobusgreyling/loop-cost/-/loop-cost-1.0.3.tgz",+ "integrity": "sha512-SeGPv8hhW0hnbcDBS4c9RwKtuU726VTL3cwyDRtGaaJHO6GLpRD/5+iGgl5lbwfjH/3H+H3OleYShxpmaejVYw==",+ "license": "MIT",+ "dependencies": {+ "yaml": "^2.8.0"+ },+ "bin": {+ "loop-cost": "dist/cli.js"+ },+ "engines": {+ "node": ">=18"+ }+ },"node_modules/@types/node": {"version": "20.19.43","resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",@@ -49,6 +67,21 @@"integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==","dev": true,"license": "MIT"+ },+ "node_modules/yaml": {+ "version": "2.9.0",+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",+ "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",+ "license": "ISC",+ "bin": {+ "yaml": "bin.mjs"+ },+ "engines": {+ "node": ">= 14.6"+ },+ "funding": {+ "url": "https://github.com/sponsors/eemeli"+ }}}}diff --git a/tools/loop-context/package.json b/tools/loop-context/package.jsonindex 947980f..89ecced 100644--- a/tools/loop-context/package.json+++ b/tools/loop-context/package.json@@ -1,6 +1,6 @@{"name": "@cobusgreyling/loop-context",- "version": "1.0.0",+ "version": "1.1.0","description": "Stateful memory manager for agent loops — summarize, prune, and inject context, with a circuit breaker that escalates stagnant or no-progress runs instead of burning tokens.","type": "module","main": "dist/context-manager.js",@@ -48,6 +48,9 @@"publishConfig": {"access": "public"},+ "dependencies": {+ "@cobusgreyling/loop-cost": "^1.0.3"+ },"devDependencies": {"@types/node": "^20.0.0","typescript": "^5.0.0"diff --git a/tools/loop-context/src/budget-resolver.ts b/tools/loop-context/src/budget-resolver.tsnew file mode 100644index 0000000..61628cb--- /dev/null+++ b/tools/loop-context/src/budget-resolver.ts@@ -0,0 +1,105 @@+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { access } from 'node:fs/promises';+import { spawn } from 'node:child_process';++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const PACKAGE_ROOT = path.resolve(__dirname, '..');++export type BudgetScenario = 'realistic' | 'action' | 'report';++export const VALID_BUDGET_SCENARIOS: BudgetScenario[] = ['realistic', 'action', 'report'];++export function assertValidBudgetScenario(scenario: string): asserts scenario is BudgetScenario {+ if (!VALID_BUDGET_SCENARIOS.includes(scenario as BudgetScenario)) {+ throw new Error(+ `Invalid --budget-scenario: ${scenario}. Valid: ${VALID_BUDGET_SCENARIOS.join(', ')}`,+ );+ }+}++export interface BudgetFromPatternInput {+ pattern: string;+ level?: string;+ scenario?: BudgetScenario;+ cadence?: string;+ conservative?: boolean;+}++async function exists(p: string): Promise<boolean> {+ try {+ await access(p);+ return true;+ } catch {+ return false;+ }+}++/** Locate loop-cost's built CLI: monorepo sibling first, then an installed dependency. */+export async function resolveCostCli(): Promise<string | null> {+ const monorepo = path.resolve(PACKAGE_ROOT, '../loop-cost/dist/cli.js');+ if (await exists(monorepo)) return monorepo;+ try {+ const { createRequire } = await import('node:module');+ const require = createRequire(import.meta.url);+ const pkg = require.resolve('@cobusgreyling/loop-cost/package.json');+ return path.join(path.dirname(pkg), 'dist/cli.js');+ } catch {+ return null;+ }+}++function runCostCli(cli: string, args: string[]): Promise<{ stdout: string; stderr: string; code: number | null }> {+ return new Promise((resolve, reject) => {+ const child = spawn('node', [cli, ...args, '--json'], { stdio: ['ignore', 'pipe', 'pipe'] });+ let stdout = '';+ let stderr = '';+ child.stdout.on('data', (chunk: Buffer | string) => (stdout += chunk.toString()));+ child.stderr.on('data', (chunk: Buffer | string) => (stderr += chunk.toString()));+ child.on('error', reject);+ child.on('close', (code) => resolve({ stdout, stderr, code }));+ });+}++/**+ * Resolve a token budget from loop-cost's realistic per-pattern estimate+ * instead of a hand-typed number. Shells out to loop-cost's built CLI+ * (same monorepo-then-installed-dependency resolution loop-init uses for+ * loop-audit) so the two tools stay independent at the source level.+ */+export async function resolveTokenBudgetFromPattern(input: BudgetFromPatternInput): Promise<number> {+ const scenario = input.scenario ?? 'realistic';+ assertValidBudgetScenario(scenario);++ const cli = await resolveCostCli();+ if (!cli) {+ throw new Error(+ '--budget-from-pattern requires @cobusgreyling/loop-cost. Install it, or run from the loop-engineering monorepo.',+ );+ }++ const args = ['--pattern', input.pattern, '--level', input.level ?? 'L1'];+ if (input.cadence) args.push('--cadence', input.cadence);+ if (input.conservative) args.push('--conservative');++ const { stdout, stderr, code } = await runCostCli(cli, args);+ if (code !== 0) {+ throw new Error(stderr.trim() || `loop-cost exited with code ${code}.`);+ }+ if (!stdout.trim()) {+ throw new Error('loop-cost produced no output.');+ }++ let parsed: { scenarios?: Record<string, { tokensPerRun?: number }> };+ try {+ parsed = JSON.parse(stdout);+ } catch {+ throw new Error('loop-cost produced output that could not be parsed as JSON.');+ }++ const tokensPerRun = parsed.scenarios?.[scenario]?.tokensPerRun;+ if (typeof tokensPerRun !== 'number') {+ throw new Error(`loop-cost output missing scenarios.${scenario}.tokensPerRun.`);+ }+ return tokensPerRun;+}diff --git a/tools/loop-context/src/cli.ts b/tools/loop-context/src/cli.tsindex c042081..41f2c29 100644--- a/tools/loop-context/src/cli.ts+++ b/tools/loop-context/src/cli.ts@@ -11,6 +11,11 @@ import {type CircuitBreakerConfig,type PruneConfig,} from './context-manager.js';+import {+ assertValidBudgetScenario,+ resolveTokenBudgetFromPattern,+ type BudgetScenario,+} from './budget-resolver.js';type Op = 'check' | 'prune' | 'inject' | 'summary' | 'status';@@ -21,6 +26,11 @@ interface Args {json: boolean;breaker: CircuitBreakerConfig;prune: PruneConfig;+ budgetFromPattern?: string;+ budgetLevel: string;+ budgetScenario: BudgetScenario;+ budgetCadence?: string;+ budgetConservative: boolean;}/** Reject NaN/0/floats so a bad flag cannot silently disable the breaker. */@@ -41,10 +51,20 @@ function parseArgs(argv: string[]): Args {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;++ const base = () => ({+ op, json, breaker, prune,+ budgetFromPattern, budgetLevel, budgetScenario, budgetCadence, budgetConservative,+ });for (let i = 0; i < argv.length; i++) {const a = argv[i];- if (a === '--help' || a === '-h') return { help: true, op, json, breaker, prune };+ 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';@@ -56,11 +76,16 @@ function parseArgs(argv: string[]): Args {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 === '--window') prune.window = parsePositiveIntFlag(argv[++i], '--window');else if (a === '--max-trace-lines') prune.maxTraceLines = parsePositiveIntFlag(argv[++i], '--max-trace-lines');}- return { help: false, op, ledger, json, breaker, prune };+ return { help: false, ledger, ...base() };}async function readLedger(pathArg?: string): Promise<Ledger> {@@ -95,6 +120,7 @@ Keeps a loop's context window clean and stops runaway loops. Reads a run ledgerUsage: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 L2Operations (default: --status):--check Run the circuit breaker. Exit 0 = continue, 2 = escalate.@@ -110,6 +136,15 @@ Options:--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>+ Which loop-cost scenario to use (default: realistic)+ --budget-cadence <spec> Cadence override passed through to loop-cost+ --budget-conservative Use the slower cadence in a range (loop-cost flag)--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@@ -128,6 +163,16 @@ async function main() {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) {diff --git a/tools/loop-context/test/budget-resolver.test.mjs b/tools/loop-context/test/budget-resolver.test.mjsnew file mode 100644index 0000000..7e8e583--- /dev/null+++ b/tools/loop-context/test/budget-resolver.test.mjs@@ -0,0 +1,38 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import {+ resolveCostCli,+ resolveTokenBudgetFromPattern,+} from '../dist/budget-resolver.js';++test('resolveCostCli finds the monorepo sibling loop-cost CLI', async () => {+ const cli = await resolveCostCli();+ assert.ok(cli, 'expected a resolved CLI path');+ assert.match(cli, /loop-cost[\\/]dist[\\/]cli\.js$/);+});++test('resolveTokenBudgetFromPattern returns the realistic per-run estimate by default', async () => {+ const tokens = await resolveTokenBudgetFromPattern({ pattern: 'ci-sweeper', level: 'L2' });+ assert.equal(typeof tokens, 'number');+ assert.ok(tokens > 0);+});++test('resolveTokenBudgetFromPattern honors --budget-scenario', async () => {+ const realistic = await resolveTokenBudgetFromPattern({ pattern: 'ci-sweeper', level: 'L2', scenario: 'realistic' });+ const action = await resolveTokenBudgetFromPattern({ pattern: 'ci-sweeper', level: 'L2', scenario: 'action' });+ assert.ok(action >= realistic, 'worst-case action scenario should be at least the realistic blend');+});++test('resolveTokenBudgetFromPattern rejects an unknown pattern with loop-cost\'s own message', async () => {+ await assert.rejects(+ () => resolveTokenBudgetFromPattern({ pattern: 'not-a-pattern' }),+ /Unknown pattern: not-a-pattern/,+ );+});++test('resolveTokenBudgetFromPattern rejects an invalid scenario before spawning loop-cost', async () => {+ await assert.rejects(+ () => resolveTokenBudgetFromPattern({ pattern: 'ci-sweeper', scenario: 'garbage' }),+ /Invalid --budget-scenario/,+ );+});diff --git a/tools/loop-context/test/cli.test.mjs b/tools/loop-context/test/cli.test.mjsindex ce5d830..5f048df 100644--- a/tools/loop-context/test/cli.test.mjs+++ b/tools/loop-context/test/cli.test.mjs@@ -51,4 +51,35 @@ test('cli rejects missing numeric flag values', () => {const r = runCli(['--check', '--stagnation']);assert.equal(r.status, 1);assert.match(r.stderr, /--stagnation requires a positive integer value/);-});\ No newline at end of file+});++const cheapLedger = JSON.stringify({+ goal: 'x',+ attempts: [{ iteration: 1, action: 'a', outcome: 'success', tokensUsed: 100 }],+});++test('cli resolves --token-budget from --budget-from-pattern', () => {+ const r = runCli(+ ['--check', '--budget-from-pattern', 'ci-sweeper', '--budget-level', 'L2', '--json'],+ cheapLedger,+ );+ assert.equal(r.status, 0);+ const decision = JSON.parse(r.stdout);+ assert.equal(decision.escalate, false);+});++test('cli --token-budget wins over --budget-from-pattern when both are given', () => {+ const r = runCli(+ ['--check', '--budget-from-pattern', 'ci-sweeper', '--token-budget', '50', '--json'],+ cheapLedger,+ );+ assert.equal(r.status, 2);+ const decision = JSON.parse(r.stdout);+ assert.equal(decision.trigger, 'token-budget');+});++test('cli --budget-from-pattern surfaces loop-cost\'s unknown-pattern error', () => {+ const r = runCli(['--check', '--budget-from-pattern', 'not-a-pattern'], cheapLedger);+ assert.equal(r.status, 1);+ assert.match(r.stderr, /Unknown pattern: not-a-pattern/);+});diff --git a/tools/loop-cost/README.md b/tools/loop-cost/README.mdindex 4c4aa28..2fa66d0 100644--- a/tools/loop-cost/README.md+++ b/tools/loop-cost/README.md@@ -67,16 +67,16 @@ and expensive to run unattended.## Feed the circuit breaker-`--json` output resolves a realistic per-run token cap for-[`loop-context`](../loop-context)'s breaker, so `--token-budget` reflects real-pattern cost instead of a hand-typed guess (the `loop-guard` skill wires this):+[`loop-context`](../loop-context)'s breaker can resolve `--token-budget` directly+from a pattern's realistic per-run estimate instead of a hand-typed guess:```bash-BUDGET=$(npx @cobusgreyling/loop-cost --pattern ci-sweeper --level L2 --json \- | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>process.stdout.write(String(JSON.parse(d).scenarios.realistic.tokensPerRun)))')-npx @cobusgreyling/loop-context --check --ledger loop-ledger.json --token-budget "$BUDGET"+npx @cobusgreyling/loop-context --check --ledger loop-ledger.json \+ --budget-from-pattern ci-sweeper --budget-level L2```-The tools stay independent — no runtime dependency, just shell wiring.+`loop-context` shells out to this CLI's built output to do it — the packages stay+independent at the source level, no shared runtime state. An explicit+`--token-budget` on the `loop-context` call always overrides the derived value.See [docs/operating-loops.md](../../docs/operating-loops.md).\ No newline at end of file