@schlenkr/ragents 0.1.0

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

@@ -0,0 +1,166 @@
+import type { JsonValue } from "../../domain/json.ts";
+import type { TurnUsage } from "../../domain/model.ts";
+import { event, type Decision } from "../command.ts";
+import { DomainError } from "../domain-error.ts";
+import { actorById, actorOf, assertSelf, clean, executableActorOf } from "../guards.ts";
+
+const runningTurn = (state: Parameters<Decision>[0], context: Parameters<Decision>[1], actorId: string, turnId: string) => {
+    assertSelf(context, actorId, "record activity");
+    const target = executableActorOf(state, actorId);
+
+    if (target.lifecycle.kind !== "running" || target.lifecycle.turnId !== turnId)
+        throw new DomainError("turn-mismatch", `Turn ${turnId} is not running for actor ${actorId}.`, 409);
+
+    actorOf(state, context);
+
+    return target;
+};
+
+export const startTurn =
+    (actorId: string, inputId: string): Decision =>
+    (state, context, services) => {
+        actorById(state, context.actorId);
+        assertSelf(context, actorId, "start a turn");
+        const target = executableActorOf(state, actorId);
+
+        if (target.lifecycle.kind !== "idle")
+            throw new DomainError("actor-not-idle", `Actor ${actorId} cannot start a turn while ${target.lifecycle.kind}.`, 409);
+
+        const input = state.inputs.get(inputId);
+
+        if (!input)
+            throw new DomainError("input-not-found", `Input ${inputId} does not exist.`, 404);
+
+        if (input.actorId !== actorId)
+            throw new DomainError("input-not-addressed", `Input ${inputId} is not addressed to actor ${actorId}.`, 400);
+
+        if (input.lifecycle.kind === "claimed")
+            throw new DomainError("input-consumed", `Input ${inputId} was already consumed by turn ${input.lifecycle.turnId}.`, 409);
+
+        if (input.lifecycle.kind === "discarded")
+            throw new DomainError("input-discarded", `Input ${inputId} was discarded.`, 409);
+
+        return [event(context, {
+            type: "turn.started",
+            payload: { turnId: services.newId("turn"), inputId },
+        })];
+    };
+
+const appendText = (
+    type: "model.output.completed" | "model.reasoning.completed" | "runtime.output.recorded",
+    actorId: string,
+    input: { turnId: string; text: string },
+): Decision => (state, context) => {
+    runningTurn(state, context, actorId, input.turnId);
+
+    return [event(context, { type, payload: { turnId: input.turnId, text: clean(input.text, "text") } })];
+};
+
+export const appendModelOutput = (actorId: string, input: { turnId: string; text: string }): Decision =>
+    appendText("model.output.completed", actorId, input);
+
+export const appendModelReasoning = (actorId: string, input: { turnId: string; text: string }): Decision =>
+    appendText("model.reasoning.completed", actorId, input);
+
+export const appendRuntimeOutput = (actorId: string, input: { turnId: string; text: string }): Decision =>
+    appendText("runtime.output.recorded", actorId, input);
+
+export const startToolCall =
+    (actorId: string, input: { turnId: string; toolCallId: string; name: string; input: JsonValue; ignoredFields?: string[] }): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+
+        return [event(context, {
+            type: "tool.call.started",
+            payload: {
+                turnId: input.turnId,
+                toolCallId: clean(input.toolCallId, "toolCallId"),
+                name: clean(input.name, "name"),
+                input: input.input,
+                ...(input.ignoredFields ? { ignoredFields: input.ignoredFields } : {}),
+            },
+        })];
+    };
+
+export const completeToolCall =
+    (actorId: string, input: { turnId: string; toolCallId: string; name: string; output: JsonValue }): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+
+        return [event(context, {
+            type: "tool.call.completed",
+            payload: {
+                turnId: input.turnId,
+                toolCallId: clean(input.toolCallId, "toolCallId"),
+                name: clean(input.name, "name"),
+                output: input.output,
+            },
+        })];
+    };
+
+export const recordToolCallSource =
+    (actorId: string, input: { turnId: string; toolCallId: string; code: string; path: string | null }): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+        const call = state.turns.get(input.turnId)?.toolCalls.find((entry) => entry.id === input.toolCallId);
+        if (!call)
+            throw new DomainError("tool-call-missing", `Tool call ${input.toolCallId} does not exist in turn ${input.turnId}.`, 404);
+        if (call.status !== "running")
+            throw new DomainError("tool-call-finished", `Tool call ${input.toolCallId} in turn ${input.turnId} is already ${call.status}.`, 409);
+        return [event(context, { type: "tool.call.source", payload: input })];
+    };
+
+const failureText = (error: string | null | undefined) => error?.trim() || "Fehler ohne Ursache";
+
+export const failToolCall =
+    (actorId: string, input: { turnId: string; toolCallId: string; name: string; error: string }): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+
+        return [event(context, {
+            type: "tool.call.failed",
+            payload: {
+                turnId: input.turnId,
+                toolCallId: clean(input.toolCallId, "toolCallId"),
+                name: clean(input.name, "name"),
+                error: failureText(input.error),
+            },
+        })];
+    };
+
+export const finishTurn =
+    (
+        actorId: string,
+        input: { turnId: string; usage?: TurnUsage }
+            & ({ outcome: "completed" } | { outcome: "failed"; reason: string }),
+    ): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+
+        const usage = input.usage ? { usage: input.usage } : {};
+
+        return [event(context, {
+            type: "turn.finished",
+            payload: input.outcome === "failed"
+                ? { turnId: input.turnId, outcome: input.outcome, reason: clean(input.reason, "reason"), ...usage }
+                : { turnId: input.turnId, outcome: input.outcome, ...usage },
+        })];
+    };
+
+export const interruptTurn =
+    (actorId: string, input: { turnId: string; reason: string }): Decision =>
+    (state, context) => {
+        const caller = actorById(state, context.actorId);
+        const target = executableActorOf(state, actorId);
+
+        if (caller.id !== actorId && caller.id !== state.ownerId)
+            throw new DomainError("turn-interrupt-denied", `Actor ${caller.id} may not interrupt ${actorId}.`, 403);
+
+        if (target.lifecycle.kind !== "running" || target.lifecycle.turnId !== input.turnId)
+            throw new DomainError("turn-mismatch", `Turn ${input.turnId} is not running for actor ${actorId}.`, 409);
+
+        return [event(context, {
+            type: "turn.interrupted",
+            payload: { turnId: input.turnId, reason: clean(input.reason, "reason") },
+        })];
+    };

