chainlesschain 0.163.7 → 0.164.0

package/src/lib/background-agent-keeper-client.js

@@ -0,0 +1,248 @@
+import net from "node:net";
+import { randomBytes } from "node:crypto";
+import { createNdjsonReader } from "./background-session-transport.js";
+import {
+  BACKGROUND_AGENT_KEEPER_ARM,
+  BACKGROUND_AGENT_KEEPER_ARMED,
+  BACKGROUND_AGENT_KEEPER_HELLO,
+  BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION,
+  BACKGROUND_AGENT_KEEPER_READY,
+  BACKGROUND_AGENT_KEEPER_RETIRE,
+  BACKGROUND_AGENT_KEEPER_RETIRED,
+  createBackgroundAgentKeeperMessage,
+  normalizeBackgroundAgentKeeperHello,
+  normalizeBackgroundAgentKeeperTurn,
+  resolveBackgroundAgentKeeperRetireTimeoutMs,
+  sameBackgroundAgentKeeperTurn,
+} from "./background-agent-keeper-protocol.js";
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+
+function keeperError(message, code = "BACKGROUND_AGENT_KEEPER_UNAVAILABLE") {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function writeMessage(socket, message) {
+  if (!socket || socket.destroyed) {
+    throw keeperError("background agent keeper channel is closed");
+  }
+  socket.write(`${JSON.stringify(message)}\n`);
+}
+
+function connectOnce(pipePath) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(pipePath);
+    const onError = (error) => {
+      socket.destroy();
+      reject(error);
+    };
+    socket.once("error", onError);
+    socket.once("connect", () => {
+      socket.removeListener("error", onError);
+      resolve(socket);
+    });
+  });
+}
+
+async function connectWithDeadline(pipePath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      return await connectOnce(pipePath);
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+  throw keeperError(
+    `timed out connecting to background agent keeper: ${lastError?.message || "unavailable"}`,
+  );
+}
+
+export async function connectBackgroundAgentKeeper(options = {}) {
+  const hello = normalizeBackgroundAgentKeeperHello(options);
+  const connectTimeoutMs = Math.max(
+    1,
+    Number(options.connectTimeoutMs) || DEFAULT_CONNECT_TIMEOUT_MS,
+  );
+  const requestTimeoutMs = Math.max(
+    1,
+    Number(options.requestTimeoutMs) || DEFAULT_REQUEST_TIMEOUT_MS,
+  );
+  const retireTimeoutMs = resolveBackgroundAgentKeeperRetireTimeoutMs(
+    options.retireTimeoutMs,
+  );
+  const socket = await connectWithDeadline(options.pipePath, connectTimeoutMs);
+  const pending = new Map();
+  let ready = false;
+  let closing = false;
+  let activeTurn = null;
+  let readyResolve;
+  let readyReject;
+  const readyPromise = new Promise((resolve, reject) => {
+    readyResolve = resolve;
+    readyReject = reject;
+  });
+
+  const failPending = (error) => {
+    readyReject(error);
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    pending.clear();
+  };
+
+  socket.on(
+    "data",
+    createNdjsonReader(
+      (message) => {
+        if (
+          message?.protocolVersion !== BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION
+        ) {
+          socket.destroy(
+            keeperError("background agent keeper protocol mismatch"),
+          );
+          return;
+        }
+        if (!ready) {
+          if (
+            message.type !== BACKGROUND_AGENT_KEEPER_READY ||
+            message.id !== hello.id ||
+            message.workerGeneration !== hello.workerGeneration
+          ) {
+            socket.destroy(
+              keeperError("background agent keeper ready binding mismatch"),
+            );
+            return;
+          }
+          ready = true;
+          readyResolve();
+          return;
+        }
+        const entry = pending.get(message.requestId);
+        if (!entry) return;
+        if (message.type === "background-agent-keeper-error") {
+          pending.delete(message.requestId);
+          clearTimeout(entry.timer);
+          entry.reject(
+            keeperError(
+              message.message || "background agent keeper rejected request",
+              message.code || "BACKGROUND_AGENT_KEEPER_REJECTED",
+            ),
+          );
+          return;
+        }
+        if (message.type !== entry.expectedType) return;
+        if (!sameBackgroundAgentKeeperTurn(message, entry.turn)) {
+          socket.destroy(
+            keeperError("background agent keeper response binding mismatch"),
+          );
+          return;
+        }
+        pending.delete(message.requestId);
+        clearTimeout(entry.timer);
+        entry.resolve(message);
+      },
+      (error) => socket.destroy(error),
+    ),
+  );
+  socket.on("error", (error) => failPending(error));
+  socket.on("close", () => {
+    const error = keeperError("background agent keeper channel disconnected");
+    failPending(error);
+    if (!closing) options.onDisconnect?.(error, activeTurn);
+  });
+
+  writeMessage(
+    socket,
+    createBackgroundAgentKeeperMessage(BACKGROUND_AGENT_KEEPER_HELLO, hello),
+  );
+  const helloTimer = setTimeout(
+    () =>
+      socket.destroy(
+        keeperError("timed out waiting for background agent keeper ready"),
+      ),
+    requestTimeoutMs,
+  );
+  helloTimer.unref?.();
+  await readyPromise.finally(() => clearTimeout(helloTimer));
+
+  const request = (
+    type,
+    expectedType,
+    turnValue,
+    timeoutMs = requestTimeoutMs,
+  ) => {
+    const turn = normalizeBackgroundAgentKeeperTurn(turnValue);
+    const requestId = randomBytes(16).toString("hex");
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(requestId);
+        reject(
+          keeperError(
+            `timed out waiting for background agent keeper ${type} after ${timeoutMs}ms`,
+          ),
+        );
+      }, timeoutMs);
+      timer.unref?.();
+      pending.set(requestId, { expectedType, reject, resolve, timer, turn });
+      try {
+        writeMessage(
+          socket,
+          createBackgroundAgentKeeperMessage(type, { requestId, ...turn }),
+        );
+      } catch (error) {
+        pending.delete(requestId);
+        clearTimeout(timer);
+        reject(error);
+      }
+    });
+  };
+
+  return Object.freeze({
+    async arm(turn) {
+      const normalized = normalizeBackgroundAgentKeeperTurn(turn);
+      if (activeTurn) {
+        throw keeperError(
+          "background agent keeper is already armed",
+          "BACKGROUND_AGENT_KEEPER_BUSY",
+        );
+      }
+      await request(
+        BACKGROUND_AGENT_KEEPER_ARM,
+        BACKGROUND_AGENT_KEEPER_ARMED,
+        normalized,
+      );
+      activeTurn = normalized;
+      return normalized;
+    },
+    async retire(turn) {
+      const normalized = normalizeBackgroundAgentKeeperTurn(turn);
+      if (!sameBackgroundAgentKeeperTurn(normalized, activeTurn)) {
+        throw keeperError(
+          "background agent keeper retire binding mismatch",
+          "BACKGROUND_AGENT_KEEPER_BINDING_MISMATCH",
+        );
+      }
+      await request(
+        BACKGROUND_AGENT_KEEPER_RETIRE,
+        BACKGROUND_AGENT_KEEPER_RETIRED,
+        normalized,
+        retireTimeoutMs,
+      );
+      activeTurn = null;
+      return true;
+    },
+    close() {
+      if (closing) return;
+      closing = true;
+      socket.end();
+    },
+    activeTurn: () => activeTurn,
+  });
+}

