@ai-agent-forge/agent-forge 0.85.0

package/dist/core/sdk.js

@@ -0,0 +1,1112 @@
+import { existsSync, realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { Agent, setDefaultStreamFn, } from "@agent-forge/agent-core";
+import { clampThinkingLevel, streamSimple } from "@agent-forge/ai/compat";
+import { createSubagentMailbox } from "@agent-forge/protocol/subagent";
+import { satisfies } from "semver";
+import { BUILTIN_CAPABILITY_PACKAGE_IDS, resolveBuiltinCapabilities } 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, suiteDanglingAssociationDiagnostic, suiteDanglingPluginAssociations, } from "../profiles/suite-loader.js";
+import { resolvePath } from "../utils/paths.js";
+import { AgentSession } from "./agent-session.js";
+import { createAgentSessionRuntime } from "./agent-session-runtime.js";
+import { listAgentSessions, readAgentSession } from "./agent-session-store.js";
+import { formatNoModelsAvailableMessage } from "./auth-guidance.js";
+import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
+import { discoverCapabilityPluginManifests, parseCapabilityPluginManifest } from "./extensions/capability-plugin.js";
+import { resolvePluginCapabilityOrder } from "./extensions/capability-runtime.js";
+import { createCodingAgentFacade } from "./facade/coding-agent-facade.js";
+import { createCodingAgentRuntimeFacade, } from "./facade/coding-agent-runtime-facade.js";
+import { convertToLlm } from "./messages.js";
+import { findExactModelReferenceMatch, findInitialModel } from "./model-resolver.js";
+import { ModelRuntime } from "./model-runtime.js";
+import { DefaultResourceLoader } from "./resource-loader.js";
+import { getDefaultSessionDir, getTraceFilePathForSession, SessionManager } from "./session-manager.js";
+import { SettingsManager } from "./settings-manager.js";
+import { time } from "./timings.js";
+import { createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createPowerShellTool, createReadOnlyTools, createReadTool, createWriteTool, withFileMutationQueue, } from "./tools/index.js";
+// Preserve the pre-0.81 fallback for extensions that construct Agent instances
+// or invoke low-level agent loops without supplying streamFn. Agent core remains
+// provider-agnostic and does not import pi-ai/compat itself.
+setDefaultStreamFn(streamSimple);
+const AGENT_TASK_SETTLED_STATUSES = new Set([
+    "queued",
+    "admitted",
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "timed_out",
+    "drain_timeout",
+    "runner_lost",
+]);
+/** Parses one settlement line; undefined for any shape outside the contract. */
+function parseAgentTaskSettledDigestLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    if (typeof record.taskId !== "string" || record.taskId === "")
+        return undefined;
+    if (typeof record.sessionId !== "string" || record.sessionId === "")
+        return undefined;
+    if (typeof record.status !== "string" || !AGENT_TASK_SETTLED_STATUSES.has(record.status))
+        return undefined;
+    if (record.reasonCode !== undefined && (typeof record.reasonCode !== "string" || record.reasonCode === "")) {
+        return undefined;
+    }
+    return {
+        taskId: record.taskId,
+        // 行内 sessionId 是子会话 id（复审 M1）：映射为事件 data 的 taskSessionId。
+        taskSessionId: record.sessionId,
+        status: record.status,
+        ...(record.reasonCode === undefined ? {} : { reasonCode: record.reasonCode }),
+    };
+}
+/**
+ * 后台委派结算行 → agent.task.settled@1 派发（第 4 期轨迹闭合）。行解析失败或
+ * status 不属九值枚举时降级为仅 hostLogger warn——不阻断既有 pending 注入行为。
+ * 会话缺席（agentSessionRef.current 在会话创建前为 undefined）或已 dispose（旧 runtime revokeState →
+ * hasLifecycleEvent false → 派发助手 no-op）时安全跳过。
+ */
+export function deliverAgentTaskSettledDigestLine(session, line, hostLogger) {
+    const facts = parseAgentTaskSettledDigestLine(line);
+    if (facts === undefined) {
+        hostLogger?.warn("sdk", "background delegation settlement line is not a valid agent.task.settled source", {
+            cause: line,
+        });
+        return;
+    }
+    session?.dispatchAgentTaskSettled(facts);
+}
+/**
+ * Plugin id of the standalone observability package (D-075 S4 second batch).
+ * When `traceEnabled` is not `false`, the assembler adds it to the installed
+ * plugin membership set so the installed package joins the session through
+ * the same loading path as every other plugin package.
+ */
+const OBSERVABILITY_PACKAGE_ID = "agent-forge.plugin.observability";
+/**
+ * Plugin id of the standalone subagent-delegate package (D-075 S4 third
+ * batch). When `subagentPoolFromSelfInvocation` is true (the real CLI
+ * assembly declaring its own process entry trustworthy), the assembler
+ * overrides the plugin's manifest config with `runnerEntryAuto: true` at load
+ * — the config key the package's auto-pooling path consumes (the former host
+ * `selfInvocationPool` option is retired). The agent-dir config file still
+ * merges over it inside the plugin entry, so users keep the final say.
+ */
+const SUBAGENT_DELEGATE_PACKAGE_ID = "agent-forge.plugin.subagent-delegate";
+/**
+ * Plugin id of the standalone memory package (D-075 S4 fourth batch). When the
+ * suite declares `builtin.memory` and the resolved memory mode is light/full,
+ * the assembler adds the package to the installed-plugin membership set and
+ * overrides its manifest config with `memoryMode`/`memorySettingsMode` at load
+ * — the config keys the package's entry resolves with the exact precedence
+ * the embedded capability used to have (explicit host option → env →
+ * settings.json → legacy alias → off). Mode off keeps the package out of the
+ * membership set entirely (禁用 = 不装配, plus one startup diagnostic).
+ */
+const MEMORY_PACKAGE_ID = "agent-forge.plugin.memory";
+const isMemoryModeV1 = (value) => value === "off" || value === "light" || value === "full";
+function resolveSdkMemoryMode(explicitMode, env, settingsMode) {
+    if (explicitMode !== undefined) {
+        if (isMemoryModeV1(explicitMode))
+            return { mode: explicitMode };
+        return { mode: "off", invalidEnvValue: explicitMode };
+    }
+    const configured = env.AGENT_FORGE_MEMORY_MODE?.trim().toLowerCase();
+    if (configured !== undefined && configured !== "") {
+        if (isMemoryModeV1(configured))
+            return { mode: configured };
+        return { mode: "off", invalidEnvValue: configured };
+    }
+    const fromSettings = settingsMode?.trim().toLowerCase();
+    if (fromSettings !== undefined && fromSettings !== "") {
+        if (isMemoryModeV1(fromSettings))
+            return { mode: fromSettings };
+        return { mode: "off", invalidSettingsValue: fromSettings };
+    }
+    const legacy = env.AGENT_FORGE_MEMORY_VECTOR?.trim().toLowerCase();
+    if (legacy !== undefined && legacy !== "") {
+        if (isMemoryModeV1(legacy))
+            return { mode: legacy };
+        return { mode: "off", invalidEnvValue: legacy };
+    }
+    return { mode: "off" };
+}
+/**
+ * 子代理 headless 交互宿主（D-044 §5.5）：child 会话无宿主 UI，interaction 请求
+ * 落回冻结 InteractionOutcomeV1 语义——prompt 返回 "unavailable"（宿主无 UI），
+ * signal 已中止返回 "cancelled"；notify 为 fire-and-forget 空操作（语义 delivered）。
+ */
+export const HEADLESS_INTERACTION_HOST = {
+    notify: () => { },
+    prompt: async (_request, context) => {
+        if (context.signal.aborted)
+            return { status: "cancelled" };
+        return { status: "unavailable" };
+    },
+};
+// Re-exports
+export * from "./agent-session-runtime.js";
+export { withFileMutationQueue, 
+// Tool factories (for custom cwd)
+createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, createPowerShellTool, };
+// Helper Functions
+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)}`);
+    }
+    return parseCapabilityPluginManifest(raw, manifestPath);
+}
+/**
+ * Create an AgentSession with the specified options.
+ *
+ * @example
+ * ```typescript
+ * // Minimal - uses defaults
+ * const { session } = await createAgentSession();
+ *
+ * // With explicit model
+ * import { getModel } from '@agent-forge/ai';
+ * const { session } = await createAgentSession({
+ *   model: getModel('anthropic', 'claude-opus-4-5'),
+ *   thinkingLevel: 'high',
+ * });
+ *
+ * // Continue previous session
+ * const { session, modelFallbackMessage } = await createAgentSession({
+ *   continueSession: true,
+ * });
+ *
+ * // Full control
+ * const loader = new DefaultResourceLoader({
+ *   cwd: process.cwd(),
+ *   agentDir: getAgentDir(),
+ *   settingsManager: SettingsManager.create(),
+ * });
+ * await loader.reload();
+ * const { session } = await createAgentSession({
+ *   model: myModel,
+ *   tools: ["read", "bash"],
+ *   resourceLoader: loader,
+ *   sessionManager: SessionManager.inMemory(),
+ * });
+ * ```
+ */
+export async function createAgentSession(options = {}) {
+    const cwd = resolvePath(options.cwd ?? options.sessionManager?.getCwd() ?? process.cwd());
+    const agentDir = options.agentDir ? resolvePath(options.agentDir) : getDefaultAgentDir();
+    let resourceLoader = options.resourceLoader;
+    const authPath = options.agentDir ? join(agentDir, "auth.json") : undefined;
+    const modelsPath = options.agentDir ? join(agentDir, "models.json") : undefined;
+    const modelRuntime = options.modelRuntime ?? (await ModelRuntime.create({ authPath, modelsPath, credentials: options.credentials }));
+    const settingsManager = options.settingsManager ?? SettingsManager.create(cwd, agentDir);
+    // Suite assembly (方案系统 M1a/M2): resolve the active suite and build the
+    // shared assembly (workspace + loader overrides + diagnostics channel).
+    // The inherit switch also gates the global agentDir SYSTEM.md/
+    // APPEND_SYSTEM.md prompt channel (设计 §8: it governs the whole system
+    // layer). Unknown ids fail here with a structured error listing the
+    // available suites. The loader overrides below are applied only when this
+    // call builds its own DefaultResourceLoader; callers that bring their own
+    // resourceLoader keep the M1a bypass boundary (unchanged).
+    const suiteId = resolveSuiteId({
+        explicit: options.suite,
+        envSuite: process.env[SUITE_ENV_VAR],
+        settings: settingsManager,
+        agentDir,
+    });
+    const suiteAssembly = createSuiteAssembly({
+        cwd,
+        agentDir,
+        suiteId,
+        pluginProfileId: options.pluginProfileId,
+        selectedPluginIds: options.selectedPluginIds,
+        disabledPluginIds: options.disabledPluginIds,
+        pluginHost: options.pluginHost,
+        verifiedPlugins: options.verifiedPlugins,
+        manifestOverrides: options.manifestOverrides,
+        pluginProfile: options.pluginProfile,
+    });
+    const suiteWorkspace = suiteAssembly.workspace;
+    // ResolvedAgentProfile (D-047 S4a): one deep-frozen aggregate view over the
+    // resolved suite per session, built once at the existing single resolution
+    // point right after suite assembly. Pure projection of the authoritative
+    // sources above (identity, lock verification, plugin profile, workspace
+    // paths) — no new generation mechanism; AgentSession stays suite-unaware.
+    const resolvedAgentProfile = buildResolvedAgentProfileV1({
+        suiteId,
+        workspace: suiteWorkspace,
+        ...(suiteAssembly.pluginProfile === undefined ? {} : { pluginProfile: suiteAssembly.pluginProfile }),
+    });
+    // Capability wiring (方案系统 M3): resolve the suite's `capabilities`
+    // short ids onto the builtin family mapping (every short id assembles from
+    // its independent plugin package; unknown ids surface as dangling
+    // diagnostics, never as errors — 决策记录 §8) and prepare the external
+    // pool / legacy skill association filters. Follows the M1a/M1b assembly
+    // boundary: wiring is on when this call builds its own loader and off for
+    // callers that bring one unless they opt in explicitly.
+    const capabilityWiring = options.suiteCapabilityWiring ?? !options.resourceLoader;
+    const capabilityDiagnostics = [];
+    // Suite preference diagnostics (统一修复轮 B): unresolvable suite.model /
+    // suite.thinking declarations surface here instead of failing startup.
+    const suitePreferenceDiagnostics = [];
+    let capabilitySkillsFilter;
+    // 子代理通信面（D-060 S4/S5）：每个装配域自持**一个**信箱（本会话的子代理们向它
+    // post escalation/兄弟消息，本会话的 delegate drain）。嵌套委派时，子装配域的信箱
+    // 由父侧 creator 构造并经 `subagentMailbox` 注入，保证 post 目标与 drain 来源同一
+    // 实例；post-up（向自己的父）接线经 `subagentCommunicationWiring` 注入，两者合并。
+    let communicationMailbox;
+    const selfMailbox = () => {
+        communicationMailbox ??= createSubagentMailbox({
+            agentDir,
+            ownerParentSessionId: () => agentSessionRef.current?.sessionId,
+        });
+        return communicationMailbox;
+    };
+    const communicationWiring = options.enableAgentTasks === false && options.subagentCommunicationWiring === undefined
+        ? undefined
+        : {
+            drainEscalations: (sessionId) => selfMailbox().drainEscalations(sessionId),
+            ...(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 插件包不装配）。
+    // 门控诊断与成员资格判定在下方 capabilityWiring 块产出。
+    const settingsMemoryMode = settingsManager.getMemoryModeSetting();
+    const memoryModeOption = options.memoryCapability?.mode;
+    const memoryModeResolution = resolveSdkMemoryMode(memoryModeOption, process.env, settingsMemoryMode);
+    if (capabilityWiring) {
+        const resolved = resolveBuiltinCapabilities(suiteWorkspace.suite.capabilities);
+        for (const shortId of resolved.unknownShortIds) {
+            capabilityDiagnostics.push(suiteDanglingAssociationDiagnostic(suiteId, "capabilities", shortId));
+        }
+        // 记忆全局门控诊断（2.4d6 S1, D-075 S4 第四批自 builtin 通道迁入）：套件确实
+        // 声明了 builtin.memory 时才输出（抑制发生了才声明；未声明的场合由白名单语
+        // 义覆盖，不加噪音）。文案由 builtin 时代逐字迁移（memory-mode-gating 等 pin）。
+        if (suiteWorkspace.suite.capabilities.includes("builtin.memory")) {
+            if (memoryModeResolution.invalidEnvValue !== undefined) {
+                capabilityDiagnostics.push(`invalid AGENT_FORGE_MEMORY_MODE value "${memoryModeResolution.invalidEnvValue}"; memory stays off (fail-closed)`);
+            }
+            if (memoryModeResolution.invalidSettingsValue !== undefined) {
+                capabilityDiagnostics.push(`invalid memory.mode setting "${memoryModeResolution.invalidSettingsValue}"; memory stays off (fail-closed)`);
+            }
+            if (memoryModeResolution.mode === "off") {
+                capabilityDiagnostics.push("memory disabled (mode=off) — set memory.mode (light|full) in settings.json to enable");
+            }
+        }
+        // Legacy plugin skill face: the bootstrap-skills contribution face is
+        // already filtered loader-side (M1b); only runtime.listSkills() entries
+        // pass through this hook. Association dangling is reported by the
+        // loader-side skills filter; this hook only narrows the plugin face.
+        // The suite-local skill layer (统一修复轮 B) passes by path there.
+        const suiteDefinition = suiteWorkspace.suite;
+        const suiteLocalSkillsDir = suiteAssembly.localSkillsDir;
+        capabilitySkillsFilter = (skills) => filterSuiteSkills(suiteDefinition, skills, { localSkillsDir: suiteLocalSkillsDir }).kept;
+    }
+    const sessionManager = options.sessionManager ?? SessionManager.create(cwd, getDefaultSessionDir(cwd, agentDir));
+    // 打点通道（设计 §5.2）：streamFn 闭包的 options 参数会遮蔽装配 options，统一
+    // 捕获为局部常量；未注入时全部打点为 no-op。
+    const hostLogger = options.hostLogger;
+    // 轨迹快照预算（设计 §6 控制面，第 2 期外露）：随 trace 服务注入安装店
+    // observability 插件；缺省 = 插件内默认（16000 字符/串、384KiB/快照）。
+    const traceOptions = options.traceOptions;
+    // 轨迹收集默认装配（设计 §4.4/§6，D-065；S4 拆包改造，D-075 第二批）：
+    // `traceEnabled` 缺省开启时，安装店 `agent-forge.plugin.observability` 包
+    // 随装配链加载（成员资格并入 installed 插件集合，可经 disabledPluginIds
+    // 显式禁用；第三方可经同一公共 lifecycle 订阅面替换）。宿主适配器闭包只
+    // 依赖装配域内既有事实：会话文件路径（惰性解析，经既有 getSessionFile()
+    // 读面加 §4.1 配对纯函数）、进程日志（options.hostLogger，未注入为 no-op）、
+    // payload 捕获（onPayload 读取；无隐藏全局）。适配器经新 `api.trace` 服务
+    // 面注入插件；插件 entry 经适配器可选 `registerFacade` 通道把门面写回
+    // 下方三个装配域 ref（payload 捕获 / plugin.log 镜像 / /metrics 数据源），
+    // dispose 时置空——与内嵌工厂时代的 ref 语义逐点一致。
+    const observabilityCapture = {};
+    // 插件日志镜像共享 ref（会话轨迹 plugin.log，设计 §7.2）：插件门面
+    // mirrorPluginLog 注册时写入，dispose 时置空；AgentSession 的 runtime
+    // 日志 sink 经 AgentSessionConfig.logRecordMirrorRef 读它。
+    const observabilityLogMirror = {};
+    // /metrics 命令的数据源（observability 门面直通）：插件门面 getMetrics
+    // 注册时写入，dispose 时置空；宿主（TUI/RPC）在装配完成后读取并接进命令
+    // options。
+    const observabilityGetMetrics = {};
+    let traceService;
+    if (options.traceEnabled !== false) {
+        const adapter = {
+            getTraceFilePath: () => {
+                const sessionFilePath = sessionManager.getSessionFile();
+                return sessionFilePath === undefined ? null : getTraceFilePathForSession(sessionFilePath);
+            },
+            captureProviderPayload: (payload, model) => {
+                observabilityCapture.current?.(payload, model);
+            },
+            onSinkFailure: (error) => {
+                hostLogger?.error("observability", "trace sink failure", { cause: error });
+            },
+            getTurnCorrelationId: () => agentSessionRef.current?.getTurnCorrelationId(),
+            getParentAgentSessionId: () => sessionManager.getHeader()?.parentAgentSession,
+            getParentTraceId: () => sessionManager.getHeader()?.parentTraceId,
+            registerFacade: (facade) => {
+                observabilityCapture.current = facade?.captureProviderPayload;
+                observabilityLogMirror.current = facade?.mirrorPluginLog;
+                observabilityGetMetrics.current = facade?.getMetrics;
+            },
+        };
+        traceService = { adapter, ...(traceOptions === undefined ? {} : { options: traceOptions }) };
+    }
+    if (!resourceLoader) {
+        // Suite association filtering (方案系统 M1b, 设计 §3/§4): the default
+        // loader's skills are filtered down to the suite's
+        // associations here, at the assembler layer; project-scope entries
+        // (cwd/.agent-forge) always pass. Dangling associations surface through
+        // suiteDiagnostics, never as errors.
+        resourceLoader = new DefaultResourceLoader({
+            cwd,
+            agentDir,
+            settingsManager,
+            ...suiteAssembly.loaderOverrides,
+            // Suite-local skill layer (统一修复轮 B): <suiteDir>/skills rides the
+            // loader's skill paths when the suite is active. The filterSuiteSkills
+            // suite-local exemption keeps these entries; user-level and other
+            // unassociated layers stay filtered. Undefined (absent directory)
+            // injects nothing, so empty and missing directories are both silent.
+            ...(suiteAssembly.localSkillsDir === undefined
+                ? {}
+                : { additionalSkillPaths: [suiteAssembly.localSkillsDir] }),
+        });
+        await resourceLoader.reload();
+        time("resourceLoader.reload");
+    }
+    // Check if session has existing data to restore
+    const existingSession = sessionManager.buildSessionContext();
+    const hasExistingSession = existingSession.messages.length > 0;
+    const branchEntries = sessionManager.getBranch();
+    const sessionSuiteBinding = readSessionSuiteBinding(branchEntries);
+    // 绑定护栏保护的是有对话上下文的会话：会话创建先于插件装载，装载失败（profile
+    // drift 等）会留下只有初始化 entry 与绑定的残留——这些 message entries 会让
+    // hasExistingSession 为真，若按它门控，用户用同一 session id 重试会永远撞墙
+    // （dogfood 2026-09-25 实测）。真实用户输入（user entry）才算对话开始。
+    const hasConversation = branchEntries.some((entry) => entry.type === "message" && entry.message?.role === "user");
+    if (hasConversation && sessionSuiteBinding !== undefined) {
+        if (sessionSuiteBinding.suiteId !== suiteId) {
+            throw new SuiteRebindError(`Session is bound to suite "${sessionSuiteBinding.suiteId}" and cannot resume with "${suiteId}"; create a new session or migrate explicitly`);
+        }
+        if (sessionSuiteBinding.profileIdentity !== undefined &&
+            !profileIdentitiesCompatible(sessionSuiteBinding.profileIdentity, suiteWorkspace.identity)) {
+            throw new SuiteRebindError("Session Profile identity drift detected; create a new session or migrate explicitly before reloading plugins");
+        }
+    }
+    const hasThinkingEntry = sessionManager.getBranch().some((entry) => entry.type === "thinking_level_change");
+    let model = options.model;
+    let modelFallbackMessage;
+    // If session has data, try to restore model from it
+    if (!model && hasExistingSession && existingSession.model) {
+        const restoredModel = modelRuntime.getModel(existingSession.model.provider, existingSession.model.modelId);
+        if (restoredModel && modelRuntime.hasConfiguredAuth(restoredModel.provider)) {
+            model = restoredModel;
+        }
+        if (!model) {
+            modelFallbackMessage = `Could not restore model ${existingSession.model.provider}/${existingSession.model.modelId}`;
+        }
+    }
+    // Suite model preference (统一修复轮 B): sits below the CLI/explicit option
+    // and the restored session model, above the settings default that
+    // findInitialModel resolves below. A suite model that matches no
+    // authenticated model falls through to the next tier with a diagnostic —
+    // never a failure (设计 §9: suite content never blocks startup). Factory
+    // builtin suites declare null, so their resolution is unchanged.
+    const suiteModelPreference = suiteWorkspace.suite.model;
+    if (!model && suiteModelPreference !== null) {
+        const suiteModel = findExactModelReferenceMatch(suiteModelPreference, [...modelRuntime.getModels()]);
+        if (suiteModel && modelRuntime.hasConfiguredAuth(suiteModel.provider)) {
+            model = suiteModel;
+        }
+        else {
+            suitePreferenceDiagnostics.push(`Suite "${suiteId}" model "${suiteModelPreference}" does not resolve to an authenticated model; using the normal model resolution instead.`);
+        }
+    }
+    // If still no model, use findInitialModel (checks settings default, then provider defaults)
+    if (!model) {
+        const result = await findInitialModel({
+            scopedModels: [],
+            isContinuing: hasExistingSession,
+            defaultProvider: settingsManager.getDefaultProvider(),
+            defaultModelId: settingsManager.getDefaultModel(),
+            defaultThinkingLevel: settingsManager.getDefaultThinkingLevel(),
+            modelThinkingLevels: settingsManager.getAllModelThinkingLevels(),
+            modelRuntime,
+        });
+        model = result.model;
+        if (!model) {
+            modelFallbackMessage = formatNoModelsAvailableMessage();
+        }
+        else if (modelFallbackMessage) {
+            modelFallbackMessage += `. Using ${model.provider}/${model.id}`;
+        }
+    }
+    let thinkingLevel = options.thinkingLevel;
+    // If session has data, restore thinking level from it
+    if (thinkingLevel === undefined && hasExistingSession && hasThinkingEntry) {
+        thinkingLevel = existingSession.thinkingLevel;
+    }
+    // Suite thinking preference (统一修复轮 B): below the session's persisted
+    // thinking entry, above the settings-derived tiers. An invalid value falls
+    // through with a diagnostic; factory builtin suites declare null, so their
+    // resolution is unchanged.
+    const suiteThinkingPreference = suiteWorkspace.suite.thinking;
+    if (thinkingLevel === undefined && suiteThinkingPreference !== null) {
+        if (isValidThinkingLevel(suiteThinkingPreference)) {
+            thinkingLevel = suiteThinkingPreference;
+        }
+        else {
+            suitePreferenceDiagnostics.push(`Suite "${suiteId}" thinking "${suiteThinkingPreference}" is not a valid thinking level; using the normal thinking resolution instead.`);
+        }
+    }
+    // If session has data without a persisted thinking entry, the settings
+    // default applies (same tier as before the suite preference was inserted).
+    if (thinkingLevel === undefined && hasExistingSession) {
+        thinkingLevel = settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
+    }
+    // Fall back to per-model override, then global default
+    if (thinkingLevel === undefined && model) {
+        const perModel = settingsManager.getModelThinkingLevel(model.provider, model.id);
+        if (perModel) {
+            thinkingLevel = perModel;
+        }
+    }
+    if (thinkingLevel === undefined) {
+        thinkingLevel = settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
+    }
+    // Clamp to model capabilities
+    if (!model) {
+        thinkingLevel = "off";
+    }
+    else {
+        thinkingLevel = clampThinkingLevel(model, thinkingLevel);
+    }
+    const defaultActiveToolNames = options.capabilityMode === "readonly" ? ["read", "grep", "find", "ls"] : ["read", "bash", "edit", "write"];
+    const configuredDefaultToolNames = settingsManager.getDefaultTools();
+    const allowedToolNames = options.tools ?? (options.noTools === "all" ? [] : undefined);
+    const excludedToolNames = options.excludeTools;
+    const excludedToolNameSet = excludedToolNames ? new Set(excludedToolNames) : undefined;
+    // 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
+    // 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 权限段):
+    // readonly narrows BOTH suites' faces a second time, so the suite
+    // declaration never defeats the readonly base face.
+    const suiteToolOverride = options.tools === undefined && options.noTools === undefined && options.capabilityMode !== "readonly"
+        ? [...suiteWorkspace.suite.tools]
+        : undefined;
+    const initialActiveToolNames = (suiteToolOverride ??
+        options.tools ??
+        (options.noTools ? [] : (configuredDefaultToolNames ?? defaultActiveToolNames))).filter((name) => !excludedToolNameSet?.has(name));
+    let agent;
+    // Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)
+    const convertToLlmWithBlockImages = (messages) => {
+        const converted = convertToLlm(messages);
+        // Check setting dynamically so mid-session changes take effect
+        if (!settingsManager.getBlockImages()) {
+            return converted;
+        }
+        // Filter out ImageContent from all messages, replacing with text placeholder
+        return converted.map((msg) => {
+            if (msg.role === "user" || msg.role === "toolResult") {
+                const content = msg.content;
+                if (Array.isArray(content)) {
+                    const hasImages = content.some((c) => c.type === "image");
+                    if (hasImages) {
+                        const filteredContent = content
+                            .map((c) => c.type === "image" ? { type: "text", text: "Image reading is disabled." } : c)
+                            .filter((c, i, arr) => 
+                        // Dedupe consecutive "Image reading is disabled." texts
+                        !(c.type === "text" &&
+                            c.text === "Image reading is disabled." &&
+                            i > 0 &&
+                            arr[i - 1].type === "text" &&
+                            arr[i - 1].text === "Image reading is disabled."));
+                        return { ...msg, content: filteredContent };
+                    }
+                }
+            }
+            return msg;
+        });
+    };
+    const agentSessionRef = {};
+    const customStreamFn = options.streamFn;
+    agent = new Agent({
+        initialState: {
+            systemPrompt: "",
+            model,
+            thinkingLevel,
+            tools: [],
+        },
+        convertToLlm: convertToLlmWithBlockImages,
+        streamFn: customStreamFn
+            ? (model, context, streamOptions) => customStreamFn(model, context, streamOptions)
+            : async (model, context, options) => {
+                const providerRetrySettings = settingsManager.getProviderRetrySettings();
+                const httpIdleTimeoutMs = settingsManager.getHttpIdleTimeoutMs();
+                // SDKs treat timeout=0 as 0ms (immediate timeout), not "no timeout".
+                // Use max int32 to effectively disable the timeout.
+                const effectiveTimeoutMs = httpIdleTimeoutMs === 0 ? 2147483647 : httpIdleTimeoutMs;
+                const timeoutMs = options?.timeoutMs ?? providerRetrySettings.timeoutMs ?? effectiveTimeoutMs;
+                const websocketConnectTimeoutMs = options?.websocketConnectTimeoutMs ?? settingsManager.getWebSocketConnectTimeoutMs();
+                try {
+                    return modelRuntime.streamSimple(model, context, {
+                        ...options,
+                        timeoutMs,
+                        websocketConnectTimeoutMs,
+                        maxRetries: options?.maxRetries ?? providerRetrySettings.maxRetries,
+                        maxRetryDelayMs: options?.maxRetryDelayMs ?? providerRetrySettings.maxRetryDelayMs,
+                        transformHeaders: async (requestHeaders) => {
+                            const session = agentSessionRef.current;
+                            // v8 ignore next -- 流式请求仅在会话初始化后发生，session 恒已赋值
+                            if (!session)
+                                throw new Error("Capability runtime is not initialized for provider request");
+                            return session.getCapabilityRuntime().transformProviderHeaders({
+                                model,
+                                ...(options?.sessionId === undefined ? {} : { sessionId: options.sessionId }),
+                                headers: requestHeaders,
+                            });
+                        },
+                    });
+                }
+                catch (error) {
+                    // streamFn 错误路径打点（设计 §5.2）：保留原始错误向上传播。
+                    hostLogger?.error("sdk", "provider stream failed", { cause: error });
+                    throw error;
+                }
+            },
+        onPayload: async (payload, model) => {
+            // 轨迹快照（设计 §4.2 llm.request）：最终 payload 转发给装配域收集器；
+            // 转发自身失败只记日志，绝不影响请求。
+            try {
+                traceService?.adapter.captureProviderPayload(payload, model?.id);
+            }
+            catch (error) {
+                hostLogger?.warn("sdk", "trace payload capture failed", { cause: error });
+            }
+        },
+        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;
+        },
+        steeringMode: settingsManager.getSteeringMode(),
+        followUpMode: settingsManager.getFollowUpMode(),
+        transport: settingsManager.getTransport(),
+        thinkingBudgets: settingsManager.getThinkingBudgets(),
+        maxRetryDelayMs: settingsManager.getProviderRetrySettings().maxRetryDelayMs,
+    });
+    // Restore messages if session has existing data
+    if (hasExistingSession) {
+        agent.state.messages = existingSession.messages;
+        if (!hasThinkingEntry) {
+            sessionManager.appendThinkingLevelChange(thinkingLevel);
+        }
+    }
+    else {
+        // Save initial model and thinking level for new sessions so they can be restored on resume
+        if (model) {
+            sessionManager.appendModelChange(model.provider, model.id);
+        }
+        sessionManager.appendThinkingLevelChange(thinkingLevel);
+    }
+    // Assistant preference card (统一修复轮 A 交付3, H2 接线) migrated into the
+    // memory plugin package with the S4 fourth batch: the plugin's
+    // transformContext loop hook reads the ledger-backed card and injects it on
+    // assistant-oriented sessions itself. The sdk no longer loads or injects
+    // the card.
+    const session = new AgentSession({
+        agent,
+        sessionManager,
+        settingsManager,
+        cwd,
+        scopedModels: options.scopedModels,
+        resourceLoader,
+        customTools: options.customTools,
+        modelRuntime,
+        initialActiveToolNames,
+        allowedToolNames,
+        excludedToolNames,
+        sessionStartEvent: options.sessionStartEvent,
+        capabilityMode: options.capabilityMode,
+        contextStrategyName: options.contextStrategyName,
+        retryPolicyName: options.retryPolicyName,
+        compactionPolicyName: options.compactionPolicyName,
+        overflowPolicyName: options.overflowPolicyName,
+        branchSummaryPolicyName: options.branchSummaryPolicyName,
+        runLoopStrategyName: options.runLoopStrategyName,
+        // 承载退役切片 2：装配域无默认 creator——委派承载 = 宿主 adapter 或 CLI 自动池化。
+        agentTaskAdapter: options.enableAgentTasks === false ? undefined : options.agentTaskAdapter,
+        ...(options.agentTaskResults === undefined ? {} : { agentTaskResults: options.agentTaskResults }),
+        // 会话回读（D-060 S3）：按 sessionId 读子会话 transcript，作用域在**宿主侧**强制——
+        // 只放行本会话自己的子会话（文件头 parentAgentSession 必须等于本会话 id），
+        // 越界与不存在同型返回 undefined。
+        ...(options.enableAgentTasks === false
+            ? {}
+            : {
+                agentSessionReader: async (sessionId) => {
+                    const parentSession = agentSessionRef.current;
+                    if (parentSession === undefined)
+                        return undefined;
+                    const read = readAgentSession({ agentDir, sessionId });
+                    if (read === undefined || read.parentAgentSession !== parentSession.sessionId)
+                        return undefined;
+                    return {
+                        sessionId: read.sessionId,
+                        ...(read.parentAgentSession === undefined ? {} : { parentAgentSession: read.parentAgentSession }),
+                        ...(read.agentRole === undefined ? {} : { agentRole: read.agentRole }),
+                        ...(read.createdAt === undefined ? {} : { createdAt: read.createdAt }),
+                        bytes: read.bytes,
+                        entryCount: read.entryCount,
+                        truncated: read.truncated,
+                        entries: read.entries,
+                    };
+                },
+                // 子会话盘点（D-060 模型面）：只列本会话自己的子会话摘要（store 默认
+                // 最近活动倒序、上限 200），读落盘目录，跨进程重启仍可列出。
+                agentSessionLister: async () => {
+                    const parentSession = agentSessionRef.current;
+                    if (parentSession === undefined)
+                        return [];
+                    return listAgentSessions({ agentDir, parentAgentSession: parentSession.sessionId }).map((summary) => ({
+                        sessionId: summary.sessionId,
+                        ...(summary.agentRole === undefined ? {} : { agentRole: summary.agentRole }),
+                        ...(summary.createdAt === undefined ? {} : { createdAt: summary.createdAt }),
+                        modifiedAt: summary.modifiedAt,
+                        bytes: summary.bytes,
+                    }));
+                },
+            }),
+        agentComposition: options.agentComposition,
+        interactionHost: options.interactionHost,
+        // 打点通道下沉（设计 §5.2/§7.2）：会话级进程日志打点（插件日志镜像、内建
+        // 装载失败等）与 plugin.log 轨迹镜像共享 ref（插件门面注册时写入，空 = 无
+        // 镜像）。
+        hostLogger: options.hostLogger,
+        logRecordMirrorRef: observabilityLogMirror,
+        observabilityGetMetricsRef: observabilityGetMetrics,
+        // D-075 S4 第二批：宿主 agentDir 上公共 HostCapabilities（磁盘状态插件的
+        // 配置通道），trace 服务随 traceEnabled 注入 installed observability 包。
+        agentDir,
+        // D-075 S4 第三批：subagent-delegate 宿主服务上公共 HostCapabilities——
+        // communication（父侧 drain + 注入的叶子 post 接线合并）、turnContext
+        // （后台结算摘要 sink + 回合 correlationId 捕获）、roleAssociations（当前
+        // 方案关联角色；角色定义只在磁盘 <agentDir>/roles/，无编译内定义）。
+        // 原内嵌 builtin 构造选项链退役；独立插件包 entry 从 api.host 组装同一形状。
+        ...(communicationWiring === undefined ? {} : { communication: communicationWiring }),
+        ...(options.enableAgentTasks === false
+            ? {}
+            : {
+                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);
+                    },
+                    // 回合级血缘（第 3 期第二批）：委派提交时刻捕获父回合 correlationId，
+                    // 随 subagent_run metadata 过线（仅 create 新建路径消费）。
+                    getTurnCorrelationId: () => agentSessionRef.current?.getTurnCorrelationId(),
+                },
+            }),
+        ...(options.enableAgentTasks === false ? {} : { roleAssociations: suiteWorkspace.suite.associations.roles }),
+        ...(traceService === undefined ? {} : { traceService }),
+        // D-075 S4 第四批：记忆底层组件注入上公共 HostCapabilities——
+        // `api.host.memoryStorage`，安装店的 memory 插件包 entry 组装消费
+        // （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'
+        // promptGuidelines instead.
+        orientationPrompt: ORIENTATION_PROMPTS[suiteWorkspace.suite.orientation],
+        // Capability wiring (方案系统 M3): undefined when the assembly boundary
+        // disabled wiring, so the session keeps its default (unwired) identity.
+        ...(capabilitySkillsFilter === undefined ? {} : { capabilitySkillsFilter }),
+    });
+    agentSessionRef.current = session;
+    // Session-suite binding (设计 §10.1): record the suite as session protocol
+    // data via the existing custom-entry extension point. New sessions only;
+    // resumed sessions keep their original binding.
+    // 新会话写入绑定；失败残留（有绑定但无对话）恢复时重写为当前装配——
+    // readSessionSuiteBinding 取 latest，之后的绑定检查语义与实际装配一致。
+    // 有对话的既有会话保持原绑定（护栏语义）。
+    if (!hasExistingSession || (sessionSuiteBinding !== undefined && !hasConversation)) {
+        session.sessionManager.appendCustomEntry(SUITE_SESSION_ENTRY_TYPE, {
+            suiteId,
+            profileIdentity: suiteWorkspace.identity,
+        });
+    }
+    const pluginRejections = [];
+    const recordRejection = async (code, manifestPath, pluginId, message) => {
+        const rejection = Object.freeze({
+            code,
+            manifestPath,
+            ...(pluginId === undefined ? {} : { pluginId }),
+            message,
+        });
+        pluginRejections.push(rejection);
+        // 插件装载失败打点（设计 §5.2）：结构化 rejection 之外的进程日志一行，
+        // 让轨迹中断时可以凭日志定位。
+        hostLogger?.error("sdk", `capability plugin rejected: ${message}`, {
+            sessionId: session.sessionId,
+            fields: { code: rejection.code, pluginId: rejection.pluginId, manifestPath: rejection.manifestPath },
+        });
+        try {
+            await session.getCapabilityRuntime().recordPluginRejection(rejection);
+        }
+        catch {
+            // Rejection visibility must never fail the remaining startup path.
+        }
+    };
+    const rejectionMessage = (error) => (error instanceof Error ? error.message : String(error));
+    try {
+        const discoveredManifestPaths = options.discoverCapabilityPlugins === false
+            ? []
+            : discoverCapabilityPluginManifests([join(agentDir, "plugins"), join(cwd, CONFIG_DIR_NAME, "plugins")]);
+        // Suite-local plugin layer (统一修复轮 B): manifests below
+        // <suiteDir>/plugins load when the suite is active and the capability
+        // surface is wired; suite activation is their association, so they bypass
+        // associations.plugins filtering like explicit caller paths and win
+        // duplicate-id resolution over the pools. The discovery switch gates them
+        // too, so callers that disable plugin discovery (child sessions) keep
+        // today's plugin-free face.
+        const suiteLocalManifestPaths = capabilityWiring && options.discoverCapabilityPlugins !== false && suiteAssembly.localPluginsDir !== undefined
+            ? discoverCapabilityPluginManifests([suiteAssembly.localPluginsDir])
+            : [];
+        // Installed-code-loading (D-075 S2): verified active installations whose
+        // plugin id is a member of the resolved plugin profile (selected, not
+        // disabled) join the pool as explicit candidates; their code loads
+        // through session.loadCapabilityPluginManifest exactly like
+        // caller-supplied paths. Installed plugins that miss membership stay
+        // unloaded — one diagnostic, no implicit third-party loading.
+        const disabledPluginIdSet = new Set(options.disabledPluginIds ?? []);
+        const profilePluginIds = suiteAssembly.pluginProfile !== undefined && suiteAssembly.pluginProfile.status === "resolved"
+            ? new Set(suiteAssembly.pluginProfile.profile.pluginIds.filter((pluginId) => !disabledPluginIdSet.has(pluginId)))
+            : new Set();
+        // S4 拆包（D-075 §6 S4 第一批）：suite.capabilities 声明的
+        // builtin.goal/builtin.plan/builtin.todo-set 短 id 不再有内嵌注册，经
+        // BUILTIN_CAPABILITY_PACKAGE_IDS 映射到独立插件包 id，并入 installed 插件的
+        // 成员资格集合——已安装即随装配链加载（active-bindings 来源不变），未安装时
+        // 静默缺席（不算 dangling）；用户显式 disable 仍然生效。第二批：session-share
+        // 短 id 同样经映射接管；observability 包 id 随 traceEnabled 直接并入（trace
+        // 关闭时不并入 = 插件不加载，与内嵌时代"不注册即禁用"语义一致）。第四批：
+        // builtin.memory 经映射接管，但 memory.mode 解析为 off 时不并入（禁用 = 不装
+        // 配，与内嵌时代"禁用 = 不注册"同语义；上面已带一行启动声明）。
+        const capabilityPackageIds = suiteWorkspace.suite.capabilities.flatMap((shortId) => {
+            const pluginId = BUILTIN_CAPABILITY_PACKAGE_IDS[shortId];
+            return pluginId === undefined ? [] : [pluginId];
+        });
+        if (options.traceEnabled !== false)
+            capabilityPackageIds.push(OBSERVABILITY_PACKAGE_ID);
+        if (memoryModeResolution.mode === "off") {
+            const memoryIndex = capabilityPackageIds.indexOf(MEMORY_PACKAGE_ID);
+            if (memoryIndex >= 0)
+                capabilityPackageIds.splice(memoryIndex, 1);
+        }
+        for (const pluginId of capabilityPackageIds) {
+            if (!disabledPluginIdSet.has(pluginId))
+                profilePluginIds.add(pluginId);
+        }
+        const installedPluginManifestPaths = [];
+        const skippedInstalledPluginIds = [];
+        for (const plugin of options.installedCapabilityPlugins ?? []) {
+            if (profilePluginIds.has(plugin.pluginId))
+                installedPluginManifestPaths.push(plugin.manifestPath);
+            else
+                skippedInstalledPluginIds.push(plugin.pluginId);
+        }
+        if (skippedInstalledPluginIds.length > 0) {
+            capabilityDiagnostics.push(`Installed capability plugins stay unloaded because the active profile did not select them: ${skippedInstalledPluginIds.sort().join(", ")}`);
+        }
+        const manifestPaths = [
+            ...suiteLocalManifestPaths,
+            ...installedPluginManifestPaths,
+            ...discoveredManifestPaths,
+            ...(options.capabilityPluginPaths ?? []),
+        ];
+        const explicitCandidatePaths = new Set([
+            ...suiteLocalManifestPaths,
+            ...installedPluginManifestPaths,
+            ...(options.capabilityPluginPaths ?? []),
+        ]);
+        const loadedManifestPaths = new Set();
+        const explicitManifestPaths = new Set();
+        const candidatePaths = [];
+        for (const manifestPath of manifestPaths) {
+            const resolvedManifestPath = resolve(cwd, manifestPath);
+            const manifestIdentity = existsSync(resolvedManifestPath)
+                ? realpathSync(resolvedManifestPath)
+                : resolvedManifestPath;
+            if (loadedManifestPaths.has(manifestIdentity))
+                continue;
+            loadedManifestPaths.add(manifestIdentity);
+            if (explicitCandidatePaths.has(manifestPath))
+                explicitManifestPaths.add(manifestIdentity);
+            candidatePaths.push(manifestIdentity);
+        }
+        // Single-plugin manifest failures reject that plugin only (D-028); the
+        // session keeps loading the remaining candidates. The D-073 host-version
+        // range gate is semantic (not a parse failure): a manifest whose
+        // declared hostVersion range excludes the running VERSION is rejected
+        // with its own reason code, and a manifest without hostVersion loads
+        // but emits a one-line diagnostic.
+        const manifestEntries = [];
+        for (const manifestPath of candidatePaths) {
+            try {
+                const manifest = await readCapabilityPluginManifestForOrdering(manifestPath);
+                if (manifest.hostVersion !== undefined) {
+                    if (!satisfies(VERSION, manifest.hostVersion)) {
+                        await recordRejection("host_version_incompatible", manifestPath, manifest.id, `Plugin ${manifest.id} declares host version range "${manifest.hostVersion}", but the host is ${VERSION}. Upgrade the host into the declared range, or install a plugin version that supports host ${VERSION}.`);
+                        continue;
+                    }
+                }
+                else {
+                    capabilityDiagnostics.push(`Capability plugin ${manifest.id} (${manifestPath}) does not declare "hostVersion"; it loads, but published plugins must declare a host semver range (e.g. ">=${VERSION}").`);
+                }
+                manifestEntries.push({ path: manifestPath, manifest });
+            }
+            catch (error) {
+                await recordRejection("invalid_manifest", manifestPath, undefined, rejectionMessage(error));
+            }
+        }
+        // Duplicate plugin IDs keep the first candidate in discovery order and
+        // reject the later duplicates. When suite capability wiring is on, the
+        // external plugin pool is filtered by `associations.plugins` (方案系统
+        // M3): the project-level pool (cwd/.agent-forge/plugins) is the third
+        // layer and always passes; every other manifest must match an
+        // association exactly. Explicit capabilityPluginPaths are caller intent
+        // and bypass the filter; filtered plugins and dangling associations
+        // surface as suite diagnostics, never as errors.
+        const poolFilter = capabilityWiring
+            ? {
+                suite: suiteWorkspace.suite,
+                decide: (manifestId, manifestPath) => decideSuiteCapabilityPlugin(suiteWorkspace.suite, { manifestId, manifestPath }, { cwd }),
+            }
+            : undefined;
+        const seenPluginIds = new Set();
+        const uniqueEntries = [];
+        const discoveredPluginIds = [];
+        for (const entry of manifestEntries) {
+            discoveredPluginIds.push(entry.manifest.id);
+            if (poolFilter && !explicitManifestPaths.has(entry.path)) {
+                const decision = poolFilter.decide(entry.manifest.id, entry.path);
+                if (!decision.keep) {
+                    if (decision.diagnostic)
+                        capabilityDiagnostics.push(decision.diagnostic);
+                    continue;
+                }
+            }
+            if (seenPluginIds.has(entry.manifest.id)) {
+                await recordRejection("duplicate_plugin_id", entry.path, entry.manifest.id, `Capability plugin is already loaded: ${entry.manifest.id}; the first manifest in discovery order wins`);
+                continue;
+            }
+            seenPluginIds.add(entry.manifest.id);
+            uniqueEntries.push(entry);
+        }
+        if (poolFilter) {
+            capabilityDiagnostics.push(...suiteDanglingPluginAssociations(poolFilter.suite, discoveredPluginIds));
+        }
+        // Required-capability shortfalls reject the dependent plugin and, by
+        // fixpoint, everything that (transitively) required it. Optional
+        // requirements never reject. Combination-level failures that
+        // resolvePluginCapabilityOrder still detects (duplicate capability
+        // identity, dependency cycles) fail the whole startup explicitly.
+        const capabilityIdentity = (id, version) => `${id}\u0000${version}`;
+        const survivors = new Set(uniqueEntries);
+        let removedInLastPass = true;
+        while (removedInLastPass) {
+            removedInLastPass = false;
+            const providers = new Set();
+            for (const entry of survivors) {
+                for (const declaration of entry.manifest.provides ?? []) {
+                    providers.add(capabilityIdentity(declaration.id, declaration.version));
+                }
+            }
+            for (const entry of [...survivors]) {
+                const missing = (entry.manifest.requires ?? []).filter((requirement) => !requirement.optional && !providers.has(capabilityIdentity(requirement.id, requirement.version)));
+                if (missing.length === 0)
+                    continue;
+                await recordRejection("missing_dependency", entry.path, entry.manifest.id, `Plugin capability is required but unavailable: ${missing
+                    .map((requirement) => `${requirement.id}@${requirement.version}`)
+                    .join(", ")} (${entry.manifest.id})`);
+                survivors.delete(entry);
+                removedInLastPass = true;
+            }
+        }
+        const pathByManifest = new Map([...survivors].map((entry) => [entry.manifest, entry.path]));
+        for (const manifest of resolvePluginCapabilityOrder([...survivors].map((entry) => entry.manifest))) {
+            const manifestPath = pathByManifest.get(manifest);
+            // v8 ignore next -- 顺序解析返回的 manifest 均来自同一 survivors 集合，路径恒存在
+            if (!manifestPath)
+                throw new Error(`Capability plugin manifest path is unavailable: ${manifest.id}`);
+            try {
+                await session.loadCapabilityPluginManifest(manifestPath, {
+                    // CLI 自动池化（承载退役切片 1，D-075 S4 第三批收敛）：宿主声明自身
+                    // 入口可信时改写插件 config 的 runnerEntryAuto（原 builtin 注入链的
+                    // selfInvocationPool 旗标退役）；插件入口的 agent-dir 配置文件仍合并
+                    // 在其上，用户显式配置保持最终决定权。
+                    ...(manifest.id === SUBAGENT_DELEGATE_PACKAGE_ID && options.subagentPoolFromSelfInvocation === true
+                        ? { configOverride: { runnerEntryAuto: true } }
+                        : {}),
+                    // 记忆档位注入（D-075 S4 第四批）：显式定档与 settings.json 持久档位经
+                    // 公共 configOverride 通道合并进 memory 插件包 manifest config——包 entry
+                    // 按同一解析链定档（显式 > env > settings > 旧别名 > off）；agent-dir
+                    // 配置文件（capabilities/builtin.memory.json）仍合并在其上，用户显式
+                    // 配置保持最终决定权。mode=off 的包已在上面的成员资格门控中排除，
+                    // 不会走到这里。
+                    ...(manifest.id === MEMORY_PACKAGE_ID
+                        ? {
+                            configOverride: {
+                                ...(memoryModeOption === undefined ? {} : { memoryMode: memoryModeOption }),
+                                ...(settingsMemoryMode === undefined ? {} : { memorySettingsMode: settingsMemoryMode }),
+                            },
+                        }
+                        : {}),
+                });
+            }
+            catch (error) {
+                await recordRejection("plugin_load_failed", manifestPath, manifest.id, rejectionMessage(error));
+            }
+        }
+        // Plugin-owned context restoration runs only after all manifests are loaded.
+        // The persisted session remains the source of truth; request-time transforms
+        // must never be written back into that history implicitly.
+        if (hasExistingSession && options.contextStrategyName) {
+            await session.replaceContext(existingSession.messages);
+        }
+    }
+    catch (error) {
+        await session.dispose();
+        throw error;
+    }
+    // 会话创建完成打点（设计 §5.2）：创建/恢复路径在装配全部完成后落一行 info。
+    hostLogger?.info("sdk", "agent session created", {
+        sessionId: session.sessionId,
+        fields: {
+            suite: suiteId,
+            ...(model === undefined ? {} : { model: `${model.provider}/${model.id}` }),
+            trace: options.traceEnabled !== false,
+        },
+    });
+    return {
+        session,
+        modelFallbackMessage,
+        pluginRejections: Object.freeze(pluginRejections.slice()),
+        suiteDiagnostics: Object.freeze([
+            ...suiteAssembly.collectDiagnostics(),
+            ...capabilityDiagnostics,
+            ...suitePreferenceDiagnostics,
+        ]),
+        ...(suiteAssembly.pluginProfile === undefined ? {} : { pluginProfile: suiteAssembly.pluginProfile }),
+        resolvedAgentProfile,
+    };
+}
+/**
+ * Create a stable agent session: the same assembly as createAgentSession
+ * (zero behavior difference), returned as the stable facade pair instead of
+ * the raw session (B-S2b③-S2).
+ *
+ * @example
+ * ```typescript
+ * const { facade, sessionAPI } = await createStableAgentSession({
+ *   streamFn: mockStreamFn,
+ *   sessionManager: SessionManager.inMemory(),
+ * });
+ * await facade.prompt("hello");
+ * console.log(sessionAPI.getSessionId());
+ * ```
+ */
+export async function createStableAgentSession(options = {}) {
+    const result = await createAgentSession(options);
+    return {
+        facade: createCodingAgentFacade(result.session),
+        sessionAPI: result.session.getSessionAPI(),
+        // Pure passthrough of the legacy result's create-time diagnostic (D-061):
+        // same value, same assembly, no behavior change.
+        modelFallbackMessage: result.modelFallbackMessage,
+    };
+}
+/**
+ * Create a stable agent session runtime: the same assembly as
+ * createAgentSessionRuntime (zero behavior difference), returned as the stable
+ * runtime facade instead of the raw runtime (D-063, 阶段 4 close-out).
+ *
+ * @example
+ * ```typescript
+ * const { runtimeFacade } = await createStableAgentSessionRuntime(createRuntime, {
+ *   cwd: process.cwd(),
+ *   agentDir: getAgentDir(),
+ *   sessionManager: SessionManager.create(process.cwd()),
+ * });
+ * await runtimeFacade.newSession();
+ * // Re-read after a replacement: the accessor projects the current session.
+ * const facade = runtimeFacade.getSessionFacade();
+ * await facade.prompt("hello");
+ * ```
+ */
+export async function createStableAgentSessionRuntime(createRuntime, options) {
+    const runtime = await createAgentSessionRuntime(createRuntime, options);
+    return { runtimeFacade: createCodingAgentRuntimeFacade(runtime) };
+}
+//# sourceMappingURL=sdk.js.map