@schlenkr/ragents 0.1.0

package/apps/server/src/rpc/stdio-transport.ts

@@ -0,0 +1,44 @@
+import { createInterface } from "node:readline";
+import type { Readable, Writable } from "node:stream";
+import { RPC_ERROR_CODES, RpcPeer, rpcFailure, unrestrictedAccess, type AccessContext } from "@aicontainer/ragents";
+import { RpcConnection, type RpcDispatcher } from "./dispatcher.js";
+
+export interface StdioTransportOptions {
+  dispatcher: RpcDispatcher;
+  input: Readable;
+  output: Writable;
+  access?: AccessContext;
+}
+
+export interface StdioTransport {
+  connection: RpcConnection;
+  closed: Promise<void>;
+  close: (reason: string) => void;
+}
+
+/** JSON-RPC über stdin und stdout, eine Nachricht je Zeile; der Aufrufer gilt als vertraut. */
+export const startStdioTransport = (options: StdioTransportOptions): StdioTransport => {
+  const write = (message: unknown) => new Promise<void>((resolve, reject) => {
+    options.output.write(`${JSON.stringify(message)}\n`, (error) => error ? reject(error) : resolve());
+  });
+  const peer = new RpcPeer({ send: write });
+  const connection = new RpcConnection({ id: "stdio", access: options.access ?? unrestrictedAccess, local: true, peer }, options.dispatcher);
+  const lines = createInterface({ input: options.input, crlfDelay: Infinity });
+  let settle: () => void = () => undefined;
+  const closed = new Promise<void>((resolve) => { settle = resolve; });
+  const close = (reason: string) => {
+    lines.close();
+    connection.close(reason);
+    settle();
+  };
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    try {
+      peer.receive(JSON.parse(line));
+    } catch {
+      void write(rpcFailure(null, RPC_ERROR_CODES.parse, "Die Zeile enthält kein gültiges JSON")).catch(() => undefined);
+    }
+  });
+  lines.on("close", () => close("Die Eingabe wurde geschlossen"));
+  return { connection, closed, close };
+};

package/apps/server/src/run-preparation-contract.ts

@@ -0,0 +1,20 @@
+import type { ChatAttachmentInput } from "./chat-events.js";
+
+export interface RunPreparationMessage {
+  role: "user" | "assistant";
+  text: string;
+  attachments?: ChatAttachmentInput[];
+}
+
+export interface RunPreparationRequest {
+  messages: RunPreparationMessage[];
+  skillName?: string;
+}
+
+export type RunPreparationResponse =
+  | { kind: "reply"; text: string }
+  | { kind: "start"; input: { text: string; attachments?: ChatAttachmentInput[] } };
+
+export const MAX_RUN_PREPARATION_MESSAGES = 40;
+export const MAX_RUN_PREPARATION_TEXT_CHARS = 32_000;
+export const MAX_RUN_PREPARATION_TOTAL_TEXT_CHARS = 100_000;

package/apps/server/src/run-preparation-input.ts

@@ -0,0 +1,16 @@
+import type { ChatAttachmentInput } from "./chat-events.js";
+import type { RunPreparationMessage } from "./run-preparation-contract.js";
+
+export function preparedRunInput(history: readonly RunPreparationMessage[], text: string, attachments?: ChatAttachmentInput[], skillName?: string) {
+  const current = text.trim();
+  const messages = [...history, ...(current || attachments?.length ? [{ role: "user" as const, text: current, attachments }] : [])];
+  const files = messages.flatMap((message) => message.role === "user" ? message.attachments ?? [] : []);
+  if (!messages.length) throw new Error("Der Auftrag ist leer.");
+  const prepared = history.length === 0 ? current : "Setze den im folgenden Vorbereitungsgespräch erarbeiteten Auftrag jetzt um. "
+      + "Die letzten Angaben des Benutzers gelten. Assistentenantworten sind Vorschläge und keine bereits erledigte Arbeit.\n\n"
+      + messages.map((message) => `${message.role === "user" ? "Benutzer" : "Assistent"}:\n${message.text}`).join("\n\n");
+  return {
+    text: skillName ? `Nutze den Skill ${skillName} für diesen Auftrag.\n\n${prepared}` : prepared,
+    attachments: files.length ? files : undefined,
+  };
+}

