@rei-standard/amsg-shared 0.4.0-next.0 → 0.4.0-next.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReiStandard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -20,32 +20,545 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   AVATAR_URL_MAX_LENGTH: () => AVATAR_URL_MAX_LENGTH,
+  DEFAULT_MULTIPART_MAX_CHUNKS: () => DEFAULT_MULTIPART_MAX_CHUNKS,
+  DEFAULT_MULTIPART_MAX_TOTAL_BYTES: () => DEFAULT_MULTIPART_MAX_TOTAL_BYTES,
+  DEFAULT_MULTIPART_TTL_MS: () => DEFAULT_MULTIPART_TTL_MS,
+  LLM_MESSAGES_ERROR: () => LLM_MESSAGES_ERROR,
   MESSAGE_KIND: () => MESSAGE_KIND,
   MESSAGE_TYPE: () => MESSAGE_TYPE,
+  MULTIPART_ENCODING: () => MULTIPART_ENCODING,
+  MULTIPART_MESSAGE_KIND: () => MULTIPART_MESSAGE_KIND,
+  MULTIPART_VERSION: () => MULTIPART_VERSION,
   PUSH_SOURCE: () => PUSH_SOURCE,
+  REI_AMSG_DELIVER_MESSAGE_TYPE: () => REI_AMSG_DELIVER_MESSAGE_TYPE,
+  REI_AMSG_POSTMESSAGE_TYPE: () => REI_AMSG_POSTMESSAGE_TYPE,
+  REI_SW_EVENT: () => REI_SW_EVENT,
+  REI_SW_MESSAGE_TYPE: () => REI_SW_MESSAGE_TYPE,
   assertValidDecision: () => assertValidDecision,
   base64UrlToBytes: () => base64UrlToBytes,
   buildContentPush: () => buildContentPush,
   buildErrorPush: () => buildErrorPush,
+  buildLlmRequestBody: () => buildLlmRequestBody,
   buildReasoningPush: () => buildReasoningPush,
   buildSessionContext: () => buildSessionContext,
   buildToolRequestPush: () => buildToolRequestPush,
+  buildVapidJwt: () => buildVapidJwt,
+  bytesToBase64: () => bytesToBase64,
+  bytesToBase64Url: () => bytesToBase64Url,
+  bytesToHex: () => bytesToHex,
+  callLlm: () => callLlm,
   chunkReasoningByUtf8Bytes: () => chunkReasoningByUtf8Bytes,
   concatBytes: () => concatBytes,
   extractAssistantMessage: () => extractAssistantMessage,
   extractToolCallsFromDecision: () => extractToolCallsFromDecision,
+  hexToBytes: () => hexToBytes,
+  hmacSha256: () => hmacSha256,
   isContentPush: () => isContentPush,
   isErrorPush: () => isErrorPush,
   isReasoningPush: () => isReasoningPush,
   isToolRequestPush: () => isToolRequestPush,
   isValidUrl: () => isValidUrl,
+  jsonToBase64Url: () => jsonToBase64Url,
+  normalizeAiApiUrl: () => normalizeAiApiUrl,
   normalizeVapidSubject: () => normalizeVapidSubject,
+  randomBytes: () => randomBytes,
+  randomUUID: () => randomUUID,
   readReasoningContent: () => readReasoningContent,
+  sendWebPush: () => sendWebPush,
   stripReasoningTags: () => stripReasoningTags,
+  timingSafeEqualBytes: () => timingSafeEqualBytes,
   toUint8: () => toUint8,
-  validateAvatarUrl: () => validateAvatarUrl
+  utf8: () => utf8,
+  utf8Decode: () => utf8Decode,
+  validateAvatarUrl: () => validateAvatarUrl,
+  validateLlmMessagesShape: () => validateLlmMessagesShape,
+  verifyVapidJwt: () => verifyVapidJwt
 });
 module.exports = __toCommonJS(src_exports);
