chainlesschain 0.162.35 → 0.162.37

package/src/lib/ide-bridge.js

@@ -0,0 +1,310 @@
+/**
+ * IDE bridge discovery (Phase 0) — find a first-party IDE MCP server that an
+ * editor extension advertises via a lockfile, and turn it into an MCP server
+ * config the agent loop can connect to.
+ *
+ * Protocol (design: docs/design/modules/98_IDE桥接对标方案.md): each running
+ * IDE instance writes
+ *     ~/.chainlesschain/ide/<port>.json     (file 0600, dir 0700)
+ * describing a localhost SSE/HTTP MCP server + a per-instance bearer token.
+ * The extension that owns the integrated terminal ALSO injects
+ *     CHAINLESSCHAIN_IDE_PORT   (+ optional CHAINLESSCHAIN_IDE_TOKEN)
+ * so the CLI can lock onto the exact instance without scanning/guessing
+ * (the deterministic "path A" below). Plain terminals fall back to a lockfile
+ * scan + workspace match ("path B").
+ *
+ * Phase 0 is pure CLI: no extension code, no VS Code dependency, fully
+ * unit-testable through `_deps`. The connect path itself reuses the existing
+ * MCP client (SSE/HTTP) via mcp-config.js `loadIdeMcp`.
+ */
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+/** A lock whose pid is dead and whose file is older than this = stale. */
+const STALE_TTL_MS = 30_000;
+
+/** Transports the CLI's MCP client can actually talk (see mcp-client.js). */
+const SUPPORTED_TRANSPORTS = new Set(["sse", "http", "https"]);
+
+/** Liveness probe via signal 0 — cross-platform (works on Windows too). */
+function defaultProcessAlive(pid) {
+  if (!pid || typeof pid !== "number") return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the process exists but we may not signal it → still alive.
+    return !!(err && err.code === "EPERM");
+  }
+}
+
+export const _deps = {
+  readDir: (d) => fs.readdirSync(d),
+  readFile: (p) => fs.readFileSync(p, "utf-8"),
+  statMtimeMs: (p) => fs.statSync(p).mtimeMs,
+  homedir: () => os.homedir(),
+  now: () => Date.now(),
+  processAlive: defaultProcessAlive,
+};
+
+/** `~/.chainlesschain/ide/`. */
+export function ideLockDir(deps = _deps) {
+  return path.join(deps.homedir(), ".chainlesschain", "ide");
+}
+
+function isLocalhostUrl(url) {
+  try {
+    const u = new URL(url);
+    return u.hostname === "127.0.0.1" || u.hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+
+function inferTransportFromUrl(url) {
+  if (/\/sse(\b|\/|$)/i.test(url)) return "sse";
+  if (/^https:/i.test(url)) return "https";
+  if (/^http:/i.test(url)) return "http";
+  return null;
+}
+
+/** Parse + validate one lock JSON. Returns a normalized lock or null. */
+function parseLock(raw, filePath) {
+  let lock;
+  try {
+    lock = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!lock || typeof lock !== "object") return null;
+  if (!lock.url || !isLocalhostUrl(lock.url)) return null;
+
+  const transport = String(
+    lock.transport || inferTransportFromUrl(lock.url) || "",
+  ).toLowerCase();
+  if (!SUPPORTED_TRANSPORTS.has(transport)) return null; // e.g. ws — not yet
+
+  let folders = lock.workspaceFolders;
+  if (typeof folders === "string") folders = [folders];
+  if (!Array.isArray(folders)) folders = [];
+  folders = folders.filter((f) => typeof f === "string" && f.length > 0);
+
+  return {
+    ide: typeof lock.ide === "string" ? lock.ide : "unknown",
+    transport,
+    url: lock.url,
+    port: lock.port,
+    token: typeof lock.token === "string" ? lock.token : null,
+    workspaceFolders: folders,
+    pid: typeof lock.pid === "number" ? lock.pid : null,
+    startedAt: typeof lock.started_at === "number" ? lock.started_at : 0,
+    _file: filePath,
+  };
+}
+
+/** True when a lock is dead: pid gone AND file older than the TTL. */
+function isStale(lock, deps) {
+  if (lock.pid && deps.processAlive(lock.pid)) return false;
+  let mtime;
+  try {
+    mtime = deps.statMtimeMs(lock._file);
+  } catch {
+    return true;
+  }
+  return deps.now() - mtime > STALE_TTL_MS;
+}
+
+/**
+ * Scan the lock dir → normalized, live, localhost, supported-transport locks.
+ * Missing dir / unreadable files are silently skipped (best-effort).
+ */
+export function readIdeLocks(deps = _deps) {
+  const dir = ideLockDir(deps);
+  let names;
+  try {
+    names = deps.readDir(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names || []) {
+    if (!String(name).endsWith(".json")) continue;
+    const fp = path.join(dir, name);
+    let raw;
+    try {
+      raw = deps.readFile(fp);
+    } catch {
+      continue;
+    }
+    const lock = parseLock(raw, fp);
+    if (!lock) continue;
+    if (isStale(lock, deps)) continue;
+    out.push(lock);
+  }
+  return out;
+}
+
+/** Are we running inside an editor's integrated terminal? */
+export function isInIdeTerminal(env = process.env) {
+  if (!env) return false;
+  if (env.CHAINLESSCHAIN_IDE_PORT) return true;
+  if (env.TERM_PROGRAM === "vscode") return true;
+  if (env.CHAINLESSCHAIN_IDE) return true;
+  if (env.TERMINAL_EMULATOR && /jetbrains/i.test(env.TERMINAL_EMULATOR)) {
+    return true;
+  }
+  return false;
+}
+
+/** Normalize a path for prefix comparison (sep + trailing slash + win case). */
+function normPath(p) {
+  const s = String(p)
+    .replace(/\\/g, "/")
+    .replace(/\/+$/, "");
+  return process.platform === "win32" ? s.toLowerCase() : s;
+}
+
+/**
+ * Longest matching workspace-folder length for `cwd`, or -1 if none of the
+ * lock's folders contains (or equals) cwd. Longer = more specific.
+ */
+function workspaceMatchScore(lock, cwd) {
+  const c = normPath(cwd);
+  let best = -1;
+  for (const f of lock.workspaceFolders) {
+    const nf = normPath(f);
+    if (c === nf || c.startsWith(nf + "/")) {
+      if (nf.length > best) best = nf.length;
+    }
+  }
+  return best;
+}
+
+/**
+ * Pick the IDE server to connect to, or null.
+ *
+ * Path A (deterministic): if `CHAINLESSCHAIN_IDE_PORT` is set and a live lock
+ *   has that port, use it (token may come from the lock or the env).
+ * Path B (scan): otherwise rank live locks by (longest workspace-prefix match,
+ *   then newest started_at). With `force`, fall back to the newest lock even
+ *   when no folder matches (used by `--ide`).
+ *
+ * @param {object} opts { cwd?, env?, force? }
+ * @param {object} [deps]
+ */
+export function discoverIdeServer(
+  { cwd = process.cwd(), env = process.env, force = false } = {},
+  deps = _deps,
+) {
+  const locks = readIdeLocks(deps);
+  if (!locks.length) return null;
+
+  // Path A — env fast-path.
+  const envPort = env && env.CHAINLESSCHAIN_IDE_PORT;
+  if (envPort) {
+    const hit = locks.find((l) => String(l.port) === String(envPort));
+    if (hit) {
+      if (!hit.token && env.CHAINLESSCHAIN_IDE_TOKEN) {
+        hit.token = env.CHAINLESSCHAIN_IDE_TOKEN;
+      }
+      return hit;
+    }
+    // env named a port with no live lock — fall through to scan.
+  }
+
+  // Path B — workspace match.
+  let best = null;
+  let bestScore = -1;
+  let bestStarted = -1;
+  for (const l of locks) {
+    const score = workspaceMatchScore(l, cwd);
+    if (score < 0) continue;
+    if (
+      score > bestScore ||
+      (score === bestScore && l.startedAt > bestStarted)
+    ) {
+      best = l;
+      bestScore = score;
+      bestStarted = l.startedAt;
+    }
+  }
+  if (best) return best;
+
+  // --ide forced but no workspace match → newest live lock.
+  if (force) {
+    return locks
+      .slice()
+      .sort((a, b) => b.startedAt - a.startedAt)[0];
+  }
+  return null;
+}
+
+/**
+ * A discovered lock → an MCP server config row for `setupMcpFromConfig`.
+ * `longRunning` is forward-compat metadata: IDE tools like `ide_openDiff` may
+ * block on the user for minutes, so the agent loop should exempt them from a
+ * per-call timeout (consumed in Phase 1).
+ */
+export function ideServerToMcpConfig(lock) {
+  if (!lock || !lock.url) return null;
+  const headers = {};
+  if (lock.token) headers.Authorization = `Bearer ${lock.token}`;
+  return {
+    url: lock.url,
+    transport: lock.transport,
+    headers,
+    longRunning: true,
+  };
+}
+
+/**
+ * Human-readable explanation of why discovery did/didn't find a server — backs
+ * `cc ide doctor`. Returns { inIdeTerminal, locks:[{...,reasons?}], chosen,
+ * reason }.
+ */
+export function diagnoseIde(
+  { cwd = process.cwd(), env = process.env, force = false } = {},
+  deps = _deps,
+) {
+  const inIdeTerminal = isInIdeTerminal(env);
+  const locks = readIdeLocks(deps);
+  const chosen = discoverIdeServer({ cwd, env, force }, deps);
+
+  let reason;
+  if (chosen) {
+    reason = env && env.CHAINLESSCHAIN_IDE_PORT &&
+      String(chosen.port) === String(env.CHAINLESSCHAIN_IDE_PORT)
+      ? "matched CHAINLESSCHAIN_IDE_PORT (env fast-path)"
+      : force
+        ? "forced (--ide); newest live lock"
+        : "workspace match";
+  } else if (!locks.length) {
+    reason =
+      "no live IDE lockfiles in " +
+      ideLockDir(deps) +
+      " (is an IDE extension running? are locks stale?)";
+  } else {
+    reason =
+      "lockfiles present but none match cwd's workspace " +
+      "(run with --ide to force the newest, or cd into the IDE workspace)";
+  }
+  return {
+    inIdeTerminal,
+    lockDir: ideLockDir(deps),
+    locks: locks.map((l) => ({
+      ide: l.ide,
+      port: l.port,
+      transport: l.transport,
+      url: l.url,
+      hasToken: !!l.token,
+      workspaceFolders: l.workspaceFolders,
+      pid: l.pid,
+      matchScore: workspaceMatchScore(l, cwd),
+    })),
+    chosen: chosen
+      ? { ide: chosen.ide, port: chosen.port, url: chosen.url }
+      : null,
+    reason,
+  };
+}

package/src/lib/image-input.js

@@ -0,0 +1,156 @@
+/**
+ * image-input — multimodal (vision) input for `cc agent`.
+ *
+ * cc's internal message format is OpenAI-shaped, so the internal multimodal
+ * representation is OpenAI's: a user message whose `content` is an array of
+ * `{type:"text"}` / `{type:"image_url", image_url:{url:"data:<media>;base64,..."}}`
+ * parts. The OpenAI-compatible providers (openai/volcengine/deepseek/…) accept
+ * that verbatim, so their branch needs no conversion. ollama and anthropic use
+ * different shapes — `toOllamaMessages` and `imageUrlBlockToAnthropic` convert.
+ *
+ * All functions are pure (except `resolveImages`, which reads files via the
+ * injectable `_deps.fs`).
+ */
+
+import fs from "fs";
+import path from "path";
+
+const EXT_MEDIA = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+
+/**
+ * Read `--image <path>` values into `[{ mediaType, data(base64) }]`.
+ * Throws on an unsupported extension so a typo fails loudly instead of sending
+ * a broken request.
+ */
+export function resolveImages(paths, deps = {}) {
+  const _fs = deps.fs || fs;
+  if (!Array.isArray(paths) || paths.length === 0) return [];
+  return paths.map((p) => {
+    const ext = path.extname(String(p)).toLowerCase();
+    const mediaType = EXT_MEDIA[ext];
+    if (!mediaType) {
+      throw new Error(
+        `Unsupported image type "${ext || p}" — use png/jpg/jpeg/gif/webp.`,
+      );
+    }
+    const data = _fs.readFileSync(p).toString("base64");
+    return { mediaType, data };
+  });
+}
+
+/**
+ * Build a user-message `content`: the plain string when there are no images,
+ * else an OpenAI-style multimodal array (the internal representation).
+ */
+export function buildUserContent(text, images) {
+  if (!Array.isArray(images) || images.length === 0) return text;
+  const parts = [];
+  if (text) parts.push({ type: "text", text });
+  for (const img of images) {
+    parts.push({
+      type: "image_url",
+      image_url: { url: `data:${img.mediaType};base64,${img.data}` },
+    });
+  }
+  return parts;
+}
+
+/** Parse a `data:<media>;base64,<data>` URL into `{ mediaType, data }` or null. */
+export function parseDataUrl(url) {
+  const m = /^data:([^;,]+);base64,(.*)$/s.exec(String(url || ""));
+  return m ? { mediaType: m[1], data: m[2] } : null;
+}
+
+/** True when a message carries any image_url part (i.e. needs provider conversion). */
+export function hasImageContent(messages) {
+  return (messages || []).some(
+    (m) =>
+      Array.isArray(m?.content) &&
+      m.content.some((p) => p?.type === "image_url"),
+  );
+}
+
+/**
+ * Convert OpenAI-shaped multimodal messages for the ollama `/api/chat` body:
+ * ollama wants `{ content: "<text>", images: ["<base64>", …] }` (bare base64,
+ * no `data:` prefix). Non-multimodal messages pass through untouched.
+ */
+export function toOllamaMessages(messages) {
+  return (messages || []).map((m) => {
+    if (!m || !Array.isArray(m.content)) return m;
+    let text = "";
+    const images = [];
+    for (const part of m.content) {
+      if (part?.type === "text") {
+        text += (text ? "\n" : "") + (part.text || "");
+      } else if (part?.type === "image_url") {
+        const parsed = parseDataUrl(part.image_url?.url);
+        if (parsed) images.push(parsed.data);
+        else if (part.image_url?.url) images.push(part.image_url.url);
+      }
+    }
+    const out = { ...m, content: text };
+    if (images.length) out.images = images;
+    return out;
+  });
+}
+
+/**
+ * Convert one OpenAI `image_url` content block into an Anthropic `image` block,
+ * or null when it isn't an image_url block / has no usable data URL.
+ */
+export function imageUrlBlockToAnthropic(block) {
+  if (!block || block.type !== "image_url") return null;
+  const parsed = parseDataUrl(block.image_url?.url);
+  if (!parsed) return null;
+  return {
+    type: "image",
+    source: { type: "base64", media_type: parsed.mediaType, data: parsed.data },
+  };
+}
+
+/** Default vision model (Volcengine Ark Doubao-Seed-1.6 Vision) when none configured. */
+export const DEFAULT_VISION_MODEL = "doubao-seed-1-6-vision-250815";
+
+/**
+ * Resolve the effective LLM config for a run. When an image is attached, default
+ * the provider/model/baseUrl/apiKey to the configured vision LLM so
+ * `cc agent --image foo.png` works without extra flags — using `llm.visionModel`
+ * (a separate, configurable vision model) and falling back to DEFAULT_VISION_MODEL.
+ * Explicit flags always win; with no image, behaviour is unchanged (vision config
+ * is ignored). `--vision-model` overrides the configured/default vision model.
+ *
+ * @param {object} p
+ * @param {boolean} p.hasImage  true when the run carries an attached image
+ * @param {object}  p.flags     { provider, model, baseUrl, apiKey, visionModel }
+ * @param {object}  p.llm       config.llm ({ provider, model, baseUrl, apiKey, visionModel })
+ * @returns {{provider, model, baseUrl, apiKey}}
+ */
+export function resolveVisionLlm({ hasImage, flags = {}, llm = {} } = {}) {
+  // No image → no vision override; the caller falls back to its normal LLM
+  // config (`visionLlm.x || options.x`).
+  if (!hasImage) {
+    return {
+      provider: undefined,
+      model: undefined,
+      baseUrl: undefined,
+      apiKey: undefined,
+    };
+  }
+  const visionModel =
+    flags.visionModel || llm.visionModel || DEFAULT_VISION_MODEL;
+  // `flags.model` must be the EXPLICIT `--model` (not a settings/default), so an
+  // attached image uses the vision model unless the user deliberately picked one.
+  return {
+    provider: flags.provider || llm.provider,
+    model: flags.model || visionModel,
+    baseUrl: flags.baseUrl || llm.baseUrl,
+    apiKey: flags.apiKey || llm.apiKey,
+  };
+}

package/src/lib/loop.js

@@ -0,0 +1,198 @@
+/**
+ * cc loop — core driver (pure, dependency-injected) for the fixed-interval
+ * loop runner. The command layer (src/commands/loop.js) supplies a concrete
+ * `runIteration` (spawns a child process) plus a real clock; everything here
+ * is side-effect-free and clock-injected so the loop semantics — iteration
+ * counting, stop conditions, between-run delay — are deterministically
+ * testable without timers or subprocesses.
+ *
+ * Claude-Code `/loop` parity (fixed-interval MVP): run a command or agent
+ * prompt repeatedly until a stop condition fires (max iterations / exit 0 /
+ * output match) or the caller aborts (Ctrl-C).
+ */
+
+/** Multipliers for the duration suffixes we accept. */
+const DURATION_UNITS = { ms: 1, s: 1000, m: 60000, h: 3600000 };
+
+/**
+ * Parse a human interval ("30s", "5m", "1.5h", "500ms") into milliseconds.
+ * A bare number is interpreted as SECONDS (the natural unit for an interval),
+ * so `--every 30` === `--every 30s`. Throws on anything unparseable.
+ */
+export function parseDuration(input) {
+  if (typeof input === "number" && Number.isFinite(input)) {
+    return Math.max(0, Math.round(input));
+  }
+  const s = String(input ?? "")
+    .trim()
+    .toLowerCase();
+  const m = s.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/);
+  if (!m) {
+    throw new Error(
+      `invalid duration: "${input}" (use 30s, 5m, 1.5h, or 500ms)`,
+    );
+  }
+  const value = parseFloat(m[1]);
+  const unit = m[2] || "s"; // bare number → seconds
+  return Math.round(value * DURATION_UNITS[unit]);
+}
+
+/** Render a millisecond duration back to a compact human string. */
+export function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${trim(ms / 1000)}s`;
+  if (ms < 3600000) return `${trim(ms / 60000)}m`;
+  return `${trim(ms / 3600000)}h`;
+}
+
+function trim(n) {
+  // Strip trailing ".0" so 5.0 → "5" but 1.5 stays "1.5".
+  return Number.isInteger(n) ? String(n) : n.toFixed(2).replace(/\.?0+$/, "");
+}
+
+/**
+ * Parse the `--dynamic` control directives an iteration may print so it can
+ * self-pace. An iteration ends its output with at most one of:
+ *   [[loop:next <interval>]]   schedule the next run after <interval>
+ *   [[loop:stop]]              the task is done; stop looping
+ * Returns { done, nextDelayMs }. `stop` wins over `next` (done short-circuits
+ * before the next sleep). A malformed interval is ignored (falls back to the
+ * fixed `--every`). Lives here so the protocol is unit-testable in isolation.
+ */
+export function parseLoopDirectives(output) {
+  const text = String(output || "");
+  const result = { done: false, nextDelayMs: null };
+  if (/\[\[\s*loop:stop\s*\]\]/i.test(text)) result.done = true;
+  const m = text.match(/\[\[\s*loop:next\s+([0-9.]+\s*(?:ms|s|m|h)?)\s*\]\]/i);
+  if (m) {
+    try {
+      result.nextDelayMs = parseDuration(m[1]);
+    } catch {
+      /* malformed interval → leave null, caller falls back to --every */
+    }
+  }
+  return result;
+}
+
+/**
+ * Reduce a persisted loop session's events into the state needed to resume it:
+ * the original `loop_config`, how many iterations already completed, and the
+ * last recorded exit code. Pure (operates on the event array, no fs) so the
+ * resume reconstruction is unit-testable without the session store.
+ */
+export function summarizeLoopEvents(events) {
+  let config = null;
+  let completedIterations = 0;
+  let lastExitCode = null;
+  for (const e of events || []) {
+    if (e?.type === "loop_config") {
+      config = e.data || null;
+    } else if (e?.type === "loop_iteration") {
+      completedIterations += 1;
+      if (e.data && typeof e.data.exitCode !== "undefined") {
+        lastExitCode = e.data.exitCode;
+      }
+    }
+  }
+  return { config, completedIterations, lastExitCode };
+}
+
+/** Default abortable sleep — resolves early if the signal aborts. */
+export function makeSleep(signal) {
+  return (ms) =>
+    new Promise((resolve) => {
+      if (signal?.aborted || ms <= 0) return resolve();
+      // NB: do NOT unref() — the pending interval timer is what keeps the
+      // process alive between rounds. Under a TTY the active stdin would mask
+      // an unref'd timer, but headless (piped stdin / CI / cron) the loop would
+      // exit after the first round. SIGINT aborts the wait via the signal.
+      const t = setTimeout(resolve, ms);
+      signal?.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(t);
+          resolve();
+        },
+        { once: true },
+      );
+    });
+}
+
+/**
+ * Drive the loop. Calls `runIteration(n)` once per round (1-based), evaluates
+ * the stop conditions AFTER each round, and sleeps `intervalMs` between rounds
+ * (never after the final round). Returns a summary describing why it stopped.
+ *
+ * @param {object}   opts
+ * @param {(n:number)=>Promise<{exitCode?:number, output?:string}>} opts.runIteration
+ * @param {number}   opts.intervalMs       default delay between iterations (>= 0)
+ * @param {number}  [opts.maxIterations]   stop after N rounds (>= 1)
+ * @param {boolean} [opts.untilExitZero]   stop once a round exits with code 0
+ * @param {RegExp}  [opts.untilRegex]      stop once a round's output matches
+ * @param {(ms:number)=>Promise<void>} [opts.sleep]  injectable delay
+ * @param {()=>boolean} [opts.shouldStop]  external stop probe (e.g. SIGINT)
+ * @param {(n:number, res:object)=>void} [opts.onIteration] per-round hook
+ * @param {number}  [opts.startIndex]      iterations already done (resume)
+ * @returns {Promise<{iterations:number, stoppedBy:string, results:object[]}>}
+ *          `iterations` is cumulative (startIndex + rounds run this call);
+ *          `results` holds only this call's rounds.
+ */
+export async function runLoop({
+  runIteration,
+  intervalMs,
+  maxIterations,
+  untilExitZero = false,
+  untilRegex = null,
+  sleep,
+  shouldStop,
+  onIteration,
+  startIndex = 0,
+}) {
+  if (typeof runIteration !== "function") {
+    throw new Error("runLoop requires a runIteration function");
+  }
+  const delay = sleep || makeSleep();
+  const results = [];
+  // Iterations already completed in a prior (resumed) run. `i` continues from
+  // here so the displayed/persisted round numbers are cumulative and
+  // `maxIterations` counts across resume.
+  let i = startIndex;
+
+  while (true) {
+    if (shouldStop && shouldStop()) {
+      return { iterations: i, stoppedBy: "signal", results };
+    }
+
+    i += 1;
+    const res = (await runIteration(i)) || {};
+    results.push(res);
+    if (onIteration) onIteration(i, res);
+
+    // Stop conditions, most-specific first. Evaluated after the round so the
+    // work always runs at least once before any condition can end the loop.
+    // `res.done` is the iteration's own explicit stop (e.g. a --dynamic
+    // [[loop:stop]] directive) and wins over everything else.
+    if (res.done) {
+      return { iterations: i, stoppedBy: "done", results };
+    }
+    if (untilExitZero && res.exitCode === 0) {
+      return { iterations: i, stoppedBy: "exit-zero", results };
+    }
+    if (untilRegex && untilRegex.test(res.output || "")) {
+      return { iterations: i, stoppedBy: "match", results };
+    }
+    if (maxIterations && i >= maxIterations) {
+      return { iterations: i, stoppedBy: "max-iterations", results };
+    }
+    if (shouldStop && shouldStop()) {
+      return { iterations: i, stoppedBy: "signal", results };
+    }
+
+    // An iteration may set its own next interval (--dynamic [[loop:next]]);
+    // otherwise fall back to the fixed --every delay.
+    const nextMs = Number.isFinite(res.nextDelayMs)
+      ? res.nextDelayMs
+      : intervalMs;
+    await delay(nextMs);
+  }
+}