@schlenkr/ragents 0.1.0

package/packages/workspace-executor/src/context.ts

@@ -0,0 +1,123 @@
+import { withGitConfigPairs, type GitConfigPairs } from "./git-config-environment.js";
+import { RUN_MARKER_ENV } from "./run-marker.js";
+import { safeProcessEnvironment } from "./safe-environment.js";
+import type { SessionIdent } from "./session-ident.js";
+import type { ResolvedWorkspaceRoot } from "./paths.js";
+
+/** Was ein Executor über einen Run weiß: seine Ordner, seine Umgebung und seine Kennung. */
+export interface WorkspaceProcessContext {
+  runId: string;
+  cwd: string;
+  root: string;
+  home: string;
+  /** Wohin ein Sprachserver Protokolle und Zwischenstände legen darf; nie das Home eines Entwicklers. */
+  logDirectory: string;
+  env: NodeJS.ProcessEnv;
+  uid?: number;
+  gid?: number;
+  additionalRoots?: readonly string[];
+  readOnlyRoots?: readonly string[];
+  workspaceAliases?: Readonly<Record<string, string>>;
+  pathVariables?: Readonly<Record<string, string>>;
+  runOperation?: <T>(operation: () => Promise<T>) => Promise<T>;
+}
+
+export interface SandboxHomeEnvironment {
+  home: string;
+  nugetPackages?: string;
+}
+
+export interface SandboxEnvironmentOptions {
+  home: SandboxHomeEnvironment;
+  ident?: { name: string };
+  pathVariables?: Readonly<Record<string, string>>;
+  additions?: Readonly<Record<string, string>>;
+}
+
+/** Die Git-Regeln, die in jeder Sandbox gelten, gleich auf welchem Rechner sie läuft. */
+export const SANDBOX_GIT_CONFIG: GitConfigPairs = [
+  ["branch.autoSetupMerge", "false"],
+  ["core.hooksPath", "/dev/null"],
+  ["core.sharedRepository", "0"],
+];
+
+const onlyStrings = (env: NodeJS.ProcessEnv): Record<string, string> =>
+  Object.fromEntries(Object.entries(env).filter((entry): entry is [string, string] => typeof entry[1] === "string"));
+
+/** Was der Server je Run zur Umgebung beiträgt: Run-Marker, Git-Regeln und die Zusätze seines Arbeitsbereichs. */
+export const sandboxRunEnvironment = (runId: string, workspace: {
+  gitConfig?: GitConfigPairs;
+  extraEnv?: NodeJS.ProcessEnv;
+  gitEnv?: NodeJS.ProcessEnv;
+} = {}): Record<string, string> => onlyStrings({
+  ...withGitConfigPairs({ ...workspace.extraEnv }, [...SANDBOX_GIT_CONFIG, ...(workspace.gitConfig ?? [])]),
+  GIT_OPTIONAL_LOCKS: "0",
+  CI: "true",
+  [RUN_MARKER_ENV]: runId,
+  ...workspace.gitEnv,
+});
+
+/** Die Umgebung eines Sandbox-Prozesses: die sichere Umgebung dieser Maschine plus die Beiträge des Runs. */
+export const sandboxEnvironment = (
+  source: NodeJS.ProcessEnv,
+  { home, ident, pathVariables, additions }: SandboxEnvironmentOptions,
+): NodeJS.ProcessEnv => ({
+  ...safeProcessEnvironment(source),
+  HOME: home.home,
+  USERPROFILE: home.home,
+  USER: ident?.name ?? "root",
+  LOGNAME: ident?.name ?? "root",
+  ...(home.nugetPackages ? { NUGET_PACKAGES: home.nugetPackages } : {}),
+  ...pathVariables,
+  ...additions,
+});
+
+export interface WorkspaceContextOptions {
+  runId: string;
+  cwd: string;
+  root: string;
+  home: SandboxHomeEnvironment;
+  logDirectory: string;
+  ident?: SessionIdent;
+  additionalRoots?: readonly ResolvedWorkspaceRoot[];
+  readOnlyRoots?: readonly ResolvedWorkspaceRoot[];
+  additions?: Readonly<Record<string, string>>;
+  runOperation?: <T>(operation: () => Promise<T>) => Promise<T>;
+  source?: NodeJS.ProcessEnv;
+}
+
+const namedEntries = (
+  roots: readonly ResolvedWorkspaceRoot[],
+  pick: (root: ResolvedWorkspaceRoot) => string | undefined,
+): Record<string, string> =>
+  Object.fromEntries(roots.flatMap((root) => {
+    const name = pick(root);
+    return name ? [[name, root.directory]] : [];
+  }));
+
+/** Baut den Kontext eines Runs aus den Ordnern dieser Maschine; jeder Executor ruft dieselbe Funktion. */
+export const workspaceProcessContext = (options: WorkspaceContextOptions): WorkspaceProcessContext => {
+  const additionalRoots = options.additionalRoots ?? [];
+  const readOnlyRoots = options.readOnlyRoots ?? [];
+  const all = [...additionalRoots, ...readOnlyRoots];
+  const pathVariables = namedEntries(all, (root) => root.environmentVariable);
+  return {
+    runId: options.runId,
+    cwd: options.cwd,
+    root: options.root,
+    home: options.home.home,
+    logDirectory: options.logDirectory,
+    env: sandboxEnvironment(options.source ?? process.env, {
+      home: options.home,
+      ...(options.ident ? { ident: options.ident } : {}),
+      pathVariables,
+      ...(options.additions ? { additions: options.additions } : {}),
+    }),
+    ...(options.ident === undefined ? {} : { uid: options.ident.uid, gid: options.ident.gid }),
+    additionalRoots: additionalRoots.map((root) => root.directory),
+    readOnlyRoots: readOnlyRoots.map((root) => root.directory),
+    workspaceAliases: namedEntries(all, (root) => root.alias),
+    pathVariables,
+    ...(options.runOperation === undefined ? {} : { runOperation: options.runOperation }),
+  };
+};

