@rei-standard/amsg-shared 0.4.0-next.5 → 0.4.0-next.7

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
@@ -70,7 +70,7 @@ omit all four.
 
 | 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. |
@@ -84,6 +84,38 @@ omit all four.
 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#不展示通知的代价)。
+
+### `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
@@ -154,6 +186,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
@@ -184,6 +232,9 @@ function dispatch(push: AmsgPush) {
     case 'error':
       console.error(push.code, push.message);
       break;
+    case 'result':
+      // push.resultKind is `string` — 宿主自己的结果，按它分流
+      break;
   }
 }
 ```
@@ -196,6 +247,7 @@ import {
   buildReasoningPush,
   buildToolRequestPush,
   buildErrorPush,
+  buildResultPush,
 } from '@rei-standard/amsg-shared';
 
 // One sentence in an N-split burst
@@ -238,12 +290,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, isToolRequestPush, isErrorPush } from '@rei-standard/amsg-shared';
+import { isContentPush, isReasoningPush, isToolRequestPush, isErrorPush, isResultPush } from '@rei-standard/amsg-shared';
 
 if (isContentPush(push)) {
   // push.message is `string`
@@ -261,6 +325,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'

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   AVATAR_URL_MAX_LENGTH: () => AVATAR_URL_MAX_LENGTH,
+  DEFAULT_MULTIPART_CHUNK_BYTES: () => DEFAULT_MULTIPART_CHUNK_BYTES,
   DEFAULT_MULTIPART_MAX_CHUNKS: () => DEFAULT_MULTIPART_MAX_CHUNKS,
   DEFAULT_MULTIPART_MAX_TOTAL_BYTES: () => DEFAULT_MULTIPART_MAX_TOTAL_BYTES,
   DEFAULT_MULTIPART_TTL_MS: () => DEFAULT_MULTIPART_TTL_MS,
@@ -27,6 +28,7 @@ __export(src_exports, {
   MESSAGE_KIND: () => MESSAGE_KIND,
   MESSAGE_TYPE: () => MESSAGE_TYPE,
   MULTIPART_ENCODING: () => MULTIPART_ENCODING,
+  MULTIPART_FAILURE_REASON: () => MULTIPART_FAILURE_REASON,
   MULTIPART_MESSAGE_KIND: () => MULTIPART_MESSAGE_KIND,
   MULTIPART_VERSION: () => MULTIPART_VERSION,
   PUSH_SOURCE: () => PUSH_SOURCE,
@@ -39,7 +41,9 @@ __export(src_exports, {
   buildContentPush: () => buildContentPush,
   buildErrorPush: () => buildErrorPush,
   buildLlmRequestBody: () => buildLlmRequestBody,
+  buildMultipartPushPayloads: () => buildMultipartPushPayloads,
   buildReasoningPush: () => buildReasoningPush,
+  buildResultPush: () => buildResultPush,
   buildSessionContext: () => buildSessionContext,
   buildToolRequestPush: () => buildToolRequestPush,
   buildVapidJwt: () => buildVapidJwt,
@@ -56,14 +60,17 @@ __export(src_exports, {
   isContentPush: () => isContentPush,
   isErrorPush: () => isErrorPush,
   isReasoningPush: () => isReasoningPush,
+  isResultPush: () => isResultPush,
   isToolRequestPush: () => isToolRequestPush,
   isValidUrl: () => isValidUrl,
   jsonToBase64Url: () => jsonToBase64Url,
   normalizeAiApiUrl: () => normalizeAiApiUrl,
   normalizeVapidSubject: () => normalizeVapidSubject,
+  notificationIntent: () => notificationIntent,
   randomBytes: () => randomBytes,
   randomUUID: () => randomUUID,
   readReasoningContent: () => readReasoningContent,
+  redactCredentials: () => redactCredentials,
   sendWebPush: () => sendWebPush,
   stripReasoningTags: () => stripReasoningTags,
   timingSafeEqualBytes: () => timingSafeEqualBytes,
@@ -230,6 +237,9 @@ function validateLlmMessagesShape(messages) {
 }
 
 // src/llm-call.js
+var UPSTREAM_ERROR_DETAIL_MAX_CHARS = 300;
+var UPSTREAM_ERROR_CODE_MAX_CHARS = 64;
+var UPSTREAM_ERROR_BODY_MAX_BYTES = 16 * 1024;
 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 : 3e5;
@@ -246,13 +256,18 @@ async function callLlm(payload, options = {}) {
     signal: AbortSignal.timeout(timeoutMs)
   });
   if (!aiResponse.ok) {
+    const detail = await readUpstreamErrorDetail(aiResponse);
     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 buildUpstreamError(
+        `AI API error: 405 Method Not Allowed. apiUrl must point to a full chat endpoint (for example: /chat/completions). Received: ${normalizedApiUrl}`,
+        aiResponse.status,
+        detail
       );
     }
-    throw new Error(
-      `AI API error: ${aiResponse.status} ${aiResponse.statusText || "Unknown Error"}. Request URL: ${normalizedApiUrl}`
+    throw buildUpstreamError(
+      `AI API error: ${aiResponse.status} ${aiResponse.statusText || "Unknown Error"}. Request URL: ${normalizedApiUrl}`,
+      aiResponse.status,
+      detail
     );
   }
   const aiData = await aiResponse.json();
@@ -319,6 +334,169 @@ function normalizeAiApiUrl(apiUrl) {
   parsed.pathname = path;
   return parsed.toString();
 }
+function buildUpstreamError(summary, status, detail) {
+  const error = new Error(
+    summary + (detail.message ? ` \u2014 ${detail.message}` : "") + (detail.code ? ` (provider code: ${detail.code})` : "")
+  );
+  error.code = "LLM_CALL_FAILED";
+  error.llmStatus = status;
+  if (detail.code) error.providerCode = detail.code;
+  return error;
+}
+async function readUpstreamErrorDetail(response) {
+  let raw;
+  let truncated = false;
+  try {
+    ({ text: raw, truncated } = await readBoundedBody(response));
+  } catch {
+    return { message: "", code: "" };
+  }
+  if (typeof raw !== "string" || !raw.trim()) return { message: "", code: "" };
+  let body;
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    if (truncated && looksLikeJson(raw)) {
+      const salvaged = salvageJsonStringFields(raw);
+      return {
+        message: clampDetail(salvaged.message || TRUNCATED_BODY_NOTE),
+        code: clampCode(salvaged.code)
+      };
+    }
+    return { message: clampDetail(raw), code: "" };
+  }
+  const envelope = body && typeof body === "object" ? body : {};
+  const inner = envelope.error && typeof envelope.error === "object" ? envelope.error : {};
+  const message = firstNonEmptyString(
+    inner.message,
+    // OpenAI / Anthropic / Gemini
+    typeof envelope.error === "string" ? envelope.error : "",
+    // `{ error: "unauthorized" }`
+    envelope.message,
+    // 一批中转把 message 放最外层
+    envelope.detail
+    // FastAPI 风格的自建中转
+  ) || raw;
+  const code = firstNonEmptyString(
+    inner.code,
+    // OpenAI：invalid_api_key / insufficient_quota / context_length_exceeded
+    inner.status,
+    // Gemini：INVALID_ARGUMENT / RESOURCE_EXHAUSTED
+    inner.type,
+    // Anthropic：invalid_request_error / overloaded_error
+    envelope.code
+  );
+  return { message: clampDetail(message), code: clampCode(code) };
+}
+async function readBoundedBody(response) {
+  const body = response && response.body;
+  if (!body || typeof body.getReader !== "function") {
+    const text = typeof response.text === "function" ? await response.text() : "";
+    return { text, truncated: false };
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let bytes = 0;
+  try {
+    while (bytes < UPSTREAM_ERROR_BODY_MAX_BYTES) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value || !value.length) continue;
+      chunks.push(value);
+      bytes += value.length;
+    }
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {
+    }
+  }
+  return {
+    text: utf8Decode(concatBytes(...chunks)),
+    truncated: bytes >= UPSTREAM_ERROR_BODY_MAX_BYTES
+  };
+}
+var TRUNCATED_BODY_NOTE = "upstream error body was truncated before any readable message";
+var JSON_STRING_FIELD = /"(message|detail|code|status|type)"\s*:\s*"((?:[^"\\]|\\.)*)"/g;
+function looksLikeJson(raw) {
+  return /^\s*[{[]/.test(raw);
+}
+function salvageJsonStringFields(raw) {
+  const found = {};
+  for (const match of raw.matchAll(JSON_STRING_FIELD)) {
+    if (found[match[1]] === void 0) found[match[1]] = unescapeJsonString(match[2]);
+  }
+  return {
+    message: firstNonEmptyString(found.message, found.detail),
+    code: firstNonEmptyString(found.code, found.status, found.type)
+  };
+}
+function unescapeJsonString(value) {
+  try {
+    return JSON.parse(`"${value}"`);
+  } catch {
+    return value;
+  }
+}
+function clampDetail(text) {
+  const flattened = String(text ?? "").replace(/\s+/g, " ").trim();
+  const safe = redactCredentials(flattened);
+  return safe.length > UPSTREAM_ERROR_DETAIL_MAX_CHARS ? `${safe.slice(0, UPSTREAM_ERROR_DETAIL_MAX_CHARS - 1)}\u2026` : safe;
+}
+function clampCode(code) {
+  return String(code ?? "").replace(/\s+/g, " ").trim().slice(0, UPSTREAM_ERROR_CODE_MAX_CHARS);
+}
+var CREDENTIAL_LIKE_TOKEN = /\b[A-Za-z]{2,6}-[A-Za-z0-9_-]{16,}/g;
+var LONG_OPAQUE_RUN = /[A-Za-z0-9+/_.-]{48,}/g;
+var MODEL_ID_LIKE = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]{1,12})+$/;
+var MODEL_ID_MAX_CHARS = 64;
+var CREDENTIAL_PREFIX_SEGMENTS = /* @__PURE__ */ new Set([
+  "sk",
+  "pk",
+  "ak",
+  "api",
+  "apikey",
+  "key",
+  "token",
+  "secret",
+  "auth",
+  "bearer",
+  "session",
+  "sess",
+  "pat",
+  "xai",
+  "gsk"
+]);
+var UUID_SHAPE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/;
+function alternationCount(segment) {
+  return (segment.match(/[a-z]+|[0-9]+/g) || []).length;
+}
+function looksLikeModelId(token) {
+  if (token.length > MODEL_ID_MAX_CHARS) return false;
+  if (!MODEL_ID_LIKE.test(token)) return false;
+  if (UUID_SHAPE.test(token)) return false;
+  const segments = token.split(/[.-]/);
+  if (CREDENTIAL_PREFIX_SEGMENTS.has(segments[0])) return false;
+  const randomLooking = segments.filter((segment) => alternationCount(segment) >= 3);
+  if (randomLooking.length === 0) return true;
+  return randomLooking.length === 1 && randomLooking[0].length <= 5;
+}
+function redactCredentials(text) {
+  let s = text;
+  s = s.replace(/Bearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer [redacted]");
+  s = s.replace(CREDENTIAL_LIKE_TOKEN, (token) => looksLikeModelId(token) ? token : "[redacted]");
+  s = s.replace(LONG_OPAQUE_RUN, (run) => {
+    const token = run.replace(/^[._+/-]+/, "").replace(/[._+/-]+$/, "");
+    return looksLikeModelId(token) ? run : "[redacted]";
+  });
+  return s;
+}
+function firstNonEmptyString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return "";
+}
 
 // src/webpush.js
 var KEY_INFO_PREFIX = utf8("WebPush: info\0");
@@ -550,23 +728,113 @@ var REI_SW_EVENT = Object.freeze({
   REASONING_RECEIVED: "rei-amsg-reasoning-received",
   TOOL_REQUEST_RECEIVED: "rei-amsg-tool-request-received",
   ERROR_RECEIVED: "rei-amsg-error-received",
+  /** 宿主自定义的一条结果（`messageKind: 'result'`），不是聊天内容。 */
+  RESULT_RECEIVED: "rei-amsg-result-received",
   MULTIPART_EXPIRED: "rei-amsg-multipart-expired",
   UNKNOWN_RECEIVED: "rei-amsg-unknown-received"
 });
+var MULTIPART_FAILURE_REASON = Object.freeze({
+  /** TTL 到期仍未收齐，或收到的分片本身已经过期。 */
+  TTL_EXPIRED: "ttl-expired",
+  /** 分片信封不合规：version / encoding 对不上、index 越界、chunk 不是合法 base64url。 */
+  INVALID_CHUNK: "invalid-chunk",
+  /** 同一个 id 的分片报了不一样的 total / encoding，已收的部分拼不回去。 */
+  CHUNK_CONFLICT: "chunk-conflict",
+  /** 累计字节数超过 maxTotalBytes。 */
+  SIZE_LIMIT_EXCEEDED: "size-limit-exceeded",
+  /** 收齐了但拼不回原 payload（缺片、超限、JSON 解不开）。 */
+  RESTORE_FAILED: "restore-failed",
+  /** 分片仓库（IndexedDB）读写失败。 */
+  STORAGE_FAILED: "storage-failed",
+  /** 接收端把 multipart 关了（`multipart.enabled === false`），分片没法重组。 */
+  DISABLED: "disabled"
+});
 var REI_SW_MESSAGE_TYPE = Object.freeze({
   ENQUEUE_REQUEST: "REI_ENQUEUE_REQUEST",
   DELIVER: "REI_AMSG_DELIVER",
   FLUSH_QUEUE: "REI_FLUSH_QUEUE",
-  QUEUE_RESULT: "REI_QUEUE_RESULT"
+  /**
+   * 入队的点对点回执：谁发的 ENQUEUE_REQUEST 就回给谁一条，一次一条。
+   * 没转 MessagePort 过来时会落到全局的 `navigator.serviceWorker` message
+   * 监听器上。
+   */
+  QUEUE_RESULT: "REI_QUEUE_RESULT",
+  /**
+   * 队列请求被永久拒绝、即将从队列里删掉时广播给所有窗口的一条。
+   *
+   * 跟 QUEUE_RESULT 分开是因为两者的收信人不是一回事：这条是广播，可能来自后台
+   * `sync` 冲刷、说的也可能是另一条八竿子打不着的旧请求。共用一个 type 的话，
+   * 页面等自己那条入队回执时会先收到这一条、当成自己的结果处理。
+   */
+  QUEUE_DROPPED: "REI_QUEUE_DROPPED"
 });
 var REI_AMSG_DELIVER_MESSAGE_TYPE = REI_SW_MESSAGE_TYPE.DELIVER;
 
+// src/multipart.js
+var DEFAULT_MULTIPART_CHUNK_BYTES = 1800;
+function buildMultipartPushPayloads(payload, options = {}) {
+  const maxChunkBytes = resolvePositiveInteger(
+    options.maxChunkBytes,
+    DEFAULT_MULTIPART_CHUNK_BYTES,
+    "maxChunkBytes"
+  );
+  const ttlMs = resolvePositiveInteger(options.ttlMs, DEFAULT_MULTIPART_TTL_MS, "ttlMs");
+  const id = typeof options.id === "string" && options.id.trim() ? options.id.trim() : `mp_${randomUUID()}`;
+  let serialized = typeof options.serializedPayload === "string" ? options.serializedPayload : void 0;
+  if (serialized === void 0) {
+    try {
+      serialized = JSON.stringify(payload);
+    } catch (error) {
+      throw new TypeError(`buildMultipartPushPayloads: payload is not JSON-serializable: ${error?.message ?? error}`);
+    }
+  }
+  if (typeof serialized !== "string") {
+    throw new TypeError("buildMultipartPushPayloads: payload serialized to a non-string");
+  }
+  const bytes = utf8(serialized);
+  const total = Math.max(1, Math.ceil(bytes.byteLength / maxChunkBytes));
+  const createdAt = Date.now();
+  const originalMessageKind = payload && typeof payload === "object" ? (
+    /** @type {{ messageKind?: unknown }} */
+    payload.messageKind
+  ) : void 0;
+  const parts = [];
+  for (let i = 0; i < total; i++) {
+    const start = i * maxChunkBytes;
+    const end = Math.min(start + maxChunkBytes, bytes.byteLength);
+    const chunkBytes = bytes.subarray(start, end);
+    parts.push({
+      messageKind: MULTIPART_MESSAGE_KIND,
+      multipart: {
+        version: MULTIPART_VERSION,
+        id,
+        index: i + 1,
+        total,
+        encoding: MULTIPART_ENCODING,
+        originalMessageKind: typeof originalMessageKind === "string" ? originalMessageKind : null,
+        createdAt,
+        ttlMs
+      },
+      chunk: bytesToBase64Url(chunkBytes)
+    });
+  }
+  return parts;
+}
+function resolvePositiveInteger(value, fallback, fieldName) {
+  if (value === void 0 || value === null) return fallback;
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(`buildMultipartPushPayloads: ${fieldName} must be a positive integer`);
+  }
+  return value;
+}
+
 // src/index.js
 var MESSAGE_KIND = Object.freeze({
   CONTENT: "content",
   REASONING: "reasoning",
   TOOL_REQUEST: "tool_request",
-  ERROR: "error"
+  ERROR: "error",
+  RESULT: "result"
 });
 var MESSAGE_TYPE = Object.freeze({
   INSTANT: "instant",
@@ -578,6 +846,17 @@ var PUSH_SOURCE = Object.freeze({
   INSTANT: "instant",
   SCHEDULED: "scheduled"
 });
+function notificationIntent(payload) {
+  const notification = payload && typeof payload === "object" && payload.notification;
+  const show = notification && typeof notification === "object" ? notification.show : void 0;
+  if (show === "always") return "always";
+  if (show === "when-hidden") return "when-hidden";
+  if (show === false) return "never";
+  if (!payload || typeof payload !== "object") return "never";
+  const kind = payload.messageKind;
+  if (kind === void 0 || kind === null) return "always";
+  return kind === MESSAGE_KIND.CONTENT || kind === MESSAGE_KIND.RESULT ? "always" : "never";
+}
 function requireField(kind, field, value) {
   if (value === void 0 || value === null || value === "") {
     throw new Error(`[amsg-shared] ${kind}: '${field}' is required`);
@@ -718,8 +997,33 @@ function buildErrorPush(args) {
   if (args.messageSubtype !== void 0) push.messageSubtype = args.messageSubtype;
   if (args.metadata !== void 0) push.metadata = args.metadata;
   if (args.notification !== void 0) push.notification = args.notification;
+  if (args.llmStatus !== void 0) push.llmStatus = args.llmStatus;
+  if (args.providerCode !== void 0) push.providerCode = args.providerCode;
   return push;
 }
+function buildResultPush(args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) {
+    throw new Error("[amsg-shared] ResultPush: payload must be a plain object");
+  }
+  requireField("ResultPush", "messageType", args.messageType);
+  requireField("ResultPush", "source", args.source);
+  requireField("ResultPush", "messageId", args.messageId);
+  requireField("ResultPush", "sessionId", args.sessionId);
+  if (typeof args.resultKind !== "string" || !args.resultKind.trim()) {
+    throw new Error(
+      "[amsg-shared] ResultPush: 'resultKind' must be a non-empty string\uFF08\u7ED9\u8FD9\u7C7B\u7ED3\u679C\u8D77\u4E2A\u540D\u5B57\uFF0C\u5BA2\u6237\u7AEF\u6309\u5B83\u5206\u6D41\uFF09"
+    );
+  }
+  validateNotificationArg("ResultPush", args.notification);
+  return (
+    /** @type {ResultPush} */
+    {
+      ...args,
+      messageKind: "result",
+      timestamp: args.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+    }
+  );
+}
 function isContentPush(value) {
   return !!value && typeof value === "object" && /** @type {{messageKind?: unknown}} */
   value.messageKind === "content";
@@ -736,6 +1040,10 @@ function isErrorPush(value) {
   return !!value && typeof value === "object" && /** @type {{messageKind?: unknown}} */
   value.messageKind === "error";
 }
+function isResultPush(value) {
+  return !!value && typeof value === "object" && /** @type {{messageKind?: unknown}} */
+  value.messageKind === "result";
+}
 var REASONING_CHUNK_ENCODER = new TextEncoder();
 var REASONING_CHUNK_DECODER = new TextDecoder("utf-8", { fatal: true });
 function chunkReasoningByUtf8Bytes(text, maxBytes) {