@loops-adk/core 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,18 @@
-# loops
-
-**Stop prompting agents. Write the loop that prompts them. Make "done" mean _converged_, not _claimed_.**
+<p align="center">
+  <img src="assets/logo.png" alt="loops" width="320">
+</p>
+
+<p align="center">
+  <strong>Stop prompting agents. Write the loop that prompts them. Make "done" mean <em>converged</em>, not <em>claimed</em>.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@loops-adk/core"><img src="https://img.shields.io/npm/v/@loops-adk/core" alt="npm"></a>
+  <img src="https://img.shields.io/badge/status-alpha-orange" alt="status: alpha">
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6" alt="TypeScript">
+  <img src="https://img.shields.io/badge/node-%3E%3D20-3c873a" alt="node &gt;=20">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="license: MIT">
+</p>
 
 `loops` is a small, nestable library for running an agent in a convergence loop. The loop finds the work, hands it to an agent, checks the result, records what it learned, and goes again until a gate _you_ define says the work is finished. You write the loop once and it drives the agent, rather than prompting the agent by hand. Compose loops and DAGs both ways, run them against any model behind a one-method `Engine`, and watch a run in a live terminal UI.
 
@@ -8,10 +20,31 @@ Every iteration runs with a **fresh context**, so a long run never rots. Progres
 
 Where most "agent memory" recalls a _conversation_, this keeps your _decisions_ consistent across long work. No vector database, no embeddings, no index to sync or let go stale. **Git is the memory.**
 