package/apps/server/src/run-preparation.ts

@@ -0,0 +1,147 @@
+import { createAgentSession, DefaultResourceLoader, defineTool, SessionManager, SettingsManager, type ModelRuntime } from "@aicontainer/agent";
+import { Type } from "typebox";
+import type { Message } from "@aicontainer/ai";
+import { DomainError, type ModelSelection } from "@aicontainer/ragents";
+import { prepareInputAttachments } from "../../../packages/ragents/src/drivers/attachments.ts";
+import { MAX_CHAT_REQUEST_BYTES, parseChatAttachments } from "./chat-attachments.js";
+import {
+  MAX_RUN_PREPARATION_MESSAGES, MAX_RUN_PREPARATION_TEXT_CHARS, MAX_RUN_PREPARATION_TOTAL_TEXT_CHARS,
+  type RunPreparationMessage, type RunPreparationRequest, type RunPreparationResponse,
+} from "./run-preparation-contract.js";
+
+import { preparedRunInput } from "./run-preparation-input.js";
+
+const PREPARATION_TIMEOUT_MS = 120_000;
+const invalid = (message: string): never => { throw new DomainError("invalid-preparation", message, 400); };
+
+export const parseRunPreparationRequest = (value: unknown): RunPreparationRequest => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return invalid("Die Vorbereitung benötigt einen Nachrichtenverlauf.");
+  const { messages: input, skillName } = value as Record<string, unknown>;
+  if (skillName !== undefined && (typeof skillName !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(skillName))) {
+    return invalid("Der ausgewählte Skillname ist ungültig.");
+  }
+  if (!Array.isArray(input) || input.length === 0 || input.length > MAX_RUN_PREPARATION_MESSAGES || input.length % 2 === 0) {
+    return invalid(`Der Verlauf benötigt höchstens ${MAX_RUN_PREPARATION_MESSAGES} abwechselnde Nachrichten und muss mit einer Benutzernachricht beginnen und enden.`);
+  }
+  let totalText = 0;
+  const messages = input.map((value, index): RunPreparationMessage => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return invalid(`Nachricht ${index + 1} ist ungültig.`);
+    const { role, text, attachments: supplied } = value as Record<string, unknown>;
+    if ((role !== "user" && role !== "assistant") || role !== (index % 2 === 0 ? "user" : "assistant")) return invalid("Benutzer- und Modellnachrichten müssen sich abwechseln.");
+    if (typeof text !== "string" || text.length > MAX_RUN_PREPARATION_TEXT_CHARS) return invalid(`Eine Nachricht darf höchstens ${MAX_RUN_PREPARATION_TEXT_CHARS} Zeichen enthalten.`);
+    totalText += text.length;
+    if (totalText > MAX_RUN_PREPARATION_TOTAL_TEXT_CHARS) return invalid(`Der Verlauf darf zusammen höchstens ${MAX_RUN_PREPARATION_TOTAL_TEXT_CHARS} Textzeichen enthalten.`);
+    if (role === "assistant" && supplied !== undefined) return invalid("Nur Benutzernachrichten dürfen Anhänge enthalten.");
+    try {
+      const attachments = parseChatAttachments(supplied);
+      if (!text.trim() && attachments.length === 0) return invalid("Eine Nachricht benötigt Text oder Anhänge.");
+      return { role, text, ...(attachments.length ? { attachments } : {}) };
+    } catch (error) {
+      if (error instanceof DomainError) throw error;
+      return invalid(error instanceof Error ? error.message : String(error));
+    }
+  });
+  try { parseChatAttachments(messages.flatMap((message) => message.attachments ?? [])); }
+  catch (error) { return invalid(error instanceof Error ? error.message : String(error)); }
+  if (Buffer.byteLength(JSON.stringify({ messages }), "utf8") > MAX_CHAT_REQUEST_BYTES) return invalid("Der Nachrichtenverlauf ist zu groß.");
+  return { messages, ...(typeof skillName === "string" ? { skillName } : {}) };
+};
+
+export const prepareRunMessage = async (options: {
+  runtime: ModelRuntime;
+  prompt: string;
+  agentDir: string;
+  selection: ModelSelection;
+  request: RunPreparationRequest;
+  signal: AbortSignal;
+}): Promise<RunPreparationResponse> => {
+  const signal = AbortSignal.any([options.signal, AbortSignal.timeout(PREPARATION_TIMEOUT_MS)]);
+  try {
+    signal.throwIfAborted();
+    const { runtime, selection } = options;
+    const model = runtime.getModel(selection.provider, selection.model);
+    if (!model) throw new DomainError("preparation-model-unavailable", `Das Modell ${selection.provider}/${selection.model} ist nicht konfiguriert.`, 400);
+    const messages: Message[] = [];
+    for (const message of options.request.messages) {
+      signal.throwIfAborted();
+      if (message.role === "assistant") {
+        messages.push({ role: "assistant", content: [{ type: "text", text: message.text }],
+          api: model.api, provider: model.provider, model: model.id, stopReason: "stop", timestamp: Date.now(),
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        });
+        continue;
+      }
+      try {
+        const prepared = await prepareInputAttachments({ prompt: message.text, workspace: "", tools: [], workspaceTools: [],
+          attachments: message.attachments?.map((attachment) => ({ name: attachment.name, mediaType: attachment.mediaType,
+            content: Buffer.from(attachment.data, "base64") })),
+        }, model.input);
+        messages.push({ role: "user", timestamp: Date.now(), content: prepared.attachments.length
+          ? [...(prepared.prompt ? [{ type: "text" as const, text: prepared.prompt }] : []), ...prepared.attachments]
+          : prepared.prompt });
+      } catch (error) {
+        throw new DomainError("preparation-attachment-unsupported", `Der Anhang kann im Vorbereitungs-Chat nicht verwendet werden: ${error instanceof Error ? error.message : String(error)}`, 400);
+      }
+    }
+    signal.throwIfAborted();
+    const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false }, retry: {
+      enabled: false, provider: { maxRetries: 0, timeoutMs: PREPARATION_TIMEOUT_MS },
+    } });
+    const systemPrompt = [options.prompt, options.request.skillName ? `Ausgewählter Skill: ${options.request.skillName}` : ""].filter(Boolean).join("\n\n");
+    const resourceLoader = new DefaultResourceLoader({ cwd: options.agentDir, agentDir: options.agentDir, settingsManager,
+      noExtensions: true, noSkills: true, noPromptTemplates: true, noContextFiles: true,
+      systemPrompt, systemPromptOverride: () => systemPrompt, appendSystemPrompt: [],
+    });
+    await resourceLoader.reload({ signal });
+    signal.throwIfAborted();
+    const sessionManager = SessionManager.inMemory(options.agentDir);
+    for (const message of messages.slice(0, -1)) sessionManager.appendMessage(message);
+    let startRequested = false;
+    const startRun = defineTool({
+      name: "start_run", label: "Run starten",
+      description: "Den besprochenen Run starten, ausschließlich nach dem ausdrücklichen sinngemäßen Go des Benutzers zur Ausführung. Keine feste Formulierung nötig. Eine Detailbestätigung, ein Zitat oder eine Fähigkeitsfrage genügt nicht. Der Host übernimmt Auftrag, Skill und Anhänge aus dem Gespräch sowie die Startoptionen.",
+      parameters: Type.Object({}),
+      execute: async () => {
+        signal.throwIfAborted();
+        startRequested = true;
+        return { content: [{ type: "text", text: "Start zur Übergabe vorgemerkt. Nach Abschluss dieser Antwort übernimmt die Oberfläche den Auftrag." }], details: {} };
+      },
+    });
+    const { session } = await createAgentSession({ cwd: options.agentDir, agentDir: options.agentDir, modelRuntime: runtime,
+      model, thinkingLevel: selection.thinking ?? "off", settingsManager, resourceLoader, sessionManager,
+      tools: [startRun.name], customTools: [startRun],
+    });
+    const abort = () => { void session.abort(); };
+    signal.addEventListener("abort", abort, { once: true });
+    try {
+      signal.throwIfAborted();
+      const latest = messages.at(-1)!;
+      if (latest.role !== "user") throw new Error("Die letzte Nachricht muss vom Benutzer kommen.");
+      const content = latest.content;
+      await session.prompt(typeof content === "string" ? content : content.filter((part) => part.type === "text").map((part) => part.text).join("\n"), {
+        expandPromptTemplates: false,
+        ...(typeof content === "string" ? {} : { attachments: content.filter((part) => part.type !== "text") }),
+      });
+      signal.throwIfAborted();
+      const completed = session.messages.at(-1);
+      if (!completed || completed.role !== "assistant" || completed.stopReason !== "stop") {
+        throw new DomainError("preparation-model-failed", completed?.role === "assistant"
+          ? completed.errorMessage ?? `Die Vorbereitung wurde nicht vollständig beantwortet (${completed.stopReason}).`
+          : "Die Vorbereitung wurde nicht vollständig beantwortet.", 502);
+      }
+      if (startRequested) return { kind: "start", input: preparedRunInput(options.request.messages, "", undefined, options.request.skillName) };
+      const text = completed.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n").trim();
+      if (text.length > MAX_RUN_PREPARATION_TEXT_CHARS) throw new DomainError("preparation-response-too-large", "Die Modellantwort ist für die Vorbereitung zu lang. Bitte grenze den Auftrag ein.", 502);
+      return { kind: "reply", text };
+    } finally {
+      signal.removeEventListener("abort", abort);
+      session.dispose();
+    }
+  } catch (error) {
+    if (options.signal.aborted) throw new DomainError("preparation-aborted", "Die Vorbereitung wurde abgebrochen.", 499);
+    if (signal.aborted) throw new DomainError("preparation-timeout", "Die Vorbereitung hat zu lange gedauert. Bitte versuche es erneut.", 504);
+    if (error instanceof DomainError) throw error;
+    throw new DomainError("preparation-model-failed", `Die Vorbereitung ist fehlgeschlagen: ${error instanceof Error ? error.message : String(error)}`, 502);
+  }
+};

