@ai-agent-forge/agent-forge 0.86.7 → 0.88.0

package/dist/core/agent-session.js

@@ -33,6 +33,7 @@ import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth
 import { THINKING_LEVEL_OPTIONS } from "./defaults.js";
 import { definitionSnapshot, detachedSnapshot } from "./extensions/capability-runtime-snapshot.js";
 import { BOOTSTRAP_AGENT_LOOP_PLUGIN_ID, BOOTSTRAP_BRANCH_SUMMARY_PLUGIN_ID, BOOTSTRAP_COMPACTION_PLUGIN_ID, BOOTSTRAP_LIFECYCLE_PLUGIN_ID, BOOTSTRAP_OVERFLOW_PLUGIN_ID, BOOTSTRAP_RETRY_PLUGIN_ID, BOOTSTRAP_SKILLS_PLUGIN_ID, BOOTSTRAP_TOOLS_PLUGIN_ID, createCapabilityRuntime, DEFAULT_BRANCH_SUMMARY_POLICY_NAME, DEFAULT_COMPACTION_POLICY_NAME, DEFAULT_OVERFLOW_POLICY_NAME, DEFAULT_RETRY_POLICY_NAME, DEFAULT_RUN_LOOP_STRATEGY_NAME, EXPERIMENTAL_PUBLIC_API_VERSION, installBootstrapAgentLoop, installBootstrapBranchSummaryPolicy, installBootstrapCompactionPolicy, installBootstrapLifecycle, installBootstrapOverflowPolicy, installBootstrapRetryPolicy, installSessionBootstrapSkills, installSessionBootstrapTools, loadCapabilityPluginFromManifest, loadCapabilityPlugin as loadCapabilityPluginRuntime, } from "./extensions/index.js";
+import { t } from "./i18n/index.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { createSessionJsonlArtifact } from "./session-export.js";
 import { createToolSearchTool } from "./tools/tool-search.js";
@@ -103,14 +104,6 @@ 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;
@@ -446,12 +439,23 @@ export class AgentSession {
             };
             await this._dispatchModelStreamLifecycle(event.message, "start", "raw");
         }
