@rei-standard/amsg-server 2.5.1 → 2.5.2

package/README.md

@@ -54,7 +54,9 @@ const rei = await createReiServer({
 
 ## 关于 `messageType: 'instant'`
 
-> **Note**：新代码的 instant 消息请用 [@rei-standard/amsg-instant](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/instant/README.md)，跳过本端点的"建任务 → 处理 → 删任务" DB 来回。本端点的 `instant` 分支为兼容保留，行为不变、不会有运行时警告。
+> **两条 instant 路径，按各自特点选一条（都是正式支持路径）：**
+> - **本端点的 `messageType: 'instant'`**（create task → process by UUID → delete task）：任务先写进数据库再处理，投递不绑在请求连接上——客户端断开也没关系，任务行还在，能继续跑、能重试，想跑多久跑多久。适合**有数据库、需要长时间生成或保证消息零丢失**的场景。
+> - **[@rei-standard/amsg-instant](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/instant/README.md)**：纯 SSE 流 + Web Push backup，不需要数据库，适合无状态边缘运行时（如 Cloudflare Workers）。它的处理挂在响应连接上，客户端一断开就只剩平台给的那点宽限期把活干完（Deno Deploy 实测 ≈20-30s），所以适合**能快速跑完的短即时消息**。
 
 ## AI 接口 `apiUrl` 约束
 

package/dist/index.d.cts

@@ -801,13 +801,13 @@ function isUniqueViolation(error) {
  * ReiStandard amsg-server v2.4.0
  *
  * Handles single message content generation and Web Push delivery for
- * scheduled tasks (`fixed` / `prompted` / `auto`) and the legacy
- * via-server instant path (`messageType: 'instant'`).
+ * 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 legacy in-server instant) or
+ * `source: 'instant'` (for the in-server instant path) or
  * `source: 'scheduled'` (for everything else).
  *
  * v2.4.0: when the LLM response carries non-empty
@@ -1004,7 +1004,7 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
     // `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 legacy in-server instant path that has no row id.
+    // the in-server instant path that has no row id.
     const messageIdBase = task.id != null
       ? `msg_task_${task.id}`
       : `msg_${randomUUID()}_instant`;
@@ -1398,12 +1398,20 @@ function createScheduleMessageHandler(ctx) {
     const encryptedPayload = encryptForStorage(JSON.stringify(fullTaskData), userKey);
 
     /**
-     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
-     *   This branch is kept for backward compatibility and the existing behavior
-     *   (create task → process → delete) is unchanged. The dedicated amsg-instant
-     *   package is stateless (no DB roundtrip), deployable to Cloudflare Workers,
-     *   and locks the encryption + push-payload contract behind a single version.
-     *   See packages/rei-standard-amsg/instant/README.md.
+     * 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') {
@@ -1459,11 +1467,20 @@ function createScheduleMessageHandler(ctx) {
     }
 
     /**
-     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
-     *   The "create-task → process-by-uuid → delete-task" sequence below is
-     *   preserved verbatim so existing clients keep working. New integrations
-     *   should call the dedicated amsg-instant endpoint instead — it skips this
-     *   DB round-trip entirely. See packages/rei-standard-amsg/instant/README.md.
+     * 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') {

package/dist/index.d.ts

@@ -801,13 +801,13 @@ function isUniqueViolation(error) {
  * ReiStandard amsg-server v2.4.0
  *
  * Handles single message content generation and Web Push delivery for
- * scheduled tasks (`fixed` / `prompted` / `auto`) and the legacy
- * via-server instant path (`messageType: 'instant'`).
+ * 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 legacy in-server instant) or
+ * `source: 'instant'` (for the in-server instant path) or
  * `source: 'scheduled'` (for everything else).
  *
  * v2.4.0: when the LLM response carries non-empty
@@ -1004,7 +1004,7 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
     // `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 legacy in-server instant path that has no row id.
+    // the in-server instant path that has no row id.
     const messageIdBase = task.id != null
       ? `msg_task_${task.id}`
       : `msg_${randomUUID()}_instant`;
@@ -1398,12 +1398,20 @@ function createScheduleMessageHandler(ctx) {
     const encryptedPayload = encryptForStorage(JSON.stringify(fullTaskData), userKey);
 
     /**
-     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
-     *   This branch is kept for backward compatibility and the existing behavior
-     *   (create task → process → delete) is unchanged. The dedicated amsg-instant
-     *   package is stateless (no DB roundtrip), deployable to Cloudflare Workers,
-     *   and locks the encryption + push-payload contract behind a single version.
-     *   See packages/rei-standard-amsg/instant/README.md.
+     * 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') {
@@ -1459,11 +1467,20 @@ function createScheduleMessageHandler(ctx) {
     }
 
     /**
-     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
-     *   The "create-task → process-by-uuid → delete-task" sequence below is
-     *   preserved verbatim so existing clients keep working. New integrations
-     *   should call the dedicated amsg-instant endpoint instead — it skips this
-     *   DB round-trip entirely. See packages/rei-standard-amsg/instant/README.md.
+     * 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') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-server",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "ReiStandard Active Messaging server SDK with pluggable database adapters. Three-axis push schema (messageKind / messageType / messageSubtype) from @rei-standard/amsg-shared. Auto-emits ReasoningPush when the LLM response carries reasoning_content.",
   "repository": {
     "type": "git",