@hasna/loops 0.4.1 → 0.4.2

package/dist/api/index.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.1",
+  version: "0.4.2",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -43,6 +43,22 @@ var package_default = {
     "./storage": {
       types: "./dist/lib/store.d.ts",
       import: "./dist/lib/store.js"
+    },
+    "./storage/contract": {
+      types: "./dist/lib/storage/contract.d.ts",
+      import: "./dist/lib/storage/contract.js"
+    },
+    "./storage/sqlite": {
+      types: "./dist/lib/storage/sqlite.d.ts",
+      import: "./dist/lib/storage/sqlite.js"
+    },
+    "./storage/postgres": {
+      types: "./dist/lib/storage/postgres.d.ts",
+      import: "./dist/lib/storage/postgres.js"
+    },
+    "./storage/postgres-schema": {
+      types: "./dist/lib/storage/postgres-schema.d.ts",
+      import: "./dist/lib/storage/postgres-schema.js"
     }
   },
   files: [
@@ -53,7 +69,7 @@ var package_default = {
     "LICENSE"
   ],
   scripts: {
-    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts src/lib/storage/index.ts src/lib/storage/contract.ts src/lib/storage/sqlite.ts src/lib/storage/postgres.ts src/lib/storage/postgres-schema.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
     typecheck: "tsc --noEmit",
     test: "bun test",
@@ -253,8 +269,503 @@ function deploymentStatusLine(status) {
 }
 
 // src/api/index.ts
+import { timingSafeEqual } from "crypto";
 import { Command } from "commander";
+
+// src/lib/errors.ts
+class CodedError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+  }
+}
+
+class LoopNotFoundError extends CodedError {
+  constructor(idOrName) {
+    super("LOOP_NOT_FOUND", `loop not found: ${idOrName}`);
+  }
+}
+
+class LoopArchivedError extends CodedError {
+  constructor(idOrName) {
+    super("LOOP_ARCHIVED", `loop is archived: ${idOrName}; unarchive it before modifying`);
+  }
+}
+
+class AmbiguousNameError extends CodedError {
+  constructor(name) {
+    super("AMBIGUOUS_NAME", `ambiguous loop name: ${name}; use a loop id`);
+  }
+}
+
+class ValidationError extends CodedError {
+  constructor(message) {
+    super("VALIDATION_ERROR", message);
+  }
+}
+
+// src/lib/format.ts
+var TEXT_OUTPUT_LIMIT = 32 * 1024;
+var SENSITIVE_PAYLOAD_KEYS = new Set(["env", "error", "prompt", "reason", "stderr", "stdout"]);
+function redact(value, visible = 0) {
+  if (!value)
+    return value;
+  if (value.length <= visible)
+    return value;
+  if (visible <= 0)
+    return `[redacted ${value.length} chars]`;
+  return `${value.slice(0, visible)}... [redacted ${value.length - visible} chars]`;
+}
+function truncateTextOutput(value) {
+  if (value.length <= TEXT_OUTPUT_LIMIT)
+    return value;
+  return `${value.slice(0, TEXT_OUTPUT_LIMIT)}
+[truncated ${value.length - TEXT_OUTPUT_LIMIT} chars]`;
+}
+function redactSensitivePayload(value, key) {
+  if (key && SENSITIVE_PAYLOAD_KEYS.has(key)) {
+    if (typeof value === "string")
+      return redact(value);
+    if (value === undefined || value === null)
+      return value;
+    return "[redacted]";
+  }
+  if (Array.isArray(value))
+    return value.map((item) => redactSensitivePayload(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [entryKey, redactSensitivePayload(entryValue, entryKey)]));
+  }
+  return value;
+}
+function textOutputBlocks(value, opts = {}) {
+  const indent = opts.indent ?? "";
+  const nested = `${indent}  `;
+  const blocks = [];
+  for (const [label, output] of [
+    ["stdout", value.stdout],
+    ["stderr", value.stderr]
+  ]) {
+    if (!output)
+      continue;
+    blocks.push(`${indent}${label}:`);
+    for (const line of truncateTextOutput(output).replace(/\s+$/, "").split(/\r?\n/)) {
+      blocks.push(`${nested}${line}`);
+    }
+  }
+  return blocks;
+}
+function publicLoop(loop) {
+  const target = loop.target.type === "command" ? { ...loop.target, env: loop.target.env ? "[redacted]" : undefined } : loop.target.type === "agent" ? { ...loop.target, prompt: redact(loop.target.prompt) } : loop.target;
+  return {
+    ...loop,
+    target
+  };
+}
+function publicRun(run, showOutput = false, opts = {}) {
+  return {
+    ...run,
+    stdout: showOutput ? run.stdout : run.stdout ? `[redacted ${run.stdout.length} chars]` : undefined,
+    stderr: showOutput ? run.stderr : run.stderr ? `[redacted ${run.stderr.length} chars]` : undefined,
+    error: opts.redactError ? redact(run.error) : run.error
+  };
+}
+function publicExecutorResult(result, showOutput = false) {
+  return {
+    ...result,
+    stdout: showOutput ? result.stdout : result.stdout ? `[redacted ${result.stdout.length} chars]` : undefined,
+    stderr: showOutput ? result.stderr : result.stderr ? `[redacted ${result.stderr.length} chars]` : undefined,
+    error: redact(result.error)
+  };
+}
+function publicWorkflow(workflow) {
+  return {
+    ...workflow,
+    steps: workflow.steps.map((step) => ({
+      ...step,
+      target: step.target.type === "agent" ? { ...step.target, prompt: redact(step.target.prompt) } : step.target.type === "command" && step.target.env ? { ...step.target, env: "[redacted]" } : step.target
+    }))
+  };
+}
+function publicWorkflowRun(run) {
+  return { ...run, error: redact(run.error) };
+}
+function publicWorkflowInvocation(invocation) {
+  return redactSensitivePayload(invocation);
+}
+function publicWorkflowWorkItem(item) {
+  return { ...item, lastReason: redact(item.lastReason, 240) };
+}
+function publicWorkflowStepRun(run, showOutput = false) {
+  return {
+    ...run,
+    stdout: showOutput ? run.stdout : run.stdout ? `[redacted ${run.stdout.length} chars]` : undefined,
+    stderr: showOutput ? run.stderr : run.stderr ? `[redacted ${run.stderr.length} chars]` : undefined,
+    error: redact(run.error)
+  };
+}
+function publicWorkflowEvent(event) {
+  return { ...event, payload: redactSensitivePayload(event.payload) };
+}
+function publicGoal(goal) {
+  return {
+    ...goal,
+    objective: redact(goal.objective, 120)
+  };
+}
+function publicGoalRun(run) {
+  return {
+    ...run,
+    evidence: redactSensitivePayload(run.evidence),
+    rawResponse: redactSensitivePayload(run.rawResponse)
+  };
+}
+
+// src/lib/recurrence.ts
+function assertDate(value, label) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime()))
+    throw new Error(`invalid ${label}: ${value}`);
+  return date;
+}
+function parseField(expr, min, max) {
+  const out = new Set;
+  for (const part of expr.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart ? Number(stepPart) : 1;
+    if (!Number.isInteger(step) || step <= 0)
+      throw new Error(`invalid cron step: ${part}`);
+    let lo = min;
+    let hi = max;
+    if (rangePart && rangePart !== "*") {
+      const bounds = rangePart.split("-");
+      if (bounds.length === 1) {
+        lo = hi = Number(bounds[0]);
+      } else if (bounds.length === 2) {
+        lo = Number(bounds[0]);
+        hi = Number(bounds[1]);
+      } else {
+        throw new Error(`invalid cron range: ${part}`);
+      }
+      if (!Number.isInteger(lo) || !Number.isInteger(hi))
+        throw new Error(`invalid cron field: ${part}`);
+    }
+    for (let v = lo;v <= hi; v += step) {
+      if (v < min || v > max)
+        throw new Error(`cron value out of range: ${v} in ${expr}`);
+      out.add(v);
+    }
+  }
+  return out;
+}
+var MINUTE_MS = 60000;
+var PARSED_CRON_CACHE_LIMIT = 256;
+var parsedCronCache = new Map;
+var emittedScheduleWarnings = new Set;
+function warnOnce(key, message) {
+  if (emittedScheduleWarnings.has(key))
+    return;
+  emittedScheduleWarnings.add(key);
+  console.warn(`[open-loops] WARN ${message}`);
+}
+function parseCron(expr) {
+  const cached = parsedCronCache.get(expr);
+  if (cached)
+    return cached;
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5)
+    throw new Error(`cron must have 5 fields, got ${fields.length}: "${expr}"`);
+  const [minute, hour, dom, month, dow] = fields;
+  const dowSet = parseField(dow, 0, 7);
+  if (dowSet.has(7)) {
+    dowSet.delete(7);
+    dowSet.add(0);
+  }
+  const parsed = {
+    minute: parseField(minute, 0, 59),
+    hour: parseField(hour, 0, 23),
+    dom: parseField(dom, 1, 31),
+    month: parseField(month, 1, 12),
+    dow: dowSet,
+    domRestricted: dom !== "*",
+    dowRestricted: dow !== "*"
+  };
+  if (parsedCronCache.size >= PARSED_CRON_CACHE_LIMIT) {
+    const oldest = parsedCronCache.keys().next().value;
+    if (oldest !== undefined)
+      parsedCronCache.delete(oldest);
+  }
+  parsedCronCache.set(expr, parsed);
+  return parsed;
+}
+function cronMatches(cron, date) {
+  if (!cron.minute.has(date.getMinutes()))
+    return false;
+  if (!cron.hour.has(date.getHours()))
+    return false;
+  if (!cron.month.has(date.getMonth() + 1))
+    return false;
+  const domOk = cron.dom.has(date.getDate());
+  const dowOk = cron.dow.has(date.getDay());
+  if (cron.domRestricted && cron.dowRestricted)
+    return domOk || dowOk;
+  if (cron.domRestricted)
+    return domOk;
+  if (cron.dowRestricted)
+    return dowOk;
+  return true;
+}
+function nextCronRun(expr, from) {
+  const cron = parseCron(expr);
+  const date = new Date(from.getTime());
+  date.setSeconds(0, 0);
+  date.setMinutes(date.getMinutes() + 1);
+  const limit = from.getTime() + 366 * 24 * 60 * 60 * 1000;
+  while (date.getTime() <= limit) {
+    if (cronMatches(cron, date))
+      return date;
+    date.setMinutes(date.getMinutes() + 1);
+  }
+  throw new Error(`no cron match within one year for: ${expr}`);
+}
+function initialNextRun(schedule, from = new Date) {
+  switch (schedule.type) {
+    case "once":
+      return assertDate(schedule.at, "schedule.at").toISOString();
+    case "interval":
+      if (!Number.isFinite(schedule.everyMs) || schedule.everyMs <= 0)
+        throw new Error("interval everyMs must be > 0");
+      return new Date(from.getTime() + schedule.everyMs).toISOString();
+    case "cron":
+      return nextCronRun(schedule.expression, from).toISOString();
+    case "dynamic":
+      return new Date(from.getTime() + (schedule.minIntervalMs ?? 60000)).toISOString();
+  }
+}
+function computeNextAfter(schedule, scheduledFor, finishedAt) {
+  switch (schedule.type) {
+    case "once":
+      return;
+    case "interval": {
+      const anchor = schedule.anchor ?? "fixed_rate";
+      const base = anchor === "fixed_delay" ? finishedAt : scheduledFor;
+      let next = new Date(base.getTime() + schedule.everyMs);
+      while (next.getTime() <= finishedAt.getTime())
+        next = new Date(next.getTime() + schedule.everyMs);
+      return next.toISOString();
+    }
+    case "cron": {
+      let next = nextCronRun(schedule.expression, scheduledFor);
+      while (next.getTime() <= finishedAt.getTime())
+        next = nextCronRun(schedule.expression, next);
+      return next.toISOString();
+    }
+    case "dynamic":
+      return new Date(finishedAt.getTime() + (schedule.minIntervalMs ?? 60000)).toISOString();
+  }
+}
+function latestIntervalSlot(first, now, everyMs) {
+  if (first.getTime() > now.getTime())
+    return first;
+  const steps = Math.floor((now.getTime() - first.getTime()) / everyMs);
+  return new Date(first.getTime() + steps * everyMs);
+}
+function floorToMinute(date) {
+  const floored = new Date(date.getTime());
+  floored.setSeconds(0, 0);
+  return floored;
+}
+var LATEST_CRON_SCAN_LIMIT_MINUTES = 366 * 24 * 60;
+function latestDailyCronSlot(cron, now) {
+  const hoursDesc = [...cron.hour].sort((a, b) => b - a);
+  const minutesDesc = [...cron.minute].sort((a, b) => b - a);
+  const candidate = floorToMinute(now);
+  for (let dayOffset = 0;dayOffset < 2; dayOffset += 1) {
+    const isToday = dayOffset === 0;
+    for (const hour of hoursDesc) {
+      if (isToday && hour > now.getHours())
+        continue;
+      const minuteCap = isToday && hour === now.getHours() ? now.getMinutes() : 59;
+      const minute = minutesDesc.find((value) => value <= minuteCap);
+      if (minute === undefined)
+        continue;
+      candidate.setHours(hour, minute, 0, 0);
+      return candidate;
+    }
+    candidate.setDate(candidate.getDate() - 1);
+  }
+  throw new Error("unreachable: daily cron pattern must match within two days");
+}
+function latestCronSlot(first, now, expression) {
+  if (first.getTime() > now.getTime())
+    return first;
+  const cron = parseCron(expression);
+  if (!cron.domRestricted && !cron.dowRestricted && cron.month.size === 12) {
+    const latest = latestDailyCronSlot(cron, now);
+    return latest.getTime() >= first.getTime() ? latest : first;
+  }
+  const scanFloorMs = Math.max(first.getTime(), now.getTime() - LATEST_CRON_SCAN_LIMIT_MINUTES * MINUTE_MS);
+  const cursor = floorToMinute(now);
+  while (cursor.getTime() >= scanFloorMs) {
+    if (cronMatches(cron, cursor))
+      return cursor;
+    cursor.setMinutes(cursor.getMinutes() - 1);
+  }
+  if (first.getTime() < scanFloorMs) {
+    warnOnce(`latest-cron:${expression}`, `latestCronSlot: no match for "${expression}" within the ${LATEST_CRON_SCAN_LIMIT_MINUTES}-minute scan window; using the stored next run as the latest slot`);
+  }
+  return first;
+}
+var MAX_CATCH_UP_SLOTS = 1000;
+function catchUpSlotLimit(loop) {
+  if (loop.catchUpLimit > MAX_CATCH_UP_SLOTS) {
+    warnOnce(`catch-up-limit:${loop.id}`, `dueSlots: loop ${loop.id} catchUpLimit ${loop.catchUpLimit} exceeds the per-plan cap; using ${MAX_CATCH_UP_SLOTS}`);
+    return MAX_CATCH_UP_SLOTS;
+  }
+  return loop.catchUpLimit;
+}
+function dueSlots(loop, now) {
+  if (!loop.nextRunAt || loop.status !== "active")
+    return { slots: [] };
+  if (loop.expiresAt && new Date(loop.expiresAt).getTime() <= now.getTime())
+    return { slots: [] };
+  const next = assertDate(loop.nextRunAt, "loop.nextRunAt");
+  if (next.getTime() > now.getTime())
+    return { slots: [] };
+  if (loop.retryScheduledFor)
+    return { slots: [loop.retryScheduledFor] };
+  const catchUp = loop.catchUp;
+  switch (loop.schedule.type) {
+    case "once":
+    case "dynamic":
+      return { slots: [next.toISOString()] };
+    case "interval": {
+      if (catchUp === "all") {
+        const limit = catchUpSlotLimit(loop);
+        const slots = [];
+        let cursor = next;
+        while (cursor.getTime() <= now.getTime() && slots.length < limit) {
+          slots.push(cursor.toISOString());
+          cursor = new Date(cursor.getTime() + loop.schedule.everyMs);
+        }
+        return { slots };
+      }
+      if (catchUp === "latest")
+        return { slots: [latestIntervalSlot(next, now, loop.schedule.everyMs).toISOString()] };
+      return { slots: [next.toISOString()] };
+    }
+    case "cron": {
+      if (catchUp === "all") {
+        const limit = catchUpSlotLimit(loop);
+        const slots = [];
+        let cursor = next;
+        while (cursor.getTime() <= now.getTime() && slots.length < limit) {
+          slots.push(cursor.toISOString());
+          cursor = nextCronRun(loop.schedule.expression, cursor);
+        }
+        return { slots };
+      }
+      if (catchUp === "latest")
+        return { slots: [latestCronSlot(next, now, loop.schedule.expression).toISOString()] };
+      return { slots: [next.toISOString()] };
+    }
+  }
+}
+function parseDuration(input) {
+  const match = input.trim().match(/^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/);
+  if (!match)
+    throw new Error(`invalid duration: ${input}`);
+  const value = Number(match[1]);
+  const unit = match[2] ?? "ms";
+  const multiplier = unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60000 : unit === "h" ? 3600000 : 86400000;
+  return Math.round(value * multiplier);
+}
+
+// src/lib/redact.ts
+var SCRUBBED = "[SCRUBBED]";
+var TOKEN_PATTERNS = [
+  /\bsk-ant-[A-Za-z0-9_-]{8,}/g,
+  /\bsk-proj-[A-Za-z0-9_-]{8,}/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\bghp_[A-Za-z0-9]{16,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{16,}\b/g,
+  /\bxox[a-z]-[A-Za-z0-9-]{8,}/g,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{10,}\b/g
+];
+var AUTHORIZATION_PATTERN = /(\bAuthorization(?:\\?["'])?\s*[:=]\s*(?:\\?["'])?(?:Bearer|Basic)\s+)[A-Za-z0-9._~+/=-]{16,}/gi;
+var PEM_PATTERN = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g;
+var ASSIGNMENT_PATTERN = /([A-Za-z0-9_.-]{0,64}(?:key|token|secret|passwd|password|passphrase|credentials?)(?:\\?["'])?\s*[:=]\s*)(\\"([^"\\\r\n]{12,})\\"|"((?:[^"\\\r\n]|\\[^\r\n]){12,})"|'([^'\\\r\n]{12,})'|([A-Za-z0-9+/_.=-]{16,}))/gi;
+var BENIGN_KEY_NAME_PATTERN = /(?:^|[._-])(?:idempotency|dedupe|route)[_-]?key$/i;
+var ASSIGNMENT_HINTS = ["key", "token", "secret", "pass", "credential"];
+function mayContainAssignment(text) {
+  const lowered = text.toLowerCase();
+  return ASSIGNMENT_HINTS.some((hint) => lowered.includes(hint));
+}
+function shannonEntropy(value) {
+  const counts = new Map;
+  for (const char of value)
+    counts.set(char, (counts.get(char) ?? 0) + 1);
+  let entropy = 0;
+  for (const count of counts.values()) {
+    const probability = count / value.length;
+    entropy -= probability * Math.log2(probability);
+  }
+  return entropy;
+}
+function isLikelySecretValue(value) {
+  if (value.length < 12)
+    return false;
+  if (value.includes(SCRUBBED))
+    return false;
+  if (value.startsWith("/") || value.startsWith("~") || value.startsWith("./"))
+    return false;
+  return shannonEntropy(value) >= 3.2;
+}
+function scrubSecrets(text) {
+  if (!text)
+    return text;
+  let scrubbed = text;
+  for (const pattern of TOKEN_PATTERNS)
+    scrubbed = scrubbed.replace(pattern, SCRUBBED);
+  scrubbed = scrubbed.replace(AUTHORIZATION_PATTERN, `$1${SCRUBBED}`);
+  scrubbed = scrubbed.replace(PEM_PATTERN, SCRUBBED);
+  if (!mayContainAssignment(scrubbed))
+    return scrubbed;
+  scrubbed = scrubbed.replace(ASSIGNMENT_PATTERN, (match, prefix, quotedValue, escapedQuoted, doubleQuoted, singleQuoted, bare) => {
+    const value = escapedQuoted ?? doubleQuoted ?? singleQuoted ?? bare ?? "";
+    const keyName = /^[A-Za-z0-9_.-]*/.exec(prefix)?.[0] ?? "";
+    if (BENIGN_KEY_NAME_PATTERN.test(keyName))
+      return match;
+    if (!isLikelySecretValue(value))
+      return match;
+    const quote = quotedValue.startsWith("\\\"") ? "\\\"" : quotedValue.startsWith('"') ? '"' : quotedValue.startsWith("'") ? "'" : "";
+    return `${prefix}${quote}${SCRUBBED}${quote}`;
+  });
+  return scrubbed;
+}
+function scrubSecretsDeep(value) {
+  if (typeof value === "string")
+    return scrubSecrets(value);
+  if (Array.isArray(value))
+    return value.map((entry) => scrubSecretsDeep(entry));
+  if (value !== null && typeof value === "object") {
+    const toJSON = value.toJSON;
+    if (typeof toJSON === "function")
+      return scrubSecretsDeep(toJSON.call(value));
+    const scrubbed = {};
+    for (const [key, entry] of Object.entries(value))
+      scrubbed[key] = scrubSecretsDeep(entry);
+    return scrubbed;
+  }
+  return value;
+}
+
+// src/api/index.ts
 var program = new Command;
+var DEFAULT_BODY_LIMIT_BYTES = 64 * 1024;
+var DEFAULT_EVIDENCE_LIMIT_BYTES = 256 * 1024;
+var MIN_RUNNER_LEASE_MS = 1000;
 program.name("loops-api").description("OpenLoops self-hosted control-plane API foundation").version(packageVersion()).option("-j, --json", "print JSON");
 function wantsJson(opts) {
   return Boolean(program.opts().json || opts?.json);
@@ -272,6 +783,12 @@ function configuredAuthToken() {
 function isLocalBind(host) {
   return ["127.0.0.1", "localhost", "::1"].includes(host);
 }
+function bearerTokenMatches(authorization, token) {
+  const expected = `Bearer ${token}`;
+  const a = new TextEncoder().encode(authorization);
+  const b = new TextEncoder().encode(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
 function authorizeRequest(request, host) {
   if (isLocalBind(host))
     return;
@@ -279,7 +796,13 @@ function authorizeRequest(request, host) {
   if (!token)
     return Response.json({ ok: false, error: "auth_required" }, { status: 401 });
   const authorization = request.headers.get("authorization") ?? "";
-  return authorization === `Bearer ${token}` ? undefined : Response.json({ ok: false, error: "unauthorized" }, { status: 401 });
+  return bearerTokenMatches(authorization, token) ? undefined : Response.json({ ok: false, error: "unauthorized" }, { status: 401 });
+}
+function ok(payload = {}, init) {
+  return Response.json({ ok: true, ...payload }, init);
+}
+function fail(error, status, details) {
+  return Response.json({ ok: false, error, ...details }, { status });
 }
 function apiStatus() {
   return {
@@ -305,10 +828,444 @@ function createLoopsApiServer(opts = {}) {
       if (url.pathname === "/health" || url.pathname === "/status") {
         return Response.json(apiStatus());
       }
-      return Response.json({ ok: false, error: "not_found" }, { status: 404 });
+      return handleV1Request({
+        request,
+        url,
+        storage: opts.storage,
+        bodyLimitBytes: opts.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES,
+        evidenceLimitBytes: opts.evidenceLimitBytes ?? DEFAULT_EVIDENCE_LIMIT_BYTES,
+        now: opts.now ?? (() => new Date)
+      });
     }
   });
 }
+async function handleV1Request(ctx) {
+  const segments = ctx.url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+  if (segments[0] !== "v1")
+    return fail("not_found", 404);
+  if (ctx.request.method === "GET" && segments.length === 1)
+    return ok({ service: "loops-api", version: "v1" });
+  if (ctx.request.method === "GET" && segments[1] === "status")
+    return Response.json(apiStatus());
+  try {
+    if (segments[1] === "loops")
+      return await handleLoopsRequest(ctx, segments.slice(2));
+    if (segments[1] === "runs")
+      return await handleRunsRequest(ctx, segments.slice(2));
+    if (segments[1] === "runners")
+      return await handleRunnerRequest(ctx, segments.slice(2));
+    if (segments[1] === "leases" && segments[2] === "recover" && ctx.request.method === "POST") {
+      return runnerProtocolPending("lease recovery is implemented in the runner protocol stage");
+    }
+    return fail("not_found", 404);
+  } catch (error) {
+    return errorResponse(error);
+  }
+}
+async function handleLoopsRequest(ctx, segments) {
+  const storage = requireStorage(ctx.storage);
+  if (segments.length === 0 && ctx.request.method === "GET") {
+    const loops = await storage.listLoops({
+      status: optionalEnum(ctx.url.searchParams.get("status"), ["active", "paused", "stopped", "expired"]),
+      limit: optionalLimit(ctx.url.searchParams.get("limit")),
+      includeArchived: optionalBoolean(ctx.url.searchParams.get("includeArchived")),
+      archived: optionalBoolean(ctx.url.searchParams.get("archived"))
+    });
+    return ok({ loops: loops.map(publicLoop) });
+  }
+  if (segments.length === 0 && ctx.request.method === "POST") {
+    const body = await readJsonBody(ctx.request, ctx.bodyLimitBytes);
+    const loop = await storage.createLoop(body);
+    return ok({ loop: publicLoop(loop) }, { status: 201 });
+  }
+  const id = segments[0];
+  if (!id)
+    return fail("not_found", 404);
+  if (segments.length === 1 && ctx.request.method === "GET") {
+    const loop = await storage.getLoop(id);
+    if (!loop)
+      throw new LoopNotFoundError(id);
+    return ok({ loop: publicLoop(loop) });
+  }
+  if (segments.length === 1 && ctx.request.method === "PATCH") {
+    const body = await readJsonBody(ctx.request, ctx.bodyLimitBytes);
+    const loop = await storage.updateLoop(id, {
+      status: body.status,
+      nextRunAt: body.nextRunAt === null ? undefined : body.nextRunAt,
+      retryScheduledFor: body.retryScheduledFor === null ? undefined : body.retryScheduledFor,
+      expiresAt: body.expiresAt === null ? undefined : body.expiresAt
+    });
+    return ok({ loop: publicLoop(loop) });
+  }
+  if (segments.length === 1 && ctx.request.method === "DELETE") {
+    return ok({ deleted: await storage.deleteLoop(id) });
+  }
+  if (segments.length === 2 && segments[1] === "archive" && ctx.request.method === "POST") {
+    return ok({ loop: publicLoop(await storage.archiveLoop(id)) });
+  }
+  if (segments.length === 2 && segments[1] === "unarchive" && ctx.request.method === "POST") {
+    return ok({ loop: publicLoop(await storage.unarchiveLoop(id)) });
+  }
+  return fail("not_found", 404);
+}
+async function handleRunsRequest(ctx, segments) {
+  const id = segments[0];
+  if (segments.length === 2 && id && ["heartbeat", "finalize", "evidence"].includes(segments[1] ?? "") && ctx.request.method === "POST") {
+    const storage2 = requireStorage(ctx.storage);
+    const action = segments[1];
+    const now = ctx.now();
+    if (action === "heartbeat")
+      return heartbeatRun(storage2, id, await readJsonBody(ctx.request, ctx.bodyLimitBytes), now);
+    if (action === "finalize")
+      return finalizeRun(storage2, id, await readJsonBody(ctx.request, ctx.bodyLimitBytes), now);
+    return acceptRunEvidence(storage2, id, await readJsonBody(ctx.request, ctx.evidenceLimitBytes), now);
+  }
+  if (segments.length === 2 && id && segments[1] === "recover" && ctx.request.method === "POST") {
+    const storage2 = requireStorage(ctx.storage);
+    const now = ctx.now();
+    const recovered = await storage2.recoverExpiredRunLeasesDetailed(now);
+    for (const run of recovered.abandoned) {
+      const loop = await storage2.getLoop(run.loopId);
+      if (loop)
+        await advanceLoopAfterRun(storage2, loop, run, new Date(run.finishedAt ?? now), false);
+    }
+    return ok({
+      abandoned: recovered.abandoned.map((run) => publicRun(run, false, { redactError: true })),
+      deferred: recovered.deferred.map((run) => publicRun(run, false, { redactError: true }))
+    });
+  }
+  const storage = requireStorage(ctx.storage);
+  const showOutput = optionalBoolean(ctx.url.searchParams.get("showOutput")) ?? false;
+  if (segments.length === 0 && ctx.request.method === "GET") {
+    const runs = await storage.listRuns({
+      loopId: ctx.url.searchParams.get("loopId") ?? undefined,
+      status: optionalEnum(ctx.url.searchParams.get("status"), ["running", "succeeded", "failed", "timed_out", "abandoned", "skipped"]),
+      limit: optionalLimit(ctx.url.searchParams.get("limit"))
+    });
+    return ok({ runs: runs.map((run) => publicRun(run, showOutput, { redactError: true })) });
+  }
+  if (!id)
+    return fail("not_found", 404);
+  if (segments.length === 1 && ctx.request.method === "GET") {
+    const run = await storage.getRun(id);
+    if (!run)
+      return fail("run_not_found", 404);
+    return ok({ run: publicRun(run, showOutput, { redactError: true }) });
+  }
+  return fail("not_found", 404);
+}
+async function handleRunnerRequest(ctx, segments) {
+  if (ctx.request.method !== "POST")
+    return fail("not_found", 404);
+  const action = segments.length === 1 ? segments[0] : segments[1];
+  if (action === "register" || action === "heartbeat") {
+    const body = await readJsonBody(ctx.request, ctx.bodyLimitBytes);
+    return ok({ runner: runnerRecord(body) });
+  }
+  if (action === "poll" || action === "claim") {
+    const storage = requireStorage(ctx.storage);
+    const body = await readJsonBody(ctx.request, ctx.bodyLimitBytes);
+    const runner = runnerRecord(body);
+    const claims = await claimRuns(storage, runner, {
+      now: ctx.now(),
+      maxClaims: optionalPositiveInteger(body.maxClaims, 1, 100) ?? 1
+    });
+    return ok({ runner, claims });
+  }
+  return fail("not_found", 404);
+}
+function runnerRecord(body) {
+  const machineId = optionalString(body.machineId);
+  const hostname = optionalString(body.hostname);
+  const id = optionalString(body.runnerId) ?? machineId ?? hostname;
+  if (!id)
+    throw Object.assign(new Error("runner_id_required"), { status: 422 });
+  return {
+    id,
+    machineId,
+    hostname,
+    labels: stringRecord(body.labels),
+    capabilities: objectRecord(body.capabilities),
+    lastSeenAt: new Date().toISOString()
+  };
+}
+async function claimRuns(storage, runner, opts) {
+  const claims = [];
+  for (const loop of await storage.dueLoops(opts.now)) {
+    if (claims.length >= opts.maxClaims)
+      break;
+    if (!runnerMatchesLoop(loop.machine, runner))
+      continue;
+    if (loop.target.type === "workflow")
+      continue;
+    if (loop.overlap === "skip" && (await storage.listRuns({ loopId: loop.id, status: "running", limit: 1 })).length > 0)
+      continue;
+    for (const slot of dueSlots(loop, opts.now).slots) {
+      if (claims.length >= opts.maxClaims)
+        break;
+      const claim = await storage.claimRun(loop, slot, runner.id, opts.now);
+      if (!claim)
+        continue;
+      const run = await storage.heartbeatRunLease(claim.run.id, runner.id, runnerLeaseMs(claim.loop.leaseMs), opts.now, { claimToken: claim.claimToken }) ?? claim.run;
+      claims.push({
+        loop: publicLoop(claim.loop),
+        run: publicRun(run, false, { redactError: true }),
+        claimToken: claim.claimToken
+      });
+      if (loop.overlap === "skip")
+        break;
+    }
+  }
+  return claims;
+}
+function runnerMatchesLoop(machine, runner) {
+  if (!machine)
+    return true;
+  const candidates = new Set([runner.id, runner.machineId, runner.hostname].filter(Boolean));
+  return candidates.has(machine.id) || (machine.requestedId ? candidates.has(machine.requestedId) : false);
+}
+async function heartbeatRun(storage, runId, body, now) {
+  const claimToken = requiredString(body.claimToken, "claimToken");
+  const run = await storage.getRun(runId);
+  if (!run)
+    return fail("run_not_found", 404);
+  if (run.status !== "running" || !run.claimedBy)
+    return fail("run_not_running", 409);
+  const loop = await storage.getLoop(run.loopId);
+  if (!loop)
+    return fail("loop_not_found", 404);
+  const heartbeat = await storage.heartbeatRunLease(run.id, run.claimedBy, runnerLeaseMs(optionalPositiveInteger(body.leaseMs, 1, 24 * 60 * 60000) ?? loop.leaseMs), now, { claimToken });
+  if (!heartbeat)
+    return fail("stale_claim", 409);
+  return ok({ run: publicRun(heartbeat, false, { redactError: true }) });
+}
+async function finalizeRun(storage, runId, body, now) {
+  const claimToken = requiredString(body.claimToken, "claimToken");
+  const status = optionalEnum(optionalString(body.status) ?? null, ["succeeded", "failed", "timed_out"]);
+  if (!status)
+    throw Object.assign(new Error("status_required"), { status: 422 });
+  const existing = await storage.getRun(runId);
+  if (!existing)
+    return fail("run_not_found", 404);
+  if (existing.status !== "running" || !existing.claimedBy)
+    return fail("run_not_running", 409);
+  const loop = await storage.getLoop(existing.loopId);
+  if (!loop)
+    return fail("loop_not_found", 404);
+  const finishedAt = optionalIsoString(body.finishedAt) ?? new Date().toISOString();
+  const durationMs = optionalPositiveInteger(body.durationMs, 0, Number.MAX_SAFE_INTEGER) ?? Math.max(0, new Date(finishedAt).getTime() - new Date(existing.startedAt ?? existing.createdAt).getTime());
+  const finalized = await storage.finalizeRun(runId, {
+    status,
+    finishedAt,
+    durationMs,
+    stdout: optionalText(body.stdout) ?? "",
+    stderr: optionalText(body.stderr) ?? "",
+    error: optionalText(body.error),
+    exitCode: optionalInteger(body.exitCode),
+    pid: optionalInteger(body.pid)
+  }, { claimedBy: existing.claimedBy, claimToken, now });
+  if (finalized.status === "running")
+    return fail("stale_claim", 409);
+  await advanceLoopAfterRun(storage, loop, finalized, new Date(finalized.finishedAt ?? finishedAt), finalized.status === "succeeded");
+  return ok({ run: publicRun(finalized, false, { redactError: true }) });
+}
+async function acceptRunEvidence(storage, runId, body, now) {
+  const heartbeat = await heartbeatRun(storage, runId, body, now);
+  if (!heartbeat.ok)
+    return heartbeat;
+  return ok({ accepted: true, evidence: scrubSecretsDeep(body.evidence ?? body) });
+}
+async function advanceLoopAfterRun(storage, loop, run, finishedAt, succeeded) {
+  if (run.status === "running")
+    return;
+  const current = await storage.getLoop(loop.id);
+  if (!current || current.status !== "active" || current.archivedAt)
+    return;
+  if (current.retryScheduledFor && current.retryScheduledFor !== run.scheduledFor)
+    return;
+  if (!succeeded && run.attempt < current.maxAttempts) {
+    await storage.updateLoop(current.id, {
+      status: "active",
+      nextRunAt: new Date(finishedAt.getTime() + retryDelayMs(current, run)).toISOString(),
+      retryScheduledFor: run.scheduledFor
+    });
+    return;
+  }
+  const nextRunAt = computeNextAfter(current.schedule, new Date(run.scheduledFor), finishedAt);
+  await storage.updateLoop(current.id, {
+    status: nextRunAt ? "active" : "stopped",
+    nextRunAt,
+    retryScheduledFor: undefined
+  });
+}
+function retryDelayMs(loop, run) {
+  const growth = 2 ** Math.min(Math.max(1, run.attempt) - 1, 20);
+  return Math.min(6 * 60 * 60000, loop.retryDelayMs * growth);
+}
+function runnerLeaseMs(leaseMs) {
+  return Math.max(MIN_RUNNER_LEASE_MS, leaseMs);
+}
+function requireStorage(storage) {
+  if (!storage)
+    throw Object.assign(new Error("storage_unconfigured"), { status: 503, code: "storage_unconfigured" });
+  return storage;
+}
+async function readJsonBody(request, limitBytes) {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (!isJsonContentType(contentType))
+    throw Object.assign(new Error("unsupported_media_type"), { status: 415 });
+  const text = await readBodyText(request, limitBytes);
+  try {
+    return JSON.parse(text || "{}");
+  } catch {
+    throw Object.assign(new Error("invalid_json"), { status: 400 });
+  }
+}
+function isJsonContentType(contentType) {
+  const mediaType = contentType.split(";")[0]?.trim().toLowerCase();
+  return mediaType === "application/json" || Boolean(mediaType?.endsWith("+json"));
+}
+async function readBodyText(request, limitBytes) {
+  const contentLength = request.headers.get("content-length");
+  if (contentLength) {
+    const declaredBytes = Number(contentLength);
+    if (!Number.isFinite(declaredBytes) || declaredBytes < 0)
+      throw Object.assign(new Error("invalid_content_length"), { status: 400 });
+    if (declaredBytes > limitBytes)
+      throw Object.assign(new Error("body_too_large"), { status: 413 });
+  }
+  if (!request.body)
+    return "";
+  const reader = request.body.getReader();
+  const chunks = [];
+  let receivedBytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    if (!value)
+      continue;
+    receivedBytes += value.byteLength;
+    if (receivedBytes > limitBytes) {
+      await reader.cancel().catch(() => {
+        return;
+      });
+      throw Object.assign(new Error("body_too_large"), { status: 413 });
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(receivedBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+function runnerProtocolPending(message) {
+  return fail("runner_protocol_pending", 501, { message });
+}
+function optionalLimit(value) {
+  if (value == null || value === "")
+    return;
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+    throw Object.assign(new Error("invalid_limit"), { status: 422 });
+  return limit;
+}
+function optionalString(value) {
+  if (value === undefined || value === null)
+    return;
+  if (typeof value !== "string" || value.trim() === "")
+    throw Object.assign(new Error("invalid_string"), { status: 422 });
+  return value.trim();
+}
+function requiredString(value, name) {
+  const result = optionalString(value);
+  if (!result)
+    throw Object.assign(new Error(`${name}_required`), { status: 422 });
+  return result;
+}
+function optionalText(value) {
+  if (value === undefined || value === null)
+    return;
+  if (typeof value !== "string")
+    throw Object.assign(new Error("invalid_string"), { status: 422 });
+  return value;
+}
+function optionalInteger(value) {
+  if (value === undefined || value === null || value === "")
+    return;
+  const result = Number(value);
+  if (!Number.isInteger(result))
+    throw Object.assign(new Error("invalid_integer"), { status: 422 });
+  return result;
+}
+function optionalPositiveInteger(value, min, max) {
+  const result = optionalInteger(value);
+  if (result === undefined)
+    return;
+  if (result < min || result > max)
+    throw Object.assign(new Error("invalid_integer_range"), { status: 422 });
+  return result;
+}
+function optionalIsoString(value) {
+  const text = optionalString(value);
+  if (!text)
+    return;
+  const parsed = new Date(text);
+  if (Number.isNaN(parsed.getTime()))
+    throw Object.assign(new Error("invalid_datetime"), { status: 422 });
+  return parsed.toISOString();
+}
+function stringRecord(value) {
+  if (value === undefined || value === null)
+    return {};
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw Object.assign(new Error("invalid_string_record"), { status: 422 });
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry !== "string")
+      throw Object.assign(new Error("invalid_string_record"), { status: 422 });
+    result[key] = entry;
+  }
+  return result;
+}
+function objectRecord(value) {
+  if (value === undefined || value === null)
+    return {};
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw Object.assign(new Error("invalid_object"), { status: 422 });
+  return value;
+}
+function optionalBoolean(value) {
+  if (value == null || value === "")
+    return;
+  if (["1", "true", "yes"].includes(value.toLowerCase()))
+    return true;
+  if (["0", "false", "no"].includes(value.toLowerCase()))
+    return false;
+  throw Object.assign(new Error("invalid_boolean"), { status: 422 });
+}
+function optionalEnum(value, allowed) {
+  if (value == null || value === "")
+    return;
+  if (allowed.includes(value))
+    return value;
+  throw Object.assign(new Error("invalid_filter"), { status: 422 });
+}
+function errorResponse(error) {
+  if (error instanceof LoopNotFoundError)
+    return fail("loop_not_found", 404, { message: error.message });
+  if (error instanceof LoopArchivedError)
+    return fail("loop_archived", 409, { message: error.message });
+  if (error instanceof ValidationError)
+    return fail("validation_failed", 422, { message: error.message });
+  const status = typeof error === "object" && error && "status" in error && typeof error.status === "number" ? error.status : 500;
+  const message = error instanceof Error ? error.message : String(error);
+  const code = typeof error === "object" && error && "code" in error && typeof error.code === "string" ? error.code : status === 500 ? "internal_error" : message;
+  return fail(code, status, status === 500 ? { message: redact(message, 240) } : undefined);
+}
 async function main(argv = process.argv) {
   await program.parseAsync(argv);
 }