@schlenkr/ragents 0.1.6 → 0.1.7

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

@@ -544,13 +544,13 @@ export const agentTools: RunFunction[] = [
             + "It inherits delegable capabilities, but tools is required and never inherited: select exact names, [] for text-only work, or explicit null for an open, dynamically resolved toolset. "
             + "An empty tools array creates a plain LLM with no runtime, workspace or host tools; "
             + "drivers without plain-LLM isolation are rejected. "
-            + "forkOf copies the model context of an existing LLM agent of this run into the new agent at its first turn: the copy ends before any unfinished tool call and carries no reasoning; the new agent still gets its own prompt, tools and model.",
+            + "forkOf gives the new agent an unchanged copy of the model context of an existing LLM agent of this run, up to the end of that agent's last finished turn; nothing of its running turn is copied, and a source without a finished turn is rejected. The new agent still gets its own prompt, tools and model, and its first input follows the copy.",
         schema: Type.Object({
             handle: Type.String({ minLength: 1 }),
             displayName: Type.Optional(Type.String({ minLength: 1, description: "Anzeigename; ohne Angabe der Handle" })),
             description: Type.Optional(Type.String({ minLength: 1, maxLength: actorDescriptionMaxLength, description: "Sehr kurze Beschreibung der Aufgabe für die Übersicht der Beteiligten, wenige Wörter wie \"prüft die Regel zu Kommentaren\"" })),
             prompt: Type.String(),
-            forkOf: Type.Optional(Type.String({ minLength: 1, description: "Handle oder ID eines LLM-Agenten dieses Runs, dessen bisheriger Modellkontext in den neuen Agenten kopiert wird" })),
+            forkOf: Type.Optional(Type.String({ minLength: 1, description: "Handle or ID of an LLM agent of this run whose model context up to the end of its last finished turn is copied into the new agent" })),
             tools: Type.Union([Type.Array(Type.String({ minLength: 1 }), { uniqueItems: true }), Type.Null()], { description: "Required explicit selection: [] for plain text-only work including app-mediated conversations; an array for exact existing tool names; null only when the task needs an open, dynamically resolved toolset. Never inherits the caller's tools. Names of future, not yet activated actor functions are invalid; choose null when those must become available later." }),
             withoutCapabilities: Type.Optional(Type.Array(capabilitySchema, { uniqueItems: true })),
             ...executionSchema,

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

@@ -164,18 +164,46 @@ export class TurnToolset {
         this.tools.splice(0, this.tools.length, ...this.functions.filter((tool) => tool.nativeTool === true));
     }
 
+    /** A model's tool call always lands in the journal: a failure before the start is recorded as start and failure. */
     async invoke(toolCallId: string, name: string, input: JsonValue, modelContext?: string): Promise<ToolInvocation> {
-        await this.refresh();
-        const tool = this.tools.find((entry) => entry.name === name);
+        const prepared = await this.#beforeStart(toolCallId, name, input, async () => {
+            await this.refresh();
+            const tool = this.tools.find((entry) => entry.name === name);
 
-        if (!tool)
-            throw new Error(`Tool ${name} is not available to actor ${this.#turn.actorId}.`);
+            if (!tool)
+                throw new Error(`Tool ${name} is not available to actor ${this.#turn.actorId}.`);
 
-        assertJsonValue(input, `Tool ${name} input`);
-        const tolerated = withoutUnknownFields(tool.schema, input);
-        const output = await this.#execute(toolCallId, tool, tolerated.input, tolerated.ignoredFields, modelContext);
+            assertJsonValue(input, `Tool ${name} input`);
+            const tolerated = withoutUnknownFields(tool.schema, input);
+
+            if (!this.#replayOf(toolCallId) && !Value.Check(tool.schema, tolerated.input))
+                throw new Error(inputComplaint(tool, tolerated.input, tolerated.ignoredFields));
+
+            return { tool, tolerated };
+        });
+        const output = await this.#execute(toolCallId, prepared.tool, prepared.tolerated.input, prepared.tolerated.ignoredFields, modelContext);
+
+        return { output, ignoredFields: prepared.tolerated.ignoredFields };
+    }
+
+    async #beforeStart<T>(toolCallId: string, name: string, input: JsonValue, prepare: () => Promise<T>): Promise<T> {
+        try {
+            return await prepare();
+        } catch (error) {
+            if (this.#replayOf(toolCallId))
+                throw error;
+
+            try {
+                this.#assertActive();
+                assertJsonValue(input, `Tool ${name} input`);
+            } catch {
+                throw error;
+            }
 
-        return { output, ignoredFields: tolerated.ignoredFields };
+            this.#runtime.startToolCall(this.#context(toolCallId, "started"), this.#turn.runId, this.#turn.actorId, { turnId: this.#turn.turnId, toolCallId, name, input });
+            this.#runtime.failToolCall(this.#context(toolCallId, "failed"), this.#turn.runId, this.#turn.actorId, { turnId: this.#turn.turnId, toolCallId, name, error: errorText(error) });
+            throw error;
+        }
     }
 
     async invokeFunction(toolCallId: string, name: string, input: JsonValue): Promise<JsonValue> {
@@ -282,18 +310,17 @@ export class TurnToolset {
     }
 
     #replayOf(toolCallId: string) {
-        const events = this.#runtime.events(this.#turn.runId).filter((event): event is ToolCallEvent => {
-            if (
-                event.type !== "tool.call.started" &&
-                event.type !== "tool.call.completed" &&
-                event.type !== "tool.call.failed"
-            )
-                return false;
-
-            return event.actorId === this.#turn.actorId &&
-                event.payload.turnId === this.#turn.turnId &&
-                event.payload.toolCallId === toolCallId;
-        });
+        const events: ToolCallEvent[] = [];
+
+        for (const event of this.#runtime.recentEvents(this.#turn.runId)) {
+            if (event.type === "turn.started" && event.payload.turnId === this.#turn.turnId)
+                break;
+
+            if ((event.type === "tool.call.started" || event.type === "tool.call.completed" || event.type === "tool.call.failed")
+                && event.actorId === this.#turn.actorId && event.payload.turnId === this.#turn.turnId && event.payload.toolCallId === toolCallId)
+                events.unshift(event);
+        }
+
         const started = events.find((event) => event.type === "tool.call.started");
         const terminal = events.findLast(
             (event) => event.type === "tool.call.completed" || event.type === "tool.call.failed",

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

@@ -2,8 +2,6 @@ export interface Workspaces {
     ensure(runId: string, workspacePath: string | null): string;
     /** How the run's workspace is described to a model; undefined when nothing describes it. */
     description(runId: string): string | undefined;
-    /** The folder on this machine where a driver keeps its own work; the workspace itself may lie on another machine. */
-    runtimeDirectory(runId: string): Promise<string>;
     /** Stores an attached file under attachments/ of the workspace, on the machine where the workspace lies; returns its name there. */
     storeAttachment(runId: string, name: string, content: Uint8Array): Promise<string>;
 }
@@ -23,10 +21,6 @@ export class FixedWorkspaces implements Workspaces {
         return undefined;
     }
 
-    runtimeDirectory() {
-        return Promise.resolve(this.#path);
-    }
-
     storeAttachment(): Promise<string> {
         return Promise.reject(new Error("Ein fester Arbeitsbereich ohne Executor nimmt keine Dateianhänge an."));
     }

package/packages/ragents/src/domain/event-semantics.ts

@@ -20,13 +20,18 @@ export type EventSemanticContext = {
     events: Map<string, JournalEvent>;
     /** Tool calls with a recorded source, by turn and call; their state stands in the turn. */
     sourcedToolCalls: Set<string>;
+    /** Inputs and tool results already presented to the model, by turn and input or call. */
+    presented: Set<string>;
 };
 
 export const eventSemanticContext = (): EventSemanticContext => ({
     events: new Map(),
     sourcedToolCalls: new Set(),
+    presented: new Set(),
 });
 
+const modelContextEventTypes: ReadonlySet<string> = new Set(["model.input.presented", "model.step.completed", "model.tool-result.presented"]);
+
 const existingActorOf = (state: RunState, actorId: string): Actor => {
     const actor = state.actors.get(actorId);
 
@@ -438,6 +443,46 @@ export const assertEventSemantics = (
             break;
         }
 
+        case "model.input.presented": {
+            const turn = runningTurnOf(state, event.payload.turnId);
+            assertTurnAuthor(turn, event);
+
+            if (event.payload.inputId !== null) {
+                const input = state.inputs.get(event.payload.inputId);
+
+                if (!input || input.lifecycle.kind !== "claimed" || input.lifecycle.turnId !== turn.id)
+                    throw new Error(`Input ${event.payload.inputId} does not belong to turn ${turn.id}.`);
+
+                if (context.presented.has(`${turn.id}\0input\0${input.id}`))
+                    throw new Error(`Input ${input.id} was already presented in turn ${turn.id}.`);
+            }
+            break;
+        }
+
+        case "model.tool-result.presented": {
+            const turn = runningTurnOf(state, event.payload.turnId);
+            assertTurnAuthor(turn, event);
+            const call = toolCallOf(turn, event.payload.toolCallId);
+
+            if (call.status === "running")
+                throw new Error(`Tool call ${call.id} in turn ${turn.id} has no result yet.`);
+
+            if (context.presented.has(`${turn.id}\0call\0${call.id}`))
+                throw new Error(`The result of tool call ${call.id} in turn ${turn.id} was already presented.`);
+            break;
+        }
+
+        case "context.compacted": {
+            const turn = runningTurnOf(state, event.payload.turnId);
+            assertTurnAuthor(turn, event);
+            const firstKept = context.events.get(event.payload.firstKeptEventId);
+
+            if (!firstKept || !modelContextEventTypes.has(firstKept.type))
+                throw new Error(`Compaction keeps from ${event.payload.firstKeptEventId}, which is no model context event.`);
+            break;
+        }
+
+        case "model.step.completed":
         case "model.output.completed":
         case "model.output.interrupted":
         case "model.reasoning.completed":
@@ -653,4 +698,10 @@ export const recordEventSemantics = (event: JournalEvent, context: EventSemantic
 
     if (event.type === "tool.call.source")
         context.sourcedToolCalls.add(toolCallKey(event.payload.turnId, event.payload.toolCallId));
+
+    if (event.type === "model.input.presented" && event.payload.inputId !== null)
+        context.presented.add(`${event.payload.turnId}\0input\0${event.payload.inputId}`);
+
+    if (event.type === "model.tool-result.presented")
+        context.presented.add(`${event.payload.turnId}\0call\0${event.payload.toolCallId}`);
 };

package/packages/ragents/src/domain/event-validation.ts

@@ -200,6 +200,98 @@ const usageOf = (value: unknown, path: string) => {
         fail(`${path}.costUsd`, "must not be negative");
 };
 
+const sha256Of = (value: unknown, path: string) => {
+    if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value))
+        fail(path, "must be a lowercase SHA-256");
+};
+
+const modelTextPartOf = (value: unknown, path: string) => {
+    const part = exactObject(value, path, ["type", "text"]);
+    stringOf(part.text, `${path}.text`);
+};
+
+const modelInputPartOf = (value: unknown, path: string) => {
+    const candidate = objectOf(value, path);
+
+    if (candidate.type === "text")
+        return modelTextPartOf(value, path);
+
+    if (candidate.type !== "image" && candidate.type !== "video" && candidate.type !== "file")
+        fail(`${path}.type`, "must be text, image, video or file");
+
+    const part = exactObject(value, path, candidate.type === "file" ? ["type", "mimeType", "filename", "hash"] : ["type", "mimeType", "hash"]);
+    nonEmptyStringOf(part.mimeType, `${path}.mimeType`);
+    sha256Of(part.hash, `${path}.hash`);
+
+    if (candidate.type === "file")
+        stringOf(part.filename, `${path}.filename`);
+};
+
+const modelToolResultPartOf = (value: unknown, path: string) => {
+    const candidate = objectOf(value, path);
+
+    if (candidate.type === "text")
+        return modelTextPartOf(value, path);
+
+    if (candidate.type !== "image")
+        fail(`${path}.type`, "must be text or image");
+
+    const part = exactObject(value, path, ["type", "mimeType", "hash"]);
+    nonEmptyStringOf(part.mimeType, `${path}.mimeType`);
+    sha256Of(part.hash, `${path}.hash`);
+};
+
+const optionalStringOf = (payload: ObjectValue, key: string, path: string) => {
+    if (Object.hasOwn(payload, key))
+        stringOf(payload[key], `${path}.${key}`);
+};
+
+const modelStepBlockOf = (value: unknown, path: string) => {
+    const candidate = objectOf(value, path);
+
+    if (candidate.type === "text") {
+        const block = exactObject(value, path, ["type"], ["text", "textSignature"]);
+        optionalStringOf(block, "text", path);
+        optionalStringOf(block, "textSignature", path);
+        return;
+    }
+
+    if (candidate.type === "thinking") {
+        const block = exactObject(value, path, ["type"], ["thinking", "thinkingSignature", "redacted"]);
+        optionalStringOf(block, "thinking", path);
+        optionalStringOf(block, "thinkingSignature", path);
+
+        if (Object.hasOwn(block, "redacted"))
+            booleanOf(block.redacted, `${path}.redacted`);
+
+        return;
+    }
+
+    if (candidate.type !== "toolCall")
+        fail(`${path}.type`, "must be text, thinking or toolCall");
+
+    const block = exactObject(value, path, ["type", "id", "name", "arguments"], ["thoughtSignature"]);
+    nonEmptyStringOf(block.id, `${path}.id`);
+    stringOf(block.name, `${path}.name`);
+    objectOf(block.arguments, `${path}.arguments`);
+    assertJsonValue(block.arguments, `${path}.arguments`);
+    optionalStringOf(block, "thoughtSignature", path);
+};
+
+const modelStepUsageOf = (value: unknown, path: string) => {
+    const usage = exactObject(value, path, ["input", "output", "cacheRead", "cacheWrite", "totalTokens", "cost"], ["cacheWrite1h", "reasoning"]);
+
+    for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens", "cacheWrite1h", "reasoning"]) {
+        if (Object.hasOwn(usage, key))
+            finiteNumberOf(usage[key], `${path}.${key}`);
+    }
+
+    const cost = exactObject(usage.cost, `${path}.cost`, ["input", "output", "cacheRead", "cacheWrite", "total"]);
+
+    for (const key of Object.keys(cost))
+        finiteNumberOf(cost[key], `${path}.cost.${key}`);
+};
+
 const pluginScopeOf = (value: unknown, path: string) => {
     const candidate = objectOf(value, path);
 
@@ -391,6 +483,80 @@ const payloadOf = (type: EventType, value: unknown, path: string) => {
             return;
         }
 
+        case "model.input.presented": {
+            const payload = exactObject(value, path, ["turnId", "inputId", "content"]);
+            stringOf(payload.turnId, `${path}.turnId`);
+            nullableStringOf(payload.inputId, `${path}.inputId`);
+
+            if (typeof payload.content !== "string")
+                arrayOf(payload.content, `${path}.content`, modelInputPartOf);
+
+            return;
+        }
+
+        case "model.step.completed": {
+            const payload = exactObject(
+                value,
+                path,
+                ["turnId", "api", "provider", "model", "usage", "stopReason", "timestamp", "content"],
+                ["responseModel", "responseId", "errorMessage", "diagnostics"],
+            );
+            stringOf(payload.turnId, `${path}.turnId`);
+            nonEmptyStringOf(payload.api, `${path}.api`);
+            nonEmptyStringOf(payload.provider, `${path}.provider`);
+            nonEmptyStringOf(payload.model, `${path}.model`);
+            optionalStringOf(payload, "responseModel", path);
+            optionalStringOf(payload, "responseId", path);
+            optionalStringOf(payload, "errorMessage", path);
+            modelStepUsageOf(payload.usage, `${path}.usage`);
+
+            if (!["stop", "length", "toolUse", "error"].includes(payload.stopReason as string))
+                fail(`${path}.stopReason`, "must be stop, length, toolUse or error");
+
+            finiteNumberOf(payload.timestamp, `${path}.timestamp`);
+            arrayOf(payload.content, `${path}.content`, modelStepBlockOf);
+
+            if (Object.hasOwn(payload, "diagnostics"))
+                arrayOf(payload.diagnostics, `${path}.diagnostics`, assertJsonValue);
+
+            return;
+        }
+
+        case "model.tool-result.presented": {
+            const payload = exactObject(value, path, ["turnId", "toolCallId", "toolName", "isError"], ["content"]);
+            stringOf(payload.turnId, `${path}.turnId`);
+            nonEmptyStringOf(payload.toolCallId, `${path}.toolCallId`);
+            stringOf(payload.toolName, `${path}.toolName`);
+            booleanOf(payload.isError, `${path}.isError`);
+
+            if (Object.hasOwn(payload, "content"))
+                arrayOf(payload.content, `${path}.content`, modelToolResultPartOf);
+
+            return;
+        }
+
+        case "context.compacted": {
+            const payload = exactObject(value, path, [
+                "turnId",
+                "summary",
+                "firstKeptEventId",
+                "tokensBefore",
+                "provider",
+                "model",
+                "readFiles",
+                "modifiedFiles",
+            ]);
+            stringOf(payload.turnId, `${path}.turnId`);
+            nonEmptyStringOf(payload.summary, `${path}.summary`);
+            nonEmptyStringOf(payload.firstKeptEventId, `${path}.firstKeptEventId`);
+            nonNegativeIntegerOf(payload.tokensBefore, `${path}.tokensBefore`);
+            nonEmptyStringOf(payload.provider, `${path}.provider`);
+            nonEmptyStringOf(payload.model, `${path}.model`);
+            stringArrayOf(payload.readFiles, `${path}.readFiles`);
+            stringArrayOf(payload.modifiedFiles, `${path}.modifiedFiles`);
+            return;
+        }
+
         case "model.output.completed":
         case "model.output.interrupted":
         case "model.reasoning.completed":

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

@@ -17,6 +17,35 @@ import type {
 } from "./model.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": {
         title: string;
@@ -84,6 +113,45 @@ 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;
@@ -198,6 +266,10 @@ export const eventTypeMap: Record<EventType, 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,

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

@@ -215,6 +215,8 @@ 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. */
@@ -241,8 +243,8 @@ export const eventSubjectOf = (state: RunState, event: JournalEvent): ActorId =>
 
 type Collections = "actors" | "inputs" | "turns" | "subscriptions" | "pluginStates" | "actions" | "artifacts";
 
-/** Die Run-Ansicht für Clients; der Eigentümer bleibt serverseitig und steht nicht in ihr. */
-export type RunView = Omit<RunState, Collections | "ownerUserId"> & {
+/** 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[];

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) => {
@@ -129,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(
@@ -349,6 +351,13 @@ export function applyEvent(
         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": {

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

@@ -1,40 +1,27 @@
-import type { InlineExtension } from "@ragents/agent";
-import type { JsonValue } from "../domain/json.ts";
-import type { AgentContribution, AgentContributionContext, AgentHookContext } from "../plugin-types.ts";
+import type {
+  AgentContribution,
+  AgentContributionContext,
+  AgentHookContext,
+  ModelCallContext,
+  ToolCallOutcome,
+  ToolResultReplacement,
+} from "../plugin-types.ts";
 
-const hookContextOf = (context: { signal: AbortSignal | undefined; model: { input: readonly string[] } | undefined }): AgentHookContext => ({
-  signal: context.signal,
-  modelReadsImages: context.model?.input.includes("image") === true,
-});
+/** 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 turns the hooks of a plugin into an extension of the agent runtime; plugins never see the runtime. */
-export const agentHookExtension = (contribution: AgentContribution, agent: AgentContributionContext): InlineExtension => ({
-  name: contribution.id,
-  factory: (api) => {
-    const { beforeModelCall, afterToolCall } = contribution;
-    if (beforeModelCall) {
-      api.on("context", async (event, context) => {
-        const stored = context.sessionManager.getBranch()
-          .filter((entry) => entry.type === "custom" && entry.customType === contribution.id)
-          .at(-1);
-        const note = await beforeModelCall(agent, {
-          ...hookContextOf(context),
-          kept: stored?.type === "custom" ? stored.data as JsonValue : undefined,
-          keep: (value) => api.appendEntry(contribution.id, value),
-        });
-        if (note === undefined) return undefined;
-        return { messages: [...event.messages, { role: "custom" as const, customType: contribution.id, content: note, display: false, timestamp: Date.now() }] };
-      });
-    }
-    if (afterToolCall) {
-      api.on("tool_result", async (event, context) => {
-        const replacement = await afterToolCall(agent, { toolName: event.toolName, isError: event.isError }, hookContextOf(context));
-        if (replacement === undefined) return undefined;
-        return {
-          content: replacement.content.map((part) => ({ ...part })),
-          ...(replacement.isError === undefined ? {} : { isError: replacement.isError }),
-        };
-      });
-    }
-  },
-});
+/** 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) } : {}),
+  };
+};