@schlenkr/ragents 0.1.0

package/plugins/ragents.product/web/ModelControl.tsx

@@ -0,0 +1,81 @@
+import { useMemo } from "react";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@aicontainer/web/ui";
+import { thinkingLabel } from "@aicontainer/web/lib/labels";
+import type { StartOptionControlContext } from "@aicontainer/web/PluginRegistry";
+
+interface ModelPresentation {
+  provider: string;
+  options: readonly string[];
+  thinkingOptions: readonly string[];
+}
+
+interface ModelValue {
+  model: string;
+  thinking?: string;
+}
+
+const isStringList = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((entry) => typeof entry === "string");
+
+const modelPresentationFrom = (presentation: unknown, optionId: string): ModelPresentation => {
+  const raw = presentation as Record<string, unknown> | null;
+  if (typeof raw !== "object" || raw === null || raw.kind !== "model"
+    || typeof raw.provider !== "string" || !isStringList(raw.options) || !isStringList(raw.thinkingOptions)) {
+    throw new Error(`Die Startoption ${optionId} liefert keine Modell-Darstellung`);
+  }
+  return { provider: raw.provider, options: raw.options, thinkingOptions: raw.thinkingOptions };
+};
+
+const modelValueFrom = (value: unknown, optionId: string): ModelValue => {
+  const raw = value as Record<string, unknown> | null;
+  if (typeof raw !== "object" || raw === null || typeof raw.model !== "string"
+    || (raw.thinking !== undefined && typeof raw.thinking !== "string")) {
+    throw new Error(`Der Wert der Startoption ${optionId} ist keine Modellwahl`);
+  }
+  return { model: raw.model, ...(typeof raw.thinking === "string" ? { thinking: raw.thinking } : {}) };
+};
+
+const modelLabel = (provider: string, model: string) => provider ? `${provider}/${model}` : model;
+
+const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
+
+const errorClass = "text-[0.75rem] text-destructive";
+
+export function ModelControl({ disabled, error, option, setValue }: StartOptionControlContext) {
+  const parsed = useMemo(() => {
+    try {
+      return { presentation: modelPresentationFrom(option.presentation, option.id), value: modelValueFrom(option.value, option.id) };
+    } catch (cause) {
+      return { message: messageOf(cause) };
+    }
+  }, [option]);
+
+  if ("message" in parsed) return <p className={errorClass} role="alert">{parsed.message}</p>;
+  const { presentation, value } = parsed;
+
+  const chooseModel = (model: string) => {
+    void setValue({ model });
+  };
+
+  const chooseThinking = (thinking: string) => {
+    void setValue({ model: value.model, thinking });
+  };
+
+  const modelOptions = presentation.options.map((model) => ({ value: model, label: modelLabel(presentation.provider, model) }));
+  const thinkingOptions = presentation.thinkingOptions.map((level) => ({ value: level, label: thinkingLabel(level) }));
+  return (
+    <div className="grid flex-1 min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1.5">
+      <Select disabled={disabled} items={modelOptions} value={value.model} onValueChange={(model) => { if (model !== null) chooseModel(model); }}>
+        <SelectTrigger aria-label="Modell" className="min-w-0 max-w-full" size="sm"><SelectValue /></SelectTrigger>
+        <SelectContent>{modelOptions.map((option) => <SelectItem key={option.value} value={option.value}>{option.label}</SelectItem>)}</SelectContent>
+      </Select>
+      {presentation.thinkingOptions.length > 0 && (
+        <Select disabled={disabled} items={thinkingOptions} value={value.thinking ?? ""} onValueChange={(thinking) => { if (thinking !== null) chooseThinking(thinking); }}>
+          <SelectTrigger aria-label="Reasoning" className="min-w-0 max-w-full" size="sm"><SelectValue /></SelectTrigger>
+          <SelectContent>{thinkingOptions.map((option) => <SelectItem key={option.value} value={option.value}>{option.label}</SelectItem>)}</SelectContent>
+        </Select>
+      )}
+      {error && <p className={`${errorClass} col-span-full`} role="alert">{error}</p>}
+    </div>
+  );
+}

package/plugins/ragents.product/web/ProductModelSettings.tsx

