@schlenkr/ragents 0.1.0

package/plugins/ragents.workspace/contract.ts

@@ -0,0 +1,182 @@
+import { Type } from "typebox";
+import { openJson } from "@aicontainer/ragents/src/http/contracts";
+import { defineChannel, defineOperation } from "@aicontainer/ragents/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";
+  size: number;
+  modifiedAt: string;
+}
+
+export interface BrowseListing {
+  root: BrowseRoot;
+  location: string;
+  path: string;
+  entries: BrowseEntry[];
+  truncated: boolean;
+}
+
+export type BrowsePreview =
+  | { root: BrowseRoot; path: string; size: number; previewable: true; content: string }
+  | { root: BrowseRoot; path: string; size: number; previewable: false; reason: string };
+
+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 };
+
+export const WORKSPACE_BINDING_KINDS = ["fresh", "path", "client"] as const;
+
+export const WORKSPACE_CLIENT_ID_PATTERN = /^[A-Za-z0-9_-]{8,64}$/;
+
+/** Was ein Arbeitsplatz bei der Anmeldung über sich sagt. */
+export interface WorkspaceClientDescription {
+  label: string;
+  hostname: string;
+  platform: string;
+  folders: string[];
+}
+
+export interface WorkspaceClientInfo extends WorkspaceClientDescription {
+  id: string;
+}
+
+export interface WorkspaceBindingPresentation {
+  kind: "workspace-binding";
+  clients: WorkspaceClientInfo[];
+}
+
+export interface WorkspaceSessionMetadata {
+  binding: WorkspaceBinding;
+  summary: string;
+}
+
+const clientId = Type.String({ pattern: "^[A-Za-z0-9_-]{8,64}$", description: "Stabile Kennung des Arbeitsplatzes" });
+
+const executorVersion = Type.String({ minLength: 1, maxLength: 64, description: "Stand des Executors, den der Arbeitsplatz mitbringt" });
+
+const clientDescription = {
+  label: Type.String({ minLength: 1, maxLength: 120 }),
+  hostname: Type.String({ minLength: 1 }),
+  platform: Type.String({ minLength: 1 }),
+  folders: Type.Array(Type.String({ minLength: 1 }), { maxItems: 32 }),
+};
+
+export const clientInfoSchema = Type.Object({
+  id: Type.String(),
+  ...clientDescription,
+}, { additionalProperties: false });
+
+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 }. */
+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 }.",
+    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 }),
+      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" }),
+    }, { 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")]),
+  path: Type.String({ description: "Pfad unterhalb der Wurzel; leer ist die Wurzel selbst" }),
+};
+
+/** Die Anmeldung eines Arbeitsplatzes bindet die aufrufende Verbindung; über sie ruft der Server zurück. */
+export const workspaceContracts = {
+  browse: {
+    list: defineOperation({
+      id: "ragents.workspace.browse.list",
+      description: "Ein Verzeichnis im Arbeitsverzeichnis oder in der Dateiablage eines Runs auflisten.",
+      rights: ["runs.read", "runs.inspect"],
+      input: Type.Object(browseTarget, { additionalProperties: false }),
+      result: openJson<BrowseListing>("BrowseListing"),
+    }),
+    preview: defineOperation({
+      id: "ragents.workspace.browse.preview",
+      description: "Eine Datei als Text vorschauen; zu große und binäre Dateien nennen stattdessen den Grund.",
+      rights: ["runs.read", "runs.inspect"],
+      input: Type.Object(browseTarget, { additionalProperties: false }),
+      result: openJson<BrowsePreview>("BrowsePreview"),
+    }),
+  },
+  channels: {
+    browse: defineChannel({
+      id: "ragents.workspace.browse",
+      description: "Meldet jede Änderung unterhalb der beobachteten Wurzel eines Runs.",
+      rights: ["runs.read", "runs.inspect"],
+      params: Type.Object({ runId: browseTarget.runId, root: browseTarget.root }, { additionalProperties: false }),
+      message: Type.Object({ changed: Type.Literal(true) }, { additionalProperties: false }),
+    }),
+  },
+  clients: {
+    list: defineOperation({
+      id: "ragents.workspace.clients.list",
+      description: "Angemeldete Arbeitsplätze mit Verbindungsstand.",
+      rights: ["runs.read"],
+      input: Type.Object({}, { additionalProperties: false }),
+      result: Type.Array(clientInfoSchema),
+    }),
+    register: defineOperation({
+      id: "ragents.workspace.clients.register",
+      description: "Einen Arbeitsplatz anmelden oder seine Ordner erneuern; die Verbindung dieser Anfrage wird sein Rückweg und braucht einen Ereignisstrom.",
+      rights: ["runs.write"],
+      input: Type.Object({ id: clientId, ...clientDescription, executor: executorVersion }, { additionalProperties: false }),
+      result: clientInfoSchema,
+    }),
+    unregister: defineOperation({
+      id: "ragents.workspace.clients.unregister",
+      description: "Einen Arbeitsplatz abmelden; offene Aufträge scheitern.",
+      rights: ["runs.write"],
+      input: Type.Object({ id: clientId }, { additionalProperties: false }),
+      result: Type.Null(),
+    }),
+  },
+} 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;
+};
+
+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}`;
+  }
+};

package/plugins/ragents.workspace/prompt.hbs

@@ -0,0 +1,14 @@
+# 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.
+- 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/server/binding.ts

@@ -0,0 +1,92 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+import { Type } from "typebox";
+import { DomainError, type JsonValue, type RunState, type StartOptionContribution } from "@aicontainer/ragents";
+import { shellPlatformChapter } from "@aicontainer/server/plugin-support/shell-platform.js";
+import { storedStartOption } from "@aicontainer/server/ragents/start-option-state.js";
+import {
+  isWorkspaceBinding,
+  WORKSPACE_BINDING_OPTION_ID,
+  workspaceBindingSummary,
+  type WorkspaceBinding,
+  type WorkspaceBindingPresentation,
+  type WorkspaceSessionMetadata,
+} from "../contract.js";
+import type { WorkspaceClientRegistry } from "./clients.js";
+
+const bindingSchema = Type.Union([
+  Type.Object({ kind: Type.Literal("fresh") }, { additionalProperties: false }),
+  Type.Object({ kind: Type.Literal("path"), path: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+  Type.Object({
+    kind: Type.Literal("client"),
+    client: Type.String({ minLength: 8, maxLength: 64 }),
+    label: Type.String(),
+    path: Type.String({ minLength: 1 }),
+  }, { additionalProperties: false }),
+]);
+
+const insideFolder = (folder: string, candidate: string): boolean => {
+  const separator = folder.includes("\\") ? "\\" : "/";
+  const root = folder.endsWith(separator) ? folder.slice(0, -separator.length) : folder;
+  return candidate === root || candidate.startsWith(root + separator);
+};
+
+export const bindingOf = (state: RunState | null): WorkspaceBinding => {
+  const stored = storedStartOption(state, WORKSPACE_BINDING_OPTION_ID);
+  if (stored === undefined) return { kind: "fresh" };
+  if (!isWorkspaceBinding(stored)) throw new Error(`Die gespeicherte Arbeitsbereich-Bindung ist ungültig: ${JSON.stringify(stored)}`);
+  return stored;
+};
+
+/** Der Ordner auf dem Serverrechner, an den der Run gebunden ist; `fresh` und `client` liegen nicht dort. */
+export const boundServerDirectory = (state: RunState | null): string | null => {
+  const binding = bindingOf(state);
+  return binding.kind === "path" ? binding.path : null;
+};
+
+/** Ein vorhandener Ordner dieses Servers als Bindung; dieselbe Prüfung wie beim Wählen der Startoption. */
+export const serverDirectoryBinding = (directory: string): Extract<WorkspaceBinding, { kind: "path" }> => {
+  if (!path.isAbsolute(directory)) throw new DomainError("workspace-path-relative", "Der Ordner muss ein absoluter Pfad sein.", 400);
+  const resolved = path.resolve(directory);
+  if (!statSync(resolved, { throwIfNoEntry: false })?.isDirectory()) {
+    throw new DomainError("workspace-path-missing", `Der Ordner ${resolved} existiert auf dem Server nicht.`, 400);
+  }
+  return { kind: "path", path: resolved };
+};
+
+/** Die Bash eines Runs läuft auf dem Executor seiner Bindung; der Prompt nennt deshalb dessen Plattform, nicht die des Servers. */
+export const executorShellChapter = (registry: WorkspaceClientRegistry, binding: WorkspaceBinding): string => {
+  if (binding.kind !== "client") return shellPlatformChapter(process.platform);
+  const client = registry.info(binding.client);
+  return client
+    ? shellPlatformChapter(client.platform as NodeJS.Platform)
+    : `## Shell platform\n\nThe workstation ${binding.label} that holds this project is not registered right now, `
+      + "so the platform of its shell is unknown; the workspace tools fail until it connects again.";
+};
+
+export const sessionMetadataOf = (state: RunState | null): WorkspaceSessionMetadata => {
+  const binding = bindingOf(state);
+  return { binding, summary: workspaceBindingSummary(binding) };
+};
+
+export const workspaceBindingOption = (registry: WorkspaceClientRegistry): StartOptionContribution => ({
+  id: WORKSPACE_BINDING_OPTION_ID,
+  schema: bindingSchema,
+  selectable: () => true,
+  defaultValue: () => ({ kind: "fresh" }),
+  accept: (value) => {
+    if (!isWorkspaceBinding(value)) throw new DomainError("workspace-binding-invalid", "Die Arbeitsbereich-Bindung hat kein gültiges Format.", 400);
+    if (value.kind === "fresh") return { kind: "fresh" };
+    if (value.kind === "path") return serverDirectoryBinding(value.path);
+    const client = registry.info(value.client);
+    if (!client) throw new DomainError("workspace-client-disconnected", `Der Arbeitsplatz ${value.label || value.client} ist nicht verbunden.`, 409);
+    if (!client.folders.some((folder) => insideFolder(folder, value.path))) {
+      throw new DomainError("workspace-client-folder", `Der Arbeitsplatz ${client.label} bietet den Ordner ${value.path} nicht an.`, 400);
+    }
+    return { kind: "client", client: client.id, label: client.label, path: value.path };
+  },
+  describe: () => {
+    const presentation: WorkspaceBindingPresentation = { kind: "workspace-binding", clients: registry.list() };
+    return presentation as unknown as JsonValue;
+  },
+});