package/packages/ragents/src/runtime/domain-error.ts

@@ -0,0 +1,10 @@
+export class DomainError extends Error {
+    readonly code: string;
+    readonly status: number;
+
+    constructor(code: string, message: string, status = 409) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}

package/packages/ragents/src/runtime/durable-fs.ts

@@ -0,0 +1,13 @@
+import { closeSync, fsyncSync, openSync } from "node:fs";
+
+export const errorCode = (error: unknown) => (error instanceof Error && "code" in error ? error.code : null);
+
+export const syncDirectory = (path: string) => {
+    const descriptor = openSync(path, "r");
+
+    try {
+        fsyncSync(descriptor);
+    } finally {
+        closeSync(descriptor);
+    }
+};

package/packages/ragents/src/runtime/failures.ts

@@ -0,0 +1,18 @@
+const failureLeaves = (failure: unknown): unknown[] => failure instanceof AggregateError && failure.errors.length > 0
+    ? failure.errors.flatMap(failureLeaves)
+    : [failure];
+
+export const throwFailures = (failures: readonly unknown[], message: string): void => {
+    const unique = [...new Set(failures.flatMap(failureLeaves))];
+
+    if (unique.length === 1)
+        throw unique[0];
+
+    if (unique.length > 1)
+        throw new AggregateError(unique, message);
+};
+
+export const throwRejected = (results: readonly PromiseSettledResult<unknown>[], message: string): void =>
+    throwFailures(results
+        .filter((result): result is PromiseRejectedResult => result.status === "rejected")
+        .map((result) => result.reason), message);

