@steerable/agent-shell 0.6.20 → 0.6.22

package/dist/storage/index.d.ts

@@ -1,9 +1,11 @@
-import Database from 'better-sqlite3';
+import type Database from 'better-sqlite3';
 import { type LlmSettings } from './llm-settings.js';
 import { type TelemetrySettings } from './telemetry-settings.js';
 import { type WebSearchSettings } from './web-search-settings.js';
 import { type InsightKind, type InsightsProfile, type InsightsSettings, type InsightsSettingsPatch } from './insights-settings.js';
 import { type UsageSummary } from './usage-summary.js';
+import type { TenantScope } from './driver.js';
+import type { ScopedStore } from './scoped-store.js';
 export type { UsageModelBucket, UsageSummary } from './usage-summary.js';
 export interface ChatSessionRecord {
     id: string;
@@ -122,15 +124,15 @@ export interface InsightOutboxRow {
     uploadError: string | null;
 }
 declare const INSIGHTS_EXPORT_SCHEMA = "deeppath-agent-insights/v1";
-export declare class LocalStore {
+export declare class SqliteScopedStore implements ScopedStore {
     private readonly db;
-    private readonly writeLease;
-    constructor();
-    /**
-     * 场景包存储扩展点：把同一个 SQLite 连接借给包内存储类（各包的
-     * <Pack>Store）。包只读写自己 migrations 声明的包前缀表；shell 表结构对包不透明。
-     */
-    getPackDb(): Database.Database;
+    readonly scope: TenantScope;
+    constructor(db: Database.Database, scope: TenantScope);
+    /** Initializes schema, cleanup, migrations, and seeds for this scope. */
+    initialize(): Promise<void>;
+    private migrateScopedSchema;
+    private copyLegacyScopeRows;
+    private tableColumns;
     /**
      * One-time cleanup for rows that became orphaned while `foreign_keys` was
      * off in earlier versions of the app (deleteChat() previously left
@@ -138,9 +140,8 @@ export declare class LocalStore {
      */
     private cleanupOrphanedRows;
     private migrate;
-    private readonly appliedPackMigrations;
     /**
-     * 应用尚未应用的已注册包迁移（幂等，按包 id 去重）。
+     * Applies registered migrations once per driver-persisted pack generation.
      */
     applyPackMigrations(): void;
     /**
@@ -164,11 +165,11 @@ export declare class LocalStore {
      * integer range, falling back to `fallback` for non-finite input.
      */
     private static clampInt;
-    listChats(page?: number, limit?: number): {
+    listChats(page?: number, limit?: number): Promise<{
         chats: ChatSessionRecord[];
         total: number;
-    };
-    createChat(title?: string, agentId?: string | null, projectId?: string | null): ChatSessionRecord;
+    }>;
+    createChat(title?: string, agentId?: string | null, projectId?: string | null): Promise<ChatSessionRecord>;
     /**
      * 用调用方给定的 id 建会话（**幂等**：已存在则原样返回，不覆盖）。
      *
@@ -178,32 +179,32 @@ export declare class LocalStore {
      * 按 URL 里的 id 现场补建，才不会把一次本来能跑的任务打断在
      * `chat not found`。
      */
-    createChatWithId(chatId: string, title?: string, agentId?: string | null, projectId?: string | null): ChatSessionRecord;
+    createChatWithId(chatId: string, title?: string, agentId?: string | null, projectId?: string | null): Promise<ChatSessionRecord>;
     /** 删除项目时调用：把该项目下所有会话降级为无项目对话（不删会话）。 */
-    clearProjectAssignment(projectId: string): number;
-    getChat(chatId: string): ChatSessionRecord | null;
-    updateChat(chatId: string, updates: Partial<Pick<ChatSessionRecord, 'title' | 'systemPrompt' | 'pinnedRefs' | 'isPinned' | 'projectId'>>): ChatSessionRecord | null;
-    deleteChat(chatId: string): boolean;
-    chatHasMessages(chatId: string): boolean;
+    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>;
     /**
      * Drop a chat that never received a message. Used when the user leaves a
      * "新对话" composer without sending — empty sessions must not stay in the
      * sidebar. Missing or already-populated chats are a no-op (`false`).
      */
-    deleteChatIfEmpty(chatId: string): boolean;
+    deleteChatIfEmpty(chatId: string): Promise<boolean>;
     /**
      * Delete every session with zero messages, optionally keeping `exceptChatId`
      * (the open composer). Returns the removed ids.
      */
-    deleteEmptyChats(exceptChatId?: string | null): string[];
+    deleteEmptyChats(exceptChatId?: string | null): Promise<string[]>;
     /**
      * W5-2: the chat's ACTIVE durable-record id on the sidecar. Regenerate
      * forks the record (non-destructive — the old tail stays discoverable as
      * a branch), so a chat's live record moves from `chatId` to its branch;
      * null means the chatId itself.
      */
-    getChatRecordId(chatId: string): string | null;
-    setChatRecordId(chatId: string, recordId: string): void;
+    getChatRecordId(chatId: string): Promise<string | null>;
+    setChatRecordId(chatId: string, recordId: string): Promise<void>;
     /**
      * W7-1: durable "a turn is in flight" marker, written BEFORE the stream
      * starts and cleared only after the terminal assistant message persists
@@ -216,17 +217,17 @@ export declare class LocalStore {
      * stale marker the detector dismisses once it sees the trailing
      * assistant message.
      */
-    setTurnActive(chatId: string): void;
-    clearTurnActive(chatId: string): void;
-    getTurnActive(chatId: string): {
+    setTurnActive(chatId: string): Promise<void>;
+    clearTurnActive(chatId: string): Promise<void>;
+    getTurnActive(chatId: string): Promise<{
         startedAt: string;
-    } | null;
+    } | null>;
     /**
      * Newest first under {@link MESSAGE_ORDER_DESC}, capped at `limit`; callers
      * that want transcript order reverse it.
      */
-    listMessages(chatId: string, limit?: number): ChatMessageRecord[];
-    getMessage(chatId: string, messageId: string): ChatMessageRecord | null;
+    listMessages(chatId: string, limit?: number): Promise<ChatMessageRecord[]>;
+    getMessage(chatId: string, messageId: string): Promise<ChatMessageRecord | null>;
     /**
      * Deletes `messageId` and every message after it in the same chat. Used by
      * regenerate: truncate from the assistant reply being regenerated onward, so
@@ -237,8 +238,14 @@ export declare class LocalStore {
      * "After" is {@link MESSAGE_CUT_FROM_ID}, the same key `listMessages` orders
      * by, so the cut matches what the user sees below the regenerated reply.
      */
-    deleteMessagesFrom(chatId: string, messageId: string): number;
-    addMessage(chatId: string, role: ChatMessageRecord['role'], content: string, messageMetadata?: string | null): ChatMessageRecord;
+    deleteMessagesFrom(chatId: string, messageId: string): Promise<number>;
+    addMessage(chatId: string, role: ChatMessageRecord['role'], content: string, messageMetadata?: string | null): Promise<ChatMessageRecord>;
+    /**
+     * 浅合并助手消息的 JSON metadata（例如回合结束后写入 suggestedReplies）。
+     * 不碰 updated_at：这类补丁不是用户可见的会话活动。
+     * metadata 损坏或非对象时从空对象开始合。
+     */
+    patchMessageMetadata(chatId: string, messageId: string, patch: Record<string, unknown>): Promise<ChatMessageRecord | null>;
     /**
      * W1.2.1: replace the chat's whole message list with a branch projection.
      * The desktop store is the UI projection of the ACTIVE framework record —
@@ -250,14 +257,14 @@ export declare class LocalStore {
     replaceChatMessages(chatId: string, messages: Array<{
         role: ChatMessageRecord['role'];
         content: string;
-    }>): void;
-    listChatAgents(includeArchived?: boolean): ChatAgentRecord[];
-    getChatAgent(agentId: string): ChatAgentRecord | null;
+    }>): Promise<void>;
+    listChatAgents(includeArchived?: boolean): Promise<ChatAgentRecord[]>;
+    getChatAgent(agentId: string): Promise<ChatAgentRecord | null>;
     createChatAgent(input: Partial<ChatAgentRecord> & {
         name: string;
-    }): ChatAgentRecord;
-    updateChatAgent(agentId: string, updates: Partial<ChatAgentRecord>): ChatAgentRecord | null;
-    archiveChatAgent(agentId: string): boolean;
+    }): Promise<ChatAgentRecord>;
+    updateChatAgent(agentId: string, updates: Partial<ChatAgentRecord>): Promise<ChatAgentRecord | null>;
+    archiveChatAgent(agentId: string): Promise<boolean>;
     saveTrace(input: {
         id: string;
         chatId: string;
@@ -266,9 +273,9 @@ export declare class LocalStore {
         durationMs?: number | null;
         status: string;
         payload: Record<string, unknown>;
-    }): HarnessTraceRecord;
-    listTracesByChat(chatId: string, limit?: number): HarnessTraceRecord[];
-    getTrace(traceId: string): HarnessTraceRecord | null;
+    }): Promise<HarnessTraceRecord>;
+    listTracesByChat(chatId: string, limit?: number): Promise<HarnessTraceRecord[]>;
+    getTrace(traceId: string): Promise<HarnessTraceRecord | null>;
     createTask(input: {
         chatId: string;
         task: string;
@@ -279,26 +286,26 @@ export declare class LocalStore {
         dependsOn?: string[] | null;
         /** 初始状态（缺省 running；有未就绪依赖时调用方传 blocked）。 */
         initialStatus?: 'blocked' | 'running';
-    }): TaskRecord;
-    getTask(taskId: string): TaskRecord | null;
+    }): Promise<TaskRecord>;
+    getTask(taskId: string): Promise<TaskRecord | null>;
     /** 按 chat 列任务（updated_at 新→旧）；chatId 缺省时列全部（任务面板的全局视图）。 */
