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

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
@@ -154,6 +154,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 }`。
+
 ---
 
 ## Usage
@@ -184,6 +200,9 @@ function dispatch(push: AmsgPush) {
     case 'error':
       console.error(push.code, push.message);
       break;
+    case 'result':
+      // push.resultKind is `string` — 宿主自己的结果，按它分流
+      break;
   }
 }
 ```
@@ -196,6 +215,7 @@ import {
   buildReasoningPush,
   buildToolRequestPush,
   buildErrorPush,
+  buildResultPush,
 } from '@rei-standard/amsg-shared';
 
 // One sentence in an N-split burst
@@ -238,12 +258,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 +293,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,6 +60,7 @@ __export(src_exports, {
   isContentPush: () => isContentPush,
   isErrorPush: () => isErrorPush,
   isReasoningPush: () => isReasoningPush,
+  isResultPush: () => isResultPush,
   isToolRequestPush: () => isToolRequestPush,
   isValidUrl: () => isValidUrl,
   jsonToBase64Url: () => jsonToBase64Url,
@@ -64,6 +69,7 @@ __export(src_exports, {
   randomBytes: () => randomBytes,
   randomUUID: () => randomUUID,
   readReasoningContent: () => readReasoningContent,
+  redactCredentials: () => redactCredentials,
   sendWebPush: () => sendWebPush,
   stripReasoningTags: () => stripReasoningTags,
   timingSafeEqualBytes: () => timingSafeEqualBytes,
@@ -230,6 +236,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 +255,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 +333,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 +727,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",
@@ -718,8 +985,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 +1028,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) {

package/dist/index.d.cts

@@ -154,6 +154,8 @@ export function buildToolRequestPush(args: {
  * @param {string}      [args.messageSubtype]
  * @param {Object}      [args.metadata]
  * @param {NotificationDirective} [args.notification]
+ * @param {number}      [args.llmStatus]     - 上游 LLM 回的 HTTP 状态码（见 ErrorPush）
+ * @param {string}      [args.providerCode]  - provider 自己的错误码（见 ErrorPush）
  * @returns {ErrorPush}
  */
 export function buildErrorPush(args: {
@@ -168,7 +170,42 @@ export function buildErrorPush(args: {
     messageSubtype?: string;
     metadata?: any;
     notification?: NotificationDirective;
+    llmStatus?: number;
+    providerCode?: string;
 }): ErrorPush;
+/**
+ * Build a {@link ResultPush} —— 宿主自定义的一条结果。
+ *
+ * 与另外四个 builder 有一处不同：**认识以外的字段原样保留**。结果的形状本来
+ * 就由宿主定，白名单式的复制等于把内容删掉一半。库只保证 `messageKind` 与
+ * `timestamp` 到位，其余交给宿主。
+ *
+ * `resultKind` 必填：宿主给这类结果起的名字（`'fire-pack'`、`'ledger-entry'`
+ * ……）。客户端有多种结果时按它分流，不用靠「有没有某个字段」去猜是哪一种。
+ *
+ * @param {Object} args - 整条 payload；下列几个字段有约束，其余原样带过去。
+ * @param {MessageType} args.messageType
+ * @param {PushSource}  args.source
+ * @param {string}      args.messageId
+ * @param {string}      args.sessionId
+ * @param {string}      args.resultKind - 这类结果的名字（宿主自定义）
+ * @param {string}      [args.timestamp]
+ * @param {string}      [args.title]  - 通知标题的兜底（`notification.title` 优先）
+ * @param {string}      [args.body]   - 通知正文的兜底（`notification.body` 优先）
+ * @param {NotificationDirective} [args.notification]
+ * @returns {ResultPush}
+ */
+export function buildResultPush(args: {
+    messageType: MessageType;
+    source: PushSource;
+    messageId: string;
+    sessionId: string;
+    resultKind: string;
+    timestamp?: string;
+    title?: string;
+    body?: string;
+    notification?: NotificationDirective;
+}): ResultPush;
 /**
  * Type guard: returns true if the argument is a {@link ContentPush}.
  *
@@ -197,6 +234,13 @@ export function isToolRequestPush(value: unknown): value is ToolRequestPush;
  * @returns {value is ErrorPush}
  */
 export function isErrorPush(value: unknown): value is ErrorPush;
+/**
+ * Type guard: returns true if the argument is a {@link ResultPush}.
+ *
+ * @param {unknown} value
+ * @returns {value is ResultPush}
+ */
+export function isResultPush(value: unknown): value is ResultPush;
 /**
  * Slice a string into UTF-8 byte chunks no larger than `maxBytes`,
  * always cutting at codepoint boundaries (never inside a multi-byte
@@ -392,7 +436,8 @@ export function extractToolCallsFromDecision(decision: unknown): Array<Record<st
  * Three orthogonal axes:
  *   1. messageType    — how the push was produced (instant / fixed / prompted / auto)
  *   2. messageSubtype — caller's business classification (free-form string)
- *   3. messageKind    — what the push carries (content / reasoning / tool_request / error)
+ *   3. messageKind    — what the push carries (content / reasoning / tool_request /
+ *                       error / result)
  *
  * Zero runtime dependencies. The package is ESM/CJS dual-published and
  * intentionally has no `dependencies:` entry — every other amsg sub-
@@ -408,7 +453,7 @@ export function extractToolCallsFromDecision(decision: unknown): Array<Record<st
 /**
  * What the push carries. Fixed enum — packages must not add values.
  *
- * @typedef {'content' | 'reasoning' | 'tool_request' | 'error'} MessageKind
+ * @typedef {'content' | 'reasoning' | 'tool_request' | 'error' | 'result'} MessageKind
  */
 /**
  * How the push was produced. Fixed enum — packages must not add values.
@@ -434,6 +479,7 @@ export const MESSAGE_KIND: Readonly<{
     REASONING: "reasoning";
     TOOL_REQUEST: "tool_request";
     ERROR: "error";
+    RESULT: "result";
 }>;
 /**
  * Runtime constant mirroring the {@link MessageType} type.
@@ -526,8 +572,9 @@ export type AmsgPushCommon = {
  * so producers get builder validation for the fields the SW actually reads.
  *
  * Routing in SW:
- *   - By default (`show: "auto"` or omitted), `messageKind: 'content'` (and legacy un-kinded payloads)
- *     will display a system notification. `reasoning` / `tool_request` / `error` will dispatch silently.
+ *   - By default (`show: "auto"` or omitted), `messageKind: 'content'` / `'result'` (and legacy
+ *     un-kinded payloads) will display a system notification. `reasoning` / `tool_request` /
+ *     `error` will dispatch silently.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
  *   - When rendering, `notification.*` is consulted first, with per-field
  *     fallback to the matching top-level payload fields (`title`,
@@ -650,18 +697,50 @@ export type ToolRequestPush = AmsgPushCommon & {
  * `{ type: 'error', code: '...' }` envelope. `code` is a stable
  * string; `iteration` is the agentic-loop iteration number when
  * relevant (0 / absent otherwise).
+ *
+ * `llmStatus` / `providerCode` 是失败来自 LLM 调用时的机读标注：上游回的 HTTP
+ * 状态码，以及 provider 自己的错误码（`invalid_api_key` /
+ * `context_length_exceeded` 之类）。客户端靠它们分流「Key 失效要去改配置」和
+ * 「上游一时抽风等会儿再说」，不用回去正则匹配 `message` 那句人话——那句是给
+ * 用户看的，措辞随时会变。失败跟 LLM 无关时两个都不出现。
  */
 export type ErrorPush = AmsgPushCommon & {
     messageKind: "error";
     code: string;
     message: string;
     iteration?: number;
+    llmStatus?: number;
+    providerCode?: string;
+};
+/**
+ * 宿主自定义的一条结果，不是聊天内容。
+ *
+ * 用在「这次跑完产出了点什么，客户端拿去自己消化」的场合：整理好的一份数据、
+ * 一条账目、一次后台生成的产物。形状由宿主定，库只固定三件事——`messageKind`
+ * 是 `'result'`（客户端一眼分得出这不是聊天），`resultKind` 是宿主给这类结果
+ * 起的名字（有多种结果时按它分流，不用去猜字段），其余字段随便加。
+ *
+ * 与另外四种 kind 的区别在投递路径：这一条同时落进服务端收件箱
+ * （`message_outbox`），客户端下次 `GET /outbox?since=` 一定拿得到——推送没送
+ * 到、内容超过一条推送的 4KB 上限，都不会让它丢。产出方见
+ * `@rei-standard/amsg-server` 的 `ctx.emitResult()`。
+ *
+ * SW 侧默认弹通知（与 `content` 同待遇，其余三种是静默送给页面）：结果往往正
+ * 是「跑完了，回来看看」那句话。不想弹就带
+ * `notification: { show: false }`，标题正文也在 `notification` 里自定义。
+ */
+export type ResultPush = AmsgPushCommon & {
+    messageKind: "result";
+    resultKind: string;
+    title?: string;
+    body?: string;
+    data?: any;
 };
 /**
  * Discriminated union of all pushes the SW can receive. TS consumers
  * `switch` on `messageKind` and the compiler narrows automatically.
  */
-export type AmsgPush = ContentPush | ReasoningPush | ToolRequestPush | ErrorPush;
+export type AmsgPush = ContentPush | ReasoningPush | ToolRequestPush | ErrorPush | ResultPush;
 export type ChatMessage = {
     role: "system" | "user" | "assistant" | "tool";
     content?: string | unknown[] | null;
@@ -710,7 +789,7 @@ export type SessionContext = {
 /**
  * What the push carries. Fixed enum — packages must not add values.
  */
-export type MessageKind = "content" | "reasoning" | "tool_request" | "error";
+export type MessageKind = "content" | "reasoning" | "tool_request" | "error" | "result";
 /**
  * How the push was produced. Fixed enum — packages must not add values.
  */
@@ -724,6 +803,7 @@ export type MessageType = "instant" | "fixed" | "prompted" | "auto";
 export type PushSource = "instant" | "scheduled";
 export { toUint8, concatBytes, utf8, utf8Decode, bytesToBase64, bytesToBase64Url, base64UrlToBytes, jsonToBase64Url, bytesToHex, hexToBytes, hmacSha256, timingSafeEqualBytes, randomBytes, randomUUID } from "./webcrypto-utils.js";
 export { LLM_MESSAGES_ERROR, validateLlmMessagesShape } from "./llm-messages.js";
-export { callLlm, buildLlmRequestBody, normalizeAiApiUrl } from "./llm-call.js";
+export { callLlm, buildLlmRequestBody, normalizeAiApiUrl, redactCredentials } from "./llm-call.js";
 export { sendWebPush, buildVapidJwt, verifyVapidJwt } from "./webpush.js";
-export { MULTIPART_MESSAGE_KIND, MULTIPART_ENCODING, MULTIPART_VERSION, DEFAULT_MULTIPART_TTL_MS, DEFAULT_MULTIPART_MAX_CHUNKS, DEFAULT_MULTIPART_MAX_TOTAL_BYTES, REI_AMSG_POSTMESSAGE_TYPE, REI_SW_EVENT, REI_SW_MESSAGE_TYPE, REI_AMSG_DELIVER_MESSAGE_TYPE } from "./protocol.js";
+export { MULTIPART_MESSAGE_KIND, MULTIPART_ENCODING, MULTIPART_VERSION, DEFAULT_MULTIPART_TTL_MS, DEFAULT_MULTIPART_MAX_CHUNKS, DEFAULT_MULTIPART_MAX_TOTAL_BYTES, MULTIPART_FAILURE_REASON, REI_AMSG_POSTMESSAGE_TYPE, REI_SW_EVENT, REI_SW_MESSAGE_TYPE, REI_AMSG_DELIVER_MESSAGE_TYPE } from "./protocol.js";
+export { buildMultipartPushPayloads, DEFAULT_MULTIPART_CHUNK_BYTES } from "./multipart.js";