chainlesschain 0.162.174 → 0.162.176

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

@@ -0,0 +1,354 @@
+/**
+ * Durable Event Runtime inbox/outbox.
+ *
+ * The in-memory EventEmitter is intentionally kept as the fast path. This
+ * store is the crash-safe boundary for producers that need delivery across a
+ * process restart: every record has a deterministic event id, a bounded
+ * attempt count, and a renewable-style execution lease. State is rewritten
+ * atomically under a directory lock so two daemon processes cannot claim the
+ * same event.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { withFileLock } from "./with-file-lock.js";
+
+const QUEUES = new Set(["inbox", "outbox"]);
+
+function defaultDir() {
+  return path.join(os.homedir(), ".chainlesschain", "event-runtime");
+}
+
+function eventId(event, explicitId = null) {
+  if (explicitId != null && String(explicitId)) return String(explicitId);
+  const supplied = event?.event_id || event?.eventId || event?.id;
+  if (supplied != null && String(supplied)) return String(supplied);
+  const digest = createHash("sha256")
+    .update(JSON.stringify(event || {}))
+    .digest("hex")
+    .slice(0, 32);
+  return `evt_${digest}`;
+}
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+export class EventRuntimeStore {
+  constructor({
+    dir = defaultDir(),
+    now = () => Date.now(),
+    owner = `${process.pid}:${randomUUID()}`,
+    maxAttempts = 5,
+    leaseMs = 120000,
+    lockTimeoutMs = 2000,
+    maxQueueLength = 10000,
+  } = {}) {
+    this.dir = dir;
+    this._now = typeof now === "function" ? now : () => Number(now);
+    this.owner = String(owner);
+    this.maxAttempts = Math.max(1, Number(maxAttempts) || 5);
+    this.leaseMs = Math.max(1, Number(leaseMs) || 120000);
+    this.lockTimeoutMs = Math.max(0, Number(lockTimeoutMs) || 2000);
+    this.maxQueueLength = Math.max(1, Number(maxQueueLength) || 10000);
+  }
+
+  _assertQueue(queue) {
+    if (!QUEUES.has(queue)) throw new Error(`Unknown event queue: ${queue}`);
+  }
+
+  _file(queue) {
+    this._assertQueue(queue);
+    return path.join(this.dir, `${queue}.json`);
+  }
+
+  _ensureDir() {
+    fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+  }
+
+  _read(queue) {
+    const file = this._file(queue);
+    try {
+      const value = JSON.parse(fs.readFileSync(file, "utf8"));
+      return Array.isArray(value) ? value : [];
+    } catch {
+      return [];
+    }
+  }
+
+  _write(queue, records) {
+    this._ensureDir();
+    const file = this._file(queue);
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(records, null, 2), "utf8");
+    fs.renameSync(tmp, file);
+  }
+
+  _mutate(queue, fn) {
+    this._ensureDir();
+    return withFileLock(
+      path.join(this.dir, ".event-runtime"),
+      () => {
+        const records = this._read(queue);
+        const result = fn(records);
+        this._write(queue, records);
+        return result;
+      },
+      { timeoutMs: this.lockTimeoutMs, failIfUnavailable: true },
+    );
+  }
+
+  enqueue(queue, event, { id = null, metadata = null } = {}) {
+    const key = eventId(event, id);
+    return this._mutate(queue, (records) => {
+      const existing = records.find((record) => record.id === key);
+      if (existing) return { ...clone(existing), duplicate: true };
+      const active = records.reduce(
+        (count, record) =>
+          count +
+          (record.status === "done" || record.status === "dead" ? 0 : 1),
+        0,
+      );
+      if (active >= this.maxQueueLength) {
+        const error = new Error(
+          `Event Runtime ${queue} queue is full (${this.maxQueueLength})`,
+        );
+        error.code = "CC_EVENT_RUNTIME_BACKPRESSURE";
+        throw error;
+      }
+      const record = {
+        id: key,
+        event: clone(event || {}),
+        metadata: clone(metadata),
+        status: "pending",
+        attempts: 0,
+        createdAt: this._now(),
+        nextAttemptAt: this._now(),
+        lease: null,
+      };
+      records.push(record);
+      return clone(record);
+    });
+  }
+
+  enqueueInbox(event, options) {
+    return this.enqueue("inbox", event, options);
+  }
+
+  enqueueOutbox(event, options) {
+    return this.enqueue("outbox", event, options);
+  }
+
+  /** Requeue abandoned claims and return claimable records for this owner. */
+  claim(queue, { limit = 50, now = this._now(), leaseMs = this.leaseMs } = {}) {
+    const t = Number(now);
+    const ttl = Math.max(1, Number(leaseMs) || this.leaseMs);
+    const max = Math.max(1, Number(limit) || 50);
+    return this._mutate(queue, (records) => {
+      const claimed = [];
+      for (const record of records) {
+        if (
+          record.status === "processing" &&
+          Number(record.lease?.expiresAt) <= t
+        ) {
+          record.status = "pending";
+          record.lease = null;
+        }
+        if (claimed.length >= max || record.status !== "pending") continue;
+        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 };
+        claimed.push(clone(record));
+      }
+      return claimed;
+    });
+  }
+
+  claimInbox(options) {
+    return this.claim("inbox", options);
+  }
+
+  claimOutbox(options) {
+    return this.claim("outbox", options);
+  }
+
+  acknowledge(queue, id, result = null, { owner = null } = {}) {
+    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)
+      ) {
+        return null;
+      }
+      record.status = "done";
+      record.result = clone(result);
+      record.completedAt = this._now();
+      record.lease = null;
+      return clone(record);
+    });
+  }
+
+  acknowledgeInbox(id, result, options) {
+    return this.acknowledge("inbox", id, result, options);
+  }
+
+  acknowledgeOutbox(id, result, options) {
+    return this.acknowledge("outbox", id, result, options);
+  }
+
+  fail(
+    queue,
+    id,
+    error,
+    { retryDelayMs = 1000, maxAttempts = this.maxAttempts, owner = null } = {},
+  ) {
+    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)
+      ) {
+        return null;
+      }
+      record.error = String(error || "event delivery failed").slice(0, 1000);
+      record.lease = null;
+      if (
+        Number(record.attempts || 0) >=
+        Math.max(1, Number(maxAttempts) || this.maxAttempts)
+      ) {
+        record.status = "dead";
+        record.deadAt = this._now();
+      } else {
+        record.status = "pending";
+        record.nextAttemptAt =
+          this._now() + Math.max(0, Number(retryDelayMs) || 0);
+      }
+      return clone(record);
+    });
+  }
+
+  list(queue, { status = null } = {}) {
+    return this._read(queue)
+      .filter((record) => !status || record.status === status)
+      .map(clone);
+  }
+
+  listInbox(options) {
+    return this.list("inbox", options);
+  }
+
+  listOutbox(options) {
+    return this.list("outbox", options);
+  }
+
+  /**
+   * Return a lock-consistent, cross-process health snapshot without claiming
+   * work. Queue capacity is measured from active records because completed and
+   * dead-letter records do not participate in producer backpressure.
+   */
+  getHealthSnapshot({ now = this._now(), highWatermarkRatio = 0.8 } = {}) {
+    const t = Number(now);
+    const highWatermark = Math.min(
+      1,
+      Math.max(0, Number(highWatermarkRatio) || 0.8),
+    );
+    this._ensureDir();
+    return withFileLock(
+      path.join(this.dir, ".event-runtime"),
+      () => {
+        const queues = {};
+        for (const queue of QUEUES) {
+          const records = this._read(queue);
+          const summary = {
+            total: records.length,
+            active: 0,
+            pending: 0,
+            processing: 0,
+            done: 0,
+            dead: 0,
+            unknown: 0,
+            claimable: 0,
+            delayed: 0,
+            expiredLeases: 0,
+            oldestActiveAgeMs: null,
+            availableCapacity: this.maxQueueLength,
+            utilization: 0,
+            pressure: "normal",
+          };
+          let oldestActiveAt = null;
+          for (const record of records) {
+            const status = String(record.status || "unknown");
+            if (["pending", "processing", "done", "dead"].includes(status)) {
+              summary[status] += 1;
+            } else summary.unknown += 1;
+            const active = status !== "done" && status !== "dead";
+            if (active) {
+              summary.active += 1;
+              const createdAt = Number(record.createdAt);
+              if (
+                Number.isFinite(createdAt) &&
+                (oldestActiveAt == null || createdAt < oldestActiveAt)
+              ) {
+                oldestActiveAt = createdAt;
+              }
+            }
+            if (status === "pending") {
+              if (Number(record.nextAttemptAt || 0) <= t)
+                summary.claimable += 1;
+              else summary.delayed += 1;
+            } else if (
+              status === "processing" &&
+              Number(record.lease?.expiresAt) <= t
+            ) {
+              summary.expiredLeases += 1;
+            }
+          }
+          summary.availableCapacity = Math.max(
+            0,
+            this.maxQueueLength - summary.active,
+          );
+          summary.utilization = Number(
+            (summary.active / this.maxQueueLength).toFixed(4),
+          );
+          summary.pressure =
+            summary.active >= this.maxQueueLength
+              ? "full"
+              : summary.utilization >= highWatermark
+                ? "high"
+                : "normal";
+          summary.oldestActiveAgeMs =
+            oldestActiveAt == null ? null : Math.max(0, t - oldestActiveAt);
+          queues[queue] = summary;
+        }
+        const pressure = Object.values(queues).some(
+          (queue) => queue.pressure === "full",
+        )
+          ? "full"
+          : Object.values(queues).some((queue) => queue.pressure === "high")
+            ? "high"
+            : "normal";
+        return {
+          schema: "chainlesschain.event-runtime-health.v1",
+          observedAt: new Date(t).toISOString(),
+          queueLimit: this.maxQueueLength,
+          highWatermarkRatio: highWatermark,
+          pressure,
+          queues,
+        };
+      },
+      { timeoutMs: this.lockTimeoutMs, failIfUnavailable: true },
+    );
+  }
+}
+
+export { eventId };

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

