aec-agent 1.0.1 → 1.0.4

package/dist/components/multi-agent-orchestration/agent/agent-loop/agent-loop.js

@@ -1,7 +1,8 @@
+import { measureContext } from "./functions/context-usage.js";
 import { resolveLoopConfig, SDKEventType } from "./types.js";
 import { HarnessExecutor } from "./components/harness-executor.js";
 import { Summarizer } from "./components/summarizer.js";
-import { Compactor } from "./components/compactor.js";
+import { Compactor, sessionCompactorConfig } from "./components/compactor.js";
 import { repairToolPairs } from "./components/tool-pairing.js";
 import { Counter } from "./components/counter.js";
 import { abortable, raceAbort } from "./components/abort.js";
@@ -9,6 +10,23 @@ import { RunTrace } from "./components/run-trace.js";
 import { recallMemories } from "./functions/memory-recall.js";
 import { describeLlmInput, withRecalledMemories, } from "./functions/llm-input.js";
 const TOKEN_BUDGET = 100_000;
+// A-88: how many model responses in a row may be cut off at the output token limit
+// while writing tool call arguments before the run stops (the model keeps retrying
+// the same oversized call otherwise).
+const MAX_CONSECUTIVE_TRUNCATIONS = 2;
+/**
+ * The size of a session's context window as the latest model response reported it
+ * (input and output only): the session's currentTokenUsage, which recordUsage replaces
+ * after every call. Zero before the first response.
+ */
+function latestContextUsage(session) {
+    return {
+        inputTokens: session.currentTokenUsage?.inputTokens ?? 0,
+        outputTokens: session.currentTokenUsage?.outputTokens ?? 0,
+    };
+}
+/** The model-call span's `error` when a response stopped with "error" and gave no error text. */
+const MODEL_ERROR_STOP = "the model stopped with stopReason error";
 // ---------------------------------------------------------------------------
 // AgentLoop — OTAR cycle (Observe → Think → Act → Reflect)
 // ---------------------------------------------------------------------------
