@loops-adk/core 0.1.0

package/dist/env/sst.d.ts

@@ -0,0 +1,39 @@
+import { W as Workspace, E as Environment } from '../types-B4wGVpqo.js';
+import { Cmd } from './command.js';
+
+/**
+ * `sstEnvironment` — a per-branch sst stage as an Environment, a thin preset over
+ * `commandEnvironment`. `sst deploy --stage <slug(branch)>` on up,
+ * `sst remove --stage …` on down. Each worktree-team gets its own stage named
+ * after its branch — the personal-stack convention, generalised per-branch.
+ *
+ * The exact sst flags vary by sst version, so deploy/outputs/destroy are all
+ * overridable, and the CONSUMER supplies `map` (which output is the URL / how
+ * outputs become env vars) since the output shape is app-specific. By default no
+ * outputs are read (the deploy still runs); set `outputs` + `map` to surface a
+ * URL. This adds no dependency — it shells out to the `sst` CLI on PATH.
+ */
+
+interface SstEnvConfig {
+    /** App dir (where sst.config.ts lives). Default: the workspace dir. */
+    cwd?: (ws: Workspace) => string;
+    /** Stage name. Default: a slug of the workspace branch. */
+    stage?: (ws: Workspace) => string;
+    /** Override the deploy command. Default: `sst deploy --stage <stage>`. */
+    deploy?: (stage: string, ws: Workspace) => Cmd;
+    /** Command to read outputs as JSON. Omitted by default (version-specific). */
+    outputs?: (stage: string, ws: Workspace) => Cmd;
+    /** Override the destroy command. Default: `sst remove --stage <stage>`. */
+    destroy?: (stage: string, ws: Workspace) => Cmd;
+    /** Map outputs → { url, env }. Required to surface a URL to the gate. */
+    map?: (outputs: Record<string, unknown>, stage: string, raw: string) => {
+        url?: string;
+        env?: Record<string, string>;
+    };
+    /** The sst binary. Default 'sst'. */
+    binary?: string;
+    timeoutMs?: number;
+}
+declare function sstEnvironment(config?: SstEnvConfig): Environment;
+
+export { type SstEnvConfig, sstEnvironment };

package/dist/env/sst.js

@@ -0,0 +1,20 @@
+import { commandEnvironment } from '../chunk-33YIGWNU.js';
+
+// src/env/sst.ts
+function sstEnvironment(config = {}) {
+  const bin = config.binary ?? "sst";
+  return commandEnvironment({
+    name: "sst",
+    cwd: config.cwd,
+    stage: config.stage,
+    deploy: config.deploy ?? ((stage) => ({ cmd: bin, args: ["deploy", "--stage", stage] })),
+    outputs: config.outputs,
+    destroy: config.destroy ?? ((stage) => ({ cmd: bin, args: ["remove", "--stage", stage] })),
+    map: config.map,
+    timeoutMs: config.timeoutMs
+  });
+}
+
+export { sstEnvironment };
+//# sourceMappingURL=sst.js.map
+//# sourceMappingURL=sst.js.map

