@ricsam/r5d-worker 0.0.122 → 0.0.124

package/README.md

@@ -81,13 +81,16 @@ Operators may set `R5D_WORKER_COMMAND_LAUNCHER` to a JSON argv array, such as `[
 
 The launcher owns admission, OS isolation, budgets, and diagnostic evidence. Its JSONL protocol uses `{requestId, method, ...fields}` requests and `{requestId, result}` or `{requestId, error}` replies:
 
-- `initialize` returns `{}` once ready; failure prevents command admission.
-- `acquire` receives `{id, kind, workspaceEffect?, sessionId?}` and returns `{argvPrefix: string[]}`. The worker prepends this argv to the command or terminal shell without interpreting it.
+- `initialize` returns `{}` once ready; failure prevents command admission. A launcher that bounds concurrency may return `{capacity: {generalSlots, utilitySlots, controlSlots, controlRuntimeMs, queueTimeoutMs}}` so the worker can report lane totals.
+- `acquire` receives `{id, kind, workspaceEffect?, commandClass?, sessionId?}` and returns `{argvPrefix: string[]}`. The worker prepends this argv to the command or terminal shell without interpreting it. `commandClass: "control"` is sent only for an `exec_start` whose argv is one plain `r5dctl` coordination command (validated against the worker's own allowlist, spawned without a shell, resolved from the worker's own `PATH`, with code-loading environment variables removed, and stopped by the worker after `controlRuntimeMs`); a launcher may give such commands a small reserved lane.
+- `status` returns `{capacity, lanes: {general|utility|control: {slots, active: [{id, sessionId?, since}], queued: [...]}}}`; optional, for operator inspection.
 - `cancel` receives `{id}` and irreversibly revokes queued or acquired work. `release` receives `{id}` and acknowledges only after cleanup. Both must be idempotent, including release before a delayed acquisition response.
 - `diagnose` receives `{id}` and returns `{message?: string}` with launcher-specific evidence. The worker does not infer a memory failure from an exit signal.
 
 Requests must be processed concurrently so cancellation and cleanup cannot wait behind queued admission. Controller RPCs are bounded (10 seconds, or 90 seconds for acquisition); external policy must reject excessive queue waits within that bound. Controller loss or protocol failure stops command admission, preserves uncertain outcomes for recovery, reaps ordinary children, and restarts the runtime through its supervisor. It never falls back to direct spawning. Shutdown closes controller stdin; the controller must reap its jobs before exiting.
 
-Cancellation is checked again immediately before spawn. Transient disconnects preserve commands and terminals; expiry of the five-minute execution lease cancels agent work and closes terminals. File operations, communication recovery, and cancellation do not enter launcher admission. Internal worker maintenance subprocesses are also outside this hook. Deployment-specific limits and service protection are documented in [Worker deployment resources](../../docs/worker-deployment-resources.md).
+Cancellation is checked again immediately before spawn. Transient disconnects preserve commands and terminals; expiry of the five-minute execution lease cancels agent work and closes terminals. File operations, communication recovery, and cancellation do not enter launcher admission. Internal worker maintenance subprocesses are also outside this hook. The worker reports its own view of every lane (holders and queue, by run id) to the server with `capacity_report` whenever an admission changes; the platform exposes it through `r5dctl ps list` and `r5dctl workspace status`. Deployment-specific limits and service protection are documented in [Worker deployment resources](../../docs/worker-deployment-resources.md).
 
 When the connected `r5d-browser` requests a port forward, the worker opens each relayed connection only to `127.0.0.1` on the requested worker port. Browser-side and worker-side ports may differ. The worker never opens a public listener, and a disconnected worker leaves the browser's long-lived mapping unavailable until the same worker label reconnects.
+
+Control execution requires an initialized launcher that explicitly declares its control capacity (or direct execution without an external launcher), an updated worker, and r5dctl installed on the worker's own PATH. Missing control support is an update error; a control request never falls back to a general shell. Deploy the app and worker support assets, update the CLI/worker, and reconnect before resuming paused work.

package/dist/cjs/command-launcher.cjs

@@ -21,12 +21,20 @@ __export(command_launcher_exports, {
   CommandLaunchCancelledError: () => CommandLaunchCancelledError,
   CommandLauncherUnavailableError: () => CommandLauncherUnavailableError,
   WorkerCommandLauncher: () => WorkerCommandLauncher,
+  commandLaunchLane: () => commandLaunchLane,
   commandLauncherEnvironment: () => commandLauncherEnvironment,
   createWorkerCommandLauncher: () => createWorkerCommandLauncher,
   parseCommandLauncher: () => parseCommandLauncher
 });
 module.exports = __toCommonJS(command_launcher_exports);
 var import_node_child_process = require("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 });
@@ -114,12 +122,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();
@@ -131,19 +141,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 {
@@ -169,6 +223,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();
@@ -268,6 +325,7 @@ class WorkerCommandLauncher {
       }
       record.released = true;
       this.launches.delete(record.request.id);
+      this.notifyCapacityChange();
     })();
   }
   assertHealthy() {
@@ -329,6 +387,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();
@@ -339,6 +412,7 @@ async function createWorkerCommandLauncher(options = {}) {
   CommandLaunchCancelledError,
   CommandLauncherUnavailableError,
   WorkerCommandLauncher,
+  commandLaunchLane,
   commandLauncherEnvironment,
   createWorkerCommandLauncher,
   parseCommandLauncher

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

@@ -0,0 +1,177 @@
+"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 control_command_policy_exports = {};
+__export(control_command_policy_exports, {
+  CONTROL_COMMAND_MAX_ARGV: () => CONTROL_COMMAND_MAX_ARGV,
+  CONTROL_COMMAND_MAX_LENGTH: () => CONTROL_COMMAND_MAX_LENGTH,
+  CONTROL_COMMAND_PROGRAM: () => CONTROL_COMMAND_PROGRAM,
+  CONTROL_COMMAND_RUNTIME_MS: () => CONTROL_COMMAND_RUNTIME_MS,
+  assertControlCommandArgv: () => assertControlCommandArgv,
+  classifyControlCommand: () => classifyControlCommand,
+  controlCommandEnvironment: () => controlCommandEnvironment,
+  resolveControlCommandExecutable: () => resolveControlCommandExecutable
+});
+module.exports = __toCommonJS(control_command_policy_exports);
+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 };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONTROL_COMMAND_MAX_ARGV,
+  CONTROL_COMMAND_MAX_LENGTH,
+  CONTROL_COMMAND_PROGRAM,
+  CONTROL_COMMAND_RUNTIME_MS,
+  assertControlCommandArgv,
+  classifyControlCommand,
+  controlCommandEnvironment,
+  resolveControlCommandExecutable
+});