@hasna/loops 0.4.13 → 0.4.22

package/dist/runner/index.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.13",
+  version: "0.4.22",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -12,6 +12,7 @@ var package_default = {
     loops: "dist/cli/index.js",
     "loops-daemon": "dist/daemon/index.js",
     "loops-api": "dist/api/index.js",
+    "loops-serve": "dist/serve/index.js",
     "loops-runner": "dist/runner/index.js",
     "loops-mcp": "dist/mcp/index.js"
   },
@@ -24,6 +25,14 @@ var package_default = {
       types: "./dist/sdk/index.d.ts",
       import: "./dist/sdk/index.js"
     },
+    "./sdk/http": {
+      types: "./dist/sdk/http.d.ts",
+      import: "./dist/sdk/http.js"
+    },
+    "./serve": {
+      types: "./dist/serve/index.d.ts",
+      import: "./dist/serve/index.js"
+    },
     "./mcp": {
       types: "./dist/mcp/index.d.ts",
       import: "./dist/mcp/index.js"
@@ -69,7 +78,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 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: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/serve/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/sdk/http.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/serve/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",
@@ -109,13 +118,16 @@ var package_default = {
     "@openrouter/ai-sdk-provider": "2.9.1",
     ai: "6.0.204",
     commander: "^13.1.0",
+    pg: "^8.13.1",
     zod: "4.4.3"
   },
   optionalDependencies: {
-    "@hasna/machines": "0.0.49"
+    "@hasna/machines": "0.0.49",
+    "@hasna/contracts": "^0.4.2"
   },
   devDependencies: {
     "@types/bun": "latest",
+    "@types/pg": "^8.11.10",
     typescript: "^5.7.3"
   },
   publishConfig: {
@@ -1086,6 +1098,7 @@ var TRANSPORT_ENV_KEYS = new Set([
   "LOGNAME",
   "PATH",
   "SHELL",
+  "SHLVL",
   "SSH_AGENT_PID",
   "SSH_AUTH_SOCK",
   "TERM",
@@ -1118,6 +1131,32 @@ function timeoutResult(startedAt, error, fields = {}) {
 function successResult(startedAt, fields = {}) {
   return buildResult("succeeded", startedAt, fields);
 }
+function codewithJsonlHasTerminalSuccess(stdout) {
+  for (const line of stdout.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.startsWith("{"))
+      continue;
+    let event;
+    try {
+      event = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (!event || typeof event !== "object")
+      continue;
+    const record = event;
+    if (record.type === "task_complete")
+      return true;
+    const payload = record.payload;
+    if (payload && typeof payload === "object" && payload.type === "task_complete") {
+      return true;
+    }
+  }
+  return false;
+}
+function codewithJsonlReconciledSuccess(spec, fields) {
+  return spec.agentProvider === "codewith" && codewithJsonlHasTerminalSuccess(fields.stdout ?? "");
+}
 function notifySpawn(pid, opts) {
   if (!pid)
     return;
@@ -1133,10 +1172,48 @@ function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function codewithProfileCandidateFromLine(line) {
-  const cols = line.trim().split(/\s+/);
-  if (cols[0] === "*")
-    return cols[1];
-  return cols[0];
+  const trimmed = line.trim();
+  if (!trimmed || trimmed === "No auth profiles saved.")
+    return;
+  const cols = trimmed.split(/\s+/);
+  const candidate = cols[0] === "*" ? cols[1] : cols[0];
+  if (candidate === "NAME" && (cols[1] === "ACCOUNT" || cols[2] === "ACCOUNT"))
+    return;
+  if (candidate === '"name":') {
+    const jsonName = trimmed.match(/"name"\s*:\s*"([^"]+)"/)?.[1];
+    if (jsonName)
+      return jsonName;
+  }
+  return candidate;
+}
+function codewithProfileCandidatesFromJson(value) {
+  const candidates = [];
+  const root = value && typeof value === "object" ? value : undefined;
+  const addProfile = (entry) => {
+    if (!entry || typeof entry !== "object")
+      return;
+    const name = entry.name;
+    if (typeof name === "string" && name)
+      candidates.push(name);
+  };
+  const data = root?.data;
+  if (Array.isArray(data))
+    data.forEach(addProfile);
+  const profiles = root?.profiles;
+  if (Array.isArray(profiles))
+    profiles.forEach(addProfile);
+  return candidates;
+}
+function codewithProfileCandidatesFromOutput(output) {
+  const trimmed = output.trim();
+  const jsonStart = trimmed.indexOf("{");
+  const jsonEnd = trimmed.lastIndexOf("}");
+  if (jsonStart >= 0 && jsonEnd >= jsonStart) {
+    try {
+      return codewithProfileCandidatesFromJson(JSON.parse(trimmed.slice(jsonStart, jsonEnd + 1)));
+    } catch {}
+  }
+  return output.split(/\r?\n/).map(codewithProfileCandidateFromLine).filter(Boolean);
 }
 function codewithProfileForError(profile) {
   return /[\u0000-\u001F\u007F]/.test(profile) ? JSON.stringify(profile) ?? profile : profile;
@@ -1229,6 +1306,7 @@ function commandSpec(target, opts) {
     preflightAnyOf: invocation.preflightAnyOf,
     stdin: invocation.stdin,
     allowlist: agentTarget.allowlist,
+    agentProvider: agentTarget.provider,
     worktree: agentTarget.worktree
   };
 }
@@ -1242,6 +1320,7 @@ function composeExecutionEnv(spec, metadata, opts, accountEnv) {
   Object.assign(env, spec.env ?? {});
   Object.assign(env, allowlistEnv(spec.allowlist));
   env.PATH = normalizeExecutionPath(env);
+  env.SHLVL ||= "1";
   Object.assign(env, metadataEnv(metadata));
   return env;
 }
@@ -1313,7 +1392,7 @@ function remoteWorktreePrepareLines(worktree) {
   return [
     "__openloops_prepare_worktree() {",
     `  local repo=${shellQuote(repoRoot)} path=${shellQuote(path)} branch=${shellQuote(branch)}`,
-    "  local top expected_common actual_common current",
+    "  local top expected_common actual_common current status recovered",
     '  if [ -L "$path" ]; then echo "refusing symlinked worktree path $path" >&2; return 1; fi',
     '  if [ -e "$path" ]; then',
     '    top="$(git -C "$path" rev-parse --show-toplevel 2>/dev/null)" || { echo "refusing to reuse non-worktree path: $path" >&2; return 1; }',
@@ -1322,7 +1401,19 @@ function remoteWorktreePrepareLines(worktree) {
     '    actual_common="$(cd "$path" 2>/dev/null && cd "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null && pwd -P)"',
     '    if [ -z "$expected_common" ] || [ "$expected_common" != "$actual_common" ]; then echo "existing worktree $path belongs to a different git common dir" >&2; return 1; fi',
     '    current="$(git -C "$path" branch --show-current 2>/dev/null)"',
-    '    if [ "$current" != "$branch" ]; then echo "existing worktree $path is on branch ${current:-unknown}, expected $branch" >&2; return 1; fi',
+    '    if [ "$current" != "$branch" ]; then',
+    '      status="$(git -C "$path" status --porcelain=v1 --untracked-files=all 2>/dev/null)" || { echo "existing worktree $path is on branch ${current:-unknown}, expected $branch, and cleanliness could not be checked; inspect or remove the stale worktree" >&2; return 1; }',
+    '      if [ -n "$status" ]; then echo "existing worktree $path is on branch ${current:-unknown}, expected $branch, and has local changes; commit/stash them or remove the stale worktree before retrying" >&2; return 1; fi',
+    '      if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch"; then',
+    '        git -C "$path" checkout "$branch" 1>&2 || { echo "existing worktree $path is clean but could not switch from branch ${current:-unknown} to expected $branch; remove/prune the stale worktree or free the branch before retrying" >&2; return 1; }',
+    '      elif [ -z "$current" ]; then',
+    '        git -C "$path" checkout -b "$branch" 1>&2 || { echo "existing worktree $path is clean but could not recreate expected branch $branch at the current detached HEAD; remove/prune the stale worktree before retrying" >&2; return 1; }',
+    "      else",
+    '        echo "existing worktree $path is on branch $current, expected $branch, but expected branch does not exist; remove/prune the stale worktree or recreate the expected branch before retrying" >&2; return 1',
+    "      fi",
+    '      recovered="$(git -C "$path" branch --show-current 2>/dev/null)"',
+    '      if [ "$recovered" != "$branch" ]; then echo "existing worktree $path branch recovery ended on ${recovered:-unknown}, expected $branch; remove/prune the stale worktree before retrying" >&2; return 1; fi',
+    "    fi",
     "    return 0",
     "  fi",
     '  git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "worktree repoRoot is not a git repository: $repo" >&2; return 1; }',
@@ -1388,7 +1479,7 @@ function remotePreflightScript(spec, metadata) {
   }
   if (spec.nativeAuthProfile?.provider === "codewith") {
     const profileForError = codewithProfileForError(spec.nativeAuthProfile.profile);
-    lines.push(`__OPENLOOPS_CODEWITH_PROFILE=${shellQuote(spec.nativeAuthProfile.profile)}`, "export __OPENLOOPS_CODEWITH_PROFILE", `__OPENLOOPS_CODEWITH_PROFILES="$(${shellQuote(spec.command)} profile list)" || {`, `  printf '%s\\n' ${shellQuote("codewith auth profile preflight failed")} >&2`, "  exit 1", "}", `if ! printf '%s\\n' "$__OPENLOOPS_CODEWITH_PROFILES" | awk 'NR > 1 { candidate = ($1 == "*" ? $2 : $1); if (candidate == ENVIRON["__OPENLOOPS_CODEWITH_PROFILE"]) found = 1 } END { exit(found ? 0 : 1) }'; then`, `  printf '%s\\n' ${shellQuote(`codewith auth profile not found: ${profileForError}`)} >&2`, "  exit 1", "fi");
+    lines.push(`__OPENLOOPS_CODEWITH_PROFILE=${shellQuote(spec.nativeAuthProfile.profile)}`, "export __OPENLOOPS_CODEWITH_PROFILE", "__openloops_codewith_profile_list_contains() {", `  printf '%s\\n' "$__OPENLOOPS_CODEWITH_PROFILES" | awk '{ line = $0; gsub(/^[[:space:]]+|[[:space:]]+$/, "", line); if (line == "" || line == "No auth profiles saved.") next; if (line ~ /"(data|profiles)"[[:space:]]*:[[:space:]]*\\[/) { in_profiles = 1; next } if (in_profiles && line ~ /^\\]/) { in_profiles = 0; next } json = line; if (in_profiles && json ~ /"name"[[:space:]]*:[[:space:]]*"/) { sub(/^.*"name"[[:space:]]*:[[:space:]]*"/, "", json); sub(/".*$/, "", json); if (json == ENVIRON["__OPENLOOPS_CODEWITH_PROFILE"]) found = 1; next } split(line, cols, /[[:space:]]+/); candidate = (cols[1] == "*" ? cols[2] : cols[1]); if (candidate == "NAME" && (cols[2] == "ACCOUNT" || cols[3] == "ACCOUNT")) next; if (candidate == ENVIRON["__OPENLOOPS_CODEWITH_PROFILE"]) found = 1 } END { exit(found ? 0 : 1) }'`, "}", `if __OPENLOOPS_CODEWITH_PROFILES="$(${shellQuote(spec.command)} profile list --json 2>/dev/null)" && __openloops_codewith_profile_list_contains; then`, "  :", "else", `  __OPENLOOPS_CODEWITH_PROFILES="$(${shellQuote(spec.command)} profile list)" || {`, `    printf '%s\\n' ${shellQuote("codewith auth profile preflight failed")} >&2`, "    exit 1", "  }", "  if ! __openloops_codewith_profile_list_contains; then", `    printf '%s\\n' ${shellQuote(`codewith auth profile not found: ${profileForError}`)} >&2`, "    exit 1", "  fi", "fi");
   }
   return lines.join(`
 `);
@@ -1403,9 +1494,28 @@ function transportEnv(opts) {
       env[key] = value;
   }
   env.PATH = normalizeExecutionPath(env);
+  env.SHLVL ||= "1";
   return env;
 }
+function remotePreflightFailureMessage(machineId, detail) {
+  const normalized = detail.trim();
+  if (/Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED|Offending .*key in .*known_hosts/i.test(normalized)) {
+    return [
+      `remote preflight failed on ${machineId}: SSH host key verification failed.`,
+      `Verify ${machineId}'s host identity and repair SSH known_hosts/trust material outside OpenLoops;`,
+      "OpenLoops will not disable host-key checking or modify known_hosts automatically.",
+      normalized ? `Transport detail: ${normalized}` : ""
+    ].filter(Boolean).join(" ");
+  }
+  return `remote preflight failed on ${machineId}${normalized ? `: ${normalized}` : ""}`;
+}
 function assertCodewithProfileListed(profile, result) {
+  const profiles = codewithProfileSetFromResult(result);
+  if (!profiles.has(profile)) {
+    throw new Error(`codewith auth profile not found: ${codewithProfileForError(profile)}`);
+  }
+}
+function codewithProfileSetFromResult(result) {
   if (result.error) {
     throw new Error(`codewith auth profile preflight failed: ${result.error}`);
   }
@@ -1413,32 +1523,45 @@ function assertCodewithProfileListed(profile, result) {
     const detail = (result.stderr || result.stdout || `exit ${result.status ?? "unknown"}`).trim();
     throw new Error(`codewith auth profile preflight failed${detail ? `: ${detail}` : ""}`);
   }
-  const profiles = new Set((result.stdout || "").split(/\r?\n/).slice(1).map(codewithProfileCandidateFromLine).filter(Boolean));
-  if (!profiles.has(profile)) {
-    throw new Error(`codewith auth profile not found: ${codewithProfileForError(profile)}`);
-  }
+  return new Set(codewithProfileCandidatesFromOutput(result.stdout || ""));
 }
 function preflightNativeAuthProfileSync(spec, env) {
   if (spec.nativeAuthProfile?.provider !== "codewith")
     return;
-  const result = spawnSync3(spec.command, ["profile", "list"], {
-    encoding: "utf8",
-    env,
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: 15000
-  });
-  assertCodewithProfileListed(spec.nativeAuthProfile.profile, {
-    status: result.status,
-    stdout: result.stdout ?? "",
-    stderr: result.stderr ?? "",
-    error: result.error?.message
-  });
+  const runProfileList = (args) => {
+    const result = spawnSync3(spec.command, args, {
+      encoding: "utf8",
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15000
+    });
+    return {
+      status: result.status,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      error: result.error?.message
+    };
+  };
+  const jsonResult = runProfileList(["profile", "list", "--json"]);
+  try {
+    if (codewithProfileSetFromResult(jsonResult).has(spec.nativeAuthProfile.profile))
+      return;
+  } catch {}
+  assertCodewithProfileListed(spec.nativeAuthProfile.profile, runProfileList(["profile", "list"]));
 }
 async function preflightNativeAuthProfile(spec, env) {
   if (spec.nativeAuthProfile?.provider !== "codewith")
     return;
-  const result = await spawnCapture(spec.command, ["profile", "list"], { env, timeoutMs: 15000 });
-  assertCodewithProfileListed(spec.nativeAuthProfile.profile, result);
+  const jsonResult = await spawnCapture(spec.command, ["profile", "list", "--json"], { env, timeoutMs: 15000 });
+  try {
+    if (codewithProfileSetFromResult(jsonResult).has(spec.nativeAuthProfile.profile))
+      return;
+  } catch {}
+  const tableResult = await spawnCapture(spec.command, ["profile", "list"], { env, timeoutMs: 15000 });
+  assertCodewithProfileListed(spec.nativeAuthProfile.profile, tableResult);
+}
+function spawnDetail(result) {
+  return (result.stderr || result.stdout || result.error || "").toString().trim();
 }
 function resolvedDirEquals(left, right) {
   try {
@@ -1489,8 +1612,45 @@ async function ensureLocalWorktree(worktree, env) {
     }
     const current = await git(["-C", path, "branch", "--show-current"]);
     const actualBranch = current.stdout.trim();
-    if (current.error || (current.status ?? 1) !== 0 || actualBranch !== branch) {
-      return { error: `existing worktree ${path} is on branch ${actualBranch || "unknown"}, expected ${branch}` };
+    if (current.error || (current.status ?? 1) !== 0) {
+      return { error: `existing worktree ${path} branch could not be inspected${spawnDetail(current) ? `: ${spawnDetail(current)}` : ""}` };
+    }
+    if (actualBranch !== branch) {
+      const actualLabel = actualBranch || "unknown";
+      const status = await git(["-C", path, "status", "--porcelain=v1", "--untracked-files=all"]);
+      if (status.error || (status.status ?? 1) !== 0) {
+        const detail = spawnDetail(status);
+        return {
+          error: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, and cleanliness could not be checked; inspect or remove the stale worktree${detail ? `: ${detail}` : ""}`
+        };
+      }
+      if (status.stdout.trim()) {
+        return {
+          error: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, and has local changes; commit/stash them or remove the stale worktree before retrying`
+        };
+      }
+      const hasBranch2 = await git(["-C", repoRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+      const checkout = hasBranch2.status === 0 ? await git(["-C", path, "checkout", branch]) : actualBranch ? {
+        status: 1,
+        stdout: "",
+        stderr: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, but expected branch does not exist; remove/prune the stale worktree or recreate the expected branch before retrying`,
+        signal: null,
+        timedOut: false
+      } : await git(["-C", path, "checkout", "-b", branch]);
+      if (checkout.error || (checkout.status ?? 1) !== 0) {
+        const detail = spawnDetail(checkout);
+        return {
+          error: `existing worktree ${path} is clean but could not recover branch ${branch} from ${actualLabel}; remove/prune the stale worktree before retrying${detail ? `: ${detail}` : ""}`
+        };
+      }
+      const recovered = await git(["-C", path, "branch", "--show-current"]);
+      if (recovered.error || (recovered.status ?? 1) !== 0 || recovered.stdout.trim() !== branch) {
+        const recoveredBranch = recovered.stdout.trim() || "unknown";
+        const detail = spawnDetail(recovered);
+        return {
+          error: `existing worktree ${path} branch recovery ended on ${recoveredBranch}, expected ${branch}; remove/prune the stale worktree before retrying${detail ? `: ${detail}` : ""}`
+        };
+      }
     }
     return { cwd: worktree.cwd };
   }
@@ -1506,7 +1666,7 @@ async function ensureLocalWorktree(worktree, env) {
   const hasBranch = await git(["-C", repoRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
   const add = hasBranch.status === 0 ? await git(["-C", repoRoot, "worktree", "add", path, branch]) : await git(["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
   if (add.error || (add.status ?? 1) !== 0) {
-    const detail = (add.stderr || add.stdout || add.error || "").toString().trim();
+    const detail = spawnDetail(add);
     return { error: `git worktree add failed for ${path}${detail ? `: ${detail}` : ""}` };
   }
   return { cwd: worktree.cwd };
@@ -1552,7 +1712,7 @@ function preflightRemoteSpec(spec, machine, metadata, opts) {
     throw new Error(`remote preflight failed on ${machine.id}: ${result.error.message}`);
   if ((result.status ?? 1) !== 0) {
     const detail = (result.stderr || result.stdout || `exit ${result.status ?? "unknown"}`).trim();
-    throw new Error(`remote preflight failed on ${machine.id}${detail ? `: ${detail}` : ""}`);
+    throw new Error(remotePreflightFailureMessage(machine.id, detail));
   }
 }
 async function executeRemoteSpec(spec, machine, metadata, opts, fallbackSpec) {
@@ -1640,6 +1800,9 @@ async function executeRemoteSpec(spec, machine, metadata, opts, fallbackSpec) {
   if (timedOut || idleTimedOut) {
     return timeoutResult(startedAt, idleTimedOut ? `idle timed out after ${spec.idleTimeoutMs}ms without stdout/stderr` : `timed out after ${spec.timeoutMs}ms`, fields);
   }
+  if (!error && exitCode !== 0 && codewithJsonlReconciledSuccess(spec, fields)) {
+    return successResult(startedAt, fields);
+  }
   if (error || exitCode !== 0) {
     return failureResult(startedAt, error ?? `remote process on ${machine.id} exited with code ${exitCode ?? "unknown"}`, fields);
   }
@@ -1775,6 +1938,9 @@ async function executeTarget(target, metadata = {}, opts = {}) {
   if (timedOut || idleTimedOut) {
     return timeoutResult(startedAt, idleTimedOut ? `idle timed out after ${spec.idleTimeoutMs}ms without stdout/stderr` : `timed out after ${spec.timeoutMs}ms`, fields);
   }
+  if (!error && exitCode !== 0 && codewithJsonlReconciledSuccess(spec, fields)) {
+    return successResult(startedAt, fields);
+  }
   if (error || exitCode !== 0) {
     return failureResult(startedAt, error ?? `process exited with code ${exitCode ?? "unknown"}`, fields);
   }

package/dist/sdk/http.d.ts

@@ -0,0 +1,182 @@
+export interface Foundation {
+    "status": string;
+    "version": string;
+    "mode": string;
+    "service"?: string;
+    "detail"?: string;
+}
+export interface Loop {
+    "id": string;
+    "name": string;
+    "description"?: string | null;
+    "status": string;
+    "schedule"?: Record<string, unknown>;
+    "target"?: Record<string, unknown>;
+    "nextRunAt"?: string | null;
+    "createdAt"?: string;
+    "updatedAt"?: string;
+}
+export interface CreateLoopInput {
+    "name": string;
+    "description"?: string;
+    "schedule": Record<string, unknown>;
+    "target": Record<string, unknown>;
+}
+export interface UpdateLoopInput {
+    "status"?: "active" | "paused" | "stopped" | "expired";
+    "nextRunAt"?: string | null;
+    "retryScheduledFor"?: string | null;
+    "expiresAt"?: string | null;
+}
+export interface Run {
+    "id": string;
+    "loopId": string;
+    "status": string;
+    "attempt"?: number;
+    "scheduledFor"?: string;
+    "startedAt"?: string | null;
+    "finishedAt"?: string | null;
+}
+export interface LoopResponse {
+    "ok": boolean;
+    "loop": Loop;
+}
+export interface LoopListResponse {
+    "ok": boolean;
+    "loops": Array<Loop>;
+}
+export interface RunResponse {
+    "ok": boolean;
+    "run": Run;
+}
+export interface RunListResponse {
+    "ok": boolean;
+    "runs": Array<Run>;
+}
+export interface DeleteResponse {
+    "ok": boolean;
+    "deleted": boolean;
+}
+export type RunReceiptMachine = string | Record<string, unknown>;
+export interface RunReceiptSummary {
+    "text"?: string;
+    "stdout_bytes": number;
+    "stderr_bytes": number;
+    "stdout_excerpt"?: string;
+    "stderr_excerpt"?: string;
+    "error"?: string;
+    "duration_ms"?: number;
+}
+export interface RunReceipt {
+    "loop_id": string;
+    "run_id": string;
+    "machine": RunReceiptMachine;
+    "repo": string;
+    "task_ids": Array<string>;
+    "knowledge_ids": Array<string>;
+    "digest_id": string;
+    "started_at": string | null;
+    "finished_at": string | null;
+    "status": string;
+    "exit_code": number | null;
+    "summary": RunReceiptSummary;
+    "evidence_paths": Array<string>;
+    "created_at": string;
+    "updated_at": string;
+}
+export interface WriteRunReceiptInput {
+    "loop_id"?: string;
+    "run_id": string;
+    "machine"?: RunReceiptMachine;
+    "repo"?: string;
+    "task_ids"?: Array<string>;
+    "knowledge_ids"?: Array<string>;
+    "digest_id"?: string;
+    "started_at"?: string | null;
+    "finished_at"?: string | null;
+    "status"?: string;
+    "exit_code"?: number | null;
+    "summary"?: string | RunReceiptSummary | null;
+    "evidence_paths"?: Array<string>;
+    "stdout"?: string;
+    "stderr"?: string;
+    "error"?: string;
+    "duration_ms"?: number;
+}
+export interface RunReceiptResponse {
+    "ok": boolean;
+    "receipt": RunReceipt;
+}
+export interface RunReceiptListResponse {
+    "ok": boolean;
+    "receipts": Array<RunReceipt>;
+}
+export interface LoopsClientOptions {
+    /** Base URL, e.g. process.env.APP_API_URL. */
+    baseUrl: string;
+    /** API key, e.g. process.env.APP_API_KEY. Sent as the 'x-api-key' header. */
+    apiKey?: string;
+    /** Custom fetch (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+export declare class LoopsClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly baseHeaders;
+    constructor(options: LoopsClientOptions);
+    private request;
+    /** Liveness probe */
+    healthCheck(init?: RequestInit): Promise<Foundation>;
+    /** Readiness probe (storage reachable + migrated) */
+    readyCheck(init?: RequestInit): Promise<Foundation>;
+    /** List loops */
+    listLoops(query?: {
+        "status"?: "active" | "paused" | "stopped" | "expired";
+        "limit"?: number;
+        "includeArchived"?: boolean;
+        "archived"?: boolean;
+    }, init?: RequestInit): Promise<LoopListResponse>;
+    /** Create a loop */
+    createLoop(body: CreateLoopInput, init?: RequestInit): Promise<LoopResponse>;
+    /** Get a loop by id */
+    getLoop(id: string, init?: RequestInit): Promise<LoopResponse>;
+    /** Delete a loop */
+    deleteLoop(id: string, init?: RequestInit): Promise<DeleteResponse>;
+    /** Update a loop (status / schedule fields) */
+    updateLoop(id: string, body: UpdateLoopInput, init?: RequestInit): Promise<LoopResponse>;
+    /** Archive a loop */
+    archiveLoop(id: string, init?: RequestInit): Promise<LoopResponse>;
+    /** Unarchive a loop */
+    unarchiveLoop(id: string, init?: RequestInit): Promise<LoopResponse>;
+    /** List run receipts */
+    listRunReceipts(query?: {
+        "loopId"?: string;
+        "repo"?: string;
+        "taskId"?: string;
+        "knowledgeId"?: string;
+        "status"?: string;
+        "limit"?: number;
+    }, init?: RequestInit): Promise<RunReceiptListResponse>;
+    /** Write a run receipt */
+    writeRunReceipt(body: WriteRunReceiptInput, init?: RequestInit): Promise<RunReceiptResponse>;
+    /** Get a run receipt by run id */
+    getRunReceipt(runId: string, init?: RequestInit): Promise<RunReceiptResponse>;
+    /** List runs */
+    listRuns(query?: {
+        "loopId"?: string;
+        "status"?: string;
+        "limit"?: number;
+    }, init?: RequestInit): Promise<RunListResponse>;
+    /** Get a run by id */
+    getRun(id: string, init?: RequestInit): Promise<RunResponse>;
+    /** Service version */
+    getVersion(init?: RequestInit): Promise<Foundation>;
+}