package/dist/env/sst.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/env/sst.ts"],"names":[],"mappings":";;;AAuCO,SAAS,cAAA,CAAe,MAAA,GAAuB,EAAC,EAAgB;AACrE,EAAA,MAAM,GAAA,GAAM,OAAO,MAAA,IAAU,KAAA;AAC7B,EAAA,OAAO,kBAAA,CAAmB;AAAA,IACxB,IAAA,EAAM,KAAA;AAAA,IACN,KAAK,MAAA,CAAO,GAAA;AAAA,IACZ,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,MAAA,EACE,MAAA,CAAO,MAAA,KACN,CAAC,KAAA,MAAW,EAAE,GAAA,EAAK,GAAA,EAAK,IAAA,EAAM,CAAC,QAAA,EAAU,SAAA,EAAW,KAAK,CAAA,EAAE,CAAA,CAAA;AAAA,IAC9D,SAAS,MAAA,CAAO,OAAA;AAAA,IAChB,OAAA,EACE,MAAA,CAAO,OAAA,KACN,CAAC,KAAA,MAAW,EAAE,GAAA,EAAK,GAAA,EAAK,IAAA,EAAM,CAAC,QAAA,EAAU,SAAA,EAAW,KAAK,CAAA,EAAE,CAAA,CAAA;AAAA,IAC9D,KAAK,MAAA,CAAO,GAAA;AAAA,IACZ,WAAW,MAAA,CAAO;AAAA,GACnB,CAAA;AACH","file":"sst.js","sourcesContent":["/**\n * `sstEnvironment` — a per-branch sst stage as an Environment, a thin preset over\n * `commandEnvironment`. `sst deploy --stage <slug(branch)>` on up,\n * `sst remove --stage …` on down. Each worktree-team gets its own stage named\n * after its branch — the personal-stack convention, generalised per-branch.\n *\n * The exact sst flags vary by sst version, so deploy/outputs/destroy are all\n * overridable, and the CONSUMER supplies `map` (which output is the URL / how\n * outputs become env vars) since the output shape is app-specific. By default no\n * outputs are read (the deploy still runs); set `outputs` + `map` to surface a\n * URL. This adds no dependency — it shells out to the `sst` CLI on PATH.\n */\n\nimport type { Workspace } from '../core/types.ts';\nimport type { Environment } from './environment.ts';\nimport { commandEnvironment, type Cmd } from './command.ts';\n\nexport interface SstEnvConfig {\n  /** App dir (where sst.config.ts lives). Default: the workspace dir. */\n  cwd?: (ws: Workspace) => string;\n  /** Stage name. Default: a slug of the workspace branch. */\n  stage?: (ws: Workspace) => string;\n  /** Override the deploy command. Default: `sst deploy --stage <stage>`. */\n  deploy?: (stage: string, ws: Workspace) => Cmd;\n  /** Command to read outputs as JSON. Omitted by default (version-specific). */\n  outputs?: (stage: string, ws: Workspace) => Cmd;\n  /** Override the destroy command. Default: `sst remove --stage <stage>`. */\n  destroy?: (stage: string, ws: Workspace) => Cmd;\n  /** Map outputs → { url, env }. Required to surface a URL to the gate. */\n  map?: (\n    outputs: Record<string, unknown>,\n    stage: string,\n    raw: string,\n  ) => { url?: string; env?: Record<string, string> };\n  /** The sst binary. Default 'sst'. */\n  binary?: string;\n  timeoutMs?: number;\n}\n\nexport function sstEnvironment(config: SstEnvConfig = {}): Environment {\n  const bin = config.binary ?? 'sst';\n  return commandEnvironment({\n    name: 'sst',\n    cwd: config.cwd,\n    stage: config.stage,\n    deploy:\n      config.deploy ??\n      ((stage) => ({ cmd: bin, args: ['deploy', '--stage', stage] })),\n    outputs: config.outputs,\n    destroy:\n      config.destroy ??\n      ((stage) => ({ cmd: bin, args: ['remove', '--stage', stage] })),\n    map: config.map,\n    timeoutMs: config.timeoutMs,\n  });\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,620 @@
+#!/usr/bin/env node
+import { renderPlan, jobMeta, run, exitCodeFor, loop, agentJob, agentCheck, bodyPassed, gateJob } from './chunk-3BPU34DE.js';
+import './chunk-JFTXJ7I2.js';
+import './chunk-XC46B4FD.js';
+import './chunk-Y2SD7GBL.js';
+import './chunk-I3STY7U6.js';
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import 'react';
+import { Command } from 'commander';
+import { z } from 'zod';
+import pc from 'picocolors';
+import ms from 'ms';
+import { jsx } from 'react/jsx-runtime';
+
+// src/runtime/hub.ts
+function createHub() {
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    emit(event) {
+      for (const listener of listeners) listener(event);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// src/runtime/signals.ts
+function installSignalHandlers() {
+  const controller = new AbortController();
+  let hits = 0;
+  const onSignal = () => {
+    hits += 1;
+    if (hits === 1) controller.abort();
+    else process.exit(130);
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  return {
+    controller,
+    dispose() {
+      process.off("SIGINT", onSignal);
+      process.off("SIGTERM", onSignal);
+    }
+  };
+}
+var indent = (path2) => "  ".repeat(Math.max(0, path2.length - 1));
+var statusColor = (status, text) => status === "pass" ? pc.green(text) : status === "fail" ? pc.red(text) : status === "exhausted" ? pc.yellow(text) : status === "paused" ? pc.cyan(text) : pc.gray(text);
+var clock = (ts) => new Date(ts).toLocaleTimeString(void 0, {
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit"
+});
+function jsonReporter() {
+  return (event) => process.stdout.write(`${JSON.stringify(event)}
+`);
+}
+var tok = (n) => n >= 1e3 ? `${(n / 1e3).toFixed(1)}k` : String(n);
+function plainReporter() {
+  let streaming = false;
+  const endStream = () => {
+    if (streaming) {
+      process.stdout.write("\n");
+      streaming = false;
+    }
+  };
+  const accums = /* @__PURE__ */ new Map();
+  const reportIteration = (key, indentPath) => {
+    const a = accums.get(key);
+    if (!a) return;
+    accums.delete(key);
+    const parts = [];
+    if (a.bodyStatus)
+      parts.push(`body=${statusColor(a.bodyStatus, a.bodyStatus)}`);
+    if (a.until)
+      parts.push(`until=${a.until.met ? pc.green("met") : pc.gray("not met")}`);
+    if (a.stopOn?.met) parts.push(`stopOn=${pc.red("met")}`);
+    if (a.review) {
+      const rv = `review=${statusColor(a.review.status, a.review.status)}`;
+      parts.push(
+        a.review.summary ? `${rv} ${pc.dim(`(${a.review.summary})`)}` : rv
+      );
+    }
+    parts.push(`${tok(a.tokensIn)}/${tok(a.tokensOut)} tok`);
+    console.log(
+      `${indent(indentPath)}  ${pc.gray(`\u21B3 iter ${a.iteration}:`)} ${parts.join(pc.gray(" \xB7 "))}`
+    );
+  };
+  return (event) => {
+    const key = event.path.join(" / ");
+    switch (event.kind) {
+      case "engine:text":
+        process.stdout.write(event.delta);
+        streaming = true;
+        return;
+      case "loop:start":
+        endStream();
+        console.log(
+          `${indent(event.path)}${pc.cyan("\u25B8 loop")} ${pc.bold(last(event.path))}${event.max ? pc.gray(` (max ${event.max})`) : ""}`
+        );
+        return;
+      case "loop:iteration":
+        endStream();
+        reportIteration(key, event.path);
+        accums.set(key, {
+          iteration: event.iteration,
+          tokensIn: 0,
+          tokensOut: 0
+        });
+        console.log(
+          `${indent(event.path)}${pc.gray(`  iteration ${event.iteration}`)}`
+        );
+        return;
+      case "loop:condition": {
+        endStream();
+        const a = accums.get(key);
+        if (a) {
+          if (event.which === "until")
+            a.until = { met: event.result.met, reason: event.result.reason };
+          else if (event.which === "stopOn")
+            a.stopOn = { met: event.result.met, reason: event.result.reason };
+        }
+        console.log(
+          `${indent(event.path)}  ${pc.magenta(event.which)}: ${event.result.met ? pc.green("met") : pc.gray("not met")} \u2014 ${pc.dim(event.result.reason)}`
+        );
+        return;
+      }
+      case "loop:review": {
+        endStream();
+        const a = accums.get(key);
+        if (a)
+          a.review = {
+            status: event.outcome.status,
+            summary: event.outcome.summary
+          };
+        console.log(
+          `${indent(event.path)}  ${pc.blue("review")}: ${statusColor(event.outcome.status, event.outcome.status)}${event.outcome.summary ? pc.dim(` \u2014 ${event.outcome.summary}`) : ""}`
+        );
+        return;
+      }
+      case "job:end": {
+        const a = accums.get(key);
+        if (a) a.bodyStatus = event.outcome.status;
+        return;
+      }
+      case "engine:usage": {
+        const a = accums.get(key);
+        if (a) {
+          a.tokensIn += event.usage.inputTokens;
+          a.tokensOut += event.usage.outputTokens;
+        }
+        return;
+      }
+      case "loop:end":
+        endStream();
+        reportIteration(key, event.path);
+        console.log(
+          `${indent(event.path)}${pc.cyan("\u25C2 loop")} ${pc.bold(last(event.path))} \u2192 ${statusColor(event.outcome.status, event.outcome.status)} ${pc.gray(`(${event.iterations} iter)`)}`
+        );
+        return;
+      case "dag:start":
+        endStream();
+        console.log(
+          `${indent(event.path)}${pc.cyan("\u25B8 dag")} ${pc.bold(last(event.path))} ${pc.gray(`[${event.nodes.join(", ")}]`)}`
+        );
+        return;
+      case "dag:node":
+        if (event.phase === "start") return;
+        endStream();
+        console.log(
+          `${indent(event.path)}  ${pc.gray("node")} ${event.node}: ${event.outcome ? statusColor(event.outcome.status, event.phase === "skip" ? "skipped" : event.outcome.status) : event.phase}`
+        );
+        return;
+      case "dag:end":
+        endStream();
+        console.log(
+          `${indent(event.path)}${pc.cyan("\u25C2 dag")} ${pc.bold(last(event.path))} \u2192 ${statusColor(event.outcome.status, event.outcome.status)}`
+        );
+        return;
+      case "job:start":
+        endStream();
+        console.log(`${indent(event.path)}  ${pc.gray("\u2022")} ${event.label}`);
+        return;
+      case "engine:tool":
+        endStream();
+        console.log(
+          `${indent(event.path)}    ${pc.dim(`tool ${event.phase}: ${event.name}`)}`
+        );
+        return;
+      case "limit:wait":
+        endStream();
+        console.log(
+          `${indent(event.path)}  ${pc.yellow(`\u23F3 ${event.code.toLowerCase()}`)}: waiting ${Math.round(event.waitMs / 1e3)}s, resuming at ${clock(event.resumeAt)}`
+        );
+        return;
+      case "limit:pause":
+        endStream();
+        console.log(
+          `${indent(event.path)}  ${pc.cyan(`\u23F8 ${event.code.toLowerCase()}`)}: ${pc.dim(event.reason)}`
+        );
+        return;
+      case "log":
+        endStream();
+        console.log(
+          `${indent(event.path)}  ${pc.dim(`[${event.level}] ${event.message}`)}`
+        );
+        return;
+      case "error":
+        endStream();
+        console.log(
+          `${indent(event.path)}  ${pc.red(`\u2717 ${event.code}: ${event.message}`)}`
+        );
+        return;
+      default:
+        return;
+    }
+  };
+}
+function printSummary(result, resumeCommand) {
+  const { outcome, stats } = result;
+  const line = pc.dim("\u2500".repeat(56));
+  console.log(`
+${line}`);
+  console.log(
+    `${pc.bold("Result")}  ${statusColor(outcome.status, outcome.status.toUpperCase())}${outcome.confidence != null ? pc.gray(`  confidence ${outcome.confidence.toFixed(2)}`) : ""}`
+  );
+  if (outcome.summary) console.log(`${pc.dim("Summary")} ${outcome.summary}`);
+  if (outcome.status === "paused") {
+    console.log(
+      resumeCommand ? `${pc.dim("Resume")}  ${pc.cyan(resumeCommand)}` : `${pc.dim("Resume")}  ${pc.yellow("re-run with --checkpoint <path> to make a pause resumable")}`
+    );
+  }
+  console.log(line);
+  console.log(`${pc.bold("Loops")}`);
+  for (const loop2 of stats.loops) {
+    const reviews = loop2.reviewsPassed + loop2.reviewsFailed;
+    console.log(
+      `  ${loop2.path || "(root)"} \u2014 ${loop2.iterations} iter` + (reviews ? `, reviews ${pc.green(String(loop2.reviewsPassed))}/${pc.red(String(loop2.reviewsFailed))}` : "") + (loop2.lastStatus ? ` \u2192 ${statusColor(loop2.lastStatus, loop2.lastStatus)}` : "")
+    );
+  }
+  if (stats.loops.length === 0) console.log(pc.dim("  (none)"));
+  console.log(line);
+  console.log(
+    `${pc.bold("Usage")}  ${stats.agentCalls} agent call(s), ${pc.cyan(String(stats.totalInputTokens))} in / ${pc.cyan(String(stats.totalOutputTokens))} out tokens, ${(stats.elapsedMs / 1e3).toFixed(1)}s`
+  );
+  for (const m of stats.models) {
+    console.log(
+      pc.dim(
+        `  ${m.model}: ${m.calls} call(s), ${m.inputTokens} in / ${m.outputTokens} out`
+      )
+    );
+  }
+  if (result.budget) {
+    const b = result.budget;
+    const spent = b.remaining === 0 ? pc.red(String(b.spent)) : pc.cyan(String(b.spent));
+    console.log(
+      `${pc.bold("Budget")} ${spent} / ${b.limit} tokens ${pc.gray(`(${b.remaining} remaining)`)}`
+    );
+  }
+  if (stats.errors.length) {
+    console.log(line);
+    console.log(`${pc.bold(pc.red("Errors"))} (${stats.errors.length})`);
+    for (const e of stats.errors.slice(0, 10)) {
+      console.log(pc.red(`  \u2717 [${e.code}] ${e.path}: ${e.message}`));
+    }
+  }
+  console.log(line);
+}
+function last(path2) {
+  return path2[path2.length - 1] ?? "(root)";
+}
+var FlagSpec = z.object({
+  prompt: z.string().min(
+    1,
+    "a --prompt or --prompt-file is required when no definition file is given"
+  ),
+  engine: z.string().optional(),
+  workerModel: z.string().optional(),
+  validatorModel: z.string().optional(),
+  reviewerModel: z.string().optional(),
+  max: z.number().int().positive().optional(),
+  untilAgent: z.string().optional(),
+  threshold: z.number().min(0).max(1).default(0.8),
+  startAgent: z.string().optional(),
+  review: z.string().optional(),
+  reviewThreshold: z.number().min(0).max(1).default(0.85),
+  interval: z.number().int().nonnegative().optional(),
+  maxTokens: z.number().int().positive().optional()
+});
+function parseDuration(value) {
+  if (/^\d+$/.test(value)) return Number(value);
+  const out = ms(value);
+  if (typeof out !== "number" || Number.isNaN(out)) {
+    throw new Error(`invalid duration: "${value}" (try 30s, 5m, 1h)`);
+  }
+  return out;
+}
+function buildJobFromFlags(input) {
+  const spec = FlagSpec.parse(input);
+  const engine = spec.engine;
+  const worker = agentJob({
+    label: "worker",
+    engine,
+    model: spec.workerModel,
+    maxTokens: spec.maxTokens,
+    // On a review-restart, fold the reviewer's objection into the next prompt
+    // so the retry is informed rather than a blind repeat.
+    prompt: (ctx) => ctx.lastReview ? `${spec.prompt}
+
+Your previous attempt was REJECTED in review: ${ctx.lastReview.summary ?? ctx.lastReview.status}. Address that specifically this time.` : spec.prompt
+  });
+  const until = spec.untilAgent ? agentCheck({
+    question: spec.untilAgent,
+    threshold: spec.threshold,
+    model: spec.validatorModel,
+    engine
+  }) : bodyPassed();
+  const start = spec.startAgent ? agentCheck({
+    question: spec.startAgent,
+    threshold: 0.5,
+    model: spec.validatorModel,
+    engine
+  }) : void 0;
+  const review = spec.review ? gateJob(
+    "review",
+    agentCheck({
+      question: spec.review,
+      threshold: spec.reviewThreshold,
+      model: spec.reviewerModel,
+      engine
+    })
+  ) : void 0;
+  return loop({
+    name: "main",
+    body: worker,
+    start,
+    until,
+    review,
+    max: spec.max,
+    delayMs: spec.interval
+  });
+}
+var ON_LIMIT_VALUES = ["auto", "wait", "exit-resume", "fail"];
+function resolvePrompt(flags) {
+  if (flags.promptFile != null && flags.prompt != null) {
+    throw new Error("pass either --prompt or --prompt-file, not both");
+  }
+  if (flags.promptFile != null) {
+    const resolved = path.resolve(flags.promptFile);
+    if (!fs.existsSync(resolved))
+      throw new Error(`prompt file not found: ${flags.promptFile}`);
+    return fs.readFileSync(resolved, "utf8");
+  }
+  return flags.prompt ?? "";
+}
+async function loadJob(file) {
+  const resolved = path.resolve(file);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(
+      `loop file not found: ${file}
+(omit the file argument to use flags mode, or run \`loops run --help\`)`
+    );
+  }
+  let mod;
+  try {
+    mod = await import(pathToFileURL(resolved).href);
+  } catch (e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    const esmHint = /ES Module|import statement outside a module|ERR_REQUIRE_ESM/i.test(detail) ? `
+  hint: the recipe's folder is not an ES module scope. Add a package.json with {"type":"module"} next to it (repos that use loops as a submodule already have this).` : "";
+    throw new Error(
+      `failed to load loop file ${file}:
+  ${detail}${esmHint}
+(the file is imported and run like \`node <file>\`; fix the error above, or run \`loops validate ${file}\` to check it without executing)`
+    );
+  }
+  const def = mod.default ?? mod.job ?? mod.loop;
+  const title = path.basename(file).replace(/\.(loop\.)?(t|j)sx?$/, "");
+  if (typeof def === "function") return { job: def, title };
+  if (def && typeof def === "object" && "body" in def)
+    return { job: loop(def), title };
+  throw new Error(
+    `${file}: default export must be a Job (from loop()/dag()/agentJob()) or a LoopConfig`
+  );
+}
+function buildFromFlags(flags) {
+  const num = (v) => v == null ? void 0 : Number(v);
+  const prompt = resolvePrompt(flags);
+  try {
+    return buildJobFromFlags({
+      prompt,
+      engine: flags.engine,
+      workerModel: flags.workerModel,
+      validatorModel: flags.validatorModel,
+      reviewerModel: flags.reviewerModel,
+      max: num(flags.max),
+      untilAgent: flags.until,
+      threshold: num(flags.threshold),
+      startAgent: flags.start,
+      review: flags.review,
+      reviewThreshold: num(flags.reviewThreshold),
+      interval: flags.interval != null ? parseDuration(flags.interval) : void 0,
+      maxTokens: num(flags.maxTokens)
+    });
+  } catch (e) {
+    if (e instanceof z.ZodError) {
+      throw new Error(
+        `invalid flags:
+  - ${e.issues.map((i) => i.message).join("\n  - ")}`
+      );
+    }
+    throw e;
+  }
+}
+async function execute(file, flags) {
+  const { job, title } = file ? await loadJob(file) : { job: buildFromFlags(flags), title: "loop" };
+  const engineOptions = {};
+  if (flags.defaultModel) engineOptions.defaultModel = flags.defaultModel;
+  if (flags.apiKey) engineOptions.apiKey = flags.apiKey;
+  if (flags.cliBinary) engineOptions.cliBinary = flags.cliBinary;
+  if (flags.permissionMode)
+    engineOptions.permissionMode = flags.permissionMode;
+  if (flags.engineArg?.length) engineOptions.cliArgs = flags.engineArg;
+  let state;
+  if (flags.state) {
+    let parsed;
+    try {
+      parsed = JSON.parse(flags.state);
+    } catch (e) {
+      throw new Error(
+        `--state must be valid JSON: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(
+        `--state must be a JSON object, got ${Array.isArray(parsed) ? "array" : typeof parsed}`
+      );
+    }
+    state = parsed;
+  }
+  let budget;
+  if (flags.budget != null) {
+    budget = Number(flags.budget);
+    if (!Number.isFinite(budget) || budget <= 0) {
+      throw new Error(
+        `--budget must be a positive number of tokens, got "${flags.budget}"`
+      );
+    }
+  }
+  let onLimit;
+  if (flags.onLimit != null) {
+    if (!ON_LIMIT_VALUES.includes(flags.onLimit)) {
+      throw new Error(
+        `--on-limit must be one of ${ON_LIMIT_VALUES.join(" | ")}, got "${flags.onLimit}"`
+      );
+    }
+    onLimit = flags.onLimit;
+  }
+  const maxWaitMs = flags.maxWait != null ? parseDuration(flags.maxWait) : void 0;
+  const mode = flags.json ? "json" : flags.tui === false || !process.stdout.isTTY ? "plain" : "tui";
+  const resumeCommand = buildResumeCommand(file, flags);
+  const hub = createHub();
+  const signals = installSignalHandlers();
+  const runOptions = {
+    engine: flags.engine,
+    engineOptions,
+    signal: signals.controller.signal,
+    onEvent: hub.emit,
+    state,
+    budget,
+    recordTo: flags.record,
+    checkpoint: flags.checkpoint,
+    resumeFrom: flags.resume,
+    onLimit,
+    maxWaitMs,
+    resumeCommand
+  };
+  let result;
+  if (mode === "tui") {
+    const { render } = await import('ink');
+    const { App } = await import('./App-3YQS6DXA.js');
+    const instance = render(
+      /* @__PURE__ */ jsx(
+        App,
+        {
+          hub,
+          title,
+          onAbort: () => signals.controller.abort()
+        }
+      )
+    );
+    result = await run(job, runOptions);
+    instance.unmount();
+    await instance.waitUntilExit().catch(() => {
+    });
+    printSummary(result, resumeCommand);
+  } else {
+    const unsubscribe = hub.subscribe(
+      mode === "json" ? jsonReporter() : plainReporter()
+    );
+    result = await run(job, runOptions);
+    unsubscribe();
+    if (mode !== "json") printSummary(result, resumeCommand);
+  }
+  if (result.outcome.status === "paused") printResumeGuidance(file, flags);
+  signals.dispose();
+  process.exitCode = exitCodeFor(result.outcome);
+}
+function buildResumeCommand(file, flags) {
+  if (!flags.checkpoint) return void 0;
+  const parts = ["loops", "run"];
+  if (file) parts.push(quoteArg(file));
+  parts.push("--resume", quoteArg(flags.checkpoint));
+  if (flags.engine) parts.push("--engine", flags.engine);
+  if (flags.budget) parts.push("--budget", flags.budget);
+  if (flags.onLimit) parts.push("--on-limit", flags.onLimit);
+  if (flags.maxWait) parts.push("--max-wait", flags.maxWait);
+  if (flags.record) parts.push("--record", quoteArg(flags.record));
+  if (flags.checkpoint) parts.push("--checkpoint", quoteArg(flags.checkpoint));
+  if (flags.tui === false) parts.push("--no-tui");
+  if (flags.json) parts.push("--json");
+  return parts.join(" ");
+}
+function quoteArg(value) {
+  return /[\s'"]/.test(value) ? `'${value.replace(/'/g, `'\\''`)}'` : value;
+}
+function printResumeGuidance(file, flags) {
+  const cmd = buildResumeCommand(file, flags);
+  if (cmd) {
+    process.stderr.write(`
+Paused at a limit. Resume with:
+  ${cmd}
+`);
+  } else {
+    process.stderr.write(
+      "\nPaused at a limit. No checkpoint was configured, so there is no warm state to resume.\nRe-run with --checkpoint <path> to make a pause resumable.\n"
+    );
+  }
+}
+async function main(argv = process.argv) {
+  const program = new Command();
+  program.name("loops").description(
+    "Run a prompt/agent in a loop with a fresh context every iteration. A nestable job primitive: loops, DAG stages, agent-validated conditions, review-restart."
+  ).version("0.1.0");
+  program.command("run", { isDefault: true }).argument(
+    "[file]",
+    "a loop-definition file (default-exports a Job); omit to use flags"
+  ).option("-p, --prompt <text>", "worker prompt (no-file mode)").option(
+    "-f, --prompt-file <path>",
+    "read the worker prompt from a file (no-file mode)"
+  ).option(
+    "-e, --engine <name>",
+    "default engine: agent-sdk | claude-cli | anthropic-api"
+  ).option("--default-model <id>", "fallback model id for engines").option("--worker-model <id>", "model for the worker job").option(
+    "--validator-model <id>",
+    "small model for agent-validated conditions"
+  ).option("--reviewer-model <id>", "model for the review job").option("-n, --max <n>", "max iterations").option("-u, --until <question>", "agent-validated stop condition").option("-t, --threshold <0..1>", "confidence threshold for --until", "0.8").option("--start <question>", "agent-validated start gate").option(
+    "--review <instructions>",
+    "review job; failing it restarts the loop"
+  ).option(
+    "--review-threshold <0..1>",
+    "confidence threshold for --review",
+    "0.85"
+  ).option("-i, --interval <dur>", "delay between iterations (e.g. 30s, 5m)").option("--max-tokens <n>", "max output tokens per agent turn").option("--api-key <key>", "Anthropic API key (anthropic-api engine)").option(
+    "--cli-binary <path>",
+    "path to the claude binary (claude-cli engine)"
+  ).option(
+    "--permission-mode <mode>",
+    "tool permission mode for claude-cli/agent-sdk (default | acceptEdits | bypassPermissions | plan | dontAsk | auto)"
+  ).option(
+    "--engine-arg <arg>",
+    "extra arg forwarded to the claude-cli engine (repeatable)",
+    (v, acc) => acc.concat(v),
+    []
+  ).option("--state <json>", "seed the shared run state (JSON)").option("--budget <tokens>", "cap total tokens (input+output) for the run").option("--record <path>", "append a JSONL run record to this path").option(
+    "--checkpoint <path>",
+    "snapshot run state to this path at each loop/dag/job boundary"
+  ).option(
+    "--resume <path>",
+    "restore run state from a prior --checkpoint file"
+  ).option(
+    "--on-limit <policy>",
+    "on a rate/quota/budget limit: auto | wait | exit-resume | fail (default auto)"
+  ).option(
+    "--max-wait <dur>",
+    "cap an auto/wait limit-wait (e.g. 5m, 30s); default 5m"
+  ).option("--json", "emit NDJSON events to stdout (no TUI)").option("--no-tui", "plain line output instead of the Ink TUI").action(
+    (file, flags) => execute(file, flags)
+  );
+  program.command("validate").argument("<file>", "a loop-definition file to check").description(
+    "load a .loop.ts and print its shape without running it: the cheap, no-model pre-flight an agent runs before `loops run`"
+  ).action(async (file) => {
+    const { job } = await loadJob(file);
+    const plan = renderPlan(jobMeta(job));
+    process.stdout.write(
+      `\u2713 ${file} loads (not executed)
+${plan.map((l) => `  ${l}`).join("\n")}
+`
+    );
+  });
+  program.command("describe").argument("<file>", "a loop-definition file").description(
+    "print a loop's shape (its gate, body, and dag nodes) without running it"
+  ).action(async (file) => {
+    const { job } = await loadJob(file);
+    process.stdout.write(`${renderPlan(jobMeta(job)).join("\n")}
+`);
+  });
+  await program.parseAsync(argv);
+}
+
+// src/index.ts
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map