@schlenkr/ragents 0.1.0

package/apps/server/src/chat-events.ts

@@ -0,0 +1,185 @@
+export type Role = "user" | "assistant" | "thinking" | "tool" | "system" | "question";
+
+export interface ChatAttachmentInput {
+  name: string;
+  mediaType: string;
+  data: string;
+}
+
+export interface ChatAttachment {
+  name: string;
+  mediaType: string;
+  size: number;
+  url: string;
+}
+
+export interface ChatAttachmentCapabilities {
+  input: readonly string[];
+  model: string;
+}
+
+export interface ToolInfo {
+  id: string;
+  name: string;
+  arguments: string;
+  result?: string;
+  isError?: boolean;
+}
+
+export interface ChatTextCursor {
+  conversationId: string;
+  sequence: number;
+  /** Accumulated non-whitespace UTF-16 units in the turn anchored by sequence. */
+  offset: number;
+}
+
+export interface ChatJournalCursor {
+  conversationId: string;
+  eventId: string;
+  sequence: number;
+}
+
+/** Eine Rückfrage des Assistenten. `answer` gesetzt heißt: beantwortet, die Karte ist nur noch Beleg. */
+export interface Question {
+  callId: string;
+  options: string[];
+  multi?: boolean;
+  answer?: string;
+}
+
+export interface Message {
+  key: string;
+  role: Role;
+  /** Absenderkennung für die Darstellung; unabhängig von Rolle und Sprechblasenlabel. */
+  sender?: string;
+  text: string;
+  textCursor?: ChatTextCursor;
+  closed?: boolean;
+  attachments?: ChatAttachment[];
+  tool?: ToolInfo;
+  question?: Question;
+  /** ISO-Zeitpunkt der Nachricht; Anzeige optional (ChatMessages showTimestamps). */
+  at?: string;
+  /** Farbige Sprechblase statt Fliesstext, z.B. fuer Mehrparteien-Gespraeche. */
+  bubble?: { color: string; side: "start" | "end"; label?: string };
+}
+
+export interface ChatStartupStatus {
+  status: "preparing" | "failed";
+  message: string;
+}
+
+export type ChatEvent =
+  | { kind: "reset"; reason?: "conversation-reset"; conversationId: string | null }
+  | { kind: "replay-end"; conversationId: string | null }
+  | { kind: "user"; text: string; at?: string; attachments?: ChatAttachment[] }
+  | { kind: "text"; delta: string; at?: string; cursor: ChatTextCursor }
+  | { kind: "thinking"; delta: string; at?: string }
+  | { kind: "tool"; id: string; name: string; arguments: string; label?: string; at?: string }
+  | { kind: "tool-result"; id: string; result: string; isError?: boolean }
+  | { kind: "question"; callId: string; text: string; options: string[]; multi?: boolean; at?: string }
+  | { kind: "question-answered"; callId: string; answer: string }
+  | { kind: "system"; text: string; at?: string }
+  | { kind: "status"; running: boolean; startup?: ChatStartupStatus }
+  | { kind: "turn-done" }
+  | { kind: "extension"; pluginId: string; type: string; payload?: unknown; at?: string; journal?: ChatJournalCursor };
+
+function openMessageIndex(messages: Message[]): number {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (!message.closed && (message.role === "assistant" || message.role === "thinking")) return index;
+  }
+  return -1;
+}
+
+function closeOpen(messages: Message[]): Message[] {
+  const index = openMessageIndex(messages);
+  if (index === -1) {
+    return messages;
+  }
+  return messages.map((message, position) => position === index ? { ...message, closed: true } : message);
+}
+
+function appendDelta(messages: Message[], role: Role, delta: string, at?: string, textCursor?: ChatTextCursor): Message[] {
+  const index = openMessageIndex(messages);
+  const current = messages[index];
+  if (current && current.role === role
+    && current.textCursor?.conversationId === textCursor?.conversationId
+    && current.textCursor?.sequence === textCursor?.sequence) {
+    return messages.map((message, position) => position === index
+      ? { ...message, text: message.text + delta, ...(textCursor ? { textCursor } : {}) }
+      : message);
+  }
+  return [...closeOpen(messages), { key: crypto.randomUUID(), role, text: delta, at, ...(textCursor ? { textCursor } : {}) }];
+}
+
+/** Eingehende Nachrichten lassen den laufenden Ausgabeblock offen. */
+export function applyEvent(messages: Message[], event: ChatEvent): Message[] {
+  switch (event.kind) {
+    case "reset":
+      return [];
+    case "user":
+      return [...messages, { key: crypto.randomUUID(), role: "user", text: event.text, closed: true, at: event.at,
+        ...(event.attachments?.length ? { attachments: event.attachments } : {}) }];
+    case "text":
+      return appendDelta(messages, "assistant", event.delta, event.at, event.cursor);
+    case "thinking":
+      return appendDelta(messages, "thinking", event.delta, event.at);
+    case "tool":
+      return [
+        ...closeOpen(messages),
+        {
+          key: crypto.randomUUID(),
+          role: "tool",
+          text: event.label ?? event.name,
+          closed: true,
+          tool: { id: event.id, name: event.name, arguments: event.arguments },
+          at: event.at,
+        },
+      ];
+    case "tool-result":
+      return messages.map((message) =>
+        message.tool?.id === event.id
+          ? { ...message, tool: { ...message.tool, result: event.result, isError: event.isError } }
+          : message,
+      );
+    case "question":
+      return [
+        ...closeOpen(messages),
+        {
+          key: crypto.randomUUID(),
+          role: "question",
+          text: event.text,
+          closed: true,
+          question: { callId: event.callId, options: event.options, multi: event.multi },
+          at: event.at,
+        },
+      ];
+    case "question-answered":
+      return messages.map((message) =>
+        message.question?.callId === event.callId
+          ? { ...message, question: { ...message.question, answer: event.answer } }
+          : message,
+      );
+    case "system":
+      return [...closeOpen(messages), { key: crypto.randomUUID(), role: "system", text: event.text, closed: true, at: event.at }];
+    case "turn-done":
+      return closeOpen(messages);
+    default:
+      return messages;
+  }
+}
+
+export function prettyJson(value: string): string {
+  try {
+    return JSON.stringify(JSON.parse(value), null, 2);
+  } catch {
+    return value;
+  }
+}
+
+export function compactToolLine(tool: ToolInfo): string {
+  const args = tool.arguments.replace(/\s+/g, " ").trim();
+  const line = args && args !== "{}" ? `${tool.name} ${args}` : tool.name;
+  return line.length > 160 ? `${line.slice(0, 160)} ...` : line;
+}

