docs(plugins): add plugin dev guide and marketplace documentation by oyi77 · Pull Request #4007 · cheaper-inference/OmniRoute

oyi77 · 2026-06-16T14:51:01Z

Replaces #3787 as a clean, non-contaminated PR branched from release/v3.8.27.

Adds comprehensive plugin documentation:

Plugin Development Guide (dev mode, testing, doctor, signing)
Plugin Marketplace documentation (discovery, publishing, ratings)

Only docs/plugins/ changes, no unrelated churn.

Supersedes: #3787

gemini-code-assist

Code Review

This pull request introduces comprehensive documentation for the OmniRoute plugin system, including guides for plugin development, the marketplace, and the SDK. While the documentation is highly detailed, several critical discrepancies between the documented features and the actual codebase implementation were identified. Specifically, the documentation references unsupported routing and stream events, incorrect code snippets for dev mode, outdated file line counts, and undocumented TypeScript interfaces for onPluginMessage and onRender. Additionally, the documented db and ipc permissions are missing from the PermissionSchema Zod enum, and the onPluginMessage and onRender events are not registered in BUILTIN_EVENTS. These inconsistencies should be resolved to ensure the documentation is accurate and does not mislead developers.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-16T14:52:41Z

+  // Optional routing events
+  onModelSelect: async (ctx) => {
+    /* ... */
+  },
+  onComboResolve: async (ctx) => {
+    /* ... */
+  },
+  onRateLimit: async (ctx) => {
+    /* ... */
+  },
+  onQuotaExhaust: async (ctx) => {
+    /* ... */
+  },
+  onProviderError: async (ctx) => {
+    /* ... */
+  },
+
+  // Stream events
+  onStreamStart: async (ctx) => {
+    /* ... */
+  },
+  onStreamEnd: async (ctx) => {
+    /* ... */
+  },


The routing and stream events listed here (such as onModelSelect, onComboResolve, onRateLimit, onQuotaExhaust, onProviderError, onStreamStart, and onStreamEnd) are currently not supported or registered by the PluginManager (src/lib/plugins/manager.ts) or the loadPlugin function (src/lib/plugins/loader.ts). Only onRequest, onResponse, onError, and the lifecycle hooks (onInstall, onActivate, onDeactivate, onUninstall) are actually loaded and registered. Documenting these unsupported events can mislead developers.

gemini-code-assist · 2026-06-16T14:52:41Z

