feat: plugin system with hook-based architecture and two built-in plugins

Add a modular plugin system that extends the pipe via lifecycle hooks,
priority-based dispatch, and plugin-exported valves. Seven hooks cover the
full request lifecycle: on_init, on_models, on_request, on_request_transform,
on_emitter_wrap, on_response_transform, and on_shutdown.

Built-in plugins (real use cases, not toy examples):

  - Pipe Stats Dashboard: virtual model exposing a live SSE-powered admin
    diagnostics dashboard with tiered data collection, multi-worker Redis
    aggregation, tabbed UI, and an extensible command system (stats, health,
    config, help). Demonstrates on_models + on_request hooks.

  - Think Streaming: live reasoning and tool execution display via
    SSE-backed iframe embeds. Wraps the stream emitter to copy thinking
    tokens and tool events into a per-session queue, served to the browser
    through a dynamically-registered FastAPI endpoint on OWUI's own app.
    Demonstrates the on_emitter_wrap + on_response_transform hooks.

Both plugins use the same SSE transport pattern: dynamically registering
API routes on OWUI's FastAPI app with ephemeral key authentication, giving
pipe plugins a real-time data channel to the browser without any external
infrastructure.

Also includes: Nagle-style delta coalescing, context budget guards,
tool executor improvements, streaming pipeline hardening, and test
coverage expansion (3536 tests).

Author: rbb-dev

.github/workflows/bundle.yml

@@ -25,8 +25,8 @@ jobs:
 
       - name: Run bundler
         run: |
-          python scripts/bundle.py
-          python scripts/bundle.py --compress
+          python scripts/bundle_v2.py
+          python scripts/bundle_v2.py --compress
 
       - name: Verify bundled files
         run: |

.github/workflows/ci.yml

@@ -36,24 +36,44 @@ jobs:
           uv pip install --python .venv/bin/python torch --index-url https://download.pytorch.org/whl/cpu
           # Install open-webui and project dependencies
           uv pip install --python .venv/bin/python open-webui -e .
-          uv pip install --python .venv/bin/python pytest pytest-asyncio pyright cairosvg pyzipper aioresponses
+          uv pip install --python .venv/bin/python pytest pytest-asyncio pyright cairosvg pyzipper aioresponses ruff
 
-      - name: Run tests and checks
+      - name: Lint source code
         run: |
           source .venv/bin/activate
-          # Build monolith bundles (used by Open WebUI "Import from Link")
-          python scripts/bundle.py
-          python scripts/bundle.py --compress
+          ruff check open_webui_openrouter_pipe/
+
+      - name: Build monolith bundles
+        run: |
+          source .venv/bin/activate
+          python scripts/bundle_v2.py
+          python scripts/bundle_v2.py --compress
+
+      - name: Lint bundles
+        run: |
+          source .venv/bin/activate
+          ruff check open_webui_openrouter_pipe_bundled.py
+          ruff check --per-file-ignores '*_compressed.py:E402' open_webui_openrouter_pipe_bundled_compressed.py
+
+      - name: Type-check source and bundles
+        run: |
+          source .venv/bin/activate
+          pyright
+          pyright open_webui_openrouter_pipe_bundled.py
+          pyright open_webui_openrouter_pipe_bundled_compressed.py
+
+      - name: Run tests
+        run: |
+          source .venv/bin/activate
+          python -m compileall open_webui_openrouter_pipe tests filters open_webui_openrouter_pipe_bundled.py open_webui_openrouter_pipe_bundled_compressed.py
 
           # Run the test suite in 3 modes:
           # 1) Normal package imports (on-disk modules)
-          # 2) Bundled raw monolith
+          # 2) Bundled flat monolith
           # 3) Bundled compressed monolith
           echo "==> pytest (package imports)"
           PYTHONPATH=. pytest tests -q
-          echo "==> pytest (bundled: open_webui_openrouter_pipe_bundled.py)"
+          echo "==> pytest (bundled flat: open_webui_openrouter_pipe_bundled.py)"
           OWUI_PIPE_BUNDLE_PATH=open_webui_openrouter_pipe_bundled.py PYTHONPATH=. pytest tests -q
-          echo "==> pytest (bundled: open_webui_openrouter_pipe_bundled_compressed.py)"
+          echo "==> pytest (bundled compressed: open_webui_openrouter_pipe_bundled_compressed.py)"
           OWUI_PIPE_BUNDLE_PATH=open_webui_openrouter_pipe_bundled_compressed.py PYTHONPATH=. pytest tests -q
-          python -m compileall open_webui_openrouter_pipe tests filters
-          pyright

.gitignore

@@ -20,3 +20,4 @@ cliff.toml
 plans/
 open_webui_openrouter_pipe_bundled.py
 open_webui_openrouter_pipe_bundled_compressed.py
+scripts/deploy_dev.sh

README-dev.md

@@ -143,6 +143,20 @@ Go to **Actions** → select a workflow run → scroll to **Artifacts** → down
 
 ---
 