package/packages/workspace-executor/src/executor.ts

@@ -0,0 +1,134 @@
+import type { WorkspaceProcessContext } from "./context.js";
+import { LanguageServerHost, type LanguageServerAdapter, type LanguageServerHostOptions } from "./language-server/host.js";
+import { createSandboxTools, type SandboxTools, type ToolUpdate } from "./sandbox-tools.js";
+
+/** Der Stand des Executors; Server und Arbeitsplatz müssen denselben tragen. */
+export const WORKSPACE_EXECUTOR_VERSION = "1";
+
+/** Beendet alles, was der Executor für einen Run hält; kein Werkzeug des Modells. */
+export const WORKSPACE_STOP_OPERATION = "stop";
+
+export const languageServerOpenTool = (adapterId: string): string => `${adapterId}_open`;
+
+export const languageServerDiagnosticsTool = (adapterId: string): string => `${adapterId}_diagnostics`;
+
+export const languageServerSnapshotTool = (adapterId: string): string => `${adapterId}_snapshot`;
+
+export interface WorkspaceExecuteOptions {
+  toolCallId?: string;
+  signal?: AbortSignal;
+  onProgress?: (text: string) => void;
+}
+
+/** Führt die Arbeitsplatz-Werkzeuge eines Runs aus; kennt weder Engine noch Run-Vertrag noch Plugins. */
+export interface WorkspaceExecutor {
+  readonly version: string;
+  execute: (runId: string, tool: string, input: unknown, options?: WorkspaceExecuteOptions) => Promise<unknown>;
+  stopRun: (runId: string) => Promise<void>;
+  shutdown: () => Promise<void>;
+}
+
+export interface WorkspaceExecutorOptions {
+  contextFor: (runId: string) => Promise<WorkspaceProcessContext>;
+  languageServers?: readonly LanguageServerAdapter[];
+  languageServerOptions?: LanguageServerHostOptions;
+}
+
+const textOf = (update: ToolUpdate): string =>
+  (update.content ?? [])
+    .filter((part) => part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("\n");
+
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
+
+export class SandboxWorkspaceExecutor implements WorkspaceExecutor {
+  readonly version = WORKSPACE_EXECUTOR_VERSION;
+  readonly #options: WorkspaceExecutorOptions;
+  readonly #sandboxes = new Map<string, Promise<SandboxTools>>();
+  readonly #languageServers: readonly LanguageServerHost[];
+
+  constructor(options: WorkspaceExecutorOptions) {
+    this.#options = options;
+    this.#languageServers = (options.languageServers ?? []).map((adapter) =>
+      new LanguageServerHost(adapter, (runId) => options.contextFor(runId), options.languageServerOptions ?? {}));
+  }
+
+  async execute(runId: string, tool: string, input: unknown, options: WorkspaceExecuteOptions = {}): Promise<unknown> {
+    if (tool === WORKSPACE_STOP_OPERATION) {
+      await this.stopRun(runId);
+      return null;
+    }
+    const languageServer = this.#languageServers.find((host) =>
+      tool === languageServerOpenTool(host.adapter.id)
+      || tool === languageServerDiagnosticsTool(host.adapter.id)
+      || tool === languageServerSnapshotTool(host.adapter.id));
+    if (languageServer) return this.#languageServerCall(languageServer, runId, tool, input);
+    return this.#toolCall(runId, tool, input, options);
+  }
+
+  async stopRun(runId: string): Promise<void> {
+    const sandbox = this.#sandboxes.get(runId);
+    this.#sandboxes.delete(runId);
+    const results = await Promise.allSettled([
+      ...(sandbox ? [sandbox.then((tools) => tools.shutdown())] : []),
+      ...this.#languageServers.map((host) => host.stopSession(runId)),
+    ]);
+    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+    if (failed) throw failed.reason;
+  }
+
+  async shutdown(): Promise<void> {
+    const running = [...this.#sandboxes.keys()];
+    const results = await Promise.allSettled([
+      ...running.map((runId) => this.stopRun(runId)),
+      ...this.#languageServers.map((host) => host.shutdown()),
+    ]);
+    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+    if (failed) throw failed.reason;
+  }
+
+  async #toolCall(runId: string, tool: string, input: unknown, options: WorkspaceExecuteOptions): Promise<unknown> {
+    const { tools } = await this.#sandbox(runId);
+    const run = tools.get(tool);
+    if (!run) throw new Error(`Der Executor kennt das Arbeitsplatz-Werkzeug ${tool} nicht`);
+    return run(input, {
+      toolCallId: options.toolCallId ?? tool,
+      ...(options.signal ? { signal: options.signal } : {}),
+      ...(options.onProgress ? { onUpdate: (update: ToolUpdate) => options.onProgress!(textOf(update)) } : {}),
+    });
+  }
+
+  #languageServerCall(host: LanguageServerHost, runId: string, tool: string, input: unknown): Promise<unknown> {
+    if (tool === languageServerSnapshotTool(host.adapter.id)) return host.snapshot(runId);
+    if (tool === languageServerOpenTool(host.adapter.id)) {
+      const { root } = input as { root: string };
+      return host.open(runId, root);
+    }
+    const { paths, warnings } = input as { paths?: readonly string[]; warnings?: boolean };
+    return host.diagnostics(runId, paths, warnings ?? false);
+  }
+
+  #sandbox(runId: string): Promise<SandboxTools> {
+    const running = this.#sandboxes.get(runId);
+    if (running) return running;
+    const created = createSandboxTools(
+      runId,
+      () => this.#options.contextFor(runId),
+      (absolutePath) => this.#annotate(runId, absolutePath),
+    ).catch((error: unknown) => {
+      this.#sandboxes.delete(runId);
+      throw error;
+    });
+    this.#sandboxes.set(runId, created);
+    return created;
+  }
+
+  async #annotate(runId: string, absolutePath: string): Promise<string | undefined> {
+    const notes = await Promise.all(this.#languageServers.map((host) =>
+      host.annotate(runId, absolutePath).catch((error: unknown) =>
+        `Diagnostik (${host.adapter.label}) fehlgeschlagen: ${messageOf(error)}`)));
+    const text = notes.filter((note): note is string => Boolean(note)).join("\n");
+    return text || undefined;
+  }
+}

