@schlenkr/ragents 0.1.5 → 0.1.7

package/apps/server/src/ragents/typescript-tools.ts

@@ -1,26 +1,25 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { Type } from "typebox";
 import {
     assertJsonValue,
     defineRunFunction,
     defineToolAvailability,
     executeTypeScriptSnippet,
-    typeScriptSnippetDeclarations,
+    runCapabilityDeclarations,
+    typeScriptSnippetContextDeclarations,
     type RunCapabilityDescriptor,
     type RunFunction,
     type PluginHost,
     type ToolContributor,
     type ToolScope,
-} from "@aicontainer/ragents";
-import { allowedWorkspacePath, expandWorkspaceAlias, type WorkspaceProcessContext } from "@aicontainer/workspace-executor";
-import { sandboxServicesToken } from "../plugin-support/workspace-sandbox-host.js";
+} from "@ragents/engine";
+import { FILE_OPERATIONS, type FileText, type WorkspaceProcessContext } from "@ragents/workspace-executor";
+import { sandboxServicesToken, type SandboxServices } from "../plugin-support/workspace-sandbox-host.js";
 
 const metadata = [
     {
         name: "typescript_api",
         label: "TypeScript API",
-        description: "Discover the typed functions available to this actor. Omit names for a compact searchable list; pass exact names for their TypeScript declarations with field documentation and the matching guidance. JSON schemas with validation constraints are added only on request. Functions are called as await context.functions.name(input) from snippets and actor programs.",
+        description: "Discover the typed functions available to this actor. Omit names for a compact searchable list; pass exact names for their entries in RAgentsCapabilityMap with field documentation and the matching guidance. JSON schemas with validation constraints are added only on request. Functions are called as await context.functions.name(input) from snippets and actor programs; context: true returns the declarations of context itself once.",
     },
     {
         name: "typescript_eval",
@@ -35,7 +34,10 @@ const available = defineToolAvailability({
 }, (actor) => actor.kind !== "human" && actor.lifecycle.kind !== "stopped");
 
 export interface TypeScriptToolOptions {
-    readonly processContextFor: (runId: string) => Promise<WorkspaceProcessContext>;
+    /** Das Snippet läuft auf dem Server, auch wenn der Arbeitsbereich auf einem Arbeitsplatz liegt. */
+    readonly serverProcessContextFor: (runId: string) => Promise<WorkspaceProcessContext>;
+    /** Eine Quelldatei kommt über den Executor des Runs, wo immer der Arbeitsbereich liegt. */
+    readonly execute: SandboxServices["execute"];
 }
 
 const functionsOf = (scope: ToolScope): readonly RunFunction[] => scope.availableFunctions()
@@ -59,17 +61,26 @@ const apiEntrySchema = Type.Object({
     resultSchema: Type.Optional(Type.Unknown()),
 }, { additionalProperties: false });
 
+const contextGuidance = "The context belongs to the calling actor: functions act as context.principal. In a snippet, context.state starts as {} and is discarded when it finishes. Actor programs retain their declared state and can receive later inputs. TypeScript checks calls against the declared input and result types before execution; schema constraints are also validated by the host.";
+
 const schemaJson = (schema: RunFunction["schema"]) => {
     const value: unknown = JSON.parse(JSON.stringify(schema));
     assertJsonValue(value, "Function schema");
     return value;
 };
 
-const sourceOf = async (input: { code?: string; path?: string }, context: WorkspaceProcessContext): Promise<string> => {
+/** Ein Alias wie `@actors` nennt eine zusätzliche Wurzel des Executors, sonst gilt der Pfad relativ zur Wurzel des Runs. */
+const sourceRequest = (requested: string): { path: string; alias?: string } => {
+    if (!requested.startsWith("@")) return { path: requested };
+    const separator = requested.indexOf("/");
+    return separator < 0 ? { alias: requested, path: "" } : { alias: requested.slice(0, separator), path: requested.slice(separator + 1) };
+};
+
+const sourceOf = async (options: TypeScriptToolOptions, runId: string, toolCallId: string, input: { code?: string; path?: string }): Promise<string> => {
     if (input.code !== undefined) return input.code;
-    const requested = expandWorkspaceAlias(input.path!, context.workspaceAliases ?? {});
-    const filename = await allowedWorkspacePath(path.resolve(context.cwd, requested), [context.root, context.cwd, ...context.additionalRoots ?? []]);
-    return readFile(filename, "utf8");
+    const text = await options.execute(runId, FILE_OPERATIONS.read, sourceRequest(input.path!), { toolCallId }) as FileText;
+    if (!text.previewable) throw new Error(`${input.path}: ${text.reason}`);
+    return text.content;
 };
 
 export const createTypeScriptToolContributor = (options: TypeScriptToolOptions): ToolContributor => {
@@ -83,13 +94,16 @@ export const createTypeScriptToolContributor = (options: TypeScriptToolOptions):
                 query: Type.Optional(Type.String({ minLength: 1, description: "Search names and descriptions. Omit for all available names." })),
                 names: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1, uniqueItems: true, description: "Exact function names whose complete declarations and guidance are needed." })),
                 schemas: Type.Optional(Type.Boolean({ description: "With names: also return the JSON schemas including validation constraints such as lengths and patterns." })),
+                context: Type.Optional(Type.Boolean({ description: "Alone: the declarations of context itself (run, actor, state, log, std with mediators), the same for every function." })),
             }, { additionalProperties: false }),
             resultSchema: Type.Object({
-                functions: Type.Array(apiEntrySchema),
+                functions: Type.Optional(Type.Array(apiEntrySchema)),
                 declarations: Type.Optional(Type.String()),
                 guidance: Type.Optional(Type.String()),
             }, { additionalProperties: false }),
             run: async (scope, _id, input) => {
+                if (input.context && (input.names || input.query !== undefined || input.schemas)) throw new Error("typescript_api erwartet context allein, ohne names, query oder schemas.");
+                if (input.context) return { declarations: typeScriptSnippetContextDeclarations, guidance: contextGuidance };
                 if (input.names && input.query !== undefined) throw new Error("typescript_api erwartet names oder query, nicht beides.");
                 if (input.schemas && !input.names) throw new Error("typescript_api liefert JSON-Schemas nur zu ausgewählten names.");
                 const functions = functionsOf(scope);
@@ -100,19 +114,15 @@ export const createTypeScriptToolContributor = (options: TypeScriptToolOptions):
                 const query = input.query?.toLocaleLowerCase();
                 const selected = input.names ? functions.filter((entry) => input.names!.includes(entry.name))
                     : query ? functions.filter((entry) => `${entry.name} ${entry.label} ${entry.description}`.toLocaleLowerCase().includes(query)) : functions;
+                const guidance = input.names ? await scope.functionGuidance(input.names) : "";
                 return {
                     functions: selected.map(({ name, label, description, longDescription, schema, resultSchema }) => ({
                         name, label, description,
                         ...(input.names && longDescription ? { longDescription } : {}),
                         ...(input.schemas ? { inputSchema: schemaJson(schema), resultSchema: schemaJson(resultSchema) } : {}),
                     })),
-                    ...(input.names ? {
-                        declarations: typeScriptSnippetDeclarations(selected.map(descriptorOf)),
-                        guidance: [
-                            "The context belongs to the calling actor: functions act as context.principal. In a snippet, context.state starts as {} and is discarded when it finishes. Actor programs retain their declared state and can receive later inputs. TypeScript checks calls against the declared input and result types before execution; schema constraints are also validated by the host.",
-                            await scope.functionGuidance(input.names),
-                        ].filter(Boolean).join("\n\n"),
-                    } : {}),
+                    ...(input.names ? { declarations: runCapabilityDeclarations(selected.map(descriptorOf)) } : {}),
+                    ...(guidance ? { guidance } : {}),
                 };
             },
         }),
