Message Content Processor¶

Message content processors run before a user-initiated message write reaches the database. They can transform content and extra so the stored row and every WebSocket subscriber see the transformed version on first paint.

spindle.registerMessageContentProcessor(async (ctx) => {
  if (!ctx.content.includes('{{my_macro}}')) return

  return {
    content: ctx.content.replaceAll('{{my_macro}}', 'resolved value'),
  }
}, 50) // priority: lower runs first (default: 100)

Use this when the transform belongs on the stored message itself, not just on the in-flight LLM call.

Parameters¶

Context Object¶

interface MessageContentProcessorCtx {
  chatId: string
  messageId?: string                              // undefined for "create"
  content: string
  extra?: Record<string, unknown>                 // populated with { role, is_user } for "render"
  origin: "create" | "update" | "swipe_add" | "swipe_update" | "render"
  swipeIndex?: number                             // set for "swipe_update"
  userId: string                                  // pass to operator-scoped Spindle calls
}

Origin values¶

Returned extra is ignored on swipe origins: swipes share the parent message's extra, which addSwipe and updateSwipe cannot patch. Only content is honored.

Returned extra is also ignored on render. There is no row to mutate, so only content is honored.

Cycling through existing swipes ({direction: "left"|"right"}) does not fire the hook; no content changes.

Render origin¶

render is a non-persisting origin. The frontend calls POST /api/v1/chats/:chatId/display-preprocess once per visible message, the chain runs in the same priority order as write-time origins, and the returned content feeds into the display-regex pass before the host's richHtmlSanitizer paints it.

The transformed content is visible only on the rendered message. It is invisible to:

• spindle.chat.getMessages() and any other read of the stored row
• write-time origins (create, update, swipe_add, swipe_update)
• chat memory embeddings, prompt assembly, and exports

Use render for per-render rewrites that depend on transient or per-message context (chat-var values, the message's own position, etc.) and would pollute history if persisted. Use a write-time origin when the transform belongs on the stored message itself.

The render context populates extra with hints from the calling frontend:

messageId is set on the context when the rendered message has one. The route accepts an optional messageIndex body field that lands on extra.messageIndex if supplied by the caller.

Return Value¶

interface MessageContentProcessorResult {
  content?: string
  extra?: Record<string, unknown>
}

Return undefined or void to pass through. Otherwise:

• content: if present, replaces the content for downstream processors and the database write.
• extra: if present, shallow-merges into the existing extra (omitted keys preserved, included keys overwrite).

Composition Order¶

Multiple processors run in priority order (lower first, default 100), with registration order as the tie-breaker. Each processor sees the previous one's returned patch.

Timeout¶

Each processor runs inside a 10-second wall-clock budget. On timeout or thrown error: the chain logs the failure and forwards the previous content to the next handler. The write still proceeds.

Message Content Processor vs Interceptor vs Context Handler¶