@qwen-code/arena-agent 0.0.10-dev.0 → 0.0.10-dev.10

package/dist/agent.js

@@ -1,18 +1,70 @@
 import crypto from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { supportsModelInput, } from "./config.js";
-import { compactMessagesIfNeeded } from "./compaction.js";
+import { compactMessagesIfNeeded, maintainSessionMemory, contextFromHistory, sessionMemoryMatchesHistory, settleSessionMemory, storedSessionMemory } from "./compaction.js";
 import { ANTHROPIC_INCOMPLETE_STREAM_ERROR_CODE } from "./anthropic.js";
-import { modelCallLogPath } from "./history.js";
+import { modelCallLogPath, withoutLeadingSystemMessage } from "./history.js";
 import { MockModelClient } from "./mock.js";
 import { contentPartMediaTypes, JsonlModelCallDiagnostics, } from "./model-diagnostics.js";
 import { RESPONSES_CAPACITY_ERROR_CODE, RESPONSES_TRANSIENT_ERROR_CODE, } from "./openai-responses.js";
 import { HttpModelClient, ModelCapabilityError } from "./provider.js";
+import { RepetitiveOutputDetector } from "./repetitive-output.js";
 import { detectRepoContext } from "./repo.js";
 import { isCodeArenaMode } from "./mode.js";
-import { defaultClientContext, initialMessages, interruptedUserMessage, isCanonicalSystemMessage, repoContextFromSystemMessage, repoSystemMessage, systemMessage, } from "./spec.js";
-import { ToolExecutor } from "./tools.js";
+import { defaultClientContext, interruptedUserMessage, repoSystemMessage, systemMessage, } from "./spec.js";
+import { imageInputFallbackConnection, ToolExecutor, } from "./tools.js";
 import { initializeWorkspace } from "./workspace.js";
