@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.1

package/dist/storage/NoticeRepository.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `notices` 表仓储：通知持久化（PRD L3：手动清 + 持久化）。
+ *
+ * 库里存的是**码 + 参数**而不是渲染好的句子：多语言在读出时按连接的语言渲染
+ * （architecture.md §6），否则一条通知存死一种语言，换个语言连回来就错了。
+ *
+ * `durationMs` 为 null 表示永久存在；有值时到点消失，靠 `deleteExpired` 清掉。
+ *
+ * `conversationId` 是「这条通知与哪段对话有关」的真值列（可空 = 全域通知），
+ * 按对话过滤与按对话清除都走它。
+ */
+import type { Database } from "./Database.js";
+import type { Notice, NoticeCreateInput } from "./types.js";
+export declare class NoticeRepository {
+    private readonly db;
+    constructor(db: Database);
+    create(input: NoticeCreateInput): Promise<void>;
+    get(id: string): Promise<Notice | undefined>;
+    /**
+     * 仍然该显示的通知：永久的（`durationMs IS NULL`）加上还没到点的。
+     * 已到点但还没被 `deleteExpired` 扫掉的，这里也不返回，免得读到已过期的通知。
+     */
+    listActive(now: number): Promise<Notice[]>;
+    /** 手动清除一条（PRD L3：永久通知只能这样消失） */
+    clear(id: string): Promise<number>;
+    clearAll(): Promise<number>;
+    /** 清掉挂在一段对话上的通知（`notice.clear({ conversationId })` 的读写路径） */
+    clearByConversation(conversationId: string): Promise<number>;
+    /** 清掉已经到点的通知，返回清掉的条数 */
+    deleteExpired(now: number): Promise<number>;
+}

package/dist/storage/NoticeRepository.js

