@rei-standard/amsg-shared 0.4.0-next.9 → 0.4.0

package/README.md

@@ -26,10 +26,10 @@ The two are intentionally independent: any `messageType` can carry any
 `messageKind`.
 
 There is also `source: 'instant' | 'scheduled'` — the **routing
-origin** (`'instant'` for `amsg-instant`, `'scheduled'` for any
-`amsg-server` output). `messageType: 'instant'` always pairs with
-`source: 'instant'`; the other three `messageType`s always pair with
-`source: 'scheduled'`.
+origin**: `messageType: 'instant'` (both `amsg-instant` and
+`amsg-server`'s in-server instant path) always pairs with
+`source: 'instant'`; the other three scheduled `messageType`s always
+pair with `source: 'scheduled'`.
 
 ---
 
@@ -45,6 +45,7 @@ origin** (`'instant'` for `amsg-instant`, `'scheduled'` for any
 | `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.                       |
+| `notification`   | `NotificationDirective?` | Optional producer-side notification display hint (see below).        |
 | `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.                            |
@@ -64,7 +65,7 @@ omit all four.
 
 ## Notification directive
 
-`ContentPush` and `ToolRequestPush` can carry an optional
+Every push variant (`AmsgPushCommon`) can carry an optional
 `notification` object. It is a producer-side hint consumed by
 `@rei-standard/amsg-sw` before rendering a system notification.
 
@@ -187,12 +188,14 @@ instead and may carry a `toolCalls` array directly — see
 
 ### `ErrorPush` — producer-level error
 
-| Field         | Type      | Notes                                                                  |
-|---------------|-----------|------------------------------------------------------------------------|
-| `messageKind` | `'error'` | Discriminator.                                                         |
-| `code`        | `string`  | Stable producer-defined code, e.g. `HOOK_THREW`, `LOOP_EXCEEDED`.      |
-| `message`     | `string`  | Human-readable description.                                            |
-| `iteration`   | `number?` | Agentic-loop iteration when relevant.                                  |
+| Field          | Type      | Notes                                                                  |
+|----------------|-----------|------------------------------------------------------------------------|
+| `messageKind`  | `'error'` | Discriminator.                                                         |
+| `code`         | `string`  | Stable producer-defined code, e.g. `HOOK_THREW`, `LOOP_EXCEEDED`.      |
+| `message`      | `string`  | Human-readable description.                                            |
+| `iteration`    | `number?` | Agentic-loop iteration when relevant.                                  |
+| `llmStatus`    | `number?` | Upstream LLM HTTP status code when the error came from an LLM call.    |
+| `providerCode` | `string?` | Upstream provider error code when present in the LLM error body.       |
 
 Replaces the legacy 0.7.0 `{ type: 'error', code: '...' }` envelope.
 The legacy `type` field is **gone** — do not look for it on
@@ -206,6 +209,7 @@ The legacy `type` field is **gone** — do not look for it on
 | `resultKind`  | `string`   | 宿主给这类结果起的名字（`'fire-pack'`、`'ledger-entry'`……），客户端按它分流。 |
 | `title`       | `string?`  | 通知标题的兜底（`notification.title` 优先）。                    |
 | `body`        | `string?`  | 通知正文的兜底（`notification.body` 优先）。                     |
+| `data`        | `object?`  | 可选结构化数据字段（任意其它顶层自定义字段也会原样保留）。         |
 
 不是聊天内容，而是「这次跑完产出了点什么，客户端拿去自己消化」：整理好的一份数据、一条账目、后台生成的产物。形状由宿主定，`buildResultPush` 是唯一**保留自己不认识的字段**的 builder——白名单式的复制会把内容删掉一半。
 
@@ -362,19 +366,20 @@ the full contract.
 
 `toUint8` · `concatBytes` · `utf8` · `utf8Decode` · `bytesToBase64` ·
 `bytesToBase64Url` · `base64UrlToBytes` · `jsonToBase64Url` ·
-`bytesToHex` · `hexToBytes` · `randomBytes` · `hmacSha256` ·
+`bytesToHex` · `hexToBytes` · `randomBytes` · `randomUUID` · `hmacSha256` ·
 `timingSafeEqualBytes` — WebCrypto-friendly byte/encoding helpers for
-base64url, hex, HMAC, and constant-time comparison.
+base64url, hex, UUID v4 generation, 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. |
+| `buildLlmRequestBody(...)` | Build the request body for prompt mode or `messages` mode (with optional `llmExtraBody`). |
 | `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. |
+| `redactCredentials(text)` | Redact `Bearer ...`, `sk-...`, and long opaque credential tokens from error strings while keeping model names intact. |
 
 ### Web Push
 
@@ -388,8 +393,9 @@ base64url, hex, HMAC, and constant-time comparison.
 
 | 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. |
+| `MULTIPART_MESSAGE_KIND` / `MULTIPART_ENCODING` / `MULTIPART_VERSION` / `MULTIPART_FAILURE_REASON` | The generic multipart chunk envelope (`'_multipart'`) produced by `amsg-instant` / `amsg-server` and reassembled by `amsg-sw`, plus the failure reason enum. |
+| `DEFAULT_MULTIPART_CHUNK_BYTES` / `DEFAULT_MULTIPART_TTL_MS` / `DEFAULT_MULTIPART_MAX_CHUNKS` / `DEFAULT_MULTIPART_MAX_TOTAL_BYTES` | Multipart chunking and reassembly budget defaults. |
+| `buildMultipartPushPayloads(payload, options?)` | Slice a JSON-safe push payload into `_multipart` chunk envelopes. |
 | `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
@@ -398,9 +404,9 @@ base64url, hex, HMAC, and constant-time comparison.
 |---|---|
 | `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. |
+| `buildSessionContext(...)` | Build the frozen, credential-free context object handed to agentic hooks (includes `usage` and optional `scratch`). |
 | `extractAssistantMessage(...)` | Safely read `choices[0].message` off an LLM response (never throws). |
-| `readReasoningContent(...)` | Read `reasoning_content` off an assistant message; empty string means "none". |
+| `readReasoningContent(llmResponse)` | Read `reasoning_content` off an LLM response (or fall back to `<think>` / `<thinking>` / `<thought>` tags in `message.content`); returns `string \| null`. |
 | `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. |
 
@@ -427,8 +433,9 @@ avatar-URL soft-strip rule shared by client / instant / server
    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.**
-   `'instant'` ⇄ `amsg-instant`; `'scheduled'` ⇄ `amsg-server`.
+5. **`source` is the routing origin.**
+   `messageType: 'instant'` pairs with `source: 'instant'`; scheduled
+   `messageType`s (`fixed` / `prompted` / `auto`) pair with `source: 'scheduled'`.
 
 See [§6 of `standards/active-messaging-api.md`](../../../standards/active-messaging-api.md)
 for the wire-level contract.

package/dist/index.cjs

@@ -253,7 +253,7 @@ async function callLlm(payload, options = {}) {
       "Authorization": `Bearer ${payload.apiKey}`
     },
     body: JSON.stringify(requestBody),
-    signal: AbortSignal.timeout(timeoutMs)
+    signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs)
   });
   if (!aiResponse.ok) {
     const detail = await readUpstreamErrorDetail(aiResponse);
@@ -270,8 +270,24 @@ async function callLlm(payload, options = {}) {
       detail
     );
   }
