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

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

@@ -1,4 +1,4 @@
-import { validateAvatarUrl, toUint8, concatBytes, base64UrlToBytes, readReasoningContent, stripReasoningTags, buildReasoningPush, buildContentPush, normalizeVapidSubject } from '@rei-standard/amsg-shared';
+import { validateAvatarUrl, toUint8, concatBytes, base64UrlToBytes, chunkReasoningByUtf8Bytes, extractAssistantMessage, buildSessionContext, assertValidDecision, extractToolCallsFromDecision, readReasoningContent, stripReasoningTags, buildReasoningPush, buildContentPush, normalizeVapidSubject } from '@rei-standard/amsg-shared';
 
 /**
  * Validation utility library (SDK version)
@@ -421,7 +421,7 @@ const TEXT_ENCODER = new TextEncoder();
 const TEXT_DECODER = new TextDecoder('utf-8', { fatal: false });
 
 /** UTF-8 encode a string into a Uint8Array. */
-function utf8(str) {
+function utf8$1(str) {
   return TEXT_ENCODER.encode(String(str));
 }
 
@@ -471,7 +471,7 @@ function hexToBytes(hex) {
 
 /** Encode a JSON-serializable value as base64url (UTF-8 JSON). */
 function jsonToBase64Url(value) {
-  return bytesToBase64Url(utf8(JSON.stringify(value)));
+  return bytesToBase64Url(utf8$1(JSON.stringify(value)));
 }
 
 /** `crypto.randomUUID()`. The Node adapter polyfills `globalThis.crypto`. */
@@ -558,7 +558,7 @@ async function aesGcmOpen(hexKey, iv, ciphertext, authTag) {
  * @returns {Promise<string>} 64-char hex key.
  */
 async function deriveUserEncryptionKey(userId, masterKey) {
-  const digest = await globalThis.crypto.subtle.digest('SHA-256', utf8(masterKey + userId));
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', utf8$1(masterKey + userId));
   return bytesToHex(new Uint8Array(digest)).slice(0, 64);
 }
 
@@ -590,7 +590,7 @@ async function decryptPayload(encryptedPayload, encryptionKey) {
 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(plaintext));
+  const { ciphertext, authTag } = await aesGcmSeal(encryptionKey, iv, utf8$1(plaintext));
 
   return {
     iv: bytesToBase64(iv),
@@ -608,7 +608,7 @@ async function encryptPayload(payload, encryptionKey) {
  */
 async function encryptForStorage(text, encryptionKey) {
   const iv = randomBytes(16);
-  const { ciphertext, authTag } = await aesGcmSeal(encryptionKey, iv, utf8(text));
+  const { ciphertext, authTag } = await aesGcmSeal(encryptionKey, iv, utf8$1(text));
   return `${bytesToHex(iv)}:${bytesToHex(authTag)}:${bytesToHex(ciphertext)}`;
 }
 
@@ -699,6 +699,613 @@ function isUniqueViolation(error) {
   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
+ *
+ * @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;
+  }
+
+  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;
+}
+
+/**
+ * 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)
+ *     → 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).
+ *
+ * scratch：每次 fire 新建一个普通对象，onBeforeFire 的 fireCtx 与同一次
+ * fire 每轮的 sessionCtx 都持有同一个引用，hook 之间借它传工具上下文，
+ * 不用再自己维护 Map<sessionId, state>。fire 结束（finish / skip-push /
+ * 抛错 / 轮数超限）后随调用栈丢弃；库不读不写、不落库、不打日志。
+ *
+ * Budget guards, both factory-level (ctx.maxToolIterations /
+ * ctx.totalTimeoutMs) and per-fire (onBeforeFire may return
+ * { messages, maxToolIterations?, totalTimeoutMs? } to override for one
+ * 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;
+
+// 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. */
+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,
+    };
+  }
+  throw new TypeError(
+    'AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs? } | 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 })
+ * @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.
+ *   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)
+    );
+  };
+
+  // 单次 fire 的宿主便签：onBeforeFire 的 fireCtx 和同一次 fire 每轮的
+  // sessionCtx（onLLMOutput / executeToolCalls）拿到同一个对象引用，fire 结束
+  // （finish / skip-push / 抛错 / 轮数超限）随调用栈丢弃。库自己不读不写、
+  // 不落库、不打日志、不跨 fire 共享 —— 重试产生的新 fire 拿到的是新对象。
+  const scratch = {};
+
+  const fireCtx = Object.freeze({
+    task: buildHookTask(task, decryptedPayload),
+    userId: task.user_id,
+    readState,
+    now: new Date(nowFn()),
+    scratch,
+  });
+
+  const before = await hooks.onBeforeFire(fireCtx);
+  if (before == null) return { handled: false };
+
+  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 },
+      { requireContent: false, timeoutMs: roundTimeoutMs }
+    );
+
+    const assistantMessage = extractAssistantMessage(llmResponse);
+    messages = [...messages, assistantMessage];
+
+    const sessionCtx = buildSessionContext({
+      sessionId,
+      messages,
+      llmResponse,
+      iteration,
+      contactName: decryptedPayload.contactName,
+      avatarUrl: decryptedPayload.avatarUrl || undefined,
+      charId: decryptedPayload.charId,
+      metadata: decryptedPayload.metadata,
+      scratch,
+    });
+
+    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.
+    const assistantWithTools = Array.isArray(assistantMessage.tool_calls) && assistantMessage.tool_calls.length > 0
+      ? assistantMessage
+      : { ...assistantMessage, tool_calls: toolCalls };
+    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
@@ -799,6 +1406,16 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
     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.
