@rei-standard/amsg-shared 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @rei-standard/amsg-shared
 
-Lowest layer of the ReiStandard Active Messaging ecosystem. Defines
-the **three-axis push contract** that `amsg-instant`, `amsg-server`,
+Lowest layer of the ReiStandard Active Messaging stack. Defines
+the **push schema** that `amsg-instant`, `amsg-server`,
 `amsg-sw`, and `amsg-client` all conform to.
 
 Zero runtime deps. Does **not** depend on any other amsg package —
@@ -9,9 +9,9 @@ every other amsg sub-package depends on this one, never the reverse.
 
 ---
 
-## Three axes
+## Push schema
 
-A single push is described by three orthogonal axes:
+A single push is described by three independent dimensions:
 
 | Axis           | Field             | Values                                                | Defined by         |
 |----------------|-------------------|-------------------------------------------------------|--------------------|
@@ -22,7 +22,7 @@ A single push is described by three orthogonal axes:
 `messageType` answers **how this push was produced** (one-shot
 `instant` worker, scheduled `fixed` ping, AI-`prompted` reply, fully
 `auto`-generated cadence). `messageKind` answers **what it carries**.
-The two are intentionally orthogonal: any `messageType` can carry any
+The two are intentionally independent: any `messageType` can carry any
 `messageKind`.
 
 There is also `source: 'instant' | 'scheduled'` — the **routing
