@schlenkr/ragents 0.1.5 → 0.1.7

package/plugins/ragents.workspace/server/clients.ts

@@ -1,4 +1,3 @@
-import { Value } from "typebox/value";
 import {
   DomainError,
   RPC_ERROR_CODES,
@@ -7,57 +6,92 @@ import {
   type AccessContext,
   type MethodConnection,
   type MethodContribution,
-} from "@aicontainer/ragents";
+} from "@ragents/engine";
 import {
   WORKSPACE_EXECUTOR_VERSION,
-  WORKSPACE_STOP_OPERATION,
   sandboxRunEnvironment,
   type WorkspaceExecuteOptions,
   type WorkspaceExecutor,
-} from "@aicontainer/workspace-executor";
+} from "@ragents/workspace-executor";
 import {
+  WORKSPACE_CLIENT_STOP_OPERATION,
   workspaceClientContracts,
-  workspaceClientProgressSchema,
   workspaceContracts,
   type WorkspaceClientDescription,
   type WorkspaceClientInfo,
 } from "../contract.js";
 
 interface ClientEntry {
-  info: WorkspaceClientInfo;
-  owner: string | null;
-  connection: MethodConnection;
-  release: () => void;
+  readonly info: WorkspaceClientInfo;
+  readonly owner: string | null;
+  readonly connection: MethodConnection;
+  readonly release: () => void;
+  /** Die offenen Aufrufe über diese Anmeldung; löst eine neue Verbindung sie ab, scheitern sie sofort. */
+  readonly calls: Set<AbortController>;
+  /** Die Stopps, die gerade über diese Anmeldung zugestellt werden, je Run. */
+  readonly stops: Map<string, Promise<void>>;
 }
 
 /** Die einzige Grenze gegen einen hängenden Arbeitsplatz; seine eigenen Zeitgrenzen hat der Executor. */
 const CLIENT_TIMEOUT_MS = 15 * 60 * 1000;
 
+/** So lange wartet Aufräumen (Stopp, `whenReachable`) auf den Arbeitsplatz; es bleibt unter der Stoppgrenze der Plugins. */
+const CLEANUP_TIMEOUT_MS = 10_000;
+
+/** Nach so langer Zeit versucht der Server einen ausstehenden Stopp erneut, solange der Arbeitsplatz angemeldet ist. */
+const STOP_RETRY_MS = 30_000;
+
 export const ownerOf = (access: AccessContext): string | null => access.user?.id ?? null;
 
