@schlenkr/ragents 0.1.5 → 0.1.7

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

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { InlineExtension, ModelRuntime } from "@aicontainer/agent";
+import type { ModelRuntime } from "@ragents/agent";
 import type { TSchema } from "typebox";
 import type { AgentProfile, CatalogModel, ModelCatalog } from "./agents/catalog.ts";
 import type { ToolContributor, ToolRegistry } from "./agents/plugins.ts";
@@ -21,10 +21,16 @@ export interface ProductDescriptor {
   accessCookieName?: string;
 }
 
+/** Where the browser loads a plugin's web half from; the host serves its bundle under these addresses. */
+export interface PluginWebAddresses {
+  readonly entry: string;
+  readonly css?: string;
+}
+
 export interface PluginManifest {
   id: string;
   requires?: readonly string[];
-  web?: boolean;
+  web?: PluginWebAddresses;
   client?: {
     config?: Readonly<Record<string, unknown>>;
   };
@@ -32,7 +38,7 @@ export interface PluginManifest {
 
 export interface PublicPluginDescriptor {
   id: string;
-  web: boolean;
+  web?: PluginWebAddresses;
   config?: Readonly<Record<string, unknown>>;
 }
 
@@ -40,6 +46,8 @@ export interface PublicPluginProfile {
   product: ProductDescriptor;
   plugins: readonly PublicPluginDescriptor[];
   startEntries: readonly PublicStartEntry[];
+  /** The profile's default template for a new run; present only when it is among the caller's templates. */
+  defaultStartEntry?: string;
 }
 
 export interface PublicPluginConfigDescriptor {
@@ -69,17 +77,18 @@ export interface PublicPromptSnapshot {
   contributions: readonly PublicPromptContribution[];
 }
 
-export interface PublicAgentExtensionFactory {
-  name: string | null;
-  scope: "global" | "per-agent";
+export interface PublicAgentHookFactory {
+  name: string;
+  scope: "per-agent";
 }
 
-export interface PublicAgentExtensionContribution {
+/** A plugin contribution as the settings show it: the host turns it into one extension per agent, named after its id. */
+export interface PublicAgentHookContribution {
   id: string;
   owner: string;
   kind: "plugin";
-  factories: readonly PublicAgentExtensionFactory[];
-  resolvesPerAgent: boolean;
+  factories: readonly PublicAgentHookFactory[];
+  resolvesPerAgent: true;
 }
 
 export interface PublicSkillContribution {
@@ -93,7 +102,7 @@ export interface PublicToolDescriptor extends ToolDescriptor {
   id: string;
   owner: string;
   source: string;
-  kind: "agent-builtin" | "agent-extension" | "ragents" | "plugin";
+  kind: "agent-builtin" | "ragents" | "plugin";
 }
 
 export interface HttpRouteContext {
@@ -163,21 +172,50 @@ export interface AgentContributionContext {
   workspace: string;
 }
 
-export interface AgentToolDescriptor extends ToolDescriptor {
-  scope: "per-agent";
-  availability: "always";
+/** What a hook sees of the model call it runs in. */
+export interface AgentHookContext {
+  readonly signal: AbortSignal | undefined;
+  readonly modelReadsImages: boolean;
 }
 
-export interface AgentContribution {
-  id: string;
-  global?: readonly InlineExtension[];
-  tools: readonly AgentToolDescriptor[];
-  resolve?: (
-    context: AgentContributionContext,
-  ) => readonly InlineExtension[] | Promise<readonly InlineExtension[]>;
+export interface ModelCallContext extends AgentHookContext {
+  /** What this contribution kept last in the agent's conversation, also after a restart of the host. */
+  readonly kept: JsonValue | undefined;
+  /** Keeps a value in the agent's conversation for later calls; the model never sees it. */
+  readonly keep: (value: JsonValue) => void;
+}
+
+export interface ToolCallOutcome {
+  readonly toolName: string;
+  readonly isError: boolean;
 }
 
-/** What every entry of the start surface shares, whichever action it triggers. */
+export type ToolResultPart =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "image"; readonly data: string; readonly mimeType: string };
+
+export interface ToolResultReplacement {
+  readonly content: readonly ToolResultPart[];
+  readonly isError?: boolean;
+}
+
+/** Hooks into the model calls of every agent; the host resolves them per agent and knows nothing of the agent runtime behind them. */
+export interface AgentContribution {
+  readonly id: string;
+  /** Before each model call of a turn; a returned text reaches the model as a hidden note after the conversation. */
+  readonly beforeModelCall?: (
+    agent: AgentContributionContext,
+    call: ModelCallContext,
+  ) => string | undefined | Promise<string | undefined>;
+  /** After each tool call; a returned result replaces what the model sees of it. */
+  readonly afterToolCall?: (
+    agent: AgentContributionContext,
+    outcome: ToolCallOutcome,
+    call: AgentHookContext,
+  ) => ToolResultReplacement | undefined | Promise<ToolResultReplacement | undefined>;
+}
+
+/** What every template of the start page shares, whichever action it triggers. */
 export interface StartEntryBase {
   id: string;
   title: string;
@@ -186,6 +224,8 @@ export interface StartEntryBase {
   guide?: string;
   /** Searchable labels supplied by the plugin, independent of the entry action. */
   tags?: readonly string[];
+  /** Start options this entry fixes, option id to value; a run started through it takes exactly these values. */
+  fixedStartOptions?: Readonly<Record<string, JsonValue>>;
 }
 
 export interface ActorProgramFile {
@@ -207,13 +247,13 @@ export interface RunScriptPackage {
 
 export type StartEntryContribution = StartEntryBase & (
   | { action: "skill"; skill: string; category: string; prompt: string }
-  /** A run script may name a category of its own; without one the start surfaces group it as a run script. */
+  /** A run script may name a category of its own; without one the start pages group it as a run script. */
   | { action: "script"; script: RunScriptPackage; category?: string }
 );
 
 export type StartEntryAction = StartEntryContribution["action"];
 
-/** The entry as the web sees it: a script entry shows its kind and coordinator flag, never its source. */
+/** The template as the web sees it: a script template shows its kind and coordinator flag, never its source. */
 export type PublicStartEntry = StartEntryBase & { owner: string } & (
   | { action: "skill"; skill: string; category: string; prompt: string }
   | { action: "script"; coordinator: boolean; category?: string }
@@ -280,10 +320,17 @@ export interface SessionStopContext extends SessionLifecycleContext {
   signal: AbortSignal;
 }
 
+export interface SessionStartedContext extends SessionLifecycleContext {
+  /** The template the run was started from; null for a start without one. */
+  startEntry: { id: string; action: StartEntryAction } | null;
+}
+
 export interface SessionLifecycleContribution {
   id: string;
   initialize?: () => void | Promise<void>;
   prepareSession?: (context: SessionLifecycleContext) => void | Promise<void>;
+  /** After a start has prepared the workspace and set up the run's first actor, before any actor got input; never after a restart of the host. */
+  sessionStarted?: (context: SessionStartedContext) => void | Promise<void>;
   stopSession?: (context: SessionStopContext) => void | Promise<void>;
   afterStopSession?: (context: SessionStopContext) => void | Promise<void>;
   deleteSession?: (context: SessionLifecycleContext) => void | Promise<void>;
@@ -296,6 +343,8 @@ export interface SessionMetadataContext {
 
 export interface StartOptionContext {
   runId: string;
+  /** Der Benutzer, der gerade handelt: aus dem Zugang der Anfrage, null ohne Anmeldung. */
+  userId: string | null;
 }
 
 export interface StartOptionContribution {
@@ -305,6 +354,12 @@ export interface StartOptionContribution {
   defaultValue: (context: StartOptionContext) => JsonValue;
   accept: (value: JsonValue, context: StartOptionContext) => JsonValue;
   describe: (value: JsonValue, context: StartOptionContext) => JsonValue;
+  /** Zusätzliche Rechte, ohne die Liste und Wahl die Option nicht anbieten, etwa runs.inspect für technische Einsicht. */
+  rights?: readonly string[];
+  /** Nach dem Start weiter wählbar: der Host schreibt jeden neuen Wert ins Journal, wer die Option liest, folgt dem jeweils gespeicherten. */
+  changeable?: boolean;
+  /** Ob nur der Eigentümer einen Run mit diesem Wert bedient; lesen und stoppen dürfen ihn alle, die ihn sehen. */
+  ownerOnly?: (value: JsonValue) => boolean;
 }
 
 export interface RegisteredStartOption {
@@ -314,9 +369,17 @@ export interface RegisteredStartOption {
 
 export interface SessionMetadataContribution {
   id: string;
+  /** Ob `describe` den Arbeitsbereich des Runs erreicht; dann ruft der Host es nur für Aufrufer, die ihn erreichen dürfen. */
+  requiresWorkspace?: boolean;
   describe: (context: SessionMetadataContext) => unknown | Promise<unknown>;
 }
 
+/** Die Angaben eines Runs je Beitrag; ein Beitrag ohne Wert steht mit seinem Grund in `unavailable`. */
+export interface SessionMetadata {
+  readonly values: Readonly<Record<string, unknown>>;
+  readonly unavailable: Readonly<Record<string, string>>;
+}
+
 export interface PluginConfigDescriptor {
   key: string;
   source: string;

package/packages/ragents/src/rpc/peer.ts

@@ -155,6 +155,12 @@ export class RpcPeer {
     void this.#deliver(rpcFailure(null, RPC_ERROR_CODES.invalidRequest, "Die Nachricht ist kein gültiges JSON-RPC")).catch(() => undefined);
   }
 
+  /** Bricht alle laufenden Handler ab, etwa wenn der Strom weg ist, über den ihre Antwort ginge; eigene Aufrufe bleiben möglich. */
+  cancelIncoming(): void {
+    for (const controller of this.#running.values()) controller.abort();
+    this.#running.clear();
+  }
+
   close(reason: string): void {
     if (this.#closed !== undefined) return;
     this.#closed = reason;

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

@@ -1,58 +1,58 @@
-import type { ActionInput, ActionKind, ActionStatus } from "../../domain/model.ts";
+import type { JsonObject, JsonValue } from "../../domain/json.ts";
+import { assertJsonValue } from "../../domain/json.ts";
+import type { ActionInput, ActionStatus } from "../../domain/model.ts";
 import { event, type Decision } from "../command.ts";
 import { DomainError } from "../domain-error.ts";
-import { actorOf, assertCapability, clean, optionalClean } from "../guards.ts";
+import { commandActorOf, assertCapability, clean, optionalClean } from "../guards.ts";
+
+const isBlank = (result: JsonValue | null) =>
+    result === null || (typeof result === "string" && result.trim() === "");
 
 export const proposeAction =
     (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;
     }): Decision =>
     (state, context, services) => {
-        const caller = actorOf(state, context);
-        const kind = input.kind ?? "action";
+        const caller = commandActorOf(state, context);
+        const owner = input.owner ? clean(input.owner, "owner") : null;
 
-        if (kind !== "question")
+        if (owner === null)
             assertCapability(caller, "action.propose", { kind: "run" });
 
-        const base = {
-            actionId: services.newId("action"),
-            title: clean(input.title, "title"),
-            description: optionalClean(input.description, "description"),
-            parameters: Object.fromEntries(
-                Object.entries(input.parameters ?? {}).map(([name, value]) => [clean(name, "parameter name"), value]),
-            ),
-            input: input.input
-                ? {
-                      label: clean(input.input.label, "input.label"),
-                      placeholder: optionalClean(input.input.placeholder, "input.placeholder"),
-                      required: input.input.required,
-                  }
-                : null,
-        };
+        if (input.payload !== undefined && input.payload !== null)
+            assertJsonValue(input.payload, "payload");
 
         return [event(context, {
             type: "action.proposed",
-            payload: kind === "question"
-                ? {
-                    ...base,
-                    kind,
-                    question: input.question
-                        ? { options: [...input.question.options], multi: input.question.multi === true }
-                        : null,
-                }
-                : { ...base, kind },
+            payload: {
+                actionId: services.newId("action"),
+                owner,
+                title: clean(input.title, "title"),
+                description: optionalClean(input.description, "description"),
+                parameters: Object.fromEntries(
+                    Object.entries(input.parameters ?? {}).map(([name, value]) => [clean(name, "parameter name"), value]),
+                ),
+                input: input.input
+                    ? {
+                          label: clean(input.input.label, "input.label"),
+                          placeholder: optionalClean(input.input.placeholder, "input.placeholder"),
+                          required: input.input.required,
+                      }
+                    : null,
+                payload: input.payload ?? null,
+            },
         })];
     };
 
 export const resolveAction =
-    (actionId: string, input: { decision: Exclude<ActionStatus, "pending">; response?: string | null }): Decision =>
+    (actionId: string, input: { decision: Exclude<ActionStatus, "pending">; result?: JsonValue | null }): Decision =>
     (state, context) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
 
         if (caller.kind !== "human")
             throw new DomainError("human-confirmation-required", "Only a human can resolve a proposed action.", 403);
@@ -65,13 +65,16 @@ export const resolveAction =
         if (action.status !== "pending")
             throw new DomainError("action-already-resolved", `Action ${actionId} is already ${action.status}.`, 409);
 
-        const response = optionalClean(input.response, "response");
+        const result = input.result ?? null;
+
+        if (result !== null)
+            assertJsonValue(result, "result");
 
-        if (input.decision === "approved" && action.input?.required && !response)
-            throw new DomainError("action-response-required", `Action ${actionId} requires a response.`, 400);
+        if (input.decision === "approved" && action.input?.required && isBlank(result))
+            throw new DomainError("action-result-required", `Action ${actionId} requires a result.`, 400);
 
         return [event(context, {
             type: "action.resolved",
-            payload: { actionId, decision: input.decision, response },
+            payload: { actionId, decision: input.decision, result },
         })];
     };

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

@@ -10,14 +10,15 @@ import type {
 import { assertJsonValue, type JsonValue } from "../../domain/json.ts";
 import { jsonChanges } from "../../domain/json-patch.ts";
 import type { UncommittedEvent } from "../../domain/events.ts";
-import { isPendingActorInput, actorStatePluginId, pluginStateKey } from "../../domain/model.ts";
+import { isPendingActorInput, actorDescriptionMaxLength, actorStatePluginId, pluginStateKey } from "../../domain/model.ts";
 import { scriptExecution } from "../../domain/driver.ts";
 import { isActiveActor } from "../../domain/projection.ts";
 import { event, type CommandContext, type Decision } from "../command.ts";
 import { DomainError } from "../domain-error.ts";
+import { descendantsOf } from "../stop.ts";
 import {
     actorById,
-    actorOf,
+    commandActorOf,
     addressedActorOf,
     assertCapability,
     assertDelegation,
@@ -40,10 +41,24 @@ const selectedToolNames = (value: readonly string[] | null): string[] | null =>
     return toolNames;
 };
 
+const descriptionOf = (value: string | undefined): { description?: string } => {
+    if (value === undefined)
+        return {};
+
+    const description = clean(value.replace(/\s+/g, " "), "description");
+
+    if (description.length > actorDescriptionMaxLength)
+        throw new DomainError("invalid-value", `description must not exceed ${actorDescriptionMaxLength} characters; it has ${description.length}.`, 400);
+
+    return { description };
+};
+
+const isRunConfigurator = (state: RunState, caller: Actor) =>
+    caller.id === state.ownerId || hasCapability(caller, "run.configure", { kind: "run" });
+
 /** The owner configures the run by right; any other actor needs the capability run.configure. */
 const assertRunConfigurator = (state: RunState, caller: Actor) => {
-    if (caller.id === state.ownerId) return;
-    if (!hasCapability(caller, "run.configure", { kind: "run" }))
+    if (!isRunConfigurator(state, caller))
         throw new DomainError(
             "run-configuration-denied",
             `${caller.displayName} may not configure the run; that takes the owner or the capability run.configure.`,
@@ -52,7 +67,7 @@ const assertRunConfigurator = (state: RunState, caller: Actor) => {
 };
 
 export const selectPrimaryActor = (actorId: string): Decision => (state, context) => {
-    const caller = actorOf(state, context);
+    const caller = commandActorOf(state, context);
     const target = executableActorOf(state, actorId);
 
     assertRunConfigurator(state, caller);
@@ -64,7 +79,7 @@ export const selectPrimaryActor = (actorId: string): Decision => (state, context
 };
 
 export const retitleRun = (title: string): Decision => (state, context) => {
-    assertRunConfigurator(state, actorOf(state, context));
+    assertRunConfigurator(state, commandActorOf(state, context));
 
     return [event(context, { type: "run.title-changed", payload: { title: clean(title, "title") } })];
 };
@@ -78,9 +93,10 @@ export const spawnAgent =
         grants: readonly CapabilityGrant[];
         toolNames: readonly string[] | null;
         forkOf?: string;
+        description?: string;
     }): Decision =>
     (state, context, services) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
         assertCapability(caller, "agent.spawn", { kind: "run" });
         assertDelegation(caller, input.grants);
 
@@ -101,13 +117,14 @@ export const spawnAgent =
                     grants: [...input.grants],
                     toolNames: selectedToolNames(input.toolNames),
                     ...(forkOf ? { forkOf } : {}),
+                    ...descriptionOf(input.description),
                 },
             }),
         ];
     };
 
 const forkSourceOf = (state: RunState, reference: string): string => {
-    const source = addressedActorOf(state, reference);
+    const source = addressedActorOf(state.actors.values(), reference);
 
     if (source.kind !== "agent")
         throw new DomainError("invalid-value", `Fork source ${reference} is not an LLM agent.`, 400);
@@ -115,6 +132,16 @@ const forkSourceOf = (state: RunState, reference: string): string => {
     if (source.execution.driver.kind !== "agent")
         throw new DomainError("invalid-value", `Fork source ${reference} has no model context to fork.`, 400);
 
+    const finishedContext = [...state.turns.values()].some((turn) =>
+        turn.actorId === source.id && turn.status !== "running" && state.contextTurns.has(turn.id));
+
+    if (source.forkOf === null && !finishedContext)
+        throw new DomainError(
+            "fork-without-turn",
+            `Fork source ${reference} has no model context from a finished turn yet; a fork takes the context of finished turns only, never of the running one.`,
+            409,
+        );
+
     return source.id;
 };
 
@@ -125,9 +152,10 @@ export const createScriptActor =
         grants: readonly CapabilityGrant[];
         toolNames: readonly string[] | null;
         turnTimeoutMs?: number | null;
+        description?: string;
     }): Decision =>
     (state, context, services) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
         assertCapability(caller, "agent.spawn", { kind: "run" });
         assertDelegation(caller, input.grants);
         const handle = handleOf(input.handle);
@@ -143,6 +171,7 @@ export const createScriptActor =
                 execution: scriptExecution(input.turnTimeoutMs ?? null),
                 grants: [...input.grants],
                 toolNames: selectedToolNames(input.toolNames),
+                ...descriptionOf(input.description),
             },
         })];
     };
@@ -169,7 +198,7 @@ const belongsToBranch = (state: RunState, actor: ExecutableActor, ownerId: strin
 export const restartActor =
     (actorId: string, reason: string): Decision =>
     (state, context) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
         const target = executableActorOf(state, actorId);
 
         if (caller.id !== state.ownerId) {
@@ -186,47 +215,27 @@ export const restartActor =
         if (target.lifecycle.kind !== "stopped")
             throw new DomainError("actor-active", `Actor ${actorId} is not stopped.`);
 
-        const collision = [...state.actors.values()].find((entry) =>
-            entry.id !== target.id && entry.handle === target.handle && isActiveActor(entry));
-
-        if (collision)
-            throw new DomainError(
-                "handle-exists",
-                `Handle @${target.handle} is now taken by ${collision.id}. Stop that actor first or leave this one stopped.`,
-            );
+        const restarted = event(context, { type: "actor.restarted", payload: { actorId: target.id, reason: clean(reason, "reason") } });
 
-        return [event(context, { type: "actor.restarted", payload: { actorId: target.id, reason: clean(reason, "reason") } })];
+        return state.stoppedPrimaryActorId === target.id && isRunConfigurator(state, caller)
+            ? [restarted, event(context, { type: "run.primary-actor-selected", payload: { actorId: target.id } })]
+            : [restarted];
     };
 
-export const stopActor =
-    (actorId: string, reason: string): Decision =>
-    (state, context) => {
-        const caller = actorOf(state, context);
-        const target = executableActorOf(state, actorId);
-
-        if (caller.id !== state.ownerId) {
-            assertCapability(caller, "execution.stopOwned", { kind: "run" });
-
-            if (!belongsToBranch(state, target, caller.id))
-                throw new DomainError("actor-stop-denied", `${caller.displayName} may only stop actors in its own branch.`, 403);
-        }
-
-        if (!isActiveActor(target))
-            throw new DomainError("actor-inactive", `Actor ${actorId} is already stopped.`);
-
-        const cleanReason = clean(reason, "reason");
-        const subscriptions = [...state.subscriptions.values()]
-            .filter((subscription) => subscription.subscriberId === target.id && subscription.status === "active");
-
-        return [
-            ...(target.lifecycle.kind === "running"
-                ? [event(context, {
-                      type: "turn.interrupted" as const,
-                      payload: { turnId: target.lifecycle.turnId, reason: cleanReason },
-                  })]
-                : []),
-            event(context, { type: "actor.stopped", payload: { actorId, reason: cleanReason } }),
-            ...subscriptions.map((subscription) => event(context, {
+const stopEventsOf = (state: RunState, context: CommandContext, targets: readonly ExecutableActor[], reason: string) => {
+    const cleanReason = clean(reason, "reason");
+
+    return targets.flatMap((target): UncommittedEvent[] => [
+        ...(target.lifecycle.kind === "running"
+            ? [event(context, {
+                  type: "turn.interrupted" as const,
+                  payload: { turnId: target.lifecycle.turnId, reason: cleanReason },
+              })]
+            : []),
+        event(context, { type: "actor.stopped", payload: { actorId: target.id, reason: cleanReason } }),
+        ...[...state.subscriptions.values()]
+            .filter((subscription) => subscription.subscriberId === target.id && subscription.status === "active")
+            .map((subscription) => event(context, {
                 type: "subscription.removed" as const,
                 payload: {
                     subscriptionId: subscription.id,
@@ -237,7 +246,47 @@ export const stopActor =
                         .map((input) => input.id),
                 },
             })),
-        ];
+    ]);
+};
+
+const stoppableActorOf = (state: RunState, caller: Actor, actorId: string) => {
+    const target = executableActorOf(state, actorId);
+
+    if (caller.id !== state.ownerId) {
+        assertCapability(caller, "execution.stopOwned", { kind: "run" });
+
+        if (!belongsToBranch(state, target, caller.id))
+            throw new DomainError("actor-stop-denied", `${caller.displayName} may only stop actors in its own branch.`, 403);
+    }
+
+    if (!isActiveActor(target))
+        throw new DomainError("actor-inactive", `Actor ${actorId} is already stopped.`);
+
+    return target;
+};
+
+/** Stops the actor and all of its active descendants together, in the name of the caller. */
+export const stopActor =
+    (actorId: string, reason: string): Decision =>
+    (state, context) => {
+        const target = stoppableActorOf(state, commandActorOf(state, context), actorId);
+
+        return stopEventsOf(state, context, [target, ...descendantsOf({ actors: state.actors.values() }, target.id)], reason);
+    };
+
+/** Stops exactly these actors together; the caller names every one of them. */
+export const stopActors =
+    (actorIds: readonly string[], reason: string): Decision =>
+    (state, context) => {
+        const caller = commandActorOf(state, context);
+
+        if (actorIds.length === 0)
+            throw new DomainError("invalid-value", "actorIds must name at least one actor.", 400);
+
+        if (new Set(actorIds).size !== actorIds.length)
+            throw new DomainError("invalid-value", "actorIds must not contain duplicates.", 400);
+
+        return stopEventsOf(state, context, actorIds.map((actorId) => stoppableActorOf(state, caller, actorId)), reason);
     };
 
 const stateChange = (state: RunState, context: CommandContext, pluginId: string, scope: PluginStateScope, raw: JsonValue): UncommittedEvent => {
@@ -257,7 +306,7 @@ const stateChange = (state: RunState, context: CommandContext, pluginId: string,
 export const replacePluginState =
     (input: { pluginId: string; scope: PluginStateScope; state: JsonValue }): Decision =>
     (state, context) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
         const pluginId = clean(input.pluginId, "pluginId");
 
         if (input.scope.kind === "actor") {
@@ -274,7 +323,7 @@ export const replacePluginState =
     };
 
 export const replaceActorState = (actorId: string, value: JsonValue): Decision => (state, context) => {
-    const caller = actorOf(state, context);
+    const caller = commandActorOf(state, context);
     executableActorOf(state, actorId);
     if (caller.id !== actorId && caller.id !== state.ownerId)
         throw new DomainError("actor-state-access-denied", "An actor may only replace its own intrinsic state.", 403);

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

@@ -1,7 +1,7 @@
 import type { Artifact } from "../../domain/model.ts";
 import { event, type Decision } from "../command.ts";
 import type { StoredArtifactContent } from "../artifacts.ts";
-import { actorOf, artifactOf, assertArtifactRead, assertCapability, clean } from "../guards.ts";
+import { commandActorOf, artifactOf, assertArtifactRead, assertCapability, clean } from "../guards.ts";
 
 export const publishArtifact =
     (
@@ -9,7 +9,7 @@ export const publishArtifact =
         stored: StoredArtifactContent,
     ): Decision =>
     (state, context, services) => {
-        const actor = actorOf(state, context);
+        const actor = commandActorOf(state, context);
         assertCapability(actor, "artifact.publish", { kind: "run" });
 
         if (input.previousVersionId)

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

@@ -3,7 +3,7 @@ import { event, type Decision } from "../command.ts";
 import { DomainError } from "../domain-error.ts";
 import {
     actorById,
-    actorOf,
+    commandActorOf,
     addressedActorOf,
     artifactOf,
     assertArtifactRead,
@@ -24,9 +24,9 @@ export type EnqueueInput = {
 export const enqueueInput =
     (input: EnqueueInput): Decision =>
     (state, context, services) => {
-        const target = executableActorOf(state, addressedActorOf(state, input.actorId).id);
+        const target = executableActorOf(state, addressedActorOf(state.actors.values(), input.actorId).id);
         const subscriptionId = input.subscriptionId ?? null;
-        const caller = subscriptionId ? actorById(state, context.actorId) : actorOf(state, context);
+        const caller = subscriptionId ? actorById(state, context.actorId) : commandActorOf(state, context);
 
         if (!isActiveActor(target))
             throw new DomainError("actor-inactive", `${target.displayName} is stopped.`);