@steerable/agent-shell 0.6.20 → 0.6.22

package/dist/storage/pack-migrations.d.ts

@@ -1,10 +1,8 @@
 /**
  * 包迁移注册表 —— ScenarioPack 的存储槽位（0.3b）。
  *
- * `storage/index.ts` 的 `LocalStore` 单例在模块求值时即构造并跑 `migrate()`，
- * 所以包迁移必须在任何 `storage/index.js` import 之前注册。入口
- * （main.ts / server/index.ts）把 `packs/active.ts` 作为第一个 import
- * 来保证这个顺序。
+ * The host initializes the selected driver only after product composition,
+ * so every active pack can register migrations before any database opens.
  *
  * 本模块刻意不 import `storage/index.js`，避免反向依赖。
  */

package/dist/storage/pack-migrations.js

@@ -1,10 +1,8 @@
 /**
  * 包迁移注册表 —— ScenarioPack 的存储槽位（0.3b）。
  *
- * `storage/index.ts` 的 `LocalStore` 单例在模块求值时即构造并跑 `migrate()`，
- * 所以包迁移必须在任何 `storage/index.js` import 之前注册。入口
- * （main.ts / server/index.ts）把 `packs/active.ts` 作为第一个 import
- * 来保证这个顺序。
+ * The host initializes the selected driver only after product composition,
+ * so every active pack can register migrations before any database opens.
  *
  * 本模块刻意不 import `storage/index.js`，避免反向依赖。
  */

package/dist/storage/scoped-store.d.ts

