@schlenkr/ragents 0.1.4 → 0.1.6

package/packages/workspace-executor/src/language-server/module.ts

@@ -0,0 +1,107 @@
+import { WorkspaceOperationError } from "../errors.js";
+import type { WorkspaceModuleFactory, WorkspaceOperation } from "../module.js";
+import { rootsOfFields, type OperationFootprint } from "../paths.js";
+import { LanguageServerHost, type LanguageServerAdapter, type LanguageServerHostOptions } from "./host.js";
+
+export const languageServerOpenOperation = (adapterId: string): string => `${adapterId}_open`;
+
+export const languageServerDiagnosticsOperation = (adapterId: string): string => `${adapterId}_diagnostics`;
+
+export const languageServerCloseOperation = (adapterId: string): string => `${adapterId}_close`;
+
+export const languageServerSnapshotOperation = (adapterId: string): string => `${adapterId}_snapshot`;
+
+export const languageServerSolutionsOperation = (adapterId: string): string => `${adapterId}_solutions`;
+
+export const languageServerSwitchOperation = (adapterId: string): string => `${adapterId}_switch`;
+
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
+
+const settledAll = async (operations: readonly Promise<void>[]): Promise<void> => {
+  const results = await Promise.allSettled(operations);
+  const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+  if (failed) throw failed.reason;
+};
+
+const invalid = (operation: string, message: string): WorkspaceOperationError =>
+  new WorkspaceOperationError("language-server-input-invalid", `${operation}: ${message}`, 400);
+
+const fieldsOf = (operation: string, input: unknown): Readonly<Record<string, unknown>> => {
+  const fields = input ?? {};
+  if (typeof fields !== "object" || Array.isArray(fields)) throw invalid(operation, "Die Eingabe muss ein Objekt sein");
+  return fields as Readonly<Record<string, unknown>>;
+};
+
+const optionalRoot = (operation: string, value: unknown): string | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") throw invalid(operation, "root muss ein Text sein");
+  return value;
+};
+
+const solutionOperationsOf = (server: LanguageServerHost): Array<readonly [string, WorkspaceOperation]> => {
+  const change = languageServerSwitchOperation(server.adapter.id);
+  return [
+    [languageServerSolutionsOperation(server.adapter.id), ({ runId }) => server.solutions(runId)],
+    [change, ({ runId, input }) => {
+      const { root } = fieldsOf(change, input);
+      if (root !== null && typeof root !== "string") throw invalid(change, "root muss ein Text oder null sein");
+      return server.switchTo(runId, root);
+    }],
+  ];
+};
+
+const operationsOf = (server: LanguageServerHost): Array<readonly [string, WorkspaceOperation]> => {
+  const { id } = server.adapter;
+  const open = languageServerOpenOperation(id);
+  const close = languageServerCloseOperation(id);
+  const diagnostics = languageServerDiagnosticsOperation(id);
+  return [
+    [open, ({ runId, input }) => {
+      const { root, ifNoneOpen } = fieldsOf(open, input);
+      const checked = optionalRoot(open, root);
+      if (checked === undefined) throw invalid(open, "root fehlt");
+      if (ifNoneOpen !== undefined && typeof ifNoneOpen !== "boolean") throw invalid(open, "ifNoneOpen muss true oder false sein");
+      return server.open(runId, checked, ifNoneOpen ?? false);
+    }],
+    [close, ({ runId, input }) => server.close(runId, optionalRoot(close, fieldsOf(close, input).root))],
+    [diagnostics, ({ runId, input }) => {
+      const { paths, warnings, root } = fieldsOf(diagnostics, input);
+      if (paths !== undefined && (!Array.isArray(paths) || !paths.every((entry) => typeof entry === "string"))) throw invalid(diagnostics, "paths muss eine Liste von Texten sein");
+      if (warnings !== undefined && typeof warnings !== "boolean") throw invalid(diagnostics, "warnings muss true oder false sein");
+      return server.diagnostics(runId, paths as readonly string[] | undefined, warnings ?? false, optionalRoot(diagnostics, root));
+    }],
+    [languageServerSnapshotOperation(id), ({ runId }) => server.snapshot(runId)],
+    ...server.adapter.solutionExtensions ? solutionOperationsOf(server) : [],
+  ];
+};
+
+/** Öffnen und Schließen sprechen die Wurzel ihrer Instanz an, die Diagnostik dazu die ihrer Dateien; ohne Wurzel und Dateien keine bestimmte. */
+const footprintsOf = (server: LanguageServerHost): Array<readonly [string, (input: unknown) => OperationFootprint]> => {
+  const { id } = server.adapter;
+  return [
+    [languageServerOpenOperation(id), (input) => ({ roots: rootsOfFields(input, "root") })],
+    [languageServerCloseOperation(id), (input) => ({ roots: rootsOfFields(input, "root") })],
+    [languageServerDiagnosticsOperation(id), (input) => ({ roots: rootsOfFields(input, "root", "paths") })],
+  ];
+};
+
+/** Die Sprachserver dieser Maschine: je Adapter Öffnen, Diagnostik, Schließen und Stand, mit Solutions auch Suche und Umschalten, dazu die Diagnostik geschriebener Dateien. */
+export const languageServerModule = (
+  adapters: readonly LanguageServerAdapter[],
+  options: LanguageServerHostOptions = {},
+): WorkspaceModuleFactory => (host) => {
+  const servers = adapters.map((adapter) => new LanguageServerHost(adapter, host.contextFor, options));
+  return {
+    operations: Object.fromEntries(servers.flatMap(operationsOf)),
+    footprints: Object.fromEntries(servers.flatMap(footprintsOf)),
+    annotate: async (runId, absolutePath) => {
+      const notes = await Promise.all(servers.map((server) =>
+        server.annotate(runId, absolutePath).catch((error: unknown) =>
+          `Diagnostik (${server.adapter.label}) fehlgeschlagen: ${messageOf(error)}`)));
+      const text = notes.filter((note): note is string => Boolean(note)).join("\n");
+      return text || undefined;
+    },
+    stopRun: (runId) => settledAll(servers.map((server) => server.stopSession(runId))),
+    shutdown: () => settledAll(servers.map((server) => server.shutdown())),
+  };
+};

