Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 19 additions & 15 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,28 +10,32 @@ tags:

Notable changes to `@dancingteeth/agent-looper`. Dates are UTC.

## Unreleased
## 0.8.3 — 2026-10-21

npm 0.8.2 no longer crashes without `@cursor/sdk`; verify output goes to a sidecar log by default; judge and worker faults park instead of crashing; Harness² ideas: `## Facts`, deliverables, opt-in lessons and stall probes.

### Headline

- **Behaviour change: verify sidecar by default** — `verifyLogMode` now defaults to `sidecar` (was `inline`). Full verify output is written under `<loop-dir>/verify-logs/` (gitignore `verify-logs/` in consumer repos); the worker prompt gets a tail-biased preview plus path. Opt into `inline` to paste capture only. In-memory capture uses head+tail with a middle elision marker (not head-only truncation).
- **Billing token breakdown on green runs** — run log and `run-report.md` sum uncached input, output, and cache read/write across worker and judge sessions, with per-role rows. List vs billed cost semantics unchanged. Cursor SDK runs mark cache splits as **unknown** (not zero).
- **Judge failures park the run** — when the review gate is on and the primary judge errors, the harness classifies the fault, retries once, then tries `reviewSecondary` as fallback primary (merge secondary skipped for that verdict). If both fail, the run parks (`status: waiting`, CLI exit `2`, failure domain `review_judge_failed`) instead of hard-failing like a verify miss.
- **Expected tool-error stats** — `log.ndjson` and `run-report.md` aggregate `tool_end` errors and plain-text tool-call stalls per runtime/model for workers and judges.
- **Transient worker SDK errors** — classify worker faults (connection stalled, `status=error`, timeouts, 5xx/rate-limit vs fatal auth/config). Retry on the next iteration with session recycle and backoff; preserve the working tree; log failure context; retain partial Cursor usage when the SDK reported it. Cap consecutive transients (`maxConsecutiveTransientAgentErrors`, default 3) then park (`agent_transient_exhausted`).
- **Secondary review errors** — a failed optional `reviewSecondary` merge session is logged and noted in `review.md`; the primary verdict alone decides completion.
- **Lazy optional peers** — the CLI no longer statically imports `@cursor/sdk` (or other runtime SDKs) at startup. `agent-loop --version`, `--help`, `agent-loop-init`, and `agent-check` for a non-Cursor runtime work with only `@dancingteeth/agent-looper` installed. Selecting a runtime whose SDK is missing fails with an actionable install line (`Runtime "cursor" needs @cursor/sdk: pnpm add -D @cursor/sdk`) instead of `ERR_MODULE_NOT_FOUND`.
- **CI: npm pack smoke** — packs the tarball, installs it in a temp project with zero optional peers, and asserts `--version` / `--help` plus the friendly missing-SDK error; also checks OpenCode-only peers without `@cursor/sdk`.
- **Lazy optional peers** — the CLI no longer statically imports `@cursor/sdk` (or other runtime SDKs) at startup. `agent-loop --version`, `--help`, `agent-loop-init`, and `agent-check` for a non-Cursor runtime work with only `@dancingteeth/agent-looper` installed. Selecting a runtime whose SDK is missing fails with an actionable install line (`Runtime "cursor" needs @cursor/sdk: pnpm add -D @cursor/sdk`) instead of `ERR_MODULE_NOT_FOUND`. This fixes the 0.8.2 crash when `@cursor/sdk` is not installed. ([#44](https://github.com/dancingteeth/agent-looper/pull/44))
- **Behaviour change: verify sidecar by default** — `verifyLogMode` now defaults to `sidecar` (was `inline`). Full verify output is written under `<loop-dir>/verify-logs/` (gitignore `verify-logs/` in consumer repos); the worker prompt gets a tail-biased preview plus path. Opt into `inline` to paste capture only. In-memory capture uses head+tail with a middle elision marker (not head-only truncation). ([#45](https://github.com/dancingteeth/agent-looper/pull/45))
- **Parked runs keep exit `2`** — every waiting park (budget, verify environment, judge down, transient worker cap, stall-probe restore failure) exits `2` in the CLI, the same as an incomplete run (per Paul); no separate exit code. ([#45](https://github.com/dancingteeth/agent-looper/pull/45))
- **Judge failures park the run** — when the review gate is on and the primary judge errors, the harness classifies the fault, retries once, then tries `reviewSecondary` as fallback primary (merge secondary skipped for that verdict). If both fail, the run parks (`status: waiting`, CLI exit `2`, failure domain `review_judge_failed`) instead of hard-failing like a verify miss. ([#45](https://github.com/dancingteeth/agent-looper/pull/45))
- **Transient worker SDK errors** — classify worker faults (connection stalled, `status=error`, timeouts, 5xx/rate-limit vs fatal auth/config). Retry on the next iteration with session recycle and backoff; preserve the working tree; log failure context; retain partial Cursor usage when the SDK reported it. Cap consecutive transients (`maxConsecutiveTransientAgentErrors`, default 3) then park (`agent_transient_exhausted`). ([#45](https://github.com/dancingteeth/agent-looper/pull/45))
- **Billing token breakdown on green runs** — run log and `run-report.md` sum uncached input, output, and cache read/write across worker and judge sessions, with per-role rows. List vs billed cost semantics unchanged. Cursor SDK runs mark cache splits as **unknown** (not zero). ([#45](https://github.com/dancingteeth/agent-looper/pull/45))
- **Expected tool-error stats** — `log.ndjson` and `run-report.md` aggregate `tool_end` errors and plain-text tool-call stalls per runtime/model for workers and judges. ([#45](https://github.com/dancingteeth/agent-looper/pull/45))
- **Secondary review errors** — a failed optional `reviewSecondary` merge session is logged and noted in `review.md`; the primary verdict alone decides completion. ([#45](https://github.com/dancingteeth/agent-looper/pull/45))
- **CI: npm pack smoke** — packs the tarball, installs it in a temp project with zero optional peers, and asserts `--version` / `--help` plus the friendly missing-SDK error; also checks OpenCode-only peers without `@cursor/sdk`. ([#44](https://github.com/dancingteeth/agent-looper/pull/44))

### Harness² ideas

- **`stallProbes`** — opt-in (`false` by default): on the first hard stall at `escalateAfterStagnation`, run two sequential probe workers with different prompt sections, snapshot/restore the git workspace between them, keep whichever verify result goes green or moves the failure fingerprint, log `probe: { variant, kept }`, then allow model escalation on later stalls. Disabled when `stagnationThreshold` is `0`. Restore puts back the branch (a probe's `git checkout -b` / detached HEAD) and HEAD (a probe's own commits are soft-reset; an unrelated HEAD is refused), restores `.gitignore` files and `info/exclude` first, and never deletes a path the snapshot's ignore rules ignore. A failed restore parks the run (`status: waiting`, failure domain `stall_probe_restore_failed`) with the restore error and the probe's original error.
- **`## Facts` block** — the stable prompt head states the verifier command exactly as configured (not trimmed) and the deliverables, on its own line after the rules; without either, the head is byte-identical to before. ([#46](https://github.com/dancingteeth/agent-looper/pull/46))
- **Plain-text tool-call warning + safety rule 7** — when the previous worker reply wrote tool calls as plain text instead of calling tools, the next prompt's volatile tail warns about it; safety rule 7 tells workers to use the tool interface. ([#46](https://github.com/dancingteeth/agent-looper/pull/46))
- **`deliverables`** — optional repo-relative paths in `loop.json`; worker prompts state them in `## Facts`, and the harness nudges the worker before verify when files are missing or empty (`deliverableNudges`, default `2`). ([#46](https://github.com/dancingteeth/agent-looper/pull/46))
- **Deliverables confined to the repo** — `deliverables` must be repo-relative: absolute paths and `..` escapes are rejected when `loop.json` is parsed, so the deliverable check and nudges never look outside the repo. Worker faults during a deliverable nudge go through the same fault path as the main worker call (transient classification, escalation, parking). ([#46](https://github.com/dancingteeth/agent-looper/pull/46))
- **Fix: HTTP/2 `CANCEL` crash** — a Connect-node `http/2 stream closed with error code CANCEL (0x8)` rejection nobody awaited (Cursor runtime) is now treated as a detached HTTP/2 transport error instead of crashing the process. ([#46](https://github.com/dancingteeth/agent-looper/pull/46))
- **`lessons.md`** — **opt-in** (`"lessons": true`; default `false`). After a green verifier run, the harness writes deduped verify gotchas to the loop bundle; the next run injects them before `## Workspace (git)`. Gotchas are the most informative lines of each failure overcome (failing `[verify]` step + `FAIL`/error lines, stderr first; banner, progress and summary lines skipped; at most 3 lines of 240 chars per failure, 6000 chars per file). Verifier output is stored and injected as a fenced block labelled as data, not instructions (the fence is longer than any backtick run in the output). Workers cannot edit the file (frozen). ([#47](https://github.com/dancingteeth/agent-looper/pull/47))
- **`stallProbes`** — opt-in (`false` by default): on the first hard stall at `escalateAfterStagnation`, run two sequential probe workers with different prompt sections, snapshot/restore the git workspace between them, keep whichever verify result goes green or moves the failure fingerprint, log `probe: { variant, kept }`, then allow model escalation on later stalls. Disabled when `stagnationThreshold` is `0`. Restore puts back the branch (a probe's `git checkout -b` / detached HEAD) and HEAD (a probe's own commits are soft-reset; an unrelated HEAD is refused), restores `.gitignore` files and `info/exclude` first, and never deletes a path the snapshot's ignore rules ignore. A failed restore parks the run (`status: waiting`, failure domain `stall_probe_restore_failed`) with the restore error and the probe's original error. ([#47](https://github.com/dancingteeth/agent-looper/pull/47))
- **Snapshot limits:** ignored files (`.env`, `node_modules/`, local data) are **not** saved in the snapshot — restore leaves them as they are rather than restoring them. Not safe with concurrent writers: restore reverts *every* change made in the worktree during the probe round (your editor, another loop, another process's commits), not only the probe's. Run one loop per worktree and don't edit it while probes run.
- **`lessons.md`** — **opt-in** (`"lessons": true`; default `false`). After a green verifier run, the harness writes deduped verify gotchas to the loop bundle; the next run injects them before `## Workspace (git)`. Gotchas are the most informative lines of each failure overcome (failing `[verify]` step + `FAIL`/error lines, stderr first; banner, progress and summary lines skipped; at most 3 lines of 240 chars per failure, 6000 chars per file). Verifier output is stored and injected as a fenced block labelled as data, not instructions (the fence is longer than any backtick run in the output). Workers cannot edit the file (frozen).
- **`deliverables`** — optional repo-relative paths in `loop.json`; worker prompts state them in `## Facts`, and the harness nudges the worker before verify when files are missing or empty (`deliverableNudges`, default `2`).
- **`## Facts` block** (#46) — the stable prompt head states the verifier command exactly as configured (not trimmed) and the deliverables, on its own line after the rules; without either, the head is byte-identical to before.
- **Plain-text tool-call warning + safety rule 7** (#46) — when the previous worker reply wrote tool calls as plain text instead of calling tools, the next prompt's volatile tail warns about it; safety rule 7 tells workers to use the tool interface.
- **Fix: HTTP/2 `CANCEL` crash** (#46) — a Connect-node `http/2 stream closed with error code CANCEL (0x8)` rejection nobody awaited (Cursor runtime) is now treated as a detached HTTP/2 transport error instead of crashing the process.

## 0.8.2 — 2026-10-20

Expand Down
2 changes: 1 addition & 1 deletion CONSUMERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Or in `package.json`:
```json
{
"devDependencies": {
"@dancingteeth/agent-looper": "^0.8.2",
"@dancingteeth/agent-looper": "^0.8.3",
"@cursor/sdk": "^1.0.18"
}
}
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ pnpm exec agent-loop run .cursor/loops/my-task

Each runtime also needs its own SDK or CLI and key, e.g. `@cursor/sdk` + `CURSOR_API_KEY` for Cursor, `claude` on PATH for Claude Code, `opencode` for OpenCode. [`docs/runtime-map.md`](./docs/runtime-map.md) lists them all; `pnpm exec agent-check <runtime>` confirms one is wired. Flags and the rest are below. You do not need them for a first green run.

How the loop is shaped: [`README.intro.md`](./README.intro.md). Technical deep dive: [`ARCHITECTURE.md`](./ARCHITECTURE.md) (including §1.1 — the harness is a small control-flow graph; the Ralph loop lives inside the worker node). npm releases: [`docs/releasing.md`](./docs/releasing.md). What shipped: [`CHANGELOG.md`](./CHANGELOG.md) (current **0.8.2**). Embedding this package as a library dependency in another ADE: [`docs/embed-api.md`](./docs/embed-api.md). Reporting a vulnerability: [`SECURITY.md`](./SECURITY.md).
How the loop is shaped: [`README.intro.md`](./README.intro.md). Technical deep dive: [`ARCHITECTURE.md`](./ARCHITECTURE.md) (including §1.1 — the harness is a small control-flow graph; the Ralph loop lives inside the worker node). npm releases: [`docs/releasing.md`](./docs/releasing.md). What shipped: [`CHANGELOG.md`](./CHANGELOG.md) (current **0.8.3**). Embedding this package as a library dependency in another ADE: [`docs/embed-api.md`](./docs/embed-api.md). Reporting a vulnerability: [`SECURITY.md`](./SECURITY.md).

Supports pluggable **agent SDK** workers (`runtime`) and judges (`reviewRuntime`). Shipped today: **Cursor**, **Cline** (Pass / Credits), **OpenCode** (Go + BYOK), **Pi**, **Codex**, **DSH** (PATH `dsh`), **Muse** (PATH `muse`), **Claude** (PATH `claude`, `--safe-mode`). Defaults and cost notes: [`docs/runtime-map.md`](./docs/runtime-map.md). DSH companion for `dsh web` (skills + scaffold, not a second harness): [`docs/dsh-plugin.md`](./docs/dsh-plugin.md). OpenCode companion plugin (1.x + 2.x: skills, detached `agent_loop_start`, shell guard): [`plugins/opencode-agent-looper/`](./plugins/opencode-agent-looper/). Muse Code: [`docs/muse-runtime.md`](./docs/muse-runtime.md). Claude Code: [`docs/claude-runtime.md`](./docs/claude-runtime.md). To measure cheap-worker claims on a frozen loop: [`docs/runtime-cost-bench.md`](./docs/runtime-cost-bench.md). The judge runs on the worker's runtime when `reviewRuntime` is unset (each runtime has its own judge model, e.g. OpenCode → DeepSeek V4 Pro, Claude → Opus); set `reviewRuntime` + `reviewModel` to pair a cheap worker with a different judge.

Expand Down
2 changes: 1 addition & 1 deletion docs/embed-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ the whole file.

## Public API and what breaks a major

Current package version: **0.8.2**. Until 1.0, minor bumps may still add fields to `Stable`
Current package version: **0.8.3**. Until 1.0, minor bumps may still add fields to `Stable`
types (additive, non-breaking for a host that ignores unknown fields) — a major bump is reserved
for anything that removes or renames a field, changes a field's type, or removes an export from
the [Supported surface](#supported-surface-stable-vs-experimental) table above.
Expand Down
4 changes: 2 additions & 2 deletions llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Start here:
- README.intro.md — product spine (worker / verify / judge / human)
- ARCHITECTURE.md — loop engine, escalation, cache-friendly prompts
- AGENTS.md — working agreements for this repo
- CHANGELOG.md — shipped versions (current: 0.8.2)
- CHANGELOG.md — shipped versions (current: 0.8.3)
- SECURITY.md — vulnerability reporting
- docs/embed-api.md — library embed contract (stable vs experimental, frozen shapes)
- docs/claude-runtime.md — PATH `claude -p --safe-mode` worker/judge
Expand Down Expand Up @@ -54,4 +54,4 @@ Worker default: composer-2.5. Judge default: grok-4.6 (`reviewModel`). `runtime:

## Package

npm: `@dancingteeth/agent-looper` **0.8.2**. Layout: src/loop, src/review, src/agents, templates, .cursor/loops. Embed: docs/embed-api.md. Security: SECURITY.md.
npm: `@dancingteeth/agent-looper` **0.8.3**. Layout: src/loop, src/review, src/agents, templates, .cursor/loops. Embed: docs/embed-api.md. Security: SECURITY.md.
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@dancingteeth/agent-looper",
"version": "0.8.2",
"version": "0.8.3",
"description": "Fix-until-green harness for coding agents: frozen goal + verify.sh, a fresh worker each round, optional judge review. Works with Cursor, Claude Code, Codex, OpenCode, Cline, Pi, DSH, and Muse.",
"keywords": [
"agent",
Expand Down
2 changes: 1 addition & 1 deletion site/about/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ <h1>About Agent Looper</h1>
<li><a href="../">Product site</a></li>
<li><a href="https://github.com/dancingteeth/agent-looper">Source</a></li>
<li><a href="https://www.npmjs.com/package/@dancingteeth/agent-looper">npm</a></li>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md">Changelog</a> — 0.8.2</li>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md">Changelog</a> — 0.8.3</li>
<li><a href="https://dancingteeth.net/">Author</a></li>
</ul>
</div>
Expand Down
2 changes: 1 addition & 1 deletion site/about/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,5 @@ Agent Looper is made by Paul Zgordan (dancingteeth), who also writes at The Vacu
- Product: https://looper.dancingteeth.net/
- Source: https://github.com/dancingteeth/agent-looper
- npm: https://www.npmjs.com/package/@dancingteeth/agent-looper
- Changelog (0.8.2): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
- Changelog (0.8.3): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
- Author: https://dancingteeth.net/
2 changes: 1 addition & 1 deletion site/docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ <h1>Agent Looper developer resources</h1>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/docs/claude-runtime.md">Claude runtime</a> — Claude Code CLI</li>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/docs/embed-api.md">Embed API</a> — contract for embedding Agent Looper</li>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/SECURITY.md">Security</a> — reporting vulnerabilities</li>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md">Changelog</a> — 0.8.2</li>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md">Changelog</a> — 0.8.3</li>
<li><a href="../llms.txt">Agent Looper llms.txt</a></li>
<li><a href="../index.md">Agent Looper homepage (markdown)</a></li>
</ul>
Expand Down
2 changes: 1 addition & 1 deletion site/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Agent Looper is the npm package `@dancingteeth/agent-looper` and the CLI `agent-
- Claude runtime (Claude Code CLI): https://github.com/dancingteeth/agent-looper/blob/main/docs/claude-runtime.md
- Embed API (contract for embedding Agent Looper): https://github.com/dancingteeth/agent-looper/blob/main/docs/embed-api.md
- Security (reporting vulnerabilities): https://github.com/dancingteeth/agent-looper/blob/main/SECURITY.md
- Changelog (0.8.2): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
- Changelog (0.8.3): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
- Agent Looper llms.txt: https://looper.dancingteeth.net/llms.txt
- Agent Looper homepage (markdown): https://looper.dancingteeth.net/index.md

Expand Down
2 changes: 1 addition & 1 deletion site/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Agent Looper is free and MIT-licensed. If it saves you time:
- [llms.txt](https://looper.dancingteeth.net/llms.txt)
- [Harnesses](https://looper.dancingteeth.net/harnesses/)
- [Developer resources](https://looper.dancingteeth.net/docs/)
- [Changelog (0.8.2)](https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md)
- [Changelog (0.8.3)](https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md)
- [Embed API](https://github.com/dancingteeth/agent-looper/blob/main/docs/embed-api.md)
- [Security](https://github.com/dancingteeth/agent-looper/blob/main/SECURITY.md)
- [GitHub](https://github.com/dancingteeth/agent-looper)
Expand Down
Loading
Loading