lumiverse-spindle-types 0.4.37 → 0.4.39

package/package.json

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

package/src/api.ts

@@ -67,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;
@@ -267,8 +373,8 @@ export interface ImageGenResultDTO {
 
 /**
  * Safe representation of a character exposed to extensions.
- * Omits the raw `extensions` blob — only exposes user-facing fields plus
- * a small allowlist of structured extension state (e.g. `world_book_ids`).
+ * Includes the full `extensions` blob so extensions can read and write
+ * their own namespaced keys alongside the allowlisted `world_book_ids`.
  */
 export interface CharacterDTO {
   id: string;
@@ -290,6 +396,8 @@ export interface CharacterDTO {
    * single-id form is auto-migrated, so consumers can rely on the array.
    */
   world_book_ids: string[];
+  /** The raw extensions object. Extensions should namespace their keys. */
+  extensions: Record<string, any>;
   created_at: number;
   updated_at: number;
 }
@@ -309,6 +417,8 @@ export interface CharacterCreateDTO {
   creator?: string;
   /** Optional initial world book attachments. */
   world_book_ids?: string[];
+  /** Optional initial extension data. */
+  extensions?: Record<string, any>;
 }
 
 export interface CharacterUpdateDTO {
@@ -329,6 +439,12 @@ export interface CharacterUpdateDTO {
    * detach all books. Omit the field to leave attachments unchanged.
    */
   world_book_ids?: string[];
+  /**
+   * Shallow-merged into the character's existing extensions.
+   * Extension-provided keys overwrite existing ones; omitting a key leaves it
+   * untouched. Pass an empty object to make no changes, or omit entirely.
+   */
+  extensions?: Record<string, any>;
 }
 
 export interface CharacterAvatarUploadDTO {
@@ -1304,6 +1420,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;
@@ -1477,6 +1607,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/index.ts

@@ -81,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 */
@@ -676,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.
    *