@schlenkr/ragents 0.1.16 → 0.1.18

package/packages/workspace-executor/src/bundled-tools.ts

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+export const WORKSPACE_TOOL_TARGETS = ["win32-x64", "win32-arm64", "darwin-x64", "darwin-arm64", "linux-x64", "linux-arm64"] as const;
+export type WorkspaceToolTarget = typeof WORKSPACE_TOOL_TARGETS[number];
+
+export const workspaceToolsPackageName = (target: string): string => `@schlenkr/ragents-tools-${target}`;
+
+export interface BundledToolsOptions {
+  readonly root: string;
+  readonly distribution: "extension" | "package";
+  readonly platform?: NodeJS.Platform;
+  readonly arch?: string;
+  readonly paths?: typeof path;
+  readonly exists?: (file: string) => boolean;
+  readonly resolvePackage?: (specifier: string) => string;
+}
+
+export interface BundledTools {
+  readonly bash: string | undefined;
+  readonly rg: string | undefined;
+}
+
+export const resolveBundledTools = (options: BundledToolsOptions): BundledTools => {
+  const platform = options.platform ?? process.platform;
+  const target = `${platform}-${options.arch ?? process.arch}`;
+  const paths = options.paths ?? path;
+  const exists = options.exists ?? existsSync;
+  const packageRoot = (): string => {
+    if (!WORKSPACE_TOOL_TARGETS.includes(target as WorkspaceToolTarget)) throw new Error(`Unsupported workstation platform: ${target}`);
+    const name = workspaceToolsPackageName(target);
+    try {
+      const resolve = options.resolvePackage ?? createRequire(paths.join(options.root, "package.json")).resolve;
+      return paths.dirname(resolve(`${name}/package.json`));
+    } catch {
+      throw new Error(`The bundled workstation tools ${name} are missing. Reinstall @schlenkr/ragents with optional dependencies enabled.`);
+    }
+  };
+  const root = options.distribution === "package" ? packageRoot() : options.root;
+  const bash = platform === "win32" ? paths.join(root, "dist", "bash", target, "usr", "bin", "bash.exe") : undefined;
+  const rg = paths.join(root, "dist", "rg", target, platform === "win32" ? "rg.exe" : "rg");
+  if (options.distribution === "package") {
+    for (const file of [rg, bash]) {
+      if (file !== undefined && !exists(file)) throw new Error(`Bundled workstation tool is missing: ${file}. Reinstall @schlenkr/ragents with optional dependencies enabled.`);
+    }
+  }
+  return { bash, rg: exists(rg) ? rg : undefined };
+};

package/packages/workspace-executor/src/owner-lifetime.d.mts

@@ -0,0 +1,18 @@
+import type { EventEmitter } from "node:events";
+import type { Readable } from "node:stream";
+
+export interface OwnerLifetimeOptions {
+  readonly detached?: boolean;
+  readonly parents?: readonly number[];
+  readonly onStop: (reason: string) => void;
+  readonly stdin?: Pick<Readable, "on" | "off" | "resume" | "pause" | "destroyed" | "readableEnded"> | null;
+  readonly signals?: EventEmitter;
+  readonly alive?: (pid: number) => boolean;
+  readonly intervalMs?: number;
+}
+
+export function processAlive(pid: number): boolean;
+export function watchOwnerLifetime(options: OwnerLifetimeOptions): () => void;
+export function processChildren(pid?: number): number[];
+export function terminateProcessTree(pid: number): void;
+export function exitWorkspaceProcess(code: number): never;

