@schlenkr/ragents 0.1.0

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

@@ -0,0 +1,236 @@
+import type {
+    ActionId,
+    ActionInput,
+    ActionKind,
+    ActionStatus,
+    ActorId,
+    ActorKind,
+    AgentExecution,
+    Artifact,
+    CapabilityGrant,
+    InputId,
+    ObservableEventType,
+    PluginStateScope,
+    RunId,
+    SubscriptionId,
+    TurnId,
+    TurnUsage,
+} from "./model.ts";
+import type { JsonChange, JsonValue } from "./json.ts";
+
+export type EventPayloads = {
+    "run.created": {
+        title: string;
+        owner: {
+            id: ActorId;
+            handle: string;
+            displayName: string;
+            grants: CapabilityGrant[];
+        };
+    };
+    "run.forked": {
+        sourceRunId: RunId;
+        sourceSequence: number;
+    };
+    "run.primary-actor-selected": {
+        actorId: ActorId;
+    };
+    "run.title-changed": {
+        title: string;
+    };
+    "agent.spawned": {
+        agentId: ActorId;
+        handle: string;
+        displayName: string;
+        prompt: string;
+        execution: AgentExecution;
+        grants: CapabilityGrant[];
+        toolNames: string[] | null;
+        forkOf?: ActorId;
+    };
+    "script.created": {
+        scriptId: ActorId;
+        handle: string;
+        displayName: string;
+        execution: AgentExecution;
+        grants: CapabilityGrant[];
+        toolNames: string[] | null;
+    };
+    "actor.input.enqueued": {
+        inputId: InputId;
+        actorId: ActorId;
+        artifactIds: string[];
+        presentation?: "background";
+    } & (
+        | { subscriptionId: null; sourceEventIds: string[]; content: string }
+        | { subscriptionId: SubscriptionId; sourceEventIds: [string]; content?: never }
+    );
+    "turn.started": {
+        turnId: TurnId;
+        inputId: InputId;
+    };
+    "turn.finished": {
+        turnId: TurnId;
+        usage?: TurnUsage;
+    } & ({ outcome: "completed" } | { outcome: "failed"; reason: string });
+    "turn.interrupted": {
+        turnId: TurnId;
+        reason: string;
+    };
+    "model.output.completed": {
+        turnId: TurnId;
+        text: string;
+    };
+    "model.reasoning.completed": {
+        turnId: TurnId;
+        text: string;
+    };
+    "runtime.output.recorded": {
+        turnId: TurnId;
+        text: string;
+    };
+    "tool.call.started": {
+        turnId: TurnId;
+        toolCallId: string;
+        name: string;
+        input: JsonValue;
+        ignoredFields?: string[];
+    };
+    "tool.call.source": {
+        turnId: TurnId;
+        toolCallId: string;
+        code: string;
+        path: string | null;
+    };
+    "tool.call.completed": {
+        turnId: TurnId;
+        toolCallId: string;
+        name: string;
+        output: JsonValue;
+    };
+    "tool.call.failed": {
+        turnId: TurnId;
+        toolCallId: string;
+        name: string;
+        error: string;
+    };
+    "actor.tools.opened": {
+        actorId: ActorId;
+        toolNames: string[];
+    };
+    "actor.stopped": {
+        actorId: ActorId;
+        reason: string;
+    };
+    "actor.restarted": {
+        actorId: ActorId;
+        reason: string;
+    };
+    "subscription.created": {
+        subscriptionId: SubscriptionId;
+        subscriberId: ActorId;
+        sourceActorIds: ActorId[] | null;
+        sourceActorKinds: ActorKind[] | null;
+        eventTypes: ObservableEventType[];
+        includeSelf: boolean;
+    };
+    "subscription.removed": {
+        subscriptionId: SubscriptionId;
+        reason: string;
+        discardedInputIds?: InputId[];
+    };
+    "subscription.failed": {
+        subscriptionId: SubscriptionId;
+        sourceEventId: string;
+        reason: string;
+    };
+    "plugin.state-replaced": {
+        pluginId: string;
+        scope: PluginStateScope;
+        state: JsonValue;
+    };
+    "plugin.state-patched": {
+        pluginId: string;
+        scope: PluginStateScope;
+        changes: JsonChange[];
+    };
+    "action.proposed": {
+        actionId: ActionId;
+        title: string;
+        description: string | null;
+        parameters: Record<string, string>;
+        input: ActionInput | null;
+    } & (
+        | { kind: "action" }
+        | { kind: "question"; question: { options: string[]; multi: boolean } | null }
+    );
+    "action.resolved": {
+        actionId: ActionId;
+        decision: Exclude<ActionStatus, "pending">;
+        response: string | null;
+    };
+    "artifact.published": {
+        artifact: Omit<Artifact, "createdBy" | "createdAt">;
+    };
+};
+
+export type EventType = keyof EventPayloads;
+
+export const eventTypeMap: Record<EventType, true> = {
+    "run.created": true,
+    "run.forked": true,
+    "run.primary-actor-selected": true,
+    "run.title-changed": true,
+    "agent.spawned": true,
+    "script.created": true,
+    "actor.input.enqueued": true,
+    "turn.started": true,
+    "turn.finished": true,
+    "turn.interrupted": true,
+    "model.output.completed": true,
+    "model.reasoning.completed": true,
+    "runtime.output.recorded": true,
+    "tool.call.started": true,
+    "tool.call.source": true,
+    "tool.call.completed": true,
+    "tool.call.failed": true,
+    "actor.tools.opened": true,
+    "actor.stopped": true,
+    "actor.restarted": true,
+    "subscription.created": true,
+    "subscription.removed": true,
+    "subscription.failed": true,
+    "plugin.state-replaced": true,
+    "plugin.state-patched": true,
+    "action.proposed": true,
+    "action.resolved": true,
+    "artifact.published": true,
+};
+
+export const isEventType = (value: unknown): value is EventType =>
+    typeof value === "string" && Object.hasOwn(eventTypeMap, value);
+
+type EventData = {
+    [Type in EventType]: {
+        type: Type;
+        payload: EventPayloads[Type];
+    };
+}[EventType];
+
+export type UncommittedEvent = EventData & {
+    actorId: ActorId;
+    correlationId: string | null;
+    causationId: string | null;
+};
+
+export type JournalEvent = EventData & {
+    eventId: string;
+    runId: RunId;
+    sequence: number;
+    schemaVersion: 3;
+    occurredAt: string;
+    actorId: ActorId;
+    commandId: string;
+    correlationId: string | null;
+    causationId: string | null;
+};

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