@@ -131,8 +141,8 @@ export const createTypeScriptToolContributor = (options: TypeScriptToolOptions):
                 scope.signal?.throwIfAborted();
                 const actor = scope.runtime.view(scope.caller.runId).actors.find((candidate) => candidate.id === scope.caller.actorId);
                 if (!actor || actor.kind === "human" || actor.lifecycle.kind === "stopped") throw new Error("Das TypeScript-Snippet braucht einen aktiven ausführbaren Actor.");
-                const processContext = await options.processContextFor(scope.caller.runId);
-                const code = await sourceOf(input, processContext);
+                const code = await sourceOf(options, scope.caller.runId, id, input);
+                const processContext = await options.serverProcessContextFor(scope.caller.runId);
                 if (!scope.caller.turnId) throw new Error("Das TypeScript-Snippet braucht einen laufenden Turn.");
                 scope.runtime.recordToolCallSource(scope.context(id, "source"), scope.caller.runId, actor.id, {
                     turnId: scope.caller.turnId, toolCallId: id, code, path: input.path ?? null,
@@ -171,12 +181,10 @@ export const createTypeScriptToolContributor = (options: TypeScriptToolOptions):
     };
 };
 
-const registeredHosts = new WeakSet<PluginHost>();
-
+/** The profile registers them once while composing; the engine finds them among the tools of the host. */
 export const registerTypeScriptFunctions = (host: PluginHost): void => {
-    if (registeredHosts.has(host)) return;
     host.tools.register("ragents.runtime", [createTypeScriptToolContributor({
-        processContextFor: (runId) => host.service(sandboxServicesToken).processContextFor(runId),
+        serverProcessContextFor: (runId) => host.service(sandboxServicesToken).serverProcessContextFor(runId),
+        execute: (runId, operation, input, options) => host.service(sandboxServicesToken).execute(runId, operation, input, options),
     })]);
-    registeredHosts.add(host);
 };

