@schlenkr/ragents 0.1.5 → 0.1.7

package/packages/workspace-executor/src/paths.ts

@@ -1,17 +1,65 @@
 import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
+import { WorkspaceOperationError } from "./errors.js";
 
 export interface ResolvedWorkspaceRoot {
   directory: string;
+  /** `@name`, bei einer Wurzel unter einem gemeinsamen Alias `@name/<ordner>`. */
   alias?: string;
   environmentVariable?: string;
 }
 
+/** Welche Wurzeln die Eingabe einer Operation anspricht: die Aliasse zusätzlicher Wurzeln und ob ein Pfad ohne Alias die Wurzel des Runs nennt. */
+export interface AddressedRoots {
+  readonly aliases: readonly string[];
+  readonly runRoot: boolean;
+}
+
+export const NO_ROOTS: AddressedRoots = { aliases: [], runRoot: false };
+
+/** Was ein Aufrufer über eine Eingabe wissen muss, ohne ihre Form zu kennen: die Wurzeln, die sie anspricht, und die Laufzeit, die sie selbst verlangt. */
+export interface OperationFootprint {
+  readonly roots: AddressedRoots;
+  readonly durationMs?: number;
+}
+
+/** Der Alias, mit dem ein Pfad beginnt, ist sein erster Abschnitt, wenn der mit @ beginnt. */
+export const aliasOf = (location: string): string | undefined =>
+  location.startsWith("@") ? location.split("/")[0] : undefined;
+
+/** Die Wurzeln, die Felder einer Eingabe als Pfade nennen, eine Liste mit jedem Eintrag: ein Pfad mit Alias dessen Wurzel, jeder andere die des Runs. */
+export const rootsOfFields = (input: unknown, ...keys: readonly string[]): AddressedRoots => {
+  const fields: Readonly<Record<string, unknown>> = typeof input === "object" && input !== null ? input as Record<string, unknown> : {};
+  const named = keys.flatMap((key) => [fields[key]].flat()).filter((entry): entry is string => typeof entry === "string");
+  const aliases = named.map(aliasOf).filter((alias): alias is string => alias !== undefined);
+  return { aliases: [...new Set(aliases)], runRoot: named.some((entry) => aliasOf(entry) === undefined) };
+};
+
+/** Die Wurzel, die ein Pfad mit Alias nennt, und der Rest darunter; ohne passenden Alias keine. */
+export const aliasedRoot = (
+  requested: string,
+  aliases: Readonly<Record<string, string>>,
+): { directory: string; rest: string } | undefined => {
+  const found = Object.entries(aliases).find(([alias]) => requested === alias || requested.startsWith(`${alias}/`));
+  return found && { directory: found[1], rest: requested.slice(found[0].length + 1) };
+};
+
+/** Nennt bei einem gemeinsamen Alias wie `@skills` auch den Ordner darunter, weil erst beide eine Wurzel bestimmen. */
+export const unknownAliasError = (requested: string, aliases: Readonly<Record<string, string>>): WorkspaceOperationError => {
+  const [first, second] = requested.split("/");
+  const known = Object.keys(aliases);
+  const named = second !== undefined && known.some((alias) => alias.startsWith(`${first}/`)) ? `${first}/${second}` : first;
+  return new WorkspaceOperationError(
+    "workspace-alias-unknown",
+    `Unbekannter Arbeitsverzeichnis-Alias: ${named} (bekannt: ${known.length > 0 ? known.join(", ") : "keine"})`,
+    400,
+  );
+};
+
 export const expandWorkspaceAlias = (requested: string, aliases: Readonly<Record<string, string>>): string => {
-  for (const [alias, directory] of Object.entries(aliases)) {
-    if (requested === alias || requested.startsWith(`${alias}/`)) return path.join(directory, requested.slice(alias.length));
-  }
-  if (requested.startsWith("@")) throw new Error(`Unbekannter Arbeitsverzeichnis-Alias: ${requested.split("/")[0]}`);
+  const found = aliasedRoot(requested, aliases);
+  if (found) return path.join(found.directory, found.rest);
+  if (requested.startsWith("@")) throw unknownAliasError(requested, aliases);
   return requested;
 };
 