-![status: alpha](https://img.shields.io/badge/status-alpha-orange)
-![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)
-![node >=20](https://img.shields.io/badge/node-%3E%3D20-3c873a)
-![license MIT](https://img.shields.io/badge/license-MIT-blue)
+## The fastest proof
+
+A downstream agent had to preserve one upstream decision: snapshots must start
+with the exact wire tag `SSv1|`. That decision lived only in a git commit body,
+not in the source files or the downstream task prompt. The commit was not just a
+fact store; it was the thread back through the journey, what was decided, why it
+was decided, and what downstream work had to honour.
+
+| Runner | What it could read | Result |
+| --- | --- | --- |
+| Memoryless graph | files plus task prompt | 0/10 preserved the contract |
+| Loops Ledger | gated commit bodies plus grounding | 9/10 preserved the contract |
+| Raw git dump | full git log pasted into every prompt | 10/10 on a toy log, not a real-repo operating mode |
+
+That is the honest shape of the claim. Loops is not just `git log`: it is the
+deterministic enforcement layer that makes agents write useful commit bodies when
+work converges, then the grounding layer that reads those verified reasons back
+into later fresh contexts. The value is not bare recall. A fresh agent can pull
+on one thread and reconstruct how and why the repository got here. Full-log dump
+is a useful sanity check on tiny histories, but on a repo with significant
+history it is context rot and cost.
+
+```bash
+npm run bench:compare
+```
 
 ```ts
 import { loop, agentJob, commandSucceeds, agentCheck } from '@loops-adk/core';
@@ -151,6 +184,7 @@ loops run \
 ```bash
 loops validate examples/confidence-gate.loop.ts      # offline pre-flight: load + print the shape, no model calls
 loops describe examples/confidence-gate.loop.ts      # print the loop's shape (gate, body, nodes) without running
+loops describe examples/confidence-gate.loop.ts --json # machine-readable shape for agents
 loops run examples/confidence-gate.loop.ts           # live Ink TUI
 loops run examples/confidence-gate.loop.ts --no-tui  # plain streamed logs
 loops run examples/confidence-gate.loop.ts --json    # NDJSON event stream
@@ -160,6 +194,19 @@ loops run examples/confidence-gate.loop.ts --json    # NDJSON event stream
 
 **Authoring is agent-native.** Both commands work from any repo, including one that consumes `loops` as a submodule or dependency (the recipe's folder just needs an ES module scope, which such repos already have). `loops validate <file>` is the cheap, no-model pre-flight an agent runs before `loops run`: it loads the loop, reports a fix-oriented error if anything is wrong, and prints the loop's shape (its gate, body, and dag nodes), all without spending a single agent turn. `loops describe <file>` prints that same shape on its own, so an agent can see exactly what it just authored. The authoring guide an agent reads to compose a loop is [`skills/author-loop/SKILL.md`](skills/author-loop/SKILL.md).
 
+The end-to-end agent workflow, from authoring through reading a supervised run's decisions back as structured records rather than a raw event stream:
+
+```bash
+loops validate feature.loop.ts --json                 # pre-flight: loads, no spend
+loops describe feature.loop.ts --json                 # the shape, incl. each agent node's contract
+loops run feature.loop.ts --no-tui --supervise        # run it, registered for observation
+loops list                                            # find the runId
+loops tail <runId>                                    # follow live events
+loops records <runId> --kind revision --path ship/implementation --json  # the semantic decision stream, filtered
+```
+
+Two supervision skills go deeper: [`skills/supervise-loop-run/SKILL.md`](skills/supervise-loop-run/SKILL.md) (monitor a run) and [`skills/design-agent-team/SKILL.md`](skills/design-agent-team/SKILL.md) (compose a specialist team).
+
 **Offline demo** (no network, no key; uses the mock engine):
 
 ```bash
@@ -276,10 +323,10 @@ The agent launch only ever touches the `Engine` interface, so the loop knows not
 
 | name            | backend                          | notes                                                       |
 | --------------- | -------------------------------- | ----------------------------------------------------------- |
-| `claude-cli`    | `claude` subprocess (`execa`)    | fresh process per call; uses host Claude auth, no key       |
-| `agent-sdk`     | `@anthropic-ai/claude-agent-sdk` | fresh `query()` per call; host Claude auth                  |
-| `anthropic-api` | `@anthropic-ai/sdk`              | token-level streaming; cheapest for judges; needs a key     |
-| `codex`         | `codex exec` subprocess (GPT-5)  | a genuinely different model for a second-model reviewer; read-only |
+| `codex`         | `codex exec` subprocess (`execa`) | fresh process per call; read-only unless `bypassPermissions` |
+| `claude-cli`    | `claude` subprocess (`execa`)     | fresh process per call; uses host Claude auth, no key        |
+| `agent-sdk`     | `@anthropic-ai/claude-agent-sdk`  | fresh `query()` per call; host Claude auth                   |
+| `anthropic-api` | `@anthropic-ai/sdk`               | token-level streaming; cheapest for judges; needs a key      |
 | `mock`          | scripted, offline                | for tests and examples                                      |
 
 Select per-run (`--engine`, `RunOptions.engine`) or per-job/condition (`engine:` takes a name **or** a ready-made `Engine`). Bring your own in ~10 lines:
@@ -314,15 +361,23 @@ const storeEngineer = defineAgent({
   system: fromFile(new URL('./agents/store-engineer.md', import.meta.url)), // the persona, as markdown
   model: 'sonnet',
   tools: ['edit', 'bash'],
+  tier: 'worker',
   capabilities: ['storage engine', 'id stability'],
+  outputs: [{ name: 'patch' }, { name: 'test-report' }],
+  requiresSkills: ['contract-first'],
   skills: [tdd],                                  // methodologies fold into the system
+  usesSkills: ['small-diff'],
+  humanGates: [{ name: 'prod-approval', when: 'deploying production changes' }],
   failureModes: [{ mode: 'tests-flaky', recovery: 'isolate the flake, retry once' }],
 });
 
 agentJob({ agent: storeEngineer, prompt: 'Build the store to its tests.', ground: true });
 ```
 
-`agentJob` resolves the def into the engine request (`system` = persona + skills, plus `model`/`tools`); inline `system`/`model`/`tools` still override it. A **skill** is a methodology (how to work: TDD, writing-plans), not a worker. This is what turns a `dag` into a named **team** (`storeEngineer`, `apiEngineer`, `securityReviewer` as small files) orchestrated by the DAG and gated by `quorum(...)`.
+For a small runnable contract plus feedback example, see
+[`examples/contracted-agent.loop.ts`](examples/contracted-agent.loop.ts).
+
+`agentJob` resolves the def into the engine request (`system` = persona + skills, plus `model`/`tools`); inline `system`/`model`/`tools` still override it. A **skill** is a methodology (how to work: TDD, writing-plans), not a worker. The extra contract fields are optional metadata for validation, `loops describe`, docs, and future discovery. They do not give an agent dispatch authority. This is what turns a `dag` into a named **team** (`storeEngineer`, `apiEngineer`, `securityReviewer` as small files) orchestrated by the DAG and gated by `quorum(...)`.
 
 ## Environments: test the running thing
 
@@ -381,6 +436,43 @@ dag({
 
 `needs` = dependencies; a non-`pass` required dependency blocks its dependents; `optional` nodes never block or fail the DAG; an unmet `when` skips a node (counts green); cycles are detected before any work runs. `sequence(name, ...jobs)` and `parallel(name, jobs, concurrency?)` are sugar over `dag`.
 
+### Feedback between nodes
+
+Review feedback is a structured revision request. In a loop, a failing `review`
+outcome is threaded into the next body turn as `ctx.lastReview`; with
+`consumeFeedback: true`, `agentJob` appends it to the implementation prompt in a
+standard block.
+
+```ts
+const implement = agentJob({
+  label: 'implementation',
+  prompt: brief,
+  consumeFeedback: true,
+});
+```
+
+For several reviewers, use `reviewPanel` to aggregate their verdicts into one
+outcome. Every reviewer is a gate: the panel passes when all of them clear (or
+`pass: N` of them, k-of-n), and each failing reviewer's concern is surfaced as a
+blocking finding threaded into the next pass. An empty panel is a construction
+error, not a vacuous pass.
+
+```ts
+const review = reviewPanel({
+  // pass: 2,  // optional: k-of-n instead of all
+  reviewers: [
+    { name: 'security', review: agentCheck({ question: 'Is it safe?', context: reviewContext({ diff: true, ledger: true }) }) },
+    { name: 'correctness', review: agentCheck({ question: 'Is it correct?' }) },
+    { name: 'simplicity', review: agentCheck({ question: 'Is it simple?', context: reviewContext({ files: ['src/**'] }) }) },
+  ],
+});
+```
+
+In a DAG, a targeted `revisionRequest({ target, findings })` reruns the target
+node and its dependents when `maxKickbacks` allows it. `kickback(to, reason)` is
+the terse compatibility helper for the same routed feedback. Agents can opt into
+a small graph-position prompt block with `graphContext: true`.
+
 **Worktree isolation: branches as teams.** A concurrent node can run in its own git worktree on a fork branch (`isolation: 'worktree'` on the DAG, or `isolate: true` per node), so parallel writers never collide on files or the index. On pass, its committed work lands back into the line with a `--no-ff` merge; a conflict fails the node honestly (loops does not auto-resolve; that's a separate layer). Each team gets its own branch, its own scratch files, and (with `DagConfig.environment`) its own stage, all born and torn down together.
 
 For **dynamic** dispatch (a loop that discovers each unit at runtime and routes it to its own isolated sub-loop), `isolated(job)` is the same boundary as a composable wrapper rather than a predeclared node (fork, run, land back on pass):
@@ -447,6 +539,19 @@ The error taxonomy backs this: an engine classifies a throttle into a `RATE_LIMI
 
 Every mode ends with a summary: result, per-loop iterations, review tallies, token usage by model, and any errors.
 
+## Supervise a running loop
+
+Run with `--supervise` and the loop registers itself under `~/.loops/runs/`, writing its live state there as it goes. Another process reads it with no daemon and no socket, because the filesystem is the channel (the same bet the rest of the library makes).
+
+```bash
+loops run build.loop.ts --supervise   # in one terminal
+loops list                             # in another: every supervised run, with state and iteration
+loops status <runId>                   # its shape plus where it is now: iteration, last gate verdict, tokens
+loops tail <runId>                     # stream its events live
+```
+
+Each run keeps the raw event stream in `events.jsonl` and a smaller semantic stream in `semantic.jsonl` with dispatch, completion, surfacing, `revision-emitted`, and `revision-routed` records. Use `loops records <runId>` to inspect those records without knowing the registry path; add `--kind revision-routed`, `--kind revision` (both revision kinds), `--path ship/implementation`, `--since <time>`, `--last <n>`, or `--json` when an agent needs a filtered machine-readable stream. `list` marks a run dead if its process is gone. The read side is also on the public surface (`listRuns`, `readRunStatus`, `runEventsPath`, `runSemanticRecordsPath`), so an agent supervising a fleet of loops, killing the ones that drift and kicking work back into the ones that hit a problem, reads the same files. Out-of-process control (pause, abort, and kickback from outside) is the next step.
+
 ## What `loops` is (and isn't)
 
 `loops` is a **fresh-context loop primitive**, not a durable workflow engine. The design bet is that **the workspace is the state**: progress _and its reasoning_ live in git (the Ledger), so each iteration can start clean and still know what came before. If the process dies mid-run, you re-run against the same workspace (the worktree holds the files, the scratch files hold the why, the log holds the milestones) and continue. You lose the bookkeeping, not the work.
@@ -464,7 +569,9 @@ It deliberately does **not** do durable mid-run replay (re-running a half-finish
 - [x] **Ledger**, git-memory core: the scratch files (working memory + handoff), grounding, milestone commits
 - [x] Worktree isolation (branches-as-teams) with `--no-ff` land-back
 - [x] Environment axis: provider interface + offline mock
-- [ ] Publish to npm (with a built `dist` + `exports`)
+- [x] Publish to npm (`@loops-adk/core`, built `dist` + types, CI release)
+- [x] Supervision: a file-based run registry with `loops list` / `status` / `tail`
+- [ ] Out-of-process control: `pause` / `abort` / `kickback` a running loop from outside
 - [ ] Optional `wip:` autosave tier (per-iteration recovery, squashed on convergence)
 - [ ] No-progress / stall detection: the third hard stop, alongside `max` and `budget`
 - [ ] `cost per accepted change` as a first-class reported metric

package/bin/loops.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // Thin launcher. Registers tsx's ESM loader globally so the CLI can transform a
 // user's `.loop.ts` recipe from any repo (the run-from-anywhere contract), then
-// hands off to the CLI. In a published install loops' own code is the built
-// `dist/`; running from source (this repo, no build step) falls back to the
-// TypeScript entry, which the same tsx loader transforms.
+// hands off to the CLI. From a checkout the TypeScript source is the entry (the
+// no-build-step dev path); a published install ships no `src`, so it falls back
+// to the built `dist`. Source wins so a stale `dist` never shadows live code.
 import { existsSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -11,6 +11,6 @@ import { register } from 'tsx/esm/api';
 
 register();
 const here = dirname(fileURLToPath(import.meta.url));
-const dist = join(here, '..', 'dist', 'index.js');
-const entry = existsSync(dist) ? dist : join(here, '..', 'src', 'index.ts');
+const src = join(here, '..', 'src', 'index.ts');
+const entry = existsSync(src) ? src : join(here, '..', 'dist', 'index.js');
 await import(pathToFileURL(entry).href);

package/dist/{agent-sdk-RF5VJZAT.js → agent-sdk-4QJDWM7N.js}

@@ -1,5 +1,5 @@
 import { newAccumulator, mapMessage } from './chunk-CXEPZHSR.js';
-import { SUBAGENT_TOOLS } from './chunk-XC46B4FD.js';
+import { SUBAGENT_TOOLS } from './chunk-MA6NDQMO.js';
 import { LoopError } from './chunk-I3STY7U6.js';
 import pTimeout from 'p-timeout';
 
@@ -91,5 +91,5 @@ var AgentSdkEngine = class {
 };
 
 export { AgentSdkEngine };
-//# sourceMappingURL=agent-sdk-RF5VJZAT.js.map
-//# sourceMappingURL=agent-sdk-RF5VJZAT.js.map
+//# sourceMappingURL=agent-sdk-4QJDWM7N.js.map
+//# sourceMappingURL=agent-sdk-4QJDWM7N.js.map

package/dist/{agent-sdk-RF5VJZAT.js.map → agent-sdk-4QJDWM7N.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/engines/agent-sdk.ts"],"names":[],"mappings":"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","file":"agent-sdk-RF5VJZAT.js","sourcesContent":["/**\n * Engine adapter: the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`).\n * Each `run` is a fresh `query()` — a clean context per loop iteration, which\n * is the whole point. Uses the host's Claude Code auth, so it needs no API key.\n */\n\nimport pTimeout from 'p-timeout';\n\nimport {\n  SUBAGENT_TOOLS,\n  type AgentRequest,\n  type AgentResult,\n  type Engine,\n  type EngineEventSink,\n  type EngineOptions,\n} from './engine.ts';\nimport { mapMessage, newAccumulator } from './message-map.ts';\nimport { LoopError } from '../core/errors.ts';\n\n/**\n * Best-effort classification of an Agent SDK error into a provider-limit\n * `LoopError`, or `undefined` to fall through to the generic ENGINE mapping.\n * The SDK exposes limit state in a few shapes (a thrown error message, an\n * `error` field carrying an `SDKAssistantMessageError` string, and a\n * `rate_limit_info.resetsAt` epoch). We read defensively rather than depend on\n * an exact internal shape:\n *   - a rate-limit / overloaded signal → RATE_LIMIT (resets on its own).\n *   - a billing / usage / credits signal → QUOTA. A `resetsAt` (when present)\n *     makes it auto-waitable; otherwise QUOTA has no reset.\n */\nfunction classifySdkLimit(error: unknown): LoopError | undefined {\n  const err = (error ?? {}) as Record<string, unknown>;\n  const tag = typeof err.error === 'string' ? err.error : '';\n  const message = error instanceof Error ? error.message : String(error);\n  const haystack = `${tag} ${message}`.toLowerCase();\n\n  const info = (err.rate_limit_info ?? {}) as Record<string, unknown>;\n  const resetAt =\n    typeof info.resetsAt === 'number'\n      ? info.resetsAt\n      : typeof info.overageResetsAt === 'number'\n        ? info.overageResetsAt\n        : undefined;\n\n  const isUsage =\n    tag === 'billing_error' ||\n    info.errorCode === 'credits_required' ||\n    /billing|credit|usage limit|quota/.test(haystack);\n  if (isUsage) {\n    return new LoopError({\n      code: 'QUOTA',\n      phase: 'engine',\n      message: `agent-sdk usage/billing limit: ${message}`,\n      cause: error,\n      resetAt,\n    });\n  }\n  const isRate =\n    tag === 'rate_limit' ||\n    tag === 'overloaded' ||\n    /rate limit|rate-limit|too many requests|overloaded/.test(haystack);\n  if (isRate) {\n    return new LoopError({\n      code: 'RATE_LIMIT',\n      phase: 'engine',\n      message: `agent-sdk rate limited: ${message}`,\n      cause: error,\n      resetAt,\n    });\n  }\n  return undefined;\n}\n\nexport class AgentSdkEngine implements Engine {\n  readonly name = 'agent-sdk';\n  constructor(private readonly opts: EngineOptions = {}) {}\n\n  async run(\n    req: AgentRequest,\n    onEvent: EngineEventSink,\n    signal: AbortSignal,\n  ): Promise<AgentResult> {\n    // Lazy import so installs/runs that never touch this engine don't pay for it.\n    const { query } = await import('@anthropic-ai/claude-agent-sdk');\n\n    const acc = newAccumulator(\n      req.model ?? this.opts.defaultModel ?? 'unknown',\n    );\n    const abort = new AbortController();\n    const onAbort = () => abort.abort();\n    if (signal.aborted) abort.abort();\n    else signal.addEventListener('abort', onAbort, { once: true });\n\n    // The SDK option surface drifts across versions; cast at this boundary.\n    const options = {\n      model: req.model ?? this.opts.defaultModel,\n      systemPrompt: req.system,\n      cwd: req.cwd,\n      allowedTools: req.allowedTools,\n      // A leaf agent may not spawn sub-agents — disallow the spawn tool.\n      disallowedTools: req.leaf ? SUBAGENT_TOOLS : undefined,\n      permissionMode: this.opts.permissionMode,\n      includePartialMessages: true,\n      abortController: abort,\n    } as Record<string, unknown>;\n\n    try {\n      const response = query({\n        prompt: req.prompt,\n        options,\n      } as never) as AsyncIterable<unknown>;\n      const consume = (async () => {\n        for await (const message of response) mapMessage(message, acc, onEvent);\n      })();\n      await (req.timeoutMs\n        ? pTimeout(consume, { milliseconds: req.timeoutMs })\n        : consume);\n    } catch (e) {\n      if (signal.aborted)\n        throw new LoopError({\n          code: 'ABORTED',\n          phase: 'engine',\n          message: 'agent-sdk run aborted',\n        });\n      const limit = classifySdkLimit(e);\n      if (limit) throw limit;\n      throw LoopError.from(e, { code: 'ENGINE', phase: 'engine' });\n    } finally {\n      signal.removeEventListener('abort', onAbort);\n    }\n\n    onEvent({ type: 'usage', usage: acc.usage, model: acc.model });\n    return {\n      text: acc.text,\n      usage: acc.usage,\n      model: acc.model,\n      stopReason: acc.stopReason,\n    };\n  }\n}\n"]}
+{"version":3,"sources":["../src/engines/agent-sdk.ts"],"names":[],"mappings":"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","file":"agent-sdk-4QJDWM7N.js","sourcesContent":["/**\n * Engine adapter: the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`).\n * Each `run` is a fresh `query()` — a clean context per loop iteration, which\n * is the whole point. Uses the host's Claude Code auth, so it needs no API key.\n */\n\nimport pTimeout from 'p-timeout';\n\nimport {\n  SUBAGENT_TOOLS,\n  type AgentRequest,\n  type AgentResult,\n  type Engine,\n  type EngineEventSink,\n  type EngineOptions,\n} from './engine.ts';\nimport { mapMessage, newAccumulator } from './message-map.ts';\nimport { LoopError } from '../core/errors.ts';\n\n/**\n * Best-effort classification of an Agent SDK error into a provider-limit\n * `LoopError`, or `undefined` to fall through to the generic ENGINE mapping.\n * The SDK exposes limit state in a few shapes (a thrown error message, an\n * `error` field carrying an `SDKAssistantMessageError` string, and a\n * `rate_limit_info.resetsAt` epoch). We read defensively rather than depend on\n * an exact internal shape:\n *   - a rate-limit / overloaded signal → RATE_LIMIT (resets on its own).\n *   - a billing / usage / credits signal → QUOTA. A `resetsAt` (when present)\n *     makes it auto-waitable; otherwise QUOTA has no reset.\n */\nfunction classifySdkLimit(error: unknown): LoopError | undefined {\n  const err = (error ?? {}) as Record<string, unknown>;\n  const tag = typeof err.error === 'string' ? err.error : '';\n  const message = error instanceof Error ? error.message : String(error);\n  const haystack = `${tag} ${message}`.toLowerCase();\n\n  const info = (err.rate_limit_info ?? {}) as Record<string, unknown>;\n  const resetAt =\n    typeof info.resetsAt === 'number'\n      ? info.resetsAt\n      : typeof info.overageResetsAt === 'number'\n        ? info.overageResetsAt\n        : undefined;\n\n  const isUsage =\n    tag === 'billing_error' ||\n    info.errorCode === 'credits_required' ||\n    /billing|credit|usage limit|quota/.test(haystack);\n  if (isUsage) {\n    return new LoopError({\n      code: 'QUOTA',\n      phase: 'engine',\n      message: `agent-sdk usage/billing limit: ${message}`,\n      cause: error,\n      resetAt,\n    });\n  }\n  const isRate =\n    tag === 'rate_limit' ||\n    tag === 'overloaded' ||\n    /rate limit|rate-limit|too many requests|overloaded/.test(haystack);\n  if (isRate) {\n    return new LoopError({\n      code: 'RATE_LIMIT',\n      phase: 'engine',\n      message: `agent-sdk rate limited: ${message}`,\n      cause: error,\n      resetAt,\n    });\n  }\n  return undefined;\n}\n\nexport class AgentSdkEngine implements Engine {\n  readonly name = 'agent-sdk';\n  constructor(private readonly opts: EngineOptions = {}) {}\n\n  async run(\n    req: AgentRequest,\n    onEvent: EngineEventSink,\n    signal: AbortSignal,\n  ): Promise<AgentResult> {\n    // Lazy import so installs/runs that never touch this engine don't pay for it.\n    const { query } = await import('@anthropic-ai/claude-agent-sdk');\n\n    const acc = newAccumulator(\n      req.model ?? this.opts.defaultModel ?? 'unknown',\n    );\n    const abort = new AbortController();\n    const onAbort = () => abort.abort();\n    if (signal.aborted) abort.abort();\n    else signal.addEventListener('abort', onAbort, { once: true });\n\n    // The SDK option surface drifts across versions; cast at this boundary.\n    const options = {\n      model: req.model ?? this.opts.defaultModel,\n      systemPrompt: req.system,\n      cwd: req.cwd,\n      allowedTools: req.allowedTools,\n      // A leaf agent may not spawn sub-agents — disallow the spawn tool.\n      disallowedTools: req.leaf ? SUBAGENT_TOOLS : undefined,\n      permissionMode: this.opts.permissionMode,\n      includePartialMessages: true,\n      abortController: abort,\n    } as Record<string, unknown>;\n\n    try {\n      const response = query({\n        prompt: req.prompt,\n        options,\n      } as never) as AsyncIterable<unknown>;\n      const consume = (async () => {\n        for await (const message of response) mapMessage(message, acc, onEvent);\n      })();\n      await (req.timeoutMs\n        ? pTimeout(consume, { milliseconds: req.timeoutMs })\n        : consume);\n    } catch (e) {\n      if (signal.aborted)\n        throw new LoopError({\n          code: 'ABORTED',\n          phase: 'engine',\n          message: 'agent-sdk run aborted',\n        });\n      const limit = classifySdkLimit(e);\n      if (limit) throw limit;\n      throw LoopError.from(e, { code: 'ENGINE', phase: 'engine' });\n    } finally {\n      signal.removeEventListener('abort', onAbort);\n    }\n\n    onEvent({ type: 'usage', usage: acc.usage, model: acc.model });\n    return {\n      text: acc.text,\n      usage: acc.usage,\n      model: acc.model,\n      stopReason: acc.stopReason,\n    };\n  }\n}\n"]}

package/dist/api.d.ts

@@ -1,5 +1,56 @@
-import { L as LoopConfig, J as Job, D as DagConfig, O as Outcome, a as JobContext, C as ConditionInput, b as JobMeta, c as EngineRef, W as Workspace, A as AgentDef, d as Condition, e as EngineOptions, f as Engine, g as EngineName, h as AgentRequest, U as Usage, i as EngineEventSink, j as AgentResult, E as Environment, k as EnvHandle, l as LoopEvent, F as Forge, B as BudgetConfig, m as LimitPolicy } from './types-B4wGVpqo.js';
-export { n as AgentJobConfig, o as Budget, p as CommitJobConfig, q as ConditionResult, r as DagNode, s as EngineStreamEvent, t as ForgeOpts, G as GhForge, u as GroundConfig, v as LogLevel, w as LoopError, x as LoopErrorCode, M as MergeOptions, y as MockForge, z as MockForgeOptions, H as OutcomeStatus, P as PrInput, I as PrPatch, K as PrRef, R as RawPredicate, N as RetryPolicy, S as SUBAGENT_TOOLS, Q as Skill, T as agentJob, V as buildChecksArgs, X as buildCreateArgs, Y as buildEditArgs, Z as buildMergeArgs, _ as buildViewArgs, $ as commitJob, a0 as defineAgent, a1 as defineSkill, a2 as fnJob, a3 as fromFile, a4 as isEngine, a5 as isEnvironment, a6 as isForge, a7 as kickback, a8 as resolveSystem } from './types-B4wGVpqo.js';
+import { C as ConditionInput, J as Job, R as RevisionRerun, F as FeedbackFinding, a as FeedbackDecision, O as Outcome, G as GraphPosition, b as FeedbackSeverity, c as FeedbackActionSeverity, d as JobContext, e as RevisionRequest, L as LoopConfig, D as DagConfig, f as JobMeta, g as EngineRef, W as Workspace, A as AgentDef, h as Condition, i as EngineOptions, j as Engine, k as EngineName, l as AgentRequest, U as Usage, m as EngineEventSink, n as AgentResult, E as Environment, o as EnvHandle, p as LoopEvent, q as Forge, B as BudgetConfig, r as LimitPolicy } from './types-Cv_3ymr9.js';
+export { s as AgentContractSummary, t as AgentFailureMode, u as AgentHumanGate, v as AgentJobConfig, w as AgentOutputContract, x as AgentSkillRef, y as AgentTier, z as Budget, H as CommitJobConfig, I as ConditionResult, K as DagNode, M as EngineStreamEvent, N as ForgeOpts, P as GhForge, Q as GroundConfig, S as LogLevel, T as LoopError, V as LoopErrorCode, X as MergeOptions, Y as MockForge, Z as MockForgeOptions, _ as OutcomeStatus, $ as PrInput, a0 as PrPatch, a1 as PrRef, a2 as RawPredicate, a3 as RetryPolicy, a4 as SUBAGENT_TOOLS, a5 as Skill, a6 as agentContract, a7 as agentJob, a8 as buildChecksArgs, a9 as buildCreateArgs, aa as buildEditArgs, ab as buildMergeArgs, ac as buildViewArgs, ad as commitJob, ae as defineAgent, af as defineSkill, ag as fnJob, ah as fromFile, ai as isEngine, aj as isEnvironment, ak as isForge, al as resolveSystem } from './types-Cv_3ymr9.js';
+
+interface RevisionRequestInput {
+    target?: string;
+    reason?: string;
+    findings?: FeedbackFinding[];
+    rerun?: RevisionRerun;
+    source?: string;
+    decision?: FeedbackDecision;
+}
+declare function normalizeFeedbackSeverity(severity: FeedbackSeverity | undefined): FeedbackActionSeverity;
+declare function isRequiredFeedbackSeverity(severity: FeedbackSeverity | undefined): boolean;
+declare function revisionRequest(input: RevisionRequestInput, over?: Partial<Outcome>): Outcome;
+declare function kickback(to: string, reason: string, over?: Partial<Outcome>): Outcome;
+/**
+ * The single accessor for an outcome's revision request. `Outcome.revision` is
+ * the one channel a producer sets (`revisionRequest`, `kickback`, `reviewPanel`,
+ * dag routing), so there is exactly one place to read it — no parallel `kickback`
+ * field or `data` copy to keep in sync.
+ */
+declare function revisionFromOutcome(outcome: Outcome): RevisionRequest | undefined;
+declare function feedbackBlock(outcome: Outcome): string;
+declare function graphPositionBlock(graph: GraphPosition): string;
+type ReviewTarget = {
+    name?: string;
+    review: ConditionInput;
+} | {
+    name?: string;
+    job: Job;
+};
+interface ReviewPanelConfig {
+    label?: string;
+    reviewers: ReviewTarget[];
+    /** Default `all`: every reviewer must pass. A number means k-of-n over all reviewers. */
+    pass?: 'all' | number;
+    /** When set, a failing panel emits a targeted revision request for dag routing. */
+    target?: string;
+    rerun?: RevisionRerun;
+}
+declare function reviewPanel(config: ReviewPanelConfig): Job;
+interface ReviewContextConfig {
+    diff?: boolean;
+    files?: string[];
+    ledger?: boolean;
+    tests?: boolean | {
+        command: string;
+        args?: string[];
+        cwd?: string;
+    };
+    maxChars?: number;
+}
+declare function reviewContext(config: ReviewContextConfig): (ctx: JobContext, last: Outcome | undefined) => Promise<string>;
 
 /**
  * The loop primitive. `loop(config)` returns a `Job`, so loops nest by simply
@@ -903,6 +954,12 @@ interface RunOptions {
     recordTo?: string;
     /** Snapshot the shared run state here at each loop/dag/job boundary. */
     checkpoint?: string;
+    /**
+     * Register this run in the global registry (`~/.loops/runs/<runId>`) and write
+     * its live state there, so another process can `loops list` / `status` / `tail`
+     * it. Off by default — opt in to make a run observable from outside.
+     */
+    supervise?: boolean;
     /** Restore shared run state written by a prior `checkpoint` before starting. */
     resumeFrom?: string;
     /**
@@ -930,11 +987,128 @@ interface RunResult {
         spent: number;
         remaining: number;
     };
+    /** The registry id, when the run was supervised. */
+    runId?: string;
 }
 declare function run(job: Job, options?: RunOptions): Promise<RunResult>;
 /** Process exit code mapped from a terminal outcome. */
 declare function exitCodeFor(outcome: Outcome): number;
 
+/**
+ * Out-of-process supervision. A supervised run registers itself under a global
+ * registry (`~/.loops/runs/<runId>/`) and writes its live state there as it goes:
+ *
+ *   - `status.json`: a snapshot rewritten at each boundary: the run's shape (the
+ *     static `JobMeta`) plus where it is right now (path, iteration, last gate
+ *     verdict and confidence, last outcome, token usage, terminal status at end).
+ *   - `events.jsonl`: the event stream appended live (the same record `recordTo`
+ *     writes, here automatically and in the registry).
+ *
+ * A separate process (a human `loops list/status/tail`, or an agent over MCP)
+ * reads those files. No daemon, no socket: the filesystem is the channel, which
+ * is the same "the workspace is the state" bet the rest of the library makes.
+ * Liveness is a pid check, so a crashed run is distinguishable from a live one.
+ */
+
+/** The registry root. `LOOPS_HOME` overrides `~/.loops` (used to isolate tests). */
+declare function runsHome(): string;
+interface RunLive {
+    path: string[];
+    iteration: number;
+    lastGate?: {
+        which: string;
+        met: boolean;
+        confidence?: number;
+        reason: string;
+    };
+    lastOutcome?: {
+        status: string;
+        summary?: string;
+    };
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        calls: number;
+    };
+}
+interface RunStatus {
+    runId: string;
+    pid: number;
+    cwd: string;
+    title: string;
+    startedAt: number;
+    updatedAt: number;
+    endedAt?: number;
+    /** Stored disposition: `running` until the run ends, then the terminal status. */
+    status: 'running' | Outcome['status'];
+    /** Whether the owning process is still alive: computed on read, not stored. */
+    alive?: boolean;
+    shape?: JobMeta;
+    live: RunLive;
+}
+/** Read one run's status, with `alive` computed from its pid. */
+declare function readRunStatus(runId: string): RunStatus | undefined;
+/** All known runs, newest first. */
+declare function listRuns(): RunStatus[];
+/** Path to a run's appended event stream (for tailing). */
+declare function runEventsPath(runId: string): string;
+/** Path to a run's semantic record stream. */
+declare function runSemanticRecordsPath(runId: string): string;
+/** A compact one-line rendering of an event, for `loops tail`. */
+declare function formatEvent(event: LoopEvent): string;
+
+type SemanticDecision = FeedbackDecision;
+type SemanticRunRecord = {
+    kind: 'dispatch';
+    ts: number;
+    path: string[];
+    unit: 'job' | 'dag-node';
+    label?: string;
+    node?: string;
+    /** Present for a dag-node: which run this is (1-based; +1 per kickback re-run). */
+    attempt?: number;
+} | {
+    kind: 'completion';
+    ts: number;
+    path: string[];
+    unit: 'job' | 'loop' | 'dag' | 'dag-node';
+    label?: string;
+    outcome: SemanticOutcome;
+    iterations?: number;
+    /** Present for a dag-node: which run this completion is for. */
+    attempt?: number;
+} | {
+    kind: 'surfacing';
+    ts: number;
+    path: string[];
+    source: 'loop-review' | 'dag-kickback';
+    decision: SemanticDecision;
+    severity?: FeedbackActionSeverity;
+    from?: string;
+    to?: string;
+    reason: string;
+    note?: string;
+} | {
+    kind: 'revision-emitted';
+    ts: number;
+    path: string[];
+    sourceEvent: 'job:end';
+    revision: RevisionRequest;
+} | {
+    kind: 'revision-routed';
+    ts: number;
+    path: string[];
+    sourceEvent: 'loop:review' | 'dag:kickback';
+    decision: SemanticDecision;
+    revision: RevisionRequest;
+};
+interface SemanticOutcome {
+    status: Outcome['status'];
+    summary?: string;
+    confidence?: number;
+}
+declare function semanticRecordsFromEvent(event: LoopEvent): SemanticRunRecord[];
+
 /**
  * Public API. A loop-definition file imports from here and `export default`s a
  * `Job` (usually a `loop(...)` or `dag(...)`). The CLI runs that default export.
@@ -946,4 +1120,4 @@ declare function exitCodeFor(outcome: Outcome): number;
 /** Identity helper that pins the type of a default export to `Job`. */
 declare function defineJob(job: Job): Job;
 
-export { type AgentCheckConfig, AgentDef, AgentRequest, AgentResult, BudgetConfig, type CommitInput, type CommitRecord, type CompactOptions, Condition, ConditionInput, type ConsolidateJobConfig, type ConsolidateOptions, DagConfig, EXIT_PAUSED, Engine, type EngineFactory, EngineName, EngineOptions, EngineRef, EngineRegistry, EnvHandle, Environment, Forge, type GroundOptions, type IsolatedOptions, Job, JobContext, JobMeta, type LedgerEntry, LimitPolicy, type LogQuery, LoopConfig, LoopEvent, type MergeJobConfig, type MergeResult, type MergeSynthesisConfig, type MergeSynthesisResult, MockEngine, type MockEnvOptions, MockEnvironment, type MockResponder, Outcome, type PromptNote, type PullRequestJobConfig, type PushJobConfig, type PushOptions, type PushResult, type RetrieveOptions, type RunOptions, type RunResult, Stats, type StatsSnapshot, type TournamentConfig, Usage, Workspace, type WorktreeHandle, addWorktree, agentCheck, all, always, any, appendLedger, appendPrompt, bodyPassed, commandSucceeds, commit, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, dag, defineJob, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, forgeChecks, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isRepo, isolated, jobMeta, ledgerPath, log, loop, mergeAbort, mergeBranch, mergeJob, mergeNoCommit, mergeSynthesis, minConfidence, mockVerdict, never, not, parallel, predicate, promptPath, pullRequestJob, push, pushJob, quorum, readLedger, readPrompt, removeWorktree, renderPlan, resetLedger, resetPrompt, retrieveLedger, run, sequence, stageAll, toCondition, tournament };
+export { type AgentCheckConfig, AgentDef, AgentRequest, AgentResult, BudgetConfig, type CommitInput, type CommitRecord, type CompactOptions, Condition, ConditionInput, type ConsolidateJobConfig, type ConsolidateOptions, DagConfig, EXIT_PAUSED, Engine, type EngineFactory, EngineName, EngineOptions, EngineRef, EngineRegistry, EnvHandle, Environment, FeedbackActionSeverity, FeedbackDecision, FeedbackFinding, FeedbackSeverity, Forge, GraphPosition, type GroundOptions, type IsolatedOptions, Job, JobContext, JobMeta, type LedgerEntry, LimitPolicy, type LogQuery, LoopConfig, LoopEvent, type MergeJobConfig, type MergeResult, type MergeSynthesisConfig, type MergeSynthesisResult, MockEngine, type MockEnvOptions, MockEnvironment, type MockResponder, Outcome, type PromptNote, type PullRequestJobConfig, type PushJobConfig, type PushOptions, type PushResult, type RetrieveOptions, type ReviewContextConfig, type ReviewPanelConfig, RevisionRequest, type RevisionRequestInput, RevisionRerun, type RunLive, type RunOptions, type RunResult, type RunStatus, type SemanticDecision, type SemanticOutcome, type SemanticRunRecord, Stats, type StatsSnapshot, type TournamentConfig, Usage, Workspace, type WorktreeHandle, addWorktree, agentCheck, all, always, any, appendLedger, appendPrompt, bodyPassed, commandSucceeds, commit, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, dag, defineJob, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, feedbackBlock, forgeChecks, formatEvent, gateJob, graphPositionBlock, groundingText, hasStagedChanges, headSha, isDirty, isRepo, isRequiredFeedbackSeverity, isolated, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeJob, mergeNoCommit, mergeSynthesis, minConfidence, mockVerdict, never, normalizeFeedbackSeverity, not, parallel, predicate, promptPath, pullRequestJob, push, pushJob, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, retrieveLedger, reviewContext, reviewPanel, revisionFromOutcome, revisionRequest, run, runEventsPath, runSemanticRecordsPath, runsHome, semanticRecordsFromEvent, sequence, stageAll, toCondition, tournament };

package/dist/api.js

@@ -1,7 +1,7 @@
-import { mergeNoCommit, stageAll, commit, mergeAbort, log, setMeta, jobMeta, isRepo, addWorktree, childContext, composeCommitBody, mergeBranch, removeWorktree, deleteBranch, push, consolidate, toCondition, GhForge } from './chunk-3BPU34DE.js';
-export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, Stats, addWorktree, agentCheck, agentJob, all, always, any, appendLedger, appendPrompt, bodyPassed, buildChecksArgs, buildCreateArgs, buildEditArgs, buildMergeArgs, buildViewArgs, commandSucceeds, commit, commitJob, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, defineAgent, defineSkill, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, fnJob, forgeChecks, fromFile, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, jobMeta, kickback, ledgerPath, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, not, predicate, promptPath, push, quorum, readLedger, readPrompt, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, run, stageAll, toCondition } from './chunk-3BPU34DE.js';
+import { mergeNoCommit, stageAll, commit, mergeAbort, log, setMeta, jobMeta, isRepo, addWorktree, childContext, composeCommitBody, mergeBranch, removeWorktree, deleteBranch, push, consolidate, toCondition, revisionFromOutcome, GhForge } from './chunk-WM5QVHM2.js';
+export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, Stats, addWorktree, agentCheck, agentContract, agentJob, all, always, any, appendLedger, appendPrompt, bodyPassed, buildChecksArgs, buildCreateArgs, buildEditArgs, buildMergeArgs, buildViewArgs, commandSucceeds, commit, commitJob, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, defineAgent, defineSkill, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, feedbackBlock, fnJob, forgeChecks, formatEvent, fromFile, gateJob, graphPositionBlock, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, isRequiredFeedbackSeverity, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, normalizeFeedbackSeverity, not, predicate, promptPath, push, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, reviewContext, reviewPanel, revisionFromOutcome, revisionRequest, run, runEventsPath, runSemanticRecordsPath, runsHome, semanticRecordsFromEvent, stageAll, toCondition } from './chunk-WM5QVHM2.js';
 import './chunk-JFTXJ7I2.js';
-export { SUBAGENT_TOOLS, isEngine } from './chunk-XC46B4FD.js';
+export { SUBAGENT_TOOLS, isEngine } from './chunk-MA6NDQMO.js';
 import './chunk-Y2SD7GBL.js';
 import { LoopError } from './chunk-I3STY7U6.js';
 export { LoopError } from './chunk-I3STY7U6.js';
@@ -160,6 +160,7 @@ function dag(config) {
     const limit = pLimit(limitN);
     const results = /* @__PURE__ */ new Map();
     const memo = /* @__PURE__ */ new Map();
+    const attempts = /* @__PURE__ */ new Map();
     let stopped = false;
     const pendingKickback = /* @__PURE__ */ new Map();
     const nodeCtx = (name, workspace, environment) => childContext(parent, {
@@ -167,7 +168,14 @@ function dag(config) {
       path: [...path, name],
       workspace,
       environment,
-      lastReview: pendingKickback.get(name)
+      lastReview: pendingKickback.get(name),
+      graph: {
+        dag: config.name,
+        node: name,
+        path: [...path, name],
+        needs: nodes.get(name).needs ?? [],
+        dependents: dependents.get(name) ?? []
+      }
     });
     const mergeLimit = pLimit(1);
     let forkSeq2 = 0;
@@ -264,11 +272,12 @@ function dag(config) {
         path,
         node: name,
         phase,
-        outcome: outcome2
+        outcome: outcome2,
+        attempt: attempts.get(name)
       });
       if (phase === "done" && outcome2.status !== "pass" && nodes.get(name).optional !== true && stopOnError && // A node requesting a kickback is going to be re-run — don't let its
       // (provisional) non-pass abort siblings before the feedback is resolved.
-      !(maxKickbacks > 0 && outcome2.kickback)) {
+      !(maxKickbacks > 0 && revisionFromOutcome(outcome2)?.target)) {
         stopped = true;
       }
       return outcome2;
@@ -278,6 +287,7 @@ function dag(config) {
       if (existing) return existing;
       const node = nodes.get(name);
       const promise = (async () => {
+        attempts.set(name, (attempts.get(name) ?? 0) + 1);
         try {
           const needs = node.needs ?? [];
           const deps = await Promise.all(needs.map(run2));
@@ -324,7 +334,8 @@ function dag(config) {
                 ts: ts(),
                 path,
                 node: name,
-                phase: "start"
+                phase: "start",
+                attempt: attempts.get(name)
               });
               return { outcome: await runNodeJob(name, node), phase: "done" };
             }
@@ -369,10 +380,15 @@ function dag(config) {
       });
       for (; ; ) {
         const from = order.find(
-          (n) => results.get(n)?.kickback && !rejected.has(n)
+          (n) => {
+            const result = results.get(n);
+            return result !== void 0 && revisionFromOutcome(result)?.target !== void 0 && !rejected.has(n);
+          }
         );
         if (!from) break;
-        const { to, reason } = results.get(from).kickback;
+        const request = revisionFromOutcome(results.get(from));
+        const to = request.target;
+        const { reason } = request;
         const allow = nodes.get(from).acceptsKickbackTo;
         const note = !nodes.has(to) ? `unknown node "${to}"` : !ancestorsOf(from).has(to) ? `"${to}" is not an ancestor of "${from}"` : allow && !allow.includes(to) ? `"${from}" does not accept kickback to "${to}"` : void 0;
         if (note) {
@@ -401,7 +417,7 @@ function dag(config) {
         pendingKickback.set(to, {
           status: "fail",
           summary: `Kicked back from "${from}": ${reason}`,
-          data: { kickback: true, from }
+          revision: { ...request, source: request.source ?? from }
         });
         stopped = false;
         await Promise.all(names.map(run2));