lumiverse-spindle-types 0.4.14 → 0.4.16

package/package.json

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

package/src/api.ts

@@ -755,6 +755,74 @@ export interface SpindleCommandContextDTO {
   isGroupChat?: boolean;
 }
 
+// ─── Generation Event Payload DTOs ──────────────────────────────────────
+
+/** Payload for `GENERATION_STARTED` events. */
+export interface GenerationStartedPayloadDTO {
+  generationId: string;
+  chatId: string;
+  model: string;
+  targetMessageId?: string;
+  characterId?: string;
+  characterName?: string;
+}
+
+/** Payload for `STREAM_TOKEN_RECEIVED` events. */
+export interface StreamTokenPayloadDTO {
+  generationId: string;
+  chatId: string;
+  /** The token text chunk. */
+  token: string;
+  /** Monotonic sequence number for deduplication on reconnect. */
+  seq: number;
+  /** Present and set to `"reasoning"` for chain-of-thought tokens. */
+  type?: "reasoning";
+}
+
+/** Payload for `GENERATION_ENDED` events. */
+export interface GenerationEndedPayloadDTO {
+  generationId: string;
+  chatId: string;
+  /** ID of the saved message (absent on error). */
+  messageId?: string;
+  /** Final generated content (absent on error). */
+  content?: string;
+  /** Error message when the generation failed. */
+  error?: string;
+}
+
+/** Payload for `GENERATION_STOPPED` events (user-initiated stop). */
+export interface GenerationStoppedPayloadDTO {
+  generationId: string;
+  chatId: string;
+  /** Partial content accumulated before the stop. */
+  content?: string;
+}
+
+/**
+ * Observer handle returned by `spindle.generate.observe()`.
+ * Provides a high-level API for watching an in-flight generation on a
+ * specific chat, with automatic token accumulation and lifecycle callbacks.
+ */
+export interface GenerationObserver {
+  /** Register a callback for when a generation starts on the observed chat. */
+  onStart(handler: (info: GenerationStartedPayloadDTO) => void): void;
+  /** Register a callback for each streamed token (content or reasoning). */
+  onToken(handler: (token: StreamTokenPayloadDTO) => void): void;
+  /** Register a callback for when the generation completes (success or error). */
+  onEnd(handler: (result: GenerationEndedPayloadDTO) => void): void;
+  /** Register a callback for when the generation is stopped by the user. */
+  onStop(handler: (result: GenerationStoppedPayloadDTO) => void): void;
+  /** Accumulated content tokens so far. */
+  readonly content: string;
+  /** Accumulated reasoning tokens so far. */
+  readonly reasoning: string;
+  /** The active generation ID, or `null` if idle. */
+  readonly generationId: string | null;
+  /** Stop observing and unsubscribe from all events. */
+  dispose(): void;
+}
+
 // ─── Worker → Host messages ──────────────────────────────────────────────
 
 export type WorkerToHost =

package/src/index.ts

@@ -62,6 +62,11 @@ export type {
   SpindleModalItemDTO,
   SpindleCommandDTO,
   SpindleCommandContextDTO,
+  GenerationStartedPayloadDTO,
+  StreamTokenPayloadDTO,
+  GenerationEndedPayloadDTO,
+  GenerationStoppedPayloadDTO,
+  GenerationObserver,
   WorkerToHost,
   HostToWorker,
 } from "./api";

package/src/spindle-api.ts

@@ -39,11 +39,24 @@ import type {
   SpindleModalItemDTO,
   SpindleCommandDTO,
   SpindleCommandContextDTO,
+  GenerationStartedPayloadDTO,
+  StreamTokenPayloadDTO,
+  GenerationEndedPayloadDTO,
+  GenerationStoppedPayloadDTO,
+  GenerationObserver,
 } from "./api";
 
 /** The global `spindle` object available in backend extension workers */
 export interface SpindleAPI {
-  /** Subscribe to a Lumiverse event */
+  /** Subscribe to generation-started events (requires `generation` permission). */
+  on(event: "GENERATION_STARTED", handler: (payload: GenerationStartedPayloadDTO) => void): () => void;
+  /** Subscribe to streamed token events (requires `generation` permission). */
+  on(event: "STREAM_TOKEN_RECEIVED", handler: (payload: StreamTokenPayloadDTO) => void): () => void;
+  /** Subscribe to generation-ended events (requires `generation` permission). */
+  on(event: "GENERATION_ENDED", handler: (payload: GenerationEndedPayloadDTO) => void): () => void;
+  /** Subscribe to generation-stopped events (requires `generation` permission). */
+  on(event: "GENERATION_STOPPED", handler: (payload: GenerationStoppedPayloadDTO) => void): () => void;
+  /** Subscribe to a Lumiverse event. */
   on(event: string, handler: (payload: unknown) => void): () => void;
 
   /** Register a macro */
@@ -89,6 +102,27 @@ export interface SpindleAPI {
     batch(input: GenerationRequestDTO): Promise<unknown>;
     /** Run a dry-run prompt assembly without calling the LLM. */
     dryRun(input: DryRunRequestDTO, userId?: string): Promise<DryRunResultDTO>;
+    /**
+     * Observe an in-flight generation on a chat.
+     *
+     * Returns a {@link GenerationObserver} that subscribes to the generation
+     * lifecycle events for the given `chatId` and accumulates streamed
+     * content/reasoning automatically. Call `.dispose()` when done.
+     *
+     * Requires the `generation` permission.
+     *
+     * @example
+     * ```ts
+     * const obs = spindle.generate.observe("chat-uuid");
+     * obs.onStart((info) => console.log("Started:", info.model));
+     * obs.onToken((t) => console.log("Token:", t.token));
+     * obs.onEnd((r) => {
+     *   console.log("Done:", obs.content);
+     *   obs.dispose();
+     * });
+     * ```
+     */
+    observe(chatId: string): GenerationObserver;
   };
 
   /** Scoped storage (per-extension virtual disk) */
@@ -186,6 +220,13 @@ export interface SpindleAPI {
       role: "system" | "user" | "assistant";
       content: string;
       metadata?: Record<string, unknown>;
+      /** Index of the active swipe in `swipes`. `0` when the message has no alternates. */
+      swipe_id: number;
+      /**
+       * All swipe variants for this message, including the currently active one.
+       * `swipes[swipe_id]` always equals `content`.
+       */
+      swipes: string[];
     }>>;
     appendMessage(
       chatId: string,