@schlenkr/ragents 0.1.5 → 0.1.7

package/packages/ragents/src/agents/tools.ts

@@ -2,18 +2,18 @@ import { Type, type Static, type TSchema } from "typebox";
 
 import { thinkingLevels } from "../domain/driver.ts";
 import type { JsonValue } from "../domain/json.ts";
-import type {
-    Actor,
-    CapabilityName,
-    EventSubscription,
-    RunView,
+import {
+    actorDescriptionMaxLength,
+    type Actor,
+    type CapabilityName,
+    type EventSubscription,
+    type RunView,
 } from "../domain/model.ts";
 import { observableEventTypes } from "../domain/vocabulary.ts";
 import type { CommandContext } from "../runtime/command.ts";
-import { inheritedGrants } from "../runtime/guards.ts";
+import { addressedActorOf, inheritedGrants } from "../runtime/guards.ts";
 import type { Orchestration } from "../runtime/orchestration.ts";
-import { descendantsOf, lineageSteps, stopLineage } from "../runtime/stop.ts";
-import { actorInputSchema, enqueueActorInput, eventResultSchema } from "./actor-input.ts";
+import { actorInputSchema, enqueueActorInput, eventResultSchemaOf } from "./actor-input.ts";
 import { resolveExecution, type ModelCatalog } from "./catalog.ts";
 import {
     capabilitySchema,
@@ -42,6 +42,8 @@ export type ToolScope = {
     functionGuidance: (names: readonly string[]) => Promise<string>;
     availableFunctions: () => readonly RunFunction[];
     resolveToolsFor: (actor: Actor, view?: RunView, onUnavailable?: (tool: RunFunction) => void) => Promise<readonly RunFunction[]>;
+    /** Only for a direct call of the model: names the model context its result enters; it changes when that context is compacted or replaced. */
+    modelContext?: string;
 };
 
 export type ToolAvailability = (actor: Actor, view: RunView) => boolean;
@@ -126,23 +128,6 @@ const needs =
             requiredCapabilities: [capability],
         }, (actor) => holdsUsable(actor, capability));
 