@@ -0,0 +1,89 @@
+/**
+ * `notices` 表仓储：通知持久化（PRD L3：手动清 + 持久化）。
+ *
+ * 库里存的是**码 + 参数**而不是渲染好的句子：多语言在读出时按连接的语言渲染
+ * （architecture.md §6），否则一条通知存死一种语言，换个语言连回来就错了。
+ *
+ * `durationMs` 为 null 表示永久存在；有值时到点消失，靠 `deleteExpired` 清掉。
+ *
+ * `conversationId` 是「这条通知与哪段对话有关」的真值列（可空 = 全域通知），
+ * 按对话过滤与按对话清除都走它。
+ */
+const COLUMNS = "id, level, code, params, durationMs, conversationId, createdAt";
+function parseParams(value) {
+    if (value === null)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function toNotice(row) {
+    return {
+        id: row.id,
+        level: row.level,
+        code: row.code,
+        params: parseParams(row.params),
+        durationMs: row.durationMs,
+        conversationId: row.conversationId,
+        createdAt: row.createdAt,
+    };
+}
+export class NoticeRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async create(input) {
+        await this.db.run(`INSERT INTO notices (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+            input.id,
+            input.level,
+            input.code,
+            input.params === undefined || input.params === null ? null : JSON.stringify(input.params),
+            input.durationMs ?? null,
+            input.conversationId ?? null,
+            input.createdAt,
+        ]);
+    }
+    async get(id) {
+        const row = await this.db.get(`SELECT ${COLUMNS} FROM notices WHERE id = ?`, [id]);
+        return row ? toNotice(row) : undefined;
+    }
+    /**
+     * 仍然该显示的通知：永久的（`durationMs IS NULL`）加上还没到点的。
+     * 已到点但还没被 `deleteExpired` 扫掉的，这里也不返回，免得读到已过期的通知。
+     */
+    async listActive(now) {
+        const rows = await this.db.all(`SELECT ${COLUMNS} FROM notices
+       WHERE durationMs IS NULL OR createdAt + durationMs > ?
+       ORDER BY createdAt ASC, id ASC`, [now]);
+        return rows.map(toNotice);
+    }
+    /** 手动清除一条（PRD L3：永久通知只能这样消失） */
+    async clear(id) {
+        const result = await this.db.run("DELETE FROM notices WHERE id = ?", [id]);
+        return result.changes;
+    }
+    async clearAll() {
+        const result = await this.db.run("DELETE FROM notices");
+        return result.changes;
+    }
+    /** 清掉挂在一段对话上的通知（`notice.clear({ conversationId })` 的读写路径） */
+    async clearByConversation(conversationId) {
+        const result = await this.db.run("DELETE FROM notices WHERE conversationId = ?", [
+            conversationId,
+        ]);
+        return result.changes;
+    }
+    /** 清掉已经到点的通知，返回清掉的条数 */
+    async deleteExpired(now) {
+        const result = await this.db.run("DELETE FROM notices WHERE durationMs IS NOT NULL AND createdAt + durationMs <= ?", [now]);
+        return result.changes;
+    }
+}

package/dist/storage/QuestionRepository.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `questions` 表仓储：问题对象的持久化（PRD D22：有状态、有生命周期、多端看同一个）。
+ *
+ * 状态机取值（`state`）与问题种类的具体含义属于上层（QuestionCenter 那一层），存储层
+ * 只按调用方给的字符串存取，不解释它、也不替它做转移。
+ */
+import type { Database } from "./Database.js";
+import type { Question, QuestionCreateInput } from "./types.js";
+/** 要更新的字段；只给想改的那几项 */
+export interface QuestionPatch {
+    state?: string;
+    /** 回答内容（会被 JSON 序列化）；显式传 `null` 表示清空 */
+    answer?: unknown;
+    answeredAt?: number | null;
+    updatedAt: number;
+}
+export declare class QuestionRepository {
+    private readonly db;
+    constructor(db: Database);
+    create(input: QuestionCreateInput): Promise<void>;
+    get(id: string): Promise<Question | undefined>;
+    /** 某段对话下的问题，按创建时间升序；给了 `state` 就只取这个状态 */
+    listByConversation(conversationId: string, state?: string): Promise<Question[]>;
+    /**
+     * 全库的问题，按创建时间升序（R61：`question.list` 不要求给对话）。
+     */
+    listAll(state?: string): Promise<Question[]>;
+    /**
+     * 更新状态 / 回答。只拼出真正要改的列，没给的列保持不变
+     * （例如只改 state 时不会把已有的 answer 抹掉）。
+     */
+    update(id: string, patch: QuestionPatch): Promise<number>;
+    delete(id: string): Promise<number>;
+}

package/dist/storage/QuestionRepository.js

@@ -0,0 +1,96 @@
+/**
+ * `questions` 表仓储：问题对象的持久化（PRD D22：有状态、有生命周期、多端看同一个）。
+ *
+ * 状态机取值（`state`）与问题种类的具体含义属于上层（QuestionCenter 那一层），存储层
+ * 只按调用方给的字符串存取，不解释它、也不替它做转移。
+ */
+const COLUMNS = "id, conversationId, kind, payload, state, answer, createdAt, updatedAt, answeredAt";
+function parseJson(value) {
+    if (value === null)
+        return null;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function toQuestion(row) {
+    return {
+        id: row.id,
+        conversationId: row.conversationId,
+        kind: row.kind,
+        payload: parseJson(row.payload),
+        state: row.state,
+        answer: parseJson(row.answer),
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+        answeredAt: row.answeredAt,
+    };
+}
+export class QuestionRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async create(input) {
+        await this.db.run(`INSERT INTO questions (${COLUMNS}) VALUES (?, ?, ?, ?, ?, NULL, ?, ?, NULL)`, [
+            input.id,
+            input.conversationId,
+            input.kind,
+            JSON.stringify(input.payload ?? null),
+            input.state,
+            input.createdAt,
+            input.createdAt,
+        ]);
+    }
+    async get(id) {
+        const row = await this.db.get(`SELECT ${COLUMNS} FROM questions WHERE id = ?`, [id]);
+        return row ? toQuestion(row) : undefined;
+    }
+    /** 某段对话下的问题，按创建时间升序；给了 `state` 就只取这个状态 */
+    async listByConversation(conversationId, state) {
+        const rows = state === undefined
+            ? await this.db.all(`SELECT ${COLUMNS} FROM questions WHERE conversationId = ? ORDER BY createdAt ASC, id ASC`, [conversationId])
+            : await this.db.all(`SELECT ${COLUMNS} FROM questions
+             WHERE conversationId = ? AND state = ?
+             ORDER BY createdAt ASC, id ASC`, [conversationId, state]);
+        return rows.map(toQuestion);
+    }
+    /**
+     * 全库的问题，按创建时间升序（R61：`question.list` 不要求给对话）。
+     */
+    async listAll(state) {
+        const rows = state === undefined
+            ? await this.db.all(`SELECT ${COLUMNS} FROM questions ORDER BY createdAt ASC, id ASC`)
+            : await this.db.all(`SELECT ${COLUMNS} FROM questions WHERE state = ? ORDER BY createdAt ASC, id ASC`, [state]);
+        return rows.map(toQuestion);
+    }
+    /**
+     * 更新状态 / 回答。只拼出真正要改的列，没给的列保持不变
+     * （例如只改 state 时不会把已有的 answer 抹掉）。
+     */
+    async update(id, patch) {
+        const assignments = ["updatedAt = ?"];
+        const params = [patch.updatedAt];
+        if (patch.state !== undefined) {
+            assignments.push("state = ?");
+            params.push(patch.state);
+        }
+        if ("answer" in patch) {
+            assignments.push("answer = ?");
+            params.push(patch.answer === undefined ? null : JSON.stringify(patch.answer));
+        }
+        if (patch.answeredAt !== undefined) {
+            assignments.push("answeredAt = ?");
+            params.push(patch.answeredAt);
+        }
+        params.push(id);
+        const result = await this.db.run(`UPDATE questions SET ${assignments.join(", ")} WHERE id = ?`, params);
+        return result.changes;
+    }
+    async delete(id) {
+        const result = await this.db.run("DELETE FROM questions WHERE id = ?", [id]);
+        return result.changes;
+    }
+}

package/dist/storage/WorkspaceRepository.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `workspaces` 表仓储：只做 SQL，不含业务判断。
+ *
+ * 一个 Workspace 对应一个工作目录，`cwd` 创建后不可变（PRD D9：搬家＝新 Workspace），
+ * 所以这里没有改 cwd 的方法 —— 想改只能建新的。
+ */
+import type { Database } from "./Database.js";
+import type { WorkspaceCreateInput, WorkspaceRow } from "./types.js";
+export declare class WorkspaceRepository {
+    private readonly db;
+    constructor(db: Database);
+    create(input: WorkspaceCreateInput): Promise<void>;
+    get(id: string): Promise<WorkspaceRow | undefined>;
+    /** 按 cwd 找登记过的 Workspace（PRD D10：普通对话遇到未登记的 cwd 时问一次） */
+    getByCwd(cwd: string): Promise<WorkspaceRow | undefined>;
+    /** 全部 Workspace，新建的排前面 */
+    list(): Promise<WorkspaceRow[]>;
+    rename(id: string, name: string): Promise<number>;
+    /**
+     * 删 Workspace：它名下的 conversations / messages / assets / questions 靠外键级联清掉
+     * （PRD D11：删项目连带删它名下的对话）。目录本身不在存储层职能范围内。
+     */
+    delete(id: string): Promise<number>;
+    count(): Promise<number>;
+}

package/dist/storage/WorkspaceRepository.js

@@ -0,0 +1,44 @@
+/**
+ * `workspaces` 表仓储：只做 SQL，不含业务判断。
+ *
+ * 一个 Workspace 对应一个工作目录，`cwd` 创建后不可变（PRD D9：搬家＝新 Workspace），
+ * 所以这里没有改 cwd 的方法 —— 想改只能建新的。
+ */
+const COLUMNS = "id, name, cwd, createdAt";
+export class WorkspaceRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async create(input) {
+        // cwd 在表上唯一：同一个目录重复登记会在这里直接报 UNIQUE 约束错误
+        await this.db.run(`INSERT INTO workspaces (${COLUMNS}) VALUES (?, ?, ?, ?)`, [input.id, input.name, input.cwd, input.createdAt]);
+    }
+    async get(id) {
+        return this.db.get(`SELECT ${COLUMNS} FROM workspaces WHERE id = ?`, [id]);
+    }
+    /** 按 cwd 找登记过的 Workspace（PRD D10：普通对话遇到未登记的 cwd 时问一次） */
+    async getByCwd(cwd) {
+        return this.db.get(`SELECT ${COLUMNS} FROM workspaces WHERE cwd = ?`, [cwd]);
+    }
+    /** 全部 Workspace，新建的排前面 */
+    async list() {
+        return this.db.all(`SELECT ${COLUMNS} FROM workspaces ORDER BY createdAt DESC, id DESC`);
+    }
+    async rename(id, name) {
+        const result = await this.db.run("UPDATE workspaces SET name = ? WHERE id = ?", [name, id]);
+        return result.changes;
+    }
+    /**
+     * 删 Workspace：它名下的 conversations / messages / assets / questions 靠外键级联清掉
+     * （PRD D11：删项目连带删它名下的对话）。目录本身不在存储层职能范围内。
+     */
+    async delete(id) {
+        const result = await this.db.run("DELETE FROM workspaces WHERE id = ?", [id]);
+        return result.changes;
+    }
+    async count() {
+        const row = await this.db.get("SELECT count(*) AS n FROM workspaces");
+        return row?.n ?? 0;
+    }
+}

package/dist/storage/dbWorker.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SQLite worker 线程：`node:sqlite` 只提供同步 API（`DatabaseSync`），在主线程上执行会
+ * 直接卡住事件循环（宿主要和多个 WebSocket 连接同时打交道，卡一次就是全体卡住），
+ * 所以数据库句柄整个住在 worker 里，主线程只发消息、按 id 收结果。
+ *
+ * 这里刻意只 import Node 内置模块、不 import 任何同目录文件：
+ * worker 是以自己的模块图独立启动的，依赖越少启动越快、也不会踩到「源码是 .ts / 产物是
+ * .js」这种路径差异。
+ */
+export {};

package/dist/storage/dbWorker.js

@@ -0,0 +1,132 @@
+/**
+ * SQLite worker 线程：`node:sqlite` 只提供同步 API（`DatabaseSync`），在主线程上执行会
+ * 直接卡住事件循环（宿主要和多个 WebSocket 连接同时打交道，卡一次就是全体卡住），
+ * 所以数据库句柄整个住在 worker 里，主线程只发消息、按 id 收结果。
+ *
+ * 这里刻意只 import Node 内置模块、不 import 任何同目录文件：
+ * worker 是以自己的模块图独立启动的，依赖越少启动越快、也不会踩到「源码是 .ts / 产物是
+ * .js」这种路径差异。
+ */
+import { parentPort, workerData } from "node:worker_threads";
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+const port = parentPort;
+if (!port)
+    throw new Error("dbWorker 只能由 worker_threads 启动");
+const { dbPath } = workerData;
+// 数据库文件所在目录可能还不存在（首次启动、测试用临时目录），开库前先补上
+if (dbPath !== ":memory:")
+    mkdirSync(dirname(dbPath), { recursive: true });
+const sqlite = new DatabaseSync(dbPath);
+// WAL：读不被写阻塞、写不被读阻塞，崩溃后也更容易恢复。
+// 读回来的模式必须真的是 "wal" —— 文件系统不支持时（网络盘、只读目录等）会静默留在
+// delete 模式，那种情况下并发读写会互相卡住，与其带病运行不如让启动直接失败。
+const journal = sqlite.prepare("PRAGMA journal_mode = WAL").get();
+if (journal?.journal_mode !== "wal") {
+    throw new Error(`无法切换到 WAL 日志模式（当前为 ${String(journal?.journal_mode)}），数据库路径：${dbPath}`);
+}
+// 外键约束在 SQLite 里默认是关的，必须显式打开，级联删除才会生效
+sqlite.exec("PRAGMA foreign_keys = ON");
+const foreignKeys = sqlite.prepare("PRAGMA foreign_keys").get();
+if (foreignKeys?.foreign_keys !== 1) {
+    throw new Error("无法开启 foreign_keys，级联删除不会生效");
+}
+/**
+ * 语句缓存：SQL 全部来自仓储里的固定语句，种类有限，缓存下来省掉热路径上重复编译。
+ * 若某次迁移改动了表结构，SQLite 会在下次执行时自动重新编译，不需要手动失效。
+ */
+const statementCache = new Map();
+function prepare(sql) {
+    const cached = statementCache.get(sql);
+    if (cached)
+        return cached;
+    const compiled = sqlite.prepare(sql);
+    statementCache.set(sql, compiled);
+    return compiled;
+}
+/** 执行一条写语句；`changes` / `lastInsertRowid` 统一转成 number，保证能结构化克隆 */
+function runStatement(sql, params) {
+    const result = prepare(sql).run(...params);
+    return {
+        changes: Number(result.changes),
+        lastInsertRowid: Number(result.lastInsertRowid),
+    };
+}
+/** 按语句自己声明的种类执行：读的回行，写的回 `changes` / `lastInsertRowid` */
+function executeStatement(statement) {
+    switch (statement.kind) {
+        case "all":
+            return prepare(statement.sql).all(...statement.params);
+        case "get":
+            return prepare(statement.sql).get(...statement.params);
+        case "run":
+            return runStatement(statement.sql, statement.params);
+    }
+}
+/**
+ * 一次消息内串行执行一批语句：`BEGIN IMMEDIATE` 先拿写锁，中途任何一条失败就整批
+ * ROLLBACK。主线程的 `Database.tx` 就是靠这个保证「要么全成、要么全不成」，也是它能让
+ * 回调里「先读再写」而不拆成两次往返的原因（读与写在同一个事务、同一条消息里跑完）。
+ */
+function runBatch(statements) {
+    sqlite.exec("BEGIN IMMEDIATE");
+    try {
+        const results = statements.map((statement) => executeStatement(statement));
+        sqlite.exec("COMMIT");
+        return results;
+    }
+    catch (error) {
+        try {
+            sqlite.exec("ROLLBACK");
+        }
+        catch {
+            // 部分错误（如死锁/中断）下 SQLite 已经自己回滚了，这里的再次回滚失败可以忽略
+        }
+        throw error;
+    }
+}
+function describeError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+port.on("message", (request) => {
+    try {
+        switch (request.kind) {
+            case "all": {
+                const rows = prepare(request.sql).all(...request.params);
+                port.postMessage({ id: request.id, ok: true, result: rows });
+                break;
+            }
+            case "get": {
+                const row = prepare(request.sql).get(...request.params);
+                port.postMessage({ id: request.id, ok: true, result: row });
+                break;
+            }
+            case "run": {
+                port.postMessage({
+                    id: request.id,
+                    ok: true,
+                    result: runStatement(request.sql, request.params),
+                });
+                break;
+            }
+            case "batch": {
+                port.postMessage({ id: request.id, ok: true, result: runBatch(request.statements) });
+                break;
+            }
+            case "close": {
+                // 先回执再收尾：主线程拿到回执就知道挂起表可以释放了
+                port.postMessage({ id: request.id, ok: true });
+                statementCache.clear();
+                sqlite.close();
+                port.close();
+                break;
+            }
+        }
+    }
+    catch (error) {
+        port.postMessage({ id: request.id, ok: false, error: describeError(error) });
+    }
+});

package/dist/storage/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 存储层出口：`Database`（worker 里的 node:sqlite）+ 迁移 + 一表一仓储。
+ *
+ * 这里不导出任何单例：`Database` 由单根（`app.ts`）创建后注入给各仓储与服务，
+ * 谁创建谁负责 `close()`。这样做的好处是测试与多实例可以各开各的库，互不影响。
+ */
+export { Database } from "./Database.js";
+export type { RunResult, TxClient, TxKind, TxOutcome, TxPlan, TxStatement, TxValue, } from "./Database.js";
+export { migrate, MIGRATIONS } from "./migrations.js";
+export type { Migration } from "./migrations.js";
+export { MetaRepository } from "./MetaRepository.js";
+export { WorkspaceRepository } from "./WorkspaceRepository.js";
+export { ConversationRepository } from "./ConversationRepository.js";
+export { MessageRepository } from "./MessageRepository.js";
+export { AssetRepository } from "./AssetRepository.js";
+export { NoticeRepository } from "./NoticeRepository.js";
+export { QuestionRepository } from "./QuestionRepository.js";
+export { CredentialRepository, hashCredential } from "./CredentialRepository.js";
+export type { QuestionPatch } from "./QuestionRepository.js";
+export type * from "./types.js";

package/dist/storage/index.js

@@ -0,0 +1,16 @@
+/**
+ * 存储层出口：`Database`（worker 里的 node:sqlite）+ 迁移 + 一表一仓储。
+ *
+ * 这里不导出任何单例：`Database` 由单根（`app.ts`）创建后注入给各仓储与服务，
+ * 谁创建谁负责 `close()`。这样做的好处是测试与多实例可以各开各的库，互不影响。
+ */
+export { Database } from "./Database.js";
+export { migrate, MIGRATIONS } from "./migrations.js";
+export { MetaRepository } from "./MetaRepository.js";
+export { WorkspaceRepository } from "./WorkspaceRepository.js";
+export { ConversationRepository } from "./ConversationRepository.js";
+export { MessageRepository } from "./MessageRepository.js";
+export { AssetRepository } from "./AssetRepository.js";
+export { NoticeRepository } from "./NoticeRepository.js";
+export { QuestionRepository } from "./QuestionRepository.js";
+export { CredentialRepository, hashCredential } from "./CredentialRepository.js";

package/dist/storage/migrations.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 建表与迁移。
+ *
+ * `meta.schemaVersion` 是唯一的版本真相：`migrate` 从当前版本往上逐级执行，
+ * 每一级的所有语句 + 版本号推进都在**同一个事务**里 —— 结构改了一半而版本号没动，
+ * 或者版本号动了而结构没改，都会让下次启动跑在错误的假设上。
+ *
+ * 不识别任何旧数据、不做数据搬迁（PRD L1：新库从空开始）。
+ */
+import type { Database } from "./Database.js";
+export interface Migration {
+    /** 目标版本号：跑完这一级后 `meta.schemaVersion` 即为此值 */
+    version: number;
+    /** 这一级要执行的语句，按顺序在同一事务内执行 */
+    statements: string[];
+}
+/**
+ * 迁移列表。眼下只有 v1：这套表结构还没随版本发出去，PM 在 W1 之后的裁定（cwd 唯一、
+ * 身份列非空）直接落进了 v1 的建表语句。再往后改结构时追加新条目 —— 已经装上升过级的库
+ * 不会重跑旧条目，改旧条目会让两台机器的表结构悄悄分叉。
+ */
+export declare const MIGRATIONS: Migration[];
+/**
+ * 把库升到最新版本。重复调用是幂等的：已经跑过的版本会跳过，不会再执行一遍语句。
+ */
+export declare function migrate(db: Database): Promise<void>;