@schlenkr/ragents 0.1.6 → 0.1.8

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

@@ -10,12 +10,13 @@ export type {
     AgentRuntimeContext,
     AgentRuntimeDiagnostic,
     AgentRuntimeManagerOptions,
-    AgentSessionStore,
 } from "./agent-runtime.ts";
-export { AgentRuntimeManager, turnDispatcherExtensionName } from "./agent-runtime.ts";
+export { AgentRuntimeManager } from "./agent-runtime.ts";
+export { agentHookOf, type AgentHook } from "./agent-hooks.ts";
 export {
-    createSkillPreloadExtension,
-    skillPreloadExtensionName,
+    createSkillPreload,
+    skillPreloadHookName,
+    type SkillPreload,
     type SkillPreloadConfiguration,
     type SkillPreloadOptions,
     type SkillCatalogEntry,
@@ -23,17 +24,18 @@ export {
     type SkillSelector,
 } from "./skill-preload.ts";
 
-export type AgentSessionDriverOptions = Omit<AgentRuntimeManagerOptions, "modelRuntime"> & {
+export type AgentLoopDriverOptions = Omit<AgentRuntimeManagerOptions, "modelRuntime"> & {
     modelRuntime?: ModelRuntime | Promise<ModelRuntime>;
 };
 
-export class AgentSessionDriver implements AgentDriver<"agent"> {
+/** The driver of LLM actors: the agent loop on the model context the journal holds. */
+export class AgentLoopDriver implements AgentDriver<"agent"> {
     readonly kind = "agent" as const;
     readonly supportsPlainLlm = true;
     readonly #modelRuntime: Promise<ModelRuntime>;
     readonly #runtimeManager: AgentRuntimeManager;
 
-    constructor(options: AgentSessionDriverOptions = {}) {
+    constructor(options: AgentLoopDriverOptions = {}) {
         this.#modelRuntime = Promise.resolve(options.modelRuntime ?? ModelRuntime.create());
         this.#runtimeManager = new AgentRuntimeManager({ ...options, modelRuntime: this.#modelRuntime });
     }

package/packages/ragents/src/drivers/skill-preload.ts

@@ -1,10 +1,10 @@
 import { readFile } from "node:fs/promises";
 
-import { stripFrontmatter, type InlineExtension, type ModelRuntime, type Skill } from "@ragents/agent";
+import { stripFrontmatter, type ModelRuntime, type Skill } from "@ragents/agent";
 
 import type { TurnUsage } from "../domain/model.ts";
 
-export const skillPreloadExtensionName = "ragents-skill-preload";
+export const skillPreloadHookName = "ragents-skill-preload";
 
 export type SkillCatalogEntry = {
     name: string;
@@ -130,64 +130,54 @@ const preloadedSkills = async (skills: readonly Skill[]): Promise<string> => {
     ].join("\n\n");
 };
 
-export const createSkillPreloadExtension = (options: SkillPreloadOptions): InlineExtension => ({
-    name: skillPreloadExtensionName,
-    factory: (agent) => {
-        agent.on("before_agent_start", async (event, context) => {
-            try {
-                const skills = event.systemPromptOptions.skills ?? [];
-
-                if (skills.length === 0)
-                    return;
-
-                const explicit = explicitSkillNames(event.prompt, skills);
-                let names: readonly string[] | null = explicit.length > 0 ? explicit : null;
-                let candidates = skills;
-
-                if (explicit.length === 0) {
-                    candidates = skills.filter((skill) => !skill.disableModelInvocation);
-                    const catalog = candidates.map(({ name, description }) => ({ name, description }));
-
-                    if (catalog.length === 0)
-                        return;
-
-                    const selector = options.selector ?? (context.model
-                        ? agentSelector(
-                            options.modelRuntime,
-                            context.model,
-                            options.maxSelectionTokens ?? 100,
-                            options.onUsage,
-                        )
-                        : null);
-
-                    if (!selector)
-                        return;
-
-                    names = await selector({
-                        prompt: event.prompt,
-                        skills: catalog,
-                        signal: context.signal,
-                    });
-                }
-
-                if (!names || names.length === 0)
-                    return;
-
-                const selected = names
-                    .map((name) => candidates.find((skill) => skill.name === name))
-                    .filter((skill): skill is Skill => skill !== undefined);
-
-                if (selected.length === 0)
-                    return;
-
-                return {
-                    systemPrompt: `${event.systemPrompt}\n\n${await preloadedSkills(selected)}`,
-                };
-            } catch (error) {
-                options.onDiagnostic?.(
-                    `Agent skill preloading fell back to the skill catalog: ${error instanceof Error ? error.message : String(error)}`,
-                );
-            }
-        });
-    },
-});
+export type SkillPreloadRequest = {
+    prompt: string;
+    skills: readonly Skill[];
+    model: ReturnType<ModelRuntime["getModels"]>[number];
+    signal: AbortSignal | undefined;
+};
+
+/** Selects skills for the task of a turn and returns their bodies as a section of this turn's system prompt, or undefined. */
+export type SkillPreload = (request: SkillPreloadRequest) => Promise<string | undefined>;
+
+export const createSkillPreload = (options: SkillPreloadOptions): SkillPreload => async ({ prompt, skills, model, signal }) => {
+    try {
+        if (skills.length === 0)
+            return undefined;
+
+        const explicit = explicitSkillNames(prompt, skills);
+        let names: readonly string[] | null = explicit.length > 0 ? explicit : null;
+        let candidates = skills;
+
+        if (explicit.length === 0) {
+            candidates = skills.filter((skill) => !skill.disableModelInvocation);
+            const catalog = candidates.map(({ name, description }) => ({ name, description }));
+
+            if (catalog.length === 0)
+                return undefined;
+
+            const selector = options.selector ?? agentSelector(
+                options.modelRuntime,
+                model,
+                options.maxSelectionTokens ?? 100,
+                options.onUsage,
+            );
+
+            names = await selector({ prompt, skills: catalog, signal });
+        }
+
+        if (!names || names.length === 0)
+            return undefined;
+
+        const selected = names
+            .map((name) => candidates.find((skill) => skill.name === name))
+            .filter((skill): skill is Skill => skill !== undefined);
+
+        return selected.length === 0 ? undefined : await preloadedSkills(selected);
+    } catch (error) {
+        options.onDiagnostic?.(
+            `Agent skill preloading fell back to the skill catalog: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        return undefined;
+    }
+};

package/packages/ragents/src/drivers/types.ts

@@ -1,4 +1,9 @@
+import type { ImageContent, TextContent, UserContent } from "@ragents/ai";
+
 import type { AgentDriverKind, ModelSelection } from "../domain/driver.ts";
+import type { EventPayloads } from "../domain/events.ts";
+import type { CompletedModelStep } from "../runtime/decisions/turns.ts";
+import type { ModelContext } from "../agents/model-context.ts";
 import type { JsonValue } from "../domain/json.ts";
 import type { TurnUsage } from "../domain/model.ts";
 import type { DeliveredInput } from "../agents/delivery.ts";
@@ -24,20 +29,33 @@ type TurnDriverFacts = {
     agent: {
         driverKind: "agent";
         selection: ModelSelection;
-        forkOf: string | null;
         /** `modelContext` names the model context the result enters, see `ToolScope.modelContext`; without it file tools track no seen state. */
         invoke: (toolCallId: string, name: string, input: JsonValue, modelContext?: string) => Promise<ToolInvocation>;
         /** Claims the pending inputs that may join this turn now, in journal order; empty once the turn ends or aborts. */
         claimSteering: () => readonly SteeredInput[];
+        /** The model context of this agent as the journal holds it now. */
+        modelContext: () => ModelContext;
+        /** Records what enters the model context; only a recorded entry is context. */
+        recordContext: (entry: ModelContextRecord) => void;
+        /** What a hook kept for this agent, in the journal as plugin state of the actor. */
+        hookState: {
+            kept: (hookId: string) => JsonValue | undefined;
+            keep: (hookId: string, value: JsonValue) => void;
+        };
     };
 };
 
 export type DriverEvent =
-    | { kind: "assistant"; text: string }
     | { kind: "assistant-interrupted"; text: string }
-    | { kind: "reasoning"; text: string }
     | { kind: "runtime"; text: string };
 
+/** What a driver writes into the model context of its agent, in the order the model sees it. */
+export type ModelContextRecord =
+    | { kind: "input"; inputId: string | null; content: string | readonly UserContent[] }
+    | { kind: "step"; step: CompletedModelStep }
+    | { kind: "tool-result"; toolCallId: string; toolName: string; isError: boolean; content: readonly (TextContent | ImageContent)[] }
+    | { kind: "compaction"; compaction: Omit<EventPayloads["context.compacted"], "turnId"> };
+
 export type DriverToolEvent =
     | { kind: "started"; id: string; name: string; input: JsonValue }
     | { kind: "completed"; id: string; name: string; output: JsonValue }
@@ -60,8 +78,6 @@ export type TurnRequest<Kind extends AutomatedDriverKind = AutomatedDriverKind>
     systemPrompt: string;
     /** The working directory of the workspace tools, as the model sees it; it may lie on another machine. */
     workspace: string;
-    /** The folder on this machine for the driver's own work, resolved only when a driver needs it. */
-    runtimeDirectory: () => Promise<string>;
     /** Stores an attached file under attachments/ of the workspace, where the workspace tools read it; returns its name there. */
     storeAttachment: (name: string, content: Uint8Array) => Promise<string>;
     tools: readonly RunFunction[];

package/packages/ragents/src/index.ts

@@ -27,6 +27,7 @@ export {
     PluginHost,
     ProfileContributionRegistry,
     PromptContributionRegistry,
+    RunConditionRegistry,
     SessionMetadataContributionRegistry,
     SkillContributionRegistry,
     StartEntryContributionRegistry,
@@ -91,18 +92,19 @@ export { TurnToolset, schemaComplaints, type ToolInvocation } from "./agents/too
 export { claimTurn, workingActorFrom, type ClaimedTurn } from "./agents/turn.ts";
 export { FixedWorkspaces, type Workspaces } from "./agents/workspaces.ts";
 export {
-    AgentSessionDriver,
+    AgentLoopDriver,
     AgentRuntimeManager,
-    createSkillPreloadExtension,
-    skillPreloadExtensionName,
-    turnDispatcherExtensionName,
-    type AgentSessionDriverOptions,
+    agentHookOf,
+    createSkillPreload,
+    skillPreloadHookName,
+    type AgentHook,
+    type AgentLoopDriverOptions,
     type AgentRuntimeContext,
     type AgentRuntimeDiagnostic,
     type AgentRuntimeManagerOptions,
+    type SkillPreload,
     type SkillPreloadConfiguration,
     type SkillPreloadOptions,
-    type AgentSessionStore,
     type SkillCatalogEntry,
     type SkillSelectionRequest,
     type SkillSelector,

package/packages/ragents/src/plugin-host.ts

@@ -1,7 +1,6 @@
 import path from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { InlineExtension } from "@ragents/agent";
-import { agentHookExtension } from "./drivers/agent-hooks.ts";
+import { agentHookOf, type AgentHook } from "./drivers/agent-hooks.ts";
 import { Value } from "typebox/value";
 import { canStartEntry, defaultHttpRights, isAccessRight, unrestrictedAccess, type AccessContext } from "./access.ts";
 import { DomainError } from "./runtime/domain-error.ts";
@@ -42,6 +41,7 @@ import type {
   RAgentsPlugin,
   ServiceToken,
   RegisteredStartOption,
+  RunCondition,
   SessionLifecycleContribution,
   SessionMetadata,
   SessionStartedContext,
@@ -87,6 +87,24 @@ class ContributionRegistry<T extends { id: string }> {
   }
 }
 
+/** Die Laufbedingung je Plugin; ein Plugin ohne gilt in jedem Run. */
+export class RunConditionRegistry {
+  readonly #conditions = new Map<string, RunCondition>();
+
+  register(owner: string, condition: RunCondition): void {
+    if (this.#conditions.has(owner)) throw new Error(`Plugin ${owner} hat bereits eine Laufbedingung`);
+    this.#conditions.set(owner, condition);
+  }
+
+  has(owner: string): boolean {
+    return this.#conditions.has(owner);
+  }
+
+  applies(owner: string, runId: string): boolean {
+    return this.#conditions.get(owner)?.(runId) ?? true;
+  }
+}
+
 export class MethodContributionRegistry {
   readonly #methods = new ContributionRegistry<{ id: string; contribution: MethodContribution }>("Methode");
 
@@ -220,6 +238,11 @@ export class OperationContributionRegistry {
 
 export class AgentContributionRegistry {
   readonly #contributions = new ContributionRegistry<AgentContribution>("Agent-Beitrag");
+  readonly #conditions: RunConditionRegistry;
+
+  constructor(conditions = new RunConditionRegistry()) {
+    this.#conditions = conditions;
+  }
 
   register(owner: string, contributions: readonly AgentContribution[]): void {
     for (const contribution of contributions) {
@@ -230,8 +253,10 @@ export class AgentContributionRegistry {
     this.#contributions.register(owner, contributions);
   }
 
-  resolve(context: AgentContributionContext): readonly InlineExtension[] {
-    return this.#contributions.entries().map(({ value }) => agentHookExtension(value, context));
+  resolve(context: AgentContributionContext): readonly AgentHook[] {
+    return this.#contributions.entries()
+      .filter(({ owner }) => this.#conditions.applies(owner, context.runId))
+      .map(({ value }) => agentHookOf(value, context));
   }
 
   describe(): readonly PublicAgentHookContribution[] {
@@ -247,6 +272,11 @@ export class AgentContributionRegistry {
 
 export class ToolContributionRegistry {
   readonly #contributors: Owned<ToolContributor>[] = [];
+  readonly #conditions: RunConditionRegistry;
+
+  constructor(conditions = new RunConditionRegistry()) {
+    this.#conditions = conditions;
+  }
 
   register(owner: string, contributors: readonly ToolContributor[]): void {
     for (const contributor of contributors) {
@@ -279,7 +309,9 @@ export class ToolContributionRegistry {
   }
 
   entries(): readonly ToolContributor[] {
-    return this.#contributors.map(({ value }) => value);
+    return this.#contributors.map(({ owner, value }) => this.#conditions.has(owner)
+      ? { ...value, runCondition: (runId: string) => this.#conditions.applies(owner, runId) }
+      : value);
   }
 
   describe(): readonly PublicToolDescriptor[] {
@@ -296,6 +328,11 @@ export class ToolContributionRegistry {
 
 export class PromptContributionRegistry {
   readonly #prompts = new ContributionRegistry<PromptContribution>("Prompt-Beitrag");
+  readonly #conditions: RunConditionRegistry;
+
+  constructor(conditions = new RunConditionRegistry()) {
+    this.#conditions = conditions;
+  }
 
   register(owner: string, prompts: readonly PromptContribution[]): void {
     this.#prompts.register(owner, prompts);
@@ -331,10 +368,13 @@ export class PromptContributionRegistry {
     })));
   }
 
-  /** Die Beiträge, die für diesen Run anders lauten als im Schnappschuss; alles andere bleibt der gerenderte Text. */
+  /** Die Beiträge, die für diesen Run anders lauten als im Schnappschuss; ein leerer Text fehlt dort, alles andere bleibt der gerenderte Text. */
   runOverrides(runId: string): ReadonlyMap<string, string> {
-    return new Map([...this.#prompts.entries()].flatMap(({ value }) =>
-      value.renderForRun ? [[value.id, value.renderForRun(runId).trim()] as const] : []));
+    return new Map([...this.#prompts.entries()].flatMap(({ owner, value }) => {
+      if (!this.#conditions.applies(owner, runId)) return [[value.id, ""] as const];
+      const text = value.renderForRun?.(runId);
+      return text === undefined ? [] : [[value.id, text.trim()] as const];
+    }));
   }
 
   static handlebarsContext(context: PromptRenderContext): Record<string, unknown> {
@@ -344,6 +384,11 @@ export class PromptContributionRegistry {
 
 export class SkillContributionRegistry {
   readonly #skills = new ContributionRegistry<SkillContribution>("Skill-Beitrag");
+  readonly #conditions: RunConditionRegistry;
+
+  constructor(conditions = new RunConditionRegistry()) {
+    this.#conditions = conditions;
+  }
 
   register(owner: string, skills: readonly SkillContribution[]): void {
     for (const skill of skills) {
@@ -386,7 +431,7 @@ export class SkillContributionRegistry {
       id: value.id,
       owner,
       audiences: value.audiences ?? allAudiences,
-      paths: await value.paths(context),
+      paths: context && !this.#conditions.applies(owner, context.runId) ? [] : await value.paths(context),
     })));
   }
 }
@@ -1069,10 +1114,11 @@ export class PluginHost {
   readonly channels = new ChannelContributionRegistry();
   readonly http = new HttpContributionRegistry();
   readonly operations = new OperationContributionRegistry();
-  readonly agentRuntime = new AgentContributionRegistry();
-  readonly tools = new ToolContributionRegistry();
-  readonly prompts = new PromptContributionRegistry();
-  readonly skills = new SkillContributionRegistry();
+  readonly runConditions = new RunConditionRegistry();
+  readonly agentRuntime = new AgentContributionRegistry(this.runConditions);
+  readonly tools = new ToolContributionRegistry(this.runConditions);
+  readonly prompts = new PromptContributionRegistry(this.runConditions);
+  readonly skills = new SkillContributionRegistry(this.runConditions);
   readonly startEntries = new StartEntryContributionRegistry();
   readonly profiles = new ProfileContributionRegistry();
   readonly script = new ScriptContributionRegistry();
@@ -1122,6 +1168,7 @@ export class PluginHost {
       agentRuntime: (...entries) => this.agentRuntime.register(manifest.id, entries),
       profiles: (...entries) => this.profiles.register(manifest.id, entries),
       prompts: (...entries) => this.prompts.register(manifest.id, entries),
+      runCondition: (condition) => this.runConditions.register(manifest.id, condition),
       provide: (token, service) => this.#services.provide(manifest.id, token, service),
       service: (token) => this.#services.require(token),
       optionalService: (token) => this.#services.optional(token),

package/packages/ragents/src/plugin-types.ts

@@ -277,10 +277,13 @@ export interface PromptContribution {
   delivery?: "initial" | "on-demand";
   requiresTools?: readonly string[];
   render: (context: PromptRenderContext) => string | Promise<string>;
-  /** Hängt der Beitrag am einzelnen Run, ersetzt dieser Text den von `render` - synchron, damit der Turn ihn ohne Warten hat. */
-  renderForRun?: (runId: string) => string;
+  /** Hängt der Beitrag am einzelnen Run, ersetzt dieser Text den von `render`, undefined behält ihn - synchron, damit der Turn ihn ohne Warten hat. */
+  renderForRun?: (runId: string) => string | undefined;
 }
 
+/** Ob die laufbezogenen Beiträge eines Plugins in einem Run gelten; der Host fragt je Run, ein Wurf lässt dessen Turn mit dieser Ursache scheitern. */
+export type RunCondition = (runId: string) => boolean;
+
 export type ModelProviderConfig = Parameters<ModelRuntime["registerProvider"]>[1];
 
 export interface ModelProviderRegistration {
@@ -420,6 +423,8 @@ export interface PluginRegistration {
   agentRuntime: (...contributions: readonly AgentContribution[]) => void;
   profiles: (...contributions: readonly ProfileContribution[]) => void;
   prompts: (...contributions: readonly PromptContribution[]) => void;
+  /** Prompts, Funktionen, Skills und Agent-Hooks dieses Plugins gelten nur in Runs, für die die Bedingung zutrifft; höchstens eine je Plugin. */
+  runCondition: (condition: RunCondition) => void;
   provide: <T>(token: ServiceToken<T>, service: T) => void;
   service: <T>(token: ServiceToken<T>) => T;
   optionalService: <T>(token: ServiceToken<T>) => T | undefined;

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

@@ -132,6 +132,16 @@ const forkSourceOf = (state: RunState, reference: string): string => {
     if (source.execution.driver.kind !== "agent")
         throw new DomainError("invalid-value", `Fork source ${reference} has no model context to fork.`, 400);
 
+    const finishedContext = [...state.turns.values()].some((turn) =>
+        turn.actorId === source.id && turn.status !== "running" && state.contextTurns.has(turn.id));
+
+    if (source.forkOf === null && !finishedContext)
+        throw new DomainError(
+            "fork-without-turn",
+            `Fork source ${reference} has no model context from a finished turn yet; a fork takes the context of finished turns only, never of the running one.`,
+            409,
+        );
+
     return source.id;
 };
 

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

@@ -1,3 +1,4 @@
+import type { EventPayloads, ModelInputContent, ModelStepBlock, ModelToolResultPart, UncommittedEvent } from "../../domain/events.ts";
 import type { JsonValue } from "../../domain/json.ts";
 import { isPendingActorInput, type TurnUsage } from "../../domain/model.ts";
 import { event, type Decision } from "../command.ts";
@@ -77,7 +78,7 @@ export const steerInputs =
     };
 
 const appendText = (
-    type: "model.output.completed" | "model.output.interrupted" | "model.reasoning.completed" | "runtime.output.recorded",
+    type: "model.output.interrupted" | "runtime.output.recorded",
     actorId: string,
     input: { turnId: string; text: string },
 ): Decision => (state, context) => {
@@ -86,18 +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 appendInterruptedModelOutput = (actorId: string, input: { turnId: string; text: string }): Decision =>
     appendText("model.output.interrupted", 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);
 
+/** 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/journal-storage.ts

@@ -8,9 +8,9 @@ import { isRunId } from "../domain/portable-id.ts";
 import { syncDirectory } from "./durable-fs.ts";
 import type { CommandRecord, JournalCommand } from "./journal.ts";
 
-/** Rises whenever an older stand would reject newly written lines; the encoding is unchanged since 4, so 4 stays readable. */
-export const journalStorageVersion = 6;
-const readableJournalStorageVersions: readonly unknown[] = [4, 5, journalStorageVersion];
+/** 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 };
@@ -161,7 +161,10 @@ export const parseJournalRecord = (line: string, runDirectory: string, location:
     const record = objectOf(parsed, location);
 
     if (!readableJournalStorageVersions.includes(record.formatVersion))
-        throw new Error(`${location} has unsupported journal format version ${String(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 ?? [])];
@@ -571,6 +605,7 @@ export class Journal {
             const semantics = log ? {
                 events: new Map(log.semantics.events),
                 sourcedToolCalls: new Set(log.semantics.sourcedToolCalls),
+                presented: new Set(log.semantics.presented),
             } : eventSemanticContext();
             let state: RunDraft | null = log?.state ? forkProjection(log.state) : null;