@fias/arche-sdk 2.21.0 → 2.23.0

package/dist/index.mjs

@@ -114,19 +114,137 @@ function installSandboxDialogShims(win = typeof window === "undefined" ? void 0
   }
 }
 
+// src/invocation-params.ts
+var ENTITY_INVOCATION_HISTORY_LIMITS = {
+  maxTurns: 40,
+  maxTurnChars: 1e5,
+  maxTotalChars: 15e4
+};
+var ENTITY_INVOCATION_REQUEST_LIMITS = {
+  textBytes: 256 * 1024,
+  visionBytes: 1536 * 1024,
+  envelopeBytes: 1024
+};
+function serializedBytes(value) {
+  return new TextEncoder().encode(JSON.stringify(value)).length;
+}
+function carriesImages(params) {
+  return Array.isArray(params.images) && params.images.length > 0;
+}
+function invocationPayloadByteLimit(params) {
+  const { textBytes, visionBytes, envelopeBytes } = ENTITY_INVOCATION_REQUEST_LIMITS;
+  return (carriesImages(params) ? visionBytes : textBytes) - envelopeBytes;
+}
+function checkInvocationRequestSize(payload) {
+  const bytes = serializedBytes(payload);
+  const limit = invocationPayloadByteLimit(payload);
+  if (bytes > limit) {
+    return {
+      ok: false,
+      message: `The request is ${bytes} bytes; ${carriesImages(payload) ? "a call with images" : "a call without images"} may be at most ${limit}. Send less history (fitHistoryToLimits with { request }) or a shorter input.`
+    };
+  }
+  return { ok: true, value: bytes };
+}
+var REASONING_EFFORTS = ["off", "low", "medium", "high"];
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function checkInvocationHistory(value) {
+  if (value === void 0) return { ok: true, value: void 0 };
+  const { maxTurns, maxTurnChars, maxTotalChars } = ENTITY_INVOCATION_HISTORY_LIMITS;
+  if (!Array.isArray(value)) return { ok: false, message: "history: must be an array" };
+  if (value.length > maxTurns) {
+    return { ok: false, message: `history: at most ${maxTurns} turns` };
+  }
+  let total = 0;
+  for (let i = 0; i < value.length; i++) {
+    const turn = value[i];
+    if (!isPlainObject(turn)) return { ok: false, message: `history.${i}: must be an object` };
+    const extra = Object.keys(turn).filter((k) => k !== "role" && k !== "content");
+    if (extra.length > 0) {
+      return { ok: false, message: `history.${i}: unknown field "${extra[0]}"` };
+    }
+    if (turn.role !== "user" && turn.role !== "assistant") {
+      return { ok: false, message: `history.${i}.role: must be "user" or "assistant"` };
+    }
+    if (typeof turn.content !== "string") {
+      return { ok: false, message: `history.${i}.content: must be a string` };
+    }
+    if (turn.content.length > maxTurnChars) {
+      return { ok: false, message: `history.${i}.content: at most ${maxTurnChars} characters` };
+    }
+    total += turn.content.length;
+  }
+  if (total > maxTotalChars) {
+    return { ok: false, message: `history: at most ${maxTotalChars} characters in total` };
+  }
+  return { ok: true, value };
+}
+function checkReasoningParameter(value) {
+  if (value === void 0) return { ok: true, value: void 0 };
+  if (!isPlainObject(value))
+    return { ok: false, message: "parameters.reasoning: must be an object" };
+  const extra = Object.keys(value).filter((k) => k !== "effort" && k !== "includeThinking");
+  if (extra.length > 0) {
+    return { ok: false, message: `parameters.reasoning: unknown field "${extra[0]}"` };
+  }
+  if (!REASONING_EFFORTS.includes(value.effort)) {
+    return {
+      ok: false,
+      message: `parameters.reasoning.effort: must be one of ${REASONING_EFFORTS.join(", ")}`
+    };
+  }
+  if (value.includeThinking !== void 0 && typeof value.includeThinking !== "boolean") {
+    return { ok: false, message: "parameters.reasoning.includeThinking: must be a boolean" };
+  }
+  return {
+    ok: true,
+    value: {
+      effort: value.effort,
+      includeThinking: value.includeThinking === true
+    }
+  };
+}
+function fitHistoryToLimits(turns, options = {}) {
+  const limits = ENTITY_INVOCATION_HISTORY_LIMITS;
+  const maxTurns = Math.min(options.maxTurns ?? limits.maxTurns, limits.maxTurns);
+  const request = options.request ?? {};
+  let bytesLeft = invocationPayloadByteLimit(request) - serializedBytes({ ...request, stream: true, history: [] });
+  const kept = [];
+  let total = 0;
+  for (let i = turns.length - 1; i >= 0 && kept.length < maxTurns; i--) {
+    const turn = turns[i];
+    const content = turn.content.length > limits.maxTurnChars ? turn.content.slice(turn.content.length - limits.maxTurnChars) : turn.content;
+    if (total + content.length > limits.maxTotalChars) break;
+    const bytes = serializedBytes({ role: turn.role, content }) + (kept.length > 0 ? 1 : 0);
+    if (bytes > bytesLeft) break;
+    bytesLeft -= bytes;
+    total += content.length;
+    kept.push({ role: turn.role, content });
+  }
+  return kept.reverse();
+}
+
 // src/bridge.ts
 var messageCounter = 0;
 function generateMessageId() {
   return `msg_${Date.now()}_${++messageCounter}`;
 }
 var FiasBridgeError = class extends Error {
-  constructor(message, code) {
+  constructor(message, code, requestId) {
     super(message);
     this.name = "FiasBridgeError";
     this.code = code;
+    if (requestId) this.requestId = requestId;
   }
   toJSON() {
-    return { name: "FiasBridgeError", code: this.code, message: this.message };
+    return {
+      name: "FiasBridgeError",
+      code: this.code,
+      message: this.message,
+      ...this.requestId ? { requestId: this.requestId } : {}
+    };
   }
 };
 function mergeThemeWithDefaults(incoming) {
@@ -141,6 +259,8 @@ function mergeThemeWithDefaults(incoming) {
   };
 }
 var DEFAULT_TIMEOUT_MS = 3e4;
+var STREAM_IDLE_TIMEOUT_MS = 12e4;
+var STREAM_MAX_DURATION_MS = 15 * 6e4;
 var FiasBridge = class {
   constructor() {
     this.pendingRequests = /* @__PURE__ */ new Map();
@@ -151,6 +271,8 @@ var FiasBridge = class {
     this.permissions = [];
     this.theme = null;
     this.vendoredAssets = null;
+    this.textModels = null;
+    this.textModelListeners = /* @__PURE__ */ new Set();
     this.currentPath = "";
     this.hostOrigin = "";
     this.themeListeners = /* @__PURE__ */ new Set();
@@ -204,6 +326,7 @@ var FiasBridge = class {
         this.permissions = initMsg.payload.permissions;
         this.theme = mergeThemeWithDefaults(initMsg.payload.theme);
         this.vendoredAssets = initMsg.payload.vendoredAssets ?? null;
+        this.textModels = initMsg.payload.textModels ?? null;
         this.currentPath = initMsg.payload.currentPath;
         this.initialized = true;
         this.initResolve?.();
@@ -220,6 +343,15 @@ var FiasBridge = class {
         }
         return;
       }
+      if (data.type === "text_models_update") {
+        if (Array.isArray(data.payload)) {
+          this.textModels = data.payload;
+          for (const listener of this.textModelListeners) {
+            listener(this.textModels);
+          }
+        }
+        return;
+      }
       if (data.type === "navigate_update") {
         this.currentPath = data.payload;
         for (const listener of this.navigationListeners) {
@@ -254,10 +386,15 @@ var FiasBridge = class {
         return;
       }
       if (data.type === "stream_token") {
-        const { messageId, text } = data;
+        const { messageId, text, channel } = data;
         const pending = this.pendingRequests.get(messageId);
-        if (pending?.onToken && typeof text === "string") {
-          pending.onToken(text);
+        if (!pending) return;
+        pending.onActivity?.();
+        if (typeof text !== "string" || channel === "keepalive") return;
+        if (channel === "thinking") {
+          pending.onThinking?.(text);
+        } else {
+          pending.onToken?.(text);
         }
         return;
       }
@@ -326,12 +463,14 @@ var FiasBridge = class {
         const pending = this.pendingRequests.get(response.messageId);
         if (!pending) return;
         clearTimeout(pending.timer);
+        pending.cleanup?.();
         this.pendingRequests.delete(response.messageId);
         if (response.error) {
           pending.reject(
             new FiasBridgeError(
               response.error || "Bridge request failed",
-              response.errorCode ?? "BRIDGE_ERROR"
+              response.errorCode ?? "BRIDGE_ERROR",
+              response.errorRequestId
             )
           );
         } else {
@@ -447,6 +586,17 @@ var FiasBridge = class {
   getCurrentPath() {
     return this.currentPath;
   }
+  /**
+   * The live text-model catalog, or null until the host has delivered it (or
+   * when the plugin lacks `entities:invoke`). See `useTextModels`.
+   */
+  getTextModels() {
+    return this.textModels;
+  }
+  onTextModelsUpdate(listener) {
+    this.textModelListeners.add(listener);
+    return () => this.textModelListeners.delete(listener);
+  }
   onThemeUpdate(listener) {
     this.themeListeners.add(listener);
     return () => this.themeListeners.delete(listener);
@@ -500,21 +650,62 @@ var FiasBridge = class {
    * resolves with the final EntityInvocationResult when the host sends the
    * normal response message.
    */
-  async requestStream(payload, onToken) {
+  async requestStream(payload, callbacks) {
+    const { onToken, onThinking, signal } = typeof callbacks === "function" ? { onToken: callbacks } : callbacks;
     await this.waitForInit();
+    const outbound = { ...payload, stream: true };
+    const size = checkInvocationRequestSize(outbound);
+    if (!size.ok) {
+      throw new FiasBridgeError(size.message, "REQUEST_TOO_LARGE");
+    }
     return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(new FiasBridgeError("Stream aborted before it started", "ABORTED"));
+        return;
+      }
       const messageId = generateMessageId();
-      const timer = setTimeout(() => {
+      const fail = (error) => {
+        const pending2 = this.pendingRequests.get(messageId);
+        if (!pending2) return;
+        clearTimeout(pending2.timer);
+        pending2.cleanup?.();
         this.pendingRequests.delete(messageId);
-        reject(new FiasBridgeError("Bridge streaming request timed out: entity_invoke", "TIMEOUT"));
-      }, 12e4);
-      this.pendingRequests.set(messageId, {
+        reject(error);
+      };
+      const idleTimer = () => setTimeout(
+        () => fail(
+          new FiasBridgeError("Bridge streaming request timed out: entity_invoke", "TIMEOUT")
+        ),
+        STREAM_IDLE_TIMEOUT_MS
+      );
+      const maxTimer = setTimeout(
+        () => fail(
+          new FiasBridgeError(
+            "Bridge streaming request exceeded its maximum duration: entity_invoke",
+            "TIMEOUT"
+          )
+        ),
+        STREAM_MAX_DURATION_MS
+      );
+      const onAbort = () => fail(new FiasBridgeError("Stream aborted", "ABORTED"));
+      signal?.addEventListener("abort", onAbort, { once: true });
+      const pending = {
         resolve,
         reject,
-        timer,
-        onToken
-      });
-      this.send("entity_invoke", { ...payload, stream: true }, messageId);
+        timer: idleTimer(),
+        onToken,
+        onThinking,
+        onActivity: () => {
+          clearTimeout(pending.timer);
+          pending.timer = idleTimer();
+        },
+        cleanup: () => {
+          clearTimeout(maxTimer);
+          signal?.removeEventListener("abort", onAbort);
+        }
+      };
+      this.pendingRequests.set(messageId, pending);
+      this.send("entity_invoke", outbound, messageId);
     });
   }
   /**
@@ -528,10 +719,12 @@ var FiasBridge = class {
     }
     for (const pending of this.pendingRequests.values()) {
       clearTimeout(pending.timer);
+      pending.cleanup?.();
       pending.reject(new FiasBridgeError("Bridge destroyed", "BRIDGE_DESTROYED"));
     }
     this.pendingRequests.clear();
     this.themeListeners.clear();
+    this.textModelListeners.clear();
     this.navigationListeners.clear();
     this.stepNavigationListeners.clear();
     this.previewStateProviders.clear();
@@ -877,6 +1070,7 @@ var VAULT_USER_DOCUMENTS_ENTITY_ID = "ent_intg_vault_documents_0000000";
 var VAULT_ARCHE_DOCUMENTS_ENTITY_ID = "ent_intg_vault_arche_docs_000000";
 var COMMUNITY_ASSETS_ENTITY_ID = "ent_intg_community_assets_000000";
 var DOCUMENT_SIGN_ENTITY_ID = "ent_intg_document_sign_000000000";
+var COMPANY_EMAIL_SEND_ENTITY_ID = "ent_intg_company_email_send_0000";
 var COMMUNITY_ASSET_MAX_URL_BATCH = 50;
 var COMMUNITY_ASSET_MAX_PUBLISH_BATCH = 20;
 async function invokeEntityOp(bridge, entityId, op, args = {}) {
@@ -1016,34 +1210,54 @@ function useFiasStorage() {
 }
 function useEntityInvocation() {
   const bridge = useBridge();
-  const [isLoading, setIsLoading] = useState2(false);
+  const [inFlight, setInFlight] = useState2(0);
   const [result, setResult] = useState2(null);
   const [error, setError] = useState2(null);
   const [streamingText, setStreamingText] = useState2("");
   const invoke = useCallback(
-    async (params) => {
-      setIsLoading(true);
-      setError(null);
-      setStreamingText("");
+    async (params, options) => {
+      const usesSharedSlots = !options?.onToken;
+      setInFlight((n) => n + 1);
+      if (usesSharedSlots) {
+        setError(null);
+        setStreamingText("");
+      }
       try {
-        const res = await bridge.requestStream(params, (token) => {
-          flushSync(() => {
-            setStreamingText((prev) => prev + token);
-          });
+        const res = await bridge.requestStream(params, {
+          onToken: (token) => {
+            if (options?.onToken) {
+              options.onToken(token);
+              return;
+            }
+            flushSync(() => {
+              setStreamingText((prev) => prev + token);
+            });
+          },
+          onThinking: options?.onThinking,
+          signal: options?.signal
         });
-        setResult(res);
+        if (usesSharedSlots) setResult(res);
         return res;
       } catch (err) {
         const e = err instanceof Error ? err : new Error(String(err));
-        setError(e);
+        if (usesSharedSlots) setError(e);
         throw e;
       } finally {
-        setIsLoading(false);
+        setInFlight((n) => n - 1);
       }
     },
     [bridge]
   );
-  return { invoke, isLoading, result, error, streamingText };
+  return { invoke, isLoading: inFlight > 0, result, error, streamingText };
+}
+function useTextModels() {
+  const bridge = useBridge();
+  const [models, setModels] = useState2(bridge.getTextModels() ?? []);
+  useEffect2(() => {
+    setModels(bridge.getTextModels() ?? []);
+    return bridge.onTextModelsUpdate(setModels);
+  }, [bridge]);
+  return models;
 }
 function useImageGeneration() {
   const bridge = useBridge();
@@ -1237,8 +1451,8 @@ function useFiasNavigation() {
     };
   }, [bridge]);
   const navigateTo = useCallback(
-    (path) => {
-      bridge.request("navigate", { path });
+    (path, opts) => {
+      bridge.request("navigate", { path, ...opts?.replace ? { replace: true } : {} });
     },
     [bridge]
   );
@@ -1968,7 +2182,7 @@ function useVaultDocuments() {
   );
 }
 var SAVE_CONTENT_BODY_LANE_MAX_BYTES = 2e5;
-var BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES = 256 * 1024 - 16 * 1024;
+var BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES = ENTITY_INVOCATION_REQUEST_LIMITS.textBytes - 16 * 1024;
 function fitsBridgeBodyAsJsonText(text, utf8Bytes) {
   if (text.length * 6 <= BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES) return true;
   const escapeOverhead = JSON.stringify(text).length - text.length;
@@ -2336,9 +2550,54 @@ function useVaultUserDocuments() {
     },
     [bridge]
   );
+  const workspace = useMemo2(
+    () => ({
+      list: async (options) => {
+        const res = await invokeEntityOp(
+          bridge,
+          VAULT_USER_DOCUMENTS_ENTITY_ID,
+          "list_workspace_documents",
+          { limit: options?.limit, offset: options?.offset, search: options?.search }
+        );
+        return res.documents;
+      },
+      get: (documentId, options) => invokeEntityOp(
+        bridge,
+        VAULT_USER_DOCUMENTS_ENTITY_ID,
+        "get_workspace_document",
+        { documentId, includeContent: options?.includeContent }
+      ),
+      getDownloadUrl: async (documentId) => {
+        const res = await invokeEntityOp(bridge, VAULT_USER_DOCUMENTS_ENTITY_ID, "get_workspace_document_url", { documentId });
+        return {
+          url: res.url,
+          expiresAt: new Date(res.expiresAt).getTime(),
+          contentType: res.contentType
+        };
+      },
+      getBytes: async (documentId) => {
+        const res = await invokeEntityOp(bridge, VAULT_USER_DOCUMENTS_ENTITY_ID, "get_workspace_document_bytes", { documentId });
+        return {
+          document: res.document,
+          bytes: base64ToBytes(res.bytesBase64),
+          contentType: res.contentType
+        };
+      }
+    }),
+    [bridge]
+  );
   return useMemo2(
-    () => ({ pick, requestEditAccess, saveContent, list, get, getDownloadUrl, getBytes }),
-    [pick, requestEditAccess, saveContent, list, get, getDownloadUrl, getBytes]
+    () => ({
+      pick,
+      requestEditAccess,
+      saveContent,
+      list,
+      get,
+      getDownloadUrl,
+      getBytes,
+      workspace
+    }),
+    [pick, requestEditAccess, saveContent, list, get, getDownloadUrl, getBytes, workspace]
   );
 }
 var COMMUNITY_ASSET_URL_REFRESH_BUFFER_MS = 3e4;
@@ -2398,6 +2657,20 @@ async function fetchCommunityAssetUrls(bridge, assetIds) {
   }
   return hits;
 }
+function useCompanyEmail() {
+  const bridge = useBridge();
+  const send = useCallback(
+    async (params) => {
+      const res = await bridge.request("entity_invoke", {
+        entityId: COMPANY_EMAIL_SEND_ENTITY_ID,
+        payload: params
+      });
+      return res.output;
+    },
+    [bridge]
+  );
+  return useMemo2(() => ({ send }), [send]);
+}
 function useCommunityAssets() {
   const bridge = useBridge();
   const publish = useCallback(
@@ -2670,6 +2943,7 @@ var VALID_PLUGIN_PERMISSIONS = [
   "data:store",
   "data:workspace",
   "docsign:envelopes:read",
+  "email:company:send",
   "entities:audio_generate",
   "entities:client_invoke",
   "entities:image_edit",
@@ -2687,7 +2961,8 @@ var VALID_PLUGIN_PERMISSIONS = [
   "vault:documents:write",
   "vault:user-documents:edit",
   "vault:user-documents:read",
-  "vault:user-documents:write"
+  "vault:user-documents:write",
+  "vault:workspace-documents:read"
 ];
 function isValidPluginPermission(perm) {
   return VALID_PLUGIN_PERMISSIONS.includes(perm);
@@ -2701,6 +2976,7 @@ var PLUGIN_PERMISSION_DESCRIPTIONS = {
   "data:store": "Save structured data in this arche's own private database.",
   "data:workspace": "Create team workspaces and manage their members.",
   "docsign:envelopes:read": "Check on signature requests it started for you \u2014 who has signed, and what is still outstanding.",
+  "email:company:send": "Send email as your Company from its own address (e.g. team@yourcompany.com) \u2014 only after a Company admin allows this app to, and only to the people they choose. Each email is charged to the person using the app.",
   "entities:audio_generate": "Generate audio with platform AI \u2014 costs credits.",
   "entities:client_invoke": "Use free on-device tools (grammar check, translation) in your browser.",
   "entities:image_edit": "Edit images with platform AI \u2014 costs credits.",
@@ -2718,7 +2994,8 @@ var PLUGIN_PERMISSION_DESCRIPTIONS = {
   "vault:documents:write": "Create and manage its own files, in its own folder of your Vault.",
   "vault:user-documents:edit": "Save changes to files of yours that you let it edit \u2014 you choose each file, earlier versions are kept unless you turned version history off, and you can remove access any time in Vault \u2192 Arche Access.",
   "vault:user-documents:read": "Read documents YOU choose to share with it from your Vault \u2014 you pick each document, and you can remove access any time in Vault \u2192 Arche Access.",
-  "vault:user-documents:write": "Save its work to your Documents \u2014 you choose the folder and the name each time."
+  "vault:user-documents:write": "Save its work to your Documents \u2014 you choose the folder and the name each time.",
+  "vault:workspace-documents:read": "Read every document you can see in a team workspace \u2014 only after that workspace's owner or admin approves it there, and never files marked proprietary."
 };
 
 // src/fias.ts
@@ -5059,7 +5336,13 @@ function validateAnimation(value, path, issues) {
   }
   rejectUnknownKeys(value, ["type", "durationMs", "easing"], path, issues);
   checkOptionalEnum(value.type, `${path}.type`, issues, ANIMATION_TYPES);
-  checkOptionalIntRange(value.durationMs, `${path}.durationMs`, issues, 0, ANIMATION_MAX_DURATION_MS);
+  checkOptionalIntRange(
+    value.durationMs,
+    `${path}.durationMs`,
+    issues,
+    0,
+    ANIMATION_MAX_DURATION_MS
+  );
   checkOptionalEnum(value.easing, `${path}.easing`, issues, ANIMATION_EASINGS);
 }
 var THEME_COLOR_FIELDS = ["bg", "fg", "border", "accent", "accentFg", "scrim"];
@@ -5201,6 +5484,8 @@ export {
   AUDIO_VOICE_CHANGER_SURFACE_KEY,
   AUDIO_VOICE_DESIGN_SURFACE_KEY,
   DARK_THEME,
+  ENTITY_INVOCATION_HISTORY_LIMITS,
+  ENTITY_INVOCATION_REQUEST_LIMITS,
   FONT_CATALOG,
   FONT_PAIRINGS,
   FiasBridge,
@@ -5240,17 +5525,23 @@ export {
   PANEL_TITLE_MAX_LENGTH,
   PLUGIN_CONTENT_ENTITY_ID,
   PLUGIN_PERMISSION_DESCRIPTIONS,
+  REASONING_EFFORTS,
   SDK_BRIDGE_PROTOCOL_VERSION,
   SDK_REQUIRES_HOST_PROTOCOL_VERSION,
   THEME_CATALOG,
   VALID_PLUGIN_PERMISSIONS,
+  checkInvocationHistory,
+  checkInvocationRequestSize,
+  checkReasoningParameter,
   ensureFontLoaded,
   fetchVaultDocumentDownloadUrl,
   fias,
+  fitHistoryToLimits,
   getBridge,
   getDefaultTheme,
   getFontPairingById,
   getThemeById,
+  invocationPayloadByteLimit,
   isValidPluginPermission,
   resetBridge,
   useArcheAssets,
@@ -5258,6 +5549,7 @@ export {
   useAudioGeneration,
   useClientEntity,
   useCommunityAssets,
+  useCompanyEmail,
   useDataSubscription,
   useDocumentSign,
   useElevenLabsAudioIsolation,
@@ -5299,6 +5591,7 @@ export {
   useSmartVectorize,
   useStepNavigation,
   useSurface,
+  useTextModels,
   useVaultDocuments,
   useVaultUserDocuments,
   validatePanelAction,

package/dist/invocation-params.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Limits and validation for the multi-turn fields of an AI `entity_invoke`:
+ * `history` (prior conversation turns) and `parameters.reasoning`.
+ *
+ * ONE implementation, deliberately placed in the SDK. It is dependency-free, so
+ * it can run in three places that must never disagree:
+ *   - the platform bridges, which reject a malformed call with `INVALID_PARAMS`;
+ *   - the dev harness's MOCK mode, which must reject the same calls offline
+ *     (the harness is published to npm and may only depend on this SDK);
+ *   - plugins, which use `fitHistoryToLimits` to trim a conversation BEFORE
+ *     sending it rather than finding out from a rejected call.
+ */
+import type { EntityInvocationParams, EntityInvocationTurn, ReasoningEffort } from './types';
+/**
+ * Bounds on `EntityInvocationParams.history`, in characters. They are the
+ * validator's rules, not a promise that a call fits: the request must ALSO fit
+ * the bridge's byte limit (`ENTITY_INVOCATION_REQUEST_LIMITS`), and a character
+ * can serialize to up to 4 bytes (CJK 3, emoji 4, a newline or quote 2). Trim
+ * with `fitHistoryToLimits(turns, { request })`, which applies both.
+ */
+export declare const ENTITY_INVOCATION_HISTORY_LIMITS: {
+    readonly maxTurns: 40;
+    readonly maxTurnChars: 100000;
+    readonly maxTotalChars: 150000;
+};
+/**
+ * The platform bridge's request-size ceilings, in bytes of the serialized
+ * (UTF-8 JSON) request. A text-only `entity_invoke` travels on the 256 KB
+ * route; one carrying images on the 1.5 MB vision route. Mirrors the server's
+ * `PLUGIN_BRIDGE_BODY_LIMIT_BYTES` / `PLUGIN_BRIDGE_VISION_BODY_LIMIT_BYTES`
+ * (pinned by `tests/architecture/invocation-params-parity.test.ts`).
+ * `envelopeBytes` is kept free for what the host wraps around the payload.
+ */
+export declare const ENTITY_INVOCATION_REQUEST_LIMITS: {
+    readonly textBytes: number;
+    readonly visionBytes: number;
+    readonly envelopeBytes: 1024;
+};
+/**
+ * The most bytes an `entity_invoke` payload may serialize to: the limit of the
+ * route it will travel on, less the host's envelope.
+ */
+export declare function invocationPayloadByteLimit(params: {
+    images?: unknown;
+}): number;
+/**
+ * Whether an `entity_invoke` payload fits the bridge's request limit. The SDK
+ * checks this before sending, so an oversized call fails with
+ * `REQUEST_TOO_LARGE` instead of an opaque HTTP 413 from the server.
+ */
+export declare function checkInvocationRequestSize(payload: Record<string, unknown>): InvocationParamCheck<number>;
+export declare const REASONING_EFFORTS: readonly ReasoningEffort[];
+export type InvocationParamCheck<T> = {
+    ok: true;
+    value: T | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Validate a `history` value. `undefined` is valid (no history). Roles are
+ * `user` / `assistant` only, so a caller can never inject a second system
+ * message; unknown turn fields are rejected, not dropped.
+ */
+export declare function checkInvocationHistory(value: unknown): InvocationParamCheck<EntityInvocationTurn[]>;
+/**
+ * Validate `parameters.reasoning`. `undefined` is valid (no reasoning request);
+ * `includeThinking` defaults to `false`.
+ */
+export declare function checkReasoningParameter(value: unknown): InvocationParamCheck<{
+    effort: ReasoningEffort;
+    includeThinking: boolean;
+}>;
+/**
+ * The newest suffix of `turns` that fits: the character caps in
+ * `ENTITY_INVOCATION_HISTORY_LIMITS` AND the bridge's byte limit, optionally
+ * capped at `maxTurns` (e.g. a "last 20 messages" window).
+ *
+ * Pass the rest of the call as `request` (input, systemPrompt, images,
+ * parameters — everything but `history`) so the byte budget is what that call
+ * leaves over on the route it will take. Without it the budget assumes the
+ * history is all there is, which a real call can still exceed.
+ *
+ * Older turns are dropped first; a single turn longer than the per-turn cap
+ * keeps its most recent text. Every turn sent is billed as input on every call,
+ * so a smaller window is also cheaper.
+ */
+export declare function fitHistoryToLimits(turns: readonly EntityInvocationTurn[], options?: {
+    maxTurns?: number;
+    request?: Omit<EntityInvocationParams, 'history'>;
+}): EntityInvocationTurn[];
+//# sourceMappingURL=invocation-params.d.ts.map

package/dist/invocation-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-params.d.ts","sourceRoot":"","sources":["../src/invocation-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC;;;;CAInC,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC;;;;CAInC,CAAC;AAWX;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAG/E;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,oBAAoB,CAAC,MAAM,CAAC,CAY9B;AAED,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAAqC,CAAC;AAE9F,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAMnC;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,oBAAoB,CAAC,oBAAoB,EAAE,CAAC,CA8B9C;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,GACb,oBAAoB,CAAC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAAC,CAwB7E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,oBAAoB,EAAE,EACtC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,CAAA;CAAO,GACrF,oBAAoB,EAAE,CA0BxB"}