+    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;
@@ -810,7 +1427,7 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
       const hasPrompt = !!decryptedPayload.completePrompt
         || (Array.isArray(decryptedPayload.messages) && decryptedPayload.messages.length > 0);
       if (hasPrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
-        const aiResult = await _callAI(decryptedPayload);
+        const aiResult = await callLlm(decryptedPayload);
         messageContent = aiResult.content;
         llmResponse = aiResult.response;
       } else if (decryptedPayload.userMessage) {
@@ -820,7 +1437,7 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
       }
 
     } else if (decryptedPayload.messageType === 'prompted' || decryptedPayload.messageType === 'auto') {
-      const aiResult = await _callAI(decryptedPayload);
+      const aiResult = await callLlm(decryptedPayload);
       messageContent = aiResult.content;
       llmResponse = aiResult.response;
     } else {
@@ -913,245 +1530,101 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
       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 };
-  }
-}
-
-/**
- * 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`.
- *
- * @private
- * @param {Object} payload
- * @returns {Promise<{ response: unknown, content: string }>}
- */
-async function _callAI(payload) {
-  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(300000)
-  });
-
-  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 content = aiData?.choices?.[0]?.message?.content;
-  if (typeof content !== 'string' || !content.trim()) {
-    throw new Error('AI API error: response missing choices[0].message.content');
-  }
-
-  return { response: aiData, content: content.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
- *
- * @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;
-  }
-
-  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.');
-  }
+    return { success: true, messagesSent: messages.length };
 
-  requestBody.max_tokens = payload.maxTokens;
-  return requestBody;
+  } catch (error) {
+    return { success: false, messagesSent: 0, error: error.message };
+  }
 }
 
 /**
- * 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).
+ * Process a single message identified by UUID (used for instant type).
  *
- * @param {string} apiUrl
- * @returns {string}
+ * @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 }>}
  */
-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).'
-    );
+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: '租户主密钥不存在或配置异常' }
+    };
   }
 
-  const trimmedApiUrl = apiUrl.trim();
-  let parsedUrl;
+  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;
+      }
 
-  try {
-    parsedUrl = new URL(trimmedApiUrl);
-  } catch {
-    throw new Error(
-      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
-    );
-  }
+      return {
+        success: false,
+        error: { code: 'INTERNAL_ERROR', message: error.message, retriesAttempted: retryCount }
+      };
+    }
 
-  let path = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+    if (!task) {
+      return { success: false, error: { code: 'TASK_NOT_FOUND', message: '任务不存在或已处理' } };
+    }
 
-  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.
+    const result = await processSingleMessage(task, ctx, masterKey);
 
