@leaves615/dsh-llm-ctl 0.1.0

package/lib/discover-ui.d.ts

@@ -0,0 +1,94 @@
+/**
+ * React views for the upstream-discovered model list slot.
+ *
+ * The client bundle runs inside the DSH ModuleLoader, so React arrives through
+ * `require('react')`; the build script rewrites these imports. Everything here
+ * is a pure view over discovered rows plus callbacks, so the data shaping is
+ * testable without a browser.
+ *
+ * @module dsh-llm-ctl/discover-ui
+ */
+import React from 'react';
+import type { VisibilitySettings } from './visibility.ts';
+/** One upstream-discovered model row of the provider card slot. */
+export interface DiscoveredRow {
+    /** Upstream model id. */
+    id: string;
+    /** Display name; falls back to {@link DiscoveredRow.id} when upstream gives none. */
+    name: string;
+    /** True when the id is absent from the advertised catalog. */
+    isNew: boolean;
+    /** Resolved through the visibility switches and preset patterns. */
+    visible: boolean;
+}
+/** Inputs for building the discovered-model rows. */
+export interface DiscoveredRowsInput {
+    /** Provider id the discovery result belongs to. */
+    provider: string;
+    /** Raw upstream entries, in upstream order. */
+    discovered: ReadonlyArray<{
+        id: string;
+        name?: string;
+    }>;
+    /** Model ids already present in the advertised catalog. */
+    advertisedIds: ReadonlyArray<string>;
+    /** Two-level visibility switches. */
+    settings: VisibilitySettings;
+    /** Preset wildcard patterns hiding models by default. */
+    patterns: readonly string[];
+}
+/** Actions the discover views call back into. */
+export interface DiscoverActions {
+    /**
+     * Write one model switch.
+     *
+     * @param provider - Provider id.
+     * @param model - Model id.
+     * @param visible - Whether the model is visible.
+     * @returns Nothing.
+     */
+    toggleModel(provider: string, model: string, visible: boolean): void;
+    /**
+     * Re-run upstream discovery.
+     *
+     * @returns Nothing.
+     */
+    refresh(): void;
+}
+/**
+ * Build discovered-model rows in upstream order, dropping blank ids.
+ *
+ * @param input - Provider id, discovered entries, advertised ids, settings, and patterns.
+ * @returns Discovered rows with newness and visibility resolved.
+ */
+export declare function buildDiscoveredRows(input: DiscoveredRowsInput): DiscoveredRow[];
+/**
+ * Small refresh button for the discovered-model list.
+ *
+ * @param props - Pending flag, optional disabled flag, and refresh callback.
+ * @returns The rendered button element.
+ */
+export declare function RefreshModelsButton(props: {
+    pending: boolean;
+    disabled?: boolean;
+    onRefresh: () => void;
+}): React.ReactElement;
+/**
+ * Upstream-discovered model list for one provider card slot.
+ *
+ * Returns null when there are no rows and the list is neither loading nor
+ * failed, so the slot stays empty for providers without discovery data.
+ *
+ * @param props - Provider id, rows, pending/failed state, and callbacks.
+ * @returns The rendered section, or null when there is nothing to show.
+ */
+export declare function DiscoveredModelsList(props: {
+    provider: string;
+    rows: DiscoveredRow[];
+    pending: boolean;
+    failed?: string;
+    onToggle: (provider: string, model: string, visible: boolean) => void;
+    onRefresh: () => void;
+}): React.ReactElement | null;
+/** Re-exported so the provider-card slot can type its settings prop from this module. */
+export type { VisibilitySettings } from './visibility.ts';

package/lib/discover-ui.js

