@maci0/dsh-omniroute 0.0.0-stage → 0.8.2

package/lib/types/host.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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
+ */
+/** Disposer returned by every host registration. */
+export type Disposable = () => void;
+/** The slice of the credentials service this plugin reads. */
+export interface CredentialsLike {
+    /**
+     * Resolve one credential reference to its value.
+     * @param ref - environment-variable-style reference name.
+     * @returns the resolved value, or `undefined` when nothing is stored.
+     */
+    resolve(ref: string): Promise<{
+        readonly value: string;
+    } | undefined>;
+}
+/** The slice of the settings service this plugin writes through. */
+export interface SettingsLike {
+    /**
+     * Merge a patch into one profile entry.
+     * @param ns - profile entry id, not a settings namespace.
+     * @param patch - plain-object patch over that entry.
+     * @returns when the write is persisted.
+     */
+    update(ns: string, patch: object): Promise<void>;
+}
+/** Request subset the trust fence reads. */
+export interface RequestLike {
+    /** Request method. */
+    readonly method?: string | undefined;
+    /** Request target, including the query string. */
+    readonly url?: string | undefined;
+    /** Request headers, read by the composition's trust fence. */
+    readonly headers: object | undefined;
+}
+/** Response subset this plugin writes. */
+export interface ResponseLike {
+    /** HTTP status code. */
+    statusCode: number;
+    /** Set one response header. */
+    setHeader(name: string, value: string): void;
+    /** End the response, optionally with a body. */
+    end(body?: string): void;
+}
+/** One exact-path route registration. */
+export interface WebRouteLike {
+    /** Match kind; this plugin registers only exact paths. */
+    readonly kind: 'exact';
+    /** Absolute pathname, no trailing slash. */
+    readonly path: string;
+    /** Owns the full response lifecycle. */
+    handler: (req: RequestLike, res: ResponseLike) => void | Promise<void>;
+}
+/** The slice of the HTTP carrier this plugin registers on. */
+export interface WebServerLike {
+    /**
+     * Register one route.
+     * @param route - path, match kind, and handler.
+     * @returns the disposer that withdraws it.
+     */
+    register(route: WebRouteLike): Disposable;
+}
+/** The composition's trust fence. */
+export interface ConnectionLike {
+    /**
+     * Reject an untrusted or unauthenticated request.
+     * @param request - headers of the incoming request.
+     * @returns the rejection status, or `undefined` when the request may proceed.
+     */
+    requestRejection(request: {
+        readonly headers: object | undefined;
+    }): 401 | 403 | undefined;
+}
+/**
+ * Structural view of the Cordis context this plugin uses.
+ *
+ * `inject` guarantees `webServer` and `connection`; the credentials and
+ * settings services are read through `get`, so a composition without them
+ * degrades to "no credential to read with" and refuses the model sync instead
+ * of failing to mount.
+ */
+export interface HostContext {
+    /** Bind a registration's lifetime to this plugin's fiber. */
+    effect(callback: () => Disposable | void, label?: string): unknown;
+    /**
+     * Subscribe to a host event. This plugin watches `loader/volatile-update`,
+     * which is what a settings write emits once the live row references moved.
+     * @param event - the event name.
+     * @param listener - the callback.
+     * @returns the disposer that removes this listener.
+     */
+    on(event: 'loader/volatile-update', listener: () => void): Disposable;
+    /** Read one optional service. */
+    get(name: string): unknown;
+    /** Structured log surface. */
+    readonly logger: {
+        warn(message: string): void;
+        error(message: string): void;
+    };
+    /** HTTP route carrier (guaranteed by `inject`). */
+    readonly webServer: WebServerLike;
+    /** Trust fence every route checks first (guaranteed by `inject`). */
+    readonly connection: ConnectionLike;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * dsh-omniroute: OmniRoute's own API surface, inside DeepSeek Harness.
+ *
+ * Three read-only routes, all behind the composition's trust fence and all
+ * serving JSON:
+ *
+ * - `GET /omniroute/models`: the live model catalog from OmniRoute's
+ *   `GET /api/models`: which models exist, which ones the router can serve
+ *   right now, and which take images. `?available=1`, `?q=<text>` and
+ *   `?provider=<key>` narrow it. `?sync=1` also writes the available models
+ *   into a configured provider route, which is how the model picker learns
+ *   them.
+ * - `GET /omniroute/connections`: the upstream connections from
+ *   `GET /api/providers`.
+ * - `GET /omniroute/quota`: the plan and windows of every connection that
+ *   publishes one, from `GET /api/usage/<connectionId>`.
+ *
+ * The API key stays in this process: the browser or the model only ever reads
+ * the JSON these routes return. Readings are cached for a few seconds per
+ * route, so a refresh loop cannot multiply requests to the router.
+ *
+ * @module dsh-omniroute
+ */
+import type { Volatile } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import type { HostContext } from './host.ts';
+/** Plugin name as it appears in the loader. */
+export declare const name = "omniroute";
+/**
+ * The route carrier, and the trust fence every route checks first: without
+ * `connection` nothing would refuse a cross-origin or unauthenticated caller,
+ * so the plugin waits for it rather than serving unfenced.
+ */
+export declare const inject: string[];
+/** The live model catalog. */
+export declare const ROUTE_MODELS = "/omniroute/models";
+/** The upstream connections. */
+export declare const ROUTE_CONNECTIONS = "/omniroute/connections";
+/** The quota every connection publishes. */
+export declare const ROUTE_QUOTA = "/omniroute/quota";
+/** Where an OmniRoute deployment listens unless configuration says otherwise. */
+export declare const DEFAULT_BASE_URL = "http://localhost:20128";
+/** Credential reference tried when the plugin row names none. */
+export declare const DEFAULT_API_KEY_ENV = "OMNIROUTE_API_KEY";
+/** Per-request deadline for one OmniRoute call, in milliseconds. */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/** Seconds one reading is served without asking OmniRoute again. */
+export declare const DEFAULT_CACHE_SECONDS = 30;
+/** Profile entry id of the provider route a model sync writes into. */
+export declare const DEFAULT_SYNC_NAMESPACE = "llm-pi-ai";
+/** Provider route a model sync writes into. */
+export declare const DEFAULT_SYNC_PROVIDER = "omniroute";
+/**
+ * Configuration this plugin's row resolves to, as `apply` receives it.
+ *
+ * Every field is `volatile()` (the settings document accepts writes only under
+ * a volatile node, and the Plugins page's OmniRoute card edits exactly these),
+ * so the loader hands live references and each is read per request. `baseURL`
+ * and `apiKeyEnv` decide where the plugin talks and as whom; the two sync
+ * fields name the row `?sync=1` writes a model catalog into.
+ */
+export interface Config {
+    /** OmniRoute origin, with or without its `/v1` path. @default http://localhost:20128 */
+    readonly baseURL: Volatile<string>;
+    /** Credential reference holding the OmniRoute API key. @default OMNIROUTE_API_KEY */
+    readonly apiKeyEnv: Volatile<string>;
+    /** Per-request deadline in milliseconds. @default 10000 */
+    readonly timeoutMs: Volatile<number>;
+    /** Seconds a reading stays cached. `0` re-asks on every request. @default 30 */
+    readonly cacheSeconds: Volatile<number>;
+    /** Profile entry id `?sync=1` writes the model catalog into. @default llm-pi-ai */
+    readonly syncNamespace: Volatile<string>;
+    /** Provider route `?sync=1` writes the model catalog into. @default omniroute */
+    readonly syncProvider: Volatile<string>;
+}
+/** Raw row values, as a profile patch states them and as direct callers pass them. */
+export type Options = {
+    [K in keyof Config]?: Config[K] extends Volatile<infer T> ? T : Config[K];
+};
+/**
+ * Row schema as Cordis resolves it: what this plugin's `config` is validated
+ * against, and where each default lives. Every field is editable from the
+ * Plugins page, so every one is volatile.
+ */
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    baseURL: Schema<string, string, "volatile-defined">;
+    apiKeyEnv: Schema<string, string, "volatile-defined">;
+    timeoutMs: Schema<number, number, "volatile-defined">;
+    cacheSeconds: Schema<number, number, "volatile-defined">;
+    syncNamespace: Schema<string, string, "volatile-defined">;
+    syncProvider: Schema<string, string, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    baseURL: Schema<string, string, "volatile-defined">;
+    apiKeyEnv: Schema<string, string, "volatile-defined">;
+    timeoutMs: Schema<number, number, "volatile-defined">;
+    cacheSeconds: Schema<number, number, "volatile-defined">;
+    syncNamespace: Schema<string, string, "volatile-defined">;
+    syncProvider: Schema<string, string, "volatile-defined">;
+}>>, "plain">;
+/**
+ * Turn a row (live references or plain values) into validated plain options.
+ * @param row - the configured row.
+ * @returns the resolved options, defaults filled by the schema.
+ */
+export declare function resolveRow(row?: Config | Options): Required<Options>;
+/**
+ * Mount the host half.
+ * @param ctx - host context carrying the route carrier.
+ * @param config - this plugin's row configuration.
+ */
+export declare function apply(ctx: HostContext, row?: Config | Options): void;

