@schlenkr/ragents 0.1.4 → 0.1.6

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

@@ -1,10 +1,10 @@
 import type { JournalEvent } from "../../domain/events.ts";
-import { isPendingActorInput, type EventSubscription, type ObservableEventType, type RunState } from "../../domain/model.ts";
+import { eventSubjectOf, isPendingActorInput, type EventSubscription, type ObservableEventType, type RunState } from "../../domain/model.ts";
 import { isActiveActor } from "../../domain/projection.ts";
 import { isObservableEventType, observableEventTypes } from "../../domain/vocabulary.ts";
 import { event, type Decision } from "../command.ts";
 import { DomainError } from "../domain-error.ts";
-import { actorById, actorOf, assertCapability, clean, executableActorOf } from "../guards.ts";
+import { actorById, commandActorOf, assertCapability, clean, executableActorOf } from "../guards.ts";
 
 export const createSubscription =
     (input: {
@@ -15,7 +15,7 @@ export const createSubscription =
         includeSelf?: boolean;
     }): Decision =>
     (state, context, services) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
         const subscriber = executableActorOf(state, input.subscriberId);
 
         if (caller.id !== state.ownerId) {
@@ -66,7 +66,7 @@ export const createSubscription =
 export const removeSubscription =
     (subscriptionId: string, reason: string): Decision =>
     (state, context) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
         const subscription = state.subscriptions.get(subscriptionId);
 
         if (!subscription)
@@ -118,14 +118,16 @@ export const matchesSubscription = (state: RunState, subscription: EventSubscrip
     if (!subscription.eventTypes.includes(source.type))
         return false;
 
-    if (!subscription.includeSelf && source.actorId === subscription.subscriberId)
+    const subjectId = eventSubjectOf(state, source);
+
+    if (!subscription.includeSelf && subjectId === subscription.subscriberId)
         return false;
 
-    if (subscription.sourceActorIds && !subscription.sourceActorIds.includes(source.actorId))
+    if (subscription.sourceActorIds && !subscription.sourceActorIds.includes(subjectId))
         return false;
 
     if (subscription.sourceActorKinds) {
-        const sourceActor = state.actors.get(source.actorId);
+        const sourceActor = state.actors.get(subjectId);
 
         if (!sourceActor || !subscription.sourceActorKinds.includes(sourceActor.kind))
             return false;

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

@@ -1,8 +1,8 @@
 import type { JsonValue } from "../../domain/json.ts";
-import type { TurnUsage } from "../../domain/model.ts";
+import { isPendingActorInput, type TurnUsage } from "../../domain/model.ts";
 import { event, type Decision } from "../command.ts";
 import { DomainError } from "../domain-error.ts";
-import { actorById, actorOf, assertSelf, clean, executableActorOf } from "../guards.ts";
+import { actorById, commandActorOf, assertSelf, clean, executableActorOf } from "../guards.ts";
 
 const runningTurn = (state: Parameters<Decision>[0], context: Parameters<Decision>[1], actorId: string, turnId: string) => {
     assertSelf(context, actorId, "record activity");
@@ -11,7 +11,7 @@ const runningTurn = (state: Parameters<Decision>[0], context: Parameters<Decisio
     if (target.lifecycle.kind !== "running" || target.lifecycle.turnId !== turnId)
         throw new DomainError("turn-mismatch", `Turn ${turnId} is not running for actor ${actorId}.`, 409);
 
-    actorOf(state, context);
+    commandActorOf(state, context);
 
     return target;
 };
@@ -46,8 +46,38 @@ export const startTurn =
         })];
     };
 
