@schlenkr/ragents 0.1.0

package/apps/server/src/plugin-support/product-start-options.ts

@@ -0,0 +1,104 @@
+import { Type } from "typebox";
+import { DomainError, isThinkingLevel, type StartOptionContribution, type ThinkingLevel } from "@aicontainer/ragents";
+import type { ModelChoice } from "./model-choice.js";
+import type { SystemPromptCatalog } from "./system-prompts.js";
+import { modelStartOptionId, systemPromptStartOptionId } from "../ragents/start-option-state.js";
+
+export interface ModelStartOptionValue {
+  model: string;
+  thinking?: ThinkingLevel;
+}
+
+export interface SystemPromptStartOptionValue {
+  promptIds: readonly string[];
+  shareWithAgents: boolean;
+}
+
+const modelSchema = Type.Object({
+  model: Type.String({ minLength: 1 }),
+  thinking: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+
+const systemPromptSchema = Type.Object({
+  promptIds: Type.Array(Type.String({ minLength: 1 })),
+  shareWithAgents: Type.Boolean(),
+}, { additionalProperties: false });
+
+export const modelStartOption = (choice: ModelChoice, preferredThinking: ThinkingLevel | (() => ThinkingLevel)): StartOptionContribution => {
+  const resolved = (model: string, wanted: string | undefined): ModelStartOptionValue => {
+    if (!choice.options.includes(model)) {
+      throw new DomainError("model-unknown", `Das Modell ${model} steht nicht zur Wahl.`, 404);
+    }
+    const allowed = choice.thinkingOptionsFor(model);
+    if (wanted !== undefined) {
+      if (!isThinkingLevel(wanted) || !allowed.includes(wanted)) {
+        throw new DomainError(
+          "thinking-unknown",
+          `Das Reasoning ${wanted} steht für dieses Modell nicht zur Wahl (gültig: ${allowed.join(", ")}).`,
+          400,
+        );
+      }
+      return { model, thinking: wanted };
+    }
+    const preferred = typeof preferredThinking === "function" ? preferredThinking() : preferredThinking;
+    const thinking = allowed.includes(preferred) ? preferred : allowed[0];
+    return thinking ? { model, thinking } : { model };
+  };
+  return {
+    id: modelStartOptionId,
+    schema: modelSchema,
+    selectable: () => choice.selectable,
+    defaultValue: () => ({ ...resolved(choice.defaultModel, undefined) }),
+    accept: (value) => {
+      const { model, thinking } = value as unknown as ModelStartOptionValue;
+      return { ...resolved(model, thinking) };
+    },
+    describe: (value) => {
+      const { model } = value as unknown as ModelStartOptionValue;
+      return {
+        kind: "model",
+        provider: choice.provider,
+        options: [...choice.options],
+        thinkingOptions: [...choice.thinkingOptionsFor(model)],
+      };
+    },
+  };
+};
+
+export const systemPromptStartOption = (catalog: () => SystemPromptCatalog): StartOptionContribution => ({
+  id: systemPromptStartOptionId,
+  schema: systemPromptSchema,
+  selectable: () => catalog().mode === "selectable" && catalog().options.length > 0,
+  defaultValue: () => ({ promptIds: [...catalog().defaultIds], shareWithAgents: catalog().shareDefault }),
+  accept: (value) => {
+    const { promptIds, shareWithAgents } = value as unknown as SystemPromptStartOptionValue;
+    const current = catalog();
+    for (const promptId of promptIds) {
+      if (!current.options.some((option) => option.id === promptId)) {
+        throw new DomainError("prompt-unknown", `Der Systemprompt ${promptId} ist nicht konfiguriert.`, 404);
+      }
+    }
+    const duplicate = promptIds.find((id, index) => promptIds.indexOf(id) !== index);
+    if (duplicate) throw new DomainError("prompt-duplicate", `Der Systemprompt ${duplicate} steht doppelt.`, 400);
+    return { promptIds: [...promptIds], shareWithAgents };
+  },
+  describe: () => {
+    const current = catalog();
+    return {
+      kind: "system-prompt",
+      mode: current.mode,
+      options: current.options.map((option) => ({ id: option.id, label: option.label, text: option.text })),
+    };
+  },
+});
+
+export interface ProductStartOptionSources {
+  modelChoice: ModelChoice;
+  coordinatorThinking: ThinkingLevel | (() => ThinkingLevel);
+  systemPrompts: () => SystemPromptCatalog;
+}
+
+export const productStartOptions = (sources: ProductStartOptionSources): StartOptionContribution[] => [
+  ...(sources.systemPrompts().options.length > 0 ? [systemPromptStartOption(sources.systemPrompts)] : []),
+  modelStartOption(sources.modelChoice, sources.coordinatorThinking),
+];

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

@@ -0,0 +1,68 @@
+import { readFile } from "node:fs/promises";
+import Handlebars from "handlebars";
+import {
+  PromptContributionRegistry,
+  type PromptContribution,
+  type PromptRenderContext,
+} from "@aicontainer/ragents";
+import { selectedSystemPrompts, type SystemPromptCatalog } from "./system-prompts.js";
+
+export const handlebarsPrompt = (
+  id: string,
+  order: number,
+  file: string,
+  values: Readonly<Record<string, unknown>> = {},
+): PromptContribution => {
+  let template: Promise<Handlebars.TemplateDelegate> | undefined;
+  return {
+    id,
+    order,
+    render: async (context) => {
+      template ??= readFile(file, "utf8").then((source) => Handlebars.compile(source));
+      return (await template)({ ...PromptContributionRegistry.handlebarsContext(context), ...values });
+    },
+  };
+};
+
+export const boundToTools = (
+  contribution: PromptContribution,
+  ...toolNames: readonly string[]
+): PromptContribution => {
+  if (toolNames.length === 0) {
+    throw new Error(`Der Prompt-Beitrag ${contribution.id} nennt kein Werkzeug, an das er gebunden ist`);
+  }
+  return { ...contribution, delivery: contribution.delivery ?? "on-demand", requiresTools: toolNames };
+};
+
+const optionTemplates = new Map<string, Promise<Handlebars.TemplateDelegate>>();
+
+const renderOption = async (file: string, context: PromptRenderContext): Promise<string> => {
+  const cached = optionTemplates.get(file)
+    ?? readFile(file, "utf8").then((source) => Handlebars.compile(source));
+  optionTemplates.set(file, cached);
+  return (await cached)(PromptContributionRegistry.handlebarsContext(context));
+};
+
+export const renderSystemPromptOption = async (
+  catalog: SystemPromptCatalog,
+  context: PromptRenderContext,
+): Promise<string> => {
+  const texts = await Promise.all(
+    selectedSystemPrompts(catalog, context.systemPromptIds).map((option) => renderOption(option.file, context)));
+  return texts.map((text) => text.trim()).filter(Boolean).join("\n\n");
+};
+
+export const systemPromptSelectionPromptIds = new Set<string>();
+
+export const systemPromptSelectionPrompt = (
+  id: string,
+  order: number,
+  catalog: SystemPromptCatalog,
+): PromptContribution => {
+  systemPromptSelectionPromptIds.add(id);
+  return {
+    id,
+    order,
+    render: (context) => renderSystemPromptOption(catalog, context),
+  };
+};

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

@@ -0,0 +1,85 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { readZipEntries, readZipNames } from "./zip.js";
+
+export { readZipNames };
+
+export type ProvisionState =
+  | { readonly kind: "ready" }
+  | { readonly kind: "gap"; readonly name: string; readonly instruction: string; readonly installable: boolean };
+
+/** Was ein Plugin in `provision.ts` exportiert: der Werkzeugordner ist sein einziger Ablageort. */
+export interface PluginProvision {
+  readonly check: (target: string) => Promise<ProvisionState>;
+  readonly apply: (target: string, log: (line: string) => void) => Promise<void>;
+}
+
+export const provisionReady: ProvisionState = { kind: "ready" };
+
+export const provisionGap = (name: string, instruction: string, installable: boolean): ProvisionState =>
+  ({ kind: "gap", name, instruction, installable });
+
+export const isPluginProvision = (value: unknown): value is PluginProvision =>
+  typeof value === "object" && value !== null
+  && typeof (value as PluginProvision).check === "function"
+  && typeof (value as PluginProvision).apply === "function";
+
+export type ArchiveDownload = (url: string) => Promise<Buffer>;
+
+export const downloadArchive: ArchiveDownload = async (url) => {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`${url} kommt nicht an: ${response.status} ${response.statusText}`);
+  return Buffer.from(await response.arrayBuffer());
+};
+
+/** Legt die Einträge unterhalb von `prefix` als frischen Ordner `directory` im Werkzeugordner ab. */
+export const unpackArchive = async (
+  archive: Buffer,
+  prefix: string,
+  target: string,
+  directory: string,
+): Promise<number> => {
+  const entries = readZipEntries(archive, (name) => name.startsWith(prefix));
+  if (entries.length === 0) throw new Error(`Das Archiv enthält keine Einträge unter ${prefix}`);
+  const destination = path.join(target, directory);
+  await rm(destination, { recursive: true, force: true });
+  for (const entry of entries) {
+    const relative = entry.name.slice(prefix.length).split("/");
+    if (relative.some((segment) => segment === "" || segment === "." || segment === "..")) {
+      throw new Error(`Der Archiveintrag ${entry.name} verlässt den Werkzeugordner`);
+    }
+    const file = path.join(destination, ...relative);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, entry.content);
+  }
+  return entries.length;
+};
+
+const STAMP_FILE = "provisioned.json";
+
+export const readProvisionStamp = async (target: string): Promise<string | undefined> => {
+  const raw = await readFile(path.join(target, STAMP_FILE), "utf8").catch(() => undefined);
+  if (raw === undefined) return undefined;
+  const parsed = JSON.parse(raw) as { version?: unknown };
+  return typeof parsed.version === "string" ? parsed.version : undefined;
+};
+
+export const writeProvisionStamp = async (target: string, version: string): Promise<void> => {
+  await mkdir(target, { recursive: true });
+  await writeFile(path.join(target, STAMP_FILE), `${JSON.stringify({ version }, null, 2)}\n`);
+};
+
+const run = promisify(execFile);
+
+/** Die Hauptversionen der installierten .NET-Laufzeiten, oder undefined, wenn es kein dotnet gibt. */
+export const dotnetRuntimeMajors = async (): Promise<readonly number[] | undefined> => {
+  const output = await run("dotnet", ["--list-runtimes"], { maxBuffer: 4 * 1024 * 1024 }).catch(() => undefined);
+  if (!output) return undefined;
+  const majors = [...output.stdout.matchAll(/^Microsoft\.NETCore\.App (\d+)\./gm)].map((match) => Number(match[1]));
+  return [...new Set(majors)].sort((left, right) => left - right);
+};
+
+export const DOTNET_INSTRUCTION = "dotnet fehlt auf diesem Rechner; das .NET-SDK von https://dotnet.microsoft.com/download "
+  + "installieren und dafür sorgen, dass dotnet im PATH steht";

