@rei-standard/amsg-server 2.6.0-next.9 → 3.0.0

package/dist/adapters/factory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ *
+ * @typedef {'neon'|'pg'} DriverName
+ *
+ * @typedef {Object} AdapterConfig
+ * @property {DriverName} driver  - Which database driver to use.
+ * @property {string}     connectionString - Database connection URL.
+ */
+/**
+ * Create a database adapter.
+ *
+ * @param {AdapterConfig} config
+ * @returns {Promise<import('./interface.js').DbAdapter>}
+ */
+export function createAdapter(config: AdapterConfig): Promise<import("./interface.js").DbAdapter>;
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ */
+export type DriverName = "neon" | "pg";
+/**
+ * Adapter Factory
+ *
+ * Creates a database adapter instance based on the supplied configuration.
+ */
+export type AdapterConfig = {
+    /**
+     * - Which database driver to use.
+     */
+    driver: DriverName;
+    /**
+     * - Database connection URL.
+     */
+    connectionString: string;
+};

package/dist/adapters/interface.d.ts

@@ -0,0 +1,384 @@
+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>;
+    /**
+     * （可选）活库里现在实际有哪些表 / 列 / 索引 / 触发器，只读不写。`triggers`
+     * 可以不回，不回时触发器这一项不查。
+     * `getSchemaVersion` / `ensureSchema`（lib/schema-version.js）拿它跟这一版
+     * 需要的清单对照；不实现的适配器调那两个函数会抛错。内置只有 D1 实现。
+     */
+    describeSchema?: () => Promise<{
+        tables: Record<string, string[]>;
+        indexes: string[];
+        triggers?: 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()` 的删除会失效。
+     * `now` 是服务端当前时刻（epoch 毫秒）：库里 `updated_at` 晚于它的行只可能来自跑偏的设备时钟，
+     * 写入与删除都对这种行放行，否则那一行会一直卡到真实时间追上去为止。忽略这个参数的自定义
+     * adapter 功能不变，只是没有这道解锁。
+     * `outcomes` 逐条报告 entries[i] 是否真的写入（缺席时调用方按物理行计数兜底）。
+     * `cleanupOutcomes`（可选）逐条报告 cleanups[i] 的结局：精确 key 形态回 `true`（这个 key 的行已不在——
+     * 删掉了或本来就没有）/ `false`（行还在，库里那行更新、删除被条件写拦下）；前缀形态回 `null`。
+     * 调用方靠它把被拦下的删除计入 skippedEntries；缺席时删除一律按「已删」计。
+     */
+    upsertClientState?: (userId: string, entries: Array<{
+        namespace: string;
+        key: string;
+        value: string;
+        updatedAt: number;
+    }>, cleanups?: Array<{
+        namespace: string;
+        key?: string;
+        keyPrefix?: string;
+        updatedAt: number;
+    }>, now?: number) => Promise<{
+        upserted: number;
+        skipped: number;
+        outcomes?: boolean[];
+        cleanupOutcomes?: Array<boolean | null>;
+    }>;
+    /**
+     * (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）这个用户名下有哪些命名空间，各自几条 / 占多少字节 / 最后
+     * 更新是什么时候。按 namespace 升序，最多 `limit` 条（调用方自己判断有没有被截断：
+     * 多要一条，回来的比 limit 多就说明还有）。
+     * `foldPrefix` 是大值分块那个保留命名空间的前缀（见 lib/state-chunks.js）：以它
+     * 开头的行不单独列，字节数与最后更新时刻折算进去掉前缀后的原命名空间，条目数不
+     * 折算（切片是一个逻辑条目的几段）。折算必须在取 `limit` 之前做——保留命名空间以
+     * \u001f 开头，排在所有正常命名空间前面，先截断再折算会把额度全吃掉。
+     * 不实现 → `GET /client-state/namespaces` 返回 501。
+     */
+    listClientStateNamespaces?: (userId: string, opts?: {
+        limit?: number;
+        foldPrefix?: string | null;
+    }) => Promise<Array<{
+        namespace: string;
+        entry_count: number;
+        byte_size: number;
+        updated_at: number;
+    }>>;
+    /**
+     * （可选；单用户/D1）把这几个命名空间下这个用户的行一次删光，要在同一个事务里。
+     * 调用方传的是「原命名空间 + 它的切片保留命名空间」两个：只删前者会把大值的切片
+     * 行留成孤儿。返回删掉的行数合计。不实现 → `DELETE /client-state?namespace=` 返回
+     * 501（不带 namespace 的整表全清仍走 clearClientState，不受影响）。
+     */
+    deleteClientStateNamespaces?: (userId: string, namespaces: 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 删全部。返回删掉的行数。
+     */
+    deleteLlmCredentials?: (userId: string, credIds: string[] | null) => Promise<number>;
+    /**
+     * （可选）按 cred_id 前缀删（宿主按角色清理：`char:<charId>/` 一把清掉该角色
+     * 名下的几行）。返回删掉的行数。这一个单独可选，不在下面那组「四个要么都实现」
+     * 里——不实现时 `DELETE /llm-credentials` 的 `credIdPrefix` 入参返回 501，另外
+     * 两种入参（`credIds` / `all`）照常。
+     * 实现时别用 LIKE：D1 把 LIKE / GLOB 的 pattern 压到 50 字节，`char:<uuid>/`
+     * 就已经 42 字节了，稍长一点整条语句报 `pattern too complex`。走字典序范围
+     * （`cred_id >= 前缀 AND cred_id < 上界`）没有长度上限，见 adapters/d1.js。
+     *
+     * llm_credentials 四个方法要么都实现、要么都不实现：缺任何一个，
+     * `PUT/GET/DELETE /llm-credentials` 返回 501，带 `credRefs` 的
+     * `POST /schedule-message` 也会被拒。内置的 D1 / pg / neon 适配器都实现了。
+     */
+    deleteLlmCredentialsByPrefix?: (userId: string, credIdPrefix: string) => 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）。内置的 D1 / pg / neon 都实现了。不实现时 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）按 task_uuid 一次删掉该任务名下还没发出去的行
+     * （delivered_at 与 acked_at 均为 NULL）。取消 / 顶替的 outbox 清理优先走
+     * 它：一个来回，且不受未 ack 积压量的影响。不实现 → 退回
+     * listUnackedOutbox + discardOutboxMessages 的翻页扫描，扫描有行数上限
+     * （见 lib/outbox-store.js），积压超过上限时会漏撤并打日志。
+     */
+    discardUndeliveredOutboxForTask?: (userId: string, taskUuid: string) => Promise<number>;
+    /**
+     * （可选；单用户/D1）未 ack 的行，id 升序游标翻页（GET /outbox）。行上要带
+     * `task_uuid` 和 `delivered_at`：适配器没实现 discardUndeliveredOutboxForTask
+     * 时，`DELETE /message` 和 supersedesUuid 顶替这两条路靠翻这份名单找出该任务
+     * 名下还没发出去的行，缺任一字段就挑不出来，那两条路上的 outbox 清理会静默
+     * 跳过。
+     */
+    listUnackedOutbox?: (userId: string, sinceId: number, limit: number) => Promise<Array<any>>;
+    /**
+     * （可选；单用户/D1）某条任务名下 `created_at >= sinceMs` 的行，**不论投递 /
+     * ack 状态**，行上要带 `message_index`、`total_messages`、`payload`、
+     * `created_at`、`delivered_at`、`acked_at`。生成成功之后推送失败、任务走重试
+     * 时，重试那一跳靠它找到这次触发已经落定的那一批，只补推送、不重新生成（见
+     * lib/outbox-store.js 的 findCommittedBatch）。不实现 → 退回
+     * listUnackedOutbox 的翻页扫描，读不到已 ack 的行：客户端恰好在两次重试之间
+     * 把整批 ack 了的话，那一跳会重新生成一份。
+     */
+    listOutboxForTask?: (userId: string, taskUuid: string, options?: {
+        sinceMs?: number;
+        limit?: number;
+    }) => Promise<Array<any>>;
+    /**
+     * （可选；单用户/D1）客户端确认收到（POST /outbox/ack，幂等）。
+     */
+    ackOutboxMessages?: (userId: string, messageIds: string[], ackedAt: number) => Promise<number>;
+    /**
+     * （可选；单用户/D1）主动删行：数组删指定那几条，null 删这个用户的全部
+     * （`DELETE /outbox`）。与 `discardOutboxMessages` 分工不同——那个只撤还没发出
+     * 去的行（取消 / 顶替的收尾），这个不看 delivered_at / acked_at，是宿主对完账
+     * 之后的清理口。不实现 → `DELETE /outbox` 返回 501。
+     * 数组形态要按 D1 的 100 个绑定参数上限切批（`user_id` 占 1 个 → 一批最多 99
+     * 个 id），切开的几条仍要在一个事务里。
+     */
+    deleteOutboxMessages?: (userId: string, messageIds: string[] | null) => 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,105 @@
+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>>;
+    createTaskSuperseding(params: any, supersedesUuid: any): Promise<{
+        id: number;
+        uuid: string;
+        next_send_at: any;
+        status: string;
+        created_at: any;
+        superseded: boolean;
+    }>;
+    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>>;
+    /**
+     * 按 uuid 改一条 pending 任务（PUT /update-message、fire hook 的 renewTask）。
+     *
+     * 改排期（extraFields 里带 next_send_at）时多一道租约门：这条任务正被一次投递
+     * 占着的话不改，返回 null。投递收尾会按自己领取时看到的排期推进下一次（一次性
+     * 任务干脆标成已发送），这期间写进去的新时刻随后就被盖掉，接口却已经回了成功
+     * ——用户以为改期生效了，实际什么都没留下。正文这类字段不受这道门约束：它们
+     * 只影响以后的触发，收尾那边本来就不会覆盖（见 run-tick 的收尾守卫）。
+     */
+    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>;
+}