@geminixiang/mikan 1.0.0-beta.4 → 1.0.0-beta.41

package/dist/harness/runner.d.ts

@@ -14,58 +14,12 @@
  * and `auto_retry_start/_end`, preserving the event surface mikan's
  * platform adapters already render.
  */
-import { Agent, type AgentEvent, type AgentMessage, type AgentTool, type ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { Agent, type AgentMessage, type AgentTool } from "@earendil-works/pi-agent-core";
 import { type Api, type ImageContent, type Model } from "@earendil-works/pi-ai";
-import type { ExtensionRegistry } from "./extensions/registry.js";
-import type { MikanModels } from "./models.js";
-import { resolveHarnessSettings, type BudgetSettings } from "./settings.js";
+import type { RunOrigin } from "./extensions/types.js";
 import type { SessionStore } from "./session-store.js";
-export type CompactionReason = "threshold" | "overflow" | "manual";
-interface CompactionResultSummary {
-    summary: string;
-    firstKeptEntryId: string;
-    tokensBefore: number;
-}
-export type HarnessEvent = AgentEvent | {
-    type: "compaction_start";
-    reason: CompactionReason;
-} | {
-    type: "compaction_end";
-    reason: CompactionReason;
-    result?: CompactionResultSummary;
-    aborted: boolean;
-    errorMessage?: string;
-} | {
-    type: "auto_retry_start";
-    attempt: number;
-    maxAttempts: number;
-    delayMs: number;
-    errorMessage: string;
-} | {
-    type: "auto_retry_end";
-    success: boolean;
-    attempt: number;
-    finalError?: string;
-} | {
-    type: "budget_exceeded";
-    /** Which cap was hit, e.g. "cost 2.01 USD > 2 USD limit". */
-    reason: string;
-    tokens: number;
-    costUsd: number;
-    llmCalls: number;
-    durationMs: number;
-};
-export type HarnessEventListener = (event: HarnessEvent) => void | Promise<void>;
-export interface MikanAgentSessionOptions {
-    systemPrompt: string;
-    model: Model<Api>;
-    thinkingLevel: ThinkingLevel;
-    tools: AgentTool[];
-    models: MikanModels;
-    sessionStore: SessionStore;
-    settings?: Parameters<typeof resolveHarnessSettings>[0];
-    extensions?: ExtensionRegistry;
-}
+import type { BudgetSettings, HarnessEventListener, MikanAgentSessionOptions, PromptBlockedOutcome, SubagentUsage, SubagentUsageSink } from "./types.js";
+export type { CompactionReason, HarnessEvent, HarnessEventListener, MikanAgentSessionOptions, PromptBlockedOutcome, } from "./types.js";
 export declare class MikanAgentSession {
     readonly agent: Agent;
     readonly sessionStore: SessionStore;
@@ -77,48 +31,90 @@ export declare class MikanAgentSession {
     private overflowRecoveryAttempted;
     private retryAbortController;
     private compactionAbortController;
+    private runActive;
     private tally;
     private runBudget;
     private budgetExceededReason;
+    private runOrigin;
     constructor(options: MikanAgentSessionOptions);
     /** Conversation transcript currently held by the agent. */
     get messages(): AgentMessage[];
     get model(): Model<Api>;
+    /** Whether this session currently owns a prompt, including pre-model hooks. */
+    get isActiveRun(): boolean;
+    /** Resource totals and terminal budget state from the most recent prompt. */
+    getLastRunStats(): Readonly<{
+        usage: SubagentUsage;
+        tokens: number;
+        costUsd: number;
+        llmCalls: number;
+        toolCalls: number;
+        toolCallCounts: Record<string, number>;
+        durationMs: number;
+        budgetExceededReason?: string;
+    }>;
+    /**
+     * Fold spend incurred outside this session's own LLM calls — e.g. subagent
+     * runs launched by a tool during the current prompt — into the run tally
+     * and enforce the run budget at the fold itself: a fold that lands over a
+     * resource ceiling aborts the run now instead of waiting for a next
+     * assistant message that may never come (and would be paid for). Complete
+     * usage is folded; external runs are not this session's turns.
+     */
+    /** Capture a usage sink bound to the tally owned by the current prompt run. */
+    captureExternalUsageSink(): SubagentUsageSink;
+    foldExternalUsage(usage: SubagentUsage): Promise<void>;
     subscribe(listener: HarnessEventListener): () => void;
     /** Replace the agent transcript from the persisted session tree. */
     reloadFromSession(): number;
     /**
      * Send a user prompt and run the agent loop to completion, including
      * automatic retries and compaction. Resolves when the turn (and any
-     * recovery continuations) settles.
+     * recovery continuations) settles. Returns a blocked outcome when a
+     * `before_agent_start` extension blocked the turn — the model was never
+     * called and nothing was persisted.
      *
      * @param options.budget Per-run resource ceilings that override the session
      *   defaults. Autonomous (event / trigger) runs should pass a budget so a
      *   runaway loop is stopped even with no human watching.
+     * @param options.origin Platform provenance forwarded to extension hooks.
      */
     prompt(text: string, options?: {
         images?: ImageContent[];
         budget?: BudgetSettings;
-    }): Promise<void>;
+        origin?: RunOrigin;
+        tools?: AgentTool[];
+    }): Promise<PromptBlockedOutcome | undefined>;
+    private runPrompt;
     /** Abort the active run, pending retry backoff, and in-flight compaction. */
     abort(): void;
     private ensureAuthConfigured;
     private emit;
     private handleAgentEvent;
-    /** Fold one assistant turn's usage into the running per-run tally. */
+    /** Fold one assistant completion's usage into the running per-run tally. */
     private recordUsage;
     /** Compare the tally against the run budget; abort the run when a cap is exceeded. */
     private enforceBudget;
+    /** Mark the run over budget, notify listeners and extensions, abort the agent. */
+    private exceedBudget;
     private overBudgetReason;
+    /** The message-independent budget checks, shared with external-spend folds. */
+    private resourceOverBudgetReason;
     private findLastAssistantMessage;
     /** Decide what to do after a run settles. Returns true when the agent should continue. */
     private handlePostRun;
     private handleOverflow;
     private checkThresholdCompaction;
     private runCompaction;
+    /**
+     * Compaction can make one completion, or two when its cut splits a turn.
+     * Intercept only those opaque upstream calls so each returned assistant
+     * message is tallied exactly once. A call at maxLlmCalls is not started;
+     * the cap is otherwise enforced before any post-compaction continuation.
+     */
+    private createCompactionModels;
     private isRetryableError;
     private prepareRetry;
     private dropTrailingErrorMessage;
 }
