lumiverse-spindle-types 0.4.24 → 0.4.26

package/package.json

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

package/src/api.ts

@@ -1,4 +1,5 @@
 import type { SpindleManifest } from "./manifest";
+import type { CouncilMemberContext } from "./council";
 
 // ─── DTO types for messages ──────────────────────────────────────────────
 
@@ -946,6 +947,42 @@ export interface MessageSwipedPayloadDTO {
   previousSwipeId?: number;
 }
 
+/**
+ * Payload delivered to `spindle.on("TOOL_INVOCATION", ...)` handlers.
+ *
+ * Fires whenever an extension-registered tool is invoked by Lumiverse. Handlers
+ * must return a string (or promise thereof) with the tool's result — the host
+ * coerces `undefined` / `null` to an empty string.
+ *
+ * `councilMember` is populated when the invocation originates from a council
+ * 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`. */
+  toolName: string;
+  /** Arguments delivered to the tool. Shape depends on the tool's JSON Schema. */
+  args: Record<string, unknown>;
+  /** Host-side correlation id for this invocation. */
+  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[];
+}
+
 /**
  * Observer handle returned by `spindle.generate.observe()`.
  * Provides a high-level API for watching an in-flight generation on a
@@ -1301,6 +1338,22 @@ export type HostToWorker =
       requestId: string;
       toolName: string;
       args: Record<string, unknown>;
+      /**
+       * Populated when the invocation originates from a council execution
+       * cycle — carries the assigned council member's identity, role, chance,
+       * avatar URL, and Lumia personality fields so the extension can tailor
+       * its tool pipeline to the member on whose behalf it is running.
+       *
+       * 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/council.ts

@@ -77,6 +77,47 @@ export interface CouncilSettings {
   toolsSettings: CouncilToolsSettings;
 }
 
+// ---- Tool Invocation Context ----
+
+/**
+ * Personality snapshot of the council member that triggered a tool invocation.
+ *
+ * Delivered to extension `TOOL_INVOCATION` handlers when an extension-provided
+ * council tool is executed as part of a council cycle. Allows extensions to
+ * personalise their tool pipeline with the assigned member's identity, role,
+ * and Lumia personality fields.
+ *
+ * This field is optional — it is only populated when the tool is invoked via
+ * the council execution path. Tools invoked outside council (e.g. future
+ * inline function calling) will not see this context.
+ */
+export interface CouncilMemberContext {
+  /** Unique council member id (council settings row id). */
+  memberId: string;
+  /** Source Lumia item id this member is backed by. */
+  itemId: string;
+  /** Pack id the Lumia item lives in. */
+  packId: string;
+  /** Pack name the Lumia item lives in. */
+  packName: string;
+  /** Display name of the Lumia item (also used as the member name). */
+  name: string;
+  /** Freeform role description assigned by the user (e.g. "Plot Enforcer"). */
+  role: string;
+  /** Probability (0–100) that this member participates each generation. */
+  chance: number;
+  /** Relative URL to the member's avatar (e.g. `/api/v1/images/{id}`), or null. */
+  avatarUrl: string | null;
+  /** Lumia item "definition" field — physical/identity description. */
+  definition: string;
+  /** Lumia item "personality" field. */
+  personality: string;
+  /** Lumia item "behavior" field — behavioural patterns. */
+  behavior: string;
+  /** Gender identity marker (0=unspecified, 1=feminine, 2=masculine). */
+  genderIdentity: 0 | 1 | 2;
+}
+
 // ---- Execution Results ----
 
 /** Result of a single tool invocation for a single member. */

package/src/index.ts

@@ -71,6 +71,7 @@ export type {
   ChatMessageDTO,
   MessageSwipeAction,
   MessageSwipedPayloadDTO,
+  ToolInvocationPayloadDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";
@@ -114,6 +115,7 @@ export type { SpindleAPI } from "./spindle-api";
 
 export type {
   CouncilMember,
+  CouncilMemberContext,
   SidecarConfig,
   CouncilSidecarConfig,
   CouncilToolsSettings,

package/src/spindle-api.ts

@@ -45,6 +45,7 @@ import type {
   GenerationStoppedPayloadDTO,
   GenerationObserver,
   MessageSwipedPayloadDTO,
+  ToolInvocationPayloadDTO,
   StreamChunkDTO,
 } from "./api";
 
@@ -64,6 +65,21 @@ export interface SpindleAPI {
    * `swipeId` identifies which slot the event concerns.
    */
   on(event: "MESSAGE_SWIPED", handler: (payload: MessageSwipedPayloadDTO, userId?: string) => void): () => void;
+  /**
+   * Receive invocations for tools registered via {@link SpindleAPI.registerTool}.
+   *
+   * The handler must return the tool's textual result (or a promise thereof).
+   * Undefined / null returns are coerced to an empty string by the host.
+   *
+   * When the invocation originates from a council execution cycle, the payload
+   * includes a `councilMember` snapshot describing the assigned member
+   * (identity, role, chance, avatar URL, and Lumia personality fields) so the
+   * extension can tailor its tool output to that member's voice.
+   */
+  on(
+    event: "TOOL_INVOCATION",
+    handler: (payload: ToolInvocationPayloadDTO) => string | Promise<string> | void | Promise<void>
+  ): () => void;
   /** Subscribe to a Lumiverse event. */
   on(event: string, handler: (payload: unknown, userId?: string) => void): () => void;