package/apps/server/src/chat-handler.ts

@@ -0,0 +1,37 @@
+/** Die Verträge der Unterhaltungen, gegen die Kernmethoden und Auslieferung arbeiten. */
+import type { ChatAttachment, ChatAttachmentInput, ChatEvent } from "./chat-events.js";
+import type { ActorConversations } from "./ragents/actor-chat-history.js";
+
+export interface SessionInfo {
+  id: string;
+  title: string;
+  createdAt?: number;
+  updatedAt: number;
+  revision?: number;
+}
+
+export interface ChatUser {
+  id: string;
+  label: string;
+}
+
+/** Was der HTTP-Adapter von einer Unterhaltung braucht. */
+export interface ChatSessionLike {
+  readonly running: boolean;
+  subscribe(listener: (event: ChatEvent) => void): () => void;
+  send(text: string, attachments?: ChatAttachmentInput[], userLocation?: unknown, user?: ChatUser): void | Promise<void>;
+  sendToActor?(actorId: string, text: string, attachments?: ChatAttachmentInput[]): Promise<void>;
+  actorConversations?(): ActorConversations;
+  capabilities?(actor?: string): Promise<{ input: string[]; model: string }>;
+  attachment?(artifactId: string): { attachment: ChatAttachment; content: Uint8Array };
+  start(entryId: string, input: unknown, user?: ChatUser): void;
+  stop(): void | Promise<void>;
+}
+
+export interface ChatSessionProvider {
+  get(id: string): Promise<ChatSessionLike>;
+  hasRun?(id: string): boolean;
+  list(): Promise<SessionInfo[]>;
+  subscribeList?(listener: () => void): () => void;
+  delete(id: string): Promise<void>;
+}