@@ -0,0 +1,125 @@
+import type { ChatAgentRecord, ChatMessageRecord, ChatSessionRecord, HarnessTraceRecord, InsightOutboxRow, TaskRecord } from './index.js';
+import type { InsightKind, InsightsSettings, InsightsSettingsPatch } from './insights-settings.js';
+import type { LlmSettings } from './llm-settings.js';
+import type { TelemetrySettings } from './telemetry-settings.js';
+import type { UsageSummary } from './usage-summary.js';
+import type { WebSearchSettings } from './web-search-settings.js';
+import type { TenantScope } from './driver.js';
+/** Explicit asynchronous storage API bound to one tenant and user. */
+export interface ScopedStore {
+    readonly scope: TenantScope;
+    listChats(page?: number, limit?: number): Promise<{
+        chats: ChatSessionRecord[];
+        total: number;
+    }>;
+    createChat(title?: string, agentId?: string | null, projectId?: string | null): Promise<ChatSessionRecord>;
+    createChatWithId(chatId: string, title?: string, agentId?: string | null, projectId?: string | null): Promise<ChatSessionRecord>;
+    clearProjectAssignment(projectId: string): Promise<number>;
+    getChat(chatId: string): Promise<ChatSessionRecord | null>;
+    updateChat(chatId: string, updates: Partial<Pick<ChatSessionRecord, 'title' | 'systemPrompt' | 'pinnedRefs' | 'isPinned' | 'projectId'>>): Promise<ChatSessionRecord | null>;
+    deleteChat(chatId: string): Promise<boolean>;
+    chatHasMessages(chatId: string): Promise<boolean>;
+    deleteChatIfEmpty(chatId: string): Promise<boolean>;
+    deleteEmptyChats(exceptChatId?: string | null): Promise<string[]>;
+    getChatRecordId(chatId: string): Promise<string | null>;
+    setChatRecordId(chatId: string, recordId: string): Promise<void>;
+    setTurnActive(chatId: string): Promise<void>;
+    clearTurnActive(chatId: string): Promise<void>;
+    getTurnActive(chatId: string): Promise<{
+        startedAt: string;
+    } | null>;
+    listMessages(chatId: string, limit?: number): Promise<ChatMessageRecord[]>;
+    getMessage(chatId: string, messageId: string): Promise<ChatMessageRecord | null>;
+    deleteMessagesFrom(chatId: string, messageId: string): Promise<number>;
+    addMessage(chatId: string, role: ChatMessageRecord['role'], content: string, messageMetadata?: string | null): Promise<ChatMessageRecord>;
+    patchMessageMetadata(chatId: string, messageId: string, patch: Record<string, unknown>): Promise<ChatMessageRecord | null>;
+    replaceChatMessages(chatId: string, messages: Array<{
+        role: ChatMessageRecord['role'];
+        content: string;
+    }>): Promise<void>;
+    listChatAgents(includeArchived?: boolean): Promise<ChatAgentRecord[]>;
+    getChatAgent(agentId: string): Promise<ChatAgentRecord | null>;
+    createChatAgent(input: Partial<ChatAgentRecord> & {
+        name: string;
+    }): Promise<ChatAgentRecord>;
+    updateChatAgent(agentId: string, updates: Partial<ChatAgentRecord>): Promise<ChatAgentRecord | null>;
+    archiveChatAgent(agentId: string): Promise<boolean>;
+    saveTrace(input: {
+        id: string;
+        chatId: string;
+        messageId?: string | null;
+        startedAtMs: number;
+        durationMs?: number | null;
+        status: string;
+        payload: Record<string, unknown>;
+    }): Promise<HarnessTraceRecord>;
+    listTracesByChat(chatId: string, limit?: number): Promise<HarnessTraceRecord[]>;
+    getTrace(traceId: string): Promise<HarnessTraceRecord | null>;
+    createTask(input: {
+        chatId: string;
+        task: string;
+        worktreePath?: string | null;
+        worktreeBranch?: string | null;
+        recordId?: string | null;
+        dependsOn?: string[] | null;
+        initialStatus?: 'blocked' | 'running';
+    }): 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>;
+    saveTaskProcess(taskId: string, processJson: string): Promise<void>;
+    failRunningTasks(reason: string): Promise<number>;
+    recordUsageEvent(input: {
+        chatId?: string | null;
+        kind: string;
+        provider?: string | null;
+        model?: string | null;
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedPromptTokens?: number;
+        costUsd?: number | null;
+    }): Promise<void>;
+    getUsageSummary(sinceDays?: number): Promise<UsageSummary>;
+    getLlmSettings(): Promise<LlmSettings | null>;
+    setLlmSettings(settings: LlmSettings): Promise<LlmSettings>;
+    getTelemetrySettings(): Promise<TelemetrySettings | null>;
+    setTelemetrySettings(settings: Partial<TelemetrySettings>): Promise<TelemetrySettings>;
+    getWebSearchSettings(): Promise<WebSearchSettings | null>;
+    setWebSearchSettings(settings: Partial<WebSearchSettings>): Promise<WebSearchSettings>;
+    getInsightsSettings(): Promise<InsightsSettings | null>;
+    ensureInsightsSettings(): Promise<InsightsSettings>;
+    setInsightsSettings(settings: InsightsSettingsPatch): Promise<InsightsSettings>;
+    enqueueInsight(kind: InsightKind, payload: Record<string, unknown>): Promise<InsightOutboxRow>;
+    listInsightOutbox(opts?: {
+        uploaded?: boolean;
+        kind?: InsightKind;
+        limit?: number;
+    }): Promise<InsightOutboxRow[]>;
+    markInsightUploaded(id: string): Promise<void>;
+    markInsightUploadError(id: string, error: string): Promise<void>;
+    insightStats(): Promise<{
+        events: number;
+        turns: number;
+        profile: number;
+        pending: number;
+    }>;
+    exportInsightsBundle(): Promise<{
+        schema: string;
+        exportedAt: string;
+        installId: string;
+        settings: {
+            shareBehavior: boolean;
+            shareConversation: boolean;
+            shareProfile: boolean;
+        };
+        profile: import('./insights-settings.js').InsightsProfile;
+        stats: {
+            events: number;
+            turns: number;
+            profile: number;
+            pending: number;
+        };
+        records: InsightOutboxRow[];
+    }>;
+}