@@ -0,0 +1,77 @@
+import { assertJsonValue, type JsonValue, type JsonChange, type JsonPath } from "./json.ts";
+
+const object = (value: JsonValue): value is { [key: string]: JsonValue | undefined } =>
+    value !== null && typeof value === "object" && !Array.isArray(value);
+
+export function jsonChanges(before: JsonValue, after: JsonValue, path: JsonPath = []): JsonChange[] {
+    if (before === after) return [];
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const changes: JsonChange[] = [];
+        for (let index = 0; index < after.length; index++)
+            changes.push(...(index < before.length
+                ? jsonChanges(before[index]!, after[index]!, [...path, index])
+                : [{ op: "set" as const, path: [...path, index], value: after[index]! }]));
+        for (let index = before.length - 1; index >= after.length; index--)
+            changes.push({ op: "remove", path: [...path, index] });
+        return changes;
+    }
+    if (object(before) && object(after)) {
+        const changes: JsonChange[] = [];
+        for (const key of Object.keys(before))
+            if (!Object.hasOwn(after, key)) changes.push({ op: "remove", path: [...path, key] });
+        for (const key of Object.keys(after))
+            changes.push(...(Object.hasOwn(before, key)
+                ? jsonChanges(before[key]!, after[key]!, [...path, key])
+                : [{ op: "set" as const, path: [...path, key], value: after[key]! }]));
+        return changes;
+    }
+    return [{ op: "set", path, value: after }];
+}
+
+export function assertJsonChanges(value: unknown): asserts value is JsonChange[] {
+    assertJsonValue(value, "changes");
+    if (!Array.isArray(value)) throw new Error("JSON changes must be an array.");
+    for (const change of value) {
+        if (!change || typeof change !== "object" || Array.isArray(change)
+            || (change.op !== "set" && change.op !== "remove")
+            || !Array.isArray(change.path)
+            || change.path.some((part) => typeof part !== "string" && !(typeof part === "number" && Number.isSafeInteger(part) && part >= 0))
+            || Object.keys(change).length !== (change.op === "set" ? 3 : 2)
+            || !Object.hasOwn(change, "op") || !Object.hasOwn(change, "path")
+            || (change.op === "set" && (!Object.hasOwn(change, "value") || change.value === undefined))
+            || (change.op === "remove" && change.path.length === 0))
+            throw new Error("Invalid JSON state change.");
+    }
+}
+
+function apply(value: JsonValue, change: JsonChange, depth: number): JsonValue {
+    if (depth === change.path.length) {
+        if (change.op !== "set") throw new Error("Cannot remove the JSON state root.");
+        return change.value;
+    }
+    const key = change.path[depth]!;
+    const last = depth === change.path.length - 1;
+    if (Array.isArray(value)) {
+        if (typeof key !== "number" || !Number.isSafeInteger(key) || key < 0
+            || key > value.length || (key === value.length && (!last || change.op !== "set")))
+            throw new Error("JSON state change has an invalid array index.");
+        const result = [...value];
+        if (last && change.op === "remove") result.splice(key, 1);
+        else result[key] = last ? (change as Extract<JsonChange, { op: "set" }>).value : apply(value[key]!, change, depth + 1);
+        return result;
+    }
+    if (!object(value) || typeof key !== "string"
+        || ((!last || change.op === "remove") && !Object.hasOwn(value, key)))
+        throw new Error("JSON state change has an invalid object path.");
+    const result = { ...value };
+    if (last && change.op === "remove") delete result[key];
+    else Object.defineProperty(result, key, {
+        value: last ? (change as Extract<JsonChange, { op: "set" }>).value : apply(value[key]!, change, depth + 1),
+        enumerable: true, writable: true, configurable: true,
+    });
+    return result;
+}
+
+export function applyJsonChanges(state: JsonValue, changes: readonly JsonChange[]): JsonValue {
+    return changes.reduce((value, change) => apply(value, change, 0), state);
+}

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

