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
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,21 @@ tags:

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

## 0.8.6 — 2026-11-12

DSH 0.2.1 compatibility, and a failed `agent-loop-prompt` run now shows why it failed.

### Fixes

- **DSH credentials preflight accepts layout v1.** DSH 0.2.1 `credentials-local` requires `version: 1` + `refs:` (what `dsh web` writes) and auto-migrates the old flat map. The 0.6.3 preflight still demanded the flat map, so every DSH loop with a `dsh web` store aborted before WORKER. `agent-check dsh` and `agent-loop run` now reject only what DSH itself refuses: a `version` other than unquoted `1`, non-POSIX or non-string `refs`, or a flat map DSH cannot migrate.
- **DSH loops require `DEEPSEEK_API_KEY` in the environment.** DSH 0.2.1 `--profile headless` mounts no credentials service, so a key stored in `~/.dsh/.credentials.yaml` never reaches the worker and the run died on iteration 1 with `MISSING_CREDENTIAL`. `agent-loop run` / `agent-loop-batch` / `agent-check dsh` now abort up front with an explanation.

### Prompt TUI

- **Done screen shows the failure reason.** On a failed run, `agent-loop-prompt` prints the `AGENT_LOOP_DONE` reason (or the last `failed:` line) and the `prompt-run.log` path, reading only this run's part of the log. `--plain` prints the same on stderr.

[npm](https://www.npmjs.com/package/@dancingteeth/agent-looper) · [tag](https://github.com/dancingteeth/agent-looper/releases/tag/v0.8.6)

## 0.8.5 — 2026-11-01

Capable → efficient handoff, after [AgentBaton](https://arxiv.org/abs/2610.35959): start the loop on the strong model, hand off to a cheaper same-runtime model once the harness (not the worker) detects readiness.
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.5",
"@dancingteeth/agent-looper": "^0.8.6",
"@cursor/sdk": "^1.0.18"
}
}
Expand Down
4 changes: 2 additions & 2 deletions 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.5**). 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.6**). 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 Expand Up @@ -125,7 +125,7 @@ pnpm exec agent-check codex
pnpm exec agent-loop run .cursor/loops/my-task --runtime codex

# DeepSeek Harness (needs `dsh` on PATH; Node ≥ 22.15)
export DEEPSEEK_API_KEY=… # or DSH credentials-local
export DEEPSEEK_API_KEY=… # required: DSH headless ignores ~/.dsh/.credentials.yaml
pnpm exec agent-check dsh
pnpm exec agent-loop run .cursor/loops/my-task --runtime dsh
# runtime: docs/dsh-runtime.md — dsh web companion: docs/dsh-plugin.md
Expand Down
1 change: 1 addition & 0 deletions docs/dsh-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ tags:
- agents
- loops
- agentic_ai
- type/app
---
# DeepSeek Harness companion plugin

Expand Down
10 changes: 7 additions & 3 deletions docs/dsh-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Full Access on the **web** session does not change the headless worker patch: th

