@rei-standard/amsg-server 2.6.0-next.2 → 2.6.0-next.21

package/dist/adapters/interface.d.ts

@@ -0,0 +1,306 @@
+export type TaskRow = {
+    id: number;
+    user_id: string;
+    uuid: string;
+    encrypted_payload: string;
+    message_type: string;
+    next_send_at: string;
+    status: string;
+    retry_count: number;
+    created_at?: string;
+    updated_at?: string;
+    /**
+     * 退避时刻。投递链路读的行（getPendingTasks / getTaskByUuidOnly）必须带上
+     * 它，读接口返回的行（getTaskByUuid / listTasks）不带。
+     */
+    retry_after?: string | null;
+    /**
+     * 上一次投递失败的脱敏摘要（JSON 串）。读接口返回的行才带。
+     *
+     * 两条链路各要一套列，内置适配器统一从 adapters/schema.js 的
+     * `TASK_DELIVERY_COLUMNS` / `TASK_DETAIL_COLUMNS` 取，三种方言共用一份。
+     */
+    last_error?: string | null;
+};
+export type InsertTaskParams = {
+    user_id: string;
+    uuid: string;
+    encrypted_payload: string;
+    next_send_at: string;
+    message_type: string;
+};
+export type InitSchemaResult = {
+    columnsCreated: number;
+    indexesCreated: number;
+    indexesFailed: number;
+    columns: any[];
+    indexes: any[];
+};
+export type DbAdapter = {
+    /**
+     *   Create the scheduled_messages table and all indexes.
+     */
+    initSchema: () => Promise<InitSchemaResult>;
+    /**
+     * （可选）活库里现在实际有哪些表 / 列 / 索引，只读不写。
+     * `getSchemaVersion` / `ensureSchema`（lib/schema-version.js）拿它跟这一版
+     * 需要的清单对照；不实现的适配器调那两个函数会抛错。内置只有 D1 实现。
+     */
+    describeSchema?: () => Promise<{
+        tables: Record<string, string[]>;
+        indexes: string[];
+    }>;
+    /**
+     *   Drop the scheduled_messages table (CASCADE).
+     */
+    dropSchema: () => Promise<void>;
+    /**
+     *   Insert a new task row and return the created record.
+     */
+    createTask: (params: InsertTaskParams) => Promise<TaskRow>;
+    /**
+     *   Fetch a single pending task by uuid + user_id.
+     */
+    getTaskByUuid: (uuid: string, userId: string) => Promise<TaskRow | null>;
+    /**
+     *   Fetch a single pending task by uuid only (used by instant processing).
+     *   返回的行要和 `getPendingTasks` 是同一套列（`TASK_DELIVERY_COLUMNS`）：
+     *   `runTask` 拿这一行走同一条投递链，少了 `retry_after`，退避守卫读到的永远
+     *   是 undefined，还在等重试的任务会被当场再跑一遍。
+     */
+    getTaskByUuidOnly: (uuid: string) => Promise<TaskRow | null>;
+    /**
+     * （可选）这条 uuid 现在是什么状态——不限用户，也不限状态。`runTask` 用它
+     * 把「这条已经跑完进终态了」和「压根没这条」分开回报；不实现时两种都归
+     * `not_found`。
+     */
+    getTaskStatusByUuidOnly?: (uuid: string) => Promise<{
+        status: string;
+    } | null>;
+    /**
+     *   Partially update a task row by its numeric id.
+     *   实现了 `claimTask` 的适配器还要认 `lease_until` 和 `retry_after`（含写
+     *   null）：投递收尾时 runScheduledTick 用前者把租约放掉，用后者写/清投递失败
+     *   的退避时刻。
+     */
+    updateTaskById: (taskId: number, updates: any) => Promise<TaskRow | null>;
+    /**
+     *   Update a pending task's encrypted_payload (and optional index fields) by uuid + user_id.
+     */
+    updateTaskByUuid: (uuid: string, userId: string, encryptedPayload: string, extraFields?: any) => Promise<TaskRow | null>;
+    /**
+     *   Delete a task by numeric id. Returns true if a row was affected.
+     */
+    deleteTaskById: (taskId: number) => Promise<boolean>;
+    /**
+     *   Delete a task by uuid + user_id. Returns true if a row was affected.
+     */
+    deleteTaskByUuid: (uuid: string, userId: string) => Promise<boolean>;
+    /**
+     *   Fetch pending tasks whose next_send_at <= NOW(), ordered ASC.
+     *   跳过两种还不该动的行：租约没到期的（`lease_until`，有人正在跑）、退避没到
+     *   点的（`retry_after`，上次投递失败在等重试）。两列都是空或已过期才算待发。
+     */
+    getPendingTasks: (limit?: number) => Promise<TaskRow[]>;
+    /**
+     * 领取一条到点的任务，返回是否领到。cron 每分钟一跳而一次投递可能跑几分
+     * 钟，runScheduledTick 靠它保证同一行同时只被一个 tick 跑。
+     * 三个条件同时成立才领得走：行仍是 pending；`lease_until` 为空或已过期
+     * （没别人正在跑）；`next_send_at` 还等于 `expectedNextSendAt`（读这行时
+     * 拿到的值，用户中途改了排期就不发了）。领到就把 `lease_until` 写成
+     * `leaseUntil`，`next_send_at` 不动。
+     * 传了非空 `serializeGroup` 时还多一个条件：同一分组里没有别的行拿着未到期
+     * 的租约（同一分组同时只跑一条，`runScheduledTick` 的 `serializeBy` 用）。
+     * 领到时把这个值写进 `serialize_group` 列。判定和占位必须在同一条语句里，
+     * 「先查再占」中间的空档会让两个 tick 同时进同一个分组。
+     * 自定义适配器可以不实现（runScheduledTick 会退回不占位的行为，代价是慢
+     * 任务可能被下一跳重复触发）；实现了但忽略第四个参数的，分组串行退化成只在
+     * 同一跳内生效。
+     */
+    claimTask?: (taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date, serializeGroup?: string | null) => Promise<boolean>;
+    /**
+     *   List tasks for a user with optional filters and pagination.
+     */
+    listTasks: (userId: string, opts: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        tasks: TaskRow[];
+        total: number;
+    }>;
+    /**
+     *   Delete completed / failed tasks older than `days` (default 7).
+     */
+    cleanupOldTasks: (days?: number) => Promise<number>;
+    /**
+     *   Return the status string of a task (used to distinguish 404 from 409).
+     */
+    getTaskStatus: (uuid: string, userId: string) => Promise<string | null>;
+    /**
+     * (optional; single-user/D1 only) Batch upsert of client state, last-write-wins on updatedAt.
+     * `cleanups` 先于 upsert 在同一事务里删旧行，两种形态：带 `keyPrefix` 的按 key 前缀删（清理大值
+     * 旧写入留下的切片行，见 lib/state-chunks.js），带 `key` 的删这一个 key（删整条状态；前缀会连带
+     * 删掉同前缀的兄弟 key）。两种都只删 `updated_at <= updatedAt` 的行。自定义 adapter 忽略前缀形态
+     * 只损失存储卫生；忽略精确 key 形态则删不掉状态，`ctx.writeState()` 的删除会失效。
+     * `outcomes` 逐条报告 entries[i] 是否真的写入（缺席时调用方按物理行计数兜底）。
+     */
+    upsertClientState?: (userId: string, entries: Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updatedAt: number;
+    }>, cleanups?: Array<{
+        namespace: string;
+        key?: string;
+        keyPrefix?: string;
+        updatedAt: number;
+    }>) => Promise<{
+        upserted: number;
+        skipped: number;
+        outcomes?: boolean[];
+    }>;
+    /**
+     * (optional; single-user/D1 only) All entries of one namespace; values still encrypted.
+     */
+    getClientState?: (userId: string, namespace: string) => Promise<Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updated_at: number;
+    }>>;
+    /**
+     * (optional; single-user/D1 only) Delete every entry of this user; returns rows deleted.
+     */
+    clearClientState?: (userId: string) => Promise<number>;
+    /**
+     * （可选；单用户/D1）按命名空间清掉 `updated_at` 早于 `updatedBefore`（epoch 毫秒）
+     * 的行，不限用户。宿主配了 `clientStateTtl` 时 runScheduledTick 每跳顺手调；
+     * 指令由 lib/client-state-store.js 的 `planClientStateCleanup` 算好（含大值切片
+     * 所在的保留命名空间）。不实现 → 不清理，与不配 TTL 时行为一致。
+     */
+    cleanupClientState?: (targets: Array<{
+        namespace: string;
+        updatedBefore: number;
+    }>) => Promise<number>;
+    /**
+     * 这个用户当前登记的 Web Push 订阅（`subscription` 是密文，解密在上层）。没有登记过 → null。
+     * 一个用户一份：任务行不携带订阅，到点投递时读这里。
+     */
+    getPushSubscription?: (userId: string) => Promise<{
+        subscription: string;
+        updated_at: number;
+    } | null>;
+    /**
+     * 覆盖写这个用户的订阅（`updatedAt` 是 epoch 毫秒）。没有 last-write-wins 比较——
+     * 客户端拿到的新订阅永远比旧的有效，旧的那份只会 410。
+     */
+    upsertPushSubscription?: (userId: string, encryptedSubscription: string, updatedAt: number) => Promise<boolean>;
+    /**
+     * 删掉这个用户的订阅；返回是否真的删掉了一行。
+     *
+     * 上面三个方法要么都实现、要么都不实现：缺任何一个，`PUT/GET/DELETE
+     * /push-subscription` 返回 501，`POST /schedule-message` 也会拒绝建任务
+     * （建了也永远发不出去）。内置的 D1 / pg / neon 适配器都实现了。
+     */
+    deletePushSubscription?: (userId: string) => Promise<boolean>;
+    /**
+     * 批量覆盖写这个用户的 LLM 凭据（`encryptedValue` 是密文，加密在上层）。
+     * 已存在的行覆盖 encrypted_value 并刷 updated_at。返回实际写入/覆盖的行数。
+     */
+    upsertLlmCredentials?: (userId: string, entries: Array<{
+        credId: string;
+        encryptedValue: string;
+    }>) => Promise<number>;
+    /**
+     * 按 cred_id 批量读凭据行（密文原样返回）。排程时的存在性检查和 fire 时的
+     * 解析共用这一个口。
+     */
+    getLlmCredentials?: (userId: string, credIds: string[]) => Promise<Array<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at，密文不出这个
+     * 方法）。按 cred_id 排序。
+     */
+    listLlmCredentials?: (userId: string) => Promise<Array<{
+        cred_id: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 删凭据：数组删指定那几行，null 删全部。返回删掉的行数。
+     *
+     * llm_credentials 四个方法要么都实现、要么都不实现：缺任何一个，
+     * `PUT/GET/DELETE /llm-credentials` 返回 501，带 `credRefs` 的
+     * `POST /schedule-message` 也会被拒。内置的 D1 / pg / neon 适配器都实现了。
+     */
+    deleteLlmCredentials?: (userId: string, credIds: string[] | null) => Promise<number>;
+    /**
+     * （可选）投递期间的租约续期（runScheduledTick 的心跳）。只在行仍是
+     * pending 且 lease_until 非空时生效——收尾放掉租约之后，迟到的心跳不会把
+     * 它复活。不实现 → 心跳自动关闭，退回一次性长租约（claimLeaseMs）。
+     *
+     * 返回值现在还是「这条任务是不是被取消/顶替了」的信号：明确返回 `false`
+     * 会中止这次投递剩下的推送（行已经不在了，再发就是「取消接口回了成功，
+     * 消息照样送达」）。所以匹配不到行时必须返回 `false`，不能返回 undefined
+     * ——什么都不返回等于关掉这条信号，取消撞上投递时又会照发。抛错不算行没
+     * 了，只当作这次没续上，下个心跳再试。
+     */
+    renewTaskLease?: (taskId: number, leaseUntil: string | Date) => Promise<boolean>;
+    /**
+     * （可选）状态 + last_error 列（脱敏失败摘要的 JSON 串）。GET /message 用
+     * 它把「为什么失败」透给已失败的行；不实现时退回 getTaskStatus（409 里就
+     * 没有 lastError）。
+     */
+    getTaskStatusInfo?: (uuid: string, userId: string) => Promise<{
+        status: string;
+        last_error: string | null;
+    } | null>;
+    /**
+     * （可选）建新任务的同一事务里取消旧的那条（POST /schedule-message 的
+     * supersedesUuid）。不实现时 handler 退回「先删再建」两步（失去原子性）。
+     */
+    createTaskSuperseding?: (params: InsertTaskParams, supersedesUuid: string) => Promise<TaskRow & {
+        superseded: boolean;
+    }>;
+    /**
+     * （可选；单用户/D1）push 发送前把整批落进 message_outbox（密文 payload），
+     * (user_id, message_id) 冲突时更新未 ack 的行、不动已 ack 的。
+     */
+    appendOutboxMessages?: (userId: string, rows: Array<any>) => Promise<number>;
+    /**
+     * （可选；单用户/D1）把发出去的段标 delivered_at。
+     */
+    markOutboxDelivered?: (userId: string, messageIds: string[], deliveredAt: number) => Promise<number>;
+    /**
+     * （可选；单用户/D1）把还没发出去的行删掉。任务投递到一半被取消 / 顶替时，
+     * 剩下那几条 push 已经落了行却不会再发，不撤掉的话客户端会从 `GET /outbox`
+     * 把它们补收回去。不实现 → 取消只挡住 Web Push 这一路。
+     */
+    discardOutboxMessages?: (userId: string, messageIds: string[]) => Promise<number>;
+    /**
+     * （可选；单用户/D1）未 ack 的行，id 升序游标翻页（GET /outbox）。行上要带
+     * `task_uuid` 和 `delivered_at`：`DELETE /message` 和 supersedesUuid 顶替这两
+     * 条路靠翻这份名单找出该任务名下还没发出去的行（没有按 task_uuid 查的读法），
+     * 缺任一字段就挑不出来，那两条路上的 outbox 清理会静默跳过。
+     */
+    listUnackedOutbox?: (userId: string, sinceId: number, limit: number) => Promise<Array<any>>;
+    /**
+     * （可选；单用户/D1）客户端确认收到（POST /outbox/ack，幂等）。
+     */
+    ackOutboxMessages?: (userId: string, messageIds: string[], ackedAt: number) => Promise<number>;
+    /**
+     * （可选；单用户/D1）outbox 例行清理（runScheduledTick 每跳顺手调）。
+     *
+     * outbox 这几个方法要么都实现、要么都不实现：缺写入侧的（append / mark），
+     * 发送链路静默跳过落行；缺读取侧的（list / ack），`GET /outbox` 与
+     * `POST /outbox/ack` 返回 501；缺 discard（或取消那条路上缺 list），取消只挡
+     * 住 Web Push。内置只有 D1 实现（与 client_state 同待遇）。
+     */
+    cleanupOutbox?: (opts: {
+        ackedBeforeMs?: number;
+        allBeforeMs?: number;
+    }) => Promise<number>;
+};