@@ -0,0 +1,86 @@
+export type JsonValue =
+    | null
+    | string
+    | number
+    | boolean
+    | JsonValue[]
+    | { [key: string]: JsonValue | undefined };
+
+export type JsonPath = (string | number)[];
+export type JsonChange =
+    | { op: "set"; path: JsonPath; value: JsonValue }
+    | { op: "remove"; path: JsonPath };
+
+const fail: (path: string, message: string) => never = (path, message) => {
+    throw new TypeError(`${path} ${message}.`);
+};
+
+const validate = (value: unknown, path: string, ancestors: WeakSet<object>): void => {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || Object.is(value, -0))
+            fail(path, "must be a finite JSON number");
+
+        return;
+    }
+
+    if (typeof value !== "object")
+        fail(path, "must be a JSON value");
+
+    if (ancestors.has(value))
+        fail(path, "must not contain a cycle");
+
+    ancestors.add(value);
+
+    try {
+        if (Array.isArray(value)) {
+            if (Object.getPrototypeOf(value) !== Array.prototype)
+                fail(path, "must be a plain JSON array");
+
+            const keys = Reflect.ownKeys(value);
+
+            if (keys.length !== value.length + 1 || !keys.includes("length"))
+                fail(path, "must not contain holes or named properties");
+
+            for (let index = 0; index < value.length; index++) {
+                const key = String(index);
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+
+                if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+                    fail(`${path}[${index}]`, "must be an own JSON value");
+
+                validate(descriptor.value, `${path}[${index}]`, ancestors);
+            }
+
+            return;
+        }
+
+        const prototype = Object.getPrototypeOf(value);
+
+        if (prototype !== Object.prototype && prototype !== null)
+            fail(path, "must be a plain JSON object");
+
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== "string")
+                fail(path, "must not contain symbol properties");
+
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+
+            if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+                fail(`${path}.${key}`, "must be an enumerable JSON value");
+
+            if (descriptor.value === undefined)
+                continue;
+
+            validate(descriptor.value, `${path}.${key}`, ancestors);
+        }
+    } finally {
+        ancestors.delete(value);
+    }
+};
+
+export const assertJsonValue: (value: unknown, path?: string) => asserts value is JsonValue = (value, path = "value") => {
+    validate(value, path, new WeakSet<object>());
+};

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

