@schlenkr/ragents 0.1.7 → 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/agents/plugins.ts

@@ -19,6 +19,8 @@ export type ToolContributor = {
     name: string;
     descriptors: readonly ToolDescriptor[];
     dynamic?: boolean;
+    /** Ob die Werkzeuge in einem Run gelten; ohne Angabe in jedem, sonst fehlen sie dort ganz. */
+    runCondition?: (runId: string) => boolean;
     tools: (context: PluginContext) => readonly RunFunction[] | Promise<readonly RunFunction[]>;
 };
 
@@ -74,6 +76,9 @@ export class ToolRegistry implements ToolProvider {
         const taken = new Set(agentTools.map((entry) => entry.name));
 
         for (const plugin of this.#plugins) {
+            if (plugin.runCondition && !plugin.runCondition(context.runId))
+                continue;
+
             const tools = await plugin.tools(context);
             this.#assertDescriptors(plugin, tools);
 

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/index.ts

@@ -27,6 +27,7 @@ export {
     PluginHost,
     ProfileContributionRegistry,
     PromptContributionRegistry,
+    RunConditionRegistry,
     SessionMetadataContributionRegistry,
     SkillContributionRegistry,
     StartEntryContributionRegistry,

package/packages/ragents/src/plugin-host.ts

@@ -41,6 +41,7 @@ import type {
   RAgentsPlugin,
   ServiceToken,
   RegisteredStartOption,
+  RunCondition,
   SessionLifecycleContribution,
   SessionMetadata,
   SessionStartedContext,
@@ -86,6 +87,24 @@ class ContributionRegistry<T extends { id: string }> {
   }
 }
 
+/** Die Laufbedingung je Plugin; ein Plugin ohne gilt in jedem Run. */
+export class RunConditionRegistry {
+  readonly #conditions = new Map<string, RunCondition>();
+
+  register(owner: string, condition: RunCondition): void {
+    if (this.#conditions.has(owner)) throw new Error(`Plugin ${owner} hat bereits eine Laufbedingung`);
+    this.#conditions.set(owner, condition);
+  }
+
+  has(owner: string): boolean {
+    return this.#conditions.has(owner);
+  }
+
+  applies(owner: string, runId: string): boolean {
+    return this.#conditions.get(owner)?.(runId) ?? true;
+  }
+}
+
 export class MethodContributionRegistry {
   readonly #methods = new ContributionRegistry<{ id: string; contribution: MethodContribution }>("Methode");
 
@@ -219,6 +238,11 @@ export class OperationContributionRegistry {
 
 export class AgentContributionRegistry {
   readonly #contributions = new ContributionRegistry<AgentContribution>("Agent-Beitrag");
+  readonly #conditions: RunConditionRegistry;
+
+  constructor(conditions = new RunConditionRegistry()) {
+    this.#conditions = conditions;
+  }
 
   register(owner: string, contributions: readonly AgentContribution[]): void {
     for (const contribution of contributions) {
@@ -230,7 +254,9 @@ export class AgentContributionRegistry {
   }
 
   resolve(context: AgentContributionContext): readonly AgentHook[] {
-    return this.#contributions.entries().map(({ value }) => agentHookOf(value, context));
+    return this.#contributions.entries()
+      .filter(({ owner }) => this.#conditions.applies(owner, context.runId))
+      .map(({ value }) => agentHookOf(value, context));
   }
 
   describe(): readonly PublicAgentHookContribution[] {
@@ -246,6 +272,11 @@ export class AgentContributionRegistry {
 
 export class ToolContributionRegistry {
   readonly #contributors: Owned<ToolContributor>[] = [];
+  readonly #conditions: RunConditionRegistry;
+
+  constructor(conditions = new RunConditionRegistry()) {
+    this.#conditions = conditions;
+  }
 
   register(owner: string, contributors: readonly ToolContributor[]): void {
     for (const contributor of contributors) {
@@ -278,7 +309,9 @@ export class ToolContributionRegistry {
   }
 
   entries(): readonly ToolContributor[] {
-    return this.#contributors.map(({ value }) => value);
+    return this.#contributors.map(({ owner, value }) => this.#conditions.has(owner)
+      ? { ...value, runCondition: (runId: string) => this.#conditions.applies(owner, runId) }
+      : value);
   }
 
   describe(): readonly PublicToolDescriptor[] {
@@ -295,6 +328,11 @@ export class ToolContributionRegistry {
 
 export class PromptContributionRegistry {
   readonly #prompts = new ContributionRegistry<PromptContribution>("Prompt-Beitrag");
+  readonly #conditions: RunConditionRegistry;
+
+  constructor(conditions = new RunConditionRegistry()) {
+    this.#conditions = conditions;
+  }
 
   register(owner: string, prompts: readonly PromptContribution[]): void {
     this.#prompts.register(owner, prompts);
@@ -330,10 +368,13 @@ export class PromptContributionRegistry {
     })));
   }
 
-  /** Die Beiträge, die für diesen Run anders lauten als im Schnappschuss; alles andere bleibt der gerenderte Text. */
+  /** Die Beiträge, die für diesen Run anders lauten als im Schnappschuss; ein leerer Text fehlt dort, alles andere bleibt der gerenderte Text. */
   runOverrides(runId: string): ReadonlyMap<string, string> {
-    return new Map([...this.#prompts.entries()].flatMap(({ value }) =>
-      value.renderForRun ? [[value.id, value.renderForRun(runId).trim()] as const] : []));
+    return new Map([...this.#prompts.entries()].flatMap(({ owner, value }) => {
+      if (!this.#conditions.applies(owner, runId)) return [[value.id, ""] as const];
+      const text = value.renderForRun?.(runId);
+      return text === undefined ? [] : [[value.id, text.trim()] as const];
+    }));
   }
 
   static handlebarsContext(context: PromptRenderContext): Record<string, unknown> {
@@ -343,6 +384,11 @@ export class PromptContributionRegistry {
 
 export class SkillContributionRegistry {
   readonly #skills = new ContributionRegistry<SkillContribution>("Skill-Beitrag");
+  readonly #conditions: RunConditionRegistry;
+
+  constructor(conditions = new RunConditionRegistry()) {
+    this.#conditions = conditions;
+  }
 
   register(owner: string, skills: readonly SkillContribution[]): void {
     for (const skill of skills) {
@@ -385,7 +431,7 @@ export class SkillContributionRegistry {
       id: value.id,
       owner,
       audiences: value.audiences ?? allAudiences,
-      paths: await value.paths(context),
+      paths: context && !this.#conditions.applies(owner, context.runId) ? [] : await value.paths(context),
     })));
   }
 }
@@ -1068,10 +1114,11 @@ export class PluginHost {
   readonly channels = new ChannelContributionRegistry();
   readonly http = new HttpContributionRegistry();
   readonly operations = new OperationContributionRegistry();
-  readonly agentRuntime = new AgentContributionRegistry();
-  readonly tools = new ToolContributionRegistry();
-  readonly prompts = new PromptContributionRegistry();
-  readonly skills = new SkillContributionRegistry();
+  readonly runConditions = new RunConditionRegistry();
+  readonly agentRuntime = new AgentContributionRegistry(this.runConditions);
+  readonly tools = new ToolContributionRegistry(this.runConditions);
+  readonly prompts = new PromptContributionRegistry(this.runConditions);
+  readonly skills = new SkillContributionRegistry(this.runConditions);
   readonly startEntries = new StartEntryContributionRegistry();
   readonly profiles = new ProfileContributionRegistry();
   readonly script = new ScriptContributionRegistry();
@@ -1121,6 +1168,7 @@ export class PluginHost {
       agentRuntime: (...entries) => this.agentRuntime.register(manifest.id, entries),
       profiles: (...entries) => this.profiles.register(manifest.id, entries),
       prompts: (...entries) => this.prompts.register(manifest.id, entries),
+      runCondition: (condition) => this.runConditions.register(manifest.id, condition),
       provide: (token, service) => this.#services.provide(manifest.id, token, service),
       service: (token) => this.#services.require(token),
       optionalService: (token) => this.#services.optional(token),

package/packages/ragents/src/plugin-types.ts

@@ -277,10 +277,13 @@ export interface PromptContribution {
   delivery?: "initial" | "on-demand";
   requiresTools?: readonly string[];
   render: (context: PromptRenderContext) => string | Promise<string>;
-  /** Hängt der Beitrag am einzelnen Run, ersetzt dieser Text den von `render` - synchron, damit der Turn ihn ohne Warten hat. */
-  renderForRun?: (runId: string) => string;
+  /** Hängt der Beitrag am einzelnen Run, ersetzt dieser Text den von `render`, undefined behält ihn - synchron, damit der Turn ihn ohne Warten hat. */
+  renderForRun?: (runId: string) => string | undefined;
 }
 
+/** Ob die laufbezogenen Beiträge eines Plugins in einem Run gelten; der Host fragt je Run, ein Wurf lässt dessen Turn mit dieser Ursache scheitern. */
+export type RunCondition = (runId: string) => boolean;
+
 export type ModelProviderConfig = Parameters<ModelRuntime["registerProvider"]>[1];
 
 export interface ModelProviderRegistration {
@@ -420,6 +423,8 @@ export interface PluginRegistration {
   agentRuntime: (...contributions: readonly AgentContribution[]) => void;
   profiles: (...contributions: readonly ProfileContribution[]) => void;
   prompts: (...contributions: readonly PromptContribution[]) => void;
+  /** Prompts, Funktionen, Skills und Agent-Hooks dieses Plugins gelten nur in Runs, für die die Bedingung zutrifft; höchstens eine je Plugin. */
+  runCondition: (condition: RunCondition) => void;
   provide: <T>(token: ServiceToken<T>, service: T) => void;
   service: <T>(token: ServiceToken<T>) => T;
   optionalService: <T>(token: ServiceToken<T>) => T | undefined;

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 }),
   };
 };