@rei-standard/amsg-server 2.6.0-next.15 → 2.6.0-next.17

package/README.md

@@ -47,6 +47,9 @@ const rei = await createReiServer({
 // PUT  /api/v1/push-subscription    -> rei.handlers.pushSubscription.PUT
 // GET  /api/v1/push-subscription    -> rei.handlers.pushSubscription.GET
 // DELETE /api/v1/push-subscription  -> rei.handlers.pushSubscription.DELETE
+// PUT  /api/v1/llm-credentials      -> rei.handlers.llmCredentials.PUT
+// GET  /api/v1/llm-credentials      -> rei.handlers.llmCredentials.GET
+// DELETE /api/v1/llm-credentials    -> rei.handlers.llmCredentials.DELETE
 ```
 
 ## 关于 `messageType: 'instant'`
@@ -160,6 +163,51 @@ const message = body.length <= remainingBytes ? body : body.slice(0, remainingBy
 
 装不下的内容（长文、附件详情）建议走旁路：正文存进 `client_state`，push 里只带一个引用键，客户端上线后用 `GET /client-state` 取回。单用户 Worker 的 fire-time hook 用 `ctx.writeState()` 写，见 [`examples/cloudflare-single-user/README.md`](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/examples/cloudflare-single-user/README.md)。
 
+## LLM 凭据（用户级）与 credRefs
+
+LLM API 凭据（`apiUrl` / `apiKey` / `primaryModel`）有两种给法：
+
+- **内联**：随排程请求带三件套，冻结进任务行（一直以来的方式，继续支持）。
+- **引用**：凭据先用 `PUT /llm-credentials` 集中登记，排程 payload 里只带
+  `credRefs: { chat: '<credId>' }`。到点投递时按 credId 现读——换 Key 覆盖对应
+  行就够了，所有引用它的任务（包括角色在 fire 里给自己排的、客户端根本不知道
+  存在的那些）下次触发用的都是新凭据。
+
+| 端点 | 语义 |
+|---|---|
+| `PUT /llm-credentials` | 批量登记 / 覆盖。body =（加密后的）`{ credentials: [{ credId, value: { apiUrl, apiKey, primaryModel } }] }`，一批 ≤100 条，单用户 ≤500 行 |
+| `GET /llm-credentials` | 对账清单 `{ credentials: [{ credId, updatedAt }] }`。**凭据本体永远不回传** |
+| `DELETE /llm-credentials` | 删除。body =（加密后的）`{ credIds: [...] }` 或 `{ all: true }` |
+
+客户端侧对应 `client.putLlmCredentials(credentials)` / `listLlmCredentials()` / `deleteLlmCredentials(opts)`。
+
+`credId` 是客户端起名的**不透明字符串**（1–128 字符、不含控制字符），服务端不
+解释语义。约定：`char:<charId>/<purpose>`（角色级）、`global/<purpose>`（全
+局）。`credRefs` 的 purpose 键里只有 `chat` 由服务端消费（fire 时的主 LLM 调
+用）；其余 purpose（如情绪评估的副 API）归宿主 hook 侧，fire hook 的 ctx 上有
+`resolveLlmCredential(credId)` 可按需取用（每次返回新对象；拿到就用，别挂到
+ctx / metadata / push 上）。
+
+配套的规则：
+
+- 排程 / 更新时对 `credRefs` 里的**全部** credId 做存在性检查，缺的返回
+  `409 CREDENTIAL_NOT_FOUND` 并点名（先登记再排程）。
+- `credRefs.chat` 与内联三件套在同一个请求里不能都传（`400`）：chat 凭据只能
+  有一个来源。
+- fire 时的解析顺序：`credRefs.chat` → 查表；行没了 → 退回任务里的内联三件套
+  （如有）；都没有 → 本轮失败，`lastError` 记 `CREDENTIAL_MISSING`，走常规重
+  试——补传凭据后下一轮自愈。
+- hook 的 `ctx.scheduleTask()` 自排任务时：父任务带 `credRefs` 就复制**引用**
+  （不复制凭据本体），换 Key 自动作用于整条自排链；存量内联任务照旧复制三件套。
+- 任务投影（`GET /messages` / hook 的 `ctx.task`）带 `credRefs`（只是名字，不
+  是机密），客户端对账用；凭据本体照旧被白名单挡在外面。
+- 数据库侧是 `llm_credentials` 表（`(user_id, cred_id)` 主键，`encrypted_value`
+  密文，时间戳 ISO8601 文本）。内置的 D1 / pg / neon 适配器都实现了，
+  `initSchema()` 会建表。自定义适配器要补 `upsertLlmCredentials` /
+  `getLlmCredentials` / `listLlmCredentials` / `deleteLlmCredentials` 四个方法，
+  缺任何一个这几个端点返回 501、带 `credRefs` 的排程也会被拒。
+- 特性探测：`GET /capabilities` 的 `features` 含 `'llm-credentials'`。
+
 ## 读一条任务：列表 vs 单条
 
 | 端点 | 给什么 |
@@ -173,12 +221,13 @@ const message = body.length <= remainingBytes ? body : body.slice(0, remainingBy
 
 ## 更新任务时能改哪些字段
 
-`PUT /update-message` 的可写字段：`contactName` / `avatarUrl` / `userMessage` / `completePrompt` / `messages` / `nextSendAt` / `recurrenceType` / `tzId` / `metadata` / `maxTokens` / `temperature` / `splitPattern`，以及凭据三件套 `apiUrl` / `apiKey` / `primaryModel`。
+`PUT /update-message` 的可写字段：`contactName` / `avatarUrl` / `userMessage` / `completePrompt` / `messages` / `nextSendAt` / `recurrenceType` / `tzId` / `metadata` / `maxTokens` / `temperature` / `splitPattern`、凭据三件套 `apiUrl` / `apiKey` / `primaryModel`，以及凭据引用 `credRefs`。
 
 - `contactName` 必须是非空字符串（口径与排程时一致），空串 / `null` / 非字符串一律 `400`。用户给角色改了名之后，之前排的任务推送出来的通知标题（「来自 <contactName>」）靠它跟着改。
 - `metadata` 是整体替换，不深合并——只改一个子字段的读-改-写流程见上一节。
 - `avatarUrl` 显式传 `null` 是「不改」而不是「清空」（§6.2 的软清空策略要求非法头像被摘掉时保留旧头像，「摘掉」和「传了个 null」在这一层是同一件事）。
 - 凭据三件套传 `null` 同样只是忽略：清掉任何一个，任务到点就发不出去。
+- `credRefs` 是整体替换（语义同 `metadata`），同样做存在性检查；与内联三件套在同一个请求里混着传返回 `400`。给存量内联任务补 `credRefs` 时不动已存的三件套——那份留作 fire 时表行缺失的兜底。
 - `pushSubscription` 不收（`400 PUSH_SUBSCRIPTION_NOT_ACCEPTED`），它是用户级的一份，走 `PUT /push-subscription`。
 
 ## 推送自带任务身份
@@ -382,6 +431,108 @@ await runScheduledTick({
 
 `lease_until` / `retry_after` / `serialize_group`（都可空）。走 `POST /init-tenant`（或任何一次 `initSchema`）会自动给已有的表补上，跑几次都没事；手工维护表结构的看 `examples/cloudflare-single-user/schema.sql`，Postgres 侧对应三句 `ALTER TABLE scheduled_messages ADD COLUMN IF NOT EXISTS …`。分组串行还多一个索引 `idx_serialize_group_lease`，`initSchema` 一并建。
 
+## 表结构自查（`getSchemaVersion` / `ensureSchema`）
+
+建表语句是 `CREATE TABLE IF NOT EXISTS`，已经存在的表不会被改动，后加的列靠 `initSchema()` 里的 ALTER 补。升级到新版之后没人再跑一次建表的话，这个部署的表就停在旧形状上——cron 每分钟挂在缺的那一列上，任务一条都不发，而前端界面一切正常。
+
+这两个函数把「我需要什么 / 现在是什么 / 帮我补齐」露出来：
+
+```js
+import { getSchemaVersion, ensureSchema } from '@rei-standard/amsg-server/cloudflare';
+
+const state = await getSchemaVersion(db);
+// → { current: '2.6.0' | null, required: '2.6.0', ok: true | false, missing: [] }
+
+if (!state.ok) {
+  const fixed = await ensureSchema(db); // 建表 + 补列 + 建索引，重复调没事
+  // → { current, required, ok, missing, migrated: true, schema }
+}
+```
+
+| 字段 | 是什么 |
+|---|---|
+| `required` | 这一版代码需要的表结构版本（导出常量 `SCHEMA_VERSION`）。表结构自己的版本号，只在表 / 列 / 关键索引变化时抬，与包版本各走各的 |
+| `current` | 活库当前满足的版本：够用就是 `required` 那个值，缺东西就是 `null`（只知道不够用，不知道它停在哪一版） |
+| `ok` | 需要的表 / 列 / 关键索引是不是都在 |
+| `missing` | 缺什么，形如 `table:message_outbox` / `column:scheduled_messages.last_error` / `index:uidx_uuid`。整张表缺席时只报这一张表，不逐列展开 |
+| `migrated`（只有 `ensureSchema` 有） | 这次有没有真的跑 `initSchema()`。本来就够用 → `false`，`schema` 也是 `null` |
+
+「需要什么」是从建表语句里解析出来的，不是另抄一份清单：抄的那份漏掉新列的话，自查会对着一个缺列的库回「一切正常」。
+
+什么时候调、缺了怎么提示用户，由宿主决定——库不会在每次请求里偷偷迁移。`POST /init-tenant` 的行为一点没变（它内部做的就是 `initSchema()`）。
+
+单用户 Worker 上有走 `env` 的同名方法：`worker.getSchemaVersion(env)` / `worker.ensureSchema(env)`，省得自己再造一次适配器。
+
+自查要求适配器实现 `describeSchema()`（活库里现在有哪些表 / 列 / 索引，只读）。内置适配器里目前只有 D1 实现了；别的适配器调这两个函数会抛错，而不是假装一切正常。
+
+## 只跑指定那一条任务（`runTask`）
+
+`scheduled()` 的语义是「扫一遍所有到期任务」。刚落库的任务想立刻跑起来时，触发一次全量扫描是能达到目的，但那样多个执行者会去扫同一批任务，宿主只能退回单实例串行才不重复发。
+
+`runTask` 只跑指定那一条，走的是 cron 完全同一条投递链（占位、租约心跳、过期守卫、失败重试 / 终态、hook 全套）：
+
+```js
+// 单用户 Worker：从 env 拿库和配置
+const result = await worker.runTask(uuid, env);
+
+// 自己攒 ctx 的宿主（和 runScheduledTick 同一份 ctx）
+import { runTask } from '@rei-standard/amsg-server/cloudflare';
+const result = await runTask(ctx, uuid);
+```
+
+跑起来了是 `{ ran: true, summary }`（`summary` 与 `runScheduledTick` 的返回同构，`totalTasks` 恒为 1）。不跑的几种情形分开回报，宿主不用猜：
+
+| `reason` | 什么意思 | 附带 |
+|---|---|---|
+| `not_found` | 没有这条 uuid。一次性任务发完即删，所以「已经发完了」的那条也落在这里 | — |
+| `already_settled` | 行还在，但已经是终态 | `status`（`sent` / `failed`） |
+| `not_due` | 还没到触发时刻 | `nextSendAt` |
+| `retry_pending` | 上次投递失败，还在退避窗口里 | `retryAfter` |
+| `not_configured` | VAPID / webpush 没配齐，跑了也只是白扣这条任务一次重试（只有 `worker.runTask` 有这一种） | — |
+
+这个入口只是换了个触发器，不是绕过排期的后门：没到点、在退避窗口里的都不跑。`already_settled` 要求适配器实现 `getTaskStatusByUuidOnly(uuid)`（D1 / pg / neon 都实现了）；不实现的自定义适配器把这种情况并进 `not_found`。
+
+## 出错时的真实原因
+
+`fetch()` 兜底的 500 一直是 `{ success: false, error: { code: 'INTERNAL_ERROR', message: '服务器内部错误' } }`。这两个字段一个没动，真因加在 `error.cause` 上：
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "INTERNAL_ERROR",
+    "message": "服务器内部错误",
+    "cause": {
+      "stage": "request",
+      "name": "Error",
+      "message": "D1_ERROR: no such table: message_outbox"
+    }
+  }
+}
+```
+
+| 字段 | 是什么 |
+|---|---|
+| `stage` | 在哪一段炸的：`config` = 构建配置时（少了 binding、环境变量丢了），`request` = 路由或处理器抛错 |
+| `name` | 错误类型（`error.name`，认不出来时是 `Error`） |
+| `message` | 错误消息，长得像凭据的串已遮掉、超长截断到 500 字符 |
+| `code` | 错误自带的 `code` 字符串，有才带 |
+
+只带错误类型和消息文本：密钥、用户数据、任务正文都不在 `error.message` 上，也不往这里放。
+
+cron 那条路上没有调用方能读到响应，所以另开两个出口：
+
+```js
+export default createSingleUserCloudflareWorker(buildConfig, {
+  onError({ stage, error, cause, path }) {
+    // fetch / cron 任何一段出错都会调一次（best-effort，自身抛错只记日志）
+  },
+});
+```
+
+- `onError` 放在工厂的第二个参数上，而不是 `buildConfig` 的返回值里：`buildConfig` 自己抛错时配置里的东西一个都读不到，而那恰恰是最需要被看见的一种故障。`stage` 在 cron 路径上是 `config`（配置构建失败 / VAPID 没配齐）或 `tick`（那一跳抛错）。VAPID 没配齐这一支没有异常对象，`error` 为 `null`、`cause.name` 是 `VapidNotConfigured`。
+- `scheduled()` 现在有返回值：`{ ok: true, summary }` 或 `{ ok: false, cause }`。Cloudflare 不看它，是给「自己包一层再转调 `scheduled`」的宿主和测试用的。
+
 ## 导出 API（Exports）
 
 包根（`@rei-standard/amsg-server`）：
@@ -391,6 +542,10 @@ await runScheduledTick({
 - `createSingleUserCloudflareWorker` — 单用户 Cloudflare Worker 一键装配（`fetch` + `scheduled` 两个入口）
 - `createAdapter` / `createD1Adapter` — pg·neon / Cloudflare D1 数据库适配器
 - `runScheduledTick` — 手动触发一轮到期任务投递（自定义 cron 宿主、要调 `claimLeaseMs` 时用）
+- `runTask` — 只跑指定那一条任务（与 cron 同一条投递链）
+- `getSchemaVersion` / `ensureSchema` / `SCHEMA_VERSION` — 表结构自查与补齐
+- `summarizeErrorCause` — 把异常压成响应体里 `error.cause` 那个形状（自己包一层路由、想回同样形状时用同一份）
+- `NonRetryableError` / `isNonRetryableError` — hook 侧标注「重试也好不了」的失败
 - `createWebCryptoWebPush` — 纯 Web Crypto 的 Web Push 发送器（不依赖 `web-push` 包）
 - `createTenantToken` / `verifyTenantToken`
 - `deriveUserEncryptionKey` / `decryptPayload` / `encryptForStorage` / `decryptFromStorage`
@@ -401,7 +556,9 @@ await runScheduledTick({
 
 `@rei-standard/amsg-server/cloudflare` 子路径 —— 只含「单用户 + D1 + Web Crypto 推送」这条子图，不引用多租户装配线和 pg / neon / `web-push`，所以 D1-only 安装（不装可选数据库 peer）也能干净打包，Worker 不需要 `nodejs_compat` 兼容 flag：
 
-- `createSingleUserCloudflareWorker` / `createSingleUserServer` / `createD1Adapter` / `runScheduledTick`
+- `createSingleUserCloudflareWorker` / `createSingleUserServer` / `createD1Adapter` / `runScheduledTick` / `runTask`
+- `getSchemaVersion` / `ensureSchema` / `SCHEMA_VERSION`
+- `summarizeErrorCause` / `NonRetryableError` / `isNonRetryableError`
 - `createWebCryptoWebPush` / `measurePushPayload` / `MAX_PUSH_PAYLOAD_BYTES` / `WEB_PUSH_MAX_BODY_BYTES` / `WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES`
 - `deriveUserEncryptionKey` / `decryptPayload` / `encryptForStorage` / `decryptFromStorage`
 

package/dist/adapters/d1.d.ts

@@ -36,6 +36,20 @@ export class D1Adapter {
             error: any;
         })[];
     }>;
+    /**
+     * 活库里现在实际有哪些表 / 列 / 索引。
+     *
+     * 只读不写，纯粹如实回报：拿它跟这一版需要的清单对照的活儿在
+     * lib/schema-version.js（`getSchemaVersion` / `ensureSchema`）。库升级后表结
+     * 构变了而老部署没跑过 initSchema 时，cron 会每分钟静默挂在缺的那一列上，
+     * 界面上一切正常——这个方法就是让宿主查得出来。
+     *
+     * @returns {Promise<{ tables: Record<string, string[]>, indexes: string[] }>}
+     */
+    describeSchema(): Promise<{
+        tables: Record<string, string[]>;
+        indexes: string[];
+    }>;
     dropSchema(): Promise<void>;
     createTask(params: any): Promise<any>;
     /**
@@ -53,6 +67,16 @@ export class D1Adapter {
     createTaskSuperseding(params: import("./interface.js").InsertTaskParams, supersedesUuid: string): Promise<any>;
     getTaskByUuid(uuid: any, userId: any): Promise<any>;
     getTaskByUuidOnly(uuid: any): Promise<any>;
+    /**
+     * 这条 uuid 现在是什么状态——不限用户，也不限状态（getTaskByUuidOnly 只看
+     * 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<{
         uuid: any;
@@ -213,6 +237,51 @@ export class D1Adapter {
      * @returns {Promise<boolean>} true = 确实删掉了一行
      */
     deletePushSubscription(userId: string): Promise<boolean>;
+    /**
+     * 批量 upsert 这个用户的凭据（value 已是密文，加密在上层）。已存在的行
+     * 覆盖 encrypted_value 并刷 updated_at，created_at 保留首次写入的时刻。
+     *
+     * @param {string} userId
+     * @param {Array<{ credId: string, encryptedValue: string }>} entries
+     * @returns {Promise<number>} 实际写入/覆盖的行数
+     */
+    upsertLlmCredentials(userId: string, entries: Array<{
+        credId: string;
+        encryptedValue: string;
+    }>): Promise<number>;
+    /**
+     * 按 cred_id 批量读这个用户的凭据行（`encrypted_value` 是密文，解密在上
+     * 层）。排程时的存在性检查和 fire 时的解析共用这一个口。
+     *
+     * @param {string} userId
+     * @param {string[]} credIds
+     * @returns {Promise<Array<{ cred_id: string, encrypted_value: string, updated_at: string }>>}
+     */
+    getLlmCredentials(userId: string, credIds: string[]): Promise<Array<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at，密文不出
+     * 这个方法）。按 cred_id 排序，输出稳定。
+     *
+     * @param {string} userId
+     * @returns {Promise<Array<{ cred_id: string, updated_at: string }>>}
+     */
+    listLlmCredentials(userId: string): Promise<Array<{
+        cred_id: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 删凭据。`credIds` 传数组删指定那几行；传 null 删这个用户的全部
+     * （「清空云端数据」用）。
+     *
+     * @param {string} userId
+     * @param {string[]|null} credIds
+     * @returns {Promise<number>} 删掉的行数
+     */
+    deleteLlmCredentials(userId: string, credIds?: string[] | null): Promise<number>;
     /**
      * 发送前把这一批 push 落进 outbox（一次 batch）。(user_id, message_id)
      * 唯一：重试同一 occurrence 带着同一批 messageId 再来时更新 payload、不加

package/dist/adapters/interface.d.ts

@@ -29,6 +29,15 @@ 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).
      */
@@ -45,6 +54,14 @@ export type DbAdapter = {
      *   Fetch a single pending task by uuid only (used by instant processing).
      */
     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`（含写
@@ -162,6 +179,39 @@ export type DbAdapter = {
      * （建了也永远发不出去）。内置的 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 非空时生效——收尾放掉租约之后，迟到的心跳不会把

package/dist/adapters/neon.d.ts

@@ -35,6 +35,16 @@ export class NeonAdapter {
     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>;
@@ -58,4 +68,15 @@ export class NeonAdapter {
     }>;
     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

@@ -101,6 +101,53 @@ export function upsertPushSubscription(query: PgQuery, userId: string, encrypted
  * @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 查询实现。
  *

package/dist/adapters/pg.d.ts

@@ -37,6 +37,16 @@ export class PgAdapter {
     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>;
@@ -60,4 +70,15 @@ export class PgAdapter {
     }>;
     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/schema.d.ts

@@ -35,6 +35,7 @@ export const INDEXES: ({
     critical: boolean;
 })[];
 export const PUSH_SUBSCRIPTION_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS push_subscriptions (\n    user_id VARCHAR(255) PRIMARY KEY,\n    subscription TEXT NOT NULL,\n    updated_at BIGINT NOT NULL\n  )\n";
+export const LLM_CREDENTIALS_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS llm_credentials (\n    user_id VARCHAR(255) NOT NULL,\n    cred_id VARCHAR(128) NOT NULL,\n    encrypted_value TEXT NOT NULL,\n    created_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL,\n    PRIMARY KEY (user_id, cred_id)\n  )\n";
 export const VERIFY_TABLE_SQL: "\n  SELECT table_name\n  FROM information_schema.tables\n  WHERE table_schema = 'public'\n    AND table_name = 'scheduled_messages'\n";
 export const COLUMNS_SQL: "\n  SELECT column_name, data_type, is_nullable\n  FROM information_schema.columns\n  WHERE table_schema = 'public'\n    AND table_name = 'scheduled_messages'\n  ORDER BY ordinal_position\n";
 export const UPDATABLE_COLUMNS: Set<string>;

package/dist/adapters/schema.sqlite.d.ts

@@ -32,5 +32,18 @@ export const SQLITE_INDEXES: {
 }[];
 export const CLIENT_STATE_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS client_state (\n    user_id TEXT NOT NULL,\n    namespace TEXT NOT NULL,\n    key TEXT NOT NULL,\n    value TEXT NOT NULL,\n    updated_at INTEGER NOT NULL,\n    PRIMARY KEY (user_id, namespace, key)\n  )\n";
 export const PUSH_SUBSCRIPTION_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS push_subscriptions (\n    user_id TEXT PRIMARY KEY,\n    subscription TEXT NOT NULL,\n    updated_at INTEGER NOT NULL\n  )\n";
+export const LLM_CREDENTIALS_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS llm_credentials (\n    user_id TEXT NOT NULL,\n    cred_id TEXT NOT NULL,\n    encrypted_value TEXT NOT NULL,\n    created_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL,\n    PRIMARY KEY (user_id, cred_id)\n  )\n";
 export const MESSAGE_OUTBOX_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS message_outbox (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    user_id TEXT NOT NULL,\n    message_id TEXT NOT NULL,\n    task_uuid TEXT,\n    session_id TEXT,\n    message_index INTEGER,\n    total_messages INTEGER,\n    payload TEXT NOT NULL,\n    created_at INTEGER NOT NULL,\n    delivered_at INTEGER,\n    acked_at INTEGER,\n    UNIQUE (user_id, message_id)\n  )\n";
 export const MESSAGE_OUTBOX_INDEX_SQL: "\n  CREATE INDEX IF NOT EXISTS idx_outbox_unacked\n    ON message_outbox (user_id, id)\n    WHERE acked_at IS NULL\n";
+/**
+ * 这一版代码跑起来需要的表 / 列 / 索引。
+ *
+ * 索引只列 critical 的那几个（uidx_uuid 之类）：其余索引缺了只是慢，缺了它则
+ * 是正确性问题。
+ *
+ * @type {{ tables: Record<string, string[]>, indexes: string[] }}
+ */
+export const SQLITE_REQUIRED_SCHEMA: {
+    tables: Record<string, string[]>;
+    indexes: string[];
+};

package/dist/{chunk-34I2YSWE.mjs → chunk-5FXVSC5O.mjs}

@@ -93,6 +93,16 @@ var PUSH_SUBSCRIPTION_TABLE_SQL = `
     updated_at BIGINT NOT NULL
   )
 `;
+var LLM_CREDENTIALS_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS llm_credentials (
+    user_id VARCHAR(255) NOT NULL,
+    cred_id VARCHAR(128) NOT NULL,
+    encrypted_value TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (user_id, cred_id)
+  )
+`;
 var VERIFY_TABLE_SQL = `
   SELECT table_name
   FROM information_schema.tables
@@ -127,6 +137,7 @@ export {
   MIGRATIONS,
   INDEXES,
   PUSH_SUBSCRIPTION_TABLE_SQL,
+  LLM_CREDENTIALS_TABLE_SQL,
   VERIFY_TABLE_SQL,
   COLUMNS_SQL,
   UPDATABLE_COLUMNS

package/dist/{chunk-TFFBMYA2.cjs → chunk-E7OWP3VL.cjs}

@@ -84,6 +84,46 @@ async function deletePushSubscription(query, userId) {
   );
   return rows.length > 0;
 }
+async function upsertLlmCredentials(query, userId, entries, now) {
+  let upserted = 0;
+  for (const entry of entries) {
+    const rows = await query(
+      `INSERT INTO llm_credentials (user_id, cred_id, encrypted_value, created_at, updated_at)
+       VALUES ($1, $2, $3, $4, $4)
+       ON CONFLICT (user_id, cred_id) DO UPDATE SET
+         encrypted_value = EXCLUDED.encrypted_value,
+         updated_at = EXCLUDED.updated_at
+       RETURNING cred_id`,
+      [userId, entry.credId, entry.encryptedValue, now]
+    );
+    if (rows.length > 0) upserted++;
+  }
+  return upserted;
+}
+async function getLlmCredentials(query, userId, credIds) {
+  if (!credIds || credIds.length === 0) return [];
+  return query(
+    `SELECT cred_id, encrypted_value, updated_at
+     FROM llm_credentials
+     WHERE user_id = $1 AND cred_id = ANY($2)`,
+    [userId, credIds]
+  );
+}
+async function listLlmCredentials(query, userId) {
+  return query(
+    "SELECT cred_id, updated_at FROM llm_credentials WHERE user_id = $1 ORDER BY cred_id ASC",
+    [userId]
+  );
+}
+async function deleteLlmCredentials(query, userId, credIds = null) {
+  if (credIds !== null && credIds.length === 0) return 0;
+  const rows = credIds === null ? await query("DELETE FROM llm_credentials WHERE user_id = $1 RETURNING cred_id", [userId]) : await query("DELETE FROM llm_credentials WHERE user_id = $1 AND cred_id = ANY($2) RETURNING cred_id", [userId, credIds]);
+  return rows.length;
+}
+
+
+
+
 
 
 
@@ -92,4 +132,4 @@ async function deletePushSubscription(query, userId) {
 
 
 
-exports.claimTask = claimTask; exports.renewTaskLease = renewTaskLease; exports.getTaskStatusInfo = getTaskStatusInfo; exports.getPushSubscription = getPushSubscription; exports.upsertPushSubscription = upsertPushSubscription; exports.deletePushSubscription = deletePushSubscription;
+exports.claimTask = claimTask; exports.renewTaskLease = renewTaskLease; exports.getTaskStatusInfo = getTaskStatusInfo; exports.getPushSubscription = getPushSubscription; exports.upsertPushSubscription = upsertPushSubscription; exports.deletePushSubscription = deletePushSubscription; exports.upsertLlmCredentials = upsertLlmCredentials; exports.getLlmCredentials = getLlmCredentials; exports.listLlmCredentials = listLlmCredentials; exports.deleteLlmCredentials = deleteLlmCredentials;