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): add tool + release wiring (closes #125 path)
Cobus Greyling61aa376e030e
diff --git a/.github/workflows/release-loop-context.yml b/.github/workflows/release-loop-context.ymlnew file mode 100644index 0000000..a259427--- /dev/null+++ b/.github/workflows/release-loop-context.yml@@ -0,0 +1,47 @@+name: Release loop-context++on:+ push:+ tags:+ - 'loop-context-v*'+ workflow_dispatch:+ inputs:+ tag:+ description: 'Tag to publish (e.g. loop-context-v1.0.0)'+ required: true+ type: string++permissions:+ contents: read+ id-token: write++jobs:+ test-and-publish:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v7+ with:+ ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', github.event.inputs.tag) || github.ref }}++ - uses: actions/setup-node@v6+ with:+ node-version: '22'+ registry-url: 'https://registry.npmjs.org'+ cache: 'npm'+ cache-dependency-path: tools/loop-context/package-lock.json++ - name: Ensure npm supports trusted publishing (OIDC)+ run: npm install -g npm@latest++ - name: Install, build, test+ working-directory: tools/loop-context+ run: |+ npm ci+ npm run build+ npm test++ - name: Publish to npm+ working-directory: tools/loop-context+ run: npm publish --access public --provenance+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\ No newline at end of filediff --git a/.gitignore b/.gitignoreindex b1b965b..ff1a8f7 100644--- a/.gitignore+++ b/.gitignore@@ -31,6 +31,7 @@ build/!tools/loop-cost/dist/!tools/loop-init/dist/!tools/mcp-server/dist/+!tools/loop-context/dist/!tools/goal-audit/dist/*.egg-info/diff --git a/README.md b/README.mdindex 28d64a3..aa0bdbb 100644--- a/README.md+++ b/README.md@@ -88,6 +88,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` || [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` || [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` |+| [loop-context](tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` || [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `node tools/mcp-server/dist/index.js` (repo v1; npm pending) || [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) || [Stories](stories/) | Real wins and honest failures |diff --git a/docs/RELEASE.md b/docs/RELEASE.mdindex a09a10d..2ac578c 100644--- a/docs/RELEASE.md+++ b/docs/RELEASE.md@@ -1,6 +1,6 @@# Release playbook — npm packages-This repo ships four public npm packages from `tools/`:+This repo ships five public npm packages from `tools/`:| Package | Directory | Release tag ||---------|-----------|-------------|@@ -8,6 +8,7 @@ This repo ships four public npm packages from `tools/`:| `@cobusgreyling/loop-init` | `tools/loop-init` | `loop-init-v*` || `@cobusgreyling/loop-cost` | `tools/loop-cost` | `loop-cost-v*` || `@cobusgreyling/loop-sync` | `tools/loop-sync` | `loop-sync-v*` |+| `@cobusgreyling/loop-context` | `tools/loop-context` | `loop-context-v*` |## One-time setup (trusted publishing — recommended)@@ -19,6 +20,7 @@ Link npm to GitHub, then for **each package** on [npmjs.com](https://www.npmjs.c| `@cobusgreyling/loop-init` | `cobusgreyling/loop-engineering` | `release-loop-init.yml` || `@cobusgreyling/loop-cost` | `cobusgreyling/loop-engineering` | `release-loop-cost.yml` || `@cobusgreyling/loop-sync` | `cobusgreyling/loop-engineering` | `release-loop-sync.yml` |+| `@cobusgreyling/loop-context` | `cobusgreyling/loop-engineering` | `release-loop-context.yml` |Names must match **exactly** (case-sensitive). No `NPM_TOKEN` secret is required when trusted publishing is configured.@@ -52,9 +54,13 @@ git push origin loop-cost-v1.0.0# loop-sync (drift detection between STATE.md and LOOP.md)git tag loop-sync-v1.0.0git push origin loop-sync-v1.0.0++# loop-context (stateful memory manager + circuit breaker)+git tag loop-context-v1.0.0+git push origin loop-context-v1.0.0```-Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`.+Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`, `.github/workflows/release-loop-context.yml`.## Verify after publish@@ -63,6 +69,7 @@ npx @cobusgreyling/loop-audit --helpnpx @cobusgreyling/loop-init --helpnpx @cobusgreyling/loop-cost --helpnpx @cobusgreyling/loop-sync --help+npx @cobusgreyling/loop-context --helpmkdir /tmp/loop-init-test && cd /tmp/loop-init-testnpx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-rundiff --git a/package.json b/package.jsonindex 9fd7ccc..e66c7c1 100644--- a/package.json+++ b/package.json@@ -9,9 +9,10 @@"test:loop-init": "cd tools/loop-init && npm test","test:loop-cost": "cd tools/loop-cost && npm test","test:loop-sync": "cd tools/loop-sync && npm test",+ "test:loop-context": "cd tools/loop-context && npm test","test:mcp-server": "cd tools/mcp-server && npm test",- "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:loop-sync && npm run test:mcp-server",- "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build && cd ../mcp-server && npm run build"+ "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:loop-sync && npm run test:loop-context && npm run test:mcp-server",+ "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build && cd ../loop-context && npm run build && cd ../mcp-server && npm run build"},"devDependencies": {"ajv": "^8.17.1",diff --git a/scripts/ci-validate-gates.sh b/scripts/ci-validate-gates.shindex 70214cc..1255542 100755--- a/scripts/ci-validate-gates.sh+++ b/scripts/ci-validate-gates.sh@@ -39,6 +39,11 @@ cd ../loop-syncnpm cinpm test+echo "Building and testing loop-context…"+cd ../loop-context+npm ci+npm test+echo "Building and testing mcp-server…"cd ../mcp-servernpm cidiff --git a/tools/loop-context/README.md b/tools/loop-context/README.mdnew file mode 100644index 0000000..d5e8c14--- /dev/null+++ b/tools/loop-context/README.md@@ -0,0 +1,130 @@+# loop-context++**Stateful memory manager for agent loops.** Keeps the context window clean and stops runaway loops before they burn tokens.++Long-running agent loops fail in two classic ways the [loop-engineering docs](../../docs/) warn about:++- **Context overflow & rot** — conversation history and error logs grow until the model loses the original goal or drowns in stale stack traces.+- **Stagnant / no-progress loops** — the agent retries the same failing action forever, quietly blowing the token budget.++`loop-context` sits between the agent and its durable memory (`STATE.md`, run logs) and, before each iteration, does three things:++1. **Summarize** what has been tried and what failed.+2. **Prune** verbose stack traces, collapse repeated errors, and drop stale attempts outside a recent window.+3. **Inject** only the essentials into the next prompt.++A **circuit breaker** watches iteration count, token spend, stagnation (same error N× in a row), and no-progress (too many consecutive failures) — and escalates to a human instead of looping in vain.++Everything is **deterministic and dependency-free**: no LLM call is needed to summarize or prune, so it is cheap enough to run on every iteration.++## Install / run++```bash+npx @cobusgreyling/loop-context --help+# or from this repo:+cd tools/loop-context && npm install && npm test+```++## The ledger++The tool reads a **run ledger** — a JSON record of the loop's goal and its attempts:++```json+{+ "goal": "Get the failing migration test to pass",+ "attempts": [+ { "iteration": 1, "action": "run migration", "outcome": "failure",+ "error": "Error: connect ECONNREFUSED 127.0.0.1:5432", "tokensUsed": 1500 },+ { "iteration": 2, "action": "run migration again", "outcome": "failure",+ "error": "Error: connect ECONNREFUSED 127.0.0.1:5432", "tokensUsed": 1400 }+ ]+}+```++`outcome` is `success | failure | noop`. `error` and `tokensUsed` are optional.++## Usage++```bash+# Circuit breaker — exit 0 = continue, 2 = escalate (wire into a loop's control flow)+loop-context --check --ledger run.json++# Compact context block for the next prompt+loop-context --inject --ledger run.json++# Factual rollup of the run+loop-context --summary --ledger run.json --json++# Pruned ledger (recent window, trimmed traces, collapsed repeats)+loop-context --prune --ledger run.json++# Pipe on stdin+cat run.json | loop-context --check+```++### Options++| Flag | Default | Meaning |+|------|---------|---------|+| `--max-iterations <n>` | 10 | Hard iteration cap |+| `--stagnation <n>` | 3 | Escalate when the same error repeats N× in a row |+| `--no-progress <n>` | 5 | Escalate after N consecutive failures |+| `--token-budget <n>` | none | Escalate when cumulative tokens reach the cap |+| `--window <n>` | 5 | Attempts kept when pruning |+| `--max-trace-lines <n>` | 8 | Stack-trace lines kept when pruning |++Exit codes: `0` continue · `2` escalate · `1` error.++## Populating the ledger++Your loop control script appends one object per iteration to `run.json` (or pipes the same shape on stdin):++```bash+# after each agent iteration — append attempt, then gate the next one+node -e "+const fs = require('fs');+const ledger = JSON.parse(fs.readFileSync('run.json', 'utf8'));+ledger.attempts.push({+ iteration: ledger.attempts.length + 1,+ action: 'run migration tests',+ outcome: 'failure',+ error: process.argv[1],+ tokensUsed: Number(process.argv[2] || 0),+});+fs.writeFileSync('run.json', JSON.stringify(ledger, null, 2));+" \"\$ERROR_MSG\" \"\$TOKENS\"+loop-context --check --ledger run.json || { loop-context --inject --ledger run.json; exit 2; }+```++Initialize once at loop start: `{ \"goal\": \"Get CI green on main\", \"attempts\": [] }`.++## In a loop++```bash+# inside your loop's control script, before each iteration:+if ! loop-context --check --ledger run.json; then+ loop-context --inject --ledger run.json > escalation.md # hand a clean summary to the human+ exit 0 # stop instead of retrying+fi+```++## Library API++```ts+import {+ checkCircuitBreaker,+ pruneLedger,+ summarizeAttempts,+ buildContextInjection,+} from '@cobusgreyling/loop-context';++const decision = checkCircuitBreaker(ledger);+if (decision.escalate) escalateToHuman(decision.reason);+else runNextIteration(buildContextInjection(ledger));+```++## Where it fits++This is the **Memory / State** primitive of loop engineering made dynamic: `STATE.md` stores state statically; `loop-context` manages it across iterations. See [docs/primitives.md](../../docs/primitives.md) and the [operating & safety](../../docs/) guides.++MIT · part of [loop-engineering](https://github.com/cobusgreyling/loop-engineering) by Cobus Greyling.diff --git a/tools/loop-context/dist/cli.d.ts b/tools/loop-context/dist/cli.d.tsnew file mode 100644index 0000000..b798801--- /dev/null+++ b/tools/loop-context/dist/cli.d.ts@@ -0,0 +1,2 @@+#!/usr/bin/env node+export {};diff --git a/tools/loop-context/dist/cli.js b/tools/loop-context/dist/cli.jsnew file mode 100644index 0000000..e04cf63--- /dev/null+++ b/tools/loop-context/dist/cli.js@@ -0,0 +1,163 @@+#!/usr/bin/env node+import { readFile } from 'node:fs/promises';+import { buildContextInjection, checkCircuitBreaker, pruneLedger, summarizeAttempts, DEFAULT_BREAKER, DEFAULT_PRUNE, } from './context-manager.js';+function parseArgs(argv) {+ const breaker = { ...DEFAULT_BREAKER };+ const prune = { ...DEFAULT_PRUNE };+ let op = 'status';+ let ledger;+ let json = false;+ for (let i = 0; i < argv.length; i++) {+ const a = argv[i];+ if (a === '--help' || a === '-h')+ return { help: true, op, json, breaker, prune };+ 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 = Number(argv[++i]);+ else if (a === '--stagnation')+ breaker.stagnationThreshold = Number(argv[++i]);+ else if (a === '--no-progress')+ breaker.noProgressThreshold = Number(argv[++i]);+ else if (a === '--token-budget')+ breaker.tokenBudget = Number(argv[++i]);+ else if (a === '--window')+ prune.window = Number(argv[++i]);+ else if (a === '--max-trace-lines')+ prune.maxTraceLines = Number(argv[++i]);+ }+ return { help: false, op, ledger, json, breaker, prune };+}+async function readLedger(pathArg) {+ 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);+ if (typeof parsed.goal !== 'string' || !Array.isArray(parsed.attempts)) {+ throw new Error('Invalid ledger: expected { goal: string, attempts: Attempt[] }.');+ }+ return parsed;+}+function readStdin() {+ 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++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)+ --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;+ }+ const ledger = await readLedger(args.ledger);+ switch (args.op) {+ case 'check': {+ const decision = checkCircuitBreaker(ledger, args.breaker);+ 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;+ }+ }+}+function formatSummary(s) {+ const lines = [];+ 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) => {+ const msg = err instanceof Error ? err.message : String(err);+ console.error('loop-context failed:', msg);+ process.exit(1);+});diff --git a/tools/loop-context/dist/context-manager.d.ts b/tools/loop-context/dist/context-manager.d.tsnew file mode 100644index 0000000..19f5e5a--- /dev/null+++ b/tools/loop-context/dist/context-manager.d.ts@@ -0,0 +1,119 @@+/**+ * Stateful Memory Manager — Context Manager, Pruner, and Circuit Breaker.+ *+ * Sits between an agent loop and its durable memory (STATE.md, run logs).+ * Before each new iteration it can: summarize what has been tried, prune stale+ * or verbose context (long stack traces, repeated errors), and inject only the+ * essentials into the next prompt — keeping the context window clean and focused.+ *+ * The circuit breaker detects the two classic loop failures the docs warn about:+ * - stagnant runs (retrying the same error N times)+ * - no-progress loops (repeated failures with no success)+ * and, together with iteration and token caps, escalates to a human instead of+ * burning tokens in a hopeless loop.+ *+ * All logic here is deterministic and dependency-free — no LLM call is required+ * to summarize or prune, so it is cheap to run on every iteration and easy to test.+ */+export type Outcome = 'success' | 'failure' | 'noop';+export interface Attempt {+ /** 1-based iteration number within the run. */+ iteration: number;+ /** ISO timestamp of the attempt (optional). */+ timestamp?: string;+ /** What the agent tried this iteration (a short description). */+ action: string;+ /** Result of the attempt. */+ outcome: Outcome;+ /** Raw error message or stack trace, if the attempt failed. */+ error?: string;+ /** Tokens spent on this iteration, if tracked. */+ tokensUsed?: number;+ /** Set by the pruner when consecutive identical failures are collapsed. */+ repeated?: number;+}+export interface Ledger {+ /** The loop's original goal — the anchor the agent must not lose. */+ goal: string;+ /** ISO timestamp when the run started (optional). */+ startedAt?: string;+ /** Ordered list of attempts, oldest first. */+ attempts: Attempt[];+}+export interface CircuitBreakerConfig {+ /** Hard cap on total iterations before escalating. */+ maxIterations: number;+ /** Escalate when the same error signature repeats this many times in a row. */+ stagnationThreshold: number;+ /** Escalate after this many consecutive failures with no success in between. */+ noProgressThreshold: number;+ /** Optional hard cap on cumulative tokens across the run. */+ tokenBudget?: number;+}+export interface PruneConfig {+ /** Max lines to keep from any single stack trace. */+ maxTraceLines: number;+ /** Number of most-recent attempts to retain in the pruned ledger. */+ window: number;+}+export declare const DEFAULT_BREAKER: CircuitBreakerConfig;+export declare const DEFAULT_PRUNE: PruneConfig;+/**+ * Reduce a raw error / stack trace to a stable signature so that "the same+ * error" can be recognized across iterations even when volatile details+ * (line numbers, addresses, timestamps, ports, temp paths) differ.+ */+export declare function errorSignature(error: string): string;+export type BreakerTrigger = 'ok' | 'stagnation' | 'no-progress' | 'token-budget' | 'max-iterations';+export interface BreakerDecision {+ /** Whether the loop is cleared to run another iteration. */+ shouldContinue: boolean;+ /** Whether the loop must hand off to a human. */+ escalate: boolean;+ /** Which condition fired (or 'ok'). */+ trigger: BreakerTrigger;+ /** Human-readable explanation. */+ reason: string;+ iterations: number;+ tokensUsed: number;+}+/**+ * Decide whether the loop may continue. Checks the most specific and cheapest-+ * to-fix conditions first (stagnation, then no-progress) before the absolute+ * caps (token budget, iteration count), so the reported reason is the most+ * actionable one when several conditions hold.+ */+export declare function checkCircuitBreaker(ledger: Ledger, config?: CircuitBreakerConfig): BreakerDecision;+/** Truncate a stack trace to its most useful head, noting how much was dropped. */+export declare function pruneStackTrace(trace: string, maxLines: number): string;+/**+ * Produce a lean ledger for injection: keep only the most-recent `window`+ * attempts, prune verbose traces, and collapse consecutive identical failures+ * into a single entry with a repeat count. The full ledger is untouched — this+ * returns a new object.+ */+export declare function pruneLedger(ledger: Ledger, config?: PruneConfig): Ledger;+export interface ErrorGroup {+ signature: string;+ count: number;+ sample: string;+}+export interface AttemptSummary {+ totalAttempts: number;+ successes: number;+ failures: number;+ noops: number;+ tokensUsed: number;+ /** Distinct error signatures, most frequent first. */+ distinctErrors: ErrorGroup[];+ /** Unique actions the agent has already tried. */+ actionsTried: string[];+}+/** Deterministic factual rollup of the whole run — no LLM required. */+export declare function summarizeAttempts(ledger: Ledger): AttemptSummary;+/**+ * Build the compact context block to prepend to the next prompt. Contains only+ * what the agent needs to make progress: the goal, what has already been tried+ * (so it does not repeat itself), the last pruned error, and the breaker status.+ */+export declare function buildContextInjection(ledger: Ledger, breaker?: CircuitBreakerConfig, prune?: PruneConfig): string;diff --git a/tools/loop-context/dist/context-manager.js b/tools/loop-context/dist/context-manager.jsnew file mode 100644index 0000000..a229f70--- /dev/null+++ b/tools/loop-context/dist/context-manager.js@@ -0,0 +1,248 @@+/**+ * Stateful Memory Manager — Context Manager, Pruner, and Circuit Breaker.+ *+ * Sits between an agent loop and its durable memory (STATE.md, run logs).+ * Before each new iteration it can: summarize what has been tried, prune stale+ * or verbose context (long stack traces, repeated errors), and inject only the+ * essentials into the next prompt — keeping the context window clean and focused.+ *+ * The circuit breaker detects the two classic loop failures the docs warn about:+ * - stagnant runs (retrying the same error N times)+ * - no-progress loops (repeated failures with no success)+ * and, together with iteration and token caps, escalates to a human instead of+ * burning tokens in a hopeless loop.+ *+ * All logic here is deterministic and dependency-free — no LLM call is required+ * to summarize or prune, so it is cheap to run on every iteration and easy to test.+ */+export const DEFAULT_BREAKER = {+ maxIterations: 10,+ stagnationThreshold: 3,+ noProgressThreshold: 5,+};+export const DEFAULT_PRUNE = {+ maxTraceLines: 8,+ window: 5,+};+// ── Error normalization ────────────────────────────────────────────+/**+ * Reduce a raw error / stack trace to a stable signature so that "the same+ * error" can be recognized across iterations even when volatile details+ * (line numbers, addresses, timestamps, ports, temp paths) differ.+ */+export function errorSignature(error) {+ const firstLine = error.split('\n').find((l) => l.trim().length > 0) ?? '';+ return firstLine+ .trim()+ .replace(/\b\d{4}-\d{2}-\d{2}[T ][\d:.]+Z?\b/g, '<ts>') // ISO timestamps+ .replace(/0x[0-9a-fA-F]+/g, '<addr>') // hex addresses+ .replace(/[A-Za-z]:[\\/][^\s:]+|(?:[\\/][^\s:/\\]+)+/g, (p) => {+ const parts = p.split(/[\\/]/);+ return parts[parts.length - 1] || p; // collapse paths to basename+ })+ .replace(/:\d+(:\d+)?/g, '') // line:col suffixes+ .replace(/\b\d+\b/g, '#') // any remaining numbers (ports, ids, counts)+ .replace(/\s+/g, ' ')+ .trim();+}+function totalTokens(ledger) {+ return ledger.attempts.reduce((sum, a) => sum + (a.tokensUsed ?? 0), 0);+}+/** Length of the trailing run of failures (since the last non-failure). */+function trailingFailureRun(attempts) {+ const run = [];+ for (let i = attempts.length - 1; i >= 0; i--) {+ if (attempts[i].outcome !== 'failure')+ break;+ run.unshift(attempts[i]);+ }+ return run;+}+/**+ * Decide whether the loop may continue. Checks the most specific and cheapest-+ * to-fix conditions first (stagnation, then no-progress) before the absolute+ * caps (token budget, iteration count), so the reported reason is the most+ * actionable one when several conditions hold.+ */+export function checkCircuitBreaker(ledger, config = DEFAULT_BREAKER) {+ const iterations = ledger.attempts.length;+ const tokensUsed = totalTokens(ledger);+ const base = { iterations, tokensUsed };+ const failRun = trailingFailureRun(ledger.attempts);+ // Stagnation: the same error signature repeated at the tail.+ if (failRun.length >= config.stagnationThreshold) {+ const lastSig = errorSignature(failRun[failRun.length - 1].error ?? '');+ let same = 0;+ for (let i = failRun.length - 1; i >= 0; i--) {+ if (errorSignature(failRun[i].error ?? '') === lastSig)+ same++;+ else+ break;+ }+ if (same >= config.stagnationThreshold) {+ return {+ ...base,+ shouldContinue: false,+ escalate: true,+ trigger: 'stagnation',+ reason: `Same error repeated ${same}× in a row (threshold ${config.stagnationThreshold}): "${lastSig}". Escalating instead of retrying.`,+ };+ }+ }+ // No-progress: many consecutive failures without a success.+ if (failRun.length >= config.noProgressThreshold) {+ return {+ ...base,+ shouldContinue: false,+ escalate: true,+ trigger: 'no-progress',+ reason: `${failRun.length} consecutive failures with no progress (threshold ${config.noProgressThreshold}). Escalating.`,+ };+ }+ // Token budget: absolute spend cap.+ if (config.tokenBudget !== undefined && tokensUsed >= config.tokenBudget) {+ return {+ ...base,+ shouldContinue: false,+ escalate: true,+ trigger: 'token-budget',+ reason: `Token budget reached (${tokensUsed} ≥ ${config.tokenBudget}). Escalating to avoid cost blowup.`,+ };+ }+ // Iteration cap: absolute count.+ if (iterations >= config.maxIterations) {+ return {+ ...base,+ shouldContinue: false,+ escalate: true,+ trigger: 'max-iterations',+ reason: `Iteration cap reached (${iterations} ≥ ${config.maxIterations}). Escalating.`,+ };+ }+ return {+ ...base,+ shouldContinue: true,+ escalate: false,+ trigger: 'ok',+ reason: 'Within limits — cleared to continue.',+ };+}+// ── Pruning ────────────────────────────────────────────────────────+/** Truncate a stack trace to its most useful head, noting how much was dropped. */+export function pruneStackTrace(trace, maxLines) {+ const lines = trace.split('\n');+ if (lines.length <= maxLines)+ return trace.trim();+ const kept = lines.slice(0, maxLines).join('\n').trimEnd();+ const omitted = lines.length - maxLines;+ return `${kept}\n … (${omitted} more line${omitted === 1 ? '' : 's'} pruned)`;+}+/**+ * Produce a lean ledger for injection: keep only the most-recent `window`+ * attempts, prune verbose traces, and collapse consecutive identical failures+ * into a single entry with a repeat count. The full ledger is untouched — this+ * returns a new object.+ */+export function pruneLedger(ledger, config = DEFAULT_PRUNE) {+ const recent = ledger.attempts.slice(-config.window);+ const collapsed = [];+ for (const attempt of recent) {+ const pruned = {+ ...attempt,+ ...(attempt.error !== undefined+ ? { error: pruneStackTrace(attempt.error, config.maxTraceLines) }+ : {}),+ };+ const prev = collapsed[collapsed.length - 1];+ const sameFailure = prev !== undefined &&+ prev.outcome === 'failure' &&+ pruned.outcome === 'failure' &&+ errorSignature(prev.error ?? '') === errorSignature(pruned.error ?? '');+ if (sameFailure) {+ prev.repeated = (prev.repeated ?? 1) + 1;+ prev.iteration = pruned.iteration; // advance to the latest iteration+ }+ else {+ collapsed.push(pruned);+ }+ }+ return { goal: ledger.goal, startedAt: ledger.startedAt, attempts: collapsed };+}+/** Deterministic factual rollup of the whole run — no LLM required. */+export function summarizeAttempts(ledger) {+ const groups = new Map();+ const actions = new Set();+ let successes = 0;+ let failures = 0;+ let noops = 0;+ for (const a of ledger.attempts) {+ actions.add(a.action);+ if (a.outcome === 'success')+ successes++;+ else if (a.outcome === 'noop')+ noops++;+ else {+ failures++;+ if (a.error) {+ const sig = errorSignature(a.error);+ const existing = groups.get(sig);+ if (existing)+ existing.count++;+ else+ groups.set(sig, { signature: sig, count: 1, sample: a.error.split('\n')[0].trim() });+ }+ }+ }+ return {+ totalAttempts: ledger.attempts.length,+ successes,+ failures,+ noops,+ tokensUsed: totalTokens(ledger),+ distinctErrors: [...groups.values()].sort((a, b) => b.count - a.count),+ actionsTried: [...actions],+ };+}+// ── Injection ──────────────────────────────────────────────────────+/**+ * Build the compact context block to prepend to the next prompt. Contains only+ * what the agent needs to make progress: the goal, what has already been tried+ * (so it does not repeat itself), the last pruned error, and the breaker status.+ */+export function buildContextInjection(ledger, breaker = DEFAULT_BREAKER, prune = DEFAULT_PRUNE) {+ const summary = summarizeAttempts(ledger);+ const decision = checkCircuitBreaker(ledger, breaker);+ const pruned = pruneLedger(ledger, prune);+ const lines = [];+ lines.push('## Loop Context (managed)');+ lines.push('');+ lines.push(`**Goal:** ${ledger.goal}`);+ lines.push(`**Progress:** iteration ${summary.totalAttempts} · ${summary.successes} ok · ${summary.failures} failed` ++ (summary.tokensUsed ? ` · ${summary.tokensUsed} tokens` : ''));+ lines.push('');+ if (summary.actionsTried.length > 0) {+ lines.push('**Already tried (do NOT repeat):**');+ for (const action of summary.actionsTried)+ lines.push(`- ${action}`);+ lines.push('');+ }+ if (summary.distinctErrors.length > 0) {+ lines.push('**Failure patterns:**');+ for (const g of summary.distinctErrors) {+ lines.push(`- (${g.count}×) ${g.sample}`);+ }+ lines.push('');+ }+ const lastFail = [...pruned.attempts].reverse().find((a) => a.outcome === 'failure');+ if (lastFail?.error) {+ lines.push('**Most recent error (pruned):**');+ lines.push('```');+ lines.push(lastFail.error);+ lines.push('```');+ lines.push('');+ }+ lines.push(decision.escalate+ ? `> STOP — circuit breaker tripped (${decision.trigger}). ${decision.reason}`+ : `> Circuit breaker: OK (${decision.iterations}/${breaker.maxIterations} iterations used).`);+ return lines.join('\n');+}diff --git a/tools/loop-context/package-lock.json b/tools/loop-context/package-lock.jsonnew file mode 100644index 0000000..b6db3e1--- /dev/null+++ b/tools/loop-context/package-lock.json@@ -0,0 +1,54 @@+{+ "name": "@cobusgreyling/loop-context",+ "version": "1.0.0",+ "lockfileVersion": 3,+ "requires": true,+ "packages": {+ "": {+ "name": "@cobusgreyling/loop-context",+ "version": "1.0.0",+ "license": "MIT",+ "bin": {+ "loop-context": "dist/cli.js"+ },+ "devDependencies": {+ "@types/node": "^20.0.0",+ "typescript": "^5.0.0"+ },+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@types/node": {+ "version": "20.19.43",+ "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",+ "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "undici-types": "~6.21.0"+ }+ },+ "node_modules/typescript": {+ "version": "5.9.3",+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",+ "dev": true,+ "license": "Apache-2.0",+ "bin": {+ "tsc": "bin/tsc",+ "tsserver": "bin/tsserver"+ },+ "engines": {+ "node": ">=14.17"+ }+ },+ "node_modules/undici-types": {+ "version": "6.21.0",+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",+ "dev": true,+ "license": "MIT"+ }+ }+}diff --git a/tools/loop-context/package.json b/tools/loop-context/package.jsonnew file mode 100644index 0000000..03c9f73--- /dev/null+++ b/tools/loop-context/package.json@@ -0,0 +1,55 @@+{+ "name": "@cobusgreyling/loop-context",+ "version": "1.0.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",+ "exports": {+ ".": "./dist/context-manager.js"+ },+ "bin": {+ "loop-context": "dist/cli.js"+ },+ "files": [+ "dist",+ "README.md"+ ],+ "scripts": {+ "build": "tsc && chmod +x dist/cli.js",+ "test": "npm run build && node --test test/context-manager.test.mjs",+ "prepublishOnly": "npm test",+ "start": "node dist/cli.js"+ },+ "engines": {+ "node": ">=18"+ },+ "keywords": [+ "loop-engineering",+ "ai-agents",+ "coding-agents",+ "context-management",+ "circuit-breaker",+ "memory",+ "claude-code",+ "grok",+ "devtools"+ ],+ "author": "Cobus Greyling",+ "license": "MIT",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/cobusgreyling/loop-engineering.git",+ "directory": "tools/loop-context"+ },+ "homepage": "https://cobusgreyling.github.io/loop-engineering/",+ "bugs": {+ "url": "https://github.com/cobusgreyling/loop-engineering/issues"+ },+ "publishConfig": {+ "access": "public"+ },+ "devDependencies": {+ "@types/node": "^20.0.0",+ "typescript": "^5.0.0"+ }+}diff --git a/tools/loop-context/src/cli.ts b/tools/loop-context/src/cli.tsnew file mode 100644index 0000000..d9dbc87--- /dev/null+++ b/tools/loop-context/src/cli.ts@@ -0,0 +1,174 @@+#!/usr/bin/env node+import { readFile } from 'node:fs/promises';+import {+ buildContextInjection,+ checkCircuitBreaker,+ pruneLedger,+ summarizeAttempts,+ DEFAULT_BREAKER,+ DEFAULT_PRUNE,+ type Ledger,+ type CircuitBreakerConfig,+ type PruneConfig,+} from './context-manager.js';++type Op = 'check' | 'prune' | 'inject' | 'summary' | 'status';++interface Args {+ help: boolean;+ op: Op;+ ledger?: string;+ json: boolean;+ breaker: CircuitBreakerConfig;+ prune: PruneConfig;+}++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;++ for (let i = 0; i < argv.length; i++) {+ const a = argv[i];+ if (a === '--help' || a === '-h') return { help: true, op, json, breaker, prune };+ 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 = Number(argv[++i]);+ else if (a === '--stagnation') breaker.stagnationThreshold = Number(argv[++i]);+ else if (a === '--no-progress') breaker.noProgressThreshold = Number(argv[++i]);+ else if (a === '--token-budget') breaker.tokenBudget = Number(argv[++i]);+ else if (a === '--window') prune.window = Number(argv[++i]);+ else if (a === '--max-trace-lines') prune.maxTraceLines = Number(argv[++i]);+ }++ return { help: false, op, ledger, json, breaker, prune };+}++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++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)+ --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;+ }++ const ledger = await readLedger(args.ledger);++ switch (args.op) {+ case 'check': {+ const decision = checkCircuitBreaker(ledger, args.breaker);+ 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;+ }+ }+}++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);+});diff --git a/tools/loop-context/src/context-manager.ts b/tools/loop-context/src/context-manager.tsnew file mode 100644index 0000000..376ac6e--- /dev/null+++ b/tools/loop-context/src/context-manager.ts@@ -0,0 +1,369 @@+/**+ * Stateful Memory Manager — Context Manager, Pruner, and Circuit Breaker.+ *+ * Sits between an agent loop and its durable memory (STATE.md, run logs).+ * Before each new iteration it can: summarize what has been tried, prune stale+ * or verbose context (long stack traces, repeated errors), and inject only the+ * essentials into the next prompt — keeping the context window clean and focused.+ *+ * The circuit breaker detects the two classic loop failures the docs warn about:+ * - stagnant runs (retrying the same error N times)+ * - no-progress loops (repeated failures with no success)+ * and, together with iteration and token caps, escalates to a human instead of+ * burning tokens in a hopeless loop.+ *+ * All logic here is deterministic and dependency-free — no LLM call is required+ * to summarize or prune, so it is cheap to run on every iteration and easy to test.+ */++export type Outcome = 'success' | 'failure' | 'noop';++export interface Attempt {+ /** 1-based iteration number within the run. */+ iteration: number;+ /** ISO timestamp of the attempt (optional). */+ timestamp?: string;+ /** What the agent tried this iteration (a short description). */+ action: string;+ /** Result of the attempt. */+ outcome: Outcome;+ /** Raw error message or stack trace, if the attempt failed. */+ error?: string;+ /** Tokens spent on this iteration, if tracked. */+ tokensUsed?: number;+ /** Set by the pruner when consecutive identical failures are collapsed. */+ repeated?: number;+}++export interface Ledger {+ /** The loop's original goal — the anchor the agent must not lose. */+ goal: string;+ /** ISO timestamp when the run started (optional). */+ startedAt?: string;+ /** Ordered list of attempts, oldest first. */+ attempts: Attempt[];+}++export interface CircuitBreakerConfig {+ /** Hard cap on total iterations before escalating. */+ maxIterations: number;+ /** Escalate when the same error signature repeats this many times in a row. */+ stagnationThreshold: number;+ /** Escalate after this many consecutive failures with no success in between. */+ noProgressThreshold: number;+ /** Optional hard cap on cumulative tokens across the run. */+ tokenBudget?: number;+}++export interface PruneConfig {+ /** Max lines to keep from any single stack trace. */+ maxTraceLines: number;+ /** Number of most-recent attempts to retain in the pruned ledger. */+ window: number;+}++export const DEFAULT_BREAKER: CircuitBreakerConfig = {+ maxIterations: 10,+ stagnationThreshold: 3,+ noProgressThreshold: 5,+};++export const DEFAULT_PRUNE: PruneConfig = {+ maxTraceLines: 8,+ window: 5,+};++// ── Error normalization ────────────────────────────────────────────++/**+ * Reduce a raw error / stack trace to a stable signature so that "the same+ * error" can be recognized across iterations even when volatile details+ * (line numbers, addresses, timestamps, ports, temp paths) differ.+ */+export function errorSignature(error: string): string {+ const firstLine = error.split('\n').find((l) => l.trim().length > 0) ?? '';+ return firstLine+ .trim()+ .replace(/\b\d{4}-\d{2}-\d{2}[T ][\d:.]+Z?\b/g, '<ts>') // ISO timestamps+ .replace(/0x[0-9a-fA-F]+/g, '<addr>') // hex addresses+ .replace(/[A-Za-z]:[\\/][^\s:]+|(?:[\\/][^\s:/\\]+)+/g, (p) => {+ const parts = p.split(/[\\/]/);+ return parts[parts.length - 1] || p; // collapse paths to basename+ })+ .replace(/:\d+(:\d+)?/g, '') // line:col suffixes+ .replace(/\b\d+\b/g, '#') // any remaining numbers (ports, ids, counts)+ .replace(/\s+/g, ' ')+ .trim();+}++// ── Circuit breaker ────────────────────────────────────────────────++export type BreakerTrigger =+ | 'ok'+ | 'stagnation'+ | 'no-progress'+ | 'token-budget'+ | 'max-iterations';++export interface BreakerDecision {+ /** Whether the loop is cleared to run another iteration. */+ shouldContinue: boolean;+ /** Whether the loop must hand off to a human. */+ escalate: boolean;+ /** Which condition fired (or 'ok'). */+ trigger: BreakerTrigger;+ /** Human-readable explanation. */+ reason: string;+ iterations: number;+ tokensUsed: number;+}++function totalTokens(ledger: Ledger): number {+ return ledger.attempts.reduce((sum, a) => sum + (a.tokensUsed ?? 0), 0);+}++/** Length of the trailing run of failures (since the last non-failure). */+function trailingFailureRun(attempts: Attempt[]): Attempt[] {+ const run: Attempt[] = [];+ for (let i = attempts.length - 1; i >= 0; i--) {+ if (attempts[i].outcome !== 'failure') break;+ run.unshift(attempts[i]);+ }+ return run;+}++/**+ * Decide whether the loop may continue. Checks the most specific and cheapest-+ * to-fix conditions first (stagnation, then no-progress) before the absolute+ * caps (token budget, iteration count), so the reported reason is the most+ * actionable one when several conditions hold.+ */+export function checkCircuitBreaker(+ ledger: Ledger,+ config: CircuitBreakerConfig = DEFAULT_BREAKER,+): BreakerDecision {+ const iterations = ledger.attempts.length;+ const tokensUsed = totalTokens(ledger);+ const base = { iterations, tokensUsed };++ const failRun = trailingFailureRun(ledger.attempts);++ // Stagnation: the same error signature repeated at the tail.+ if (failRun.length >= config.stagnationThreshold) {+ const lastSig = errorSignature(failRun[failRun.length - 1].error ?? '');+ let same = 0;+ for (let i = failRun.length - 1; i >= 0; i--) {+ if (errorSignature(failRun[i].error ?? '') === lastSig) same++;+ else break;+ }+ if (same >= config.stagnationThreshold) {+ return {+ ...base,+ shouldContinue: false,+ escalate: true,+ trigger: 'stagnation',+ reason: `Same error repeated ${same}× in a row (threshold ${config.stagnationThreshold}): "${lastSig}". Escalating instead of retrying.`,+ };+ }+ }++ // No-progress: many consecutive failures without a success.+ if (failRun.length >= config.noProgressThreshold) {+ return {+ ...base,+ shouldContinue: false,+ escalate: true,+ trigger: 'no-progress',+ reason: `${failRun.length} consecutive failures with no progress (threshold ${config.noProgressThreshold}). Escalating.`,+ };+ }++ // Token budget: absolute spend cap.+ if (config.tokenBudget !== undefined && tokensUsed >= config.tokenBudget) {+ return {+ ...base,+ shouldContinue: false,+ escalate: true,+ trigger: 'token-budget',+ reason: `Token budget reached (${tokensUsed} ≥ ${config.tokenBudget}). Escalating to avoid cost blowup.`,+ };+ }++ // Iteration cap: absolute count.+ if (iterations >= config.maxIterations) {+ return {+ ...base,+ shouldContinue: false,+ escalate: true,+ trigger: 'max-iterations',+ reason: `Iteration cap reached (${iterations} ≥ ${config.maxIterations}). Escalating.`,+ };+ }++ return {+ ...base,+ shouldContinue: true,+ escalate: false,+ trigger: 'ok',+ reason: 'Within limits — cleared to continue.',+ };+}++// ── Pruning ────────────────────────────────────────────────────────++/** Truncate a stack trace to its most useful head, noting how much was dropped. */+export function pruneStackTrace(trace: string, maxLines: number): string {+ const lines = trace.split('\n');+ if (lines.length <= maxLines) return trace.trim();+ const kept = lines.slice(0, maxLines).join('\n').trimEnd();+ const omitted = lines.length - maxLines;+ return `${kept}\n … (${omitted} more line${omitted === 1 ? '' : 's'} pruned)`;+}++/**+ * Produce a lean ledger for injection: keep only the most-recent `window`+ * attempts, prune verbose traces, and collapse consecutive identical failures+ * into a single entry with a repeat count. The full ledger is untouched — this+ * returns a new object.+ */+export function pruneLedger(ledger: Ledger, config: PruneConfig = DEFAULT_PRUNE): Ledger {+ const recent = ledger.attempts.slice(-config.window);++ const collapsed: Attempt[] = [];+ for (const attempt of recent) {+ const pruned: Attempt = {+ ...attempt,+ ...(attempt.error !== undefined+ ? { error: pruneStackTrace(attempt.error, config.maxTraceLines) }+ : {}),+ };++ const prev = collapsed[collapsed.length - 1];+ const sameFailure =+ prev !== undefined &&+ prev.outcome === 'failure' &&+ pruned.outcome === 'failure' &&+ errorSignature(prev.error ?? '') === errorSignature(pruned.error ?? '');++ if (sameFailure) {+ prev.repeated = (prev.repeated ?? 1) + 1;+ prev.iteration = pruned.iteration; // advance to the latest iteration+ } else {+ collapsed.push(pruned);+ }+ }++ return { goal: ledger.goal, startedAt: ledger.startedAt, attempts: collapsed };+}++// ── Summarization ──────────────────────────────────────────────────++export interface ErrorGroup {+ signature: string;+ count: number;+ sample: string;+}++export interface AttemptSummary {+ totalAttempts: number;+ successes: number;+ failures: number;+ noops: number;+ tokensUsed: number;+ /** Distinct error signatures, most frequent first. */+ distinctErrors: ErrorGroup[];+ /** Unique actions the agent has already tried. */+ actionsTried: string[];+}++/** Deterministic factual rollup of the whole run — no LLM required. */+export function summarizeAttempts(ledger: Ledger): AttemptSummary {+ const groups = new Map<string, ErrorGroup>();+ const actions = new Set<string>();+ let successes = 0;+ let failures = 0;+ let noops = 0;++ for (const a of ledger.attempts) {+ actions.add(a.action);+ if (a.outcome === 'success') successes++;+ else if (a.outcome === 'noop') noops++;+ else {+ failures++;+ if (a.error) {+ const sig = errorSignature(a.error);+ const existing = groups.get(sig);+ if (existing) existing.count++;+ else groups.set(sig, { signature: sig, count: 1, sample: a.error.split('\n')[0].trim() });+ }+ }+ }++ return {+ totalAttempts: ledger.attempts.length,+ successes,+ failures,+ noops,+ tokensUsed: totalTokens(ledger),+ distinctErrors: [...groups.values()].sort((a, b) => b.count - a.count),+ actionsTried: [...actions],+ };+}++// ── Injection ──────────────────────────────────────────────────────++/**+ * Build the compact context block to prepend to the next prompt. Contains only+ * what the agent needs to make progress: the goal, what has already been tried+ * (so it does not repeat itself), the last pruned error, and the breaker status.+ */+export function buildContextInjection(+ ledger: Ledger,+ breaker: CircuitBreakerConfig = DEFAULT_BREAKER,+ prune: PruneConfig = DEFAULT_PRUNE,+): string {+ const summary = summarizeAttempts(ledger);+ const decision = checkCircuitBreaker(ledger, breaker);+ const pruned = pruneLedger(ledger, prune);+ const lines: string[] = [];++ lines.push('## Loop Context (managed)');+ lines.push('');+ lines.push(`**Goal:** ${ledger.goal}`);+ lines.push(+ `**Progress:** iteration ${summary.totalAttempts} · ${summary.successes} ok · ${summary.failures} failed` ++ (summary.tokensUsed ? ` · ${summary.tokensUsed} tokens` : ''),+ );+ lines.push('');++ if (summary.actionsTried.length > 0) {+ lines.push('**Already tried (do NOT repeat):**');+ for (const action of summary.actionsTried) lines.push(`- ${action}`);+ lines.push('');+ }++ if (summary.distinctErrors.length > 0) {+ lines.push('**Failure patterns:**');+ for (const g of summary.distinctErrors) {+ lines.push(`- (${g.count}×) ${g.sample}`);+ }+ lines.push('');+ }++ const lastFail = [...pruned.attempts].reverse().find((a) => a.outcome === 'failure');+ if (lastFail?.error) {+ lines.push('**Most recent error (pruned):**');+ lines.push('```');+ lines.push(lastFail.error);+ lines.push('```');+ lines.push('');+ }++ lines.push(+ decision.escalate+ ? `> STOP — circuit breaker tripped (${decision.trigger}). ${decision.reason}`+ : `> Circuit breaker: OK (${decision.iterations}/${breaker.maxIterations} iterations used).`,+ );++ return lines.join('\n');+}diff --git a/tools/loop-context/test/context-manager.test.mjs b/tools/loop-context/test/context-manager.test.mjsnew file mode 100644index 0000000..43b3c95--- /dev/null+++ b/tools/loop-context/test/context-manager.test.mjs@@ -0,0 +1,199 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import {+ errorSignature,+ checkCircuitBreaker,+ pruneStackTrace,+ pruneLedger,+ summarizeAttempts,+ buildContextInjection,+ DEFAULT_BREAKER,+ DEFAULT_PRUNE,+} from '../dist/context-manager.js';++function attempt(iteration, outcome, opts = {}) {+ return { iteration, action: opts.action ?? `try ${iteration}`, outcome, ...opts };+}++function ledger(attempts, goal = 'make the build green') {+ return { goal, attempts };+}++// ── errorSignature ─────────────────────────────────────────────────++test('errorSignature normalizes volatile details to a stable key', () => {+ const a = errorSignature('TypeError: cannot read x at /home/u/app/foo.js:12:5');+ const b = errorSignature('TypeError: cannot read x at /tmp/build/foo.js:88:9');+ assert.equal(a, b);+});++test('errorSignature collapses ports and addresses', () => {+ const a = errorSignature('Error: connect ECONNREFUSED 127.0.0.1:5432');+ const b = errorSignature('Error: connect ECONNREFUSED 127.0.0.1:5433');+ assert.equal(a, b);+});++test('errorSignature keeps genuinely different errors distinct', () => {+ const a = errorSignature('TypeError: undefined is not a function');+ const b = errorSignature('ReferenceError: foo is not defined');+ assert.notEqual(a, b);+});++// ── circuit breaker: stagnation ────────────────────────────────────++test('breaker trips on stagnation (same error 3× in a row)', () => {+ const err = 'Error: connect ECONNREFUSED 127.0.0.1:5432';+ const l = ledger([+ attempt(1, 'failure', { error: err }),+ attempt(2, 'failure', { error: err }),+ attempt(3, 'failure', { error: err }),+ ]);+ const d = checkCircuitBreaker(l);+ assert.equal(d.escalate, true);+ assert.equal(d.trigger, 'stagnation');+ assert.equal(d.shouldContinue, false);+});++test('breaker does not trip when errors differ each time', () => {+ const l = ledger([+ attempt(1, 'failure', { error: 'TypeError: a' }),+ attempt(2, 'failure', { error: 'ReferenceError: b' }),+ ]);+ const d = checkCircuitBreaker(l);+ assert.equal(d.escalate, false);+ assert.equal(d.trigger, 'ok');+});++test('breaker stagnation resets after a success', () => {+ const err = 'Error: boom';+ const l = ledger([+ attempt(1, 'failure', { error: err }),+ attempt(2, 'failure', { error: err }),+ attempt(3, 'success'),+ attempt(4, 'failure', { error: err }),+ ]);+ const d = checkCircuitBreaker(l);+ assert.equal(d.escalate, false, 'trailing failure run is only 1 after the success');+});++// ── circuit breaker: no-progress ───────────────────────────────────++test('breaker trips on no-progress (consecutive failures, distinct errors)', () => {+ const l = ledger([+ attempt(1, 'failure', { error: 'e1' }),+ attempt(2, 'failure', { error: 'e2' }),+ attempt(3, 'failure', { error: 'e3' }),+ attempt(4, 'failure', { error: 'e4' }),+ attempt(5, 'failure', { error: 'e5' }),+ ]);+ const d = checkCircuitBreaker(l, { ...DEFAULT_BREAKER, stagnationThreshold: 99 });+ assert.equal(d.escalate, true);+ assert.equal(d.trigger, 'no-progress');+});++// ── circuit breaker: caps ──────────────────────────────────────────++test('breaker trips on token budget', () => {+ const l = ledger([+ attempt(1, 'noop', { tokensUsed: 600 }),+ attempt(2, 'noop', { tokensUsed: 600 }),+ ]);+ const d = checkCircuitBreaker(l, { ...DEFAULT_BREAKER, tokenBudget: 1000 });+ assert.equal(d.trigger, 'token-budget');+ assert.equal(d.tokensUsed, 1200);+});++test('breaker trips on iteration cap', () => {+ const attempts = [];+ for (let i = 1; i <= 10; i++) attempts.push(attempt(i, 'noop'));+ const d = checkCircuitBreaker(ledger(attempts), { ...DEFAULT_BREAKER, maxIterations: 10 });+ assert.equal(d.trigger, 'max-iterations');+});++test('breaker clears an empty ledger', () => {+ const d = checkCircuitBreaker(ledger([]));+ assert.equal(d.shouldContinue, true);+ assert.equal(d.iterations, 0);+});++// ── pruning ────────────────────────────────────────────────────────++test('pruneStackTrace keeps head and notes omissions', () => {+ const trace = Array.from({ length: 20 }, (_, i) => `line ${i}`).join('\n');+ const pruned = pruneStackTrace(trace, 5);+ assert.ok(pruned.includes('line 0'));+ assert.ok(pruned.includes('15 more lines pruned'));+ assert.ok(!pruned.includes('line 19'));+});++test('pruneStackTrace leaves short traces intact', () => {+ const trace = 'line 0\nline 1';+ assert.equal(pruneStackTrace(trace, 5), trace);+});++test('pruneLedger keeps only the recent window', () => {+ const attempts = [];+ for (let i = 1; i <= 12; i++) attempts.push(attempt(i, 'noop'));+ const pruned = pruneLedger(ledger(attempts), { ...DEFAULT_PRUNE, window: 3 });+ assert.equal(pruned.attempts.length, 3);+ assert.equal(pruned.attempts[2].iteration, 12);+});++test('pruneLedger collapses consecutive identical failures with a count', () => {+ const err = 'Error: same thing';+ const l = ledger([+ attempt(1, 'failure', { error: err }),+ attempt(2, 'failure', { error: err }),+ attempt(3, 'failure', { error: err }),+ ]);+ const pruned = pruneLedger(l, { ...DEFAULT_PRUNE, window: 5 });+ assert.equal(pruned.attempts.length, 1);+ assert.equal(pruned.attempts[0].repeated, 3);+ assert.equal(pruned.attempts[0].iteration, 3);+});++test('pruneLedger does not mutate the input ledger', () => {+ const l = ledger([attempt(1, 'failure', { error: 'x'.repeat(10) + '\n'.repeat(20) })]);+ const before = JSON.stringify(l);+ pruneLedger(l);+ assert.equal(JSON.stringify(l), before);+});++// ── summarization ──────────────────────────────────────────────────++test('summarizeAttempts groups errors by signature, most frequent first', () => {+ const l = ledger([+ attempt(1, 'failure', { error: 'Error: connect ECONNREFUSED 127.0.0.1:5432', action: 'run migration' }),+ attempt(2, 'failure', { error: 'Error: connect ECONNREFUSED 127.0.0.1:5433', action: 'run migration' }),+ attempt(3, 'failure', { error: 'TypeError: x', action: 'patch code' }),+ attempt(4, 'success', { action: 'patch code' }),+ ]);+ const s = summarizeAttempts(l);+ assert.equal(s.totalAttempts, 4);+ assert.equal(s.failures, 3);+ assert.equal(s.successes, 1);+ assert.equal(s.distinctErrors[0].count, 2, 'ECONNREFUSED collapses to one group of 2');+ assert.deepEqual(s.actionsTried, ['run migration', 'patch code']);+});++// ── injection ──────────────────────────────────────────────────────++test('buildContextInjection includes goal, tried actions, and breaker status', () => {+ const err = 'Error: boom';+ const l = ledger([+ attempt(1, 'failure', { error: err, action: 'approach A' }),+ attempt(2, 'failure', { error: err, action: 'approach A' }),+ attempt(3, 'failure', { error: err, action: 'approach A' }),+ ]);+ const block = buildContextInjection(l);+ assert.ok(block.includes('make the build green'));+ assert.ok(block.includes('approach A'));+ assert.ok(block.includes('do NOT repeat'));+ assert.ok(block.includes('STOP'), 'stagnation should surface a STOP directive');+});++test('buildContextInjection shows OK status for a healthy run', () => {+ const l = ledger([attempt(1, 'noop'), attempt(2, 'success')]);+ const block = buildContextInjection(l);+ assert.ok(block.includes('Circuit breaker: OK'));+});diff --git a/tools/loop-context/tsconfig.json b/tools/loop-context/tsconfig.jsonnew file mode 100644index 0000000..ef0f184--- /dev/null+++ b/tools/loop-context/tsconfig.json@@ -0,0 +1,13 @@+{+ "compilerOptions": {+ "target": "ES2022",+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "outDir": "dist",+ "rootDir": "src",+ "strict": true,+ "skipLibCheck": true,+ "declaration": true+ },+ "include": ["src/**/*"]+}