@@ -0,0 +1,109 @@
+/**
+ * Recoverable consumer for EventRuntimeStore.
+ *
+ * Handlers are injected because inbox events and outbox deliveries have
+ * different side effects in different hosts (Hooks, Agenda, WebSocket, CI).
+ * The worker owns only claim/ack/retry semantics and never invents an
+ * authority policy for the event payload.
+ */
+
+export class EventRuntimeWorker {
+  constructor({
+    store,
+    onInbox = async () => {},
+    onOutbox = async () => {},
+    now = () => Date.now(),
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    batchSize = 50,
+    retryDelayMs = 1000,
+  } = {}) {
+    if (!store) throw new Error("EventRuntimeWorker requires a store");
+    this.store = store;
+    this.onInbox = onInbox;
+    this.onOutbox = onOutbox;
+    this.now = now;
+    this.sleep = sleep;
+    this.batchSize = Math.max(1, Number(batchSize) || 50);
+    this.retryDelayMs = Math.max(0, Number(retryDelayMs) || 0);
+  }
+
+  async _drain(queue, handler, stats) {
+    const claimed =
+      queue === "inbox"
+        ? this.store.claimInbox({ limit: this.batchSize, now: this.now() })
+        : this.store.claimOutbox({ limit: this.batchSize, now: this.now() });
+    for (const record of claimed) {
+      try {
+        const result = await handler(record.event, record);
+        const options = { owner: record.lease?.owner };
+        const settled =
+          queue === "inbox"
+            ? this.store.acknowledgeInbox(record.id, result, options)
+            : this.store.acknowledgeOutbox(record.id, result, options);
+        if (settled === null && options.owner) stats[`${queue}LeaseLost`] += 1;
+        else stats[`${queue}Acked`] += 1;
+      } catch (error) {
+        const options = {
+          retryDelayMs: this.retryDelayMs,
+          owner: record.lease?.owner,
+        };
+        const settled = this.store.fail(
+          queue,
+          record.id,
+          error?.message || error,
+          options,
+        );
+        if (settled === null && options.owner) stats[`${queue}LeaseLost`] += 1;
+        else stats[`${queue}Failed`] += 1;
+      }
+    }
+    stats[`${queue}Claimed`] += claimed.length;
+  }
+
+  async runOnce() {
+    const stats = {
+      inboxClaimed: 0,
+      inboxAcked: 0,
+      inboxFailed: 0,
+      inboxLeaseLost: 0,
+      outboxClaimed: 0,
+      outboxAcked: 0,
+      outboxFailed: 0,
+      outboxLeaseLost: 0,
+    };
+    await this._drain("inbox", this.onInbox, stats);
+    await this._drain("outbox", this.onOutbox, stats);
+    return stats;
+  }
+
+  async run({ intervalMs = 1000, signal = null, maxTicks = null } = {}) {
+    let stopped = Boolean(signal?.aborted);
+    let ticks = 0;
+    const stop = () => {
+      stopped = true;
+    };
+    signal?.addEventListener?.("abort", stop, { once: true });
+    const totals = {
+      inboxClaimed: 0,
+      inboxAcked: 0,
+      inboxFailed: 0,
+      inboxLeaseLost: 0,
+      outboxClaimed: 0,
+      outboxAcked: 0,
+      outboxFailed: 0,
+      outboxLeaseLost: 0,
+    };
+    try {
+      while (!stopped) {
+        const stats = await this.runOnce();
+        for (const key of Object.keys(totals)) totals[key] += stats[key];
+        ticks += 1;
+        if (Number.isFinite(maxTicks) && ticks >= maxTicks) break;
+        await this.sleep(Math.max(0, Number(intervalMs) || 0));
+      }
+    } finally {
+      signal?.removeEventListener?.("abort", stop);
+    }
+    return { ticks, ...totals };
+  }
+}

