@steerable/agent-shell 0.6.20 → 0.6.22

package/dist/local-backend/worktree-service.js

@@ -49,8 +49,8 @@ export class WorktreeService {
     managedRoot(projectRoot) {
         return path.join(projectRoot, '.steerable', 'worktrees');
     }
-    requireProject(chatId) {
-        const project = this.deps.resolveProject(chatId);
+    async requireProject(chatId) {
+        const project = await this.deps.resolveProject(chatId);
         if (!project) {
             throw new Error('worktree 需要对话绑定项目（git 仓库）——请先把本对话关联到一个项目。');
         }
@@ -91,7 +91,7 @@ export class WorktreeService {
      * 同名已存在时直接复用（幂等——模型重试不该炸掉已建好的工作区）。
      */
     async createWorktree(chatId, rawName) {
-        const project = this.requireProject(chatId);
+        const project = await this.requireProject(chatId);
         await this.requireGitRepo(project.folderPath);
         const name = slugifyWorktreeName(rawName ?? '');
         const suffix = name === 'wt' ? `-${Date.now().toString(36)}` : '';
@@ -117,7 +117,7 @@ export class WorktreeService {
     }
     /** 列出本项目的托管 worktree（只认 .steerable/worktrees 下的）。 */
     async listWorktrees(chatId) {
-        const project = this.requireProject(chatId);
+        const project = await this.requireProject(chatId);
         await this.requireGitRepo(project.folderPath);
         const { stdout } = await this.git(project.folderPath, [
             'worktree',
@@ -168,7 +168,7 @@ export class WorktreeService {
      * 但默认删掉保持分支列表干净——已合并的分支删除是安全的）。
      */
     async removeWorktree(chatId, name, options = {}) {
-        const project = this.requireProject(chatId);
+        const project = await this.requireProject(chatId);
         const worktrees = await this.listWorktrees(chatId);
         const target = worktrees.find((w) => w.name === name || w.path === name);
         if (!target) {
@@ -203,7 +203,7 @@ export class WorktreeService {
      * 可稍后重试或手工处理。
      */
     async mergeWorktree(chatId, name, commitMessage) {
-        const project = this.requireProject(chatId);
+        const project = await this.requireProject(chatId);
         const worktrees = await this.listWorktrees(chatId);
         const target = worktrees.find((w) => w.name === name || w.path === name);
         if (!target) {

package/dist/main.js

@@ -39,7 +39,6 @@ const __dirname = path.dirname(__filename);
 app.setPath('userData', getUserDataDir());
 import { getActiveCoreLoopStreamId } from './local-backend/coreloop-stream.js';
 import { getSidecarSupervisor } from './llm/index.js';
-import { localStore } from './storage/index.js';
 import { createHostRuntime } from './host/runtime.js';
 import { registerPackIpc } from './host/ipc.js';
 const store = createJsonStore({ name: 'config' });
@@ -62,20 +61,16 @@ const RETRY_DELAYS = [2000, 5000, 10000, 30000];
 // 全部宿主服务由共享 HostRuntime 装配（与 BS server 同一份，见
 // src/host/runtime.ts 模块头——历史上两处逐行重复，BS 曾漏接 TaskService
 // 导致模型退化成"假后台"）。CS 的差异只剩广播（IPC）与生命周期。
-const runtime = createHostRuntime({
-    broadcast: (channel, payload) => broadcastTerminalEvent(channel, payload),
-    // LocalBackendRouter 的后台事件（目前只有 chat-title-updated）只推主窗口。
-    // 没拿到 mainWindow 时静默丢——title 是 nice-to-have，不该让启动顺序影响功能。
-    broadcastMain: (eventName, payload) => {
-        if (!mainWindow || mainWindow.isDestroyed())
-            return;
-        mainWindow.webContents.send(eventName, payload);
-    },
-    hasWindow: () => BrowserWindow.getAllWindows().some((win) => !win.isDestroyed()),
-    onLog: (line) => log.info('[sidecar]', line),
-    taskSweepReason: '应用重启，任务流已中断',
-});
-const { localExecutor, localScriptRegistry, terminalManager, packHandles, localBackendRouter, approvalBridge, askUserBridge, maybeExecInTerminal, } = runtime;
+let runtime;
+let hostStore;
+let localExecutor;
+let localScriptRegistry;
+let terminalManager;
+let packHandles;
+let localBackendRouter;
+let approvalBridge;
+let askUserBridge;
+let maybeExecInTerminal;
 let routeWindow = null;
 // 进行中的 agent 流（streamId → AbortController）。cancelStream IPC、
 // 窗口销毁、应用退出时统一 abort，保证不会有"关了还在跑"的幽灵循环。
@@ -90,15 +85,6 @@ function broadcastTerminalEvent(channel, payload) {
             win.webContents.send(channel, payload);
     }
 }
-terminalManager.on('data', (sessionId, chunk) => {
-    broadcastTerminalEvent('terminal:data', { sessionId, chunk });
-});
-terminalManager.on('exit', (sessionId, code, signal) => {
-    broadcastTerminalEvent('terminal:exit', { sessionId, code, signal });
-});
-terminalManager.on('spawned', session => {
-    broadcastTerminalEvent('terminal:spawned', session);
-});
 function getStartPath() {
     if (!START_PATH)
         return '/agent';
@@ -544,9 +530,11 @@ function setupIpcHandlers() {
     // validated and routed to the pending sidecar `approval.request` call;
     // unknown requestIds (late/stale answers) are dropped.
     ipcMain.handle('approval:decide', (_event, payload) => approvalBridge.decide(payload));
+    ipcMain.handle('approval:pending', () => approvalBridge.pending());
     // W8: the renderer's ask-user card answers here; routed to the pending
     // sidecar `ask_user.request` call (fail-open empty answers on mismatch).
     ipcMain.handle('ask-user:answer', (_event, payload) => askUserBridge.answer(payload));
+    ipcMain.handle('ask-user:pending', () => askUserBridge.pending());
     ipcMain.handle('local:update-safety-config', async (_event, config) => {
         localExecutor.updateSafetyConfig(config);
         return { success: true };
@@ -746,7 +734,7 @@ function setupIpcHandlers() {
             // between the turn's user message and the assistant reply persisted at
             // turn end. Only on acceptance: a soft failure degrades into the
             // follow-up queue, which persists through the normal send path.
-            localStore.addMessage(chatId, 'user', content);
+            await hostStore.addMessage(chatId, 'user', content);
         }
         return { ok, ...(ok ? {} : { reason: 'stream_not_active' }) };
     });
@@ -804,10 +792,41 @@ function setupIpcHandlers() {
 }
 app.whenReady().then(async () => {
     applyStrictCsp();
+    runtime = await createHostRuntime({
+        broadcast: (channel, payload) => broadcastTerminalEvent(channel, payload),
+        broadcastMain: (eventName, payload) => {
+            if (!mainWindow || mainWindow.isDestroyed())
+                return;
+            mainWindow.webContents.send(eventName, payload);
+        },
+        hasWindow: () => BrowserWindow.getAllWindows().some((win) => !win.isDestroyed()),
+        onLog: (line) => log.info('[sidecar]', line),
+        taskSweepReason: '应用重启，任务流已中断',
+    });
+    ({
+        store: hostStore,
+        localExecutor,
+        localScriptRegistry,
+        terminalManager,
+        packHandles,
+        localBackendRouter,
+        approvalBridge,
+        askUserBridge,
+        maybeExecInTerminal,
+    } = runtime);
+    terminalManager.on('data', (sessionId, chunk) => {
+        broadcastTerminalEvent('terminal:data', { sessionId, chunk });
+    });
+    terminalManager.on('exit', (sessionId, code, signal) => {
+        broadcastTerminalEvent('terminal:exit', { sessionId, code, signal });
+    });
+    terminalManager.on('spawned', session => {
+        broadcastTerminalEvent('terminal:spawned', session);
+    });
     setupIpcHandlers();
     // 任务清扫 / mock 广播 / sidecar 启动 / MCP 刷新 / 终端预热都在
     // runtime.start() 里（与 BS 同一份）。
-    runtime.start();
+    await runtime.start();
     createWindow();
     setSecondInstanceHandler(() => {
         if (mainWindow && !mainWindow.isDestroyed()) {

package/dist/preload.cjs

@@ -87,6 +87,25 @@ function buildPreloadApi(packContributions = {}) {
         import_electron.ipcRenderer.removeListener("chat-title-updated", handler);
       };
     },
+    /**
+     * 回合追问建议就绪。Backend 在助手回复完成后 fire-and-forget 生成 3 条
+     * 下一轮用户输入；启发式兜底会立刻推一次，LLM 成功后再替换。返回 unsubscribe。
+     */
+    onSuggestedReplies: (callback) => {
+      const handler = (_event, payload) => {
+        if (typeof payload?.chatId === "string" && typeof payload?.messageId === "string" && Array.isArray(payload.suggestions) && payload.suggestions.every((item) => typeof item === "string")) {
+          callback({
+            chatId: payload.chatId,
+            messageId: payload.messageId,
+            suggestions: payload.suggestions
+          });
+        }
+      };
+      import_electron.ipcRenderer.on("suggested-replies", handler);
+      return () => {
+        import_electron.ipcRenderer.removeListener("suggested-replies", handler);
+      };
+    },
     /**
      * 会话补建通知：Backend 在向本地不存在的 chatId 首次发送时按 URL 里的 id
      * 现场补建会话，并广播 `chat-created`（{chatId, agentId}）。返回 unsubscribe
@@ -154,9 +173,9 @@ function buildPreloadApi(packContributions = {}) {
     },
     /**
      * W4-1 审批代数：sidecar 的 ApprovalExecutor 经反向通道请示，主进程把
-     * 请求广播到 renderer（approval:request），审批弹窗应答后走
-     * approval:decide 回到主进程。订阅返回 unsubscribe；同一时刻只有一个
-     * 弹窗监听者（AgentPage 挂载的 ApprovalModalHost）。
+     * 请求广播到 renderer（approval:request），输入区审批菜单应答后走
+     * approval:decide 回到主进程。pending 供刷新后的 renderer 恢复仍在等待
+     * 的请求。
      */
     approval: {
       onRequest: (callback) => {
@@ -173,13 +192,16 @@ function buildPreloadApi(packContributions = {}) {
       },
       decide: async (decision) => {
         await import_electron.ipcRenderer.invoke("approval:decide", decision);
+      },
+      pending: async () => {
+        return await import_electron.ipcRenderer.invoke("approval:pending");
       }
     },
     /**
      * W8 结构化提问：sidecar 的 ask_user 工具经反向通道请示，主进程把
      * 请求广播到 renderer（ask-user:request），问题卡片应答后走
-     * ask-user:answer 回到主进程。订阅返回 unsubscribe；同一时刻只有一个
-     * 卡片监听者（AgentLayout 挂载的 AskUserModalHost）。
+     * ask-user:answer 回到主进程。pending 供刷新后的 renderer 恢复仍在等待
+     * 的请求。
      */
     askUser: {
       onRequest: (callback) => {
@@ -196,6 +218,9 @@ function buildPreloadApi(packContributions = {}) {
       },
       answer: async (reply) => {
         await import_electron.ipcRenderer.invoke("ask-user:answer", reply);
+      },
+      pending: async () => {
+        return await import_electron.ipcRenderer.invoke("ask-user:pending");
       }
     },
     local: {
@@ -380,11 +405,6 @@ function buildPreloadApi(packContributions = {}) {
         const fn = (_event, session) => callback(session);
         import_electron.ipcRenderer.on("terminal:spawned", fn);
         return () => import_electron.ipcRenderer.removeListener("terminal:spawned", fn);
-      },
-      onReveal: (callback) => {
-        const fn = (_event, payload) => callback(payload);
-        import_electron.ipcRenderer.on("terminal:reveal", fn);
-        return () => import_electron.ipcRenderer.removeListener("terminal:reveal", fn);
       }
     }
   };

package/dist/preload.js

@@ -103,6 +103,28 @@ export function buildPreloadApi(packContributions = {}) {
                 ipcRenderer.removeListener('chat-title-updated', handler);
             };
         },
+        /**
+         * 回合追问建议就绪。Backend 在助手回复完成后 fire-and-forget 生成 3 条
+         * 下一轮用户输入；启发式兜底会立刻推一次，LLM 成功后再替换。返回 unsubscribe。
+         */
+        onSuggestedReplies: (callback) => {
+            const handler = (_event, payload) => {
+                if (typeof payload?.chatId === 'string' &&
+                    typeof payload?.messageId === 'string' &&
+                    Array.isArray(payload.suggestions) &&
+                    payload.suggestions.every((item) => typeof item === 'string')) {
+                    callback({
+                        chatId: payload.chatId,
+                        messageId: payload.messageId,
+                        suggestions: payload.suggestions,
+                    });
+                }
+            };
+            ipcRenderer.on('suggested-replies', handler);
+            return () => {
+                ipcRenderer.removeListener('suggested-replies', handler);
+            };
+        },
         /**
          * 会话补建通知：Backend 在向本地不存在的 chatId 首次发送时按 URL 里的 id
          * 现场补建会话，并广播 `chat-created`（{chatId, agentId}）。返回 unsubscribe
@@ -171,9 +193,9 @@ export function buildPreloadApi(packContributions = {}) {
         },
         /**
          * W4-1 审批代数：sidecar 的 ApprovalExecutor 经反向通道请示，主进程把
-         * 请求广播到 renderer（approval:request），审批弹窗应答后走
-         * approval:decide 回到主进程。订阅返回 unsubscribe；同一时刻只有一个
-         * 弹窗监听者（AgentPage 挂载的 ApprovalModalHost）。
+         * 请求广播到 renderer（approval:request），输入区审批菜单应答后走
+         * approval:decide 回到主进程。pending 供刷新后的 renderer 恢复仍在等待
+         * 的请求。
          */
         approval: {
             onRequest: (callback) => {
@@ -191,12 +213,15 @@ export function buildPreloadApi(packContributions = {}) {
             decide: async (decision) => {
                 await ipcRenderer.invoke('approval:decide', decision);
             },
+            pending: async () => {
+                return await ipcRenderer.invoke('approval:pending');
+            },
         },
         /**
          * W8 结构化提问：sidecar 的 ask_user 工具经反向通道请示，主进程把
          * 请求广播到 renderer（ask-user:request），问题卡片应答后走
-         * ask-user:answer 回到主进程。订阅返回 unsubscribe；同一时刻只有一个
-         * 卡片监听者（AgentLayout 挂载的 AskUserModalHost）。
+         * ask-user:answer 回到主进程。pending 供刷新后的 renderer 恢复仍在等待
+         * 的请求。
          */
         askUser: {
             onRequest: (callback) => {
@@ -214,6 +239,9 @@ export function buildPreloadApi(packContributions = {}) {
             answer: async (reply) => {
                 await ipcRenderer.invoke('ask-user:answer', reply);
             },
+            pending: async () => {
+                return await ipcRenderer.invoke('ask-user:pending');
+            },
         },
         local: {
             selectDirectory: async (options) => {
@@ -398,11 +426,6 @@ export function buildPreloadApi(packContributions = {}) {
                 ipcRenderer.on('terminal:spawned', fn);
                 return () => ipcRenderer.removeListener('terminal:spawned', fn);
             },
-            onReveal: (callback) => {
-                const fn = (_event, payload) => callback(payload);
-                ipcRenderer.on('terminal:reveal', fn);
-                return () => ipcRenderer.removeListener('terminal:reveal', fn);
-            },
         },
     };
     contextBridge.exposeInMainWorld('electron', { ...electronAPI, ...packContributions });

package/dist/server/http-server.d.ts

@@ -23,15 +23,21 @@
  * 不要绑到非回环地址，那会把 shell / 文件读写 / 场景包工具控制暴露给整个
  * 网络（token 只能挡没有 token 的人）。
  */
-import { type Server } from 'node:http';
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import type { LocalBackendRouter } from '../local-backend/router.js';
+import type { ScopedStore } from '../storage/scoped-store.js';
 import type { LocalExecutor, LocalExecRequest, LocalExecResult } from '../local-executor.js';
 import type { LocalScriptRegistry } from '../local-script-registry.js';
 import type { TerminalManager } from '../terminal-manager.js';
 import type { createApprovalBridge } from '../sidecar/reverse-approval.js';
 import type { createAskUserBridge } from '../sidecar/reverse-ask-user.js';
 import type { SseBus } from './sse-bus.js';
+/** Runs before built-in routing; `handled` short-circuits the request. */
+export interface BsMiddleware {
+    (req: IncomingMessage, res: ServerResponse): Promise<'handled' | 'pass'>;
+}
 export interface BsServerDeps {
+    store: ScopedStore;
     localBackendRouter: LocalBackendRouter;
     localExecutor: LocalExecutor;
     localScriptRegistry: LocalScriptRegistry;
@@ -44,5 +50,11 @@ export interface BsServerDeps {
     webDistDir: string;
     /** Bearer token；缺省每次启动随机生成。测试注入固定值。 */
     authToken?: string;
+    /**
+     * Trusted product middleware, invoked in order after Host validation and
+     * before authentication. This position lets a product own public sign-in
+     * and identity-provider callback routes without weakening built-in routes.
+     */
+    middleware?: readonly BsMiddleware[];
 }
 export declare function createBsServer(deps: BsServerDeps): Server;

package/dist/server/http-server.js

@@ -31,10 +31,10 @@ import path from 'node:path';
 import log from 'electron-log';
 import { getActiveCoreLoopStreamId } from '../local-backend/coreloop-stream.js';
 import { getSidecarSupervisor } from '../llm/index.js';
-import { localStore } from '../storage/index.js';
 import { matchPackHttpRoute } from '../host/http-routes.js';
 import { getBrand } from '../brand.js';
 import { saveAttachmentFiles } from '../attachments.js';
+import { getAuthProvider } from '../auth/index.js';
 /** 与 router.handleStream 内部的路由正则保持一致——只有这些路径是流式。 */
 const STREAM_PATH_PATTERNS = [
     /^\/api\/v2\/chats\/[^/]+\/(send|run|agent)$/,
@@ -91,6 +91,7 @@ function asRecord(body) {
 }
 export function createBsServer(deps) {
     const { localBackendRouter, localExecutor, localScriptRegistry, terminalManager, approvalBridge, askUserBridge, maybeExecInTerminal, bus, webDistDir, } = deps;
+    const middleware = deps.middleware ?? [];
     const authToken = deps.authToken ?? randomBytes(24).toString('base64url');
     /** `/api/v2/*` 与 `/host/*` 的 Bearer 门；EventSource 不能设头，收 query token。 */
     function isAuthorized(req, url) {
@@ -98,13 +99,18 @@ export function createBsServer(deps) {
             return true;
         return url.searchParams.get('token') === authToken;
     }
-    async function handleApi(req, res, pathname) {
+    async function handleApi(req, res, pathname, principal) {
         const isStream = req.method === 'POST' && STREAM_PATH_PATTERNS.some((p) => p.test(pathname));
         const body = req.method === 'POST' || req.method === 'PATCH' || req.method === 'PUT'
             ? await readJsonBody(req)
             : undefined;
         const search = new URL(req.url ?? '/', 'http://bs.local').search;
-        const request = { method: req.method ?? 'GET', path: `${pathname}${search}`, body };
+        const request = {
+            method: req.method ?? 'GET',
+            path: `${pathname}${search}`,
+            body,
+            ...(principal ? { principal } : {}),
+        };
         if (isStream) {
             const controller = new AbortController();
             // 浏览器关页/取消 fetch → 中止 agent 循环（对齐 Electron 的 cancelStream）。
@@ -221,7 +227,7 @@ export function createBsServer(deps) {
             const ok = await supervisor.steerChat(streamId, content);
             // 与 main.ts 同理：接受即落库，重开对话能看到这条注入的用户消息。
             if (ok)
-                localStore.addMessage(chatId, 'user', content);
+                await deps.store.addMessage(chatId, 'user', content);
             sendJson(res, 200, { ok, ...(ok ? {} : { reason: 'stream_not_active' }) });
             return;
         }
@@ -230,11 +236,19 @@ export function createBsServer(deps) {
             sendJson(res, 200, await approvalBridge.decide(body));
             return;
         }
+        if (method === 'GET' && pathname === '/host/approval/pending') {
+            sendJson(res, 200, approvalBridge.pending());
+            return;
+        }
         // ─── ask_user（对齐 ask-user:answer IPC） ───
         if (method === 'POST' && pathname === '/host/ask-user/answer') {
             sendJson(res, 200, askUserBridge.answer(body));
             return;
         }
+        if (method === 'GET' && pathname === '/host/ask-user/pending') {
+            sendJson(res, 200, askUserBridge.pending());
+            return;
+        }
         // ─── local（对齐 local:* IPC） ───
         if (method === 'POST' && pathname === '/host/local/exec-shell') {
             const request = body;
@@ -357,19 +371,42 @@ export function createBsServer(deps) {
             }
             const url = new URL(req.url ?? '/', 'http://bs.local');
             const pathname = url.pathname;
+            for (const handle of middleware) {
+                const result = await handle(req, res);
+                if (result !== 'handled' && result !== 'pass') {
+                    throw new Error(`BS middleware returned invalid result: ${String(result)}`);
+                }
+                if (result === 'handled' || res.writableEnded)
+                    return;
+                if (res.headersSent) {
+                    throw new Error('BS middleware returned pass after starting a response');
+                }
+            }
             // 门 2：API 与宿主能力要 Bearer token；静态资源不验（浏览器靠它
             // 拿 token），静态面不暴露任何能力。
             const needsAuth = pathname.startsWith('/api/v2/') || pathname.startsWith('/host/');
-            if (needsAuth && !isAuthorized(req, url)) {
-                sendJson(res, 401, { detail: 'unauthorized' });
-                return;
+            let principal;
+            if (needsAuth) {
+                const authProvider = getAuthProvider();
+                if (authProvider) {
+                    const decision = await authProvider.authenticate(req.headers);
+                    if (!decision.ok) {
+                        sendJson(res, decision.status, decision.body ?? { detail: decision.status === 403 ? 'forbidden' : 'unauthorized' });
+                        return;
+                    }
+                    principal = decision.principal;
+                }
+                else if (!isAuthorized(req, url)) {
+                    sendJson(res, 401, { detail: 'unauthorized' });
+                    return;
+                }
             }
             if (pathname === '/api/v2/events' && req.method === 'GET') {
                 bus.attach(res);
                 return;
             }
             if (pathname.startsWith('/api/v2/')) {
-                await handleApi(req, res, pathname);
+                await handleApi(req, res, pathname, principal);
                 return;
             }
             if (pathname.startsWith('/host/')) {

package/dist/server/index.js

@@ -1,100 +1,14 @@
-/**
- * BS 模式入口：`node dist/server/index.js`。
- *
- * 装配与 Electron 主进程（main.ts）相同的一组服务——同一份装配住在
- * src/host/runtime.ts（HostRuntime），这里只保留 BS 特有的部分：SSE
- * 总线广播、HTTP 出口（http-server.ts）、SIGINT/SIGTERM 生命周期。
- * 数据目录、sidecar、工具链、审批流全部共用；两种模式因此操作同一份
- * SQLite / JSON 配置（不要同时启动两个宿主——write-lease 会拒绝第二个写者）。
- *
- * 默认绑定 127.0.0.1:4787（DEEPPATH_BS_HOST / DEEPPATH_BS_PORT 可改）。
- * 无认证：与桌面版同一信任模型，不要暴露到非回环地址。
- */
-// 产品组装根必须是第一个 import：包迁移注册要先于 storage 单例构造（0.3b）。
-// 产品组装根（products/<id>/server.ts 或 devtools/dev-server.ts）必须先于
-// 本模块完成 import：包迁移注册要先于 storage 单例构造（0.3b / 2.3）。
-import { existsSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import dotenv from 'dotenv';
-import log from 'electron-log';
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// 与 main.ts 相同的 .env 加载顺序（.env.local 优先；已有环境变量胜出）。
-(function loadDotenvFiles() {
-    const repoRoot = path.resolve(__dirname, '..', '..');
-    for (const file of ['.env.local', '.env']) {
-        const fullPath = path.join(repoRoot, file);
-        if (existsSync(fullPath))
-            dotenv.config({ path: fullPath, override: false });
-    }
-})();
-import { getBrand } from '../brand.js';
-import { getUserDataDir } from '../runtime.js';
-import { createHostRuntime } from '../host/runtime.js';
-import { registerPackHttpRoutes } from '../host/http-routes.js';
-import { SseBus } from './sse-bus.js';
-import { createBsServer } from './http-server.js';
-// BS 模式没有 Electron 的 userData 概念，electron-log 默认会写
-// ~/.config/<name>/logs；在 HOME 只读（容器/只读环境）或用户显式指定
-// DEEPPATH_USER_DATA_DIR 时，日志应跟随应用数据目录走。
-log.transports.file.resolvePathFn = () => path.join(getUserDataDir(), 'logs', 'main.log');
+/** Executable BS entry; reusable assembly lives in `start.ts`. */
+import { startBsHost } from './start.js';
 async function main() {
-    const brand = getBrand();
-    const bus = new SseBus();
-    const broadcast = (channel, payload) => bus.broadcast(channel, payload);
-    // 与 CS 同一份服务装配；BS 的差异只有广播（SSE 总线）与"有浏览器连着
-    // 事件总线 = 有人能应答审批/提问"的 hasWindow 判定。
-    const runtime = createHostRuntime({
-        broadcast,
-        hasWindow: () => bus.size > 0,
-        onLog: (line) => log.info('[sidecar]', line),
-        taskSweepReason: '服务重启，任务流已中断',
-    });
-    const { localExecutor, localScriptRegistry, terminalManager, packHandles, localBackendRouter, approvalBridge, askUserBridge, maybeExecInTerminal, } = runtime;
-    // 2.3 起 web 产物按产品构建：产品入口注入 DEEPPATH_WEB_DIST
-    //（products/<id>/web/dist）；缺省回退到 shell 包自带的 web/dist
-    //（packages/agent-shell/web/dist），仅用于给出可读的报错。
-    const webDistDir = process.env.DEEPPATH_WEB_DIST ??
-        path.join(__dirname, '..', '..', 'web', 'dist');
-    if (!existsSync(path.join(webDistDir, 'index.html'))) {
-        console.error(`[bs] web build not found at ${webDistDir} — run \`pnpm build\` first.`);
-        process.exit(1);
-    }
-    // 场景包 HTTP 路由（/host/<packId>/*）由装配产物给出，宿主循环注册
-    //（2.3；路由路径命名空间由 registerPackHttpRoutes 校验）。
-    for (const [packId, handle] of packHandles) {
-        const routes = handle.httpRoutes?.();
-        if (routes)
-            registerPackHttpRoutes(packId, routes);
-    }
-    const server = createBsServer({
-        localBackendRouter,
-        localExecutor,
-        localScriptRegistry,
-        terminalManager,
-        approvalBridge,
-        askUserBridge,
-        maybeExecInTerminal,
-        bus,
-        webDistDir,
-    });
-    const host = process.env.DEEPPATH_BS_HOST || '127.0.0.1';
-    const port = Number(process.env.DEEPPATH_BS_PORT || 4787);
-    await new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(port, host, () => resolve());
-    });
-    console.log(`[bs] ${brand.displayName} server listening at http://${host}:${port}  (flavor=${brand.flavor})`);
-    // 任务清扫 / mock 广播 / sidecar 启动 / MCP 刷新 / 终端预热。不阻塞
-    // HTTP 就绪；竞速的回合由 router 回退处理（同 main.ts）。
-    runtime.start();
+    const handle = await startBsHost();
     let shuttingDown = false;
     const shutdown = () => {
         if (shuttingDown)
             return;
         shuttingDown = true;
         console.log('[bs] shutting down…');
-        void runtime.shutdown().finally(() => process.exit(0));
+        void handle.shutdown().finally(() => process.exit(0));
         // 兜底：sidecar 卡住也不拖住退出。
         setTimeout(() => process.exit(0), 5_000).unref();
     };

package/dist/server/sse-bus.d.ts

@@ -1,7 +1,7 @@
 /**
  * BS 模式的 SSE 事件总线：替代 Electron 的 `webContents.send(channel, payload)`
  * 广播。所有宿主事件（terminal:data、approval:request、chat-title-updated、
- * 场景包事件……）经这一条 `GET /api/v2/events` 长连接推给浏览器，
+ * suggested-replies、场景包事件……）经这一条 `GET /api/v2/events` 长连接推给浏览器，
  * channel 名与 IPC 通道保持一致，前端 http-bridge 按名分发。
  */
 import type { ServerResponse } from 'node:http';

package/dist/server/start.d.ts

@@ -0,0 +1,26 @@
+import type { Server } from 'node:http';
+import type { TenantScope } from '../storage/driver.js';
+import { type BsMiddleware } from './http-server.js';
+export interface BsHostOptions {
+    host?: string;
+    port?: number;
+    authToken?: string;
+    middleware?: readonly BsMiddleware[];
+    /** Fixed storage owner for a per-user host process. */
+    scope?: TenantScope;
+}
+export interface BsHostHandle {
+    readonly server: Server;
+    readonly host: string;
+    readonly port: number;
+    /** Stops accepting requests and shuts down all host runtime services. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Assembles and starts the BS HTTP host.
+ *
+ * Product composition roots may register providers, package contributions,
+ * and middleware before calling this function.
+ */
+export declare function startBsHost(options?: BsHostOptions): Promise<BsHostHandle>;
+export type { BsMiddleware };