lumiverse-spindle-types 0.5.16 → 0.5.18

package/package.json

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

package/src/api.ts

@@ -774,6 +774,26 @@ export interface ChatChangedPayloadDTO {
   changedFields?: string[];
 }
 
+/**
+ * Payload for `CHAT_FORKED` events. Emitted when a chat is forked (branched)
+ * from a specific message — the messages up to and including the fork point are
+ * copied into a brand-new chat that shares the source chat's character.
+ */
+export interface ChatForkedPayloadDTO {
+  /** Id of the source chat that was forked. */
+  sourceChatId: string;
+  /** Id of the newly created forked chat. Equal to `chat.id`. */
+  forkedChatId: string;
+  /** The new forked chat row, including its `metadata` (carries `branched_from` and `branch_at_message`). */
+  chat: { id: string; [key: string]: unknown };
+  /** The `branch_id` assigned to every message copied into the forked chat. */
+  branchId: string;
+  /** Id of the message in the source chat the fork was taken at. Messages up to and including this one were copied into the forked chat. */
+  forkedAtMessageId: string;
+  /** Zero-based index of the fork-point message within the source chat. */
+  forkedAtMessageIndex: number;
+}
+
 // ─── User Preset DTOs ───────────────────────────────────────────────────
 
 /** Option entry for `select` and `multiselect` prompt variables. */
@@ -1356,8 +1376,19 @@ export interface MemoryStatsDTO {
   chunksAvailable: number;
   chunksPending: number;
   injectionMethod: "macro" | "fallback" | "disabled";
+  /**
+   * How the chunks were retrieved: a real vector/hybrid search ("vector") or
+   * the recency fallback ("recency", e.g. when the query embedding failed).
+   * Absent until the chat-memory cache has been populated.
+   */
+  retrievalMode?: "vector" | "recency" | "empty" | "disabled";
   retrievedChunks: Array<{
-    score: number;
+    /**
+     * Vector distance (lower = more similar). `null` for keyword-only or
+     * recency-fallback hits, which have no vector distance — do not treat a
+     * missing score as a perfect (zero-distance) match.
+     */
+    score: number | null;
     tokenEstimate: number;
     messageRange: [number, number];
     preview: string;
@@ -1395,7 +1426,12 @@ export interface DryRunResultDTO {
 
 export interface ChatMemoryChunkDTO {
   content: string;
-  score: number;
+  /**
+   * Vector distance (lower = more similar). `null` for keyword-only or
+   * recency-fallback hits, which have no vector distance — do not treat a
+   * missing score as a perfect (zero-distance) match.
+   */
+  score: number | null;
   metadata: Record<string, unknown>;
 }
 
@@ -1408,6 +1444,8 @@ export interface ChatMemoryResultDTO {
   settingsSource: "global" | "per_chat";
   chunksAvailable: number;
   chunksPending: number;
+  /** How chunks were retrieved (real vector search vs. recency fallback). */
+  retrievalMode?: "vector" | "recency" | "empty" | "disabled";
 }
 
 /**

package/src/events.ts

@@ -14,6 +14,7 @@ export enum CoreEventType {
   CONNECTED = "CONNECTED",
   CHAT_CHANGED = "CHAT_CHANGED",
   CHAT_SWITCHED = "CHAT_SWITCHED",
+  CHAT_FORKED = "CHAT_FORKED",
   MESSAGE_SENT = "MESSAGE_SENT",
   MESSAGE_EDITED = "MESSAGE_EDITED",
   MESSAGE_DELETED = "MESSAGE_DELETED",

package/src/index.ts

@@ -49,6 +49,7 @@ export type {
     ChatUpdateDTO,
     ChatSwitchedPayloadDTO,
     ChatChangedPayloadDTO,
+    ChatForkedPayloadDTO,
     PromptVariableOptionDTO,
     PromptVariableDefDTO,
     PromptVariableTypeDTO,

package/src/spindle-api.ts

@@ -85,6 +85,7 @@ import type {
   BackendProcessLifecycleEventDTO,
   BackendProcessStopOptionsDTO,
   ChatChangedPayloadDTO,
+  ChatForkedPayloadDTO,
   ChatMessageDTO,
   GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
@@ -220,6 +221,8 @@ export interface SpindleAPI {
   on(event: "GENERATION_STOPPED", handler: (payload: GenerationStoppedPayloadDTO, userId?: string) => void): () => void;
   /** Subscribe to `CHAT_CHANGED` events. `changedFields` lists the dot-paths that differed when emitted by the standard `updateChat` path; absent on emits from other sources. */
   on(event: "CHAT_CHANGED", handler: (payload: ChatChangedPayloadDTO, userId?: string) => void): () => void;
+  /** Subscribe to `CHAT_FORKED` events. Emitted when a chat is forked (branched) from a message into a new chat. The payload carries the source/forked chat ids, the full forked chat row, and the fork point. */
+  on(event: "CHAT_FORKED", handler: (payload: ChatForkedPayloadDTO, userId?: string) => void): () => void;
   /**
    * Subscribe to swipe lifecycle events. The payload's `action` discriminator
    * tells you whether a swipe was added, updated, deleted, or navigated, and