@leaves615/dsh-llm-ctl 0.1.0

package/lib/queue.js

@@ -0,0 +1,313 @@
+/** Production scheduler backed by the global timers. */
+export const realScheduler = {
+    now: () => Date.now(),
+    setTimer: (callback, delayMs) => setTimeout(callback, Math.max(0, delayMs)),
+    clearTimer: (handle) => clearTimeout(handle),
+};
+/** Admission gate over all provider routes. */
+export class ProviderGate {
+    scheduler;
+    concurrencyFor;
+    maxQueueDepth;
+    maxWaitMs;
+    onEvent;
+    idFactory;
+    lanes = new Map();
+    disposed = false;
+    counter = 0;
+    constructor(options) {
+        this.scheduler = options.scheduler ?? realScheduler;
+        this.concurrencyFor = options.concurrencyFor;
+        this.maxQueueDepth = Math.max(1, options.maxQueueDepth);
+        this.maxWaitMs = Math.max(0, options.maxWaitMs);
+        this.onEvent = options.onEvent;
+        this.idFactory = options.idFactory ?? (() => `q${(this.counter += 1)}`);
+    }
+    lane(provider) {
+        let lane = this.lanes.get(provider);
+        if (lane === undefined) {
+            lane = { active: 0, waiters: [], cooldownUntil: 0, cooldownTimer: undefined, averageDurationMs: 1_000 };
+            this.lanes.set(provider, lane);
+        }
+        return lane;
+    }
+    emit(kind, detail) {
+        this.onEvent?.(kind, detail);
+    }
+    grant(provider, lane, origin, queueId, waitMs) {
+        const grantedAt = this.scheduler.now();
+        lane.active += 1;
+        this.emit('granted', { provider, origin, queueId, waitMs, position: 0 });
+        return {
+            ok: true,
+            queueId,
+            provider,
+            origin,
+            waitMs,
+            release: () => this.release(provider, this.scheduler.now() - grantedAt),
+        };
+    }
+    /** Refuse immediately when the provider cannot serve inside the budget. */
+    preflightRefusal(lane, provider, origin, now) {
+        const cooldownRemaining = lane.cooldownUntil - now;
+        if (cooldownRemaining > this.maxWaitMs) {
+            this.emit('queue-timeout', { provider, origin, reason: 'cooldown-exceeds-budget', delayMs: cooldownRemaining });
+            return { ok: false, code: 'QUEUE_TIMEOUT', provider, origin, waitMs: 0, reason: 'cooldown-exceeds-budget' };
+        }
+        if (lane.waiters.length >= this.maxQueueDepth) {
+            this.emit('queue-full', { provider, origin, reason: 'max-queue-depth', position: lane.waiters.length });
+            return { ok: false, code: 'QUEUE_FULL', provider, origin, waitMs: 0, reason: 'max-queue-depth' };
+        }
+        return undefined;
+    }
+    /** Request admission; resolves once a slot is granted or refused. */
+    acquire(provider, options) {
+        const { origin, signal } = options;
+        if (this.disposed) {
+            return Promise.resolve({ ok: false, code: 'ABORTED', provider, origin, waitMs: 0, reason: 'disposed' });
+        }
+        const lane = this.lane(provider);
+        const now = this.scheduler.now();
+        if (lane.active < this.concurrencyFor(provider) && lane.waiters.length === 0 && now >= lane.cooldownUntil) {
+            const queueId = this.idFactory();
+            return Promise.resolve(this.grant(provider, lane, origin, queueId, 0));
+        }
+        const refused = this.preflightRefusal(lane, provider, origin, now);
+        if (refused !== undefined)
+            return Promise.resolve(refused);
+        return new Promise((resolve) => {
+            const waiter = {
+                id: this.idFactory(),
+                provider,
+                origin,
+                enqueuedAt: now,
+                settled: false,
+                deadline: undefined,
+                resolve,
+                detachAbort: () => undefined,
+                settle: () => undefined,
+            };
+            const settle = (outcome) => {
+                if (waiter.settled)
+                    return;
+                waiter.settled = true;
+                this.scheduler.clearTimer(waiter.deadline);
+                waiter.detachAbort();
+                const index = lane.waiters.indexOf(waiter);
+                if (index >= 0)
+                    lane.waiters.splice(index, 1);
+                resolve(outcome);
+            };
+            waiter.settle = settle;
+            waiter.deadline = this.scheduler.setTimer(() => {
+                const waitedMs = this.scheduler.now() - waiter.enqueuedAt;
+                this.emit('queue-timeout', { provider, origin, queueId: waiter.id, reason: 'max-wait', waitMs: waitedMs });
+                settle({ ok: false, code: 'QUEUE_TIMEOUT', provider, origin, waitMs: waitedMs, reason: 'max-wait', queueId: waiter.id });
+            }, this.maxWaitMs);
+            if (signal !== undefined) {
+                if (signal.aborted) {
+                    settle({ ok: false, code: 'ABORTED', provider, origin, waitMs: 0, reason: 'aborted', queueId: waiter.id });
+                    return;
+                }
+                const onAbort = () => {
+                    settle({
+                        ok: false,
+                        code: 'ABORTED',
+                        provider,
+                        origin,
+                        waitMs: this.scheduler.now() - waiter.enqueuedAt,
+                        reason: 'aborted',
+                        queueId: waiter.id,
+                    });
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+                waiter.detachAbort = () => signal.removeEventListener('abort', onAbort);
+            }
+            lane.waiters.push(waiter);
+            this.emit('queued', {
+                provider,
+                origin,
+                queueId: waiter.id,
+                position: lane.waiters.length,
+                waitMs: 0,
+                delayMs: Math.max(0, lane.cooldownUntil - now),
+            });
+            this.armCooldown(provider, lane);
+        });
+    }
+    /**
+     * Replace the global wait budget and depth cap at runtime.
+     *
+     * Only admissions started after the call observe the new values: waiters
+     * already queued keep the deadline timer armed at acquire time.
+     *
+     * @param limits - partial limits; each defined field replaces the current one.
+     */
+    updateLimits(limits) {
+        if (limits.maxWaitMs !== undefined)
+            this.maxWaitMs = Math.max(0, limits.maxWaitMs);
+        if (limits.maxQueueDepth !== undefined)
+            this.maxQueueDepth = Math.max(1, limits.maxQueueDepth);
+    }
+    /** Return a slot granted by {@link acquire}. */
+    release(provider, durationMs) {
+        const lane = this.lanes.get(provider);
+        if (lane === undefined)
+            return;
+        if (lane.active > 0)
+            lane.active -= 1;
+        if (durationMs !== undefined && Number.isFinite(durationMs) && durationMs >= 0) {
+            lane.averageDurationMs = lane.averageDurationMs * 0.7 + durationMs * 0.3;
+        }
+        this.emit('released', { provider, position: lane.active });
+        this.pump(provider);
+    }
+    /**
+     * Push the provider's cooldown to at least `now + delayMs`.
+     *
+     * A cooldown longer than the wait budget fails every current waiter at once:
+     * none of them could be served before its own deadline, so waiting would only
+     * spend the user's time to produce the same failure.
+     */
+    registerCooldown(provider, delayMs, reason, source) {
+        if (!Number.isFinite(delayMs) || delayMs <= 0)
+            return;
+        const lane = this.lane(provider);
+        const now = this.scheduler.now();
+        const until = now + delayMs;
+        if (until <= lane.cooldownUntil)
+            return;
+        lane.cooldownUntil = until;
+        this.emit('cooldown', { provider, delayMs, reason, ...(source === undefined ? {} : { source }) });
+        if (delayMs > this.maxWaitMs) {
+            for (const waiter of [...lane.waiters]) {
+                waiter.settle({
+                    ok: false,
+                    code: 'QUEUE_TIMEOUT',
+                    provider,
+                    origin: waiter.origin,
+                    waitMs: now - waiter.enqueuedAt,
+                    reason: 'cooldown-exceeds-budget',
+                    queueId: waiter.id,
+                });
+                this.emit('queue-timeout', {
+                    provider,
+                    origin: waiter.origin,
+                    queueId: waiter.id,
+                    reason: 'cooldown-exceeds-budget',
+                    delayMs,
+                });
+            }
+            return;
+        }
+        this.armCooldown(provider, lane);
+    }
+    /** Cancel one still-queued request. */
+    cancel(queueId) {
+        for (const lane of this.lanes.values()) {
+            const waiter = lane.waiters.find((candidate) => candidate.id === queueId);
+            if (waiter === undefined)
+                continue;
+            waiter.settle({
+                ok: false,
+                code: 'ABORTED',
+                provider: waiter.provider,
+                origin: waiter.origin,
+                waitMs: this.scheduler.now() - waiter.enqueuedAt,
+                reason: 'cancelled',
+                queueId: waiter.id,
+            });
+            this.emit('cancelled', { provider: waiter.provider, origin: waiter.origin, queueId: waiter.id, reason: 'user' });
+            return true;
+        }
+        return false;
+    }
+    /** Current lanes and waiters, ordered by provider then arrival. */
+    snapshot() {
+        const now = this.scheduler.now();
+        const lanes = [];
+        const waiters = [];
+        for (const [provider, lane] of this.lanes) {
+            const limit = this.concurrencyFor(provider);
+            // The wire value stays JSON-safe: Infinity would serialize to null.
+            const concurrency = Number.isFinite(limit) ? Math.max(1, limit) : 0;
+            lanes.push({
+                provider,
+                active: lane.active,
+                concurrency,
+                queued: lane.waiters.length,
+                cooldownRemainingMs: Math.max(0, lane.cooldownUntil - now),
+                averageDurationMs: lane.averageDurationMs,
+            });
+            lane.waiters.forEach((waiter, index) => {
+                waiters.push({
+                    queueId: waiter.id,
+                    provider,
+                    origin: waiter.origin,
+                    position: index + 1,
+                    waitedMs: now - waiter.enqueuedAt,
+                    // index 之前还有 lane.active 个正在跑的请求占着并发槽；
+                    // (index + active) / limit 算出还要排空几波（不限流时只剩冷却）。
+                    etaMs: Math.max(0, lane.cooldownUntil - now) + Math.floor((index + lane.active) / limit) * lane.averageDurationMs,
+                });
+            });
+        }
+        return { at: now, lanes, waiters };
+    }
+    /** Fail every waiter and stop all timers. */
+    dispose() {
+        this.disposed = true;
+        const now = this.scheduler.now();
+        for (const lane of this.lanes.values()) {
+            this.scheduler.clearTimer(lane.cooldownTimer);
+            lane.cooldownTimer = undefined;
+            for (const waiter of [...lane.waiters]) {
+                waiter.settle({
+                    ok: false,
+                    code: 'ABORTED',
+                    provider: waiter.provider,
+                    origin: waiter.origin,
+                    waitMs: now - waiter.enqueuedAt,
+                    reason: 'disposed',
+                    queueId: waiter.id,
+                });
+            }
+        }
+    }
+    armCooldown(provider, lane) {
+        this.scheduler.clearTimer(lane.cooldownTimer);
+        lane.cooldownTimer = undefined;
+        const remaining = lane.cooldownUntil - this.scheduler.now();
+        if (remaining <= 0) {
+            this.pump(provider);
+            return;
+        }
+        lane.cooldownTimer = this.scheduler.setTimer(() => {
+            lane.cooldownTimer = undefined;
+            this.pump(provider);
+        }, remaining);
+    }
+    pump(provider) {
+        const lane = this.lanes.get(provider);
+        if (lane === undefined || this.disposed)
+            return;
+        const now = this.scheduler.now();
+        if (now < lane.cooldownUntil) {
+            this.armCooldown(provider, lane);
+            return;
+        }
+        const concurrency = Math.max(1, this.concurrencyFor(provider));
+        while (lane.waiters.length > 0 && lane.active < concurrency) {
+            const waiter = lane.waiters.shift();
+            if (waiter === undefined)
+                break;
+            if (waiter.settled)
+                continue;
+            waiter.settled = true;
+            this.scheduler.clearTimer(waiter.deadline);
+            waiter.detachAbort();
+            const waitMs = now - waiter.enqueuedAt;
+            waiter.resolve(this.grant(provider, lane, waiter.origin, waiter.id, waitMs));
+        }
+    }
+}

package/lib/reactive.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Standalone request recovery for deployments without `@deepseek-ai/dsh-llm-retry`.
+ *
+ * The plugin never races the retry executor: it registers the provider cooldown,
+ * asks the rest of the `agent/request-error` waterfall for a decision, and only
+ * spends its own bounded budget when no downstream listener took the failure.
+ *
+ * @module dsh-llm-ctl/reactive
+ */
+import type { DelayResolution } from './delay.ts';
+/**
+ * Failure codes a queue can meaningfully wait out. Mirrors the default retryable
+ * set of `dsh-llm`; quota, auth, and context failures are terminal.
+ */
+export declare const WAITABLE_CODES: readonly string[];
+/** Why standalone recovery did or did not schedule a retry. */
+export type ReactiveReason = 'scheduled' | 'downstream-owns' | 'code-not-waitable' | 'disabled' | 'budget-exhausted' | 'over-budget';
+/** One standalone recovery decision. */
+export interface ReactiveDecision {
+    retry: boolean;
+    delayMs: number;
+    reason: ReactiveReason;
+}
+/** Inputs to {@link decideReactive}. */
+export interface ReactiveInput {
+    code: string;
+    /** True when a downstream listener returned `{kind:'retry'}`. */
+    delegated: boolean;
+    /** Retries already scheduled for this session/provider/turn/step. */
+    attempts: number;
+    /** Configured cap; 0 disables standalone recovery. */
+    limit: number;
+    delay: DelayResolution;
+}
+/**
+ * Decide whether this plugin should schedule the retry itself.
+ *
+ * A downstream decision always wins; the local budget is the fallback for a
+ * deployment that mounts no retry executor at all.
+ */
+export declare function decideReactive(input: ReactiveInput): ReactiveDecision;
+/** Bounded per-step retry counters keyed by session, provider, turn, and step. */
+export declare class RetryBudget {
+    private readonly counts;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    /** Retries already scheduled for this key. */
+    attempts(key: string): number;
+    /** Record one scheduled retry and return the new count. */
+    record(key: string): number;
+    /** Forget one key, e.g. after the step completed. */
+    forget(key: string): void;
+    /** Current entry count, for tests and diagnostics. */
+    get size(): number;
+}
+/** Abortable delay; resolves false when the wait was cancelled. */
+export declare function cancellableDelay(delayMs: number, signal: AbortSignal): Promise<boolean>;

package/lib/reactive.js

@@ -0,0 +1,75 @@
+/**
+ * Failure codes a queue can meaningfully wait out. Mirrors the default retryable
+ * set of `dsh-llm`; quota, auth, and context failures are terminal.
+ */
+export const WAITABLE_CODES = ['RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE'];
+/**
+ * Decide whether this plugin should schedule the retry itself.
+ *
+ * A downstream decision always wins; the local budget is the fallback for a
+ * deployment that mounts no retry executor at all.
+ */
+export function decideReactive(input) {
+    if (input.delegated)
+        return { retry: false, delayMs: input.delay.delayMs, reason: 'downstream-owns' };
+    if (!WAITABLE_CODES.includes(input.code))
+        return { retry: false, delayMs: input.delay.delayMs, reason: 'code-not-waitable' };
+    if (input.limit <= 0)
+        return { retry: false, delayMs: input.delay.delayMs, reason: 'disabled' };
+    if (input.attempts >= input.limit)
+        return { retry: false, delayMs: input.delay.delayMs, reason: 'budget-exhausted' };
+    if (input.delay.overBudget)
+        return { retry: false, delayMs: input.delay.delayMs, reason: 'over-budget' };
+    return { retry: true, delayMs: input.delay.delayMs, reason: 'scheduled' };
+}
+/** Bounded per-step retry counters keyed by session, provider, turn, and step. */
+export class RetryBudget {
+    counts = new Map();
+    maxEntries;
+    constructor(maxEntries = 500) {
+        this.maxEntries = Math.max(1, maxEntries);
+    }
+    /** Retries already scheduled for this key. */
+    attempts(key) {
+        return this.counts.get(key) ?? 0;
+    }
+    /** Record one scheduled retry and return the new count. */
+    record(key) {
+        const next = this.attempts(key) + 1;
+        this.counts.delete(key);
+        this.counts.set(key, next);
+        while (this.counts.size > this.maxEntries) {
+            const oldest = this.counts.keys().next();
+            if (oldest.done === true)
+                break;
+            this.counts.delete(oldest.value);
+        }
+        return next;
+    }
+    /** Forget one key, e.g. after the step completed. */
+    forget(key) {
+        this.counts.delete(key);
+    }
+    /** Current entry count, for tests and diagnostics. */
+    get size() {
+        return this.counts.size;
+    }
+}
+/** Abortable delay; resolves false when the wait was cancelled. */
+export function cancellableDelay(delayMs, signal) {
+    if (signal.aborted)
+        return Promise.resolve(false);
+    if (delayMs <= 0)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(true);
+        }, delayMs);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve(false);
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/lib/reasoning-efforts.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 declare const PI_AI_SETTINGS_NS = "llm-pi-ai";
+/** Thinking levels in escalation order. */
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/** One selectable thinking level. */
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** Official-aligned default ladder: Off/Low/High/Max. */
+export declare const DEFAULT_EFFORT_LEVELS: readonly ThinkingLevel[];
+/** Advanced levels hidden behind the disclosure, off by default. */
+export declare const ADVANCED_EFFORT_LEVELS: readonly ThinkingLevel[];
+/** Wire spelling per level; identity mapping is the standard OpenAI spelling. */
+export type EffortWireMap = Partial<Record<ThinkingLevel, string | null>>;
+/**
+ * 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 declare function defaultReasoningEfforts(levels?: readonly ThinkingLevel[]): Record<string, string>;
+/**
+ * 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 declare function validateReasoningEfforts(value: unknown): string | undefined;
+/** One hand-declared pi-ai model entry (structural subset). */
+export interface PiAiModelEntry {
+    id: string;
+    reasoningEfforts?: unknown;
+    compat?: {
+        supportsReasoningEffort?: unknown;
+    } & Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Resolved per-model effort facts for the settings UI. */
+export interface ModelEffortFacts {
+    provider: string;
+    model: string;
+    /** True when the settings namespace is `llm-pi-ai` (the only writable family). */
+    writableNs: boolean;
+    /** True when the model came from an explicit `models` list (vs catalog/override). */
+    declared: boolean;
+    /** Currently stored reasoningEfforts dict, when valid. */
+    stored?: Record<string, string | null>;
+    /** Currently offered levels (keys of a valid stored dict). */
+    levels: string[];
+    /** Currently offered by the live catalog (read-only display). */
+    liveLevels?: string[];
+}
+/**
+ * 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 declare function summarizeModelEffort(input: {
+    provider: string;
+    model: string;
+    settingsNs: string;
+    entry?: PiAiModelEntry | undefined;
+    liveLevels?: readonly string[] | undefined;
+}): ModelEffortFacts;
+/** Path-addressed settings op (mirrors the host settings shape). */
+export type EffortPathOp = {
+    op: 'set';
+    path: readonly string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: readonly string[];
+};
+/**
+ * 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 declare function buildEffortOps(input: {
+    provider: string;
+    models: readonly PiAiModelEntry[] | undefined;
+    model: string;
+    efforts: Record<string, string | null>;
+}): EffortPathOp[];
+/**
+ * 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 declare function buildEffortResetOps(input: {
+    provider: string;
+    models: readonly PiAiModelEntry[] | undefined;
+    model: string;
+}): EffortPathOp[];