chainlesschain 0.162.177 → 0.162.178

package/src/lib/event-runtime-host.js

@@ -0,0 +1,225 @@
+/**
+ * Process-level lifecycle owner for the durable Event Runtime.
+ *
+ * Producers only append records. This host owns the single non-overlapping
+ * drain loop, dispatches records to registered handlers, and exposes a
+ * stoppable lifecycle shared by short CLI commands and resident daemons.
+ */
+
+import { EventEmitter } from "node:events";
+import { EventRuntimeStore } from "./event-runtime-store.js";
+import { EventRuntimeWorker } from "./event-runtime-worker.js";
+
+function routeType(event) {
+  return String(
+    event?.runtime_type ||
+      event?.runtimeType ||
+      event?.event ||
+      event?.type ||
+      "*",
+  );
+}
+
+function routeOrigin(event) {
+  return String(event?.origin || "*");
+}
+
+function routeKey(queue, type = "*", origin = "*") {
+  return `${queue}:${String(type || "*")}:${String(origin || "*")}`;
+}
+
+export class EventRuntimeHost extends EventEmitter {
+  constructor({
+    store = new EventRuntimeStore(),
+    intervalMs = 1000,
+    worker = null,
+    setTimeoutFn = setTimeout,
+    clearTimeoutFn = clearTimeout,
+  } = {}) {
+    super();
+    this.store = store;
+    this.intervalMs = Math.max(1, Number(intervalMs) || 1000);
+    this.setTimeoutFn = setTimeoutFn;
+    this.clearTimeoutFn = clearTimeoutFn;
+    this.handlers = new Map();
+    this.running = false;
+    this.timer = null;
+    this.inFlight = null;
+    this.lastStats = null;
+    this.lastError = null;
+    this.worker =
+      worker ||
+      new EventRuntimeWorker({
+        store,
+        onInbox: (event, record) =>
+          this._dispatch("inbox", event, record),
+        onOutbox: (event, record) =>
+          this._dispatch("outbox", event, record),
+      });
+  }
+
+  registerHandler(
+    handler,
+    { queue = "inbox", type = "*", origin = "*" } = {},
+  ) {
+    if (typeof handler !== "function") {
+      throw new TypeError("Event Runtime handler must be a function");
+    }
+    if (queue !== "inbox" && queue !== "outbox") {
+      throw new Error(`unsupported event queue: ${queue}`);
+    }
+    const key = routeKey(queue, type, origin);
+    const handlers = this.handlers.get(key) || new Set();
+    handlers.add(handler);
+    this.handlers.set(key, handlers);
+    return () => {
+      handlers.delete(handler);
+      if (handlers.size === 0) this.handlers.delete(key);
+    };
+  }
+
+  async _dispatch(queue, event, record) {
+    const type = routeType(event);
+    const origin = routeOrigin(event);
+    const candidates = [
+      routeKey(queue, type, origin),
+      routeKey(queue, type, "*"),
+      routeKey(queue, "*", origin),
+      routeKey(queue, "*", "*"),
+    ];
+    const handlers = [];
+    const seen = new Set();
+    for (const key of candidates) {
+      for (const handler of this.handlers.get(key) || []) {
+        if (seen.has(handler)) continue;
+        seen.add(handler);
+        handlers.push(handler);
+      }
+    }
+    if (handlers.length === 0 && event?.requiresHandler === true) {
+      const error = new Error(
+        `No Event Runtime handler for ${queue}:${type}:${origin}`,
+      );
+      error.code = "CC_EVENT_RUNTIME_HANDLER_UNAVAILABLE";
+      throw error;
+    }
+    const results = await Promise.all(
+      handlers.map((handler) => handler(event, record)),
+    );
+    const delivery = {
+      queue,
+      type,
+      origin,
+      handlerCount: handlers.length,
+      results,
+    };
+    this.emit("delivered", delivery, event, record);
+    this.emit(`${queue}:${type}`, event, record, delivery);
+    return delivery;
+  }
+
+  async runOnce() {
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = Promise.resolve()
+      .then(() => this.worker.runOnce())
+      .then((stats) => {
+        this.lastStats = stats;
+        this.lastError = null;
+        this.emit("tick", stats);
+        return stats;
+      })
+      .catch((error) => {
+        this.lastError = error;
+        this.emit("runtime-error", error);
+        throw error;
+      })
+      .finally(() => {
+        this.inFlight = null;
+      });
+    return this.inFlight;
+  }
+
+  _schedule() {
+    if (!this.running || this.timer != null) return;
+    this.timer = this.setTimeoutFn(async () => {
+      this.timer = null;
+      try {
+        await this.runOnce();
+      } catch {
+        // The durable records remain pending/retriable. The host keeps running
+        // so a transient lock or filesystem failure does not kill the daemon.
+      } finally {
+        this._schedule();
+      }
+    }, this.intervalMs);
+    this.timer?.unref?.();
+  }
+
+  start({ immediate = true } = {}) {
+    if (this.running) return false;
+    this.running = true;
+    if (immediate) {
+      void this.runOnce()
+        .catch(() => {})
+        .finally(() => this._schedule());
+    } else {
+      this._schedule();
+    }
+    this.emit("started");
+    return true;
+  }
+
+  async stop({ drain = true } = {}) {
+    const wasRunning = this.running;
+    this.running = false;
+    if (this.timer != null) {
+      this.clearTimeoutFn(this.timer);
+      this.timer = null;
+    }
+    if (drain && this.inFlight) {
+      try {
+        await this.inFlight;
+      } catch {
+        // Error already exposed through runtime-error/lastError.
+      }
+    }
+    if (wasRunning) this.emit("stopped");
+    return wasRunning;
+  }
+
+  status() {
+    return {
+      running: this.running,
+      inFlight: this.inFlight != null,
+      handlerRoutes: this.handlers.size,
+      lastStats: this.lastStats,
+      lastError: this.lastError?.message || null,
+      health: this.store.getHealthSnapshot(),
+    };
+  }
+}
+
+let defaultHost = null;
+
+export function getDefaultEventRuntimeHost(options = {}) {
+  if (!defaultHost) defaultHost = new EventRuntimeHost(options);
+  return defaultHost;
+}
+
+export function startDefaultEventRuntimeHost(options = {}) {
+  if (process.env.CC_EVENT_RUNTIME_DURABLE !== "1" && options.force !== true) {
+    return null;
+  }
+  const host = getDefaultEventRuntimeHost(options);
+  host.start({ immediate: options.immediate !== false });
+  return host;
+}
+
+export async function stopDefaultEventRuntimeHost(options) {
+  return defaultHost ? defaultHost.stop(options) : false;
+}
+
+export function _resetDefaultEventRuntimeHostForTests() {
+  defaultHost = null;
+}
+