package/lib/types/omniroute.d.ts

@@ -0,0 +1,159 @@
+/**
+ * OmniRoute management-API client: the live model catalog, the provider
+ * connections, and the quota each connection reports.
+ *
+ * The endpoints are OmniRoute's own, read from a running `v3.8.50` server's
+ * `/api/openapi/spec` and `/api/agent-skills` directory:
+ *
+ * - `GET /api/models`: every model across the configured providers, each with
+ *   an `available` flag and a `supportsVision` flag. This is the management
+ *   listing, not the OpenAI-shaped `GET /v1/models`: it is the one that says
+ *   which models the router can actually serve *now*.
+ * - `GET /api/providers`: the upstream connections. Each carries the `id` that
+ *   the per-connection usage route addresses, plus `quotaVisible` and
+ *   `isActive`.
+ * - `GET /api/usage/<connectionId>`: that connection's plan, its windows
+ *   (`session`, `weekly`, `credits_usd`, …), and whether the limit is reached.
+ *
+ * OmniRoute routes to accounts it holds, so it publishes no figure for the
+ * router itself; quota is read per connection and flattened into one list.
+ * `/api/quota/plans` resolves plans but carries no consumption, and
+ * `/api/quota/pools` is empty unless the deployment defines pools, so neither
+ * is used here.
+ *
+ * Everything below the `createOmniRouteApi` line is pure parsing; the tests
+ * drive it with payloads copied from a live server.
+ *
+ * @module dsh-omniroute/omniroute
+ */
+/**
+ * A failure this plugin phrased itself. Only its message reaches a route
+ * reply; any other error is logged on the host and answered generically.
+ */
+export declare class OmniRouteError extends Error {
+    readonly name = "OmniRouteError";
+}
+/** One model OmniRoute advertises. */
+export interface OmniRouteModel {
+    /** Id a request names: the `fullModel` when the listing has one. */
+    readonly id: string;
+    /** Upstream provider key, e.g. `glm` or `cc`. */
+    readonly provider: string;
+    /** Display name, when the listing carries one. */
+    readonly name?: string;
+    /** Short alias, when the listing carries one. */
+    readonly alias?: string;
+    /** Whether the router can serve it right now. */
+    readonly available: boolean;
+    /** Whether it accepts images. */
+    readonly vision: boolean;
+}
+/** One upstream connection OmniRoute holds. */
+export interface OmniRouteConnection {
+    /** Connection id, which the usage route addresses. */
+    readonly id: string;
+    /** Upstream provider key, e.g. `deepseek`. */
+    readonly provider: string;
+    /** Human label for the connection, e.g. an account address. */
+    readonly name?: string;
+    /** Whether the connection is switched on. */
+    readonly active: boolean;
+    /** Whether the connection publishes its quota. */
+    readonly quotaVisible: boolean;
+}
+/** One quota window of one connection. */
+export interface OmniRouteQuota {
+    /** Connection the window belongs to. */
+    readonly connection: string;
+    /** Upstream provider key of that connection. */
+    readonly provider: string;
+    /** Resolved plan name the connection reported, e.g. `plus` or `DeepSeek`. */
+    readonly plan?: string;
+    /** Window name as OmniRoute spells it, e.g. `session (5h)` or `credits_usd`. */
+    readonly window: string;
+    /** Consumed amount, in the window's own unit. */
+    readonly used?: number;
+    /** Window ceiling, when it has one. */
+    readonly total?: number;
+    /** Amount left, when the connection reports one. */
+    readonly remaining?: number;
+    /** Percentage left as the connection reports it. */
+    readonly remainingPercent?: number;
+    /** Whether the connection reports no ceiling at all. */
+    readonly unlimited: boolean;
+    /** ISO instant the window resets, when it reports one. */
+    readonly resetAt?: string;
+    /** Currency of a money window, when it reports one. */
+    readonly currency?: string;
+    /** Whether the connection says the limit is reached. */
+    readonly limitReached: boolean;
+}
+/** Everything the client needs to talk to one OmniRoute deployment. */
+export interface OmniRouteApiOptions {
+    /** Deployment origin, without the `/v1` path, e.g. `http://box:20128`. */
+    readonly origin: string;
+    /** OmniRoute API key, sent as a bearer token. */
+    readonly key: string;
+    /** Per-request deadline in milliseconds. */
+    readonly timeoutMs: number;
+    /** Transport override, for tests. @default globalThis.fetch */
+    readonly fetchImpl?: typeof fetch;
+}
+/** The three reads this plugin offers. */
+export interface OmniRouteApi {
+    /**
+     * List every advertised model.
+     * @returns the catalog in listing order.
+     */
+    models(): Promise<readonly OmniRouteModel[]>;
+    /**
+     * List every upstream connection.
+     * @returns the connections in listing order.
+     */
+    connections(): Promise<readonly OmniRouteConnection[]>;
+    /**
+     * Read the quota of every connection that publishes one.
+     * @param listed - connections already read, so the caller does not make this
+     * client ask `/api/providers` a second time for the same reading.
+     * @returns one entry per window, connections in listing order.
+     */
+    quota(listed?: readonly OmniRouteConnection[]): Promise<readonly OmniRouteQuota[]>;
+}
+/**
+ * Parse a `GET /api/models` body.
+ * @param payload - the decoded body.
+ * @returns one entry per model the body carried.
+ */
+export declare function parseModels(payload: unknown): readonly OmniRouteModel[];
+/**
+ * Parse a `GET /api/providers` body.
+ * @param payload - the decoded body.
+ * @returns one entry per connection the body carried.
+ */
+export declare function parseConnections(payload: unknown): readonly OmniRouteConnection[];
+/**
+ * Parse one `GET /api/usage/<connectionId>` body.
+ * @param payload - the decoded body.
+ * @param connection - the connection it was asked about.
+ * @returns one entry per window the body carried.
+ */
+export declare function parseUsage(payload: unknown, connection: OmniRouteConnection): readonly OmniRouteQuota[];
+/**
+ * What a configured base URL must start with: an http(s) scheme and a host.
+ * A scheme-less `box:20128` parses as a URL whose origin is the string "null".
+ */
+export declare const BASE_URL_PATTERN: RegExp;
+/**
+ * Origin of a configured base URL, which is what carries OmniRoute's own API.
+ * @param baseURL - the configured value, with or without its `/v1` path.
+ * @returns the origin.
+ * @throws OmniRouteError when the value is not an absolute http(s) URL: no
+ * other origin is guessed, so the key never goes to a host nobody configured.
+ */
+export declare function originOf(baseURL: string): string;
+/**
+ * Build the client for one deployment.
+ * @param options - origin, credential, deadline, and transport.
+ * @returns the three reads, each failing loud on a refused request.
+ */
+export declare function createOmniRouteApi(options: OmniRouteApiOptions): OmniRouteApi;

