@schlenkr/ragents 0.1.0

package/packages/ragents/src/typescript/async-compiler.ts

@@ -0,0 +1,322 @@
+import { Worker, type ResourceLimits } from "node:worker_threads";
+import { performance } from "node:perf_hooks";
+
+import type {
+    CompileVirtualTypeScriptRequest,
+    VirtualTypeScriptCompilation,
+} from "./compiler.ts";
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_TIMEOUT_MS = 180_000;
+const MAX_CONCURRENT_COMPILERS = 8;
+const MAX_COMPILER_FILES = 128;
+const MAX_COMPILER_INPUT_BYTES = 2 * 1024 * 1024;
+const COMPILER_RESOURCE_LIMITS = {
+    maxOldGenerationSizeMb: 256,
+    maxYoungGenerationSizeMb: 16,
+    stackSizeMb: 4,
+} as const satisfies ResourceLimits;
+
+export interface CompileVirtualTypeScriptAsyncOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal | undefined;
+}
+
+export type VirtualTypeScriptWorkerErrorCode =
+    | "ABORTED"
+    | "COMPILER_EXCEPTION"
+    | "TIMEOUT"
+    | "WORKER_FAILURE";
+
+export class VirtualTypeScriptWorkerError extends Error {
+    readonly code: VirtualTypeScriptWorkerErrorCode;
+
+    constructor(code: VirtualTypeScriptWorkerErrorCode, message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = "VirtualTypeScriptWorkerError";
+        this.code = code;
+    }
+}
+
+interface PooledWorker {
+    readonly worker: Worker;
+    busy: boolean;
+}
+
+interface WorkerWaiter {
+    readonly activate: (pooled: PooledWorker) => void;
+}
+
+const pool: PooledWorker[] = [];
+const workerWaiters: WorkerWaiter[] = [];
+let nextRequestId = 0;
+
+const spawnWorker = (): PooledWorker => {
+    const worker = new Worker(new URL("./compiler-worker.ts", import.meta.url), {
+        execArgv: [],
+        name: "ragents-typescript-compiler",
+        resourceLimits: COMPILER_RESOURCE_LIMITS,
+    });
+    worker.unref();
+    const pooled: PooledWorker = { worker, busy: false };
+    const forget = (): void => {
+        const index = pool.indexOf(pooled);
+        if (index >= 0) pool.splice(index, 1);
+    };
+    worker.on("error", forget);
+    worker.on("exit", forget);
+    pool.push(pooled);
+    return pooled;
+};
+
+const discardWorker = (pooled: PooledWorker): Promise<number> => {
+    const index = pool.indexOf(pooled);
+    if (index >= 0) pool.splice(index, 1);
+    return pooled.worker.terminate();
+};
+
+const releaseWorker = (pooled: PooledWorker): void => {
+    pooled.busy = false;
+    const waiter = workerWaiters.shift();
+    if (waiter) waiter.activate(pooled);
+};
+
+const idleWorker = (): PooledWorker | undefined => {
+    const idle = pool.find((pooled) => !pooled.busy);
+    if (idle) return idle;
+    return pool.length < MAX_CONCURRENT_COMPILERS ? spawnWorker() : undefined;
+};
+
+export const typeScriptCompilerPool = (): { readonly threadIds: readonly number[]; readonly busy: number } => ({
+    threadIds: pool.map((pooled) => pooled.worker.threadId),
+    busy: pool.filter((pooled) => pooled.busy).length,
+});
+
+export const closeTypeScriptCompilers = async (): Promise<void> => {
+    await Promise.all([...pool].map((pooled) => discardWorker(pooled)));
+};
+
+const acquireWorker = (
+    deadline: number,
+    timeoutMs: number,
+    signal: AbortSignal | undefined,
+): Promise<PooledWorker> => new Promise((resolve, reject) => {
+    let settled = false;
+    let waiter: WorkerWaiter | undefined;
+    const removeWaiter = (): void => {
+        if (!waiter) return;
+        const index = workerWaiters.indexOf(waiter);
+        if (index >= 0) workerWaiters.splice(index, 1);
+    };
+    const cleanup = (): void => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        removeWaiter();
+    };
+    const fail = (error: VirtualTypeScriptWorkerError): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+    };
+    const activate = (pooled: PooledWorker | undefined): void => {
+        if (settled) {
+            if (pooled) releaseWorker(pooled);
+            return;
+        }
+        if (!pooled) {
+            waiter = { activate };
+            workerWaiters.push(waiter);
+            return;
+        }
+        settled = true;
+        cleanup();
+        pooled.busy = true;
+        resolve(pooled);
+    };
+    const onAbort = (): void => fail(new VirtualTypeScriptWorkerError(
+        "ABORTED",
+        "Die TypeScript-Kompilierung wurde abgebrochen.",
+        { cause: signal?.reason },
+    ));
+    const timer = setTimeout(() => fail(new VirtualTypeScriptWorkerError(
+        "TIMEOUT",
+        `Der TypeScript-Compiler hat die Zeitgrenze von ${timeoutMs} ms überschritten.`,
+    )), Math.max(0, deadline - performance.now()));
+
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    else {
+        try { activate(idleWorker()); }
+        catch (error) {
+            fail(new VirtualTypeScriptWorkerError(
+                "WORKER_FAILURE",
+                "Der TypeScript-Compiler-Worker konnte nicht gestartet werden.",
+                { cause: error },
+            ));
+        }
+    }
+});
+
+interface SerializedWorkerError {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+}
+
+type CompilerWorkerMessage = {
+    readonly kind: "result";
+    readonly requestId: number;
+    readonly compilation: VirtualTypeScriptCompilation;
+} | {
+    readonly kind: "error";
+    readonly requestId: number;
+    readonly error: SerializedWorkerError;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    value !== null && typeof value === "object" && !Array.isArray(value);
+
+const isSerializedError = (value: unknown): value is SerializedWorkerError =>
+    isRecord(value)
+    && typeof value.name === "string"
+    && typeof value.message === "string"
+    && (value.stack === undefined || typeof value.stack === "string");
+
+const isWorkerMessage = (value: unknown): value is CompilerWorkerMessage => {
+    if (!isRecord(value) || typeof value.requestId !== "number") return false;
+    if (value.kind === "result") return isRecord(value.compilation);
+    return value.kind === "error" && isSerializedError(value.error);
+};
+
+const timeoutOf = (options: CompileVirtualTypeScriptAsyncOptions | undefined): number => {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
+        throw new RangeError(`TypeScript-Compiler-Timeout muss zwischen 1 und ${MAX_TIMEOUT_MS} ms liegen.`);
+    }
+    return timeoutMs;
+};
+
+const validateRequestSize = (request: CompileVirtualTypeScriptRequest): void => {
+    const files = [...request.sources, ...(request.declarations ?? [])];
+    if (files.length > MAX_COMPILER_FILES)
+        throw new RangeError(`Eine TypeScript-Kompilierung darf höchstens ${MAX_COMPILER_FILES} Dateien enthalten.`);
+    const bytes = files.reduce((size, file) =>
+        size + Buffer.byteLength(file.fileName, "utf8") + Buffer.byteLength(file.text, "utf8"),
+    Buffer.byteLength(request.contract ?? "", "utf8"));
+    if (bytes > MAX_COMPILER_INPUT_BYTES)
+        throw new RangeError(`Die TypeScript-Compiler-Eingabe darf höchstens ${MAX_COMPILER_INPUT_BYTES} Byte groß sein.`);
+};
+
+const remoteError = (error: SerializedWorkerError): Error => {
+    const remote = new Error(error.message);
+    remote.name = error.name;
+    if (error.stack !== undefined) remote.stack = error.stack;
+    return remote;
+};
+
+export const compileVirtualTypeScriptAsync = async (
+    request: CompileVirtualTypeScriptRequest,
+    options?: CompileVirtualTypeScriptAsyncOptions,
+): Promise<VirtualTypeScriptCompilation> => {
+    validateRequestSize(request);
+    const timeoutMs = timeoutOf(options);
+    const deadline = performance.now() + timeoutMs;
+    const pooled = await acquireWorker(deadline, timeoutMs, options?.signal);
+    const { worker } = pooled;
+    const requestId = ++nextRequestId;
+
+    return await new Promise<VirtualTypeScriptCompilation>((resolve, reject) => {
+        let settled = false;
+        const cleanup = (): void => {
+            clearTimeout(timer);
+            options?.signal?.removeEventListener("abort", onAbort);
+            worker.removeListener("message", onMessage);
+            worker.removeListener("messageerror", onMessageError);
+            worker.removeListener("error", onError);
+            worker.removeListener("exit", onExit);
+        };
+        const finish = (
+            result: { readonly compilation: VirtualTypeScriptCompilation }
+                | { readonly error: VirtualTypeScriptWorkerError; readonly keepWorker?: boolean },
+        ): void => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            if ("compilation" in result || result.keepWorker) {
+                releaseWorker(pooled);
+                if ("compilation" in result) resolve(result.compilation);
+                else reject(result.error);
+                return;
+            }
+            void discardWorker(pooled).then(
+                () => reject(result.error),
+                (terminationError: unknown) => reject(new VirtualTypeScriptWorkerError(
+                    "WORKER_FAILURE",
+                    "Der TypeScript-Compiler-Worker konnte nicht sauber beendet werden.",
+                    { cause: terminationError },
+                )),
+            );
+        };
+        const onMessage = (message: unknown): void => {
+            if (!isWorkerMessage(message)) {
+                finish({ error: new VirtualTypeScriptWorkerError(
+                    "WORKER_FAILURE",
+                    "Der TypeScript-Compiler-Worker hat eine ungültige Antwort geliefert.",
+                ) });
+                return;
+            }
+            if (message.requestId !== requestId) return;
+            if (message.kind === "result") {
+                finish({ compilation: message.compilation });
+                return;
+            }
+            finish({ error: new VirtualTypeScriptWorkerError(
+                "COMPILER_EXCEPTION",
+                `Der TypeScript-Compiler ist fehlgeschlagen: ${message.error.message}`,
+                { cause: remoteError(message.error) },
+            ), keepWorker: true });
+        };
+        const onMessageError = (error: Error): void => finish({
+            error: new VirtualTypeScriptWorkerError(
+                "WORKER_FAILURE",
+                "Die Antwort des TypeScript-Compiler-Workers konnte nicht gelesen werden.",
+                { cause: error },
+            ),
+        });
+        const onError = (error: Error): void => finish({
+            error: new VirtualTypeScriptWorkerError(
+                "WORKER_FAILURE",
+                `Der TypeScript-Compiler-Worker ist fehlgeschlagen: ${error.message}`,
+                { cause: error },
+            ),
+        });
+        const onExit = (code: number): void => finish({
+            error: new VirtualTypeScriptWorkerError(
+                "WORKER_FAILURE",
+                `Der TypeScript-Compiler-Worker wurde ohne Ergebnis beendet (Exit-Code ${code}).`,
+            ),
+        });
+        const onAbort = (): void => finish({
+            error: new VirtualTypeScriptWorkerError(
+                "ABORTED",
+                "Die TypeScript-Kompilierung wurde abgebrochen.",
+                { cause: options?.signal?.reason },
+            ),
+        });
+        const timer = setTimeout(() => finish({
+            error: new VirtualTypeScriptWorkerError(
+                "TIMEOUT",
+                `Der TypeScript-Compiler hat die Zeitgrenze von ${timeoutMs} ms überschritten.`,
+            ),
+        }), Math.max(0, deadline - performance.now()));
+
+        worker.on("message", onMessage);
+        worker.on("messageerror", onMessageError);
+        worker.on("error", onError);
+        worker.on("exit", onExit);
+        options?.signal?.addEventListener("abort", onAbort, { once: true });
+        if (options?.signal?.aborted) onAbort();
+        else worker.postMessage({ kind: "compile", requestId, request });
+    });
+};

