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

package/dist/{cloudflare-sVIPkSsf.d.cts → cloudflare-qy1YWQcp.d.cts}

@@ -1009,7 +1009,7 @@ async function resolveClientStateEntries(rows, fetchChunkRows, decryptValue) {
  * When the host configures fire-time hooks, an LLM task stops replaying
  * the completePrompt frozen at schedule time. At fire time instead:
  *
- *   onBeforeFire(fireCtx) → fresh messages (may read client_state)
+ *   onBeforeFire(fireCtx) → fresh messages (may read client_state) | { skip: true }
  *     → callLlm → onLLMOutput(sessionCtx) → decision
  *         ├─ 'finish'       → push decision.pushPayloads, done
  *         ├─ 'skip-push'    → record, done (task counts as delivered)
@@ -1073,7 +1073,13 @@ function taskNeedsLlm(decryptedPayload) {
   return false;
 }
 
-/** Frozen, credential-free view of the task for hook authors. */
+/**
+ * Frozen, credential-free view of the task for hook authors.
+ *
+ * nextSendAt 是这条任务原本的触发时刻。run-tick 领取任务时写的是 lease_until，
+ * next_send_at 那一列不动，所以这里给出去的和库里的是同一个值——宿主拿它当
+ * 时间锚点（窗口判断、缓存键）时对得上。
+ */
 function buildHookTask(task, decryptedPayload) {
   const safe = {};
   for (const [key, value] of Object.entries(decryptedPayload)) {
@@ -1100,7 +1106,7 @@ function normalizeBeforeFireResult(result) {
     };
   }
   throw new TypeError(
-    'AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs? } | null'
+    'AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs? } | { skip: true } | null'
   );
 }
 
@@ -1127,7 +1133,11 @@ function firstPositiveNumber(values, fallback) {
  * @param {string} args.userKey - per-user storage key (for readState decryption)
  * @param {Object} args.ctx - processor ctx ({ db, webpush, vapid, hooks, maxToolIterations, totalTimeoutMs })
  * @returns {Promise<{ handled: false } | { handled: true, result: { success: true, messagesSent: number, status: 'finished'|'skipped', iterations: number } }>}
- *   `handled: false` → caller falls back to the legacy frozen-prompt path.
+ *   `handled: false` → caller falls back to the legacy frozen-prompt path
+ *   (onBeforeFire returned null).
+ *   `onBeforeFire` may also return `{ skip: true }` to complete the fire
+ *   before the first LLM call → `status: 'skipped', iterations: 0`, same
+ *   success handling as the post-LLM skip-push path.
  *   Failures (timeout / loop exceeded / config errors) throw — the caller's
  *   existing error handling turns them into task retry/failure.
  */
@@ -1173,6 +1183,14 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
   const before = await hooks.onBeforeFire(fireCtx);
   if (before == null) return { handled: false };
 
+  // Pre-LLM skip: the host judged this fire moot before generation (e.g. the
+  // conversation moved on after the task was scheduled). Shaped exactly like
+  // the post-LLM 'skipped' result, so run-tick's success handling (delete
+  // once-off / advance recurrence) applies unchanged — and zero tokens spent.
+  if (typeof before === 'object' && before.skip === true) {
+    return { handled: true, result: { success: true, messagesSent: 0, status: 'skipped', iterations: 0 } };
+  }
+
   const normalized = normalizeBeforeFireResult(before);
   const maxToolIterations = firstPositiveInt(
     [normalized.maxToolIterations, ctx.maxToolIterations],
@@ -1410,7 +1428,9 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
     // needs the LLM, offer the agentic path first. onBeforeFire → null
     // falls straight through to the frozen-prompt chain below, and
     // deployments without hooks never enter this branch — legacy behavior
-    // is byte-identical.
+    // is byte-identical. onBeforeFire → { skip: true } completes the fire
+    // here as a zero-push success (no LLM call, no frozen-prompt fallback):
+    // use it when the host can tell at fire time the message is moot.
     if (ctx.hooks && typeof ctx.hooks.onBeforeFire === 'function' && taskNeedsLlm(decryptedPayload)) {
       const agentic = await runAgenticFire({ task, decryptedPayload, userKey, ctx });
       if (agentic.handled) return agentic.result;
@@ -1870,14 +1890,47 @@ function createScheduleMessageHandler(ctx) {
  * Extracted verbatim from the send-notifications handler so both the HTTP
  * handler (multi-tenant) and the CF scheduled() path (single-user) share it.
  *
- * @param {Object} ctx - { db, masterKey, vapid, webpush }
+ * 每个 tick 是一次独立调用（cron 每分钟一跳，不会因为上一跳还没跑完就跳过
+ * 这一跳），而一次投递「组 prompt → 调 LLM → 跑工具 → 推送」可能要几分钟。
+ * 所以每条任务开跑前先占位：在这一行的 lease_until 上写下「归我管到什么时
+ * 候」，本次投递期间别的 tick 领不走它。占位失败（0 行）说明别人先领走了，
+ * 直接跳过。
+ *
+ * 租约写在自己的列上，next_send_at 全程不动——那一列是用户设的触发时刻，
+ * 任务列表要读它、循环任务推进下一次也要拿它当基准。投递收尾时把租约放掉，
+ * 这条任务立刻可以被下一跳接手（失败重试的退避只有 2 分钟，比租期短得多，
+ * 不放掉的话退避就白设了）。
+ *
+ * 领了任务的 tick 中途没了（Worker 被回收之类）就没人来放租约，这条任务要
+ * 等租约到期才会被接手——这是租约本身的代价，把租期设得比最慢的一次投递长
+ * 一点就行。
+ *
+ * @param {Object} ctx - { db, masterKey, vapid, webpush, claimLeaseMs? }
  * @returns {Promise<Object>} summary { totalTasks, successCount, failedCount, processedAt, executionTime, details }
  */
 
 
+// 占位租期：要盖住最慢的一次投递。老链路单次 LLM 调用上限 300s，agentic 链路
+// 整链默认 240s，再留出推送节奏的余量。
+const DEFAULT_CLAIM_LEASE_MS = 10 * 60 * 1000;
+// 宿主把 totalTimeoutMs 调大时租期跟着抬，别让下一跳在投递还没跑完时就把行
+// 捞回去。（onBeforeFire 里按次放宽的预算这里看不到，那种情况请显式设
+// ctx.claimLeaseMs。）
+const CLAIM_LEASE_MARGIN_MS = 2 * 60 * 1000;
+
+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);
@@ -1887,20 +1940,42 @@ async function runScheduledTick(ctx) {
     totalTasks: tasks.length,
     successCount: 0,
     failedCount: 0,
+    claimSkippedTasks: 0,
     deletedOnceOffTasks: 0,
     updatedRecurringTasks: 0,
     failedTasks: []
   };
 
+  // 适配器没实现 claimTask（自定义适配器）→ 退回不占位的老行为：跑得动，只是
+  // 超过一跳间隔的慢任务仍可能被下一跳重复触发。
+  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));
+  }
+
+  /**
+   * 投递收尾时写库，顺手把租约放掉。占位之后的每一次写库都要走这里，漏掉
+   * 一条那条任务就得等租约到期才动得了。
+   *
+   * 没实现 claimTask 的适配器不会有 lease_until 这一列，就别往它的
+   * updateTaskById 里塞这个字段了。
+   */
+  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 * 1000);
-        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) {
@@ -1912,7 +1987,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;
@@ -1926,6 +2001,22 @@ async function runScheduledTick(ctx) {
   }
 
   async function processTask(task) {
+    let claimed;
+    try {
+      claimed = await claimForThisTick(task);
+    } catch (error) {
+      // 占位这一步就出错，说明库有问题——此时不知道别人有没有在跑这条，宁可
+      // 不发。行还是 pending，下一跳会重新捞。
+      results.failedCount++;
+      results.failedTasks.push({ taskId: task.id, reason: error.message || '任务占位失败', status: 'claim_failed' });
+      return;
+    }
+    if (!claimed) {
+      // 另一个 tick 已经领走了这条，本次什么都不做。
+      results.claimSkippedTasks++;
+      return;
+    }
+
     let sendResult;
     try {
       sendResult = await processSingleMessage(task, { ...ctx, db, masterKey }, masterKey);
@@ -1948,13 +2039,14 @@ async function runScheduledTick(ctx) {
         results.deletedOnceOffTasks++;
       } else {
         let nextSendAt;
+        // 以这条任务原本的触发时刻为基准往后推。
         const currentSendAt = new Date(task.next_send_at);
         if (decryptedPayload.recurrenceType === 'daily') {
           nextSendAt = new Date(currentSendAt.getTime() + 24 * 60 * 60 * 1000);
         } else if (decryptedPayload.recurrenceType === 'weekly') {
           nextSendAt = new Date(currentSendAt.getTime() + 7 * 24 * 60 * 60 * 1000);
         }
-        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++;
       }
 
@@ -1993,6 +2085,7 @@ async function runScheduledTick(ctx) {
     processedAt: new Date().toISOString(),
     executionTime,
     details: {
+      claimSkippedTasks: results.claimSkippedTasks,
       deletedOnceOffTasks: results.deletedOnceOffTasks,
       updatedRecurringTasks: results.updatedRecurringTasks,
       failedTasks: results.failedTasks
@@ -2302,7 +2395,14 @@ function createMessagesHandler(ctx) {
         status: task.status,
         retryCount: task.retry_count,
         createdAt: task.created_at,
-        updatedAt: task.updated_at
+        updatedAt: task.updated_at,
+        // Character ownership / client-side task identity, pulled from the
+        // scheduling host's metadata so it can filter tasks by character
+        // (contactName can collide across characters). Only these two
+        // metadata fields are surfaced — the rest of metadata may hold
+        // host-private data and stays server-side. Absent → null.
+        charId: decrypted.metadata?.charId ?? null,
+        clientTaskId: decrypted.metadata?.amsgClientTaskId ?? null
       };
     }));
 
@@ -2348,6 +2448,7 @@ const 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,
@@ -2355,6 +2456,18 @@ const SQLITE_TABLE_SQL = `
   )
 `;
 
+/**
+ * 建表语句用的是 CREATE TABLE IF NOT EXISTS，已经存在的表不会被改动，所以
+ * 后加的列要单独补。initSchema 每次都会跑一遍，列已经在了就跳过。
+ */
+const SQLITE_MIGRATIONS = [
+  {
+    name: 'add_lease_until',
+    sql: 'ALTER TABLE scheduled_messages ADD COLUMN lease_until TEXT',
+    description: 'Task claim lease (2.6.0)'
+  }
+];
+
 const SQLITE_INDEXES = [
   {
     name: 'idx_pending_tasks_optimized',
@@ -2431,7 +2544,7 @@ const CLIENT_STATE_TABLE_SQL = `
 // from ever turning a caller-supplied key into interpolated SQL.
 const UPDATABLE_COLUMNS = new Set([
   'user_id', 'uuid', 'encrypted_payload', 'message_type',
-  'next_send_at', 'status', 'retry_count', 'created_at', 'updated_at'
+  'next_send_at', 'lease_until', 'status', 'retry_count', 'created_at', 'updated_at'
 ]);
 
 // LIKE 前缀转义：用户 key 里的 % _ \ 不能变成通配符/转义符。
@@ -2464,6 +2577,17 @@ class D1Adapter {
     await this._db.prepare(SQLITE_TABLE_SQL).run();
     await this._db.prepare(CLIENT_STATE_TABLE_SQL).run();
 
+    // SQLite 的 ALTER TABLE 没有 ADD COLUMN IF NOT EXISTS，列已经在了就会
+    // 报 duplicate column name。那正是「这一步不用做」的意思，跳过即可；
+    // 其他错误照常抛出去。
+    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 {
@@ -2484,7 +2608,7 @@ class D1Adapter {
     }
 
     return {
-      columnsCreated: 10,
+      columnsCreated: 11,
       indexesCreated: indexResults.filter((r) => r.status === 'success').length,
       indexesFailed: indexResults.filter((r) => r.status === 'failed').length,
       columns: [],
@@ -2591,16 +2715,57 @@ class D1Adapter {
   }
 
   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 = ?'];
@@ -3640,6 +3805,10 @@ function createWebCryptoWebPush(vapid = {}, { ttl = SCHEDULED_DEFAULT_TTL } = {}
  * config to let scheduled AI tasks assemble their prompt and run a server-side
  * tool loop at fire time. Omit them and AI tasks replay the schedule-time frozen
  * prompt exactly as before. See lib/agentic-fire.js.
+ *
+ * scheduled() 每次触发都会先给任务占位（在行的 lease_until 上写租约），同一
+ * 条任务不会被相邻两跳重复触发（见 lib/run-tick.js）。租期默认 10 分钟，可以
+ * 用 config 里的 `claimLeaseMs` 调整。
  */
 
 
@@ -3772,7 +3941,9 @@ 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,
+        // 任务占位租期（默认 10 分钟，随 totalTimeoutMs 抬高）。
+        claimLeaseMs: cfg.claimLeaseMs
       });
     } catch (error) {
       console.error('[amsg single-user] scheduled(): tick failed:', error && error.message);