lumiverse-spindle-types 0.4.31 → 0.4.32

package/package.json

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

package/src/api.ts

@@ -29,6 +29,27 @@ export interface MacroDefinitionDTO {
   handler: string; // serialized function body (executed in worker context)
 }
 
+/** Minimal shape exposed to extension macro handlers. Additional fields may be present. */
+export interface MacroInvocationContextDTO {
+  /** False when the host is performing a dry / non-committing resolve. */
+  commit: boolean;
+  [key: string]: unknown;
+}
+
+export interface MacroResolveOptionsDTO {
+  chatId?: string;
+  characterId?: string;
+  /** For operator-scoped extensions only. */
+  userId?: string;
+  /** Defaults to true. Set false to request a dry / non-committing resolve. */
+  commit?: boolean;
+}
+
+export interface MacroResolveResultDTO {
+  text: string;
+  diagnostics: Array<{ message: string; offset: number; length: number }>;
+}
+
 export interface ToolRegistrationDTO {
   name: string;
   display_name: string;
@@ -1349,7 +1370,7 @@ export type WorkerToHost =
   | { type: "confirm_open"; requestId: string; title: string; message: string; variant?: "info" | "warning" | "danger" | "success"; confirmLabel?: string; cancelLabel?: string; userId?: string }
   | { type: "input_prompt_open"; requestId: string; title: string; message?: string; placeholder?: string; defaultValue?: string; submitLabel?: string; cancelLabel?: string; multiline?: boolean; userId?: string }
   // ─── Macro Resolution (free tier) ──────────────────────────────────
-  | { type: "macros_resolve"; requestId: string; template: string; chatId?: string; characterId?: string; userId?: string }
+  | { type: "macros_resolve"; requestId: string; template: string; chatId?: string; characterId?: string; userId?: string; commit?: boolean }
   // ─── Image Generation (gated: "image_gen") ──────────────────────────
   | { type: "image_gen_generate"; requestId: string; input: ImageGenRequestDTO }
   | { type: "image_gen_providers"; requestId: string; userId?: string }

package/src/index.ts

@@ -16,6 +16,9 @@ export type {
   LlmMessageDTO,
   InterceptorResultDTO,
   MacroDefinitionDTO,
+  MacroInvocationContextDTO,
+  MacroResolveOptionsDTO,
+  MacroResolveResultDTO,
   ToolRegistrationDTO,
   ToolSchemaDTO,
   ToolCallDTO,

package/src/spindle-api.ts

@@ -3,6 +3,8 @@ import type {
   LlmMessageDTO,
   InterceptorResultDTO,
   MacroDefinitionDTO,
+  MacroResolveOptionsDTO,
+  MacroResolveResultDTO,
   ToolRegistrationDTO,
   GenerationRequestDTO,
   RequestInitDTO,
@@ -96,7 +98,7 @@ export interface SpindleAPI {
   /** Subscribe to a Lumiverse event. */
   on(event: string, handler: (payload: unknown, userId?: string) => void): () => void;
 
-  /** Register a macro */
+  /** Register a macro. Handler contexts expose `commit === false` during dry resolves. */
   registerMacro(def: MacroDefinitionDTO): void;
   /** Unregister a macro */
   unregisterMacro(name: string): void;
@@ -763,6 +765,8 @@ export interface SpindleAPI {
      * Resolve all macros in the given template string.
      * Provide `chatId` and/or `characterId` for full context resolution.
      * Without them, only context-free macros (time, random, etc.) resolve.
+     * Set `commit: false` for a dry / non-committing resolve; extension macro
+     * handlers will receive `ctx.commit === false`.
      *
      * @example
      * ```ts
@@ -774,16 +778,8 @@ export interface SpindleAPI {
      */
     resolve(
       template: string,
-      options?: {
-        chatId?: string;
-        characterId?: string;
-        /** For operator-scoped extensions only. */
-        userId?: string;
-      },
-    ): Promise<{
-      text: string;
-      diagnostics: Array<{ message: string; offset: number; length: number }>;
-    }>;
+      options?: MacroResolveOptionsDTO,
+    ): Promise<MacroResolveResultDTO>;
   };
 
   /**