@@ -48,6 +48,30 @@ origin** (`'instant'` for `amsg-instant`, `'scheduled'` for any
 
 ---
 
+## Notification directive
+
+`ContentPush` and `ToolRequestPush` can carry an optional
+`notification` object. It is a producer-side hint consumed by
+`@rei-standard/amsg-sw` before rendering a system notification.
+
+| Field                | Type                                      | Notes |
+|----------------------|-------------------------------------------|-------|
+| `show`               | `'auto' \| 'always' \| 'when-hidden' \| false` | Display policy. `auto` follows SW defaults. |
+| `title`              | `string?`                                | Notification title override. |
+| `body`               | `string?`                                | Notification body override. |
+| `icon`               | `string?`                                | Notification icon URL. |
+| `badge`              | `string?`                                | Notification badge URL. |
+| `tag`                | `string?`                                | Notification grouping tag. |
+| `renotify`           | `boolean?`                               | Re-alert when a matching `tag` replaces an existing notification. |
+| `requireInteraction` | `boolean?`                               | Keep the notification visible until the user dismisses it. |
+| `silent`             | `boolean?`                               | Suppress notification sound and vibration. |
+| `data`               | `Record<string, unknown>?`               | Custom data passed to the notification. |
+
+Unknown fields are preserved for forward compatibility, but the known
+fields above are validated by the builders when present.
+
+---
+
 ## Per-kind fields
 
 ### `ContentPush` — final user-facing content

package/dist/index.cjs

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var src_exports = {};
 __export(src_exports, {
+  AVATAR_URL_MAX_LENGTH: () => AVATAR_URL_MAX_LENGTH,
   MESSAGE_KIND: () => MESSAGE_KIND,
   MESSAGE_TYPE: () => MESSAGE_TYPE,
   PUSH_SOURCE: () => PUSH_SOURCE,
@@ -33,7 +34,12 @@ __export(src_exports, {
   isErrorPush: () => isErrorPush,
   isReasoningPush: () => isReasoningPush,
   isToolRequestPush: () => isToolRequestPush,
-  toUint8: () => toUint8
+  isValidUrl: () => isValidUrl,
+  normalizeVapidSubject: () => normalizeVapidSubject,
+  readReasoningContent: () => readReasoningContent,
+  stripReasoningTags: () => stripReasoningTags,
+  toUint8: () => toUint8,
+  validateAvatarUrl: () => validateAvatarUrl
 });
 module.exports = __toCommonJS(src_exports);
 var MESSAGE_KIND = Object.freeze({
@@ -159,7 +165,7 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
     }
   }
-  for (const f of ["renotify", "requireInteraction"]) {
+  for (const f of ["renotify", "requireInteraction", "silent"]) {
     if (n[f] !== void 0 && typeof n[f] !== "boolean") {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }
@@ -264,3 +270,66 @@ function concatBytes(...chunks) {
   }
   return out;
 }
+function isValidUrl(value) {
+  if (typeof value !== "string") return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var AVATAR_URL_MAX_LENGTH = 2048;
+function validateAvatarUrl(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "string") {
+    return "avatarUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32";
+  }
+  if (/^data:/i.test(value)) {
+    return "\u5934\u50CF\u4E0D\u652F\u6301\u4F20\u5165 data: URI\uFF0C\u8BF7\u6539\u4E3A\u516C\u7F51\u53EF\u8BBF\u95EE\u7684 https:// \u56FE\u7247 URL";
+  }
+  if (value.length > AVATAR_URL_MAX_LENGTH) {
+    return `\u5934\u50CF URL \u957F\u5EA6 ${value.length} \u5B57\u7B26\u8D85\u8FC7 ${AVATAR_URL_MAX_LENGTH} \u4E0A\u9650\uFF0C\u8BF7\u6539\u4E3A\u66F4\u77ED\u7684\u56FE\u7247 URL`;
+  }
+  if (!isValidUrl(value)) {
+    return "avatarUrl \u4E0D\u662F\u5408\u6CD5 URL";
+  }
+  return null;
+}
+function normalizeVapidSubject(email) {
+  const trimmed = String(email || "").trim();
+  if (!trimmed) return "";
+  return /^mailto:/i.test(trimmed) || /^https?:/i.test(trimmed) ? trimmed : `mailto:${trimmed}`;
+}
+var REASONING_TAG_RE = /<(think|thinking|thought)>([\s\S]*?)<\/\1>/i;
+var REASONING_TAG_RE_G = /<(think|thinking|thought)>[\s\S]*?<\/\1>/gi;
+function readReasoningContent(llmResponse) {
+  if (!llmResponse || typeof llmResponse !== "object") return null;
+  const choices = (
+    /** @type {{ choices?: unknown }} */
+    llmResponse.choices
+  );
+  if (!Array.isArray(choices) || choices.length === 0) return null;
+  const message = (
+    /** @type {{ message?: { reasoning_content?: unknown, content?: unknown } }} */
+    choices[0]?.message
+  );
+  const raw = message?.reasoning_content;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  const content = message?.content;
+  if (typeof content === "string") {
+    const match = content.match(REASONING_TAG_RE);
+    if (match) {
+      const trimmed = match[2].trim();
+      if (trimmed.length > 0) return trimmed;
+    }
+  }
+  return null;
+}
+function stripReasoningTags(content) {
+  if (typeof content !== "string" || !content.includes("<")) return content;
+  return content.replace(REASONING_TAG_RE_G, "").trim();
+}

package/dist/index.d.cts

@@ -200,10 +200,10 @@ export function isErrorPush(value: unknown): value is ErrorPush;
 /**
  * Slice a string into UTF-8 byte chunks no larger than `maxBytes`,
  * always cutting at codepoint boundaries (never inside a multi-byte
- * char). Designed for the {@link ReasoningPush} byte-chunking path
- * in amsg-instant — producers facing the ~3 KB Web Push payload
- * limit slice oversized reasoning into N pushes with
- * `chunkIndex` / `totalChunks`, the SW reassembles by concat.
+ * char). This is a generic byte-safe string helper retained for
+ * callers that need deterministic UTF-8 chunking around small Web Push
+ * payload budgets; current amsg-instant oversized payload delivery uses
+ * BlobStore / generic multipart instead of reasoning-only wire fields.
  *
  * Algorithm: TextEncoder → Uint8Array → backward scan from each
  * candidate cut index until the byte is a UTF-8 lead byte (any byte
@@ -247,6 +247,56 @@ export function base64UrlToBytes(input: string): Uint8Array;
  * @returns {Uint8Array}
  */
 export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
+/**
+ * True when `value` parses as an absolute URL.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isValidUrl(value: unknown): boolean;
+/**
+ * Validate the optional `avatarUrl` field. Rejects `data:` URIs (typically
+ * base64-encoded inline images) and anything longer than
+ * {@link AVATAR_URL_MAX_LENGTH} chars — both the dominant trigger for
+ * downstream 413 / Web Push 4 KB payload errors — plus anything that doesn't
+ * parse as a URL. Returns an error message string, or null when valid.
+ *
+ * Pure: callers decide how to act on a non-null result (amsg-server /
+ * amsg-instant / amsg-client soft-strip + console.warn; see standards §6.2).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function validateAvatarUrl(value: unknown): string | null;
+/**
+ * Normalize a VAPID `sub` (subject) claim. Web Push (RFC 8292) accepts a
+ * `mailto:` address or an `http(s):` URL; a bare contact like
+ * `you@example.com` is prefixed with `mailto:`. An already-prefixed
+ * `mailto:` / `http(s):` value is returned untouched. Empty / blank → `''`.
+ *
+ * @param {unknown} email
+ * @returns {string}
+ */
+export function normalizeVapidSubject(email: unknown): string;
+/**
+ * Read `choices[0].message.reasoning_content` as a non-empty trimmed string,
+ * or null when absent / empty. Falls back to the first `<think>` span inside
+ * `message.content` when a provider inlines reasoning there. Many providers
+ * return an empty string instead of omitting the field — treated the same as
+ * missing so callers don't emit an empty ReasoningPush.
+ *
+ * @param {unknown} llmResponse
+ * @returns {string | null}
+ */
+export function readReasoningContent(llmResponse: unknown): string | null;
+/**
+ * Drop any `<think>` / `<thinking>` / `<thought>` spans from a user-facing
+ * content string, so private chain-of-thought leaking through `message.content`
+ * does not also ship inside the ContentPush burst.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stripReasoningTags(content: string): string;
 /**
  * @rei-standard/amsg-shared
  *
@@ -316,6 +366,8 @@ export const PUSH_SOURCE: Readonly<{
     INSTANT: "instant";
     SCHEDULED: "scheduled";
 }>;
+/** Max accepted `avatarUrl` length, in characters. */
+export const AVATAR_URL_MAX_LENGTH: 2048;
 /**
  * Fields present on every push, regardless of kind. Discriminator
  * fields (`messageKind`) and kind-specific fields live on the kind
@@ -361,18 +413,21 @@ export type AmsgPushCommon = {
 };
 /**
  * SW-rendering directive. Mirrors the fields that `amsg-sw`'s
- * `createNotificationFromPayload` consumes (`notification.{title,body,icon,badge,tag,renotify,requireInteraction,data}`)
- * — typing all fields so callers don't lose IDE checking and slip back into the untyped-spread footgun.
+ * `createNotificationFromPayload` consumes (`notification.{show,title,body,icon,badge,tag,renotify,requireInteraction,silent,data}`)
+ * so producers get builder validation for the fields the SW actually reads.
  *
- * Routing in SW (kept here so producers don't have to cross-check):
+ * 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.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
- *   - When rendering, `notification.*` is consulted, with per-field fallback to
- *     the top-level `title` / `avatarUrl` / `messageId` and finally
- *     to the SW's `defaultIcon` / `defaultBadge` options. Everything
- *     else (`tag`, `renotify`, `requireInteraction`) has no top-level
- *     fallback — set them under `notification` or accept the SW default.
+ *   - When rendering, `notification.*` is consulted first, with per-field
+ *     fallback to the matching top-level payload fields (`title`,
+ *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
+ *     `renotify`, `requireInteraction`, `silent`, `data`), and finally to
+ *     the SW's `defaultIcon` / `defaultBadge` options (boolean knobs
+ *     default to `false` at the SW). Prefer setting overrides under
+ *     `notification` for explicitness; top-level fallback exists so that
+ *     legacy un-namespaced payloads keep working byte-for-byte.
  */
 export type NotificationDirective = {
     /**
@@ -380,35 +435,39 @@ export type NotificationDirective = {
      */
     show?: "auto" | "always" | "when-hidden" | false;
     /**
-     * - Notification title override.
+     * - Notification title override (falls back to top-level `title`, then `来自 {contactName}`).
      */
     title?: string;
     /**
-     * - Notification body override.
+     * - Notification body override (falls back to top-level `body`, then `message`).
      */
     body?: string;
     /**
-     * - Icon URL override (falls back to top-level `avatarUrl` then SW `defaultIcon`).
+     * - Icon URL override (falls back to top-level `icon`/`avatarUrl`, then SW `defaultIcon`).
      */
     icon?: string;
     /**
-     * - Badge URL override (falls back to SW `defaultBadge`).
+     * - Badge URL override (falls back to top-level `badge`, then SW `defaultBadge`).
      */
     badge?: string;
     /**
-     * - Notification grouping tag; matching tag replaces the prior notification.
+     * - Notification grouping tag; matching tag replaces the prior notification (falls back to top-level `tag`, then `messageId`, then a generated unique tag).
      */
     tag?: string;
     /**
-     * - When tag matches, still vibrate/sound. Default false at SW.
+     * - When tag matches, still vibrate/sound (falls back to top-level `renotify`, default false at SW).
      */
     renotify?: boolean;
     /**
-     * - Notification stays until user dismisses. Default false at SW.
+     * - Notification stays until user dismisses (falls back to top-level `requireInteraction`, default false at SW).
      */
     requireInteraction?: boolean;
     /**
-     * - Custom payload data to attach to the notification.
+     * - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+     */
+    silent?: boolean;
+    /**
+     * - Custom payload data to attach to the notification (falls back to top-level `data`).
      */
     data?: Record<string, unknown>;
 };
@@ -432,24 +491,24 @@ export type ContentPush = AmsgPushCommon & {
  * out of the upstream response into its own push. Emitted **before**
  * the matching {@link ContentPush} burst when present and non-empty.
  *
- * Reasoning carries two orthogonal "multi-part" axes, both optional —
- * they are *omitted* when the part count is 1 so the wire stays
- * byte-for-byte compatible with single-shot ReasoningPush callers:
+ * Reasoning carries two optional "multi-part" axes, both *omitted* when
+ * the part count is 1 so the wire stays byte-for-byte compatible with
+ * single-shot callers. The type reserves them for forward compatibility;
+ * current producers emit a single ReasoningPush and set neither — oversized
+ * reasoning rides the generic multipart transport, not a reasoning-only
+ * chunk format.
  *
- *   - `messageIndex` / `totalMessages` — set when a semantic
- *     splitter (`reasoningSplitPattern` in amsg-instant) has cut the
- *     reasoning into multiple sentences for typing-bubble UX.
+ *   - `messageIndex` / `totalMessages` — a 1-based part index when a producer
+ *     splits reasoning into multiple sentences for typing-bubble UX.
  *
- *   - `chunkIndex` / `totalChunks` — set when a single segment was
- *     too large for the Web Push payload limit and the producer had
- *     to slice it across multiple pushes at UTF-8 byte boundaries.
- *     Transport-only; SW reassembles the original `reasoningContent`
- *     by sorting on `chunkIndex` within a `(sessionId, messageIndex)`
- *     bucket. See `chunkReasoningByUtf8Bytes` for the safe-edge
- *     splitter helper.
+ *   - `chunkIndex` / `totalChunks` — transport-only slicing when a single
+ *     segment exceeds the Web Push payload limit; SW would reassemble the
+ *     original `reasoningContent` by sorting on `chunkIndex` within a
+ *     `(sessionId, messageIndex)` bucket. See `chunkReasoningByUtf8Bytes`
+ *     for the safe-edge splitter helper.
  *
- * Both axes can coexist on the same push when a sentence-split
- * segment is itself oversized.
+ * Both axes can coexist on the same push when a sentence-split segment is
+ * itself oversized.
  */
 export type ReasoningPush = AmsgPushCommon & {
     messageKind: "reasoning";

package/dist/index.d.ts

@@ -200,10 +200,10 @@ export function isErrorPush(value: unknown): value is ErrorPush;
 /**
  * Slice a string into UTF-8 byte chunks no larger than `maxBytes`,
  * always cutting at codepoint boundaries (never inside a multi-byte
- * char). Designed for the {@link ReasoningPush} byte-chunking path
- * in amsg-instant — producers facing the ~3 KB Web Push payload
- * limit slice oversized reasoning into N pushes with
- * `chunkIndex` / `totalChunks`, the SW reassembles by concat.
+ * char). This is a generic byte-safe string helper retained for
+ * callers that need deterministic UTF-8 chunking around small Web Push
+ * payload budgets; current amsg-instant oversized payload delivery uses
+ * BlobStore / generic multipart instead of reasoning-only wire fields.
  *
  * Algorithm: TextEncoder → Uint8Array → backward scan from each
  * candidate cut index until the byte is a UTF-8 lead byte (any byte
@@ -247,6 +247,56 @@ export function base64UrlToBytes(input: string): Uint8Array;
  * @returns {Uint8Array}
  */
 export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
+/**
+ * True when `value` parses as an absolute URL.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isValidUrl(value: unknown): boolean;
+/**
+ * Validate the optional `avatarUrl` field. Rejects `data:` URIs (typically
+ * base64-encoded inline images) and anything longer than
+ * {@link AVATAR_URL_MAX_LENGTH} chars — both the dominant trigger for
+ * downstream 413 / Web Push 4 KB payload errors — plus anything that doesn't
+ * parse as a URL. Returns an error message string, or null when valid.
+ *
+ * Pure: callers decide how to act on a non-null result (amsg-server /
+ * amsg-instant / amsg-client soft-strip + console.warn; see standards §6.2).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function validateAvatarUrl(value: unknown): string | null;
+/**
+ * Normalize a VAPID `sub` (subject) claim. Web Push (RFC 8292) accepts a
+ * `mailto:` address or an `http(s):` URL; a bare contact like
+ * `you@example.com` is prefixed with `mailto:`. An already-prefixed
+ * `mailto:` / `http(s):` value is returned untouched. Empty / blank → `''`.
+ *
+ * @param {unknown} email
+ * @returns {string}
+ */
+export function normalizeVapidSubject(email: unknown): string;
+/**
+ * Read `choices[0].message.reasoning_content` as a non-empty trimmed string,
+ * or null when absent / empty. Falls back to the first `<think>` span inside
+ * `message.content` when a provider inlines reasoning there. Many providers
+ * return an empty string instead of omitting the field — treated the same as
+ * missing so callers don't emit an empty ReasoningPush.
+ *
+ * @param {unknown} llmResponse
+ * @returns {string | null}
+ */
+export function readReasoningContent(llmResponse: unknown): string | null;
+/**
+ * Drop any `<think>` / `<thinking>` / `<thought>` spans from a user-facing
+ * content string, so private chain-of-thought leaking through `message.content`
+ * does not also ship inside the ContentPush burst.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stripReasoningTags(content: string): string;
 /**
  * @rei-standard/amsg-shared
  *
@@ -316,6 +366,8 @@ export const PUSH_SOURCE: Readonly<{
     INSTANT: "instant";
     SCHEDULED: "scheduled";
 }>;
+/** Max accepted `avatarUrl` length, in characters. */
+export const AVATAR_URL_MAX_LENGTH: 2048;
 /**
  * Fields present on every push, regardless of kind. Discriminator
  * fields (`messageKind`) and kind-specific fields live on the kind
@@ -361,18 +413,21 @@ export type AmsgPushCommon = {
 };
 /**
  * SW-rendering directive. Mirrors the fields that `amsg-sw`'s
- * `createNotificationFromPayload` consumes (`notification.{title,body,icon,badge,tag,renotify,requireInteraction,data}`)
- * — typing all fields so callers don't lose IDE checking and slip back into the untyped-spread footgun.
+ * `createNotificationFromPayload` consumes (`notification.{show,title,body,icon,badge,tag,renotify,requireInteraction,silent,data}`)
+ * so producers get builder validation for the fields the SW actually reads.
  *
- * Routing in SW (kept here so producers don't have to cross-check):
+ * 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.
  *   - `show: "always"`, `"when-hidden"`, or `false` overrides this default.
- *   - When rendering, `notification.*` is consulted, with per-field fallback to
- *     the top-level `title` / `avatarUrl` / `messageId` and finally
- *     to the SW's `defaultIcon` / `defaultBadge` options. Everything
- *     else (`tag`, `renotify`, `requireInteraction`) has no top-level
- *     fallback — set them under `notification` or accept the SW default.
+ *   - When rendering, `notification.*` is consulted first, with per-field
+ *     fallback to the matching top-level payload fields (`title`,
+ *     `body`/`message`, `icon`/`avatarUrl`, `badge`, `tag`/`messageId`,
+ *     `renotify`, `requireInteraction`, `silent`, `data`), and finally to
+ *     the SW's `defaultIcon` / `defaultBadge` options (boolean knobs
+ *     default to `false` at the SW). Prefer setting overrides under
+ *     `notification` for explicitness; top-level fallback exists so that
+ *     legacy un-namespaced payloads keep working byte-for-byte.
  */
 export type NotificationDirective = {
     /**
@@ -380,35 +435,39 @@ export type NotificationDirective = {
      */
     show?: "auto" | "always" | "when-hidden" | false;
     /**
-     * - Notification title override.
+     * - Notification title override (falls back to top-level `title`, then `来自 {contactName}`).
      */
     title?: string;
     /**
-     * - Notification body override.
+     * - Notification body override (falls back to top-level `body`, then `message`).
      */
     body?: string;
     /**
-     * - Icon URL override (falls back to top-level `avatarUrl` then SW `defaultIcon`).
+     * - Icon URL override (falls back to top-level `icon`/`avatarUrl`, then SW `defaultIcon`).
      */
     icon?: string;
     /**
-     * - Badge URL override (falls back to SW `defaultBadge`).
+     * - Badge URL override (falls back to top-level `badge`, then SW `defaultBadge`).
      */
     badge?: string;
     /**
-     * - Notification grouping tag; matching tag replaces the prior notification.
+     * - Notification grouping tag; matching tag replaces the prior notification (falls back to top-level `tag`, then `messageId`, then a generated unique tag).
      */
     tag?: string;
     /**
-     * - When tag matches, still vibrate/sound. Default false at SW.
+     * - When tag matches, still vibrate/sound (falls back to top-level `renotify`, default false at SW).
      */
     renotify?: boolean;
     /**
-     * - Notification stays until user dismisses. Default false at SW.
+     * - Notification stays until user dismisses (falls back to top-level `requireInteraction`, default false at SW).
      */
     requireInteraction?: boolean;
     /**
-     * - Custom payload data to attach to the notification.
+     * - Suppress sound and vibration (falls back to top-level `silent`, default false at SW).
+     */
+    silent?: boolean;
+    /**
+     * - Custom payload data to attach to the notification (falls back to top-level `data`).
      */
     data?: Record<string, unknown>;
 };
@@ -432,24 +491,24 @@ export type ContentPush = AmsgPushCommon & {
  * out of the upstream response into its own push. Emitted **before**
  * the matching {@link ContentPush} burst when present and non-empty.
  *
- * Reasoning carries two orthogonal "multi-part" axes, both optional —
- * they are *omitted* when the part count is 1 so the wire stays
- * byte-for-byte compatible with single-shot ReasoningPush callers:
+ * Reasoning carries two optional "multi-part" axes, both *omitted* when
+ * the part count is 1 so the wire stays byte-for-byte compatible with
+ * single-shot callers. The type reserves them for forward compatibility;
+ * current producers emit a single ReasoningPush and set neither — oversized
+ * reasoning rides the generic multipart transport, not a reasoning-only
+ * chunk format.
  *
- *   - `messageIndex` / `totalMessages` — set when a semantic
- *     splitter (`reasoningSplitPattern` in amsg-instant) has cut the
- *     reasoning into multiple sentences for typing-bubble UX.
+ *   - `messageIndex` / `totalMessages` — a 1-based part index when a producer
+ *     splits reasoning into multiple sentences for typing-bubble UX.
  *
- *   - `chunkIndex` / `totalChunks` — set when a single segment was
- *     too large for the Web Push payload limit and the producer had
- *     to slice it across multiple pushes at UTF-8 byte boundaries.
- *     Transport-only; SW reassembles the original `reasoningContent`
- *     by sorting on `chunkIndex` within a `(sessionId, messageIndex)`
- *     bucket. See `chunkReasoningByUtf8Bytes` for the safe-edge
- *     splitter helper.
+ *   - `chunkIndex` / `totalChunks` — transport-only slicing when a single
+ *     segment exceeds the Web Push payload limit; SW would reassemble the
+ *     original `reasoningContent` by sorting on `chunkIndex` within a
+ *     `(sessionId, messageIndex)` bucket. See `chunkReasoningByUtf8Bytes`
+ *     for the safe-edge splitter helper.
  *
- * Both axes can coexist on the same push when a sentence-split
- * segment is itself oversized.
+ * Both axes can coexist on the same push when a sentence-split segment is
+ * itself oversized.
  */
 export type ReasoningPush = AmsgPushCommon & {
     messageKind: "reasoning";

package/dist/index.mjs

@@ -122,7 +122,7 @@ function validateNotificationArg(kind, value) {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
     }
   }
-  for (const f of ["renotify", "requireInteraction"]) {
+  for (const f of ["renotify", "requireInteraction", "silent"]) {
     if (n[f] !== void 0 && typeof n[f] !== "boolean") {
       throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
     }
@@ -227,7 +227,71 @@ function concatBytes(...chunks) {
   }
   return out;
 }
+function isValidUrl(value) {
+  if (typeof value !== "string") return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var AVATAR_URL_MAX_LENGTH = 2048;
+function validateAvatarUrl(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "string") {
+    return "avatarUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32";
+  }
+  if (/^data:/i.test(value)) {
+    return "\u5934\u50CF\u4E0D\u652F\u6301\u4F20\u5165 data: URI\uFF0C\u8BF7\u6539\u4E3A\u516C\u7F51\u53EF\u8BBF\u95EE\u7684 https:// \u56FE\u7247 URL";
+  }
+  if (value.length > AVATAR_URL_MAX_LENGTH) {
+    return `\u5934\u50CF URL \u957F\u5EA6 ${value.length} \u5B57\u7B26\u8D85\u8FC7 ${AVATAR_URL_MAX_LENGTH} \u4E0A\u9650\uFF0C\u8BF7\u6539\u4E3A\u66F4\u77ED\u7684\u56FE\u7247 URL`;
+  }
+  if (!isValidUrl(value)) {
+    return "avatarUrl \u4E0D\u662F\u5408\u6CD5 URL";
+  }
+  return null;
+}
+function normalizeVapidSubject(email) {
+  const trimmed = String(email || "").trim();
+  if (!trimmed) return "";
+  return /^mailto:/i.test(trimmed) || /^https?:/i.test(trimmed) ? trimmed : `mailto:${trimmed}`;
+}
+var REASONING_TAG_RE = /<(think|thinking|thought)>([\s\S]*?)<\/\1>/i;
+var REASONING_TAG_RE_G = /<(think|thinking|thought)>[\s\S]*?<\/\1>/gi;
+function readReasoningContent(llmResponse) {
+  if (!llmResponse || typeof llmResponse !== "object") return null;
+  const choices = (
+    /** @type {{ choices?: unknown }} */
+    llmResponse.choices
+  );
+  if (!Array.isArray(choices) || choices.length === 0) return null;
+  const message = (
+    /** @type {{ message?: { reasoning_content?: unknown, content?: unknown } }} */
+    choices[0]?.message
+  );
+  const raw = message?.reasoning_content;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  const content = message?.content;
+  if (typeof content === "string") {
+    const match = content.match(REASONING_TAG_RE);
+    if (match) {
+      const trimmed = match[2].trim();
+      if (trimmed.length > 0) return trimmed;
+    }
+  }
+  return null;
+}
+function stripReasoningTags(content) {
+  if (typeof content !== "string" || !content.includes("<")) return content;
+  return content.replace(REASONING_TAG_RE_G, "").trim();
+}
 export {
+  AVATAR_URL_MAX_LENGTH,
   MESSAGE_KIND,
   MESSAGE_TYPE,
   PUSH_SOURCE,
@@ -242,5 +306,10 @@ export {
   isErrorPush,
   isReasoningPush,
   isToolRequestPush,
-  toUint8
+  isValidUrl,
+  normalizeVapidSubject,
+  readReasoningContent,
+  stripReasoningTags,
+  toUint8,
+  validateAvatarUrl
 };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@rei-standard/amsg-shared",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "ReiStandard Active Messaging shared types and push builders — the lowest layer (no deps on other amsg packages)",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Tosd0/ReiStandard",
+    "url": "git+https://github.com/Tosd0/ReiStandard.git",
     "directory": "packages/rei-standard-amsg/shared"
   },
   "license": "MIT",