+import { checkpointAction, } from "./midturn-checkpoint-hook.js";
+function wrapMalformedToolArguments(argumentsText) {
+    try {
+        JSON.parse(argumentsText);
+        return argumentsText;
+    }
+    catch {
+        return JSON.stringify({ __malformedToolArguments: argumentsText });
+    }
+}
+/** Keep Agent Arena history replayable without losing the model's invalid input. */
+function normalizeToolCallHistory(message, mode) {
+    if (isCodeArenaMode(mode) || message.role !== "assistant")
+        return message;
+    // A failed Responses stream can retain completed native items without the
+    // assembled tool_calls batch. Restore their identities so resume can pair
+    // them with interrupted results instead of replaying orphaned calls.
+    const calls = message.tool_calls?.length ? message.tool_calls
+        : message.openai_response_items?.flatMap((item) => item.type === "function_call" && typeof item.call_id === "string" &&
+            typeof item.name === "string" && typeof item.arguments === "string"
+            ? [{ id: item.call_id, type: "function", function: { name: item.name, arguments: item.arguments } }]
+            : []) ?? message.tool_calls;
+    let changed = Boolean(calls?.length && calls !== message.tool_calls);
+    const toolCalls = calls?.map((call) => {
+        if (typeof call.function?.arguments !== "string")
+            return call;
+        const argumentsText = wrapMalformedToolArguments(call.function.arguments);
+        if (argumentsText === call.function.arguments)
+            return call;
+        changed = true;
+        return { ...call, function: { ...call.function, arguments: argumentsText } };
+    });
+    // Native Responses replays these items instead of tool_calls. Normalize both
+    // representations while leaving reasoning and other opaque items intact.
+    const responseItems = message.openai_response_items?.map((item) => {
+        if (item.type !== "function_call" || typeof item.arguments !== "string")
+            return item;
+        const argumentsText = wrapMalformedToolArguments(item.arguments);
+        if (argumentsText === item.arguments)
+            return item;
+        changed = true;
+        return { ...item, arguments: argumentsText };
+    });
+    return changed
+        ? {
+            ...message,
+            ...(toolCalls ? { tool_calls: toolCalls } : {}),
+            ...(responseItems ? { openai_response_items: responseItems } : {}),
+        }
+        : message;
+}
 function parseToolResult(content) {
     try {
         return JSON.parse(content);
@@ -142,6 +194,11 @@ function preflightUnsupportedMedia(config, messages) {
         !isCodeArenaMode(config.mode);
     return replaceUnsupportedMedia(messages, mediaTypes, imageReadFileFallback);
 }
+function modelContextFromTrajectory(messages) {
+    return contextFromHistory(messages).map((message) => message.role === "user" && Array.isArray(message.content)
+        ? { ...message, content: structuredClone(message.content) }
+        : message);
+}
 function completeInterruptedToolCalls(messages) {
     const completed = [];
     let pending = [];
@@ -176,6 +233,13 @@ function completeInterruptedToolCalls(messages) {
     flushPending();
     return completed;
 }
+export function isContinuableHistory(messages) {
+    const last = messages.at(-1);
+    return Boolean(last &&
+        (last.role === "user" ||
+            last.role === "tool" ||
+            (last.role === "assistant" && Boolean(last.tool_calls?.length))));
+}
 const identityModelsWithQwen = "Claude, ChatGPT, Gemini, Grok, Qwen, and Kimi";
 const identityModelsWithoutQwen = "Claude, ChatGPT, Gemini, Grok, and Kimi";
 const arenaWorkspaceIdentityOpening = "You are a helpful agentic assistant with tool access running on Arena.ai's Agent Mode.";
@@ -209,19 +273,12 @@ function withAppendedSystemPrompt(content, appendix) {
             : "\n\n";
     return `${content}${separator}${appendix}`;
 }
-function applySystemPromptConfig(message, config, preserveExistingAppendix = false) {
+function applySystemPromptConfig(message, config) {
     if (message?.role !== "system" || typeof message.content !== "string") {
         return;
     }
     const appendix = config.appendSystemPrompt;
-    const existingAppendix = preserveExistingAppendix &&
-        appendix &&
-        message.content.endsWith(`\n\n${appendix}`)
-        ? appendix
-        : undefined;
-    let content = existingAppendix
-        ? message.content.slice(0, -existingAppendix.length)
-        : message.content;
+    let content = message.content;
     if (typeof config.systemPrompt === "string") {
         content = config.systemPrompt;
     }
@@ -234,11 +291,7 @@ function applySystemPromptConfig(message, config, preserveExistingAppendix = fal
             ? content.replace(identityModelsWithQwen, identityModelsWithoutQwen)
             : content.replace(identityModelsWithoutQwen, identityModelsWithQwen);
     }
-    const reuseExistingAppendix = existingAppendix && typeof config.systemPrompt !== "string";
-    if (reuseExistingAppendix) {
-        content += existingAppendix;
-    }
-    if (appendix !== undefined && !reuseExistingAppendix) {
+    if (appendix !== undefined) {
         content = withAppendedSystemPrompt(content, appendix);
     }
     message.content = content;
@@ -253,20 +306,33 @@ class PartialAssistantTurnError extends Error {
         this.name = "PartialAssistantTurnError";
     }
 }
-// Mode is fixed at the first turn: resume reads it back from the history's
-// system message, so a mid-session clone or detached HEAD cannot flip it.
-// Exported so the replay script checks the same decision instead of redoing it.
-export function resolveRepoContext(workspace, history, mode = "arena") {
-    if (isCodeArenaMode(mode))
-        return undefined;
-    return history?.length
-        ? repoContextFromSystemMessage(history[0])
-        : detectRepoContext(workspace);
+class CheckpointExit extends Error {
+    event;
+    constructor(event) {
+        super("model generation stopped by checkpoint hook");
+        this.event = event;
+    }
+}
+class CheckpointFailure extends Error {
+    cause;
+    constructor(cause) {
+        super(describeError(cause));
+        this.cause = cause;
+    }
+}
+// Rebuild the runtime repo context from the current workspace on every run.
+// The history argument is retained for callers; it never supplies runtime state.
+export function resolveRepoContext(workspace, _history, mode = "arena") {
+    return isCodeArenaMode(mode) ? undefined : detectRepoContext(workspace);
 }
 export class Agent {
     config;
     sink;
     options;
+    checkpointQueue = Promise.resolve();
+    checkpointError;
+    persistedMemory;
+    memoryCache;
     client;
     tools;
     workspaceContext;
@@ -276,40 +342,58 @@ export class Agent {
         this.config = config;
         this.sink = sink;
         this.options = options;
+        this.memoryCache = options.sessionMemory || {};
         this.sessionId =
             options.sessionId || crypto.randomUUID().replaceAll("-", "");
         this.sessionAffinityId = options.sessionAffinityId || crypto.randomUUID();
-        this.workspaceContext =
-            options.workspaceContext ||
-                (isCodeArenaMode(config.mode)
-                    ? {
-                        root: config.workspace,
-                        cwd: config.workspace,
-                        presentFile: false,
-                    }
-                    : undefined);
+        // Local workspace guidance is explicit opt-in. Code Arena defaults must
+        // send the captured prompt; Agent Arena already used this same opt-in path.
+        this.workspaceContext = options.workspaceContext;
+        const fallbackConnection = config.imageInputFallbackModel
+            ? imageInputFallbackConnection(config)
+            : undefined;
+        const needsMainHttpClient = !options.client && !config.model.startsWith("mock/");
+        const needsFallbackHttpClient = Boolean(fallbackConnection) && !options.imageInputFallbackClient;
+        const diagnostics = config.modelCallLogging === false ||
+            (!needsMainHttpClient && !needsFallbackHttpClient)
+            ? undefined
+            : new JsonlModelCallDiagnostics(modelCallLogPath(config.stateRoot, config.tenantId, this.sessionId));
         this.client =
             options.client ||
                 (config.model.startsWith("mock/")
                     ? new MockModelClient()
                     : new HttpModelClient(config, {
                         sessionAffinityId: this.sessionAffinityId,
-                        ...(config.modelCallLogging === false
-                            ? {}
-                            : {
-                                diagnostics: new JsonlModelCallDiagnostics(modelCallLogPath(config.stateRoot, config.tenantId, this.sessionId)),
-                            }),
+                        ...(diagnostics ? { diagnostics } : {}),
                     }));
+        const imageInputFallbackClient = options.imageInputFallbackClient ||
+            (fallbackConnection
+                ? new HttpModelClient(config, {
+                    connection: fallbackConnection,
+                    sessionAffinityId: this.sessionAffinityId,
+                    ...(diagnostics ? { diagnostics } : {}),
+                })
+                : undefined);
         this.tools =
             options.tools ||
                 new ToolExecutor(config, {
                     modelClient: this.client,
+                    imageInputFallbackClient,
                     signal: options.signal,
                     askUserHandler: options.askUserHandler,
                     workspaceContext: this.workspaceContext,
                 });
     }
     async run(prompt, history, runOptions = {}) {
+        try {
+            return await this.runTurn(prompt, history, runOptions);
+        }
+        finally {
+            await settleSessionMemory(this.memoryCache);
+            await this.checkpointQueue;
+        }
+    }
+    async runTurn(prompt, history, runOptions) {
         if (runOptions.resumeFromHistory && !history?.length) {
             throw new Error("resumeFromHistory requires a non-empty history");
         }
@@ -323,57 +407,66 @@ export class Agent {
             : structuredClone(baseUserMessage);
         const clientContext = this.options.clientContext || defaultClientContext();
         const repoContext = resolveRepoContext(this.config.workspace, history, this.config.mode);
-        const trajectory = history?.length
-            ? completeInterruptedToolCalls(structuredClone(history))
-            : initialMessages(prompt, clientContext, this.workspaceContext, repoContext, this.config.mode, this.config.maxTurns);
-        applySystemPromptConfig(trajectory[0], this.config, Boolean(history?.length));
-        if (history?.length) {
-            const expected = repoContext
-                ? repoSystemMessage(clientContext, repoContext, this.config.mode, this.workspaceContext, this.config.maxTurns)
-                : systemMessage(clientContext, this.workspaceContext, this.config.mode, this.config.maxTurns);
-            applySystemPromptConfig(expected, this.config);
-            if (typeof this.config.systemPrompt === "object") {
-                trajectory[0] = structuredClone(expected);
+        // System instructions belong to this invocation, never to the saved dialogue.
+        // Older local histories included a system message; accept them without
+        // carrying the old runtime configuration into the next request.
+        const dialogue = withoutLeadingSystemMessage(history || []).map((message) => normalizeToolCallHistory(message, this.config.mode));
+        const trajectory = completeInterruptedToolCalls(this.options.reuseHistoryMessages ? [...dialogue] : structuredClone(dialogue));
+        const runtimeSystemMessage = repoContext
+            ? repoSystemMessage(clientContext, repoContext, this.config.mode, this.workspaceContext, this.config.maxTurns)
+            : systemMessage(clientContext, this.workspaceContext, this.config.mode, this.config.maxTurns);
+        applySystemPromptConfig(runtimeSystemMessage, this.config);
+        if (runOptions.resumeFromHistory) {
+            if (!isContinuableHistory(dialogue)) {
+                throw new Error("resumeFromHistory requires an unfinished user or tool boundary");
             }
-            if (!isCanonicalSystemMessage(trajectory[0], expected, this.config.mode, this.config.maxTurns)) {
-                const portableExpected = systemMessage(clientContext, undefined, this.config.mode, this.config.maxTurns);
-                applySystemPromptConfig(portableExpected, this.config);
-                if (!repoContext &&
-                    this.workspaceContext &&
-                    isCanonicalSystemMessage(trajectory[0], portableExpected, this.config.mode, this.config.maxTurns)) {
-                    const runtimeSystemMessage = initialMessages("", this.options.clientContext, this.workspaceContext, undefined, this.config.mode, this.config.maxTurns)[0];
-                    applySystemPromptConfig(runtimeSystemMessage, this.config);
-                    trajectory[0] = runtimeSystemMessage;
-                }
-                else {
-                    throw new Error("history does not match the current workspace runtime context");
-                }
+        }
+        else {
+            trajectory.push(userMessage);
+        }
+        // Compaction projects model input with a runtime system prefix; the lossless
+        // trajectory and its checkpoints remain in the official dialogue format.
+        const messages = modelContextFromTrajectory([runtimeSystemMessage, ...trajectory]);
+        if (!isCodeArenaMode(this.config.mode)) {
+            const saved = this.persistedMemory ?? this.options.storedSessionMemory ?? storedSessionMemory(this.memoryCache);
+            preflightUnsupportedMedia(this.config, messages);
+            // Opting out of restoration must not delete a still-valid durable snapshot.
+            this.persistedMemory = saved?.version === 1 ? structuredClone(saved) : undefined;
+            if (this.persistedMemory?.latest && !sessionMemoryMatchesHistory(this.persistedMemory.latest, messages)) {
+                this.persistedMemory.latest = undefined;
             }
-            if (runOptions.resumeFromHistory) {
-                const lastRole = trajectory.at(-1)?.role;
-                if (lastRole !== "user" && lastRole !== "tool") {
-                    throw new Error("resumeFromHistory history must end with a user or tool message");
-                }
+            if (this.persistedMemory?.update?.status === "pending") {
+                this.persistedMemory.update = { status: "cancelled", code: "MEMORY_INTERRUPTED",
+                    error: "Previous process ended during a memory update" };
             }
-            else {
-                trajectory.push(userMessage);
+            this.memoryCache.latest = undefined;
+            this.memoryCache.state = undefined;
+            this.memoryCache.latestUsage = undefined;
+            this.memoryCache.attemptedPrefix = undefined;
+            this.memoryCache.update = undefined;
+            if (this.config.compactionMode !== "summary" &&
+                (runOptions.restoreSessionMemory ?? runOptions.singleStep) && saved?.version === 1) {
+                if (sessionMemoryMatchesHistory(saved.latest, messages)) {
+                    this.memoryCache.latest = structuredClone(saved.latest);
+                }
+                this.memoryCache.update = this.persistedMemory?.update;
+                if (saved.latest && !this.memoryCache.latest) {
+                    this.memoryCache.update = { status: "error", code: "MEMORY_STALE_HISTORY",
+                        error: "Saved memory does not match the current history prefix" };
+                }
+                if (this.memoryCache.update)
+                    this.sink.emit({ type: "memory.update", session_id: this.sessionId, ...this.memoryCache.update });
             }
         }
-        else {
-            trajectory[1] = userMessage;
-        }
-        // Persisted history is the lossless source of truth for replay and
-        // training. Compaction may rewrite only this private model-context copy;
-        // every real user, assistant, and tool message is appended to both.
-        const messages = structuredClone(trajectory);
         const recordMessage = async (message) => {
-            messages.push(message);
-            const recorded = structuredClone(message);
+            const normalized = normalizeToolCallHistory(message, this.config.mode);
+            messages.push(normalized);
+            const recorded = structuredClone(normalized);
             trajectory.push(recorded);
             this.sink.message(this.sessionId, recorded, trajectory);
             await this.checkpoint(trajectory);
         };
-        await this.maybeCompact(messages);
+        await this.maybeCompact(messages, trajectory);
         this.sink.start(this.sessionId, trajectory);
         try {
             await this.checkpoint(trajectory);
@@ -391,14 +484,21 @@ export class Agent {
                 // stores its encrypted reasoning output items there, so compaction is
                 // safe at the same tool-step boundaries as the other protocols.
                 if (step > 1)
-                    await this.maybeCompact(messages);
+                    await this.maybeCompact(messages, trajectory, "inner");
                 const offeredTools = this.tools.availableTools();
                 this.sink.modelStart(this.sessionId, step, offeredTools.map((tool) => tool.function.name));
                 let assistant;
                 try {
-                    assistant = await this.assistantTurn(messages, offeredTools);
+                    assistant = await this.assistantTurn(messages, offeredTools, trajectory);
                 }
                 catch (error) {
+                    if (error instanceof CheckpointExit) {
+                        this.sink.modelComplete(this.sessionId, step, "checkpoint");
+                        await this.makeCheckpoint(trajectory, offeredTools, error.event, "snapshot_exit");
+                        return await this.pause(trajectory, "checkpoint");
+                    }
+                    if (error instanceof CheckpointFailure)
+                        throw error.cause;
                     if (error instanceof PartialAssistantTurnError) {
                         this.options.onModelFailure?.(trajectory, error.cause);
                         if (error.assistant) {
@@ -411,9 +511,24 @@ export class Agent {
                 }
                 const finishReason = assistant.tool_calls?.length ? "tool_calls" : "stop";
                 this.sink.modelComplete(this.sessionId, step, finishReason, assistant.usage);
+                if (assistant.tool_calls?.length &&
+                    this.options.midturnCheckpointHook) {
+                    const event = {
+                        type: "tool_validation",
+                        sessionId: this.sessionId,
+                        toolCalls: assistant.tool_calls.map((call) => this.tools.inspect(call)),
+                    };
+                    const action = checkpointAction(await this.options.midturnCheckpointHook(event));
+                    if (action !== "continue") {
+                        await this.makeCheckpoint(trajectory, offeredTools, event, action);
+                        if (action === "snapshot_exit") {
+                            return await this.pause(trajectory, "checkpoint");
+                        }
+                    }
+                }
                 await recordMessage(assistant);
                 if (!assistant.tool_calls?.length) {
-                    return this.sink.result(this.sessionId, "success", trajectory);
+                    return await this.finish(trajectory, "success");
                 }
                 const completedToolCallIds = [];
                 for (const call of assistant.tool_calls) {
@@ -445,7 +560,7 @@ export class Agent {
                                 ? toolResult.questions
                                 : [];
                             this.sink.inputRequired(this.sessionId, toolCallId, questions);
-                            return this.sink.result(this.sessionId, "needs_input", trajectory);
+                            return await this.finish(trajectory, "needs_input");
                         }
                     }
                     if (this.options.signal?.aborted) {
@@ -456,28 +571,111 @@ export class Agent {
                 if (visualMessage) {
                     await recordMessage(visualMessage);
                 }
+                if (runOptions.singleStep) {
+                    return await this.pause(trajectory, "single_step");
+                }
             }
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            return this.sink.result(this.sessionId, "error", trajectory, message);
+            return await this.finish(trajectory, "error", message);
         }
     }
     async checkpoint(messages) {
-        await this.options.onCheckpoint?.(messages, this.tools.availableTools());
+        const snapshot = [...messages];
+        const tools = this.tools.availableTools();
+        const currentMemory = storedSessionMemory(this.memoryCache);
+        const memory = isCodeArenaMode(this.config.mode) ? undefined : (currentMemory || this.persistedMemory
+            ? { version: 1, latest: currentMemory?.latest ?? this.persistedMemory?.latest,
+                update: currentMemory?.update ?? this.persistedMemory?.update }
+            : null);
+        if (memory !== undefined)
+            this.persistedMemory = memory ?? undefined;
+        const write = this.checkpointQueue.then(() => this.options.onCheckpoint?.(snapshot, tools, memory));
+        this.checkpointQueue = write.catch(error => { this.checkpointError ??= error; });
+        await write;
+        if (this.checkpointError)
+            throw this.checkpointError;
+    }
+    async finish(messages, status, error) {
+        await settleSessionMemory(this.memoryCache);
+        try {
+            await this.checkpoint(messages);
+        }
+        catch (failure) {
+            status = "error";
+            error ??= failure instanceof Error ? failure.message : String(failure);
+        }
+        return this.sink.result(this.sessionId, status, messages, error, undefined, this.memoryCache.update);
+    }
+    async makeCheckpoint(messages, tools, event, action) {
+        await settleSessionMemory(this.memoryCache);
+        await this.checkpoint(messages);
+        if (!this.options.onMidturnCheckpoint) {
+            throw new Error("mid-turn checkpoint hook triggered without a snapshot handler");
+        }
+        await this.options.onMidturnCheckpoint(messages, tools, event, action);
+    }
+    async pause(messages, reason) {
+        this.options.signal?.throwIfAborted();
+        await settleSessionMemory(this.memoryCache, reason !== "single_step");
+        if (reason === "single_step")
+            await this.checkpoint(messages);
+        await this.options.onPause?.(messages, this.tools.availableTools());
+        this.options.signal?.throwIfAborted();
+        return this.sink.result(this.sessionId, "paused", messages, undefined, reason, this.memoryCache.update);
     }
-    async maybeCompact(messages) {
+    async maybeCompact(messages, trajectory, source = "outer") {
         preflightUnsupportedMedia(this.config, messages);
         try {
-            const result = await compactMessagesIfNeeded(messages, this.tools.availableTools(), this.client, this.config.model, {
+            const settings = {
                 contextWindow: this.config.contextWindow,
                 triggerRatio: this.config.contextCompactionRatio,
                 summaryMaxTokens: this.config.compactionSummaryMaxTokens,
-            }, this.options.signal);
+                reasoningEffort: this.config.reasoningEffort,
+                compactionThresholdTokens: isCodeArenaMode(this.config.mode) ? undefined
+                    : this.options.compactionThresholdTokens ?? this.config.compactionThresholdTokens,
+                legacy: isCodeArenaMode(this.config.mode) || this.config.compactionMode === "summary",
+            };
+            const contextLength = messages.length;
+            const result = settings.legacy
+                ? await compactMessagesIfNeeded(messages, this.tools.availableTools(), this.client, this.config.model, settings, this.options.signal)
+                : await maintainSessionMemory(messages, messages, this.memoryCache, this.tools.availableTools(), this.client, this.config.model, settings, this.config.memoryUpdateTokens, this.options.signal, update => {
+                    this.sink.emit({ type: "memory.update", session_id: this.sessionId, ...update });
+                    // Serialized with message checkpoints; persistence failures surface at
+                    // the next checkpoint/finish instead of becoming unhandled rejections.
+                    return this.checkpoint(trajectory).catch(() => undefined);
+                });
             if (result.compacted) {
-                // The summary exists only in the private model context, not as a real
-                // trajectory message, so the event stream is the only place its usage
-                // can be accounted for.
+                if (!isCodeArenaMode(this.config.mode)) {
+                    const covered = settings.legacy ? result.coveredMessages : this.memoryCache.state.coveredMessages;
+                    const retained = contextLength - covered;
+                    // Insert at the covered boundary, before the retained original tail.
+                    // Marker position is the resume boundary; no separate index is stored.
+                    let insertion = trajectory.length;
+                    let remaining = retained;
+                    while (remaining > 0 && insertion > 0) {
+                        if (trajectory[--insertion].role !== "compaction")
+                            remaining--;
+                    }
+                    trajectory.splice(insertion, 0, {
+                        role: "compaction", content: [{ type: "text", text: result.memory }],
+                        undone: false,
+                        compaction: {
+                            ratio: result.estimatedTokensBefore / this.config.contextWindow,
+                            tokens_at_compaction: result.estimatedTokensBefore,
+                            source,
+                        },
+                    });
+                    // Coverage indices referred to the pre-compaction history. The next
+                    // update reads its prior memory from the newly embedded block.
+                    this.memoryCache.state = undefined;
+                    this.memoryCache.latest = undefined;
+                    this.memoryCache.latestUsage = undefined;
+                    this.memoryCache.attemptedPrefix = undefined;
+                    this.persistedMemory = undefined;
+                }
+                await this.checkpoint(trajectory);
                 this.sink.compaction(this.sessionId, result.usage);
             }
             return result.compacted;
@@ -489,7 +687,7 @@ export class Agent {
             return false;
         }
     }
-    async assistantTurn(messages, offeredTools) {
+    async assistantTurn(messages, offeredTools, trajectory) {
         // A mid-stream network fault loses only the tokens produced so far, not the
         // conversation: the request is idempotent, so the whole turn is re-issued
         // from scratch. Accumulators live inside the loop and reset each attempt, so
@@ -499,11 +697,9 @@ export class Agent {
         // original content, and route-specific rejections keep the runtime fallback.
         preflightUnsupportedMedia(this.config, messages);
         const maxRetries = Math.max(0, Math.floor(this.config.modelMaxRetries ?? 10));
-        // Keep an immutable request snapshot for automatic retries. Each attempt
-        // receives its own clone so even a stateful ModelClient cannot contaminate
-        // the next request after a partial or failed stream.
-        let requestMessages = structuredClone(messages);
-        const requestTools = structuredClone(offeredTools);
+        // Each attempt receives one fresh clone, so a stateful ModelClient cannot
+        // contaminate the retry. Keeping an additional immutable clone of the same
+        // request doubled the largest live allocation without adding isolation.
         let multimodalFallbackApplied = false;
         for (let attempt = 0;; attempt += 1) {
             const contentParts = [];
@@ -512,11 +708,56 @@ export class Agent {
             const responseItems = new Map();
             let usage;
             let reasoningDetails;
+            const detectors = this.options.midturnCheckpointHook ? {
+                content: new RepetitiveOutputDetector(),
+                reasoning: new RepetitiveOutputDetector(),
+            } : undefined;
+            const controller = detectors ? new AbortController() : undefined;
+            const signal = controller
+                ? this.options.signal
+                    ? AbortSignal.any([this.options.signal, controller.signal])
+                    : controller.signal
+                : this.options.signal;
+            let repetitionReported = false;
+            let checkpointControl;
+            const inspectOutput = async (channel, text) => {
+                if (!detectors || repetitionReported)
+                    return;
+                const sample = detectors[channel].append(text);
+                if (sample === undefined)
+                    return;
+                repetitionReported = true;
+                const event = {
+                    type: "repetitive_output",
+                    sessionId: this.sessionId,
+                    toolCalls: [],
+                    repetition: { channel, sample },
+                };
+                try {
+                    const action = checkpointAction(await this.options.midturnCheckpointHook(event));
+                    if (action === "snapshot_exit") {
+                        checkpointControl = new CheckpointExit(event);
+                    }
+                    else if (action === "snapshot_continue") {
+                        await this.makeCheckpoint(trajectory, offeredTools, event, action);
+                    }
+                }
+                catch (error) {
+                    checkpointControl = new CheckpointFailure(error);
+                }
+                if (checkpointControl) {
+                    // Abort the transport, then let for-await close its iterator before
+                    // the caller snapshots or reports an error. Never save this partial
+                    // assistant or retry a policy decision as a network failure.
+                    controller.abort(checkpointControl);
+                    throw checkpointControl;
+                }
+            };
             try {
                 const stream = this.client.stream({
                     model: this.config.model,
-                    messages: structuredClone(requestMessages),
-                    tools: structuredClone(requestTools),
+                    messages: structuredClone(messages),
+                    tools: structuredClone(offeredTools),
                     toolChoice: this.config.toolChoice,
                     temperature: this.config.temperature,
                     maxTokens: this.config.maxTokens,
@@ -526,7 +767,7 @@ export class Agent {
                     enableThinking: this.config.enableThinking,
                     thinkingBudget: this.config.thinkingBudget,
                     preserveThinking: this.config.preserveThinking,
-                    signal: this.options.signal,
+                    signal,
                 });
                 for await (const chunk of stream) {
                     // With stream_options.include_usage the usage arrives on the final
@@ -545,12 +786,16 @@ export class Agent {
                         const content = String(delta.content);
                         contentParts.push(content);
                         this.sink.delta(this.sessionId, { content });
+                        if (detectors)
+                            await inspectOutput("content", content);
                     }
                     const reasoning = delta.reasoning_content || delta.reasoning;
                     if (reasoning) {
                         const value = String(reasoning);
                         reasoningParts.push(value);
                         this.sink.delta(this.sessionId, { reasoning_content: value });
+                        if (detectors)
+                            await inspectOutput("reasoning", value);
                     }
                     for (const [position, fragment] of (delta.tool_calls || []).entries()) {
                         const index = Number(fragment.index ?? position);
@@ -586,6 +831,9 @@ export class Agent {
                 }
             }
             catch (error) {
+                // Iterator cleanup may itself report the intentional transport abort.
+                if (checkpointControl)
+                    throw checkpointControl;
                 // A user cancellation is not a transient fault: skip the retry, but
                 // still fall through so any partial output is preserved in history.
                 const aborted = Boolean(this.options.signal?.aborted);
@@ -595,7 +843,6 @@ export class Agent {
                     const replacedMedia = replaceUnsupportedMedia(messages, error.mediaTypes);
                     if (replacedMedia > 0) {
                         multimodalFallbackApplied = true;
-                        requestMessages = structuredClone(messages);
                         this.sink.modelRetry(this.sessionId, attempt + 1, `model rejected ${error.mediaTypes.join(", ")} input; replaced ` +
                             `${replacedMedia} media part(s) with an unsupported-input notice`);
                         continue;