@maci0/dsh-omniroute 0.0.0-stage → 0.8.3

package/lib/index.js

@@ -0,0 +1,403 @@
+/**
+ * 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 Schema from '@deepseek-ai/schemastery';
+import { createOmniRouteApi, OmniRouteError, BASE_URL_PATTERN, originOf, } from './omniroute.js';
+/** Plugin name as it appears in the loader. */
+export 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 const inject = ['webServer', 'connection'];
+/** The live model catalog. */
+export const ROUTE_MODELS = '/omniroute/models';
+/** The upstream connections. */
+export const ROUTE_CONNECTIONS = '/omniroute/connections';
+/** The quota every connection publishes. */
+export const ROUTE_QUOTA = '/omniroute/quota';
+/** Where an OmniRoute deployment listens unless configuration says otherwise. */
+export const DEFAULT_BASE_URL = 'http://localhost:20128';
+/** Credential reference tried when the plugin row names none. */
+export const DEFAULT_API_KEY_ENV = 'OMNIROUTE_API_KEY';
+/** Per-request deadline for one OmniRoute call, in milliseconds. */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/** Seconds one reading is served without asking OmniRoute again. */
+export const DEFAULT_CACHE_SECONDS = 30;
+/** Profile entry id of the provider route a model sync writes into. */
+export const DEFAULT_SYNC_NAMESPACE = 'llm-pi-ai';
+/** Provider route a model sync writes into. */
+export const DEFAULT_SYNC_PROVIDER = 'omniroute';
+/**
+ * Field defaults and bounds with no volatility wrapper. {@link resolveRow}
+ * parses a plain row through this schema, so its output is plain values; the
+ * loader-facing {@link Config} below is the same shape with every field made
+ * `volatile()`. The pair is asserted equal in the suite.
+ */
+const ValueSchema = Schema.object({
+    baseURL: Schema.string().default(DEFAULT_BASE_URL),
+    apiKeyEnv: Schema.string().default(DEFAULT_API_KEY_ENV),
+    timeoutMs: Schema.number().min(1).max(60_000).default(DEFAULT_TIMEOUT_MS),
+    cacheSeconds: Schema.number().min(0).max(3_600).default(DEFAULT_CACHE_SECONDS),
+    syncNamespace: Schema.string().default(DEFAULT_SYNC_NAMESPACE),
+    syncProvider: Schema.string().default(DEFAULT_SYNC_PROVIDER),
+});
+/**
+ * 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 const Config = Schema.object({
+    baseURL: Schema.string().pattern(BASE_URL_PATTERN).default(DEFAULT_BASE_URL).volatile(),
+    apiKeyEnv: Schema.string().default(DEFAULT_API_KEY_ENV).volatile(),
+    timeoutMs: Schema.number().min(1).max(60_000).default(DEFAULT_TIMEOUT_MS).volatile(),
+    cacheSeconds: Schema.number().min(0).max(3_600).default(DEFAULT_CACHE_SECONDS).volatile(),
+    syncNamespace: Schema.string().default(DEFAULT_SYNC_NAMESPACE).volatile(),
+    syncProvider: Schema.string().default(DEFAULT_SYNC_PROVIDER).volatile(),
+});
+/**
+ * Read one configured field as a plain value.
+ *
+ * The loader hands a `volatile()` field a live reference; a direct caller (a
+ * test, another plugin composing this one) hands the value itself. Both are
+ * accepted, so one read path serves both.
+ * @param value - the configured value, live or plain.
+ * @returns the current plain value, or `undefined` when a reference holds none.
+ */
+function readLive(value) {
+    if (value !== null && typeof value === 'object' && typeof value.get === 'function') {
+        // A scalar snapshot is the value; the generic cannot narrow that itself.
+        return value.get();
+    }
+    return value;
+}
+/**
+ * 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 function resolveRow(row = {}) {
+    return ValueSchema({
+        baseURL: readLive(row.baseURL),
+        apiKeyEnv: readLive(row.apiKeyEnv),
+        timeoutMs: readLive(row.timeoutMs),
+        cacheSeconds: readLive(row.cacheSeconds),
+        syncNamespace: readLive(row.syncNamespace),
+        syncProvider: readLive(row.syncProvider),
+    });
+}
+/** Write a JSON reply; readings are live facts and are never browser-cached. */
+function sendJson(res, status, payload) {
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.setHeader('cache-control', 'no-store');
+    res.end(JSON.stringify(payload));
+}
+/**
+ * Query parameters of a request target.
+ *
+ * Only the query matters here, so only the query is parsed: building a `URL`
+ * for every poll pays for an origin the routes never read.
+ * @param url - request target, path and query.
+ * @returns the decoded parameters.
+ */
+function searchParamsOf(url) {
+    // The fragment is not part of the request target a `URL` would parse either,
+    // and a target whose `#` precedes its `?` must not have the fragment read as
+    // query text.
+    const hash = url.indexOf('#');
+    const target = hash < 0 ? url : url.slice(0, hash);
+    const start = target.indexOf('?');
+    if (start < 0)
+        return new URLSearchParams();
+    return new URLSearchParams(target.slice(start + 1));
+}
+/**
+ * Resolve the OmniRoute API key: the configured reference first, then the
+ * launcher's own environment for that name.
+ * @param ctx - host context.
+ * @param envName - the reference to resolve.
+ * @returns the key, or `undefined` when neither source has one.
+ */
+async function apiKeyOf(ctx, envName) {
+    const credentials = ctx.get('credentials');
+    const resolved = await credentials?.resolve(envName);
+    const stored = resolved?.value;
+    if (stored !== undefined && stored.length > 0)
+        return stored;
+    const ambient = process.env[envName];
+    return ambient !== undefined && ambient.length > 0 ? ambient : undefined;
+}
+/**
+ * Copy the live catalog into a provider route's settings.
+ * @param ctx - host context.
+ * @param namespace - profile entry id to merge into.
+ * @param provider - provider route to write models for.
+ * @param models - the catalog to write, already filtered to what is servable.
+ * @returns the count written.
+ */
+async function syncModels(ctx, namespace, provider, models) {
+    const settings = ctx.get('settings');
+    if (settings === undefined)
+        throw new OmniRouteError('the settings service is not mounted, so nothing can be written');
+    const entries = models.map(model => {
+        const entry = { id: model.id };
+        if (model.name !== undefined)
+            entry['name'] = model.name;
+        return entry;
+    });
+    try {
+        await settings.update(namespace, { providers: { [provider]: { models: entries } } });
+    }
+    catch (error) {
+        ctx.logger.warn(`omniroute: the model sync into ${namespace} failed (${String(error)})`);
+        throw new OmniRouteError(`the settings service refused the model sync into ${namespace}; the host log names the cause`);
+    }
+    return entries.length;
+}
+/**
+ * Mount the host half.
+ * @param ctx - host context carrying the route carrier.
+ * @param config - this plugin's row configuration.
+ */
+export function apply(ctx, row = {}) {
+    // Read the row at every use: each field is volatile, so a save from the
+    // Plugins card has to reach the next request, not a mount-time copy.
+    const live = () => resolveRow(row);
+    /**
+     * The origin the live `baseURL` names, derived once per distinct value.
+     *
+     * Deriving it per request is what makes an edit take effect; doing it more
+     * than once per distinct value is what the served-read cost guard forbids,
+     * because parsing an origin is not free and a settled row never changes.
+     */
+    let originKey;
+    let originValue = '';
+    const liveOrigin = () => {
+        const { baseURL } = live();
+        if (baseURL !== originKey) {
+            // Remembered only once it parsed, so a malformed value fails every read.
+            originValue = originOf(baseURL);
+            originKey = baseURL;
+        }
+        return originValue;
+    };
+    // A row passed by a direct caller skipped the loader's schema: validate it
+    // at mount, so a malformed baseURL fails here rather than on the first poll.
+    liveOrigin();
+    /**
+     * The live origin for a reply that reports a failure, or nothing while the
+     * baseURL is malformed: that malformation is then the failure reported.
+     */
+    const knownOrigin = () => {
+        try {
+            return { origin: liveOrigin() };
+        }
+        catch {
+            return {};
+        }
+    };
+    const cache = new Map();
+    const inflight = new Map();
+    // Bumped by a settings write. A read that started before one belongs to the
+    // old row, so it must not fill the cache the write just emptied: doing so
+    // would serve the previous origin or cache window for another whole window.
+    let generation = 0;
+    /** The client for one request, built after its credential resolved. */
+    const apiFor = async (origin, { apiKeyEnv, timeoutMs }) => {
+        const key = await apiKeyOf(ctx, apiKeyEnv);
+        if (key === undefined)
+            throw new OmniRouteError(`no OmniRoute API key is configured (${apiKeyEnv})`);
+        return createOmniRouteApi({ origin, key, timeoutMs });
+    };
+    /** Serve one cached read, keyed by route name. */
+    const read = async (key, refresh, load) => {
+        const hit = cache.get(key);
+        if (!refresh && hit !== undefined && Date.now() - hit.at < live().cacheSeconds * 1_000)
+            return hit.value;
+        const running = inflight.get(key);
+        if (running !== undefined)
+            return running;
+        const started = generation;
+        const pending = load().then((value) => {
+            // A write that landed mid-read emptied the cache; the value it fetched
+            // belongs to the row before the write, so it is answered but not kept.
+            if (started === generation)
+                cache.set(key, { at: Date.now(), value });
+            return value;
+        }).finally(() => {
+            // Only this read's own entry: a write that landed mid-read cleared the
+            // map, a later poll installed its own read under the same key, and
+            // retracting that one would leave the next poll with nothing to join.
+            if (inflight.get(key) === pending)
+                inflight.delete(key);
+        });
+        inflight.set(key, pending);
+        return pending;
+    };
+    /** The catalog, filtered the way the query string asked for. */
+    const filtered = (models, params) => {
+        const query = (params.get('q') ?? '').toLowerCase();
+        const provider = params.get('provider');
+        const onlyAvailable = params.get('available') === '1';
+        // Nothing narrows the read: hand back the cached catalog rather than
+        // walking it once per request to build an identical copy.
+        if (query === '' && (provider === null || provider === '') && !onlyAvailable)
+            return models;
+        return models.filter((model) => {
+            if (onlyAvailable && !model.available)
+                return false;
+            if (provider !== null && provider !== '' && model.provider !== provider)
+                return false;
+            if (query === '')
+                return true;
+            return model.id.toLowerCase().includes(query)
+                || (model.name ?? '').toLowerCase().includes(query)
+                || (model.alias ?? '').toLowerCase().includes(query);
+        });
+    };
+    const modelsRoute = async (params, refresh) => {
+        const row = live();
+        const { syncNamespace, syncProvider } = row;
+        const origin = liveOrigin();
+        // The available count is a property of the reading, not of the request, so
+        // it is counted once per fetch and cached beside the catalog.
+        const catalog = await read('models', refresh, async () => {
+            const api = await apiFor(origin, row);
+            const models = await api.models();
+            let available = 0;
+            for (const model of models)
+                if (model.available)
+                    available += 1;
+            return { models, available, fetchedAt: Date.now() };
+        });
+        const shown = filtered(catalog.models, params);
+        const reply = {
+            status: 'ok',
+            provider: syncProvider,
+            origin,
+            fetchedAt: catalog.fetchedAt,
+            counts: {
+                total: catalog.models.length,
+                available: catalog.available,
+                shown: shown.length,
+            },
+            models: shown,
+        };
+        if (params.get('sync') === '1') {
+            const written = await syncModels(ctx, syncNamespace, syncProvider, shown.filter(model => model.available));
+            reply['synced'] = {
+                namespace: syncNamespace,
+                path: `providers.${syncProvider}.models`,
+                count: written,
+            };
+            ctx.logger.warn(`omniroute: wrote ${String(written)} models into ${syncNamespace}.providers.${syncProvider}.models`);
+        }
+        return reply;
+    };
+    /**
+     * The connection list and the windows read from it are one reading: cached
+     * apart, a refresh of one alone would answer with windows for connections the
+     * same reply does not list. Both routes therefore serve this pair, so the two
+     * halves can never disagree, and `/api/providers` is asked once per miss.
+     */
+    const readConnections = (origin, row, refresh) => read('connections', refresh, async () => {
+        const api = await apiFor(origin, row);
+        const listed = await api.connections();
+        const windows = await api.quota(listed);
+        return { connections: listed, windows, fetchedAt: Date.now() };
+    });
+    const connectionsRoute = async (refresh) => {
+        const row = live();
+        const origin = liveOrigin();
+        const { connections, fetchedAt } = await readConnections(origin, row, refresh);
+        return { status: 'ok', origin, fetchedAt, total: connections.length, connections };
+    };
+    const quotaRoute = async (refresh) => {
+        const row = live();
+        const origin = liveOrigin();
+        const { connections, windows, fetchedAt } = await readConnections(origin, row, refresh);
+        return {
+            status: 'ok',
+            origin,
+            fetchedAt,
+            connections,
+            windows,
+            limitReached: windows.filter(window => window.limitReached).map(window => window.plan ?? window.connection),
+        };
+    };
+    /** One shared GET wrapper around every route handler. */
+    const handlerFor = (path, run) => async (req, res) => {
+        const rejection = ctx.connection.requestRejection(req);
+        if (rejection !== undefined) {
+            res.statusCode = rejection;
+            res.end();
+            return;
+        }
+        if ((req.method ?? 'GET').toUpperCase() !== 'GET') {
+            res.setHeader('allow', 'GET');
+            sendJson(res, 405, { status: 'error', message: 'this route answers GET only' });
+            return;
+        }
+        const params = searchParamsOf(String(req.url));
+        try {
+            sendJson(res, 200, await run(params, params.get('refresh') === '1'));
+        }
+        catch (error) {
+            // A refusal never carries the key, the router's own body, or another
+            // service's exception text: only this plugin's own sentence is sent,
+            // and anything else is logged here and answered generically.
+            let message;
+            if (error instanceof OmniRouteError) {
+                message = error.message;
+            }
+            else {
+                ctx.logger.warn(`omniroute: GET ${path} failed (${String(error)})`);
+                message = 'the read failed; the host log names the cause';
+            }
+            sendJson(res, 502, { status: 'error', message, ...knownOrigin() });
+        }
+    };
+    const routes = [
+        [ROUTE_MODELS, modelsRoute],
+        [ROUTE_CONNECTIONS, (_params, refresh) => connectionsRoute(refresh)],
+        [ROUTE_QUOTA, (_params, refresh) => quotaRoute(refresh)],
+    ];
+    for (const [path, run] of routes) {
+        ctx.effect(() => ctx.webServer.register({ kind: 'exact', path, handler: handlerFor(path, run) }), `omniroute: GET ${path}`);
+    }
+    // A settings write moves the live references in place. Dropping the served
+    // readings makes the next poll answer from the edited row instead of a
+    // cached body fetched from the previous origin, and the log line records it.
+    ctx.on('loader/volatile-update', () => {
+        cache.clear();
+        // A poll that starts after the write must ask the new row, so the reads the
+        // old row started stop being handed out. Their callers still get an answer.
+        inflight.clear();
+        generation += 1;
+        const { apiKeyEnv, timeoutMs, cacheSeconds, syncNamespace, syncProvider } = live();
+        ctx.logger.warn(`omniroute: configuration updated: ${knownOrigin().origin ?? 'an invalid baseURL'} as ${apiKeyEnv},`
+            + ` ${timeoutMs}ms deadline, ${cacheSeconds}s cache, sync into ${syncNamespace}.providers.${syncProvider}`);
+    });
+}

