@ai-agent-forge/agent-forge 0.88.1 → 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";
@@ -36,6 +37,7 @@ import { BOOTSTRAP_AGENT_LOOP_PLUGIN_ID, BOOTSTRAP_LIFECYCLE_PLUGIN_ID, BOOTSTRA
 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. */
@@ -283,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()),
@@ -294,6 +299,10 @@ 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;
@@ -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({
@@ -2042,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);
     }