package/apps/server/src/ragents/workspace-runtime.ts

@@ -1,14 +1,24 @@
-import { serviceToken, type JsonValue, type WorkspaceToolNaming } from "@aicontainer/ragents";
-import type { ResolvedWorkspaceRoot } from "@aicontainer/workspace-executor";
+import { serviceToken, type JsonValue, type WorkspaceToolNaming } from "@ragents/engine";
+import type { ResolvedWorkspaceRoot, SessionIdent } from "@ragents/workspace-executor";
+
+/** Ein Ordner außerhalb des Arbeitsbereichs, den die Prozess-Sandbox eines Runs zulässt; absolut, zum Lesen oder zum Lesen und Schreiben. */
+export interface SandboxFolder {
+  directory: string;
+  access: "read" | "write";
+}
 
 export interface SessionWorkspace {
   cwd: string;
-  hostSandbox?: { home: string; readOnlyRoots: readonly ResolvedWorkspaceRoot[] };
+  /** Beschreibt den aufgelösten Arbeitsbereich in Worten; wird Kapitel im Systemprompt jedes Actors mit Arbeitsbereichswerkzeugen. */
+  description?: string;
+  /** Heimatordner, nur lesbare Wurzeln und Konto der Sandbox, wenn der Arbeitsbereich sie selbst bestimmt. */
+  hostSandbox?: { home: string; readOnlyRoots: readonly ResolvedWorkspaceRoot[]; ident?: SessionIdent };
+  /** Was Prozesse des Runs auf dem Server außerhalb des Arbeitsbereichs brauchen, etwa das gemeinsame Repository eines Git-Worktrees. */
+  sandboxFolders?: readonly SandboxFolder[];
   gitEnv?: NodeJS.ProcessEnv;
   gitConfig?: ReadonlyArray<readonly [string, string]>;
   extraEnv?: NodeJS.ProcessEnv;
   currentRoot: () => Promise<string>;
-  ensureWritable: () => Promise<string>;
   runOperation: <T>(operation: () => Promise<T>) => Promise<T>;
 }
 
