@schlenkr/ragents 0.1.0

package/apps/server/src/ragents/start-option-state.ts

@@ -0,0 +1,37 @@
+import { pluginStateKey, type JsonValue, type PluginStateScope, type RunState } from "@aicontainer/ragents";
+import { modelStartOptionId, systemPromptStartOptionId } from "../plugin-support/start-options-contract.js";
+
+export { modelStartOptionId, systemPromptStartOptionId };
+
+export const startOptionScope = Object.freeze({ kind: "run" } satisfies PluginStateScope);
+
+export const storedStartOption = (state: RunState | null, optionId: string): JsonValue | undefined =>
+  state?.pluginStates.get(pluginStateKey(optionId, startOptionScope))?.state;
+
+export interface StoredSystemPrompt {
+  readonly promptIds: readonly string[] | undefined;
+  readonly shareWithAgents: boolean;
+}
+
+export const storedSystemPrompt = (state: RunState | null): StoredSystemPrompt => {
+  const value = storedStartOption(state, systemPromptStartOptionId) as
+    | { promptId?: unknown; promptIds?: unknown; shareWithAgents?: unknown }
+    | undefined;
+  const ids = Array.isArray(value?.promptIds)
+    ? value.promptIds.filter((id): id is string => typeof id === "string")
+    : typeof value?.promptId === "string" ? [value.promptId] : undefined;
+  return {
+    promptIds: ids,
+    shareWithAgents: value?.shareWithAgents === true,
+  };
+};
+
+export const storedModel = (state: RunState | null): string | undefined => {
+  const value = (storedStartOption(state, modelStartOptionId) as { model?: unknown } | undefined)?.model;
+  return typeof value === "string" && value ? value : undefined;
+};
+
+export const storedThinking = (state: RunState | null): string | undefined => {
+  const value = (storedStartOption(state, modelStartOptionId) as { thinking?: unknown } | undefined)?.thinking;
+  return typeof value === "string" && value ? value : undefined;
+};

package/apps/server/src/ragents/typescript-tools.ts

