@schlenkr/ragents 0.1.9 → 0.1.11

package/plugins/ragents.browser/server/browser.ts

@@ -22,7 +22,7 @@ interface SavedCapture {
   path: string;
 }
 
-/** Was der Server von der Seite eines Runs weiß: den zuletzt gemeldeten Stand und die Zeit der letzten bestandenen Prüfung. */
+/** What the server knows about a run's page: the last reported state and the time of the last passed check. */
 interface ObservedPage {
   url: string;
   checkedAt?: string;
@@ -37,7 +37,7 @@ export interface BrowserOptions {
 
 const capturePath = (id: string): string => `browser/${id}.png`;
 
-/** Die Browserprüfung eines Runs: die Seite lebt beim Executor des Runs, Evidenz, Aufnahmen und Viewport hält der Server. */
+/** A run's browser testing: the page lives in the run's executor, the server holds evidence, screenshots and viewport. */
 export class RunBrowser implements BrowserRuntime {
   readonly #options: BrowserOptions;
   readonly #pages = new Map<string, ObservedPage>();
@@ -67,7 +67,7 @@ export class RunBrowser implements BrowserRuntime {
     await this.restore(runId);
     options.signal?.throwIfAborted();
     this.#assertRunning();
-    if (generation !== this.#generation(runId)) throw new Error("Der Browser wurde beendet.");
+    if (generation !== this.#generation(runId)) throw new Error("The browser was closed.");
     return this.#run(runId, BROWSER_OPERATIONS.open, { url, viewport: this.#viewports.get(runId) ?? DEFAULT_VIEWPORT }, options);
   }
 
@@ -75,7 +75,7 @@ export class RunBrowser implements BrowserRuntime {
     return this.#run(runId, BROWSER_OPERATIONS.snapshot, null, options);
   }
 
-  /** Der gewählte Viewport gilt für den Run, auch für einen später neu gestarteten Browser. */
+  /** The chosen viewport applies to the run, including a browser restarted later. */
   async viewport(runId: string, viewport: BrowserViewport, options: BrowserCallOptions = {}): Promise<BrowserSnapshot> {
     const snapshot = await this.#run<BrowserSnapshot>(runId, BROWSER_OPERATIONS.viewport, viewport, options);
     this.#viewports.set(runId, viewport);
@@ -98,7 +98,7 @@ export class RunBrowser implements BrowserRuntime {
     return this.#run(runId, BROWSER_OPERATIONS.press, { target, key }, options);
   }
 
-  /** Die Zeit einer bestandenen Prüfung ist die des Servers, damit sie sich mit seinen übrigen Zeiten vergleichen lässt. */
+  /** The time of a passed check is the server's, so it compares with its other times. */
   async check(runId: string, input: BrowserCheck, options: BrowserCallOptions = {}): Promise<{ checkedAt: string; url: string; assertions: string[] }> {
     const generation = this.#generation(runId);
     const { result, page } = await this.#execute<BrowserCheckResult>(runId, generation, BROWSER_OPERATIONS.check, input, options);
@@ -117,7 +117,7 @@ export class RunBrowser implements BrowserRuntime {
     await this.restore(runId);
     const id = randomUUID();
     const image = await this.#run<string>(runId, BROWSER_OPERATIONS.screenshot, { id, fullPage: input.fullPage ?? false }, options);
-    const capture = { name: input.label?.trim() || "Browseraufnahme", path: capturePath(id) };
+    const capture = { name: input.label?.trim() || "Browser screenshot", path: capturePath(id) };
     await this.#store(runId, capture, Buffer.from(image, "base64"));
     const url = this.#captureUrl(runId, capture.path);
     return {
@@ -130,7 +130,7 @@ export class RunBrowser implements BrowserRuntime {
 
   async image(runId: string): Promise<Buffer> {
     const latest = this.#captures.get(runId)?.at(-1);
-    if (!latest) throw new Error("Für diesen Run gibt es noch keinen Browser-Screenshot. Zuerst browser_screenshot aufrufen.");
+    if (!latest) throw new Error("There is no browser screenshot for this run yet. Call browser_screenshot first.");
     return readFile(path.join(await this.#options.filesFor(runId), latest.path));
   }
 
@@ -152,7 +152,7 @@ export class RunBrowser implements BrowserRuntime {
     };
   }
 
-  /** Schließt den Browser beim Executor des Runs; ein nicht verbundener Arbeitsplatz hält nichts, was sich jetzt schließen ließe. */
+  /** Closes the browser in the run's executor; a disconnected workspace holds nothing that could be closed now. */
   async close(runId: string): Promise<void> {
     this.#forget(runId);
     await this.#options.sandbox.execute(runId, BROWSER_OPERATIONS.close, null, { whenReachable: true });
@@ -178,14 +178,14 @@ export class RunBrowser implements BrowserRuntime {
   }
 
   #assertRunning(): void {
-    if (this.#shutdown) throw new Error("Der Browserdienst ist beendet.");
+    if (this.#shutdown) throw new Error("The browser service has ended.");
   }
 
   #generation(runId: string): number {
     return this.#generations.get(runId) ?? 0;
   }
 
-  /** Ein geschlossener Browser hat keine Seite mehr; Ergebnisse, die vorher begonnen haben, zählen danach nicht. */
+  /** A closed browser has no page anymore; results that started before no longer count afterwards. */
   #forget(runId: string): void {
     this.#generations.set(runId, this.#generation(runId) + 1);
     this.#pages.delete(runId);
@@ -207,14 +207,14 @@ export class RunBrowser implements BrowserRuntime {
     }
   }
 
-  /** Nach einem gescheiterten Aufruf fragt der Server den Stand der Seite nach; wer ihn nicht nennen kann, hat keine Seite. */
+  /** After a failed call the server asks for the page state; whoever cannot report it has no page. */
   async #resync(runId: string, generation: number): Promise<void> {
     const page = await this.#options.sandbox.execute(runId, BROWSER_OPERATIONS.state, null, { whenReachable: true })
       .then((value) => value as BrowserPageState | null, () => null);
     this.#observe(runId, generation, page);
   }
 
-  /** Nur eine bestandene Prüfung setzt die Zeit; jeder andere Stand behält sie, solange die Seite geprüft bleibt. */
+  /** Only a passed check sets the time; every other state keeps it as long as the page stays checked. */
   #observe(runId: string, generation: number, page: BrowserPageState | null, checkedAt?: string): void {
     if (generation !== this.#generation(runId)) return;
     if (!page) {
@@ -230,7 +230,7 @@ export class RunBrowser implements BrowserRuntime {
     });
   }
 
-  /** Legt eine Aufnahme in die Dateiablage des Runs und schreibt die Aufnahmeliste atomar; die Aufnahmen eines Runs der Reihe nach. */
+  /** Puts a screenshot into the run's file storage and writes the screenshot list atomically; a run's screenshots one after another. */
   #store(runId: string, capture: SavedCapture, image: Buffer): Promise<void> {
     const previous = this.#captureWrites.get(runId) ?? Promise.resolve();
     const pending = previous.then(async () => {
@@ -265,7 +265,7 @@ export class RunBrowser implements BrowserRuntime {
     const captures: unknown = JSON.parse(content);
     if (!Array.isArray(captures) || captures.some((entry) => !entry || typeof entry.name !== "string"
       || typeof entry.path !== "string" || !/^browser\/[a-f0-9-]{36}\.png$/.test(entry.path))) {
-      throw new Error("Die gespeicherte Browser-Aufnahmeliste dieses Runs ist beschädigt.");
+      throw new Error("The stored browser screenshot list of this run is corrupt.");
     }
     this.#captures.set(runId, captures);
   }

package/plugins/ragents.browser/server/contract.ts

@@ -11,7 +11,7 @@ export interface BrowserEvidence {
   errors: string[];
 }
 
-/** Wer eine Operation an der Seite auslöst: bei einem Werkzeugaufruf dessen Kennung, dazu der Abbruch. */
+/** Who triggers an operation on the page: for a tool call its id, plus the abort signal. */
 export interface BrowserCallOptions {
   signal?: AbortSignal;
   toolCallId?: string;

package/plugins/ragents.browser/server/index.ts

@@ -7,7 +7,7 @@ import { RunBrowser } from "./browser.js";
 import { browserRuntimeToken } from "./contract.js";
 import { createBrowserFunctions, createBrowserImageContribution } from "./tools.js";
 
-/** Der Executor des Servers liest den Wert aus seiner Umgebung; ein Arbeitsplatz aus seiner eigenen, nie aus dem Profil. */
+/** The server's executor reads the value from its environment; a workspace from its own, never from the profile. */
 export const browserConfigDescriptors = [{ key: BROWSER_EXECUTABLE_VARIABLE, source: "environment" }] as const;
 
 const browserPlugin: RAgentsPlugin = {

package/plugins/ragents.browser/server/tools.ts

@@ -30,7 +30,7 @@ const screenshotDescription = "Capture the real browser page into this run's doc
 export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   defineRunFunction({
     name: "browser_open",
-    label: "Browser öffnen",
+    label: "Open browser",
     description: "Open an HTTP(S) page in this run's isolated headless browser. Returns its accessible structure and browser errors. Reuses the current run browser; other runs have separate cookies and processes.",
     schema: Type.Object({ url: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
     resultSchema: snapshotSchema,
@@ -41,7 +41,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_snapshot",
-    label: "Browser lesen",
+    label: "Read browser",
     description: "Read the current real page's accessible structure, title, URL and errors. Use role/name or labels for subsequent actions; snapshot reference IDs never need to be copied.",
     schema: emptySchema,
     resultSchema: snapshotSchema,
@@ -52,7 +52,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_click",
-    label: "Im Browser klicken",
+    label: "Click in browser",
     description: "Click a uniquely identified visible element with Playwright auto-waiting. Returns the actual resulting page. Ambiguous or absent targets are errors.",
     schema: targetInputSchema,
     resultSchema: snapshotSchema,
@@ -63,7 +63,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_fill",
-    label: "Browserfeld ausfüllen",
+    label: "Fill browser field",
     description: "Fill an input or textarea by accessible label or another semantic target, firing the normal input events. Returns the resulting page.",
     schema: Type.Object({ target: targetSchema, value: Type.String() }, { additionalProperties: false }),
     resultSchema: snapshotSchema,
@@ -74,7 +74,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_select",
-    label: "Im Browser auswählen",
+    label: "Select in browser",
     description: "Choose an option by its visible label in a native select element. For custom dropdowns use browser_click on the trigger and the visible option.",
     schema: Type.Object({ target: targetSchema, label: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
     resultSchema: snapshotSchema,
@@ -85,7 +85,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_press",
-    label: "Browsertaste drücken",
+    label: "Press browser key",
     description: "Focus a target and press a Playwright key or chord such as Enter, Escape, Tab or ControlOrMeta+A. Returns the resulting page.",
     schema: Type.Object({ target: targetSchema, key: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
     resultSchema: snapshotSchema,
@@ -96,7 +96,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_check",
-    label: "Browserergebnis prüfen",
+    label: "Check browser result",
     description: "Assert visible target/text, resulting URL and absence of browser errors. Fails on mismatch; records successful evidence for this page until the next action/navigation/error. Supply at least one assertion. Browser errors are checked by default. Visibility assertions wait at most 5 seconds, shorter than actions.",
     schema: Type.Object({
       target: Type.Optional(targetSchema),
@@ -113,7 +113,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_viewport",
-    label: "Browsergröße setzen",
+    label: "Set browser size",
     description: "Resize the page viewport in CSS pixels, for example to check a narrow layout. The default is 1920 x 1080 (16:9) and screenshots use the viewport size at scale 1; the chosen size stays for the run until changed again. Returns the resulting page.",
     schema: Type.Object({
       width: Type.Integer({ minimum: 320, maximum: 3840 }),
@@ -126,7 +126,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_screenshot",
-    label: "Browser aufnehmen",
+    label: "Capture browser",
     description: screenshotDescription,
     schema: Type.Object({ label: Type.Optional(Type.String({ maxLength: 200 })), fullPage: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
     resultSchema: Type.Object({
@@ -143,7 +143,7 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
   }),
   defineRunFunction({
     name: "browser_view_screenshot",
-    label: "Browseraufnahme ansehen",
+    label: "View browser screenshot",
     description: "View this run's latest screenshot as native image input without a path. Invoke this native tool directly to receive pixels; calling it through TypeScript only verifies image availability. Requires an image-capable model for native image input.",
     nativeTool: true,
     schema: emptySchema,
@@ -153,12 +153,12 @@ export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
     run: async ({ caller, signal }) => {
       signal?.throwIfAborted();
       await browser.image(caller.runId);
-      return "Letzte Browseraufnahme dieses Runs ist verfügbar.";
+      return "The latest browser screenshot of this run is available.";
     },
   }),
   defineRunFunction({
     name: "browser_close",
-    label: "Browser schließen",
+    label: "Close browser",
     description: "Close this run's browser and discard its cookies. Saved screenshots remain in the document library.",
     schema: emptySchema,
     resultSchema: Type.Object({ closed: Type.Boolean() }, { additionalProperties: false }),
@@ -175,11 +175,11 @@ export const createBrowserImageContribution = (browser: RunBrowser): AgentContri
     if (outcome.toolName !== "browser_view_screenshot" || outcome.isError) return undefined;
     try {
       call.signal?.throwIfAborted();
-      if (!call.modelReadsImages) throw new Error("Das gewählte Modell unterstützt keine Bilder. Screenshot über die Dokumente ansehen oder ein bildfähiges Modell wählen.");
+      if (!call.modelReadsImages) throw new Error("The selected model does not support images. View the screenshot in the documents or choose an image-capable model.");
       const data = (await browser.image(runId)).toString("base64");
       call.signal?.throwIfAborted();
       return { content: [
-        { type: "text", text: "Letzte Browseraufnahme dieses Runs." },
+        { type: "text", text: "Latest browser screenshot of this run." },
         { type: "image", data, mimeType: "image/png" },
       ] };
     } catch (error) {

package/plugins/ragents.browser/skills/browser-testing/SKILL.md

@@ -1,38 +1,38 @@
 ---
 name: browser-testing
-description: Prüfe eine laufende Webanwendung mit echten Browseraktionen, sichtbaren Ergebnissen und Screenshots.
+description: Test a running web application with real browser actions, visible results, and screenshots.
 ---
 
-# Webanwendung prüfen
+# Testing a web application
 
-Verwende die TypeScript-Funktionen `browser_open`, `browser_snapshot`, `browser_click`,
+Use the TypeScript functions `browser_open`, `browser_snapshot`, `browser_click`,
 `browser_fill`, `browser_select`, `browser_press`, `browser_check`, `browser_viewport`,
-`browser_screenshot` und `browser_close`. Lade deren genaue Verträge mit `typescript_api`.
+`browser_screenshot` and `browser_close`. Load their exact contracts with `typescript_api`.
 
-1. Starte die Anwendung mit ihren tatsächlichen Diensten und warte auf deren Bereitschaft.
-2. Öffne ihre HTTP-Adresse mit `browser_open`. Jeder Run hat einen eigenen Browser ohne
-   übernommene Anmeldung. Er läuft auf dem Rechner Deines Arbeitsbereichs; eine dort gestartete
-   Anwendung erreichst Du über `localhost`. Melde fehlende Dienste und Browser-Voraussetzungen
-   ausdrücklich.
-3. Lies den Snapshot und bediene den tatsächlichen Nutzerweg. Wähle Ziele über sichtbare
-   Rollen/Namen oder Feldbeschriftungen, beispielsweise `{ role: "button", name: "Speichern" }`.
-   Die Auflösung erfolgt im Browser. Snapshot-IDs werden nicht abgeschrieben.
-4. Prüfe Erfolg und relevante Fehlerfälle mit `browser_check`: sichtbares Ergebnis, Zieladresse
-   und Browserfehler. Ein Typecheck oder Screenshot allein belegt keinen erfolgreichen Nutzerweg.
-   Nach jeder Aktion ist eine neue Prüfung nötig. Erfinde keine Ergebnisse bei fehlendem Netz.
-5. Erzeuge mit `browser_screenshot` echte Aufnahmen. Übernimm `url` oder `markdown`
-   programmatisch in den Ergebnisbericht oder die Mini-App. Das Bild liegt in der Dateiablage
-   dieses Runs. Das native Werkzeug `browser_view_screenshot` zeigt Dir die letzte Aufnahme
-   ohne Pfadangabe; dafür benötigt Dein Modell Bildunterstützung. Der Viewport ist standardmäßig
-   1920 x 1080 (16:9); für schmale Layouts oder kleine Bildschirme stellst Du ihn mit
-   `browser_viewport` um und prüfst danach erneut.
-6. Benenne geprüfte Schritte und verbleibende Grenzen. Schließe den Browser nach Abschluss;
-   Aufnahmen bleiben erhalten. Run-Stopp und Serverende schließen ihn ebenfalls.
+1. Start the application with its actual services and wait until they are ready.
+2. Open its HTTP address with `browser_open`. Every run has its own browser without an
+   inherited sign-in. It runs on the machine of your workspace; you reach an application
+   started there via `localhost`. Report missing services and browser prerequisites
+   explicitly.
+3. Read the snapshot and follow the actual user path. Choose targets by visible
+   roles/names or field labels, for example `{ role: "button", name: "Save" }`.
+   Resolution happens in the browser. Snapshot IDs are not copied.
+4. Check success and relevant error cases with `browser_check`: visible result, target address
+   and browser errors. A typecheck or screenshot alone does not prove a successful user path.
+   Every action needs a new check. Do not invent results when the network is missing.
+5. Create real screenshots with `browser_screenshot`. Put `url` or `markdown`
+   programmatically into the result report or the mini-app. The image lives in the file storage
+   of this run. The native tool `browser_view_screenshot` shows you the latest screenshot
+   without a path; for that your model needs image support. The viewport defaults to
+   1920 x 1080 (16:9); for narrow layouts or small screens you change it with
+   `browser_viewport` and check again afterwards.
+6. Name the checked steps and remaining limits. Close the browser when you are done;
+   screenshots are kept. Stopping the run and shutting down the server close it as well.
 
-Die Browseraktionen verwenden Playwright-Locators mit automatischem Warten. Mehrdeutige Ziele
-sind Fehler, die die Kandidaten nennen; wähle dann mit `nth` (0-basiert) oder `first: true` im
-Ziel einen Treffer, oder prüfe die Anzahl sichtbarer Treffer mit `count` in `browser_check`.
-Sichtbarkeitsprüfungen warten höchstens 5 Sekunden, Aktionen länger; ein fehlendes Element
-kostet also keine lange Wartezeit. Native Selects verwenden `browser_select`; eigene Auswahlmenüs werden geklickt.
-Mit `target.frame` wählst Du ein Iframe per CSS. Neue Fenster werden ausdrücklich gemeldet;
-dieser Ablauf bedient eine Seite. Verdeckte Elemente werden nicht per JavaScript angeklickt.
+The browser actions use Playwright locators with automatic waiting. Ambiguous targets
+are errors that name the candidates; then pick one match with `nth` (0-based) or `first: true` in
+the target, or check the number of visible matches with `count` in `browser_check`.
+Visibility checks wait at most 5 seconds, actions longer; a missing element
+therefore costs no long wait. Native selects use `browser_select`; custom dropdown menus are clicked.
+With `target.frame` you choose an iframe by CSS. New windows are reported explicitly;
+this flow operates one page. Hidden elements are not clicked via JavaScript.

package/plugins/ragents.documents/contract.ts

@@ -25,10 +25,10 @@ export type RunFilesListing = Static<typeof filesListing>;
 export const documentsContracts = {
   files: defineOperation({
     id: "ragents.documents.files",
-    description: "Die Dateiablage eines Runs als Gruppen und lose Dateien. Recht: runs.read.",
+    description: "A run's file store as groups and loose files. Right: runs.read.",
     rights: ["runs.read"],
     input: Type.Object({
-      runId: Type.String({ minLength: 1, maxLength: 64, description: "Kennung des Runs" }),
+      runId: Type.String({ minLength: 1, maxLength: 64, description: "Run id" }),
     }, { additionalProperties: false }),
     result: filesListing,
   }),

package/plugins/ragents.documents/prompt.hbs

@@ -8,7 +8,7 @@ to put something there is the tool `document_write`.
   they are part of the actual assignment.
 - `document_write` takes the full `content` of the file. For a file of the working directory,
   `read` it first and pass the content here.
-- The user sees these files in the "Dokumente" area of the interface, grouped by subdirectory.
+- The user sees these files in the "Documents" area of the interface, grouped by subdirectory.
 - When you spawn agents, name in their assignment the store path they are supposed to write to.
 
 If the user wants to see the content of a file or a document, show it COMPLETELY via

package/plugins/ragents.documents/server/document-write-tool.ts

@@ -6,21 +6,21 @@ import { alwaysAvailable } from "@ragents/host/plugin-support/tool-availability.
 
 export const documentWriteToolMetadata = {
   name: "document_write",
-  label: "Dokument ablegen",
+  label: "Store document",
   nativeTool: true,
-  description: "Legt eine Datei mit dem übergebenen Inhalt in der Dateiablage dieses Runs ab.",
-  longDescription: "Dokumente, Berichte und Zwischenprodukte gehören in die Dateiablage, nicht ins "
-    + "Arbeitsverzeichnis - dort steht nur, was zum Auftrag selbst gehört. Der Benutzer sieht die "
-    + "Ablage im Bereich \"Dokumente\", nach Unterordnern gruppiert. Soll eine Datei aus dem "
-    + "Arbeitsbereich in die Ablage, lies sie zuerst mit read und übergib den Inhalt hier als content. "
-    + "Die Ablage ist kein Bash-Pfad: sie liegt nicht im Arbeitsbereich und ist nur über dieses Werkzeug "
-    + "beschreibbar.",
+  description: "Stores a file with the given content in this run's file store.",
+  longDescription: "Documents, reports and intermediate products belong in the file store, not in the "
+    + "working directory - that only holds what belongs to the task itself. The user sees the "
+    + "store in the \"Documents\" area, grouped by subdirectory. To put a file from the "
+    + "workspace into the store, read it first with read and pass the content here as content. "
+    + "The store is not a bash path: it does not live in the workspace and can only be written "
+    + "through this tool.",
 } as const;
 
 const relativeStorePath = (value: string): string => {
   const normalized = value.replace(/^\.\//, "");
   if (path.isAbsolute(normalized) || normalized.split("/").includes("..") || normalized.trim() === "") {
-    throw new Error("path muss relativ zur Dateiablage sein, ohne führenden / und ohne ..");
+    throw new Error("path must be relative to the file store, without a leading / and without ..");
   }
   return normalized;
 };
@@ -29,8 +29,8 @@ export const createDocumentWriteTool = (filesFor: (runId: string) => Promise<str
   defineRunFunction({
     ...documentWriteToolMetadata,
     schema: Type.Object({
-      path: Type.String({ minLength: 1, description: "Pfad in der Dateiablage, etwa thema/bericht.md" }),
-      content: Type.String({ description: "Der vollständige Inhalt der Datei" }),
+      path: Type.String({ minLength: 1, description: "Path in the file store, e.g. topic/report.md" }),
+      content: Type.String({ description: "The complete content of the file" }),
     }, { additionalProperties: false }),
     resultSchema: Type.String(),
     available: alwaysAvailable,
@@ -40,6 +40,6 @@ export const createDocumentWriteTool = (filesFor: (runId: string) => Promise<str
       const target = path.join(await filesFor(scope.caller.runId), relative);
       await mkdir(path.dirname(target), { recursive: true });
       await writeFile(target, input.content, "utf8");
-      return `In der Dateiablage abgelegt: ${relative} (${Buffer.byteLength(input.content, "utf8")} Byte)`;
+      return `Stored in the file store: ${relative} (${Buffer.byteLength(input.content, "utf8")} bytes)`;
     },
   });

package/plugins/ragents.documents/server/files-route.ts

@@ -31,7 +31,7 @@ const visibleEntries = async (directory: string) => {
   const entries = await readdir(directory, { withFileTypes: true });
   return entries
     .filter((entry) => !entry.name.startsWith(".") && !entry.isSymbolicLink())
-    .sort((left, right) => left.name.localeCompare(right.name, "de"));
+    .sort((left, right) => left.name.localeCompare(right.name, "en-US"));
 };
 
 const collectFiles = async (
@@ -77,11 +77,11 @@ const listingOf = async (root: string): Promise<RunFilesListing> => {
 const resolveInside = async (root: string, relative: string): Promise<string> => {
   if (!relative || relative.includes("\0") || relative.includes("\\") || path.isAbsolute(relative)
     || relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
-    throw new Error("Ungültiger Dateipfad");
+    throw new Error("Invalid file path");
   }
   const rootReal = await realpath(root);
   const real = await realpath(path.join(rootReal, relative));
-  if (real !== rootReal && !real.startsWith(rootReal + path.sep)) throw new Error("Ungültiger Dateipfad");
+  if (real !== rootReal && !real.startsWith(rootReal + path.sep)) throw new Error("Invalid file path");
   return real;
 };
 
@@ -104,14 +104,14 @@ export const createFilesMethod = (options: FilesRouteOptions): MethodContributio
     return listingOf(await options.filesFor(runId));
   });
 
-/** Der Inhalt bleibt Auslieferung: ein GET mit dem Medientyp der Datei. */
+/** Content stays plain delivery: a GET with the file's media type. */
 export const createFileContentRoute = (options: FilesRouteOptions): HttpRouteContribution => ({
   id: "ragents.documents.files-content",
   isApiPath: (pathname) => contentPattern.test(pathname),
   matches: (request, url) => request.method === "GET" && contentPattern.test(url.pathname),
   handle: async ({ response, request, url }) => {
     const match = url.pathname.match(contentPattern);
-    if (!match) throw new Error("Ungültige Dokumente-Route");
+    if (!match) throw new Error("Invalid documents route");
     const [, runId] = match;
     await guardedJsonRoute({
       response,
@@ -122,7 +122,7 @@ export const createFileContentRoute = (options: FilesRouteOptions): HttpRouteCon
         const relative = url.searchParams.get("path") ?? "";
         const file = await resolveInside(await options.filesFor(runId), relative);
         const info = await lstat(file);
-        if (!info.isFile()) throw new Error("Ungültiger Dateipfad");
+        if (!info.isFile()) throw new Error("Invalid file path");
         const content = await readFile(file);
         response.writeHead(200, {
           "Cache-Control": "no-store",

package/plugins/ragents.documents/server/show-document-tool.ts

@@ -5,26 +5,26 @@ import { facesOperator } from "@ragents/host/plugin-support/tool-availability.js
 
 export const showDocumentToolMetadata = {
   name: "show_document",
-  label: "Dokument anzeigen",
+  label: "Show document",
   nativeTool: true,
-  description: "Zeigt Dokumente vollständig in der Oberfläche; Dateipfade gelten nur für die Dateiablage dieses Runs.",
-  longDescription: "Nutze dieses Werkzeug IMMER, wenn der Benutzer den "
-    + "Inhalt einer Datei oder ein längeres Dokument sehen möchte - statt den Inhalt in die "
-    + "Chat-Antwort zu kopieren oder zu paraphrasieren. path zeigt ausschließlich eine Datei aus "
-    + "der Dateiablage dieses Runs an, NICHT aus deinem Arbeitsverzeichnis. "
-    + "Alles andere - Dateien des Arbeitsverzeichnisses und selbst erzeugte Inhalte - geht über "
-    + "content; stammt der Inhalt aus einer Datei, übernimm ihn dort WÖRTLICH aus dem letzten "
-    + "read- oder write-Ergebnis, niemals aus dem Gedächtnis neu getippt.",
+  description: "Shows documents completely in the interface; file paths only apply to this run's file store.",
+  longDescription: "ALWAYS use this tool when the user wants to see the "
+    + "content of a file or a longer document - instead of copying or paraphrasing the content in the "
+    + "chat answer. path only shows a file from "
+    + "this run's file store, NOT from your working directory. "
+    + "Everything else - files of the working directory and content you produced yourself - goes through "
+    + "content; if the content comes from a file, take it VERBATIM from the last "
+    + "read or write result, never retyped from memory.",
 } as const;
 
-const sourceRule = "content und path schließen einander aus: gültig sind { title, content, format } für "
-  + "selbst erzeugte Inhalte und Dateien des Arbeitsverzeichnisses und { title, path, format } für Dateien "
-  + "der Dateiablage - genau eines von beiden muss gesetzt sein.";
+const sourceRule = "content and path exclude each other: valid are { title, content, format } for "
+  + "self-produced content and files of the working directory, and { title, path, format } for files "
+  + "of the file store - exactly one of the two must be set.";
 
-const titleSchema = Type.String({ description: "Titel der Anzeige, z.B. der Dateiname" });
+const titleSchema = Type.String({ description: "Title of the display, e.g. the file name" });
 const formatSchema = Type.Optional(Type.Union(
   [Type.Literal("markdown"), Type.Literal("text"), Type.Literal("html")],
-  { description: "Darstellung, Default markdown" }));
+  { description: "Rendering, default markdown" }));
 
 const documentSource = (input: { content?: string; path?: string }):
   | { kind: "content" }
@@ -40,14 +40,14 @@ export const createShowDocumentTool = (filesFor: (runId: string) => Promise<stri
     schema: Type.Object({
       title: titleSchema,
       content: Type.Optional(Type.String({
-        description: "Der vollständige Inhalt - für Dateien aus dem Arbeitsverzeichnis und für "
-          + "selbst erzeugte Inhalte, also alles, was nicht in der Dateiablage liegt. " + sourceRule,
+        description: "The complete content - for files from the working directory and for "
+          + "self-produced content, i.e. everything that is not in the file store. " + sourceRule,
       })),
       path: Type.Optional(Type.String({
-        description: "Datei aus der Dateiablage dieses Runs, relativ zur Ablage (z.B. thema/datei.md). "
-          + "Nur dort abgelegte Dateien sind so anzeigbar - für Pfade des Arbeitsverzeichnisses "
-          + "content nutzen. Der Inhalt wird direkt aus der Datei angezeigt und muss nie "
-          + "abgetippt werden. " + sourceRule,
+        description: "File from this run's file store, relative to the store (e.g. topic/file.md). "
+          + "Only files stored there can be shown this way - for paths of the working directory "
+          + "use content. The content is shown directly from the file and never has to be "
+          + "retyped. " + sourceRule,
       })),
       format: formatSchema,
     }, { additionalProperties: false }),
@@ -57,17 +57,17 @@ export const createShowDocumentTool = (filesFor: (runId: string) => Promise<stri
       const source = documentSource(input);
 
       if (source.kind === "content")
-        return `Dem Benutzer angezeigt: ${input.title}`;
+        return `Shown to the user: ${input.title}`;
 
       const path = source.path;
       if (path.startsWith("/") || path.split("/").includes(".."))
-        throw new Error("path muss relativ zur Dateiablage sein, ohne führenden / und ohne ..");
+        throw new Error("path must be relative to the file store, without a leading / and without ..");
       if (!await runFileExists(await filesFor(caller.runId), path))
         throw new Error(
-          `${source.path} liegt nicht in der Dateiablage dieses Runs. Über path sind nur Dateien der `
-          + "Dateiablage anzeigbar - für Dateien aus dem Arbeitsverzeichnis und für selbst erzeugte "
-          + "Inhalte den Inhalt über content übergeben.",
+          `${source.path} is not in this run's file store. Only files of the `
+          + "file store can be shown via path - for files from the working directory and for self-produced "
+          + "content, pass the content via content.",
         );
-      return `Dem Benutzer angezeigt: ${input.title} (Datei ${path} aus der Dateiablage)`;
+      return `Shown to the user: ${input.title} (file ${path} from the file store)`;
     },
   });

package/plugins/ragents.documents/server/store.ts

@@ -17,7 +17,7 @@ export class RunDocumentStore implements DocumentStore {
   }
 
   async directoryFor(runId: string): Promise<string> {
-    if (!isRunId(runId)) throw new Error(`Ungültige Run-ID: ${runId}`);
+    if (!isRunId(runId)) throw new Error(`Invalid run id: ${runId}`);
     const directory = this.#options.externalRoot
       ? path.join(this.#options.externalRoot, runId)
       : this.#options.sessionDirectory(runId);