@rei-standard/amsg-server 2.6.0-next.9 → 3.0.0

package/dist/cloudflare-kUY6z-k5.d.cts

@@ -1,4460 +0,0 @@
-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)
- * ReiStandard SDK v2.0.1
- */
-
-
-/**
- * Validate ISO 8601 date string.
- * @param {string} dateString
- * @returns {boolean}
- */
-function isValidISO8601(dateString) {
-  const date = new Date(dateString);
-  return date instanceof Date && !isNaN(date.getTime());
-}
-
-/**
- * Validate URL format.
- * @param {string} urlString
- * @returns {boolean}
- */
-function isValidUrl(urlString) {
-  try {
-    new URL(urlString);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Validate UUID format.
- * @param {string} uuid
- * @returns {boolean}
- */
-function isValidUUID(uuid) {
-  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  return uuidRegex.test(uuid);
-}
-
-/**
- * Validate UUID v4 format.
- * @param {string} uuid
- * @returns {boolean}
- */
-function isValidUUIDv4(uuid) {
-  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-  return uuidV4Regex.test(uuid);
-}
-
-const VALID_LLM_MESSAGE_ROLES = new Set(['system', 'user', 'assistant', 'tool']);
-
-const SPLIT_PATTERN_MAX_LENGTH = 200;
-const SPLIT_PATTERN_MAX_ITEMS = 10;
-
-/**
- * Validate the optional `splitPattern` field (amsg-server scheduled tasks
- * only; amsg-instant 0.8.0 dropped its request-level `splitPattern`).
- * Accepts `string`, `string[]`, or absent/null. Returns an error message
- * string, or null when valid.
- *
- * Limits (per-item length ≤ 200, array ≤ 10 items, must compile via
- * `new RegExp(item)`) are an **input-size guard**, NOT a ReDoS defense —
- * a 6-character pattern like `(a+)+$` is enough to trigger catastrophic
- * backtracking. The real backstop is Worker / runtime CPU limits + the
- * fact that splitPattern is stored under the user's own encrypted task
- * and matched against output from the user's own LLM API key, so the
- * blast radius is self-inflicted only (no cross-tenant attack surface).
- *
- * @param {unknown} value
- * @returns {string | null}
- */
-function validateSplitPattern(value) {
-  if (value === undefined || value === null) return null;
-  const isArray = Array.isArray(value);
-  const items = isArray ? value : [value];
-  if (isArray && items.length === 0) return null;          // empty array = use default
-  if (items.length > SPLIT_PATTERN_MAX_ITEMS) {
-    return `splitPattern 数组最多 ${SPLIT_PATTERN_MAX_ITEMS} 项`;
-  }
-  for (let i = 0; i < items.length; i++) {
-    const s = items[i];
-    const label = isArray ? `splitPattern[${i}]` : 'splitPattern';
-    if (typeof s !== 'string') return `${label} 必须是字符串`;
-    if (s.length > SPLIT_PATTERN_MAX_LENGTH) {
-      return `${label} 不能超过 ${SPLIT_PATTERN_MAX_LENGTH} 字符`;
-    }
-    try { new RegExp(s); }
-    catch (_) { return `${label} 不是有效正则表达式`; }
-  }
-  return null;
-}
-
-/**
- * Validate an OpenAI-style messages array. Same shape contract as
- * `@rei-standard/amsg-instant` (kept in lockstep on purpose — both packages
- * end up forwarding this to the same LLM body).
- *
- * @param {unknown} messages
- * @returns {string | null}   Error message, or null if valid.
- */
-function validateLlmMessagesArray(messages) {
-  if (!Array.isArray(messages) || messages.length === 0) {
-    return 'messages must be a non-empty array';
-  }
-  for (let i = 0; i < messages.length; i++) {
-    const m = messages[i];
-    if (!m || typeof m !== 'object' || Array.isArray(m)) {
-      return `messages[${i}] must be an object`;
-    }
-    if (!VALID_LLM_MESSAGE_ROLES.has(m.role)) {
-      return `messages[${i}].role must be one of system / user / assistant / tool`;
-    }
-    if (typeof m.content === 'string') {
-      if (!m.content) return `messages[${i}].content must be a non-empty string`;
-    } else if (Array.isArray(m.content)) {
-      if (m.content.length === 0) return `messages[${i}].content array must be non-empty`;
-      // Element schema is intentionally not enforced — passed through to LLM as-is.
-    } else {
-      return `messages[${i}].content must be a non-empty string or a non-empty array`;
-    }
-  }
-  return null;
-}
-
-/**
- * Validate the schedule-message request payload.
- *
- * @param {Object} payload
- * @returns {{ valid: boolean, errorCode?: string, errorMessage?: string, details?: Object }}
- */
-function validateScheduleMessagePayload(payload) {
-  if (!payload.contactName || typeof payload.contactName !== 'string') {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { missingFields: ['contactName'] } };
-  }
-
-  if (!payload.messageType || !['fixed', 'prompted', 'auto', 'instant'].includes(payload.messageType)) {
-    return { valid: false, errorCode: 'INVALID_MESSAGE_TYPE', errorMessage: '消息类型无效', details: { providedType: payload.messageType, allowedTypes: ['fixed', 'prompted', 'auto', 'instant'] } };
-  }
-
-  if (!payload.firstSendTime || !isValidISO8601(payload.firstSendTime)) {
-    return { valid: false, errorCode: 'INVALID_TIMESTAMP', errorMessage: '时间格式无效', details: { field: 'firstSendTime' } };
-  }
-
-  if (payload.firstSendTime && new Date(payload.firstSendTime) <= new Date()) {
-    return { valid: false, errorCode: 'INVALID_TIMESTAMP', errorMessage: '时间必须在未来', details: { field: 'firstSendTime', reason: 'must be in the future' } };
-  }
-
-  if (!payload.pushSubscription || typeof payload.pushSubscription !== 'object') {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { missingFields: ['pushSubscription'] } };
-  }
-
-  if (payload.recurrenceType && !['none', 'daily', 'weekly'].includes(payload.recurrenceType)) {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['recurrenceType'] } };
-  }
-
-  if (
-    payload.maxTokens !== undefined &&
-    payload.maxTokens !== null &&
-    (!Number.isInteger(payload.maxTokens) || payload.maxTokens <= 0)
-  ) {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['maxTokens'] } };
-  }
-
-  if (payload.messageType === 'fixed') {
-    if (!payload.userMessage) {
-      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { missingFields: ['userMessage (required for fixed type)'] } };
-    }
-  }
-
-  // ─── Prompt schema (shared by prompted / auto / instant AI configs) ──
-  //
-  // Callers provide *exactly one of* `completePrompt` (string) or `messages`
-  // (OpenAI-style array). Same contract as @rei-standard/amsg-instant; the
-  // server's LLM path forwards either verbatim.
-  const promptCheck = (() => {
-    const hasCompletePrompt = payload.completePrompt !== undefined && payload.completePrompt !== null && payload.completePrompt !== '';
-    const hasMessages = payload.messages !== undefined && payload.messages !== null;
-    if (hasCompletePrompt && hasMessages) {
-      return {
-        error: { code: 'INVALID_PARAMETERS', message: 'exactly one of `completePrompt` or `messages` must be provided（两者不能同时出现）', details: { invalidFields: ['completePrompt', 'messages'] } },
-        hasCompletePrompt: true, hasMessages: true,
-      };
-    }
-    if (hasMessages) {
-      const err = validateLlmMessagesArray(payload.messages);
-      if (err) {
-        return {
-          error: { code: 'INVALID_PARAMETERS', message: err, details: { invalidFields: ['messages'] } },
-          hasCompletePrompt: false, hasMessages: true,
-        };
-      }
-    }
-    return { error: null, hasCompletePrompt, hasMessages };
-  })();
-
-  if (promptCheck.error) {
-    return { valid: false, errorCode: promptCheck.error.code, errorMessage: promptCheck.error.message, details: promptCheck.error.details };
-  }
-  const hasPrompt = promptCheck.hasCompletePrompt || promptCheck.hasMessages;
-
-  if (payload.messageType === 'prompted' || payload.messageType === 'auto') {
-    const missingAiFields = [];
-    if (!hasPrompt) missingAiFields.push('completePrompt or messages');
-    if (!payload.apiUrl) missingAiFields.push('apiUrl');
-    if (!payload.apiKey) missingAiFields.push('apiKey');
-    if (!payload.primaryModel) missingAiFields.push('primaryModel');
-    if (missingAiFields.length > 0) {
-      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { missingFields: missingAiFields } };
-    }
-  }
-
-  if (payload.messageType === 'instant') {
-    if (payload.recurrenceType && payload.recurrenceType !== 'none') {
-      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型的 recurrenceType 必须为 none', details: { invalidFields: ['recurrenceType (must be "none" for instant type)'] } };
-    }
-    const hasAiConfig = hasPrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
-    const hasUserMessage = payload.userMessage;
-    if (!hasAiConfig && !hasUserMessage) {
-      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型必须提供 userMessage 或完整的 AI 配置', details: { missingFields: ['userMessage or ((completePrompt | messages) + apiUrl + apiKey + primaryModel)'] } };
-    }
-  }
-
-  if (
-    payload.temperature !== undefined &&
-    payload.temperature !== null &&
-    (typeof payload.temperature !== 'number' || !Number.isFinite(payload.temperature))
-  ) {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['temperature (must be a finite number)'] } };
-  }
-
-  const avatarErr = validateAvatarUrl(payload.avatarUrl);
-  if (avatarErr) {
-    // Soft-strip: a bad avatarUrl (data: URI / oversized / malformed) used to
-    // 400 the whole schedule. Avatar is cosmetic — drop the field, log, and
-    // let the rest of the task ship. See standards §6.2.
-    console.warn('[amsg-server] avatarUrl 不合法，已置空：', avatarErr);
-    payload.avatarUrl = null;
-  }
-  if (payload.uuid && !isValidUUID(payload.uuid)) {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['uuid (invalid UUID format)'] } };
-  }
-  // messageSubtype is a free-form string tag forwarded to SW-side push payload
-  // for classification. Only the type is enforced; the taxonomy is the
-  // consumer's call (previously the enum was chat/forum/moment).
-  if (
-    payload.messageSubtype !== undefined &&
-    payload.messageSubtype !== null &&
-    typeof payload.messageSubtype !== 'string'
-  ) {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['messageSubtype'] } };
-  }
-
-  const splitErr = validateSplitPattern(payload.splitPattern);
-  if (splitErr) {
-    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: splitErr, details: { invalidFields: ['splitPattern'] } };
-  }
-
-  return { valid: true };
-}
-
-/**
- * Request payload utilities.
- * Keeps body parsing and shape validation consistent across handlers.
- */
-
-const REQUEST_ERRORS = {
-  INVALID_JSON: { code: 'INVALID_JSON', message: '请求体不是有效的 JSON' },
-  INVALID_REQUEST_BODY: { code: 'INVALID_REQUEST_BODY', message: '请求体格式无效' },
-  INVALID_ENCRYPTED_PAYLOAD: { code: 'INVALID_ENCRYPTED_PAYLOAD', message: '加密数据格式错误' }
-};
-
-/**
- * @typedef {{ code: string, message: string }} ValidationError
- */
-
-/**
- * @typedef {{
- *   invalidJson?: ValidationError,
- *   invalidType?: ValidationError
- * }} ParseBodyOptions
- */
-
-/**
- * @typedef {{
- *   ok: true,
- *   data: Record<string, any>
- * } | {
- *   ok: false,
- *   error: ValidationError
- * }} ParseBodyResult
- */
-
-/**
- * Parse body into a JSON object.
- *
- * @param {unknown} body
- * @param {ParseBodyOptions} [options]
- * @returns {ParseBodyResult}
- */
-function parseBodyAsObject(body, options = {}) {
-  const invalidJson = options.invalidJson || REQUEST_ERRORS.INVALID_JSON;
-  const invalidType = options.invalidType || REQUEST_ERRORS.INVALID_REQUEST_BODY;
-
-  let parsed = body;
-  if (typeof parsed === 'string') {
-    try {
-      parsed = JSON.parse(parsed);
-    } catch {
-      return { ok: false, error: invalidJson };
-    }
-  }
-
-  if (!isPlainObject(parsed)) {
-    return { ok: false, error: invalidType };
-  }
-
-  return { ok: true, data: parsed };
-}
-
-/**
- * Parse a standard JSON object body.
- *
- * @param {unknown} body
- * @returns {ParseBodyResult}
- */
-function parseJsonBody(body) {
-  return parseBodyAsObject(body, {
-    invalidJson: REQUEST_ERRORS.INVALID_JSON,
-    invalidType: REQUEST_ERRORS.INVALID_REQUEST_BODY
-  });
-}
-
-/**
- * Check if a value is a plain object (and not null/array).
- *
- * @param {unknown} value
- * @returns {value is Record<string, any>}
- */
-function isPlainObject(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/**
- * Check if an object follows the encrypted payload envelope shape.
- *
- * @param {unknown} payload
- * @returns {payload is { iv: string, authTag: string, encryptedData: string }}
- */
-function isEncryptedEnvelope(payload) {
-  if (!isPlainObject(payload)) return false;
-
-  return (
-    typeof payload.iv === 'string' &&
-    typeof payload.authTag === 'string' &&
-    typeof payload.encryptedData === 'string'
-  );
-}
-
-/**
- * Parse and validate an encrypted payload envelope.
- *
- * @param {unknown} body
- * @returns {ParseBodyResult}
- */
-function parseEncryptedBody(body) {
-  const parsedBody = parseBodyAsObject(body, {
-    invalidJson: REQUEST_ERRORS.INVALID_ENCRYPTED_PAYLOAD,
-    invalidType: REQUEST_ERRORS.INVALID_ENCRYPTED_PAYLOAD
-  });
-
-  if (!parsedBody.ok) {
-    return parsedBody;
-  }
-
-  if (!isEncryptedEnvelope(parsedBody.data)) {
-    return { ok: false, error: REQUEST_ERRORS.INVALID_ENCRYPTED_PAYLOAD };
-  }
-
-  return parsedBody;
-}
-
-/**
- * Read a header value case-insensitively.
- *
- * @param {Record<string, any>} headers
- * @param {string} name
- * @returns {string}
- */
-function getHeader(headers = {}, name) {
-  if (!headers || typeof headers !== 'object') {
-    return '';
-  }
-
-  const lowerName = String(name || '').toLowerCase();
-  if (!lowerName) return '';
-
-  for (const [key, value] of Object.entries(headers)) {
-    if (String(key).toLowerCase() === lowerName) {
-      return String(value || '').trim();
-    }
-  }
-
-  return '';
-}
-
-/**
- * Runtime-neutral crypto + encoding helpers.
- *
- * Everything in here is implemented on top of WHATWG-standard primitives
- * (`globalThis.crypto.subtle`, `TextEncoder`, `Uint8Array`) so the package
- * runs on Cloudflare Workers, Vercel Edge, Netlify Edge, Deno, Bun, and
- * Node ≥ 19 with zero polyfills. The Node adapter polyfills
- * `globalThis.crypto` for Node 18 deployments before any of these are
- * touched.
- */
-
-const TEXT_ENCODER = new TextEncoder();
-const TEXT_DECODER = new TextDecoder('utf-8', { fatal: false });
-
-/** UTF-8 encode a string into a Uint8Array. */
-function utf8$1(str) {
-  return TEXT_ENCODER.encode(String(str));
-}
-
-/** UTF-8 decode a Uint8Array / ArrayBuffer into a string. */
-function utf8Decode(buf) {
-  return TEXT_DECODER.decode(toUint8(buf));
-}
-
-
-/** Encode bytes as standard base64 (with padding). */
-function bytesToBase64(buf) {
-  const bytes = toUint8(buf);
-  let bin = '';
-  for (let i = 0; i < bytes.length; i++) {
-    bin += String.fromCharCode(bytes[i]);
-  }
-  // btoa is available in all Web Crypto runtimes (browsers, Workers, Node 16+).
-  return (typeof btoa === 'function')
-    ? btoa(bin)
-    : Buffer.from(bin, 'binary').toString('base64');
-}
-
-/** Encode bytes as base64url (no padding). */
-function bytesToBase64Url(buf) {
-  return bytesToBase64(buf).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
-}
-
-/** Encode bytes as lowercase hex. */
-function bytesToHex(buf) {
-  const bytes = toUint8(buf);
-  let out = '';
-  for (let i = 0; i < bytes.length; i++) {
-    out += bytes[i].toString(16).padStart(2, '0');
-  }
-  return out;
-}
-
-/** Decode a hex string into a Uint8Array. */
-function hexToBytes(hex) {
-  const out = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < out.length; i++) {
-    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-  }
-  return out;
-}
-
-
-/** Encode a JSON-serializable value as base64url (UTF-8 JSON). */
-function jsonToBase64Url(value) {
-  return bytesToBase64Url(utf8$1(JSON.stringify(value)));
-}
-
-/** `crypto.randomUUID()`. The Node adapter polyfills `globalThis.crypto`. */
-function randomUUID() {
-  return globalThis.crypto.randomUUID();
-}
-
-/** Cryptographically random bytes. */
-function randomBytes(n) {
-  const out = new Uint8Array(n);
-  globalThis.crypto.getRandomValues(out);
-  return out;
-}
-
-/**
- * Encryption utility library (SDK version)
- *
- * Wraps AES-256-GCM operations for request/response and storage encryption.
- * Implemented on `globalThis.crypto.subtle` (Web Crypto) so the module runs
- * on Cloudflare Workers and other edge runtimes without `nodejs_compat`, as
- * well as on Node ≥ 19. All exports are async because SubtleCrypto is.
- *
- * Wire formats are byte-identical to the previous node:crypto implementation
- * (pinned by test/encryption-compat.test.mjs):
- *   - payload:  12-byte IV, base64 `{ iv, authTag, encryptedData }`
- *   - storage:  16-byte IV, hex `iv:authTag:encryptedData`
- * Web Crypto appends the GCM auth tag to the ciphertext, while these formats
- * carry it detached — aesGcmSeal / aesGcmOpen below own that seam.
- */
-
-
-// Decoder for the wire formats' base64 fields. base64UrlToBytes normalizes
-// the url-safe alphabet and padding first, so it accepts both standard and
-// url-safe base64 — same leniency as node's Buffer.from(x, 'base64').
-const base64ToBytes = base64UrlToBytes;
-
-const TAG_LENGTH_BYTES = 16; // AES-GCM auth tag emitted on encrypt
-
-function importAesKey(hexKey, usage) {
-  return globalThis.crypto.subtle.importKey(
-    'raw',
-    hexToBytes(hexKey),
-    { name: 'AES-GCM' },
-    false,
-    [usage]
-  );
-}
-
-/** AES-256-GCM encrypt; returns the ciphertext and the detached 16-byte tag. */
-async function aesGcmSeal(hexKey, iv, plaintextBytes) {
-  const key = await importAesKey(hexKey, 'encrypt');
-  const sealed = new Uint8Array(await globalThis.crypto.subtle.encrypt(
-    { name: 'AES-GCM', iv, tagLength: TAG_LENGTH_BYTES * 8 },
-    key,
-    plaintextBytes
-  ));
-  return {
-    ciphertext: sealed.slice(0, sealed.length - TAG_LENGTH_BYTES),
-    authTag: sealed.slice(sealed.length - TAG_LENGTH_BYTES)
-  };
-}
-
-/** AES-256-GCM decrypt from detached-tag form; returns plaintext bytes. */
-async function aesGcmOpen(hexKey, iv, ciphertext, authTag) {
-  const key = await importAesKey(hexKey, 'decrypt');
-  // node's decipher accepted GCM tags truncated down to 96 bits; mirror that
-  // by sizing tagLength from the provided tag. Anything outside the standard
-  // 96–128-bit range keeps 128 and fails authentication, as it did before.
-  const tagBits = authTag.length * 8;
-  const tagLength = tagBits >= 96 && tagBits <= 128 ? tagBits : 128;
-  const plain = await globalThis.crypto.subtle.decrypt(
-    { name: 'AES-GCM', iv, tagLength },
-    key,
-    concatBytes(ciphertext, authTag)
-  );
-  return new Uint8Array(plain);
-}
-
-/**
- * Derive a user-specific encryption key from the master key.
- *
- * @param {string} userId    - Unique user identifier.
- * @param {string} masterKey - 64-char hex master key.
- * @returns {Promise<string>} 64-char hex key.
- */
-async function deriveUserEncryptionKey(userId, masterKey) {
-  const digest = await globalThis.crypto.subtle.digest('SHA-256', utf8$1(masterKey + userId));
-  return bytesToHex(new Uint8Array(digest)).slice(0, 64);
-}
-
-/**
- * Decrypt a client-encrypted request body (AES-256-GCM, base64 encoded).
- *
- * @param {{ iv: string, authTag: string, encryptedData: string }} encryptedPayload
- * @param {string} encryptionKey - 64-char hex key.
- * @returns {Promise<Object>} Decrypted JSON object.
- */
-async function decryptPayload(encryptedPayload, encryptionKey) {
-  const { iv, authTag, encryptedData } = encryptedPayload;
-  const plain = await aesGcmOpen(
-    encryptionKey,
-    base64ToBytes(iv),
-    base64ToBytes(encryptedData),
-    base64ToBytes(authTag)
-  );
-  return JSON.parse(utf8Decode(plain));
-}
-
-/**
- * Encrypt a JSON payload for API transfer (AES-256-GCM, base64 encoded).
- *
- * @param {string|Object} payload
- * @param {string} encryptionKey - 64-char hex key.
- * @returns {Promise<{ iv: string, authTag: string, encryptedData: string }>}
- */
-async function encryptPayload(payload, encryptionKey) {
-  const plaintext = typeof payload === 'string' ? payload : JSON.stringify(payload);
-  const iv = randomBytes(12);
-  const { ciphertext, authTag } = await aesGcmSeal(encryptionKey, iv, utf8$1(plaintext));
-
-  return {
-    iv: bytesToBase64(iv),
-    authTag: bytesToBase64(authTag),
-    encryptedData: bytesToBase64(ciphertext)
-  };
-}
-
-/**
- * Encrypt data for database storage (hex encoded, colon-separated).
- *
- * @param {string} text          - Plaintext string.
- * @param {string} encryptionKey - 64-char hex key.
- * @returns {Promise<string>} Format: iv:authTag:encryptedData
- */
-async function encryptForStorage(text, encryptionKey) {
-  const iv = randomBytes(16);
-  const { ciphertext, authTag } = await aesGcmSeal(encryptionKey, iv, utf8$1(text));
-  return `${bytesToHex(iv)}:${bytesToHex(authTag)}:${bytesToHex(ciphertext)}`;
-}
-
-/**
- * Decrypt data from database storage format.
- *
- * @param {string} encryptedText - Format: iv:authTag:encryptedData
- * @param {string} encryptionKey - 64-char hex key.
- * @returns {Promise<string>} Plaintext string.
- */
-async function decryptFromStorage(encryptedText, encryptionKey) {
-  const [ivHex, authTagHex, encryptedDataHex] = encryptedText.split(':');
-  const plain = await aesGcmOpen(
-    encryptionKey,
-    hexToBytes(ivHex),
-    hexToBytes(encryptedDataHex),
-    hexToBytes(authTagHex)
-  );
-  return utf8Decode(plain);
-}
-
-/**
- * Handler: get-user-key
- * ReiStandard SDK v2.0.1
- *
- * @param {Object} ctx - Server context.
- * @returns {{ GET: function }}
- */
-
-
-function createGetUserKeyHandler(ctx) {
-  async function GET(url, headers) {
-    const effectiveHeaders = headers || url || {};
-    const tenantResult = await ctx.tenantManager.resolveTenant(effectiveHeaders);
-    if (!tenantResult.ok) {
-      return tenantResult.error;
-    }
-
-    const { masterKey } = tenantResult.context;
-    const userId = getHeader(effectiveHeaders, 'x-user-id');
-
-    if (!userId) {
-      return {
-        status: 400,
-        body: { success: false, error: { code: 'USER_ID_REQUIRED', message: '缺少用户标识符' } }
-      };
-    }
-
-    if (!isValidUUIDv4(userId)) {
-      return {
-        status: 400,
-        body: { success: false, error: { code: 'INVALID_USER_ID_FORMAT', message: 'X-User-Id 必须是 UUID v4 格式' } }
-      };
-    }
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        data: {
-          userKey: await deriveUserEncryptionKey(userId, masterKey),
-          version: 1
-        }
-      }
-    };
-  }
-
-  return { GET };
-}
-
-/**
- * Database error helpers.
- */
-
-/**
- * Check whether an error is caused by a unique-constraint violation.
- *
- * @param {unknown} error
- * @returns {boolean}
- */
-function isUniqueViolation(error) {
-  if (!error || typeof error !== 'object') return false;
-
-  const code = error.code;
-  if (code === '23505') return true;
-
-  const message = typeof error.message === 'string' ? error.message.toLowerCase() : '';
-  return message.includes('duplicate key') || message.includes('unique constraint');
-}
-
-/**
- * OpenAI-compatible LLM call for the server-side fire chain.
- *
- * Extracted from message-processor.js so the agentic fire loop
- * (lib/agentic-fire.js) can call the LLM without a circular import.
- * The legacy single-shot path (processSingleMessage) and the multi-round
- * loop share this one function.
- */
-
-/**
- * Call an OpenAI-compatible API.
- *
- * Returns the full response object alongside the extracted (trimmed)
- * `content` string. Callers that only need the text can ignore
- * `response`; callers that want `reasoning_content` / `tool_calls`
- * read from `response.choices[0].message`.
- *
- * @param {Object} payload
- * @param {{ requireContent?: boolean, timeoutMs?: number }} [options]
- *   requireContent defaults to true (legacy single-shot behavior:
- *   throw when the response carries no content). Tool rounds legitimately
- *   return no content (pure tool_calls), so the agentic loop passes
- *   `{ requireContent: false }` — same precedent as amsg-instant's
- *   callLlmRaw.
- *   timeoutMs defaults to 300000 (the legacy per-call ceiling). The
- *   agentic loop passes its remaining wall-time budget so a hung LLM
- *   request cannot outlive totalTimeoutMs.
- * @returns {Promise<{ response: unknown, content: string }>}
- */
-async function callLlm(payload, options = {}) {
-  const requireContent = options.requireContent !== false;
-  const timeoutMs = typeof options.timeoutMs === 'number' && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
-    ? options.timeoutMs
-    : 300000;
-  const normalizedApiUrl = normalizeAiApiUrl(payload.apiUrl);
-  const requestBody = buildAiRequestBody(payload);
-
-  const aiResponse = await fetch(normalizedApiUrl, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${payload.apiKey}`
-    },
-    body: JSON.stringify(requestBody),
-    signal: AbortSignal.timeout(timeoutMs)
-  });
-
-  if (!aiResponse.ok) {
-    if (aiResponse.status === 405) {
-      throw new Error(
-        `AI API error: 405 Method Not Allowed. ` +
-        `apiUrl must point to a full chat endpoint (for example: /chat/completions). ` +
-        `Received: ${normalizedApiUrl}`
-      );
-    }
-
-    throw new Error(
-      `AI API error: ${aiResponse.status} ${aiResponse.statusText || 'Unknown Error'}. ` +
-      `Request URL: ${normalizedApiUrl}`
-    );
-  }
-
-  const aiData = await aiResponse.json();
-  const rawContent = aiData?.choices?.[0]?.message?.content;
-  if (requireContent && (typeof rawContent !== 'string' || !rawContent.trim())) {
-    throw new Error('AI API error: response missing choices[0].message.content');
-  }
-
-  return { response: aiData, content: typeof rawContent === 'string' ? rawContent.trim() : '' };
-}
-
-/**
- * Build OpenAI-compatible request body.
- *
- * `max_tokens` is optional:
- * - include it only when payload.maxTokens is provided
- * - omit it when payload.maxTokens is undefined / null
- *
- * `tools` / `tool_choice` are optional as well: forwarded only when the
- * caller passes a non-empty payload.tools.
- *
- * @param {Object} payload
- * @returns {Object}
- */
-function buildAiRequestBody(payload) {
-  // messages mode (added in v2.2.0): forward the caller's OpenAI-style array
-  // verbatim — same contract as @rei-standard/amsg-instant 0.5.0+. No auto
-  // role injection, no concatenation back to a single user message. Lets
-  // the upstream app preserve system / multi-turn context byte-for-byte
-  // across the schedule-message path.
-  const llmMessages = Array.isArray(payload.messages) && payload.messages.length > 0
-    ? payload.messages
-    : [{ role: 'user', content: payload.completePrompt }];
-
-  const requestBody = {
-    model: payload.primaryModel,
-    messages: llmMessages,
-  };
-
-  // Match the instant package's behavior: only inject default temperature
-  // for the legacy completePrompt path; messages mode forwards whatever the
-  // upstream app set (or nothing) so behavior matches their main chat path.
-  if (payload.temperature !== undefined && payload.temperature !== null) {
-    requestBody.temperature = payload.temperature;
-  } else if (!Array.isArray(payload.messages)) {
-    requestBody.temperature = 0.8;
-  }
-
-  // tools mode (added in v2.6.0): forward the caller's OpenAI tools array
-  // verbatim — same philosophy as messages mode above. The agentic loop
-  // already appends assistant tool_calls + role:'tool' results; this is
-  // the request-side half of the same protocol. An empty array is treated
-  // as "no tools" because some OpenAI-compatible relays reject `tools: []`.
-  if (Array.isArray(payload.tools) && payload.tools.length > 0) {
-    requestBody.tools = payload.tools;
-    if (payload.toolChoice !== undefined && payload.toolChoice !== null) {
-      requestBody.tool_choice = payload.toolChoice;
-    }
-  }
-
-  if (payload.maxTokens === undefined || payload.maxTokens === null) {
-    return requestBody;
-  }
-
-  if (!Number.isInteger(payload.maxTokens) || payload.maxTokens <= 0) {
-    throw new Error('Invalid maxTokens: maxTokens must be a positive integer when provided.');
-  }
-
-  requestBody.max_tokens = payload.maxTokens;
-  return requestBody;
-}
-
-/**
- * Normalize AI API URL for OpenAI-compatible chat endpoints.
- *
- * **Keep in sync** with `@rei-standard/amsg-instant`'s
- * `src/message-processor.js` `normalizeAiApiUrl` — same rules, same
- * tests. The two packages share this logic but each carry their own copy
- * to avoid an architectural dependency (server should not depend on the
- * stateless worker package).
- *
- * @param {string} apiUrl
- * @returns {string}
- */
-function normalizeAiApiUrl(apiUrl) {
-  if (typeof apiUrl !== 'string' || !apiUrl.trim()) {
-    throw new Error(
-      'Invalid apiUrl: apiUrl is required. ' +
-      'Please provide a chat endpoint URL ' +
-      '(for example: https://api.openai.com or https://api.openai.com/v1/chat/completions).'
-    );
-  }
-
-  const trimmedApiUrl = apiUrl.trim();
-  let parsedUrl;
-
-  try {
-    parsedUrl = new URL(trimmedApiUrl);
-  } catch {
-    throw new Error(
-      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
-    );
-  }
-
-  let path = parsedUrl.pathname.replace(/\/+$/, '') || '/';
-
-  if (/\/chat\/completions$/.test(path)) ; else if (path === '/') {
-    // Bare host → assume OpenAI shape.
-    path = '/v1/chat/completions';
-  } else if (/\/v\d+$/.test(path)) {
-    // Path ends in `/v1`, `/v2`, … — caller already versioned the URL.
-    // Append only `/chat/completions`; never re-add `/v1`.
-    path = `${path}/chat/completions`;
-  }
-  // Any other custom path is left untouched on purpose.
-
-  parsedUrl.pathname = path;
-  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;
-}
-
-/**
- * client_state 的落库实现，所有写入方共用。
- *
- * 写入方有两个：HTTP 的 `PUT /client-state`（客户端批量把本地状态同步上来）
- * 和 fire-time hook 的 `ctx.writeState()`（服务端在组消息时把大内容旁路存下
- * 来，见 lib/agentic-fire.js）。加密、大值分块、旧切片清理都在这里一份，
- * 两条路径写出来的行完全同构，读回时也就不用区分是谁写的。
- *
- * 读回在 lib/state-chunks.js 的 resolveClientStateEntries。
- */
-
-
-const utf8 = new TextEncoder();
-
-// 一次写入的条目上限。客户端一次后台窗口传几十条是设计负载，200 留足余量，
-// 同时给 D1 的一次 batch 定个上界。
-const MAX_STATE_ENTRIES_PER_BATCH = 200;
-// namespace / key 的字符长度上限，HTTP 与 hook 两条写入路径共用一套。
-const MAX_NAMESPACE_CHARS = 128;
-const MAX_KEY_CHARS = 256;
-
-/** value 的 UTF-8 字节数——各处限额判断用的都是这个口径。 */
-function stateValueBytes(value) {
-  return utf8.encode(value).length;
-}
-
-/**
- * 把逻辑条目写进 client_state。条目要么是覆盖写（`value` 是字符串），要么是
- * 删除（`value` 为 `null`）：
- *
- *   - 覆盖写：≤ 200KB 单行存；超过的切片跨行存（见 lib/state-chunks.js）。
- *     同一批里先清掉这个 key 上次写入留下的切片行，所以覆盖成更小的值、或者
- *     块数变少，都不会留下尾巴。
- *   - 删除：根行按精确 key 删，切片行按 key 前缀删，一个 key 的数据清干净。
- *
- * 两者都受同一套 last-write-wins 约束：`updatedAt` 比库里已有值旧的写入
- * （或删除）不生效，陈旧批次盖不掉新数据。
- *
- * 条目本身的合法性（namespace / key 字符、value 大小）由调用方先校验好：
- * HTTP handler 逐条拒绝并把原因回给客户端，`writeState()` 直接抛错给 hook。
- *
- * @param {Object} args
- * @param {{ upsertClientState: Function }} args.db
- * @param {string} args.userId
- * @param {CryptoKey|string} args.userKey - 该用户的存储密钥（value 用它加密）
- * @param {Array<{ namespace: string, key: string, value: string|null, updatedAt: number }>} args.entries
- * @returns {Promise<{ upserted: number, skipped: number, deleted: number }>}
- *   `upserted` / `skipped` 按逻辑条目计（切片行不计）；`deleted` 是请求删除的
- *   key 数，不代表这些 key 原本一定存在。
- */
-async function writeClientStateEntries({ db, userId, userKey, entries }) {
-  const physicalRows = [];
-  const cleanups = [];
-  const rootRowIndexes = [];
-  let deleted = 0;
-
-  for (const entry of entries) {
-    // 不管写还是删，都先清掉这个 key 上一次写入留下的切片行（同一批里先删后写）。
-    cleanups.push({
-      namespace: chunkNamespaceFor(entry.namespace),
-      keyPrefix: chunkKeyPrefixFor(entry.key),
-      updatedAt: entry.updatedAt,
-    });
-
-    if (entry.value === null) {
-      // 根行按精确 key 删——用前缀会连带删掉同前缀的兄弟 key（'note' 删掉 'notes'）。
-      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) {
-    // 逻辑计数：一条条目的 upserted/skipped 看它的根行，切片行不计数。
-    for (const rootIndex of rootRowIndexes) {
-      if (result.outcomes[rootIndex]) upserted++; else skipped++;
-    }
-  } else {
-    // 自定义 adapter 只回老形状 { upserted, skipped } 时按物理行计数兜底。
-    upserted = result.upserted;
-    skipped = result.skipped;
-  }
-  return { upserted, skipped, deleted };
-}
-
-/**
- * Server-side agentic fire loop.
- *
- * 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) | { skip: true }
- *     → callLlm → onLLMOutput(sessionCtx) → decision
- *         ├─ 'finish'       → push decision.pushPayloads, done
- *         ├─ 'skip-push'    → record, done (task counts as delivered)
- *         ├─ 'continue'     → replace history, next round
- *         └─ 'tool-request' → executeToolCalls IN the worker — the client
- *                             is offline at fire time, so unlike
- *                             amsg-instant nothing is pushed back for the
- *                             client to execute — then append the
- *                             assistant turn + tool results, next round
- *
- * The decision contract is shared with @rei-standard/amsg-instant
- * (assertValidDecision / buildSessionContext live in
- * @rei-standard/amsg-shared), so a classifier written for instant's
- * onLLMOutput drops in unchanged: 'tool-request' may carry `toolCalls`
- * directly, or tool_request pushPayloads that embed them — both work.
- *
- * Credential hiding: hook ctx objects never contain apiKey /
- * pushSubscription / vapid / masterKey (same rationale as instant's
- * SessionContext — a console.log(ctx) in a hook must not leak keys).
- *
- * client_state 读写：fireCtx 和每轮的 sessionCtx 上都挂着 readState /
- * writeState，读到和写出的都是客户端 `GET/PUT /client-state` 那套数据。写口
- * 在 sessionCtx 上也给，是因为「这条内容太大、塞不进 push」往往到工具跑完、
- * 组 pushPayloads 时才知道，那时 onBeforeFire 早已返回。
- *
- * scratch：每次 fire 新建一个普通对象，onBeforeFire 的 fireCtx 与同一次
- * fire 每轮的 sessionCtx 都持有同一个引用，hook 之间借它传工具上下文，
- * 不用再自己维护 Map<sessionId, state>。fire 结束（finish / skip-push /
- * 抛错 / 轮数超限）后随调用栈丢弃；库不读不写、不落库、不打日志。
- *
- * 工具声明：onBeforeFire 的返回值里可以带 `tools`（OpenAI 的 tools 数组，
- * 另有可选的 `toolChoice`），本次 fire 的每一轮 LLM 请求都原样带上它们——
- * 补完那轮模型仍可能再发起调用。库不看 tools 的内容，执行照旧是
- * executeToolCalls 的事。
- *
- * 自排后续任务：fireCtx 和每轮的 sessionCtx 上都挂着 scheduleTask，宿主用它
- * 在这次 fire 里给同一个用户再建一条定时任务（「这条发完，一个半小时后我再
- * 接着说一句」）。写口在 sessionCtx 上也给，是因为要不要接着说往往是看完
- * LLM 输出才定的，那时 onBeforeFire 早已返回。凭据（pushSubscription /
- * apiKey）和投递配置从当前任务继承、宿主全程看不到（与 buildHookTask 屏蔽
- * 凭据同一个原则），宿主只提供「什么时候、说什么方向」。
- *
- * 新任务不继承 completePrompt / messages，两者都置 null：fire-time hook 每次
- * 现场重组 prompt，把排程时冻结的旧 prompt 带过去，会在新任务万一走回老链路
- * （onBeforeFire 返回 null、或那次部署没配 hooks）时静默顶替宿主的意图——
- * 与其发一条来路不明的旧文案，不如让它当场失败、走既有的重试/标记逻辑。
- *
- * 护栏（几条都是这个能力能不能上线的关键）：
- *   - firstSendTime 至少比现在晚 MIN_SCHEDULE_LEAD_MS（60 秒）。cron 每分钟
- *     一跳，排在 60 秒内等于让下一跳立刻捡走，容易变成自己触发自己的紧密循环。
- *   - messageType 只收 auto / prompted / fixed，不收 instant。instant 的语义是
- *     「建行的那一刻就投递」，那条路径归 POST /schedule-message 管；从 fire 里
- *     造这么一行，投递时机反而说不清（这里不投，要等 cron 捞到才发）。
- *   - 单次 fire 的建任务上限默认 DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE 条，
- *     factory 配置 ctx.maxScheduledTasksPerFire 可覆盖（0 表示不许自排）。模型
- *     自排后续本质上是个可以无限延伸的链：没有上限的话，一次 fire 里连排十条、
- *     或者每条任务都排下一条，就成了谁也没按下停止键的循环。
- *   - uuid 冲突不抛错，返回 { created: false, reason: 'duplicate' }。fire 失败
- *     会整条重跑（run-tick 的重试语义），宿主传一个由「任务 id + 触发时刻」推
- *     出来的确定性 uuid 就天然幂等，不会每重试一次多排一条。
- *
- * Budget guards, both factory-level (ctx.maxToolIterations /
- * ctx.totalTimeoutMs) and per-fire (onBeforeFire may return
- * { messages, maxToolIterations?, totalTimeoutMs? } to override for one
- * task — e.g. a task the host knows runs slow tools): maxToolIterations
- * caps LLM rounds; totalTimeoutMs is a wall-time ceiling checked before
- * each round so a cron tick can never hang forever. Both exhaustions
- * surface as ordinary task failures → the existing retry / mark-failed
- * semantics apply.
- */
-
-
-const DEFAULT_MAX_TOOL_ITERATIONS = 5;
-const DEFAULT_TOTAL_TIMEOUT_MS = 240_000;
-
-// 一次 fire 里最多能给自己排几条后续任务（ctx.maxScheduledTasksPerFire 可覆盖）。
-const DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE = 2;
-// 自排任务的最小提前量：cron 一分钟一跳，比这更近等于让下一跳立刻捡走。
-const MIN_SCHEDULE_LEAD_MS = 60_000;
-
-// 自排任务允许的类型。instant 归 POST /schedule-message 那条同步路径管。
-const SCHEDULABLE_MESSAGE_TYPES = new Set(['auto', 'prompted', 'fixed']);
-// 与 validateScheduleMessagePayload 同一套；run-tick 只认得这三种，别的值会让
-// 任务发完之后推进不到下一次。
-const SCHEDULABLE_RECURRENCE_TYPES = new Set(['none', 'daily', 'weekly']);
-
-// Same pacing as the legacy path / amsg-instant.
-const SLEEP_BETWEEN_MESSAGES_MS$1 = 1500;
-
-// Task-payload fields that must never reach hook code.
-const CREDENTIAL_PAYLOAD_KEYS = new Set(['apiKey', 'pushSubscription']);
-
-const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-/**
- * Does this task need the LLM at fire time? Fixed text never does, so it
- * always stays on the legacy path regardless of hooks.
- *
- * @param {Object} decryptedPayload
- * @returns {boolean}
- */
-function taskNeedsLlm(decryptedPayload) {
-  const type = decryptedPayload.messageType;
-  if (type === 'prompted' || type === 'auto') return true;
-  if (type === 'instant') {
-    return !!(decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel);
-  }
-  return false;
-}
-
-/**
- * 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)) {
-    if (!CREDENTIAL_PAYLOAD_KEYS.has(key)) safe[key] = value;
-  }
-  return Object.freeze({
-    ...safe,
-    id: task.id ?? null,
-    uuid: task.uuid ?? null,
-    nextSendAt: task.next_send_at ?? null,
-    retryCount: task.retry_count ?? 0,
-  });
-}
-
-function normalizeBeforeFireResult(result) {
-  if (Array.isArray(result)) {
-    return { messages: result };
-  }
-  if (result && typeof result === 'object' && Array.isArray(result.messages)) {
-    return {
-      messages: result.messages,
-      maxToolIterations: result.maxToolIterations,
-      totalTimeoutMs: result.totalTimeoutMs,
-      // 归一成「有就是非空数组，否则 undefined」，让下面每轮的透传判断能直接
-      // 用真值。真正决定请求体带不带 tools 的规则住在 llm.js 的
-      // buildAiRequestBody（那边有测试钉着），这层只是不把空数组往下传。
-      tools: Array.isArray(result.tools) && result.tools.length > 0 ? result.tools : undefined,
-      toolChoice: result.toolChoice,
-    };
-  }
-  throw new TypeError(
-    'AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs?, tools?, toolChoice? } | { skip: true } | null'
-  );
-}
-
-function firstPositiveInt(values, fallback) {
-  for (const v of values) {
-    if (Number.isInteger(v) && v > 0) return v;
-  }
-  return fallback;
-}
-
-function firstPositiveNumber(values, fallback) {
-  for (const v of values) {
-    if (typeof v === 'number' && Number.isFinite(v) && v > 0) return v;
-  }
-  return fallback;
-}
-
-/**
- * Try the hook-driven fire path for one task.
- *
- * @param {Object} args
- * @param {import('../adapters/interface.js').TaskRow} args.task
- * @param {Object} args.decryptedPayload - decrypted task payload (has credentials; they stop here)
- * @param {string} args.userKey - per-user storage key (for readState decryption)
- * @param {Object} args.ctx - processor ctx ({ db, webpush, vapid, hooks, maxToolIterations, totalTimeoutMs, maxScheduledTasksPerFire })
- * @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
- *   (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.
- */
-async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
-  const hooks = ctx.hooks;
-  if (typeof hooks.onLLMOutput !== 'function') {
-    throw new Error('AGENTIC_CONFIG_ERROR: hooks.onBeforeFire requires hooks.onLLMOutput to classify LLM rounds');
-  }
-
-  // Injectable seams for tests only (fake clock / no real 1500ms pacing).
-  const nowFn = typeof ctx._agenticNow === 'function' ? ctx._agenticNow : Date.now;
-  const sleep = typeof ctx._agenticSleep === 'function' ? ctx._agenticSleep : defaultSleep;
-
-  const readState = async (namespace) => {
-    if (typeof namespace !== 'string' || !namespace.trim()) {
-      throw new TypeError('readState(namespace) requires a non-empty string');
-    }
-    if (!ctx.db || typeof ctx.db.getClientState !== 'function') return [];
-    const rows = await ctx.db.getClientState(task.user_id, namespace);
-    // 分块存储的值在这里拼回原文（见 state-chunks.js）；块不齐全的 key 视为
-    // 不存在 —— hook 作者拿到的与客户端写入的一致，永远不会是半截数据。
-    return resolveClientStateEntries(
-      rows,
-      () => ctx.db.getClientState(task.user_id, chunkNamespaceFor(namespace)),
-      (value) => decryptFromStorage(value, userKey)
-    );
-  };
-
-  const maxStateValueBytes = Number.isInteger(ctx.maxStateValueBytes) && ctx.maxStateValueBytes > 0
-    ? ctx.maxStateValueBytes
-    : DEFAULT_MAX_STATE_VALUE_BYTES;
-
-  /**
-   * writeState(namespace, entries) —— readState 的写入口，落库走的是
-   * `PUT /client-state` 那条路径的同一份实现（加密、大值分块、切片清理，见
-   * lib/client-state-store.js），所以 hook 写下的东西客户端 `GET /client-state`
-   * 能原样读回，反过来也一样。
-   *
-   * 典型用法是「大内容旁路」：一条 Web Push 的正文只有 4KB 出头（见
-   * lib/webpush-webcrypto.js 的 MAX_PUSH_PAYLOAD_BYTES），塞不下的内容先写进
-   * client_state，push 里只带一个引用键，客户端上线后按键取回。
-   *
-   * @param {string} namespace
-   * @param {Array<{ key: string, value: string|null, updatedAt?: number }>} entries
-   *   `value` 是字符串 → 整条覆盖写（不是追加，宿主自己负责序列化）；
-   *   `value` 为 `null` → 删掉这个 key（含它的切片行）。
-   *   `updatedAt` 默认取当前时刻，语义与客户端同步一致：比库里已有值旧的写入
-   *   （或删除）不生效，客户端后写的数据不会被这次 fire 盖回去。
-   * @returns {Promise<{ upserted: number, skipped: number, deleted: number }>}
-   *
-   * 谁清、什么时候清：库不做 TTL 也不自动回收，写进去的东西一直在，直到有人
-   * 覆盖或删除它。旁路内容建议放在固定的少量 key 上（例如每个角色一个），下次
-   * 写同一个 key 直接覆盖，存量天然有上限；一次性的大内容在确认客户端取走后，
-   * 用 `{ key, value: null }` 删掉。`DELETE /client-state` 仍然是清空这个用户
-   * 全部状态的兜底。
-   */
-  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 必须是 1-${MAX_NAMESPACE_CHARS} 字符且不含控制字符（\\u0000-\\u001f 为库内部保留）`
-      );
-    }
-    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: 单次最多 ${MAX_STATE_ENTRIES_PER_BATCH} 条，收到 ${entries.length} 条`);
-    }
-    // readState 在适配器不支持时返回空数组（读不到状态，hook 走自己的兜底）。
-    // 写不一样：静默成功会让 push 带上一个指向不存在数据的引用键，所以这里报错。
-    if (!ctx.db || typeof ctx.db.upsertClientState !== 'function') {
-      throw new Error('AGENTIC_STATE_WRITE_UNSUPPORTED: 当前数据库适配器不支持 client_state 写入');
-    }
-
-    const now = nowFn();
-    const normalized = entries.map((entry, index) => {
-      if (!entry || typeof entry !== 'object') {
-        throw new TypeError(`writeState: entries[${index}] 必须是对象`);
-      }
-      if (typeof entry.key !== 'string' || !entry.key.trim() || entry.key.length > MAX_KEY_CHARS) {
-        throw new TypeError(`writeState: entries[${index}].key 必须是 1-${MAX_KEY_CHARS} 字符的字符串`);
-      }
-      if (INTERNAL_STATE_CHAR_RE.test(entry.key)) {
-        throw new TypeError(`writeState: entries[${index}].key 不能包含控制字符（\\u0000-\\u001f 为库内部保留）`);
-      }
-      if (entry.value !== null && typeof entry.value !== 'string') {
-        throw new TypeError(`writeState: entries[${index}].value 必须是字符串（宿主自行序列化），或 null 表示删除`);
-      }
-      if (typeof entry.value === 'string') {
-        const bytes = stateValueBytes(entry.value);
-        if (bytes > maxStateValueBytes) {
-          throw new RangeError(`writeState: entries[${index}].value 为 ${bytes} 字节，超过单条上限 ${maxStateValueBytes} 字节`);
-        }
-      }
-      if (entry.updatedAt !== undefined && (!Number.isInteger(entry.updatedAt) || entry.updatedAt <= 0)) {
-        throw new TypeError(`writeState: entries[${index}].updatedAt 必须是正整数（epoch 毫秒）`);
-      }
-      return {
-        namespace,
-        key: entry.key,
-        value: entry.value,
-        updatedAt: entry.updatedAt ?? now,
-      };
-    });
-
-    return writeClientStateEntries({ db: ctx.db, userId: task.user_id, userKey, entries: normalized });
-  };
-
-  const maxScheduledTasksPerFire =
-    Number.isInteger(ctx.maxScheduledTasksPerFire) && ctx.maxScheduledTasksPerFire >= 0
-      ? ctx.maxScheduledTasksPerFire
-      : DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE;
-  // 本次 fire 已经用掉的建任务额度。校验通过、真的要写库时才 +1，参数不合法的
-  // 调用不占额度；uuid 撞车（那条任务其实已经建出来了）照样占。
-  let scheduledTaskCount = 0;
-
-  /**
-   * scheduleTask(options) —— 在这次 fire 里给**同一个用户**再建一条定时任务。
-   *
-   * 典型用法：角色发完这条，想过一个半小时再接着说一句。以前只能写进
-   * client_state 等客户端上线重放，用户一直不上线这条链就断了；建成任务行之后，
-   * 到点由 cron 直接触发，跟别的定时消息一样。
-   *
-   * 凭据与投递配置（pushSubscription / apiUrl / apiKey / primaryModel /
-   * maxTokens / temperature / splitPattern）以及 contactName / avatarUrl /
-   * messageSubtype / userMessage 从当前任务继承，宿主只说「什么时候、说什么
-   * 方向」——hook 全程看不到凭据。completePrompt / messages 不继承（都置 null），
-   * 见文件头。
-   *
-   * @param {Object} options
-   * @param {string} options.firstSendTime      - 必填，ISO 8601；至少比现在晚 60 秒
-   * @param {'none'|'daily'|'weekly'} [options.recurrenceType='none']
-   * @param {'auto'|'prompted'|'fixed'} [options.messageType]  - 默认继承当前任务
-   * @param {Object} [options.metadata]         - 整体替换（不是深合并）当前任务的 metadata
-   * @param {string} [options.contactName]      - 默认继承
-   * @param {string|null} [options.avatarUrl]   - 默认继承
-   * @param {string} [options.messageSubtype]   - 默认继承
-   * @param {string|null} [options.userMessage] - 默认继承；messageType 'fixed' 时必须有
-   * @param {string} [options.uuid]             - 默认 randomUUID()；传确定性 uuid 可做重试幂等
-   * @returns {Promise<{ created: true, id: number|null, uuid: string, nextSendAt: string }
-   *   | { created: false, reason: 'duplicate', uuid: string }>}
-   */
-  const scheduleTask = async (options) => {
-    if (!options || typeof options !== 'object' || Array.isArray(options)) {
-      throw new TypeError('scheduleTask(options) 需要一个对象，至少包含 { firstSendTime }');
-    }
-
-    // ---- 触发时刻 ----
-    if (typeof options.firstSendTime !== 'string' || !options.firstSendTime.trim()) {
-      throw new RangeError('scheduleTask: firstSendTime 必填，且必须是 ISO 8601 字符串');
-    }
-    const firstSendAt = new Date(options.firstSendTime);
-    if (Number.isNaN(firstSendAt.getTime())) {
-      throw new RangeError(`scheduleTask: firstSendTime 解析不出合法时间：${options.firstSendTime}`);
-    }
-    const earliest = nowFn() + MIN_SCHEDULE_LEAD_MS;
-    if (firstSendAt.getTime() < earliest) {
-      throw new RangeError(
-        `scheduleTask: firstSendTime 至少要比现在晚 ${MIN_SCHEDULE_LEAD_MS / 1000} 秒` +
-        `（最早可排 ${new Date(earliest).toISOString()}，收到 ${firstSendAt.toISOString()}）` +
-        '——cron 一分钟一跳，排得更近等于让下一跳立刻捡走'
-      );
-    }
-    const nextSendAt = firstSendAt.toISOString();
-
-    // ---- 类型 ----
-    const inheritedType = options.messageType == null;
-    const messageType = inheritedType ? decryptedPayload.messageType : options.messageType;
-    if (messageType === 'instant') {
-      throw new TypeError(
-        "scheduleTask: messageType 不能是 'instant'——instant 的语义是「建行的那一刻就投递」，" +
-        '那条路径归 POST /schedule-message 管；从 fire 里建一条 instant，投递时机反而说不清。' +
-        (inheritedType ? '（这个 instant 是从当前任务继承来的，显式传 auto / prompted / fixed 覆盖它。）' : '')
-      );
-    }
-    if (!SCHEDULABLE_MESSAGE_TYPES.has(messageType)) {
-      throw new TypeError(
-        `scheduleTask: messageType 只能是 auto / prompted / fixed，收到 ${JSON.stringify(messageType)}`
-      );
-    }
-
-    const recurrenceType = options.recurrenceType == null ? 'none' : options.recurrenceType;
-    if (!SCHEDULABLE_RECURRENCE_TYPES.has(recurrenceType)) {
-      throw new TypeError(
-        `scheduleTask: recurrenceType 只能是 none / daily / weekly，收到 ${JSON.stringify(recurrenceType)}`
-      );
-    }
-
-    // ---- 继承 + 覆盖 ----
-    const contactName = options.contactName === undefined ? decryptedPayload.contactName : options.contactName;
-    if (typeof contactName !== 'string' || !contactName.trim()) {
-      throw new TypeError('scheduleTask: contactName 必须是非空字符串（默认继承当前任务）');
-    }
-    const userMessage = options.userMessage === undefined
-      ? (decryptedPayload.userMessage ?? null)
-      : options.userMessage;
-    if (messageType === 'fixed' && (typeof userMessage !== 'string' || !userMessage.trim())) {
-      throw new TypeError(
-        "scheduleTask: messageType 'fixed' 必须有 userMessage（自己传，或从当前任务继承到）" +
-        '——固定文本任务没有正文，就是一条永远发空的任务'
-      );
-    }
-    const metadata = options.metadata === undefined ? (decryptedPayload.metadata || {}) : options.metadata;
-    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
-      throw new TypeError('scheduleTask: metadata 必须是普通对象（整体替换当前任务的 metadata，不做深合并）');
-    }
-    const uuid = options.uuid == null ? randomUUID() : options.uuid;
-    if (typeof uuid !== 'string' || !uuid.trim()) {
-      throw new TypeError('scheduleTask: uuid 必须是非空字符串');
-    }
-
-    // ---- 额度 ----
-    if (scheduledTaskCount >= maxScheduledTasksPerFire) {
-      throw new RangeError(
-        `scheduleTask: 单次 fire 最多建 ${maxScheduledTasksPerFire} 条任务` +
-        `（factory 配置 maxScheduledTasksPerFire 可调），这是第 ${scheduledTaskCount + 1} 条`
-      );
-    }
-    // readState 在适配器不支持时降级成空数组；建任务不一样，静默成功会让宿主
-    // 以为后续那条已经排上了，其实谁也不会触发它。
-    if (!ctx.db || typeof ctx.db.createTask !== 'function') {
-      throw new Error('AGENTIC_SCHEDULE_UNSUPPORTED: 当前数据库适配器不支持建任务（缺 createTask）');
-    }
-    scheduledTaskCount++;
-
-    // 字段构成与 POST /schedule-message 落库的那份保持一致，只是走库内部、不经 HTTP。
-    const fullTaskData = {
-      contactName,
-      avatarUrl: options.avatarUrl === undefined ? (decryptedPayload.avatarUrl || null) : (options.avatarUrl || null),
-      messageType,
-      messageSubtype: (options.messageSubtype === undefined ? decryptedPayload.messageSubtype : options.messageSubtype) || 'chat',
-      userMessage: userMessage || null,
-      firstSendTime: nextSendAt,
-      recurrenceType,
-      apiUrl: decryptedPayload.apiUrl || null,
-      apiKey: decryptedPayload.apiKey || null,
-      primaryModel: decryptedPayload.primaryModel || null,
-      // 见文件头：fire-time hook 每次现场重组 prompt，旧 prompt 带过去只会在新
-      // 任务走回老链路时顶替宿主的意图。
-      completePrompt: null,
-      messages: null,
-      maxTokens: decryptedPayload.maxTokens ?? null,
-      temperature: decryptedPayload.temperature ?? null,
-      splitPattern: decryptedPayload.splitPattern ?? null,
-      pushSubscription: decryptedPayload.pushSubscription,
-      metadata,
-    };
-
-    const encryptedPayload = await encryptForStorage(JSON.stringify(fullTaskData), userKey);
-
-    let created;
-    try {
-      created = await ctx.db.createTask({
-        user_id: task.user_id,
-        uuid,
-        encrypted_payload: encryptedPayload,
-        next_send_at: nextSendAt,
-        message_type: messageType,
-      });
-    } catch (error) {
-      // 撞 uuid 不算错：fire 失败会整条重跑，宿主用确定性 uuid（任务 id + 触发
-      // 时刻推出来的那种）就天然幂等，重试不会多排一条。
-      if (isUniqueViolation(error)) return { created: false, reason: 'duplicate', uuid };
-      throw error;
-    }
-    if (!created) {
-      throw new Error('AGENTIC_SCHEDULE_FAILED: createTask 没有返回新建的任务行');
-    }
-    return {
-      created: true,
-      id: created.id ?? null,
-      uuid: created.uuid ?? uuid,
-      nextSendAt: created.next_send_at ?? nextSendAt,
-    };
-  };
-
-  // 单次 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,
-    writeState,
-    scheduleTask,
-    now: new Date(nowFn()),
-    scratch,
-  });
-
-  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],
-    DEFAULT_MAX_TOOL_ITERATIONS
-  );
-  const totalTimeoutMs = firstPositiveNumber(
-    [normalized.totalTimeoutMs, ctx.totalTimeoutMs],
-    DEFAULT_TOTAL_TIMEOUT_MS
-  );
-  const deadline = nowFn() + totalTimeoutMs;
-
-  // Same sessionId scheme as the legacy path: pinned to the task id so a
-  // retried task reuses the same session and clients can group/dedupe.
-  const sessionId = task.id != null ? `sess_task_${task.id}` : `sess_${randomUUID()}`;
-  let messages = normalized.messages.slice();
-
-  for (let iteration = 0; iteration < maxToolIterations; iteration++) {
-    if (nowFn() >= deadline) {
-      throw new Error(`AGENTIC_TOTAL_TIMEOUT: fire chain exceeded ${totalTimeoutMs}ms after ${iteration} LLM round(s)`);
-    }
-
-    // Shrink each round's fetch timeout to the remaining wall-time budget
-    // (capped at the legacy 300s single-call ceiling) — a hung LLM request
-    // must not outlive totalTimeoutMs waiting for its own 300s abort.
-    const roundTimeoutMs = Math.max(1, Math.min(300_000, deadline - nowFn()));
-    const { response: llmResponse } = await callLlm(
-      {
-        ...decryptedPayload,
-        messages,
-        ...(normalized.tools ? { tools: normalized.tools, toolChoice: normalized.toolChoice } : {}),
-      },
-      { requireContent: false, timeoutMs: roundTimeoutMs }
-    );
-
-    const assistantMessage = extractAssistantMessage(llmResponse);
-    messages = [...messages, assistantMessage];
-
-    // 共享的 SessionContext（与 amsg-instant 同形状）之上，再挂两个状态访问器
-    // 和 scheduleTask：大内容要不要旁路存、要不要给自己排条后续，往往到工具跑完、
-    // 组 push 时才知道，而那正是 onLLMOutput / executeToolCalls 的位置，
-    // onBeforeFire 早就返回了。
-    const sessionCtx = Object.freeze({
-      ...buildSessionContext({
-        sessionId,
-        messages,
-        llmResponse,
-        iteration,
-        contactName: decryptedPayload.contactName,
-        avatarUrl: decryptedPayload.avatarUrl || undefined,
-        charId: decryptedPayload.charId,
-        metadata: decryptedPayload.metadata,
-        scratch,
-      }),
-      readState,
-      writeState,
-      scheduleTask,
-    });
-
-    const decision = await hooks.onLLMOutput(sessionCtx);
-    assertValidDecision(decision, { inlineToolCalls: true });
-
-    if (decision.decision === 'continue') {
-      messages = decision.nextHistory.slice();
-      continue;
-    }
-
-    if (decision.decision === 'skip-push') {
-      return { handled: true, result: { success: true, messagesSent: 0, status: 'skipped', iterations: iteration + 1 } };
-    }
-
-    if (decision.decision === 'finish') {
-      const messagesSent = await sendHookPushPayloads(decision.pushPayloads, decryptedPayload, ctx, sessionId, task, sleep);
-      return { handled: true, result: { success: true, messagesSent, status: 'finished', iterations: iteration + 1 } };
-    }
-
-    // 'tool-request' — execute right here in the worker.
-    const toolCalls = extractToolCallsFromDecision(decision);
-    if (toolCalls.length === 0) {
-      throw new Error('AGENTIC_EMPTY_TOOL_REQUEST: tool-request decision carried no toolCalls (neither decision.toolCalls nor pushPayloads[].toolCalls)');
-    }
-    if (typeof hooks.executeToolCalls !== 'function') {
-      throw new Error('AGENTIC_CONFIG_ERROR: onLLMOutput returned tool-request but hooks.executeToolCalls is not configured');
-    }
-    if (iteration === maxToolIterations - 1) {
-      // No LLM round left to consume the results — executing tools now
-      // would only burn external calls. Fall straight to the exceeded error.
-      break;
-    }
-
-    let toolResults;
-    try {
-      toolResults = await hooks.executeToolCalls(toolCalls, sessionCtx);
-      if (!Array.isArray(toolResults)) {
-        throw new TypeError('executeToolCalls must resolve to an array of { tool_call_id, role: "tool", content }');
-      }
-    } catch (error) {
-      // Feed the failure back as tool results and let the LLM talk its way
-      // out, instead of failing the whole fire.
-      toolResults = toolCalls.map((toolCall) => ({
-        tool_call_id: toolCall && typeof toolCall === 'object' && typeof toolCall.id === 'string' ? toolCall.id : '',
-        role: 'tool',
-        content: `Tool execution failed: ${error?.message ?? String(error)}`,
-      }));
-    }
-
-    // Text-protocol classifiers synthesize toolCalls the raw assistant
-    // message doesn't carry; stamp them on so the appended role:'tool'
-    // results stay valid for OpenAI-compatible APIs. Merge rather than pick
-    // one side: when a native tool_call and a synthesized one land in the
-    // same round, both need their id on the assistant turn, or the half
-    // that's missing leaves an orphan role:'tool' and a strict relay
-    // rejects the next round.
-    //
-    // Contract for onLLMOutput: the toolCalls it returns must cover every
-    // native tool_call the model declared. A native call left out still
-    // gets declared on the assistant turn (it came from the model) but has
-    // no matching role:'tool' result, and a strict relay rejects the next
-    // round over the unanswered id. Drop a call on purpose → return a
-    // result for it saying so, don't just omit it.
-    const nativeCalls = Array.isArray(assistantMessage.tool_calls) ? assistantMessage.tool_calls : [];
-    const nativeIds = new Set(nativeCalls.map((tc) => tc && tc.id));
-    const synthesized = toolCalls.filter((tc) => !nativeIds.has(tc && tc.id));
-    const assistantWithTools = synthesized.length === 0
-      ? assistantMessage
-      : { ...assistantMessage, tool_calls: [...nativeCalls, ...synthesized] };
-    messages = [...messages.slice(0, -1), assistantWithTools, ...toolResults];
-  }
-
-  throw new Error(`AGENTIC_LOOP_EXCEEDED: no finish/skip-push decision within ${maxToolIterations} LLM round(s)`);
-}
-
-/**
- * Deliver the hook's pushPayloads sequentially. Mirrors instant's
- * sendPushesSequentially: force-overwrite messageIndex/totalMessages,
- * stamp missing ids, pace with the same 1500ms spacing. Ids are
- * deterministic per (task, index) so a retried task reuses the same ids
- * and clients can dedupe.
- */
-async function sendHookPushPayloads(pushPayloads, decryptedPayload, ctx, sessionId, task, sleep) {
-  if (!ctx.vapid || !ctx.vapid.email || !ctx.vapid.publicKey || !ctx.vapid.privateKey) {
-    throw new Error('VAPID configuration missing - push notifications cannot be sent');
-  }
-  const pushSubscription = decryptedPayload.pushSubscription;
-  const total = pushPayloads.length;
-  const messageIdBase = task.id != null ? `msg_task_${task.id}` : `msg_${randomUUID()}`;
-
-  for (let i = 0; i < total; i++) {
-    const push = { ...pushPayloads[i] };
-    if (typeof push.messageId !== 'string' || !push.messageId) push.messageId = `${messageIdBase}_hook_${i}`;
-    if (typeof push.sessionId !== 'string' || !push.sessionId) push.sessionId = sessionId;
-    if (typeof push.timestamp !== 'string' || !push.timestamp) push.timestamp = new Date().toISOString();
-    push.messageIndex = i + 1;
-    push.totalMessages = total;
-
-    await ctx.webpush.sendNotification(pushSubscription, JSON.stringify(push));
-    if (i < total - 1) await sleep(SLEEP_BETWEEN_MESSAGES_MS$1);
-  }
-  return total;
-}
-
-/**
- * Message Processor (SDK version)
- * ReiStandard amsg-server v2.4.0
- *
- * Handles single message content generation and Web Push delivery for
- * scheduled tasks (`fixed` / `prompted` / `auto`) and the
- * in-server instant path (`messageType: 'instant'`).
- *
- * Push wire shape comes from `@rei-standard/amsg-shared`'s
- * discriminated union (`AmsgPush`). The SW (`@rei-standard/amsg-sw`)
- * routes on `messageKind`. Server-driven pushes always carry
- * `source: 'instant'` (for the in-server instant path) or
- * `source: 'scheduled'` (for everything else).
- *
- * v2.4.0: when the LLM response carries non-empty
- * `choices[0].message.reasoning_content`, the processor now emits a
- * standalone `ReasoningPush` **before** the `ContentPush` burst.
- * `messagesSent` in the return value continues to reflect the sentence
- * count only (reasoning is an auxiliary push, not a sentence).
- */
-
-
-const DEFAULT_SPLIT_REGEX = /([。！？!?]+)/;
-
-// Pacing between consecutive Web Push deliveries (reasoning → content, and
-// between content sentences) so the client renders a natural typing cadence.
-// Kept equal to amsg-instant's SLEEP_BETWEEN_MESSAGES_MS default.
-const SLEEP_BETWEEN_MESSAGES_MS = 1500;
-
-/**
- * Split a single chunk by one regex; on no-match return [chunk] so a later
- * regex in a cascade can still take a swing at it.
- */
-function splitOnceByRegex(chunk, regex) {
-  const out = chunk
-    .split(regex)
-    .reduce((acc, part, i, arr) => {
-      if (i % 2 === 0 && part.trim()) {
-        const punctuation = arr[i + 1] || '';
-        acc.push(part.trim() + punctuation);
-      }
-      return acc;
-    }, [])
-    .filter(s => s.length > 0);
-  return out.length > 0 ? out : [chunk];
-}
-
-/**
- * Sentence splitter for amsg-server's scheduled `splitPattern` feature
- * (see standards §6.1). Server-only: amsg-instant 0.8.0 dropped its
- * request-level `splitPattern`, so there is no instant counterpart to keep
- * in lockstep.
- *
- * @param {string} messageContent
- * @param {string | string[] | null} [splitPattern=null]
- * @returns {string[]}
- */
-function splitMessageIntoSentences(messageContent, splitPattern = null) {
-  const sources =
-    splitPattern == null ? null :
-    Array.isArray(splitPattern) ? splitPattern :
-    [splitPattern];
-
-  const regexes = (sources && sources.length > 0)
-    ? sources.map(s => new RegExp(s))
-    : [DEFAULT_SPLIT_REGEX];
-
-  let chunks = [messageContent];
-  for (const regex of regexes) {
-    chunks = chunks.flatMap(c => splitOnceByRegex(c, regex));
-  }
-
-  return chunks.length > 0 ? chunks : [messageContent];
-}
-
-/**
- * @typedef {Object} ProcessorContext
- * @property {Object}  webpush           - The web-push module instance (already VAPID-configured).
- * @property {Object}  vapid             - { email, publicKey, privateKey }
- * @property {import('../adapters/interface.js').DbAdapter} db
- */
-
-/**
- * Process a single database task row: decrypt → generate content → push.
- *
- * @param {import('../adapters/interface.js').TaskRow} task
- * @param {ProcessorContext} ctx
- * @param {string} [providedMasterKey]
- * @returns {Promise<{ success: boolean, messagesSent: number, error?: string }>}
- */
-async function processSingleMessage(task, ctx, providedMasterKey) {
-  try {
-    const masterKey = providedMasterKey || ctx.masterKey;
-    if (!masterKey) {
-      return { success: false, messagesSent: 0, error: 'TENANT_MASTER_KEY_MISSING' };
-    }
-
-    const userKey = await deriveUserEncryptionKey(task.user_id, masterKey);
-    const decryptedPayload = JSON.parse(await decryptFromStorage(task.encrypted_payload, userKey));
-
-    // Fire-time hooks: when the host configured onBeforeFire and the task
-    // 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. 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;
-    }
-
-    let messageContent;
-    /** @type {unknown} */
-    let llmResponse = null;
-
-    if (decryptedPayload.messageType === 'fixed') {
-      messageContent = decryptedPayload.userMessage;
-
-    } else if (decryptedPayload.messageType === 'instant') {
-      const hasPrompt = !!decryptedPayload.completePrompt
-        || (Array.isArray(decryptedPayload.messages) && decryptedPayload.messages.length > 0);
-      if (hasPrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
-        const aiResult = await callLlm(decryptedPayload);
-        messageContent = aiResult.content;
-        llmResponse = aiResult.response;
-      } else if (decryptedPayload.userMessage) {
-        messageContent = decryptedPayload.userMessage;
-      } else {
-        throw new Error('Invalid instant message: no content source available');
-      }
-
-    } else if (decryptedPayload.messageType === 'prompted' || decryptedPayload.messageType === 'auto') {
-      const aiResult = await callLlm(decryptedPayload);
-      messageContent = aiResult.content;
-      llmResponse = aiResult.response;
-    } else {
-      throw new Error('Invalid message configuration: no content source available');
-    }
-
-    // Auto-extract reasoning BEFORE the sentence split: when reasoning
-    // came from the `<think>` fallback inside message.content, the same
-    // span is still embedded in messageContent and would otherwise leak
-    // as raw markup into ContentPush.
-    const reasoning = readReasoningContent(llmResponse);
-    if (reasoning) {
-      messageContent = stripReasoningTags(messageContent);
-    }
-
-    // Sentence splitting (mirrors @rei-standard/amsg-instant
-    // splitMessageIntoSentences — keep in lockstep; do not drift). Caller may
-    // override the default regex via decryptedPayload.splitPattern (string
-    // for a single regex, string[] for a cascade). Validation already enforces
-    // length cap + RegExp compilability upstream.
-    const messages = splitMessageIntoSentences(messageContent, decryptedPayload.splitPattern ?? null);
-
-    if (!ctx.vapid.email || !ctx.vapid.publicKey || !ctx.vapid.privateKey) {
-      throw new Error('VAPID configuration missing - push notifications cannot be sent');
-    }
-
-    const pushSubscription = decryptedPayload.pushSubscription;
-    // sessionId is shared across the optional ReasoningPush and every
-    // ContentPush from this LLM round. Pin it to the task id when
-    // available (scheduled tasks) so retries reuse the same id;
-    // otherwise mint a UUID.
-    const sessionId = task.id != null
-      ? `sess_task_${task.id}`
-      : `sess_${randomUUID()}`;
-    const source = decryptedPayload.messageType === 'instant' ? 'instant' : 'scheduled';
-    const messageSubtype = decryptedPayload.messageSubtype || 'chat';
-    const avatarUrl = decryptedPayload.avatarUrl || null;
-    const metadata = decryptedPayload.metadata || {};
-
-    // `messageId` format — deterministic when we have a task.id so a
-    // retry produces the same id for the same (task, sentence) pair
-    // (downstream dedupers can key on it). Falls back to a UUID for
-    // the in-server instant path that has no row id.
-    const messageIdBase = task.id != null
-      ? `msg_task_${task.id}`
-      : `msg_${randomUUID()}_instant`;
-
-    // ReasoningPush — auto-emitted before the content burst when the
-    // LLM response carried non-empty reasoning_content. `fixed` and
-    // explicit-userMessage paths produce no LLM response, so this
-    // block is naturally skipped for them (llmResponse stays null).
-    if (reasoning) {
-      const reasoningPush = buildReasoningPush({
-        messageType: decryptedPayload.messageType,
-        source,
-        messageId: `${messageIdBase}_reasoning`,
-        sessionId,
-        reasoningContent: reasoning,
-        timestamp: new Date().toISOString(),
-        title: `来自 ${decryptedPayload.contactName}`,
-        contactName: decryptedPayload.contactName,
-        avatarUrl,
-        messageSubtype,
-        metadata,
-      });
-      await ctx.webpush.sendNotification(pushSubscription, JSON.stringify(reasoningPush));
-      await new Promise(resolve => setTimeout(resolve, SLEEP_BETWEEN_MESSAGES_MS));
-    }
-
-    for (let i = 0; i < messages.length; i++) {
-      const contentPush = buildContentPush({
-        messageType: decryptedPayload.messageType,
-        source,
-        messageId: `${messageIdBase}_${i}`,
-        sessionId,
-        message: messages[i],
-        timestamp: new Date().toISOString(),
-        title: `来自 ${decryptedPayload.contactName}`,
-        contactName: decryptedPayload.contactName,
-        avatarUrl,
-        messageSubtype,
-        messageIndex: i + 1,
-        totalMessages: messages.length,
-        taskId: task.id || null,
-        metadata,
-      });
-
-      await ctx.webpush.sendNotification(pushSubscription, JSON.stringify(contentPush));
-
-      if (i < messages.length - 1) {
-        await new Promise(resolve => setTimeout(resolve, SLEEP_BETWEEN_MESSAGES_MS));
-      }
-    }
-
-    return { success: true, messagesSent: messages.length };
-
-  } catch (error) {
-    return { success: false, messagesSent: 0, error: error.message };
-  }
-}
-
-/**
- * Process a single message identified by UUID (used for instant type).
- *
- * @param {string} uuid
- * @param {ProcessorContext} ctx
- * @param {number} [maxRetries=2]
- * @param {string} [userId]
- * @param {string} [providedMasterKey]
- * @returns {Promise<{ success: boolean, messagesSent?: number, retriesUsed?: number, error?: Object }>}
- */
-async function processMessagesByUuid(uuid, ctx, maxRetries = 2, userId, providedMasterKey) {
-  let retryCount = 0;
-  const masterKey = providedMasterKey || ctx.masterKey;
-
-  if (!masterKey) {
-    return {
-      success: false,
-      error: { code: 'TENANT_MASTER_KEY_MISSING', message: '租户主密钥不存在或配置异常' }
-    };
-  }
-
-  while (retryCount <= maxRetries) {
-    let task;
-    try {
-      task = userId
-        ? await ctx.db.getTaskByUuid(uuid, userId)
-        : await ctx.db.getTaskByUuidOnly(uuid);
-    } catch (error) {
-      if (retryCount < maxRetries) {
-        retryCount++;
-        await new Promise(resolve => setTimeout(resolve, 1000 * retryCount));
-        continue;
-      }
-
-      return {
-        success: false,
-        error: { code: 'INTERNAL_ERROR', message: error.message, retriesAttempted: retryCount }
-      };
-    }
-
-    if (!task) {
-      return { success: false, error: { code: 'TASK_NOT_FOUND', message: '任务不存在或已处理' } };
-    }
-
-    const result = await processSingleMessage(task, ctx, masterKey);
-
-    if (!result.success) {
-      if (retryCount < maxRetries) {
-        retryCount++;
-        await new Promise(resolve => setTimeout(resolve, 1000 * retryCount));
-        continue;
-      }
-
-      try {
-        await ctx.db.updateTaskById(task.id, { status: 'failed', retry_count: retryCount });
-      } catch (_updateError) {
-        // best-effort status update; keep original processing error as primary signal
-      }
-
-      return {
-        success: false,
-        error: { code: 'PROCESSING_ERROR', message: result.error, retriesAttempted: retryCount }
-      };
-    }
-
-    try {
-      await ctx.db.deleteTaskById(task.id);
-    } catch (error) {
-      try {
-        await ctx.db.updateTaskById(task.id, { status: 'sent', retry_count: 0 });
-      } catch (_markSentError) {
-        // best effort: avoid re-sending if storage mutation partially fails
-      }
-
-      return {
-        success: false,
-        error: {
-          code: 'POST_SEND_CLEANUP_FAILED',
-          message: '消息已发送，但任务清理失败',
-          details: { error: error.message }
-        }
-      };
-    }
-
-    return { success: true, messagesSent: result.messagesSent, retriesUsed: retryCount };
-  }
-}
-
-/**
- * Handler: schedule-message
- * ReiStandard SDK v2.0.1
- *
- * @param {Object} ctx - Server context.
- * @returns {{ POST: function }}
- */
-
-
-function createScheduleMessageHandler(ctx) {
-  async function POST(headers, body) {
-    const tenantResult = await ctx.tenantManager.resolveTenant(headers);
-    if (!tenantResult.ok) {
-      return tenantResult.error;
-    }
-
-    const tenantCtx = tenantResult.context;
-    const db = tenantCtx.db;
-    const masterKey = tenantCtx.masterKey;
-    const isEncrypted = getHeader(headers, 'x-payload-encrypted') === 'true';
-    const encryptionVersion = getHeader(headers, 'x-encryption-version');
-    const userId = getHeader(headers, 'x-user-id');
-
-    if (!isEncrypted) {
-      return { status: 400, body: { success: false, error: { code: 'ENCRYPTION_REQUIRED', message: '请求体必须加密' } } };
-    }
-    if (!userId) {
-      return { status: 400, body: { success: false, error: { code: 'USER_ID_REQUIRED', message: '缺少用户标识符' } } };
-    }
-    if (!isValidUUIDv4(userId)) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_USER_ID_FORMAT', message: 'X-User-Id 必须是 UUID v4 格式' } } };
-    }
-    if (encryptionVersion !== '1') {
-      return { status: 400, body: { success: false, error: { code: 'UNSUPPORTED_ENCRYPTION_VERSION', message: '加密版本不支持' } } };
-    }
-
-    // Decrypt request body
-    const parsedBody = parseEncryptedBody(body);
-    if (!parsedBody.ok) {
-      return { status: 400, body: { success: false, error: parsedBody.error } };
-    }
-
-    const encryptedBody = parsedBody.data;
-    const userKey = await deriveUserEncryptionKey(userId, masterKey);
-
-    let payload;
-    try {
-      payload = await decryptPayload(encryptedBody, userKey);
-    } catch (error) {
-      if (error instanceof SyntaxError) {
-        return { status: 400, body: { success: false, error: { code: 'INVALID_PAYLOAD_FORMAT', message: '解密后的数据不是有效 JSON' } } };
-      }
-
-      const message = typeof error.message === 'string' ? error.message : '';
-      if (message.includes('auth') || message.includes('Unsupported state')) {
-        return { status: 400, body: { success: false, error: { code: 'DECRYPTION_FAILED', message: '请求体解密失败' } } };
-      }
-
-      return { status: 400, body: { success: false, error: { code: 'DECRYPTION_FAILED', message: '请求体解密失败' } } };
-    }
-
-    if (!isPlainObject(payload)) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_PAYLOAD_FORMAT', message: '解密后的数据必须是 JSON 对象' } } };
-    }
-
-    // Validate
-    const validationResult = validateScheduleMessagePayload(payload);
-    if (!validationResult.valid) {
-      return { status: 400, body: { success: false, error: { code: validationResult.errorCode, message: validationResult.errorMessage, details: validationResult.details } } };
-    }
-
-    const taskUuid = payload.uuid || randomUUID();
-
-    const fullTaskData = {
-      contactName: payload.contactName,
-      avatarUrl: payload.avatarUrl || null,
-      messageType: payload.messageType,
-      messageSubtype: payload.messageSubtype || 'chat',
-      userMessage: payload.userMessage || null,
-      firstSendTime: payload.firstSendTime,
-      recurrenceType: payload.recurrenceType || 'none',
-      apiUrl: payload.apiUrl || null,
-      apiKey: payload.apiKey || null,
-      primaryModel: payload.primaryModel || null,
-      // Prompt is one-of: legacy completePrompt (string) OR messages (OpenAI-
-      // style array). Validation has already enforced exactly-one-of, so
-      // exactly one of these will be non-null when an AI config is provided.
-      completePrompt: payload.completePrompt || null,
-      messages: Array.isArray(payload.messages) ? payload.messages : null,
-      maxTokens: payload.maxTokens ?? null,
-      temperature: payload.temperature ?? null,
-      // 0.6.0+: optional caller-provided regex (string or string[]) used by
-      // the message processor to chunk LLM output into individual pushes.
-      // null → processor falls back to the default /([。！？!?]+)/ regex.
-      splitPattern: payload.splitPattern ?? null,
-      pushSubscription: payload.pushSubscription,
-      metadata: payload.metadata || {}
-    };
-
-    const encryptedPayload = await encryptForStorage(JSON.stringify(fullTaskData), userKey);
-
-    /**
-     * In-server instant path. Delivers an instant message through this
-     * server's own task queue (create task → process by UUID → delete task).
-     * The task is written to the database before processing, so delivery is
-     * not tied to the request connection: even if the client disconnects, the
-     * row stays and the generation keeps running (and can be retried) for as
-     * long as it needs. Use this when you have a database and want long or
-     * guaranteed-complete generations with no dropped messages.
-     *
-     * The stateless alternative is `@rei-standard/amsg-instant`: it streams
-     * over SSE with a Web Push backup and needs no database, which makes it a
-     * good fit for edge runtimes (e.g. Cloudflare Workers). Its work rides the
-     * response connection, so after the client disconnects it only has the
-     * platform's brief grace window to finish (≈20-30s observed on Deno
-     * Deploy) — ideal for short instant messages that complete quickly.
-     */
-    // Instant type: check VAPID before creating the task to avoid orphaned rows
-    if (payload.messageType === 'instant') {
-      if (!ctx.vapid.email || !ctx.vapid.publicKey || !ctx.vapid.privateKey) {
-        return {
-          status: 500,
-          body: {
-            success: false,
-            error: {
-              code: 'VAPID_CONFIG_ERROR',
-              message: 'VAPID 配置缺失，无法发送即时消息',
-              details: {
-                missingKeys: [
-                  !ctx.vapid.email && 'VAPID_EMAIL',
-                  !ctx.vapid.publicKey && 'NEXT_PUBLIC_VAPID_PUBLIC_KEY',
-                  !ctx.vapid.privateKey && 'VAPID_PRIVATE_KEY'
-                ].filter(Boolean)
-              }
-            }
-          }
-        };
-      }
-    }
-
-    // Insert into database
-    let dbResult;
-    try {
-      dbResult = await db.createTask({
-        user_id: userId,
-        uuid: taskUuid,
-        encrypted_payload: encryptedPayload,
-        next_send_at: payload.firstSendTime,
-        message_type: payload.messageType
-      });
-    } catch (error) {
-      if (isUniqueViolation(error)) {
-        return {
-          status: 409,
-          body: {
-            success: false,
-            error: {
-              code: 'TASK_UUID_CONFLICT',
-              message: '任务 UUID 已存在，请使用新的 uuid 重新提交'
-            }
-          }
-        };
-      }
-      throw error;
-    }
-
-    if (!dbResult) {
-      return { status: 500, body: { success: false, error: { code: 'TASK_CREATE_FAILED', message: '创建任务失败' } } };
-    }
-
-    /**
-     * In-server instant path. Delivers an instant message through this
-     * server's own task queue (create task → process by UUID → delete task).
-     * The task is written to the database before processing, so delivery is
-     * not tied to the request connection: even if the client disconnects, the
-     * row stays and the generation keeps running (and can be retried) for as
-     * long as it needs. Use this when you have a database and want long or
-     * guaranteed-complete generations with no dropped messages.
-     *
-     * The stateless alternative is `@rei-standard/amsg-instant`: it streams
-     * over SSE with a Web Push backup and needs no database, which makes it a
-     * good fit for edge runtimes (e.g. Cloudflare Workers). Its work rides the
-     * response connection, so after the client disconnects it only has the
-     * platform's brief grace window to finish (≈20-30s observed on Deno
-     * Deploy) — ideal for short instant messages that complete quickly.
-     */
-    // Instant type: send immediately
-    if (payload.messageType === 'instant') {
-      try {
-        const sendResult = await processMessagesByUuid(taskUuid, {
-          ...ctx,
-          db,
-          masterKey
-        }, 2, userId, masterKey);
-
-        if (!sendResult.success) {
-          return { status: 500, body: { success: false, error: { code: 'MESSAGE_SEND_FAILED', message: '消息发送失败', details: sendResult.error } } };
-        }
-
-        return {
-          status: 200,
-          body: {
-            success: true,
-            data: {
-              uuid: taskUuid,
-              contactName: payload.contactName,
-              messagesSent: sendResult.messagesSent,
-              sentAt: new Date().toISOString(),
-              status: 'sent',
-              retriesUsed: sendResult.retriesUsed || 0
-            }
-          }
-        };
-      } catch (error) {
-        return { status: 500, body: { success: false, error: { code: 'MESSAGE_SEND_FAILED', message: '消息发送失败', details: { error: error.message } } } };
-      }
-    }
-
-    // Non-instant: return scheduled response
-    return {
-      status: 201,
-      body: {
-        success: true,
-        data: {
-          id: dbResult.id,
-          uuid: dbResult.uuid,
-          contactName: payload.contactName,
-          nextSendAt: dbResult.next_send_at,
-          status: dbResult.status,
-          createdAt: dbResult.created_at
-        }
-      }
-    };
-  }
-
-  return { POST };
-}
-
-/**
- * Scheduled tick core: fetch due tasks, deliver, reschedule/retry, cleanup.
- * Extracted verbatim from the send-notifications handler so both the HTTP
- * handler (multi-tenant) and the CF scheduled() path (single-user) share it.
- *
- * 每个 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);
-
-  const MAX_CONCURRENT = 8;
-  const results = {
-    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 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 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) {
-      results.failedTasks.push({ taskId: task.id, reason, status: 'retry_update_failed', updateError: updateError.message });
-    }
-  }
-
-  async function handlePostSendPersistenceFailure(task, reason) {
-    results.failedCount++;
-    let markedSent = false;
-    try {
-      await updateAndRelease(task.id, { status: 'sent', retry_count: 0 });
-      markedSent = true;
-    } catch (_markSentError) {
-      markedSent = false;
-    }
-    results.failedTasks.push({
-      taskId: task.id,
-      reason,
-      status: markedSent ? 'post_send_cleanup_failed_marked_sent' : 'post_send_cleanup_failed',
-      messageDelivered: true
-    });
-  }
-
-  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);
-    } catch (error) {
-      await handleDeliveryFailure(task, error.message || '消息发送失败');
-      return;
-    }
-
-    if (!sendResult.success) {
-      await handleDeliveryFailure(task, sendResult.error || '消息发送失败');
-      return;
-    }
-
-    try {
-      const userKey = await deriveUserEncryptionKey(task.user_id, masterKey);
-      const decryptedPayload = JSON.parse(await decryptFromStorage(task.encrypted_payload, userKey));
-
-      if (decryptedPayload.recurrenceType === 'none') {
-        await db.deleteTaskById(task.id);
-        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 updateAndRelease(task.id, { next_send_at: nextSendAt.toISOString(), retry_count: 0 });
-        results.updatedRecurringTasks++;
-      }
-
-      results.successCount++;
-    } catch (error) {
-      await handlePostSendPersistenceFailure(task, error.message || '发送后状态更新失败');
-    }
-  }
-
-  const taskQueue = [...tasks];
-  const processing = [];
-
-  while (taskQueue.length > 0 || processing.length > 0) {
-    while (processing.length < MAX_CONCURRENT && taskQueue.length > 0) {
-      const task = taskQueue.shift();
-      const promise = processTask(task);
-      processing.push(promise);
-      promise.finally(() => {
-        const index = processing.indexOf(promise);
-        if (index > -1) processing.splice(index, 1);
-      });
-    }
-    if (processing.length > 0) {
-      await Promise.race(processing);
-    }
-  }
-
-  await db.cleanupOldTasks(7);
-
-  const executionTime = Date.now() - startTime;
-
-  return {
-    totalTasks: results.totalTasks,
-    successCount: results.successCount,
-    failedCount: results.failedCount,
-    processedAt: new Date().toISOString(),
-    executionTime,
-    details: {
-      claimSkippedTasks: results.claimSkippedTasks,
-      deletedOnceOffTasks: results.deletedOnceOffTasks,
-      updatedRecurringTasks: results.updatedRecurringTasks,
-      failedTasks: results.failedTasks
-    }
-  };
-}
-
-/**
- * Handler: update-message
- * ReiStandard SDK v2.0.1
- *
- * @param {Object} ctx - Server context.
- * @returns {{ PUT: function }}
- */
-
-
-function createUpdateMessageHandler(ctx) {
-  async function PUT(url, headers, body) {
-    const tenantResult = await ctx.tenantManager.resolveTenant(headers, { url });
-    if (!tenantResult.ok) {
-      return tenantResult.error;
-    }
-
-    const tenantCtx = tenantResult.context;
-    const db = tenantCtx.db;
-    const masterKey = tenantCtx.masterKey;
-    const u = new URL(url, 'https://dummy');
-    const taskUuid = u.searchParams.get('id');
-
-    if (!taskUuid) {
-      return { status: 400, body: { success: false, error: { code: 'TASK_ID_REQUIRED', message: '缺少任务ID' } } };
-    }
-
-    const userId = getHeader(headers, 'x-user-id');
-    if (!userId) {
-      return { status: 400, body: { success: false, error: { code: 'USER_ID_REQUIRED', message: '缺少用户标识符' } } };
-    }
-    if (!isValidUUIDv4(userId)) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_USER_ID_FORMAT', message: 'X-User-Id 必须是 UUID v4 格式' } } };
-    }
-
-    const isEncrypted = getHeader(headers, 'x-payload-encrypted') === 'true';
-    const encryptionVersion = getHeader(headers, 'x-encryption-version');
-
-    if (!isEncrypted) {
-      return { status: 400, body: { success: false, error: { code: 'ENCRYPTION_REQUIRED', message: '请求体必须加密' } } };
-    }
-
-    if (encryptionVersion !== '1') {
-      return { status: 400, body: { success: false, error: { code: 'UNSUPPORTED_ENCRYPTION_VERSION', message: '加密版本不支持' } } };
-    }
-
-    const parsedBody = parseEncryptedBody(body);
-    if (!parsedBody.ok) {
-      return { status: 400, body: { success: false, error: parsedBody.error } };
-    }
-
-    const encryptedBody = parsedBody.data;
-    const userKey = await deriveUserEncryptionKey(userId, masterKey);
-    let updates;
-
-    try {
-      updates = await decryptPayload(encryptedBody, userKey);
-    } catch (_error) {
-      return { status: 400, body: { success: false, error: { code: 'DECRYPTION_FAILED', message: '请求体解密失败' } } };
-    }
-
-    if (!isPlainObject(updates)) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误' } } };
-    }
-
-    if (updates.nextSendAt && !isValidISO8601(updates.nextSendAt)) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['nextSendAt'] } } } };
-    }
-
-    if (updates.recurrenceType && !['none', 'daily', 'weekly'].includes(updates.recurrenceType)) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['recurrenceType'] } } } };
-    }
-
-    if (
-      Object.prototype.hasOwnProperty.call(updates, 'maxTokens') &&
-      updates.maxTokens !== null &&
-      (!Number.isInteger(updates.maxTokens) || updates.maxTokens <= 0)
-    ) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['maxTokens'] } } } };
-    }
-
-    // Reject updates that try to set both completePrompt and messages at
-    // once. We don't enforce one-of-required here (callers may patch other
-    // fields), but the two prompt sources are mutually exclusive and must
-    // stay that way in storage too.
-    if (
-      updates.completePrompt &&
-      updates.messages !== undefined && updates.messages !== null
-    ) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: 'completePrompt 与 messages 不能同时更新（二选一）', details: { invalidFields: ['completePrompt', 'messages'] } } } };
-    }
-    if (updates.messages !== undefined && updates.messages !== null) {
-      const msgErr = validateLlmMessagesArray(updates.messages);
-      if (msgErr) {
-        return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: msgErr, details: { invalidFields: ['messages'] } } } };
-      }
-    }
-    if (
-      Object.prototype.hasOwnProperty.call(updates, 'temperature') &&
-      updates.temperature !== null &&
-      (typeof updates.temperature !== 'number' || !Number.isFinite(updates.temperature))
-    ) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['temperature'] } } } };
-    }
-    if (Object.prototype.hasOwnProperty.call(updates, 'splitPattern')) {
-      const splitErr = validateSplitPattern(updates.splitPattern);
-      if (splitErr) {
-        return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: splitErr, details: { invalidFields: ['splitPattern'] } } } };
-      }
-    }
-    if (Object.prototype.hasOwnProperty.call(updates, 'avatarUrl')) {
-      const avatarErr = validateAvatarUrl(updates.avatarUrl);
-      if (avatarErr) {
-        // Soft-strip: drop the bad avatarUrl from the patch (keeps the
-        // existing stored avatar untouched) and continue applying the rest
-        // of the update. See standards §6.2.
-        console.warn('[amsg-server] update-message avatarUrl 不合法，已忽略：', avatarErr);
-        delete updates.avatarUrl;
-      }
-    }
-
-    // Fetch existing task
-    const existingTask = await db.getTaskByUuid(taskUuid, userId);
-
-    if (!existingTask) {
-      const taskStatus = await db.getTaskStatus(taskUuid, userId);
-      if (!taskStatus) {
-        return { status: 404, body: { success: false, error: { code: 'TASK_NOT_FOUND', message: '指定的任务不存在或已被删除' } } };
-      }
-      return { status: 409, body: { success: false, error: { code: 'TASK_ALREADY_COMPLETED', message: '任务已完成或已失败，无法更新' } } };
-    }
-
-    const existingData = JSON.parse(await decryptFromStorage(existingTask.encrypted_payload, userKey));
-
-    // When the caller switches prompt source (completePrompt ↔ messages),
-    // null out the other so storage stays one-of (matches schedule-message
-    // shape and prevents buildAiRequestBody from accidentally seeing both).
-    const promptUpdates = {};
-    if (updates.completePrompt) {
-      promptUpdates.completePrompt = updates.completePrompt;
-      promptUpdates.messages = null;
-    } else if (updates.messages !== undefined && updates.messages !== null) {
-      promptUpdates.messages = updates.messages;
-      promptUpdates.completePrompt = null;
-    }
-
-    const updatedData = {
-      ...existingData,
-      ...promptUpdates,
-      ...(updates.userMessage && { userMessage: updates.userMessage }),
-      ...(updates.recurrenceType && { recurrenceType: updates.recurrenceType }),
-      ...(updates.avatarUrl && { avatarUrl: updates.avatarUrl }),
-      ...(updates.metadata && { metadata: updates.metadata }),
-      ...(Object.prototype.hasOwnProperty.call(updates, 'maxTokens') && { maxTokens: updates.maxTokens ?? null }),
-      ...(Object.prototype.hasOwnProperty.call(updates, 'temperature') && { temperature: updates.temperature ?? null }),
-      // splitPattern: hasOwnProperty so that explicit `null` (= revert to
-      // default) doesn't get swallowed by truthy-spread the way the optional
-      // string fields above are.
-      ...(Object.prototype.hasOwnProperty.call(updates, 'splitPattern') && { splitPattern: updates.splitPattern ?? null })
-    };
-
-    const encryptedPayload = await encryptForStorage(JSON.stringify(updatedData), userKey);
-    const extraFields = updates.nextSendAt ? { next_send_at: updates.nextSendAt } : undefined;
-
-    const result = await db.updateTaskByUuid(taskUuid, userId, encryptedPayload, extraFields);
-
-    if (!result) {
-      return { status: 409, body: { success: false, error: { code: 'UPDATE_CONFLICT', message: '任务更新失败，任务可能已被修改或删除' } } };
-    }
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        data: {
-          uuid: taskUuid,
-          updatedFields: Object.keys(updates),
-          updatedAt: result.updated_at
-        }
-      }
-    };
-  }
-
-  return { PUT };
-}
-
-/**
- * Handler: cancel-message
- * ReiStandard SDK v2.0.1
- *
- * @param {Object} ctx - Server context.
- * @returns {{ DELETE: function }}
- */
-
-
-function createCancelMessageHandler(ctx) {
-  async function DELETE(url, headers) {
-    const tenantResult = await ctx.tenantManager.resolveTenant(headers, { url });
-    if (!tenantResult.ok) {
-      return tenantResult.error;
-    }
-
-    const db = tenantResult.context.db;
-    const u = new URL(url, 'https://dummy');
-    const taskUuid = u.searchParams.get('id');
-
-    if (!taskUuid) {
-      return { status: 400, body: { success: false, error: { code: 'TASK_ID_REQUIRED', message: '缺少任务ID' } } };
-    }
-
-    const userId = getHeader(headers, 'x-user-id');
-    if (!userId) {
-      return { status: 400, body: { success: false, error: { code: 'USER_ID_REQUIRED', message: '缺少用户标识符' } } };
-    }
-    if (!isValidUUIDv4(userId)) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_USER_ID_FORMAT', message: 'X-User-Id 必须是 UUID v4 格式' } } };
-    }
-
-    const deleted = await db.deleteTaskByUuid(taskUuid, userId);
-
-    if (!deleted) {
-      return {
-        status: 404,
-        body: { success: false, error: { code: 'TASK_NOT_FOUND', message: '指定的任务不存在或已被删除' } }
-      };
-    }
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        data: { uuid: taskUuid, message: '任务已成功取消', deletedAt: new Date().toISOString() }
-      }
-    };
-  }
-
-  return { DELETE };
-}
-
-/**
- * Handler: messages
- * ReiStandard SDK v2.0.1
- *
- * @param {Object} ctx - Server context.
- * @returns {{ GET: function }}
- */
-
-
-function createMessagesHandler(ctx) {
-  async function GET(url, headers) {
-    const tenantResult = await ctx.tenantManager.resolveTenant(headers, { url });
-    if (!tenantResult.ok) {
-      return tenantResult.error;
-    }
-
-    const tenantCtx = tenantResult.context;
-    const db = tenantCtx.db;
-    const masterKey = tenantCtx.masterKey;
-    const userId = getHeader(headers, 'x-user-id');
-
-    if (!userId) {
-      return {
-        status: 400,
-        body: { success: false, error: { code: 'USER_ID_REQUIRED', message: '必须提供 X-User-Id 请求头' } }
-      };
-    }
-    if (!isValidUUIDv4(userId)) {
-      return {
-        status: 400,
-        body: { success: false, error: { code: 'INVALID_USER_ID_FORMAT', message: 'X-User-Id 必须是 UUID v4 格式' } }
-      };
-    }
-
-    const u = new URL(url, 'https://dummy');
-    const status = u.searchParams.get('status') || 'all';
-    const limit = Math.min(parseInt(u.searchParams.get('limit') || '20', 10), 100);
-    const offset = parseInt(u.searchParams.get('offset') || '0', 10);
-
-    if (isNaN(limit) || limit < 1) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_PARAMETERS', message: 'limit 参数无效，必须为正整数' } } };
-    }
-
-    if (isNaN(offset) || offset < 0) {
-      return { status: 400, body: { success: false, error: { code: 'INVALID_PARAMETERS', message: 'offset 参数无效，必须为非负整数' } } };
-    }
-
-    const { tasks, total } = await db.listTasks(userId, { status, limit, offset });
-
-    const userKey = await deriveUserEncryptionKey(userId, masterKey);
-
-    const decryptedTasks = await Promise.all(tasks.map(async task => {
-      const decrypted = JSON.parse(await decryptFromStorage(task.encrypted_payload, userKey));
-      return {
-        id: task.id,
-        uuid: task.uuid,
-        contactName: decrypted.contactName,
-        messageType: task.message_type,
-        messageSubtype: decrypted.messageSubtype,
-        nextSendAt: task.next_send_at,
-        recurrenceType: decrypted.recurrenceType,
-        status: task.status,
-        retryCount: task.retry_count,
-        createdAt: task.created_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
-      };
-    }));
-
-    const responsePayload = {
-      tasks: decryptedTasks,
-      pagination: { total, limit, offset, hasMore: offset + limit < total }
-    };
-    const encryptedResponse = await encryptPayload(responsePayload, userKey);
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        encrypted: true,
-        version: 1,
-        data: encryptedResponse
-      }
-    };
-  }
-
-  return { GET };
-}
-
-/**
- * SQLite (Cloudflare D1) dialect schema for scheduled_messages.
- *
- * Differences from the Postgres schema (adapters/schema.js):
- *   - id: INTEGER PRIMARY KEY AUTOINCREMENT (vs SERIAL)
- *   - timestamps stored as TEXT ISO8601 UTC (vs TIMESTAMP WITH TIME ZONE)
- *   - no NOW()/DEFAULT; the adapter always writes timestamps explicitly
- *   - retry_count is NOT NULL here (Postgres omits NOT NULL); every write path
- *     sets it explicitly, so the tighter constraint just documents that intent
- * Partial indexes and CHECK constraints are native to SQLite, so they carry over.
- * Index entries mirror the Postgres INDEXES shape ({ name, sql, description,
- * critical }) so both adapters' initSchema() return the same index metadata.
- */
-
-const SQLITE_TABLE_SQL = `
-  CREATE TABLE IF NOT EXISTS scheduled_messages (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    user_id TEXT NOT NULL,
-    uuid TEXT,
-    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
-  )
-`;
-
-/**
- * 建表语句用的是 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',
-    sql: `CREATE INDEX IF NOT EXISTS idx_pending_tasks_optimized
-          ON scheduled_messages (status, next_send_at, id, retry_count)
-          WHERE status = 'pending'`,
-    description: 'Main query index (Cron Job finds pending tasks)',
-    critical: false
-  },
-  {
-    name: 'idx_cleanup_completed',
-    sql: `CREATE INDEX IF NOT EXISTS idx_cleanup_completed
-          ON scheduled_messages (status, updated_at)
-          WHERE status IN ('sent', 'failed')`,
-    description: 'Cleanup query index',
-    critical: false
-  },
-  {
-    name: 'idx_failed_retry',
-    sql: `CREATE INDEX IF NOT EXISTS idx_failed_retry
-          ON scheduled_messages (status, retry_count, next_send_at)
-          WHERE status = 'failed' AND retry_count < 3`,
-    description: 'Failed retry index',
-    critical: false
-  },
-  {
-    name: 'idx_user_id',
-    sql: `CREATE INDEX IF NOT EXISTS idx_user_id
-          ON scheduled_messages (user_id)`,
-    description: 'User task query index',
-    critical: false
-  },
-  {
-    name: 'uidx_uuid',
-    sql: `CREATE UNIQUE INDEX IF NOT EXISTS uidx_uuid
-          ON scheduled_messages (uuid)
-          WHERE uuid IS NOT NULL`,
-    description: 'UUID uniqueness guard',
-    critical: true
-  }
-];
-
-// client_state: cloud mirror of client-side state for the single-user
-// deployment. One live copy per (user, namespace, key) — not per-task
-// snapshots. The client is the only writer (batch upsert, last-write-wins
-// on updated_at); fire-time hooks are the reader. `value` holds
-// encryptForStorage ciphertext. `updated_at` is a caller-supplied epoch-ms
-// INTEGER (unlike scheduled_messages' ISO TEXT) so conflict resolution
-// compares without parsing. Single-user/SQLite only — no Postgres mirror.
-const CLIENT_STATE_TABLE_SQL = `
-  CREATE TABLE IF NOT EXISTS client_state (
-    user_id TEXT NOT NULL,
-    namespace TEXT NOT NULL,
-    key TEXT NOT NULL,
-    value TEXT NOT NULL,
-    updated_at INTEGER NOT NULL,
-    PRIMARY KEY (user_id, namespace, key)
-  )
-`;
-
-/**
- * Cloudflare D1 (SQLite) Database Adapter.
- *
- * @implements {import('./interface.js').DbAdapter}
- *
- * Timestamps are stored as ISO8601 UTC TEXT. Every timestamp is normalized
- * with new Date(v).toISOString() before store/compare so lexical ordering
- * equals chronological ordering (mixed offsets like +08:00 vs Z are unified).
- */
-
-
-// Update methods build a dynamic SET clause from object keys. Callers pass only
-// hardcoded column names today, but enforcing a whitelist keeps a future caller
-// 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', 'lease_until', '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) {
-    /** @private */
-    this._db = db;
-  }
-
-  /** @private */
-  _now() {
-    return new Date().toISOString();
-  }
-
-  /** @private */
-  _iso(value) {
-    const d = new Date(value);
-    if (Number.isNaN(d.getTime())) {
-      throw new Error(`[amsg-server D1] invalid timestamp: ${value}`);
-    }
-    return d.toISOString();
-  }
-
-  async initSchema() {
-    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 {
-        await this._db.prepare(index.sql).run();
-        indexResults.push({ name: index.name, status: 'success', description: index.description, critical: !!index.critical });
-      } catch (error) {
-        indexResults.push({ name: index.name, status: 'failed', description: index.description, critical: !!index.critical, error: error.message });
-      }
-    }
-
-    const criticalFailures = indexResults.filter((i) => i.critical && i.status === 'failed');
-    if (criticalFailures.length > 0) {
-      const names = criticalFailures.map((i) => i.name).join(', ');
-      throw new Error(
-        `Critical index creation failed (${names}). ` +
-        'Please remove duplicate UUID rows and run initSchema again.'
-      );
-    }
-
-    return {
-      columnsCreated: 11,
-      indexesCreated: indexResults.filter((r) => r.status === 'success').length,
-      indexesFailed: indexResults.filter((r) => r.status === 'failed').length,
-      columns: [],
-      indexes: indexResults
-    };
-  }
-
-  async dropSchema() {
-    await this._db.prepare('DROP TABLE IF EXISTS scheduled_messages').run();
-    await this._db.prepare('DROP TABLE IF EXISTS client_state').run();
-  }
-
-  async createTask(params) {
-    const now = this._now();
-    const nextSendAt = this._iso(params.next_send_at);
-    const res = await this._db.prepare(
-      `INSERT INTO scheduled_messages
-        (user_id, uuid, encrypted_payload, next_send_at, message_type, status, retry_count, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, 'pending', 0, ?, ?)`
-    ).bind(params.user_id, params.uuid, params.encrypted_payload, nextSendAt, params.message_type, now, now).run();
-
-    const id = res.meta.last_row_id;
-    return this._db.prepare(
-      `SELECT id, uuid, next_send_at, status, created_at FROM scheduled_messages WHERE id = ?`
-    ).bind(id).first();
-  }
-
-  async getTaskByUuid(uuid, userId) {
-    return this._db.prepare(
-      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count
-       FROM scheduled_messages
-       WHERE uuid = ? AND user_id = ? AND status = 'pending'
-       LIMIT 1`
-    ).bind(uuid, userId).first();
-  }
-
-  async getTaskByUuidOnly(uuid) {
-    return this._db.prepare(
-      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count
-       FROM scheduled_messages
-       WHERE uuid = ? AND status = 'pending'
-       LIMIT 1`
-    ).bind(uuid).first();
-  }
-
-  async updateTaskById(taskId, updates) {
-    const sets = [];
-    const values = [];
-    for (const [key, value] of Object.entries(updates)) {
-      if (!UPDATABLE_COLUMNS.has(key)) {
-        throw new Error(`[amsg-server D1] rejected unknown update column: ${key}`);
-      }
-      sets.push(`${key} = ?`);
-      values.push(key === 'next_send_at' ? this._iso(value) : value);
-    }
-    // Callers may pass updated_at explicitly (tests); otherwise stamp now.
-    if (!Object.prototype.hasOwnProperty.call(updates, 'updated_at')) {
-      sets.push('updated_at = ?');
-      values.push(this._now());
-    }
-    values.push(taskId);
-
-    await this._db.prepare(
-      `UPDATE scheduled_messages SET ${sets.join(', ')} WHERE id = ?`
-    ).bind(...values).run();
-
-    return this._db.prepare('SELECT * FROM scheduled_messages WHERE id = ?').bind(taskId).first();
-  }
-
-  async updateTaskByUuid(uuid, userId, encryptedPayload, extraFields) {
-    const now = this._now();
-    const sets = ['encrypted_payload = ?', 'updated_at = ?'];
-    const values = [encryptedPayload, now];
-    if (extraFields) {
-      for (const [key, value] of Object.entries(extraFields)) {
-        if (!UPDATABLE_COLUMNS.has(key)) {
-          throw new Error(`[amsg-server D1] rejected unknown update column: ${key}`);
-        }
-        sets.push(`${key} = ?`);
-        values.push(key === 'next_send_at' ? this._iso(value) : value);
-      }
-    }
-    values.push(uuid, userId);
-
-    const res = await this._db.prepare(
-      `UPDATE scheduled_messages SET ${sets.join(', ')}
-       WHERE uuid = ? AND user_id = ? AND status = 'pending'`
-    ).bind(...values).run();
-
-    if (!res.meta.changes) return null;
-    return { uuid, updated_at: now };
-  }
-
-  async deleteTaskById(taskId) {
-    const res = await this._db.prepare('DELETE FROM scheduled_messages WHERE id = ?').bind(taskId).run();
-    return res.meta.changes > 0;
-  }
-
-  async deleteTaskByUuid(uuid, userId) {
-    const res = await this._db.prepare(
-      'DELETE FROM scheduled_messages WHERE uuid = ? AND user_id = ?'
-    ).bind(uuid, userId).run();
-    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(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 = ?'];
-    const params = [userId];
-    if (status !== 'all') {
-      conditions.push('status = ?');
-      params.push(status);
-    }
-    const where = conditions.join(' AND ');
-
-    const countRow = await this._db.prepare(
-      `SELECT COUNT(*) as count FROM scheduled_messages WHERE ${where}`
-    ).bind(...params).first();
-    const total = Number(countRow.count) || 0;
-
-    const res = await this._db.prepare(
-      `SELECT id, user_id, uuid, encrypted_payload, message_type, next_send_at, status, retry_count, created_at, updated_at
-       FROM scheduled_messages
-       WHERE ${where}
-       ORDER BY next_send_at ASC
-       LIMIT ? OFFSET ?`
-    ).bind(...params, limit, offset).all();
-
-    return { tasks: res.results || [], total };
-  }
-
-  async cleanupOldTasks(days = 7) {
-    const safeDays = Math.max(1, Math.floor(Number(days)));
-    const cutoff = new Date(Date.now() - safeDays * 24 * 60 * 60 * 1000).toISOString();
-    const res = await this._db.prepare(
-      `DELETE FROM scheduled_messages
-       WHERE status IN ('sent', 'failed') AND updated_at < ?`
-    ).bind(cutoff).run();
-    return res.meta.changes || 0;
-  }
-
-  async getTaskStatus(uuid, userId) {
-    const row = await this._db.prepare(
-      'SELECT status FROM scheduled_messages WHERE uuid = ? AND user_id = ? LIMIT 1'
-    ).bind(uuid, userId).first();
-    return row ? row.status : null;
-  }
-
-  // ── client_state (single-user cloud state mirror) ──────────────────────
-
-  /**
-   * Batch upsert. Last-write-wins per (namespace, key): an entry older
-   * than the stored row (updatedAt strictly lower) is skipped; equal or
-   * newer overwrites. Values arrive pre-encrypted (the handler encrypts).
-   *
-   * `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
-   * background window, so N sequential round trips could eat the whole
-   * window. Bindings without batch() (e.g. the sqlite test shim, custom
-   * adapters) fall back to a sequential loop.
-   *
-   * @param {string} userId
-   * @param {Array<{ namespace: string, key: string, value: string, updatedAt: number }>} entries
-   * @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）。
-   */
-  async upsertClientState(userId, entries, cleanups = []) {
-    const UPSERT_SQL =
-      `INSERT INTO client_state (user_id, namespace, key, value, updated_at)
-       VALUES (?, ?, ?, ?, ?)
-       ON CONFLICT (user_id, namespace, key) DO UPDATE SET
-         value = excluded.value,
-         updated_at = excluded.updated_at
-       WHERE excluded.updated_at >= client_state.updated_at`;
-    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) => (
-        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)
-      ),
-    ];
-
-    let results;
-    if (typeof this._db.batch === 'function') {
-      results = await this._db.batch(buildStatements());
-    } else {
-      results = [];
-      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 wrote of outcomes) {
-      if (wrote) upserted++; else skipped++;
-    }
-    return { upserted, skipped, outcomes };
-  }
-
-  /**
-   * All entries of one namespace (values still encrypted).
-   *
-   * @param {string} userId
-   * @param {string} namespace
-   * @returns {Promise<Array<{ namespace: string, key: string, value: string, updated_at: number }>>}
-   */
-  async getClientState(userId, namespace) {
-    const res = await this._db.prepare(
-      `SELECT namespace, key, value, updated_at
-       FROM client_state
-       WHERE user_id = ? AND namespace = ?
-       ORDER BY key ASC`
-    ).bind(userId, namespace).all();
-    return res.results || [];
-  }
-
-  /**
-   * Wipe every entry of this user.
-   *
-   * @param {string} userId
-   * @returns {Promise<number>} rows deleted
-   */
-  async clearClientState(userId) {
-    const res = await this._db.prepare('DELETE FROM client_state WHERE user_id = ?').bind(userId).run();
-    return res.meta.changes || 0;
-  }
-}
-
-/**
- * Create a D1 adapter from a Cloudflare D1 binding (env.DB).
- * @param {{ prepare: (sql: string) => any }} db
- * @returns {import('./interface.js').DbAdapter}
- */
-function createD1Adapter(db) {
-  if (!db || typeof db.prepare !== 'function') {
-    throw new Error('[amsg-server] createD1Adapter requires a D1 database binding (env.DB)');
-  }
-  return new D1Adapter(db);
-}
-
-/**
- * Portable constant-time string comparison.
- *
- * Runs identically on Node (tests) and Cloudflare Workers (prod). We avoid
- * both node:crypto's timingSafeEqual (undefined on Workers historically) and
- * crypto.subtle.timingSafeEqual (absent on Node). Instead we HMAC-SHA256 both
- * inputs under one fresh random key, then compare the two digests. Because the
- * key is random per call, an attacker can't precompute or replay a stable
- * timing oracle; digests are a fixed 32 bytes, so the XOR-accumulate compare
- * runs the same number of steps regardless of input length, with no early-out.
- *
- * globalThis.crypto (Web Crypto) is available on Node >= 20 and on Workers.
- */
-async function constantTimeEqual(a, b) {
-  const enc = new TextEncoder();
-  const keyBytes = globalThis.crypto.getRandomValues(new Uint8Array(32));
-  const key = await globalThis.crypto.subtle.importKey(
-    'raw',
-    keyBytes,
-    { name: 'HMAC', hash: 'SHA-256' },
-    false,
-    ['sign']
-  );
-  const da = new Uint8Array(await globalThis.crypto.subtle.sign('HMAC', key, enc.encode(String(a))));
-  const db = new Uint8Array(await globalThis.crypto.subtle.sign('HMAC', key, enc.encode(String(b))));
-
-  let diff = 0;
-  for (let i = 0; i < da.length; i++) {
-    diff |= da[i] ^ db[i];
-  }
-  return diff === 0;
-}
-
-/**
- * Single-user tenant context manager.
- *
- * Interface-compatible with createTenantContextManager (resolveTenant /
- * initializeTenant), so the existing business handlers reuse it unchanged.
- * No blob registry, no tenant token — db and masterKey come from the caller
- * (the Worker resolves them from env + D1 binding per request).
- */
-
-
-function createSingleUserContextManager({ db, masterKey, serverToken } = {}) {
-  if (!db) throw new Error('[amsg-server single-user] db (adapter) is required');
-  if (!masterKey) throw new Error('[amsg-server single-user] masterKey is required');
-  const token = String(serverToken || '').trim();
-
-  async function isAuthorized(headers) {
-    if (!token) return true; // open when no shared secret configured
-    const provided = getHeader(headers, 'x-client-token');
-    if (!provided) return false;
-    return constantTimeEqual(provided, token);
-  }
-
-  async function resolveTenant(headers) {
-    if (!(await isAuthorized(headers))) {
-      return {
-        ok: false,
-        error: {
-          status: 401,
-          body: { success: false, error: { code: 'INVALID_CLIENT_TOKEN', message: '共享密钥无效或缺失' } }
-        }
-      };
-    }
-    return {
-      ok: true,
-      context: { tenantId: 'single', tokenType: 'tenant', db, masterKey }
-    };
-  }
-
-  async function initializeTenant() {
-    const schema = await db.initSchema();
-    return { tenantId: 'single', schema };
-  }
-
-  return { resolveTenant, initializeTenant };
-}
-
-/**
- * Handler: single-user-init
- *
- * Idempotent "just create the tables" endpoint for single-user deployments
- * (the degenerate form of init-tenant). Reuses resolveTenant purely to enforce
- * the optional shared secret, then runs initSchema. Issues no token.
- *
- * @param {Object} ctx - Single-user server context (ctx.tenantManager).
- * @returns {{ POST: function }}
- */
-function createSingleUserInitHandler(ctx) {
-  async function POST(headers /* , body */) {
-    const auth = await ctx.tenantManager.resolveTenant(headers || {});
-    if (!auth.ok) {
-      return auth.error;
-    }
-    try {
-      const result = await ctx.tenantManager.initializeTenant();
-      return {
-        status: 200,
-        body: { success: true, data: { tenantId: result.tenantId, schema: result.schema } }
-      };
-    } catch (error) {
-      return {
-        status: 500,
-        body: { success: false, error: { code: 'INIT_FAILED', message: error.message } }
-      };
-    }
-  }
-
-  return { POST };
-}
-
-/**
- * Handler: vapid-public-key
- *
- * Exposes this worker's own VAPID public key so a browser frontend can build a
- * Web Push subscription (`applicationServerKey`) at runtime. Each self-hosted
- * worker owns its keypair, so the key can't be baked into the frontend — it
- * pulls it from here.
- *
- * Auth funnels through the same resolveTenant as every other endpoint, so with
- * a serverToken configured this route requires `X-Client-Token` too (the
- * all-or-nothing contract). The public key itself is not a secret; gating it
- * just keeps every endpoint consistent.
- *
- * @param {Object} ctx - Server context ({ vapid, tenantManager, ... }).
- * @returns {{ GET: function }}
- */
-
-function createVapidPublicKeyHandler(ctx) {
-  async function GET(url, headers) {
-    const effectiveHeaders = headers || url || {};
-    const tenantResult = await ctx.tenantManager.resolveTenant(effectiveHeaders);
-    if (!tenantResult.ok) {
-      return tenantResult.error;
-    }
-
-    const publicKey = ctx.vapid && ctx.vapid.publicKey;
-    if (!publicKey) {
-      return {
-        status: 503,
-        body: {
-          success: false,
-          error: {
-            code: 'VAPID_NOT_CONFIGURED',
-            message: 'VAPID 公钥未配置：请为本 Worker 设置 VAPID_PUBLIC_KEY'
-          }
-        }
-      };
-    }
-
-    return {
-      status: 200,
-      body: { success: true, publicKey }
-    };
-  }
-
-  return { GET };
-}
-
-/**
- * Handler: client-state
- *
- * Cloud mirror of client-side state for the single-user deployment. The
- * client batch-syncs entries up (PUT) whenever convenient — e.g. in the
- * few-seconds window before iOS backgrounds the page — and fire-time
- * hooks read them back via ctx.readState(namespace). One live copy per
- * (user, namespace, key).
- *
- * 反方向也通：hook 用 ctx.writeState() 写进来的条目和这里写的完全同构
- * （落库共用 lib/client-state-store.js），客户端 GET 回去读得到，读的时候
- * 不区分是谁写的。
- *
- *   PUT    /client-state                 batch upsert, last-write-wins on updatedAt
- *   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
- * encryptForStorage ciphertext under the per-user key, and GET responses
- * ride the existing encrypted-response envelope.
- */
-
-// "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 = MAX_STATE_ENTRIES_PER_BATCH;
-
-function err(status, code, message, details) {
-  const error = details === undefined ? { code, message } : { code, message, details };
-  return { status, body: { success: false, error } };
-}
-
-function requireUserId(headers) {
-  const userId = getHeader(headers, 'x-user-id');
-  if (!userId) return { error: err(400, 'USER_ID_REQUIRED', '缺少用户标识符') };
-  if (!isValidUUIDv4(userId)) return { error: err(400, 'INVALID_USER_ID_FORMAT', 'X-User-Id 必须是 UUID v4 格式') };
-  return { userId };
-}
-
-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 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 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 rejectEntry(entry, index, 'INVALID_STATE_VALUE', `entries[${index}].value 必须是字符串（宿主自行序列化）`);
-  }
-  const bytes = stateValueBytes(entry.value);
-  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 rejectEntry(entry, index, 'INVALID_STATE_UPDATED_AT', `entries[${index}].updatedAt 必须是正整数（epoch 毫秒）`);
-  }
-  return null;
-}
-
-function createClientStateHandler(ctx) {
-  async function PUT(headers, body) {
-    const tenantResult = await ctx.tenantManager.resolveTenant(headers);
-    if (!tenantResult.ok) return tenantResult.error;
-    const { db, masterKey } = tenantResult.context;
-
-    if (getHeader(headers, 'x-payload-encrypted') !== 'true') {
-      return err(400, 'ENCRYPTION_REQUIRED', '请求体必须加密');
-    }
-    const gate = requireUserId(headers);
-    if (gate.error) return gate.error;
-    const { userId } = gate;
-    if (getHeader(headers, 'x-encryption-version') !== '1') {
-      return err(400, 'UNSUPPORTED_ENCRYPTION_VERSION', '加密版本不支持');
-    }
-
-    const parsedBody = parseEncryptedBody(body);
-    if (!parsedBody.ok) return { status: 400, body: { success: false, error: parsedBody.error } };
-
-    const userKey = await deriveUserEncryptionKey(userId, masterKey);
-    let payload;
-    try {
-      payload = await decryptPayload(parsedBody.data, userKey);
-    } catch (error) {
-      if (error instanceof SyntaxError) {
-        return err(400, 'INVALID_PAYLOAD_FORMAT', '解密后的数据不是有效 JSON');
-      }
-      return err(400, 'DECRYPTION_FAILED', '请求体解密失败');
-    }
-    if (!isPlainObject(payload)) return err(400, 'INVALID_PAYLOAD_FORMAT', '解密后的数据必须是 JSON 对象');
-
-    const entries = payload.entries;
-    if (!Array.isArray(entries) || entries.length === 0) {
-      return err(400, 'INVALID_STATE_ENTRIES', 'entries 必须是非空数组');
-    }
-    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 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');
-    }
-
-    // 落库（加密 + 大值分块 + 旧切片清理）与 hook 的 ctx.writeState() 共用
-    // lib/client-state-store.js。这条路径只写不删，所以 deleted 恒为 0。
-    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 } };
-  }
-
-  async function GET(url, headers) {
-    const tenantResult = await ctx.tenantManager.resolveTenant(headers);
-    if (!tenantResult.ok) return tenantResult.error;
-    const { db, masterKey } = tenantResult.context;
-
-    const gate = requireUserId(headers);
-    if (gate.error) return gate.error;
-    const { userId } = gate;
-
-    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');
-    }
-
-    const userKey = await deriveUserEncryptionKey(userId, masterKey);
-    const rows = await db.getClientState(userId, namespace);
-    // 分块存储的值在这里拼回原文；块不齐全的 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 } };
-  }
-
-  async function DELETE(url, headers) {
-    const tenantResult = await ctx.tenantManager.resolveTenant(headers);
-    if (!tenantResult.ok) return tenantResult.error;
-    const { db } = tenantResult.context;
-
-    const gate = requireUserId(headers);
-    if (gate.error) return gate.error;
-    const { userId } = gate;
-
-    if (typeof db.clearClientState !== 'function') {
-      return err(501, 'CLIENT_STATE_NOT_SUPPORTED', '当前数据库适配器不支持 client_state');
-    }
-
-    const deleted = await db.clearClientState(userId);
-    return { status: 200, body: { success: true, data: { deleted } } };
-  }
-
-  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',
-  'agentic-write-state',
-  'agentic-fire-tools',
-  'agentic-schedule-task',
-  '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.
- *
- * Same shape as createReiServer ({ handlers }), but wired for a single user:
- *   - tenant context comes from createSingleUserContextManager (db + masterKey
- *     supplied by the caller; no blob registry, no tenant token)
- *   - only the 5 business handlers + an idempotent init route are exposed
- *   - send-notifications is NOT exposed over HTTP (cron runs via CF scheduled())
- *
- * @param {Object} config
- * @param {import('./adapters/interface.js').DbAdapter} config.db
- * @param {string} config.masterKey
- * @param {string} [config.serverToken]  - optional shared secret (X-Client-Token)
- * @param {{ email?: string, publicKey?: string, privateKey?: string }} [config.vapid]
- * @param {{ sendNotification: function }} [config.webpush] - web-push-compatible sender
- * @param {Object} [config.hooks] - optional fire-time hooks (see lib/agentic-fire.js):
- *   { onBeforeFire, onLLMOutput, executeToolCalls }. When omitted, AI tasks
- *   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）。
- * @param {number} [config.maxScheduledTasksPerFire] - 一次 fire 里 hook 用 ctx.scheduleTask() 最多能建几条后续任务（默认 2，0 表示不许自排）。
- * @returns {{ handlers: Object, ctx: Object }}
- */
-
-
-function createSingleUserServer(config) {
-  if (!config || !config.db) throw new Error('[amsg-server single-user] config.db is required');
-  if (!config.masterKey) throw new Error('[amsg-server single-user] config.masterKey is required');
-
-  const vapid = config.vapid || {};
-  const tenantManager = createSingleUserContextManager({
-    db: config.db,
-    masterKey: config.masterKey,
-    serverToken: config.serverToken
-  });
-
-  const ctx = {
-    vapid: {
-      email: vapid.email || '',
-      publicKey: vapid.publicKey || '',
-      privateKey: vapid.privateKey || ''
-    },
-    webpush: config.webpush || null,
-    tenantManager,
-    // Fire-time hooks (optional): the in-server instant path fires through
-    // processMessagesByUuid with this ctx, so instant-type tasks can take
-    // the agentic path too.
-    hooks: config.hooks || null,
-    maxToolIterations: config.maxToolIterations,
-    totalTimeoutMs: config.totalTimeoutMs,
-    maxStateValueBytes: config.maxStateValueBytes,
-    // hook 的 ctx.scheduleTask() 单次 fire 建任务的条数上限（默认 2）。
-    maxScheduledTasksPerFire: config.maxScheduledTasksPerFire
-  };
-
-  return {
-    ctx,
-    handlers: {
-      init: createSingleUserInitHandler(ctx),
-      getUserKey: createGetUserKeyHandler(ctx),
-      scheduleMessage: createScheduleMessageHandler(ctx),
-      updateMessage: createUpdateMessageHandler(ctx),
-      cancelMessage: createCancelMessageHandler(ctx),
-      messages: createMessagesHandler(ctx),
-      vapidPublicKey: createVapidPublicKeyHandler(ctx),
-      clientState: createClientStateHandler(ctx),
-      capabilities: createCapabilitiesHandler(ctx)
-    }
-  };
-}
-
-/**
- * Web Push — RFC 8030 (transport) + RFC 8291 (aes128gcm payload encryption)
- *           + RFC 8292 (VAPID).
- *
- * Pure-WebCrypto implementation. Zero runtime dependencies. Runs natively on
- * Cloudflare Workers, Vercel Edge, Netlify Edge, Deno, Bun, and Node ≥ 19.
- * Node 18 deployments must go through the `adapters/node` entry which
- * polyfills `globalThis.crypto` from `node:crypto.webcrypto`.
- *
- * The wire format produced here is byte-identical to the `web-push` npm
- * package and to the Push API in any modern browser, so amsg-sw and any
- * existing Web Push subscriptions keep working untouched.
- */
-
-
-// RFC 8291 fixed labels (each followed by a NUL byte per HKDF "info" framing).
-const KEY_INFO_PREFIX = utf8$1('WebPush: info\0');
-const CEK_INFO = utf8$1('Content-Encoding: aes128gcm\0');
-const NONCE_INFO = utf8$1('Content-Encoding: nonce\0');
-
-const VAPID_DEFAULT_TTL = 60;          // seconds — short, matches single-shot instant.
-const VAPID_TOKEN_LIFETIME = 12 * 3600; // 12h — comfortably under the 24h RFC 8292 cap.
-const RECORD_SIZE = 4096;               // arbitrary — must be ≥ ciphertext length.
-
-// ─── Payload budget ────────────────────────────────────────────────────
-//
-// 推送服务（FCM / APNs / Mozilla autopush）限的是 POST 上去的**密文** body，
-// 上限 4096 字节，超了当场 413，消息就没了。明文能塞多少要把 aes128gcm 的固
-// 定开销减掉：
-//
-//   密文 body = header(86) + 明文 + 填充分隔符(1) + GCM auth tag(16)
-//   header    = salt(16) + record size(4) + keyid 长度(1) + keyid(65)
-//
-// keyid 是应用服务器的 P-256 公钥，恒定 65 字节；单记录只带一个 0x02 分隔符
-// （RFC 8188 §2），不额外填充。所以开销是固定的 103 字节，明文上限
-// 4096 - 103 = 3993 字节（UTF-8 计，不是字符数）。
-// 这个换算由 webpush-webcrypto.test.mjs 钉住：上限大小的 payload 编出来的
-// body 恰好 4096 字节。
-
-/** 推送服务对加密后 body 的上限（字节）。 */
-const WEB_PUSH_MAX_BODY_BYTES = 4096;
-/** aes128gcm 固定开销：header 86 + 填充分隔符 1 + GCM tag 16。 */
-const WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = 16 + 4 + 1 + 65 + 1 + 16;
-/** 一条 push 的明文（JSON 字符串）上限，UTF-8 字节数。 */
-const MAX_PUSH_PAYLOAD_BYTES = WEB_PUSH_MAX_BODY_BYTES - WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES;
-
-const payloadEncoder = new TextEncoder();
-
-/**
- * 组 payload 前做预算用：先量骨架有多大，剩下多少字节才是能塞附加数据的额度。
- *
- * @example
- * const { remainingBytes } = measurePushPayload(JSON.stringify(basePush));
- * const excerpt = remainingBytes > 0 ? text.slice(0, remainingBytes) : '';
- *
- * @param {string} payload - 待发送的 payload 字符串（通常是 JSON.stringify 的结果）。
- * @returns {{ bytes: number, maxBytes: number, remainingBytes: number, withinLimit: boolean }}
- *   `bytes` 是 payload 的 UTF-8 字节数；`remainingBytes` 是还能加多少字节
- *   （已超限时为负）；`withinLimit` 为 false 时 sendWebPush 会抛
- *   `PUSH_PAYLOAD_TOO_LARGE`。
- */
-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,
-  };
-}
-
-/**
- * Send a single Web Push notification.
- *
- * @param {Object}   args
- * @param {Object}   args.subscription  - Standard PushSubscription JSON.
- * @param {string}   args.subscription.endpoint
- * @param {Object}   args.subscription.keys
- * @param {string}   args.subscription.keys.p256dh - base64url, 65 B uncompressed P-256 point.
- * @param {string}   args.subscription.keys.auth   - base64url, 16 B auth secret.
- * @param {string}   args.payload       - Already-stringified JSON to deliver.
- * @param {Object}   args.vapid
- * @param {string}   args.vapid.email      - VAPID `sub` (mailto: auto-prepended if missing).
- * @param {string}   args.vapid.publicKey  - base64url, 65 B uncompressed P-256 point.
- * @param {string}   args.vapid.privateKey - base64url, 32 B scalar.
- * @param {number}  [args.ttl=60]       - Push service TTL header, seconds.
- * @param {typeof fetch} [args.fetch]   - Override fetch impl (testing / proxy).
- * @returns {Promise<{ statusCode: number, body: string, headers: Headers }>}
- * @throws  {Error}  err.code = 'PUSH_PAYLOAD_TOO_LARGE' when the payload
- *                   exceeds MAX_PUSH_PAYLOAD_BYTES (nothing is sent);
- *                   err.code = 'PUSH_SEND_FAILED' on push-service error.
- */
-async function sendWebPush({ subscription, payload, vapid, ttl, fetch: fetchImpl }) {
-  if (!subscription || typeof subscription.endpoint !== 'string') {
-    throw new Error('sendWebPush: invalid subscription');
-  }
-  if (typeof payload !== 'string') {
-    throw new Error('sendWebPush: payload must be a string');
-  }
-  if (!vapid || !vapid.email || !vapid.publicKey || !vapid.privateKey) {
-    throw new Error('VAPID_CONFIG_MISSING');
-  }
-
-  const subscriptionKeys = subscription.keys || {};
-  if (typeof subscriptionKeys.p256dh !== 'string' || typeof subscriptionKeys.auth !== 'string') {
-    throw new Error('sendWebPush: subscription.keys.p256dh and .auth are required');
-  }
-
-  // 超限的 payload 发出去只会被推送服务 413 掉，用户什么也收不到。加密之前就
-  // 拦下来，让调用方拿到一个说得清的错误（宿主可以退回一条短消息 + 引用键）。
-  const size = measurePushPayload(payload);
-  if (!size.withinLimit) {
-    const err = 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)`
-    );
-    err.code = 'PUSH_PAYLOAD_TOO_LARGE';
-    err.bytes = size.bytes;
-    err.maxBytes = MAX_PUSH_PAYLOAD_BYTES;
-    throw err;
-  }
-
-  const encryptedBody = await encryptPushPayload({
-    plaintext: utf8$1(payload),
-    uaPublicKey: base64UrlToBytes(subscriptionKeys.p256dh),
-    authSecret: base64UrlToBytes(subscriptionKeys.auth),
-  });
-
-  const jwt = await buildVapidJwt({
-    audience: originOf(subscription.endpoint),
-    subject: normalizeVapidSubject(vapid.email),
-    publicKey: vapid.publicKey,
-    privateKey: vapid.privateKey,
-  });
-
-  const fetchFn = fetchImpl || globalThis.fetch;
-  if (typeof fetchFn !== 'function') {
-    throw new Error('sendWebPush: no fetch implementation available');
-  }
-
-  const res = await fetchFn(subscription.endpoint, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/octet-stream',
-      'Content-Encoding': 'aes128gcm',
-      'TTL': String(Number.isFinite(ttl) ? ttl : VAPID_DEFAULT_TTL),
-      'Authorization': `vapid t=${jwt}, k=${vapid.publicKey}`,
-    },
-    body: encryptedBody,
-  });
-
-  // Push services return 201 (RFC 8030) or 200/202 depending on implementation.
-  if (!res.ok) {
-    const text = await safeReadText(res);
-    const err = new Error(
-      `Web Push delivery failed: ${res.status} ${res.statusText || ''}${text ? ` — ${text}` : ''}`
-    );
-    err.code = 'PUSH_SEND_FAILED';
-    err.statusCode = res.status;
-    throw err;
-  }
-
-  return {
-    statusCode: res.status,
-    body: await safeReadText(res),
-    headers: res.headers,
-  };
-}
-
-// ─── RFC 8291: aes128gcm payload encryption ────────────────────────────
-
-/**
- * @param {Object} args
- * @param {Uint8Array} args.plaintext
- * @param {Uint8Array} args.uaPublicKey  - recipient p256dh, 65 B uncompressed.
- * @param {Uint8Array} args.authSecret   - recipient auth, 16 B.
- * @returns {Promise<Uint8Array>} encryption header || ciphertext
- */
-async function encryptPushPayload({ plaintext, uaPublicKey, authSecret }) {
-  // 1. Ephemeral ECDH key pair (as = "application server" per RFC 8291).
-  const asKeyPair = await globalThis.crypto.subtle.generateKey(
-    { name: 'ECDH', namedCurve: 'P-256' },
-    true,
-    ['deriveBits']
-  );
-  const asPublicRaw = new Uint8Array(
-    await globalThis.crypto.subtle.exportKey('raw', asKeyPair.publicKey)
-  );
-
-  // 2. ECDH shared secret with recipient's p256dh.
-  const uaPublicCryptoKey = await globalThis.crypto.subtle.importKey(
-    'raw',
-    uaPublicKey,
-    { name: 'ECDH', namedCurve: 'P-256' },
-    false,
-    []
-  );
-  const ecdhSecret = new Uint8Array(
-    await globalThis.crypto.subtle.deriveBits(
-      { name: 'ECDH', public: uaPublicCryptoKey },
-      asKeyPair.privateKey,
-      256
-    )
-  );
-
-  // 3. IKM = HKDF-SHA256(salt=auth_secret, ikm=ecdh_secret,
-  //                     info="WebPush: info\0" || ua_public || as_public, L=32)
-  const keyInfo = concatBytes(KEY_INFO_PREFIX, uaPublicKey, asPublicRaw);
-  const ikm = await hkdfSha256(authSecret, ecdhSecret, keyInfo, 32);
-
-  // 4. encryption_salt (random, 16 B). Goes into the header so the recipient
-  //    can re-derive CEK / NONCE.
-  const salt = randomBytes(16);
-
-  // 5. CEK = HKDF-SHA256(salt, ikm, "Content-Encoding: aes128gcm\0", 16)
-  const cekBytes = await hkdfSha256(salt, ikm, CEK_INFO, 16);
-  const cek = await globalThis.crypto.subtle.importKey(
-    'raw',
-    cekBytes,
-    { name: 'AES-GCM' },
-    false,
-    ['encrypt']
-  );
-
-  // 6. NONCE = HKDF-SHA256(salt, ikm, "Content-Encoding: nonce\0", 12)
-  const nonce = await hkdfSha256(salt, ikm, NONCE_INFO, 12);
-
-  // 7. Single-record AES-128-GCM. Padding delimiter 0x02 marks the final
-  //    (and only) record per RFC 8188 §2.
-  const padded = concatBytes(plaintext, new Uint8Array([0x02]));
-  const ciphertext = new Uint8Array(
-    await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce }, cek, padded)
-  );
-
-  // 8. aes128gcm content-encoding framing (RFC 8188 §2.1):
-  //      salt(16) || rs(4 BE) || idlen(1) || keyid(idlen) || ciphertext
-  //    For Web Push, keyid is the application-server public key (65 B).
-  const header = new Uint8Array(16 + 4 + 1 + asPublicRaw.byteLength);
-  header.set(salt, 0);
-  writeUint32BE(header, 16, RECORD_SIZE);
-  header[20] = asPublicRaw.byteLength;
-  header.set(asPublicRaw, 21);
-
-  return concatBytes(header, ciphertext);
-}
-
-/**
- * HKDF-SHA-256 (extract-then-expand) via WebCrypto.
- *
- * @param {Uint8Array} salt
- * @param {Uint8Array} ikm
- * @param {Uint8Array} info
- * @param {number}     length  - desired output length in bytes (≤ 32 in our usage).
- * @returns {Promise<Uint8Array>}
- */
-async function hkdfSha256(salt, ikm, info, length) {
-  const baseKey = await globalThis.crypto.subtle.importKey(
-    'raw',
-    toUint8(ikm),
-    { name: 'HKDF' },
-    false,
-    ['deriveBits']
-  );
-  const bits = await globalThis.crypto.subtle.deriveBits(
-    {
-      name: 'HKDF',
-      hash: 'SHA-256',
-      salt: toUint8(salt),
-      info: toUint8(info),
-    },
-    baseKey,
-    length * 8
-  );
-  return new Uint8Array(bits);
-}
-
-// ─── RFC 8292: VAPID JWT ───────────────────────────────────────────────
-
-/**
- * Build a VAPID `Authorization` JWT for a single push.
- *
- * @param {Object} args
- * @param {string} args.audience    - Origin of the push endpoint (e.g. https://fcm.googleapis.com).
- * @param {string} args.subject     - VAPID `sub` claim, typically `mailto:you@example.com`.
- * @param {string} args.publicKey   - base64url, 65 B uncompressed P-256 point.
- * @param {string} args.privateKey  - base64url, 32 B scalar.
- * @returns {Promise<string>} compact JWS (three base64url segments).
- */
-async function buildVapidJwt({ audience, subject, publicKey, privateKey }) {
-  const header = jsonToBase64Url({ typ: 'JWT', alg: 'ES256' });
-  const payload = jsonToBase64Url({
-    aud: audience,
-    exp: Math.floor(Date.now() / 1000) + VAPID_TOKEN_LIFETIME,
-    sub: subject,
-  });
-
-  const signingInput = utf8$1(`${header}.${payload}`);
-
-  const pubBytes = base64UrlToBytes(publicKey);
-  const privBytes = base64UrlToBytes(privateKey);
-  if (pubBytes.length !== 65 || pubBytes[0] !== 0x04) {
-    throw new Error('VAPID publicKey must be a 65-byte uncompressed P-256 point (base64url).');
-  }
-  if (privBytes.length !== 32) {
-    throw new Error('VAPID privateKey must be a 32-byte scalar (base64url).');
-  }
-
-  // Import as JWK so we can supply both private scalar (d) and public point
-  // (x, y) in one step — required by WebCrypto for ECDSA signing.
-  const jwk = {
-    kty: 'EC',
-    crv: 'P-256',
-    d: bytesToBase64Url(privBytes),
-    x: bytesToBase64Url(pubBytes.subarray(1, 33)),
-    y: bytesToBase64Url(pubBytes.subarray(33, 65)),
-    ext: true,
-  };
-  const key = await globalThis.crypto.subtle.importKey(
-    'jwk',
-    jwk,
-    { name: 'ECDSA', namedCurve: 'P-256' },
-    false,
-    ['sign']
-  );
-
-  // WebCrypto ECDSA produces a raw 64-byte (r || s) signature — exactly the
-  // wire format JOSE/JWS expects, so no DER unwrapping is needed.
-  const sig = await globalThis.crypto.subtle.sign(
-    { name: 'ECDSA', hash: 'SHA-256' },
-    key,
-    signingInput
-  );
-
-  return `${header}.${payload}.${bytesToBase64Url(sig)}`;
-}
-
-// ─── Helpers ───────────────────────────────────────────────────────────
-
-function originOf(endpoint) {
-  return new URL(endpoint).origin;
-}
-
-function writeUint32BE(buf, offset, value) {
-  buf[offset] = (value >>> 24) & 0xff;
-  buf[offset + 1] = (value >>> 16) & 0xff;
-  buf[offset + 2] = (value >>> 8) & 0xff;
-  buf[offset + 3] = value & 0xff;
-}
-
-async function safeReadText(res) {
-  try {
-    return await res.text();
-  } catch {
-    return '';
-  }
-}
-
-// Scheduled reminders must survive an offline device, so default to the same
-// 4-week TTL the web-push npm backend applies. sendWebPush's module-level
-// VAPID_DEFAULT_TTL (60s) is tuned for single-shot instant pushes; using it for
-// durable schedules would drop any reminder whose device was offline > 1 min.
-const SCHEDULED_DEFAULT_TTL = 2419200; // 4 weeks, in seconds
-
-/**
- * web-push-compatible sender backed by the Web Crypto implementation above.
- * message-processor calls `ctx.webpush.sendNotification(subscription, payloadString)`,
- * so we only need that one method. VAPID keys are baked in at construction.
- *
- * @param {{ email: string, publicKey: string, privateKey: string }} [vapid]
- * @param {{ ttl?: number }} [options] - Push TTL in seconds; defaults to 4 weeks
- *   (matches the web-push backend) so scheduled pushes outlive an offline device.
- * @returns {{ sendNotification: (subscription: Object, payload: string) => Promise<any> }}
- */
-function createWebCryptoWebPush(vapid = {}, { ttl = SCHEDULED_DEFAULT_TTL } = {}) {
-  return {
-    async sendNotification(subscription, payload) {
-      return sendWebPush({
-        subscription,
-        payload,
-        ttl,
-        vapid: {
-          email: vapid.email,
-          publicKey: vapid.publicKey,
-          privateKey: vapid.privateKey
-        },
-        fetch: globalThis.fetch
-      });
-    }
-  };
-}
-
-/**
- * Cloudflare Worker factory for the single-user amsg-server.
- *
- * Mirrors instant's createCloudflareWorker: you pass a buildConfig(env) that
- * returns the single-user config; we build the server per request (cheap) and
- * dispatch. Returns { fetch, scheduled } for `export default`.
- *
- * Routes (server endpoints only — NO /send-notifications; cron is scheduled()):
- *   POST /init-tenant       → build tables (idempotent)
- *   GET  /get-user-key      → derive user key
- *   POST /schedule-message  → create task
- *   GET  /messages          → list
- *   PUT  /update-message    → patch
- *   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
- *
- * CORS is opt-in: pass `cors: { origin }` in the config (a fixed origin, '*', or
- * an (origin) => allowedOrigin function) to answer OPTIONS preflights and echo
- * Access-Control-* on responses. With no `cors` the Worker stays same-origin.
- *
- * Fire-time hooks are opt-in too: pass `hooks: { onBeforeFire, onLLMOutput,
- * executeToolCalls }` (+ optional `maxToolIterations` / `totalTimeoutMs` /
- * `maxScheduledTasksPerFire`) in the 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` 调整。
- */
-
-
-function headersToObject(h) {
-  const out = {};
-  for (const [k, v] of h) out[k] = v;
-  return out;
-}
-
-function jsonResponse(status, body, extraHeaders) {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { 'Content-Type': 'application/json; charset=utf-8', ...(extraHeaders || {}) }
-  });
-}
-
-// The custom headers the amsg-client sends; browsers preflight any request
-// carrying them, so cross-origin callers need them echoed in the CORS response.
-const CORS_ALLOW_HEADERS =
-  'Content-Type, X-User-Id, X-Payload-Encrypted, X-Encryption-Version, X-Response-Encrypted, X-Client-Token';
-const CORS_ALLOW_METHODS = 'GET, POST, PUT, DELETE, OPTIONS';
-
-/**
- * Resolve the CORS response headers for a request, or null when CORS is off.
- * Opt-in: with no `cors` config the Worker stays same-origin (no headers, and
- * OPTIONS falls through to 404) — so nothing is exposed unless asked for.
- *
- * @param {undefined | { origin: string | ((requestOrigin: string) => string|null|undefined), allowHeaders?: string, maxAge?: number }} cors
- * @param {string} requestOrigin - the request's Origin header (may be '')
- */
-function corsHeadersFor(cors, requestOrigin) {
-  if (!cors || cors.origin == null) return null;
-  const allowOrigin = typeof cors.origin === 'function'
-    ? cors.origin(requestOrigin) || null
-    : cors.origin; // e.g. '*' or a fixed origin like 'https://app.example.com'
-  if (!allowOrigin) return null;
-
-  const headers = {
-    'Access-Control-Allow-Origin': allowOrigin,
-    'Access-Control-Allow-Methods': CORS_ALLOW_METHODS,
-    'Access-Control-Allow-Headers': cors.allowHeaders || CORS_ALLOW_HEADERS,
-    'Access-Control-Max-Age': String(cors.maxAge ?? 86400)
-  };
-  // A per-origin echo must vary the cache by Origin; '*' does not.
-  if (allowOrigin !== '*') headers['Vary'] = 'Origin';
-  return headers;
-}
-
-function createSingleUserCloudflareWorker(buildConfig) {
-  async function resolveConfig(env) {
-    const cfg = await buildConfig(env);
-    if (!cfg.db) cfg.db = createD1Adapter(env.DB);
-    return cfg;
-  }
-
-  async function fetch(request, env /* , ctx */) {
-    // Error boundary: a handler (or config build) may throw — e.g.
-    // schedule-message re-throws a non-unique DB error. Keep the client-facing
-    // contract consistent (a JSON envelope, not the runtime's HTML error page).
-    try {
-      const cfg = await resolveConfig(env);
-      const cors = corsHeadersFor(cfg.cors, request.headers.get('origin') || '');
-      const method = request.method.toUpperCase();
-
-      // CORS preflight: answer OPTIONS directly when CORS is configured.
-      if (method === 'OPTIONS') {
-        return cors
-          ? new Response(null, { status: 204, headers: cors })
-          : jsonResponse(404, { success: false, error: { code: 'NOT_FOUND', message: 'Unknown route' } });
-      }
-
-      const server = createSingleUserServer(cfg);
-
-      const url = request.url;
-      // Strip trailing slash(es) so `/init-tenant/` routes like `/init-tenant`
-      // (endsWith matching is kept so a prefixed mount still resolves).
-      const pathname = new URL(url).pathname.replace(/\/+$/, '') || '/';
-      const headers = headersToObject(request.headers);
-
-      let result;
-      if (method === 'POST' && pathname.endsWith('/init-tenant')) {
-        result = await server.handlers.init.POST(headers, await request.text());
-      } else if (method === 'GET' && pathname.endsWith('/get-user-key')) {
-        result = await server.handlers.getUserKey.GET(url, headers);
-      } else if (method === 'POST' && pathname.endsWith('/schedule-message')) {
-        result = await server.handlers.scheduleMessage.POST(headers, await request.text());
-      } else if (method === 'GET' && pathname.endsWith('/messages')) {
-        result = await server.handlers.messages.GET(url, headers);
-      } else if (method === 'PUT' && pathname.endsWith('/update-message')) {
-        result = await server.handlers.updateMessage.PUT(url, headers, await request.text());
-      } else if (method === 'DELETE' && pathname.endsWith('/cancel-message')) {
-        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')) {
-        result = await server.handlers.clientState.GET(url, headers);
-      } else if (method === 'DELETE' && pathname.endsWith('/client-state')) {
-        result = await server.handlers.clientState.DELETE(url, headers);
-      } else {
-        result = { status: 404, body: { success: false, error: { code: 'NOT_FOUND', message: 'Unknown route' } } };
-      }
-
-      return jsonResponse(result.status, result.body, cors);
-    } catch (error) {
-      console.error('[amsg single-user] fetch() unhandled error:', error && error.message);
-      return jsonResponse(500, { success: false, error: { code: 'INTERNAL_ERROR', message: '服务器内部错误' } });
-    }
-  }
-
-  async function scheduled(event, env /* , ctx */) {
-    const cfg = await resolveConfig(env);
-    const vapid = cfg.vapid || {};
-    if (!cfg.webpush || !vapid.email || !vapid.publicKey || !vapid.privateKey) {
-      console.error('[amsg single-user] scheduled(): VAPID/webpush not configured; skipping tick');
-      return;
-    }
-    // Swallow tick failures: pending tasks stay pending, so the next cron tick
-    // retries them. Logging keeps the failure visible in the tail log.
-    try {
-      await runScheduledTick({
-        db: cfg.db,
-        masterKey: cfg.masterKey,
-        vapid,
-        webpush: cfg.webpush,
-        // Fire-time hooks (optional; see lib/agentic-fire.js). runScheduledTick
-        // spreads its ctx into processSingleMessage, so these ride along.
-        hooks: cfg.hooks || null,
-        maxToolIterations: cfg.maxToolIterations,
-        totalTimeoutMs: cfg.totalTimeoutMs,
-        // hook 的 ctx.writeState() 用它判断单条 value 的上限，和 PUT /client-state 同一个配置。
-        maxStateValueBytes: cfg.maxStateValueBytes,
-        // hook 的 ctx.scheduleTask() 单次 fire 建任务的条数上限（默认 2）。
-        maxScheduledTasksPerFire: cfg.maxScheduledTasksPerFire,
-        // 任务占位租期（默认 10 分钟，随 totalTimeoutMs 抬高）。
-        claimLeaseMs: cfg.claimLeaseMs
-      });
-    } catch (error) {
-      console.error('[amsg single-user] scheduled(): tick failed:', error && error.message);
-    }
-  }
-
-  return { fetch, scheduled };
-}
-
-export { MAX_PUSH_PAYLOAD_BYTES as M, WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES as W, createCancelMessageHandler as a, createUpdateMessageHandler as b, createMessagesHandler as c, createScheduleMessageHandler as d, createGetUserKeyHandler as e, WEB_PUSH_MAX_BODY_BYTES as f, getHeader as g, createD1Adapter as h, isValidUUIDv4 as i, createSingleUserCloudflareWorker as j, createSingleUserServer as k, createWebCryptoWebPush as l, decryptFromStorage as m, decryptPayload as n, deriveUserEncryptionKey as o, parseJsonBody as p, encryptForStorage as q, runScheduledTick as r, isValidISO8601 as s, isValidUUID as t, isValidUrl as u, measurePushPayload as v, validateLlmMessagesArray as w, validateScheduleMessagePayload as x, validateSplitPattern as y };