package/plugins/ragents.workspace/server/browse-route.ts

@@ -0,0 +1,134 @@
+import { watch } from "node:fs";
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import {
+  DomainError,
+  implement,
+  implementChannel,
+  type ChannelContribution,
+  type MethodContribution,
+} from "@aicontainer/ragents";
+import {
+  BROWSE_ENTRY_LIMIT,
+  BROWSE_PREVIEW_LIMIT,
+  workspaceContracts,
+  type BrowseEntry,
+  type BrowseListing,
+  type BrowsePreview,
+  type BrowseRoot,
+} from "../contract.js";
+
+const invalid = (message: string): DomainError => new DomainError("browse-path-invalid", message, 400);
+
+const relativeOf = (value: string): string => {
+  const segments = value.split("/").filter((segment) => segment !== "");
+  if (value.includes("\0") || value.includes("\\") || path.isAbsolute(value)
+    || segments.some((segment) => segment === "." || segment === "..")) {
+    throw invalid("Ungültiger Pfad");
+  }
+  return segments.join("/");
+};
+
+const realOf = async (target: string, missing: string): Promise<string> => {
+  try {
+    return await realpath(target);
+  } catch {
+    throw new DomainError("browse-not-found", missing, 404);
+  }
+};
+
+const resolveInside = async (root: string, relative: string): Promise<string> => {
+  const rootReal = await realOf(root, "Der Lauf hat dieses Verzeichnis nicht");
+  const real = await realOf(
+    relative ? path.join(rootReal, relative) : rootReal,
+    `Nicht gefunden: ${relative || "."}`,
+  );
+  if (real !== rootReal && !real.startsWith(rootReal + path.sep)) throw invalid("Ungültiger Pfad");
+  return real;
+};
+
+const entryOf = async (directory: string, name: string, isDirectory: boolean): Promise<BrowseEntry> => {
+  const info = await lstat(path.join(directory, name));
+  return {
+    name,
+    kind: isDirectory ? "directory" : "file",
+    size: info.size,
+    modifiedAt: info.mtime.toISOString(),
+  };
+};
+
+const byKindThenName = (left: BrowseEntry, right: BrowseEntry): number =>
+  (left.kind === right.kind ? 0 : left.kind === "directory" ? -1 : 1)
+  || left.name.localeCompare(right.name, "de");
+
+const listingOf = async (root: string, relative: string, kind: BrowseRoot): Promise<BrowseListing> => {
+  const directory = await resolveInside(root, relative);
+  if (!(await lstat(directory)).isDirectory()) throw invalid(`Kein Verzeichnis: ${relative || "."}`);
+  const found = await readdir(directory, { withFileTypes: true });
+  const entries = (await Promise.all(found.map((entry) => entryOf(directory, entry.name, entry.isDirectory()))))
+    .sort(byKindThenName);
+  return {
+    root: kind,
+    location: root,
+    path: relative,
+    entries: entries.slice(0, BROWSE_ENTRY_LIMIT),
+    truncated: entries.length > BROWSE_ENTRY_LIMIT,
+  };
+};
+
+const previewOf = async (root: string, relative: string, kind: BrowseRoot): Promise<BrowsePreview> => {
+  const file = await resolveInside(root, relative);
+  const info = await lstat(file);
+  if (!info.isFile()) throw invalid(`Keine Datei: ${relative || "."}`);
+  const described = { root: kind, path: relative, size: info.size };
+  if (info.size > BROWSE_PREVIEW_LIMIT) {
+    return {
+      ...described,
+      previewable: false,
+      reason: `Die Datei ist größer als ${BROWSE_PREVIEW_LIMIT / 1024} KB und wird nicht angezeigt`,
+    };
+  }
+  const content = await readFile(file);
+  if (content.includes(0)) return { ...described, previewable: false, reason: "Die Datei ist binär" };
+  return { ...described, previewable: true, content: content.toString("utf8") };
+};
+
+export interface BrowseOptions {
+  rootFor: (runId: string, root: BrowseRoot) => Promise<string>;
+  ensureSession: (runId: string) => void;
+}
+
+export const createBrowseMethods = (options: BrowseOptions): MethodContribution[] => [
+  implement(workspaceContracts.browse.list, async ({ runId, root, path: target }) => {
+    options.ensureSession(runId);
+    return listingOf(await options.rootFor(runId, root), relativeOf(target), root);
+  }),
+  implement(workspaceContracts.browse.preview, async ({ runId, root, path: target }) => {
+    options.ensureSession(runId);
+    return previewOf(await options.rootFor(runId, root), relativeOf(target), root);
+  }),
+];
+
+export const createBrowseChannel = (options: BrowseOptions): ChannelContribution =>
+  implementChannel(workspaceContracts.channels.browse, async ({ runId, root }, emit) => {
+    options.ensureSession(runId);
+    const directory = await options.rootFor(runId, root);
+    let debounce: NodeJS.Timeout | undefined;
+    const changed = () => {
+      if (debounce) return;
+      debounce = setTimeout(() => {
+        debounce = undefined;
+        emit({ changed: true });
+      }, 150);
+    };
+    let watcher: ReturnType<typeof watch> | undefined;
+    try {
+      watcher = watch(directory, { recursive: true }, changed);
+      watcher.on("error", changed);
+    } catch {
+    }
+    return () => {
+      if (debounce) clearTimeout(debounce);
+      watcher?.close();
+    };
+  });

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