package/packages/workspace-executor/src/git-config-environment.ts

@@ -0,0 +1,10 @@
+export type GitConfigPairs = ReadonlyArray<readonly [string, string]>;
+
+export const withGitConfigPairs = (env: NodeJS.ProcessEnv, pairs: GitConfigPairs): NodeJS.ProcessEnv => ({
+  ...env,
+  GIT_CONFIG_COUNT: String(pairs.length),
+  ...Object.fromEntries(pairs.flatMap(([key, value], index) => [
+    [`GIT_CONFIG_KEY_${index}`, key],
+    [`GIT_CONFIG_VALUE_${index}`, value],
+  ])),
+});

package/packages/workspace-executor/src/index.ts

@@ -0,0 +1,52 @@
+export {
+  sandboxEnvironment,
+  sandboxRunEnvironment,
+  workspaceProcessContext,
+  type SandboxHomeEnvironment,
+  type WorkspaceProcessContext,
+} from "./context.js";
+export {
+  SandboxWorkspaceExecutor,
+  WORKSPACE_EXECUTOR_VERSION,
+  WORKSPACE_STOP_OPERATION,
+  languageServerDiagnosticsTool,
+  languageServerOpenTool,
+  languageServerSnapshotTool,
+  type WorkspaceExecuteOptions,
+  type WorkspaceExecutor,
+} from "./executor.js";
+export { processGroupExists, runManagedProcess, startManagedService, type ManagedService } from "./managed-process.js";
+export {
+  allowedWorkspacePath,
+  containsWorkspacePath,
+  expandWorkspaceAlias,
+  resolvedWorkspacePath,
+  type ResolvedWorkspaceRoot,
+} from "./paths.js";
+export { RUN_MARKER_ENV, runMarkerOf } from "./run-marker.js";
+export { safeProcessEnvironment } from "./safe-environment.js";
+export { createSandboxTools, withAnnotation } from "./sandbox-tools.js";
+export { type SessionIdent } from "./session-ident.js";
+export { shellPlatformText } from "./shell-platform.js";
+export { hostDataDirectory, hostToolFile, pluginToolsDirectory, ragentsDataRoot, workspaceDataDirectory } from "./tools.js";
+export {
+  LanguageServerHost,
+  changedWorkspaceFiles,
+  type LanguageServerAdapter,
+  type LanguageServerHostOptions,
+} from "./language-server/host.js";
+export {
+  type LanguageServerDiagnostic,
+  type LanguageServerFileDiagnostics,
+  type LanguageServerSeverity,
+  type LanguageServerSnapshot,
+  type LanguageServerState,
+} from "./language-server/contract.js";
+export { diagnosticEntries, formatDiagnostics } from "./language-server/diagnostics.js";
+export { resolveRootDirectory } from "./language-server/roots.js";
+export { LanguageServerSession, withTimeout, type Diagnostic } from "./language-server/session.js";
+export { solutionProjects } from "./language-server/solution.js";
+export { fsharpAdapter, FSHARP_PLUGIN_ID, FSHARP_SERVER_FILE, FSHARP_SERVER_VARIABLE } from "./language-server/adapters/fsharp.js";
+export { roslynAdapter, ROSLYN_PLUGIN_ID, ROSLYN_SERVER_FILE, ROSLYN_SERVER_VARIABLE } from "./language-server/adapters/roslyn.js";
+export { typescriptAdapter } from "./language-server/adapters/typescript.js";
+export { workspaceLanguageServers } from "./language-server/adapters/index.js";