+/** Pending inputs join a running agent turn in their journal order; nothing may be skipped. */
+export const steerInputs =
+    (actorId: string, input: { turnId: string; inputIds: readonly string[] }): Decision =>
+    (state, context) => {
+        const target = runningTurn(state, context, actorId, input.turnId);
+
+        if (target.execution.driver.kind !== "agent")
+            throw new DomainError("steering-unsupported", `Actor ${actorId} runs without a model and takes no steering.`, 409);
+
+        if (input.inputIds.length === 0)
+            throw new DomainError("steering-empty", `Steering into turn ${input.turnId} names no input.`, 400);
+
+        const pending = [...state.inputs.values()]
+            .filter((entry) => entry.actorId === actorId && isPendingActorInput(entry))
+            .sort((left, right) => left.sequence - right.sequence)
+            .map((entry) => entry.id);
+
+        if (input.inputIds.some((inputId, index) => pending[index] !== inputId))
+            throw new DomainError(
+                "steering-order",
+                `Steering into turn ${input.turnId} must take the oldest pending inputs in order; pending are ${pending.join(", ") || "none"}.`,
+                409,
+            );
+
+        return input.inputIds.map((inputId) => event(context, {
+            type: "turn.input-steered",
+            payload: { turnId: input.turnId, inputId },
+        }));
+    };
+
 const appendText = (
-    type: "model.output.completed" | "model.reasoning.completed" | "runtime.output.recorded",
+    type: "model.output.completed" | "model.output.interrupted" | "model.reasoning.completed" | "runtime.output.recorded",
     actorId: string,
     input: { turnId: string; text: string },
 ): Decision => (state, context) => {
@@ -59,6 +89,9 @@ const appendText = (
 export const appendModelOutput = (actorId: string, input: { turnId: string; text: string }): Decision =>
     appendText("model.output.completed", actorId, input);
 
+export const appendInterruptedModelOutput = (actorId: string, input: { turnId: string; text: string }): Decision =>
+    appendText("model.output.interrupted", actorId, input);
+
 export const appendModelReasoning = (actorId: string, input: { turnId: string; text: string }): Decision =>
     appendText("model.reasoning.completed", actorId, input);
 

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

@@ -2,15 +2,15 @@ import { resolve } from "node:path";
 
 import type {
     Actor,
-    AgentActor,
     Artifact,
     CapabilityGrant,
     CapabilityName,
     CapabilityScope,
     ExecutableActor,
     RunState,
+    Turn,
 } from "../domain/model.ts";
-import { isActiveActor } from "../domain/projection.ts";
+import { actorByReference, handleKey } from "../domain/actor-reference.ts";
 import { DomainError } from "./domain-error.ts";
 
 export const clean = (value: string, name: string) => {
@@ -32,7 +32,7 @@ export const optionalClean = (value: string | null | undefined, name: string) =>
 };
 
 export const handleOf = (value: string) => {
-    const result = value.trim().replace(/^@/, "").normalize("NFC").toLowerCase();
+    const result = handleKey(value);
 
     if (!/^[\p{L}\p{N}][\p{L}\p{N}._-]*$/u.test(result))
         throw new DomainError("invalid-handle", "A handle may contain letters, digits, dot, dash, and underscore.", 400);
@@ -72,11 +72,11 @@ export const executableActorOf = (state: RunState, actorId: string): ExecutableA
     return found;
 };
 
-export const agentActorOf = (state: RunState, agentId: string): AgentActor => {
-    const found = actorById(state, agentId);
+export const turnOf = (state: RunState, turnId: string): Turn => {
+    const found = state.turns.get(turnId);
 
-    if (found.kind !== "agent")
-        throw new DomainError("agent-not-found", `Actor ${agentId} is not an agent.`, 404);
+    if (!found)
+        throw new DomainError("turn-not-found", `Turn ${turnId} does not exist.`, 404);
 
     return found;
 };
@@ -90,20 +90,13 @@ export const artifactOf = (state: RunState, artifactId: string): Artifact => {
     return found;
 };
 
-export const addressedActorOf = (state: RunState, reference: string): Actor => {
-    const direct = state.actors.get(reference);
-
-    if (direct)
-        return direct;
-
-    const wanted = reference.trim().replace(/^@/, "").normalize("NFC").toLowerCase();
-    const sharing = [...state.actors.values()].filter((entry) => entry.handle === wanted);
-    const byHandle = sharing.find(isActiveActor) ?? sharing.at(-1);
+export const addressedActorOf = (actors: Iterable<Actor>, reference: string): Actor => {
+    const found = actorByReference(actors, reference);
 
-    if (!byHandle)
+    if (!found)
         throw new DomainError("actor-not-found", `Actor ${reference} does not exist.`, 404);
 
-    return byHandle;
+    return found;
 };
 
 export const assertActorCanCommand = (actor: Actor, turnId: string | undefined) => {
@@ -121,15 +114,13 @@ export const assertActorCanCommand = (actor: Actor, turnId: string | undefined)
         throw new DomainError("turn-mismatch", `Turn ${turnId ?? "<missing>"} is not running for actor ${actor.id}.`, 409);
 };
 
-export const actorOf = (state: RunState, context: { actorId: string; turnId?: string }): Actor => {
+export const commandActorOf = (state: RunState, context: { actorId: string; turnId?: string }): Actor => {
     const actor = actorById(state, context.actorId);
     assertActorCanCommand(actor, context.turnId);
 
     return actor;
 };
 
-export const isActiveCommandActor = (state: RunState, actor: Actor) => isActiveActor(actorById(state, actor.id));
-
 export const scopeCovers = (parent: CapabilityScope, child: CapabilityScope) => {
     if (parent.kind === "run")
         return true;

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

@@ -8,7 +8,9 @@ import { isRunId } from "../domain/portable-id.ts";
 import { syncDirectory } from "./durable-fs.ts";
 import type { CommandRecord, JournalCommand } from "./journal.ts";
 
-export const journalStorageVersion = 4;
+/** Rises whenever an older stand would reject newly written lines; the encoding is unchanged since 4, so 4 stays readable. */
+export const journalStorageVersion = 6;
+const readableJournalStorageVersions: readonly unknown[] = [4, 5, journalStorageVersion];
 export const journalPayloadThresholdBytes = 4096;
 
 type PayloadReference = { sha256: string; bytes: number };
@@ -158,7 +160,7 @@ export const parseJournalRecord = (line: string, runDirectory: string, location:
     assertJsonValue(parsed, location);
     const record = objectOf(parsed, location);
 
-    if (record.formatVersion !== journalStorageVersion)
+    if (!readableJournalStorageVersions.includes(record.formatVersion))
         throw new Error(`${location} has unsupported journal format version ${String(record.formatVersion)}.`);
 
     exactKeys(record, location, ["formatVersion", "runId", "command", "occurredAt", "events"]);

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

@@ -570,7 +570,7 @@ export class Journal {
             const log = this.#runs.get(runId);
             const semantics = log ? {
                 events: new Map(log.semantics.events),
-                toolCalls: clone(log.semantics.toolCalls),
+                sourcedToolCalls: new Set(log.semantics.sourcedToolCalls),
             } : eventSemanticContext();
             let state: RunDraft | null = log?.state ? forkProjection(log.state) : null;
 

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

@@ -1,8 +1,7 @@
 import type { JournalEvent, UncommittedEvent } from "../domain/events.ts";
-import { assertJsonValue, type JsonValue } from "../domain/json.ts";
+import { assertJsonValue, type JsonObject, type JsonValue } from "../domain/json.ts";
 import type {
     ActionInput,
-    ActionKind,
     ActionStatus,
     ActorKind,
     AgentExecution,
@@ -25,7 +24,7 @@ import * as turns from "./decisions/turns.ts";
 import { DomainError } from "./domain-error.ts";
 import {
     actorById,
-    actorOf,
+    commandActorOf,
     addressedActorOf,
     assertArtifactRead,
     assertCapability,
@@ -33,6 +32,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";
@@ -126,7 +126,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 +135,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 +180,7 @@ export class Orchestration {
                             scope: { kind: "run" },
                             delegable: true,
                         })),
+                        ...input.ownerUserId === undefined ? {} : { userId: clean(input.ownerUserId, "ownerUserId") },
                     },
                 },
             }),
@@ -345,6 +348,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 +363,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,10 +381,18 @@ export class Orchestration {
         return this.#run(context, runId, "turn.start", { actorId, inputId }, turns.startTurn(actorId, inputId));
     }
 
+    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));
+    }
+
     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));
     }
 
+    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));
+    }
+
     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));
     }
@@ -471,7 +484,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 +493,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 +508,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 +521,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 +544,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 +554,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 +600,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;