@loops-adk/core 0.1.1 → 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):
@@ -458,7 +550,7 @@ loops status <runId>                   # its shape plus where it is now: iterati
 loops tail <runId>                     # stream its events live
 ```
 
-`list` marks a run dead if its process is gone. The read side is also on the public surface (`listRuns`, `readRunStatus`, `runEventsPath`), 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.
+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)
 

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
@@ -1001,9 +1052,63 @@ declare function readRunStatus(runId: string): RunStatus | undefined;
 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.
@@ -1015,4 +1120,4 @@ declare function formatEvent(event: LoopEvent): string;
 /** 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 RunLive, type RunOptions, type RunResult, type RunStatus, 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, formatEvent, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isRepo, isolated, jobMeta, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeJob, mergeNoCommit, mergeSynthesis, minConfidence, mockVerdict, never, not, parallel, predicate, promptPath, pullRequestJob, push, pushJob, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, retrieveLedger, run, runEventsPath, runsHome, 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-6BDWTFOS.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, formatEvent, fromFile, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, not, predicate, promptPath, push, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, run, runEventsPath, runsHome, stageAll, toCondition } from './chunk-6BDWTFOS.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));