@schlenkr/ragents 0.1.4 → 0.1.6

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

@@ -0,0 +1,170 @@
+import type { WorkspaceProcessContext } from "./context.js";
+import { WorkspaceOperationError } from "./errors.js";
+import { workspaceDirectory } from "./files.js";
+import { runManagedProcess } from "./managed-process.js";
+import type { WorkspaceModuleFactory, WorkspaceOperation } from "./module.js";
+import type { OperationFootprint } from "./paths.js";
+import { sandboxedLaunch } from "./process-sandbox.js";
+
+export const COMMAND_OPERATIONS = {
+  run: "commands.run",
+} as const;
+
+/** Die größte Ausgabe je Datenstrom, die ein Aufruf zurückgibt; was darüber hinausgeht, verwirft er und meldet die Kürzung. */
+export const COMMAND_OUTPUT_LIMIT = 2 * 1024 * 1024;
+
+export interface CommandRunInput {
+  /** Ein Name aus dem PATH des Executors oder der Pfad eines Programms; es läuft ohne Shell. */
+  program: string;
+  args?: readonly string[];
+  /** Der Arbeitsordner relativ zur Wurzel des Runs; ohne Angabe die Wurzel selbst. */
+  cwd?: string;
+  timeoutMs: number;
+  /** Höchstens so viele Bytes je Datenstrom; ohne Angabe `COMMAND_OUTPUT_LIMIT`. */
+  maxOutputBytes?: number;
+}
+
+export interface CommandResult {
+  /** `null`, wenn der Prozess durch ein Signal endete. */
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+}
+
+interface CheckedCommand {
+  readonly program: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly timeoutMs: number;
+  readonly maxOutputBytes: number;
+}
+
+interface RunningCommand {
+  readonly controller: AbortController;
+  readonly finished: Promise<unknown>;
+}
+
+const invalid = (message: string): WorkspaceOperationError => new WorkspaceOperationError("command-invalid", message, 400);
+
+const textWithoutNul = (value: unknown): value is string => typeof value === "string" && !value.includes("\0");
+
+const checkedCommand = (input: unknown, platform: NodeJS.Platform): CheckedCommand => {
+  const value = (input ?? {}) as Partial<Record<keyof CommandRunInput, unknown>>;
+  const { program, args = [], cwd = "", timeoutMs, maxOutputBytes = COMMAND_OUTPUT_LIMIT } = value;
+  if (!textWithoutNul(program) || program === "") throw invalid("Der Befehl braucht ein Programm als Text");
+  if (platform === "win32" && /\.(cmd|bat)$/i.test(program)) throw invalid(`${program} braucht unter Windows eine Shell; ein Befehl läuft ohne`);
+  if (!Array.isArray(args) || !args.every(textWithoutNul)) throw invalid("Die Argumente müssen Texte ohne Nullzeichen sein");
+  if (typeof cwd !== "string") throw invalid("Der Arbeitsordner muss ein Text sein");
+  if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw invalid("Die Zeitgrenze muss eine positive ganze Zahl in Millisekunden sein");
+  }
+  if (typeof maxOutputBytes !== "number" || !Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 0 || maxOutputBytes > COMMAND_OUTPUT_LIMIT) {
+    throw invalid(`Die Ausgabegrenze liegt zwischen 0 und ${COMMAND_OUTPUT_LIMIT} Bytes`);
+  }
+  return { program, args, cwd, timeoutMs, maxOutputBytes };
+};
+
+/** Sammelt einen Datenstrom bis zur Grenze; der Rest wird verworfen, der Prozess läuft weiter. */
+const boundedOutput = (limit: number) => {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  let truncated = false;
+  return {
+    add: (chunk: Buffer): void => {
+      const kept = chunk.subarray(0, Math.max(0, limit - size));
+      if (kept.length < chunk.length) truncated = true;
+      if (kept.length === 0) return;
+      chunks.push(kept);
+      size += kept.length;
+    },
+    text: (): string => Buffer.concat(chunks, size).toString("utf8"),
+    truncated: (): boolean => truncated,
+  };
+};
+
+const unavailable = (program: string, error: unknown): WorkspaceOperationError | undefined => {
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code === "ENOENT") return new WorkspaceOperationError("command-unavailable", `Das Programm ${program} gibt es auf diesem Rechner nicht`, 409);
+  if (code === "EACCES") return new WorkspaceOperationError("command-unavailable", `Das Programm ${program} ist auf diesem Rechner nicht ausführbar`, 409);
+  return undefined;
+};
+
+const runCommand = async (context: WorkspaceProcessContext, command: CheckedCommand, signal: AbortSignal): Promise<CommandResult> => {
+  const cwd = await workspaceDirectory(context.root, command.cwd);
+  const stdout = boundedOutput(command.maxOutputBytes);
+  const stderr = boundedOutput(command.maxOutputBytes);
+  const launch = await sandboxedLaunch(context, { command: command.program, args: command.args });
+  signal.throwIfAborted();
+  const result = await runManagedProcess({
+    command: launch.command,
+    args: [...launch.args],
+    cwd,
+    env: context.env,
+    uid: context.uid,
+    gid: context.gid,
+    label: command.program,
+    signal,
+    timeoutMs: command.timeoutMs,
+    onStdout: stdout.add,
+    onStderr: stderr.add,
+  }).catch((error: unknown) => {
+    throw unavailable(command.program, error) ?? error;
+  });
+  if (result.timedOut) {
+    throw new WorkspaceOperationError("command-timeout", `${command.program} hat die Zeitgrenze von ${command.timeoutMs} ms überschritten`, 504);
+  }
+  return {
+    exitCode: result.code,
+    stdout: stdout.text(),
+    stderr: stderr.text(),
+    stdoutTruncated: stdout.truncated(),
+    stderrTruncated: stderr.truncated(),
+  };
+};
+
+/** Ein Befehl läuft in der Wurzel des Runs, ein Alias gilt dort nicht; seine Zeitgrenze verlängert, wie lange ein entfernter Executor auf ihn warten darf. */
+const commandFootprint = (input: unknown): OperationFootprint => {
+  const timeoutMs = typeof input === "object" && input !== null ? (input as { timeoutMs?: unknown }).timeoutMs : undefined;
+  return { roots: { aliases: [], runRoot: true }, ...(typeof timeoutMs === "number" && timeoutMs > 0 ? { durationMs: timeoutMs } : {}) };
+};
+
+/** Befehle im Arbeitsbereich des Runs: ein Programm mit Argumenten, ohne Shell, in einem Ordner unter der Wurzel, mit der Umgebung dieses Executors. */
+export const commandModule = (platform: NodeJS.Platform = process.platform): WorkspaceModuleFactory => (host) => {
+  const running = new Map<string, Set<RunningCommand>>();
+  const stopAll = async (commands: readonly RunningCommand[]): Promise<void> => {
+    for (const command of commands) command.controller.abort(new Error("Der Befehl wurde mit seinem Run beendet"));
+    await Promise.allSettled(commands.map((command) => command.finished));
+  };
+  const run: WorkspaceOperation = async ({ runId, input, signal }) => {
+    const command = checkedCommand(input, platform);
+    const controller = new AbortController();
+    const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    const finished = (async (): Promise<CommandResult> => {
+      const context = await host.contextFor(runId);
+      combined.throwIfAborted();
+      const execute = (): Promise<CommandResult> => runCommand(context, command, combined);
+      return context.runOperation ? context.runOperation(execute) : execute();
+    })();
+    const entry: RunningCommand = { controller, finished };
+    const commands = running.get(runId) ?? new Set<RunningCommand>();
+    running.set(runId, commands.add(entry));
+    try {
+      return await finished;
+    } finally {
+      commands.delete(entry);
+      if (commands.size === 0) running.delete(runId);
+    }
+  };
+  return {
+    operations: {
+      [COMMAND_OPERATIONS.run]: run,
+    },
+    footprints: {
+      [COMMAND_OPERATIONS.run]: commandFootprint,
+    },
+    stopRun: (runId) => stopAll([...running.get(runId) ?? []]),
+    shutdown: () => stopAll([...running.values()].flatMap((commands) => [...commands])),
+  };
+};

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

