@schlenkr/ragents 0.1.8 → 0.1.9

package/packages/ai/dist/types.d.ts

@@ -520,6 +520,15 @@ export interface ModelCost extends ModelCostRates {
     /** Request-wide pricing tiers. The highest matching input threshold applies to the full request. */
     tiers?: ModelCostTier[];
 }
+/** When an agent compacts its context on a model and how much it keeps, in absolute tokens of that model. */
+export interface ModelCompaction {
+    /** Context tokens above which the agent compacts. */
+    threshold: number;
+    /** Tokens of the newest context the compaction keeps verbatim. */
+    keepRecentTokens: number;
+    /** Output budget of the summary. */
+    summaryTokens: number;
+}
 export interface Model<TApi extends Api> {
     id: string;
     name: string;
@@ -536,6 +545,8 @@ export interface Model<TApi extends Api> {
     cost: ModelCost;
     contextWindow: number;
     maxTokens: number;
+    /** The model's own compaction values; without them the agent applies the catalog standard of its context window. */
+    compaction?: ModelCompaction;
     headers?: Record<string, string>;
     /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
     compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" | "openai-codex-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : never;

package/packages/ai/src/types.ts

@@ -561,6 +561,16 @@ export interface ModelCost extends ModelCostRates {
 	tiers?: ModelCostTier[];
 }
 
+/** When an agent compacts its context on a model and how much it keeps, in absolute tokens of that model. */
+export interface ModelCompaction {
+	/** Context tokens above which the agent compacts. */
+	threshold: number;
+	/** Tokens of the newest context the compaction keeps verbatim. */
+	keepRecentTokens: number;
+	/** Output budget of the summary. */
+	summaryTokens: number;
+}
+
 // Model interface for the unified model system
 export interface Model<TApi extends Api> {
 	id: string;
@@ -578,6 +588,8 @@ export interface Model<TApi extends Api> {
 	cost: ModelCost;
 	contextWindow: number;
 	maxTokens: number;
+	/** The model's own compaction values; without them the agent applies the catalog standard of its context window. */
+	compaction?: ModelCompaction;
 	headers?: Record<string, string>;
 	/** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
 	compat?: TApi extends "openai-completions"

package/packages/ragents/src/domain/event-semantics.ts

@@ -358,6 +358,9 @@ export const assertEventSemantics = (
             for (const artifactId of event.payload.artifactIds)
                 assertArtifactRead(state, event.actorId, artifactId);
 
+            if (event.payload.origin === "human" && existingActorOf(state, event.actorId).kind !== "human")
+                throw new Error(`Input ${event.payload.inputId} of human origin was not enqueued by a human actor.`);
+
             if (event.payload.subscriptionId) {
                 const subscription = state.subscriptions.get(event.payload.subscriptionId);
 

package/packages/ragents/src/domain/event-validation.ts

@@ -431,9 +431,13 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
                 "artifactIds",
                 "sourceEventIds",
                 "subscriptionId",
-            ], ["presentation"]);
+            ], ["presentation", "origin"]);
             if (payload.presentation !== undefined && payload.presentation !== "background")
                 fail(`${path}.presentation`, "must be background");
+            if (payload.origin !== undefined && payload.origin !== "human")
+                fail(`${path}.origin`, "must be human");
+            if (subscriptionInput && Object.hasOwn(payload, "origin"))
+                fail(`${path}.origin`, "is not supported for a subscription input");
             stringOf(payload.inputId, `${path}.inputId`);
             actorIdOf(payload.actorId, `${path}.actorId`);
             stringArrayOf(payload.artifactIds, `${path}.artifactIds`);
@@ -545,7 +549,7 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
                 "model",
                 "readFiles",
                 "modifiedFiles",
-            ]);
+            ], ["threshold"]);
             stringOf(payload.turnId, `${path}.turnId`);
             nonEmptyStringOf(payload.summary, `${path}.summary`);
             nonEmptyStringOf(payload.firstKeptEventId, `${path}.firstKeptEventId`);
@@ -554,6 +558,15 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
             nonEmptyStringOf(payload.model, `${path}.model`);
             stringArrayOf(payload.readFiles, `${path}.readFiles`);
             stringArrayOf(payload.modifiedFiles, `${path}.modifiedFiles`);
+
+            if (Object.hasOwn(payload, "threshold")) {
+                const threshold = exactObject(payload.threshold, `${path}.threshold`, ["tokens", "source"]);
+                if (!Number.isSafeInteger(threshold.tokens))
+                    fail(`${path}.threshold.tokens`, "must be a safe integer");
+                if (threshold.source !== "model" && threshold.source !== "catalog")
+                    fail(`${path}.threshold.source`, "must be model or catalog");
+            }
+
             return;
         }
 

package/packages/ragents/src/domain/events.ts

@@ -93,6 +93,7 @@ export type EventPayloads = {
         actorId: ActorId;
         artifactIds: string[];
         presentation?: "background";
+        origin?: "human";
     } & (
         | { subscriptionId: null; sourceEventIds: string[]; content: string }
         | { subscriptionId: SubscriptionId; sourceEventIds: [string]; content?: never }
@@ -151,6 +152,8 @@ export type EventPayloads = {
         model: string;
         readFiles: string[];
         modifiedFiles: string[];
+        /** The compaction threshold of the model and whether it is the model's own or the catalog standard; absent before file format 9. */
+        threshold?: { tokens: number; source: "model" | "catalog" };
     };
     "model.output.completed": {
         turnId: TurnId;

package/packages/ragents/src/domain/model.ts

@@ -89,6 +89,8 @@ export type ActorInput = {
     actorId: ActorId;
     content: string;
     presentation?: "background";
+    /** Set only on a person's own message, because system inputs are enqueued under the owner too. */
+    origin?: "human";
     artifactIds: readonly ArtifactId[];
     enqueuedBy: ActorId;
     enqueuedAt: string;

package/packages/ragents/src/domain/projection.ts

@@ -222,6 +222,7 @@ export function applyEvent(
                 actorId: event.payload.actorId,
                 content: event.payload.subscriptionId === null ? event.payload.content : JSON.stringify(source),
                 ...(event.payload.presentation ? { presentation: event.payload.presentation } : {}),
+                ...(event.payload.origin ? { origin: event.payload.origin } : {}),
                 artifactIds: event.payload.artifactIds,
                 enqueuedBy: event.actorId,
                 enqueuedAt: event.occurredAt,

package/packages/ragents/src/drivers/agent-runtime.ts

@@ -36,7 +36,7 @@ export type AgentRuntimeManagerOptions = {
         context: AgentRuntimeContext,
         signal: AbortSignal,
     ) => readonly AgentHook[] | Promise<readonly AgentHook[]>;
-    /** Compaction, retry and provider request limits; unset values keep the defaults. */
+    /** Retry and provider request limits; unset values keep the defaults. Compaction comes from the model. */
     settings?: AgentSettingsInput;
     turnAbortTimeoutMs?: number;
     onDiagnostic?: (diagnostic: AgentRuntimeDiagnostic) => void;

package/packages/ragents/src/drivers/agent-turn.ts

@@ -10,6 +10,7 @@ import {
     type AgentTool,
     calculateContextTokens,
     compact,
+    compactionOf,
     contextMessages,
     convertToLlm,
     EMPTY_RESPONSE_NUDGE,
@@ -626,12 +627,11 @@ export class AgentTurn {
         return true;
     }
 
-    /** After a context overflow compacts and retries once; over the threshold compacts without a retry. */
+    /** After a context overflow compacts and retries once; over the threshold of the turn's model compacts without a retry. */
     async #checkCompaction(assistant: AssistantMessage | undefined, skipAborted = true): Promise<boolean> {
-        const settings = this.#options.settings.compaction;
         const { model } = this.#options;
 
-        if (!assistant || !settings.enabled || (skipAborted && assistant.stopReason === "aborted"))
+        if (!assistant || (skipAborted && assistant.stopReason === "aborted"))
             return false;
 
         const contextWindow = model.contextWindow ?? 0;
@@ -672,12 +672,13 @@ export class AgentTurn {
             contextTokens = estimate.tokens;
         }
 
-        return shouldCompact(contextTokens, contextWindow, settings) ? this.#compact(false) : false;
+        return shouldCompact(contextTokens, compactionOf(model).values) ? this.#compact(false) : false;
     }
 
     async #compact(retry: boolean): Promise<boolean> {
-        const { model, modelRuntime, thinkingLevel, settings } = this.#options;
-        const preparation = prepareCompaction([...this.#request.modelContext().entries], settings.compaction);
+        const { model, modelRuntime, thinkingLevel } = this.#options;
+        const compaction = compactionOf(model);
+        const preparation = prepareCompaction([...this.#request.modelContext().entries], compaction.values);
 
         if (!preparation)
             return false;
@@ -715,6 +716,7 @@ export class AgentTurn {
                     model: model.id,
                     readFiles: result.readFiles,
                     modifiedFiles: result.modifiedFiles,
+                    threshold: { tokens: compaction.values.threshold, source: compaction.source },
                 },
             });
             const messages = this.#request.modelContext().messages;

package/packages/ragents/src/runtime/decisions/inputs.ts

@@ -17,8 +17,8 @@ export type EnqueueInput = {
     artifactIds?: readonly string[];
     presentation?: "background";
 } & (
-    | { content: string; sourceEventIds?: readonly string[]; subscriptionId?: null }
-    | { content?: never; sourceEventIds: readonly [string]; subscriptionId: string }
+    | { content: string; sourceEventIds?: readonly string[]; subscriptionId?: null; origin?: "human" }
+    | { content?: never; sourceEventIds: readonly [string]; subscriptionId: string; origin?: never }
 );
 
 export const enqueueInput =
@@ -43,6 +43,9 @@ export const enqueueInput =
             assertCapability(caller, "actor.input", { kind: "run" });
         }
 
+        if (input.origin === "human" && caller.kind !== "human")
+            throw new DomainError("input-origin-invalid", "Only a human can enqueue an input of human origin.", 403);
+
         const artifactIds = [...new Set(input.artifactIds ?? [])];
 
         for (const artifactId of artifactIds)
@@ -55,6 +58,7 @@ export const enqueueInput =
             actorId: target.id,
             artifactIds,
             ...(input.presentation !== undefined ? { presentation: input.presentation } : {}),
+            ...(input.origin !== undefined ? { origin: input.origin } : {}),
         };
 
         if (subscriptionId && firstSourceEventId === undefined)

package/packages/ragents/src/runtime/journal-storage.ts

@@ -8,9 +8,10 @@ import { isRunId } from "../domain/portable-id.ts";
 import { syncDirectory } from "./durable-fs.ts";
 import type { CommandRecord, JournalCommand } from "./journal.ts";
 
-/** Rises whenever an older stand would reject newly written lines; the journal reads only this version. */
-export const journalStorageVersion = 7;
-const readableJournalStorageVersions: readonly unknown[] = [journalStorageVersion];
+/** Rises whenever an older stand would reject newly written lines; formats 7 and 8 stay readable because they only lack the input origin and the compaction threshold. */
+export const journalStorageVersion = 9;
+const oldestReadableJournalStorageVersion = 7;
+const readableJournalStorageVersions: readonly unknown[] = [oldestReadableJournalStorageVersion, 8, journalStorageVersion];
 export const journalPayloadThresholdBytes = 4096;
 
 type PayloadReference = { sha256: string; bytes: number };
@@ -162,7 +163,7 @@ export const parseJournalRecord = (line: string, runDirectory: string, location:
 
     if (!readableJournalStorageVersions.includes(record.formatVersion))
         throw new Error(`${location} has unsupported journal format version ${String(record.formatVersion)}.${
-            typeof record.formatVersion === "number" && record.formatVersion < journalStorageVersion
+            typeof record.formatVersion === "number" && record.formatVersion < oldestReadableJournalStorageVersion
                 ? " Journals before format 7 hold no model context and are not migrated."
                 : ""}`);
 

package/packages/workspace-executor/package.json

@@ -15,7 +15,6 @@
   "dependencies": {
     "@ragents/agent": "workspace:*",
     "typescript": "^5.9.0",
-    "typescript-language-server": "6.0.0",
     "vscode-jsonrpc": "^9.0.2"
   },
   "devDependencies": {

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

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { accessSync, constants, existsSync, statSync } from "node:fs";
 import path from "node:path";
 import { getShellConfig } from "@ragents/agent";
 
@@ -9,6 +9,12 @@ export interface BashLaunch {
   readonly env: NodeJS.ProcessEnv;
 }
 
+/** Was der Executor dem Werkzeug bash mitgibt: die Bash selbst und rg; ohne Angabe gilt jeweils das des Systems. */
+export interface BashPrograms {
+  readonly bash: string | undefined;
+  readonly rg: string | undefined;
+}
+
 /** Unter Windows sucht RAgents keine Bash; der Executor nennt die mitgebrachte. */
 const missingWindowsBash = (): Error => new Error(
   "Unter Windows arbeitet das Werkzeug bash nur mit der Bash, die RAgents mitbringt, und für diesen Executor ist keine genannt. "
@@ -16,17 +22,51 @@ const missingWindowsBash = (): Error => new Error(
   + "und reicht sie an Arbeitsplatz und lokalen Host weiter; ein Host oder Arbeitsplatz ohne Erweiterung braucht RAGENTS_BASH mit dem Pfad dieser bash.exe.",
 );
 
-/** Die Windows-Umgebung der Bash: ihr usr/bin vorn im PATH, damit find.exe und sort.exe aus System32 nicht gewinnen; MSYSTEM gehört einer Git-Bash-Anmeldung. */
-const windowsBashEnvironment = (env: NodeJS.ProcessEnv, bin: string): NodeJS.ProcessEnv => {
-  const pathNames = Object.keys(env).filter((name) => name.toUpperCase() === "PATH");
-  const current = pathNames.map((name) => env[name]).find((value) => value !== undefined && value !== "");
-  const kept = Object.entries(env).filter(([name]) => !pathNames.includes(name) && name !== "MSYSTEM");
-  return { ...Object.fromEntries(kept), PATH: current ? `${bin}${path.win32.delimiter}${current}` : bin };
+const missingRipgrep = (rg: string): Error =>
+  new Error(`Das rg dieses Executors fehlt: ${rg}. Es gehört zur Erweiterung (dist/rg/<plattform>) oder steht in RAGENTS_RG.`);
+
+const pathModule = (platform: NodeJS.Platform): path.PlatformPath => platform === "win32" ? path.win32 : path.posix;
+
+/** Die Namen der PATH-Variablen; unter Windows zählt jede Schreibweise (`Path`). */
+const pathNames = (env: NodeJS.ProcessEnv, platform: NodeJS.Platform): readonly string[] =>
+  platform === "win32" ? Object.keys(env).filter((name) => name.toUpperCase() === "PATH") : ["PATH"];
+
+const currentPath = (env: NodeJS.ProcessEnv, platform: NodeJS.Platform): string | undefined =>
+  pathNames(env, platform).map((name) => env[name]).find((value) => value !== undefined && value !== "");
+
+/** Die Ordner vorn im PATH, als eine Variable PATH; MSYSTEM gehört unter Windows einer Git-Bash-Anmeldung und fällt weg. */
+const withPathFront = (env: NodeJS.ProcessEnv, directories: readonly string[], platform: NodeJS.Platform): NodeJS.ProcessEnv => {
+  if (directories.length === 0) return env;
+  const names = pathNames(env, platform);
+  const current = currentPath(env, platform);
+  const kept = Object.entries(env).filter(([name]) => !names.includes(name) && (platform !== "win32" || name !== "MSYSTEM"));
+  const delimiter = pathModule(platform).delimiter;
+  return { ...Object.fromEntries(kept), PATH: [...directories, ...(current ? [current] : [])].join(delimiter) };
+};
+
+const isExecutableFile = (file: string, platform: NodeJS.Platform): boolean => {
+  try {
+    if (platform !== "win32") accessSync(file, constants.X_OK);
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/** Ob die Bash dieses Executors rg findet: das genannte, sonst eines im PATH; ein genanntes, das fehlt, ist ein Fehler. */
+export const ripgrepAvailable = (rg: string | undefined, env: NodeJS.ProcessEnv, platform: NodeJS.Platform = process.platform): boolean => {
+  if (rg !== undefined) {
+    if (!existsSync(rg)) throw missingRipgrep(rg);
+    return true;
+  }
+  const file = platform === "win32" ? "rg.exe" : "rg";
+  return (currentPath(env, platform) ?? "").split(pathModule(platform).delimiter).filter(Boolean)
+    .some((directory) => isExecutableFile(path.join(directory, file), platform));
 };
 
-/** Wie ein Befehl in der Bash dieses Executors startet; die Plattform ist für Prüfungen wählbar. */
+/** Wie ein Befehl in der Bash dieses Executors startet: das Verzeichnis von rg vorn im PATH, unter Windows dahinter das usr/bin der Bash, damit find.exe und sort.exe aus System32 nicht gewinnen. */
 export const bashLaunch = (
-  bash: string | undefined,
+  { bash, rg }: BashPrograms,
   command: string,
   env: NodeJS.ProcessEnv,
   platform: NodeJS.Platform = process.platform,
@@ -35,11 +75,17 @@ export const bashLaunch = (
   if (bash !== undefined && !existsSync(bash)) {
     throw new Error(`Die Bash dieses Executors fehlt: ${bash}. Unter Windows gehört sie zur Erweiterung (dist/bash/<plattform>) oder steht in RAGENTS_BASH.`);
   }
+  if (rg !== undefined && !existsSync(rg)) throw missingRipgrep(rg);
   const shell = getShellConfig(bash, platform);
   if (!/bash(\.exe)?$/i.test(shell.shell)) throw new Error(`${shell.shell} ist keine Bash; das Werkzeug heißt bash und der Prompt beschreibt bash`);
+  const paths = pathModule(platform);
+  const front = [
+    ...(rg === undefined ? [] : [paths.dirname(rg)]),
+    ...(platform === "win32" ? [paths.dirname(shell.shell)] : []),
+  ];
   return {
     command: shell.shell,
     args: [...shell.args, command],
-    env: platform === "win32" ? windowsBashEnvironment(env, path.win32.dirname(shell.shell)) : env,
+    env: withPathFront(env, front, platform),
   };
 };

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

@@ -27,6 +27,8 @@ export interface WorkspaceProcessContext {
   sandbox?: ProcessSandbox;
   /** Die Bash, mit der das Werkzeug bash startet; unter Windows Pflicht, sonst gilt ohne Angabe die des Systems. */
   bash?: string;
+  /** Das rg, dessen Ordner das Werkzeug bash vorn im PATH hat; ohne Angabe gilt eines im PATH, falls es eines gibt. */
+  rg?: string;
 }
 
 export interface SandboxHomeEnvironment {
@@ -103,6 +105,7 @@ export interface WorkspaceContextOptions {
   source?: NodeJS.ProcessEnv;
   baseEnvironment?: BaseEnvironment;
   bash?: string;
+  rg?: string;
 }
 
 const namedEntries = (
@@ -151,5 +154,6 @@ export const workspaceProcessContext = (options: WorkspaceContextOptions): Works
     ...(options.runOperation === undefined ? {} : { runOperation: options.runOperation }),
     ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
     ...(options.bash === undefined ? {} : { bash: options.bash }),
+    ...(options.rg === undefined ? {} : { rg: options.rg }),
   };
 };

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

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { WorkspaceOperationError } from "./errors.js";
+import type { LanguageServerAdapter } from "./language-server/host.js";
+import { resolveRootDirectory, resolveRootFile } from "./language-server/roots.js";
+import type { WorkspaceModuleFactory } from "./module.js";
+import { RUN_MARKER_ENV } from "./run-marker.js";
+import { safeProcessEnvironment } from "./safe-environment.js";
+
+/** Wo ein Bundle seinen Beitrag zum Executor trägt: eine in sich geschlossene Datei, die jeder Node-Prozess ohne Host-Auflösung lädt. */
+export const EXECUTOR_CONTRIBUTION_FILE = "executor/index.mjs";
+
+/** Was der Executor einer Maschine einem Beitrag über sie sagt; ein Beitrag importiert vom Host nur Typen, alles andere kommt hierüber. */
+export interface WorkspaceExecutorMachine {
+  /** Der Werkzeugordner des Plugins auf dieser Maschine, wohin seine Provisionierung lädt. */
+  readonly toolsDirectory: string;
+  /** Eine Datei aus einem Paket in den node_modules des Hosts dieser Maschine; ohne Host oder Paket scheitert der Aufruf mit Ursache. */
+  readonly hostPackageFile: (hostRoot: string | undefined, specifier: string) => string;
+  /** Eine Datei mit einer der Endungen im Arbeitsbereich, aufgelöst und geprüft. */
+  readonly resolveRootFile: (workspaceRoot: string, requested: string, extensions: readonly string[]) => Promise<string>;
+  /** Ein Ordner im Arbeitsbereich, aufgelöst und geprüft. */
+  readonly resolveRootDirectory: (workspaceRoot: string, requested: string) => Promise<string>;
+  /** Ein fachlicher Fehler einer Operation mit Kennung und Status; beim Aufrufer kommt er als derselbe Fehler an wie einer des Executors. */
+  readonly operationError: (code: string, message: string, status: number) => Error;
+  /** Die Umgebung eines Prozesses, den ein Beitrag selbst startet: die sichere Auswahl dieser Maschine, ihr HOME und der Marker des Runs für die Prozessanzeige. */
+  readonly processEnvironment: (runId: string) => NodeJS.ProcessEnv;
+}
+
+/** Was ein Beitrag dem Executor einer Maschine hinzufügt. */
+export interface WorkspaceExecutorParts {
+  readonly languageServers?: readonly LanguageServerAdapter[];
+  /** Module mit eigenen Operationen; jede Operation gehört genau einem Modul. */
+  readonly modules?: readonly WorkspaceModuleFactory[];
+}
+
+/** Was ein Plugin-Bundle als `executor` exportiert; es läuft in jedem Executor, im Server wie auf jedem Arbeitsplatz, und berührt beim Bauen weder Platte noch Netz. */
+export type WorkspaceExecutorContribution = (machine: WorkspaceExecutorMachine) => WorkspaceExecutorParts;
+
+/** Wessen Beitrag in welchem Stand; Server und Arbeitsplatz verlangen dieselben. */
+export interface ExecutorContributionStand {
+  readonly plugin: string;
+  /** SHA-256 der Datei des Beitrags. */
+  readonly stand: string;
+}
+
+export interface LoadedExecutorContribution extends ExecutorContributionStand {
+  readonly contribution: WorkspaceExecutorContribution;
+}
+
+/** Ein Beitrag, gebaut für diese Maschine. */
+export interface PreparedExecutorContribution extends ExecutorContributionStand {
+  readonly parts: WorkspaceExecutorParts;
+}
+
+const LANGUAGE_SERVER_ID = /^[a-z][a-z0-9]{0,39}$/;
+const PART_KEYS = new Set(["languageServers", "modules"]);
+
+const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
+
+/** Der Paketname eines Bezeichners wie acme-server/lib/cli.mjs oder @scope/name/datei. */
+const packageOf = (specifier: string): string =>
+  specifier.split("/").slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
+
+const hostPackageFile = (hostRoot: string | undefined, specifier: string): string => {
+  if (!hostRoot) {
+    throw new Error(`Auf diesem Rechner ist kein Host bekannt, aus dem sich ${packageOf(specifier)} auflösen ließe. Ein Arbeitsplatz `
+      + "bekommt ihn mit der ersten Verbindung zu einem verteilenden Server oder über die Einstellung ragents.hostPath");
+  }
+  try {
+    return createRequire(path.join(hostRoot, "package.json")).resolve(specifier);
+  } catch (cause) {
+    throw new Error(`${packageOf(specifier)} liegt nicht im Host ${hostRoot}: ${messageOf(cause)}`);
+  }
+};
+
+export const executorMachine = (toolsDirectory: string): WorkspaceExecutorMachine => ({
+  toolsDirectory,
+  hostPackageFile,
+  resolveRootFile,
+  resolveRootDirectory,
+  operationError: (code, message, status) => new WorkspaceOperationError(code, message, status),
+  processEnvironment: (runId) => ({ ...safeProcessEnvironment(process.env), HOME: homedir(), [RUN_MARKER_ENV]: runId }),
+});
+
+/** Lädt die Datei eines Beitrags, mit `expected` nur in diesem Stand; der Stand steht in ihrer Adresse, damit ein neu gebauter Beitrag nie aus dem Modulcache kommt. */
+export const loadExecutorContribution = async (plugin: string, file: string, expected?: string): Promise<LoadedExecutorContribution> => {
+  const content = await readFile(file).catch((cause: unknown) => {
+    throw new Error(`Der Executor-Beitrag von ${plugin} fehlt unter ${file}: ${messageOf(cause)}`);
+  });
+  const stand = createHash("sha256").update(content).digest("hex");
+  if (expected !== undefined && stand !== expected) {
+    throw new Error(`Der Executor-Beitrag von ${plugin} unter ${file} hat den Stand ${stand.slice(0, 12)}, verlangt ist ${expected.slice(0, 12)}`);
+  }
+  const exported = await import(`${pathToFileURL(file).href}?stand=${stand}`).catch((cause: unknown) => {
+    throw new Error(`Der Executor-Beitrag von ${plugin} (${file}) lädt nicht: ${messageOf(cause)}`, { cause });
+  }) as Readonly<Record<string, unknown>>;
+  const contribution = exported.executor;
+  if (typeof contribution !== "function") {
+    throw new Error(`Das Bundle ${plugin} exportiert in ${file} keinen gültigen Executor-Beitrag; erwartet wird `
+      + "\"export const executor: WorkspaceExecutorContribution\" als Funktion der Maschine");
+  }
+  return { plugin, stand, contribution: contribution as WorkspaceExecutorContribution };
+};
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isStringList = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((entry) => typeof entry === "string");
+
+/** Was an einem Sprachserver fehlt oder die falsche Form hat; leer, wenn er taugt. */
+const adapterProblems = (value: Readonly<Record<string, unknown>>): readonly string[] => [
+  ...typeof value.id === "string" && LANGUAGE_SERVER_ID.test(value.id) ? [] : ["id aus Kleinbuchstaben und Ziffern"],
+  ...typeof value.label === "string" ? [] : ["label"],
+  ...isRecord(value.languages) && Object.values(value.languages).every((entry) => typeof entry === "string") ? [] : ["languages"],
+  ...typeof value.rootDescription === "string" ? [] : ["rootDescription"],
+  ...value.solutionExtensions === undefined || isStringList(value.solutionExtensions) ? [] : ["solutionExtensions"],
+  ...(["resolveRoot", "rootDirectory", "launch", "open"] as const).filter((name) => typeof value[name] !== "function"),
+];
+
+/** Baut einen geladenen Beitrag für diese Maschine und prüft, was er liefert; eine falsche Form ist ein Fehler mit Ursache. */
+export const prepareExecutorContribution = (loaded: LoadedExecutorContribution, toolsDirectory: string): PreparedExecutorContribution => {
+  const invalid = (detail: string): Error => new Error(`Der Executor-Beitrag von ${loaded.plugin} ist ungültig: ${detail}`);
+  const parts = ((): unknown => {
+    try {
+      return loaded.contribution(executorMachine(toolsDirectory));
+    } catch (cause) {
+      throw invalid(`die Funktion wirft: ${messageOf(cause)}`);
+    }
+  })();
+  if (!isRecord(parts)) throw invalid("die Funktion liefert kein Objekt");
+  const unknown = Object.keys(parts).filter((key) => !PART_KEYS.has(key));
+  if (unknown.length > 0) throw invalid(`unbekannte Teile ${unknown.join(", ")}; erlaubt sind ${[...PART_KEYS].join(", ")}`);
+  const modules = parts.modules;
+  if (modules !== undefined && (!Array.isArray(modules) || !modules.every((module) => typeof module === "function"))) {
+    throw invalid("modules ist keine Liste von Modulfabriken");
+  }
+  const servers = parts.languageServers;
+  if (servers !== undefined && !Array.isArray(servers)) throw invalid("languageServers ist keine Liste");
+  for (const [index, server] of (servers ?? []).entries()) {
+    if (!isRecord(server)) throw invalid(`der Sprachserver ${index + 1} ist kein Objekt`);
+    const problems = adapterProblems(server);
+    if (problems.length > 0) throw invalid(`der Sprachserver ${index + 1} braucht ${problems.join(", ")}`);
+  }
+  return { plugin: loaded.plugin, stand: loaded.stand, parts: parts as WorkspaceExecutorParts };
+};

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

@@ -4,7 +4,7 @@ import type { WorkspaceExecutorModule, WorkspaceModuleFactory, WorkspaceOperatio
 import { NO_ROOTS, type OperationFootprint } from "./paths.js";
 
 /** Der Stand des Executors; Server und Arbeitsplatz müssen denselben tragen. */
-export const WORKSPACE_EXECUTOR_VERSION = "5";
+export const WORKSPACE_EXECUTOR_VERSION = "7";
 
 export interface WorkspaceExecuteOptions {
   toolCallId?: string;

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

@@ -18,6 +18,18 @@ export {
   type WorkspaceModuleFactory,
 } from "./module.js";
 export { workspaceExecutorModules, type WorkspaceExecutorModuleOptions } from "./modules.js";
+export {
+  EXECUTOR_CONTRIBUTION_FILE,
+  executorMachine,
+  loadExecutorContribution,
+  prepareExecutorContribution,
+  type ExecutorContributionStand,
+  type LoadedExecutorContribution,
+  type PreparedExecutorContribution,
+  type WorkspaceExecutorContribution,
+  type WorkspaceExecutorMachine,
+  type WorkspaceExecutorParts,
+} from "./contributions.js";
 export { RUN_FOLDER_OPERATIONS, runFolderModule, type RunFolderCreated } from "./run-folders.js";
 export {
   FILE_OPERATIONS,
@@ -37,18 +49,6 @@ export {
   type CommandResult,
   type CommandRunInput,
 } from "./commands.js";
-export {
-  BROWSER_EXECUTABLE_VARIABLE,
-  BROWSER_OPERATIONS,
-  type BrowserCheck,
-  type BrowserCheckResult,
-  type BrowserPageState,
-  type BrowserSnapshot,
-  type BrowserStep,
-  type BrowserTarget,
-  type BrowserViewport,
-} from "./browser/contract.js";
-export { browserModule, type BrowserModuleOptions } from "./browser/module.js";
 export { processGroupExists, runManagedProcess, startManagedService, type ManagedService } from "./managed-process.js";
 export {
   containsWorkspacePath,
@@ -81,15 +81,16 @@ export { labelOf, runProcessesFrom } from "./processes/snapshot.js";
 export { RunProcessTerminator } from "./processes/terminator.js";
 export { RUN_MARKER_ENV } from "./run-marker.js";
 export { editorFreeEnvironment, inheritedProcessEnvironment, safeProcessEnvironment } from "./safe-environment.js";
-export { bashLaunch, type BashLaunch } from "./bash-launch.js";
+export { bashLaunch, ripgrepAvailable, type BashLaunch, type BashPrograms } from "./bash-launch.js";
 export { createSandboxTools, sandboxToolsModule, withAnnotation, type SeenFile } from "./sandbox-tools.js";
 export { type SessionIdent } from "./session-ident.js";
-export { shellPlatformText } from "./shell-platform.js";
-export { ragentsDataRoot, workspaceDataDirectory } from "./tools.js";
+export { shellPlatformText, type ShellTools } from "./shell-platform.js";
+export { hostDataDirectory, pluginToolsDirectory, ragentsDataRoot, workspaceDataDirectory } from "./tools.js";
 export {
   LanguageServerHost,
   changedWorkspaceFiles,
   type LanguageServerAdapter,
+  type LanguageServerDescription,
   type LanguageServerHostOptions,
 } from "./language-server/host.js";
 export {
@@ -112,7 +113,3 @@ export {
 } from "./language-server/module.js";
 export { resolveRootDirectory } from "./language-server/roots.js";
 export { LanguageServerSession, withTimeout } from "./language-server/session.js";
-export { solutionProjects } from "./language-server/solution.js";
-export { fsharpAdapter, FSHARP_SERVER_FILE, FSHARP_SERVER_VARIABLE } from "./language-server/adapters/fsharp.js";
-export { roslynAdapter, ROSLYN_SERVER_FILE, ROSLYN_SERVER_VARIABLE } from "./language-server/adapters/roslyn.js";
-export { typescriptAdapter } from "./language-server/adapters/typescript.js";

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

@@ -27,6 +27,9 @@ export interface LanguageServerAdapter {
   open: (session: LanguageServerSession, root: string, timeoutMs: number) => Promise<string>;
 }
 
+/** Was der Server über einen Sprachserver wissen muss, um Werkzeuge und Reiter zu beschreiben; gestartet wird er nur im Executor. */
+export type LanguageServerDescription = Pick<LanguageServerAdapter, "id" | "label" | "languages" | "rootDescription" | "solutionExtensions">;
+
 export interface LanguageServerHostOptions {
   idleMs?: number;
   openTimeoutMs?: number;

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

@@ -1,5 +1,5 @@
 import { WorkspaceOperationError } from "../errors.js";
-import type { WorkspaceModuleFactory, WorkspaceOperation } from "../module.js";
+import type { WorkspaceExecutorModule, WorkspaceModuleFactory, WorkspaceModuleHost, WorkspaceOperation } from "../module.js";
 import { rootsOfFields, type OperationFootprint } from "../paths.js";
 import { LanguageServerHost, type LanguageServerAdapter, type LanguageServerHostOptions } from "./host.js";
 
@@ -89,7 +89,17 @@ const footprintsOf = (server: LanguageServerHost): Array<readonly [string, (inpu
 export const languageServerModule = (
   adapters: readonly LanguageServerAdapter[],
   options: LanguageServerHostOptions = {},
-): WorkspaceModuleFactory => (host) => {
+): WorkspaceModuleFactory => {
+  const duplicate = adapters.find((adapter, index) => adapters.findIndex((other) => other.id === adapter.id) !== index);
+  if (duplicate) throw new Error(`Der Sprachserver ${duplicate.id} kommt im Executor zweimal vor; seine Operationen gehören genau einem Beitrag`);
+  return (host) => languageServersOn(host, adapters, options);
+};
+
+const languageServersOn = (
+  host: WorkspaceModuleHost,
+  adapters: readonly LanguageServerAdapter[],
+  options: LanguageServerHostOptions,
+): WorkspaceExecutorModule => {
   const servers = adapters.map((adapter) => new LanguageServerHost(adapter, host.contextFor, options));
   return {
     operations: Object.fromEntries(servers.flatMap(operationsOf)),