@rei-standard/amsg-shared 0.1.0-next.0 → 0.1.0-next.3

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(src_exports, {
   buildErrorPush: () => buildErrorPush,
   buildReasoningPush: () => buildReasoningPush,
   buildToolRequestPush: () => buildToolRequestPush,
+  chunkReasoningByUtf8Bytes: () => chunkReasoningByUtf8Bytes,
   isContentPush: () => isContentPush,
   isErrorPush: () => isErrorPush,
   isReasoningPush: () => isReasoningPush,
@@ -61,6 +62,7 @@ function buildContentPush(args) {
   if (typeof args.message !== "string") {
     throw new Error("[amsg-shared] ContentPush: 'message' must be a string");
   }
+  validateNotificationArg("ContentPush", args.notification);
   const push = {
     messageKind: "content",
     messageType: args.messageType,
@@ -78,6 +80,7 @@ function buildContentPush(args) {
   if (args.totalMessages !== void 0) push.totalMessages = args.totalMessages;
   if (args.taskId !== void 0) push.taskId = args.taskId;
   if (args.metadata !== void 0) push.metadata = args.metadata;
+  if (args.notification !== void 0) push.notification = args.notification;
   return push;
 }
 function buildReasoningPush(args) {
@@ -101,6 +104,10 @@ function buildReasoningPush(args) {
   if (args.contactName !== void 0) push.contactName = args.contactName;
   if (args.avatarUrl !== void 0) push.avatarUrl = args.avatarUrl;
   if (args.messageSubtype !== void 0) push.messageSubtype = args.messageSubtype;
+  if (args.messageIndex !== void 0) push.messageIndex = args.messageIndex;
+  if (args.totalMessages !== void 0) push.totalMessages = args.totalMessages;
+  if (args.chunkIndex !== void 0) push.chunkIndex = args.chunkIndex;
+  if (args.totalChunks !== void 0) push.totalChunks = args.totalChunks;
   if (args.metadata !== void 0) push.metadata = args.metadata;
   return push;
 }
@@ -112,6 +119,7 @@ function buildToolRequestPush(args) {
   if (!Array.isArray(args.toolCalls) || args.toolCalls.length === 0) {
     throw new Error("[amsg-shared] ToolRequestPush: 'toolCalls' must be a non-empty array");
   }
+  validateNotificationArg("ToolRequestPush", args.notification);
   const push = {
     messageKind: "tool_request",
     messageType: args.messageType,
@@ -126,8 +134,29 @@ function buildToolRequestPush(args) {
   if (args.message !== void 0) push.message = args.message;
   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;
   return push;
 }
+function validateNotificationArg(kind, value) {
+  if (value === void 0) return;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`[amsg-shared] ${kind}: 'notification' must be a plain object`);
+  }
+  const n = (
+    /** @type {Record<string, unknown>} */
+    value
+  );
+  for (const f of ["title", "body", "icon", "badge", "tag"]) {
+    if (n[f] !== void 0 && typeof n[f] !== "string") {
+      throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
+    }
+  }
+  for (const f of ["renotify", "requireInteraction"]) {
+    if (n[f] !== void 0 && typeof n[f] !== "boolean") {
+      throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
+    }
+  }
+}
 function buildErrorPush(args) {
   requireField("ErrorPush", "messageType", args.messageType);
   requireField("ErrorPush", "source", args.source);
@@ -168,3 +197,31 @@ function isErrorPush(value) {
   return !!value && typeof value === "object" && /** @type {{messageKind?: unknown}} */
   value.messageKind === "error";
 }
+var REASONING_CHUNK_ENCODER = new TextEncoder();
+var REASONING_CHUNK_DECODER = new TextDecoder("utf-8", { fatal: true });
+function chunkReasoningByUtf8Bytes(text, maxBytes) {
+  if (typeof text !== "string") {
+    throw new TypeError("[amsg-shared] chunkReasoningByUtf8Bytes: text must be a string");
+  }
+  if (!Number.isInteger(maxBytes) || maxBytes < 4) {
+    throw new RangeError(
+      "[amsg-shared] chunkReasoningByUtf8Bytes: maxBytes must be an integer \u2265 4 (UTF-8 max codepoint width)"
+    );
+  }
+  if (text.length === 0) return [];
+  const bytes = REASONING_CHUNK_ENCODER.encode(text);
+  if (bytes.byteLength <= maxBytes) return [text];
+  const chunks = [];
+  let start = 0;
+  while (start < bytes.byteLength) {
+    let end = Math.min(start + maxBytes, bytes.byteLength);
+    if (end < bytes.byteLength) {
+      while (end > start && (bytes[end] & 192) === 128) {
+        end--;
+      }
+    }
+    chunks.push(REASONING_CHUNK_DECODER.decode(bytes.subarray(start, end)));
+    start = end;
+  }
+  return chunks;
+}

package/dist/index.d.cts

@@ -18,6 +18,12 @@
  * @param {number}      [args.totalMessages]
  * @param {string | null} [args.taskId]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
+ *                       - SW-side `showNotification` overrides for content
+ *                         (and for ToolRequestPush prefix chunks that get
+ *                         demoted to `content` during sentence-split). All
+ *                         fields optional; see {@link NotificationDirective}
+ *                         for the SW fallback chain.
  * @returns {ContentPush}
  */
 export function buildContentPush(args: {
@@ -35,14 +41,23 @@ export function buildContentPush(args: {
     totalMessages?: number;
     taskId?: string | null;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ContentPush;
 /**
  * Build a {@link ReasoningPush}. Producers emit this **before** any
  * matching `ContentPush` burst when the LLM response carried a non-
  * empty `reasoning_content`.
  *
- * Does NOT take `messageIndex` / `totalMessages` — reasoning is one
- * push per LLM round.
+ * Two optional multi-part axes (both omitted from wire when the part
+ * count is 1, so single-shot reasoning stays byte-for-byte compatible):
+ *
+ *   - `messageIndex` / `totalMessages` — semantic splitter (sentence
+ *     regex) produced multiple segments.
+ *   - `chunkIndex` / `totalChunks` — byte splitter (UTF-8 payload-limit
+ *     workaround) sliced a single segment across multiple pushes.
+ *
+ * Both can be set together when a sentence-split segment is itself
+ * oversized. See README §"Reasoning chunking".
  *
  * @param {Object} args
  * @param {MessageType} args.messageType
@@ -55,6 +70,10 @@ export function buildContentPush(args: {
  * @param {string}      [args.contactName]
  * @param {string | null} [args.avatarUrl]
  * @param {string}      [args.messageSubtype]
+ * @param {number}      [args.messageIndex]
+ * @param {number}      [args.totalMessages]
+ * @param {number}      [args.chunkIndex]
+ * @param {number}      [args.totalChunks]
  * @param {Object}      [args.metadata]
  * @returns {ReasoningPush}
  */
@@ -69,6 +88,10 @@ export function buildReasoningPush(args: {
     contactName?: string;
     avatarUrl?: string | null;
     messageSubtype?: string;
+    messageIndex?: number;
+    totalMessages?: number;
+    chunkIndex?: number;
+    totalChunks?: number;
     metadata?: any;
 }): ReasoningPush;
 /**
@@ -88,6 +111,15 @@ export function buildReasoningPush(args: {
  * @param {string}      [args.message]
  * @param {string}      [args.messageSubtype]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
+ *                       - SW notification overrides. Used after the
+ *                         splitter demotes prefix chunks to `content`
+ *                         (where `messageKind: 'content'` triggers
+ *                         `showNotification`). On the un-demoted last
+ *                         chunk (`messageKind: 'tool_request'`) the
+ *                         SW dispatches silently and the field is
+ *                         ignored — typed here purely so the demoted
+ *                         chunks inherit it via the splitter's spread.
  * @returns {ToolRequestPush}
  */
 export function buildToolRequestPush(args: {
@@ -102,6 +134,7 @@ export function buildToolRequestPush(args: {
     message?: string;
     messageSubtype?: string;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ToolRequestPush;
 /**
  * Build an {@link ErrorPush}. Replaces the legacy
@@ -162,6 +195,40 @@ export function isToolRequestPush(value: unknown): value is ToolRequestPush;
  * @returns {value is ErrorPush}
  */
 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.
+ *
+ * Algorithm: TextEncoder → Uint8Array → backward scan from each
+ * candidate cut index until the byte is a UTF-8 lead byte (any byte
+ * where `(b & 0xC0) !== 0x80`; continuation bytes are `0b10xxxxxx`).
+ * TextDecoder turns each slice back into a JS string.
+ *
+ *   chunkReasoningByUtf8Bytes('A寿B', 4) → ['A寿', 'B']  // '寿' = 3 B,
+ *                                                       // cut at safe edge
+ *
+ * Constraints:
+ *   - `maxBytes` MUST be ≥ 4 (UTF-8 codepoints can be up to 4 bytes;
+ *     any smaller threshold has no valid cut point for a 4-byte char
+ *     and is also operationally nonsensical). Throws `RangeError`
+ *     otherwise.
+ *   - Empty `text` → `[]` (caller can check `.length === 0`).
+ *   - `text` whose total UTF-8 byte length ≤ `maxBytes` → `[text]`
+ *     (no chunking).
+ *   - `text` MUST be a string. Non-string throws `TypeError`.
+ *
+ * Joining the result `chunks.join('')` is guaranteed to equal the
+ * input `text` (no data loss, no extra whitespace).
+ *
+ * @param {string} text
+ * @param {number} maxBytes
+ * @returns {string[]}
+ */
+export function chunkReasoningByUtf8Bytes(text: string, maxBytes: number): string[];
 /**
  * @rei-standard/amsg-shared
  *
@@ -270,6 +337,58 @@ export type AmsgPushCommon = {
      */
     metadata?: any;
 };
+/**
+ * SW-rendering directive carried on `ContentPush` / `ToolRequestPush`.
+ * Mirrors the seven fields that `amsg-sw`'s `createNotificationFromPayload`
+ * actually consumes (`notification.{title,body,icon,badge,tag,renotify,requireInteraction}`)
+ * — typing all seven (rather than just `title` / `body`) so callers
+ * don't lose IDE checking on the other five and slip back into the
+ * untyped-spread footgun this typedef was added to close.
+ *
+ * Routing in SW (kept here so producers don't have to cross-check):
+ *   - `messageKind: 'content'` (and legacy un-kinded payloads) →
+ *     `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 (`messageId`-derived tag, no renotify, no requireInteraction).
+ *   - `messageKind: 'reasoning'` / `'tool_request'` / `'error'` →
+ *     dispatched silently to controlled clients. `notification` is
+ *     ignored. (It's still typed on `ToolRequestPush` because the
+ *     splitter demotes prefix chunks to `messageKind: 'content'`, at
+ *     which point the field starts mattering.)
+ */
+export type NotificationDirective = {
+    /**
+     * - Notification title override.
+     */
+    title?: string;
+    /**
+     * - Notification body override.
+     */
+    body?: string;
+    /**
+     * - Icon URL override (falls back to top-level `avatarUrl` then SW `defaultIcon`).
+     */
+    icon?: string;
+    /**
+     * - Badge URL override (falls back to SW `defaultBadge`).
+     */
+    badge?: string;
+    /**
+     * - Notification grouping tag; matching tag replaces the prior notification.
+     */
+    tag?: string;
+    /**
+     * - When tag matches, still vibrate/sound. Default false at SW.
+     */
+    renotify?: boolean;
+    /**
+     * - Notification stays until user dismisses. Default false at SW.
+     */
+    requireInteraction?: boolean;
+};
 /**
  * Final user-facing content. Sentence-split bursts of N use
  * `messageIndex` (1-based) + `totalMessages` so the client can
@@ -284,16 +403,31 @@ export type ContentPush = AmsgPushCommon & {
     messageIndex?: number;
     totalMessages?: number;
     taskId?: string | null;
+    notification?: NotificationDirective;
 };
 /**
  * LLM "meta-thinking" — `choices[0].message.reasoning_content` lifted
  * out of the upstream response into its own push. Emitted **before**
  * the matching {@link ContentPush} burst when present and non-empty.
  *
- * Intentionally does NOT carry `messageIndex` / `totalMessages` —
- * reasoning is a single push per LLM round, never a split-burst.
- * That's why those fields are absent at the type level rather than
- * `optional` (which would leave callers wondering when they're set).
+ * 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:
+ *
+ *   - `messageIndex` / `totalMessages` — set when a semantic
+ *     splitter (`reasoningSplitPattern` in amsg-instant) has cut the
+ *     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.
+ *
+ * Both axes can coexist on the same push when a sentence-split
+ * segment is itself oversized.
  */
 export type ReasoningPush = AmsgPushCommon & {
     messageKind: "reasoning";
@@ -301,6 +435,10 @@ export type ReasoningPush = AmsgPushCommon & {
     title?: string;
     contactName?: string;
     avatarUrl?: string | null;
+    messageIndex?: number;
+    totalMessages?: number;
+    chunkIndex?: number;
+    totalChunks?: number;
 };
 /**
  * Tool invocation request emitted by an agentic-loop hook (`decision:
@@ -317,6 +455,7 @@ export type ToolRequestPush = AmsgPushCommon & {
     title?: string;
     contactName?: string;
     message?: string;
+    notification?: NotificationDirective;
 };
 /**
  * Producer-level error. Replaces the legacy

package/dist/index.d.ts

@@ -18,6 +18,12 @@
  * @param {number}      [args.totalMessages]
  * @param {string | null} [args.taskId]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
+ *                       - SW-side `showNotification` overrides for content
+ *                         (and for ToolRequestPush prefix chunks that get
+ *                         demoted to `content` during sentence-split). All
+ *                         fields optional; see {@link NotificationDirective}
+ *                         for the SW fallback chain.
  * @returns {ContentPush}
  */
 export function buildContentPush(args: {
@@ -35,14 +41,23 @@ export function buildContentPush(args: {
     totalMessages?: number;
     taskId?: string | null;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ContentPush;
 /**
  * Build a {@link ReasoningPush}. Producers emit this **before** any
  * matching `ContentPush` burst when the LLM response carried a non-
  * empty `reasoning_content`.
  *
- * Does NOT take `messageIndex` / `totalMessages` — reasoning is one
- * push per LLM round.
+ * Two optional multi-part axes (both omitted from wire when the part
+ * count is 1, so single-shot reasoning stays byte-for-byte compatible):
+ *
+ *   - `messageIndex` / `totalMessages` — semantic splitter (sentence
+ *     regex) produced multiple segments.
+ *   - `chunkIndex` / `totalChunks` — byte splitter (UTF-8 payload-limit
+ *     workaround) sliced a single segment across multiple pushes.
+ *
+ * Both can be set together when a sentence-split segment is itself
+ * oversized. See README §"Reasoning chunking".
  *
  * @param {Object} args
  * @param {MessageType} args.messageType
@@ -55,6 +70,10 @@ export function buildContentPush(args: {
  * @param {string}      [args.contactName]
  * @param {string | null} [args.avatarUrl]
  * @param {string}      [args.messageSubtype]
+ * @param {number}      [args.messageIndex]
+ * @param {number}      [args.totalMessages]
+ * @param {number}      [args.chunkIndex]
+ * @param {number}      [args.totalChunks]
  * @param {Object}      [args.metadata]
  * @returns {ReasoningPush}
  */
@@ -69,6 +88,10 @@ export function buildReasoningPush(args: {
     contactName?: string;
     avatarUrl?: string | null;
     messageSubtype?: string;
+    messageIndex?: number;
+    totalMessages?: number;
+    chunkIndex?: number;
+    totalChunks?: number;
     metadata?: any;
 }): ReasoningPush;
 /**
@@ -88,6 +111,15 @@ export function buildReasoningPush(args: {
  * @param {string}      [args.message]
  * @param {string}      [args.messageSubtype]
  * @param {Object}      [args.metadata]
+ * @param {NotificationDirective} [args.notification]
+ *                       - SW notification overrides. Used after the
+ *                         splitter demotes prefix chunks to `content`
+ *                         (where `messageKind: 'content'` triggers
+ *                         `showNotification`). On the un-demoted last
+ *                         chunk (`messageKind: 'tool_request'`) the
+ *                         SW dispatches silently and the field is
+ *                         ignored — typed here purely so the demoted
+ *                         chunks inherit it via the splitter's spread.
  * @returns {ToolRequestPush}
  */
 export function buildToolRequestPush(args: {
@@ -102,6 +134,7 @@ export function buildToolRequestPush(args: {
     message?: string;
     messageSubtype?: string;
     metadata?: any;
+    notification?: NotificationDirective;
 }): ToolRequestPush;
 /**
  * Build an {@link ErrorPush}. Replaces the legacy
@@ -162,6 +195,40 @@ export function isToolRequestPush(value: unknown): value is ToolRequestPush;
  * @returns {value is ErrorPush}
  */
 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.
+ *
+ * Algorithm: TextEncoder → Uint8Array → backward scan from each
+ * candidate cut index until the byte is a UTF-8 lead byte (any byte
+ * where `(b & 0xC0) !== 0x80`; continuation bytes are `0b10xxxxxx`).
+ * TextDecoder turns each slice back into a JS string.
+ *
+ *   chunkReasoningByUtf8Bytes('A寿B', 4) → ['A寿', 'B']  // '寿' = 3 B,
+ *                                                       // cut at safe edge
+ *
+ * Constraints:
+ *   - `maxBytes` MUST be ≥ 4 (UTF-8 codepoints can be up to 4 bytes;
+ *     any smaller threshold has no valid cut point for a 4-byte char
+ *     and is also operationally nonsensical). Throws `RangeError`
+ *     otherwise.
+ *   - Empty `text` → `[]` (caller can check `.length === 0`).
+ *   - `text` whose total UTF-8 byte length ≤ `maxBytes` → `[text]`
+ *     (no chunking).
+ *   - `text` MUST be a string. Non-string throws `TypeError`.
+ *
+ * Joining the result `chunks.join('')` is guaranteed to equal the
+ * input `text` (no data loss, no extra whitespace).
+ *
+ * @param {string} text
+ * @param {number} maxBytes
+ * @returns {string[]}
+ */
+export function chunkReasoningByUtf8Bytes(text: string, maxBytes: number): string[];
 /**
  * @rei-standard/amsg-shared
  *
@@ -270,6 +337,58 @@ export type AmsgPushCommon = {
      */
     metadata?: any;
 };
+/**
+ * SW-rendering directive carried on `ContentPush` / `ToolRequestPush`.
+ * Mirrors the seven fields that `amsg-sw`'s `createNotificationFromPayload`
+ * actually consumes (`notification.{title,body,icon,badge,tag,renotify,requireInteraction}`)
+ * — typing all seven (rather than just `title` / `body`) so callers
+ * don't lose IDE checking on the other five and slip back into the
+ * untyped-spread footgun this typedef was added to close.
+ *
+ * Routing in SW (kept here so producers don't have to cross-check):
+ *   - `messageKind: 'content'` (and legacy un-kinded payloads) →
+ *     `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 (`messageId`-derived tag, no renotify, no requireInteraction).
+ *   - `messageKind: 'reasoning'` / `'tool_request'` / `'error'` →
+ *     dispatched silently to controlled clients. `notification` is
+ *     ignored. (It's still typed on `ToolRequestPush` because the
+ *     splitter demotes prefix chunks to `messageKind: 'content'`, at
+ *     which point the field starts mattering.)
+ */
+export type NotificationDirective = {
+    /**
+     * - Notification title override.
+     */
+    title?: string;
+    /**
+     * - Notification body override.
+     */
+    body?: string;
+    /**
+     * - Icon URL override (falls back to top-level `avatarUrl` then SW `defaultIcon`).
+     */
+    icon?: string;
+    /**
+     * - Badge URL override (falls back to SW `defaultBadge`).
+     */
+    badge?: string;
+    /**
+     * - Notification grouping tag; matching tag replaces the prior notification.
+     */
+    tag?: string;
+    /**
+     * - When tag matches, still vibrate/sound. Default false at SW.
+     */
+    renotify?: boolean;
+    /**
+     * - Notification stays until user dismisses. Default false at SW.
+     */
+    requireInteraction?: boolean;
+};
 /**
  * Final user-facing content. Sentence-split bursts of N use
  * `messageIndex` (1-based) + `totalMessages` so the client can
@@ -284,16 +403,31 @@ export type ContentPush = AmsgPushCommon & {
     messageIndex?: number;
     totalMessages?: number;
     taskId?: string | null;
+    notification?: NotificationDirective;
 };
 /**
  * LLM "meta-thinking" — `choices[0].message.reasoning_content` lifted
  * out of the upstream response into its own push. Emitted **before**
  * the matching {@link ContentPush} burst when present and non-empty.
  *
- * Intentionally does NOT carry `messageIndex` / `totalMessages` —
- * reasoning is a single push per LLM round, never a split-burst.
- * That's why those fields are absent at the type level rather than
- * `optional` (which would leave callers wondering when they're set).
+ * 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:
+ *
+ *   - `messageIndex` / `totalMessages` — set when a semantic
+ *     splitter (`reasoningSplitPattern` in amsg-instant) has cut the
+ *     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.
+ *
+ * Both axes can coexist on the same push when a sentence-split
+ * segment is itself oversized.
  */
 export type ReasoningPush = AmsgPushCommon & {
     messageKind: "reasoning";
@@ -301,6 +435,10 @@ export type ReasoningPush = AmsgPushCommon & {
     title?: string;
     contactName?: string;
     avatarUrl?: string | null;
+    messageIndex?: number;
+    totalMessages?: number;
+    chunkIndex?: number;
+    totalChunks?: number;
 };
 /**
  * Tool invocation request emitted by an agentic-loop hook (`decision:
@@ -317,6 +455,7 @@ export type ToolRequestPush = AmsgPushCommon & {
     title?: string;
     contactName?: string;
     message?: string;
+    notification?: NotificationDirective;
 };
 /**
  * Producer-level error. Replaces the legacy

package/dist/index.mjs

@@ -28,6 +28,7 @@ function buildContentPush(args) {
   if (typeof args.message !== "string") {
     throw new Error("[amsg-shared] ContentPush: 'message' must be a string");
   }
+  validateNotificationArg("ContentPush", args.notification);
   const push = {
     messageKind: "content",
     messageType: args.messageType,
@@ -45,6 +46,7 @@ function buildContentPush(args) {
   if (args.totalMessages !== void 0) push.totalMessages = args.totalMessages;
   if (args.taskId !== void 0) push.taskId = args.taskId;
   if (args.metadata !== void 0) push.metadata = args.metadata;
+  if (args.notification !== void 0) push.notification = args.notification;
   return push;
 }
 function buildReasoningPush(args) {
@@ -68,6 +70,10 @@ function buildReasoningPush(args) {
   if (args.contactName !== void 0) push.contactName = args.contactName;
   if (args.avatarUrl !== void 0) push.avatarUrl = args.avatarUrl;
   if (args.messageSubtype !== void 0) push.messageSubtype = args.messageSubtype;
+  if (args.messageIndex !== void 0) push.messageIndex = args.messageIndex;
+  if (args.totalMessages !== void 0) push.totalMessages = args.totalMessages;
+  if (args.chunkIndex !== void 0) push.chunkIndex = args.chunkIndex;
+  if (args.totalChunks !== void 0) push.totalChunks = args.totalChunks;
   if (args.metadata !== void 0) push.metadata = args.metadata;
   return push;
 }
@@ -79,6 +85,7 @@ function buildToolRequestPush(args) {
   if (!Array.isArray(args.toolCalls) || args.toolCalls.length === 0) {
     throw new Error("[amsg-shared] ToolRequestPush: 'toolCalls' must be a non-empty array");
   }
+  validateNotificationArg("ToolRequestPush", args.notification);
   const push = {
     messageKind: "tool_request",
     messageType: args.messageType,
@@ -93,8 +100,29 @@ function buildToolRequestPush(args) {
   if (args.message !== void 0) push.message = args.message;
   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;
   return push;
 }
+function validateNotificationArg(kind, value) {
+  if (value === void 0) return;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`[amsg-shared] ${kind}: 'notification' must be a plain object`);
+  }
+  const n = (
+    /** @type {Record<string, unknown>} */
+    value
+  );
+  for (const f of ["title", "body", "icon", "badge", "tag"]) {
+    if (n[f] !== void 0 && typeof n[f] !== "string") {
+      throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a string when present`);
+    }
+  }
+  for (const f of ["renotify", "requireInteraction"]) {
+    if (n[f] !== void 0 && typeof n[f] !== "boolean") {
+      throw new Error(`[amsg-shared] ${kind}: 'notification.${f}' must be a boolean when present`);
+    }
+  }
+}
 function buildErrorPush(args) {
   requireField("ErrorPush", "messageType", args.messageType);
   requireField("ErrorPush", "source", args.source);
@@ -135,6 +163,34 @@ function isErrorPush(value) {
   return !!value && typeof value === "object" && /** @type {{messageKind?: unknown}} */
   value.messageKind === "error";
 }
+var REASONING_CHUNK_ENCODER = new TextEncoder();
+var REASONING_CHUNK_DECODER = new TextDecoder("utf-8", { fatal: true });
+function chunkReasoningByUtf8Bytes(text, maxBytes) {
+  if (typeof text !== "string") {
+    throw new TypeError("[amsg-shared] chunkReasoningByUtf8Bytes: text must be a string");
+  }
+  if (!Number.isInteger(maxBytes) || maxBytes < 4) {
+    throw new RangeError(
+      "[amsg-shared] chunkReasoningByUtf8Bytes: maxBytes must be an integer \u2265 4 (UTF-8 max codepoint width)"
+    );
+  }
+  if (text.length === 0) return [];
+  const bytes = REASONING_CHUNK_ENCODER.encode(text);
+  if (bytes.byteLength <= maxBytes) return [text];
+  const chunks = [];
+  let start = 0;
+  while (start < bytes.byteLength) {
+    let end = Math.min(start + maxBytes, bytes.byteLength);
+    if (end < bytes.byteLength) {
+      while (end > start && (bytes[end] & 192) === 128) {
+        end--;
+      }
+    }
+    chunks.push(REASONING_CHUNK_DECODER.decode(bytes.subarray(start, end)));
+    start = end;
+  }
+  return chunks;
+}
 export {
   MESSAGE_KIND,
   MESSAGE_TYPE,
@@ -143,6 +199,7 @@ export {
   buildErrorPush,
   buildReasoningPush,
   buildToolRequestPush,
+  chunkReasoningByUtf8Bytes,
   isContentPush,
   isErrorPush,
   isReasoningPush,

package/package.json

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