lumiverse-spindle-types 0.4.13 → 0.4.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "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 =
@@ -933,6 +1001,11 @@ export type WorkerToHost =
   | { type: "vars_delete_global"; requestId: string; key: string; userId?: string }
   | { type: "vars_list_global"; requestId: string; userId?: string }
   | { type: "vars_has_global"; requestId: string; key: string; userId?: string }
+  | { type: "vars_get_chat"; requestId: string; chatId: string; key: string }
+  | { type: "vars_set_chat"; requestId: string; chatId: string; key: string; value: string }
+  | { type: "vars_delete_chat"; requestId: string; chatId: string; key: string }
+  | { type: "vars_list_chat"; requestId: string; chatId: string }
+  | { type: "vars_has_chat"; requestId: string; chatId: string; key: string }
   // ─── Characters (gated: "characters") ──────────────────────────────
   | { type: "characters_list"; requestId: string; limit?: number; offset?: number; userId?: string }
   | { type: "characters_get"; requestId: string; characterId: string; userId?: string }

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) */
@@ -307,8 +341,9 @@ export interface SpindleAPI {
   };
 
   /**
-   * Local (chat-scoped) and global variable access (free tier — no permission needed).
-   * Uses the same storage as built-in {{getvar}}/{{setgvar}} macros.
+   * Local (transient), global (user-scoped), and chat (persisted) variable access
+   * (free tier — no permission needed).
+   * Uses the same storage as built-in {{getvar}}/{{setgvar}}/{{getchatvar}} macros.
    */
   variables: {
     local: {
@@ -325,6 +360,15 @@ export interface SpindleAPI {
       list(userId?: string): Promise<Record<string, string>>;
       has(key: string, userId?: string): Promise<boolean>;
     };
+    /** Chat-scoped persisted variables — stored in chat.metadata.chat_variables.
+     *  Persists across generations within the same chat. */
+    chat: {
+      get(chatId: string, key: string): Promise<string>;
+      set(chatId: string, key: string, value: string): Promise<void>;
+      delete(chatId: string, key: string): Promise<void>;
+      list(chatId: string): Promise<Record<string, string>>;
+      has(chatId: string, key: string): Promise<boolean>;
+    };
   };
 
   /**