lumiverse-spindle-types 0.4.31 → 0.4.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.4.31",
+  "version": "0.4.33",
   "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/council.ts

@@ -161,16 +161,32 @@ export type CouncilToolCategory =
   | "content"
   | "extension";
 
+export type CouncilToolExecution =
+  | "llm"
+  | "host"
+  | "extension"
+  | "mcp";
+
 /** Canonical definition of a council tool (built-in or DLC). */
 export interface CouncilToolDefinition {
   name: string;
   displayName: string;
   description: string;
   category: CouncilToolCategory;
-  /** The prompt sent to the sidecar LLM when invoking this tool. */
-  prompt: string;
-  /** JSON Schema describing the tool's expected output structure. */
-  inputSchema: Record<string, unknown>;
+  /** Optional explicit runtime. When omitted, the host may infer one from the tool source. */
+  execution?: CouncilToolExecution;
+  /** The prompt sent to the sidecar LLM when invoking prompt-style LLM tools. */
+  prompt?: string;
+  /**
+   * JSON Schema describing the prompt-style tool's expected output structure.
+   *
+   * Historically this field was also used as the callable argument schema for
+   * extension / MCP tools. New host-callable tools should prefer `argsSchema`
+   * instead so invocation arguments and returned content are not conflated.
+   */
+  inputSchema?: Record<string, unknown>;
+  /** JSON Schema describing the callable arguments for host / extension / MCP tools. */
+  argsSchema?: Record<string, unknown>;
   /** If set, the tool's result is stored under this variable name for macro access. */
   resultVariable?: string;
   /** Whether this tool's output appears in the deliberation block (default true). */

package/src/index.ts

@@ -16,6 +16,9 @@ export type {
   LlmMessageDTO,
   InterceptorResultDTO,
   MacroDefinitionDTO,
+  MacroInvocationContextDTO,
+  MacroResolveOptionsDTO,
+  MacroResolveResultDTO,
   ToolRegistrationDTO,
   ToolSchemaDTO,
   ToolCallDTO,
@@ -129,6 +132,7 @@ export type {
   CouncilExecutionResult,
   CachedCouncilResult,
   CouncilToolCategory,
+  CouncilToolExecution,
   CouncilToolDefinition,
 } from "./council";
 export {

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>;
   };
 
   /**