@@ -0,0 +1,267 @@
+import type { AgentExecution } from "./driver.ts";
+import type { JsonValue } from "./json.ts";
+import type { CapabilityName, ObservableEventType } from "./vocabulary.ts";
+
+export type { CapabilityName, ObservableEventType };
+export type { AgentDriverKind, AgentDriverRef, AgentExecution, ModelSelection } from "./driver.ts";
+
+export type ActorId = string;
+export type InputId = string;
+export type SubscriptionId = string;
+export type RunId = string;
+export type TurnId = string;
+export type ArtifactId = string;
+export type ActionId = string;
+
+export type CapabilityScope =
+    | { kind: "run" }
+    | { kind: "workspace"; path: string };
+
+export type CapabilityGrant = {
+    capability: CapabilityName;
+    scope: CapabilityScope;
+    delegable: boolean;
+    usable?: boolean;
+};
+
+export type ActorKind = "human" | "agent" | "script";
+
+type ActorBase = {
+    id: ActorId;
+    handle: string;
+    displayName: string;
+    grants: readonly CapabilityGrant[];
+    createdAt: string;
+};
+
+export type HumanActor = ActorBase & {
+    kind: "human";
+};
+
+export type ActorLifecycle =
+    | { kind: "idle"; since: string }
+    | { kind: "running"; turnId: TurnId; inputId: InputId; startedAt: string }
+    | { kind: "stopped"; stoppedAt: string; reason: string };
+
+export type TurnUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costUsd: number;
+};
+
+type ExecutableActorBase = ActorBase & {
+    createdBy: ActorId;
+    execution: AgentExecution;
+    lifecycle: ActorLifecycle;
+    usage: TurnUsage;
+    toolNames: readonly string[] | null;
+    openedToolNames: readonly string[];
+};
+
+export type AgentActor = ExecutableActorBase & {
+    kind: "agent";
+    prompt: string;
+    forkOf: ActorId | null;
+};
+
+export const actorStatePluginId = "ragents.actor-state";
+
+export type ScriptActor = ExecutableActorBase & { kind: "script" };
+
+export type ExecutableActor = AgentActor | ScriptActor;
+export type Actor = HumanActor | ExecutableActor;
+
+export type ActorInputLifecycle =
+    | { kind: "pending" }
+    | { kind: "claimed"; turnId: TurnId }
+    | { kind: "discarded"; at: string; reason: string };
+
+export type ActorInput = {
+    id: InputId;
+    actorId: ActorId;
+    content: string;
+    presentation?: "background";
+    artifactIds: readonly ArtifactId[];
+    enqueuedBy: ActorId;
+    enqueuedAt: string;
+    sequence: number;
+    lifecycle: ActorInputLifecycle;
+} & (
+    | { subscriptionId: null; sourceEventIds: readonly string[] }
+    | { subscriptionId: SubscriptionId; sourceEventIds: readonly [string, ...string[]] }
+);
+
+export const isPendingActorInput = (input: ActorInput) => input.lifecycle.kind === "pending";
+
+export type TurnStatus = "running" | "completed" | "failed" | "interrupted";
+
+/** Der volle Text eines model.output.completed; nie gekürzt, `sequence` ist die Journal-Reihenfolge. */
+export type TurnOutput = {
+    text: string;
+    sequence: number;
+    occurredAt: string;
+};
+
+export type TurnToolCall = {
+    id: string;
+    name: string;
+    status: "running" | "completed" | "failed" | "interrupted";
+    startedAt: string;
+    finishedAt: string | null;
+};
+
+export type Turn = {
+    id: TurnId;
+    actorId: ActorId;
+    inputId: InputId;
+    status: TurnStatus;
+    startedAt: string;
+    finishedAt: string | null;
+    reason: string | null;
+    usage: TurnUsage;
+    outputs: readonly TurnOutput[];
+    toolCalls: readonly TurnToolCall[];
+};
+
+export type SubscriptionStatus = "active" | "removed" | "failed";
+
+export type EventSubscription = {
+    id: SubscriptionId;
+    subscriberId: ActorId;
+    sourceActorIds: readonly ActorId[] | null;
+    sourceActorKinds: readonly ActorKind[] | null;
+    eventTypes: readonly ObservableEventType[];
+    includeSelf: boolean;
+    createdBy: ActorId;
+    createdAt: string;
+    createdSequence: number;
+} & (
+    | { status: "active" }
+    | { status: "removed"; endedAt: string; reason: string }
+    | { status: "failed"; endedAt: string; reason: string; sourceEventId: string }
+);
+
+export type PluginStateScope =
+    | { kind: "run" }
+    | { kind: "actor"; actorId: ActorId };
+
+export type PluginState = {
+    pluginId: string;
+    scope: PluginStateScope;
+    state: JsonValue;
+    updatedAt: string;
+};
+
+export const pluginStateKey = (pluginId: string, scope: PluginStateScope): string =>
+    `${pluginId}\0${scope.kind}\0${scope.kind === "actor" ? scope.actorId : ""}`;
+
+export type ActionInput = {
+    label: string;
+    placeholder: string | null;
+    required: boolean;
+};
+
+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;
+    title: string;
+    description: string | null;
+    parameters: Readonly<Record<string, string>>;
+    input: ActionInput | null;
+    status: ActionStatus;
+    proposedAt: string;
+    resolvedAt: string | null;
+    resolvedBy: ActorId | null;
+    response: string | null;
+} & (
+    | { kind: "action" }
+    | { kind: "question"; question: ActionQuestion | null }
+);
+
+export type Artifact = {
+    id: ArtifactId;
+    title: string;
+    mediaType: string;
+    hash: string;
+    size: number;
+    previousVersionId: ArtifactId | null;
+    createdBy: ActorId;
+    createdAt: string;
+};
+
+export type RunState = {
+    id: RunId;
+    revision: number;
+    title: string;
+    ownerId: ActorId;
+    primaryActorId: ActorId | null;
+    createdAt: string;
+    forkedFrom: { runId: RunId; sequence: number } | null;
+    actors: ReadonlyMap<ActorId, Actor>;
+    inputs: ReadonlyMap<InputId, ActorInput>;
+    turns: ReadonlyMap<TurnId, Turn>;
+    subscriptions: ReadonlyMap<SubscriptionId, EventSubscription>;
+    pluginStates: ReadonlyMap<string, PluginState>;
+    actions: ReadonlyMap<ActionId, Action>;
+    artifacts: ReadonlyMap<ArtifactId, Artifact>;
+};
+
+type Collections = "actors" | "inputs" | "turns" | "subscriptions" | "pluginStates" | "actions" | "artifacts";
+
+export type RunView = Omit<RunState, Collections> & {
+    actors: Actor[];
+    inputs: ActorInput[];
+    turns: Turn[];
+    subscriptions: EventSubscription[];
+    pluginStates: PluginState[];
+    actions: Action[];
+    artifacts: Artifact[];
+};
+
+export const emptyUsage = (): TurnUsage => ({
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    costUsd: 0,
+});
+
+const checkedTokenTotal = (name: keyof Omit<TurnUsage, "costUsd">, left: number, right: number) => {
+    const total = left + right;
+    const valid = (value: number) => Number.isSafeInteger(value) && value >= 0;
+
+    if (!valid(left) || !valid(right) || !valid(total))
+        throw new Error(`Cumulative turn usage ${name} must be a non-negative safe integer.`);
+
+    return total;
+};
+
+const checkedCostTotal = (left: number, right: number) => {
+    const total = left + right;
+    const valid = (value: number) => Number.isFinite(value) && value >= 0 && !Object.is(value, -0);
+
+    if (!valid(left) || !valid(right) || !valid(total))
+        throw new Error("Cumulative turn usage costUsd must be a finite non-negative number.");
+
+    return total;
+};
+
+export const addUsage = (left: TurnUsage, right: TurnUsage): TurnUsage => ({
+    inputTokens: checkedTokenTotal("inputTokens", left.inputTokens, right.inputTokens),
+    outputTokens: checkedTokenTotal("outputTokens", left.outputTokens, right.outputTokens),
+    cacheReadTokens: checkedTokenTotal("cacheReadTokens", left.cacheReadTokens, right.cacheReadTokens),
+    cacheWriteTokens: checkedTokenTotal("cacheWriteTokens", left.cacheWriteTokens, right.cacheWriteTokens),
+    costUsd: checkedCostTotal(left.costUsd, right.costUsd),
+});
+
+export const isExecutableActor = (actor: Actor): actor is ExecutableActor => actor.kind !== "human";

