@steerable/agent-shell 0.6.21 → 0.6.24

package/dist/local-backend/skills/00-identity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: identity
-description: Defines the product agent's core role, working environment, and language convention. Always loaded as the foundational skill. Brand placeholders ({agentName}) are rendered from the product-injected brand.
+description: Defines the core role, working environment, and language convention. Always loaded as the foundational skill. {agentName} is the current chat agent display name (product brand if none).
 priority: 1000
 tags: [identity, base]
 ---

package/dist/local-backend/task-service.d.ts

@@ -29,7 +29,7 @@ import type { ToolRouter } from '../tool-router.js';
 import { streamCoreLoopTurn } from './coreloop-stream.js';
 import type { WorktreeService } from './worktree-service.js';
 import { type PersistedTurnBlock } from './turn-timeline.js';
-/** 任务表的最小读写面（生产 = localStore；测试注入内存实现）。 */
+/** 任务表的最小异步读写面（生产注入 scoped store；测试注入内存实现）。 */
 export interface TaskStore {
     createTask(input: {
         chatId: string;
@@ -39,22 +39,22 @@ export interface TaskStore {
         recordId?: string | null;
         dependsOn?: string[] | null;
         initialStatus?: 'blocked' | 'running';
-    }): TaskRecord;
-    getTask(taskId: string): TaskRecord | null;
-    listTasks(chatId?: string, limit?: number): TaskRecord[];
-    updateTask(taskId: string, updates: Partial<Pick<TaskRecord, 'status' | 'answer' | 'error' | 'worktreeState' | 'traceId' | 'recordId'>>): TaskRecord | null;
+    }): Promise<TaskRecord>;
+    getTask(taskId: string): Promise<TaskRecord | null>;
+    listTasks(chatId?: string, limit?: number): Promise<TaskRecord[]>;
+    updateTask(taskId: string, updates: Partial<Pick<TaskRecord, 'status' | 'answer' | 'error' | 'worktreeState' | 'traceId' | 'recordId'>>): Promise<TaskRecord | null>;
     /** 回写推理时间线；缺省实现可为空（测试假 store 内存覆盖）。 */
