@steerable/agent-shell 0.6.36 → 0.6.37

package/dist/attachments.d.ts

@@ -20,6 +20,12 @@ export interface StoredAttachment {
     error?: string;
 }
 export declare function isValidChatAttachmentsKey(chatId: string): boolean;
+/**
+ * 当前会话的附件目录路径，**不创建目录**（供拼系统提示等只读场景使用）。
+ * chatId 非法时仍然返回路径但由调用方在写入前用
+ * {@link isValidChatAttachmentsKey} 校验。
+ */
+export declare function chatAttachmentsDirPath(chatId: string): string;
 /**
  * 当前会话的附件目录（会确保目录存在）。chatId 非法时仍然返回路径但由
  * 调用方在写入前用 {@link isValidChatAttachmentsKey} 校验。

package/dist/attachments.js

@@ -31,12 +31,20 @@ const SAFE_CHAT_ID = /^[0-9a-zA-Z_-]{1,64}$/;
 export function isValidChatAttachmentsKey(chatId) {
     return SAFE_CHAT_ID.test(chatId);
 }
+/**
+ * 当前会话的附件目录路径，**不创建目录**（供拼系统提示等只读场景使用）。
+ * chatId 非法时仍然返回路径但由调用方在写入前用
+ * {@link isValidChatAttachmentsKey} 校验。
+ */
+export function chatAttachmentsDirPath(chatId) {
+    return path.join(getUserDataDir(), ATTACHMENTS_DIR_NAME, chatId);
+}
 /**
  * 当前会话的附件目录（会确保目录存在）。chatId 非法时仍然返回路径但由
  * 调用方在写入前用 {@link isValidChatAttachmentsKey} 校验。
  */
 export function getChatAttachmentsDir(chatId) {
-    const dir = path.join(getUserDataDir(), ATTACHMENTS_DIR_NAME, chatId);
+    const dir = chatAttachmentsDirPath(chatId);
     mkdirSync(dir, { recursive: true });
     return dir;
 }

package/dist/local-backend/ai-suggestions.d.ts

@@ -1,14 +1,21 @@
 /**
  * 回合结束后生成「下一轮用户输入」建议。
  *
- * 只走一次短 LLM 调用。判断来源只有助手给用户的下一步：
+ * 主路径只走一次短 LLM 调用。判断来源只有助手给用户的下一步：
  * `[next_steps]...[/next_steps]` 标签，或回复最后一段里的建议。
- * 不做规则抽取、不按 PPT/计划/代码套模板。永不抛错。
+ * 永不抛错；没有真实下一步时不展示建议。
+ *
+ * 项目分支额外保留两类保障：
+ * - 正文里显式承诺的下一步指令（如「请回复：确认内容」）始终排在最前，
+ *   不依赖模型是否稳定产出；
+ * - 长回复按头 + 尾截断，避免只看头部时丢掉结尾处的邀请。
  *
  * 调用方应该 fire-and-forget，且只广播一次最终结果。
  * 不要挂在 SSE 主流程里阻塞 `[DONE]`。
  */
 export declare const SUGGESTED_REPLY_MAX = 8;
+/** 项目分支历史上建议芯片固定最多 3 条，生成入口继续沿用该上限。 */
+export declare const SUGGESTED_REPLY_COUNT = 3;
 /**
  * 建议芯片的判断来源：有 `[next_steps]` 用最后一段标签正文，否则用回复最后一段。
  */
@@ -20,9 +27,23 @@ export declare function cleanSuggestedReply(raw: string): string;
  * 最多 {@link SUGGESTED_REPLY_MAX} 条。
  */
 export declare function parseSuggestedReplies(raw: string): string[];