-  const aiData = await aiResponse.json();
-  const rawContent = aiData?.choices?.[0]?.message?.content;
+  const okStatus = Number.isInteger(aiResponse.status) ? aiResponse.status : 200;
+  const body = await readCompletionBody(aiResponse);
+  if (!body.parsed) {
+    throw buildUpstreamError(
+      `AI API error: HTTP ${okStatus} but body is not valid JSON. Request URL: ${normalizedApiUrl}`,
+      okStatus,
+      describeUnparsableBody(body.raw)
+    );
+  }
+  const aiData = body.data;
+  if (!isChatCompletionShape(aiData)) {
+    throw buildUpstreamError(
+      `AI API error: HTTP ${okStatus} but body is not a chat completion (no choices). Request URL: ${normalizedApiUrl}`,
+      okStatus,
+      describeNonCompletionBody(aiData)
+    );
+  }
+  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");
   }
@@ -365,6 +381,9 @@ async function readUpstreamErrorDetail(response) {
     }
     return { message: clampDetail(raw), code: "" };
   }
+  return extractErrorEnvelopeDetail(body, { fallbackMessage: raw });
+}
+function extractErrorEnvelopeDetail(body, { fallbackMessage = "", keepNumericCode = false } = {}) {
   const envelope = body && typeof body === "object" ? body : {};
   const inner = envelope.error && typeof envelope.error === "object" ? envelope.error : {};
   const message = firstNonEmptyString(
@@ -374,9 +393,11 @@ async function readUpstreamErrorDetail(response) {
     // `{ error: "unauthorized" }`
     envelope.message,
     // 一批中转把 message 放最外层
+    envelope.msg,
+    // 国内中转的 `{ code, msg }`
     envelope.detail
     // FastAPI 风格的自建中转
-  ) || raw;
+  ) || fallbackMessage;
   const code = firstNonEmptyString(
     inner.code,
     // OpenAI：invalid_api_key / insufficient_quota / context_length_exceeded
@@ -385,9 +406,61 @@ async function readUpstreamErrorDetail(response) {
     inner.type,
     // Anthropic：invalid_request_error / overloaded_error
     envelope.code
-  );
+  ) || (keepNumericCode ? firstIntegerString(inner.code, envelope.code) : "");
   return { message: clampDetail(message), code: clampCode(code) };
 }