-  parsedUrl.pathname = path;
-  return parsedUrl.toString();
+    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 };
+  }
 }
 
 /**
@@ -1924,6 +2397,24 @@ const SQLITE_INDEXES = [
   }
 ];
 
+// 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.
  *
@@ -1943,6 +2434,11 @@ const UPDATABLE_COLUMNS = new Set([
   'next_send_at', 'status', 'retry_count', 'created_at', 'updated_at'
 ]);
 
+// LIKE 前缀转义：用户 key 里的 % _ \ 不能变成通配符/转义符。
+function escapeLikePrefix(prefix) {
+  return prefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+
 class D1Adapter {
   /** @param {{ prepare: (sql: string) => any }} db - Cloudflare D1 binding */
   constructor(db) {
@@ -1966,6 +2462,7 @@ class D1Adapter {
 
   async initSchema() {
     await this._db.prepare(SQLITE_TABLE_SQL).run();
+    await this._db.prepare(CLIENT_STATE_TABLE_SQL).run();
 
     const indexResults = [];
     for (const index of SQLITE_INDEXES) {
@@ -1997,6 +2494,7 @@ class D1Adapter {
 
   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) {
@@ -2145,6 +2643,98 @@ class D1Adapter {
     ).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` 是分块存储的清理项（见 lib/state-chunks.js）：在同一 batch 里
+   * 先于 upsert 执行，按 (namespace, key 前缀) 删掉旧写入留下的切片行；
+   * `updated_at <= ?` 条件保证陈旧批次删不动更新写入的行。
+   *
+   * Uses D1's batch() — one network round trip for the whole set (implicit
+   * transaction). The client calls this endpoint inside its few-seconds
+   * background window, so N sequential round trips could eat the whole
+   * 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, 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_SQL =
+      `DELETE FROM client_state
+       WHERE user_id = ? AND namespace = ? AND key LIKE ? ESCAPE '\\' AND updated_at <= ?`;
+
+    const buildStatements = () => [
+      ...cleanups.map((c) =>
+        this._db.prepare(CLEANUP_SQL).bind(userId, c.namespace, `${escapeLikePrefix(c.keyPrefix)}%`, c.updatedAt)
+      ),
+      ...entries.map((entry) =>
+        this._db.prepare(UPSERT_SQL).bind(userId, entry.namespace, entry.key, entry.value, entry.updatedAt)
+      ),
+    ];
+
+    let results;
+    if (typeof this._db.batch === 'function') {
+      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;
+  }
 }
 
 /**
@@ -2319,6 +2909,310 @@ function createVapidPublicKeyHandler(ctx) {
   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); the client is the only writer.
+ *
+ *   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 = 200;
+const MAX_NAMESPACE_CHARS = 128;
+const MAX_KEY_CHARS = 256;
+
+const utf8 = new TextEncoder();
+
+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 = utf8.encode(entry.value).length;
+  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');
+    }
+
+    // 展开成物理行：小值 1 行（历史路径，字节级不变），大值 = 根 marker 行 +
+    // 保留 namespace 里的 N 个加密切片行。每条 accepted 条目都配一条 cleanup
+    // （同一 batch 里先删后写），把这个 key 旧写入留下的切片清干净 —— 覆盖写
+    // 变小 / 缩块都不留尾巴；陈旧批次的 cleanup 因 updated_at 条件删不动新行。
+    const physicalRows = [];
+    const cleanups = [];
+    const rootRowIndexes = [];
+    for (const entry of accepted) {
+      cleanups.push({
+        namespace: chunkNamespaceFor(entry.namespace),
+        keyPrefix: chunkKeyPrefixFor(entry.key),
+        updatedAt: entry.updatedAt,
+      });
+      rootRowIndexes.push(physicalRows.length);
+      if (utf8.encode(entry.value).length <= STATE_CHUNK_SLICE_BYTES) {
+        physicalRows.push({
+          namespace: entry.namespace,
+          key: entry.key,
+          value: await encryptForStorage(entry.value, userKey),
+          updatedAt: entry.updatedAt,
+        });
+      } else {
+        const slices = splitStateValue(entry.value);
+        physicalRows.push({
+          namespace: entry.namespace,
+          key: entry.key,
+          value: buildChunkedRootValue(slices.length),
+          updatedAt: entry.updatedAt,
+        });
+        const encryptedSlices = await Promise.all(slices.map((slice) => encryptForStorage(slice, userKey)));
+        for (let c = 0; c < encryptedSlices.length; c++) {
+          physicalRows.push({
+            namespace: chunkNamespaceFor(entry.namespace),
+            key: chunkKeyFor(entry.key, c),
+            value: encryptedSlices[c],
+            updatedAt: entry.updatedAt,
+          });
+        }
+      }
+    }
+
+    let upserted = 0;
+    let skipped = 0;
+    if (physicalRows.length > 0) {
+      const result = await db.upsertClientState(userId, physicalRows, cleanups);
+      if (Array.isArray(result.outcomes) && result.outcomes.length === physicalRows.length) {
+        // 逻辑计数：一条 entry 的 upserted/skipped 看它的根行（切片行不计数）。
+        for (const rootIndex of rootRowIndexes) {
+          if (result.outcomes[rootIndex]) upserted++; else skipped++;
+        }
+      } else {
+        // 自定义 adapter 只回老形状 { upserted, skipped } 时按物理行计数兜底。
+        upserted = result.upserted;
+        skipped = result.skipped;
+      }
+    }
+
+    const 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',
+  '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.
  *
@@ -2334,6 +3228,12 @@ function createVapidPublicKeyHandler(ctx) {
  * @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）。
  * @returns {{ handlers: Object, ctx: Object }}
  */
 
@@ -2356,7 +3256,14 @@ function createSingleUserServer(config) {
       privateKey: vapid.privateKey || ''
     },
     webpush: config.webpush || null,
-    tenantManager
+    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
   };
 
   return {
@@ -2368,7 +3275,9 @@ function createSingleUserServer(config) {
       updateMessage: createUpdateMessageHandler(ctx),
       cancelMessage: createCancelMessageHandler(ctx),
       messages: createMessagesHandler(ctx),
-      vapidPublicKey: createVapidPublicKeyHandler(ctx)
+      vapidPublicKey: createVapidPublicKeyHandler(ctx),
+      clientState: createClientStateHandler(ctx),
+      capabilities: createCapabilitiesHandler(ctx)
     }
   };
 }
@@ -2389,9 +3298,9 @@ function createSingleUserServer(config) {
 
 
 // RFC 8291 fixed labels (each followed by a NUL byte per HKDF "info" framing).
-const KEY_INFO_PREFIX = utf8('WebPush: info\0');
-const CEK_INFO = utf8('Content-Encoding: aes128gcm\0');
-const NONCE_INFO = utf8('Content-Encoding: nonce\0');
+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.
@@ -2433,7 +3342,7 @@ async function sendWebPush({ subscription, payload, vapid, ttl, fetch: fetchImpl
   }
 
   const encryptedBody = await encryptPushPayload({
-    plaintext: utf8(payload),
+    plaintext: utf8$1(payload),
     uaPublicKey: base64UrlToBytes(subscriptionKeys.p256dh),
     authSecret: base64UrlToBytes(subscriptionKeys.auth),
   });
@@ -2606,7 +3515,7 @@ async function buildVapidJwt({ audience, subject, publicKey, privateKey }) {
     sub: subject,
   });
 
-  const signingInput = utf8(`${header}.${payload}`);
+  const signingInput = utf8$1(`${header}.${payload}`);
 
   const pubBytes = base64UrlToBytes(publicKey);
   const privBytes = base64UrlToBytes(privateKey);
@@ -2717,10 +3626,20 @@ function createWebCryptoWebPush(vapid = {}, { ttl = SCHEDULED_DEFAULT_TTL } = {}
  *   DELETE /cancel-message  → delete
  *   GET  /vapid-public-key  → this worker's VAPID public key (for the frontend's
  *                             Web Push subscription); 503 if VAPID_PUBLIC_KEY unset
+ *   GET  /capabilities      → { serverVersion, features }（特性探测；老部署无此路由 → 404）
+ *   PUT  /client-state      → batch upsert client state (last-write-wins on updatedAt)
+ *   GET  /client-state      → read one namespace's entries (?namespace=<ns>)
+ *   DELETE /client-state    → wipe this user's client state
  *
  * 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`) 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.
  */
 
 
@@ -2815,6 +3734,14 @@ function createSingleUserCloudflareWorker(buildConfig) {
         result = await server.handlers.cancelMessage.DELETE(url, headers);
       } else if (method === 'GET' && pathname.endsWith('/vapid-public-key')) {
         result = await server.handlers.vapidPublicKey.GET(url, headers);
+      } else if (method === 'GET' && pathname.endsWith('/capabilities')) {
+        result = await server.handlers.capabilities.GET(url, headers);
+      } else if (method === 'PUT' && pathname.endsWith('/client-state')) {
+        result = await server.handlers.clientState.PUT(headers, await request.text());
+      } else if (method === 'GET' && pathname.endsWith('/client-state')) {
+        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' } } };
       }
@@ -2836,7 +3763,17 @@ function createSingleUserCloudflareWorker(buildConfig) {
     // 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 });
+      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
+      });
     } catch (error) {
       console.error('[amsg single-user] scheduled(): tick failed:', error && error.message);
     }