package/apps/server/src/plugin-support/run-scripts.ts

@@ -0,0 +1,88 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import type { ActorProgramFile, StartEntryContribution } from "@aicontainer/ragents";
+import { flag, frontMatterOf, numberOf, tagsOf } from "./front-matter.js";
+
+export type ScriptStartEntry = Extract<StartEntryContribution, { action: "script" }>;
+
+const PACKAGE_NAME = /^[a-z0-9][a-z0-9-]*$/;
+const RUN_FIELDS = ["title", "description", "order", "guide", "tags", "coordinator"];
+
+const requiredFile = (directory: string, name: string): string => {
+  const file = path.join(directory, name);
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`Dem Run-Script ${directory} fehlt die Datei ${name}`);
+  return file;
+};
+
+const packageFiles = (directory: string, relative = ""): ActorProgramFile[] =>
+  readdirSync(path.join(directory, relative), {withFileTypes: true})
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .flatMap((entry) => {
+      if (["node_modules", "dist"].includes(entry.name) || entry.name.startsWith(".")) return [];
+      if (!relative && ["actors", "RUN.md"].includes(entry.name)) return [];
+      const filePath = path.posix.join(relative, entry.name);
+      if (entry.isDirectory()) return packageFiles(directory, filePath);
+      if (!entry.isFile()) throw new Error(`${directory}: ${filePath} ist keine reguläre Paketdatei`);
+      return [{path: filePath, content: readFileSync(path.join(directory, filePath), "utf8")}];
+    });
+
+const filesOf = (directory: string): ActorProgramFile[] => {
+  requiredFile(directory, "package.json");
+  return packageFiles(directory);
+};
+
+const runScriptFrom = (directory: string, name: string, id: string): ScriptStartEntry => {
+  if (!PACKAGE_NAME.test(name))
+    throw new Error(`${directory}: der Ordnername ${name} ist kein Handle (Kleinbuchstaben, Ziffern, Bindestrich)`);
+  const runFile = requiredFile(directory, "RUN.md");
+  const {fields} = frontMatterOf(runFile, readFileSync(runFile, "utf8"), "title und description");
+  const unknown = [...fields.keys()].filter((key) => !RUN_FIELDS.includes(key));
+  if (unknown.length > 0) throw new Error(`${runFile}: unbekannte Kopfzeilen ${unknown.join(", ")}`);
+  const title = fields.get("title");
+  const description = fields.get("description");
+  if (!title) throw new Error(`${runFile}: title fehlt`);
+  if (!description) throw new Error(`${runFile}: description fehlt`);
+  const order = numberOf(runFile, "order", fields.get("order"));
+  const guide = fields.get("guide");
+  const tags = tagsOf(runFile, fields.get("tags"));
+  const programsDirectory = path.join(directory, "actors");
+  const programsStats = statSync(programsDirectory, {throwIfNoEntry: false});
+  if (programsStats && !programsStats.isDirectory()) throw new Error(`${programsDirectory} muss ein Verzeichnis sein`);
+  const programs = programsStats ? readdirSync(programsDirectory, {withFileTypes: true})
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((entry) => {
+      if (!entry.isDirectory() || !PACKAGE_NAME.test(entry.name))
+        throw new Error(`${programsDirectory}: ${entry.name} ist kein Actor-Programm-Ordner`);
+      return {name: entry.name, files: filesOf(path.join(programsDirectory, entry.name))};
+    }) : [];
+  return {
+    id, action: "script", title, description,
+    ...(order !== undefined ? {order} : {}),
+    ...(guide ? {guide} : {}),
+    ...(tags !== undefined ? {tags} : {}),
+    script: {
+      handle: name,
+      coordinator: flag(runFile, "coordinator", fields.get("coordinator"), true),
+      files: filesOf(directory),
+      programs,
+    },
+  };
+};
+
+export const runScriptsFromDirectory = (directory: string, idPrefix: string): readonly ScriptStartEntry[] => {
+  const resolved = path.resolve(directory);
+  let entries;
+  try { entries = readdirSync(resolved, {withFileTypes: true}); }
+  catch (error) { throw new Error(`Das Run-Script-Verzeichnis ${resolved} ist nicht lesbar (${error instanceof Error ? error.message : String(error)})`); }
+  const packages = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  const stray = entries.filter((entry) => !entry.isDirectory()).map((entry) => entry.name);
+  if (stray.length > 0) throw new Error(`${resolved} enthält Dateien statt Run-Script-Ordner: ${stray.join(", ")}`);
+  if (packages.length === 0) throw new Error(`${resolved} enthält keinen Run-Script-Ordner`);
+  return packages.map((name) => runScriptFrom(path.join(resolved, name), name, `${idPrefix}.${name}`));
+};
+
+export const runScriptFromDirectory = (directory: string): ScriptStartEntry => {
+  if (!path.isAbsolute(directory)) throw new Error("Das Run-Script-Paket braucht einen absoluten Serverdateipfad");
+  const resolved = path.resolve(directory);
+  return runScriptFrom(resolved, path.basename(resolved), `local.${path.basename(resolved)}`);
+};

