@rei-standard/amsg-shared 0.2.0 → 0.4.0-next.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

package/dist/index.cjs

@@ -19,21 +19,31 @@ 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,
+  assertValidDecision: () => assertValidDecision,
   base64UrlToBytes: () => base64UrlToBytes,
   buildContentPush: () => buildContentPush,
   buildErrorPush: () => buildErrorPush,
   buildReasoningPush: () => buildReasoningPush,
+  buildSessionContext: () => buildSessionContext,
   buildToolRequestPush: () => buildToolRequestPush,
   chunkReasoningByUtf8Bytes: () => chunkReasoningByUtf8Bytes,
   concatBytes: () => concatBytes,
+  extractAssistantMessage: () => extractAssistantMessage,
+  extractToolCallsFromDecision: () => extractToolCallsFromDecision,
   isContentPush: () => isContentPush,
   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({
@@ -264,3 +274,231 @@ 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();
+}
+function buildSessionContext({
+  sessionId,
+  messages,
+  llmResponse,
+  iteration,
+  contactName,
+  avatarUrl,
+  charId,
+  metadata
+}) {
+  const llmOutputText = readLlmOutputText(llmResponse);
+  const ctx = {
+    sessionId,
+    charId,
+    messages,
+    llmResponse,
+    llmOutputText,
+    iteration,
+    metadata: metadata && typeof metadata === "object" ? metadata : {},
+    contactName,
+    avatarUrl: avatarUrl || void 0
+  };
+  return Object.freeze(ctx);
+}
+function readLlmOutputText(llmResponse) {
+  if (!llmResponse || typeof llmResponse !== "object") return "";
+  const choices = (
+    /** @type {{ choices?: unknown }} */
+    llmResponse.choices
+  );
+  if (!Array.isArray(choices) || choices.length === 0) return "";
+  const message = (
+    /** @type {{ message?: { content?: unknown } }} */
+    choices[0]?.message
+  );
+  const content = message?.content;
+  return typeof content === "string" ? content : "";
+}
+function extractAssistantMessage(llmResponse) {
+  const message = llmResponse && typeof llmResponse === "object" && Array.isArray(
+    /** @type {{ choices?: unknown }} */
+    llmResponse.choices
+  ) && /** @type {{ choices: Array<{ message?: unknown }> }} */
+  llmResponse.choices[0]?.message;
+  if (message && typeof message === "object") {
+    return (
+      /** @type {ChatMessage} */
+      message
+    );
+  }
+  return { role: "assistant", content: "" };
+}
+var VALID_DECISIONS = /* @__PURE__ */ new Set(["finish", "tool-request", "continue", "skip-push"]);
+function assertValidDecision(decision, options = {}) {
+  const inlineToolCalls = options.inlineToolCalls === true;
+  if (!decision || typeof decision !== "object") {
+    throw new TypeError(`onLLMOutput returned invalid decision: ${stringifyDecisionForError(decision)}`);
+  }
+  const tag = (
+    /** @type {{ decision?: unknown }} */
+    decision.decision
+  );
+  if (typeof tag !== "string" || !VALID_DECISIONS.has(tag)) {
+    throw new TypeError(`onLLMOutput returned invalid decision tag: ${stringifyDecisionForError(tag)}`);
+  }
+  const hasSingular = Object.prototype.hasOwnProperty.call(decision, "pushPayload");
+  const hasPlural = Object.prototype.hasOwnProperty.call(decision, "pushPayloads");
+  if (hasSingular) {
+    throw new TypeError(
+      hasPlural ? "pushPayload (singular) is removed in 0.8.0, use pushPayloads" : "pushPayload (singular) is removed in 0.8.0, use pushPayloads: [yourPayload]"
+    );
+  }
+  if (tag === "continue") {
+    if (!Array.isArray(
+      /** @type {{ nextHistory?: unknown }} */
+      decision.nextHistory
+    )) {
+      throw new TypeError('decision:"continue" requires a nextHistory array');
+    }
+    return;
+  }
+  if (tag === "skip-push") {
+    return;
+  }
+  if (tag === "tool-request" && inlineToolCalls && Object.prototype.hasOwnProperty.call(decision, "toolCalls")) {
+    const toolCalls = (
+      /** @type {{ toolCalls?: unknown }} */
+      decision.toolCalls
+    );
+    if (!Array.isArray(toolCalls) || toolCalls.length === 0) {
+      throw new TypeError('decision:"tool-request" toolCalls must be a non-empty array when set');
+    }
+    for (let i = 0; i < toolCalls.length; i++) {
+      const t = toolCalls[i];
+      if (!t || typeof t !== "object" || Array.isArray(t)) {
+        throw new TypeError(`toolCalls[${i}] must be a plain object, got ${stringifyDecisionForError(t)}`);
+      }
+    }
+    if (!hasPlural) return;
+  }
+  if (!hasPlural || !Array.isArray(
+    /** @type {{ pushPayloads?: unknown }} */
+    decision.pushPayloads
+  )) {
+    throw new TypeError(`decision:"${tag}" requires a pushPayloads array`);
+  }
+  const pushes = (
+    /** @type {Array<unknown>} */
+    decision.pushPayloads
+  );
+  if (pushes.length === 0) {
+    throw new TypeError("pushPayloads: [] \u2014 use decision: skip-push to skip notification entirely");
+  }
+  for (let i = 0; i < pushes.length; i++) {
+    const p = pushes[i];
+    if (!p || typeof p !== "object" || Array.isArray(p)) {
+      throw new TypeError(`pushPayloads[${i}] must be a plain object, got ${stringifyDecisionForError(p)}`);
+    }
+    if (Object.prototype.hasOwnProperty.call(p, "splitPattern")) {
+      throw new TypeError(`pushPayloads[${i}].splitPattern is removed in 0.8.0; caller is responsible for splitting`);
+    }
+    if (Object.prototype.hasOwnProperty.call(p, "messageId")) {
+      const id = (
+        /** @type {{ messageId?: unknown }} */
+        p.messageId
+      );
+      if (typeof id !== "string" || id === "") {
+        throw new TypeError(`pushPayloads[${i}].messageId must be a non-empty string when set, got ${stringifyDecisionForError(id)}`);
+      }
+    }
+  }
+}
+function extractToolCallsFromDecision(decision) {
+  if (!decision || typeof decision !== "object") return [];
+  const direct = (
+    /** @type {{ toolCalls?: unknown }} */
+    decision.toolCalls
+  );
+  if (Array.isArray(direct) && direct.length > 0) {
+    return direct;
+  }
+  const pushPayloads = (
+    /** @type {{ pushPayloads?: unknown }} */
+    decision.pushPayloads
+  );
+  if (!Array.isArray(pushPayloads)) return [];
+  const out = [];
+  for (const push of pushPayloads) {
+    if (push && typeof push === "object" && Array.isArray(
+      /** @type {{ toolCalls?: unknown }} */
+      push.toolCalls
+    )) {
+      out.push(.../** @type {{ toolCalls: unknown[] }} */
+      push.toolCalls);
+    }
+  }
+  return out;
+}
+function stringifyDecisionForError(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}

package/dist/index.d.cts

@@ -247,6 +247,153 @@ 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;
+/**
+ * @typedef {Object} ChatMessage
+ * @property {'system' | 'user' | 'assistant' | 'tool'} role
+ * @property {string | unknown[] | null} [content]
+ * @property {Array<{ id: string, type: 'function', function: { name: string, arguments: string } }>} [tool_calls]
+ * @property {string} [tool_call_id]
+ * @property {string} [name]
+ */
+/**
+ * @typedef {Object} SessionContext
+ * @property {string}                   sessionId
+ * @property {string}                   [charId]
+ * @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 {number}                   iteration      - 0-indexed: the round that just finished.
+ * @property {Record<string, unknown>}  metadata
+ * @property {string}                   contactName
+ * @property {string}                   [avatarUrl]
+ */
+/**
+ * Build the frozen SessionContext handed to an onLLMOutput hook.
+ *
+ * Credentials (apiKey / apiUrl / pushSubscription / vapid / masterKey) are
+ * intentionally NOT part of the shape: a console.log(ctx) from a hook must
+ * not leak keys, and a third-party hook must not be able to exfiltrate
+ * them. Frozen so a hook cannot mutate the live history — if it chooses
+ * `decision:'continue'`, the caller still owns its copy.
+ *
+ * @param {Object} args
+ * @param {string} args.sessionId
+ * @param {ChatMessage[]} args.messages
+ * @param {unknown} args.llmResponse
+ * @param {number} args.iteration
+ * @param {string} args.contactName
+ * @param {string} [args.avatarUrl]
+ * @param {string} [args.charId]
+ * @param {Record<string, unknown>} [args.metadata]
+ * @returns {SessionContext}
+ */
+export function buildSessionContext({ sessionId, messages, llmResponse, iteration, contactName, avatarUrl, charId, metadata, }: {
+    sessionId: string;
+    messages: ChatMessage[];
+    llmResponse: unknown;
+    iteration: number;
+    contactName: string;
+    avatarUrl?: string;
+    charId?: string;
+    metadata?: Record<string, unknown>;
+}): SessionContext;
+/**
+ * Extract the `choices[0].message` whole object — preserving `tool_calls`
+ * / `reasoning_content` / `refusal` etc. — for appending to the running
+ * history. Falls back to a minimal placeholder when the response is
+ * malformed so the hook still gets a chance to react via
+ * `llmOutputText === ''`.
+ *
+ * Critically, we keep the entire message object (not just
+ * `{role, content}`): the next round may need to forward a `tool_calls`
+ * array to OpenAI alongside the matching tool-result messages, and
+ * stripping the field would make the API reject the request.
+ *
+ * @param {unknown} llmResponse
+ * @returns {ChatMessage}
+ */
+export function extractAssistantMessage(llmResponse: unknown): ChatMessage;
+/**
+ * Assert that an onLLMOutput hook returned a structurally valid decision.
+ * TypeScript discriminated unions don't survive into runtime, and a
+ * misbehaving hook can easily return `null` / `{ decision: 'idk' }` /
+ * `undefined` — treat any of those as a hook contract violation.
+ *
+ * Flavors:
+ * - default (amsg-instant): 'tool-request' must carry pushPayloads — the
+ *   tool_request push goes to the client, which executes the tools and
+ *   POSTs /continue.
+ * - `{ inlineToolCalls: true }` (amsg-server fire-time loop): the host
+ *   executes tools in-process, so 'tool-request' may instead carry a
+ *   non-empty `toolCalls` array directly; pushPayloads then become
+ *   optional. pushPayloads-shaped tool-requests stay valid so a
+ *   classifier written for instant drops in unchanged.
+ *
+ * @param {unknown} decision
+ * @param {{ inlineToolCalls?: boolean }} [options]
+ */
+export function assertValidDecision(decision: unknown, options?: {
+    inlineToolCalls?: boolean;
+}): void;
+/**
+ * Pull the toolCalls out of a 'tool-request' decision, whichever shape it
+ * came in: `decision.toolCalls` directly (server flavor), or embedded in
+ * tool_request pushPayloads (instant classifier flavor).
+ *
+ * @param {unknown} decision
+ * @returns {Array<Record<string, unknown>>}
+ */
+export function extractToolCallsFromDecision(decision: unknown): Array<Record<string, unknown>>;
 /**
  * @rei-standard/amsg-shared
  *
@@ -316,6 +463,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
@@ -439,24 +588,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";
@@ -502,6 +651,43 @@ export type ErrorPush = AmsgPushCommon & {
  * `switch` on `messageKind` and the compiler narrows automatically.
  */
 export type AmsgPush = ContentPush | ReasoningPush | ToolRequestPush | ErrorPush;
+export type ChatMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | unknown[] | null;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+    name?: string;
+};
+export type SessionContext = {
+    sessionId: string;
+    charId?: string;
+    /**
+     * - Including the just-appended assistant turn.
+     */
+    messages: ChatMessage[];
+    /**
+     * - Full LLM response (choices, usage, …).
+     */
+    llmResponse: unknown;
+    /**
+     * - May be '' for pure tool-call responses.
+     */
+    llmOutputText: string;
+    /**
+     * - 0-indexed: the round that just finished.
+     */
+    iteration: number;
+    metadata: Record<string, unknown>;
+    contactName: string;
+    avatarUrl?: string;
+};
 /**
  * What the push carries. Fixed enum — packages must not add values.
  */

