lumiverse-spindle-types 0.4.57 → 0.4.59

package/package.json

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

package/src/api.ts

@@ -97,6 +97,12 @@ export interface MacroInterceptorEnvDTO {
     readonly global: Record<string, string>;
     readonly chat: Record<string, string>;
   };
+  /**
+   * Per-call dynamic macros injected by the caller (e.g. display-regex
+   * pre-resolution passes `chat_index` here). Keys merge into the macro
+   * lookup table for the duration of one resolve() call.
+   */
+  readonly dynamicMacros: Record<string, string>;
   readonly extra: Record<string, unknown>;
 }
 
@@ -138,7 +144,8 @@ export type MessageContentProcessorOrigin =
   | "create"
   | "update"
   | "swipe_add"
-  | "swipe_update";
+  | "swipe_update"
+  | "render";
 
 /**
  * Context passed to a message content processor before a user-initiated
@@ -667,6 +674,166 @@ export interface WorldBookEntryCreateDTO {
 
 export type WorldBookEntryUpdateDTO = WorldBookEntryCreateDTO;
 
+// ─── Regex Script DTOs ──────────────────────────────────────────────────
+
+export type RegexPlacementDTO = "user_input" | "ai_output" | "world_info" | "reasoning";
+export type RegexScopeDTO = "global" | "character" | "chat";
+export type RegexTargetDTO = "prompt" | "response" | "display";
+export type RegexMacroModeDTO = "none" | "raw" | "escaped";
+
+export interface RegexScriptDTO {
+  id: string;
+  name: string;
+  script_id: string;
+  find_regex: string;
+  replace_string: string;
+  flags: string;
+  placement: RegexPlacementDTO[];
+  scope: RegexScopeDTO;
+  scope_id: string | null;
+  target: RegexTargetDTO;
+  min_depth: number | null;
+  max_depth: number | null;
+  trim_strings: string[];
+  run_on_edit: boolean;
+  substitute_macros: RegexMacroModeDTO;
+  disabled: boolean;
+  sort_order: number;
+  description: string;
+  folder: string;
+  metadata: Record<string, unknown>;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface RegexScriptListOptionsDTO {
+  scope?: RegexScopeDTO;
+  scopeId?: string;
+  target?: RegexTargetDTO;
+  limit?: number;
+  offset?: number;
+  userId?: string;
+}
+
+export interface RegexScriptActiveOptionsDTO {
+  target: RegexTargetDTO;
+  characterId?: string;
+  chatId?: string;
+  userId?: string;
+}
+
+export interface RegexScriptCreateDTO {
+  name: string;
+  find_regex: string;
+  replace_string?: string;
+  flags?: string;
+  placement?: RegexPlacementDTO[];
+  scope?: RegexScopeDTO;
+  scope_id?: string | null;
+  target?: RegexTargetDTO;
+  min_depth?: number | null;
+  max_depth?: number | null;
+  trim_strings?: string[];
+  run_on_edit?: boolean;
+  substitute_macros?: RegexMacroModeDTO;
+  disabled?: boolean;
+  sort_order?: number;
+  description?: string;
+  folder?: string;
+  metadata?: Record<string, unknown>;
+  script_id?: string;
+}
+
+export type RegexScriptUpdateDTO = Partial<RegexScriptCreateDTO>;
+
+// ─── World Info Interceptor (permission: "generation") ─────────────────
+
+/**
+ * One world info entry exposed to a `registerWorldInfoInterceptor` handler.
+ * Subset of `WorldBookEntryDTO` covering the fields the interceptor needs to
+ * inspect for activation gating.
+ */
+export interface WorldInfoInterceptorEntryDTO {
+  readonly id: string;
+  readonly world_book_id: string;
+  readonly comment: string;
+  readonly disabled: boolean;
+  readonly constant: boolean;
+  readonly extensions: Readonly<Record<string, unknown>>;
+  readonly key: readonly string[];
+  readonly keysecondary: readonly string[];
+  readonly position: number;
+  readonly depth: number;
+  readonly priority: number;
+  readonly probability: number;
+  readonly use_probability: boolean;
+  readonly content: string;
+  readonly automation_id: string | null;
+  readonly selective: boolean;
+  readonly selective_logic: number;
+  readonly match_whole_words: boolean;
+  readonly case_sensitive: boolean;
+  readonly use_regex: boolean;
+  readonly prevent_recursion: boolean;
+  readonly exclude_recursion: boolean;
+  readonly delay_until_recursion: boolean;
+  readonly scan_depth: number | null;
+  readonly order_value: number;
+}
+
+/**
+ * One chat message exposed to a `registerWorldInfoInterceptor` handler.
+ * `index_in_chat` is the zero-based position in the chat's message list and
+ * `is_greeting` is true for the synthetic greeting row at index 0.
+ */
+export interface WorldInfoInterceptorMessageDTO {
+  readonly id: string;
+  readonly role: "system" | "user" | "assistant";
+  readonly content: string;
+  readonly is_user: boolean;
+  readonly is_greeting: boolean;
+  readonly greeting_index?: number;
+  readonly swipe_id: number;
+  readonly index_in_chat: number;
+}
+
+/**
+ * Context passed to a `registerWorldInfoInterceptor` handler. Fires inside
+ * `assemblePrompt` immediately before `activateWorldInfo` runs, so any
+ * `disabled` / `enabled` / `forced` votes affect activation and downstream
+ * token-budget calculation.
+ */
+export interface WorldInfoInterceptorCtxDTO {
+  readonly chatId: string;
+  readonly characterId: string;
+  readonly userId?: string;
+  readonly entries: readonly WorldInfoInterceptorEntryDTO[];
+  readonly messages: readonly WorldInfoInterceptorMessageDTO[];
+  readonly chatTurn: number;
+  readonly chatMetadata: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Per-entry content override emitted by a `registerWorldInfoInterceptor`
+ * handler. `content` replaces the entry's `content` for this prompt only.
+ */
+export interface WorldInfoInterceptorMutationDTO {
+  readonly id: string;
+  readonly content?: string;
+}
+
+/**
+ * Return value of a `registerWorldInfoInterceptor` handler. Each list is
+ * additive — handlers chain in priority order and a later handler sees the
+ * prior handlers' votes applied.
+ */
+export interface WorldInfoInterceptorResultDTO {
+  readonly disabled?: readonly string[];
+  readonly enabled?: readonly string[];
+  readonly forced?: readonly string[];
+  readonly mutated?: readonly WorldInfoInterceptorMutationDTO[];
+}
+
 // ─── Databank DTOs ───────────────────────────────────────────────────────
 
 export type DatabankScopeDTO = "global" | "character" | "chat";
@@ -1796,6 +1963,13 @@ export type WorkerToHost =
       requestId: string;
       result: MacroInterceptorResultDTO;
     }