package/apps/server/src/config-definition.ts

@@ -0,0 +1,80 @@
+import type { hostConfigDescriptors } from "./config.js";
+
+export interface EnvironmentReference {
+  readonly kind: "environment";
+  readonly name: string;
+}
+
+const ENVIRONMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export const env = (name: string): EnvironmentReference => {
+  if (!ENVIRONMENT_NAME.test(name)) {
+    throw new Error(`env("${name}") nennt keinen gültigen Namen einer Umgebungsvariablen`);
+  }
+  return { kind: "environment", name };
+};
+
+export const isEnvironmentReference = (value: unknown): value is EnvironmentReference =>
+  typeof value === "object" && value !== null && (value as EnvironmentReference).kind === "environment";
+
+export interface ProvisionedReference {
+  readonly kind: "provisioned";
+  readonly plugin: string;
+  readonly path: string;
+}
+
+const PLUGIN_ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+/** Eine Datei im Werkzeugordner eines Plugins; beim Laden der Profildatei wird daraus ein absoluter Pfad. */
+export const provisioned = (plugin: string, file: string): ProvisionedReference => {
+  if (!PLUGIN_ID.test(plugin)) {
+    throw new Error(`provisioned("${plugin}", ...) nennt keine gültige Plugin-Kennung`);
+  }
+  if (!file || file.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error(`provisioned("${plugin}", "${file}") braucht einen relativen Pfad im Werkzeugordner`);
+  }
+  return { kind: "provisioned", plugin, path: file };
+};
+
+export const isProvisionedReference = (value: unknown): value is ProvisionedReference =>
+  typeof value === "object" && value !== null && (value as ProvisionedReference).kind === "provisioned";
+
+export interface ProfileAnonymousUser {
+  readonly id: string;
+  readonly label?: string;
+  readonly rights: readonly string[];
+  readonly startEntries?: readonly string[];
+}
+
+export interface ProfileUser extends ProfileAnonymousUser {
+  readonly password: string | EnvironmentReference;
+  /** Dauerhafter Bearer-Token für Clients ohne Anmeldedialog; nur als env(...), nie im Klartext. */
+  readonly token?: EnvironmentReference;
+}
+
+export type ConfigValue = string | number | boolean | readonly string[] | EnvironmentReference | ProvisionedReference;
+
+type Descriptors = readonly { readonly key: string }[];
+
+type SecretKeyOf<T extends Descriptors> = T[number] extends infer Descriptor
+  ? Descriptor extends { readonly secret: true; readonly key: infer Key } ? Key : never
+  : never;
+
+type Section<T extends Descriptors> = {
+  readonly [Key in T[number]["key"]]?: Key extends SecretKeyOf<T> ? EnvironmentReference : ConfigValue;
+};
+
+// Der Kern kennt keine Plugin-IDs: welche Sektion und welcher Schlüssel gültig ist, entscheidet die
+// Laufzeitprüfung gegen die Deklarationen der geladenen Plugins.
+export type PluginSection = {
+  readonly [key: `${string}_PAT`]: EnvironmentReference | undefined;
+  readonly [key: `${string}_KEY`]: EnvironmentReference | undefined;
+  readonly [key: `${string}_TOKEN`]: EnvironmentReference | undefined;
+  readonly [key: `${string}_SECRET`]: EnvironmentReference | undefined;
+  readonly [key: `${string}_PASSWORD`]: EnvironmentReference | undefined;
+  readonly [key: string]: ConfigValue | undefined;
+};
+
+export type RAgentsConfig =
+  & { readonly host?: Section<typeof hostConfigDescriptors> }
+  & { readonly [pluginId: string]: PluginSection | undefined };