package/packages/workspace-executor/src/language-server/workspace-solutions.ts

@@ -0,0 +1,90 @@
+import { readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import type { WorkspaceProcessContext } from "../context.js";
+import { runManagedProcess } from "../managed-process.js";
+import { containsWorkspacePath } from "../paths.js";
+import { sandboxedLaunch } from "../process-sandbox.js";
+
+const GIT_TIMEOUT_MS = 30 * 1000;
+const DIRECTORY_DEPTH = 6;
+const SKIPPED_DIRECTORIES = new Set(["node_modules", "bin", "obj"]);
+
+interface GitResult {
+  code: number | null;
+  output: string;
+}
+
+interface FoundSolution {
+  path: string;
+  root: string;
+}
+
+export const runGit = async (
+  context: WorkspaceProcessContext,
+  directory: string,
+  args: readonly string[],
+): Promise<GitResult> => {
+  const chunks: Buffer[] = [];
+  const launch = await sandboxedLaunch(context, { command: "git", args });
+  const result = await runManagedProcess({
+    command: launch.command,
+    args: [...launch.args],
+    cwd: directory,
+    env: context.env,
+    uid: context.uid,
+    gid: context.gid,
+    label: `git ${args[0]}`,
+    timeoutMs: GIT_TIMEOUT_MS,
+    onStdout: (chunk) => { chunks.push(chunk); },
+  });
+  return { code: result.code, output: Buffer.concat(chunks).toString("utf8") };
+};
+
+const skipped = (name: string): boolean => SKIPPED_DIRECTORIES.has(name.toLowerCase());
+
+const matches = (relative: string, extensions: readonly string[]): boolean =>
+  extensions.includes(path.extname(relative).toLowerCase())
+  && !relative.split("/").slice(0, -1).some(skipped);
+
+const gitSolutions = async (context: WorkspaceProcessContext, extensions: readonly string[]): Promise<string[] | undefined> => {
+  if ((await runGit(context, context.root, ["rev-parse", "--is-inside-work-tree"])).code !== 0) return undefined;
+  const listed = await runGit(context, context.root, [
+    "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--",
+    ...extensions.map((extension) => `:(icase)*${extension}`),
+  ]);
+  if (listed.code !== 0) throw new Error(`git ls-files ist mit Code ${listed.code} gescheitert`);
+  return listed.output.split("\0").filter(Boolean);
+};
+
+const directorySolutions = async (root: string, extensions: readonly string[], relative = "", depth = 0): Promise<string[]> => {
+  const entries = await readdir(path.join(root, relative), { withFileTypes: true });
+  const nested = await Promise.all(entries.map(async (entry) => {
+    const child = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      return depth < DIRECTORY_DEPTH && !entry.name.startsWith(".") && !skipped(entry.name)
+        ? directorySolutions(root, extensions, child, depth + 1)
+        : [];
+    }
+    return entry.isFile() ? [child] : [];
+  }));
+  return nested.flat();
+};
+
+/** Ohne Git-Arbeitsverzeichnis durchsucht es den Ordner selbst, sechs Ebenen tief und ohne versteckte Ordner. */
+export const workspaceSolutions = async (
+  context: WorkspaceProcessContext,
+  extensions: readonly string[],
+): Promise<{ source: "git" | "directory"; solutions: FoundSolution[] }> => {
+  const tracked = await gitSolutions(context, extensions);
+  const candidates = [...new Set(tracked ?? await directorySolutions(context.root, extensions))]
+    .filter((relative) => matches(relative, extensions))
+    .sort((left, right) => left.localeCompare(right, "de"));
+  const workspaceRoot = await realpath(context.root);
+  const found = await Promise.all(candidates.map(async (relative): Promise<FoundSolution | undefined> => {
+    const absolute = path.join(context.root, relative);
+    if (!await stat(absolute).then((info) => info.isFile(), () => false)) return undefined;
+    const root = await realpath(absolute);
+    return containsWorkspacePath(workspaceRoot, root) ? { path: relative, root } : undefined;
+  }));
+  return { source: tracked ? "git" : "directory", solutions: found.filter((entry) => entry !== undefined) };
+};