package/packages/workspace-executor/src/owner-lifetime.mjs

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, readdirSync } from "node:fs";
+
+export const processAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+};
+
+export const watchOwnerLifetime = ({ detached = false, parents = [process.ppid], onStop, stdin = process.stdin, signals = process, alive = processAlive, intervalMs = 1000 }) => {
+  const releases = [];
+  const signalReleases = [];
+  let stopped = false;
+  const dispose = () => {
+    for (const release of releases.splice(0)) release();
+  };
+  const stop = (reason) => {
+    if (stopped) return;
+    stopped = true;
+    dispose();
+    onStop(reason);
+  };
+  const listen = (emitter, event, handler, keepDuringStop = false) => {
+    emitter.on(event, handler);
+    (keepDuringStop ? signalReleases : releases).push(() => emitter.off(event, handler));
+  };
+  listen(signals, "SIGINT", () => stop("SIGINT"), true);
+  listen(signals, "SIGTERM", () => stop("SIGTERM"), true);
+  listen(signals, "SIGHUP", () => { if (!detached) stop("SIGHUP"); }, true);
+  if (!detached) {
+    if (parents.some((pid) => !Number.isSafeInteger(pid) || pid <= 0)) throw new Error("The workspace owner PID must be a positive integer.");
+    const check = () => {
+      if (parents.some((pid) => !alive(pid))) stop("parent exited");
+    };
+    const timer = setInterval(check, intervalMs);
+    timer.unref();
+    releases.push(() => clearInterval(timer));
+    listen(signals, "disconnect", () => stop("owner disconnected"));
+    if (stdin) {
+      listen(stdin, "end", () => stop("stdin closed"));
+      listen(stdin, "close", () => stop("stdin closed"));
+      listen(stdin, "error", () => stop("stdin failed"));
+      stdin.resume();
+      releases.push(() => stdin.pause());
+      if (stdin.destroyed || stdin.readableEnded) queueMicrotask(() => stop("stdin closed"));
+    }
+    queueMicrotask(check);
+  }
+  return () => {
+    stopped = true;
+    dispose();
+    for (const release of signalReleases.splice(0)) release();
+  };
+};
+
+export const processChildren = (pid = process.pid) => {
+  if (process.platform === "win32") {
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command",
+      `Get-CimInstance Win32_Process -Filter 'ParentProcessId = ${pid}' | ForEach-Object { $_.ProcessId }`], { encoding: "utf8", windowsHide: true, timeout: 5000 });
+    if (result.status !== 0) throw new Error("Cannot inspect workspace child processes for shutdown.");
+    return result.stdout.trim().split(/\s+/).map(Number).filter((child) => child > 0);
+  }
+  const rows = process.platform === "linux" ? readdirSync("/proc").filter((entry) => /^\d+$/.test(entry)).flatMap((entry) => {
+    try {
+      const stat = readFileSync(`/proc/${entry}/stat`, "utf8");
+      return [[Number(entry), Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1])]];
+    } catch (error) {
+      if (["ENOENT", "ESRCH", "EACCES"].includes(error.code)) return [];
+      throw error;
+    }
+  }) : (() => {
+    const table = spawnSync("ps", ["-axo", "pid=,ppid="], { encoding: "utf8" });
+    if (table.status !== 0) throw new Error("Cannot inspect workspace child processes for shutdown.");
+    return table.stdout.trim().split("\n").map((line) => line.trim().split(/\s+/).map(Number));
+  })();
+  const descendants = (parent) => rows.filter((row) => row[1] === parent).flatMap((row) => [...descendants(row[0]), row[0]]);
+  return descendants(pid);
+};
+
+export const terminateProcessTree = (pid) => {
+  if (process.platform === "win32") {
+    const killed = spawnSync("taskkill", ["/T", "/F", "/PID", String(pid)], { stdio: "ignore", windowsHide: true, timeout: 5000 });
+    if (killed.status !== 0 && processAlive(pid)) throw new Error(`Could not stop workspace child process ${pid}.`);
+    return;
+  }
+  for (const child of [...processChildren(pid), pid]) {
+    try { process.kill(child, "SIGKILL"); } catch (error) { if (error.code !== "ESRCH") throw error; }
+  }
+};
+
+export const exitWorkspaceProcess = (code) => {
+  for (const pid of processChildren()) {
+    if (process.platform === "win32") terminateProcessTree(pid);
+    else {
+      try { process.kill(pid, "SIGKILL"); } catch (error) { if (error.code !== "ESRCH") throw error; }
+    }
+  }
+  process.exit(code);
+};

package/plugins/ragents.workspace/client/transport.ts

@@ -1,13 +1,11 @@
-import { RpcClient } from "../../../apps/web/src/rpc/client";
-import type { WorkspaceClientTransport } from "./workspace-client";
+import { ServerClient } from "../../../apps/web/src/server-client";
 