package/lib/types/util.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Narrowing helpers for the OmniRoute client: every payload field is an
+ * `unknown` until one of these reads it.
+ *
+ * This package's own copy. The two plugins ship independently and share no
+ * package, so each keeps the handful of lines it narrows with.
+ *
+ * @module dsh-omniroute/util
+ */
+/** Narrow an unknown to an indexable object. */
+export declare function record(value: unknown): Record<string, unknown> | undefined;
+/** Read one field as a non-empty string, or `undefined`. */
+export declare function stringOf(value: unknown): string | undefined;
+/** Read one field as a finite number, or `undefined`. */
+export declare function numberOf(value: unknown): number | undefined;

package/lib/util.js

@@ -0,0 +1,24 @@
+/**
+ * Narrowing helpers for the OmniRoute client: every payload field is an
+ * `unknown` until one of these reads it.
+ *
+ * This package's own copy. The two plugins ship independently and share no
+ * package, so each keeps the handful of lines it narrows with.
+ *
+ * @module dsh-omniroute/util
+ */
+/** Narrow an unknown to an indexable object. */
+export function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Read one field as a non-empty string, or `undefined`. */
+export function stringOf(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Read one field as a finite number, or `undefined`. */
+export function numberOf(value) {
+    const parsed = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+    return typeof parsed === 'number' && Number.isFinite(parsed) ? parsed : undefined;
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OmniRoute",
+    "description": "Live model catalog, upstream connections, and per-connection quota from OmniRoute."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "OmniRoute",
+    "description": "查询 OmniRoute 的实时模型目录、上游连接，以及各连接的额度。"
+  }
+}

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@maci0/dsh-omniroute",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.2",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "description": "OmniRoute provider surface for DeepSeek Harness: query its live model catalog, its connections, and the quota each upstream connection reports.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maci0/dsh-omniroute.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": ">=0.2.0-rc.2 <0.3.0"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
+      ]
+    }
+  },
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "lib/**/*.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bunx --bun tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "bunx --bun tsc -p tsconfig.json",
+    "test:node": "node --test tests/*.test.*"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-alpha.1",
+    "@types/node": "^22.20.2",
+    "typescript": "^7.0.2"
+  },
+  "icon": "./icon.svg",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-locale": "*",
+    "@deepseek-ai/dsh-client-ui-renderer": "*",
+    "@deepseek-ai/dsh-client-ui-settings": "*",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-renderer": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-plugin-manager": {
+      "optional": true
+    }
+  }
+}