@syntax-syllogism/aloop 0.5.0

package/presets/work-item/prompts/review.md

@@ -0,0 +1,77 @@
+{{TASK_CONTEXT}}
+
+Take on the role of a Sr. Dev. Your job is to review all work on the branch for
+quality, following best practice and bugs. This work is in reference to task
+`{{TASK_NAME}}`. Implemented on branch `{{BRANCH}}` in the worktree at
+`{{REPO}}`.
+
+If a task file is present (`{{TASK_FILE}}`), add your notes to its `## Code Review`
+section, creating the section at the end of the file if it is absent. Start with Date
+AND Time as there may be multiple rounds of code reviews. Provide a summary of your
+review and note any gaps in completion of the task.
+
+The implementation, repair, and documentation phases commit their work. The
+worktree should be clean; confirm that with `git status`. Review the complete
+cumulative branch diff with `git diff {{BASE_BRANCH}}...HEAD`, including all
+new files. Review all of it, not a sample.
+
+This is review round {{ROUND}} of at most {{MAX_ROUNDS}}.
+
+Deterministic gate status: {{GATE_STATUS}}
+
+## If this is round 2 or later
+
+The previous review ended at commit `{{SINCE_SHA}}`. First inspect the
+incremental response with `git diff {{SINCE_SHA}}..HEAD` to confirm all findings
+from the previous round have been addressed. Then sanity-check the cumulative
+branch diff for regressions elsewhere. Report only blocking issues — style
+preferences and minor suggestions burn a round without improving the merge.
+Note explicitly which previous findings are now resolved and which are not.
+
+## Findings
+
+Cite `file:line` in the cumulative branch diff for every finding. A finding you
+cannot point to there is not a finding.
+
+Classify each by severity:
+
+- 🔴 **Blocker** — must fix before merge (bugs, security, broken spec alignment).
+- 🟡 **Major** — should fix; meaningful correctness or quality concern.
+- 🟢 **Minor** — nice to fix; style, small refactors.
+- 💬 **Nit/Question** — optional, or a request for clarification.
+
+Do not bury blockers under nits. Watch specifically for tests deleted, skipped,
+or weakened to make a gate pass; acceptance criteria in the task that no test
+exercises; changes outside the task's scope; and error paths that swallow failures silently.
+
+Do not fix anything yourself. Reviewing and repairing are separate phases.
+
+## Machine-readable verdict
+
+In addition to your notes in the task file (if present), write this JSON to
+`{{VERDICT_FILE}}`. The loop reads only this file to decide whether to continue
+— it does not read your prose or your stdout.
+
+```json
+{
+  "verdict": "APPROVED | CHANGES_REQUESTED",
+  "summary": "one line",
+  "blocking": [
+    { "file": "src/x.ts", "line": 42, "issue": "what is wrong and what to do" }
+  ],
+  "nits": [
+    { "file": "src/y.ts", "line": 7, "issue": "..." }
+  ]
+}
+```
+
+Rules the loop enforces — violating them stalls the run:
+
+- `blocking` holds every 🔴 and 🟡 finding. `nits` holds 🟢 and 💬.
+- `CHANGES_REQUESTED` requires at least one entry in `blocking`.
+- `APPROVED` requires `blocking` to be empty.
+- Approve only if you would merge this as-is. If the gate status above is
+  FAILING, the verdict is `CHANGES_REQUESTED` regardless of code quality.
+
+Approving weak work is a worse failure than requesting one more round. So is
+inventing a finding to look thorough — if the work is genuinely ready, approve it.

package/prompts/address.md