package/dist/storage/scoped-store.js

@@ -0,0 +1 @@
+export {};

package/dist/storage/sqlite-driver.d.ts

@@ -0,0 +1,16 @@
+import type { PackDbAccess, StorageDriver, TenantScope } from './driver.js';
+import type { ScopedStore } from './scoped-store.js';
+/** Default local SQLite storage driver. */
+export declare class SqliteStorageDriver implements StorageDriver {
+    private db;
+    private writeLease;
+    private localSqliteStore;
+    private readonly stores;
+    initialize(): Promise<void>;
+    scoped(scope: TenantScope): ScopedStore;
+    packAccess(scope: TenantScope): PackDbAccess;
+    applyPackMigrations(): Promise<void>;
+    close(): Promise<void>;
+    private requireDb;
+    private scopeKey;
+}

package/dist/storage/sqlite-driver.js

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { getProductConfig } from '../product-config.js';
+import { getUserDataDir } from '../runtime.js';
+import { LOCAL_SCOPE } from './driver.js';
+import { SqliteScopedStore } from './index.js';
+import { acquireWriteLease, lockPathForDb, } from './write-lease.js';
+import { acquireWriteLeaseOrExit } from './write-lease-error.js';
+function invokeStatement(statement, operation, params) {
+    if (Array.isArray(params))
+        return statement[operation](...params);
+    if (params)
+        return statement[operation](params);
+    return statement[operation]();
+}
+function assertScopedPackStatement(sql, params, scope) {
+    if (/^\s*PRAGMA\b/i.test(sql) || /\bsqlite_master\b/i.test(sql))
+        return;
+    if (!/\btenant_id\b/i.test(sql) || !/\buser_id\b/i.test(sql)) {
+        throw new Error('[storage] pack SQL must bind tenant_id and user_id');
+    }
+    if (!params) {
+        throw new Error('[storage] scoped pack parameters are required');
+    }
+    if (Array.isArray(params)) {
+        if (!params.includes(scope.tenantId) || !params.includes(scope.userId)) {
+            throw new Error('[storage] pack parameters do not match the bound scope');
+        }
+        return;
+    }
+    const named = params;
+    const tenantId = named.tenantId ?? named.tenant_id;
+    const userId = named.userId ?? named.user_id;
+    if (tenantId !== scope.tenantId || userId !== scope.userId) {
+        throw new Error('[storage] pack parameters do not match the bound scope');
+    }
+}
+class SqlitePackDbAccess {
+    db;
+    scope;
+    constructor(db, scope) {
+        this.db = db;
+        this.scope = scope;
+    }
+    async get(sql, params) {
+        assertScopedPackStatement(sql, params, this.scope);
+        return invokeStatement(this.db.prepare(sql), 'get', params);
+    }
+    async all(sql, params) {
+        assertScopedPackStatement(sql, params, this.scope);
+        return invokeStatement(this.db.prepare(sql), 'all', params);
+    }
+    async run(sql, params) {
+        assertScopedPackStatement(sql, params, this.scope);
+        const result = invokeStatement(this.db.prepare(sql), 'run', params);
+        return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
+    }
+    async exec(sql) {
+        this.db.exec(sql);
+    }
+    async transaction(operation) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const value = await operation(this);
+            this.db.exec('COMMIT');
+            return value;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+}
+/** Default local SQLite storage driver. */
+export class SqliteStorageDriver {
+    db = null;
+    writeLease = null;
+    localSqliteStore = null;
+    stores = new Map();
+    async initialize() {
+        if (this.db)
+            return;
+        const dbPath = path.join(getUserDataDir(), getProductConfig().dbFileName ?? 'agent-shell.db');
+        this.writeLease = acquireWriteLeaseOrExit(() => acquireWriteLease(lockPathForDb(dbPath)));
+        let db = null;
+        try {
+            db = new Database(dbPath);
+            db.pragma('journal_mode = WAL');
+            db.pragma('foreign_keys = ON');
+            this.db = db;
+            const local = new SqliteScopedStore(db, LOCAL_SCOPE);
+            await local.initialize();
+            this.localSqliteStore = local;
+            this.stores.set(this.scopeKey(LOCAL_SCOPE), local);
+        }
+        catch (error) {
+            db?.close();
+            this.writeLease.release();
+            this.writeLease = null;
+            throw error;
+        }
+    }
+    scoped(scope) {
+        const db = this.requireDb();
+        const key = this.scopeKey(scope);
+        const existing = this.stores.get(key);
+        if (existing)
+            return existing;
+        const store = new SqliteScopedStore(db, scope);
+        this.stores.set(key, store);
+        return store;
+    }
+    packAccess(scope) {
+        return new SqlitePackDbAccess(this.requireDb(), scope);
+    }
+    async applyPackMigrations() {
+        this.localSqliteStore?.applyPackMigrations();
+    }
+    async close() {
+        this.stores.clear();
+        this.db?.close();
+        this.db = null;
+        this.localSqliteStore = null;
+        this.writeLease?.release();
+        this.writeLease = null;
+    }
+    requireDb() {
+        if (!this.db)
+            throw new Error('[storage] SQLite driver is not initialized');
+        return this.db;
+    }
+    scopeKey(scope) {
+        return `${scope.tenantId}\u0000${scope.userId}`;
+    }
+}

