@schlenkr/ragents 0.1.0

package/plugins/ragents.lsp-roslyn/web/language-server-plugin.tsx

@@ -0,0 +1,236 @@
+import { Alert, AlertDescription, Badge, Button, Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, Spinner } from "@aicontainer/web/ui";
+import { useEffect, useState, type ComponentType } from "react";
+import type {
+  LanguageServerSeverity,
+  LanguageServerSnapshot,
+} from "@aicontainer/server/plugin-support/language-server/contract";
+import {
+  type WebPlugin,
+  type WebPluginDescriptor,
+  type WorkspaceTabContext,
+} from "@aicontainer/web/PluginRegistry";
+import { fetchLanguageServerSnapshot } from "./api";
+
+const POLL_MS = 5000;
+const BADGE_POLL_MS = 15000;
+
+interface TabSettings {
+  label: string;
+  openTool: string;
+  pluginId: string;
+}
+
+const severityLabels: Readonly<Record<LanguageServerSeverity, string>> = {
+  error: "Fehler",
+  warning: "Warnung",
+  information: "Hinweis",
+  hint: "Tipp",
+};
+
+const textFrom = (config: Readonly<Record<string, unknown>>, key: string, pluginId: string): string => {
+  const value = config[key];
+  if (typeof value !== "string" || !value) throw new Error(`Plugin-Konfiguration für ${pluginId} enthält kein ${key}`);
+  return value;
+};
+
+const stateLabel = (snapshot: LanguageServerSnapshot | undefined): string => {
+  if (!snapshot) return "wird geladen";
+  if (snapshot.state === "closed") return "nicht gestartet";
+  if (snapshot.state === "opening") return "wird geladen";
+  if (snapshot.state === "failed") return "fehlgeschlagen";
+  if (snapshot.state === "suspended") return "nach Leerlauf beendet";
+  return snapshot.summary ?? "bereit";
+};
+
+const countLabel = (count: number, singular: string, plural: string): string =>
+  `${count} ${count === 1 ? singular : plural}`;
+
+const compactEmpty = "h-auto min-h-30 flex-none";
+const severityClass = "text-[0.64rem] uppercase tracking-[0.04em]"
+  + " in-data-[severity=error]:text-destructive in-data-[severity=warning]:text-warning"
+  + " in-data-[severity=information]:text-primary in-data-[severity=hint]:text-primary";
+
+function IconDiagnostics() {
+  return (
+    <svg aria-hidden fill="none" height="15" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.7" viewBox="0 0 24 24" width="15">
+      <path d="M9 4 4 12l5 8M15 4l5 8-5 8" />
+      <path d="M12 9v4M12 16v.5" />
+    </svg>
+  );
+}
+
+function IconRefresh({ className }: { className?: string }) {
+  return (
+    <svg aria-hidden className={className} fill="none" height="15" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.8" viewBox="0 0 24 24" width="15">
+      <path d="M20 7v5h-5M4 17v-5h5" />
+      <path d="M6.1 9a7 7 0 0 1 11.7-2L20 9M4 15l2.2 2A7 7 0 0 0 18 15" />
+    </svg>
+  );
+}
+
+const useSnapshot = (pluginId: string, runId: string, active: boolean, pollMs: number = POLL_MS) => {
+  const [snapshot, setSnapshot] = useState<LanguageServerSnapshot>();
+  const [error, setError] = useState<string>();
+  const [pending, setPending] = useState(false);
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  useEffect(() => {
+    if (!active) return;
+    let disposed = false;
+    let timer: number | undefined;
+
+    const poll = async () => {
+      setPending(true);
+      try {
+        const value = await fetchLanguageServerSnapshot(pluginId, runId);
+        if (disposed) return;
+        setSnapshot(value);
+        setError(undefined);
+      } catch (caught) {
+        if (!disposed) setError(caught instanceof Error ? caught.message : String(caught));
+      } finally {
+        if (!disposed) {
+          setPending(false);
+          timer = window.setTimeout(() => void poll(), pollMs);
+        }
+      }
+    };
+
+    void poll();
+    return () => {
+      disposed = true;
+      if (timer !== undefined) window.clearTimeout(timer);
+    };
+  }, [active, pluginId, pollMs, refreshKey, runId]);
+
+  return { snapshot, error, pending, refresh: () => setRefreshKey((value) => value + 1) };
+};
+
+const panelFor = (settings: TabSettings) => {
+  function LanguageServerPanel({ active, session }: WorkspaceTabContext) {
+    const { snapshot, error, pending, refresh } = useSnapshot(settings.pluginId, session.session.id, active);
+    return <LanguageServerPanelView settings={settings} snapshot={snapshot} error={error} pending={pending} onRefresh={refresh} />;
+  }
+
+  return LanguageServerPanel;
+};
+
+export function LanguageServerPanelView({ settings, snapshot, error, pending, onRefresh }: {
+  settings: Pick<TabSettings, "label" | "openTool">;
+  snapshot?: LanguageServerSnapshot;
+  error?: string;
+  pending: boolean;
+  onRefresh: () => void;
+}) {
+  const diagnosticsAvailable = snapshot?.state === "ready" || snapshot?.state === "suspended";
+  const files = diagnosticsAvailable ? snapshot.files : [];
+  const rows = files.flatMap((file) => file.diagnostics.map((entry) => ({ file: file.path, entry })));
+  const errors = rows.filter((row) => row.entry.severity === "error").length;
+  const warnings = rows.filter((row) => row.entry.severity === "warning").length;
+
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      <header className="flex items-center gap-2 px-2.5 py-2">
+        <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+          <span className="text-[0.8rem] font-medium text-foreground">{settings.label}</span>
+          <span className="text-xs text-muted-foreground">{stateLabel(snapshot)}</span>
+        </div>
+        <Button aria-label="Diagnosen aktualisieren" onClick={onRefresh} size="icon" title="Aktualisieren" variant="ghost">
+          <IconRefresh className={pending ? "animate-spin" : undefined} />
+        </Button>
+      </header>
+      {error && <Alert variant="destructive"><AlertDescription>{error}</AlertDescription></Alert>}
+      {snapshot?.root && <div className="overflow-hidden text-ellipsis whitespace-nowrap px-2.5 pb-2 font-mono text-[0.66rem] text-muted-foreground" title={snapshot.root}>{snapshot.root}</div>}
+      {snapshot?.state === "opening" && (
+        <Empty className={compactEmpty} role="status">
+          <EmptyHeader>
+            <EmptyMedia><Spinner aria-label="Wird geladen" /></EmptyMedia>
+            <EmptyTitle>Sprachserver wird geladen</EmptyTitle>
+            <EmptyDescription>{snapshot.summary || "Die Initialisierung läuft."}</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+      {snapshot?.state === "failed" && (
+        <Empty className={`${compactEmpty} text-destructive`} role="alert">
+          <EmptyHeader>
+            <EmptyTitle>Sprachserver nicht verfügbar</EmptyTitle>
+            <EmptyDescription className="whitespace-pre-wrap text-destructive [overflow-wrap:anywhere]">{snapshot.summary || "Beim Laden ist ein Fehler aufgetreten."}</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+      {snapshot?.state === "closed" && (
+        <Empty>
+          <EmptyHeader>
+            <EmptyMedia><IconDiagnostics /></EmptyMedia>
+            <EmptyTitle>Kein Sprachserver</EmptyTitle>
+            <EmptyDescription>{`${settings.label}-Sprachserver ist nicht gestartet - ein Agent startet ihn mit ${settings.openTool}.`}</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+      {diagnosticsAvailable && rows.length === 0 && (
+        <Empty className={compactEmpty}>
+          <EmptyHeader>
+            <EmptyTitle>Keine Diagnosen</EmptyTitle>
+            <EmptyDescription>{files.length === 0 ? "Bisher wurde keine Datei geprüft." : "Alle geprüften Dateien sind fehlerfrei."}</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+      {rows.length > 0 && (
+        <>
+          <div className="border-y border-border-soft px-2.5 py-1.5 text-xs text-muted-foreground">
+            {`${countLabel(errors, "Fehler", "Fehler")}, ${countLabel(warnings, "Warnung", "Warnungen")} in ${countLabel(files.length, "Datei", "Dateien")}`}
+          </div>
+          <div className="min-h-0 flex-1 overflow-y-auto px-1.5 pt-1 pb-2.5">
+            {rows.map((row, index) => (
+              <div className="grid grid-cols-[minmax(0,1fr)_auto] gap-x-2 gap-y-0.5 border-b border-border-soft px-2 py-1.5 text-[0.7rem]"
+                data-severity={row.entry.severity} key={`${row.file}:${row.entry.line}:${row.entry.character}:${index}`}>
+                <span className="overflow-hidden text-ellipsis whitespace-nowrap font-mono text-muted-foreground">{`${row.file}:${row.entry.line}`}</span>
+                <span className={severityClass}>
+                  {row.entry.code ? `${severityLabels[row.entry.severity]} ${row.entry.code}` : severityLabels[row.entry.severity]}
+                </span>
+                <span className="col-span-full leading-[1.4] text-foreground">{row.entry.message}</span>
+              </div>
+            ))}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+const badgeFor = (settings: TabSettings) => {
+  function LanguageServerBadge({ session }: WorkspaceTabContext) {
+    const { snapshot } = useSnapshot(settings.pluginId, session.session.id, true, BADGE_POLL_MS);
+    const errors = (snapshot?.state === "ready" || snapshot?.state === "suspended" ? snapshot.files : [])
+      .flatMap((file) => file.diagnostics)
+      .filter((entry) => entry.severity === "error").length;
+    return errors > 0 ? <Badge variant="secondary">{errors}</Badge> : null;
+  }
+
+  return LanguageServerBadge;
+};
+
+const configuredPlugin = (descriptor: WebPluginDescriptor, settings: TabSettings, Icon: ComponentType): WebPlugin => ({
+  ...descriptor,
+  workspaceTabs: [{
+    readRight: `${descriptor.id}.read`,
+    id: `${descriptor.id}.diagnostics`,
+    label: settings.label,
+    order: 300,
+    Icon,
+    Panel: panelFor(settings),
+    Badge: badgeFor(settings),
+  }],
+});
+
+export const languageServerWebPlugin = (pluginId: string, Icon: ComponentType = IconDiagnostics): WebPlugin => {
+  const descriptor: WebPluginDescriptor = { id: pluginId };
+  return {
+    ...descriptor,
+    activate: (config) => configuredPlugin(descriptor, {
+      label: textFrom(config, "label", pluginId),
+      openTool: textFrom(config, "openTool", pluginId),
+      pluginId,
+    }, Icon),
+  };
+};

package/plugins/ragents.lsp-typescript/server/index.ts

@@ -0,0 +1,7 @@
+import { typescriptAdapter } from "@aicontainer/workspace-executor";
+import { createLanguageServerPlugin } from "@aicontainer/server/plugin-support/language-server/plugin.js";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+
+export const plugin: PluginModule = {
+  create: () => createLanguageServerPlugin({ id: "ragents.lsp-typescript", adapter: typescriptAdapter }),
+};

package/plugins/ragents.lsp-typescript/web/index.tsx

@@ -0,0 +1,7 @@
+import { languageServerWebPlugin } from "@aicontainer/plugins/ragents.lsp-roslyn/web/language-server-plugin";
+
+export const webPlugin = languageServerWebPlugin("ragents.lsp-typescript", LanguageIcon);
+
+function LanguageIcon() {
+  return <span aria-hidden="true" className="font-mono text-[12px] font-bold">TS</span>;
+}

package/plugins/ragents.model-relay/server/config.ts

@@ -0,0 +1,37 @@
+import { declaredEnvironment } from "@aicontainer/server/plugin-support/plugin-config.js";
+
+export const modelRelayConfigDescriptors = [
+  { key: "RELAY_MODELS", source: "environment" },
+] as const;
+
+const env = declaredEnvironment(modelRelayConfigDescriptors);
+
+export interface RelayAlias {
+  readonly alias: string;
+  readonly upstream: string;
+  readonly model: string;
+}
+
+const ALIAS = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** RELAY_MODELS: eine Liste "alias=anbieter/modell"; der Alias ist der einzige Name, den ein Client sieht. */
+export const parseRelayAliases = (entries: readonly string[]): readonly RelayAlias[] => {
+  if (entries.length === 0) throw new Error("RELAY_MODELS nennt kein Modell; erwartet wird eine Liste \"alias=anbieter/modell\"");
+  const aliases = entries.map((entry) => {
+    const separator = entry.indexOf("=");
+    const alias = separator > 0 ? entry.slice(0, separator).trim() : "";
+    const target = separator > 0 ? entry.slice(separator + 1).trim() : "";
+    const slash = target.indexOf("/");
+    if (!ALIAS.test(alias) || slash <= 0 || slash === target.length - 1) {
+      throw new Error(`RELAY_MODELS: "${entry}" hat nicht das Format "alias=anbieter/modell"`);
+    }
+    return { alias, upstream: target.slice(0, slash), model: target.slice(slash + 1) };
+  });
+  const duplicate = aliases.find((entry, index) => aliases.findIndex((other) => other.alias === entry.alias) !== index);
+  if (duplicate) throw new Error(`RELAY_MODELS nennt den Alias ${duplicate.alias} mehrfach`);
+  return aliases;
+};
+
+export const modelRelayConfig = Object.freeze({
+  aliases: () => parseRelayAliases(env.list("RELAY_MODELS")),
+});

package/plugins/ragents.model-relay/server/index.ts

@@ -0,0 +1,31 @@
+import type { RAgentsPlugin } from "@aicontainer/ragents";
+import { modelUpstreamsToken } from "@aicontainer/server/plugin-support/model-upstreams.js";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { Protocol } from "@aicontainer/server/protocol.js";
+import { modelRelayConfig, modelRelayConfigDescriptors } from "./config.js";
+import { createRelayRoutes, resolveAliases, type ResolvedAlias } from "./relay.js";
+
+const modelRelayPlugin: RAgentsPlugin = {
+  manifest: { id: "ragents.model-relay" },
+  register: (host) => {
+    host.config(...modelRelayConfigDescriptors);
+    const upstreams = host.service(modelUpstreamsToken);
+    let resolved: readonly ResolvedAlias[] | undefined;
+    const aliases = (): readonly ResolvedAlias[] => resolved ??= resolveAliases(modelRelayConfig.aliases(), upstreams());
+    const log = new Protocol(host.storage.root("relay.log"));
+    host.lifecycle({
+      id: "ragents.model-relay",
+      initialize: () => {
+        const list = aliases();
+        log.write(`=== Start: ${list.map((entry) => `${entry.alias}=${entry.upstream.id}/${entry.model.id}`).join(", ")} ===`);
+        console.log(`Modell-Relay: ${list.length} Aliasse unter /relay/v1 (${list.map((entry) => entry.alias).join(", ")})`);
+      },
+      shutdown: () => log.close(),
+    });
+    host.http(...createRelayRoutes({ aliases, log: (line) => log.write(line) }));
+  },
+};
+
+export const plugin: PluginModule = {
+  create: () => modelRelayPlugin,
+};

package/plugins/ragents.model-relay/server/relay.ts

@@ -0,0 +1,213 @@
+import type { IncomingMessage } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { ReadableStream } from "node:stream/web";
+import type { Api, Model } from "@aicontainer/ai";
+import type { HttpRouteContribution } from "@aicontainer/ragents";
+import { PayloadTooLargeError, readBody, writeJson } from "@aicontainer/server/plugin-support/http.js";
+import type { ModelUpstream } from "@aicontainer/server/plugin-support/model-upstreams.js";
+import type { RelayAlias } from "./config.js";
+
+export const RELAY_PATH_PREFIX = "/relay/v1";
+export const RELAY_RIGHT = "models.use";
+
+const MAX_REQUEST_BYTES = 64 * 1024 * 1024;
+const MAX_SCAN_BYTES = 8 * 1024 * 1024;
+const DROPPED_HEADERS = new Set(["host", "authorization", "cookie", "content-length", "connection", "transfer-encoding", "accept-encoding", "expect"]);
+
+export interface ResolvedAlias {
+  readonly alias: string;
+  readonly upstream: ModelUpstream;
+  readonly model: Model<Api>;
+}
+
+/** Jeder Alias muss auf einen konfigurierten Anbieter und ein Modell aus dessen Katalog zeigen. */
+export const resolveAliases = (aliases: readonly RelayAlias[], upstreams: readonly ModelUpstream[]): readonly ResolvedAlias[] =>
+  aliases.map((entry) => {
+    const upstream = upstreams.find((candidate) => candidate.id === entry.upstream);
+    if (!upstream) {
+      const available = upstreams.map((candidate) => candidate.id).join(", ") || "keiner";
+      throw new Error(`RELAY_MODELS: der Anbieter ${entry.upstream} hinter ${entry.alias} ist auf diesem Server nicht konfiguriert (verfügbar: ${available})`);
+    }
+    const model = upstream.models.find((candidate) => candidate.id === entry.model);
+    if (!model) throw new Error(`RELAY_MODELS: das Modell ${entry.model} hinter ${entry.alias} fehlt im Katalog von ${entry.upstream}`);
+    return { alias: entry.alias, upstream, model };
+  });
+
+/** Der Katalogeintrag nennt nur, was der Verbraucher für den Draht braucht; Name, Anbieter und Kosten bleiben beim Server. */
+export const catalogEntryOf = (resolved: ResolvedAlias) => ({
+  id: resolved.alias,
+  object: "model" as const,
+  owned_by: "relay",
+  catalog: {
+    reasoning: resolved.model.reasoning,
+    ...(resolved.model.thinkingLevelMap ? { thinkingLevelMap: resolved.model.thinkingLevelMap } : {}),
+    input: [...resolved.model.input],
+    contextWindow: resolved.model.contextWindow,
+    maxTokens: resolved.model.maxTokens,
+    ...(resolved.model.compat ? { compat: resolved.model.compat } : {}),
+  },
+});
+
+interface Usage {
+  readonly prompt: number | undefined;
+  readonly completion: number | undefined;
+}
+
+/** Ersetzt im durchgereichten Strom den echten Modellnamen durch den Alias, entfernt den Anbieter und merkt sich den letzten usage-Block. */
+const responseRewriter = (alias: string) => {
+  const decoder = new TextDecoder();
+  let pending = "";
+  let usage: Usage | undefined;
+  let overflow = false;
+  const rewrite = (text: string): string => {
+    let parsed: unknown;
+    try { parsed = JSON.parse(text); }
+    catch { return text; }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return text;
+    const body = parsed as { model?: unknown; provider?: unknown; usage?: { prompt_tokens?: unknown; completion_tokens?: unknown } };
+    if (body.usage && typeof body.usage === "object") {
+      const number = (value: unknown) => typeof value === "number" ? value : undefined;
+      usage = { prompt: number(body.usage.prompt_tokens), completion: number(body.usage.completion_tokens) };
+    }
+    if (typeof body.model !== "string" && body.provider === undefined) return text;
+    const rest = Object.fromEntries(Object.entries(body).filter(([key]) => key !== "provider"));
+    return JSON.stringify(typeof body.model === "string" ? { ...rest, model: alias } : rest);
+  };
+  const line = (text: string): string => text.startsWith("data: ") ? `data: ${rewrite(text.slice(6))}` : text;
+  return {
+    feed: (chunk: Buffer): string => {
+      const text = decoder.decode(chunk, { stream: true });
+      if (overflow) return text;
+      pending += text;
+      const lines = pending.split("\n");
+      pending = lines.pop() ?? "";
+      const forwarded = lines.map((entry) => `${line(entry)}\n`).join("");
+      if (pending.length <= MAX_SCAN_BYTES) return forwarded;
+      overflow = true;
+      const remainder = pending;
+      pending = "";
+      return `${forwarded}${remainder}`;
+    },
+    finish: (): string => {
+      const rest = overflow || !pending.trim() ? pending : pending.startsWith("data: ") ? line(pending) : rewrite(pending);
+      pending = "";
+      return rest;
+    },
+    usage: (): Usage | undefined => usage,
+  };
+};
+
+const openAiError = (message: string, type: string) => ({ error: { message, type } });
+
+const forwardedHeaders = (request: IncomingMessage, apiKey: string): Record<string, string> => {
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (DROPPED_HEADERS.has(name) || value === undefined) continue;
+    headers[name] = Array.isArray(value) ? value.join(", ") : value;
+  }
+  headers["content-type"] = "application/json";
+  headers.authorization = `Bearer ${apiKey}`;
+  return headers;
+};
+
+export interface RelayRouteOptions {
+  aliases: () => readonly ResolvedAlias[];
+  log: (line: string) => void;
+  fetch?: typeof fetch;
+}
+
+const modelsPath = `${RELAY_PATH_PREFIX}/models`;
+const completionsPath = `${RELAY_PATH_PREFIX}/chat/completions`;
+
+export const createRelayRoutes = (options: RelayRouteOptions): HttpRouteContribution[] => {
+  const fetchImpl = options.fetch ?? fetch;
+  return [
+    {
+      id: "ragents.model-relay.models",
+      isApiPath: (pathname) => pathname.startsWith(`${RELAY_PATH_PREFIX}/`),
+      matches: (request, url) => request.method === "GET" && url.pathname === modelsPath,
+      requiredRights: [RELAY_RIGHT],
+      handle: ({ response }) => {
+        writeJson(response, 200, { object: "list", data: options.aliases().map(catalogEntryOf) });
+      },
+    },
+    {
+      id: "ragents.model-relay.completions",
+      isApiPath: (pathname) => pathname.startsWith(`${RELAY_PATH_PREFIX}/`),
+      matches: (request, url) => request.method === "POST" && url.pathname === completionsPath,
+      requiredRights: [RELAY_RIGHT],
+      handle: async ({ request, response, access }) => {
+        const user = access.user?.id ?? "anonym";
+        let text: string;
+        try {
+          text = await readBody(request, MAX_REQUEST_BYTES);
+        } catch (error) {
+          if (!(error instanceof PayloadTooLargeError)) throw error;
+          writeJson(response, 413, openAiError(error.message, "invalid_request_error"));
+          return;
+        }
+        let parsed: unknown;
+        try { parsed = JSON.parse(text); }
+        catch { parsed = undefined; }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+          writeJson(response, 400, openAiError("Der Anfragekörper ist kein JSON-Objekt", "invalid_request_error"));
+          return;
+        }
+        const alias = (parsed as { model?: unknown }).model;
+        if (typeof alias !== "string" || !alias) {
+          writeJson(response, 400, openAiError("Die Anfrage nennt kein Modell", "invalid_request_error"));
+          return;
+        }
+        const resolved = options.aliases().find((candidate) => candidate.alias === alias);
+        if (!resolved) {
+          writeJson(response, 404, openAiError(`Das Modell ${alias} ist auf diesem Relay unbekannt`, "invalid_request_error"));
+          return;
+        }
+        const controller = new AbortController();
+        response.once("close", () => controller.abort());
+        const target = `${resolved.upstream.baseUrl}/chat/completions`;
+        let upstream: Response;
+        try {
+          upstream = await fetchImpl(target, {
+            method: "POST",
+            headers: forwardedHeaders(request, resolved.upstream.apiKey),
+            body: JSON.stringify({ ...parsed, model: resolved.model.id }),
+            signal: controller.signal,
+          });
+        } catch (error) {
+          if (controller.signal.aborted) return;
+          const reason = error instanceof Error ? error.message : String(error);
+          options.log(`${user} ${alias} -> ${resolved.upstream.id}/${resolved.model.id}: nicht erreichbar (${reason})`);
+          writeJson(response, 502, openAiError(`Der Anbieter hinter ${alias} ist nicht erreichbar`, "server_error"));
+          return;
+        }
+        response.writeHead(upstream.status, {
+          "Content-Type": upstream.headers.get("content-type") ?? "application/octet-stream",
+          "Cache-Control": "no-store",
+        });
+        const rewriter = responseRewriter(alias);
+        if (upstream.body) {
+          const source = Readable.fromWeb(upstream.body as ReadableStream<Uint8Array>);
+          try {
+            await pipeline(source, async function* (chunks: AsyncIterable<Buffer>) {
+              for await (const chunk of chunks) {
+                const forwarded = rewriter.feed(chunk);
+                if (forwarded) yield forwarded;
+              }
+              const rest = rewriter.finish();
+              if (rest) yield rest;
+            }, response);
+          } catch (error) {
+            if (!controller.signal.aborted) throw error;
+          }
+        } else {
+          response.end();
+        }
+        const usage = rewriter.usage();
+        const tokens = usage ? ` tokens in=${usage.prompt ?? "?"} out=${usage.completion ?? "?"}` : "";
+        options.log(`${user} ${alias} -> ${resolved.upstream.id}/${resolved.model.id}: ${upstream.status}${tokens}`);
+      },
+    },
+  ];
+};

package/plugins/ragents.orchestration/canvas.hbs

@@ -0,0 +1,50 @@
+## Designing the canvas
+
+The canvas shows the personally visible actors and actor views of this run. Use
+`context.functions.canvas_layout_replace` from TypeScript to arrange
+existing participants and explain their relationships. Free canvas is the default; do not switch
+to tiles unless the user requests them or the run setup explicitly specifies them. Read its exact input and result types with
+`typescript_api` before constructing a layout; they define the supported entities,
+groups, shapes, connections and size limits.
+
+For a fixed, viewport-filling workspace set mode to "tiled" and supply root. A leaf is
+{entity:"@helper"} or {entity:"app:@workspace/main"}. A split has direction "horizontal"
+(left/right) or "vertical" (top/bottom), two positive weights and exactly two children.
+Children can be split again. For "50:50, app left, chat right", use:
+{mode:"tiled",root:{direction:"horizontal",weights:[1,1],children:[
+  {entity:"app:@workspace/main"},{entity:"@helper"}
+]}}. Use [2,1] for two thirds and one third. Use an outer vertical split and an inner
+horizontal split for one pane above two panes below. Resolve the user's actual actor and app
+names before calling; the example names are not existing participants.
+
+Tiled mode disables canvas pan, zoom and overview. Users with Actors access can remove panes
+and drag actors/apps from the header or pane title onto docking targets. Split dividers remain
+resizable without Actors access.
+Personal user arrangements take precedence over program suggestions until the user resets them.
+Do not repeatedly resend a layout to fight a personal override. Newly created participants stay
+available in the header without changing existing tiles. A mode/root-only call preserves the free
+canvas arrangement; {mode:"free"} restores it. A root-only call implies tiled mode; root:null
+clears the tiles. Free-layout updates supply nodes and replace the explicit nodes, shapes and
+lines together, so include everything that should remain there.
+
+Activate actor programs before placing their views. Reference a view as `app:@handle/view-key`
+or `app:program-name/view-key`, using the handle, program name and view key you chose. The server
+resolves the actual view ID and rejects unknown views before storing the layout. Do not invent
+or copy generated view IDs. The same references work in nodes and connection endpoints.
+`actor_view_set_visibility` uses the same package/view or @handle/view names without the `app:` prefix.
+
+Place the essentials first and update the layout when the participants or flow change. The host
+adds unplaced visible participants and visible actor views automatically in free mode. Actors with their own
+views start hidden; their views remain on the canvas and the Actors list opens their inspector.
+A layout never overrides the user's personal actor visibility or connection choice. The user
+participates through the chat and does not need a separate canvas node.
+
+Choose arrangements by meaning: peers in a discussion, a sequence of work stages, a hierarchy or
+a collection of independent items. Keep groups small enough to read, preserve a useful order and
+add a frame only where a visible boundary helps. Leave space for expanded content and connection
+labels instead of packing cards tightly together.
+
+Connections should explain actual relationships. Give them short, meaningful labels and choose
+direction and line style deliberately. The canvas does not infer the connections for you. Every
+connection must join existing entities. Shapes can represent stages, decisions or topics that are
+not actors; use them to explain the work without inventing additional participants.