omniroute-plugin/README.md

omniroute-plugin

OmniRoute gateway integration for the DeepSeek Harness (DSH): model auto-import (context window, max output, modalities, thinking levels) provider quota tracking under the composer, and a web search toolkit for the agent backed by OmniRoute's search/fetch providers.

Features

• Model discovery / import: pulls models and combos from your OmniRoute gateway into an llm-pi-ai provider (default id omni, created if missing), with context window, output limit, input modalities and supported thinking levels (off/minimal/low/medium/high/xhigh/max).
• Periodic re-import (syncMin, default 60 min; 0 = manual only) and an update existing models only mode.
• Include / exclude filters: comma-separated glob patterns (*, ?) on model ids, e.g. claude*, gemini-*; exclude always wins.
• Manage imported models: search, select and prune models from the provider.
• Quota tracking: provider quotas (5-hour, weekly, monthly, …) shown in the composer dock, refreshed every pollSec seconds (default 120); requires a management-scoped API key.
• Web search toolkit for the agent (see below): omniroute_web_search, omniroute_web_fetch, omniroute_search_providers, routed through the gateway's /v1/search and /v1/web/fetch.
• English and Chinese UI.

Files

File	Role
index.js	Host plugin. Injects webServer, connection, credentials, settings, tools.
client.js	Web client: settings panel (plugins.bundle.config) and quota dock (conversation.composer.dock).
locale/*.json	Plugin title/description (en, zh).
cordis.patch.yml	Bundle patch inserting the omniroute row.

Host routes (relative to the Web origin, behind the connection trust fence)

Route	Purpose
GET /omniroute/status	Effective settings, key presence, last import
POST /omniroute/config	Save settings (+ optional write-only API key)
POST /omniroute/test	Probe the gateway with given or saved credentials
GET /omniroute/models	Models currently imported
POST /omniroute/prune	Remove selected imported models
POST /omniroute/import	Import models/combos into the llm-pi-ai provider
GET /omniroute/quotas	Provider quotas (?model=<id> narrows to that model's provider)
GET /omniroute/search-providers	Web search / fetch providers known to the gateway

Web search toolkit

While Web search tools is on (default), the plugin registers three agent tools. They use the same gateway URL and API key as the rest of the plugin, so nothing extra needs configuring. To use them, enable at least one search provider in OmniRoute (Dashboard → Search).

Tool	What it does
omniroute_web_search	POST /v1/search. Params: query (required), max_results (1–20), search_type (web/news/x), time_range (any/hour/day/week/month/year), include_domains, exclude_domains, country, language, provider. Returns {provider, query, results:[{n,title,url,snippet,published?,content?}], answer?}.
omniroute_web_fetch	POST /v1/web/fetch. Params: url (required), format (markdown/html), max_characters (default 20000), provider. Returns the page content (truncated, with a truncated marker) and links.
omniroute_search_providers	Lists the gateway's search/fetch providers with kind, status (configured/missing), supported search types and cost per query.

Choosing a provider:

1. The tool call's provider argument wins.
2. Otherwise the Search provider / Fetch provider setting is used.
3. If both are blank, the plugin picks the first provider OmniRoute reports as configured. The list is cached for 10 minutes and refreshed on save.

This matters because the gateway's built-in default (duckduckgo-free) often returns no results.

Every result is prefixed with a notice telling the model to treat web content as untrusted data. Turning the toggle off unregisters the tools immediately, with no restart. The tool names don't clash with DSH's built-in web_search / web_fetch, so both can be enabled at once.

Installation

Requirements: a working DeepSeek Harness (dsh) install with the web profile (or any profile that includes the Web UI).

Option A — install from git (recommended)

dsh plugin --profile web add git+https://git.rizzy.dev/DSH-Plugins/omniroute-plugin.git

You can also paste git+https://git.rizzy.dev/DSH-Plugins/omniroute-plugin.git into Settings → Plugins → Install in the Web UI, or ask the agent to install it with its plugin_manager tool (install_bundle).

The plugin manager adds @local/omniroute to dependencies and to dsh.profile.bundles in ~/.dsh/profiles/web/package.json.

Option B — local checkout (for development)

git clone https://git.rizzy.dev/DSH-Plugins/omniroute-plugin.git ~/dsh-plugins/omniroute-plugin
dsh plugin --profile web add link:$HOME/dsh-plugins/omniroute-plugin

With a link: install, edits in the checkout are picked up directly (client changes reload on page refresh, Host changes after a DSH restart or HMR reload).

Enable / verify

1. Make sure @local/omniroute is listed in dsh.profile.bundles of ~/.dsh/profiles/web/package.json (the installer does this; add it by hand if you edited package.json manually).
2. Restart DSH (dsh web) or reload the page.
3. Check Settings → Plugins: the @local/omniroute bundle should be enabled.

Uninstall

dsh plugin --profile web remove @local/omniroute

Updating

Re-run the add command from Option A (or git pull in your Option B checkout).

Setup after install

1. Open Settings → Plugins → OmniRoute.
2. Enter the Gateway URL (e.g. https://omniroute.example.com) and paste your API key.
   • The key is stored in the DSH credential store under OMNIROUTE_API_KEY (keyRef) and never leaves the Host.
   • Use a management-scoped key if you want quota tracking.
3. Press Test, then Save, then Re-discover models.
4. Pick an omni/… model in the model selector. Quotas appear under the composer.
5. (Optional) Under Web search tools, set a preferred search/fetch provider and the default number of results.

Configuration file

Non-secret settings live in <profile>/omniroute.json ($DSH_PROFILE_DIR or ~/.dsh/profiles/web/omniroute.json):

{
  "url": "https://omniroute.example.com",
  "keyRef": "OMNIROUTE_API_KEY",
  "provider": "omni",
  "discovery": true,
  "updateOnly": false,
  "include": "",
  "exclude": "",
  "discoverThinking": true,
  "usage": true,
  "pollSec": 120,
  "syncMin": 60,
  "webSearch": true,
  "searchProvider": "",
  "fetchProvider": "",
  "searchMaxResults": 8
}

All of these are editable from the settings panel; imported and lastImport are maintained by the plugin.