@rei-standard/amsg-server 2.6.0-next.3 → 2.6.0-next.4

package/dist/{cloudflare-DlLTdCp0.d.ts → cloudflare-sVIPkSsf.d.ts}

@@ -1,4 +1,4 @@
-import { validateAvatarUrl, toUint8, concatBytes, base64UrlToBytes, extractAssistantMessage, buildSessionContext, assertValidDecision, extractToolCallsFromDecision, readReasoningContent, stripReasoningTags, buildReasoningPush, buildContentPush, normalizeVapidSubject } from '@rei-standard/amsg-shared';
+import { validateAvatarUrl, toUint8, concatBytes, base64UrlToBytes, chunkReasoningByUtf8Bytes, extractAssistantMessage, buildSessionContext, assertValidDecision, extractToolCallsFromDecision, readReasoningContent, stripReasoningTags, buildReasoningPush, buildContentPush, normalizeVapidSubject } from '@rei-standard/amsg-shared';
 
 /**
  * Validation utility library (SDK version)
@@ -864,6 +864,145 @@ function normalizeAiApiUrl(apiUrl) {
   return parsedUrl.toString();
 }
 
+/**
+ * client_state 大值透明分块（单用户/D1 专用；handlers/client-state.js 与
+ * lib/agentic-fire.js 的 readState 共用）。
+ *
+ * 存储格式（库内部实现细节，不进公开契约）：
+ *   - 单条 value ≤ STATE_CHUNK_SLICE_BYTES（200KB）→ 历史单行路径，存储字节级不变。
+ *   - 超过 → 服务端切片跨行：原 (namespace, key) 行的 value 写成纯文本 marker
+ *     （`\u001famsg-chunked\u001fv1\u001f<块数>`），切片本体逐片
+ *     encryptForStorage 后存进保留 namespace（`\u001famsg-chunks\u001f<原ns>`），
+ *     key 为 `<原key>\u001f<序号>`。写入方与读取方（客户端 / hook 作者）完全无感。
+ *   - marker 以 \u001f (Unit Separator) 开头；encryptForStorage 输出是
+ *     `hex:hex:hex`，永远不以控制字符开头，两种行值不会混淆。
+ *
+ * 读取完整性：块必须齐全，且每块 updated_at 与根行一致（同一次写入的印记）。
+ * 不满足（写到一半断了 / 新旧写交错）→ 该 key 视为不存在，读方走自己的兜底，
+ * 不抛错、不吐半截数据。
+ *
+ * 保留字符：namespace / key 里的 C0 控制字符（\u0000-\u001f）为库内部保留，
+ * handler 对用户输入逐条拒绝。内部分隔符选 \u001f 而不是 NUL，因为 SQLite 的
+ * LIKE 在 \u0000 处截断 pattern，前缀清理会失效。
+ */
+
+
+// 每个切片行的 plaintext 上限 = 历史单条上限，沿用已验证的行大小。
+const STATE_CHUNK_SLICE_BYTES = 200 * 1024;
+// 单条 value 总上限的默认值（工厂配置 maxStateValueBytes 可调）。
+const DEFAULT_MAX_STATE_VALUE_BYTES = 5 * 1024 * 1024;
+// 用户输入里的保留字符（namespace / key 逐条拒绝）。
+const INTERNAL_STATE_CHAR_RE = /[\u0000-\u001f]/;
+
+const SEP = '\u001f';
+const CHUNK_NS_PREFIX = `${SEP}amsg-chunks${SEP}`;
+const ROOT_MARKER_PREFIX = `${SEP}amsg-chunked${SEP}v1${SEP}`;
+
+/** 某个用户 namespace 的切片行所在的保留 namespace。 */
+function chunkNamespaceFor(namespace) {
+  return CHUNK_NS_PREFIX + namespace;
+}
+
+/** 第 index 片的存储 key。 */
+function chunkKeyFor(key, index) {
+  return `${key}${SEP}${index}`;
+}
+
+/** 清理某 key 全部切片行用的 key 前缀。 */
+function chunkKeyPrefixFor(key) {
+  return `${key}${SEP}`;
+}
+
+/** 分块根行的 value（纯文本 marker，不加密——不含用户数据）。 */
+function buildChunkedRootValue(chunkCount) {
+  return `${ROOT_MARKER_PREFIX}${chunkCount}`;
+}
+
+/**
+ * 严格解析根行 marker。不是 marker（普通密文 / 任意文本 / 计数非正整数）
+ * → null，调用方按普通单行处理。
+ *
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+function parseChunkedRootCount(value) {
+  if (typeof value !== 'string' || !value.startsWith(ROOT_MARKER_PREFIX)) return null;
+  const raw = value.slice(ROOT_MARKER_PREFIX.length);
+  if (!/^[1-9][0-9]*$/.test(raw)) return null;
+  return Number(raw);
+}
+
+/**
+ * 把超限 value 切成 ≤ STATE_CHUNK_SLICE_BYTES 的切片。切点在码点边界
+ * （chunkReasoningByUtf8Bytes 保证多字节字符 / emoji 代理对不被劈开，
+ * join('') === 原文）。
+ *
+ * @param {string} value
+ * @returns {string[]}
+ */
+function splitStateValue(value) {
+  return chunkReasoningByUtf8Bytes(value, STATE_CHUNK_SLICE_BYTES);
+}
+
+/**
+ * 把一个 namespace 的存储行解析成逻辑条目（GET /client-state 与 readState
+ * 共用）。普通行解密直读；分块根行按 marker 拼回。切片行查询是惰性的：
+ * 整个 namespace 没有分块根行时一次都不发。
+ *
+ * @param {Array<{ namespace: string, key: string, value: string, updated_at: number }>} rows
+ *   用户 namespace 的存储行（getClientState 返回值）。
+ * @param {() => Promise<Array<{ key: string, value: string, updated_at: number }>>} fetchChunkRows
+ *   取该 namespace 对应保留 namespace 的全部切片行（最多调用一次）。
+ * @param {(value: string) => Promise<string>} decryptValue
+ * @returns {Promise<Array<{ namespace: string, key: string, value: string, updatedAt: number }>>}
+ */
+async function resolveClientStateEntries(rows, fetchChunkRows, decryptValue) {
+  let chunkMap = null;
+  const loadChunks = async () => {
+    if (chunkMap === null) {
+      const chunkRows = await fetchChunkRows();
+      chunkMap = new Map(chunkRows.map((row) => [row.key, row]));
+    }
+    return chunkMap;
+  };
+
+  const entries = [];
+  for (const row of rows) {
+    const count = parseChunkedRootCount(row.value);
+    if (count === null) {
+      entries.push({
+        namespace: row.namespace,
+        key: row.key,
+        value: await decryptValue(row.value),
+        updatedAt: row.updated_at,
+      });
+      continue;
+    }
+
+    const map = await loadChunks();
+    const chunkRows = [];
+    let intact = true;
+    for (let i = 0; i < count; i++) {
+      const chunk = map.get(chunkKeyFor(row.key, i));
+      if (!chunk || chunk.updated_at !== row.updated_at) {
+        intact = false;
+        break;
+      }
+      chunkRows.push(chunk);
+    }
+    if (!intact) continue; // 写到一半断了 → 该 key 视为不存在
+
+    const parts = await Promise.all(chunkRows.map((chunk) => decryptValue(chunk.value)));
+    entries.push({
+      namespace: row.namespace,
+      key: row.key,
+      value: parts.join(''),
+      updatedAt: row.updated_at,
+    });
+  }
+  return entries;
+}
+
 /**
  * Server-side agentic fire loop.
  *
@@ -891,6 +1030,11 @@ function normalizeAiApiUrl(apiUrl) {
  * pushSubscription / vapid / masterKey (same rationale as instant's
  * SessionContext — a console.log(ctx) in a hook must not leak keys).
  *
+ * scratch：每次 fire 新建一个普通对象，onBeforeFire 的 fireCtx 与同一次
+ * fire 每轮的 sessionCtx 都持有同一个引用，hook 之间借它传工具上下文，
+ * 不用再自己维护 Map<sessionId, state>。fire 结束（finish / skip-push /
+ * 抛错 / 轮数超限）后随调用栈丢弃；库不读不写、不落库、不打日志。
+ *
  * Budget guards, both factory-level (ctx.maxToolIterations /
  * ctx.totalTimeoutMs) and per-fire (onBeforeFire may return
  * { messages, maxToolIterations?, totalTimeoutMs? } to override for one
@@ -1003,19 +1147,27 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     }
     if (!ctx.db || typeof ctx.db.getClientState !== 'function') return [];
     const rows = await ctx.db.getClientState(task.user_id, namespace);
-    return Promise.all(rows.map(async (row) => ({
-      namespace: row.namespace,
-      key: row.key,
-      value: await decryptFromStorage(row.value, userKey),
-      updatedAt: row.updated_at,
-    })));
+    // 分块存储的值在这里拼回原文（见 state-chunks.js）；块不齐全的 key 视为
+    // 不存在 —— hook 作者拿到的与客户端写入的一致，永远不会是半截数据。
+    return resolveClientStateEntries(
+      rows,
+      () => ctx.db.getClientState(task.user_id, chunkNamespaceFor(namespace)),
+      (value) => decryptFromStorage(value, userKey)
+    );
   };
 
+  // 单次 fire 的宿主便签：onBeforeFire 的 fireCtx 和同一次 fire 每轮的
+  // sessionCtx（onLLMOutput / executeToolCalls）拿到同一个对象引用，fire 结束
+  // （finish / skip-push / 抛错 / 轮数超限）随调用栈丢弃。库自己不读不写、
+  // 不落库、不打日志、不跨 fire 共享 —— 重试产生的新 fire 拿到的是新对象。
+  const scratch = {};
+
   const fireCtx = Object.freeze({
     task: buildHookTask(task, decryptedPayload),
     userId: task.user_id,
     readState,
     now: new Date(nowFn()),
+    scratch,
   });
 
   const before = await hooks.onBeforeFire(fireCtx);
@@ -1063,6 +1215,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       avatarUrl: decryptedPayload.avatarUrl || undefined,
       charId: decryptedPayload.charId,
       metadata: decryptedPayload.metadata,
+      scratch,
     });
 
     const decision = await hooks.onLLMOutput(sessionCtx);
@@ -2281,6 +2434,11 @@ const UPDATABLE_COLUMNS = new Set([
   'next_send_at', 'status', 'retry_count', 'created_at', 'updated_at'
 ]);
 
+// LIKE 前缀转义：用户 key 里的 % _ \ 不能变成通配符/转义符。
+function escapeLikePrefix(prefix) {
+  return prefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+
 class D1Adapter {
   /** @param {{ prepare: (sql: string) => any }} db - Cloudflare D1 binding */
   constructor(db) {
@@ -2493,6 +2651,10 @@ class D1Adapter {
    * 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 <= ?` 条件保证陈旧批次删不动更新写入的行。
+   *
    * Uses D1's batch() — one network round trip for the whole set (implicit
    * transaction). The client calls this endpoint inside its few-seconds
    * background window, so N sequential round trips could eat the whole
@@ -2501,9 +2663,11 @@ class D1Adapter {
    *
    * @param {string} userId
    * @param {Array<{ namespace: string, key: string, value: string, updatedAt: number }>} entries
-   * @returns {Promise<{ upserted: number, skipped: number }>}
+   * @param {Array<{ namespace: string, keyPrefix: string, updatedAt: number }>} [cleanups]
+   * @returns {Promise<{ upserted: number, skipped: number, outcomes: boolean[] }>}
+   *   `outcomes[i]` 对应 entries[i] 是否真的写入（changes > 0）。
    */
-  async upsertClientState(userId, entries) {
+  async upsertClientState(userId, entries, cleanups = []) {
     const UPSERT_SQL =
       `INSERT INTO client_state (user_id, namespace, key, value, updated_at)
        VALUES (?, ?, ?, ?, ?)
@@ -2511,28 +2675,37 @@ class D1Adapter {
          value = excluded.value,
          updated_at = excluded.updated_at
        WHERE excluded.updated_at >= client_state.updated_at`;
+    const CLEANUP_SQL =
+      `DELETE FROM client_state
+       WHERE user_id = ? AND namespace = ? AND key LIKE ? ESCAPE '\\' AND updated_at <= ?`;
+
+    const buildStatements = () => [
+      ...cleanups.map((c) =>
+        this._db.prepare(CLEANUP_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)
+      ),
+    ];
 
     let results;
     if (typeof this._db.batch === 'function') {
-      const statements = entries.map((entry) =>
-        this._db.prepare(UPSERT_SQL).bind(userId, entry.namespace, entry.key, entry.value, entry.updatedAt)
-      );
-      results = await this._db.batch(statements);
+      results = await this._db.batch(buildStatements());
     } else {
       results = [];
-      for (const entry of entries) {
-        results.push(
-          await this._db.prepare(UPSERT_SQL).bind(userId, entry.namespace, entry.key, entry.value, entry.updatedAt).run()
-        );
+      for (const stmt of buildStatements()) {
+        results.push(await stmt.run());
       }
     }
 
+    // cleanup 语句不计数：upserted/skipped/outcomes 只看 entries 对应的语句。
+    const outcomes = results.slice(cleanups.length).map((res) => res.meta.changes > 0);
     let upserted = 0;
     let skipped = 0;
-    for (const res of results) {
-      if (res.meta.changes > 0) upserted++; else skipped++;
+    for (const wrote of outcomes) {
+      if (wrote) upserted++; else skipped++;
     }
-    return { upserted, skipped };
+    return { upserted, skipped, outcomes };
   }
 
   /**
@@ -2749,6 +2922,12 @@ function createVapidPublicKeyHandler(ctx) {
  *   GET    /client-state?namespace=<ns>  one namespace's entries (decrypted, response re-encrypted)
  *   DELETE /client-state                 wipe every entry of this user
  *
+ * 单条 value 超过 200KB 时由服务端透明分块（见 lib/state-chunks.js）：写入时
+ * 切片跨行存储，GET / readState 返回拼好的原值，客户端与 hook 作者无感。
+ * 单条总上限默认 5MB，工厂配置 maxStateValueBytes 可调。批内某条超限/非法
+ * 只拒它自己：有拒绝时响应带 data.rejected 逐条给原因，全部成功时响应形状
+ * 与单值时代完全一致。
+ *
  * Auth & crypto follow the existing endpoints exactly: X-Client-Token is
  * all-or-nothing via resolveTenant, PUT bodies must be encrypted
  * (X-Payload-Encrypted / X-Encryption-Version), values are stored as
@@ -2756,11 +2935,6 @@ function createVapidPublicKeyHandler(ctx) {
  * ride the existing encrypted-response envelope.
  */
 
-
-// One value may hold a serialized state chunk, but must stay well under
-// D1's per-row limits — reject early with a clear error instead of an
-// opaque DB failure.
-const MAX_STATE_VALUE_BYTES = 200 * 1024;
 // "a few dozen entries in one background-window request" is the design
 // load; 200 bounds a single request with generous headroom.
 const MAX_STATE_ENTRIES_PER_REQUEST = 200;
@@ -2781,23 +2955,41 @@ function requireUserId(headers) {
   return { userId };
 }
 
-function validateEntry(entry, index) {
-  if (!isPlainObject(entry)) return err(400, 'INVALID_STATE_ENTRY', `entries[${index}] 必须是对象`);
+function rejectEntry(entry, index, code, message, extra) {
+  const rejection = { index, code, message, ...(extra || {}) };
+  if (entry && typeof entry === 'object') {
+    if (typeof entry.namespace === 'string') rejection.namespace = entry.namespace;
+    if (typeof entry.key === 'string') rejection.key = entry.key;
+  }
+  return rejection;
+}
+
+// 逐条校验：返回 null（合法）或拒绝对象（进 data.rejected，只拒这一条）。
+function validateEntry(entry, index, maxValueBytes) {
+  if (!isPlainObject(entry)) {
+    return rejectEntry(entry, index, 'INVALID_STATE_ENTRY', `entries[${index}] 必须是对象`);
+  }
   if (typeof entry.namespace !== 'string' || !entry.namespace.trim() || entry.namespace.length > MAX_NAMESPACE_CHARS) {
-    return err(400, 'INVALID_STATE_NAMESPACE', `entries[${index}].namespace 必须是 1-${MAX_NAMESPACE_CHARS} 字符的字符串`);
+    return rejectEntry(entry, index, 'INVALID_STATE_NAMESPACE', `entries[${index}].namespace 必须是 1-${MAX_NAMESPACE_CHARS} 字符的字符串`);
+  }
+  if (INTERNAL_STATE_CHAR_RE.test(entry.namespace)) {
+    return rejectEntry(entry, index, 'INVALID_STATE_NAMESPACE', `entries[${index}].namespace 不能包含控制字符（\\u0000-\\u001f 为库内部保留）`);
   }
   if (typeof entry.key !== 'string' || !entry.key.trim() || entry.key.length > MAX_KEY_CHARS) {
-    return err(400, 'INVALID_STATE_KEY', `entries[${index}].key 必须是 1-${MAX_KEY_CHARS} 字符的字符串`);
+    return rejectEntry(entry, index, 'INVALID_STATE_KEY', `entries[${index}].key 必须是 1-${MAX_KEY_CHARS} 字符的字符串`);
+  }
+  if (INTERNAL_STATE_CHAR_RE.test(entry.key)) {
+    return rejectEntry(entry, index, 'INVALID_STATE_KEY', `entries[${index}].key 不能包含控制字符（\\u0000-\\u001f 为库内部保留）`);
   }
   if (typeof entry.value !== 'string') {
-    return err(400, 'INVALID_STATE_VALUE', `entries[${index}].value 必须是字符串（宿主自行序列化）`);
+    return rejectEntry(entry, index, 'INVALID_STATE_VALUE', `entries[${index}].value 必须是字符串（宿主自行序列化）`);
   }
   const bytes = utf8.encode(entry.value).length;
-  if (bytes > MAX_STATE_VALUE_BYTES) {
-    return err(413, 'STATE_VALUE_TOO_LARGE', `entries[${index}].value 超过单条上限`, { index, key: entry.key, bytes, maxBytes: MAX_STATE_VALUE_BYTES });
+  if (bytes > maxValueBytes) {
+    return rejectEntry(entry, index, 'STATE_VALUE_TOO_LARGE', `entries[${index}].value 超过单条总上限`, { bytes, maxBytes: maxValueBytes });
   }
   if (!Number.isInteger(entry.updatedAt) || entry.updatedAt <= 0) {
-    return err(400, 'INVALID_STATE_UPDATED_AT', `entries[${index}].updatedAt 必须是正整数（epoch 毫秒）`);
+    return rejectEntry(entry, index, 'INVALID_STATE_UPDATED_AT', `entries[${index}].updatedAt 必须是正整数（epoch 毫秒）`);
   }
   return null;
 }
@@ -2840,24 +3032,82 @@ function createClientStateHandler(ctx) {
     if (entries.length > MAX_STATE_ENTRIES_PER_REQUEST) {
       return err(400, 'TOO_MANY_STATE_ENTRIES', `单次最多 ${MAX_STATE_ENTRIES_PER_REQUEST} 条`, { count: entries.length });
     }
+    const maxValueBytes = Number.isInteger(ctx.maxStateValueBytes) && ctx.maxStateValueBytes > 0
+      ? ctx.maxStateValueBytes
+      : DEFAULT_MAX_STATE_VALUE_BYTES;
+
+    // 逐条校验：坏条目只拒它自己（进 rejected），好条目照常入库。
+    const accepted = [];
+    const rejected = [];
     for (let i = 0; i < entries.length; i++) {
-      const invalid = validateEntry(entries[i], i);
-      if (invalid) return invalid;
+      const rejection = validateEntry(entries[i], i, maxValueBytes);
+      if (rejection) rejected.push(rejection); else accepted.push(entries[i]);
     }
 
     if (typeof db.upsertClientState !== 'function') {
       return err(501, 'CLIENT_STATE_NOT_SUPPORTED', '当前数据库适配器不支持 client_state');
     }
 
-    const encryptedEntries = await Promise.all(entries.map(async (entry) => ({
-      namespace: entry.namespace,
-      key: entry.key,
-      value: await encryptForStorage(entry.value, userKey),
-      updatedAt: entry.updatedAt,
-    })));
+    // 展开成物理行：小值 1 行（历史路径，字节级不变），大值 = 根 marker 行 +
+    // 保留 namespace 里的 N 个加密切片行。每条 accepted 条目都配一条 cleanup
+    // （同一 batch 里先删后写），把这个 key 旧写入留下的切片清干净 —— 覆盖写
+    // 变小 / 缩块都不留尾巴；陈旧批次的 cleanup 因 updated_at 条件删不动新行。
+    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 (utf8.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) {
+        // 逻辑计数：一条 entry 的 upserted/skipped 看它的根行（切片行不计数）。
+        for (const rootIndex of rootRowIndexes) {
+          if (result.outcomes[rootIndex]) upserted++; else skipped++;
+        }
+      } else {
+        // 自定义 adapter 只回老形状 { upserted, skipped } 时按物理行计数兜底。
+        upserted = result.upserted;
+        skipped = result.skipped;
+      }
+    }
 
-    const { upserted, skipped } = await db.upsertClientState(userId, encryptedEntries);
-    return { status: 200, body: { success: true, data: { upserted, skipped } } };
+    const data = { upserted, skipped };
+    if (rejected.length > 0) data.rejected = rejected;
+    return { status: 200, body: { success: true, data } };
   }
 
   async function GET(url, headers) {
@@ -2871,6 +3121,9 @@ function createClientStateHandler(ctx) {
 
     const namespace = new URL(url, 'https://dummy').searchParams.get('namespace') || '';
     if (!namespace.trim()) return err(400, 'NAMESPACE_REQUIRED', '必须提供 namespace 查询参数');
+    if (INTERNAL_STATE_CHAR_RE.test(namespace)) {
+      return err(400, 'INVALID_STATE_NAMESPACE', 'namespace 不能包含控制字符（\\u0000-\\u001f 为库内部保留）');
+    }
 
     if (typeof db.getClientState !== 'function') {
       return err(501, 'CLIENT_STATE_NOT_SUPPORTED', '当前数据库适配器不支持 client_state');
@@ -2878,12 +3131,12 @@ function createClientStateHandler(ctx) {
 
     const userKey = await deriveUserEncryptionKey(userId, masterKey);
     const rows = await db.getClientState(userId, namespace);
-    const decrypted = await Promise.all(rows.map(async (row) => ({
-      namespace: row.namespace,
-      key: row.key,
-      value: await decryptFromStorage(row.value, userKey),
-      updatedAt: row.updated_at,
-    })));
+    // 分块存储的值在这里拼回原文；块不齐全的 key 视为不存在（不抛错）。
+    const decrypted = await resolveClientStateEntries(
+      rows,
+      () => db.getClientState(userId, chunkNamespaceFor(namespace)),
+      (value) => decryptFromStorage(value, userKey)
+    );
 
     const encryptedResponse = await encryptPayload({ namespace, entries: decrypted }, userKey);
     return { status: 200, body: { success: true, encrypted: true, version: 1, data: encryptedResponse } };
@@ -2909,6 +3162,57 @@ function createClientStateHandler(ctx) {
   return { PUT, GET, DELETE };
 }
 
+/**
+ * 构建期注入的包版本。tsup 用 define 把 __AMSG_SERVER_VERSION__ 替换成
+ * package.json 的 version（见 tsup.config.js），发布产物里是真实版本号；
+ * 直接跑 src（node --test / 本地调试）没有这个替换，typeof 守卫落到
+ * '0.0.0-dev'。
+ */
+/* global __AMSG_SERVER_VERSION__ */
+const SERVER_VERSION =
+  typeof __AMSG_SERVER_VERSION__ !== 'undefined' ? __AMSG_SERVER_VERSION__ : '0.0.0-dev';
+
+/**
+ * Handler: capabilities
+ *
+ * GET /capabilities → { success, serverVersion, features }。前端用它做特性
+ * 探测：worker 部署版本落后时，新链路只是「探测不到」（而不是静默失效），
+ * 设置页可以据此提示重新部署 worker。老部署没有这个路由 → 404，客户端 SDK
+ * 的 getCapabilities() 把 404 归一成 null。
+ *
+ * features 表达「这份代码支持什么」，随版本静态演进追加；不反映部署配置——
+ * 例如 'agentic-hooks' 表示该版本认识 fire-time hooks，宿主配没配 hooks 不
+ * 影响它出现。
+ *
+ * 鉴权与 /vapid-public-key 同待遇：走 resolveTenant，配置 serverToken 后同样
+ * 要求 X-Client-Token。
+ */
+
+
+const SERVER_FEATURES = Object.freeze([
+  'client-state',
+  'client-state-chunking',
+  'client-state-partial-failure',
+  'agentic-hooks',
+  'agentic-scratch',
+  'vapid-public-key',
+]);
+
+function createCapabilitiesHandler(ctx) {
+  async function GET(url, headers) {
+    const effectiveHeaders = headers || url || {};
+    const tenantResult = await ctx.tenantManager.resolveTenant(effectiveHeaders);
+    if (!tenantResult.ok) {
+      return tenantResult.error;
+    }
+    return {
+      status: 200,
+      body: { success: true, serverVersion: SERVER_VERSION, features: [...SERVER_FEATURES] },
+    };
+  }
+  return { GET };
+}
+
 /**
  * Single-user ReiStandard server assembly.
  *
@@ -2929,6 +3233,7 @@ function createClientStateHandler(ctx) {
  *   replay the schedule-time frozen prompt (legacy behavior, unchanged).
  * @param {number} [config.maxToolIterations] - factory default LLM-round cap for the agentic loop (default 5).
  * @param {number} [config.totalTimeoutMs] - factory default wall-time ceiling for the agentic loop (default 240000).
+ * @param {number} [config.maxStateValueBytes] - client_state 单条 value 的总上限（默认 5MB）。超过 200KB 的值由服务端透明分块存储（见 lib/state-chunks.js）。
  * @returns {{ handlers: Object, ctx: Object }}
  */
 
@@ -2957,7 +3262,8 @@ function createSingleUserServer(config) {
     // the agentic path too.
     hooks: config.hooks || null,
     maxToolIterations: config.maxToolIterations,
-    totalTimeoutMs: config.totalTimeoutMs
+    totalTimeoutMs: config.totalTimeoutMs,
+    maxStateValueBytes: config.maxStateValueBytes
   };
 
   return {
@@ -2970,7 +3276,8 @@ function createSingleUserServer(config) {
       cancelMessage: createCancelMessageHandler(ctx),
       messages: createMessagesHandler(ctx),
       vapidPublicKey: createVapidPublicKeyHandler(ctx),
-      clientState: createClientStateHandler(ctx)
+      clientState: createClientStateHandler(ctx),
+      capabilities: createCapabilitiesHandler(ctx)
     }
   };
 }
@@ -3319,6 +3626,7 @@ function createWebCryptoWebPush(vapid = {}, { ttl = SCHEDULED_DEFAULT_TTL } = {}
  *   DELETE /cancel-message  → delete
  *   GET  /vapid-public-key  → this worker's VAPID public key (for the frontend's
  *                             Web Push subscription); 503 if VAPID_PUBLIC_KEY unset
+ *   GET  /capabilities      → { serverVersion, features }（特性探测；老部署无此路由 → 404）
  *   PUT  /client-state      → batch upsert client state (last-write-wins on updatedAt)
  *   GET  /client-state      → read one namespace's entries (?namespace=<ns>)
  *   DELETE /client-state    → wipe this user's client state
@@ -3426,6 +3734,8 @@ function createSingleUserCloudflareWorker(buildConfig) {
         result = await server.handlers.cancelMessage.DELETE(url, headers);
       } else if (method === 'GET' && pathname.endsWith('/vapid-public-key')) {
         result = await server.handlers.vapidPublicKey.GET(url, headers);
+      } else if (method === 'GET' && pathname.endsWith('/capabilities')) {
+        result = await server.handlers.capabilities.GET(url, headers);
       } else if (method === 'PUT' && pathname.endsWith('/client-state')) {
         result = await server.handlers.clientState.PUT(headers, await request.text());
       } else if (method === 'GET' && pathname.endsWith('/client-state')) {

package/dist/cloudflare.cjs

@@ -8,7 +8,7 @@
 
 
 
-var _chunkL7WMM33Qcjs = require('./chunk-L7WMM33Q.cjs');
+var _chunkREX5MCEZcjs = require('./chunk-REX5MCEZ.cjs');
 
 
 
@@ -19,4 +19,4 @@ var _chunkL7WMM33Qcjs = require('./chunk-L7WMM33Q.cjs');
 
 
 
-exports.createD1Adapter = _chunkL7WMM33Qcjs.createD1Adapter; exports.createSingleUserCloudflareWorker = _chunkL7WMM33Qcjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunkL7WMM33Qcjs.createSingleUserServer; exports.createWebCryptoWebPush = _chunkL7WMM33Qcjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunkL7WMM33Qcjs.decryptFromStorage; exports.decryptPayload = _chunkL7WMM33Qcjs.decryptPayload; exports.deriveUserEncryptionKey = _chunkL7WMM33Qcjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunkL7WMM33Qcjs.encryptForStorage; exports.runScheduledTick = _chunkL7WMM33Qcjs.runScheduledTick;
+exports.createD1Adapter = _chunkREX5MCEZcjs.createD1Adapter; exports.createSingleUserCloudflareWorker = _chunkREX5MCEZcjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunkREX5MCEZcjs.createSingleUserServer; exports.createWebCryptoWebPush = _chunkREX5MCEZcjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunkREX5MCEZcjs.decryptFromStorage; exports.decryptPayload = _chunkREX5MCEZcjs.decryptPayload; exports.deriveUserEncryptionKey = _chunkREX5MCEZcjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunkREX5MCEZcjs.encryptForStorage; exports.runScheduledTick = _chunkREX5MCEZcjs.runScheduledTick;

package/dist/cloudflare.d.cts

@@ -1,2 +1,2 @@
-export { f as createD1Adapter, h as createSingleUserCloudflareWorker, j as createSingleUserServer, k as createWebCryptoWebPush, l as decryptFromStorage, m as decryptPayload, n as deriveUserEncryptionKey, o as encryptForStorage, r as runScheduledTick } from './cloudflare-DlLTdCp0.cjs';
+export { f as createD1Adapter, h as createSingleUserCloudflareWorker, j as createSingleUserServer, k as createWebCryptoWebPush, l as decryptFromStorage, m as decryptPayload, n as deriveUserEncryptionKey, o as encryptForStorage, r as runScheduledTick } from './cloudflare-sVIPkSsf.cjs';
 import '@rei-standard/amsg-shared';

package/dist/cloudflare.d.ts

@@ -1,2 +1,2 @@
-export { f as createD1Adapter, h as createSingleUserCloudflareWorker, j as createSingleUserServer, k as createWebCryptoWebPush, l as decryptFromStorage, m as decryptPayload, n as deriveUserEncryptionKey, o as encryptForStorage, r as runScheduledTick } from './cloudflare-DlLTdCp0.js';
+export { f as createD1Adapter, h as createSingleUserCloudflareWorker, j as createSingleUserServer, k as createWebCryptoWebPush, l as decryptFromStorage, m as decryptPayload, n as deriveUserEncryptionKey, o as encryptForStorage, r as runScheduledTick } from './cloudflare-sVIPkSsf.js';
 import '@rei-standard/amsg-shared';

package/dist/cloudflare.mjs

@@ -8,7 +8,7 @@ import {
   deriveUserEncryptionKey,
   encryptForStorage,
   runScheduledTick
-} from "./chunk-PPPWETND.mjs";
+} from "./chunk-OVGQHTSE.mjs";
 export {
   createD1Adapter,
   createSingleUserCloudflareWorker,