@leaves615/dsh-llm-ctl 0.1.0

package/lib/queue-dock.js

@@ -0,0 +1,291 @@
+/**
+ * React views for the `conversation.composer.dock` queue seat.
+ *
+ * The dock is the official list slot below the composer card
+ * (`dsh-client-ui-conversation`, kind `list`, scope `session`, no owner
+ * props). Seats render as siblings inside one `display: contents` slot
+ * anchor: the official stats pills (`dsh-client-ui-chat` `StatsPills`,
+ * order 0, `.bOPqQW_root` — a centered 13px tertiary pill row) come first,
+ * our queue pills go last (order 1000). We cannot nest inside the stats
+ * seat's own root (it is owned by another plugin's component), so this panel
+ * mirrors its pill-row language so the two stacked rows read as one dock.
+ *
+ * Each pill is a compact trigger (glyph + count) that opens an anchored
+ * dialog with the full queue or cooling detail — the same interaction the
+ * official stats pills use. The seat returns null while the control plane is
+ * idle so the dock collapses to nothing.
+ *
+ * Pure view over a small state object plus callbacks: shaping and the trigger
+ * markup are testable without a browser. Hover/expanded styles live in the
+ * client half (`client-plugin.ts` `ensureDockStyles`) because inline styles
+ * cannot express `:hover`.
+ *
+ * @module dsh-llm-ctl/queue-dock
+ */
+import React from 'react';
+import { createPortal } from 'react-dom';
+/**
+ * Format milliseconds as a compact human delay.
+ *
+ * @param ms - Non-negative duration in milliseconds.
+ * @returns Compact label such as `850ms`, `12.0s`, or `2m05s`.
+ */
+export function formatMs(ms) {
+    if (ms < 1000)
+        return Math.max(0, Math.round(ms)) + 'ms';
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return (seconds < 10 ? seconds.toFixed(1) : String(Math.round(seconds))) + 's';
+    return Math.floor(seconds / 60) + 'm' + Math.round(seconds % 60) + 's';
+}
+/**
+ * Shape the dock view, or undefined when the control plane is idle.
+ *
+ * @param queue - Live lanes and waiters from the state poll.
+ * @returns The content to render, or undefined when there is nothing to show.
+ */
+export function buildQueueDockView(queue) {
+    const cooling = queue.lanes.filter((lane) => lane.cooldownRemainingMs > 0);
+    if (queue.waiters.length === 0 && cooling.length === 0)
+        return undefined;
+    return { waiters: [...queue.waiters], cooling };
+}
+/** Cancel-button class; hover is styled by the injected dock stylesheet. */
+export const DOCK_CANCEL_CLASS = 'dsh-llm-ctl-dock-cancel';
+/** Pill-trigger class; hover/expanded styling comes from the dock stylesheet. */
+export const DOCK_PILL_CLASS = 'dsh-llm-ctl-dock-pill';
+/**
+ * Pill row: mirrors the stats seat's `.bOPqQW_root` (centered 13px tertiary
+ * row, same content width and side clearance). Class hashes are
+ * version-specific, so the values are repeated here instead of referencing
+ * the stats classes.
+ */
+const panelStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexWrap: 'wrap',
+    gap: '4px 12px',
+    boxSizing: 'border-box',
+    width: '100%',
+    maxWidth: 'var(--dsh-chat-content-width)',
+    margin: '0 auto',
+    padding: '4px calc(var(--dsh-composer-side-clearance, 16px) + 16px) 0',
+    fontSize: 'var(--dsh-content-font-size-secondary, 13px)',
+    lineHeight: 'calc(20px + var(--dsh-content-font-delta-secondary, 0px))',
+    color: 'var(--dsw-alias-label-tertiary, #93a1c0)',
+};
+const anchorStyle = { display: 'inline-flex', minWidth: 0 };
+/** Same inline-flex rhythm as `.bOPqQW_pill`; hover comes from CSS. */
+const triggerStyle = {
+    boxSizing: 'border-box',
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 6,
+    maxWidth: '100%',
+    padding: '1px 8px',
+    border: 'none',
+    borderRadius: 24,
+    background: 'transparent',
+    color: 'inherit',
+    font: 'inherit',
+    fontVariantNumeric: 'tabular-nums',
+    lineHeight: 'inherit',
+    whiteSpace: 'nowrap',
+    cursor: 'pointer',
+};
+const labelStyle = { minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis' };
+const glyphStyle = { flex: 'none', width: 14, height: 14 };
+const dialogPanelStyle = {
+    position: 'fixed',
+    zIndex: 1100,
+    boxSizing: 'border-box',
+    transform: 'translateX(-50%)',
+    width: 'max-content',
+    minWidth: 'min(300px, 100vw - 24px)',
+    maxWidth: 'min(440px, 100vw - 24px)',
+    background: 'var(--dsw-specific-menu)',
+    boxShadow: 'var(--dsw-elevation-prominent)',
+    color: 'var(--dsw-alias-label-secondary)',
+    border: 0,
+    borderRadius: 12,
+    padding: 16,
+    fontSize: 12,
+    lineHeight: '18px',
+};
+const dialogTitleStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 6,
+    color: 'var(--dsw-alias-label-primary)',
+    marginBottom: 8,
+    fontWeight: 500,
+};
+const dialogRuleStyle = { borderTop: '.5px solid var(--dsw-alias-border-l2)', marginBottom: 10 };
+const listStyle = {
+    listStyle: 'none',
+    margin: 0,
+    padding: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 6,
+    maxHeight: 240,
+    overflowY: 'auto',
+};
+const rowStyle = { display: 'flex', alignItems: 'center', gap: 8, minWidth: 0 };
+const rowBadgeStyle = { flex: 'none', color: 'var(--dsw-alias-label-tertiary)', fontVariantNumeric: 'tabular-nums' };
+const rowProviderStyle = {
+    flex: 1,
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+    color: 'var(--dsw-alias-label-primary)',
+};
+const rowMetaStyle = { flex: 'none', color: 'var(--dsw-alias-label-tertiary)', fontVariantNumeric: 'tabular-nums' };
+const cancelButtonStyle = {
+    flex: 'none',
+    border: 'none',
+    background: 'transparent',
+    color: 'var(--dsw-alias-label-tertiary)',
+    borderRadius: 6,
+    padding: '2px 8px',
+    font: 'inherit',
+    cursor: 'pointer',
+};
+/** Clock glyph for the queue pill (stroke-style, matches the stats pills). */
+function QueueGlyph() {
+    return React.createElement('svg', { width: 14, height: 14, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': true, style: glyphStyle }, React.createElement('circle', { cx: 8, cy: 8, r: 6, stroke: 'currentColor', strokeWidth: 1.25 }), React.createElement('path', {
+        d: 'M8 4.6V8.4L10.6 10',
+        stroke: 'currentColor',
+        strokeWidth: 1.25,
+        strokeLinecap: 'round',
+        strokeLinejoin: 'round',
+    }));
+}
+/** Snowflake glyph for the cooling pill. */
+function CoolingGlyph() {
+    return React.createElement('svg', { width: 14, height: 14, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': true, style: glyphStyle }, React.createElement('path', {
+        d: 'M8 1.5V14.5M2.4 4.75L13.6 11.25M13.6 4.75L2.4 11.25',
+        stroke: 'currentColor',
+        strokeWidth: 1.25,
+        strokeLinecap: 'round',
+    }));
+}
+/**
+ * One compact trigger that opens its dialog above itself.
+ *
+ * Mirrors the official stats-pill interaction (anchored panel, outside
+ * pointer and Escape dismiss) with local state, so the browser half needs no
+ * UI-primitives types.
+ *
+ * @param props - Glyph, pill label, dialog title, and dialog body.
+ * @returns The trigger plus, while open, its portaled dialog.
+ */
+function DockPill(props) {
+    const { icon, label, title, children } = props;
+    const [open, setOpen] = React.useState(false);
+    const [pos, setPos] = React.useState(undefined);
+    const rootRef = React.useRef(null);
+    const panelRef = React.useRef(null);
+    React.useEffect(() => {
+        if (!open) {
+            setPos(undefined);
+            return;
+        }
+        const anchor = rootRef.current;
+        if (anchor === null)
+            return;
+        const rect = anchor.getBoundingClientRect();
+        setPos({ left: rect.left + rect.width / 2, bottom: window.innerHeight - rect.top + 8 });
+    }, [open]);
+    React.useEffect(() => {
+        if (!open)
+            return;
+        const onPointerDown = (event) => {
+            const target = event.target;
+            if (target !== null) {
+                if (rootRef.current !== null && rootRef.current.contains(target))
+                    return;
+                if (panelRef.current !== null && panelRef.current.contains(target))
+                    return;
+            }
+            setOpen(false);
+        };
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape')
+                setOpen(false);
+        };
+        document.addEventListener('mousedown', onPointerDown, true);
+        document.addEventListener('keydown', onKeyDown);
+        return () => {
+            document.removeEventListener('mousedown', onPointerDown, true);
+            document.removeEventListener('keydown', onKeyDown);
+        };
+    }, [open]);
+    const trigger = React.createElement('span', { ref: rootRef, style: anchorStyle }, React.createElement('button', {
+        type: 'button',
+        className: DOCK_PILL_CLASS,
+        style: triggerStyle,
+        'aria-haspopup': 'dialog',
+        'aria-expanded': open,
+        'aria-label': label,
+        title: label,
+        onClick: () => setOpen(!open),
+    }, icon, React.createElement('span', { style: labelStyle }, label)));
+    const dialog = open
+        ? createPortal(React.createElement('div', {
+            ref: panelRef,
+            className: 'dsh-llm-ctl-queue-dialog',
+            role: 'dialog',
+            'aria-label': title,
+            style: pos === undefined ? { ...dialogPanelStyle, visibility: 'hidden' } : { ...dialogPanelStyle, ...pos },
+        }, React.createElement('div', { style: dialogTitleStyle }, icon, title), React.createElement('div', { style: dialogRuleStyle, 'aria-hidden': true }), children), document.body)
+        : null;
+    return React.createElement(React.Fragment, null, trigger, dialog);
+}
+/** Queue pill: count plus the front waiter's ETA, details on click. */
+function QueuePill(props) {
+    const { waiters, onCancel } = props;
+    const first = waiters[0];
+    const label = first === undefined ? '排队 ' + waiters.length : '排队 ' + waiters.length + ' · ~' + formatMs(first.etaMs);
+    return React.createElement(DockPill, { icon: QueueGlyph(), label, title: '队列状况' }, React.createElement(QueueDetails, { waiters, onCancel }));
+}
+/** Dialog body: one row per waiter, each with its own cancel button. */
+export function QueueDetails(props) {
+    const { waiters, onCancel } = props;
+    return React.createElement('ul', { style: listStyle }, waiters.map((waiter) => React.createElement('li', { key: waiter.queueId, style: rowStyle }, React.createElement('span', { style: rowBadgeStyle }, '#' + waiter.position), React.createElement('span', { style: rowProviderStyle }, waiter.provider), React.createElement('span', { style: rowMetaStyle }, (waiter.origin === 'background' ? '后台' : '对话') + ' · ' + formatMs(waiter.etaMs)), React.createElement('button', {
+        type: 'button',
+        className: DOCK_CANCEL_CLASS,
+        style: cancelButtonStyle,
+        onClick: () => onCancel(waiter.queueId),
+    }, '取消'))));
+}
+/** Cooling pill: lane count plus the longest remaining cooldown. */
+function CoolingPill(props) {
+    const { lanes } = props;
+    const longest = lanes.reduce((max, lane) => Math.max(max, lane.cooldownRemainingMs), 0);
+    return React.createElement(DockPill, { icon: CoolingGlyph(), label: '冷却 ' + lanes.length + ' · 最长 ' + formatMs(longest), title: '冷却中的 provider' }, React.createElement(CoolingDetails, { lanes }));
+}
+/** Dialog body: one row per cooling lane. */
+export function CoolingDetails(props) {
+    const { lanes } = props;
+    return React.createElement('ul', { style: listStyle }, lanes.map((lane) => React.createElement('li', { key: lane.provider, style: rowStyle }, React.createElement('span', { style: rowProviderStyle }, lane.provider), React.createElement('span', { style: rowMetaStyle }, formatMs(lane.cooldownRemainingMs)))));
+}
+/**
+ * Queue/cooldown pills for the composer dock.
+ *
+ * @param props - Shaped dock view plus the cancel callback.
+ * @returns The rendered pill row.
+ */
+export function QueueDockPanel(props) {
+    const { view, onCancel } = props;
+    const children = [];
+    if (view.waiters.length > 0) {
+        children.push(React.createElement(QueuePill, { key: 'queue', waiters: view.waiters, onCancel }));
+    }
+    if (view.cooling.length > 0) {
+        children.push(React.createElement(CoolingPill, { key: 'cooling', lanes: view.cooling }));
+    }
+    return React.createElement('div', { style: panelStyle, role: 'status', 'aria-live': 'polite' }, children);
+}