-const progressOf = (label: string, value: unknown): string => {
-  if (!Value.Check(workspaceClientProgressSchema, value)) throw new Error(`Der Arbeitsplatz ${label} hat keine gültige Ausgabe geliefert`);
-  return value.text;
+/** Eine Beobachtung läuft bis zum Abbruch, Aufräumen kurz; alles andere wartet die Sicherheitsgrenze plus der Dauer, die der Aufruf selbst verlangt. */
+const timeoutFor = (options: WorkspaceExecuteOptions): { timeoutMs?: number } => {
+  if (options.untilAborted) return {};
+  if (options.whenReachable) return { timeoutMs: CLEANUP_TIMEOUT_MS };
+  return { timeoutMs: CLIENT_TIMEOUT_MS + (options.durationMs ?? 0) };
 };
 
-const timeoutFor = (input: unknown): number =>
-  CLIENT_TIMEOUT_MS + ((input as { timeout?: number } | null | undefined)?.timeout ?? 0) * 1000;
+const disconnected = (label: string, detail: string): DomainError =>
+  new DomainError("workspace-client-disconnected", `Der Arbeitsplatz ${label} hat die Verbindung verloren: ${detail}`, 409);
 
-/** Bricht die Verbindung mitten im Aufruf, muss die Ursache den Arbeitsplatz nennen, nicht den Server. */
+/** Bricht die Verbindung mitten im Aufruf, muss die Ursache den Arbeitsplatz nennen, nicht den Server; ein fachlicher Fehler bleibt einer. */
 const withClientCause = (cause: unknown, label: string): unknown => {
   if (!(cause instanceof RpcError)) return cause;
-  if (cause.code === RPC_ERROR_CODES.connectionClosed) {
-    return new DomainError("workspace-client-disconnected", `Der Arbeitsplatz ${label} hat die Verbindung verloren: ${cause.message}`, 409);
-  }
+  if (cause.code === RPC_ERROR_CODES.connectionClosed) return disconnected(label, cause.message);
   if (cause.code === RPC_ERROR_CODES.timeout) {
     return new DomainError("workspace-client-timeout", `Der Arbeitsplatz ${label} hat nicht geantwortet: ${cause.message}`, 504);
   }
+  if (cause.code === RPC_ERROR_CODES.application && cause.domainCode !== undefined && cause.status !== undefined) {
+    return new DomainError(cause.domainCode, cause.message, cause.status);
+  }
   return cause;
 };
 
-/** Kennt die angemeldeten Arbeitsplätze und hält je Client die Verbindung, über die der Server ihn zurückruft. */
+/** Der Arbeitsplatz war nicht da oder hat nicht rechtzeitig geantwortet; ein fachlicher Fehler zählt nicht dazu. */
+const unreached = (cause: unknown): boolean =>
+  cause instanceof DomainError && (cause.code === "workspace-client-disconnected" || cause.code === "workspace-client-timeout");
+
+const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
+
+/** Ein Arbeitsplatz ist erst durch Besitzer und Kennung bestimmt; zwei Benutzer mit derselben Kennung teilen nichts. */
+const keyOf = (owner: string | null, id: string): string => JSON.stringify([owner, id]);
+
+/** Über das Netz nimmt der Server Arbeitsplätze nur von angemeldeten Benutzern an; ohne Benutzer gäbe es nur einen Besitzer für alle Zugänge. */
+export const assertMayRegister = (access: AccessContext, local: boolean): void => {
+  if (local || (access.enabled && access.user !== null)) return;
+  throw new DomainError(
+    "workspace-client-login-required",
+    "Dieser Server kennt keine Benutzeranmeldung; einen Arbeitsplatz nimmt er deshalb nur über eine Loopback-Verbindung an "
+      + "(etwa http://127.0.0.1 auf seinem eigenen Rechner). Über das Netz braucht ein Arbeitsplatz ein Profil mit Benutzern.",
+    403,
+  );
+};
+
+/** Kennt die angemeldeten Arbeitsplätze je Besitzer, hält je Client die Verbindung, über die der Server ihn zurückruft, und die Stopps, die ihn nicht erreicht haben. */
 export class WorkspaceClientRegistry {
   readonly #clients = new Map<string, ClientEntry>();
+  /** Stopps, die den Arbeitsplatz noch nicht erreicht haben, je Arbeitsplatz und Run mit dem Ordner der Bindung. */
+  readonly #pendingStops = new Map<string, Map<string, string>>();
+  readonly #stopRetries = new Map<string, NodeJS.Timeout>();
 
   async register(
     id: string,
@@ -76,86 +110,220 @@ export class WorkspaceClientRegistry {
       );
     }
     const owner = connection.userId;
-    const existing = this.#clients.get(id);
-    if (existing && existing.owner !== owner) {
-      throw new DomainError("workspace-client-foreign", `Der Arbeitsplatz ${id} gehört einem anderen Benutzer.`, 403);
-    }
-    existing?.release();
+    const key = keyOf(owner, id);
+    const previous = this.#clients.get(key);
+    previous?.release();
     const info: WorkspaceClientInfo = { ...description, id };
-    const release = connection.onClose(() => this.#disconnected(id, connection));
-    this.#clients.set(id, { info, owner, connection, release });
+    const renewed = previous?.connection === connection;
+    const entry: ClientEntry = {
+      info,
+      owner,
+      connection,
+      release: connection.onClose(() => this.#disconnected(key, connection)),
+      calls: renewed ? previous.calls : new Set(),
+      stops: renewed ? previous.stops : new Map(),
+    };
+    this.#clients.set(key, entry);
+    if (previous && !renewed) this.#abandon(previous);
+    this.#deliverPendingStops(key);
     return info;
   }
 
-  /** Nach einer Trennung steht kein Eintrag mehr; eine Abmeldung ohne Eintrag ist deshalb kein Fehler. */
-  unregister(id: string, owner: string | null): void {
-    const entry = this.#clients.get(id);
-    if (!entry) return;
-    if (entry.owner !== owner) throw new DomainError("workspace-client-foreign", `Der Arbeitsplatz ${id} gehört einem anderen Benutzer.`, 403);
-    entry.release();
-    this.#clients.delete(id);
+  /** Nur die Verbindung, die den Eintrag hält, meldet ihn ab; eine Abmeldung ohne Eintrag ist nach einer Trennung kein Fehler. */
+  unregister(owner: string | null, id: string, connection: MethodConnection): void {
+    const key = keyOf(owner, id);
+    const entry = this.#clients.get(key);
+    if (entry?.connection !== connection) return;
+    this.#remove(key, entry);
   }
 
-  list(): WorkspaceClientInfo[] {
-    return [...this.#clients.values()].map((entry) => entry.info);
+  list(owner: string | null): WorkspaceClientInfo[] {
+    return [...this.#clients.values()].filter((entry) => entry.owner === owner).map((entry) => entry.info);
   }
 
-  info(id: string): WorkspaceClientInfo | undefined {
-    return this.#clients.get(id)?.info;
+  info(owner: string | null, id: string): WorkspaceClientInfo | undefined {
+    return this.#clients.get(keyOf(owner, id))?.info;
   }
 
-  /** Der Executor eines gebundenen Runs: dieselbe Schnittstelle wie im Server, nur über die Verbindung des Arbeitsplatzes. */
-  executorFor(id: string, label: string, cwd: string): WorkspaceExecutor {
-    const connection = (): MethodConnection => {
-      const entry = this.#clients.get(id);
-      if (!entry) throw new DomainError("workspace-client-disconnected", `Der Arbeitsplatz ${label} ist nicht verbunden.`, 409);
-      return entry.connection;
-    };
-    const call = async (runId: string, tool: string, input: unknown, options: WorkspaceExecuteOptions): Promise<unknown> => {
+  /** Die Runs, deren Stopp diesen Arbeitsplatz noch nicht erreicht hat. */
+  pendingStops(owner: string | null, id: string): readonly string[] {
+    return this.#pendingRuns(keyOf(owner, id));
+  }
+
+  /** Der Executor eines gebundenen Runs: dieselbe Schnittstelle wie im Server, nur über die Verbindung des Arbeitsplatzes seines Besitzers. */
+  executorFor(owner: string | null, id: string, label: string, cwd: string): WorkspaceExecutor {
+    const key = keyOf(owner, id);
+    const call = async (runId: string, operation: string, input: unknown, options: WorkspaceExecuteOptions): Promise<unknown> => {
+      if (options.untilAborted && !options.signal) throw new Error(`Die Operation ${operation} läuft bis zum Abbruch und braucht dafür ein Abbruchsignal`);
+      if (this.#pendingStops.get(key)?.has(runId)) {
+        // Aufräumen neben einem ausstehenden Stopp erledigt dieser mit; alles andere wartet, bis er zugestellt ist.
+        if (options.whenReachable) return null;
+        if (this.#clients.has(key)) await this.#deliverStop(key, runId);
+      }
+      const entry = this.#clients.get(key);
+      if (!entry) {
+        if (options.whenReachable) return null;
+        throw new DomainError("workspace-client-disconnected", `Der Arbeitsplatz ${label} ist nicht verbunden.`, 409);
+      }
       try {
-        const { value } = await connection().call(
-          workspaceClientContracts.execute,
-          { runId, tool, toolCallId: options.toolCallId ?? tool, cwd, env: sandboxRunEnvironment(runId), input },
-          {
-            ...(options.signal ? { signal: options.signal } : {}),
-            timeoutMs: timeoutFor(input),
-            ...(options.onProgress ? { onProgress: (progress: unknown) => options.onProgress!(progressOf(label, progress)) } : {}),
-          },
-        );
-        return value;
+        return await this.#send(entry, runId, operation, input, cwd, options);
       } catch (cause) {
-        throw withClientCause(cause, label);
+        if (options.whenReachable && unreached(cause)) return null;
+        throw cause;
       }
     };
     return {
       version: WORKSPACE_EXECUTOR_VERSION,
-      execute: (runId, tool, input, options = {}) => call(runId, tool, input, options),
+      execute: (runId, operation, input, options = {}) => call(runId, operation, input, options),
       stopRun: async (runId) => {
-        if (!this.#clients.has(id)) return;
-        await call(runId, WORKSPACE_STOP_OPERATION, null, {});
+        this.#pendingStopsOf(key).set(runId, cwd);
+        await this.#deliverStop(key, runId);
       },
       shutdown: async () => undefined,
     };
   }
 
   shutdown(): void {
-    for (const entry of this.#clients.values()) entry.release();
+    for (const entry of this.#clients.values()) {
+      entry.release();
+      this.#abandon(entry);
+    }
     this.#clients.clear();
+    for (const timer of this.#stopRetries.values()) clearTimeout(timer);
+    this.#stopRetries.clear();
+    this.#pendingStops.clear();
   }
 
   /** Ein getrennter Arbeitsplatz verlässt die Registry; eine spätere Anmeldung über eine neue Verbindung bleibt stehen. */
-  #disconnected(id: string, connection: MethodConnection): void {
-    if (this.#clients.get(id)?.connection !== connection) return;
-    this.#clients.delete(id);
+  #disconnected(key: string, connection: MethodConnection): void {
+    const entry = this.#clients.get(key);
+    if (entry?.connection !== connection) return;
+    this.#remove(key, entry);
+  }
+
+  #remove(key: string, entry: ClientEntry): void {
+    entry.release();
+    this.#clients.delete(key);
+    this.#abandon(entry);
+  }
+
+  /** Eine Verbindung, die niemand mehr hält, bekommt keine Antworten mehr zugestellt; ihre offenen Aufrufe scheitern sofort. */
+  #abandon(entry: ClientEntry): void {
+    for (const controller of entry.calls) controller.abort();
+    entry.calls.clear();
+  }
+
+  async #send(
+    entry: ClientEntry,
+    runId: string,
+    operation: string,
+    input: unknown,
+    cwd: string,
+    options: WorkspaceExecuteOptions,
+  ): Promise<unknown> {
+    const label = entry.info.label;
+    const abandoned = new AbortController();
+    entry.calls.add(abandoned);
+    const signal = options.signal ? AbortSignal.any([options.signal, abandoned.signal]) : abandoned.signal;
+    try {
+      const { value } = await Promise.race([
+        entry.connection.call(
+          workspaceClientContracts.execute,
+          {
+            runId,
+            operation,
+            ...(options.toolCallId ? { toolCallId: options.toolCallId } : {}),
+            cwd,
+            env: sandboxRunEnvironment(runId),
+            input,
+          },
+          {
+            signal,
+            ...timeoutFor(options),
+            ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+          },
+        ),
+        new Promise<never>((_settle, fail) => abandoned.signal.addEventListener("abort", () =>
+          fail(disconnected(label, "eine neue Verbindung hat die Anmeldung abgelöst")), { once: true })),
+      ]);
+      return value;
+    } catch (cause) {
+      throw withClientCause(cause, label);
+    } finally {
+      entry.calls.delete(abandoned);
+    }
+  }
+
+  #pendingStopsOf(key: string): Map<string, string> {
+    const known = this.#pendingStops.get(key);
+    if (known) return known;
+    const created = new Map<string, string>();
+    this.#pendingStops.set(key, created);
+    return created;
+  }
+
+  /** Stellt einen ausstehenden Stopp zu; erreicht er den Arbeitsplatz nicht, bleibt er ausstehend, und die nächste Anmeldung holt ihn nach. */
+  #deliverStop(key: string, runId: string): Promise<void> {
+    const entry = this.#clients.get(key);
+    const cwd = this.#pendingStops.get(key)?.get(runId);
+    if (cwd === undefined) return Promise.resolve();
+    if (!entry) {
+      console.warn(`Der Stopp des Runs ${runId} erreicht seinen Arbeitsplatz erst bei dessen nächster Anmeldung.`);
+      return Promise.resolve();
+    }
+    const running = entry.stops.get(runId);
+    if (running) return running;
+    const delivery = this.#send(entry, runId, WORKSPACE_CLIENT_STOP_OPERATION, null, cwd, { whenReachable: true })
+      .then(() => this.#stopDelivered(key, runId, cwd), (cause: unknown) => {
+        if (!unreached(cause)) {
+          this.#stopDelivered(key, runId, cwd);
+          throw cause;
+        }
+        console.warn(`Der Stopp des Runs ${runId} hat den Arbeitsplatz ${entry.info.label} nicht erreicht und bleibt ausstehend: ${messageOf(cause)}`);
+        this.#retryStops(key);
+      })
+      .finally(() => entry.stops.delete(runId));
+    entry.stops.set(runId, delivery);
+    return delivery;
+  }
+
+  #stopDelivered(key: string, runId: string, cwd: string): void {
+    const pending = this.#pendingStops.get(key);
+    if (pending?.get(runId) === cwd) pending.delete(runId);
+    if (pending?.size === 0) this.#pendingStops.delete(key);
+  }
+
+  #deliverPendingStops(key: string): void {
+    for (const runId of this.#pendingRuns(key)) {
+      void this.#deliverStop(key, runId).catch((cause: unknown) =>
+        console.warn(`Der nachgeholte Stopp des Runs ${runId} ist gescheitert: ${messageOf(cause)}`));
+    }
+  }
+
+  #pendingRuns(key: string): readonly string[] {
+    return [...this.#pendingStops.get(key)?.keys() ?? []];
+  }
+
+  /** Ein Arbeitsplatz, der angemeldet bleibt, aber nicht antwortet, bekommt seine ausstehenden Stopps später noch einmal. */
+  #retryStops(key: string): void {
+    if (this.#stopRetries.has(key)) return;
+    const timer = setTimeout(() => {
+      this.#stopRetries.delete(key);
+      if (this.#clients.has(key)) this.#deliverPendingStops(key);
+    }, STOP_RETRY_MS);
+    timer.unref();
+    this.#stopRetries.set(key, timer);
   }
 }
 
 export const clientMethods = (registry: WorkspaceClientRegistry): MethodContribution[] => [
-  implement(workspaceContracts.clients.list, () => registry.list()),
-  implement(workspaceContracts.clients.register, ({ id, executor, ...description }, { connection }) =>
-    registry.register(id, description, executor, connection)),
-  implement(workspaceContracts.clients.unregister, ({ id }, { access }) => {
-    registry.unregister(id, ownerOf(access));
+  implement(workspaceContracts.clients.list, (_input, { access }) => registry.list(ownerOf(access))),
+  implement(workspaceContracts.clients.register, ({ id, executor, ...description }, { access, connection, local }) => {
+    assertMayRegister(access, local);
+    return registry.register(id, description, executor, connection);
+  }),
+  implement(workspaceContracts.clients.unregister, ({ id }, { access, connection }) => {
+    registry.unregister(ownerOf(access), id, connection);
     return null;
   }),
 ];

package/plugins/ragents.workspace/server/config.ts

@@ -0,0 +1,30 @@
+import { declaredEnvironment } from "@ragents/host/plugin-support/plugin-config.js";
+import { PROCESS_SANDBOX_DEFAULT_NETWORK } from "@ragents/host/plugin-support/process-sandbox.js";
+
+export const workspaceConfigDescriptors = [
+  { key: "PROCESS_SANDBOX", source: "environment" },
+  { key: "PROCESS_SANDBOX_NETWORK", source: "environment" },
+  { key: "RAGENTS_BASH", source: "environment" },
+] as const;
+
+const env = declaredEnvironment(workspaceConfigDescriptors);
+
+export interface ProcessSandboxSetting {
+  readonly enabled: boolean;
+  readonly network: readonly string[];
+}
+
+/** Ohne Angabe ist die Sandbox an; abschalten geht nur ausdrücklich mit "off". */
+export const processSandboxSetting = (): ProcessSandboxSetting => {
+  const mode = env.optional("PROCESS_SANDBOX") ?? "on";
+  if (mode !== "on" && mode !== "off") {
+    throw new Error(`PROCESS_SANDBOX in der Sektion ragents.workspace ist "on" oder "off", nicht "${mode}"`);
+  }
+  const network = env.optional("PROCESS_SANDBOX_NETWORK") === undefined
+    ? PROCESS_SANDBOX_DEFAULT_NETWORK
+    : env.list("PROCESS_SANDBOX_NETWORK");
+  return { enabled: mode === "on", network };
+};
+
+/** Die Bash, mit der der Executor dieses Servers das Werkzeug bash startet; unter Windows setzt sie die VS-Code-Erweiterung für ihren lokalen Host. */
+export const bashSetting = (): string | undefined => env.optional("RAGENTS_BASH") || undefined;

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

@@ -1,30 +1,37 @@
 import path from "node:path";
-import { DomainError, type JsonValue, type RAgentsPlugin, type RunState } from "@aicontainer/ragents";
-import { documentStoreToken } from "@aicontainer/server/ragents/document-store.js";
-import { workspaceResolverToken, workspaceRuntimeToken } from "@aicontainer/server/ragents/workspace-runtime.js";
-import { sandboxServicesToken } from "@aicontainer/server/plugin-support/workspace-sandbox-host.js";
+import { DomainError, type JsonValue, type RAgentsPlugin, type RunState } from "@ragents/engine";
+import { documentStoreToken } from "@ragents/host/ragents/document-store.js";
+import { workspaceResolverToken, workspaceRuntimeToken, type WorkspaceResolver } from "@ragents/host/ragents/workspace-runtime.js";
+import { sandboxServicesToken } from "@ragents/host/plugin-support/workspace-sandbox-host.js";
 import {
+  hostAddressToken,
   runtimeProviderToken,
-  sessionGuardToken,
-  sessionWorkspaceProviderToken,
-} from "@aicontainer/server/ragents/host-services.js";
-import { pluginAssetPath } from "@aicontainer/server/plugin-support/asset-path.js";
-import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
-import { handlebarsPrompt } from "@aicontainer/server/plugin-support/prompt.js";
-import { shellPlatformPrompt } from "@aicontainer/server/plugin-support/shell-platform.js";
-import { startOptionScope } from "@aicontainer/server/ragents/start-option-state.js";
-import { WORKSPACE_BINDING_OPTION_ID, WORKSPACE_METADATA_ID, type BrowseRoot } from "../contract.js";
-import { bindingOf, executorShellChapter, sessionMetadataOf, workspaceBindingOption } from "./binding.js";
+  runGuardToken,
+  runWorkspaceProviderToken,
+  workspaceGuardToken,
+} from "@ragents/host/ragents/host-services.js";
+import { pluginAsset } from "@ragents/host/plugin-support/plugin-folder.js";
+import { ServerProcessSandbox } from "@ragents/host/plugin-support/process-sandbox.js";
+import type { PluginModule } from "@ragents/host/plugin-support/plugin-module.js";
+import { boundToTools, handlebarsPrompt } from "@ragents/host/plugin-support/prompt.js";
+import { shellPlatformPrompt } from "./shell-platform.js";
+import { agentWorkspaceToolNames } from "./workspace-tool-naming.js";
+import { startOptionScope } from "@ragents/host/ragents/start-option-state.js";
+import { WORKSPACE_BINDING_OPTION_ID, WORKSPACE_METADATA_ID } from "../contract.js";
+import { bindingOf, executorShellChapter, sessionMetadataOf, workspaceBindingOption, workspaceLocation, workspaceOwnerOf } from "./binding.js";
 import { createBrowseChannel, createBrowseMethods } from "./browse-route.js";
 import { clientMethods, WorkspaceClientRegistry } from "./clients.js";
+import { bashSetting, processSandboxSetting, workspaceConfigDescriptors } from "./config.js";
 import { RunWorkspaceRuntime } from "./runtime.js";
 
-const promptFile = pluginAssetPath(import.meta.url, "../prompt.hbs");
+const warnWithoutSandbox = (): void => {
+  console.warn("Prozess-Sandbox ausgeschaltet (PROCESS_SANDBOX: \"off\" in der Sektion ragents.workspace): Prozesse der Runs laufen auf dem Server ohne Sandbox.");
+};
 
 const ragentsWorkspacePlugin = (skillPaths: () => Promise<readonly string[]>): RAgentsPlugin => ({
   manifest: { id: "ragents.workspace" },
   register: (host) => {
-    const sessionWorkspaceFor = host.service(sessionWorkspaceProviderToken);
+    const sessionWorkspaceFor = host.service(runWorkspaceProviderToken);
     const orchestration = host.service(runtimeProviderToken);
     const runState = (runId: string): RunState | null => {
       try {
@@ -42,14 +49,28 @@ const ragentsWorkspacePlugin = (skillPaths: () => Promise<readonly string[]>): R
       return directory;
     };
     const clients = new WorkspaceClientRegistry();
+    const contribution = (): WorkspaceResolver | undefined => host.optionalService(workspaceResolverToken);
+    host.config(...workspaceConfigDescriptors);
+    const sandboxSetting = processSandboxSetting();
+    const processSandbox = sandboxSetting.enabled
+      ? new ServerProcessSandbox({
+        network: sandboxSetting.network,
+        serverAddress: host.service(hostAddressToken)(),
+        dataDirectory: path.dirname(host.storage.sessionsRoot),
+      })
+      : undefined;
+    const bash = bashSetting();
     const runtime = new RunWorkspaceRuntime({
       clients,
+      ...(processSandbox ? { processSandbox } : {}),
+      ...(bash === undefined ? {} : { bash }),
       globalDirectory: host.storage.root(),
       sessionDirectory: (runId, ...segments) => host.storage.session(runId, ...segments),
+      storageRootFor: (runId) => path.join(host.storage.sessionsRoot, runId),
       sessionsDirectoryPattern: path.join(host.storage.sessionsRoot, "{runId}", "plugins", host.manifest.id),
       sessionWorkspaceFor,
       skillPaths,
-      resolver: () => host.optionalService(workspaceResolverToken),
+      resolver: contribution,
       runState,
       storeBinding: (runId, binding) => {
         const state = orchestration().state(runId);
@@ -63,25 +84,39 @@ const ragentsWorkspacePlugin = (skillPaths: () => Promise<readonly string[]>): R
     host.provide(workspaceRuntimeToken, runtime);
     host.provide(sandboxServicesToken, runtime.sandbox);
     host.functions(runtime.sandbox.workspaceTools());
+    const rules = handlebarsPrompt("ragents.workspace.prompt", 100, pluginAsset("ragents.workspace", "prompt.hbs"));
     host.prompts(
-      handlebarsPrompt("ragents.workspace.prompt", 100, promptFile),
-      shellPlatformPrompt("ragents.workspace.shell.prompt", 102, (runId) => executorShellChapter(clients, bindingOf(runState(runId)))),
+      boundToTools({
+        ...rules,
+        delivery: "initial",
+        // Die Regeln gelten für die Arbeitsbereiche des Hosts; eine beigesteuerte Art beschreibt ihre eigenen.
+        render: (context) => contribution()?.kind ? "" : rules.render(context),
+      }, ...agentWorkspaceToolNames),
+      shellPlatformPrompt("ragents.workspace.shell.prompt", 102, (runId) => {
+        const state = runState(runId);
+        return executorShellChapter(clients, workspaceOwnerOf(state), bindingOf(state));
+      }),
     );
     const browseOptions = {
-      ensureSession: host.service(sessionGuardToken),
-      rootFor: (runId: string, root: BrowseRoot) => root === "files"
-        ? documentsRoot(runId)
-        : sessionWorkspaceFor(runId).then((workspace) => workspace.currentRoot()),
+      ensureSession: host.service(runGuardToken),
+      ensureWorkspaceAccess: host.service(workspaceGuardToken),
+      execute: runtime.sandbox.execute.bind(runtime.sandbox),
+      documentsFor: documentsRoot,
+      locationOf: (runId: string, location: string) => workspaceLocation(bindingOf(runState(runId)), location),
     };
     host.methods(...createBrowseMethods(browseOptions), ...clientMethods(clients));
     host.channels(createBrowseChannel(browseOptions));
-    host.startOptions(workspaceBindingOption(clients));
-    host.sessionMetadata({ id: WORKSPACE_METADATA_ID, describe: ({ runId }) => sessionMetadataOf(runState(runId)) });
+    host.startOptions(workspaceBindingOption(clients, contribution));
+    host.sessionMetadata({ id: WORKSPACE_METADATA_ID, describe: ({ runId }) => sessionMetadataOf(runState(runId), contribution()) });
     host.lifecycle({
       id: "ragents.workspace.lifecycle",
+      initialize: () => processSandbox ? processSandbox.start() : warnWithoutSandbox(),
       stopSession: ({ runId }) => runtime.stopSession(runId),
       deleteSession: ({ runId }) => runtime.deleteSession(runId),
-      shutdown: () => runtime.shutdown(),
+      shutdown: async () => {
+        await runtime.shutdown();
+        await processSandbox?.stop();
+      },
     });
   },
 });