-        // When a user message starts, check if it's from either queue and remove it BEFORE emitting
-        // This ensures the UI sees the updated queue state
-        if (event.type === "message_start" && event.message.role === "user") {
-            this._overflowRecoveryAttempted = false;
-            this._overflowTrimStage = 0;
-            const messageText = contentText(event.message.content, "");
+        // When a user or custom message starts, check if it's from either queue and
+        // remove it BEFORE emitting. This ensures the UI sees the updated queue state.
+        // Queued custom messages (sendCustomMessage deliverAs steer/followUp) are
+        // registered in the copy arrays under their contentText text and delivered
+        // with role "custom", so they must go through the same copy-removal path
+        // (D-078 fix).
+        if (event.type === "message_start" && (event.message.role === "user" || event.message.role === "custom")) {
+            if (event.message.role === "user") {
+                this._overflowRecoveryAttempted = false;
+                this._overflowTrimStage = 0;
+            }
+            // Custom queue entries register their copy text via _queuedCopyText
+            // (placeholder for textless content); match removal with the same
+            // expression so both sides stay symmetric.
+            const messageText = event.message.role === "custom"
+                ? this._queuedCopyText(event.message.content)
+                : contentText(event.message.content, "");
             if (messageText) {
                 // Check steering queue first
                 const steeringIndex = this._steeringMessages.indexOf(messageText);
@@ -514,11 +518,6 @@ 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) {
@@ -738,7 +737,7 @@ export class AgentSession {
     /** Public capability runtime for external orchestration and plugin composition. */
     getCapabilityRuntime() {
         if (!this._capabilityRuntime)
-            throw new Error("Capability runtime is not available");
+            throw new Error(t("Capability runtime is not available"));
         return this._capabilityRuntime;
     }
     /**
@@ -774,18 +773,21 @@ export class AgentSession {
             commitContext: async (request) => {
                 const commit = this._contextCommitQueue.then(async () => {
                     if (request.signal?.aborted)
-                        throw new Error("Context commit cancelled");
+                        throw new Error(t("Context commit cancelled"));
                     const currentRevision = this._contextRevision;
                     if (request.operationId.trim() === "")
-                        throw new Error("Context commit operationId is required");
+                        throw new Error(t("Context commit operationId is required"));
                     if (request.expectedRevision !== currentRevision) {
-                        throw new Error(`Context revision conflict: expected ${request.expectedRevision}, current ${currentRevision}`);
+                        throw new Error(t("Context revision conflict: expected {expected}, current {current}", {
+                            expected: request.expectedRevision,
+                            current: currentRevision,
+                        }));
                     }
                     if (!Array.isArray(request.value))
-                        throw new Error("Session context commit requires a message array");
+                        throw new Error(t("Session context commit requires a message array"));
                     await this.replaceContext(request.value);
                     if (request.signal?.aborted)
-                        throw new Error("Context commit cancelled");
+                        throw new Error(t("Context commit cancelled"));
                     return {
                         version: 1,
                         status: "committed",
@@ -868,7 +870,7 @@ export class AgentSession {
             }))),
             exportArtifact: (request) => {
                 if (request.format !== "jsonl")
-                    throw new Error(`Unsupported session export format: ${request.format}`);
+                    throw new Error(t("Unsupported session export format: {format}", { format: request.format }));
                 return createSessionJsonlArtifact(this.sessionManager);
             },
         };
@@ -1007,6 +1009,11 @@ export class AgentSession {
             .filter((tool) => this._capabilityMode !== "readonly" ||
             (!tool.source.startsWith("agent-forge.builtin.") && !tool.source.startsWith("agent-forge.plugin.")) ||
             tool.readonlySafe === true)
+            // Deferred plugin tools register but stay out of the active set on
+            // this explicit-activation path too, until tool_search or
+            // setActiveTools names them (same contract as the default path in
+            // agent-session-tools.ts).
+            .filter((tool) => !this._deferredToolPluginIds.has(tool.source))
             .map((tool) => tool.name)
             .filter((name) => !previousToolNames.has(name));
         this._refreshToolRegistry({
@@ -1019,10 +1026,10 @@ export class AgentSession {
         const runtime = this._capabilityRuntime;
         // v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在
         if (!runtime)
-            throw new Error("Capability runtime is not available");
+            throw new Error(t("Capability runtime is not available"));
         const resolvedManifestPath = resolve(this._cwd, manifestPath);
         if (this._capabilityPlugins.has(resolvedManifestPath)) {
-            throw new Error(`Capability plugin manifest is already loaded: ${resolvedManifestPath}`);
+            throw new Error(t("Capability plugin manifest is already loaded: {path}", { path: resolvedManifestPath }));
         }
         const previousToolNames = new Set(runtime.listTools().map((tool) => tool.name));
         const loaded = await loadCapabilityPluginFromManifest(runtime, resolvedManifestPath, options);
@@ -1037,10 +1044,10 @@ export class AgentSession {
         const runtime = this._capabilityRuntime;
         // v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在
         if (!runtime)
-            throw new Error("Capability runtime is not available");
+            throw new Error(t("Capability runtime is not available"));
         const key = `inline:${manifest.id}`;
         if (this._capabilityPlugins.has(key)) {
-            throw new Error(`Capability plugin is already loaded in this session: ${manifest.id}`);
+            throw new Error(t("Capability plugin is already loaded in this session: {id}", { id: manifest.id }));
         }
         const previousToolNames = new Set(runtime.listTools().map((tool) => tool.name));
         const loaded = await loadCapabilityPluginRuntime(runtime, manifest, factory);
@@ -1166,7 +1173,9 @@ export class AgentSession {
                     textLength: currentText.length,
                     reason,
                 });
-                throw new Error(reason === undefined ? "Input rejected by an input gate" : `Input rejected by an input gate: ${reason}`);
+                throw new Error(reason === undefined
+                    ? t("Input rejected by an input gate")
+                    : t("Input rejected by an input gate: {reason}", { reason }));
             }
             if ("text" in result && typeof result.text === "string") {
                 currentText = result.text;
@@ -1188,7 +1197,7 @@ export class AgentSession {
      */
     async prompt(text, options) {
         if (this._reloadInProgress) {
-            throw new Error("Session reload in progress; prompts are unavailable");
+            throw new Error(t("Session reload in progress; prompts are unavailable"));
         }
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
@@ -1203,7 +1212,7 @@ export class AgentSession {
             }
         }
         if (this._compactionAbortController !== undefined) {
-            throw new Error("Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.");
+            throw new Error(t("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)
@@ -1217,7 +1226,7 @@ export class AgentSession {
         // 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.");
+                throw new Error(t("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message."));
             }
             if (options.streamingBehavior === "followUp") {
                 await this._queueFollowUp(expandedText, currentImages);
@@ -1241,9 +1250,7 @@ export class AgentSession {
         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(t("Authentication failed for \"{provider}\". Credentials may have expired or network is unavailable. Run '/login {provider}' to re-authenticate.", { provider: this.model.provider }));
             }
             throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
         }
@@ -1306,7 +1313,10 @@ export class AgentSession {
             const skillConflict = skillName !== undefined && this._getAvailableSkills().some((skill) => skill.name === skillName);
             if (templateConflict || skillConflict) {
                 const source = templateConflict ? "prompt template" : "skill";
-                throw new Error(`Command is registered by both CapabilityAPI and ${source}: ${commandName}`);
+                throw new Error(t("Command is registered by both CapabilityAPI and {source}: {command}", {
+                    source,
+                    command: commandName,
+                }));
             }
         }
         else {
@@ -1445,9 +1455,15 @@ export class AgentSession {
      * Send a custom message to the session. Creates a CustomMessageEntry.
      *
      * Handles four cases:
-     * - Streaming: queues message, processed when loop pulls from queue
+     * - Streaming: queues message (registered in the queued-message view via its
+     *   text content), processed when loop pulls from queue
      * - Streaming + triggerTurn false: appended to state/session once the current turn ends
-     * - Not streaming + triggerTurn: appends to state/session, starts new turn
+     * - Not streaming + triggerTurn: appends to state/session, starts new turn —
+     *   unless manual compaction is in flight (same guard as prompt()), in which
+     *   case the message degrades to a followUp queue entry instead of a
+     *   concurrent turn (D-060 ruling 12 boundary: the compaction revision
+     *   mutex must not be pierced; the queued message is drained at the next
+     *   driving point after compaction ends)
      * - Not streaming + no trigger: appends to state/session, no turn
      *
      * @param message Custom message with customType, content, display, details
@@ -1468,15 +1484,34 @@ export class AgentSession {
             this._pendingNextTurnMessages.push(appMessage);
         }
         else if (this.isStreaming && options?.triggerTurn !== false) {
+            // Register the queued text in the session's queued-message view so the
+            // display copy and the agent queue stay isomorphic (D-078 fix). See
+            // _queuedCopyText for the placeholder rationale.
+            const queuedText = this._queuedCopyText(appMessage.content);
             if (options?.deliverAs === "followUp") {
+                this._followUpMessages.push(queuedText);
                 this.agent.followUp(appMessage);
             }
             else {
+                this._steeringMessages.push(queuedText);
                 this.agent.steer(appMessage);
             }
+            this._emitQueueUpdate();
         }
         else if (options?.triggerTurn) {
-            await this._runAgentPrompt(appMessage);
+            if (this._compactionAbortController !== undefined) {
+                // 压缩互斥窗口（D-060 裁决 12 边界，复审 C-1）：手动压缩进行中（与
+                // prompt() 同判据同字段）时不起并发回合——压缩提交按 revision 互斥，
+                // 并发验收回合会以 revision conflict 打断用户压缩。回注降级为
+                // followUp 入队：消息不丢（队列可见），压缩结束后的下一驱动点（用户
+                // 下一交互或下一结算回注）drain 注入。
+                this._followUpMessages.push(this._queuedCopyText(appMessage.content));
+                this.agent.followUp(appMessage);
+                this._emitQueueUpdate();
+            }
+            else {
+                await this._runAgentPrompt(appMessage);
+            }
         }
         else if (this.isStreaming) {
             // Appending now would put the message between an assistant tool call and its
@@ -1489,6 +1524,20 @@ export class AgentSession {
             this._appendCustomMessage(appMessage);
         }
     }
+    /**
+     * Copy text registered in the queued-message view for a queued custom
+     * message. The copy holds the message's text content; CustomMessage.display
+     * is a boolean visibility flag, not display text. Content without text
+     * (e.g. images only) registers a placeholder: an empty copy entry would
+     * never be matched for removal on delivery (the drain-side guard skips
+     * empty text) and would desynchronize both layers (D-078). The placeholder
+     * is a stable literal, deliberately not localized — both registration and
+     * removal must derive the same string, even if the UI language changes
+     * between the two calls.
+     */
+    _queuedCopyText(content) {
+        return contentText(content, "") || "(no text)";
+    }
     _appendCustomMessage(appMessage) {
         this.agent.state.messages.push(appMessage);
         this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details);
@@ -1559,6 +1608,55 @@ export class AgentSession {
         this._emitQueueUpdate();
         return { steering, followUp };
     }
+    /**
+     * Move a queued message from index `from` to index `to` within the steering
+     * or follow-up queue. Indices refer to the session's queued-message view
+     * (getSteeringMessages()/getFollowUpMessages() and queue_update payloads)
+     * at the moment of the call; the same move is applied to the agent queue.
+     * During streaming, drain points consume queued messages, so previously
+     * observed indices can become stale.
+     * @returns true when the message moved; false for from === to, out-of-bounds
+     * indices, or an agent-side rejection — both layers stay untouched in every
+     * false case
+     */
+    reorderQueuedMessages(queue, from, to) {
+        const copy = queue === "steer" ? this._steeringMessages : this._followUpMessages;
+        if (from === to || from < 0 || to < 0 || from >= copy.length || to >= copy.length) {
+            return false;
+        }
+        // Apply the move on the agent queue first and mirror it on the session copy
+        // only after the agent accepts it. A rejected move (stale index) leaves
+        // both layers untouched instead of widening a copy/queue mismatch.
+        if (!this.agent.reorderQueuedMessages(queue, from, to)) {
+            return false;
+        }
+        const [moved] = copy.splice(from, 1);
+        copy.splice(to, 0, moved);
+        this._emitQueueUpdate();
+        return true;
+    }
+    /**
+     * Remove the queued message at `index` from the steering or follow-up queue.
+     * Indices refer to the session's queued-message view at the moment of the
+     * call; the same removal is applied to the agent queue.
+     * @returns The removed queued text, or null when index is out of bounds or the
+     * agent-side removal is rejected — both layers stay untouched in every null case
+     */
+    removeQueuedMessageAt(queue, index) {
+        const copy = queue === "steer" ? this._steeringMessages : this._followUpMessages;
+        if (index < 0 || index >= copy.length) {
+            return null;
+        }
+        // Remove on the agent queue first and mirror it on the session copy only
+        // after the agent accepts it. A rejected removal (stale index) leaves both
+        // layers untouched instead of widening a copy/queue mismatch.
+        if (this.agent.removeQueuedMessage(queue, index) === null) {
+            return null;
+        }
+        const [removed] = copy.splice(index, 1);
+        this._emitQueueUpdate();
+        return removed;
+    }
     /** Number of pending messages (includes both steering and follow-up) */
     get pendingMessageCount() {
         return this._steeringMessages.length + this._followUpMessages.length;
@@ -1855,7 +1953,7 @@ export class AgentSession {
      */
     async compact(customInstructions) {
         if (this._reloadInProgress) {
-            throw new Error("Session reload in progress; compaction is unavailable");
+            throw new Error(t("Session reload in progress; compaction is unavailable"));
         }
         return this._enqueueCompaction(() => this._compactInternal(customInstructions));
     }
@@ -1913,16 +2011,6 @@ export class AgentSession {
     _runAutoCompaction(reason, willRetry) {
         return runAutoCompaction(this._internal, reason, willRetry);
     }
-    /**
-     * Toggle auto-compaction setting.
-     */
-    setAutoCompactionEnabled(enabled) {
-        this.settingsManager.setCompactionEnabled(enabled);
-    }
-    /** Whether auto-compaction is enabled */
-    get autoCompactionEnabled() {
-        return this.settingsManager.getCompactionEnabled();
-    }
     /**
      * Run the session-start boundary: dispatch session.start@1 to the capability
      * runtime and run the resource discovery pass (contributed skills/prompts/
@@ -2098,7 +2186,7 @@ export class AgentSession {
                         invoke: async (input, options) => {
                             const model = this.agent.state.model;
                             if (!model)
-                                throw new Error("No model is set on this session's agent");
+                                throw new Error(t("No model is set on this session's agent"));
                             const authResult = await this._modelRuntime.getAuth(model, {
                                 ...(options?.signal === undefined ? {} : { signal: options.signal }),
                             });
@@ -2299,7 +2387,7 @@ export class AgentSession {
     }
     async reload(options) {
         if (this._reloadInProgress)
-            throw new Error("Session reload is already in progress");
+            throw new Error(t("Session reload is already in progress"));
         this._reloadInProgress = true;
         this._beginContextTransitionFence();
         this._bashEpoch += 1;
@@ -2312,7 +2400,7 @@ export class AgentSession {
             let hasContextSnapshot = false;
             if (contextStrategyName) {
                 if (!oldCapabilityRuntime?.hasContextStrategy(contextStrategyName)) {
-                    throw new Error(`Configured context strategy is not registered: ${contextStrategyName}`);
+                    throw new Error(t("Configured context strategy is not registered: {name}", { name: contextStrategyName }));
                 }
                 contextSnapshot = await oldCapabilityRuntime.snapshotContext(contextStrategyName, this._copyContextMessages(this.agent.state.messages, contextStrategyName, "input"), { reason: "reload", sessionId: this.sessionId });
                 hasContextSnapshot = true;
@@ -2361,7 +2449,9 @@ export class AgentSession {
             if (contextStrategyName && hasContextSnapshot) {
                 const runtime = this._capabilityRuntime;
                 if (!runtime?.hasContextStrategy(contextStrategyName)) {
-                    throw new Error(`Configured context strategy is not registered after reload: ${contextStrategyName}`);
+                    throw new Error(t("Configured context strategy is not registered after reload: {name}", {
+                        name: contextStrategyName,
+                    }));
                 }
                 await this._restoreContextTransition(contextSnapshot, "reload", { allowReload: true });
             }
@@ -2375,7 +2465,7 @@ export class AgentSession {
             this._reloadInProgress = false;
         }
         if (committedGeneration === undefined)
-            throw new Error("Session reload did not commit a generation");
+            throw new Error(t("Session reload did not commit a generation"));
         await this._dispatchSessionReloadLifecycle(committedGeneration);
     }
     // =========================================================================
@@ -2407,16 +2497,6 @@ export class AgentSession {
     get isRetrying() {
         return this._retryAbortController !== undefined;
     }
-    /** Whether auto-retry is enabled */
-    get autoRetryEnabled() {
-        return this.settingsManager.getRetryEnabled();
-    }
-    /**
-     * Toggle auto-retry setting.
-     */
-    setAutoRetryEnabled(enabled) {
-        this.settingsManager.setRetryEnabled(enabled);
-    }
     // =========================================================================
     // Bash Execution
     // =========================================================================