@gram-ai/elements 1.33.2 → 1.35.0

package/src/hooks/useRadius.ts

@@ -34,7 +34,7 @@ type RadiusSize = "sm" | "md" | "lg" | "xl" | "full";
  * Hook to get radius classes based on theme config
  * Use: const r = useRadius(); then r('lg') returns the appropriate rounded class
  */
-export const useRadius = () => {
+export const useRadius = (): ((size: RadiusSize) => string) => {
   const { config } = useElements();
   const radius = config.theme?.radius ?? "soft";
 

package/src/hooks/useSession.ts

@@ -1,7 +1,9 @@
 import { GetSessionFn } from "@/types";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 
-export function getChatSessionQueryKey(projectSlug: string) {
+export function getChatSessionQueryKey(
+  projectSlug: string,
+): readonly ["chatSession", string] {
   return ["chatSession", projectSlug] as const;
 }
 

package/src/hooks/useThemeProps.ts

@@ -4,13 +4,13 @@ import { useElements } from "./useElements";
 /**
  * Hook to get theme-related props including dark mode class
  */
-export const useThemeProps = () => {
+export const useThemeProps = (): {
+  readonly className: string | undefined;
+} => {
   const { config } = useElements();
-  const theme = config.theme ?? {};
+  const colorScheme = config.theme?.colorScheme ?? "light";
 
   return useMemo(() => {
-    const { colorScheme = "light" } = theme;
-
     const isDark =
       colorScheme === "dark" ||
       (colorScheme === "system" &&
@@ -20,5 +20,5 @@ export const useThemeProps = () => {
     return {
       className: isDark ? "dark" : undefined,
     } as const;
-  }, [theme]);
+  }, [colorScheme]);
 };

package/src/hooks/useToolApproval.ts

@@ -1,11 +1,12 @@
 import { useContext } from "react";
 import { ToolApprovalContext } from "@/contexts/contexts";
+import type { ToolApprovalContextType } from "@/contexts/ToolApprovalContext";
 
 /**
  * Hook to access the tool approval context for managing human-in-the-loop
  * tool execution approval.
  */
-export const useToolApproval = () => {
+export const useToolApproval = (): ToolApprovalContextType => {
   const context = useContext(ToolApprovalContext);
   if (!context) {
     throw new Error(

package/src/index.ts

@@ -56,6 +56,8 @@ export type {
   Dimension,
   Dimensions,
   ElementsConfig,
+  ElementsTransportContext,
+  ElementsTransportFactory,
   ErrorTrackingConfigOption,
   GetSessionFn,
   HistoryConfig,
@@ -80,6 +82,20 @@ export type {
 
 export { MODELS } from "./lib/models";
 
+// Chat-message conversion — for consumers building a custom transport against
+// the Gram chat service (e.g. the dashboard's server-assistant transport).
+export {
+  convertGramMessagesToUIMessages,
+  convertGramMessagesToExported,
+} from "@/lib/messageConverter";
+
+export { sleep } from "@/lib/utils";
+export type {
+  GramChat,
+  GramChatMessage,
+  GramChatOverview,
+} from "@/lib/messageConverter";
+
 export type { Plugin } from "./types/plugins";
 
 // Time Range Picker

package/src/lib/cassette.ts

@@ -10,8 +10,14 @@
  * 3. Pass it to `<Replay cassette={...}>` to play it back
  */
 
-import { createUIMessageStream, type ChatTransport, type UIMessage } from "ai";
+import {
+  createUIMessageStream,
+  type ChatTransport,
+  type UIMessage,
+  type UIMessageStreamWriter,
+} from "ai";
 import type { ThreadMessage } from "@assistant-ui/react";
+import { sleep } from "@/lib/utils";
 
 // ---------------------------------------------------------------------------
 // Cassette types
@@ -94,6 +100,12 @@ export function recordCassette(messages: readonly ThreadMessage[]): Cassette {
           });
           break;
         // Skip image, file, audio, source, data parts for now
+        case "image":
+        case "file":
+        case "audio":
+        case "source":
+        case "data":
+          break;
       }
     }
 
@@ -112,25 +124,6 @@ export function recordCassette(messages: readonly ThreadMessage[]): Cassette {
 // Playback: Cassette → ChatTransport
 // ---------------------------------------------------------------------------
 
-/** Sleep that respects AbortSignal for clean cancellation. */
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new DOMException("Aborted", "AbortError"));
-      return;
-    }
-    const timeout = setTimeout(resolve, ms);
-    signal?.addEventListener(
-      "abort",
-      () => {
-        clearTimeout(timeout);
-        reject(new DOMException("Aborted", "AbortError"));
-      },
-      { once: true },
-    );
-  });
-}
-
 /**
  * Creates a ChatTransport that replays pre-recorded assistant messages
  * from a cassette. Each call to `sendMessages` (triggered by a user message
@@ -153,7 +146,7 @@ export function createReplayTransport(
       // Advance cursor past it (it should be pointing at a user message).
       if (
         cursor < cassette.messages.length &&
-        cassette.messages[cursor].role === "user"
+        cassette.messages[cursor]?.role === "user"
       ) {
         cursor++;
       }
@@ -163,9 +156,10 @@ export function createReplayTransport(
       const assistantMessages: CassetteMessage[] = [];
       while (
         cursor < cassette.messages.length &&
-        cassette.messages[cursor].role === "assistant"
+        cassette.messages[cursor]?.role === "assistant"
       ) {
-        assistantMessages.push(cassette.messages[cursor]);
+        const m = cassette.messages[cursor];
+        if (m) assistantMessages.push(m);
         cursor++;
       }
 
@@ -204,10 +198,10 @@ export function createReplayTransport(
 // Stream writing helpers
 // ---------------------------------------------------------------------------
 
-interface StreamWriter {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  write(part: any): void;
-}
+// Match the `write` shape of `UIMessageStreamWriter<UIMessage>` so callers can
+// pass the writer they receive from `createUIMessageStream` directly. We only
+// rely on `write` here, so this stays narrow on purpose.
+type StreamWriter = Pick<UIMessageStreamWriter<UIMessage>, "write">;
 
 async function writeReplayPart(
   writer: StreamWriter,

package/src/lib/contextCompaction.test.ts

@@ -38,8 +38,8 @@ describe("getModelContextLimit", () => {
     expect(getModelContextLimit("anthropic/claude-sonnet-4.6")).toBe(1_000_000);
   });
 
-  it("returns known mapping for Claude 4 (non-1M)", () => {
-    expect(getModelContextLimit("anthropic/claude-sonnet-4")).toBe(200_000);
+  it("returns known mapping for Claude Sonnet 4", () => {
+    expect(getModelContextLimit("anthropic/claude-sonnet-4")).toBe(1_000_000);
   });
 
   it("returns DEFAULT_CONTEXT_LIMIT for unknown models", () => {

package/src/lib/contextCompaction.ts

@@ -32,39 +32,51 @@ export const DEFAULT_CONTEXT_LIMIT = 200_000;
  */
 const MODEL_CONTEXT_LIMITS: Partial<Record<KnownModelId, number>> = {
   // Anthropic (1M tier where available, else 200K)
+  "anthropic/claude-opus-4.8": 1_000_000,
+  "anthropic/claude-opus-4.7": 1_000_000,
   "anthropic/claude-opus-4.6": 1_000_000,
-  "anthropic/claude-opus-4.5": 1_000_000,
-  "anthropic/claude-opus-4.1": 200_000,
+  "anthropic/claude-opus-4.5": 200_000,
   "anthropic/claude-sonnet-4.6": 1_000_000,
   "anthropic/claude-sonnet-4.5": 1_000_000,
-  "anthropic/claude-sonnet-4": 200_000,
+  "anthropic/claude-sonnet-4": 1_000_000,
   "anthropic/claude-haiku-4.5": 200_000,
 
   // OpenAI
-  "openai/gpt-5.4": 400_000,
+  "openai/gpt-5.5": 1_000_000,
+  "openai/gpt-5.5-pro": 1_000_000,
+  "openai/gpt-5.4": 1_000_000,
   "openai/gpt-5.4-mini": 400_000,
+  "openai/gpt-5.4-nano": 400_000,
+  "openai/gpt-5.3-codex": 400_000,
   "openai/gpt-5.1": 400_000,
-  "openai/gpt-5.1-codex": 400_000,
   "openai/gpt-5": 400_000,
   "openai/gpt-4.1": 1_000_000,
   "openai/o4-mini": 200_000,
   "openai/o3": 200_000,
 
   // Google
+  "google/gemini-3.5-flash": 1_000_000,
   "google/gemini-3.1-pro-preview": 1_000_000,
+  "google/gemini-3.1-flash-lite": 1_000_000,
   "google/gemini-2.5-pro": 1_000_000,
   "google/gemini-2.5-flash": 1_000_000,
 
   // Others
+  "deepseek/deepseek-v4-pro": 1_000_000,
+  "deepseek/deepseek-v4-flash": 1_000_000,
   "deepseek/deepseek-r1": 128_000,
   "deepseek/deepseek-v3.2": 128_000,
   "meta-llama/llama-4-maverick": 1_000_000,
-  "x-ai/grok-4": 256_000,
+  "x-ai/grok-4.3": 1_000_000,
+  "x-ai/grok-4.20": 2_000_000,
+  "qwen/qwen3.7-max": 1_000_000,
   "qwen/qwen3-coder": 256_000,
-  "moonshotai/kimi-k2.5": 128_000,
+  "moonshotai/kimi-k2.6": 256_000,
+  "moonshotai/kimi-k2.5": 256_000,
+  "mistralai/mistral-medium-3-5": 256_000,
   "mistralai/mistral-medium-3.1": 128_000,
   "mistralai/codestral-2508": 256_000,
-  "mistralai/devstral-small": 128_000,
+  "mistralai/devstral-2512": 256_000,
 };
 
 /**

package/src/lib/errorTracking.ts

@@ -75,10 +75,7 @@ export function initErrorTracking(config: ErrorTrackingConfig = {}): void {
  * Track an error to Datadog RUM.
  * Includes context about where the error originated.
  */
-export function trackError(
-  error: Error | unknown,
-  context: ErrorContext,
-): void {
+export function trackError(error: unknown, context: ErrorContext): void {
   if (!enabled || !initialized) {
     return;
   }

package/src/lib/messageConverter.test.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { describe, expect, it } from "vitest";
 import {
   convertGramMessagesToExported,
@@ -6,6 +5,7 @@ import {
   convertGramMessagePartsToUIMessageParts,
   type GramChatMessage,
 } from "./messageConverter";
+import type { ToolCallMessagePart } from "@assistant-ui/react";
 
 /**
  * Helper to create a minimal GramChatMessage for testing.
@@ -41,10 +41,7 @@ describe("convertGramMessagePartsToUIMessageParts", () => {
       tool_calls: makeToolCallsJSON([{ id: "tc_1", name: "search_deals" }]),
     } as Partial<GramChatMessage> & { role: string });
 
-    const parts = convertGramMessagePartsToUIMessageParts(
-      msg as any,
-      new Map(),
-    );
+    const parts = convertGramMessagePartsToUIMessageParts(msg, new Map());
 
     const toolParts = parts.filter((p) => p.type === "dynamic-tool");
     expect(toolParts).toHaveLength(1);
@@ -66,11 +63,7 @@ describe("convertGramMessagePartsToUIMessageParts", () => {
       ]),
     } as Partial<GramChatMessage> & { role: string });
 
-    const parts = convertGramMessagePartsToUIMessageParts(
-      msg as any,
-      new Map(),
-      seen,
-    );
+    const parts = convertGramMessagePartsToUIMessageParts(msg, new Map(), seen);
 
     const toolParts = parts.filter((p) => p.type === "dynamic-tool");
     expect(toolParts).toHaveLength(1);
@@ -230,10 +223,15 @@ describe("convertGramMessagesToExported - string content with tool calls", () =>
 
     const result = convertGramMessagesToExported(messages);
     const assistantEntry = result.messages.find(
-      (m) => m.message.role === "assistant",
+      (m): m is typeof m & { message: { role: "assistant" } } =>
+        m.message.role === "assistant",
     )!;
-    const toolCallParts = (assistantEntry.message as any).content.filter(
-      (p: any) => p.type === "tool-call",
+    const assistantMessage = assistantEntry.message;
+    if (assistantMessage.role !== "assistant") {
+      throw new Error("expected assistant message");
+    }
+    const toolCallParts = assistantMessage.content.filter(
+      (p): p is ToolCallMessagePart => p.type === "tool-call",
     );
     expect(toolCallParts).toHaveLength(1);
     expect(toolCallParts[0]).toMatchObject({

package/src/lib/messageConverter.ts

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
 /**
  * Message format converter for Gram API <-> assistant-ui.
  *
@@ -19,23 +17,69 @@ import type {
   ThreadAssistantMessagePart,
   TextMessagePart,
 } from "@assistant-ui/react";
-import type {
-  Message,
-  UserMessage,
-  AssistantMessage,
-  ToolResponseMessage,
-} from "@openrouter/sdk/models";
 import { UIMessage } from "ai";
 
 /**
- * Represents a chat message from the Gram API.
- * This mirrors the ChatMessage type from @gram/sdk without requiring the SDK dependency.
+ * A single text part of a multi-modal chat message.
+ */
+export interface GramChatTextPart {
+  type: "text";
+  text: string;
+}
+
+/**
+ * A single image part of a multi-modal chat message. The wire shape mirrors the
+ * upstream OpenAI/OpenRouter chat schema (`image_url.url`) so the converter can
+ * read it without normalisation.
+ */
+export interface GramChatImagePart {
+  type: "image_url";
+  image_url?: { url?: string };
+}
+
+/**
+ * A single audio part of a multi-modal chat message. Mirrors the OpenAI/OpenRouter
+ * `input_audio.{data, format}` shape on the wire.
+ */
+export interface GramChatAudioPart {
+  type: "input_audio";
+  input_audio?: { data?: string; format?: string };
+}
+
+/**
+ * Content part of a multi-modal chat message.
  */
-export type GramChatMessage = Message & {
+export type GramChatContentPart =
+  | GramChatTextPart
+  | GramChatImagePart
+  | GramChatAudioPart;
+
+/**
+ * Content of a chat message — either a plain string or an array of parts for
+ * multi-modal messages.
+ */
+export type GramChatContent = string | GramChatContentPart[];
+
+/**
+ * Represents a chat message from the Gram API. Only fields actually surfaced
+ * through Elements' public converters are modelled; provider-specific extras
+ * remain on the wire shape but are intentionally not part of the contract.
+ *
+ * `tool_calls` is the JSON-encoded string the Gram chat service stores on
+ * assistant rows; `tool_call_id` is the id the corresponding tool-response row
+ * carries when `role === "tool"`.
+ */
+export interface GramChatMessage {
   id: string;
   model: string;
   created_at: Date | string;
-};
+  role: "system" | "developer" | "user" | "assistant" | "tool";
+  content?: GramChatContent | null;
+  name?: string;
+  tool_calls?: string;
+  tool_call_id?: string;
+  reasoning?: string | null;
+}
 
 /**
  * Represents a chat from the Gram API.
@@ -96,29 +140,23 @@ function buildUserContentParts(msg: GramChatMessage): ThreadUserMessagePart[] {
           text: item.text,
         });
         break;
-      case "image_url":
+      case "image_url": {
+        const url = item.image_url?.url ?? "";
         parts.push({
           type: "image",
-          image: (item as any).image_url?.url as FIXME<
-            string,
-            "Fixed by switching to Gram TS SDK."
-          >,
+          image: url,
         });
         break;
+      }
       case "input_audio": {
-        const format = (item as any).input_audio?.format as FIXME<
-          string,
-          "Fixed by switching to Gram TS SDK."
-        >;
-        if (format === "mp3" || format === "wav") {
+        const format = item.input_audio?.format;
+        const data = item.input_audio?.data;
+        if ((format === "mp3" || format === "wav") && data) {
           parts.push({
             type: "audio",
             audio: {
-              data: (item as any).input_audio.data as FIXME<
-                string,
-                "Fixed by switching to Gram TS SDK."
-              >,
-              format: format,
+              data,
+              format,
             },
           });
         }
@@ -155,12 +193,18 @@ function buildAssistantContentParts(
     });
   }
 
-  const toolCallsJSON = (msg as any).tool_calls as FIXME<
-    string | undefined,
-    "Fixed by switching to Gram TS SDK."
-  >;
+  // Accept both the OpenAI/OpenRouter shape (`{ id, function: { name, arguments } }`)
+  // and the assistant-ui shape (`{ toolCallId, toolName, args }`). Tool calls
+  // arrive as JSON the server stored opaquely, so we model the union here.
+  type WireToolCall = {
+    id?: string;
+    toolCallId?: string;
+    function?: { name?: string; arguments?: string | Record<string, unknown> };
+    toolName?: string;
+    args?: string | Record<string, unknown>;
+  };
 
-  let toolCalls = tryParseJSON(toolCallsJSON || "[]");
+  let toolCalls = tryParseJSON<WireToolCall[]>(msg.tool_calls || "[]");
   if (!Array.isArray(toolCalls)) {
     console.warn("Invalid tool_calls format, expected an array.");
     toolCalls = [];
@@ -280,8 +324,10 @@ function convertGramMessageToThreadMessage(
  * Converts an array of Gram ChatMessages to an ExportedMessageRepository.
  * Creates parent-child relationships based on message order.
  *
- * Note: System messages are filtered out because assistant-ui's
- * `fromThreadMessageLike` doesn't support them in the exported format.
+ * Note: system, developer, and tool messages are filtered out. assistant-ui's
+ * exported format only models user/assistant turns; system/developer rows are
+ * pre-prompt instructions the UI doesn't render, and tool rows are folded into
+ * the preceding assistant message as `tool-call` parts via `tool_calls`.
  */
 export function convertGramMessagesToExported(
   messages: GramChatMessage[],
@@ -294,8 +340,11 @@ export function convertGramMessagesToExported(
   let prevId: string | null = null;
 
   for (const msg of messages) {
-    // Skip system messages - they're not supported in the exported message format
-    if (msg.role === "system") {
+    if (
+      msg.role === "system" ||
+      msg.role === "developer" ||
+      msg.role === "tool"
+    ) {
       continue;
     }
 
@@ -322,17 +371,17 @@ export function convertGramMessagesToUIMessages(messages: GramChatMessage[]): {
     return { messages: [], headId: null };
   }
 
-  const toolCallResults = new Map<string, ToolResponseMessage>();
+  const toolCallResults = new Map<string, GramChatMessage>();
   for (const msg of messages) {
     if (msg.role !== "tool") {
       continue;
     }
-    const id = (msg as any).tool_call_id;
+    const id = msg.tool_call_id;
     if (typeof id !== "string") {
       continue;
     }
 
-    toolCallResults.set(id, msg as ToolResponseMessage);
+    toolCallResults.set(id, msg);
   }
 
   const uiMessages: { parentId: string | null; message: UIMessage }[] = [];
@@ -415,9 +464,19 @@ export function convertGramMessagesToUIMessages(messages: GramChatMessage[]): {
   };
 }
 
+/**
+ * Parsed shape of a single entry inside an assistant message's `tool_calls`
+ * JSON string. Mirrors the OpenAI/OpenRouter tool-call wire format.
+ */
+interface GramToolCall {
+  id: string;
+  type?: "function";
+  function?: { name?: string; arguments?: string | Record<string, unknown> };
+}
+
 export function convertGramMessagePartsToUIMessageParts(
-  msg: UserMessage | AssistantMessage,
-  toolResults: Map<string, ToolResponseMessage>,
+  msg: GramChatMessage,
+  toolResults: Map<string, GramChatMessage>,
   seenToolCallIds?: Set<string>,
 ): UIMessage["parts"] {
   const uiparts: UIMessage["parts"] = [];
@@ -440,10 +499,7 @@ export function convertGramMessagePartsToUIMessageParts(
         break;
       }
       case "image_url": {
-        const url = (p as any).image_url?.url as FIXME<
-          string | undefined,
-          "Fixed by switching to Gram TS SDK."
-        >;
+        const url = p.image_url?.url;
         if (!url) {
           break;
         }
@@ -456,10 +512,7 @@ export function convertGramMessagePartsToUIMessageParts(
         break;
       }
       case "input_audio": {
-        const url = (p as any).input_audio?.data as FIXME<
-          string | undefined,
-          "Fixed by switching to Gram TS SDK."
-        >;
+        const url = p.input_audio?.data;
         if (!url) {
           break;
         }
@@ -481,14 +534,8 @@ export function convertGramMessagePartsToUIMessageParts(
     });
   }
 
-  if (msg.role === "assistant" && (msg as any).tool_calls) {
-    const toolCallsJSON = (msg as any).tool_calls as FIXME<
-      string,
-      "Fixed by switching to Gram TS SDK."
-    >;
-    let toolCalls = tryParseJSON<AssistantMessage["toolCalls"]>(
-      toolCallsJSON || "[]",
-    );
+  if (msg.role === "assistant" && msg.tool_calls) {
+    let toolCalls = tryParseJSON<GramToolCall[]>(msg.tool_calls || "[]");
     if (!Array.isArray(toolCalls)) {
       console.warn("Invalid tool_calls format, expected an array.");
       toolCalls = [];
@@ -526,7 +573,7 @@ function mediaTypeFromURL(url: string): string {
   return match?.[1] || unspecified;
 }
 
-function tryParseJSON<T = any>(str: string): T | null {
+function tryParseJSON<T = unknown>(str: string): T | null {
   try {
     return JSON.parse(str) as T;
   } catch {

package/src/lib/models.ts

@@ -1,31 +1,43 @@
 // List of openrouter models available to the user
 // This list should be updated to match the model whitelist on the backend side.
 export const MODELS = [
-  "anthropic/claude-opus-4.6",
+  "anthropic/claude-opus-4.8",
+  "anthropic/claude-opus-4.7",
   "anthropic/claude-sonnet-4.6",
   "anthropic/claude-sonnet-4.5",
+  "anthropic/claude-opus-4.6",
   "anthropic/claude-opus-4.5",
   "anthropic/claude-haiku-4.5",
-  "anthropic/claude-opus-4.1",
   "anthropic/claude-sonnet-4",
+  "openai/gpt-5.5",
+  "openai/gpt-5.5-pro",
   "openai/gpt-5.4",
   "openai/gpt-5.4-mini",
+  "openai/gpt-5.4-nano",
+  "openai/gpt-5.3-codex",
   "openai/gpt-5.1",
-  "openai/gpt-5.1-codex",
   "openai/gpt-5",
   "openai/gpt-4.1",
   "openai/o4-mini",
   "openai/o3",
+  "google/gemini-3.5-flash",
   "google/gemini-3.1-pro-preview",
+  "google/gemini-3.1-flash-lite",
   "google/gemini-2.5-pro",
   "google/gemini-2.5-flash",
-  "deepseek/deepseek-r1",
+  "deepseek/deepseek-v4-pro",
+  "deepseek/deepseek-v4-flash",
   "deepseek/deepseek-v3.2",
+  "deepseek/deepseek-r1",
   "meta-llama/llama-4-maverick",
-  "x-ai/grok-4",
+  "x-ai/grok-4.3",
+  "x-ai/grok-4.20",
+  "qwen/qwen3.7-max",
   "qwen/qwen3-coder",
+  "moonshotai/kimi-k2.6",
   "moonshotai/kimi-k2.5",
-  "mistralai/mistral-medium-3.1",
+  "mistralai/mistral-medium-3-5",
   "mistralai/codestral-2508",
-  "mistralai/devstral-small",
+  "mistralai/devstral-2512",
+  "mistralai/mistral-medium-3.1",
 ] as const;

package/src/lib/token.ts

@@ -9,7 +9,7 @@ export function getTokenExpiry(token: string): number | null {
     if (parts.length !== 3) return null;
 
     // base64url → base64 → decode
-    let payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    let payload = parts[1]!.replace(/-/g, "+").replace(/_/g, "/");
     while (payload.length % 4) payload += "=";
 
     const json = atob(payload);
@@ -29,10 +29,7 @@ export function getTokenExpiry(token: string): number | null {
  * of expiry. Fails open (returns false) for non-JWT tokens or tokens
  * without an `exp` claim so they pass through unchanged.
  */
-export function isTokenExpired(
-  token: string,
-  bufferMs: number = 30_000,
-): boolean {
+export function isTokenExpired(token: string, bufferMs = 30_000): boolean {
   const exp = getTokenExpiry(token);
   if (exp === null) return false; // fail-open for non-JWT tokens
   return Date.now() >= exp * 1000 - bufferMs;