package/packages/ragents/src/runtime/guards.ts

@@ -0,0 +1,196 @@
+import { resolve } from "node:path";
+
+import type {
+    Actor,
+    AgentActor,
+    Artifact,
+    CapabilityGrant,
+    CapabilityName,
+    CapabilityScope,
+    ExecutableActor,
+    RunState,
+} from "../domain/model.ts";
+import { isActiveActor } from "../domain/projection.ts";
+import { DomainError } from "./domain-error.ts";
+
+export const clean = (value: string, name: string) => {
+    const result = value.trim();
+
+    if (!result)
+        throw new DomainError("invalid-value", `${name} must not be empty.`, 400);
+
+    return result;
+};
+
+export const optionalClean = (value: string | null | undefined, name: string) => {
+    if (value === null || value === undefined)
+        return null;
+
+    const result = value.trim();
+
+    return result ? clean(result, name) : null;
+};
+
+export const handleOf = (value: string) => {
+    const result = value.trim().replace(/^@/, "").normalize("NFC").toLowerCase();
+
+    if (!/^[\p{L}\p{N}][\p{L}\p{N}._-]*$/u.test(result))
+        throw new DomainError("invalid-handle", "A handle may contain letters, digits, dot, dash, and underscore.", 400);
+
+    return result;
+};
+
+export const uniqueHandleOf = (state: RunState, handle: string): string => {
+    const taken = new Set([...state.actors.values()].map((entry) => entry.handle));
+
+    if (!taken.has(handle))
+        return handle;
+
+    for (let counter = 1; ; counter += 1) {
+        const candidate = `${handle}-${counter}`;
+
+        if (!taken.has(candidate))
+            return candidate;
+    }
+};
+
+export const actorById = (state: RunState, actorId: string): Actor => {
+    const found = state.actors.get(actorId);
+
+    if (!found)
+        throw new DomainError("actor-not-found", `Actor ${actorId} does not exist.`, 404);
+
+    return found;
+};
+
+export const executableActorOf = (state: RunState, actorId: string): ExecutableActor => {
+    const found = actorById(state, actorId);
+
+    if (found.kind === "human")
+        throw new DomainError("actor-not-executable", `Actor ${actorId} is a human and takes no turns.`, 404);
+
+    return found;
+};
+
+export const agentActorOf = (state: RunState, agentId: string): AgentActor => {
+    const found = actorById(state, agentId);
+
+    if (found.kind !== "agent")
+        throw new DomainError("agent-not-found", `Actor ${agentId} is not an agent.`, 404);
+
+    return found;
+};
+
+export const artifactOf = (state: RunState, artifactId: string): Artifact => {
+    const found = state.artifacts.get(artifactId);
+
+    if (!found)
+        throw new DomainError("artifact-not-found", `Artifact ${artifactId} does not exist.`, 404);
+
+    return found;
+};
+
+export const addressedActorOf = (state: RunState, reference: string): Actor => {
+    const direct = state.actors.get(reference);
+
+    if (direct)
+        return direct;
+
+    const wanted = reference.trim().replace(/^@/, "").normalize("NFC").toLowerCase();
+    const sharing = [...state.actors.values()].filter((entry) => entry.handle === wanted);
+    const byHandle = sharing.find(isActiveActor) ?? sharing.at(-1);
+
+    if (!byHandle)
+        throw new DomainError("actor-not-found", `Actor ${reference} does not exist.`, 404);
+
+    return byHandle;
+};
+
+export const assertActorCanCommand = (actor: Actor, turnId: string | undefined) => {
+    if (actor.kind === "human")
+        return;
+
+    if (actor.lifecycle.kind !== "running")
+        throw new DomainError(
+            "actor-not-running",
+            `Actor ${actor.id} cannot issue commands while ${actor.lifecycle.kind}.`,
+            409,
+        );
+
+    if (!turnId || actor.lifecycle.turnId !== turnId)
+        throw new DomainError("turn-mismatch", `Turn ${turnId ?? "<missing>"} is not running for actor ${actor.id}.`, 409);
+};
+
+export const actorOf = (state: RunState, context: { actorId: string; turnId?: string }): Actor => {
+    const actor = actorById(state, context.actorId);
+    assertActorCanCommand(actor, context.turnId);
+
+    return actor;
+};
+
+export const isActiveCommandActor = (state: RunState, actor: Actor) => isActiveActor(actorById(state, actor.id));
+
+export const scopeCovers = (parent: CapabilityScope, child: CapabilityScope) => {
+    if (parent.kind === "run")
+        return true;
+
+    if (parent.kind === "workspace" && child.kind === "workspace") {
+        const parentPath = resolve(parent.path);
+        const childPath = resolve(child.path);
+        const root = parentPath.endsWith("/") ? parentPath : `${parentPath}/`;
+
+        return childPath === parentPath || childPath.startsWith(root);
+    }
+
+    return false;
+};
+
+const matchingGrants = (actor: Actor, capability: CapabilityName, scope: CapabilityScope) =>
+    actor.grants.filter((grant) => grant.capability === capability && scopeCovers(grant.scope, scope));
+
+export const hasCapability = (actor: Actor, capability: CapabilityName, scope: CapabilityScope) =>
+    matchingGrants(actor, capability, scope).some((grant) => grant.usable !== false);
+
+export const assertCapability = (actor: Actor, capability: CapabilityName, scope: CapabilityScope) => {
+    if (!hasCapability(actor, capability, scope))
+        throw new DomainError("capability-denied", `${actor.displayName} may not use ${capability} in this scope.`, 403);
+};
+
+export const assertDelegation = (actor: Actor, grants: readonly CapabilityGrant[]) => {
+    for (const grant of grants) {
+        if (!matchingGrants(actor, grant.capability, grant.scope).some((parent) => parent.delegable))
+            throw new DomainError("delegation-denied", `${actor.displayName} may not delegate ${grant.capability}.`, 403);
+    }
+};
+
+export const inheritedGrants = (
+    actor: Actor,
+    withoutCapabilities: readonly CapabilityName[] = [],
+): CapabilityGrant[] => {
+    const excluded = new Set(withoutCapabilities);
+
+    return actor.grants
+        .filter((grant) => grant.delegable && !excluded.has(grant.capability))
+        .map((grant) => ({
+            capability: grant.capability,
+            scope: grant.scope.kind === "run"
+                ? { kind: "run" as const }
+                : { kind: "workspace" as const, path: grant.scope.path },
+            delegable: true,
+        }));
+};
+
+export const assertArtifactRead = (state: RunState, actor: Actor, artifact: Artifact) => {
+    if (actor.id === state.ownerId
+        || actor.id === artifact.createdBy
+        || [...state.inputs.values()].some((input) =>
+            input.actorId === actor.id && input.artifactIds.includes(artifact.id)))
+        return;
+
+    throw new DomainError("artifact-read-denied", `${actor.displayName} may not read artifact ${artifact.id}.`, 403);
+};
+
+export const assertSelf = (context: { actorId: string }, actorId: string, action: string) => {
+    if (context.actorId !== actorId)
+        throw new DomainError("actor-identity-mismatch", `An actor may only ${action} for itself.`, 403);
+};