package/apps/server/src/config-file.ts

@@ -0,0 +1,324 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { pluginToolsDirectory } from "@aicontainer/workspace-executor/src/tools.ts";
+import { isAccessRight, type AccessUser } from "../../../packages/ragents/src/access.js";
+import {
+  isEnvironmentReference,
+  isProvisionedReference,
+  type ConfigValue,
+  type EnvironmentReference,
+  type ProvisionedReference,
+  type RAgentsConfig,
+} from "./config-definition.js";
+import { defaultDataDirectory } from "./data-directory.js";
+import { isPluginPath, pluginFolderFor } from "./plugin-support/plugins-root.js";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+export const SECRET_KEY_PATTERN = /(_PAT|_KEY|_TOKEN|_SECRET|_PASSWORD)$/;
+const ENVIRONMENT_PLACEHOLDER = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+
+interface ConfigFileEntry {
+  section: string;
+  key: string;
+  value: string;
+  viaReference: boolean;
+  overriddenByEnvironment: boolean;
+}
+
+interface LoadedConfigFile {
+  path: string;
+  entries: readonly ConfigFileEntry[];
+  users: readonly ResolvedProfileUser[] | undefined;
+  anonymousUser: AccessUser | undefined;
+}
+
+export interface ResolvedProfileUser extends AccessUser {
+  readonly password: string;
+  readonly token?: string;
+}
+
+const MIN_TOKEN_LENGTH = 16;
+const MAX_TOKEN_LENGTH = 512;
+
+const resolveUserToken = (
+  location: string,
+  raw: unknown,
+  environment: Readonly<Record<string, string | undefined>>,
+): string | undefined => {
+  if (raw === undefined) return undefined;
+  if (!isEnvironmentReference(raw) || typeof raw.name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(raw.name)) {
+    throw new Error(`${location}.token braucht env("ENV_NAME"); ein Token steht nie im Klartext in der Profildatei`);
+  }
+  const token = environment[raw.name];
+  if (!token) throw new Error(`${location}.token verweist auf die nicht gesetzte oder leere Umgebungsvariable ${raw.name}`);
+  // $ und ! sind tabu, weil der Verbraucher den Token als API-Schlüssel mit Vorlagen- und Befehlssyntax auswertet.
+  if (token.length < MIN_TOKEN_LENGTH || token.length > MAX_TOKEN_LENGTH || !/^[\x21-\x7e]+$/.test(token) || /[$!]/.test(token)) {
+    throw new Error(`${location}.token (${raw.name}) braucht ${MIN_TOKEN_LENGTH} bis ${MAX_TOKEN_LENGTH} druckbare ASCII-Zeichen ohne Leerzeichen, $ und !`);
+  }
+  return token;
+};
+
+const resolveIdentity = (location: string, entry: Record<string, unknown>): AccessUser => {
+  if (typeof entry.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(entry.id)) {
+    throw new Error(`${location}.id braucht 1 bis 64 Zeichen: Buchstaben, Ziffern, Punkt, Unterstrich oder Bindestrich`);
+  }
+  if (entry.label !== undefined && (typeof entry.label !== "string" || !entry.label.trim() || entry.label.length > 120)) {
+    throw new Error(`${location}.label braucht 1 bis 120 Zeichen`);
+  }
+  if (!Array.isArray(entry.rights) || !entry.rights.every(isAccessRight)) {
+    throw new Error(`${location}.rights braucht gültige Rechte als Strings oder "*" für alle Rechte`);
+  }
+  if (new Set(entry.rights).size !== entry.rights.length) throw new Error(`${location}.rights enthält doppelte Rechte`);
+  if (entry.startEntries !== undefined && (!Array.isArray(entry.startEntries)
+    || !entry.startEntries.every((id) => typeof id === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/.test(id))
+    || new Set(entry.startEntries).size !== entry.startEntries.length)) {
+    throw new Error(`${location}.startEntries braucht eindeutige Einstiegkennungen als Strings`);
+  }
+  return Object.freeze({
+    id: entry.id,
+    label: entry.label?.trim() ?? entry.id,
+    rights: Object.freeze([...entry.rights]),
+    ...(entry.startEntries ? { startEntries: Object.freeze([...entry.startEntries as string[]]) } : {}),
+  });
+};
+
+export const resolveAnonymousUser = (source: string, raw: unknown): AccessUser | undefined => {
+  if (raw === undefined) return undefined;
+  const location = `${source}: anonymousUser`;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${location} ist kein Benutzer`);
+  const entry = raw as Record<string, unknown>;
+  if (Object.keys(entry).some((key) => !["id", "label", "rights", "startEntries"].includes(key))) {
+    throw new Error(`${location} erlaubt nur id, label, rights und startEntries`);
+  }
+  return resolveIdentity(location, entry);
+};
+
+export const resolveProfileUsers = (
+  source: string,
+  raw: unknown,
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+): readonly ResolvedProfileUser[] | undefined => {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new Error(`${source}: users muss eine nicht leere Liste sein; ohne users ist die Anmeldung ausgeschaltet`);
+  }
+  const ids = new Set<string>();
+  const tokens = new Map<string, string>();
+  return raw.map((value: unknown, index: number) => {
+    const location = `${source}: users[${index}]`;
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${location} ist kein Benutzer`);
+    const entry = value as Record<string, unknown>;
+    if (Object.keys(entry).some((key) => !["id", "label", "password", "token", "rights", "startEntries"].includes(key))) {
+      throw new Error(`${location} erlaubt nur id, label, password, token, rights und startEntries`);
+    }
+    const user = resolveIdentity(location, entry);
+    if (ids.has(user.id)) throw new Error(`${location}.id ist doppelt: ${user.id}`);
+    ids.add(user.id);
+    if (typeof entry.password !== "string" && (!isEnvironmentReference(entry.password)
+      || typeof entry.password.name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(entry.password.name))) {
+      throw new Error(`${location}.password braucht einen Text oder env("ENV_NAME")`);
+    }
+    const password = typeof entry.password === "string" ? entry.password : environment[entry.password.name];
+    if (!password || password.length > 2048) throw new Error(`${location}.password fehlt, ist leer oder länger als 2048 Zeichen`);
+    const token = resolveUserToken(location, entry.token, environment);
+    if (token !== undefined) {
+      const other = tokens.get(token);
+      if (other) throw new Error(`${location}.token ist derselbe wie bei Benutzer ${other}; jeder Token gehört genau einem Benutzer`);
+      tokens.set(token, user.id);
+    }
+    return Object.freeze({ ...user, password, ...(token !== undefined ? { token } : {}) });
+  });
+};
+
+export const listFromEnvironmentValue = (value: string): readonly string[] | undefined => {
+  if (!value.startsWith("[")) return undefined;
+  const parsed = JSON.parse(value) as unknown;
+  if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== "string")) {
+    throw new Error(`Der Wert ${value} sieht aus wie eine Liste, ist aber keine Liste von Strings`);
+  }
+  return parsed as string[];
+};
+
+const materialize = (value: Exclude<ConfigValue, EnvironmentReference | ProvisionedReference>): string => {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return value ? "1" : "0";
+  return JSON.stringify(value);
+};
+
+/** Der Datenordner des Hosts, in dessen tools/ die Provisionierung ihre Werkzeuge legt. */
+const dataDirectoryOf = (source: string, raw: RAgentsConfig): string => {
+  const configured = raw.host?.DATA_DIR;
+  if (isEnvironmentReference(configured) && process.env[configured.name] === undefined) {
+    throw new Error(`${source}: host.DATA_DIR verweist auf die nicht gesetzte Umgebungsvariable ${configured.name}`);
+  }
+  const fromFile = isEnvironmentReference(configured) ? process.env[configured.name] : typeof configured === "string" ? configured : undefined;
+  const profile = process.env.PRODUCT_PROFILE;
+  if (!profile) throw new Error(`${source}: ohne PRODUCT_PROFILE gibt es keinen Datenordner und damit keinen Werkzeugordner`);
+  return path.resolve(process.env.DATA_DIR ?? fromFile ?? defaultDataDirectory(profile));
+};
+
+const entryFor = (source: string, section: string, key: string, value: ConfigValue, dataDirectory: () => string): ConfigFileEntry => {
+  const overriddenByEnvironment = process.env[key] !== undefined;
+  if (isProvisionedReference(value)) {
+    const file = path.join(pluginToolsDirectory(dataDirectory(), value.plugin), ...value.path.split("/"));
+    return { section, key, value: file, viaReference: false, overriddenByEnvironment };
+  }
+  if (isEnvironmentReference(value)) {
+    const resolved = process.env[value.name];
+    if (resolved === undefined) {
+      throw new Error(
+        `${source}: ${section}.${key} verweist mit env("${value.name}") auf eine Umgebungsvariable, `
+        + `die in dieser Shell nicht gesetzt ist. Setze sie vor dem Start (export ${value.name}=...) oder `
+        + "hinterlege sie in der Startdatei Deiner Shell; Secrets stehen nie in der Konfigurationsdatei.");
+    }
+    return { section, key, value: resolved, viaReference: true, overriddenByEnvironment };
+  }
+  if (typeof value === "string" && ENVIRONMENT_PLACEHOLDER.test(value)) {
+    throw new Error(
+      `${source}: ${section}.${key} steht als Text "${value}" in der Konfiguration; `
+      + `eine Referenz auf die Umgebung wird als env("...") geschrieben`);
+  }
+  if (SECRET_KEY_PATTERN.test(key)) {
+    throw new Error(
+      `${source}: ${section}.${key} ist ein Secret und darf nicht im Klartext in der Konfiguration stehen; `
+      + `per Umgebungsvariable setzen oder als env("ENV_NAME") referenzieren`);
+  }
+  return { section, key, value: materialize(value), viaReference: false, overriddenByEnvironment };
+};
+
+const parseEntries = (source: string, raw: RAgentsConfig): readonly ConfigFileEntry[] => {
+  const sections = Object.entries(raw) as readonly [string, Readonly<Record<string, ConfigValue>>][];
+  let resolved: string | undefined;
+  const dataDirectory = (): string => resolved ??= dataDirectoryOf(source, raw);
+  const entries: ConfigFileEntry[] = [];
+  for (const [section, sectionValue] of sections) {
+    for (const [key, value] of Object.entries(sectionValue)) {
+      entries.push(entryFor(source, section, key, value, dataDirectory));
+    }
+  }
+  const byKey = new Map<string, ConfigFileEntry>();
+  for (const entry of entries) {
+    const existing = byKey.get(entry.key);
+    if (existing && existing.value !== entry.value) {
+      throw new Error(
+        `${source}: ${entry.key} steht in ${existing.section} und ${entry.section} mit unterschiedlichen Werten`);
+    }
+    byKey.set(entry.key, entry);
+  }
+  return entries;
+};
+
+const PROFILE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export const profileFileName = (profile: string): string => `ragents.config.${profile}.ts`;
+
+/** The profile file lives in the repository root or wherever PRODUCT_PROFILE_FILE points; its name carries the profile. */
+export const profileFilePath = (root: string, environment: Readonly<Record<string, string | undefined>> = process.env): string | undefined => {
+  const profile = environment.PRODUCT_PROFILE;
+  if (!profile) return undefined;
+  if (!PROFILE_NAME.test(profile)) throw new Error(`PRODUCT_PROFILE ist kein gültiger Profilname: ${profile}`);
+  const file = environment.PRODUCT_PROFILE_FILE;
+  if (!file) return path.join(root, profileFileName(profile));
+  const source = path.resolve(file);
+  if (path.basename(source) !== profileFileName(profile)) {
+    throw new Error(`PRODUCT_PROFILE_FILE ${source} passt nicht zum Profil ${profile}; erwartet wird ${profileFileName(profile)}`);
+  }
+  if (!statSync(source, { throwIfNoEntry: false })?.isFile()) throw new Error(`Die Profildatei ${source} fehlt`);
+  return source;
+};
+
+const withPluginPaths = (source: string, raw: RAgentsConfig): RAgentsConfig => {
+  const plugins = raw.host?.PLUGINS;
+  if (!Array.isArray(plugins)) return raw;
+  const resolved = plugins.map((entry) => isPluginPath(entry) ? pluginFolderFor(entry, path.dirname(source)) : entry);
+  return { ...raw, host: { ...raw.host, PLUGINS: resolved } };
+};
+
+const readProfileConfiguration = async (root: string): Promise<LoadedConfigFile | undefined> => {
+  const source = profileFilePath(root);
+  if (!source || !statSync(source, { throwIfNoEntry: false })?.isFile()) return undefined;
+  const module = await import(pathToFileURL(source).href) as Record<string, unknown>;
+  const loadedConfig = module.config;
+  if (typeof loadedConfig !== "object" || loadedConfig === null) {
+    throw new Error(`${source} exportiert keine Konstante config mit den Konfigurationssektionen`);
+  }
+  const raw = withPluginPaths(source, loadedConfig as RAgentsConfig);
+  const users = resolveProfileUsers(source, module.users);
+  const anonymousUser = resolveAnonymousUser(source, module.anonymousUser);
+  if (users && anonymousUser) throw new Error(`${source}: users und anonymousUser schließen einander aus`);
+  return { path: source, entries: parseEntries(source, raw), users, anonymousUser };
+};
+
+let loadedConfigFile: LoadedConfigFile | undefined;
+let loadCompleted = false;
+
+export const loadConfigFile = async (root = rootDir): Promise<void> => {
+  if (loadCompleted) throw new Error("Die Konfiguration wurde bereits geladen");
+  loadedConfigFile = await readProfileConfiguration(root);
+  loadCompleted = true;
+  if (!loadedConfigFile) return;
+  let applied = 0;
+  for (const entry of loadedConfigFile.entries) {
+    if (entry.overriddenByEnvironment) continue;
+    process.env[entry.key] = entry.value;
+    applied++;
+  }
+  const overridden = loadedConfigFile.entries.length - applied;
+  console.log(`Konfiguration ${loadedConfigFile.path} geladen `
+    + `(${applied} Werte übernommen, ${overridden} durch Umgebung überstimmt)`);
+};
+
+export const configFilePath = (): string | null => loadedConfigFile?.path ?? null;
+
+export const configuredUsers = (): readonly ResolvedProfileUser[] | undefined => loadedConfigFile?.users;
+
+export const configuredAnonymousUser = (): AccessUser | undefined => loadedConfigFile?.anonymousUser;
+
+export interface ConfigFileValidationContext {
+  hostKeys: readonly string[];
+  knownPluginIds: readonly string[];
+  activePluginIds: readonly string[];
+  declaredKeysFor: (pluginId: string) => readonly string[];
+  secretKeys: readonly string[];
+}
+
+export const validateConfigFileSections = (context: ConfigFileValidationContext): void => {
+  if (!loadCompleted) throw new Error("Die Konfiguration muss vor ihrer Prüfung geladen werden");
+  if (!loadedConfigFile) return;
+  const source = loadedConfigFile.path;
+  const known = new Set(context.knownPluginIds);
+  const active = new Set(context.activePluginIds);
+  const secret = new Set(context.secretKeys);
+  for (const section of new Set(loadedConfigFile.entries.map((entry) => entry.section))) {
+    if (section === "host") continue;
+    if (!known.has(section)) {
+      throw new Error(`${source}: unbekannte Sektion ${section}; bekannt sind host, ${[...known].join(", ")}`);
+    }
+    if (!active.has(section)) {
+      console.log(`Konfiguration: Sektion ${section} gehört zu einem inaktiven Plugin und wird ignoriert`);
+    }
+  }
+  for (const entry of loadedConfigFile.entries) {
+    if (secret.has(entry.key) && !entry.viaReference) {
+      throw new Error(
+        `${source}: ${entry.section}.${entry.key} ist als Secret deklariert und darf nicht im Klartext `
+        + `in der Konfiguration stehen; per Umgebungsvariable setzen oder als env("ENV_NAME") referenzieren`);
+    }
+    if (entry.section === "host") {
+      if (!context.hostKeys.includes(entry.key)) {
+        throw new Error(`${source}: host.${entry.key} ist kein Host-Schlüssel; erlaubt sind ${context.hostKeys.join(", ")}`);
+      }
+      continue;
+    }
+    if (!active.has(entry.section)) continue;
+    const declared = context.declaredKeysFor(entry.section);
+    if (!declared.includes(entry.key)) {
+      throw new Error(
+        `${source}: ${entry.section}.${entry.key} ist für dieses Plugin nicht deklariert; `
+        + (declared.length > 0 ? `deklariert sind ${declared.join(", ")}` : "das Plugin deklariert keine Schlüssel"));
+    }
+  }
+};