@@ -0,0 +1,161 @@
+import { Value } from "typebox/value";
+import {
+  DomainError,
+  RPC_ERROR_CODES,
+  RpcError,
+  implement,
+  type AccessContext,
+  type MethodConnection,
+  type MethodContribution,
+} from "@aicontainer/ragents";
+import {
+  WORKSPACE_EXECUTOR_VERSION,
+  WORKSPACE_STOP_OPERATION,
+  sandboxRunEnvironment,
+  type WorkspaceExecuteOptions,
+  type WorkspaceExecutor,
+} from "@aicontainer/workspace-executor";
+import {
+  workspaceClientContracts,
+  workspaceClientProgressSchema,
+  workspaceContracts,
+  type WorkspaceClientDescription,
+  type WorkspaceClientInfo,
+} from "../contract.js";
+
+interface ClientEntry {
+  info: WorkspaceClientInfo;
+  owner: string | null;
+  connection: MethodConnection;
+  release: () => void;
+}
+
+/** Die einzige Grenze gegen einen hängenden Arbeitsplatz; seine eigenen Zeitgrenzen hat der Executor. */
+const CLIENT_TIMEOUT_MS = 15 * 60 * 1000;
+
+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;
+};
+
+const timeoutFor = (input: unknown): number =>
+  CLIENT_TIMEOUT_MS + ((input as { timeout?: number } | null | undefined)?.timeout ?? 0) * 1000;
+
+/** Bricht die Verbindung mitten im Aufruf, muss die Ursache den Arbeitsplatz nennen, nicht den Server. */
+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.timeout) {
+    return new DomainError("workspace-client-timeout", `Der Arbeitsplatz ${label} hat nicht geantwortet: ${cause.message}`, 504);
+  }
+  return cause;
+};
+
+/** Kennt die angemeldeten Arbeitsplätze und hält je Client die Verbindung, über die der Server ihn zurückruft. */
+export class WorkspaceClientRegistry {
+  readonly #clients = new Map<string, ClientEntry>();
+
+  async register(
+    id: string,
+    description: WorkspaceClientDescription,
+    executor: string,
+    connection: MethodConnection,
+  ): Promise<WorkspaceClientInfo> {
+    if (connection.streamless) {
+      throw new DomainError("stream-required", "Die Anmeldung eines Arbeitsplatzes braucht einen Ereignisstrom.", 409);
+    }
+    if (executor !== WORKSPACE_EXECUTOR_VERSION) {
+      throw new DomainError(
+        "workspace-executor-version",
+        `Der Arbeitsplatz ${description.label} bringt den Executor ${executor} mit, der Server verlangt ${WORKSPACE_EXECUTOR_VERSION}.`,
+        409,
+      );
+    }
+    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 info: WorkspaceClientInfo = { ...description, id };
+    const release = connection.onClose(() => this.#disconnected(id, connection));
+    this.#clients.set(id, { info, owner, connection, release });
+    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);
+  }
+
+  list(): WorkspaceClientInfo[] {
+    return [...this.#clients.values()].map((entry) => entry.info);
+  }
+
+  info(id: string): WorkspaceClientInfo | undefined {
+    return this.#clients.get(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> => {
+      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;
+      } catch (cause) {
+        throw withClientCause(cause, label);
+      }
+    };
+    return {
+      version: WORKSPACE_EXECUTOR_VERSION,
+      execute: (runId, tool, input, options = {}) => call(runId, tool, input, options),
+      stopRun: async (runId) => {
+        if (!this.#clients.has(id)) return;
+        await call(runId, WORKSPACE_STOP_OPERATION, null, {});
+      },
+      shutdown: async () => undefined,
+    };
+  }
+
+  shutdown(): void {
+    for (const entry of this.#clients.values()) entry.release();
+    this.#clients.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);
+  }
+}
+
+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));
+    return null;
+  }),
+];

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

