@schlenkr/ragents 0.1.5 → 0.1.7

package/apps/server/src/plugin-support/workspace-sandbox-host.ts

@@ -1,33 +1,40 @@
-import { realpath } from "node:fs/promises";
+import { mkdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import {
+  DomainError,
   serviceToken,
   type RunFunction,
   type PluginContext,
   type ToolContributor,
-} from "@aicontainer/ragents";
+  type ToolScope,
+} from "@ragents/engine";
 import {
   createBashToolDefinition,
   createEditToolDefinition,
   createReadToolDefinition,
   createWriteToolDefinition,
-} from "@aicontainer/agent";
+} from "@ragents/agent";
 import {
-  SandboxWorkspaceExecutor,
+  WorkspaceOperationError,
+  WorkspaceOperationExecutor,
   resolvedWorkspacePath,
   sandboxRunEnvironment,
-  workspaceLanguageServers,
+  workspaceExecutorModules,
   workspaceProcessContext,
+  type AddressedRoots,
   type ResolvedWorkspaceRoot,
   type SandboxHomeEnvironment,
+  type SeenFile,
   type SessionIdent,
   type WorkspaceExecuteOptions,
   type WorkspaceExecutor,
   type WorkspaceProcessContext,
-} from "@aicontainer/workspace-executor";
+} from "@ragents/workspace-executor";
 import { hostRoot } from "../host-version.js";
-import type { SessionWorkspace } from "../ragents/workspace-runtime.js";
-import { agentToolFrom, toolDescriptorFrom, type AgentToolDefinition } from "./agent-tool.js";
+import type { SandboxFolder, SessionWorkspace } from "../ragents/workspace-runtime.js";
+import { agentToolFrom, textOf, toolDescriptorFrom, type AgentToolDefinition, type ToolOutput } from "./agent-tool.js";
+import type { RunProcessSandboxes } from "./process-sandbox.js";
+import { SKILLS_ALIAS, skillRootAlias } from "./skills.js";
 import { alwaysAvailable } from "./tool-availability.js";
 import { syncWorkspaceOwnership } from "./workspace-ownership.js";
 
@@ -39,13 +46,26 @@ export interface RegisteredWorkspaceRoot {
   ownershipDirectoryFor?: (runId: string) => string | Promise<string>;
 }
 
+/** Eine Wurzel des Servers, wie ein Prompt sie nennt: ihr Alias, ob Werkzeuge darin schreiben dürfen, und die Variable, die sie in einer Bash auf dem Server nennt. */
+export interface ServerRootDescription {
+  readonly alias: string;
+  readonly writable: boolean;
+  readonly environmentVariable?: string;
+}
+
+/** Der einzige Zugang der Plugins zum Arbeitsbereich eines Runs: eine Operation läuft beim Executor der Maschine, der die angesprochene Wurzel gehört. */
 export interface SandboxServices {
-  processContextFor: (runId: string) => Promise<WorkspaceProcessContext>;
+  execute: (runId: string, operation: string, input: unknown, options?: WorkspaceExecuteOptions) => Promise<unknown>;
+  /** Der Kontext für Arbeit, die auf dem Server läuft (TypeScript-Plattform, Actor-Programme); nie der Ordner eines Arbeitsplatzes. */
+  serverProcessContextFor: (runId: string) => Promise<WorkspaceProcessContext>;
   registerWorkspaceRoot: (root: RegisteredWorkspaceRoot) => void;
-  execute: (runId: string, tool: string, input: unknown, options?: WorkspaceExecuteOptions) => Promise<unknown>;
   shutdown: (runId: string) => Promise<void>;
 }
 