package/lib/queue.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Per-provider admission queue: concurrency cap, arrival-order FIFO, and the
+ * provider cooldown clock that follows a rate-limit failure.
+ *
+ * The gate is deliberately transport-free: it never touches a stream, only
+ * decides when a request may be dispatched. Clock and timers are injectable so
+ * the whole scheduler is testable without real time.
+ *
+ * @module dsh-llm-ctl/queue
+ */
+import type { CtlEvent, CtlEventKind, Origin } from './events.ts';
+/** Why an admission request did not get a slot. */
+export type AcquireFailureCode = 'QUEUE_FULL' | 'QUEUE_TIMEOUT' | 'ABORTED';
+/** Successful admission: the caller must invoke `release` exactly once. */
+export interface AcquireGranted {
+    ok: true;
+    queueId: string;
+    provider: string;
+    origin: Origin;
+    waitMs: number;
+    release: () => void;
+}
+/** Refused admission. */
+export interface AcquireRefused {
+    ok: false;
+    code: AcquireFailureCode;
+    provider: string;
+    origin: Origin;
+    waitMs: number;
+    reason: string;
+    queueId?: string;
+}
+/** Result of one admission attempt. */
+export type AcquireOutcome = AcquireGranted | AcquireRefused;
+/** Minimal clock and timer seam, so tests can drive time deterministically. */
+export interface Scheduler {
+    now(): number;
+    setTimer(callback: () => void, delayMs: number): unknown;
+    clearTimer(handle: unknown): void;
+}
+/** Production scheduler backed by the global timers. */
+export declare const realScheduler: Scheduler;
+/** One queued request as reported to the UI. */
+export interface QueueWaiterView {
+    queueId: string;
+    provider: string;
+    origin: Origin;
+    position: number;
+    waitedMs: number;
+    etaMs: number;
+}
+/** Current control-plane state. */
+export interface GateSnapshot {
+    at: number;
+    lanes: Array<{
+        provider: string;
+        active: number;
+        /** Effective cap; `0` means unlimited. */
+        concurrency: number;
+        queued: number;
+        cooldownRemainingMs: number;
+        averageDurationMs: number;
+    }>;
+    waiters: QueueWaiterView[];
+}
+/** Construction options for {@link ProviderGate}. */
+export interface GateOptions {
+    scheduler?: Scheduler;
+    concurrencyFor: (provider: string) => number;
+    maxQueueDepth: number;
+    maxWaitMs: number;
+    /** Emit one observable fact. */
+    onEvent?: (kind: CtlEventKind, detail: Omit<CtlEvent, 'seq' | 'at' | 'kind'>) => void;
+    idFactory?: () => string;
+}
+/** Admission gate over all provider routes. */
+export declare class ProviderGate {
+    private readonly scheduler;
+    private readonly concurrencyFor;
+    private maxQueueDepth;
+    private maxWaitMs;
+    private readonly onEvent;
+    private readonly idFactory;
+    private readonly lanes;
+    private disposed;
+    private counter;
+    constructor(options: GateOptions);
+    private lane;
+    private emit;
+    private grant;
+    /** Refuse immediately when the provider cannot serve inside the budget. */
+    private preflightRefusal;
+    /** Request admission; resolves once a slot is granted or refused. */
+    acquire(provider: string, options: {
+        origin: Origin;
+        signal?: AbortSignal | undefined;
+    }): Promise<AcquireOutcome>;
+    /**
+     * 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: {
+        maxWaitMs?: number;
+        maxQueueDepth?: number;
+    }): void;
+    /** Return a slot granted by {@link acquire}. */
+    release(provider: string, durationMs?: number): void;
+    /**
+     * 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: string, delayMs: number, reason: string, source?: string): void;
+    /** Cancel one still-queued request. */
+    cancel(queueId: string): boolean;
+    /** Current lanes and waiters, ordered by provider then arrival. */
+    snapshot(): GateSnapshot;
+    /** Fail every waiter and stop all timers. */
+    dispose(): void;
+    private armCooldown;
+    private pump;
+}