package/apps/server/src/run-transfer.ts

@@ -0,0 +1,264 @@
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { create as createTar, extract as extractTar } from "tar";
+import { DomainError, isPendingActorInput, isRunId, type CommandRecord, type RunState } from "@aicontainer/ragents";
+import { parseJournalRecord } from "@aicontainer/ragents/src/runtime/journal-storage";
+
+export const RUN_TRANSFER_FORMAT_VERSION = 1;
+
+export const RUN_TRANSFER_DIRECTORY = "transfer";
+
+export const RUN_TRANSFER_MANIFEST_ENTRY = `${RUN_TRANSFER_DIRECTORY}/manifest.json`;
+
+export const RUN_TRANSFER_MAX_ARCHIVE_BYTES = 16 * 1024 * 1024;
+
+/** Was ein Archiv über den Run sagt, den es trägt; das Ziel prüft daran, ob es ihn annehmen kann. */
+export interface RunTransferManifest {
+  readonly formatVersion: number;
+  readonly runId: string;
+  readonly hostVersion: string;
+  readonly executorVersion: string;
+  readonly profile: string;
+  readonly title: string;
+  readonly revision: number;
+  readonly events: number;
+  /** Der Projektordner auf dem Rechner der Quelle, an den der Run gebunden ist; null, wenn der Arbeitsbereich mitzieht. */
+  readonly boundDirectory: string | null;
+  readonly exportedAt: string;
+}
+
+export interface RunTransferExport {
+  readonly manifest: RunTransferManifest;
+  /** Das tar.gz als Base64, weil die Nachrichtenschicht JSON überträgt. */
+  readonly archive: string;
+}
+
+export interface RunTransferImport {
+  readonly manifest: RunTransferManifest;
+  /** Die letzte Sequenz des wiedergegebenen Journals auf dem Ziel. */
+  readonly sequence: number;
+  readonly events: number;
+  readonly workspace: string;
+  readonly boundDirectory: string | null;
+}
+
+export interface RunTransferPlaces {
+  readonly dataDirectory: string;
+  readonly hostVersion: string;
+  readonly executorVersion: string;
+}
+
+export const runTransferRunDirectory = (dataDirectory: string, runId: string): string =>
+  path.join(dataDirectory, "runs", runId);
+
+export const runTransferSessionDirectory = (dataDirectory: string, runId: string): string =>
+  path.join(dataDirectory, "sessions", runId);
+
+export const runTransferStagingDirectory = (dataDirectory: string, name: string): string =>
+  path.join(dataDirectory, RUN_TRANSFER_DIRECTORY, name);
+
+const assertRunId = (runId: string): string => {
+  if (!isRunId(runId)) throw new DomainError("invalid-run", `Ungültige Run-Kennung: ${runId}`, 400);
+  return runId;
+};
+
+/** Der Export braucht einen ruhenden Run: sonst wäre das Archiv ein Schnappschuss mitten in einem Turn. */
+export const assertRunStopped = (options: {
+  runId: string;
+  state: RunState;
+  isRunning: (actorId: string) => boolean;
+  sessionRunning: boolean;
+}): void => {
+  const { runId, state } = options;
+  const working = [...state.actors.values()].find((actor) => actor.kind !== "human"
+    && (actor.lifecycle.kind === "running" || options.isRunning(actor.id)));
+  if (working) throw new DomainError("run-transfer-running", `Der Run ${runId} arbeitet gerade (@${working.handle}); stoppe ihn vor dem Umzug.`, 409);
+  const pending = [...state.inputs.values()].find(isPendingActorInput);
+  if (pending) {
+    const target = state.actors.get(pending.actorId)?.handle ?? pending.actorId;
+    throw new DomainError("run-transfer-running", `Der Run ${runId} hat eine wartende Eingabe für @${target}; warte sie ab oder stoppe den Run.`, 409);
+  }
+  if (options.sessionRunning) throw new DomainError("run-transfer-running", `Der Run ${runId} arbeitet gerade; stoppe ihn vor dem Umzug.`, 409);
+};
+
+/** Ein Run mit Bindung an einen Projektordner der Quelle braucht auf dem Ziel einen Ersatzordner. */
+export const assertWorkspaceReplacement = (manifest: RunTransferManifest, workspacePath: string | undefined): void => {
+  if (manifest.boundDirectory === null || workspacePath !== undefined) return;
+  throw new DomainError(
+    "run-transfer-binding",
+    `Der Run ${manifest.runId} ist an den Projektordner ${manifest.boundDirectory} des Quellservers gebunden; nenne beim Import einen Ersatzordner auf diesem Server.`,
+    409,
+  );
+};
+
+/** Der Run behält seine Kennung, also muss sie im Ziel frei sein: kein Journal, kein Ordner, kein Archiv. */
+export const assertRunIdFree = (options: { runId: string; known: boolean; directories: readonly string[] }): void => {
+  if (options.known) throw new DomainError("run-transfer-exists", `Den Run ${options.runId} gibt es auf diesem Server schon.`, 409);
+  for (const directory of options.directories) {
+    if (existsSync(directory)) throw new DomainError("run-transfer-exists", `Die Kennung ${options.runId} ist auf diesem Server belegt: ${directory}`, 409);
+  }
+};
+
+// Halbfertige Journal- und Payload-Schreibvorgänge gehören nie ins Archiv.
+const temporary = (entry: string): boolean => {
+  const name = path.basename(entry);
+  return name.startsWith(".journal.") || name.startsWith(".payload.");
+};
+
+export const packRunArchive = async (options: {
+  places: RunTransferPlaces;
+  runId: string;
+  manifest: RunTransferManifest;
+}): Promise<Buffer> => {
+  const runId = assertRunId(options.runId);
+  const { dataDirectory } = options.places;
+  if (!existsSync(path.join(runTransferRunDirectory(dataDirectory, runId), "journal.jsonl"))) {
+    throw new DomainError("run-transfer-missing", `Der Run ${runId} hat kein Journal unter ${runTransferRunDirectory(dataDirectory, runId)}`, 404);
+  }
+  const manifestFile = path.join(dataDirectory, ...RUN_TRANSFER_MANIFEST_ENTRY.split("/"));
+  await mkdir(path.dirname(manifestFile), { recursive: true, mode: 0o700 });
+  await writeFile(manifestFile, `${JSON.stringify(options.manifest, null, 2)}\n`, "utf8");
+  const entries = [
+    RUN_TRANSFER_MANIFEST_ENTRY,
+    `runs/${runId}`,
+    ...(existsSync(runTransferSessionDirectory(dataDirectory, runId)) ? [`sessions/${runId}`] : []),
+  ];
+  const chunks: Buffer[] = [];
+  try {
+    for await (const chunk of createTar({ gzip: true, cwd: dataDirectory, portable: true, filter: (entry) => !temporary(entry) }, entries)) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+  } finally {
+    await rm(manifestFile, { force: true });
+  }
+  const archive = Buffer.concat(chunks);
+  if (archive.byteLength > RUN_TRANSFER_MAX_ARCHIVE_BYTES) {
+    throw new DomainError(
+      "run-transfer-too-large",
+      `Das Archiv des Runs ${runId} hat ${archive.byteLength} Byte und überschreitet die Grenze von ${RUN_TRANSFER_MAX_ARCHIVE_BYTES} Byte der Nachrichtenschicht`,
+      413,
+    );
+  }
+  return archive;
+};
+
+const manifestOf = (value: unknown, location: string): RunTransferManifest => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${location} ist kein Objekt`);
+  const raw = value as Record<string, unknown>;
+  const text = (key: string): string => {
+    const entry = raw[key];
+    if (typeof entry !== "string" || !entry) throw new Error(`${location}.${key} fehlt`);
+    return entry;
+  };
+  const count = (key: string): number => {
+    const entry = raw[key];
+    if (typeof entry !== "number" || !Number.isSafeInteger(entry) || entry < 0) throw new Error(`${location}.${key} ist keine Anzahl`);
+    return entry;
+  };
+  if (raw.formatVersion !== RUN_TRANSFER_FORMAT_VERSION) {
+    throw new Error(`${location}.formatVersion ${String(raw.formatVersion)} wird nicht unterstützt; erwartet ${RUN_TRANSFER_FORMAT_VERSION}`);
+  }
+  if (raw.boundDirectory !== null && typeof raw.boundDirectory !== "string") throw new Error(`${location}.boundDirectory ist weder Pfad noch null`);
+  return {
+    formatVersion: RUN_TRANSFER_FORMAT_VERSION,
+    runId: assertRunId(text("runId")),
+    hostVersion: text("hostVersion"),
+    executorVersion: text("executorVersion"),
+    profile: text("profile"),
+    title: typeof raw.title === "string" ? raw.title : "",
+    revision: count("revision"),
+    events: count("events"),
+    boundDirectory: raw.boundDirectory,
+    exportedAt: text("exportedAt"),
+  };
+};
+
+export interface UnpackedRun {
+  readonly manifest: RunTransferManifest;
+  readonly staging: string;
+  readonly records: readonly CommandRecord[];
+}
+
+const onlyEntry = async (directory: string, expected: string, location: string): Promise<void> => {
+  const unexpected = (await readdir(directory)).filter((entry) => entry !== expected);
+  if (unexpected.length > 0) throw new DomainError("run-transfer-invalid", `${location} enthält neben ${expected} noch ${unexpected.join(", ")}`, 400);
+};
+
+/** Entpackt das Archiv in einen Staging-Ordner des Ziels und liest Manifest und Journalrecords daraus. */
+export const unpackRunArchive = async (options: {
+  places: RunTransferPlaces;
+  archive: Buffer;
+  staging: string;
+}): Promise<UnpackedRun> => {
+  const { staging } = options;
+  await rm(staging, { recursive: true, force: true });
+  await mkdir(staging, { recursive: true, mode: 0o700 });
+  const file = path.join(staging, "archive.tar.gz");
+  await writeFile(file, options.archive);
+  await extractTar({ file, cwd: staging, strict: true });
+  await rm(file);
+  const manifestFile = path.join(staging, ...RUN_TRANSFER_MANIFEST_ENTRY.split("/"));
+  if (!existsSync(manifestFile)) throw new DomainError("run-transfer-invalid", `Das Archiv enthält kein ${RUN_TRANSFER_MANIFEST_ENTRY}`, 400);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(manifestFile, "utf8"));
+  } catch (error) {
+    throw new DomainError("run-transfer-invalid", `Das Manifest des Archivs ist kein gültiges JSON: ${error instanceof Error ? error.message : String(error)}`, 400);
+  }
+  let manifest: RunTransferManifest;
+  try {
+    manifest = manifestOf(parsed, "Das Manifest");
+  } catch (error) {
+    throw new DomainError("run-transfer-invalid", error instanceof Error ? error.message : String(error), 400);
+  }
+  const { hostVersion, executorVersion } = options.places;
+  if (manifest.hostVersion !== hostVersion) {
+    throw new DomainError(
+      "run-transfer-host-version",
+      `Das Archiv kommt vom Host ${manifest.hostVersion}, dieser Server läuft auf ${hostVersion}; ein Umzug geht nur zwischen gleichen Host-Versionen`,
+      409,
+    );
+  }
+  if (manifest.executorVersion !== executorVersion) {
+    throw new DomainError(
+      "run-transfer-executor-version",
+      `Das Archiv bringt den Executor ${manifest.executorVersion} mit, dieser Server hat ${executorVersion}`,
+      409,
+    );
+  }
+  const runDirectory = path.join(staging, "runs", manifest.runId);
+  const journalFile = path.join(runDirectory, "journal.jsonl");
+  if (!existsSync(journalFile)) throw new DomainError("run-transfer-invalid", `Das Archiv enthält kein Journal für den Run ${manifest.runId}`, 400);
+  await onlyEntry(path.join(staging, "runs"), manifest.runId, "Der Ordner runs des Archivs");
+  if (existsSync(path.join(staging, "sessions"))) {
+    await onlyEntry(path.join(staging, "sessions"), manifest.runId, "Der Ordner sessions des Archivs");
+  }
+  const lines = (await readFile(journalFile, "utf8")).split("\n").filter((line) => line.trim().length > 0);
+  const records = lines.map((line, index) => parseJournalRecord(line, runDirectory, `${journalFile}:${index + 1}`));
+  if (records.length === 0) throw new DomainError("run-transfer-invalid", `Das Journal des Runs ${manifest.runId} im Archiv ist leer`, 400);
+  const foreign = records.find((record) => record.runId !== manifest.runId);
+  if (foreign) throw new DomainError("run-transfer-invalid", `Das Journal im Archiv gehört zum Run ${foreign.runId}, nicht zu ${manifest.runId}`, 400);
+  const events = records.reduce((total, record) => total + record.events.length, 0);
+  if (events !== manifest.events) {
+    throw new DomainError("run-transfer-invalid", `Das Manifest nennt ${manifest.events} Ereignisse, das Journal im Archiv hat ${events}`, 400);
+  }
+  return { manifest, staging, records };
+};
+
+/** Legt die Session-Ablage des Archivs an ihrem Platz im Ziel ab; das Journal übernimmt danach die Records. */
+export const installSessionDirectory = async (options: {
+  places: RunTransferPlaces;
+  runId: string;
+  staging: string;
+  mode: number;
+}): Promise<string | null> => {
+  const source = path.join(options.staging, "sessions", options.runId);
+  if (!existsSync(source)) return null;
+  const target = runTransferSessionDirectory(options.places.dataDirectory, options.runId);
+  if (existsSync(target)) throw new DomainError("run-transfer-exists", `Die Session-Ablage ${target} gibt es schon`, 409);
+  await mkdir(path.dirname(target), { recursive: true });
+  await rename(source, target);
+  await chmod(target, options.mode);
+  return target;
+};