+var EMPTY_BODY_NOTE = "response body is empty";
+var NON_COMPLETION_KEYS_MAX = 10;
+async function readCompletionBody(response) {
+  if (typeof response.text === "function") {
+    const raw = await response.text();
+    try {
+      return { parsed: true, data: JSON.parse(raw) };
+    } catch {
+      return { parsed: false, raw: typeof raw === "string" ? raw : null };
+    }
+  }
+  try {
+    return { parsed: true, data: await response.json() };
+  } catch (error) {
+    if (error && /** @type {any} */
+    error.name === "SyntaxError") return { parsed: false, raw: null };
+    throw error;
+  }
+}
+function isChatCompletionShape(data) {
+  return !!data && typeof data === "object" && Array.isArray(
+    /** @type {any} */
+    data.choices
+  ) && /** @type {any} */
+  data.choices.length > 0;
+}
+function describeUnparsableBody(raw) {
+  if (raw === null) return { message: "", code: "" };
+  const trimmed = raw.trim();
+  if (!trimmed) return { message: EMPTY_BODY_NOTE, code: "" };
+  if (looksLikeSseStream(trimmed)) return { message: SSE_BODY_NOTE, code: "" };
+  return { message: clampDetail(raw), code: "" };
+}
+function looksLikeSseStream(trimmed) {
+  return trimmed.startsWith(":") || SSE_FIELD_LINE.test(trimmed);
+}
+var SSE_FIELD_LINE = /^(?:data|event|id|retry):/im;
+var SSE_BODY_NOTE = "response body looks like an SSE stream (the endpoint ignored stream: false)";
+function describeNonCompletionBody(data) {
+  const detail = extractErrorEnvelopeDetail(data, { keepNumericCode: true });
+  if (detail.message || detail.code) return detail;
+  let shape;
+  if (Array.isArray(data)) {
+    shape = "response body is a JSON array";
+  } else if (data && typeof data === "object") {
+    const keys = Object.keys(data);
+    shape = keys.length === 0 ? "response body is an empty object" : `top-level keys: ${keys.slice(0, NON_COMPLETION_KEYS_MAX).join(", ")}` + (keys.length > NON_COMPLETION_KEYS_MAX ? ", \u2026" : "");
+  } else {
+    shape = `response body is ${data === null ? "null" : `a JSON ${typeof data}`}`;
+  }
+  return { message: clampDetail(shape), code: "" };
+}
 async function readBoundedBody(response) {
   const body = response && response.body;
   if (!body || typeof body.getReader !== "function") {
@@ -512,6 +585,12 @@ function firstNonEmptyString(...values) {
   }
   return "";
 }
+function firstIntegerString(...values) {
+  for (const value of values) {
+    if (Number.isInteger(value)) return String(value);
+  }
+  return "";
+}
 
 // src/webpush.js
 var KEY_INFO_PREFIX = utf8("WebPush: info\0");

package/dist/index.mjs

@@ -168,7 +168,7 @@ async function callLlm(payload, options = {}) {
       "Authorization": `Bearer ${payload.apiKey}`
     },
     body: JSON.stringify(requestBody),
-    signal: AbortSignal.timeout(timeoutMs)
+    signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs)
   });
   if (!aiResponse.ok) {
     const detail = await readUpstreamErrorDetail(aiResponse);
@@ -185,8 +185,24 @@ async function callLlm(payload, options = {}) {
       detail
     );
   }