@@ -0,0 +1,59 @@
+{{TASK_CONTEXT}}
+
+The structured review verdict is recorded in `{{VERDICT_FILE}}`, and the full
+prose review is in `{{RUN_DIR}}/review-round-{{ROUND}}.md`. Address all blocking
+findings.
+
+The work is in the worktree at `{{REPO}}` on branch `{{BRANCH}}`; prior phases
+have committed their changes.
+
+This is round {{ROUND}} of at most {{MAX_ROUNDS}}. If the findings are not
+resolved by round {{MAX_ROUNDS}} the run stops and a human picks it up, so fix
+causes rather than symptoms.
+
+## Blocking findings
+
+{{FINDINGS}}
+
+Write any rebuttal to `{{RUN_DIR}}/response-round-{{ROUND}}.md`.
+
+## Deterministic gate
+
+{{GATE_STATUS}}
+
+If the gate is failing, that is your first priority — the review cannot clear
+while it is red.
+
+## How to respond
+
+Address every blocking finding. For each one, either fix it or — if you believe
+the reviewer is wrong — leave the code as it is and record a short rebuttal in
+`{{RUN_DIR}}/response-round-{{ROUND}}.md`, naming the finding and your reasoning.
+A disagreement recorded in writing is a legitimate outcome; silently ignoring a
+finding is not.
+
+Do not:
+
+- Delete, skip, or weaken a test to make a finding or a gate go away. If a test
+  is genuinely wrong, fix the test and explain why in the response file.
+- Fix anything the reviewer did not raise. Unrelated changes make the next
+  review round harder and can introduce new findings.
+
+Scope and token discipline from the implementation phase still apply: work from
+the files the findings name, keep command output short, and summarize before
+editing.
+
+## Verification
+
+Run the targeted tests for what you changed, then the gate commands:
+
+```
+{{GATE_COMMANDS}}
+```
+
+Judge them by process exit code on unfiltered output.
+
+At the end of the phase, commit the fixes and their tests in a conventional
+commit whose message names the review findings addressed. Keep the worktree
+clean for the next phase. If there is nothing to commit, leave the worktree
+clean.

package/prompts/docs.md

@@ -0,0 +1,23 @@
+{{TASK_CONTEXT}}
+
+Do a documentation-as-built pass for the committed work on branch `{{BRANCH}}`,
+in the worktree at `{{REPO}}`.
+
+This is a documentation reconciliation pass only. Do not make code changes
+unless they are strictly necessary to correct documentation generation or a
+broken reference.
+
+Audit the final as-built state and update whatever durable documentation the
+change affects: README files, docs/, or concise inline documentation. If the
+documentation is already accurate, make no changes.
+
+After the pass, run the smallest meaningful verification checks for
+documentation changes, such as checking links and paths by inspection and
+reviewing the documentation diff.
+
+If you find a bug while reading, note it in your final summary rather than
+fixing it; a code change at this point would go out unreviewed.
+
+At the end of the phase, commit documentation changes in a `docs:` conventional
+commit. Keep the worktree clean for the next phase. If the documentation is
+already accurate, make no changes and leave the worktree clean.

package/prompts/git.md

@@ -0,0 +1,29 @@
+{{TASK_CONTEXT}}
+
+The code-producing phases have already committed their work in `{{REPO}}`, on
+branch `{{BRANCH}}`.
+
+Verify the worktree is clean and do not create any code commits in this phase.
+
+- Inspect the full worktree and recent branch history before pushing.
+- Do _NOT_ include notes about co-author / author.
+- Report the existing code commit hashes and messages, validation performed,
+  and whether the worktree is clean.
+- Push to `{{REMOTE}}` and create a PR to `{{BASE_BRANCH}}` on the same repo. PR
+  body should be < 250 words.
+
+The PR body should cover what changed and why, a summary of the task, the review
+outcome (how many rounds, plus any recorded disagreements), and anything
+deliberately left out of scope.
+
+## Boundaries
+
+- If the worktree is **not** clean — `git status --porcelain` reports anything —
+  do **not** edit files, tests, or configuration to make it clean, and do not
+  create commits. A dirty tree at this phase is a pipeline error: stop
+  immediately and report the offending paths. Reconciling it is out of scope.
+- **Do not merge the pull request**, and do not enable auto-merge. A human
+  decides; an open PR is the correct end state for this run.
+- Never force-push, and never rewrite commits that already exist on `{{REMOTE}}`.
+- If the push is rejected because the branch moved, stop and report it rather
+  than forcing anything.

