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

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
@@ -296,6 +340,7 @@ export function stripReasoningTags(content: string): string;
  * @property {ChatMessage[]}            messages       - Including the just-appended assistant turn.
  * @property {unknown}                  llmResponse    - Full LLM response (choices, usage, …).
  * @property {string}                   llmOutputText  - May be '' for pure tool-call responses.
+ * @property {Record<string, unknown>|null} usage      - `llmResponse.usage` 的直接引用（prompt/completion/total tokens）。响应没带 usage → null。llmResponse 里本来就有，单独提出来是让「记本轮用量」不必依赖响应对象的具体形状。
  * @property {number}                   iteration      - 0-indexed: the round that just finished.
  * @property {Record<string, unknown>}  metadata
  * @property {string}                   contactName
@@ -391,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-
@@ -407,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.
@@ -433,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.
@@ -525,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`,
@@ -649,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;
@@ -690,6 +770,10 @@ export type SessionContext = {
      * - May be '' for pure tool-call responses.
      */
     llmOutputText: string;
+    /**
+     * - `llmResponse.usage` 的直接引用（prompt/completion/total tokens）。响应没带 usage → null。llmResponse 里本来就有，单独提出来是让「记本轮用量」不必依赖响应对象的具体形状。
+     */
+    usage: Record<string, unknown> | null;
     /**
      * - 0-indexed: the round that just finished.
      */
@@ -705,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.
  */
@@ -719,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";

package/dist/index.d.ts

@@ -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
@@ -296,6 +340,7 @@ export function stripReasoningTags(content: string): string;
  * @property {ChatMessage[]}            messages       - Including the just-appended assistant turn.
  * @property {unknown}                  llmResponse    - Full LLM response (choices, usage, …).
  * @property {string}                   llmOutputText  - May be '' for pure tool-call responses.
+ * @property {Record<string, unknown>|null} usage      - `llmResponse.usage` 的直接引用（prompt/completion/total tokens）。响应没带 usage → null。llmResponse 里本来就有，单独提出来是让「记本轮用量」不必依赖响应对象的具体形状。
  * @property {number}                   iteration      - 0-indexed: the round that just finished.
  * @property {Record<string, unknown>}  metadata
  * @property {string}                   contactName
@@ -391,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-
@@ -407,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.
@@ -433,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.
@@ -525,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`,
@@ -649,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;
@@ -690,6 +770,10 @@ export type SessionContext = {
      * - May be '' for pure tool-call responses.
      */
     llmOutputText: string;
+    /**
+     * - `llmResponse.usage` 的直接引用（prompt/completion/total tokens）。响应没带 usage → null。llmResponse 里本来就有，单独提出来是让「记本轮用量」不必依赖响应对象的具体形状。
+     */
+    usage: Record<string, unknown> | null;
     /**
      * - 0-indexed: the round that just finished.
      */
@@ -705,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.
  */
@@ -719,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";