@rei-standard/amsg-shared 0.3.0 → 0.4.0-next.1

package/dist/index.cjs

@@ -23,13 +23,17 @@ __export(src_exports, {
   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,
@@ -333,3 +337,170 @@ 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,
+  scratch
+}) {
+  const llmOutputText = readLlmOutputText(llmResponse);
+  const ctx = {
+    sessionId,
+    charId,
+    messages,
+    llmResponse,
+    llmOutputText,
+    iteration,
+    metadata: metadata && typeof metadata === "object" ? metadata : {},
+    contactName,
+    avatarUrl: avatarUrl || void 0
+  };
+  if (scratch !== void 0) ctx.scratch = scratch;
+  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

@@ -297,6 +297,106 @@ export function readReasoningContent(llmResponse: unknown): string | null;
  * @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]
+ * @property {Record<string, unknown>}  [scratch]      - Per-fire host scratch object. Producers that run several hooks within one fire (amsg-server's fire-time loop) pass the same mutable object to every hook of that fire, so hooks can hand context to each other without a module-level Map. The library never reads, writes, logs, or persists it, and never shares it across fires. Absent when the producer does not supply one (amsg-instant).
+ */
+/**
+ * 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]
+ * @param {Record<string, unknown>} [args.scratch]
+ * @returns {SessionContext}
+ */
+export function buildSessionContext({ sessionId, messages, llmResponse, iteration, contactName, avatarUrl, charId, metadata, scratch, }: {
+    sessionId: string;
+    messages: ChatMessage[];
+    llmResponse: unknown;
+    iteration: number;
+    contactName: string;
+    avatarUrl?: string;
+    charId?: string;
+    metadata?: Record<string, unknown>;
+    scratch?: 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
  *
@@ -554,6 +654,47 @@ 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;
+    /**
+     * - Per-fire host scratch object. Producers that run several hooks within one fire (amsg-server's fire-time loop) pass the same mutable object to every hook of that fire, so hooks can hand context to each other without a module-level Map. The library never reads, writes, logs, or persists it, and never shares it across fires. Absent when the producer does not supply one (amsg-instant).
+     */
+    scratch?: Record<string, unknown>;
+};
 /**
  * What the push carries. Fixed enum — packages must not add values.
  */

package/dist/index.d.ts

@@ -297,6 +297,106 @@ export function readReasoningContent(llmResponse: unknown): string | null;
  * @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]
+ * @property {Record<string, unknown>}  [scratch]      - Per-fire host scratch object. Producers that run several hooks within one fire (amsg-server's fire-time loop) pass the same mutable object to every hook of that fire, so hooks can hand context to each other without a module-level Map. The library never reads, writes, logs, or persists it, and never shares it across fires. Absent when the producer does not supply one (amsg-instant).
+ */
+/**
+ * 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]
+ * @param {Record<string, unknown>} [args.scratch]
+ * @returns {SessionContext}
+ */
+export function buildSessionContext({ sessionId, messages, llmResponse, iteration, contactName, avatarUrl, charId, metadata, scratch, }: {
+    sessionId: string;
+    messages: ChatMessage[];
+    llmResponse: unknown;
+    iteration: number;
+    contactName: string;
+    avatarUrl?: string;
+    charId?: string;
+    metadata?: Record<string, unknown>;
+    scratch?: 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
  *
@@ -554,6 +654,47 @@ 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;
+    /**
+     * - Per-fire host scratch object. Producers that run several hooks within one fire (amsg-server's fire-time loop) pass the same mutable object to every hook of that fire, so hooks can hand context to each other without a module-level Map. The library never reads, writes, logs, or persists it, and never shares it across fires. Absent when the producer does not supply one (amsg-instant).
+     */
+    scratch?: Record<string, unknown>;
+};
 /**
  * What the push carries. Fixed enum — packages must not add values.
  */

package/dist/index.mjs

@@ -290,18 +290,189 @@ 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,
+  scratch
+}) {
+  const llmOutputText = readLlmOutputText(llmResponse);
+  const ctx = {
+    sessionId,
+    charId,
+    messages,
+    llmResponse,
+    llmOutputText,
+    iteration,
+    metadata: metadata && typeof metadata === "object" ? metadata : {},
+    contactName,
+    avatarUrl: avatarUrl || void 0
+  };
+  if (scratch !== void 0) ctx.scratch = scratch;
+  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,

package/package.json

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