@schlenkr/ragents 0.1.5 → 0.1.6

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

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 
 import type { JournalEvent } from "./events.ts";
+import type { JsonValue } from "./json.ts";
 import type {
     Actor,
     AgentExecution,
@@ -12,28 +13,21 @@ import type {
     RunState,
     Turn,
 } from "./model.ts";
-import { isPendingActorInput, actorStatePluginId } from "./model.ts";
+import { eventSubjectOf, isPendingActorInput, actorStatePluginId } from "./model.ts";
 import { isObservableEventType } from "./vocabulary.ts";
 
-type ToolCall = {
-    turnId: string;
-    toolCallId: string;
-    name: string;
-    status: "running" | "completed" | "failed" | "interrupted";
-    sourceRecorded: boolean;
-};
-
 export type EventSemanticContext = {
     events: Map<string, JournalEvent>;
-    toolCalls: Map<string, ToolCall>;
+    /** Tool calls with a recorded source, by turn and call; their state stands in the turn. */
+    sourcedToolCalls: Set<string>;
 };
 
 export const eventSemanticContext = (): EventSemanticContext => ({
     events: new Map(),
-    toolCalls: new Map(),
+    sourcedToolCalls: new Set(),
 });
 
-const actorOf = (state: RunState, actorId: string): Actor => {
+const existingActorOf = (state: RunState, actorId: string): Actor => {
     const actor = state.actors.get(actorId);
 
     if (!actor)
@@ -43,7 +37,7 @@ const actorOf = (state: RunState, actorId: string): Actor => {
 };
 
 const executableOf = (state: RunState, actorId: string): ExecutableActor => {
-    const actor = actorOf(state, actorId);
+    const actor = existingActorOf(state, actorId);
 
     if (actor.kind === "human")
         throw new Error(`Actor ${actorId} is not executable.`);
@@ -96,24 +90,20 @@ const assertUnique = (values: readonly string[], kind: string) => {
         throw new Error(`${kind} contains duplicate references.`);
 };
 
+const isBlankResult = (result: JsonValue | null) =>
+    result === null || (typeof result === "string" && result.trim() === "");
+
 const toolCallKey = (turnId: string, toolCallId: string) => `${turnId}\0${toolCallId}`;
 
-const toolCallOf = (
-    context: EventSemanticContext,
-    turnId: string,
-    toolCallId: string,
-) => {
-    const call = context.toolCalls.get(toolCallKey(turnId, toolCallId));
+const toolCallOf = (turn: Turn, toolCallId: string) => {
+    const call = turn.toolCalls.find((entry) => entry.id === toolCallId);
 
     if (!call)
-        throw new Error(`Tool call ${toolCallId} does not exist in turn ${turnId}.`);
+        throw new Error(`Tool call ${toolCallId} does not exist in turn ${turn.id}.`);
 
     return call;
 };
 
-const runningToolCallsOf = (context: EventSemanticContext, turnId: string) =>
-    [...context.toolCalls.values()].filter((call) => call.turnId === turnId && call.status === "running");
-
 const assertExistingEvents = (context: EventSemanticContext, eventIds: readonly string[]) => {
     assertUnique(eventIds, "sourceEventIds");
 
@@ -141,7 +131,7 @@ const assertArtifactRead = (state: RunState, actorId: string, artifactId: string
 };
 
 const commandActorOf = (state: RunState, actorId: string) => {
-    const actor = actorOf(state, actorId);
+    const actor = existingActorOf(state, actorId);
 
     if (actor.kind !== "human" && actor.lifecycle.kind !== "running")
         throw new Error(`Actor ${actor.id} cannot author a command while ${actor.lifecycle.kind}.`);
@@ -268,14 +258,16 @@ const assertSubscriptionSource = (
     if (!isObservableEventType(source.type) || !subscription.eventTypes.includes(source.type))
         throw new Error(`Source event ${sourceEventId} does not match subscription ${subscription.id}.`);
 
-    if (!subscription.includeSelf && source.actorId === subscription.subscriberId)
+    const subjectId = eventSubjectOf(state, source);
+
+    if (!subscription.includeSelf && subjectId === subscription.subscriberId)
         throw new Error(`Source event ${sourceEventId} is excluded by subscription ${subscription.id}.`);
 
-    if (subscription.sourceActorIds && !subscription.sourceActorIds.includes(source.actorId))
+    if (subscription.sourceActorIds && !subscription.sourceActorIds.includes(subjectId))
         throw new Error(`Source event ${sourceEventId} has the wrong actor for subscription ${subscription.id}.`);
 
     if (subscription.sourceActorKinds) {
-        const sourceActor = actorOf(state, source.actorId);
+        const sourceActor = existingActorOf(state, subjectId);
 
         if (!subscription.sourceActorKinds.includes(sourceActor.kind))
             throw new Error(`Source event ${sourceEventId} has the wrong actor kind for subscription ${subscription.id}.`);
@@ -311,7 +303,7 @@ export const assertEventSemantics = (
     if (!state)
         throw new Error(`Run ${event.runId} has no creation event.`);
 
-    actorOf(state, event.actorId);
+    existingActorOf(state, event.actorId);
 
     switch (event.type) {
         case "run.forked":
@@ -403,14 +395,36 @@ export const assertEventSemantics = (
             break;
         }
 
+        case "turn.input-steered": {
+            const turn = runningTurnOf(state, event.payload.turnId);
+            assertTurnAuthor(turn, event);
+            const input = state.inputs.get(event.payload.inputId);
+
+            if (!input)
+                throw new Error(`Input ${event.payload.inputId} does not exist.`);
+
+            if (input.actorId !== turn.actorId)
+                throw new Error(`Input ${input.id} is not addressed to actor ${turn.actorId}.`);
+
+            if (!isPendingActorInput(input))
+                throw new Error(`Input ${input.id} is no longer pending and cannot join turn ${turn.id}.`);
+
+            const earlier = [...state.inputs.values()].find((entry) =>
+                entry.actorId === input.actorId && isPendingActorInput(entry) && entry.sequence < input.sequence);
+
+            if (earlier)
+                throw new Error(`Input ${input.id} cannot join turn ${turn.id} before the earlier input ${earlier.id}.`);
+            break;
+        }
+
         case "turn.finished": {
             const turn = runningTurnOf(state, event.payload.turnId);
             assertTurnAuthor(turn, event);
-            const openCalls = runningToolCallsOf(context, turn.id);
+            const openCalls = turn.toolCalls.filter((call) => call.status === "running");
 
-            if (openCalls.length > 0)
+            if (event.payload.outcome === "completed" && openCalls.length > 0)
                 throw new Error(
-                    `Turn ${turn.id} still has running tool calls: ${openCalls.map((call) => call.toolCallId).join(", ")}.`,
+                    `Turn ${turn.id} still has running tool calls: ${openCalls.map((call) => call.id).join(", ")}.`,
                 );
             break;
         }
@@ -425,6 +439,7 @@ export const assertEventSemantics = (
         }
 
         case "model.output.completed":
+        case "model.output.interrupted":
         case "model.reasoning.completed":
         case "runtime.output.recorded": {
             const turn = runningTurnOf(state, event.payload.turnId);
@@ -435,9 +450,8 @@ export const assertEventSemantics = (
         case "tool.call.started": {
             const turn = runningTurnOf(state, event.payload.turnId);
             assertTurnAuthor(turn, event);
-            const key = toolCallKey(turn.id, event.payload.toolCallId);
 
-            if (context.toolCalls.has(key))
+            if (turn.toolCalls.some((call) => call.id === event.payload.toolCallId))
                 throw new Error(`Tool call ${event.payload.toolCallId} already exists in turn ${turn.id}.`);
             break;
         }
@@ -446,24 +460,24 @@ export const assertEventSemantics = (
         case "tool.call.failed": {
             const turn = runningTurnOf(state, event.payload.turnId);
             assertTurnAuthor(turn, event);
-            const call = toolCallOf(context, turn.id, event.payload.toolCallId);
+            const call = toolCallOf(turn, event.payload.toolCallId);
 
             if (call.status !== "running")
-                throw new Error(`Tool call ${call.toolCallId} in turn ${call.turnId} is already ${call.status}.`);
+                throw new Error(`Tool call ${call.id} in turn ${turn.id} is already ${call.status}.`);
 
             if (call.name !== event.payload.name)
-                throw new Error(`Tool call ${call.toolCallId} started as ${call.name}, not ${event.payload.name}.`);
+                throw new Error(`Tool call ${call.id} started as ${call.name}, not ${event.payload.name}.`);
             break;
         }
 
         case "tool.call.source": {
             const turn = runningTurnOf(state, event.payload.turnId);
             assertTurnAuthor(turn, event);
-            const call = toolCallOf(context, turn.id, event.payload.toolCallId);
+            const call = toolCallOf(turn, event.payload.toolCallId);
             if (call.status !== "running")
-                throw new Error(`Tool call ${call.toolCallId} in turn ${call.turnId} is already ${call.status}.`);
-            if (call.sourceRecorded)
-                throw new Error(`Tool call ${call.toolCallId} in turn ${call.turnId} already has a source snapshot.`);
+                throw new Error(`Tool call ${call.id} in turn ${turn.id} is already ${call.status}.`);
+            if (context.sourcedToolCalls.has(toolCallKey(turn.id, call.id)))
+                throw new Error(`Tool call ${call.id} in turn ${turn.id} already has a source snapshot.`);
             break;
         }
 
@@ -514,7 +528,7 @@ export const assertEventSemantics = (
             assertUnique(event.payload.eventTypes, "eventTypes");
 
             for (const actorId of event.payload.sourceActorIds ?? [])
-                actorOf(state, actorId);
+                existingActorOf(state, actorId);
             break;
         }
 
@@ -573,7 +587,7 @@ export const assertEventSemantics = (
             const author = commandActorOf(state, event.actorId);
 
             if (event.payload.scope.kind === "actor") {
-                actorOf(state, event.payload.scope.actorId);
+                existingActorOf(state, event.payload.scope.actorId);
 
                 if (author.id !== state.ownerId && author.id !== event.payload.scope.actorId)
                     throw new Error(`Actor ${author.id} cannot replace plugin state for ${event.payload.scope.actorId}.`);
@@ -595,7 +609,7 @@ export const assertEventSemantics = (
             const author = commandActorOf(state, event.actorId);
             assertNewId(state.actions, event.payload.actionId, "Action");
 
-            if (event.payload.kind === "action" && !hasRunCapability(author, "action.propose"))
+            if (event.payload.owner === null && !hasRunCapability(author, "action.propose"))
                 throw new Error(`Actor ${author.id} lacks action.propose.`);
             break;
         }
@@ -609,11 +623,11 @@ export const assertEventSemantics = (
             if (action.status !== "pending")
                 throw new Error(`Action ${action.id} is already ${action.status}.`);
 
-            if (actorOf(state, event.actorId).kind !== "human")
+            if (existingActorOf(state, event.actorId).kind !== "human")
                 throw new Error(`Action ${action.id} was not resolved by a human actor.`);
 
-            if (event.payload.decision === "approved" && action.input?.required && !event.payload.response?.trim())
-                throw new Error(`Action ${action.id} requires a response.`);
+            if (event.payload.decision === "approved" && action.input?.required && isBlankResult(event.payload.result))
+                throw new Error(`Action ${action.id} requires a result.`);
             break;
         }
 
@@ -637,32 +651,6 @@ export const assertEventSemantics = (
 export const recordEventSemantics = (event: JournalEvent, context: EventSemanticContext) => {
     context.events.set(event.eventId, event);
 
-    if (event.type === "tool.call.started") {
-        context.toolCalls.set(toolCallKey(event.payload.turnId, event.payload.toolCallId), {
-            turnId: event.payload.turnId,
-            toolCallId: event.payload.toolCallId,
-            name: event.payload.name,
-            status: "running",
-            sourceRecorded: false,
-        });
-    }
-
-    if (event.type === "tool.call.source") {
-        const call = toolCallOf(context, event.payload.turnId, event.payload.toolCallId);
-        call.sourceRecorded = true;
-    }
-
-    if (event.type === "tool.call.completed" || event.type === "tool.call.failed") {
-        const call = context.toolCalls.get(toolCallKey(event.payload.turnId, event.payload.toolCallId));
-
-        if (!call)
-            throw new Error(`Tool call ${event.payload.toolCallId} was not validated.`);
-
-        call.status = event.type === "tool.call.completed" ? "completed" : "failed";
-    }
-
-    if (event.type === "turn.interrupted") {
-        for (const call of runningToolCallsOf(context, event.payload.turnId))
-            call.status = "interrupted";
-    }
+    if (event.type === "tool.call.source")
+        context.sourcedToolCalls.add(toolCallKey(event.payload.turnId, event.payload.toolCallId));
 };

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

@@ -217,13 +217,12 @@ const pluginScopeOf = (value: unknown, path: string) => {
     fail(`${path}.kind`, "must be run or actor");
 };
 
-const questionOf = (value: unknown, path: string) => {
+const actionPayloadOf = (value: unknown, path: string) => {
     if (value === null)
         return;
 
-    const question = exactObject(value, path, ["options", "multi"]);
-    stringArrayOf(question.options, `${path}.options`);
-    booleanOf(question.multi, `${path}.multi`);
+    objectOf(value, path);
+    assertJsonValue(value, path);
 };
 
 const actionInputOf = (value: unknown, path: string) => {
@@ -262,8 +261,9 @@ const eventTypeArrayOf = (value: unknown, path: string) => arrayOf(value, path,
 });
 
 const scriptDefinitionOf = (payload: ObjectValue, path: string) => {
-    const definition = exactObject(payload, path, ["scriptId", "handle", "displayName", "execution", "grants", "toolNames"]);
+    const definition = exactObject(payload, path, ["scriptId", "handle", "displayName", "execution", "grants", "toolNames"], ["description"]);
     actorIdOf(definition.scriptId, `${path}.scriptId`);
+    if (definition.description !== undefined) nonEmptyStringOf(definition.description, `${path}.description`);
     stringOf(definition.handle, `${path}.handle`);
     stringOf(definition.displayName, `${path}.displayName`);
     executionOf(definition.execution, `${path}.execution`);
@@ -275,12 +275,13 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
     switch (type) {
         case "run.created": {
             const payload = exactObject(value, path, ["title", "owner"]);
-            const owner = exactObject(payload.owner, `${path}.owner`, ["id", "handle", "displayName", "grants"]);
+            const owner = exactObject(payload.owner, `${path}.owner`, ["id", "handle", "displayName", "grants"], ["userId"]);
             stringOf(payload.title, `${path}.title`);
             actorIdOf(owner.id, `${path}.owner.id`);
             stringOf(owner.handle, `${path}.owner.handle`);
             stringOf(owner.displayName, `${path}.owner.displayName`);
             grantsOf(owner.grants, `${path}.owner.grants`);
+            if (owner.userId !== undefined) stringOf(owner.userId, `${path}.owner.userId`);
             return;
         }
 
@@ -312,9 +313,10 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
                 "execution",
                 "grants",
                 "toolNames",
-            ], ["forkOf"]);
+            ], ["forkOf", "description"]);
             actorIdOf(payload.agentId, `${path}.agentId`);
             if (payload.forkOf !== undefined) actorIdOf(payload.forkOf, `${path}.forkOf`);
+            if (payload.description !== undefined) nonEmptyStringOf(payload.description, `${path}.description`);
             stringOf(payload.handle, `${path}.handle`);
             stringOf(payload.displayName, `${path}.displayName`);
             stringOf(payload.prompt, `${path}.prompt`);
@@ -356,7 +358,8 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
             return;
         }
 
-        case "turn.started": {
+        case "turn.started":
+        case "turn.input-steered": {
             const payload = exactObject(value, path, ["turnId", "inputId"]);
             stringOf(payload.turnId, `${path}.turnId`);
             stringOf(payload.inputId, `${path}.inputId`);
@@ -389,6 +392,7 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
         }
 
         case "model.output.completed":
+        case "model.output.interrupted":
         case "model.reasoning.completed":
         case "runtime.output.recorded": {
             const payload = exactObject(value, path, ["turnId", "text"]);
@@ -510,39 +514,36 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
         }
 
         case "action.proposed": {
+            if (Object.hasOwn(objectOf(value, path), "kind"))
+                fail(`${path}.kind`, "belongs to a journal written before actions became opaque and is not migrated");
+
             const payload = exactObject(value, path, [
                 "actionId",
-                "kind",
+                "owner",
                 "title",
                 "description",
                 "parameters",
                 "input",
-            ], ["question"]);
+                "payload",
+            ]);
             stringOf(payload.actionId, `${path}.actionId`);
-
-            if (payload.kind !== "action" && payload.kind !== "question")
-                fail(`${path}.kind`, "must be action or question");
-
-            if (payload.kind === "question")
-                questionOf(payload.question, `${path}.question`);
-            else if (Object.hasOwn(payload, "question"))
-                fail(`${path}.question`, "is only supported for questions");
-
+            nullableStringOf(payload.owner, `${path}.owner`);
             stringOf(payload.title, `${path}.title`);
             nullableStringOf(payload.description, `${path}.description`);
             stringRecordOf(payload.parameters, `${path}.parameters`);
             actionInputOf(payload.input, `${path}.input`);
+            actionPayloadOf(payload.payload, `${path}.payload`);
             return;
         }
 
         case "action.resolved": {
-            const payload = exactObject(value, path, ["actionId", "decision", "response"]);
+            const payload = exactObject(value, path, ["actionId", "decision", "result"]);
             stringOf(payload.actionId, `${path}.actionId`);
 
             if (payload.decision !== "approved" && payload.decision !== "dismissed")
                 fail(`${path}.decision`, "must be approved or dismissed");
 
-            nullableStringOf(payload.response, `${path}.response`);
+            assertJsonValue(payload.result, `${path}.result`);
             return;
         }
 

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

@@ -1,7 +1,6 @@
 import type {
     ActionId,
     ActionInput,
-    ActionKind,
     ActionStatus,
     ActorId,
     ActorKind,
@@ -16,7 +15,7 @@ import type {
     TurnId,
     TurnUsage,
 } from "./model.ts";
-import type { JsonChange, JsonValue } from "./json.ts";
+import type { JsonChange, JsonObject, JsonValue } from "./json.ts";
 
 export type EventPayloads = {
     "run.created": {
@@ -26,6 +25,8 @@ export type EventPayloads = {
             handle: string;
             displayName: string;
             grants: CapabilityGrant[];
+            /** Der angemeldete Benutzer, dem der Run gehört; ohne Anmeldung nicht gesetzt. */
+            userId?: string;
         };
     };
     "run.forked": {
@@ -47,6 +48,7 @@ export type EventPayloads = {
         grants: CapabilityGrant[];
         toolNames: string[] | null;
         forkOf?: ActorId;
+        description?: string;
     };
     "script.created": {
         scriptId: ActorId;
@@ -55,6 +57,7 @@ export type EventPayloads = {
         execution: AgentExecution;
         grants: CapabilityGrant[];
         toolNames: string[] | null;
+        description?: string;
     };
     "actor.input.enqueued": {
         inputId: InputId;
@@ -69,6 +72,10 @@ export type EventPayloads = {
         turnId: TurnId;
         inputId: InputId;
     };
+    "turn.input-steered": {
+        turnId: TurnId;
+        inputId: InputId;
+    };
     "turn.finished": {
         turnId: TurnId;
         usage?: TurnUsage;
@@ -81,6 +88,10 @@ export type EventPayloads = {
         turnId: TurnId;
         text: string;
     };
+    "model.output.interrupted": {
+        turnId: TurnId;
+        text: string;
+    };
     "model.reasoning.completed": {
         turnId: TurnId;
         text: string;
@@ -156,18 +167,17 @@ export type EventPayloads = {
     };
     "action.proposed": {
         actionId: ActionId;
+        owner: string | null;
         title: string;
         description: string | null;
         parameters: Record<string, string>;
         input: ActionInput | null;
-    } & (
-        | { kind: "action" }
-        | { kind: "question"; question: { options: string[]; multi: boolean } | null }
-    );
+        payload: JsonObject | null;
+    };
     "action.resolved": {
         actionId: ActionId;
         decision: Exclude<ActionStatus, "pending">;
-        response: string | null;
+        result: JsonValue | null;
     };
     "artifact.published": {
         artifact: Omit<Artifact, "createdBy" | "createdAt">;
@@ -185,9 +195,11 @@ export const eventTypeMap: Record<EventType, true> = {
     "script.created": true,
     "actor.input.enqueued": true,
     "turn.started": true,
+    "turn.input-steered": true,
     "turn.finished": true,
     "turn.interrupted": true,
     "model.output.completed": true,
+    "model.output.interrupted": true,
     "model.reasoning.completed": true,
     "runtime.output.recorded": true,
     "tool.call.started": true,

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

@@ -6,6 +6,8 @@ export type JsonValue =
     | JsonValue[]
     | { [key: string]: JsonValue | undefined };
 
+export type JsonObject = { [key: string]: JsonValue | undefined };
+
 export type JsonPath = (string | number)[];
 export type JsonChange =
     | { op: "set"; path: JsonPath; value: JsonValue }

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

@@ -1,5 +1,6 @@
 import type { AgentExecution } from "./driver.ts";
-import type { JsonValue } from "./json.ts";
+import type { JournalEvent } from "./events.ts";
+import type { JsonObject, JsonValue } from "./json.ts";
 import type { CapabilityName, ObservableEventType } from "./vocabulary.ts";
 
 export type { CapabilityName, ObservableEventType };
@@ -51,8 +52,12 @@ export type TurnUsage = {
     costUsd: number;
 };
 
+/** Longest short description an actor may carry for overviews. */
+export const actorDescriptionMaxLength = 160;
+
 type ExecutableActorBase = ActorBase & {
     createdBy: ActorId;
+    description: string | null;
     execution: AgentExecution;
     lifecycle: ActorLifecycle;
     usage: TurnUsage;
@@ -73,9 +78,10 @@ export type ScriptActor = ExecutableActorBase & { kind: "script" };
 export type ExecutableActor = AgentActor | ScriptActor;
 export type Actor = HumanActor | ExecutableActor;
 
+/** `steered` marks an input that joined its already running turn instead of starting it. */
 export type ActorInputLifecycle =
     | { kind: "pending" }
-    | { kind: "claimed"; turnId: TurnId }
+    | { kind: "claimed"; turnId: TurnId; steered: boolean }
     | { kind: "discarded"; at: string; reason: string };
 
 export type ActorInput = {
@@ -125,8 +131,6 @@ export type Turn = {
     toolCalls: readonly TurnToolCall[];
 };
 
-export type SubscriptionStatus = "active" | "removed" | "failed";
-
 export type EventSubscription = {
     id: SubscriptionId;
     subscriberId: ActorId;
@@ -164,29 +168,22 @@ export type ActionInput = {
 };
 
 export type ActionStatus = "pending" | "approved" | "dismissed";
-export type ActionKind = "action" | "question";
-
-export type ActionQuestion = {
-    options: readonly string[];
-    multi: boolean;
-};
 
 export type Action = {
     id: ActionId;
     askedBy: ActorId;
+    owner: string | null;
     title: string;
     description: string | null;
     parameters: Readonly<Record<string, string>>;
     input: ActionInput | null;
+    payload: JsonObject | null;
     status: ActionStatus;
     proposedAt: string;
     resolvedAt: string | null;
     resolvedBy: ActorId | null;
-    response: string | null;
-} & (
-    | { kind: "action" }
-    | { kind: "question"; question: ActionQuestion | null }
-);
+    result: JsonValue | null;
+};
 
 export type Artifact = {
     id: ArtifactId;
@@ -204,7 +201,11 @@ export type RunState = {
     revision: number;
     title: string;
     ownerId: ActorId;
+    /** Der angemeldete Benutzer, dem der Run gehört; null für Runs, die ohne Anmeldung entstanden sind. */
+    ownerUserId: string | null;
     primaryActorId: ActorId | null;
+    /** Der Primary-Actor, der als solcher gestoppt wurde, bis ein Primary-Actor gewählt wird; sein Neustart durch den Owner macht ihn wieder dazu. */
+    stoppedPrimaryActorId: ActorId | null;
     createdAt: string;
     forkedFrom: { runId: RunId; sequence: number } | null;
     actors: ReadonlyMap<ActorId, Actor>;
@@ -216,9 +217,32 @@ export type RunState = {
     artifacts: ReadonlyMap<ArtifactId, Artifact>;
 };
 
+/** Der Actor, den ein Event betrifft: bei Turn-Enden der Besitzer des Turns, bei Stopp und Neustart der Ziel-Actor, sonst der Schreiber. */
+export const eventSubjectOf = (state: RunState, event: JournalEvent): ActorId => {
+    switch (event.type) {
+        case "turn.finished":
+        case "turn.interrupted": {
+            const turn = state.turns.get(event.payload.turnId);
+
+            if (!turn)
+                throw new Error(`Turn ${event.payload.turnId} of event ${event.eventId} does not exist.`);
+
+            return turn.actorId;
+        }
+
+        case "actor.stopped":
+        case "actor.restarted":
+            return event.payload.actorId;
+
+        default:
+            return event.actorId;
+    }
+};
+
 type Collections = "actors" | "inputs" | "turns" | "subscriptions" | "pluginStates" | "actions" | "artifacts";
 
-export type RunView = Omit<RunState, Collections> & {
+/** Die Run-Ansicht für Clients; der Eigentümer bleibt serverseitig und steht nicht in ihr. */
+export type RunView = Omit<RunState, Collections | "ownerUserId"> & {
     actors: Actor[];
     inputs: ActorInput[];
     turns: Turn[];
@@ -263,5 +287,3 @@ export const addUsage = (left: TurnUsage, right: TurnUsage): TurnUsage => ({
     cacheWriteTokens: checkedTokenTotal("cacheWriteTokens", left.cacheWriteTokens, right.cacheWriteTokens),
     costUsd: checkedCostTotal(left.costUsd, right.costUsd),
 });
-
-export const isExecutableActor = (actor: Actor): actor is ExecutableActor => actor.kind !== "human";