@@ -0,0 +1,182 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { Type } from "typebox";
+import {
+    assertJsonValue,
+    defineRunFunction,
+    defineToolAvailability,
+    executeTypeScriptSnippet,
+    typeScriptSnippetDeclarations,
+    type RunCapabilityDescriptor,
+    type RunFunction,
+    type PluginHost,
+    type ToolContributor,
+    type ToolScope,
+} from "@aicontainer/ragents";
+import { allowedWorkspacePath, expandWorkspaceAlias, type WorkspaceProcessContext } from "@aicontainer/workspace-executor";
+import { sandboxServicesToken } from "../plugin-support/workspace-sandbox-host.js";
+
+const metadata = [
+    {
+        name: "typescript_api",
+        label: "TypeScript API",
+        description: "Discover the typed functions available to this actor. Omit names for a compact searchable list; pass exact names for their TypeScript declarations with field documentation and the matching guidance. JSON schemas with validation constraints are added only on request. Functions are called as await context.functions.name(input) from snippets and actor programs.",
+    },
+    {
+        name: "typescript_eval",
+        label: "Evaluate TypeScript",
+        description: "Typecheck and execute a one-off TypeScript snippet as the calling actor, with the same context.functions API as actor programs. Supply code or a workspace path containing an async function body: await and return are supported; use await import() for Node modules. Return a JSON value; no return yields null. context.log captures output. Locals and context.state last for this execution only. Function calls can change the run and are not rolled back on later failure. Use an actor program for persistent state and future messages or events.",
+    },
+] as const;
+
+const available = defineToolAvailability({
+    availability: "conditional",
+    availabilityDetail: "Für aktive ausführbare Actors mit einer Funktionsauswahl.",
+}, (actor) => actor.kind !== "human" && actor.lifecycle.kind !== "stopped");
+
+export interface TypeScriptToolOptions {
+    readonly processContextFor: (runId: string) => Promise<WorkspaceProcessContext>;
+}
+
+const functionsOf = (scope: ToolScope): readonly RunFunction[] => scope.availableFunctions()
+    .filter((entry) => !metadata.some((tool) => tool.name === entry.name))
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+const descriptorOf = (entry: RunFunction): RunCapabilityDescriptor => ({
+    id: entry.name,
+    label: entry.label,
+    description: entry.description,
+    schema: entry.schema,
+    resultSchema: entry.resultSchema,
+});
+
+const apiEntrySchema = Type.Object({
+    name: Type.String(),
+    label: Type.String(),
+    description: Type.String(),
+    longDescription: Type.Optional(Type.String()),
+    inputSchema: Type.Optional(Type.Unknown()),
+    resultSchema: Type.Optional(Type.Unknown()),
+}, { additionalProperties: false });
+
+const schemaJson = (schema: RunFunction["schema"]) => {
+    const value: unknown = JSON.parse(JSON.stringify(schema));
+    assertJsonValue(value, "Function schema");
+    return value;
+};
+
+const sourceOf = async (input: { code?: string; path?: string }, context: WorkspaceProcessContext): Promise<string> => {
+    if (input.code !== undefined) return input.code;
+    const requested = expandWorkspaceAlias(input.path!, context.workspaceAliases ?? {});
+    const filename = await allowedWorkspacePath(path.resolve(context.cwd, requested), [context.root, context.cwd, ...context.additionalRoots ?? []]);
+    return readFile(filename, "utf8");
+};
+
+export const createTypeScriptToolContributor = (options: TypeScriptToolOptions): ToolContributor => {
+    const tools: readonly RunFunction[] = [
+        defineRunFunction({
+            ...metadata[0],
+            nativeTool: true,
+            available,
+            executionMode: "parallel",
+            schema: Type.Object({
+                query: Type.Optional(Type.String({ minLength: 1, description: "Search names and descriptions. Omit for all available names." })),
+                names: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1, uniqueItems: true, description: "Exact function names whose complete declarations and guidance are needed." })),
+                schemas: Type.Optional(Type.Boolean({ description: "With names: also return the JSON schemas including validation constraints such as lengths and patterns." })),
+            }, { additionalProperties: false }),
+            resultSchema: Type.Object({
+                functions: Type.Array(apiEntrySchema),
+                declarations: Type.Optional(Type.String()),
+                guidance: Type.Optional(Type.String()),
+            }, { additionalProperties: false }),
+            run: async (scope, _id, input) => {
+                if (input.names && input.query !== undefined) throw new Error("typescript_api erwartet names oder query, nicht beides.");
+                if (input.schemas && !input.names) throw new Error("typescript_api liefert JSON-Schemas nur zu ausgewählten names.");
+                const functions = functionsOf(scope);
+                if (input.names) {
+                    const unknown = input.names.filter((name) => !functions.some((entry) => entry.name === name));
+                    if (unknown.length > 0) throw new Error(`Nicht verfügbare TypeScript-Funktionen: ${unknown.join(", ")}. Mit typescript_api ohne names verfügbare Funktionen nachschlagen.`);
+                }
+                const query = input.query?.toLocaleLowerCase();
+                const selected = input.names ? functions.filter((entry) => input.names!.includes(entry.name))
+                    : query ? functions.filter((entry) => `${entry.name} ${entry.label} ${entry.description}`.toLocaleLowerCase().includes(query)) : functions;
+                return {
+                    functions: selected.map(({ name, label, description, longDescription, schema, resultSchema }) => ({
+                        name, label, description,
+                        ...(input.names && longDescription ? { longDescription } : {}),
+                        ...(input.schemas ? { inputSchema: schemaJson(schema), resultSchema: schemaJson(resultSchema) } : {}),
+                    })),
+                    ...(input.names ? {
+                        declarations: typeScriptSnippetDeclarations(selected.map(descriptorOf)),
+                        guidance: [
+                            "The context belongs to the calling actor: functions act as context.principal. In a snippet, context.state starts as {} and is discarded when it finishes. Actor programs retain their declared state and can receive later inputs. TypeScript checks calls against the declared input and result types before execution; schema constraints are also validated by the host.",
+                            await scope.functionGuidance(input.names),
+                        ].filter(Boolean).join("\n\n"),
+                    } : {}),
+                };
+            },
+        }),
+        defineRunFunction({
+            ...metadata[1],
+            nativeTool: true,
+            available,
+            executionMode: "sequential",
+            schema: Type.Object({
+                code: Type.Optional(Type.String({ minLength: 1, description: "Async TypeScript function body. context is supplied; await and return work directly." })),
+                path: Type.Optional(Type.String({ minLength: 1, description: "Workspace file containing the same snippet body. Use a relative path or an existing workspace alias such as @actors; generated absolute paths are not needed." })),
+            }, { additionalProperties: false }),
+            resultSchema: Type.Object({ result: Type.Unknown(), logs: Type.Array(Type.String()) }, { additionalProperties: false }),
+            run: async (scope, id, input) => {
+                if ((input.code === undefined) === (input.path === undefined)) throw new Error("typescript_eval braucht genau eines von code oder path.");
+                scope.signal?.throwIfAborted();
+                const actor = scope.runtime.view(scope.caller.runId).actors.find((candidate) => candidate.id === scope.caller.actorId);
+                if (!actor || actor.kind === "human" || actor.lifecycle.kind === "stopped") throw new Error("Das TypeScript-Snippet braucht einen aktiven ausführbaren Actor.");
+                const processContext = await options.processContextFor(scope.caller.runId);
+                const code = await sourceOf(input, processContext);
+                if (!scope.caller.turnId) throw new Error("Das TypeScript-Snippet braucht einen laufenden Turn.");
+                scope.runtime.recordToolCallSource(scope.context(id, "source"), scope.caller.runId, actor.id, {
+                    turnId: scope.caller.turnId, toolCallId: id, code, path: input.path ?? null,
+                });
+                const capabilities = functionsOf(scope).map(descriptorOf);
+                let callIndex = 0;
+                const output = await executeTypeScriptSnippet({
+                    code,
+                    capabilities,
+                    cwd: processContext.cwd,
+                    signal: scope.signal,
+                    executor: scope.runtime.nativeTypeScriptExecutor,
+                    context: {
+                        runId: scope.caller.runId,
+                        invocationId: id,
+                        actor: { id: actor.id, handle: actor.handle },
+                        principal: { id: actor.id, kind: actor.kind === "script" ? "script" : "agent" },
+                    },
+                    call: (name, value) => scope.invokeFunction(`${id}:function:${++callIndex}`, name, value),
+                });
+                return { result: output.result, logs: output.logs };
+            },
+        }),
+    ];
+    return {
+        name: "ragents.typescript",
+        descriptors: tools.map((entry) => ({
+            name: entry.name,
+            description: entry.description,
+            nativeTool: true,
+            scope: "per-turn",
+            availability: "conditional",
+            availabilityDetail: "Für aktive ausführbare Actors mit einer Funktionsauswahl.",
+        })),
+        tools: () => tools,
+    };
+};
+
+const registeredHosts = new WeakSet<PluginHost>();
+
+export const registerTypeScriptFunctions = (host: PluginHost): void => {
+    if (registeredHosts.has(host)) return;
+    host.tools.register("ragents.runtime", [createTypeScriptToolContributor({
+        processContextFor: (runId) => host.service(sandboxServicesToken).processContextFor(runId),
+    })]);
+    registeredHosts.add(host);
+};

