@schlenkr/ragents 0.1.5 → 0.1.7

package/apps/server/src/provider.ts

@@ -1,15 +1,15 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { chmod, mkdir, open, readFile, readdir, realpath, rename, rm } from "node:fs/promises";
 import path from "node:path";
-import type { ChatSessionLike, ChatSessionProvider, SessionInfo } from "./chat-handler.js";
-import { DomainError, isRunId, unrestrictedAccess, type AccessContext, type HttpRouteContribution, type MethodContribution, type PluginHost, type ServiceToken } from "@aicontainer/ragents";
-import { WORKSPACE_EXECUTOR_VERSION } from "@aicontainer/workspace-executor";
-import type { GlobalRunPolicy } from "./api/rights.js";
+import type { ChatSessionLike, ChatSessionProvider, RunListScope, SessionInfo } from "./chat-handler.js";
+import { DomainError, isRunId, unrestrictedAccess, type AccessContext, type HttpRouteContribution, type Journal, type JournalLoadFailure, type MethodContribution, type PluginHost, type ServiceToken, type SessionStartedContext } from "@ragents/engine";
+import { WORKSPACE_EXECUTOR_VERSION } from "@ragents/workspace-executor";
+import { assertRunRights, assertRunWorkspaceAccess, runIdInPath, runListScope, runReachable, type GlobalRunPolicy, type RunAccessPolicy } from "./api/rights.js";
 import { configuredAnonymousUser, configuredUsers } from "./config-file.js";
 import { accessibleRunView } from "./access-projection.js";
-import { accessServiceToken } from "./access-service.js";
+import { coordinatorAccessToken } from "./access-service.js";
 import { config } from "./config.js";
 import { layout, ROOT_ONLY_MODE, SESSION_MODE, SESSIONS_MODE } from "./layout.js";
 import { readHostPackage, readHostVersion } from "./host-version.js";