+/** Ein fachlicher Fehler des Executors sieht beim Aufrufer aus wie jeder andere Fehler des Servers. */
+export const withDomainCause = (error: unknown): unknown =>
+  error instanceof WorkspaceOperationError ? new DomainError(error.code, error.message, error.status) : error;
+
 export const sandboxServicesToken = serviceToken<SandboxServices>("ragents.workspace.sandbox-services");
 
 export interface WorkspaceSandboxHostOptions {
@@ -55,15 +75,21 @@ export interface WorkspaceSandboxHostOptions {
   skillPaths: () => Promise<readonly string[]>;
   homeFor: (runId: string) => Promise<SandboxHomeEnvironment>;
   storageRootFor?: (runId: string) => string;
-  /** Der Executor des Runs; ohne Antwort führt der Executor des Servers aus. */
+  /** Der Executor eines Runs, der nicht auf dem Server arbeitet; ohne Antwort führt der Executor des Servers aus. */
   executorFor?: (runId: string) => Promise<WorkspaceExecutor | undefined>;
+  /** Der eigene Ordner eines solchen Runs auf dem Server, für Arbeit, die dort läuft. */
+  serverDirectoryFor?: (runId: string) => Promise<string>;
+  /** Die Prozess-Sandbox, in der jeder Prozess des Executors dieses Servers startet; ohne sie laufen Prozesse ohne. */
+  processSandbox?: RunProcessSandboxes;
+  /** Die Bash des Executors dieses Servers; unter Windows Pflicht, sonst ohne Angabe die des Systems. */
+  bash?: string;
 }
 
 const sandboxDescriptions: Readonly<Record<string, string>> = {
   read: "Read file contents or images within the run's allowed workspace roots.",
   edit: "Apply exact text replacements to existing files within the run's writable workspace roots.",
   write: "Create or overwrite files within the run's writable workspace roots.",
-  bash: "Execute shell commands in the run's workspace with sandbox restrictions.",
+  bash: "Execute shell commands in the run's workspace, or with cwd in one of its roots, with sandbox restrictions.",
 };
 
 const describeSandboxTool = (definition: AgentToolDefinition): AgentToolDefinition => {
@@ -82,24 +108,51 @@ const sandboxDescriptorDefinitions = [
 const sandboxDescriptors = sandboxDescriptorDefinitions.map((definition) =>
   toolDescriptorFrom(describeSandboxTool(definition), alwaysAvailable));
 
+const fileToolNames = new Set(["read", "edit", "write"]);
+
 interface StableRunParts {
   ident?: SessionIdent;
   home: SandboxHomeEnvironment;
   readOnlyRoots: readonly ResolvedWorkspaceRoot[];
+  /** Der eigene Temp-Ordner des Runs in der Sandbox. */
+  temporary?: string;
 }
 
-/** Der Executor des Servers, seine Wurzeln und die Weiterreichung der Arbeitsplatz-Werkzeuge an den Executor des Runs. */
+const mixedRoots = (aliases: readonly string[]): DomainError => new DomainError(
+  "workspace-roots-mixed",
+  `Der Aufruf nennt ${aliases.join(", ")} auf dem Server und zugleich einen Pfad im Arbeitsbereich auf dem Arbeitsplatz; `
+    + "ein Aufruf erreicht nur einen Rechner. Teile ihn in einen Aufruf je Rechner.",
+  400,
+);
+
+/** Die Ordner, die ein Arbeitsbereich der Prozess-Sandbox zusätzlich öffnet, getrennt nach Zugriff; ein relativer Pfad hätte auf dem Server keinen Ort. */
+const sandboxFoldersWith = (folders: readonly SandboxFolder[], access: SandboxFolder["access"]): string[] =>
+  folders.filter((folder) => folder.access === access).map((folder) => {
+    if (!path.isAbsolute(folder.directory)) throw new Error(`Der Ordner ${folder.directory} für die Prozess-Sandbox muss absolut sein`);
+    return folder.directory;
+  });
+
+/** Ein nur lesbarer Pfad, den es nicht gibt, ist keine Wurzel; ein fehlender Skill-Ordner darf keinen Run verhindern. */
+const existingRoots = async (roots: readonly ResolvedWorkspaceRoot[]): Promise<ResolvedWorkspaceRoot[]> => {
+  const resolved = await Promise.all(roots.map((root) =>
+    realpath(root.directory).then((directory) => ({ ...root, directory }), () => undefined)));
+  return resolved.filter((root) => root !== undefined);
+};
+
+/** Der Executor des Servers mit den Wurzeln des Servers; eine Operation mit Alias läuft dort, jede andere beim Executor der Bindung des Runs. */
 export class WorkspaceSandboxHost implements SandboxServices {
   readonly #options: WorkspaceSandboxHostOptions;
   readonly #workspaceRoots: RegisteredWorkspaceRoot[] = [];
-  readonly #local: SandboxWorkspaceExecutor;
+  readonly #local: WorkspaceOperationExecutor;
   readonly #stable = new Map<string, Promise<StableRunParts>>();
+  /** Je Run der Dateistand, den ein Modell zuletzt gesehen hat, nach Actor, Modellkontext und Pfad; nur im Speicher, ein Verlust verlangt höchstens ein neues read. */
+  readonly #seen = new Map<string, Map<string, SeenFile>>();
 
   constructor(options: WorkspaceSandboxHostOptions) {
     this.#options = options;
-    this.#local = new SandboxWorkspaceExecutor({
-      contextFor: (runId) => this.processContextFor(runId),
-      languageServers: workspaceLanguageServers,
+    this.#local = new WorkspaceOperationExecutor({
+      contextFor: (runId) => this.serverProcessContextFor(runId),
+      modules: workspaceExecutorModules(),
     });
   }
 
@@ -107,8 +160,9 @@ export class WorkspaceSandboxHost implements SandboxServices {
     if (!root.id.trim() || this.#workspaceRoots.some((entry) => entry.id === root.id)) {
       throw new Error(`Arbeitsverzeichnis ${root.id} ist leer oder bereits registriert`);
     }
-    if (root.alias && (!/^@[a-z][a-z0-9-]*$/.test(root.alias) || this.#workspaceRoots.some((entry) => entry.alias === root.alias))) {
-      throw new Error(`Arbeitsverzeichnis-Alias ${root.alias} ist ungültig oder bereits registriert`);
+    if (root.alias && (!/^@[a-z][a-z0-9-]*$/.test(root.alias) || root.alias === SKILLS_ALIAS
+      || this.#workspaceRoots.some((entry) => entry.alias === root.alias))) {
+      throw new Error(`Arbeitsverzeichnis-Alias ${root.alias} ist ungültig, dem Host vorbehalten oder bereits registriert`);
     }
     if (root.environmentVariable && (!/^RAGENTS_[A-Z_]+_DIR$/.test(root.environmentVariable) || this.#workspaceRoots.some((entry) => entry.environmentVariable === root.environmentVariable))) {
       throw new Error(`Arbeitsverzeichnis-Variable ${root.environmentVariable} ist ungültig oder bereits registriert`);
@@ -129,24 +183,71 @@ export class WorkspaceSandboxHost implements SandboxServices {
     return roots.filter((root) => root !== undefined);
   }
 
-  async processContextFor(runId: string): Promise<WorkspaceProcessContext> {
+  /** Die Wurzeln des Servers mit Alias, die ein Run neben seinem Arbeitsbereich erreicht: die registrierten und die Skill-Ordner. */
+  async serverRoots(): Promise<readonly ServerRootDescription[]> {
+    const registered = this.#workspaceRoots.flatMap(({ alias, environmentVariable }) => alias === undefined ? [] : [{
+      alias, writable: true, ...(environmentVariable === undefined ? {} : { environmentVariable }),
+    }]);
+    const skills = (await this.#options.skillPaths()).length > 0 ? [{ alias: SKILLS_ALIAS, writable: false }] : [];
+    return [...registered, ...skills];
+  }
+
+  /** Bei einem Run mit eigenem Executor ein Ordner des Runs auf dem Server, sonst derselbe Kontext wie für seine Werkzeuge. */
+  async serverProcessContextFor(runId: string): Promise<WorkspaceProcessContext> {
+    if (!await this.#options.executorFor?.(runId)) return this.#contextFor(runId);
+    const serverDirectoryFor = this.#options.serverDirectoryFor;
+    if (!serverDirectoryFor) throw new Error(`Der Run ${runId} arbeitet nicht auf dem Server, und der Sandbox-Host kennt keinen Serverordner für ihn`);
+    return this.#contextFor(runId, await serverDirectoryFor(runId));
+  }
+
+  /** Der Kontext des Executors dieses Servers; ohne eigenen Ordner der Arbeitsbereich selbst, der dafür auf dem Server liegen muss. */
+  async #contextFor(runId: string, serverDirectory?: string): Promise<WorkspaceProcessContext> {
     const workspace = await this.#options.workspaceFor(runId);
-    const { ident, home, readOnlyRoots } = await this.#stableParts(runId, workspace);
+    const { ident, home, readOnlyRoots, temporary } = await this.#stableParts(runId, workspace);
+    const root = serverDirectory ?? await workspace.currentRoot();
+    const additionalRoots = await this.#additionalRoots(runId, ident);
+    const folders = workspace.sandboxFolders ?? [];
+    const sandbox = this.#options.processSandbox && temporary !== undefined
+      ? this.#options.processSandbox.forRun({
+        writable: [
+          root, ...additionalRoots.map((entry) => entry.directory), home.home, ...home.nugetPackages ? [home.nugetPackages] : [],
+          ...sandboxFoldersWith(folders, "write"),
+        ],
+        readable: [
+          ...readOnlyRoots.map((entry) => entry.directory), ...this.#options.storageRootFor ? [this.#options.storageRootFor(runId)] : [],
+          ...sandboxFoldersWith(folders, "read"),
+        ],
+        temporary,
+      })
+      : undefined;
     return workspaceProcessContext({
       runId,
-      cwd: workspace.cwd,
-      root: await workspace.currentRoot(),
+      cwd: serverDirectory ?? workspace.cwd,
+      root,
       home,
       logDirectory: home.home,
       hostRoot: hostRoot(),
       ...(ident ? { ident } : {}),
-      additionalRoots: await this.#additionalRoots(runId, ident),
+      additionalRoots,
       readOnlyRoots,
       additions: sandboxRunEnvironment(runId, workspace),
       runOperation: workspace.runOperation,
+      ...(sandbox ? { sandbox } : {}),
+      ...(this.#options.bash === undefined ? {} : { bash: this.#options.bash }),
     });
   }
 
+  /** Der Temp-Ordner eines Runs liegt in seiner Ablage, damit er mit dem Run verschwindet und kein anderer Run ihn sieht. */
+  async #temporaryFor(runId: string, ident: SessionIdent | undefined): Promise<string | undefined> {
+    if (!this.#options.processSandbox) return undefined;
+    const storageRoot = this.#options.storageRootFor?.(runId);
+    if (!storageRoot) throw new Error(`Die Prozess-Sandbox braucht die Ablage des Runs ${runId} für seinen Temp-Ordner`);
+    const directory = path.join(storageRoot, "tmp");
+    await mkdir(directory, { recursive: true });
+    if (ident) await syncWorkspaceOwnership(directory, { ...ident, storageRoot });
+    return realpath(directory);
+  }
+
   /** Kennung, Heimatordner und nur lesbare Wurzeln stehen je Run fest; nur sie werden gemerkt. */
   #stableParts(runId: string, workspace: SessionWorkspace): Promise<StableRunParts> {
     const known = this.#stable.get(runId);
@@ -161,17 +262,27 @@ export class WorkspaceSandboxHost implements SandboxServices {
 
   async #resolveStableParts(runId: string, workspace: SessionWorkspace): Promise<StableRunParts> {
     if (workspace.hostSandbox) {
-      const readOnlyRoots = await Promise.all(workspace.hostSandbox.readOnlyRoots.map(async (root) =>
-        ({ ...root, directory: await realpath(root.directory) })));
-      return { home: { home: workspace.hostSandbox.home }, readOnlyRoots };
+      const { home, ident } = workspace.hostSandbox;
+      const temporary = await this.#temporaryFor(runId, ident);
+      return {
+        ...(ident ? { ident } : {}),
+        home: { home },
+        readOnlyRoots: await existingRoots(workspace.hostSandbox.readOnlyRoots),
+        ...(temporary ? { temporary } : {}),
+      };
     }
     const [ident, home, skills] = await Promise.all([
       this.#options.identFor(runId),
       this.#options.homeFor(runId),
       this.#options.skillPaths(),
     ]);
-    const resolved = await Promise.all(skills.map((directory) => realpath(directory).then((real) => ({ directory: real }), () => undefined)));
-    return { ...(ident ? { ident } : {}), home, readOnlyRoots: resolved.filter((root) => root !== undefined) };
+    const temporary = await this.#temporaryFor(runId, ident);
+    return {
+      ...(ident ? { ident } : {}),
+      home,
+      readOnlyRoots: await existingRoots(skills.map((directory) => ({ directory, alias: skillRootAlias(path.basename(directory)) }))),
+      ...(temporary ? { temporary } : {}),
+    };
   }
 
   workspaceTools(): ToolContributor {
@@ -182,23 +293,40 @@ export class WorkspaceSandboxHost implements SandboxServices {
     };
   }
 
-  execute(runId: string, tool: string, input: unknown, options: WorkspaceExecuteOptions = {}): Promise<unknown> {
-    return this.#executorFor(runId).then((executor) => executor.execute(runId, tool, input, options));
+  /** Die Laufzeit, die eine Eingabe selbst verlangt, gilt, wenn der Aufrufer keine nennt; sie verlängert nur das Warten auf einen entfernten Executor. */
+  async execute(runId: string, operation: string, input: unknown, options: WorkspaceExecuteOptions = {}): Promise<unknown> {
+    try {
+      const { roots, durationMs } = this.#local.footprintOf(operation, input);
+      const executor = await this.#executorFor(runId, roots);
+      const timed = options.durationMs === undefined && durationMs !== undefined ? { ...options, durationMs } : options;
+      return await executor.execute(runId, operation, input, timed);
+    } catch (error) {
+      throw withDomainCause(error);
+    }
   }
 
-  /** Ein Run mit Bindung `client` legt im Server nie eine Sandbox an; sein Executor allein hält, was zu beenden ist. */
+  /** Auch ein Run mit eigenem Executor hat auf dem Server markierte Prozesse der TypeScript-Plattform; beide Executoren räumen ab. */
   async shutdown(runId: string): Promise<void> {
     this.#stable.delete(runId);
-    await (await this.#executorFor(runId)).stopRun(runId);
+    this.#seen.delete(runId);
+    const remote = await this.#options.executorFor?.(runId);
+    const results = await Promise.allSettled([this.#local.stopRun(runId), ...(remote ? [remote.stopRun(runId)] : [])]);
+    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+    if (failed) throw failed.reason;
   }
 
   shutdownAll(): Promise<void> {
     this.#stable.clear();
+    this.#seen.clear();
     return this.#local.shutdown();
   }
 
-  async #executorFor(runId: string): Promise<WorkspaceExecutor> {
-    return await this.#options.executorFor?.(runId) ?? this.#local;
+  /** Aliasse nennen Wurzeln des Servers, jeder andere Pfad die Wurzel des Runs auf der Maschine seiner Bindung; ohne Alias entscheidet die Bindung. */
+  async #executorFor(runId: string, { aliases, runRoot }: AddressedRoots): Promise<WorkspaceExecutor> {
+    const bound = await this.#options.executorFor?.(runId);
+    if (!bound || aliases.length === 0) return bound ?? this.#local;
+    if (runRoot) throw mixedRoots(aliases);
+    return this.#local;
   }
 
   #workspaceToolsFor(context: PluginContext): Promise<RunFunction[]> {
@@ -207,9 +335,28 @@ export class WorkspaceSandboxHost implements SandboxServices {
       const proxy = {
         ...described,
         execute: (toolCallId: string, params: unknown, signal: AbortSignal | undefined) =>
-          this.execute(context.runId, described.name, params, { toolCallId, ...(signal ? { signal } : {}) }),
+          this.execute(context.runId, described.name, params, {
+            toolCallId,
+            ...(signal ? { signal } : {}),
+          }),
       } as AgentToolDefinition;
-      return agentToolFrom(proxy, alwaysAvailable, described.name === "bash" ? "sequential" : "parallel");
+      const tool = agentToolFrom(proxy, alwaysAvailable, described.name === "bash" ? "sequential" : "parallel");
+      return fileToolNames.has(described.name)
+        ? { ...tool, run: (scope: ToolScope, toolCallId: string, input: never) => this.#fileToolCall(context.runId, described.name, scope, toolCallId, input) }
+        : tool;
     }));
   }
+
+  /** Ein direkter Aufruf des Modells gibt den Stand mit, den es von der Datei gesehen hat, und merkt sich den neuen; ein Aufruf aus TypeScript arbeitet ohne. */
+  async #fileToolCall(runId: string, name: string, scope: ToolScope, toolCallId: string, input: { path: string }): Promise<string> {
+    const options = { toolCallId, ...(scope.signal ? { signal: scope.signal } : {}) };
+    if (scope.modelContext === undefined) return textOf(await this.execute(runId, name, input, options) as ToolOutput);
+    const known = this.#seen.get(runId) ?? new Map<string, SeenFile>();
+    const key = [scope.caller.actorId, scope.modelContext, path.posix.normalize(input.path)].join("\0");
+    const result = await this.execute(runId, name, { ...input, seen: known.get(key) ?? null }, options) as ToolOutput & { details?: { seen?: SeenFile } };
+    const seen = result.details?.seen;
+    if (!seen) throw new Error(`Der Executor meldet nach ${name} keinen Dateistand; Server und Arbeitsplatz brauchen denselben Executor-Stand`);
+    this.#seen.set(runId, known.set(key, seen));
+    return textOf(result);
+  }
 }

package/apps/server/src/profile/bundle-manifest.ts

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { ragentsDataRoot } from "../data-directory.js";
+import { filesBelow } from "../folder-install.js";
+import { HOST_API_VERSION, type HostApiHalf } from "../host-api.js";
+import { hostRoot, type HostApiRecord } from "../host-version.js";
+import { isCheckout } from "../host-web.js";
+import { bundlesRoot, pluginIdOf } from "../plugin-support/plugins-root.js";
+
+export const BUNDLE_MANIFEST_FILE = "ragents-bundle.json";
+export const BUNDLE_FORMAT = 3;
+
+/** The value names a half imports from each module of the host API. */
+export type HostNames = Readonly<Record<string, readonly string[]>>;
+
+/** The one entry point of a bundle, written by the build tool and never by hand. */
+export interface BundleManifest {
+  readonly format: typeof BUNDLE_FORMAT;
+  readonly id: string;
+  readonly api: number;
+  /** The names of the host API the bundle uses, per half; a host that lacks one refuses the bundle. */
+  readonly hostNames: Readonly<Record<HostApiHalf, HostNames>>;
+  /** A hash over every file of the bundle; copies and the build tool check it. */
+  readonly stand: string;
+  /** A hash over the source folder and the host inputs of the build; a checkout compares it with its built-in plugins. */
+  readonly sourceStand: string;
+  readonly server: string;
+  readonly web?: { readonly entry: string; readonly css?: string; readonly classes: string };
+  readonly exports: Readonly<Record<HostApiHalf, Readonly<Record<string, string>>>>;
+  readonly uses: readonly string[];
+  readonly assets: readonly string[];
+}
+
+const MANIFEST_KEYS = new Set(["format", "id", "api", "hostNames", "stand", "sourceStand", "server", "web", "exports", "uses", "assets"]);
+const SOURCE_MARKERS = ["ragents-plugin.json", "server/index.ts", "server/index.tsx"];
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isStringList = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((entry) => typeof entry === "string");
+
+const isPathRecord = (value: unknown): value is Readonly<Record<string, string>> =>
+  isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+
+const isHostNames = (value: unknown): boolean =>
+  isRecord(value) && [value.server, value.web].every((half) => isRecord(half) && Object.values(half).every(isStringList));
+
+const isWeb = (value: unknown): boolean =>
+  value === undefined || (isRecord(value) && typeof value.entry === "string" && typeof value.classes === "string"
+    && (value.css === undefined || typeof value.css === "string"));
+
+const realFolder = (folder: string): string | undefined =>
+  existsSync(folder) ? realpathSync.native(folder) : undefined;
+
+/** A built-in bundle lies directly in the host's bundles folder; everything else comes from its author. */
+export const isBuiltInBundle = (folder: string, bundles = bundlesRoot): boolean => {
+  const root = realFolder(bundles);
+  return root !== undefined && path.dirname(realFolder(folder) ?? path.resolve(folder)) === root;
+};
+
+/** A bundle that ragents connect fetched lies below the remote folder of the data root; the server holds its sources. */
+export const isFetchedBundle = (folder: string, dataRoot = ragentsDataRoot()): boolean =>
+  path.resolve(folder).startsWith(path.join(dataRoot, "remote") + path.sep);
+
+/** How the author, or for a fetched bundle its user, gets a bundle that fits this host again. */
+export const rebuildHint = (folder: string): string => {
+  if (isBuiltInBundle(folder)) return "im Checkout mit pnpm build:plugins neu bauen";
+  if (isFetchedBundle(folder)) return "der Stand kommt von einem Server: mit ragents connect <server-url> neu holen, connect nennt die passende Host-Fassung";
+  return "mit ragents plugin build <quellordner> neu bauen";
+};
+
+const SKIPPED_SOURCE_ENTRIES = new Set(["node_modules", ".DS_Store"]);
+
+const sourceFiles = (folder: string, skipped: ReadonlySet<string>, prefix = ""): readonly string[] =>
+  readdirSync(folder, { withFileTypes: true })
+    .filter((entry) => !SKIPPED_SOURCE_ENTRIES.has(entry.name) && !skipped.has(path.join(folder, entry.name)))
+    .sort((left, right) => left.name.localeCompare(right.name, "en"))
+    .flatMap((entry) => {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) return sourceFiles(path.join(folder, entry.name), skipped, relative);
+      return entry.isFile() ? [relative] : [];
+    });
+
+const fileDigest = (file: string): string => createHash("sha256").update(readFileSync(file)).digest("hex");
+
+/** Host files that shape every bundle besides its sources: the build tool, the host API and the versions of the bundled libraries. */
+const buildInputsOf = (root: string): readonly string[] => [
+  "apps/server/src/host-api.ts",
+  "apps/server/src/host-api.json",
+  "apps/server/src/plugin-build/build.ts",
+  "apps/server/src/plugin-build/plugin-description.ts",
+  isCheckout(root) ? "pnpm-lock.yaml" : "package.json",
+];
+
+/** A hash over every file of a plugin source folder except dependencies and the given output folders, together with the build inputs of the host. */
+export const sourceStandOf = (folder: string, skipped: readonly string[] = [], root = hostRoot()): string => {
+  const hash = createHash("sha256");
+  for (const relative of sourceFiles(folder, new Set(skipped))) hash.update(`${relative}\0${fileDigest(path.join(folder, relative))}\n`);
+  for (const input of buildInputsOf(root)) hash.update(`host:${input}\0${fileDigest(path.join(root, input))}\n`);
+  return hash.digest("hex");
+};
+
+/** A hash over every file of the bundle except its manifest and what Finder leaves behind, stable across machines. */
+export const bundleStand = (folder: string): string => {
+  const hash = createHash("sha256");
+  const files = filesBelow(folder).filter((name) => name !== BUNDLE_MANIFEST_FILE && path.posix.basename(name) !== ".DS_Store");
+  for (const relative of files) hash.update(`${relative}\0${fileDigest(path.join(folder, relative))}\n`);
+  return hash.digest("hex");
+};
+
+/** A copy of a bundle, from a package or an archive, must carry exactly the files it was built with. */
+export const assertBundleStand = (folder: string, manifest: Pick<BundleManifest, "id" | "stand">): void => {
+  if (bundleStand(folder) !== manifest.stand) {
+    throw new Error(`Das Bundle ${manifest.id} in ${folder} hat nicht mehr die Dateien, mit denen es gebaut wurde (stand); ${rebuildHint(folder)}`);
+  }
+};
+
+/** What a bundle needs from the host API that this host does not offer, one line per module. */
+const missingHostNames = (manifest: Pick<BundleManifest, "hostNames">, record: HostApiRecord): readonly string[] =>
+  (["server", "web"] as const).flatMap((half) => Object.entries(manifest.hostNames[half]).flatMap(([specifier, names]) => {
+    const offered = record[half][specifier];
+    if (!offered) return [`${half} ${specifier}`];
+    const missing = names.filter((name) => !offered.includes(name));
+    return missing.length > 0 ? [`${half} ${specifier}: ${missing.join(", ")}`] : [];
+  }));
+
+/** A bundle built against a newer host of the same number may use names this host lacks; that is a start error with its cause, never undefined at run time. */
+export const assertHostNames = (folder: string, manifest: Pick<BundleManifest, "id" | "hostNames">, record: HostApiRecord): void => {
+  const missing = missingHostNames(manifest, record);
+  if (missing.length === 0) return;
+  throw new Error(`Das Bundle ${manifest.id} braucht aus der Host-API ${record.version} Namen, die dieser Host nicht anbietet (${missing.join("; ")}); `
+    + `es ist gegen einen neueren Host gebaut: den Host aktualisieren, sonst ${rebuildHint(folder)}`);
+};
+
+/** Reads and checks the manifest; format and host API must match this host exactly. */
+export const readBundleManifest = (folder: string): BundleManifest => {
+  const file = path.join(folder, BUNDLE_MANIFEST_FILE);
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) {
+    if (SOURCE_MARKERS.some((marker) => existsSync(path.join(folder, marker)))) {
+      throw new Error(`${folder} ist ein Quellordner, kein Bundle: mit ragents plugin build ${folder} bauen und im Profil den Bundle-Ordner nennen`);
+    }
+    throw new Error(`${folder} ist kein Bundle: ${BUNDLE_MANIFEST_FILE} fehlt`);
+  }
+  const id = pluginIdOf(folder);
+  const raw = ((): unknown => {
+    try {
+      return JSON.parse(readFileSync(file, "utf8"));
+    } catch (cause) {
+      throw new Error(`${file} ist kein gültiges JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+  })();
+  if (!isRecord(raw)) throw new Error(`${file} muss ein Objekt enthalten`);
+  if (raw.format !== BUNDLE_FORMAT) {
+    throw new Error(`Das Bundle ${id} hat das Format ${String(raw.format)}, dieser Host liest Format ${BUNDLE_FORMAT}; ${rebuildHint(folder)}`);
+  }
+  if (raw.id !== id) throw new Error(`Das Bundle in ${folder} meldet die Kennung ${String(raw.id)}; die Kennung ist der Ordnername ${id}`);
+  if (raw.api !== HOST_API_VERSION) {
+    throw new Error(`Das Bundle ${id} ist für Host-API ${String(raw.api)} gebaut, dieser Host bietet ${HOST_API_VERSION}; ${rebuildHint(folder)}`);
+  }
+  const unknown = Object.keys(raw).filter((key) => !MANIFEST_KEYS.has(key));
+  if (unknown.length > 0) throw new Error(`${file}: unbekannte Felder ${unknown.join(", ")}; ${rebuildHint(folder)}`);
+  const malformed = [
+    ...(isHostNames(raw.hostNames) ? [] : ["hostNames"]),
+    ...(typeof raw.stand === "string" ? [] : ["stand"]),
+    ...(typeof raw.sourceStand === "string" ? [] : ["sourceStand"]),
+    ...(typeof raw.server === "string" ? [] : ["server"]),
+    ...(isWeb(raw.web) ? [] : ["web"]),
+    ...(isRecord(raw.exports) && isPathRecord(raw.exports.server) && isPathRecord(raw.exports.web) ? [] : ["exports"]),
+    ...(isStringList(raw.uses) ? [] : ["uses"]),
+    ...(isStringList(raw.assets) ? [] : ["assets"]),
+  ];
+  if (malformed.length > 0) throw new Error(`${file}: ${malformed.join(", ")} fehlt oder hat die falsche Form; ${rebuildHint(folder)}`);
+  const web = raw.web as BundleManifest["web"];
+  const webFiles = web === undefined ? [] : [web.entry, web.classes, ...(web.css === undefined ? [] : [web.css])];
+  const misplaced = webFiles.filter((entry) => !entry.startsWith("web/") || entry.split("/").includes(".."));
+  if (misplaced.length > 0) throw new Error(`${file}: ${misplaced.join(", ")} liegt nicht unter web/; ${rebuildHint(folder)}`);
+  for (const required of [raw.server as string, ...webFiles]) {
+    if (!statSync(path.join(folder, required), { throwIfNoEntry: false })?.isFile()) throw new Error(`Dem Bundle ${id} fehlt ${required}; ${rebuildHint(folder)}`);
+  }
+  return raw as unknown as BundleManifest;
+};

package/apps/server/src/profile/compose.ts

@@ -1,16 +1,17 @@
-import { PluginHost } from "@aicontainer/ragents";
+import { PluginHost, type PluginWebAddresses } from "@ragents/engine";
 import { config, HOST_SECRET_ENV_NAMES } from "../config.js";
 import { SESSION_MODE, SESSIONS_MODE } from "../layout.js";
 import { withFolderAssets } from "../plugin-support/plugin-folder.js";
-import { pluginFolder, webEntryOf } from "../plugin-support/plugins-root.js";
 import type { PluginModule } from "../plugin-support/plugin-module.js";
-import { sessionManagementToken } from "../ragents/global-chat.js";
+import { runManagementToken } from "../ragents/global-chat.js";
 import { registerTypeScriptFunctions } from "../ragents/typescript-tools.js";
 import {
+  hostAddressToken,
   runtimeProviderToken,
   secretEnvNamesToken,
-  sessionGuardToken,
-  sessionWorkspaceProviderToken,
+  runGuardToken,
+  runWorkspaceProviderToken,
+  workspaceGuardToken,
   type HostBridges,
 } from "../ragents/host-services.js";
 
@@ -24,6 +25,10 @@ export interface ProfileComposition {
   readonly product: ProductDescriptor;
   readonly pluginIds: readonly string[];
   readonly modules: ReadonlyMap<string, PluginModule>;
+  /** The plugins with a web half and where the browser loads it; the web loads exactly these. */
+  readonly web: ReadonlyMap<string, PluginWebAddresses>;
+  /** Die Vorlage aus defaultStartEntry der Profildatei; der Host lehnt eine nicht registrierte beim Versiegeln ab. */
+  readonly defaultStartEntry?: string;
 }
 
 export const composeProfile = (options: ProfileComposition, bridges: HostBridges): PluginHost => {
@@ -31,11 +36,14 @@ export const composeProfile = (options: ProfileComposition, bridges: HostBridges
     product: options.product,
     dataDirectory: config.dataDir,
     storageModes: { sessionsRoot: SESSIONS_MODE, session: SESSION_MODE },
+    ...(options.defaultStartEntry !== undefined ? { defaultStartEntry: options.defaultStartEntry } : {}),
   });
-  host.provideHost(sessionGuardToken, bridges.ensureSession);
-  host.provideHost(sessionWorkspaceProviderToken, bridges.sessionWorkspaceFor);
+  host.provideHost(runGuardToken, bridges.ensureSession);
+  host.provideHost(workspaceGuardToken, bridges.ensureWorkspaceAccess);
+  host.provideHost(runWorkspaceProviderToken, bridges.sessionWorkspaceFor);
   host.provideHost(runtimeProviderToken, bridges.runtime);
-  host.provideHost(sessionManagementToken, () => {
+  host.provideHost(hostAddressToken, () => bridges.apiBaseUrl);
+  host.provideHost(runManagementToken, () => {
     if (!bridges.sessions) throw new Error("Der Host stellt keine Sitzungsverwaltung bereit");
     return bridges.sessions();
   });
@@ -52,13 +60,14 @@ export const composeProfile = (options: ProfileComposition, bridges: HostBridges
       throw new Error(`Plugin ${id} deklariert requires im Manifest; es gehört in den Modulvertrag`);
     }
     if (plugin.manifest.web !== undefined) {
-      throw new Error(`Plugin ${id} deklariert web im Manifest; das ergibt sich aus dem Plugin-Ordner`);
+      throw new Error(`Plugin ${id} deklariert web im Manifest; das ergibt sich aus dem Bundle`);
     }
+    const web = options.web.get(id);
     host.register(withFolderAssets({
       ...plugin,
       manifest: {
         ...plugin.manifest,
-        web: webEntryOf(pluginFolder(id)) !== undefined,
+        ...(web ? { web } : {}),
         ...(module.requires ? { requires: module.requires } : {}),
       },
     }));