+## Linting
+
+Production code is linted with [ruff](https://docs.astral.sh/ruff/) in CI. No config file is needed — the command scopes itself:
+
+```bash
+source .venv/bin/activate && ruff check open_webui_openrouter_pipe/
+```
+
+Tests (`tests/`) are **not** linted — patterns like mid-file imports, fixture redefinitions, and assign-to-verify are intentional and would trigger false positives.
+
+> **Warning:** Do not use `ruff --fix`. It cannot detect re-exports and will silently remove imports that other modules depend on. Fix issues manually.
+
+---
+
 ## Key Insight
 
 **Branches are for work, tags are for releases.**

README.md

@@ -1,8 +1,8 @@
 # Open WebUI → OpenRouter Pipe
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-2.2.1-blue.svg)](https://github.com/rbb-dev/Open-WebUI-OpenRouter-pipe)
-[![Open WebUI Compatible](https://img.shields.io/badge/Open%20WebUI-0.7.0%2B-green.svg)](https://openwebui.com/)
+[![Version](https://img.shields.io/badge/version-2.2.11-blue.svg)](https://github.com/rbb-dev/Open-WebUI-OpenRouter-pipe)
+[![Open WebUI Compatible](https://img.shields.io/badge/Open%20WebUI-0.8.0%2B-green.svg)](https://openwebui.com/)
 
 **Access 350+ AI models through one interface.**
 
@@ -70,6 +70,9 @@ Optional encrypted session logs for incident response. Request identifiers flow
 🛡️ **Enterprise Controls**
 Encryption, retention policies, request attribution, and operational hooks your governance program can build on.
 
+🔌 **Plugin System**
+Extend the pipe with custom plugins — inject virtual models, intercept requests, transform payloads before OpenRouter, and post-process responses before delivery. Ships with the Pipe Stats Dashboard plugin as a reference implementation. Disabled by default; enable via valves. See [Plugin System Guide](docs/plugin_system.md).
+
 ---
 
 ## Quick Start
@@ -133,7 +136,7 @@ That's it. Start talking.
 
 ## Requirements
 
-- Open WebUI 0.7.0+
+- Open WebUI 0.8.0+
 - An [OpenRouter](https://openrouter.ai/) account
 - `WEBUI_SECRET_KEY` configured (required for encrypted credential storage)
 

docs/README.md

@@ -20,7 +20,7 @@ Use these docs if you are modifying the pipe, working on tests, or extending the
 ## Quick start (install and use)
 
 ### Prerequisites
-- Open WebUI `0.7.0` or later (the pipe declares this requirement in its manifest header).
+- Open WebUI `0.8.0` or later (the pipe declares this requirement in its manifest header).
 - An OpenRouter API key, provided either via the `OPENROUTER_API_KEY` environment variable or via the pipe’s valve configuration.
 
 ### Install (Open WebUI UI)
@@ -115,5 +115,8 @@ See: [Model Variants & Presets](model_variants_and_presets.md).
 - [Multimodal Ingestion Pipeline](multimodal_ingestion_pipeline.md)
 - [Task Models & Housekeeping](task_models_and_housekeeping.md)
 - [Tooling & Integrations](tooling_and_integrations.md)
+- [Plugin System — Developer Guide](plugin_system.md) — hook-based plugin architecture for extending pipe behavior (model injection, request interception, request/response transformation).
+- [Pipe Stats Dashboard Plugin](plugins_pipe_stats.md) — built-in plugin: virtual model with live SSE dashboard for admin diagnostics.
+- [Think Streaming Plugin](plugins_think_streaming.md) — built-in plugin: live reasoning and tool execution display via SSE-powered iframe embeds.
 - [Test Suite Audit Snapshot](test_suite_audit_snapshot.md) — one-shot snapshot of a completed test audit; not maintained.
 - `CHANGELOG.md` (repo root) — audit trail for changes.

docs/developer_guide_and_architecture.md

@@ -63,7 +63,7 @@ At a high level, a request follows this shape:
 
 4. **Tool-call loop (between Responses calls)**
    - When a Responses run completes, the pipe inspects the returned `output` items.
-   - `function_call` items are executed locally against the Open WebUI tool registry, converted into `function_call_output` items, appended to the next request’s `input[]`, and the loop continues until no further tool calls are produced or `MAX_FUNCTION_CALL_LOOPS` is reached.
+   - `function_call` items are executed locally against the Open WebUI tool registry, converted into `function_call_output` items, appended to the next request’s `input[]`, and the loop continues until no further tool calls are produced or `MAX_FUNCTION_CALL_LOOPS` is reached (at which point the model gets a synthesis turn). Applies only when `TOOL_EXECUTION_MODE="Pipeline"`.
 
 5. **Persistence (optional)**
    - Depending on valves, artifacts (reasoning/tool outputs) are persisted to SQL storage (optionally encrypted and/or compressed) and may be cached in Redis in multi-worker configurations.

docs/model_catalog_and_routing_intelligence.md

@@ -68,7 +68,7 @@ Behavior:
   - `meta.profile_image_url` (model icon as a PNG data URL), and
   - `meta.description` (model description text).
   This behavior is controlled by `UPDATE_MODEL_CAPABILITIES`, `UPDATE_MODEL_IMAGES`, and `UPDATE_MODEL_DESCRIPTIONS`. See: [OpenRouter Integrations & Telemetry](openrouter_integrations_and_telemetry.md).
-  - New model access control defaults are set **on insert only**: `NEW_MODEL_ACCESS_CONTROL` determines whether newly inserted OpenRouter overlays are public (`access_control=None`) or private (`access_control={}`), with the `admins` option relying on Open WebUI’s `BYPASS_ADMIN_ACCESS_CONTROL` for admin access.
+  - New model access control defaults are set **on insert only**: `NEW_MODEL_ACCESS_CONTROL` determines whether newly inserted OpenRouter overlays are public (wildcard read grant) or private (no access grants), with the `admins` option relying on Open WebUI's `BYPASS_ADMIN_ACCESS_CONTROL` for admin access.
 
 ---