@hasna/loops 0.1.0

package/dist/sdk/index.js

@@ -0,0 +1,1059 @@
+// @bun
+// src/lib/store.ts
+import { Database } from "bun:sqlite";
+import { mkdirSync as mkdirSync2 } from "fs";
+import { dirname } from "path";
+
+// src/lib/ids.ts
+import { randomBytes } from "crypto";
+function genId(length = 12) {
+  return randomBytes(Math.ceil(length / 2)).toString("hex").slice(0, length);
+}
+function nowIso() {
+  return new Date().toISOString();
+}
+
+// src/lib/paths.ts
+import { mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function dataDir() {
+  return process.env.LOOPS_DATA_DIR || join(homedir(), ".hasna", "loops");
+}
+function ensureDataDir() {
+  const dir = dataDir();
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  return dir;
+}
+function dbPath() {
+  return join(dataDir(), "loops.db");
+}
+function pidFilePath() {
+  return join(dataDir(), "daemon.pid");
+}
+function daemonLogPath() {
+  return join(dataDir(), "daemon.log");
+}
+function systemdServicePath() {
+  return join(homedir(), ".config", "systemd", "user", "loops-daemon.service");
+}
+function launchdPlistPath() {
+  return join(homedir(), "Library", "LaunchAgents", "com.hasna.loops.daemon.plist");
+}
+
+// src/lib/schedule.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;
+}
+function parseCron(expr) {
+  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);
+  }
+  return {
+    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 !== "*"
+  };
+}
+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 latestCronSlot(first, now, expression) {
+  let current = first;
+  while (true) {
+    const next = nextCronRun(expression, current);
+    if (next.getTime() > now.getTime())
+      return current;
+    current = next;
+  }
+}
+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 slots = [];
+        let cursor = next;
+        while (cursor.getTime() <= now.getTime() && slots.length < loop.catchUpLimit) {
+          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 slots = [];
+        let cursor = next;
+        while (cursor.getTime() <= now.getTime() && slots.length < loop.catchUpLimit) {
+          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/store.ts
+function rowToLoop(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description ?? undefined,
+    status: row.status,
+    schedule: JSON.parse(row.schedule_json),
+    target: JSON.parse(row.target_json),
+    nextRunAt: row.next_run_at ?? undefined,
+    retryScheduledFor: row.retry_scheduled_for ?? undefined,
+    catchUp: row.catch_up,
+    catchUpLimit: row.catch_up_limit,
+    overlap: row.overlap,
+    maxAttempts: row.max_attempts,
+    retryDelayMs: row.retry_delay_ms,
+    leaseMs: row.lease_ms,
+    expiresAt: row.expires_at ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToRun(row) {
+  return {
+    id: row.id,
+    loopId: row.loop_id,
+    loopName: row.loop_name,
+    scheduledFor: row.scheduled_for,
+    attempt: row.attempt,
+    status: row.status,
+    startedAt: row.started_at ?? undefined,
+    finishedAt: row.finished_at ?? undefined,
+    claimedBy: row.claimed_by ?? undefined,
+    leaseExpiresAt: row.lease_expires_at ?? undefined,
+    pid: row.pid ?? undefined,
+    exitCode: row.exit_code ?? undefined,
+    durationMs: row.duration_ms ?? undefined,
+    stdout: row.stdout ?? undefined,
+    stderr: row.stderr ?? undefined,
+    error: row.error ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToLease(row) {
+  return {
+    id: row.id,
+    pid: row.pid,
+    hostname: row.hostname,
+    heartbeatAt: row.heartbeat_at,
+    expiresAt: row.expires_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+
+class Store {
+  db;
+  constructor(path) {
+    const file = path ?? dbPath();
+    if (file !== ":memory:")
+      mkdirSync2(dirname(file), { recursive: true, mode: 448 });
+    this.db = new Database(file);
+    this.db.exec("PRAGMA busy_timeout = 5000;");
+    this.db.exec("PRAGMA journal_mode = WAL;");
+    this.migrate();
+  }
+  migrate() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS loops (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL,
+        schedule_json TEXT NOT NULL,
+        target_json TEXT NOT NULL,
+        next_run_at TEXT,
+        retry_scheduled_for TEXT,
+        catch_up TEXT NOT NULL,
+        catch_up_limit INTEGER NOT NULL,
+        overlap TEXT NOT NULL,
+        max_attempts INTEGER NOT NULL,
+        retry_delay_ms INTEGER NOT NULL,
+        lease_ms INTEGER NOT NULL,
+        expires_at TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_loops_status_next ON loops(status, next_run_at);
+      CREATE INDEX IF NOT EXISTS idx_loops_name ON loops(name);
+
+      CREATE TABLE IF NOT EXISTS loop_runs (
+        id TEXT PRIMARY KEY,
+        loop_id TEXT NOT NULL,
+        loop_name TEXT NOT NULL,
+        scheduled_for TEXT NOT NULL,
+        attempt INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        started_at TEXT,
+        finished_at TEXT,
+        claimed_by TEXT,
+        lease_expires_at TEXT,
+        pid INTEGER,
+        exit_code INTEGER,
+        duration_ms INTEGER,
+        stdout TEXT,
+        stderr TEXT,
+        error TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(loop_id, scheduled_for)
+      );
+      CREATE INDEX IF NOT EXISTS idx_runs_loop ON loop_runs(loop_id, created_at);
+      CREATE INDEX IF NOT EXISTS idx_runs_status ON loop_runs(status);
+      CREATE INDEX IF NOT EXISTS idx_runs_scheduled ON loop_runs(scheduled_for);
+
+      CREATE TABLE IF NOT EXISTS daemon_lease (
+        id TEXT PRIMARY KEY,
+        pid INTEGER NOT NULL,
+        hostname TEXT NOT NULL,
+        heartbeat_at TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+    `);
+  }
+  createLoop(input, from = new Date) {
+    const now = nowIso();
+    const loop = {
+      id: genId(),
+      name: input.name,
+      description: input.description,
+      status: "active",
+      schedule: input.schedule,
+      target: input.target,
+      nextRunAt: initialNextRun(input.schedule, from),
+      catchUp: input.catchUp ?? "latest",
+      catchUpLimit: input.catchUpLimit ?? 50,
+      overlap: input.overlap ?? "skip",
+      maxAttempts: input.maxAttempts ?? 1,
+      retryDelayMs: input.retryDelayMs ?? 60000,
+      leaseMs: input.leaseMs ?? 30 * 60000,
+      expiresAt: input.expiresAt,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.db.query(`INSERT INTO loops (id, name, description, status, schedule_json, target_json, next_run_at, retry_scheduled_for,
+          catch_up, catch_up_limit, overlap, max_attempts, retry_delay_ms, lease_ms, expires_at, created_at, updated_at)
+         VALUES ($id, $name, $description, $status, $schedule, $target, $nextRun, NULL, $catchUp, $catchUpLimit,
+          $overlap, $maxAttempts, $retryDelay, $leaseMs, $expiresAt, $created, $updated)`).run({
+      $id: loop.id,
+      $name: loop.name,
+      $description: loop.description ?? null,
+      $status: loop.status,
+      $schedule: JSON.stringify(loop.schedule),
+      $target: JSON.stringify(loop.target),
+      $nextRun: loop.nextRunAt ?? null,
+      $catchUp: loop.catchUp,
+      $catchUpLimit: loop.catchUpLimit,
+      $overlap: loop.overlap,
+      $maxAttempts: loop.maxAttempts,
+      $retryDelay: loop.retryDelayMs,
+      $leaseMs: loop.leaseMs,
+      $expiresAt: loop.expiresAt ?? null,
+      $created: loop.createdAt,
+      $updated: loop.updatedAt
+    });
+    return loop;
+  }
+  getLoop(id) {
+    const row = this.db.query("SELECT * FROM loops WHERE id = ?").get(id);
+    return row ? rowToLoop(row) : undefined;
+  }
+  findLoopByName(name) {
+    const row = this.db.query("SELECT * FROM loops WHERE name = ? ORDER BY created_at DESC LIMIT 1").get(name);
+    return row ? rowToLoop(row) : undefined;
+  }
+  requireLoop(idOrName) {
+    return this.getLoop(idOrName) ?? this.findLoopByName(idOrName) ?? (() => {
+      throw new Error(`loop not found: ${idOrName}`);
+    })();
+  }
+  listLoops(opts = {}) {
+    const limit = opts.limit ?? 200;
+    const rows = opts.status ? this.db.query("SELECT * FROM loops WHERE status = ? ORDER BY next_run_at ASC LIMIT ?").all(opts.status, limit) : this.db.query("SELECT * FROM loops ORDER BY status ASC, next_run_at ASC LIMIT ?").all(limit);
+    return rows.map(rowToLoop);
+  }
+  dueLoops(now) {
+    const rows = this.db.query(`SELECT * FROM loops
+         WHERE status = 'active'
+           AND next_run_at IS NOT NULL
+           AND next_run_at <= ?
+         ORDER BY next_run_at ASC`).all(now.toISOString());
+    return rows.map(rowToLoop);
+  }
+  updateLoop(id, patch) {
+    const current = this.getLoop(id);
+    if (!current)
+      throw new Error(`loop not found: ${id}`);
+    const merged = { ...current, ...patch, updatedAt: nowIso() };
+    this.db.query(`UPDATE loops SET status=$status, next_run_at=$nextRun, retry_scheduled_for=$retrySlot,
+         expires_at=$expiresAt, updated_at=$updated WHERE id=$id`).run({
+      $id: id,
+      $status: merged.status,
+      $nextRun: merged.nextRunAt ?? null,
+      $retrySlot: merged.retryScheduledFor ?? null,
+      $expiresAt: merged.expiresAt ?? null,
+      $updated: merged.updatedAt
+    });
+    return merged;
+  }
+  deleteLoop(idOrName) {
+    const loop = this.requireLoop(idOrName);
+    const res = this.db.query("DELETE FROM loops WHERE id = ?").run(loop.id);
+    return res.changes > 0;
+  }
+  hasRunningRun(loopId) {
+    const row = this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE loop_id = ? AND status = 'running'").get(loopId);
+    return (row?.count ?? 0) > 0;
+  }
+  createSkippedRun(loop, scheduledFor, reason) {
+    const now = nowIso();
+    const run = {
+      id: genId(),
+      loopId: loop.id,
+      loopName: loop.name,
+      scheduledFor,
+      attempt: 1,
+      status: "skipped",
+      finishedAt: now,
+      error: reason,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.db.query(`INSERT OR IGNORE INTO loop_runs (id, loop_id, loop_name, scheduled_for, attempt, status, started_at, finished_at,
+          claimed_by, lease_expires_at, pid, exit_code, duration_ms, stdout, stderr, error, created_at, updated_at)
+         VALUES ($id, $loopId, $loopName, $scheduledFor, $attempt, $status, NULL, $finished, NULL, NULL, NULL, NULL, NULL,
+          NULL, NULL, $error, $created, $updated)`).run({
+      $id: run.id,
+      $loopId: run.loopId,
+      $loopName: run.loopName,
+      $scheduledFor: run.scheduledFor,
+      $attempt: run.attempt,
+      $status: run.status,
+      $finished: run.finishedAt ?? null,
+      $error: run.error ?? null,
+      $created: run.createdAt,
+      $updated: run.updatedAt
+    });
+    return this.getRunBySlot(loop.id, scheduledFor) ?? run;
+  }
+  getRun(id) {
+    const row = this.db.query("SELECT * FROM loop_runs WHERE id = ?").get(id);
+    return row ? rowToRun(row) : undefined;
+  }
+  getRunBySlot(loopId, scheduledFor) {
+    const row = this.db.query("SELECT * FROM loop_runs WHERE loop_id = ? AND scheduled_for = ?").get(loopId, scheduledFor);
+    return row ? rowToRun(row) : undefined;
+  }
+  claimRun(loop, scheduledFor, runnerId, now = new Date) {
+    const startedAt = now.toISOString();
+    const leaseExpiresAt = new Date(now.getTime() + loop.leaseMs).toISOString();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const existing = this.getRunBySlot(loop.id, scheduledFor);
+      if (existing) {
+        if (existing.status === "running") {
+          const res3 = this.db.query(`UPDATE loop_runs SET status='running', started_at=$started, finished_at=NULL,
+               claimed_by=$claimedBy, lease_expires_at=$lease, pid=NULL, exit_code=NULL,
+               duration_ms=NULL, stdout=NULL, stderr=NULL, error=NULL, updated_at=$updated
+               WHERE id=$id AND status='running' AND lease_expires_at <= $now`).run({
+            $id: existing.id,
+            $started: startedAt,
+            $claimedBy: runnerId,
+            $lease: leaseExpiresAt,
+            $updated: startedAt,
+            $now: startedAt
+          });
+          this.db.exec("COMMIT");
+          if (res3.changes !== 1)
+            return;
+          const run3 = this.getRun(existing.id);
+          return run3 ? { run: run3, loop } : undefined;
+        }
+        if (existing.status === "succeeded" || existing.status === "skipped") {
+          this.db.exec("COMMIT");
+          return;
+        }
+        const attempt = existing.attempt + 1;
+        const res2 = this.db.query(`UPDATE loop_runs SET attempt=$attempt, status='running', started_at=$started, finished_at=NULL,
+             claimed_by=$claimedBy, lease_expires_at=$lease, pid=NULL, exit_code=NULL,
+             duration_ms=NULL, stdout=NULL, stderr=NULL, error=NULL, updated_at=$updated
+             WHERE id=$id
+               AND status IN ('failed', 'timed_out', 'abandoned')
+               AND attempt < $maxAttempts`).run({
+          $id: existing.id,
+          $attempt: attempt,
+          $started: startedAt,
+          $claimedBy: runnerId,
+          $lease: leaseExpiresAt,
+          $updated: startedAt,
+          $maxAttempts: loop.maxAttempts
+        });
+        this.db.exec("COMMIT");
+        if (res2.changes !== 1)
+          return;
+        const run2 = this.getRun(existing.id);
+        return run2 ? { run: run2, loop } : undefined;
+      }
+      const id = genId();
+      const res = this.db.query(`INSERT OR IGNORE INTO loop_runs (id, loop_id, loop_name, scheduled_for, attempt, status, started_at, finished_at,
+            claimed_by, lease_expires_at, pid, exit_code, duration_ms, stdout, stderr, error, created_at, updated_at)
+           VALUES ($id, $loopId, $loopName, $scheduledFor, 1, 'running', $started, NULL, $claimedBy, $lease,
+            NULL, NULL, NULL, NULL, NULL, NULL, $created, $updated)`).run({
+        $id: id,
+        $loopId: loop.id,
+        $loopName: loop.name,
+        $scheduledFor: scheduledFor,
+        $started: startedAt,
+        $claimedBy: runnerId,
+        $lease: leaseExpiresAt,
+        $created: startedAt,
+        $updated: startedAt
+      });
+      this.db.exec("COMMIT");
+      if (res.changes !== 1)
+        return;
+      const run = this.getRun(id);
+      return run ? { run, loop } : undefined;
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
+  finalizeRun(id, patch) {
+    const finishedAt = patch.finishedAt ?? nowIso();
+    this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
+         duration_ms=$durationMs, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated WHERE id=$id`).run({
+      $id: id,
+      $status: patch.status,
+      $finished: finishedAt,
+      $pid: patch.pid ?? null,
+      $exitCode: patch.exitCode ?? null,
+      $durationMs: patch.durationMs ?? null,
+      $stdout: patch.stdout ?? null,
+      $stderr: patch.stderr ?? null,
+      $error: patch.error ?? null,
+      $updated: finishedAt
+    });
+    const run = this.getRun(id);
+    if (!run)
+      throw new Error(`run not found after finalize: ${id}`);
+    return run;
+  }
+  listRuns(opts = {}) {
+    const limit = opts.limit ?? 100;
+    let rows;
+    if (opts.loopId && opts.status) {
+      rows = this.db.query("SELECT * FROM loop_runs WHERE loop_id = ? AND status = ? ORDER BY created_at DESC LIMIT ?").all(opts.loopId, opts.status, limit);
+    } else if (opts.loopId) {
+      rows = this.db.query("SELECT * FROM loop_runs WHERE loop_id = ? ORDER BY created_at DESC LIMIT ?").all(opts.loopId, limit);
+    } else if (opts.status) {
+      rows = this.db.query("SELECT * FROM loop_runs WHERE status = ? ORDER BY created_at DESC LIMIT ?").all(opts.status, limit);
+    } else {
+      rows = this.db.query("SELECT * FROM loop_runs ORDER BY created_at DESC LIMIT ?").all(limit);
+    }
+    return rows.map(rowToRun);
+  }
+  recoverExpiredRunLeases(now = new Date) {
+    const rows = this.db.query("SELECT * FROM loop_runs WHERE status = 'running' AND lease_expires_at <= ?").all(now.toISOString());
+    const recovered = [];
+    for (const row of rows) {
+      this.db.query(`UPDATE loop_runs SET status='abandoned', finished_at=$finished, lease_expires_at=NULL,
+           error='run lease expired before completion', updated_at=$updated WHERE id=$id`).run({ $id: row.id, $finished: now.toISOString(), $updated: now.toISOString() });
+      const run = this.getRun(row.id);
+      if (run)
+        recovered.push(run);
+    }
+    return recovered;
+  }
+  expireLoops(now = new Date) {
+    const rows = this.db.query("SELECT * FROM loops WHERE status = 'active' AND expires_at IS NOT NULL AND expires_at <= ?").all(now.toISOString());
+    const expired = [];
+    for (const row of rows)
+      expired.push(this.updateLoop(row.id, { status: "expired", nextRunAt: undefined }));
+    return expired;
+  }
+  countLoops(status) {
+    const row = status ? this.db.query("SELECT COUNT(*) AS count FROM loops WHERE status = ?").get(status) : this.db.query("SELECT COUNT(*) AS count FROM loops").get();
+    return row?.count ?? 0;
+  }
+  countRuns(status) {
+    const row = status ? this.db.query("SELECT COUNT(*) AS count FROM loop_runs WHERE status = ?").get(status) : this.db.query("SELECT COUNT(*) AS count FROM loop_runs").get();
+    return row?.count ?? 0;
+  }
+  acquireDaemonLease(input) {
+    const now = input.now ?? new Date;
+    const expiresAt = new Date(now.getTime() + input.ttlMs).toISOString();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const existing = this.db.query("SELECT * FROM daemon_lease LIMIT 1").get();
+      if (existing && existing.expires_at > now.toISOString() && existing.id !== input.id) {
+        this.db.exec("COMMIT");
+        return;
+      }
+      this.db.query("DELETE FROM daemon_lease").run();
+      this.db.query(`INSERT INTO daemon_lease (id, pid, hostname, heartbeat_at, expires_at, created_at, updated_at)
+           VALUES ($id, $pid, $hostname, $heartbeat, $expires, $created, $updated)`).run({
+        $id: input.id,
+        $pid: input.pid,
+        $hostname: input.hostname,
+        $heartbeat: now.toISOString(),
+        $expires: expiresAt,
+        $created: now.toISOString(),
+        $updated: now.toISOString()
+      });
+      this.db.exec("COMMIT");
+      return this.getDaemonLease();
+    } catch (error) {
+      try {
+        this.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  }
+  heartbeatDaemonLease(id, ttlMs, now = new Date) {
+    const expiresAt = new Date(now.getTime() + ttlMs).toISOString();
+    const res = this.db.query(`UPDATE daemon_lease SET heartbeat_at=$heartbeat, expires_at=$expires, updated_at=$updated WHERE id=$id`).run({ $id: id, $heartbeat: now.toISOString(), $expires: expiresAt, $updated: now.toISOString() });
+    if (res.changes !== 1)
+      return;
+    return this.getDaemonLease();
+  }
+  releaseDaemonLease(id) {
+    this.db.query("DELETE FROM daemon_lease WHERE id = ?").run(id);
+  }
+  getDaemonLease() {
+    const row = this.db.query("SELECT * FROM daemon_lease LIMIT 1").get();
+    return row ? rowToLease(row) : undefined;
+  }
+  close() {
+    this.db.close();
+  }
+}
+
+// src/lib/executor.ts
+import { spawn } from "child_process";
+import { once } from "events";
+var DEFAULT_TIMEOUT_MS = 30 * 60000;
+var DEFAULT_MAX_OUTPUT_BYTES = 256 * 1024;
+function appendBounded(current, chunk, maxBytes) {
+  const next = current + chunk.toString("utf8");
+  if (Buffer.byteLength(next, "utf8") <= maxBytes)
+    return next;
+  const overflow = Buffer.byteLength(next, "utf8") - maxBytes;
+  return `[truncated ${overflow} bytes]
+${next.slice(-maxBytes)}`;
+}
+function killProcessGroup(pid) {
+  try {
+    process.kill(-pid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {}
+  }
+  setTimeout(() => {
+    try {
+      process.kill(-pid, "SIGKILL");
+    } catch {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {}
+    }
+  }, 2000).unref();
+}
+function providerCommand(provider) {
+  switch (provider) {
+    case "claude":
+      return "claude";
+    case "cursor":
+      return "cursor-agent";
+    case "codewith":
+      return "codewith";
+    case "aicopilot":
+      return "aicopilot";
+    case "opencode":
+      return "opencode";
+  }
+}
+function agentArgs(target) {
+  const isolation = target.configIsolation ?? "safe";
+  const args = [];
+  switch (target.provider) {
+    case "claude":
+      if (isolation === "safe")
+        args.push("--safe-mode", "--setting-sources", "local", "--no-session-persistence");
+      args.push("-p", "--output-format", "json");
+      if (target.model)
+        args.push("--model", target.model);
+      if (target.agent)
+        args.push("--agent", target.agent);
+      args.push(...target.extraArgs ?? [], target.prompt);
+      return args;
+    case "cursor":
+      args.push("-p");
+      if (target.model)
+        args.push("--model", target.model);
+      if (target.agent)
+        args.push("--agent", target.agent);
+      args.push(...target.extraArgs ?? [], target.prompt);
+      return args;
+    case "codewith":
+      args.push("exec", "--json", "--ephemeral", "--ask-for-approval", "never", "--sandbox", "workspace-write");
+      if (isolation === "safe")
+        args.push("--ignore-rules");
+      if (target.cwd)
+        args.push("--cd", target.cwd);
+      if (target.model)
+        args.push("--model", target.model);
+      if (target.agent)
+        args.push("--agent", target.agent);
+      args.push(...target.extraArgs ?? [], target.prompt);
+      return args;
+    case "aicopilot":
+      args.push("run", "--format", "json");
+      if (isolation === "safe")
+        args.push("--pure");
+      if (target.cwd)
+        args.push("--dir", target.cwd);
+      if (target.model)
+        args.push("--model", target.model);
+      if (target.agent)
+        args.push("--agent", target.agent);
+      args.push(...target.extraArgs ?? [], target.prompt);
+      return args;
+    case "opencode":
+      args.push("run", "--format", "json");
+      if (isolation === "safe")
+        args.push("--pure");
+      if (target.cwd)
+        args.push("--dir", target.cwd);
+      if (target.model)
+        args.push("--model", target.model);
+      if (target.agent)
+        args.push("--agent", target.agent);
+      args.push(...target.extraArgs ?? [], target.prompt);
+      return args;
+  }
+}
+function commandSpec(loop) {
+  const target = loop.target;
+  if (target.type === "command") {
+    const commandTarget = target;
+    return {
+      command: commandTarget.command,
+      args: commandTarget.args ?? [],
+      cwd: commandTarget.cwd,
+      shell: commandTarget.shell,
+      env: commandTarget.env,
+      timeoutMs: commandTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    };
+  }
+  const agentTarget = target;
+  return {
+    command: providerCommand(agentTarget.provider),
+    args: agentArgs(agentTarget),
+    cwd: agentTarget.cwd,
+    timeoutMs: agentTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  };
+}
+async function executeLoop(loop, run, opts = {}) {
+  const spec = commandSpec(loop);
+  const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const startedAt = nowIso();
+  let stdout = "";
+  let stderr = "";
+  let timedOut = false;
+  let exitCode;
+  let error;
+  const env = {
+    ...opts.env ?? process.env,
+    ...spec.env ?? {},
+    LOOPS_LOOP_ID: loop.id,
+    LOOPS_LOOP_NAME: loop.name,
+    LOOPS_RUN_ID: run.id,
+    LOOPS_SCHEDULED_FOR: run.scheduledFor
+  };
+  const child = spawn(spec.command, spec.args, {
+    cwd: spec.cwd,
+    env,
+    shell: spec.shell ?? false,
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  child.stdout.on("data", (chunk) => {
+    stdout = appendBounded(stdout, chunk, maxOutputBytes);
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr = appendBounded(stderr, chunk, maxOutputBytes);
+  });
+  const timer = setTimeout(() => {
+    timedOut = true;
+    if (child.pid)
+      killProcessGroup(child.pid);
+  }, spec.timeoutMs);
+  timer.unref();
+  try {
+    const [code, signal] = await once(child, "exit");
+    if (typeof code === "number")
+      exitCode = code;
+    if (signal)
+      error = `terminated by ${signal}`;
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err);
+  } finally {
+    clearTimeout(timer);
+  }
+  const finishedAt = nowIso();
+  const durationMs = new Date(finishedAt).getTime() - new Date(startedAt).getTime();
+  if (timedOut) {
+    return {
+      status: "timed_out",
+      exitCode,
+      stdout,
+      stderr,
+      error: `timed out after ${spec.timeoutMs}ms`,
+      pid: child.pid,
+      startedAt,
+      finishedAt,
+      durationMs
+    };
+  }
+  if (error || exitCode !== 0) {
+    return {
+      status: "failed",
+      exitCode,
+      stdout,
+      stderr,
+      error: error ?? `process exited with code ${exitCode ?? "unknown"}`,
+      pid: child.pid,
+      startedAt,
+      finishedAt,
+      durationMs
+    };
+  }
+  return {
+    status: "succeeded",
+    exitCode,
+    stdout,
+    stderr,
+    pid: child.pid,
+    startedAt,
+    finishedAt,
+    durationMs
+  };
+}
+
+// src/lib/scheduler.ts
+function nextAfterRetry(loop, now) {
+  return new Date(now.getTime() + loop.retryDelayMs).toISOString();
+}
+function advanceLoop(store, loop, run, finishedAt, succeeded) {
+  const shouldRetry = !succeeded && run.attempt < loop.maxAttempts;
+  if (shouldRetry) {
+    store.updateLoop(loop.id, {
+      status: "active",
+      nextRunAt: nextAfterRetry(loop, finishedAt),
+      retryScheduledFor: run.scheduledFor
+    });
+    return;
+  }
+  const nextRunAt = computeNextAfter(loop.schedule, new Date(run.scheduledFor), finishedAt);
+  store.updateLoop(loop.id, {
+    status: nextRunAt ? "active" : "stopped",
+    nextRunAt,
+    retryScheduledFor: undefined
+  });
+}
+async function runSlot(deps, loop, scheduledFor) {
+  const now = deps.now?.() ?? new Date;
+  if (loop.overlap === "skip" && deps.store.hasRunningRun(loop.id)) {
+    const skipped = deps.store.createSkippedRun(loop, scheduledFor, "previous run still active");
+    advanceLoop(deps.store, loop, skipped, now, true);
+    deps.onRun?.(skipped);
+    return skipped;
+  }
+  const claim = deps.store.claimRun(loop, scheduledFor, deps.runnerId, now);
+  if (!claim)
+    return;
+  deps.onRun?.(claim.run);
+  try {
+    const result = await (deps.execute ?? executeLoop)(claim.loop, claim.run);
+    const finalRun = deps.store.finalizeRun(claim.run.id, {
+      status: result.status,
+      finishedAt: result.finishedAt,
+      durationMs: result.durationMs,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode,
+      error: result.error,
+      pid: result.pid
+    });
+    advanceLoop(deps.store, claim.loop, finalRun, new Date(result.finishedAt), result.status === "succeeded");
+    deps.onRun?.(finalRun);
+    return finalRun;
+  } catch (err) {
+    deps.onError?.(claim.loop, err);
+    const finishedAt = new Date;
+    const finalRun = deps.store.finalizeRun(claim.run.id, {
+      status: "failed",
+      finishedAt: finishedAt.toISOString(),
+      durationMs: finishedAt.getTime() - new Date(claim.run.startedAt ?? claim.run.createdAt).getTime(),
+      stdout: "",
+      stderr: "",
+      error: err instanceof Error ? err.message : String(err)
+    });
+    advanceLoop(deps.store, claim.loop, finalRun, finishedAt, false);
+    deps.onRun?.(finalRun);
+    return finalRun;
+  }
+}
+async function tick(deps) {
+  const now = deps.now?.() ?? new Date;
+  const recovered = deps.store.recoverExpiredRunLeases(now);
+  for (const run of recovered) {
+    const loop = deps.store.getLoop(run.loopId);
+    if (loop)
+      advanceLoop(deps.store, loop, run, new Date(run.finishedAt ?? now), false);
+  }
+  const expired = deps.store.expireLoops(now);
+  const claimed = [];
+  const completed = [];
+  const skipped = [];
+  for (const loop of deps.store.dueLoops(now)) {
+    const plan = dueSlots(loop, now);
+    for (const slot of plan.slots) {
+      const run = await runSlot(deps, loop, slot);
+      if (!run)
+        continue;
+      if (run.status === "running")
+        claimed.push(run);
+      else if (run.status === "skipped")
+        skipped.push(run);
+      else
+        completed.push(run);
+    }
+  }
+  return { claimed, completed, skipped, recovered, expired };
+}
+
+// src/sdk/index.ts
+class LoopsClient {
+  store;
+  ownStore;
+  runnerId;
+  constructor(opts = {}) {
+    this.store = opts.store ?? new Store;
+    this.ownStore = !opts.store;
+    this.runnerId = opts.runnerId ?? `sdk:${process.pid}`;
+  }
+  create(input) {
+    return this.store.createLoop(input);
+  }
+  list() {
+    return this.store.listLoops();
+  }
+  get(idOrName) {
+    return this.store.requireLoop(idOrName);
+  }
+  pause(idOrName) {
+    const loop = this.get(idOrName);
+    return this.store.updateLoop(loop.id, { status: "paused" });
+  }
+  resume(idOrName) {
+    const loop = this.get(idOrName);
+    return this.store.updateLoop(loop.id, { status: "active" });
+  }
+  stop(idOrName) {
+    const loop = this.get(idOrName);
+    return this.store.updateLoop(loop.id, { status: "stopped", nextRunAt: undefined });
+  }
+  delete(idOrName) {
+    return this.store.deleteLoop(idOrName);
+  }
+  runs(loopId) {
+    return this.store.listRuns({ loopId });
+  }
+  async tick() {
+    return tick({ store: this.store, runnerId: this.runnerId });
+  }
+  async runNow(idOrName) {
+    const loop = this.get(idOrName);
+    const scheduledFor = new Date().toISOString();
+    const claim = this.store.claimRun(loop, scheduledFor, this.runnerId);
+    if (!claim)
+      throw new Error(`could not claim manual run for ${idOrName}`);
+    const result = await executeLoop(loop, claim.run);
+    return this.store.finalizeRun(claim.run.id, {
+      status: result.status,
+      finishedAt: result.finishedAt,
+      durationMs: result.durationMs,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode,
+      error: result.error,
+      pid: result.pid
+    });
+  }
+  close() {
+    if (this.ownStore)
+      this.store.close();
+  }
+}
+function loops(opts = {}) {
+  return new LoopsClient(opts);
+}
+export {
+  loops,
+  LoopsClient
+};