-    saveTaskProcess?(taskId: string, processJson: string): void;
+    saveTaskProcess?(taskId: string, processJson: string): Promise<void>;
 }
 export interface TaskServiceDeps {
-    store: TaskStore;
+    store: TaskStore | (() => TaskStore);
     toolRouter: ToolRouter;
     worktreeService: WorktreeService;
     /** chatId → 绑定项目（无项目对话返回 null）。与 router.resolveChatProject 同源。 */
-    resolveChatProject: (chatId: string) => {
+    resolveChatProject: (chatId: string) => Promise<{
         name: string;
         folderPath: string;
-    } | null;
+    } | null>;
     /** 任务终态 / 推理过程广播（renderer 任务面板与右侧过程栏）。 */
     broadcast?: (eventName: 'task-updated' | 'task-process', payload: Record<string, unknown>) => void;
     /** 测试缝：替换真实流驱动（默认 streamCoreLoopTurn）。 */
@@ -68,6 +68,7 @@ export declare class TaskService {
     private readonly deps;
     private readonly running;
     constructor(deps: TaskServiceDeps);
+    private get store();
     /**
      * task_run 工具的实现：落任务表 + 点火独立流，立即返回。
      * 任何同步可知的失败（无 sidecar、worktree 建不起来）都抛给工具层，
@@ -113,21 +114,21 @@ export declare class TaskService {
     private cancelProcessFlush;
     private executeTask;
     /** task_status 工具：单任务或本 chat 全部任务的快照。 */
-    status(chatId: string, taskId?: string): Record<string, unknown>;
+    status(chatId: string, taskId?: string): Promise<Record<string, unknown>>;
     /** task_result 工具：取终态任务的完整结果。 */
-    result(chatId: string, taskId: string): Record<string, unknown>;
+    result(chatId: string, taskId: string): Promise<Record<string, unknown>>;
     /** 喂给模型的任务视图（完整字段，answer 截断防爆上下文）。 */
     private toModelView;
     /**
      * 右侧过程栏：当前推理时间线。running 且进程内有流 = live；
      * 表上 running 但本进程没流 = 上次崩溃残留（stale）。
      */
-    getProcess(taskId: string): {
+    getProcess(taskId: string): Promise<{
         task: TaskRecord;
         timeline: PersistedTurnBlock[];
         live: boolean;
         stale: boolean;
-    } | null;
+    } | null>;
     /** 合并任务 worktree 到主仓（UI「合并到主仓」按钮的路由实现）。 */
     mergeTaskWorktree(taskId: string): Promise<TaskRecord>;
     /** 丢弃任务 worktree（UI「丢弃」按钮的路由实现）。 */

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

@@ -55,6 +55,9 @@ export class TaskService {
     constructor(deps) {
         this.deps = deps;
     }
+    get store() {
+        return typeof this.deps.store === 'function' ? this.deps.store() : this.deps.store;
+    }
     /**
      * task_run 工具的实现：落任务表 + 点火独立流，立即返回。
      * 任何同步可知的失败（无 sidecar、worktree 建不起来）都抛给工具层，
@@ -76,13 +79,13 @@ export class TaskService {
         const dependsOn = input.dependsOn?.length ? input.dependsOn : null;
         let blockedBy = [];
         if (dependsOn) {
-            const deps = dependsOn.map((id) => {
-                const dep = this.deps.store.getTask(id);
+            const deps = await Promise.all(dependsOn.map(async (id) => {
+                const dep = await this.store.getTask(id);
                 if (!dep || dep.chatId !== input.chatId) {
                     throw new Error(`task_run: 依赖任务不存在或不属于本会话：${id}`);
                 }
                 return dep;
-            });
+            }));
             const failed = deps.filter((d) => d.status === 'failed');
             if (failed.length) {
                 throw new Error(`task_run: 依赖任务已失败（${failed.map((d) => d.id.slice(0, 8)).join('、')}）——`
@@ -108,7 +111,7 @@ export class TaskService {
             }
         }
         const blocked = blockedBy.length > 0;
-        const record = this.deps.store.createTask({
+        const record = await this.store.createTask({
             chatId: input.chatId,
             task,
             worktreePath,
@@ -117,7 +120,7 @@ export class TaskService {
             initialStatus: blocked ? 'blocked' : 'running',
         });
         const recordId = `task:${record.id}`;
-        this.deps.store.updateTask(record.id, { recordId });
+        await this.store.updateTask(record.id, { recordId });
         if (!blocked) {
             this.ignite(record.id, input.chatId, task, recordId, worktreePath);
         }
@@ -137,7 +140,7 @@ export class TaskService {
         const text = message.trim();
         if (!text)
             return { success: false, error: 'task_send: message 不能为空' };
-        const task = this.deps.store.getTask(taskId);
+        const task = await this.store.getTask(taskId);
         if (!task || task.chatId !== chatId) {
             return { success: false, error: `任务不存在：${taskId}` };
         }
@@ -178,15 +181,15 @@ export class TaskService {
      * completed 的点火；任一依赖 failed 的标 failed（fail fast，错误
      * 指明是哪个依赖挂了）。
      */
-    maybeUnblock(chatId) {
-        const blocked = this.deps.store
-            .listTasks(chatId, 100)
+    async maybeUnblock(chatId) {
+        const blocked = (await this.store
+            .listTasks(chatId, 100))
             .filter((t) => t.status === 'blocked' && t.dependsOn?.length);
         for (const task of blocked) {
-            const deps = task.dependsOn.map((id) => this.deps.store.getTask(id));
+            const deps = await Promise.all(task.dependsOn.map((id) => this.store.getTask(id)));
             const failedDep = deps.find((d) => d?.status === 'failed');
             if (failedDep) {
-                this.deps.store.updateTask(task.id, {
+                await this.store.updateTask(task.id, {
                     status: 'failed',
                     error: `依赖任务失败：${failedDep.id.slice(0, 8)}（${failedDep.error ?? '无错误信息'}）`,
                 });
@@ -195,7 +198,7 @@ export class TaskService {
             }
             const allCompleted = deps.every((d) => d?.status === 'completed');
             if (allCompleted) {
-                this.deps.store.updateTask(task.id, { status: 'running' });
+                await this.store.updateTask(task.id, { status: 'running' });
                 this.ignite(task.id, task.chatId, task.task, task.recordId ?? `task:${task.id}`, task.worktreePath);
                 this.deps.broadcast?.('task-updated', { chatId, taskId: task.id });
             }
@@ -217,7 +220,7 @@ export class TaskService {
             .finally(() => {
             this.running.delete(taskId);
             // 一个任务到终态，可能让同 chat 的 blocked 任务依赖就绪——调度点火。
-            this.maybeUnblock(chatId);
+            void this.maybeUnblock(chatId);
         });
         this.running.set(taskId, entry);
     }
@@ -235,7 +238,7 @@ export class TaskService {
                 timeline: entry.timeline,
                 live: true,
             });
-            this.deps.store.saveTaskProcess?.(taskId, JSON.stringify(entry.timeline));
+            void this.store.saveTaskProcess?.(taskId, JSON.stringify(entry.timeline));
         };
         if (when === 'immediate') {
             this.cancelProcessFlush(taskId);
@@ -259,7 +262,7 @@ export class TaskService {
         const getSupervisor = this.deps.getSupervisor ?? getSidecarSupervisor;
         const supervisor = getSupervisor();
         if (!supervisor) {
-            this.deps.store.updateTask(taskId, {
+            await this.store.updateTask(taskId, {
                 status: 'failed',
                 error: 'sidecar 未运行',
             });
@@ -267,7 +270,7 @@ export class TaskService {
             return;
         }
         const settings = llmService.getSettings();
-        const project = this.deps.resolveChatProject(chatId);
+        const project = await this.deps.resolveChatProject(chatId);
         // 4.6b 整合：worktree 任务的围栏根 = worktree 路径（更紧——任务摸不到
         // 主检出）；否则沿用项目根。writableRoots 同理收窄。
         const fenceRoot = worktreePath ?? project?.folderPath ?? null;
@@ -397,14 +400,14 @@ export class TaskService {
                 traceId = failureTraceId;
             }
         }
-        this.deps.store.updateTask(taskId, {
+        await this.store.updateTask(taskId, {
             status,
             answer: answer.trim() || null,
             error,
             ...(traceId ? { traceId } : {}),
         });
         this.cancelProcessFlush(taskId);
-        this.deps.store.saveTaskProcess?.(taskId, JSON.stringify(entry.timeline));
+        await this.store.saveTaskProcess?.(taskId, JSON.stringify(entry.timeline));
         this.deps.broadcast?.('task-updated', { chatId, taskId });
         this.deps.broadcast?.('task-process', {
             chatId,
@@ -414,15 +417,15 @@ export class TaskService {
         });
     }
     /** task_status 工具：单任务或本 chat 全部任务的快照。 */
-    status(chatId, taskId) {
+    async status(chatId, taskId) {
         if (taskId) {
-            const task = this.deps.store.getTask(taskId);
+            const task = await this.store.getTask(taskId);
             if (!task || task.chatId !== chatId) {
                 return { success: false, error: `任务不存在：${taskId}` };
             }
             return { success: true, task: this.toModelView(task) };
         }
-        const tasks = this.deps.store.listTasks(chatId, 50);
+        const tasks = await this.store.listTasks(chatId, 50);
         return {
             success: true,
             total: tasks.length,
@@ -430,8 +433,8 @@ export class TaskService {
         };
     }
     /** task_result 工具：取终态任务的完整结果。 */
-    result(chatId, taskId) {
-        const task = this.deps.store.getTask(taskId);
+    async result(chatId, taskId) {
+        const task = await this.store.getTask(taskId);
         if (!task || task.chatId !== chatId) {
             return { success: false, error: `任务不存在：${taskId}` };
         }
@@ -473,8 +476,8 @@ export class TaskService {
      * 右侧过程栏：当前推理时间线。running 且进程内有流 = live；
      * 表上 running 但本进程没流 = 上次崩溃残留（stale）。
      */
-    getProcess(taskId) {
-        const task = this.deps.store.getTask(taskId);
+    async getProcess(taskId) {
+        const task = await this.store.getTask(taskId);
         if (!task)
             return null;
         const entry = this.running.get(taskId);
@@ -509,7 +512,7 @@ export class TaskService {
     }
     /** 合并任务 worktree 到主仓（UI「合并到主仓」按钮的路由实现）。 */
     async mergeTaskWorktree(taskId) {
-        const task = this.deps.store.getTask(taskId);
+        const task = await this.store.getTask(taskId);
         if (!task)
             throw new Error(`任务不存在：${taskId}`);
         if (!task.worktreePath || !task.worktreeBranch) {
@@ -523,13 +526,13 @@ export class TaskService {
         }
         const name = path.basename(task.worktreePath);
         await this.deps.worktreeService.mergeWorktree(task.chatId, name, `task(${taskId.slice(0, 8)}): ${task.task.slice(0, 60)}`);
-        const updated = this.deps.store.updateTask(taskId, { worktreeState: 'merged' });
+        const updated = await this.store.updateTask(taskId, { worktreeState: 'merged' });
         this.deps.broadcast?.('task-updated', { chatId: task.chatId, taskId });
         return updated;
     }
     /** 丢弃任务 worktree（UI「丢弃」按钮的路由实现）。 */
     async discardTaskWorktree(taskId) {
-        const task = this.deps.store.getTask(taskId);
+        const task = await this.store.getTask(taskId);
         if (!task)
             throw new Error(`任务不存在：${taskId}`);
         if (!task.worktreePath) {
@@ -545,7 +548,7 @@ export class TaskService {
         await this.deps.worktreeService.removeWorktree(task.chatId, name, {
             deleteBranch: true,
         });
-        const updated = this.deps.store.updateTask(taskId, { worktreeState: 'discarded' });
+        const updated = await this.store.updateTask(taskId, { worktreeState: 'discarded' });
         this.deps.broadcast?.('task-updated', { chatId: task.chatId, taskId });
         return updated;
     }

package/dist/local-backend/worktree-service.d.ts

@@ -35,7 +35,7 @@ export declare function slugifyWorktreeName(raw: string): string;
 export declare class WorktreeService {
     private readonly deps;
     constructor(deps: {
-        resolveProject: (chatId: string) => WorktreeProject | null;
+        resolveProject: (chatId: string) => Promise<WorktreeProject | null>;
         runGit?: GitRunner;
     });
     private git;

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 / suggested-replies）只推主窗口。
-    // 没拿到 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';
@@ -748,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' }) };
     });
@@ -806,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/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;
         }
@@ -365,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/')) {