package/lib/omniroute.js

@@ -0,0 +1,206 @@
+/**
+ * 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
+ */
+import { numberOf, record, stringOf } from './util.js';
+/**
+ * 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 class OmniRouteError extends Error {
+    name = 'OmniRouteError';
+}
+/**
+ * Parse a `GET /api/models` body.
+ * @param payload - the decoded body.
+ * @returns one entry per model the body carried.
+ */
+export function parseModels(payload) {
+    const entries = record(payload)?.['models'];
+    if (!Array.isArray(entries))
+        return [];
+    const models = [];
+    for (const entry of entries) {
+        const model = record(entry);
+        if (model === undefined)
+            continue;
+        const id = stringOf(model['fullModel']) ?? stringOf(model['model']);
+        if (id === undefined)
+            continue;
+        models.push({
+            id,
+            provider: stringOf(model['provider']) ?? 'omniroute',
+            name: stringOf(model['name']),
+            alias: stringOf(model['alias']),
+            available: model['available'] === true,
+            vision: model['supportsVision'] === true,
+        });
+    }
+    return models;
+}
+/**
+ * Parse a `GET /api/providers` body.
+ * @param payload - the decoded body.
+ * @returns one entry per connection the body carried.
+ */
+export function parseConnections(payload) {
+    const entries = record(payload)?.['connections'];
+    if (!Array.isArray(entries))
+        return [];
+    const connections = [];
+    for (const entry of entries) {
+        const connection = record(entry);
+        if (connection === undefined)
+            continue;
+        const id = stringOf(connection['id']);
+        if (id === undefined)
+            continue;
+        connections.push({
+            id,
+            provider: stringOf(connection['provider']) ?? 'omniroute',
+            name: stringOf(connection['name']),
+            active: connection['isActive'] !== false,
+            quotaVisible: connection['quotaVisible'] !== false,
+        });
+    }
+    return connections;
+}
+/**
+ * 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 function parseUsage(payload, connection) {
+    const usage = record(payload);
+    if (usage === undefined)
+        return [];
+    const quotas = record(usage['quotas']);
+    if (quotas === undefined)
+        return [];
+    const plan = stringOf(usage['plan']) ?? connection.name ?? connection.provider;
+    const limitReached = usage['limitReached'] === true;
+    const windows = [];
+    for (const [window, raw] of Object.entries(quotas)) {
+        const meter = record(raw);
+        if (meter === undefined)
+            continue;
+        windows.push({
+            connection: connection.id,
+            provider: connection.provider,
+            plan,
+            window,
+            used: numberOf(meter['used']),
+            total: numberOf(meter['total']),
+            remaining: numberOf(meter['remaining']),
+            remainingPercent: numberOf(meter['remainingPercentage']),
+            unlimited: meter['unlimited'] === true,
+            resetAt: stringOf(meter['resetAt']),
+            currency: stringOf(meter['currency']),
+            limitReached,
+        });
+    }
+    return windows;
+}
+/**
+ * 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 const BASE_URL_PATTERN = /^https?:\/\/[^\s/?#]+/iu;
+/**
+ * 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 function originOf(baseURL) {
+    if (BASE_URL_PATTERN.test(baseURL) && URL.canParse(baseURL))
+        return new URL(baseURL).origin;
+    throw new OmniRouteError('baseURL is not an absolute http(s) URL; fix the omniroute row');
+}
+/**
+ * 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 function createOmniRouteApi(options) {
+    const transport = options.fetchImpl ?? globalThis.fetch;
+    const headers = { authorization: `Bearer ${options.key}`, accept: 'application/json' };
+    const get = async (path) => {
+        let response;
+        try {
+            response = await transport(`${options.origin}${path}`, {
+                headers,
+                signal: AbortSignal.timeout(options.timeoutMs),
+            });
+        }
+        catch (error) {
+            // `AbortSignal.timeout` rejects with a `TimeoutError`; anything else is
+            // a connection that never produced a response.
+            throw new OmniRouteError(error instanceof Error && error.name === 'TimeoutError'
+                ? `OmniRoute did not answer ${path} within ${String(options.timeoutMs)}ms`
+                : `OmniRoute could not be reached for ${path}`);
+        }
+        if (!response.ok) {
+            throw new OmniRouteError(`OmniRoute answered HTTP ${String(response.status)} for ${path}`);
+        }
+        // A body that is not JSON is reported as that and nothing more: the parse
+        // error a JSON reader raises quotes the first bytes of whatever the router
+        // answered, which would put the router's own body in this plugin's reply.
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new OmniRouteError(`OmniRoute answered a non-JSON body for ${path}`);
+        }
+    };
+    const connections = async () => parseConnections(await get('/api/providers'));
+    return {
+        models: async () => parseModels(await get('/api/models')),
+        connections,
+        quota: async (listed) => {
+            const all = listed ?? await connections();
+            // A connection that is off, or hides its quota, is not asked at all; one
+            // that fails to answer contributes no window rather than failing the read.
+            // An id of `.` or `..` is asked neither: it survives `encodeURIComponent`
+            // and the URL parser then climbs out of `/api/usage/` into a different
+            // router endpoint, so no path can address it.
+            const asked = all.filter(connection => connection.active && connection.quotaVisible
+                && connection.id !== '.' && connection.id !== '..');
+            const answers = await Promise.all(asked.map(async (connection) => {
+                try {
+                    return parseUsage(await get(`/api/usage/${encodeURIComponent(connection.id)}`), connection);
+                }
+                catch {
+                    return [];
+                }
+            }));
+            return answers.flat();
+        },
+    };
+}