Plugins #

Summary #

SCN Chat's features beyond the core chat loop come from plugins: model providers, tools the model can call, file ingesters that turn uploads into text, and hooks that run around each turn. A plugin is an npm package that exports a factory. The admin lists plugins by package name, with their options, in config.yml. At startup the server imports each package, validates its options against the schema the plugin exports, checks the plugin, and calls its setup function, which registers what the plugin provides. The types plugins build against live in their own package, @scn-chat/plugin-api, so third parties can write plugins without depending on the server.

Motivation #

The project is meant to be extended and forked. Anyone should be able to add a model provider, a search engine, or an OCR engine without touching core code. Other chat apps either have no code-level plugin system (Chatbot UI, LibreChat, which relies on YAML config and MCP) or store pasted code in the database without versioning (Open WebUI). Using npm packages gives versioning, lockfiles, and ordinary code review for free, and options validated against each plugin's schema catch configuration mistakes at startup.

The design borrows from several systems:

• Drupal's split between registries and hooks. Some extension points pick one implementation by ID (Drupal's Plugin API). Others let many plugins act on the same event (Drupal hooks, WordPress actions and filters).
• Vite's plugin shape. A plugin is a factory returning a plain typed object, and the config lists plugins in order.
• LibreChat's config split. Public settings go in a YAML file and secrets in .env.
• Open WebUI's settings split. Admin settings and per-user settings are separate, and forms are generated from a schema.
• Fastify and VS Code's compatibility checks. Each plugin declares which plugin API version it targets, and incompatible plugins are refused at startup.

Design #

Packages #

• packages/plugin-api (@scn-chat/plugin-api) exports definePlugin and every type a plugin sees. It depends only on zod, @scn-chat/lexicons, and @ai-sdk/provider for the model interface. It has its own semver version, separate from the app. Inside the workspace it exports TypeScript source like every other package. Publishing it to npm for third-party authors, built to JavaScript with type declarations, is a later step.
• plugins/* holds the plugins that ship with SCN Chat, each its own workspace package named @scn-chat/plugin-<name>. The specs for providers, attachments, and titles define the phase 1 plugins.
• The server depends on @scn-chat/plugin-api and implements the registries, hooks, and context behind it.

Config file #

Plugins are listed in the plugins section of config.yml, described in the foundation spec, in the order they load:

plugins:
  - package: '@scn-chat/plugin-anthropic'
    options:
      apiKey: ${ANTHROPIC_API_KEY}
  - package: '@scn-chat/plugin-openai-compatible'
    options:
      id: cocore
      name: co/core
      baseURL: https://cocore.dev/v1
      apiKey: ${COCORE_API_KEY}
  - package: '@scn-chat/plugin-pdf-text'
  - package: '@scn-chat/plugin-titles'

• package is an npm package name, or a path starting with ./ for a local plugin. It is resolved from the directory holding config.yml, so a plugin installed in the project with pnpm add is found.
• options are the plugin's admin settings. Secrets come from .env through ${NAME} references, never from the file itself.
• The same package may be listed more than once with different options, as the OpenAI-compatible plugin is for each endpoint.

The models list is described in the providers spec, roles in the auth spec, and sync in the chat-storage spec.

Plugin shape #

export default function titles(options: TitlesOptions = {}) {
  return definePlugin({
    id: 'titles',
    name: 'Chat titles',
    apiVersion: 1,
    setup(ctx) {
      ctx.hooks.on('turn:after', async (turn) => { /* ... */ })
    },
  })
}

A plugin package exports:

• A default export, the factory, which takes the options object and returns a plugin.
• An optional optionsSchema, a zod schema for the options. The server validates the configured options against it before calling the factory. A failure stops startup, naming the package and the option. A plugin without a schema gets its options unchecked.

The plugin the factory returns:

• id is unique across loaded plugins, and matches ^[a-z0-9-]+$.
• apiVersion is the plugin API major version the plugin targets. The server supports exactly version 1 in phase 1.
• userSettings is an optional zod schema for per-user settings. Fields marked with .meta({ secret: true }) are stored encrypted.
• setup(ctx) runs once at startup and may be async. Startup waits for every setup to finish, in config order.

Plugin context #

setup receives a narrow context. It has no raw database handle and no access to OAuth sessions, so a plugin cannot bypass record ownership by accident.

Member	Purpose
ctx.providers.register(provider)	Add a model provider. See the providers spec.
ctx.tools.register(tool)	Add a tool the model can call.
ctx.toolSources.register(source)	Add a source of tools that change at runtime, such as an MCP server.
ctx.ingesters.register(ingester)	Add a file ingester. See the attachments spec.
ctx.hooks.on(name, handler, options?)	Handle a hook.
ctx.models.generateText(request)	Run a one-off model call for a user, through the provider registry.
ctx.conversations.updateInfo(user, conversation, patch)	Change a conversation's info record, written under the user's DID through the storage layer.
ctx.userSettings(user)	Read this plugin's validated settings for a user.
ctx.logger	A pino child logger tagged with the plugin ID.
ctx.app	Read-only app name and public URL.
ctx.onClose(fn)	Register cleanup to run at shutdown.

Registries #

Registries hold implementations picked by ID or by match. Registering a duplicate ID fails startup.

