@steerable/agent-shell 0.6.48 → 0.6.49

package/dist/local-backend/turn-files.js

@@ -32,6 +32,7 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { PRESENT_FILES_TOOL_NAME, readPresentedArgs, } from '../present-files.js';
 /** 这些目录要么体量巨大（node_modules/target），要么是框架内部状态（.steerable），扫了只有噪音。 */
 const IGNORED_DIR_NAMES = new Set([
     'node_modules',
@@ -48,7 +49,65 @@ const IGNORED_DIR_NAMES = new Set([
     'target',
     '.steerable',
 ]);
-const IGNORED_FILE_NAMES = new Set(['.DS_Store']);
+const IGNORED_FILE_NAMES = new Set(['.DS_Store', 'Thumbs.db']);
+/** 交付物扩展名（最终产物，如电子表格、幻灯片、文档、图片、音视频、独立页面、压缩包）。 */
+export const DELIVERABLE_EXTENSIONS = new Set([
+    // 表格 / Spreadsheets
+    '.xlsx', '.xls', '.csv', '.tsv', '.numbers',
+    // 幻灯片 / Presentations
+    '.pptx', '.ppt', '.key', // shell-neutral:allow — Office 幻灯片扩展名，不是产品品牌
+    // 文档 / Documents
+    '.docx', '.doc', '.pdf', '.pages', '.epub', '.rtf',
+    // 图像与富媒体 / Images & Media
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.mp4', '.mov', '.mp3',
+    // 独立文档输出与压缩包 / Standalone HTML & Archives
+    '.html', '.htm', '.zip', '.tar.gz', '.tar', '.7z',
+]);
+const INTERMEDIATE_DIR_PATTERNS = [
+    /(?:^|[\\/])review_work(?:[\\/]|$)/i,
+    /(?:^|[\\/])(?:work|temp|tmp|\.temp|\.tmp|scratch)(?:[\\/]|$)/i,
+    /(?:^|[\\/])scripts(?:[\\/]|$)/i,
+    /(?:^|[\\/])(?:build|dist|\.cache|__pycache__)(?:[\\/]|$)/i,
+];
+/** 是否为临时文件 / 办公软件锁定文件（如 ~$ 开头的文件名），产物列表中一律排除。 */
+export function isIgnoredFileName(name) {
+    if (IGNORED_FILE_NAMES.has(name))
+        return true;
+    // Office 临时锁定文件（如 ~$ 开头）
+    if (name.startsWith('~$'))
+        return true;
+    // 临时文件与编辑器交换文件
+    if (name.endsWith('.tmp') || name.endsWith('.swp') || name.endsWith('~'))
+        return true;
+    return false;
+}
+/** 判定文件是最终交付文件还是中间修改文件。 */
+export function classifyFileCategory(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const ext = path.extname(normalized).toLowerCase();
+    // 1. 若具有最终交付产物扩展名（电子表格、PPT、PDF、图片等），属于交付物
+    if (DELIVERABLE_EXTENSIONS.has(ext))
+        return 'deliverable';
+    // 2. 位于中间工作目录（如 review_work/、scripts/）属于中间文件
+    for (const pattern of INTERMEDIATE_DIR_PATTERNS) {
+        if (pattern.test(normalized))
+            return 'intermediate';
+    }
+    // 3. 其余脚本、代码、配置文件均归为中间文件
+    return 'intermediate';
+}
+/** 从统一 diff 文本中统计增删行数。 */
+export function parseDiffStats(diffText) {
+    let additions = 0;
+    let deletions = 0;
+    for (const line of diffText.split('\n')) {
+        if (line.startsWith('+') && !line.startsWith('+++'))
+            additions++;
+        else if (line.startsWith('-') && !line.startsWith('---'))
+            deletions++;
+    }
+    return { additions, deletions };
+}
 /** 单次扫描的遍历上限：深度 10、条目 10 万、结果 100 条。 */
 const MAX_DEPTH = 10;
 const MAX_VISITED = 100_000;
@@ -101,7 +160,78 @@ export async function collectTurnFiles(options) {
     for (const dir of shallowRoots) {
         await scanShallow(dir, sinceMs, byPath);
     }
-    return [...byPath.values()]
+    // present_files 声明的文件：本轮可能没动过（交付已有文件），不受时间水位线
+    // 约束，只要求仍是普通文件。
+    const presented = new Map();
+    for (const action of options.actions ?? []) {
+        if (action.tool !== PRESENT_FILES_TOOL_NAME || action.success === false)
+            continue;
+        for (const file of readPresentedArgs(action.arguments, projectRoot, homeDir)) {
+            presented.set(file.path, file);
+        }
+    }
+    for (const file of presented.values()) {
+        if (byPath.has(file.path))
+            continue;
+        const stat = await statPresentedFile(file.path);
+        if (stat)
+            byPath.set(file.path, stat);
+    }
+    // 从 actions 中提取增删行数统计（local_edit_file 的 diff 或 local_write_file 的 content）
+    const statsByPath = new Map();
+    for (const action of options.actions ?? []) {
+        if (typeof action.tool === 'string') {
+            const args = action.arguments && typeof action.arguments === 'object' ? action.arguments : null;
+            const rawPath = typeof args?.path === 'string' ? args.path : null;
+            if (rawPath) {
+                const full = path.isAbsolute(rawPath)
+                    ? path.normalize(rawPath)
+                    : projectRoot
+                        ? path.resolve(projectRoot, rawPath)
+                        : null;
+                if (full) {
+                    if (action.tool === 'local_edit_file') {
+                        const diff = editDiffOf(action.result);
+                        if (diff !== null) {
+                            const diffStats = parseDiffStats(diff);
+                            const prev = statsByPath.get(full) ?? { additions: 0, deletions: 0 };
+                            statsByPath.set(full, {
+                                additions: prev.additions + diffStats.additions,
+                                deletions: prev.deletions + diffStats.deletions,
+                            });
+                        }
+                    }
+                    else if (action.tool === 'local_write_file') {
+                        if (typeof args?.content === 'string') {
+                            const lineCount = args.content ? args.content.split('\n').length : 0;
+                            statsByPath.set(full, { additions: lineCount, deletions: 0 });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const enriched = [];
+    for (const file of byPath.values()) {
+        const base = path.basename(file.path);
+        if (isIgnoredFileName(base))
+            continue;
+        const stats = statsByPath.get(file.path);
+        const declared = presented.get(file.path);
+        // 本轮有声明时以声明为准；没有声明（旧模型、未调用）才退回扩展名规则。
+        const category = presented.size > 0
+            ? declared
+                ? 'deliverable'
+                : 'intermediate'
+            : classifyFileCategory(file.path);
+        enriched.push({
+            ...file,
+            category,
+            ...(declared?.description ? { description: declared.description } : {}),
+            ...(stats ? { additions: stats.additions, deletions: stats.deletions } : {}),
+        });
+    }
+    return enriched
         .sort((a, b) => a.path.localeCompare(b.path))
         .slice(0, MAX_FILES);
 }
@@ -134,7 +264,7 @@ async function walk(dir, sinceMs, depth, state, out) {
             await walk(full, sinceMs, depth + 1, state, out);
             continue;
         }
-        if (!entry.isFile() || IGNORED_FILE_NAMES.has(entry.name))
+        if (!entry.isFile() || isIgnoredFileName(entry.name))
             continue;
         const file = await statTurnFile(full, sinceMs);
         if (file)
@@ -152,7 +282,7 @@ async function statTurnFile(full, sinceMs) {
         return null;
     }
     // 路径字面量可能指到目录（如 xxx.app 包）；产物列表只收文件。
-    if (!stat.isFile())
+    if (!stat.isFile() || isIgnoredFileName(path.basename(full)))
         return null;
     const touched = stat.mtimeMs + TOUCHED_SLACK_MS >= sinceMs ||
         stat.birthtimeMs + TOUCHED_SLACK_MS >= sinceMs;
@@ -160,6 +290,33 @@ async function statTurnFile(full, sinceMs) {
         return null;
     return { path: full, kind: kindOf(stat, sinceMs), size: stat.size };
 }
+/** 声明的交付文件只要求仍是普通文件；本轮没动过的已有文件标 modified。 */
+async function statPresentedFile(full) {
+    let stat;
+    try {
+        stat = await fs.stat(full);
+    }
+    catch {
+        // 声明后到回合收尾之间被删掉：不再列出。
+        return null;
+    }
+    if (!stat.isFile())
+        return null;
+    return { path: full, kind: 'modified', size: stat.size };
+}
+/** local_edit_file 的 diff：直连结果在顶层，经 sidecar 回流的结果折进 `data`。 */
+function editDiffOf(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const record = result;
+    if (typeof record.diff === 'string')
+        return record.diff;
+    const data = record.data;
+    if (data && typeof data === 'object' && typeof data.diff === 'string') {
+        return data.diff;
+    }
+    return null;
+}
 function kindOf(stat, sinceMs) {
     // birthtime 不可用的文件系统返回 0/负值——此时无法区分新建与修改，
     // 统一标 modified（标签降级，不漏文件）。
@@ -232,7 +389,7 @@ async function scanShallow(dir, sinceMs, out) {
         return;
     }
     for (const entry of entries) {
-        if (entry.name.startsWith('.') || IGNORED_FILE_NAMES.has(entry.name))
+        if (entry.name.startsWith('.') || isIgnoredFileName(entry.name))
             continue;
         if (entry.isSymbolicLink() || !entry.isFile())
             continue;

package/dist/present-files.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `present_files`：模型声明本轮的最终交付文件。
+ *
+ * 回合产物列表（turn-files）把声明过的文件渲染成交付卡片，其余本轮写过的
+ * 文件归入「Edited N files」。只看扩展名分不清交付物与检查用的预览图、
+ * 导出副本，所以由模型显式声明。工具只 stat 元数据、不读内容，也不复制
+ * 文件——用户打开的是源文件当前版本。
+ */
+export declare const PRESENT_FILES_TOOL_NAME = "present_files";
+export declare const PRESENT_FILES_SCHEMA: {
+    name: string;
+    description: string;
+    mode: "read";
+    inputSchema: {
+        type: string;
+        properties: {
+            files: {
+                type: string;
+                minItems: number;
+                maxItems: number;
+                description: string;
+                items: {
+                    type: string;
+                    properties: {
+                        path: {
+                            type: string;
+                            description: string;
+                        };
+                        description: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                };
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+};
+export interface PresentedFile {
+    path: string;
+    description?: string;
+}
+/**
+ * 把参数里的路径解析成绝对路径：展开 `~/`，相对路径按项目根解析；
+ * 无项目根的相对路径无法定位，返回 null。
+ */
+export declare function resolvePresentedPath(raw: string, projectRoot: string | null, homeDir?: string): string | null;
+/** 从工具参数里取出声明的文件（不校验存在性）；形状不符的条目跳过。 */
+export declare function readPresentedArgs(args: unknown, projectRoot: string | null, homeDir?: string): PresentedFile[];
+/**
+ * 执行 `present_files`：每个路径必须是已存在的普通文件。任一路径不合格时
+ * 整次调用失败并逐个说明原因，模型可以修正后重试。
+ */
+export declare function executePresentFiles(args: Record<string, unknown>, projectRoot: string | null): Promise<{
+    success: true;
+    presented: PresentedFile[];
+} | {
+    success: false;
+    error: string;
+}>;

package/dist/present-files.js

@@ -0,0 +1,136 @@
+/**
+ * `present_files`：模型声明本轮的最终交付文件。
+ *
+ * 回合产物列表（turn-files）把声明过的文件渲染成交付卡片，其余本轮写过的
+ * 文件归入「Edited N files」。只看扩展名分不清交付物与检查用的预览图、
+ * 导出副本，所以由模型显式声明。工具只 stat 元数据、不读内容，也不复制
+ * 文件——用户打开的是源文件当前版本。
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+export const PRESENT_FILES_TOOL_NAME = 'present_files';
+/** 单次调用最多声明的文件数；交付卡片过多就失去「最终结果」的意义。 */
+const MAX_PRESENTED_FILES = 4;
+export const PRESENT_FILES_SCHEMA = {
+    name: PRESENT_FILES_TOOL_NAME,
+    description: 'Declare existing local files as the final deliverables of this turn. ' +
+        'When a file you created or updated is an output the user asked to receive ' +
+        '(spreadsheet, slide deck, document, report, image, exported archive), call this after writing it ' +
+        'and before your final reply, including files produced by scripts or commands. ' +
+        'Do not present helper scripts, scratch files, render previews made only to check your work, ' +
+        'or intermediate exports. Files you write but do not present are still listed to the user as edited files.',
+    mode: 'read',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            files: {
+                type: 'array',
+                minItems: 1,
+                maxItems: MAX_PRESENTED_FILES,
+                description: `Usually the 1-2 most important deliverables; at most ${MAX_PRESENTED_FILES}.`,
+                items: {
+                    type: 'object',
+                    properties: {
+                        path: {
+                            type: 'string',
+                            description: 'Absolute path, or a path relative to the project root.',
+                        },
+                        description: {
+                            type: 'string',
+                            description: 'Optional one-line summary shown on the file card.',
+                        },
+                    },
+                    required: ['path'],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ['files'],
+        additionalProperties: false,
+    },
+};
+/**
+ * 把参数里的路径解析成绝对路径：展开 `~/`，相对路径按项目根解析；
+ * 无项目根的相对路径无法定位，返回 null。
+ */
+export function resolvePresentedPath(raw, projectRoot, homeDir = os.homedir()) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const expanded = trimmed === '~' || trimmed.startsWith('~/')
+        ? path.join(homeDir, trimmed.slice(1))
+        : trimmed;
+    if (path.isAbsolute(expanded))
+        return path.normalize(expanded);
+    return projectRoot ? path.resolve(projectRoot, expanded) : null;
+}
+/** 从工具参数里取出声明的文件（不校验存在性）；形状不符的条目跳过。 */
+export function readPresentedArgs(args, projectRoot, homeDir) {
+    if (!args || typeof args !== 'object')
+        return [];
+    const files = args.files;
+    if (!Array.isArray(files))
+        return [];
+    const out = [];
+    for (const item of files) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const record = item;
+        if (typeof record.path !== 'string')
+            continue;
+        const resolved = resolvePresentedPath(record.path, projectRoot, homeDir);
+        if (!resolved)
+            continue;
+        const description = typeof record.description === 'string' ? record.description.trim() : '';
+        out.push({ path: resolved, ...(description ? { description } : {}) });
+    }
+    return out;
+}
+/**
+ * 执行 `present_files`：每个路径必须是已存在的普通文件。任一路径不合格时
+ * 整次调用失败并逐个说明原因，模型可以修正后重试。
+ */
+export async function executePresentFiles(args, projectRoot) {
+    const rawFiles = Array.isArray(args.files) ? args.files : [];
+    if (rawFiles.length === 0) {
+        return { success: false, error: 'files must list at least one file to present.' };
+    }
+    if (rawFiles.length > MAX_PRESENTED_FILES) {
+        return {
+            success: false,
+            error: `Present at most ${MAX_PRESENTED_FILES} files per call; keep only the final deliverables.`,
+        };
+    }
+    const problems = [];
+    const presented = [];
+    for (const item of rawFiles) {
+        const raw = item && typeof item === 'object' && typeof item.path === 'string'
+            ? item.path
+            : '';
+        const [file] = readPresentedArgs({ files: [item] }, projectRoot);
+        if (!file) {
+            problems.push(raw
+                ? `${raw}: use an absolute path (no project root to resolve a relative path).`
+                : 'each entry needs a non-empty path.');
+            continue;
+        }
+        try {
+            const stat = await fs.stat(file.path);
+            if (!stat.isFile()) {
+                problems.push(`${file.path}: not a regular file.`);
+                continue;
+            }
+        }
+        catch {
+            // stat 失败（多为 ENOENT）：报给模型让它先写文件或修正路径。
+            problems.push(`${file.path}: file not found. Create it first or fix the path.`);
+            continue;
+        }
+        presented.push(file);
+    }
+    if (problems.length > 0) {
+        return { success: false, error: `Cannot present: ${problems.join(' ')}` };
+    }
+    return { success: true, presented };
+}

package/dist/product-config.d.ts

@@ -66,6 +66,10 @@ export interface ProductConfig {
      * 设置入口。缺省全开。`false` 藏对应侧栏页或综合设置分段。
      */
     settings?: Record<string, boolean>;
+    /**
+     * 对话与配置的导出/导入。缺省关。只有显式 `true` 的产品才有入口和接口。
+     */
+    portable?: boolean;
     /**
      * 产品钉死的大模型。`settings.llm === false` 时必填，运行时用这份，
      * 不再读设置页。密钥用 `apiKeyEnv` 指向环境变量，不要把 key 写进仓库。
@@ -105,6 +109,8 @@ export interface ProductConfig {
 }
 /** shell 内置智能体：只有产品显式 `true` 才开。 */
 export declare function isShellBuiltinAgentEnabled(id: 'local-assistant' | 'all-round-assistant', config?: ProductConfig): boolean;
+/** 对话与配置能否导出/导入。缺省关，产品必须显式打开。 */
+export declare function isPortableProduct(config?: ProductConfig): boolean;
 /** shell 内置技能：`true` 全开；否则只有对象里显式 `true` 的目录开。 */
 export declare function isShellBuiltinSkillEnabled(id: string, config?: ProductConfig): boolean;
 /**

package/dist/product-config.js

@@ -13,6 +13,10 @@
 export function isShellBuiltinAgentEnabled(id, config = getProductConfig()) {
     return config.builtinAgents?.[id] === true;
 }
+/** 对话与配置能否导出/导入。缺省关，产品必须显式打开。 */
+export function isPortableProduct(config = getProductConfig()) {
+    return config.portable === true;
+}
 /** shell 内置技能：`true` 全开；否则只有对象里显式 `true` 的目录开。 */
 export function isShellBuiltinSkillEnabled(id, config = getProductConfig()) {
     const value = config.builtinSkills;

package/dist/sidecar/boot.d.ts

@@ -1,3 +1,4 @@
+import { SidecarSupervisor } from './supervisor.js';
 import type { ScopedStore } from '../storage/scoped-store.js';
 import { type ToolRouter } from '../tool-router.js';
 import type { createApprovalBridge } from './reverse-approval.js';
@@ -28,10 +29,24 @@ export interface HostSidecarDeps {
     onLogLine?: (line: string) => void;
 }
 /**
- * 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 declare function wirePluginRegistry(supervisor: Pick<SidecarSupervisor, 'call' | 'invokeTool'>, toolRouter: ToolRouter): Promise<void>;
+/**
+ * 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 declare function startHostSidecar(deps: HostSidecarDeps): Promise<void>;
 /** 宿主退出钩子：停 supervisor + egress proxy。幂等。 */

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 { rustSidecarEnabled, 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';
@@ -159,17 +159,42 @@ 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 = !rustSidecarEnabled() || Boolean(pythonRunner);
+    const runCodeEnabled = true;
     // ready 后的完整接线：注册全局 handle + reverse channels + web 工具握手。
     // 正常 boot 路径与「boot 失败后后台 restart 迟到就绪」路径共用。
     const wireSupervisor = async (supervisor) => {
@@ -259,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());
@@ -332,19 +355,13 @@ export async function startHostSidecar(deps) {
             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);

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.
  *
@@ -218,10 +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 Rust sidecar binary from an explicit path, a packaged engine,
- * or a framework source checkout. Boot fails when Rust was explicitly
- * enabled but no binary resolves.
- */
-export declare function resolveRustSidecarBin(explicit?: string): string | undefined;