package/apps/server/src/config.ts

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { declaredEnvironment } from "./plugin-support/plugin-config.js";
+import { defaultDataDirectory } from "./data-directory.js";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+export const hostConfigDescriptors = [
+  { key: "PORT", source: "environment" },
+  { key: "DATA_DIR", source: "environment" },
+  { key: "WEB_DIST_DIR", source: "environment" },
+  { key: "AGENT_THINKING", source: "environment" },
+  { key: "AGENT_HOME_DIR", source: "environment" },
+  { key: "COMPACTION_PROVIDER", source: "environment" },
+  { key: "COMPACTION_MODEL", source: "environment" },
+  { key: "PRODUCT_PROFILE", source: "environment" },
+  { key: "PLUGINS", source: "environment" },
+  { key: "PRODUCT_ID", source: "environment" },
+  { key: "PRODUCT_TITLE", source: "environment" },
+  { key: "RAGENTS_BASH_TIMEOUT_SECONDS", source: "environment" },
+  { key: "ACCESS_TOKEN", source: "environment", secret: true },
+] as const;
+
+export const hostConfigKeys: readonly string[] = hostConfigDescriptors.map((descriptor) => descriptor.key);
+
+export const HOST_SECRET_ENV_NAMES: readonly string[] = hostConfigDescriptors
+  .filter((descriptor) => "secret" in descriptor && descriptor.secret)
+  .map((descriptor) => descriptor.key);
+
+const env = declaredEnvironment(hostConfigDescriptors);
+
+export const config = Object.freeze({
+  port: Number(env.value("PORT", "4710")),
+  dataDir: path.resolve(env.value("DATA_DIR", defaultDataDirectory(env.required("PRODUCT_PROFILE")))),
+  webDistDir: path.resolve(env.value("WEB_DIST_DIR", path.join(rootDir, "apps/web/dist", env.required("PRODUCT_PROFILE")))),
+  agentThinking: env.value("AGENT_THINKING", "high"),
+  agentHomeDir: path.resolve(env.value("AGENT_HOME_DIR", path.join(rootDir, "apps/server/agent-home"))),
+  compactionProvider: env.value("COMPACTION_PROVIDER", "openrouter"),
+  compactionModel: env.value("COMPACTION_MODEL", ""),
+  productProfile: env.required("PRODUCT_PROFILE"),
+  productId: env.required("PRODUCT_ID"),
+  productTitle: env.required("PRODUCT_TITLE"),
+  plugins: env.list("PLUGINS"),
+});
+
+export type Config = typeof config;