@@ -1,6 +1,7 @@
 import { withGitConfigPairs, type GitConfigPairs } from "./git-config-environment.js";
+import type { ProcessSandbox } from "./process-sandbox.js";
 import { RUN_MARKER_ENV } from "./run-marker.js";
-import { safeProcessEnvironment } from "./safe-environment.js";
+import { inheritedProcessEnvironment, safeProcessEnvironment } from "./safe-environment.js";
 import type { SessionIdent } from "./session-ident.js";
 import type { ResolvedWorkspaceRoot } from "./paths.js";
 
@@ -22,6 +23,10 @@ export interface WorkspaceProcessContext {
   workspaceAliases?: Readonly<Record<string, string>>;
   pathVariables?: Readonly<Record<string, string>>;
   runOperation?: <T>(operation: () => Promise<T>) => Promise<T>;
+  /** Die Prozess-Sandbox dieses Runs; fehlt sie, starten Prozesse ohne. */
+  sandbox?: ProcessSandbox;
+  /** Die Bash, mit der das Werkzeug bash startet; unter Windows Pflicht, sonst gilt ohne Angabe die des Systems. */
+  bash?: string;
 }
 
 export interface SandboxHomeEnvironment {
@@ -29,7 +34,12 @@ export interface SandboxHomeEnvironment {
   nugetPackages?: string;
 }
 
+/** Woraus die Umgebung eines Prozesses entsteht: "safe" nimmt nur die sichere Auswahl (Server), "inherited" alles außer Editor-Variablen und Bash-Startdateien (eigener Rechner). */
+export type BaseEnvironment = "safe" | "inherited";
+
 export interface SandboxEnvironmentOptions {
+  /** Ohne Angabe "safe": wer nichts wählt, gibt nur die sichere Auswahl weiter. */
+  base?: BaseEnvironment;
   home: SandboxHomeEnvironment;
   ident?: { name: string };
   pathVariables?: Readonly<Record<string, string>>;
@@ -59,16 +69,19 @@ export const sandboxRunEnvironment = (runId: string, workspace: {
   ...workspace.gitEnv,
 });
 
-/** Die Umgebung eines Sandbox-Prozesses: die sichere Umgebung dieser Maschine plus die Beiträge des Runs. */
+/** Ohne eigenes Konto läuft der Prozess unter dem Benutzer dieser Maschine und trägt dessen Namen. */
+const accountEnvironment = (source: NodeJS.ProcessEnv, ident: { name: string } | undefined): Record<string, string> =>
+  ident ? { USER: ident.name, LOGNAME: ident.name } : onlyStrings({ USER: source.USER, LOGNAME: source.LOGNAME });
+
+/** Die Umgebung eines Sandbox-Prozesses: die gewählte Grundlage dieser Maschine plus die Beiträge des Runs. */
 export const sandboxEnvironment = (
   source: NodeJS.ProcessEnv,
-  { home, ident, pathVariables, additions }: SandboxEnvironmentOptions,
+  { base = "safe", home, ident, pathVariables, additions }: SandboxEnvironmentOptions,
 ): NodeJS.ProcessEnv => ({
-  ...safeProcessEnvironment(source),
+  ...(base === "inherited" ? inheritedProcessEnvironment(source) : safeProcessEnvironment(source)),
   HOME: home.home,
   USERPROFILE: home.home,
-  USER: ident?.name ?? "root",
-  LOGNAME: ident?.name ?? "root",
+  ...accountEnvironment(source, ident),
   ...(home.nugetPackages ? { NUGET_PACKAGES: home.nugetPackages } : {}),
   ...pathVariables,
   ...additions,
@@ -86,7 +99,10 @@ export interface WorkspaceContextOptions {
   readOnlyRoots?: readonly ResolvedWorkspaceRoot[];
   additions?: Readonly<Record<string, string>>;
   runOperation?: <T>(operation: () => Promise<T>) => Promise<T>;
+  sandbox?: ProcessSandbox;
   source?: NodeJS.ProcessEnv;
+  baseEnvironment?: BaseEnvironment;
+  bash?: string;
 }
 
 const namedEntries = (
@@ -98,11 +114,20 @@ const namedEntries = (
     return name ? [[name, root.directory]] : [];
   }));
 
+/** Ein Alias nennt genau einen Ordner und liegt nicht unter einem anderen, sonst wäre offen, welche Wurzel ein Pfad meint. */
+const assertDistinctAliases = (roots: readonly ResolvedWorkspaceRoot[]): void => {
+  const aliases = roots.flatMap((root) => root.alias === undefined ? [] : [root.alias]);
+  const clash = aliases.find((alias, index) => aliases.some((other, position) =>
+    position !== index && (other === alias || other.startsWith(`${alias}/`))));
+  if (clash !== undefined) throw new Error(`Der Arbeitsverzeichnis-Alias ${clash} nennt mehr als eine Wurzel`);
+};
+
 /** Baut den Kontext eines Runs aus den Ordnern dieser Maschine; jeder Executor ruft dieselbe Funktion. */
 export const workspaceProcessContext = (options: WorkspaceContextOptions): WorkspaceProcessContext => {
   const additionalRoots = options.additionalRoots ?? [];
   const readOnlyRoots = options.readOnlyRoots ?? [];
   const all = [...additionalRoots, ...readOnlyRoots];
+  assertDistinctAliases(all);
   const pathVariables = namedEntries(all, (root) => root.environmentVariable);
   return {
     runId: options.runId,
@@ -112,6 +137,7 @@ export const workspaceProcessContext = (options: WorkspaceContextOptions): Works
     logDirectory: options.logDirectory,
     hostRoot: options.hostRoot,
     env: sandboxEnvironment(options.source ?? process.env, {
+      ...(options.baseEnvironment === undefined ? {} : { base: options.baseEnvironment }),
       home: options.home,
       ...(options.ident ? { ident: options.ident } : {}),
       pathVariables,
@@ -123,5 +149,7 @@ export const workspaceProcessContext = (options: WorkspaceContextOptions): Works
     workspaceAliases: namedEntries(all, (root) => root.alias),
     pathVariables,
     ...(options.runOperation === undefined ? {} : { runOperation: options.runOperation }),
+    ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
+    ...(options.bash === undefined ? {} : { bash: options.bash }),
   };
 };

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

@@ -0,0 +1,12 @@
+/** Ein fachlicher Fehler einer Operation mit Kennung und Status; der Aufrufer macht daraus seinen eigenen Fehlertyp. */
+export class WorkspaceOperationError extends Error {
+  readonly code: string;
+  readonly status: number;
+
+  constructor(code: string, message: string, status: number) {
+    super(message);
+    this.name = "WorkspaceOperationError";
+    this.code = code;
+    this.status = status;
+  }
+}

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

@@ -1,140 +1,98 @@
 import type { WorkspaceProcessContext } from "./context.js";
-import { LanguageServerHost, type LanguageServerAdapter, type LanguageServerHostOptions } from "./language-server/host.js";
-import { createSandboxTools, type SandboxTools, type ToolUpdate } from "./sandbox-tools.js";
+import { WorkspaceOperationError } from "./errors.js";
+import type { WorkspaceExecutorModule, WorkspaceModuleFactory, WorkspaceOperation } from "./module.js";
+import { NO_ROOTS, type OperationFootprint } from "./paths.js";
 
 /** Der Stand des Executors; Server und Arbeitsplatz müssen denselben tragen. */
-export const WORKSPACE_EXECUTOR_VERSION = "1";
-
-/** Beendet alles, was der Executor für einen Run hält; kein Werkzeug des Modells. */
-export const WORKSPACE_STOP_OPERATION = "stop";
-
-export const languageServerOpenTool = (adapterId: string): string => `${adapterId}_open`;
-
-export const languageServerDiagnosticsTool = (adapterId: string): string => `${adapterId}_diagnostics`;
-
-export const languageServerCloseTool = (adapterId: string): string => `${adapterId}_close`;
-
-export const languageServerSnapshotTool = (adapterId: string): string => `${adapterId}_snapshot`;
+export const WORKSPACE_EXECUTOR_VERSION = "5";
 
 export interface WorkspaceExecuteOptions {
   toolCallId?: string;
   signal?: AbortSignal;
-  onProgress?: (text: string) => void;
+  /** Nimmt den Fortschritt der Operation als JSON-Wert entgegen. */
+  onProgress?: (value: unknown) => void;
+  /** Wie lange die Operation selbst laufen darf; ein entfernter Executor wartet so lange zusätzlich zu seiner Sicherheitsgrenze. */
+  durationMs?: number;
+  /** Die Operation läuft bis zum Abbruch über `signal`, etwa eine Beobachtung; keine Zeitgrenze greift. */
+  untilAborted?: boolean;
+  /** Nur ausführen, wenn der Executor erreichbar ist und rechtzeitig antwortet; sonst ist das Ergebnis `null`. Für Aufräumen, das `stopRun` nachholt. */
+  whenReachable?: boolean;
 }
 
-/** Führt die Arbeitsplatz-Werkzeuge eines Runs aus; kennt weder Engine noch Run-Vertrag noch Plugins. */
+/** Führt die Operationen eines Runs auf einer Maschine aus; kennt weder Engine noch Run-Vertrag noch Plugins. */
 export interface WorkspaceExecutor {
   readonly version: string;
-  execute: (runId: string, tool: string, input: unknown, options?: WorkspaceExecuteOptions) => Promise<unknown>;
+  execute: (runId: string, operation: string, input: unknown, options?: WorkspaceExecuteOptions) => Promise<unknown>;
+  /** Gibt frei, was der Executor für den Run hält; ein entfernter Executor holt das nach, wenn er gerade nicht erreichbar ist. */
   stopRun: (runId: string) => Promise<void>;
+  /** Beendet den Executor endgültig; wer danach wieder einen braucht, baut einen neuen. */
   shutdown: () => Promise<void>;
 }
 
-export interface WorkspaceExecutorOptions {
+export interface WorkspaceOperationExecutorOptions {
   contextFor: (runId: string) => Promise<WorkspaceProcessContext>;
-  languageServers?: readonly LanguageServerAdapter[];
-  languageServerOptions?: LanguageServerHostOptions;
+  modules: readonly WorkspaceModuleFactory[];
 }
 
-const textOf = (update: ToolUpdate): string =>
-  (update.content ?? [])
-    .filter((part) => part.type === "text" && typeof part.text === "string")
-    .map((part) => part.text)
-    .join("\n");
-
 const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
 
-export class SandboxWorkspaceExecutor implements WorkspaceExecutor {
-  readonly version = WORKSPACE_EXECUTOR_VERSION;
-  readonly #options: WorkspaceExecutorOptions;
-  readonly #sandboxes = new Map<string, Promise<SandboxTools>>();
-  readonly #languageServers: readonly LanguageServerHost[];
-
-  constructor(options: WorkspaceExecutorOptions) {
-    this.#options = options;
-    this.#languageServers = (options.languageServers ?? []).map((adapter) =>
-      new LanguageServerHost(adapter, (runId) => options.contextFor(runId), options.languageServerOptions ?? {}));
-  }
+const settledAll = async (operations: readonly Promise<void>[]): Promise<void> => {
+  const results = await Promise.allSettled(operations);
+  const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+  if (failed) throw failed.reason;
+};
 
-  async execute(runId: string, tool: string, input: unknown, options: WorkspaceExecuteOptions = {}): Promise<unknown> {
-    if (tool === WORKSPACE_STOP_OPERATION) {
-      await this.stopRun(runId);
-      return null;
+/** Ein Executor aus Modulen: jede Operation gehört genau einem Modul, der Executor selbst kennt keine. */
+export class WorkspaceOperationExecutor implements WorkspaceExecutor {
+  readonly version = WORKSPACE_EXECUTOR_VERSION;
+  readonly #modules: readonly WorkspaceExecutorModule[];
+  readonly #operations: ReadonlyMap<string, WorkspaceOperation>;
+  readonly #footprints: ReadonlyMap<string, (input: unknown) => OperationFootprint>;
+
+  constructor(options: WorkspaceOperationExecutorOptions) {
+    const host = {
+      contextFor: options.contextFor,
+      annotate: (runId: string, absolutePath: string) => this.#annotate(runId, absolutePath),
+    };
+    this.#modules = options.modules.map((create) => create(host));
+    const operations = new Map<string, WorkspaceOperation>();
+    for (const module of this.#modules) {
+      for (const [name, operation] of Object.entries(module.operations)) {
+        if (operations.has(name)) throw new Error(`Die Operation ${name} ist im Executor doppelt registriert`);
+        operations.set(name, operation);
+      }
     }
-    const languageServer = this.#languageServers.find((host) =>
-      tool === languageServerOpenTool(host.adapter.id)
-      || tool === languageServerDiagnosticsTool(host.adapter.id)
-      || tool === languageServerCloseTool(host.adapter.id)
-      || tool === languageServerSnapshotTool(host.adapter.id));
-    if (languageServer) return this.#languageServerCall(languageServer, runId, tool, input);
-    return this.#toolCall(runId, tool, input, options);
+    this.#operations = operations;
+    this.#footprints = new Map(this.#modules.flatMap((module) => Object.entries(module.footprints ?? {}).map(([name, footprint]) => {
+      if (!Object.hasOwn(module.operations, name)) throw new Error(`Ein Modul erklärt einen Fußabdruck für ${name}, eine Operation, die es nicht hat`);
+      return [name, footprint] as const;
+    })));
   }
 
-  async stopRun(runId: string): Promise<void> {
-    const sandbox = this.#sandboxes.get(runId);
-    this.#sandboxes.delete(runId);
-    const results = await Promise.allSettled([
-      ...(sandbox ? [sandbox.then((tools) => tools.shutdown())] : []),
-      ...this.#languageServers.map((host) => host.stopSession(runId)),
-    ]);
-    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
-    if (failed) throw failed.reason;
+  /** Der Fußabdruck einer Eingabe nach der Erklärung des Moduls, dem die Operation gehört; so weiß ein Aufrufer, auf welche Maschine sie gehört. */
+  footprintOf(operation: string, input: unknown): OperationFootprint {
+    return this.#footprints.get(operation)?.(input) ?? { roots: NO_ROOTS };
   }
 
-  async shutdown(): Promise<void> {
-    const running = [...this.#sandboxes.keys()];
-    const results = await Promise.allSettled([
-      ...running.map((runId) => this.stopRun(runId)),
-      ...this.#languageServers.map((host) => host.shutdown()),
-    ]);
-    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
-    if (failed) throw failed.reason;
+  async execute(runId: string, operation: string, input: unknown, options: WorkspaceExecuteOptions = {}): Promise<unknown> {
+    const run = this.#operations.get(operation);
+    if (!run) throw new WorkspaceOperationError("workspace-operation-unknown", `Der Executor kennt die Operation ${operation} nicht`, 400);
+    if (options.untilAborted && !options.signal) throw new Error(`Die Operation ${operation} läuft bis zum Abbruch und braucht dafür ein Abbruchsignal`);
+    return run({ runId, input, toolCallId: options.toolCallId, signal: options.signal, progress: options.onProgress });
   }
 
-  async #toolCall(runId: string, tool: string, input: unknown, options: WorkspaceExecuteOptions): Promise<unknown> {
-    const { tools } = await this.#sandbox(runId);
-    const run = tools.get(tool);
-    if (!run) throw new Error(`Der Executor kennt das Arbeitsplatz-Werkzeug ${tool} nicht`);
-    return run(input, {
-      toolCallId: options.toolCallId ?? tool,
-      ...(options.signal ? { signal: options.signal } : {}),
-      ...(options.onProgress ? { onUpdate: (update: ToolUpdate) => options.onProgress!(textOf(update)) } : {}),
-    });
-  }
-
-  #languageServerCall(host: LanguageServerHost, runId: string, tool: string, input: unknown): Promise<unknown> {
-    if (tool === languageServerSnapshotTool(host.adapter.id)) return host.snapshot(runId);
-    if (tool === languageServerOpenTool(host.adapter.id)) {
-      const { root } = input as { root: string };
-      return host.open(runId, root);
-    }
-    if (tool === languageServerCloseTool(host.adapter.id)) {
-      const { root } = (input ?? {}) as { root?: string };
-      return host.close(runId, root);
-    }
-    const { paths, warnings, root } = input as { paths?: readonly string[]; warnings?: boolean; root?: string };
-    return host.diagnostics(runId, paths, warnings ?? false, root);
+  stopRun(runId: string): Promise<void> {
+    return settledAll(this.#modules.flatMap((module) => module.stopRun ? [module.stopRun(runId)] : []));
   }
 
-  #sandbox(runId: string): Promise<SandboxTools> {
-    const running = this.#sandboxes.get(runId);
-    if (running) return running;
-    const created = createSandboxTools(
-      runId,
-      () => this.#options.contextFor(runId),
-      (absolutePath) => this.#annotate(runId, absolutePath),
-    ).catch((error: unknown) => {
-      this.#sandboxes.delete(runId);
-      throw error;
-    });
-    this.#sandboxes.set(runId, created);
-    return created;
+  shutdown(): Promise<void> {
+    return settledAll(this.#modules.flatMap((module) => module.shutdown ? [module.shutdown()] : []));
   }
 
   async #annotate(runId: string, absolutePath: string): Promise<string | undefined> {
-    const notes = await Promise.all(this.#languageServers.map((host) =>
-      host.annotate(runId, absolutePath).catch((error: unknown) =>
-        `Diagnostik (${host.adapter.label}) fehlgeschlagen: ${messageOf(error)}`)));
+    const notes = await Promise.all(this.#modules.flatMap((module) => module.annotate
+      ? [module.annotate(runId, absolutePath).catch((error: unknown) => `Anmerkung fehlgeschlagen: ${messageOf(error)}`)]
+      : []));
     const text = notes.filter((note): note is string => Boolean(note)).join("\n");
     return text || undefined;
   }