package/packages/workspace-executor/src/managed-process.ts

@@ -1,7 +1,7 @@
 import { execFile, spawn, type ChildProcess } from "node:child_process";
 import { readdir, readFile } from "node:fs/promises";
 import type { Writable } from "node:stream";
-import { killProcessTree } from "@aicontainer/agent";
+import { killProcessTree } from "@ragents/agent";
 
 const PROCESS_GROUP_JOIN_TIMEOUT_MS = 5_000;
 const PROCESS_GROUP_POLL_MS = 25;

package/packages/workspace-executor/src/module.ts

@@ -0,0 +1,35 @@
+import type { WorkspaceProcessContext } from "./context.js";
+import type { OperationFootprint } from "./paths.js";
+
+/** Ein Aufruf einer Operation: der Run, die Eingabe und was der Aufrufer mitgibt. */
+export interface WorkspaceOperationCall {
+  readonly runId: string;
+  readonly input: unknown;
+  readonly toolCallId: string | undefined;
+  readonly signal: AbortSignal | undefined;
+  /** Meldet einen JSON-Wert als Fortschritt; fehlt, wenn der Aufrufer keinen Fortschritt will. */
+  readonly progress: ((value: unknown) => void) | undefined;
+}
+
+export type WorkspaceOperation = (call: WorkspaceOperationCall) => Promise<unknown>;
+
+/** Ein Baustein des Executors: benannte Operationen und sein Anteil am Aufräumen. */
+export interface WorkspaceExecutorModule {
+  readonly operations: Readonly<Record<string, WorkspaceOperation>>;
+  /** Der Fußabdruck einer Eingabe je Operation; ohne Eintrag spricht sie keine bestimmte Wurzel an. Wirft nie, auch nicht bei ungültiger Eingabe. */
+  readonly footprints?: Readonly<Record<string, (input: unknown) => OperationFootprint>>;
+  /** Eine Anmerkung zu einer gerade geschriebenen Datei, etwa die Diagnostik eines Sprachservers. */
+  readonly annotate?: (runId: string, absolutePath: string) => Promise<string | undefined>;
+  /** Gibt frei, was das Modul für einen Run hält. */
+  readonly stopRun?: (runId: string) => Promise<void>;
+  /** Gibt alles frei; danach ruft niemand das Modul mehr auf, es darf spätere Aufrufe mit Ursache ablehnen. */
+  readonly shutdown?: () => Promise<void>;
+}
+
+/** Was ein Modul vom Executor bekommt: den Kontext eines Runs auf dieser Maschine und die Anmerkungen aller Module. */
+export interface WorkspaceModuleHost {
+  readonly contextFor: (runId: string) => Promise<WorkspaceProcessContext>;
+  readonly annotate: (runId: string, absolutePath: string) => Promise<string | undefined>;
+}
+
+export type WorkspaceModuleFactory = (host: WorkspaceModuleHost) => WorkspaceExecutorModule;

package/packages/workspace-executor/src/modules.ts