-const actorOf = (view: RunView, reference: string) => {
-    const direct = view.actors.find((entry) => entry.id === reference);
-
-    if (direct)
-        return direct;
-
-    const wanted = reference.trim().replace(/^@/, "").toLowerCase();
-    const sharing = view.actors.filter((entry) => entry.handle === wanted);
-    const active = sharing.find((entry) => entry.kind === "human" || entry.lifecycle.kind !== "stopped");
-    const found = active ?? sharing.at(-1);
-
-    if (!found)
-        throw new Error(`Actor ${reference} does not exist in this run.`);
-
-    return found;
-};
-
 const actorKindSchema = Type.Union([
     Type.Literal("human"),
     Type.Literal("agent"),
@@ -158,7 +143,11 @@ const actorListResultSchema = Type.Array(Type.Object({
     kind: actorKindSchema,
     lifecycle: Type.String(),
     createdBy: Type.Union([Type.String(), Type.Null()]),
-    tools: Type.Union([Type.Array(Type.String()), Type.Null()]),
+    description: Type.Union([Type.String(), Type.Null()]),
+    toolCount: Type.Union([Type.Integer({ minimum: 0 }), Type.Null()], {
+        description: "Number of selected tools; 0 is a plain LLM, null an open, dynamically resolved toolset.",
+    }),
+    toolNames: Type.Optional(Type.Array(Type.String(), { description: "Only with toolNames: true, for a fixed selection." })),
 }, { additionalProperties: false }));
 
 const actorReferenceSchema = Type.Object({
@@ -284,7 +273,7 @@ const executionSchema = {
     isolateWorkspace: Type.Optional(Type.Boolean()),
 };
 
-const handleOf = (view: RunView, actorId: string) => {
+const handleLabelOf = (view: RunView, actorId: string) => {
     const found = view.actors.find((entry) => entry.id === actorId);
 
     return found ? `@${found.handle}` : actorId;
@@ -298,13 +287,22 @@ const subscriptionView = (view: RunView, subscription: EventSubscription) => {
         subscriptionId: id,
         sourceActorIds: subscription.sourceActorIds ? [...subscription.sourceActorIds] : null,
         sources: subscription.sourceActorIds
-            ? subscription.sourceActorIds.map((actorId) => handleOf(view, actorId))
+            ? subscription.sourceActorIds.map((actorId) => handleLabelOf(view, actorId))
             : null,
         sourceActorKinds: subscription.sourceActorKinds ? [...subscription.sourceActorKinds] : null,
         eventTypes: [...subscription.eventTypes],
     };
 };
 
+const subscriptionCreatedSchema = Type.Object({
+    subscriptionId: Type.String({ description: "ID der Subscription; event_unsubscribe nimmt sie als subscriptionId" }),
+    sources: Type.Union([Type.Array(Type.String()), Type.Null()], {
+        description: "Die aufgelösten Quell-Actors als @handle, soweit auflösbar, sonst als ID; null = alle.",
+    }),
+}, { additionalProperties: false });
+
+const acknowledgementSchema = Type.Null({ description: "Erledigt; ein Fehler wirft." });
+
 const subscriptionResult = (runtime: Orchestration, runId: string, commandId: string) => {
     const created = runtime.events(runId).findLast(
         (event) => event.commandId === commandId && event.type === "subscription.created",
@@ -318,35 +316,44 @@ const subscriptionResult = (runtime: Orchestration, runId: string, commandId: st
     if (!subscription)
         throw new Error(`Subscription ${created.payload.subscriptionId} does not exist after creation.`);
 
-    return subscriptionView(runtime.view(runId), subscription);
+    const { subscriptionId, sources } = subscriptionView(runtime.view(runId), subscription);
+
+    return { subscriptionId, sources };
 };
 
 export const agentTools: RunFunction[] = [
     tool({
         name: "actor_list",
         label: "List Actors",
-        description: "List existing actors with their identity, lifecycle and function selection.",
-        longDescription: "Check before spawning: reuse suitable participants, including actors created by a setup or another actor. Only kind agent is a conversational partner. A script executes its programmed input protocol; it does not interpret arbitrary natural-language requests. Inspect its documented functions or program before using it.",
-        schema: Type.Object({}, { additionalProperties: false }),
+        description: "List existing actors with their identity, lifecycle and the size of their function selection.",
+        longDescription: "Check before spawning: reuse suitable participants, including actors created by a setup or another actor. Only kind agent is a conversational partner. A script executes its programmed input protocol; it does not interpret arbitrary natural-language requests. Inspect its documented functions or program before using it. toolNames: true also lists the names of each fixed selection.",
+        schema: Type.Object({
+            toolNames: Type.Optional(Type.Boolean({ description: "Also list the tool names of each actor with a fixed selection." })),
+        }, { additionalProperties: false }),
         resultSchema: actorListResultSchema,
         available: needs("actor.input"),
-        run: ({ runtime, caller }) => runtime.view(caller.runId).actors.map((actor) => ({
-            id: actor.id,
-            handle: actor.handle,
-            displayName: actor.displayName,
-            kind: actor.kind,
-            lifecycle: actor.kind === "human" ? "human" : actor.lifecycle.kind,
-            createdBy: actor.kind === "human" ? null : actor.createdBy,
-            tools: actor.kind === "human" || actor.toolNames === null ? null : [...actor.toolNames],
-        })),
+        run: ({ runtime, caller }, _toolCallId, input) => runtime.view(caller.runId).actors.map((actor) => {
+            const selected = actor.kind === "human" ? null : actor.toolNames;
+            return {
+                id: actor.id,
+                handle: actor.handle,
+                displayName: actor.displayName,
+                kind: actor.kind,
+                lifecycle: actor.kind === "human" ? "human" : actor.lifecycle.kind,
+                createdBy: actor.kind === "human" ? null : actor.createdBy,
+                description: actor.kind === "human" ? null : actor.description,
+                toolCount: selected === null ? null : selected.length,
+                ...(input.toolNames && selected !== null ? { toolNames: [...selected] } : {}),
+            };
+        }),
     }),
     tool({
         name: "actor_input",
         label: "Enqueue Actor Input",
         description: "Enqueue plain text and optional artifacts for one actor. The actor receives no routing envelope.",
-        longDescription: "This only confirms enqueueing, not processing, an answer or completion. Agents interpret natural language. TypeScript actors only process their programmed input protocol: use their documented functions, or send an exact supported program input after inspecting the program. Never address an unknown script with a natural-language task or assume an idle or completed turn means the requested work happened.",
+        longDescription: "This only confirms enqueueing, not processing, an answer or completion. An agent in the middle of a turn receives the text in that turn before its next model request; otherwise it starts the agent's next turn. Agents interpret natural language. TypeScript actors only process their programmed input protocol: use their documented functions, or send an exact supported program input after inspecting the program. Never address an unknown script with a natural-language task or assume an idle or completed turn means the requested work happened.",
         schema: actorInputSchema,
-        resultSchema: eventResultSchema,
+        resultSchema: eventResultSchemaOf("actor.input.enqueued"),
         available: needs("actor.input"),
         run: ({ runtime, caller, context }, toolCallId, input) =>
             enqueueActorInput(runtime, context(toolCallId), caller.runId, input),
@@ -362,13 +369,13 @@ export const agentTools: RunFunction[] = [
             eventTypes: Type.Array(observableEventTypeSchema, { minItems: 1, uniqueItems: true }),
             includeSelf: Type.Optional(Type.Boolean()),
         }, { additionalProperties: false }),
-        resultSchema: subscriptionSchema,
+        resultSchema: subscriptionCreatedSchema,
         available: needs("event.subscribe"),
         run: ({ runtime, caller, context }, toolCallId, input) => {
             const command = context(toolCallId);
             const view = runtime.view(caller.runId);
             const sourceActorIds = input.sourceActorIds
-                ? [...new Set(input.sourceActorIds.map((reference) => actorOf(view, reference).id))]
+                ? [...new Set(input.sourceActorIds.map((reference) => addressedActorOf(view.actors, reference).id))]
                 : null;
             runtime.createSubscription(command, caller.runId, {
                 subscriberId: caller.actorId,
@@ -389,12 +396,12 @@ export const agentTools: RunFunction[] = [
             subscriptionId: Type.String({ minLength: 1, description: "subscriptionId aus event_subscribe oder event_subscription_list" }),
             reason: Type.String({ minLength: 1 }),
         }, { additionalProperties: false }),
-        resultSchema: eventResultSchema,
+        resultSchema: acknowledgementSchema,
         available: needs("event.subscribe"),
-        run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
+        run: ({ runtime, caller, context }, toolCallId, input) => {
             runtime.removeSubscription(context(toolCallId), caller.runId, input.subscriptionId, input.reason);
 
-            return eventsFor(toolCallId);
+            return null;
         },
     }),
     tool({
@@ -433,7 +440,7 @@ export const agentTools: RunFunction[] = [
             const view = runtime.view(caller.runId);
             const eventIds = input.eventIds ? new Set(input.eventIds) : null;
             const actorIds = input.actorIds
-                ? new Set(input.actorIds.map((reference) => actorOf(view, reference).id))
+                ? new Set(input.actorIds.map((reference) => addressedActorOf(view.actors, reference).id))
                 : null;
             const eventTypes = input.eventTypes ? new Set(input.eventTypes) : null;
 
@@ -508,7 +515,7 @@ export const agentTools: RunFunction[] = [
                 required: Type.Boolean(),
             }, { additionalProperties: false })),
         }, { additionalProperties: false }),
-        resultSchema: eventResultSchema,
+        resultSchema: eventResultSchemaOf("action.proposed"),
         available: needs("action.propose"),
         run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
             runtime.proposeAction(context(toolCallId), caller.runId, {
@@ -537,12 +544,13 @@ export const agentTools: RunFunction[] = [
             + "It inherits delegable capabilities, but tools is required and never inherited: select exact names, [] for text-only work, or explicit null for an open, dynamically resolved toolset. "
             + "An empty tools array creates a plain LLM with no runtime, workspace or host tools; "
             + "drivers without plain-LLM isolation are rejected. "
-            + "forkOf copies the model context of an existing LLM agent of this run into the new agent at its first turn: the copy ends before any unfinished tool call and carries no reasoning; the new agent still gets its own prompt, tools and model.",
+            + "forkOf gives the new agent an unchanged copy of the model context of an existing LLM agent of this run, up to the end of that agent's last finished turn; nothing of its running turn is copied, and a source without a finished turn is rejected. The new agent still gets its own prompt, tools and model, and its first input follows the copy.",
         schema: Type.Object({
             handle: Type.String({ minLength: 1 }),
             displayName: Type.Optional(Type.String({ minLength: 1, description: "Anzeigename; ohne Angabe der Handle" })),
+            description: Type.Optional(Type.String({ minLength: 1, maxLength: actorDescriptionMaxLength, description: "Sehr kurze Beschreibung der Aufgabe für die Übersicht der Beteiligten, wenige Wörter wie \"prüft die Regel zu Kommentaren\"" })),
             prompt: Type.String(),
-            forkOf: Type.Optional(Type.String({ minLength: 1, description: "Handle oder ID eines LLM-Agenten dieses Runs, dessen bisheriger Modellkontext in den neuen Agenten kopiert wird" })),
+            forkOf: Type.Optional(Type.String({ minLength: 1, description: "Handle or ID of an LLM agent of this run whose model context up to the end of its last finished turn is copied into the new agent" })),
             tools: Type.Union([Type.Array(Type.String({ minLength: 1 }), { uniqueItems: true }), Type.Null()], { description: "Required explicit selection: [] for plain text-only work including app-mediated conversations; an array for exact existing tool names; null only when the task needs an open, dynamically resolved toolset. Never inherits the caller's tools. Names of future, not yet activated actor functions are invalid; choose null when those must become available later." }),
             withoutCapabilities: Type.Optional(Type.Array(capabilitySchema, { uniqueItems: true })),
             ...executionSchema,
@@ -552,7 +560,7 @@ export const agentTools: RunFunction[] = [
         run: async ({ runtime, caller, catalog, context, eventsFor, resolveToolsFor }, toolCallId, input) => {
             const executionId = `agent_${toolCallId}`;
             const execution = resolveExecution(catalog, input, executionId, await catalog.models());
-            const actor = actorOf(runtime.view(caller.runId), caller.actorId);
+            const actor = addressedActorOf(runtime.view(caller.runId).actors, caller.actorId);
 
             if (actor.kind === "human")
                 throw new Error(`Actor ${caller.actorId} cannot call agent_spawn from a turn.`);
@@ -574,6 +582,7 @@ export const agentTools: RunFunction[] = [
             runtime.spawnAgent(context(toolCallId), caller.runId, {
                 handle: input.handle,
                 displayName: input.displayName ?? input.handle,
+                ...(input.description === undefined ? {} : { description: input.description }),
                 prompt: input.prompt,
                 execution,
                 grants: inheritedGrants(actor, input.withoutCapabilities),
@@ -594,7 +603,7 @@ export const agentTools: RunFunction[] = [
         label: "Configure Run",
         description:
             "Set the run title and/or choose the primary actor the chat talks to. Give title, primaryActor or both; "
-            + "the primary actor must be an active agent or script actor of this run.",
+            + "the primary actor must be an active agent or TypeScript actor of this run.",
         schema: Type.Object({
             title: Type.Optional(Type.String({ minLength: 1, maxLength: 200, description: "Neuer Titel des Runs" })),
             primaryActor: Type.Optional(Type.String({
@@ -602,9 +611,9 @@ export const agentTools: RunFunction[] = [
                 description: "Handle oder ID des Actors, mit dem der Chat des Benutzers spricht",
             })),
         }, { additionalProperties: false }),
-        resultSchema: eventResultSchema,
+        resultSchema: acknowledgementSchema,
         available: needs("run.configure"),
-        run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
+        run: ({ runtime, caller, context }, toolCallId, input) => {
             if (input.title === undefined && input.primaryActor === undefined)
                 throw new Error("run_configure braucht title oder primaryActor; gültig sind { title }, { primaryActor } und beides zusammen.");
 
@@ -612,7 +621,7 @@ export const agentTools: RunFunction[] = [
                 runtime.retitleRun(context(toolCallId, "title"), caller.runId, input.title);
 
             if (input.primaryActor !== undefined) {
-                const target = actorOf(runtime.view(caller.runId), input.primaryActor);
+                const target = addressedActorOf(runtime.view(caller.runId).actors, input.primaryActor);
 
                 if (target.kind === "human")
                     throw new Error(`${input.primaryActor} is not an executable actor.`);
@@ -620,7 +629,7 @@ export const agentTools: RunFunction[] = [
                 runtime.selectPrimaryActor(context(toolCallId, "primary"), caller.runId, target.id);
             }
 
-            return ["title", "primary"].flatMap((step) => eventsFor(toolCallId, step));
+            return null;
         },
     }),
     tool({
@@ -631,11 +640,10 @@ export const agentTools: RunFunction[] = [
             actorId: Type.String({ minLength: 1, description: "Handle oder ID" }),
             reason: Type.String({ minLength: 1 }),
         }, { additionalProperties: false }),
-        resultSchema: eventResultSchema,
+        resultSchema: eventResultSchemaOf("actor.restarted", "run.primary-actor-selected"),
         available: needs("execution.stopOwned"),
         run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
-            const view = runtime.view(caller.runId);
-            const target = actorOf(view, input.actorId);
+            const target = addressedActorOf(runtime.view(caller.runId).actors, input.actorId);
 
             if (target.kind === "human")
                 throw new Error(`${input.actorId} is not an executable actor.`);
@@ -653,28 +661,19 @@ export const agentTools: RunFunction[] = [
             actorId: Type.String({ minLength: 1, description: "Handle oder ID" }),
             reason: Type.String({ minLength: 1 }),
         }, { additionalProperties: false }),
-        resultSchema: eventResultSchema,
+        resultSchema: eventResultSchemaOf("turn.interrupted", "actor.stopped", "subscription.removed"),
         available: needs("execution.stopOwned"),
         run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
-            const view = runtime.view(caller.runId);
-            const target = actorOf(view, input.actorId);
+            const target = addressedActorOf(runtime.view(caller.runId).actors, input.actorId);
 
             if (target.kind === "human")
                 throw new Error(`${input.actorId} is not an executable actor.`);
             if (target.id === caller.actorId)
                 throw new Error("An actor cannot stop itself; whoever created it decides that.");
 
-            const after = runtime.stopActor(context(toolCallId, "stop"), caller.runId, target.id, input.reason);
-            const lineage = descendantsOf(after, target.id);
-            const failures = stopLineage(runtime, caller.runId, lineage, input.reason, (step) => ({
-                ...context(toolCallId, step),
-                actorId: after.ownerId,
-            }));
-
-            if (failures.length > 0)
-                throw new AggregateError(failures, `${target.handle} konnte nicht vollständig gestoppt werden.`);
+            runtime.stopActor(context(toolCallId), caller.runId, target.id, input.reason);
 
-            return ["stop", ...lineageSteps(lineage)].flatMap((step) => eventsFor(toolCallId, step));
+            return eventsFor(toolCallId);
         },
     }),
     tool({
@@ -687,7 +686,7 @@ export const agentTools: RunFunction[] = [
             content: Type.String(),
             previousVersionId: Type.Optional(Type.String({ minLength: 1 })),
         }, { additionalProperties: false }),
-        resultSchema: eventResultSchema,
+        resultSchema: eventResultSchemaOf("artifact.published"),
         available: needs("artifact.publish"),
         run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
             runtime.publishArtifact(context(toolCallId), caller.runId, {

package/packages/ragents/src/agents/toolset.ts

@@ -164,18 +164,46 @@ export class TurnToolset {
         this.tools.splice(0, this.tools.length, ...this.functions.filter((tool) => tool.nativeTool === true));
     }
 
-    async invoke(toolCallId: string, name: string, input: JsonValue): Promise<ToolInvocation> {
-        await this.refresh();
-        const tool = this.tools.find((entry) => entry.name === name);
+    /** A model's tool call always lands in the journal: a failure before the start is recorded as start and failure. */
+    async invoke(toolCallId: string, name: string, input: JsonValue, modelContext?: string): Promise<ToolInvocation> {
+        const prepared = await this.#beforeStart(toolCallId, name, input, async () => {
+            await this.refresh();
+            const tool = this.tools.find((entry) => entry.name === name);
 
-        if (!tool)
-            throw new Error(`Tool ${name} is not available to actor ${this.#turn.actorId}.`);
+            if (!tool)
+                throw new Error(`Tool ${name} is not available to actor ${this.#turn.actorId}.`);
 
-        assertJsonValue(input, `Tool ${name} input`);
-        const tolerated = withoutUnknownFields(tool.schema, input);
-        const output = await this.#execute(toolCallId, tool, tolerated.input, tolerated.ignoredFields);
+            assertJsonValue(input, `Tool ${name} input`);
+            const tolerated = withoutUnknownFields(tool.schema, input);
+
+            if (!this.#replayOf(toolCallId) && !Value.Check(tool.schema, tolerated.input))
+                throw new Error(inputComplaint(tool, tolerated.input, tolerated.ignoredFields));
+
+            return { tool, tolerated };
+        });
+        const output = await this.#execute(toolCallId, prepared.tool, prepared.tolerated.input, prepared.tolerated.ignoredFields, modelContext);
+
+        return { output, ignoredFields: prepared.tolerated.ignoredFields };
+    }
+
+    async #beforeStart<T>(toolCallId: string, name: string, input: JsonValue, prepare: () => Promise<T>): Promise<T> {
+        try {
+            return await prepare();
+        } catch (error) {
+            if (this.#replayOf(toolCallId))
+                throw error;
+
+            try {
+                this.#assertActive();
+                assertJsonValue(input, `Tool ${name} input`);
+            } catch {
+                throw error;
+            }
 
-        return { output, ignoredFields: tolerated.ignoredFields };
+            this.#runtime.startToolCall(this.#context(toolCallId, "started"), this.#turn.runId, this.#turn.actorId, { turnId: this.#turn.turnId, toolCallId, name, input });
+            this.#runtime.failToolCall(this.#context(toolCallId, "failed"), this.#turn.runId, this.#turn.actorId, { turnId: this.#turn.turnId, toolCallId, name, error: errorText(error) });
+            throw error;
+        }
     }
 
     async invokeFunction(toolCallId: string, name: string, input: JsonValue): Promise<JsonValue> {
@@ -186,7 +214,7 @@ export class TurnToolset {
         return this.#execute(toolCallId, fn, input, []);
     }
 
-    async #execute(toolCallId: string, tool: RunFunction, input: JsonValue, ignoredFields: readonly string[]): Promise<JsonValue> {
+    async #execute(toolCallId: string, tool: RunFunction, input: JsonValue, ignoredFields: readonly string[], modelContext?: string): Promise<JsonValue> {
         const name = tool.name;
 
         assertJsonValue(input, `Tool ${name} input`);
@@ -225,10 +253,10 @@ export class TurnToolset {
         );
 
         try {
-            const output = await tool.run(this.#scope, toolCallId, input as never);
+            const output = await tool.run(modelContext === undefined ? this.#scope : { ...this.#scope, modelContext }, toolCallId, input as never);
             this.#assertActive();
             if (!Value.Check(tool.resultSchema, output))
-                throw new Error(`Tool ${name} returned output that does not match its result schema.`);
+                throw new Error(`Tool ${name} returned output that does not match its result schema: ${schemaComplaints(tool.resultSchema, output, "output")}.`);
             assertJsonValue(output, `Tool ${name} output`);
             const recordedOutput = tool.recordOutput ? tool.recordOutput(output) : output;
             assertJsonValue(recordedOutput, `Tool ${name} recorded output`);
@@ -282,18 +310,17 @@ export class TurnToolset {
     }
 
     #replayOf(toolCallId: string) {
-        const events = this.#runtime.events(this.#turn.runId).filter((event): event is ToolCallEvent => {
-            if (
-                event.type !== "tool.call.started" &&
-                event.type !== "tool.call.completed" &&
-                event.type !== "tool.call.failed"
-            )
-                return false;
-
-            return event.actorId === this.#turn.actorId &&
-                event.payload.turnId === this.#turn.turnId &&
-                event.payload.toolCallId === toolCallId;
-        });
+        const events: ToolCallEvent[] = [];
+
+        for (const event of this.#runtime.recentEvents(this.#turn.runId)) {
+            if (event.type === "turn.started" && event.payload.turnId === this.#turn.turnId)
+                break;
+
+            if ((event.type === "tool.call.started" || event.type === "tool.call.completed" || event.type === "tool.call.failed")
+                && event.actorId === this.#turn.actorId && event.payload.turnId === this.#turn.turnId && event.payload.toolCallId === toolCallId)
+                events.unshift(event);
+        }
+
         const started = events.find((event) => event.type === "tool.call.started");
         const terminal = events.findLast(
             (event) => event.type === "tool.call.completed" || event.type === "tool.call.failed",

package/packages/ragents/src/agents/turn.ts

@@ -1,6 +1,6 @@
-import type { AgentActor, ExecutableActor, RunView } from "../domain/model.ts";
+import type { ExecutableActor, RunView } from "../domain/model.ts";
 import type { Orchestration } from "../runtime/orchestration.ts";
-import { deliveredInputOf, renderedPromptFor, type DeliveredInput } from "./delivery.ts";
+import { deliveredInputOf, type DeliveredInput } from "./delivery.ts";
 
 export type ClaimedTurn = {
     runId: string;
@@ -19,18 +19,6 @@ export const workingActorFrom = (view: RunView, actorId: string): ExecutableActo
     return found;
 };
 
-export const agentFrom = (view: RunView, actorId: string): AgentActor => {
-    const found = view.actors.find((entry) => entry.id === actorId);
-
-    if (found?.kind !== "agent")
-        throw new Error(`Agent ${actorId} does not exist.`);
-
-    return found;
-};
-
-export const promptFor = (view: RunView, actorId: string, input: DeliveredInput) =>
-    renderedPromptFor(view, actorId, input);
-
 export function claimTurn(
     runtime: Orchestration,
     runId: string,

package/packages/ragents/src/agents/workspaces.ts

@@ -1,5 +1,9 @@
 export interface Workspaces {
     ensure(runId: string, workspacePath: string | null): string;
+    /** How the run's workspace is described to a model; undefined when nothing describes it. */
+    description(runId: string): string | undefined;
+    /** Stores an attached file under attachments/ of the workspace, on the machine where the workspace lies; returns its name there. */
+    storeAttachment(runId: string, name: string, content: Uint8Array): Promise<string>;
 }
 
 export class FixedWorkspaces implements Workspaces {
@@ -12,4 +16,12 @@ export class FixedWorkspaces implements Workspaces {
     ensure() {
         return this.#path;
     }
+
+    description() {
+        return undefined;
+    }
+
+    storeAttachment(): Promise<string> {
+        return Promise.reject(new Error("Ein fester Arbeitsbereich ohne Executor nimmt keine Dateianhänge an."));
+    }
 }

package/packages/ragents/src/domain/actor-reference.ts

@@ -0,0 +1,22 @@
+/** What resolving a reference needs of an actor; the engine's actors and the web's run view both have it. */
+export type ReferencedActor = {
+    readonly id: string;
+    readonly handle: string;
+};
+
+/** The form in which handles are stored: without a leading @, NFC-composed and lower case. */
+export const handleKey = (reference: string) => reference.trim().replace(/^@/, "").normalize("NFC").toLowerCase();
+
+/** The actor with this handle; the journal gives a handle to exactly one actor of a run, stopped or not. */
+export const actorByHandle = <Found extends ReferencedActor>(actors: Iterable<Found>, handle: string): Found | undefined => {
+    const wanted = handleKey(handle);
+
+    return [...actors].find((actor) => actor.handle === wanted);
+};
+
+/** The actor with this ID, otherwise the one with this handle (with or without @). */
+export const actorByReference = <Found extends ReferencedActor>(actors: Iterable<Found>, reference: string): Found | undefined => {
+    const listed = [...actors];
+
+    return listed.find((actor) => actor.id === reference) ?? actorByHandle(listed, reference);
+};

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

@@ -40,17 +40,8 @@ export type AgentExecution = {
     turnTimeoutMs: number | null;
 };
 
-export const manualExecution = (): AgentExecution => ({
-    driver: { kind: "manual", config: {} },
-    workspacePath: null,
-    turnTimeoutMs: null,
-});
-
 export const scriptExecution = (turnTimeoutMs: number | null = null): AgentExecution => ({
     driver: { kind: "script", config: {} },
     workspacePath: null,
     turnTimeoutMs,
 });
-
-export const modelSelectionOf = (execution: AgentExecution): ModelSelection | null =>
-    execution.driver.kind === "manual" || execution.driver.kind === "script" ? null : execution.driver.config;