lumiverse-spindle-types 0.4.25 → 0.4.27

package/package.json

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

package/src/api.ts

@@ -947,6 +947,28 @@ export interface MessageSwipedPayloadDTO {
   previousSwipeId?: number;
 }
 
+/**
+ * Payload for `SWIPE_EDITED` events.
+ *
+ * Fires when `spindle.chat.updateMessage()` explicitly supplies one or more
+ * swipe-shaped fields (`swipes`, `swipe_id`, or `swipe_dates`). Plain content
+ * edits that mirror into the active swipe slot continue to emit only
+ * `MESSAGE_EDITED` — this event is for extension-driven rewrites of the
+ * swipe array itself, index navigation, or date-array rewrites.
+ *
+ * `MESSAGE_SWIPED` still fires for the dedicated swipe REST routes
+ * (`addSwipe`, `updateSwipe`, `deleteSwipe`, `cycleSwipe`) with its
+ * `action` discriminator. Consumers that need fine-grained action semantics
+ * should prefer `MESSAGE_SWIPED`; `SWIPE_EDITED` is intentionally coarser.
+ */
+export interface SwipeEditedPayloadDTO {
+  chatId: string;
+  /** The full message after the mutation. */
+  message: ChatMessageDTO;
+  /** Active swipe index before the mutation. Equals `message.swipe_id` when navigation did not occur. */
+  previousSwipeId: number;
+}
+
 /**
  * Payload delivered to `spindle.on("TOOL_INVOCATION", ...)` handlers.
  *
@@ -958,6 +980,13 @@ export interface MessageSwipedPayloadDTO {
  * execution cycle, providing the assigned member's identity, role, chance,
  * avatar URL, and Lumia personality fields. It is `undefined` for all other
  * invocation paths.
+ *
+ * `contextMessages` is populated when the invocation originates from a council
+ * execution cycle — carrying the structured chat context (system enrichment +
+ * chat history) that was assembled for this member. Extensions can inspect
+ * role boundaries directly instead of re-parsing the flattened `args.context`
+ * string. Multi-part message content is flattened to its text portion before
+ * being delivered. `undefined` for non-council invocation paths.
  */
 export interface ToolInvocationPayloadDTO {
   /** The bare (unqualified) tool name, matching what was passed to `registerTool`. */
@@ -968,6 +997,12 @@ export interface ToolInvocationPayloadDTO {
   requestId: string;
   /** Council member snapshot when invoked via council — otherwise `undefined`. */
   councilMember?: CouncilMemberContext;
+  /**
+   * Structured chat context for council invocations — preserves role
+   * boundaries lost by the flattened `args.context` string. `undefined` for
+   * non-council paths.
+   */
+  contextMessages?: LlmMessageDTO[];
 }
 
 /**
@@ -1334,6 +1369,13 @@ export type HostToWorker =
        * Undefined for non-council invocation paths.
        */
       councilMember?: CouncilMemberContext;
+      /**
+       * Structured chat context for council invocations — the same messages
+       * that populated `args.context` (flattened string), but with role
+       * boundaries preserved so extensions can re-render or filter them
+       * without parsing. Undefined for non-council invocation paths.
+       */
+      contextMessages?: LlmMessageDTO[];
     }
   | { type: "shutdown" }
   | { type: "frontend_message"; payload: unknown; userId: string }

package/src/events.ts