+/**
+ * 助手正文里显式写出的下一步指令（「请回复：确认内容」/「回复「确认内容」」）。
+ *
+ * 这是角色提示词对下一轮用户输入的**明确承诺**，对应的按钮必须原样出现：
+ * 不能交给追问建议模型自由改写（长回复被截断、模型跑偏都会让按钮消失）。
+ * 只认「请回复：X」「回复「X」」这两种窄格式，X 为 2-12 字的短标签，
+ * 避免把正文里的普通引用误当成按钮。
+ */
+export declare function explicitReplyHints(assistantText: string): string[];
+/**
+ * 不调模型的启发式三条。PPT / 计划 / 代码有专用句子，其它走通用。
+ * 该函数作为项目分支的兼容能力保留；新的生成主路径不再依赖它兜底。
+ */
+export declare function fallbackSuggestedReplies(userText: string, assistantText: string): string[];
 export interface GenerateSuggestedRepliesResult {
     suggestions: string[];
-    /** true = LLM 失败、超时或输出不合格；suggestions 为空。空数组本身算有效判断。 */
+    /** true = LLM 失败、超时或输出不合格；suggestions 为空或仅剩显式回复提示。 */
     usedFallback: boolean;
 }
 export interface GenerateSuggestedRepliesOptions {

package/dist/local-backend/ai-suggestions.js

@@ -1,15 +1,22 @@
 /**
  * 回合结束后生成「下一轮用户输入」建议。
  *
- * 只走一次短 LLM 调用。判断来源只有助手给用户的下一步：
+ * 主路径只走一次短 LLM 调用。判断来源只有助手给用户的下一步：
  * `[next_steps]...[/next_steps]` 标签，或回复最后一段里的建议。
- * 不做规则抽取、不按 PPT/计划/代码套模板。永不抛错。
+ * 永不抛错；没有真实下一步时不展示建议。
+ *
+ * 项目分支额外保留两类保障：
+ * - 正文里显式承诺的下一步指令（如「请回复：确认内容」）始终排在最前，
+ *   不依赖模型是否稳定产出；
+ * - 长回复按头 + 尾截断，避免只看头部时丢掉结尾处的邀请。
  *
  * 调用方应该 fire-and-forget，且只广播一次最终结果。
  * 不要挂在 SSE 主流程里阻塞 `[DONE]`。
  */
 import { llmService } from '../llm/index.js';
 export const SUGGESTED_REPLY_MAX = 8;
+/** 项目分支历史上建议芯片固定最多 3 条，生成入口继续沿用该上限。 */
+export const SUGGESTED_REPLY_COUNT = 3;
 const MAX_SUGGESTION_CHARS = 48;
 const USER_TEXT_LIMIT = 500;
 const SOURCE_LIMIT = 2000;
@@ -26,7 +33,8 @@ const SYSTEM_PROMPT = `你是对话追问建议助手。根据「下一步来源
 3. 不要编造，不要用「继续完善这份结果」「告诉我下一步怎么做」这类套话凑数。
 4. 有几条真实下一步就给几条，最少 0 条，最多 8 条。
 5. 每条 6-40 个字。不要编号、不要引号、不要解释、不要附带命令行或绝对路径。
-6. 只输出 JSON 字符串数组，例如 ["把封面改成深蓝商务风","第2页个人简介写具体"]`;
+6. 只输出 JSON 字符串数组，例如 ["把封面改成深蓝商务风","第2页个人简介写具体"]
+7. 如果下一步来源显示任务尚未完成、校验/验证未通过、或助手在问「是否继续」，第一条建议必须是继续完成任务的短指令。`;
 const LIST_ITEM_RE = /^(?:\d+[.)、]|[-*•])\s+(\S.*)$/;
 function withTimeout(promise, timeoutMs, label) {
     if (timeoutMs <= 0)
@@ -50,6 +58,18 @@ function clip(text, limit) {
         return chars.join('');
     return `${chars.slice(0, limit).join('')}…`;
 }
+/**
+ * 长文本截断（头 + 尾）。助手回复的**结尾**才是结论与下一步邀请所在
+ * （例如「以上初稿已生成完毕。如需继续，请回复：确认内容」）；只取头部会让
+ * 追问建议模型看不到邀请。头部保留话题上下文，尾部保留收尾邀请，两头各取一半。
+ */
+function clipHeadTail(text, limit) {
+    const chars = Array.from((text ?? '').trim());
+    if (chars.length <= limit)
+        return chars.join('');
+    const head = Math.floor(limit / 2);
+    return `${chars.slice(0, head).join('')}…${chars.slice(-(limit - head)).join('')}`;
+}
 function lastParagraph(text) {
     const trimmed = (text ?? '').trim();
     if (!trimmed)
@@ -140,15 +160,92 @@ export function parseSuggestedReplies(raw) {
     const listLines = lines.filter((line) => isListItem(line));
     return uniqueSuggestions(listLines.length > 0 ? listLines : lines);
 }
+function uniqueThree(candidates, extras = []) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of [...candidates, ...extras]) {
+        const cleaned = cleanSuggestedReply(raw);
+        if (!cleaned || seen.has(cleaned))
+            continue;
+        seen.add(cleaned);
+        out.push(cleaned);
+        if (out.length === SUGGESTED_REPLY_COUNT)
+            break;
+    }
+    return out;
+}
+/**
+ * 助手正文里显式写出的下一步指令（「请回复：确认内容」/「回复「确认内容」」）。
+ *
+ * 这是角色提示词对下一轮用户输入的**明确承诺**，对应的按钮必须原样出现：
+ * 不能交给追问建议模型自由改写（长回复被截断、模型跑偏都会让按钮消失）。
+ * 只认「请回复：X」「回复「X」」这两种窄格式，X 为 2-12 字的短标签，
+ * 避免把正文里的普通引用误当成按钮。
+ */
+export function explicitReplyHints(assistantText) {
+    const out = [];
+    const text = assistantText ?? '';
+    const push = (raw) => {
+        const cleaned = cleanSuggestedReply(raw);
+        if (cleaned && Array.from(cleaned).length <= 12 && !out.includes(cleaned)) {
+            out.push(cleaned);
+        }
+    };
+    for (const match of text.matchAll(/请回复[：:][ \t]*([^\n，。；、,.;!?！？]{2,12})/g)) {
+        push(match[1]);
+    }
+    for (const match of text.matchAll(/回复[「『“"]([^」』”"\n]{2,12})[」』”"]/g)) {
+        push(match[1]);
+    }
+    return out.slice(0, SUGGESTED_REPLY_COUNT);
+}
+const PPT_FALLBACK = ['调整封面标题和配色', '把某一页内容写得更具体', '再加一页项目案例'];
+const PLAN_FALLBACK = ['按这个计划开始执行', '先改第 2 步再执行', '把计划写得更细一点'];
+const CODE_FALLBACK = ['解释这段实现的思路', '帮我补上测试', '再优化一下可读性'];
+const GENERIC_FALLBACK = ['继续完善这份结果', '换一种呈现方式', '告诉我下一步怎么做'];
+const PPT_OFFER_FALLBACK = ['调整幻灯片的内容和文案', '调整配色和版式', '再加一页补充材料'];
+const PPT_INCOMPLETE_FALLBACK = [
+    '继续修复并生成 PPT 预览稿',
+    '按当前方案继续生成 PPT 预览',
+    '先修正配置再继续生成预览稿',
+];
+/**
+ * 不调模型的启发式三条。PPT / 计划 / 代码有专用句子，其它走通用。
+ * 该函数作为项目分支的兼容能力保留；新的生成主路径不再依赖它兜底。
+ */
+export function fallbackSuggestedReplies(userText, assistantText) {
+    const blob = `${userText}\n${assistantText}`;
+    if (/\.pptx\b|幻灯片|演示文稿|\bppt\b/i.test(blob)) { // shell-neutral:allow — Office 扩展名 'ppt'/'.pptx'，不是产品品牌
+        // PPT 任务未完成：校验未通过、预览稿未生成、助手在问是否继续时，
+        // 第一条建议必须是可以直接点发、继续把 PPT 预览稿生成出来的指令。
+        if (/svg_output|SVG\s*预览|预览.{0,12}(?:未|没有|为空|尚未)|验证.{0,12}(?:未通过|失败|错误)|校验.{0,12}(?:未通过|失败|错误)|是否继续|请确认是否继续/.test(assistantText)) {
+            return uniqueThree(PPT_INCOMPLETE_FALLBACK, PPT_FALLBACK);
+        }
+        if (/修改内容|调整样式/.test(assistantText)) {
+            return uniqueThree(PPT_OFFER_FALLBACK, PPT_FALLBACK);
+        }
+        return uniqueThree(PPT_FALLBACK, GENERIC_FALLBACK);
+    }
+    if (/标准工作流程|待办清单|\bTODO\b|先制定计划/.test(blob) || /^\s*计划已/.test(assistantText)) {
+        return uniqueThree(PLAN_FALLBACK, GENERIC_FALLBACK);
+    }
+    if (/```|单元测试|函数实现|补测试/.test(blob)) {
+        return uniqueThree(CODE_FALLBACK, GENERIC_FALLBACK);
+    }
+    return uniqueThree(GENERIC_FALLBACK);
+}
 /**
  * 生成本轮追问建议。永不抛错；没有下一步来源或模型判定没有下一步时返回空数组。
  */
 export async function generateSuggestedReplies(userText, assistantText, opts = {}) {
+    // 正文里显式承诺的下一步指令（如「确认内容」）始终排在最前，优先级高于
+    // LLM 自由生成的建议——按钮不能时有时无。
+    const hints = explicitReplyHints(assistantText);
     const source = extractNextStepsSource(assistantText);
     const user = clip(userText, USER_TEXT_LIMIT);
-    const sourceClip = clip(source, SOURCE_LIMIT);
+    const sourceClip = clipHeadTail(source, SOURCE_LIMIT);
     if (!sourceClip) {
-        return { suggestions: [], usedFallback: false };
+        return { suggestions: uniqueThree(hints), usedFallback: false };
     }
     const perAttemptTimeoutMs = opts.perAttemptTimeoutMs ?? 12_000;
     try {
@@ -164,8 +261,12 @@ export async function generateSuggestedReplies(userText, assistantText, opts = {
         }), perAttemptTimeoutMs, 'ai-suggestions');
         const raw = result.content ?? '';
         const parsed = parseSuggestedReplies(raw);
-        if (parsed.length > 0) {
-            return { suggestions: parsed, usedFallback: false };
+        // 显式承诺的那条已经在 hints 里了；模型经常再产出一条「确认内容，按这版继续」
+        // 这类包含同一指令的变体，去掉，给真正的修改建议腾位置。
+        const withoutHintEchoes = parsed.filter((item) => !hints.some((hint) => item.includes(hint)));
+        const suggestions = uniqueThree([...hints, ...withoutHintEchoes]);
+        if (suggestions.length > 0) {
+            return { suggestions, usedFallback: false };
         }
         if (Array.isArray(sliceJsonArray(raw))) {
             return { suggestions: [], usedFallback: false };
@@ -174,6 +275,6 @@ export async function generateSuggestedReplies(userText, assistantText, opts = {
     }
     catch (err) {
         console.warn('[ai-suggestions] LLM 追问建议失败，不展示建议', err);
-        return { suggestions: [], usedFallback: true };
+        return { suggestions: uniqueThree(hints), usedFallback: true };
     }
 }

package/dist/local-backend/coreloop-stream.d.ts

@@ -1,5 +1,5 @@
 /**
- * A4: drive one chat turn through the sidecar-hosted Python CoreLoop.
+ * A4: drive one chat turn through the sidecar-hosted Rust CoreLoop.
  *
  * This is the default chat path (since 2026-08-26): the sidecar owns
  * think→act→observe, and tool calls come back over the reverse channel

package/dist/local-backend/coreloop-stream.js

@@ -1,5 +1,5 @@
 /**
- * A4: drive one chat turn through the sidecar-hosted Python CoreLoop.
+ * A4: drive one chat turn through the sidecar-hosted Rust CoreLoop.
  *
  * This is the default chat path (since 2026-08-26): the sidecar owns
  * think→act→observe, and tool calls come back over the reverse channel

package/dist/local-backend/router.js

@@ -39,6 +39,7 @@ import { resolveBranchActivation } from './branch-helper.js';
 import { detectInterruptedTurn } from './interrupted-helper.js';
 import { dropCurrentUserMessage } from './history-helper.js';
 import { parseImageAttachments, processImageAttachments } from '../image-attachment.js';
+import { chatAttachmentsDirPath } from '../attachments.js';
 import { loadProjectRuleFiles } from '../project-rules.js';
 import { allocateProjectHome, ensureChatWorkspace, ensureProjectHome, expandUserPath, } from '../project-home.js';
 import { registerLiveStream, getLiveStream, removeLiveStream } from './live-stream.js';
@@ -2435,7 +2436,11 @@ export class LocalBackendRouter {
                         ? `另有源文件夹（只读）：${chatProject.sourceFolders.join('、')}。`
                         : '') +
                     `请一律使用项目目录内的路径（相对路径按家目录解析）。` +
-                    `如确需访问项目外的文件，向用户说明该限制，或请其在项目里附加为源文件夹。`;
+                    `如确需读取项目外的文件，可请用户在项目里附加为源文件夹。\n` +
+                    `例外：本会话的用户上传附件目录 ${chatAttachmentsDirPath(chatId)} 也在项目家目录外，` +
+                    `但它已作为**只读放行根**开放给 local_read_file（用绝对路径可直接读取，不会被项目围栏拒绝）。` +
+                    `用户附到本条消息的文件都放在那里；需要转换（docx / pdf / xlsx / pptx 等）时，` +
+                    `把该绝对路径交给 local_exec_shell 的转换脚本处理即可，**不要**因为它在项目家目录外就拒绝读取或要求用户重新拷贝。`;
             // W6-5 + W6-7a：项目级规则文件（AGENTS.md / CLAUDE.md）是不可信输入，
             // 仅在用户显式信任该项目后才注入模型上下文——未信任一律不读取、不注入
             // （打开恶意仓库时，一段构造的规则文件不能劫持 agent）。信任状态持久化、

package/dist/main.js

@@ -208,7 +208,7 @@ function applyStrictCsp() {
             "img-src 'self' data: blob:",
             "style-src 'self' 'unsafe-inline'",
             "script-src 'self' 'unsafe-eval' 'unsafe-inline'",
-            "font-src 'self' data:",
+            "font-src 'self' data: blob:",
         ].join('; ');
         callback({
             responseHeaders: {

package/dist/server/http-server.js

@@ -43,7 +43,23 @@ const STREAM_PATH_PATTERNS = [
     /^\/api\/v2\/chats\/[^/]+\/(send|run|agent)$/,
     /^\/api\/v2\/chats\/[^/]+\/messages\/[^/]+\/regenerate$/,
 ];
-const MAX_BODY_BYTES = 25 * 1024 * 1024;
+/**
+ * 请求体上限。会话附件（`/host/attachments/save`）在浏览器模式走 base64，
+ * 相对原始字节膨胀约 4/3，所以这里必须比 `ATTACHMENT_MAX_BYTES`（25MB，
+ * 按**解码后**字节校验）留出足够 headroom，否则一个合法的 20MB 文件也会
+ * 在进到 saveAttachmentFiles 之前就被 body 上限挡掉。批量多个文件共享同一
+ * 上限（超出返回 413，前端据此提示用户分开上传）。
+ */
+const MAX_BODY_BYTES = 64 * 1024 * 1024;
+/** body 超限专用错误：外层据此回 413 + 可读原因，而不是笼统的 500。 */
+class BodyTooLargeError extends Error {
+    limit;
+    constructor(limit) {
+        super(`request body too large (max ${Math.round(limit / 1024 / 1024)}MB)`);
+        this.limit = limit;
+        this.name = 'BodyTooLargeError';
+    }
+}
 const MIME = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'text/javascript; charset=utf-8',
@@ -79,7 +95,7 @@ async function readJsonBody(req) {
     for await (const chunk of req) {
         size += chunk.length;
         if (size > MAX_BODY_BYTES)
-            throw new Error('request body too large');
+            throw new BodyTooLargeError(MAX_BODY_BYTES);
         chunks.push(chunk);
     }
     if (chunks.length === 0)
@@ -432,6 +448,16 @@ export function createBsServer(deps) {
             }
             sendJson(res, 404, { detail: 'not found' });
         })().catch((err) => {
+            // body 超限是可预期的客户端问题（附件太大/一次传太多），回 413 +
+            // 可读原因，让前端把它显示给用户，而不是笼统的 500 "internal error"。
+            if (err instanceof BodyTooLargeError) {
+                log.warn('[bs] request body too large', { url: req.url, limit: err.limit });
+                if (!res.headersSent)
+                    sendJson(res, 413, { detail: err.message });
+                else
+                    res.end();
+                return;
+            }
             log.error('[bs] unhandled request error', err);
             if (!res.headersSent)
                 sendJson(res, 500, { detail: 'internal error' });

package/dist/sidecar/boot.js

@@ -7,15 +7,16 @@
  * 由宿主的退出钩子调用（Electron before-quit / BS SIGTERM）。
  */
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import log from 'electron-log';
-import { SidecarSupervisor, resolveSidecarPython } 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';
 import { createToolInvokeHandler } from './reverse-tools.js';
 import { createProcessSpawnHandler } from './reverse-spawn.js';
 import { collectAmbientProxyEndpoints } from './proxy-detect.js';
-import { buildEgressProxyPlan, decideEgressProxy, deriveWebEgressHosts, pickFreePort, recordEgressPosture, startEgressProxy, } from './egress-proxy.js';
+import { buildEgressProxyPlan, decideEgressProxy, ensureEgressProxyExecutable, deriveWebEgressHosts, pickFreePort, recordEgressPosture, startEgressProxy, } from './egress-proxy.js';
 import { WEB_TOOL_RPC_TIMEOUT_MS, webToolsEnabled } from '../tool-router.js';
 import { sidecarWebSearchEnv } from '../storage/web-search-settings.js';
 import { executeHostedWebSearch } from '../hosted-web-search.js';
@@ -48,7 +49,7 @@ async function deriveSidecarEgressAllowList() {
 }
 /**
  * W1.3.3（3.1a 起默认开）：把 sidecar 出网收敛到本机
- * steerable_egress_proxy。显式 `STEERABLE_EGRESS_PROXY=0` 退出。
+ * steerable-egress-proxy 二进制。显式 `STEERABLE_EGRESS_PROXY=0` 退出。
  *
  * 两类自动回退到旧的 Seatbelt 端口级派生路径（加固永远不能弄断 LLM
  * 通路）：
@@ -78,8 +79,17 @@ async function startEgressProxyIfEnabled(store) {
             storedProvider: searchSettings?.provider,
             llmBaseUrl: settings.baseUrl,
         });
+        const executable = await ensureEgressProxyExecutable(path.dirname(fileURLToPath(import.meta.url)));
+        if (!executable) {
+            log.warn('[egress-proxy] steerable-egress-proxy binary was not found; staying on port-level enforcement');
+            recordEgressPosture({
+                mode: 'port-only-fallback',
+                reason: '未找到 steerable-egress-proxy 二进制，按主机管控未启用',
+            });
+            return null;
+        }
         const plan = buildEgressProxyPlan({
-            pythonExecutable: resolveSidecarPython(),
+            executable,
             port: await pickFreePort(),
             providerBaseUrl: settings.baseUrl,
             providerApiKey: settings.apiKey || undefined,

package/dist/sidecar/egress-proxy.d.ts

@@ -1,5 +1,5 @@
 /**
- * W1.3.3：桌面宿主内嵌 `steerable_egress_proxy` 的启动器。
+ * 桌面宿主启动闭源 `steerable-egress-proxy` 二进制的启动器。
  *
  * 默认态势（3.1a，2026-09-08 起默认开）：sidecar 出网收敛到本机代理，
  * Seatbelt 列表只放行代理端口，真正的主机名单由代理进程持有（代理跑在
@@ -71,8 +71,30 @@ export declare function egressAllowEntry(baseUrl: string | undefined): {
  * null（调用方回退到旧的 Seatbelt 派生路径——空名单的代理没有意义，
  * 框架侧也会 fail loud）。
  */
+export declare function resolveEgressProxyExecutable(): string | null;
+/** Walk up from a compiled file until the repo that owns the fetch script. */
+export declare function findFrameworkRoot(startDir: string): string | null;
+/**
+ * 下载缓存目录。egress 代理跑在沙箱外，所以这里绝不能落在 sidecar 沙箱
+ * 可写的根（`~/.steerable`、storage path、scratch）之下——否则沙箱内
+ * 代码可以替换这个二进制，下次启动即在沙箱外执行。
+ */
+export declare function egressBinaryCacheDir(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * 缓存命中且与同目录 `.sha256` 一致时返回路径。每次启动都重新计算哈希，
+ * 被截断或替换的文件不会被执行。
+ */
+export declare function verifiedCachedEgress(cacheDir: string, version: string, target: string): string | null;
+/** Download the lockstep egress binary. Returns the printed path, or null. */
+export declare function downloadPublishedEgress(repoRoot: string, cacheDir: string): Promise<string | null>;
+/**
+ * Env override, then a locally built private binary, then a cached copy
+ * whose SHA-256 still matches, then the verified public Release asset.
+ * A missing binary stays null so boot can fall back to port-level rules.
+ */
+export declare function ensureEgressProxyExecutable(startDir: string, download?: (repoRoot: string, cacheDir: string) => Promise<string | null>, cacheDir?: string): Promise<string | null>;
 export declare function buildEgressProxyPlan(options: {
-    pythonExecutable: string;
+    executable: string;
     port: number;
     providerBaseUrl?: string;
     /** 存在且 provider 为 https 时启用凭证代理模式（W2.2.2）。 */

package/dist/sidecar/egress-proxy.js

@@ -1,5 +1,5 @@
 /**
- * W1.3.3：桌面宿主内嵌 `steerable_egress_proxy` 的启动器。
+ * 桌面宿主启动闭源 `steerable-egress-proxy` 二进制的启动器。
  *
  * 默认态势（3.1a，2026-09-08 起默认开）：sidecar 出网收敛到本机代理，
  * Seatbelt 列表只放行代理端口，真正的主机名单由代理进程持有（代理跑在
@@ -18,9 +18,13 @@
  * - 代理直连目标主机，无上游代理链。
  */
 import { spawn } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
 import { connect, createServer } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
 import { defaultSearchBaseUrl } from '../storage/web-search-settings.js';
+import { resolveSidecarPython } from './supervisor.js';
 /**
  * `baseUrl` 对应的允许条目形态：裸主机（框架侧隐含 443/80）或 `host:port`。
  *
@@ -53,8 +57,136 @@ export function egressAllowEntry(baseUrl) {
  * null（调用方回退到旧的 Seatbelt 派生路径——空名单的代理没有意义，
  * 框架侧也会 fail loud）。
  */
+export function resolveEgressProxyExecutable() {
+    const fromEnv = process.env.STEERABLE_EGRESS_PROXY_BIN?.trim();
+    return fromEnv && existsSync(fromEnv) ? fromEnv : null;
+}
+/** Walk up from a compiled file until the repo that owns the fetch script. */
+export function findFrameworkRoot(startDir) {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < 8; i += 1) {
+        if (existsSync(path.join(dir, 'scripts', 'fetch_verified_artifacts.py')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+function localBuiltEgress(repoRoot) {
+    const exe = process.platform === 'win32' ? 'steerable-egress-proxy.exe' : 'steerable-egress-proxy';
+    for (const kind of ['release', 'debug']) {
+        const candidate = path.join(repoRoot, 'packages', 'egress-proxy', 'rs', 'target', kind, exe);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * 下载缓存目录。egress 代理跑在沙箱外，所以这里绝不能落在 sidecar 沙箱
+ * 可写的根（`~/.steerable`、storage path、scratch）之下——否则沙箱内
+ * 代码可以替换这个二进制，下次启动即在沙箱外执行。
+ */
+export function egressBinaryCacheDir(platform = process.platform, env = process.env, home = os.homedir()) {
+    if (platform === 'darwin')
+        return path.join(home, 'Library', 'Caches', 'steerable', 'egress-proxy');
+    if (platform === 'win32') {
+        return path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'steerable', 'egress-proxy');
+    }
+    return path.join(env.XDG_CACHE_HOME || path.join(home, '.cache'), 'steerable', 'egress-proxy');
+}
+function hostEgressTarget() {
+    if (process.platform === 'darwin')
+        return process.arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+    if (process.platform === 'win32')
+        return process.arch === 'x64' ? 'win32-x64' : null;
+    if (process.platform === 'linux')
+        return process.arch === 'x64' ? 'linux-x64' : null;
+    return null;
+}
+function lockstepVersion(repoRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : null;
+    }
+    catch {
+        // 读不到根 package.json 就无法定位缓存文件，交给下载步骤处理。
+        return null;
+    }
+}
+/**
+ * 缓存命中且与同目录 `.sha256` 一致时返回路径。每次启动都重新计算哈希，
+ * 被截断或替换的文件不会被执行。
+ */
+export function verifiedCachedEgress(cacheDir, version, target) {
+    const name = `steerable-egress-proxy-bin-${version}-${target}${target === 'win32-x64' ? '.exe' : ''}`;
+    const binary = path.join(cacheDir, name);
+    const digestFile = `${binary}.sha256`;
+    if (!existsSync(binary) || !existsSync(digestFile))
+        return null;
+    const expected = readFileSync(digestFile, 'utf8').trim().split(/\s+/)[0]?.toLowerCase();
+    const actual = createHash('sha256').update(readFileSync(binary)).digest('hex');
+    return expected && expected === actual ? binary : null;
+}
+const EGRESS_DOWNLOAD_TIMEOUT_MS = 60_000;
+/** Download the lockstep egress binary. Returns the printed path, or null. */
+export function downloadPublishedEgress(repoRoot, cacheDir) {
+    const script = path.join(repoRoot, 'scripts', 'fetch_verified_artifacts.py');
+    // 与 sidecar 同一解释器：系统 python3 可能不带 SSL，下载不了 https。
+    const python = resolveSidecarPython();
+    return new Promise((resolve) => {
+        const child = spawn(python, [script, 'egress', '--lockstep', '--target', 'host', '--out', cacheDir], {
+            cwd: repoRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const timer = setTimeout(() => child.kill(), EGRESS_DOWNLOAD_TIMEOUT_MS);
+        let stdout = '';
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.on('error', () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            const printed = stdout.trim().split('\n').pop()?.trim();
+            if (code === 0 && printed && existsSync(printed))
+                resolve(printed);
+            else
+                resolve(null);
+        });
+    });
+}
+/**
+ * Env override, then a locally built private binary, then a cached copy
+ * whose SHA-256 still matches, then the verified public Release asset.
+ * A missing binary stays null so boot can fall back to port-level rules.
+ */
+export async function ensureEgressProxyExecutable(startDir, download = downloadPublishedEgress, cacheDir = egressBinaryCacheDir()) {
+    const fromEnv = resolveEgressProxyExecutable();
+    if (fromEnv)
+        return fromEnv;
+    const repoRoot = findFrameworkRoot(startDir);
+    if (!repoRoot)
+        return null;
+    const built = localBuiltEgress(repoRoot);
+    if (built)
+        return built;
+    const version = lockstepVersion(repoRoot);
+    const target = hostEgressTarget();
+    if (!version || !target)
+        return null;
+    const cached = verifiedCachedEgress(cacheDir, version, target);
+    if (cached)
+        return cached;
+    const downloaded = await download(repoRoot, cacheDir);
+    return downloaded && verifiedCachedEgress(cacheDir, version, target);
+}
 export function buildEgressProxyPlan(options) {
-    const { pythonExecutable, port, providerBaseUrl, providerApiKey } = options;
+    const { executable, port, providerBaseUrl, providerApiKey } = options;
     const proxiedHosts = [];
     const directHosts = [];
     let brokerHost = null;
@@ -91,10 +223,8 @@ export function buildEgressProxyPlan(options) {
         tokenValue: randomBytes(24).toString('base64url'),
     };
     return {
-        command: pythonExecutable,
+        command: executable,
         args: [
-            '-m',
-            'steerable_egress_proxy',
             '--bind',
             proxyEndpoint,
             ...proxiedHosts.flatMap((host) => ['--allow', host]),

package/dist/sidecar/types.d.ts

@@ -292,7 +292,7 @@ export interface SidecarChatStreamRequest {
     providerOptions?: Record<string, unknown>;
     /** Per-start RPC timeout (NOT per-chunk). Default 30_000ms. */
     startTimeoutMs?: number;
-    /** Route the stream through the sidecar-hosted Python CoreLoop (A4). */
+    /** Route the stream through the sidecar-hosted Rust CoreLoop (A4). */
     useCoreLoop?: boolean;
     /**
      * W7-1: continue the durable record's interrupted turn instead of opening

package/dist/storage/llm-settings.d.ts

@@ -21,9 +21,10 @@ export interface OpenAICompatOverrides {
     reasoningEchoField?: string;
     supportsForcedToolChoice?: boolean;
     /**
-     * thinking 模式下带 tool_calls 的 assistant 消息即使没产出思考，也必须
-     * 回传 reasoning 字段（空串）——DeepSeek 缺键即 400；框架按 baseUrl
-     * 自动为 api.deepseek.com 打开，这里只是允许设置页显式覆盖。
+     * thinking 模式下**所有** assistant 消息即使没产出思考，也必须回传
+     * reasoning 字段（空串）——DeepSeek 缺键即 400，不只是带 tool_calls 的
+     * 轮次；框架按 baseUrl 自动为 api.deepseek.com 打开，这里只是允许设置页
+     * 显式覆盖。
      */
     echoEmptyReasoningForToolCalls?: boolean;
     cachedTokensFields?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "Steerable framework — product-neutral desktop/headless agent host (Tier 5). Electron main + preload + headless HTTP server (BS) sharing one storage/sidecar/tooling core; scenario packs extend it through the @steerable/pack-sdk contract and are composed at build time by the consuming product.",
   "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/agent-protocol": "0.6.36",
-    "@steerable/pack-sdk": "0.6.36",
-    "@steerable/agent-harness": "0.6.36"
+    "@steerable/agent-harness": "0.6.37",
+    "@steerable/agent-protocol": "0.6.37",
+    "@steerable/pack-sdk": "0.6.37"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",