@schlenkr/ragents 0.1.5 → 0.1.6

package/apps/server/src/host-api.ts

@@ -0,0 +1,190 @@
+/** The number of the host API a plugin is built against; it changes with every incompatible change of a list, a listed name or a library. */
+export const HOST_API_VERSION = 6;
+
+/** A library the host shares whole, as its installed version exports it; host code instead names each value it offers. */
+export const LIBRARY = "library";
+
+type HostApiModules = Readonly<Record<string, readonly string[] | typeof LIBRARY>>;
+
+/** The modules the host provides to plugins, per half, with the values a plugin may import; nothing else of the host may be imported by a plugin. */
+export const hostApi: { readonly server: HostApiModules; readonly web: HostApiModules } = {
+  server: {
+    "@ragents/engine": [
+      "DomainError", "RPC_ERROR_CODES", "RpcError", "ScriptDriver", "ToolRegistry", "actorByHandle",
+      "actorByReference", "actorDescriptionMaxLength", "actorInputSchema", "agentTools", "assertJsonValue", "builtinProfiles", "canonicalHash",
+      "compileVirtualTypeScriptAsync", "defineRunFunction", "defineToolAvailability", "emptyUsage",
+      "enqueueActorInput", "eventResultSchemaOf", "handleKey", "holdsUsable", "implement", "implementChannel",
+      "isRunId", "isThinkingLevel", "modelToolDescriptors", "pluginStateAt", "runCapabilityBindingHash",
+      "runCapabilityContractHash", "schemaComplaints", "scriptInputOf", "serviceToken",
+    ],
+    "@ragents/engine/src/domain/events": ["eventTypeMap"],
+    "@ragents/engine/src/http/contracts": ["handleKey", "openJson"],
+    "@ragents/engine/src/rpc/contract": ["defineChannel", "defineOperation"],
+    "@ragents/host/access-service": ["profileAccessCookieName"],
+    "@ragents/host/api/reference": ["methodReference", "openRpcDocument"],
+    "@ragents/host/chat-context": [],
+    "@ragents/host/chat-handler": [],
+    "@ragents/host/config": ["hostConfigKeys"],
+    "@ragents/host/config-definition": ["isEnvironmentReference", "isProvisionedReference"],
+    "@ragents/host/config-file": [
+      "SECRET_KEY_PATTERN", "configFilePath", "configuredUsers", "resolveAnonymousUser", "resolveProfileUsers",
+    ],
+    "@ragents/host/host-version": ["readHostApiVersion", "readHostVersion", "readPackageVersion"],
+    "@ragents/host/plugin-support/actor-programs/app-project": [
+      "compileAppBackend", "installServerSdk", "prepareAppProject", "prepareAppWorkspace", "projectSourceFiles",
+      "readAppPackage", "typecheckServerProject",
+    ],
+    "@ragents/host/plugin-support/actor-programs/client-compiler": ["compileClientProject", "installClientSdk"],
+    "@ragents/host/plugin-support/actor-programs/client-contracts": [
+      "readClientUiComponentContracts", "readClientUiComponentNames",
+    ],
+    "@ragents/host/plugin-support/actor-programs/client-runtime": [
+      "FRAME_BODY_CLASS", "FRAME_DOCUMENT_CLASS", "FRAME_ROOT_CLASS", "browserInputRuntime", "browserRuntimeStyles",
+    ],
+    "@ragents/host/plugin-support/actor-programs/contract": [
+      "ACTOR_INVOCATIONS_STATE_ID", "ACTOR_PROGRAMS_STATE_ID", "ACTOR_SCRIPT_STATE_ID", "ACTOR_STATE_ID",
+      "actorProgramContracts", "resolveActorView",
+    ],
+    "@ragents/host/plugin-support/actor-programs/service": ["actorProgramsToken"],
+    "@ragents/host/plugin-support/actor-programs/tailwind": ["buildTailwind"],
+    "@ragents/host/plugin-support/actor-programs/workflow/prompt-reader": ["createPromptReader"],
+    "@ragents/host/plugin-support/agent-tool": ["toolDescriptorFrom"],
+    "@ragents/host/plugin-support/await-with-signal": ["awaitWithSignal"],
+    "@ragents/host/plugin-support/chat-display-policy": [
+      "chatDisplayEnvDescriptors", "chatDisplayPolicyFromEnvironment",
+    ],
+    "@ragents/host/plugin-support/front-matter": ["frontMatterOf"],
+    "@ragents/host/plugin-support/http": [
+      "PayloadTooLargeError", "guardedJsonRoute", "readBody", "readJsonBody", "withAbort", "writeJson",
+    ],
+    "@ragents/host/plugin-support/language-server/plugin": ["createLanguageServerPlugin"],
+    "@ragents/host/plugin-support/model-aliases": ["configuredModelAliases", "modelLabel"],
+    "@ragents/host/plugin-support/model-choice": [
+      "builtinCatalog", "modelChoiceEnvDescriptors", "modelChoiceFromEnvironment", "modelThinkingOptions",
+    ],
+    "@ragents/host/plugin-support/model-completion": ["openRouterCompletionModel"],
+    "@ragents/host/plugin-support/model-upstreams": ["modelUpstreamsToken"],
+    "@ragents/host/plugin-support/plugin-config": ["declaredEnvironment"],
+    "@ragents/host/plugin-support/plugin-folder": ["folderSystemPrompts", "pluginAsset", "pluginFolder"],
+    "@ragents/host/plugin-support/plugin-module": [],
+    "@ragents/host/plugin-support/plugins-root": ["bundlesRoot", "isPluginPath"],
+    "@ragents/host/plugin-support/process-sandbox": ["PROCESS_SANDBOX_DEFAULT_NETWORK", "ServerProcessSandbox"],
+    "@ragents/host/plugin-support/product-model-settings": ["ProductModelSettingsStore", "productModelSettingsMethods"],
+    "@ragents/host/plugin-support/product-relay": ["RELAY_PROVIDER", "createRelayCatalog"],
+    "@ragents/host/plugin-support/product-start-options": ["productStartOptions"],
+    "@ragents/host/plugin-support/prompt": ["boundToTools", "handlebarsPrompt", "systemPromptSelectionPrompt"],
+    "@ragents/host/plugin-support/provision": [
+      "DOTNET_INSTRUCTION", "dotnetRuntimeMajors", "downloadArchive", "hostPackageFolder", "provisionGap",
+      "provisionReady", "readProvisionStamp", "readZipNames", "unpackArchive", "writeProvisionStamp",
+    ],
+    "@ragents/host/plugin-support/skills": ["skillEnvDescriptors", "skillsFromEnvironment"],
+    "@ragents/host/plugin-support/system-prompts": ["lazySystemPromptCatalog", "systemPromptEnvDescriptors"],
+    "@ragents/host/plugin-support/thinking-level": ["checkedThinkingLevel", "roleThinkingLevel"],
+    "@ragents/host/plugin-support/tool-availability": ["alwaysAvailable", "facesOperator"],
+    "@ragents/host/plugin-support/workspace-ownership": ["syncWorkspaceOwnership"],
+    "@ragents/host/plugin-support/workspace-sandbox-host": [
+      "WorkspaceSandboxHost", "sandboxServicesToken", "withDomainCause",
+    ],
+    "@ragents/host/profile/plugin-discovery": ["discoverPluginIds", "resolvePluginEntries"],
+    "@ragents/host/protocol": ["Protocol"],
+    "@ragents/host/ragents/document-store": ["documentStoreToken"],
+    "@ragents/host/ragents/global-chat": ["globalChatToken", "runManagementToken"],
+    "@ragents/host/ragents/host-services": [
+      "hostAddressToken", "runtimeProviderToken", "secretEnvNamesToken", "runGuardToken", "runWorkspaceProviderToken", "workspaceGuardToken",
+    ],
+    "@ragents/host/ragents/product-runtime": ["productRuntimeToken"],
+    "@ragents/host/ragents/runtime-bridge": ["runtimeBridgeToken"],
+    "@ragents/host/ragents/start-option-state": ["startOptionScope", "storedStartOption"],
+    "@ragents/host/ragents/workspace-runtime": [
+      "gitWorkspaceViewToken", "workspaceResolverToken", "workspaceRuntimeToken",
+    ],
+    "@ragents/workflow": ["defineWorkflow", "workflowInstructions"],
+    "@ragents/workspace-executor": [
+      "BROWSER_EXECUTABLE_VARIABLE", "BROWSER_OPERATIONS", "COMMAND_OPERATIONS", "FILE_OPERATIONS",
+      "FSHARP_SERVER_FILE", "FSHARP_SERVER_VARIABLE", "PROCESS_OPERATIONS", "ROSLYN_SERVER_FILE",
+      "ROSLYN_SERVER_VARIABLE", "RUN_FOLDER_OPERATIONS", "RUN_MARKER_ENV", "WORKSPACE_EXECUTOR_VERSION", "fsharpAdapter",
+      "languageServerOpenOperation", "languageServerSolutionsOperation", "listDirectory", "readTextFile", "roslynAdapter", "runManagedProcess", "safeProcessEnvironment", "sandboxRunEnvironment", "sandboxedLaunch",
+      "shellPlatformText", "startManagedService", "typescriptAdapter", "watchDirectory",
+    ],
+    "@ragents/workspace-executor/src/git-config-environment": ["withGitConfigPairs"],
+    "@ragents/workspace-executor/src/managed-process": ["ProcessGroupJoinError"],
+    "@ragents/workspace-executor/src/session-ident": ["stopUidProcesses"],
+    "handlebars": LIBRARY,
+    "playwright-core": LIBRARY,
+    "tar": LIBRARY,
+    "typebox": LIBRARY,
+    "typebox/value": LIBRARY,
+  },
+  web: {
+    "@ragents/engine/src/domain/events": ["eventTypeMap"],
+    "@ragents/engine/src/domain/json": [],
+    "@ragents/engine/src/http/contracts": ["actorByHandle", "handleKey", "openJson", "runContracts"],
+    "@ragents/engine/src/rpc/contract": ["defineChannel", "defineOperation"],
+    "@ragents/host/plugin-support/actor-programs/contract": [
+      "ACTOR_INVOCATIONS_STATE_ID", "ACTOR_PROGRAMS_STATE_ID", "ACTOR_STATE_ID", "actorProgramContracts",
+    ],
+    "@ragents/web/AccessContext": ["useAccess"],
+    "@ragents/web/DiffCode": ["DiffCode"],
+    "@ragents/web/PluginRegistry": [
+      "SurfaceControllerProvider", "ChatStepsProvider", "chatDisplayPolicyFrom", "pluginRoutePrefixFrom",
+      "useActionRenderer", "useSurfaceController", "useChatSteps", "useToolRenderer", "workspaceAccessible",
+    ],
+    "@ragents/web/SourceCode": ["SourceCode"],
+    "@ragents/web/StatusGroup": ["StatusGroup"],
+    "@ragents/web/Toolbar": ["ToolbarCopy", "ToolbarItem", "ToolbarLabel", "ToolbarText"],
+    "@ragents/web/access-token": ["withAccessToken"],
+    "@ragents/web/actor-conversation": ["actorChatMessages", "actorInputLabel"],
+    "@ragents/web/actor-programs/client-ui/contracts": [],
+    "@ragents/web/api": ["interruptActorTurn", "sendActorMessage"],
+    "@ragents/web/chat-view-settings": ["ChatViewSwitches", "useChatViewSettings"],
+    "@ragents/web/chat/StoppedActorNotice": ["StoppedActorNotice"],
+    "@ragents/web/chat/chat-target": ["programChatNotice", "runIsWorking"],
+    "@ragents/web/chat/useAttachmentCapabilities": ["getAttachmentCapabilities", "useAttachmentCapabilities"],
+    "@ragents/web/chat/useChat": ["useChat"],
+    "@ragents/web/language-server/language-server-plugin": ["languageServerWebPlugin"],
+    "@ragents/web/lib/format": ["formatBytes"],
+    "@ragents/web/lib/guards": ["hasExactKeys", "isRecord"],
+    "@ragents/web/lib/http": ["errorFrom"],
+    "@ragents/web/lib/labels": ["thinkingLabel"],
+    "@ragents/web/lib/local-storage-setting": ["createLocalStorageSetting"],
+    "@ragents/web/page-opener": ["useOptionalPageOpener"],
+    "@ragents/web/product/ProductModelSettings": ["ProductModelSettings"],
+    "@ragents/web/product/start-options": ["productStartOptions"],
+    "@ragents/web/rpc": ["rpc"],
+    "@ragents/web/run-panel/input-bridge": ["hostInputEnabled", "isRunPanelKeyboardMessage", "relayFrameInput"],
+    "@ragents/web/run-panel/host": ["useCenterElements", "useRunPanelHost"],
+    "@ragents/web/run-view": [
+      "actorPluginState", "actorTone", "chatPrimaryId", "isPendingRunActorInput", "runActorFrom",
+      "runArtifactContentUrl", "runViewFrom",
+    ],
+    "@ragents/web/theme": ["useResolvedTheme"],
+    "@ragents/web/toolLine": ["withToolSummaries"],
+    "@ragents/web/ui": [
+      "Alert", "AlertDescription", "AlertTitle", "Badge", "Button", "Card", "Dialog", "DialogBody", "DialogContent",
+      "DialogDescription", "DialogFooter", "DialogHeader", "DialogTitle", "Empty", "EmptyContent", "EmptyDescription",
+      "EmptyHeader", "EmptyMedia", "EmptyTitle", "Field", "FieldDescription", "FieldTitle", "Input", "Label",
+      "Popover", "PopoverContent", "SectionLabel", "Select", "SelectContent", "SelectItem", "SelectTrigger",
+      "SelectValue", "Spinner", "StartupNotice", "StopButton", "StopGlyph", "Switch", "Tabs", "TabsContent",
+      "TabsList", "TabsTrigger", "Textarea", "Toggle", "ToggleGroup", "ToggleGroupItem", "buttonVariants", "cn",
+    ],
+    "@ragents/web/ui/dialog": ["RunModalContext"],
+    "quassel": LIBRARY,
+    "react": LIBRARY,
+    "react-dom": LIBRARY,
+    "react/jsx-runtime": LIBRARY,
+    "typebox": LIBRARY,
+  },
+};
+
+/** The global under which the host web keeps its register of the web modules; plugin bundles read them from there. */
+export const HOST_MODULES_GLOBAL = "__ragentsHostModules";
+
+export type HostApiHalf = keyof typeof hostApi;
+
+export const hostApiModules = (half: HostApiHalf): readonly string[] => Object.keys(hostApi[half]);
+
+/** Host code and libraries whose module state, context or class identity the host shares; a plugin never carries its own copy. */
+export const hostOnly = (specifier: string): boolean => /^(react|react-dom)(\/|$)|^@ragents\/(?!plugins\/)/.test(specifier);
+
+export const providedByHost = (half: HostApiHalf, specifier: string): boolean =>
+  Object.hasOwn(hostApi[half], specifier.replace(/\.(js|ts|tsx)$/, ""));

