@schlenkr/ragents 0.1.0

package/scripts/package/build-package.ts

@@ -0,0 +1,249 @@
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { copyFile, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { builtinModules } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readHostVersion, readPackageVersion } from "../../apps/server/src/host-version.ts";
+import { runtimeLibraries } from "../../plugins/ragents.actor-programs/server/runtime-libraries.ts";
+
+export const PACKAGE_NAME = "@schlenkr/ragents";
+/** Der Ordner unter dist/; der Paketname hat einen Scope, der Ordnername bleibt schlicht. */
+export const PACKAGE_FOLDER = "ragents";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+const SKIPPED_FOLDERS = new Set(["node_modules", "dist", ".git"]);
+const SKIPPED_FILES = new Set([".DS_Store"]);
+
+/** Die Prüfungen der Unterbefehle laufen im Checkout; im Paket wäre nur ihr Testmaterial zu sehen. */
+const SKIPPED_IN_PACKAGE = /^scripts\/.*\.test\.tsx?$/;
+
+const packagePath = (packageRoot: string, file: string): string => path.relative(packageRoot, file).split(path.sep).join("/");
+
+/** Die neutralen Profile des Repositories; ragents start fährt sie aus dem Paket wie aus dem Checkout. */
+export const PACKAGED_PROFILES = ["core", "developer"] as const;
+
+export const PACKAGE_LICENSE = "PolyForm-Shield-1.0.0";
+export const PACKAGE_AUTHOR = "Ronald Schlenker";
+export const REPOSITORY_URL = "https://github.com/SchlenkR/RAgents";
+export const PACKAGE_KEYWORDS = ["agents", "llm", "actors", "typescript", "csharp", "fsharp", "vscode"] as const;
+
+/** Lizenz und Listing-README liegen an der Wurzel des Pakets, ihre Quellen im Repository woanders. */
+export const PACKAGE_ROOT_FILES: readonly (readonly [string, string])[] = [
+  ["LICENSE", "LICENSE"],
+  ["scripts/package/README.md", "README.md"],
+];
+
+const ROOT_FILE_SOURCES = new Set(PACKAGE_ROOT_FILES.map(([source]) => source));
+
+const skippedInPackage = (relative: string): boolean => SKIPPED_IN_PACKAGE.test(relative) || ROOT_FILE_SOURCES.has(relative);
+
+/** Was der Host zur Laufzeit lädt: Server, Engine, Plugins, Profile und die Skripte hinter den Unterbefehlen. */
+export const packageContents = (root = repositoryRoot): readonly string[] => [
+  "apps/server/package.json",
+  "apps/server/src",
+  "apps/server/agent-home/settings.json",
+  "apps/web/package.json",
+  "apps/web/src",
+  ...readdirSync(path.join(root, "packages"), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .flatMap((entry) => [`packages/${entry.name}/package.json`, `packages/${entry.name}/src`]),
+  "plugins",
+  ...PACKAGED_PROFILES.map((profile) => `ragents.config.${profile}.ts`),
+  "scripts/agent",
+  "scripts/package",
+  "scripts/provision",
+  "scripts/remote",
+  "scripts/workspace-client",
+];
+
+/** Was der Host ausführt oder in eine Mini-App bündelt; die web-Ordner der Plugins baut der zentrale Server. */
+const SCANNED = ["apps/server/src", "apps/web/src", "packages", "plugins", "scripts"];
+const PACKAGE_NAME_PATTERN = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+const SCAN_SKIPPED = new Set(["web", "node_modules", "dist"]);
+const SCANNED_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".mjs", ".js", ".css"]);
+const IMPORT_PATTERN = /\b(?:from|import|require(?:\.resolve)?)\s*\(?\s*["']([^"'\n]+)["']/g;
+
+const files = async (folder: string): Promise<readonly string[]> => {
+  const found: string[] = [];
+  for (const entry of (await readdir(folder, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+    if (entry.isDirectory()) {
+      if (!SKIPPED_FOLDERS.has(entry.name)) found.push(...await files(path.join(folder, entry.name)));
+    } else if (entry.isFile() && !SKIPPED_FILES.has(entry.name)) {
+      found.push(path.join(folder, entry.name));
+    }
+  }
+  return found;
+};
+
+const copyTo = async (source: string, target: string, packageRoot: string): Promise<readonly string[]> => {
+  if (statSync(source).isFile()) {
+    if (skippedInPackage(packagePath(packageRoot, target))) return [];
+    await mkdir(path.dirname(target), { recursive: true });
+    await copyFile(source, target);
+    return [target];
+  }
+  const copied: string[] = [];
+  for (const file of await files(source)) {
+    const destination = path.join(target, path.relative(source, file));
+    if (skippedInPackage(packagePath(packageRoot, destination))) continue;
+    await mkdir(path.dirname(destination), { recursive: true });
+    await copyFile(file, destination);
+    copied.push(destination);
+  }
+  return copied;
+};
+
+const scanRoots = (root: string): readonly string[] => SCANNED.map((entry) => path.join(root, entry));
+
+const scannedFiles = (folder: string): readonly string[] => {
+  if (!statSync(folder, { throwIfNoEntry: false })?.isDirectory()) return [];
+  return readdirSync(folder, { withFileTypes: true }).flatMap((entry) => {
+    const absolute = path.join(folder, entry.name);
+    if (entry.isDirectory()) return SCAN_SKIPPED.has(entry.name) ? [] : scannedFiles(absolute);
+    return entry.isFile() && SCANNED_EXTENSIONS.has(path.extname(entry.name)) ? [absolute] : [];
+  });
+};
+
+const packageNameOf = (specifier: string): string | undefined => {
+  if (/^(\.{1,2}\/|\/|node:|data:|@aicontainer\/|@ragents\/|virtual:)/.test(specifier) || specifier === "vscode") return undefined;
+  const parts = specifier.split("/");
+  const name = specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]!;
+  if (builtinModules.includes(name)) return undefined;
+  return PACKAGE_NAME_PATTERN.test(name) ? name : undefined;
+};
+
+/** Die Pakete, die der ausgeführte Teil des Pakets wirklich importiert, plus die zur Laufzeit verlinkten Bibliotheken. */
+export const requiredPackages = (packageDirectory: string): ReadonlyMap<string, string> => {
+  const sources = new Map<string, string>();
+  for (const name of runtimeLibraries) sources.set(name, "plugins/ragents.actor-programs (verlinkt zur Laufzeit)");
+  for (const folder of scanRoots(packageDirectory)) {
+    for (const file of scannedFiles(folder)) {
+      const content = readFileSync(file, "utf8");
+      for (const match of content.matchAll(IMPORT_PATTERN)) {
+        const name = packageNameOf(match[1]!);
+        if (name && !sources.has(name)) sources.set(name, path.relative(packageDirectory, file));
+      }
+    }
+  }
+  return new Map([...sources].sort(([left], [right]) => left.localeCompare(right, "en")));
+};
+
+const compareVersions = (left: string, right: string): number => {
+  const parts = (value: string) => value.split(/[.+-]/).map((part) => Number.isInteger(Number(part)) ? Number(part) : part);
+  const [first, second] = [parts(left), parts(right)];
+  for (let index = 0; index < Math.max(first.length, second.length); index += 1) {
+    const [one, other] = [first[index] ?? 0, second[index] ?? 0];
+    if (one === other) continue;
+    return typeof one === "number" && typeof other === "number" ? one - other : String(one).localeCompare(String(other), "en");
+  }
+  return 0;
+};
+
+const anchors = (root: string): readonly string[] => [
+  path.join(root, "package.json"),
+  ...["apps", "packages"].flatMap((group) => readdirSync(path.join(root, group), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(root, group, entry.name, "package.json"))
+    .filter((file) => statSync(file, { throwIfNoEntry: false })?.isFile() === true)),
+];
+
+/** Die Fassungen, die dieser Checkout für ein Paket installiert hat; die jüngste kommt ins Paket. */
+export const installedVersions = (name: string, root = repositoryRoot): readonly string[] => {
+  const found = new Set<string>();
+  for (const anchor of anchors(root)) {
+    for (let directory = path.dirname(anchor); ; directory = path.dirname(directory)) {
+      const file = path.join(directory, "node_modules", ...name.split("/"), "package.json");
+      if (statSync(file, { throwIfNoEntry: false })?.isFile()) {
+        found.add((JSON.parse(readFileSync(file, "utf8")) as { version: string }).version);
+        break;
+      }
+      if (path.dirname(directory) === directory) break;
+    }
+  }
+  const versions = [...found].sort(compareVersions);
+  if (versions.length === 0) throw new Error(`Das Paket ${name} ist in diesem Checkout nicht installiert; ohne Fassung kann es nicht ins Paket`);
+  return versions;
+};
+
+export interface BuiltPackage {
+  readonly directory: string;
+  readonly manifest: Record<string, unknown>;
+  readonly fileCount: number;
+  readonly byteSize: number;
+  readonly flattened: readonly string[];
+}
+
+export const buildPackage = async (target: string, root = repositoryRoot): Promise<BuiltPackage> => {
+  await rm(target, { recursive: true, force: true });
+  await mkdir(target, { recursive: true });
+  let fileCount = 0;
+  let byteSize = 0;
+  for (const entry of packageContents(root)) {
+    const copied = await copyTo(path.join(root, entry), path.join(target, entry), target);
+    fileCount += copied.length;
+    for (const file of copied) byteSize += statSync(file).size;
+  }
+  for (const [source, packaged] of PACKAGE_ROOT_FILES) {
+    const destination = path.join(target, packaged);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await copyFile(path.join(root, source), destination);
+    fileCount += 1;
+    byteSize += statSync(destination).size;
+  }
+  const flattened: string[] = [];
+  const dependencies: Record<string, string> = {};
+  for (const [name] of requiredPackages(target)) {
+    const versions = installedVersions(name, root);
+    if (versions.length > 1) flattened.push(`${name}: ${versions.join(", ")} -> ${versions.at(-1)!}`);
+    dependencies[name] = versions.at(-1)!;
+  }
+  const manifest = {
+    name: PACKAGE_NAME,
+    version: readPackageVersion(root),
+    description: "RAgents-Host: Server, Engine, Plugins und Werkzeuge ohne Quell-Checkout",
+    keywords: [...PACKAGE_KEYWORDS],
+    homepage: `${REPOSITORY_URL}#readme`,
+    bugs: { url: `${REPOSITORY_URL}/issues` },
+    license: PACKAGE_LICENSE,
+    author: PACKAGE_AUTHOR,
+    repository: { type: "git", url: `git+${REPOSITORY_URL}.git` },
+    type: "module",
+    bin: { ragents: "scripts/package/ragents.mjs" },
+    engines: { node: ">=22.19.0" },
+    publishConfig: { access: "public" },
+    dependencies,
+    ragents: { hostVersion: readHostVersion(root) },
+  };
+  const manifestFile = path.join(target, "package.json");
+  await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+  fileCount += 1;
+  byteSize += statSync(manifestFile).size;
+  return { directory: target, manifest, fileCount, byteSize, flattened };
+};
+
+const main = async (): Promise<void> => {
+  const pack = process.argv.includes("--pack");
+  const unknown = process.argv.slice(2).filter((argument) => argument !== "--pack");
+  if (unknown.length) throw new Error(`Unbekanntes Argument: ${unknown.join(" ")} (erlaubt: --pack)`);
+  const target = path.join(repositoryRoot, "dist", PACKAGE_FOLDER);
+  const built = await buildPackage(target);
+  console.log(`== Paket ${PACKAGE_NAME}@${built.manifest.version as string} in ${built.directory}`);
+  console.log(`== Host-Version ${(built.manifest.ragents as { hostVersion: string }).hostVersion}`);
+  console.log(`== ${built.fileCount} Dateien, ${(built.byteSize / 1024 / 1024).toFixed(1)} MB, ${Object.keys(built.manifest.dependencies as object).length} Abhängigkeiten`);
+  for (const [name, version] of Object.entries(built.manifest.dependencies as Record<string, string>)) console.log(`   ${name}@${version}`);
+  for (const entry of built.flattened) console.log(`== Mehrfachfassung abgeflacht: ${entry}`);
+  if (!pack) return;
+  const packed = spawnSync("npm", ["pack", "--pack-destination", path.dirname(built.directory)], { cwd: built.directory, encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
+  if (packed.status !== 0) throw new Error(`npm pack endete mit Code ${packed.status}`);
+  console.log(`== Archiv ${path.join(path.dirname(built.directory), packed.stdout.trim().split("\n").at(-1) ?? "")}`);
+};
+
+const moduleUrl: string | undefined = import.meta.url;
+if (moduleUrl && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(moduleUrl)) {
+  main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/package/host-links.d.mts

@@ -0,0 +1 @@
+export declare const ensureHostLinks: (root: string) => readonly string[];

package/scripts/package/host-links.mjs

@@ -0,0 +1,39 @@
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, symlinkSync } from "node:fs";
+import path from "node:path";
+
+const isFile = (file) => statSync(file, { throwIfNoEntry: false })?.isFile() === true;
+
+const workspaceFolders = (root) => [
+  ...["apps", "packages"].flatMap((group) => {
+    const folder = path.join(root, group);
+    if (!statSync(folder, { throwIfNoEntry: false })?.isDirectory()) return [];
+    return readdirSync(folder, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => path.join(folder, entry.name));
+  }),
+  path.join(root, "plugins"),
+].filter((folder) => isFile(path.join(folder, "package.json")));
+
+const nameOf = (folder) => {
+  const file = path.join(folder, "package.json");
+  const name = JSON.parse(readFileSync(file, "utf8")).name;
+  if (typeof name !== "string" || !name) throw new Error(`${file} nennt keinen Paketnamen`);
+  return name;
+};
+
+/** Legt im Paket @schlenkr/ragents die Verknüpfungen an, die im Checkout von pnpm kommen; im Checkout tut sie nichts. */
+export const ensureHostLinks = (root) => {
+  const manifest = path.join(root, "package.json");
+  if (!isFile(manifest) || JSON.parse(readFileSync(manifest, "utf8")).ragents?.hostVersion === undefined) return [];
+  const created = [];
+  for (const folder of workspaceFolders(root)) {
+    const link = path.join(root, "node_modules", nameOf(folder));
+    const existing = lstatSync(link, { throwIfNoEntry: false });
+    if (existing) {
+      if (realpathSync(link) !== realpathSync(folder)) throw new Error(`${link} zeigt nicht auf ${folder}; das Paket ist beschädigt`);
+      continue;
+    }
+    mkdirSync(path.dirname(link), { recursive: true });
+    symlinkSync(folder, link, process.platform === "win32" ? "junction" : "dir");
+    created.push(path.relative(path.join(root, "node_modules"), link));
+  }
+  return created;
+};

package/scripts/package/publish-package.ts

@@ -0,0 +1,129 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildPackage, PACKAGE_FOLDER, PACKAGE_NAME } from "./build-package.ts";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+const usage = `Verwendung: pnpm publish:package [--dry-run]
+Baut das Paket ${PACKAGE_NAME} und veröffentlicht es auf npm. Der Token kommt aus der
+Umgebungsvariable npm_key. --dry-run reicht npm den Probelauf durch und veröffentlicht nichts.
+Die Fassung steht in der package.json der Wurzel und wird von Hand erhöht.`;
+
+const REGISTRY_TOKEN_KEY = "npm_config_//registry.npmjs.org/:_authToken";
+
+export interface NpmResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export type NpmRunner = (args: readonly string[], options: { cwd: string; token?: string }) => NpmResult;
+
+/** Der Token geht nur als Konfiguration in die Umgebung des Kindprozesses, nie auf die Kommandozeile. */
+export const publishEnvironment = (token: string, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv =>
+  ({ ...base, [REGISTRY_TOKEN_KEY]: token });
+
+/** Alles, was von npm kommt, geht durch diese Maske, damit der Token auch in einer Fehlermeldung nicht auftaucht. */
+export const redacting = (token: string) => (text: string): string => token ? text.split(token).join("<npm_key>") : text;
+
+/** Eine Fehlermeldung ist eine Zeile; die Ausgabe von npm wandert deshalb auf eine. */
+export const oneLine = (text: string): string => text.split("\n").map((line) => line.trim()).filter(Boolean).join("; ");
+
+const runNpm: NpmRunner = (args, options) => {
+  const result = spawnSync("npm", [...args], {
+    cwd: options.cwd,
+    encoding: "utf8",
+    env: options.token ? publishEnvironment(options.token) : process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.error) throw new Error(`npm ${args[0]} konnte nicht gestartet werden: ${result.error.message}`);
+  return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+};
+
+/** Die Fassungen, die schon auf npm liegen; ein dort unbekanntes Paket ist die leere Liste, kein Fehler. */
+export const publishedVersions = (name: string, npm: NpmRunner): readonly string[] => {
+  const result = npm(["view", name, "versions", "--json"], { cwd: repositoryRoot });
+  if (result.status !== 0) {
+    if (/E404|404 Not Found/.test(`${result.stdout}\n${result.stderr}`)) return [];
+    throw new Error(`npm view ${name} versions endete mit Code ${result.status}: ${oneLine(result.stderr)}`);
+  }
+  const parsed = JSON.parse(result.stdout.trim() || "[]") as string | readonly string[];
+  return typeof parsed === "string" ? [parsed] : parsed;
+};
+
+export interface PublishPlan {
+  readonly name: string;
+  readonly version: string;
+  readonly hostVersion: string;
+}
+
+/** Was vor einem Publish stimmen muss: das gebaute Manifest und eine Fassung, die es auf npm noch nicht gibt. */
+export const publishPlan = (manifest: Record<string, unknown>, published: readonly string[]): PublishPlan => {
+  const { name, version } = manifest as { name?: unknown; version?: unknown };
+  const access = (manifest.publishConfig as { access?: unknown } | undefined)?.access;
+  const hostVersion = (manifest.ragents as { hostVersion?: unknown } | undefined)?.hostVersion;
+  if (name !== PACKAGE_NAME) throw new Error(`Das gebaute Paket heißt ${String(name)}, veröffentlicht wird ${PACKAGE_NAME}`);
+  if (access !== "public") throw new Error(`${PACKAGE_NAME} hat einen Scope und braucht publishConfig.access "public", nicht ${JSON.stringify(access)}`);
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/.test(version)) {
+    throw new Error(`Die Fassung ${JSON.stringify(version)} ist keine Fassung; sie steht als version in der package.json der Wurzel`);
+  }
+  if (typeof hostVersion !== "string" || !/^[0-9a-f]{40}$/.test(hostVersion)) {
+    throw new Error("Dem Paket fehlt ragents.hostVersion als vollständiger Git-Commit; gebaut wird nur aus einem Checkout");
+  }
+  if (published.includes(version)) {
+    throw new Error(`${PACKAGE_NAME}@${version} liegt schon auf npm (dort: ${published.join(", ")}); `
+      + "erhöhe version in der package.json der Wurzel und baue neu");
+  }
+  return { name: PACKAGE_NAME, version, hostVersion };
+};
+
+export interface PublishOptions {
+  readonly directory: string;
+  readonly token: string;
+  readonly dryRun: boolean;
+  readonly npm: NpmRunner;
+  readonly log: (line: string) => void;
+}
+
+/** npm meldet eine fehlende Organisation als 404; ohne den Hinweis sucht man den Fehler beim Paket. */
+const scopeAdvice = (output: string): string => /Scope not found/i.test(output)
+  ? ` Die Organisation ${PACKAGE_NAME.split("/")[0]} existiert auf npm nicht oder der Token darf sie nicht: `
+    + "auf npmjs.com anlegen bzw. den Token für den Scope freigeben."
+  : "";
+
+/** Veröffentlicht den gebauten Ordner und nennt danach die Fassung, die npm ausliefert. */
+export const publishDirectory = (options: PublishOptions): void => {
+  const hide = redacting(options.token);
+  const published = options.npm(["publish", "--access", "public", ...options.dryRun ? ["--dry-run"] : []], { cwd: options.directory, token: options.token });
+  const output = `${published.stdout}${published.stderr}`;
+  for (const line of output.split("\n")) if (line.trim()) options.log(hide(line));
+  if (published.status !== 0) throw new Error(`npm publish endete mit Code ${published.status}.${scopeAdvice(output)}`);
+  if (options.dryRun) {
+    options.log("== Probelauf: nichts veröffentlicht");
+    return;
+  }
+  const view = options.npm(["view", PACKAGE_NAME, "version"], { cwd: repositoryRoot });
+  if (view.status !== 0) throw new Error(`npm view ${PACKAGE_NAME} version endete mit Code ${view.status}: ${hide(oneLine(view.stderr))}`);
+  options.log(`== Auf npm steht jetzt ${PACKAGE_NAME}@${view.stdout.trim()}`);
+};
+
+const main = async (): Promise<void> => {
+  const dryRun = process.argv.includes("--dry-run");
+  const unknown = process.argv.slice(2).filter((argument) => argument !== "--dry-run");
+  if (unknown.length) throw new Error(`Unbekanntes Argument: ${unknown.join(" ")}\n${usage}`);
+  const token = process.env.npm_key;
+  if (!token) throw new Error(`npm_key fehlt: der npm-Token mit Schreibrecht auf ${PACKAGE_NAME}.\n${usage}`);
+  const built = await buildPackage(path.join(repositoryRoot, "dist", PACKAGE_FOLDER));
+  const plan = publishPlan(built.manifest, publishedVersions(PACKAGE_NAME, runNpm));
+  console.log(`== ${plan.name}@${plan.version} aus Host ${plan.hostVersion.slice(0, 12)}, ${built.fileCount} Dateien, ${(built.byteSize / 1024 / 1024).toFixed(1)} MB`);
+  publishDirectory({ directory: built.directory, token, dryRun, npm: runNpm, log: (line) => console.log(line) });
+};
+
+const moduleUrl: string | undefined = import.meta.url;
+if (moduleUrl && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(moduleUrl)) {
+  main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/package/ragents.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureHostLinks } from "./host-links.mjs";
+
+const AGENT_CLI = "scripts/agent/agent-cli.ts";
+
+export const commands = {
+  connect: "scripts/remote/connect.ts",
+  start: "scripts/remote/start.ts",
+  provision: "scripts/provision/run-provision.ts",
+  "workspace-client": "scripts/workspace-client/run-workspace-client.ts",
+  run: AGENT_CLI,
+  send: AGENT_CLI,
+  journal: AGENT_CLI,
+  stop: AGENT_CLI,
+};
+
+const usage = `Verwendung: ragents <befehl> [argumente]
+
+  run <ordner> "<auftrag>"         Host starten, Run auf dem Ordner anlegen und auf das Ende warten
+  send <run> "<text>"              Folgeauftrag im selben Run
+  journal <run> [--tools]          Verlauf eines Runs lesen
+  stop <run> | stop --host         laufenden Turn abbrechen oder den gemerkten Host beenden
+  connect <server-url>             Client-Profil holen und den lokalen Server damit starten
+  start <profil>                   ein Profil des Pakets oder einen geholten Stand starten
+  provision [<profil>|--workspace] Werkzeuge der Plugins holen
+  workspace-client <server-url>    diesen Rechner als Arbeitsplatz anmelden
+`;
+
+const main = () => {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+  const [command, ...rest] = process.argv.slice(2);
+  const script = command ? commands[command] : undefined;
+  if (!script) {
+    console.error(command ? `Unbekannter Befehl: ${command}\n\n${usage}` : usage);
+    process.exit(1);
+  }
+  ensureHostLinks(root);
+  const passed = script === AGENT_CLI ? [command, ...rest] : rest;
+  const child = spawn(process.execPath, ["--import", "tsx", path.join(root, script), ...passed], {
+    cwd: path.join(root, "apps/server"),
+    env: { ...process.env, RAGENTS_CWD: process.cwd() },
+    stdio: "inherit",
+  });
+  const forward = (signal) => () => child.kill(signal);
+  process.on("SIGINT", forward("SIGINT"));
+  process.on("SIGTERM", forward("SIGTERM"));
+  child.once("error", (error) => {
+    console.error(`ragents ${command} konnte nicht gestartet werden: ${error.message}`);
+    process.exit(1);
+  });
+  child.once("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+};
+
+// npm legt den Befehl als Verknüpfung ab; der Vergleich braucht deshalb den echten Pfad.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/scripts/provision/run-provision.ts

@@ -0,0 +1,72 @@
+import "../../apps/server/src/host-resolution.ts";
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { hostDataDirectory } from "@aicontainer/workspace-executor/src/tools.ts";
+import { loadConfigFile } from "../../apps/server/src/config-file.ts";
+import { resolvePluginEntries } from "../../apps/server/src/profile/plugin-discovery.ts";
+import {
+  provisionPlugins,
+  provisionWorkspace,
+  type PluginProvisionReport,
+} from "../../apps/server/src/profile/provisioning.ts";
+
+const PROFILE_FILE = /^ragents\.config\.([a-z0-9]+(?:-[a-z0-9]+)*)\.ts$/;
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+const usage = (): string => `Verwendung: pnpm provision [<profil>|<pfad zu ragents.config.<profil>.ts>|--workspace]
+Provisioniert die Werkzeuge der Plugins eines Profils nach <Datenordner>/tools/<plugin-id>/ und
+berichtet je Plugin bereit, installiert oder fehlt. --workspace provisioniert stattdessen die
+Sprachserver eines Arbeitsplatzes auf dieser Maschine. Ein relativer Pfad gilt ab der
+Repository-Wurzel; ohne Argument gilt das Profil aus der Umgebung (PRODUCT_PROFILE_FILE oder
+PRODUCT_PROFILE).`;
+
+const availableProfiles = (): readonly string[] => readdirSync(repositoryRoot)
+  .map((name) => PROFILE_FILE.exec(name)?.[1])
+  .filter((name): name is string => name !== undefined && name !== "example")
+  .sort();
+
+export const selectedProfile = (selection: string, root = repositoryRoot): { profile: string; file: string } => {
+  const file = selection.includes("/") || selection.endsWith(".ts")
+    ? path.resolve(root, selection)
+    : path.join(root, `ragents.config.${selection}.ts`);
+  const name = PROFILE_FILE.exec(path.basename(file));
+  if (!name) throw new Error(`Eine Profildatei heißt ragents.config.<profil>.ts: ${selection}`);
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`Konfiguration fehlt: ${file}`);
+  return { profile: name[1]!, file };
+};
+
+const forProfile = async (selection: string): Promise<readonly PluginProvisionReport[]> => {
+  const { profile, file } = selectedProfile(selection);
+  process.env.PRODUCT_PROFILE = profile;
+  process.env.PRODUCT_PROFILE_FILE = file;
+  await loadConfigFile();
+  const { config } = await import("../../apps/server/src/config.ts");
+  console.log(`== Provisionierung Profil ${profile} (${file})`);
+  console.log(`== Werkzeuge unter ${path.join(config.dataDir, "tools")}`);
+  return provisionPlugins(resolvePluginEntries(config.plugins), config.dataDir, (line) => console.log(line));
+};
+
+const forWorkspace = (): Promise<readonly PluginProvisionReport[]> => {
+  console.log("== Provisionierung Arbeitsplatz");
+  console.log(`== Werkzeuge unter ${path.join(hostDataDirectory(), "tools")}`);
+  return provisionWorkspace((line) => console.log(line));
+};
+
+const main = async (): Promise<void> => {
+  const argv = process.argv.slice(2);
+  if (argv.length > 1 || argv.some((argument) => argument.startsWith("-") && argument !== "--workspace")) {
+    throw new Error(`Unerwartete Argumente: ${argv.join(" ")}\n${usage()}`);
+  }
+  const selection = argv[0] ?? process.env.PRODUCT_PROFILE_FILE ?? process.env.PRODUCT_PROFILE;
+  if (!selection) throw new Error(`Kein Profil genannt; im Repository liegen ${availableProfiles().join(", ")}.\n${usage()}`);
+  const reports = selection === "--workspace" ? await forWorkspace() : await forProfile(selection);
+  if (reports.length === 0) console.log("Kein Plugin bringt eine Provisionierung mit.");
+  if (reports.some((report) => report.outcome === "missing")) process.exitCode = 1;
+};
+
+await main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});