@schlenkr/ragents 0.1.5 → 0.1.7

package/{plugins/ragents.processes/server → packages/workspace-executor/src/processes}/terminator.ts

@@ -1,11 +1,12 @@
-import { DomainError } from "@aicontainer/ragents";
-import { runMarkerOf } from "@aicontainer/workspace-executor";
+import { WorkspaceOperationError } from "../errors.js";
+import { runMarkerOf } from "../run-marker.js";
 import { processIdOf, type ProcessRecord, type ProcessTable } from "./process-table.js";
 
 export interface ProcessTerminationOptions {
   table: ProcessTable;
-  serverPid: number;
-  serverUid: number | undefined;
+  /** Der Prozess dieses Executors; er und seine Vorfahren sind geschützt. */
+  executorPid: number;
+  executorUid: number | undefined;
   termGraceMs?: number;
   killGraceMs?: number;
   timeoutMs?: number;
@@ -15,7 +16,6 @@ export interface ProcessTerminationOptions {
 
 export interface ProcessTerminationContext {
   signal?: AbortSignal;
-  assertAllowed?: () => void;
 }
 
 interface Attempt {
@@ -49,7 +49,7 @@ export class RunProcessTerminator {
   async stop(runId: string, processId: string, context: ProcessTerminationContext = {}): Promise<void> {
     const pid = Number(processId.split("-")[0]);
     if (!/^[1-9]\d*-[a-f0-9]{64}$/.test(processId) || !Number.isSafeInteger(pid) || pid > 2_147_483_647)
-      throw new DomainError("invalid-process", "Ungültige Prozessreferenz", 400);
+      throw new WorkspaceOperationError("invalid-process", "Ungültige Prozessreferenz", 400);
     await this.#stop(runId, processId, context);
   }
 
@@ -58,7 +58,7 @@ export class RunProcessTerminator {
   }
 
   async #stop(runId: string, processId: string | undefined, context: ProcessTerminationContext): Promise<void> {
-    if (runMarkerOf(runId) !== runId) throw new DomainError("invalid-run", "Ungültige Laufkennung", 400);
+    if (runMarkerOf(runId) !== runId) throw new WorkspaceOperationError("invalid-run", "Ungültige Laufkennung", 400);
     const deadline = Date.now() + this.#timeoutMs;
     const attempts = new Map<string, Attempt>();
     const failures = new Map<string, unknown>();
@@ -69,15 +69,15 @@ export class RunProcessTerminator {
     let first = true;
     let emptyScans = 0;
     while (true) {
-      this.#assertAllowed(context, deadline);
+      this.#assertActive(context, deadline);
       const records = await this.#bounded(this.#options.table.list(), deadline);
       const selected = processId === undefined ? records : records.filter((record) => record.pid === Number(processId.split("-")[0]));
       const readable = selected.filter((record) => this.#readable(record));
       const markers = await this.#bounded(this.#options.table.runMarkers(readable.map((record) => record.pid)), deadline);
       if (first && processId !== undefined && selected.length > 0) {
         const record = selected[0];
-        if (processIdOf(record) !== processId) throw new DomainError("stale-process", "Die Prozess-ID wurde inzwischen neu vergeben. Bitte die Prozessliste aktualisieren.", 409);
-        if (markers.get(record.pid) !== runId) throw new DomainError("process-run-mismatch", "Der Prozess gehört nicht zu diesem Lauf", 403);
+        if (processIdOf(record) !== processId) throw new WorkspaceOperationError("stale-process", "Die Prozess-ID wurde inzwischen neu vergeben. Bitte die Prozessliste aktualisieren.", 409);
+        if (markers.get(record.pid) !== runId) throw new WorkspaceOperationError("process-run-mismatch", "Der Prozess gehört nicht zu diesem Run", 403);
       }
       first = false;
       const targets = readable.filter((record) => markers.get(record.pid) === runId
@@ -100,10 +100,10 @@ export class RunProcessTerminator {
             } else if (attempt.killAt === undefined && Date.now() - attempt.termAt >= this.#termGraceMs) {
               if (await this.#signal(record, runId, "SIGKILL", context, deadline)) attempt.killAt = Date.now();
             } else if (attempt.killAt !== undefined && Date.now() - attempt.killAt >= this.#killGraceMs) {
-              throw new Error(`Prozess ${record.pid} von Lauf ${runId} ist nach SIGKILL noch aktiv`);
+              throw new Error(`Prozess ${record.pid} von Run ${runId} ist nach SIGKILL noch aktiv`);
             }
           } catch (error) {
-            this.#assertAllowed(context, deadline);
+            this.#assertActive(context, deadline);
             if (processId !== undefined) throw error;
             failures.set(key, error);
           }
@@ -115,22 +115,21 @@ export class RunProcessTerminator {
   }
 
   #readable(record: ProcessRecord): boolean {
-    return this.#options.serverUid === undefined || this.#options.serverUid === 0 || record.uid === this.#options.serverUid;
+    return this.#options.executorUid === undefined || this.#options.executorUid === 0 || record.uid === this.#options.executorUid;
   }
 
   #assertUnprotected(record: ProcessRecord, records: readonly ProcessRecord[]): void {
-    const protectedPids = new Set([0, 1, this.#options.serverPid]);
-    let parent = records.find((candidate) => candidate.pid === this.#options.serverPid)?.ppid;
+    const protectedPids = new Set([0, 1, this.#options.executorPid]);
+    let parent = records.find((candidate) => candidate.pid === this.#options.executorPid)?.ppid;
     while (parent !== undefined && !protectedPids.has(parent)) {
       protectedPids.add(parent);
       parent = records.find((candidate) => candidate.pid === parent)?.ppid;
     }
-    if (protectedPids.has(record.pid)) throw new DomainError("protected-process", `Prozess ${record.pid} gehört zum geschützten Server-Prozessbaum`, 403);
+    if (protectedPids.has(record.pid)) throw new WorkspaceOperationError("protected-process", `Prozess ${record.pid} gehört zum geschützten Prozessbaum des Executors`, 403);
   }
 
-  #assertAllowed(context: ProcessTerminationContext, deadline: number): void {
+  #assertActive(context: ProcessTerminationContext, deadline: number): void {
     context.signal?.throwIfAborted();
-    context.assertAllowed?.();
     if (Date.now() >= deadline) throw new Error(`Prozess-Stopp hat die Zeitgrenze von ${this.#timeoutMs} ms überschritten`);
   }
 
@@ -150,9 +149,9 @@ export class RunProcessTerminator {
     const records = await this.#bounded(this.#options.table.list(), deadline);
     const current = records.find((record) => record.pid === expected.pid);
     if (!current || current.startKey !== expected.startKey || current.uid !== expected.uid) return false;
-    if (markers.get(current.pid) !== runId) throw new DomainError("process-run-mismatch", `Prozess ${current.pid} gehört nicht mehr zu diesem Lauf`, 403);
+    if (markers.get(current.pid) !== runId) throw new WorkspaceOperationError("process-run-mismatch", `Prozess ${current.pid} gehört nicht mehr zu diesem Run`, 403);
     this.#assertUnprotected(current, records);
-    this.#assertAllowed(context, deadline);
+    this.#assertActive(context, deadline);
     try {
       this.#sendSignal(current.pid, signal);
       return true;

package/packages/workspace-executor/src/run-folders.ts

@@ -0,0 +1,33 @@
+import { mkdir, rm } from "node:fs/promises";
+import { WorkspaceOperationError } from "./errors.js";
+import type { WorkspaceModuleFactory } from "./module.js";
+
+export const RUN_FOLDER_OPERATIONS = {
+  create: "runFolder.create",
+  remove: "runFolder.remove",
+} as const;
+
+export interface RunFolderCreated {
+  /** Ob der Ordner eben entstanden ist; ein schon vorhandener bleibt, wie er ist. */
+  created: boolean;
+}
+
+/** Der neue Ordner je Run auf dieser Maschine; nur ein Executor, der einen Ordner für Runs kennt, legt ihn an, und nur diesen einen je Run. */
+export const runFolderModule = (folderOf: ((runId: string) => string) | undefined): WorkspaceModuleFactory => () => {
+  const folder = (runId: string): string => {
+    if (!folderOf) {
+      throw new WorkspaceOperationError("run-folder-unavailable", "Dieser Executor legt keine Ordner je Run an; auf dem Server tut das der Host", 409);
+    }
+    return folderOf(runId);
+  };
+  return {
+    operations: {
+      [RUN_FOLDER_OPERATIONS.create]: async ({ runId }): Promise<RunFolderCreated> =>
+        ({ created: await mkdir(folder(runId), { recursive: true }) !== undefined }),
+      [RUN_FOLDER_OPERATIONS.remove]: async ({ runId }): Promise<{ removed: true }> => {
+        await rm(folder(runId), { recursive: true, force: true });
+        return { removed: true };
+      },
+    },
+  };
+};

package/packages/workspace-executor/src/safe-environment.ts

@@ -45,3 +45,17 @@ export const safeProcessEnvironment = (source: NodeJS.ProcessEnv): NodeJS.Proces
   }
   return environment;
 };
+
+/** Die Variablen des umgebenden Editors; ein Kindprozess, der sie erbt, hängt sich an VS Code oder Electron. */
+const isEditorVariable = (name: string): boolean => name.startsWith("VSCODE_") || name.startsWith("ELECTRON_");
+
+/** Was eine nicht interaktive Bash von sich aus einliest; über sie käme eine Startdatei des Benutzers in jeden Befehl. */
+const BASH_STARTUP_VARIABLES: ReadonlySet<string> = new Set(["BASH_ENV", "ENV"]);
+
+/** Die ganze Umgebung eines Prozesses ohne die Variablen des umgebenden Editors. */
+export const editorFreeEnvironment = (source: NodeJS.ProcessEnv): Record<string, string> => Object.fromEntries(Object.entries(source)
+  .filter((entry): entry is [string, string] => typeof entry[1] === "string" && !isEditorVariable(entry[0])));
+
+/** Die geerbte Umgebung für Prozesse auf dem eigenen Rechner des Benutzers: alles außer Editor-Variablen und den Startdateien der Bash. */
+export const inheritedProcessEnvironment = (source: NodeJS.ProcessEnv): Record<string, string> => Object.fromEntries(
+  Object.entries(editorFreeEnvironment(source)).filter(([name]) => !BASH_STARTUP_VARIABLES.has(name)));

package/packages/workspace-executor/src/sandbox-tools.ts

@@ -1,18 +1,22 @@
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import {
   createBashToolDefinition,
   createEditToolDefinition,
   createReadToolDefinition,
   createWriteToolDefinition,
-  getShellConfig,
   type BashOperations,
-  type ShellConfig,
-} from "@aicontainer/agent";
+} from "@ragents/agent";
+import { bashLaunch } from "./bash-launch.js";
 import type { WorkspaceProcessContext } from "./context.js";
+import { WorkspaceOperationError } from "./errors.js";
 import { processGroupExists, stopProcessTree } from "./managed-process.js";
+import type { WorkspaceModuleFactory, WorkspaceOperation } from "./module.js";
+import { sandboxedLaunch } from "./process-sandbox.js";
 import { stopUidProcesses } from "./session-ident.js";
-import { allowedWorkspacePath, expandWorkspaceAlias } from "./paths.js";
+import { allowedWorkspacePath, expandWorkspaceAlias, rootsOfFields, type OperationFootprint } from "./paths.js";
 
 export interface ToolUpdate {
   content?: ReadonlyArray<{ type: string; text?: string }>;
@@ -23,7 +27,6 @@ type ToolExecute = (
   input: unknown,
   signal: AbortSignal | undefined,
   onUpdate: ((update: ToolUpdate) => void) | undefined,
-  context: unknown,
 ) => Promise<unknown>;
 
 export interface SandboxToolCall {
@@ -42,7 +45,61 @@ export const DEFAULT_BASH_TIMEOUT_SECONDS = (() => {
   return Number.isFinite(value) && value > 0 ? value : 600;
 })();
 
-type ToolResult = { content?: Array<{ type: string; text?: string }> };
+type ToolResult = { content?: Array<{ type: string; text?: string }>; details?: unknown };
+
+/** Der Stand einer Datei, den das Modell zuletzt gesehen hat; der Host führt ihn je Actor und gibt ihn mit, das Modell nennt ihn nie. */
+export interface SeenFile {
+  readonly file: string;
+  readonly hash: string;
+  /** Nur nach einem read: der gelesene Ausschnitt. */
+  readonly read?: { readonly offset?: number; readonly limit?: number };
+}
+
+/** Die Eingabe der Dateiwerkzeuge: was das Modell übergibt, und nur bei dessen direktem Aufruf der Stand, den es gesehen hat (`null`: keiner). */
+type FileToolInput = {
+  readonly path?: unknown;
+  readonly offset?: number;
+  readonly limit?: number;
+  readonly content?: string;
+  readonly seen?: SeenFile | null;
+};
+
+type FileToolName = "read" | "edit" | "write";
+
+const unchangedNotice = "Unverändert seit dem letzten read in diesem Gespräch; der frühere Inhalt gilt weiter.";
+
+const sha256 = (content: Buffer | string): string => createHash("sha256").update(content).digest("hex");
+
+/** Der Inhalts-Hash einer Datei; eine fehlende Datei hat keinen. */
+const currentHash = async (file: string): Promise<string | undefined> => {
+  try {
+    return sha256(await readFile(file));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+};
+
+const detailHash = (result: unknown, name: FileToolName): string => {
+  const hash = (result as { details?: { contentHash?: unknown } }).details?.contentHash;
+  if (typeof hash !== "string") throw new Error(`Das Werkzeug ${name} meldet keinen Inhalts-Hash`);
+  return hash;
+};
+
+/** Ein Ergebnis und ein Fehler nennen den Pfad so, wie das Modell ihn übergeben hat, nicht den aufgelösten. */
+const withShownPath = (result: unknown, resolved: string, shown: string): unknown => {
+  const typed = result as ToolResult;
+  if (resolved === shown || !Array.isArray(typed.content)) return result;
+  return { ...typed, content: typed.content.map((part) => typeof part.text === "string" ? { ...part, text: part.text.replaceAll(resolved, shown) } : part) };
+};
+
+const errorWithShownPath = (error: unknown, resolved: string, shown: string): unknown => {
+  if (resolved === shown || !(error instanceof Error) || !error.message.includes(resolved)) return error;
+  const message = error.message.replaceAll(resolved, shown);
+  return error instanceof WorkspaceOperationError
+    ? new WorkspaceOperationError(error.code, message, error.status)
+    : new Error(message, { cause: error });
+};
 
 export const withAnnotation = (result: unknown, note: string | undefined): unknown => {
   if (!note || typeof result !== "object" || result === null) return result;
@@ -52,8 +109,7 @@ export const withAnnotation = (result: unknown, note: string | undefined): unkno
 };
 
 /** Löst `$RAGENTS_..._DIR` und `${...}` am Anfang eines Pfads gegen die Variablen des Kontexts auf. */
-const expandPathVariables = (value: unknown, variables: Readonly<Record<string, string>>): unknown => {
-  if (typeof value !== "string") return value;
+const expandPathVariables = (value: string, variables: Readonly<Record<string, string>>): string => {
   for (const [name, root] of Object.entries(variables)) {
     for (const prefix of [`$${name}`, `\${${name}}`]) {
       const relative = value.startsWith("./") ? value.slice(2) : value;
@@ -75,13 +131,6 @@ export const createSandboxTools = async (
   let shuttingDown = false;
   const processGroups = new Set<number>();
 
-  /** Kein stiller Ausweg auf `sh`: das Werkzeug heißt bash und der Prompt beschreibt bash. */
-  const resolvedShell = (): ShellConfig => {
-    const shell = getShellConfig();
-    if (!/bash(\.exe)?$/i.test(shell.shell)) throw new Error(`Auf diesem Rechner gibt es keine Bash; ${shell.shell} ist kein Ersatz`);
-    return shell;
-  };
-
   const killProcessGroup = async (pid: number): Promise<void> => {
     if (onWindows) {
       stopProcessTree(pid);
@@ -127,60 +176,113 @@ export const createSandboxTools = async (
     await allowedWorkspacePath(path.resolve(cwd, String(raw)), roots);
   };
 
-  const concurrent = (execute: ToolExecute): ToolExecute => (toolCallId, input, signal, onUpdate, context) => {
+  const concurrent = (execute: ToolExecute): ToolExecute => (toolCallId, input, signal, onUpdate) => {
     if (shuttingDown) throw new Error("Die Werkzeuge werden killed");
     if (signal?.aborted) throw new Error("Abgebrochen");
-    const run = () => execute(toolCallId, input, signal, onUpdate, context);
+    const run = () => execute(toolCallId, input, signal, onUpdate);
     return initial.runOperation ? initial.runOperation(run) : run();
   };
 
   const serial = (execute: ToolExecute): ToolExecute => {
     const inner = concurrent(execute);
-    return (toolCallId, input, signal, onUpdate, context) => {
-      const call = () => inner(toolCallId, input, signal, onUpdate, context);
+    return (toolCallId, input, signal, onUpdate) => {
+      const call = () => inner(toolCallId, input, signal, onUpdate);
       const result = toolOperation.then(call, call);
       toolOperation = result.then(() => undefined, () => undefined);
       return result;
     };
   };
 
-  const guarded = (execute: ToolExecute, writing: boolean): ToolExecute => {
-    const checked: ToolExecute = async (toolCallId, input, signal, onUpdate, ctx) => {
-      const params = input as { path?: unknown } | undefined;
+  /** Bei einem direkten Aufruf des Modells prüft ein Schreiben den gesehenen Stand und ein erneutes read eines unveränderten Ausschnitts antwortet knapp. */
+  const checkedAgainstSeen = async (name: FileToolName, file: string, shown: string, input: FileToolInput, seen: SeenFile | null): Promise<ToolResult | undefined> => {
+    if (name === "read") {
+      const sameView = seen?.read !== undefined && seen.file === file && seen.read.offset === input.offset && seen.read.limit === input.limit;
+      return sameView && await currentHash(file) === seen.hash ? { content: [{ type: "text", text: unchangedNotice }], details: { seen } } : undefined;
+    }
+    const current = await currentHash(file);
+    if (current === undefined) return undefined;
+    if (seen === null || seen.file !== file) throw new WorkspaceOperationError("workspace-file-unread", `${shown}: Datei zuerst mit read lesen.`, 409);
+    if (seen.hash !== current) {
+      throw new WorkspaceOperationError("workspace-file-changed",
+        `${shown}: Datei wurde seit dem Lesen geändert (vom Benutzer, einem Formatter oder einem anderen Actor); erneut lesen.`, 409);
+    }
+    return undefined;
+  };
+
+  const seenAfter = (name: FileToolName, file: string, input: FileToolInput, result: unknown): SeenFile => {
+    if (name === "write") return { file, hash: sha256(input.content ?? "") };
+    if (name === "edit") return { file, hash: detailHash(result, name) };
+    return {
+      file,
+      hash: detailHash(result, name),
+      read: { ...input.offset === undefined ? {} : { offset: input.offset }, ...input.limit === undefined ? {} : { limit: input.limit } },
+    };
+  };
+
+  const guarded = (name: FileToolName, execute: ToolExecute): ToolExecute => {
+    const writing = name !== "read";
+    const checked: ToolExecute = async (toolCallId, input, signal, onUpdate) => {
+      const { seen, ...params } = (input ?? {}) as FileToolInput;
       const context = await contextFor();
-      if (params && typeof params.path === "string") {
-        params.path = expandPathVariables(expandWorkspaceAlias(params.path, context.workspaceAliases ?? {}), context.pathVariables ?? {});
+      const shown = typeof params.path === "string" ? params.path : undefined;
+      const requested = shown === undefined
+        ? undefined
+        : expandPathVariables(expandWorkspaceAlias(shown, context.workspaceAliases ?? {}), context.pathVariables ?? {});
+      try {
+        const writable = [context.root, ...context.additionalRoots ?? []];
+        await assertInsideRoots(requested ?? params.path, writing ? writable : [...writable, ...context.readOnlyRoots ?? []]);
+        const file = requested === undefined ? undefined : path.resolve(cwd, requested);
+        const tracked = seen !== undefined && file !== undefined && shown !== undefined;
+        const early = tracked ? await checkedAgainstSeen(name, file, shown, params, seen) : undefined;
+        if (early) return early;
+        const result = await execute(toolCallId, requested === undefined ? params : { ...params, path: requested }, signal, onUpdate);
+        const recorded = tracked ? { ...result as ToolResult, details: { ...(result as ToolResult).details as object, seen: seenAfter(name, file, params, result) } } : result;
+        const annotated = writing && annotate && file !== undefined ? withAnnotation(recorded, await annotate(file)) : recorded;
+        return requested === undefined || shown === undefined ? annotated : withShownPath(annotated, requested, shown);
+      } catch (error) {
+        throw requested === undefined || shown === undefined ? error : errorWithShownPath(error, requested, shown);
       }
-      const writable = [context.root, ...context.additionalRoots ?? []];
-      await assertInsideRoots(params?.path, writing ? writable : [...writable, ...context.readOnlyRoots ?? []]);
-      const result = await execute(toolCallId, input, signal, onUpdate, ctx);
-      if (!writing || !annotate || typeof params?.path !== "string") return result;
-      return withAnnotation(result, await annotate(path.resolve(cwd, params.path)));
     };
     return writing ? serial(checked) : concurrent(checked);
   };
 
+  /** Der Ordner eines Bash-Aufrufs: relativ zum Arbeitsverzeichnis oder mit Alias, auf jedem Rechner gleich, darum nie absolut, und immer in einer Wurzel des Runs. */
+  const inFolder = (execute: ToolExecute): ToolExecute => async (toolCallId, input, signal, onUpdate) => {
+    const params = input as { cwd?: unknown } | undefined;
+    if (params?.cwd === undefined) return execute(toolCallId, input, signal, onUpdate);
+    const requested = params.cwd;
+    if (typeof requested !== "string" || requested === "" || path.isAbsolute(requested)) {
+      throw new WorkspaceOperationError("workspace-path-invalid",
+        `cwd nennt einen Ordner relativ zum Arbeitsverzeichnis oder beginnt mit einem Alias wie @actors; ${JSON.stringify(requested)} ist das nicht`, 400);
+    }
+    const context = await contextFor();
+    const directory = await allowedWorkspacePath(path.resolve(cwd, expandWorkspaceAlias(requested, context.workspaceAliases ?? {})),
+      [context.root, ...context.additionalRoots ?? [], ...context.readOnlyRoots ?? []]);
+    if (!(await stat(directory).catch(() => undefined))?.isDirectory()) {
+      throw new WorkspaceOperationError("workspace-path-not-found", `Den Ordner ${requested} gibt es nicht`, 404);
+    }
+    return execute(toolCallId, { ...params, cwd: directory }, signal, onUpdate);
+  };
+
   const startBash: BashOperations["exec"] = async (command, commandCwd, options) => {
       if (shuttingDown) throw new Error("Die Werkzeuge werden killed");
       const context = await contextFor();
       if (shuttingDown) throw new Error("Die Werkzeuge werden killed");
       options.signal?.throwIfAborted();
-      const shell = resolvedShell();
-      const fromStdin = shell.commandTransport === "stdin";
+      const bash = bashLaunch(context.bash, command, context.env);
+      const launch = await sandboxedLaunch(context, bash);
+      if (shuttingDown) throw new Error("Die Werkzeuge werden killed");
+      options.signal?.throwIfAborted();
       return new Promise((resolve, reject) => {
-        const child = spawn(shell.shell, fromStdin ? shell.args : [...shell.args, command], {
+        const child = spawn(launch.command, [...launch.args], {
           cwd: commandCwd,
           detached: !onWindows,
-          stdio: [fromStdin ? "pipe" : "ignore", "pipe", "pipe"],
-          env: context.env,
+          stdio: ["ignore", "pipe", "pipe"],
+          env: bash.env,
           uid: context.uid,
           gid: context.gid,
           windowsHide: true,
         });
-        if (fromStdin) {
-          child.stdin?.on("error", () => undefined);
-          child.stdin?.end(command);
-        }
         if (child.pid) processGroups.add(child.pid);
         child.stdout?.on("data", options.onData);
         child.stderr?.on("data", options.onData);
@@ -245,14 +347,81 @@ export const createSandboxTools = async (
 
   const executeOf = (definition: { execute: unknown }): ToolExecute => definition.execute as ToolExecute;
   const wrapped: ReadonlyArray<readonly [string, ToolExecute]> = [
-    ["read", guarded(executeOf(createReadToolDefinition(cwd)), false)],
-    ["edit", guarded(executeOf(createEditToolDefinition(cwd)), true)],
-    ["write", guarded(executeOf(createWriteToolDefinition(cwd)), true)],
-    ["bash", serial(executeOf(createBashToolDefinition(cwd, { operations: bashOperations })))],
+    ["read", guarded("read", executeOf(createReadToolDefinition(cwd)))],
+    ["edit", guarded("edit", executeOf(createEditToolDefinition(cwd)))],
+    ["write", guarded("write", executeOf(createWriteToolDefinition(cwd)))],
+    ["bash", serial(inFolder(executeOf(createBashToolDefinition(cwd, { operations: bashOperations }))))],
   ];
   return {
     tools: new Map(wrapped.map(([name, execute]) =>
-      [name, (input: unknown, call: SandboxToolCall) => execute(call.toolCallId, input, call.signal, call.onUpdate, undefined)])),
+      [name, (input: unknown, call: SandboxToolCall) => execute(call.toolCallId, input, call.signal, call.onUpdate)])),
     shutdown,
   };
 };
+
+/** Die Operationen des Moduls heißen wie die Werkzeuge, die das Modell sieht. */
+export const SANDBOX_TOOL_NAMES = ["read", "edit", "write", "bash"] as const;
+
+/** Eine ausdrücklich verlangte Zeitgrenze in Sekunden verlängert, wie lange ein entfernter Executor auf die Bash warten darf. */
+const bashDuration = (input: unknown): { durationMs?: number } => {
+  const seconds = typeof input === "object" && input !== null ? (input as { timeout?: unknown }).timeout : undefined;
+  return typeof seconds === "number" && seconds > 0 ? { durationMs: seconds * 1000 } : {};
+};
+
+/** Die Dateiwerkzeuge sprechen die Wurzel ihres Pfads an, Bash die ihres Ordners und ohne Ordner keine bestimmte. */
+const sandboxToolFootprints: Readonly<Record<(typeof SANDBOX_TOOL_NAMES)[number], (input: unknown) => OperationFootprint>> = {
+  read: (input) => ({ roots: rootsOfFields(input, "path") }),
+  edit: (input) => ({ roots: rootsOfFields(input, "path") }),
+  write: (input) => ({ roots: rootsOfFields(input, "path") }),
+  bash: (input) => ({ roots: rootsOfFields(input, "cwd"), ...bashDuration(input) }),
+};
+
+const textOf = (update: ToolUpdate): string =>
+  (update.content ?? [])
+    .filter((part) => part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("\n");
+
+/** Die vier Sandbox-Werkzeuge als Operationen; die Sandbox eines Runs entsteht beim ersten Aufruf, Bash meldet ihre Ausgabe als `{ text }`. */
+export const sandboxToolsModule: WorkspaceModuleFactory = (host) => {
+  const sandboxes = new Map<string, Promise<SandboxTools>>();
+  const sandboxOf = (runId: string): Promise<SandboxTools> => {
+    const running = sandboxes.get(runId);
+    if (running) return running;
+    const created = createSandboxTools(
+      runId,
+      () => host.contextFor(runId),
+      (absolutePath) => host.annotate(runId, absolutePath),
+    ).catch((error: unknown) => {
+      sandboxes.delete(runId);
+      throw error;
+    });
+    sandboxes.set(runId, created);
+    return created;
+  };
+  const stopRun = async (runId: string): Promise<void> => {
+    const sandbox = sandboxes.get(runId);
+    sandboxes.delete(runId);
+    await sandbox?.then((tools) => tools.shutdown());
+  };
+  const operation = (name: string): WorkspaceOperation => async ({ runId, input, toolCallId, signal, progress }) => {
+    const { tools } = await sandboxOf(runId);
+    const run = tools.get(name);
+    if (!run) throw new Error(`Die Sandbox kennt das Werkzeug ${name} nicht`);
+    return run(input, {
+      toolCallId: toolCallId ?? name,
+      ...(signal ? { signal } : {}),
+      ...(progress ? { onUpdate: (update: ToolUpdate) => progress({ text: textOf(update) }) } : {}),
+    });
+  };
+  return {
+    operations: Object.fromEntries(SANDBOX_TOOL_NAMES.map((name) => [name, operation(name)])),
+    footprints: sandboxToolFootprints,
+    stopRun,
+    shutdown: async () => {
+      const results = await Promise.allSettled([...sandboxes.keys()].map(stopRun));
+      const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+      if (failed) throw failed.reason;
+    },
+  };
+};

package/packages/workspace-executor/src/shell-platform.ts

@@ -1,7 +1,7 @@
 const platformTexts: Partial<Record<NodeJS.Platform, string>> = {
-  darwin: "`bash` runs on macOS with the BSD userland: `grep` has no `-P` (use `grep -E` or `rg`), in-place `sed` needs an explicit backup suffix (`sed -i '' ...`), `date` uses `-v` instead of `-d`, `xargs` uses `-I{}` instead of `-i`, and other GNU-only flags are unavailable.",
+  darwin: "`bash` runs on macOS with the BSD userland: `grep` has no `-P` (use `grep -E` or `rg`), in-place `sed` needs an explicit backup suffix (`sed -i '' ...`), `date` uses `-v` instead of `-d`, `xargs` uses `-I{}` instead of `-i`, and other GNU-only flags are unavailable. `/bin/bash` is version 3.2: no associative arrays (`declare -A`), no `mapfile`/`readarray`, no `${var,,}` case conversion.",
   linux: "`bash` runs on Linux with the GNU userland: `grep -P`, `sed -i` without suffix and the usual GNU flags work.",
-  win32: "`bash` runs on Windows through Git Bash, an MSYS userland with the GNU tools: `grep -P`, `sed -i` without suffix and the usual GNU flags work. The file system is the Windows one: absolute paths are `C:/project/...` or `/c/project/...`, both spellings reach the same file, and a path from another tool may use backslashes. Files often carry CRLF line endings, so anchor patterns with `\\r\\?$` and keep the line ending a file already has. Windows programs (`dotnet`, `git`, `node`) are on the `PATH` and take Windows paths, not `/c/...`.",
+  win32: "`bash` runs on Windows with the bash RAgents brings along, an MSYS userland with the GNU tools (coreutils, `grep`, `sed`, `awk`, `find`, `xargs`, `diff`, `patch`, `tar`, `gzip`, `unzip`, `file`, `cygpath`, `dos2unix`): `grep -P`, `sed -i` without suffix and the usual GNU flags work. `git`, `dotnet` and `node` are the Windows programs of this machine on the `PATH`, with the user's own configuration and login; they take Windows paths, not `/c/...` (`cygpath -w` converts). The file system is the Windows one: absolute paths are `C:/project/...` or `/c/project/...`, both spellings reach the same file, and a path from another tool may use backslashes. Files often carry CRLF line endings, so anchor patterns with `\\r\\?$` and keep the line ending a file already has.",
 };
 
 export const shellPlatformText = (platform: NodeJS.Platform = process.platform): string => {

package/plugins/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@aicontainer/plugins",
+  "name": "@ragents/plugins",
   "private": true,
   "type": "module",
   "exports": {

package/plugins/ragents.activity/ragents-plugin.json

@@ -0,0 +1,3 @@
+{
+  "id": "ragents.activity"
+}

package/plugins/ragents.activity/server/index.ts

@@ -1,5 +1,5 @@
-import type { RAgentsPlugin } from "@aicontainer/ragents";
-import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import type { RAgentsPlugin } from "@ragents/engine";
+import type { PluginModule } from "@ragents/host/plugin-support/plugin-module.js";
 
 const activityPlugin: RAgentsPlugin = {
   manifest: { id: "ragents.activity" },

package/plugins/ragents.activity/web/ActivityHeader.tsx

@@ -5,8 +5,8 @@ import {
   elapsedLabel,
   type ActivityEntry,
 } from "./activity";
-import { ToolbarCopy, ToolbarItem, ToolbarLabel, ToolbarText } from "@aicontainer/web/Toolbar";
-import type { SessionHeaderContext } from "@aicontainer/web/PluginRegistry";
+import { ToolbarCopy, ToolbarItem, ToolbarLabel, ToolbarText } from "@ragents/web/Toolbar";
+import type { SessionHeaderContext } from "@ragents/web/PluginRegistry";
 
 const kindLabels: Readonly<Record<ActivityEntry["kind"], string>> = {
   tool: "Tool",

package/plugins/ragents.activity/web/activity.ts

@@ -72,7 +72,7 @@ const turnFrom = (value: unknown): ActivityTurn[] => {
   }];
 };
 
-/** Liest Actors und Turns aus der Laufansicht; eine noch nicht geladene oder fremde Struktur ergibt nichts. */
+/** Liest Actors und Turns aus der Run-Ansicht; eine noch nicht geladene oder fremde Struktur ergibt nichts. */
 export const activitySourceFrom = (
   runView: unknown,
 ): ActivitySource => {

package/plugins/ragents.activity/web/index.tsx

@@ -1,5 +1,5 @@
 import { ActivityHeader } from "./ActivityHeader";
-import type { WebPlugin } from "@aicontainer/web/PluginRegistry";
+import type { WebPlugin } from "@ragents/web/PluginRegistry";
 
 export const webPlugin: WebPlugin = {
   id: "ragents.activity",

package/plugins/ragents.actor-programs/prompt.hbs

@@ -8,8 +8,8 @@ its model for ActorInputs; a TypeScript actor can handle them with `onInput`. Ca
 from a view executes that function directly and does not start a model turn.
 
 1. Create the closest template with `actor_program_create`; read and reuse its package, contract,
-   implementation, view and tests under `@actors/<name>/`. Language servers use that alias;
-   Bash uses `$RAGENTS_ACTORS_DIR/<name>/`.
+   implementation, view and tests under `@actors/<name>/`, the path for file tools, language
+   servers and `bash` (as `cwd`).
 2. Edit with ordinary file tools; preserve imports and structure. Changed errors arrive before
    model requests; `actor_program_diagnostics` returns the full last check.
 3. Adapt meaningful `node:test` cases in `tests/**/*.test.ts`. Query `actor_program_controls`
@@ -17,8 +17,8 @@ from a view executes that function directly and does not start a model turn.
 4. `actor_program_activate` typechecks, builds, tests and activates. Fix errors and reactivate.
    List, removal and visibility have separate functions.
 
-Published functions enter the shared API in the same turn. Inspect with `typescript_api`, call
-`context.functions.<name>(input)`. Reactivation updates the contract; removal withdraws it.
+Published functions enter the shared API in the same turn. Reactivation updates the contract;
+removal withdraws it.
 Native tool exposure is optional and explicit.
 
 Use `actor: "self"` or `actor: "@handle"` to bind to an existing actor. Without a binding, a
@@ -40,9 +40,10 @@ Export `defineActor(contract, { functions: { ... }, onInput? })` as default. Cal
 `(input, context)`; returned values are results. Only `context.state.replace` changes actor state.
 The state schema must accept the initial `{}`. `context.actor` identifies the owning actor.
 Server code calls run functions through `context.functions`; declared `capabilities` select the
-functions it needs. An `onInput` acts as its actor. A function owns that actor's state but calls
-run functions as its caller. A subscription therefore belongs to the caller; initialize an
-actor's own event handling through its `onInput`. Snippets act as their caller.
+functions it needs. An `onInput` acts as its actor. A function owns that actor's state but acts
+as its caller, from a view the clicking human. So a subscription belongs to the caller; the
+actor's own event handling, or a message to another actor in its name, goes as an ActorInput to
+the actor, whose `onInput` handles it. Snippets act as their caller.
 
 Import React and `createRoot` normally. Import `context` and `useAppState` from `@ragents/client`
 and controls from `@ragents/client/ui`: shadcn/ui components (`Button`, `Select`, `Tabs`, `Dialog`,

package/plugins/ragents.actor-programs/ragents-plugin.json

@@ -0,0 +1,3 @@
+{
+  "id": "ragents.actor-programs"
+}

package/plugins/ragents.actor-programs/server/agent-tools.ts

@@ -1,5 +1,5 @@
-import { ToolRegistry, type RunFunction, type ExecutableActor, type PluginHost } from "@aicontainer/ragents";
-import { runtimeProviderToken, sessionWorkspaceProviderToken } from "@aicontainer/server/ragents/host-services.js";
+import { ToolRegistry, type RunFunction, type ExecutableActor, type PluginHost } from "@ragents/engine";
+import { runtimeProviderToken, runWorkspaceProviderToken } from "@ragents/host/ragents/host-services.js";
 
 export const agentToolsFrom = (host: PluginHost) =>
   async (runId: string, actorId: string, provisional?: ExecutableActor): Promise<readonly RunFunction[]> => {
@@ -11,7 +11,7 @@ export const agentToolsFrom = (host: PluginHost) =>
     }
     const registry = new ToolRegistry();
     host.tools.entries().forEach((contributor) => registry.register(contributor));
-    const workspace = await host.service(sessionWorkspaceProviderToken)(runId);
+    const workspace = await host.service(runWorkspaceProviderToken)(runId);
     const tools = await registry.resolve({
       runId,
       actorId,