feat(plugins): add plugin system with guardrail phases, streaming hooks and route strategies

[SantiagoDePolonia]

Summary

Adds a plugin system and rebuilds guardrails on top of it. Guardrail definitions become plugin instances, workflows gain response and stream phases next to the prompt phase, and virtual models can delegate routing to a plugin.

Design: docs/adr/0012-plugin-system.md, spec in docs/dev/2026-09-03_plugins-and-guardrails-spec.md (status header lists deviations).

User-visible changes

• Plugin contract pluginapi/ (stdlib-only): Plugin + optional PromptHook, ResponseHook, StreamHook, RouteStrategy; Exchange with Prompt, Completion, StreamState, Headers, Values; decisions allow | block | respond | warn.
• Built-in plugins: system_prompt, llm_based_altering (now also on responses), string_replace (multi-line rules, literal/regex, replace/block/respond/warn, streams), header_edit, llm_judge (LLM as judge for prompts and responses), cheapest_healthy (route strategy example).
• Guardrails: definitions gain fail_mode and timeout_ms; GET /admin/guardrails/types exposes phases, source, mutates.
• Workflows: payload v2 with steps[].phase (prompt | response | stream); v1 guardrails payloads still load. GET /admin/workflows/guardrails now returns objects {name, type, phases, summary} instead of strings.
• Streaming: transform mode with lookbehind and buffer mode with keep-alive comments, for chat and Responses streams. Blocked streams end with a proper termination event.
• External plugins: plugins.search_paths / plugins.load[] (sha256 pins) load .so files; gomodel plugin build and gomodel plugin inspect; Dockerfile.plugins; example at examples/plugins/keywordblock.
• Virtual models: strategy: plugin with strategy_plugin and strategy_config, validated against the plugin's route fields.
• Admin API: new GET /admin/plugins.
• Dashboard: schema-driven guardrail editor, Plugins list, workflow step phases, plugin strategies in the virtual model editor.
• Docs: docs/advanced/plugins.mdx (new), guardrails, workflows, admin endpoints, CLI, virtual models.

Known gaps (documented in ADR-0012 §10)

• request and complete hooks are in the contract but not called yet.
• Headers.Upstream is not forwarded; Host.History is unavailable; route strategies do not receive the prompt.
• Response phase does not run on response-cache hits.
• Old guardrail instances are not Closed on refresh.

Verification

• go test across ./cmd ./config ./ext ./internal ./run ./pluginapi and go test -tags=e2e ./tests/e2e/... (includes loading a real .so).
• golangci-lint 0 issues; dashboard tests, build and check clean.
• Hot-path perf guard within ceilings (request state maps are created lazily so a request without plugins allocates only the context value).

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
gomodel	🟢 Ready	View Preview	Sep 4, 2026, 12:12 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}