@schlenkr/ragents 0.1.5 → 0.1.7

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

@@ -1,10 +1,10 @@
 import type { JournalEvent } from "../../domain/events.ts";
-import { isPendingActorInput, type EventSubscription, type ObservableEventType, type RunState } from "../../domain/model.ts";
+import { eventSubjectOf, 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";
+import { actorById, commandActorOf, assertCapability, clean, executableActorOf } from "../guards.ts";
 
 export const createSubscription =
     (input: {
@@ -15,7 +15,7 @@ export const createSubscription =
         includeSelf?: boolean;
     }): Decision =>
     (state, context, services) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
         const subscriber = executableActorOf(state, input.subscriberId);
 
         if (caller.id !== state.ownerId) {
@@ -66,7 +66,7 @@ export const createSubscription =
 export const removeSubscription =
     (subscriptionId: string, reason: string): Decision =>
     (state, context) => {
-        const caller = actorOf(state, context);
+        const caller = commandActorOf(state, context);
         const subscription = state.subscriptions.get(subscriptionId);
 
         if (!subscription)
@@ -118,14 +118,16 @@ export const matchesSubscription = (state: RunState, subscription: EventSubscrip
     if (!subscription.eventTypes.includes(source.type))
         return false;
 
-    if (!subscription.includeSelf && source.actorId === subscription.subscriberId)
+    const subjectId = eventSubjectOf(state, source);
+
+    if (!subscription.includeSelf && subjectId === subscription.subscriberId)
         return false;
 
-    if (subscription.sourceActorIds && !subscription.sourceActorIds.includes(source.actorId))
+    if (subscription.sourceActorIds && !subscription.sourceActorIds.includes(subjectId))
         return false;
 
     if (subscription.sourceActorKinds) {
-        const sourceActor = state.actors.get(source.actorId);
+        const sourceActor = state.actors.get(subjectId);
 
         if (!sourceActor || !subscription.sourceActorKinds.includes(sourceActor.kind))
             return false;

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

@@ -1,8 +1,9 @@
+import type { EventPayloads, ModelInputContent, ModelStepBlock, ModelToolResultPart, UncommittedEvent } from "../../domain/events.ts";
 import type { JsonValue } from "../../domain/json.ts";
-import type { TurnUsage } from "../../domain/model.ts";
+import { isPendingActorInput, 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";
+import { actorById, commandActorOf, 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");
@@ -11,7 +12,7 @@ const runningTurn = (state: Parameters<Decision>[0], context: Parameters<Decisio
     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);
+    commandActorOf(state, context);
 
     return target;
 };
@@ -46,8 +47,38 @@ export const startTurn =
         })];
     };
 
+/** Pending inputs join a running agent turn in their journal order; nothing may be skipped. */
+export const steerInputs =
+    (actorId: string, input: { turnId: string; inputIds: readonly string[] }): Decision =>
+    (state, context) => {
+        const target = runningTurn(state, context, actorId, input.turnId);
+
+        if (target.execution.driver.kind !== "agent")
+            throw new DomainError("steering-unsupported", `Actor ${actorId} runs without a model and takes no steering.`, 409);
+
+        if (input.inputIds.length === 0)
+            throw new DomainError("steering-empty", `Steering into turn ${input.turnId} names no input.`, 400);
+
+        const pending = [...state.inputs.values()]
+            .filter((entry) => entry.actorId === actorId && isPendingActorInput(entry))
+            .sort((left, right) => left.sequence - right.sequence)
+            .map((entry) => entry.id);
+
+        if (input.inputIds.some((inputId, index) => pending[index] !== inputId))
+            throw new DomainError(
+                "steering-order",
+                `Steering into turn ${input.turnId} must take the oldest pending inputs in order; pending are ${pending.join(", ") || "none"}.`,
+                409,
+            );
+
+        return input.inputIds.map((inputId) => event(context, {
+            type: "turn.input-steered",
+            payload: { turnId: input.turnId, inputId },
+        }));
+    };
+
 const appendText = (
-    type: "model.output.completed" | "model.reasoning.completed" | "runtime.output.recorded",
+    type: "model.output.interrupted" | "runtime.output.recorded",
     actorId: string,
     input: { turnId: string; text: string },
 ): Decision => (state, context) => {
@@ -56,15 +87,76 @@ const appendText = (
     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 appendInterruptedModelOutput = (actorId: string, input: { turnId: string; text: string }): Decision =>
+    appendText("model.output.interrupted", actorId, input);
 
 export const appendRuntimeOutput = (actorId: string, input: { turnId: string; text: string }): Decision =>
     appendText("runtime.output.recorded", actorId, input);
 
+/** The input exactly as the model received it, at its place between the model steps. */
+export const presentModelInput =
+    (actorId: string, input: { turnId: string; inputId: string | null; content: ModelInputContent }): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+
+        return [event(context, { type: "model.input.presented", payload: input })];
+    };
+
+export type CompletedModelStep = Omit<EventPayloads["model.step.completed"], "turnId" | "content"> & {
+    content: readonly (
+        | { type: "text"; text: string; textSignature?: string }
+        | { type: "thinking"; thinking: string; thinkingSignature?: string; redacted?: boolean }
+        | Extract<ModelStepBlock, { type: "toolCall" }>
+    )[];
+};
+
+/** One command: the text and reasoning a step made visible as observation events, then the step itself, which does not repeat them. */
+export const completeModelStep =
+    (actorId: string, input: { turnId: string; step: CompletedModelStep }): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+        const observed: UncommittedEvent[] = [];
+        const content = input.step.content.map((block): ModelStepBlock => {
+            if (block.type === "text" && block.text.trim()) {
+                observed.push(event(context, { type: "model.output.completed", payload: { turnId: input.turnId, text: block.text } }));
+                const { text: _text, ...rest } = block;
+                return rest;
+            }
+
+            if (block.type === "thinking" && block.thinking.trim()) {
+                observed.push(event(context, { type: "model.reasoning.completed", payload: { turnId: input.turnId, text: block.thinking } }));
+                const { thinking: _thinking, ...rest } = block;
+                return rest;
+            }
+
+            return { ...block };
+        });
+
+        return [
+            ...observed,
+            event(context, { type: "model.step.completed", payload: { turnId: input.turnId, ...input.step, content } }),
+        ];
+    };
+
+export const presentToolResult =
+    (
+        actorId: string,
+        input: { turnId: string; toolCallId: string; toolName: string; isError: boolean; content?: ModelToolResultPart[] },
+    ): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+
+        return [event(context, { type: "model.tool-result.presented", payload: input })];
+    };
+
+export const compactContext =
+    (actorId: string, input: EventPayloads["context.compacted"]): Decision =>
+    (state, context) => {
+        runningTurn(state, context, actorId, input.turnId);
+
+        return [event(context, { type: "context.compacted", payload: input })];
+    };
+
 export const startToolCall =
     (actorId: string, input: { turnId: string; toolCallId: string; name: string; input: JsonValue; ignoredFields?: string[] }): Decision =>
     (state, context) => {

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

@@ -2,15 +2,15 @@ import { resolve } from "node:path";
 
 import type {
     Actor,
-    AgentActor,
     Artifact,
     CapabilityGrant,
     CapabilityName,
     CapabilityScope,
     ExecutableActor,
     RunState,
+    Turn,
 } from "../domain/model.ts";
-import { isActiveActor } from "../domain/projection.ts";
+import { actorByReference, handleKey } from "../domain/actor-reference.ts";
 import { DomainError } from "./domain-error.ts";
 
 export const clean = (value: string, name: string) => {
@@ -32,7 +32,7 @@ export const optionalClean = (value: string | null | undefined, name: string) =>
 };
 
 export const handleOf = (value: string) => {
-    const result = value.trim().replace(/^@/, "").normalize("NFC").toLowerCase();
+    const result = handleKey(value);
 
     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);
@@ -72,11 +72,11 @@ export const executableActorOf = (state: RunState, actorId: string): ExecutableA
     return found;
 };
 
-export const agentActorOf = (state: RunState, agentId: string): AgentActor => {
-    const found = actorById(state, agentId);
+export const turnOf = (state: RunState, turnId: string): Turn => {
+    const found = state.turns.get(turnId);
 
-    if (found.kind !== "agent")
-        throw new DomainError("agent-not-found", `Actor ${agentId} is not an agent.`, 404);
+    if (!found)
+        throw new DomainError("turn-not-found", `Turn ${turnId} does not exist.`, 404);
 
     return found;
 };
@@ -90,20 +90,13 @@ export const artifactOf = (state: RunState, artifactId: string): Artifact => {
     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);
+export const addressedActorOf = (actors: Iterable<Actor>, reference: string): Actor => {
+    const found = actorByReference(actors, reference);
 
-    if (!byHandle)
+    if (!found)
         throw new DomainError("actor-not-found", `Actor ${reference} does not exist.`, 404);
 
-    return byHandle;
+    return found;
 };
 
 export const assertActorCanCommand = (actor: Actor, turnId: string | undefined) => {
@@ -121,15 +114,13 @@ export const assertActorCanCommand = (actor: Actor, turnId: string | undefined)
         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 => {
+export const commandActorOf = (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;

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

@@ -8,7 +8,9 @@ import { isRunId } from "../domain/portable-id.ts";
 import { syncDirectory } from "./durable-fs.ts";
 import type { CommandRecord, JournalCommand } from "./journal.ts";
 
-export const journalStorageVersion = 4;
+/** Rises whenever an older stand would reject newly written lines; the journal reads only this version. */
+export const journalStorageVersion = 7;
+const readableJournalStorageVersions: readonly unknown[] = [journalStorageVersion];
 export const journalPayloadThresholdBytes = 4096;
 
 type PayloadReference = { sha256: string; bytes: number };
@@ -158,8 +160,11 @@ export const parseJournalRecord = (line: string, runDirectory: string, location:
     assertJsonValue(parsed, location);
     const record = objectOf(parsed, location);
 
-    if (record.formatVersion !== journalStorageVersion)
-        throw new Error(`${location} has unsupported journal format version ${String(record.formatVersion)}.`);
+    if (!readableJournalStorageVersions.includes(record.formatVersion))
+        throw new Error(`${location} has unsupported journal format version ${String(record.formatVersion)}.${
+            typeof record.formatVersion === "number" && record.formatVersion < journalStorageVersion
+                ? " Journals before format 7 hold no model context and are not migrated."
+                : ""}`);
 
     exactKeys(record, location, ["formatVersion", "runId", "command", "occurredAt", "events"]);
 

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

@@ -346,6 +346,12 @@ export class Journal {
         return [...this.#loadFailures.values()];
     }
 
+    /** Every locked run with its cause: journals rejected at load and runs isolated by a write failure. */
+    unavailableRuns(): readonly JournalLoadFailure[] {
+        return [...new Set([...this.#loadFailures.keys(), ...this.#writeFailures.keys()])]
+            .flatMap((runId) => this.failureOf(runId) ?? []);
+    }
+
     failureOf(runId: string): JournalLoadFailure | null {
         const failure = this.#loadFailures.get(runId);
         const writeFailure = this.#writeFailures.get(runId);
@@ -369,6 +375,34 @@ export class Journal {
         return [...(this.#runs.get(runId)?.events ?? [])];
     }
 
+    /** The events after the given sequence; the sequence counts from 1 without gaps. */
+    eventsSince(runId: RunId, sequence: number): JournalEvent[] {
+        this.assertRunAvailable(runId);
+        return (this.#runs.get(runId)?.events ?? []).slice(sequence);
+    }
+
+    /** The events from the newest back, without copying the journal; a caller stops as soon as it has what it needs. */
+    *recentEvents(runId: RunId): Generator<JournalEvent> {
+        this.assertRunAvailable(runId);
+        const events = this.#runs.get(runId)?.events ?? [];
+
+        for (let index = events.length - 1; index >= 0; index--)
+            yield events[index]!;
+    }
+
+    /** A value read from the current state without cloning all of it; `read` must neither keep nor change the state. */
+    select<Value>(runId: RunId, read: (state: RunState) => Value): Value | null {
+        this.assertRunAvailable(runId);
+        const state = this.#runs.get(runId)?.state;
+
+        return state ? clone(read(state)) : null;
+    }
+
+    firstEventId(runId: RunId): string | undefined {
+        this.assertRunAvailable(runId);
+        return this.#runs.get(runId)?.events[0]?.eventId;
+    }
+
     records(runId: RunId): readonly CommandRecord[] {
         this.assertRunAvailable(runId);
         return [...(this.#runs.get(runId)?.records ?? [])];
@@ -570,7 +604,8 @@ export class Journal {
             const log = this.#runs.get(runId);
             const semantics = log ? {
                 events: new Map(log.semantics.events),
-                toolCalls: clone(log.semantics.toolCalls),
+                sourcedToolCalls: new Set(log.semantics.sourcedToolCalls),
+                presented: new Set(log.semantics.presented),
             } : eventSemanticContext();
             let state: RunDraft | null = log?.state ? forkProjection(log.state) : null;