@@ -33,7 +81,11 @@ export const resolvedWorkspacePath = async (filename: string): Promise<string> =
   }
 };
 
-export const containsWorkspacePath = (root: string, filename: string): boolean => filename === root || filename.startsWith(`${root}${path.sep}`);
+/** Liegt der Pfad in der Wurzel oder ist er sie selbst; auch für eine Laufwerkswurzel wie `/` oder `C:\`. */
+export const containsWorkspacePath = (root: string, filename: string): boolean => {
+  const relative = path.relative(root, filename);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+};
 
 export const allowedWorkspacePath = async (filename: string, roots: readonly string[]): Promise<string> => {
   const absolute = await resolvedWorkspacePath(filename);

package/packages/workspace-executor/src/process-sandbox.ts

@@ -0,0 +1,16 @@
+import type { WorkspaceProcessContext } from "./context.js";
+
+/** Ein Programm mit seinen Argumenten, so wie es gestartet wird. */
+export interface ProcessLaunch {
+  readonly command: string;
+  readonly args: readonly string[];
+}
+
+/** Wie ein Executor die Prozesse eines Runs in seine Sandbox steckt; der Kontext trägt sie, jeder Start fragt sie. */
+export interface ProcessSandbox {
+  readonly wrap: (launch: ProcessLaunch) => Promise<ProcessLaunch>;
+}
+
+/** Der Start eines Prozesses im Kontext eines Runs: mit Sandbox eingepackt, ohne unverändert. */
+export const sandboxedLaunch = (context: WorkspaceProcessContext, launch: ProcessLaunch): Promise<ProcessLaunch> =>
+  context.sandbox ? context.sandbox.wrap(launch) : Promise.resolve(launch);

package/packages/workspace-executor/src/processes/module.ts

@@ -0,0 +1,48 @@
+import { WorkspaceOperationError } from "../errors.js";
+import type { WorkspaceModuleFactory } from "../module.js";
+import { hasProcessTable, processTableForPlatform, type ProcessTable } from "./process-table.js";
+import { ProcessScanner } from "./scanner.js";
+import { RunProcessTerminator } from "./terminator.js";
+
+export const PROCESS_OPERATIONS = {
+  snapshot: "processes.snapshot",
+  stop: "processes.stop",
+  stopAll: "processes.stopAll",
+} as const;
+
+export interface ProcessModuleOptions {
+  /** Die Prozesstabelle dieser Maschine; ohne Angabe die der Plattform, aufgelöst erst im Aufruf. */
+  table?: () => ProcessTable;
+}
+
+const processIdOf = (input: unknown): string => {
+  const value = (input as { processId?: unknown } | null)?.processId;
+  if (typeof value !== "string") throw new WorkspaceOperationError("invalid-process", "Ungültige Prozessreferenz", 400);
+  return value;
+};
+
+/** Die markierten Prozesse eines Runs auf dieser Maschine; ohne Prozesstabelle (Windows) räumt der Stopp nur die Bash-Bäume ab. */
+export const processModule = (options: ProcessModuleOptions = {}): WorkspaceModuleFactory => () => {
+  const table = options.table ?? (() => processTableForPlatform());
+  const cleansUp = options.table !== undefined || hasProcessTable();
+  const identity = { executorPid: process.pid, executorUid: process.getuid?.() };
+  const scanner = new ProcessScanner({ table, ...identity });
+  const terminator = (): RunProcessTerminator => new RunProcessTerminator({ table: table(), ...identity });
+  const stopAll = async (runId: string, signal?: AbortSignal): Promise<null> => {
+    if (cleansUp) await terminator().stopRun(runId, signal ? { signal } : {});
+    return null;
+  };
+  return {
+    operations: {
+      [PROCESS_OPERATIONS.snapshot]: ({ runId }) => scanner.snapshot(runId),
+      [PROCESS_OPERATIONS.stop]: async ({ runId, input, signal }) => {
+        await terminator().stop(runId, processIdOf(input), signal ? { signal } : {});
+        return null;
+      },
+      [PROCESS_OPERATIONS.stopAll]: ({ runId, signal }) => stopAll(runId, signal),
+    },
+    stopRun: async (runId) => {
+      await stopAll(runId);
+    },
+  };
+};

package/{plugins/ragents.processes/server → packages/workspace-executor/src/processes}/process-table.ts

@@ -2,8 +2,12 @@ import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { readdir, readFile, readlink } from "node:fs/promises";
 import { promisify } from "node:util";
-import { RUN_MARKER_ENV, runMarkerOf } from "@aicontainer/workspace-executor";
-import type { RunProcessPort } from "../contract.js";
+import { RUN_MARKER_ENV, runMarkerOf } from "../run-marker.js";
+
+export interface WorkspaceProcessPort {
+  port: number;
+  address: string;
+}
 
 const execFileAsync = promisify(execFile);
 
@@ -19,7 +23,7 @@ export interface ProcessRecord {
 export interface ProcessTable {
   list: () => Promise<ProcessRecord[]>;
   runMarkers: (pids: readonly number[]) => Promise<Map<number, string>>;
-  listeningPorts: (pids: readonly number[]) => Promise<Map<number, RunProcessPort[]>>;
+  listeningPorts: (pids: readonly number[]) => Promise<Map<number, WorkspaceProcessPort[]>>;
 }
 
 export const processIdOf = (record: Pick<ProcessRecord, "pid" | "startKey">): string =>
@@ -46,7 +50,7 @@ const runCommand = async (file: string, args: string[], toleratedExitCodes: read
   }
 };
 
-const addPort = (ports: RunProcessPort[], port: RunProcessPort): void => {
+const addPort = (ports: WorkspaceProcessPort[], port: WorkspaceProcessPort): void => {
   if (!ports.some((known) => known.port === port.port && known.address === port.address)) ports.push(port);
 };
 
@@ -93,7 +97,7 @@ export const parseDarwinMarkers = (text: string, commands?: ReadonlyMap<number,
   return markers;
 };
 
-const portFromLsofName = (name: string): RunProcessPort | undefined => {
+const portFromLsofName = (name: string): WorkspaceProcessPort | undefined => {
   const separator = name.lastIndexOf(":");
   if (separator < 0) return undefined;
   const port = Number(name.slice(separator + 1));
@@ -103,9 +107,9 @@ const portFromLsofName = (name: string): RunProcessPort | undefined => {
   return { port, address: wildcard ? WILDCARD : host.replace(/^\[|\]$/g, "") };
 };
 
-export const parseLsofListeners = (text: string): Map<number, RunProcessPort[]> => {
-  const listeners = new Map<number, RunProcessPort[]>();
-  let current: RunProcessPort[] | undefined;
+export const parseLsofListeners = (text: string): Map<number, WorkspaceProcessPort[]> => {
+  const listeners = new Map<number, WorkspaceProcessPort[]>();
+  let current: WorkspaceProcessPort[] | undefined;
   for (const line of text.split("\n")) {
     if (line.startsWith("p")) {
       const pid = Number(line.slice(1));
@@ -160,7 +164,7 @@ export const darwinProcessTable = (command: typeof runCommand = runCommand): Pro
     return markers;
   },
   listeningPorts: async (pids) => {
-    const listeners = new Map<number, RunProcessPort[]>();
+    const listeners = new Map<number, WorkspaceProcessPort[]>();
     for (const chunk of chunked(pids)) {
       const output = await command(
         "lsof",
@@ -173,13 +177,16 @@ export const darwinProcessTable = (command: typeof runCommand = runCommand): Pro
   },
 });
 
-const PROC = "/proc";
-
 const isGone = (error: unknown): boolean => {
   const code = (error as NodeJS.ErrnoException).code;
   return code === "ENOENT" || code === "ESRCH";
 };
 
+const isDenied = (error: unknown): boolean => {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "EACCES" || code === "EPERM";
+};
+
 const explainAccess = (error: unknown, pid: number, what: string): Error => {
   const code = (error as NodeJS.ErrnoException).code;
   if (code === "EACCES" || code === "EPERM") {
@@ -258,7 +265,7 @@ export const addressFromHex = (hex: string): string => {
 
 export interface LinuxListener {
   inode: string;
-  port: RunProcessPort;
+  port: WorkspaceProcessPort;
 }
 
 export const parseLinuxTcpTable = (text: string): LinuxListener[] =>
@@ -273,15 +280,15 @@ export const parseLinuxTcpTable = (text: string): LinuxListener[] =>
 const numericEntries = async (directory: string): Promise<number[]> =>
   (await readdir(directory)).filter((name) => /^\d+$/.test(name)).map(Number);
 
-const readLinuxRecord = async (pid: number): Promise<ProcessRecord | undefined> => {
+const readLinuxRecord = async (proc: string, pid: number): Promise<ProcessRecord | undefined> => {
   let stat: string;
   let status: string;
   let cmdline: Buffer;
   try {
     [stat, status, cmdline] = await Promise.all([
-      readFile(`${PROC}/${pid}/stat`, "utf8"),
-      readFile(`${PROC}/${pid}/status`, "utf8"),
-      readFile(`${PROC}/${pid}/cmdline`),
+      readFile(`${proc}/${pid}/stat`, "utf8"),
+      readFile(`${proc}/${pid}/status`, "utf8"),
+      readFile(`${proc}/${pid}/cmdline`),
     ]);
   } catch (error) {
     if (isGone(error)) return undefined;
@@ -290,7 +297,7 @@ const readLinuxRecord = async (pid: number): Promise<ProcessRecord | undefined>
   const parsed = parseLinuxStat(stat);
   if (parsed.state === "Z") return undefined;
   const uid = Number(/^Uid:\s+(\d+)/m.exec(status)?.[1]);
-  if (!Number.isInteger(uid)) throw new Error(`${PROC}/${pid}/status nennt keine Uid`);
+  if (!Number.isInteger(uid)) throw new Error(`${proc}/${pid}/status nennt keine Uid`);
   const args = cmdline.toString("utf8").split("\0").filter((argument) => argument !== "");
   return {
     pid,
@@ -302,12 +309,12 @@ const readLinuxRecord = async (pid: number): Promise<ProcessRecord | undefined>
   };
 };
 
-const readLinuxMarker = async (pid: number): Promise<string | undefined> => {
+const readLinuxMarker = async (proc: string, pid: number, asRoot: boolean): Promise<string | undefined> => {
   let environ: Buffer;
   try {
-    environ = await readFile(`${PROC}/${pid}/environ`);
+    environ = await readFile(`${proc}/${pid}/environ`);
   } catch (error) {
-    if (isGone(error)) return undefined;
+    if (isGone(error) || (isDenied(error) && !asRoot)) return undefined;
     throw explainAccess(error, pid, "Die Umgebung");
   }
   const prefix = `${RUN_MARKER_ENV}=`;
@@ -315,12 +322,12 @@ const readLinuxMarker = async (pid: number): Promise<string | undefined> => {
   return runMarkerOf(entry?.slice(prefix.length));
 };
 
-const linuxListeningInodes = async (): Promise<Map<string, RunProcessPort>> => {
-  const inodes = new Map<string, RunProcessPort>();
+const linuxListeningInodes = async (proc: string): Promise<Map<string, WorkspaceProcessPort>> => {
+  const inodes = new Map<string, WorkspaceProcessPort>();
   for (const table of ["tcp", "tcp6"]) {
     let text: string;
     try {
-      text = await readFile(`${PROC}/net/${table}`, "utf8");
+      text = await readFile(`${proc}/net/${table}`, "utf8");
     } catch (error) {
       if (isGone(error)) continue;
       throw error;
@@ -330,13 +337,13 @@ const linuxListeningInodes = async (): Promise<Map<string, RunProcessPort>> => {
   return inodes;
 };
 
-const linuxSocketInodes = async (pid: number): Promise<string[]> => {
-  const directory = `${PROC}/${pid}/fd`;
+const linuxSocketInodes = async (proc: string, pid: number, asRoot: boolean): Promise<string[]> => {
+  const directory = `${proc}/${pid}/fd`;
   let names: string[];
   try {
     names = await readdir(directory);
   } catch (error) {
-    if (isGone(error)) return [];
+    if (isGone(error) || (isDenied(error) && !asRoot)) return [];
     throw explainAccess(error, pid, "Die Dateideskriptoren");
   }
   const inodes: string[] = [];
@@ -345,7 +352,7 @@ const linuxSocketInodes = async (pid: number): Promise<string[]> => {
     try {
       target = await readlink(`${directory}/${name}`);
     } catch (error) {
-      if (isGone(error)) continue;
+      if (isGone(error) || (isDenied(error) && !asRoot)) continue;
       throw explainAccess(error, pid, "Die Dateideskriptoren");
     }
     const match = /^socket:\[(\d+)\]$/.exec(target);
@@ -354,42 +361,58 @@ const linuxSocketInodes = async (pid: number): Promise<string[]> => {
   return inodes;
 };
 
-const linuxProcessTable = (): ProcessTable => ({
-  list: async () => {
-    const records = await Promise.all((await numericEntries(PROC)).map(readLinuxRecord));
-    return records.filter((record): record is ProcessRecord => record !== undefined);
-  },
-  runMarkers: async (pids) => {
-    const markers = new Map<number, string>();
-    for (const pid of pids) {
-      const marker = await readLinuxMarker(pid);
-      if (marker) markers.set(pid, marker);
-    }
-    return markers;
-  },
-  listeningPorts: async (pids) => {
-    const listeners = new Map<number, RunProcessPort[]>();
-    if (pids.length === 0) return listeners;
-    const inodes = await linuxListeningInodes();
-    if (inodes.size === 0) return listeners;
-    for (const pid of pids) {
-      const ports: RunProcessPort[] = [];
-      for (const inode of await linuxSocketInodes(pid)) {
-        const port = inodes.get(inode);
-        if (port) addPort(ports, port);
+export interface LinuxProcessTableOptions {
+  /** Der Ordner der Prozessdateien; Tests nennen einen eigenen. */
+  readonly proc?: string;
+  /** Als root ist eine gesperrte Umgebung ein fehlendes Recht; sonst hat sich ein eigener Prozess unlesbar gemacht. */
+  readonly asRoot?: boolean;
+}
+
+/** Ohne root liest die Tabelle nur eigene Prozesse; einer, der sich unlesbar gemacht hat (PR_SET_DUMPABLE, etwa ein Chrome-Helfer oder ssh-agent), trägt keinen erkennbaren Marker. */
+export const linuxProcessTable = (options: LinuxProcessTableOptions = {}): ProcessTable => {
+  const proc = options.proc ?? "/proc";
+  const asRoot = options.asRoot ?? process.getuid?.() === 0;
+  return {
+    list: async () => {
+      const records = await Promise.all((await numericEntries(proc)).map((pid) => readLinuxRecord(proc, pid)));
+      return records.filter((record): record is ProcessRecord => record !== undefined);
+    },
+    runMarkers: async (pids) => {
+      const markers = new Map<number, string>();
+      for (const pid of pids) {
+        const marker = await readLinuxMarker(proc, pid, asRoot);
+        if (marker) markers.set(pid, marker);
       }
-      if (ports.length > 0) listeners.set(pid, ports);
-    }
-    return listeners;
-  },
-});
+      return markers;
+    },
+    listeningPorts: async (pids) => {
+      const listeners = new Map<number, WorkspaceProcessPort[]>();
+      if (pids.length === 0) return listeners;
+      const inodes = await linuxListeningInodes(proc);
+      if (inodes.size === 0) return listeners;
+      for (const pid of pids) {
+        const ports: WorkspaceProcessPort[] = [];
+        for (const inode of await linuxSocketInodes(proc, pid, asRoot)) {
+          const port = inodes.get(inode);
+          if (port) addPort(ports, port);
+        }
+        if (ports.length > 0) listeners.set(pid, ports);
+      }
+      return listeners;
+    },
+  };
+};
+
+/** Nur macOS und Linux haben eine Prozesstabelle, aus der sich Run-Marker lesen lassen. */
+export const hasProcessTable = (platform: NodeJS.Platform = process.platform): boolean =>
+  platform === "darwin" || platform === "linux";
 
 export const processTableForPlatform = (platform: NodeJS.Platform = process.platform): ProcessTable => {
   if (platform === "darwin") return darwinProcessTable();
   if (platform === "linux") return linuxProcessTable();
   if (platform === "win32") {
-    throw new Error("Das Plugin ragents.processes läuft nicht unter Windows: für win32 gibt es keine Prozesstabelle. "
-      + "Nimm ragents.processes aus der Plugin-Liste des Profils; die Werkzeuge des Arbeitsbereichs brauchen es nicht.");
+    throw new Error("Unter Windows gibt es keine Prozesstabelle: für Runs, die auf diesem Rechner arbeiten, zeigt und beendet "
+      + "die Prozessüberwachung nichts. Die Werkzeuge des Arbeitsbereichs brauchen sie nicht.");
   }
   throw new Error(`Die Prozessüberwachung kennt die Plattform ${platform} nicht (nur darwin und linux)`);
 };

package/packages/workspace-executor/src/processes/scanner.ts

@@ -0,0 +1,106 @@
+import type { ProcessRecord, ProcessTable, WorkspaceProcessPort } from "./process-table.js";
+import { runProcessesFrom, type WorkspaceProcess } from "./snapshot.js";
+
+export interface WorkspaceProcessSnapshot {
+  observedAt: string;
+  processes: WorkspaceProcess[];
+}
+
+export interface ProcessScannerOptions {
+  table: () => ProcessTable;
+  executorPid: number;
+  executorUid: number | undefined;
+  now?: () => Date;
+}
+
+interface Scan {
+  records: readonly ProcessRecord[];
+  observedAt: string;
+  markers: ReadonlyMap<number, string | undefined>;
+  firstSeen: ReadonlyMap<number, string>;
+}
+
+const keyOf = (record: ProcessRecord): string => `${record.pid}:${record.startKey}`;
+
+/** Liest die markierten Prozesse dieser Maschine; gleichzeitige Abfragen mehrerer Runs teilen sich einen Tabellenscan. */
+export class ProcessScanner {
+  readonly #options: ProcessScannerOptions;
+  readonly #now: () => Date;
+  readonly #markers = new Map<string, string | null>();
+  readonly #firstSeen = new Map<string, string>();
+  #scanning: Promise<Scan> | undefined;
+
+  constructor(options: ProcessScannerOptions) {
+    this.#options = options;
+    this.#now = options.now ?? (() => new Date());
+  }
+
+  async snapshot(runId: string): Promise<WorkspaceProcessSnapshot> {
+    const scan = await this.#shared();
+    const markerOf = (record: ProcessRecord): string | undefined => scan.markers.get(record.pid);
+    const marked = scan.records.filter((record) => markerOf(record) === runId);
+    const ports: ReadonlyMap<number, readonly WorkspaceProcessPort[]> = marked.length > 0
+      ? await this.#options.table().listeningPorts(marked.map((record) => record.pid))
+      : new Map();
+    return {
+      observedAt: scan.observedAt,
+      processes: runProcessesFrom({
+        runId,
+        executorPid: this.#options.executorPid,
+        records: scan.records,
+        markerOf,
+        ports,
+        firstSeen: (record) => {
+          const seen = scan.firstSeen.get(record.pid);
+          if (!seen) throw new Error(`Prozess ${record.pid} ohne Erstsichtung`);
+          return seen;
+        },
+      }),
+    };
+  }
+
+  #shared(): Promise<Scan> {
+    this.#scanning ??= this.#scan().finally(() => {
+      this.#scanning = undefined;
+    });
+    return this.#scanning;
+  }
+
+  #readable(record: ProcessRecord): boolean {
+    const uid = this.#options.executorUid;
+    return uid === undefined || uid === 0 || record.uid === uid;
+  }
+
+  /** Die Umgebung eines Prozesses wird nur einmal gelesen; ein Fehler dabei merkt sich nichts. */
+  async #scan(): Promise<Scan> {
+    const table = this.#options.table();
+    const records = await table.list();
+    const observedAt = this.#now().toISOString();
+    const present = new Set<string>();
+    const unknown: ProcessRecord[] = [];
+    for (const record of records) {
+      const key = keyOf(record);
+      present.add(key);
+      if (!this.#firstSeen.has(key)) this.#firstSeen.set(key, observedAt);
+      if (!this.#markers.has(key) && this.#readable(record)) unknown.push(record);
+    }
+    if (unknown.length > 0) {
+      const found = await table.runMarkers(unknown.map((record) => record.pid));
+      for (const record of unknown) this.#markers.set(keyOf(record), found.get(record.pid) ?? null);
+    }
+    for (const key of [...this.#markers.keys(), ...this.#firstSeen.keys()]) {
+      if (present.has(key)) continue;
+      this.#markers.delete(key);
+      this.#firstSeen.delete(key);
+    }
+    return {
+      records,
+      observedAt,
+      markers: new Map(records.map((record) => [record.pid, this.#markers.get(keyOf(record)) ?? undefined])),
+      firstSeen: new Map(records.flatMap((record) => {
+        const seen = this.#firstSeen.get(keyOf(record));
+        return seen === undefined ? [] : [[record.pid, seen] as const];
+      })),
+    };
+  }
+}

package/{plugins/ragents.processes/server → packages/workspace-executor/src/processes}/snapshot.ts

@@ -1,6 +1,17 @@
 import path from "node:path";
-import type { RunProcess, RunProcessPort } from "../contract.js";
-import { processIdOf, type ProcessRecord } from "./process-table.js";
+import { processIdOf, type ProcessRecord, type WorkspaceProcessPort } from "./process-table.js";
+
+export type WorkspaceProcessOrigin = "tool-call" | "background";
+
+export interface WorkspaceProcess {
+  id: string;
+  pid: number;
+  label: string;
+  command: string;
+  origin: WorkspaceProcessOrigin;
+  ports: WorkspaceProcessPort[];
+  seenSince: string;
+}
 
 const INTERPRETERS = new Set(["node", "nodejs", "bun", "deno", "tsx", "python", "python3", "dotnet", "ruby", "perl", "java"]);
 const INLINE_SCRIPT_FLAGS = new Set(["-e", "--eval", "-p", "--print", "-c"]);
@@ -22,29 +33,30 @@ export const labelOf = (command: string): string => {
 
 export interface ObservationInput {
   runId: string;
-  serverPid: number;
+  /** Der Prozess dieses Executors; seine direkten Kinder sind laufende Werkzeugaufrufe. */
+  executorPid: number;
   records: readonly ProcessRecord[];
   markerOf: (record: ProcessRecord) => string | undefined;
-  ports: ReadonlyMap<number, readonly RunProcessPort[]>;
+  ports: ReadonlyMap<number, readonly WorkspaceProcessPort[]>;
   firstSeen: (record: ProcessRecord) => string;
 }
 
-const wildcardFirst = (port: RunProcessPort): number => port.address === "*" ? 0 : 1;
+const wildcardFirst = (port: WorkspaceProcessPort): number => port.address === "*" ? 0 : 1;
 
-const byPort = (left: RunProcessPort, right: RunProcessPort): number =>
+const byPort = (left: WorkspaceProcessPort, right: WorkspaceProcessPort): number =>
   left.port - right.port || wildcardFirst(left) - wildcardFirst(right) || left.address.localeCompare(right.address);
 
-const byAppearance = (left: RunProcess, right: RunProcess): number =>
+const byAppearance = (left: WorkspaceProcess, right: WorkspaceProcess): number =>
   left.seenSince.localeCompare(right.seenSince) || left.pid - right.pid;
 
-/** Prozesse des Laufs: Hintergrundprozesse immer, Kinder eines laufenden Werkzeugaufrufs nur mit offenem Port. */
-export const runProcessesFrom = (input: ObservationInput): RunProcess[] => {
+/** Prozesse des Runs: Hintergrundprozesse immer, Kinder eines laufenden Werkzeugaufrufs nur mit offenem Port. */
+export const runProcessesFrom = (input: ObservationInput): WorkspaceProcess[] => {
   const toolCallGroups = new Set(
-    input.records.filter((record) => record.ppid === input.serverPid).map((record) => record.pgid),
+    input.records.filter((record) => record.ppid === input.executorPid).map((record) => record.pgid),
   );
   return input.records
     .filter((record) => input.markerOf(record) === input.runId)
-    .filter((record) => record.pid !== input.serverPid)
+    .filter((record) => record.pid !== input.executorPid)
     .flatMap((record) => {
       const ports = [...(input.ports.get(record.pid) ?? [])].sort(byPort);
       const origin = toolCallGroups.has(record.pgid) ? "tool-call" as const : "background" as const;