-/** A workstation access without a user interface: the message layer with a bearer token. */
-export const workspaceClientTransport = (baseUrl: string, token: string | undefined): WorkspaceClientTransport => ({
-  rpc: new RpcClient({
-    baseUrl: new URL(baseUrl).origin,
-    fetch: (input, init) => {
-      const headers = init?.headers as Record<string, string> | undefined ?? {};
-      return fetch(input, { ...init, headers: token === undefined ? headers : { ...headers, authorization: `Bearer ${token}` } });
+export const workspaceClientTransport = (baseUrl: string, token: string | undefined, environment: NodeJS.ProcessEnv = process.env): ServerClient =>
+  new ServerClient(baseUrl, token, fetch, {
+    log: (line) => console.error(line),
+    credentials: async () => {
+      const id = environment.RAGENTS_USER;
+      const password = environment.RAGENTS_PASSWORD;
+      return id && password ? { id, password } : undefined;
     },
-  }),
-});
+  });

package/plugins/ragents.workspace/client/workspace-client.ts

@@ -65,6 +65,7 @@ export interface WorkspaceClientOptions {
 /** What the workstation needs for the server: the message layer. */
 export interface WorkspaceClientTransport {
   readonly rpc: RpcClient;
+  readonly signInFailure?: () => string | undefined;
 }
 
 type ExecuteInput = OperationInput<typeof workspaceClientContracts.execute>;
@@ -255,6 +256,11 @@ export class WorkspaceClient {
     releases.push(
       rpc.handle(workspaceClientContracts.execute, (input, context) => this.#execute(attachment, input, context)),
       rpc.onConnected(() => void this.#announce()),
+      rpc.onStatus((status) => {
+        if (status.kind === "unauthorized" && attachment === this.#attachment) {
+          this.#set({ kind: "failed", message: this.transport.signInFailure?.() ?? "The server requires a sign-in.", mismatch: false });
+        }
+      }),
     );
     this.#attachment = attachment;
     return attachment;
@@ -288,13 +294,14 @@ export class WorkspaceClient {
   #connected(): Promise<void> {
     const rpc = this.transport.rpc;
     if (rpc.status.kind === "connected") return Promise.resolve();
+    if (rpc.status.kind === "unauthorized") return Promise.reject(new Error(this.transport.signInFailure?.() ?? "The server requires a sign-in."));
     return new Promise((settle, fail) => {
       const release = rpc.onStatus((status) => {
         if (status.kind === "connecting") return;
         release();
         if (status.kind === "connected") settle();
         else if (status.kind === "retrying") fail(new Error(status.message));
-        else if (status.kind === "unauthorized") fail(new Error("The server requires a sign-in."));
+        else if (status.kind === "unauthorized") fail(new Error(this.transport.signInFailure?.() ?? "The server requires a sign-in."));
         else fail(new Error("The server's event stream is closed."));
       });
     });

package/scripts/package/ragents.mjs

@@ -3,6 +3,7 @@ import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { terminateProcessTree, watchOwnerLifetime } from "../../packages/workspace-executor/src/owner-lifetime.mjs";
 import { ensureHostLinks } from "./host-links.mjs";
 
 const AGENT_CLI = "scripts/agent/agent-cli.ts";
@@ -55,14 +56,39 @@ const main = () => {
   }
   ensureHostLinks(root);
   const passed = script === AGENT_CLI ? [command, ...rest] : rest;
+  const workspace = command === "workspace-client";
+  const detached = rest.includes("--detached");
   const child = spawn(process.execPath, ["--import", "tsx", path.join(root, script), ...passed], {
     cwd: path.join(root, "apps/server"),
-    env: { ...process.env, RAGENTS_CWD: process.cwd() },
-    stdio: "inherit",
+    env: { ...process.env, RAGENTS_CWD: process.cwd(), ...(workspace ? { RAGENTS_WORKSPACE_OWNER_PID: String(process.ppid) } : {}) },
+    stdio: workspace ? ["ignore", "inherit", "inherit", "ipc"] : "inherit",
+    detached: workspace && process.platform !== "win32",
   });
+  if (workspace) {
+    let stopReason;
+    let deadline;
+    const requestStop = () => {
+      if (child.connected && stopReason) child.send({ type: "workspace-stop", reason: stopReason }, () => undefined);
+    };
+    const release = watchOwnerLifetime({ detached, onStop: (reason) => {
+      stopReason = reason;
+      requestStop();
+      deadline = setTimeout(() => { if (child.pid) terminateProcessTree(child.pid); }, 20_000);
+    } });
+    child.on("message", (message) => { if (message?.type === "workspace-ready") requestStop(); });
+    child.once("exit", () => {
+      release();
+      clearTimeout(deadline);
+      if (process.platform !== "win32" && child.pid) {
+        try { process.kill(-child.pid, "SIGKILL"); } catch {}
+      }
+    });
+  }
   const forward = (signal) => () => child.kill(signal);
-  process.on("SIGINT", forward("SIGINT"));
-  process.on("SIGTERM", forward("SIGTERM"));
+  if (!workspace) {
+    process.on("SIGINT", forward("SIGINT"));
+    process.on("SIGTERM", forward("SIGTERM"));
+  }
   child.once("error", (error) => {
     console.error(`ragents ${command} could not be started: ${error.message}`);
     process.exit(1);

package/scripts/workspace-client/run-workspace-client.ts

@@ -3,25 +3,28 @@ import { statSync } from "node:fs";
 import { hostname } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveBundledTools } from "../../packages/workspace-executor/src/bundled-tools.ts";
+import { exitWorkspaceProcess, watchOwnerLifetime } from "../../packages/workspace-executor/src/owner-lifetime.mjs";
+import { isCheckout } from "../../apps/server/src/host-web.ts";
 import { hostRoot } from "../../apps/server/src/host-version.ts";
 import { callerDirectory } from "../../apps/server/src/profile-target.ts";
 import { provisionWorkspace } from "../../apps/server/src/profile/provisioning.ts";
 import { workspaceClientTransport } from "../../plugins/ragents.workspace/client/transport.ts";
 import { WorkspaceClient, workstationRunsDirectory } from "../../plugins/ragents.workspace/client/workspace-client.ts";
 
-const usage = (): string => `Usage: [RAGENTS_TOKEN=<token>] pnpm workspace-client <server-url> [folder ...] [--id <id>] [--label <name>]
-Registers the folders as a workspace with the server and executes its tasks with the executor
-of this machine - the same as the VS Code extension does, just without VS Code. Without folders
-the current directory applies. Every tool call appears as one line on stdout.
-What the server's plugins contribute to the executor, such as language servers, the workspace loads
-at registration from this host's bundles; startup fetches their tools onto this machine
-(the same as pnpm provision --workspace). On Windows
-RAGENTS_BASH names the bash.exe that RAgents brings along (from the Windows build of the VS Code
-extension); without it the bash tool fails. RAGENTS_RG names an rg whose folder the bash has at the
-front of its PATH, such as the one from the extension; if not given, one in the PATH applies. The
-script runs until it is ended with Ctrl-C.`;
+const usage = (): string => `Usage: ragents workspace-client <server-url> [folder ...] [--id <id>] [--label <name>] [--detached]
+Registers the folders as a workspace and executes tasks with the same tools as VS Code.
+Without folders the current directory applies. Tools are provisioned before registration.
+The npm package includes ripgrep and, on Windows, Bash. In a checkout run pnpm bundle:rg
+(and pnpm bundle:bash on Windows) first.
+Set RAGENTS_TOKEN for an existing session or RAGENTS_USER and RAGENTS_PASSWORD for automatic
+sign-in and renewal. Credentials belong only in the environment.
+By default closing stdin, the terminal, or the owning process ends the client and its children.
+--detached explicitly opts out of terminal and parent ownership for nohup or a service manager;
+SIGINT and SIGTERM still stop it. It does not daemonize the process.`;
 
 export interface WorkspaceClientArguments {
+  readonly detached: boolean;
   readonly serverUrl: string;
   readonly folders: readonly string[];
   readonly id: string | undefined;
@@ -30,11 +33,13 @@ export interface WorkspaceClientArguments {
 
 export const parseArguments = (argv: readonly string[]): WorkspaceClientArguments => {
   const folders: string[] = [];
+  let detached = false;
   let serverUrl: string | undefined;
   let id: string | undefined;
   let label: string | undefined;
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index]!;
+    if (argument === "--detached") { detached = true; continue; }
     if (argument === "--id" || argument === "--label") {
       const value = argv[index + 1];
       if (!value || value.startsWith("-")) throw new Error(`${argument} needs a value.\n${usage()}`);
@@ -49,7 +54,7 @@ export const parseArguments = (argv: readonly string[]): WorkspaceClientArgument
   }
   if (!serverUrl) throw new Error(`The server address is missing.\n${usage()}`);
   if (id !== undefined && !/^[A-Za-z0-9_-]{8,64}$/.test(id)) throw new Error("--id needs 8 to 64 characters from A-Z, a-z, 0-9, _ and -.");
-  return { serverUrl, folders, id, label };
+  return { serverUrl, folders, id, label, detached };
 };
 
 /** A stable id per machine and folder set, so the server recognizes the same workspace again. */
@@ -67,6 +72,27 @@ export const resolvedFolders = (folders: readonly string[], caller = callerDirec
 
 const main = async (): Promise<void> => {
   const parsed = parseArguments(process.argv.slice(2));
+  let stopping: Promise<void> | undefined;
+  const stop = (code: number, reason: string): Promise<void> => stopping ??= (async () => {
+    console.log(`== Stopping workspace: ${reason}`);
+    const force = setTimeout(() => exitWorkspaceProcess(code || 1), 15_000);
+    try {
+      await client.unregister();
+      transport.rpc.close();
+    } finally {
+      clearTimeout(force);
+      exitWorkspaceProcess(code);
+    }
+  })();
+  const releaseOwner = watchOwnerLifetime({
+    detached: parsed.detached,
+    parents: [process.ppid, ...process.env.RAGENTS_WORKSPACE_OWNER_PID ? [Number(process.env.RAGENTS_WORKSPACE_OWNER_PID)] : []],
+    stdin: process.send ? null : process.stdin,
+    onStop: (reason) => { void stop(0, reason); },
+  });
+  process.on("message", (message: unknown) => {
+    if (typeof message === "object" && message !== null && (message as { type?: string }).type === "workspace-stop") void stop(0, "owner stopped");
+  });
   const folders = resolvedFolders(parsed.folders);
   const host = hostname();
   const identity = {
@@ -78,46 +104,37 @@ const main = async (): Promise<void> => {
     runsDirectory: workstationRunsDirectory(),
   };
   const transport = workspaceClientTransport(parsed.serverUrl, process.env.RAGENTS_TOKEN);
+  const root = hostRoot();
+  const tools = resolveBundledTools({ root: isCheckout(root) ? path.join(root, "apps/vscode") : root, distribution: isCheckout(root) ? "extension" : "package" });
   const client = new WorkspaceClient(transport, identity, {
     hostRoot,
-    bash: process.env.RAGENTS_BASH || undefined,
-    rg: process.env.RAGENTS_RG || undefined,
+    ...tools,
     onExecuted: ({ runId, operation, durationMs, error }) =>
       console.log(`== ${runId.slice(0, 8)} ${operation} ${durationMs} ms ${error ?? "ok"}`),
   });
   console.log(`== Workspace ${identity.label} (${identity.id})`);
   for (const folder of folders) console.log(`== Folder ${folder}`);
+  process.send?.({ type: "workspace-ready" });
   console.log("== Provisioning tools");
   await provisionWorkspace((line) => console.log(line));
   console.log(`== Server ${parsed.serverUrl}`);
-  client.onChange(() => {
-    const status = client.status;
+  const workspace = client;
+  workspace.onChange(() => {
+    const status = workspace.status;
     console.log(status.kind === "failed" ? `== Registration failed: ${status.message}` : `== State ${status.kind}`);
+    if (status.kind === "failed" && !stopping && (status.mismatch || transport.rpc.status.kind === "unauthorized")) void stop(1, "registration or sign-in failed");
   });
-  await client.register();
-  if (client.status.kind !== "registered") {
-    process.exitCode = 1;
-    transport.rpc.close();
-    return;
-  }
+  await workspace.register();
+  if (stopping) return;
+  if (workspace.status.kind !== "registered") return stop(1, "registration failed");
   console.log("== Registered; Ctrl-C ends the workspace");
-  await new Promise<void>((finish) => {
-    const stop = () => {
-      process.off("SIGINT", stop);
-      process.off("SIGTERM", stop);
-      finish();
-    };
-    process.on("SIGINT", stop);
-    process.on("SIGTERM", stop);
-  });
-  await client.unregister();
-  transport.rpc.close();
+  process.once("exit", releaseOwner);
 };
 
 const moduleUrl: string | undefined = import.meta.url;
 if (moduleUrl && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(moduleUrl)) {
   main().catch((error: unknown) => {
     console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
+    exitWorkspaceProcess(1);
   });
 }