package/dist/index.d.ts

@@ -247,6 +247,153 @@ 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;
+/**
+ * @typedef {Object} ChatMessage
+ * @property {'system' | 'user' | 'assistant' | 'tool'} role
+ * @property {string | unknown[] | null} [content]
+ * @property {Array<{ id: string, type: 'function', function: { name: string, arguments: string } }>} [tool_calls]
+ * @property {string} [tool_call_id]
+ * @property {string} [name]
+ */
+/**
+ * @typedef {Object} SessionContext
+ * @property {string}                   sessionId
+ * @property {string}                   [charId]
+ * @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 {number}                   iteration      - 0-indexed: the round that just finished.
+ * @property {Record<string, unknown>}  metadata
+ * @property {string}                   contactName
+ * @property {string}                   [avatarUrl]
+ */
+/**
+ * Build the frozen SessionContext handed to an onLLMOutput hook.
+ *
+ * Credentials (apiKey / apiUrl / pushSubscription / vapid / masterKey) are
+ * intentionally NOT part of the shape: a console.log(ctx) from a hook must
+ * not leak keys, and a third-party hook must not be able to exfiltrate
+ * them. Frozen so a hook cannot mutate the live history — if it chooses
+ * `decision:'continue'`, the caller still owns its copy.
+ *
+ * @param {Object} args
+ * @param {string} args.sessionId
+ * @param {ChatMessage[]} args.messages
+ * @param {unknown} args.llmResponse
+ * @param {number} args.iteration
+ * @param {string} args.contactName
+ * @param {string} [args.avatarUrl]
+ * @param {string} [args.charId]
+ * @param {Record<string, unknown>} [args.metadata]
+ * @returns {SessionContext}
+ */
+export function buildSessionContext({ sessionId, messages, llmResponse, iteration, contactName, avatarUrl, charId, metadata, }: {
+    sessionId: string;
+    messages: ChatMessage[];
+    llmResponse: unknown;
+    iteration: number;
+    contactName: string;
+    avatarUrl?: string;
+    charId?: string;
+    metadata?: Record<string, unknown>;
+}): SessionContext;
+/**
+ * Extract the `choices[0].message` whole object — preserving `tool_calls`
+ * / `reasoning_content` / `refusal` etc. — for appending to the running
+ * history. Falls back to a minimal placeholder when the response is
+ * malformed so the hook still gets a chance to react via
+ * `llmOutputText === ''`.
+ *
+ * Critically, we keep the entire message object (not just
+ * `{role, content}`): the next round may need to forward a `tool_calls`
+ * array to OpenAI alongside the matching tool-result messages, and
+ * stripping the field would make the API reject the request.
+ *
+ * @param {unknown} llmResponse
+ * @returns {ChatMessage}
+ */
+export function extractAssistantMessage(llmResponse: unknown): ChatMessage;
+/**
+ * Assert that an onLLMOutput hook returned a structurally valid decision.
+ * TypeScript discriminated unions don't survive into runtime, and a
+ * misbehaving hook can easily return `null` / `{ decision: 'idk' }` /
+ * `undefined` — treat any of those as a hook contract violation.
+ *
+ * Flavors:
+ * - default (amsg-instant): 'tool-request' must carry pushPayloads — the
+ *   tool_request push goes to the client, which executes the tools and
+ *   POSTs /continue.
+ * - `{ inlineToolCalls: true }` (amsg-server fire-time loop): the host
+ *   executes tools in-process, so 'tool-request' may instead carry a
+ *   non-empty `toolCalls` array directly; pushPayloads then become
+ *   optional. pushPayloads-shaped tool-requests stay valid so a
+ *   classifier written for instant drops in unchanged.
+ *
+ * @param {unknown} decision
+ * @param {{ inlineToolCalls?: boolean }} [options]
+ */
+export function assertValidDecision(decision: unknown, options?: {
+    inlineToolCalls?: boolean;
+}): void;
+/**
+ * Pull the toolCalls out of a 'tool-request' decision, whichever shape it
+ * came in: `decision.toolCalls` directly (server flavor), or embedded in
+ * tool_request pushPayloads (instant classifier flavor).
+ *
+ * @param {unknown} decision
+ * @returns {Array<Record<string, unknown>>}
+ */
+export function extractToolCallsFromDecision(decision: unknown): Array<Record<string, unknown>>;
 /**
  * @rei-standard/amsg-shared
  *
@@ -316,6 +463,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
@@ -439,24 +588,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";
@@ -502,6 +651,43 @@ export type ErrorPush = AmsgPushCommon & {
  * `switch` on `messageKind` and the compiler narrows automatically.
  */
 export type AmsgPush = ContentPush | ReasoningPush | ToolRequestPush | ErrorPush;
