@schlenkr/ragents 0.1.0

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

@@ -0,0 +1,283 @@
+
+import type {
+    Actor,
+    AgentExecution,
+    CapabilityGrant,
+    ExecutableActor,
+    PluginStateScope,
+    RunState,
+} from "../../domain/model.ts";
+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 { 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 {
+    actorById,
+    actorOf,
+    addressedActorOf,
+    assertCapability,
+    assertDelegation,
+    uniqueHandleOf,
+    clean,
+    executableActorOf,
+    handleOf,
+    hasCapability,
+} from "../guards.ts";
+
+const selectedToolNames = (value: readonly string[] | null): string[] | null => {
+    if (value === null)
+        return null;
+
+    const toolNames = value.map((name) => clean(name, "tool name"));
+
+    if (new Set(toolNames).size !== toolNames.length)
+        throw new DomainError("invalid-value", "toolNames must not contain duplicates.", 400);
+
+    return toolNames;
+};
+
+/** 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" }))
+        throw new DomainError(
+            "run-configuration-denied",
+            `${caller.displayName} may not configure the run; that takes the owner or the capability run.configure.`,
+            403,
+        );
+};
+
+export const selectPrimaryActor = (actorId: string): Decision => (state, context) => {
+    const caller = actorOf(state, context);
+    const target = executableActorOf(state, actorId);
+
+    assertRunConfigurator(state, caller);
+
+    if (!isActiveActor(target))
+        throw new DomainError("actor-inactive", `Actor ${actorId} is stopped.`, 409);
+
+    return [event(context, { type: "run.primary-actor-selected", payload: { actorId: target.id } })];
+};
+
+export const retitleRun = (title: string): Decision => (state, context) => {
+    assertRunConfigurator(state, actorOf(state, context));
+
+    return [event(context, { type: "run.title-changed", payload: { title: clean(title, "title") } })];
+};
+
+export const spawnAgent =
+    (input: {
+        handle: string;
+        displayName: string;
+        prompt: string;
+        execution: AgentExecution;
+        grants: readonly CapabilityGrant[];
+        toolNames: readonly string[] | null;
+        forkOf?: string;
+    }): Decision =>
+    (state, context, services) => {
+        const caller = actorOf(state, context);
+        assertCapability(caller, "agent.spawn", { kind: "run" });
+        assertDelegation(caller, input.grants);
+
+        const requested = handleOf(input.handle);
+        const handle = uniqueHandleOf(state, requested);
+        const suffix = handle === requested ? "" : ` ${handle.slice(requested.length + 1)}`;
+        const forkOf = input.forkOf === undefined ? undefined : forkSourceOf(state, input.forkOf);
+
+        return [
+            event(context, {
+                type: "agent.spawned",
+                payload: {
+                    agentId: services.newId("agent"),
+                    handle,
+                    displayName: `${clean(input.displayName, "displayName")}${suffix}`,
+                    prompt: input.prompt.trim(),
+                    execution: input.execution,
+                    grants: [...input.grants],
+                    toolNames: selectedToolNames(input.toolNames),
+                    ...(forkOf ? { forkOf } : {}),
+                },
+            }),
+        ];
+    };
+
+const forkSourceOf = (state: RunState, reference: string): string => {
+    const source = addressedActorOf(state, reference);
+
+    if (source.kind !== "agent")
+        throw new DomainError("invalid-value", `Fork source ${reference} is not an LLM agent.`, 400);
+
+    if (source.execution.driver.kind !== "agent")
+        throw new DomainError("invalid-value", `Fork source ${reference} has no model context to fork.`, 400);
+
+    return source.id;
+};
+
+export const createScriptActor =
+    (input: {
+        handle: string;
+        displayName: string;
+        grants: readonly CapabilityGrant[];
+        toolNames: readonly string[] | null;
+        turnTimeoutMs?: number | null;
+    }): Decision =>
+    (state, context, services) => {
+        const caller = actorOf(state, context);
+        assertCapability(caller, "agent.spawn", { kind: "run" });
+        assertDelegation(caller, input.grants);
+        const handle = handleOf(input.handle);
+        if ([...state.actors.values()].some((actor) => actor.handle === handle))
+            throw new DomainError("handle-exists", `Handle @${handle} already belongs to an actor.`);
+
+        return [event(context, {
+            type: "script.created",
+            payload: {
+                scriptId: services.newId("script"),
+                handle,
+                displayName: clean(input.displayName, "displayName"),
+                execution: scriptExecution(input.turnTimeoutMs ?? null),
+                grants: [...input.grants],
+                toolNames: selectedToolNames(input.toolNames),
+            },
+        })];
+    };
+
+const belongsToBranch = (state: RunState, actor: ExecutableActor, ownerId: string) => {
+    let creatorId = actor.createdBy;
+    const visited = new Set<string>();
+
+    while (!visited.has(creatorId)) {
+        if (creatorId === ownerId)
+            return true;
+
+        visited.add(creatorId);
+        const creator = state.actors.get(creatorId);
+        if (!creator || creator.kind === "human")
+            return false;
+
+        creatorId = creator.createdBy;
+    }
+
+    return false;
+};
+
+export const restartActor =
+    (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-restart-denied",
+                    `${caller.displayName} may only restart actors in its own branch.`,
+                    403,
+                );
+        }
+
+        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.`,
+            );
+
+        return [event(context, { type: "actor.restarted", payload: { actorId: target.id, reason: clean(reason, "reason") } })];
+    };
+
+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, {
+                type: "subscription.removed" as const,
+                payload: {
+                    subscriptionId: subscription.id,
+                    reason: cleanReason,
+                    discardedInputIds: [...state.inputs.values()]
+                        .filter((input) =>
+                            input.subscriptionId === subscription.id && isPendingActorInput(input))
+                        .map((input) => input.id),
+                },
+            })),
+        ];
+    };
+
+const stateChange = (state: RunState, context: CommandContext, pluginId: string, scope: PluginStateScope, raw: JsonValue): UncommittedEvent => {
+    assertJsonValue(raw, "state");
+    const value: JsonValue = JSON.parse(JSON.stringify(raw));
+    const previous = state.pluginStates.get(pluginStateKey(pluginId, scope));
+    const replacement = event(context, { type: "plugin.state-replaced", payload: { pluginId, scope, state: value } });
+    if (previous) {
+        const changes = jsonChanges(previous.state, value);
+        const patch = event(context, { type: "plugin.state-patched", payload: { pluginId, scope, changes } });
+        if (Buffer.byteLength(JSON.stringify(patch)) < Buffer.byteLength(JSON.stringify(replacement)))
+            return patch;
+    }
+    return replacement;
+};
+
+export const replacePluginState =
+    (input: { pluginId: string; scope: PluginStateScope; state: JsonValue }): Decision =>
+    (state, context) => {
+        const caller = actorOf(state, context);
+        const pluginId = clean(input.pluginId, "pluginId");
+
+        if (input.scope.kind === "actor") {
+            actorById(state, input.scope.actorId);
+
+            if (caller.id !== input.scope.actorId && caller.id !== state.ownerId)
+                throw new DomainError("plugin-state-access-denied", "An actor may only replace its own plugin state.", 403);
+        }
+
+        if (caller.kind !== "human")
+            assertCapability(caller, "plugin.state.write", { kind: "run" });
+
+        return [stateChange(state, context, pluginId, input.scope, input.state)];
+    };
+
+export const replaceActorState = (actorId: string, value: JsonValue): Decision => (state, context) => {
+    const caller = actorOf(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);
+
+    return [stateChange(state, context, actorStatePluginId, { kind: "actor", actorId }, value)];
+};

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

@@ -0,0 +1,28 @@
+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";
+
+export const publishArtifact =
+    (
+        input: { title: string; mediaType: string; previousVersionId: string | null },
+        stored: StoredArtifactContent,
+    ): Decision =>
+    (state, context, services) => {
+        const actor = actorOf(state, context);
+        assertCapability(actor, "artifact.publish", { kind: "run" });
+
+        if (input.previousVersionId)
+            assertArtifactRead(state, actor, artifactOf(state, input.previousVersionId));
+
+        const artifact: Omit<Artifact, "createdBy" | "createdAt"> = {
+            id: services.newId("artifact"),
+            title: clean(input.title, "title"),
+            mediaType: clean(input.mediaType, "mediaType"),
+            hash: stored.hash,
+            size: stored.size,
+            previousVersionId: input.previousVersionId,
+        };
+
+        return [event(context, { type: "artifact.published", payload: { artifact } })];
+    };

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

@@ -0,0 +1,79 @@
+import { isActiveActor } from "../../domain/projection.ts";
+import { event, type Decision } from "../command.ts";
+import { DomainError } from "../domain-error.ts";
+import {
+    actorById,
+    actorOf,
+    addressedActorOf,
+    artifactOf,
+    assertArtifactRead,
+    assertCapability,
+    clean,
+    executableActorOf,
+} from "../guards.ts";
+
+export type EnqueueInput = {
+    actorId: string;
+    artifactIds?: readonly string[];
+    presentation?: "background";
+} & (
+    | { content: string; sourceEventIds?: readonly string[]; subscriptionId?: null }
+    | { content?: never; sourceEventIds: readonly [string]; subscriptionId: string }
+);
+
+export const enqueueInput =
+    (input: EnqueueInput): Decision =>
+    (state, context, services) => {
+        const target = executableActorOf(state, addressedActorOf(state, input.actorId).id);
+        const subscriptionId = input.subscriptionId ?? null;
+        const caller = subscriptionId ? actorById(state, context.actorId) : actorOf(state, context);
+
+        if (!isActiveActor(target))
+            throw new DomainError("actor-inactive", `${target.displayName} is stopped.`);
+
+        if (subscriptionId) {
+            const subscription = state.subscriptions.get(subscriptionId);
+
+            if (!subscription || subscription.status !== "active")
+                throw new DomainError("subscription-inactive", `Subscription ${subscriptionId} is not active.`, 409);
+
+            if (subscription.subscriberId !== caller.id || target.id !== caller.id)
+                throw new DomainError("subscription-input-denied", `Subscription ${subscriptionId} cannot enqueue this input.`, 403);
+        } else if (caller.id !== state.ownerId) {
+            assertCapability(caller, "actor.input", { kind: "run" });
+        }
+
+        const artifactIds = [...new Set(input.artifactIds ?? [])];
+
+        for (const artifactId of artifactIds)
+            assertArtifactRead(state, caller, artifactOf(state, artifactId));
+
+        const [firstSourceEventId, ...furtherSourceEventIds] =
+            [...new Set((input.sourceEventIds ?? []).map((id) => clean(id, "sourceEventId")))];
+        const base = {
+            inputId: services.newId("input"),
+            actorId: target.id,
+            artifactIds,
+            ...(input.presentation !== undefined ? { presentation: input.presentation } : {}),
+        };
+
+        if (subscriptionId && firstSourceEventId === undefined)
+            throw new DomainError("subscription-source-required", `Subscription ${subscriptionId} input has no source event.`, 400);
+
+        if (subscriptionId && furtherSourceEventIds.length > 0)
+            throw new DomainError("subscription-source-invalid", `Subscription ${subscriptionId} input must have exactly one source event.`, 400);
+
+        return [event(context, {
+            type: "actor.input.enqueued",
+            payload: subscriptionId && firstSourceEventId !== undefined
+                ? { ...base, subscriptionId, sourceEventIds: [firstSourceEventId] }
+                : {
+                    ...base,
+                    content: artifactIds.length > 0 ? input.content!.trim() : clean(input.content!, "content"),
+                    subscriptionId: null,
+                    sourceEventIds: firstSourceEventId === undefined
+                        ? []
+                        : [firstSourceEventId, ...furtherSourceEventIds],
+                },
+        })];
+    };

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

@@ -0,0 +1,135 @@
+import type { JournalEvent } from "../../domain/events.ts";
+import { 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";
+
+export const createSubscription =
+    (input: {
+        subscriberId: string;
+        sourceActorIds?: readonly string[] | null;
+        sourceActorKinds?: readonly ("human" | "agent" | "script")[] | null;
+        eventTypes: readonly ObservableEventType[];
+        includeSelf?: boolean;
+    }): Decision =>
+    (state, context, services) => {
+        const caller = actorOf(state, context);
+        const subscriber = executableActorOf(state, input.subscriberId);
+
+        if (caller.id !== state.ownerId) {
+            assertCapability(caller, "event.subscribe", { kind: "run" });
+
+            if (caller.id !== subscriber.id)
+                throw new DomainError("subscription-access-denied", "An actor may only subscribe itself.", 403);
+        }
+
+        if (!isActiveActor(subscriber))
+            throw new DomainError("actor-inactive", `Actor ${subscriber.id} is stopped.`, 409);
+
+        const eventTypes = [...new Set(input.eventTypes)];
+
+        if (eventTypes.length === 0)
+            throw new DomainError("subscription-events-empty", "A subscription needs at least one event type.", 400);
+
+        const denied = eventTypes.filter((type) => !isObservableEventType(type));
+
+        if (denied.length > 0)
+            throw new DomainError(
+                "subscription-event-denied",
+                `The subscription contains a control or unknown event type: ${denied.join(", ")}. `
+                + `Subscribable event types: ${observableEventTypes.join(", ")}.`,
+                400,
+            );
+
+        const sourceActorIds = input.sourceActorIds === null || input.sourceActorIds === undefined
+            ? null
+            : [...new Set(input.sourceActorIds.map((id) => actorById(state, id).id))];
+        const sourceActorKinds = input.sourceActorKinds === null || input.sourceActorKinds === undefined
+            ? null
+            : [...new Set(input.sourceActorKinds)];
+
+        return [event(context, {
+            type: "subscription.created",
+            payload: {
+                subscriptionId: services.newId("subscription"),
+                subscriberId: subscriber.id,
+                sourceActorIds,
+                sourceActorKinds,
+                eventTypes,
+                includeSelf: input.includeSelf === true,
+            },
+        })];
+    };
+
+export const removeSubscription =
+    (subscriptionId: string, reason: string): Decision =>
+    (state, context) => {
+        const caller = actorOf(state, context);
+        const subscription = state.subscriptions.get(subscriptionId);
+
+        if (!subscription)
+            throw new DomainError("subscription-not-found", `Subscription ${subscriptionId} does not exist.`, 404);
+
+        if (subscription.status !== "active")
+            throw new DomainError("subscription-inactive", `Subscription ${subscriptionId} is ${subscription.status}.`, 409);
+
+        if (caller.id !== state.ownerId && caller.id !== subscription.subscriberId && caller.id !== subscription.createdBy)
+            throw new DomainError("subscription-access-denied", `Actor ${caller.id} may not remove ${subscriptionId}.`, 403);
+
+        if (caller.id !== state.ownerId)
+            assertCapability(caller, "event.subscribe", { kind: "run" });
+
+        const discardedInputIds = [...state.inputs.values()]
+            .filter((input) => input.subscriptionId === subscriptionId && isPendingActorInput(input))
+            .map((input) => input.id);
+
+        return [event(context, {
+            type: "subscription.removed",
+            payload: { subscriptionId, reason: clean(reason, "reason"), discardedInputIds },
+        })];
+    };
+
+export const failSubscription =
+    (subscriptionId: string, sourceEventId: string, reason: string): Decision =>
+    (state, context) => {
+        const subscription = state.subscriptions.get(subscriptionId);
+
+        if (!subscription)
+            throw new DomainError("subscription-not-found", `Subscription ${subscriptionId} does not exist.`, 404);
+
+        actorById(state, context.actorId);
+
+        return [event(context, {
+            type: "subscription.failed",
+            payload: {
+                subscriptionId,
+                sourceEventId: clean(sourceEventId, "sourceEventId"),
+                reason: clean(reason, "reason"),
+            },
+        })];
+    };
+
+export const matchesSubscription = (state: RunState, subscription: EventSubscription, source: JournalEvent) => {
+    if (subscription.status !== "active" || !isObservableEventType(source.type))
+        return false;
+
+    if (!subscription.eventTypes.includes(source.type))
+        return false;
+
+    if (!subscription.includeSelf && source.actorId === subscription.subscriberId)
+        return false;
+
+    if (subscription.sourceActorIds && !subscription.sourceActorIds.includes(source.actorId))
+        return false;
+
+    if (subscription.sourceActorKinds) {
+        const sourceActor = state.actors.get(source.actorId);
+
+        if (!sourceActor || !subscription.sourceActorKinds.includes(sourceActor.kind))
+            return false;
+    }
+
+    return true;
+};