package/apps/server/src/ragents/workspace-runtime.ts

@@ -0,0 +1,64 @@
+import { serviceToken, type JsonValue, type WorkspaceToolNaming } from "@aicontainer/ragents";
+import type { ResolvedWorkspaceRoot } from "@aicontainer/workspace-executor";
+
+export interface SessionWorkspace {
+  cwd: string;
+  hostSandbox?: { home: string; readOnlyRoots: readonly ResolvedWorkspaceRoot[] };
+  gitEnv?: NodeJS.ProcessEnv;
+  gitConfig?: ReadonlyArray<readonly [string, string]>;
+  extraEnv?: NodeJS.ProcessEnv;
+  currentRoot: () => Promise<string>;
+  ensureWritable: () => Promise<string>;
+  runOperation: <T>(operation: () => Promise<T>) => Promise<T>;
+}
+
+export interface WorkspaceRuntimeDescription {
+  mode: string;
+  directoryPattern: string;
+}
+
+/** Umzug eines Runs auf einen anderen Server: was seine Bindung dort bedeutet und wie das Ziel sie ersetzt. */
+export interface WorkspaceTransfer {
+  /** Der Projektordner auf diesem Serverrechner, an den der Run gebunden ist; null, wenn der Arbeitsbereich in der Session-Ablage liegt. */
+  boundDirectory: (runId: string) => string | null;
+  /** Prüft einen Ersatzordner, bevor der Import etwas anlegt. */
+  assertDirectory: (directory: string) => void;
+  /** Bindet den Run auf dem Ziel an einen vorhandenen Ersatzordner. */
+  rebind: (runId: string, directory: string) => void;
+}
+
+export interface WorkspaceRuntime {
+  resolve: (runId: string, emitSystem: (text: string) => void) => Promise<SessionWorkspace>;
+  describe: () => WorkspaceRuntimeDescription;
+  toolNaming?: WorkspaceToolNaming;
+  transfer?: WorkspaceTransfer;
+}
+
+export const workspaceRuntimeToken = serviceToken<WorkspaceRuntime>("ragents.workspace-runtime");
+
+export interface WorkspaceResolverContext {
+  runId: string;
+  directory: string;
+  choice: JsonValue | null;
+  emitSystem: (text: string) => void;
+}
+
+export interface WorkspaceResolution {
+  cwd: string;
+  extraEnv?: NodeJS.ProcessEnv;
+}
+
+export interface WorkspaceResolver {
+  optionId?: string;
+  resolve: (context: WorkspaceResolverContext) => Promise<WorkspaceResolution>;
+}
+
+export const workspaceResolverToken = serviceToken<WorkspaceResolver>("ragents.workspace-resolver");
+
+export interface GitWorkspaceView {
+  branch: (runId: string) => Promise<string | undefined>;
+  changes: (runId: string) => Promise<unknown>;
+  file: (runId: string, filePath: string, view: "diff" | "current") => Promise<unknown>;
+}
+
+export const gitWorkspaceViewToken = serviceToken<GitWorkspaceView>("ragents.git-workspace-view");

