@schlenkr/ragents 0.1.5 → 0.1.6

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

@@ -1,92 +1,175 @@
 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 { DomainError, type JsonValue, type RunState, type StartOptionContribution } from "@ragents/engine";
+import { shellPlatformChapter } from "./shell-platform.js";
+import { storedStartOption } from "@ragents/host/ragents/start-option-state.js";
+import type { WorkspaceResolver } from "@ragents/host/ragents/workspace-runtime.js";
 import {
+  freshServerBinding,
+  FRESH_WORKSPACE_LABEL,
+  isFreshFolder,
   isWorkspaceBinding,
+  storedWorkspaceBinding,
   WORKSPACE_BINDING_OPTION_ID,
   workspaceBindingSummary,
+  type ExistingWorkspaceFolder,
+  type FreshWorkspaceLabels,
+  type FreshWorkstationFolder,
   type WorkspaceBinding,
   type WorkspaceBindingPresentation,
+  type WorkspaceClientInfo,
   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 machineSchema = Type.Union([
+  Type.Literal("server"),
+  Type.Object({ client: Type.String({ minLength: 8, maxLength: 64 }), label: Type.String() }, { additionalProperties: false }),
 ]);
 
+const folderSchema = Type.Union([
+  Type.Literal("fresh"),
+  Type.Object({ path: Type.String({ minLength: 1 }), fresh: Type.Optional(Type.Literal(true)) }, { additionalProperties: false }),
+]);
+
+const bindingSchema = Type.Object({ machine: machineSchema, folder: folderSchema }, { additionalProperties: false });
+
+/** Ein Run auf einem Arbeitsplatz mit dessen Kennung, Label und dem Ordner dort; `fresh` trägt dann schon seinen Pfad. */
+export type WorkstationBinding = {
+  machine: { client: string; label: string };
+  folder: ExistingWorkspaceFolder | FreshWorkstationFolder;
+};
+
 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);
 };
 
+/** Der Ordner eines Runs unter dem Ordner, in dem ein Arbeitsplatz die neuen Ordner je Run anlegt; mit dessen Trennzeichen. */
+export const workstationRunFolder = (runsDirectory: string, runId: string): string => {
+  const separator = runsDirectory.includes("\\") ? "\\" : "/";
+  const root = runsDirectory.endsWith(separator) ? runsDirectory.slice(0, -separator.length) : runsDirectory;
+  return `${root}${separator}${runId}`;
+};
+
+/** Die Bindung eines Runs; ohne gespeicherte Wahl der neue Ordner auf dem Server, eine unlesbare sperrt den Run mit Ursache. */
 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;
+  if (stored === undefined) return freshServerBinding();
+  const binding = storedWorkspaceBinding(stored);
+  if (!binding || (binding.machine !== "server" && binding.folder === "fresh")) {
+    throw new Error(`Die gespeicherte Arbeitsbereich-Bindung ist ungültig: ${JSON.stringify(stored)}`);
+  }
+  return binding;
 };
 
