lumiverse-spindle-types 0.4.35 → 0.4.38

package/package.json

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

package/src/api.ts

@@ -9,6 +9,21 @@ export interface LlmMessageDTO {
   name?: string;
 }
 
+/**
+ * Optional metadata returned by an interceptor so Lumiverse can surface
+ * extension-injected prompt messages as first-class items in Prompt Breakdown.
+ *
+ * `messageIndex` points at the message inside the interceptor's returned
+ * `messages` array. The host resolves role/content/extension attribution from
+ * that message and from the installed extension manifest, so extensions only
+ * need to identify which injected messages should appear in the breakdown.
+ */
+export interface InterceptorBreakdownEntryDTO {
+  messageIndex: number;
+  /** Optional human label for this injected prompt block. */
+  name?: string;
+}
+
 /**
  * Return type for interceptor handlers.
  * Interceptors may return either a plain `LlmMessageDTO[]` (backwards-compatible)
@@ -18,6 +33,8 @@ export interface InterceptorResultDTO {
   messages: LlmMessageDTO[];
   /** Provider parameters merged into the outgoing LLM request. Requires `generation_parameters` permission. */
   parameters?: Record<string, unknown>;
+  /** Optional prompt-breakdown entries for injected messages. */
+  breakdown?: InterceptorBreakdownEntryDTO[];
 }
 
 export interface MacroDefinitionDTO {
@@ -50,6 +67,112 @@ export interface MacroResolveResultDTO {
   diagnostics: Array<{ message: string; offset: number; length: number }>;
 }
 
+// ─── Macro Interceptor (permission: "macro_interceptor") ────────────────
+
+/**
+ * Where a macro evaluation originated. Useful for interceptors that only
+ * want to fire for certain call sites (e.g. prompt assembly vs. response
+ * post-processing vs. display-time resolution).
+ */
+export type MacroInterceptorPhase =
+  | "prompt"
+  | "display"
+  | "response"
+  | "other";
+
+/**
+ * Structured-clone snapshot of the live macro evaluation environment,
+ * passed to a macro interceptor. All values are read-only copies — mutating
+ * them has no effect on the real environment. Persist state via
+ * `spindle.variables.*` helpers instead.
+ */
+export interface MacroInterceptorEnvDTO {
+  readonly commit: boolean;
+  readonly names: Record<string, string>;
+  readonly character: Record<string, unknown>;
+  readonly chat: Record<string, unknown>;
+  readonly system: Record<string, unknown>;
+  readonly variables: {
+    readonly local: Record<string, string>;
+    readonly global: Record<string, string>;
+    readonly chat: Record<string, string>;
+  };
+  readonly extra: Record<string, unknown>;
+}
+
+/**
+ * Context passed to a macro interceptor handler on every iteration of
+ * `MacroEvaluator.evaluate()`. The handler receives the current raw
+ * template (already transformed by any earlier interceptors in the chain)
+ * and returns either a transformed template string or `void` to pass through.
+ */
+export interface MacroInterceptorCtxDTO {
+  readonly template: string;
+  readonly env: MacroInterceptorEnvDTO;
+  readonly commit: boolean;
+  readonly phase: MacroInterceptorPhase;
+  readonly sourceHint?: string;
+  /**
+   * User ID that initiated the macro resolution (when available). Relevant
+   * for operator-scoped extensions that need to route work through other
+   * Spindle APIs on that user's behalf.
+   */
+  readonly userId?: string;
+}
+
+/**
+ * Return value of a macro interceptor handler.
+ *  - `string` replaces the template for subsequent interceptors + parsing.
+ *  - `void` / `undefined` passes the template through unchanged.
+ */
+export type MacroInterceptorResultDTO = string | void;
+
+// ─── Message Content Processor (permission: "chat_mutation") ───────────
+
+/**
+ * Which content-write path triggered a message content processor run.
+ * `"create"` covers both user-initiated `POST .../messages` writes and
+ * auto-inserted greeting rows.
+ */
+export type MessageContentProcessorOrigin =
+  | "create"
+  | "update"
+  | "swipe_add"
+  | "swipe_update";
+
+/**
+ * Context passed to a message content processor before a user-initiated
+ * message write reaches SQLite. Handlers can inspect this and return a
+ * patch (new `content` / merged `extra`) to transform what is stored and
+ * what WebSocket subscribers observe on first paint.
+ */
+export interface MessageContentProcessorCtxDTO {
+  chatId: string;
+  /** Undefined for `"create"` origins (the row doesn't exist yet). */
+  messageId?: string;
+  content: string;
+  extra?: Record<string, unknown>;
+  origin: MessageContentProcessorOrigin;
+  /** Set for `"swipe_update"` only — the zero-based index of the swipe being rewritten. */
+  swipeIndex?: number;
+  /** Owning user for the write. Pass this through to operator-scoped Spindle calls. */
+  userId: string;
+}
+
+/**
+ * Return value for a message content processor handler. Return `undefined`
+ * / `void` to pass through, or a partial patch to modify the write:
+ *  - `content` (if present) replaces the content for downstream processors
+ *    and the DB write.
+ *  - `extra` (if present) shallow-merges into the existing `extra` — keys
+ *    you omit are preserved. Ignored on swipe origins (swipes share the
+ *    parent message's `extra`).
+ */
+export interface MessageContentProcessorResultDTO {
+  content?: string;
+  extra?: Record<string, unknown>;
+}
+
 export interface ToolRegistrationDTO {
   name: string;
   display_name: string;
@@ -522,6 +645,8 @@ export interface AssemblyBreakdownEntryDTO {
   firstMessageIndex?: number;
   preCountedTokens?: number;
   excludeFromTotal?: boolean;
+  extensionId?: string;
+  extensionName?: string;
 }
 
 export interface ActivationStatsDTO {
@@ -552,7 +677,14 @@ export interface MemoryStatsDTO {
 
 export interface DryRunTokenCountDTO {
   total_tokens: number;
-  breakdown: Array<{ name: string; type: string; tokens: number; role?: string }>;
+  breakdown: Array<{
+    name: string;
+    type: string;
+    tokens: number;
+    role?: string;
+    extensionId?: string;
+    extensionName?: string;
+  }>;
   tokenizer_id: string | null;
   tokenizer_name: string | null;
 }
@@ -868,6 +1000,7 @@ export interface GenerationStartedPayloadDTO {
   targetMessageId?: string;
   characterId?: string;
   characterName?: string;
+  breakdown?: AssemblyBreakdownEntryDTO[];
 }
 
 /** Payload for `STREAM_TOKEN_RECEIVED` events. */
@@ -1108,7 +1241,13 @@ export type WorkerToHost =
   | { type: "unregister_macro"; name: string }
   | { type: "update_macro_value"; name: string; value: string }
   | { type: "register_interceptor"; priority?: number }
-  | { type: "intercept_result"; requestId: string; messages: LlmMessageDTO[]; parameters?: Record<string, unknown> }
+  | {
+      type: "intercept_result";
+      requestId: string;
+      messages: LlmMessageDTO[];
+      parameters?: Record<string, unknown>;
+      breakdown?: InterceptorBreakdownEntryDTO[];
+    }
   | { type: "register_tool"; tool: ToolRegistrationDTO }
   | { type: "unregister_tool"; name: string }
   | { type: "request_generation"; requestId: string; input: GenerationRequestDTO }
@@ -1271,6 +1410,20 @@ export type WorkerToHost =
       requestId: string;
       context: unknown;
     }
+  // ─── Macro Interceptor (gated: "macro_interceptor") ────────────────
+  | { type: "register_macro_interceptor"; priority?: number }
+  | {
+      type: "macro_interceptor_result";
+      requestId: string;
+      result: MacroInterceptorResultDTO;
+    }
+  // ─── Message Content Processor (gated: "chat_mutation") ────────────
+  | { type: "register_message_content_processor"; priority?: number }
+  | {
+      type: "message_content_processor_result";
+      requestId: string;
+      result: MessageContentProcessorResultDTO | void;
+    }
   | {
       type: "macro_result";
       requestId: string;
@@ -1444,6 +1597,16 @@ export type HostToWorker =
       requestId: string;
       context: unknown;
     }
+  | {
+      type: "macro_interceptor_request";
+      requestId: string;
+      ctx: MacroInterceptorCtxDTO;
+    }
+  | {
+      type: "message_content_processor_request";
+      requestId: string;
+      ctx: MessageContentProcessorCtxDTO;
+    }
   | {
       type: "response";
       requestId: string;

package/src/dom.ts

@@ -135,6 +135,7 @@ export interface SpindleAppMountHandle {
 export interface SpindleInputBarActionOptions {
   id: string;
   label: string;
+  subtitle?: string;
   iconSvg?: string;
   iconUrl?: string;
   enabled?: boolean;
@@ -143,6 +144,7 @@ export interface SpindleInputBarActionOptions {
 export interface SpindleInputBarActionHandle {
   actionId: string;
   setLabel(label: string): void;
+  setSubtitle(subtitle?: string): void;
   setEnabled(enabled: boolean): void;
   onClick(handler: () => void): () => void;
   destroy(): void;

package/src/index.ts

@@ -14,6 +14,7 @@ export { SpindleEvent, CoreEventType } from "./events";
 
 export type {
   LlmMessageDTO,
+  InterceptorBreakdownEntryDTO,
   InterceptorResultDTO,
   MacroDefinitionDTO,
   MacroInvocationContextDTO,
@@ -80,6 +81,13 @@ export type {
   TokenModelSourceDTO,
   TokenCountOptionsDTO,
   TokenCountResultDTO,
+  MacroInterceptorPhase,
+  MacroInterceptorEnvDTO,
+  MacroInterceptorCtxDTO,
+  MacroInterceptorResultDTO,
+  MessageContentProcessorOrigin,
+  MessageContentProcessorCtxDTO,
+  MessageContentProcessorResultDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";

package/src/permissions.ts

@@ -4,15 +4,16 @@
  * Free tier (no declaration needed): events, storage, macros, dom, variables
  *
  * Gated tier (must declare):
- * - "generation"       — fire generations on behalf of user
- * - "interceptor"      — pre-generation prompt modification
- * - "tools"            — register LLM tools
- * - "cors_proxy"       — use CORS proxy
- * - "context_handler"  — register global context middleware
+ * - "generation"           — fire generations on behalf of user
+ * - "interceptor"          — pre-generation prompt modification
+ * - "tools"                — register LLM tools
+ * - "cors_proxy"           — use CORS proxy
+ * - "context_handler"      — register global context middleware
  * - "generation_parameters" — inject parameters into in-flight generations via interceptors
- * - "characters"       — CRUD on character cards
- * - "chats"            — CRUD on chat sessions
- * - "personas"         — CRUD on personas
+ * - "characters"           — CRUD on character cards
+ * - "chats"                — CRUD on chat sessions
+ * - "personas"             — CRUD on personas
+ * - "macro_interceptor"    — transform raw templates before macro parsing/dispatch
  */
 export type SpindlePermission =
   | "generation"
@@ -32,7 +33,8 @@ export type SpindlePermission =
   | "personas"
   | "push_notification"
   | "image_gen"
-  | "generation_parameters";
+  | "generation_parameters"
+  | "macro_interceptor";
 
 export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "generation",
@@ -53,6 +55,7 @@ export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "push_notification",
   "image_gen",
   "generation_parameters",
+  "macro_interceptor",
 ] as const;
 
 export function isValidPermission(p: string): p is SpindlePermission {

package/src/spindle-api.ts

@@ -53,6 +53,10 @@ import type {
   StreamChunkDTO,
   TokenCountOptionsDTO,
   TokenCountResultDTO,
+  MacroInterceptorCtxDTO,
+  MacroInterceptorResultDTO,
+  MessageContentProcessorCtxDTO,
+  MessageContentProcessorResultDTO,
 } from "./api";
 
 /** The global `spindle` object available in backend extension workers */
@@ -116,7 +120,9 @@ export interface SpindleAPI {
    * The handler receives the assembled messages and a context object, and may
    * return either a plain `LlmMessageDTO[]` (backwards-compatible) or an
    * `InterceptorResultDTO` to also inject generation parameters into the
-   * outgoing LLM request.
+   * outgoing LLM request. `InterceptorResultDTO.breakdown` can be used to mark
+   * specific injected messages as Prompt Breakdown entries so dry-run/live UI
+   * and saved breakdowns can attribute them back to the extension.
    *
    * Returning `parameters` requires the `generation_parameters` permission.
    * Without it, returned parameters are silently stripped.
@@ -674,6 +680,82 @@ export interface SpindleAPI {
     priority?: number
   ): void;
 
+  /**
+   * Register a macro interceptor (permission: `macro_interceptor`).
+   *
+   * Runs at the top of `MacroEvaluator.evaluate()`, once per fixed-point
+   * iteration, before Lumiverse parses the template. Receives the raw
+   * template plus a read-only env snapshot and returns either a transformed
+   * template or `void` to pass through.
+   *
+   * Use this when per-macro RPC cost dominates iteration-heavy templates
+   * (e.g. `{{#each LARGE_LIST}}…{{my_macro}}…{{/each}}`). For single macros
+   * without iteration, prefer {@link SpindleAPI.registerMacro}.
+   *
+   * Each invocation runs inside a 10-second wall-clock budget on the host.
+   * On timeout or thrown error the chain logs the failure and forwards the
+   * previous template to the next handler — macro evaluation itself never
+   * aborts. A second registration from the same extension replaces the
+   * previous handler.
+   *
+   * @param handler  Returns the transformed template, or `void` to pass through.
+   * @param priority Lower values run first. Default `100`.
+   *
+   * @example
+   * ```ts
+   * spindle.registerMacroInterceptor(async (ctx) => {
+   *   if (!ctx.template.includes('{{my_macro')) return
+   *   return resolveInWorker(ctx.template, ctx.env)
+   * }, 100)
+   * ```
+   */
+  registerMacroInterceptor(
+    handler: (
+      ctx: MacroInterceptorCtxDTO
+    ) => Promise<MacroInterceptorResultDTO>,
+    priority?: number
+  ): void;
+
+  /**
+   * Register a message content processor (permission: `chat_mutation`).
+   *
+   * Runs synchronously inside every user-initiated message-write REST
+   * route (create, update, swipe add/update) and the auto-greeting path,
+   * before the row reaches SQLite. The returned patch transforms both the
+   * stored row and every `MESSAGE_SENT` / `MESSAGE_EDITED` / `MESSAGE_SWIPED`
+   * subscriber on first paint.
+   *
+   * Not invoked for `spindle.chat.*` mutations — those paths intentionally
+   * bypass the processor chain to avoid loops on an extension's own writes.
+   *
+   * Each invocation runs inside a 10-second wall-clock budget on the host.
+   * On timeout or thrown error the chain logs the failure and forwards the
+   * previous content to the next handler — the write still proceeds. A
+   * second registration from the same extension replaces the previous
+   * handler.
+   *
+   * Every millisecond of handler work is visible latency on send/edit/swipe.
+   * Keep handlers tight.
+   *
+   * @param handler  Receives the about-to-be-committed content; returns a
+   *                 patch, or `void` to pass through.
+   * @param priority Lower values run first. Default `100`.
+   *
+   * @example
+   * ```ts
+   * spindle.registerMessageContentProcessor(async (ctx) => {
+   *   if (!ctx.content.includes('{{my_macro}}')) return
+   *   return { content: ctx.content.replaceAll('{{my_macro}}', 'resolved') }
+   * }, 50)
+   * ```
+   */
+  registerMessageContentProcessor(
+    handler: (
+      ctx: MessageContentProcessorCtxDTO
+    ) => Promise<MessageContentProcessorResultDTO | void>,
+    priority?: number
+  ): void;
+
   /**
    * Send a message to the frontend module.
    *