+
+  watcher = watch(pluginDir, { recursive: true }, (_eventType, filename) => {
+    if (!filename) return;
+    const pluginName = filename.replace(/\\/g, "/").split("/")[0];


The code snippet shown here does not match the actual implementation in src/lib/plugins/devMode.ts. In the codebase, filename.split("/")[0] is used directly without replacing backslashes (which might cause issues on Windows). The documentation should be updated to match the actual code, or the code itself should be updated to handle Windows path separators.

Suggested change

const pluginName = filename.replace(/\\/g, "/").split("/")[0];

const pluginName = filename.split("/")[0];

gemini-code-assist · 2026-06-16T14:52:41Z

+   ───────              ───────────────
+   Local seed           Remote registry
+   registry             with ratings,
+   (3 entries)          downloads, signed


The diagram mentions (3 entries) for the Phase 1 local seed registry, but the registry actually ships with 4 verified plugins (as documented on line 36 and implemented in src/lib/plugins/marketplace.ts). This should be updated to (4 entries) for accuracy.

Suggested change

(3 entries) downloads, signed

(4 entries) downloads, signed

gemini-code-assist · 2026-06-16T14:52:41Z

+
+| File                             | Lines | Purpose                               |
+| -------------------------------- | ----- | ------------------------------------- |
+| `src/lib/plugins/marketplace.ts` | 107   | Marketplace data + API                |


The line counts listed in this table are outdated compared to the actual files in the repository:\n- marketplace.ts has 203 lines (not 107)\n- manager.ts has 569 lines (not 410+)\n- loader.ts has 327 lines (not 280+)\n- manifest.ts has 214 lines (not 200+)\n- signing.ts has 35 lines (not 34)\n\nConsider updating these numbers or removing the exact line counts to avoid maintaining outdated documentation.

gemini-code-assist · 2026-06-16T14:52:41Z

+- `onPluginMessage` (function, optional) — Receives IPC messages from other plugins via `__omniroute.broadcast()` / `__omniroute.sendTo()`
+- `onRender` (function, optional) — Renders a dashboard page when a user visits the plugin's admin page


The onPluginMessage and onRender functions are documented as optional parameters for definePlugin, but they are not defined in PluginDefinition or Plugin interfaces in src/lib/plugins/sdk.ts and src/lib/plugins/hooks.ts. Passing them to definePlugin will result in TypeScript compilation errors. Please update the documentation or the TypeScript definitions to align them.

gemini-code-assist · 2026-06-16T14:52:41Z

+| `db`         | `__omniroute.db` — persistent key-value store (SQLite-backed, isolated per plugin)         |
+| `ipc`        | `__omniroute.broadcast()` / `__omniroute.sendTo()` — cross-plugin messaging                |


The "db" and "ipc" permissions are listed in the permission system table, but they are not included in the PermissionSchema Zod enum in src/lib/plugins/manifest.ts. Any plugin declaring "db" or "ipc" in its plugin.json manifest will fail validation during installation/activation. Please add "db" and "ipc" to the PermissionSchema in src/lib/plugins/manifest.ts or correct the documentation if they are not intended to be declared as permissions.

gemini-code-assist · 2026-06-16T14:52:42Z

+| `onPluginMessage` | IPC message from another plugin           | `{ source, event, data }`                              |
+| `onRender`        | Dashboard page requested                  | `{ slug, params }` — return HTML or structured content |


The onPluginMessage and onRender events are listed under the Built-in Events table, but they are not defined in the BUILTIN_EVENTS array in src/lib/plugins/hooks.ts. As a result, they are unrecognized by the hooks system and will never be triggered. Please ensure these events are added to BUILTIN_EVENTS and properly registered in the plugin loader/manager.

diegosouzapw · 2026-06-16T16:17:58Z

Thanks @oyi77 — heads up: #4006 and #4007 have identical diffs (both add all three docs: PLUGIN_DEVELOPMENT / PLUGIN_MARKETPLACE / PLUGIN_SDK). Please consolidate into a single PR. Same two blockers apply to both (see my note on #4006): (1) check:fabricated-docs flags onPluginMessage/onRender in PLUGIN_SDK.md as hooks not in BUILTIN_EVENTS — they belong to the unmerged plugin IPC/UI PRs (#3783/#3785), so document only merged APIs or land those first; (2) drop the stray .omo/run-continuation/ses_*.json artifact. Leaving open for the consolidated re-cut. 🙏

oyi77 · 2026-06-17T08:25:55Z

Status update

Verified that the latest commits on this branch have addressed the review feedback:

✅ onPluginMessage and onRender removed from PLUGIN_SDK.md (not in BUILTIN_EVENTS)
✅ db and ipc permissions removed from SDK permissions table (not in PermissionSchema)
✅ PLUGIN_MARKETPLACE examples fixed (await added, param types corrected)

Remaining blocker: Needs rebase onto current release/v3.8.27 (was on .22/.23). Also, per @diegosouzapw's note, #4006 and #4007 have identical diffs — should consolidate into a single PR.

oyi77 · 2026-06-17T19:21:45Z

Consolidated from #4006 (now closed). Changes pushed:

✅ Stray artifact .omo/run-continuation/ses_*.json removed
✅ onPluginMessage and onRender removed from PLUGIN_SDK.md (not in BUILTIN_EVENTS)
✅ Entire 'Planned Features' section removed (references unmerged feat(plugins): plugin IPC/runtime core with permission model (split from #3668) #3783/feat(plugins): plugin UI-extensibility — admin pages, render routes, sidebar (split from #3668) #3785)
✅ Rebased onto release/v3.8.28

diegosouzapw · 2026-06-19T12:42:26Z

Thanks @oyi77 for the documentation work 🙏

This PR is conflicting against release/v3.8.30 and the docs tree has moved substantially since it was opened (~185–225 files in the diff). Could you rebase onto the latest release/v3.8.30 and resolve conflicts? Given how much the docs have changed, some sections may now overlap with already-merged docs — a rebase will surface what's genuinely new so we can review and land it. Thanks!

oyi77 · 2026-06-19T14:23:49Z

Rebased onto latest release/v3.8.30 — diff is now clean: 3 files, +966/-60 (down from ~200 files). Plugin docs ready for review. ✅

diegosouzapw · 2026-06-20T21:47:37Z

Thanks for this @oyi77 — leaving it open for a rework rather than merging as-is, because a review against the current release/v3.8.32 surfaced a few blockers:

Duplicate marketplace doc — docs/plugins/PLUGIN_MARKETPLACE.md (354 lines) is a near-duplicate of the docs/frameworks/PLUGIN_MARKETPLACE.md (348 lines) that's already on the release branch. We shouldn't ship two marketplace docs in different directories. Please consolidate into the existing docs/frameworks/ one (or move/replace it deliberately) rather than adding a second.
Stale base / PLUGIN_SDK.md regression — the branch is based off an older tip, so its PLUGIN_SDK.md rewrite removes the richer reference tables already on release (PluginContext fields, sandbox permission grants, the plugin-event table, the auth example). A rebase onto the current release/v3.8.32 is needed so the diff doesn't revert existing content.
Feature accuracy — PLUGIN_DEVELOPMENT.md documents dev-mode hot-reload (it notes 'when wired up'), the plugin doctor, and plugin signing/verification. Some of these are only partially wired in the current plugin runtime. Please make sure each documented capability is actually reachable on release/v3.8.32, or mark it clearly as planned, so the guide doesn't describe behavior that isn't live yet.
Out-of-scope files — the evals/ControlsSection.tsx + evals/SuiteBuilderModal.tsx components are unrelated to the plugin docs and are orphaned without the EvalsTab modularization (refactor: modularize EvalsTab.tsx (#3594) #4422); please drop them from this PR.

Heads-up that the plugin system is heading into a redesign, so a rebased, deduped, accuracy-checked version is the way to land this cleanly. Happy to re-review once it's updated — appreciate the docs effort! 🙏

…C+D) (cheaper-inference#4622) C — scripts/quality/validate-release-green.mjs (npm run check:release-green): reproduces the release-equivalent validation (typecheck, eslint, db-rules, public-creds, full unit, vitest, ratchets, optional --with-build package-artifact) against the current working tree and classifies each red as HARD (real defect, exit 1) vs DRIFT (ratchet — reported, never affects exit / never blocks). Pure helpers exported + orchestration behind a direct-run guard; unit-tested. D — .github/workflows/nightly-release-green.yml: runs C on the active release branch nightly (and on workflow_dispatch) and opens/updates a single tracking issue on HARD failures. Never a required check, never touches a contributor PR. Closes the gap where the full gate (ci.yml) only ran on the release PR, so reds accrued silently on release/** and surfaced in 40-min layers at release time. Non-blocking by construction; drift is the maintainer's to rebaseline at release. Co-authored-by: Diego Rodrigues de Sa e Souza <diego.souza@cdwasolutions.com.br>

…marketplace

oyi77 · 2026-06-23T09:12:09Z

Closing stale PR — conflicts with current release branch. Will reopen fresh if needed.

oyi77 requested a review from diegosouzapw as a code owner June 16, 2026 14:51

gemini-code-assist Bot reviewed Jun 16, 2026

View reviewed changes

oyi77 mentioned this pull request Jun 16, 2026

docs(plugins): add plugin documentation — dev guide, marketplace, SDK reference (clean re-cut) #3787

Closed

diegosouzapw mentioned this pull request Jun 16, 2026

docs(plugins): add SDK reference with typed API for IPC, DB, UI extensions #4006

Closed

diegosouzapw changed the base branch from release/v3.8.27 to release/v3.8.28 June 17, 2026 08:19

oyi77 force-pushed the docs/plugin-dev-guide branch from 74d6c6c to 5b8dc8a Compare June 17, 2026 08:55

diegosouzapw changed the base branch from release/v3.8.28 to release/v3.8.29 June 18, 2026 00:08

oyi77 force-pushed the docs/plugin-dev-guide branch from b80c346 to 11f632c Compare June 18, 2026 09:53

diegosouzapw changed the base branch from release/v3.8.29 to release/v3.8.30 June 19, 2026 10:17

oyi77 force-pushed the docs/plugin-dev-guide branch from 11f632c to c8845dd Compare June 19, 2026 14:09

oyi77 force-pushed the docs/plugin-dev-guide branch from c8845dd to dfd806f Compare June 20, 2026 05:31

oyi77 force-pushed the docs/plugin-dev-guide branch from dfd806f to 1c06d4d Compare June 20, 2026 05:39

diegosouzapw changed the base branch from release/v3.8.30 to release/v3.8.31 June 20, 2026 10:41

oyi77 force-pushed the docs/plugin-dev-guide branch from 1c06d4d to 1c6e922 Compare June 20, 2026 12:39

oyi77 force-pushed the docs/plugin-dev-guide branch from 1c6e922 to bdfc430 Compare June 20, 2026 15:37

diegosouzapw changed the base branch from release/v3.8.31 to release/v3.8.32 June 20, 2026 18:31

oyi77 force-pushed the docs/plugin-dev-guide branch from bdfc430 to d07f2d0 Compare June 20, 2026 18:34

oyi77 force-pushed the docs/plugin-dev-guide branch from d07f2d0 to 656be22 Compare June 20, 2026 18:41

oyi77 force-pushed the docs/plugin-dev-guide branch from 656be22 to 83d156d Compare June 20, 2026 19:05

oyi77 force-pushed the docs/plugin-dev-guide branch from 83d156d to 754cecf Compare June 20, 2026 22:12

diegosouzapw changed the base branch from release/v3.8.32 to release/v3.8.33 June 21, 2026 14:03

chore(release): open v3.8.34 development cycle

5cb7621

diegosouzapw changed the base branch from release/v3.8.33 to release/v3.8.34 June 22, 2026 07:40

diegosouzapw and others added 5 commits June 22, 2026 08:46

docs(plugins): add plugin dev guide and marketplace documentation

0a5d6c0

docs: fix plugin references and mark planned features

337c703

docs: fix plugin references, mark planned features, remove duplicate …

c8f86c0

…marketplace

chore: drop unrelated evals components

808e7f3

oyi77 force-pushed the docs/plugin-dev-guide branch from 410b690 to 808e7f3 Compare June 22, 2026 18:43

diegosouzapw changed the base branch from release/v3.8.34 to release/v3.8.35 June 23, 2026 06:51

oyi77 closed this Jun 23, 2026

oyi77 deleted the docs/plugin-dev-guide branch August 7, 2026 21:07

	const pluginName = filename.replace(/\\/g, "/").split("/")[0];
	const pluginName = filename.split("/")[0];

		- `onPluginMessage` (function, optional) — Receives IPC messages from other plugins via `__omniroute.broadcast()` / `__omniroute.sendTo()`
		- `onRender` (function, optional) — Renders a dashboard page when a user visits the plugin's admin page

		\| `db` \| `__omniroute.db` — persistent key-value store (SQLite-backed, isolated per plugin) \|
		\| `ipc` \| `__omniroute.broadcast()` / `__omniroute.sendTo()` — cross-plugin messaging \|

		\| `onPluginMessage` \| IPC message from another plugin \| `{ source, event, data }` \|
		\| `onRender` \| Dashboard page requested \| `{ slug, params }` — return HTML or structured content \|

Conversation

oyi77 commented Jun 16, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

diegosouzapw commented Jun 16, 2026

Uh oh!

oyi77 commented Jun 17, 2026

Status update

Uh oh!

oyi77 commented Jun 17, 2026

Uh oh!

diegosouzapw commented Jun 19, 2026

Uh oh!

oyi77 commented Jun 19, 2026

Uh oh!

diegosouzapw commented Jun 20, 2026

Uh oh!

oyi77 commented Jun 23, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants