@steerable/agent-shell 0.6.47 → 0.6.49

package/dist/sidecar/boot.js

@@ -9,7 +9,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import log from 'electron-log';
-import { SidecarSupervisor } from './supervisor.js';
+import { SidecarSupervisor, } from './supervisor.js';
 import { setSidecarSupervisor, setSidecarSupervisorPending, llmService } from '../llm/index.js';
 import { resolveSidecarStoragePath } from './storage-path.js';
 import { deriveEgressAllowListFromBaseUrl, probeExecSandboxCapability, } from './exec-sandbox.js';
@@ -22,6 +22,7 @@ import { sidecarWebSearchEnv } from '../storage/web-search-settings.js';
 import { executeHostedWebSearch } from '../hosted-web-search.js';
 let egressProxyRef = null;
 let supervisorRef = null;
+let sidecarGeneration = 0;
 async function deriveSidecarEgressAllowList() {
     const envList = (process.env.STEERABLE_SIDECAR_SANDBOX_ALLOWED_HOSTS ?? '')
         .split(',')
@@ -158,17 +159,49 @@ async function startEgressProxyIfEnabled(store) {
     }
 }
 /**
- * Default-on (2026-08-26): the sidecar hosts the CoreLoop, which is the
- * default chat path. Explicit STEERABLE_USE_SIDECAR=0 opts out (in-process
- * TS loop). Boot is registered synchronously so early RPC thin clients
- * (skill-loader et al.) can await it via whenSidecarSupervisor().
+ * Wire the sidecar plugin registry into the host tool router.
+ *
+ * The `plugin.list` probe doubles as the availability check: on failure the
+ * router is cleared (no plugin_* tools, no plugin-provided tools) and the
+ * error is rethrown for the caller to log. On success the router gets the
+ * plugin.* RPC seam plus a `tool.invoke` forwarder, then syncs the enabled
+ * plugins' tool descriptors from `plugin.tools.describe`. Plugin tools run
+ * only in the sidecar; approval already happened in its CoreLoop before a
+ * call is forwarded here, hence `consentGranted`.
+ *
+ * @param supervisor Running sidecar supervisor.
+ * @param toolRouter Host router that advertises and dispatches the tools.
+ */
+export async function wirePluginRegistry(supervisor, toolRouter) {
+    try {
+        await supervisor.call('plugin.list');
+    }
+    catch (err) {
+        toolRouter.setPluginRpc(null);
+        throw err;
+    }
+    toolRouter.setPluginRpc((method, params) => supervisor.call(method, params), (name, args) => supervisor.invokeTool(name, args, {
+        consentGranted: true,
+        timeoutMs: WEB_TOOL_RPC_TIMEOUT_MS,
+    }));
+    await toolRouter.refreshPluginTools();
+}
+/**
+ * The complete Python sidecar hosts the Rust CoreLoop and is mandatory.
+ * Boot is registered synchronously so early RPC thin clients (skill-loader
+ * et al.) can await it via whenSidecarSupervisor().
  */
 export async function startHostSidecar(deps) {
-    if (process.env.STEERABLE_USE_SIDECAR === '0')
-        return;
+    const generation = ++sidecarGeneration;
+    const pythonRunner = process.env.STEERABLE_PYTHON?.trim();
+    const runCodeEnabled = true;
     // ready 后的完整接线：注册全局 handle + reverse channels + web 工具握手。
     // 正常 boot 路径与「boot 失败后后台 restart 迟到就绪」路径共用。
     const wireSupervisor = async (supervisor) => {
+        if (generation !== sidecarGeneration) {
+            await supervisor.shutdown();
+            return;
+        }
         supervisorRef = supervisor;
         setSidecarSupervisor(supervisor);
         // A4 reverse channel: the sidecar-hosted CoreLoop asks this process to
@@ -251,12 +284,10 @@ export async function startHostSidecar(deps) {
         // 缺省接线）。模型面是 tool-router 的 plugin_* 工具（deferred 层，经
         // tool_search 发现）；这里注入直调缝。握手失败降级为工具缺席，不阻塞 boot。
         try {
-            await supervisor.call('plugin.list');
-            deps.toolRouter.setPluginRpc((method, params) => supervisor.call(method, params));
+            await wirePluginRegistry(supervisor, deps.toolRouter);
             log.info('[sidecar] plugin registry wired; plugin_* tools available');
         }
         catch (err) {
-            deps.toolRouter.setPluginRpc(null);
             log.warn('[sidecar] plugin registry unavailable; plugin_* tools hidden this session', err);
         }
         log.info('[sidecar] ready', supervisor.getBootSnapshot());
@@ -302,7 +333,8 @@ export async function startHostSidecar(deps) {
                     // P1: offer the sidecar's run_code (programmatic tool calls) to the
                     // model. The sidecar registers + advertises it; the desktop's
                     // tool-router forwards the call back over the reverse channel.
-                    STEERABLE_RUN_CODE: '1',
+                    STEERABLE_RUN_CODE: runCodeEnabled ? '1' : '0',
+                    ...(pythonRunner ? { STEERABLE_PYTHON: pythonRunner } : {}),
                     // P3: conversational JS PTC (run_js/wait_js). The sidecar spawns a
                     // long-lived Node worker. Browser and Tauri desktop hosts both run
                     // under the pinned Node runtime, so process.execPath is directly
@@ -311,24 +343,25 @@ export async function startHostSidecar(deps) {
                     STEERABLE_PTC_NODE: process.execPath,
                 },
                 onLogLine: (line) => (deps.onLogLine ?? ((l) => log.info('[sidecar]', l)))(line),
+            }, (created) => {
+                if (generation === sidecarGeneration) {
+                    supervisorRef = created;
+                }
+                else {
+                    void created.shutdown();
+                }
             });
             await wireSupervisor(supervisor);
             return supervisor;
         }
         catch (err) {
-            log.error('[sidecar] failed to start, falling back to in-process providers', err);
+            log.error('[sidecar] failed to start; Python sidecar is required', err);
             setSidecarSupervisor(null);
-            // boot 失败后 supervisor 的 exit→restart 循环仍在后台重试（另一个
-            // 宿主暂时持有 sessions.lock 这类瞬态冲突会自愈）。迟到就绪时补
-            // 接线，否则 sidecar 进程活着但 router 永远 503。
             const late = err.supervisor;
             if (late) {
-                late.once('ready', () => {
-                    log.info('[sidecar] late ready after initial boot failure');
-                    void wireSupervisor(late);
-                });
+                await late.shutdown();
             }
-            return null;
+            throw err;
         }
     })();
     setSidecarSupervisorPending(boot);
@@ -336,6 +369,7 @@ export async function startHostSidecar(deps) {
 }
 /** 宿主退出钩子：停 supervisor + egress proxy。幂等。 */
 export async function shutdownHostSidecar() {
+    sidecarGeneration += 1;
     if (supervisorRef) {
         const supervisor = supervisorRef;
         supervisorRef = null;

package/dist/sidecar/handle.d.ts

@@ -1,9 +1,7 @@
 /**
- * Optional sidecar handle. `main.ts` calls `setSidecarSupervisor()` after the
- * sidecar has booted. The sidecar path is default-on (2026-08-26): the
- * CoreLoop chat path and the LLM provider both route through it. Set
- * `STEERABLE_USE_SIDECAR=0` to fall back to the in-process providers — also
- * the automatic behavior when the sidecar failed to start.
+ * Mandatory sidecar handle. The host calls `setSidecarSupervisor()` after the
+ * complete Python sidecar has booted; CoreLoop and provider traffic route
+ * through it.
  *
  * Kept in a dependency-light module (type-only import of the supervisor) so
  * RPC thin clients (`local-edit`, `skill-loader`) can read the handle without
@@ -25,8 +23,7 @@ export declare function isSidecarEnabled(): boolean;
 /**
  * Await the sidecar handle through boot: returns the live handle immediately
  * when already up, otherwise waits on the registered boot promise. Returns
- * null when the sidecar is disabled, no boot is in flight, boot failed, or
- * the wait exceeds `timeoutMs` (bounded so a hung python env degrades the
- * caller to its no-sidecar fallback instead of hanging the request).
+ * null when no boot is in flight, boot failed, or the wait exceeds
+ * `timeoutMs`; callers surface that as sidecar unavailable.
  */
 export declare function whenSidecarSupervisor(timeoutMs?: number): Promise<SidecarSupervisor | null>;

package/dist/sidecar/handle.js

@@ -14,21 +14,18 @@ export function setSidecarSupervisorPending(pending) {
 }
 /** The supervised sidecar handle, when the sidecar path is active. */
 export function getSidecarSupervisor() {
-    return isSidecarEnabled() ? sidecarSupervisor : null;
+    return sidecarSupervisor;
 }
 export function isSidecarEnabled() {
-    return process.env.STEERABLE_USE_SIDECAR !== '0' && sidecarSupervisor != null;
+    return sidecarSupervisor != null;
 }
 /**
  * Await the sidecar handle through boot: returns the live handle immediately
  * when already up, otherwise waits on the registered boot promise. Returns
- * null when the sidecar is disabled, no boot is in flight, boot failed, or
- * the wait exceeds `timeoutMs` (bounded so a hung python env degrades the
- * caller to its no-sidecar fallback instead of hanging the request).
+ * null when no boot is in flight, boot failed, or the wait exceeds
+ * `timeoutMs`; callers surface that as sidecar unavailable.
  */
 export async function whenSidecarSupervisor(timeoutMs = 20_000) {
-    if (process.env.STEERABLE_USE_SIDECAR === '0')
-        return null;
     const live = getSidecarSupervisor();
     if (live)
         return live;
@@ -39,9 +36,8 @@ export async function whenSidecarSupervisor(timeoutMs = 20_000) {
     const timeout = new Promise((resolve) => {
         timer = setTimeout(() => resolve(null), timeoutMs);
     });
-    // A rejected boot promise (python env broken etc.) is already logged by the
-    // boot path; waiters degrade to their no-sidecar fallback instead of
-    // crashing on someone else's boot failure.
+    // A rejected boot promise is surfaced by host startup; concurrent waiters
+    // receive null and return their explicit sidecar-unavailable error.
     const settled = pending.catch(() => null);
     try {
         return await Promise.race([settled, timeout]);

package/dist/sidecar/supervisor.d.ts

@@ -11,8 +11,6 @@
  */
 import { EventEmitter } from 'node:events';
 import type { SidecarApplyEditsResult, SidecarChatStreamHandlers, SidecarChatStreamRequest, SidecarHealthSnapshot, SidecarMethodOptions, SidecarModelCatalog, SidecarReverseHandler, SidecarSandboxPosture, SidecarSessionBranches, SidecarSessionForkOutcome, SidecarSessionMessages, SidecarSessionTree, SidecarSkillModule, SidecarStartOptions, SidecarToolResult } from './types.js';
-export declare const RUST_SIDECAR_ENV = "STEERABLE_RUST_SIDECAR";
-export declare const RUST_SIDECAR_BIN_ENV = "STEERABLE_RUST_SIDECAR_BIN";
 /**
  * Tool names carried by a `tool.list` reply.
  *
@@ -48,7 +46,7 @@ export declare class SidecarSupervisor extends EventEmitter {
     private reverseHandlers;
     private constructor();
     /** Spawn the sidecar and wait for the ready marker. */
-    static start(options?: SidecarStartOptions): Promise<SidecarSupervisor>;
+    static start(options?: SidecarStartOptions, onCreate?: (supervisor: SidecarSupervisor) => void): Promise<SidecarSupervisor>;
     /** Round-trip a JSON-RPC method call. */
     call<T = unknown>(method: string, params?: unknown, options?: SidecarMethodOptions): Promise<T>;
     /** Convenience: list tools registered on the sidecar. */
@@ -218,9 +216,3 @@ export declare class SidecarSupervisor extends EventEmitter {
  * launcher (W1.3.3) spawns the same interpreter the sidecar uses.
  */
 export declare function resolveSidecarPython(pythonExecutable?: string): string;
-export declare function rustSidecarEnabled(): boolean;
-/**
- * Resolve the optional Rust sidecar binary. Missing binary with the flag
- * on is a silent fallback to Python (`python -m steerable_sidecar`).
- */
-export declare function resolveRustSidecarBin(explicit?: string): string | undefined;

package/dist/sidecar/supervisor.js

@@ -25,8 +25,6 @@ const READY_PREFIX = '__SIDECAR_READY__:';
 const DEFAULT_BOOT_TIMEOUT_MS = 15_000;
 const DEFAULT_HEALTH_INTERVAL_MS = 5_000;
 const DEFAULT_RESTART_AFTER_FAILED_PINGS = 3;
-export const RUST_SIDECAR_ENV = 'STEERABLE_RUST_SIDECAR';
-export const RUST_SIDECAR_BIN_ENV = 'STEERABLE_RUST_SIDECAR_BIN';
 // Only /usr/bin/sandbox-exec is trusted — a PATH-relative lookup could
 // resolve to an attacker-planted binary (codex's rule).
 const SEATBELT_EXECUTABLE = '/usr/bin/sandbox-exec';
@@ -77,8 +75,9 @@ export class SidecarSupervisor extends EventEmitter {
         this.options = options;
     }
     /** Spawn the sidecar and wait for the ready marker. */
-    static async start(options = {}) {
+    static async start(options = {}, onCreate) {
         const supervisor = new SidecarSupervisor(options);
+        onCreate?.(supervisor);
         try {
             await supervisor.boot();
             SidecarSupervisor.lastSpawnRefusal = null;
@@ -383,18 +382,14 @@ export class SidecarSupervisor extends EventEmitter {
     // Internal: boot
     // ------------------------------------------------------------------
     async boot() {
-        const rustBin = rustSidecarEnabled()
-            ? resolveRustSidecarBin(this.options.rustSidecarBin)
-            : undefined;
-        let spawnPlan;
-        if (rustBin) {
-            spawnPlan = await this.resolveSandboxedSpawn(rustBin, this.options.args ?? []);
-        }
-        else {
-            const py = this.resolvePythonBinary();
-            const entry = this.options.entryModule ?? 'steerable_sidecar';
-            const args = ['-m', entry, ...(this.options.args ?? [])];
-            spawnPlan = await this.resolveSandboxedSpawn(py, args);
+        const py = this.resolvePythonBinary();
+        const entry = this.options.entryModule ?? 'steerable_sidecar';
+        const args = ['-m', entry, ...(this.options.args ?? [])];
+        const spawnPlan = await this.resolveSandboxedSpawn(py, args);
+        // Profile generation is asynchronous. A quit can begin while it runs;
+        // never spawn a new child after shutdown has claimed the supervisor.
+        if (this.shuttingDown) {
+            throw new SidecarShutdownError('sidecar startup cancelled by shutdown');
         }
         const child = spawn(spawnPlan.command, spawnPlan.args, {
             cwd: this.options.cwd,
@@ -492,12 +487,7 @@ export class SidecarSupervisor extends EventEmitter {
                 ...(webEgress ? ['--allow-web-egress'] : []),
                 ...(allowResolver ? ['--allow-resolver'] : []),
             ];
-            const rustBin = rustSidecarEnabled()
-                ? resolveRustSidecarBin(this.options.rustSidecarBin)
-                : undefined;
-            const { stdout } = rustBin
-                ? await execFileAsync(rustBin, ['sandbox', 'profile', ...flags], { timeout: 10_000 })
-                : await execFileAsync(command, ['-m', 'steerable_sidecar.sandbox', 'profile', ...flags], { timeout: 10_000 });
+            const { stdout } = await execFileAsync(command, ['-m', 'steerable_sidecar.sandbox', 'profile', ...flags], { timeout: 10_000 });
             const profile = stdout.trim();
             if (!profile.includes('(deny default)')) {
                 throw new Error('generated profile is not a Seatbelt policy');
@@ -508,9 +498,6 @@ export class SidecarSupervisor extends EventEmitter {
                 (allowResolver ? ' + resolver only (web tools egress via the per-host proxy)' : '') +
                 ')');
             this.sandboxPosture = { backend: 'seatbelt', enforcement: 'partial', reason: 'active' };
-            // macOS TMPDIR is /var/folders, which the Seatbelt profile does not
-            // allow. run_code / run_js materialize their workers there and fail
-            // with EPERM, so the model cannot list or read local folders.
             const confinedTmp = join(writableRoots[0], 'tmp');
             mkdirSync(confinedTmp, { recursive: true });
             return {
@@ -545,29 +532,17 @@ export class SidecarSupervisor extends EventEmitter {
         // 都透传环境）+ sidecar 应用层域名名单强制，网络命名空间保持共享。
         // 这里如实记录，不假装接上了实际不强制的参数。
         const egressViaProxy = this.options.env?.STEERABLE_EGRESS_CONFINED === '1';
-        const rustBin = rustSidecarEnabled()
-            ? resolveRustSidecarBin(this.options.rustSidecarBin)
-            : undefined;
-        const wrapArgs = rustBin
-            ? [
-                'sandbox',
-                'linux-wrap',
-                ...writableRoots.flatMap((root) => ['--writable-root', root]),
-                '--',
-                command,
-                ...args,
-            ]
-            : [
-                '-m',
-                'steerable_sidecar.sandbox',
-                'linux-wrap',
-                ...writableRoots.flatMap((root) => ['--writable-root', root]),
-                '--',
-                command,
-                ...args,
-            ];
+        const wrapArgs = [
+            '-m',
+            'steerable_sidecar.sandbox',
+            'linux-wrap',
+            ...writableRoots.flatMap((root) => ['--writable-root', root]),
+            '--',
+            command,
+            ...args,
+        ];
         try {
-            const { stdout } = await execFileAsync(rustBin ?? command, wrapArgs, { timeout: 15_000 });
+            const { stdout } = await execFileAsync(command, wrapArgs, { timeout: 15_000 });
             const plan = JSON.parse(stdout.trim());
             if (!Array.isArray(plan.argv) || plan.argv.length < 1 || typeof plan.argv[0] !== 'string') {
                 throw new Error('linux-wrap did not return an argv');
@@ -646,6 +621,15 @@ export class SidecarSupervisor extends EventEmitter {
         child.stderr.setEncoding('utf-8');
         child.stdout.on('data', (chunk) => this.handleStdoutChunk(chunk));
         child.stderr.on('data', (chunk) => this.handleStderrChunk(chunk));
+        child.stdin.on('error', (error) => {
+            // A child may close stdin between shutdown's requireChild() and write().
+            // Keep the stream error handled; the write callback/pending failure
+            // carries the transport error to callers.
+            this.failPending(new SidecarShutdownError(`sidecar stdin closed: ${error.message}`));
+            if (!this.shuttingDown) {
+                this.options.onLogLine?.(`sidecar stdin error: ${error.message}`);
+            }
+        });
         child.on('exit', (code, signal) => {
             this.emit('exit', { code, signal });
             this.failPending(new SidecarShutdownError(`sidecar exited (code=${code ?? 'null'}, signal=${signal ?? 'null'})`));
@@ -960,39 +944,5 @@ export function resolveSidecarPython(pythonExecutable) {
         if (existsSync(candidate))
             return candidate;
     }
-    // Fallback to system python (developer machines).
-    return process.platform === 'win32' ? 'python' : 'python3';
-}
-function envFlag(name) {
-    const raw = (process.env[name] ?? '').trim().toLowerCase();
-    return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
-}
-export function rustSidecarEnabled() {
-    return envFlag(RUST_SIDECAR_ENV);
-}
-/**
- * Resolve the optional Rust sidecar binary. Missing binary with the flag
- * on is a silent fallback to Python (`python -m steerable_sidecar`).
- */
-export function resolveRustSidecarBin(explicit) {
-    if (explicit) {
-        return existsSync(explicit) ? explicit : undefined;
-    }
-    const fromEnv = process.env[RUST_SIDECAR_BIN_ENV];
-    if (fromEnv) {
-        return existsSync(fromEnv) ? fromEnv : undefined;
-    }
-    const exe = process.platform === 'win32' ? 'steerable-sidecar.exe' : 'steerable-sidecar';
-    const relatives = [
-        join('..', '..', '..', '..', 'sidecar', 'rs', 'target', 'debug', exe),
-        join('..', '..', '..', '..', '..', 'sidecar', 'rs', 'target', 'debug', exe),
-        join('..', '..', '..', '..', 'sidecar', 'rs', 'target', 'release', exe),
-        join('..', '..', '..', '..', '..', 'sidecar', 'rs', 'target', 'release', exe),
-    ];
-    for (const rel of relatives) {
-        const candidate = join(__dirname, rel);
-        if (existsSync(candidate))
-            return candidate;
-    }
-    return undefined;
+    throw new Error('portable Python sidecar runtime not found; prepare python-runtime or set STEERABLE_SIDECAR_PYTHON');
 }

package/dist/sidecar/types.d.ts

@@ -21,8 +21,6 @@ export interface SidecarSandboxPosture {
 export interface SidecarStartOptions {
     /** Override the python binary; defaults to the bundled portable runtime. */
     pythonExecutable?: string;
-    /** Optional Rust sidecar binary; used when STEERABLE_RUST_SIDECAR is on. */
-    rustSidecarBin?: string;
     /** Override the entrypoint module; defaults to ``steerable_sidecar``. */
     entryModule?: string;
     /** Extra arguments appended after ``-m <entryModule>``. */

package/dist/tool-router.d.ts

@@ -76,7 +76,13 @@ export declare const WEB_TOOL_RPC_TIMEOUT_MS = 130000;
  * 由 PluginRegistry 背书。宿主只持 schema 并经此 delegate 直调——与 web 工具
  * 不同，这些是普通 RPC 而非 tool.invoke（不经过模型工具分发层）。
  */
-export type PluginRpcDelegate = (method: 'plugin.list' | 'plugin.enable' | 'plugin.disable' | 'plugin.reload', params?: Record<string, unknown>) => Promise<unknown>;
+export type PluginRpcDelegate = (method: 'plugin.list' | 'plugin.enable' | 'plugin.disable' | 'plugin.reload' | 'plugin.tools.describe', params?: Record<string, unknown>) => Promise<unknown>;
+/**
+ * 插件自带工具的执行缝：唯一实现在 sidecar 的插件路由上，宿主只持
+ * `plugin.tools.describe` 给出的 schema，调用经 `tool.invoke` 前转（与 web
+ * 工具同一模式）。审批已在 sidecar CoreLoop 的 ApprovalExecutor 完成。
+ */
+export type PluginToolDelegate = (name: string, args: Record<string, unknown>) => Promise<unknown>;
 /**
  * 本机是否提供网络读取工具（`STEERABLE_WEB_TOOLS=0` 关闭）。
  *
@@ -142,7 +148,18 @@ export declare class ToolRouter {
      * plugin_* 工具一个 schema 都不出——模型看不到不可用的工具。
      */
     private pluginRpc;
-    setPluginRpc(delegate: PluginRpcDelegate | null): void;
+    private pluginToolInvoke;
+    /** 已启用插件的工具（名字 → schema），由 refreshPluginTools 从 sidecar 同步。 */
+    private pluginToolSchemas;
+    setPluginRpc(delegate: PluginRpcDelegate | null, invokeTool?: PluginToolDelegate | null): void;
+    private pluginToolsEnabled;
+    /**
+     * 从 sidecar 拉取已启用插件的工具描述，替换宿主侧的插件工具集。
+     * 启动握手后和每次 plugin_enable / plugin_disable / plugin_reload 成功后
+     * 调用，保证模型看到的集合与 sidecar 路由上可分发的集合一致。
+     * 与内置 / 场景包工具重名的插件工具被跳过并告警——内置工具优先。
+     */
+    refreshPluginTools(): Promise<void>;
     listSchemas(): ToolSchema[];
     /**
      * 插件生命周期工具（框架 plugin.* RPC 的模型面）。全在 deferred 层：

package/dist/tool-router.js

@@ -6,6 +6,7 @@ import { rankTools, resolveMaxResults, TOOL_SEARCH_DEFAULT_MAX_RESULTS, } from '
 import { maybeAutoInstallWrittenSkill } from './local-backend/skill-install.js';
 import { filterToolsByPolicy, isToolAllowed, } from './local-backend/agent-capability.js';
 import { processViewImage } from './image-attachment.js';
+import { PRESENT_FILES_SCHEMA, PRESENT_FILES_TOOL_NAME, executePresentFiles, } from './present-files.js';
 import { isHostToolCapabilityEnabled } from './host-tools.js';
 import { getResolvedHostTools } from './host-tools-runtime.js';
 /** 已注册 MCP 服务的动态工具名前缀：`mcp__<serverKey>__<toolName>`。 */
@@ -22,6 +23,7 @@ export const MCP_DYNAMIC_TOOL_PREFIX = 'mcp__';
 export const TOOL_SEARCH_TOOL_NAME = 'tool_search';
 /** 前转 RPC 超时：sidecar 侧单次请求上限默认 30s（可配到 600s），这里给足余量。 */
 export const WEB_TOOL_RPC_TIMEOUT_MS = 130_000;
+const PLUGIN_TOOL_MODES = new Set(['read', 'safe_write', 'destructive']);
 /**
  * 本机是否提供网络读取工具（`STEERABLE_WEB_TOOLS=0` 关闭）。
  *
@@ -107,8 +109,52 @@ export class ToolRouter {
      * plugin_* 工具一个 schema 都不出——模型看不到不可用的工具。
      */
     pluginRpc = null;
-    setPluginRpc(delegate) {
+    pluginToolInvoke = null;
+    /** 已启用插件的工具（名字 → schema），由 refreshPluginTools 从 sidecar 同步。 */
+    pluginToolSchemas = new Map();
+    setPluginRpc(delegate, invokeTool = null) {
         this.pluginRpc = delegate;
+        this.pluginToolInvoke = delegate ? invokeTool : null;
+        if (!delegate)
+            this.pluginToolSchemas = new Map();
+    }
+    pluginToolsEnabled() {
+        return getResolvedHostTools().plugins.capability;
+    }
+    /**
+     * 从 sidecar 拉取已启用插件的工具描述，替换宿主侧的插件工具集。
+     * 启动握手后和每次 plugin_enable / plugin_disable / plugin_reload 成功后
+     * 调用，保证模型看到的集合与 sidecar 路由上可分发的集合一致。
+     * 与内置 / 场景包工具重名的插件工具被跳过并告警——内置工具优先。
+     */
+    async refreshPluginTools() {
+        if (!this.pluginRpc || !this.pluginToolInvoke) {
+            this.pluginToolSchemas = new Map();
+            return;
+        }
+        const result = (await this.pluginRpc('plugin.tools.describe'));
+        this.pluginToolSchemas = new Map();
+        const taken = new Set(this.listSchemas().map((s) => s.name));
+        const next = new Map();
+        for (const tool of result?.tools ?? []) {
+            if (!tool || typeof tool.name !== 'string' || !tool.name)
+                continue;
+            if (taken.has(tool.name)) {
+                console.warn(`[tool-router] plugin tool ${tool.name} (${tool.plugin ?? 'unknown plugin'}) shadows a host tool; skipped`);
+                continue;
+            }
+            const owner = tool.plugin ? `[plugin:${tool.plugin}] ` : '';
+            next.set(tool.name, {
+                name: tool.name,
+                description: `${owner}${tool.description || tool.name}`,
+                inputSchema: tool.schema && typeof tool.schema === 'object'
+                    ? tool.schema
+                    : { type: 'object', properties: {} },
+                mode: (tool.mode && PLUGIN_TOOL_MODES.has(tool.mode) ? tool.mode : 'external'),
+                exposure: 'deferred',
+            });
+        }
+        this.pluginToolSchemas = next;
     }
     listSchemas() {
         return [
@@ -240,6 +286,7 @@ export class ToolRouter {
                     required: ['path', 'edits'],
                 },
             },
+            PRESENT_FILES_SCHEMA,
             {
                 name: 'local_open_path',
                 description: 'Open local path or URL',
@@ -374,6 +421,9 @@ export class ToolRouter {
             ...this.listWebToolSchemas(),
             ...this.listRegisteredMcpToolSchemas(),
             ...this.listPluginToolSchemas(),
+            // 插件自带的工具：与 MCP 动态工具同在 deferred 层，经 tool_search 发现。
+            // 名字不带族前缀，按名归族会漏过 plugins 能力开关，这里显式判定。
+            ...(this.pluginToolsEnabled() ? this.pluginToolSchemas.values() : []),
             // ─── 场景包贡献的工具（0.3a 开槽） ─────────────────
             ...[...this.contributedTools.values()].map((c) => ({
                 name: c.name,
@@ -747,6 +797,8 @@ export class ToolRouter {
                 this.autoInstallSkillOnSuccess(edited, args.path);
                 return edited;
             }
+            case PRESENT_FILES_TOOL_NAME:
+                return await executePresentFiles(args, projectRoot);
             case 'local_open_path':
                 return await this.localExecutor.openLocalTarget({
                     target: String(args.target || ''),
@@ -802,7 +854,10 @@ export class ToolRouter {
                 }
                 const method = call.name.replace('_', '.');
                 const params = call.name === 'plugin_list' ? undefined : { name: String(args.name || '') };
-                return await this.pluginRpc(method, params);
+                const result = await this.pluginRpc(method, params);
+                if (call.name !== 'plugin_list')
+                    await this.refreshPluginTools();
+                return result;
             }
             case 'task_run': {
                 const chatId = this.requireTaskContext(context);
@@ -857,6 +912,12 @@ export class ToolRouter {
                 if (contributed) {
                     return await contributed.handler(args, context ?? {});
                 }
+                if (this.pluginToolSchemas.has(call.name) && this.pluginToolInvoke) {
+                    if (!this.pluginToolsEnabled()) {
+                        throw new Error(`工具 ${call.name} 未在本产品引入`);
+                    }
+                    return await this.pluginToolInvoke(call.name, args);
+                }
                 return { success: false, error: `Unknown tool: ${call.name}` };
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.47",
+  "version": "0.6.49",
   "description": "Steerable framework — product-neutral Node HostRuntime and headless HTTP server shared by Tauri desktop and browser deployments; scenario packs extend it through @steerable/pack-sdk.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -55,9 +55,9 @@
     "he": "^1.2.0",
     "node-pty": "^1.1.0",
     "semver": "^7.8.0",
-    "@steerable/pack-sdk": "0.6.47",
-    "@steerable/agent-harness": "0.6.47",
-    "@steerable/agent-protocol": "0.6.47"
+    "@steerable/pack-sdk": "0.6.49",
+    "@steerable/agent-protocol": "0.6.49",
+    "@steerable/agent-harness": "0.6.49"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",