@@ -0,0 +1,131 @@
+import { useEffect, useRef, useState } from "react";
+import { useAccess } from "@aicontainer/web/AccessContext";
+import { Alert, AlertAction, AlertDescription, Button, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@aicontainer/web/ui";
+import { thinkingLabel } from "@aicontainer/web/lib/labels";
+import type { ProductModelDraft, ProductModelSettings as Settings } from "../model-settings-contract";
+import { modelDraftOf, requestProductModelSettings } from "./model-settings";
+import { modelDefaultsChangedEvent } from "@aicontainer/web/model-settings-events";
+
+const profileLabels: Record<string, { title: string; description: string }> = {
+  coordinator: { title: "Run-Koordinator", description: "Die Vorgabe beim Start einer neuen Unterhaltung." },
+  relay: { title: "Vermittler", description: "Agenten, die Nachrichten und Ergebnisse weitergeben." },
+  standard: { title: "Agenten", description: "Die Vorgabe für weitere Agenten im Run." },
+  reviewer: { title: "Prüfung", description: "Die Vorgabe für Agenten mit Prüfauftrag." },
+};
+
+type LoadState = { status: "loading" } | { status: "failed"; error: string }
+  | { status: "ready"; settings: Settings };
+const messageOf = (cause: unknown) => cause instanceof Error ? cause.message : String(cause);
+
+const noteClass = "text-[0.8rem] leading-[1.5] text-muted-foreground";
+const triggerClass = "w-full min-w-0 max-w-full";
+
+export function ProductModelSettings({ pluginId }: { pluginId: string }) {
+  const access = useAccess();
+  const readable = access.can("settings.read");
+  const writable = access.can("settings.write");
+  const [state, setState] = useState<LoadState>({ status: "loading" });
+  const [draft, setDraft] = useState<ProductModelDraft>();
+  const [pending, setPending] = useState(false);
+  const saving = useRef(false);
+  const [error, setError] = useState<string>();
+  const [notice, setNotice] = useState<string>();
+  const [retry, setRetry] = useState(0);
+  const dirty = state.status === "ready" && draft !== undefined
+    && JSON.stringify(draft) !== JSON.stringify(modelDraftOf(state.settings));
+  useEffect(() => {
+    const refresh = () => { if (!dirty && !saving.current) setRetry((value) => value + 1); };
+    window.addEventListener(modelDefaultsChangedEvent, refresh);
+    return () => window.removeEventListener(modelDefaultsChangedEvent, refresh);
+  }, [dirty]);
+  useEffect(() => {
+    if (!readable) return;
+    const controller = new AbortController();
+    void requestProductModelSettings(pluginId, { signal: controller.signal }).then((settings) => {
+      if (controller.signal.aborted) return;
+      setState({ status: "ready", settings });
+      setDraft(modelDraftOf(settings));
+    }).catch((cause: unknown) => {
+      if (!controller.signal.aborted) setState({ status: "failed", error: messageOf(cause) });
+    });
+    return () => controller.abort();
+  }, [pluginId, readable, retry]);
+
+  if (!readable) return null;
+  if (state.status === "failed") return <Alert variant="destructive">
+    <AlertDescription>{state.error}</AlertDescription>
+    <AlertAction><Button onClick={() => setRetry((value) => value + 1)} size="sm" variant="outline">Erneut laden</Button></AlertAction>
+  </Alert>;
+  if (state.status !== "ready" || !draft) return <p role="status">Modellvorgaben werden geladen ...</p>;
+  const { settings } = state;
+  const change = (name: string, model: string, thinking: ProductModelDraft["profiles"][number]["thinking"]) => {
+    setDraft({ profiles: draft.profiles.map((profile) => profile.name === name ? { ...profile, model, thinking } : profile) });
+    setError(undefined);
+    setNotice(undefined);
+  };
+  const save = async () => {
+    if (!writable || saving.current || !dirty) return;
+    saving.current = true;
+    setPending(true);
+    setError(undefined);
+    setNotice(undefined);
+    try {
+      const saved = await requestProductModelSettings(pluginId, { draft });
+      setState({ status: "ready", settings: saved });
+      setDraft(modelDraftOf(saved));
+      setNotice("Vorgaben gespeichert. Sie gelten für neue Actors und noch nicht gestartete Runs.");
+      window.dispatchEvent(new Event(modelDefaultsChangedEvent));
+    } catch (cause) { setError(messageOf(cause)); }
+    finally { saving.current = false; setPending(false); }
+  };
+  return <form className="grid min-w-0 gap-4.5" aria-label="Modellvorgaben für neue Runs und Agenten" onSubmit={(event) => {
+    event.preventDefault();
+    void save();
+  }}>
+    <p className={noteClass}>Für dieses Produktprofil gespeichert. Bereits angelegte Actors behalten ihr Modell.
+      Eine ausdrücklich gewählte Modellauswahl im Run hat Vorrang.</p>
+    {!writable && <p className={noteClass}>Du hast Lesezugriff auf diese Einstellungen.</p>}
+    <div className="grid gap-4">
+      {settings.profiles.map((profile) => {
+        const value = draft.profiles.find((entry) => entry.name === profile.name)!;
+        const metadata = settings.models.find((model) => model.provider === profile.provider && model.id === value.model)!;
+        const label = profileLabels[profile.name] ?? { title: profile.name, description: profile.description };
+        const modelOptions = settings.models.filter((model) => model.provider === profile.provider).map((model) => ({ value: model.id, label: model.label }));
+        const thinkingOptions = metadata.thinking.map((thinking) => ({ value: thinking, label: thinkingLabel(thinking) }));
+        return <fieldset className="min-w-0 border-t border-border-soft pt-4 first:border-t-0 first:pt-0" key={profile.name} disabled={!writable || pending}>
+          <legend className="float-left w-full text-[0.9rem] font-semibold">{label.title}</legend>
+          <p className="clear-both mt-0.5 mb-3 text-[0.8rem] text-muted-foreground">{label.description}</p>
+          <div className="grid grid-cols-[minmax(0,1fr)_minmax(125px,180px)] gap-3 max-sm:grid-cols-[minmax(0,1fr)]">
+            <Select disabled={!writable || pending} items={modelOptions} value={value.model}
+              onValueChange={(model) => {
+                if (model === null) return;
+                const next = settings.models.find((entry) => entry.id === model && entry.provider === profile.provider)!;
+                const thinking = next.thinking.includes(value.thinking) ? value.thinking : next.thinking[0]!;
+                change(profile.name, model, thinking);
+                if (thinking !== value.thinking) setNotice(`Für ${label.title} wurde die verfügbare Reasoning-Stufe ${thinkingLabel(thinking)} gewählt. Prüfe sie vor dem Speichern.`);
+              }}>
+              <SelectTrigger aria-label="Modell" className={triggerClass}><SelectValue /></SelectTrigger>
+              <SelectContent>{modelOptions.map((option) => <SelectItem key={option.value} value={option.value}>{option.label}</SelectItem>)}</SelectContent>
+            </Select>
+            <Select disabled={!writable || pending || metadata.thinking.length < 2} items={thinkingOptions} value={value.thinking}
+              onValueChange={(thinking) => {
+                const level = metadata.thinking.find((entry) => entry === thinking);
+                if (level) change(profile.name, value.model, level);
+              }}>
+              <SelectTrigger aria-label="Reasoning" className={triggerClass}><SelectValue /></SelectTrigger>
+              <SelectContent>{thinkingOptions.map((option) => <SelectItem key={option.value} value={option.value}>{option.label}</SelectItem>)}</SelectContent>
+            </Select>
+          </div>
+        </fieldset>;
+      })}
+    </div>
+    <div className="flex flex-wrap items-center gap-2.5">
+      <Button type="submit" disabled={!writable || pending || !dirty}>{pending ? "Wird gespeichert ..." : "Vorgaben speichern"}</Button>
+      {dirty && <Button disabled={pending} variant="outline" onClick={() => {
+        setDraft(modelDraftOf(settings)); setError(undefined); setNotice(undefined);
+      }}>Änderungen verwerfen</Button>}
+      <span className={`${noteClass} basis-full`} role="status">{notice ?? (dirty ? "Ungespeicherte Änderungen" : "")}</span>
+    </div>
+    {error && <Alert variant="destructive"><AlertDescription>{error}</AlertDescription></Alert>}
+  </form>;
+}

package/plugins/ragents.product/web/SystemPromptControl.tsx

@@ -0,0 +1,136 @@
+import { Checkbox, Toggle } from "@aicontainer/web/ui";
+import { ToolbarCopy, ToolbarItem, ToolbarLabel, ToolbarText } from "@aicontainer/web/Toolbar";
+import { useMemo, useState } from "react";
+import type { StartOptionBadgeContext, StartOptionControlContext } from "@aicontainer/web/PluginRegistry";
+
+interface SystemPromptOption {
+  id: string;
+  label: string;
+  text: string;
+}
+
+interface SystemPromptPresentation {
+  options: readonly SystemPromptOption[];
+}
+
+interface SystemPromptValue {
+  promptIds: readonly string[];
+  shareWithAgents: boolean;
+}
+
+const isPromptOption = (value: unknown): value is SystemPromptOption =>
+  typeof value === "object" && value !== null
+  && typeof (value as SystemPromptOption).id === "string"
+  && typeof (value as SystemPromptOption).label === "string"
+  && typeof (value as SystemPromptOption).text === "string";
+
+const presentationFrom = (presentation: unknown, optionId: string): SystemPromptPresentation => {
+  const raw = presentation as Record<string, unknown> | null;
+  if (typeof raw !== "object" || raw === null || raw.kind !== "system-prompt"
+    || !Array.isArray(raw.options) || !raw.options.every(isPromptOption)) {
+    throw new Error(`Die Startoption ${optionId} liefert keine Systemprompt-Darstellung`);
+  }
+  return { options: raw.options };
+};
+
+const valueFrom = (value: unknown, optionId: string): SystemPromptValue => {
+  const raw = value as Record<string, unknown> | null;
+  if (typeof raw !== "object" || raw === null
+    || !Array.isArray(raw.promptIds) || raw.promptIds.some((id) => typeof id !== "string")
+    || typeof raw.shareWithAgents !== "boolean") {
+    throw new Error(`Der Wert der Startoption ${optionId} ist keine Systemprompt-Auswahl`);
+  }
+  return { promptIds: raw.promptIds as string[], shareWithAgents: raw.shareWithAgents };
+};
+
+const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
+
+const errorClass = "text-[0.75rem] text-destructive";
+
+const parse = (option: StartOptionControlContext["option"]) => {
+  try {
+    return { presentation: presentationFrom(option.presentation, option.id), value: valueFrom(option.value, option.id) };
+  } catch (cause) {
+    return { message: messageOf(cause) };
+  }
+};
+
+export function SystemPromptControl({ disabled, error, option, setValue }: StartOptionControlContext) {
+  const [previewId, setPreviewId] = useState<string | undefined>(undefined);
+  const parsed = useMemo(() => parse(option), [option]);
+  if ("message" in parsed) return <p className={errorClass} role="alert">{parsed.message}</p>;
+  const { presentation, value } = parsed;
+  const preview = presentation.options.find((entry) => entry.id === previewId);
+
+  const toggle = (wanted: string) => {
+    const next = value.promptIds.includes(wanted)
+      ? value.promptIds.filter((id) => id !== wanted)
+      : presentation.options.map((entry) => entry.id).filter((id) => id === wanted || value.promptIds.includes(id));
+    void setValue({ promptIds: next, shareWithAgents: value.shareWithAgents });
+  };
+
+  const share = (shareWithAgents: boolean) => {
+    void setValue({ promptIds: value.promptIds, shareWithAgents });
+  };
+
+  return (
+    <div className="flex flex-col items-start gap-2" onMouseLeave={() => setPreviewId(undefined)}>
+      <span className="text-[0.72rem] font-semibold text-muted-foreground">Systemprompts</span>
+      <div className="relative flex justify-center">
+        <div aria-label="Systemprompts" className="flex flex-wrap justify-center gap-2" role="group">
+          {presentation.options.map((entry) => (
+            <Toggle
+              disabled={disabled}
+              key={entry.id}
+              onBlur={() => setPreviewId(undefined)}
+              onFocus={() => setPreviewId(entry.id)}
+              onMouseEnter={() => setPreviewId(entry.id)}
+              onPressedChange={() => toggle(entry.id)}
+              pressed={value.promptIds.includes(entry.id)}
+              size="sm"
+              variant="outline"
+            >
+              {entry.label}
+            </Toggle>
+          ))}
+        </div>
+        {preview && <div className="absolute top-[calc(100%+6px)] left-1/2 z-3 max-h-[44vh] w-max max-w-[min(620px,78vw)] -translate-x-1/2 overflow-y-auto whitespace-pre-wrap rounded-xl border border-border bg-background px-3.5 py-3 text-left text-sm leading-[1.5] text-foreground shadow-pop" role="tooltip">{preview.text}</div>}
+      </div>
+      <label className="flex max-w-[34rem] cursor-pointer items-start gap-2 text-sm">
+        <Checkbox
+          checked={value.shareWithAgents}
+          className="mt-0.5"
+          disabled={disabled}
+          onCheckedChange={(checked) => share(checked)}
+        />
+        <span>
+          Auch an die Agenten weiterreichen
+          <span className="block text-[0.72rem] text-muted-foreground">
+            {value.shareWithAgents
+              ? "Erzeugte Agenten bekommen die Prompts zusätzlich. Plain-LLMs mit tools: [] bleiben ausgenommen."
+              : "Die Prompts gelten nur für den Koordinator."}
+          </span>
+        </span>
+      </label>
+      {error && <p className={errorClass} role="alert">{error}</p>}
+    </div>
+  );
+}
+
+export function SystemPromptBadge({ option }: StartOptionBadgeContext) {
+  if (!option.selectable || !option.locked) return null;
+  const parsed = parse(option);
+  if ("message" in parsed) return <ToolbarItem title={parsed.message}><ToolbarText>Systemprompts unlesbar</ToolbarText></ToolbarItem>;
+  const { presentation, value } = parsed;
+  const labels = presentation.options
+    .filter((entry) => value.promptIds.includes(entry.id))
+    .map((entry) => entry.label);
+  if (labels.length === 0) return null;
+  const scopeLabel = value.shareWithAgents ? "Koordinator und Agenten" : "nur Koordinator";
+  const text = labels.join(" + ");
+  return (
+    <ToolbarItem title={`Systemprompts: ${text} (${scopeLabel})`}>
+      <ToolbarCopy><ToolbarLabel>Systemprompts</ToolbarLabel><ToolbarText>{value.shareWithAgents ? `${text} + Agenten` : text}</ToolbarText></ToolbarCopy>
+    </ToolbarItem>
+  );
+}

package/plugins/ragents.product/web/index.tsx

@@ -0,0 +1,29 @@
+import {
+  chatDisplayPolicyFrom,
+  type WebPlugin,
+  type WebPluginDescriptor,
+} from "@aicontainer/web/PluginRegistry";
+import { productStartOptions } from "./start-options";
+import { ProductModelSettings } from "./ProductModelSettings";
+
+const ModelSettings = () => <ProductModelSettings pluginId="ragents.product" />;
+
+const basePlugin = (descriptor: WebPluginDescriptor): WebPlugin => ({
+  ...descriptor,
+  brand: {
+    title: "RAgents",
+  },
+  startOptions: productStartOptions,
+  settings: [{ id: "ragents.product.model-settings", label: "Neue Runs und Agenten", category: "models",
+    order: 20, readRight: "settings.read", Settings: ModelSettings }],
+});
+
+const descriptor: WebPluginDescriptor = { id: "ragents.product" };
+
+export const webPlugin: WebPlugin = {
+  ...basePlugin(descriptor),
+  activate: (config) => ({
+    ...basePlugin(descriptor),
+    chatDisplayPolicy: chatDisplayPolicyFrom(descriptor.id, config),
+  }),
+};

package/plugins/ragents.product/web/model-settings.ts

@@ -0,0 +1,39 @@
+import { rpc } from "@aicontainer/web/rpc";
+import { productModelSettingsContracts } from "@aicontainer/server/plugin-support/product-model-settings-contract";
+import type { ProductModelDraft, ProductModelSettings } from "../model-settings-contract";
+
+const record = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+
+export const productModelSettingsFrom = (value: unknown): ProductModelSettings => {
+  if (!record(value) || !Array.isArray(value.models) || !Array.isArray(value.profiles)
+    || !value.models.length || !value.profiles.length
+    || !value.models.every((model) => record(model) && text(model.id) && text(model.provider)
+      && text(model.label) && Array.isArray(model.thinking) && model.thinking.length > 0 && model.thinking.every(text))
+    || !value.profiles.every((profile) => record(profile) && text(profile.name) && typeof profile.description === "string"
+      && text(profile.provider) && text(profile.model) && text(profile.thinking))) {
+    throw new Error("Der Server hat ungültige Modellvorgaben geliefert.");
+  }
+  const settings = value as unknown as ProductModelSettings;
+  const names = settings.profiles.map((profile) => profile.name);
+  if (new Set(names).size !== names.length || settings.profiles.some((profile) => !settings.models.some((model) =>
+    model.id === profile.model && model.provider === profile.provider && model.thinking.includes(profile.thinking)))) {
+    throw new Error("Die Modellvorgaben passen nicht zum verfügbaren Modellkatalog.");
+  }
+  return settings;
+};
+
+export const modelDraftOf = (settings: ProductModelSettings): ProductModelDraft => ({
+  profiles: settings.profiles.map(({ name, model, thinking }) => ({ name, model, thinking })),
+});
+
+export async function requestProductModelSettings(pluginId: string, options: {
+  draft?: ProductModelDraft; signal?: AbortSignal;
+} = {}): Promise<ProductModelSettings> {
+  const contracts = productModelSettingsContracts(pluginId);
+  const result = options.draft
+    ? await rpc.call(contracts.save, { value: options.draft }, { signal: options.signal })
+    : await rpc.call(contracts.read, {}, { signal: options.signal });
+  return productModelSettingsFrom(result);
+}

package/plugins/ragents.product/web/start-options.tsx

@@ -0,0 +1,12 @@
+import type { StartOptionContribution } from "@aicontainer/web/PluginRegistry";
+import {
+  modelStartOptionId,
+  systemPromptStartOptionId,
+} from "@aicontainer/server/plugin-support/start-options-contract";
+import { ModelControl } from "./ModelControl";
+import { SystemPromptBadge, SystemPromptControl } from "./SystemPromptControl";
+
+export const productStartOptions: StartOptionContribution[] = [
+  { id: systemPromptStartOptionId, Control: SystemPromptControl, Badge: SystemPromptBadge },
+  { id: modelStartOptionId, placement: "composer", Control: ModelControl },
+];

package/plugins/ragents.profile-distribution/contract.ts

@@ -0,0 +1,38 @@
+import { Type, type Static } from "typebox";
+import { defineOperation } from "@aicontainer/ragents/src/rpc/contract";
+
+const pluginEntry = Type.Object({
+  id: Type.String({ minLength: 1 }),
+  source: Type.Union([Type.Literal("host"), Type.Literal("archive")], {
+    description: "host: der Client nimmt das Plugin aus seinem Host-Checkout; archive: das Plugin liegt im Archiv",
+  }),
+}, { additionalProperties: false });
+
+/** Im Archiv liegt das für dieses Profil gebaute Web unter diesem Ordner; der Client baut es nicht selbst. */
+export const CLIENT_WEB_FOLDER = "web";
+
+const description = Type.Object({
+  profile: Type.String({ minLength: 1, description: "Profilname; die Datei heißt ragents.config.<profil>.ts" }),
+  version: Type.String({ minLength: 64, maxLength: 64, description: "Stand des Archivs als SHA-256" }),
+  hostVersion: Type.String({ minLength: 40, maxLength: 40, description: "Git-Commit des Hosts, den der Client exakt braucht" }),
+  packageVersion: Type.String({ minLength: 1, description: "Fassung des npm-Pakets, die diesen Commit trägt; damit findet der Client die passende Installation" }),
+  file: Type.String({ minLength: 1, description: "Pfad der Profildatei innerhalb des Archivs" }),
+  web: Type.String({ minLength: 1, description: "Ordner des gebauten Webs innerhalb des Archivs; der Client setzt WEB_DIST_DIR darauf" }),
+  size: Type.Integer({ minimum: 0, description: "Archivgröße in Byte" }),
+  archivePath: Type.String({ minLength: 1, description: "HTTP-Pfad des Archivs auf diesem Server" }),
+  plugins: Type.Array(pluginEntry),
+}, { additionalProperties: false });
+
+export type ClientProfileDescription = Static<typeof description>;
+
+export const profileArchivePath = (version: string): string => `/profile/${version}.tar.gz`;
+
+export const profileDistributionContracts = {
+  describe: defineOperation({
+    id: "ragents.profile.describe",
+    description: "Das Client-Profil dieses Servers: Name, Stand, verlangte Host- und Paketfassung, Plugins und Archiv. Recht: profile.fetch.",
+    rights: ["profile.fetch"],
+    input: Type.Object({}, { additionalProperties: false }),
+    result: description,
+  }),
+};

package/plugins/ragents.profile-distribution/server/archive.ts

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { readdirSync, statSync, lstatSync } from "node:fs";
+import { copyFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { create as createTar } from "tar";
+import { hostConfigKeys } from "@aicontainer/server/config.js";
+import { isEnvironmentReference, isProvisionedReference } from "@aicontainer/server/config-definition.js";
+import { resolveAnonymousUser, resolveProfileUsers, SECRET_KEY_PATTERN } from "@aicontainer/server/config-file.js";
+import { discoverPluginIds } from "@aicontainer/server/profile/plugin-discovery.js";
+import { isPluginPath, PLUGIN_SERVER_FOLDER, pluginFolderFor, pluginIdOf, pluginsRoot } from "@aicontainer/server/plugin-support/plugins-root.js";
+import { CLIENT_WEB_FOLDER } from "../contract.js";
+
+export interface ClientProfilePlugin {
+  readonly id: string;
+  readonly source: "host" | "archive";
+  readonly folder: string;
+}
+
+export interface InspectedClientProfile {
+  readonly profile: string;
+  readonly source: string;
+  readonly root: string;
+  readonly file: string;
+  readonly plugins: readonly ClientProfilePlugin[];
+}
+
+export interface PackedClientProfile {
+  readonly archive: Buffer;
+  readonly version: string;
+  readonly entries: readonly string[];
+}
+
+const EXCLUDED_FOLDERS = new Set(["node_modules", "tests", ".git"]);
+const PROFILE_FILE = /^ragents\.config\.([a-z0-9]+(?:-[a-z0-9]+)*)\.ts$/;
+
+const hasServerEntry = (folder: string): boolean =>
+  ["index.ts", "index.js"].some((name) => statSync(path.join(folder, PLUGIN_SERVER_FOLDER, name), { throwIfNoEntry: false })?.isFile() === true);
+
+const commonRoot = (first: string, others: readonly string[]): string => {
+  let root = first;
+  for (const folder of others) {
+    while (folder !== root && !folder.startsWith(root + path.sep)) {
+      const parent = path.dirname(root);
+      if (parent === root) throw new Error(`Profildatei und Plugin ${folder} haben keinen gemeinsamen Ordner`);
+      root = parent;
+    }
+  }
+  return root;
+};
+
+const posixRelative = (root: string, target: string): string => path.relative(root, target).split(path.sep).join("/");
+
+// Jeder Name ist frei, damit ein Passwort- oder Token-Verweis auch ohne die Client-Umgebung prüfbar ist.
+const placeholderEnvironment: Readonly<Record<string, string | undefined>> = new Proxy({}, { get: () => "client-placeholder-value" });
+
+const checkSections = (source: string, raw: Record<string, unknown>, pluginIds: ReadonlySet<string>): void => {
+  for (const [section, value] of Object.entries(raw)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${source}: die Sektion ${section} ist kein Objekt`);
+    if (section !== "host" && !pluginIds.has(section)) throw new Error(`${source}: die Sektion ${section} gehört zu keinem Plugin aus host.PLUGINS`);
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      if (section === "host" && !hostConfigKeys.includes(key)) throw new Error(`${source}: host.${key} ist kein Host-Schlüssel`);
+      if (isEnvironmentReference(entry) || isProvisionedReference(entry)) continue;
+      if (SECRET_KEY_PATTERN.test(key)) throw new Error(`${source}: ${section}.${key} ist ein Secret und muss als env("...") stehen`);
+      const valid = typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean"
+        || (Array.isArray(entry) && entry.every((item) => typeof item === "string"));
+      if (!valid) throw new Error(`${source}: ${section}.${key} hat keinen gültigen Wert`);
+      if (typeof entry === "string" && /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(entry)) throw new Error(`${source}: ${section}.${key} verweist als Text auf die Umgebung; env("...") verwenden`);
+    }
+  }
+};
+
+/** Prüft die Client-Profildatei ohne ihre Umgebung und bestimmt, welche Plugins ins Archiv gehören. */
+export const inspectClientProfile = async (source: string, root = pluginsRoot): Promise<InspectedClientProfile> => {
+  const name = PROFILE_FILE.exec(path.basename(source));
+  if (!name) throw new Error(`Die Client-Profildatei muss ragents.config.<profil>.ts heißen: ${source}`);
+  if (!statSync(source, { throwIfNoEntry: false })?.isFile()) throw new Error(`Die Client-Profildatei ${source} fehlt`);
+  const profile = name[1]!;
+  const module = await import(pathToFileURL(source).href) as Record<string, unknown>;
+  const raw = module.config;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${source} exportiert keine Konstante config`);
+  const host = (raw as Record<string, unknown>).host as Record<string, unknown> | undefined;
+  const entries = host?.PLUGINS;
+  if (!Array.isArray(entries) || entries.length === 0 || !entries.every((entry) => typeof entry === "string" && entry)) {
+    throw new Error(`${source}: host.PLUGINS muss eine nicht leere Liste sein`);
+  }
+  if (host?.PRODUCT_PROFILE !== profile) throw new Error(`${source}: host.PRODUCT_PROFILE muss ${profile} sein`);
+  const known = discoverPluginIds(root);
+  const directory = path.dirname(source);
+  const plugins = (entries as string[]).map((entry): ClientProfilePlugin => {
+    if (!isPluginPath(entry)) {
+      if (!known.includes(entry)) throw new Error(`${source}: das Plugin ${entry} ist im Host nicht bekannt (bekannt: ${known.join(", ")})`);
+      return { id: entry, source: "host", folder: path.join(root, entry) };
+    }
+    const folder = pluginFolderFor(entry, directory, root);
+    if (!statSync(folder, { throwIfNoEntry: false })?.isDirectory() || !hasServerEntry(folder)) {
+      throw new Error(`${source}: das Plugin ${entry} hat keinen Ordner ${folder} mit ${PLUGIN_SERVER_FOLDER}/index.ts`);
+    }
+    if (statSync(path.join(folder, "node_modules"), { throwIfNoEntry: false })) {
+      throw new Error(`${source}: das Plugin ${entry} bringt eigene node_modules mit; Abhängigkeiten müssen aus dem Host kommen`);
+    }
+    return { id: pluginIdOf(folder), source: "archive", folder };
+  });
+  const duplicate = plugins.find((plugin, index) => plugins.findIndex((other) => other.id === plugin.id) !== index);
+  if (duplicate) throw new Error(`${source}: das Plugin ${duplicate.id} steht mehrfach in host.PLUGINS`);
+  checkSections(source, raw as Record<string, unknown>, new Set([...known, ...plugins.map((plugin) => plugin.id)]));
+  const users = resolveProfileUsers(source, module.users, placeholderEnvironment);
+  const anonymous = resolveAnonymousUser(source, module.anonymousUser);
+  if (users && anonymous) throw new Error(`${source}: users und anonymousUser schließen einander aus`);
+  const archived = plugins.filter((plugin) => plugin.source === "archive").map((plugin) => plugin.folder);
+  const commonDirectory = commonRoot(directory, archived);
+  return { profile, source, root: commonDirectory, file: posixRelative(commonDirectory, source), plugins };
+};
+
+const collectFiles = (folder: string, root: string): string[] => {
+  const files: string[] = [];
+  for (const entry of readdirSync(folder, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+    const absolute = path.join(folder, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`Das Client-Profil enthält einen symbolischen Link, den das Archiv nicht abbildet: ${absolute}`);
+    if (entry.isDirectory()) {
+      if (!EXCLUDED_FOLDERS.has(entry.name)) files.push(...collectFiles(absolute, root));
+    } else if (entry.isFile()) {
+      files.push(posixRelative(root, absolute));
+    }
+  }
+  return files;
+};
+
+const collectStaged = (folder: string, root: string): string[] =>
+  readdirSync(folder, { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name, "en"))
+    .flatMap((entry) => entry.isDirectory() ? collectStaged(path.join(folder, entry.name), root) : [posixRelative(root, path.join(folder, entry.name))]);
+
+/** Kopiert Profildatei und Archiv-Plugins in den Staging-Ordner, in dem das gebaute Web schon unter web/ liegt. */
+export const stageClientProfile = async (inspected: InspectedClientProfile, staging: string): Promise<readonly string[]> => {
+  const entries = [inspected.file, ...inspected.plugins.filter((plugin) => plugin.source === "archive").flatMap((plugin) => collectFiles(plugin.folder, inspected.root))];
+  for (const entry of entries) {
+    if (!lstatSync(path.join(inspected.root, entry)).isFile()) throw new Error(`Der Archiveintrag ${entry} ist keine Datei`);
+    if (entry === CLIENT_WEB_FOLDER || entry.startsWith(`${CLIENT_WEB_FOLDER}/`)) {
+      throw new Error(`Der Archiveintrag ${entry} kollidiert mit ${CLIENT_WEB_FOLDER}/, dem Ordner des gebauten Webs`);
+    }
+    const target = path.join(staging, ...entry.split("/"));
+    await mkdir(path.dirname(target), { recursive: true });
+    await copyFile(path.join(inspected.root, entry), target);
+  }
+  return entries;
+};
+
+/** Packt den Staging-Ordner deterministisch; der Stand ist der SHA-256 des Archivs. */
+export const packClientProfile = async (inspected: InspectedClientProfile, staging: string): Promise<PackedClientProfile> => {
+  await stageClientProfile(inspected, staging);
+  const entries = collectStaged(staging, staging);
+  const chunks: Buffer[] = [];
+  for await (const chunk of createTar({ gzip: { level: 9 }, cwd: staging, portable: true, noMtime: true }, entries)) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const archive = Buffer.concat(chunks);
+  return { archive, version: createHash("sha256").update(archive).digest("hex"), entries };
+};