@ai-agent-forge/agent-forge 0.85.0

package/dist/core/agent-session.js

@@ -0,0 +1,2550 @@
+/**
+ * AgentSession - Core abstraction for agent lifecycle and session management.
+ *
+ * This class is shared between all run modes (interactive, print, rpc).
+ * It encapsulates:
+ * - Agent state access
+ * - Event subscription with automatic session persistence
+ * - Model and thinking level management
+ * - Compaction (manual and auto)
+ * - Bash execution
+ * - Session switching and branching
+ *
+ * Modes use this class and add their own I/O layer on top.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { contentText } from "@agent-forge/ai";
+import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, streamSimple, } from "@agent-forge/ai/compat";
+import { stripFrontmatter } from "../utils/frontmatter.js";
+import { abortBash, captureBashEpoch, emitUserBash, executeBash, flushPendingBashMessages, isBashEpochCurrent, recordBashResult, } from "./agent-session-bash.js";
+import { checkCompaction, compactBeforeNextAssistantResponse, compactInternal, enqueueCompaction, navigateTree, runAutoCompaction, } from "./agent-session-compaction.js";
+import { applyContextTransition, assertContextTransitionCurrent, beginContextTransitionFence, copyContextMessages, enqueueContextTransition, isContextTransitionCurrent, replaceContext, requireContextStrategy, requireIdleContextOperation, restoreContext, restoreContextTransition, snapshotContext, } from "./agent-session-context.js";
+import { buildExtensionResourcePaths, collectCommandInfos, extendResourcesFromExtensions, getExtensionSourceLabel, } from "./agent-session-extensions.js";
+import { detachedSessionSnapshot, } from "./agent-session-internal.js";
+import { dispatchAgentEndLifecycle, dispatchAgentSettledLifecycle, dispatchAgentStartLifecycle, dispatchAgentTaskSettledLifecycle, dispatchBeforeAgentStartLifecycle, dispatchBeforeAgentStartV2Lifecycle, dispatchContextReplacedLifecycle, dispatchInputGateBlockedLifecycle, dispatchInputReceivedLifecycle, dispatchMessageEndLifecycle, dispatchMessageStartLifecycle, dispatchModelResponseLifecycle, dispatchModelStreamLifecycle, dispatchSessionEndLifecycle, dispatchSessionEntryAppendedLifecycle, dispatchSessionInfoChangedLifecycle, dispatchSessionReloadLifecycle, dispatchSessionStartLifecycle, dispatchThinkingLevelSelectLifecycle, dispatchToolCommitLifecycle, dispatchToolExecutionStartLifecycle, dispatchToolResultLifecycle, dispatchTurnEndLifecycle, dispatchTurnStartLifecycle, observeLifecycleDeliveryError, } from "./agent-session-lifecycle.js";
+import { createLoopWiring, wireDefaultLoop } from "./agent-session-loop.js";
+import { postAgentRun, runPromptLoop } from "./agent-session-loop-runner.js";
+import { addPersistedDefaultToNonEmptyScope, cycleAvailableModel, cycleModel, cycleScopedModel, emitModelSelect, getScopedModels, getThinkingLevelForModelSwitch, modelFactsView, setModel, setScopedModels, } from "./agent-session-model.js";
+import { exportToHtml, exportToJsonl, getContextUsage, getLastAssistantText, getSessionStats, getUserMessagesForForking, } from "./agent-session-projection.js";
+import { isRetryableError, prepareRetry, willRetryAfterAgentEnd } from "./agent-session-retry.js";
+import { getAllTools, getCapabilitySkills, getToolDefinition, normalizePromptGuidelines, normalizePromptSnippet, rebuildSystemPrompt, refreshBootstrapSkills, refreshToolRegistry, setActiveToolsByName, syncCapabilityTools, validateCapabilitySkillConflicts, } from "./agent-session-tools.js";
+import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
+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 { expandPromptTemplate } from "./prompt-templates.js";
+import { createSessionJsonlArtifact } from "./session-export.js";
+import { createToolSearchTool } from "./tools/tool-search.js";
+/**
+ * Parse a skill block from message text.
+ * Returns null if the text doesn't contain a skill block.
+ */
+export function parseSkillBlock(text) {
+    const match = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
+    if (!match)
+        return null;
+    return {
+        name: match[1],
+        location: match[2],
+        content: match[3],
+        userMessage: match[4]?.trim() || undefined,
+    };
+}
+/**
+ * Custom entry type marking a cross-suite resume (设计 §10.1 最小可用版): the
+ * session was created under one suite but its context was reassembled under
+ * another. Entry data: `{ originalSuiteId, currentSuiteId }`.
+ */
+export const SUITE_MISMATCH_SESSION_ENTRY_TYPE = "suite_mismatch";
+// ============================================================================
+// Constants
+// ============================================================================
+// ============================================================================
+// AgentSession Class
+// ============================================================================
+/**
+ * Core session orchestration adapter.
+ *
+ * The stable facade `CodingAgentFacadeV1` (docs/design/稳定门面统一入口设计.md)
+ * is the only supported consumption surface for product hosts. Direct
+ * consumption of this class is limited to registered carve-outs
+ * (tui-private-path-contract.test.ts allowlists and the §2.7/§2.9 deferred
+ * registrations in the design doc).
+ *
+ * @internal
+ */
+export class AgentSession {
+    agent;
+    sessionManager;
+    settingsManager;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _scopedModels;
+    // Event subscription state
+    _unsubscribeAgent;
+    _eventListeners = [];
+    _isAgentRunActive = false;
+    _idleWaitPromise;
+    _resolveIdleWait;
+    /** Tracks pending steering messages for UI display. Removed when delivered. */
+    _steeringMessages = [];
+    /** Tracks pending follow-up messages for UI display. Removed when delivered. */
+    _followUpMessages = [];
+    /** Messages queued to be included with the next user prompt as context ("asides"). */
+    _pendingNextTurnMessages = [];
+    /** Context-only custom messages queued during a run, flushed once the current turn's tool results are in. */
+    _pendingCustomMessages = [];
+    // Compaction state
+    /** Serializes manual and automatic compaction, including their projections. */
+    _compactionQueue = Promise.resolve();
+    _compactionAbortController = undefined;
+    _autoCompactionAbortController = undefined;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _overflowRecoveryAttempted = false;
+    // Branch summarization state
+    _branchSummaryAbortController = undefined;
+    _branchSummaryPromise = undefined;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _resolveBranchSummaryPromise = undefined;
+    // Retry state
+    _retryAbortController = undefined;
+    /** Cancellation boundary for retry/overflow policy decisions in the active agent loop. */
+    _policyDecisionAbortController = undefined;
+    _retryAttempt = 0;
+    /** Cancellation signal for the capability command currently executing through prompt(). */
+    _commandAbortController = undefined;
+    /**
+     * Parent-session cancel fence for agent tasks (D-044 §4.2). Consumed once
+     * per task creation through the runtime's `parentSignal` getter; replaced
+     * after every abort/runtime rebuild so later tasks bind to a fresh signal.
+     */
+    _agentTaskScopeAbortController = new AbortController();
+    _activeCapabilityCommand;
+    _activeCompactionPromise;
+    /** Prevents new mutable work from entering while the session is being replaced. */
+    _reloadInProgress = false;
+    /** Monotonic committed reload generation, distinct from disposal and bash fences. */
+    _reloadGeneration = 0;
+    /** Generation fence for context projections that may outlive a runtime replacement. */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _contextEpoch = 0;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _contextTransitionAbortController = new AbortController();
+    /** Serializes context transitions and lets reload/dispose drain them before teardown. */
+    _activeContextTransition;
+    /** Monotonic revision for the public context snapshot/commit facade. */
+    _contextRevision = 0;
+    /** Serializes public context commits so expectedRevision is a real CAS fence. */
+    _contextCommitQueue = Promise.resolve();
+    // Bash execution state
+    _bashAbortControllers = new Set();
+    /** Whole bash operations, including their final session-history write. */
+    _activeBashPromises = new Set();
+    /** Fences mode-level bash results captured before a runtime replacement. */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _bashEpoch = 0;
+    _pendingBashMessages = [];
+    _turnIndex = 0;
+    _resourceLoader;
+    _customTools;
+    _deferredToolPluginIds;
+    /** Abort reason supplied to the in-flight abort(); consumed by the interruption marker. */
+    _pendingAbortReason;
+    /** Set when the in-flight prompt run produced an aborted terminal assistant turn. */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _currentRunAborted = false;
+    /** Most recent abort reason; persists after abort() returns so prompt() can report it. */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _lastAbortReason;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _baseToolDefinitions = new Map();
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _baseToolSources = new Map();
+    _capabilityRuntime;
+    /** Output-artifact commit listeners registered through {@link onOutputArtifactCommit}. */
+    _outputArtifactCommitListeners = new Set();
+    /**
+     * Stable commit dispatcher handed to every CapabilityRuntime this session
+     * builds; listeners registered on the session survive runtime rebuilds.
+     */
+    _dispatchOutputArtifactCommit = (artifact) => {
+        for (const listener of [...this._outputArtifactCommitListeners])
+            listener(artifact);
+    };
+    _bootstrapToolsHandle;
+    _bootstrapSkillsHandle;
+    _bootstrapRetryHandle;
+    _bootstrapCompactionHandle;
+    _bootstrapBranchSummaryHandle;
+    _bootstrapOverflowHandle;
+    _bootstrapAgentLoopHandle;
+    _bootstrapLifecycleHandle;
+    _capabilityPlugins = new Map();
+    _inlineCapabilityPlugins = new Map();
+    _isDisposingCapabilityPlugins = false;
+    /**
+     * 工具表变更钩子的两道门（见 _buildRuntime 的 onToolRegistryChange）：
+     * - `_toolRegistryHookReady`：构造期门。_buildRuntime 求值阶段 bootstrap 插件
+     *   注册即触发 notify，而此时内部状态未就绪（观察回调会抛），构造完成后既有
+     *   边界（_buildRuntime 尾部的显式 sync + refresh）已兜底，跳过不丢状态。
+     * - `_suspendToolRegistryHookRefresh`：插件卸载恢复链的中间态挂起位。恢复过程
+     *   会先删新注册、后恢复被替换者，中间 notify 的工具表是暂态（活跃名暂时缺
+     *   席）；该窗口内刷新会把缺席名从活动集永久剔除。装卸边界在 dispose 完成后
+     *   自行兜底刷新。
+     */
+    _suspendToolRegistryHookRefresh = false;
+    _toolRegistryHookReady = false;
+    _disposePromise;
+    _cwd;
+    _initialActiveToolNames;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _allowedToolNames;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _excludedToolNames;
+    _baseToolsOverride;
+    _disabledBootstrapPlugins;
+    _sessionStartEvent;
+    _capabilityMode;
+    _contextStrategyName;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _retryPolicyName;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _compactionPolicyName;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _branchSummaryPolicyName;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _overflowPolicyName;
+    /** Post-run continuation strategy name; missing registrations fall back to the host candidate. */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _runLoopStrategyName;
+    /**
+     * Internal loop-executor seam (D-043 G3); no public config, distinct from
+     * runLoopStrategyName (a per-continuation veto policy).
+     */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _loopExecutor;
+    /** The agent's construction-time prepare adapter, captured once by the loop wiring. */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _initialPrepareNextTurn;
+    _agentTaskAdapter;
+    _agentTaskResults;
+    _agentSessionReader;
+    _agentSessionLister;
+    _agentComposition;
+    _interactionHost;
+    _modelRuntime;
+    _modelStreamCounter = 0;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _modelStreamState;
+    /** Correlation id shared by every in-turn lifecycle dispatch of the active prompt run. */
+    _turnCorrelationId;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _turnCorrelationCounter = 0;
+    // Tool registry for extension getTools/setTools
+    _toolRegistry = new Map();
+    _toolDefinitions = new Map();
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _toolPromptSnippets = new Map();
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _toolPromptGuidelines = new Map();
+    // Base system prompt (without extension appends) - used to apply fresh appends each turn
+    _baseSystemPrompt = "";
+    _baseSystemPromptOptions;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _systemPromptOverride;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _orientationPrompt;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _preferenceCard;
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _capabilitySkillsFilter;
+    _hostLogger;
+    _logRecordMirrorRef;
+    _observabilityGetMetricsRef;
+    _agentDir;
+    _communication;
+    _turnContext;
+    _roleAssociations;
+    _memoryStorage;
+    _traceService;
+    constructor(config) {
+        this.agent = config.agent;
+        this.sessionManager = config.sessionManager;
+        this._contextRevision = this.sessionManager.getRevision().sequence;
+        this.settingsManager = config.settingsManager;
+        this._scopedModels = config.scopedModels ?? [];
+        this._resourceLoader = config.resourceLoader;
+        this._customTools = config.customTools ?? [];
+        this._deferredToolPluginIds = new Set(config.deferredToolPluginIds ?? []);
+        if (this._deferredToolPluginIds.size > 0) {
+            this._customTools.push(createToolSearchTool({
+                listAllToolNames: () => Array.from(this._toolRegistry.keys()),
+                getToolInfo: (name) => {
+                    const definition = this._toolDefinitions.get(name)?.definition;
+                    return definition ? { name: definition.name, description: definition.description } : undefined;
+                },
+                getActiveToolNames: () => this.getActiveToolNames(),
+                setActiveToolsByName: (toolNames) => this.setActiveToolsByName(toolNames),
+            }));
+        }
+        this._cwd = config.cwd;
+        this._modelRuntime = config.modelRuntime;
+        this._initialActiveToolNames = config.initialActiveToolNames;
+        this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
+        this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
+        this._baseToolsOverride = config.baseToolsOverride;
+        this._disabledBootstrapPlugins = config.disabledBootstrapPlugins;
+        this._sessionStartEvent = config.sessionStartEvent ?? { reason: "startup" };
+        this._capabilityMode = config.capabilityMode ?? "full-control";
+        this._contextStrategyName = config.contextStrategyName;
+        this._retryPolicyName = config.retryPolicyName ?? DEFAULT_RETRY_POLICY_NAME;
+        this._compactionPolicyName = config.compactionPolicyName ?? DEFAULT_COMPACTION_POLICY_NAME;
+        this._branchSummaryPolicyName = config.branchSummaryPolicyName ?? DEFAULT_BRANCH_SUMMARY_POLICY_NAME;
+        this._overflowPolicyName = config.overflowPolicyName ?? DEFAULT_OVERFLOW_POLICY_NAME;
+        this._runLoopStrategyName = config.runLoopStrategyName ?? DEFAULT_RUN_LOOP_STRATEGY_NAME;
+        this._agentTaskAdapter = config.agentTaskAdapter;
+        this._agentTaskResults = config.agentTaskResults;
+        this._agentSessionReader = config.agentSessionReader;
+        this._agentSessionLister = config.agentSessionLister;
+        this._agentComposition = config.agentComposition;
+        this._interactionHost = config.interactionHost;
+        this._orientationPrompt = config.orientationPrompt;
+        this._preferenceCard = config.preferenceCard;
+        this._capabilitySkillsFilter = config.capabilitySkillsFilter;
+        this._hostLogger = config.hostLogger;
+        this._logRecordMirrorRef = config.logRecordMirrorRef;
+        this._observabilityGetMetricsRef = config.observabilityGetMetricsRef;
+        this._agentDir = config.agentDir;
+        this._communication = config.communication;
+        this._turnContext = config.turnContext;
+        this._roleAssociations = config.roleAssociations;
+        this._memoryStorage = config.memoryStorage;
+        this._traceService = config.traceService;
+        // Always subscribe to agent events for internal handling
+        // (session persistence, extensions, auto-compaction, retry logic)
+        this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
+        this._buildRuntime({
+            activeToolNames: this._initialActiveToolNames,
+            includeAllExtensionTools: true,
+        });
+        this._wireDefaultLoop();
+    }
+    /**
+     * 当前回合的 correlation id（会话轨迹设计 §4.2）：活跃 prompt 回合内所有
+     * lifecycle 信封携带的同一 correlationId（与信封同源：loop-runner 在回合
+     * 开始写入 `_turnCorrelationId`、回合结束清除）；空闲时为 undefined。只读
+     * 事实，供宿主适配器做回合级关联（如 observability 的 llm.request traceId）。
+     */
+    getTurnCorrelationId() {
+        return this._turnCorrelationId;
+    }
+    /**
+     * 宿主 digest sink 面（第 4 期轨迹闭合）：把一条后台委派结算行投递为
+     * agent.task.settled@1（父会话 sessionId 由派发助手补）。派发是非致命
+     * fire-and-forget；dispose 后 runtime 已 revoke，助手 no-op。
+     */
+    dispatchAgentTaskSettled(facts) {
+        void dispatchAgentTaskSettledLifecycle(this._internal, facts);
+    }
+    get modelRuntime() {
+        return this._modelRuntime;
+    }
+    /** Internal facade passed to the agent-session-* submodule functions. */
+    get _internal() {
+        return this;
+    }
+    /**
+     * Wire the default main loop onto the Agent instance.
+     *
+     * The four hook positions are composed from the runtime's loop-hook chains.
+     * Chains are read at execution time, so extension reload swaps in the new
+     * runtime without reinstalling the wiring. The legacy extension gate and the
+     * agent's construction-time context transform stay as chain heads (host
+     * wiring, not plugin capabilities); the default links come from the
+     * bootstrap agent-loop plugin and third-party links chain after them in
+     * registration order.
+     */
+    _wireDefaultLoop() {
+        wireDefaultLoop(this._internal);
+    }
+    /** Session-bound host state the default loop links read at execution time. */
+    _createLoopWiring() {
+        return createLoopWiring(this._internal);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _compactBeforeNextAssistantResponse(context, signal) {
+        return compactBeforeNextAssistantResponse(this._internal, context, signal);
+    }
+    // =========================================================================
+    // Event Subscription
+    // =========================================================================
+    /** Emit an event to all listeners */
+    _emit(event) {
+        for (const l of this._eventListeners) {
+            l(event);
+        }
+    }
+    _emitQueueUpdate() {
+        this._emit({
+            type: "queue_update",
+            steering: [...this._steeringMessages],
+            followUp: [...this._followUpMessages],
+        });
+    }
+    _getIdleWaitPromise() {
+        if (!this._idleWaitPromise) {
+            this._idleWaitPromise = new Promise((resolve) => {
+                this._resolveIdleWait = resolve;
+            });
+        }
+        return this._idleWaitPromise;
+    }
+    _resolveIdleWaitIfIdle() {
+        if (!this.isIdle || !this._resolveIdleWait) {
+            return;
+        }
+        const resolve = this._resolveIdleWait;
+        this._idleWaitPromise = undefined;
+        this._resolveIdleWait = undefined;
+        resolve();
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    async _emitAgentSettled() {
+        this._isAgentRunActive = false;
+        try {
+            this._emit({ type: "agent_settled" });
+            await dispatchAgentSettledLifecycle(this._internal);
+        }
+        finally {
+            this._resolveIdleWaitIfIdle();
+        }
+    }
+    // Track last assistant message for auto-compaction check
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _lastAssistantMessage = undefined;
+    // The agent_end event and post-run handler both need the retry decision. Cache it
+    // so policy plugins are evaluated once per assistant turn (and mock queues remain
+    // strict/deterministic).
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _pendingRetryDecision = undefined;
+    /** Internal handler for agent events - shared by subscribe and reconnect */
+    _handleAgentEvent = async (event) => {
+        if (event.type === "message_start" && event.message.role === "assistant") {
+            this._modelStreamState = {
+                streamId: `model-stream:${++this._modelStreamCounter}`,
+                sequence: 0,
+            };
+            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;
+            const messageText = contentText(event.message.content, "");
+            if (messageText) {
+                // Check steering queue first
+                const steeringIndex = this._steeringMessages.indexOf(messageText);
+                if (steeringIndex !== -1) {
+                    this._steeringMessages.splice(steeringIndex, 1);
+                    this._emitQueueUpdate();
+                }
+                else {
+                    // Check follow-up queue
+                    const followUpIndex = this._followUpMessages.indexOf(messageText);
+                    if (followUpIndex !== -1) {
+                        this._followUpMessages.splice(followUpIndex, 1);
+                        this._emitQueueUpdate();
+                    }
+                }
+            }
+        }
+        await this._emitLifecycleEvents(event);
+        if (event.type === "message_update" && event.message.role === "assistant") {
+            await this._dispatchModelStreamLifecycle(event.message, event.assistantMessageEvent.type, "candidate");
+        }
+        // Notify all listeners
+        this._emit(event.type === "agent_end"
+            ? {
+                ...event,
+                willRetry: await this._willRetryAfterAgentEnd(event, this._policyDecisionAbortController?.signal),
+            }
+            : event);
+        // Handle session persistence
+        if (event.type === "message_end") {
+            // Check if this is a custom message from extensions
+            if (event.message.role === "custom") {
+                // Persist as CustomMessageEntry
+                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+            }
+            else if (event.message.role === "user" ||
+                event.message.role === "assistant" ||
+                event.message.role === "toolResult") {
+                // Regular LLM message - persist as SessionMessageEntry
+                const entryId = this.sessionManager.appendMessage(event.message);
+                if (event.message.role === "assistant") {
+                    if (event.message.stopReason === "aborted") {
+                        this._currentRunAborted = true;
+                    }
+                    await this._dispatchModelStreamLifecycle(event.message, event.message.stopReason === "error" || event.message.stopReason === "aborted" ? "error" : "done", "committed");
+                    this._modelStreamState = undefined;
+                    await this._dispatchModelResponseLifecycle(event.message, entryId);
+                }
+                else if (event.message.role === "toolResult") {
+                    await this._dispatchToolCommitLifecycle(event.message, entryId);
+                    await this._dispatchToolResultLifecycle(event.message, entryId);
+                }
+            }
+            // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
+            // Track assistant message for auto-compaction (checked on agent_end)
+            if (event.message.role === "assistant") {
+                this._lastAssistantMessage = event.message;
+                const assistantMsg = event.message;
+                if (assistantMsg.stopReason !== "error" && assistantMsg.stopReason !== "length") {
+                    this._overflowRecoveryAttempted = false;
+                }
+                // 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) {
+                    this._emit({
+                        type: "auto_retry_end",
+                        success: true,
+                        attempt: this._retryAttempt,
+                    });
+                    this._retryAttempt = 0;
+                }
+            }
+        }
+        // A turn ends after its assistant message and every tool result has been appended,
+        // so this is the first point in the run where a context-only custom message can be
+        // inserted without landing between a tool call and its result. Flushing after the
+        // extension and listener dispatch above also picks up messages that turn_end
+        // handlers queued.
+        if (event.type === "turn_end") {
+            this._flushPendingCustomMessages();
+        }
+    };
+    async _dispatchModelStreamLifecycle(message, eventName, phase) {
+        await dispatchModelStreamLifecycle(this._internal, message, eventName, phase);
+    }
+    _willRetryAfterAgentEnd(event, signal) {
+        return willRetryAfterAgentEnd(this._internal, event, signal);
+    }
+    /** Find the last assistant message in agent state (including aborted ones) */
+    _findLastAssistantMessage() {
+        const messages = this.agent.state.messages;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const msg = messages[i];
+            if (msg.role === "assistant") {
+                return msg;
+            }
+        }
+        return undefined;
+    }
+    /** Deliver capability lifecycle events derived from one agent event. */
+    async _emitLifecycleEvents(event) {
+        if (event.type === "agent_start") {
+            this._turnIndex = 0;
+            await dispatchAgentStartLifecycle(this._internal);
+        }
+        else if (event.type === "agent_end") {
+            await dispatchAgentEndLifecycle(this._internal);
+        }
+        else if (event.type === "turn_start") {
+            await dispatchTurnStartLifecycle(this._internal, this._turnIndex);
+        }
+        else if (event.type === "turn_end") {
+            this._turnIndex++;
+            // turn 级 outcome 判定（复审 M2）：取 turn_end 事件自带 assistant message
+            // 的 stopReason（provider 层 signal.aborted 优先返回 "aborted"，取值互斥
+            // 精确）。禁用 run 级 `_currentRunAborted`——abort 后 drain 排队消息的
+            // 正常回合会被误标；completed 回合不传，缺席省键。
+            const turnMessage = event.message;
+            const outcome = turnMessage.role === "assistant" &&
+                (turnMessage.stopReason === "aborted" || turnMessage.stopReason === "error")
+                ? turnMessage.stopReason
+                : undefined;
+            await dispatchTurnEndLifecycle(this._internal, this._turnIndex, this.agent.state.messages.length, outcome);
+        }
+        else if (event.type === "message_start") {
+            await dispatchMessageStartLifecycle(this._internal, event.message.role);
+        }
+        else if (event.type === "message_end") {
+            await dispatchMessageEndLifecycle(this._internal, event.message.role);
+        }
+        else if (event.type === "tool_execution_start") {
+            await dispatchToolExecutionStartLifecycle(this._internal, event.toolCallId, event.toolName);
+        }
+    }
+    /**
+     * Subscribe to agent events.
+     * Session persistence is handled internally (saves messages on message_end).
+     * Multiple listeners can be added. Returns unsubscribe function for this listener.
+     */
+    subscribe(listener) {
+        this._eventListeners.push(listener);
+        // Return unsubscribe function for this specific listener
+        return () => {
+            const index = this._eventListeners.indexOf(listener);
+            if (index !== -1) {
+                this._eventListeners.splice(index, 1);
+            }
+        };
+    }
+    /** Disconnect from agent events during disposal. */
+    _disconnectFromAgent() {
+        if (this._unsubscribeAgent) {
+            this._unsubscribeAgent();
+            this._unsubscribeAgent = undefined;
+        }
+    }
+    /**
+     * Remove all listeners and disconnect from agent.
+     * Call this when completely done with the session.
+     */
+    dispose() {
+        if (this._disposePromise)
+            return this._disposePromise;
+        this._disposePromise = (async () => {
+            const errors = [];
+            this._beginContextTransitionFence();
+            // Fence mode-level and legacy extension bash work before async cleanup.
+            this._bashEpoch += 1;
+            for (const abort of [
+                () => this._abortActiveCapabilityCommand("session disposed"),
+                () => this.abortRetry(),
+                () => this.abortCompaction(),
+                () => this.abortBranchSummary(),
+                () => this.abortBash(),
+                () => this._agentTaskScopeAbortController.abort("session disposed"),
+                () => this.agent.abort(),
+            ]) {
+                try {
+                    await abort();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            await Promise.allSettled([this._activeContextTransition, ...this._activeBashPromises, this.waitForIdle()].filter((operation) => operation !== undefined));
+            this._disconnectFromAgent();
+            this._eventListeners = [];
+            // 会话终态（第 4 期轨迹闭合）：capability plugins dispose 之前派发
+            // session.end@1——runtime 仍存活、observability 插件此时尚未 dispose，
+            // 能写入最后一行轨迹。dispose 幂等（_disposePromise 重入即返回同一
+            // promise），派发天然只发生一次；reload 不经过 dispose，不派发。
+            await dispatchSessionEndLifecycle(this._internal);
+            const disposals = [
+                () => this._disposeCapabilityPlugins(),
+                () => this._capabilityRuntime?.disposeAll(),
+                () => {
+                    const adapter = this._agentTaskAdapter;
+                    return adapter?.dispose?.();
+                },
+                () => {
+                    const interactionHost = this._interactionHost;
+                    return interactionHost?.dispose?.();
+                },
+                () => this._bootstrapToolsHandle?.dispose(),
+                () => this._bootstrapSkillsHandle?.dispose(),
+                () => this._bootstrapRetryHandle?.dispose(),
+                () => this._bootstrapCompactionHandle?.dispose(),
+                () => this._bootstrapOverflowHandle?.dispose(),
+                () => this._bootstrapBranchSummaryHandle?.dispose(),
+                () => this._bootstrapAgentLoopHandle?.dispose(),
+                () => this._bootstrapLifecycleHandle?.dispose(),
+            ];
+            for (const dispose of disposals) {
+                try {
+                    await dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            this._capabilityRuntime?.revokeAllAPIs();
+            this._capabilityPlugins.clear();
+            this._inlineCapabilityPlugins.clear();
+            this._bootstrapToolsHandle = undefined;
+            this._bootstrapSkillsHandle = undefined;
+            this._bootstrapRetryHandle = undefined;
+            this._bootstrapCompactionHandle = undefined;
+            this._bootstrapOverflowHandle = undefined;
+            this._bootstrapBranchSummaryHandle = undefined;
+            this._bootstrapAgentLoopHandle = undefined;
+            this._bootstrapLifecycleHandle = undefined;
+            cleanupSessionResources(this.sessionId);
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1)
+                throw new AggregateError(errors, `Agent session disposal failed: ${this.sessionId}`);
+        })();
+        return this._disposePromise;
+    }
+    // =========================================================================
+    // Read-only State Access
+    // =========================================================================
+    /** Full agent state */
+    get state() {
+        return this.agent.state;
+    }
+    /** Current model (may be undefined if not yet selected) */
+    get model() {
+        return this.agent.state.model;
+    }
+    /** Current thinking level */
+    get thinkingLevel() {
+        return this.agent.state.thinkingLevel;
+    }
+    /** Whether the session is currently processing an agent run or post-run continuation. */
+    get isStreaming() {
+        return this._isAgentRunActive;
+    }
+    /** Whether the session has no active agent run, retry, compaction, branch summarization, or queued continuation. */
+    get isIdle() {
+        return !this._isAgentRunActive && !this.isCompacting;
+    }
+    /** Current effective system prompt (includes any per-turn extension modifications) */
+    get systemPrompt() {
+        return this.agent.state.systemPrompt;
+    }
+    /** Current retry attempt (0 if not retrying) */
+    get retryAttempt() {
+        return this._retryAttempt;
+    }
+    /**
+     * Get the names of currently active tools.
+     * Returns the names of tools currently set on the agent.
+     */
+    getActiveToolNames() {
+        return this.agent.state.tools.map((t) => t.name);
+    }
+    /** Public capability runtime for external orchestration and plugin composition. */
+    getCapabilityRuntime() {
+        if (!this._capabilityRuntime)
+            throw new Error("Capability runtime is not available");
+        return this._capabilityRuntime;
+    }
+    /**
+     * Observes every output artifact committed through this session's capability
+     * runtime. Host adapters mirror the payload into durable storage; the runtime
+     * itself carries no durable dependency. The registration survives runtime
+     * rebuilds (reload) because the session owns the dispatcher. Returns an
+     * unsubscribe function.
+     */
+    onOutputArtifactCommit(listener) {
+        this._outputArtifactCommitListeners.add(listener);
+        return () => {
+            this._outputArtifactCommitListeners.delete(listener);
+        };
+    }
+    get isDisposed() {
+        return this._disposePromise !== undefined;
+    }
+    /** Public session facade for host adapters. It never exposes SessionManager internals. */
+    getSessionAPI() {
+        return {
+            getSessionId: () => this.sessionManager.getSessionId(),
+            getRevision: () => this.sessionManager.getRevision(),
+            registerEntryProjection: (projection) => 
+            // 公共投影契约是松类型（unknown 列表）；此处是宿主信任边界，
+            // 投影实现错误会在上下文投影时显式失败，不在此静默防御。
+            this.sessionManager.registerEntryProjection(projection),
+            getContextSnapshot: () => ({
+                version: 1,
+                revision: this._contextRevision,
+                value: detachedSessionSnapshot(this.agent.state.messages),
+            }),
+            commitContext: async (request) => {
+                const commit = this._contextCommitQueue.then(async () => {
+                    if (request.signal?.aborted)
+                        throw new Error("Context commit cancelled");
+                    const currentRevision = this._contextRevision;
+                    if (request.operationId.trim() === "")
+                        throw new Error("Context commit operationId is required");
+                    if (request.expectedRevision !== currentRevision) {
+                        throw new Error(`Context revision conflict: expected ${request.expectedRevision}, current ${currentRevision}`);
+                    }
+                    if (!Array.isArray(request.value))
+                        throw new Error("Session context commit requires a message array");
+                    await this.replaceContext(request.value);
+                    if (request.signal?.aborted)
+                        throw new Error("Context commit cancelled");
+                    return {
+                        version: 1,
+                        status: "committed",
+                        revision: this._contextRevision,
+                        value: detachedSessionSnapshot(this.agent.state.messages),
+                    };
+                });
+                this._contextCommitQueue = commit.then(() => undefined, () => undefined);
+                return commit;
+            },
+            getMessages: () => detachedSessionSnapshot(this.agent.state.messages),
+            isIdle: () => this.isIdle,
+            prompt: (text) => this.prompt(text),
+            steer: (text) => this.steer(text),
+            queueFollowUp: (text) => this.sendUserMessage(text, { deliverAs: "followUp" }),
+            abort: () => this.abort(),
+            waitForIdle: () => this.waitForIdle(),
+            getActiveTools: () => this.getActiveToolNames(),
+            // readonly 会话不暴露能力面变更口（只读就是只读：能在只读会话上改工具面的
+            // 消费方等于拿到了放大权限的口子）。成员缺席即不可用，调用方按可选处理。
+            ...(this._capabilityMode === "readonly"
+                ? {}
+                : { setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames) }),
+            compact: (customInstructions) => this.compact(customInstructions),
+            navigateTree: (targetId, options) => this.navigateTree(targetId, options),
+            appendEntry: (customType, data) => {
+                const entryId = this.sessionManager.appendCustomEntry(customType, data === undefined ? undefined : detachedSessionSnapshot(data));
+                const entry = this.sessionManager.getEntry(entryId);
+                if (entry) {
+                    this._emit({ type: "entry_appended", entry });
+                    void dispatchSessionEntryAppendedLifecycle(this._internal, entryId, entry.type);
+                }
+                return entryId;
+            },
+            setSessionName: (name) => this.setSessionName(name),
+            getSessionName: () => this.sessionManager.getSessionName(),
+            setLabel: (entryId, label) => this.sessionManager.appendLabelChange(entryId, label),
+            getLabel: (entryId) => this.sessionManager.getLabel(entryId),
+            getAllTools: () => definitionSnapshot(this.getAllTools()),
+            getCommands: () => collectCommandInfos(this._internal),
+            getModel: () => (this.model ? detachedSnapshot(modelFactsView(this.model)) : undefined),
+            getScopedModels: () => detachedSnapshot(this.scopedModels.map((entry) => ({
+                model: modelFactsView(entry.model),
+                ...(entry.thinkingLevel === undefined ? {} : { thinkingLevel: entry.thinkingLevel }),
+            }))),
+            getThinkingLevel: () => this.thinkingLevel,
+            ...(this._capabilityMode === "readonly" ? {} : { setThinkingLevel: (level) => this.setThinkingLevel(level) }),
+            ...(this._capabilityMode === "readonly"
+                ? {}
+                : {
+                    setModel: async (modelId) => {
+                        const scoped = this.scopedModels.find((entry) => entry.model.id === modelId);
+                        if (!scoped)
+                            return false;
+                        if (!this._modelRuntime.hasConfiguredAuth(scoped.model.provider))
+                            return false;
+                        await this.setModel(scoped.model);
+                        return true;
+                    },
+                }),
+            getSystemPrompt: () => this.systemPrompt,
+            getSystemPromptOptions: () => detachedSnapshot(this._baseSystemPromptOptions),
+            getContextUsage: () => getContextUsage(this._internal),
+            sendMessage: (message, options) => this.sendCustomMessage(message, options),
+            getBranchEntries: () => detachedSessionSnapshot(this.sessionManager.getBranch().map((entry) => ({
+                id: entry.id,
+                parentId: entry.parentId,
+                timestamp: entry.timestamp,
+                type: entry.type,
+                ...(entry.type === "message"
+                    ? {
+                        message: {
+                            role: entry.message.role,
+                            ...("content" in entry.message ? { content: entry.message.content } : {}),
+                        },
+                    }
+                    : {}),
+                ...(entry.type === "custom" ? { customType: entry.customType, data: entry.data } : {}),
+            }))),
+            exportArtifact: (request) => {
+                if (request.format !== "jsonl")
+                    throw new Error(`Unsupported session export format: ${request.format}`);
+                return createSessionJsonlArtifact(this.sessionManager);
+            },
+        };
+    }
+    /** Return all currently loaded capability plugins without exposing private session state. */
+    getCapabilityPlugins() {
+        const handles = Array.from(this._capabilityPlugins.values());
+        for (const handle of [
+            this._bootstrapToolsHandle,
+            this._bootstrapSkillsHandle,
+            this._bootstrapRetryHandle,
+            this._bootstrapCompactionHandle,
+            this._bootstrapOverflowHandle,
+            this._bootstrapBranchSummaryHandle,
+            this._bootstrapLifecycleHandle,
+        ]) {
+            if (handle)
+                handles.push(handle);
+        }
+        return handles;
+    }
+    /** Name of the externally selected context strategy, when configured. */
+    get contextStrategyName() {
+        return this._contextStrategyName;
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _requireContextStrategy() {
+        return requireContextStrategy(this._internal);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _requireIdleContextOperation(operation) {
+        requireIdleContextOperation(this._internal, operation);
+    }
+    _beginContextTransitionFence() {
+        beginContextTransitionFence(this._internal);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _isContextTransitionCurrent(epoch, allowReload) {
+        return isContextTransitionCurrent(this._internal, epoch, allowReload);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _assertContextTransitionCurrent(epoch, allowReload) {
+        assertContextTransitionCurrent(this._internal, epoch, allowReload);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _enqueueContextTransition(operation, options) {
+        return enqueueContextTransition(this._internal, operation, options);
+    }
+    _copyContextMessages(value, strategyName, direction) {
+        return copyContextMessages(value, strategyName, direction);
+    }
+    /** Apply a persisted-context transition, including strategy-owned projections. */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    async _applyContextTransition(messages, reason = "session_replace", signal, options) {
+        return applyContextTransition(this._internal, messages, reason, signal, options);
+    }
+    /** Notify observers only after the runtime context projection has been committed. */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    async _dispatchContextReplacedLifecycle(reason, strategyName) {
+        await dispatchContextReplacedLifecycle(this._internal, reason, strategyName);
+    }
+    /** Deliver the finalized assistant response only after its session entry is committed. */
+    async _dispatchModelResponseLifecycle(message, entryId) {
+        await dispatchModelResponseLifecycle(this._internal, message, entryId);
+    }
+    /** Deliver the finalized tool result only after its session entry is committed. */
+    async _dispatchToolCommitLifecycle(message, entryId) {
+        await dispatchToolCommitLifecycle(this._internal, message, entryId);
+    }
+    /** Deliver the finalized tool result only after its session entry is committed. */
+    async _dispatchToolResultLifecycle(message, entryId) {
+        await dispatchToolResultLifecycle(this._internal, message, entryId);
+    }
+    /** Notify the rebuilt runtime only after all reload work has committed. */
+    async _dispatchSessionReloadLifecycle(generation) {
+        await dispatchSessionReloadLifecycle(this._internal, generation);
+    }
+    /** Snapshot the current session messages with the configured context strategy. */
+    async snapshotContext() {
+        return snapshotContext(this._internal);
+    }
+    /** Restore session messages from a strategy snapshot. */
+    async restoreContext(snapshot) {
+        return restoreContext(this._internal, snapshot);
+    }
+    /** Replace session messages through the configured context strategy. */
+    async replaceContext(context) {
+        return replaceContext(this._internal, context);
+    }
+    _restoreContextTransition(snapshot, reason, options) {
+        return restoreContextTransition(this._internal, snapshot, reason, options);
+    }
+    async _trackCapabilityPlugin(key, loaded, previousToolNames) {
+        try {
+            this._validateCapabilitySkillConflicts();
+        }
+        catch (error) {
+            await loaded.dispose();
+            throw error;
+        }
+        let disposed = false;
+        const handle = {
+            manifest: loaded.manifest,
+            api: loaded.api,
+            ready: loaded.ready,
+            dispose: async () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                // 卸载恢复链的中间 notify 是暂态（活跃名暂时缺席），挂起钩子内的可见
+                // 注册表刷新；恢复完成后在此按装卸边界语义兜底刷新一次。
+                this._suspendToolRegistryHookRefresh = true;
+                try {
+                    await loaded.dispose();
+                }
+                finally {
+                    this._suspendToolRegistryHookRefresh = false;
+                }
+                this._capabilityPlugins.delete(key);
+                this._inlineCapabilityPlugins.delete(key);
+                if (!this._isDisposingCapabilityPlugins) {
+                    this._syncCapabilityTools();
+                    this._refreshToolRegistry({ activeToolNames: this.getActiveToolNames() });
+                }
+            },
+        };
+        this._capabilityPlugins.set(key, handle);
+        this._syncCapabilityTools();
+        const newToolNames = this._capabilityRuntime.listTools()
+            // First-party domain tools (the S4 split moved every capability to
+            // `agent-forge.plugin.*`; `agent-forge.builtin.*` is the retired
+            // embedded id era) join the active surface under the same readonly
+            // narrowing as runtime-built tools: non-readonlySafe declarations
+            // stay off a readonly session (宪法 §6). Third-party plugins decide
+            // their own mode semantics.
+            .filter((tool) => this._capabilityMode !== "readonly" ||
+            (!tool.source.startsWith("agent-forge.builtin.") && !tool.source.startsWith("agent-forge.plugin.")) ||
+            tool.readonlySafe === true)
+            .map((tool) => tool.name)
+            .filter((name) => !previousToolNames.has(name));
+        this._refreshToolRegistry({
+            activeToolNames: [...this.getActiveToolNames(), ...newToolNames],
+        });
+        return handle;
+    }
+    /** Load an external capability manifest through the same runtime as first-party plugins. */
+    async loadCapabilityPluginManifest(manifestPath, options) {
+        const runtime = this._capabilityRuntime;
+        // v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在
+        if (!runtime)
+            throw new Error("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}`);
+        }
+        const previousToolNames = new Set(runtime.listTools().map((tool) => tool.name));
+        const loaded = await loadCapabilityPluginFromManifest(runtime, resolvedManifestPath, options);
+        return this._trackCapabilityPlugin(resolvedManifestPath, loaded, previousToolNames);
+    }
+    /**
+     * Load an in-memory capability plugin and attach its handle to this session.
+     * This is useful for embedders and deterministic fixtures that already own a
+     * validated manifest/factory pair; reload and dispose will release the handle.
+     */
+    async loadCapabilityPlugin(manifest, factory) {
+        const runtime = this._capabilityRuntime;
+        // v8 ignore next -- capability runtime 恒由 _buildRuntime 创建，dispose 后不再调用，运行期恒存在
+        if (!runtime)
+            throw new Error("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}`);
+        }
+        const previousToolNames = new Set(runtime.listTools().map((tool) => tool.name));
+        const loaded = await loadCapabilityPluginRuntime(runtime, manifest, factory);
+        this._inlineCapabilityPlugins.set(key, { manifest, factory });
+        try {
+            return await this._trackCapabilityPlugin(key, loaded, previousToolNames);
+        }
+        catch (error) {
+            this._inlineCapabilityPlugins.delete(key);
+            throw error;
+        }
+    }
+    /**
+     * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
+     */
+    getAllTools() {
+        return getAllTools(this._internal);
+    }
+    getToolDefinition(name) {
+        return getToolDefinition(this._internal, name);
+    }
+    /**
+     * Set active tools by name.
+     * Only tools in the registry can be enabled. Unknown tool names are ignored.
+     * Also rebuilds the system prompt to reflect the new tool set.
+     * Changes take effect on the next agent turn.
+     */
+    setActiveToolsByName(toolNames) {
+        setActiveToolsByName(this._internal, toolNames);
+    }
+    /** Whether compaction or branch summarization is currently running */
+    get isCompacting() {
+        return (this._autoCompactionAbortController !== undefined ||
+            this._compactionAbortController !== undefined ||
+            this._branchSummaryAbortController !== undefined);
+    }
+    /** All messages including custom types like BashExecutionMessage */
+    get messages() {
+        return this.agent.state.messages;
+    }
+    /** Current steering mode */
+    get steeringMode() {
+        return this.agent.steeringMode;
+    }
+    /** Current follow-up mode */
+    get followUpMode() {
+        return this.agent.followUpMode;
+    }
+    /** Current session file path, or undefined if sessions are disabled */
+    get sessionFile() {
+        return this.sessionManager.getSessionFile();
+    }
+    /** Current session ID */
+    get sessionId() {
+        return this.sessionManager.getSessionId();
+    }
+    /**
+     * /metrics 数据源共享 ref（config 原样透出；observability 插件工厂挂载时写入
+     * plugin.getMetrics、dispose 时置空）。宿主（TUI/RPC）经它惰性解引用接进
+     * 命令 options——空 = 插件未挂载。
+     */
+    get observabilityGetMetricsRef() {
+        return this._observabilityGetMetricsRef;
+    }
+    /** Current session display name, if set */
+    get sessionName() {
+        return this.sessionManager.getSessionName();
+    }
+    /** Durable revision host fact (SessionManager entry sequence) for session boundaries. */
+    getRevision() {
+        return this.sessionManager.getRevision();
+    }
+    /** Scoped models for cycling (from --models flag) */
+    get scopedModels() {
+        return getScopedModels(this._internal);
+    }
+    /** Update scoped models for cycling */
+    setScopedModels(scopedModels) {
+        setScopedModels(this._internal, scopedModels);
+    }
+    /** File-based prompt templates */
+    get promptTemplates() {
+        return this._resourceLoader.getPrompts().prompts;
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _normalizePromptSnippet(text) {
+        return normalizePromptSnippet(text);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _normalizePromptGuidelines(guidelines) {
+        return normalizePromptGuidelines(guidelines);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _rebuildSystemPrompt(toolNames) {
+        return rebuildSystemPrompt(this._internal, toolNames);
+    }
+    // =========================================================================
+    // Prompting
+    // =========================================================================
+    async _runAgentPrompt(messages) {
+        return runPromptLoop(this._internal, messages);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: called from test/coverage-branch-core3-agent-session-misc.test.ts via the private cast
+    _handlePostAgentRun() {
+        return postAgentRun(this._internal);
+    }
+    async _runInputHandlers(text, images, source) {
+        // 输入门（扩展位盘点 A3，对称于工具门 beforeToolCall）：先于
+        // input.received@1——门决定输入是否被接受，received 是"已接受"输入的
+        // 观察事实，被拒输入不派发。链序 = 注册序；改写喂给下一环与后续展开；
+        // block 短路：派发 input.gate.blocked@1（facts only，文本不入信封）后
+        // 以 reason 拒绝本次提交。无钩子时零开销直通（默认行为零变化）。
+        const gateChain = this._capabilityRuntime?.getLoopHookChain("beforeInput") ?? [];
+        let currentText = text;
+        for (const link of gateChain) {
+            const result = await link({ text: currentText, source });
+            if (!result)
+                continue;
+            if (result.block === true) {
+                const reason = typeof result.reason === "string" && result.reason.trim() !== "" ? result.reason : undefined;
+                await dispatchInputGateBlockedLifecycle(this._internal, {
+                    source,
+                    textLength: currentText.length,
+                    reason,
+                });
+                throw new Error(reason === undefined ? "Input rejected by an input gate" : `Input rejected by an input gate: ${reason}`);
+            }
+            if ("text" in result && typeof result.text === "string") {
+                currentText = result.text;
+            }
+        }
+        // input.received@1 is an after-commit observe event: the input text and
+        // images never enter the envelope, and no interception result exists.
+        void dispatchInputReceivedLifecycle(this._internal, { source, textLength: currentText.length });
+        return { text: currentText, images };
+    }
+    /**
+     * Send a prompt to the agent.
+     * - Handles legacy and capability plugin commands immediately, even during streaming
+     * - Expands file-based prompt templates by default
+     * - During streaming, queues via steer() or followUp() based on streamingBehavior option
+     * - Validates model and API key before sending (when not streaming)
+     * @throws Error if streaming and no streamingBehavior specified
+     * @throws Error if no model selected or no API key available (when not streaming)
+     */
+    async prompt(text, options) {
+        if (this._reloadInProgress) {
+            throw new Error("Session reload in progress; prompts are unavailable");
+        }
+        const expandPromptTemplates = options?.expandPromptTemplates ?? true;
+        const preflightResult = options?.preflightResult;
+        let messages;
+        try {
+            // Handle plugin commands first (execute immediately, even during streaming).
+            if (expandPromptTemplates && text.startsWith("/")) {
+                const handled = await this._tryExecuteExtensionCommand(text);
+                if (handled) {
+                    // Extension command executed, no prompt to send
+                    preflightResult?.(true);
+                    return { status: "done" };
+                }
+            }
+            if (this._compactionAbortController !== undefined) {
+                throw new Error("Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.");
+            }
+            // Dispatch the input.gate chain, then the input.received facts (both
+            // before skill/template expansion)
+            const { text: currentText, images: currentImages } = await this._runInputHandlers(text, options?.images, options?.source ?? "interactive");
+            // Expand skill commands (/skill:name args) and prompt templates (/template args)
+            let expandedText = currentText;
+            if (expandPromptTemplates) {
+                expandedText = this._expandSkillCommand(expandedText);
+                expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+            }
+            // If streaming, queue via steer() or followUp() based on option
+            if (this.isStreaming) {
+                if (!options?.streamingBehavior) {
+                    throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
+                }
+                if (options.streamingBehavior === "followUp") {
+                    await this._queueFollowUp(expandedText, currentImages);
+                }
+                else {
+                    await this._queueSteer(expandedText, currentImages);
+                }
+                preflightResult?.(true);
+                return { status: "done" };
+            }
+            // Flush any pending bash and custom messages before the new prompt
+            this._flushPendingBashMessages();
+            this._flushPendingCustomMessages();
+            // Validate model
+            if (!this.model) {
+                throw new Error(formatNoModelSelectedMessage());
+            }
+            const hasConfiguredAuth = this.agent.streamFunction !== streamSimple ||
+                this._modelRuntime.hasConfiguredAuth(this.model.provider) ||
+                (await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;
+            if (!hasConfiguredAuth) {
+                const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
+                if (isOAuth) {
+                    throw new Error(`Authentication failed for "${this.model.provider}". ` +
+                        `Credentials may have expired or network is unavailable. ` +
+                        `Run '/login ${this.model.provider}' to re-authenticate.`);
+                }
+                throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
+            }
+            // Check if we need to compact before sending (catches aborted responses).
+            // The user's new prompt is sent below, so do not call agent.continue() here.
+            const lastAssistant = this._findLastAssistantMessage();
+            if (lastAssistant) {
+                await this._checkCompaction(lastAssistant, false);
+            }
+            // Build messages array (custom message if any, then user message)
+            messages = [];
+            // Add user message
+            const userContent = [{ type: "text", text: expandedText }];
+            if (currentImages) {
+                userContent.push(...currentImages);
+            }
+            messages.push({
+                role: "user",
+                content: userContent,
+                timestamp: Date.now(),
+            });
+            // Inject any pending "nextTurn" messages as context alongside the user message
+            for (const msg of this._pendingNextTurnMessages) {
+                messages.push(msg);
+            }
+            this._pendingNextTurnMessages = [];
+            await dispatchBeforeAgentStartLifecycle(this._internal, (currentImages?.length ?? 0) > 0);
+            // Reset to the base prompt (in case a previous turn had an override),
+            // then apply the before.agent.start@2 candidate transform (capability
+            // channel). A transform yielding a different systemPrompt is the later
+            // writer and wins; a missing registration, a verbatim result, or a
+            // failed delivery keeps the base prompt.
+            this._systemPromptOverride = undefined;
+            this.agent.state.systemPrompt = this._baseSystemPrompt;
+            const capabilitySystemPrompt = await dispatchBeforeAgentStartV2Lifecycle(this._internal, this._baseSystemPrompt, this._baseSystemPromptOptions);
+            if (capabilitySystemPrompt !== undefined) {
+                this._systemPromptOverride = capabilitySystemPrompt;
+                this.agent.state.systemPrompt = capabilitySystemPrompt;
+            }
+        }
+        catch (error) {
+            preflightResult?.(false);
+            throw error;
+        }
+        // v8 ignore next -- try 块内所有不发送路径均已提前 return，messages 必然已赋值
+        if (!messages) {
+            return { status: "done" };
+        }
+        preflightResult?.(true);
+        return this._runAgentPrompt(messages);
+    }
+    /**
+     * Try to execute a capability command. A cross-system name collision with a
+     * prompt template or skill is always an explicit error.
+     */
+    async _tryExecuteExtensionCommand(text) {
+        // Parse command name and args
+        const spaceIndex = text.indexOf(" ");
+        const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+        const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);
+        const runtime = this._capabilityRuntime;
+        if (runtime?.hasCommand(commandName)) {
+            const templateConflict = this.promptTemplates.some((template) => template.name === commandName);
+            const skillName = commandName.startsWith("skill:") ? commandName.slice("skill:".length) : undefined;
+            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}`);
+            }
+        }
+        else {
+            return false;
+        }
+        const source = runtime.listCommands().find(({ definition }) => definition.name === commandName)?.source ?? "unknown";
+        const abortController = new AbortController();
+        this._commandAbortController = abortController;
+        const execute = async () => {
+            const result = await runtime.invokeCommand(commandName, args, {
+                signal: abortController.signal,
+                cwd: this._cwd,
+            });
+            if (result !== undefined) {
+                this._emit({
+                    type: "capability_command_result",
+                    command: commandName,
+                    source,
+                    result,
+                });
+            }
+        };
+        const commandExecution = execute();
+        this._activeCapabilityCommand = commandExecution;
+        try {
+            await commandExecution;
+        }
+        finally {
+            if (this._commandAbortController === abortController)
+                this._commandAbortController = undefined;
+            if (this._activeCapabilityCommand === commandExecution)
+                this._activeCapabilityCommand = undefined;
+        }
+        return true;
+    }
+    /**
+     * Expand skill commands (/skill:name args) to their full content.
+     * Returns the expanded text, or the original text if not a skill command or skill not found.
+     * Emits errors via extension runner if file read fails.
+     */
+    _expandSkillCommand(text) {
+        if (!text.startsWith("/skill:"))
+            return text;
+        const spaceIndex = text.indexOf(" ");
+        const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
+        const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+        const skill = this._getAvailableSkills().find((s) => s.name === skillName);
+        if (!skill)
+            return text; // Unknown skill, pass through
+        try {
+            const content = readFileSync(skill.filePath, "utf-8");
+            const body = stripFrontmatter(content).trim();
+            const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
+            return args ? `${skillBlock}\n\n${args}` : skillBlock;
+        }
+        catch (err) {
+            // Report like command errors do: process log, non-fatal, original text kept.
+            this._hostLogger?.error("session", "skill expansion failed", {
+                ...(this.sessionId === undefined ? {} : { sessionId: this.sessionId }),
+                fields: { skill: skill.name, path: skill.filePath },
+                cause: err,
+            });
+            return text; // Return original on error
+        }
+    }
+    async _queueUserInput(text, images, behavior, source) {
+        const processedInput = await this._runInputHandlers(text, images, source);
+        let expandedText = this._expandSkillCommand(processedInput.text);
+        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        if (behavior === "steer") {
+            await this._queueSteer(expandedText, processedInput.images);
+        }
+        else {
+            await this._queueFollowUp(expandedText, processedInput.images);
+        }
+    }
+    /**
+     * Queue a steering message while the agent is running.
+     * Delivered after the current assistant turn finishes executing its tool calls,
+     * before the next LLM call.
+     * Expands skill commands and prompt templates. Errors on extension commands.
+     * @param images Optional image attachments to include with the message
+     * @param options Input source; defaults to interactive
+     * @throws Error if text is an extension command
+     */
+    async steer(text, images, options) {
+        await this._queueUserInput(text, images, "steer", options?.source ?? "interactive");
+    }
+    /**
+     * Queue a follow-up message to be processed after the agent finishes.
+     * Delivered only when agent has no more tool calls or steering messages.
+     * Expands skill commands and prompt templates. Errors on extension commands.
+     * @param images Optional image attachments to include with the message
+     * @param options Input source; defaults to interactive
+     * @throws Error if text is an extension command
+     */
+    async followUp(text, images, options) {
+        await this._queueUserInput(text, images, "followUp", options?.source ?? "interactive");
+    }
+    /**
+     * Internal: Queue a steering message (already expanded, no extension command check).
+     */
+    async _queueSteer(text, images) {
+        this._steeringMessages.push(text);
+        this._emitQueueUpdate();
+        const content = [{ type: "text", text }];
+        if (images) {
+            content.push(...images);
+        }
+        this.agent.steer({
+            role: "user",
+            content,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Internal: Queue a follow-up message (already expanded, no extension command check).
+     */
+    async _queueFollowUp(text, images) {
+        this._followUpMessages.push(text);
+        this._emitQueueUpdate();
+        const content = [{ type: "text", text }];
+        if (images) {
+            content.push(...images);
+        }
+        this.agent.followUp({
+            role: "user",
+            content,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Send a custom message to the session. Creates a CustomMessageEntry.
+     *
+     * Handles four cases:
+     * - Streaming: queues message, 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 + no trigger: appends to state/session, no turn
+     *
+     * @param message Custom message with customType, content, display, details
+     * @param options.triggerTurn If true and not streaming, triggers a new LLM turn
+     * @param options.deliverAs Delivery mode: "steer", "followUp", or "nextTurn"
+     */
+    async sendCustomMessage(message, options) {
+        const appMessage = {
+            role: "custom",
+            customType: message.customType,
+            // Untyped extensions can pass null/missing content; normalize at ingestion.
+            content: message.content ?? [],
+            display: message.display,
+            details: message.details,
+            timestamp: Date.now(),
+        };
+        if (options?.deliverAs === "nextTurn") {
+            this._pendingNextTurnMessages.push(appMessage);
+        }
+        else if (this.isStreaming && options?.triggerTurn !== false) {
+            if (options?.deliverAs === "followUp") {
+                this.agent.followUp(appMessage);
+            }
+            else {
+                this.agent.steer(appMessage);
+            }
+        }
+        else if (options?.triggerTurn) {
+            await this._runAgentPrompt(appMessage);
+        }
+        else if (this.isStreaming) {
+            // Appending now would put the message between an assistant tool call and its
+            // result, which providers that validate message order reject on replay. Defer
+            // to the end of the turn. Nothing is emitted yet: message events must not
+            // describe messages the session tree does not contain.
+            this._pendingCustomMessages.push(appMessage);
+        }
+        else {
+            this._appendCustomMessage(appMessage);
+        }
+    }
+    _appendCustomMessage(appMessage) {
+        this.agent.state.messages.push(appMessage);
+        this.sessionManager.appendCustomMessageEntry(appMessage.customType, appMessage.content, appMessage.display, appMessage.details);
+        this._emit({ type: "message_start", message: appMessage });
+        this._emit({ type: "message_end", message: appMessage });
+    }
+    /**
+     * Append custom messages queued while the agent was running.
+     * Called once the current turn's tool results are in agent state and session history.
+     */
+    _flushPendingCustomMessages() {
+        if (this._pendingCustomMessages.length === 0)
+            return;
+        const pending = this._pendingCustomMessages;
+        this._pendingCustomMessages = [];
+        for (const appMessage of pending) {
+            this._appendCustomMessage(appMessage);
+        }
+    }
+    /**
+     * Send a user message to the agent. Always triggers a turn.
+     * When the agent is streaming, use deliverAs to specify how to queue the message.
+     *
+     * @param content User message content (string or content array)
+     * @param options.deliverAs Delivery mode when streaming: "steer" or "followUp"
+     * @param options.expandPromptTemplates Whether to dispatch extension commands and expand skill commands and prompt templates. Default: false.
+     */
+    async sendUserMessage(content, options) {
+        // Normalize content to text string + optional images
+        let text;
+        let images;
+        if (typeof content === "string") {
+            text = content;
+        }
+        else {
+            const textParts = [];
+            images = [];
+            for (const part of content) {
+                if (part.type === "text") {
+                    textParts.push(part.text);
+                }
+                else {
+                    images.push(part);
+                }
+            }
+            text = textParts.join("\n");
+            if (images.length === 0)
+                images = undefined;
+        }
+        await this.prompt(text, {
+            expandPromptTemplates: options?.expandPromptTemplates ?? false,
+            streamingBehavior: options?.deliverAs,
+            images,
+            source: "extension",
+        });
+    }
+    /**
+     * Clear all queued messages and return them.
+     * Useful for restoring to editor when user aborts.
+     * @returns Object with steering and followUp arrays
+     */
+    clearQueue() {
+        const steering = [...this._steeringMessages];
+        const followUp = [...this._followUpMessages];
+        this._steeringMessages = [];
+        this._followUpMessages = [];
+        this.agent.clearAllQueues();
+        this._emitQueueUpdate();
+        return { steering, followUp };
+    }
+    /** Number of pending messages (includes both steering and follow-up) */
+    get pendingMessageCount() {
+        return this._steeringMessages.length + this._followUpMessages.length;
+    }
+    /** Get pending steering messages (read-only) */
+    getSteeringMessages() {
+        return this._steeringMessages;
+    }
+    /** Get pending follow-up messages (read-only) */
+    getFollowUpMessages() {
+        return this._followUpMessages;
+    }
+    get resourceLoader() {
+        return this._resourceLoader;
+    }
+    /**
+     * Why the active turn was aborted, following codex's TurnAbortReason
+     * (protocol.rs:4173). The interruption marker's visible text stays fixed;
+     * the reason rides the marker `details` for hosts and plugins.
+     */
+    async abort(reason) {
+        this._pendingAbortReason = reason ?? "interrupted";
+        this._lastAbortReason = this._pendingAbortReason;
+        // 级联取消子 agent 任务（D-044 §4.2）：fire-and-forget，不阻塞父会话自身的 abort。
+        this._agentTaskScopeAbortController.abort(reason ?? "interrupted");
+        try {
+            await this._abortInternal();
+            this._appendTurnInterruptedMarker();
+        }
+        finally {
+            this._pendingAbortReason = undefined;
+            // epoch 刷新：旧 signal 已 spent，刷新后后续回合提交的任务绑到新信号，不会被立即取消。
+            this._agentTaskScopeAbortController = new AbortController();
+        }
+    }
+    /**
+     * Abort without the interruption marker; used by internal flows (compaction,
+     * teardown) that abort for their own bookkeeping. Takes no reason: the abort
+     * reason only exists where the marker is written.
+     */
+    async _abortInternal() {
+        this.abortRetry();
+        this._policyDecisionAbortController?.abort("session aborted");
+        this._commandAbortController?.abort("session aborted");
+        this.abortCompaction();
+        this.abortBranchSummary();
+        this.abortBash();
+        this.agent.abort();
+        await this.waitForIdle();
+    }
+    /**
+     * Append a model-visible marker after an abort that actually cut a turn
+     * short. transform-messages drops the aborted assistant message on replay,
+     * so without this marker the model has no way to learn that the
+     * interruption happened. Tool calls skipped mid-batch already carry their
+     * own persisted error results; this covers the streaming-interrupt case.
+     * The text is intentionally fixed (codex keeps INTERRUPTED_GUIDANCE stable
+     * across reasons); the abort reason rides `details` for host consumers.
+     */
+    _appendTurnInterruptedMarker() {
+        const messages = this.agent.state.messages;
+        const last = messages[messages.length - 1];
+        if (last?.role === "custom" && last.customType === "turn-interrupted") {
+            return;
+        }
+        let lastAssistantAborted = false;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const message = messages[i];
+            if (message.role === "assistant") {
+                lastAssistantAborted = message.stopReason === "aborted";
+                break;
+            }
+        }
+        if (!lastAssistantAborted) {
+            return;
+        }
+        this._appendCustomMessage({
+            role: "custom",
+            customType: "turn-interrupted",
+            content: "The previous turn was interrupted by the user before it completed.",
+            display: false,
+            details: this._pendingAbortReason === undefined ? undefined : { reason: this._pendingAbortReason },
+            timestamp: Date.now(),
+        });
+    }
+    async _abortActiveCapabilityCommand(reason) {
+        this._commandAbortController?.abort(reason);
+        await this._activeCapabilityCommand;
+    }
+    /**
+     * Stop every operation that can still mutate session state before a reload
+     * replaces the runtime. This deliberately does not call `abort()`: reload
+     * must also wait for queued compaction and branch-summary work, while a
+     * compaction itself calls `abort()` as part of its normal entry path.
+     */
+    async _cancelAndDrainForReload() {
+        this.abortRetry();
+        this._policyDecisionAbortController?.abort("session reloaded");
+        this._commandAbortController?.abort("session reloaded");
+        this.abortCompaction();
+        this.abortBranchSummary();
+        this.abortBash();
+        this.agent.abort();
+        await Promise.allSettled([
+            this._activeCapabilityCommand,
+            this._activeCompactionPromise,
+            this._branchSummaryPromise,
+            this._activeContextTransition,
+            ...this._activeBashPromises,
+            this.waitForIdle(),
+        ].filter((operation) => operation !== undefined));
+        // The tail includes compactions that were enqueued just before the reload
+        // barrier. They must settle before the old runtime is revoked.
+        await this._compactionQueue.catch(() => undefined);
+    }
+    async waitForIdle() {
+        if (this.isIdle) {
+            return;
+        }
+        await this._getIdleWaitPromise();
+    }
+    // =========================================================================
+    // Model Management
+    // =========================================================================
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    async _emitModelSelect(nextModel, previousModel, source) {
+        return emitModelSelect(this._internal, nextModel, previousModel, source);
+    }
+    /**
+     * Set model directly.
+     * Validates that auth is configured and saves to the session transcript.
+     * Persists to global defaults only when options.persist is true.
+     * @throws Error if no auth is configured for the model
+     */
+    async setModel(model, options = {}) {
+        return setModel(this._internal, model, options);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _addPersistedDefaultToNonEmptyScope(model) {
+        addPersistedDefaultToNonEmptyScope(this._internal, model);
+    }
+    /**
+     * Cycle to next/previous model.
+     * Uses scoped models (from --models flag) if available, otherwise all available models.
+     * @param direction - "forward" (default) or "backward"
+     * @returns The new model info, or undefined if only one model available
+     */
+    async cycleModel(direction = "forward", options = {}) {
+        return cycleModel(this._internal, direction, options);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    async _cycleScopedModel(direction, options) {
+        return cycleScopedModel(this._internal, direction, options);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    async _cycleAvailableModel(direction, options) {
+        return cycleAvailableModel(this._internal, direction, options);
+    }
+    // =========================================================================
+    // Thinking Level Management
+    // =========================================================================
+    /**
+     * Set thinking level.
+     * Clamps to model capabilities based on available thinking levels.
+     * Saves the clamped level to the session transcript only if the level actually changes.
+     * Persists the requested level to global defaults only when options.persist is true.
+     */
+    setThinkingLevel(level, options = {}) {
+        const availableLevels = this.getAvailableThinkingLevels();
+        const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);
+        // Only persist if actually changing
+        const previousLevel = this.agent.state.thinkingLevel;
+        const isChanging = effectiveLevel !== previousLevel;
+        this.agent.state.thinkingLevel = effectiveLevel;
+        if (options.persist) {
+            this.settingsManager.setDefaultThinkingLevel(level);
+        }
+        if (isChanging) {
+            this.sessionManager.appendThinkingLevelChange(effectiveLevel);
+            this._emit({ type: "thinking_level_changed", level: effectiveLevel });
+            void dispatchThinkingLevelSelectLifecycle(this._internal, effectiveLevel, previousLevel);
+        }
+    }
+    /**
+     * Cycle to next thinking level.
+     * @returns New level, or undefined if model doesn't support thinking
+     */
+    cycleThinkingLevel(options = {}) {
+        if (!this.supportsThinking())
+            return undefined;
+        const levels = this.getAvailableThinkingLevels();
+        const currentIndex = levels.indexOf(this.thinkingLevel);
+        const nextIndex = (currentIndex + 1) % levels.length;
+        const nextLevel = levels[nextIndex];
+        this.setThinkingLevel(nextLevel, options);
+        return nextLevel;
+    }
+    /**
+     * Get available thinking levels for current model.
+     * The provider will clamp to what the specific model supports internally.
+     */
+    getAvailableThinkingLevels() {
+        if (!this.model)
+            return [...THINKING_LEVEL_OPTIONS];
+        return getSupportedThinkingLevels(this.model);
+    }
+    /**
+     * Check if current model supports thinking/reasoning.
+     */
+    supportsThinking() {
+        return !!this.model?.reasoning;
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _getThinkingLevelForModelSwitch(targetModel, explicitLevel) {
+        return getThinkingLevelForModelSwitch(this._internal, targetModel, explicitLevel);
+    }
+    _clampThinkingLevel(level, _availableLevels) {
+        return this.model ? clampThinkingLevel(this.model, level) : "off";
+    }
+    // =========================================================================
+    // Queue Mode Management
+    // =========================================================================
+    syncQueueModesFromSettings() {
+        this.agent.steeringMode = this.settingsManager.getSteeringMode();
+        this.agent.followUpMode = this.settingsManager.getFollowUpMode();
+    }
+    /**
+     * Set steering message mode.
+     * Saves to settings.
+     */
+    setSteeringMode(mode) {
+        this.agent.steeringMode = mode;
+        this.settingsManager.setSteeringMode(mode);
+    }
+    /**
+     * Set follow-up message mode.
+     * Saves to settings.
+     */
+    setFollowUpMode(mode) {
+        this.agent.followUpMode = mode;
+        this.settingsManager.setFollowUpMode(mode);
+    }
+    // =========================================================================
+    // Compaction
+    // =========================================================================
+    /** Queue compaction work so canonical commit and runtime projection stay ordered. */
+    _enqueueCompaction(operation) {
+        return enqueueCompaction(this._internal, operation);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _observeLifecycleDeliveryError(error, extensionPath, event) {
+        observeLifecycleDeliveryError(this._internal, error, extensionPath, event);
+    }
+    /**
+     * Manually compact the session context.
+     *
+     * This is the manual entry point used by `/compact`, RPC, and extensions. It is
+     * separate from automatic threshold/overflow compaction, which enters through
+     * `_checkCompaction()` and `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, both paths use the selected compaction policy
+     * unless the hook cancels or supplies a custom result, then commit the result
+     * against the revision captured for that branch.
+     *
+     * Aborts the current agent operation first. Manual compaction never retries or
+     * continues the interrupted agent turn.
+     *
+     * @param customInstructions Optional instructions for the compaction summary
+     */
+    async compact(customInstructions) {
+        if (this._reloadInProgress) {
+            throw new Error("Session reload in progress; compaction is unavailable");
+        }
+        return this._enqueueCompaction(() => this._compactInternal(customInstructions));
+    }
+    _compactInternal(customInstructions) {
+        return compactInternal(this._internal, customInstructions);
+    }
+    /**
+     * Cancel in-progress compaction (manual or auto).
+     */
+    abortCompaction() {
+        this._compactionAbortController?.abort();
+        this._autoCompactionAbortController?.abort();
+    }
+    /**
+     * Cancel in-progress branch summarization.
+     */
+    abortBranchSummary() {
+        this._branchSummaryAbortController?.abort();
+    }
+    /**
+     * Dispatch automatic compaction after `agent_end` or before prompt submission.
+     * Manual compaction does not call this method; it enters through `compact()`.
+     *
+     * Automatic cases:
+     * 1. Overflow with retry: a context-overflow error or recoverable length stop;
+     *    remove the failed assistant message, compact, and retry the turn once.
+     * 2. Overflow without retry: a successful response exceeded the configured
+     *    context window; compact but preserve the completed response.
+     * 3. Threshold without retry: valid or estimated context usage crossed the
+     *    configured threshold; compact without retrying the completed response.
+     *
+     * Each case calls `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, that method calls the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * @param assistantMessage The assistant message to check
+     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
+     */
+    _checkCompaction(assistantMessage, skipAbortedCheck = true, signal) {
+        return checkCompaction(this._internal, assistantMessage, skipAbortedCheck, signal);
+    }
+    /**
+     * Execute threshold or overflow compaction. Manual compaction uses
+     * `AgentSession.compact()` instead. Both paths use the selected compaction
+     * policy after preparation and extension interception, then commit against the
+     * branch revision captured before asynchronous work.
+     *
+     * @param reason Automatic trigger selected by `_checkCompaction()`
+     * @param willRetry Whether to continue the interrupted turn after overflow compaction
+     * @returns Whether the post-run loop should call `agent.continue()`
+     */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _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/
+     * themes). Hosts await this once after constructing (or rebinding to) a
+     * session, before the first prompt.
+     */
+    async startSession() {
+        await dispatchSessionStartLifecycle(this._internal, this._sessionStartEvent.reason, this._sessionStartEvent.previousSessionFile);
+        await this.extendResourcesFromExtensions(this._sessionStartEvent.reason === "reload" ? "reload" : "startup");
+    }
+    async extendResourcesFromExtensions(reason) {
+        return extendResourcesFromExtensions(this._internal, reason);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    buildExtensionResourcePaths(entries) {
+        return buildExtensionResourcePaths(this._internal, entries);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    getExtensionSourceLabel(extensionPath) {
+        return getExtensionSourceLabel(extensionPath);
+    }
+    _refreshToolRegistry(options) {
+        refreshToolRegistry(this._internal, options);
+    }
+    _syncCapabilityTools() {
+        syncCapabilityTools(this._internal);
+    }
+    _getCapabilitySkills() {
+        return getCapabilitySkills(this._internal);
+    }
+    _getAvailableSkills() {
+        const capabilitySkills = this._getCapabilitySkills();
+        return capabilitySkills.length > 0 ? capabilitySkills : this._resourceLoader.getSkills().skills;
+    }
+    _validateCapabilitySkillConflicts() {
+        validateCapabilitySkillConflicts(this._internal);
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _refreshBootstrapSkills() {
+        return refreshBootstrapSkills(this._internal);
+    }
+    async _disposeCapabilityPlugins() {
+        const handles = Array.from(this._capabilityPlugins.values());
+        this._isDisposingCapabilityPlugins = true;
+        const errors = [];
+        try {
+            for (const handle of handles) {
+                try {
+                    await handle.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+        }
+        finally {
+            this._isDisposingCapabilityPlugins = false;
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, "Capability plugin disposal failed");
+    }
+    /**
+     * 插件日志记录 → 宿主进程日志（会话轨迹第 2 期，设计 §7.2）：HostLogger 是
+     * debug/info/warn/error 四方法（无泛用 log），按记录级别映射调用；级别门槛由
+     * logger 自身过滤（"级别沿用宿主日志级别门槛"）。src 用 pluginId（宿主日志的
+     * 来源标记位）；sessionId 随行。LoggerRecord 当前无已填充的 correlationId
+     * （recordLog 不写该字段），不编造 traceId。
+     */
+    _forwardLogRecordToHost(record) {
+        const hostLogger = this._hostLogger;
+        if (!hostLogger)
+            return;
+        const context = {
+            ...(record.sessionId === undefined ? {} : { sessionId: record.sessionId }),
+            ...(record.fields === undefined ? {} : { fields: record.fields }),
+            ...(record.cause === undefined ? {} : { cause: record.cause }),
+        };
+        switch (record.level) {
+            case "debug":
+                hostLogger.debug(record.pluginId, record.message, context);
+                break;
+            case "info":
+                hostLogger.info(record.pluginId, record.message, context);
+                break;
+            case "warn":
+                hostLogger.warn(record.pluginId, record.message, context);
+                break;
+            case "error":
+                hostLogger.error(record.pluginId, record.message, context);
+                break;
+        }
+    }
+    _buildRuntime(options) {
+        // 对齐 context transition 控制器的替换模式：runtime 重建时刷新 parent
+        // 取消栅栏，防止 reload 后新 runtime 的任务绑到旧 spent 信号被立即取消。
+        this._agentTaskScopeAbortController = new AbortController();
+        const autoResizeImages = this.settingsManager.getImageAutoResize();
+        const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
+        const shellPath = this.settingsManager.getShellPath();
+        this._capabilityRuntime = createCapabilityRuntime({
+            apiVersion: EXPERIMENTAL_PUBLIC_API_VERSION,
+            mode: this._capabilityMode,
+            // D-075 S4 second batch: the host agent dir rides the public
+            // HostCapabilities so disk-state plugins resolve their config files.
+            ...(this._agentDir === undefined ? {} : { agentDir: this._agentDir }),
+            // D-075 S4 third batch: the subagent delegation host services ride
+            // the public HostCapabilities (communication wiring, turn-scoped
+            // digest/correlation context, suite role associations) — the same
+            // facts the embedded builtin used to receive as constructor options.
+            ...(this._communication === undefined ? {} : { communication: this._communication }),
+            ...(this._turnContext === undefined ? {} : { turnContext: this._turnContext }),
+            ...(this._roleAssociations === undefined ? {} : { roleAssociations: this._roleAssociations }),
+            // D-075 S4 fourth batch: the memory storage injection face rides
+            // the public HostCapabilities — the first-party memory plugin
+            // binds these components in place of its built-in defaults.
+            ...(this._memoryStorage === undefined ? {} : { memoryStorage: this._memoryStorage }),
+            features: [
+                "tools",
+                "skills",
+                "logger-v1",
+                "diagnostics-v1",
+                "plugin-state-v1",
+                "runtime-inspector-v1",
+                "retry-policy",
+                "compaction-policy",
+                "overflow-policy",
+                "events",
+                "operations",
+                "rpc",
+                "context",
+                "provider-headers",
+                "credentials",
+                "commands",
+                "session",
+                "session-revision-v1",
+                "session-export",
+                "output-artifacts",
+                ...(this._agentTaskAdapter || this._agentSessionReader || this._agentSessionLister ? ["agents"] : []),
+                ...(this._agentTaskResults ? ["agent-result-replay-v1"] : []),
+                ...(this._agentComposition ? ["agent-composition-v1"] : []),
+                ...(this._interactionHost ? ["interaction"] : []),
+            ],
+            transports: ["in-process"],
+        }, {
+            ...(this._agentTaskAdapter ? { agents: this._agentTaskAdapter } : {}),
+            ...(this._agentTaskResults ? { agentResults: this._agentTaskResults } : {}),
+            ...(this._agentSessionReader ? { agentSessionReader: this._agentSessionReader } : {}),
+            ...(this._agentSessionLister ? { agentSessionLister: this._agentSessionLister } : {}),
+            ...(this._agentComposition ? { composition: this._agentComposition } : {}),
+            ...(this._interactionHost ? { interaction: this._interactionHost } : {}),
+            parentSignal: () => this._agentTaskScopeAbortController.signal,
+            ...(this._traceService === undefined ? {} : { trace: this._traceService }),
+            ...(this._modelRuntime
+                ? {
+                    modelRuntime: {
+                        getModelFacts: () => {
+                            const model = this.agent.state.model;
+                            if (!model)
+                                return undefined;
+                            return {
+                                provider: model.provider,
+                                id: model.id,
+                                contextWindow: model.contextWindow ?? 0,
+                                maxTokens: model.maxTokens ?? 0,
+                                reasoning: model.reasoning ?? false,
+                            };
+                        },
+                        invoke: async (input, options) => {
+                            const model = this.agent.state.model;
+                            if (!model)
+                                throw new Error("No model is set on this session's agent");
+                            const authResult = await this._modelRuntime.getAuth(model, {
+                                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                            });
+                            const requestModel = authResult?.auth.baseUrl
+                                ? { ...model, baseUrl: authResult.auth.baseUrl }
+                                : model;
+                            const context = {
+                                ...(input.systemPrompt === undefined ? {} : { systemPrompt: input.systemPrompt }),
+                                messages: [
+                                    {
+                                        role: "user",
+                                        content: [{ type: "text", text: input.prompt }],
+                                        timestamp: Date.now(),
+                                    },
+                                ],
+                            };
+                            const requestOptions = {
+                                ...(input.maxTokens === undefined ? {} : { maxTokens: input.maxTokens }),
+                                ...(input.thinkingLevel && input.thinkingLevel !== "off" && model.reasoning
+                                    ? { reasoning: input.thinkingLevel }
+                                    : {}),
+                                ...(authResult?.auth.apiKey === undefined ? {} : { apiKey: authResult.auth.apiKey }),
+                                ...(authResult?.auth.headers === undefined ? {} : { headers: authResult.auth.headers }),
+                                ...(authResult?.env === undefined ? {} : { env: authResult.env }),
+                                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                            };
+                            const stream = await this.agent.streamFunction(requestModel, context, requestOptions);
+                            const response = await stream.result();
+                            if (response.stopReason === "aborted")
+                                return { version: 1, status: "aborted" };
+                            if (response.stopReason === "error")
+                                return {
+                                    version: 1,
+                                    status: "failed",
+                                    error: {
+                                        code: "summary_provider_error",
+                                        message: response.errorMessage ?? "Unknown error",
+                                    },
+                                };
+                            if (response.stopReason === "length")
+                                return {
+                                    version: 1,
+                                    status: "failed",
+                                    error: { code: "summary_length_cap", message: "generation hit the token cap" },
+                                };
+                            const text = response.content
+                                .filter((block) => block.type === "text")
+                                .map((block) => block.text)
+                                .join("");
+                            return { version: 1, status: "completed", text, usage: response.usage };
+                        },
+                    },
+                }
+                : {}),
+            onOutputArtifactCommit: this._dispatchOutputArtifactCommit,
+            // 工具表变更钩子：runtime 侧任何工具表变更（含同名替换/恢复）后，先重
+            // 同步会话基础工具定义，再刷新可见注册表——运行期注册/替换/恢复随即
+            // 对 getToolDefinition 与模型面可见、可被 setActiveToolsByName 激活；
+            // 不自动加入活动集（激活权留给调用方）。两道门（见
+            // _suspendToolRegistryHookRefresh/_toolRegistryHookReady 的注释）内
+            // 整体跳过，由构造尾部与装卸边界兜底。
+            onToolRegistryChange: () => {
+                if (this._suspendToolRegistryHookRefresh || !this._toolRegistryHookReady)
+                    return;
+                this._syncCapabilityTools();
+                this._refreshToolRegistry({ activeToolNames: this.getActiveToolNames() });
+            },
+            // 运行时 invoke 面传给工具 execute 的第二参上下文（cwd 与命令面同源）。
+            toolExecutionContext: { cwd: this._cwd },
+            // 插件日志宿主 sink（会话轨迹第 2 期，设计 §7.2）：先经装配域共享 ref
+            // 镜像进轨迹（observability 插件工厂写入，空 = 无镜像），再按级别落
+            // 宿主进程日志（无 hostLogger 时为 no-op）。runtime 侧对回调抛错自吞，
+            // 这里不再叠加容错。
+            ...(this._hostLogger === undefined && this._logRecordMirrorRef === undefined
+                ? {}
+                : {
+                    onLogRecord: (record) => {
+                        this._logRecordMirrorRef?.current?.(record);
+                        this._forwardLogRecordToHost(record);
+                    },
+                }),
+            credentials: {
+                resolve: async ({ providerId, minValidityMs, signal }) => {
+                    const result = await this._modelRuntime.getAuth(providerId, {
+                        signal,
+                        ...(minValidityMs === undefined ? {} : { minOAuthValidityMs: minValidityMs }),
+                    });
+                    if (!result)
+                        return undefined;
+                    return {
+                        ...(result.auth.apiKey === undefined ? {} : { apiKey: result.auth.apiKey }),
+                        headers: { ...(result.auth.headers ?? {}) },
+                        ...(result.auth.baseUrl === undefined ? {} : { baseUrl: result.auth.baseUrl }),
+                        ...(result.source === undefined ? {} : { source: result.source }),
+                    };
+                },
+            },
+            session: this.getSessionAPI(),
+        });
+        // Bootstrap 插件家族（宪法 §1/§7）：随产品内嵌、默认安装，但必须可禁用且
+        // 独立失败——任一件装载抛错走 D-028 结构化 rejection + 进程日志，不阻断
+        // 会话构造，也不伪装成内核失败。
+        const disabledBootstrap = this._disabledBootstrapPlugins;
+        const capabilityRuntime = this._capabilityRuntime;
+        const installBootstrap = (pluginId, install) => {
+            if (disabledBootstrap?.includes(pluginId))
+                return;
+            try {
+                install();
+            }
+            catch (error) {
+                this._hostLogger?.error("session", "bootstrap plugin load failed", {
+                    fields: { pluginId },
+                    cause: error,
+                });
+                void capabilityRuntime
+                    .recordPluginRejection(Object.freeze({
+                    code: "plugin_load_failed",
+                    manifestPath: "<embedded>",
+                    pluginId,
+                    message: error instanceof Error ? error.message : String(error),
+                }))
+                    .catch(() => {
+                    // Rejection visibility must never fail the remaining startup path.
+                });
+            }
+        };
+        installBootstrap(BOOTSTRAP_LIFECYCLE_PLUGIN_ID, () => installBootstrapLifecycle(capabilityRuntime));
+        installBootstrap(BOOTSTRAP_AGENT_LOOP_PLUGIN_ID, () => installBootstrapAgentLoop(capabilityRuntime, this._createLoopWiring()));
+        installBootstrap(BOOTSTRAP_TOOLS_PLUGIN_ID, () => installSessionBootstrapTools(capabilityRuntime, this._cwd, {
+            read: { autoResizeImages },
+            bash: { commandPrefix: shellCommandPrefix, shellPath },
+            mode: this._capabilityMode,
+        }, this._baseToolsOverride));
+        this._syncCapabilityTools();
+        installBootstrap(BOOTSTRAP_SKILLS_PLUGIN_ID, () => {
+            // refreshBootstrapSkills keys off this handle to decide refresh vs
+            // install; dropping it would double-install on the first refresh.
+            this._bootstrapSkillsHandle = installSessionBootstrapSkills(capabilityRuntime, this._resourceLoader.getSkills().skills);
+            return this._bootstrapSkillsHandle;
+        });
+        installBootstrap(BOOTSTRAP_RETRY_PLUGIN_ID, () => installBootstrapRetryPolicy(capabilityRuntime));
+        installBootstrap(BOOTSTRAP_OVERFLOW_PLUGIN_ID, () => installBootstrapOverflowPolicy(capabilityRuntime));
+        installBootstrap(BOOTSTRAP_COMPACTION_PLUGIN_ID, () => installBootstrapCompactionPolicy(capabilityRuntime));
+        installBootstrap(BOOTSTRAP_BRANCH_SUMMARY_PLUGIN_ID, () => installBootstrapBranchSummaryPolicy(capabilityRuntime));
+        // The embedded builtin capability channel (方案系统 M3) is retired: the
+        // last embedded capability (memory) moved to its own package in D-075
+        // S4 fourth batch, so every suite capability now assembles through the
+        // installed-plugin path (session.loadCapabilityPluginManifest) and
+        // nothing loads here.
+        this._syncCapabilityTools();
+        // First-party capability activation (统一修复轮 B): readonly capabilityMode
+        // narrows the first-party tool face by the OWNING PLUGIN's declaration
+        // (宪法 §6): first-party tools stay on the active surface only when their
+        // definition declares `readonlySafe`. The first-party domain covers both
+        // naming eras — the retired embedded `agent-forge.builtin.*` ids and the
+        // `agent-forge.plugin.*` package ids every capability moved to in the S4
+        // split (D-075). The plugins stay installed — protocol entries, RPC
+        // methods, and events are untouched; only the model tool face is narrowed.
+        // Third-party plugin tools keep their existing semantics: whether they
+        // respect the mode is the plugin's own declaration and the user's choice.
+        const builtinToolNames = this._capabilityRuntime
+            .listTools()
+            .filter((tool) => this._capabilityMode !== "readonly" ||
+            !tool.source.startsWith("agent-forge.builtin.") ||
+            tool.readonlySafe === true)
+            .filter((tool) => this._capabilityMode !== "readonly" ||
+            !tool.source.startsWith("agent-forge.plugin.") ||
+            tool.readonlySafe === true)
+            .map((tool) => tool.name);
+        const defaultActiveToolNames = this._baseToolsOverride
+            ? Object.keys(this._baseToolsOverride)
+            : this._capabilityMode === "readonly"
+                ? // Derive from declarations: the readonly install path registers
+                    // exactly the declared-safe definitions, so the kernel carries no
+                    // per-tool name knowledge for the readonly face.
+                    this._capabilityRuntime
+                        .listTools()
+                        .filter((tool) => tool.readonlySafe)
+                        .map((tool) => tool.name)
+                : ["read", "bash", "edit", "write"];
+        // Builtin capability tools join the active surface like externally
+        // loaded plugin tools do (_trackCapabilityPlugin); the allowlist /
+        // denylist filters below still gate them.
+        const baseActiveToolNames = [...(options.activeToolNames ?? defaultActiveToolNames), ...builtinToolNames];
+        this._refreshToolRegistry({
+            activeToolNames: baseActiveToolNames,
+            includeAllExtensionTools: options.includeAllExtensionTools,
+        });
+        // Runtime 装配与首次同步（上方显式 sync + refresh）完成后，工具表变更钩子
+        // 才开始驱动会话侧同步；构造期通知全部跳过（见 _toolRegistryHookReady）。
+        this._toolRegistryHookReady = true;
+    }
+    async reload(options) {
+        if (this._reloadInProgress)
+            throw new Error("Session reload is already in progress");
+        this._reloadInProgress = true;
+        this._beginContextTransitionFence();
+        this._bashEpoch += 1;
+        let committedGeneration;
+        try {
+            await this._cancelAndDrainForReload();
+            const oldCapabilityRuntime = this._capabilityRuntime;
+            const contextStrategyName = this._contextStrategyName;
+            let contextSnapshot;
+            let hasContextSnapshot = false;
+            if (contextStrategyName) {
+                if (!oldCapabilityRuntime?.hasContextStrategy(contextStrategyName)) {
+                    throw new Error(`Configured context strategy is not registered: ${contextStrategyName}`);
+                }
+                contextSnapshot = await oldCapabilityRuntime.snapshotContext(contextStrategyName, this._copyContextMessages(this.agent.state.messages, contextStrategyName, "input"), { reason: "reload", sessionId: this.sessionId });
+                hasContextSnapshot = true;
+            }
+            const capabilityPluginPaths = Array.from(this._capabilityPlugins.keys()).filter((key) => !this._inlineCapabilityPlugins.has(key));
+            const inlineCapabilityPlugins = Array.from(this._inlineCapabilityPlugins.values());
+            await this._disposeCapabilityPlugins();
+            oldCapabilityRuntime?.revokeAllAPIs();
+            await oldCapabilityRuntime?.disposeAll();
+            const agentTaskAdapter = this._agentTaskAdapter;
+            await agentTaskAdapter?.dispose?.();
+            const interactionHost = this._interactionHost;
+            await interactionHost?.dispose?.();
+            await this._bootstrapToolsHandle?.dispose();
+            this._bootstrapToolsHandle = undefined;
+            await this._bootstrapSkillsHandle?.dispose();
+            this._bootstrapSkillsHandle = undefined;
+            await this._bootstrapRetryHandle?.dispose();
+            this._bootstrapRetryHandle = undefined;
+            await this._bootstrapOverflowHandle?.dispose();
+            this._bootstrapOverflowHandle = undefined;
+            await this._bootstrapCompactionHandle?.dispose();
+            this._bootstrapCompactionHandle = undefined;
+            await this._bootstrapBranchSummaryHandle?.dispose();
+            this._bootstrapBranchSummaryHandle = undefined;
+            await this._bootstrapAgentLoopHandle?.dispose();
+            this._bootstrapAgentLoopHandle = undefined;
+            await this._bootstrapLifecycleHandle?.dispose();
+            this._bootstrapLifecycleHandle = undefined;
+            await this.settingsManager.reload();
+            this.syncQueueModesFromSettings();
+            // NOTE: reload must not call resetApiProviders(). The API provider
+            // registry is process-global shared state; one session reloading must
+            // never silently unregister providers owned by other sessions or hosts.
+            await this._resourceLoader.reload();
+            this._buildRuntime({
+                activeToolNames: this.getActiveToolNames(),
+                includeAllExtensionTools: true,
+            });
+            for (const manifestPath of capabilityPluginPaths) {
+                await this.loadCapabilityPluginManifest(manifestPath);
+            }
+            for (const { manifest, factory } of inlineCapabilityPlugins) {
+                await this.loadCapabilityPlugin(manifest, factory);
+            }
+            if (contextStrategyName && hasContextSnapshot) {
+                const runtime = this._capabilityRuntime;
+                if (!runtime?.hasContextStrategy(contextStrategyName)) {
+                    throw new Error(`Configured context strategy is not registered after reload: ${contextStrategyName}`);
+                }
+                await this._restoreContextTransition(contextSnapshot, "reload", { allowReload: true });
+            }
+            await options?.beforeSessionStart?.();
+            await dispatchSessionStartLifecycle(this._internal, "reload");
+            await this.extendResourcesFromExtensions("reload");
+            committedGeneration = this._reloadGeneration + 1;
+            this._reloadGeneration = committedGeneration;
+        }
+        finally {
+            this._reloadInProgress = false;
+        }
+        if (committedGeneration === undefined)
+            throw new Error("Session reload did not commit a generation");
+        await this._dispatchSessionReloadLifecycle(committedGeneration);
+    }
+    // =========================================================================
+    // Auto-Retry
+    // =========================================================================
+    /**
+     * Check if an error is retryable (overloaded, rate limit, server errors).
+     * Context overflow errors are NOT retryable (handled by compaction instead).
+     */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _isRetryableError(message, execution, signal) {
+        return isRetryableError(this._internal, message, execution, signal);
+    }
+    /**
+     * Prepare a retryable error for continuation with exponential backoff.
+     * @returns true if the caller should continue the agent, false otherwise
+     */
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
+    _prepareRetry(message, precomputedDecision) {
+        return prepareRetry(this._internal, message, precomputedDecision);
+    }
+    /**
+     * Cancel in-progress retry.
+     */
+    abortRetry() {
+        this._retryAbortController?.abort();
+    }
+    /** Whether auto-retry is currently in progress */
+    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
+    // =========================================================================
+    /** Capture a mode-level bash epoch for an intercepted user_bash result. */
+    captureBashEpoch() {
+        return captureBashEpoch(this._internal);
+    }
+    /** Return whether a mode-level bash result still belongs to this runtime epoch. */
+    isBashEpochCurrent(epoch) {
+        return isBashEpochCurrent(this._internal, epoch);
+    }
+    /** Dispatch the user.bash lifecycle facts for a `!`/`!!` user bash command. */
+    emitUserBash(excludeFromContext) {
+        emitUserBash(this._internal, excludeFromContext);
+    }
+    /**
+     * Execute a bash command.
+     * Adds result to agent context and session.
+     * @param command The bash command to execute
+     * @param onChunk Optional streaming callback for output
+     * @param options.excludeFromContext If true, command output won't be sent to LLM (!! prefix)
+     * @param options.id Optional identifier included in bash execution update events
+     * @param options.operations Custom BashOperations for remote execution
+     */
+    async executeBash(command, onChunk, options) {
+        return executeBash(this._internal, command, onChunk, options);
+    }
+    /**
+     * Record a bash execution result in session history.
+     * Used by executeBash and by extensions that handle bash execution themselves.
+     */
+    recordBashResult(command, result, options) {
+        recordBashResult(this._internal, command, result, options);
+    }
+    /**
+     * Cancel running bash command.
+     */
+    abortBash() {
+        abortBash(this._internal);
+    }
+    /** Whether a bash command is currently running */
+    get isBashRunning() {
+        return this._bashAbortControllers.size > 0;
+    }
+    /** Whether there are pending bash messages waiting to be flushed */
+    get hasPendingBashMessages() {
+        return this._pendingBashMessages.length > 0;
+    }
+    /**
+     * Flush pending bash messages to agent state and session.
+     * Called after agent turn completes to maintain proper message ordering.
+     */
+    _flushPendingBashMessages() {
+        flushPendingBashMessages(this._internal);
+    }
+    // =========================================================================
+    // Session Management
+    // =========================================================================
+    /**
+     * Set a display name for the current session.
+     */
+    setSessionName(name) {
+        this.sessionManager.appendSessionInfo(name);
+        const event = { type: "session_info_changed", name: this.sessionManager.getSessionName() };
+        this._emit(event);
+        void dispatchSessionInfoChangedLifecycle(this._internal, event.name);
+    }
+    /**
+     * Record a cross-suite resume (设计 §10.1 最小可用版): the session was created
+     * under `originalSuiteId` but its context is being reassembled under
+     * `currentSuiteId` (assembly happens at session creation, so reassembly is
+     * the existing behavior). Appends a `suite_mismatch` custom entry as session
+     * protocol data so later debugging can trace the switch; context
+     * serialization/conversion is explicitly out of scope.
+     */
+    recordSuiteMismatch(originalSuiteId, currentSuiteId) {
+        this.sessionManager.appendCustomEntry(SUITE_MISMATCH_SESSION_ENTRY_TYPE, {
+            originalSuiteId,
+            currentSuiteId,
+        });
+    }
+    // =========================================================================
+    // Tree Navigation
+    // =========================================================================
+    /**
+     * Navigate to a different node in the session tree.
+     * Unlike fork() which creates a new session file, this stays in the same file.
+     *
+     * @param targetId The entry ID to navigate to
+     * @param options.summarize Whether user wants to summarize abandoned branch
+     * @param options.customInstructions Custom instructions for summarizer
+     * @param options.replaceInstructions If true, customInstructions replaces the default prompt
+     * @param options.label Label to attach to the branch summary entry
+     * @returns Result with editorText (if user message) and cancelled status
+     */
+    async navigateTree(targetId, options = {}) {
+        return navigateTree(this._internal, targetId, options);
+    }
+    /**
+     * Get all user messages from session for fork selector.
+     */
+    getUserMessagesForForking() {
+        return getUserMessagesForForking(this._internal);
+    }
+    /**
+     * Get session statistics. Aggregates over ALL session entries (including
+     * history that was compacted away), so token/cost totals reflect what was
+     * actually billed across the session.
+     */
+    getSessionStats() {
+        return getSessionStats(this._internal);
+    }
+    getContextUsage() {
+        return getContextUsage(this._internal);
+    }
+    /**
+     * Export session to HTML.
+     * @param outputPath Optional output path (defaults to session directory)
+     * @param options Optional export presentation settings
+     * @returns Path to exported file
+     */
+    async exportToHtml(outputPath, options = {}) {
+        return await exportToHtml(this._internal, outputPath, options);
+    }
+    /**
+     * Export the current session branch to a JSONL file.
+     * Writes the session header followed by all entries on the current branch path.
+     * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.
+     * @returns The resolved output file path.
+     */
+    exportToJsonl(outputPath) {
+        return exportToJsonl(this._internal, outputPath);
+    }
+    // =========================================================================
+    // Utilities
+    // =========================================================================
+    /**
+     * Get text content of last assistant message.
+     * Useful for /copy command.
+     * @returns Text content, or undefined if no assistant message exists
+     */
+    getLastAssistantText() {
+        return getLastAssistantText(this._internal);
+    }
+    // =========================================================================
+    // Extension System
+    // =========================================================================
+    createReplacedSessionContext() {
+        return {
+            sendMessage: (message, options) => this.sendCustomMessage(message, options),
+            sendUserMessage: (content, options) => this.sendUserMessage(content, options),
+        };
+    }
+    /** Curated host surface (1B.7c): the only supported raw-integration point for product hosts. */
+    get host() {
+        const agent = this.agent;
+        const sessionManager = this.sessionManager;
+        return {
+            get abortSignal() {
+                return agent.signal;
+            },
+            get cwd() {
+                return sessionManager.getCwd();
+            },
+            get sessionName() {
+                return sessionManager.getSessionName();
+            },
+            get entries() {
+                return sessionManager.getEntries();
+            },
+            setTransport: (transport) => {
+                agent.transport = transport;
+            },
+            abortAgent: () => {
+                agent.abort();
+            },
+        };
+    }
+}
+//# sourceMappingURL=agent-session.js.map