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

package/dist/core/sdk.js

@@ -9,7 +9,6 @@ import { BUILTIN_CAPABILITY_PACKAGE_IDS } from "../capabilities/builtin.js";
 import { isValidThinkingLevel } from "../cli/args.js";
 import { CONFIG_DIR_NAME, getAgentDir, VERSION } from "../config.js";
 import { profileIdentitiesCompatible } from "../profile/identity.js";
-import { ORIENTATION_PROMPTS } from "../profiles/builtin-suites.js";
 import { buildResolvedAgentProfileV1 } from "../profiles/resolved-agent-profile.js";
 import { createSuiteAssembly, decideSuiteCapabilityPlugin, filterSuiteSkills, readSessionSuiteBinding, resolveSuiteId, SUITE_ENV_VAR, SUITE_SESSION_ENTRY_TYPE, SuiteRebindError, suiteDanglingPluginAssociations, } from "../profiles/suite-loader.js";
 import { resolvePath } from "../utils/paths.js";
@@ -23,6 +22,7 @@ import { resolvePluginCapabilityOrder } from "./extensions/capability-runtime.js
 import { installProviderFailoverPlugin, readProviderFailoverSettingsNode } from "./extensions/provider-failover.js";
 import { createCodingAgentFacade } from "./facade/coding-agent-facade.js";
 import { createCodingAgentRuntimeFacade, } from "./facade/coding-agent-runtime-facade.js";
+import { t } from "./i18n/index.js";
 import { convertToLlm } from "./messages.js";
 import { findExactModelReferenceMatch, findInitialModel } from "./model-resolver.js";
 import { ModelRuntime } from "./model-runtime.js";
