@schlenkr/ragents 0.1.5 → 0.1.7

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

@@ -1,7 +1,6 @@
 import type {
     ActionId,
     ActionInput,
-    ActionKind,
     ActionStatus,
     ActorId,
     ActorKind,
@@ -16,7 +15,36 @@ import type {
     TurnId,
     TurnUsage,
 } from "./model.ts";
-import type { JsonChange, JsonValue } from "./json.ts";
+import type { JsonChange, JsonObject, JsonValue } from "./json.ts";
+
+/** A media part the model saw, stored by the SHA-256 of its bytes in the artifact contents instead of Base64. */
+export type ModelMediaPart =
+    | { type: "image" | "video"; mimeType: string; hash: string }
+    | { type: "file"; mimeType: string; filename: string; hash: string };
+
+export type ModelTextPart = { type: "text"; text: string };
+
+/** The content of a user message exactly as the model received it. */
+export type ModelInputContent = string | (ModelTextPart | ModelMediaPart)[];
+
+export type ModelToolResultPart = ModelTextPart | { type: "image"; mimeType: string; hash: string };
+
+/** A block of a model step; text and thinking without their own field stand in the observation events of the same command, in order. */
+export type ModelStepBlock =
+    | { type: "text"; text?: string; textSignature?: string }
+    | { type: "thinking"; thinking?: string; thinkingSignature?: string; redacted?: boolean }
+    | { type: "toolCall"; id: string; name: string; arguments: JsonObject; thoughtSignature?: string };
+
+export type ModelStepUsage = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cacheWrite1h?: number;
+    reasoning?: number;
+    totalTokens: number;
+    cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };
+};
 
 export type EventPayloads = {
     "run.created": {
@@ -26,6 +54,8 @@ export type EventPayloads = {
             handle: string;
             displayName: string;
             grants: CapabilityGrant[];
+            /** Der angemeldete Benutzer, dem der Run gehört; ohne Anmeldung nicht gesetzt. */
+            userId?: string;
         };
     };
     "run.forked": {
@@ -47,6 +77,7 @@ export type EventPayloads = {
         grants: CapabilityGrant[];
         toolNames: string[] | null;
         forkOf?: ActorId;
+        description?: string;
     };
     "script.created": {
         scriptId: ActorId;
@@ -55,6 +86,7 @@ export type EventPayloads = {
         execution: AgentExecution;
         grants: CapabilityGrant[];
         toolNames: string[] | null;
+        description?: string;
     };
     "actor.input.enqueued": {
         inputId: InputId;
@@ -69,6 +101,10 @@ export type EventPayloads = {
         turnId: TurnId;
         inputId: InputId;
     };
+    "turn.input-steered": {
+        turnId: TurnId;
+        inputId: InputId;
+    };
     "turn.finished": {
         turnId: TurnId;
         usage?: TurnUsage;
@@ -77,10 +113,53 @@ export type EventPayloads = {
         turnId: TurnId;
         reason: string;
     };
+    "model.input.presented": {
+        turnId: TurnId;
+        /** The claimed input, or null for a message of the agent loop itself. */
+        inputId: InputId | null;
+        content: ModelInputContent;
+    };
+    "model.step.completed": {
+        turnId: TurnId;
+        api: string;
+        provider: string;
+        model: string;
+        responseModel?: string;
+        responseId?: string;
+        usage: ModelStepUsage;
+        stopReason: "stop" | "length" | "toolUse" | "error";
+        errorMessage?: string;
+        diagnostics?: JsonValue[];
+        timestamp: number;
+        content: ModelStepBlock[];
+    };
+    "model.tool-result.presented": {
+        turnId: TurnId;
+        toolCallId: string;
+        toolName: string;
+        isError: boolean;
+        /** Absent when the model saw exactly the text of the call's tool.call.completed or tool.call.failed. */
+        content?: ModelToolResultPart[];
+    };
+    "context.compacted": {
+        turnId: TurnId;
+        summary: string;
+        /** The first context event after the cut; everything before it is replaced by the summary. */
+        firstKeptEventId: string;
+        tokensBefore: number;
+        provider: string;
+        model: string;
+        readFiles: string[];
+        modifiedFiles: string[];
+    };
     "model.output.completed": {
         turnId: TurnId;
         text: string;
     };
+    "model.output.interrupted": {
+        turnId: TurnId;
+        text: string;
+    };
     "model.reasoning.completed": {
         turnId: TurnId;
         text: string;
@@ -156,18 +235,17 @@ export type EventPayloads = {
     };
     "action.proposed": {
         actionId: ActionId;
+        owner: string | null;
         title: string;
         description: string | null;
         parameters: Record<string, string>;
         input: ActionInput | null;
-    } & (
-        | { kind: "action" }
-        | { kind: "question"; question: { options: string[]; multi: boolean } | null }
-    );
+        payload: JsonObject | null;
+    };
     "action.resolved": {
         actionId: ActionId;
         decision: Exclude<ActionStatus, "pending">;
-        response: string | null;
+        result: JsonValue | null;
     };
     "artifact.published": {
         artifact: Omit<Artifact, "createdBy" | "createdAt">;
@@ -185,9 +263,15 @@ export const eventTypeMap: Record<EventType, true> = {
     "script.created": true,
     "actor.input.enqueued": true,
     "turn.started": true,
+    "turn.input-steered": true,
     "turn.finished": true,
     "turn.interrupted": true,
+    "model.input.presented": true,
+    "model.step.completed": true,
+    "model.tool-result.presented": true,
+    "context.compacted": true,
     "model.output.completed": true,
+    "model.output.interrupted": true,
     "model.reasoning.completed": true,
     "runtime.output.recorded": true,
     "tool.call.started": true,

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

@@ -6,6 +6,8 @@ export type JsonValue =
     | JsonValue[]
     | { [key: string]: JsonValue | undefined };
 
+export type JsonObject = { [key: string]: JsonValue | undefined };
+
 export type JsonPath = (string | number)[];
 export type JsonChange =
     | { op: "set"; path: JsonPath; value: JsonValue }

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

@@ -1,5 +1,6 @@
 import type { AgentExecution } from "./driver.ts";
-import type { JsonValue } from "./json.ts";
+import type { JournalEvent } from "./events.ts";
+import type { JsonObject, JsonValue } from "./json.ts";
 import type { CapabilityName, ObservableEventType } from "./vocabulary.ts";
 
 export type { CapabilityName, ObservableEventType };
@@ -51,8 +52,12 @@ export type TurnUsage = {
     costUsd: number;
 };
 
+/** Longest short description an actor may carry for overviews. */
+export const actorDescriptionMaxLength = 160;
+
 type ExecutableActorBase = ActorBase & {
     createdBy: ActorId;
+    description: string | null;
     execution: AgentExecution;
     lifecycle: ActorLifecycle;
     usage: TurnUsage;
@@ -73,9 +78,10 @@ export type ScriptActor = ExecutableActorBase & { kind: "script" };
 export type ExecutableActor = AgentActor | ScriptActor;
 export type Actor = HumanActor | ExecutableActor;
 
+/** `steered` marks an input that joined its already running turn instead of starting it. */
 export type ActorInputLifecycle =
     | { kind: "pending" }
-    | { kind: "claimed"; turnId: TurnId }
+    | { kind: "claimed"; turnId: TurnId; steered: boolean }
     | { kind: "discarded"; at: string; reason: string };
 
 export type ActorInput = {
@@ -125,8 +131,6 @@ export type Turn = {
     toolCalls: readonly TurnToolCall[];
 };
 
-export type SubscriptionStatus = "active" | "removed" | "failed";
-
 export type EventSubscription = {
     id: SubscriptionId;
     subscriberId: ActorId;
@@ -164,29 +168,22 @@ export type ActionInput = {
 };
 
 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;
+    owner: string | null;
     title: string;
     description: string | null;
     parameters: Readonly<Record<string, string>>;
     input: ActionInput | null;
+    payload: JsonObject | null;
     status: ActionStatus;
     proposedAt: string;
     resolvedAt: string | null;
     resolvedBy: ActorId | null;
-    response: string | null;
-} & (
-    | { kind: "action" }
-    | { kind: "question"; question: ActionQuestion | null }
-);
+    result: JsonValue | null;
+};
 
 export type Artifact = {
     id: ArtifactId;
@@ -204,7 +201,11 @@ export type RunState = {
     revision: number;
     title: string;
     ownerId: ActorId;
+    /** Der angemeldete Benutzer, dem der Run gehört; null für Runs, die ohne Anmeldung entstanden sind. */
+    ownerUserId: string | null;
     primaryActorId: ActorId | null;
+    /** Der Primary-Actor, der als solcher gestoppt wurde, bis ein Primary-Actor gewählt wird; sein Neustart durch den Owner macht ihn wieder dazu. */
+    stoppedPrimaryActorId: ActorId | null;
     createdAt: string;
     forkedFrom: { runId: RunId; sequence: number } | null;
     actors: ReadonlyMap<ActorId, Actor>;
@@ -214,11 +215,36 @@ export type RunState = {
     pluginStates: ReadonlyMap<string, PluginState>;
     actions: ReadonlyMap<ActionId, Action>;
     artifacts: ReadonlyMap<ArtifactId, Artifact>;
+    /** Turns that presented input to the model, with their actor; only they leave model context behind. */
+    contextTurns: ReadonlyMap<TurnId, ActorId>;
+};
+
+/** Der Actor, den ein Event betrifft: bei Turn-Enden der Besitzer des Turns, bei Stopp und Neustart der Ziel-Actor, sonst der Schreiber. */
+export const eventSubjectOf = (state: RunState, event: JournalEvent): ActorId => {
+    switch (event.type) {
+        case "turn.finished":
+        case "turn.interrupted": {
+            const turn = state.turns.get(event.payload.turnId);
+
+            if (!turn)
+                throw new Error(`Turn ${event.payload.turnId} of event ${event.eventId} does not exist.`);
+
+            return turn.actorId;
+        }
+
+        case "actor.stopped":
+        case "actor.restarted":
+            return event.payload.actorId;
+
+        default:
+            return event.actorId;
+    }
 };
 
 type Collections = "actors" | "inputs" | "turns" | "subscriptions" | "pluginStates" | "actions" | "artifacts";
 
-export type RunView = Omit<RunState, Collections> & {
+/** Die Run-Ansicht für Clients; Eigentümer und Kontext-Turns bleiben serverseitig und stehen nicht in ihr. */
+export type RunView = Omit<RunState, Collections | "ownerUserId" | "contextTurns"> & {
     actors: Actor[];
     inputs: ActorInput[];
     turns: Turn[];
@@ -263,5 +289,3 @@ export const addUsage = (left: TurnUsage, right: TurnUsage): TurnUsage => ({
     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/projection.ts

@@ -50,6 +50,7 @@ export const forkProjection = (state: RunDraft): RunDraft => ({
     subscriptions: new Map(state.subscriptions),
     pluginStates: new Map(state.pluginStates),
     artifacts: new Map(state.artifacts),
+    contextTurns: new Map(state.contextTurns),
 });
 
 const actor = (state: RunDraft, id: string) => {
@@ -79,6 +80,15 @@ const turn = (state: RunDraft, id: string): Draft<Turn> => {
     return found;
 };
 
+/** A turn end closes the calls still open: they are interrupted, whatever ended the turn. */
+const interruptOpenToolCalls = (current: Draft<Turn>, at: string) => {
+    for (const call of current.toolCalls) {
+        if (call.status !== "running") continue;
+        call.status = "interrupted";
+        call.finishedAt = at;
+    }
+};
+
 const subscriptionBaseOf = (subscription: Draft<EventSubscription>) => ({
     id: subscription.id,
     subscriberId: subscription.subscriberId,
@@ -96,7 +106,9 @@ const created = (event: Extract<JournalEvent, { type: "run.created" }>): RunDraf
     revision: event.sequence,
     title: event.payload.title,
     ownerId: event.payload.owner.id,
+    ownerUserId: event.payload.owner.userId ?? null,
     primaryActorId: null,
+    stoppedPrimaryActorId: null,
     createdAt: event.occurredAt,
     forkedFrom: null,
     actors: new Map([
@@ -104,7 +116,10 @@ const created = (event: Extract<JournalEvent, { type: "run.created" }>): RunDraf
             event.payload.owner.id,
             {
                 kind: "human" as const,
-                ...event.payload.owner,
+                id: event.payload.owner.id,
+                handle: event.payload.owner.handle,
+                displayName: event.payload.owner.displayName,
+                grants: event.payload.owner.grants,
                 createdAt: event.occurredAt,
             },
         ],
@@ -115,6 +130,7 @@ const created = (event: Extract<JournalEvent, { type: "run.created" }>): RunDraf
     pluginStates: new Map(),
     actions: new Map(),
     artifacts: new Map(),
+    contextTurns: new Map(),
 });
 
 export function applyEvent(
@@ -148,6 +164,7 @@ export function applyEvent(
         case "run.primary-actor-selected":
             executable(state, event.payload.actorId);
             state.primaryActorId = event.payload.actorId;
+            state.stoppedPrimaryActorId = null;
             break;
 
         case "run.title-changed":
@@ -161,6 +178,7 @@ export function applyEvent(
                 handle: event.payload.handle,
                 displayName: event.payload.displayName,
                 createdBy: event.actorId,
+                description: event.payload.description ?? null,
                 prompt: event.payload.prompt,
                 forkOf: event.payload.forkOf ?? null,
                 execution: event.payload.execution,
@@ -180,6 +198,7 @@ export function applyEvent(
                 handle: event.payload.handle,
                 displayName: event.payload.displayName,
                 createdBy: event.actorId,
+                description: event.payload.description ?? null,
                 execution: event.payload.execution,
                 grants: event.payload.grants,
                 toolNames: event.payload.toolNames,
@@ -229,7 +248,7 @@ export function applyEvent(
             if (input.lifecycle.kind === "claimed")
                 throw new Error(`Input ${input.id} already belongs to turn ${input.lifecycle.turnId}.`);
 
-            input.lifecycle = { kind: "claimed", turnId: event.payload.turnId };
+            input.lifecycle = { kind: "claimed", turnId: event.payload.turnId, steered: false };
             target.lifecycle = {
                 kind: "running",
                 turnId: event.payload.turnId,
@@ -251,6 +270,17 @@ export function applyEvent(
             break;
         }
 
+        case "turn.input-steered": {
+            const current = turn(state, event.payload.turnId);
+            const input = state.inputs.get(event.payload.inputId);
+
+            if (!input)
+                throw new Error(`Input ${event.payload.inputId} does not exist.`);
+
+            input.lifecycle = { kind: "claimed", turnId: current.id, steered: true };
+            break;
+        }
+
         case "turn.finished": {
             const current = turn(state, event.payload.turnId);
             const target = executable(state, current.actorId);
@@ -260,6 +290,7 @@ export function applyEvent(
             current.status = event.payload.outcome;
             current.finishedAt = event.occurredAt;
             current.reason = event.payload.outcome === "failed" ? event.payload.reason : null;
+            interruptOpenToolCalls(current, event.occurredAt);
 
             if (event.payload.usage && cumulativeUsage) {
                 current.usage = event.payload.usage;
@@ -278,11 +309,7 @@ export function applyEvent(
             current.status = "interrupted";
             current.finishedAt = event.occurredAt;
             current.reason = event.payload.reason;
-            for (const call of current.toolCalls) {
-                if (call.status !== "running") continue;
-                call.status = "interrupted";
-                call.finishedAt = event.occurredAt;
-            }
+            interruptOpenToolCalls(current, event.occurredAt);
 
             if (target.lifecycle.kind === "running" && target.lifecycle.turnId === current.id)
                 target.lifecycle = { kind: "idle", since: event.occurredAt };
@@ -321,8 +348,16 @@ export function applyEvent(
         }
 
         case "model.reasoning.completed":
+        case "model.output.interrupted":
         case "runtime.output.recorded":
         case "tool.call.source":
+        case "model.step.completed":
+        case "model.tool-result.presented":
+        case "context.compacted":
+            break;
+
+        case "model.input.presented":
+            state.contextTurns.set(event.payload.turnId, event.actorId);
             break;
 
         case "actor.tools.opened": {
@@ -338,8 +373,10 @@ export function applyEvent(
                 reason: event.payload.reason,
             };
 
-            if (state.primaryActorId === event.payload.actorId)
+            if (state.primaryActorId === event.payload.actorId) {
                 state.primaryActorId = null;
+                state.stoppedPrimaryActorId = event.payload.actorId;
+            }
             break;
 
         case "actor.restarted":
@@ -426,22 +463,21 @@ export function applyEvent(
         }
 
         case "action.proposed": {
-            const base = {
+            const action: Draft<Action> = {
                 id: event.payload.actionId,
                 askedBy: event.actorId,
+                owner: event.payload.owner,
                 title: event.payload.title,
                 description: event.payload.description,
                 parameters: event.payload.parameters,
                 input: event.payload.input,
-                status: "pending" as const,
+                payload: event.payload.payload,
+                status: "pending",
                 proposedAt: event.occurredAt,
                 resolvedAt: null,
                 resolvedBy: null,
-                response: null,
+                result: null,
             };
-            const action: Draft<Action> = event.payload.kind === "question"
-                ? { ...base, kind: "question", question: event.payload.question }
-                : { ...base, kind: "action" };
             state.actions.set(action.id, action);
             break;
         }
@@ -455,7 +491,7 @@ export function applyEvent(
             found.status = event.payload.decision;
             found.resolvedAt = event.occurredAt;
             found.resolvedBy = event.actorId;
-            found.response = event.payload.response;
+            found.result = event.payload.result;
             break;
         }
 
@@ -491,6 +527,7 @@ export function viewOf(state: RunState): RunView {
         title: state.title,
         ownerId: state.ownerId,
         primaryActorId: state.primaryActorId,
+        stoppedPrimaryActorId: state.stoppedPrimaryActorId,
         createdAt: state.createdAt,
         forkedFrom: state.forkedFrom,
         actors: [...state.actors.values()],

package/packages/ragents/src/domain/schema-errors.ts

@@ -24,7 +24,7 @@ const stringsOf = (params: unknown, key: string): string[] => {
     return Array.isArray(value) ? value.map(String) : [];
 };
 
-export const schemaComplaints = (schema: unknown, input: unknown): string => {
+export const schemaComplaints = (schema: unknown, input: unknown, root = "input"): string => {
     const errors = [...Value.Errors(schema as Parameters<typeof Value.Errors>[0], input)];
     const byPath = new Map<string, typeof errors>();
 
@@ -34,7 +34,7 @@ export const schemaComplaints = (schema: unknown, input: unknown): string => {
     const lines: string[] = [];
 
     for (const [pointer, group] of byPath) {
-        const path = pointer.split("/").slice(1).join(".") || "input";
+        const path = pointer.split("/").slice(1).join(".") || root;
         const allowed = group.flatMap((entry) =>
             entry.keyword === "const" ? [String((entry.params as Record<string, unknown>).allowedValue)] : []);
         const missing = group.flatMap((entry) => (entry.keyword === "required" ? stringsOf(entry.params, "requiredProperties") : []));
@@ -51,6 +51,6 @@ export const schemaComplaints = (schema: unknown, input: unknown): string => {
             lines.push(`${path} ${group[0].message}, got ${shortJson(valueAt(input, pointer))}`);
     }
 
-    return lines.slice(0, 8).join("; ");
+    return lines.length > 0 ? lines.slice(0, 8).join("; ") : `${root} does not match its schema`;
 };
 

package/packages/ragents/src/domain/tool-result-text.ts

@@ -0,0 +1,9 @@
+import type { JournalEvent } from "./events.ts";
+
+type ToolResultEvent = Extract<JournalEvent, { type: "tool.call.completed" | "tool.call.failed" }>;
+
+/** The text the model sees of a tool call when no hook replaced it and the tool recorded its full output. */
+export const derivedToolResultText = (event: ToolResultEvent): string =>
+    event.type === "tool.call.failed"
+        ? event.payload.error
+        : typeof event.payload.output === "string" ? event.payload.output : JSON.stringify(event.payload.output ?? {});

package/packages/ragents/src/drivers/agent-hooks.ts

@@ -0,0 +1,27 @@
+import type {
+  AgentContribution,
+  AgentContributionContext,
+  AgentHookContext,
+  ModelCallContext,
+  ToolCallOutcome,
+  ToolResultReplacement,
+} from "../plugin-types.ts";
+
+/** A hook of a plugin, bound to one agent; the agent driver calls it directly. */
+export interface AgentHook {
+  readonly id: string;
+  readonly beforeModelCall?: (call: ModelCallContext) => string | undefined | Promise<string | undefined>;
+  readonly afterToolCall?: (outcome: ToolCallOutcome, call: AgentHookContext) =>
+    ToolResultReplacement | undefined | Promise<ToolResultReplacement | undefined>;
+}
+
+/** The one place that binds the hooks of a plugin to an agent; plugins never see the agent runtime. */
+export const agentHookOf = (contribution: AgentContribution, agent: AgentContributionContext): AgentHook => {
+  const { id, beforeModelCall, afterToolCall } = contribution;
+
+  return {
+    id,
+    ...(beforeModelCall ? { beforeModelCall: (call: ModelCallContext) => beforeModelCall(agent, call) } : {}),
+    ...(afterToolCall ? { afterToolCall: (outcome: ToolCallOutcome, call: AgentHookContext) => afterToolCall(agent, outcome, call) } : {}),
+  };
+};