@@ -0,0 +1,91 @@
+/**
+ * React views for the upstream-discovered model list slot.
+ *
+ * The client bundle runs inside the DSH ModuleLoader, so React arrives through
+ * `require('react')`; the build script rewrites these imports. Everything here
+ * is a pure view over discovered rows plus callbacks, so the data shaping is
+ * testable without a browser.
+ *
+ * @module dsh-llm-ctl/discover-ui
+ */
+import React from 'react';
+import { CollapseToggle, useAutoCollapse } from "./settings-ui.js";
+import { isModelVisible } from "./visibility.js";
+/**
+ * Build discovered-model rows in upstream order, dropping blank ids.
+ *
+ * @param input - Provider id, discovered entries, advertised ids, settings, and patterns.
+ * @returns Discovered rows with newness and visibility resolved.
+ */
+export function buildDiscoveredRows(input) {
+    const config = { hiddenPatterns: input.patterns };
+    const rows = [];
+    for (const entry of input.discovered) {
+        if (entry.id === '')
+            continue;
+        rows.push({
+            id: entry.id,
+            name: entry.name ?? entry.id,
+            isNew: !input.advertisedIds.includes(entry.id),
+            visible: isModelVisible(input.provider, entry.id, input.settings, config),
+        });
+    }
+    return rows;
+}
+const rowStyle = { display: 'flex', alignItems: 'center', gap: 8, padding: '2px 0' };
+const nameStyle = { flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' };
+const buttonStyle = {
+    border: '1px solid var(--dsw-alias-border-inverted, rgba(127,127,127,.35))',
+    background: 'transparent',
+    color: 'inherit',
+    borderRadius: 6,
+    padding: '1px 8px',
+    fontSize: 11,
+    cursor: 'pointer',
+};
+const badgeStyle = {
+    border: '1px solid var(--dsw-alias-border-inverted, rgba(127,127,127,.35))',
+    borderRadius: 4,
+    padding: '0 4px',
+    fontSize: 10,
+};
+const errorStyle = { color: '#f31260', padding: '2px 0' };
+/**
+ * Small refresh button for the discovered-model list.
+ *
+ * @param props - Pending flag, optional disabled flag, and refresh callback.
+ * @returns The rendered button element.
+ */
+export function RefreshModelsButton(props) {
+    const disabled = props.pending || props.disabled === true;
+    return React.createElement('button', {
+        type: 'button',
+        style: buttonStyle,
+        disabled: disabled,
+        onClick: () => props.onRefresh(),
+    }, props.pending ? '刷新中…' : '刷新清单');
+}
+/**
+ * Upstream-discovered model list for one provider card slot.
+ *
+ * Returns null when there are no rows and the list is neither loading nor
+ * failed, so the slot stays empty for providers without discovery data.
+ *
+ * @param props - Provider id, rows, pending/failed state, and callbacks.
+ * @returns The rendered section, or null when there is nothing to show.
+ */
+export function DiscoveredModelsList(props) {
+    const [collapsed, toggleCollapsed] = useAutoCollapse(props.rows.length);
+    if (props.rows.length === 0 && !props.pending && !props.failed)
+        return null;
+    const failed = props.failed ?? '';
+    return React.createElement('section', { style: { marginTop: 8, fontSize: 12 } }, React.createElement('div', { style: rowStyle }, CollapseToggle({ collapsed, count: props.rows.length, label: '上游发现', onToggle: toggleCollapsed }), React.createElement(RefreshModelsButton, { pending: props.pending, onRefresh: props.onRefresh })), failed.length > 0 ? React.createElement('div', { style: errorStyle }, failed) : null, collapsed
+        ? null
+        : props.rows.map((row) => React.createElement('div', { key: row.id, style: { ...rowStyle, opacity: row.visible ? 1 : 0.5 } }, React.createElement('span', { style: nameStyle }, row.name), row.isNew ? React.createElement('span', { style: badgeStyle }, '新') : null, React.createElement('button', {
+            type: 'button',
+            style: buttonStyle,
+            title: row.visible ? '隐藏' : '显示',
+            'aria-pressed': !row.visible,
+            onClick: () => props.onToggle(props.provider, row.id, !row.visible),
+        }, row.visible ? '👁' : '🚫'))));
+}

package/lib/discover.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Upstream model discovery for third-party providers.
+ *
+ * Two paths, cheapest first: the provider's own discovery registration on
+ * `ctx.llm` (which reuses the stored credential server-side, so this module
+ * never handles secrets), then the public OpenCode Zen feed for zen-family
+ * routes, which needs no credential at all.
+ *
+ * @module dsh-llm-ctl/discover
+ */
+/** Public Zen model feed, readable without any credential. */
+export declare const ZEN_MODELS_URL = "https://opencode.ai/zen/v1/models";
+/** True for zen-family provider routes served by the public feed. */
+export declare function isZenProvider(provider: string): boolean;
+/** One discovered model. */
+export interface DiscoveredModel {
+    id: string;
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+}
+/** Minimal slice of `ctx.llm` this module needs. */
+export interface LlmDiscoveryLike {
+    listConfigurableProviders(): Array<{
+        provider: string;
+        displayName: string;
+        settingsNs: string;
+    }>;
+    discoverModels(settingsNs: string, request: {
+        provider?: string;
+        baseURL?: string;
+        api?: string;
+        apiKey?: string;
+    }, signal?: AbortSignal): Promise<DiscoveredModel[]>;
+}
+/** Dependencies, all injectable for tests. */
+export interface DiscoverDeps {
+    llm?: LlmDiscoveryLike;
+    fetchJson?: (url: string, headers?: Record<string, string>, signal?: AbortSignal) => Promise<unknown>;
+    logger?: {
+        info(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+    };
+    timeoutMs?: number;
+}
+/** Inputs for one discovery run. */
+export interface DiscoverInput {
+    provider: string;
+    settingsNs?: string;
+    baseURL?: string;
+    api?: string;
+    apiKey?: string;
+    advertised?: readonly string[];
+}
+/** Where the discovered list came from. */
+export type DiscoverSource = 'adapter' | 'zen-feed' | 'none';
+/** One discovery result; business failures ride in `error`, never throw. */
+export interface DiscoverResult {
+    provider: string;
+    settingsNs?: string;
+    discovered: DiscoveredModel[];
+    advertised: string[];
+    fresh: string[];
+    source: DiscoverSource;
+    error?: string;
+}
+/**
+ * Discover the upstream model list for one provider.
+ *
+ * Tries the adapter registration first (server-side, reuses the stored
+ * credential), then the public Zen feed for zen-family routes. Business
+ * failures are reported in `error`; only aborts and programming errors throw.
+ *
+ * @param deps Host capabilities, all optional except the logger default.
+ * @param input Provider identity plus optional discovery hints.
+ * @param signal Caller cancellation; a 30s timeout applies when omitted.
+ * @returns The discovered list with fresh ids relative to `advertised`.
+ */
+export declare function discoverProviderModels(deps: DiscoverDeps, input: DiscoverInput, signal?: AbortSignal): Promise<DiscoverResult>;

package/lib/discover.js

@@ -0,0 +1,141 @@
+/**
+ * Upstream model discovery for third-party providers.
+ *
+ * Two paths, cheapest first: the provider's own discovery registration on
+ * `ctx.llm` (which reuses the stored credential server-side, so this module
+ * never handles secrets), then the public OpenCode Zen feed for zen-family
+ * routes, which needs no credential at all.
+ *
+ * @module dsh-llm-ctl/discover
+ */
+/** Public Zen model feed, readable without any credential. */
+export const ZEN_MODELS_URL = 'https://opencode.ai/zen/v1/models';
+/** True for zen-family provider routes served by the public feed. */
+export function isZenProvider(provider) {
+    const normalized = provider.toLowerCase();
+    return normalized.includes('zen') || normalized.includes('opencode');
+}
+/** Default fetch: bounded JSON GET with a plain user agent. */
+async function defaultFetchJson(url, headers, signal) {
+    const response = await fetch(url, { headers, signal });
+    if (!response.ok)
+        throw new Error(url + ': HTTP ' + response.status);
+    return (await response.json());
+}
+/** Resolve the discovery namespace, preferring the explicit value. */
+function resolveSettingsNs(llm, provider, explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    if (llm === undefined)
+        return undefined;
+    const entries = llm.listConfigurableProviders();
+    return entries.find((entry) => entry.provider === provider)?.settingsNs ?? entries.find((entry) => entry.provider.toLowerCase() === provider.toLowerCase())?.settingsNs;
+}
+/** Normalize one raw model record; undefined when it carries no usable id. */
+function normalizeModel(record) {
+    if (record === null || typeof record !== 'object')
+        return undefined;
+    const entry = record;
+    const id = entry['id'];
+    const name = entry['name'];
+    const contextWindow = entry['contextWindow'];
+    const maxTokens = entry['maxTokens'];
+    if (typeof id !== 'string' || id.length === 0)
+        return undefined;
+    const model = { id };
+    if (typeof name === 'string' && name.length > 0)
+        model.name = name;
+    if (typeof contextWindow === 'number' && Number.isFinite(contextWindow))
+        model.contextWindow = contextWindow;
+    if (typeof maxTokens === 'number' && Number.isFinite(maxTokens))
+        model.maxTokens = maxTokens;
+    return model;
+}
+/** Read the public Zen feed into model records. */
+async function readZenFeed(fetchJson, signal) {
+    const payload = await fetchJson(ZEN_MODELS_URL, { 'User-Agent': '@leaves615/dsh-llm-ctl', accept: 'application/json' }, signal);
+    if (payload === null || typeof payload !== 'object')
+        throw new Error('zen feed: unexpected response shape');
+    const data = payload['data'];
+    if (!Array.isArray(data))
+        throw new Error('zen feed: unexpected response shape');
+    const seen = new Set();
+    const out = [];
+    for (const record of data) {
+        const model = normalizeModel(record);
+        if (model === undefined || seen.has(model.id))
+            continue;
+        seen.add(model.id);
+        out.push(model);
+    }
+    return out;
+}
+/**
+ * Discover the upstream model list for one provider.
+ *
+ * Tries the adapter registration first (server-side, reuses the stored
+ * credential), then the public Zen feed for zen-family routes. Business
+ * failures are reported in `error`; only aborts and programming errors throw.
+ *
+ * @param deps Host capabilities, all optional except the logger default.
+ * @param input Provider identity plus optional discovery hints.
+ * @param signal Caller cancellation; a 30s timeout applies when omitted.
+ * @returns The discovered list with fresh ids relative to `advertised`.
+ */
+export async function discoverProviderModels(deps, input, signal) {
+    const advertised = [...(input.advertised ?? [])];
+    const base = {
+        provider: input.provider,
+        advertised,
+    };
+    const settingsNs = resolveSettingsNs(deps.llm, input.provider, input.settingsNs);
+    if (settingsNs !== undefined)
+        base.settingsNs = settingsNs;
+    const timeoutMs = deps.timeoutMs ?? 30_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('discover timeout')), timeoutMs);
+    const fused = signal === undefined ? controller.signal : AbortSignal.any([signal, controller.signal]);
+    try {
+        if (settingsNs !== undefined && deps.llm !== undefined) {
+            try {
+                const raw = await deps.llm.discoverModels(settingsNs, { provider: input.provider, baseURL: input.baseURL, api: input.api, apiKey: input.apiKey }, fused);
+                const seen = new Set();
+                const discovered = [];
+                for (const record of raw) {
+                    const model = normalizeModel(record);
+                    if (model === undefined || seen.has(model.id))
+                        continue;
+                    seen.add(model.id);
+                    discovered.push(model);
+                }
+                deps.logger?.info('llm-ctl: discovered %d model(s) for provider %s via adapter', discovered.length, input.provider);
+                return { ...base, discovered, advertised, fresh: discovered.map((model) => model.id).filter((id) => !advertised.includes(id)), source: 'adapter' };
+            }
+            catch (error) {
+                if (fused.aborted)
+                    throw error;
+                deps.logger?.warn('llm-ctl: adapter discovery failed for provider %s: %o', input.provider, error);
+            }
+        }
+        if (isZenProvider(input.provider)) {
+            try {
+                const fetchJson = deps.fetchJson ?? defaultFetchJson;
+                const discovered = await readZenFeed(fetchJson, fused);
+                deps.logger?.info('llm-ctl: discovered %d model(s) for provider %s via zen feed', discovered.length, input.provider);
+                return { ...base, discovered, advertised, fresh: discovered.map((model) => model.id).filter((id) => !advertised.includes(id)), source: 'zen-feed' };
+            }
+            catch (error) {
+                if (fused.aborted)
+                    throw error;
+                const message = error instanceof Error ? error.message : String(error);
+                deps.logger?.warn('llm-ctl: zen feed failed for provider %s: %o', input.provider, error);
+                return { ...base, discovered: [], advertised, fresh: [], source: 'zen-feed', error: message };
+            }
+        }
+        const reason = settingsNs === undefined ? 'no discovery namespace for provider' : 'no llm service or adapter discovery failed';
+        return { ...base, discovered: [], advertised, fresh: [], source: 'none', error: reason };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/lib/events.d.ts

@@ -0,0 +1,45 @@
+/**
+ * In-memory observability for queue and recovery decisions.
+ *
+ * Deliberately not written to the session log: `Session.append()` exposes no way
+ * to mark an out-of-repo event type `ignorable`, and an unmarked unknown type
+ * makes the persistence read path refuse to reconstruct the session. Queue
+ * state is process-local anyway — a crash loses the in-flight request too.
+ *
+ * @module dsh-llm-ctl/events
+ */
+/** Where a queued request came from. */
+export type Origin = 'loop' | 'background';
+/** One observable control-plane fact. */
+export type CtlEventKind = 'queued' | 'granted' | 'released' | 'cooldown' | 'queue-timeout' | 'queue-full' | 'cancelled' | 'retry-scheduled' | 'retry-skipped' | 'retry-delegated' | 'visibility-changed' | 'queue-config-changed' | 'default-model-fallback' | 'default-model-hidden';
+/** One recorded fact with its assigned sequence and timestamp. */
+export interface CtlEvent {
+    seq: number;
+    at: number;
+    kind: CtlEventKind;
+    provider: string;
+    queueId?: string;
+    origin?: Origin;
+    position?: number;
+    waitMs?: number;
+    delayMs?: number;
+    code?: string;
+    reason?: string;
+    attempt?: number;
+    source?: string;
+}
+/** Bounded ring of recent facts, newest last. */
+export declare class CtlEventLog {
+    private readonly capacity;
+    private readonly entries;
+    private seq;
+    constructor(capacity?: number);
+    /** Append one fact, dropping the oldest when the ring is full. */
+    push(fact: Omit<CtlEvent, 'seq' | 'at'> & {
+        at?: number;
+    }): CtlEvent;
+    /** Recent facts, newest last. */
+    list(limit?: number): CtlEvent[];
+    /** Drop every recorded fact. */
+    clear(): void;
+}

package/lib/events.js

@@ -0,0 +1,37 @@
+/**
+ * In-memory observability for queue and recovery decisions.
+ *
+ * Deliberately not written to the session log: `Session.append()` exposes no way
+ * to mark an out-of-repo event type `ignorable`, and an unmarked unknown type
+ * makes the persistence read path refuse to reconstruct the session. Queue
+ * state is process-local anyway — a crash loses the in-flight request too.
+ *
+ * @module dsh-llm-ctl/events
+ */
+/** Bounded ring of recent facts, newest last. */
+export class CtlEventLog {
+    capacity;
+    entries = [];
+    seq = 0;
+    constructor(capacity = 200) {
+        this.capacity = Math.max(1, capacity);
+    }
+    /** Append one fact, dropping the oldest when the ring is full. */
+    push(fact) {
+        const event = { seq: (this.seq += 1), at: fact.at ?? Date.now(), ...fact };
+        this.entries.push(event);
+        if (this.entries.length > this.capacity)
+            this.entries.splice(0, this.entries.length - this.capacity);
+        return event;
+    }
+    /** Recent facts, newest last. */
+    list(limit) {
+        if (limit === undefined || limit >= this.entries.length)
+            return [...this.entries];
+        return this.entries.slice(this.entries.length - Math.max(0, limit));
+    }
+    /** Drop every recorded fact. */
+    clear() {
+        this.entries.length = 0;
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * dsh-llm-ctl — rate-limit admission control and standalone request recovery.
+ *
+ * Two seams, both official:
+ *
+ * - `llm/stream` (global, prepended): every model call — agent loop and
+ *   background tasks alike — waits for a per-provider slot before `next()`
+ *   dispatches, so no provider I/O happens while queued and the chunk protocol
+ *   is untouched.
+ * - `agent/request-error` (global, prepended): the provider cooldown is
+ *   registered, then the downstream waterfall decides. When no retry executor
+ *   is mounted the plugin spends its own bounded budget so a first 429 does not
+ *   end the turn.
+ *
+ * @module dsh-llm-ctl
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, type ConfigInput } from './config.ts';
+import { type Scheduler } from './queue.ts';
+/** Cordis plugin name. */
+export declare const name = "llm-ctl";
+/** No service is required; both seams are event listeners. */
+export declare const inject: string[];
+export { Config };
+/** Non-serializable hooks that make timing deterministic in tests. */
+export interface LlmCtlInternals {
+    random?: () => number;
+    scheduler?: Scheduler;
+    now?: () => number;
+}
+/**
+ * Install admission control and standalone recovery.
+ *
+ * @param ctx - plugin context owning both listeners and every pending wait.
+ * @param config - queue and recovery configuration.
+ * @param internals - deterministic hooks for tests.
+ */
+export declare function apply(ctx: Context, config?: ConfigInput, internals?: LlmCtlInternals): void;