@@ -17,6 +17,7 @@ export enum CoreEventType {
   MESSAGE_EDITED = "MESSAGE_EDITED",
   MESSAGE_DELETED = "MESSAGE_DELETED",
   MESSAGE_SWIPED = "MESSAGE_SWIPED",
+  SWIPE_EDITED = "SWIPE_EDITED",
   CHARACTER_MESSAGE_RENDERED = "CHARACTER_MESSAGE_RENDERED",
   USER_MESSAGE_RENDERED = "USER_MESSAGE_RENDERED",
   GENERATION_STARTED = "GENERATION_STARTED",

package/src/index.ts

@@ -71,6 +71,7 @@ export type {
   ChatMessageDTO,
   MessageSwipeAction,
   MessageSwipedPayloadDTO,
+  SwipeEditedPayloadDTO,
   ToolInvocationPayloadDTO,
   WorkerToHost,
   HostToWorker,

package/src/spindle-api.ts

@@ -45,6 +45,7 @@ import type {
   GenerationStoppedPayloadDTO,
   GenerationObserver,
   MessageSwipedPayloadDTO,
+  SwipeEditedPayloadDTO,
   ToolInvocationPayloadDTO,
   StreamChunkDTO,
 } from "./api";
@@ -65,6 +66,15 @@ export interface SpindleAPI {
    * `swipeId` identifies which slot the event concerns.
    */
   on(event: "MESSAGE_SWIPED", handler: (payload: MessageSwipedPayloadDTO, userId?: string) => void): () => void;
+  /**
+   * Subscribe to `SWIPE_EDITED` events. Emitted when {@link SpindleAPI.chat.updateMessage}
+   * explicitly rewrites one or more swipe-shaped fields (`swipes`, `swipe_id`,
+   * or `swipe_dates`). Plain content-only edits continue to emit `MESSAGE_EDITED`
+   * only. This event is coarser than `MESSAGE_SWIPED` by design — use
+   * `MESSAGE_SWIPED` when you need the `added`/`updated`/`deleted`/`navigated`
+   * discriminator.
+   */
+  on(event: "SWIPE_EDITED", handler: (payload: SwipeEditedPayloadDTO, userId?: string) => void): () => void;
   /**
    * Receive invocations for tools registered via {@link SpindleAPI.registerTool}.
    *
@@ -308,6 +318,12 @@ export interface SpindleAPI {
       id: string;
       role: "system" | "user" | "assistant";
       content: string;
+      /**
+       * The free-form `extra` bag minus `spindle_metadata` (which is surfaced
+       * separately on `metadata`). Carries reasoning text/duration, attachments,
+       * and any host-owned housekeeping fields.
+       */
+      extra: Record<string, unknown>;
       metadata?: Record<string, unknown>;
       /** Index of the active swipe in `swipes`. `0` when the message has no alternates. */
       swipe_id: number;
@@ -316,6 +332,8 @@ export interface SpindleAPI {
        * `swipes[swipe_id]` always equals `content`.
        */
       swipes: string[];
+      /** Per-swipe creation timestamps (unix epoch seconds), aligned with `swipes`. */
+      swipe_dates: number[];
     }>>;
     appendMessage(
       chatId: string,
@@ -325,12 +343,36 @@ export interface SpindleAPI {
         metadata?: Record<string, unknown>;
       }
     ): Promise<{ id: string }>;
+    /**
+     * Patch an existing message. All fields are optional; `undefined` leaves
+     * the field untouched. Precedence rules:
+     *
+     *  - If `content` is supplied, it overwrites both `messages.content` and
+     *    `swipes[swipe_id]` (the active slot).
+     *  - If `swipes` is supplied without `content`, the new active content is
+     *    derived from `swipes[swipe_id]` (either the supplied `swipe_id` or
+     *    the existing one).
+     *  - If only `swipe_id` is supplied, it acts as a navigation and content
+     *    is re-derived from the existing swipes array.
+     *  - `reasoning.text === null` clears `extra.reasoning`; `reasoning.duration
+     *    === null` clears `extra.reasoning_duration`. The two are independent.
+     *
+     * When any of `swipes`/`swipe_id`/`swipe_dates` are supplied, a
+     * `SWIPE_EDITED` event is emitted alongside (or instead of) `MESSAGE_EDITED`.
+     */
     updateMessage(
       chatId: string,
       messageId: string,
       patch: {
         content?: string;
         metadata?: Record<string, unknown>;
+        swipes?: string[];
+        swipe_id?: number;
+        swipe_dates?: number[];
+        reasoning?: {
+          text?: string | null;
+          duration?: number | null;
+        };
       }
     ): Promise<void>;
     deleteMessage(chatId: string, messageId: string): Promise<void>;