@@ -35,27 +53,37 @@ export class AgentLoop {
     executor;
     compactor;
     summarizer;
-    counter;
     constructor(deps) {
         this.deps = deps;
         this.executor = new HarnessExecutor(deps);
         this.summarizer = new Summarizer(deps);
         this.compactor = new Compactor(deps.profile.compactor);
-        this.counter = new Counter(deps.modelManager);
     }
     /**
      * run() — blocking call, returns final message
      * @param userMessage
-     * @param sessionId
+     * @param conversation the session to run in (A-97) — the caller holds that session's turn slot
      * @param modelOverrides
      * @param runOptions
      * @returns
      */
-    async run(userMessage, sessionId, modelOverrides, runOptions) {
-        const { modelManager, contextManager, conversationManager } = this.deps;
+    async run(userMessage, conversation, modelOverrides, runOptions) {
         // A-65: aborting this stops the run at the next safe point (below) —
         // same contract as stream()'s `signal`.
-        const run = await this.beginRun(userMessage, sessionId, runOptions);
+        const run = await this.beginRun(userMessage, conversation, runOptions);
+        try {
+            return await this.runLoop(run, modelOverrides);
+        }
+        catch (err) {
+            // A failed run (a model, context, store or tool port threw) ends every open span
+            // with the error and removes its trace context; no RunCompleted follows (as Go).
+            run.trace.fail(err);
+            throw err;
+        }
+    }
+    /** The iteration loop of run(), after beginRun. */
+    async runLoop(run, modelOverrides) {
+        const { modelManager, contextManager } = this.deps;
         const { signal, totalUsage, emit } = run;
         const aborted = (iterations) => ({
             message: { role: "assistant", content: "" },
@@ -100,6 +128,8 @@ export class AgentLoop {
             });
             modelSpan?.end({
                 stopReason: response.stopReason,
+                // A refusal or filter stop ends the span with status "error", not "ok".
+                ...(response.stopReason === "error" && { error: MODEL_ERROR_STOP }),
                 inputTokens: response.usage.inputTokens,
                 outputTokens: response.usage.outputTokens,
                 hasToolCalls: !!response.message.toolCalls?.length,
@@ -109,13 +139,18 @@ export class AgentLoop {
                     arguments: tc.arguments,
                 })),
             });
-            this.recordUsage(run, input.llmMessages, response.usage);
+            this.recordUsage(run, input, response.usage);
             emit(SDKEventType.ModelResponded, {
                 stopReason: response.stopReason,
                 usage: response.usage,
                 hasToolCalls: !!response.message.toolCalls?.length,
             });
-            await conversationManager.addMessage(response.message);
+            this.emitContextUsage(run, iteration, input, response.message, response.usage);
+            // The response's usage is saved with the message it produced (none reported: no usage).
+            if (response.usage && (response.usage.inputTokens > 0 || response.usage.outputTokens > 0)) {
+                response.message.usage = { ...response.usage };
+            }
+            await run.conversation.addMessage(response.message);
             // --- End turn: return final answer ---
             if (response.stopReason === "end_turn") {
                 this.completeRun(run, iteration, iterSpan);
@@ -125,10 +160,49 @@ export class AgentLoop {
                     iterations: iteration,
                 };
             }
+            // The provider reported a stop it does not map to a normal finish (e.g. a refusal or a
+            // guardrail/content filter): end the turn like stream() does, instead of asking the
+            // model again until maxIterations.
+            if (response.stopReason === "error") {
+                this.completeRun(run, iteration, iterSpan, "error");
+                return {
+                    message: response.message,
+                    usage: totalUsage,
+                    iterations: iteration,
+                    stopReason: "error",
+                };
+            }
+            // A-88: the reply was cut off at the output token limit and has no tool calls:
+            // the turn ends here, no auto-continue.
+            if (response.stopReason === "max_tokens" &&
+                !response.message.toolCalls?.length) {
+                this.completeRun(run, iteration, iterSpan, "max_tokens");
+                return {
+                    message: response.message,
+                    usage: totalUsage,
+                    iterations: iteration,
+                    stopReason: "max_tokens",
+                };
+            }
             // --- ACT: execute tool/skill calls ---
-            if (response.stopReason === "tool_use" &&
+            if ((response.stopReason === "tool_use" ||
+                response.stopReason === "max_tokens") &&
                 response.message.toolCalls?.length) {
-                await this.executeToolCalls(run, response.message.toolCalls);
+                const { truncationLimitReached } = await this.actOnToolCalls(run, input, response.stopReason, response.message.toolCalls);
+                // A-88: cut off mid tool call too many times in a row — stop. Like the
+                // max-iterations fallback, this message is returned but not saved.
+                if (truncationLimitReached) {
+                    this.completeRun(run, iteration, iterSpan, "max_tokens");
+                    return {
+                        message: {
+                            role: "assistant",
+                            content: this.truncationLimitMessage(input),
+                        },
+                        usage: totalUsage,
+                        iterations: iteration,
+                        stopReason: "max_tokens",
+                    };
+                }
             }
             // --- REFLECT: loop back, model sees tool results and decides next step ---
             iterSpan?.end();
@@ -148,14 +222,53 @@ export class AgentLoop {
     /**
      * stream() — yields chunks in real-time, handles tool calls between streams
      * @param userMessage
-     * @param sessionId
+     * @param conversation the session to run in (A-97) — the caller holds that session's turn slot
      * @param modelOverrides
      * @param runOptions
      * @returns
      */
-    async *stream(userMessage, sessionId, modelOverrides, runOptions) {
-        const { conversationManager } = this.deps;
-        const run = await this.beginRun(userMessage, sessionId, runOptions);
+    async *stream(userMessage, conversation, modelOverrides, runOptions) {
+        const run = await this.beginRun(userMessage, conversation, runOptions);
+        try {
+            yield* this.streamLoop(run, modelOverrides);
+        }
+        catch (err) {
+            // A failed run ends every open span with the error and removes its trace
+            // context; no RunCompleted follows (as Go).
+            run.trace.fail(err);
+            throw err;
+        }
+        finally {
+            // The consumer stopped iterating (a break, a return, a closed HTTP response)
+            // before a terminal path ran: the run is closed as if it was aborted, so no span
+            // or trace context outlives it (as Go's Stream deferred cleanup). Never yields.
+            if (!run.trace.closed)
+                await this.closeStoppedStream(run);
+        }
+    }
+    /**
+     * Close a stream whose consumer stopped iterating: save the text the consumer
+     * received when there is some (never the tool calls collected from an unfinished
+     * response — they were not run and would dangle without a result), then close the
+     * run as aborted. A failed write is logged, not thrown: no consumer is left to
+     * receive it. The log carries the agent and session ids and the error text only,
+     * never message content.
+     */
+    async closeStoppedStream(run) {
+        const partial = run.partial;
+        run.partial = "";
+        if (partial) {
+            try {
+                await run.conversation.addMessage({ role: "assistant", content: partial });
+            }
+            catch (err) {
+                console.warn(`[agent-loop] saving the partial reply of a stopped stream failed for agent ${this.deps.profile.id} session ${run.session.id}:`, err instanceof Error ? err.message : String(err));
+            }
+        }
+        this.closeAbortedRun(run, run.iteration, null);
+    }
+    /** The iteration loop of stream(), after beginRun. */
+    async *streamLoop(run, modelOverrides) {
         const { signal, totalUsage, emit } = run;
         let iteration = 0;
         while (iteration < run.maxIterations) {
@@ -188,8 +301,9 @@ export class AgentLoop {
             // never dispatched and would dangle without a matching tool result.
             if (signal?.aborted) {
                 modelSpan?.end({ aborted: true, responsePreview: streamed.content });
+                run.partial = "";
                 if (streamed.content) {
-                    await conversationManager.addMessage({
+                    await run.conversation.addMessage({
                         role: "assistant",
                         content: streamed.content,
                     });
@@ -201,6 +315,8 @@ export class AgentLoop {
             const { content, toolCalls, stopReason, usage } = streamed;
             modelSpan?.end({
                 stopReason,
+                // An error chunk (or a refusal/filter stop) ends the span with status "error", not "ok".
+                ...(stopReason === "error" && { error: streamed.error ?? MODEL_ERROR_STOP }),
                 hasToolCalls: !!toolCalls.length,
                 responsePreview: content,
                 toolCalls: toolCalls.length
@@ -218,23 +334,50 @@ export class AgentLoop {
                 role: "assistant",
                 content,
                 toolCalls: toolCalls.length ? toolCalls : undefined,
+                // saved with the message it produced
+                ...(usage && { usage: { ...usage } }),
             };
+            // The usage rides along when the provider reported one, as in run() (the
+            // SubagentManager counts a child's tokens from it).
             emit(SDKEventType.ModelResponded, {
                 stopReason,
+                ...(usage && { usage: { ...usage } }),
                 hasToolCalls: !!toolCalls.length,
             });
-            await conversationManager.addMessage(responseMessage);
+            this.emitContextUsage(run, iteration, input, responseMessage, usage);
+            // Saved below: a stop from here on must not save the text again.
+            run.partial = "";
+            await run.conversation.addMessage(responseMessage);
             if (stopReason === "end_turn" || stopReason === "error") {
-                this.completeRun(run, iteration, iterSpan);
-                yield { type: "done", usage: totalUsage };
+                this.completeRun(run, iteration, iterSpan, stopReason === "error" ? "error" : undefined);
+                yield {
+                    type: "done",
+                    usage: totalUsage,
+                    ...(stopReason === "error" && { stopReason }),
+                };
+                return;
+            }
+            // A-88: the reply was cut off at the output token limit and has no tool calls:
+            // the turn ends here, no auto-continue.
+            if (stopReason === "max_tokens" && !toolCalls.length) {
+                this.completeRun(run, iteration, iterSpan, "max_tokens");
+                yield { type: "done", usage: totalUsage, stopReason: "max_tokens" };
                 return;
             }
-            if (stopReason === "tool_use" && toolCalls.length) {
-                const results = await this.executeToolCalls(run, toolCalls);
+            if ((stopReason === "tool_use" || stopReason === "max_tokens") &&
+                toolCalls.length) {
+                const { results, truncationLimitReached } = await this.actOnToolCalls(run, input, stopReason, toolCalls);
                 // Yield tool results as stream chunks so the consumer can display them
                 for (const result of results) {
                     yield { type: "tool_result", toolResult: result };
                 }
+                // A-88: cut off mid tool call too many times in a row — stop with an
+                // error (same convention as the max-iterations path: no done after it).
+                if (truncationLimitReached) {
+                    this.completeRun(run, iteration, iterSpan, "max_tokens");
+                    yield { type: "error", error: this.truncationLimitMessage(input) };
+                    return;
+                }
             }
             iterSpan?.end();
         }
@@ -242,47 +385,94 @@ export class AgentLoop {
         yield { type: "error", error: "Reached maximum reasoning steps." };
     }
     //#region Steps shared by run() and stream()
+    /**
+     * A-103: run one tool call outside a turn — a tool job's stored call. It goes through the
+     * same steps as a call the model makes (tool policy, approval gate, retries, sandbox and
+     * dispatch tracing, tool events), under its own "tool-job" run span. Nothing is written to
+     * the session here: the caller (the JobManager) records the call and its result.
+     */
+    async executeToolCall(call, options) {
+        const { sessionId, signal } = options;
+        const emit = this.executor.createEmitter(this.deps.eventBus, sessionId);
+        const trace = new RunTrace(this.deps.traceService);
+        const runSpan = trace.span("tool-job", "run", { agentId: this.deps.profile.id, sessionId, toolName: call.name });
+        try {
+            const toolCtx = this.executor.buildToolContext(sessionId, emit, signal, crypto.randomUUID());
+            const result = await this.executor.executeScheduled(call, toolCtx, emit, trace.service, trace.ctx ?? undefined);
+            runSpan?.end({ isError: result.isError ?? false });
+            return result;
+        }
+        catch (err) {
+            runSpan?.end({ error: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+        finally {
+            trace.close();
+        }
+    }
     /**
      * Start a run: open the trace, record the user's message, restore token
      * usage and counter calibration from the session, and recall memories.
      */
-    async beginRun(userMessage, sessionId, runOptions) {
-        const { conversationManager, eventBus, traceService } = this.deps;
+    async beginRun(userMessage, conversation, runOptions) {
+        const { eventBus, traceService } = this.deps;
         // A-65: aborting this stops the run at the next safe point (below).
         const signal = runOptions?.signal;
-        const session = conversationManager.getSession();
-        if (!session)
-            throw new Error("No active session");
+        const session = conversation.getSession();
+        const sessionId = session.id;
         const emit = this.executor.createEmitter(eventBus, sessionId);
+        const runId = crypto.randomUUID();
         // --- Trace: create a context and root "run" span ---
+        // A-105: a child run adds its parent turn (RunOptions.traceAttributes); agentId and
+        // sessionId always name this run's own agent and session.
         const trace = new RunTrace(traceService);
         const runSpan = trace.span("agent-run", "run", {
+            ...runOptions?.traceAttributes,
             agentId: this.deps.profile.id,
             sessionId,
+            runId,
         });
-        await conversationManager.addMessage({
-            role: "user",
-            content: userMessage,
-        });
+        try {
+            await conversation.addMessage({
+                role: "user",
+                content: userMessage,
+            });
+        }
+        catch (err) {
+            // The user message write failed: the run span ends with the error and the trace
+            // context is removed, so a run that never started leaks nothing. (Memory recall
+            // below never throws.)
+            trace.fail(err);
+            throw err;
+        }
         emit(SDKEventType.UserMessage, { role: "user", content: userMessage });
         const totalUsage = {
             inputTokens: session.currentTokenUsage?.inputTokens || 0,
             outputTokens: session.currentTokenUsage?.outputTokens || 0,
         };
         // Restore learned chars-per-token ratio from previous turns
+        const counter = new Counter(this.deps.modelManager);
         if (session.counterCalibration) {
-            this.counter.seed(session.counterCalibration.charsPerToken, session.counterCalibration.samples);
+            counter.seed(session.counterCalibration.charsPerToken, session.counterCalibration.samples);
         }
         // --- Memory recall: once per run, keyed on the user's message ---
         const recalled = await recallMemories({
             memorySystem: this.deps.memorySystem,
-            counter: this.counter,
+            counter,
             agentId: this.deps.profile.id,
         }, userMessage, sessionId, trace);
         // Resolved once per run — a runtime updateLoopConfig() takes effect on the next turn.
         const { maxIterations } = resolveLoopConfig(this.deps.profile.loopConfig);
+        // A session may plan around a larger (or smaller) context window than the agent's.
+        const compactorConfig = sessionCompactorConfig(this.deps.profile.compactor, session);
+        const compactor = compactorConfig === this.deps.profile.compactor
+            ? this.compactor
+            : new Compactor(compactorConfig);
         return {
+            conversation,
             session,
+            runId,
+            counter,
             emit,
             signal,
             trace,
@@ -290,10 +480,16 @@ export class AgentLoop {
             totalUsage,
             recalled,
             maxIterations,
+            iteration: 0,
+            partial: "",
+            truncatedResponses: 0,
+            compactor,
+            compactorConfig,
         };
     }
     /** Emit the Iteration event and open the iteration span. */
     startIteration(run, iteration) {
+        run.iteration = iteration;
         run.emit(SDKEventType.Iteration, {
             iteration,
             maxIterations: run.maxIterations,
@@ -310,21 +506,26 @@ export class AgentLoop {
      * for this iteration's model call.
      */
     async assembleModelInput(run, iteration, modelOverrides) {
-        const { toolManager, contextManager, conversationManager, modelManager } = this.deps;
-        const { session, totalUsage, recalled, trace } = run;
+        const { modelManager } = this.deps;
+        const { conversation, session, totalUsage, recalled, trace, counter, compactor } = run;
         const ctxSpan = trace.span("context-assembly", "context-assembly");
         // Use LLM working set (compacted if available) instead of full history
-        const messages = await contextManager.prepareMessages(conversationManager.getLlmMessages(), { session, tokenBudget: TOKEN_BUDGET, usage: totalUsage });
+        // A-104: with the system message's labelled sections when the ContextManager gives them.
+        const { messages, sections } = await this.prepareContext(conversation.getLlmMessages(), { session, tokenBudget: TOKEN_BUDGET, usage: totalUsage });
         // --- Compaction: check if context needs shrinking ---
+        // The compactor is fed the context window size the latest response reported
+        // (as Go's contextUsage), not the run total, which grows past the window with
+        // every call of a run.
+        const contextUsage = latestContextUsage(session);
         const compactSpan = trace.span("compaction", "compaction", {
             messageCountBefore: messages.length,
-            inputTokens: totalUsage.inputTokens,
-            outputTokens: totalUsage.outputTokens,
+            inputTokens: contextUsage.inputTokens,
+            outputTokens: contextUsage.outputTokens,
         });
-        const compactResult = await this.compactor.compactIfNeeded(messages, totalUsage, this.counter.countTokens, this.summarizer.summarize);
+        const compactResult = await compactor.compactIfNeeded(messages, contextUsage, counter.countTokens, this.summarizer.traced(trace));
         // Persist compacted messages so subsequent turns don't re-compact
         if (compactResult.compacted) {
-            await conversationManager.setCompactedMessages(compactResult.messages);
+            await conversation.setCompactedMessages(compactResult.messages);
         }
         compactSpan?.end({
             triggered: compactResult.compacted,
@@ -337,11 +538,7 @@ export class AgentLoop {
         // repairToolPairs: drop tool calls/results that lost their partner (e.g. a
         // history compacted before this fix) so the provider does not reject the request.
         const llmMessages = repairToolPairs(withRecalledMemories(compactResult.messages, recalled));
-        // The agent's tools, plus skill_view when it has skills (the index is in the system prompt).
-        const toolDefs = [
-            ...toolManager.list().map((t) => t.definition),
-            ...(await this.deps.skillManager.toolDefinitions()),
-        ];
+        const toolDefs = await this.toolDefinitions(session);
         const options = { tools: toolDefs, ...modelOverrides };
         // Computed once per iteration, only when a sink is listening — tracing
         // must never run (or throw) when there's no traceCtx to attach it to.
@@ -353,7 +550,7 @@ export class AgentLoop {
                 llmMessages,
                 recalled,
                 options,
-            }, { modelManager, counter: this.counter })
+            }, { modelManager, counter })
             : null;
         if (llmInput) {
             ctxSpan?.end({ ...llmInput });
@@ -361,7 +558,140 @@ export class AgentLoop {
         else {
             ctxSpan?.end();
         }
-        return { llmMessages, toolDefs, options, llmInput };
+        return { llmMessages, toolDefs, options, llmInput, sections };
+    }
+    /**
+     * The agent's tools, plus skill_view when it has skills (the index is in the system prompt).
+     * A-105: a subagent's session sees only the tools its scope allows.
+     */
+    async toolDefinitions(session) {
+        const inScope = this.deps.toolScope?.(session.id);
+        // A-136: in plan mode the model is offered only read-only tools (the executor refuses the rest).
+        const planning = (await this.deps.getApprovalMode?.(session.id)) === "plan";
+        return [
+            ...this.deps.toolManager
+                .list(session.id)
+                .map((t) => t.definition)
+                .filter((d) => (!inScope || inScope(d)) && (!planning || d.risk === "read-only")),
+            ...(await this.deps.skillManager.toolDefinitions()),
+        ];
+    }
+    /**
+     * A-104: the prepared messages and the system message's labelled sections. A context
+     * manager without prepare() (a host's own) gives no sections: its whole system
+     * message then counts as system_prompt.
+     */
+    async prepareContext(messages, context) {
+        const { contextManager } = this.deps;
+        if (typeof contextManager.prepare === "function")
+            return contextManager.prepare(messages, context);
+        return { messages: await contextManager.prepareMessages(messages, context), sections: [] };
+    }
+    /**
+     * A-104: emit what fills the session's context window, right after ModelResponded.
+     * `usage` is the provider's reported usage of this response (absent or zero = the
+     * total is estimated).
+     */
+    emitContextUsage(run, iteration, input, response, usage) {
+        let measured;
+        try {
+            measured = measureContext({
+                sessionId: run.session.id,
+                model: this.resolvedModel(input.options),
+                iteration,
+                sections: input.sections,
+                messages: input.llmMessages,
+                recalled: run.recalled?.content,
+                tools: input.toolDefs,
+                response,
+                reported: usage,
+                compactor: run.compactorConfig,
+                countTokens: run.counter.countTokens,
+            });
+        }
+        catch {
+            return; // like tracing, measuring must never break the loop
+        }
+        run.emit(SDKEventType.ContextUsage, measured);
+    }
+    /**
+     * A-104: the model a call with these options goes to (the ModelManager's defaults
+     * merged in). Never throws — like tracing, measuring must never break the loop.
+     */
+    resolvedModel(options) {
+        try {
+            return this.deps.modelManager.resolveOptions?.(options)?.model ?? options.model;
+        }
+        catch {
+            return options.model;
+        }
+    }
+    /**
+     * A-104: measure what fills a session's context window now, without a model call or
+     * any write: the same assembly as a model call (system message, working set, tools),
+     * without compaction or memory recall (recalled memories depend on the next message,
+     * so they count 0). `usedTokens` is the session's last reported usage when it has one.
+     * The caller loads the conversation; it needs no turn slot.
+     */
+    async measureContext(conversation) {
+        const session = conversation.getSession();
+        const counter = new Counter(this.deps.modelManager);
+        if (session.counterCalibration) {
+            counter.seed(session.counterCalibration.charsPerToken, session.counterCalibration.samples);
+        }
+        const { messages, sections } = await this.prepareContext(conversation.getLlmMessages(), {
+            session,
+            tokenBudget: TOKEN_BUDGET,
+            usage: session.currentTokenUsage ?? { inputTokens: 0, outputTokens: 0 },
+        });
+        return measureContext({
+            sessionId: session.id,
+            model: this.resolvedModel(session.llmModel ? { model: session.llmModel } : {}),
+            sections,
+            messages: repairToolPairs(messages),
+            tools: await this.toolDefinitions(session),
+            reported: session.currentTokenUsage,
+            compactor: sessionCompactorConfig(this.deps.profile.compactor, session),
+            countTokens: counter.countTokens,
+        });
+    }
+    /**
+     * A-136: compact the session's working set now (/compact), whatever its size, with the
+     * user's focus added to the summary request. The caller holds the session's turn slot.
+     * The session's reported context size is dropped once compacted (it described the old
+     * working set), so the next turn does not compact again before a response reports anew.
+     */
+    async compactNow(conversation, focus) {
+        const session = conversation.getSession();
+        const before = await this.measureContext(conversation);
+        const messages = conversation.getLlmMessages();
+        const counter = new Counter(this.deps.modelManager);
+        if (session.counterCalibration) {
+            counter.seed(session.counterCalibration.charsPerToken, session.counterCalibration.samples);
+        }
+        const compactor = new Compactor(sessionCompactorConfig(this.deps.profile.compactor, session));
+        const result = await compactor.compactNow(messages, counter.countTokens, this.summarizer.summarize, focus || undefined);
+        if (!result.compacted) {
+            return {
+                compacted: false,
+                beforeTokens: before.usedTokens,
+                afterTokens: before.usedTokens,
+                messagesBefore: messages.length,
+                messagesAfter: messages.length,
+            };
+        }
+        await conversation.setCompactedMessages(result.messages);
+        await conversation.updateSession((s) => {
+            delete s.currentTokenUsage;
+        });
+        const after = await this.measureContext(conversation);
+        return {
+            compacted: true,
+            beforeTokens: before.usedTokens,
+            afterTokens: after.usedTokens,
+            messagesBefore: messages.length,
+            messagesAfter: result.messages.length,
+        };
     }
     /** Emit ModelRequested and open the model-call span. */
     startModelCall(run, iteration, input) {
@@ -387,10 +717,11 @@ export class AgentLoop {
     async *streamModelResponse(run, input) {
         const { signal } = run;
         const { llmMessages, options } = input;
-        let fullContent = "";
+        run.partial = "";
         const collectedToolCalls = [];
         let stopReason = "end_turn";
         let streamUsage;
+        let streamError;
         // --- Safe point C (A-65): mid-stream. abortable() stops iterating the
         // provider's stream as soon as `signal` aborts, without waiting on the
         // provider's in-flight next() to settle; the leading `if` below drops
@@ -403,60 +734,129 @@ export class AgentLoop {
             if (signal?.aborted)
                 break;
             if (chunk.type === "done") {
-                stopReason = collectedToolCalls.length ? "tool_use" : "end_turn";
+                // A-88: the provider's reported "max_tokens" wins. Otherwise collected tool calls mean
+                // "tool_use" (also covers an older provider that reports nothing, or a reported
+                // end_turn/error); a reported "error" stays "error"; anything else ends the turn.
+                stopReason =
+                    chunk.stopReason === "max_tokens"
+                        ? "max_tokens"
+                        : collectedToolCalls.length
+                            ? "tool_use"
+                            : chunk.stopReason === "error"
+                                ? "error"
+                                : "end_turn";
                 if (chunk.usage) {
                     streamUsage = chunk.usage;
-                    this.recordUsage(run, llmMessages, chunk.usage);
+                    this.recordUsage(run, input, chunk.usage);
+                    // The response's usage reaches the consumer as a usage chunk (shown with
+                    // the response's message, which saves it too).
+                    yield { type: "usage", usage: { ...chunk.usage } };
                 }
                 continue;
             }
-            yield chunk;
+            // Appended before the yield: what the consumer received is what a stop saves.
             if (chunk.type === "text" && chunk.content) {
-                fullContent += chunk.content;
+                run.partial += chunk.content;
             }
+            yield chunk;
             if (chunk.type === "tool_call" && chunk.toolCall) {
                 collectedToolCalls.push(chunk.toolCall);
             }
             if (chunk.type === "error") {
                 stopReason = "error";
+                if (chunk.error)
+                    streamError = chunk.error;
             }
         }
         return {
-            content: fullContent,
+            content: run.partial,
             toolCalls: collectedToolCalls,
             stopReason,
             usage: streamUsage,
+            ...(streamError !== undefined && { error: streamError }),
         };
     }
     /** Add a model response's usage to the run total and save it on the session. */
-    recordUsage(run, llmMessages, usage) {
+    recordUsage(run, input, usage) {
         this.executor.accumulateUsage(run.totalUsage, usage);
         // Calibrate against llmMessages (what was actually sent), not the
         // pre-compaction/pre-memory `messages` array — otherwise the
         // chars-per-token ratio (and every downstream token estimate) is
         // skewed by content the model never saw.
-        this.counter.calibrate(llmMessages, usage);
+        // A-104 audit: the tool definitions were sent too and are in the input tokens.
+        run.counter.calibrate(input.llmMessages, usage, input.toolDefs);
         // Save the latest response's raw usage — this IS the current context window size
         // (inputTokens = full conversation sent, outputTokens = what the model just added)
         run.session.currentTokenUsage = { ...usage };
-        run.session.counterCalibration = this.counter.getCalibration();
+        run.session.counterCalibration = run.counter.getCalibration();
     }
-    /** ACT: execute the model's tool/skill calls and append the results as a single message. */
-    async executeToolCalls(run, toolCalls) {
-        const toolCtx = this.executor.buildToolContext(run.session.id, run.emit, run.signal);
-        const results = await this.executor.executeAll(toolCalls, toolCtx, run.emit, run.trace.service, run.trace.ctx ?? undefined);
+    /**
+     * ACT: execute the model's tool/skill calls and append the results as a single message.
+     * `outputTruncation` (A-88) is set when the response stopped at max_tokens: the cut-off calls
+     * are answered with an output-token-limit tool error instead of being run.
+     */
+    async executeToolCalls(run, toolCalls, outputTruncation) {
+        const toolCtx = this.executor.buildToolContext(run.session.id, run.emit, run.signal, run.runId);
+        const results = await this.executor.executeAll(toolCalls, toolCtx, run.emit, run.trace.service, run.trace.ctx ?? undefined, outputTruncation);
         // Append all results as a single message
-        await this.deps.conversationManager.addMessage({
+        await run.conversation.addMessage({
             role: "assistant",
             content: "",
             toolResults: results,
         });
         return results;
     }
+    /**
+     * ACT, the single entry point for run() and stream() (A-88). Executes the response's calls.
+     * When the response stopped at max_tokens, a call counts as cut off if it has an argumentsError
+     * OR it is the LAST call of the response (the block the model was writing when the limit hit;
+     * non-streaming Anthropic/Bedrock hand over pre-parsed inputs, so they never carry an
+     * argumentsError). Cut-off calls are never run: each gets an output-token-limit tool error
+     * that names maxTokens when it is configured. Earlier calls run normally. Every call gets a
+     * saved result, so the conversation never has a tool call without one — even when the
+     * consecutive-truncation guard trips (`truncationLimitReached`).
+     */
+    async actOnToolCalls(run, input, stopReason, toolCalls) {
+        let outputTruncation;
+        if (stopReason === "max_tokens") {
+            const truncatedCalls = new Set(toolCalls.filter((tc) => !!tc.argumentsError));
+            const last = toolCalls[toolCalls.length - 1];
+            if (last)
+                truncatedCalls.add(last);
+            outputTruncation = {
+                maxTokens: this.deps.modelManager.resolveOptions(input.options)?.maxTokens,
+                truncatedCalls,
+            };
+            run.truncatedResponses++;
+        }
+        else {
+            run.truncatedResponses = 0;
+        }
+        const results = await this.executeToolCalls(run, toolCalls, outputTruncation);
+        return {
+            results,
+            truncationLimitReached: run.truncatedResponses >= MAX_CONSECUTIVE_TRUNCATIONS,
+        };
+    }
+    /** The text that ends a run stopped by the consecutive-truncation guard (A-88). */
+    truncationLimitMessage(input) {
+        const maxTokens = this.deps.modelManager.resolveOptions(input.options)?.maxTokens;
+        const limit = typeof maxTokens === "number" ? ` (maxTokens=${maxTokens})` : "";
+        return (`The model's output was cut off at the output token limit${limit} on ` +
+            `${MAX_CONSECUTIVE_TRUNCATIONS} consecutive responses while writing tool call arguments. ` +
+            "Raise maxTokens or ask for the work in smaller steps.");
+    }
     /** The model ended its turn: close the spans and emit RunCompleted. */
-    completeRun(run, iterations, iterSpan) {
+    // A-88: `stopReason` is "max_tokens" when the turn ended because the output token limit was
+    // hit; it is added to the run span only, RunCompleted is emitted unchanged.
+    // It is "error" when the provider reported a stop that is not a normal finish (refusal, filter).
+    completeRun(run, iterations, iterSpan, stopReason) {
         iterSpan?.end();
-        run.runSpan?.end({ iterations, totalUsage: run.totalUsage });
+        run.runSpan?.end({
+            iterations,
+            totalUsage: run.totalUsage,
+            ...(stopReason && { stopReason }),
+        });
         run.trace.close();
         run.emit(SDKEventType.RunCompleted, {
             iterations,
@@ -489,6 +889,9 @@ export class AgentLoop {
         const { totalUsage } = run;
         iterSpan?.end({ aborted: true });
         run.runSpan?.end({ iterations, totalUsage, aborted: true });
+        // Whatever else is still open (a model call or memory recall the consumer stopped
+        // reading in) ends marked aborted too, so no span outlives the run (as Go).
+        run.trace.endOpen({ aborted: true });
         run.trace.close();
         run.emit(SDKEventType.RunCompleted, {
             iterations,