package/apps/server/src/host-resolution-hooks.mjs

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import { isBuiltin } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -6,19 +8,66 @@ const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url))
 const hostEntries = ["apps/server/src/main.ts", "apps/web/src/main.tsx"]
   .map((entry) => pathToFileURL(path.join(repositoryRoot, entry)).href);
 
+const serverEntry = hostEntries[0];
+
+const workflowEntry = pathToFileURL(path.join(repositoryRoot, "apps/server/src/plugin-support/actor-programs/workflow/index.ts")).href;
+
+const bundles = new Map();
+let serverModules = new Set();
+
+export const initialize = ({ port, serverModules: modules }) => {
+  serverModules = new Set(modules);
+  port.on("message", ({ id, bundles: announced }) => {
+    for (const [bundleId, folder] of announced) bundles.set(bundleId, pathToFileURL(`${folder}${path.sep}`).href);
+    port.postMessage({ acknowledged: id });
+  });
+  port.unref();
+};
+
 const isBareSpecifier = (specifier) => !/^(\.{1,2}\/|\/|[a-z][a-z0-9+.-]*:)/i.test(specifier);
 
 const isResolutionFailure = (error) =>
   typeof error === "object" && error !== null
   && ["ERR_MODULE_NOT_FOUND", "ERR_PACKAGE_PATH_NOT_EXPORTED"].includes(String(error.code));
 