@@ -0,0 +1,25 @@
+import { browserModule } from "./browser/module.js";
+import { commandModule } from "./commands.js";
+import { fileModule } from "./files.js";
+import { workspaceLanguageServers } from "./language-server/adapters/index.js";
+import { languageServerModule } from "./language-server/module.js";
+import type { WorkspaceModuleFactory } from "./module.js";
+import { processModule } from "./processes/module.js";
+import { runFolderModule } from "./run-folders.js";
+import { sandboxToolsModule } from "./sandbox-tools.js";
+
+export interface WorkspaceExecutorModuleOptions {
+  /** Der neue Ordner eines Runs auf dieser Maschine; nur ein Arbeitsplatz kennt ihn, auf dem Server legt ihn der Host an. */
+  runFolder?: (runId: string) => string;
+}
+
+/** Die Module jedes Executors, im Server wie auf dem Arbeitsplatz dieselben. */
+export const workspaceExecutorModules = (options: WorkspaceExecutorModuleOptions = {}): readonly WorkspaceModuleFactory[] => [
+  sandboxToolsModule,
+  languageServerModule(workspaceLanguageServers),
+  fileModule,
+  processModule(),
+  commandModule(),
+  browserModule(),
+  runFolderModule(options.runFolder),
+];

package/packages/workspace-executor/src/paths.ts

@@ -1,17 +1,65 @@
 import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
+import { WorkspaceOperationError } from "./errors.js";
 
 export interface ResolvedWorkspaceRoot {
   directory: string;
+  /** `@name`, bei einer Wurzel unter einem gemeinsamen Alias `@name/<ordner>`. */
   alias?: string;
   environmentVariable?: string;
 }
 
+/** Welche Wurzeln die Eingabe einer Operation anspricht: die Aliasse zusätzlicher Wurzeln und ob ein Pfad ohne Alias die Wurzel des Runs nennt. */
+export interface AddressedRoots {
+  readonly aliases: readonly string[];
+  readonly runRoot: boolean;
+}
+
+export const NO_ROOTS: AddressedRoots = { aliases: [], runRoot: false };
+
+/** Was ein Aufrufer über eine Eingabe wissen muss, ohne ihre Form zu kennen: die Wurzeln, die sie anspricht, und die Laufzeit, die sie selbst verlangt. */
+export interface OperationFootprint {
+  readonly roots: AddressedRoots;
+  readonly durationMs?: number;
+}
+
+/** Der Alias, mit dem ein Pfad beginnt, ist sein erster Abschnitt, wenn der mit @ beginnt. */
+export const aliasOf = (location: string): string | undefined =>
+  location.startsWith("@") ? location.split("/")[0] : undefined;
+
+/** Die Wurzeln, die Felder einer Eingabe als Pfade nennen, eine Liste mit jedem Eintrag: ein Pfad mit Alias dessen Wurzel, jeder andere die des Runs. */
+export const rootsOfFields = (input: unknown, ...keys: readonly string[]): AddressedRoots => {
+  const fields: Readonly<Record<string, unknown>> = typeof input === "object" && input !== null ? input as Record<string, unknown> : {};
+  const named = keys.flatMap((key) => [fields[key]].flat()).filter((entry): entry is string => typeof entry === "string");
+  const aliases = named.map(aliasOf).filter((alias): alias is string => alias !== undefined);
+  return { aliases: [...new Set(aliases)], runRoot: named.some((entry) => aliasOf(entry) === undefined) };
+};
+
+/** Die Wurzel, die ein Pfad mit Alias nennt, und der Rest darunter; ohne passenden Alias keine. */
+export const aliasedRoot = (
+  requested: string,
+  aliases: Readonly<Record<string, string>>,
+): { directory: string; rest: string } | undefined => {
+  const found = Object.entries(aliases).find(([alias]) => requested === alias || requested.startsWith(`${alias}/`));
+  return found && { directory: found[1], rest: requested.slice(found[0].length + 1) };
+};
+
+/** Nennt bei einem gemeinsamen Alias wie `@skills` auch den Ordner darunter, weil erst beide eine Wurzel bestimmen. */
+export const unknownAliasError = (requested: string, aliases: Readonly<Record<string, string>>): WorkspaceOperationError => {
+  const [first, second] = requested.split("/");
+  const known = Object.keys(aliases);
+  const named = second !== undefined && known.some((alias) => alias.startsWith(`${first}/`)) ? `${first}/${second}` : first;
+  return new WorkspaceOperationError(
+    "workspace-alias-unknown",
+    `Unbekannter Arbeitsverzeichnis-Alias: ${named} (bekannt: ${known.length > 0 ? known.join(", ") : "keine"})`,
+    400,
+  );
+};
+
 export const expandWorkspaceAlias = (requested: string, aliases: Readonly<Record<string, string>>): string => {
-  for (const [alias, directory] of Object.entries(aliases)) {
-    if (requested === alias || requested.startsWith(`${alias}/`)) return path.join(directory, requested.slice(alias.length));
-  }
-  if (requested.startsWith("@")) throw new Error(`Unbekannter Arbeitsverzeichnis-Alias: ${requested.split("/")[0]}`);
+  const found = aliasedRoot(requested, aliases);
+  if (found) return path.join(found.directory, found.rest);
+  if (requested.startsWith("@")) throw unknownAliasError(requested, aliases);
   return requested;
 };
 