-    listTasks(chatId?: string, limit?: number): TaskRecord[];
+    listTasks(chatId?: string, limit?: number): Promise<TaskRecord[]>;
     /**
      * 终态/进度回写。只写传入的字段（undefined 过滤），updated_at 总是刷新。
      * 与 updateChat 同约定：显式传 null 才是置空。
      */
-    updateTask(taskId: string, updates: Partial<Pick<TaskRecord, 'status' | 'answer' | 'error' | 'worktreeState' | 'traceId' | 'recordId'>>): TaskRecord | null;
+    updateTask(taskId: string, updates: Partial<Pick<TaskRecord, 'status' | 'answer' | 'error' | 'worktreeState' | 'traceId' | 'recordId'>>): Promise<TaskRecord | null>;
     /**
      * 回写推理时间线。故意不碰 updated_at——流过程中的增量不应把任务
      * 面板按「最近活动」反复顶到最上。
      */
-    saveTaskProcess(taskId: string, processJson: string): void;
+    saveTaskProcess(taskId: string, processJson: string): Promise<void>;
     /**
      * 启动清扫：running 任务只可能属于上一个已死的进程（任务流不跨进程
      * 存活），全部落成 failed/interrupted——与 W7-1 turn_active 检测器同
      * 理，残留 running 是崩溃签名，不是真相。
      */