package/dist/storage/write-lease-error.d.ts

@@ -0,0 +1,11 @@
+interface ElectronExit {
+    app: {
+        exit(code: number): void;
+    };
+    dialog: {
+        showErrorBox(title: string, message: string): void;
+    };
+}
+/** Maps write-lease contention to the desktop's user-facing startup failure. */
+export declare function acquireWriteLeaseOrExit<T>(acquire: () => T, loadElectron?: () => Promise<ElectronExit>, exitProcess?: (code: number) => void): T;
+export {};

package/dist/storage/write-lease-error.js

@@ -0,0 +1,18 @@
+import { StoreAlreadyOwnedError } from './write-lease.js';
+/** Maps write-lease contention to the desktop's user-facing startup failure. */
+export function acquireWriteLeaseOrExit(acquire, loadElectron = () => import('electron'), exitProcess = (code) => process.exit(code)) {
+    try {
+        return acquire();
+    }
+    catch (error) {
+        if (error instanceof StoreAlreadyOwnedError) {
+            void loadElectron()
+                .then(({ app, dialog }) => {
+                dialog.showErrorBox('无法启动', '另一个实例正在运行并占用本地数据库。请先关闭该实例，再重新打开应用。');
+                app.exit(1);
+            })
+                .catch(() => exitProcess(1));
+        }
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.20",
+  "version": "0.6.22",
   "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/",
@@ -15,6 +15,14 @@
   "type": "module",
   "main": "dist/runtime.js",
   "exports": {
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./server/start": {
+      "types": "./dist/server/start.d.ts",
+      "default": "./dist/server/start.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"
@@ -41,9 +49,9 @@
     "electron-store": "^8.1.0",
     "he": "^1.2.0",
     "node-pty": "^1.1.0",
-    "@steerable/agent-protocol": "0.6.20",
-    "@steerable/agent-harness": "0.6.20",
-    "@steerable/pack-sdk": "0.6.20"
+    "@steerable/agent-harness": "0.6.22",
+    "@steerable/agent-protocol": "0.6.22",
+    "@steerable/pack-sdk": "0.6.22"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
@@ -58,9 +66,10 @@
     "gen": "echo agent-shell-ts",
     "build": "tsc -p tsconfig.json && node copy-skills.mjs && node scripts/build-preload.mjs",
     "test": "vitest run",
-    "lint": "tsc -p tsconfig.json --noEmit && node scripts/check-shell-neutral.mjs",
+    "lint": "tsc -p tsconfig.json --noEmit && node scripts/check-shell-neutral.mjs && node scripts/check-storage-boundaries.mjs",
     "check:drift": "echo ok",
     "shell:neutral": "node scripts/check-shell-neutral.mjs",
+    "storage:boundaries": "node scripts/check-storage-boundaries.mjs",
     "web": "ELECTRON_RUN_AS_NODE=1 DEEPPATH_WEB_DIST=${DEEPPATH_WEB_DIST:-../web/app/dist} node node_modules/electron/cli.js dist/server/index.js",
     "client": "DEEPPATH_FORCE_BUNDLED_WEB=1 DEEPPATH_WEB_DIST=${DEEPPATH_WEB_DIST:-../web/app/dist} node node_modules/electron/cli.js dist/main.js"
   }

package/dist/storage/local-store-singleton.d.ts

@@ -1,28 +0,0 @@
-/**
- * The `localStore` singleton's friendly handling of a held write lease.
- *
- * `createLocalStore` turns a `StoreAlreadyOwnedError` into a readable dialog
- * + exit instead of a raw stack. The single-instance lock (single-instance.ts)
- * already stops a second OS process earlier; this is the deeper kernel-lock
- * backstop for the cases it cannot reach (a bypassed lock, two userData dirs
- * pointed at one database, a crashed-then-relaunched app racing its own
- * cleanup).
- *
- * This lives in its own module — and takes an injectable constructor — so the
- * error-mapping path is testable in a plain-node vitest worker. Importing
- * `storage/index.ts` constructs the real `LocalStore`, which loads
- * better-sqlite3 (Electron ABI) and cannot resolve outside Electron; this
- * module imports only the error class, so it loads anywhere. `dialog`/`app`
- * are loaded lazily for the same reason.
- */
-/** The slice of electron's app/dialog the friendly exit uses. */
-interface ElectronExit {
-    app: {
-        exit(code: number): void;
-    };
-    dialog: {
-        showErrorBox(title: string, message: string): void;
-    };
-}
-export declare function createLocalStore<T>(construct: () => T, loadElectron?: () => Promise<ElectronExit>, exitProcess?: (code: number) => void): T;
-export {};

package/dist/storage/local-store-singleton.js

@@ -1,38 +0,0 @@
-/**
- * The `localStore` singleton's friendly handling of a held write lease.
- *
- * `createLocalStore` turns a `StoreAlreadyOwnedError` into a readable dialog
- * + exit instead of a raw stack. The single-instance lock (single-instance.ts)
- * already stops a second OS process earlier; this is the deeper kernel-lock
- * backstop for the cases it cannot reach (a bypassed lock, two userData dirs
- * pointed at one database, a crashed-then-relaunched app racing its own
- * cleanup).
- *
- * This lives in its own module — and takes an injectable constructor — so the
- * error-mapping path is testable in a plain-node vitest worker. Importing
- * `storage/index.ts` constructs the real `LocalStore`, which loads
- * better-sqlite3 (Electron ABI) and cannot resolve outside Electron; this
- * module imports only the error class, so it loads anywhere. `dialog`/`app`
- * are loaded lazily for the same reason.
- */
-import { StoreAlreadyOwnedError } from './write-lease.js';
-export function createLocalStore(construct, loadElectron = () => import('electron'), exitProcess = (code) => process.exit(code)) {
-    try {
-        return construct();
-    }
-    catch (err) {
-        if (err instanceof StoreAlreadyOwnedError) {
-            void loadElectron()
-                .then(({ app, dialog }) => {
-                dialog.showErrorBox('无法启动', '另一个实例正在运行并占用本地数据库。请先关闭该实例，再重新打开应用。');
-                app.exit(1);
-            })
-                .catch(() => exitProcess(1));
-            // Unreachable once electron resolves (app.exit ends the process); the
-            // rethrow is the non-electron fallback so a plain-node import still
-            // fails loud rather than returning a half-built store.
-            throw err;
-        }
-        throw err;
-    }
-}