package/src/lib/background-agent-keeper-protocol.js

@@ -0,0 +1,147 @@
+import { join } from "node:path";
+
+export const BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION = 1;
+export const BACKGROUND_AGENT_KEEPER_HELLO = "background-agent-keeper-hello";
+export const BACKGROUND_AGENT_KEEPER_READY = "background-agent-keeper-ready";
+export const BACKGROUND_AGENT_KEEPER_ARM = "background-agent-keeper-arm";
+export const BACKGROUND_AGENT_KEEPER_ARMED = "background-agent-keeper-armed";
+export const BACKGROUND_AGENT_KEEPER_RETIRE = "background-agent-keeper-retire";
+export const BACKGROUND_AGENT_KEEPER_RETIRED =
+  "background-agent-keeper-retired";
+
+// RETIRE is the only keeper request that performs destructive OS cleanup. Its
+// deadline is deliberately independent from the short HELLO/ARM request
+// deadline and is derived from every synchronous operation on the longest
+// Windows path:
+//
+//   2 targets * (taskkill + WMIC + PowerShell) +
+//   2 durable state-lock acquisitions + cleanup confirmation + scheduling
+//   margin = 70 seconds.
+//
+// Keeping these limits in the shared protocol contract prevents either side
+// from silently reintroducing the old 10-second client / longer keeper race.
+export const BACKGROUND_AGENT_KEEPER_CLEANUP_TARGET_LIMIT = 2;
+export const BACKGROUND_AGENT_KEEPER_TASKKILL_TIMEOUT_MS = 10_000;
+export const BACKGROUND_AGENT_KEEPER_WMIC_TIMEOUT_MS = 5_000;
+export const BACKGROUND_AGENT_KEEPER_POWERSHELL_TIMEOUT_MS = 10_000;
+export const BACKGROUND_AGENT_KEEPER_STATE_LOCK_TIMEOUT_MS = 5_000;
+export const BACKGROUND_AGENT_KEEPER_CLEANUP_CONFIRM_TIMEOUT_MS = 2_000;
+export const BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MARGIN_MS = 8_000;
+export const BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MS =
+  BACKGROUND_AGENT_KEEPER_CLEANUP_TARGET_LIMIT *
+    (BACKGROUND_AGENT_KEEPER_TASKKILL_TIMEOUT_MS +
+      BACKGROUND_AGENT_KEEPER_WMIC_TIMEOUT_MS +
+      BACKGROUND_AGENT_KEEPER_POWERSHELL_TIMEOUT_MS) +
+  2 * BACKGROUND_AGENT_KEEPER_STATE_LOCK_TIMEOUT_MS +
+  BACKGROUND_AGENT_KEEPER_CLEANUP_CONFIRM_TIMEOUT_MS +
+  BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MARGIN_MS;
+
+export function resolveBackgroundAgentKeeperRetireTimeoutMs(value) {
+  const requested = Number(value);
+  if (!Number.isFinite(requested) || requested <= 0) {
+    return BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MS;
+  }
+  return Math.min(
+    BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MS,
+    Math.max(1, Math.floor(requested)),
+  );
+}
+
+const SAFE_ID = /^[A-Za-z0-9_-]{1,256}$/u;
+const SAFE_TOKEN = /^[a-f0-9]{64}$/u;
+
+function requiredSafeString(value, label, pattern = SAFE_ID) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  if (!pattern.test(normalized)) {
+    throw new TypeError(`invalid background agent keeper ${label}`);
+  }
+  return normalized;
+}
+
+function requiredPositiveInteger(value, label) {
+  const normalized = Number(value);
+  if (!Number.isSafeInteger(normalized) || normalized < 1) {
+    throw new TypeError(`invalid background agent keeper ${label}`);
+  }
+  return normalized;
+}
+
+function requiredTimestamp(value, label) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new TypeError(`invalid background agent keeper ${label}`);
+  }
+  return normalized;
+}
+
+export function backgroundAgentKeeperPipePath(id, directory) {
+  const safeId = requiredSafeString(id, "id");
+  if (process.platform === "win32") {
+    return `\\\\.\\pipe\\cc-bg-keeper-${safeId}`;
+  }
+  return join(directory, `${safeId}.keeper.sock`);
+}
+
+export function normalizeBackgroundAgentKeeperAuthority(value = {}) {
+  return Object.freeze({
+    id: requiredSafeString(value.id, "id"),
+    workerGeneration: requiredSafeString(
+      value.workerGeneration,
+      "worker generation",
+    ),
+  });
+}
+
+export function normalizeBackgroundAgentKeeperHello(value = {}) {
+  return Object.freeze({
+    ...normalizeBackgroundAgentKeeperAuthority(value),
+    token: requiredSafeString(value.token, "token", SAFE_TOKEN),
+    workerPid: requiredPositiveInteger(value.workerPid, "worker pid"),
+  });
+}
+
+export function normalizeBackgroundAgentKeeperTurn(value = {}) {
+  return Object.freeze({
+    ...normalizeBackgroundAgentKeeperAuthority(value),
+    turnLaunchToken: requiredSafeString(
+      value.turnLaunchToken,
+      "turn launch token",
+    ),
+    attempt: requiredPositiveInteger(value.attempt, "turn attempt"),
+    agentPid: requiredPositiveInteger(value.agentPid, "agent pid"),
+    agentStartedAt: requiredTimestamp(
+      value.agentStartedAt,
+      "agent start anchor",
+    ),
+    agentRuntimePid: requiredPositiveInteger(
+      value.agentRuntimePid,
+      "agent runtime pid",
+    ),
+    agentRuntimeStartedAt: requiredTimestamp(
+      value.agentRuntimeStartedAt,
+      "agent runtime start anchor",
+    ),
+  });
+}
+
+export function sameBackgroundAgentKeeperTurn(left, right) {
+  let normalizedLeft;
+  let normalizedRight;
+  try {
+    normalizedLeft = normalizeBackgroundAgentKeeperTurn(left);
+    normalizedRight = normalizeBackgroundAgentKeeperTurn(right);
+  } catch {
+    return false;
+  }
+  return Object.keys(normalizedLeft).every(
+    (key) => normalizedLeft[key] === normalizedRight[key],
+  );
+}
+
+export function createBackgroundAgentKeeperMessage(type, payload = {}) {
+  return Object.freeze({
+    type,
+    protocolVersion: BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION,
+    ...payload,
+  });
+}