-  const aiData = await aiResponse.json();
-  const rawContent = aiData?.choices?.[0]?.message?.content;
+  const okStatus = Number.isInteger(aiResponse.status) ? aiResponse.status : 200;
+  const body = await readCompletionBody(aiResponse);
+  if (!body.parsed) {
+    throw buildUpstreamError(
+      `AI API error: HTTP ${okStatus} but body is not valid JSON. Request URL: ${normalizedApiUrl}`,
+      okStatus,
+      describeUnparsableBody(body.raw)
+    );
+  }
+  const aiData = body.data;
+  if (!isChatCompletionShape(aiData)) {
+    throw buildUpstreamError(
+      `AI API error: HTTP ${okStatus} but body is not a chat completion (no choices). Request URL: ${normalizedApiUrl}`,
+      okStatus,
+      describeNonCompletionBody(aiData)
+    );
+  }
+  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");
   }
@@ -280,6 +296,9 @@ async function readUpstreamErrorDetail(response) {
     }
     return { message: clampDetail(raw), code: "" };
   }
+  return extractErrorEnvelopeDetail(body, { fallbackMessage: raw });
+}
+function extractErrorEnvelopeDetail(body, { fallbackMessage = "", keepNumericCode = false } = {}) {
   const envelope = body && typeof body === "object" ? body : {};
   const inner = envelope.error && typeof envelope.error === "object" ? envelope.error : {};
   const message = firstNonEmptyString(
@@ -289,9 +308,11 @@ async function readUpstreamErrorDetail(response) {
     // `{ error: "unauthorized" }`
     envelope.message,
     // 一批中转把 message 放最外层
+    envelope.msg,
+    // 国内中转的 `{ code, msg }`
     envelope.detail
     // FastAPI 风格的自建中转
-  ) || raw;
+  ) || fallbackMessage;
   const code = firstNonEmptyString(
     inner.code,
     // OpenAI：invalid_api_key / insufficient_quota / context_length_exceeded
@@ -300,9 +321,61 @@ async function readUpstreamErrorDetail(response) {
     inner.type,
     // Anthropic：invalid_request_error / overloaded_error
     envelope.code
-  );
+  ) || (keepNumericCode ? firstIntegerString(inner.code, envelope.code) : "");
   return { message: clampDetail(message), code: clampCode(code) };
 }