package/prompts/implement.md

@@ -0,0 +1,45 @@
+{{TASK_CONTEXT}}
+
+Work in the worktree at
+`{{REPO}}`, on the existing branch `{{BRANCH}}` based on `{{BASE_BRANCH}}`.
+Do not create or switch branches.
+
+Skip any steps that require manual human intervention. Implement the task from
+start to finish.
+
+This run is unattended, so you cannot ask clarifying questions. Where you would
+have asked, choose the reading most consistent with the task and the surrounding
+code, and record the question and assumption in `{{RUN_DIR}}/notes.md`. If a
+step genuinely cannot proceed without a human, implement everything else and
+record what you skipped and why in that file.
+
+Scope:
+
+- Start with the files referenced in the task.
+- Do _not_ scan or explore the whole repo.
+- Only read additional files if they are imported or referenced in the task.
+
+Token discipline:
+
+- Keep command output short.
+- Summarize findings before editing.
+
+Verification:
+
+- Add or update targeted tests.
+- Run only the relevant test file first.
+- Run broader tests after the targeted test passes.
+- These commands gate the work and will be run against your changes, so run
+  them yourself before finishing:
+
+```
+{{GATE_COMMANDS}}
+```
+
+- Judge them by process exit code on unfiltered output. A wrapper that
+  summarizes output can report a failure the tool never produced, and a cached
+  build can report success without compiling anything.
+- At the end of the phase, commit the implementation and its targeted tests in
+  a conventional commit. Keep the worktree clean for the next phase.
+- End your turn with a summary and next steps if applicable. The loop runs the
+  code review next, so you do not need to ask for one.

package/prompts/review.md

@@ -0,0 +1,74 @@
+{{TASK_CONTEXT}}
+
+Take on the role of a senior developer. Review all work on branch `{{BRANCH}}`
+in the worktree at `{{REPO}}` for bugs, quality, and alignment with the task.
+
+Write your prose review to `{{RUN_DIR}}/review-round-{{ROUND}}.md`. Include a
+summary of the review and any gaps in completion of the task.
+
+The implementation, repair, and documentation phases commit their work. The
+worktree should be clean; confirm that with `git status`. Review the complete
+cumulative branch diff with `git diff {{BASE_BRANCH}}...HEAD`, including all
+new files. Review all of it, not a sample.
+
+This is review round {{ROUND}} of at most {{MAX_ROUNDS}}.
+
+Deterministic gate status: {{GATE_STATUS}}
+
+## If this is round 2 or later
+
+The previous review ended at commit `{{SINCE_SHA}}`. First inspect the
+incremental response with `git diff {{SINCE_SHA}}..HEAD` to confirm all findings
+from the previous round have been addressed. Then sanity-check the cumulative
+branch diff for regressions elsewhere. Report only blocking issues — style
+preferences and minor suggestions burn a round without improving the merge.
+Note explicitly which previous findings are now resolved and which are not.
+
+## Findings
+
+Cite `file:line` in the cumulative branch diff for every finding. A finding you
+cannot point to there is not a finding.
+
+Classify each by severity:
+
+- 🔴 **Blocker** — must fix before merge (bugs, security, broken spec alignment).
+- 🟡 **Major** — should fix; meaningful correctness or quality concern.
+- 🟢 **Minor** — nice to fix; style, small refactors.
+- 💬 **Nit/Question** — optional, or a request for clarification.
+
+Do not bury blockers under nits. Watch specifically for tests deleted, skipped,
+or weakened to make a gate pass; acceptance criteria in the task that no test
+exercises; changes outside the task's scope; and error paths that swallow
+failures silently.
+
+Do not fix anything yourself. Reviewing and repairing are separate phases.
+
+## Machine-readable verdict
+
+In addition to your prose review, write this JSON to `{{VERDICT_FILE}}`. The
+loop reads only this file to decide whether to continue — it does not read your
+prose or your stdout.
+
+```json
+{
+  "verdict": "APPROVED | CHANGES_REQUESTED",
+  "summary": "one line",
+  "blocking": [
+    { "file": "src/x.ts", "line": 42, "issue": "what is wrong and what to do" }
+  ],
+  "nits": [
+    { "file": "src/y.ts", "line": 7, "issue": "..." }
+  ]
+}
+```
+
+Rules the loop enforces — violating them stalls the run:
+
+- `blocking` holds every 🔴 and 🟡 finding. `nits` holds 🟢 and 💬.
+- `CHANGES_REQUESTED` requires at least one entry in `blocking`.
+- `APPROVED` requires `blocking` to be empty.
+- Approve only if you would merge this as-is. If the gate status above is
+  FAILING, the verdict is `CHANGES_REQUESTED` regardless of code quality.
+
+Approving weak work is a worse failure than requesting one more round. So is
+inventing a finding to look thorough — if the work is genuinely ready, approve it.

