@leaves615/dsh-llm-ctl 0.1.0

package/lib/reasoning-efforts.js

@@ -0,0 +1,143 @@
+/**
+ * Reasoning-effort declarations for hand-declared `llm-pi-ai` models.
+ *
+ * A custom provider model shows no effort picker because its materialized
+ * pi-ai descriptor carries no reasoning capability. The official fix is a
+ * per-model `reasoningEfforts` declaration (plus `compat.supportsReasoningEffort`)
+ * written into the `llm-pi-ai` settings section. Everything here is pure data
+ * shaping so it is testable without a browser or a settings provider.
+ *
+ * Official vocabulary (escalation order): off, minimal, low, medium, high,
+ * xhigh, max. Locked default (official-aligned): off/low/high/max with an
+ * identity wire mapping, matching the official deepseek adapter's
+ * Off/Low/High/Max ladder.
+ *
+ * @module dsh-llm-ctl/reasoning-efforts
+ */
+/** Settings namespace owning hand-declared pi-ai routes. */
+export const PI_AI_SETTINGS_NS = 'llm-pi-ai';
+/** Thinking levels in escalation order. */
+export const THINKING_LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+/** Official-aligned default ladder: Off/Low/High/Max. */
+export const DEFAULT_EFFORT_LEVELS = ['off', 'low', 'high', 'max'];
+/** Advanced levels hidden behind the disclosure, off by default. */
+export const ADVANCED_EFFORT_LEVELS = ['minimal', 'medium', 'xhigh'];
+/**
+ * Build the default `reasoningEfforts` dict: every default level maps to
+ * itself, `off` included (explicit off switch, official-aligned).
+ *
+ * @param levels - levels to offer; defaults to the official ladder.
+ * @returns the dict to store on the model entry.
+ */
+export function defaultReasoningEfforts(levels = DEFAULT_EFFORT_LEVELS) {
+    const out = {};
+    for (const level of levels)
+        out[level] = level;
+    return out;
+}
+/**
+ * Validate a user-supplied effort dict against the official shape:
+ * non-empty, every key a known level, `off` may be string|null, every other
+ * declared level a non-empty string, and at least one level beyond `off`.
+ *
+ * @param value - candidate dict.
+ * @returns the failure reason, or undefined when valid.
+ */
+export function validateReasoningEfforts(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return 'reasoningEfforts must be an object';
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return 'declare at least one level, or reset to inherit';
+    const known = new Set(THINKING_LEVELS);
+    let beyondOff = false;
+    for (const [level, wire] of entries) {
+        if (!known.has(level))
+            return 'unknown thinking level: ' + level;
+        if (level !== 'off')
+            beyondOff = true;
+        if (wire === null) {
+            if (level !== 'off')
+                return 'only "off" may leave the wire value empty';
+        }
+        else if (typeof wire !== 'string' || wire.length === 0) {
+            return 'wire value for "' + level + '" must be a non-empty string';
+        }
+    }
+    if (!beyondOff)
+        return 'offer at least one level beyond "off"';
+    return undefined;
+}
+/**
+ * Summarize one model row for the effort editor.
+ *
+ * @param input - provider identity, settings namespace, stored entry, live catalog levels.
+ * @returns facts the UI renders from.
+ */
+export function summarizeModelEffort(input) {
+    const stored = input.entry?.reasoningEfforts;
+    const valid = stored !== undefined && validateReasoningEfforts(stored) === undefined;
+    const dict = valid ? stored : undefined;
+    return {
+        provider: input.provider,
+        model: input.model,
+        writableNs: input.settingsNs === PI_AI_SETTINGS_NS,
+        declared: input.entry !== undefined,
+        ...(dict === undefined ? {} : { stored: { ...dict } }),
+        levels: dict === undefined ? [] : Object.keys(dict),
+        ...(input.liveLevels === undefined ? {} : { liveLevels: [...input.liveLevels] }),
+    };
+}
+/**
+ * Build the settings ops that declare efforts for one model.
+ *
+ * Hand-declared routes (`settingsPath = ["providers", route]`) store the
+ * whole `models` array, so the op sets the full array with the entry merged.
+ * Catalog routes store per-model overrides under
+ * `providers.<route>.modelOverrides.<id>`, so the op targets the
+ * `reasoningEfforts` (and compat flag) paths directly.
+ *
+ * @param input - route identity, current models array (hand-declared only), target model, effort dict.
+ * @returns ordered ops for `settings.mutate`.
+ */
+export function buildEffortOps(input) {
+    const compat = { supportsReasoningEffort: true };
+    if (input.models !== undefined) {
+        let found = false;
+        const next = input.models.map((entry) => {
+            if (entry.id !== input.model)
+                return entry;
+            found = true;
+            return { ...entry, reasoningEfforts: { ...input.efforts }, compat: { ...(entry.compat ?? {}), ...compat } };
+        });
+        const rows = found ? next : [...next, { id: input.model, reasoningEfforts: { ...input.efforts }, compat }];
+        return [{ op: 'set', path: ['providers', input.provider, 'models'], value: rows }];
+    }
+    return [
+        { op: 'set', path: ['providers', input.provider, 'modelOverrides', input.model, 'reasoningEfforts'], value: { ...input.efforts } },
+        { op: 'set', path: ['providers', input.provider, 'modelOverrides', input.model, 'compat', 'supportsReasoningEffort'], value: true },
+    ];
+}
+/**
+ * Build the settings ops that reset efforts for one model (back to inherit).
+ *
+ * @param input - route identity, hand-declared models array, target model.
+ * @returns ordered ops for `settings.mutate`.
+ */
+export function buildEffortResetOps(input) {
+    if (input.models !== undefined) {
+        const next = input.models.map((entry) => {
+            if (entry.id !== input.model)
+                return entry;
+            const { reasoningEfforts: _dropped, compat: currentCompat, ...kept } = entry;
+            void _dropped;
+            if (currentCompat === undefined)
+                return kept;
+            const { supportsReasoningEffort: _flag, ...rest } = currentCompat;
+            void _flag;
+            return Object.keys(rest).length === 0 ? kept : { ...kept, compat: rest };
+        });
+        return [{ op: 'set', path: ['providers', input.provider, 'models'], value: next }];
+    }
+    return [{ op: 'unset', path: ['providers', input.provider, 'modelOverrides', input.model, 'reasoningEfforts'] }];
+}

