@schlenkr/ragents 0.1.6 → 0.1.7

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

@@ -91,18 +91,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";
@@ -230,8 +229,8 @@ 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().map(({ value }) => agentHookOf(value, context));
   }
 
   describe(): readonly PublicAgentHookContribution[] {

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;