package/packages/ragents/src/runtime/journal-storage.ts

@@ -0,0 +1,228 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { journalEventOf } from "../domain/event-validation.ts";
+import { assertJsonValue } from "../domain/json.ts";
+import { isRunId } from "../domain/portable-id.ts";
+import { syncDirectory } from "./durable-fs.ts";
+import type { CommandRecord, JournalCommand } from "./journal.ts";
+
+export const journalStorageVersion = 4;
+export const journalPayloadThresholdBytes = 4096;
+
+type PayloadReference = { sha256: string; bytes: number };
+
+const objectOf = (value: unknown, location: string): Record<string, unknown> => {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${location} must be an object.`);
+
+    return value as Record<string, unknown>;
+};
+
+const exactKeys = (value: Record<string, unknown>, location: string, required: string[], optional: string[] = []) => {
+    for (const key of required) {
+        if (!Object.hasOwn(value, key))
+            throw new Error(`${location}.${key} is required.`);
+    }
+
+    for (const key of Object.keys(value)) {
+        if (!required.includes(key) && !optional.includes(key))
+            throw new Error(`${location}.${key} is not supported.`);
+    }
+};
+
+const commandOf = (value: unknown, location: string): JournalCommand => {
+    const command = objectOf(value, location);
+    const keys = ["id", "type", "actorId", "requestHash"];
+    exactKeys(command, location, keys);
+
+    for (const key of keys) {
+        if (typeof command[key] !== "string")
+            throw new Error(`${location}.${key} must be a string.`);
+    }
+
+    return value as JournalCommand;
+};
+
+const digest = (content: string | Buffer) => createHash("sha256").update(content).digest("hex");
+
+const readPayload = (reference: PayloadReference, directory: string, location: string) => {
+    const path = join(directory, "payloads", `${reference.sha256}.json`);
+    let content: Buffer;
+
+    try {
+        content = readFileSync(path);
+    } catch (error) {
+        throw new Error(`${location} cannot read journal payload ${path}.`, { cause: error });
+    }
+
+    if (content.length !== reference.bytes || digest(content) !== reference.sha256)
+        throw new Error(`${location} journal payload ${path} failed size or SHA-256 verification.`);
+
+    return content;
+};
+
+const persistPayload = (content: string, directory: string): PayloadReference => {
+    const reference = { sha256: digest(content), bytes: Buffer.byteLength(content, "utf8") };
+    const payloadDirectory = join(directory, "payloads");
+    const path = join(payloadDirectory, `${reference.sha256}.json`);
+
+    if (!existsSync(payloadDirectory))
+        mkdirSync(payloadDirectory);
+
+    syncDirectory(directory);
+
+    if (existsSync(path)) {
+        readPayload(reference, directory, "Existing payload");
+        syncDirectory(payloadDirectory);
+        return reference;
+    }
+
+    const temporaryPath = join(payloadDirectory, `.payload.${randomUUID()}.tmp`);
+    let descriptor: number | null = null;
+
+    try {
+        descriptor = openSync(temporaryPath, "wx", 0o600);
+        writeFileSync(descriptor, content, "utf8");
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = null;
+        renameSync(temporaryPath, path);
+        syncDirectory(payloadDirectory);
+    } finally {
+        if (descriptor !== null)
+            closeSync(descriptor);
+
+        if (existsSync(temporaryPath))
+            unlinkSync(temporaryPath);
+    }
+
+    return reference;
+};
+
+export const serializeJournalRecord = (record: CommandRecord, runDirectory: string): string => {
+    assertJsonValue(record, "Journal record");
+    exactKeys(objectOf(record, "Journal record"), "Journal record", ["formatVersion", "runId", "command", "events"]);
+
+    if (record.formatVersion !== 3 || !isRunId(record.runId) || record.events.length === 0)
+        throw new Error("Cannot serialize an invalid journal record.");
+
+    commandOf(record.command, "Journal command");
+    const occurredAt = record.events[0]!.occurredAt;
+
+    for (const event of record.events) {
+        journalEventOf(event, `Journal event ${event.eventId}`);
+
+        if (event.runId !== record.runId || event.commandId !== record.command.id
+            || event.actorId !== record.command.actorId || event.occurredAt !== occurredAt)
+            throw new Error(`Journal event ${event.eventId} does not match its command envelope.`);
+    }
+
+    const events = record.events.map((event) => {
+        const payload: Record<string, unknown> = Object.create(null);
+        const payloadRefs: Record<string, PayloadReference> = Object.create(null);
+
+        for (const [key, value] of Object.entries(event.payload)) {
+            const content = JSON.stringify(value);
+
+            if (Buffer.byteLength(content, "utf8") >= journalPayloadThresholdBytes)
+                payloadRefs[key] = persistPayload(content, runDirectory);
+            else
+                payload[key] = value;
+        }
+
+        return {
+            eventId: event.eventId,
+            sequence: event.sequence,
+            type: event.type,
+            correlationId: event.correlationId,
+            causationId: event.causationId,
+            payload,
+            ...(Object.keys(payloadRefs).length === 0 ? {} : { payloadRefs }),
+        };
+    });
+
+    return JSON.stringify({ formatVersion: journalStorageVersion, runId: record.runId, command: record.command, occurredAt, events });
+};
+
+export const parseJournalRecord = (line: string, runDirectory: string, location: string): CommandRecord => {
+    let parsed: unknown;
+
+    try {
+        parsed = JSON.parse(line);
+    } catch (error) {
+        throw new Error(`${location} is not valid JSON.`, { cause: error });
+    }
+
+    assertJsonValue(parsed, location);
+    const record = objectOf(parsed, location);
+
+    if (record.formatVersion !== journalStorageVersion)
+        throw new Error(`${location} has unsupported journal format version ${String(record.formatVersion)}.`);
+
+    exactKeys(record, location, ["formatVersion", "runId", "command", "occurredAt", "events"]);
+
+    if (!isRunId(record.runId))
+        throw new Error(`${location}.runId must be a run ID.`);
+
+    if (typeof record.occurredAt !== "string")
+        throw new Error(`${location}.occurredAt must be a string.`);
+
+    const command = commandOf(record.command, `${location}.command`);
+
+    if (!Array.isArray(record.events) || record.events.length === 0)
+        throw new Error(`${location}.events must be a non-empty array.`);
+
+    const events = record.events.map((value: unknown, index: number) => {
+        const eventLocation = `${location}, event ${index + 1}`;
+        const event = objectOf(value, eventLocation);
+        exactKeys(event, eventLocation, ["eventId", "sequence", "type", "correlationId", "causationId", "payload"], ["payloadRefs"]);
+        const payload = { ...objectOf(event.payload, `${eventLocation}.payload`) };
+
+        if (Object.hasOwn(event, "payloadRefs")) {
+            const references = objectOf(event.payloadRefs, `${eventLocation}.payloadRefs`);
+
+            for (const [key, value] of Object.entries(references)) {
+                const referenceLocation = `${eventLocation}.payloadRefs.${key}`;
+                const reference = objectOf(value, referenceLocation);
+                exactKeys(reference, referenceLocation, ["sha256", "bytes"]);
+
+                if (typeof reference.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(reference.sha256)
+                    || typeof reference.bytes !== "number" || !Number.isSafeInteger(reference.bytes)
+                    || reference.bytes < journalPayloadThresholdBytes)
+                    throw new Error(`${referenceLocation} is not a valid payload reference.`);
+
+                if (Object.hasOwn(payload, key))
+                    throw new Error(`${referenceLocation} duplicates an inline payload field.`);
+
+                const content = readPayload(reference as PayloadReference, runDirectory, referenceLocation);
+                let resolved: unknown;
+
+                try {
+                    resolved = JSON.parse(content.toString("utf8"));
+                } catch (error) {
+                    throw new Error(`${referenceLocation} contains invalid JSON.`, { cause: error });
+                }
+
+                Object.defineProperty(payload, key, { value: resolved, enumerable: true, writable: true, configurable: true });
+            }
+        }
+
+        return journalEventOf({
+            eventId: event.eventId,
+            runId: record.runId,
+            sequence: event.sequence,
+            schemaVersion: 3,
+            occurredAt: record.occurredAt,
+            actorId: command.actorId,
+            commandId: command.id,
+            correlationId: event.correlationId,
+            causationId: event.causationId,
+            type: event.type,
+            payload,
+        }, eventLocation);
+    });
+
+    return { formatVersion: 3, runId: record.runId, command, events };
+};