package/apps/server/src/plugin-support/shell-platform.ts

@@ -0,0 +1,21 @@
+import type { PromptContribution } from "@aicontainer/ragents";
+import { shellPlatformText } from "@aicontainer/workspace-executor";
+import { boundToTools } from "./prompt.js";
+
+export { shellPlatformText };
+
+export const shellPlatformChapter = (platform: NodeJS.Platform): string =>
+  `## Shell platform\n\n${shellPlatformText(platform)}`;
+
+/** Ohne Angabe gilt die Plattform des Servers; `chapterFor` nennt die des Executors, der den Run ausführt. */
+export const shellPlatformPrompt = (
+  id: string,
+  order: number,
+  chapterFor?: (runId: string) => string,
+): PromptContribution => boundToTools({
+  id,
+  order,
+  delivery: "initial",
+  render: () => shellPlatformChapter(process.platform),
+  ...(chapterFor ? { renderForRun: chapterFor } : {}),
+}, "bash");

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

@@ -0,0 +1,97 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "@aicontainer/agent";
+import type { StartEntryContribution } from "@aicontainer/ragents";
+import { flag, FRONT_MATTER, numberOf, tagsOf } from "./front-matter.js";
+import type { DeclaredEnvironment } from "./plugin-config.js";
+
+export type SkillStartEntry = Extract<StartEntryContribution, { action: "skill" }>;
+
+export interface FolderSkills {
+  readonly startEntries: readonly SkillStartEntry[];
+  readonly paths: readonly string[];
+}
+
+export const skillEnvDescriptors = [
+  { key: "SKILLS_DIR", source: "environment" },
+] as const;
+
+type SkillEnvironment = DeclaredEnvironment<(typeof skillEnvDescriptors)[number]["key"]>;
+
+const skillStartFrom = (directory: string, idPrefix: string): SkillStartEntry | undefined => {
+  const file = path.join(directory, "SKILL.md");
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`Dem Skill ${directory} fehlt die SKILL.md`);
+  const raw = readFileSync(file, "utf8");
+  if (!FRONT_MATTER.test(raw)) throw new Error(`${file}: es fehlt der ---Kopf mit name und description`);
+  const { frontmatter, body } = parseFrontmatter(raw);
+  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) throw new Error(`${file}: Kopf muss ein Objekt sein`);
+  const metadata = ["license", "compatibility", "metadata", "allowed-tools"];
+  const fields = new Map(Object.entries(frontmatter).filter(([key]) => !metadata.includes(key)).map(([key, value]) => {
+    const flagField = ["start", "disable-model-invocation", "user-invokable"].includes(key);
+    if (flagField && typeof value !== "boolean") throw new Error(`${file}: ${key} muss true oder false sein`);
+    if (value === null) return [key, ""];
+    if (typeof value !== "string" && !(flagField && typeof value === "boolean") && !(key === "order" && typeof value === "number")) {
+      throw new Error(`${file}: ${key} hat einen ungültigen Wert`);
+    }
+    return [key, String(value)];
+  }));
+  const allowed = ["name", "description", "start", "title", "category", "order", "tags", "guide", "prompt", "disable-model-invocation", "user-invokable"];
+  const unknown = [...fields.keys()].filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) throw new Error(`${file}: unbekannte Kopfzeilen ${unknown.join(", ")}`);
+  const name = fields.get("name");
+  if (!name) throw new Error(`${file}: name fehlt`);
+  if (name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new Error(`${file}: name ist kein gültiger Skillname`);
+  if (name !== path.basename(directory)) throw new Error(`${file}: name muss dem Skill-Ordner entsprechen`);
+  const description = fields.get("description");
+  if (!description) throw new Error(`${file}: description fehlt`);
+  if (!body.trim()) throw new Error(`${file}: Skill-Anleitung ist leer`);
+  flag(file, "disable-model-invocation", fields.get("disable-model-invocation"));
+  flag(file, "user-invokable", fields.get("user-invokable"));
+  const order = numberOf(file, "order", fields.get("order"));
+  const tags = tagsOf(file, fields.get("tags"));
+  if (!flag(file, "start", fields.get("start"))) return undefined;
+  const title = fields.get("title");
+  if (!title) throw new Error(`${file}: title fehlt`);
+  const category = fields.get("category");
+  if (!category) throw new Error(`${file}: category fehlt`);
+  const prompt = fields.get("prompt") ?? body.trim();
+  if (!prompt.trim()) throw new Error(`${file}: prompt ist leer`);
+  const guide = fields.get("guide");
+  if (guide !== undefined && !guide) throw new Error(`${file}: guide ist leer`);
+  return {
+    id: `${idPrefix}.${name}`,
+    action: "skill",
+    skill: name,
+    title,
+    description,
+    category,
+    prompt,
+    ...(order !== undefined ? { order } : {}),
+    ...(tags !== undefined ? { tags } : {}),
+    ...(guide !== undefined ? { guide } : {}),
+  };
+};
+
+export const skillsFromDirectory = (directory: string, idPrefix: string): FolderSkills => {
+  const resolved = path.resolve(directory);
+  let entries;
+  try {
+    entries = readdirSync(resolved, { withFileTypes: true });
+  } catch (error) {
+    throw new Error(`Das Skill-Verzeichnis ${resolved} ist nicht lesbar (${error instanceof Error ? error.message : String(error)})`);
+  }
+  const stray = entries.filter((entry) => !entry.isDirectory()).map((entry) => entry.name);
+  if (stray.length > 0) throw new Error(`${resolved} enthält Dateien statt Skill-Ordner: ${stray.join(", ")}`);
+  const paths = entries.map((entry) => path.join(resolved, entry.name)).sort();
+  if (paths.length === 0) throw new Error(`${resolved} enthält keinen Skill-Ordner`);
+  const startEntries = paths.flatMap((skillPath) => {
+    const entry = skillStartFrom(skillPath, idPrefix);
+    return entry ? [entry] : [];
+  });
+  return { startEntries, paths };
+};
+
+export const skillsFromEnvironment = (env: SkillEnvironment, idPrefix: string): FolderSkills => {
+  const directory = env.optional("SKILLS_DIR");
+  return directory ? skillsFromDirectory(directory, idPrefix) : { startEntries: [], paths: [] };
+};

