@schlenkr/ragents 0.1.9 → 0.1.11

package/apps/server/src/plugin-support/skills.ts

@@ -27,31 +27,31 @@ type SkillEnvironment = DeclaredEnvironment<(typeof skillEnvDescriptors)[number]
 /** Reads and checks the SKILL.md of a skill folder; the one parser for templates and the skills of agents. */
 const readSkill = (directory: string): { skill: Skill; start: (idPrefix: string) => SkillStartEntry | undefined } => {
   const file = path.join(directory, "SKILL.md");
-  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`Dem Skill ${directory} fehlt die SKILL.md`);
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`The skill ${directory} is missing its SKILL.md`);
   const raw = readFileSync(file, "utf8");
-  if (!FRONT_MATTER.test(raw)) throw new Error(`${file}: es fehlt der ---Kopf mit name und description`);
+  if (!FRONT_MATTER.test(raw)) throw new Error(`${file}: the --- header with name and description is missing`);
   const { frontmatter, body } = parseFrontmatter(raw);
-  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) throw new Error(`${file}: Kopf muss ein Objekt sein`);
+  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) throw new Error(`${file}: header must be an object`);
   const metadata = ["license", "compatibility", "metadata", "allowed-tools"];
   const fields = new Map(Object.entries(frontmatter).filter(([key]) => !metadata.includes(key)).map(([key, value]) => {
     const flagField = ["start", "disable-model-invocation", "user-invokable"].includes(key);
-    if (flagField && typeof value !== "boolean") throw new Error(`${file}: ${key} muss true oder false sein`);
+    if (flagField && typeof value !== "boolean") throw new Error(`${file}: ${key} must be true or false`);
     if (value === null) return [key, ""];
     if (typeof value !== "string" && !(flagField && typeof value === "boolean") && !(key === "order" && typeof value === "number")) {
-      throw new Error(`${file}: ${key} hat einen ungültigen Wert`);
+      throw new Error(`${file}: ${key} has an invalid value`);
     }
     return [key, String(value)];
   }));
   const allowed = ["name", "description", "start", "title", "category", "order", "tags", "guide", "prompt", "disable-model-invocation", "user-invokable"];
   const unknown = [...fields.keys()].filter((key) => !allowed.includes(key));
-  if (unknown.length > 0) throw new Error(`${file}: unbekannte Kopfzeilen ${unknown.join(", ")}`);
+  if (unknown.length > 0) throw new Error(`${file}: unknown header lines ${unknown.join(", ")}`);
   const name = fields.get("name");
