@leaves615/dsh-llm-ctl 0.1.0

package/lib/index.js

@@ -0,0 +1,378 @@
+import { Config, UNLIMITED_CONCURRENCY, concurrencyFor, resolveConfig } from "./config.js";
+import { CtlEventLog } from "./events.js";
+import { resolveDelay } from "./delay.js";
+import { ProviderGate } from "./queue.js";
+import { RetryBudget, WAITABLE_CODES, cancellableDelay, decideReactive } from "./reactive.js";
+import { LlmCtlController } from "./controller.js";
+import { createRoutes } from "./routes.js";
+import { VISIBILITY_SETTINGS_NS, installVisibilitySettings, } from "./visibility-settings.js";
+import { discoverProviderModels } from "./discover.js";
+import { isModelVisible, pickFallback } from "./visibility.js";
+/** Cordis plugin name. */
+export const name = 'llm-ctl';
+/** No service is required; both seams are event listeners. */
+export const inject = [];
+export { Config };
+/** Terminal error chunk used to refuse admission without dispatching. */
+function refusalChunk(code, message) {
+    return { type: 'finish', reason: { kind: 'error', failure: { code, message } } };
+}
+/**
+ * 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 function apply(ctx, config = {}, internals = {}) {
+    const resolved = resolveConfig(config);
+    const random = internals.random ?? Math.random;
+    const now = internals.now;
+    const events = new CtlEventLog(200);
+    const budget = new RetryBudget();
+    const lifetime = new AbortController();
+    const active = new Set();
+    const gate = new ProviderGate({
+        ...(internals.scheduler === undefined ? {} : { scheduler: internals.scheduler }),
+        concurrencyFor: (provider) => concurrencyFor(resolved.queue.perProviderConcurrency, provider),
+        maxQueueDepth: resolved.queue.maxQueueDepth,
+        maxWaitMs: resolved.queue.maxWaitMs,
+        onEvent: (kind, detail) => {
+            events.push({ kind, ...detail });
+        },
+    });
+    /** Cordis composition base for the global queue budget; the settings user layer may override it. */
+    const baseMaxWaitMs = resolved.queue.maxWaitMs;
+    const baseMaxQueueDepth = resolved.queue.maxQueueDepth;
+    const basePerProviderConcurrency = { ...resolved.queue.perProviderConcurrency };
+    const baseDefaultConcurrency = basePerProviderConcurrency['default'] ?? UNLIMITED_CONCURRENCY;
+    /** Track one in-flight recovery so disposal can drain it. */
+    function track(operation) {
+        const tracked = operation.finally(() => active.delete(tracked));
+        active.add(tracked);
+        return tracked;
+    }
+    function resolveFailureDelay(provider, failure, attempt) {
+        return resolveDelay({
+            providerRetryAfterMs: failure.providerRetryAfterMs,
+            attempt,
+            backoff: resolved.queue.backoff,
+            maxWaitMs: resolved.queue.maxWaitMs,
+            honorRetryAfter: resolved.queue.honorRetryAfter,
+            random,
+            ...(now === undefined ? {} : { now }),
+        });
+    }
+    /** Register the cooldown a terminal failure implies. */
+    function observeTerminal(provider, origin, chunk) {
+        if (chunk.type !== 'finish')
+            return;
+        const reason = chunk.reason;
+        if (reason.kind !== 'error' && reason.kind !== 'aborted')
+            return;
+        const failure = reason.failure;
+        if (!WAITABLE_CODES.includes(failure.code))
+            return;
+        const delay = resolveFailureDelay(provider, failure, 1);
+        ctx.logger.debug('llm-ctl: provider %s reported %s (%s), cooldown %dms', provider, failure.code, delay.source, delay.delayMs);
+        gate.registerCooldown(provider, delay.delayMs, 'terminal-failure', delay.source);
+    }
+    const disposeStream = ctx.on('llm/stream', (options, next) => {
+        const provider = options.provider;
+        const origin = options.purpose === undefined ? 'loop' : 'background';
+        const signal = options.signal;
+        return (async function* admission() {
+            const outcome = await gate.acquire(provider, { origin, signal });
+            if (!outcome.ok) {
+                ctx.logger.warn('llm-ctl: refusing %s request for provider %s (%s)', origin, provider, outcome.reason);
+                yield refusalChunk(outcome.code, `dsh-llm-ctl: ${outcome.code} for provider "${provider}" (${outcome.reason})`);
+                return;
+            }
+            try {
+                for await (const chunk of next()) {
+                    observeTerminal(provider, origin, chunk);
+                    yield chunk;
+                }
+            }
+            finally {
+                outcome.release();
+            }
+        })();
+    }, { global: true, prepend: true });
+    /** Standalone recovery: cooldown first, downstream second, own budget last. */
+    async function recover(payload, next) {
+        const { agent, provider, failure, turn, step, signal } = payload;
+        const key = `${agent.session.id}:${provider}:${turn}:${step}`;
+        const attempts = budget.attempts(key);
+        const delay = resolveFailureDelay(provider, failure, attempts + 1);
+        gate.registerCooldown(provider, delay.delayMs, 'request-error', delay.source);
+        let delegated = false;
+        let downstreamError;
+        try {
+            const action = await next();
+            delegated = action?.kind === 'retry';
+        }
+        catch (error) {
+            downstreamError = error;
+        }
+        if (delegated) {
+            events.push({ kind: 'retry-delegated', provider, code: failure.code, reason: 'downstream', attempt: attempts });
+            return { kind: 'retry' };
+        }
+        const decision = decideReactive({
+            code: failure.code,
+            delegated: false,
+            attempts,
+            limit: resolved.reactiveRetryLimit,
+            delay,
+        });
+        if (!decision.retry) {
+            events.push({
+                kind: 'retry-skipped',
+                provider,
+                code: failure.code,
+                reason: decision.reason,
+                attempt: attempts,
+                delayMs: decision.delayMs,
+            });
+            if (downstreamError !== undefined)
+                throw downstreamError;
+            return undefined;
+        }
+        budget.record(key);
+        const fused = AbortSignal.any([signal, lifetime.signal]);
+        events.push({
+            kind: 'retry-scheduled',
+            provider,
+            code: failure.code,
+            reason: decision.reason,
+            attempt: attempts + 1,
+            delayMs: decision.delayMs,
+            source: delay.source,
+        });
+        const waited = await cancellableDelay(decision.delayMs, fused);
+        if (!waited || fused.aborted) {
+            events.push({ kind: 'retry-skipped', provider, code: failure.code, reason: 'cancelled', attempt: attempts + 1 });
+            return undefined;
+        }
+        return { kind: 'retry' };
+    }
+    const disposeError = ctx.on('agent/request-error', (payload, next) => {
+        if (lifetime.signal.aborted)
+            return Promise.resolve(undefined);
+        return track(recover(payload, next));
+    }, { global: true, prepend: true });
+    /** Best-effort handle on the llm service; undefined in compositions without one. */
+    function llmService() {
+        try {
+            return ctx.get('llm');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Late-bound queue-override reader.
+     *
+     * The settings attach may fire `onChange` synchronously inside
+     * `installVisibilitySettings`, i.e. before the handle binding below is
+     * assigned; reading the handle directly there would throw a TDZ error.
+     */
+    let readQueueOverride = () => ({});
+    let visibilityReady = false;
+    /** Reconcile the effective queue budget: settings override wins, cordis base is the fallback. */
+    function applyQueueOverrides() {
+        const override = readQueueOverride();
+        const nextTable = {
+            ...basePerProviderConcurrency,
+            ...(override.defaultConcurrency === undefined ? {} : { default: override.defaultConcurrency }),
+            ...override.perProviderConcurrency,
+        };
+        const next = {
+            maxWaitMs: override.maxWaitMs ?? baseMaxWaitMs,
+            maxQueueDepth: override.maxQueueDepth ?? baseMaxQueueDepth,
+        };
+        const tableBefore = JSON.stringify(resolved.queue.perProviderConcurrency);
+        const changed = next.maxWaitMs !== resolved.queue.maxWaitMs ||
+            next.maxQueueDepth !== resolved.queue.maxQueueDepth ||
+            JSON.stringify(nextTable) !== tableBefore;
+        resolved.queue.maxWaitMs = next.maxWaitMs;
+        resolved.queue.maxQueueDepth = next.maxQueueDepth;
+        // The gate's concurrency lookup closes over this table object, so replacing
+        // it takes effect for every admission decided after this call.
+        resolved.queue.perProviderConcurrency = nextTable;
+        gate.updateLimits(next);
+        if (changed)
+            events.push({ kind: 'queue-config-changed', provider: '*', reason: 'settings' });
+    }
+    const controlState = () => ({
+        at: Date.now(),
+        queue: gate.snapshot(),
+        events: events.list(100),
+        reactive: { mode: resolved.reactiveRetryMode, limit: resolved.reactiveRetryLimit },
+        queueConfig: (() => {
+            const override = visibility.queue();
+            const { default: _default, ...perProvider } = resolved.queue.perProviderConcurrency;
+            void _default;
+            return {
+                maxWaitMs: resolved.queue.maxWaitMs,
+                maxQueueDepth: resolved.queue.maxQueueDepth,
+                defaultConcurrency: resolved.queue.perProviderConcurrency['default'] ?? UNLIMITED_CONCURRENCY,
+                perProviderConcurrency: perProvider,
+                defaults: { maxWaitMs: baseMaxWaitMs, maxQueueDepth: baseMaxQueueDepth, defaultConcurrency: baseDefaultConcurrency },
+                overridden: override.maxWaitMs !== undefined ||
+                    override.maxQueueDepth !== undefined ||
+                    override.defaultConcurrency !== undefined ||
+                    override.perProviderConcurrency !== undefined,
+                revision: visibility.revision() ?? 0,
+            };
+        })(),
+        visibility: {
+            settings: visibility.read(),
+            patterns: resolved.hiddenPatterns,
+            configurableProviders: (() => {
+                try {
+                    return llmService()?.listConfigurableProviders() ?? [];
+                }
+                catch {
+                    return [];
+                }
+            })(),
+        },
+    });
+    // ── model visibility ───────────────────────────────────────────────────────
+    const visibility = installVisibilitySettings(ctx, {
+        namespace: VISIBILITY_SETTINGS_NS,
+        patterns: resolved.hiddenPatterns,
+        onChange: () => {
+            events.push({ kind: 'visibility-changed', provider: '*', reason: 'settings' });
+            // Attach may fire synchronously inside installVisibilitySettings, before
+            // the handle binding below is assigned; the explicit calls after install
+            // cover that first transition.
+            if (!visibilityReady)
+                return;
+            applyQueueOverrides();
+            void reconcileDefaultModel();
+        },
+    });
+    readQueueOverride = () => visibility.queue();
+    visibilityReady = true;
+    applyQueueOverrides();
+    void reconcileDefaultModel();
+    /** Enumerate the advisory catalog for fallback selection. */
+    async function collectCatalog() {
+        const llm = ctx.get('llm');
+        if (llm === undefined)
+            return [];
+        const out = [];
+        for (const provider of llm.listProviders()) {
+            try {
+                for (const model of await llm.listModels(provider.id)) {
+                    out.push({ provider: provider.id, model: model.id, name: model.name });
+                }
+            }
+            catch {
+                // Advisory catalog only; an unreachable provider simply contributes none.
+            }
+        }
+        return out;
+    }
+    /**
+     * Move the default selection off a hidden model so fresh sessions stay usable.
+     * The catalog default is exactly what new agents read, so this is the one place
+     * a visibility switch can strand them.
+     */
+    async function reconcileDefaultModel() {
+        const service = ctx.get('agentDefaultModel');
+        if (service === undefined)
+            return;
+        const current = service.currentSelection();
+        const settings = visibility.read();
+        const config = { hiddenPatterns: resolved.hiddenPatterns };
+        if (isModelVisible(current.provider, current.model, settings, config))
+            return;
+        const fallback = pickFallback(current, await collectCatalog(), settings, config);
+        if (fallback === undefined) {
+            events.push({
+                kind: 'default-model-hidden',
+                provider: current.provider,
+                code: 'MODEL_HIDDEN',
+                reason: 'no-visible-fallback',
+            });
+            return;
+        }
+        try {
+            await service.saveSelection({ provider: fallback.provider, model: fallback.model });
+            events.push({
+                kind: 'default-model-fallback',
+                provider: fallback.provider,
+                code: 'MODEL_HIDDEN',
+                reason: `${current.provider}:${current.model}`,
+            });
+        }
+        catch (error) {
+            ctx.logger.warn('llm-ctl: default model fallback failed: %o', error);
+        }
+    }
+    const controller = new LlmCtlController(ctx, {
+        snapshot: () => controlState(),
+        cancel: (queueId) => gate.cancel(queueId),
+    });
+    void controller;
+    // The browser half talks HTTP: a third-party Typert namespace is not reachable
+    // from the generated client proxy. The route seat exists only in web profiles,
+    // so the injection is optional and the plugin stays loadable headless.
+    ctx.inject(['webServer'], (webCtx) => {
+        const server = webCtx.webServer;
+        const adapt = (result) => ({
+            ok: result.ok,
+            ...(result.code === undefined ? {} : { code: result.code }),
+            ...(result.message === undefined ? {} : { message: result.message }),
+            ...(result.revision === undefined ? {} : { revision: result.revision }),
+        });
+        const disposers = createRoutes({
+            state: controlState,
+            cancel: (queueId) => gate.cancel(queueId),
+            setVisibility: async (input) => adapt(input.model === undefined ? await visibility.setProvider(input.provider, input.visible) : await visibility.setModel(input.provider, input.model, input.visible)),
+            resetVisibility: async () => adapt(await visibility.resetAll()),
+            setQueue: async (input) => adapt(await visibility.setQueue(input, input.expectedRevision)),
+            resetQueue: async (input) => adapt(await visibility.resetQueue(input.expectedRevision)),
+            discover: async (input) => {
+                const llm = llmService();
+                let advertised = [];
+                if (llm !== undefined) {
+                    try {
+                        advertised = (await llm.listModels(input.provider)).map((model) => model.id);
+                    }
+                    catch {
+                        advertised = [];
+                    }
+                }
+                return discoverProviderModels({
+                    llm,
+                    logger: {
+                        info: (first, ...rest) => {
+                            ctx.logger.info(first, ...rest);
+                        },
+                        warn: (first, ...rest) => {
+                            ctx.logger.warn(first, ...rest);
+                        },
+                    },
+                }, { provider: input.provider, baseURL: input.baseURL, api: input.api, advertised });
+            },
+        }).map((route) => server.register(route));
+        webCtx.effect(() => () => {
+            for (const dispose of disposers)
+                dispose();
+        }, 'llm-ctl: unregister control routes');
+    });
+    ctx.effect(() => async () => {
+        disposeStream();
+        disposeError();
+        lifetime.abort(new Error('dsh-llm-ctl disposed'));
+        visibility.dispose();
+        gate.dispose();
+        await Promise.allSettled([...active]);
+    }, 'llm-ctl: abort and drain queue and recovery');
+    ctx.logger.info('llm-ctl: queue maxWaitMs=%d maxQueueDepth=%d reactiveRetry=%s', resolved.queue.maxWaitMs, resolved.queue.maxQueueDepth, String(resolved.reactiveRetryMode));
+}

package/lib/menu-filter.d.ts

@@ -0,0 +1,134 @@
+/**
+ * DOM filtering for the model-selection popup (PRD FR3.2 / FR3.3).
+ *
+ * The module owns no state and no event listeners of its own: callers hand it
+ * the popup roots (or a container to search) and it reports what it hid. The
+ * selectors are deliberately fuzzy — the popup's hashed class prefixes change
+ * on every harness build, so only `[class*=...]` matching and the stable
+ * ARIA/role contract may be relied upon.
+ *
+ * @module dsh-llm-ctl/menu-filter
+ */
+/** The popup nodes this module operates on. */
+export interface ModelMenuRoots {
+    /** The `div[role="menu"]` element of the model-selection popup. */
+    menu: HTMLElement;
+    /** The container holding the `section[role="group"]` provider groups. */
+    groups: HTMLElement;
+}
+/** One selectable model row and the display names read from the DOM. */
+export interface ModelMenuRow {
+    /** The `[role="menuitemradio"]` button element. */
+    row: HTMLElement;
+    /** Provider name, i.e. the owning group's title text. */
+    providerName: string;
+    /** Model display name resolved from the row. */
+    modelName: string;
+}
+/** Filter inputs for {@link applyMenuFilter}. */
+export interface MenuFilterOptions {
+    /** Free-text query; empty or whitespace-only means "no query". */
+    query?: string;
+    /** Extra predicate; a row must also pass it to stay visible. */
+    isRowVisible?: (row: ModelMenuRow) => boolean;
+    /** When false, `query` is ignored and only `isRowVisible` applies. Defaults to true. */
+    hideUnmatched?: boolean;
+}
+/** Outcome of one {@link applyMenuFilter} pass. */
+export interface MenuFilterResult {
+    /** Rows left visible. */
+    shown: number;
+    /** Rows set to `display: none`. */
+    hidden: number;
+    /** Groups set to `display: none` because none of their rows stayed visible. */
+    groupsHidden: number;
+}
+/**
+ * Find the model-selection popup inside a container.
+ *
+ * Matches `div[role="menu"]` whose aria-label mentions the model menu in either
+ * locale ("模型与推理等级", "Model and reasoning effort", or any label containing
+ * `model`/`推理等级`/`effort`). When no labelled candidate exists, an unlabelled
+ * menu that already contains `[role="group"]` is accepted. The first match wins.
+ *
+ * @param root Document, fragment, or element to search within.
+ * @returns The popup roots, or undefined when no model menu is present.
+ */
+export declare function findModelMenu(root: ParentNode): ModelMenuRoots | undefined;
+/**
+ * List every model row of the popup in DOM order, including rows currently hidden.
+ *
+ * @param roots Popup roots from {@link findModelMenu}.
+ * @returns One entry per `[role="menuitemradio"]` inside a `section[role="group"]`.
+ */
+export declare function listModelRows(roots: ModelMenuRoots): ModelMenuRow[];
+/**
+ * Parsed search query: plain tokens match the model or provider name, while a
+ * `p:` or `provider:` prefix restricts that token to the provider name only.
+ * A bare prefix with no term (`p:`) is ignored so a half-typed token never
+ * hides the whole menu.
+ */
+export interface ParsedMenuQuery {
+    providerTerms: string[];
+    modelTerms: string[];
+}
+/**
+ * Split one query line into provider-scoped and plain terms.
+ *
+ * @param raw Raw query text as typed by the user.
+ * @returns Lowercased provider terms and model terms.
+ */
+export declare function parseMenuQuery(raw: string): ParsedMenuQuery;
+/**
+ * Apply the query and visibility predicate to every row and collapse empty groups.
+ *
+ * A row is shown only when it passes `isRowVisible` (when supplied) and matches
+ * `query` (when `hideUnmatched` is true). Query tokens match the model or provider
+ * name; a `p:` or `provider:` prefix restricts that token to the provider name.
+ * A group whose rows are all hidden is itself hidden; groups without rows are
+ * left untouched.
+ *
+ * @param roots Popup roots from {@link findModelMenu}.
+ * @param options Filter inputs; omit for "show everything".
+ * @returns Counts of shown rows, hidden rows, and hidden groups.
+ */
+export declare function applyMenuFilter(roots: ModelMenuRoots, options?: MenuFilterOptions): MenuFilterResult;
+/**
+ * Clear every inline `display` this module may have written.
+ *
+ * Elements are never removed; rows and groups return to their natural layout.
+ *
+ * @param roots Popup roots from {@link findModelMenu}.
+ */
+export declare function resetMenuFilter(roots: ModelMenuRoots): void;
+/**
+ * Detect a search widget injected by `dsh-model-search-plugin`.
+ *
+ * A foreign widget sits before the groups container, either as its previous
+ * sibling or anywhere inside the menu (or the menu's parent). When one is found
+ * the caller must not inject a second search box (PRD FR3.2).
+ *
+ * @param roots Popup roots from {@link findModelMenu}.
+ * @returns True when a foreign search widget occupies the slot above the groups.
+ */
+export declare function hasForeignSearchWidget(roots: ModelMenuRoots): boolean;
+/**
+ * Insert (or update) the "everything is filtered out" empty state above the groups.
+ *
+ * The element carries the message text plus one button that invokes `onAction`,
+ * so a caller can restore the hidden entries in one click (PRD FR3.3). Repeated
+ * calls reuse the same element and replace its text, button label, and handler.
+ *
+ * @param roots Popup roots from {@link findModelMenu}.
+ * @param text Message shown before the action button.
+ * @param actionLabel Button label, e.g. "显示 3 个隐藏项".
+ * @param onAction Click handler for that button.
+ * @returns The inserted `#dsh-llm-ctl-empty` element.
+ */
+export declare function ensureEmptyState(roots: ModelMenuRoots, text: string, actionLabel: string, onAction: () => void): HTMLElement;
+/**
+ * Remove the empty state injected by {@link ensureEmptyState}, if present.
+ *
+ * @param roots Popup roots from {@link findModelMenu}.
+ */
+export declare function removeEmptyState(roots: ModelMenuRoots): void;