package/src/adapters.mjs

@@ -0,0 +1,281 @@
+/**
+ * Engine adapters.
+ *
+ * Every adapter turns the same request — a prompt, a working directory, and a
+ * set of extra writable directories — into one CLI invocation. That is the
+ * entire portability story: phases, prompts, and the verdict contract are
+ * shared, and only this file knows which vendor is running.
+ *
+ * Adapters deliberately do not parse stdout for *results*. Steps communicate by
+ * writing files the runner reads, because stdout formats are per-vendor and
+ * change between releases while a JSON file on disk does not.
+ *
+ * Rendering progress is the one exception, and it stays here for the same
+ * reason: only this file knows a vendor's stdout format. An adapter may expose
+ * `createRenderer()` to turn its stdout into human-readable lines; the runner
+ * treats the result as opaque text.
+ */
+
+/** Fields worth showing for a tool call, most specific first. */
+const toolSummaryFields = ['command', 'file_path', 'pattern', 'path', 'url', 'description', 'prompt'];
+
+function condense(text, limit = 120) {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > limit ? `${flat.slice(0, limit - 1)}\u2026` : flat;
+}
+
+function summarizeToolInput(input) {
+  if (!input || typeof input !== 'object') return '';
+  for (const field of toolSummaryFields) {
+    if (typeof input[field] === 'string' && input[field].trim()) return condense(input[field]);
+  }
+  return '';
+}
+
+/**
+ * Summarize an agy tool call's parameters.
+ *
+ * agy names its parameters differently from Claude (`CommandLine`, `AbsolutePath`,
+ * …), so try the most descriptive keys first and fall back to the first string
+ * value — robust to tools this list has never seen.
+ */
+function summarizeAgyParams(params) {
+  if (!params || typeof params !== 'object') return '';
+  const preferred = ['CommandLine', 'Command', 'AbsolutePath', 'FilePath', 'Path', 'Query', 'Url', 'Pattern'];
+  for (const key of preferred) {
+    if (typeof params[key] === 'string' && params[key].trim()) return condense(params[key]);
+  }
+  for (const value of Object.values(params)) {
+    if (typeof value === 'string' && value.trim()) return condense(value);
+  }
+  return '';
+}
+
+function renderClaudeBlock(block) {
+  if (block.type === 'text') return block.text?.trim() ? `${block.text.trimEnd()}\n` : '';
+  if (block.type === 'thinking') return '  \u00b7 thinking\n';
+  if (block.type === 'tool_use') {
+    const detail = summarizeToolInput(block.input);
+    return `  \u2192 ${block.name}${detail ? ` ${detail}` : ''}\n`;
+  }
+  return '';
+}
+
+/**
+ * Turn one Claude stream-json event into the line a watching human wants.
+ *
+ * Unrecognized events render as nothing rather than raw JSON: the vendor adds
+ * event types between releases, and a log that dumps every one of them is as
+ * unreadable as no log at all.
+ */
+export function renderClaudeEvent(event) {
+  if (event.type === 'assistant') return (event.message?.content ?? []).map(renderClaudeBlock).join('');
+  if (event.type === 'user') {
+    return (event.message?.content ?? [])
+      .filter((block) => block.type === 'tool_result' && block.is_error)
+      .map((block) => `  \u2717 ${condense(String(block.content ?? 'tool call failed'), 160)}\n`)
+      .join('');
+  }
+  if (event.type === 'system' && event.subtype === 'init') {
+    return `  \u00b7 session ${String(event.session_id ?? '').slice(0, 8)}${event.model ? ` model ${event.model}` : ''}\n`;
+  }
+  if (event.type === 'system' && event.subtype === 'permission_denied') {
+    return `  \u26a0 permission denied: ${event.tool_name ?? 'tool'}\n`;
+  }
+  if (event.type === 'result') {
+    const turns = event.num_turns ? ` ${event.num_turns} turns` : '';
+    const seconds = event.duration_ms ? ` ${Math.round(event.duration_ms / 1000)}s` : '';
+    return `  ${event.is_error ? '\u2717 failed' : '\u2713 done'}${turns}${seconds}\n`;
+  }
+  return '';
+}
+
+/**
+ * Turn one agy stream-json event into the line a watching human wants.
+ *
+ * agy's events are `init` (session), `step_update` (per-step progress: user
+ * input, agent text deltas, tool calls), and `result` (final status). As with
+ * the Claude renderer, an unrecognized shape renders as nothing rather than raw
+ * JSON — notably the enormous `init` tool list is collapsed to one line.
+ */
+export function renderAgyEvent(event) {
+  if (event.event === 'init') {
+    const id = String(event.conversation_id ?? '').slice(0, 8);
+    const model = event.init?.model;
+    return `  · session ${id}${model ? ` model ${model}` : ''}\n`;
+  }
+  if (event.event === 'step_update') {
+    const step = event.step_update ?? {};
+    // Assistant text arrives as deltas; stream them through verbatim.
+    if (step.step_type === 'agent_response' && typeof step.text_delta === 'string') return step.text_delta;
+    if (step.step_type === 'tool') {
+      if (step.state === 'ACTIVE') {
+        const detail = summarizeAgyParams(step.tool_info?.parameters);
+        return `  → ${step.tool_name ?? 'tool'}${detail ? ` ${detail}` : ''}\n`;
+      }
+      if (step.state === 'DONE' && step.tool_info?.error) {
+        return `  ✗ ${condense(String(step.tool_info.error), 160)}\n`;
+      }
+    }
+    return '';
+  }
+  if (event.event === 'result') {
+    const result = event.result ?? {};
+    const turns = result.num_turns ? ` ${result.num_turns} turn${result.num_turns === 1 ? '' : 's'}` : '';
+    const seconds = result.duration_seconds ? ` ${Math.round(result.duration_seconds)}s` : '';
+    if (result.status && result.status !== 'SUCCESS') {
+      const why = result.error ? `: ${condense(String(result.error), 160)}` : '';
+      return `  ✗ ${String(result.status).toLowerCase()}${why}${turns}${seconds}\n`;
+    }
+    return `  ✓ done${turns}${seconds}\n`;
+  }
+  return '';
+}
+
+/**
+ * Line-buffer a JSONL stream and render each complete event.
+ *
+ * Chunks split mid-line, so the tail is held until its newline arrives. A line
+ * that is not JSON passes through untouched — that is how a vendor warning
+ * printed alongside the stream still reaches the log.
+ */
+export function createJsonlRenderer(renderEvent) {
+  let pending = '';
+  const renderLine = (line) => {
+    if (!line.trim()) return '';
+    try {
+      return renderEvent(JSON.parse(line));
+    } catch {
+      return `${line}\n`;
+    }
+  };
+  return {
+    write(text) {
+      pending += text;
+      const lines = pending.split('\n');
+      pending = lines.pop() ?? '';
+      return lines.map(renderLine).join('');
+    },
+    end() {
+      const rest = pending;
+      pending = '';
+      return renderLine(rest);
+    },
+  };
+}
+
+/** A renderer for engines whose stdout is already meant to be read. */
+export function passthroughRenderer() {
+  return { write: (text) => text, end: () => '' };
+}
+
+const claudeAdapter = {
+  name: 'claude',
+  efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+  command({ prompt, addDirs, agent = {} }) {
+    // `auto`, not `acceptEdits`: under acceptEdits a non-interactive `-p` run
+    // auto-denies every Bash call, because there is no one to answer the
+    // prompt it raises. Phases that have to build, test, and commit then spin
+    // until the timeout kills them.
+    // stream-json, not text: `--output-format text` withholds every byte until
+    // the process exits, so a phase that runs for half an hour looks identical
+    // to one that has hung. stream-json emits an event per step, which
+    // `createRenderer` turns back into readable lines.
+    const args = ['-p', prompt, '--permission-mode', 'auto', '--output-format', 'stream-json', '--verbose'];
+    if (agent.model) args.push('--model', agent.model);
+    if (agent.effort) args.push('--effort', agent.effort);
+    for (const dir of addDirs) args.push('--add-dir', dir);
+    return { command: 'claude', args };
+  },
+  createRenderer: () => createJsonlRenderer(renderClaudeEvent),
+};
+
+const codexAdapter = {
+  name: 'codex',
+  efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+  command({ prompt, cwd, addDirs, agent = {} }) {
+    const args = ['exec', prompt, '--sandbox', 'workspace-write', '--cd', cwd];
+    if (agent.model) args.push('--model', agent.model);
+    if (agent.effort) args.push('-c', `model_reasoning_effort=${JSON.stringify(agent.effort)}`);
+    for (const dir of addDirs) args.push('--add-dir', dir);
+    return { command: 'codex', args };
+  },
+};
+
+const agyAdapter = {
+  name: 'agy',
+  efforts: ['low', 'medium', 'high'],
+  command({ prompt, addDirs, timeoutMs, agent = {} }) {
+    // `--dangerously-skip-permissions`, not bare `accept-edits`: in headless
+    // `--print` mode agy cannot prompt for the `command` permission its Bash-
+    // style tools need, so it auto-denies the first one and exits 0 having done
+    // nothing — the phase then "completes" instantly with an empty log. This is
+    // agy's equivalent of the claude adapter's `--permission-mode auto` above;
+    // agy has no `auto` mode (`--mode` is accept-edits|plan only).
+    //
+    // stream-json, not the default `text`: agy's text output withholds every
+    // byte until the process exits, so a multi-minute phase is indistinguishable
+    // from a hang (the run log shows only the header). stream-json emits an
+    // event per step, which `createRenderer` turns back into readable lines —
+    // same reasoning as the claude adapter above.
+    const args = [
+      '--print', prompt,
+      '--mode', 'accept-edits',
+      '--dangerously-skip-permissions',
+      '--output-format', 'stream-json',
+    ];
+    if (agent.model) args.push('--model', agent.model);
+    if (agent.effort) args.push('--effort', agent.effort);
+    if (timeoutMs) args.push('--print-timeout', `${Math.ceil(timeoutMs / 1000)}s`);
+    for (const dir of addDirs) args.push('--add-dir', dir);
+    return { command: 'agy', args };
+  },
+  createRenderer: () => createJsonlRenderer(renderAgyEvent),
+};
+
+const adapters = { claude: claudeAdapter, codex: codexAdapter, agy: agyAdapter };
+
+function validateConfiguredAdapter(name, adapter) {
+  if (!adapter || typeof adapter !== 'object' || Array.isArray(adapter) || typeof adapter.command !== 'function') {
+    throw new Error(`Invalid adapter "${name}": expected an object with a command function.`);
+  }
+  if (adapter.efforts !== undefined && (!Array.isArray(adapter.efforts) || adapter.efforts.some((effort) => typeof effort !== 'string'))) {
+    throw new Error(`Invalid adapter "${name}": efforts must be an array of strings.`);
+  }
+  if (adapter.createRenderer !== undefined && typeof adapter.createRenderer !== 'function') {
+    throw new Error(`Invalid adapter "${name}": createRenderer must be a function.`);
+  }
+  return adapter;
+}
+
+export function adapterFor(engine, customAdapters = {}) {
+  const configuredNames = customAdapters && typeof customAdapters === 'object' ? Object.keys(customAdapters) : [];
+  const hasConfiguredAdapter = customAdapters && typeof customAdapters === 'object'
+    && Object.hasOwn(customAdapters, engine);
+  const adapter = hasConfiguredAdapter ? validateConfiguredAdapter(engine, customAdapters[engine]) : adapters[engine];
+  if (!adapter) {
+    const available = [...new Set([...Object.keys(adapters), ...configuredNames])];
+    throw new Error(`Unsupported engine "${engine}"; expected one of ${available.join(', ')}.`);
+  }
+  return adapter;
+}
+
+export function validateAgent(agent, customAdapters = {}) {
+  const adapter = adapterFor(agent.name, customAdapters);
+  if (agent.effort && adapter.efforts && !adapter.efforts.includes(agent.effort)) {
+    throw new Error(`Engine "${agent.name}" does not support effort "${agent.effort}"; expected one of ${adapter.efforts.join(', ')}.`);
+  }
+  return agent;
+}
+
+/** Resolve an agent descriptor: per-phase override, else the default. */
+export function agentForPhase(config, phaseName) {
+  return config.engines[phaseName] ?? config.engines.default;
+}
+
+/** Resolve which executable runs a phase. Retained for string-based callers. */
+export function engineForPhase(config, phaseName) {
+  return agentForPhase(config, phaseName).name;
+}
+
+export { adapters };