package/packages/workspace-executor/src/language-server/adapters/fsharp.ts

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { hostToolFile } from "../../tools.js";
+import type { LanguageServerAdapter } from "../host.js";
+import { dotnetCommand, resolveRootFile } from "../roots.js";
+import { solutionProjects } from "../solution.js";
+
+export const FSHARP_SERVER_VARIABLE = "FSHARP_LANGUAGE_SERVER";
+export const FSHARP_PLUGIN_ID = "ragents.lsp-fsharp";
+export const FSHARP_SERVER_FILE = "fsautocomplete/fsautocomplete.dll";
+
+const languages = { ".fs": "fsharp", ".fsi": "fsharp", ".fsx": "fsharp" } as const;
+
+const serverPath = (): string => {
+  const configured = process.env[FSHARP_SERVER_VARIABLE];
+  if (configured) return configured;
+  const provisioned = hostToolFile(FSHARP_PLUGIN_ID, FSHARP_SERVER_FILE);
+  if (existsSync(provisioned)) return provisioned;
+  throw new Error("fsautocomplete gibt es auf diesem Rechner nicht: weder "
+    + `${FSHARP_SERVER_VARIABLE} gesetzt noch ${provisioned} vorhanden. Ein Arbeitsplatz holt es mit `
+    + `pnpm provision --workspace, ein Server über pnpm provision <profil>; ${FSHARP_SERVER_VARIABLE} übersteuert beides`);
+};
+
+const contentOf = (params: unknown): string => (params as { content?: string } | undefined)?.content ?? "";
+
+export const fsharpAdapter: LanguageServerAdapter = {
+  id: "fsharp",
+  label: "FSAC",
+  languages,
+  rootDescription: "the .sln file (or a single .fsproj)",
+  resolveRoot: (workspaceRoot, root) => resolveRootFile(workspaceRoot, root, [".sln", ".fsproj"]),
+  launch: async (context, root) => ({
+    label: "FSAC",
+    ...dotnetCommand(serverPath(), ["--state-directory", path.join(context.logDirectory, "fsautocomplete")]),
+    cwd: path.dirname(root),
+    env: context.env,
+    uid: context.uid,
+    gid: context.gid,
+    rootUri: pathToFileURL(path.dirname(root)).href,
+    initializationOptions: { AutomaticWorkspaceInit: false },
+    languages,
+  }),
+  open: async (session, root, timeoutMs) => {
+    const projects = root.toLowerCase().endsWith(".sln")
+      ? (await solutionProjects(root)).filter((project) => project.toLowerCase().endsWith(".fsproj"))
+      : [root];
+    if (projects.length === 0) throw new Error(`${path.basename(root)} enthält keine F#-Projekte`);
+    const finished = session.waitForNotification(timeoutMs, "Projekte geladen", (method, params) =>
+      method === "fsharp/notifyWorkspace"
+      && contentOf(params).includes("\"workspaceLoad\"")
+      && contentOf(params).includes("\"finished\""));
+    await session.request("fsharp/workspaceLoad", {
+      textDocuments: projects.map((project) => ({ uri: pathToFileURL(project).href })),
+    });
+    await finished;
+    return `${projects.length} F#-Projekt${projects.length === 1 ? "" : "e"} aus ${path.basename(root)} geladen`;
+  },
+};

