World Info Interceptor¶

World info interceptors run before world info activation. They receive the candidate entries plus the current chat state, and return a list of entry IDs to disable for this turn and/or per-entry content overrides.

spindle.registerWorldInfoInterceptor(async (ctx) => {
  const disabled: string[] = []
  for (const entry of ctx.entries) {
    if (entry.constant && ctx.chatTurn < 5) disabled.push(entry.id)
  }
  return { disabled }
}, 100)

Use this when an entry's stored fields can't express the activation rule (turn-based gates, sticky flags, external state lookups, content rewrites driven by retrieval).

Parameters¶

One interceptor per extension; a second registration replaces the first.

Context Object¶

interface WorldInfoInterceptorCtx {
  chatId: string
  characterId: string
  userId?: string
  entries: WorldInfoInterceptorEntry[]
  messages: WorldInfoInterceptorMessage[]
  chatTurn: number
  chatMetadata: Record<string, unknown>
}

interface WorldInfoInterceptorEntry {
  id: string
  world_book_id: string
  comment: string
  disabled: boolean
  constant: boolean
  extensions: Record<string, unknown>
  key: string[]
  keysecondary: string[]
  position: number
  depth: number
  priority: number
  probability: number
  use_probability: boolean
  content: string
  automation_id: string | null
  selective: boolean
  selective_logic: number
  match_whole_words: boolean
  case_sensitive: boolean
  use_regex: boolean
  prevent_recursion: boolean
  exclude_recursion: boolean
  delay_until_recursion: boolean
  scan_depth: number | null
  order_value: number
}

interface WorldInfoInterceptorMessage {
  id: string
  role: "system" | "user" | "assistant"
  content: string
  is_user: boolean
  is_greeting: boolean
  greeting_index?: number
  swipe_id: number
  index_in_chat: number
}

entries reflects the current state of the chain: each interceptor sees the previous one's mutations. disabled: true on an incoming entry can mean either "stored as disabled" or "an earlier interceptor disabled it"; use extensions to mark your own provenance if you need to tell them apart.

chatMetadata is the chat-level metadata blob. Persist cross-turn state here via spindle.chats.update; the snapshot is read-only.

Return Value¶

interface WorldInfoInterceptorResult {
  disabled?: string[]
  enabled?: string[]
  forced?: string[]
  mutated?: { id: string; content?: string }[]
}

Return void (or omit all arrays) for a no-op pass-through. The four axes are independent:

Mutating an entry that another interceptor disabled is allowed but inert.

Composition Order¶

Multiple interceptors run in priority order (lower first), with registration order as the tie-breaker. Each interceptor receives the previous one's mutations applied to the entry list. There is no cap on chain depth.

Vote-off precedence is the chain's invariant: once any handler votes disabled for an entry, no later handler's enabled or forced can revive it. This makes per-handler reasoning order-independent on the disable axis.

Content overrides accumulate last-write-wins: if two handlers set content for the same entry, the higher-priority handler (later in the chain) wins.

Permission Scope¶

registerWorldInfoInterceptor requires the generation permission — the same gate that covers registerInterceptor and registerContextHandler. No additional permission is needed for content overrides.

Timeout¶

Each interceptor runs inside a 10-second wall-clock budget. On timeout or thrown error: the chain logs the failure and forwards the previous entry list to the next handler. World info activation itself never aborts.

World Info Interceptor vs Context Handler vs Interceptor¶