@schlenkr/ragents 0.1.0

package/apps/server/src/api/contracts.ts

@@ -0,0 +1,203 @@
+import { Type } from "typebox";
+import type { PublicPluginProfile } from "@aicontainer/ragents/src/plugin-types";
+import { defineChannel, defineOperation } from "@aicontainer/ragents/src/rpc/contract";
+import { openJson, runContracts } from "@aicontainer/ragents/src/http/contracts";
+import type { ChatAttachmentCapabilities, ChatEvent } from "../chat-events.js";
+import type { ChatUserLocation } from "../chat-context.js";
+import type { SessionInfo } from "../chat-handler.js";
+import type { ActorConversations } from "../ragents/actor-chat-history.js";
+import type { StartOptionState } from "../plugin-support/start-options-contract.js";
+import type { RunPreparationRequest, RunPreparationResponse } from "../run-preparation-contract.js";
+import type { RunTransferExport, RunTransferImport } from "../run-transfer.js";
+import type { SettingsResponse, SettingsSkillDetail } from "../settings.js";
+import type { TitleModelSettings } from "../title-settings-contract.js";
+
+export { runContracts };
+
+const runId = Type.String({ minLength: 1, maxLength: 64, description: "Kennung des Runs" });
+
+const attachment = Type.Object({
+  name: Type.String({ minLength: 1 }),
+  mediaType: Type.String({ minLength: 1 }),
+  data: Type.String({ description: "Inhalt als Base64" }),
+}, { additionalProperties: false });
+
+const sessionInfo = openJson<SessionInfo>("SessionInfo");
+
+/** Rechte je Run prüft der Host dynamisch; Verträge ohne `rights` nennen ihre Regel in der Beschreibung. */
+export const coreContracts = {
+  sessions: {
+    list: defineOperation({
+      id: "ragents.sessions.list",
+      description: "Alle Runs des Profils mit Titel, Zeiten und Metadaten. Recht: runs.read.",
+      rights: ["runs.read"],
+      input: Type.Object({}, { additionalProperties: false }),
+      result: Type.Array(sessionInfo),
+    }),
+    delete: defineOperation({
+      id: "ragents.sessions.delete",
+      description: "Einen Run mit seinen Daten löschen. Rechte: runs.read und runs.delete.",
+      rights: ["runs.read", "runs.delete"],
+      input: Type.Object({ runId }, { additionalProperties: false }),
+      result: Type.Null(),
+    }),
+  },
+  chat: {
+    send: defineOperation({
+      id: "ragents.chat.send",
+      description: "Eine Nachricht an den Koordinator des Runs; startet einen neuen Run oder funkt in einen laufenden. Rechte: runs.read und runs.write, für einen neuen Run runs.create; beim globalen Chat dessen Rechte.",
+      input: Type.Object({
+        runId,
+        text: Type.Optional(Type.String()),
+        attachments: Type.Optional(Type.Array(attachment)),
+        userLocation: Type.Optional(openJson<ChatUserLocation>("ChatUserLocation")),
+      }, { additionalProperties: false }),
+      result: Type.Null(),
+    }),
+    sendToActor: defineOperation({
+      id: "ragents.chat.sendToActor",
+      description: "Eine Nachricht an einen bestimmten LLM-Actor des Runs. Rechte wie ragents.chat.send.",
+      input: Type.Object({ runId, actorId: Type.String({ minLength: 1 }), text: Type.Optional(Type.String()), attachments: Type.Optional(Type.Array(attachment)) }, { additionalProperties: false }),
+      result: Type.Null(),
+    }),
+    start: defineOperation({
+      id: "ragents.chat.start",
+      description: "Einen Run über einen Skill- oder Run-Script-Einstieg starten, ohne Nachricht. Rechte: runs.read, runs.write und die Freigabe des Einstiegs.",
+      input: Type.Object({ runId, entry: Type.String({ minLength: 1 }), input: Type.Optional(Type.Any()) }, { additionalProperties: false }),
+      result: Type.Null(),
+    }),
+    stop: defineOperation({
+      id: "ragents.chat.stop",
+      description: "Den laufenden Turn des Koordinators abbrechen. Rechte: runs.read und runs.write.",
+      input: Type.Object({ runId }, { additionalProperties: false }),
+      result: Type.Null(),
+    }),
+    capabilities: defineOperation({
+      id: "ragents.chat.capabilities",
+      description: "Welche Anhänge das Modell eines Actors annimmt; der Modellname erscheint nur mit runs.inspect. Recht: runs.read.",
+      input: Type.Object({ runId, actor: Type.Optional(Type.String({ minLength: 1 })) }, { additionalProperties: false }),
+      result: openJson<ChatAttachmentCapabilities>("ChatAttachmentCapabilities"),
+    }),
+    actorHistory: defineOperation({
+      id: "ragents.chat.actorHistory",
+      description: "Die Gesprächsverläufe aller Actors des Runs, ohne runs.inspect ohne Werkzeugdetails. Recht: runs.read.",
+      input: Type.Object({ runId }, { additionalProperties: false }),
+      result: openJson<ActorConversations>("ActorConversations"),
+    }),
+  },
+  startOptions: {
+    list: defineOperation({
+      id: "ragents.startOptions.list",
+      description: "Die Startoptionen eines noch nicht gestarteten Runs mit Wert und Darstellung. Rechte: runs.read, runs.create, runs.inspect.",
+      rights: ["runs.read", "runs.create", "runs.inspect"],
+      input: Type.Object({ runId }, { additionalProperties: false }),
+      result: Type.Array(openJson<StartOptionState>("StartOptionState")),
+    }),
+    select: defineOperation({
+      id: "ragents.startOptions.select",
+      description: "Eine Startoption vor dem Start wählen. Rechte: runs.read, runs.write, runs.create, runs.inspect.",
+      rights: ["runs.read", "runs.write", "runs.create", "runs.inspect"],
+      input: Type.Object({ runId, optionId: Type.String({ minLength: 1, maxLength: 128 }), value: Type.Any() }, { additionalProperties: false }),
+      result: openJson<StartOptionState>("StartOptionState"),
+    }),
+  },
+  transfer: {
+    export: defineOperation({
+      id: "ragents.runs.export",
+      description: "Einen gestoppten Run als Archiv holen: Journal, Payloads, Modellkontexte und die Plugin-Ablagen seiner Session. Rechte: runs.read und runs.inspect.",
+      rights: ["runs.read", "runs.inspect"],
+      input: Type.Object({ runId }, { additionalProperties: false }),
+      result: openJson<RunTransferExport>("RunTransferExport"),
+    }),
+    import: defineOperation({
+      id: "ragents.runs.import",
+      description: "Ein Run-Archiv annehmen, sein Journal wiedergeben und den Run gestoppt öffnen. Rechte: runs.read, runs.write und runs.create.",
+      rights: ["runs.read", "runs.write", "runs.create"],
+      input: Type.Object({
+        archive: Type.String({ minLength: 1, description: "Das tar.gz des Exports als Base64" }),
+        workspacePath: Type.Optional(Type.String({ minLength: 1, description: "Ersatzordner auf diesem Server für einen Run mit Bindung path" })),
+      }, { additionalProperties: false }),
+      result: openJson<RunTransferImport>("RunTransferImport"),
+    }),
+  },
+  prepare: defineOperation({
+    id: "ragents.runs.prepare",
+    description: "Den Auftrag eines neuen Runs im Gespräch mit einer eigenen Koordinator-Instanz ausarbeiten. Rechte: runs.read, runs.write, runs.create.",
+    rights: ["runs.read", "runs.write", "runs.create"],
+    input: Type.Intersect([Type.Object({ runId }), openJson<RunPreparationRequest>("RunPreparationRequest")]),
+    result: openJson<RunPreparationResponse>("RunPreparationResponse"),
+  }),
+  settings: {
+    read: defineOperation({
+      id: "ragents.settings.read",
+      description: "Modelle, Plugins, Werkzeuge, Skills und Laufzeitinformationen des Profils. Recht: settings.read; nur lokal oder mit Zugang.",
+      rights: ["settings.read"],
+      input: Type.Object({}, { additionalProperties: false }),
+      result: openJson<SettingsResponse>("SettingsResponse"),
+    }),
+    skill: defineOperation({
+      id: "ragents.settings.skill",
+      description: "Die Dateien eines registrierten Skills lesen; null, wenn er nicht registriert ist. Recht: settings.read.",
+      rights: ["settings.read"],
+      input: Type.Object({ id: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+      result: Type.Union([openJson<SettingsSkillDetail>("SettingsSkillDetail"), Type.Null()]),
+    }),
+    titlesRead: defineOperation({
+      id: "ragents.settings.titles.read",
+      description: "Das Modell für automatische Überschriften und die Auswahl lesen. Recht: settings.read.",
+      rights: ["settings.read"],
+      input: Type.Object({}, { additionalProperties: false }),
+      result: openJson<TitleModelSettings>("TitleModelSettings"),
+    }),
+    titlesSave: defineOperation({
+      id: "ragents.settings.titles.save",
+      description: "Das Modell für automatische Überschriften setzen oder die Erzeugung ausschalten. Recht: settings.write.",
+      rights: ["settings.write"],
+      input: Type.Object({ value: Type.Any() }, { additionalProperties: false }),
+      result: openJson<TitleModelSettings>("TitleModelSettings"),
+    }),
+  },
+  plugins: {
+    bootstrap: defineOperation({
+      id: "ragents.plugins.bootstrap",
+      description: "Produkt, aktive Plugins mit Web-Konfiguration und freigegebene Einstiege für die Oberfläche.",
+      input: Type.Object({}, { additionalProperties: false }),
+      result: openJson<PublicPluginProfile>("PublicPluginProfile"),
+    }),
+  },
+  external: {
+    set: defineOperation({
+      id: "ragents.external.set",
+      description: "Den Zugang von außen ein- oder ausschalten; nur vom eigenen Rechner. Recht: settings.write.",
+      rights: ["settings.write"],
+      input: Type.Object({ state: Type.Union([Type.Literal("on"), Type.Literal("off")]) }, { additionalProperties: false }),
+      result: Type.Object({ external: Type.Boolean() }),
+    }),
+  },
+  channels: {
+    sessions: defineChannel({
+      id: "ragents.sessions",
+      description: "Meldet jede Änderung der Run-Liste. Recht: runs.read.",
+      rights: ["runs.read"],
+      params: Type.Object({}, { additionalProperties: false }),
+      message: Type.Object({ type: Type.Literal("changed") }),
+    }),
+    run: defineChannel({
+      id: "ragents.run",
+      description: "Meldet jedes neue Journalereignis eines Runs; erst ready, dann run. Rechte wie das Lesen des Runs.",
+      params: Type.Object({ runId }, { additionalProperties: false }),
+      message: Type.Object({ kind: Type.Union([Type.Literal("ready"), Type.Literal("run")]) }),
+    }),
+    chat: defineChannel({
+      id: "ragents.chat",
+      description: "Der Chatverlauf des Koordinators: erst der gespeicherte Verlauf, dann live. Rechte wie das Lesen des Runs.",
+      params: Type.Object({ runId }, { additionalProperties: false }),
+      message: openJson<ChatEvent>("ChatEvent"),
+    }),
+  },
+} as const;
+
+export const ATTACHMENT_CONTENT_PATH = /^\/files\/runs\/([A-Za-z0-9_-]{1,64})\/attachments\/([A-Za-z0-9_-]{1,128})$/;
+
+export const attachmentContentPath = (runId: string, artifactId: string): string =>
+  `/files/runs/${encodeURIComponent(runId)}/attachments/${encodeURIComponent(artifactId)}`;

package/apps/server/src/api/core-methods.ts

@@ -0,0 +1,163 @@
+import { canStartEntry, DomainError, implement, implementChannel, type AccessContext, type ChannelContribution, type MethodContribution, type PluginHost } from "@aicontainer/ragents";
+import { parseChatAttachments } from "../chat-attachments.js";
+import type { ChatSessionLike, ChatSessionProvider, ChatUser } from "../chat-handler.js";
+import { accessibleActorConversations, accessibleChatEvent } from "../access-projection.js";
+import type { StartOptionState } from "../plugin-support/start-options-contract.js";
+import type { RunPreparationResponse } from "../run-preparation-contract.js";
+import type { RunTransferExport, RunTransferImport } from "../run-transfer.js";
+import type { SettingsResponse, SettingsSkillDetail } from "../settings.js";
+import type { TitleModelSettings } from "../title-settings-contract.js";
+import { coreContracts } from "./contracts.js";
+import { assertRunRights, type GlobalRunPolicy } from "./rights.js";
+import { assertRights } from "../rpc/dispatcher.js";
+
+export interface CoreMethodSources {
+  sessions: ChatSessionProvider & {
+    subscribeList: (listener: () => void) => () => void;
+    subscribeRun: (runId: string, listener: () => void) => () => void;
+    startOptions: (runId: string) => readonly StartOptionState[];
+    selectStartOption: (runId: string, optionId: string, value: unknown) => StartOptionState;
+    prepareRunMessage: (runId: string, request: unknown, signal: AbortSignal) => Promise<RunPreparationResponse>;
+    exportRun: (runId: string) => Promise<RunTransferExport>;
+    importRun: (archive: Buffer, workspacePath: string | undefined) => Promise<RunTransferImport>;
+    settings: () => Promise<SettingsResponse>;
+    skill: (id: string) => Promise<SettingsSkillDetail | null>;
+    titleModelSettings: () => TitleModelSettings;
+    saveTitleModelSettings: (value: unknown) => Promise<TitleModelSettings>;
+  };
+  plugins: PluginHost;
+  global: GlobalRunPolicy | undefined;
+  /** Einstellungen sind ohne Anmeldung und Zugangstoken nur vom eigenen Rechner lesbar. */
+  settingsGuarded: () => boolean;
+  external: { open: () => boolean; set: (value: boolean) => Promise<void> };
+}
+
+const userOf = (access: AccessContext): ChatUser | undefined => access.user ? { id: access.user.id, label: access.user.label } : undefined;
+
+const messageOf = (text: string | undefined, attachments: unknown) => {
+  try {
+    const trimmed = text?.trim() ?? "";
+    const parsed = parseChatAttachments(attachments);
+    if (!trimmed && parsed.length === 0) throw new Error("Text oder Anhänge fehlen");
+    return { text: trimmed, attachments: parsed };
+  } catch (error) {
+    throw new DomainError("invalid-message", error instanceof Error ? error.message : String(error), 400);
+  }
+};
+
+const TECHNICAL_ATTACHMENT_ERRORS = ["attachment-model-unsupported", "attachment-tools-required", "attachments-unsupported"];
+
+/** Ohne runs.inspect bekommt der Benutzer bei technischen Fehlern nur den allgemeinen Hinweis, wie bisher. */
+const guardedForUser = async <T>(access: AccessContext, work: () => Promise<T>): Promise<T> => {
+  try {
+    return await work();
+  } catch (error) {
+    if (access.can("runs.inspect")) throw error;
+    const technical = error instanceof DomainError && TECHNICAL_ATTACHMENT_ERRORS.includes(error.code);
+    if (technical) throw new DomainError(error.code, "Dieser Agent kann die angehängte Datei nicht verarbeiten.", error.status);
+    if (!(error instanceof DomainError) || error.status >= 500) throw new DomainError("request-failed", "Die Anfrage konnte nicht verarbeitet werden.", 500);
+    throw error;
+  }
+};
+
+export const coreMethods = (sources: CoreMethodSources): MethodContribution[] => {
+  const { sessions, global } = sources;
+  const session = async (access: AccessContext, runId: string, kind: "read" | "write"): Promise<ChatSessionLike> => {
+    assertRunRights(access, runId, kind, global);
+    return sessions.get(runId);
+  };
+  const assertMaySend = (access: AccessContext, runId: string) => {
+    if (!access.can("runs.create") && !sessions.hasRun?.(runId)) throw new DomainError("access-denied", "Freie Runs sind für diesen Zugang nicht freigegeben.", 403);
+  };
+  const assertSettingsReachable = (local: boolean) => {
+    if (!local && sources.settingsGuarded()) throw new DomainError("settings-local-only", "Einstellungen sind nur lokal oder mit Zugangstoken verfügbar", 403);
+  };
+  return [
+    implement(coreContracts.sessions.list, () => sessions.list()),
+    implement(coreContracts.sessions.delete, async ({ runId }) => { await sessions.delete(runId); return null; }),
+    implement(coreContracts.chat.send, async ({ runId, text, attachments, userLocation }, { access }) => {
+      assertMaySend(access, runId);
+      const current = await session(access, runId, "write");
+      const message = messageOf(text, attachments);
+      await guardedForUser(access, async () => current.send(message.text, message.attachments, userLocation, userOf(access)));
+      return null;
+    }),
+    implement(coreContracts.chat.sendToActor, async ({ runId, actorId, text, attachments }, { access }) => {
+      assertMaySend(access, runId);
+      const current = await session(access, runId, "write");
+      if (!current.sendToActor) throw new DomainError("actor-send-unavailable", "Actor-Nachrichten sind nicht verfügbar", 404);
+      const message = messageOf(text, attachments);
+      await guardedForUser(access, () => current.sendToActor!(actorId, message.text, message.attachments));
+      return null;
+    }),
+    implement(coreContracts.chat.start, async ({ runId, entry, input }, { access }) => {
+      const trimmed = entry.trim();
+      if (!canStartEntry(access, trimmed)) throw new DomainError("access-denied", "Dieses Setup ist für diesen Zugang nicht freigegeben.", 403);
+      const current = await session(access, runId, "write");
+      current.start(trimmed, input === undefined ? null : input, userOf(access));
+      return null;
+    }),
+    implement(coreContracts.chat.stop, async ({ runId }, { access }) => {
+      const current = await session(access, runId, "write");
+      await current.stop();
+      return null;
+    }),
+    implement(coreContracts.chat.capabilities, async ({ runId, actor }, { access }) => {
+      const current = await session(access, runId, "read");
+      if (!current.capabilities) throw new DomainError("capabilities-unavailable", "Modellfähigkeiten sind nicht verfügbar", 404);
+      const capabilities = await current.capabilities(actor ?? "primary");
+      return access.can("runs.inspect") ? capabilities : { ...capabilities, model: "" };
+    }),
+    implement(coreContracts.chat.actorHistory, async ({ runId }, { access }) => {
+      const current = await session(access, runId, "read");
+      if (!current.actorConversations) throw new DomainError("actor-history-unavailable", "Actor-Verläufe sind nicht verfügbar", 404);
+      return accessibleActorConversations(current.actorConversations(), access);
+    }),
+    implement(coreContracts.startOptions.list, ({ runId }) => [...sessions.startOptions(runId)]),
+    implement(coreContracts.startOptions.select, ({ runId, optionId, value }) => sessions.selectStartOption(runId, optionId, value)),
+    implement(coreContracts.prepare, ({ runId, ...request }, { signal }) => sessions.prepareRunMessage(runId, request, signal)),
+    implement(coreContracts.transfer.export, ({ runId }) => sessions.exportRun(runId)),
+    implement(coreContracts.transfer.import, ({ archive, workspacePath }) => {
+      const decoded = Buffer.from(archive, "base64");
+      if (decoded.length === 0) throw new DomainError("run-transfer-invalid", "Das Archiv ist leer.", 400);
+      return sessions.importRun(decoded, workspacePath);
+    }),
+    implement(coreContracts.settings.read, (_input, { local }) => { assertSettingsReachable(local); return sessions.settings(); }),
+    implement(coreContracts.settings.skill, ({ id }, { local }) => { assertSettingsReachable(local); return sessions.skill(id); }),
+    implement(coreContracts.settings.titlesRead, (_input, { local }) => { assertSettingsReachable(local); return sessions.titleModelSettings(); }),
+    implement(coreContracts.settings.titlesSave, ({ value }, { local }) => { assertSettingsReachable(local); return sessions.saveTitleModelSettings(value); }),
+    implement(coreContracts.plugins.bootstrap, (_input, { access }) => sources.plugins.publicProfile(access)),
+    implement(coreContracts.external.set, async ({ state }, { local }) => {
+      if (!local) throw new DomainError("local-only", "Nur lokal schaltbar", 403);
+      await sources.external.set(state === "on");
+      return { external: sources.external.open() };
+    }),
+  ];
+};
+
+export const coreChannels = (sources: Pick<CoreMethodSources, "sessions" | "global">): ChannelContribution[] => {
+  const { sessions, global } = sources;
+  return [
+    implementChannel(coreContracts.channels.sessions, (_params, emit) => {
+      const notify = () => emit({ type: "changed" });
+      const unsubscribe = sessions.subscribeList(notify);
+      notify();
+      return unsubscribe;
+    }),
+    implementChannel(coreContracts.channels.run, ({ runId }, emit, { access }) => {
+      assertRunRights(access, runId, "read", global);
+      emit({ kind: "ready" });
+      return sessions.subscribeRun(runId, () => emit({ kind: "run" }));
+    }),
+    implementChannel(coreContracts.channels.chat, async ({ runId }, emit, { access }) => {
+      assertRunRights(access, runId, "read", global);
+      const current = await sessions.get(runId);
+      return current.subscribe((event) => {
+        const visible = accessibleChatEvent(event, access);
+        if (visible) emit(visible);
+      });
+    }),
+  ];
+};
+
+export { assertRights };

package/apps/server/src/api/delivery.ts

@@ -0,0 +1,40 @@
+import { DomainError, type HttpRouteContribution } from "@aicontainer/ragents";
+import type { ChatSessionProvider } from "../chat-handler.js";
+import { writeJson } from "../plugin-support/http.js";
+import { ATTACHMENT_CONTENT_PATH } from "./contracts.js";
+import { assertRunRights, type GlobalRunPolicy } from "./rights.js";
+
+/** Anhänge sind Auslieferung: ein GET mit dem Medientyp, inline für Bilder und Videos. */
+export const attachmentContentRoute = (sessions: ChatSessionProvider, global: GlobalRunPolicy | undefined): HttpRouteContribution => ({
+  id: "ragents.chat.attachment-content",
+  requiredRights: [],
+  isApiPath: (pathname) => ATTACHMENT_CONTENT_PATH.test(pathname),
+  matches: (request, url) => request.method === "GET" && ATTACHMENT_CONTENT_PATH.test(url.pathname),
+  handle: async ({ response, url, access }) => {
+    const match = url.pathname.match(ATTACHMENT_CONTENT_PATH)!;
+    const runId = decodeURIComponent(match[1]!);
+    const artifactId = decodeURIComponent(match[2]!);
+    try {
+      assertRunRights(access, runId, "read", global);
+      const session = await sessions.get(runId);
+      if (!session.attachment) throw new DomainError("attachments-unavailable", "Anhänge sind nicht verfügbar", 404);
+      const { attachment, content } = session.attachment(artifactId);
+      const inline = !url.searchParams.has("download")
+        && (attachment.mediaType.startsWith("image/") || attachment.mediaType.startsWith("video/"));
+      response.writeHead(200, {
+        "Content-Type": attachment.mediaType,
+        "Content-Length": content.byteLength,
+        "Content-Disposition": `${inline ? "inline" : "attachment"}; filename*=UTF-8''${encodeURIComponent(attachment.name).replace(/['()*]/g, (character) => `%${character.charCodeAt(0).toString(16)}`)}`,
+        "X-Content-Type-Options": "nosniff",
+        "Content-Security-Policy": "default-src 'none'; sandbox",
+        "Cache-Control": "private, max-age=31536000, immutable",
+      });
+      response.end(Buffer.from(content));
+    } catch (error) {
+      writeJson(response, error instanceof DomainError ? error.status : 500, {
+        error: error instanceof Error ? error.message : String(error),
+        ...(error instanceof DomainError ? { code: error.code } : {}),
+      });
+    }
+  },
+});

package/apps/server/src/api/reference.ts

@@ -0,0 +1,146 @@
+import type { TSchema } from "typebox";
+import { RPC_METHODS, type ChannelDescriptor, type MethodDescriptor, type PluginHost } from "@aicontainer/ragents";
+
+export type ApiAuthentication = { kind: "open" } | { kind: "token" } | { kind: "users"; cookieName: string };
+
+export const RPC_API_TITLE = "RAgents JSON-RPC-API";
+
+const schemaJson = (schema: TSchema): Record<string, unknown> => JSON.parse(JSON.stringify(schema)) as Record<string, unknown>;
+
+const byId = <T extends { id: string }>(entries: readonly T[]): T[] =>
+  [...entries].sort((left, right) => left.id.localeCompare(right.id, "en"));
+
+const rights = (entry: { rights: readonly string[] }): string => entry.rights.length > 0 ? entry.rights.join(", ") : "keine festen Rechte";
+
+export const authenticationDescription = (authentication: ApiAuthentication): string => authentication.kind === "users"
+  ? "Benutzeranmeldung: POST /api/access/login mit id und password. Das erhaltene Sitzungscookie bei weiteren Anfragen mitsenden. ACCESS_TOKEN ersetzt keine Benutzeranmeldung."
+  : authentication.kind === "token" ? "Dieses Profil verlangt den konfigurierten ACCESS_TOKEN als Bearer-Token oder das bestehende Zugangscookie."
+    : "Dieses Profil verlangt keine Anmeldung. Profile mit users verwenden Sitzungscookies; ohne users kann ACCESS_TOKEN den bisherigen Zugang schützen.";
+
+const transportLines = (authentication: ApiAuthentication, example: string): string[] => [
+  "Die API ist JSON-RPC 2.0. Eine Anfrage ist ein Objekt mit jsonrpc, id, method und params; params ist immer das Eingabeobjekt der Methode. Die Antwort enthält result oder error; error.data nennt code und status des Fehlers.",
+  "",
+  "Transporte:",
+  "",
+  "- HTTP: `POST /rpc` mit genau einer Nachricht je Anfrage. `GET /rpc/stream` liefert als Server-Sent-Events die Benachrichtigungen und Anfragen des Servers; das erste Ereignis `hello` nennt die Verbindungskennung, die weitere Anfragen im Header `x-ragents-connection` mitsenden.",
+  "- stdio: der Server startet mit `--stdio` und tauscht eine JSON-Nachricht je Zeile über stdin und stdout aus.",
+  "",
+  `Feste Methoden der Nachrichtenschicht: ${RPC_METHODS.subscribe}, ${RPC_METHODS.unsubscribe}, ${RPC_METHODS.event}, ${RPC_METHODS.cancel} und ${RPC_METHODS.progress}. Ein Abonnement nennt channel und params und erhält eine Abonnementkennung; jede Nachricht des Kanals kommt als ${RPC_METHODS.event}.`,
+  "",
+  authenticationDescription(authentication),
+  "",
+  "Die Shellvariable RAGENTS_API_BASE_URL enthält die Serveradresse. Falls RAGENTS_API_TOKEN gesetzt ist, bei Anfragen den Header Authorization: Bearer <Token> senden. Der Token gehört nicht in Ausgaben oder Dokumente.",
+  "",
+  "```sh",
+  `curl -s "$RAGENTS_API_BASE_URL/rpc" -H 'content-type: application/json' \\`,
+  `  -d '{"jsonrpc":"2.0","id":1,"method":"${example}","params":{}}'`,
+  "```",
+  "",
+  "Kennungen aus Ergebnissen werden programmgesteuert weiterverwendet, nicht abgeschrieben.",
+];
+
+const methodSection = (method: MethodDescriptor): string[] => [
+  `## ${method.id}`,
+  "",
+  method.description,
+  "",
+  `Eigentümer: ${method.owner}. Rechte: ${rights(method)}. Ausführung: ${method.implementedBy === "client" ? "der verbundene Client" : "der Server"}.`,
+  "",
+  "### Eingabe",
+  "",
+  "```json",
+  JSON.stringify(schemaJson(method.input), null, 2),
+  "```",
+  "",
+  "### Ergebnis",
+  "",
+  "```json",
+  JSON.stringify(schemaJson(method.result), null, 2),
+  "```",
+  "",
+];
+
+const channelSection = (channel: ChannelDescriptor): string[] => [
+  `## Kanal ${channel.id}`,
+  "",
+  channel.description,
+  "",
+  `Eigentümer: ${channel.owner}. Rechte: ${rights(channel)}.`,
+  "",
+  "### Parameter",
+  "",
+  "```json",
+  JSON.stringify(schemaJson(channel.params), null, 2),
+  "```",
+  "",
+  "### Nachricht",
+  "",
+  "```json",
+  JSON.stringify(schemaJson(channel.message), null, 2),
+  "```",
+  "",
+];
+
+/** Für das Beispiel eine Methode ohne Pflichtfelder, damit der gezeigte Aufruf tatsächlich funktioniert. */
+const exampleMethod = (methods: readonly MethodDescriptor[]): string => {
+  const empty = methods.find((method) => {
+    const schema = schemaJson(method.input);
+    return schema.type === "object" && schema.required === undefined && method.implementedBy === "server";
+  });
+  return empty?.id ?? methods[0]?.id ?? "<methoden-id>";
+};
+
+/** Lesbare Referenz aller registrierten Methoden und Kanäle, direkt aus ihren Verträgen. */
+export function methodReference(host: PluginHost, authentication: ApiAuthentication = { kind: "open" }): string {
+  const methods = byId(host.methods.describe());
+  const channels = byId(host.channels.describe());
+  return [
+    `# ${RPC_API_TITLE}`,
+    "",
+    "Diese Referenz entsteht aus den registrierten Verträgen. Interne und externe Clients verwenden dieselben Methoden.",
+    "",
+    ...transportLines(authentication, exampleMethod(methods)),
+    "",
+    "## Methodenübersicht",
+    "",
+    "| Methode | Eigentümer | Rechte |",
+    "| --- | --- | --- |",
+    ...methods.map((method) => `| ${method.id} | ${method.owner} | ${rights(method)} |`),
+    "",
+    "## Kanalübersicht",
+    "",
+    "| Kanal | Eigentümer | Rechte |",
+    "| --- | --- | --- |",
+    ...channels.map((channel) => `| ${channel.id} | ${channel.owner} | ${rights(channel)} |`),
+    "",
+    ...methods.flatMap(methodSection),
+    ...channels.flatMap(channelSection),
+  ].join("\n");
+}
+
+/** OpenRPC 1.3 aus denselben Verträgen; Kanäle stehen als x-channels daneben. */
+export function openRpcDocument(host: PluginHost, authentication: ApiAuthentication = { kind: "open" }): Record<string, unknown> {
+  return {
+    openrpc: "1.3.0",
+    info: { title: RPC_API_TITLE, version: "1", description: authenticationDescription(authentication) },
+    servers: [{ name: "http", url: "/rpc" }, { name: "stdio", url: "stdio:" }],
+    methods: byId(host.methods.describe()).map((method) => ({
+      name: method.id,
+      description: method.description,
+      params: [{ name: "input", required: true, schema: schemaJson(method.input) }],
+      paramStructure: "by-name",
+      result: { name: "result", schema: schemaJson(method.result) },
+      "x-owner": method.owner,
+      "x-rights": [...method.rights],
+      "x-implemented-by": method.implementedBy,
+    })),
+    "x-channels": byId(host.channels.describe()).map((channel) => ({
+      name: channel.id,
+      description: channel.description,
+      params: schemaJson(channel.params),
+      message: schemaJson(channel.message),
+      "x-owner": channel.owner,
+      "x-rights": [...channel.rights],
+    })),
+  };
+}

package/apps/server/src/api/rights.ts

@@ -0,0 +1,26 @@
+import type { AccessContext } from "@aicontainer/ragents";
+import { assertRights } from "../rpc/dispatcher.js";
+import type { RunRightsKind } from "@aicontainer/ragents/src/http/methods";
+
+export interface GlobalRunPolicy {
+  runId: string;
+  read: string;
+  write: string;
+}
+
+/** Rechte je Run: gewöhnliche Runs über runs.*, der globale Chat über die Rechte seines Plugins. */
+export const runRights = (runId: string, kind: RunRightsKind, global: GlobalRunPolicy | undefined): readonly string[] => {
+  if (global && runId === global.runId) {
+    const technical = kind === "inspect" || kind === "write-inspect" ? ["runs.inspect"] : [];
+    return kind === "read" || kind === "inspect" ? [global.read, ...technical] : [global.read, global.write, ...technical];
+  }
+  switch (kind) {
+    case "read": return ["runs.read"];
+    case "inspect": return ["runs.read", "runs.inspect"];
+    case "write": return ["runs.read", "runs.write"];
+    case "write-inspect": return ["runs.read", "runs.write", "runs.inspect"];
+  }
+};
+
+export const assertRunRights = (access: AccessContext, runId: string, kind: RunRightsKind, global: GlobalRunPolicy | undefined): void =>
+  assertRights(access, runRights(runId, kind, global));

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

@@ -0,0 +1,52 @@
+import type { ChatAttachmentInput } from "./chat-events.js";
+
+export const MAX_CHAT_ATTACHMENTS = 8;
+export const MAX_CHAT_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export const MAX_CHAT_REQUEST_BYTES = 29 * 1024 * 1024;
+
+export const chatAttachmentMediaType = (name: string, mediaType: string): string => {
+  const explicit = mediaType.trim().toLowerCase();
+  if (explicit) return explicit === "video/quicktime" ? "video/mov" : explicit;
+  const types: Record<string, string> = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+    avif: "image/avif", svg: "image/svg+xml", pdf: "application/pdf",
+    mp4: "video/mp4", webm: "video/webm", mov: "video/mov", mpeg: "video/mpeg", mpg: "video/mpeg",
+    txt: "text/plain", md: "text/markdown", csv: "text/csv", tsv: "text/tab-separated-values",
+    json: "application/json", jsonl: "application/x-ndjson", xml: "application/xml",
+    yaml: "application/yaml", yml: "application/yaml", ts: "text/plain", tsx: "text/plain",
+    js: "application/javascript", py: "text/plain", cs: "text/plain", fs: "text/plain",
+    html: "text/html", css: "text/css", log: "text/plain",
+  };
+  return types[name.split(".").at(-1)?.toLowerCase() ?? ""] ?? "application/octet-stream";
+};
+
+export const parseChatAttachments = (value: unknown): ChatAttachmentInput[] => {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_CHAT_ATTACHMENTS) {
+    throw new Error(`Anhänge müssen eine Liste mit höchstens ${MAX_CHAT_ATTACHMENTS} Dateien sein.`);
+  }
+  let total = 0;
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`Anhang ${index + 1} ist ungültig.`);
+    const { name, mediaType, data } = entry as Record<string, unknown>;
+    if (typeof name !== "string" || !name.trim() || name.length > 255 || /[/\\\u0000-\u001f\u007f]/.test(name)
+      || name === "." || name === "..") throw new Error(`Anhang ${index + 1} benötigt einen gültigen Dateinamen ohne Pfad.`);
+    const normalizedType = typeof mediaType === "string" ? chatAttachmentMediaType(name, mediaType) : "";
+    if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i.test(normalizedType)) {
+      throw new Error(`Anhang ${name} benötigt einen gültigen MIME-Typ.`);
+    }
+    if (typeof data === "string" && data.length > Math.ceil(MAX_CHAT_ATTACHMENT_BYTES / 3) * 4)
+      throw new Error("Anhänge dürfen zusammen höchstens 20 MiB groß sein.");
+    if (typeof data !== "string" || data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
+      throw new Error(`Anhang ${name} enthält ungültiges Base64.`);
+    }
+    const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    if (padding && (alphabet.indexOf(data[data.length - padding - 1]) & (padding === 2 ? 15 : 3)) !== 0) {
+      throw new Error(`Anhang ${name} enthält nichtkanonisches Base64.`);
+    }
+    total += data.length / 4 * 3 - padding;
+    if (total > MAX_CHAT_ATTACHMENT_BYTES) throw new Error("Anhänge dürfen zusammen höchstens 20 MiB groß sein.");
+    return { name, mediaType: normalizedType, data };
+  });
+};

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

@@ -0,0 +1,6 @@
+export interface ChatUserLocation {
+  surface: "home" | "overview" | "run";
+  runId: string | null;
+  tab: string | null;
+  selection: { type: string; id: string } | null;
+}