@steerable/agent-shell 0.6.21 → 0.6.22

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/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 };

package/dist/server/start.js

@@ -0,0 +1,111 @@
+/**
+ * Composable BS host assembly for executable and embedded deployments.
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import dotenv from 'dotenv';
+import log from 'electron-log';
+import { getBrand } from '../brand.js';
+import { registerPackHttpRoutes } from '../host/http-routes.js';
+import { createHostRuntime } from '../host/runtime.js';
+import { getUserDataDir } from '../runtime.js';
+import { createBsServer, } from './http-server.js';
+import { SseBus } from './sse-bus.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Match the Electron entry's dotenv precedence: local file first, existing
+// process variables always win.
+for (const file of ['.env.local', '.env']) {
+    const fullPath = path.join(path.resolve(__dirname, '..', '..'), file);
+    if (existsSync(fullPath))
+        dotenv.config({ path: fullPath, override: false });
+}
+log.transports.file.resolvePathFn = () => path.join(getUserDataDir(), 'logs', 'main.log');
+/**
+ * Assembles and starts the BS HTTP host.
+ *
+ * Product composition roots may register providers, package contributions,
+ * and middleware before calling this function.
+ */
+export async function startBsHost(options = {}) {
+    const brand = getBrand();
+    const bus = new SseBus();
+    const broadcast = (channel, payload) => bus.broadcast(channel, payload);
+    const runtime = await createHostRuntime({
+        scope: options.scope,
+        broadcast,
+        hasWindow: () => bus.size > 0,
+        onLog: (line) => log.info('[sidecar]', line),
+        taskSweepReason: '服务重启，任务流已中断',
+    });
+    const { localExecutor, localScriptRegistry, terminalManager, packHandles, localBackendRouter, approvalBridge, askUserBridge, maybeExecInTerminal, } = runtime;
+    const webDistDir = process.env.DEEPPATH_WEB_DIST ??
+        path.join(__dirname, '..', '..', 'web', 'dist');
+    if (!existsSync(path.join(webDistDir, 'index.html'))) {
+        await runtime.shutdown();
+        throw new Error(`[bs] web build not found at ${webDistDir} — run \`pnpm build\` first.`);
+    }
+    for (const [packId, handle] of packHandles) {
+        const routes = handle.httpRoutes?.();
+        if (routes)
+            registerPackHttpRoutes(packId, routes);
+    }
+    const server = createBsServer({
+        store: runtime.store,
+        localBackendRouter,
+        localExecutor,
+        localScriptRegistry,
+        terminalManager,
+        approvalBridge,
+        askUserBridge,
+        maybeExecInTerminal,
+        bus,
+        webDistDir,
+        authToken: options.authToken,
+        middleware: options.middleware,
+    });
+    const host = options.host ?? (process.env.DEEPPATH_BS_HOST || '127.0.0.1');
+    const requestedPort = options.port ?? Number(process.env.DEEPPATH_BS_PORT || 4787);
+    try {
+        await new Promise((resolve, reject) => {
+            const onError = (error) => reject(error);
+            server.once('error', onError);
+            server.listen(requestedPort, host, () => {
+                server.off('error', onError);
+                resolve();
+            });
+        });
+    }
+    catch (error) {
+        await runtime.shutdown();
+        throw error;
+    }
+    const address = server.address();
+    const port = address.port;
+    console.log(`[bs] ${brand.displayName} server listening at http://${host}:${port}  (flavor=${brand.flavor})`);
+    await runtime.start();
+    let shutdownPromise = null;
+    return {
+        server,
+        host,
+        port,
+        shutdown() {
+            shutdownPromise ??= (async () => {
+                try {
+                    await new Promise((resolve, reject) => {
+                        server.close((error) => {
+                            if (error)
+                                reject(error);
+                            else
+                                resolve();
+                        });
+                    });
+                }
+                finally {
+                    await runtime.shutdown();
+                }
+            })();
+            return shutdownPromise;
+        },
+    };
+}

package/dist/sidecar/boot.d.ts