-    failRunningTasks(reason: string): number;
+    failRunningTasks(reason: string): Promise<number>;
     /**
      * 记录一条用量事件(一轮 chat / 一次标题生成 / 一次摘要压缩等)。
      * `costUsd` 为 null 表示该模型无单价(本地/未知)——存 NULL,面板渲染为 "—"。
@@ -313,38 +320,38 @@ export declare class LocalStore {
         totalTokens: number;
         cachedPromptTokens?: number;
         costUsd?: number | null;
-    }): void;
+    }): Promise<void>;
     /**
      * 聚合最近 `sinceDays` 天的用量:按 model 分桶( token 合计 + 成本合计),
      * 外加总计。成本只统计有单价的模型(cost_usd 非 NULL);无单价模型的
      * token 照常计入,但成本列不计。返回按 totalTokens 降序。
      */
-    getUsageSummary(sinceDays?: number): UsageSummary;
-    getLlmSettings(): LlmSettings | null;
-    setLlmSettings(settings: LlmSettings): LlmSettings;
+    getUsageSummary(sinceDays?: number): Promise<UsageSummary>;
+    getLlmSettings(): Promise<LlmSettings | null>;
+    setLlmSettings(settings: LlmSettings): Promise<LlmSettings>;
     /** 读取遥测设置;从未配置过时返回 null(调用方按"关"处理)。 */
-    getTelemetrySettings(): TelemetrySettings | null;
-    setTelemetrySettings(settings: Partial<TelemetrySettings>): TelemetrySettings;
-    getWebSearchSettings(): WebSearchSettings | null;
-    setWebSearchSettings(settings: Partial<WebSearchSettings>): WebSearchSettings;
-    getInsightsSettings(): InsightsSettings | null;
-    ensureInsightsSettings(): InsightsSettings;
-    setInsightsSettings(settings: InsightsSettingsPatch): InsightsSettings;
-    enqueueInsight(kind: InsightKind, payload: Record<string, unknown>): InsightOutboxRow;
+    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;
-    }): InsightOutboxRow[];
-    markInsightUploaded(id: string): void;
-    markInsightUploadError(id: string, error: string): void;
-    insightStats(): {
+    }): 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(): {
+    }>;
+    exportInsightsBundle(): Promise<{
         schema: typeof INSIGHTS_EXPORT_SCHEMA;
         exportedAt: string;
         installId: string;
@@ -361,13 +368,19 @@ export declare class LocalStore {
             pending: number;
         };
         records: InsightOutboxRow[];
-    };
+    }>;
     private mapInsightOutbox;
     private mapChatSession;
     private mapChatMessage;
     private mapHarnessTrace;
     private mapTask;
     private mapChatAgent;
+    private getSetting;
+    private setSetting;
     private safeJson;
 }
-export declare const localStore: LocalStore;
+export type { PackDbAccess, StorageDriver, StorageDriverFactory, TenantScope, } from './driver.js';
+export type { ScopedStore } from './scoped-store.js';
+export { LOCAL_SCOPE, closeStorage, getPackDbAccess, getScopedStore, initializeStorage, selectStorageDriver, } from './driver.js';
+export { registerStorageDriver } from './driver.js';
+export { SqliteStorageDriver } from './sqlite-driver.js';