@hasna/loops 0.3.37 → 0.3.39

package/dist/sdk/index.js

@@ -1,8 +1,9 @@
 // @bun
 // src/lib/store.ts
 import { Database } from "bun:sqlite";
-import { mkdirSync as mkdirSync2 } from "fs";
-import { dirname } from "path";
+import { mkdirSync as mkdirSync3, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join as join3 } from "path";
 
 // src/lib/ids.ts
 import { randomBytes } from "crypto";
@@ -363,6 +364,8 @@ function validateTarget(value, label) {
   assertObject(value, label);
   if (value.type === "command") {
     assertString(value.command, `${label}.command`);
+    optionalPositiveInteger(value.timeoutMs, `${label}.timeoutMs`);
+    optionalPositiveInteger(value.idleTimeoutMs, `${label}.idleTimeoutMs`);
     if (value.shell !== true && /\s/.test(value.command.trim())) {
       throw new Error(`${label}.command must be an executable without spaces when shell is false; put flags in args or set shell true`);
     }
@@ -374,6 +377,8 @@ function validateTarget(value, label) {
     const providers = ["claude", "cursor", "codewith", "aicopilot", "opencode", "codex"];
     if (!providers.includes(value.provider))
       throw new Error(`${label}.provider must be one of ${providers.join(", ")}`);
+    optionalPositiveInteger(value.timeoutMs, `${label}.timeoutMs`);
+    optionalPositiveInteger(value.idleTimeoutMs, `${label}.idleTimeoutMs`);
     if (value.authProfile !== undefined) {
       assertString(value.authProfile, `${label}.authProfile`);
       if (value.provider !== "codewith")
@@ -528,6 +533,52 @@ function workflowBodyFromJson(value, fallbackName) {
   });
 }
 
+// src/lib/run-artifacts.ts
+import { createHash } from "crypto";
+import { mkdirSync as mkdirSync2, writeFileSync } from "fs";
+import { basename, join as join2 } from "path";
+function shortHash(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+function safeRunPathSlug(value, fallback) {
+  const raw = value?.trim() || fallback;
+  const slug = raw.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 72);
+  return slug || fallback;
+}
+function workflowRunSubjectKey(kind, rawSubjectRef) {
+  const raw = rawSubjectRef?.trim() || "subject";
+  const kindSlug = safeRunPathSlug(kind, "subject").slice(0, 24);
+  const subjectSlug = safeRunPathSlug(raw, "subject").slice(0, 48);
+  return `${kindSlug}-${subjectSlug}-${shortHash(`${kindSlug}
+${raw}`)}`;
+}
+function workflowRunProjectSlug(projectKey) {
+  if (!projectKey?.trim())
+    return "global";
+  return safeRunPathSlug(projectKey.startsWith("/") ? basename(projectKey) : projectKey, "project");
+}
+function writeWorkflowRunManifest(args) {
+  const projectSlug = workflowRunProjectSlug(args.projectKey);
+  const subjectKey = workflowRunSubjectKey(args.subjectKind, args.rawSubjectRef);
+  const dir = join2(args.loopsDataDir, "runs", projectSlug, subjectKey, args.workflowRunId);
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  const manifestPath = join2(dir, "manifest.json");
+  writeFileSync(manifestPath, JSON.stringify({
+    version: 1,
+    workflowRunId: args.workflowRunId,
+    workflowId: args.workflowId,
+    workflowName: args.workflowName,
+    invocationId: args.invocationId,
+    workItemId: args.workItemId,
+    projectSlug,
+    subjectKey,
+    requiredReading: [],
+    createdAt: new Date().toISOString(),
+    ...args.payload
+  }, null, 2), { mode: 384 });
+  return manifestPath;
+}
+
 // src/lib/store.ts
 function rowToLoop(row) {
   return {
@@ -597,8 +648,11 @@ function rowToWorkflowRun(row) {
     workflowName: row.workflow_name,
     loopId: row.loop_id ?? undefined,
     loopRunId: row.loop_run_id ?? undefined,
+    invocationId: row.invocation_id ?? undefined,
+    workItemId: row.work_item_id ?? undefined,
     scheduledFor: row.scheduled_for ?? undefined,
     idempotencyKey: row.idempotency_key ?? undefined,
+    manifestPath: row.manifest_path ?? undefined,
     status: row.status,
     startedAt: row.started_at ?? undefined,
     finishedAt: row.finished_at ?? undefined,
@@ -609,6 +663,44 @@ function rowToWorkflowRun(row) {
     updatedAt: row.updated_at
   };
 }
+function rowToWorkflowInvocation(row) {
+  return {
+    id: row.id,
+    workflowId: row.workflow_id ?? undefined,
+    templateId: row.template_id ?? undefined,
+    sourceRef: JSON.parse(row.source_json),
+    subjectRef: JSON.parse(row.subject_json),
+    intent: row.intent,
+    scope: row.scope_json ? JSON.parse(row.scope_json) : undefined,
+    outputPolicy: row.output_policy_json ? JSON.parse(row.output_policy_json) : undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function rowToWorkflowWorkItem(row) {
+  return {
+    id: row.id,
+    routeKey: row.route_key,
+    idempotencyKey: row.idempotency_key,
+    invocationId: row.invocation_id,
+    sourceType: row.source_type,
+    sourceRef: row.source_ref,
+    subjectRef: row.subject_ref,
+    projectKey: row.project_key ?? undefined,
+    projectGroup: row.project_group ?? undefined,
+    priority: row.priority,
+    status: row.status,
+    attempts: row.attempts,
+    nextAttemptAt: row.next_attempt_at ?? undefined,
+    leaseExpiresAt: row.lease_expires_at ?? undefined,
+    workflowId: row.workflow_id ?? undefined,
+    loopId: row.loop_id ?? undefined,
+    workflowRunId: row.workflow_run_id ?? undefined,
+    lastReason: row.last_reason ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
 function rowToWorkflowStepRun(row) {
   return {
     id: row.id,
@@ -722,13 +814,23 @@ function rowToLease(row) {
     updatedAt: row.updated_at
   };
 }
+function workItemStatusForLoopRun(status, attempt, maxAttempts) {
+  if (status === "succeeded")
+    return "succeeded";
+  if (["failed", "timed_out", "abandoned"].includes(status)) {
+    return maxAttempts !== undefined && attempt < maxAttempts ? "admitted" : "failed";
+  }
+  return;
+}
 
 class Store {
   db;
+  rootDir;
   constructor(path) {
     const file = path ?? dbPath();
     if (file !== ":memory:")
-      mkdirSync2(dirname(file), { recursive: true, mode: 448 });
+      mkdirSync3(dirname(file), { recursive: true, mode: 448 });
+    this.rootDir = file === ":memory:" ? mkdtempSync(join3(tmpdir(), "open-loops-store-")) : dirname(file);
     this.db = new Database(file);
     this.db.exec("PRAGMA busy_timeout = 5000;");
     this.db.exec("PRAGMA journal_mode = WAL;");
@@ -823,8 +925,11 @@ class Store {
         workflow_name TEXT NOT NULL,
         loop_id TEXT REFERENCES loops(id) ON DELETE SET NULL,
         loop_run_id TEXT REFERENCES loop_runs(id) ON DELETE SET NULL,
+        invocation_id TEXT,
+        work_item_id TEXT,
         scheduled_for TEXT,
         idempotency_key TEXT,
+        manifest_path TEXT,
         status TEXT NOT NULL,
         started_at TEXT,
         finished_at TEXT,
@@ -839,8 +944,63 @@ class Store {
         WHERE idempotency_key IS NOT NULL;
       CREATE INDEX IF NOT EXISTS idx_workflow_runs_workflow_created ON workflow_runs(workflow_id, created_at DESC);
       CREATE INDEX IF NOT EXISTS idx_workflow_runs_loop_run ON workflow_runs(loop_run_id);
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_invocation ON workflow_runs(invocation_id);
+      CREATE INDEX IF NOT EXISTS idx_workflow_runs_work_item ON workflow_runs(work_item_id);
       CREATE INDEX IF NOT EXISTS idx_workflow_runs_status ON workflow_runs(status);
 
+      CREATE TABLE IF NOT EXISTS workflow_invocations (
+        id TEXT PRIMARY KEY,
+        workflow_id TEXT,
+        template_id TEXT,
+        source_kind TEXT NOT NULL,
+        source_id TEXT,
+        source_dedupe_key TEXT,
+        source_json TEXT NOT NULL,
+        subject_kind TEXT NOT NULL,
+        subject_id TEXT,
+        subject_path TEXT,
+        subject_url TEXT,
+        subject_json TEXT NOT NULL,
+        intent TEXT NOT NULL,
+        scope_json TEXT,
+        output_policy_json TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_invocations_source ON workflow_invocations(source_kind, source_id);
+      CREATE INDEX IF NOT EXISTS idx_workflow_invocations_subject ON workflow_invocations(subject_kind, subject_id, subject_path);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_workflow_invocations_dedupe
+        ON workflow_invocations(source_kind, source_dedupe_key)
+        WHERE source_dedupe_key IS NOT NULL;
+
+      CREATE TABLE IF NOT EXISTS workflow_work_items (
+        id TEXT PRIMARY KEY,
+        route_key TEXT NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        invocation_id TEXT NOT NULL REFERENCES workflow_invocations(id) ON DELETE CASCADE,
+        source_type TEXT NOT NULL,
+        source_ref TEXT NOT NULL,
+        subject_ref TEXT NOT NULL,
+        project_key TEXT,
+        project_group TEXT,
+        priority INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        attempts INTEGER NOT NULL,
+        next_attempt_at TEXT,
+        lease_expires_at TEXT,
+        workflow_id TEXT REFERENCES workflow_specs(id) ON DELETE SET NULL,
+        loop_id TEXT REFERENCES loops(id) ON DELETE SET NULL,
+        workflow_run_id TEXT REFERENCES workflow_runs(id) ON DELETE SET NULL,
+        last_reason TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(route_key, idempotency_key)
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_work_items_status_next ON workflow_work_items(status, next_attempt_at, priority DESC, created_at ASC);
+      CREATE INDEX IF NOT EXISTS idx_workflow_work_items_project ON workflow_work_items(project_key, status);
+      CREATE INDEX IF NOT EXISTS idx_workflow_work_items_group ON workflow_work_items(project_group, status);
+      CREATE INDEX IF NOT EXISTS idx_workflow_work_items_invocation ON workflow_work_items(invocation_id);
+
       CREATE TABLE IF NOT EXISTS workflow_step_runs (
         id TEXT PRIMARY KEY,
         workflow_run_id TEXT NOT NULL REFERENCES workflow_runs(id) ON DELETE CASCADE,
@@ -953,12 +1113,16 @@ class Store {
     this.addColumnIfMissing("loop_runs", "goal_run_id", "TEXT");
     this.addColumnIfMissing("workflow_specs", "goal_json", "TEXT");
     this.addColumnIfMissing("workflow_runs", "goal_run_id", "TEXT");
+    this.addColumnIfMissing("workflow_runs", "invocation_id", "TEXT");
+    this.addColumnIfMissing("workflow_runs", "work_item_id", "TEXT");
+    this.addColumnIfMissing("workflow_runs", "manifest_path", "TEXT");
     this.addColumnIfMissing("workflow_step_runs", "pid", "INTEGER");
     this.addColumnIfMissing("workflow_step_runs", "goal_run_id", "TEXT");
     this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0001_initial_and_workflows", nowIso());
     this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0002_loop_machines", nowIso());
     this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0003_goals", nowIso());
     this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0004_loop_archive_metadata", nowIso());
+    this.db.query("INSERT OR IGNORE INTO schema_migrations (id, applied_at) VALUES (?, ?)").run("0005_workflow_invocations_and_admission", nowIso());
   }
   addColumnIfMissing(table, column, definition) {
     const columns = this.db.query(`PRAGMA table_info(${table})`).all();
@@ -1081,6 +1245,10 @@ class Store {
       $daemonLeaseId: opts.daemonLeaseId ?? null,
       $now: updated
     });
+    if (patch.status && patch.status !== "active") {
+      const status = patch.status === "paused" ? "deferred" : "cancelled";
+      this.setWorkflowWorkItemsForLoop(id, status, `loop ${patch.status}`, updated);
+    }
     const after = this.getLoop(id);
     if (!after)
       throw new Error(`loop not found after update: ${id}`);
@@ -1125,6 +1293,7 @@ class Store {
       $archivedFromStatus: loop.status,
       $updated: updated
     });
+    this.setWorkflowWorkItemsForLoop(loop.id, "deferred", "loop archived", updated);
     const archived = this.getLoop(loop.id);
     if (!archived)
       throw new Error(`loop not found after archive: ${loop.id}`);
@@ -1150,6 +1319,7 @@ class Store {
   }
   deleteLoop(idOrName) {
     const loop = this.requireLoop(idOrName);
+    this.setWorkflowWorkItemsForLoop(loop.id, "cancelled", "loop deleted", nowIso());
     const res = this.db.query("DELETE FROM loops WHERE id = ?").run(loop.id);
     return res.changes > 0;
   }
@@ -1208,6 +1378,185 @@ class Store {
       throw new Error(`workflow not found after archive: ${workflow.id}`);
     return archived;
   }
+  createWorkflowInvocation(input) {
+    const now = nowIso();
+    const sourceDedupeKey = input.sourceRef.dedupeKey ?? undefined;
+    if (sourceDedupeKey) {
+      const existing = this.db.query("SELECT * FROM workflow_invocations WHERE source_kind = ? AND source_dedupe_key = ? LIMIT 1").get(input.sourceRef.kind, sourceDedupeKey);
+      if (existing)
+        return rowToWorkflowInvocation(existing);
+    }
+    const id = input.id ?? genId();
+    this.db.query(`INSERT INTO workflow_invocations (id, workflow_id, template_id, source_kind, source_id, source_dedupe_key,
+          source_json, subject_kind, subject_id, subject_path, subject_url, subject_json, intent, scope_json,
+          output_policy_json, created_at, updated_at)
+         VALUES ($id, $workflowId, $templateId, $sourceKind, $sourceId, $sourceDedupeKey, $sourceJson,
+          $subjectKind, $subjectId, $subjectPath, $subjectUrl, $subjectJson, $intent, $scopeJson,
+          $outputPolicyJson, $created, $updated)`).run({
+      $id: id,
+      $workflowId: input.workflowId ?? null,
+      $templateId: input.templateId ?? null,
+      $sourceKind: input.sourceRef.kind,
+      $sourceId: input.sourceRef.id ?? null,
+      $sourceDedupeKey: sourceDedupeKey ?? null,
+      $sourceJson: JSON.stringify(input.sourceRef),
+      $subjectKind: input.subjectRef.kind,
+      $subjectId: input.subjectRef.id ?? null,
+      $subjectPath: input.subjectRef.path ?? null,
+      $subjectUrl: input.subjectRef.url ?? null,
+      $subjectJson: JSON.stringify(input.subjectRef),
+      $intent: input.intent,
+      $scopeJson: input.scope ? JSON.stringify(input.scope) : null,
+      $outputPolicyJson: input.outputPolicy ? JSON.stringify(input.outputPolicy) : null,
+      $created: now,
+      $updated: now
+    });
+    const row = this.db.query("SELECT * FROM workflow_invocations WHERE id = ?").get(id);
+    if (!row)
+      throw new Error(`workflow invocation not found after create: ${id}`);
+    return rowToWorkflowInvocation(row);
+  }
+  getWorkflowInvocation(id) {
+    const row = this.db.query("SELECT * FROM workflow_invocations WHERE id = ?").get(id);
+    return row ? rowToWorkflowInvocation(row) : undefined;
+  }
+  listWorkflowInvocations(opts = {}) {
+    const rows = this.db.query("SELECT * FROM workflow_invocations ORDER BY created_at DESC LIMIT ?").all(opts.limit ?? 100);
+    return rows.map(rowToWorkflowInvocation);
+  }
+  upsertWorkflowWorkItem(input) {
+    const now = nowIso();
+    const id = genId();
+    const status = input.status ?? "queued";
+    this.db.query(`INSERT INTO workflow_work_items (id, route_key, idempotency_key, invocation_id, source_type, source_ref,
+          subject_ref, project_key, project_group, priority, status, attempts, next_attempt_at, lease_expires_at,
+          workflow_id, loop_id, workflow_run_id, last_reason, created_at, updated_at)
+         VALUES ($id, $routeKey, $idempotencyKey, $invocationId, $sourceType, $sourceRef, $subjectRef,
+          $projectKey, $projectGroup, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
+          $lastReason, $created, $updated)
+         ON CONFLICT(route_key, idempotency_key) DO UPDATE SET
+          invocation_id=excluded.invocation_id,
+          source_type=excluded.source_type,
+          source_ref=excluded.source_ref,
+          subject_ref=excluded.subject_ref,
+          project_key=excluded.project_key,
+          project_group=excluded.project_group,
+          priority=excluded.priority,
+          status=CASE
+            WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running')
+              THEN workflow_work_items.status
+            ELSE excluded.status
+          END,
+          workflow_id=CASE
+            WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running') THEN workflow_work_items.workflow_id
+            ELSE NULL
+          END,
+          loop_id=CASE
+            WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running') THEN workflow_work_items.loop_id
+            ELSE NULL
+          END,
+          workflow_run_id=CASE
+            WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running') THEN workflow_work_items.workflow_run_id
+            ELSE NULL
+          END,
+          lease_expires_at=CASE
+            WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running') THEN workflow_work_items.lease_expires_at
+            ELSE NULL
+          END,
+          next_attempt_at=excluded.next_attempt_at,
+          last_reason=COALESCE(excluded.last_reason, workflow_work_items.last_reason),
+          updated_at=excluded.updated_at`).run({
+      $id: id,
+      $routeKey: input.routeKey,
+      $idempotencyKey: input.idempotencyKey,
+      $invocationId: input.invocationId,
+      $sourceType: input.sourceType,
+      $sourceRef: input.sourceRef,
+      $subjectRef: input.subjectRef,
+      $projectKey: input.projectKey ?? null,
+      $projectGroup: input.projectGroup ?? null,
+      $priority: input.priority ?? 0,
+      $status: status,
+      $nextAttemptAt: input.nextAttemptAt ?? null,
+      $lastReason: input.lastReason ?? null,
+      $created: now,
+      $updated: now
+    });
+    const row = this.db.query("SELECT * FROM workflow_work_items WHERE route_key = ? AND idempotency_key = ? LIMIT 1").get(input.routeKey, input.idempotencyKey);
+    if (!row)
+      throw new Error(`workflow work item not found after upsert: ${input.routeKey}/${input.idempotencyKey}`);
+    return rowToWorkflowWorkItem(row);
+  }
+  getWorkflowWorkItem(id) {
+    const row = this.db.query("SELECT * FROM workflow_work_items WHERE id = ?").get(id);
+    return row ? rowToWorkflowWorkItem(row) : undefined;
+  }
+  findWorkflowWorkItem(routeKey, idempotencyKey) {
+    const row = this.db.query("SELECT * FROM workflow_work_items WHERE route_key = ? AND idempotency_key = ? LIMIT 1").get(routeKey, idempotencyKey);
+    return row ? rowToWorkflowWorkItem(row) : undefined;
+  }
+  listWorkflowWorkItems(opts = {}) {
+    const limit = opts.limit ?? 100;
+    let rows;
+    if (opts.status && opts.routeKey) {
+      rows = this.db.query("SELECT * FROM workflow_work_items WHERE route_key = ? AND status = ? ORDER BY priority DESC, created_at ASC LIMIT ?").all(opts.routeKey, opts.status, limit);
+    } else if (opts.status) {
+      rows = this.db.query("SELECT * FROM workflow_work_items WHERE status = ? ORDER BY priority DESC, created_at ASC LIMIT ?").all(opts.status, limit);
+    } else if (opts.routeKey) {
+      rows = this.db.query("SELECT * FROM workflow_work_items WHERE route_key = ? ORDER BY created_at DESC LIMIT ?").all(opts.routeKey, limit);
+    } else {
+      rows = this.db.query("SELECT * FROM workflow_work_items ORDER BY created_at DESC LIMIT ?").all(limit);
+    }
+    return rows.map(rowToWorkflowWorkItem);
+  }
+  countActiveWorkflowWorkItems(args = {}) {
+    const active = ["admitted", "running"];
+    const placeholders = active.map(() => "?").join(",");
+    const global = this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders})`).get(...active)?.count ?? 0;
+    const project = args.projectKey ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_key = ?`).get(...active, args.projectKey)?.count ?? 0 : 0;
+    const projectGroup = args.projectGroup ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_group = ?`).get(...active, args.projectGroup)?.count ?? 0 : undefined;
+    return { global, project, ...projectGroup !== undefined ? { projectGroup } : {} };
+  }
+  admitWorkflowWorkItem(id, patch) {
+    const now = nowIso();
+    const res = this.db.query(`UPDATE workflow_work_items
+         SET status='admitted', attempts=attempts + 1, workflow_id=$workflowId, loop_id=$loopId,
+          next_attempt_at=NULL, lease_expires_at=NULL, last_reason=$reason, updated_at=$updated
+         WHERE id=$id AND status IN ('queued', 'deferred')`).run({
+      $id: id,
+      $workflowId: patch.workflowId,
+      $loopId: patch.loopId,
+      $reason: patch.reason ?? null,
+      $updated: now
+    });
+    const item = this.getWorkflowWorkItem(id);
+    if (!item)
+      throw new Error(`workflow work item not found after admit: ${id}`);
+    if (res.changes !== 1)
+      throw new Error(`workflow work item is not claimable: ${id} status=${item.status}`);
+    return item;
+  }
+  setWorkflowWorkItemsForLoop(loopId, status, reason, updated, statuses = ["admitted", "running"]) {
+    const placeholders = statuses.map(() => "?").join(",");
+    this.db.query(`UPDATE workflow_work_items
+         SET status=?, lease_expires_at=NULL, last_reason=COALESCE(?, last_reason), updated_at=?
+         WHERE loop_id = ? AND status IN (${placeholders})`).run(status, reason ?? null, updated, loopId, ...statuses);
+  }
+  setWorkflowWorkItemsForWorkflowRun(workflowRunId, status, reason, updated, statuses = ["admitted", "running"]) {
+    const placeholders = statuses.map(() => "?").join(",");
+    this.db.query(`UPDATE workflow_work_items
+         SET status=?, lease_expires_at=NULL, last_reason=COALESCE(?, last_reason), updated_at=?
+         WHERE workflow_run_id = ? AND status IN (${placeholders})`).run(status, reason ?? null, updated, workflowRunId, ...statuses);
+  }
+  setWorkflowWorkItemsForLoopRun(run, reason, updated) {
+    const loop = this.getLoop(run.loopId);
+    const status = workItemStatusForLoopRun(run.status, run.attempt, loop?.maxAttempts);
+    if (!status)
+      return;
+    const statuses = status === "admitted" ? ["admitted", "running", "failed"] : ["admitted", "running"];
+    const nextReason = status === "admitted" ? reason ? `attempt failed; retry pending: ${reason}` : "attempt failed; retry pending" : reason;
+    this.setWorkflowWorkItemsForLoop(run.loopId, status, nextReason, updated, statuses);
+  }
   createGoal(input, opts = {}) {
     const now = nowIso();
     this.db.exec("BEGIN IMMEDIATE");
@@ -1481,6 +1830,10 @@ class Store {
   }
   createWorkflowRun(input) {
     const now = nowIso();
+    const targetInput = input.loop?.target.type === "workflow" ? input.loop.target.input : undefined;
+    const invocationId = input.invocationId ?? targetInput?.workflowInvocationId ?? targetInput?.invocationId;
+    const workItemId = input.workItemId ?? targetInput?.workflowWorkItemId ?? targetInput?.workItemId;
+    let manifestPath;
     if (input.idempotencyKey) {
       const existing = this.db.query("SELECT * FROM workflow_runs WHERE workflow_id = ? AND idempotency_key = ? LIMIT 1").get(input.workflow.id, input.idempotencyKey);
       if (existing) {
@@ -1499,21 +1852,59 @@ class Store {
         }
       }
       const runId = genId();
-      this.db.query(`INSERT INTO workflow_runs (id, workflow_id, workflow_name, loop_id, loop_run_id, scheduled_for, idempotency_key,
-            status, started_at, finished_at, duration_ms, error, created_at, updated_at)
-           VALUES ($id, $workflowId, $workflowName, $loopId, $loopRunId, $scheduledFor, $idempotencyKey,
-            'running', $started, NULL, NULL, NULL, $created, $updated)`).run({
+      const workItem = workItemId ? this.getWorkflowWorkItem(workItemId) : undefined;
+      const invocation = invocationId ? this.getWorkflowInvocation(invocationId) : undefined;
+      manifestPath = invocation || workItem ? writeWorkflowRunManifest({
+        loopsDataDir: this.rootDir,
+        workflowRunId: runId,
+        workflowId: input.workflow.id,
+        workflowName: input.workflow.name,
+        invocationId,
+        workItemId,
+        projectKey: workItem?.projectKey ?? invocation?.scope?.projectPath,
+        subjectKind: invocation?.subjectRef.kind,
+        rawSubjectRef: workItem?.subjectRef ?? invocation?.subjectRef.path ?? invocation?.subjectRef.id ?? invocation?.subjectRef.url,
+        payload: {
+          workflowInvocation: invocation,
+          workflowWorkItem: workItem,
+          loopId: input.loop?.id,
+          loopRunId: input.loopRun?.id,
+          scheduledFor: input.scheduledFor ?? input.loopRun?.scheduledFor
+        }
+      }) : undefined;
+      this.db.query(`INSERT INTO workflow_runs (id, workflow_id, workflow_name, loop_id, loop_run_id, invocation_id, work_item_id,
+            scheduled_for, idempotency_key, manifest_path, status, started_at, finished_at, duration_ms, error,
+            created_at, updated_at)
+           VALUES ($id, $workflowId, $workflowName, $loopId, $loopRunId, $invocationId, $workItemId, $scheduledFor,
+            $idempotencyKey, $manifestPath, 'running', $started, NULL, NULL, NULL, $created, $updated)`).run({
         $id: runId,
         $workflowId: input.workflow.id,
         $workflowName: input.workflow.name,
         $loopId: input.loop?.id ?? null,
         $loopRunId: input.loopRun?.id ?? null,
+        $invocationId: invocationId ?? null,
+        $workItemId: workItemId ?? null,
         $scheduledFor: input.scheduledFor ?? input.loopRun?.scheduledFor ?? null,
         $idempotencyKey: input.idempotencyKey ?? null,
+        $manifestPath: manifestPath ?? null,
         $started: now,
         $created: now,
         $updated: now
       });
+      if (workItemId) {
+        const workItemRes = this.db.query(`UPDATE workflow_work_items
+             SET status='running', workflow_run_id=$workflowRunId, lease_expires_at=$leaseExpiresAt, updated_at=$updated
+             WHERE id=$id AND status IN ('admitted', 'queued', 'deferred', 'running')`).run({
+          $id: workItemId,
+          $workflowRunId: runId,
+          $leaseExpiresAt: input.loop ? new Date(Date.now() + input.loop.leaseMs).toISOString() : null,
+          $updated: now
+        });
+        if (workItemRes.changes !== 1) {
+          const current = this.getWorkflowWorkItem(workItemId);
+          throw new Error(`workflow work item is not runnable: ${workItemId}${current ? ` status=${current.status}` : ""}`);
+        }
+      }
       input.workflow.steps.forEach((step, sequence) => {
         const account = step.account ?? step.target.account;
         this.db.query(`INSERT INTO workflow_step_runs (id, workflow_run_id, step_id, sequence, status, started_at, finished_at,
@@ -1539,7 +1930,10 @@ class Store {
           workflowName: input.workflow.name,
           stepCount: input.workflow.steps.length,
           loopId: input.loop?.id,
-          loopRunId: input.loopRun?.id
+          loopRunId: input.loopRun?.id,
+          invocationId,
+          workItemId,
+          manifestPath
         }),
         $created: now
       });
@@ -1552,6 +1946,8 @@ class Store {
       try {
         this.db.exec("ROLLBACK");
       } catch {}
+      if (manifestPath)
+        rmSync(manifestPath, { force: true });
       throw error;
     }
   }
@@ -1764,6 +2160,10 @@ class Store {
       changed = res.changes === 1;
       if (changed)
         this.appendWorkflowEvent(workflowRunId, status, undefined, { error: patch.error });
+      if (changed) {
+        const itemStatus = status === "succeeded" ? "succeeded" : status === "cancelled" ? "cancelled" : "failed";
+        this.setWorkflowWorkItemsForWorkflowRun(workflowRunId, itemStatus, patch.error, finishedAt);
+      }
       this.db.exec("COMMIT");
     } catch (error) {
       try {
@@ -1788,6 +2188,7 @@ class Store {
         this.db.query(`UPDATE workflow_step_runs
              SET status='cancelled', finished_at=$finished, pid=NULL, error=$reason, updated_at=$updated
              WHERE workflow_run_id=$workflowRunId AND status IN ('pending', 'running')`).run({ $workflowRunId: workflowRunId, $finished: now, $reason: reason, $updated: now });
+        this.setWorkflowWorkItemsForWorkflowRun(workflowRunId, "cancelled", reason, now);
         this.appendWorkflowEvent(workflowRunId, "cancelled", undefined, { reason });
       }
       this.db.exec("COMMIT");
@@ -2041,6 +2442,8 @@ class Store {
       throw new Error(`run not found after finalize: ${id}`);
     if (opts.claimedBy && res.changes !== 1)
       return run;
+    if (res.changes === 1)
+      this.setWorkflowWorkItemsForLoopRun(run, patch.error, finishedAt);
     return run;
   }
   heartbeatRunLease(id, claimedBy, leaseMs, now = new Date, opts = {}) {
@@ -2134,6 +2537,14 @@ class Store {
             error: "parent loop run lease expired before completion",
             loopRunId: row.id
           });
+          this.setWorkflowWorkItemsForWorkflowRun(workflowRow.id, "failed", "parent loop run lease expired before completion", finished);
+        }
+        const loop = this.getLoop(row.loop_id);
+        const itemStatus = workItemStatusForLoopRun("abandoned", row.attempt, loop?.maxAttempts);
+        if (itemStatus) {
+          const statuses = itemStatus === "admitted" ? ["admitted", "running", "failed"] : ["admitted", "running"];
+          const reason = itemStatus === "admitted" ? "run lease expired before completion; retry pending" : "run lease expired before completion";
+          this.setWorkflowWorkItemsForLoop(row.loop_id, itemStatus, reason, finished, statuses);
         }
         this.db.exec("COMMIT");
       } catch (error) {
@@ -2346,7 +2757,7 @@ function resolveAccountEnv(account, toolHint, env) {
 // src/lib/env.ts
 import { accessSync, constants } from "fs";
 import { homedir as homedir2 } from "os";
-import { delimiter, join as join2 } from "path";
+import { delimiter, join as join4 } from "path";
 function compactPathParts(parts) {
   const seen = new Set;
   const result = [];
@@ -2362,14 +2773,14 @@ function compactPathParts(parts) {
 function commonExecutableDirs(env = process.env) {
   const home = env.HOME || homedir2();
   return compactPathParts([
-    join2(home, ".local", "bin"),
-    join2(home, ".bun", "bin"),
-    join2(home, ".cargo", "bin"),
-    join2(home, ".npm-global", "bin"),
-    join2(home, "bin"),
-    env.BUN_INSTALL ? join2(env.BUN_INSTALL, "bin") : undefined,
+    join4(home, ".local", "bin"),
+    join4(home, ".bun", "bin"),
+    join4(home, ".cargo", "bin"),
+    join4(home, ".npm-global", "bin"),
+    join4(home, "bin"),
+    env.BUN_INSTALL ? join4(env.BUN_INSTALL, "bin") : undefined,
     env.PNPM_HOME,
-    env.NPM_CONFIG_PREFIX ? join2(env.NPM_CONFIG_PREFIX, "bin") : undefined,
+    env.NPM_CONFIG_PREFIX ? join4(env.NPM_CONFIG_PREFIX, "bin") : undefined,
     "/opt/homebrew/bin",
     "/usr/local/bin",
     "/usr/bin",
@@ -2393,7 +2804,7 @@ function executableExists(command, env = process.env) {
   if (command.includes("/"))
     return isExecutable(command);
   for (const dir of (env.PATH ?? "").split(delimiter)) {
-    if (dir && isExecutable(join2(dir, command)))
+    if (dir && isExecutable(join4(dir, command)))
       return true;
   }
   return false;
@@ -2751,6 +3162,7 @@ function commandSpec(target) {
       shell: commandTarget.shell,
       env: commandTarget.env,
       timeoutMs: commandTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      idleTimeoutMs: commandTarget.idleTimeoutMs,
       account: commandTarget.account,
       accountTool: commandTarget.account?.tool
     };
@@ -2761,6 +3173,7 @@ function commandSpec(target) {
     args: agentArgs(agentTarget),
     cwd: agentTarget.cwd,
     timeoutMs: agentTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    idleTimeoutMs: agentTarget.idleTimeoutMs,
     account: agentTarget.account,
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
     nativeAuthProfile: agentTarget.authProfile ? { provider: agentTarget.provider, profile: agentTarget.authProfile } : undefined,
@@ -2908,6 +3321,7 @@ async function executeRemoteSpec(spec, machine, metadata, opts) {
   let stdout = "";
   let stderr = "";
   let timedOut = false;
+  let idleTimedOut = false;
   let exitCode;
   let error;
   let plan;
@@ -2946,18 +3360,34 @@ async function executeRemoteSpec(spec, machine, metadata, opts) {
   if (opts.signal?.aborted)
     abortHandler();
   opts.signal?.addEventListener("abort", abortHandler, { once: true });
-  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();
+  let idleTimer;
+  const resetIdleTimer = () => {
+    if (!spec.idleTimeoutMs)
+      return;
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      idleTimedOut = true;
+      if (child.pid)
+        killProcessGroup(child.pid);
+    }, spec.idleTimeoutMs);
+    idleTimer.unref();
+  };
+  resetIdleTimer();
+  child.stdout?.on("data", (chunk) => {
+    stdout = appendBounded(stdout, chunk, maxOutputBytes);
+    resetIdleTimer();
+  });
+  child.stderr?.on("data", (chunk) => {
+    stderr = appendBounded(stderr, chunk, maxOutputBytes);
+    resetIdleTimer();
+  });
   try {
     const [code, signal] = await once(child, "exit");
     if (typeof code === "number")
@@ -2968,17 +3398,19 @@ async function executeRemoteSpec(spec, machine, metadata, opts) {
     error = err instanceof Error ? err.message : String(err);
   } finally {
     clearTimeout(timer);
+    if (idleTimer)
+      clearTimeout(idleTimer);
     opts.signal?.removeEventListener("abort", abortHandler);
   }
   const finishedAt = nowIso();
   const durationMs = new Date(finishedAt).getTime() - new Date(startedAt).getTime();
-  if (timedOut) {
+  if (timedOut || idleTimedOut) {
     return {
       status: "timed_out",
       exitCode,
       stdout,
       stderr,
-      error: `timed out after ${spec.timeoutMs}ms`,
+      error: idleTimedOut ? `idle timed out after ${spec.idleTimeoutMs}ms without stdout/stderr` : `timed out after ${spec.timeoutMs}ms`,
       pid: child.pid,
       startedAt,
       finishedAt,
@@ -3044,6 +3476,7 @@ async function executeTarget(target, metadata = {}, opts = {}) {
   let stdout = "";
   let stderr = "";
   let timedOut = false;
+  let idleTimedOut = false;
   let exitCode;
   let error;
   const env = executionEnv(spec, metadata, opts);
@@ -3106,18 +3539,34 @@ async function executeTarget(target, metadata = {}, opts = {}) {
   if (opts.signal?.aborted)
     abortHandler();
   opts.signal?.addEventListener("abort", abortHandler, { once: true });
-  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();
+  let idleTimer;
+  const resetIdleTimer = () => {
+    if (!spec.idleTimeoutMs)
+      return;
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      idleTimedOut = true;
+      if (child.pid)
+        killProcessGroup(child.pid);
+    }, spec.idleTimeoutMs);
+    idleTimer.unref();
+  };
+  resetIdleTimer();
+  child.stdout?.on("data", (chunk) => {
+    stdout = appendBounded(stdout, chunk, maxOutputBytes);
+    resetIdleTimer();
+  });
+  child.stderr?.on("data", (chunk) => {
+    stderr = appendBounded(stderr, chunk, maxOutputBytes);
+    resetIdleTimer();
+  });
   try {
     const [code, signal] = await once(child, "exit");
     if (typeof code === "number")
@@ -3128,17 +3577,19 @@ async function executeTarget(target, metadata = {}, opts = {}) {
     error = err instanceof Error ? err.message : String(err);
   } finally {
     clearTimeout(timer);
+    if (idleTimer)
+      clearTimeout(idleTimer);
     opts.signal?.removeEventListener("abort", abortHandler);
   }
   const finishedAt = nowIso();
   const durationMs = new Date(finishedAt).getTime() - new Date(startedAt).getTime();
-  if (timedOut) {
+  if (timedOut || idleTimedOut) {
     return {
       status: "timed_out",
       exitCode,
       stdout,
       stderr,
-      error: `timed out after ${spec.timeoutMs}ms`,
+      error: idleTimedOut ? `idle timed out after ${spec.idleTimeoutMs}ms without stdout/stderr` : `timed out after ${spec.timeoutMs}ms`,
       pid: child.pid,
       startedAt,
       finishedAt,
@@ -4270,8 +4721,48 @@ class LoopsClient {
 function loops(opts = {}) {
   return new LoopsClient(opts);
 }
+function openAutomationsRuntimeBinding(overrides = {}) {
+  const defaults = {
+    integration: "open-automations",
+    role: "runtime",
+    handoff: "claim-queue",
+    queueOwner: "open-automations",
+    runtimeOwner: "open-loops",
+    statusCommand: "automations status",
+    claimCommand: "automations queue claim",
+    completeCommand: "automations queue complete",
+    failCommand: "automations queue fail",
+    eventHandoff: {
+      envelopeCommand: "automations webhooks event",
+      handlerCommand: "loops events handle generic",
+      pipeExample: "automations --json webhooks event <route> --body-json '<json>' | loops --json events handle generic",
+      boundary: "Use only for explicit event-envelope workflow handoff. OpenAutomations still owns deterministic automation materialization and queue state; OpenLoops owns workflow invocation."
+    },
+    requiredEnvironment: ["HASNA_AUTOMATIONS_DIR"],
+    guarantees: [
+      "OpenAutomations owns automation specs, run materialization, queue state, DLQ, replay, idempotency, and approvals.",
+      "OpenLoops may execute claimed actions through explicit command or SDK handoff only.",
+      "OpenLoops may consume exported event envelopes only through explicit events handle commands.",
+      "Workers must complete or fail actions by action id and runner id so OpenAutomations can enforce queue leases."
+    ],
+    nonGoals: [
+      "OpenLoops must not become the OpenAutomations product surface.",
+      "OpenLoops must not store automation specs or replace the OpenAutomations queue.",
+      "OpenLoops must not infer automation trigger semantics from event transport alone."
+    ]
+  };
+  return {
+    ...defaults,
+    ...overrides,
+    eventHandoff: overrides.eventHandoff ?? defaults.eventHandoff,
+    requiredEnvironment: overrides.requiredEnvironment ?? defaults.requiredEnvironment,
+    guarantees: overrides.guarantees ?? defaults.guarantees,
+    nonGoals: overrides.nonGoals ?? defaults.nonGoals
+  };
+}
 export {
   runGoal,
+  openAutomationsRuntimeBinding,
   loops,
   LoopsClient
 };