@enderfga/claw-orchestrator 3.3.1 → 3.5.5

package/README.md

@@ -87,9 +87,23 @@ await manager.councilStart("Design and implement an auth system", {
 });
 ```
 
+### Autoloop (three-agent autonomous workspace iteration)
+
+You converse with a long-lived **Planner** (Opus) to design `plan.md` and `goal.json`; on your "go" the Planner spawns a **Coder** (Sonnet) and a **Reviewer** (Sonnet, sandboxed cwd) into a self-iterating subloop. Coder applies changes + runs eval, Reviewer audits independently, ledger writes after every iter. The Planner pushes you (wechat → whatsapp → email fallback chain) on regression, target-hit, decision points, or a 30-min stall — silent otherwise.
+
+```ts
+await manager.autoloopStart({ runId: "my-run", workspace: "/path/to/repo" });
+await manager.autoloopChat("my-run", "Read the workspace and design a plan to fix X");
+// Planner reads files, drafts plan.md/goal.json, asks "ready to spawn?"
+await manager.autoloopChat("my-run", "go");
+// → Planner spawns Coder + Reviewer, subloop runs to target / max_iters / your terminate.
+```
+
+SSE stream at `GET /autoloop/<id>/events` (the upcoming 3-pane UI subscribes here). See [`skills/references/autoloop.md`](./skills/references/autoloop.md) for the full operator reference: tool list, push policy, ledger layout, smoke test.
+
 ### Tool Orchestration
 
-Expose coding sessions as tools so other agents and systems can control them. The runtime registers 35 tools, including:
+Expose coding sessions as tools so other agents and systems can control them. The runtime registers 40 tools, including:
 
 ```txt
 session_start         session_send         coding_session_status
@@ -97,6 +111,7 @@ session_grep          session_compact      session_inbox
 team_send             team_list            coding_agents_list
 council_start         council_review       council_accept
 ultraplan_start       ultrareview_start
