@schlenkr/ragents 0.1.6 → 0.1.8

package/packages/agent/src/index.ts

@@ -1,20 +1,23 @@
 // Everything the engine, the server and the workspace executor use; the rest is internal.
-export type { AgentSession } from "./core/agent-session.ts";
-export type { ExtensionAPI, ExtensionContext, ExtensionError, InlineExtension, ToolDefinition } from "./core/extensions/index.ts";
-export { defineTool } from "./core/extensions/index.ts";
 export { aliasedModel, type ModelAlias, ModelRuntime } from "./core/model-runtime.ts";
-export { DefaultResourceLoader } from "./core/resource-loader.ts";
+export { type AgentSettings, type AgentSettingsInput, agentSettings } from "./core/agent-settings.ts";
 export {
-	type AgentSessionRuntime,
-	type CreateAgentSessionRuntimeFactory,
-	createAgentSession,
-	createAgentSessionFromServices,
-	createAgentSessionRuntime,
-	createAgentSessionServices,
-} from "./core/sdk.ts";
-export { CURRENT_SESSION_VERSION, type SessionEntry, SessionManager } from "./core/session-manager.ts";
-export type { AgentSettingsInput } from "./core/agent-settings.ts";
-export type { Skill } from "./core/skills.ts";
+	activeContextEntries,
+	type ContextCompaction,
+	type ContextLogEntry,
+	contextMessages,
+	latestCompaction,
+} from "./core/context-log.ts";
+export {
+	calculateContextTokens,
+	compact,
+	estimateContextTokens,
+	prepareCompaction,
+	shouldCompact,
+} from "./core/compaction/index.ts";
+export { convertToLlm } from "./core/messages.ts";
+export { formatSkillsForPrompt, type Skill } from "./core/skills.ts";
+export { defineTool, type ToolDefinition } from "./core/tool-definition.ts";
 export {
 	type BashOperations,
 	createBashToolDefinition,
@@ -22,5 +25,16 @@ export {
 	createReadToolDefinition,
 	createWriteToolDefinition,
 } from "./core/tools/index.ts";
+export {
+	Agent,
+	type AgentEvent,
+	type AgentLoopTurnUpdate,
+	type AgentMessage,
+	type AgentTool,
+	type AgentToolResult,
+	EMPTY_RESPONSE_NUDGE,
+	isRunFailure,
+	type ThinkingLevel,
+} from "./loop/index.ts";
 export { parseFrontmatter, stripFrontmatter } from "./utils/frontmatter.ts";
 export { getShellConfig, killProcessTree, type ShellConfig } from "./utils/shell.ts";

package/packages/agent/src/loop/agent-loop.ts

@@ -715,8 +715,7 @@ function createToolResultMessage(finalized: FinalizedToolCallOutcome): ToolResul
 		role: "toolResult",
 		toolCallId: finalized.toolCall.id,
 		toolName: finalized.toolCall.name,
-		// Untyped tools (JS extensions) can return results without content; normalize
-		// so the null never enters session history or provider payloads.
+		// Untyped tools can return results without content; the null never enters the context.
 		content: finalized.result.content ?? [],
 		details: finalized.result.details,
 		...(finalized.result.addedToolNames?.length ? { addedToolNames: finalized.result.addedToolNames } : {}),

package/packages/agent/src/loop/agent.ts

@@ -123,6 +123,11 @@ type ActiveRun = {
  * `Agent` owns the current transcript, emits lifecycle events, executes tools,
  * and polls its steering source before each model request.
  */
+const runFailures = new WeakSet<object>();
+
+/** Whether a message is the stand-in the agent reports for a failed run; no model produced it. */
+export const isRunFailure = (message: AgentMessage): boolean => runFailures.has(message);
+
 export class Agent {
 	private _state: MutableAgentState;
 	private readonly listeners = new Set<(event: AgentEvent, signal: AbortSignal) => Promise<void> | void>();
@@ -363,7 +368,7 @@ export class Agent {
 	}
 
 	private async handleRunFailure(error: unknown, aborted: boolean): Promise<void> {
-		const failureMessage = {
+		const failureMessage: AgentMessage = {
 			role: "assistant",
 			content: [{ type: "text", text: "" }],
 			api: this._state.model.api,
@@ -373,7 +378,8 @@ export class Agent {
 			stopReason: aborted ? "aborted" : "error",
 			errorMessage: error instanceof Error ? error.message : String(error),
 			timestamp: Date.now(),
-		} satisfies AgentMessage;
+		};
+		runFailures.add(failureMessage);
 		await this.processEvents({ type: "message_start", message: failureMessage });
 		await this.processEvents({ type: "message_end", message: failureMessage });
 		await this.processEvents({ type: "turn_end", message: failureMessage, toolResults: [] });

package/packages/ai/dist/api/ai-sdk.d.ts

@@ -9,5 +9,7 @@ export interface OpenRouterOptions extends StreamOptions {
     reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 }
 export declare const stream: StreamFunction<"openai-completions", OpenRouterOptions>;
+/** Counts cache_control blocks anywhere in the request body, as the provider counts them. */
+export declare const cacheMarksOf: (value: unknown) => number;
 export declare const streamSimple: StreamFunction<"openai-completions", SimpleStreamOptions>;
 //# sourceMappingURL=ai-sdk.d.ts.map

package/packages/ai/dist/types.d.ts

@@ -211,6 +211,8 @@ export interface UserMessage {
     role: "user";
     content: string | UserContent[];
     timestamp: number;
+    /** A note for this one request only; the cache boundary stays in front of it. */
+    transient?: true;
 }
 export interface AssistantMessage {
     role: "assistant";

package/packages/ai/src/api/ai-sdk-messages.ts

@@ -1,4 +1,4 @@
-import type { AssistantModelMessage, FilePart, JSONValue, ModelMessage, UserContent as SdkUserContent } from "ai";
+import type { AssistantModelMessage, FilePart, JSONValue, ModelMessage, ToolResultPart, UserContent as SdkUserContent } from "ai";
 import type { Api, AssistantMessage, Context, Model, UserContent } from "../types.ts";
 import { sanitizeSurrogates } from "../utils/sanitize-unicode.ts";
 import { transformMessages } from "./transform-messages.ts";
@@ -54,21 +54,33 @@ function assistantMessage(message: AssistantMessage): AssistantModelMessage | un
 	};
 }
 
+/** The breakpoint sits on the last lasting block; on a part, because the SDK merges tool messages and copies a message mark onto every result. */
+function markCacheBoundary(message: ModelMessage | undefined, cacheControl: CacheControl): void {
+	if (!message || message.role === "system") return;
+	const lastPart = message.role === "tool" ? message.content.filter((part): part is ToolResultPart => part.type === "tool-result").at(-1)
+		: message.role === "user" && Array.isArray(message.content) ? message.content.at(-1) : undefined;
+	const target = lastPart ?? message;
+	target.providerOptions = { ...target.providerOptions, openrouter: { ...target.providerOptions?.openrouter, cacheControl } };
+}
+
 export function convertMessages(context: Context, model: Model<Api>, cacheControl?: CacheControl): ModelMessage[] {
 	const result: ModelMessage[] = [];
 	if (context.systemPrompt) result.push({ role: "system", content: sanitizeSurrogates(context.systemPrompt),
 		...(cacheControl ? { providerOptions: { openrouter: { cacheControl } } } : {}),
 	});
 	const messages = transformMessages(context.messages, model);
+	let boundary: ModelMessage | undefined;
 	for (let index = 0; index < messages.length; index += 1) {
 		const message = messages[index]!;
 		if (message.role === "user") {
 			const content = typeof message.content === "string" ? sanitizeSurrogates(message.content)
 				: message.content.filter((part) => part.type !== "text" || part.text.length > 0).map(userContent);
 			if (typeof content === "string" || content.length > 0) result.push({ role: "user", content });
+			if (!message.transient) boundary = result.at(-1);
 		} else if (message.role === "assistant") {
 			const converted = assistantMessage(message);
 			if (converted) result.push(converted);
+			boundary = result.at(-1);
 		} else {
 			const images: FilePart[] = [];
 			while (messages[index]?.role === "toolResult") {
@@ -87,16 +99,9 @@ export function convertMessages(context: Context, model: Model<Api>, cacheContro
 			}
 			index -= 1;
 			if (images.length > 0) result.push({ role: "user", content: [{ type: "text", text: "Attached image(s) from tool result:" }, ...images] });
+			boundary = result.at(-1);
 		}
 	}
-	if (cacheControl) {
-		const lastMessage = [...result].reverse().find((message) => (message.role === "user" || message.role === "assistant")
-			&& (typeof message.content === "string" ? message.content.length > 0
-				: message.content.some((part) => part.type === "text")));
-		if (lastMessage) lastMessage.providerOptions = {
-			...lastMessage.providerOptions,
-			openrouter: { ...lastMessage.providerOptions?.openrouter, cacheControl },
-		};
-	}
+	if (cacheControl) markCacheBoundary(boundary, cacheControl);
 	return result;
 }

package/packages/ai/src/api/ai-sdk.ts

@@ -261,8 +261,19 @@ function applyRequestCompatibility(payload: unknown, model: Model<"openai-comple
 	}
 	if (cacheControl && body.tools?.length) body.tools[body.tools.length - 1].cache_control = cacheControl;
 	if (!body.tools && body.messages.some((message) => message.role === "tool")) body.tools = [];
+	const marks = cacheMarksOf(body);
+	if (marks > MAX_CACHE_MARKS) throw new Error(`The request carries ${marks} cache marks; Anthropic accepts at most ${MAX_CACHE_MARKS}.`);
 }
 
+const MAX_CACHE_MARKS = 4;
+
+/** Counts cache_control blocks anywhere in the request body, as the provider counts them. */
+export const cacheMarksOf = (value: unknown): number => {
+	if (Array.isArray(value)) return value.reduce((sum: number, item) => sum + cacheMarksOf(item), 0);
+	if (!value || typeof value !== "object") return 0;
+	return Object.entries(value).reduce((sum, [key, item]) => sum + (key === "cache_control" && item ? 1 : cacheMarksOf(item)), 0);
+};
+
 export const streamSimple: StreamFunction<"openai-completions", SimpleStreamOptions> = (model, context, options) => {
 	const reasoning = options?.reasoning ? clampThinkingLevel(model, options.reasoning) : undefined;
 	return stream(model, context, {

package/packages/ai/src/api/transform-messages.ts

@@ -31,7 +31,7 @@ export function transformMessages<TApi extends Api>(
 	// Build a map of original tool call IDs to normalized IDs
 	const toolCallIdMap = new Map<string, string>();
 	// Normalize null/undefined content from untyped callers (custom tools, hand-built
-	// histories, old session files) so downstream code can rely on the type contract.
+	// histories) so downstream code can rely on the type contract.
 	const normalizedMessages = messages.map((msg) => (msg.content == null ? { ...msg, content: [] } : msg));
 	validateInputModalities(normalizedMessages, model);
 

package/packages/ai/src/types.ts

@@ -261,6 +261,8 @@ export interface UserMessage {
 	role: "user";
 	content: string | UserContent[];
 	timestamp: number; // Unix timestamp in milliseconds
+	/** A note for this one request only; the cache boundary stays in front of it. */
+	transient?: true;
 }
 
 export interface AssistantMessage {

package/packages/ai/src/utils/retry.ts

@@ -97,5 +97,19 @@ export function isRetryableAssistantError(message: AssistantMessage): boolean {
 	if (message.stopReason !== "error" || !message.errorMessage) return false;
 	const errorMessage = message.errorMessage;
 	if (NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN.test(errorMessage)) return false;
+	if (isDeterministicClientError(errorMessage)) return false;
 	return RETRYABLE_PROVIDER_ERROR_PATTERN.test(errorMessage);
 }
+
+const RETRYABLE_CLIENT_STATUSES = new Set([408, 409, 429]);
+
+/** The status leads the formatted error ("400: body", "Relay url (400): body"), sits in a JSON body ("code"/"status": 400) or follows "HTTP". */
+const ERROR_STATUS_PATTERN = /^(\d{3}): |\((\d{3})\): |"(?:code|status)"\s*:\s*(\d{3})\b|\bHTTP\s*(\d{3})\b/i;
+
+/** A rejected request fails the same way again: 4xx other than timeout, conflict and throttling, or Anthropic's invalid_request_error. */
+function isDeterministicClientError(errorMessage: string): boolean {
+	if (/invalid_request_error/.test(errorMessage)) return true;
+	const match = ERROR_STATUS_PATTERN.exec(errorMessage);
+	const status = Number(match?.slice(1).find((group) => group !== undefined));
+	return status >= 400 && status < 500 && !RETRYABLE_CLIENT_STATUSES.has(status);
+}

package/packages/ragents/src/agents/actor-input.ts

@@ -61,6 +61,21 @@ const eventPayloads = {
     "turn.interrupted": payloadOf<"turn.interrupted">({
         turnId: Type.String({ description: "ID des unterbrochenen Turns" }),
     }),
+    "model.input.presented": payloadOf<"model.input.presented">({
+        turnId: Type.String({ description: "Turn in which the model was given the input" }),
+    }),
+    "model.step.completed": payloadOf<"model.step.completed">({
+        turnId: Type.String({ description: "Turn the model step belongs to" }),
+        stopReason: Type.String(),
+    }),
+    "model.tool-result.presented": payloadOf<"model.tool-result.presented">({
+        turnId: Type.String(),
+        toolCallId: Type.String({ description: "ID of the tool call" }),
+    }),
+    "context.compacted": payloadOf<"context.compacted">({
+        turnId: Type.String({ description: "Turn in which the context was compacted" }),
+        tokensBefore: Type.Integer(),
+    }),
     "model.output.completed": payloadOf<"model.output.completed">({
         turnId: Type.String({ description: "Turn, zu dem die Ausgabe gehört" }),
     }),

package/packages/ragents/src/agents/model-context.ts

@@ -0,0 +1,360 @@
+import {
+    contextMessages,
+    latestCompaction,
+    type AgentMessage,
+    type ContextLogEntry,
+} from "@ragents/agent";
+import type { AssistantMessage, ImageContent, TextContent, ToolResultMessage, UserContent, UserMessage } from "@ragents/ai";
+
+import type { EventPayloads, JournalEvent, ModelInputContent, ModelToolResultPart } from "../domain/events.ts";
+import type { JsonValue } from "../domain/json.ts";
+import { pluginStateKey } from "../domain/model.ts";
+import { derivedToolResultText } from "../domain/tool-result-text.ts";
+import type { ModelContextRecord, TurnRequest } from "../drivers/types.ts";
+import type { Orchestration } from "../runtime/orchestration.ts";
+import type { ClaimedTurn } from "./turn.ts";
+
+/** Reads the bytes behind a stored media hash as Base64. */
+export type MediaSource = (hash: string) => string;
+
+/** The model context of one actor, projected from the journal; `key` changes with every compaction. */
+export type ModelContext = {
+    readonly entries: readonly ContextLogEntry[];
+    readonly messages: readonly AgentMessage[];
+    readonly key: string;
+};
+
+type ToolEvent = Extract<JournalEvent, { type: "tool.call.completed" | "tool.call.failed" }>;
+
+const timeOf = (event: JournalEvent) => Date.parse(event.occurredAt);
+
+const userContentOf = (content: ModelInputContent, media: MediaSource): string | UserContent[] =>
+    typeof content === "string"
+        ? content
+        : content.map((part): UserContent => {
+            if (part.type === "text") return part;
+            if (part.type === "file") return { type: "file", data: media(part.hash), mimeType: part.mimeType, filename: part.filename };
+            return { type: part.type, data: media(part.hash), mimeType: part.mimeType };
+        });
+
+const toolResultContentOf = (content: readonly ModelToolResultPart[], media: MediaSource): (TextContent | ImageContent)[] =>
+    content.map((part) => part.type === "text" ? part : { type: "image", data: media(part.hash), mimeType: part.mimeType });
+
+const assistantMessageOf = (
+    event: Extract<JournalEvent, { type: "model.step.completed" }>,
+    observed: readonly JournalEvent[],
+): AssistantMessage => {
+    const texts = observed.filter((entry) => entry.type === "model.output.completed").map((entry) => entry.payload.text as string);
+    const thoughts = observed.filter((entry) => entry.type === "model.reasoning.completed").map((entry) => entry.payload.text as string);
+    const next = (queue: string[], kind: string) => {
+        const value = queue.shift();
+
+        if (value === undefined)
+            throw new Error(`Model step ${event.eventId} misses the ${kind} of one of its blocks in its command.`);
+
+        return value;
+    };
+    const { turnId: _turnId, content, ...step } = event.payload;
+    const message: AssistantMessage = {
+        role: "assistant",
+        ...step,
+        content: content.map((block) => {
+            if (block.type === "text")
+                return block.text === undefined ? { ...block, text: next(texts, "text") } : { ...block, text: block.text };
+
+            if (block.type === "thinking")
+                return block.thinking === undefined ? { ...block, thinking: next(thoughts, "reasoning") } : { ...block, thinking: block.thinking };
+
+            return block;
+        }),
+    } as unknown as AssistantMessage;
+
+    if (texts.length > 0 || thoughts.length > 0)
+        throw new Error(`Model step ${event.eventId} has observation events that none of its blocks takes.`);
+
+    return message;
+};
+
+/** The context log of one actor from its own events, built event by event. */
+class OwnContextLog {
+    readonly entries: ContextLogEntry[] = [];
+    readonly #actorId: string;
+    readonly #media: MediaSource;
+    readonly #toolResults = new Map<string, ToolEvent>();
+    readonly #observedByCommand = new Map<string, JournalEvent[]>();
+
+    constructor(actorId: string, media: MediaSource) {
+        this.#actorId = actorId;
+        this.#media = media;
+    }
+
+    /** Takes one event of the run; true when the context of the actor changed. */
+    apply(event: JournalEvent): boolean {
+        if (event.actorId !== this.#actorId)
+            return false;
+
+        switch (event.type) {
+            case "tool.call.completed":
+            case "tool.call.failed":
+                this.#toolResults.set(`${event.payload.turnId}\0${event.payload.toolCallId}`, event);
+                return false;
+
+            case "model.output.completed":
+            case "model.reasoning.completed":
+                this.#observedByCommand.set(event.commandId, [...(this.#observedByCommand.get(event.commandId) ?? []), event]);
+                return false;
+
+            case "model.input.presented": {
+                const message: UserMessage = { role: "user", content: userContentOf(event.payload.content, this.#media), timestamp: timeOf(event) };
+                this.entries.push({ kind: "message", id: event.eventId, message });
+                return true;
+            }
+
+            case "model.step.completed":
+                this.entries.push({ kind: "message", id: event.eventId, message: assistantMessageOf(event, this.#observedByCommand.get(event.commandId) ?? []) });
+                this.#observedByCommand.delete(event.commandId);
+                return true;
+
+            case "model.tool-result.presented": {
+                const key = `${event.payload.turnId}\0${event.payload.toolCallId}`;
+                this.entries.push({ kind: "message", id: event.eventId, message: toolResultMessageOf(event, this.#toolResults, this.#media) });
+                this.#toolResults.delete(key);
+                return true;
+            }
+
+            case "context.compacted":
+                this.entries.push({
+                    kind: "compaction",
+                    id: event.eventId,
+                    summary: event.payload.summary,
+                    firstKeptId: event.payload.firstKeptEventId,
+                    tokensBefore: event.payload.tokensBefore,
+                    timestamp: timeOf(event),
+                    readFiles: [...event.payload.readFiles],
+                    modifiedFiles: [...event.payload.modifiedFiles],
+                });
+                return true;
+
+            default:
+                return false;
+        }
+    }
+}
+
+const ownEntries = (events: readonly JournalEvent[], actorId: string, media: MediaSource): ContextLogEntry[] => {
+    const log = new OwnContextLog(actorId, media);
+
+    for (const event of events)
+        log.apply(event);
+
+    return log.entries;
+};
+
+const toolResultMessageOf = (
+    event: Extract<JournalEvent, { type: "model.tool-result.presented" }>,
+    toolResults: ReadonlyMap<string, ToolEvent>,
+    media: MediaSource,
+): ToolResultMessage => {
+    const payload: EventPayloads["model.tool-result.presented"] = event.payload;
+    let content: (TextContent | ImageContent)[];
+
+    if (payload.content) {
+        content = toolResultContentOf(payload.content, media);
+    } else {
+        const result = toolResults.get(`${payload.turnId}\0${payload.toolCallId}`);
+
+        if (!result)
+            throw new Error(`Tool result ${event.eventId} names call ${payload.toolCallId}, which has no recorded result.`);
+
+        content = [{ type: "text", text: derivedToolResultText(result) }];
+    }
+
+    return {
+        role: "toolResult",
+        toolCallId: payload.toolCallId,
+        toolName: payload.toolName,
+        content,
+        isError: payload.isError,
+        timestamp: timeOf(event),
+    };
+};
+
+/** Where a fork cuts its source: before the source's turn that was still running at the spawn, else at the spawn. */
+const forkCut = (events: readonly JournalEvent[], source: string, spawnSequence: number): number => {
+    const running = new Map<string, number>();
+
+    for (const event of events) {
+        if (event.sequence >= spawnSequence)
+            break;
+
+        if (event.type === "turn.started" && event.actorId === source)
+            running.set(event.payload.turnId, event.sequence);
+        else if (event.type === "turn.finished" || event.type === "turn.interrupted")
+            running.delete(event.payload.turnId);
+    }
+
+    return Math.min(spawnSequence, ...running.values());
+};
+
+/** What a fork took over from its source: an unchanged copy of the context of the source's finished turns. */
+const inheritedEntries = (events: readonly JournalEvent[], actorId: string, media: MediaSource): ContextLogEntry[] => {
+    const spawn = events.find((event): event is Extract<JournalEvent, { type: "agent.spawned" }> =>
+        event.type === "agent.spawned" && event.payload.agentId === actorId);
+    const source = spawn?.payload.forkOf;
+
+    if (!source)
+        return [];
+
+    const cut = forkCut(events, source, spawn.sequence);
+    const inherited = modelContextLog(events.filter((event) => event.sequence < cut), source, media);
+
+    if (inherited.length === 0)
+        throw new Error(`Fork source ${source} had no model context from a finished turn at the spawn.`);
+
+    return inherited;
+};
+
+/** The context log of an actor, including the part a fork took over from its source at its spawn. */
+export const modelContextLog = (events: readonly JournalEvent[], actorId: string, media: MediaSource): ContextLogEntry[] =>
+    [...inheritedEntries(events, actorId, media), ...ownEntries(events, actorId, media)];
+
+const contextOf = (entries: ContextLogEntry[], conversation: string): ModelContext => ({
+    entries,
+    messages: contextMessages(entries),
+    key: `${conversation}:${latestCompaction(entries)?.id ?? ""}`,
+});
+
+/** The model context of an actor as a pure projection of the journal; no rendering, only stored forms. */
+export const modelContextOf = (events: readonly JournalEvent[], actorId: string, media: MediaSource): ModelContext =>
+    contextOf(modelContextLog(events, actorId, media), events.find((event) => event.type === "run.created")?.eventId ?? "");
+
+const deepFreeze = <T>(value: T): T => {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return value;
+
+    for (const entry of Object.values(value))
+        deepFreeze(entry);
+
+    return Object.freeze(value);
+};
+
+/** The events of a run as the journal holds them; the sequence counts from 1 without gaps. */
+export type ModelContextSource = {
+    eventsSince: (runId: string, sequence: number) => readonly JournalEvent[];
+    firstEventId: (runId: string) => string | undefined;
+    media: MediaSource;
+};
+
+type CachedContext = {
+    conversation: string;
+    sequence: number;
+    inherited: ContextLogEntry[];
+    own: OwnContextLog;
+    context: ModelContext | null;
+};
+
+/** The model contexts of actors in a turn, extended by new events only; always equal to `modelContextOf` over the journal. */
+export class ModelContexts {
+    readonly #source: ModelContextSource;
+    readonly #runs = new Map<string, Map<string, CachedContext>>();
+
+    constructor(source: ModelContextSource) {
+        this.#source = source;
+    }
+
+    contextOf(runId: string, actorId: string): ModelContext {
+        const actors = this.#runs.get(runId) ?? new Map<string, CachedContext>();
+        const conversation = this.#source.firstEventId(runId) ?? "";
+        let cached = actors.get(actorId);
+
+        if (!cached || cached.conversation !== conversation) {
+            const events = this.#source.eventsSince(runId, 0);
+            cached = {
+                conversation,
+                sequence: 0,
+                inherited: deepFreeze(inheritedEntries(events, actorId, this.#source.media)),
+                own: new OwnContextLog(actorId, this.#source.media),
+                context: null,
+            };
+            this.#extend(cached, events);
+        } else {
+            this.#extend(cached, this.#source.eventsSince(runId, cached.sequence));
+        }
+
+        actors.set(actorId, cached);
+        this.#runs.set(runId, actors);
+        cached.context ??= deepFreeze(contextOf([...cached.inherited, ...cached.own.entries], conversation));
+
+        return cached.context;
+    }
+
+    forget(runId: string) {
+        this.#runs.delete(runId);
+    }
+
+    /** Drops what an actor holds once its turn ended; the next turn builds its context once from the journal. */
+    forgetActor(runId: string, actorId: string) {
+        const actors = this.#runs.get(runId);
+        actors?.delete(actorId);
+
+        if (actors?.size === 0)
+            this.#runs.delete(runId);
+    }
+
+    /** How many actor contexts are held; only actors in a running turn keep one. */
+    get size() {
+        return [...this.#runs.values()].reduce((sum, actors) => sum + actors.size, 0);
+    }
+
+    #extend(cached: CachedContext, events: readonly JournalEvent[]) {
+        for (const event of events) {
+            if (event.sequence !== cached.sequence + 1)
+                throw new Error(`The model context expected event ${cached.sequence + 1} and got ${event.sequence}.`);
+
+            cached.sequence = event.sequence;
+
+            if (cached.own.apply(event))
+                cached.context = null;
+        }
+    }
+}
+
+/** How a turn of an LLM actor reads and writes its model context in the journal; `next` numbers the commands of the turn. */
+export const turnModelContext = (
+    runtime: Orchestration,
+    turn: ClaimedTurn,
+    next: () => number,
+): Pick<TurnRequest<"agent">, "modelContext" | "recordContext" | "hookState"> => {
+    const { runId, actorId, turnId } = turn;
+    const context = (kind: string) => ({ actorId, commandId: `scheduler:${turnId}:context:${kind}:${next()}`, turnId, correlationId: turnId });
+
+    return {
+        modelContext: () => runtime.modelContext(runId, actorId),
+        recordContext: (entry: ModelContextRecord) => {
+            if (entry.kind === "input")
+                runtime.presentModelInput(context(entry.kind), runId, actorId, { turnId, inputId: entry.inputId, content: entry.content });
+            else if (entry.kind === "step")
+                runtime.completeModelStep(context(entry.kind), runId, actorId, { turnId, step: entry.step });
+            else if (entry.kind === "tool-result")
+                runtime.presentToolResult(context(entry.kind), runId, actorId, {
+                    turnId,
+                    toolCallId: entry.toolCallId,
+                    toolName: entry.toolName,
+                    isError: entry.isError,
+                    content: entry.content,
+                });
+            else
+                runtime.compactContext(context(entry.kind), runId, actorId, { turnId, ...entry.compaction });
+        },
+        hookState: {
+            kept: (hookId: string) => runtime.select(runId, (state) => state.pluginStates.get(pluginStateKey(hookId, { kind: "actor", actorId }))?.state),
+            keep: (hookId: string, value: JsonValue) => {
+                runtime.replacePluginState(
+                    { actorId: runtime.select(runId, (state) => state.ownerId), commandId: `scheduler:${turnId}:hook:${hookId}:${next()}`, turnId },
+                    runId,
+                    { pluginId: hookId, scope: { kind: "actor", actorId }, state: value },
+                );
+            },
+        },
+    };
+};

package/packages/ragents/src/agents/plugins.ts

@@ -19,6 +19,8 @@ export type ToolContributor = {
     name: string;
     descriptors: readonly ToolDescriptor[];
     dynamic?: boolean;
+    /** Ob die Werkzeuge in einem Run gelten; ohne Angabe in jedem, sonst fehlen sie dort ganz. */
+    runCondition?: (runId: string) => boolean;
     tools: (context: PluginContext) => readonly RunFunction[] | Promise<readonly RunFunction[]>;
 };
 
@@ -74,6 +76,9 @@ export class ToolRegistry implements ToolProvider {
         const taken = new Set(agentTools.map((entry) => entry.name));
 
         for (const plugin of this.#plugins) {
+            if (plugin.runCondition && !plugin.runCondition(context.runId))
+                continue;
+
             const tools = await plugin.tools(context);
             this.#assertDescriptors(plugin, tools);