package/dist/adapters/neon.d.ts

@@ -0,0 +1,88 @@
+export class NeonAdapter {
+    /** @param {string} connectionString */
+    constructor(connectionString: string);
+    /** @private */
+    private _connectionString;
+    /** @private */
+    private _sql;
+    /**
+     * neon() 的 HTTP 驱动：一次查询一个 fetch，两次查询之间不留连接。所以它没有
+     * pg 那种「空闲连接被服务端掐断」的问题——连接层面的错误只会让当次调用的
+     * Promise 失败，落在调用方的 try/catch 里，不会变成进程级未捕获异常。
+     *
+     * @private
+     */
+    private _getSql;
+    initSchema(): Promise<{
+        columnsCreated: number;
+        indexesCreated: number;
+        indexesFailed: number;
+        columns: {
+            table: string;
+            name: any;
+            type: any;
+            nullable: boolean;
+        }[];
+        indexes: ({
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error?: undefined;
+        } | {
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error: any;
+        })[];
+    }>;
+    dropSchema(): Promise<void>;
+    createTask(params: any): Promise<Record<string, any>>;
+    getTaskByUuid(uuid: any, userId: any): Promise<Record<string, any>>;
+    getTaskByUuidOnly(uuid: any): Promise<Record<string, any>>;
+    /**
+     * 这条 uuid 现在是什么状态——不限用户，也不限状态（上面那个只看 pending
+     * 行）。`runTask` 用它把「这条已经跑完了」和「压根没这条」分开回报。
+     *
+     * @param {string} uuid
+     * @returns {Promise<{ status: string }|null>}
+     */
+    getTaskStatusByUuidOnly(uuid: string): Promise<{
+        status: string;
+    } | null>;
+    updateTaskById(taskId: any, updates: any): Promise<Record<string, any>>;
+    updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<Record<string, any>>;
+    deleteTaskById(taskId: any): Promise<boolean>;
+    deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;
+    getPendingTasks(limit?: number): Promise<Record<string, any>[]>;
+    claimTask(taskId: any, expectedNextSendAt: any, leaseUntil: any, serializeGroup?: any): Promise<boolean>;
+    renewTaskLease(taskId: any, leaseUntil: any): Promise<boolean>;
+    listTasks(userId: any, opts?: {}): Promise<{
+        tasks: Record<string, any>[];
+        total: number;
+    }>;
+    cleanupOldTasks(days?: number): Promise<number>;
+    getTaskStatus(uuid: any, userId: any): Promise<any>;
+    getTaskStatusInfo(uuid: any, userId: any): Promise<{
+        status: string;
+        last_error: string | null;
+    }>;
+    getPushSubscription(userId: any): Promise<{
+        subscription: string;
+        updated_at: number;
+    }>;
+    upsertPushSubscription(userId: any, encryptedSubscription: any, updatedAt: any): Promise<boolean>;
+    deletePushSubscription(userId: any): Promise<boolean>;
+    upsertLlmCredentials(userId: any, entries: any): Promise<number>;
+    getLlmCredentials(userId: any, credIds: any): Promise<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }[]>;
+    listLlmCredentials(userId: any): Promise<{
+        cred_id: string;
+        updated_at: string;
+    }[]>;
+    deleteLlmCredentials(userId: any, credIds?: any): Promise<number>;
+}