@@ -1,10 +1,12 @@
+import type { ScopedStore } from '../storage/scoped-store.js';
 import { type ToolRouter } from '../tool-router.js';
 import type { createApprovalBridge } from './reverse-approval.js';
 import type { SidecarReverseHandler } from './types.js';
 export interface HostSidecarDeps {
+    store: ScopedStore;
     toolRouter: ToolRouter;
     /** W4-2 项目模式围栏：chatId → 项目根（无项目对话返回 null）。 */
-    resolveProjectRoot: (chatId: string) => string | null;
+    resolveProjectRoot: (chatId: string) => Promise<string | null>;
     /**
      * 项目模式之外额外放行的只读根（会话附件目录等）。文件写入仍只受
      * projectRoot 围栏约束；这些根只放宽 local_read_file 的读取范围。

package/dist/sidecar/boot.js

@@ -10,7 +10,6 @@ import path from 'node:path';
 import log from 'electron-log';
 import { SidecarSupervisor, resolveSidecarPython } from './supervisor.js';
 import { setSidecarSupervisor, setSidecarSupervisorPending, llmService } from '../llm/index.js';
-import { localStore } from '../storage/index.js';
 import { resolveSidecarStoragePath } from './storage-path.js';
 import { deriveEgressAllowListFromBaseUrl, probeExecSandboxCapability, } from './exec-sandbox.js';
 import { createToolInvokeHandler } from './reverse-tools.js';
@@ -58,7 +57,7 @@ async function deriveSidecarEgressAllowList() {
  *   ambient 端点并进允许列表，见 W4-8）。
  * - 启动失败 / 派生不出任何代理条目。
  */
-async function startEgressProxyIfEnabled() {
+async function startEgressProxyIfEnabled(store) {
     try {
         const ambient = process.env.STEERABLE_EGRESS_PROXY === '0' ? [] : await collectAmbientProxyEndpoints();
         const decision = decideEgressProxy({ env: process.env, ambientProxies: ambient });
@@ -72,7 +71,7 @@ async function startEgressProxyIfEnabled() {
             return null;
         }
         const settings = llmService.getSettings();
-        const searchSettings = localStore.getWebSearchSettings();
+        const searchSettings = await store.getWebSearchSettings();
         const searchEnv = sidecarWebSearchEnv({
             processEnv: process.env,
             storedApiKey: searchSettings?.apiKey,
@@ -214,7 +213,7 @@ export async function startHostSidecar(deps) {
                 consentGranted: true,
                 timeoutMs: WEB_TOOL_RPC_TIMEOUT_MS,
             }), webNames);
-            const searchSettings = localStore.getWebSearchSettings();
+            const searchSettings = await deps.store.getWebSearchSettings();
             const searchEnv = sidecarWebSearchEnv({
                 processEnv: process.env,
                 storedApiKey: searchSettings?.apiKey,
@@ -254,7 +253,7 @@ export async function startHostSidecar(deps) {
     };
     const boot = (async () => {
         try {
-            const egressProxy = await startEgressProxyIfEnabled();
+            const egressProxy = await startEgressProxyIfEnabled(deps.store);
             // W2.6.1: durable sessions/traces/history in a zero-dependency
             // sqlite database under ~/.steerable — the one root the Seatbelt
             // profile already allows writes to; userData would be denied.
@@ -286,8 +285,8 @@ export async function startHostSidecar(deps) {
                     ...egressProxy?.env,
                     ...sidecarWebSearchEnv({
                         processEnv: process.env,
-                        storedApiKey: localStore.getWebSearchSettings()?.apiKey,
-                        storedProvider: localStore.getWebSearchSettings()?.provider,
+                        storedApiKey: (await deps.store.getWebSearchSettings())?.apiKey,
+                        storedProvider: (await deps.store.getWebSearchSettings())?.provider,
                         llmBaseUrl: llmService.getSettings().baseUrl,
                     }),
                     // P1: offer the sidecar's run_code (programmatic tool calls) to the

package/dist/sidecar/reverse-spawn.js

@@ -29,17 +29,25 @@ export function resolveWinSpawnHelperPath() {
     // 显式覆盖（测试/调试逃生门）：设置后只认这一条路径。指向不存在的
     // 路径即可强制走"helper 缺失"的失败分支，与 dev checkout 是否已构建
     // Rust 二进制无关，保证失败分支的测试确定性。
-    const override = process.env.DEEPPATH_WIN_SPAWN_HELPER;
+    const override = process.env.DEEPPATH_WIN_SPAWN_HELPER ?? process.env.STEERABLE_WIN_SPAWN_HELPER;
     if (override !== undefined) {
         return override && existsSync(override) ? override : null;
     }
-    const resourcesPath = process.resourcesPath;
+    const electron = process;
+    const resourcesPath = electron.resourcesPath;
     const candidates = [];
     if (resourcesPath) {
         candidates.push(join(resourcesPath, 'win-spawn-helper', binary));
     }
-    // Dev checkout: native/ builds into resources/windows-spawn-helper/.
-    candidates.push(join(__dirname, '..', '..', 'resources', 'windows-spawn-helper', binary));
+    // Packaged extraResources live under resourcesPath. cwd is the user's
+    // launch directory and must not supply the confinement binary.
+    // `electron .` sets defaultApp and does not copy extraResources there;
+    // npm-published shell also cannot see the host checkout via __dirname.
+    const packagedElectron = Boolean(resourcesPath) && electron.defaultApp !== true;
+    if (!packagedElectron) {
+        candidates.push(join(process.cwd(), 'resources', 'windows-spawn-helper', binary));
+        candidates.push(join(__dirname, '..', '..', 'resources', 'windows-spawn-helper', binary));
+    }
     for (const candidate of candidates) {
         if (existsSync(candidate))
             return candidate;

package/dist/sidecar/reverse-tools.d.ts

@@ -19,7 +19,7 @@ export interface ReverseToolDeps {
      * main.ts 注入 LocalBackendRouter.resolveChatProject 的适配；未注入时
      * 项目围栏不生效（CLI/test 场景）。
      */
-    resolveProjectRoot?: (chatId: string) => string | null;
+    resolveProjectRoot?: (chatId: string) => Promise<string | null>;
     /**
      * 额外放行的只读根（会话附件目录等）。写入仍只受 projectRoot 围栏约束，
      * 这里只放宽 local_read_file 的读取范围。

package/dist/sidecar/reverse-tools.js

@@ -53,7 +53,7 @@ export function createToolInvokeHandler(deps) {
         const projectRoot = typeof p.context?.workspaceRoot === 'string' && p.context.workspaceRoot
             ? p.context.workspaceRoot
             : p.context?.chatId
-                ? (deps.resolveProjectRoot?.(p.context.chatId) ?? null)
+                ? (await deps.resolveProjectRoot?.(p.context.chatId) ?? null)
                 : null;
         const additionalReadRoots = p.context?.chatId
             ? (deps.resolveAdditionalReadRoots?.(p.context.chatId) ?? [])

package/dist/sidecar/storage-path.js

@@ -1,9 +1,8 @@
 /**
  * Sidecar 持久化库（sessions/traces/history）路径解析。
  *
- * 单独成模块而不是留在 boot.ts：boot.ts 会拉起 localStore 单例（进程内
- * 独占写锁），只想读 history 的调用方（如后台任务过程投影）不该为一个
- * 路径付这个代价。
+ * Kept outside boot.ts so history readers can resolve this separate database
+ * without initializing host storage.
  */
 import path from 'node:path';
 import { homedir } from 'node:os';

package/dist/storage/driver.d.ts

@@ -0,0 +1,57 @@
+import type { ScopedStore } from './scoped-store.js';
+/** Ownership context applied to every host and scenario-pack database operation. */
+export interface TenantScope {
+    tenantId: string;
+    userId: string;
+}
+/** Ownership used by the personal, single-user product. */
+export declare const LOCAL_SCOPE: TenantScope;
+export type PackDbParams = readonly unknown[] | Readonly<Record<string, unknown>>;
+export interface PackDbRunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+/**
+ * Driver-neutral SQL access for scenario-pack repositories.
+ *
+ * The access object carries scope but cannot safely rewrite arbitrary SQL.
+ * Every pack statement must include tenant_id and user_id predicates or values;
+ * drivers and source gates reject missing or mismatched ownership. The driver
+ * connection is never exposed.
+ */
+export interface PackDbAccess {
+    readonly scope: TenantScope;
+    get<T extends Record<string, unknown>>(sql: string, params?: PackDbParams): Promise<T | undefined>;
+    all<T extends Record<string, unknown>>(sql: string, params?: PackDbParams): Promise<T[]>;
+    run(sql: string, params?: PackDbParams): Promise<PackDbRunResult>;
+    exec(sql: string): Promise<void>;
+    transaction<T>(operation: (db: PackDbAccess) => Promise<T>): Promise<T>;
+}
+export type { ScopedStore } from './scoped-store.js';
+/** Product-selectable host storage implementation. */
+export interface StorageDriver {
+    initialize(): Promise<void>;
+    scoped(scope: TenantScope): ScopedStore;
+    packAccess(scope: TenantScope): PackDbAccess;
+    applyPackMigrations(): Promise<void>;
+    close(): Promise<void>;
+}
+export type StorageDriverFactory = () => StorageDriver | Promise<StorageDriver>;
+/** Registers a storage driver. Product packs call this during composition. */
+export declare function registerStorageDriver(id: string, factory: StorageDriverFactory, options?: {
+    default?: boolean;
+}): () => void;
+/** Selects a registered driver before storage initialization. */
+export declare function selectStorageDriver(id: string): void;
+/**
+ * Initializes storage after all product-pack registrations have run.
+ *
+ * Calls are idempotent and share one initialization promise.
+ */
+export declare function initializeStorage(): Promise<StorageDriver>;
+/** Returns a scoped view after explicit storage initialization. */
+export declare function getScopedStore(scope: TenantScope): ScopedStore;
+/** Returns scope-bound scenario-pack access after initialization. */
+export declare function getPackDbAccess(scope: TenantScope): PackDbAccess;
+/** Closes the active driver. Mainly used by host shutdown and tests. */
+export declare function closeStorage(): Promise<void>;

package/dist/storage/driver.js

@@ -0,0 +1,104 @@
+/** Ownership used by the personal, single-user product. */
+export const LOCAL_SCOPE = Object.freeze({
+    tenantId: 'local',
+    userId: 'local',
+});
+const DEFAULT_DRIVER_ID = 'sqlite';
+const factories = new Map();
+let selectedDriverId = DEFAULT_DRIVER_ID;
+let activeDriver = null;
+let initialization = null;
+/** Registers a storage driver. Product packs call this during composition. */
+export function registerStorageDriver(id, factory, options = {}) {
+    if (factories.has(id)) {
+        throw new Error(`[storage] duplicate driver registration: ${id}`);
+    }
+    if (activeDriver || initialization) {
+        throw new Error('[storage] drivers must be registered before initialization');
+    }
+    factories.set(id, factory);
+    if (options.default)
+        selectedDriverId = id;
+    return () => {
+        if (!activeDriver && !initialization) {
+            factories.delete(id);
+            if (selectedDriverId === id)
+                selectedDriverId = DEFAULT_DRIVER_ID;
+        }
+    };
+}
+/** Selects a registered driver before storage initialization. */
+export function selectStorageDriver(id) {
+    if (activeDriver || initialization) {
+        throw new Error('[storage] driver selection is closed after initialization');
+    }
+    selectedDriverId = id;
+}
+/**
+ * Initializes storage after all product-pack registrations have run.
+ *
+ * Calls are idempotent and share one initialization promise.
+ */
+export function initializeStorage() {
+    if (activeDriver)
+        return Promise.resolve(activeDriver);
+    if (initialization)
+        return initialization;
+    const attempt = (async () => {
+        const factory = factories.get(selectedDriverId);
+        if (!factory) {
+            throw new Error(`[storage] unknown storage driver: ${selectedDriverId}`);
+        }
+        let driver = null;
+        try {
+            driver = await factory();
+            await driver.initialize();
+            await driver.applyPackMigrations();
+            activeDriver = driver;
+            return driver;
+        }
+        catch (error) {
+            if (driver) {
+                try {
+                    await driver.close();
+                }
+                catch (_closeError) {
+                    // Initialization error remains the actionable startup failure.
+                }
+            }
+            throw error;
+        }
+    })();
+    initialization = attempt;
+    void attempt.catch(() => {
+        if (initialization === attempt)
+            initialization = null;
+    });
+    return attempt;
+}
+/** Returns a scoped view after explicit storage initialization. */
+export function getScopedStore(scope) {
+    if (!activeDriver) {
+        throw new Error('[storage] initializeStorage() must complete before use');
+    }
+    return activeDriver.scoped(scope);
+}
+/** Returns scope-bound scenario-pack access after initialization. */
+export function getPackDbAccess(scope) {
+    if (!activeDriver) {
+        throw new Error('[storage] initializeStorage() must complete before use');
+    }
+    return activeDriver.packAccess(scope);
+}
+/** Closes the active driver. Mainly used by host shutdown and tests. */
+export async function closeStorage() {
+    const driver = activeDriver;
+    activeDriver = null;
+    initialization = null;
+    if (driver)
+        await driver.close();
+}
+registerStorageDriver(DEFAULT_DRIVER_ID, async () => {
+    const { SqliteStorageDriver } = await import('./sqlite-driver.js');
+    return new SqliteStorageDriver();
+});