package/apps/server/src/plugin-support/start-entries-contract.ts

@@ -0,0 +1,71 @@
+export type StartEntryAction = "skill" | "script";
+
+export interface StartEntryBase {
+  id: string;
+  owner: string;
+  title: string;
+  description: string;
+  order?: number;
+  guide?: string;
+  tags?: readonly string[];
+}
+
+/** One entry of the start surface as GET /api/plugins publishes it; a script entry never carries its source. */
+export type StartEntry = StartEntryBase & (
+  | { action: "skill"; skill: string; category: string; prompt: string }
+  | { action: "script"; coordinator: boolean }
+);
+
+export type SkillStartEntry = Extract<StartEntry, { action: "skill" }>;
+export type ScriptStartEntry = Extract<StartEntry, { action: "script" }>;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+
+const BASE_FIELDS = ["id", "owner", "title", "description", "order", "guide", "tags", "action"];
+
+const invalid = (detail: string): Error => new Error(`Die Plugin-Konfiguration enthält einen ungültigen Einstieg: ${detail}`);
+
+export const startEntryFrom = (value: unknown): StartEntry => {
+  if (!isRecord(value)) throw invalid("kein Objekt");
+  if (!text(value.id)) throw invalid("id fehlt");
+  const id = value.id;
+  if (!text(value.owner) || !text(value.title) || !text(value.description)) throw invalid(`${id}: owner, title und description sind Pflicht`);
+  if (value.order !== undefined && typeof value.order !== "number") throw invalid(`${id}: order ist keine Zahl`);
+  if (value.guide !== undefined && !text(value.guide)) throw invalid(`${id}: guide ist leer`);
+  if (value.tags !== undefined && (!Array.isArray(value.tags)
+    || value.tags.some((tag) => !text(tag) || tag !== tag.trim())
+    || new Set(value.tags).size !== value.tags.length)) {
+    throw invalid(`${id}: tags müssen eindeutige, nicht leere Schlagworte sein`);
+  }
+  const base: StartEntryBase = {
+    id,
+    owner: value.owner,
+    title: value.title,
+    description: value.description,
+    ...(value.order !== undefined ? { order: value.order } : {}),
+    ...(value.guide !== undefined ? { guide: value.guide } : {}),
+    ...(value.tags !== undefined ? { tags: [...value.tags] as string[] } : {}),
+  };
+  const allowed = (extra: readonly string[]) => {
+    const unknown = Object.keys(value).filter((field) => !BASE_FIELDS.includes(field) && !extra.includes(field));
+    if (unknown.length > 0) throw invalid(`${id}: unbekannte Felder ${unknown.join(", ")}`);
+  };
+  switch (value.action) {
+    case "skill": {
+      allowed(["skill", "prompt", "category"]);
+      if (!text(value.skill)) throw invalid(`${id}: skill fehlt`);
+      if (!text(value.category) || !value.category.trim() || value.category !== value.category.trim()) throw invalid(`${id}: category muss ein einzelner nicht leerer Text sein`);
+      if (!text(value.prompt) || !value.prompt.trim()) throw invalid(`${id}: prompt fehlt oder ist leer`);
+      return { ...base, action: "skill", skill: value.skill, category: value.category, prompt: value.prompt };
+    }
+    case "script":
+      allowed(["coordinator"]);
+      if (typeof value.coordinator !== "boolean") throw invalid(`${id}: coordinator muss true oder false sein`);
+      return { ...base, action: "script", coordinator: value.coordinator };
+    default:
+      throw invalid(`${id}: unbekannte Aktion ${String(value.action)}; gültig sind skill und script`);
+  }
+};