package/packages/ragents/src/typescript/build-contract.ts

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+
+export const canonicalTypeScriptBuildContract = (value: unknown): string => {
+    if (value === null || typeof value !== "object") return JSON.stringify(value);
+    if (Array.isArray(value)) return `[${value.map(canonicalTypeScriptBuildContract).join(",")}]`;
+    return `{${Object.entries(value as Record<string, unknown>)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalTypeScriptBuildContract(entry)}`)
+        .join(",")}}`;
+};
+
+export const typeScriptBuildContractHash = (contract: string): string =>
+    createHash("sha256").update(contract).digest("hex");

package/packages/ragents/src/typescript/compiler-worker.ts

@@ -0,0 +1,52 @@
+import { parentPort } from "node:worker_threads";
+
+import {
+    compileVirtualTypeScript,
+    type CompileVirtualTypeScriptRequest,
+} from "./compiler.ts";
+
+interface SerializedWorkerError {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+}
+
+type CompilerWorkerRequest = {
+    readonly kind: "compile";
+    readonly requestId: number;
+    readonly request: CompileVirtualTypeScriptRequest;
+};
+
+type CompilerWorkerMessage = {
+    readonly kind: "result";
+    readonly requestId: number;
+    readonly compilation: ReturnType<typeof compileVirtualTypeScript>;
+} | {
+    readonly kind: "error";
+    readonly requestId: number;
+    readonly error: SerializedWorkerError;
+};
+
+const serializedError = (error: unknown): SerializedWorkerError => {
+    if (!(error instanceof Error)) return { name: "Error", message: String(error) };
+    return {
+        name: error.name,
+        message: error.message,
+        ...(error.stack === undefined ? {} : { stack: error.stack }),
+    };
+};
+
+if (parentPort === null) {
+    throw new Error("Der TypeScript-Compiler-Worker benötigt einen übergeordneten Thread.");
+}
+
+const port = parentPort;
+port.on("message", (message: CompilerWorkerRequest) => {
+    if (message?.kind !== "compile") throw new Error("Der TypeScript-Compiler-Worker hat eine unbekannte Anfrage erhalten.");
+    try {
+        const compilation = compileVirtualTypeScript(message.request);
+        port.postMessage({ kind: "result", requestId: message.requestId, compilation } satisfies CompilerWorkerMessage);
+    } catch (error) {
+        port.postMessage({ kind: "error", requestId: message.requestId, error: serializedError(error) } satisfies CompilerWorkerMessage);
+    }
+});

package/packages/ragents/src/typescript/compiler.ts

@@ -0,0 +1,304 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import ts from "typescript";
+import { canonicalTypeScriptBuildContract as canonical } from "./build-contract.ts";
+export { canonicalTypeScriptBuildContract, typeScriptBuildContractHash } from "./build-contract.ts";
+
+const VIRTUAL_ROOT = "/";
+const OUTPUT_ROOT = "/__ragents__/out";
+const nodeTypeRoot = () => path.dirname(path.dirname(createRequire(import.meta.url).resolve("@types/node/package.json")));
+
+export interface VirtualTypeScriptFile {
+    readonly fileName: string;
+    readonly text: string;
+}
+
+export interface VirtualTypeScriptLibrary {
+    readonly fileName: string;
+    readonly path: string;
+}
+
+export type VirtualTypeScriptEmit = "none" | "browser" | "node";
+
+export interface CompileVirtualTypeScriptRequest {
+    readonly sources: readonly VirtualTypeScriptFile[];
+    readonly declarations?: readonly VirtualTypeScriptFile[];
+    readonly libraries?: readonly VirtualTypeScriptLibrary[];
+    readonly contract?: string;
+    readonly emit?: VirtualTypeScriptEmit;
+    readonly rootDirectory?: string;
+}
+
+export type VirtualTypeScriptDiagnosticCategory = "warning" | "error" | "suggestion" | "message";
+
+export interface VirtualTypeScriptPosition {
+    readonly line: number;
+    readonly column: number;
+}
+
+export interface VirtualTypeScriptDiagnostic {
+    readonly code: number;
+    readonly category: VirtualTypeScriptDiagnosticCategory;
+    readonly message: string;
+    readonly fileName?: string;
+    readonly start?: VirtualTypeScriptPosition;
+    readonly end?: VirtualTypeScriptPosition;
+}
+
+export interface VirtualTypeScriptCompilation {
+    readonly valid: boolean;
+    readonly compilationHash: string;
+    readonly diagnostics: readonly VirtualTypeScriptDiagnostic[];
+    readonly emittedFiles: readonly VirtualTypeScriptFile[];
+}
+
+type VirtualFileKind = "source" | "declaration";
+
+interface NormalizedFile extends VirtualTypeScriptFile {
+    readonly kind: VirtualFileKind;
+}
+
+interface LoadedLibrary extends NormalizedFile {
+    readonly hash: string;
+}
+
+const compareText = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
+
+const MAX_CACHED_SOURCE_FILES = 256;
+const parsedFiles = new Map<string, ts.SourceFile>();
+const fileHashes = new WeakMap<ts.SourceFile, string>();
+let previousProgram: ts.Program | undefined;
+
+const textHash = (text: string): string => createHash("sha256").update(text).digest("hex");
+
+const cachedSourceFile = (key: string, parse: () => ts.SourceFile): ts.SourceFile => {
+    const cached = parsedFiles.get(key);
+    if (cached) {
+        parsedFiles.delete(key);
+        parsedFiles.set(key, cached);
+        return cached;
+    }
+    const file = parse();
+    parsedFiles.set(key, file);
+    while (parsedFiles.size > MAX_CACHED_SOURCE_FILES) parsedFiles.delete(parsedFiles.keys().next().value!);
+    return file;
+};
+
+const hashOf = (file: ts.SourceFile): string => {
+    const known = fileHashes.get(file);
+    if (known) return known;
+    const hash = textHash(file.text);
+    fileHashes.set(file, hash);
+    return hash;
+};
+
+const requestLibraryCache = new Map<string, { readonly text: string; readonly hash: string }>();
+
+const libraryContent = (source: string): { readonly text: string; readonly hash: string } => {
+    const cached = requestLibraryCache.get(source);
+    if (cached) return cached;
+    const text = readFileSync(source, "utf8");
+    const content = { text, hash: textHash(text) };
+    requestLibraryCache.set(source, content);
+    return content;
+};
+
+const normalizeFileName = (fileName: string, kind: VirtualFileKind): string => {
+    if (!fileName.trim() || fileName.includes("\0") || fileName.includes("\\")) {
+        throw new TypeError(`Ungültiger virtueller TypeScript-Pfad: ${fileName}`);
+    }
+
+    const normalized = path.posix.normalize(`/${fileName}`).replace(/^\/+(?=.)/, "/");
+    if (normalized === VIRTUAL_ROOT || normalized.startsWith("/__ragents__/")) {
+        throw new TypeError(`Reservierter virtueller TypeScript-Pfad: ${fileName}`);
+    }
+
+    if (kind === "source" && ((!normalized.endsWith(".ts") && !normalized.endsWith(".tsx")) || normalized.endsWith(".d.ts"))) {
+        throw new TypeError(`Virtuelle TypeScript-Quelle muss auf .ts oder .tsx enden: ${fileName}`);
+    }
+    if (kind === "declaration" && !normalized.endsWith(".d.ts")) {
+        throw new TypeError(`Virtuelle TypeScript-Deklaration muss auf .d.ts enden: ${fileName}`);
+    }
+
+    return normalized;
+};
+
+const normalizedFiles = (
+    files: readonly VirtualTypeScriptFile[],
+    kind: VirtualFileKind,
+): NormalizedFile[] => files.map((file) => ({
+    fileName: normalizeFileName(file.fileName, kind),
+    text: file.text,
+    kind,
+})).sort((left, right) => compareText(left.fileName, right.fileName));
+
+const assertUniqueFiles = (files: readonly NormalizedFile[]): void => {
+    const names = new Set<string>();
+    for (const file of files) {
+        if (names.has(file.fileName)) throw new TypeError(`Virtuelle Datei doppelt deklariert: ${file.fileName}`);
+        names.add(file.fileName);
+    }
+};
+
+const compilerOptions = (emit: VirtualTypeScriptEmit): ts.CompilerOptions => ({
+    allowJs: false,
+    alwaysStrict: true,
+    exactOptionalPropertyTypes: false,
+    module: ts.ModuleKind.ES2022,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    newLine: ts.NewLineKind.LineFeed,
+    noEmit: emit === "none",
+    noEmitOnError: true,
+    noImplicitAny: true,
+    noImplicitReturns: false,
+    noUncheckedIndexedAccess: true,
+    outDir: OUTPUT_ROOT,
+    removeComments: false,
+    rootDir: VIRTUAL_ROOT,
+    skipLibCheck: true,
+    sourceMap: false,
+    strict: true,
+    strictNullChecks: true,
+    target: ts.ScriptTarget.ES2022,
+    useDefineForClassFields: true,
+    ...(emit === "browser" ? { jsx: ts.JsxEmit.React, types: [] } : { types: ["node"], typeRoots: [nodeTypeRoot()] }),
+});
+
+const compilationHashOf = (
+    sources: readonly NormalizedFile[],
+    declarations: readonly NormalizedFile[],
+    libraries: readonly LoadedLibrary[],
+    options: ts.CompilerOptions,
+    contract: string | undefined,
+): string => createHash("sha256").update(canonical({
+    apiVersion: 1,
+    compilerOptions: options,
+    contract: contract ?? null,
+    declarations: declarations
+        .map(({ fileName, text }) => ({ fileName, text }))
+        .sort((left, right) => compareText(left.fileName, right.fileName)),
+    ...(libraries.length > 0 ? {
+        libraries: libraries
+            .map(({ fileName, hash }) => ({ fileName, hash }))
+            .sort((left, right) => compareText(left.fileName, right.fileName)),
+    } : {}),
+    sources: sources
+        .map(({ fileName, text }) => ({ fileName, text }))
+        .sort((left, right) => compareText(left.fileName, right.fileName)),
+    typescriptVersion: ts.version,
+})).digest("hex");
+
+const categoryOf = (category: ts.DiagnosticCategory): VirtualTypeScriptDiagnosticCategory => {
+    switch (category) {
+        case ts.DiagnosticCategory.Warning: return "warning";
+        case ts.DiagnosticCategory.Error: return "error";
+        case ts.DiagnosticCategory.Suggestion: return "suggestion";
+        case ts.DiagnosticCategory.Message: return "message";
+    }
+};
+
+const positionOf = (file: ts.SourceFile, offset: number): VirtualTypeScriptPosition => {
+    const position = file.getLineAndCharacterOfPosition(offset);
+    return { line: position.line + 1, column: position.character + 1 };
+};
+
+const structuredDiagnostic = (diagnostic: ts.Diagnostic): VirtualTypeScriptDiagnostic => {
+    const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+    if (!diagnostic.file || diagnostic.start === undefined) {
+        return { code: diagnostic.code, category: categoryOf(diagnostic.category), message };
+    }
+
+    const start = positionOf(diagnostic.file, diagnostic.start);
+    const end = positionOf(diagnostic.file, diagnostic.start + (diagnostic.length ?? 0));
+    return {
+        code: diagnostic.code,
+        category: categoryOf(diagnostic.category),
+        message,
+        fileName: diagnostic.file.fileName,
+        start,
+        end,
+    };
+};
+
+const diagnosticsOf = (diagnostics: readonly ts.Diagnostic[]): VirtualTypeScriptDiagnostic[] => {
+    const unique = new Map<string, VirtualTypeScriptDiagnostic>();
+    for (const diagnostic of diagnostics.map(structuredDiagnostic)) {
+        const key = canonical(diagnostic);
+        if (!unique.has(key)) unique.set(key, diagnostic);
+    }
+    return [...unique.values()].sort((left, right) =>
+        compareText(left.fileName ?? "", right.fileName ?? "")
+        || (left.start?.line ?? 0) - (right.start?.line ?? 0)
+        || (left.start?.column ?? 0) - (right.start?.column ?? 0)
+        || left.code - right.code
+        || compareText(left.message, right.message));
+};
+
+export const compileVirtualTypeScript = (
+    request: CompileVirtualTypeScriptRequest,
+): VirtualTypeScriptCompilation => {
+    if (request.sources.length === 0) throw new TypeError("Mindestens eine TypeScript-Quelle ist erforderlich.");
+    const emit = request.emit ?? "none";
+    if (!["none", "browser", "node"].includes(emit)) throw new TypeError(`Unbekannter TypeScript-Emitmodus: ${String(emit)}`);
+    const sources = normalizedFiles(request.sources, "source");
+    const declarations = normalizedFiles(request.declarations ?? [], "declaration");
+    const libraries: LoadedLibrary[] = (request.libraries ?? []).map((library) => ({
+        fileName: normalizeFileName(library.fileName, "declaration"),
+        kind: "declaration" as const,
+        ...libraryContent(library.path),
+    })).sort((left, right) => compareText(left.fileName, right.fileName));
+    assertUniqueFiles([...sources, ...declarations, ...libraries]);
+    const root = path.resolve(request.rootDirectory ?? path.join(process.cwd(), ".ragents-typescript"));
+    const output = path.join(root, ".compiled");
+    const options = { ...compilerOptions(emit), rootDir: root, outDir: output };
+    const absolute = (name: string) => path.join(root, name.slice(1));
+    const files = new Map([...sources, ...declarations, ...libraries].map((file) => [absolute(file.fileName), file]));
+    const emitted = new Map<string, string>();
+    const host = ts.createCompilerHost(options, true);
+    const read = host.readFile.bind(host);
+    const exists = host.fileExists.bind(host);
+    const directoryExists = host.directoryExists?.bind(host);
+    const directories = host.getDirectories?.bind(host);
+    host.readFile = (name) => files.get(path.resolve(name))?.text ?? read(name);
+    host.fileExists = (name) => files.has(path.resolve(name)) || exists(name);
+    host.directoryExists = (name) => [...files.keys()].some((file) => file.startsWith(`${path.resolve(name)}/`)) || directoryExists?.(name) === true;
+    host.getDirectories = (name) => [...new Set([
+        ...directories?.(name) ?? [],
+        ...[...files.keys()].flatMap((file) => {
+            const relative = path.relative(name, file);
+            return relative.includes(path.sep) && !relative.startsWith("..") ? [relative.split(path.sep)[0]!] : [];
+        }),
+    ])];
+    host.getCurrentDirectory = () => root;
+    host.getSourceFile = (name, languageVersion) => {
+        const virtual = files.get(path.resolve(name));
+        if (virtual?.kind === "source") return ts.createSourceFile(name, virtual.text, languageVersion, true);
+        const text = virtual?.text ?? read(name);
+        if (text === undefined) return undefined;
+        const key = virtual ? `${name}\0${"hash" in virtual ? virtual.hash : textHash(text)}` : `${name}\0${languageVersion}`;
+        return cachedSourceFile(key, () => ts.createSourceFile(name, text, languageVersion, true));
+    };
+    host.writeFile = (name, text) => emitted.set(path.relative(output, name).split(path.sep).join("/"), text);
+    const program = ts.createProgram({ rootNames: [...files.keys()], options, host, ...(previousProgram ? { oldProgram: previousProgram } : {}) });
+    previousProgram = program;
+    const rawDiagnostics = [...ts.getPreEmitDiagnostics(program)];
+    if (emit !== "none") rawDiagnostics.push(...program.emit().diagnostics);
+    const diagnostics = diagnosticsOf(rawDiagnostics).map((diagnostic) => diagnostic.fileName && files.has(diagnostic.fileName)
+        ? { ...diagnostic, fileName: files.get(diagnostic.fileName)!.fileName }
+        : diagnostic);
+    const valid = !diagnostics.some((diagnostic) => diagnostic.category === "error");
+    const dependencies = program.getSourceFiles().filter((file) => !files.has(file.fileName)).map((file) => ({
+        fileName: file.fileName,
+        kind: "declaration" as const,
+        text: file.text,
+        hash: hashOf(file),
+    }));
+    return {
+        valid,
+        compilationHash: compilationHashOf(sources, declarations, [...libraries, ...dependencies], options, request.contract),
+        diagnostics,
+        emittedFiles: valid ? [...emitted].map(([fileName, text]) => ({ fileName, text })).sort((left, right) => compareText(left.fileName, right.fileName)) : [],
+    };
+};