package/packages/workspace-executor/src/language-server/adapters/index.ts

@@ -0,0 +1,7 @@
+import type { LanguageServerAdapter } from "../host.js";
+import { fsharpAdapter } from "./fsharp.js";
+import { roslynAdapter } from "./roslyn.js";
+import { typescriptAdapter } from "./typescript.js";
+
+/** Jeder Executor bietet dieselbe Menge Sprachserver an; fehlt einer auf der Maschine, scheitert erst der Aufruf. */
+export const workspaceLanguageServers: readonly LanguageServerAdapter[] = [roslynAdapter, fsharpAdapter, typescriptAdapter];

package/packages/workspace-executor/src/language-server/adapters/roslyn.ts

@@ -0,0 +1,54 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { hostToolFile } from "../../tools.js";
+import type { LanguageServerAdapter } from "../host.js";
+import { dotnetCommand, resolveRootFile } from "../roots.js";
+
+export const ROSLYN_SERVER_VARIABLE = "ROSLYN_LANGUAGE_SERVER";
+export const ROSLYN_PLUGIN_ID = "ragents.lsp-roslyn";
+export const ROSLYN_SERVER_FILE = "roslyn/Microsoft.CodeAnalysis.LanguageServer.dll";
+
+const languages = { ".cs": "csharp" } as const;
+
+const serverPath = (): string => {
+  const configured = process.env[ROSLYN_SERVER_VARIABLE];
+  if (configured) return configured;
+  const provisioned = hostToolFile(ROSLYN_PLUGIN_ID, ROSLYN_SERVER_FILE);
+  if (existsSync(provisioned)) return provisioned;
+  throw new Error("Microsoft.CodeAnalysis.LanguageServer gibt es auf diesem Rechner nicht: weder "
+    + `${ROSLYN_SERVER_VARIABLE} gesetzt noch ${provisioned} vorhanden. Ein Arbeitsplatz holt ihn mit `
+    + `pnpm provision --workspace, ein Server über pnpm provision <profil>; ${ROSLYN_SERVER_VARIABLE} übersteuert beides`);
+};
+
+export const roslynAdapter: LanguageServerAdapter = {
+  id: "roslyn",
+  label: "Roslyn",
+  languages,
+  rootDescription: "the .sln file (or a single .csproj)",
+  resolveRoot: (workspaceRoot, root) => resolveRootFile(workspaceRoot, root, [".sln", ".slnx", ".csproj"]),
+  launch: async (context, root) => ({
+    label: "Roslyn",
+    ...dotnetCommand(serverPath(), [
+      "--stdio",
+      "--logLevel", "Warning",
+      "--extensionLogDirectory", path.join(context.logDirectory, "roslyn-logs"),
+    ]),
+    cwd: path.dirname(root),
+    env: context.env,
+    uid: context.uid,
+    gid: context.gid,
+    rootUri: pathToFileURL(path.dirname(root)).href,
+    languages,
+    newFileSettleMs: 2_000,
+  }),
+  open: async (session, root, timeoutMs) => {
+    const uri = pathToFileURL(root).href;
+    const loaded = session.waitForNotification(timeoutMs, "Projekte geladen",
+      (method) => method === "workspace/projectInitializationComplete");
+    if (root.toLowerCase().endsWith(".csproj")) session.notify("project/open", { projects: [uri] });
+    else session.notify("solution/open", { solution: uri });
+    await loaded;
+    return `${path.basename(root)} geladen`;
+  },
+};

