@ai-agent-forge/agent-forge 0.86.1 → 0.86.3

package/dist/core/agent-session.js

@@ -103,6 +103,14 @@ export class AgentSession {
     _overflowRecoveryAttempted = false;
     // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
     _overflowTrimStage = 0;
+    /**
+     * microcompact 冷却（按模型请求计数，0 = 不冷却）：relief 落地时置
+     * MICROCOMPACT_COOLDOWN_ASSISTANT_RESPONSES，此后每次 assistant message_end
+     * （无论 stopReason）减 1、下限 0；user message_start 不复位。冷却期内阈值
+     * decide 以 microcompactEnabled:false 关闭便宜缓解。微观经济动机见
+     * agent-session-compaction.ts 的常量注释（中部历史改写 × 不稳定前缀缓存）。
+     */
+    _microcompactCooldown = 0;
     // Branch summarization state
     _branchSummaryAbortController = undefined;
     _branchSummaryPromise = undefined;
@@ -506,6 +514,11 @@ export class AgentSession {
                     this._overflowRecoveryAttempted = false;
                     this._overflowTrimStage = 0;
                 }
+                // microcompact 冷却按模型请求计数：每个完成的 assistant 响应（无论
+                // stopReason）释放一档，下限 0；冷却期内的阈值 decide 不做便宜缓解。
+                if (this._microcompactCooldown > 0) {
+                    this._microcompactCooldown -= 1;
+                }
                 // Reset retry counter immediately on successful assistant response
                 // This prevents accumulation across multiple LLM calls within a turn
                 if (assistantMsg.stopReason !== "error" && this._retryAttempt > 0) {
@@ -786,7 +799,8 @@ export class AgentSession {
             getMessages: () => detachedSessionSnapshot(this.agent.state.messages),
             isIdle: () => this.isIdle,
             prompt: (text) => this.prompt(text),
-            steer: (text) => this.steer(text),
+            // SessionAPI 契约固定 Promise<void>；disposition（"queued"/"handled"）不外泄到该面。
+            steer: (text) => this.steer(text).then(() => undefined),
             queueFollowUp: (text) => this.sendUserMessage(text, { deliverAs: "followUp" }),
             abort: () => this.abort(),
             waitForIdle: () => this.waitForIdle(),
@@ -1179,107 +1193,101 @@ export class AgentSession {
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let messages;
-        try {
-            // Handle plugin commands first (execute immediately, even during streaming).
-            if (expandPromptTemplates && text.startsWith("/")) {
-                const handled = await this._tryExecuteExtensionCommand(text);
-                if (handled) {
-                    // Extension command executed, no prompt to send
-                    preflightResult?.(true);
-                    return { status: "done" };
-                }
-            }
-            if (this._compactionAbortController !== undefined) {
-                throw new Error("Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.");
-            }
-            // Dispatch the input.gate chain, then the input.received facts (both
-            // before skill/template expansion)
-            const { text: currentText, images: currentImages } = await this._runInputHandlers(text, options?.images, options?.source ?? "interactive");
-            // Expand skill commands (/skill:name args) and prompt templates (/template args)
-            let expandedText = currentText;
-            if (expandPromptTemplates) {
-                expandedText = this._expandSkillCommand(expandedText);
-                expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-            }
-            // If streaming, queue via steer() or followUp() based on option
-            if (this.isStreaming) {
-                if (!options?.streamingBehavior) {
-                    throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
-                }
-                if (options.streamingBehavior === "followUp") {
-                    await this._queueFollowUp(expandedText, currentImages);
-                }
-                else {
-                    await this._queueSteer(expandedText, currentImages);
-                }
-                preflightResult?.(true);
+        // Handle plugin commands first (execute immediately, even during streaming).
+        if (expandPromptTemplates && text.startsWith("/")) {
+            const handled = await this._tryExecuteExtensionCommand(text);
+            if (handled) {
+                // Extension command executed, no prompt to send
+                preflightResult?.("handled");
                 return { status: "done" };
             }
-            // Flush any pending bash and custom messages before the new prompt
-            this._flushPendingBashMessages();
-            this._flushPendingCustomMessages();
-            // Validate model
-            if (!this.model) {
-                throw new Error(formatNoModelSelectedMessage());
-            }
-            const hasConfiguredAuth = this.agent.streamFunction !== streamSimple ||
-                this._modelRuntime.hasConfiguredAuth(this.model.provider) ||
-                (await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;
-            if (!hasConfiguredAuth) {
-                const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
-                if (isOAuth) {
-                    throw new Error(`Authentication failed for "${this.model.provider}". ` +
-                        `Credentials may have expired or network is unavailable. ` +
-                        `Run '/login ${this.model.provider}' to re-authenticate.`);
-                }
-                throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
-            }
-            // Check if we need to compact before sending (catches aborted responses).
-            // The user's new prompt is sent below, so do not call agent.continue() here.
-            const lastAssistant = this._findLastAssistantMessage();
-            if (lastAssistant) {
-                await this._checkCompaction(lastAssistant, false);
+        }
+        if (this._compactionAbortController !== undefined) {
+            throw new Error("Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.");
+        }
+        // Dispatch the input.gate chain, then the input.received facts (both
+        // before skill/template expansion)
+        const { text: currentText, images: currentImages } = await this._runInputHandlers(text, options?.images, options?.source ?? "interactive");
+        // Expand skill commands (/skill:name args) and prompt templates (/template args)
+        let expandedText = currentText;
+        if (expandPromptTemplates) {
+            expandedText = this._expandSkillCommand(expandedText);
+            expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        }
+        // If streaming, queue via steer() or followUp() based on option
+        if (this.isStreaming) {
+            if (!options?.streamingBehavior) {
+                throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
             }
-            // Build messages array (custom message if any, then user message)
-            messages = [];
-            // Add user message
-            const userContent = [{ type: "text", text: expandedText }];
-            if (currentImages) {
-                userContent.push(...currentImages);
+            if (options.streamingBehavior === "followUp") {
+                await this._queueFollowUp(expandedText, currentImages);
             }
-            messages.push({
-                role: "user",
-                content: userContent,
-                timestamp: Date.now(),
-            });
-            // Inject any pending "nextTurn" messages as context alongside the user message
-            for (const msg of this._pendingNextTurnMessages) {
-                messages.push(msg);
-            }
-            this._pendingNextTurnMessages = [];
-            await dispatchBeforeAgentStartLifecycle(this._internal, (currentImages?.length ?? 0) > 0);
-            // Reset to the base prompt (in case a previous turn had an override),
-            // then apply the before.agent.start@2 candidate transform (capability
-            // channel). A transform yielding a different systemPrompt is the later
-            // writer and wins; a missing registration, a verbatim result, or a
-            // failed delivery keeps the base prompt.
-            this._systemPromptOverride = undefined;
-            this.agent.state.systemPrompt = this._baseSystemPrompt;
-            const capabilitySystemPrompt = await dispatchBeforeAgentStartV2Lifecycle(this._internal, this._baseSystemPrompt, this._baseSystemPromptOptions);
-            if (capabilitySystemPrompt !== undefined) {
-                this._systemPromptOverride = capabilitySystemPrompt;
-                this.agent.state.systemPrompt = capabilitySystemPrompt;
+            else {
+                await this._queueSteer(expandedText, currentImages);
             }
+            preflightResult?.("queued");
+            return { status: "done" };
         }
-        catch (error) {
-            preflightResult?.(false);
-            throw error;
+        // Flush any pending bash and custom messages before the new prompt
+        this._flushPendingBashMessages();
+        this._flushPendingCustomMessages();
+        // Validate model
+        if (!this.model) {
+            throw new Error(formatNoModelSelectedMessage());
+        }
+        const hasConfiguredAuth = this.agent.streamFunction !== streamSimple ||
+            this._modelRuntime.hasConfiguredAuth(this.model.provider) ||
+            (await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;
+        if (!hasConfiguredAuth) {
+            const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
+            if (isOAuth) {
+                throw new Error(`Authentication failed for "${this.model.provider}". ` +
+                    `Credentials may have expired or network is unavailable. ` +
+                    `Run '/login ${this.model.provider}' to re-authenticate.`);
+            }
+            throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
+        }
+        // Check if we need to compact before sending (catches aborted responses).
+        // The user's new prompt is sent below, so do not call agent.continue() here.
+        const lastAssistant = this._findLastAssistantMessage();
+        if (lastAssistant) {
+            await this._checkCompaction(lastAssistant, false);
+        }
+        // Build messages array (custom message if any, then user message)
+        messages = [];
+        // Add user message
+        const userContent = [{ type: "text", text: expandedText }];
+        if (currentImages) {
+            userContent.push(...currentImages);
+        }
+        messages.push({
+            role: "user",
+            content: userContent,
+            timestamp: Date.now(),
+        });
+        // Inject any pending "nextTurn" messages as context alongside the user message
+        for (const msg of this._pendingNextTurnMessages) {
+            messages.push(msg);
+        }
+        this._pendingNextTurnMessages = [];
+        await dispatchBeforeAgentStartLifecycle(this._internal, (currentImages?.length ?? 0) > 0);
+        // Reset to the base prompt (in case a previous turn had an override),
+        // then apply the before.agent.start@2 candidate transform (capability
+        // channel). A transform yielding a different systemPrompt is the later
+        // writer and wins; a missing registration, a verbatim result, or a
+        // failed delivery keeps the base prompt.
+        this._systemPromptOverride = undefined;
+        this.agent.state.systemPrompt = this._baseSystemPrompt;
+        const capabilitySystemPrompt = await dispatchBeforeAgentStartV2Lifecycle(this._internal, this._baseSystemPrompt, this._baseSystemPromptOptions);
+        if (capabilitySystemPrompt !== undefined) {
+            this._systemPromptOverride = capabilitySystemPrompt;
+            this.agent.state.systemPrompt = capabilitySystemPrompt;
         }
         // v8 ignore next -- try 块内所有不发送路径均已提前 return，messages 必然已赋值
         if (!messages) {
             return { status: "done" };
         }
-        preflightResult?.(true);
+        preflightResult?.("started");
         return this._runAgentPrompt(messages);
     }
     /**
@@ -1374,6 +1382,7 @@ export class AgentSession {
         else {
             await this._queueFollowUp(expandedText, processedInput.images);
         }
+        return "queued";
     }
     /**
      * Queue a steering message while the agent is running.
@@ -1382,10 +1391,11 @@ export class AgentSession {
      * Expands skill commands and prompt templates. Errors on extension commands.
      * @param images Optional image attachments to include with the message
      * @param options Input source; defaults to interactive
+     * @returns How the input was dispatched ("queued"; "handled" if a handler consumed it)
      * @throws Error if text is an extension command
      */
     async steer(text, images, options) {
-        await this._queueUserInput(text, images, "steer", options?.source ?? "interactive");
+        return this._queueUserInput(text, images, "steer", options?.source ?? "interactive");
     }
     /**
      * Queue a follow-up message to be processed after the agent finishes.
@@ -1393,10 +1403,11 @@ export class AgentSession {
      * Expands skill commands and prompt templates. Errors on extension commands.
      * @param images Optional image attachments to include with the message
      * @param options Input source; defaults to interactive
+     * @returns How the input was dispatched ("queued"; "handled" if a handler consumed it)
      * @throws Error if text is an extension command
      */
     async followUp(text, images, options) {
-        await this._queueUserInput(text, images, "followUp", options?.source ?? "interactive");
+        return this._queueUserInput(text, images, "followUp", options?.source ?? "interactive");
     }
     /**
      * Internal: Queue a steering message (already expanded, no extension command check).