@schlenkr/ragents 0.1.10 → 0.1.12

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

@@ -10,22 +10,22 @@ 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. */
+/** The largest output per stream that a call returns; whatever goes beyond it is discarded and the truncation is reported. */
 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. */
+  /** A name from the PATH of the executor or the path of a program; it runs without a shell. */
   program: string;
   args?: readonly string[];
-  /** Der Arbeitsordner relativ zur Wurzel des Runs; ohne Angabe die Wurzel selbst. */
+  /** The working folder relative to the root of the run; without a value the root itself. */
   cwd?: string;
   timeoutMs: number;
-  /** Höchstens so viele Bytes je Datenstrom; ohne Angabe `COMMAND_OUTPUT_LIMIT`. */
+  /** At most this many bytes per stream; without a value `COMMAND_OUTPUT_LIMIT`. */
   maxOutputBytes?: number;
 }
 
 export interface CommandResult {
-  /** `null`, wenn der Prozess durch ein Signal endete. */
+  /** `null` if the process ended through a signal. */
   exitCode: number | null;
   stdout: string;
   stderr: string;
@@ -53,20 +53,20 @@ const textWithoutNul = (value: unknown): value is string => typeof value === "st
 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 (!textWithoutNul(program) || program === "") throw invalid("The command needs a program as text");
+  if (platform === "win32" && /\.(cmd|bat)$/i.test(program)) throw invalid(`${program} needs a shell on Windows; a command runs without one`);
+  if (!Array.isArray(args) || !args.every(textWithoutNul)) throw invalid("The arguments must be texts without null characters");
+  if (typeof cwd !== "string") throw invalid("The working folder must be a text");
   if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
-    throw invalid("Die Zeitgrenze muss eine positive ganze Zahl in Millisekunden sein");
+    throw invalid("The timeout must be a positive integer in milliseconds");
   }
   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`);
+    throw invalid(`The output limit is between 0 and ${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. */
+/** Collects a stream up to the limit; the rest is discarded, the process keeps running. */
 const boundedOutput = (limit: number) => {
   const chunks: Buffer[] = [];
   let size = 0;
@@ -86,8 +86,8 @@ const boundedOutput = (limit: number) => {
 
 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);
+  if (code === "ENOENT") return new WorkspaceOperationError("command-unavailable", `The program ${program} does not exist on this machine`, 409);
+  if (code === "EACCES") return new WorkspaceOperationError("command-unavailable", `The program ${program} is not executable on this machine`, 409);
   return undefined;
 };
 
@@ -113,7 +113,7 @@ const runCommand = async (context: WorkspaceProcessContext, command: CheckedComm
     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);
+    throw new WorkspaceOperationError("command-timeout", `${command.program} exceeded the timeout of ${command.timeoutMs} ms`, 504);
   }
   return {
     exitCode: result.code,
@@ -124,17 +124,17 @@ const runCommand = async (context: WorkspaceProcessContext, command: CheckedComm
   };
 };
 
-/** 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. */
+/** A command runs in the root of the run, an alias does not apply there; its timeout extends how long a remote executor may wait for it. */
 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. */
+/** Commands in the workspace of the run: a program with arguments, without a shell, in a folder under the root, with the environment of this executor. */
 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"));
