@maci0/dsh-omniroute 0.0.0-stage → 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-omniroute contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# dsh-omniroute
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OmniRoute's own API, inside DeepSeek Harness. The router that fronts every
+upstream account knows things the OpenAI-compatible `/v1` surface does not: which
+models it can serve *right now*, which accounts it holds, and what each of those
+accounts has left. This plugin serves all three as JSON routes on the harness's
+own origin, behind the same trust fence as the harness's browser routes, with the
+OmniRoute API key never leaving the host process.
+
+## What you get
+
+- **The live catalog, not `/v1/models`.** `available` and `vision` per
+  model, with `?available=1`, `?q=`, and `?provider=` to narrow it.
+- **The account inventory.** Every upstream connection with its id, provider, switch
+  state, and whether it publishes quota.
+- **Per-connection quota.** Plan and windows for each connection that publishes one.
+- **An explicit picker sync.** `?sync=1` merges the available models into a provider
+  route's settings, so the model picker learns them. It never runs on a timer.
+- **The key stays on the host.** Routes answer formatted JSON only.
+
+## Install
+
+> **Install it as a bundle.** `dsh plugin add …` mounts the row from the
+> package's own patch layer, which is what the settings editor can write to. A
+> row added with `--patch` is an overlay: it disappears at the next start, and
+> the Plugins card cannot save into it (the editor refuses a write an overlay
+> would win).
+
+```sh
+dsh plugin --profile web add @maci0/dsh-omniroute@0.8.2
+```
+
+This installs the public npm package; no GitHub token or `~/.secrets` setup is needed.
+The version is pinned. To upgrade, run the same command with a newer version,
+then restart `dsh web` (bundle layers compose at boot).
+
+Do **not** also paste the `id: omniroute` row from `cordis.patch.yml` into the
+profile's own patch: `insert` does not dedupe ids.
+
+## Configure
+
+Every field is editable from the Web client: open **Plugins**, then the
+**omniroute** row, then **Configure**. The card validates the URL, the non-empty
+references, and the numeric bounds before the write, saves every changed field
+in one update, and offers **Reset to defaults** for the fields you overrode.
+Every field is `volatile()`, so a save reaches the running routes: each is read
+per request and a settings write drops the served readings, so a new origin or
+cache window applies to the next poll instead of a restart.
+
+The same row can be set by hand in the profile's own `cordis.patch.yml`; a patch
+replaces the targeted row's whole `config`, so restate every key you keep:
+
+```yaml
+- id: omniroute
+  config:
+    baseURL: http://192.168.0.100:20128/v1   # origin is used; the /v1 path is dropped
+    apiKeyEnv: OMNIROUTE_API_KEY             # credential reference, then that env var
+    timeoutMs: 10000                         # per OmniRoute request
+    cacheSeconds: 30                         # how long one reading is served from cache
+    syncNamespace: llm-pi-ai                 # where ?sync=1 writes
+    syncProvider: omniroute                  # which provider route it writes for
+```
+
+| Key | Default | Bounds | Meaning |
+|---|---|---|---|
+| `baseURL` | `http://localhost:20128` | absolute http(s) | The deployment. Its origin addresses OmniRoute's management API, so a `/v1` suffix is fine and ignored. A value without an http(s) scheme fails at load, and a live edit to one makes every route answer a configuration error without asking anything; no default origin is guessed. |
+| `apiKeyEnv` | `OMNIROUTE_API_KEY` | non-empty | Credential reference resolved through `ctx.credentials`, falling back to the launcher's environment. The key needs the scopes the endpoints use: this box's key carries `self:usage` and `manage`. |
+| `timeoutMs` | `10000` | 1–60000 | Deadline for each OmniRoute request, including the connection listing. |
+| `cacheSeconds` | `30` | 0–3600 | How long one reading is served before OmniRoute is asked again. `0` re-asks every time. |
+| `syncNamespace` | `llm-pi-ai` | non-empty | Settings namespace `?sync=1` merges into. |
+| `syncProvider` | `omniroute` | non-empty | Provider route inside that namespace. |
+
+## Routes
+
+- `GET /omniroute/models`: the live catalog, with `available` and `vision` per
+  model, and `?available=1`, `?q=<text>`, `?provider=<key>` to narrow it.
+  `?sync=1` also copies the available models into a provider route's settings,
+  which is how the model picker learns them.
+- `GET /omniroute/connections`: every upstream connection, with the id, the
+  provider, whether it is switched on, and whether it publishes quota.
+- `GET /omniroute/quota`: the plan and windows of every connection that
+  publishes one.
+
+Every route also answers `?refresh=1`, which ignores the cache for that read.
+`fetchedAt` is when OmniRoute answered, so a reading served from cache keeps the
+time it was taken.
+
+```
+http://127.0.0.1:3080/omniroute/models?available=1&q=claude
+```
+
+`/omniroute/models` answers with the catalog and its counts:
+
+```json
+{
+  "status": "ok",
+  "provider": "omniroute",
+  "origin": "http://192.168.0.100:20128",
+  "fetchedAt": 1789793193906,
+  "counts": { "total": 525, "available": 95, "shown": 95 },
+  "models": [
+    { "id": "cc/claude-opus-5", "provider": "cc", "name": "Claude Opus 5", "available": true, "vision": true }
+  ]
+}
+```
+
+`/omniroute/quota` answers with the connection list and one entry per window:
+
+```json
+{
+  "status": "ok",
+  "windows": [
+    {
+      "connection": "acbe586b-7488-44c4-b8d1-de4982c18ed7",
+      "provider": "deepseek",
+      "plan": "DeepSeek",
+      "window": "credits_usd",
+      "used": 0,
+      "total": 0,
+      "remaining": 91.27,
+      "remainingPercent": 100,
+      "unlimited": true,
+      "currency": "USD",
+      "limitReached": false
+    }
+  ],
+  "limitReached": []
+}
+```
+
+### Filling the model picker
+
+The picker reads a route's models from `settings.yaml`, so the live catalog only
+reaches it when something writes them there. That is what `?sync=1` does, and it
+is deliberately explicit rather than automatic: a background writer that
+rewrites a provider row on a timer is not something a plugin should do to a
+settings document it does not own.
+
+```sh
+curl 'http://127.0.0.1:3080/omniroute/models?available=1&sync=1'
+```
+
+That fetches the catalog, keeps the `available` models (after `?q=` and
+`?provider=`, so a narrowed sync is possible), and merges
+`providers.<syncProvider>.models` into `syncNamespace`. The reply names what it
+wrote:
+
+```json
+"synced": { "namespace": "llm-pi-ai", "path": "providers.omniroute.models", "count": 95 }
+```
+
+The write is a merge, so fields the row already carries (`apiKeyEnv`, `baseURL`,
+`compat`) survive; only `models` is replaced.
+
+## How it works
+
+- **The endpoints are OmniRoute's own.** They were read off a running `v3.8.50`
+  server rather than guessed: `GET /api/openapi/spec` lists 361 endpoints, and
+  `GET /api/agent-skills` indexes them per area. The paths people commonly try
+  (`/api/balance`, `/api/usage`, `/api/quota`, `/key/info`) are not among them
+  (`/key/info` is the web app's HTML fallback), which is why earlier attempts at
+  this router found nothing.
+- **The catalog comes from `/api/models`, not `/v1/models`.** Both answer, but
+  only the management listing carries `available` and `supportsVision`, and only
+  it says which models are servable now instead of which have ever existed.
+- **Quota is per connection, because OmniRoute holds the accounts.** The router
+  publishes no figure for itself, so the plugin lists connections, skips the ones
+  that are switched off or hide their quota, and asks `/api/usage/<id>` for the
+  rest. A connection that fails to answer contributes no window instead of
+  failing the read. `/api/quota/plans` resolves plans without consumption and
+  `/api/quota/pools` is empty unless the deployment defines pools, so neither is
+  read here.
+- **Readings are cached** for `cacheSeconds`: the catalog, and the connection
+  listing together with its windows (both connection routes serve that one
+  reading, so they never disagree). Concurrent callers share one in-flight read,
+  so a refresh loop cannot multiply requests to the router.
+- **Every route checks the trust fence first.** The plugin injects the
+  composition's `connection` service and asks `requestRejection` before anything
+  else; a composition without that service never mounts the routes.
+- **The key stays in this process.** Routes answer formatted JSON only: no key,
+  no Authorization header. A refusal is this plugin's own one-line message
+  (HTTP status, timeout, unreachable, non-JSON body), never the router's body;
+  a failure inside another service (credentials, settings) is logged on the
+  host and answered generically.
+
+## Limits
+
+- **One quota read is one listing plus one request per visible connection.** On
+  the reference box that is 21 requests, cached for `cacheSeconds`. A deployment
+  with many connections should raise `cacheSeconds`.
+- **Quota is read per connection, not per route.** A route served by OmniRoute
+  spends whichever account the router picks, so no single figure belongs to it.
+  `dsh-quota-check`'s OmniRoute probe renders the fullest window across
+  connections for exactly that reason.
+- **No statusbar chip.** The browser half ships the row's configuration card
+  only; the routes are the read surface, and `dsh-quota-check` draws the chip.
+- **The catalog carries no capacities.** `/api/models` reports availability and
+  vision but no context window, so a synced model entry sets only `id` and
+  `name`. Set capacities in the provider row when they matter.
+- **`?sync=1` writes a namespace this plugin does not own.** It merges into
+  `syncNamespace` (default `llm-pi-ai`) because that is where the picker reads
+  from. Point it elsewhere, or leave it alone, when that route is not yours.
+- **Read-only.** Creating keys, connections, and combos is out of scope; nothing
+  here mutates the router.
+
+## Development
+
+dsh loads plugins on Node `^22.19.0 || >=24.0.0`; development and tests run on bun.
+
+```sh
+bun install          # first run only (typescript, @types/node, cordis, carrier, schemastery)
+bun run typecheck
+bun test             # parsers, the client, both route halves, and a real-composition boot
+bun run build        # tsc -> lib/*.js
+```
+
+For local development, `dsh plugin --profile <name> add <path-to-checkout>`
+(after `bun run build`), then restart `dsh web`.
+
+`bun test` includes the real-composition case: the plugin mounts into a real
+Cordis `Context` beside the real HTTP carrier on an OS-assigned port, a route is
+driven over real HTTP with the settings write observed, disposing the fiber
+must withdraw every route, and no route exists until the trust fence is mounted.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# The dsh-omniroute bundle patch: applied automatically when a profile lists
+# this bundle (`dsh plugin add`/`update` appends the package to
+# dsh.profile.bundles). Override the row from the profile's own
+# cordis.patch.yml with a `- id: omniroute` row, which replaces the row's whole
+# `config`.
+# Do not also insert this same row into the profile patch: insert does not
+# dedupe ids, and a second row would register the plugin twice.
+- insert:
+    - id: omniroute
+      name: '@maci0/dsh-omniroute'

package/icon.svg

@@ -0,0 +1,8 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M15.2 16.2L10.2 11.6M20.8 16.2L25.8 11.6M15.2 19.8L10.2 24.4M20.8 19.8L25.8 24.4" stroke="#145AF3" stroke-width="1.6" stroke-linecap="round"/>
+  <circle cx="18" cy="18" r="4" fill="#145AF3"/>
+  <circle cx="8" cy="9.5" r="2.4" fill="#7CB7FF"/>
+  <circle cx="28" cy="9.5" r="2.4" fill="#45D9E7"/>
+  <circle cx="8" cy="26.5" r="2.4" fill="#F2AF63"/>
+  <circle cx="28" cy="26.5" r="2.4" fill="#7CB7FF"/>
+</svg>

package/lib/client.js

@@ -0,0 +1,383 @@
+/**
+ * dsh-omniroute browser half: the OmniRoute card on the Plugins page.
+ *
+ * One surface: the OmniRoute card on the Plugins page, keyed on the
+ * `omniroute` settings namespace the host half declares as its row id. Every
+ * field of the row is volatile, and the host reads it per request, so a save
+ * lands on the next poll without remounting the plugin or restarting the
+ * server.
+ *
+ * The form stages edits locally and writes them in one `scope.mutate` call:
+ * a half-typed base URL must not reach the settings document field by field.
+ * Chrome is a stylesheet, not inline style objects: the module system claims
+ * every `<style>` tag a factory appends while it materializes and removes it
+ * when the package unloads. Classes are `or-`-prefixed because that sheet
+ * lands in the page's own document.
+ *
+ * This file is plain JavaScript on purpose. The client module system serves a
+ * package's `exports["./client"]` artifact as a lazy-CJS factory registered on
+ * `window.__ModuleLoader__`, and that is the whole format: an out-of-tree
+ * plugin can author it directly instead of reproducing the repository's tsdown
+ * client preset. `react` is provided by the module system; nothing else is
+ * required here.
+ */
+
+window.__ModuleLoader__.load({
+  id: '@maci0/dsh-omniroute',
+
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const React = require('react')
+
+    /** Settings namespace shared with the host half; also this card's slot key. */
+    const NAMESPACE = 'omniroute'
+
+    /** Locale namespace for this plugin's copy. */
+    const LOCALE_NS = 'omniroute'
+
+    /**
+     * Every editable row field, in display order. `integer` fields are sent as
+     * numbers and must be positive integers; the host schema bounds each one,
+     * and the card refuses what it can see before the write.
+     */
+    const FIELDS = [
+      { key: 'baseURL', kind: 'url', label: 'labelBaseURL', hint: 'hintBaseURL' },
+      { key: 'apiKeyEnv', kind: 'text', label: 'labelApiKeyEnv', hint: 'hintApiKeyEnv' },
+      { key: 'timeoutMs', kind: 'integer', min: 1, max: 60_000, label: 'labelTimeoutMs', hint: 'hintTimeoutMs' },
+      { key: 'cacheSeconds', kind: 'integer', min: 0, max: 3_600, label: 'labelCacheSeconds', hint: 'hintCacheSeconds' },
+      { key: 'syncNamespace', kind: 'text', label: 'labelSyncNamespace', hint: 'hintSyncNamespace' },
+      { key: 'syncProvider', kind: 'text', label: 'labelSyncProvider', hint: 'hintSyncProvider' },
+    ]
+
+    /** Every class is `or-`-prefixed: the sheet lands in the page's own document. */
+    const CSS = [
+      '.or-page{display:flex;flex-direction:column;gap:12px}',
+      '.or-field{display:flex;flex-direction:column;gap:4px}',
+      '.or-label{font-size:13px;font-weight:600;line-height:1.5;color:var(--dsw-alias-label-primary)}',
+      '.or-hint{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}',
+      '.or-input{font:inherit;font-size:13px;line-height:1.5;padding:5px 12px;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-4);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;width:100%;box-sizing:border-box}',
+      '.or-input:disabled{cursor:default;opacity:.5}',
+      '.or-row{display:flex;flex-wrap:wrap;align-items:center;gap:8px}',
+      '.or-button{appearance:none;font:inherit;font-size:13px;line-height:1.5;padding:5px 14px;cursor:pointer;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-4);border:1px solid var(--dsw-alias-border-l2);border-radius:8px}',
+      '.or-button:disabled{cursor:default;opacity:.5}',
+      '.or-button-quiet{padding:3px 10px;font-size:12px;color:var(--dsw-alias-label-secondary)}',
+      '.or-status{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}',
+      '.or-error{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-error)}',
+    ].join('')
+
+    // Appended while the factory materializes: the module system claims the tag
+    // for this package and disposes it on unload. Guarded because the unit
+    // tests evaluate this file without a DOM.
+    if (typeof document !== 'undefined') {
+      const style = document.createElement('style')
+      style.textContent = CSS
+      document.head.append(style)
+    }
+
+    /** Plugin version, shown in the card footer. Kept in lockstep with package.json. */
+    const VERSION = '0.8.2'
+
+    const en = {
+      title: 'OmniRoute',
+      summary: 'OmniRoute catalog, connections, and quota at {baseURL}.',
+      summaryEmpty: 'OmniRoute catalog, connections, and quota.',
+      labelBaseURL: 'Base URL',
+      labelApiKeyEnv: 'API key reference',
+      labelTimeoutMs: 'Request deadline (ms)',
+      labelCacheSeconds: 'Cache seconds',
+      labelSyncNamespace: 'Sync namespace',
+      labelSyncProvider: 'Sync provider',
+      hintBaseURL: 'OmniRoute origin, with or without its /v1 path.',
+      hintApiKeyEnv: 'Credential reference holding the API key; the key itself never reaches the browser.',
+      hintTimeoutMs: 'Per-request deadline for one OmniRoute call.',
+      hintCacheSeconds: 'How long a reading is served before OmniRoute is asked again. 0 asks every time.',
+      hintSyncNamespace: 'Profile entry id ?sync=1 writes the model catalog into.',
+      hintSyncProvider: 'Provider route ?sync=1 writes the model catalog into.',
+      overridden: 'overridden',
+      save: 'Save',
+      saving: 'Saving…',
+      saved: 'Saved. The next poll uses these values.',
+      reset: 'Reset to defaults',
+      persists: 'Stored in your profile; every route reads the row on each request.',
+      readOnly: 'Read-only: this deployment does not persist settings.',
+      baseUrlInvalid: 'Base URL must be an absolute http(s) URL.',
+      textInvalid: 'Must not be empty.',
+      numberInvalid: 'Must be a whole number within the allowed range.',
+      rejected: 'The Host refused the write; the previous values are still in effect.',
+      failed: 'Could not save: {message}',
+      version: 'v{version}',
+    }
+
+    const zh = {
+      title: 'OmniRoute',
+      summary: 'OmniRoute 目录、连接与额度：{baseURL}。',
+      summaryEmpty: 'OmniRoute 目录、连接与额度。',
+      labelBaseURL: '基础地址',
+      labelApiKeyEnv: 'API 密钥引用',
+      labelTimeoutMs: '请求超时（毫秒）',
+      labelCacheSeconds: '缓存秒数',
+      labelSyncNamespace: '同步命名空间',
+      labelSyncProvider: '同步提供方',
+      hintBaseURL: 'OmniRoute 地址，可带或不带 /v1 路径。',
+      hintApiKeyEnv: '保存 API 密钥的凭据引用；密钥本身不会进入浏览器。',
+      hintTimeoutMs: '单次 OmniRoute 调用的超时时间。',
+      hintCacheSeconds: '一次读取在再次询问 OmniRoute 前可复用的时长。0 表示每次都询问。',
+      hintSyncNamespace: '?sync=1 写入模型目录的配置条目 id。',
+      hintSyncProvider: '?sync=1 写入模型目录的提供方路由。',
+      overridden: '已覆盖',
+      save: '保存',
+      saving: '保存中…',
+      saved: '已保存。下一次轮询将使用这些值。',
+      reset: '恢复默认',
+      persists: '保存在你的配置中；每个路由都会在每次请求时读取该行。',
+      readOnly: '只读：此部署不持久化设置。',
+      baseUrlInvalid: '基础地址必须是绝对的 http(s) URL。',
+      textInvalid: '不能为空。',
+      numberInvalid: '必须是允许范围内的整数。',
+      rejected: 'Host 拒绝了写入；原先的值仍然有效。',
+      failed: '保存失败：{message}',
+      version: 'v{version}',
+    }
+
+    /**
+     * Bind one settings scope to a React subscription.
+     * @param scope - the scope bound to the omniroute settings namespace.
+     * @returns a hook reading that scope's current snapshot.
+     */
+    function useScope(scope) {
+      const subscribe = (listener) => scope.subscribe(listener)
+      const getSnapshot = () => scope.getSnapshot()
+      return () => React.useSyncExternalStore(subscribe, getSnapshot)
+    }
+
+    /**
+     * Read a snapshot's resolved row. A namespace this deployment does not
+     * serve reports no row, which the card renders as nothing at all.
+     * @param snapshot - the settings scope snapshot.
+     * @returns the resolved row, or `undefined` when unreadable.
+     */
+    function rowOf(snapshot) {
+      if (snapshot.status !== 'ready') return undefined
+      return snapshot.value !== null && typeof snapshot.value === 'object' ? snapshot.value : {}
+    }
+
+    /** One editable field: label, hint, input, and the override marker. */
+    function Field(props) {
+      const { t, field, value, overridden, disabled, onChange } = props
+      return React.createElement(
+        'div',
+        { className: 'or-field' },
+        React.createElement(
+          'div',
+          { className: 'or-row' },
+          React.createElement('span', { className: 'or-label' }, t(field.label)),
+          overridden === true
+            ? React.createElement('span', { className: 'or-hint' }, `(${t('overridden')})`)
+            : null,
+        ),
+        React.createElement('input', {
+          className: 'or-input',
+          type: field.kind === 'integer' ? 'number' : 'text',
+          value: value,
+          disabled,
+          'aria-label': t(field.label),
+          onChange: (event) => { onChange(field.key, event.target.value) },
+        }),
+        React.createElement('span', { className: 'or-hint' }, t(field.hint)),
+      )
+    }
+
+    /**
+     * Build the card component over one bound settings scope.
+     * @param scope - the scope bound to the omniroute settings namespace.
+     * @param t - translate function bound to this plugin's locale namespace.
+     * @returns the component the slot renders.
+     */
+    function createCard(scope, t) {
+      const useOmniRoute = useScope(scope)
+
+      return function OmniRouteCard(props) {
+        const snapshot = useOmniRoute()
+        const [draft, setDraft] = React.useState(null)
+        const [error, setError] = React.useState(null)
+        const [status, setStatus] = React.useState(null)
+        // True while a write is in flight: Save and Reset stay disabled, so a
+        // double click sends one write.
+        const [pending, setPending] = React.useState(false)
+
+        const row = rowOf(snapshot)
+        // A namespace this deployment does not serve renders no trace of itself.
+        if (row === undefined) return null
+
+        if (props != null && props.view === 'summary') {
+          return row.baseURL === undefined
+            ? t('summaryEmpty')
+            : t('summary', { baseURL: String(row.baseURL) })
+        }
+
+        const disabled = !snapshot.writable
+        const busy = disabled || pending
+        const shown = draft ?? row
+        const user = snapshot.user !== null && typeof snapshot.user === 'object' ? snapshot.user : {}
+
+        /**
+         * Validate and collect the staged edits.
+         * @returns an error key, or the ordered path operations to write.
+         */
+        const collect = () => {
+          const ops = []
+          for (const field of FIELDS) {
+            const value = shown[field.key]
+            if (String(value) === String(row[field.key])) continue
+            if (field.kind === 'integer') {
+              // An emptied box is not zero: `Number('')` is 0, which would pass
+              // a min of 0 and write a value nobody typed.
+              const text = String(value).trim()
+              const parsed = Number(text)
+              if (text === '' || !Number.isInteger(parsed) || parsed < field.min || parsed > field.max) {
+                return { error: 'numberInvalid' }
+              }
+              ops.push({ op: 'set', path: [field.key], value: parsed })
+              continue
+            }
+            const text = String(value).trim()
+            if (text === '') return { error: 'textInvalid' }
+            if (field.kind === 'url' && !/^https?:\/\//u.test(text)) return { error: 'baseUrlInvalid' }
+            ops.push({ op: 'set', path: [field.key], value: text })
+          }
+          return { ops }
+        }
+
+        /** Run one settings write; a synchronous throw becomes a rejection. */
+        const write = (ops) => new Promise((resolve) => { resolve(scope.mutate(ops)) })
+
+        const save = () => {
+          if (pending) return
+          setError(null)
+          const result = collect()
+          if (result.error !== undefined) {
+            setError(t(result.error))
+            return
+          }
+          if (result.ops.length === 0) {
+            // Nothing moved: an edit that landed back on the stored value is
+            // not a change, and the row already holds it.
+            setStatus(null)
+            return
+          }
+          setStatus(t('saving'))
+          setPending(true)
+          write(result.ops)
+            .then((accepted) => {
+              if (accepted === false) {
+                setError(t('rejected'))
+                setStatus(null)
+                return
+              }
+              setDraft(null)
+              setStatus(t('saved'))
+            })
+            .catch((cause) => {
+              setStatus(null)
+              setError(t('failed', { message: cause instanceof Error ? cause.message : String(cause) }))
+            })
+            .finally(() => { setPending(false) })
+        }
+
+        const reset = () => {
+          if (pending) return
+          setDraft(null)
+          setStatus(null)
+          setError(null)
+          const ops = Object.keys(user)
+            .filter((key) => FIELDS.some((field) => field.key === key))
+            .map((key) => ({ op: 'unset', path: [key] }))
+          if (ops.length === 0) return
+          setPending(true)
+          write(ops).then((accepted) => {
+            // The Host resolves false when it refuses the write, so a swallowed
+            // refusal would leave the override in place with nothing said.
+            if (accepted === false) setError(t('rejected'))
+          }).catch((cause) => {
+            setError(t('failed', { message: cause instanceof Error ? cause.message : String(cause) }))
+          }).finally(() => { setPending(false) })
+        }
+
+        const overridden = Object.keys(user).some((key) => FIELDS.some((field) => field.key === key))
+
+        return React.createElement(
+          'div',
+          { className: 'or-page' },
+          ...FIELDS.map((field) => React.createElement(Field, {
+            key: field.key,
+            t,
+            field,
+            value: String(shown[field.key] ?? ''),
+            overridden: Object.hasOwn(user, field.key),
+            disabled: busy,
+            onChange: (key, value) => {
+              setStatus(null)
+              setDraft({ ...shown, [key]: value })
+            },
+          })),
+          React.createElement(
+            'div',
+            { className: 'or-row' },
+            React.createElement(
+              'button',
+              { type: 'button', className: 'or-button', disabled: busy, onClick: save },
+              t('save'),
+            ),
+            overridden
+              ? React.createElement(
+                'button',
+                { type: 'button', className: 'or-button or-button-quiet', disabled: busy, onClick: reset },
+                t('reset'),
+              )
+              : null,
+          ),
+          React.createElement(
+            'div',
+            { className: 'or-status' },
+            status ?? (snapshot.writable ? t('persists') : t('readOnly')),
+            ' ',
+            t('version', { version: VERSION }),
+          ),
+          error === null ? null : React.createElement('div', { className: 'or-error' }, error),
+        )
+      }
+    }
+
+    /**
+     * Mount the browser surface: the OmniRoute card on the Plugins page.
+     * @param ctx - the browser plugin context.
+     */
+    function apply(ctx) {
+      const t = ctx.locale.bind(LOCALE_NS)
+      ctx.effect(
+        () => ctx.locale.register(LOCALE_NS, { en, zh }),
+        'dsh-omniroute: locale dictionary',
+      )
+
+      const scope = ctx.configForms.get(NAMESPACE)
+      const Card = createCard(scope, t)
+
+      // The owner declares its own slot; injecting waits for it to exist, so
+      // this registration does not depend on plugin load order. The card takes
+      // no injected props (it closes over its own bound scope), so the entry
+      // declares the documented `locale` namespace and no `inject`.
+      ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
+        name: 'plugins.row.config',
+        key: '@maci0/dsh-omniroute#omniroute',
+        locale: LOCALE_NS,
+      }, Card))
+    }
+
+    exports.apply = apply
+    exports.inject = ['slots', 'configForms', 'locale']
+    return module.exports
+  },
+})

package/lib/host.js

@@ -0,0 +1,12 @@
+/**
+ * The slice of the DeepSeek Harness host surface this plugin uses, declared
+ * structurally.
+ *
+ * The plugin installs from outside the harness checkout and has no runtime
+ * dependency on harness packages: the services it reaches are typed here, and
+ * a composition that mounts none of them simply omits that capability. The
+ * same shape also lets the unit tests drive `apply` with a plain fake context.
+ *
+ * @module dsh-omniroute/host
+ */
+export {};