+  // ─── World Info Interceptor (gated: "generation") ──────────────────
+  | { type: "register_world_info_interceptor"; priority?: number }
+  | {
+      type: "world_info_interceptor_result";
+      requestId: string;
+      result: WorldInfoInterceptorResultDTO | null;
+    }
   // ─── Message Content Processor (gated: "chat_mutation") ────────────
   | { type: "register_message_content_processor"; priority?: number }
   | {
@@ -1911,6 +2085,13 @@ export type WorkerToHost =
   | { type: "council_get_available_lumia_items"; requestId: string; userId?: string }
   // ─── Activated World Info (gated: "world_books") ───────────────────
   | { type: "world_books_get_activated"; requestId: string; chatId: string; userId?: string }
+  // ─── Regex Scripts (gated: "regex_scripts") ────────────────────────
+  | { type: "regex_scripts_list"; requestId: string; scope?: RegexScopeDTO; scopeId?: string; target?: RegexTargetDTO; limit?: number; offset?: number; userId?: string }
+  | { type: "regex_scripts_get"; requestId: string; scriptId: string; userId?: string }
+  | { type: "regex_scripts_get_active"; requestId: string; target: RegexTargetDTO; characterId?: string; chatId?: string; userId?: string }
+  | { type: "regex_scripts_create"; requestId: string; input: RegexScriptCreateDTO; userId?: string }
+  | { type: "regex_scripts_update"; requestId: string; scriptId: string; input: RegexScriptUpdateDTO; userId?: string }
+  | { type: "regex_scripts_delete"; requestId: string; scriptId: string; userId?: string }
   // ─── Dry Run (gated: "generation") ────────────────────────────────
   | { type: "generate_dry_run"; requestId: string; input: DryRunRequestDTO; userId?: string }
   // ─── Chat Memories (gated: "chats") ───────────────────────────────
@@ -2050,6 +2231,11 @@ export type HostToWorker =
       requestId: string;
       ctx: MacroInterceptorCtxDTO;
     }