• Providers, picked by provider ID. The providers spec defines the interface.
• Tools, picked by name. A tool has a name, a description, a zod inputSchema, and run(input, context), which returns text or JSON-encodable data. A result that would push the record past the size cap is stored as a blob. The web-search spec adds tool switches, untrusted output, and the tool context's fetch, cite, and turnCache.
• Tool sources, each with list(user) and call(user, name, input). Their tools are merged with registered tools, with names prefixed by the source ID.
• Ingesters, matched by MIME type. The attachments spec defines the interface.

The web search and fetch plugins are the first tools. MCP servers are expected to arrive as tool sources.

Hooks #

Hooks let many plugins act on the same event. Every payload uses our own normalized types, never a provider's raw request or response shape.

Hook	Kind	Payload
messages:beforeModel	filter	The system prompt and message list about to be sent, with the turn context
message:afterModel	filter	The assistant's final content before it is written, with the turn context
turn:after	action	The finished turn: conversation, user, request, and the written reply
conversation:created	action	The new conversation and its owner
conversation:deleted	action	The deleted conversation and its owner

• Filters run in order, and each handler returns the value the next one receives. A filter that throws fails the turn, which ends with status error and an error naming the plugin.
• Actions run in order, and their return values are ignored. An action that throws is logged with the plugin ID, and the turn is unaffected.
• Order. Handlers are sorted by options.order ('pre', 'normal', or 'post', default 'normal'), then by the plugin's position in the config. There are no numeric priorities. The server logs each hook's resolved handler order at startup.

The hook runner is a small typed module in the server, about 80 lines, that handles ordering, filter chaining, and action error isolation. The hookable library has no ordering and cannot pass a value through a chain of handlers, which filters need. tapable has both, but needs a class per hook.

Per-user settings #

Per-user settings are stored in a plugin_user_settings table: DID, plugin ID, JSON value, and a separate encrypted JSON value for secret fields. Values are validated against the plugin's schema on read. Invalid stored values fail loudly and are not silently reset. The settings page shows the validation error for that plugin with a reset button, which calls DELETE /api/plugins/:id/settings and clears the user's stored values for it. The web UI renders a settings form from z.toJSONSchema(userSettings), as the web-ui spec describes. Secret fields are encrypted with the same key and scheme as BYO API keys, described in the providers spec.

Scope Boundaries #

• No admin UI for installing or configuring plugins. Admins edit the config file and restart.
• No sandboxing. Plugins run in-process with full trust, and the docs say so.
• No user-installed plugins. If users ever add their own tools, that goes through MCP, not in-process code.
• No plugins that add UI to the web app.
• No filter over individual streaming chunks in phase 1.
• No built-in tools in phase 1.

Edge Cases and Decisions #

• Plugins are listed explicitly in config.yml, not discovered by scanning node_modules, which is unreliable under pnpm.
• Configuration is YAML, not a TypeScript file, so admins who are not developers can edit it. The plugin option schemas replace the type-checking a TypeScript file gave.
• Hook ordering uses config position plus pre, normal, and post, not numeric priorities, to avoid WordPress's priority guessing.
• Filter errors fail the turn, and action errors do not. A filter changes what the model sees or what gets written, so skipping one silently could corrupt a conversation.
• Plugin output that becomes a record goes through the context's storage methods, so it is always written under the user's DID.
• ModelProvider gained an optional providerOptions, sent with every call to that provider. The OpenAI plugin needs store: false and encrypted reasoning on every request, and the interface had nowhere to say so.
• ModelAccess carries an optional fetch, so a user endpoint can be reached through the private network guard.
• @scn-chat/plugin-api/testing exports setupForTest, which runs a plugin's setup against a recording context, for plugin tests.
• The per-user settings API is GET /api/plugins/settings, PUT /api/plugins/:id/settings, and DELETE /api/plugins/:id/settings. Secret values are never returned. A blank secret on save keeps the stored one.
• An OpenAI-compatible plugin's ID is openai-compatible-<provider id>, so the same package can be listed several times.
• A local plugin directory is loaded through its package.json exports or main, since Node's resolver ignores exports for directory paths.
• The server's config types (ModelConfig, SyncConfig) live in the server, since plugins never see them.

Acceptance Criteria #

• The server imports the plugins listed in config.yml in order and calls each setup once.
• A plugin package is resolved from the directory holding config.yml, and a ./ path loads a local plugin.
• Options that fail a plugin's schema stop startup, naming the package and the option.
• A package that cannot be found stops startup, naming it.
• Two plugins with the same ID fail startup, naming the ID.
• A plugin with an unsupported apiVersion fails startup, naming the plugin and version.
• Registering a duplicate provider ID, tool name, or ingester ID fails startup.
• Filter handlers run in order, with pre before normal before post, and config order within each group.
• Each filter receives the previous filter's return value.
• A throwing filter fails the turn with an error naming the plugin.
• A throwing action is logged and does not affect the turn or later actions.
• Per-user settings round-trip through storage, with secret fields stored encrypted and returned decrypted.
• Stored per-user settings that fail validation raise an error instead of being reset.
• Deleting a plugin's settings clears the user's stored values, so the schema defaults apply.
• ctx.conversations.updateInfo writes through the storage layer under the user's DID.