@@ -0,0 +1,91 @@
+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 {
+  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";
+import { createBrowseChannel, createBrowseMethods } from "./browse-route.js";
+import { clientMethods, WorkspaceClientRegistry } from "./clients.js";
+import { RunWorkspaceRuntime } from "./runtime.js";
+
+const promptFile = pluginAssetPath(import.meta.url, "../prompt.hbs");
+
+const ragentsWorkspacePlugin = (skillPaths: () => Promise<readonly string[]>): RAgentsPlugin => ({
+  manifest: { id: "ragents.workspace" },
+  register: (host) => {
+    const sessionWorkspaceFor = host.service(sessionWorkspaceProviderToken);
+    const orchestration = host.service(runtimeProviderToken);
+    const runState = (runId: string): RunState | null => {
+      try {
+        return orchestration().state(runId);
+      } catch (error) {
+        if (error instanceof DomainError && error.code === "run-not-found") return null;
+        throw error;
+      }
+    };
+    const documentsFor = (runId: string): Promise<string | undefined> =>
+      host.optionalService(documentStoreToken)?.directoryFor(runId) ?? Promise.resolve(undefined);
+    const documentsRoot = async (runId: string): Promise<string> => {
+      const directory = await documentsFor(runId);
+      if (!directory) throw new Error("In diesem Profil gibt es keine Dateiablage; das Plugin ragents.documents fehlt");
+      return directory;
+    };
+    const clients = new WorkspaceClientRegistry();
+    const runtime = new RunWorkspaceRuntime({
+      clients,
+      globalDirectory: host.storage.root(),
+      sessionDirectory: (runId, ...segments) => host.storage.session(runId, ...segments),
+      sessionsDirectoryPattern: path.join(host.storage.sessionsRoot, "{runId}", "plugins", host.manifest.id),
+      sessionWorkspaceFor,
+      skillPaths,
+      resolver: () => host.optionalService(workspaceResolverToken),
+      runState,
+      storeBinding: (runId, binding) => {
+        const state = orchestration().state(runId);
+        orchestration().replacePluginState(
+          { actorId: state.ownerId, commandId: `workspace-binding:${runId}:${state.revision}` },
+          runId,
+          { pluginId: WORKSPACE_BINDING_OPTION_ID, scope: startOptionScope, state: binding as unknown as JsonValue },
+        );
+      },
+    });
+    host.provide(workspaceRuntimeToken, runtime);
+    host.provide(sandboxServicesToken, runtime.sandbox);
+    host.functions(runtime.sandbox.workspaceTools());
+    host.prompts(
+      handlebarsPrompt("ragents.workspace.prompt", 100, promptFile),
+      shellPlatformPrompt("ragents.workspace.shell.prompt", 102, (runId) => executorShellChapter(clients, bindingOf(runState(runId)))),
+    );
+    const browseOptions = {
+      ensureSession: host.service(sessionGuardToken),
+      rootFor: (runId: string, root: BrowseRoot) => root === "files"
+        ? documentsRoot(runId)
+        : sessionWorkspaceFor(runId).then((workspace) => workspace.currentRoot()),
+    };
+    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.lifecycle({
+      id: "ragents.workspace.lifecycle",
+      stopSession: ({ runId }) => runtime.stopSession(runId),
+      deleteSession: ({ runId }) => runtime.deleteSession(runId),
+      shutdown: () => runtime.shutdown(),
+    });
+  },
+});
+
+export const plugin: PluginModule = {
+  create: (host) => ragentsWorkspacePlugin(() => host.skills.global()),
+};