@rei-standard/amsg-server 2.6.0-next.6 → 2.6.0-next.7

package/README.md

@@ -104,10 +104,32 @@ AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
 - 限制：每项 ≤ 200 字符，数组 ≤ 10 项；非法或无法 `new RegExp(...)` 通过 → `400 INVALID_PARAMETERS`（schedule）/ `400 INVALID_UPDATE_DATA`（update）。
 - `update-message` 显式传 `splitPattern: null` 可重置回默认；不传则保留原值。
 
+## 一条 Web Push 能塞多少
+
+推送服务（FCM / APNs / Mozilla autopush）限的是**加密后** body 的 4096 字节，超了当场 413 拒收，用户什么也收不到。明文额度要把 aes128gcm 的固定开销减掉——header 86（salt 16 + record size 4 + keyid 长度 1 + 应用服务器公钥 65）+ 填充分隔符 1 + GCM auth tag 16 = 103 字节——所以**一条 push 的 payload 上限是 3993 字节**，按 UTF-8 字节算，不是字符数。
+
+`sendWebPush` 会在发出去之前挡下超限的 payload，抛出 `err.code === 'PUSH_PAYLOAD_TOO_LARGE'` 的错误，消息里带实际字节数和上限。
+
+组 payload 之前想自己做预算，用导出的常量和工具函数，别写死魔法数字：
+
+```js
+import { MAX_PUSH_PAYLOAD_BYTES, measurePushPayload } from '@rei-standard/amsg-server';
+
+const { bytes, remainingBytes, withinLimit } = measurePushPayload(JSON.stringify(push));
+// remainingBytes = 还能再塞多少字节（已超限时为负）
+```
+
+装不下的内容（长文、附件详情）建议走旁路：正文存进 `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)。
+
 ## 导出（新增）
 
 - `validateLlmMessagesArray(messages)` — 同步预校验 messages 数组，返回 `string | null`（错误信息 / 通过）。和 `@rei-standard/amsg-instant` 的校验规则字节级一致。
 - `validateSplitPattern(value)` — 同步预校验 splitPattern（string / string[] / null），返回 `string | null`。
+- `MAX_PUSH_PAYLOAD_BYTES` — 一条 push 的明文上限，3993 字节。
+- `WEB_PUSH_MAX_BODY_BYTES` / `WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES` — 推送服务的密文 body 上限（4096）与 aes128gcm 固定开销（103），上面那个数就是两者相减。
+- `measurePushPayload(payload)` — 量一段 payload 的字节数与剩余额度，返回 `{ bytes, maxBytes, remainingBytes, withinLimit }`。
+
+以上四个在包根和 `@rei-standard/amsg-server/cloudflare` 两个入口都有。
 
 ## 一体化初始化流程
 
@@ -150,6 +172,10 @@ AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
 - `encryptForStorage`
 - `decryptFromStorage`
 - `validateScheduleMessagePayload`
+- `measurePushPayload`
+- `MAX_PUSH_PAYLOAD_BYTES`
+- `WEB_PUSH_MAX_BODY_BYTES`
+- `WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES`
 - `isValidISO8601`
 - `isValidUrl`
 - `isValidUUID`

package/dist/{chunk-JODQV7MD.mjs → chunk-I7EUMYQ4.mjs}

@@ -559,6 +559,79 @@ async function resolveClientStateEntries(rows, fetchChunkRows, decryptValue) {
   return entries;
 }
 
+// src/server/lib/client-state-store.js
+var utf82 = new TextEncoder();
+var MAX_STATE_ENTRIES_PER_BATCH = 200;
+var MAX_NAMESPACE_CHARS = 128;
+var MAX_KEY_CHARS = 256;
+function stateValueBytes(value) {
+  return utf82.encode(value).length;
+}
+async function writeClientStateEntries({ db, userId, userKey, entries }) {
+  const physicalRows = [];
+  const cleanups = [];
+  const rootRowIndexes = [];
+  let deleted = 0;
+  for (const entry of entries) {
+    cleanups.push({
+      namespace: chunkNamespaceFor(entry.namespace),
+      keyPrefix: chunkKeyPrefixFor(entry.key),
+      updatedAt: entry.updatedAt
+    });
+    if (entry.value === null) {
+      cleanups.push({
+        namespace: entry.namespace,
+        key: entry.key,
+        updatedAt: entry.updatedAt
+      });
+      deleted++;
+      continue;
+    }
+    rootRowIndexes.push(physicalRows.length);
+    if (stateValueBytes(entry.value) <= STATE_CHUNK_SLICE_BYTES) {
+      physicalRows.push({
+        namespace: entry.namespace,
+        key: entry.key,
+        value: await encryptForStorage(entry.value, userKey),
+        updatedAt: entry.updatedAt
+      });
+    } else {
+      const slices = splitStateValue(entry.value);
+      physicalRows.push({
+        namespace: entry.namespace,
+        key: entry.key,
+        value: buildChunkedRootValue(slices.length),
+        updatedAt: entry.updatedAt
+      });
+      const encryptedSlices = await Promise.all(slices.map((slice) => encryptForStorage(slice, userKey)));
+      for (let c = 0; c < encryptedSlices.length; c++) {
+        physicalRows.push({
+          namespace: chunkNamespaceFor(entry.namespace),
+          key: chunkKeyFor(entry.key, c),
+          value: encryptedSlices[c],
+          updatedAt: entry.updatedAt
+        });
+      }
+    }
+  }
+  if (physicalRows.length === 0 && cleanups.length === 0) {
+    return { upserted: 0, skipped: 0, deleted: 0 };
+  }
+  const result = await db.upsertClientState(userId, physicalRows, cleanups);
+  let upserted = 0;
+  let skipped = 0;
+  if (Array.isArray(result.outcomes) && result.outcomes.length === physicalRows.length) {
+    for (const rootIndex of rootRowIndexes) {
+      if (result.outcomes[rootIndex]) upserted++;
+      else skipped++;
+    }
+  } else {
+    upserted = result.upserted;
+    skipped = result.skipped;
+  }
+  return { upserted, skipped, deleted };
+}
+
 // src/server/lib/agentic-fire.js
 var DEFAULT_MAX_TOOL_ITERATIONS = 5;
 var DEFAULT_TOTAL_TIMEOUT_MS = 24e4;
@@ -632,11 +705,64 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       (value) => decryptFromStorage(value, userKey)
     );
   };
+  const maxStateValueBytes = Number.isInteger(ctx.maxStateValueBytes) && ctx.maxStateValueBytes > 0 ? ctx.maxStateValueBytes : DEFAULT_MAX_STATE_VALUE_BYTES;
+  const writeState = async (namespace, entries) => {
+    if (typeof namespace !== "string" || !namespace.trim()) {
+      throw new TypeError("writeState(namespace, entries) requires a non-empty string namespace");
+    }
+    if (namespace.length > MAX_NAMESPACE_CHARS || INTERNAL_STATE_CHAR_RE.test(namespace)) {
+      throw new TypeError(
+        `writeState: namespace \u5FC5\u987B\u662F 1-${MAX_NAMESPACE_CHARS} \u5B57\u7B26\u4E14\u4E0D\u542B\u63A7\u5236\u5B57\u7B26\uFF08\\u0000-\\u001f \u4E3A\u5E93\u5185\u90E8\u4FDD\u7559\uFF09`
+      );
+    }
+    if (!Array.isArray(entries)) {
+      throw new TypeError("writeState(namespace, entries) requires an array of { key, value }");
+    }
+    if (entries.length === 0) return { upserted: 0, skipped: 0, deleted: 0 };
+    if (entries.length > MAX_STATE_ENTRIES_PER_BATCH) {
+      throw new RangeError(`writeState: \u5355\u6B21\u6700\u591A ${MAX_STATE_ENTRIES_PER_BATCH} \u6761\uFF0C\u6536\u5230 ${entries.length} \u6761`);
+    }
+    if (!ctx.db || typeof ctx.db.upsertClientState !== "function") {
+      throw new Error("AGENTIC_STATE_WRITE_UNSUPPORTED: \u5F53\u524D\u6570\u636E\u5E93\u9002\u914D\u5668\u4E0D\u652F\u6301 client_state \u5199\u5165");
+    }
+    const now = nowFn();
+    const normalized2 = entries.map((entry, index) => {
+      if (!entry || typeof entry !== "object") {
+        throw new TypeError(`writeState: entries[${index}] \u5FC5\u987B\u662F\u5BF9\u8C61`);
+      }
+      if (typeof entry.key !== "string" || !entry.key.trim() || entry.key.length > MAX_KEY_CHARS) {
+        throw new TypeError(`writeState: entries[${index}].key \u5FC5\u987B\u662F 1-${MAX_KEY_CHARS} \u5B57\u7B26\u7684\u5B57\u7B26\u4E32`);
+      }
+      if (INTERNAL_STATE_CHAR_RE.test(entry.key)) {
+        throw new TypeError(`writeState: entries[${index}].key \u4E0D\u80FD\u5305\u542B\u63A7\u5236\u5B57\u7B26\uFF08\\u0000-\\u001f \u4E3A\u5E93\u5185\u90E8\u4FDD\u7559\uFF09`);
+      }
+      if (entry.value !== null && typeof entry.value !== "string") {
+        throw new TypeError(`writeState: entries[${index}].value \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\uFF08\u5BBF\u4E3B\u81EA\u884C\u5E8F\u5217\u5316\uFF09\uFF0C\u6216 null \u8868\u793A\u5220\u9664`);
+      }
+      if (typeof entry.value === "string") {
+        const bytes = stateValueBytes(entry.value);
+        if (bytes > maxStateValueBytes) {
+          throw new RangeError(`writeState: entries[${index}].value \u4E3A ${bytes} \u5B57\u8282\uFF0C\u8D85\u8FC7\u5355\u6761\u4E0A\u9650 ${maxStateValueBytes} \u5B57\u8282`);
+        }
+      }
+      if (entry.updatedAt !== void 0 && (!Number.isInteger(entry.updatedAt) || entry.updatedAt <= 0)) {
+        throw new TypeError(`writeState: entries[${index}].updatedAt \u5FC5\u987B\u662F\u6B63\u6574\u6570\uFF08epoch \u6BEB\u79D2\uFF09`);
+      }
+      return {
+        namespace,
+        key: entry.key,
+        value: entry.value,
+        updatedAt: entry.updatedAt ?? now
+      };
+    });
+    return writeClientStateEntries({ db: ctx.db, userId: task.user_id, userKey, entries: normalized2 });
+  };
   const scratch = {};
   const fireCtx = Object.freeze({
     task: buildHookTask(task, decryptedPayload),
     userId: task.user_id,
     readState,
+    writeState,
     now: new Date(nowFn()),
     scratch
   });
@@ -668,16 +794,20 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     );
     const assistantMessage = extractAssistantMessage(llmResponse);
     messages = [...messages, assistantMessage];
-    const sessionCtx = buildSessionContext({
-      sessionId,
-      messages,
-      llmResponse,
-      iteration,
-      contactName: decryptedPayload.contactName,
-      avatarUrl: decryptedPayload.avatarUrl || void 0,
-      charId: decryptedPayload.charId,
-      metadata: decryptedPayload.metadata,
-      scratch
+    const sessionCtx = Object.freeze({
+      ...buildSessionContext({
+        sessionId,
+        messages,
+        llmResponse,
+        iteration,
+        contactName: decryptedPayload.contactName,
+        avatarUrl: decryptedPayload.avatarUrl || void 0,
+        charId: decryptedPayload.charId,
+        metadata: decryptedPayload.metadata,
+        scratch
+      }),
+      readState,
+      writeState
     });
     const decision = await hooks.onLLMOutput(sessionCtx);
     assertValidDecision(decision, { inlineToolCalls: true });
@@ -1796,9 +1926,15 @@ var D1Adapter = class {
    * than the stored row (updatedAt strictly lower) is skipped; equal or
    * newer overwrites. Values arrive pre-encrypted (the handler encrypts).
    *
-   * `cleanups` 是分块存储的清理项（见 lib/state-chunks.js）：在同一 batch 里
-   * 先于 upsert 执行，按 (namespace, key 前缀) 删掉旧写入留下的切片行；
-   * `updated_at <= ?` 条件保证陈旧批次删不动更新写入的行。
+   * `cleanups` 是删除项：在同一 batch 里先于 upsert 执行，`updated_at <= ?`
+   * 条件保证陈旧批次删不动更新写入的行。两种形态——
+   *   - `{ namespace, keyPrefix, updatedAt }` 删 key 前缀下的所有行，用来清掉
+   *     大值旧写入留下的切片行（见 lib/state-chunks.js）；
+   *   - `{ namespace, key, updatedAt }` 删这一个 key，用来删整条状态（前缀会
+   *     连带删掉同前缀的兄弟 key，删单条必须走精确匹配）。
+   *
+   * 删掉一整条状态就是这两种各来一条（切片行走前缀、根行走精确 key），
+   * `entries` 传空数组即可——见 lib/client-state-store.js。
    *
    * Uses D1's batch() — one network round trip for the whole set (implicit
    * transaction). The client calls this endpoint inside its few-seconds
@@ -1808,7 +1944,7 @@ var D1Adapter = class {
    *
    * @param {string} userId
    * @param {Array<{ namespace: string, key: string, value: string, updatedAt: number }>} entries
-   * @param {Array<{ namespace: string, keyPrefix: string, updatedAt: number }>} [cleanups]
+   * @param {Array<{ namespace: string, key?: string, keyPrefix?: string, updatedAt: number }>} [cleanups]
    * @returns {Promise<{ upserted: number, skipped: number, outcomes: boolean[] }>}
    *   `outcomes[i]` 对应 entries[i] 是否真的写入（changes > 0）。
    */
@@ -1819,12 +1955,12 @@ var D1Adapter = class {
          value = excluded.value,
          updated_at = excluded.updated_at
        WHERE excluded.updated_at >= client_state.updated_at`;