@@ -17,6 +17,8 @@ import {
   assertRunIdFree,
   assertRunStopped,
   assertWorkspaceReplacement,
+  contentHashesOf,
+  installContents,
   installSessionDirectory,
   packRunArchive,
   runTransferStagingDirectory,
@@ -28,17 +30,19 @@ import {
   type RunTransferPlaces,
 } from "./run-transfer.js";
 import type { StartOptionState } from "./plugin-support/start-options-contract.js";
+import { ALIAS_PROVIDER, validatedModelAliases } from "./plugin-support/model-aliases.js";
 import { runScriptFromDirectory } from "./plugin-support/run-scripts.js";
 import { createEngine, SessionWorkspaces, type Engine } from "./ragents/engine.js";
 import type { ProductProfileFactory } from "./ragents/host-services.js";
 import { actorProgramsToken } from "./plugin-support/actor-programs/service.js";
 import { productRuntimeToken } from "./ragents/product-runtime.js";
+import { runOwnerOf, runOwnerOnly } from "./ragents/run-owner.js";
 import { RunChatSession } from "./ragents/session.js";
-import { globalChatToken, type ManagedRunStart, type SessionManagement } from "./ragents/global-chat.js";
+import { globalChatToken, globalRunPolicyOf, type GlobalChatPolicy, type ManagedRunStart, type RunManagement } from "./ragents/global-chat.js";
 import { workspaceRuntimeToken, type SessionWorkspace, type WorkspaceTransfer } from "./ragents/workspace-runtime.js";
 import { settingsResponse, skillDetailResponse, type SettingsResponse, type SettingsSkillDetail } from "./settings.js";
 import { createTitleCompactor } from "./title-compactor.js";
-import { ModelRuntime } from "@aicontainer/agent";
+import { ModelRuntime } from "@ragents/agent";
 import { TitleSettingsStore } from "./title-settings.js";
 import { sandboxServicesToken } from "./plugin-support/workspace-sandbox-host.js";
 import { parseRunPreparationRequest, prepareRunMessage } from "./run-preparation.js";
@@ -50,12 +54,23 @@ const hostVersionOf = (): string => readHostPackage()?.hostVersion ?? readHostVe
 /** accepted: the delete intent is durable and the run is hidden; done: the cleanup job has finished. */
 interface DeleteJob { accepted: Promise<void>; done: Promise<void> }
 
+type ListedSession = SessionInfo & {
+  running: boolean;
+  /** Ob der Aufrufer den Arbeitsbereich des Runs erreicht; Oberflächen blenden sonst aus, was ihn braucht. */
+  workspaceAccessible: boolean;
+  metadata?: Readonly<Record<string, unknown>>;
+  metadataUnavailable?: Readonly<Record<string, string>>;
+};
+
+/** Die Run-Liste wird oft abgefragt; so lange wartet sie höchstens auf einen Metadaten-Beitrag. */
+export const SESSION_METADATA_TIMEOUT_MS = 1_500;
+
 export class RunSessionProvider implements ChatSessionProvider {
   private readonly sessions = new Map<string, RunChatSession>();
   private readonly deleting = new Map<string, DeleteJob>();
   private readonly deleteRequested = new Set<string>();
   private readonly deleted = new Set<string>();
-  private readonly workspaces = new SessionWorkspaces();
+  private readonly workspaces = new SessionWorkspaces(() => this.plugins.service(sandboxServicesToken));
   private readonly sessionWorkspaces = new Map<string, Promise<SessionWorkspace>>();
   private modelRuntime: Promise<ModelRuntime> | undefined;
   private readonly runPreparations = new Map<string, { controller: AbortController; done: Promise<RunPreparationResponse> }>();
@@ -63,7 +78,6 @@ export class RunSessionProvider implements ChatSessionProvider {
   private readonly listListeners = new Set<() => void>();
   private readonly titleCompactor = createTitleCompactor({
     selection: () => this.requireTitleSettings().selection(),
-    agentHomeDir: config.agentHomeDir,
     sessionsDir: layout.sessionsDir,
     modelRuntime: () => this.getModelRuntime(),
     onTitle: () => this.notifyList(),
@@ -72,23 +86,31 @@ export class RunSessionProvider implements ChatSessionProvider {
   readonly plugins: PluginHost;
   private shutdownPromise: Promise<void> | undefined;
   private engine: Engine | undefined;
-  private globalReset: Promise<void> | undefined;
-  private globalResetRequested = false;
+  private readonly globalResets = new Map<string, Promise<void>>();
+  private readonly globalResetsRequested = new Set<string>();
   private transferring = false;
+  /** Die Adresse, unter der dieser Server seine API anbietet; ohne HTTP (nur stdio) keine. */
+  private readonly apiBaseUrl: string | undefined;
 
-  constructor(profileFactory: ProductProfileFactory) {
+  constructor(profileFactory: ProductProfileFactory, apiBaseUrl: string | undefined) {
+    this.apiBaseUrl = apiBaseUrl;
     this.plugins = profileFactory({
       ensureSession: (runId) => this.ensureUsable(runId),
+      ensureWorkspaceAccess: (access, runId) => {
+        this.ensureUsable(runId);
+        assertRunWorkspaceAccess(access, runId, this.runAccess());
+      },
       runtime: () => this.requireEngine().runtime,
       sessionWorkspaceFor: (runId) => this.sessionWorkspace(runId, () => {}),
       sessions: () => this.sessionManagement(),
+      ...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),
     });
   }
 
   private requireContract(token: ServiceToken<unknown>): void {
     if (this.plugins.optionalService(token) !== undefined) return;
     throw new Error(
-      `Das Produktprofil stellt den Pflichtvertrag ${token.id} nicht bereit. `
+      `Das Profil stellt den Pflichtvertrag ${token.id} nicht bereit. `
       + "Ein Produkt-Plugin muss ihn mit host.provide(...) registrieren.",
     );
   }
@@ -119,11 +141,16 @@ export class RunSessionProvider implements ChatSessionProvider {
     this.requireContract(productRuntimeToken);
     this.requireContract(workspaceRuntimeToken);
     const globalChat = this.plugins.optionalService(globalChatToken);
-    if (globalChat?.resetIntentFile && existsSync(globalChat.resetIntentFile)) {
-      await this.validateGlobalResetIntent(globalChat.resetIntentFile, globalChat.runId);
-      await this.removeGlobalConversation();
-      await rm(globalChat.resetIntentFile);
-      await this.syncDirectory(path.dirname(globalChat.resetIntentFile));
+    if (globalChat?.resetIntentDirectory && existsSync(globalChat.resetIntentDirectory)) {
+      for (const entry of await readdir(globalChat.resetIntentDirectory)) {
+        if (!entry.endsWith(".json")) continue;
+        const intentFile = path.join(globalChat.resetIntentDirectory, entry);
+        const runId = entry.slice(0, -5);
+        await this.validateGlobalResetIntent(intentFile, runId);
+        await this.removeGlobalConversation(runId);
+        await rm(intentFile);
+        await this.syncDirectory(globalChat.resetIntentDirectory);
+      }
     }
     this.engine = await createEngine({
       plugins: this.plugins,
@@ -131,16 +158,16 @@ export class RunSessionProvider implements ChatSessionProvider {
       modelRuntime: this.getModelRuntime(),
       assertAvailable: () => this.ensureAvailable(),
       assertRunUsable: (runId) => this.ensureUsable(runId),
-      onChatSessionPersisted: () => undefined,
     });
     for (const id of this.deleted) {
       if (this.deleteRequested.has(id)) continue;
       if (this.engine.journal.stateOf(id) || existsSync(layout.sessionDir(id))) {
-        throw new Error(`Archivierte Unterhaltung ${id} besitzt erneut aktive Daten`);
+        throw new Error(`Archivierter Run ${id} besitzt erneut aktive Daten`);
       }
     }
     for (const id of pendingDeletes) await this.beginDelete(id).done;
-    const runIds = this.engine.journal.runIds();
+    // Ein Koordinator ohne heutigen Zugang (der frühere gemeinsame, ein entfernter Benutzer) bleibt unberührt.
+    const runIds = this.engine.journal.runIds().filter((runId) => !globalChat?.isCoordinator(runId) || this.coordinatorUser(runId) !== undefined);
     await Promise.all(runIds.map((runId) => this.sessionWorkspace(runId, () => {})));
     for (const runId of runIds) this.openSession(runId);
     this.engine.start();
@@ -151,13 +178,15 @@ export class RunSessionProvider implements ChatSessionProvider {
     return this.engine;
   }
 
-  /** Die eine Modelllaufzeit des Servers; Anbieter der Plugins sind registriert, bevor jemand ein Modell nachschlägt. */
+  /** Die eine Modelllaufzeit des Servers; Anbieter der Plugins und Aliasse des Profils stehen, bevor jemand ein Modell nachschlägt. */
   private getModelRuntime(): Promise<ModelRuntime> {
-    return this.modelRuntime ??= ModelRuntime.create({ authPath: path.join(config.agentHomeDir, "auth.json"), modelsPath: path.join(config.agentHomeDir, "models.json") })
-      .then(async (runtime) => {
-        for (const provider of await this.plugins.profiles.providers()) runtime.registerProvider(provider.id, provider.config);
-        return runtime;
-      });
+    return this.modelRuntime ??= this.plugins.profiles.providers().then((providers) => {
+      const runtime = ModelRuntime.create();
+      for (const provider of providers) runtime.registerProvider(provider.id, provider.config);
+      const aliases = validatedModelAliases();
+      if (aliases.length > 0) runtime.registerAliases(ALIAS_PROVIDER, aliases);
+      return runtime;
+    });
   }
 
   private requireTitleSettings(): TitleSettingsStore {
@@ -186,7 +215,7 @@ export class RunSessionProvider implements ChatSessionProvider {
     const engine = this.requireEngine();
     const productRuntime = this.plugins.service(productRuntimeToken);
     const globalChat = this.plugins.optionalService(globalChatToken);
-    const globalPolicy = id === globalChat?.runId ? globalChat : undefined;
+    const globalPolicy = globalChat?.isCoordinator(id) ? globalChat : undefined;
     const session = new RunChatSession({
       engine,
       id,
@@ -208,7 +237,9 @@ export class RunSessionProvider implements ChatSessionProvider {
       },
       prepare: (runId) => this.prepareRun(runId),
       prepareWorkspace: (runId, emitSystem) => this.prepareWorkspace(runId, emitSystem),
+      started: (runId, startEntry) => this.startedRun(runId, startEntry),
       scriptEntryFor: (entryId) => globalPolicy ? undefined : this.plugins.startEntries.scriptPackage(entryId),
+      startEntryFor: (entryId) => globalPolicy ? undefined : this.plugins.startEntries.entry(entryId),
       actorPrograms: {
         runInput: (...args) => this.plugins.service(actorProgramsToken).runInput(...args),
         workspaceDirectory: (runId) => this.plugins.service(actorProgramsToken).workspaceDirectory(runId),
@@ -220,52 +251,59 @@ export class RunSessionProvider implements ChatSessionProvider {
     return session;
   }
 
-  startOptions(id: string): readonly StartOptionState[] {
-    return this.openSession(id).startOptions();
+  startOptions(id: string, userId: string | null): readonly StartOptionState[] {
+    return this.openSession(id).startOptions(userId);
   }
 
-  selectStartOption(id: string, optionId: string, value: unknown): StartOptionState {
-    return this.openSession(id).selectStartOption(optionId, value);
+  selectStartOption(id: string, optionId: string, value: unknown, userId: string | null): Promise<StartOptionState> {
+    return this.openSession(id).selectStartOption(optionId, value, userId);
   }
 
-  async prepareRunMessage(id: string, value: unknown, signal: AbortSignal): Promise<RunPreparationResponse> {
+  async prepareRunMessage(id: string, value: unknown, signal: AbortSignal, userId: string | null): Promise<RunPreparationResponse> {
     this.ensureUsable(id);
     if (this.runPreparations.has(id)) throw new DomainError("preparation-busy", "Eine Antwort für diese Vorbereitung wird bereits erstellt.", 409);
     const request = parseRunPreparationRequest(value);
     const session = this.openSession(id);
-    const selection = session.preparationSelection();
+    const selection = session.preparationSelection(userId);
     const prompt = this.plugins.optionalService(globalChatToken)?.preparationPrompt;
     if (!prompt) throw new DomainError("preparation-unavailable", "Das Profil stellt keinen Vorbereitungskoordinator bereit.", 409);
     const controller = new AbortController();
     const combined = AbortSignal.any([signal, controller.signal]);
     const done = this.getModelRuntime().then(async (runtime) => {
       this.ensureUsable(id);
-      session.preparationSelection();
-      const result = await prepareRunMessage({ runtime, selection, request, prompt, agentDir: config.agentHomeDir, signal: combined });
+      session.preparationSelection(userId);
+      const result = await prepareRunMessage({ runtime, selection, request, prompt, signal: combined });
       this.ensureUsable(id);
-      session.preparationSelection();
+      session.preparationSelection(userId);
       return result;
     }).finally(() => this.runPreparations.delete(id));
     this.runPreparations.set(id, { controller, done });
     return done;
   }
 
-  async list(): Promise<SessionInfo[]> {
+  /** Nur sichtbare Runs bekommen Titel und Metadaten; ohne Bereich alle, ohne einen Arbeitsbereich, den nur sein Eigentümer bedient. */
+  async list(scope?: RunListScope): Promise<SessionInfo[]> {
+    const visible = scope?.visible ?? (() => true);
+    const workspaceAccessible = scope?.workspaceAccessible ?? ((runId: string) => !this.runOwnerOnly(runId));
     const engine = this.requireEngine();
     const productRuntime = this.plugins.service(productRuntimeToken);
-    const infos: Array<SessionInfo & { running: boolean; metadata?: Readonly<Record<string, unknown>> }> = [];
-    for (const runId of engine.journal.runIds()) {
-      if (runId === this.plugins.optionalService(globalChatToken)?.runId) continue;
-      if (this.deleteRequested.has(runId) || this.deleted.has(runId)) continue;
+    const isCoordinator = (runId: string) => this.plugins.optionalService(globalChatToken)?.isCoordinator(runId) ?? false;
+    const listed = engine.journal.runIds().filter((runId) => !isCoordinator(runId)
+      && !this.deleteRequested.has(runId) && !this.deleted.has(runId) && visible(runId));
+    const described = await Promise.all(listed.map(async (runId): Promise<ListedSession | undefined> => {
       const state = engine.journal.stateOf(runId);
-      if (!state) continue;
+      if (!state) return undefined;
       const firstInput = [...state.inputs.values()]
         .sort((left, right) => left.sequence - right.sequence)
         .find((input) => input.enqueuedBy === state.ownerId);
       // A title set on purpose (run script, run_configure) beats the first-message heuristic.
       const chosenTitle = state.title !== productRuntime.coordinator.runTitle ? state.title : undefined;
-      const compactTitle = chosenTitle ?? await this.titleCompactor.titleFor(runId, firstInput?.content);
-      infos.push({
+      const workspace = workspaceAccessible(runId);
+      const [compactTitle, metadata] = await Promise.all([
+        chosenTitle ?? this.titleCompactor.titleFor(runId, firstInput?.content),
+        this.plugins.sessionMetadata.describe(runId, workspace, SESSION_METADATA_TIMEOUT_MS),
+      ]);
+      return {
         id: runId,
         title: compactTitle ?? sessionTitle(firstInput?.content) ?? productRuntime.coordinator.runTitle,
         createdAt: Date.parse(state.createdAt),
@@ -273,11 +311,17 @@ export class RunSessionProvider implements ChatSessionProvider {
         revision: state.revision,
         running: [...state.actors.values()].some((actor) => actor.kind !== "human" && engine.scheduler.isRunning(runId, actor.id))
           || (this.sessions.get(runId)?.running ?? false),
-        metadata: await this.plugins.sessionMetadata.describe(runId),
-      });
-    }
+        workspaceAccessible: workspace,
+        metadata: metadata.values,
+        ...(Object.keys(metadata.unavailable).length > 0 ? { metadataUnavailable: metadata.unavailable } : {}),
+      };
+    }));
+    const locked = engine.journal.unavailableRuns()
+      .filter(({ runId }) => !isCoordinator(runId) && !this.deleteRequested.has(runId) && !this.deleted.has(runId) && visible(runId))
+      .map((failure) => lockedSession(failure, engine.journal));
+    const infos = [...described.filter((info): info is ListedSession => info !== undefined), ...locked];
     for (const [id, session] of this.sessions) {
-      if (id === this.plugins.optionalService(globalChatToken)?.runId) continue;
+      if (isCoordinator(id) || !visible(id)) continue;
       if (this.deleteRequested.has(id) || this.deleted.has(id)) continue;
       if (!session.started || infos.some((info) => info.id === id)) continue;
       infos.push({
@@ -285,14 +329,15 @@ export class RunSessionProvider implements ChatSessionProvider {
         title: productRuntime.coordinator.runTitle,
         updatedAt: Date.now(),
         running: session.running,
+        workspaceAccessible: workspaceAccessible(id),
       });
     }
     return infos.sort((a, b) => b.updatedAt - a.updatedAt);
   }
 
-  private sessionManagement(): SessionManagement {
+  private sessionManagement(): RunManagement {
     return {
-      list: () => this.list(),
+      list: (access) => this.list(access ? runListScope(access, this.runAccess()) : undefined),
       view: (runId) => {
         this.ensureUsable(runId);
         return this.requireEngine().runtime.view(runId);
@@ -302,9 +347,12 @@ export class RunSessionProvider implements ChatSessionProvider {
         return this.requireEngine().runtime.events(runId);
       },
       create: (start) => this.createManagedRun(start),
-      send: (runId, message) => this.openSession(runId).sendAndWait(message),
+      send: (runId, message, access) => {
+        assertRunRights(access, runId, "write", this.runAccess());
+        return this.openSession(runId).sendAndWait(message, access.user ? { id: access.user.id, label: access.user.label } : undefined);
+      },
       stop: (runId) => this.openSession(runId).stop(),
-      resetGlobal: () => this.resetGlobalConversation(),
+      resetGlobal: (runId) => this.resetGlobalConversation(runId),
     };
   }
 
@@ -312,14 +360,15 @@ export class RunSessionProvider implements ChatSessionProvider {
     const local = start.kind === "package" ? runScriptFromDirectory(start.directory) : undefined;
     const id = randomUUID();
     const session = this.openSession(id, start.title);
-    for (const [optionId, value] of Object.entries(start.options ?? {})) session.selectStartOption(optionId, value);
-    if (start.kind === "script") await session.startAndWait(start.entryId, start.input);
+    const user = start.user ?? undefined;
+    for (const [optionId, value] of Object.entries(start.options ?? {})) await session.selectStartOption(optionId, value, start.user?.id ?? null);
+    if (start.kind === "script") await session.startAndWait(start.entryId, start.input, user);
     else if (start.kind === "package") {
       if (!local) throw new Error("Das Run-Script-Paket wurde nicht geladen");
       const { script, ...entry } = local;
-      await session.startPackageAndWait({ ...script, entry: { ...entry, coordinator: script.coordinator, owner: "ragents.overseer" } }, start.input);
+      await session.startPackageAndWait({ ...script, entry: { ...entry, coordinator: script.coordinator, owner: "ragents.overseer" } }, start.input, user);
     }
-    else await session.sendAndWait(start.message);
+    else await session.sendAndWait(start.message, user);
     return id;
   }
 
@@ -332,8 +381,19 @@ export class RunSessionProvider implements ChatSessionProvider {
   }
 
   globalPolicy(): GlobalRunPolicy | undefined {
-    const globalChat = this.plugins.optionalService(globalChatToken);
-    return globalChat?.access ? { runId: globalChat.runId, ...globalChat.access } : undefined;
+    return globalRunPolicyOf(this.plugins.optionalService(globalChatToken));
+  }
+
+  runOwner(id: string): string | null | undefined {
+    return runOwnerOf(this.requireEngine().journal, id);
+  }
+
+  runOwnerOnly(id: string): boolean {
+    return runOwnerOnly(this.requireEngine().journal, this.plugins.startOptions, id);
+  }
+
+  runAccess(): RunAccessPolicy {
+    return { global: this.globalPolicy(), ownerOf: (runId) => this.runOwner(runId), ownerOnly: (runId) => this.runOwnerOnly(runId) };
   }
 
   runView(id: string, access: AccessContext = unrestrictedAccess): unknown {
@@ -363,18 +423,25 @@ export class RunSessionProvider implements ChatSessionProvider {
     return pathname === "/rpc" || pathname === "/rpc/stream" || pathname.startsWith("/files/") || this.plugins.isApiPath(pathname);
   }
 
-  pluginRoutes(req: IncomingMessage, res: ServerResponse, url: URL, access?: AccessContext): Promise<boolean> {
+  /** Auslieferungsrouten nennen ihren Run im Pfad; ein fremder Run ist dort so wenig erreichbar wie in einer Methode. */
+  async pluginRoutes(req: IncomingMessage, res: ServerResponse, url: URL, access?: AccessContext): Promise<boolean> {
+    const named = runIdInPath(url.pathname);
+    if (named !== undefined && access && !runReachable(access, named, this.runAccess())) {
+      res.writeHead(404, { "Cache-Control": "no-store", "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: `Run ${named} does not exist.`, code: "run-not-found" }));
+      return true;
+    }
     return this.plugins.dispatchHttp(req, res, url, access);
   }
 
   private ensureUsable(id: string): void {
-    if (!isRunId(id)) throw new DomainError("invalid-run", `Ungültige Session-Id: ${id}`, 400);
+    if (!isRunId(id)) throw new DomainError("invalid-run", `Ungültige Run-ID: ${id}`, 400);
     this.ensureAvailable();
-    if (this.globalResetRequested && id === this.plugins.optionalService(globalChatToken)?.runId) {
+    if (this.globalResetsRequested.has(id)) {
       throw new DomainError("conversation-resetting", "Das globale Gespräch wird zurückgesetzt. Bitte warte kurz oder wiederhole den Reset nach einem Fehler.", 409);
     }
-    if (this.deleteRequested.has(id)) throw new DomainError("run-deleting", "Die Unterhaltung wird gelöscht", 409);
-    if (this.deleted.has(id)) throw new DomainError("run-deleted", "Die Unterhaltung wurde gelöscht", 410);
+    if (this.deleteRequested.has(id)) throw new DomainError("run-deleting", "Der Run wird gelöscht", 409);
+    if (this.deleted.has(id)) throw new DomainError("run-deleted", "Der Run wurde gelöscht", 410);
     this.engine?.journal.assertRunAvailable(id);
   }
 
@@ -389,7 +456,7 @@ export class RunSessionProvider implements ChatSessionProvider {
     const created = this.resolveWorkspace(id, emitSystem)
       .then((workspace) => {
         this.ensureUsable(id);
-        this.workspaces.remember(id, workspace.cwd);
+        this.workspaces.remember(id, workspace.cwd, workspace.description);
         return workspace;
       })
       .catch((error: unknown) => {
@@ -402,12 +469,13 @@ export class RunSessionProvider implements ChatSessionProvider {
 
   private async prepareRun(id: string): Promise<void> {
     this.ensureUsable(id);
-    if (id !== this.plugins.optionalService(globalChatToken)?.runId) await this.plugins.lifecycle.prepareSession(id);
-    this.ensureUsable(id);
-    await mkdir(layout.chatDir(id), { recursive: true, mode: ROOT_ONLY_MODE });
+    if (!this.plugins.optionalService(globalChatToken)?.isCoordinator(id)) await this.plugins.lifecycle.prepareSession(id);
     this.ensureUsable(id);
-    await chmod(layout.chatDir(id), ROOT_ONLY_MODE);
+  }
+
+  private async startedRun(id: string, startEntry: SessionStartedContext["startEntry"]): Promise<void> {
     this.ensureUsable(id);
+    if (!this.plugins.optionalService(globalChatToken)?.isCoordinator(id)) await this.plugins.lifecycle.sessionStarted(id, startEntry);
   }
 
   private async prepareWorkspace(id: string, emitSystem: (text: string) => void): Promise<void> {
@@ -417,10 +485,10 @@ export class RunSessionProvider implements ChatSessionProvider {
   }
 
   delete(id: string): Promise<void> {
-    if (id === this.plugins.optionalService(globalChatToken)?.runId) {
-      return Promise.reject(new DomainError("global-chat-protected", "Der übergeordnete Koordinator kann nicht gelöscht werden", 409));
+    if (this.plugins.optionalService(globalChatToken)?.isCoordinator(id)) {
+      return Promise.reject(new DomainError("global-chat-protected", "Der globale Koordinator kann nicht gelöscht werden", 409));
     }
-    if (!isRunId(id)) return Promise.reject(new Error(`Ungültige Session-Id: ${id}`));
+    if (!isRunId(id)) return Promise.reject(new Error(`Ungültige Run-ID: ${id}`));
     if (this.shutdownPromise) return Promise.reject(new Error("Der Server wird beendet"));
     return this.beginDelete(id).accepted;
   }
@@ -429,16 +497,16 @@ export class RunSessionProvider implements ChatSessionProvider {
     return this.deleting.get(id)?.done;
   }
 
-  /** Ein gestoppter Run als Archiv: Journal, Payloads, Modellkontexte und die Plugin-Ablagen seiner Session. */
+  /** Ein gestoppter Run als Archiv: Journal, Payloads, die Inhalte, auf die er verweist, und seine Plugin-Ablagen. */
   exportRun(id: string): Promise<RunTransferExport> {
     this.ensureUsable(id);
-    if (id === this.plugins.optionalService(globalChatToken)?.runId) {
-      return Promise.reject(new DomainError("global-chat-protected", "Der übergeordnete Koordinator zieht nicht um", 409));
+    if (this.plugins.optionalService(globalChatToken)?.isCoordinator(id)) {
+      return Promise.reject(new DomainError("global-chat-protected", "Der globale Koordinator zieht nicht um", 409));
     }
     return this.runTransfer(async () => {
       const engine = this.requireEngine();
       const state = engine.journal.stateOf(id);
-      if (!state) throw new DomainError("run-not-found", `Die Unterhaltung ${id} gibt es nicht`, 404);
+      if (!state) throw new DomainError("run-not-found", `Den Run ${id} gibt es nicht`, 404);
       assertRunStopped({
         runId: id,
         state,
@@ -457,7 +525,12 @@ export class RunSessionProvider implements ChatSessionProvider {
         boundDirectory: this.workspaceTransfer().boundDirectory(id),
         exportedAt: new Date().toISOString(),
       };
-      const archive = await packRunArchive({ places: this.transferPlaces(), runId: id, manifest });
+      const archive = await packRunArchive({
+        places: this.transferPlaces(),
+        runId: id,
+        manifest,
+        contentHashes: contentHashesOf(engine.journal.load(id)),
+      });
       return { manifest, archive: archive.toString("base64") };
     });
   }
@@ -476,6 +549,7 @@ export class RunSessionProvider implements ChatSessionProvider {
         assertWorkspaceReplacement(manifest, workspacePath);
         if (workspacePath !== undefined) transfer.assertDirectory(workspacePath);
         const sessionDirectory = await installSessionDirectory({ places, runId: manifest.runId, staging, mode: SESSION_MODE });
+        await installContents({ places, staging });
         const engine = this.requireEngine();
         try {
           engine.journal.adopt(unpacked.records);
@@ -520,8 +594,8 @@ export class RunSessionProvider implements ChatSessionProvider {
   }
 
   private assertRunIdAvailable(id: string): void {
-    if (id === this.plugins.optionalService(globalChatToken)?.runId) {
-      throw new DomainError("run-transfer-exists", `Die Kennung ${id} gehört dem übergeordneten Koordinator dieses Servers.`, 409);
+    if (this.plugins.optionalService(globalChatToken)?.isCoordinator(id)) {
+      throw new DomainError("run-transfer-exists", `Die Kennung ${id} ist den übergeordneten Koordinatoren dieses Servers vorbehalten.`, 409);
     }
     const engine = this.requireEngine();
     assertRunIdFree({
@@ -531,23 +605,26 @@ export class RunSessionProvider implements ChatSessionProvider {
     });
   }
 
-  private resetGlobalConversation(): Promise<void> {
+  private resetGlobalConversation(id: string): Promise<void> {
     this.ensureAvailable();
-    if (this.globalReset) return this.globalReset;
+    const running = this.globalResets.get(id);
+    if (running) return running;
     const policy = this.plugins.optionalService(globalChatToken);
-    if (!policy?.resetIntentFile) return Promise.reject(new DomainError("conversation-reset-unavailable", "Dieses Profil bietet keinen Gesprächsreset an.", 404));
-    this.globalResetRequested = true;
-    const operation = this.resetGlobalInner(policy.runId, policy.resetIntentFile).catch((error: unknown) => {
-      if (!existsSync(policy.resetIntentFile!)) this.globalResetRequested = false;
+    if (!policy?.resetIntentDirectory) return Promise.reject(new DomainError("conversation-reset-unavailable", "Dieses Profil bietet keinen Gesprächsreset an.", 404));
+    if (!policy.isCoordinator(id)) return Promise.reject(new DomainError("conversation-reset-unavailable", `${id} ist kein globaler Koordinator.`, 404));
+    const intentFile = path.join(policy.resetIntentDirectory, `${id}.json`);
+    this.globalResetsRequested.add(id);
+    const operation = this.resetGlobalInner(id, intentFile, policy).catch((error: unknown) => {
+      if (!existsSync(intentFile)) this.globalResetsRequested.delete(id);
       throw error;
     }).finally(() => {
-      if (this.globalReset === operation) this.globalReset = undefined;
+      if (this.globalResets.get(id) === operation) this.globalResets.delete(id);
     });
-    this.globalReset = operation;
+    this.globalResets.set(id, operation);
     return operation;
   }
 
-  private async resetGlobalInner(id: string, intentFile: string): Promise<void> {
+  private async resetGlobalInner(id: string, intentFile: string, policy: GlobalChatPolicy): Promise<void> {
     if (!existsSync(intentFile)) {
       await mkdir(path.dirname(intentFile), { recursive: true });
       const temporary = `${intentFile}.tmp-${randomUUID()}`;
@@ -568,33 +645,42 @@ export class RunSessionProvider implements ChatSessionProvider {
       await stopped;
       await settled;
       await this.plugins.optionalService(sandboxServicesToken)?.shutdown(id);
-      await this.removeGlobalConversation();
-      engine.journal.forget(id);
+      await this.removeGlobalConversation(id, policy);
+      engine.runtime.forgetRun(id);
       this.sessionWorkspaces.delete(id);
       this.workspaces.forget(id);
     });
     await rm(intentFile);
     await this.syncDirectory(path.dirname(intentFile));
-    this.globalResetRequested = false;
+    this.globalResetsRequested.delete(id);
     session?.resetHistory();
   }
 
   private async validateGlobalResetIntent(file: string, id: string): Promise<void> {
     const marker: unknown = JSON.parse(await readFile(file, "utf8"));
-    if (!marker || typeof marker !== "object" || !("version" in marker) || marker.version !== 1 || !("runId" in marker) || marker.runId !== id) {
+    if (!isRunId(id) || !marker || typeof marker !== "object" || !("version" in marker) || marker.version !== 1 || !("runId" in marker) || marker.runId !== id) {
       throw new Error("Der Gesprächsreset-Marker ist ungültig");
     }
   }
 
-  private async removeGlobalConversation(): Promise<void> {
-    const policy = this.plugins.service(globalChatToken);
-    const directories = [layout.sessionDir(policy.runId), path.join(layout.runsDir, policy.runId), layout.recoverySessionDir(policy.runId), policy.workspaceDirectory];
+  private async removeGlobalConversation(id: string, policy = this.plugins.service(globalChatToken)): Promise<void> {
+    const directories = [layout.sessionDir(id), path.join(layout.runsDir, id), layout.recoverySessionDir(id), policy.workspaceDirectory(id)];
     for (const directory of directories) await rm(directory, { recursive: true, force: true });
     for (const parent of new Set(directories.map((directory) => path.dirname(directory)))) {
       if (existsSync(parent)) await this.syncDirectory(parent);
     }
   }
 
+  /** Wem ein Koordinator gehört: dem Benutzer, dessen Kennung er trägt, ohne Anmeldung dem einen Zugang; sonst niemandem. */
+  private coordinatorUser(id: string): { userId: string | null } | undefined {
+    const policy = this.plugins.optionalService(globalChatToken);
+    if (!policy?.isCoordinator(id)) return undefined;
+    const users = configuredUsers();
+    if (!users) return policy.runIdFor(null) === id ? { userId: null } : undefined;
+    const user = users.find((entry) => policy.runIdFor(entry.id) === id);
+    return user ? { userId: user.id } : undefined;
+  }
+
   private beginDelete(id: string): DeleteJob {
     const vorhanden = this.deleting.get(id);
     if (vorhanden) return vorhanden;
@@ -637,7 +723,7 @@ export class RunSessionProvider implements ChatSessionProvider {
     await Promise.allSettled([...this.runPreparations.values()].map((preparation) => preparation.done));
     await this.titleCompactor.shutdown();
     this.listListeners.clear();
-    const resetResults = await Promise.allSettled(this.globalReset ? [this.globalReset] : []);
+    const resetResults = await Promise.allSettled([...this.globalResets.values()]);
     const sessions = [...this.sessions.entries()];
     for (const [, session] of sessions) session.dispose();
     const results = await Promise.allSettled([
@@ -674,10 +760,10 @@ export class RunSessionProvider implements ChatSessionProvider {
       .slice(0, 3)
       .filter((result): result is PromiseRejectedResult => result.status === "rejected")
       .map((result) => result.reason);
-    if (failures.length > 0) throw new AggregateError(failures, `Unterhaltung ${id} konnte nicht gestoppt werden`);
+    if (failures.length > 0) throw new AggregateError(failures, `Run ${id} konnte nicht gestoppt werden`);
     await this.plugins.lifecycle.deleteSession(id);
     await this.archiveSession(id);
-    this.engine?.journal.forget(id);
+    this.engine?.runtime.forgetRun(id);
     this.sessions.delete(id);
     this.sessionWorkspaces.delete(id);
     this.workspaces.forget(id);
@@ -764,20 +850,24 @@ export class RunSessionProvider implements ChatSessionProvider {
 
   private async resolveWorkspace(id: string, emitSystem: (text: string) => void): Promise<SessionWorkspace> {
     const globalChat = this.plugins.optionalService(globalChatToken);
-    if (id === globalChat?.runId) {
-      await mkdir(globalChat.workspaceDirectory, { recursive: true, mode: ROOT_ONLY_MODE });
-      const cwd = await realpath(globalChat.workspaceDirectory);
+    if (globalChat?.isCoordinator(id)) {
+      const owner = this.coordinatorUser(id);
+      if (!owner) throw new DomainError("coordinator-without-access", `Der Koordinator ${id} gehört keinem Zugang dieses Profils.`, 409);
+      const directory = globalChat.workspaceDirectory(id);
+      await mkdir(directory, { recursive: true, mode: ROOT_ONLY_MODE });
+      const cwd = await realpath(directory);
       await globalChat.prepareWorkspace?.(cwd);
+      const users = configuredUsers();
       return {
         cwd,
-        hostSandbox: { home: cwd, readOnlyRoots: [{ directory: layout.runsDir, environmentVariable: "RAGENTS_JOURNAL_DIR" }] },
+        // Mit Benutzern enthielte der Journalordner fremde Runs; der Koordinator liest über die Methoden seines Benutzers.
+        hostSandbox: { home: cwd, readOnlyRoots: users ? [] : [{ directory: layout.runsDir, environmentVariable: "RAGENTS_JOURNAL_DIR" }] },
         extraEnv: {
-          RAGENTS_API_BASE_URL: `http://127.0.0.1:${config.port}`,
-          ...(configuredUsers() || configuredAnonymousUser() ? { RAGENTS_API_TOKEN: accessServiceToken() }
+          ...(this.apiBaseUrl ? { RAGENTS_API_BASE_URL: this.apiBaseUrl } : {}),
+          ...(users || configuredAnonymousUser() ? { RAGENTS_API_TOKEN: coordinatorAccessToken(owner.userId) }
             : process.env.ACCESS_TOKEN ? { RAGENTS_API_TOKEN: process.env.ACCESS_TOKEN } : {}),
         },
         currentRoot: async () => cwd,
-        ensureWritable: async () => cwd,
         runOperation: (operation) => operation(),
       };
     }
@@ -787,6 +877,7 @@ export class RunSessionProvider implements ChatSessionProvider {
   private async archiveSession(id: string): Promise<void> {
     const target = layout.archiveSessionDir(id);
     await mkdir(target, { recursive: true, mode: ROOT_ONLY_MODE });
+    // Journale vor Format 7 hielten den Modellkontext unter sessions/<id>/chat; er bleibt im Archiv erhalten.
     const moves = [
       [path.join(layout.sessionDir(id), "chat"), "chat"],
       [path.join(layout.runsDir, id), "run"],
@@ -810,6 +901,21 @@ export class RunSessionProvider implements ChatSessionProvider {
   }
 }
 
+/** Ein gesperrter Run ohne Plugin-Metadaten und Arbeitsbereich; ohne geladenen Zustand zählt die Journaldatei. */
+const lockedSession = (failure: JournalLoadFailure, journal: Journal): ListedSession => {
+  const state = journal.stateOf(failure.runId);
+  const updatedAt = state ? Date.parse(journal.updatedAt(failure.runId) ?? state.createdAt) : statSync(failure.path, { throwIfNoEntry: false })?.mtimeMs ?? 0;
+  return {
+    id: failure.runId,
+    title: state?.title ?? failure.runId,
+    ...(state ? { createdAt: Date.parse(state.createdAt), revision: state.revision } : {}),
+    updatedAt,
+    running: false,
+    workspaceAccessible: false,
+    locked: failure.message,
+  };
+};
+
 const sessionTitle = (text: string | undefined): string | undefined => {
   const lines = text?.split(/\r?\n/).map((line) => line.trim()).filter(Boolean) ?? [];
   if (lines.length === 0) return undefined;