package/src/lib/event-runtime-store.js

@@ -100,7 +100,17 @@ export class EventRuntimeStore {
     );
   }
 
-  enqueue(queue, event, { id = null, metadata = null } = {}) {
+  enqueue(
+    queue,
+    event,
+    {
+      id = null,
+      metadata = null,
+      claimOwner = null,
+      leaseMs = this.leaseMs,
+      availableAt = null,
+    } = {},
+  ) {
     const key = eventId(event, id);
     return this._mutate(queue, (records) => {
       const existing = records.find((record) => record.id === key);
@@ -118,15 +128,27 @@ export class EventRuntimeStore {
         error.code = "CC_EVENT_RUNTIME_BACKPRESSURE";
         throw error;
       }
+      const createdAt = this._now();
+      const claimed = claimOwner != null && String(claimOwner);
       const record = {
         id: key,
         event: clone(event || {}),
         metadata: clone(metadata),
-        status: "pending",
-        attempts: 0,
-        createdAt: this._now(),
-        nextAttemptAt: this._now(),
-        lease: null,
+        status: claimed ? "processing" : "pending",
+        attempts: claimed ? 1 : 0,
+        fence: claimed ? 1 : 0,
+        createdAt,
+        nextAttemptAt:
+          availableAt == null ? createdAt : Math.max(createdAt, Number(availableAt)),
+        lease: claimed
+          ? {
+              owner: String(claimOwner),
+              fence: 1,
+              claimedAt: createdAt,
+              expiresAt:
+                createdAt + Math.max(1, Number(leaseMs) || this.leaseMs),
+            }
+          : null,
       };
       records.push(record);
       return clone(record);
@@ -160,7 +182,13 @@ export class EventRuntimeStore {
         if (Number(record.nextAttemptAt || 0) > t) continue;
         record.status = "processing";
         record.attempts = Number(record.attempts || 0) + 1;
-        record.lease = { owner: this.owner, claimedAt: t, expiresAt: t + ttl };
+        record.fence = Number(record.fence || 0) + 1;
+        record.lease = {
+          owner: this.owner,
+          fence: record.fence,
+          claimedAt: t,
+          expiresAt: t + ttl,
+        };
         claimed.push(clone(record));
       }
       return claimed;
@@ -175,16 +203,68 @@ export class EventRuntimeStore {
     return this.claim("outbox", options);
   }
 
-  acknowledge(queue, id, result = null, { owner = null } = {}) {
+  _leaseMatches(record, { owner = null, fence = null, now = this._now() } = {}) {
+    const expectedOwner = owner == null ? null : String(owner);
+    const expectedFence =
+      fence == null || !Number.isFinite(Number(fence)) ? null : Number(fence);
+    if (expectedOwner == null && expectedFence == null) return true;
+    if (record.status !== "processing" || !record.lease) return false;
+    if (expectedOwner != null && record.lease.owner !== expectedOwner) {
+      return false;
+    }
+    if (
+      expectedFence != null &&
+      Number(record.lease.fence) !== expectedFence
+    ) {
+      return false;
+    }
+    // A holder that let its lease expire must renew before it is allowed to
+    // commit. This closes the gap where a slow worker could settle just before
+    // a recovery worker claims the same record.
+    return Number(record.lease.expiresAt) > Number(now);
+  }
+
+  renew(
+    queue,
+    id,
+    {
+      owner = this.owner,
+      fence = null,
+      now = this._now(),
+      leaseMs = this.leaseMs,
+    } = {},
+  ) {
+    const t = Number(now);
+    const ttl = Math.max(1, Number(leaseMs) || this.leaseMs);
+    return this._mutate(queue, (records) => {
+      const record = records.find((item) => item.id === String(id));
+      if (!record || !this._leaseMatches(record, { owner, fence, now: t })) {
+        return null;
+      }
+      record.lease.expiresAt = t + ttl;
+      record.lease.renewedAt = t;
+      return clone(record);
+    });
+  }
+
+  renewInbox(id, options) {
+    return this.renew("inbox", id, options);
+  }
+
+  renewOutbox(id, options) {
+    return this.renew("outbox", id, options);
+  }
+
+  acknowledge(
+    queue,
+    id,
+    result = null,
+    { owner = null, fence = null, now = this._now() } = {},
+  ) {
     return this._mutate(queue, (records) => {
       const record = records.find((item) => item.id === String(id));
       if (!record) return null;
-      const expectedOwner = owner ? String(owner) : null;
-      if (
-        expectedOwner &&
-        (record.status !== "processing" ||
-          record.lease?.owner !== expectedOwner)
-      ) {
+      if (!this._leaseMatches(record, { owner, fence, now })) {
         return null;
       }
       record.status = "done";
@@ -207,17 +287,18 @@ export class EventRuntimeStore {
     queue,
     id,
     error,
-    { retryDelayMs = 1000, maxAttempts = this.maxAttempts, owner = null } = {},
+    {
+      retryDelayMs = 1000,
+      maxAttempts = this.maxAttempts,
+      owner = null,
+      fence = null,
+      now = this._now(),
+    } = {},
   ) {
     return this._mutate(queue, (records) => {
       const record = records.find((item) => item.id === String(id));
       if (!record) return null;
-      const expectedOwner = owner ? String(owner) : null;
-      if (
-        expectedOwner &&
-        (record.status !== "processing" ||
-          record.lease?.owner !== expectedOwner)
-      ) {
+      if (!this._leaseMatches(record, { owner, fence, now })) {
         return null;
       }
       record.error = String(error || "event delivery failed").slice(0, 1000);

package/src/lib/event-runtime-worker.js

@@ -16,6 +16,9 @@ export class EventRuntimeWorker {
     sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     batchSize = 50,
     retryDelayMs = 1000,
+    leaseRenewIntervalMs = null,
+    setIntervalFn = setInterval,
+    clearIntervalFn = clearInterval,
   } = {}) {
     if (!store) throw new Error("EventRuntimeWorker requires a store");
     this.store = store;
@@ -25,6 +28,60 @@ export class EventRuntimeWorker {
     this.sleep = sleep;
     this.batchSize = Math.max(1, Number(batchSize) || 50);
     this.retryDelayMs = Math.max(0, Number(retryDelayMs) || 0);
+    const inferredRenewMs = Math.max(
+      1,
+      Math.floor(Number(store.leaseMs || 120000) / 3),
+    );
+    this.leaseRenewIntervalMs =
+      leaseRenewIntervalMs == null
+        ? inferredRenewMs
+        : Math.max(0, Number(leaseRenewIntervalMs) || 0);
+    this.setIntervalFn = setIntervalFn;
+    this.clearIntervalFn = clearIntervalFn;
+  }
+
+  _settlementOptions(record) {
+    if (!record?.lease?.owner) return {};
+    return {
+      owner: record.lease.owner,
+      ...(record.lease.fence == null ? {} : { fence: record.lease.fence }),
+    };
+  }
+
+  _startLeaseRenewal(queue, record) {
+    const renew =
+      queue === "inbox" ? this.store.renewInbox : this.store.renewOutbox;
+    if (
+      typeof renew !== "function" ||
+      !record?.lease?.owner ||
+      this.leaseRenewIntervalMs <= 0
+    ) {
+      return { lost: false, stop() {} };
+    }
+    const options = this._settlementOptions(record);
+    const state = { lost: false, timer: null };
+    const tick = () => {
+      if (state.lost) return;
+      try {
+        const renewed = renew.call(this.store, record.id, options);
+        if (renewed == null) state.lost = true;
+      } catch {
+        // Renewal is part of the correctness boundary. A lock/storage failure
+        // means this worker can no longer prove it owns the record.
+        state.lost = true;
+      }
+    };
+    state.timer = this.setIntervalFn(tick, this.leaseRenewIntervalMs);
+    state.timer?.unref?.();
+    return {
+      get lost() {
+        return state.lost;
+      },
+      stop: () => {
+        if (state.timer != null) this.clearIntervalFn(state.timer);
+        state.timer = null;
+      },
+    };
   }
 
   async _drain(queue, handler, stats) {
@@ -33,9 +90,15 @@ export class EventRuntimeWorker {
         ? this.store.claimInbox({ limit: this.batchSize, now: this.now() })
         : this.store.claimOutbox({ limit: this.batchSize, now: this.now() });
     for (const record of claimed) {
+      const renewal = this._startLeaseRenewal(queue, record);
       try {
         const result = await handler(record.event, record);
-        const options = { owner: record.lease?.owner };
+        renewal.stop();
+        if (renewal.lost) {
+          stats[`${queue}LeaseLost`] += 1;
+          continue;
+        }
+        const options = this._settlementOptions(record);
         const settled =
           queue === "inbox"
             ? this.store.acknowledgeInbox(record.id, result, options)
@@ -43,9 +106,14 @@ export class EventRuntimeWorker {
         if (settled === null && options.owner) stats[`${queue}LeaseLost`] += 1;
         else stats[`${queue}Acked`] += 1;
       } catch (error) {
+        renewal.stop();
+        if (renewal.lost) {
+          stats[`${queue}LeaseLost`] += 1;
+          continue;
+        }
         const options = {
           retryDelayMs: this.retryDelayMs,
-          owner: record.lease?.owner,
+          ...this._settlementOptions(record),
         };
         const settled = this.store.fail(
           queue,

package/src/lib/hooks-v2-producers.js

@@ -3,13 +3,38 @@
  * Hook failures never change the surrounding agent or interaction result.
  */
 export function emitHooksV2Event(eventName, context = {}, options = {}) {
-  void import("./hooks-v2-runtime.js")
-    .then(({ default: runtime }) => {
-      if (!runtime || typeof runtime.executeHooks !== "function") return;
-      return runtime.executeHooks(eventName, context, options);
-    })
-    .catch(() => {
-      // Hooks are an optional extension; producer delivery is best-effort.
-    });
+  void executeHooksV2Event(eventName, context, options);
 }
 
+/**
+ * Decision-capable producer bridge. Callers at a real gate (PreToolUse,
+ * Setup, prompt expansion) await this result; observer producers can keep
+ * using emitHooksV2Event().
+ */
+export async function executeHooksV2Event(
+  eventName,
+  context = {},
+  options = {},
+) {
+  try {
+    const { default: runtime } = await import("./hooks-v2-runtime.js");
+    if (!runtime || typeof runtime.executeHooks !== "function") {
+      return {
+        success: options.failClosed !== true,
+        blocked: options.failClosed === true,
+        decision: options.failClosed === true ? "block" : "continue",
+        unavailable: true,
+        results: [],
+      };
+    }
+    return await runtime.executeHooks(eventName, context, options);
+  } catch (error) {
+    return {
+      success: options.failClosed !== true,
+      blocked: options.failClosed === true,
+      decision: options.failClosed === true ? "block" : "continue",
+      error: error?.message || String(error),
+      results: [],
+    };
+  }
+}