@schlenkr/ragents 0.1.9 → 0.1.11

package/plugins/ragents.workspace/client/workspace-client.ts

@@ -33,17 +33,18 @@ import {
   type WorkspaceClientDescription,
 } from "../contract";
 
+/** mismatch: workstation and server carry a different version of executor or bundles; only an update of one side fixes it. */
 export type WorkspaceClientStatus =
   | { kind: "idle" }
   | { kind: "registered" }
-  | { kind: "failed"; message: string };
+  | { kind: "failed"; message: string; mismatch: boolean };
 
-/** Was der Arbeitsplatz über sich sagt; ob seine Bash rg findet, ermittelt er selbst bei jeder Anmeldung. */
+/** What the workstation says about itself; whether its bash finds rg, it determines itself at every sign-in. */
 export interface WorkspaceClientIdentity extends Omit<WorkspaceClientDescription, "ripgrep"> {
   id: string;
 }
 
-/** Ein abgeschlossener Werkzeugaufruf des Modells; der Aufrufer entscheidet, wohin die Zeile geht. */
+/** A completed tool call of the model; the caller decides where the line goes. */
 export interface WorkspaceClientExecution {
   runId: string;
   operation: string;
@@ -52,31 +53,43 @@ export interface WorkspaceClientExecution {
 }
 
 export interface WorkspaceClientOptions {
-  /** Die Host-Wurzel dieses Rechners mit den Bundles, aus denen der Executor seine Beiträge lädt; sie kann erst später entstehen. */
+  /** The host root of this machine with the bundles from which the executor loads its contributions; it may only come into existence later. */
   hostRoot: () => string | undefined;
-  /** Die Bash dieses Rechners für das Werkzeug bash; unter Windows die mitgebrachte und Pflicht, sonst ohne Angabe die des Systems. */
+  /** The bash of this machine for the bash tool; on Windows the bundled one and required, otherwise without a value the system's. */
   bash?: string | undefined;
-  /** Das mitgebrachte rg, dessen Ordner die Bash vorn im PATH hat; ohne Angabe gilt eines im PATH dieses Rechners. */
+  /** The bundled rg, whose folder the bash has at the front of its PATH; without a value, one in the PATH of this machine applies. */
   rg?: string | undefined;
   onExecuted?: (execution: WorkspaceClientExecution) => void;
 }
 
-/** Was der Arbeitsplatz zum Server braucht: die Nachrichtenschicht. */
+/** What the workstation needs for the server: the message layer. */
 export interface WorkspaceClientTransport {
   readonly rpc: RpcClient;
 }
 
 type ExecuteInput = OperationInput<typeof workspaceClientContracts.execute>;
 
-/** So lange wartet eine Anmeldung auf die Antwort des Servers. */
+/** This is how long a sign-in waits for the server's answer. */
 const REGISTER_TIMEOUT_MS = 10_000;
 
-/** So lange wartet eine Abmeldung auf den Server; der Executor endet unabhängig davon. */
+/** This is how long a sign-out waits for the server; the executor ends independently of it. */
 const SIGN_OFF_TIMEOUT_MS = 3_000;
 
 const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
 
-/** Der echte Pfad des nächsten vorhandenen Elternordners, um die noch fehlenden Namen ergänzt. */
+/** A version of this workstation that does not match the server's. */
+class VersionMismatch extends Error {}
+
+const VERSION_REFUSALS = ["workspace-executor-version", "workspace-executor-contributions"];
+
+/** By the domain code instead of the class: RpcError can be loaded twice in one process. */
+const isVersionMismatch = (cause: unknown): boolean => {
+  if (cause instanceof VersionMismatch) return true;
+  const code = typeof cause === "object" && cause !== null ? (cause as { domainCode?: unknown }).domainCode : undefined;
+  return typeof code === "string" && VERSION_REFUSALS.includes(code);
+};
+
+/** The real path of the nearest existing parent folder, extended by the names still missing. */
 const realPathOf = async (target: string): Promise<string> => {
   try {
     return await realpath(target);
@@ -86,14 +99,14 @@ const realPathOf = async (target: string): Promise<string> => {
   }
 };
 
-/** Wo ein Arbeitsplatz ohne eigene Angabe die neuen Ordner je Run anlegt: im Datenordner des Arbeitsplatzes, nie in einem angebotenen Projekt. */
+/** Where a workstation without its own value creates the new folders per run: in the workstation's data folder, never in an offered project. */
 export const workstationRunsDirectory = (): string => join(workspaceDataDirectory(), "runs");
 
 const RUN_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 
-/** Der neue Ordner eines Runs auf diesem Rechner; eine Kennung mit Pfadzeichen käme aus dem Ordner für Runs heraus. */
+/** The new folder of a run on this machine; an ID with path characters would escape the folder for runs. */
 const runFolderOf = (runsDirectory: string, runId: string): string => {
-  if (!RUN_ID_PATTERN.test(runId)) throw new Error(`Die Run-Kennung ${runId} taugt nicht als Ordnername`);
+  if (!RUN_ID_PATTERN.test(runId)) throw new Error(`The run ID ${runId} is not usable as a folder name`);
   return join(runsDirectory, runId);
 };
 
@@ -102,59 +115,59 @@ const sameFolders = (left: readonly string[], right: readonly string[]): boolean
 
 const contextOf = (runs: ReadonlyMap<string, WorkspaceProcessContext>, runId: string): Promise<WorkspaceProcessContext> => {
   const context = runs.get(runId);
-  if (!context) throw new Error(`Für den Run ${runId} liegt auf diesem Arbeitsplatz kein Auftrag vor`);
+  if (!context) throw new Error(`There is no task for run ${runId} on this workstation`);
   return Promise.resolve(context);
 };
 
 const sameContributions = (left: readonly ExecutorContributionStand[], right: readonly ExecutorContributionStand[]): boolean =>
   left.length === right.length && left.every((entry) => right.some((other) => other.plugin === entry.plugin && other.stand === entry.stand));
 
-/** Die Bundles eines Arbeitsplatzes sind die eingebauten seines Hosts; ein Plugin, das dort fehlt, kann er nicht ausführen. */
+/** The bundles of a workstation are the built-in ones of its host; it cannot run a plugin that is missing there. */
 const contributionFileOf = (hostRoot: string, plugin: string): string => join(hostRoot, "bundles", plugin, EXECUTOR_CONTRIBUTION_FILE);
 
-/** Lädt die Beiträge, die der Server verlangt, aus den Bundles des Hosts dieser Maschine; ein fehlendes Bundle oder ein anderer Stand ist ein Fehler mit Ursache. */
+/** Loads the contributions the server requires from the bundles of this machine's host; a missing bundle or a different version is an error with a cause. */
 const loadedContributions = async (
   hostRoot: string | undefined,
   wanted: readonly ExecutorContributionStand[],
 ): Promise<readonly PreparedExecutorContribution[]> => {
   if (wanted.length === 0) return [];
   if (!hostRoot) {
-    throw new Error(`Der Server verlangt die Executor-Beiträge von ${wanted.map(({ plugin }) => plugin).join(", ")}; dieser Arbeitsplatz `
-      + "kennt keinen Host, aus dessen Bundles er sie laden könnte. Er bekommt ihn mit der ersten Verbindung zu einem verteilenden "
-      + "Server oder über die Einstellung ragents.hostPath");
+    throw new Error(`The server requires the executor contributions of ${wanted.map(({ plugin }) => plugin).join(", ")}; this workstation `
+      + "knows no host from whose bundles it could load them. It gets one with the first connection to a distributing "
+      + "server or through the setting ragents.hostPath");
   }
   return Promise.all(wanted.map(async ({ plugin, stand }) => {
-    if (!PLUGIN_ID_PATTERN.test(plugin)) throw new Error(`Der Server nennt ${plugin} als Plugin; das ist keine Kennung eines Plugins`);
+    if (!PLUGIN_ID_PATTERN.test(plugin)) throw new Error(`The server names ${plugin} as a plugin; that is not a plugin ID`);
     const loaded = await loadExecutorContribution(plugin, contributionFileOf(hostRoot, plugin), stand).catch((cause: unknown) => {
-      throw new Error(`${messageOf(cause)}. Der Host dieses Arbeitsplatzes (${hostRoot}) muss dieselben Bundles tragen wie der Server: `
-        + "die RAgents-Erweiterung beziehungsweise das Paket @schlenkr/ragents in der Fassung des Servers, im Checkout pnpm build:plugins");
+      throw new VersionMismatch(`${messageOf(cause)}. The host of this workstation (${hostRoot}) must carry the same bundles as the server: `
+        + "the RAgents extension or the package @schlenkr/ragents in the server's version, in a checkout pnpm build:plugins");
     });
     return prepareExecutorContribution(loaded, pluginToolsDirectory(hostDataDirectory(), plugin));
   }));
 };
 
-/** Ein Executor aus den Beiträgen, die der Server bei der Anmeldung verlangt hat. */
+/** An executor from the contributions the server required at sign-in. */
 interface BuiltExecutor {
   readonly executor: WorkspaceOperationExecutor;
   readonly contributions: readonly ExecutorContributionStand[];
 }
 
-/** Was eine Anmeldung auf diesem Rechner hält: ihren eigenen Executor, die Aufträge ihrer Runs und ihre Handler an der Nachrichtenschicht. */
+/** What a sign-in on this machine holds: its own executor, the tasks of its runs, and its handlers on the message layer. */
 interface Attachment {
-  /** Entsteht mit der Antwort des Servers, welche Beiträge er verlangt; verlangt er nach einer Neuverbindung andere, ersetzt ein neuer ihn. */
+  /** Comes into existence with the server's answer about which contributions it requires; if it requires others after a reconnect, a new one replaces it. */
   built: BuiltExecutor | undefined;
   readonly runsDirectory: string;
   readonly runs: Map<string, WorkspaceProcessContext>;
   readonly release: () => void;
 }
 
-/** Der Arbeitsplatz: meldet seine Ordner an und führt die Aufträge des Servers mit dem Executor dieser Maschine aus. */
+/** The workstation: signs in its folders and runs the server's tasks with the executor of this machine. */
 export class WorkspaceClient {
   #identity: WorkspaceClientIdentity;
   #status: WorkspaceClientStatus = { kind: "idle" };
   #attachment: Attachment | undefined;
   #announcing: Promise<void> | undefined;
-  /** Die Abmeldungen beim Server, der Reihe nach; eine spätere Anmeldung wartet auf sie, damit keine sie überholt. */
+  /** The sign-outs at the server, in order; a later sign-in waits for them so that none overtakes them. */
   #signingOff: Promise<void> = Promise.resolve();
   readonly #listeners = new Set<() => void>();
 
@@ -187,7 +200,7 @@ export class WorkspaceClient {
     return () => { this.#listeners.delete(listener); };
   }
 
-  /** Erst die Operation anbieten - das öffnet den Strom -, dann anmelden, sobald er steht; eine Abmeldung, die inzwischen kam, gilt. */
+  /** First offer the operation - that opens the stream -, then sign in as soon as it is established; a sign-out that came in the meantime applies. */
   async register(): Promise<void> {
     const signingOff = this.#signingOff;
     await signingOff;
@@ -196,13 +209,13 @@ export class WorkspaceClient {
     try {
       await this.#connected();
     } catch (cause) {
-      if (attachment === this.#attachment) this.#set({ kind: "failed", message: messageOf(cause) });
+      if (attachment === this.#attachment) this.#set({ kind: "failed", message: messageOf(cause), mismatch: false });
       return;
     }
     if (attachment === this.#attachment) await this.#announce();
   }
 
-  /** Geänderte Ordner werden erneut angemeldet; ohne Ordner meldet sich der Arbeitsplatz ab. */
+  /** Changed folders are signed in again; without folders the workstation signs out. */
   async update(folders: readonly string[]): Promise<void> {
     if (sameFolders(this.#identity.folders, folders)) return;
     this.#identity = { ...this.#identity, folders: [...folders] };
@@ -211,7 +224,7 @@ export class WorkspaceClient {
     else await this.register();
   }
 
-  /** Die Abmeldung erreicht den Server nach einer laufenden Anmeldung und vor jeder späteren; der Executor endet sofort, auch wenn der Server nicht antwortet. */
+  /** The sign-out reaches the server after a running sign-in and before any later one; the executor ends immediately, even if the server does not respond. */
   async unregister(): Promise<void> {
     const attachment = this.#attachment;
     this.#attachment = undefined;
@@ -223,12 +236,12 @@ export class WorkspaceClient {
     await Promise.all([signingOff, attachment?.built?.executor.shutdown()]);
   }
 
-  /** Der Arbeitsplatz bindet immer sich selbst; wo der Server läuft, ändert daran nichts. */
+  /** The workstation always binds itself; where the server runs does not change that. */
   binding(folder: string): WorkspaceBinding {
     return { machine: { client: this.id, label: this.label }, folder: { path: folder } };
   }
 
-  /** Jede Anmeldung baut ihren eigenen Executor; einer, den eine Abmeldung beendet hat, wird nie wieder benutzt. */
+  /** Every sign-in builds its own executor; one that a sign-out has ended is never used again. */
   #attach(): Attachment {
     if (this.#attachment) return this.#attachment;
     const rpc = this.transport.rpc;
@@ -247,7 +260,7 @@ export class WorkspaceClient {
     return attachment;
   }
 
-  /** Behält den Executor, solange der Server dieselben Beiträge verlangt; sonst baut es einen neuen aus den Bundles dieses Rechners und beendet den alten. */
+  /** Keeps the executor as long as the server requires the same contributions; otherwise it builds a new one from the bundles of this machine and ends the old one. */
   async #built(attachment: Attachment, wanted: readonly ExecutorContributionStand[]): Promise<BuiltExecutor> {
     const current = attachment.built;
     if (current && sameContributions(current.contributions, wanted)) return current;
@@ -264,14 +277,14 @@ export class WorkspaceClient {
     };
     if (attachment !== this.#attachment) {
       await built.executor.shutdown();
-      throw new Error("Der Arbeitsplatz hat sich inzwischen abgemeldet");
+      throw new Error("The workstation has signed out in the meantime");
     }
     attachment.built = built;
     await current?.executor.shutdown();
     return built;
   }
 
-  /** Wartet auf den Ereignisstrom; ohne ihn nimmt der Server die Anmeldung nicht an. */
+  /** Waits for the event stream; without it the server does not accept the sign-in. */
   #connected(): Promise<void> {
     const rpc = this.transport.rpc;
     if (rpc.status.kind === "connected") return Promise.resolve();
@@ -281,8 +294,8 @@ export class WorkspaceClient {
         release();
         if (status.kind === "connected") settle();
         else if (status.kind === "retrying") fail(new Error(status.message));
-        else if (status.kind === "unauthorized") fail(new Error("Der Server verlangt eine Anmeldung."));
-        else fail(new Error("Der Ereignisstrom des Servers ist geschlossen."));
+        else if (status.kind === "unauthorized") fail(new Error("The server requires a sign-in."));
+        else fail(new Error("The server's event stream is closed."));
       });
     });
   }
@@ -292,7 +305,7 @@ export class WorkspaceClient {
     return this.#announcing;
   }
 
-  /** Erst die Beiträge, die der Server verlangt, dann die Anmeldung mit dem Executor daraus; eine Antwort nach einer Abmeldung ändert den Zustand nicht mehr. */
+  /** First the contributions the server requires, then the sign-in with the executor built from them; an answer after a sign-out no longer changes the state. */
   async #send(): Promise<void> {
     const attachment = this.#attachment;
     if (!attachment) return;
@@ -302,8 +315,8 @@ export class WorkspaceClient {
         executor: WORKSPACE_EXECUTOR_VERSION,
       }, { timeoutMs: REGISTER_TIMEOUT_MS }).catch((cause: unknown) => {
         if (!(cause instanceof RpcError) || cause.code !== RPC_ERROR_CODES.methodNotFound) throw cause;
-        throw new Error(`Der Server kennt ${workspaceContracts.clients.contributions.id} nicht; er ist älter als dieser Arbeitsplatz `
-          + `mit dem Executor ${WORKSPACE_EXECUTOR_VERSION}. Den Server auf die Fassung des Arbeitsplatzes aktualisieren.`);
+        throw new VersionMismatch(`The server does not know ${workspaceContracts.clients.contributions.id}; it is older than this workstation `
+          + `with executor ${WORKSPACE_EXECUTOR_VERSION}. Update the server to the workstation's version.`);
       });
       const { contributions } = await this.#built(attachment, wanted);
       await this.transport.rpc.call(workspaceContracts.clients.register, {
@@ -319,7 +332,7 @@ export class WorkspaceClient {
       }, { timeoutMs: REGISTER_TIMEOUT_MS });
       if (attachment === this.#attachment) this.#set({ kind: "registered" });
     } catch (cause) {
-      if (attachment === this.#attachment) this.#set({ kind: "failed", message: messageOf(cause) });
+      if (attachment === this.#attachment) this.#set({ kind: "failed", message: messageOf(cause), mismatch: isVersionMismatch(cause) });
     }
   }
 
@@ -327,18 +340,18 @@ export class WorkspaceClient {
     try {
       await this.transport.rpc.call(workspaceContracts.clients.unregister, { id: this.id }, { timeoutMs: SIGN_OFF_TIMEOUT_MS });
     } catch (cause) {
-      this.#set({ kind: "failed", message: messageOf(cause) });
+      this.#set({ kind: "failed", message: messageOf(cause), mismatch: false });
     }
   }
 
-  /** Der Entwickler arbeitet auf seinem Arbeitsplatz mit seinen eigenen Zugangsdaten und seiner ganzen Umgebung; HOME bleibt sein Home. */
+  /** The developer works on their workstation with their own credentials and their whole environment; HOME stays their home. */
   async #execute(attachment: Attachment, input: ExecuteInput, context: RpcHandlerContext): Promise<{ value: unknown }> {
     if (input.operation === WORKSPACE_CLIENT_STOP_OPERATION) return this.#stop(attachment, input.runId);
     const cwd = await this.#inside(input.cwd, input.runId);
     const root = await realPathOf(cwd);
-    if (attachment !== this.#attachment) throw new Error("Der Arbeitsplatz hat sich inzwischen abgemeldet");
+    if (attachment !== this.#attachment) throw new Error("The workstation has signed out in the meantime");
     const executor = attachment.built?.executor;
-    if (!executor) throw new Error("Der Arbeitsplatz ist beim Server noch nicht angemeldet");
+    if (!executor) throw new Error("The workstation is not signed in at the server yet");
     attachment.runs.set(input.runId, workspaceProcessContext({
       runId: input.runId,
       cwd,
@@ -375,7 +388,7 @@ export class WorkspaceClient {
     }
   }
 
-  /** Der Stopp braucht keinen Ordner: er gibt frei, was der Run hält, auch wenn sein Ordner nicht mehr angeboten wird. */
+  /** The stop needs no folder: it releases what the run holds, even if its folder is no longer offered. */
   async #stop(attachment: Attachment, runId: string): Promise<{ value: null }> {
     try {
       await attachment.built?.executor.stopRun(runId);
@@ -385,14 +398,14 @@ export class WorkspaceClient {
     return { value: null };
   }
 
-  /** Jeder Auftrag muss in einem der angebotenen Ordner liegen oder im neuen Ordner seines Runs; fehlende Pfade zählen über ihren vorhandenen Elternordner. */
+  /** Every task must be in one of the offered folders or in the new folder of its run; missing paths count through their existing parent folder. */
   async #inside(candidate: string, runId: string): Promise<string> {
     const target = resolve(candidate);
     const real = await realPathOf(target);
     const allowed = [...this.#identity.folders, runFolderOf(this.#identity.runsDirectory, runId)];
     const roots = await Promise.all(allowed.map((folder) => realPathOf(resolve(folder))));
     if (!roots.some((root) => containsWorkspacePath(root, real))) {
-      throw new Error(`Pfad außerhalb des angebotenen Ordners: ${candidate}`);
+      throw new Error(`Path outside the offered folder: ${candidate}`);
     }
     return target;
   }