+    for (const command of commands) command.controller.abort(new Error("The command was ended with its run"));
     await Promise.allSettled(commands.map((command) => command.finished));
   };
   const run: WorkspaceOperation = async ({ runId, input, signal }) => {

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

@@ -5,15 +5,15 @@ import { inheritedProcessEnvironment, safeProcessEnvironment } from "./safe-envi
 import type { SessionIdent } from "./session-ident.js";
 import type { ResolvedWorkspaceRoot } from "./paths.js";
 
-/** Was ein Executor über einen Run weiß: seine Ordner, seine Umgebung und seine Kennung. */
+/** What an executor knows about a run: its folders, its environment and its id. */
 export interface WorkspaceProcessContext {
   runId: string;
   cwd: string;
   root: string;
   home: string;
-  /** Wohin ein Sprachserver Protokolle und Zwischenstände legen darf; nie das Home eines Entwicklers. */
+  /** Where a language server may put logs and intermediate state; never the home of a developer. */
   logDirectory: string;
-  /** Die Wurzel des Hosts auf dieser Maschine, aus der ein Adapter seinen Sprachserver auflöst; ohne Host bleibt sie offen. */
+  /** The root of the host on this machine from which an adapter resolves its language server; without a host it stays open. */
   hostRoot: string | undefined;
   env: NodeJS.ProcessEnv;
   uid?: number;
@@ -23,11 +23,11 @@ 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. */
+  /** The process sandbox of this run; if it is missing, processes start without one. */
   sandbox?: ProcessSandbox;
-  /** Die Bash, mit der das Werkzeug bash startet; unter Windows Pflicht, sonst gilt ohne Angabe die des Systems. */
+  /** The bash the bash tool starts with; required on Windows, otherwise the system's one applies without a value. */
   bash?: string;
-  /** Das rg, dessen Ordner das Werkzeug bash vorn im PATH hat; ohne Angabe gilt eines im PATH, falls es eines gibt. */
+  /** The rg whose folder the bash tool has at the front of PATH; without a value one in PATH applies, if there is one. */
   rg?: string;
 }
 
@@ -36,11 +36,11 @@ 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). */
+/** What the environment of a process is built from: "safe" takes only the safe selection (server), "inherited" everything except editor variables and bash startup files (own machine). */
 export type BaseEnvironment = "safe" | "inherited";
 
 export interface SandboxEnvironmentOptions {
-  /** Ohne Angabe "safe": wer nichts wählt, gibt nur die sichere Auswahl weiter. */
+  /** Defaults to "safe": whoever chooses nothing passes on only the safe selection. */
   base?: BaseEnvironment;
   home: SandboxHomeEnvironment;
   ident?: { name: string };
@@ -48,7 +48,7 @@ export interface SandboxEnvironmentOptions {
   additions?: Readonly<Record<string, string>>;
 }
 
-/** Die Git-Regeln, die in jeder Sandbox gelten, gleich auf welchem Rechner sie läuft. */
+/** The Git rules that apply in every sandbox, no matter which machine it runs on. */
 export const SANDBOX_GIT_CONFIG: GitConfigPairs = [
   ["branch.autoSetupMerge", "false"],
   ["core.hooksPath", "/dev/null"],
@@ -58,7 +58,7 @@ export const SANDBOX_GIT_CONFIG: GitConfigPairs = [
 const onlyStrings = (env: NodeJS.ProcessEnv): Record<string, string> =>
   Object.fromEntries(Object.entries(env).filter((entry): entry is [string, string] => typeof entry[1] === "string"));
 
-/** Was der Server je Run zur Umgebung beiträgt: Run-Marker, Git-Regeln und die Zusätze seines Arbeitsbereichs. */
+/** What the server contributes to the environment per run: run marker, Git rules and the additions of its workspace. */
 export const sandboxRunEnvironment = (runId: string, workspace: {
   gitConfig?: GitConfigPairs;
   extraEnv?: NodeJS.ProcessEnv;
@@ -71,11 +71,11 @@ export const sandboxRunEnvironment = (runId: string, workspace: {
   ...workspace.gitEnv,
 });
 
-/** Ohne eigenes Konto läuft der Prozess unter dem Benutzer dieser Maschine und trägt dessen Namen. */
+/** Without its own account the process runs as the user of this machine and carries that user's name. */
 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. */
+/** The environment of a sandbox process: the chosen base of this machine plus the contributions of the run. */
 export const sandboxEnvironment = (
   source: NodeJS.ProcessEnv,
   { base = "safe", home, ident, pathVariables, additions }: SandboxEnvironmentOptions,
@@ -117,15 +117,15 @@ 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. */
+/** An alias names exactly one folder and does not lie under another, otherwise it would be open which root a path means. */
 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`);
+  if (clash !== undefined) throw new Error(`The working directory alias ${clash} names more than one root`);
 };
 
-/** Baut den Kontext eines Runs aus den Ordnern dieser Maschine; jeder Executor ruft dieselbe Funktion. */
+/** Builds the context of a run from the folders of this machine; every executor calls the same function. */
 export const workspaceProcessContext = (options: WorkspaceContextOptions): WorkspaceProcessContext => {
   const additionalRoots = options.additionalRoots ?? [];
   const readOnlyRoots = options.readOnlyRoots ?? [];

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

@@ -11,48 +11,48 @@ import type { WorkspaceModuleFactory } from "./module.js";
 import { RUN_MARKER_ENV } from "./run-marker.js";
 import { safeProcessEnvironment } from "./safe-environment.js";
 
-/** Wo ein Bundle seinen Beitrag zum Executor trägt: eine in sich geschlossene Datei, die jeder Node-Prozess ohne Host-Auflösung lädt. */
+/** Where a bundle carries its contribution to the executor: a self-contained file that every Node process loads without host resolution. */
 export const EXECUTOR_CONTRIBUTION_FILE = "executor/index.mjs";
 
-/** Was der Executor einer Maschine einem Beitrag über sie sagt; ein Beitrag importiert vom Host nur Typen, alles andere kommt hierüber. */
+/** What the executor of a machine tells a contribution about it; a contribution imports only types from the host, everything else comes through here. */
 export interface WorkspaceExecutorMachine {
-  /** Der Werkzeugordner des Plugins auf dieser Maschine, wohin seine Provisionierung lädt. */
+  /** The tools folder of the plugin on this machine, where its provisioning downloads to. */
   readonly toolsDirectory: string;
-  /** Eine Datei aus einem Paket in den node_modules des Hosts dieser Maschine; ohne Host oder Paket scheitert der Aufruf mit Ursache. */
+  /** A file from a package in the node_modules of the host of this machine; without a host or package the call fails with a cause. */
   readonly hostPackageFile: (hostRoot: string | undefined, specifier: string) => string;
-  /** Eine Datei mit einer der Endungen im Arbeitsbereich, aufgelöst und geprüft. */
+  /** A file with one of the extensions in the workspace, resolved and checked. */
   readonly resolveRootFile: (workspaceRoot: string, requested: string, extensions: readonly string[]) => Promise<string>;
-  /** Ein Ordner im Arbeitsbereich, aufgelöst und geprüft. */
+  /** A folder in the workspace, resolved and checked. */
   readonly resolveRootDirectory: (workspaceRoot: string, requested: string) => Promise<string>;
-  /** Ein fachlicher Fehler einer Operation mit Kennung und Status; beim Aufrufer kommt er als derselbe Fehler an wie einer des Executors. */
+  /** A domain error of an operation with code and status; it reaches the caller as the same error as one of the executor. */
   readonly operationError: (code: string, message: string, status: number) => Error;
-  /** Die Umgebung eines Prozesses, den ein Beitrag selbst startet: die sichere Auswahl dieser Maschine, ihr HOME und der Marker des Runs für die Prozessanzeige. */
+  /** The environment of a process that a contribution starts itself: the safe selection of this machine, its HOME and the marker of the run for the process view. */
   readonly processEnvironment: (runId: string) => NodeJS.ProcessEnv;
 }
 
-/** Was ein Beitrag dem Executor einer Maschine hinzufügt. */
+/** What a contribution adds to the executor of a machine. */
 export interface WorkspaceExecutorParts {
   readonly languageServers?: readonly LanguageServerAdapter[];
-  /** Module mit eigenen Operationen; jede Operation gehört genau einem Modul. */
+  /** Modules with their own operations; every operation belongs to exactly one module. */
   readonly modules?: readonly WorkspaceModuleFactory[];
 }
 
-/** Was ein Plugin-Bundle als `executor` exportiert; es läuft in jedem Executor, im Server wie auf jedem Arbeitsplatz, und berührt beim Bauen weder Platte noch Netz. */
+/** What a plugin bundle exports as `executor`; it runs in every executor, in the server as on every workspace, and touches neither disk nor network while building. */
 export type WorkspaceExecutorContribution = (machine: WorkspaceExecutorMachine) => WorkspaceExecutorParts;
 
-/** Wessen Beitrag in welchem Stand; Server und Arbeitsplatz verlangen dieselben. */
-export interface ExecutorContributionStand {
+/** Whose contribution in which version; server and workspace require the same ones. */
+export interface ExecutorContributionRevision {
   readonly plugin: string;
-  /** SHA-256 der Datei des Beitrags. */
-  readonly stand: string;
+  /** SHA-256 of the file of the contribution. */
+  readonly revision: string;
 }
 
-export interface LoadedExecutorContribution extends ExecutorContributionStand {
+export interface LoadedExecutorContribution extends ExecutorContributionRevision {
   readonly contribution: WorkspaceExecutorContribution;
 }
 
-/** Ein Beitrag, gebaut für diese Maschine. */
-export interface PreparedExecutorContribution extends ExecutorContributionStand {
+/** A contribution built for this machine. */
+export interface PreparedExecutorContribution extends ExecutorContributionRevision {
   readonly parts: WorkspaceExecutorParts;
 }
 
@@ -61,19 +61,19 @@ const PART_KEYS = new Set(["languageServers", "modules"]);
 
 const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
 
-/** Der Paketname eines Bezeichners wie acme-server/lib/cli.mjs oder @scope/name/datei. */
+/** The package name of a specifier like acme-server/lib/cli.mjs or @scope/name/file. */
 const packageOf = (specifier: string): string =>
   specifier.split("/").slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
 
 const hostPackageFile = (hostRoot: string | undefined, specifier: string): string => {
   if (!hostRoot) {
-    throw new Error(`Auf diesem Rechner ist kein Host bekannt, aus dem sich ${packageOf(specifier)} auflösen ließe. Ein Arbeitsplatz `
-      + "bekommt ihn mit der ersten Verbindung zu einem verteilenden Server oder über die Einstellung ragents.hostPath");
+    throw new Error(`No host is known on this machine from which ${packageOf(specifier)} could be resolved. A workspace `
+      + "gets it with the first connection to a distributing server or through the setting ragents.hostPath");
   }
   try {
     return createRequire(path.join(hostRoot, "package.json")).resolve(specifier);
   } catch (cause) {
-    throw new Error(`${packageOf(specifier)} liegt nicht im Host ${hostRoot}: ${messageOf(cause)}`);
+    throw new Error(`${packageOf(specifier)} is not in the host ${hostRoot}: ${messageOf(cause)}`);
   }
 };
 
@@ -86,24 +86,24 @@ export const executorMachine = (toolsDirectory: string): WorkspaceExecutorMachin
   processEnvironment: (runId) => ({ ...safeProcessEnvironment(process.env), HOME: homedir(), [RUN_MARKER_ENV]: runId }),
 });
 
-/** Lädt die Datei eines Beitrags, mit `expected` nur in diesem Stand; der Stand steht in ihrer Adresse, damit ein neu gebauter Beitrag nie aus dem Modulcache kommt. */
+/** Loads the file of a contribution, with `expected` only in that version; the version is part of its address so that a newly built contribution never comes from the module cache. */
 export const loadExecutorContribution = async (plugin: string, file: string, expected?: string): Promise<LoadedExecutorContribution> => {
   const content = await readFile(file).catch((cause: unknown) => {
-    throw new Error(`Der Executor-Beitrag von ${plugin} fehlt unter ${file}: ${messageOf(cause)}`);
+    throw new Error(`The executor contribution of ${plugin} is missing at ${file}: ${messageOf(cause)}`);
   });
-  const stand = createHash("sha256").update(content).digest("hex");
-  if (expected !== undefined && stand !== expected) {
-    throw new Error(`Der Executor-Beitrag von ${plugin} unter ${file} hat den Stand ${stand.slice(0, 12)}, verlangt ist ${expected.slice(0, 12)}`);
+  const revision = createHash("sha256").update(content).digest("hex");
+  if (expected !== undefined && revision !== expected) {
+    throw new Error(`The executor contribution of ${plugin} at ${file} has the version ${revision.slice(0, 12)}, required is ${expected.slice(0, 12)}`);
   }
-  const exported = await import(`${pathToFileURL(file).href}?stand=${stand}`).catch((cause: unknown) => {
-    throw new Error(`Der Executor-Beitrag von ${plugin} (${file}) lädt nicht: ${messageOf(cause)}`, { cause });
+  const exported = await import(`${pathToFileURL(file).href}?revision=${revision}`).catch((cause: unknown) => {
+    throw new Error(`The executor contribution of ${plugin} (${file}) does not load: ${messageOf(cause)}`, { cause });
   }) as Readonly<Record<string, unknown>>;
   const contribution = exported.executor;
   if (typeof contribution !== "function") {
-    throw new Error(`Das Bundle ${plugin} exportiert in ${file} keinen gültigen Executor-Beitrag; erwartet wird `
-      + "\"export const executor: WorkspaceExecutorContribution\" als Funktion der Maschine");
+    throw new Error(`The bundle ${plugin} exports no valid executor contribution in ${file}; expected is `
+      + "\"export const executor: WorkspaceExecutorContribution\" as a function of the machine");
   }
-  return { plugin, stand, contribution: contribution as WorkspaceExecutorContribution };
+  return { plugin, revision, contribution: contribution as WorkspaceExecutorContribution };
 };
 
 const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
@@ -112,9 +112,9 @@ const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
 const isStringList = (value: unknown): value is readonly string[] =>
   Array.isArray(value) && value.every((entry) => typeof entry === "string");
 
-/** Was an einem Sprachserver fehlt oder die falsche Form hat; leer, wenn er taugt. */
+/** What is missing from a language server or has the wrong shape; empty if it is usable. */
 const adapterProblems = (value: Readonly<Record<string, unknown>>): readonly string[] => [
-  ...typeof value.id === "string" && LANGUAGE_SERVER_ID.test(value.id) ? [] : ["id aus Kleinbuchstaben und Ziffern"],
+  ...typeof value.id === "string" && LANGUAGE_SERVER_ID.test(value.id) ? [] : ["id of lowercase letters and digits"],
   ...typeof value.label === "string" ? [] : ["label"],
   ...isRecord(value.languages) && Object.values(value.languages).every((entry) => typeof entry === "string") ? [] : ["languages"],
   ...typeof value.rootDescription === "string" ? [] : ["rootDescription"],
@@ -122,29 +122,29 @@ const adapterProblems = (value: Readonly<Record<string, unknown>>): readonly str
   ...(["resolveRoot", "rootDirectory", "launch", "open"] as const).filter((name) => typeof value[name] !== "function"),
 ];
 
-/** Baut einen geladenen Beitrag für diese Maschine und prüft, was er liefert; eine falsche Form ist ein Fehler mit Ursache. */
+/** Builds a loaded contribution for this machine and checks what it returns; a wrong shape is an error with a cause. */
 export const prepareExecutorContribution = (loaded: LoadedExecutorContribution, toolsDirectory: string): PreparedExecutorContribution => {
-  const invalid = (detail: string): Error => new Error(`Der Executor-Beitrag von ${loaded.plugin} ist ungültig: ${detail}`);
+  const invalid = (detail: string): Error => new Error(`The executor contribution of ${loaded.plugin} is invalid: ${detail}`);
   const parts = ((): unknown => {
     try {
       return loaded.contribution(executorMachine(toolsDirectory));
     } catch (cause) {
-      throw invalid(`die Funktion wirft: ${messageOf(cause)}`);
+      throw invalid(`the function throws: ${messageOf(cause)}`);
     }
   })();
-  if (!isRecord(parts)) throw invalid("die Funktion liefert kein Objekt");
+  if (!isRecord(parts)) throw invalid("the function returns no object");
   const unknown = Object.keys(parts).filter((key) => !PART_KEYS.has(key));
-  if (unknown.length > 0) throw invalid(`unbekannte Teile ${unknown.join(", ")}; erlaubt sind ${[...PART_KEYS].join(", ")}`);
+  if (unknown.length > 0) throw invalid(`unknown parts ${unknown.join(", ")}; allowed are ${[...PART_KEYS].join(", ")}`);
   const modules = parts.modules;
   if (modules !== undefined && (!Array.isArray(modules) || !modules.every((module) => typeof module === "function"))) {
-    throw invalid("modules ist keine Liste von Modulfabriken");
+    throw invalid("modules is not a list of module factories");
   }
   const servers = parts.languageServers;
-  if (servers !== undefined && !Array.isArray(servers)) throw invalid("languageServers ist keine Liste");
+  if (servers !== undefined && !Array.isArray(servers)) throw invalid("languageServers is not a list");
   for (const [index, server] of (servers ?? []).entries()) {
-    if (!isRecord(server)) throw invalid(`der Sprachserver ${index + 1} ist kein Objekt`);
+    if (!isRecord(server)) throw invalid(`the language server ${index + 1} is not an object`);
     const problems = adapterProblems(server);
-    if (problems.length > 0) throw invalid(`der Sprachserver ${index + 1} braucht ${problems.join(", ")}`);
+    if (problems.length > 0) throw invalid(`the language server ${index + 1} needs ${problems.join(", ")}`);
   }
-  return { plugin: loaded.plugin, stand: loaded.stand, parts: parts as WorkspaceExecutorParts };
+  return { plugin: loaded.plugin, revision: loaded.revision, parts: parts as WorkspaceExecutorParts };
 };

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

@@ -1,4 +1,4 @@
-/** Ein fachlicher Fehler einer Operation mit Kennung und Status; der Aufrufer macht daraus seinen eigenen Fehlertyp. */
+/** A domain error of an operation with code and status; the caller turns it into its own error type. */
 export class WorkspaceOperationError extends Error {
   readonly code: string;
   readonly status: number;

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

@@ -3,29 +3,29 @@ 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 = "7";
+/** The version of the executor; server and workspace must carry the same one. */
+export const WORKSPACE_EXECUTOR_VERSION = "8";
 
 export interface WorkspaceExecuteOptions {
   toolCallId?: string;
   signal?: AbortSignal;
-  /** Nimmt den Fortschritt der Operation als JSON-Wert entgegen. */
+  /** Receives the progress of the operation as a JSON value. */
   onProgress?: (value: unknown) => void;
-  /** Wie lange die Operation selbst laufen darf; ein entfernter Executor wartet so lange zusätzlich zu seiner Sicherheitsgrenze. */
+  /** How long the operation itself may run; a remote executor waits this long in addition to its safety margin. */
   durationMs?: number;
-  /** Die Operation läuft bis zum Abbruch über `signal`, etwa eine Beobachtung; keine Zeitgrenze greift. */
+  /** The operation runs until it is aborted through `signal`, such as a watch; no timeout applies. */
   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. */
+  /** Execute only if the executor is reachable and answers in time; otherwise the result is `null`. For cleanup that `stopRun` catches up on. */
   whenReachable?: boolean;
 }
 
-/** Führt die Operationen eines Runs auf einer Maschine aus; kennt weder Engine noch Run-Vertrag noch Plugins. */
+/** Executes the operations of a run on a machine; knows neither engine nor run contract nor plugins. */
 export interface WorkspaceExecutor {
   readonly version: string;
   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. */
+  /** Releases what the executor holds for the run; a remote executor catches up on this if it is currently unreachable. */
   stopRun: (runId: string) => Promise<void>;
-  /** Beendet den Executor endgültig; wer danach wieder einen braucht, baut einen neuen. */
+  /** Ends the executor for good; whoever needs one again afterwards builds a new one. */
   shutdown: () => Promise<void>;
 }
 
@@ -42,7 +42,7 @@ const settledAll = async (operations: readonly Promise<void>[]): Promise<void> =
   if (failed) throw failed.reason;
 };
 
-/** Ein Executor aus Modulen: jede Operation gehört genau einem Modul, der Executor selbst kennt keine. */
+/** An executor made of modules: every operation belongs to exactly one module, the executor itself knows none. */
 export class WorkspaceOperationExecutor implements WorkspaceExecutor {
   readonly version = WORKSPACE_EXECUTOR_VERSION;
   readonly #modules: readonly WorkspaceExecutorModule[];
@@ -58,26 +58,26 @@ export class WorkspaceOperationExecutor implements WorkspaceExecutor {
     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`);
+        if (operations.has(name)) throw new Error(`The operation ${name} is registered twice in the executor`);
         operations.set(name, operation);
       }
     }
     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`);
+      if (!Object.hasOwn(module.operations, name)) throw new Error(`A module declares a footprint for ${name}, an operation it does not have`);
       return [name, footprint] as const;
     })));
   }
 
-  /** 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. */
+  /** The footprint of an input according to the declaration of the module the operation belongs to; this tells a caller which machine it belongs on. */
   footprintOf(operation: string, input: unknown): OperationFootprint {
     return this.#footprints.get(operation)?.(input) ?? { roots: NO_ROOTS };
   }
 
   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`);
+    if (!run) throw new WorkspaceOperationError("workspace-operation-unknown", `The executor does not know the operation ${operation}`, 400);
+    if (options.untilAborted && !options.signal) throw new Error(`The operation ${operation} runs until it is aborted and needs an abort signal for that`);
     return run({ runId, input, toolCallId: options.toolCallId, signal: options.signal, progress: options.onProgress });
   }
 
@@ -91,7 +91,7 @@ export class WorkspaceOperationExecutor implements WorkspaceExecutor {
 
   async #annotate(runId: string, absolutePath: string): Promise<string | undefined> {
     const notes = await Promise.all(this.#modules.flatMap((module) => module.annotate
-      ? [module.annotate(runId, absolutePath).catch((error: unknown) => `Anmerkung fehlgeschlagen: ${messageOf(error)}`)]
+      ? [module.annotate(runId, absolutePath).catch((error: unknown) => `Annotation failed: ${messageOf(error)}`)]
       : []));
     const text = notes.filter((note): note is string => Boolean(note)).join("\n");
     return text || undefined;