package/src/command.mjs

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Run a command, capturing its output while optionally streaming it onward.
+ *
+ * Agent phases run for minutes at a time, so unlike a buffered helper this one
+ * forwards each chunk to `onOutput` as it arrives — a run you cannot watch is a
+ * run you cannot debug. `timeoutMs` exists because a silently hung agent is the
+ * most common unattended failure and it burns tokens for as long as it hangs.
+ */
+export async function runCommand(command, args = [], options = {}) {
+  const { cwd, env = process.env, timeoutMs, onOutput, input } = options;
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          timedOut = true;
+          child.kill('SIGKILL');
+        }, timeoutMs)
+      : null;
+
+    const collect = (stream, name) => {
+      stream.on('data', (chunk) => {
+        const text = String(chunk);
+        if (name === 'stdout') stdout += text;
+        else stderr += text;
+        onOutput?.(text, name);
+      });
+    };
+    collect(child.stdout, 'stdout');
+    collect(child.stderr, 'stderr');
+
+    const decorate = (error) => {
+      if (timer) clearTimeout(timer);
+      error.command = [command, ...args].join(' ');
+      error.stdout = stdout;
+      error.stderr = stderr;
+      error.output = [stdout, stderr].filter(Boolean).join('\n');
+      error.timedOut = timedOut;
+      return error;
+    };
+
+    child.on('error', (error) => reject(decorate(error)));
+    child.on('close', (code, signal) => {
+      if (timer) clearTimeout(timer);
+      if (timedOut) {
+        const error = decorate(new Error(`Command timed out after ${timeoutMs}ms: ${command} ${args.join(' ')}`));
+        error.code = 'ETIMEDOUT';
+        return reject(error);
+      }
+      if (code === 0) return resolve({ stdout, stderr, code });
+      const error = decorate(new Error(`Command failed: ${command} ${args.join(' ')}${stderr ? `\n${stderr}` : ''}`));
+      error.code = code;
+      error.signal = signal;
+      return reject(error);
+    });
+
+    if (input !== undefined) child.stdin.end(input);
+    else child.stdin.end();
+  });
+}