+const bundleOf = (url) => {
+  if (!url) return undefined;
+  for (const [id, folder] of bundles) if (url.startsWith(folder)) return id;
+  return undefined;
+};
+
+/** A bundle gets from the host only what the server list names, and from other bundles only their exports. */
+const resolveFromBundle = async (bundle, specifier, context, next) => {
+  if (!isBareSpecifier(specifier) || isBuiltin(specifier)) return next(specifier, context);
+  const cross = /^@ragents\/plugins\/([^/]+)\/(.+)$/.exec(specifier);
+  if (cross) {
+    const [, owner, name] = cross;
+    const folder = bundles.get(owner);
+    if (!folder) throw new Error(`Das Bundle ${bundle} importiert ${specifier}, aber ${owner} steht nicht in der Pluginliste`);
+    const url = new URL(`server/exports/${name.replace(/\.js$/, "")}.js`, folder).href;
+    if (!existsSync(fileURLToPath(url))) throw new Error(`Das Bundle ${bundle} importiert ${specifier}, das Bundle ${owner} exportiert ${name} aber nicht für den Server; beide Bundles aus ihren Quellen neu bauen`);
+    return { url, shortCircuit: true };
+  }
+  const listed = specifier.replace(/\.(js|ts|tsx)$/, "");
+  if (listed === "@ragents/workflow") return { url: workflowEntry, shortCircuit: true };
+  if (!serverModules.has(listed)) throw new Error(`Das Bundle ${bundle} importiert ${specifier}, das der Host nicht bereitstellt; das Bundle gegen diesen Host neu bauen`);
+  return next(specifier, { ...context, parentURL: serverEntry });
+};
+
+/** Bundle code is always ESM, also where no package.json says so. */
+export const load = async (url, context, next) =>
+  bundleOf(url) !== undefined && url.endsWith(".js") ? next(url, { ...context, format: "module" }) : next(url, context);
+
 // Reines JavaScript, weil Node diese Datei im Loader-Thread lädt und dort unter node_modules keine Typen entfernt.
