@tangle-network/agent-runtime 0.12.0 → 0.13.0

package/dist/index.js

@@ -106,33 +106,78 @@ function createSandboxPromptBackend(options) {
     }
   };
 }
+var DEFAULT_RETRY_STATUSES = [408, 425, 429, 500, 502, 503, 504];
+function pickRetryDelayMs(attempt, policy) {
+  const exp = policy.initialBackoffMs * 2 ** (attempt - 1);
+  const capped = Math.min(exp, policy.maxBackoffMs);
+  const jitter = capped * policy.jitter * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(capped + jitter));
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function createOpenAICompatibleBackend(options) {
   const fetcher = options.fetchImpl ?? fetch;
   const kind = options.kind ?? "tcloud";
+  const retryPolicy = {
+    maxAttempts: options.retry?.maxAttempts ?? 5,
+    initialBackoffMs: options.retry?.initialBackoffMs ?? 1e3,
+    maxBackoffMs: options.retry?.maxBackoffMs ?? 3e4,
+    jitter: options.retry?.jitter ?? 0.25,
+    retryStatuses: options.retry?.retryStatuses ?? DEFAULT_RETRY_STATUSES
+  };
   return {
     kind,
     start(_input, context) {
       return newRuntimeSession(kind, context.requestedSessionId);
     },
     async *stream(input, context) {
-      const response = await fetcher(`${options.baseUrl.replace(/\/$/, "")}/chat/completions`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${options.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          model: options.model,
-          stream: true,
-          messages: input.messages ?? [
-            { role: "user", content: input.message ?? context.task.intent }
-          ]
-        }),
-        signal: context.signal
-      });
-      if (!response.ok) {
-        throw new BackendTransportError(kind, `chat backend returned ${response.status}`, {
-          status: response.status
+      let response;
+      let lastStatus = 0;
+      for (let attempt = 1; attempt <= retryPolicy.maxAttempts; attempt++) {
+        response = await fetcher(`${options.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${options.apiKey}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            model: options.model,
+            stream: true,
+            messages: input.messages ?? [
+              { role: "user", content: input.message ?? context.task.intent }
+            ]
+          }),
+          signal: context.signal
+        });
+        if (response.ok) break;
+        lastStatus = response.status;
+        if (!retryPolicy.retryStatuses.includes(response.status)) break;
+        if (attempt === retryPolicy.maxAttempts) break;
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+        const delayMs = pickRetryDelayMs(attempt, retryPolicy);
+        await sleep(delayMs, context.signal);
+      }
+      if (!response || !response.ok) {
+        throw new BackendTransportError(kind, `chat backend returned ${lastStatus || "unknown"}`, {
+          status: lastStatus || 0
         });
       }
       yield* streamResponseEvents(response, context);
@@ -388,6 +433,1111 @@ function sandboxAsChatTurnTarget(instance, opts) {
   };
 }
 
+// src/durable/identity.ts
+import { createHash } from "crypto";
+function canonicalHash(value) {
+  const json = canonicalJson(value);
+  return createHash("sha256").update(json).digest("hex");
+}
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+  if (value === null) return null;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return value;
+  if (t === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`canonicalJson: non-finite number ${String(value)} not serializable`);
+    }
+    return value;
+  }
+  if (t === "undefined" || t === "function" || t === "symbol") {
+    throw new TypeError(`canonicalJson: ${t} is not JSON-serializable`);
+  }
+  if (t === "bigint") {
+    return { __bigint: String(value) };
+  }
+  if (t === "object") {
+    const obj = value;
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== null && proto !== Object.prototype) {
+      const ctor = obj.constructor?.name ?? "unknown";
+      throw new TypeError(
+        `canonicalJson: class instance (${ctor}) is not JSON-serializable. Project to plain { ... } at the boundary.`
+      );
+    }
+    const keys = Object.keys(obj).sort();
+    const out = {};
+    for (const k of keys) out[k] = canonicalize(obj[k]);
+    return out;
+  }
+  throw new TypeError(`canonicalJson: unsupported type ${t}`);
+}
+function manifestHash(manifest) {
+  return canonicalHash({
+    projectId: manifest.projectId,
+    scenarioId: manifest.scenarioId ?? null,
+    taskId: manifest.task.id,
+    taskIntent: manifest.task.intent,
+    taskDomain: manifest.task.domain,
+    input: manifest.input
+  });
+}
+function stepId(runId, stepIndex, intent) {
+  return canonicalHash({ runId, stepIndex, intent });
+}
+var counter = 0;
+function deriveWorkerId() {
+  const host = process.env.HOSTNAME ?? "host";
+  const pid = process.pid ?? 0;
+  const rand = Math.random().toString(36).slice(2, 10);
+  counter += 1;
+  return `${host}:${pid}:${rand}:${counter}`;
+}
+
+// src/durable/types.ts
+var DurableRunError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = this.constructor.name;
+  }
+  code;
+};
+var DurableRunLeaseHeldError = class extends DurableRunError {
+  constructor(message) {
+    super(message, "lease_held");
+  }
+};
+var DurableRunInputMismatchError = class extends DurableRunError {
+  constructor(message) {
+    super(message, "manifest_mismatch");
+  }
+};
+var DurableRunDivergenceError = class extends DurableRunError {
+  constructor(message) {
+    super(message, "step_divergence");
+  }
+};
+var DurableAwaitEventTimeoutError = class extends DurableRunError {
+  constructor(message) {
+    super(message, "await_event_timeout");
+  }
+};
+
+// src/durable/d1-store.ts
+var DEFAULT_LEASE_MS = 3e4;
+var D1DurableRunStore = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  /** Override for tests — defaults to Date.now(). */
+  now = () => Date.now();
+  async startOrResume(input) {
+    const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS;
+    const hash = manifestHash(input.manifest);
+    const nowMs = this.now();
+    const nowIso2 = new Date(nowMs).toISOString();
+    const leaseExpiresAt = new Date(nowMs + leaseMs).toISOString();
+    const existing = await this.db.prepare("SELECT * FROM durable_runs WHERE run_id = ?").bind(input.runId).first();
+    if (!existing) {
+      await this.db.prepare(
+        `INSERT INTO durable_runs
+             (run_id, manifest_hash, project_id, scenario_id, status,
+              created_at, updated_at, lease_holder_id, lease_expires_at, step_count)
+           VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, 0)`
+      ).bind(
+        input.runId,
+        hash,
+        input.manifest.projectId,
+        input.manifest.scenarioId ?? null,
+        nowIso2,
+        nowIso2,
+        input.workerId,
+        leaseExpiresAt
+      ).run();
+      const record2 = {
+        runId: input.runId,
+        manifestHash: hash,
+        projectId: input.manifest.projectId,
+        scenarioId: input.manifest.scenarioId,
+        status: "running",
+        createdAt: nowIso2,
+        updatedAt: nowIso2,
+        leaseHolderId: input.workerId,
+        leaseExpiresAt,
+        stepCount: 0
+      };
+      return { run: record2, completedSteps: [], leaseExpiresAt };
+    }
+    if (existing.manifest_hash !== hash) {
+      throw new DurableRunInputMismatchError(
+        `runId ${input.runId} exists with a different manifest hash; refuse to corrupt prior steps`
+      );
+    }
+    const claim = await this.db.prepare(
+      `UPDATE durable_runs
+           SET lease_holder_id = ?,
+               lease_expires_at = ?,
+               updated_at = ?,
+               status = CASE WHEN status IN ('completed','failed') THEN status ELSE 'running' END
+         WHERE run_id = ?
+           AND (
+             lease_holder_id = ? OR
+             lease_holder_id IS NULL OR
+             lease_expires_at IS NULL OR
+             lease_expires_at < ?
+           )`
+    ).bind(input.workerId, leaseExpiresAt, nowIso2, input.runId, input.workerId, nowIso2).run();
+    const changes = claim.meta?.changes ?? 0;
+    if (changes === 0) {
+      throw new DurableRunLeaseHeldError(
+        `runId ${input.runId} leased by ${existing.lease_holder_id} until ${existing.lease_expires_at}`
+      );
+    }
+    const completedSteps = await this.readSteps(input.runId, "completed");
+    const record = rowToRunRecord({
+      ...existing,
+      lease_holder_id: input.workerId,
+      lease_expires_at: leaseExpiresAt,
+      updated_at: nowIso2,
+      status: existing.status === "completed" || existing.status === "failed" ? existing.status : "running"
+    });
+    return { run: record, completedSteps, leaseExpiresAt };
+  }
+  async renewLease(input) {
+    const nowMs = this.now();
+    const nowIso2 = new Date(nowMs).toISOString();
+    const leaseExpiresAt = new Date(nowMs + (input.leaseMs ?? DEFAULT_LEASE_MS)).toISOString();
+    const res = await this.db.prepare(
+      `UPDATE durable_runs
+           SET lease_expires_at = ?, updated_at = ?
+         WHERE run_id = ?
+           AND (lease_holder_id = ? OR lease_expires_at IS NULL OR lease_expires_at < ?)`
+    ).bind(leaseExpiresAt, nowIso2, input.runId, input.workerId, nowIso2).run();
+    const ok = (res.meta?.changes ?? 0) > 0;
+    return ok ? { ok: true, leaseExpiresAt } : { ok: false };
+  }
+  async loadStep(runId, stepIndex) {
+    const row = await this.db.prepare("SELECT * FROM durable_steps WHERE run_id = ? AND step_index = ?").bind(runId, stepIndex).first();
+    return row ? rowToStepRecord(row) : void 0;
+  }
+  async beginStep(input) {
+    const nowIso2 = new Date(this.now()).toISOString();
+    const prior = await this.loadStep(input.runId, input.stepIndex);
+    if (prior) {
+      if (prior.intent !== input.intent) {
+        throw new DurableRunDivergenceError(
+          `step ${input.stepIndex}: intent changed ('${prior.intent}' -> '${input.intent}')`
+        );
+      }
+      await this.db.prepare(
+        `UPDATE durable_steps
+             SET status='running', attempts = attempts + 1, started_at = ?, error_json = NULL
+           WHERE run_id = ? AND step_index = ?`
+      ).bind(nowIso2, input.runId, input.stepIndex).run();
+      await this.bumpUpdated(input.runId, nowIso2);
+      return {
+        ...prior,
+        attempts: prior.attempts + 1,
+        status: "running",
+        startedAt: nowIso2,
+        error: void 0
+      };
+    }
+    await this.db.prepare(
+      `INSERT INTO durable_steps
+           (run_id, step_index, intent, kind, input_hash, status, attempts, started_at)
+         VALUES (?, ?, ?, ?, ?, 'running', 1, ?)`
+    ).bind(input.runId, input.stepIndex, input.intent, input.kind, input.inputHash, nowIso2).run();
+    await this.db.prepare(
+      `UPDATE durable_runs
+           SET step_count = MAX(step_count, ?), updated_at = ?
+         WHERE run_id = ?`
+    ).bind(input.stepIndex + 1, nowIso2, input.runId).run();
+    return {
+      runId: input.runId,
+      stepIndex: input.stepIndex,
+      intent: input.intent,
+      kind: input.kind,
+      inputHash: input.inputHash,
+      status: "running",
+      attempts: 1,
+      startedAt: nowIso2
+    };
+  }
+  async completeStep(input) {
+    const nowIso2 = new Date(this.now()).toISOString();
+    await this.db.prepare(
+      `UPDATE durable_steps
+           SET status='completed', result_json = ?, completed_at = ?, error_json = NULL
+         WHERE run_id = ? AND step_index = ?`
+    ).bind(JSON.stringify(input.result ?? null), nowIso2, input.runId, input.stepIndex).run();
+    await this.bumpUpdated(input.runId, nowIso2);
+    const row = await this.loadStep(input.runId, input.stepIndex);
+    if (!row) {
+      throw new Error(`durable-runs: completeStep cannot find step ${input.stepIndex}`);
+    }
+    return row;
+  }
+  async failStep(input) {
+    const nowIso2 = new Date(this.now()).toISOString();
+    await this.db.prepare(
+      `UPDATE durable_steps
+           SET status='failed', error_json = ?, completed_at = ?
+         WHERE run_id = ? AND step_index = ?`
+    ).bind(JSON.stringify(input.error), nowIso2, input.runId, input.stepIndex).run();
+    await this.bumpUpdated(input.runId, nowIso2);
+    const row = await this.loadStep(input.runId, input.stepIndex);
+    if (!row) {
+      throw new Error(`durable-runs: failStep cannot find step ${input.stepIndex}`);
+    }
+    return row;
+  }
+  async endRun(input) {
+    const nowIso2 = new Date(this.now()).toISOString();
+    await this.db.prepare(
+      `UPDATE durable_runs
+           SET status = ?, completed_at = ?, updated_at = ?,
+               outcome_json = ?,
+               lease_holder_id = CASE WHEN lease_holder_id = ? THEN NULL ELSE lease_holder_id END,
+               lease_expires_at = CASE WHEN lease_holder_id = ? THEN NULL ELSE lease_expires_at END
+         WHERE run_id = ?`
+    ).bind(
+      input.status,
+      nowIso2,
+      nowIso2,
+      input.outcome ? JSON.stringify(input.outcome) : null,
+      input.workerId,
+      input.workerId,
+      input.runId
+    ).run();
+    const row = await this.db.prepare("SELECT * FROM durable_runs WHERE run_id = ?").bind(input.runId).first();
+    if (!row) throw new Error(`durable-runs: endRun cannot find run ${input.runId}`);
+    return rowToRunRecord(row);
+  }
+  async emitEvent(input) {
+    const nowIso2 = new Date(this.now()).toISOString();
+    const res = await this.db.prepare(
+      `INSERT OR IGNORE INTO durable_events (run_id, key, payload_json, emitted_at)
+         VALUES (?, ?, ?, ?)`
+    ).bind(input.runId, input.key, JSON.stringify(input.payload ?? null), nowIso2).run();
+    const accepted = (res.meta?.changes ?? 0) > 0;
+    const row = await this.db.prepare("SELECT * FROM durable_events WHERE run_id = ? AND key = ?").bind(input.runId, input.key).first();
+    if (!row) throw new Error("durable-runs: emitEvent failed to persist or read back");
+    return {
+      accepted,
+      record: rowToEventRecord(row)
+    };
+  }
+  async loadEvent(runId, key) {
+    const row = await this.db.prepare("SELECT * FROM durable_events WHERE run_id = ? AND key = ?").bind(runId, key).first();
+    return row ? rowToEventRecord(row) : void 0;
+  }
+  async close() {
+  }
+  /** Inspect the currently-applied schema version. */
+  async getSchemaVersion() {
+    const row = await this.db.prepare("SELECT MAX(version) AS version FROM durable_schema_info").first();
+    return row?.version ?? void 0;
+  }
+  // ── internals ──────────────────────────────────────────────────────
+  async readSteps(runId, status) {
+    const { results } = await this.db.prepare("SELECT * FROM durable_steps WHERE run_id = ? AND status = ? ORDER BY step_index").bind(runId, status).all();
+    return results.map(rowToStepRecord);
+  }
+  async bumpUpdated(runId, nowIso2) {
+    await this.db.prepare("UPDATE durable_runs SET updated_at = ? WHERE run_id = ?").bind(nowIso2, runId).run();
+  }
+};
+function rowToRunRecord(row) {
+  return {
+    runId: row.run_id,
+    manifestHash: row.manifest_hash,
+    projectId: row.project_id,
+    scenarioId: row.scenario_id ?? void 0,
+    status: row.status,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    completedAt: row.completed_at ?? void 0,
+    leaseHolderId: row.lease_holder_id ?? void 0,
+    leaseExpiresAt: row.lease_expires_at ?? void 0,
+    outcome: row.outcome_json ? JSON.parse(row.outcome_json) : void 0,
+    stepCount: row.step_count
+  };
+}
+function rowToStepRecord(row) {
+  return {
+    runId: row.run_id,
+    stepIndex: row.step_index,
+    intent: row.intent,
+    kind: row.kind,
+    inputHash: row.input_hash,
+    status: row.status,
+    attempts: row.attempts,
+    result: row.result_json ? JSON.parse(row.result_json) : void 0,
+    error: row.error_json ? JSON.parse(row.error_json) : void 0,
+    startedAt: row.started_at ?? void 0,
+    completedAt: row.completed_at ?? void 0
+  };
+}
+function rowToEventRecord(row) {
+  return {
+    runId: row.run_id,
+    key: row.key,
+    payload: row.payload_json ? JSON.parse(row.payload_json) : null,
+    emittedAt: row.emitted_at
+  };
+}
+
+// src/durable/file-system-store.ts
+import { existsSync, mkdirSync } from "fs";
+import { appendFile, readdir, readFile, rename, writeFile } from "fs/promises";
+import { join } from "path";
+var DEFAULT_LEASE_MS2 = 3e4;
+var FileSystemDurableRunStore = class {
+  constructor(root) {
+    this.root = root;
+    mkdirSync(root, { recursive: true });
+  }
+  root;
+  /** Override for tests — defaults to Date.now(). */
+  now = () => Date.now();
+  async startOrResume(input) {
+    const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS2;
+    const hash = manifestHash(input.manifest);
+    const nowMs = this.now();
+    const nowIso2 = new Date(nowMs).toISOString();
+    const leaseExpiresAt = new Date(nowMs + leaseMs).toISOString();
+    const dir = this.runDir(input.runId);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      const record2 = {
+        runId: input.runId,
+        manifestHash: hash,
+        projectId: input.manifest.projectId,
+        scenarioId: input.manifest.scenarioId,
+        status: "running",
+        createdAt: nowIso2,
+        updatedAt: nowIso2,
+        leaseHolderId: input.workerId,
+        leaseExpiresAt,
+        stepCount: 0
+      };
+      await this.writeRun(record2);
+      await this.writeLease(input.runId, { workerId: input.workerId, leaseExpiresAt });
+      await appendFile(join(dir, "steps.jsonl"), "", "utf8");
+      await appendFile(join(dir, "events.jsonl"), "", "utf8");
+      return { run: record2, completedSteps: [], leaseExpiresAt };
+    }
+    const record = await this.readRun(input.runId);
+    if (record.manifestHash !== hash) {
+      throw new DurableRunInputMismatchError(
+        `runId ${input.runId} exists with a different manifest hash; refuse to corrupt prior steps`
+      );
+    }
+    const lease = await this.readLeaseSafe(input.runId);
+    const leaseStillLive = lease && lease.workerId !== input.workerId && new Date(lease.leaseExpiresAt).getTime() > nowMs;
+    if (leaseStillLive) {
+      throw new DurableRunLeaseHeldError(
+        `runId ${input.runId} leased by ${lease.workerId} until ${lease.leaseExpiresAt}`
+      );
+    }
+    const completedSteps = await this.readSteps(input.runId);
+    const nextRecord = {
+      ...record,
+      status: record.status === "completed" || record.status === "failed" ? record.status : "running",
+      updatedAt: nowIso2,
+      leaseHolderId: input.workerId,
+      leaseExpiresAt
+    };
+    await this.writeRun(nextRecord);
+    await this.writeLease(input.runId, { workerId: input.workerId, leaseExpiresAt });
+    return { run: nextRecord, completedSteps, leaseExpiresAt };
+  }
+  async renewLease(input) {
+    const lease = await this.readLeaseSafe(input.runId);
+    const nowMs = this.now();
+    if (lease && lease.workerId !== input.workerId) {
+      if (new Date(lease.leaseExpiresAt).getTime() > nowMs) {
+        return { ok: false };
+      }
+    }
+    const leaseExpiresAt = new Date(nowMs + (input.leaseMs ?? DEFAULT_LEASE_MS2)).toISOString();
+    await this.writeLease(input.runId, { workerId: input.workerId, leaseExpiresAt });
+    return { ok: true, leaseExpiresAt };
+  }
+  async loadStep(runId, stepIndex) {
+    const steps = await this.readSteps(runId, { includeFailed: true, includeRunning: true });
+    return steps.find((s) => s.stepIndex === stepIndex);
+  }
+  async beginStep(input) {
+    const all = await this.readSteps(input.runId, { includeFailed: true, includeRunning: true });
+    const prior = all.find((s) => s.stepIndex === input.stepIndex);
+    const nowIso2 = new Date(this.now()).toISOString();
+    if (prior) {
+      if (prior.intent !== input.intent) {
+        throw new DurableRunDivergenceError(
+          `step ${input.stepIndex}: intent changed ('${prior.intent}' -> '${input.intent}')`
+        );
+      }
+      const rec2 = {
+        ...prior,
+        attempts: prior.attempts + 1,
+        status: "running",
+        startedAt: nowIso2,
+        error: void 0
+      };
+      await this.appendStep(input.runId, rec2);
+      await this.bumpRunUpdated(input.runId, nowIso2);
+      return rec2;
+    }
+    const rec = {
+      runId: input.runId,
+      stepIndex: input.stepIndex,
+      intent: input.intent,
+      kind: input.kind,
+      inputHash: input.inputHash,
+      status: "running",
+      attempts: 1,
+      startedAt: nowIso2
+    };
+    await this.appendStep(input.runId, rec);
+    const record = await this.readRun(input.runId);
+    record.stepCount = Math.max(record.stepCount, input.stepIndex + 1);
+    record.updatedAt = nowIso2;
+    await this.writeRun(record);
+    return rec;
+  }
+  async completeStep(input) {
+    const all = await this.readSteps(input.runId, { includeFailed: true, includeRunning: true });
+    const prior = all.find((s) => s.stepIndex === input.stepIndex);
+    if (!prior) {
+      throw new Error(
+        `durable-runs: completeStep called before beginStep (step ${input.stepIndex})`
+      );
+    }
+    const nowIso2 = new Date(this.now()).toISOString();
+    const rec = {
+      ...prior,
+      status: "completed",
+      result: input.result,
+      completedAt: nowIso2,
+      error: void 0
+    };
+    await this.appendStep(input.runId, rec);
+    await this.bumpRunUpdated(input.runId, nowIso2);
+    return rec;
+  }
+  async failStep(input) {
+    const all = await this.readSteps(input.runId, { includeFailed: true, includeRunning: true });
+    const prior = all.find((s) => s.stepIndex === input.stepIndex);
+    if (!prior) {
+      throw new Error(`durable-runs: failStep called before beginStep (step ${input.stepIndex})`);
+    }
+    const nowIso2 = new Date(this.now()).toISOString();
+    const rec = {
+      ...prior,
+      status: "failed",
+      error: input.error,
+      completedAt: nowIso2
+    };
+    await this.appendStep(input.runId, rec);
+    await this.bumpRunUpdated(input.runId, nowIso2);
+    return rec;
+  }
+  async endRun(input) {
+    const record = await this.readRun(input.runId);
+    const nowIso2 = new Date(this.now()).toISOString();
+    record.status = input.status;
+    record.outcome = input.outcome;
+    record.completedAt = nowIso2;
+    record.updatedAt = nowIso2;
+    const lease = await this.readLeaseSafe(input.runId);
+    if (lease && lease.workerId === input.workerId) {
+      record.leaseHolderId = void 0;
+      record.leaseExpiresAt = void 0;
+      await this.writeLease(input.runId, null);
+    }
+    await this.writeRun(record);
+    return record;
+  }
+  async emitEvent(input) {
+    const existing = await this.loadEvent(input.runId, input.key);
+    if (existing) return { accepted: false, record: existing };
+    const rec = {
+      runId: input.runId,
+      key: input.key,
+      payload: input.payload,
+      emittedAt: new Date(this.now()).toISOString()
+    };
+    await appendFile(
+      join(this.runDir(input.runId), "events.jsonl"),
+      `${JSON.stringify(rec)}
+`,
+      "utf8"
+    );
+    return { accepted: true, record: rec };
+  }
+  async loadEvent(runId, key) {
+    const path = join(this.runDir(runId), "events.jsonl");
+    if (!existsSync(path)) return void 0;
+    const content = await readFile(path, "utf8");
+    for (const line of content.split("\n").reverse()) {
+      if (!line) continue;
+      const rec = JSON.parse(line);
+      if (rec.key === key) return rec;
+    }
+    return void 0;
+  }
+  async close() {
+  }
+  /** @internal — used by tests to list runs in the store. */
+  async _listRunIds() {
+    if (!existsSync(this.root)) return [];
+    const entries = await readdir(this.root, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  }
+  // ── internals ──────────────────────────────────────────────────────
+  runDir(runId) {
+    return join(this.root, runId);
+  }
+  async readRun(runId) {
+    const path = join(this.runDir(runId), "run.json");
+    const content = await readFile(path, "utf8");
+    return JSON.parse(content);
+  }
+  async writeRun(record) {
+    const dir = this.runDir(record.runId);
+    const path = join(dir, "run.json");
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(record, null, 2), "utf8");
+    await rename(tmp, path);
+  }
+  async readLeaseSafe(runId) {
+    const path = join(this.runDir(runId), "lease.json");
+    if (!existsSync(path)) return void 0;
+    try {
+      const content = await readFile(path, "utf8");
+      if (!content.trim()) return void 0;
+      return JSON.parse(content);
+    } catch {
+      return void 0;
+    }
+  }
+  async writeLease(runId, lease) {
+    const path = join(this.runDir(runId), "lease.json");
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, lease ? JSON.stringify(lease) : "", "utf8");
+    await rename(tmp, path);
+  }
+  async readSteps(runId, opts = {}) {
+    const path = join(this.runDir(runId), "steps.jsonl");
+    if (!existsSync(path)) return [];
+    const content = await readFile(path, "utf8");
+    const latest = /* @__PURE__ */ new Map();
+    for (const line of content.split("\n")) {
+      if (!line) continue;
+      const rec = JSON.parse(line);
+      latest.set(rec.stepIndex, rec);
+    }
+    const out = [...latest.values()].sort((a, b) => a.stepIndex - b.stepIndex);
+    return out.filter((s) => {
+      if (s.status === "completed") return true;
+      if (s.status === "failed") return opts.includeFailed ?? false;
+      if (s.status === "running") return opts.includeRunning ?? false;
+      return false;
+    });
+  }
+  async appendStep(runId, rec) {
+    await appendFile(join(this.runDir(runId), "steps.jsonl"), `${JSON.stringify(rec)}
+`, "utf8");
+  }
+  async bumpRunUpdated(runId, nowIso2) {
+    const record = await this.readRun(runId);
+    record.updatedAt = nowIso2;
+    await this.writeRun(record);
+  }
+};
+
+// src/durable/in-memory-store.ts
+var DEFAULT_LEASE_MS3 = 3e4;
+var InMemoryDurableRunStore = class {
+  runs = /* @__PURE__ */ new Map();
+  /** Override for tests — defaults to Date.now(). */
+  now = () => Date.now();
+  async startOrResume(input) {
+    const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS3;
+    const hash = manifestHash(input.manifest);
+    const nowMs = this.now();
+    const nowIso2 = new Date(nowMs).toISOString();
+    const leaseExpiresMs = nowMs + leaseMs;
+    const leaseExpiresAt = new Date(leaseExpiresMs).toISOString();
+    let state = this.runs.get(input.runId);
+    if (!state) {
+      const record = {
+        runId: input.runId,
+        manifestHash: hash,
+        projectId: input.manifest.projectId,
+        scenarioId: input.manifest.scenarioId,
+        status: "running",
+        createdAt: nowIso2,
+        updatedAt: nowIso2,
+        leaseHolderId: input.workerId,
+        leaseExpiresAt,
+        stepCount: 0
+      };
+      state = { record, steps: /* @__PURE__ */ new Map(), events: /* @__PURE__ */ new Map() };
+      this.runs.set(input.runId, state);
+      return { run: { ...record }, completedSteps: [], leaseExpiresAt };
+    }
+    if (state.record.manifestHash !== hash) {
+      throw new DurableRunInputMismatchError(
+        `runId ${input.runId} exists with a different manifest hash; refuse to corrupt prior steps`
+      );
+    }
+    const leaseStillLive = state.record.leaseHolderId !== void 0 && state.record.leaseHolderId !== input.workerId && state.record.leaseExpiresAt !== void 0 && new Date(state.record.leaseExpiresAt).getTime() > nowMs;
+    if (leaseStillLive) {
+      throw new DurableRunLeaseHeldError(
+        `runId ${input.runId} is leased by ${state.record.leaseHolderId} until ${state.record.leaseExpiresAt}`
+      );
+    }
+    state.record.leaseHolderId = input.workerId;
+    state.record.leaseExpiresAt = leaseExpiresAt;
+    state.record.status = state.record.status === "completed" || state.record.status === "failed" ? state.record.status : "running";
+    state.record.updatedAt = nowIso2;
+    const completed = [...state.steps.values()].filter((s) => s.status === "completed").sort((a, b) => a.stepIndex - b.stepIndex);
+    return {
+      run: { ...state.record },
+      completedSteps: completed.map((s) => ({ ...s })),
+      leaseExpiresAt
+    };
+  }
+  async renewLease(input) {
+    const state = this.runs.get(input.runId);
+    if (!state) return { ok: false };
+    const nowMs = this.now();
+    if (state.record.leaseHolderId !== input.workerId) {
+      if (state.record.leaseExpiresAt && new Date(state.record.leaseExpiresAt).getTime() > nowMs) {
+        return { ok: false };
+      }
+    }
+    const leaseExpiresMs = nowMs + (input.leaseMs ?? DEFAULT_LEASE_MS3);
+    const leaseExpiresAt = new Date(leaseExpiresMs).toISOString();
+    state.record.leaseHolderId = input.workerId;
+    state.record.leaseExpiresAt = leaseExpiresAt;
+    state.record.updatedAt = new Date(nowMs).toISOString();
+    return { ok: true, leaseExpiresAt };
+  }
+  async loadStep(runId, stepIndex) {
+    const state = this.runs.get(runId);
+    return state ? cloneStep(state.steps.get(stepIndex)) : void 0;
+  }
+  async beginStep(input) {
+    const state = this.requireRun(input.runId);
+    const nowIso2 = new Date(this.now()).toISOString();
+    const prior = state.steps.get(input.stepIndex);
+    if (prior) {
+      if (prior.intent !== input.intent) {
+        throw new DurableRunDivergenceError(
+          `step ${input.stepIndex}: intent changed across replays ('${prior.intent}' -> '${input.intent}')`
+        );
+      }
+      prior.attempts += 1;
+      prior.status = "running";
+      prior.startedAt = nowIso2;
+      prior.error = void 0;
+      state.record.updatedAt = nowIso2;
+      return cloneStep(prior);
+    }
+    const rec = {
+      runId: input.runId,
+      stepIndex: input.stepIndex,
+      intent: input.intent,
+      kind: input.kind,
+      inputHash: input.inputHash,
+      status: "running",
+      attempts: 1,
+      startedAt: nowIso2
+    };
+    state.steps.set(input.stepIndex, rec);
+    state.record.stepCount = Math.max(state.record.stepCount, input.stepIndex + 1);
+    state.record.updatedAt = nowIso2;
+    return cloneStep(rec);
+  }
+  async completeStep(input) {
+    const state = this.requireRun(input.runId);
+    const rec = state.steps.get(input.stepIndex);
+    if (!rec) {
+      throw new Error(
+        `durable-runs: completeStep called before beginStep (step ${input.stepIndex})`
+      );
+    }
+    const nowIso2 = new Date(this.now()).toISOString();
+    rec.status = "completed";
+    rec.result = input.result;
+    rec.completedAt = nowIso2;
+    rec.error = void 0;
+    state.record.updatedAt = nowIso2;
+    return cloneStep(rec);
+  }
+  async failStep(input) {
+    const state = this.requireRun(input.runId);
+    const rec = state.steps.get(input.stepIndex);
+    if (!rec) {
+      throw new Error(`durable-runs: failStep called before beginStep (step ${input.stepIndex})`);
+    }
+    const nowIso2 = new Date(this.now()).toISOString();
+    rec.status = "failed";
+    rec.error = input.error;
+    rec.completedAt = nowIso2;
+    state.record.updatedAt = nowIso2;
+    return cloneStep(rec);
+  }
+  async endRun(input) {
+    const state = this.requireRun(input.runId);
+    const nowIso2 = new Date(this.now()).toISOString();
+    state.record.status = input.status;
+    state.record.outcome = input.outcome;
+    state.record.completedAt = nowIso2;
+    state.record.updatedAt = nowIso2;
+    if (state.record.leaseHolderId === input.workerId) {
+      state.record.leaseHolderId = void 0;
+      state.record.leaseExpiresAt = void 0;
+    }
+    return { ...state.record };
+  }
+  async emitEvent(input) {
+    const state = this.requireRun(input.runId);
+    const existing = state.events.get(input.key);
+    if (existing) {
+      return { accepted: false, record: { ...existing } };
+    }
+    const rec = {
+      runId: input.runId,
+      key: input.key,
+      payload: input.payload,
+      emittedAt: new Date(this.now()).toISOString()
+    };
+    state.events.set(input.key, rec);
+    return { accepted: true, record: { ...rec } };
+  }
+  async loadEvent(runId, key) {
+    const state = this.runs.get(runId);
+    if (!state) return void 0;
+    const rec = state.events.get(key);
+    return rec ? { ...rec } : void 0;
+  }
+  async close() {
+    this.runs.clear();
+  }
+  // ── test helpers ───────────────────────────────────────────────────
+  /** @internal — used by tests to inspect lease metadata. */
+  _inspect(runId) {
+    const s = this.runs.get(runId);
+    return s ? { ...s.record } : void 0;
+  }
+  /** @internal — used by tests to simulate lease expiry. */
+  _expireLease(runId) {
+    const s = this.runs.get(runId);
+    if (s) {
+      s.record.leaseHolderId = void 0;
+      s.record.leaseExpiresAt = void 0;
+    }
+  }
+  requireRun(runId) {
+    const s = this.runs.get(runId);
+    if (!s) {
+      throw new Error(`durable-runs: run ${runId} not found (must call startOrResume first)`);
+    }
+    return s;
+  }
+};
+function cloneStep(rec) {
+  if (!rec) return void 0;
+  return { ...rec, error: rec.error ? { ...rec.error } : void 0 };
+}
+
+// src/durable/runner.ts
+var DEFAULT_LEASE_MS4 = 3e4;
+var DEFAULT_AWAIT_POLL_MS = 250;
+async function runDurable(input) {
+  const workerId = input.workerId ?? deriveWorkerId();
+  const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS4;
+  const { completedSteps } = await input.store.startOrResume({
+    runId: input.runId,
+    manifest: input.manifest,
+    workerId,
+    leaseMs
+  });
+  const priorByIndex = /* @__PURE__ */ new Map();
+  for (const s of completedSteps) priorByIndex.set(s.stepIndex, s);
+  const collected = [...completedSteps].sort((a, b) => a.stepIndex - b.stepIndex);
+  let leaseLost = false;
+  const heartbeatIntervalMs = Math.max(1e3, Math.floor(leaseMs / 3));
+  const heartbeat = setInterval(() => {
+    void input.store.renewLease({ runId: input.runId, workerId, leaseMs }).then((res) => {
+      if (!res.ok) leaseLost = true;
+    }).catch(() => {
+      leaseLost = true;
+    });
+  }, heartbeatIntervalMs);
+  if (typeof heartbeat.unref === "function") heartbeat.unref();
+  let positionCounter = 0;
+  const ctx = {
+    runId: input.runId,
+    projectId: input.manifest.projectId,
+    scenarioId: input.manifest.scenarioId,
+    async step(intent, fn, opts) {
+      checkAbortAndLease(input.signal, leaseLost);
+      const stepIndex = positionCounter++;
+      const prior = priorByIndex.get(stepIndex);
+      const inputHash = opts?.inputFingerprint !== void 0 ? canonicalHash(opts.inputFingerprint) : "";
+      if (prior && prior.status === "completed") {
+        if (prior.intent !== intent) {
+          throw new DurableRunDivergenceError(
+            `step ${stepIndex}: intent changed across replays ('${prior.intent}' -> '${intent}')`
+          );
+        }
+        return prior.result;
+      }
+      const begun = await input.store.beginStep({
+        runId: input.runId,
+        stepIndex,
+        intent,
+        kind: opts?.kind ?? "logic",
+        inputHash
+      });
+      try {
+        const result = await fn();
+        const completed = await input.store.completeStep({
+          runId: input.runId,
+          stepIndex,
+          result
+        });
+        upsertCollected(collected, completed);
+        priorByIndex.set(stepIndex, completed);
+        return result;
+      } catch (err) {
+        const failed = await input.store.failStep({
+          runId: input.runId,
+          stepIndex,
+          error: toStepError(err)
+        });
+        upsertCollected(collected, failed);
+        priorByIndex.set(stepIndex, failed);
+        throw err;
+      } finally {
+        void begun;
+      }
+    },
+    async awaitEvent(key, opts) {
+      const stepIndex = positionCounter++;
+      const prior = priorByIndex.get(stepIndex);
+      if (prior && prior.status === "completed") {
+        if (prior.intent !== `event:${key}`) {
+          throw new DurableRunDivergenceError(
+            `step ${stepIndex}: awaitEvent key changed across replays`
+          );
+        }
+        return prior.result;
+      }
+      const beginAt = Date.now();
+      const timeoutMs = opts?.timeoutMs ?? 6e4;
+      const pollMs = opts?.pollMs ?? DEFAULT_AWAIT_POLL_MS;
+      await input.store.beginStep({
+        runId: input.runId,
+        stepIndex,
+        intent: `event:${key}`,
+        kind: "event",
+        inputHash: ""
+      });
+      try {
+        for (; ; ) {
+          checkAbortAndLease(input.signal, leaseLost);
+          const evt = await input.store.loadEvent(input.runId, key);
+          if (evt) {
+            const completed = await input.store.completeStep({
+              runId: input.runId,
+              stepIndex,
+              result: evt.payload
+            });
+            upsertCollected(collected, completed);
+            priorByIndex.set(stepIndex, completed);
+            return evt.payload;
+          }
+          if (Date.now() - beginAt > timeoutMs) {
+            const err = new DurableAwaitEventTimeoutError(
+              `awaitEvent('${key}') timed out after ${timeoutMs}ms`
+            );
+            const failed = await input.store.failStep({
+              runId: input.runId,
+              stepIndex,
+              error: toStepError(err)
+            });
+            upsertCollected(collected, failed);
+            priorByIndex.set(stepIndex, failed);
+            throw err;
+          }
+          await sleep2(pollMs, input.signal);
+        }
+      } catch (err) {
+        if (!(err instanceof DurableAwaitEventTimeoutError)) {
+          const existing = priorByIndex.get(stepIndex);
+          if (!existing || existing.status !== "failed") {
+            const failed = await input.store.failStep({
+              runId: input.runId,
+              stepIndex,
+              error: toStepError(err)
+            });
+            upsertCollected(collected, failed);
+            priorByIndex.set(stepIndex, failed);
+          }
+        }
+        throw err;
+      }
+    },
+    async emitEvent(key, payload) {
+      const res = await input.store.emitEvent({ runId: input.runId, key, payload });
+      return { accepted: res.accepted };
+    },
+    async now() {
+      const v = await this.step(`deterministic:now`, async () => (/* @__PURE__ */ new Date()).toISOString(), {
+        kind: "deterministic"
+      });
+      return new Date(v);
+    },
+    async uuid() {
+      return this.step(`deterministic:uuid`, async () => cryptoRandomUuid(), {
+        kind: "deterministic"
+      });
+    }
+  };
+  try {
+    const result = await input.taskFn(ctx);
+    const finalRecord = await input.store.endRun({
+      runId: input.runId,
+      workerId,
+      status: "completed",
+      outcome: input.defaultOutcome
+    });
+    return { result, record: finalRecord, steps: collected };
+  } catch (err) {
+    const finalRecord = await input.store.endRun({
+      runId: input.runId,
+      workerId,
+      status: "failed",
+      outcome: {
+        ...input.defaultOutcome,
+        notes: err instanceof Error ? err.message : String(err)
+      }
+    });
+    void finalRecord;
+    throw err;
+  } finally {
+    clearInterval(heartbeat);
+  }
+}
+function checkAbortAndLease(signal, leaseLost) {
+  if (signal?.aborted) throw signal.reason ?? new Error("aborted");
+  if (leaseLost) throw new Error("durable-runs: lease lost; another worker has taken over this run");
+}
+function upsertCollected(list, rec) {
+  const i = list.findIndex((s) => s.stepIndex === rec.stepIndex);
+  if (i === -1) list.push(rec);
+  else list[i] = rec;
+}
+function toStepError(err) {
+  if (err instanceof Error) {
+    return {
+      message: err.message,
+      code: err.code,
+      stack: err.stack
+    };
+  }
+  return { message: String(err) };
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function cryptoRandomUuid() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+  bytes[6] = (bytes[6] ?? 0) & 15 | 64;
+  bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+// src/durable/workflows.ts
+async function runOnWorkflowStep(workflowStep, input) {
+  const stepCfg = input.stepConfig;
+  let counter2 = 0;
+  const stepName = (intent) => `${input.workflowName}/${counter2++}:${intent}`;
+  const ctx = {
+    runId: `cf-workflow:${input.workflowName}`,
+    projectId: input.workflowName,
+    async step(intent, fn) {
+      const name = stepName(intent);
+      if (stepCfg) {
+        return workflowStep.do(name, stepCfg, fn);
+      }
+      return workflowStep.do(name, fn);
+    },
+    async awaitEvent(key, opts) {
+      const timeout = opts?.timeoutMs ? `${Math.ceil(opts.timeoutMs / 1e3)}s` : void 0;
+      const ev = await workflowStep.waitForEvent(stepName(`event:${key}`), {
+        type: key,
+        timeout
+      });
+      return ev.payload;
+    },
+    async emitEvent() {
+      throw new Error(
+        "runOnWorkflowStep: ctx.emitEvent is not available inside a Workflows entrypoint. Emit from the sibling worker that drives the workflow."
+      );
+    },
+    async now() {
+      const iso = await this.step("deterministic:now", async () => (/* @__PURE__ */ new Date()).toISOString());
+      return new Date(iso);
+    },
+    async uuid() {
+      return this.step("deterministic:uuid", async () => {
+        if (typeof globalThis.crypto?.randomUUID === "function") {
+          return globalThis.crypto.randomUUID();
+        }
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        bytes[6] = (bytes[6] ?? 0) & 15 | 64;
+        bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+        const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+      });
+    }
+  };
+  return input.taskFn(ctx);
+}
+
 // src/intent-router.ts
 var DEFAULT_PATTERN_WEIGHT = 1.5;
 var DEFAULT_MIN_SCORE = 1;
@@ -1462,8 +2612,8 @@ function createTraceBridge(options) {
   if (!options.runId) {
     throw new ValidationError("createTraceBridge: runId is required");
   }
-  let counter = 0;
-  const newEventId = options.newEventId ?? (() => `evt-${++counter}`);
+  let counter2 = 0;
+  const newEventId = options.newEventId ?? (() => `evt-${++counter2}`);
   const baseSpanId = options.spanId;
   const toTraceEvent = (event) => {
     const projection = projectToTraceEvent(event);
@@ -1640,6 +2790,14 @@ export {
   CaptureIntegrityError,
   ChatTurnError,
   ConfigError,
+  D1DurableRunStore,
+  DurableAwaitEventTimeoutError,
+  DurableRunDivergenceError,
+  DurableRunError,
+  DurableRunInputMismatchError,
+  DurableRunLeaseHeldError,
+  FileSystemDurableRunStore,
+  InMemoryDurableRunStore,
   InMemoryRuntimeSessionStore,
   JudgeError,
   NotFoundError,
@@ -1649,6 +2807,8 @@ export {
   ValidationError,
   VerificationError,
   assertProfileConformance,
+  canonicalHash,
+  canonicalJson,
   classifyIntent,
   composeTurnProfile,
   createIterableBackend,
@@ -1658,17 +2818,22 @@ export {
   createSandboxPromptBackend,
   createTraceBridge,
   decideKnowledgeReadiness,
+  deriveWorkerId,
   encodeServerSentEvent,
+  manifestHash,
   readinessServerSentEvent,
   runAgentTask,
   runAgentTaskStream,
   runChatTurn,
+  runDurable,
+  runOnWorkflowStep,
   runtimeStreamServerSentEvent,
   sandboxAsChatTurnTarget,
   sanitizeAgentRuntimeEvent,
   sanitizeKnowledgeReadinessReport,
   sanitizeRuntimeStreamEvent,
   startRuntimeRun,
+  stepId,
   summarizeAgentTaskRun,
   toAgentEvalTrace
 };