@@ -33,7 +81,11 @@ export const resolvedWorkspacePath = async (filename: string): Promise<string> =
   }
 };
 
-export const containsWorkspacePath = (root: string, filename: string): boolean => filename === root || filename.startsWith(`${root}${path.sep}`);
+/** Liegt der Pfad in der Wurzel oder ist er sie selbst; auch für eine Laufwerkswurzel wie `/` oder `C:\`. */
+export const containsWorkspacePath = (root: string, filename: string): boolean => {
+  const relative = path.relative(root, filename);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+};
 
 export const allowedWorkspacePath = async (filename: string, roots: readonly string[]): Promise<string> => {
   const absolute = await resolvedWorkspacePath(filename);

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

@@ -0,0 +1,16 @@
+import type { WorkspaceProcessContext } from "./context.js";
+
+/** Ein Programm mit seinen Argumenten, so wie es gestartet wird. */
+export interface ProcessLaunch {
+  readonly command: string;
+  readonly args: readonly string[];
+}
+
+/** Wie ein Executor die Prozesse eines Runs in seine Sandbox steckt; der Kontext trägt sie, jeder Start fragt sie. */
+export interface ProcessSandbox {
+  readonly wrap: (launch: ProcessLaunch) => Promise<ProcessLaunch>;
+}
+
+/** Der Start eines Prozesses im Kontext eines Runs: mit Sandbox eingepackt, ohne unverändert. */
+export const sandboxedLaunch = (context: WorkspaceProcessContext, launch: ProcessLaunch): Promise<ProcessLaunch> =>
+  context.sandbox ? context.sandbox.wrap(launch) : Promise.resolve(launch);

package/packages/workspace-executor/src/processes/module.ts

@@ -0,0 +1,48 @@
+import { WorkspaceOperationError } from "../errors.js";
+import type { WorkspaceModuleFactory } from "../module.js";
+import { hasProcessTable, processTableForPlatform, type ProcessTable } from "./process-table.js";
+import { ProcessScanner } from "./scanner.js";
+import { RunProcessTerminator } from "./terminator.js";
+
+export const PROCESS_OPERATIONS = {
+  snapshot: "processes.snapshot",
+  stop: "processes.stop",
+  stopAll: "processes.stopAll",
+} as const;
+
+export interface ProcessModuleOptions {
+  /** Die Prozesstabelle dieser Maschine; ohne Angabe die der Plattform, aufgelöst erst im Aufruf. */
+  table?: () => ProcessTable;
+}
+
+const processIdOf = (input: unknown): string => {
+  const value = (input as { processId?: unknown } | null)?.processId;
+  if (typeof value !== "string") throw new WorkspaceOperationError("invalid-process", "Ungültige Prozessreferenz", 400);
+  return value;
+};
+
+/** Die markierten Prozesse eines Runs auf dieser Maschine; ohne Prozesstabelle (Windows) räumt der Stopp nur die Bash-Bäume ab. */
+export const processModule = (options: ProcessModuleOptions = {}): WorkspaceModuleFactory => () => {
+  const table = options.table ?? (() => processTableForPlatform());
+  const cleansUp = options.table !== undefined || hasProcessTable();
+  const identity = { executorPid: process.pid, executorUid: process.getuid?.() };
+  const scanner = new ProcessScanner({ table, ...identity });
+  const terminator = (): RunProcessTerminator => new RunProcessTerminator({ table: table(), ...identity });
+  const stopAll = async (runId: string, signal?: AbortSignal): Promise<null> => {
+    if (cleansUp) await terminator().stopRun(runId, signal ? { signal } : {});
+    return null;
+  };
+  return {
+    operations: {
+      [PROCESS_OPERATIONS.snapshot]: ({ runId }) => scanner.snapshot(runId),
+      [PROCESS_OPERATIONS.stop]: async ({ runId, input, signal }) => {
+        await terminator().stop(runId, processIdOf(input), signal ? { signal } : {});
+        return null;
+      },
+      [PROCESS_OPERATIONS.stopAll]: ({ runId, signal }) => stopAll(runId, signal),
+    },
+    stopRun: async (runId) => {
+      await stopAll(runId);
+    },
+  };
+};