-    const CLEANUP_SQL = `DELETE FROM client_state
+    const CLEANUP_PREFIX_SQL = `DELETE FROM client_state
        WHERE user_id = ? AND namespace = ? AND key LIKE ? ESCAPE '\\' AND updated_at <= ?`;
+    const CLEANUP_KEY_SQL = `DELETE FROM client_state
+       WHERE user_id = ? AND namespace = ? AND key = ? AND updated_at <= ?`;
     const buildStatements = () => [
-      ...cleanups.map(
-        (c) => this._db.prepare(CLEANUP_SQL).bind(userId, c.namespace, `${escapeLikePrefix(c.keyPrefix)}%`, c.updatedAt)
-      ),
+      ...cleanups.map((c) => typeof c.key === "string" ? this._db.prepare(CLEANUP_KEY_SQL).bind(userId, c.namespace, c.key, c.updatedAt) : this._db.prepare(CLEANUP_PREFIX_SQL).bind(userId, c.namespace, `${escapeLikePrefix(c.keyPrefix)}%`, c.updatedAt)),
       ...entries.map(
         (entry) => this._db.prepare(UPSERT_SQL).bind(userId, entry.namespace, entry.key, entry.value, entry.updatedAt)
       )
@@ -1987,10 +2123,7 @@ function createVapidPublicKeyHandler(ctx) {
 }
 
 // src/server/handlers/client-state.js
-var MAX_STATE_ENTRIES_PER_REQUEST = 200;
-var MAX_NAMESPACE_CHARS = 128;
-var MAX_KEY_CHARS = 256;
-var utf82 = new TextEncoder();
+var MAX_STATE_ENTRIES_PER_REQUEST = MAX_STATE_ENTRIES_PER_BATCH;
 function err(status, code, message, details) {
   const error = details === void 0 ? { code, message } : { code, message, details };
   return { status, body: { success: false, error } };
@@ -2028,7 +2161,7 @@ function validateEntry(entry, index, maxValueBytes) {
   if (typeof entry.value !== "string") {
     return rejectEntry(entry, index, "INVALID_STATE_VALUE", `entries[${index}].value \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\uFF08\u5BBF\u4E3B\u81EA\u884C\u5E8F\u5217\u5316\uFF09`);
   }
-  const bytes = utf82.encode(entry.value).length;
+  const bytes = stateValueBytes(entry.value);
   if (bytes > maxValueBytes) {
     return rejectEntry(entry, index, "STATE_VALUE_TOO_LARGE", `entries[${index}].value \u8D85\u8FC7\u5355\u6761\u603B\u4E0A\u9650`, { bytes, maxBytes: maxValueBytes });
   }
@@ -2082,56 +2215,7 @@ function createClientStateHandler(ctx) {
     if (typeof db.upsertClientState !== "function") {
       return err(501, "CLIENT_STATE_NOT_SUPPORTED", "\u5F53\u524D\u6570\u636E\u5E93\u9002\u914D\u5668\u4E0D\u652F\u6301 client_state");
     }
-    const physicalRows = [];
-    const cleanups = [];
-    const rootRowIndexes = [];
-    for (const entry of accepted) {
-      cleanups.push({
-        namespace: chunkNamespaceFor(entry.namespace),
-        keyPrefix: chunkKeyPrefixFor(entry.key),
-        updatedAt: entry.updatedAt
-      });
-      rootRowIndexes.push(physicalRows.length);
-      if (utf82.encode(entry.value).length <= STATE_CHUNK_SLICE_BYTES) {
-        physicalRows.push({
-          namespace: entry.namespace,
-          key: entry.key,
-          value: await encryptForStorage(entry.value, userKey),
-          updatedAt: entry.updatedAt
-        });
-      } else {
-        const slices = splitStateValue(entry.value);
-        physicalRows.push({
-          namespace: entry.namespace,
-          key: entry.key,
-          value: buildChunkedRootValue(slices.length),
-          updatedAt: entry.updatedAt
-        });
-        const encryptedSlices = await Promise.all(slices.map((slice) => encryptForStorage(slice, userKey)));
-        for (let c = 0; c < encryptedSlices.length; c++) {
-          physicalRows.push({
-            namespace: chunkNamespaceFor(entry.namespace),
-            key: chunkKeyFor(entry.key, c),
-            value: encryptedSlices[c],
-            updatedAt: entry.updatedAt
-          });
-        }
-      }
-    }
-    let upserted = 0;
-    let skipped = 0;
-    if (physicalRows.length > 0) {
-      const result = await db.upsertClientState(userId, physicalRows, cleanups);
-      if (Array.isArray(result.outcomes) && result.outcomes.length === physicalRows.length) {
-        for (const rootIndex of rootRowIndexes) {
-          if (result.outcomes[rootIndex]) upserted++;
-          else skipped++;
-        }
-      } else {
-        upserted = result.upserted;
-        skipped = result.skipped;
-      }
-    }
+    const { upserted, skipped } = await writeClientStateEntries({ db, userId, userKey, entries: accepted });
     const data = { upserted, skipped };
     if (rejected.length > 0) data.rejected = rejected;
     return { status: 200, body: { success: true, data } };
@@ -2178,7 +2262,7 @@ function createClientStateHandler(ctx) {
 }
 
 // src/server/lib/version.js
-var SERVER_VERSION = true ? "2.6.0-next.6" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.6.0-next.7" : "0.0.0-dev";
 
 // src/server/handlers/capabilities.js
 var SERVER_FEATURES = Object.freeze([
@@ -2187,6 +2271,7 @@ var SERVER_FEATURES = Object.freeze([
   "client-state-partial-failure",
   "agentic-hooks",
   "agentic-scratch",
+  "agentic-write-state",
   "vapid-public-key"
 ]);
 function createCapabilitiesHandler(ctx) {
@@ -2254,6 +2339,19 @@ var NONCE_INFO = utf8("Content-Encoding: nonce\0");
 var VAPID_DEFAULT_TTL = 60;
 var VAPID_TOKEN_LIFETIME = 12 * 3600;
 var RECORD_SIZE = 4096;
+var WEB_PUSH_MAX_BODY_BYTES = 4096;
+var WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = 16 + 4 + 1 + 65 + 1 + 16;
+var MAX_PUSH_PAYLOAD_BYTES = WEB_PUSH_MAX_BODY_BYTES - WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES;
+var payloadEncoder = new TextEncoder();
+function measurePushPayload(payload) {
+  const bytes = payloadEncoder.encode(typeof payload === "string" ? payload : String(payload)).length;
+  return {
+    bytes,
+    maxBytes: MAX_PUSH_PAYLOAD_BYTES,
+    remainingBytes: MAX_PUSH_PAYLOAD_BYTES - bytes,
+    withinLimit: bytes <= MAX_PUSH_PAYLOAD_BYTES
+  };
+}
 async function sendWebPush({ subscription, payload, vapid, ttl, fetch: fetchImpl }) {
   if (!subscription || typeof subscription.endpoint !== "string") {
     throw new Error("sendWebPush: invalid subscription");
@@ -2268,6 +2366,16 @@ async function sendWebPush({ subscription, payload, vapid, ttl, fetch: fetchImpl
   if (typeof subscriptionKeys.p256dh !== "string" || typeof subscriptionKeys.auth !== "string") {
     throw new Error("sendWebPush: subscription.keys.p256dh and .auth are required");
   }
+  const size = measurePushPayload(payload);
+  if (!size.withinLimit) {
+    const err2 = new Error(
+      `sendWebPush: payload is ${size.bytes} bytes, over the ${MAX_PUSH_PAYLOAD_BYTES}-byte limit (push services cap the encrypted body at ${WEB_PUSH_MAX_BODY_BYTES} bytes; aes128gcm adds ${WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES} bytes)`
+    );
+    err2.code = "PUSH_PAYLOAD_TOO_LARGE";
+    err2.bytes = size.bytes;
+    err2.maxBytes = MAX_PUSH_PAYLOAD_BYTES;
+    throw err2;
+  }
   const encryptedBody = await encryptPushPayload({
     plaintext: utf8(payload),
     uaPublicKey: base64UrlToBytes(subscriptionKeys.p256dh),
@@ -2542,6 +2650,8 @@ function createSingleUserCloudflareWorker(buildConfig) {
         hooks: cfg.hooks || null,
         maxToolIterations: cfg.maxToolIterations,
         totalTimeoutMs: cfg.totalTimeoutMs,
+        // hook 的 ctx.writeState() 用它判断单条 value 的上限，和 PUT /client-state 同一个配置。
+        maxStateValueBytes: cfg.maxStateValueBytes,
         // 任务占位租期（默认 10 分钟，随 totalTimeoutMs 抬高）。
         claimLeaseMs: cfg.claimLeaseMs
       });
@@ -2575,6 +2685,10 @@ export {
   createMessagesHandler,
   createD1Adapter,
   createSingleUserServer,
+  WEB_PUSH_MAX_BODY_BYTES,
+  WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,
+  MAX_PUSH_PAYLOAD_BYTES,
+  measurePushPayload,
   createWebCryptoWebPush,
   createSingleUserCloudflareWorker
 };