@schlenkr/ragents 0.1.5 → 0.1.7

package/packages/ragents/src/runtime/orchestration.ts

@@ -1,8 +1,11 @@
-import type { JournalEvent, UncommittedEvent } from "../domain/events.ts";
-import { assertJsonValue, type JsonValue } from "../domain/json.ts";
+import type { ImageContent, TextContent, UserContent } from "@ragents/ai";
+
+import type { EventPayloads, JournalEvent, ModelInputContent, ModelToolResultPart, UncommittedEvent } from "../domain/events.ts";
+import { derivedToolResultText } from "../domain/tool-result-text.ts";
+import { ModelContexts } from "../agents/model-context.ts";
+import { assertJsonValue, type JsonObject, type JsonValue } from "../domain/json.ts";
 import type {
     ActionInput,
-    ActionKind,
     ActionStatus,
     ActorKind,
     AgentExecution,
@@ -25,7 +28,7 @@ import * as turns from "./decisions/turns.ts";
 import { DomainError } from "./domain-error.ts";
 import {
     actorById,
-    actorOf,
+    commandActorOf,
     addressedActorOf,
     assertArtifactRead,
     assertCapability,
@@ -33,6 +36,7 @@ import {
     clean,
     executableActorOf,
     handleOf,
+    turnOf,
 } from "./guards.ts";
 import { journalFormatVersion, sameJournalCommand, type CommandRecord, type Journal } from "./journal.ts";
 import type { RuntimeServices } from "./services.ts";
@@ -41,17 +45,32 @@ export type { CommandContext } from "./command.ts";
 
 const errorMessage = (error: unknown) => error instanceof Error ? error.message : String(error);
 
+const firstOf = <Value, Found extends Value>(values: Iterable<Value>, matches: (value: Value) => value is Found): Found | undefined => {
+    for (const value of values)
+        if (matches(value))
+            return value;
+
+    return undefined;
+};
+
 export class Orchestration {
     readonly #journal: Journal;
     readonly #services: RuntimeServices;
     readonly #artifactContents: ArtifactContents;
     readonly #suppressedSubscriptionRuns = new Set<string>();
+    readonly #modelContexts: ModelContexts;
 
     constructor(journal: Journal, services: RuntimeServices, artifactContents: ArtifactContents = new MemoryArtifactContents()) {
         this.#journal = journal;
         this.#services = services;
         this.#artifactContents = artifactContents;
+        this.#modelContexts = new ModelContexts({
+            eventsSince: (runId, sequence) => this.#journal.eventsSince(runId, sequence),
+            firstEventId: (runId) => this.#journal.firstEventId(runId),
+            media: (hash) => this.mediaContent(hash),
+        });
         this.#journal.subscribe((events) => {
+            this.#releaseModelContexts(events);
             this.#dispatchSubscriptions(events);
             this.#dispatchCreatorAlerts(events);
         });
@@ -107,6 +126,21 @@ export class Orchestration {
         return state;
     }
 
+    /** A value of the current state without cloning all of it; `read` must neither keep nor change the state. */
+    select<Value>(runId: string, read: (state: RunState) => Value): Value {
+        const found = this.#journal.select(runId, (state) => ({ value: read(state) }));
+
+        if (!found)
+            throw new DomainError("run-not-found", `Run ${runId} does not exist.`, 404);
+
+        return found.value;
+    }
+
+    /** The events of a run from the newest back, without copying the journal. */
+    recentEvents(runId: string) {
+        return this.#journal.recentEvents(runId);
+    }
+
     view(runId: string) {
         return viewOf(this.state(runId));
     }
@@ -126,7 +160,7 @@ export class Orchestration {
     }
 
     assertActorTurn(runId: string, actorId: string, turnId: string) {
-        actorOf(this.state(runId), { actorId, turnId });
+        commandActorOf(this.state(runId), { actorId, turnId });
     }
 
     createRun(
@@ -135,6 +169,8 @@ export class Orchestration {
             title: string;
             ownerHandle: string;
             ownerDisplayName: string;
+            /** Der angemeldete Benutzer, dem der Run gehört; ohne Anmeldung bleibt er offen. */
+            ownerUserId?: string;
             runId?: string;
             initialPluginStates?: readonly { pluginId: string; state: JsonValue }[];
         },
@@ -178,6 +214,7 @@ export class Orchestration {
                             scope: { kind: "run" },
                             delegable: true,
                         })),
