@steerable/agent-shell 0.6.15

package/dist/storage/index.d.ts

@@ -0,0 +1,373 @@
+import 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';
+export type { UsageModelBucket, UsageSummary } from './usage-summary.js';
+export interface ChatSessionRecord {
+    id: string;
+    title: string;
+    userId: string;
+    agentId: string | null;
+    /** 项目模式：绑定的项目 id（ProjectRegistry）。null = 无项目对话（不沙箱）。 */
+    projectId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    isPinned: boolean;
+    systemPrompt: string | null;
+    pinnedRefs: unknown[] | null;
+}
+export interface ChatMessageRecord {
+    id: string;
+    chatId: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    messageMetadata: string | null;
+    createdAt: string;
+}
+export interface ChatAgentRecord {
+    id: string;
+    slug: string | null;
+    name: string;
+    icon: string | null;
+    color: string | null;
+    description: string | null;
+    rolePrompt: string | null;
+    forbiddenPrompt: string | null;
+    /**
+     * 勾选的技能（skill `dirName` 或 `name`）：正文无条件常驻系统提示词
+     * （绕过触发条件与 eager/catalog 分层）。空 = 不钉任何技能。
+     */
+    skillIds: string[];
+    /**
+     * 模型可见工具的准入策略。`allowlist`/`denylist` 是真实限制：每轮工具
+     * 列表、`tool_search` 发现结果、以及反向通道的分发复检三处都执行。
+     */
+    toolPolicy: {
+        mode: 'all' | 'allowlist' | 'denylist';
+        tools: string[];
+    };
+    /**
+     * true（默认）= 未勾选的技能照旧按触发条件/目录按需加载；
+     * false = 只允许 {@link skillIds} 里的技能（硬白名单，注入、目录、
+     * `/技能名` 显式触发三处都拦）。
+     */
+    allowExternalSkills: boolean;
+    /**
+     * true = 无视技能的触发条件全量加载（内置「智能助手」的行为）。
+     * 与 `allowExternalSkills: false` 同时设置时白名单仍然优先。
+     */
+    loadAllSkills: boolean;
+    isBuiltin: boolean;
+    isArchived: boolean;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface HarnessTraceRecord {
+    id: string;
+    chatId: string;
+    messageId: string | null;
+    startedAtMs: number;
+    durationMs: number | null;
+    status: string;
+    payload: string;
+    createdAt: string;
+}
+/**
+ * 跨 turn 后台任务（4.6a）。task_run 工具落一行后立刻返回，任务由宿主的
+ * 独立 sidecar 流跑完（不绑父 turn 生命周期），终态回写本表。
+ *
+ * worktree* 三列是 Task×Worktree 组合（4.6c）：worktreeState 仅对
+ * worktree 任务有意义——任务终态后 'pending'（等待用户合并/丢弃），
+ * 操作后落 'merged' / 'discarded'。
+ */
+export interface TaskRecord {
+    id: string;
+    chatId: string;
+    /** 完整的任务指令（模型给的 task 原文）。 */
+    task: string;
+    /** blocked = 依赖未就绪，等调度点火（依赖任务全部 completed 后自动转 running）。 */
+    status: 'blocked' | 'running' | 'completed' | 'failed';
+    answer: string | null;
+    error: string | null;
+    worktreePath: string | null;
+    worktreeBranch: string | null;
+    worktreeState: 'pending' | 'merged' | 'discarded' | null;
+    /** sidecar durable record id（task:<id>），trace.fetch / 排障用。 */
+    recordId: string | null;
+    traceId: string | null;
+    /** 编排依赖：本任务等这些 taskId 全部 completed 才点火（null = 无依赖，立即点火）。 */
+    dependsOn: string[] | null;
+    /** 推理时间线 JSON（与主对话 TurnBlock 同形）；流过程中回写，重启后可回看。 */
+    processJson: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export type { LlmSettings, LlmProvider } from './llm-settings.js';
+export { DEFAULT_SYSTEM_PROMPT } from './llm-settings.js';
+export type { TelemetrySettings, TelemetryPrivacyMode } from './telemetry-settings.js';
+export { DEFAULT_TELEMETRY_SETTINGS, telemetryEnabled, normalizeTelemetryEndpoint, } from './telemetry-settings.js';
+export type { WebSearchSettings, WebSearchProviderId } from './web-search-settings.js';
+export { DEFAULT_WEB_SEARCH_SETTINGS, mergeWebSearchSettings, hostedSearchAvailable, sidecarWebSearchEnv, defaultSearchBaseUrl, } from './web-search-settings.js';
+export type { InsightsSettings, InsightsProfile, InsightKind, InsightsSettingsPatch } from './insights-settings.js';
+export { mergeInsightsSettings, insightsNeedsPrompt, canAutoUpload, rowsEligibleForAutoUpload, resolveInsightsApiBase, } from './insights-settings.js';
+export interface InsightOutboxRow {
+    id: string;
+    kind: InsightKind;
+    payload: Record<string, unknown>;
+    createdAt: string;
+    uploadedAt: string | null;
+    uploadError: string | null;
+}
+declare const INSIGHTS_EXPORT_SCHEMA = "deeppath-agent-insights/v1";
+export declare class LocalStore {
+    private readonly db;
+    private readonly writeLease;
+    constructor();
+    /**
+     * 场景包存储扩展点：把同一个 SQLite 连接借给包内存储类（各包的
+     * <Pack>Store）。包只读写自己 migrations 声明的包前缀表；shell 表结构对包不透明。
+     */
+    getPackDb(): Database.Database;
+    /**
+     * One-time cleanup for rows that became orphaned while `foreign_keys` was
+     * off in earlier versions of the app (deleteChat() previously left
+     * chat_messages/harness_traces behind for deleted chat_sessions).
+     */
+    private cleanupOrphanedRows;
+    private migrate;
+    private readonly appliedPackMigrations;
+    /**
+     * 应用尚未应用的已注册包迁移（幂等，按包 id 去重）。
+     */
+    applyPackMigrations(): void;
+    /**
+     * 应用一条包智能体种子（0.3d 的通用机制）：
+     * 包激活 —— 不存在则种子；命中历史代文案则静默升级到当前代；被归档但
+     * 未定制的行重新露出。包缺席 —— 未定制的内置行归档。用户改过的行不动。
+     */
+    private applyPackAgentSeed;
+    /**
+     * SQLite 没有 ADD COLUMN IF NOT EXISTS，先查 PRAGMA 再加列。
+     *
+     * @returns 本次是否真的加了列（调用方据此做一次性回填）。
+     */
+    private ensureColumn;
+    private seedDefaults;
+    /**
+     * `Math.max`/`Math.min` propagate `NaN` instead of clamping it, so a bad
+     * caller-supplied value (e.g. `?page=abc` parsed via `Number()`) used to
+     * produce a NaN OFFSET/LIMIT and an ill-defined SQL query result. All
+     * paginated list methods below route through this to clamp to a sane
+     * integer range, falling back to `fallback` for non-finite input.
+     */
+    private static clampInt;
+    listChats(page?: number, limit?: number): {
+        chats: ChatSessionRecord[];
+        total: number;
+    };
+    createChat(title?: string, agentId?: string | null, projectId?: string | null): ChatSessionRecord;
+    /**
+     * 用调用方给定的 id 建会话（**幂等**：已存在则原样返回，不覆盖）。
+     *
+     * 会话 URL（`/api/v2/chats/:id/*`、前端 `#/agent/:chatId`）在产品和外部
+     * 平台眼里就是「一次会话任务」的身份。本地会话可能因为用户清理、空会话
+     * prune、或换机重装而消失，但平台仍会拿原来的 URL 再次运行——首次发送时
+     * 按 URL 里的 id 现场补建，才不会把一次本来能跑的任务打断在
+     * `chat not found`。
+     */
+    createChatWithId(chatId: string, title?: string, agentId?: string | null, projectId?: string | null): 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;
+    /**
+     * 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;
+    /**
+     * Delete every session with zero messages, optionally keeping `exceptChatId`
+     * (the open composer). Returns the removed ids.
+     */
+    deleteEmptyChats(exceptChatId?: string | null): 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;
+    /**
+     * W7-1: durable "a turn is in flight" marker, written BEFORE the stream
+     * starts and cleared only after the terminal assistant message persists
+     * (or the turn fails before any reply could exist). A crash or kill
+     * mid-turn never reaches the clear, so a surviving marker is the crash
+     * signature — distinct from `completionStatus: 'cancelled' | 'failed'`,
+     * which only a live process can write. Cleared AFTER the assistant
+     * write, never before: the reverse order would turn a crash in that gap
+     * into a lost reply with no recourse, while this order's worst case is a
+     * stale marker the detector dismisses once it sees the trailing
+     * assistant message.
+     */
+    setTurnActive(chatId: string): void;
+    clearTurnActive(chatId: string): void;
+    getTurnActive(chatId: string): {
+        startedAt: string;
+    } | 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;
+    /**
+     * Deletes `messageId` and every message after it in the same chat. Used by
+     * regenerate: truncate from the assistant reply being regenerated onward, so
+     * the next turn re-runs against the history as it stood right before that
+     * reply, instead of appending a new "please regenerate" user turn on top of
+     * stale history.
+     *
+     * "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;
+    /**
+     * 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 —
+     * switching branches re-projects it. The previous projection is not lost:
+     * its source of truth is the framework history record it came from.
+     * Timestamps are synthesized (base + index ms) to preserve projection
+     * order under the created_at ordering.
+     */
+    replaceChatMessages(chatId: string, messages: Array<{
+        role: ChatMessageRecord['role'];
+        content: string;
+    }>): void;
+    listChatAgents(includeArchived?: boolean): ChatAgentRecord[];
+    getChatAgent(agentId: string): ChatAgentRecord | null;
+    createChatAgent(input: Partial<ChatAgentRecord> & {
+        name: string;
+    }): ChatAgentRecord;
+    updateChatAgent(agentId: string, updates: Partial<ChatAgentRecord>): ChatAgentRecord | null;
+    archiveChatAgent(agentId: string): boolean;
+    saveTrace(input: {
+        id: string;
+        chatId: string;
+        messageId?: string | null;
+        startedAtMs: number;
+        durationMs?: number | null;
+        status: string;
+        payload: Record<string, unknown>;
+    }): HarnessTraceRecord;
+    listTracesByChat(chatId: string, limit?: number): HarnessTraceRecord[];
+    getTrace(traceId: string): HarnessTraceRecord | null;
+    createTask(input: {
+        chatId: string;
+        task: string;
+        worktreePath?: string | null;
+        worktreeBranch?: string | null;
+        recordId?: string | null;
+        /** 编排依赖（taskId 列表）；非空且未就绪时初始状态为 blocked 而非 running。 */
+        dependsOn?: string[] | null;
+        /** 初始状态（缺省 running；有未就绪依赖时调用方传 blocked）。 */
+        initialStatus?: 'blocked' | 'running';
+    }): TaskRecord;
+    getTask(taskId: string): TaskRecord | null;
+    /** 按 chat 列任务（updated_at 新→旧）；chatId 缺省时列全部（任务面板的全局视图）。 */
+    listTasks(chatId?: string, limit?: number): TaskRecord[];
+    /**
+     * 终态/进度回写。只写传入的字段（undefined 过滤），updated_at 总是刷新。
+     * 与 updateChat 同约定：显式传 null 才是置空。
+     */
+    updateTask(taskId: string, updates: Partial<Pick<TaskRecord, 'status' | 'answer' | 'error' | 'worktreeState' | 'traceId' | 'recordId'>>): TaskRecord | null;
+    /**
+     * 回写推理时间线。故意不碰 updated_at——流过程中的增量不应把任务
+     * 面板按「最近活动」反复顶到最上。
+     */
+    saveTaskProcess(taskId: string, processJson: string): void;
+    /**
+     * 启动清扫：running 任务只可能属于上一个已死的进程（任务流不跨进程
+     * 存活），全部落成 failed/interrupted——与 W7-1 turn_active 检测器同
+     * 理，残留 running 是崩溃签名，不是真相。
+     */
+    failRunningTasks(reason: string): number;
+    /**
+     * 记录一条用量事件(一轮 chat / 一次标题生成 / 一次摘要压缩等)。
+     * `costUsd` 为 null 表示该模型无单价(本地/未知)——存 NULL,面板渲染为 "—"。
+     */
+    recordUsageEvent(input: {
+        chatId?: string | null;
+        kind: string;
+        provider?: string | null;
+        model?: string | null;
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedPromptTokens?: number;
+        costUsd?: number | null;
+    }): void;
+    /**
+     * 聚合最近 `sinceDays` 天的用量:按 model 分桶( token 合计 + 成本合计),
+     * 外加总计。成本只统计有单价的模型(cost_usd 非 NULL);无单价模型的
+     * token 照常计入,但成本列不计。返回按 totalTokens 降序。
+     */
+    getUsageSummary(sinceDays?: number): UsageSummary;
+    getLlmSettings(): LlmSettings | null;
+    setLlmSettings(settings: LlmSettings): 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;
+    listInsightOutbox(opts?: {
+        uploaded?: boolean;
+        kind?: InsightKind;
+        limit?: number;
+    }): InsightOutboxRow[];
+    markInsightUploaded(id: string): void;
+    markInsightUploadError(id: string, error: string): void;
+    insightStats(): {
+        events: number;
+        turns: number;
+        profile: number;
+        pending: number;
+    };
+    exportInsightsBundle(): {
+        schema: typeof INSIGHTS_EXPORT_SCHEMA;
+        exportedAt: string;
+        installId: string;
+        settings: {
+            shareBehavior: boolean;
+            shareConversation: boolean;
+            shareProfile: boolean;
+        };
+        profile: InsightsProfile;
+        stats: {
+            events: number;
+            turns: number;
+            profile: number;
+            pending: number;
+        };
+        records: InsightOutboxRow[];
+    };
+    private mapInsightOutbox;
+    private mapChatSession;
+    private mapChatMessage;
+    private mapHarnessTrace;
+    private mapTask;
+    private mapChatAgent;
+    private safeJson;
+}
+export declare const localStore: LocalStore;