package/apps/server/src/rpc/dispatcher.ts

@@ -0,0 +1,178 @@
+import { randomUUID } from "node:crypto";
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+import {
+  DomainError,
+  RPC_ERROR_CODES,
+  RPC_METHODS,
+  RpcError,
+  type AccessContext,
+  type ChannelContributionRegistry,
+  type JsonValue,
+  type MethodConnection,
+  type MethodContributionRegistry,
+  type OperationContract,
+  type OperationInput,
+  type OperationResult,
+  type RpcCallOptions,
+  type RpcEventParams,
+  type RpcHandlerContext,
+  type RpcPeer,
+  type RpcSubscribeParams,
+  type RpcSubscribeResult,
+  type RpcUnsubscribeParams,
+} from "@aicontainer/ragents";
+
+const MAX_SUBSCRIPTIONS = 64;
+
+export interface RpcConnectionOptions {
+  id: string;
+  access: AccessContext;
+  local: boolean;
+  peer: RpcPeer;
+  /** Ohne Ereignisstrom erreichen Benachrichtigungen den Client nicht; Abonnements sind dann abgelehnt. */
+  streamless?: boolean;
+}
+
+const firstComplaint = (schema: TSchema, value: unknown): string =>
+  [...Value.Errors(schema, value)].at(0)?.message ?? "Schema nicht erfüllt";
+
+/** Eine Verbindung eines Clients: hält ihre Abonnements und ist der Rückweg für Anfragen des Servers. */
+export class RpcConnection implements MethodConnection {
+  readonly id: string;
+  readonly access: AccessContext;
+  readonly local: boolean;
+  readonly peer: RpcPeer;
+  readonly streamless: boolean;
+  readonly subscriptions = new Map<string, () => void>();
+  readonly #closeListeners = new Set<() => void>();
+  #closed = false;
+
+  constructor(options: RpcConnectionOptions, dispatcher: RpcDispatcher) {
+    this.id = options.id;
+    this.access = options.access;
+    this.local = options.local;
+    this.peer = options.peer;
+    this.streamless = options.streamless ?? false;
+    this.peer.fallback((method, params, context) => dispatcher.dispatch(this, method, params, context));
+  }
+
+  get userId(): string | null {
+    return this.access.user?.id ?? null;
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  call<C extends OperationContract>(contract: C, input: OperationInput<C>, options?: RpcCallOptions): Promise<OperationResult<C>> {
+    if (contract.implementedBy !== "client") return Promise.reject(new Error(`Die Operation ${contract.id} wird vom Server ausgeführt, nicht vom Client`));
+    if (this.streamless) return Promise.reject(new DomainError("stream-required", "Der Rückruf an den Client braucht einen Ereignisstrom.", 409));
+    return this.peer.call(contract, input, options);
+  }
+
+  onClose(listener: () => void): () => void {
+    this.#closeListeners.add(listener);
+    return () => { this.#closeListeners.delete(listener); };
+  }
+
+  close(reason: string): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const stop of this.subscriptions.values()) stop();
+    this.subscriptions.clear();
+    this.peer.close(reason);
+    for (const listener of [...this.#closeListeners]) listener();
+    this.#closeListeners.clear();
+  }
+}
+
+export interface RpcDispatcherOptions {
+  methods: MethodContributionRegistry;
+  channels: ChannelContributionRegistry;
+}
+
+/** Führt Anfragen einer Verbindung gegen die registrierten Verträge aus: Rechte, Eingabe, Ausführung, Antwort. */
+export class RpcDispatcher {
+  readonly #options: RpcDispatcherOptions;
+
+  constructor(options: RpcDispatcherOptions) {
+    this.#options = options;
+  }
+
+  async dispatch(connection: RpcConnection, method: string, params: unknown, context: RpcHandlerContext): Promise<unknown> {
+    if (method === RPC_METHODS.subscribe) return this.#subscribe(connection, params);
+    if (method === RPC_METHODS.unsubscribe) return this.#unsubscribe(connection, params);
+    const found = this.#options.methods.find(method);
+    if (!found || found.contribution.contract.implementedBy === "client") {
+      throw new RpcError(RPC_ERROR_CODES.methodNotFound, `Unbekannte Methode: ${method}`);
+    }
+    const { contract, execute } = found.contribution;
+    assertRights(connection.access, contract.rights);
+    const input = params === undefined ? {} : params;
+    if (!Value.Check(contract.input, input)) {
+      throw new RpcError(RPC_ERROR_CODES.invalidParams, `Ungültige Eingabe für ${method}: ${firstComplaint(contract.input, input)}`);
+    }
+    const result = await execute(input, {
+      access: connection.access,
+      signal: context.signal,
+      progress: (value: JsonValue) => context.progress(value),
+      connection,
+      local: connection.local,
+    });
+    const plain = result === undefined ? null : JSON.parse(JSON.stringify(result)) as unknown;
+    if (!Value.Check(contract.result, plain)) {
+      const complaint = firstComplaint(contract.result, plain);
+      console.error(`Die Antwort von ${method} verletzt ihren Vertrag: ${complaint}`);
+      throw new RpcError(RPC_ERROR_CODES.internal, `Die Antwort von ${method} verletzt ihren Vertrag: ${complaint}`);
+    }
+    return plain;
+  }
+
+  async #subscribe(connection: RpcConnection, params: unknown): Promise<RpcSubscribeResult> {
+    const { channel, params: channelParams } = (params ?? {}) as Partial<RpcSubscribeParams>;
+    if (typeof channel !== "string") throw new RpcError(RPC_ERROR_CODES.invalidParams, "channel fehlt");
+    if (connection.streamless) throw new DomainError("stream-required", "Abonnements brauchen einen Ereignisstrom.", 409);
+    const found = this.#options.channels.find(channel);
+    if (!found) throw new DomainError("unknown-channel", `Unbekannter Ereigniskanal: ${channel}`, 400);
+    const { contract, open } = found.contribution;
+    assertRights(connection.access, contract.rights);
+    const input = channelParams === undefined ? {} : channelParams;
+    if (!Value.Check(contract.params, input)) {
+      throw new RpcError(RPC_ERROR_CODES.invalidParams, `Ungültige Parameter für ${channel}: ${firstComplaint(contract.params, input)}`);
+    }
+    if (connection.subscriptions.size >= MAX_SUBSCRIPTIONS) throw new DomainError("too-many-channels", "Zu viele Ereigniskanäle auf einer Verbindung.", 429);
+    const subscription = randomUUID();
+    const buffered: unknown[] = [];
+    let opening = true;
+    const send = (message: unknown) => connection.peer.notify(RPC_METHODS.event, { subscription, channel, message } satisfies RpcEventParams);
+    const emit = (message: unknown) => {
+      if (opening) buffered.push(message);
+      else if (connection.subscriptions.has(subscription)) send(message);
+    };
+    const stop = await open(input, emit, { access: connection.access, connection });
+    opening = false;
+    if (connection.closed) {
+      stop();
+      throw new DomainError("connection-closed", "Die Ereignisverbindung wurde beendet.", 410);
+    }
+    connection.subscriptions.set(subscription, stop);
+    // Erst die Antwort auf das Abonnement, dann die beim Öffnen entstandenen Nachrichten.
+    setTimeout(() => { if (connection.subscriptions.has(subscription)) for (const message of buffered) send(message); }, 0);
+    return { subscription };
+  }
+
+  #unsubscribe(connection: RpcConnection, params: unknown): null {
+    const { subscription } = (params ?? {}) as Partial<RpcUnsubscribeParams>;
+    if (typeof subscription !== "string") throw new RpcError(RPC_ERROR_CODES.invalidParams, "subscription fehlt");
+    const stop = connection.subscriptions.get(subscription);
+    connection.subscriptions.delete(subscription);
+    stop?.();
+    return null;
+  }
+}
+
+export const assertRights = (access: AccessContext, rights: readonly string[]): void => {
+  const missing = rights.find((right) => !access.can(right));
+  if (missing) throw new DomainError("access-denied", `Das Recht ${missing} fehlt.`, 403);
+};