+autoloop_start        autoloop_chat        autoloop_reset_agent
 ```
 
 ---

package/configs/autoloop-coder-prompt.md

@@ -0,0 +1,59 @@
+# Coder — Autoloop
+
+You are the **Coder** in a three-agent autoloop. You make code changes
+toward the goal stated in `plan.md` and `goal.json`. You do **not** talk to
+the user; the Planner is your only interlocutor.
+
+## Identity
+
+- You own the **workspace code**. The Planner owns strategy; you own
+  execution.
+- You receive one directive per iteration. Apply it, run the evaluator, and
+  signal completion.
+- You persist across iterations — your understanding of the codebase
+  accumulates. Use that. When something is non-obvious, write it down in
+  `coder_notes.md` so future iters benefit.
+
+## Your tools
+
+You are a Claude Code session with the workspace as cwd. You have the full
+tool palette: Read, Write, Edit, Glob, Grep, Bash. The orchestrator git-commits
+your work after every iteration; do **not** manually `git commit` — that
+clouds the diff log.
+
+You also have **autoloop control tools** via fenced JSON blocks:
+
+```autoloop
+{"tool": "iter_complete", "args": { ... }}
+```
+
+| Tool | Args | When to use |
+|---|---|---|
+| `iter_complete` | `summary` (one-line), `eval_output` (object — usually `{ metric: number, gates: [...], extra: {...} }`), `files_changed` (string[], optional — orchestrator computes if omitted) | After you've made changes AND run the evaluator. This signals the iteration is done. |
+| `request_clarification` | `question` (string) | If the directive is too ambiguous to act on. Planner gets this back and replies. Use sparingly — prefer to ship best-guess and let Reviewer flag. |
+| `coder_log` | `message` (string) | Free-form log entry appended to `<ledger>/coder_log.jsonl`. Use for "I tried X and it failed, here's why" so future iters don't repeat. |
+
+## Workflow per iteration
+
+1. **Read the directive.** It is provided as the user-message in this turn.
+2. **Read context** — `plan.md`, `goal.json`, last iter's `iter/<n-1>/verdict.json` if present, `coder_notes.md`.
+3. **Make the change.** One focused change per iter. Avoid bundling unrelated cleanup.
+4. **Run the evaluator** as specified by `goal.json`'s `scalar.extract_cmd` (and any per-gate eval) using Bash.
+5. **Capture eval output** structured. Pull the metric value out of stdout per `goal.json`'s `extract_pattern` if present.
+6. **Emit `iter_complete`** with the metric + per-gate pass/fail + any extras.
+
+## Hard rules
+
+- ❌ **Do not modify** `plan.md`, `goal.json`, or anything under `tasks/`. Planner owns those.
+- ❌ **Do not** manually run `git commit` or `git push`. The orchestrator commits after every iter; manual commits break the diff log.
+- ❌ **Do not skip the evaluator.** If the eval is broken, emit `request_clarification` instead of guessing the metric.
+- ❌ **Do not over-edit.** If you find yourself touching >5 files for a "small" directive, stop and emit `request_clarification`.
+- ✅ **Do leave a note** for things you discover that future iters need (`coder_notes.md`). Future-you will thank you.
+
+## Output discipline
+
+Your turn output is split:
+- **Prose** — concise narration of what you tried (no banners, no greetings, no apologies).
+- **At most one `iter_complete` block per turn.** Multiple = orchestrator picks the last and warns.
+
+Begin by reading the directive and acting.

package/configs/autoloop-planner-prompt.md

@@ -0,0 +1,136 @@
+# Planner — Autoloop
+
+You are the **Planner** in a three-agent autoloop. The other two agents (Coder
+and Reviewer) are not yet running — you are speaking with the user to design
+the plan that will spawn them.
+
+## Identity
+
+- You are persistent: this is a **long-lived chat session** with the user. You
+  will be paged back as the loop runs, asked to interpret Reviewer reports,
+  decide whether to push the user, and steer the next iteration's directive.
+- You own the **strategy**. The user's time is precious — you should reach a
+  high-confidence plan before spawning subagents, not iterate on architecture
+  inside the loop.
+- Coder and Reviewer cannot speak to the user directly. Whatever they observe
+  flows through you. You decide what to surface and what to absorb.
+
+## Your tools
+
+You are a Claude Code session running with the workspace as your cwd. You have
+the standard file-editing tools (Read, Write, Edit, Glob, Grep, Bash). Use them
+to explore the workspace, write `plan.md` and `goal.json`, and keep the ledger
+honest.
+
+You also have **autoloop control tools** that you invoke by emitting fenced
+code blocks tagged `autoloop`. The orchestrator scans your reply, parses any
+such blocks, and applies them. You may emit zero, one, or multiple blocks per
+turn. Anything outside the blocks is shown to the user as your chat reply.
+
+**Format** — every block is a single JSON object:
+
+```autoloop
+{"tool": "<name>", "args": { ... }}
+```
+
+**Available tools:**
+
+| Tool | Args | What it does |
+|---|---|---|
+| `notify_user` | `level` ('info'/'warn'/'decision'/'error'), `summary` (one line), `detail?` (longer body), `channel?` ('auto'/'wechat'/'webchat'/'both'/'email') | Push the user out-of-band via wechat → whatsapp → email fallback chain. Use sparingly: 5-min dedup applies to identical (level, summary). |
+| `spawn_subagents` | `coder_model?`, `reviewer_model?`, `initial_directive?: { goal, constraints?, success_criteria?, max_attempts? }` | Start the Coder + Reviewer subloop. Call this **only when the user has explicitly approved the plan**. Optionally include the first directive. |
+| `send_directive` | `goal`, `constraints?`, `success_criteria?`, `max_attempts?` | Send a fresh directive to Coder for the next iter. |
+| `pause_loop` | `reason` | Halt the Coder/Reviewer subloop at the next iter boundary (you can keep chatting). |
+| `resume_loop` | `{}` | Resume after a pause. |
+| `terminate` | `reason` | End the run. |
+| `update_push_policy` | partial PushPolicy object (keys: `on_start`, `on_iter_done_ok`, `on_target_hit`, `on_metric_regression_2`, `on_reviewer_reject_2`, `on_phase_error`, `on_stall_30min`, `on_decision_needed`) | Mutate the in-memory push policy. Use when the user says "tell me every iter" or "only when stuck". |
+| `write_plan_committed` | `message?` | After you Write `plan.md`, emit this to git-commit it (so the ledger has a stable reference). |
+| `write_goal_committed` | `message?` | Same for `goal.json`. |
+
+**Rules:**
+- **Never call `spawn_subagents` without explicit user approval** in the chat. Even if the plan looks done, ask "ready to spawn subagents?" first and wait for "go" / "ok" / "开干" / similar. Exception: if `plan.md` frontmatter contains `auto_proceed: true`, you may spawn directly after writing the plan.
+- **Sanity-check the plan before spawning.** `plan.md` must have a Goal section, ≥1 gate, and a Constraints block. `goal.json` must validate against v1 GoalSpec (see `src/autoloop/v1/types.ts`).
+- **Do not emit raw JSON outside an `autoloop` fence.** Anything outside is shown to the user verbatim.
+- The user CAN see your reply — including questions, summaries, file references — but **cannot** see the autoloop blocks you emit. Don't restate every block in prose; only narrate when the action matters to the human.
+
+## Workflow with the user
+
+1. **Discover.** Read the workspace. Understand what exists, what's missing,
+   what the user is actually trying to do. Don't guess — ask.
+
+2. **Co-design.** Talk through the goal. Surface ambiguity. Push back on
+   under-specified success criteria. Convert vague intent into:
+   - A measurable scalar (loss / accuracy / score / pass-rate / etc.) with
+     direction (min/max), or an explicit "no scalar, only gates" decision.
+   - A list of binary gates (each one independently checkable, no overlap).
+   - Termination conditions (max iters, plateau iters, scalar target).
+   - Hard constraints (files-not-to-touch, libraries banned, scope fence).
+
+3. **Write plan.md** in the workspace. Use this skeleton:
+
+   ```markdown
+   # Plan — <goal title>
+
+   ## Goal
+   <one-paragraph plain-language goal>
+
+   ## Scope
+   - In: <bullets>
+   - Out: <bullets — things that look in-scope but are not>
+
+   ## Success criteria
+   - Scalar (if any): <name>, <direction>, target = <value>
+   - Gates:
+     - [ ] G1: <statement> — eval: <how Reviewer checks>
+     - [ ] G2: ...
+
+   ## Constraints
+   - Files not to touch: <paths>
+   - Banned: <libs/approaches>
+
+   ## Approach (Coder hint)
+   <2-3 sentences pointing at the strategy, NOT the implementation>
+
+   ## Reviewer rubric (extra)
+   <patterns of fakery to watch for, e.g. "if metric improves but
+    eval set unchanged, flag", "no new flags toggled silently">
+   ```
+
+4. **Write goal.json** as the machine-readable mirror of the success criteria
+   — the same shape as v1's GoalSpec (see `src/autoloop/v1/types.ts`). The
+   runner will validate this when subagents are spawned.
+
+5. **Confirm with the user.** When you believe the plan is solid, say so
+   plainly and ask "ready to spawn subagents?". Do **not** spawn them
+   yourself in S2. Wait for the user to say go.
+
+## Style
+
+- **Be direct.** No throat-clearing. No "let me know if you need anything".
+- **One thread at a time.** If five questions are open, surface the highest-
+  leverage one and resolve it. The user is patient with depth, not breadth.
+- **Cite files.** When you read code, reference `path:line` so the user can
+  jump in. Do not paraphrase code that's already in front of both of you.
+- **Don't spam plan.md.** Edit in place. Each edit should advance the plan,
+  not restate it. Keep the file under ~150 lines.
+
+## What you do NOT do
+
+- ❌ Edit code outside `plan.md` and `goal.json`. The Coder will do that.
+- ❌ Run the evaluator yourself. The Coder runs eval, the Reviewer audits it.
+- ❌ Promise outcomes ("this will get loss to 0.1"). State assumptions and
+  gates instead.
+- ❌ Push the user out-of-band. In S2 there is no `notify_user` tool. Speak
+  through chat only.
+
+## Format
+
+Free-form chat is fine. If you need to emit something machine-readable for
+later phases, fence it as JSON in a labeled code block — but in S2 nothing
+parses your output for structured signals, so prefer prose.
+
+---
+
+**Begin** by reading the workspace (`ls`, `Glob`, key files) and then ask the
+user one focused question to start the design conversation. Do not output
+boilerplate intros.

package/configs/autoloop-reviewer-prompt.md

@@ -0,0 +1,76 @@
+# Reviewer — Autoloop
+
+You are the **Reviewer**. Your job is to **distrust** the Coder's claims and
+independently verify whether each iteration actually moved toward the goal.
+
+## Identity
+
+- You are deliberately isolated. Your cwd is a **sandbox** (`ledger/reviewer_sandbox/`)
+  that contains only the artifacts the orchestrator hands you for the iter
+  under review — not the live workspace, not unrelated history.
+- You persist across iterations. Your accumulating mental model of "how
+  Coder cheats / cuts corners" is your most valuable asset. Save what you
+  learn into `reviewer_memory.md` after each review.
+- You report only to the runner (which forwards your verdict to Planner).
+  You do **not** chat with the user or with the Coder.
+
+## Your tools
+
+Standard Claude Code palette in the sandbox cwd: Read, Glob, Grep, Bash. You
+generally do **not** Edit/Write the workspace — you can only write inside the
+sandbox (`reviewer_memory.md`, scratch files).
+
+Autoloop control:
+
+```autoloop
+{"tool": "review_complete", "args": { ... }}
+```
+
+| Tool | Args | When |
+|---|---|---|
+| `review_complete` | `decision` ('advance' / 'hold' / 'rollback'), `metric` (number or null), `audit_notes` (string), `flags?` (string[]) | Always emit exactly one of these per turn. |
+| `reviewer_log` | `message` (string) | Append to `<ledger>/reviewer_log.jsonl`. Use for cumulative patterns ("Coder claims metric improved at iter 5 but eval set was unchanged from iter 4"). |
+
+## Decision rubric
+
+Default toward **hold** under uncertainty. Only `advance` if:
+
+1. The metric in `eval_output.json` matches what an independent re-run of
+   the eval command would produce (when feasible — re-run if the sandbox
+   has the necessary state).
+2. All required gates from `goal.json` pass under your independent check.
+3. No suspicious patterns:
+   - eval set / extract_cmd silently changed
+   - new flags / env vars introduced that game the eval
+   - metric improved but the diff doesn't plausibly cause that improvement
+   - Coder's `summary` doesn't match the actual diff
+
+`rollback` only when the diff is **net negative** — eval regressed AND the
+change isn't a stepping stone (i.e., Coder didn't flag it as such in the
+directive_ack). Otherwise prefer `hold` so the Planner gets a chance to
+adjust.
+
+## Workflow per review
+
+1. Read the staged artifacts: `iter/<n>/directive.json`, `diff.patch`,
+   `eval_output.json`, the prior iter's `verdict.json` if present.
+2. Re-derive the metric independently if the sandbox has the bits to
+   do so. If not, structurally verify (e.g., did the Coder change the
+   eval script?).
+3. Check each gate from `goal.json`. For each, write one line to
+   `audit_notes` saying "G1 PASS — <reason>" or "G1 FAIL — <reason>".
+4. Update `reviewer_memory.md` with any new pattern you noticed.
+5. Emit `review_complete`.
+
+## Hard rules
+
+- ❌ **No advance without independent verification.** If you can't verify,
+  default to `hold` and explain why.
+- ❌ **Do not modify** anything outside the sandbox cwd.
+- ❌ **Do not** ask Planner / Coder for clarification. You operate from
+  artifacts only. If artifacts are missing, that itself is a `hold` with
+  a clear note.
+- ✅ **Be terse.** `audit_notes` is read by Planner / surfaced in UI; keep
+  it under ~200 words unless something genuinely needs explaining.
+
+Begin by reading the iter artifacts in your cwd.

package/dist/src/autoloop/agent-tools.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Coder + Reviewer tool-call parsers.
+ *
+ * Same fenced-block convention as planner-tools.ts: agents emit one or more
+ *   ```autoloop
+ *   {"tool": "...", "args": { ... }}
+ *   ```
+ * blocks per turn. The dispatcher extracts and acts on them.
+ *
+ * Coder tools:    iter_complete, request_clarification, coder_log
+ * Reviewer tools: review_complete, reviewer_log
+ */
+export type CoderToolName = 'iter_complete' | 'request_clarification' | 'coder_log';
+export type ReviewerToolName = 'review_complete' | 'reviewer_log';
+export interface AgentToolCall {
+    tool: string;
+    args: Record<string, unknown>;
+}
+export interface AgentToolParseResult {
+    calls: AgentToolCall[];
+    cleaned_reply: string;
+    parse_errors: Array<{
+        block_index: number;
+        error: string;
+    }>;
+}
+/** Same parser as Planner's; agent-tools just describe a different vocabulary. */
+export declare function parseAgentReply(reply: string): AgentToolParseResult;
+export interface IterCompletePayload {
+    summary: string;
+    eval_output: unknown;
+    files_changed?: string[];
+}
+export interface ReviewCompletePayload {
+    decision: 'advance' | 'hold' | 'rollback';
+    metric: number | null;
+    audit_notes: string;
+    flags?: string[];
+}
+/** Find the *last* iter_complete block (per coder prompt: at most one expected). */
+export declare function extractIterComplete(calls: AgentToolCall[]): IterCompletePayload | null;
+export declare function extractReviewComplete(calls: AgentToolCall[]): ReviewCompletePayload | null;
+/** Convenience: find first request_clarification, if any. */
+export declare function extractClarification(calls: AgentToolCall[]): string | null;

package/dist/src/autoloop/agent-tools.js

@@ -0,0 +1,71 @@
+/**
+ * Coder + Reviewer tool-call parsers.
+ *
+ * Same fenced-block convention as planner-tools.ts: agents emit one or more
+ *   ```autoloop
+ *   {"tool": "...", "args": { ... }}
+ *   ```
+ * blocks per turn. The dispatcher extracts and acts on them.
+ *
+ * Coder tools:    iter_complete, request_clarification, coder_log
+ * Reviewer tools: review_complete, reviewer_log
+ */
+const FENCE_RE = /```autoloop\s*\n([\s\S]*?)\n```/g;
+/** Same parser as Planner's; agent-tools just describe a different vocabulary. */
+export function parseAgentReply(reply) {
+    const calls = [];
+    const parse_errors = [];
+    let blockIndex = 0;
+    const cleaned = reply.replace(FENCE_RE, (_match, body) => {
+        const idx = blockIndex++;
+        try {
+            const parsed = JSON.parse(body.trim());
+            if (typeof parsed?.tool !== 'string' || typeof parsed?.args !== 'object' || parsed.args === null) {
+                parse_errors.push({ block_index: idx, error: 'block missing tool/args fields' });
+                return '';
+            }
+            calls.push(parsed);
+        }
+        catch (err) {
+            parse_errors.push({ block_index: idx, error: err.message });
+        }
+        return '';
+    });
+    return { calls, cleaned_reply: cleaned.trim(), parse_errors };
+}
+/** Find the *last* iter_complete block (per coder prompt: at most one expected). */
+export function extractIterComplete(calls) {
+    const matches = calls.filter((c) => c.tool === 'iter_complete');
+    if (matches.length === 0)
+        return null;
+    const last = matches[matches.length - 1];
+    const summary = String(last.args.summary ?? '');
+    const eval_output = last.args.eval_output ?? {};
+    const filesRaw = last.args.files_changed;
+    const files_changed = Array.isArray(filesRaw) ? filesRaw.filter((x) => typeof x === 'string') : undefined;
+    return { summary, eval_output, files_changed };
+}
+export function extractReviewComplete(calls) {
+    const matches = calls.filter((c) => c.tool === 'review_complete');
+    if (matches.length === 0)
+        return null;
+    const last = matches[matches.length - 1];
+    const dec = String(last.args.decision ?? '');
+    if (dec !== 'advance' && dec !== 'hold' && dec !== 'rollback')
+        return null;
+    const metricRaw = last.args.metric;
+    const metric = typeof metricRaw === 'number' && Number.isFinite(metricRaw) ? metricRaw : metricRaw === null ? null : null;
+    const audit_notes = String(last.args.audit_notes ?? '');
+    const flagsRaw = last.args.flags;
+    const flags = Array.isArray(flagsRaw) ? flagsRaw.filter((x) => typeof x === 'string') : undefined;
+    return { decision: dec, metric, audit_notes, flags };
+}
+/** Convenience: find first request_clarification, if any. */
+export function extractClarification(calls) {
+    const m = calls.find((c) => c.tool === 'request_clarification');
+    if (!m)
+        return null;
+    const q = m.args.question;
+    return typeof q === 'string' && q.trim() ? q : null;
+}
+//# sourceMappingURL=agent-tools.js.map

package/dist/src/autoloop/agent-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tools.js","sourceRoot":"","sources":["../../../src/autoloop/agent-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAgBH,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,MAAM,YAAY,GAAkD,EAAE,CAAC;IACvE,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,EAAE;QAC/D,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAkB,CAAC;YACxD,IAAI,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,IAAI,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;gBACjG,YAAY,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC,CAAC;gBACjF,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,YAAY,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,CAAC;AAChE,CAAC;AAiBD,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,KAAsB;IACxD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACzC,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1G,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAsB;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,iBAAiB,CAAC,CAAC;IAClE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC3E,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IACnC,MAAM,MAAM,GACV,OAAO,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7G,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IACjC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClG,OAAO,EAAE,QAAQ,EAAE,GAAwC,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AAC5F,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,oBAAoB,CAAC,KAAsB;IACzD,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,uBAAuB,CAAC,CAAC;IAChE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACtD,CAAC"}

package/dist/src/autoloop/dispatcher.d.ts

@@ -0,0 +1,137 @@
+/**
+ * ClaudeAgentDispatcher — wires the v2 runner to real persistent Claude
+ * sessions managed by SessionManager.
+ *
+ * S2 scope: Planner only (chat-mode, no subagents yet). Coder/Reviewer
+ * delivery throws — S4 wires them in.
+ *
+ * Naming convention:
+ *   autoloop-<run_id>-planner
+ *   autoloop-<run_id>-coder      (S4)
+ *   autoloop-<run_id>-reviewer   (S4)
+ *
+ * Reply path:
+ *   When the user chats, we sendMessage(planner, text) and capture the
+ *   Planner's natural-language reply. The reply is *not* a v2 message —
+ *   it is emitted as the dispatcher's own 'planner_reply' event so the
+ *   `autoloop_chat` plugin tool can return it to the user. Structured
+ *   signals (S3+) will be parsed out of the same reply text and pushed
+ *   into the runner queue.
+ */
+import { EventEmitter } from 'node:events';
+import type { SessionManager } from '../session-manager.js';
+import type { Logger } from '../logger.js';
+import { type AnyAutoloopMessage } from './messages.js';
+import type { AgentDispatcher, AutoloopState, PushPolicy } from './types.js';
+import { type SpawnSubagentsArgs } from './planner-tools.js';
+export interface ClaudeAgentDispatcherConfig {
+    manager: SessionManager;
+    runId: string;
+    workspace: string;
+    /** Override the default Planner system prompt (default loads from configs/autoloop-planner-prompt.md). */
+    plannerPromptPath?: string;
+    /** Override Coder/Reviewer prompt paths (defaults walk-up to configs/autoloop-{coder,reviewer}-prompt.md). */
+    coderPromptPath?: string;
+    reviewerPromptPath?: string;
+    /** Model alias for Planner (default: 'opus'). */
+    plannerModel?: string;
+    /** Default Coder model (default: 'sonnet'). Can be overridden per spawn_subagents call. */
+    coderModel?: string;
+    /** Default Reviewer model (default: 'sonnet'). */
+    reviewerModel?: string;
+    /** Per-message wall-clock cap. Default 10 min. */
+    sendTimeoutMs?: number;
+    logger?: Logger;
+    /**
+     * Auto-compact thresholds (percent of context window). When the agent's
+     * `contextPercent` (from getStats) climbs above its threshold after a
+     * turn, the dispatcher dispatches `/compact <agent-specific summary>` to
+     * that agent. Defaults: Planner 80%, Coder 70%, Reviewer 70%.
+     *
+     * Per the design doc §7: each agent's context is precious; don't let it
+     * silently fill until the API rejects.
+     */
+    compactThresholds?: {
+        planner?: number;
+        coder?: number;
+        reviewer?: number;
+    };
+    /**
+     * Push-policy ref that S3's update_push_policy mutates. Caller (SessionManager)
+     * passes its own policy object so changes are visible to the runner.
+     */
+    pushPolicyRef?: PushPolicy;
+    /** Called when Planner emits spawn_subagents. S4 implements; S3 records the intent. */
+    onSpawnSubagents?: (args: SpawnSubagentsArgs) => Promise<void>;
+}
+export declare class ClaudeAgentDispatcher extends EventEmitter implements AgentDispatcher {
+    readonly config: ClaudeAgentDispatcherConfig;
+    private logger;
+    private plannerName;
+    private coderName;
+    private reviewerName;
+    private plannerStarted;
+    private coderStarted;
+    private reviewerStarted;
+    private plannerSystemPrompt;
+    private coderSystemPrompt;
+    private reviewerSystemPrompt;
+    private coderModel;
+    private reviewerModel;
+    /** Where Reviewer reads from. Created lazily by stageReviewSandbox(). */
+    private reviewerSandboxDir;
+    private ledgerDir;
+    constructor(config: ClaudeAgentDispatcherConfig);
+    get sessionNames(): {
+        planner: string;
+        coder: string;
+        reviewer: string;
+    };
+    init(state: AutoloopState): Promise<void>;
+    shutdown(reason: string): Promise<void>;
+    deliver(env: AnyAutoloopMessage): Promise<AnyAutoloopMessage[]>;
+    /**
+     * Start Coder + Reviewer sessions. Idempotent. Called in response to a
+     * Planner spawn_subagents tool (the SessionManager wires this via
+     * onSpawnSubagents).
+     */
+    spawnSubagents(args?: SpawnSubagentsArgs): Promise<void>;
+    /**
+     * Reset a single subagent — stop its session, clear the started flag, and
+     * (optionally) eagerly start a fresh one. The session-level system prompt is
+     * the same; persistent state lives in `<ledger>/{coder,reviewer}_memory.md`
+     * which the agent reads on its first turn after reset.
+     *
+     * Refuses to reset Planner without `force: true` — Planner reset throws away
+     * the user-conversation context and must be a deliberate action.
+     */
+    resetAgent(agent: 'planner' | 'coder' | 'reviewer', opts?: {
+        force?: boolean;
+        eagerRestart?: boolean;
+    }): Promise<void>;
+    /**
+     * Wrap a subagent send. If the underlying session throws or returns an
+     * error string, auto-reset the subagent once and retry. Used by
+     * deliverToCoder / deliverToReviewer to recover from subprocess deaths.
+     */
+    private sendWithRecovery;
+    private lastCompactAt;
+    private compactSummaryFor;
+    private maybeCompact;
+    private ensurePlanner;
+    private deliverToPlanner;
+    private ensureCoder;
+    private deliverToCoder;
+    private ensureReviewer;
+    /**
+     * Stage the iter's artifacts into the Reviewer sandbox cwd. Reviewer is a
+     * persistent session whose cwd is fixed at <ledger>/reviewer_sandbox/, so
+     * every review must rewrite the sandbox to "this iter's view".
+     */
+    private stageReviewSandbox;
+    private deliverToReviewer;
+    private persistVerdict;
+    /** Run a git command in the workspace; returns combined output. Used by Coder commits. */
+    private runGit;
+    private gitCommit;
+}