+                        ...input.ownerUserId === undefined ? {} : { userId: clean(input.ownerUserId, "ownerUserId") },
                     },
                 },
             }),
@@ -272,6 +309,14 @@ export class Orchestration {
                 };
             }
 
+            if (entry.type === "context.compacted") {
+                return {
+                    ...entry,
+                    ...identities,
+                    payload: { ...entry.payload, firstKeptEventId: rewriteEventId(entry.payload.firstKeptEventId) },
+                };
+            }
+
             if (entry.type === "subscription.failed") {
                 return {
                     ...entry,
@@ -345,6 +390,7 @@ export class Orchestration {
             grants: readonly CapabilityGrant[];
             toolNames: readonly string[] | null;
             forkOf?: string;
+            description?: string;
         },
     ) {
         return this.#run(context, runId, "agent.spawn", input, actors.spawnAgent(input));
@@ -359,6 +405,7 @@ export class Orchestration {
             grants: readonly CapabilityGrant[];
             toolNames: readonly string[] | null;
             turnTimeoutMs?: number | null;
+            description?: string;
         },
     ) {
         return this.#run(context, runId, "script.create", input, actors.createScriptActor(input));
@@ -376,18 +423,115 @@ export class Orchestration {
         return this.#run(context, runId, "turn.start", { actorId, inputId }, turns.startTurn(actorId, inputId));
     }
 
-    appendModelOutput(context: CommandContext, runId: string, actorId: string, input: { turnId: string; text: string }) {
-        return this.#run(context, runId, "model.output.complete", { actorId, ...input }, turns.appendModelOutput(actorId, input));
+    steerInputs(context: CommandContext, runId: string, actorId: string, input: { turnId: string; inputIds: readonly string[] }) {
+        return this.#run(context, runId, "turn.steer", { actorId, ...input }, turns.steerInputs(actorId, input));
     }
 
-    appendModelReasoning(context: CommandContext, runId: string, actorId: string, input: { turnId: string; text: string }) {
-        return this.#run(context, runId, "model.reasoning.complete", { actorId, ...input }, turns.appendModelReasoning(actorId, input));
+    appendInterruptedModelOutput(context: CommandContext, runId: string, actorId: string, input: { turnId: string; text: string }) {
+        return this.#run(context, runId, "model.output.interrupt", { actorId, ...input }, turns.appendInterruptedModelOutput(actorId, input));
     }
 
     appendRuntimeOutput(context: CommandContext, runId: string, actorId: string, input: { turnId: string; text: string }) {
         return this.#run(context, runId, "runtime.output.record", { actorId, ...input }, turns.appendRuntimeOutput(actorId, input));
     }
 
+    /** The model context of an actor, extended by the events since the last call. */
+    modelContext(runId: string, actorId: string) {
+        return this.#modelContexts.contextOf(runId, actorId);
+    }
+
+    /** How many actor contexts are held in memory. */
+    heldModelContexts() {
+        return this.#modelContexts.size;
+    }
+
+    #releaseModelContexts(events: readonly JournalEvent[]) {
+        for (const event of events) {
+            if ((event.type !== "turn.finished" && event.type !== "turn.interrupted") || this.#journal.failureOf(event.runId))
+                continue;
+
+            const actorId = this.#journal.select(event.runId, (state) => state.turns.get(event.payload.turnId)?.actorId);
+
+            if (actorId)
+                this.#modelContexts.forgetActor(event.runId, actorId);
+        }
+    }
+
+    /** Removes a run from the journal and everything held for it in memory; its files stay. */
+    forgetRun(runId: string) {
+        this.#modelContexts.forget(runId);
+        return this.#journal.forget(runId);
+    }
+
+    /** The Base64 of stored media bytes, for the model context. */
+    mediaContent(hash: string): string {
+        return Buffer.from(this.#artifactContents.read(hash)).toString("base64");
+    }
+
+    #storedMedia(data: string): string {
+        return this.#artifactContents.put(Buffer.from(data, "base64")).hash;
+    }
+
+    presentModelInput(
+        context: CommandContext,
+        runId: string,
+        actorId: string,
+        input: { turnId: string; inputId: string | null; content: string | readonly UserContent[] },
+    ) {
+        const content: ModelInputContent = typeof input.content === "string"
+            ? input.content
+            : input.content.map((part) => {
+                if (part.type === "text") return { type: "text" as const, text: part.text };
+                const hash = this.#storedMedia(part.data);
+                return part.type === "file"
+                    ? { type: "file" as const, mimeType: part.mimeType, filename: part.filename, hash }
+                    : { type: part.type, mimeType: part.mimeType, hash };
+            });
+        const payload = { turnId: input.turnId, inputId: input.inputId, content };
+
+        return this.#run(context, runId, "model.input.present", { actorId, ...payload }, turns.presentModelInput(actorId, payload));
+    }
+
+    completeModelStep(context: CommandContext, runId: string, actorId: string, input: { turnId: string; step: turns.CompletedModelStep }) {
+        const step = JSON.parse(JSON.stringify(input.step)) as turns.CompletedModelStep;
+
+        return this.#run(context, runId, "model.step.complete", { actorId, turnId: input.turnId, step }, turns.completeModelStep(actorId, { turnId: input.turnId, step }));
+    }
+
+    /** Stores what the model saw of a tool result; the content is left out when it is exactly the text of the recorded result. */
+    presentToolResult(
+        context: CommandContext,
+        runId: string,
+        actorId: string,
+        input: { turnId: string; toolCallId: string; toolName: string; isError: boolean; content: readonly (TextContent | ImageContent)[] },
+    ) {
+        const content: ModelToolResultPart[] = input.content.map((part) => part.type === "text"
+            ? { type: "text", text: part.text }
+            : { type: "image", mimeType: part.mimeType, hash: this.#storedMedia(part.data) });
+        const recorded = firstOf(this.recentEvents(runId), (event): event is Extract<JournalEvent, { type: "tool.call.completed" | "tool.call.failed" }> =>
+            (event.type === "tool.call.completed" || event.type === "tool.call.failed")
+            && event.actorId === actorId
+            && event.payload.turnId === input.turnId
+            && event.payload.toolCallId === input.toolCallId);
+        const derived = recorded !== undefined
+            && content.length === 1
+            && content[0]!.type === "text"
+            && content[0]!.text === derivedToolResultText(recorded);
+        const payload = {
+            turnId: input.turnId,
+            toolCallId: input.toolCallId,
+            toolName: input.toolName,
+            isError: input.isError,
+            ...(derived ? {} : { content }),
+        };
+
+        return this.#run(context, runId, "model.tool-result.present", { actorId, ...payload }, turns.presentToolResult(actorId, payload));
+    }
+
+    compactContext(context: CommandContext, runId: string, actorId: string, input: EventPayloads["context.compacted"]) {
+        return this.#run(context, runId, "context.compact", { actorId, ...input }, turns.compactContext(actorId, input));
+    }
+
     startToolCall(
         context: CommandContext,
         runId: string,
@@ -471,7 +615,7 @@ export class Orchestration {
 
     listSubscriptions(runId: string, subscriberId?: string) {
         const state = this.state(runId);
-        const resolved = subscriberId ? addressedActorOf(state, subscriberId).id : null;
+        const resolved = subscriberId ? addressedActorOf(state.actors.values(), subscriberId).id : null;
 
         return [...state.subscriptions.values()].filter((subscription) => !resolved || subscription.subscriberId === resolved);
     }
@@ -480,12 +624,12 @@ export class Orchestration {
         context: CommandContext,
         runId: string,
         input: {
-            kind?: ActionKind;
-            question?: { options: readonly string[]; multi?: boolean } | null;
+            owner?: string | null;
             title: string;
             description?: string | null;
             parameters?: Record<string, string>;
             input?: ActionInput | null;
+            payload?: JsonObject | null;
         },
     ) {
         return this.#run(context, runId, "action.propose", input, actions.proposeAction(input));
@@ -495,7 +639,7 @@ export class Orchestration {
         context: CommandContext,
         runId: string,
         actionId: string,
-        input: { decision: Exclude<ActionStatus, "pending">; response?: string | null },
+        input: { decision: Exclude<ActionStatus, "pending">; result?: JsonValue | null },
     ) {
         return this.#run(context, runId, "action.resolve", { actionId, ...input }, actions.resolveAction(actionId, input));
     }
@@ -508,6 +652,10 @@ export class Orchestration {
         return this.#run(context, runId, "actor.stop", { actorId, reason }, actors.stopActor(actorId, reason));
     }
 
+    stopActors(context: CommandContext, runId: string, actorIds: readonly string[], reason: string) {
+        return this.#run(context, runId, "actors.stop", { actorIds, reason }, actors.stopActors(actorIds, reason));
+    }
+
     replacePluginState(
         context: CommandContext,
         runId: string,
@@ -527,7 +675,7 @@ export class Orchestration {
         runId: string,
         input: { title: string; mediaType: string; content: string | Uint8Array; previousVersionId: string | null },
     ) {
-        assertCapability(actorOf(this.state(runId), context), "artifact.publish", { kind: "run" });
+        assertCapability(commandActorOf(this.state(runId), context), "artifact.publish", { kind: "run" });
         const stored = this.#artifactContents.put(typeof input.content === "string" ? Buffer.from(input.content, "utf8") : input.content);
         const { content: _content, ...metadata } = input;
 
@@ -537,7 +685,7 @@ export class Orchestration {
     artifactContent(runId: string, artifactId: string, actorId: string) {
         const state = this.state(runId);
         const artifact = artifactOf(state, artifactId);
-        assertArtifactRead(state, addressedActorOf(state, actorId), artifact);
+        assertArtifactRead(state, addressedActorOf(state.actors.values(), actorId), artifact);
 
         return { artifact, content: this.#artifactContents.read(artifact.hash) };
     }
@@ -583,18 +731,18 @@ export class Orchestration {
                 continue;
 
             const alert = source.type === "turn.finished" && source.payload.outcome === "failed"
-                ? { kind: "failed" as const, reason: source.payload.reason }
+                ? { kind: "failed" as const, turnId: source.payload.turnId, reason: source.payload.reason }
                 : source.type === "turn.interrupted"
-                    ? { kind: "interrupted" as const, reason: source.payload.reason }
+                    ? { kind: "interrupted" as const, turnId: source.payload.turnId, reason: source.payload.reason }
                     : null;
 
             if (!alert)
                 continue;
 
             const state = this.state(source.runId);
-            const child = state.actors.get(source.actorId);
+            const child = executableActorOf(state, turnOf(state, alert.turnId).actorId);
 
-            if (!child || child.kind === "human" || !child.createdBy || child.createdBy === child.id)
+            if (child.createdBy === child.id || child.lifecycle.kind === "stopped")
                 continue;
 
             const creator = state.actors.get(child.createdBy);

package/packages/ragents/src/runtime/serial-queue.ts

@@ -11,3 +11,27 @@ export class SerialQueue {
         return result;
     }
 }
+
+/** One queue per key: work under one key runs in arrival order, keys never wait for each other. */
+export class KeyedSerialQueue {
+    readonly #tails = new Map<string, Promise<void>>();
+
+    run<Result>(key: string, work: () => Result | Promise<Result>) {
+        const result = (this.#tails.get(key) ?? Promise.resolve()).then(work);
+        const tail = result.then(
+            () => undefined,
+            () => undefined,
+        );
+        this.#tails.set(key, tail);
+        void tail.then(() => {
+            if (this.#tails.get(key) === tail)
+                this.#tails.delete(key);
+        });
+
+        return result;
+    }
+
+    get size() {
+        return this.#tails.size;
+    }
+}

package/packages/ragents/src/runtime/stop.ts

@@ -1,11 +1,10 @@
-import type { ExecutableActor, RunView } from "../domain/model.ts";
+import type { Actor, ExecutableActor, RunView } from "../domain/model.ts";
 import { isActiveActor } from "../domain/projection.ts";
+import { canonicalHash } from "./canonical-hash.ts";
 import type { CommandContext } from "./command.ts";
 import { throwFailures } from "./failures.ts";
 import type { Orchestration } from "./orchestration.ts";
 
-export type WorkingActor = ExecutableActor;
-
 export type RunStopCommand = {
     commandId: string;
     reason: string;
@@ -28,11 +27,11 @@ export type RunStopperOptions = {
     stopExternal?: RunStopBoundary;
 };
 
-export const descendantsOf = (view: RunView, rootId: string): WorkingActor[] => {
-    const working = view.actors.filter((entry): entry is WorkingActor => entry.kind !== "human");
+export const descendantsOf = (view: { readonly actors: Iterable<Actor> }, rootId: string): ExecutableActor[] => {
+    const working = [...view.actors].filter((entry): entry is ExecutableActor => entry.kind !== "human");
     const reached = new Set([rootId]);
     const frontier = [rootId];
-    const found: WorkingActor[] = [];
+    const found: ExecutableActor[] = [];
 
     for (const creatorId of frontier) {
         for (const actor of working) {
@@ -50,31 +49,6 @@ export const descendantsOf = (view: RunView, rootId: string): WorkingActor[] =>
     return found;
 };
 
-const actorStep = (actorId: string) => `actor:${actorId}`;
-
-export const lineageSteps = (lineage: readonly WorkingActor[]): string[] => lineage.map((entry) => actorStep(entry.id));
-
-export const stopLineage = (
-    runtime: Orchestration,
-    runId: string,
-    lineage: readonly WorkingActor[],
-    reason: string,
-    context: (step: string) => CommandContext,
-): unknown[] => {
-    const failures: unknown[] = [];
-    const ordered = [...lineage].sort((left, right) => (left.kind === right.kind ? 0 : left.kind === "script" ? -1 : 1));
-
-    for (const actor of ordered) {
-        try {
-            runtime.stopActor(context(actorStep(actor.id)), runId, actor.id, reason);
-        } catch (error: unknown) {
-            failures.push(error);
-        }
-    }
-
-    return failures;
-};
-
 export class RunStopper {
     readonly #options: RunStopperOptions;
     readonly #active = new Map<string, Promise<RunView>>();
@@ -159,28 +133,29 @@ export class RunStopper {
         context: (step: string) => CommandContext,
         cleanupSettled: Promise<void>,
     ) {
-        const attempted = new Set<string>();
         const failures: unknown[] = [];
-        const stopCurrentLineage = () => {
-            const lineage = descendantsOf(this.#options.runtime.view(runId), ownerId)
-                .filter((actor) => actor.id !== primaryActorId && !attempted.has(actor.id));
+        const stopOwnedActors = (step: string) => {
+            const lineage = descendantsOf(this.#options.runtime.view(runId), ownerId).filter((actor) => actor.id !== primaryActorId);
 
-            lineage.forEach((actor) => attempted.add(actor.id));
-            failures.push(...stopLineage(this.#options.runtime, runId, lineage, reason, context));
+            if (lineage.length === 0)
+                return;
 
-            return lineage.length;
-        };
+            const actorIds = lineage.map((actor) => actor.id);
 
-        while (stopCurrentLineage() > 0) {
-        }
+            try {
+                // The actors name the command, so a repeated stop with the same ID reaches actors created since.
+                this.#options.runtime.stopActors(context(`${step}:${canonicalHash(actorIds).slice(0, 16)}`), runId, actorIds, reason);
+            } catch (error: unknown) {
+                failures.push(error);
+            }
+        };
 
+        stopOwnedActors("before-cleanup");
         const cleanupResult = await Promise.allSettled([cleanupSettled]);
         if (cleanupResult[0]?.status === "rejected")
             failures.push(cleanupResult[0].reason);
 
-        while (stopCurrentLineage() > 0) {
-        }
-
+        stopOwnedActors("after-cleanup");
         throwFailures(failures, `Der Run ${runId} konnte nicht vollständig gestoppt werden.`);
     }
 }

package/packages/ragents/src/script/mediators.ts

@@ -1,3 +1,4 @@
+import { handleKey } from "../domain/actor-reference.ts";
 import type { RunCapabilityPort, RunStatePort } from "../typescript/run-context.ts";
 import { ScriptError } from "./types.ts";
 
@@ -43,8 +44,6 @@ const recordOf = (value: unknown): Record<string, unknown> | null =>
 
 const strippedOf = (value: string) => value.trim().replace(/^@/, "");
 
-const foldedOf = (value: string) => strippedOf(value).normalize("NFC").toLowerCase();
-
 const referenceOf = (what: string, value: unknown): string => {
     if (typeof value !== "string" || !strippedOf(value))
         throw new ScriptError(`${where}: ${what} muss eine Actor-ID oder ein Handle als nicht leerer Text sein.`);
@@ -53,7 +52,7 @@ const referenceOf = (what: string, value: unknown): string => {
 };
 
 const keysOf = (references: readonly string[]): MediatorKeys => {
-    const folded = new Map(references.map((reference) => [foldedOf(reference), reference] as const));
+    const folded = new Map(references.map((reference) => [handleKey(reference), reference] as const));
 
     if (folded.size !== references.length)
         throw new ScriptError(`${where}: table nennt denselben Beteiligten doppelt.`);
@@ -62,12 +61,12 @@ const keysOf = (references: readonly string[]): MediatorKeys => {
 };
 
 const keyOf = (keys: MediatorKeys, reference: string): string | null =>
-    keys.exact.has(reference) ? reference : keys.folded.get(foldedOf(reference)) ?? null;
+    keys.exact.has(reference) ? reference : keys.folded.get(handleKey(reference)) ?? null;
 
 const senderKeyOf = (keys: MediatorKeys, event: MediatorEvent): string | null =>
     keys.exact.has(event.sourceActorId)
         ? event.sourceActorId
-        : keys.folded.get(foldedOf(event.sourceActorHandle)) ?? null;
+        : keys.folded.get(handleKey(event.sourceActorHandle)) ?? null;
 
 const unknownTarget = (what: string, reference: string, keys: MediatorKeys): never => {
     throw new ScriptError(

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

@@ -21,6 +21,7 @@ export { typeScriptTypeFromSchema, typeScriptTypesFromSchema } from "./schema.ts
 export {
     createRunContextDeclarations,
     runCapabilityBindingHash,
+    runCapabilityDeclarations,
     runCapabilityContract,
     runCapabilityContractHash,
     runContextApiVersion,
@@ -39,6 +40,7 @@ export type { NativeTypeScriptProgram, NativeTypeScriptRequest, NativeTypeScript
 export {
     compileTypeScriptSnippet,
     executeTypeScriptSnippet,
+    typeScriptSnippetContextDeclarations,
     typeScriptSnippetDeclarations,
     TypeScriptSnippetCompilationError,
     TypeScriptSnippetExecutionError,

package/packages/ragents/src/typescript/run-context.ts

@@ -123,7 +123,8 @@ export interface RunContextDeclarationsOptions {
     readonly program: string;
 }
 
-const capabilityMap = (capabilities: readonly RunCapabilityDescriptor[]): string => {
+/** The types of the given functions as `RAgentsCapabilityMap`, without the declarations of the context around them. */
+export const runCapabilityDeclarations = (capabilities: readonly RunCapabilityDescriptor[]): string => {
     const seen = new Set<string>();
     const declarations: string[] = [];
     const sorted = [...capabilities].sort((left, right) => left.id.localeCompare(right.id));
@@ -159,10 +160,8 @@ const capabilityMap = (capabilities: readonly RunCapabilityDescriptor[]): string
     return `${declarations.join("\n")}${declarations.length > 0 ? "\n\n" : ""}type RAgentsCapabilityMap = ${map};`;
 };
 
-export const createRunContextDeclarations = (options: RunContextDeclarationsOptions): string => `
-${capabilityMap(options.capabilities)}
-
-interface RAgentsRunState<State> {
+/** The declarations of the context itself, the same for every function selection. */
+export const runContextFrameDeclarations = (stateType: string, program: string): string => `interface RAgentsRunState<State> {
   read(): State;
   replace(value: State): void;
 }
@@ -193,7 +192,10 @@ interface RAgentsRunContext<State, Capabilities> {
   throwIfAborted(): void;
 }
 
-type RunContext = RAgentsRunContext<${options.stateType}, RAgentsCapabilityMap>;
+type RunContext = RAgentsRunContext<${stateType}, RAgentsCapabilityMap>;
+
+${program.trim()}
+`;
 
-${options.program.trim()}
-`.trimStart();
+export const createRunContextDeclarations = (options: RunContextDeclarationsOptions): string =>
+    `${runCapabilityDeclarations(options.capabilities)}\n\n${runContextFrameDeclarations(options.stateType, options.program)}`;

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

@@ -6,16 +6,17 @@ import { scriptStdDeclarations } from "../script/std.ts";
 import { compileVirtualTypeScriptAsync } from "./async-compiler.ts";
 import type { VirtualTypeScriptDiagnostic } from "./compiler.ts";
 import type { NativeTypeScriptExecutor, NativeTypeScriptProgram, NativeTypeScriptRequest } from "./native-executor.ts";
-import { createRunContextDeclarations, runCapabilityContract, type RunCapabilityDescriptor } from "./run-context.ts";
+import { createRunContextDeclarations, runCapabilityContract, runContextFrameDeclarations, type RunCapabilityDescriptor } from "./run-context.ts";
 
 const snippetFile = "snippet.ts";
+const snippetStateType = "Record<string, unknown>";
+const snippetProgram = `${scriptStdDeclarations}\ninterface RAgentsRunContext<State, Capabilities> { readonly std: RAgentsStd; }\ndeclare const context: RunContext;`;
 
 export const typeScriptSnippetDeclarations = (capabilities: readonly RunCapabilityDescriptor[]): string =>
-    createRunContextDeclarations({
-        capabilities,
-        stateType: "Record<string, unknown>",
-        program: `${scriptStdDeclarations}\ninterface RAgentsRunContext<State, Capabilities> { readonly std: RAgentsStd; }\ndeclare const context: RunContext;`,
-    });
+    createRunContextDeclarations({ capabilities, stateType: snippetStateType, program: snippetProgram });
+
+/** What a snippet's context offers besides its functions (run, actor, state, log, std with mediators); typescript_api gives it once on request. */
+export const typeScriptSnippetContextDeclarations = runContextFrameDeclarations(snippetStateType, snippetProgram);
 
 export interface TypeScriptSnippetSource {
     readonly code: string;

package/packages/workspace-executor/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@aicontainer/workspace-executor",
+  "name": "@ragents/workspace-executor",
   "version": "0.1.0",
   "private": true,
   "type": "module",
@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@aicontainer/agent": "workspace:*",
+    "@ragents/agent": "workspace:*",
     "typescript": "^5.9.0",
     "typescript-language-server": "6.0.0",
     "vscode-jsonrpc": "^9.0.2"

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

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { getShellConfig } from "@ragents/agent";
+
+/** Ein Befehl des Werkzeugs bash, so wie er startet: Programm, Argumente und Umgebung. */
+export interface BashLaunch {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly env: NodeJS.ProcessEnv;
+}
+
+/** 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. "
+  + "Die VS-Code-Erweiterung bringt sie in ihrer Windows-Fassung (win32-x64, win32-arm64) unter dist/bash/<plattform>/usr/bin/bash.exe mit "
+  + "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 };
+};
+
+/** Wie ein Befehl in der Bash dieses Executors startet; die Plattform ist für Prüfungen wählbar. */
+export const bashLaunch = (
+  bash: string | undefined,
+  command: string,
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+): BashLaunch => {
+  if (platform === "win32" && bash === undefined) throw missingWindowsBash();
+  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.`);
+  }
+  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`);
+  return {
+    command: shell.shell,
+    args: [...shell.args, command],
+    env: platform === "win32" ? windowsBashEnvironment(env, path.win32.dirname(shell.shell)) : env,
+  };
+};