package/apps/server/src/plugin-support/start-options-contract.ts

@@ -0,0 +1,65 @@
+export const systemPromptStartOptionId = "ragents.system-prompt";
+
+export const modelStartOptionId = "ragents.model";
+
+export interface StartOptionState {
+  id: string;
+  owner: string;
+  value: unknown;
+  presentation: unknown;
+  selectable: boolean;
+  locked: boolean;
+}
+
+export interface ChoicePresentationOption {
+  value: string;
+  label: string;
+  hint?: string;
+}
+
+export interface ChoicePresentation {
+  kind: "choice";
+  label: string;
+  options: readonly ChoicePresentationOption[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isChoiceOption = (value: unknown): value is ChoicePresentationOption =>
+  isRecord(value)
+  && typeof value.value === "string" && value.value.length > 0
+  && typeof value.label === "string" && value.label.length > 0
+  && (value.hint === undefined || typeof value.hint === "string");
+
+export const choicePresentationFrom = (presentation: unknown, optionId: string): ChoicePresentation | undefined => {
+  if (!isRecord(presentation)) throw new Error(`Die Startoption ${optionId} liefert keine Darstellung`);
+  if (presentation.kind !== "choice") return undefined;
+  if (typeof presentation.label !== "string" || !presentation.label) {
+    throw new Error(`Die Auswahl-Darstellung der Startoption ${optionId} hat kein label`);
+  }
+  if (!Array.isArray(presentation.options) || !presentation.options.every(isChoiceOption)) {
+    throw new Error(`Die Auswahl-Darstellung der Startoption ${optionId} braucht options aus value und label`);
+  }
+  return { kind: "choice", label: presentation.label, options: presentation.options };
+};
+
+export const startOptionStateFrom = (value: unknown): StartOptionState => {
+  if (!isRecord(value)
+    || typeof value.id !== "string" || !value.id
+    || typeof value.owner !== "string" || !value.owner
+    || !("value" in value)
+    || !("presentation" in value)
+    || typeof value.selectable !== "boolean"
+    || typeof value.locked !== "boolean") {
+    throw new Error("Die Startoption entspricht nicht dem erwarteten Format");
+  }
+  return {
+    id: value.id,
+    owner: value.owner,
+    value: value.value,
+    presentation: value.presentation,
+    selectable: value.selectable,
+    locked: value.locked,
+  };
+};