-export {};
 //# sourceMappingURL=runner.d.ts.map

package/dist/harness/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/harness/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/harness/runner.ts"],"names":[],"mappings":"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"}

package/dist/harness/runner.js

@@ -18,6 +18,7 @@ import { Agent, calculateContextTokens, compact, convertToLlm, estimateContextTo
 import { isContextOverflow, } from "@earendil-works/pi-ai";
 import * as log from "../log.js";
 import { resolveHarnessSettings } from "./settings.js";
+import { addSubagentUsage, copySubagentUsage, createEmptySubagentUsage } from "./usage.js";
 // Transient provider failures worth retrying: overload/rate-limit responses,
 // 5xx statuses, and network/stream interruptions.
 const RETRYABLE_ERROR_PATTERN = /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|stream ended before message_stop|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i;
@@ -43,7 +44,14 @@ export class MikanAgentSession {
         this.listeners = new Set();
         this.retryAttempt = 0;
         this.overflowRecoveryAttempted = false;
-        this.tally = { tokens: 0, costUsd: 0, llmCalls: 0, startedAt: 0 };
+        this.runActive = false;
+        this.tally = {
+            usage: createEmptySubagentUsage(),
+            llmCalls: 0,
+            toolCalls: 0,
+            toolCallCounts: {},
+            startedAt: 0,
+        };
         this.runBudget = {};
         this.models = options.models;
         this.sessionStore = options.sessionStore;
@@ -58,6 +66,11 @@ export class MikanAgentSession {
                 tools,
             },
             convertToLlm,
+            transformContext: async (messages) => {
+                if (!this.extensions?.hasHandlers("context"))
+                    return messages;
+                return this.extensions.emitContext({ messages, origin: this.runOrigin });
+            },
             streamFn: (model, context, streamOptions) => this.models.models.streamSimple(model, context, streamOptions),
             beforeToolCall: async ({ toolCall, args }) => {
                 if (!this.extensions?.hasHandlers("tool_call"))
@@ -66,20 +79,26 @@ export class MikanAgentSession {
                     toolCallId: toolCall.id,
                     toolName: toolCall.name,
                     args,
+                    origin: this.runOrigin,
                 });
                 return result ?? undefined;
             },
             afterToolCall: async ({ toolCall, args, result, isError }) => {
-                if (this.extensions?.hasHandlers("tool_result")) {
-                    await this.extensions.emit("tool_result", {
-                        toolCallId: toolCall.id,
-                        toolName: toolCall.name,
-                        args,
-                        content: result.content,
-                        isError,
-                    });
-                }
-                return undefined;
+                if (!this.extensions?.hasHandlers("tool_result"))
+                    return undefined;
+                // Chained extension rewrites (redaction, truncation) become a
+                // pi-agent-core AfterToolCallResult override; undefined keeps the
+                // executed result untouched.
+                return this.extensions.emitToolResult({
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.name,
+                    args,
+                    content: result.content,
+                    details: result.details,
+                    isError,
+                    usage: result.usage,
+                    origin: this.runOrigin,
+                });
             },
         });
         this.agent.subscribe(async (event) => {
@@ -93,6 +112,46 @@ export class MikanAgentSession {
     get model() {
         return this.agent.state.model;
     }
+    /** Whether this session currently owns a prompt, including pre-model hooks. */
+    get isActiveRun() {
+        return this.runActive;
+    }
+    /** Resource totals and terminal budget state from the most recent prompt. */
+    getLastRunStats() {
+        return {
+            usage: copySubagentUsage(this.tally.usage),
+            tokens: this.tally.usage.totalTokens,
+            costUsd: this.tally.usage.cost.total,
+            llmCalls: this.tally.llmCalls,
+            toolCalls: this.tally.toolCalls,
+            toolCallCounts: { ...this.tally.toolCallCounts },
+            durationMs: this.tally.startedAt > 0 ? Date.now() - this.tally.startedAt : 0,
+            ...(this.budgetExceededReason ? { budgetExceededReason: this.budgetExceededReason } : {}),
+        };
+    }
+    /**
+     * Fold spend incurred outside this session's own LLM calls — e.g. subagent
+     * runs launched by a tool during the current prompt — into the run tally
+     * and enforce the run budget at the fold itself: a fold that lands over a
+     * resource ceiling aborts the run now instead of waiting for a next
+     * assistant message that may never come (and would be paid for). Complete
+     * usage is folded; external runs are not this session's turns.
+     */
+    /** Capture a usage sink bound to the tally owned by the current prompt run. */
+    captureExternalUsageSink() {
+        const tally = this.tally;
+        return async (usage) => {
+            addSubagentUsage(tally.usage, usage);
+            if (this.tally !== tally || this.budgetExceededReason || !this.runActive)
+                return;
+            const reason = this.resourceOverBudgetReason();
+            if (reason)
+                await this.exceedBudget(reason);
+        };
+    }
+    async foldExternalUsage(usage) {
+        await this.captureExternalUsageSink()(usage);
+    }
     subscribe(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
@@ -108,53 +167,107 @@ export class MikanAgentSession {
     /**
      * Send a user prompt and run the agent loop to completion, including
      * automatic retries and compaction. Resolves when the turn (and any
-     * recovery continuations) settles.
+     * recovery continuations) settles. Returns a blocked outcome when a
+     * `before_agent_start` extension blocked the turn — the model was never
+     * called and nothing was persisted.
      *
      * @param options.budget Per-run resource ceilings that override the session
      *   defaults. Autonomous (event / trigger) runs should pass a budget so a
      *   runaway loop is stopped even with no human watching.
+     * @param options.origin Platform provenance forwarded to extension hooks.
      */
     async prompt(text, options) {
-        if (this.agent.state.isStreaming) {
+        if (this.runActive) {
             throw new Error("Agent is already processing a prompt");
         }
+        this.runActive = true;
+        const runSystemPrompt = this.agent.state.systemPrompt;
+        const runTools = this.agent.state.tools;
+        if (options?.tools)
+            this.agent.state.tools = options.tools;
+        try {
+            return await this.runPrompt(text, runSystemPrompt, options);
+        }
+        finally {
+            this.agent.state.systemPrompt = runSystemPrompt;
+            this.agent.state.tools = runTools;
+            this.runActive = false;
+        }
+    }
+    async runPrompt(text, runSystemPrompt, options) {
         const model = this.agent.state.model;
         await this.ensureAuthConfigured(model);
         this.retryAttempt = 0;
         this.overflowRecoveryAttempted = false;
         this.runBudget = { ...this.settings.budget, ...options?.budget };
         this.budgetExceededReason = undefined;
-        this.tally = { tokens: 0, costUsd: 0, llmCalls: 0, startedAt: Date.now() };
+        this.tally = {
+            usage: createEmptySubagentUsage(),
+            llmCalls: 0,
+            toolCalls: 0,
+            toolCallCounts: {},
+            startedAt: Date.now(),
+        };
+        this.runOrigin = options?.origin;
         // A previous turn may have ended over the threshold (for example after an
         // abort); compact before adding new context on top.
         const lastAssistant = this.findLastAssistantMessage();
         if (lastAssistant && lastAssistant.stopReason !== "error") {
             await this.checkThresholdCompaction(lastAssistant);
         }
-        let systemPrompt = this.agent.state.systemPrompt;
+        let promptText = text;
+        let systemPrompt = runSystemPrompt;
         if (this.extensions?.hasHandlers("before_agent_start")) {
-            const result = await this.extensions.emit("before_agent_start", {
-                prompt: text,
+            const result = await this.extensions.emitBeforeAgentStart({
+                prompt: promptText,
                 images: options?.images,
                 systemPrompt,
+                origin: this.runOrigin,
             });
-            if (result?.systemPrompt) {
+            if (result?.block) {
+                // Blocked before agent.prompt(): the user message never enters the
+                // transcript or session store, so the blocked turn leaves no trace.
+                log.logInfo(`Extension blocked turn${result.reason ? `: ${result.reason}` : ""}`);
+                return { blocked: true, reason: result.reason };
+            }
+            if (result?.prompt !== undefined && result.prompt !== promptText) {
+                log.logInfo(`Extension rewrote user prompt: ${promptText.length} → ${result.prompt.length} chars`);
+                promptText = result.prompt;
+            }
+            if (result?.systemPrompt && result.systemPrompt !== systemPrompt) {
+                // An extension rewrote the system prompt for this turn. Log the new
+                // size so the diagnostic in agent.ts (which logs the pre-hook prompt)
+                // isn't mistaken for the final prompt sent to the model.
+                log.logInfo(`Extension rewrote system prompt: ${systemPrompt.length} → ${result.systemPrompt.length} chars`);
                 systemPrompt = result.systemPrompt;
                 this.agent.state.systemPrompt = systemPrompt;
             }
         }
         const userMessage = {
             role: "user",
-            content: [{ type: "text", text }, ...(options?.images ?? [])],
+            content: [{ type: "text", text: promptText }, ...(options?.images ?? [])],
             timestamp: Date.now(),
         };
         await this.agent.prompt([userMessage]);
         while (await this.handlePostRun()) {
             await this.agent.continue();
         }
+        // The turn settled on an error (retries exhausted or not retryable):
+        // give monitoring extensions the final failure, once per turn.
+        const settled = this.findLastAssistantMessage();
+        if (settled?.stopReason === "error" && this.extensions?.hasHandlers("agent_error")) {
+            await this.extensions.emit("agent_error", {
+                errorMessage: settled.errorMessage || "Unknown error",
+                origin: this.runOrigin,
+            });
+        }
         if (this.extensions?.hasHandlers("turn_end")) {
-            await this.extensions.emit("turn_end", { messages: this.agent.state.messages });
+            await this.extensions.emit("turn_end", {
+                messages: this.agent.state.messages,
+                origin: this.runOrigin,
+            });
         }
+        return undefined;
     }
     /** Abort the active run, pending retry backoff, and in-flight compaction. */
     abort() {
@@ -179,10 +292,25 @@ export class MikanAgentSession {
         }
     }
     async handleAgentEvent(event) {
-        await this.emit(event);
-        if (event.type !== "message_end")
+        if (event.type === "tool_execution_start") {
+            this.tally.toolCalls += 1;
+            this.tally.toolCallCounts[event.toolName] =
+                (this.tally.toolCallCounts[event.toolName] ?? 0) + 1;
+        }
+        if (event.type !== "message_end") {
+            await this.emit(event);
             return;
-        const message = event.message;
+        }
+        let message = event.message;
+        if (this.extensions?.hasHandlers("message_end")) {
+            const result = await this.extensions.emitMessageEnd({ message, origin: this.runOrigin });
+            if (result?.message) {
+                for (const key of Object.keys(message)) {
+                    delete message[key];
+                }
+                Object.assign(message, result.message);
+            }
+        }
         if (message.role === "user" || message.role === "assistant" || message.role === "toolResult") {
             this.sessionStore.appendMessage(message);
         }
@@ -190,12 +318,10 @@ export class MikanAgentSession {
             const custom = message;
             this.sessionStore.appendCustomMessageEntry(custom.customType, custom.content, custom.display, custom.details);
         }
-        if (this.extensions?.hasHandlers("message_end")) {
-            await this.extensions.emit("message_end", { message });
-        }
+        await this.emit({ ...event, message });
         if (message.role === "assistant") {
             this.recordUsage(message);
-            await this.enforceBudget();
+            await this.enforceBudget(message);
             if (message.stopReason !== "error") {
                 this.overflowRecoveryAttempted = false;
                 if (this.retryAttempt > 0) {
@@ -205,44 +331,65 @@ export class MikanAgentSession {
             }
         }
     }
-    /** Fold one assistant turn's usage into the running per-run tally. */
+    /** Fold one assistant completion's usage into the running per-run tally. */
     recordUsage(message) {
         this.tally.llmCalls += 1;
         const usage = message.usage;
         if (!usage)
             return;
-        this.tally.tokens += usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
-        this.tally.costUsd += usage.cost?.total ?? 0;
+        addSubagentUsage(this.tally.usage, usage);
     }
     /** Compare the tally against the run budget; abort the run when a cap is exceeded. */
-    async enforceBudget() {
+    async enforceBudget(message) {
         if (this.budgetExceededReason)
             return;
-        const reason = this.overBudgetReason();
+        const reason = this.overBudgetReason(message);
         if (!reason)
             return;
+        await this.exceedBudget(reason);
+    }
+    /** Mark the run over budget, notify listeners and extensions, abort the agent. */
+    async exceedBudget(reason) {
+        if (this.budgetExceededReason)
+            return;
         this.budgetExceededReason = reason;
         await this.emit({
             type: "budget_exceeded",
             reason,
-            tokens: this.tally.tokens,
-            costUsd: this.tally.costUsd,
+            tokens: this.tally.usage.totalTokens,
+            costUsd: this.tally.usage.cost.total,
             llmCalls: this.tally.llmCalls,
             durationMs: Date.now() - this.tally.startedAt,
         });
+        if (this.extensions?.hasHandlers("budget_exceeded")) {
+            await this.extensions.emit("budget_exceeded", {
+                reason,
+                tokens: this.tally.usage.totalTokens,
+                costUsd: this.tally.usage.cost.total,
+                llmCalls: this.tally.llmCalls,
+                durationMs: Date.now() - this.tally.startedAt,
+                origin: this.runOrigin,
+            });
+        }
         log.logWarning("Run budget exceeded — aborting", reason);
         this.agent.abort();
     }
-    overBudgetReason() {
-        const { maxTokens, maxCostUsd, maxDurationMs, maxLlmCalls } = this.runBudget;
-        if (maxLlmCalls !== undefined && this.tally.llmCalls >= maxLlmCalls) {
+    overBudgetReason(message) {
+        const { maxLlmCalls } = this.runBudget;
+        const needsAnotherCall = message.stopReason === "error" || message.content.some((part) => part.type === "toolCall");
+        if (needsAnotherCall && maxLlmCalls !== undefined && this.tally.llmCalls >= maxLlmCalls) {
             return `${this.tally.llmCalls} LLM calls >= ${maxLlmCalls} limit`;
         }
-        if (maxTokens !== undefined && this.tally.tokens >= maxTokens) {
-            return `${this.tally.tokens} tokens >= ${maxTokens} limit`;
+        return this.resourceOverBudgetReason();
+    }
+    /** The message-independent budget checks, shared with external-spend folds. */
+    resourceOverBudgetReason() {
+        const { maxTokens, maxCostUsd, maxDurationMs } = this.runBudget;
+        if (maxTokens !== undefined && this.tally.usage.totalTokens >= maxTokens) {
+            return `${this.tally.usage.totalTokens} tokens >= ${maxTokens} limit`;
         }
-        if (maxCostUsd !== undefined && this.tally.costUsd >= maxCostUsd) {
-            return `cost ${this.tally.costUsd.toFixed(2)} USD >= ${maxCostUsd} USD limit`;
+        if (maxCostUsd !== undefined && this.tally.usage.cost.total >= maxCostUsd) {
+            return `cost ${this.tally.usage.cost.total.toFixed(2)} USD >= ${maxCostUsd} USD limit`;
         }
         if (maxDurationMs !== undefined && Date.now() - this.tally.startedAt >= maxDurationMs) {
             return `${Date.now() - this.tally.startedAt}ms >= ${maxDurationMs}ms limit`;
@@ -253,7 +400,7 @@ export class MikanAgentSession {
         const messages = this.agent.state.messages;
         for (let i = messages.length - 1; i >= 0; i--) {
             const message = messages[i];
-            if (message.role === "assistant")
+            if (message?.role === "assistant")
                 return message;
         }
         return undefined;
@@ -322,12 +469,19 @@ export class MikanAgentSession {
             started = true;
             this.compactionAbortController = new AbortController();
             const signal = this.compactionAbortController.signal;
-            const result = getOrThrow(await compact(preparation, this.models.models, this.agent.state.model, undefined, signal, this.agent.state.thinkingLevel));
+            const result = getOrThrow(await compact(preparation, this.createCompactionModels(), this.agent.state.model, undefined, signal, this.agent.state.thinkingLevel));
             if (signal.aborted) {
                 await this.emit({ type: "compaction_end", reason, aborted: true });
                 return false;
             }
-            const entryId = this.sessionStore.appendCompaction(result.summary, result.firstKeptEntryId, result.tokensBefore, result.details);
+            // pi 0.82 reserves an absent firstKeptEntryId for keep-nothing
+            // compactions; mikan's session format requires a kept entry on the
+            // branch, and the compaction path used here always produces one.
+            const firstKeptEntryId = result.firstKeptEntryId;
+            if (firstKeptEntryId === undefined) {
+                throw new Error("compaction returned no first kept entry");
+            }
+            const entryId = this.sessionStore.appendCompaction(result.summary, firstKeptEntryId, result.tokensBefore, result.details);
             const context = this.sessionStore.buildSessionContext();
             this.agent.state.messages = context.messages;
             if (this.extensions?.hasHandlers("session_compact")) {
@@ -344,11 +498,13 @@ export class MikanAgentSession {
                 reason,
                 result: {
                     summary: result.summary,
-                    firstKeptEntryId: result.firstKeptEntryId,
+                    firstKeptEntryId,
                     tokensBefore: result.tokensBefore,
                 },
                 aborted: false,
             });
+            if (this.budgetExceededReason)
+                return false;
             if (willRetry) {
                 this.dropTrailingErrorMessage();
                 return true;
@@ -376,6 +532,36 @@ export class MikanAgentSession {
             this.compactionAbortController = undefined;
         }
     }
+    /**
+     * Compaction can make one completion, or two when its cut splits a turn.
+     * Intercept only those opaque upstream calls so each returned assistant
+     * message is tallied exactly once. A call at maxLlmCalls is not started;
+     * the cap is otherwise enforced before any post-compaction continuation.
+     */
+    createCompactionModels() {
+        const models = this.models.models;
+        return new Proxy(models, {
+            get: (target, property) => {
+                if (property === "completeSimple") {
+                    return async (...args) => {
+                        const maxLlmCalls = this.runBudget.maxLlmCalls;
+                        if (maxLlmCalls !== undefined && this.tally.llmCalls >= maxLlmCalls) {
+                            await this.exceedBudget(`${this.tally.llmCalls} LLM calls >= ${maxLlmCalls} limit`);
+                            throw new Error("Compaction LLM-call budget exhausted");
+                        }
+                        const message = await target.completeSimple(...args);
+                        this.recordUsage(message);
+                        const reason = this.resourceOverBudgetReason();
+                        if (reason)
+                            await this.exceedBudget(reason);
+                        return message;
+                    };
+                }
+                const value = Reflect.get(target, property, target);
+                return typeof value === "function" ? value.bind(target) : value;
+            },
+        });
+    }
     isRetryableError(message) {
         if (message.stopReason !== "error" || !message.errorMessage)
             return false;
@@ -428,7 +614,7 @@ export class MikanAgentSession {
     }
     dropTrailingErrorMessage() {
         const messages = this.agent.state.messages;
-        if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
+        if (messages[messages.length - 1]?.role === "assistant") {
             this.agent.state.messages = messages.slice(0, -1);
         }
     }