@rei-standard/amsg-shared 0.4.0-next.0 → 0.4.0-next.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReiStandard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -17,7 +17,7 @@ A single push is described by three independent dimensions:
 |----------------|-------------------|-------------------------------------------------------|--------------------|
 | Dispatch       | `messageType`     | `instant` / `fixed` / `prompted` / `auto`             | Package (fixed)    |
 | Business       | `messageSubtype`  | Any string                                            | Caller (free-form) |
-| Content        | `messageKind`     | `content` / `reasoning` / `tool_request` / `error`    | Package (fixed)    |
+| Content        | `messageKind`     | `content` / `reasoning` / `tool_request` / `error` / `result` | Package (fixed) |
 
 `messageType` answers **how this push was produced** (one-shot
 `instant` worker, scheduled `fixed` ping, AI-`prompted` reply, fully
@@ -41,10 +41,24 @@ origin** (`'instant'` for `amsg-instant`, `'scheduled'` for any
 | `messageType`    | `MessageType`     | Dispatch axis.                                                              |
 | `source`         | `'instant' \| 'scheduled'` | Routing origin.                                                    |
 | `messageId`      | `string`          | Unique per push. Format owned by the producer.                              |
-| `sessionId`      | `string`          | **Shared across all pushes from the same LLM round** (reasoning + content), and across all iterations of a single agentic-loop request. |
+| `sessionId`      | `string`          | **Shared across all pushes from the same LLM round** (reasoning + content), and across all iterations of a single agentic-loop request. Opaque — do not parse it for task identity, read the scheduling fields below. |
 | `timestamp`      | `string` (ISO 8601) | Producer-side wall clock.                                                 |
 | `messageSubtype` | `string?`         | Caller's business namespace. Defaults to `'chat'` at producers.             |
 | `metadata`       | `object?`         | **Caller passthrough.** Packages MUST NOT write here.                       |
+| `taskId`         | `number \| string \| null?` | Scheduled task row id.                                          |
+| `taskUuid`       | `string \| null?` | Scheduled task uuid (the id the scheduling side chose).                    |
+| `recurrenceType` | `'none' \| 'daily' \| 'weekly'?` | Whether that task fires again.                            |
+| `occurrenceMs`   | `number \| null?` | Nominal fire time of this occurrence (epoch ms).                           |
+
+### Scheduling identity
+
+`taskId` / `taskUuid` / `recurrenceType` / `occurrenceMs` are stamped by
+`@rei-standard/amsg-server` on every push that came out of a scheduled task
+row. They tell the client which task this is, whether the task will come
+back, and which nominal fire time produced this burst — so a task the client
+never created (one the character scheduled for itself at fire time) still
+arrives fully identified. Pushes with no task behind them (`amsg-instant`)
+omit all four.
 
 ---
 
@@ -56,7 +70,7 @@ origin** (`'instant'` for `amsg-instant`, `'scheduled'` for any
 
 | Field                | Type                                      | Notes |
 |----------------------|-------------------------------------------|-------|
-| `show`               | `'auto' \| 'always' \| 'when-hidden' \| false` | Display policy. `auto` follows SW defaults. |
+| `show`               | `'auto' \| 'always' \| 'when-hidden' \| false` | Display policy — see [选哪个 `show`](#选哪个-show). |
 | `title`              | `string?`                                | Notification title override. |
 | `body`               | `string?`                                | Notification body override. |
 | `icon`               | `string?`                                | Notification icon URL. |
@@ -64,12 +78,56 @@ origin** (`'instant'` for `amsg-instant`, `'scheduled'` for any
 | `tag`                | `string?`                                | Notification grouping tag. |
 | `renotify`           | `boolean?`                               | Re-alert when a matching `tag` replaces an existing notification. |
 | `requireInteraction` | `boolean?`                               | Keep the notification visible until the user dismisses it. |
-| `silent`             | `boolean?`                               | Suppress notification sound and vibration. |
+| `silent`             | `(boolean \| 'when-visible')?`            | Suppress notification sound and vibration — see [选哪个 `silent`](#选哪个-silent). |
 | `data`               | `Record<string, unknown>?`               | Custom data passed to the notification. |
 
 Unknown fields are preserved for forward compatibility, but the known
 fields above are validated by the builders when present.
 
+### 选哪个 `show`
+
+订阅是按 `userVisibleOnly: true` 建的，收到 push 却不弹通知就是违约：Chrome 替你弹一条通用横幅，Firefox 有配额、超了退订，iOS 给新订阅几天宽限期（跟条数无关）、过期后一条不弹就吊销订阅。所以口径只有一条，跟机型无关——**要推就一定弹，不想弹就别推。**
+
+| 值 | SW 那边 | 什么时候用 |
+|---|---|---|
+| 不配 / `'auto'` | 按 `messageKind` 走默认（`content` / `result` 弹，其余不弹） | 默认，多数 payload 不用管 |
+| `'always'` | 一定弹 | 要推的一律用它。嫌打扰配 `tag` 折叠加 `silent`，而不是不弹 |
+| `false` | 一定不弹 | 明说这条不弹。有收件箱的发送端据此**根本不发这条 push**，内容落收件箱等客户端补拉 |
+| `'when-hidden'` | 有可见窗口就不弹 | 兼容档，新代码不选——应用在前台时它就是一条不弹的 push，那笔账照记 |
+
+所以 `show: false` 在发送端和接收端不是同一件事：有服务端收件箱的发送端（`@rei-standard/amsg-server` 单用户线）见到它压根不发，SW 那边收不到；没有收件箱的发送端才是「推过去、SW 不弹」。
+
+想要「立刻推到、但页面自己渲染」没有专门的档：用 `'always'` + `tag` + `silent`，页面自绘不受影响（`postMessage` 跟弹不弹通知无关）。
+
+完整取舍见 [`@rei-standard/amsg-sw` README 的「不展示通知的代价」](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/sw/README.md#不展示通知的代价)。
+
+### 选哪个 `silent`
+
+`silent` 管的是「响不响铃、震不震」，跟弹不弹（`show`）是两件独立的事——通知照样进通知中心，只是安静地进。
+
+| 值 | SW 那边 | 什么时候用 |
+|---|---|---|
+| 不配 / `false` | 正常响铃震动 | 默认 |
+| `true` | 一律不响 | 一串连着来的通知配 `tag` 折叠，只想在通知中心留个痕迹 |
+| `'when-visible'` | 有可见窗口就静音，没有就照常响 | 页面自己会把内容画出来的那类消息：用户正看着页面就别再响一声，人切后台了照样叫得动 |
+
+`'when-visible'` 只能由 Service Worker 当场算：发送端发推那一刻并不知道用户此刻在不在前台，写死 `silent: true` 的话，用户切到后台收到的那条也不会响。判定用的是跟 `show: 'when-hidden'` 同一套窗口可见性口径，一条 payload 只算一次。
+
+### `notificationIntent(payload)`
+
+把上面这套规则算成一个值，`'always'` / `'when-hidden'` / `'never'`：`notification.show` 说了算，没说才按 `messageKind` 走默认。两端读同一份——SW 拿它决定要不要 `showNotification`，发送端拿它决定这条值不值得占用推送通道（`'never'` 的 payload 推过去不会有任何可见反馈，`@rei-standard/amsg-server` 只把它落进收件箱，等客户端上线 `GET /outbox?since=` 补拉）。
+
+```js
+import { notificationIntent } from '@rei-standard/amsg-shared';
+
+notificationIntent({ messageKind: 'content' });                                  // 'always'
+notificationIntent({ messageKind: 'reasoning' });                                // 'never'
+notificationIntent({ messageKind: 'reasoning', notification: { show: 'always' } }); // 'always'
+notificationIntent({ messageKind: 'content', notification: { show: false } });   // 'never'
+```
+
+`'when-hidden'` 单独占一档，因为它到底弹不弹要看当下有没有可见窗口，那只有 SW 知道；发送端把它当「可能会弹」照发。
+
 ---
 
 ## Per-kind fields
@@ -85,7 +143,6 @@ fields above are validated by the builders when present.
 | `title`          | `string?`   | Notification title.                                            |
 | `contactName`    | `string?`   | Sender display name.                                           |
 | `avatarUrl`      | `string \| null?` | Sender avatar URL (`https:` only — `data:` is rejected upstream). |
-| `taskId`         | `string \| null?` | Scheduled task ID (server only).                          |
 
 ### `ReasoningPush` — LLM meta-thinking
 
@@ -96,11 +153,17 @@ fields above are validated by the builders when present.
 | `title`            | `string?`      |                                                             |
 | `contactName`      | `string?`      |                                                             |
 | `avatarUrl`        | `string \| null?` |                                                          |
-
-**No `messageIndex` / `totalMessages`.** Reasoning is one push per
-LLM round, never a split-burst. Those fields are absent at the type
-level on purpose — making them optional would leave callers
-wondering when they're set.
+| `messageIndex`     | `number?`      | 1-based part index when a producer sentence-splits reasoning into a burst. Omit for singletons. |
+| `totalMessages`    | `number?`      | Total parts of that split. Omit for singletons.             |
+| `chunkIndex`       | `number?`      | Transport-only slice index when a single segment exceeds the Web Push payload limit (see `chunkReasoningByUtf8Bytes`). |
+| `totalChunks`      | `number?`      | Total transport slices. Omit when not sliced.               |
+
+Both multi-part axes are **omitted from the wire when the part count
+is 1**, so single-shot reasoning stays byte-for-byte identical to
+older payloads. Current producers emit one `ReasoningPush` per LLM
+round and set neither — oversized reasoning rides the generic
+multipart transport instead. The two axes can coexist when a
+sentence-split segment is itself oversized.
 
 Emitted **before** the matching `ContentPush` burst when the LLM
 response carried a non-empty `reasoning_content`.
@@ -116,8 +179,11 @@ response carried a non-empty `reasoning_content`.
 | `message`     | `string?`        | Optional human-readable tag for the request.                |
 
 Emitted by an agentic-loop hook returning
-`{ decision: 'tool-request', pushPayload }`. The client is expected
-to execute the tool and resume via `/continue`.
+`{ decision: 'tool-request', pushPayloads }`. In the default
+(amsg-instant) flavor the client executes the tools and resumes via
+`/continue`; amsg-server's fire-time loop runs the tools in-process
+instead and may carry a `toolCalls` array directly — see
+`assertValidDecision` below.
 
 ### `ErrorPush` — producer-level error
 
@@ -132,6 +198,22 @@ Replaces the legacy 0.7.0 `{ type: 'error', code: '...' }` envelope.
 The legacy `type` field is **gone** — do not look for it on
 `ErrorPush`.
 
+### `ResultPush` — 宿主自定义的一条结果
+
+| Field         | Type       | Notes                                                          |
+|---------------|------------|----------------------------------------------------------------|
+| `messageKind` | `'result'` | Discriminator.                                                 |
+| `resultKind`  | `string`   | 宿主给这类结果起的名字（`'fire-pack'`、`'ledger-entry'`……），客户端按它分流。 |
+| `title`       | `string?`  | 通知标题的兜底（`notification.title` 优先）。                    |
+| `body`        | `string?`  | 通知正文的兜底（`notification.body` 优先）。                     |
+
+不是聊天内容，而是「这次跑完产出了点什么，客户端拿去自己消化」：整理好的一份数据、一条账目、后台生成的产物。形状由宿主定，`buildResultPush` 是唯一**保留自己不认识的字段**的 builder——白名单式的复制会把内容删掉一半。
+
+两处与别的 kind 不同：
+
+- **投递路径**：产出方（`@rei-standard/amsg-server` 的 `ctx.emitResult()`）除了推送，还把它落进服务端收件箱，客户端下次 `GET /outbox?since=` 一定拿得到。
+- **通知**：SW 侧默认弹（与 `content` 同待遇，其余三种是静默送给页面）——结果往往正是「跑完了，回来看看」那句话。不想弹就带 `notification: { show: false }`：这一档 `amsg-server` 不发推送、只落收件箱，客户端补拉时拿到（见[选哪个 `show`](#选哪个-show)）。
+
 ---
 
 ## Usage
@@ -162,6 +244,9 @@ function dispatch(push: AmsgPush) {
     case 'error':
       console.error(push.code, push.message);
       break;
+    case 'result':
+      // push.resultKind is `string` — 宿主自己的结果，按它分流
+      break;
   }
 }
 ```
@@ -174,6 +259,7 @@ import {
   buildReasoningPush,
   buildToolRequestPush,
   buildErrorPush,
+  buildResultPush,
 } from '@rei-standard/amsg-shared';
 
 // One sentence in an N-split burst
@@ -216,12 +302,24 @@ const error = buildErrorPush({
   message: 'onLLMOutput threw: ...',
   iteration: 2,
 });
+
+// 宿主自定义的一条结果（认识以外的字段原样保留）
+const result = buildResultPush({
+  messageType: 'auto',
+  source: 'scheduled',
+  messageId: 'msg_task_7@1700000000000_result_0',
+  sessionId: 'sess_abc',
+  resultKind: 'fire-pack',
+  packId: 'pack_42',
+  entries: [{ id: 1 }, { id: 2 }],
+  notification: { title: '整理好了', body: '点开看看' },
+});
 ```
 
 ### Type guards
 
 ```js
-import { isContentPush, isReasoningPush, isErrorPush } from '@rei-standard/amsg-shared';
+import { isContentPush, isReasoningPush, isToolRequestPush, isErrorPush, isResultPush } from '@rei-standard/amsg-shared';
 
 if (isContentPush(push)) {
   // push.message is `string`
@@ -239,6 +337,7 @@ MESSAGE_KIND.CONTENT;       // 'content'
 MESSAGE_KIND.REASONING;     // 'reasoning'
 MESSAGE_KIND.TOOL_REQUEST;  // 'tool_request'
 MESSAGE_KIND.ERROR;         // 'error'
+MESSAGE_KIND.RESULT;        // 'result'
 
 MESSAGE_TYPE.INSTANT;       // 'instant'
 MESSAGE_TYPE.FIXED;         // 'fixed'
@@ -251,6 +350,68 @@ PUSH_SOURCE.SCHEDULED;      // 'scheduled'
 
 ---
 
+## Shared building blocks
+
+Besides the push schema, this package is the single source of truth
+for helpers that `amsg-instant`, `amsg-server`, and `amsg-sw` used to
+each keep a copy of. All are exported from the package root; the
+one-liners below are just a map — see the JSDoc on each export for
+the full contract.
+
+### Bytes / encoding / crypto
+
+`toUint8` · `concatBytes` · `utf8` · `utf8Decode` · `bytesToBase64` ·
+`bytesToBase64Url` · `base64UrlToBytes` · `jsonToBase64Url` ·
+`bytesToHex` · `hexToBytes` · `randomBytes` · `hmacSha256` ·
+`timingSafeEqualBytes` — WebCrypto-friendly byte/encoding helpers for
+base64url, hex, HMAC, and constant-time comparison.
+
+### LLM call
+
+| Export | What it is |
+|---|---|
+| `callLlm(...)` | Call an OpenAI-compatible chat-completions endpoint with timeout / abort handling (default 300 000 ms, injectable `fetch`). |
+| `buildLlmRequestBody(...)` | Build the request body for prompt mode or `messages` mode. |
+| `normalizeAiApiUrl(apiUrl)` | Normalize a base URL to its chat-completions endpoint without doubling `/v1`; unrecognized paths pass through unchanged. |
+| `validateLlmMessagesShape(...)` | Validate a `messages` array, including assistant `tool_calls` and `role: 'tool'` entries. |
+| `LLM_MESSAGES_ERROR` | Stable error codes emitted by that validation. |
+
+### Web Push
+
+| Export | What it is |
+|---|---|
+| `sendWebPush(...)` | RFC 8291 payload encryption + RFC 8292 VAPID auth + POST to the push service (`err.code = 'PUSH_SEND_FAILED'` on failure). |
+| `buildVapidJwt(...)` / `verifyVapidJwt(...)` | Build / verify the ES256 VAPID JWT. |
+| `normalizeVapidSubject(...)` | Normalize the VAPID subject (e.g. add the `mailto:` prefix). |
+
+### Wire-protocol constants
+
+| Export | What it is |
+|---|---|
+| `MULTIPART_MESSAGE_KIND` / `MULTIPART_ENCODING` / `MULTIPART_VERSION` | The generic multipart chunk envelope (`'_multipart'`) produced by `amsg-instant` and reassembled by `amsg-sw`. |
+| `DEFAULT_MULTIPART_TTL_MS` / `DEFAULT_MULTIPART_MAX_CHUNKS` / `DEFAULT_MULTIPART_MAX_TOTAL_BYTES` | Multipart reassembly budget defaults. |
+| `REI_AMSG_POSTMESSAGE_TYPE` / `REI_SW_EVENT` / `REI_SW_MESSAGE_TYPE` / `REI_AMSG_DELIVER_MESSAGE_TYPE` | The window ⇄ Service Worker `postMessage` protocol strings — import these instead of hard-coding the literals. |
+
+### Agentic-loop contract
+
+| Export | What it is |
+|---|---|
+| `assertValidDecision(decision, options?)` | Runtime-validate an `onLLMOutput` hook decision (`finish` / `tool-request` / `continue` / `skip-push`); `{ inlineToolCalls: true }` enables the amsg-server flavor. |
+| `extractToolCallsFromDecision(...)` | Pull tool calls out of either decision flavor (inline `toolCalls` or tool-request `pushPayloads`). |
+| `buildSessionContext(...)` | Build the frozen, credential-free context object handed to agentic hooks. |
+| `extractAssistantMessage(...)` | Safely read `choices[0].message` off an LLM response (never throws). |
+| `readReasoningContent(...)` | Read `reasoning_content` off an assistant message; empty string means "none". |
+| `stripReasoningTags(...)` | Strip reasoning that leaked into `message.content` so it doesn't ship inside the `ContentPush` burst. |
+| `chunkReasoningByUtf8Bytes(text, maxBytes)` | Split reasoning text on safe UTF-8 edges for payload-limited transports. |
+
+### Validation misc
+
+`isValidUrl` · `validateAvatarUrl` · `AVATAR_URL_MAX_LENGTH` — the
+avatar-URL soft-strip rule shared by client / instant / server
+(standards §6.2).
+
+---
+
 ## Invariants
 
 1. **`messageKind` is a literal-type discriminator.** Producers must
@@ -260,8 +421,10 @@ PUSH_SOURCE.SCHEDULED;      // 'scheduled'
    `ReasoningPush` and the `ContentPush`(es) it precedes share the
    same `sessionId`. Agentic-loop multi-iteration runs reuse the
    same `sessionId` across iterations.
-3. **`ReasoningPush` carries no `messageIndex` / `totalMessages`.**
-   Those fields belong to the content N-split burst.
+3. **Multi-part fields are omitted for singletons.** On `ContentPush`
+   and `ReasoningPush` alike, `messageIndex` / `totalMessages` (and
+   reasoning's `chunkIndex` / `totalChunks`) only appear on genuine
+   multi-part bursts — never as a redundant `1 / 1`.
 4. **`metadata` is caller-owned.** Packages must add protocol-level
    data as top-level fields, never inside `metadata`.
 5. **`source` is the routing origin, not the dispatch type.**