@@ -76,10 +76,11 @@ function parseAgentTaskSettledDigestLine(line) {
     };
 }
 /**
- * 后台委派结算行 → agent.task.settled@1 派发（第 4 期轨迹闭合）。行解析失败或
- * status 不属九值枚举时降级为仅 hostLogger warn——不阻断既有 pending 注入行为。
+ * 后台委派结算行 → agent.task.settled@1 派发（第 4 期轨迹闭合），并返回解析出的
+ * facts 供调用方复用（结算回注构造，D-060 裁决 12——同一行不再二次 parse）。行解析
+ * 失败或 status 不属九值枚举时降级为仅 hostLogger warn 并返回 undefined。
  * 会话缺席（agentSessionRef.current 在会话创建前为 undefined）或已 dispose（旧 runtime revokeState →
- * hasLifecycleEvent false → 派发助手 no-op）时安全跳过。
+ * hasLifecycleEvent false → 派发助手 no-op）时安全跳过（facts 仍返回，调用方自行守卫）。
  */
 export function deliverAgentTaskSettledDigestLine(session, line, hostLogger) {
     const facts = parseAgentTaskSettledDigestLine(line);
@@ -87,9 +88,10 @@ export function deliverAgentTaskSettledDigestLine(session, line, hostLogger) {
         hostLogger?.warn("sdk", "background delegation settlement line is not a valid agent.task.settled source", {
             cause: line,
         });
-        return;
+        return undefined;
     }
     session?.dispatchAgentTaskSettled(facts);
+    return facts;
 }
 /**
  * Plugin id of the standalone observability package (D-075 S4 second batch).
@@ -180,29 +182,16 @@ createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createEd
 function getDefaultAgentDir() {
     return getAgentDir();
 }
-/**
- * Inserts one request-time injection right after the last user message: the
- * injected context is turn-scoped, so it belongs at the head of the current
- * turn, ahead of any assistant/toolResult round already in flight. Purely a
- * request-time view — the persisted session history stays untouched. (The B1
- * memory auto-recall injection moved to the builtin memory capability plugin,
- * D-071; the background delegation digest below is the remaining consumer.)
- */
-function injectAfterLastUserMessage(messages, injection) {
-    for (let index = messages.length - 1; index >= 0; index -= 1) {
-        if (messages[index]?.role === "user") {
-            return [...messages.slice(0, index + 1), injection, ...messages.slice(index + 1)];
-        }
-    }
-    return messages;
-}
 async function readCapabilityPluginManifestForOrdering(manifestPath) {
     let raw;
     try {
         raw = JSON.parse(await readFile(manifestPath, "utf8"));
     }
     catch (error) {
-        throw new Error(`Failed to read capability plugin manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(t("Failed to read capability plugin manifest {path}: {reason}", {
+            path: manifestPath,
+            reason: error instanceof Error ? error.message : String(error),
+        }));
     }
     return parseCapabilityPluginManifest(raw, manifestPath);
 }
@@ -315,12 +304,10 @@ export async function createAgentSession(options = {}) {
         ? undefined
         : {
             drainEscalations: (sessionId) => selfMailbox().drainEscalations(sessionId),
+            // 父侧只读的兄弟流量摘录（D-060 裁决 14 父可见性）：随验收信封对父可见。
+            readSiblingTraffic: (sessionId, limit) => selfMailbox().readSiblingTraffic(sessionId, limit),
             ...(options.subagentCommunicationWiring ?? {}),
         };
-    // 后台委派结算摘要（D-060 S6）：delegate 的 background 任务结算时经 sink 落一行
-    // 有界 JSON（上限 20 条，超出丢最旧），transformContext 在父的下一次模型轮次
-    // 一次性注入并清空——完成感知不抢占父回合。
-    const backgroundDigest = { pending: [] };
     // 记忆档位解析（2.4d6 S1；D-075 S4 第四批）：SDK 显式选项最优先，settings.json
     // 档位作为 env 之下的持久来源进入解析链（显式 > env > settings > 旧别名 env >
     // off）；两者皆缺省时同样走 env/别名/off 解析（off = memory 插件包不装配）。
@@ -440,11 +427,11 @@ export async function createAgentSession(options = {}) {
     const hasConversation = branchEntries.some((entry) => entry.type === "message" && entry.message?.role === "user");
     if (hasConversation && sessionSuiteBinding !== undefined && !options.allowSuiteRebind) {
         if (sessionSuiteBinding.suiteId !== suiteId) {
-            throw new SuiteRebindError(`Session is bound to suite "${sessionSuiteBinding.suiteId}" and cannot resume with "${suiteId}"; rerun with --rebind-suite to adopt the new suite, or create a new session`);
+            throw new SuiteRebindError(t('Session is bound to suite "{boundSuiteId}" and cannot resume with "{suiteId}"; rerun with --rebind-suite to adopt the new suite, or create a new session', { boundSuiteId: sessionSuiteBinding.suiteId, suiteId }));
         }
         if (sessionSuiteBinding.profileIdentity !== undefined &&
             !profileIdentitiesCompatible(sessionSuiteBinding.profileIdentity, suiteWorkspace.identity)) {
-            throw new SuiteRebindError("Session Profile identity drift detected (the active plugin set changed since the conversation started); rerun with --rebind-suite to adopt the new plugin set, or create a new session");
+            throw new SuiteRebindError(t("Session Profile identity drift detected (the active plugin set changed since the conversation started); rerun with --rebind-suite to adopt the new plugin set, or create a new session"));
         }
     }
     const hasThinkingEntry = sessionManager.getBranch().some((entry) => entry.type === "thinking_level_change");
@@ -543,8 +530,8 @@ export async function createAgentSession(options = {}) {
     // Suite tool surface (设计 §5/§6): the resolved suite's declared tools
     // override the default allowlist when the caller passed neither tools nor
     // noTools. Both builtin suites share the same unrestricted 8-tool
-    // declaration (设计 §5: "两方案同一全集、无任何限制"), so the default
-    // assistant activates it too — the historical DEFAULT_SUITE_ID exemption
+    // declaration (设计 §5: "两方案同一全集、无任何限制"), so whichever suite
+    // is default activates it too — the historical DEFAULT_SUITE_ID exemption
     // that pinned assistant to the 4-tool base was removed in the 统一修复轮
     // (2026-09-08, per 方案设计 §5 and the user decision "不需要限制这么死").
     // capabilityMode stays a separate, orthogonal axis (设计 §5 权限段):
@@ -621,7 +608,7 @@ export async function createAgentSession(options = {}) {
                                 const session = agentSessionRef.current;
                                 // v8 ignore next -- 流式请求仅在会话初始化后发生，session 恒已赋值
                                 if (!session)
-                                    throw new Error("Capability runtime is not initialized for provider request");
+                                    throw new Error(t("Capability runtime is not initialized for provider request"));
                                 return session.getCapabilityRuntime().transformProviderHeaders({
                                     model: requestModel,
                                     ...(requestOptions?.sessionId === undefined
@@ -667,20 +654,10 @@ export async function createAgentSession(options = {}) {
         },
         sessionId: sessionManager.getSessionId(),
         transformContext: async (messages) => {
-            // 后台委派完成感知（D-060 S6）：有已结算未消费的摘要时，在下一次模型轮次
-            // 注入一块有界清单（一次性，取后即清）——不打断当前回合，也不写进持久历史。
             // （B1 记忆自动注入已迁至 builtin memory 能力插件的 transformContext 链
-            // 环节，D-071。）
-            let result = messages;
-            if (backgroundDigest.pending.length > 0) {
-                const drained = backgroundDigest.pending.splice(0);
-                result = injectAfterLastUserMessage(result, {
-                    role: "user",
-                    content: ["Background subagent tasks settled:", ...drained.map((line) => `- ${line}`)].join("\n"),
-                    timestamp: Date.now(),
-                });
-            }
-            return result;
+            // 环节，D-071；后台委派结算回注迁至 sink 侧 sendCustomMessage，D-060
+            // 裁决 12——本装配域自身不再做请求时注入。）
+            return messages;
         },
         steeringMode: settingsManager.getSteeringMode(),
         followUpMode: settingsManager.getFollowUpMode(),
@@ -719,6 +696,10 @@ export async function createAgentSession(options = {}) {
         initialActiveToolNames,
         allowedToolNames,
         excludedToolNames,
+        // 延迟工具（MCP `deferredTools: true`）：services 装配域解析出的插件 id 集
+        // 合在此过线；AgentSession 据此注册 tool_search 并把对应插件的新工具排除出
+        // 默认激活集（agent-session-tools 的默认激活分支）。
+        ...(options.deferredToolPluginIds === undefined ? {} : { deferredToolPluginIds: options.deferredToolPluginIds }),
         sessionStartEvent: options.sessionStartEvent,
         capabilityMode: options.capabilityMode,
         contextStrategyName: options.contextStrategyName,
@@ -791,12 +772,53 @@ export async function createAgentSession(options = {}) {
             : {
                 turnContext: {
                     backgroundDigestSink: (line) => {
-                        if (backgroundDigest.pending.length >= 20)
-                            backgroundDigest.pending.shift();
-                        backgroundDigest.pending.push(line);
-                        // 轨迹闭合（第 4 期）：结算行同步投递为 agent.task.settled@1（解析
-                        // 失败/非法 status 降级为 hostLogger warn；dispose 后派发助手 no-op）。
-                        deliverAgentTaskSettledDigestLine(agentSessionRef.current, line, hostLogger);
+                        try {
+                            const session = agentSessionRef.current;
+                            // 轨迹闭合（第 4 期）：结算行同步投递为 agent.task.settled@1（解析
+                            // 失败/非法 status 降级为 hostLogger warn；dispose 后派发助手 no-op），
+                            // 返回的 facts 供回注复用（同一行不二次 parse）。
+                            const facts = deliverAgentTaskSettledDigestLine(session, line, hostLogger);
+                            // 结算回注（D-060 裁决 12，用户裁决 2026-10-02）：结算即时回注主
+                            // 会话为一条 agent-task-settled custom message——主在跑经 followUp
+                            // 入队（本轮 drain、不抢占当前回合），主空闲时同一调用原子触发验
+                            // 收回合（被动机制，主不需要主动找子）。会话未建、已 dispose（同
+                            // 步置 isDisposed，读取时点无竞态）或行解析失败时跳过，不产生孤儿
+                            // 回合；手动压缩进行中由会话层降级为 followUp 入队（不穿透压缩
+                            // revision 互斥）。
+                            if (facts === undefined || session === undefined || session.isDisposed)
+                                return;
+                            const reasonSuffix = facts.reasonCode === undefined ? "" : ` (reason: ${facts.reasonCode})`;
+                            const summary = `Background subagent task ${facts.taskId} settled: ${facts.status}${reasonSuffix}.`;
+                            void session
+                                .sendCustomMessage({
+                                customType: "agent-task-settled",
+                                // 首行是用户可读摘要（TUI custom message 渲染 content 全文），
+                                // 第二行指引模型收割完整结果并验收（custom 投影为 user 消息，
+                                // content 全文模型可见）。
+                                content: `${summary}\n` +
+                                    "The settled result can be read with subagent_result (optionally waiting); read it and review the outcome before continuing.",
+                                display: true,
+                                details: {
+                                    taskId: facts.taskId,
+                                    taskSessionId: facts.taskSessionId,
+                                    status: facts.status,
+                                    ...(facts.reasonCode === undefined ? {} : { reasonCode: facts.reasonCode }),
+                                },
+                            }, { deliverAs: "followUp", triggerTurn: true })
+                                .catch((error) => {
+                                // 回注失败不影响 delegate 任务本身（终态已在调度器落库，可经
+                                // subagent_result 收割）——与结算观察器的 catch 注释同风格。
+                                hostLogger?.warn("sdk", "background delegation settlement delivery failed", {
+                                    cause: error,
+                                });
+                            });
+                        }
+                        catch (error) {
+                            // sink 是同步函数且挂在 promise 链上：守卫外异常只记日志，不外抛。
+                            hostLogger?.warn("sdk", "background delegation settlement sink failed", {
+                                cause: error,
+                            });
+                        }
                     },
                     // 回合级血缘（第 3 期第二批）：委派提交时刻捕获父回合 correlationId，
                     // 随 subagent_run metadata 过线（仅 create 新建路径消费）。
@@ -810,10 +832,12 @@ export async function createAgentSession(options = {}) {
         // （store/ledger 工厂与向量组件公共契约，缺省 = 包内默认实现）。
         ...(options.memoryCapability?.storage === undefined ? {} : { memoryStorage: options.memoryCapability.storage }),
         // Orientation persona (设计 §6.2, M2): the resolved suite's orientation
-        // text rides every system prompt rebuild on this session. Capability
-        // tool guides (memory / task management, D-071) ride the owning tools'
+        // text rides every system prompt rebuild on this session. A custom
+        // orientation's persona text comes from the workspace persona.md,
+        // already resolved by loadSuiteWorkspace (设计 §6.3). Capability tool
+        // guides (memory / task management, D-071) ride the owning tools'
         // promptGuidelines instead.
-        orientationPrompt: ORIENTATION_PROMPTS[suiteWorkspace.suite.orientation],
+        orientationPrompt: suiteWorkspace.orientationPersona,
         // Capability wiring (方案系统 M3): undefined when the assembly boundary
         // disabled wiring, so the session keeps its default (unwired) identity.
         ...(capabilitySkillsFilter === undefined ? {} : { capabilitySkillsFilter }),
@@ -823,7 +847,8 @@ export async function createAgentSession(options = {}) {
     // 插件经公共 registerStreamFnWrapper 注册面挂进上方默认 streamFn 装配（此处早于
     // 下方外部插件装载，故 failover wrapper 位于链最外层，观察到的是其余 wrapper 与
     // 默认闭包之后的最终流）。熔断状态是模块级单例，随进程生命周期跨会话共享（§4.2）。
-    // 配置从 settings `failover` 节原始读出（未配置 / enabled:false / 配置错误则不装配）；
+    // 配置从 settings `failover` 节原始读出（未配置 / 无有效候选 / 配置错误则不装配；
+    // 残留 `failover.enabled` 键已移除并警告忽略，D-079）；
     // 装配失败只警告——可靠性能力不得阻断会话构造。装载预检（§4.6）随装配同步执行：
     // 检查面全部为 modelRuntime 静态读取（目录解析/provider 存在/凭据条目快照），
     // 零网络请求、不触发 OAuth 刷新。
@@ -1080,7 +1105,7 @@ export async function createAgentSession(options = {}) {
             const manifestPath = pathByManifest.get(manifest);
             // v8 ignore next -- 顺序解析返回的 manifest 均来自同一 survivors 集合，路径恒存在
             if (!manifestPath)
-                throw new Error(`Capability plugin manifest path is unavailable: ${manifest.id}`);
+                throw new Error(t("Capability plugin manifest path is unavailable: {id}", { id: manifest.id }));
             try {
                 await session.loadCapabilityPluginManifest(manifestPath, {
                     // CLI 自动池化（承载退役切片 1，D-075 S4 第三批收敛）：宿主声明自身