package/src/lib/execution-backend.js

@@ -10,14 +10,34 @@
  * @module execution-backend
  */
 
-import { execSync } from "node:child_process";
+import executionBroker from "./process-execution-broker/index.js";
 
 // ─── Exported for test injection ────────────────────────────────────
 
 export const _deps = {
-  execSync,
+  execSync: (...args) => executionBroker.execSync(...args),
+  spawnSync: (...args) => executionBroker.spawnSync(...args),
 };
 
+function execArgv(command, args, options) {
+  const result = _deps.spawnSync(command, args, options);
+  if (result?.error) {
+    result.error.status ??= result.status ?? 1;
+    result.error.stdout ??= result.stdout;
+    result.error.stderr ??= result.stderr;
+    throw result.error;
+  }
+  if (!result || result.status !== 0) {
+    const status = result?.status ?? 1;
+    const error = new Error(`${command} exited with status ${status}`);
+    error.status = status;
+    error.stdout = result?.stdout;
+    error.stderr = result?.stderr;
+    throw error;
+  }
+  return result?.stdout || "";
+}
+
 // ─── Base class ─────────────────────────────────────────────────────
 
 export class ExecutionBackend {
@@ -60,6 +80,9 @@ export class LocalBackend extends ExecutionBackend {
 
     try {
       const stdout = _deps.execSync(command, {
+        origin: "execution-backend:local",
+        scope: "execution-backend",
+        policy: "allow",
         cwd,
         encoding: "utf8",
         timeout,
@@ -106,14 +129,32 @@ export class DockerBackend extends ExecutionBackend {
     const maxBuffer = opts.maxBuffer || 1024 * 1024;
     const cwd = opts.cwd || this.workdir;
 
-    let dockerCmd;
+    let dockerArgs;
     if (this.container) {
       // Exec into existing container
-      dockerCmd = `docker exec -w "${cwd}" ${this.container} ${this.shell} -c "${this._escapeCommand(command)}"`;
+      dockerArgs = [
+        "exec",
+        "-w",
+        cwd,
+        this.container,
+        this.shell,
+        "-c",
+        command,
+      ];
     } else if (this.image) {
       // Run ephemeral container
-      const volumeArgs = this.volumes.map((v) => `-v "${v}"`).join(" ");
-      dockerCmd = `docker run --rm -w "${cwd}" ${volumeArgs} ${this.image} ${this.shell} -c "${this._escapeCommand(command)}"`;
+      const volumeArgs = this.volumes.flatMap((volume) => ["-v", volume]);
+      dockerArgs = [
+        "run",
+        "--rm",
+        "-w",
+        cwd,
+        ...volumeArgs,
+        this.image,
+        this.shell,
+        "-c",
+        command,
+      ];
     } else {
       return {
         stdout: "",
@@ -123,7 +164,11 @@ export class DockerBackend extends ExecutionBackend {
     }
 
     try {
-      const stdout = _deps.execSync(dockerCmd, {
+      const stdout = execArgv("docker", dockerArgs, {
+        origin: "execution-backend:docker",
+        scope: "execution-backend",
+        policy: "allow",
+        shell: false,
         encoding: "utf8",
         timeout,
         maxBuffer,
@@ -138,10 +183,6 @@ export class DockerBackend extends ExecutionBackend {
     }
   }
 
-  _escapeCommand(cmd) {
-    return cmd.replace(/"/g, '\\"');
-  }
-
   describe() {
     if (this.container) return `docker exec (container: ${this.container})`;
     return `docker run (image: ${this.image})`;
@@ -183,14 +224,24 @@ export class SSHBackend extends ExecutionBackend {
     }
 
     const userHost = this.user ? `${this.user}@${this.host}` : this.host;
-    const keyArg = this.key ? `-i "${this.key}"` : "";
-    const portArg = this.port !== 22 ? `-p ${this.port}` : "";
-    const remoteCmd = `cd "${cwd}" && ${command}`;
-
-    const sshCmd = `ssh ${keyArg} ${portArg} -o StrictHostKeyChecking=no -o ConnectTimeout=10 ${userHost} "${this._escapeCommand(remoteCmd)}"`;
+    const sshArgs = [];
+    if (this.key) sshArgs.push("-i", this.key);
+    if (this.port !== 22) sshArgs.push("-p", String(this.port));
+    sshArgs.push(
+      "-o",
+      "StrictHostKeyChecking=no",
+      "-o",
+      "ConnectTimeout=10",
+      userHost,
+      `cd ${quotePosixShellArg(cwd)} && ${command}`,
+    );
 
     try {
-      const stdout = _deps.execSync(sshCmd, {
+      const stdout = execArgv("ssh", sshArgs, {
+        origin: "execution-backend:ssh",
+        scope: "execution-backend",
+        policy: "allow",
+        shell: false,
         encoding: "utf8",
         timeout,
         maxBuffer,
@@ -205,16 +256,16 @@ export class SSHBackend extends ExecutionBackend {
     }
   }
 
-  _escapeCommand(cmd) {
-    return cmd.replace(/"/g, '\\"');
-  }
-
   describe() {
     const userHost = this.user ? `${this.user}@${this.host}` : this.host;
     return `ssh (${userHost}:${this.port})`;
   }
 }
 
+function quotePosixShellArg(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
 // ─── Factory ────────────────────────────────────────────────────────
 
 /**

package/src/lib/git-integration.js

@@ -2,9 +2,14 @@
  * Git integration — wraps system git commands for knowledge base versioning.
  */
 
-import { execSync, spawnSync } from "child_process";
 import { existsSync, writeFileSync, chmodSync } from "fs";
 import { join } from "path";
+import { executionBroker } from "./process-execution-broker/index.js";
+
+export const _deps = {
+  execSync: (...args) => executionBroker.execSync(...args),
+  spawnSync: (...args) => executionBroker.spawnSync(...args),
+};
 
 /**
  * Check if a directory is a git repository.
@@ -80,12 +85,16 @@ export function assertSafeGitPath(p, label = "file path") {
  * @returns {string} trimmed stdout
  */
 export function gitExecArgs(args, cwd, opts = {}) {
-  const res = spawnSync("git", args, {
+  const res = _deps.spawnSync("git", args, {
     cwd,
     encoding: "utf-8",
     windowsHide: true,
     maxBuffer: 64 * 1024 * 1024,
     input: opts.input,
+    origin: "git-integration:argv",
+    policy: "allow",
+    scope: "git",
+    shell: false,
   });
   if (res.error) throw res.error;
   if (res.status !== 0) {
@@ -102,7 +111,7 @@ export function gitExecArgs(args, cwd, opts = {}) {
  */
 export function gitExec(args, cwd) {
   try {
-    return execSync(`git ${args}`, {
+    return _deps.execSync(`git ${args}`, {
       cwd,
       encoding: "utf-8",
       // git diff/log/worktree-list output on a large repo easily exceeds
@@ -111,6 +120,9 @@ export function gitExec(args, cwd) {
       // pass, which isn't wrapped in a degrade-gracefully try/catch).
       maxBuffer: 64 * 1024 * 1024,
       stdio: ["pipe", "pipe", "pipe"],
+      origin: "git-integration:shell",
+      policy: "allow",
+      scope: "git",
     }).trim();
   } catch (err) {
     const stderr = err.stderr ? err.stderr.toString("utf-8").trim() : "";
@@ -138,10 +150,13 @@ export function gitStatus(dir) {
   }
 
   // Use execSync directly to preserve leading whitespace in porcelain format
-  const output = execSync("git status --porcelain", {
+  const output = _deps.execSync("git status --porcelain", {
     cwd: dir,
     encoding: "utf-8",
     stdio: ["pipe", "pipe", "pipe"],
+    origin: "git-integration:shell",
+    policy: "allow",
+    scope: "git",
   });
   const files = output
     .split("\n")