lumiverse-spindle-types 0.4.28 → 0.4.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.4.28",
+  "version": "0.4.30",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -1029,6 +1029,46 @@ export interface GenerationObserver {
   dispose(): void;
 }
 
+// ─── Token Count DTOs ───────────────────────────────────────────────────
+
+/** Where the model used for server-side token counting came from. */
+export type TokenModelSourceDTO = "main" | "sidecar" | "explicit";
+
+/** Optional settings for Spindle token count helpers. */
+export interface TokenCountOptionsDTO {
+  /**
+   * Explicit model ID to resolve the tokenizer against.
+   *
+   * When provided, this takes precedence over `modelSource`.
+   */
+  model?: string;
+  /**
+   * Which configured model to use when resolving the tokenizer.
+   *
+    * - `"main"`    → the user's default main connection profile model
+    * - `"sidecar"` → the user's selected sidecar model (or its backing connection model)
+   *
+   * Defaults to `"main"`.
+   */
+  modelSource?: TokenModelSourceDTO;
+  /** For operator-scoped extensions. */
+  userId?: string;
+}
+
+/** Server-resolved token count result for a text or chat payload. */
+export interface TokenCountResultDTO {
+  total_tokens: number;
+  /** Model ID that was actually used to resolve the tokenizer. */
+  model: string;
+  /** Whether the model came from the main connection, sidecar selection, or an explicit override. */
+  modelSource: TokenModelSourceDTO;
+  /** Null when no exact tokenizer match was found and an approximate fallback was used. */
+  tokenizer_id: string | null;
+  tokenizer_name: string;
+  /** True when Lumiverse had to fall back to its approximate char/4 heuristic. */
+  approximate: boolean;
+}
+
 // ─── Worker → Host messages ──────────────────────────────────────────────
 
 export type WorkerToHost =
@@ -1320,7 +1360,32 @@ export type WorkerToHost =
   | { type: "commands_unregister"; commandIds: string[] }
   // ─── Version (free tier) ───────────────────────────────────────────────
   | { type: "version_get_backend"; requestId: string }
-  | { type: "version_get_frontend"; requestId: string };
+  | { type: "version_get_frontend"; requestId: string }
+  // ─── Token Counting (free tier) ───────────────────────────────────────
+  | {
+      type: "tokens_count_text";
+      requestId: string;
+      text: string;
+      model?: string;
+      modelSource?: TokenModelSourceDTO;
+      userId?: string;
+    }
+  | {
+      type: "tokens_count_messages";
+      requestId: string;
+      messages: Array<Pick<LlmMessageDTO, "role" | "content">>;
+      model?: string;
+      modelSource?: TokenModelSourceDTO;
+      userId?: string;
+    }
+  | {
+      type: "tokens_count_chat";
+      requestId: string;
+      chatId: string;
+      model?: string;
+      modelSource?: TokenModelSourceDTO;
+      userId?: string;
+    };
 
 // ─── Host → Worker messages ──────────────────────────────────────────────
 

package/src/dom.ts

@@ -62,6 +62,7 @@ export interface SpindleDrawerTabHandle {
   setBadge(text: string | null): void;
   activate(): void;
   destroy(): void;
+  /** Register a callback fired when the active drawer tab switches to this tab. Returns an unsubscribe function. */
   onActivate(handler: () => void): () => void;
 }
 

package/src/index.ts

@@ -73,6 +73,9 @@ export type {
   MessageSwipedPayloadDTO,
   SwipeEditedPayloadDTO,
   ToolInvocationPayloadDTO,
+  TokenModelSourceDTO,
+  TokenCountOptionsDTO,
+  TokenCountResultDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";

package/src/spindle-api.ts

@@ -48,6 +48,8 @@ import type {
   SwipeEditedPayloadDTO,
   ToolInvocationPayloadDTO,
   StreamChunkDTO,
+  TokenCountOptionsDTO,
+  TokenCountResultDTO,
 } from "./api";
 
 /** The global `spindle` object available in backend extension workers */
@@ -465,6 +467,25 @@ export interface SpindleAPI {
     get(connectionId: string, userId?: string): Promise<ConnectionProfileDTO | null>;
   };
 
+  /** Server-side token counting helpers (free tier). */
+  tokens: {
+    /** Count tokens for an arbitrary text string. `options.model` overrides `options.modelSource`. */
+    countText(text: string, options?: TokenCountOptionsDTO): Promise<TokenCountResultDTO>;
+    /**
+     * Count tokens for an array of chat-style messages.
+     *
+     * This accepts any array whose items expose `{ role, content }`, so the
+     * normalized output of `spindle.chat.getMessages(chatId)` can be passed
+     * directly without reshaping. `options.model` overrides `options.modelSource`.
+     */
+    countMessages(
+      messages: Array<Pick<LlmMessageDTO, "role" | "content">>,
+      options?: TokenCountOptionsDTO
+    ): Promise<TokenCountResultDTO>;
+    /** Count tokens for a live stored chat by ID. `options.model` overrides `options.modelSource`. */
+    countChat(chatId: string, options?: TokenCountOptionsDTO): Promise<TokenCountResultDTO>;
+  };
+
   /**
    * Image generation (permission: "image_gen").
    * Generate images via the user's configured image gen connection profiles.