@@ -19,7 +29,7 @@ export interface WorkspaceRuntimeDescription {
 
 /** Umzug eines Runs auf einen anderen Server: was seine Bindung dort bedeutet und wie das Ziel sie ersetzt. */
 export interface WorkspaceTransfer {
-  /** Der Projektordner auf diesem Serverrechner, an den der Run gebunden ist; null, wenn der Arbeitsbereich in der Session-Ablage liegt. */
+  /** Der vorhandene Ordner auf diesem Serverrechner, an den der Run gebunden ist; null bei einem neuen Ordner je Run oder einem Arbeitsplatz. */
   boundDirectory: (runId: string) => string | null;
   /** Prüft einen Ersatzordner, bevor der Import etwas anlegt. */
   assertDirectory: (directory: string) => void;
@@ -27,9 +37,19 @@ export interface WorkspaceTransfer {
   rebind: (runId: string, directory: string) => void;
 }
 
+/** Wo und in welchem Ordner ein Run arbeitet, getrennt beantwortet; ein Ablauf fragt beides, nie einen Mischwert. */
+export interface WorkspacePlacement {
+  machine: "server" | "client";
+  folder: "fresh" | "existing";
+  /** Die Kennung der Art (`WorkspaceKind.id`), wenn ein Beitrag den neuen Ordner gestellt hat. */
+  kind?: string;
+}
+
 export interface WorkspaceRuntime {
   resolve: (runId: string, emitSystem: (text: string) => void) => Promise<SessionWorkspace>;
   describe: () => WorkspaceRuntimeDescription;
+  /** Die eine Stelle, an der ein Ablauf zentral fragt, wo und in welchem Ordner ein Run arbeitet. */
+  placementOf: (runId: string) => WorkspacePlacement;
   toolNaming?: WorkspaceToolNaming;
   transfer?: WorkspaceTransfer;
 }
@@ -43,14 +63,59 @@ export interface WorkspaceResolverContext {
   emitSystem: (text: string) => void;
 }
 
-export interface WorkspaceResolution {
+/** Was ein Beitrag zum Arbeitsbereich eines Runs liefert; was er weglässt, ergänzt das Arbeitsbereich-Plugin. */
+export interface WorkspaceResolution extends Partial<Omit<SessionWorkspace, "cwd">> {
   cwd: string;
-  extraEnv?: NodeJS.ProcessEnv;
+}
+
+/** Die Art von Arbeitsbereich, die ein Plugin je Run auf dem Server an Stelle des leeren Ordners beisteuert. */
+export interface WorkspaceKind {
+  /** Kennung, an der ein Ablauf den Arbeitsbereich eines Runs erkennt. */
+  id: string;
+  /** Kurzform für Startoption und Sitzungsdaten, etwa "Worktree je Run". */
+  label: string;
+  /** Ob daneben ein Ordner des Serverrechners gebunden werden darf; ein Arbeitsbereich mit eigenen Rechten schließt ihn aus. */
+  serverFolders: boolean;
+  /** Wo die Ordner je Run liegen, wenn nicht in der Ablage des Arbeitsbereich-Plugins; nur zur Anzeige. */
+  directoryPattern?: string;
+}
+
+/** Ein Schritt beim Anlegen oder Wegräumen des neuen Ordners auf einem Arbeitsplatz: eine Operation des Executors dort, im Ordner des Runs. */
+export interface WorkspaceFolderStep {
+  operation: string;
+  input: JsonValue;
+}
+
+export interface WorkstationFolderContext {
+  runId: string;
+  /** Der Ordner des Runs auf dem Arbeitsplatz. */
+  path: string;
+  label: string;
+  choice: JsonValue | null;
+}
+
+/** Wie ein Beitrag den neuen Ordner je Run auf einem Arbeitsplatz stellt; der Executor dort legt ihn leer an, die Schritte füllen ihn. */
+export interface WorkstationFolder {
+  /** Kurzform für Startoption und Sitzungsdaten, etwa "Git-Worktree je Run". */
+  label: string;
+  /** Laufen der Reihe nach, einmal nach dem Anlegen; scheitert einer, räumt der Host den Ordner wieder weg. */
+  prepare: (context: WorkstationFolderContext) => readonly WorkspaceFolderStep[];
+  /** Laufen vor dem Wegräumen des Ordners, etwa um einen Worktree aus seinem Repository auszutragen. */
+  release?: (context: WorkstationFolderContext) => readonly WorkspaceFolderStep[];
+  /** Beschreibt den Ordner im Systemprompt; ohne Angabe der neue, zunächst leere Ordner. */
+  description?: (context: WorkstationFolderContext) => string;
 }
 
 export interface WorkspaceResolver {
   optionId?: string;
+  kind?: WorkspaceKind;
+  /** Den neuen Ordner je Run gibt es mit einem Beitrag auf einem Arbeitsplatz nur, wenn er ihn dort stellt. */
+  workstation?: WorkstationFolder;
   resolve: (context: WorkspaceResolverContext) => Promise<WorkspaceResolution>;
+  /** Beenden eines Runs im beigesteuerten Arbeitsbereich auf dem Server; `sandbox` beendet dabei die Werkzeuge des Hosts. */
+  stopSession?: (runId: string, sandbox: () => Promise<void>) => Promise<void>;
+  /** Löschen eines Runs im beigesteuerten Arbeitsbereich auf dem Server, nach dem Beenden. */
+  deleteSession?: (runId: string) => Promise<void>;
 }
 
 export const workspaceResolverToken = serviceToken<WorkspaceResolver>("ragents.workspace-resolver");
@@ -58,7 +123,8 @@ export const workspaceResolverToken = serviceToken<WorkspaceResolver>("ragents.w
 export interface GitWorkspaceView {
   branch: (runId: string) => Promise<string | undefined>;
   changes: (runId: string) => Promise<unknown>;
-  file: (runId: string, filePath: string, view: "diff" | "current") => Promise<unknown>;
+  /** previousPath nennt die Quelle einer Umbenennung aus der Änderungsliste; nur so paart Git sie ohne die ganze Liste. */
+  file: (runId: string, filePath: string, view: "diff" | "current", previousPath?: string) => Promise<unknown>;
 }
 
 export const gitWorkspaceViewToken = serviceToken<GitWorkspaceView>("ragents.git-workspace-view");

package/apps/server/src/rpc/dispatcher.ts

@@ -1,11 +1,11 @@
 import { randomUUID } from "node:crypto";
-import type { TSchema } from "typebox";
 import { Value } from "typebox/value";
 import {
   DomainError,
   RPC_ERROR_CODES,
   RPC_METHODS,
   RpcError,
+  schemaComplaints,
   type AccessContext,
   type ChannelContributionRegistry,
   type JsonValue,
@@ -21,7 +21,7 @@ import {
   type RpcSubscribeParams,
   type RpcSubscribeResult,
   type RpcUnsubscribeParams,
-} from "@aicontainer/ragents";
+} from "@ragents/engine";
 
 const MAX_SUBSCRIPTIONS = 64;
 
@@ -34,9 +34,6 @@ export interface RpcConnectionOptions {
   streamless?: boolean;
 }
 
-const firstComplaint = (schema: TSchema, value: unknown): string =>
-  [...Value.Errors(schema, value)].at(0)?.message ?? "Schema nicht erfüllt";
-
 /** Eine Verbindung eines Clients: hält ihre Abonnements und ist der Rückweg für Anfragen des Servers. */
 export class RpcConnection implements MethodConnection {
   readonly id: string;
@@ -90,8 +87,16 @@ export class RpcConnection implements MethodConnection {
 export interface RpcDispatcherOptions {
   methods: MethodContributionRegistry;
   channels: ChannelContributionRegistry;
+  /** Jede Methode und jeder Kanal mit runId wird zusätzlich gegen die Zugehörigkeit des Runs geprüft; eine Methode mit runs.write bedient ihn. */
+  assertRunReachable?: (access: AccessContext, runId: string, operates: boolean) => void;
 }
 
+const runIdOf = (input: unknown): string | undefined => {
+  if (typeof input !== "object" || input === null || !("runId" in input)) return undefined;
+  const value = (input as { runId: unknown }).runId;
+  return typeof value === "string" ? value : undefined;
+};
+
 /** Führt Anfragen einer Verbindung gegen die registrierten Verträge aus: Rechte, Eingabe, Ausführung, Antwort. */
 export class RpcDispatcher {
   readonly #options: RpcDispatcherOptions;
@@ -111,8 +116,10 @@ export class RpcDispatcher {
     assertRights(connection.access, contract.rights);
     const input = params === undefined ? {} : params;
     if (!Value.Check(contract.input, input)) {
-      throw new RpcError(RPC_ERROR_CODES.invalidParams, `Ungültige Eingabe für ${method}: ${firstComplaint(contract.input, input)}`);
+      throw new RpcError(RPC_ERROR_CODES.invalidParams, `Ungültige Eingabe für ${method}: ${schemaComplaints(contract.input, input, "params")}`);
     }
+    const target = runIdOf(input);
+    if (target !== undefined) this.#options.assertRunReachable?.(connection.access, target, contract.rights.includes("runs.write"));
     const result = await execute(input, {
       access: connection.access,
       signal: context.signal,
@@ -122,7 +129,7 @@ export class RpcDispatcher {
     });
     const plain = result === undefined ? null : JSON.parse(JSON.stringify(result)) as unknown;
     if (!Value.Check(contract.result, plain)) {
-      const complaint = firstComplaint(contract.result, plain);
+      const complaint = schemaComplaints(contract.result, plain, "result");
       console.error(`Die Antwort von ${method} verletzt ihren Vertrag: ${complaint}`);
       throw new RpcError(RPC_ERROR_CODES.internal, `Die Antwort von ${method} verletzt ihren Vertrag: ${complaint}`);
     }
@@ -139,8 +146,10 @@ export class RpcDispatcher {
     assertRights(connection.access, contract.rights);
     const input = channelParams === undefined ? {} : channelParams;
     if (!Value.Check(contract.params, input)) {
-      throw new RpcError(RPC_ERROR_CODES.invalidParams, `Ungültige Parameter für ${channel}: ${firstComplaint(contract.params, input)}`);
+      throw new RpcError(RPC_ERROR_CODES.invalidParams, `Ungültige Parameter für ${channel}: ${schemaComplaints(contract.params, input, "params")}`);
     }
+    const target = runIdOf(input);
+    if (target !== undefined) this.#options.assertRunReachable?.(connection.access, target, false);
     if (connection.subscriptions.size >= MAX_SUBSCRIPTIONS) throw new DomainError("too-many-channels", "Zu viele Ereigniskanäle auf einer Verbindung.", 429);
     const subscription = randomUUID();
     const buffered: unknown[] = [];

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

@@ -10,7 +10,7 @@ import {
   rpcFailure,
   type AccessContext,
   type RpcMessage,
-} from "@aicontainer/ragents";
+} from "@ragents/engine";
 import { PayloadTooLargeError, readBody, writeJson } from "../plugin-support/http.js";
 import { RpcConnection, type RpcDispatcher } from "./dispatcher.js";
 
@@ -32,8 +32,6 @@ export interface RpcHttpTransportOptions {
   maxBodyBytes?: number;
 }
 
-export const isRpcPath = (pathname: string): boolean => pathname === RPC_PATH || pathname === RPC_STREAM_PATH;
-
 /** JSON-RPC über HTTP: Anfragen per POST, Benachrichtigungen und Anfragen des Servers über einen SSE-Strom je Verbindung. */
 export class RpcHttpTransport {
   readonly #dispatcher: RpcDispatcher;

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

@@ -1,6 +1,6 @@
 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 { RPC_ERROR_CODES, RpcPeer, rpcFailure, unrestrictedAccess, type AccessContext } from "@ragents/engine";
 import { RpcConnection, type RpcDispatcher } from "./dispatcher.js";
 
 export interface StdioTransportOptions {

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

@@ -1,4 +1,4 @@
-import type { ChatAttachmentInput } from "./chat-events.js";
+import type { ChatAttachmentInput } from "quassel/events";
 
 export interface RunPreparationMessage {
   role: "user" | "assistant";

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

@@ -1,4 +1,4 @@
-import type { ChatAttachmentInput } from "./chat-events.js";
+import type { ChatAttachmentInput } from "quassel/events";
 import type { RunPreparationMessage } from "./run-preparation-contract.js";
 
 export function preparedRunInput(history: readonly RunPreparationMessage[], text: string, attachments?: ChatAttachmentInput[], skillName?: string) {

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

@@ -1,9 +1,9 @@
-import { createAgentSession, DefaultResourceLoader, defineTool, SessionManager, SettingsManager, type ModelRuntime } from "@aicontainer/agent";
+import { Agent, convertToLlm, type AgentTool, type ModelRuntime } from "@ragents/agent";
 import { Type } from "typebox";
-import type { Message } from "@aicontainer/ai";
-import { DomainError, type ModelSelection } from "@aicontainer/ragents";
+import { clampThinkingLevel, type Message } from "@ragents/ai";
+import { DomainError, type ModelSelection } from "@ragents/engine";
 import { prepareInputAttachments } from "../../../packages/ragents/src/drivers/attachments.ts";
-import { MAX_CHAT_REQUEST_BYTES, parseChatAttachments } from "./chat-attachments.js";
+import { MAX_CHAT_REQUEST_BYTES, parseChatAttachments } from "quassel/events";
 import {
   MAX_RUN_PREPARATION_MESSAGES, MAX_RUN_PREPARATION_TEXT_CHARS, MAX_RUN_PREPARATION_TOTAL_TEXT_CHARS,
   type RunPreparationMessage, type RunPreparationRequest, type RunPreparationResponse,
@@ -50,7 +50,6 @@ export const parseRunPreparationRequest = (value: unknown): RunPreparationReques
 export const prepareRunMessage = async (options: {
   runtime: ModelRuntime;
   prompt: string;
-  agentDir: string;
   selection: ModelSelection;
   request: RunPreparationRequest;
   signal: AbortSignal;
@@ -73,7 +72,8 @@ export const prepareRunMessage = async (options: {
         continue;
       }
       try {
-        const prepared = await prepareInputAttachments({ prompt: message.text, workspace: "", tools: [], workspaceTools: [],
+        const prepared = await prepareInputAttachments({ prompt: message.text, tools: [],
+          storeAttachment: () => Promise.reject(new Error("Der Vorbereitungs-Chat hat keinen Arbeitsbereich.")),
           attachments: message.attachments?.map((attachment) => ({ name: attachment.name, mediaType: attachment.mediaType,
             content: Buffer.from(attachment.data, "base64") })),
         }, model.input);
@@ -85,20 +85,9 @@ export const prepareRunMessage = async (options: {
       }
     }
     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({
+    const startRun: AgentTool = {
       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({}),
@@ -107,24 +96,25 @@ export const prepareRunMessage = async (options: {
         startRequested = true;
         return { content: [{ type: "text", text: "Start zur Übergabe vorgemerkt. Nach Abschluss dieser Antwort übernimmt die Oberfläche den Auftrag." }], details: {} };
       },
+    };
+    if (!(await runtime.checkAuth(model.provider))) throw new Error(`No key is configured for the provider ${model.provider}.`);
+    const agent = new Agent({
+      initialState: { systemPrompt, model, thinkingLevel: clampThinkingLevel(model, selection.thinking ?? "off"), tools: [startRun], messages: messages.slice(0, -1) },
+      convertToLlm,
+      streamFn: (streamModel, context, streamOptions) => runtime.streamSimple(streamModel, context, { ...streamOptions, maxRetries: 0, timeoutMs: PREPARATION_TIMEOUT_MS }),
     });
-    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(); };
+    const abort = () => { agent.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") }),
-      });
+      await agent.prompt({ role: "user", timestamp: Date.now(), content: typeof content === "string"
+        ? [{ type: "text", text: content }]
+        : [{ type: "text", text: content.filter((part) => part.type === "text").map((part) => part.text).join("\n") }, ...content.filter((part) => part.type !== "text")] });
       signal.throwIfAborted();
-      const completed = session.messages.at(-1);
+      const completed = agent.state.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}).`
@@ -136,7 +126,6 @@ export const prepareRunMessage = async (options: {
       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);

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

@@ -1,9 +1,10 @@
-import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, readlinkSync, Stats } 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";
+import { create as createTar, extract as extractTar, type ReadEntry } from "tar";
+import { DomainError, isPendingActorInput, isRunId, type CommandRecord, type JournalEvent, type RunState } from "@ragents/engine";
+import { parseJournalRecord } from "@ragents/engine/src/runtime/journal-storage";
 
 export const RUN_TRANSFER_FORMAT_VERSION = 1;
 
@@ -100,16 +101,36 @@ export const assertRunIdFree = (options: { runId: string; known: boolean; direct
   }
 };
 
+/** Die Inhalte unter artifacts/, auf die der Run verweist: veröffentlichte Artefakte und Medien seiner Modellkontexte. */
+export const contentHashesOf = (events: readonly JournalEvent[]): string[] => [...new Set(events.flatMap((event) => {
+  if (event.type === "artifact.published") return [event.payload.artifact.hash];
+  const content = event.type === "model.input.presented" || event.type === "model.tool-result.presented" ? event.payload.content : undefined;
+  return Array.isArray(content) ? content.flatMap((part) => "hash" in part ? [part.hash] : []) : [];
+}))].sort();
+
+const sha256 = /^[0-9a-f]{64}$/;
+
 // 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.");
 };
 
+/** A link travels only inside the run's tree; one out of it below node_modules is left for the next install, elsewhere refused. */
+const linkDecision = (dataDirectory: string, entry: string): "keep" | "skip" | "refuse" => {
+  const file = path.join(dataDirectory, entry);
+  const target = readlinkSync(file);
+  const root = path.join(dataDirectory, ...entry.split("/").slice(0, 2));
+  const resolved = path.resolve(path.dirname(file), target);
+  if (!path.isAbsolute(target) && (resolved === root || resolved.startsWith(`${root}${path.sep}`))) return "keep";
+  return entry.split("/").includes("node_modules") ? "skip" : "refuse";
+};
+
 export const packRunArchive = async (options: {
   places: RunTransferPlaces;
   runId: string;
   manifest: RunTransferManifest;
+  contentHashes: readonly string[];
 }): Promise<Buffer> => {
   const runId = assertRunId(options.runId);
   const { dataDirectory } = options.places;
@@ -123,15 +144,36 @@ export const packRunArchive = async (options: {
     RUN_TRANSFER_MANIFEST_ENTRY,
     `runs/${runId}`,
     ...(existsSync(runTransferSessionDirectory(dataDirectory, runId)) ? [`sessions/${runId}`] : []),
+    ...options.contentHashes.map((hash) => {
+      if (!sha256.test(hash) || !existsSync(path.join(dataDirectory, "artifacts", hash))) {
+        throw new DomainError("run-transfer-missing", `The content ${hash} of run ${runId} is missing under artifacts`, 404);
+      }
+      return `artifacts/${hash}`;
+    }),
   ];
   const chunks: Buffer[] = [];
+  const refused: string[] = [];
+  const portable = (entry: string, stat: Stats | ReadEntry): boolean => {
+    if (temporary(entry)) return false;
+    if (!(stat instanceof Stats) || !stat.isSymbolicLink()) return true;
+    const decision = linkDecision(dataDirectory, entry);
+    if (decision === "refuse") refused.push(entry);
+    return decision === "keep";
+  };
   try {
-    for await (const chunk of createTar({ gzip: true, cwd: dataDirectory, portable: true, filter: (entry) => !temporary(entry) }, entries)) {
+    for await (const chunk of createTar({ gzip: true, cwd: dataDirectory, portable: true, filter: portable }, entries)) {
       chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
     }
   } finally {
     await rm(manifestFile, { force: true });
   }
+  if (refused.length > 0) {
+    throw new DomainError(
+      "run-transfer-link",
+      `Run ${runId} contains links that would point nowhere on the target: ${refused.join(", ")}. Replace them with files or relative links inside the run.`,
+      409,
+    );
+  }
   const archive = Buffer.concat(chunks);
   if (archive.byteLength > RUN_TRANSFER_MAX_ARCHIVE_BYTES) {
     throw new DomainError(
@@ -234,6 +276,14 @@ export const unpackRunArchive = async (options: {
   if (existsSync(path.join(staging, "sessions"))) {
     await onlyEntry(path.join(staging, "sessions"), manifest.runId, "Der Ordner sessions des Archivs");
   }
+  if (existsSync(path.join(staging, "artifacts"))) {
+    for (const name of await readdir(path.join(staging, "artifacts"))) {
+      const content = sha256.test(name) ? await readFile(path.join(staging, "artifacts", name)) : undefined;
+      if (!content || createHash("sha256").update(content).digest("hex") !== name) {
+        throw new DomainError("run-transfer-invalid", `The archive content artifacts/${name} does not match its name`, 400);
+      }
+    }
+  }
   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);
@@ -246,6 +296,17 @@ export const unpackRunArchive = async (options: {
   return { manifest, staging, records };
 };
 
+/** Legt die Inhalte des Archivs unter artifacts/ des Ziels ab; vorhandene sind wegen ihres Hash-Namens dieselben. */
+export const installContents = async (options: { places: RunTransferPlaces; staging: string }): Promise<void> => {
+  const source = path.join(options.staging, "artifacts");
+  if (!existsSync(source)) return;
+  const target = path.join(options.places.dataDirectory, "artifacts");
+  await mkdir(target, { recursive: true });
+  for (const name of await readdir(source)) {
+    if (!existsSync(path.join(target, name))) await rename(path.join(source, name), path.join(target, name));
+  }
+};
+
 /** 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;