-/** Der Ordner auf dem Serverrechner, an den der Run gebunden ist; `fresh` und `client` liegen nicht dort. */
+export const isWorkstationBinding = (binding: WorkspaceBinding): binding is WorkstationBinding =>
+  binding.machine !== "server" && binding.folder !== "fresh";
+
+/** Ein Run benutzt nur Arbeitsplätze seines Eigentümers, ein Run ohne Eigentümer nur ohne Benutzer angemeldete. */
+export const workspaceOwnerOf = (state: RunState | null): string | null => state?.ownerUserId ?? null;
+
+/** Der vorhandene Ordner auf dem Serverrechner, an den der Run gebunden ist; ein neuer Ordner und ein Arbeitsplatz liegen nicht dort. */
 export const boundServerDirectory = (state: RunState | null): string | null => {
-  const binding = bindingOf(state);
-  return binding.kind === "path" ? binding.path : null;
+  const { machine, folder } = bindingOf(state);
+  return machine === "server" && folder !== "fresh" ? folder.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" }> => {
+/** Ein vorhandener Ordner dieses Servers; dieselbe Prüfung wie beim Wählen der Startoption. */
+export const serverDirectoryFolder = (directory: string): ExistingWorkspaceFolder => {
   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 };
+  return { 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);
+export const executorShellChapter = (registry: WorkspaceClientRegistry, owner: string | null, binding: WorkspaceBinding): string => {
+  const { machine } = binding;
+  if (machine === "server") return shellPlatformChapter(process.platform);
+  const client = registry.info(owner, machine.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, `
+    : `## Shell platform\n\nThe workstation ${machine.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 => {
+/** Wo die Wurzel eines Runs liegt, in Worten: bei einem Arbeitsplatz mit dessen Label, sonst der Pfad selbst. */
+export const workspaceLocation = (binding: WorkspaceBinding, location: string): string =>
+  binding.machine === "server" ? location : `Arbeitsplatz ${binding.machine.label}: ${location}`;
+
+/** Den neuen Ordner je Run stellt der Beitrag, sobald es einen gibt; auf einem Arbeitsplatz nur, wenn er es dort ausdrücklich kann. */
+export const freshLabels = (contribution: WorkspaceResolver | undefined): FreshWorkspaceLabels => ({
+  server: contribution?.kind?.label ?? FRESH_WORKSPACE_LABEL,
+  client: contribution ? contribution.workstation?.label ?? null : FRESH_WORKSPACE_LABEL,
+});
+
+export const sessionMetadataOf = (state: RunState | null, contribution: WorkspaceResolver | undefined): WorkspaceSessionMetadata => {
   const binding = bindingOf(state);
-  return { binding, summary: workspaceBindingSummary(binding) };
+  return { binding, summary: workspaceBindingSummary(binding, freshLabels(contribution)) };
+};
+
+const unsupported = (message: string): DomainError => new DomainError("workspace-binding-unsupported", message, 400);
+
+/** Ein Arbeitsplatz des Handelnden, der den Ordner anbietet; ein neuer Ordner je Run bekommt dort seinen Pfad unter dessen Ordner für Runs. */
+const workstationBinding = (
+  client: WorkspaceClientInfo,
+  folder: WorkspaceBinding["folder"],
+  runId: string,
+  labels: FreshWorkspaceLabels,
+): WorkstationBinding => {
+  const machine = { client: client.id, label: client.label };
+  if (isFreshFolder(folder)) {
+    if (labels.client === null) {
+      throw unsupported(`Einen neuen Ordner je Run gibt es hier nur auf dem Server (${labels.server}); wähle dort einen oder einen vorhandenen Ordner des Arbeitsplatzes.`);
+    }
+    return { machine, folder: { path: workstationRunFolder(client.runsDirectory, runId), fresh: true } };
+  }
+  if (!client.folders.some((offered) => insideFolder(offered, folder.path))) {
+    throw new DomainError("workspace-client-folder", `Der Arbeitsplatz ${client.label} bietet den Ordner ${folder.path} nicht an.`, 400);
+  }
+  return { machine, folder: { path: folder.path } };
 };
 
-export const workspaceBindingOption = (registry: WorkspaceClientRegistry): StartOptionContribution => ({
+export const workspaceBindingOption = (
+  registry: WorkspaceClientRegistry,
+  contribution: () => WorkspaceResolver | undefined,
+): StartOptionContribution => ({
   id: WORKSPACE_BINDING_OPTION_ID,
   schema: bindingSchema,
   selectable: () => true,
-  defaultValue: () => ({ kind: "fresh" }),
-  accept: (value) => {
+  defaultValue: () => freshServerBinding(),
+  accept: (value, { runId, userId }) => {
     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);
+    const labels = freshLabels(contribution());
+    const { machine, folder } = value;
+    if (machine === "server") {
+      if (folder === "fresh") return freshServerBinding();
+      if ("fresh" in folder) throw new DomainError("workspace-binding-invalid", "Einen neuen Ordner je Run legt auf dem Server der Host an; er hat keinen gewählten Pfad.", 400);
+      if (!(contribution()?.kind?.serverFolders ?? true)) {
+        throw unsupported(`Ein vorhandener Ordner auf dem Serverrechner ist hier keine Bindung; wähle ${labels.server} oder einen Arbeitsplatz.`);
+      }
+      return { machine, folder: serverDirectoryFolder(folder.path) };
     }
-    return { kind: "client", client: client.id, label: client.label, path: value.path };
+    const client = registry.info(userId, machine.client);
+    if (!client) throw new DomainError("workspace-client-disconnected", `Der Arbeitsplatz ${machine.label || machine.client} ist nicht verbunden.`, 409);
+    return workstationBinding(client, folder, runId, labels);
   },
-  describe: () => {
-    const presentation: WorkspaceBindingPresentation = { kind: "workspace-binding", clients: registry.list() };
+  describe: (_value, { userId }) => {
+    const presentation: WorkspaceBindingPresentation = {
+      kind: "workspace-binding",
+      clients: registry.list(userId),
+      fresh: freshLabels(contribution()),
+      serverFolders: contribution()?.kind?.serverFolders ?? true,
+    };
     return presentation as unknown as JsonValue;
   },
+  ownerOnly: (value) => {
+    const binding = storedWorkspaceBinding(value);
+    return binding !== undefined && binding.machine !== "server";
+  },
 });

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

@@ -1,134 +1,127 @@
-import { watch } from "node:fs";
-import { lstat, readdir, readFile, realpath } from "node:fs/promises";
-import path from "node:path";
 import {
-  DomainError,
   implement,
   implementChannel,
+  type AccessContext,
   type ChannelContribution,
   type MethodContribution,
-} from "@aicontainer/ragents";
+} from "@ragents/engine";
+import {
+  FILE_OPERATIONS,
+  listDirectory,
+  readTextFile,
+  watchDirectory,
+  type FileListing,
+  type FileText,
+  type FileWatchProgress,
+} from "@ragents/workspace-executor";
+import { withDomainCause, type SandboxServices } from "@ragents/host/plugin-support/workspace-sandbox-host.js";
 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("/");
-};
+export interface BrowseOptions {
+  ensureSession: (runId: string) => void;
+  /** Der Arbeitsbereich eines Runs, den nur sein Eigentümer bedient, liegt bei ihm; die Dateiablage des Servers nicht. */
+  ensureWorkspaceAccess: (access: AccessContext, runId: string) => void;
+  /** Der Arbeitsbereich ist nur über den Executor des Runs erreichbar, wo immer er liegt. */
+  execute: SandboxServices["execute"];
+  /** Die Dateiablage liegt auf dem Server und gehört nicht zum Arbeitsbereich. */
+  documentsFor: (runId: string) => Promise<string>;
+  /** Wie die Wurzel eines Runs heißt, etwa mit dem Label seines Arbeitsplatzes. */
+  locationOf: (runId: string, location: string) => string;
+}
 
-const realOf = async (target: string, missing: string): Promise<string> => {
+const onServer = async <T>(operation: () => Promise<T>): Promise<T> => {
   try {
-    return await realpath(target);
-  } catch {
-    throw new DomainError("browse-not-found", missing, 404);
+    return await operation();
+  } catch (error) {
+    throw withDomainCause(error);
   }
 };
 
-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 listingOf = async (options: BrowseOptions, runId: string, root: BrowseRoot, target: string): Promise<BrowseListing> => {
+  if (root === "files") {
+    const listing = await onServer(async () => listDirectory(await options.documentsFor(runId), target));
+    return { root, ...listing };
+  }
+  const listing = await options.execute(runId, FILE_OPERATIONS.list, { path: target }) as FileListing;
+  return { root, ...listing, location: options.locationOf(runId, listing.location) };
 };
 
-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 (options: BrowseOptions, runId: string, root: BrowseRoot, target: string): Promise<BrowsePreview> => {
+  const text = root === "files"
+    ? await onServer(async () => readTextFile(await options.documentsFor(runId), target))
+    : await options.execute(runId, FILE_OPERATIONS.read, { path: target }) as FileText;
+  return { root, ...text };
 };
 
-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") };
+const ensureRoot = (options: BrowseOptions, access: AccessContext, runId: string, root: BrowseRoot): void => {
+  if (root === "workspace") options.ensureWorkspaceAccess(access, runId);
+  else options.ensureSession(runId);
 };
 
-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.list, ({ runId, root, path: target }, { access }) => {
+    ensureRoot(options, access, runId, root);
+    return listingOf(options, runId, root, target);
   }),
-  implement(workspaceContracts.browse.preview, async ({ runId, root, path: target }) => {
-    options.ensureSession(runId);
-    return previewOf(await options.rootFor(runId, root), relativeOf(target), root);
+  implement(workspaceContracts.browse.preview, ({ runId, root, path: target }, { access }) => {
+    ensureRoot(options, access, runId, root);
+    return previewOf(options, runId, root, target);
   }),
 ];
 
-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);
+/** Nach dem Ende einer laufenden Beobachtung, etwa weil der Arbeitsplatz weg war, versucht der Kanal es in diesem Abstand erneut. */
+const WATCH_RETRY_MS = 5_000;
+
+/** Beobachtet den Arbeitsbereich beim Executor des Runs bis zum Abbruch; steht die Beobachtung, ist der Kanal offen, und endet sie, beginnt er eine neue. */
+const watchWorkspace = (options: BrowseOptions, runId: string, changed: () => void): Promise<() => void> =>
+  new Promise((ready, failed) => {
+    const controller = new AbortController();
+    let opened = false;
+    let retry: NodeJS.Timeout | undefined;
+    const stop = (): void => {
+      controller.abort();
+      clearTimeout(retry);
     };
-    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();
+    const start = (): void => {
+      let watching = false;
+      const ended = (error?: unknown): void => {
+        if (controller.signal.aborted) return;
+        if (!opened) {
+          failed(error ?? new Error("Die Beobachtung des Arbeitsbereichs endete, bevor sie stand"));
+          return;
+        }
+        // Endet eine laufende Beobachtung, lädt die Ansicht neu und zeigt die Ursache; steht die nächste, lädt sie noch einmal.
+        if (watching) changed();
+        retry = setTimeout(start, WATCH_RETRY_MS);
+      };
+      options.execute(runId, FILE_OPERATIONS.watch, {}, {
+        signal: controller.signal,
+        untilAborted: true,
+        onProgress: (value) => {
+          if ((value as FileWatchProgress).kind === "changed") changed();
+          else if (!watching) {
+            watching = true;
+            if (opened) changed();
+            else {
+              opened = true;
+              ready(stop);
+            }
+          }
+        },
+      }).then(() => ended(), ended);
     };
+    start();
+  });
+
+export const createBrowseChannel = (options: BrowseOptions): ChannelContribution =>
+  implementChannel(workspaceContracts.channels.browse, async ({ runId, root }, emit, { access }) => {
+    ensureRoot(options, access, runId, root);
+    const changed = (): void => emit({ changed: true });
+    if (root === "workspace") return watchWorkspace(options, runId, changed);
+    return onServer(async () => watchDirectory(await options.documentsFor(runId), { onChange: changed, onError: changed }));
   });