package/packages/ragents/src/domain/plugin-state.ts

@@ -0,0 +1,33 @@
+import type { JournalEvent } from "./events.ts";
+import type { JsonValue } from "./json.ts";
+import { applyJsonChanges } from "./json-patch.ts";
+import { pluginStateKey } from "./model.ts";
+
+export type PluginStateEvent = Extract<JournalEvent, { type: "plugin.state-replaced" | "plugin.state-patched" }>;
+
+export class PluginStateProjection {
+    readonly #states = new Map<string, JsonValue>();
+
+    observe(event: JournalEvent): JsonValue | undefined {
+        if (event.type !== "plugin.state-replaced" && event.type !== "plugin.state-patched") return undefined;
+        const key = pluginStateKey(event.payload.pluginId, event.payload.scope);
+        if (event.type === "plugin.state-patched" && !this.#states.has(key))
+            throw new Error(`Plugin state ${event.payload.pluginId} must exist before it can be patched.`);
+        const state = event.type === "plugin.state-replaced"
+            ? event.payload.state : applyJsonChanges(this.#states.get(key)!, event.payload.changes);
+        this.#states.set(key, state);
+        return state;
+    }
+}
+
+export function pluginStateAt(events: readonly JournalEvent[], target: PluginStateEvent): JsonValue {
+    const projection = new PluginStateProjection();
+    const key = pluginStateKey(target.payload.pluginId, target.payload.scope);
+    for (const event of events) {
+        if ((event.type !== "plugin.state-replaced" && event.type !== "plugin.state-patched")
+            || pluginStateKey(event.payload.pluginId, event.payload.scope) !== key) continue;
+        const state = projection.observe(event)!;
+        if (event.eventId === target.eventId) return state;
+    }
+    throw new Error(`Plugin state event ${target.eventId} is missing.`);
+}