package/packages/workspace-executor/src/language-server/adapters/typescript.ts

@@ -0,0 +1,46 @@
+import { stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { LanguageServerAdapter } from "../host.js";
+import { resolveRootDirectory } from "../roots.js";
+
+const require = createRequire(import.meta.url);
+const serverScript = require.resolve("typescript-language-server/lib/cli.mjs");
+const bundledTypeScriptLib = path.dirname(require.resolve("typescript"));
+
+const languages = {
+  ".ts": "typescript",
+  ".tsx": "typescriptreact",
+  ".mts": "typescript",
+  ".cts": "typescript",
+  ".js": "javascript",
+  ".jsx": "javascriptreact",
+} as const;
+
+const hasWorkspaceTypeScript = (root: string): Promise<boolean> =>
+  stat(path.join(root, "node_modules", "typescript", "lib", "tsserver.js")).then((info) => info.isFile(), () => false);
+
+export const typescriptAdapter: LanguageServerAdapter = {
+  id: "typescript",
+  label: "TypeScript",
+  languages,
+  rootDescription: "the directory whose tsconfig.json projects should be served (e.g. src)",
+  resolveRoot: resolveRootDirectory,
+  launch: async (context, root) => ({
+    label: "TypeScript",
+    command: process.execPath,
+    args: [serverScript, "--stdio"],
+    cwd: root,
+    // Im Extension-Host ist process.execPath Electron; ohne diese Variable startet es die Anwendung statt des Skripts.
+    env: { ...context.env, ELECTRON_RUN_AS_NODE: "1" },
+    uid: context.uid,
+    gid: context.gid,
+    rootUri: pathToFileURL(root).href,
+    initializationOptions: await hasWorkspaceTypeScript(root) ? {} : { tsserver: { path: bundledTypeScriptLib } },
+    languages,
+    publishesOnlyChangedDiagnostics: true,
+  }),
+  open: async (_session, root) =>
+    `TypeScript-Server auf ${path.basename(root)} bereit; Projekte werden je Datei aus der nächsten tsconfig.json geladen`,
+};

package/packages/workspace-executor/src/language-server/contract.ts

@@ -0,0 +1,23 @@
+export type LanguageServerState = "closed" | "opening" | "ready" | "failed" | "suspended";
+
+export type LanguageServerSeverity = "error" | "warning" | "information" | "hint";
+
+export interface LanguageServerDiagnostic {
+  line: number;
+  character: number;
+  severity: LanguageServerSeverity;
+  code?: string;
+  message: string;
+}
+
+export interface LanguageServerFileDiagnostics {
+  path: string;
+  diagnostics: readonly LanguageServerDiagnostic[];
+}
+
+export interface LanguageServerSnapshot {
+  state: LanguageServerState;
+  root: string | null;
+  summary: string | null;
+  files: readonly LanguageServerFileDiagnostics[];
+}

package/packages/workspace-executor/src/language-server/diagnostics.ts

@@ -0,0 +1,62 @@
+import type { LanguageServerDiagnostic, LanguageServerSeverity } from "./contract.js";
+import type { Diagnostic } from "./session.js";
+
+const ERROR = 1;
+const WARNING = 2;
+const MAX_LINES = 30;
+const MAX_ENTRIES = 200;
+
+const severityNames: Readonly<Record<number, LanguageServerSeverity>> = {
+  1: "error",
+  2: "warning",
+  3: "information",
+  4: "hint",
+};
+
+const severityOf = (diagnostic: Diagnostic): number => diagnostic.severity ?? ERROR;
+
+const byPlace = (left: Diagnostic, right: Diagnostic): number =>
+  severityOf(left) - severityOf(right)
+  || left.range.start.line - right.range.start.line
+  || left.range.start.character - right.range.start.character;
+
+const firstLine = (message: string): string => message.split("\n")[0].trim();
+
+const lineOf = (relativePath: string, diagnostic: Diagnostic): string => {
+  const { line, character } = diagnostic.range.start;
+  const kind = severityOf(diagnostic) === ERROR ? "error" : "warning";
+  const code = diagnostic.code === undefined ? "" : ` ${diagnostic.code}`;
+  return `${relativePath}:${line + 1}:${character + 1} ${kind}${code}: ${firstLine(diagnostic.message)}`;
+};
+
+export const diagnosticEntries = (diagnostics: readonly Diagnostic[]): LanguageServerDiagnostic[] =>
+  [...diagnostics]
+    .sort(byPlace)
+    .slice(0, MAX_ENTRIES)
+    .map((diagnostic) => ({
+      line: diagnostic.range.start.line + 1,
+      character: diagnostic.range.start.character + 1,
+      severity: severityNames[severityOf(diagnostic)] ?? "error",
+      ...(diagnostic.code === undefined ? {} : { code: String(diagnostic.code) }),
+      message: firstLine(diagnostic.message),
+    }));
+
+export const formatDiagnostics = (
+  label: string,
+  relativePath: string,
+  diagnostics: readonly Diagnostic[],
+  includeWarnings: boolean,
+): string => {
+  const errors = diagnostics.filter((diagnostic) => severityOf(diagnostic) === ERROR);
+  const warnings = diagnostics.filter((diagnostic) => severityOf(diagnostic) === WARNING);
+  const warningNote = warnings.length === 0
+    ? ""
+    : `, ${warnings.length} ${warnings.length === 1 ? "Warnung" : "Warnungen"}`;
+  const heading = errors.length === 0
+    ? `Diagnostik (${label}) ${relativePath}: keine Fehler${warningNote}`
+    : `Diagnostik (${label}) ${relativePath}: ${errors.length} Fehler${warningNote}`;
+  const listed = [...errors, ...(includeWarnings ? warnings : [])].sort(byPlace);
+  const lines = listed.slice(0, MAX_LINES).map((diagnostic) => lineOf(relativePath, diagnostic));
+  if (listed.length > MAX_LINES) lines.push(`... und ${listed.length - MAX_LINES} weitere`);
+  return [heading, ...lines].join("\n");
+};