package/apps/server/src/rpc/http-transport.ts

@@ -0,0 +1,178 @@
+import { randomBytes } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  isRpcMessage,
+  isRpcRequest,
+  isRpcResponse,
+  RPC_ERROR_CODES,
+  RPC_METHODS,
+  RpcPeer,
+  rpcFailure,
+  type AccessContext,
+  type RpcMessage,
+} from "@aicontainer/ragents";
+import { PayloadTooLargeError, readBody, writeJson } from "../plugin-support/http.js";
+import { RpcConnection, type RpcDispatcher } from "./dispatcher.js";
+
+export const RPC_PATH = "/rpc";
+export const RPC_STREAM_PATH = "/rpc/stream";
+export const RPC_CONNECTION_HEADER = "x-ragents-connection";
+
+const PING_INTERVAL_MS = 15_000;
+const DEFAULT_MAX_BODY_BYTES = 32 * 1024 * 1024;
+
+interface StreamConnection {
+  connection: RpcConnection;
+  response: ServerResponse;
+  ping: NodeJS.Timeout;
+}
+
+export interface RpcHttpTransportOptions {
+  dispatcher: RpcDispatcher;
+  maxBodyBytes?: number;
+}
+
+export const isRpcPath = (pathname: string): boolean => pathname === RPC_PATH || pathname === RPC_STREAM_PATH;
+
+/** JSON-RPC über HTTP: Anfragen per POST, Benachrichtigungen und Anfragen des Servers über einen SSE-Strom je Verbindung. */
+export class RpcHttpTransport {
+  readonly #dispatcher: RpcDispatcher;
+  readonly #maxBodyBytes: number;
+  readonly #streams = new Map<string, StreamConnection>();
+
+  constructor(options: RpcHttpTransportOptions) {
+    this.#dispatcher = options.dispatcher;
+    this.#maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+  }
+
+  connectionCount(): number {
+    return this.#streams.size;
+  }
+
+  async handle(request: IncomingMessage, response: ServerResponse, url: URL, access: AccessContext, local: boolean): Promise<boolean> {
+    if (url.pathname === RPC_STREAM_PATH) {
+      if (request.method !== "GET") {
+        response.setHeader("Allow", "GET");
+        writeJson(response, 405, { error: "Methode nicht erlaubt" });
+        return true;
+      }
+      this.#openStream(request, response, access, local);
+      return true;
+    }
+    if (url.pathname !== RPC_PATH) return false;
+    if (request.method !== "POST") {
+      response.setHeader("Allow", "POST");
+      writeJson(response, 405, { error: "Methode nicht erlaubt" });
+      return true;
+    }
+    await this.#post(request, response, access, local);
+    return true;
+  }
+
+  close(): void {
+    for (const stream of [...this.#streams.values()]) this.#end(stream, "Der Server wird beendet");
+  }
+
+  #openStream(request: IncomingMessage, response: ServerResponse, access: AccessContext, local: boolean): void {
+    const id = randomBytes(16).toString("hex");
+    const write = (payload: string) => {
+      if (!response.writableEnded && !response.destroyed) response.write(payload);
+    };
+    const peer = new RpcPeer({ send: (message) => write(`data: ${JSON.stringify(message)}\n\n`) });
+    const connection = new RpcConnection({ id, access, local, peer }, this.#dispatcher);
+    const stream: StreamConnection = { connection, response, ping: setInterval(() => write(": ping\n\n"), PING_INTERVAL_MS) };
+    this.#streams.set(id, stream);
+    response.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" });
+    write(`event: hello\ndata: ${JSON.stringify({ connection: id })}\n\n`);
+    request.on("close", () => this.#end(stream, "Der Ereignisstrom wurde beendet"));
+  }
+
+  #end(stream: StreamConnection, reason: string): void {
+    if (!this.#streams.delete(stream.connection.id)) return;
+    clearInterval(stream.ping);
+    stream.connection.close(reason);
+    if (!stream.response.writableEnded) stream.response.end();
+  }
+
+  #streamFor(request: IncomingMessage, access: AccessContext): StreamConnection | undefined {
+    const header = request.headers[RPC_CONNECTION_HEADER];
+    const id = Array.isArray(header) ? header[0] : header;
+    if (!id) return undefined;
+    const stream = this.#streams.get(id);
+    if (!stream) throw new DomainRejection(404, "unknown-connection", "Die Ereignisverbindung ist unbekannt oder beendet.");
+    if (stream.connection.userId !== (access.user?.id ?? null)) throw new DomainRejection(403, "foreign-connection", "Die Ereignisverbindung gehört einem anderen Benutzer.");
+    return stream;
+  }
+
+  async #post(request: IncomingMessage, response: ServerResponse, access: AccessContext, local: boolean): Promise<void> {
+    let message: unknown;
+    try {
+      message = JSON.parse(await readBody(request, this.#maxBodyBytes));
+    } catch (error) {
+      if (error instanceof PayloadTooLargeError) {
+        writeJson(response, 413, rpcFailure(null, RPC_ERROR_CODES.invalidRequest, error.message));
+        return;
+      }
+      writeJson(response, 400, rpcFailure(null, RPC_ERROR_CODES.parse, "Der Request enthält kein gültiges JSON"));
+      return;
+    }
+    if (!isRpcMessage(message)) {
+      writeJson(response, 400, rpcFailure(null, RPC_ERROR_CODES.invalidRequest, "Die Nachricht ist kein gültiges JSON-RPC"));
+      return;
+    }
+    let stream: StreamConnection | undefined;
+    try {
+      stream = this.#streamFor(request, access);
+    } catch (error) {
+      if (error instanceof DomainRejection) {
+        writeJson(response, error.status, rpcFailure(isRpcRequest(message) ? message.id : null, RPC_ERROR_CODES.application, error.message, { code: error.code, status: error.status }));
+        return;
+      }
+      throw error;
+    }
+    if (!isRpcRequest(message)) {
+      if (!stream) {
+        writeJson(response, 409, rpcFailure(null, RPC_ERROR_CODES.invalidRequest, "Benachrichtigungen und Antworten brauchen einen Ereignisstrom."));
+        return;
+      }
+      stream.connection.peer.receive(message);
+      response.writeHead(202, { "Cache-Control": "no-store" });
+      response.end();
+      return;
+    }
+    await this.#answer(request, response, message, stream, access, local);
+  }
+
+  /** Eine Anfrage bekommt ihren eigenen Peer, dessen Antwort die HTTP-Antwort ist; Abonnements landen auf dem Strom. */
+  #answer(request: IncomingMessage, response: ServerResponse, message: RpcMessage, stream: StreamConnection | undefined, access: AccessContext, local: boolean): Promise<void> {
+    return new Promise<void>((resolve) => {
+      let answered = false;
+      const peer = new RpcPeer({
+        send: (reply) => {
+          if (!isRpcResponse(reply)) {
+            stream?.connection.peer.notify(reply.method, reply.params);
+            return;
+          }
+          if (answered) return;
+          answered = true;
+          writeJson(response, 200, reply);
+          resolve();
+        },
+      });
+      const target = stream?.connection ?? new RpcConnection({ id: `request-${randomBytes(8).toString("hex")}`, access, local, peer, streamless: true }, this.#dispatcher);
+      peer.fallback((method, params, context) => this.#dispatcher.dispatch(target, method, params, context));
+      request.on("close", () => {
+        if (answered) return;
+        peer.receive({ jsonrpc: "2.0", method: RPC_METHODS.cancel, params: { id: (message as { id: unknown }).id } });
+      });
+      response.on("close", () => { if (!answered) { answered = true; resolve(); } });
+      peer.receive(message);
+    });
+  }
+}
+
+class DomainRejection extends Error {
+  constructor(readonly status: number, readonly code: string, message: string) {
+    super(message);
+  }
+}