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

package/dist/core/agent-session.js

@@ -13,6 +13,7 @@
  * Modes use this class and add their own I/O layer on top.
  */
 import { readFileSync } from "node:fs";
+import { readFile as readFileUtf8 } from "node:fs/promises";
 import { resolve } from "node:path";
 import { contentText } from "@agent-forge/ai";
 import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, streamSimple, } from "@agent-forge/ai/compat";
@@ -32,10 +33,11 @@ import { getAllTools, getCapabilitySkills, getToolDefinition, normalizePromptGui
 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 { BOOTSTRAP_AGENT_LOOP_PLUGIN_ID, BOOTSTRAP_LIFECYCLE_PLUGIN_ID, BOOTSTRAP_SKILLS_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, installBootstrapLifecycle, installSessionBootstrapSkills, loadCapabilityPluginFromManifest, loadCapabilityPlugin as loadCapabilityPluginRuntime, } from "./extensions/index.js";
 import { t } from "./i18n/index.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { createSessionJsonlArtifact } from "./session-export.js";
+import { createCapabilityMountTools } from "./tools/capability-mount.js";
 import { createToolSearchTool } from "./tools/tool-search.js";
 /**
  * Parse a skill block from message text.
@@ -151,6 +153,8 @@ export class AgentSession {
     _resourceLoader;
     _customTools;
     _deferredToolPluginIds;
+    _deferredCapabilityCards = [];
+    _capabilityMountToolsRegistered = false;
     /** 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. */
@@ -174,7 +178,6 @@ export class AgentSession {
         for (const listener of [...this._outputArtifactCommitListeners])
             listener(artifact);
     };
-    _bootstrapToolsHandle;
     _bootstrapSkillsHandle;
     _bootstrapRetryHandle;
     _bootstrapCompactionHandle;
@@ -184,6 +187,12 @@ export class AgentSession {
     _bootstrapLifecycleHandle;
     _capabilityPlugins = new Map();
     _inlineCapabilityPlugins = new Map();
+    /**
+     * 宿主装配链经 loadCapabilityPluginManifest 声明的 configOverride（按解析后
+     * manifest 路径）。reload 重装载循环据此回放 sdk 注入的会话事实（D-082 批 1：
+     * coding-tools 的 cwd/read/bash 等），会话生命周期内随同路径显式装载覆盖。
+     */
+    _capabilityPluginConfigOverrides = new Map();
     _isDisposingCapabilityPlugins = false;
     /**
      * 工具表变更钩子的两道门（见 _buildRuntime 的 onToolRegistryChange）：
@@ -204,7 +213,6 @@ export class AgentSession {
     _allowedToolNames;
     // biome-ignore lint/correctness/noUnusedPrivateClassMembers: read and written via the agent-session-* submodule facade
     _excludedToolNames;
-    _baseToolsOverride;
     _disabledBootstrapPlugins;
     _sessionStartEvent;
     _capabilityMode;
@@ -279,6 +287,7 @@ export class AgentSession {
         this._resourceLoader = config.resourceLoader;
         this._customTools = config.customTools ?? [];
         this._deferredToolPluginIds = new Set(config.deferredToolPluginIds ?? []);
+        this._deferredCapabilityCards = [...(config.deferredCapabilityCards ?? [])];
         if (this._deferredToolPluginIds.size > 0) {
             this._customTools.push(createToolSearchTool({
                 listAllToolNames: () => Array.from(this._toolRegistry.keys()),
@@ -290,12 +299,15 @@ export class AgentSession {
                 setActiveToolsByName: (toolNames) => this.setActiveToolsByName(toolNames),
             }));
         }
+        if (this._deferredCapabilityCards.length > 0) {
+            this._capabilityMountToolsRegistered = true;
+            this._customTools.push(...this._createCapabilityMountTools());
+        }
         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";
@@ -660,7 +672,6 @@ export class AgentSession {
                     const interactionHost = this._interactionHost;
                     return interactionHost?.dispose?.();
                 },
-                () => this._bootstrapToolsHandle?.dispose(),
                 () => this._bootstrapSkillsHandle?.dispose(),
                 () => this._bootstrapRetryHandle?.dispose(),
                 () => this._bootstrapCompactionHandle?.dispose(),
@@ -680,7 +691,6 @@ export class AgentSession {
             this._capabilityRuntime?.revokeAllAPIs();
             this._capabilityPlugins.clear();
             this._inlineCapabilityPlugins.clear();
-            this._bootstrapToolsHandle = undefined;
             this._bootstrapSkillsHandle = undefined;
             this._bootstrapRetryHandle = undefined;
             this._bootstrapCompactionHandle = undefined;
@@ -879,7 +889,6 @@ export class AgentSession {
     getCapabilityPlugins() {
         const handles = Array.from(this._capabilityPlugins.values());
         for (const handle of [
-            this._bootstrapToolsHandle,
             this._bootstrapSkillsHandle,
             this._bootstrapRetryHandle,
             this._bootstrapCompactionHandle,
@@ -1010,10 +1019,11 @@ export class AgentSession {
             (!tool.source.startsWith("agent-forge.builtin.") && !tool.source.startsWith("agent-forge.plugin.")) ||
             tool.readonlySafe === true)
             // Deferred plugin tools register but stay out of the active set on
-            // this explicit-activation path too, until tool_search or
-            // setActiveTools names them (same contract as the default path in
-            // agent-session-tools.ts).
-            .filter((tool) => !this._deferredToolPluginIds.has(tool.source))
+            // this explicit-activation path too, until tool_search /
+            // capability_mount or setActiveTools names them (same contract as the
+            // default path in agent-session-tools.ts).
+            .filter((tool) => !this._deferredToolPluginIds.has(tool.source) &&
+            !this._deferredCapabilityCards.some((card) => card.pluginId === tool.source))
             .map((tool) => tool.name)
             .filter((name) => !previousToolNames.has(name));
         this._refreshToolRegistry({
@@ -1031,6 +1041,13 @@ export class AgentSession {
         if (this._capabilityPlugins.has(resolvedManifestPath)) {
             throw new Error(t("Capability plugin manifest is already loaded: {path}", { path: resolvedManifestPath }));
         }
+        // 宿主装配声明的 configOverride 按路径记录（D-082 批 1）：sdk 装配链注入的
+        // 会话事实（coding-tools 的 cwd/read/bash 等）在 reload 重装载时经此回放，
+        // 否则插件会退回 manifest 缺省值（cwd 缺失即退回 process.cwd()）。同路径的
+        // 后续显式装载覆盖旧值。
+        if (options?.configOverride !== undefined) {
+            this._capabilityPluginConfigOverrides.set(resolvedManifestPath, options.configOverride);
+        }
         const previousToolNames = new Set(runtime.listTools().map((tool) => tool.name));
         const loaded = await loadCapabilityPluginFromManifest(runtime, resolvedManifestPath, options);
         return this._trackCapabilityPlugin(resolvedManifestPath, loaded, previousToolNames);
@@ -2035,6 +2052,50 @@ export class AgentSession {
     _refreshToolRegistry(options) {
         refreshToolRegistry(this._internal, options);
     }
+    /** Registry tool names whose owning capability plugin is `pluginId`. */
+    _toolNamesForPlugin(pluginId) {
+        return Array.from(this._toolDefinitions.entries())
+            .filter(([, entry]) => entry.sourceInfo.source === pluginId)
+            .map(([name]) => name);
+    }
+    _readManual(manualPath) {
+        return readFileUtf8(manualPath, "utf8");
+    }
+    _createCapabilityMountTools() {
+        return createCapabilityMountTools({
+            getCards: () => this._deferredCapabilityCards,
+            toolNamesForPlugin: (pluginId) => {
+                const names = this._toolNamesForPlugin(pluginId);
+                // readonly narrowing (宪法 §6): the registry keeps non-readonlySafe
+                // tools even in readonly sessions (the normal load path filters them
+                // at activation); mount must not smuggle them past that gate.
+                if (this._capabilityMode !== "readonly")
+                    return names;
+                const readonlySafe = new Set((this._capabilityRuntime?.listTools() ?? [])
+                    .filter((tool) => tool.source === pluginId)
+                    .filter((tool) => tool.readonlySafe === true)
+                    .map((tool) => tool.name));
+                return names.filter((name) => readonlySafe.has(name));
+            },
+            getActiveToolNames: () => this.getActiveToolNames(),
+            setActiveToolsByName: (toolNames) => this.setActiveToolsByName(toolNames),
+            readManual: (manualPath) => this._readManual(manualPath),
+        });
+    }
+    /**
+     * Register on-demand capability cards after construction (插件按需挂载与能力手册设计 §4).
+     * The sdk assembly calls this once the plugin pool settles, before loading;
+     * first call also injects the capability_mount / capability_unmount pair.
+     * Idempotent: later calls replace the card set.
+     */
+    registerDeferredCapabilityCards(cards) {
+        this._deferredCapabilityCards = [...cards];
+        if (this._deferredCapabilityCards.length === 0 || this._capabilityMountToolsRegistered)
+            return;
+        this._capabilityMountToolsRegistered = true;
+        this._customTools.push(...this._createCapabilityMountTools());
+        this._refreshToolRegistry();
+    }
     _syncCapabilityTools() {
         syncCapabilityTools(this._internal);
     }
@@ -2109,9 +2170,6 @@ export class AgentSession {
         // 对齐 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,
@@ -2132,6 +2190,27 @@ export class AgentSession {
             // The session working directory rides the public HostCapabilities as a host
             // service so workspace-bound plugins (LSP real host) resolve their adapters.
             workspaceDirectory: this._cwd,
+            // 模型目录宿主服务（D-082 批 3b，契约 B）：provider-failover 装载预检/
+            // 目录快照读面（api.host.modelCatalog）。全部是 ModelRuntime 静态目录
+            // 与凭据条目的即时读投影，零网络、零 OAuth；resolveModel 返回结构视图
+            // （provider/contextWindow/maxTokens/compat/thinkingLevelMap 五字段），
+            // 不透出内部 Model 对象，未知 provider/model 对返回 undefined。
+            modelCatalog: {
+                resolveModel: (provider, modelId) => {
+                    const model = this._modelRuntime.getModel(provider, modelId);
+                    if (!model)
+                        return undefined;
+                    return {
+                        provider: model.provider,
+                        contextWindow: model.contextWindow,
+                        maxTokens: model.maxTokens,
+                        ...(model.compat === undefined ? {} : { compat: model.compat }),
+                        ...(model.thinkingLevelMap === undefined ? {} : { thinkingLevelMap: model.thinkingLevelMap }),
+                    };
+                },
+                hasProvider: (providerId) => this._modelRuntime.getProvider(providerId) !== undefined,
+                hasConfiguredAuth: (providerId) => this._modelRuntime.hasConfiguredAuth(providerId),
+            },
             features: [
                 "tools",
                 "skills",
@@ -2321,22 +2400,20 @@ export class AgentSession {
         };
         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();
+        // 默认编码工具不再由内嵌 bootstrap-tools 注册（D-082 批 1，S6 工具批）：
+        // 实现体迁出为 plugins/coding-tools 独立包，sdk 装配链经 bundled 分发通道
+        // （manifest/jiti）装载，禁用面平移到 options.disabledPluginIds。
+        // 默认策略家族（retry / overflow / compaction / branch summary）自 D-082
+        // 批 3 起不再内嵌安装：实现体迁出为 plugins/{retry,overflow,compaction}-policy
+        // 独立包（branch summary 随 compaction 包），sdk 装配链经 bundled 分发通道
+        // （manifest/jiti）装载，禁用面平移到 options.disabledPluginIds；四个缺省
+        // 策略名（DEFAULT_*_POLICY_NAME）仍由宿主持有。
         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
@@ -2362,17 +2439,15 @@ export class AgentSession {
             !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"];
+        const defaultActiveToolNames = 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.
@@ -2414,8 +2489,6 @@ export class AgentSession {
             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();
@@ -2441,7 +2514,10 @@ export class AgentSession {
                 includeAllExtensionTools: true,
             });
             for (const manifestPath of capabilityPluginPaths) {
-                await this.loadCapabilityPluginManifest(manifestPath);
+                // 宿主装配注入的 configOverride 按路径回放（D-082 批 1），重装载不退
+                // 回 manifest 缺省值。
+                const configOverride = this._capabilityPluginConfigOverrides.get(manifestPath);
+                await this.loadCapabilityPluginManifest(manifestPath, ...(configOverride === undefined ? [] : [{ configOverride }]));
             }
             for (const { manifest, factory } of inlineCapabilityPlugins) {
                 await this.loadCapabilityPlugin(manifest, factory);