@ricsam/r5d-worker 0.0.122 → 0.0.124

package/dist/cjs/workspace-mount-hold-fence.cjs

@@ -0,0 +1,120 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var workspace_mount_hold_fence_exports = {};
+__export(workspace_mount_hold_fence_exports, {
+  WorkspaceMountHoldAbortedError: () => WorkspaceMountHoldAbortedError,
+  WorkspaceMountHoldFence: () => WorkspaceMountHoldFence
+});
+module.exports = __toCommonJS(workspace_mount_hold_fence_exports);
+class WorkspaceMountHoldAbortedError extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "WorkspaceMountHoldAbortedError";
+  }
+}
+class WorkspaceMountHoldFence {
+  holds = /* @__PURE__ */ new Map();
+  waiters = /* @__PURE__ */ new Set();
+  now;
+  constructor(options = {}) {
+    this.now = options.now ?? (() => Date.now());
+  }
+  /** Take one hold on every listed mount; the returned release is idempotent. */
+  hold(mountIds, description) {
+    const ids = [...new Set(mountIds)];
+    for (const id of ids) {
+      const existing = this.holds.get(id);
+      if (existing) {
+        existing.count += 1;
+        continue;
+      }
+      this.holds.set(id, { count: 1, description, sinceMs: this.now() });
+    }
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      for (const id of ids) {
+        const existing = this.holds.get(id);
+        if (!existing) continue;
+        existing.count -= 1;
+        if (existing.count === 0) this.holds.delete(id);
+      }
+      this.wake();
+    };
+  }
+  isHeld(mountIds) {
+    return mountIds.some((id) => this.holds.has(id));
+  }
+  /** Human-readable holder of the first held mount among `mountIds`, for diagnostics. */
+  describeHold(mountIds) {
+    for (const id of mountIds) {
+      const hold = this.holds.get(id);
+      if (hold) return `${hold.description} (held for ${Math.round((this.now() - hold.sinceMs) / 1e3)}s)`;
+    }
+    return null;
+  }
+  /** Every held mount id, sorted, for status reporting. */
+  heldMountIds() {
+    return [...this.holds.keys()].sort();
+  }
+  /**
+   * Resolves in the same turn as the release that leaves none of `mountIds`
+   * held, so the caller can re-check and reserve without an interleaving
+   * hold. Resolves immediately when nothing is held. Rejects with
+   * WorkspaceMountHoldAbortedError when `signal` aborts first.
+   */
+  waitForRelease(mountIds, options = {}) {
+    if (options.signal?.aborted) {
+      return Promise.reject(new WorkspaceMountHoldAbortedError(abortReason(options.signal)));
+    }
+    if (!this.isHeld(mountIds)) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const waiter = { mountIds, resolve, reject, signal: options.signal };
+      if (options.signal) {
+        const signal = options.signal;
+        waiter.onAbort = () => {
+          this.waiters.delete(waiter);
+          reject(new WorkspaceMountHoldAbortedError(abortReason(signal)));
+        };
+        signal.addEventListener("abort", waiter.onAbort, { once: true });
+      }
+      this.waiters.add(waiter);
+    });
+  }
+  wake() {
+    for (const waiter of [...this.waiters]) {
+      if (this.isHeld(waiter.mountIds)) continue;
+      this.waiters.delete(waiter);
+      if (waiter.signal && waiter.onAbort) waiter.signal.removeEventListener("abort", waiter.onAbort);
+      waiter.resolve();
+    }
+  }
+}
+function abortReason(signal) {
+  const reason = signal.reason;
+  if (reason instanceof Error) return reason.message;
+  if (typeof reason === "string" && reason) return reason;
+  return "Workspace mount reservation was aborted";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WorkspaceMountHoldAbortedError,
+  WorkspaceMountHoldFence
+});

package/dist/mjs/command-launcher.mjs

@@ -1,4 +1,11 @@
 import { spawn } from "node:child_process";
