@schlenkr/ragents 0.1.0

package/apps/server/src/plugin-support/native-typescript-executor.ts

@@ -0,0 +1,260 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, realpath, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "esbuild";
+import type { NativeTypeScriptBinding, NativeTypeScriptExecutor, NativeTypeScriptRequest, NativeTypeScriptResult } from "@aicontainer/ragents";
+import type { JsonValue } from "@aicontainer/ragents";
+import { startManagedService, type ManagedService, type WorkspaceProcessContext } from "@aicontainer/workspace-executor";
+import { syncWorkspaceOwnership } from "./workspace-ownership.js";
+
+interface ExecutorOptions {
+  directoryFor(runId: string): string;
+  processContextFor(runId: string): Promise<WorkspaceProcessContext>;
+}
+interface Backend {
+  runId: string;
+  instanceId: string;
+  fingerprint: string;
+  controller: AbortController;
+  service: ManagedService;
+  queue: Promise<void>;
+  receive(message: unknown): void;
+  reject(error: Error): void;
+  log(value: unknown): void;
+}
+interface BackendSlot {
+  controller: AbortController;
+  pending: Promise<Backend>;
+  stopping?: Promise<void>;
+}
+const errorOf = (error: unknown): Error => error instanceof Error ? error : new Error(String(error));
+let runnerBundle: Promise<string> | undefined;
+const runner = (): Promise<string> => runnerBundle ??= build({
+  entryPoints: [fileURLToPath(new URL("./native-typescript-child.ts", import.meta.url))],
+  bundle: true,
+  platform: "node",
+  format: "esm",
+  target: "node22",
+  packages: "external",
+  write: false,
+}).then((result) => result.outputFiles![0]!.text);
+
+export class NodeTypeScriptExecutor implements NativeTypeScriptExecutor {
+  readonly #options: ExecutorOptions;
+  readonly #backends = new Map<string, BackendSlot>();
+  readonly #stopping = new Map<string, Promise<void>>();
+  #closed = false;
+
+  constructor(options: ExecutorOptions) { this.#options = options; }
+
+  async execute(request: NativeTypeScriptRequest, binding: NativeTypeScriptBinding): Promise<NativeTypeScriptResult> {
+    binding.signal?.throwIfAborted();
+    if (this.#closed || this.#stopping.has(request.context.runId)) throw new Error("Die Node-Ausführung wird beendet.");
+    const instanceId = request.instanceId ?? `invocation-${randomUUID()}`;
+    const key = `${request.context.runId}\0${instanceId}`;
+    const fingerprint = createHash("sha256").update(JSON.stringify({ entry: request.program.entry, files: request.program.files })).digest("hex");
+    let slot = this.#backends.get(key);
+    if (!slot) {
+      const controller = new AbortController();
+      slot = { controller, pending: this.#start(request, instanceId, fingerprint, controller, binding.signal) };
+      this.#backends.set(key, slot);
+      const created = slot;
+      void slot.pending.catch(() => { if (this.#backends.get(key) === created) this.#backends.delete(key); });
+    }
+    slot.controller.signal.throwIfAborted();
+    const backend = await slot.pending;
+    if (backend.fingerprint !== fingerprint) throw new Error("Die Backend-Revision muss vor dem Codewechsel beendet werden.");
+    const operation = backend.queue.then(() => this.#invoke(backend, request, binding));
+    backend.queue = operation.then(() => undefined, () => undefined);
+    try { return await operation; }
+    finally {
+      if (request.instanceId === undefined) await this.stopInstance(request.context.runId, instanceId);
+    }
+  }
+
+  async #start(request: NativeTypeScriptRequest, instanceId: string, fingerprint: string, controller: AbortController, callerSignal?: AbortSignal): Promise<Backend> {
+    const signal = callerSignal ? AbortSignal.any([controller.signal, callerSignal]) : controller.signal;
+    const processContext = await this.#options.processContextFor(request.context.runId);
+    signal.throwIfAborted();
+    const directory = path.join(this.#options.directoryFor(request.context.runId), createHash("sha256").update(instanceId).digest("hex"), fingerprint);
+    await mkdir(directory, { recursive: true });
+    for (const file of request.program.files) {
+      const target = path.resolve(directory, file.fileName);
+      if (!target.startsWith(`${directory}${path.sep}`)) throw new Error("Backend-Datei liegt außerhalb des Builds.");
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, file.text);
+    }
+    const entry = path.resolve(directory, request.program.entry);
+    if (!entry.startsWith(`${directory}${path.sep}`) || !request.program.files.some((file) => path.resolve(directory, file.fileName) === entry))
+      throw new Error("Der gebaute Backend-Einstieg fehlt.");
+    await writeFile(path.join(directory, "package.json"), JSON.stringify({ type: "module" }));
+    await writeFile(path.join(directory, "__runner.mjs"), await runner());
+    const toolkit = fileURLToPath(new URL("../../../../node_modules", import.meta.url));
+    const resolvedDependencies = request.cwd ? await realpath(path.join(request.cwd, "node_modules")).catch((error: NodeJS.ErrnoException) => {
+      if (error.code !== "ENOENT") throw error;
+      return realpath(toolkit);
+    }) : await realpath(toolkit);
+    await symlink(resolvedDependencies, path.join(directory, "node_modules")).catch((error: NodeJS.ErrnoException) => {
+      if (error.code !== "EEXIST") throw error;
+    });
+    await syncWorkspaceOwnership(directory, processContext);
+    signal.throwIfAborted();
+    let resolveReady!: () => void;
+    let rejectReady!: (error: Error) => void;
+    const ready = new Promise<void>((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+    void ready.catch(() => undefined);
+    const backend: Backend = {
+      runId: request.context.runId, instanceId, fingerprint, controller,
+      service: undefined as unknown as ManagedService,
+      queue: Promise.resolve(), log: () => undefined,
+      reject: rejectReady,
+      receive: (raw) => {
+        const message = raw as { kind: string; error?: string };
+        if (message.kind === "ready") resolveReady();
+        else if (message.kind === "failed") rejectReady(new Error(message.error));
+      },
+    };
+    let stderr = "";
+    const fail = (error: Error): void => {
+      controller.abort(error);
+      backend.reject(error);
+      backend.service.kill("SIGKILL");
+    };
+    backend.service = startManagedService({
+      command: process.execPath,
+      args: [path.join(directory, "__runner.mjs")],
+      cwd: request.cwd ?? processContext.cwd,
+      env: { ...processContext.env, RAGENTS_RUN_ID: request.context.runId },
+      uid: processContext.uid, gid: processContext.gid,
+      ipc: true, label: `TypeScript ${instanceId}`,
+      onMessage: (message) => {
+        try { backend.receive(message); }
+        catch (error) { fail(errorOf(error)); }
+      },
+      onStdout: (chunk) => backend.log(chunk.toString("utf8")),
+      onStderr: (chunk) => {
+        const text = chunk.toString("utf8");
+        stderr = (stderr + text).slice(-4_000);
+        backend.log(text);
+      },
+      onError: fail,
+      onExit: (code) => {
+        const error = new Error(`Backendprozess beendet (Code ${code}).${stderr.trim() ? `\n${stderr.trim()}` : ""}`);
+        controller.abort(error);
+        backend.reject(error);
+        void backend.service.finished.then(() => backend.queue).finally(() => {
+          const key = `${backend.runId}\0${backend.instanceId}`;
+          const current = this.#backends.get(key);
+          if (current) void current.pending.then((value) => { if (value === backend && this.#backends.get(key) === current) this.#backends.delete(key); }, () => undefined);
+        }).catch(() => undefined);
+      },
+    });
+    const timeout = setTimeout(() => rejectReady(new Error("Das Backend wurde nicht innerhalb von 15 Sekunden bereit.")), 15_000);
+    const abort = () => rejectReady(errorOf(signal?.reason ?? "Der Backendstart wurde abgebrochen."));
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      signal?.throwIfAborted();
+      await backend.service.send({ kind: "load", entry });
+      await ready;
+      signal.throwIfAborted();
+      if (this.#closed || this.#stopping.has(backend.runId)) throw new Error("Der Run wurde beim Backendstart gestoppt.");
+      return backend;
+    } catch (error) {
+      backend.service.kill("SIGKILL");
+      await backend.service.finished;
+      throw error;
+    } finally { clearTimeout(timeout); signal?.removeEventListener("abort", abort); }
+  }
+
+  async #invoke(backend: Backend, request: NativeTypeScriptRequest, binding: NativeTypeScriptBinding): Promise<NativeTypeScriptResult> {
+    const signal = binding.signal ? AbortSignal.any([backend.controller.signal, binding.signal]) : backend.controller.signal;
+    signal.throwIfAborted();
+    const capabilities = new Set(request.context.capabilities.map((entry) => entry.id));
+    const calls = new Set<Promise<void>>();
+    let force: NodeJS.Timeout | undefined;
+    let rejectInvocation!: (error: Error) => void;
+    const abort = (): void => {
+      void backend.service.send({ kind: "cancel" }).catch(() => undefined);
+      force = setTimeout(() => backend.service.kill("SIGKILL"), 200);
+      rejectInvocation(errorOf(signal.reason ?? "Der Aufruf wurde abgebrochen."));
+    };
+    const operation = new Promise<NativeTypeScriptResult>((resolve, reject) => {
+      rejectInvocation = reject;
+      backend.reject = reject;
+      backend.log = binding.log;
+      backend.receive = (raw) => {
+        const message = raw as { kind: string; name?: string; input?: JsonValue; callId?: number; value?: unknown; result?: unknown; state?: unknown; error?: string };
+        if (message.kind === "result") resolve({ result: message.result, state: message.state });
+        else if (message.kind === "failed") reject(new Error(message.error));
+        else if (message.kind === "log") binding.log(message.value);
+        else if (message.kind === "call") {
+          const operation = (async () => {
+            try {
+              signal.throwIfAborted();
+              if (!capabilities.has(message.name!)) throw new Error(`Capability ${message.name} ist nicht freigegeben.`);
+              const value = await binding.call(message.name!, message.input!);
+              await backend.service.send({ kind: "reply", callId: message.callId, value });
+            } catch (error) {
+              await backend.service.send({ kind: "reply", callId: message.callId, error: errorOf(error).message }).catch(() => undefined);
+            }
+          })();
+          calls.add(operation);
+          void operation.finally(() => calls.delete(operation));
+        }
+      };
+      signal.addEventListener("abort", abort, { once: true });
+      if (signal.aborted) abort();
+      else void backend.service.send({ kind: "execute", request }).catch(reject);
+    });
+    try {
+      const result = await operation;
+      await Promise.allSettled([...calls]);
+      signal.throwIfAborted();
+      return result;
+    } finally {
+      try {
+        await Promise.allSettled([...calls]);
+        if (signal.aborted) await backend.service.finished;
+      } finally {
+        signal.removeEventListener("abort", abort);
+        if (force) clearTimeout(force);
+        backend.log = () => undefined;
+        backend.reject = () => undefined;
+        backend.receive = () => undefined;
+      }
+    }
+  }
+
+  stopInstance(runId: string, instanceId: string): Promise<void> {
+    const key = `${runId}\0${instanceId}`;
+    const slot = this.#backends.get(key);
+    if (!slot) return Promise.resolve();
+    if (slot.stopping) return slot.stopping;
+    slot.controller.abort(new Error("Die Node-Instanz wird beendet."));
+    slot.stopping = (async () => {
+      const backend = await slot.pending.catch(() => undefined);
+      if (!backend) return;
+      backend.service.kill("SIGKILL");
+      await backend.service.finished;
+      await backend.queue;
+    })().finally(() => { if (this.#backends.get(key) === slot) this.#backends.delete(key); });
+    return slot.stopping;
+  }
+
+  stopRun(runId: string): Promise<void> {
+    const current = this.#stopping.get(runId);
+    if (current) return current;
+    const stopped = Promise.resolve().then(async () => {
+      await Promise.all([...this.#backends.keys()].filter((key) => key.startsWith(`${runId}\0`))
+        .map((key) => this.stopInstance(runId, key.slice(runId.length + 1))));
+    }).finally(() => { if (this.#stopping.get(runId) === stopped) this.#stopping.delete(runId); });
+    this.#stopping.set(runId, stopped);
+    return stopped;
+  }
+
+  async shutdown(): Promise<void> {
+    this.#closed = true;
+    await Promise.all([...new Set([...this.#backends.keys()].map((key) => key.split("\0")[0]!))].map((runId) => this.stopRun(runId)));
+  }
+}

package/apps/server/src/plugin-support/plugin-config.ts

@@ -0,0 +1,48 @@
+import type { PluginConfigDescriptor } from "@aicontainer/ragents";
+import { listFromEnvironmentValue } from "../config-file.js";
+
+export interface DeclaredEnvironment<Key extends string> {
+  descriptors: readonly PluginConfigDescriptor[];
+  value: (key: Key, fallback: string) => string;
+  optional: (key: Key) => string | undefined;
+  required: (key: Key) => string;
+  list: (key: Key) => readonly string[];
+  flag: (key: Key) => boolean;
+  positiveNumber: (key: Key, fallback: string) => number;
+}
+
+type EnvironmentKeyOf<T extends readonly PluginConfigDescriptor[]> =
+  Extract<T[number], { source: "environment" }>["key"];
+
+export const declaredEnvironment = <const T extends readonly PluginConfigDescriptor[]>(
+  descriptors: T,
+): DeclaredEnvironment<EnvironmentKeyOf<T>> => {
+  const declared = new Set(
+    descriptors.filter((descriptor) => descriptor.source === "environment").map((descriptor) => descriptor.key),
+  );
+  const read = (key: string): string | undefined => {
+    if (!declared.has(key)) throw new Error(`Umgebungsvariable ${key} ist für dieses Plugin nicht deklariert`);
+    return process.env[key];
+  };
+  return {
+    descriptors,
+    value: (key, fallback) => read(key) ?? fallback,
+    optional: (key) => read(key),
+    required: (key) => {
+      const value = read(key);
+      if (!value) throw new Error(`Umgebungsvariable ${key} fehlt`);
+      return value;
+    },
+    list: (key) => {
+      const value = read(key);
+      if (value === undefined || value === "") return [];
+      return listFromEnvironmentValue(value) ?? [value];
+    },
+    flag: (key) => read(key) === "1",
+    positiveNumber: (key, fallback) => {
+      const value = Number(read(key) ?? fallback);
+      if (!Number.isFinite(value) || value <= 0) throw new Error(`${key} muss eine positive Zahl sein`);
+      return value;
+    },
+  };
+};

package/apps/server/src/plugin-support/plugin-folder.ts

@@ -0,0 +1,81 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+import type {
+  PluginRegistration,
+  RAgentsPlugin,
+  SkillContribution,
+  StartEntryContribution,
+} from "@aicontainer/ragents";
+import { skillsFromDirectory, type FolderSkills } from "./skills.js";
+import { pluginFolder } from "./plugins-root.js";
+import { runScriptsFromDirectory, type ScriptStartEntry } from "./run-scripts.js";
+import { systemPromptOptionsFromDirectory, type SystemPromptOption } from "./system-prompts.js";
+
+export { pluginFolder };
+
+const assetFolder = (folder: string, name: string): string | undefined => {
+  const directory = path.join(folder, name);
+  const stats = statSync(directory, { throwIfNoEntry: false });
+  if (!stats) return undefined;
+  if (!stats.isDirectory()) throw new Error(`${directory} muss ein Verzeichnis sein`);
+  return directory;
+};
+
+export const folderSkills = (folder: string, pluginId: string): FolderSkills => {
+  const directory = assetFolder(folder, "skills");
+  return directory ? skillsFromDirectory(directory, pluginId) : { startEntries: [], paths: [] };
+};
+
+export const folderRunScripts = (
+  folder: string,
+  pluginId: string,
+): readonly ScriptStartEntry[] => {
+  const directory = assetFolder(folder, "run-scripts");
+  return directory ? runScriptsFromDirectory(directory, pluginId) : [];
+};
+
+export const folderSkillPaths = (folder: string): readonly string[] => folderSkills(folder, path.basename(folder)).paths;
+
+export const folderSystemPrompts = (folder: string): readonly SystemPromptOption[] => {
+  const directory = assetFolder(folder, "prompts");
+  return directory ? systemPromptOptionsFromDirectory(directory) : [];
+};
+
+export const withFolderAssets = (plugin: RAgentsPlugin): RAgentsPlugin => ({
+  manifest: plugin.manifest,
+  register: (host) => {
+    const explicitEntries: StartEntryContribution[] = [];
+    const explicitSkills: SkillContribution[] = [];
+    const observed: PluginRegistration = {
+      ...host,
+      startEntries: (...contributions) => {
+        explicitEntries.push(...contributions);
+        host.startEntries(...contributions);
+      },
+      skills: (...contributions) => {
+        explicitSkills.push(...contributions);
+        host.skills(...contributions);
+      },
+    };
+    plugin.register(observed);
+
+    const folder = pluginFolder(plugin.manifest.id);
+    const skills = folderSkills(folder, plugin.manifest.id);
+    const entries = [
+      ...skills.startEntries,
+      ...folderRunScripts(folder, plugin.manifest.id),
+    ].filter((entry) => !explicitEntries.some((explicit) => explicit.id === entry.id));
+    if (entries.length > 0) host.startEntries(...entries);
+
+    const skillPaths = skills.paths;
+    if (skillPaths.length === 0) return;
+    host.skills({
+      id: `${plugin.manifest.id}.folder-skills`,
+      paths: async (context) => {
+        const explicit = await Promise.all(explicitSkills.map((skill) => skill.paths(context)));
+        const taken = new Set(explicit.flat());
+        return skillPaths.filter((skillPath) => !taken.has(skillPath));
+      },
+    });
+  },
+});

package/apps/server/src/plugin-support/plugin-module.ts

@@ -0,0 +1,14 @@
+import type { PluginHost, RAgentsPlugin } from "@aicontainer/ragents";
+
+export interface PluginModule {
+  readonly requires?: readonly string[];
+  readonly create: (host: PluginHost) => RAgentsPlugin;
+}
+
+export const isPluginModule = (value: unknown): value is PluginModule => {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as PluginModule;
+  if (typeof candidate.create !== "function") return false;
+  if (candidate.requires === undefined) return true;
+  return Array.isArray(candidate.requires) && candidate.requires.every((id) => typeof id === "string");
+};

package/apps/server/src/plugin-support/plugins-root.ts

@@ -0,0 +1,41 @@
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PLUGIN_SERVER_FOLDER = "server";
+
+export const pluginsRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)), "../../../../plugins");
+
+export const isPluginPath = (entry: string): boolean => /^(\.{1,2}\/|\/|~\/)/.test(entry);
+
+/** A profile names a plugin by id (a folder under plugins/) or by a path, relative to the profile file. */
+export const pluginFolderFor = (entry: string, base: string, root = pluginsRoot): string => {
+  if (!isPluginPath(entry)) return path.join(root, entry);
+  const expanded = entry.startsWith("~/") ? path.join(homedir(), entry.slice(2)) : entry;
+  return path.resolve(base, expanded);
+};
+
+export const pluginIdOf = (folder: string): string => path.basename(folder);
+
+export const WEB_ENTRY_FILES = ["web/index.ts", "web/index.tsx"] as const;
+
+export const webEntryOf = (folder: string): string | undefined =>
+  WEB_ENTRY_FILES.map((name) => path.join(folder, name))
+    .find((candidate) => statSync(candidate, { throwIfNoEntry: false })?.isFile() === true);
+
+const folders = new Map<string, string>();
+
+export const registerPluginFolder = (id: string, folder: string): void => {
+  const known = folders.get(id);
+  if (known && known !== folder) throw new Error(`Das Plugin ${id} liegt bereits unter ${known}, nicht unter ${folder}`);
+  folders.set(id, folder);
+};
+
+export const pluginFolder = (pluginId: string): string => {
+  const folder = folders.get(pluginId) ?? path.join(pluginsRoot, pluginId);
+  const stats = statSync(folder, { throwIfNoEntry: false });
+  if (!stats?.isDirectory()) throw new Error(`Das Plugin ${pluginId} hat keinen Ordner ${folder}`);
+  return folder;
+};

package/apps/server/src/plugin-support/product-model-settings-contract.ts

@@ -0,0 +1,24 @@
+import { Type } from "typebox";
+import { defineOperation } from "@aicontainer/ragents/src/rpc/contract";
+import { openJson } from "@aicontainer/ragents/src/http/contracts";
+import type { ProductModelDraft, ProductModelSettings } from "../../../../plugins/ragents.product/model-settings-contract.js";
+
+const settings = openJson<ProductModelSettings>("ProductModelSettings");
+
+/** Je Produktplugin ein Paar: die Modellvorgaben lesen und speichern. */
+export const productModelSettingsContracts = (pluginId: string) => ({
+  read: defineOperation({
+    id: `${pluginId}.modelSettings.read`,
+    description: "Die Modellvorgaben der Agentprofile mit dem verfügbaren Modellkatalog. Recht: settings.read.",
+    rights: ["settings.read"],
+    input: Type.Object({}, { additionalProperties: false }),
+    result: settings,
+  }),
+  save: defineOperation({
+    id: `${pluginId}.modelSettings.save`,
+    description: "Die Modellvorgaben der Agentprofile speichern. Rechte: settings.read und settings.write.",
+    rights: ["settings.read", "settings.write"],
+    input: Type.Object({ value: openJson<ProductModelDraft>("ProductModelDraft") }, { additionalProperties: false }),
+    result: settings,
+  }),
+});

package/apps/server/src/plugin-support/product-model-settings.ts

@@ -0,0 +1,120 @@
+import { readFileSync, renameSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { DomainError, implement, isThinkingLevel, type AgentProfile, type MethodContribution, type ThinkingLevel } from "@aicontainer/ragents";
+import type { ProductModelDraft, ProductModelSettings } from "../../../../plugins/ragents.product/model-settings-contract.js";
+import type { ModelChoice } from "./model-choice.js";
+import { productModelSettingsContracts } from "./product-model-settings-contract.js";
+
+type AgentModelProfile = Extract<AgentProfile, { driver: "agent" }>;
+
+const invalid = (message: string): DomainError => new DomainError("product-model-invalid", message, 400);
+
+const objectOf = (value: unknown, fields: readonly string[]): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalid(`${fields.join(", ")} sind erforderlich.`);
+  if (Object.keys(value).some((key) => !fields.includes(key))) throw invalid(`Erlaubt sind nur ${fields.join(", ")}.`);
+  return value as Record<string, unknown>;
+};
+
+export class ProductModelSettingsStore {
+  readonly #file: string;
+  readonly #baseProfiles: readonly AgentProfile[];
+  readonly #choice: ModelChoice;
+  #current: ProductModelDraft;
+  #pending: Promise<unknown> = Promise.resolve();
+  readonly modelChoice: ModelChoice;
+
+  constructor(file: string, choice: ModelChoice, profiles: readonly AgentProfile[]) {
+    this.#file = file;
+    this.#choice = choice;
+    this.#baseProfiles = profiles.map((profile) => ({ ...profile }));
+    let saved: unknown;
+    try { saved = JSON.parse(readFileSync(file, "utf8")); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      saved = { profiles: this.#agentProfiles().map(({ name, model, thinking }) => ({ name, model, thinking })) };
+    }
+    this.#current = this.#validate(saved);
+    const store = this;
+    this.modelChoice = {
+      provider: choice.provider,
+      get options() { return choice.options; },
+      get selectable() { return choice.selectable; },
+      get defaultModel() { return store.#selection("coordinator").model; },
+      thinkingOptionsFor: (model) => choice.thinkingOptionsFor(model ?? store.#selection("coordinator").model),
+    };
+  }
+
+  readonly coordinatorThinking = (): ThinkingLevel => this.#selection("coordinator").thinking;
+
+  readonly profiles = (): AgentProfile[] => this.#baseProfiles.map((profile) => {
+    if (profile.driver !== "agent") return { ...profile };
+    const selected = this.#selection(profile.name);
+    return {
+      ...profile, ...selected,
+      description: `${selected.model} mit Denktiefe ${selected.thinking}. ${profile.description}`,
+    };
+  });
+
+  get(): ProductModelSettings {
+    return {
+      profiles: this.profiles().filter((profile): profile is AgentModelProfile => profile.driver === "agent")
+        .map(({ name, description, provider, model, thinking }) => ({ name, description, provider, model, thinking: thinking! })),
+      models: this.#choice.options.map((id) => ({
+        id, provider: this.#choice.provider, label: `${this.#choice.provider}/${id}`,
+        thinking: [...this.#choice.thinkingOptionsFor(id)],
+      })),
+    };
+  }
+
+  async save(value: unknown): Promise<ProductModelSettings> {
+    const selected = this.#validate(value);
+    const operation = this.#pending.then(async () => {
+      await mkdir(path.dirname(this.#file), { recursive: true, mode: 0o700 });
+      await writeFile(`${this.#file}.tmp`, JSON.stringify(selected), { mode: 0o600 });
+      renameSync(`${this.#file}.tmp`, this.#file);
+      this.#current = selected;
+      return this.get();
+    });
+    this.#pending = operation.catch(() => undefined);
+    return operation;
+  }
+
+  #agentProfiles(): AgentModelProfile[] {
+    return this.#baseProfiles.filter((profile): profile is AgentModelProfile => profile.driver === "agent");
+  }
+
+  #selection(name: string): ProductModelDraft["profiles"][number] {
+    const selected = this.#current.profiles.find((profile) => profile.name === name);
+    if (!selected) throw invalid(`Das Agentprofil ${name} hat keine Modellvorgabe.`);
+    return selected;
+  }
+
+  #validate(value: unknown): ProductModelDraft {
+    const { profiles } = objectOf(value, ["profiles"]);
+    const expected = this.#agentProfiles();
+    if (!Array.isArray(profiles) || profiles.length !== expected.length) throw invalid(`Vollständig erforderlich sind die Agentprofile: ${expected.map((profile) => profile.name).join(", ")}.`);
+    const seen = new Set<string>();
+    const validated = profiles.map((item: unknown) => {
+      const entry = objectOf(item, ["name", "model", "thinking"]);
+      const profile = expected.find((candidate) => candidate.name === entry.name);
+      if (!profile) throw invalid(`Unbekanntes Agentprofil ${String(entry.name)}.`);
+      if (seen.has(profile.name)) throw invalid(`Das Agentprofil ${profile.name} steht doppelt.`);
+      seen.add(profile.name);
+      if (profile.provider !== this.#choice.provider) throw invalid(`Das Agentprofil ${profile.name} verwendet einen anderen Provider.`);
+      if (typeof entry.model !== "string" || !this.#choice.options.includes(entry.model)) throw invalid(`Das Modell ${String(entry.model)} steht nicht zur Wahl.`);
+      const allowed = this.#choice.thinkingOptionsFor(entry.model);
+      if (!isThinkingLevel(entry.thinking) || !allowed.includes(entry.thinking)) throw invalid(`Die Denktiefe ${String(entry.thinking)} ist für ${entry.model} nicht verfügbar (gültig: ${allowed.join(", ")}).`);
+      return { name: profile.name, model: entry.model, thinking: entry.thinking };
+    });
+    return { profiles: expected.map((profile) => validated.find((entry) => entry.name === profile.name)!) };
+  }
+}
+
+export const productModelSettingsMethods = (pluginId: string, settings: Pick<ProductModelSettingsStore, "get" | "save">): MethodContribution[] => {
+  const contracts = productModelSettingsContracts(pluginId);
+  return [
+    implement(contracts.read, () => settings.get()),
+    implement(contracts.save, ({ value }) => settings.save(value)),
+  ];
+};