@schlenkr/ragents 0.1.5 → 0.1.6

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

@@ -1,18 +1,22 @@
 import { realpath } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { basename, dirname, join, resolve, sep } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import {
-  SandboxWorkspaceExecutor,
   WORKSPACE_EXECUTOR_VERSION,
-  WORKSPACE_STOP_OPERATION,
-  workspaceLanguageServers,
+  containsWorkspacePath,
+  WorkspaceOperationError,
+  WorkspaceOperationExecutor,
+  workspaceDataDirectory,
+  workspaceExecutorModules,
   workspaceProcessContext,
   type WorkspaceProcessContext,
-} from "@aicontainer/workspace-executor";
+} from "@ragents/workspace-executor";
 import type { RpcClient } from "../../../apps/web/src/rpc/client";
 import type { OperationInput } from "../../../packages/ragents/src/rpc/contract";
 import type { RpcHandlerContext } from "../../../packages/ragents/src/rpc/peer";
+import { DomainError } from "../../../packages/ragents/src/runtime/domain-error";
 import {
+  WORKSPACE_CLIENT_STOP_OPERATION,
   workspaceClientContracts,
   workspaceContracts,
   type WorkspaceBinding,
@@ -28,10 +32,10 @@ export interface WorkspaceClientIdentity extends WorkspaceClientDescription {
   id: string;
 }
 
-/** Ein abgeschlossener Auftrag des Servers; der Aufrufer entscheidet, wohin die Zeile geht. */
+/** Ein abgeschlossener Werkzeugaufruf des Modells; der Aufrufer entscheidet, wohin die Zeile geht. */
 export interface WorkspaceClientExecution {
   runId: string;
-  tool: string;
+  operation: string;
   durationMs: number;
   error: string | undefined;
 }
@@ -39,6 +43,8 @@ export interface WorkspaceClientExecution {
 export interface WorkspaceClientOptions {
   /** Die Host-Wurzel dieses Rechners, aus der die Sprachserver aufgelöst werden; sie kann erst später entstehen. */
   hostRoot: () => string | undefined;
+  /** Die Bash dieses Rechners für das Werkzeug bash; unter Windows die mitgebrachte und Pflicht, sonst ohne Angabe die des Systems. */
+  bash?: string | undefined;
   onExecuted?: (execution: WorkspaceClientExecution) => void;
 }
 
@@ -49,6 +55,12 @@ export interface WorkspaceClientTransport {
 
 type ExecuteInput = OperationInput<typeof workspaceClientContracts.execute>;
 
+/** So lange wartet eine Anmeldung auf die Antwort des Servers. */
+const REGISTER_TIMEOUT_MS = 10_000;
+
+/** So lange wartet eine Abmeldung auf den Server; der Executor endet unabhängig davon. */
+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. */
@@ -61,18 +73,42 @@ 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. */
+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. */
+const runFolderOf = (runsDirectory: string, runId: string): string => {
+  if (!RUN_ID_PATTERN.test(runId)) throw new Error(`Die Run-Kennung ${runId} taugt nicht als Ordnername`);
+  return join(runsDirectory, runId);
+};
+
 const sameFolders = (left: readonly string[], right: readonly string[]): boolean =>
   left.length === right.length && left.every((folder, index) => folder === right[index]);
 
+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`);
+  return Promise.resolve(context);
+};
+
+/** Was eine Anmeldung auf diesem Rechner hält: ihren eigenen Executor, die Aufträge ihrer Runs und ihre Handler an der Nachrichtenschicht. */
+interface Attachment {
+  readonly executor: WorkspaceOperationExecutor;
+  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. */
 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. */
+  #signingOff: Promise<void> = Promise.resolve();
   readonly #listeners = new Set<() => void>();
-  readonly #attached: Array<() => void> = [];
-  readonly #runs = new Map<string, WorkspaceProcessContext>();
-  readonly #executor: SandboxWorkspaceExecutor;
 
   constructor(
     private readonly transport: WorkspaceClientTransport,
@@ -80,10 +116,6 @@ export class WorkspaceClient {
     private readonly options: WorkspaceClientOptions,
   ) {
     this.#identity = { ...identity, folders: [...identity.folders] };
-    this.#executor = new SandboxWorkspaceExecutor({
-      contextFor: (runId) => this.#contextFor(runId),
-      languageServers: workspaceLanguageServers,
-    });
   }
 
   get id(): string {
@@ -107,16 +139,19 @@ export class WorkspaceClient {
     return () => { this.#listeners.delete(listener); };
   }
 
-  /** Erst die Operation anbieten - das öffnet den Strom -, dann anmelden, sobald er steht; der Strom ist der Rückweg des Servers. */
+  /** Erst die Operation anbieten - das öffnet den Strom -, dann anmelden, sobald er steht; eine Abmeldung, die inzwischen kam, gilt. */
   async register(): Promise<void> {
-    this.#attach();
+    const signingOff = this.#signingOff;
+    await signingOff;
+    if (signingOff !== this.#signingOff) return;
+    const attachment = this.#attach();
     try {
       await this.#connected();
     } catch (cause) {
-      this.#set({ kind: "failed", message: messageOf(cause) });
+      if (attachment === this.#attachment) this.#set({ kind: "failed", message: messageOf(cause) });
       return;
     }
-    await this.#announce();
+    if (attachment === this.#attachment) await this.#announce();
   }
 
   /** Geänderte Ordner werden erneut angemeldet; ohne Ordner meldet sich der Arbeitsplatz ab. */
@@ -128,30 +163,39 @@ 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. */
   async unregister(): Promise<void> {
-    for (const release of this.#attached.splice(0)) release();
+    const attachment = this.#attachment;
+    this.#attachment = undefined;
+    attachment?.release();
+    attachment?.runs.clear();
     this.#set({ kind: "idle" });
-    this.#runs.clear();
-    await this.#executor.shutdown();
-    try {
-      await this.transport.rpc.call(workspaceContracts.clients.unregister, { id: this.id });
-    } catch (cause) {
-      this.#set({ kind: "failed", message: messageOf(cause) });
-    }
+    const signingOff = Promise.allSettled([this.#signingOff, this.#announcing]).then(() => this.#signOff());
+    this.#signingOff = signingOff;
+    await Promise.all([signingOff, attachment?.executor.shutdown()]);
   }
 
   /** Der Arbeitsplatz bindet immer sich selbst; wo der Server läuft, ändert daran nichts. */
   binding(folder: string): WorkspaceBinding {
-    return { kind: "client", client: this.id, label: this.label, path: folder };
+    return { machine: { client: this.id, label: this.label }, folder: { path: folder } };
   }
 
-  #attach(): void {
-    if (this.#attached.length > 0) return;
+  /** Jede Anmeldung baut ihren eigenen Executor; einer, den eine Abmeldung beendet hat, wird nie wieder benutzt. */
+  #attach(): Attachment {
+    if (this.#attachment) return this.#attachment;
+    const runs = new Map<string, WorkspaceProcessContext>();
+    const runsDirectory = this.#identity.runsDirectory;
+    const executor = new WorkspaceOperationExecutor({
+      contextFor: (runId) => contextOf(runs, runId),
+      modules: workspaceExecutorModules({ runFolder: (runId) => runFolderOf(runsDirectory, runId) }),
+    });
     const rpc = this.transport.rpc;
-    this.#attached.push(
-      rpc.handle(workspaceClientContracts.execute, (input, context) => this.#execute(input, context)),
+    const releases = [
+      rpc.handle(workspaceClientContracts.execute, (input, context) => this.#execute(executor, runs, input, context)),
       rpc.onConnected(() => void this.#announce()),
-    );
+    ];
+    this.#attachment = { executor, runs, release: () => { for (const release of releases) release(); } };
+    return this.#attachment;
   }
 
   /** Wartet auf den Ereignisstrom; ohne ihn nimmt der Server die Anmeldung nicht an. */
@@ -175,7 +219,9 @@ export class WorkspaceClient {
     return this.#announcing;
   }
 
+  /** Eine Antwort, die erst nach einer Abmeldung ankommt, ändert den Zustand nicht mehr. */
   async #send(): Promise<void> {
+    const attachment = this.#attachment;
     try {
       await this.transport.rpc.call(workspaceContracts.clients.register, {
         id: this.#identity.id,
@@ -183,61 +229,86 @@ export class WorkspaceClient {
         hostname: this.#identity.hostname,
         platform: this.#identity.platform,
         folders: [...this.#identity.folders],
+        runsDirectory: this.#identity.runsDirectory,
         executor: WORKSPACE_EXECUTOR_VERSION,
-      });
-      this.#set({ kind: "registered" });
+      }, { 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) });
+    }
+  }
+
+  async #signOff(): Promise<void> {
+    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) });
     }
   }
 
-  /** Der Entwickler arbeitet auf seinem Arbeitsplatz mit seinen eigenen Zugangsdaten; HOME bleibt sein Home. */
-  async #execute(input: ExecuteInput, context: RpcHandlerContext): Promise<{ value: unknown }> {
-    const cwd = await this.#inside(input.cwd);
-    this.#runs.set(input.runId, workspaceProcessContext({
+  /** Der Entwickler arbeitet auf seinem Arbeitsplatz mit seinen eigenen Zugangsdaten und seiner ganzen Umgebung; HOME bleibt sein Home. */
+  async #execute(
+    executor: WorkspaceOperationExecutor,
+    runs: Map<string, WorkspaceProcessContext>,
+    input: ExecuteInput,
+    context: RpcHandlerContext,
+  ): Promise<{ value: unknown }> {
+    if (input.operation === WORKSPACE_CLIENT_STOP_OPERATION) return this.#stop(executor, runs, input.runId);
+    const cwd = await this.#inside(input.cwd, input.runId);
+    const root = await realPathOf(cwd);
+    if (executor !== this.#attachment?.executor) throw new Error("Der Arbeitsplatz hat sich inzwischen abgemeldet");
+    runs.set(input.runId, workspaceProcessContext({
       runId: input.runId,
       cwd,
-      root: await realPathOf(cwd),
+      root,
       home: { home: homedir() },
       logDirectory: join(tmpdir(), "ragents-workspace-logs", input.runId),
       hostRoot: this.options.hostRoot(),
       additions: input.env,
+      baseEnvironment: "inherited",
+      ...(this.options.bash === undefined ? {} : { bash: this.options.bash }),
     }));
     const startedAt = Date.now();
     let failure: string | undefined;
     try {
-      const value = await this.#executor.execute(input.runId, input.tool, input.input, {
-        toolCallId: input.toolCallId,
+      const value = await executor.execute(input.runId, input.operation, input.input, {
+        ...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
         signal: context.signal,
-        onProgress: (text) => context.progress({ text }),
+        onProgress: context.progress,
       });
       return { value };
     } catch (cause) {
       failure = messageOf(cause);
-      throw cause;
+      throw cause instanceof WorkspaceOperationError ? new DomainError(cause.code, cause.message, cause.status) : cause;
     } finally {
-      if (input.tool === WORKSPACE_STOP_OPERATION) this.#runs.delete(input.runId);
-      this.options.onExecuted?.({
-        runId: input.runId,
-        tool: input.tool,
-        durationMs: Date.now() - startedAt,
-        error: failure,
-      });
+      if (input.toolCallId) {
+        this.options.onExecuted?.({
+          runId: input.runId,
+          operation: input.operation,
+          durationMs: Date.now() - startedAt,
+          error: failure,
+        });
+      }
     }
   }
 
-  #contextFor(runId: string): Promise<WorkspaceProcessContext> {
-    const context = this.#runs.get(runId);
-    if (!context) throw new Error(`Für den Run ${runId} liegt auf diesem Arbeitsplatz kein Auftrag vor`);
-    return Promise.resolve(context);
+  /** Der Stopp braucht keinen Ordner: er gibt frei, was der Run hält, auch wenn sein Ordner nicht mehr angeboten wird. */
+  async #stop(executor: WorkspaceOperationExecutor, runs: Map<string, WorkspaceProcessContext>, runId: string): Promise<{ value: null }> {
+    try {
+      await executor.stopRun(runId);
+    } finally {
+      runs.delete(runId);
+    }
+    return { value: null };
   }
 
-  /** Jeder Auftrag muss in einem der angebotenen Ordner liegen; fehlende Pfade zählen über ihren vorhandenen Elternordner. */
-  async #inside(candidate: string): Promise<string> {
+  /** Jeder Auftrag muss in einem der angebotenen Ordner liegen oder im neuen Ordner seines Runs; fehlende Pfade zählen über ihren vorhandenen Elternordner. */
+  async #inside(candidate: string, runId: string): Promise<string> {
     const target = resolve(candidate);
     const real = await realPathOf(target);
-    const roots = await Promise.all(this.#identity.folders.map((folder) => realPathOf(resolve(folder))));
-    if (!roots.some((root) => real === root || real.startsWith(`${root}${sep}`))) {
+    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}`);
     }
     return target;

package/plugins/ragents.workspace/contract.ts

@@ -1,15 +1,12 @@
 import { Type } from "typebox";
-import { openJson } from "@aicontainer/ragents/src/http/contracts";
-import { defineChannel, defineOperation } from "@aicontainer/ragents/src/rpc/contract";
+import { openJson } from "@ragents/engine/src/http/contracts";
+import { defineChannel, defineOperation } from "@ragents/engine/src/rpc/contract";
 
 export const WORKSPACE_PLUGIN_ID = "ragents.workspace";
 
 export const BROWSE_ROOTS = ["workspace", "files"] as const;
 export type BrowseRoot = typeof BROWSE_ROOTS[number];
 
-export const BROWSE_ENTRY_LIMIT = 500;
-export const BROWSE_PREVIEW_LIMIT = 256 * 1024;
-
 export interface BrowseEntry {
   name: string;
   kind: "directory" | "file";
@@ -19,6 +16,7 @@ export interface BrowseEntry {
 
 export interface BrowseListing {
   root: BrowseRoot;
+  /** Wo die Wurzel liegt; bei einem Arbeitsplatz mit dessen Label. */
   location: string;
   path: string;
   entries: BrowseEntry[];
@@ -33,13 +31,30 @@ export const WORKSPACE_BINDING_OPTION_ID = "ragents.workspace.binding";
 
 export const WORKSPACE_METADATA_ID = "ragents.workspace";
 
-/** Wo der Arbeitsbereich eines Runs liegt; wird beim Start als Startoption ins Journal eingefroren. */
-export type WorkspaceBinding =
-  | { kind: "fresh" }
-  | { kind: "path"; path: string }
-  | { kind: "client"; client: string; label: string; path: string };
+/** Auf welchem Rechner der Arbeitsbereich eines Runs liegt: dem Server oder einem Arbeitsplatz, dessen Label die Bindung festhält. */
+export type WorkspaceMachine = "server" | { client: string; label: string };
+
+/** Ein vorhandener Ordner, den der Run weder anlegt noch löscht. */
+export type ExistingWorkspaceFolder = {
+  path: string;
+};
+
+/** Der neue Ordner je Run auf einem Arbeitsplatz; seinen Pfad dort hält die Bindung ab dem Wählen fest. */
+export type FreshWorkstationFolder = {
+  path: string;
+  fresh: true;
+};
+
+/** Welcher Ordner: ein neuer je Run oder ein vorhandener; `fresh` auf dem Server legt der Host je Run in seiner Ablage an. */
+export type WorkspaceFolder = "fresh" | ExistingWorkspaceFolder | FreshWorkstationFolder;
+
+/** Wo und in welchem Ordner ein Run arbeitet; wird beim Start als Startoption ins Journal eingefroren. */
+export type WorkspaceBinding = {
+  machine: WorkspaceMachine;
+  folder: WorkspaceFolder;
+};
 
-export const WORKSPACE_BINDING_KINDS = ["fresh", "path", "client"] as const;
+export const freshServerBinding = (): WorkspaceBinding => ({ machine: "server", folder: "fresh" });
 
 export const WORKSPACE_CLIENT_ID_PATTERN = /^[A-Za-z0-9_-]{8,64}$/;
 
@@ -49,15 +64,26 @@ export interface WorkspaceClientDescription {
   hostname: string;
   platform: string;
   folders: string[];
+  /** Wo der Arbeitsplatz die neuen Ordner je Run anlegt, je Run ein Unterordner mit dessen Kennung. */
+  runsDirectory: string;
 }
 
 export interface WorkspaceClientInfo extends WorkspaceClientDescription {
   id: string;
 }
 
+/** Wie der neue Ordner je Run auf jedem Rechner heißt: der leere Ordner oder der Beitrag eines Plugins; null, wo es keinen gibt. */
+export interface FreshWorkspaceLabels {
+  server: string;
+  client: string | null;
+}
+
 export interface WorkspaceBindingPresentation {
   kind: "workspace-binding";
   clients: WorkspaceClientInfo[];
+  fresh: FreshWorkspaceLabels;
+  /** Ob ein vorhandener Ordner des Serverrechners gebunden werden darf. */
+  serverFolders: boolean;
 }
 
 export interface WorkspaceSessionMetadata {
@@ -74,6 +100,7 @@ const clientDescription = {
   hostname: Type.String({ minLength: 1 }),
   platform: Type.String({ minLength: 1 }),
   folders: Type.Array(Type.String({ minLength: 1 }), { maxItems: 32 }),
+  runsDirectory: Type.String({ minLength: 1, description: "Absoluter Ordner, unter dem der Arbeitsplatz die neuen Ordner je Run anlegt" }),
 };
 
 export const clientInfoSchema = Type.Object({
@@ -83,26 +110,27 @@ export const clientInfoSchema = Type.Object({
 
 const absolutePath = Type.String({ minLength: 1, description: "Absoluter Pfad im gebundenen Ordner" });
 
-/** Die eine Operation, die der Server auf dem Arbeitsplatz ruft; Bash-Ausgabe meldet sie als Fortschritt mit { text }. */
+/** Keine Operation eines Moduls: gibt frei, was der Executor des Arbeitsplatzes für den Run hält. */
+export const WORKSPACE_CLIENT_STOP_OPERATION = "stop";
+
+/** Die eine Operation, die der Server auf dem Arbeitsplatz ruft; Fortschritt ist der JSON-Wert der Operation, bei Bash { text }. */
 export const workspaceClientContracts = {
   execute: defineOperation({
     id: "ragents.workspace.client.execute",
-    description: "Ein Arbeitsplatz-Werkzeug auf dem Arbeitsplatz ausführen; das Ergebnis ist der Wert des Werkzeugs, Ausgabe kommt als Fortschritt { text }.",
+    description: "Eine Operation des Executors auf dem Arbeitsplatz ausführen, etwa ein Werkzeug, eine Dateiabfrage oder die Prozessanzeige; das Ergebnis ist ihr Wert, Fortschritt ihr JSON-Wert. stop gibt frei, was der Arbeitsplatz für den Run hält.",
     implementedBy: "client",
     input: Type.Object({
       runId: Type.String({ minLength: 1, maxLength: 64, description: "Kennung des Runs" }),
-      tool: Type.String({ minLength: 1, maxLength: 64, description: "Name des Werkzeugs, etwa read, bash oder roslyn_open" }),
-      toolCallId: Type.String({ minLength: 1, maxLength: 200 }),
+      operation: Type.String({ minLength: 1, maxLength: 64, description: "Name der Operation, etwa read, bash, roslyn_open, files.list oder stop" }),
+      toolCallId: Type.Optional(Type.String({ minLength: 1, maxLength: 200, description: "Nur bei einem Werkzeugaufruf des Modells" })),
       cwd: absolutePath,
       env: Type.Record(Type.String(), Type.String(), { description: "Was der Server beiträgt: Run-Marker und Git-Regeln der Sandbox" }),
-      input: Type.Unknown({ description: "Die Eingabe des Werkzeugs" }),
+      input: Type.Unknown({ description: "Die Eingabe der Operation" }),
     }, { additionalProperties: false }),
     result: Type.Object({ value: Type.Unknown() }, { additionalProperties: false }),
   }),
 } as const;
 
-export const workspaceClientProgressSchema = Type.Object({ text: Type.String() }, { additionalProperties: false });
-
 const browseTarget = {
   runId: Type.String({ minLength: 1, maxLength: 64, description: "Kennung des Runs" }),
   root: Type.Union([Type.Literal("workspace"), Type.Literal("files")]),
@@ -139,7 +167,7 @@ export const workspaceContracts = {
   clients: {
     list: defineOperation({
       id: "ragents.workspace.clients.list",
-      description: "Angemeldete Arbeitsplätze mit Verbindungsstand.",
+      description: "Die angemeldeten Arbeitsplätze des Aufrufers; fremde erscheinen auch mit runs.read.all nicht.",
       rights: ["runs.read"],
       input: Type.Object({}, { additionalProperties: false }),
       result: Type.Array(clientInfoSchema),
@@ -153,7 +181,7 @@ export const workspaceContracts = {
     }),
     unregister: defineOperation({
       id: "ragents.workspace.clients.unregister",
-      description: "Einen Arbeitsplatz abmelden; offene Aufträge scheitern.",
+      description: "Einen eigenen Arbeitsplatz abmelden; offene Aufträge scheitern.",
       rights: ["runs.write"],
       input: Type.Object({ id: clientId }, { additionalProperties: false }),
       result: Type.Null(),
@@ -161,22 +189,57 @@ export const workspaceContracts = {
   },
 } as const;
 
-export const isWorkspaceBinding = (value: unknown): value is WorkspaceBinding => {
-  if (typeof value !== "object" || value === null) return false;
-  const raw = value as Record<string, unknown>;
-  if (raw.kind === "fresh") return true;
-  if (raw.kind === "path") return typeof raw.path === "string" && raw.path.length > 0;
-  if (raw.kind === "client") {
-    return typeof raw.client === "string" && WORKSPACE_CLIENT_ID_PATTERN.test(raw.client)
-      && typeof raw.label === "string" && typeof raw.path === "string" && raw.path.length > 0;
-  }
-  return false;
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null;
+
+const hasExactly = (value: Record<string, unknown>, keys: readonly string[]): boolean =>
+  Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+
+const isMachine = (value: unknown): value is WorkspaceMachine =>
+  value === "server" || (isRecord(value) && hasExactly(value, ["client", "label"])
+    && typeof value.client === "string" && WORKSPACE_CLIENT_ID_PATTERN.test(value.client) && typeof value.label === "string");
+
+const isFolder = (value: unknown): value is WorkspaceFolder => {
+  if (value === "fresh") return true;
+  if (!isRecord(value) || typeof value.path !== "string" || value.path.length === 0) return false;
+  return hasExactly(value, ["path"]) || (hasExactly(value, ["path", "fresh"]) && value.fresh === true);
 };
 
-export const workspaceBindingSummary = (binding: WorkspaceBinding): string => {
-  switch (binding.kind) {
-    case "fresh": return "Leerer Ordner je Run";
-    case "path": return binding.path;
-    case "client": return `${binding.label}: ${binding.path}`;
+/** Einen neuen Ordner mit Pfad gibt es nur auf einem Arbeitsplatz; auf dem Server legt ihn der Host selbst an. */
+export const isWorkspaceBinding = (value: unknown): value is WorkspaceBinding =>
+  isRecord(value) && hasExactly(value, ["machine", "folder"]) && isMachine(value.machine) && isFolder(value.folder)
+  && !(value.machine === "server" && typeof value.folder === "object" && "fresh" in value.folder);
+
+export const isFreshFolder = (folder: WorkspaceFolder): folder is "fresh" | FreshWorkstationFolder =>
+  folder === "fresh" || "fresh" in folder;
+
+/** Die Form vor der Trennung von Rechner und Ordner, `{ kind: "fresh" | "path" | "client" }`, eindeutig in der heutigen. */
+const fromKind = (value: Record<string, unknown>): unknown => {
+  switch (value.kind) {
+    case "fresh": return hasExactly(value, ["kind"]) ? freshServerBinding() : undefined;
+    case "path": return hasExactly(value, ["kind", "path"]) ? { machine: "server", folder: { path: value.path } } : undefined;
+    case "client": return hasExactly(value, ["kind", "client", "label", "path"])
+      ? { machine: { client: value.client, label: value.label }, folder: { path: value.path } }
+      : undefined;
+    default: return undefined;
   }
 };
+
+/** Die gespeicherte Bindung; ältere, unveränderliche Journale tragen die Form mit `kind`, und nur hier wird sie abgebildet. */
+export const storedWorkspaceBinding = (value: unknown): WorkspaceBinding | undefined => {
+  if (isWorkspaceBinding(value)) return value;
+  const mapped = isRecord(value) && Object.hasOwn(value, "kind") ? fromKind(value) : undefined;
+  return isWorkspaceBinding(mapped) ? mapped : undefined;
+};
+
+export const FRESH_WORKSPACE_LABEL = "Leerer Ordner je Run";
+
+/** Wie der neue Ordner je Run auf dem Rechner der Bindung heißt; ohne Beitrag dort der leere Ordner. */
+const freshLabelOf = (binding: WorkspaceBinding, labels: FreshWorkspaceLabels): string =>
+  (binding.machine === "server" ? labels.server : labels.client) ?? FRESH_WORKSPACE_LABEL;
+
+export const workspaceBindingSummary = (binding: WorkspaceBinding, labels: FreshWorkspaceLabels): string => {
+  const { machine, folder } = binding;
+  const fresh = freshLabelOf(binding, labels);
+  const where = folder === "fresh" ? fresh : "fresh" in folder ? `${folder.path} (${fresh})` : folder.path;
+  return machine === "server" ? where : `${machine.label}: ${where}`;
+};

package/plugins/ragents.workspace/prompt.hbs

@@ -1,14 +1,7 @@
 # Working environment
 
-Your working directory belongs to this conversation. A system note at the start says where it is:
-
-- A private empty folder: no other conversation sees it, and it starts empty unless the profile has
-  prepared content in it.
-- A project folder the user chose, on the server or on the user's own workplace: it is the user's
-  real project. Work inside it, keep its structure, and never delete or reorganize files unless asked.
-
 Rules:
 
-- Reads and writes are allowed only inside the working directory and the run's file store.
+- Reads and writes are allowed only inside the working directory, the roots named with it and the run's file store.
 - Remote git operations (push, fetch, pull) and global git configuration are not allowed.
 - No network access from `bash`; use only the tools explicitly provided.

package/plugins/ragents.workspace/ragents-plugin.json

@@ -0,0 +1,3 @@
+{
+  "id": "ragents.workspace"
+}