@schlenkr/ragents 0.1.5 → 0.1.7

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;
   }

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

@@ -0,0 +1,287 @@
+import { watch } from "node:fs";
+import { lstat, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { WorkspaceOperationError } from "./errors.js";
+import type { WorkspaceModuleFactory, WorkspaceOperation } from "./module.js";
+import { aliasOf, aliasedRoot, containsWorkspacePath, unknownAliasError, type OperationFootprint } from "./paths.js";
+
+export const FILE_LIST_LIMIT = 500;
+
+export const FILE_READ_LIMIT = 256 * 1024;
+
+const WATCH_DEBOUNCE_MS = 150;
+
+export const FILE_OPERATIONS = {
+  list: "files.list",
+  read: "files.read",
+  watch: "files.watch",
+  attach: "files.attach",
+} as const;
+
+/** Der Unterordner der Wurzel, in dem angehängte Dateien eines Runs liegen. */
+export const ATTACHMENT_DIRECTORY = "attachments";
+
+export interface FileEntry {
+  name: string;
+  kind: "directory" | "file";
+  size: number;
+  modifiedAt: string;
+}
+
+export interface FileListing {
+  /** Der echte Pfad der Wurzel auf dieser Maschine. */
+  location: string;
+  path: string;
+  entries: FileEntry[];
+  truncated: boolean;
+}
+
+export type FileText =
+  | { path: string; size: number; previewable: true; content: string }
+  | { path: string; size: number; previewable: false; reason: string };
+
+/** Erst `ready`, sobald die Beobachtung steht, danach je entprellter Änderung `changed`. */
+export type FileWatchProgress = { kind: "ready" } | { kind: "changed" };
+
+export interface FileWatchListener {
+  onChange: () => void;
+  onError: (error: Error) => void;
+}
+
+const invalid = (message: string): WorkspaceOperationError => new WorkspaceOperationError("workspace-path-invalid", message, 400);
+
+const notFound = (message: string): WorkspaceOperationError => new WorkspaceOperationError("workspace-path-not-found", message, 404);
+
+const missing = (error: unknown): boolean => {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "ENOENT" || code === "ENOTDIR";
+};
+
+/** Ein Pfad unterhalb einer Wurzel: relativ, mit `/` getrennt und ohne `..`; `.` und leere Abschnitte fallen weg. */
+export const relativeWorkspacePath = (value: string): string => {
+  const segments = value.split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (value.includes("\0") || value.includes("\\") || path.isAbsolute(value) || segments.includes("..")) {
+    throw invalid(`Ungültiger Pfad: ${value}`);
+  }
+  return segments.join("/");
+};
+
+const realRoot = async (root: string): Promise<string> => {
+  try {
+    return await realpath(root);
+  } catch (error) {
+    if (missing(error)) throw notFound(`Den Ordner ${root} gibt es nicht`);
+    throw error;
+  }
+};
+
+/** Löst einen geprüften relativen Pfad auf; ein Symlink darf nicht aus der Wurzel führen. */
+const inside = async (base: string, relative: string): Promise<string> => {
+  let real: string;
+  try {
+    real = await realpath(relative ? path.join(base, ...relative.split("/")) : base);
+  } catch (error) {
+    if (missing(error)) throw notFound(`Nicht gefunden: ${relative || "."}`);
+    throw error;
+  }
+  if (!containsWorkspacePath(base, real)) throw invalid(`Pfad außerhalb des Arbeitsverzeichnisses: ${relative}`);
+  return real;
+};
+
+/** Ein Eintrag, der zwischen Auflisten und Abfragen verschwindet, gehört nicht mehr zum Ordner. */
+const entryOf = async (directory: string, name: string, isDirectory: boolean): Promise<FileEntry | undefined> => {
+  try {
+    const info = await lstat(path.join(directory, name));
+    return { name, kind: isDirectory ? "directory" : "file", size: info.size, modifiedAt: info.mtime.toISOString() };
+  } catch (error) {
+    if (missing(error)) return undefined;
+    throw error;
+  }
+};
+
+const byKindThenName = (left: FileEntry, right: FileEntry): number =>
+  (left.kind === right.kind ? 0 : left.kind === "directory" ? -1 : 1)
+  || left.name.localeCompare(right.name, "de");
+
+const directoryIn = async (base: string, checked: string): Promise<string> => {
+  const directory = await inside(base, checked);
+  if (!(await lstat(directory)).isDirectory()) throw invalid(`Kein Verzeichnis: ${checked || "."}`);
+  return directory;
+};
+
+/** Der echte Pfad eines Ordners unterhalb der Wurzel, geprüft wie jeder Pfad dieses Moduls. */
+export const workspaceDirectory = async (root: string, relative: string): Promise<string> =>
+  directoryIn(await realRoot(root), relativeWorkspacePath(relative));
+
+/** Listet einen Ordner unterhalb der Wurzel: Ordner zuerst, dann alphabetisch, höchstens `FILE_LIST_LIMIT` Einträge. */
+export const listDirectory = async (root: string, relative: string): Promise<FileListing> => {
+  const checked = relativeWorkspacePath(relative);
+  const base = await realRoot(root);
+  const directory = await directoryIn(base, checked);
+  const found = await readdir(directory, { withFileTypes: true });
+  const entries = (await Promise.all(found.map((entry) => entryOf(directory, entry.name, entry.isDirectory()))))
+    .filter((entry): entry is FileEntry => entry !== undefined)
+    .sort(byKindThenName);
+  return {
+    location: base,
+    path: checked,
+    entries: entries.slice(0, FILE_LIST_LIMIT),
+    truncated: entries.length > FILE_LIST_LIMIT,
+  };
+};
+
+/** Liest eine Textdatei unterhalb der Wurzel; eine zu große oder binäre Datei nennt statt des Inhalts den Grund. */
+export const readTextFile = async (root: string, relative: string): Promise<FileText> => {
+  const checked = relativeWorkspacePath(relative);
+  const file = await inside(await realRoot(root), checked);
+  const info = await lstat(file);
+  if (!info.isFile()) throw invalid(`Keine Datei: ${checked || "."}`);
+  const described = { path: checked, size: info.size };
+  if (info.size > FILE_READ_LIMIT) {
+    return { ...described, previewable: false, reason: `Die Datei ist größer als ${FILE_READ_LIMIT / 1024} KB und wird nicht gelesen` };
+  }
+  const content = await readFile(file);
+  if (content.includes(0)) return { ...described, previewable: false, reason: "Die Datei ist binär" };
+  return { ...described, previewable: true, content: content.toString("utf8") };
+};
+
+/** Legt eine angehängte Datei unter einem freien Namen in `attachments` unterhalb der Wurzel ab, nie über eine vorhandene. */
+export const storeAttachment = async (root: string, original: string, content: Uint8Array): Promise<string> => {
+  const directory = path.join(await realRoot(root), ATTACHMENT_DIRECTORY);
+  await mkdir(directory, { recursive: true, mode: 0o755 });
+  if (!(await lstat(directory)).isDirectory()) throw invalid("Das Anhangsverzeichnis ist kein normales Verzeichnis.");
+  const name = path.basename(original).replace(/[^a-zA-Z0-9._-]/g, "_") || "attachment";
+  for (let index = 1; index <= 10000; index += 1) {
+    const candidate = index === 1 ? name : `${index}-${name}`;
+    try {
+      await writeFile(path.join(directory, candidate), content, { mode: 0o644, flag: "wx" });
+      return candidate;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+  throw invalid("Im Anhangsverzeichnis sind zu viele gleichnamige Dateien.");
+};
+
+/** Beobachtet einen Ordner rekursiv und meldet Änderungen entprellt; der Rückgabewert beendet die Beobachtung. */
+export const watchDirectory = async (root: string, listener: FileWatchListener): Promise<() => void> => {
+  const directory = await realRoot(root);
+  let debounce: NodeJS.Timeout | undefined;
+  const watcher = watch(directory, { recursive: true }, () => {
+    if (debounce) return;
+    debounce = setTimeout(() => {
+      debounce = undefined;
+      listener.onChange();
+    }, WATCH_DEBOUNCE_MS);
+  });
+  watcher.on("error", listener.onError);
+  return () => {
+    if (debounce) clearTimeout(debounce);
+    watcher.close();
+  };
+};
+
+const pathOf = (input: unknown): string => {
+  const value = (input as { path?: unknown } | null)?.path;
+  if (typeof value !== "string") throw invalid("Die Eingabe braucht einen Pfad als Text");
+  return value;
+};
+
+/** Mit Alias spricht die Eingabe dessen Wurzel an, sonst die des Runs. */
+const aliasFootprint = (input: unknown): OperationFootprint => {
+  const alias = (input as { alias?: unknown } | null)?.alias;
+  return { roots: typeof alias === "string" ? { aliases: [aliasOf(alias) ?? alias], runRoot: false } : { aliases: [], runRoot: true } };
+};
+
+/** Beobachtet bis zum Abbruch; eine gescheiterte Beobachtung beendet die Operation mit ihrer Ursache. */
+const watchUntilAborted = (root: string, signal: AbortSignal, progress: (value: FileWatchProgress) => void): Promise<null> =>
+  new Promise((resolve, reject) => {
+    let close: (() => void) | undefined;
+    let finished = false;
+    const finish = (error?: Error): void => {
+      if (finished) return;
+      finished = true;
+      signal.removeEventListener("abort", aborted);
+      close?.();
+      if (error) reject(error);
+      else resolve(null);
+    };
+    const aborted = (): void => finish();
+    signal.addEventListener("abort", aborted, { once: true });
+    watchDirectory(root, { onChange: () => progress({ kind: "changed" }), onError: finish }).then((stop) => {
+      if (finished || signal.aborted) {
+        stop();
+        finish();
+        return;
+      }
+      close = stop;
+      progress({ kind: "ready" });
+    }, finish);
+  });
+
+/** Dateien des Runs auf dieser Maschine: auflisten, Text lesen, beobachten und Anhänge ablegen, relativ zur Wurzel des Runs oder eines Alias. */
+export const fileModule: WorkspaceModuleFactory = (host) => {
+  /** Die offenen Beobachtungen je Run; Stopp und Shutdown beenden sie, auch wenn ihr Aufrufer nie abbricht. */
+  const watches = new Map<string, Set<AbortController>>();
+  let closed = false;
+  const endWatches = (runId: string): void => {
+    for (const controller of watches.get(runId) ?? []) controller.abort();
+    watches.delete(runId);
+  };
+  /** Alias und Pfad bilden zusammen einen Ort; unter einem gemeinsamen Alias wie `@skills` nennt der Pfad zuerst den Ordner der Wurzel. */
+  const locate = async (runId: string, input: unknown): Promise<{ root: string; path: string }> => {
+    const context = await host.contextFor(runId);
+    const alias = (input as { alias?: unknown } | null)?.alias;
+    const requested = pathOf(input);
+    if (alias === undefined) return { root: context.root, path: requested };
+    const aliases = context.workspaceAliases ?? {};
+    const location = requested === "" ? String(alias) : `${String(alias)}/${requested}`;
+    const found = typeof alias === "string" ? aliasedRoot(location, aliases) : undefined;
+    if (!found) throw unknownAliasError(location, aliases);
+    return { root: found.directory, path: found.rest };
+  };
+  const list: WorkspaceOperation = async ({ runId, input }) => {
+    const { root, path: requested } = await locate(runId, input);
+    return listDirectory(root, requested);
+  };
+  const attach: WorkspaceOperation = async ({ runId, input }) => {
+    const { name, content } = (input ?? {}) as { name?: unknown; content?: unknown };
+    if (typeof name !== "string" || typeof content !== "string") throw invalid("Ein Anhang braucht name und content (Base64) als Text");
+    return { name: await storeAttachment((await host.contextFor(runId)).root, name, Buffer.from(content, "base64")) };
+  };
+  const read: WorkspaceOperation = async ({ runId, input }) => {
+    const { root, path: requested } = await locate(runId, input);
+    return readTextFile(root, requested);
+  };
+  const watchFiles: WorkspaceOperation = async ({ runId, signal, progress }) => {
+    if (!signal || !progress) throw new Error(`${FILE_OPERATIONS.watch} läuft bis zum Abbruch und braucht Abbruchsignal und Fortschritt`);
+    if (closed) throw new Error("Das Dateimodul ist beendet und beobachtet nichts mehr");
+    const own = new AbortController();
+    const running = watches.get(runId) ?? new Set<AbortController>();
+    watches.set(runId, running.add(own));
+    try {
+      const root = (await host.contextFor(runId)).root;
+      return await watchUntilAborted(root, AbortSignal.any([signal, own.signal]), progress);
+    } finally {
+      running.delete(own);
+      if (running.size === 0 && watches.get(runId) === running) watches.delete(runId);
+    }
+  };
+  return {
+    operations: {
+      [FILE_OPERATIONS.list]: list,
+      [FILE_OPERATIONS.read]: read,
+      [FILE_OPERATIONS.watch]: watchFiles,
+      [FILE_OPERATIONS.attach]: attach,
+    },
+    footprints: {
+      [FILE_OPERATIONS.list]: aliasFootprint,
+      [FILE_OPERATIONS.read]: aliasFootprint,
+    },
+    stopRun: async (runId) => endWatches(runId),
+    shutdown: async () => {
+      closed = true;
+      for (const runId of [...watches.keys()]) endWatches(runId);
+    },
+  };
+};