package/lib/routes.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Browser channel for the control plane.
+ *
+ * A Typert Remote namespace is not reachable from an out-of-repo client half:
+ * the browser proxy in \`@deepseek-ai/dsh-api-remotes\` is generated per known
+ * namespace, so a third-party namespace never appears on \`ctx.remote\`. The
+ * supported channel for a plugin is therefore a plain HTTP route registered on
+ * the optional \`webServer\` service (the same seam \`@linxin666/dsh-doctor\` uses).
+ *
+ * @module dsh-llm-ctl/routes
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { CtlEvent } from './events.ts';
+import type { GateSnapshot } from './queue.ts';
+import type { VisibilitySettings } from './visibility.ts';
+/** Route shape accepted by \`ctx.webServer.register\`. */
+export interface WebRoute {
+    kind: 'exact' | 'prefix';
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
+/** Minimal slice of the host web server the plugin needs. */
+export interface WebServerLike {
+    register(route: WebRoute): () => void;
+}
+/** Effective global queue budget surfaced to the settings UI. */
+export interface QueueConfigState {
+    /** Effective maxWaitMs in ms (settings override wins over the cordis base). */
+    maxWaitMs: number;
+    /** Effective maxQueueDepth (settings override wins over the cordis base). */
+    maxQueueDepth: number;
+    /** Effective default per-provider concurrency; `0` means unlimited. */
+    defaultConcurrency: number;
+    /** Effective provider-specific concurrency entries, excluding `default`; `0` means unlimited. */
+    perProviderConcurrency: Record<string, number>;
+    /** Cordis composition base, before the user-layer override. */
+    defaults: {
+        maxWaitMs: number;
+        maxQueueDepth: number;
+        defaultConcurrency: number;
+    };
+    /** True when at least one field carries a user-layer override. */
+    overridden: boolean;
+    /** Current settings section revision, for write fencing. */
+    revision: number;
+}
+/** Visibility slice of the state payload. */
+export interface VisibilityState {
+    settings: VisibilitySettings;
+    /** Composition preset patterns, read-only. */
+    patterns: readonly string[];
+    /** Declared provider directory, including providers absent from the catalog. */
+    configurableProviders: ConfigurableProviderView[];
+}
+/** State payload the browser polls. */
+export interface ControlState {
+    at: number;
+    queue: GateSnapshot;
+    events: CtlEvent[];
+    reactive: {
+        mode: 'auto' | 'off' | number;
+        limit: number;
+    };
+    queueConfig: QueueConfigState;
+    visibility: VisibilityState;
+}
+/** Result of one visibility write. */
+export interface VisibilityWriteOutcome {
+    ok: boolean;
+    code?: string;
+    message?: string;
+    revision?: number;
+}
+/** Configurable provider directory entry surfaced to the browser. */
+export interface ConfigurableProviderView {
+    provider: string;
+    displayName: string;
+    settingsNs: string;
+}
+/** Callbacks the routes delegate to. */
+export interface RouteDeps {
+    state: () => ControlState;
+    cancel: (queueId: string) => boolean;
+    setQueue: (input: {
+        maxWaitMs?: number | undefined;
+        maxQueueDepth?: number | undefined;
+        defaultConcurrency?: number | undefined;
+        perProviderConcurrency?: Record<string, number> | undefined;
+        expectedRevision?: number;
+    }) => Promise<VisibilityWriteOutcome>;
+    resetQueue: (input: {
+        expectedRevision?: number;
+    }) => Promise<VisibilityWriteOutcome>;
+    setVisibility: (input: {
+        provider: string;
+        model?: string;
+        visible: boolean;
+    }) => Promise<VisibilityWriteOutcome>;
+    resetVisibility: () => Promise<VisibilityWriteOutcome>;
+    discover: (input: {
+        provider: string;
+        baseURL?: string;
+        api?: string;
+    }) => Promise<unknown>;
+}
+/** Path of the polled state document. */
+export declare const STATE_PATH = "/api/llm-ctl/state";
+/** Path of the cancel action. */
+export declare const CANCEL_PATH = "/api/llm-ctl/cancel";
+/** Path of the visibility write action. */
+export declare const VISIBILITY_PATH = "/api/llm-ctl/visibility";
+/** Path of the visibility reset action. */
+export declare const VISIBILITY_RESET_PATH = "/api/llm-ctl/visibility/reset";
+/** Path of the upstream model discovery action. */
+export declare const DISCOVER_PATH = "/api/llm-ctl/discover";
+/** Path of the global queue-budget write action. */
+export declare const QUEUE_PATH = "/api/llm-ctl/queue";
+/** Path of the global queue-budget reset action. */
+export declare const QUEUE_RESET_PATH = "/api/llm-ctl/queue/reset";
+/**
+ * Build the two routes the browser half uses.
+ *
+ * @param deps - state reader and cancel action.
+ * @returns route descriptors ready for \`webServer.register\`.
+ */
+export declare function createRoutes(deps: RouteDeps): WebRoute[];

package/lib/routes.js

@@ -0,0 +1,267 @@
+/** Path of the polled state document. */
+export const STATE_PATH = '/api/llm-ctl/state';
+/** Path of the cancel action. */
+export const CANCEL_PATH = '/api/llm-ctl/cancel';
+/** Path of the visibility write action. */
+export const VISIBILITY_PATH = '/api/llm-ctl/visibility';
+/** Path of the visibility reset action. */
+export const VISIBILITY_RESET_PATH = '/api/llm-ctl/visibility/reset';
+/** Path of the upstream model discovery action. */
+export const DISCOVER_PATH = '/api/llm-ctl/discover';
+/** Path of the global queue-budget write action. */
+export const QUEUE_PATH = '/api/llm-ctl/queue';
+/** Path of the global queue-budget reset action. */
+export const QUEUE_RESET_PATH = '/api/llm-ctl/queue/reset';
+/** Write one JSON response with no caching. */
+function writeJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+        'content-length': Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+/** Read a bounded JSON request body. */
+async function readJson(req, limitBytes = 4_096) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > limitBytes)
+            throw new Error('request body too large');
+        chunks.push(buffer);
+    }
+    if (total === 0)
+        return undefined;
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+/**
+ * Build the two routes the browser half uses.
+ *
+ * @param deps - state reader and cancel action.
+ * @returns route descriptors ready for \`webServer.register\`.
+ */
+export function createRoutes(deps) {
+    return [
+        {
+            kind: 'exact',
+            path: STATE_PATH,
+            handler: (_req, res) => {
+                try {
+                    writeJson(res, 200, deps.state());
+                }
+                catch (error) {
+                    writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: CANCEL_PATH,
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    writeJson(res, 405, { error: 'method not allowed' });
+                    return;
+                }
+                try {
+                    const body = await readJson(req);
+                    const queueId = body !== null && typeof body === 'object' ? body.queueId : undefined;
+                    if (typeof queueId !== 'string' || queueId.length === 0) {
+                        writeJson(res, 400, { error: 'queueId is required' });
+                        return;
+                    }
+                    writeJson(res, 200, { cancelled: deps.cancel(queueId) });
+                }
+                catch (error) {
+                    writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: VISIBILITY_PATH,
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    writeJson(res, 405, { error: 'method not allowed' });
+                    return;
+                }
+                try {
+                    const body = await readJson(req);
+                    const record = body !== null && typeof body === 'object' ? body : {};
+                    const provider = record['provider'];
+                    const model = record['model'];
+                    const visible = record['visible'];
+                    if (typeof provider !== 'string' || provider.length === 0 || typeof visible !== 'boolean') {
+                        writeJson(res, 400, { error: 'provider and visible are required' });
+                        return;
+                    }
+                    if (model !== undefined && typeof model !== 'string') {
+                        writeJson(res, 400, { error: 'model must be a string' });
+                        return;
+                    }
+                    const outcome = await deps.setVisibility({
+                        provider,
+                        ...(typeof model === 'string' && model.length > 0 ? { model } : {}),
+                        visible,
+                    });
+                    writeJson(res, outcome.ok ? 200 : 409, outcome);
+                }
+                catch (error) {
+                    writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: VISIBILITY_RESET_PATH,
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    writeJson(res, 405, { error: 'method not allowed' });
+                    return;
+                }
+                try {
+                    const outcome = await deps.resetVisibility();
+                    writeJson(res, outcome.ok ? 200 : 409, outcome);
+                }
+                catch (error) {
+                    writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: QUEUE_PATH,
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    writeJson(res, 405, { error: 'method not allowed' });
+                    return;
+                }
+                try {
+                    const body = await readJson(req);
+                    const record = body !== null && typeof body === 'object' ? body : {};
+                    const input = {};
+                    if (record['maxWaitMs'] !== undefined) {
+                        if (typeof record['maxWaitMs'] !== 'number' || !Number.isFinite(record['maxWaitMs']) || record['maxWaitMs'] < 0) {
+                            writeJson(res, 400, { error: 'maxWaitMs must be a number >= 0' });
+                            return;
+                        }
+                        input.maxWaitMs = record['maxWaitMs'];
+                    }
+                    if (record['maxQueueDepth'] !== undefined) {
+                        if (typeof record['maxQueueDepth'] !== 'number' || !Number.isFinite(record['maxQueueDepth']) || record['maxQueueDepth'] < 1) {
+                            writeJson(res, 400, { error: 'maxQueueDepth must be a number >= 1' });
+                            return;
+                        }
+                        input.maxQueueDepth = Math.floor(record['maxQueueDepth']);
+                    }
+                    if (record['defaultConcurrency'] !== undefined) {
+                        if (typeof record['defaultConcurrency'] !== 'number' || !Number.isFinite(record['defaultConcurrency']) || record['defaultConcurrency'] < 0) {
+                            writeJson(res, 400, { error: 'defaultConcurrency must be a number >= 0 (0 means unlimited)' });
+                            return;
+                        }
+                        input.defaultConcurrency = Math.floor(record['defaultConcurrency']);
+                    }
+                    if (record['perProviderConcurrency'] !== undefined) {
+                        const table = record['perProviderConcurrency'];
+                        if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+                            writeJson(res, 400, { error: 'perProviderConcurrency must be an object' });
+                            return;
+                        }
+                        const entries = {};
+                        for (const [key, value] of Object.entries(table)) {
+                            if (key.length === 0 || typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+                                writeJson(res, 400, { error: `perProviderConcurrency[${JSON.stringify(key)}] must be a number >= 0 (0 means unlimited)` });
+                                return;
+                            }
+                            entries[key] = Math.floor(value);
+                        }
+                        input.perProviderConcurrency = entries;
+                    }
+                    if (record['expectedRevision'] !== undefined) {
+                        if (typeof record['expectedRevision'] !== 'number' || !Number.isFinite(record['expectedRevision']) || record['expectedRevision'] < 0) {
+                            writeJson(res, 400, { error: 'expectedRevision must be a number >= 0' });
+                            return;
+                        }
+                        input.expectedRevision = Math.floor(record['expectedRevision']);
+                    }
+                    if (input.maxWaitMs === undefined && input.maxQueueDepth === undefined && input.defaultConcurrency === undefined && input.perProviderConcurrency === undefined) {
+                        writeJson(res, 400, { error: 'maxWaitMs, maxQueueDepth, defaultConcurrency, or perProviderConcurrency is required' });
+                        return;
+                    }
+                    const outcome = await deps.setQueue(input);
+                    writeJson(res, outcome.ok ? 200 : 409, outcome);
+                }
+                catch (error) {
+                    writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: QUEUE_RESET_PATH,
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    writeJson(res, 405, { error: 'method not allowed' });
+                    return;
+                }
+                try {
+                    const body = await readJson(req);
+                    const record = body !== null && typeof body === 'object' ? body : {};
+                    const input = {};
+                    if (record['expectedRevision'] !== undefined) {
+                        if (typeof record['expectedRevision'] !== 'number' || !Number.isFinite(record['expectedRevision']) || record['expectedRevision'] < 0) {
+                            writeJson(res, 400, { error: 'expectedRevision must be a number >= 0' });
+                            return;
+                        }
+                        input.expectedRevision = Math.floor(record['expectedRevision']);
+                    }
+                    const outcome = await deps.resetQueue(input);
+                    writeJson(res, outcome.ok ? 200 : 409, outcome);
+                }
+                catch (error) {
+                    writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+        {
+            kind: 'exact',
+            path: DISCOVER_PATH,
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    writeJson(res, 405, { error: 'method not allowed' });
+                    return;
+                }
+                try {
+                    const body = await readJson(req);
+                    const record = body !== null && typeof body === 'object' ? body : {};
+                    const provider = record['provider'];
+                    if (typeof provider !== 'string' || provider.length === 0) {
+                        writeJson(res, 400, { error: 'provider is required' });
+                        return;
+                    }
+                    const optional = (key) => {
+                        const value = record[key];
+                        if (value === undefined)
+                            return undefined;
+                        if (typeof value !== 'string')
+                            throw new Error(key + ' must be a string');
+                        return value;
+                    };
+                    // Secrets never cross this channel: discovery reuses the stored
+                    // credential server-side. An `apiKey` field in the body is rejected
+                    // so a stray or malicious caller cannot smuggle one through logs.
+                    if (record['apiKey'] !== undefined) {
+                        writeJson(res, 400, { error: 'apiKey must not be sent; discovery uses the stored credential' });
+                        return;
+                    }
+                    writeJson(res, 200, await deps.discover({ provider, baseURL: optional('baseURL'), api: optional('api') }));
+                }
+                catch (error) {
+                    writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+                }
+            },
+        },
+    ];
+}