lumiverse-spindle-types 0.4.34 → 0.4.37

package/package.json

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

package/src/api.ts

@@ -9,6 +9,21 @@ export interface LlmMessageDTO {
   name?: string;
 }
 
+/**
+ * Optional metadata returned by an interceptor so Lumiverse can surface
+ * extension-injected prompt messages as first-class items in Prompt Breakdown.
+ *
+ * `messageIndex` points at the message inside the interceptor's returned
+ * `messages` array. The host resolves role/content/extension attribution from
+ * that message and from the installed extension manifest, so extensions only
+ * need to identify which injected messages should appear in the breakdown.
+ */
+export interface InterceptorBreakdownEntryDTO {
+  messageIndex: number;
+  /** Optional human label for this injected prompt block. */
+  name?: string;
+}
+
 /**
  * Return type for interceptor handlers.
  * Interceptors may return either a plain `LlmMessageDTO[]` (backwards-compatible)
@@ -18,6 +33,8 @@ export interface InterceptorResultDTO {
   messages: LlmMessageDTO[];
   /** Provider parameters merged into the outgoing LLM request. Requires `generation_parameters` permission. */
   parameters?: Record<string, unknown>;
+  /** Optional prompt-breakdown entries for injected messages. */
+  breakdown?: InterceptorBreakdownEntryDTO[];
 }
 
 export interface MacroDefinitionDTO {
@@ -522,6 +539,8 @@ export interface AssemblyBreakdownEntryDTO {
   firstMessageIndex?: number;
   preCountedTokens?: number;
   excludeFromTotal?: boolean;
+  extensionId?: string;
+  extensionName?: string;
 }
 
 export interface ActivationStatsDTO {
@@ -552,7 +571,14 @@ export interface MemoryStatsDTO {
 
 export interface DryRunTokenCountDTO {
   total_tokens: number;
-  breakdown: Array<{ name: string; type: string; tokens: number; role?: string }>;
+  breakdown: Array<{
+    name: string;
+    type: string;
+    tokens: number;
+    role?: string;
+    extensionId?: string;
+    extensionName?: string;
+  }>;
   tokenizer_id: string | null;
   tokenizer_name: string | null;
 }
@@ -868,6 +894,7 @@ export interface GenerationStartedPayloadDTO {
   targetMessageId?: string;
   characterId?: string;
   characterName?: string;
+  breakdown?: AssemblyBreakdownEntryDTO[];
 }
 
 /** Payload for `STREAM_TOKEN_RECEIVED` events. */
@@ -1108,7 +1135,13 @@ export type WorkerToHost =
   | { type: "unregister_macro"; name: string }
   | { type: "update_macro_value"; name: string; value: string }
   | { type: "register_interceptor"; priority?: number }
-  | { type: "intercept_result"; requestId: string; messages: LlmMessageDTO[]; parameters?: Record<string, unknown> }
+  | {
+      type: "intercept_result";
+      requestId: string;
+      messages: LlmMessageDTO[];
+      parameters?: Record<string, unknown>;
+      breakdown?: InterceptorBreakdownEntryDTO[];
+    }
   | { type: "register_tool"; tool: ToolRegistrationDTO }
   | { type: "unregister_tool"; name: string }
   | { type: "request_generation"; requestId: string; input: GenerationRequestDTO }
@@ -1366,7 +1399,7 @@ export type WorkerToHost =
   // ─── Chat Memories (gated: "chats") ───────────────────────────────
   | { type: "chats_get_memories"; requestId: string; chatId: string; topK?: number; userId?: string }
   // ─── Toast (free tier) ───────────────────────────────────────────────
-  | { type: "toast_show"; toastType: "success" | "warning" | "error" | "info"; message: string; title?: string; duration?: number }
+  | { type: "toast_show"; toastType: "success" | "warning" | "error" | "info"; message: string; title?: string; duration?: number; userId?: string }
   // ─── Push Notifications (gated: "push_notification") ────────────────
   | { type: "push_send"; requestId: string; title: string; body: string; tag?: string; url?: string; userId?: string; icon?: string; rawTitle?: boolean; image?: string }
   | { type: "push_get_status"; requestId: string; userId?: string }

package/src/dom.ts

@@ -135,6 +135,7 @@ export interface SpindleAppMountHandle {
 export interface SpindleInputBarActionOptions {
   id: string;
   label: string;
+  subtitle?: string;
   iconSvg?: string;
   iconUrl?: string;
   enabled?: boolean;
@@ -143,6 +144,7 @@ export interface SpindleInputBarActionOptions {
 export interface SpindleInputBarActionHandle {
   actionId: string;
   setLabel(label: string): void;
+  setSubtitle(subtitle?: string): void;
   setEnabled(enabled: boolean): void;
   onClick(handler: () => void): () => void;
   destroy(): void;

package/src/index.ts

@@ -14,6 +14,7 @@ export { SpindleEvent, CoreEventType } from "./events";
 
 export type {
   LlmMessageDTO,
+  InterceptorBreakdownEntryDTO,
   InterceptorResultDTO,
   MacroDefinitionDTO,
   MacroInvocationContextDTO,

package/src/spindle-api.ts

@@ -57,13 +57,13 @@ import type {
 
 /** The global `spindle` object available in backend extension workers */
 export interface SpindleAPI {
-  /** Subscribe to generation-started events (requires `generation` permission). */
+  /** Subscribe to generation-started events (requires `generation` permission). The optional `userId` identifies which user triggered the event. */
   on(event: "GENERATION_STARTED", handler: (payload: GenerationStartedPayloadDTO, userId?: string) => void): () => void;
-  /** Subscribe to streamed token events (requires `generation` permission). */
+  /** Subscribe to streamed token events (requires `generation` permission). The optional `userId` identifies which user triggered the event. */
   on(event: "STREAM_TOKEN_RECEIVED", handler: (payload: StreamTokenPayloadDTO, userId?: string) => void): () => void;
-  /** Subscribe to generation-ended events (requires `generation` permission). */
+  /** Subscribe to generation-ended events (requires `generation` permission). The optional `userId` identifies which user triggered the event. */
   on(event: "GENERATION_ENDED", handler: (payload: GenerationEndedPayloadDTO, userId?: string) => void): () => void;
-  /** Subscribe to generation-stopped events (requires `generation` permission). */
+  /** Subscribe to generation-stopped events (requires `generation` permission). The optional `userId` identifies which user triggered the event. */
   on(event: "GENERATION_STOPPED", handler: (payload: GenerationStoppedPayloadDTO, userId?: string) => void): () => void;
   /**
    * Subscribe to swipe lifecycle events. The payload's `action` discriminator
@@ -95,7 +95,7 @@ export interface SpindleAPI {
     event: "TOOL_INVOCATION",
     handler: (payload: ToolInvocationPayloadDTO) => string | Promise<string> | void | Promise<void>
   ): () => void;
-  /** Subscribe to a Lumiverse event. */
+  /** Subscribe to a Lumiverse event. Multi-user extensions should use the optional `userId` to keep per-user state and notifications isolated. */
   on(event: string, handler: (payload: unknown, userId?: string) => void): () => void;
 
   /** Register a macro. Handler contexts expose `commit === false` during dry resolves. */
@@ -116,7 +116,9 @@ export interface SpindleAPI {
    * The handler receives the assembled messages and a context object, and may
    * return either a plain `LlmMessageDTO[]` (backwards-compatible) or an
    * `InterceptorResultDTO` to also inject generation parameters into the
-   * outgoing LLM request.
+   * outgoing LLM request. `InterceptorResultDTO.breakdown` can be used to mark
+   * specific injected messages as Prompt Breakdown entries so dry-run/live UI
+   * and saved breakdowns can attribute them back to the extension.
    *
    * Returning `parameters` requires the `generation_parameters` permission.
    * Without it, returned parameters are silently stripped.
@@ -708,6 +710,8 @@ export interface SpindleAPI {
     /**
      * Send a push notification to a user's registered devices.
      * Only delivered when the app is not focused (avoids double-notification).
+     * Operator-scoped extensions should pass the `userId` from the triggering
+     * frontend message or event handler to avoid cross-user delivery.
      */
     send(input: {
       title: string;
@@ -810,10 +814,10 @@ export interface SpindleAPI {
 
   /** Show toast notifications in the frontend UI (free tier — no permission needed) */
   toast: {
-    success(message: string, options?: { title?: string; duration?: number }): void;
-    warning(message: string, options?: { title?: string; duration?: number }): void;
-    error(message: string, options?: { title?: string; duration?: number }): void;
-    info(message: string, options?: { title?: string; duration?: number }): void;
+    success(message: string, options?: { title?: string; duration?: number; /** For operator-scoped extensions only. */ userId?: string }): void;
+    warning(message: string, options?: { title?: string; duration?: number; /** For operator-scoped extensions only. */ userId?: string }): void;
+    error(message: string, options?: { title?: string; duration?: number; /** For operator-scoped extensions only. */ userId?: string }): void;
+    info(message: string, options?: { title?: string; duration?: number; /** For operator-scoped extensions only. */ userId?: string }): void;
   };
 
   /** OAuth callback handling (permission: "oauth") */