package/dist/adapters/pg-shared.d.ts

@@ -0,0 +1,161 @@
+/**
+ * pg / neon 共用的 Postgres 查询实现。
+ *
+ * 两个适配器只在「怎么把 SQL 发出去」上不同（pg 的连接池 vs neon 的 HTTP
+ * 驱动），SQL 与并发语义必须逐字一致——各自复制一份的话，修一边漏一边就会让
+ * 两种 Postgres 部署的串行化行为静默分歧，而各自的测试还都是绿的。所以这里
+ * 按执行器参数化：适配器只递一个 `query(text, params) → rows`。
+ *
+ * D1（SQLite 方言、单写者、ISO TEXT 时间戳）不走这份实现。
+ *
+ * @typedef {(text: string, params?: any[]) => Promise<any[]>} PgQuery
+ */
+/**
+ * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
+ * 本次投递期间别的 tick 领不走它。
+ *
+ * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
+ * 任务列表要读它、循环任务推进下一次也要拿它当基准。
+ *
+ * 两个 tick 抢同一行时只有一个改得动，另一个拿不到 RETURNING 行，据此跳
+ * 过。WHERE 里的两个条件各管一件事：
+ *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
+ *     也不会把行焊死，租约到期后自然可以被接手。
+ *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
+ *     这一跳就不该再按旧时刻发。
+ *
+ * 不加一个 'sending' 状态来表达「正在跑」：status 上有 CHECK 约束，加值
+ * 要改表。
+ *
+ * 比 next_send_at 时两边都截到毫秒：列是 timestamptz（微秒精度），驱动读
+ * 出来是 JS Date（毫秒精度），原值送回去可能因为亚毫秒差对不上。
+ *
+ * 带 serializeGroup 时多一道分组门：同一分组里已经有别的行拿着未到期的租
+ * 约，这条就领不走（同一分组同时只跑一条）。判定和写租约在同一条 UPDATE
+ * 里完成——但那只对「抢同一行」成立；READ COMMITTED 下两个并发 tick 各领
+ * 同组的**不同**行时，各自的 NOT EXISTS 子查询都看不到对方尚未提交的租约，
+ * 也没有行锁冲突逼它重查（写偏斜）。所以占位成功后再回头查一次：真撞上了
+ * 就把自己刚写的租约放掉、这一跳不跑——两边都让也没事，行保持 pending，
+ * 下一跳重试。分组门只看租约，不看 `retry_after`：等着重试的任务其实闲着，
+ * 不该把同分组的其他任务一起堵住。
+ *
+ * @param {PgQuery} query
+ * @param {number} taskId
+ * @param {string|Date} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
+ * @param {string|Date} leaseUntil - 租期末尾
+ * @param {string|null} [serializeGroup] - 串行分组标识；空表示不参与分组串行
+ * @returns {Promise<boolean>} true = 领到了；false = 已被别人领走、同分组有
+ *   任务正在跑、排期被改过、或行已不是 pending
+ */
+export function claimTask(query: PgQuery, taskId: number, expectedNextSendAt: string | Date, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
+/**
+ * 投递期间的租约续期（run-tick 的心跳用）。只在行仍是 pending 且确实持有
+ * 租约（lease_until 非空）时生效——收尾把租约放掉之后，迟到的心跳不会把
+ * 租约复活。
+ *
+ * @param {PgQuery} query
+ * @param {number} taskId
+ * @param {string|Date} leaseUntil - 新的租期末尾
+ * @returns {Promise<boolean>} true = 续上了
+ */
+export function renewTaskLease(query: PgQuery, taskId: number, leaseUntil: string | Date): Promise<boolean>;
+/**
+ * 状态 + 失败摘要（GET /message 用它把「为什么失败」透给已失败的行）。
+ *
+ * @param {PgQuery} query
+ * @param {string} uuid
+ * @param {string} userId
+ * @returns {Promise<{ status: string, last_error: string|null }|null>}
+ */
+export function getTaskStatusInfo(query: PgQuery, uuid: string, userId: string): Promise<{
+    status: string;
+    last_error: string | null;
+} | null>;
+/**
+ * 这个用户当前登记的推送订阅（密文原样返回，解密在上层）。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @returns {Promise<{ subscription: string, updated_at: number }|null>}
+ */
+export function getPushSubscription(query: PgQuery, userId: string): Promise<{
+    subscription: string;
+    updated_at: number;
+} | null>;
+/**
+ * 覆盖写这个用户的订阅。一个用户一行，没有 last-write-wins 之类的比较——
+ * 客户端拿到的新订阅永远比旧的有效，旧的那份只会 410。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @param {string} encryptedSubscription
+ * @param {number} updatedAt - epoch 毫秒
+ * @returns {Promise<boolean>}
+ */
+export function upsertPushSubscription(query: PgQuery, userId: string, encryptedSubscription: string, updatedAt: number): Promise<boolean>;
+/**
+ * 删掉这个用户的订阅（设置页「停止接收推送」）。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @returns {Promise<boolean>} true = 确实删掉了一行
+ */
+export function deletePushSubscription(query: PgQuery, userId: string): Promise<boolean>;
+/**
+ * 批量 upsert 这个用户的凭据（value 已是密文，加密在上层）。已存在的行覆盖
+ * encrypted_value 并刷 updated_at，created_at 保留首次写入的时刻。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @param {Array<{ credId: string, encryptedValue: string }>} entries
+ * @param {string} now - ISO8601 时间戳（与 SQLite 侧同口径的 TEXT）
+ * @returns {Promise<number>} 实际写入/覆盖的行数
+ */
+export function upsertLlmCredentials(query: PgQuery, userId: string, entries: Array<{
+    credId: string;
+    encryptedValue: string;
+}>, now: string): Promise<number>;
+/**
+ * 按 cred_id 批量读这个用户的凭据行（密文原样返回，解密在上层）。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @param {string[]} credIds
+ * @returns {Promise<Array<{ cred_id: string, encrypted_value: string, updated_at: string }>>}
+ */
+export function getLlmCredentials(query: PgQuery, userId: string, credIds: string[]): Promise<Array<{
+    cred_id: string;
+    encrypted_value: string;
+    updated_at: string;
+}>>;
+/**
+ * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at）。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @returns {Promise<Array<{ cred_id: string, updated_at: string }>>}
+ */
+export function listLlmCredentials(query: PgQuery, userId: string): Promise<Array<{
+    cred_id: string;
+    updated_at: string;
+}>>;
+/**
+ * 删凭据。`credIds` 传数组删指定那几行；传 null 删这个用户的全部。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @param {string[]|null} credIds
+ * @returns {Promise<number>} 删掉的行数
+ */
+export function deleteLlmCredentials(query: PgQuery, userId: string, credIds?: string[] | null): Promise<number>;
+/**
+ * pg / neon 共用的 Postgres 查询实现。
+ *
+ * 两个适配器只在「怎么把 SQL 发出去」上不同（pg 的连接池 vs neon 的 HTTP
+ * 驱动），SQL 与并发语义必须逐字一致——各自复制一份的话，修一边漏一边就会让
+ * 两种 Postgres 部署的串行化行为静默分歧，而各自的测试还都是绿的。所以这里
+ * 按执行器参数化：适配器只递一个 `query(text, params) → rows`。
+ *
+ * D1（SQLite 方言、单写者、ISO TEXT 时间戳）不走这份实现。
+ */
+export type PgQuery = (text: string, params?: any[]) => Promise<any[]>;

package/dist/adapters/pg.d.ts

@@ -0,0 +1,84 @@
+export class PgAdapter {
+    /** @param {string} connectionString */
+    constructor(connectionString: string);
+    /** @private */
+    private _connectionString;
+    /** @private */
+    private _pool;
+    /** @private */
+    private _getPool;
+    /** @private */
+    private _query;
+    initSchema(): Promise<{
+        columnsCreated: number;
+        indexesCreated: number;
+        indexesFailed: number;
+        columns: {
+            table: string;
+            name: any;
+            type: any;
+            nullable: boolean;
+        }[];
+        indexes: ({
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error?: undefined;
+        } | {
+            name: string;
+            status: string;
+            description: string;
+            critical: boolean;
+            error: any;
+        })[];
+    }>;
+    dropSchema(): Promise<void>;
+    createTask(params: any): Promise<any[]>;
+    getTaskByUuid(uuid: any, userId: any): Promise<any[]>;
+    getTaskByUuidOnly(uuid: any): Promise<any[]>;
+    /**
+     * 这条 uuid 现在是什么状态——不限用户，也不限状态（上面那个只看 pending
+     * 行）。`runTask` 用它把「这条已经跑完了」和「压根没这条」分开回报。
+     *
+     * @param {string} uuid
+     * @returns {Promise<{ status: string }|null>}
+     */
+    getTaskStatusByUuidOnly(uuid: string): Promise<{
+        status: string;
+    } | null>;
+    updateTaskById(taskId: any, updates: any): Promise<any[]>;
+    updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<any[]>;
+    deleteTaskById(taskId: any): Promise<boolean>;
+    deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;
+    getPendingTasks(limit?: number): Promise<any[][]>;
+    claimTask(taskId: any, expectedNextSendAt: any, leaseUntil: any, serializeGroup?: any): Promise<boolean>;
+    renewTaskLease(taskId: any, leaseUntil: any): Promise<boolean>;
+    listTasks(userId: any, opts?: {}): Promise<{
+        tasks: any[][];
+        total: number;
+    }>;
+    cleanupOldTasks(days?: number): Promise<number>;
+    getTaskStatus(uuid: any, userId: any): Promise<any>;
+    getTaskStatusInfo(uuid: any, userId: any): Promise<{
+        status: string;
+        last_error: string | null;
+    }>;
+    getPushSubscription(userId: any): Promise<{
+        subscription: string;
+        updated_at: number;
+    }>;
+    upsertPushSubscription(userId: any, encryptedSubscription: any, updatedAt: any): Promise<boolean>;
+    deletePushSubscription(userId: any): Promise<boolean>;
+    upsertLlmCredentials(userId: any, entries: any): Promise<number>;
+    getLlmCredentials(userId: any, credIds: any): Promise<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }[]>;
+    listLlmCredentials(userId: any): Promise<{
+        cred_id: string;
+        updated_at: string;
+    }[]>;
+    deleteLlmCredentials(userId: any, credIds?: any): Promise<number>;
+}