+
+// src/webcrypto-utils.js
+var TEXT_ENCODER = new TextEncoder();
+var TEXT_DECODER = new TextDecoder("utf-8", { fatal: false });
+function toUint8(buf) {
+  if (buf instanceof Uint8Array) return buf;
+  if (buf instanceof ArrayBuffer) return new Uint8Array(buf);
+  if (ArrayBuffer.isView(buf)) return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  throw new TypeError("Expected ArrayBuffer / Uint8Array");
+}
+function concatBytes(...chunks) {
+  let total = 0;
+  for (const c of chunks) total += c.byteLength;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c instanceof Uint8Array ? c : new Uint8Array(c.buffer || c), offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+function utf8(str) {
+  return TEXT_ENCODER.encode(String(str));
+}
+function utf8Decode(buf) {
+  return TEXT_DECODER.decode(toUint8(buf));
+}
+function bytesToBase64(buf) {
+  const bytes = toUint8(buf);
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) {
+    bin += String.fromCharCode(bytes[i]);
+  }
+  return typeof btoa === "function" ? btoa(bin) : Buffer.from(bin, "binary").toString("base64");
+}
+function bytesToBase64Url(buf) {
+  return bytesToBase64(buf).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlToBytes(input) {
+  const s = String(input).replace(/-/g, "+").replace(/_/g, "/");
+  const pad = (4 - s.length % 4) % 4;
+  const padded = s + "=".repeat(pad);
+  const bin = typeof atob === "function" ? atob(padded) : Buffer.from(padded, "base64").toString("binary");
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function jsonToBase64Url(value) {
+  return bytesToBase64Url(utf8(JSON.stringify(value)));
+}
+function bytesToHex(buf) {
+  const bytes = toUint8(buf);
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function hexToBytes(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+async function hmacSha256(keyBytes, data) {
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    toUint8(keyBytes),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await globalThis.crypto.subtle.sign("HMAC", key, toUint8(data));
+  return new Uint8Array(sig);
+}
+function timingSafeEqualBytes(a, b) {
+  const x = toUint8(a);
+  const y = toUint8(b);
+  if (x.length !== y.length) return false;
+  let diff = 0;
+  for (let i = 0; i < x.length; i++) {
+    diff |= x[i] ^ y[i];
+  }
+  return diff === 0;
+}
+function randomBytes(n) {
+  const out = new Uint8Array(n);
+  globalThis.crypto.getRandomValues(out);
+  return out;
+}
+function randomUUID() {
+  return globalThis.crypto.randomUUID();
+}
+
+// src/llm-messages.js
+var VALID_LLM_MESSAGE_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool"]);
+var LLM_MESSAGES_ERROR = Object.freeze({
+  MESSAGES_NOT_ARRAY: "MESSAGES_NOT_ARRAY",
+  MESSAGE_NOT_OBJECT: "MESSAGE_NOT_OBJECT",
+  INVALID_ROLE: "INVALID_ROLE",
+  TOOL_CALL_MALFORMED: "TOOL_CALL_MALFORMED",
+  TOOL_CONTENT_INVALID: "TOOL_CONTENT_INVALID",
+  TOOL_CALL_ID_MISSING: "TOOL_CALL_ID_MISSING",
+  CONTENT_EMPTY_STRING: "CONTENT_EMPTY_STRING",
+  CONTENT_EMPTY_ARRAY: "CONTENT_EMPTY_ARRAY",
+  CONTENT_INVALID_TYPE: "CONTENT_INVALID_TYPE"
+});
+function validateLlmMessagesShape(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return { code: LLM_MESSAGES_ERROR.MESSAGES_NOT_ARRAY };
+  }
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m !== "object" || Array.isArray(m)) {
+      return { code: LLM_MESSAGES_ERROR.MESSAGE_NOT_OBJECT, index: i };
+    }
+    if (!VALID_LLM_MESSAGE_ROLES.has(m.role)) {
+      return { code: LLM_MESSAGES_ERROR.INVALID_ROLE, index: i };
+    }
+    const isAssistantToolCallCarrier = m.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.length > 0;
+    if (isAssistantToolCallCarrier) {
+      for (let j = 0; j < m.tool_calls.length; j++) {
+        const tc = m.tool_calls[j];
+        if (!tc || typeof tc !== "object" || typeof tc.id !== "string" || !tc.function) {
+          return { code: LLM_MESSAGES_ERROR.TOOL_CALL_MALFORMED, index: i, toolCallIndex: j };
+        }
+      }
+      continue;
+    }
+    if (m.role === "tool") {
+      if (typeof m.content !== "string" && !Array.isArray(m.content)) {
+        return { code: LLM_MESSAGES_ERROR.TOOL_CONTENT_INVALID, index: i };
+      }
+      if (typeof m.tool_call_id !== "string" || !m.tool_call_id) {
+        return { code: LLM_MESSAGES_ERROR.TOOL_CALL_ID_MISSING, index: i };
+      }
+      continue;
+    }
+    if (typeof m.content === "string") {
+      if (!m.content) {
+        return { code: LLM_MESSAGES_ERROR.CONTENT_EMPTY_STRING, index: i };
+      }
+    } else if (Array.isArray(m.content)) {
+      if (m.content.length === 0) {
+        return { code: LLM_MESSAGES_ERROR.CONTENT_EMPTY_ARRAY, index: i };
+      }
+    } else {
+      return { code: LLM_MESSAGES_ERROR.CONTENT_INVALID_TYPE, index: i };
+    }
+  }
+  return null;
+}
+
+// src/llm-call.js
+async function callLlm(payload, options = {}) {
+  const requireContent = options.requireContent !== false;
+  const timeoutMs = typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 3e5;
+  const fetchImpl = options.fetch || globalThis.fetch;
+  const normalizedApiUrl = normalizeAiApiUrl(payload.apiUrl);
+  const requestBody = buildLlmRequestBody(payload, options);
+  const aiResponse = await fetchImpl(normalizedApiUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${payload.apiKey}`
+    },
+    body: JSON.stringify(requestBody),
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  if (!aiResponse.ok) {
+    if (aiResponse.status === 405) {
+      throw new Error(
+        `AI API error: 405 Method Not Allowed. apiUrl must point to a full chat endpoint (for example: /chat/completions). Received: ${normalizedApiUrl}`
+      );
+    }
+    throw new Error(
+      `AI API error: ${aiResponse.status} ${aiResponse.statusText || "Unknown Error"}. Request URL: ${normalizedApiUrl}`
+    );
+  }
+  const aiData = await aiResponse.json();
+  const rawContent = aiData?.choices?.[0]?.message?.content;
+  if (requireContent && (typeof rawContent !== "string" || !rawContent.trim())) {
+    throw new Error("AI API error: response missing choices[0].message.content");
+  }
+  return { response: aiData, content: typeof rawContent === "string" ? rawContent.trim() : "" };
+}
+function buildLlmRequestBody(payload, options = {}) {
+  const llmMessages = Array.isArray(payload.messages) && payload.messages.length > 0 ? payload.messages : [{ role: "user", content: payload.completePrompt }];
+  const requestBody = {
+    model: payload.primaryModel,
+    messages: llmMessages
+  };
+  if (options.stream !== void 0) {
+    requestBody.stream = options.stream;
+  }
+  if (payload.temperature !== void 0 && payload.temperature !== null) {
+    requestBody.temperature = payload.temperature;
+  } else if (!Array.isArray(payload.messages)) {
+    requestBody.temperature = 0.8;
+  }
+  if (options.forwardTools !== false && Array.isArray(payload.tools) && payload.tools.length > 0) {
+    requestBody.tools = payload.tools;
+    if (payload.toolChoice !== void 0 && payload.toolChoice !== null) {
+      requestBody.tool_choice = payload.toolChoice;
+    }
+  }
+  if (payload.maxTokens === void 0 || payload.maxTokens === null) {
+    return requestBody;
+  }
+  if (!Number.isInteger(payload.maxTokens) || payload.maxTokens <= 0) {
+    throw new Error("Invalid maxTokens: maxTokens must be a positive integer when provided.");
+  }
+  requestBody.max_tokens = payload.maxTokens;
+  return requestBody;
+}
+function normalizeAiApiUrl(apiUrl) {
+  const trimmed = String(apiUrl || "").trim();
+  if (!trimmed) {
+    throw new Error(
+      "Invalid apiUrl: apiUrl is required. Please provide a chat endpoint URL (for example: https://api.openai.com or https://api.openai.com/v1/chat/completions)."
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
+    );
+  }
+  let path = parsed.pathname.replace(/\/+$/, "") || "/";
+  if (/\/chat\/completions$/.test(path)) {
+  } else if (path === "/") {
+    path = "/v1/chat/completions";
+  } else if (/\/v\d+$/.test(path)) {
+    path = `${path}/chat/completions`;
+  }
+  parsed.pathname = path;
+  return parsed.toString();
+}
+
+// src/webpush.js
+var KEY_INFO_PREFIX = utf8("WebPush: info\0");
+var CEK_INFO = utf8("Content-Encoding: aes128gcm\0");
+var NONCE_INFO = utf8("Content-Encoding: nonce\0");
+var VAPID_DEFAULT_TTL = 60;
+var VAPID_TOKEN_LIFETIME = 12 * 3600;
+var RECORD_SIZE = 4096;
+async function sendWebPush({ subscription, payload, vapid, ttl, fetch: fetchImpl }) {
+  if (!subscription || typeof subscription.endpoint !== "string") {
+    throw new Error("sendWebPush: invalid subscription");
+  }
+  if (typeof payload !== "string") {
+    throw new Error("sendWebPush: payload must be a string");
+  }
+  if (!vapid || !vapid.email || !vapid.publicKey || !vapid.privateKey) {
+    throw new Error("VAPID_CONFIG_MISSING");
+  }
+  const subscriptionKeys = subscription.keys || {};
+  if (typeof subscriptionKeys.p256dh !== "string" || typeof subscriptionKeys.auth !== "string") {
+    throw new Error("sendWebPush: subscription.keys.p256dh and .auth are required");
+  }
+  const encryptedBody = await encryptPushPayload({
+    plaintext: utf8(payload),
+    uaPublicKey: base64UrlToBytes(subscriptionKeys.p256dh),
+    authSecret: base64UrlToBytes(subscriptionKeys.auth)
+  });
+  const jwt = await buildVapidJwt({
+    audience: originOf(subscription.endpoint),
+    subject: normalizeVapidSubject(vapid.email),
+    publicKey: vapid.publicKey,
+    privateKey: vapid.privateKey
+  });
+  const fetchFn = fetchImpl || globalThis.fetch;
+  if (typeof fetchFn !== "function") {
+    throw new Error("sendWebPush: no fetch implementation available");
+  }
+  const res = await fetchFn(subscription.endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/octet-stream",
+      "Content-Encoding": "aes128gcm",
+      "TTL": String(Number.isFinite(ttl) ? ttl : VAPID_DEFAULT_TTL),
+      "Authorization": `vapid t=${jwt}, k=${vapid.publicKey}`
+    },
+    body: encryptedBody
+  });
+  if (!res.ok) {
+    const text = await safeReadText(res);
+    const err = new Error(
+      `Web Push delivery failed: ${res.status} ${res.statusText || ""}${text ? ` \u2014 ${text}` : ""}`
+    );
+    err.code = "PUSH_SEND_FAILED";
+    err.statusCode = res.status;
+    throw err;
+  }
+  return {
+    statusCode: res.status,
+    body: await safeReadText(res),
+    headers: res.headers
+  };
+}
+async function encryptPushPayload({ plaintext, uaPublicKey, authSecret }) {
+  const asKeyPair = await globalThis.crypto.subtle.generateKey(
+    { name: "ECDH", namedCurve: "P-256" },
+    true,
+    ["deriveBits"]
+  );
+  const asPublicRaw = new Uint8Array(
+    await globalThis.crypto.subtle.exportKey("raw", asKeyPair.publicKey)
+  );
+  const uaPublicCryptoKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    uaPublicKey,
+    { name: "ECDH", namedCurve: "P-256" },
+    false,
+    []
+  );
+  const ecdhSecret = new Uint8Array(
+    await globalThis.crypto.subtle.deriveBits(
+      { name: "ECDH", public: uaPublicCryptoKey },
+      asKeyPair.privateKey,
+      256
+    )
+  );
+  const keyInfo = concatBytes(KEY_INFO_PREFIX, uaPublicKey, asPublicRaw);
+  const ikm = await hkdfSha256(authSecret, ecdhSecret, keyInfo, 32);
+  const salt = randomBytes(16);
+  const cekBytes = await hkdfSha256(salt, ikm, CEK_INFO, 16);
+  const cek = await globalThis.crypto.subtle.importKey(
+    "raw",
+    cekBytes,
+    { name: "AES-GCM" },
+    false,
+    ["encrypt"]
+  );
+  const nonce = await hkdfSha256(salt, ikm, NONCE_INFO, 12);
+  const padded = concatBytes(plaintext, new Uint8Array([2]));
+  const ciphertext = new Uint8Array(
+    await globalThis.crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, cek, padded)
+  );
+  const header = new Uint8Array(16 + 4 + 1 + asPublicRaw.byteLength);
+  header.set(salt, 0);
+  writeUint32BE(header, 16, RECORD_SIZE);
+  header[20] = asPublicRaw.byteLength;
+  header.set(asPublicRaw, 21);
+  return concatBytes(header, ciphertext);
+}
+async function hkdfSha256(salt, ikm, info, length) {
+  const baseKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    toUint8(ikm),
+    { name: "HKDF" },
+    false,
+    ["deriveBits"]
+  );
+  const bits = await globalThis.crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: toUint8(salt),
+      info: toUint8(info)
+    },
+    baseKey,
+    length * 8
+  );
+  return new Uint8Array(bits);
+}
+async function buildVapidJwt({ audience, subject, publicKey, privateKey }) {
+  const header = jsonToBase64Url({ typ: "JWT", alg: "ES256" });
+  const payload = jsonToBase64Url({
+    aud: audience,
+    exp: Math.floor(Date.now() / 1e3) + VAPID_TOKEN_LIFETIME,
+    sub: subject
+  });
+  const signingInput = utf8(`${header}.${payload}`);
+  const pubBytes = base64UrlToBytes(publicKey);
+  const privBytes = base64UrlToBytes(privateKey);
+  if (pubBytes.length !== 65 || pubBytes[0] !== 4) {
+    throw new Error("VAPID publicKey must be a 65-byte uncompressed P-256 point (base64url).");
+  }
+  if (privBytes.length !== 32) {
+    throw new Error("VAPID privateKey must be a 32-byte scalar (base64url).");
+  }
+  const jwk = {
+    kty: "EC",
+    crv: "P-256",
+    d: bytesToBase64Url(privBytes),
+    x: bytesToBase64Url(pubBytes.subarray(1, 33)),
+    y: bytesToBase64Url(pubBytes.subarray(33, 65)),
+    ext: true
+  };
+  const key = await globalThis.crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await globalThis.crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    signingInput
+  );
+  return `${header}.${payload}.${bytesToBase64Url(sig)}`;
+}
+async function verifyVapidJwt(jwt, publicKey) {
+  const parts = String(jwt).split(".");
+  if (parts.length !== 3) throw new Error("VAPID JWT: malformed (expected three segments)");
+  const [h, p, s] = parts;
+  const pubBytes = base64UrlToBytes(publicKey);
+  if (pubBytes.length !== 65 || pubBytes[0] !== 4) {
+    throw new Error("VAPID publicKey must be 65 B uncompressed P-256 (base64url).");
+  }
+  const jwk = {
+    kty: "EC",
+    crv: "P-256",
+    x: bytesToBase64Url(pubBytes.subarray(1, 33)),
+    y: bytesToBase64Url(pubBytes.subarray(33, 65)),
+    ext: true
+  };
+  const key = await globalThis.crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["verify"]
+  );
+  const ok = await globalThis.crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    base64UrlToBytes(s),
+    utf8(`${h}.${p}`)
+  );
+  if (!ok) throw new Error("VAPID JWT: signature mismatch");
+  const payload = JSON.parse(new TextDecoder().decode(base64UrlToBytes(p)));
+  if (!payload.exp || payload.exp <= Math.floor(Date.now() / 1e3)) {
+    throw new Error("VAPID JWT: expired");
+  }
+  return payload;
+}
+function originOf(endpoint) {
+  return new URL(endpoint).origin;
+}
+function writeUint32BE(buf, offset, value) {
+  buf[offset] = value >>> 24 & 255;
+  buf[offset + 1] = value >>> 16 & 255;
+  buf[offset + 2] = value >>> 8 & 255;
+  buf[offset + 3] = value & 255;
+}
+async function safeReadText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+// src/protocol.js
+var MULTIPART_MESSAGE_KIND = "_multipart";
+var MULTIPART_ENCODING = "json-utf8-base64url";
+var MULTIPART_VERSION = 1;
+var DEFAULT_MULTIPART_TTL_MS = 6e4;
+var DEFAULT_MULTIPART_MAX_CHUNKS = 128;
+var DEFAULT_MULTIPART_MAX_TOTAL_BYTES = 256e3;
+var REI_AMSG_POSTMESSAGE_TYPE = "REI_AMSG_PUSH";
+var REI_SW_EVENT = Object.freeze({
+  CONTENT_RECEIVED: "rei-amsg-content-received",
+  REASONING_RECEIVED: "rei-amsg-reasoning-received",
+  TOOL_REQUEST_RECEIVED: "rei-amsg-tool-request-received",
+  ERROR_RECEIVED: "rei-amsg-error-received",
+  MULTIPART_EXPIRED: "rei-amsg-multipart-expired",
+  UNKNOWN_RECEIVED: "rei-amsg-unknown-received"
+});
+var REI_SW_MESSAGE_TYPE = Object.freeze({
+  ENQUEUE_REQUEST: "REI_ENQUEUE_REQUEST",
+  DELIVER: "REI_AMSG_DELIVER",
+  FLUSH_QUEUE: "REI_FLUSH_QUEUE",
+  QUEUE_RESULT: "REI_QUEUE_RESULT"
+});
+var REI_AMSG_DELIVER_MESSAGE_TYPE = REI_SW_MESSAGE_TYPE.DELIVER;
+
+// src/index.js
 var MESSAGE_KIND = Object.freeze({
   CONTENT: "content",
   REASONING: "reasoning",
@@ -248,32 +761,6 @@ function chunkReasoningByUtf8Bytes(text, maxBytes) {
   }
   return chunks;
 }
-function toUint8(buf) {
-  if (buf instanceof Uint8Array) return buf;
-  if (buf instanceof ArrayBuffer) return new Uint8Array(buf);
-  if (ArrayBuffer.isView(buf)) return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-  throw new TypeError("Expected ArrayBuffer / Uint8Array");
-}
-function base64UrlToBytes(input) {
-  const s = String(input).replace(/-/g, "+").replace(/_/g, "/");
-  const pad = (4 - s.length % 4) % 4;
-  const padded = s + "=".repeat(pad);
-  const bin = typeof atob === "function" ? atob(padded) : Buffer.from(padded, "base64").toString("binary");
-  const out = new Uint8Array(bin.length);
-  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
-  return out;
-}
-function concatBytes(...chunks) {
-  let total = 0;
-  for (const c of chunks) total += c.byteLength;
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const c of chunks) {
-    out.set(c instanceof Uint8Array ? c : new Uint8Array(c.buffer || c), offset);
-    offset += c.byteLength;
-  }
-  return out;
-}
 function isValidUrl(value) {
   if (typeof value !== "string") return false;
   try {
@@ -345,7 +832,8 @@ function buildSessionContext({
   contactName,
   avatarUrl,
   charId,
-  metadata
+  metadata,
+  scratch
 }) {
   const llmOutputText = readLlmOutputText(llmResponse);
   const ctx = {
@@ -359,6 +847,7 @@ function buildSessionContext({
     contactName,
     avatarUrl: avatarUrl || void 0
   };
+  if (scratch !== void 0) ctx.scratch = scratch;
   return Object.freeze(ctx);
 }
 function readLlmOutputText(llmResponse) {

package/dist/index.d.cts

@@ -231,22 +231,6 @@ export function isErrorPush(value: unknown): value is ErrorPush;
  * @returns {string[]}
  */
 export function chunkReasoningByUtf8Bytes(text: string, maxBytes: number): string[];
-/**
- * Coerce ArrayBuffer | Uint8Array | view → Uint8Array (no copy when possible).
- */
-export function toUint8(buf: any): Uint8Array<ArrayBufferLike>;
-/**
- * Decode base64url (with or without padding) → Uint8Array.
- * @param {string} input
- * @returns {Uint8Array}
- */
-export function base64UrlToBytes(input: string): Uint8Array;
-/**
- * Concatenate Uint8Arrays into a single Uint8Array.
- * @param {...(Uint8Array | ArrayBuffer | ArrayBufferView)} chunks
- * @returns {Uint8Array}
- */
-export function concatBytes(...chunks: (Uint8Array | ArrayBuffer | ArrayBufferView)[]): Uint8Array;
 /**
  * True when `value` parses as an absolute URL.
  * @param {unknown} value
@@ -316,6 +300,7 @@ export function stripReasoningTags(content: string): string;
  * @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.
@@ -335,9 +320,10 @@ export function stripReasoningTags(content: string): string;
  * @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, }: {
+export function buildSessionContext({ sessionId, messages, llmResponse, iteration, contactName, avatarUrl, charId, metadata, scratch, }: {
     sessionId: string;
     messages: ChatMessage[];
     llmResponse: unknown;
@@ -346,6 +332,7 @@ export function buildSessionContext({ sessionId, messages, llmResponse, iteratio
     avatarUrl?: string;
     charId?: string;
     metadata?: Record<string, unknown>;
+    scratch?: Record<string, unknown>;
 }): SessionContext;
 /**
  * Extract the `choices[0].message` whole object — preserving `tool_calls`
@@ -687,6 +674,10 @@ export type SessionContext = {
     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.
@@ -703,3 +694,8 @@ export type MessageType = "instant" | "fixed" | "prompted" | "auto";
  * add values.
  */
 export type PushSource = "instant" | "scheduled";
+export { toUint8, concatBytes, utf8, utf8Decode, bytesToBase64, bytesToBase64Url, base64UrlToBytes, jsonToBase64Url, bytesToHex, hexToBytes, hmacSha256, timingSafeEqualBytes, randomBytes, randomUUID } from "./webcrypto-utils.js";
+export { LLM_MESSAGES_ERROR, validateLlmMessagesShape } from "./llm-messages.js";
+export { callLlm, buildLlmRequestBody, normalizeAiApiUrl } from "./llm-call.js";
+export { sendWebPush, buildVapidJwt, verifyVapidJwt } from "./webpush.js";
+export { MULTIPART_MESSAGE_KIND, MULTIPART_ENCODING, MULTIPART_VERSION, DEFAULT_MULTIPART_TTL_MS, DEFAULT_MULTIPART_MAX_CHUNKS, DEFAULT_MULTIPART_MAX_TOTAL_BYTES, REI_AMSG_POSTMESSAGE_TYPE, REI_SW_EVENT, REI_SW_MESSAGE_TYPE, REI_AMSG_DELIVER_MESSAGE_TYPE } from "./protocol.js";