-  if (!name) throw new Error(`${file}: name fehlt`);
-  if (name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new Error(`${file}: name ist kein gültiger Skillname`);
-  if (name !== path.basename(directory)) throw new Error(`${file}: name muss dem Skill-Ordner entsprechen`);
+  if (!name) throw new Error(`${file}: name is missing`);
+  if (name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new Error(`${file}: name is not a valid skill name`);
+  if (name !== path.basename(directory)) throw new Error(`${file}: name must match the skill folder`);
   const description = fields.get("description");
-  if (!description) throw new Error(`${file}: description fehlt`);
-  if (!body.trim()) throw new Error(`${file}: Skill-Anleitung ist leer`);
+  if (!description) throw new Error(`${file}: description is missing`);
+  if (!body.trim()) throw new Error(`${file}: skill instructions are empty`);
   const disableModelInvocation = flag(file, "disable-model-invocation", fields.get("disable-model-invocation"));
   flag(file, "user-invokable", fields.get("user-invokable"));
   const order = numberOf(file, "order", fields.get("order"));
@@ -61,13 +61,13 @@ const readSkill = (directory: string): { skill: Skill; start: (idPrefix: string)
   };
   if (!flag(file, "start", fields.get("start"))) return { skill, start: () => undefined };
   const title = fields.get("title");
-  if (!title) throw new Error(`${file}: title fehlt`);
+  if (!title) throw new Error(`${file}: title is missing`);
   const category = fields.get("category");
-  if (!category) throw new Error(`${file}: category fehlt`);
+  if (!category) throw new Error(`${file}: category is missing`);
   const prompt = fields.get("prompt") ?? body.trim();
-  if (!prompt.trim()) throw new Error(`${file}: prompt ist leer`);
+  if (!prompt.trim()) throw new Error(`${file}: prompt is empty`);
   const guide = fields.get("guide");
-  if (guide !== undefined && !guide) throw new Error(`${file}: guide ist leer`);
+  if (guide !== undefined && !guide) throw new Error(`${file}: guide is empty`);
   return {
     skill,
     start: (idPrefix) => ({
@@ -94,12 +94,12 @@ export const skillsFromDirectory = (directory: string, idPrefix: string): Folder
   try {
     entries = readdirSync(resolved, { withFileTypes: true });
   } catch (error) {
-    throw new Error(`Das Skill-Verzeichnis ${resolved} ist nicht lesbar (${error instanceof Error ? error.message : String(error)})`);
+    throw new Error(`The skill directory ${resolved} is not readable (${error instanceof Error ? error.message : String(error)})`);
   }
   const stray = entries.filter((entry) => !entry.isDirectory()).map((entry) => entry.name);
-  if (stray.length > 0) throw new Error(`${resolved} enthält Dateien statt Skill-Ordner: ${stray.join(", ")}`);
+  if (stray.length > 0) throw new Error(`${resolved} contains files instead of skill folders: ${stray.join(", ")}`);
   const paths = entries.map((entry) => path.join(resolved, entry.name)).sort();
-  if (paths.length === 0) throw new Error(`${resolved} enthält keinen Skill-Ordner`);
+  if (paths.length === 0) throw new Error(`${resolved} contains no skill folder`);
   const startEntries = paths.flatMap((skillPath) => {
     const entry = readSkill(skillPath).start(idPrefix);
     return entry ? [entry] : [];

package/apps/server/src/plugin-support/start-entries-contract.ts

@@ -1,6 +1,6 @@
 export type StartEntryAction = "skill" | "script";
 
-/** Dieselbe JSON-Form wie im Kern; der Vertrag bleibt importfrei. */
+/** The same JSON shape as in the core; the contract stays free of imports. */
 export type JsonValue = null | string | number | boolean | JsonValue[] | { [key: string]: JsonValue | undefined };
 
 export interface StartEntryBase {
@@ -11,7 +11,7 @@ export interface StartEntryBase {
   order?: number;
   guide?: string;
   tags?: readonly string[];
-  /** Startoptionen, die die Vorlage festlegt: ein Run über sie läuft genau mit diesen Werten. */
+  /** Start options the template fixes: a run started from it runs with exactly these values. */
   fixedStartOptions?: Readonly<Record<string, JsonValue>>;
 }
 
@@ -31,22 +31,22 @@ const text = (value: unknown): value is string => typeof value === "string" && v
 
 const BASE_FIELDS = ["id", "owner", "title", "description", "order", "guide", "tags", "fixedStartOptions", "action"];
 
-const invalid = (detail: string): Error => new Error(`Die Plugin-Konfiguration enthält eine ungültige Vorlage: ${detail}`);
+const invalid = (detail: string): Error => new Error(`The plugin configuration contains an invalid template: ${detail}`);
 
 export const startEntryFrom = (value: unknown): StartEntry => {
-  if (!isRecord(value)) throw invalid("kein Objekt");
-  if (!text(value.id)) throw invalid("id fehlt");
+  if (!isRecord(value)) throw invalid("not an object");
+  if (!text(value.id)) throw invalid("id is missing");
   const id = value.id;
-  if (!text(value.owner) || !text(value.title) || !text(value.description)) throw invalid(`${id}: owner, title und description sind Pflicht`);
-  if (value.order !== undefined && typeof value.order !== "number") throw invalid(`${id}: order ist keine Zahl`);
-  if (value.guide !== undefined && !text(value.guide)) throw invalid(`${id}: guide ist leer`);
+  if (!text(value.owner) || !text(value.title) || !text(value.description)) throw invalid(`${id}: owner, title and description are required`);
+  if (value.order !== undefined && typeof value.order !== "number") throw invalid(`${id}: order is not a number`);
+  if (value.guide !== undefined && !text(value.guide)) throw invalid(`${id}: guide is empty`);
   if (value.tags !== undefined && (!Array.isArray(value.tags)
     || value.tags.some((tag) => !text(tag) || tag !== tag.trim())
     || new Set(value.tags).size !== value.tags.length)) {
-    throw invalid(`${id}: tags müssen eindeutige, nicht leere Schlagworte sein`);
+    throw invalid(`${id}: tags must be unique, non-empty keywords`);
   }
   if (value.fixedStartOptions !== undefined && (!isRecord(value.fixedStartOptions) || Object.keys(value.fixedStartOptions).length === 0)) {
-    throw invalid(`${id}: fixedStartOptions muss mindestens eine Startoption festlegen`);
+    throw invalid(`${id}: fixedStartOptions must fix at least one start option`);
   }
   const base: StartEntryBase = {
     id,
@@ -60,22 +60,22 @@ export const startEntryFrom = (value: unknown): StartEntry => {
   };
   const allowed = (extra: readonly string[]) => {
     const unknown = Object.keys(value).filter((field) => !BASE_FIELDS.includes(field) && !extra.includes(field));
-    if (unknown.length > 0) throw invalid(`${id}: unbekannte Felder ${unknown.join(", ")}`);
+    if (unknown.length > 0) throw invalid(`${id}: unknown fields ${unknown.join(", ")}`);
   };
   switch (value.action) {
     case "skill": {
       allowed(["skill", "prompt", "category"]);
-      if (!text(value.skill)) throw invalid(`${id}: skill fehlt`);
-      if (!text(value.category) || !value.category.trim() || value.category !== value.category.trim()) throw invalid(`${id}: category muss ein einzelner nicht leerer Text sein`);
-      if (!text(value.prompt) || !value.prompt.trim()) throw invalid(`${id}: prompt fehlt oder ist leer`);
+      if (!text(value.skill)) throw invalid(`${id}: skill is missing`);
+      if (!text(value.category) || !value.category.trim() || value.category !== value.category.trim()) throw invalid(`${id}: category must be a single non-empty text`);
+      if (!text(value.prompt) || !value.prompt.trim()) throw invalid(`${id}: prompt is missing or empty`);
       return { ...base, action: "skill", skill: value.skill, category: value.category, prompt: value.prompt };
     }
     case "script":
       allowed(["coordinator", "category"]);
-      if (typeof value.coordinator !== "boolean") throw invalid(`${id}: coordinator muss true oder false sein`);
-      if (value.category !== undefined && (!text(value.category) || value.category !== value.category.trim())) throw invalid(`${id}: category muss ein einzelner nicht leerer Text sein`);
+      if (typeof value.coordinator !== "boolean") throw invalid(`${id}: coordinator must be true or false`);
+      if (value.category !== undefined && (!text(value.category) || value.category !== value.category.trim())) throw invalid(`${id}: category must be a single non-empty text`);
       return { ...base, action: "script", coordinator: value.coordinator, ...(value.category !== undefined ? { category: value.category } : {}) };
     default:
-      throw invalid(`${id}: unbekannte Aktion ${String(value.action)}; gültig sind skill und script`);
+      throw invalid(`${id}: unknown action ${String(value.action)}; valid are skill and script`);
   }
 };

package/apps/server/src/plugin-support/start-options-contract.ts

@@ -9,7 +9,7 @@ export interface StartOptionState {
   presentation: unknown;
   selectable: boolean;
   locked: boolean;
-  /** Ob jemand den Wert vor dem Start gewählt hat; eine Vorlage, die etwas anderes festlegt, lehnt den Start dann ab. */
+  /** Whether someone chose the value before the start; a template that sets something else then rejects the start. */
   chosen: boolean;
 }
 
@@ -35,13 +35,13 @@ const isChoiceOption = (value: unknown): value is ChoicePresentationOption =>
   && (value.hint === undefined || typeof value.hint === "string");
 
 export const choicePresentationFrom = (presentation: unknown, optionId: string): ChoicePresentation | undefined => {
-  if (!isRecord(presentation)) throw new Error(`Die Startoption ${optionId} liefert keine Darstellung`);
+  if (!isRecord(presentation)) throw new Error(`The start option ${optionId} provides no presentation`);
   if (presentation.kind !== "choice") return undefined;
   if (typeof presentation.label !== "string" || !presentation.label) {
-    throw new Error(`Die Auswahl-Darstellung der Startoption ${optionId} hat kein label`);
+    throw new Error(`The choice presentation of the start option ${optionId} has no label`);
   }
   if (!Array.isArray(presentation.options) || !presentation.options.every(isChoiceOption)) {
-    throw new Error(`Die Auswahl-Darstellung der Startoption ${optionId} braucht options aus value und label`);
+    throw new Error(`The choice presentation of the start option ${optionId} needs options made of value and label`);
   }
   return { kind: "choice", label: presentation.label, options: presentation.options };
 };
@@ -55,7 +55,7 @@ export const startOptionStateFrom = (value: unknown): StartOptionState => {
     || typeof value.selectable !== "boolean"
     || typeof value.locked !== "boolean"
     || typeof value.chosen !== "boolean") {
-    throw new Error("Die Startoption entspricht nicht dem erwarteten Format");
+    throw new Error("The start option does not match the expected format");
   }
   return {
     id: value.id,

package/apps/server/src/plugin-support/system-prompts.ts

@@ -38,7 +38,7 @@ const flag = (value: string | undefined, key: string): boolean => {
   if (value === undefined || value === "") return false;
   if (value === "1") return true;
   if (value === "0") return false;
-  throw new Error(`${key} muss "0" oder "1" sein, nicht "${value}"`);
+  throw new Error(`${key} must be "0" or "1", not "${value}"`);
 };
 
 const labelOf = (text: string, id: string): string => {
@@ -52,7 +52,7 @@ export const systemPromptOptionsFromDirectory = (directory: string): readonly Sy
     entries = readdirSync(directory, { withFileTypes: true });
   } catch (error) {
     throw new Error(
-      `Das Prompt-Verzeichnis ${directory} ist nicht lesbar (${error instanceof Error ? error.message : String(error)})`);
+      `The prompt directory ${directory} is not readable (${error instanceof Error ? error.message : String(error)})`);
   }
   const files = entries
     .filter((entry) => entry.isFile() && PROMPT_EXTENSIONS.includes(path.extname(entry.name)))
@@ -65,9 +65,9 @@ export const systemPromptOptionsFromDirectory = (directory: string): readonly Sy
     return { id, label: labelOf(text, id), file, text };
   });
   const duplicate = options.find((option, index) => options.findIndex((other) => other.id === option.id) !== index);
-  if (duplicate) throw new Error(`Das Prompt-Verzeichnis ${directory} enthält die Kennung ${duplicate.id} mehrfach`);
+  if (duplicate) throw new Error(`The prompt directory ${directory} contains the identifier ${duplicate.id} more than once`);
   if (options.length === 0) {
-    throw new Error(`Das Prompt-Verzeichnis ${directory} enthält keine ${PROMPT_EXTENSIONS.join("- oder ")}-Datei`);
+    throw new Error(`The prompt directory ${directory} contains no ${PROMPT_EXTENSIONS.join(" or ")} file`);
   }
   return options;
 };
@@ -94,28 +94,28 @@ export const systemPromptCatalogFromEnvironment = (
   ];
   const collision = options.find((option, index) => options.findIndex((other) => other.id === option.id) !== index);
   if (collision) {
-    throw new Error(`Der Systemprompt ${collision.id} kommt aus dem Plugin-Ordner und aus SYSTEM_PROMPTS_DIR`);
+    throw new Error(`The system prompt ${collision.id} comes from the plugin folder and from SYSTEM_PROMPTS_DIR`);
   }
   if (options.length === 0) {
     return Object.freeze({ mode: "fixed" as const, options: [], defaultIds: [], shareDefault: false });
   }
   if (mode !== undefined && !SYSTEM_PROMPT_MODES.includes(mode as SystemPromptMode)) {
-    throw new Error(`SYSTEM_PROMPT_MODE muss einer der Werte ${SYSTEM_PROMPT_MODES.join(", ")} sein, nicht "${mode}"`);
+    throw new Error(`SYSTEM_PROMPT_MODE must be one of ${SYSTEM_PROMPT_MODES.join(", ")}, not "${mode}"`);
   }
   const effectiveMode = (mode ?? "selectable") as SystemPromptMode;
   const wanted = (defaultId ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
   if (effectiveMode === "fixed" && wanted.length === 0) {
-    throw new Error("SYSTEM_PROMPT_MODE ist fixed, SYSTEM_PROMPT_DEFAULT benennt dann die gültigen Prompts");
+    throw new Error("SYSTEM_PROMPT_MODE is fixed, so SYSTEM_PROMPT_DEFAULT names the valid prompts");
   }
   for (const id of wanted) {
     if (!options.some((option) => option.id === id)) {
       throw new Error(
-        `SYSTEM_PROMPT_DEFAULT ${id} ist kein auswählbarer Systemprompt; `
-        + `vorhanden sind ${options.map((option) => option.id).join(", ")}`);
+        `SYSTEM_PROMPT_DEFAULT ${id} is not a selectable system prompt; `
+        + `available are ${options.map((option) => option.id).join(", ")}`);
     }
   }
   const duplicate = wanted.find((id, index) => wanted.indexOf(id) !== index);
-  if (duplicate) throw new Error(`SYSTEM_PROMPT_DEFAULT nennt ${duplicate} mehrfach`);
+  if (duplicate) throw new Error(`SYSTEM_PROMPT_DEFAULT names ${duplicate} more than once`);
   return Object.freeze({
     mode: effectiveMode,
     options,
@@ -132,7 +132,7 @@ export const selectedSystemPrompts = (
   const wanted = catalog.mode === "fixed" ? catalog.defaultIds : selection ?? catalog.defaultIds;
   return wanted.map((id) => {
     const option = catalog.options.find((entry) => entry.id === id);
-    if (!option) throw new Error(`Der Systemprompt ${id} ist nicht mehr konfiguriert`);
+    if (!option) throw new Error(`The system prompt ${id} is no longer configured`);
     return option;
   });
 };

package/apps/server/src/plugin-support/thinking-level.ts

@@ -3,11 +3,11 @@ import { modelDefaultThinking } from "./model-aliases.js";
 
 export const checkedThinkingLevel = (value: string, label: string): ThinkingLevel => {
   if (!isThinkingLevel(value)) {
-    throw new Error(`${label} hat die unbekannte Denktiefe "${value}"; erlaubt sind ${thinkingLevels.join(", ")}.`);
+    throw new Error(`${label} has the unknown thinking level "${value}"; allowed are ${thinkingLevels.join(", ")}.`);
   }
   return value;
 };
 
-/** Die Denktiefe einer Rolle: ihr Schlüssel, sonst die Denktiefe, die der Alias ihres Modells mitbringt, sonst high. */
+/** The thinking level of a role: its key, otherwise the thinking level the alias of its model brings along, otherwise high. */
 export const roleThinkingLevel = (configured: string | undefined, label: string, provider: string, model: string): ThinkingLevel =>
   checkedThinkingLevel(configured || modelDefaultThinking(provider, model) || "high", label);

package/apps/server/src/plugin-support/tool-availability.ts

@@ -5,10 +5,10 @@ import {
 
 export const alwaysAvailable = defineToolAvailability({
   availability: "always",
-  availabilityDetail: "In jedem Modell-Turn verfügbar.",
+  availabilityDetail: "Available in every model turn.",
 }, () => true);
 
 export const facesOperator: ToolAvailability = defineToolAvailability({
   availability: "always",
-  availabilityDetail: "In jedem Turn verfügbar; die Frage geht immer an den Benutzer des Runs.",
+  availabilityDetail: "Available in every turn; the question always goes to the user of the run.",
 }, () => true);

package/apps/server/src/plugin-support/workspace-ownership.ts

@@ -8,7 +8,7 @@ export interface WorkspaceIdentity {
   storageRoot?: string;
 }
 
-/** Was während des Abgleichs verschwindet, etwa ein umbenanntes Paket aus dem Staging, braucht keine Rechte mehr. */
+/** Whatever vanishes during the sync, such as a renamed package from staging, no longer needs rights. */
 const unlessVanished = (error: NodeJS.ErrnoException): undefined => {
   if (error.code === "ENOENT") return undefined;
   throw error;
@@ -17,11 +17,11 @@ const unlessVanished = (error: NodeJS.ErrnoException): undefined => {
 export const syncWorkspaceOwnership = async (directory: string, identity: WorkspaceIdentity): Promise<void> => {
   if (identity.uid === undefined && identity.gid === undefined) return;
   if (identity.uid === undefined || identity.gid === undefined || !identity.storageRoot) {
-    throw new Error("Für private Arbeitsdateien fehlen UID, GID oder die Run-Speichergrenze.");
+    throw new Error("Private working files are missing a UID, GID or the run storage boundary.");
   }
-  if ((await lstat(directory)).isSymbolicLink()) throw new Error("Das private Arbeitsverzeichnis darf kein Symlink sein.");
+  if ((await lstat(directory)).isSymbolicLink()) throw new Error("The private working directory must not be a symlink.");
   const [root, target] = await Promise.all([realpath(identity.storageRoot), realpath(directory)]);
-  if (!containsWorkspacePath(root, target) || target === root) throw new Error("Das private Arbeitsverzeichnis liegt außerhalb seiner Run-Speichergrenze.");
+  if (!containsWorkspacePath(root, target) || target === root) throw new Error("The private working directory lies outside its run storage boundary.");
   const { uid, gid } = identity;
   const visit = async (file: string): Promise<void> => {
     const info = await lstat(file).catch(unlessVanished);
@@ -34,7 +34,7 @@ export const syncWorkspaceOwnership = async (directory: string, identity: Worksp
   await visit(target);
   for (let ancestor = path.dirname(target); containsWorkspacePath(root, ancestor); ancestor = path.dirname(ancestor)) {
     const info = await lstat(ancestor);
-    if (!info.isDirectory()) throw new Error("Ein Vorfahr des Arbeitsverzeichnisses ist kein Verzeichnis.");
+    if (!info.isDirectory()) throw new Error("An ancestor of the working directory is not a directory.");
     const mode = (info.mode & 0o7777) | 0o111;
     if ((info.mode & 0o7777) !== mode) await chmod(ancestor, mode);
     if (ancestor === root) break;

package/apps/server/src/plugin-support/workspace-sandbox-host.ts

@@ -48,23 +48,23 @@ export interface RegisteredWorkspaceRoot {
   ownershipDirectoryFor?: (runId: string) => string | Promise<string>;
 }
 
-/** Eine Wurzel des Servers, wie ein Prompt sie nennt: ihr Alias, ob Werkzeuge darin schreiben dürfen, und die Variable, die sie in einer Bash auf dem Server nennt. */
+/** A root of the server as a prompt names it: its alias, whether tools may write in it, and the variable that names it in a bash on the server. */
 export interface ServerRootDescription {
   readonly alias: string;
   readonly writable: boolean;
   readonly environmentVariable?: string;
 }
 
-/** Der einzige Zugang der Plugins zum Arbeitsbereich eines Runs: eine Operation läuft beim Executor der Maschine, der die angesprochene Wurzel gehört. */
+/** The plugins' only access to a run's workspace: an operation runs at the executor of the machine that owns the addressed root. */
 export interface SandboxServices {
   execute: (runId: string, operation: string, input: unknown, options?: WorkspaceExecuteOptions) => Promise<unknown>;
-  /** Der Kontext für Arbeit, die auf dem Server läuft (TypeScript-Plattform, Actor-Programme); nie der Ordner eines Arbeitsplatzes. */
+  /** The context for work that runs on the server (TypeScript platform, actor programs); never the folder of a workstation. */
   serverProcessContextFor: (runId: string) => Promise<WorkspaceProcessContext>;
   registerWorkspaceRoot: (root: RegisteredWorkspaceRoot) => void;
   shutdown: (runId: string) => Promise<void>;
 }
 
-/** Ein fachlicher Fehler des Executors sieht beim Aufrufer aus wie jeder andere Fehler des Servers. */
+/** A domain error of the executor looks to the caller like any other error of the server. */
 export const withDomainCause = (error: unknown): unknown =>
   error instanceof WorkspaceOperationError ? new DomainError(error.code, error.message, error.status) : error;
 
@@ -72,24 +72,24 @@ export const sandboxServicesToken = serviceToken<SandboxServices>("ragents.works
 
 export interface WorkspaceSandboxHostOptions {
   contributorName: string;
-  /** Was die Plugins des Profils zum Executor dieses Servers beitragen; jeder Arbeitsplatz der Runs trägt dieselben Beiträge. */
+  /** What the profile's plugins contribute to this server's executor; every workstation of the runs carries the same contributions. */
   contributions: readonly WorkspaceExecutorParts[];
   workspaceFor: (runId: string) => Promise<SessionWorkspace>;
   identFor: (runId: string) => Promise<SessionIdent | undefined>;
   skillPaths: () => Promise<readonly string[]>;
   homeFor: (runId: string) => Promise<SandboxHomeEnvironment>;
   storageRootFor?: (runId: string) => string;
-  /** Der Executor eines Runs, der nicht auf dem Server arbeitet; ohne Antwort führt der Executor des Servers aus. */
+  /** The executor of a run that does not work on the server; without an answer the server's executor executes. */
   executorFor?: (runId: string) => Promise<WorkspaceExecutor | undefined>;
-  /** Der eigene Ordner eines solchen Runs auf dem Server, für Arbeit, die dort läuft. */
+  /** The own folder of such a run on the server, for work that runs there. */
   serverDirectoryFor?: (runId: string) => Promise<string>;
-  /** Die Prozess-Sandbox, in der jeder Prozess des Executors dieses Servers startet; ohne sie laufen Prozesse ohne. */
+  /** The process sandbox in which every process of this server's executor starts; without it processes run without one. */
   processSandbox?: RunProcessSandboxes;
-  /** Die Bash des Executors dieses Servers; unter Windows Pflicht, sonst ohne Angabe die des Systems. */
+  /** The bash of this server's executor; required on Windows, otherwise the system's when not set. */
   bash?: string;
-  /** Das rg des Executors dieses Servers; ohne Angabe gilt eines im PATH. */
+  /** The rg of this server's executor; when not set, one on the PATH applies. */
   rg?: string;
-  /** Die Zeitgrenze von bash in Sekunden für Aufrufe ohne eigene, auf jeder Maschine der Runs; ohne Angabe die des Werkzeugs. */
+  /** The bash time limit in seconds for calls without their own, on every machine of the runs; when not set, the tool's. */
   bashTimeoutSeconds?: number;
 }
 
@@ -102,7 +102,7 @@ const sandboxDescriptions: Readonly<Record<string, string>> = {
 
 const describeSandboxTool = (definition: AgentToolDefinition): AgentToolDefinition => {
   const description = sandboxDescriptions[definition.name];
-  if (!description) throw new Error(`Das Sandbox-Werkzeug ${definition.name} hat keine Kurzbeschreibung`);
+  if (!description) throw new Error(`The sandbox tool ${definition.name} has no short description`);
   return { ...definition, description, longDescription: definition.description, nativeTool: true };
 };
 
@@ -119,39 +119,39 @@ interface StableRunParts {
   ident?: SessionIdent;
   home: SandboxHomeEnvironment;
   readOnlyRoots: readonly ResolvedWorkspaceRoot[];
-  /** Der eigene Temp-Ordner des Runs in der Sandbox. */
+  /** The run's own temp folder in the sandbox. */
   temporary?: string;
 }
 
 const mixedRoots = (aliases: readonly string[]): DomainError => new DomainError(
   "workspace-roots-mixed",
-  `Der Aufruf nennt ${aliases.join(", ")} auf dem Server und zugleich einen Pfad im Arbeitsbereich auf dem Arbeitsplatz; `
-    + "ein Aufruf erreicht nur einen Rechner. Teile ihn in einen Aufruf je Rechner.",
+  `The call names ${aliases.join(", ")} on the server and at the same time a path in the workspace on the workstation; `
+    + "a call reaches only one machine. Split it into one call per machine.",
   400,
 );
 
-/** Die Ordner, die ein Arbeitsbereich der Prozess-Sandbox zusätzlich öffnet, getrennt nach Zugriff; ein relativer Pfad hätte auf dem Server keinen Ort. */
+/** The folders a workspace additionally opens to the process sandbox, separated by access; a relative path would have no location on the server. */
 const sandboxFoldersWith = (folders: readonly SandboxFolder[], access: SandboxFolder["access"]): string[] =>
   folders.filter((folder) => folder.access === access).map((folder) => {
-    if (!path.isAbsolute(folder.directory)) throw new Error(`Der Ordner ${folder.directory} für die Prozess-Sandbox muss absolut sein`);
+    if (!path.isAbsolute(folder.directory)) throw new Error(`The folder ${folder.directory} for the process sandbox must be absolute`);
     return folder.directory;
   });
 
-/** Ein nur lesbarer Pfad, den es nicht gibt, ist keine Wurzel; ein fehlender Skill-Ordner darf keinen Run verhindern. */
+/** A read-only path that does not exist is not a root; a missing skill folder must not prevent a run. */
 const existingRoots = async (roots: readonly ResolvedWorkspaceRoot[]): Promise<ResolvedWorkspaceRoot[]> => {
   const resolved = await Promise.all(roots.map((root) =>
     realpath(root.directory).then((directory) => ({ ...root, directory }), () => undefined)));
   return resolved.filter((root) => root !== undefined);
 };
 
-/** Der Executor des Servers mit den Wurzeln des Servers; eine Operation mit Alias läuft dort, jede andere beim Executor der Bindung des Runs. */
+/** The server's executor with the server's roots; an operation with an alias runs there, every other one at the executor of the run's binding. */
 export class WorkspaceSandboxHost implements SandboxServices {
   readonly #options: WorkspaceSandboxHostOptions;
   readonly #definitions: readonly AgentToolDefinition[];
   readonly #workspaceRoots: RegisteredWorkspaceRoot[] = [];
   readonly #local: WorkspaceOperationExecutor;
   readonly #stable = new Map<string, Promise<StableRunParts>>();
-  /** Je Run der Dateistand, den ein Modell zuletzt gesehen hat, nach Actor, Modellkontext und Pfad; nur im Speicher, ein Verlust verlangt höchstens ein neues read. */
+  /** Per run the file state a model saw last, by actor, model context and path; only in memory, a loss requires at most a new read. */
   readonly #seen = new Map<string, Map<string, SeenFile>>();
 
   constructor(options: WorkspaceSandboxHostOptions) {
@@ -165,14 +165,14 @@ export class WorkspaceSandboxHost implements SandboxServices {
 
   registerWorkspaceRoot(root: RegisteredWorkspaceRoot): void {
     if (!root.id.trim() || this.#workspaceRoots.some((entry) => entry.id === root.id)) {
-      throw new Error(`Arbeitsverzeichnis ${root.id} ist leer oder bereits registriert`);
+      throw new Error(`Working directory ${root.id} is empty or already registered`);
     }
     if (root.alias && (!/^@[a-z][a-z0-9-]*$/.test(root.alias) || root.alias === SKILLS_ALIAS
       || this.#workspaceRoots.some((entry) => entry.alias === root.alias))) {
-      throw new Error(`Arbeitsverzeichnis-Alias ${root.alias} ist ungültig, dem Host vorbehalten oder bereits registriert`);
+      throw new Error(`Working directory alias ${root.alias} is invalid, reserved for the host or already registered`);
     }
     if (root.environmentVariable && (!/^RAGENTS_[A-Z_]+_DIR$/.test(root.environmentVariable) || this.#workspaceRoots.some((entry) => entry.environmentVariable === root.environmentVariable))) {
-      throw new Error(`Arbeitsverzeichnis-Variable ${root.environmentVariable} ist ungültig oder bereits registriert`);
+      throw new Error(`Working directory variable ${root.environmentVariable} is invalid or already registered`);
     }
     this.#workspaceRoots.push(root);
   }
@@ -181,7 +181,7 @@ export class WorkspaceSandboxHost implements SandboxServices {
     const roots = await Promise.all(this.#workspaceRoots.map(async (entry) => {
       const directory = await entry.directoryFor(runId);
       if (directory === undefined) return undefined;
-      if (!path.isAbsolute(directory)) throw new Error(`Arbeitsverzeichnis ${entry.id} muss absolut sein`);
+      if (!path.isAbsolute(directory)) throw new Error(`Working directory ${entry.id} must be absolute`);
       if (ident) await syncWorkspaceOwnership(await entry.ownershipDirectoryFor?.(runId) ?? directory, {
         ...ident, storageRoot: this.#options.storageRootFor?.(runId),
       });
@@ -190,7 +190,7 @@ export class WorkspaceSandboxHost implements SandboxServices {
     return roots.filter((root) => root !== undefined);
   }
 
-  /** Die Wurzeln des Servers mit Alias, die ein Run neben seinem Arbeitsbereich erreicht: die registrierten und die Skill-Ordner. */
+  /** The server's roots with an alias that a run reaches besides its workspace: the registered ones and the skill folders. */
   async serverRoots(): Promise<readonly ServerRootDescription[]> {
     const registered = this.#workspaceRoots.flatMap(({ alias, environmentVariable }) => alias === undefined ? [] : [{
       alias, writable: true, ...(environmentVariable === undefined ? {} : { environmentVariable }),
@@ -199,15 +199,15 @@ export class WorkspaceSandboxHost implements SandboxServices {
     return [...registered, ...skills];
   }
 
-  /** Bei einem Run mit eigenem Executor ein Ordner des Runs auf dem Server, sonst derselbe Kontext wie für seine Werkzeuge. */
+  /** For a run with its own executor a folder of the run on the server, otherwise the same context as for its tools. */
   async serverProcessContextFor(runId: string): Promise<WorkspaceProcessContext> {
     if (!await this.#options.executorFor?.(runId)) return this.#contextFor(runId);
     const serverDirectoryFor = this.#options.serverDirectoryFor;
-    if (!serverDirectoryFor) throw new Error(`Der Run ${runId} arbeitet nicht auf dem Server, und der Sandbox-Host kennt keinen Serverordner für ihn`);
+    if (!serverDirectoryFor) throw new Error(`The run ${runId} does not work on the server, and the sandbox host knows no server folder for it`);
     return this.#contextFor(runId, await serverDirectoryFor(runId));
   }
 
-  /** Der Kontext des Executors dieses Servers; ohne eigenen Ordner der Arbeitsbereich selbst, der dafür auf dem Server liegen muss. */
+  /** The context of this server's executor; without its own folder the workspace itself, which must then lie on the server. */
   async #contextFor(runId: string, serverDirectory?: string): Promise<WorkspaceProcessContext> {
     const workspace = await this.#options.workspaceFor(runId);
     const { ident, home, readOnlyRoots, temporary } = await this.#stableParts(runId, workspace);
@@ -245,18 +245,18 @@ export class WorkspaceSandboxHost implements SandboxServices {
     });
   }
 
-  /** Der Temp-Ordner eines Runs liegt in seiner Ablage, damit er mit dem Run verschwindet und kein anderer Run ihn sieht. */
+  /** A run's temp folder lies in its storage so that it vanishes with the run and no other run sees it. */
   async #temporaryFor(runId: string, ident: SessionIdent | undefined): Promise<string | undefined> {
     if (!this.#options.processSandbox) return undefined;
     const storageRoot = this.#options.storageRootFor?.(runId);
-    if (!storageRoot) throw new Error(`Die Prozess-Sandbox braucht die Ablage des Runs ${runId} für seinen Temp-Ordner`);
+    if (!storageRoot) throw new Error(`The process sandbox needs the storage of the run ${runId} for its temp folder`);
     const directory = path.join(storageRoot, "tmp");
     await mkdir(directory, { recursive: true });
     if (ident) await syncWorkspaceOwnership(directory, { ...ident, storageRoot });
     return realpath(directory);
   }
 
-  /** Kennung, Heimatordner und nur lesbare Wurzeln stehen je Run fest; nur sie werden gemerkt. */
+  /** Identity, home folder and read-only roots are fixed per run; only they are remembered. */
   #stableParts(runId: string, workspace: SessionWorkspace): Promise<StableRunParts> {
     const known = this.#stable.get(runId);
     if (known) return known;
@@ -301,7 +301,7 @@ export class WorkspaceSandboxHost implements SandboxServices {
     };
   }
 
-  /** Die Laufzeit, die eine Eingabe selbst verlangt, gilt, wenn der Aufrufer keine nennt; sie verlängert nur das Warten auf einen entfernten Executor. */
+  /** The duration an input asks for itself applies when the caller names none; it only extends the wait for a remote executor. */
   async execute(runId: string, operation: string, input: unknown, options: WorkspaceExecuteOptions = {}): Promise<unknown> {
     try {
       const { roots, durationMs } = this.#local.footprintOf(operation, input);
@@ -313,7 +313,7 @@ export class WorkspaceSandboxHost implements SandboxServices {
     }
   }
 
-  /** Auch ein Run mit eigenem Executor hat auf dem Server markierte Prozesse der TypeScript-Plattform; beide Executoren räumen ab. */
+  /** A run with its own executor also has marked TypeScript platform processes on the server; both executors clean up. */
   async shutdown(runId: string): Promise<void> {
     this.#stable.delete(runId);
     this.#seen.delete(runId);
@@ -329,7 +329,7 @@ export class WorkspaceSandboxHost implements SandboxServices {
     return this.#local.shutdown();
   }
 
-  /** Aliasse nennen Wurzeln des Servers, jeder andere Pfad die Wurzel des Runs auf der Maschine seiner Bindung; ohne Alias entscheidet die Bindung. */
+  /** Aliases name roots of the server, every other path the run's root on the machine of its binding; without an alias the binding decides. */
   async #executorFor(runId: string, { aliases, runRoot }: AddressedRoots): Promise<WorkspaceExecutor> {
     const bound = await this.#options.executorFor?.(runId);
     if (!bound || aliases.length === 0) return bound ?? this.#local;
@@ -342,7 +342,7 @@ export class WorkspaceSandboxHost implements SandboxServices {
       const described = describeSandboxTool(definition);
       const proxy = {
         ...described,
-        // Die Vorgaben des Schemas, etwa die Zeitgrenze von bash, setzt der Server ein; so gilt auf jeder Maschine, was das Modell im Schema sieht.
+        // The server fills in the schema defaults, such as the bash time limit; so what the model sees in the schema applies on every machine.
         execute: (toolCallId: string, params: unknown, signal: AbortSignal | undefined) =>
           this.execute(context.runId, described.name, Value.Default(described.parameters, structuredClone(params)), {
             toolCallId,
@@ -356,7 +356,7 @@ export class WorkspaceSandboxHost implements SandboxServices {
     }));
   }
 
-  /** Ein direkter Aufruf des Modells gibt den Stand mit, den es von der Datei gesehen hat, und merkt sich den neuen; ein Aufruf aus TypeScript arbeitet ohne. */
+  /** A direct call of the model passes the state it has seen of the file and remembers the new one; a call from TypeScript works without it. */
   async #fileToolCall(runId: string, name: string, scope: ToolScope, toolCallId: string, input: { path: string }): Promise<string> {
     const options = { toolCallId, ...(scope.signal ? { signal: scope.signal } : {}) };
     if (scope.modelContext === undefined) return textOf(await this.execute(runId, name, input, options) as ToolOutput);
@@ -364,7 +364,7 @@ export class WorkspaceSandboxHost implements SandboxServices {
     const key = [scope.caller.actorId, scope.modelContext, path.posix.normalize(input.path)].join("\0");
     const result = await this.execute(runId, name, { ...input, seen: known.get(key) ?? null }, options) as ToolOutput & { details?: { seen?: SeenFile } };
     const seen = result.details?.seen;
-    if (!seen) throw new Error(`Der Executor meldet nach ${name} keinen Dateistand; Server und Arbeitsplatz brauchen denselben Executor-Stand`);
+    if (!seen) throw new Error(`The executor reports no file state after ${name}; server and workstation need the same executor version`);
     this.#seen.set(runId, known.set(key, seen));
     return textOf(result);
   }