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

package/dist/{chunk-ES2HUXYZ.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 });
@@ -1091,9 +1221,18 @@ function createScheduleMessageHandler(ctx) {
 }
 
 // src/server/lib/run-tick.js
+var DEFAULT_CLAIM_LEASE_MS = 10 * 60 * 1e3;
+var CLAIM_LEASE_MARGIN_MS = 2 * 60 * 1e3;
+function positiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function resolveClaimLeaseMs(ctx) {
+  return positiveNumber(ctx.claimLeaseMs) || Math.max(DEFAULT_CLAIM_LEASE_MS, positiveNumber(ctx.totalTimeoutMs) + CLAIM_LEASE_MARGIN_MS);
+}
 async function runScheduledTick(ctx) {
   const db = ctx.db;
   const masterKey = ctx.masterKey;
+  const claimLeaseMs = resolveClaimLeaseMs(ctx);
   const startTime = Date.now();
   const tasks = await db.getPendingTasks(50);
   const MAX_CONCURRENT = 8;
@@ -1101,19 +1240,29 @@ async function runScheduledTick(ctx) {
     totalTasks: tasks.length,
     successCount: 0,
     failedCount: 0,
+    claimSkippedTasks: 0,
     deletedOnceOffTasks: 0,
     updatedRecurringTasks: 0,
     failedTasks: []
   };
+  const supportsClaim = typeof db.claimTask === "function";
+  async function claimForThisTick(task) {
+    if (!supportsClaim) return true;
+    const leaseUntil = new Date(Date.now() + claimLeaseMs).toISOString();
+    return !!await db.claimTask(task.id, task.next_send_at, leaseUntil);
+  }
+  async function updateAndRelease(taskId, fields) {
+    return db.updateTaskById(taskId, supportsClaim ? { ...fields, lease_until: null } : fields);
+  }
   async function handleDeliveryFailure(task, reason) {
     results.failedCount++;
     try {
       if (task.retry_count >= 3) {
-        await db.updateTaskById(task.id, { status: "failed" });
+        await updateAndRelease(task.id, { status: "failed" });
         results.failedTasks.push({ taskId: task.id, reason, retryCount: task.retry_count, status: "permanently_failed" });
       } else {
         const nextRetryTime = new Date(Date.now() + (task.retry_count + 1) * 2 * 60 * 1e3);
-        await db.updateTaskById(task.id, { next_send_at: nextRetryTime.toISOString(), retry_count: task.retry_count + 1 });
+        await updateAndRelease(task.id, { next_send_at: nextRetryTime.toISOString(), retry_count: task.retry_count + 1 });
         results.failedTasks.push({ taskId: task.id, reason, retryCount: task.retry_count + 1, nextRetryAt: nextRetryTime.toISOString() });
       }
     } catch (updateError) {
@@ -1124,7 +1273,7 @@ async function runScheduledTick(ctx) {
     results.failedCount++;
     let markedSent = false;
     try {
-      await db.updateTaskById(task.id, { status: "sent", retry_count: 0 });
+      await updateAndRelease(task.id, { status: "sent", retry_count: 0 });
       markedSent = true;
     } catch (_markSentError) {
       markedSent = false;
@@ -1137,6 +1286,18 @@ async function runScheduledTick(ctx) {
     });
   }
   async function processTask(task) {
+    let claimed;
+    try {
+      claimed = await claimForThisTick(task);
+    } catch (error) {
+      results.failedCount++;
+      results.failedTasks.push({ taskId: task.id, reason: error.message || "\u4EFB\u52A1\u5360\u4F4D\u5931\u8D25", status: "claim_failed" });
+      return;
+    }
+    if (!claimed) {
+      results.claimSkippedTasks++;
+      return;
+    }
     let sendResult;
     try {
       sendResult = await processSingleMessage(task, { ...ctx, db, masterKey }, masterKey);
@@ -1162,7 +1323,7 @@ async function runScheduledTick(ctx) {
         } else if (decryptedPayload.recurrenceType === "weekly") {
           nextSendAt = new Date(currentSendAt.getTime() + 7 * 24 * 60 * 60 * 1e3);
         }
-        await db.updateTaskById(task.id, { next_send_at: nextSendAt.toISOString(), retry_count: 0 });
+        await updateAndRelease(task.id, { next_send_at: nextSendAt.toISOString(), retry_count: 0 });
         results.updatedRecurringTasks++;
       }
       results.successCount++;
@@ -1195,6 +1356,7 @@ async function runScheduledTick(ctx) {
     processedAt: (/* @__PURE__ */ new Date()).toISOString(),
     executionTime,
     details: {
+      claimSkippedTasks: results.claimSkippedTasks,
       deletedOnceOffTasks: results.deletedOnceOffTasks,
       updatedRecurringTasks: results.updatedRecurringTasks,
       failedTasks: results.failedTasks
@@ -1456,12 +1618,20 @@ var SQLITE_TABLE_SQL = `
     encrypted_payload TEXT NOT NULL,
     message_type TEXT NOT NULL CHECK (message_type IN ('fixed', 'prompted', 'auto', 'instant')),
     next_send_at TEXT NOT NULL,
+    lease_until TEXT,
     status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'failed')),
     retry_count INTEGER NOT NULL DEFAULT 0,
     created_at TEXT NOT NULL,
     updated_at TEXT NOT NULL
   )
 `;
+var SQLITE_MIGRATIONS = [
+  {
+    name: "add_lease_until",
+    sql: "ALTER TABLE scheduled_messages ADD COLUMN lease_until TEXT",
+    description: "Task claim lease (2.6.0)"
+  }
+];
 var SQLITE_INDEXES = [
   {
     name: "idx_pending_tasks_optimized",
@@ -1521,6 +1691,7 @@ var UPDATABLE_COLUMNS = /* @__PURE__ */ new Set([
   "encrypted_payload",
   "message_type",
   "next_send_at",
+  "lease_until",
   "status",
   "retry_count",
   "created_at",
@@ -1549,6 +1720,13 @@ var D1Adapter = class {
   async initSchema() {
     await this._db.prepare(SQLITE_TABLE_SQL).run();
     await this._db.prepare(CLIENT_STATE_TABLE_SQL).run();
+    for (const migration of SQLITE_MIGRATIONS) {
+      try {
+        await this._db.prepare(migration.sql).run();
+      } catch (error) {
+        if (!/duplicate column name/i.test(error.message || "")) throw error;
+      }
+    }
     const indexResults = [];
     for (const index of SQLITE_INDEXES) {
       try {
@@ -1566,7 +1744,7 @@ var D1Adapter = class {
       );
     }
     return {
-      columnsCreated: 10,
+      columnsCreated: 11,
       indexesCreated: indexResults.filter((r) => r.status === "success").length,
       indexesFailed: indexResults.filter((r) => r.status === "failed").length,
       columns: [],
@@ -1658,15 +1836,53 @@ var D1Adapter = class {
     return res.meta.changes > 0;
   }
   async getPendingTasks(limit = 50) {
+    const now = this._now();
     const res = await this._db.prepare(
       `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count
        FROM scheduled_messages
        WHERE status = 'pending' AND next_send_at <= ?
+         AND (lease_until IS NULL OR lease_until <= ?)
        ORDER BY next_send_at ASC
        LIMIT ?`
-    ).bind(this._now(), limit).all();
+    ).bind(now, now, limit).all();
     return res.results || [];
   }
+  /**
+   * 领取一条到点的任务：在 lease_until 上写下「这条归我管到什么时候」，
+   * 本次投递期间别的 tick 领不走它。
+   *
+   * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
+   * 任务列表要读它、循环任务推进下一次也要拿它当基准。
+   *
+   * 两个 tick 抢同一行时只有一个能改到行，另一个拿到 changes = 0，据此跳过。
+   * WHERE 里的两个条件各管一件事：
+   *   - lease_until 为空或已过期：没人正在跑这条。领了任务的 tick 中途没了
+   *     也不会把行焊死，租约到期后自然可以被接手。
+   *   - next_send_at 等于读这行时看到的值：读出来之后用户又改了排期的话，
+   *     这一跳就不该再按旧时刻发。
+   *
+   * 不加一个 'sending' 状态来表达「正在跑」：建表语句里 status 有
+   * CHECK (status IN ('pending','sent','failed'))，加值要重建表。
+   *
+   * expectedNextSendAt 按读到的原样比对，不做时区归一化——老部署里可能还留
+   * 着非归一化写法的行（如 +08:00 结尾），归一化后反而对不上，那条任务会永
+   * 远领不到。
+   *
+   * @param {number} taskId
+   * @param {string} expectedNextSendAt - 读这行时拿到的 next_send_at 原值
+   * @param {string|Date} leaseUntil - 租期末尾
+   * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、排期被改过、或行已不是 pending
+   */
+  async claimTask(taskId, expectedNextSendAt, leaseUntil) {
+    const expected = typeof expectedNextSendAt === "string" ? expectedNextSendAt : this._iso(expectedNextSendAt);
+    const res = await this._db.prepare(
+      `UPDATE scheduled_messages
+          SET lease_until = ?, updated_at = ?
+        WHERE id = ? AND status = 'pending' AND next_send_at = ?
+          AND (lease_until IS NULL OR lease_until <= ?)`
+    ).bind(this._iso(leaseUntil), this._now(), taskId, expected, this._now()).run();
+    return (res.meta.changes || 0) > 0;
+  }
   async listTasks(userId, opts = {}) {
     const { status = "all", limit = 20, offset = 0 } = opts;
     const conditions = ["user_id = ?"];
@@ -1710,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
@@ -1722,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）。
    */
@@ -1733,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)
       )
@@ -1901,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 } };
@@ -1942,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 });
   }
@@ -1996,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 } };
@@ -2092,7 +2262,7 @@ function createClientStateHandler(ctx) {
 }
 
 // src/server/lib/version.js
-var SERVER_VERSION = true ? "2.6.0-next.5" : "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([
@@ -2101,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) {
@@ -2168,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");
@@ -2182,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),
@@ -2455,7 +2649,11 @@ function createSingleUserCloudflareWorker(buildConfig) {
         // spreads its ctx into processSingleMessage, so these ride along.
         hooks: cfg.hooks || null,
         maxToolIterations: cfg.maxToolIterations,
-        totalTimeoutMs: cfg.totalTimeoutMs
+        totalTimeoutMs: cfg.totalTimeoutMs,
+        // hook 的 ctx.writeState() 用它判断单条 value 的上限，和 PUT /client-state 同一个配置。
+        maxStateValueBytes: cfg.maxStateValueBytes,
+        // 任务占位租期（默认 10 分钟，随 totalTimeoutMs 抬高）。
+        claimLeaseMs: cfg.claimLeaseMs
       });
     } catch (error) {
       console.error("[amsg single-user] scheduled(): tick failed:", error && error.message);
@@ -2487,6 +2685,10 @@ export {
   createMessagesHandler,
   createD1Adapter,
   createSingleUserServer,
+  WEB_PUSH_MAX_BODY_BYTES,
+  WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,
+  MAX_PUSH_PAYLOAD_BYTES,
+  measurePushPayload,
   createWebCryptoWebPush,
   createSingleUserCloudflareWorker
 };