-/** Bare imports of files outside the repository resolve through the host, so plugins need no own node_modules. */
+/** Bundles resolve strictly; other code outside the repository resolves bare imports through the host, so it needs no own node_modules. */
 export const resolve = async (specifier, context, next) => {
+  const bundle = bundleOf(context.parentURL);
+  if (bundle !== undefined) return resolveFromBundle(bundle, specifier, context, next);
   try {
     return await next(specifier, context);
   } catch (error) {
     if (!isBareSpecifier(specifier) || !isResolutionFailure(error) || hostEntries.includes(context.parentURL ?? "")) throw error;
+    if (specifier === "@ragents/workflow") return { url: workflowEntry, shortCircuit: true };
     for (const [index, parentURL] of hostEntries.entries()) {
       try {
         return await next(specifier, { ...context, parentURL });

package/apps/server/src/host-resolution.ts

@@ -1,3 +1,28 @@
 import { register } from "node:module";
+import { MessageChannel } from "node:worker_threads";
+import { hostApiModules } from "./host-api.js";
 
-register("./host-resolution-hooks.mjs", import.meta.url);
+const channel = new MessageChannel();
+register("./host-resolution-hooks.mjs", {
+  parentURL: import.meta.url,
+  data: { port: channel.port2, serverModules: hostApiModules("server") },
+  transferList: [channel.port2],
+});
+channel.port1.unref();
+
+let announcement = 0;
+
+/** Tells the loader thread which bundle folder (real path) belongs to which id; resolves once it knows. */
+export const announceBundles = (bundles: ReadonlyMap<string, string>): Promise<void> => new Promise((resolve) => {
+  announcement += 1;
+  const id = announcement;
+  const acknowledged = (message: { readonly acknowledged?: number }): void => {
+    if (message.acknowledged !== id) return;
+    channel.port1.off("message", acknowledged);
+    channel.port1.unref();
+    resolve();
+  };
+  channel.port1.on("message", acknowledged);
+  channel.port1.ref();
+  channel.port1.postMessage({ id, bundles: [...bundles] });
+});

package/apps/server/src/host-version.ts

@@ -1,9 +1,50 @@
 import { readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { HOST_API_VERSION, hostApiModules } from "./host-api.js";
 
 export const hostRoot = (): string => path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
 
+/** The value names of the host API and its number, relative to the host root; generated by pnpm update:host-api. */
+export const HOST_API_RECORD_FILE = "apps/server/src/host-api.json";
+
+/** Die Nummer der Host-API eines Hosts an beliebiger Stelle; so prüft auch die Erweiterung einen Host, der nicht sie selbst ist. */
+export const readHostApiVersion = (root: string = hostRoot()): number => {
+  const file = path.join(root, HOST_API_RECORD_FILE);
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`Die Host-API ist unbekannt: ${file} fehlt`);
+  const version = (JSON.parse(readFileSync(file, "utf8")) as { version?: unknown }).version;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) throw new Error(`${file}: version ist keine Nummer der Host-API`);
+  return version;
+};
+
+/** The value names each module of the host API offers at runtime, per half; the build tool generates the web shims from it. */
+export interface HostApiRecord {
+  readonly version: number;
+  readonly server: Readonly<Record<string, readonly string[]>>;
+  readonly web: Readonly<Record<string, readonly string[]>>;
+}
+
+export const readHostApiRecord = (root = hostRoot()): HostApiRecord => {
+  const file = path.join(root, HOST_API_RECORD_FILE);
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`${file} fehlt; mit pnpm update:host-api erzeugen`);
+  return JSON.parse(readFileSync(file, "utf8")) as HostApiRecord;
+};
+
+/** The stored names must describe the current list and number; building and loading both read them, so both agree with the constant. */
+export const checkedHostApiRecord = (root = hostRoot()): HostApiRecord => {
+  const record = readHostApiRecord(root);
+  if (record.version !== HOST_API_VERSION) {
+    throw new Error(`host-api.json beschreibt Host-API ${record.version}, der Host bietet ${HOST_API_VERSION}; pnpm update:host-api`);
+  }
+  for (const half of ["server", "web"] as const) {
+    const listed = [...hostApiModules(half)].sort().join("\n");
+    if (Object.keys(record[half]).sort().join("\n") !== listed) {
+      throw new Error(`host-api.json nennt für die ${half}-Hälfte andere Module als apps/server/src/host-api.ts; pnpm update:host-api`);
+    }
+  }
+  return record;
+};
+
 export interface HostPackage {
   readonly name: string;
   readonly version: string;

package/apps/server/src/host-web.ts

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { hostRoot } from "./host-version.js";
+
+/** The file in the built web that names every source file the build read, each with its hash. */
+export const HOST_WEB_RECORD = "host-web.json";
+
+const HOST_WEB_PAGES = ["index.html", "run-panel.html"] as const;
+
+export interface HostWebRecord {
+  readonly inputs: Readonly<Record<string, string>>;
+}
+
+/** The built web of the host: one for every profile, built with the host by pnpm build:web. */
+export const hostWebDirectory = (root = hostRoot()): string => path.join(root, "apps/web/dist");
+
+/** Only a checkout has a git folder; there the sources of the built web and of the built-in bundles can change. */
+export const isCheckout = (root = hostRoot()): boolean => existsSync(path.join(root, ".git"));
+
+const fileHash = (file: string): string => createHash("sha256").update(readFileSync(file)).digest("hex");
+
+const isFile = (file: string): boolean => statSync(file, { throwIfNoEntry: false })?.isFile() === true;
+
+/** Records the source files a web build read, relative to the host root. */
+export const hostWebRecordOf = (root: string, files: readonly string[]): HostWebRecord => ({
+  inputs: Object.fromEntries([...new Set(files)]
+    .map((file) => [path.relative(root, file).split(path.sep).join("/"), fileHash(file)] as const)
+    .sort(([left], [right]) => left.localeCompare(right, "en"))),
+});
+
+const changedInputs = (record: HostWebRecord, root: string): readonly string[] =>
+  Object.entries(record.inputs)
+    .filter(([name, hash]) => !isFile(path.join(root, name)) || fileHash(path.join(root, name)) !== hash)
+    .map(([name]) => name);
+
+const readRecord = (file: string): HostWebRecord | undefined => {
+  if (!isFile(file)) return undefined;
+  const raw = JSON.parse(readFileSync(file, "utf8")) as { inputs?: unknown };
+  const inputs = raw.inputs;
+  if (typeof inputs !== "object" || inputs === null || Array.isArray(inputs)
+    || Object.values(inputs).some((hash) => typeof hash !== "string")) {
+    throw new Error(`${file} hat nicht die erwartete Form`);
+  }
+  return { inputs: inputs as Record<string, string> };
+};
+
+/** Why a built web cannot be served as it is; with sources, a checkout also compares it with the files it was built from. */
+export const hostWebProblem = (directory: string, root: string, sources: boolean): string | undefined => {
+  const missing = HOST_WEB_PAGES.filter((page) => !isFile(path.join(directory, page)));
+  if (missing.length > 0) return `Das Web des Hosts fehlt unter ${directory} (${missing.join(", ")})`;
+  if (!sources) return undefined;
+  const record = readRecord(path.join(directory, HOST_WEB_RECORD));
+  if (!record) return `Das Web des Hosts unter ${directory} hat keinen Quellstand (${HOST_WEB_RECORD})`;
+  const changed = changedInputs(record, root);
+  if (changed.length === 0) return undefined;
+  const shown = changed.slice(0, 5).join(", ") + (changed.length > 5 ? ` und ${changed.length - 5} weitere` : "");
+  return `Das Web des Hosts unter ${directory} passt nicht mehr zu seinen Quellen (geändert: ${shown})`;
+};

package/apps/server/src/layout.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { isPortableId } from "@aicontainer/ragents";
+import { isPortableId } from "@ragents/engine";
 import { config } from "./config.js";
 
 const portableId = (value: string, name: string) => {

package/apps/server/src/main.ts

@@ -1,10 +1,11 @@
 import "./host-resolution.js";
-import { configuredAnonymousUser, configuredUsers, loadConfigFile } from "./config-file.js";
+import { configuredAnonymousUser, configuredUsers, loadConfigFile, missingEnvironmentOf, reportMissingEnvironment } from "./config-file.js";
 
 const startupFailure = (error: unknown): never => {
   const message = error instanceof Error ? error.message : String(error);
-  if (error instanceof Error && error.constructor !== Error) console.error(error.stack ?? message);
+  if (error instanceof Error && error.constructor !== Error && missingEnvironmentOf(error) === undefined) console.error(error.stack ?? message);
   console.error(`\nRAgents startet nicht: ${message}`);
+  reportMissingEnvironment(error, (line) => console.error(line));
   process.exit(1);
 };
 

package/apps/server/src/missing-environment.ts

@@ -0,0 +1,47 @@
+/** Eine Konfiguration nennt env("NAME") für eine Umgebungsvariable, die der Prozess nicht hat; dazu, wofür sie gebraucht wird. */
+export interface MissingEnvironment {
+  readonly variable: string;
+  readonly section: string;
+  readonly key: string;
+}
+
+/** Derselbe Fehler wie bisher, nur trägt er den Namen mit, statt ihn im Satz zu verstecken. */
+export class MissingEnvironmentError extends Error {
+  constructor(readonly missing: MissingEnvironment, message: string) {
+    super(message);
+  }
+}
+
+const NOTICE = "ragents:missing-environment ";
+
+const ENVIRONMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const asMissingEnvironment = (value: unknown): MissingEnvironment | undefined => {
+  const missing = value as Partial<MissingEnvironment> | null | undefined;
+  if (!missing || typeof missing.variable !== "string" || typeof missing.section !== "string" || typeof missing.key !== "string") return undefined;
+  if (!ENVIRONMENT_NAME.test(missing.variable)) return undefined;
+  return { variable: missing.variable, section: missing.section, key: missing.key };
+};
+
+/** Der Befund an einem Fehler; geprüft wird sein Inhalt, nicht seine Klasse, denn er kommt auch aus einem anderen Modul. */
+export const missingEnvironmentOf = (error: unknown): MissingEnvironment | undefined =>
+  asMissingEnvironment((error as { missing?: unknown } | null | undefined)?.missing);
+
+/** Die Zeile, mit der ein Kindprozess den Befund an den weitergibt, der ihn gestartet hat; sein Text bleibt daneben stehen. */
+export const missingEnvironmentNotice = (missing: MissingEnvironment): string => NOTICE + JSON.stringify(missing);
+
+/** Der Befund aus einer Ausgabezeile; alles andere ist keiner. */
+export const parseMissingEnvironmentNotice = (line: string): MissingEnvironment | undefined => {
+  if (!line.startsWith(NOTICE)) return undefined;
+  try {
+    return asMissingEnvironment(JSON.parse(line.slice(NOTICE.length)));
+  } catch {
+    return undefined;
+  }
+};
+
+/** Was ein Prozess zusätzlich ausgibt, wenn er an einer fehlenden Umgebungsvariablen scheitert. */
+export const reportMissingEnvironment = (error: unknown, write: (line: string) => void): void => {
+  const missing = missingEnvironmentOf(error);
+  if (missing) write(missingEnvironmentNotice(missing));
+};

package/apps/server/src/parent-watch.ts

@@ -0,0 +1,37 @@
+const CHECK_INTERVAL_MS = 5_000;
+
+export interface ParentWatch {
+  readonly parentPid: string | undefined;
+  readonly onGone: (pid: number) => void;
+  /** Nur für Tests: die Lebendprüfung und der Takt des Wächters. */
+  readonly alive?: (pid: number) => boolean;
+  readonly intervalMs?: number;
+}
+
+/** Lebt der Prozess noch? ESRCH heißt weg, EPERM heißt lebendig unter fremdem Besitzer. */
+export const processAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+/** Beendet den Host, sobald der Prozess aus RAGENTS_PARENT_PID verschwindet; ohne die Variable gibt es keinen Wächter. */
+export const watchParentProcess = (watch: ParentWatch): (() => void) | undefined => {
+  const given = watch.parentPid;
+  if (given === undefined) return undefined;
+  if (!/^\d+$/.test(given) || !Number.isSafeInteger(Number(given)) || Number(given) <= 0) {
+    throw new Error(`RAGENTS_PARENT_PID nennt die Prozesskennung des Aufrufers; ${JSON.stringify(given)} ist keine positive ganze Zahl.`);
+  }
+  const pid = Number(given);
+  const alive = watch.alive ?? processAlive;
+  const timer = setInterval(() => {
+    if (alive(pid)) return;
+    clearInterval(timer);
+    watch.onGone(pid);
+  }, watch.intervalMs ?? CHECK_INTERVAL_MS);
+  timer.unref();
+  return () => clearInterval(timer);
+};