```bash
# Node ≥ 22.15 (DSH zlib/zstd). dsh on PATH.
export DEEPSEEK_API_KEY=… # or DSH credentials-local / settings
export DEEPSEEK_API_KEY=… # required: DSH headless ignores ~/.dsh/.credentials.yaml
# this checkout:
node dist/cli/check.js dsh
# consumer (agent-looper is a dependency):
Expand All @@ -79,9 +79,13 @@ pnpm exec agent-check dsh

## Credentials document

`$DSH_HOME/.credentials.yaml` (default `~/.dsh/.credentials.yaml`) must be a **flat** `KEY: "string"` map. Current DSH `credentials-local` rejects a wrapped store (`version` / `refs` / `records`) and YAML integers (`version: 1`). Headless still parses that file even when `DEEPSEEK_API_KEY` is in the environment — quoting `version` is not enough.
`$DSH_HOME/.credentials.yaml` (default `~/.dsh/.credentials.yaml`) uses DSH **layout v1** since DSH 0.2.1: `version: 1` (unquoted integer), `refs:` holding `KEY: "string"` entries, and DSH-owned `records:` (`dsh web` writes a `client-connection/browser-session` record there). DSH still auto-migrates the pre-release flat `KEY: "string"` map. Headless parses the file even when `DEEPSEEK_API_KEY` is in the environment.

`agent-check dsh` and `agent-loop run` abort **before WORKER** when the document looks wrapped. Flatten it to `DEEPSEEK_API_KEY: "…"`. Do not dump the file. The harness does not rewrite it (`dsh web` may recreate the wrapped schema).
**The key itself must come from the environment.** DSH 0.2.1 `--profile headless` mounts no credentials service, so a `DEEPSEEK_API_KEY` stored in `refs:` (what the web Models page writes) is invisible to the worker and the run dies with `MISSING_CREDENTIAL` on iteration 1. `agent-loop run` and `agent-check dsh` therefore abort up front unless `DEEPSEEK_API_KEY` is exported (or injected via Doppler).

`agent-check dsh` and `agent-loop run` abort **before WORKER** only when the document would fail DSH boot: a `version` other than unquoted `1` (`version: "1"` fails), non-POSIX or non-string `refs` entries, or a flat map DSH cannot migrate. The scan is structure-only and never echoes values. Do not dump the file. The harness does not rewrite it.

Before agent-looper 0.8.6 the preflight required the flat map and rejected layout v1 — the opposite of what DSH 0.2.1+ needs.

## Defaults

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.5**. Until 1.0, minor bumps may still add fields to `Stable`
Current package version: **0.8.6**. 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
2 changes: 2 additions & 0 deletions docs/muse-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ tags:
- muse
- cost
- agents
- agentic_ai
- type/app
---
# Muse Code worker runtime

Expand Down
2 changes: 2 additions & 0 deletions docs/runtime-cost-bench.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ tags:
- cost
- agents
- loops
- agentic_ai
- type/app
---
# Same-task runtime cost bench

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.5)
- CHANGELOG.md — shipped versions (current: 0.8.6)
- 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.5**. Layout: src/loop, src/review, src/agents, templates, .cursor/loops. Embed: docs/embed-api.md. Security: SECURITY.md.
npm: `@dancingteeth/agent-looper` **0.8.6**. 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.5",
"version": "0.8.6",
"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
7 changes: 2 additions & 5 deletions plugins/agent-looper/skills/check-running-loops/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,12 @@
---
name: check-running-loops
description: >-
Checks whether agent-loop / agent-loop-batch jobs are actually alive, stale, hung, dead, or done,
for any worker/judge runtime (Cursor, Cline, OpenCode, Pi, Codex, DSH, Muse, Claude).
Use when the user asks if loops are ok, stuck, running, healthy, or what the current batch status is;
when they mention agent-loop, loop-batch, verify.sh harness, or AGENT_LOOP_DONE.
description: Checks whether agent-loop / agent-loop-batch jobs are actually alive, stale, hung, dead, or done, for any worker/judge runtime (Cursor, Cline, OpenCode, Pi, Codex, DSH, Muse, Claude). Use when the user asks if loops are ok, stuck, running, healthy, or what the current batch status is; when they mention agent-loop, loop-batch, verify.sh harness, or AGENT_LOOP_DONE.
tags:
- agentic_ai
- agents
- documentation
- loops
- type/app
---

# Check running loops
Expand Down
1 change: 1 addition & 0 deletions plugins/dsh-agent-looper/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ tags:
- documentation
- loops
- plugins
- type/app
---
# Agent Looper (DSH companion plugin)

Expand Down
1 change: 1 addition & 0 deletions plugins/dsh-agent-looper/skills/design-loop/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ tags:
- agents
- documentation
- loops
- type/app
---

# Design a loop
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ tags:
- agents
- documentation
- loops
- type/app
---

# Install Agent Looper
Expand Down
1 change: 1 addition & 0 deletions plugins/dsh-agent-looper/skills/review-gate/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ tags:
- agents
- documentation
- loops
- type/app
---

# Review gate
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.5</li>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md">Changelog</a> — 0.8.6</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.5): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
- Changelog (0.8.6): 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.5</li>
<li><a href="https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md">Changelog</a> — 0.8.6</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.5): https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md
- Changelog (0.8.6): 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/harnesses/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ <h3>DSH</h3>
<span class="harness-chip">Judge: same runtime by default (V4 Pro), override any, optional</span>
</p>
<p class="harness-card__run"><code>pnpm exec agent-loop run .cursor/loops/my-task --runtime dsh --review-gate</code></p>
<p class="harness-card__note">Default worker is <code>deepseek-official/deepseek-flash</code> (DeepSeek-V41-Flash, image-capable). Previous <code>deepseek-official/deepseek-v4-flash</code> stays allowed. Ensure <code>dsh</code> is on PATH. <code>~/.dsh/.credentials.yaml</code> must be a flat <code>KEY: "string"</code> map — a wrapped store (<code>version</code> / <code>refs</code> / <code>records</code>) or YAML integer fails <code>agent-check dsh</code> and <code>agent-loop run</code> before spawning the worker. Quoting <code>version</code> alone is not enough; the harness does not rewrite that file. DSH companion plugin guard blocks accidental foreground grinds. See <a href="https://github.com/dancingteeth/agent-looper/blob/main/docs/dsh-plugin.md">docs/dsh-plugin.md</a> and <a href="https://github.com/dancingteeth/agent-looper/tree/main/plugins/dsh-agent-looper">plugins/dsh-agent-looper/</a>.</p>
<p class="harness-card__note">Default worker is <code>deepseek-official/deepseek-flash</code> (DeepSeek-V41-Flash, image-capable). Previous <code>deepseek-official/deepseek-v4-flash</code> stays allowed. Ensure <code>dsh</code> is on PATH. Export <code>DEEPSEEK_API_KEY</code> in the launching shell — DSH 0.2.1 headless ignores the key stored in <code>~/.dsh/.credentials.yaml</code>, so <code>agent-check dsh</code> and <code>agent-loop run</code> abort before spawning the worker without it. The file itself may be DSH layout v1 (<code>version: 1</code> + <code>refs:</code>, what <code>dsh web</code> writes) or the old flat map; the harness does not rewrite that file. DSH companion plugin guard blocks accidental foreground grinds. See <a href="https://github.com/dancingteeth/agent-looper/blob/main/docs/dsh-plugin.md">docs/dsh-plugin.md</a> and <a href="https://github.com/dancingteeth/agent-looper/tree/main/plugins/dsh-agent-looper">plugins/dsh-agent-looper/</a>.</p>
</article>

<article class="harness-card" id="cline">
Expand Down
2 changes: 1 addition & 1 deletion site/harnesses/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ DeepSeek Harness CLI — worker is `dsh --profile headless`; `dsh-agent-looper`
- Worker: `deepseek-official/deepseek-flash` (4.1 Flash, escalates to `deepseek-official/deepseek-v4-pro`). Previous `deepseek-official/deepseek-v4-flash` stays allowed.
- Judge (optional): same runtime by default (V4 Pro), override any
- Run: `pnpm exec agent-loop run .cursor/loops/my-task --runtime dsh --review-gate`
- `~/.dsh/.credentials.yaml` must be a flat `KEY: "string"` map — a wrapped store (`version` / `refs` / `records`) or YAML integer fails `agent-check dsh` and `agent-loop run` before spawning the worker. Quoting `version` alone is not enough; the harness does not rewrite that file.
- Export `DEEPSEEK_API_KEY` in the launching shell — DSH 0.2.1 headless ignores the key stored in `~/.dsh/.credentials.yaml`, so `agent-check dsh` and `agent-loop run` abort before spawning the worker without it. The file itself may be DSH layout v1 (`version: 1` + `refs:`, what `dsh web` writes) or the old flat map; the harness does not rewrite that file.
- DSH companion plugin guard blocks accidental foreground grinds

### Cline (`--runtime cline-pass` · `cline`)
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.5)](https://github.com/dancingteeth/agent-looper/blob/main/CHANGELOG.md)
- [Changelog (0.8.6)](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