+function commandLaunchLane(request) {
+  if (request.commandClass === "control") {
+    if (request.kind !== "exec_start") throw new Error("Control commands must be exec_start launches");
+    return "control";
+  }
+  return request.kind === "exec" && request.workspaceEffect === "none" ? "utility" : "general";
+}
 class CommandLauncherUnavailableError extends Error {
   constructor(message, cause) {
     super(message, { cause });
@@ -86,12 +93,14 @@ class WorkerCommandLauncher {
   initialized = false;
   closePromise;
   sequence = 0;
+  capacity;
   async initialize() {
     this.assertHealthy();
     if (this.initialized) return;
     if (this.child) {
       try {
-        await this.rpc("initialize");
+        const result = await this.rpc("initialize");
+        this.capacity = parseCapacity(result.capacity);
       } catch (error) {
         this.fail(error instanceof Error ? error : new Error(String(error)));
         await this.close();
@@ -103,19 +112,63 @@ class WorkerCommandLauncher {
   get activeIds() {
     return [...this.launches.keys()];
   }
+  /** The lane totals the launcher declared at initialization; undefined for a direct worker or an older launcher. */
+  get declaredCapacity() {
+    return this.capacity;
+  }
+  get supportsControlLane() {
+    return this.initialized && (this.mode === "direct" || (this.capacity?.controlSlots ?? 0) > 0);
+  }
+  /** Current admissions per lane, for the worker's capacity report. */
+  capacityReport() {
+    const bounded = this.child !== void 0;
+    const lanes = {
+      general: { slots: bounded ? this.capacity?.generalSlots ?? null : null, active: [], queued: [] },
+      utility: { slots: bounded ? this.capacity?.utilitySlots ?? null : null, active: [], queued: [] },
+      control: { slots: bounded ? this.capacity?.controlSlots ?? null : null, active: [], queued: [] }
+    };
+    for (const record of this.launches.values()) {
+      if (record.released) continue;
+      const entry = {
+        id: record.request.id,
+        ...record.request.sessionId ? { sessionId: record.request.sessionId } : {},
+        since: record.since
+      };
+      (record.phase === "active" ? lanes[record.lane].active : lanes[record.lane].queued).push(entry);
+    }
+    return { bounded, controlRuntimeMs: bounded ? this.capacity?.controlRuntimeMs ?? null : null, lanes };
+  }
+  notifyCapacityChange() {
+    try {
+      this.options.onCapacityChange?.();
+    } catch {
+    }
+  }
   async acquire(request) {
     this.assertHealthy();
     if (!this.initialized) throw new Error("Command launcher is not initialized");
     request.assertAdmission();
     if (this.launches.has(request.id)) throw new Error(`Duplicate command launch identity: ${request.id}`);
+    const lane = commandLaunchLane(request);
+    if (lane === "control" && !this.supportsControlLane)
+      throw new Error("Update the worker command launcher before running control commands");
     let rejectAdmission;
     const cancellation = new Promise((_resolve, reject) => {
       rejectAdmission = reject;
     });
     void cancellation.catch(() => {
     });
-    const record = { request, revoked: false, released: false, rejectAdmission };
+    const record = {
+      request,
+      lane,
+      phase: this.child ? "queued" : "active",
+      since: (/* @__PURE__ */ new Date()).toISOString(),
+      revoked: false,
+      released: false,
+      rejectAdmission
+    };
     this.launches.set(request.id, record);
+    this.notifyCapacityChange();
     let prefix = [];
     let admissionTimer;
     try {
@@ -141,6 +194,9 @@ class WorkerCommandLauncher {
           }
         }, 100);
         prefix = await Promise.race([acquisition, cancellation]);
+        record.phase = "active";
+        record.since = (/* @__PURE__ */ new Date()).toISOString();
+        this.notifyCapacityChange();
       }
       request.assertAdmission();
       this.assertHealthy();
@@ -240,6 +296,7 @@ class WorkerCommandLauncher {
       }
       record.released = true;
       this.launches.delete(record.request.id);
+      this.notifyCapacityChange();
     })();
   }
   assertHealthy() {
@@ -301,6 +358,21 @@ class WorkerCommandLauncher {
     return this.failure;
   }
 }
+function parseCapacity(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const candidate = value;
+  const numbers = ["generalSlots", "utilitySlots", "controlSlots", "controlRuntimeMs", "queueTimeoutMs"];
+  if (!numbers.every((key) => typeof candidate[key] === "number" && Number.isSafeInteger(candidate[key]) && candidate[key] >= 0)) {
+    throw new Error("Command launcher initialize returned an invalid capacity");
+  }
+  return {
+    generalSlots: candidate.generalSlots,
+    utilitySlots: candidate.utilitySlots,
+    controlSlots: candidate.controlSlots,
+    controlRuntimeMs: candidate.controlRuntimeMs,
+    queueTimeoutMs: candidate.queueTimeoutMs
+  };
+}
 async function createWorkerCommandLauncher(options = {}) {
   const launcher = new WorkerCommandLauncher({ ...options, argv: parseCommandLauncher(options.configuration) });
   await launcher.initialize();
@@ -310,6 +382,7 @@ export {
   CommandLaunchCancelledError,
   CommandLauncherUnavailableError,
   WorkerCommandLauncher,
+  commandLaunchLane,
   commandLauncherEnvironment,
   createWorkerCommandLauncher,
   parseCommandLauncher

package/dist/mjs/control-command-policy.mjs

@@ -0,0 +1,146 @@
+const CONTROL_COMMAND_PROGRAM = "r5dctl";
+const CONTROL_COMMAND_RUNTIME_MS = 12e4;
+const CONTROL_COMMAND_MAX_ARGV = 64;
+const CONTROL_COMMAND_MAX_LENGTH = 4096;
+const CONTROL_GLOBAL_FLAGS_WITH_VALUE = /* @__PURE__ */ new Set(["-p", "--project", "-s", "--session", "-b", "--branch"]);
+const CONTROL_GLOBAL_FLAGS = /* @__PURE__ */ new Set(["--json", "-h", "--help", "-v", "--version"]);
+const REFUSED_ANYWHERE = /* @__PURE__ */ new Set(["-f", "--follow", "--watch", "--base-url", "--config", "--token", "--api-key"]);
+const CONTROL_VERBS = {
+  session: /* @__PURE__ */ new Set(["status", "stop", "prompt", "claim", "claims", "process-log"]),
+  sessions: /* @__PURE__ */ new Set(["recent"]),
+  describe: /* @__PURE__ */ new Set(["project", "branch", "session", "branch-operation", "branch-deletion"]),
+  get: /* @__PURE__ */ new Set(["projects", "branches", "sessions", "envs", "env"]),
+  conversation: /* @__PURE__ */ new Set(["overview", "inspect-node", "inspect-work"]),
+  ps: /* @__PURE__ */ new Set(["list", "history", "inspect", "stop"]),
+  workspace: /* @__PURE__ */ new Set(["status"]),
+  auth: /* @__PURE__ */ new Set(["status"]),
+  create: /* @__PURE__ */ new Set(["session"]),
+  update: /* @__PURE__ */ new Set(["session"]),
+  delete: /* @__PURE__ */ new Set(["session"]),
+  "answer-questions": null,
+  "answer-env-request": null
+};
+const CODE_LOADING_ENV_PATTERN = /^(NODE_OPTIONS|NODE_PATH|NODE_REPL_EXTERNAL_MODULE|BUN_OPTIONS|BUN_CONFIG_[A-Z_]+|LD_PRELOAD|LD_LIBRARY_PATH|LD_AUDIT|DYLD_[A-Z_]+|PATH|PATHEXT|PYTHONPATH|PERL5OPT|RUBYOPT|SHELL|ENV|BASH_ENV)$/i;
+const BARE_WORD = /^[A-Za-z0-9_@%+=:,./-]+$/;
+const DOUBLE_QUOTED_FORBIDDEN = /[$`\\!]/;
+function tokenizePlainInvocation(command) {
+  if (command.length > CONTROL_COMMAND_MAX_LENGTH) return { reason: "command is longer than the control lane allows" };
+  if (/[\r\n]/.test(command)) return { reason: "multi-line commands are shell scripts" };
+  const argv = [];
+  let index = 0;
+  while (index < command.length) {
+    const char = command[index];
+    if (char === " " || char === "	") {
+      index += 1;
+      continue;
+    }
+    let word = "";
+    let quotedParts = 0;
+    let bareParts = 0;
+    while (index < command.length && command[index] !== " " && command[index] !== "	") {
+      const current = command[index];
+      if (current === "'") {
+        const end = command.indexOf("'", index + 1);
+        if (end < 0) return { reason: "unterminated single quote" };
+        word += command.slice(index + 1, end);
+        quotedParts += 1;
+        index = end + 1;
+        continue;
+      }
+      if (current === '"') {
+        const end = command.indexOf('"', index + 1);
+        if (end < 0) return { reason: "unterminated double quote" };
+        const inner = command.slice(index + 1, end);
+        if (DOUBLE_QUOTED_FORBIDDEN.test(inner)) return { reason: "double-quoted text would be expanded by the shell" };
+        word += inner;
+        quotedParts += 1;
+        index = end + 1;
+        continue;
+      }
+      let bare = "";
+      while (index < command.length && !/[\s'"]/.test(command[index])) {
+        bare += command[index];
+        index += 1;
+      }
+      if (!BARE_WORD.test(bare)) return { reason: `shell syntax in "${bare}" is not part of a plain invocation` };
+      word += bare;
+      bareParts += 1;
+    }
+    if (quotedParts + bareParts > 1) return { reason: "adjacent quoted and bare text is shell concatenation" };
+    argv.push(word);
+    if (argv.length > CONTROL_COMMAND_MAX_ARGV) return { reason: "too many arguments for a control command" };
+  }
+  if (argv.length === 0) return { reason: "empty command" };
+  return { argv };
+}
+function assertControlCommandArgv(argv) {
+  if (argv.length === 0 || argv.length > CONTROL_COMMAND_MAX_ARGV) throw new Error("Control commands are a single r5dctl invocation");
+  if (argv[0] !== CONTROL_COMMAND_PROGRAM) throw new Error(`Control commands must start with ${CONTROL_COMMAND_PROGRAM}`);
+  if (argv.reduce((length, argument) => length + (typeof argument === "string" ? argument.length : 0) + 1, 0) > CONTROL_COMMAND_MAX_LENGTH)
+    throw new Error("Control command arguments exceed the length limit");
+  for (const argument of argv) {
+    if (typeof argument !== "string" || argument.includes("\0") || /[\r\n]/.test(argument)) throw new Error("Control command arguments must be plain text");
+    if (REFUSED_ANYWHERE.has(argument.split("=", 1)[0])) throw new Error(`Control command option is not allowed (${argument.split("=", 1)[0]})`);
+    if (argument === "--") throw new Error("Control commands cannot use `--`");
+  }
+  let position = 1;
+  while (position < argv.length) {
+    const argument = argv[position];
+    if (CONTROL_GLOBAL_FLAGS.has(argument)) {
+      position += 1;
+      continue;
+    }
+    if (CONTROL_GLOBAL_FLAGS_WITH_VALUE.has(argument)) {
+      if (position + 1 >= argv.length) throw new Error(`Missing value for ${argument}`);
+      position += 2;
+      continue;
+    }
+    if (argument.startsWith("-")) throw new Error(`Global flag ${argument} is not allowed in a control command`);
+    break;
+  }
+  const verb = argv[position];
+  if (verb === void 0) throw new Error("Control commands need a coordination verb (for example `r5dctl ps list`)");
+  const allowed = Object.hasOwn(CONTROL_VERBS, verb) ? CONTROL_VERBS[verb] : void 0;
+  if (allowed === void 0) throw new Error(`r5dctl ${verb} is not a coordination command`);
+  if (allowed === null) return;
+  const subject = argv[position + 1];
+  if (subject === void 0 || !allowed.has(subject)) {
+    throw new Error(`r5dctl ${verb}${subject ? ` ${subject}` : ""} is not a coordination command`);
+  }
+}
+function resolveControlCommandExecutable(trustedPath, which, program = CONTROL_COMMAND_PROGRAM) {
+  const resolved = trustedPath ? which(program, { PATH: trustedPath }) : null;
+  if (!resolved) throw new Error(`${program} is not installed on the worker's trusted PATH; control commands are unavailable until it is`);
+  return resolved;
+}
+function controlCommandEnvironment(environment, trustedPath) {
+  const result = {};
+  for (const [key, value] of Object.entries(environment)) {
+    if (value === void 0 || CODE_LOADING_ENV_PATTERN.test(key)) continue;
+    result[key] = value;
+  }
+  if (trustedPath !== void 0) result.PATH = trustedPath;
+  return result;
+}
+function classifyControlCommand(command) {
+  const tokenized = tokenizePlainInvocation(command.trim());
+  if ("reason" in tokenized) return { control: false, reason: tokenized.reason };
+  const { argv } = tokenized;
+  if (argv[0] !== CONTROL_COMMAND_PROGRAM) return { control: false, reason: "not an r5dctl invocation" };
+  try {
+    assertControlCommandArgv(argv);
+  } catch (error) {
+    return { control: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  return { control: true, argv };
+}
+export {
+  CONTROL_COMMAND_MAX_ARGV,
+  CONTROL_COMMAND_MAX_LENGTH,
+  CONTROL_COMMAND_PROGRAM,
+  CONTROL_COMMAND_RUNTIME_MS,
+  assertControlCommandArgv,
+  classifyControlCommand,
+  controlCommandEnvironment,
+  resolveControlCommandExecutable
+};