+var EMPTY_BODY_NOTE = "response body is empty";
+var NON_COMPLETION_KEYS_MAX = 10;
+async function readCompletionBody(response) {
+  if (typeof response.text === "function") {
+    const raw = await response.text();
+    try {
+      return { parsed: true, data: JSON.parse(raw) };
+    } catch {
+      return { parsed: false, raw: typeof raw === "string" ? raw : null };
+    }
+  }
+  try {
+    return { parsed: true, data: await response.json() };
+  } catch (error) {
+    if (error && /** @type {any} */
+    error.name === "SyntaxError") return { parsed: false, raw: null };
+    throw error;
+  }
+}
+function isChatCompletionShape(data) {
+  return !!data && typeof data === "object" && Array.isArray(
+    /** @type {any} */
+    data.choices
+  ) && /** @type {any} */
+  data.choices.length > 0;
+}
+function describeUnparsableBody(raw) {
+  if (raw === null) return { message: "", code: "" };
+  const trimmed = raw.trim();
+  if (!trimmed) return { message: EMPTY_BODY_NOTE, code: "" };
+  if (looksLikeSseStream(trimmed)) return { message: SSE_BODY_NOTE, code: "" };
+  return { message: clampDetail(raw), code: "" };
+}
+function looksLikeSseStream(trimmed) {
+  return trimmed.startsWith(":") || SSE_FIELD_LINE.test(trimmed);
+}
+var SSE_FIELD_LINE = /^(?:data|event|id|retry):/im;
+var SSE_BODY_NOTE = "response body looks like an SSE stream (the endpoint ignored stream: false)";
+function describeNonCompletionBody(data) {
+  const detail = extractErrorEnvelopeDetail(data, { keepNumericCode: true });
+  if (detail.message || detail.code) return detail;
+  let shape;
+  if (Array.isArray(data)) {
+    shape = "response body is a JSON array";
+  } else if (data && typeof data === "object") {
+    const keys = Object.keys(data);
+    shape = keys.length === 0 ? "response body is an empty object" : `top-level keys: ${keys.slice(0, NON_COMPLETION_KEYS_MAX).join(", ")}` + (keys.length > NON_COMPLETION_KEYS_MAX ? ", \u2026" : "");
+  } else {
+    shape = `response body is ${data === null ? "null" : `a JSON ${typeof data}`}`;
+  }
+  return { message: clampDetail(shape), code: "" };
+}
 async function readBoundedBody(response) {
   const body = response && response.body;
   if (!body || typeof body.getReader !== "function") {
@@ -427,6 +500,12 @@ function firstNonEmptyString(...values) {
   }
   return "";
 }
+function firstIntegerString(...values) {
+  for (const value of values) {
+    if (Number.isInteger(value)) return String(value);
+  }
+  return "";
+}
 
 // src/webpush.js
 var KEY_INFO_PREFIX = utf8("WebPush: info\0");

package/dist/llm-call.d.cts

@@ -10,6 +10,7 @@
  * @param {{
  *   requireContent?: boolean,
  *   timeoutMs?: number,
+ *   signal?: AbortSignal,
  *   fetch?: typeof globalThis.fetch,
  *   stream?: boolean,
  *   forwardTools?: boolean,
@@ -17,21 +18,32 @@
  *   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 agentic loops pass
- *   `{ requireContent: false }`.
+ *   `{ requireContent: false }`. It only decides whether an empty
+ *   `content` counts as a failure; a 2xx body that is not a chat
+ *   completion at all throws either way (see @throws).
  *   timeoutMs defaults to 300000 (the legacy per-call ceiling).
  *   fetch defaults to `globalThis.fetch` (resolved at call time so test
  *   stubs on the global still take effect).
  *   stream / forwardTools are forwarded to {@link buildLlmRequestBody}.
  * @returns {Promise<{ response: unknown, content: string }>}
- * @throws {Error} 上游回非 2xx 时抛，错误上带机读标注（见
+ * @throws {Error} 上游答复了、但没给出能用的结果时抛，错误上带机读标注（见
  *   {@link buildUpstreamError}）：`code` = `'LLM_CALL_FAILED'`、`llmStatus` =
  *   上游的 HTTP 状态码、`providerCode` = provider 自己的错误码（拿得到才有）。
- *   这三个字段只在上游确实答复了的时候出现——网络直接炸、超时、响应体不是
- *   合法 JSON 时不会有，接入方据此也能分清「上游拒了」和「根本没连上」。
+ *   两种情况：
+ *   - 上游回非 2xx；
+ *   - 上游回 2xx，但响应体解析不成 JSON，或者没有非空的 `choices` 数组（中转站
+ *     把报错塞进 200 响应体就是这样）。这时 `llmStatus` 就是那个 2xx，而且不管
+ *     requireContent 取什么都抛。
+ *   这三个字段只在上游确实答复了的时候出现——网络直接炸、超时的时候不会有，接入
+ *   方据此也能分清「上游拒了」和「根本没连上」。
+ *   `choices` 在、只是 content 为空（纯 tool_calls、被内容审核拦下）是合法的空
+ *   生成，requireContent 为 false 时照常返回；为 true 时抛的那条错误不带上面这些
+ *   标注。
  */
 export function callLlm(payload: any, options?: {
     requireContent?: boolean;
     timeoutMs?: number;
+    signal?: AbortSignal;
     fetch?: typeof globalThis.fetch;
     stream?: boolean;
     forwardTools?: boolean;

package/dist/llm-call.d.ts

@@ -10,6 +10,7 @@
  * @param {{
  *   requireContent?: boolean,
  *   timeoutMs?: number,
+ *   signal?: AbortSignal,
  *   fetch?: typeof globalThis.fetch,
  *   stream?: boolean,
  *   forwardTools?: boolean,
@@ -17,21 +18,32 @@
  *   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 agentic loops pass
- *   `{ requireContent: false }`.
+ *   `{ requireContent: false }`. It only decides whether an empty
+ *   `content` counts as a failure; a 2xx body that is not a chat
+ *   completion at all throws either way (see @throws).
  *   timeoutMs defaults to 300000 (the legacy per-call ceiling).
  *   fetch defaults to `globalThis.fetch` (resolved at call time so test
  *   stubs on the global still take effect).
  *   stream / forwardTools are forwarded to {@link buildLlmRequestBody}.
  * @returns {Promise<{ response: unknown, content: string }>}
- * @throws {Error} 上游回非 2xx 时抛，错误上带机读标注（见
+ * @throws {Error} 上游答复了、但没给出能用的结果时抛，错误上带机读标注（见
  *   {@link buildUpstreamError}）：`code` = `'LLM_CALL_FAILED'`、`llmStatus` =
  *   上游的 HTTP 状态码、`providerCode` = provider 自己的错误码（拿得到才有）。
- *   这三个字段只在上游确实答复了的时候出现——网络直接炸、超时、响应体不是
- *   合法 JSON 时不会有，接入方据此也能分清「上游拒了」和「根本没连上」。
+ *   两种情况：
+ *   - 上游回非 2xx；
+ *   - 上游回 2xx，但响应体解析不成 JSON，或者没有非空的 `choices` 数组（中转站
+ *     把报错塞进 200 响应体就是这样）。这时 `llmStatus` 就是那个 2xx，而且不管
+ *     requireContent 取什么都抛。
+ *   这三个字段只在上游确实答复了的时候出现——网络直接炸、超时的时候不会有，接入
+ *   方据此也能分清「上游拒了」和「根本没连上」。
+ *   `choices` 在、只是 content 为空（纯 tool_calls、被内容审核拦下）是合法的空
+ *   生成，requireContent 为 false 时照常返回；为 true 时抛的那条错误不带上面这些
+ *   标注。
  */
 export function callLlm(payload: any, options?: {
     requireContent?: boolean;
     timeoutMs?: number;
+    signal?: AbortSignal;
     fetch?: typeof globalThis.fetch;
     stream?: boolean;
     forwardTools?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-shared",
-  "version": "0.4.0-next.9",
+  "version": "0.4.0",
   "description": "ReiStandard Active Messaging shared types and push builders — the lowest layer (no deps on other amsg packages)",
   "repository": {
     "type": "git",