+  | {
+      type: "world_info_interceptor_request";
+      requestId: string;
+      ctx: WorldInfoInterceptorCtxDTO;
+    }
   | {
       type: "message_content_processor_request";
       requestId: string;

package/src/events.ts

@@ -36,6 +36,8 @@ export enum CoreEventType {
   CONNECTION_PROFILE_LOADED = "CONNECTION_PROFILE_LOADED",
   MAIN_API_CHANGED = "MAIN_API_CHANGED",
   WORLD_INFO_ACTIVATED = "WORLD_INFO_ACTIVATED",
+  REGEX_SCRIPT_CHANGED = "REGEX_SCRIPT_CHANGED",
+  REGEX_SCRIPT_DELETED = "REGEX_SCRIPT_DELETED",
   MESSAGE_TAG_INTERCEPTED = "MESSAGE_TAG_INTERCEPTED",
   TOOL_INVOCATION = "TOOL_INVOCATION",
 }

package/src/index.ts

@@ -42,6 +42,20 @@ export type {
   WorldBookEntryDTO,
   WorldBookEntryCreateDTO,
   WorldBookEntryUpdateDTO,
+  RegexPlacementDTO,
+  RegexScopeDTO,
+  RegexTargetDTO,
+  RegexMacroModeDTO,
+  RegexScriptDTO,
+  RegexScriptCreateDTO,
+  RegexScriptUpdateDTO,
+  RegexScriptListOptionsDTO,
+  RegexScriptActiveOptionsDTO,
+  WorldInfoInterceptorEntryDTO,
+  WorldInfoInterceptorMessageDTO,
+  WorldInfoInterceptorCtxDTO,
+  WorldInfoInterceptorMutationDTO,
+  WorldInfoInterceptorResultDTO,
   DatabankScopeDTO,
   DatabankDocumentStatusDTO,
   DatabankDTO,

package/src/permissions.ts

@@ -31,6 +31,7 @@ export type SpindlePermission =
   | "characters"
   | "chats"
   | "world_books"
+  | "regex_scripts"
   | "databanks"
   | "personas"
   | "push_notification"
@@ -54,6 +55,7 @@ export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "characters",
   "chats",
   "world_books",
+  "regex_scripts",
   "databanks",
   "personas",
   "push_notification",

package/src/spindle-api.ts

@@ -27,6 +27,11 @@ import type {
   WorldBookEntryDTO,
   WorldBookEntryCreateDTO,
   WorldBookEntryUpdateDTO,
+  RegexScriptDTO,
+  RegexScriptCreateDTO,
+  RegexScriptUpdateDTO,
+  RegexScriptListOptionsDTO,
+  RegexScriptActiveOptionsDTO,
   DatabankDTO,
   DatabankCreateDTO,
   DatabankUpdateDTO,
@@ -81,6 +86,8 @@ import type {
   TokenCountResultDTO,
   MacroInterceptorCtxDTO,
   MacroInterceptorResultDTO,
+  WorldInfoInterceptorCtxDTO,
+  WorldInfoInterceptorResultDTO,
   MessageContentProcessorCtxDTO,
   MessageContentProcessorResultDTO,
   SharedRpcRequestContextDTO,
@@ -741,6 +748,24 @@ export interface SpindleAPI {
     getActivated(chatId: string, userId?: string): Promise<ActivatedWorldInfoEntryDTO[]>;
   };
 
+  /**
+   * Regex Scripts CRUD (permission: "regex_scripts").
+   * Full access to regex scripts attached to the user's account, including
+   * global, character-scoped, and chat-scoped rules. Same shape Lumiverse uses
+   * internally during prompt assembly, response baking, and display rendering.
+   * For user-scoped extensions, userId is inferred from the extension owner.
+   * For operator-scoped extensions, pass userId to scope to a specific user.
+   */
+  regex_scripts: {
+    list(options?: RegexScriptListOptionsDTO): Promise<{ data: RegexScriptDTO[]; total: number }>;
+    get(scriptId: string, userId?: string): Promise<RegexScriptDTO | null>;
+    create(input: RegexScriptCreateDTO, userId?: string): Promise<RegexScriptDTO>;
+    update(scriptId: string, input: RegexScriptUpdateDTO, userId?: string): Promise<RegexScriptDTO>;
+    delete(scriptId: string, userId?: string): Promise<boolean>;
+    /** Resolve the enabled scripts that would actually fire for the given target + character/chat context, merged across global + character + chat scopes and ordered by scope tier then sort_order. */
+    getActive(options: RegexScriptActiveOptionsDTO): Promise<RegexScriptDTO[]>;
+  };
+
   /**
    * Databank CRUD (permission: "databanks").
    * Manage databanks plus the documents they contain.
@@ -893,6 +918,39 @@ export interface SpindleAPI {
     priority?: number
   ): void;
 
+  /**
+   * Register a world info interceptor (permission: `generation`).
+   *
+   * Fires inside `assemblePrompt` immediately before `activateWorldInfo`
+   * runs. Handlers can disable, force-enable, or content-override world info
+   * entries based on chat state, message history, or external rules.
+   * Multiple handlers chain in priority order and a later handler sees the
+   * prior handlers' votes applied — useful for cross-entry injection
+   * patterns where one entry merges into another and then disables itself.
+   *
+   * Returning `void` passes the activation set through unchanged. Per-handler
+   * 10s timeout; errors are logged and the chain continues.
+   *
+   * @param handler  Returns the disabled / enabled / forced / mutated lists, or `void`.
+   * @param priority Lower values run first. Default `100`.
+   *
+   * @example
+   * ```ts
+   * spindle.registerWorldInfoInterceptor(async (ctx) => {
+   *   const disabled = ctx.entries
+   *     .filter((e) => e.comment.startsWith("[debug]"))
+   *     .map((e) => e.id)
+   *   return { disabled }
+   * }, 100)
+   * ```
+   */
+  registerWorldInfoInterceptor(
+    handler: (
+      ctx: WorldInfoInterceptorCtxDTO
+    ) => Promise<WorldInfoInterceptorResultDTO | void>,
+    priority?: number
+  ): void;
+
   /**
    * Register a message content processor (permission: `chat_mutation`).
    *