amness 0.0.0-stage → 0.1.0

package/dist/src/web.js

@@ -0,0 +1,56 @@
+import { defineTool } from "./harness.js";
+const decode = (s) => s.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#x27;|&#39;/g, "'").replace(/&nbsp;/g, " ");
+const strip = (s) => decode(s.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
+/** Tavily (needs TAVILY_API_KEY): returns clean snippets built for agents. */
+export const tavily = (key = process.env.TAVILY_API_KEY ?? "") => async (query, n) => {
+    const r = await fetch("https://api.tavily.com/search", {
+        method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+        body: JSON.stringify({ query, max_results: n }), signal: AbortSignal.timeout(20_000),
+    });
+    if (!r.ok)
+        throw new Error(`tavily HTTP ${r.status}`);
+    return ((await r.json()).results ?? []).map((x) => ({ title: x.title, url: x.url, snippet: x.content }));
+};
+/** Keyless fallback: scrapes DuckDuckGo's HTML endpoint. Fragile by nature; prefer a real provider in production. */
+export const duckduckgo = async (query, n) => {
+    const r = await fetch("https://html.duckduckgo.com/html/?q=" + encodeURIComponent(query), { headers: { "user-agent": "Mozilla/5.0 (amness)" }, signal: AbortSignal.timeout(20_000) });
+    if (!r.ok)
+        throw new Error(`duckduckgo HTTP ${r.status}`);
+    const html = await r.text();
+    const hits = [];
+    const re = /<a[^>]+class="result__a"[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
+    for (let m; (m = re.exec(html)) && hits.length < n;) {
+        const href = decode(m[1]);
+        const real = new URL(href, "https://duckduckgo.com").searchParams.get("uddg") ?? href;
+        hits.push({ title: strip(m[2]), url: real, snippet: strip(m[3]) });
+    }
+    return hits;
+};
+const PRIVATE = /^(localhost|127\.|10\.|192\.168\.|169\.254\.|172\.(1[6-9]|2\d|3[01])\.|0\.|\[?::1)/;
+/** Fetch a URL and reduce it to readable text. Refuses non-http(s) and local/private hosts. */
+export async function fetchText(url, max = 20_000, offset = 0) {
+    const u = new URL(url);
+    if (!/^https?:$/.test(u.protocol) || PRIVATE.test(u.hostname))
+        throw new Error("refusing to fetch " + url);
+    const r = await fetch(u, { headers: { "user-agent": "Mozilla/5.0 (amness)" }, signal: AbortSignal.timeout(20_000), redirect: "follow" });
+    if (!r.ok)
+        throw new Error(`HTTP ${r.status} for ${url}`);
+    const body = await r.text();
+    const text = /html/.test(r.headers.get("content-type") ?? "")
+        ? strip(body.replace(/<(script|style|noscript|svg|nav|footer|header)[\s\S]*?<\/\1>/gi, " ").replace(/<(\/?(p|div|br|li|h\d|tr|section|article))[^>]*>/gi, "\n")).replace(/ ?\n ?/g, "\n")
+        : body;
+    const slice = text.slice(offset, offset + max);
+    return slice + (text.length > offset + max ? `\n[truncated; ${text.length - offset - max} more chars. Call again with offset=${offset + max}]` : "");
+}
+export const webTools = (search = process.env.TAVILY_API_KEY ? tavily() : duckduckgo) => [
+    defineTool({
+        name: "web_search", untrusted: true, description: "Search the web. Returns title, url, snippet per hit. Use specific queries; run several varied ones.",
+        schema: { type: "object", required: ["query"], properties: { query: { type: "string" }, n: { type: "integer" } } },
+        run: async ({ query, n }) => (await search(query, Math.min(n ?? 6, 10))).map((h, i) => `${i + 1}. ${h.title}\n   ${h.url}\n   ${h.snippet}`).join("\n") || "no results; rephrase the query",
+    }),
+    defineTool({
+        name: "fetch_url", untrusted: true, description: "Fetch a web page as readable text (20k chars per call; use offset to page).",
+        schema: { type: "object", required: ["url"], properties: { url: { type: "string" }, offset: { type: "integer" } } },
+        run: ({ url, offset }) => fetchText(url, 20_000, offset ?? 0),
+    }),
+];

package/dist/src/worktree.d.ts

@@ -0,0 +1,24 @@
+export type Worktree = {
+    dir: string; /** the repository it was made from */
+    repo: string;
+};
+/** True inside a git repository with at least one commit. */
+export declare function isRepo(cwd: string): Promise<boolean>;
+/** A detached worktree of HEAD in a fresh temp folder. Uncommitted work in the main tree is NOT included (the isolated agent starts from the last commit). */
+export declare function createWorktree(repo: string): Promise<Worktree>;
+/** Everything changed in the worktree relative to its starting commit, as one unified diff (new files included). */
+export declare function worktreeDiff(w: Worktree): Promise<string>;
+export declare function removeWorktree(w: Worktree): Promise<void>;
+/** Apply a unified diff to a working tree (atomically: `git apply --check` first). Returns what failed, or undefined. */
+export declare function applyDiff(cwd: string, diff: string): Promise<string | undefined>;
+/** Undo a diff that was applied with applyDiff. */
+export declare function revertDiff(cwd: string, diff: string): Promise<string | undefined>;
+/** A named, persistent worktree on its own branch (`amness/<name>`) inside the repository's `.amness/worktrees/`, for a whole working session. */
+export declare function createSessionWorktree(repo: string, name: string): Promise<{
+    dir: string;
+    branch: string;
+    repo: string; /** the commit it branched from */
+    base: string;
+}>;
+/** True when nothing has changed in `dir` (no modified, staged or untracked files) and the branch has no commits beyond `base`. */
+export declare function worktreeIsUntouched(dir: string, base: string): Promise<boolean>;

package/dist/src/worktree.js

@@ -0,0 +1,85 @@
+// Git worktrees: an isolated copy of the repository at HEAD, so an agent can edit freely without touching the working tree. The result comes back as a diff.
+import { execFile } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const git = (cwd, args, input) => new Promise((res, rej) => { const p = execFile("git", args, { cwd, maxBuffer: 64 << 20 }, (e, out, err) => (e ? rej(new Error((err || e.message).trim().split("\n")[0])) : res(out))); if (input !== undefined) {
+    p.stdin?.end(input);
+} });
+/** True inside a git repository with at least one commit. */
+export async function isRepo(cwd) { try {
+    await git(cwd, ["rev-parse", "--verify", "HEAD"]);
+    return true;
+}
+catch {
+    return false;
+} }
+/** A detached worktree of HEAD in a fresh temp folder. Uncommitted work in the main tree is NOT included (the isolated agent starts from the last commit). */
+export async function createWorktree(repo) {
+    const root = (await git(repo, ["rev-parse", "--show-toplevel"])).trim(), dir = mkdtempSync(join(tmpdir(), "amness-wt-"));
+    try {
+        await git(root, ["worktree", "add", "--detach", dir, "HEAD"]);
+    }
+    catch (e) {
+        rmSync(dir, { recursive: true, force: true });
+        throw e;
+    }
+    return { dir, repo: root };
+}
+/** Everything changed in the worktree relative to its starting commit, as one unified diff (new files included). */
+export async function worktreeDiff(w) {
+    await git(w.dir, ["add", "-A", "-N", "."]).catch(() => { }); // make new files show up in the diff without staging content
+    return (await git(w.dir, ["diff", "--no-color", "--no-ext-diff", "HEAD"])).trimEnd();
+}
+export async function removeWorktree(w) {
+    await git(w.repo, ["worktree", "remove", "--force", w.dir]).catch(() => { });
+    rmSync(w.dir, { recursive: true, force: true });
+    await git(w.repo, ["worktree", "prune"]).catch(() => { });
+}
+/** Apply a unified diff to a working tree (atomically: `git apply --check` first). Returns what failed, or undefined. */
+export async function applyDiff(cwd, diff) {
+    if (!diff.trim())
+        return undefined;
+    try {
+        await git(cwd, ["apply", "--check", "--whitespace=nowarn", "-"], diff + "\n");
+        await git(cwd, ["apply", "--whitespace=nowarn", "-"], diff + "\n");
+        return undefined;
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+/** Undo a diff that was applied with applyDiff. */
+export async function revertDiff(cwd, diff) {
+    if (!diff.trim())
+        return undefined;
+    try {
+        await git(cwd, ["apply", "-R", "--whitespace=nowarn", "-"], diff + "\n");
+        return undefined;
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+/** A named, persistent worktree on its own branch (`amness/<name>`) inside the repository's `.amness/worktrees/`, for a whole working session. */
+export async function createSessionWorktree(repo, name) {
+    const root = (await git(repo, ["rev-parse", "--show-toplevel"])).trim(), clean = name.replace(/[^\w.-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+    if (!clean)
+        throw new Error("the worktree needs a name made of letters, numbers, . _ or -");
+    const dir = join(root, ".amness", "worktrees", clean), branch = `amness/${clean}`;
+    const base = (await git(root, ["rev-parse", "HEAD"])).trim();
+    await git(root, ["worktree", "add", "-b", branch, dir, "HEAD"]);
+    return { dir, branch, repo: root, base };
+}
+/** True when nothing has changed in `dir` (no modified, staged or untracked files) and the branch has no commits beyond `base`. */
+export async function worktreeIsUntouched(dir, base) {
+    try {
+        if ((await git(dir, ["status", "--porcelain"])).trim())
+            return false;
+        const ahead = (await git(dir, ["rev-list", "--count", `${base}..HEAD`]).catch(() => "0")).trim();
+        return ahead === "0";
+    }
+    catch {
+        return false;
+    }
+}

package/docs/agent-loop.md

@@ -0,0 +1,222 @@
+# The agent loop, caching and where the design comes from
+
+This page explains how Amness runs one turn of work, which checks keep a long run safe, and where the ideas come from.
+
+In this page you will learn:
+
+- what happens, step by step, from your message to the final answer
+- which guards stop an agent that is stuck, and how to tune them
+- how the claims ledger checks the agent's final summary
+- how Amness keeps the prompt cache valid, and which sources the design follows
+
+## Words used on this page
+
+| Term | Meaning |
+|---|---|
+| Token | A small piece of text that a model reads or writes. One token is about four letters. |
+| Context window | The most text a model can read in one request. The whole conversation must fit in it. |
+| Cache | A copy of the start of your request that the provider keeps for a short time. Cached input costs much less than fresh input. |
+| Guard | A rule in the loop that watches for a problem (a repeated call, no progress) and reacts. |
+| Ledger | A record of what really happened: files edited, commands run, exit codes. |
+| Hook | A command of yours that runs at a fixed point of the loop and can block a step or add text. |
+| Subagent | A second agent that the main agent starts for one job. It has its own fresh context. |
+| Budget | A limit on tokens (and sometimes time) for a run. |
+
+## See how one turn works
+
+**What it is.** A *turn* is one pass of the loop in `run()` in `src/harness.ts`. The agent asks the model what to do, runs the tools the model asks for, and repeats until the model calls `finish` or gives a plain answer.
+
+**Why you would read this.** You can find out why a run stopped, or which guard sent a message to the model.
+
+```mermaid
+flowchart LR
+  A["steer<br/>messages typed meanwhile"] --> B["budget<br/>check"] --> C["compact<br/>supersede · elide · handoff"] --> D["model call<br/>streaming"]
+  D -->|tool calls| E["validate · approve ·<br/>schedule: reads in parallel,<br/>writes one at a time"]
+  E --> F{"all failed?"}
+  F -->|"3×: reflect, 6×: stop"| A
+  F -->|no| A
+  D -->|finish| G{"verify gate<br/>npm test"}
+  G -->|rejected + feedback| A
+  G -->|passes| H(["done"])
+```
+
+Each turn does these things in this order: steer, budget check, compaction, model call, tool calls, then the verification gate when the model calls `finish`.
+
+### Example: one turn from your message to the answer
+
+You type `Fix the failing test in src/math.ts` in the chat and press Enter. The agent edits one file, runs the tests, and finishes. The numbered steps below show where each part happens.
+
+1. **You press Enter.** `handleKey()` in `cli/tui/app.ts` calls `submit()`. If the agent is already working, `submit()` puts your text in a queue instead. The loop reads that queue in step 5.
+2. **The UI starts the turn.** `submit()` calls `dispatch()`, which calls `turn()` in `cli/tui/app.ts`. `turn()` expands `@file` mentions and resets the token budget (cap from your config, 60 minutes). It then calls `agent.chat()`.
+3. **The agent prepares the request.** `chat()` in `src/code.ts` runs the `UserPromptSubmit` hook (`promptHooks`). It adds acceptance criteria when the reviewer is on (`withContract`), adds relevant memory notes, and builds the message list. It then calls `run()` of the harness.
+4. **The loop starts a step.** `run()` in `src/harness.ts` first checks the abort signal.
+5. **Steer.** `run()` calls `o.inbox()`. In the chat this is `drainQueue()` in `cli/tui/app.ts`. Each queued message joins the conversation.
+6. **Budget.** `run()` reads `Budget.fraction` (class `Budget` in `src/harness.ts`). At 50%, 75% and 90% it appends a note. At 95% or more, or when another step would not fit, it makes a final report call and stops.
+7. **Compaction.** If the transcript is longer than `contextBudget` (default 60,000 characters), `run()` calls `supersede()` and then `compact()`. Claude models skip this step (see the cache section). Before this, `makeHandoff()` runs if a context rollover is due.
+8. **Model call.** `run()` checks for a cache break (`firstCacheBreak()`), runs the `PreModel` hook, and calls the model. Text streams to the UI through `onText`.
+9. **Tool calls.** The model asks for `edit_file` and `sh`. Inside `run()`, `exec()` checks the arguments (`validate()` in `src/schema.ts`), runs the `PreToolUse` hook, checks repeated calls (`canonicalCall()`, `findCycle()`), and asks the permission rules and you for approval. Then it runs the tool. The edit and the shell command do not run at the same time, because they can change state.
+10. **Results.** `condense()` shortens the output. `redact()` in `src/secrets.ts` masks secrets. The `PostToolUse` hook runs. For an edit, `Ledger.onEdit()` in `src/ledger.ts` records it. For a shell command, `Ledger.onCommand()` records the exit code.
+11. **Checks after the tools.** `run()` updates the read streak, `ProgressTracker.observe()` in `src/progress.ts`, and the count of turns where every call failed.
+12. **The next step.** The model sees the test result. It calls `finish` with a summary.
+13. **The finish gate.** `exec()` runs the `Stop` hook, then `Ledger.check()`, then the `verify` command (built in `createCodeAgent()` in `src/code.ts`, run with `runShell()`), then the reviewer if it is on. If all pass, the loop emits an `audit` event and a `finish` event and returns.
+14. **The answer reaches you.** `chat()` calls `memory.endTurn()` and returns. `turn()` saves the messages. Each loop event passed through `onEvent()` in `cli/tui/app.ts` into the block store (`cli/tui/blocks.ts`), and `draw()` in `cli/tui/full.ts` showed it on screen.
+
+**Limits and common problems.**
+
+- The exact step numbers differ from run to run. A plain-text answer without `finish` also ends a run, and then `finished` is `false` in the result.
+- The loop stops after `maxSteps` (the code agent uses 60 in chat and 40 otherwise, unless you set it).
+- Not every event appears in every run. Guards only speak when they fire.
+
+**Related pages.** [Architecture](architecture.md), [Library](library.md), [Why: what Amness checks](why.md).
+
+## Know what keeps long runs reliable
+
+### Scheduling of tool calls
+
+**What it is.** Read-only calls and subagent calls in one turn run at the same time, up to 5 (`MAX_PARALLEL` in `src/harness.ts`). Anything that can change state runs alone, in the order the model gave.
+
+**How to use it.** Mark your own tool `readOnly: true` or `parallel: true` in `defineTool()`. A tool can also set `concurrent`, a function that decides per call.
+
+**Limits.** The `task` tool (subagents) has its own limit of 3 running at the same time (`taskSlots` in `src/code.ts`). The rule that writing tools never overlap is tested in `test/loop.test.ts`. The limit of 3 subagents is not covered by a test that I found.
+
+### Compaction in stages, cheapest first
+
+**What it is.** Compaction makes the conversation shorter so it fits in the context window. Amness works in stages and starts with the cheapest:
+
+1. **Condense each result as it arrives** (`condense()`). It removes terminal codes and progress redraws and collapses repeated lines. If the output is still longer than 6,000 characters, it keeps the first 40%, the last 30%, and up to 25 error-like lines from the middle.
+2. **Drop repeated or expired output** (`supersede()`). An *expired* read is a read of a file that was edited afterwards. Both kinds are replaced by a short note.
+3. **Elide old tool output** (`compact()`). Output over 300 characters in older messages is replaced by a note. The last 6 messages stay intact. The cut goes down to 70% of `contextBudget` in one go.
+4. **Hand off to a fresh context** (`makeHandoff()`). The model writes a note, and the run continues from the task plus that note. For the code agent, this happens when the last prompt passes 120,000 tokens or the transcript passes 500,000 characters. You can change this with the `rollover` option.
+
+**Why.** Every change to old messages breaks the provider's cache from that point on. One large cut every few turns costs less than a small cut every turn.
+
+**Example.** Type `/loop` in the chat. It lists each model turn, the guards that fired, and how much was trimmed.
+
+**Limits.** Stages 2 and 3 do not run for models that set `appendOnly` (Claude). Stage 4 works for every provider. A hook on `PreCompact` can veto stages 2 and 3.
+
+### Post-edit check
+
+**What it is.** A fast command, such as a typecheck, that runs after every edit.
+
+**How to use it.**
+
+```
+/check npm run typecheck
+```
+
+In headless mode, use `amness run --check "npm run typecheck" "your task"`. In the library, use the `check` option.
+
+**Example.** Only a failure is shown to the model. It is appended to the edit result as `[post-edit check ... failed; fix this before moving on]`. The model sees the mistake one step after it makes it.
+
+### Guards
+
+A *guard* watches the loop. You can switch each one off with the `off` option (see the list of names below).
+
+| Guard (`off` name) | What it does |
+|---|---|
+| `loop` | Stops the same call (after normalising it) from running a third time while nothing was edited in between. Running tests again after an edit is fine. It also finds cycles: 2 to 4 different calls that repeat three times, such as an edit flipped back and forth around a test run. |
+| `nudge` | If the model says what it will do ("I'll run the tests") instead of doing it, the loop tells it to act. At most 2 times. |
+| `wrapup` | Warns 3 steps before the step cap. Adds budget notes. Makes the final report. Checks for 12 read-only turns in a row. |
+| `stuck` | After 3 turns in a row where every tool call failed, asks the model to reflect. After 6, stops the run. |
+| `stagnation` | See the next section. |
+| `compact`, `condense`, `schedule`, `ledger`, `review`, `redact` | Switch off the matching feature. |
+
+`off` takes a list of these names. The type is `Guard` in `src/harness.ts`. With `amness replay <trace.jsonl> --off loop,stuck` you can replay a recorded session with some guards off. See [Evaluating the harness](evaluation.md).
+
+### Stagnation is judged from signals you can check
+
+**What it is.** A loop that keeps acting while nothing measurable improves gets a structured reflection after 8 such turns and a clean stop after 12. The code is `ProgressTracker` in `src/progress.ts`.
+
+"Improves" means one of these:
+
+- The count of failing tests, errors or lint problems reaches a new low. Amness reads the count from output of Jest, pytest, Go, Cargo, the Node test runner, `tsc` and `eslint`, among others (`countFailures()`).
+- A file is edited for the first time.
+- An edit adds a change that is not the undo of an earlier edit.
+- The agent reads something new (counted at most 15 times per run).
+
+The model's own confidence counts for nothing.
+
+**How to tune it.** Set `stagnationTurns` (default 8; the stop comes at 8 plus half of 8, which is 12). Set it to `0`, or use `off: ["stagnation"]`, to switch it off. Tested in `test/progress.test.ts`.
+
+**Limits.** The count is read from text output. If a tool prints failures in a format Amness does not know, it falls back to the exit code and counts 1 failure.
+
+### The claims ledger checks the final summary
+
+**What it is.** The ledger (`Ledger` in `src/ledger.ts`) records what really happened: which files were edited, which commands ran, and their exit codes. When the model calls `finish`, `Ledger.check()` compares the summary with this record.
+
+**What it checks.**
+
+- "All tests pass" needs a passing test run after the last edit.
+- "The build is clean" needs a successful build, typecheck or lint after the last edit. A passing test run also counts.
+- A file named as changed must have been edited. This check is skipped if a shell command wrote files (`sed -i`, `>`, `mv` and similar).
+- If your `verify` command already gates `finish`, the test and build claims are not checked a second time.
+
+A mismatch is rejected with the reason. This happens at most twice, so it cannot lock the loop. After that, the loop accepts the summary and records a `Ledger` hook event.
+
+**Example.** Accepted runs end with an `audit` event: files changed, whether tests passed after the final edit, and notes. A note appears when test files changed although your task did not mention tests, when more than 8 files changed, or when no test command ran. Tested in `test/ledger.test.ts`.
+
+**Limits.** The checks use word patterns in English. A summary in another language, or an unusual test command, may not match. You can tell the ledger your own test command through `verify` or `check`. Agents that judge their own work accept plausible progress as real progress ([When Do Agent Loops Mistake Stagnation for Progress?](https://arxiv.org/abs/2607.25152)). The ledger is a cheap outside check.
+
+### Independent reviewer (opt-in)
+
+**What it is.** A second agent in a fresh context. It writes acceptance criteria before the work (at most 7) and checks the diff before `finish` is accepted.
+
+**Why.** Builders overpraise their own work, and a separate judge is easier to make sceptical than a builder is to make self-critical ([Anthropic's long-running harness write-up](https://www.anthropic.com/engineering/harness-design-long-running-apps)).
+
+**How to use it.** Type `/reviewer on` in the chat, or add `--review` to `amness run`.
+
+**Details.**
+
+- The reviewer can read files and run only the project's own test, build and lint commands. It cannot edit.
+- It runs after the ledger and after your `verify` command.
+- Findings go back to the builder. After two rounds the work is accepted and flagged. A verdict that cannot be used never blocks.
+- It can use another model: `review: { model }`.
+
+**Limits.** It costs extra model calls. The number per task is not verified here. It is off by default. To measure it, run `amness eval --variants full,full+review`. See [Evaluating the harness](evaluation.md).
+
+### Done means verified
+
+`finish` passes through your `verify` gate (for example your tests or build). It is rejected with feedback until the command exits with 0.
+
+## Understand the prompt cache
+
+**What it is.** Cached input costs a fraction of fresh input. Amness keeps the start of each request identical from turn to turn so the cache stays valid.
+
+**What Amness does.**
+
+- **Append-only by default.** Old messages change only when the window needs it, in one cut well below the budget. New information (steering messages, memory notes) goes at the end.
+- **Claude is append-only always.** The Claude adapter sets `appendOnly`, so the harness never edits past turns for Claude (`src/anthropic.ts`, `src/harness.ts`). Context rollover still works.
+- **Stable request shape.** Tool definitions are sorted by name. The memory index is added once per conversation. OpenAI requests carry a `prompt_cache_key` and ask for `24h` cache retention. If a model refuses these fields, the adapter drops them (`src/openai.ts`).
+- **Keep-alive (opt-in).** Claude drops a cached prefix after about 5 idle minutes. `/keepwarm on` re-sends the conversation with a 16-token output cap after 270 seconds of idle time, at most 3 times per break. This costs a cache read instead of a cold read. It is off by default because it spends tokens while you are away. It applies to Claude only.
+- **You can see it.** `/loop` marks every turn where the start of the request changed (for example "earlier history was rewritten at message 14" or "the tool list changed"). The usage panel shows the cache hit rate. `amness eval` reports it per variant.
+
+**Limits and common problems.**
+
+- A change in the tool list, such as a mode switch or a loaded tool, breaks the whole cache once.
+- The cost effect of these choices is from the papers below. Amness has not measured it on a real model yet.
+
+**Related pages.** [Budgets and subagents](budgets.md), [Providers and models](providers.md).
+
+## Learn where these choices come from
+
+Recent work on coding-agent loops points the same way. The loop follows it where this can be done without training a model.
+
+- [An Empirical Study of Harness Design for Coding Agents](https://arxiv.org/abs/2609.20804) (2026): cheap rule-based elision before any LLM summary gave the lowest cost. A recall tool for elided content was almost never used, so Amness has none. Stuck detection and light post-edit checks are cheap ways to stop wasted turns.
+- [AgentDiet](https://arxiv.org/abs/2509.23586) (trajectory reduction): removing useless, redundant and *expired* information cut input tokens by 40-60% with unchanged results. This is the source of the expired-read and repeated-call rules.
+- [CoACT](https://arxiv.org/abs/2607.02911) and [SWE-Pruner](https://arxiv.org/abs/2601.16746): reads use most of the tokens. Compression must keep what the next action needs, and earlier messages stay untouched so the cache stays valid. Amness uses rules for this. The papers use trained compressors, which would add a dependency.
+- [Don't Break the Cache](https://arxiv.org/abs/2601.06007) (prompt caching for long-horizon agents): caching cut API cost by 41-80% across OpenAI, Anthropic and Google, but naive full-context caching can hurt. Put dynamic content at the end, avoid dynamic tool lists, and keep dynamic tool results out of the cached prefix. [Keeping the Cache Warm Pays](https://arxiv.org/abs/2607.19214) motivates the longer OpenAI retention and the opt-in Claude keep-alive.
+- Memory: [Infini Memory](https://arxiv.org/abs/2606.10677) (plain-text topic documents, lexical retrieval, merge and split maintenance, recency resolves contradictions; its structural maintenance mattered most in its ablations), [REALM](https://arxiv.org/abs/2609.16053) (retrieval feeds back into how memory is organised, which is why Amness records use and ranks by it) and the strategic-forgetting work ([SF-AMS](https://arxiv.org/abs/2607.22562), [FSFM](https://arxiv.org/abs/2604.20300)). Amness uses plain files: word-based retrieval plus optional embeddings, merge maintenance (`/memory consolidate`), a light note graph, ranking by outcome, and forgetting you can undo. "Learning" here means simple counts (wins and losses per note), not a trained model. There is no graph database.
+- A [source-code study of eleven coding agents](https://arxiv.org/html/2609.00006v1): read-only tools run at the same time, tools that change things run one at a time.
+
+The percentages above are the papers' results on their own benchmarks. They are not measurements of Amness. Use the eval runner (`evaluate`) with the guards switched on and off to measure them on your own tasks. Whether a source was read in full or only seen as a search snippet is marked on [Budgets and subagents](budgets.md).
+
+## Know what the budget does to the loop
+
+The loop also watches the token budget: notes at 50%, 75% and 90%, a final report instead of a bare stop, a check for 12 read-only turns, and slices for subagents. These are explained, with sources, in [Budgets and subagents](budgets.md). They are tested with scripted models. Whether they reduce exhausted runs on real tasks is not measured.
+
+## Next steps
+
+- [Budgets and subagents](budgets.md): choose a budget and read the budget notes.
+- [Architecture](architecture.md): see which file does what.
+- [Evaluating the harness](evaluation.md): measure a guard on your own tasks.
+- [Plugins](plugins.md): add your own loop rules.

package/docs/architecture.md

@@ -0,0 +1,228 @@
+# Architecture
+
+Amness has three layers: a terminal interface, an agent, and a loop called the harness. This page shows how they connect and which file does what.
+
+In this page you will learn:
+
+- how the layers depend on each other
+- which file in `src/` and `cli/` you should open for a given job
+- how the full-screen interface draws a frame
+
+## Find your way around the layers
+
+**What it is.** The layers depend on each other in one direction only. The **UI** (`cli/`) drives the **agent** (`src/code.ts`, `src/deep.ts`). The agent is built on the **harness** (`src/harness.ts`). Models are plain functions that you pass in from outside.
+
+**Why it matters.** The harness and the agents do not import the UI. So everything in `src/` works as a library. See [Use it as a library](library.md).
+
+```
+  you (keyboard, mouse)
+        |
+  +-----v--------------------------------------------+
+  | UI layer          cli/                           |
+  |   amness.ts  ->  tui/app.ts  ->  full.ts / screen.ts
+  +-----+--------------------------------------------+
+        |  prompts go down, events come up
+  +-----v--------------------------------------------+
+  | Agent layer       src/code.ts   src/deep.ts      |
+  |   coding agent, tools, subagents, memory         |
+  +-----+--------------------------------------------+
+        |
+  +-----v--------------------------------------------+
+  | Harness layer     src/harness.ts                 |
+  |   run(): steer, budget, compact, model, tools,   |
+  |   verify. Guards: ledger.ts, progress.ts         |
+  +-----+--------------------------------------------+
+        |  model(messages, tools) -> message
+  +-----v--------------------------------------------+
+  | Model adapters    src/openai.ts  src/anthropic.ts|
+  |   or any function with the same shape            |
+  +--------------------------------------------------+
+```
+
+The same picture with more detail:
+
+```mermaid
+flowchart TB
+  subgraph UI["cli/ : terminal interface"]
+    direction TB
+    entry["amness.ts<br/>chat · run · menu · demo"]
+    app["tui/app.ts<br/>App: input, modes, approvals,<br/>slash commands, sessions"]
+    full["Full-screen view<br/>full.ts · cards · sidebar · modal<br/>canvas · themes · blocks"]
+    inline["Inline view<br/>screen.ts · view.ts"]
+    entry --> app
+    app --> full
+    app --> inline
+  end
+  subgraph AGENT["src/ : agents"]
+    code["code.ts<br/>coding agent + file/shell tools"]
+    deep["deep.ts<br/>research agent + subagents"]
+  end
+  subgraph CORE["harness.ts : the loop"]
+    loop["run(): steer → budget → compact →<br/>model → schedule tools → verify"]
+    reg["Registry<br/>deferred tools · MCP"]
+  end
+  subgraph MODELS["model adapters"]
+    oa["openai.ts<br/>Responses + Chat Completions"]
+    an["anthropic.ts<br/>Claude"]
+    local["any (messages, tools) → message"]
+  end
+  subgraph STATE["state"]
+    mem["memory.ts<br/>ranked, learning notes<br/>embed.ts: optional vectors"]
+    bundle["bundle.ts<br/>portable sessions"]
+    sess["cli/tui/session.ts<br/>chats + checkpoints"]
+  end
+  app -->|"events up, prompts down"| code
+  code --> loop
+  deep --> loop
+  loop --> reg
+  loop -->|"model(messages, tools)"| oa
+  loop --> an
+  loop --> local
+  code --> mem
+  app --> sess
+  app --> bundle
+  ev["evals.ts + stats.ts<br/>variants, bootstrap, sign test"] --> code
+  evcli["cli/evalcli.ts<br/>amness eval"] --> ev
+```
+
+**Limits.** The diagrams show the main paths only. Many small files in `src/` (for example `permissions.ts`, `hooks.ts`, `sandbox.ts`) are called by the agent layer and are not drawn.
+
+The runtime has no required packages. The Claude adapter needs the optional package `@anthropic-ai/sdk`.
+
+## Find which file does what
+
+The table lists every file in `src/` and `cli/`. The text comes from the first comment lines of each file. Open the file for details.
+
+### `src/` : agent, harness and helpers
+
+| File | What it does |
+|---|---|
+| `src/harness.ts` | The agent loop and its guards. Also `Registry` (the tools), `Budget`, `extract()` and the compaction functions. |
+| `src/code.ts` | The coding agent: file and shell tools, the `task` tool for subagents, todos, plan mode, permission modes. |
+| `src/deep.ts` | The research agent with subagents and an in-memory file system. |
+| `src/index.ts` | The library entry point. It re-exports the other modules. |
+| `src/openai.ts` | Adapter for OpenAI and OpenAI-compatible servers (Responses and Chat Completions APIs). |
+| `src/anthropic.ts` | Adapter for Claude through the official Anthropic SDK. |
+| `src/route.ts` | Roles that use different models (explore, compact, review) and a fallback chain when a provider is overloaded. |
+| `src/router.ts` | Per-step routing between a strong and a cheap model, with the prompt-cache cost in the decision. |
+| `src/ratelimit.ts` | A shared gate that keeps requests under the provider's per-minute limits. See [Budgets](budgets.md#rate-limits-requests-and-tokens-per-minute). |
+| `src/ledger.ts` | The claims ledger: records edits and commands and checks the final summary. |
+| `src/progress.ts` | Stagnation detection from objective signals (failing-test counts, new edits). |
+| `src/review.ts` | The independent reviewer: acceptance criteria before the work, a check before it is accepted. |
+| `src/approver.ts` | An optional second opinion on risky calls, from a cheaper model. It can approve but not refuse. |
+| `src/permissions.ts` | Permission rules and the safety floor that holds in every mode. |
+| `src/hooks.ts` | Lifecycle hooks: your commands at fixed points of the loop. |
+| `src/plugins.ts` | Plugins: harness behaviour written as code (tools, hooks, eval tasks, variants). |
+| `src/sandbox.ts` | OS-level sandbox for shell commands (Seatbelt on macOS, Bubblewrap on Linux). |
+| `src/snapshot.ts` | Reversible shell commands: records the working tree as a git tree object before a command runs. |
+| `src/secrets.ts` | Masks secrets in tool output before the model sees it. |
+| `src/shell.ts` | Chooses which shell runs commands (a POSIX shell, including on Windows). |
+| `src/procs.ts` | Background processes: start a server, read its output later, stop it. |
+| `src/schema.ts` | A small JSON-schema checker and a tolerant JSON parser for model output. |
+| `src/patch.ts` | Multi-file patches, applied all or nothing. |
+| `src/diff.ts` | A line diff that makes unified hunks. |
+| `src/lsp.ts` | Language-server diagnostics after edits. |
+| `src/codeindex.ts` | A structural index of the repository: symbols, imports and where symbols are used. |
+| `src/guidance.ts` | Loads project instruction files (`AGENTS.md`, with `CLAUDE.md` and `GEMINI.md` as fallbacks). |
+| `src/skills.ts` | Skills: folders with a `SKILL.md` that the model loads when needed. |
+| `src/agents.ts` | Custom subagents defined as markdown files. |
+| `src/memory.ts` | Memory: ranked notes, merging, a light graph, learning from outcomes, an archive. |
+| `src/embed.ts` | Optional embeddings for memory search. |
+| `src/bundle.ts` | Portable session bundles: handoff note, memory and changed files. |
+| `src/dynamic.ts` | Tools the agent defines as shell commands, and the live tool registry (MCP). |
+| `src/images.ts` | Reads an image file for models that accept images. |
+| `src/web.ts` | Web search and URL fetch tools. |
+| `src/worktree.ts` | Git worktrees: an isolated copy of the repository for an agent. |
+| `src/parallel.ts` | Several agents at once, each in its own worktree (best-of-N and parts). |
+| `src/gitflow.ts` | Review and pull-request helpers around git and the GitHub CLI. |
+| `src/live.ts` | Live view of a run in the browser, on `127.0.0.1` only. |
+| `src/acp.ts` | Agent Client Protocol server, so an editor can host Amness. |
+| `src/schedule.ts` | Recurring headless runs through cron lines. |
+| `src/trace.ts` | Tracing: every loop event goes to a local JSONL file, and optionally to an OpenTelemetry collector. |
+| `src/replay.ts` | Replays a recorded trace through the current harness without a model or tools. |
+| `src/mining.ts` | Failure mining: groups failures from traces and turns one into an eval task. |
+| `src/evals.ts` | The eval runner: variants and ablations. |
+| `src/evalcases.ts` | Small built-in eval tasks and a loader for your own cases. |
+| `src/hardcases.ts` | Harder built-in eval tasks. |
+| `src/suites.ts` | Public-benchmark style suites (SWE-bench format) as eval cases. |
+| `src/stats.ts` | Small statistics for comparing variants. Tasks are the unit of analysis. |
+| `src/profiles.ts` | Harness profiles: settings that depend on the model. |
+| `src/tune.ts` | `amness tune`: bounded changes to the harness settings, kept only if they hold on unseen tasks. |
+
+### `cli/` : the command line and the terminal interface
+
+| File | What it does |
+|---|---|
+| `cli/amness.ts` | The entry point: chat (default), headless `run`, the classic menu, `demo`. It picks the full-screen or inline view. |
+| `cli/headless.ts` | Non-interactive mode for CI, scripts and containers: `amness run`. |
+| `cli/config.ts` | Reads and writes the configuration file. |
+| `cli/model.ts` | Builds the model for a configuration. All models for one endpoint and key share one rate-limit gate. |
+| `cli/detect.ts` | Guesses the command that proves the project works (the finish gate). |
+| `cli/state.ts` | Small remembered state: last project, verify command per project, task history. |
+| `cli/format.ts` | One readable trace line per harness event. |
+| `cli/ui.ts` | A small terminal UI without dependencies: colours, boxes, menus, prompts, spinner. |
+| `cli/demo.ts` | The guided demo: a scripted model that makes mistakes so every guard fires. No API key. |
+| `cli/evalcli.ts` | `amness eval`: compare harness variants with statistics. |
+| `cli/schedulecli.ts` | `amness schedule`: recurring headless runs through cron. |
+| `cli/acpcli.ts` | `amness acp`: serve the Agent Client Protocol on stdin and stdout. |
+
+### `cli/tui/` : the chat interface
+
+| File | What it does |
+|---|---|
+| `cli/tui/app.ts` | The `App`: one persistent conversation with input box, streaming output, approvals and slash commands. |
+| `cli/tui/commands.ts` | The slash commands. |
+| `cli/tui/custom.ts` | Your own slash commands, from markdown files. |
+| `cli/tui/complete.ts` | Autocomplete for `/commands` and `@file` mentions. |
+| `cli/tui/mentions.ts` | Turns `@path` mentions into attached file contents. |
+| `cli/tui/editor.ts` | The multi-line input editor, as a state machine with no terminal input or output. |
+| `cli/tui/keys.ts` | Turns raw terminal input into key events (keys, mouse, paste). |
+| `cli/tui/session.ts` | Saves conversations per project and handles undo and rewind of file changes. |
+| `cli/tui/blocks.ts` | The retained transcript: structured blocks that the full-screen view draws from. |
+| `cli/tui/full.ts` | The full-screen view: header, transcript, sidebar, input, modals, toasts and mouse handling. |
+| `cli/tui/cards.ts` | Card renderers: each transcript block becomes rows of styled cells. |
+| `cli/tui/sidebar.ts` | The right-hand panel with the state of the session. |
+| `cli/tui/modal.ts` | Modal dialogs for the full-screen view. |
+| `cli/tui/overlays.ts` | Pieces drawn in place of the input box in the inline view: choices, pickers, help. |
+| `cli/tui/canvas.ts` | A grid of character cells. `flush()` writes only the cells that changed. |
+| `cli/tui/ansi.ts` | Converts between ANSI strings and styled cells. |
+| `cli/tui/rich.ts` | Row-building helpers and the markdown style for the full-screen view. |
+| `cli/tui/themes.ts` | The colour themes for the full-screen view. |
+| `cli/tui/theme.ts` | Colour support for the inline view (truecolor, 256, 16, none). |
+| `cli/tui/brand.ts` | Provider and model symbols, and the logo. |
+| `cli/tui/diffview.ts` | The diff viewer: line numbers, tints, syntax colours, split layout. |
+| `cli/tui/markdown.ts` | Converts markdown to ANSI lines for assistant messages. |
+| `cli/tui/text.ts` | Text basics: strip ANSI, display width, wrapping. |
+| `cli/tui/screen.ts` | The inline renderer: finished output goes to normal scrollback, and a small live region at the bottom is redrawn. |
+| `cli/tui/view.ts` | Pure rendering helpers for the chat UI. They return lines and never touch the terminal. |
+| `cli/tui/pager.ts` | The full-transcript viewer (Ctrl+O). |
+| `cli/tui/clipboard.ts` | Copies text to your clipboard (OSC 52 and the platform tool). |
+| `cli/tui/pricing.ts` | Rough price and context-window tables for the footer. They are estimates. |
+| `cli/tui/tokens.ts` | The "where did my tokens go" report. |
+
+## Understand how the full-screen interface draws
+
+**What it is.** The full-screen view draws the whole screen from one grid of cells.
+
+**How it works.**
+
+1. Agent events reach `App.onEvent()` in `cli/tui/app.ts`. They are written into the block store (`BlockStore` in `cli/tui/blocks.ts`).
+2. Each block is drawn into rows of styled cells (`cli/tui/cards.ts`). `cli/tui/full.ts` keeps the result in a cache and reuses it while the block's signature is the same.
+3. `draw()` in `cli/tui/full.ts` places the header, transcript, sidebar, status line, input and footer on a `Canvas`. The sidebar shows only when the terminal is at least 104 columns wide.
+4. `Canvas.flush()` in `cli/tui/canvas.ts` returns only the cells that changed since the last frame. `draw()` wraps that text in synchronized-output markers (`ESC[?2026h` and `ESC[?2026l`), so you do not see a half-drawn frame.
+5. While the view runs, it turns on the alternate screen, mouse reporting (SGR 1006) and bracketed paste. It turns them off on exit. Copying uses OSC 52.
+6. When you resize the terminal, `invalidate()` clears the cache and forces a full repaint.
+
+The inline renderer (`cli/tui/screen.ts`) uses the same `App` and the same agent events. Both views show the same behaviour.
+
+**Limits and common problems.**
+
+- Synchronized output and OSC 52 depend on your terminal. If your terminal ignores them, you may see flicker or copying may not reach your clipboard. Not verified on every terminal.
+- Tests for the canvas, keys and full-screen view are in `test/tui-canvas.test.ts`, `test/tui-keys.test.ts` and `test/tui-full.test.ts`.
+
+## Next steps
+
+- [The agent loop](agent-loop.md): follow one turn through these files.
+- [Use it as a library](library.md): use `src/` without the UI.
+- [Plugins](plugins.md): add behaviour as code.
+- [Development and limitations](development.md): run the tests.