+export type ChatMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | unknown[] | null;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+    name?: string;
+};
+export type SessionContext = {
+    sessionId: string;
+    charId?: string;
+    /**
+     * - Including the just-appended assistant turn.
+     */
+    messages: ChatMessage[];
+    /**
+     * - Full LLM response (choices, usage, …).
+     */
+    llmResponse: unknown;
+    /**
+     * - May be '' for pure tool-call responses.
+     */
+    llmOutputText: string;
+    /**
+     * - 0-indexed: the round that just finished.
+     */
+    iteration: number;
+    metadata: Record<string, unknown>;
+    contactName: string;
+    avatarUrl?: string;
+};
 /**
  * What the push carries. Fixed enum — packages must not add values.
  */

package/dist/index.mjs

@@ -227,20 +227,258 @@ 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();
+}
+function buildSessionContext({
+  sessionId,
+  messages,
+  llmResponse,
+  iteration,
+  contactName,
+  avatarUrl,
+  charId,
+  metadata
+}) {
+  const llmOutputText = readLlmOutputText(llmResponse);
+  const ctx = {
+    sessionId,
+    charId,
+    messages,
+    llmResponse,
+    llmOutputText,
+    iteration,
+    metadata: metadata && typeof metadata === "object" ? metadata : {},
+    contactName,
+    avatarUrl: avatarUrl || void 0
+  };
+  return Object.freeze(ctx);
+}
+function readLlmOutputText(llmResponse) {
+  if (!llmResponse || typeof llmResponse !== "object") return "";
+  const choices = (
+    /** @type {{ choices?: unknown }} */
+    llmResponse.choices
+  );
+  if (!Array.isArray(choices) || choices.length === 0) return "";
+  const message = (
+    /** @type {{ message?: { content?: unknown } }} */
+    choices[0]?.message
+  );
+  const content = message?.content;
+  return typeof content === "string" ? content : "";
+}
+function extractAssistantMessage(llmResponse) {
+  const message = llmResponse && typeof llmResponse === "object" && Array.isArray(
+    /** @type {{ choices?: unknown }} */
+    llmResponse.choices
+  ) && /** @type {{ choices: Array<{ message?: unknown }> }} */
+  llmResponse.choices[0]?.message;
+  if (message && typeof message === "object") {
+    return (
+      /** @type {ChatMessage} */
+      message
+    );
+  }
+  return { role: "assistant", content: "" };
+}
+var VALID_DECISIONS = /* @__PURE__ */ new Set(["finish", "tool-request", "continue", "skip-push"]);
+function assertValidDecision(decision, options = {}) {
+  const inlineToolCalls = options.inlineToolCalls === true;
+  if (!decision || typeof decision !== "object") {
+    throw new TypeError(`onLLMOutput returned invalid decision: ${stringifyDecisionForError(decision)}`);
+  }
+  const tag = (
+    /** @type {{ decision?: unknown }} */
+    decision.decision
+  );
+  if (typeof tag !== "string" || !VALID_DECISIONS.has(tag)) {
+    throw new TypeError(`onLLMOutput returned invalid decision tag: ${stringifyDecisionForError(tag)}`);
+  }
+  const hasSingular = Object.prototype.hasOwnProperty.call(decision, "pushPayload");
+  const hasPlural = Object.prototype.hasOwnProperty.call(decision, "pushPayloads");
+  if (hasSingular) {
+    throw new TypeError(
+      hasPlural ? "pushPayload (singular) is removed in 0.8.0, use pushPayloads" : "pushPayload (singular) is removed in 0.8.0, use pushPayloads: [yourPayload]"
+    );
+  }
+  if (tag === "continue") {
+    if (!Array.isArray(
+      /** @type {{ nextHistory?: unknown }} */
+      decision.nextHistory
+    )) {
+      throw new TypeError('decision:"continue" requires a nextHistory array');
+    }
+    return;
+  }
+  if (tag === "skip-push") {
+    return;
+  }
+  if (tag === "tool-request" && inlineToolCalls && Object.prototype.hasOwnProperty.call(decision, "toolCalls")) {
+    const toolCalls = (
+      /** @type {{ toolCalls?: unknown }} */
+      decision.toolCalls
+    );
+    if (!Array.isArray(toolCalls) || toolCalls.length === 0) {
+      throw new TypeError('decision:"tool-request" toolCalls must be a non-empty array when set');
+    }
+    for (let i = 0; i < toolCalls.length; i++) {
+      const t = toolCalls[i];
+      if (!t || typeof t !== "object" || Array.isArray(t)) {
+        throw new TypeError(`toolCalls[${i}] must be a plain object, got ${stringifyDecisionForError(t)}`);
+      }
+    }
+    if (!hasPlural) return;
+  }
+  if (!hasPlural || !Array.isArray(
+    /** @type {{ pushPayloads?: unknown }} */
+    decision.pushPayloads
+  )) {
+    throw new TypeError(`decision:"${tag}" requires a pushPayloads array`);
+  }
+  const pushes = (
+    /** @type {Array<unknown>} */
+    decision.pushPayloads
+  );
+  if (pushes.length === 0) {
+    throw new TypeError("pushPayloads: [] \u2014 use decision: skip-push to skip notification entirely");
+  }
+  for (let i = 0; i < pushes.length; i++) {
+    const p = pushes[i];
+    if (!p || typeof p !== "object" || Array.isArray(p)) {
+      throw new TypeError(`pushPayloads[${i}] must be a plain object, got ${stringifyDecisionForError(p)}`);
+    }
+    if (Object.prototype.hasOwnProperty.call(p, "splitPattern")) {
+      throw new TypeError(`pushPayloads[${i}].splitPattern is removed in 0.8.0; caller is responsible for splitting`);
+    }
+    if (Object.prototype.hasOwnProperty.call(p, "messageId")) {
+      const id = (
+        /** @type {{ messageId?: unknown }} */
+        p.messageId
+      );
+      if (typeof id !== "string" || id === "") {
+        throw new TypeError(`pushPayloads[${i}].messageId must be a non-empty string when set, got ${stringifyDecisionForError(id)}`);
+      }
+    }
+  }
+}
+function extractToolCallsFromDecision(decision) {
+  if (!decision || typeof decision !== "object") return [];
+  const direct = (
+    /** @type {{ toolCalls?: unknown }} */
+    decision.toolCalls
+  );
+  if (Array.isArray(direct) && direct.length > 0) {
+    return direct;
+  }
+  const pushPayloads = (
+    /** @type {{ pushPayloads?: unknown }} */
+    decision.pushPayloads
+  );
+  if (!Array.isArray(pushPayloads)) return [];
+  const out = [];
+  for (const push of pushPayloads) {
+    if (push && typeof push === "object" && Array.isArray(
+      /** @type {{ toolCalls?: unknown }} */
+      push.toolCalls
+    )) {
+      out.push(.../** @type {{ toolCalls: unknown[] }} */
+      push.toolCalls);
+    }
+  }
+  return out;
+}
+function stringifyDecisionForError(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
 export {
+  AVATAR_URL_MAX_LENGTH,
   MESSAGE_KIND,
   MESSAGE_TYPE,
   PUSH_SOURCE,
+  assertValidDecision,
   base64UrlToBytes,
   buildContentPush,
   buildErrorPush,
   buildReasoningPush,
+  buildSessionContext,
   buildToolRequestPush,
   chunkReasoningByUtf8Bytes,
   concatBytes,
+  extractAssistantMessage,
+  extractToolCallsFromDecision,
   isContentPush,
   isErrorPush,
   isReasoningPush,
   isToolRequestPush,
-  toUint8
+  isValidUrl,
+  normalizeVapidSubject,
+  readReasoningContent,
+  stripReasoningTags,
+  toUint8,
+  validateAvatarUrl
 };

package/package.json

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