@2lab.ai/ui 0.0.0-stage → 0.1.1

package/dist/components/agent-queue/logic.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Pure data helpers for `<ui-agent-queue>` — ported from the soma-work dashboard (`aq*`, `cap*`, `cron*` in
+ * dash-main.ts, .prd/affectui/re-agent-queue.md D3·D8–D10·D13·D16–D19). No DOM, no clock: every function takes `now`.
+ * Every time here is epoch **milliseconds**; seconds are converted once, at the boundary (`normalize`, `toMs`).
+ */
+/** Unit of every epoch field in the data (`now`, `fetchedAt`, `measuredAt`, `returnAt`, `refills[].at`, `nextRunAt`, `runs[].at`). */
+export type TimeUnit = 'ms' | 's';
+/** Pool state of a provider. `low` = the primary measure is under {@link LOW_PCT}% of the total. */
+export type AqPoolState = 'ok' | 'low' | 'empty' | 'unknown';
+/**
+ * One account (a worker).
+ * - `available` — usable now (its dot says which window binds first).
+ * - `limited` — counted but blocked by a limit; shows the reason and the time left (`returnAt`).
+ * - `paused` — held out of the totals (paused, auth failure …).
+ * - `spent` — counted, not blocked, nothing usable now.
+ * - `unmeasured` — counted, no 5-hour reading.
+ * - `excluded` — not counted (no measurement, unknown tier …).
+ */
+export type AqAccountState = 'available' | 'limited' | 'paused' | 'spent' | 'unmeasured' | 'excluded';
+/** Known reason keys (translated). Any other string is shown as given. */
+export type AqReason = 'weekly' | '5h' | 'model' | 'cooldown' | 'paused' | 'auth' | 'held' | 'noMeasure' | 'unknownTier';
+export interface AqAccount {
+    /** Stable identity (the open card, the roving stop and focus follow it across updates). */
+    id: string;
+    name: string;
+    state: AqAccountState;
+    /** Why it is limited / paused / excluded: a known key (translated) or free text. */
+    reason?: AqReason | (string & {});
+    /** When every block has lifted (epoch, see `timeUnit`). Limited accounts count down to it. */
+    returnAt?: number;
+    /** Which window binds a usable account first — colours its dot (5h teal, 7d violet). */
+    binding?: '5h' | '7d';
+    /** Plan label, e.g. `Max x5`. */
+    tier?: string;
+    /** The tier is assumed (no configured or reported plan). */
+    tierAssumed?: boolean;
+    /** This account's own 5-hour remaining, 0..1 (account card only). */
+    fiveHour?: number;
+    /** This account's own weekly remaining, 0..1 (account card only). */
+    weekly?: number;
+    /** A passed reset decides a number this account contributes. */
+    estimated?: boolean;
+}
+/** A replayed reset: what comes back, and when. Gains are in accounts' worth. */
+export interface AqRefill {
+    at: number;
+    /** `5h` reset (dot), `7d` weekly reset (diamond), or a block lifting. */
+    cause: '5h' | '7d' | 'release';
+    /** Gain to the 5-hour measure. */
+    fiveHour?: number;
+    /** Gain to the weekly measure. */
+    weekly?: number;
+    /** Account name (titles only). */
+    account?: string;
+}
+export interface AqProvider {
+    id: string;
+    name: string;
+    /** Where the numbers come from, e.g. `llmux`. */
+    source?: string;
+    /** Pool size in accounts' worth (tier-weighted). Nothing is computed without it. */
+    total: number;
+    /** Usable now (5-hour window), accounts' worth. Omit for providers without a 5-hour window. */
+    fiveHour?: number;
+    /** Left this week, accounts' worth. */
+    weekly?: number;
+    /** Pool state. Derived from the primary measure when omitted (see {@link poolState}). */
+    state?: AqPoolState;
+    /** Accounts in the pool (default `accounts.length`). */
+    accountCount?: number;
+    /** Accounts counted in the totals (default: accounts not paused / excluded). */
+    countedAccounts?: number;
+    /** Accounts left out of the totals, by reason (default: derived from `accounts`). */
+    excluded?: {
+        held?: number;
+        unknownTier?: number;
+        noMeasure?: number;
+    };
+    /** Accounts whose numbers are estimated (default: derived). */
+    estimated?: number;
+    /** Accounts without a 5-hour reading (default: derived). */
+    unmeasured5h?: number;
+    /** Oldest measurement behind the numbers (epoch) — “measured 4h ago”, flagged past a day. */
+    measuredAt?: number;
+    /** Replayed resets in time order (next 7 days). */
+    refills?: AqRefill[];
+    accounts?: AqAccount[];
+}
+/**
+ * A run record. `unknown` = a run whose result is not known — counted apart, never as success.
+ * `running` / `waiting` = recorded, and its session is busy now (stacked as “in progress”).
+ */
+export type AqRunStatus = 'ok' | 'running' | 'waiting' | 'failed' | 'unknown';
+export interface AqRun {
+    at: number;
+    status: AqRunStatus;
+    /** Owning job (only needed in `lane.runs24h`). */
+    jobId?: string;
+    /** What the run was, e.g. a session headline or `Thread reply (no session)`. */
+    label?: string;
+    /** Error text of a failed run. */
+    error?: string;
+}
+export interface AqJob {
+    id: string;
+    name: string;
+    /** Schedule in words. Derived from `expression` for common shapes when omitted. */
+    schedule?: string;
+    /** Raw cron expression (shown as the schedule's tooltip). */
+    expression?: string;
+    /** Next fire (epoch). Jobs without one are left out of the up-next queue. */
+    nextRunAt?: number;
+    /** Kept run records, any order. */
+    runs?: AqRun[];
+    /** “Past runs N” (default `runs.length`). */
+    pastRuns?: number;
+    /** Live state now: a running session, or one waiting for a reply. */
+    state?: 'running' | 'waiting' | 'idle';
+    /** History is FIFO-capped at this many runs: counts in a window it no longer covers become “≥ n”. */
+    historyCap?: number;
+}
+export interface AqLane {
+    /** Lane title (default `CRON`). */
+    title?: string;
+    jobs: AqJob[];
+    /** Run records of the last 24 hours for the stats and the chart. Default: every job's `runs`. */
+    runs24h?: AqRun[];
+}
+export interface AgentQueueData {
+    /** Provider capacity. Omit to hide the section. */
+    providers?: AqProvider[];
+    /** Muted note beside the capacity title, e.g. `account = one top-plan account's worth · llmux`. */
+    capacityNote?: string;
+    /** When the capacity was read (epoch) — “updated 12s ago”, ticking. */
+    fetchedAt?: number;
+    /** The capacity could not be read: shown instead of the cards. */
+    capacityError?: string;
+    /** The scheduled-job lane. Omit to hide the section. */
+    lane?: AqLane;
+    /** The clock (epoch). Default `Date.now()`; countdowns tick on from it. */
+    now?: number;
+    /** Unit of every epoch field. Default `ms`. Capacity servers that speak epoch seconds pass `s`. */
+    timeUnit?: TimeUnit;
+}
+export declare const SEC = 1000;
+export declare const HOUR = 3600000;
+export declare const DAY = 86400000;
+export declare const H5: number;
+export declare const D7: number;
+/** Under this % of the total a pool reads `low` (dashboard CAP_LOW_PCT = capacity-view CAPACITY_LOW_PCT). */
+export declare const LOW_PCT = 20;
+/** An epoch in the given unit as milliseconds; `undefined` for anything not finite. */
+export declare function toMs(v: unknown, unit?: TimeUnit): number | undefined;
+/** A copy of the data with every epoch in milliseconds — the one place units are converted. */
+export declare function normalize(d: AgentQueueData): AgentQueueData;
+/** Tool- or user-written text as one plain line for the live region: control chars / whitespace runs → one space, capped. */
+export declare function plain(s: unknown, max?: number): string;
+/** `HH:MM` today, `M/D HH:MM` on another day (viewer's zone). */
+export declare function clockLabel(atMs: number, nowMs: number): string;
+/** `HH:MM` (chart bins). */
+export declare function hm(ms: number): string;
+/** Elapsed span, minutes floored: `<1m`, `11m`, `3h 5m`, `1d 6h` (the dashboard's capCountdown). */
+export declare function spanShort(secs: number): string;
+/** One decimal: `3.5`. */
+export declare function fmt1(x: number): string;
+/** “2.37 / 2.4”, never “2.4 / 2.4 99%”: a value that rounds to the total but is not full keeps two decimals. */
+export declare function fmtCount(v: number, total: number): string;
+/** % from the raw ratio: 100% only when full; `—` without a total. */
+export declare function fmtPct(v: number, total: number): string;
+export type MeasureKey = 'fiveHour' | 'weekly';
+/** The provider has a 5-hour window (two bars) — otherwise the weekly measure is primary. */
+export declare function has5h(p: AqProvider): boolean;
+/** The measure that decides empty / low: 5-hour when present, else weekly. */
+export declare function primaryKey(p: AqProvider): MeasureKey;
+/** Host-supplied enums are checked at the boundary: an unknown value never reaches markup. */
+export declare function accountState(v: unknown): AqAccountState;
+export declare function poolState(p: AqProvider): AqPoolState;
+/** Refills whose time has come are folded into the measures they moved, so nothing past reads as “to come”. */
+export declare function advanceProvider(p: AqProvider, nowMs: number): AqProvider;
+/** The first gain ≥ 0.05 within 7 days that raises this measure, or null. */
+export declare function nextRefill(p: AqProvider, key: MeasureKey, nowMs: number): AqRefill | null;
+/** Sum of the gains to this measure within the span (small gains are summed, never dropped). */
+export declare function gainWithin(p: AqProvider, key: MeasureKey, nowMs: number, span?: number): number;
+/** Accounts that are counted but limited right now. */
+export declare function limitedAccounts(p: AqProvider): AqAccount[];
+/** The earliest return among the limited accounts (epoch ms), or null. */
+export declare function firstReturn(p: AqProvider): number | null;
+/** When an empty pool gets something back: the first return, else the first refill of the primary measure. */
+export declare function emptyReturnAt(p: AqProvider, nowMs: number): number | null;
+/** Accounts counted in the totals (not paused, not excluded). */
+export declare function countedAccounts(p: AqProvider): number;
+/** Exclusions by reason: given, else from the accounts (paused → held; excluded by its reason key). */
+export declare function exclusions(p: AqProvider): {
+    held: number;
+    unknownTier: number;
+    noMeasure: number;
+};
+/** now → 24h takes 55% of the axis (0·1·3·6·12·24h), then days to 7d. Offset in ms → 0..1. */
+export declare function axisPos(offsetMs: number): number;
+export interface TimelineMark {
+    /** `h5` = 5-hour reset (dot, label above), `wk` = weekly reset (diamond, label below). */
+    c: 'h5' | 'wk';
+    x0: number;
+    x1: number;
+    gain: number;
+    n: number;
+    names: string[];
+    at: number;
+}
+/**
+ * The 7-day timeline's marks at width W (px): refills that raise a measure (5h by the 5-hour gain, weekly by the
+ * weekly gain); same-type marks closer than a label merge into one with a short span.
+ */
+export declare function timelineMarks(p: AqProvider, W: number, nowMs: number, pad?: number): TimelineMark[];
+export type RunKind = 'ok' | 'run' | 'fail' | 'unknown';
+/** ok → ok, running / waiting → in progress, failed → fail, anything else → unknown (never ok). */
+export declare function runKind(status: unknown): RunKind;
+export interface DayRuns {
+    from: number;
+    runs: Array<{
+        at: number;
+        kind: 'ok' | 'run' | 'fail';
+    }>;
+    n: number;
+    ok: number;
+    fail: number;
+    run: number;
+    /** Runs with an unknown result: counted apart, never drawn, never success. */
+    unknown: number;
+    /** Jobs whose capped history starts inside the window: counts are lower bounds from `from`. */
+    cut: Array<{
+        name: string;
+        from: number;
+        cap: number;
+    }>;
+    cutFrom: number;
+}
+/** The last 24 hours of run records: `lane.runs24h` when given, else every job's runs. */
+export declare function dayRuns(lane: AqLane, nowMs: number): DayRuns;
+export interface RunBin {
+    at: number;
+    ok: number;
+    run: number;
+    fail: number;
+}
+/** 24 rolling one-hour bins ending now (each labelled by its start). */
+export declare function runBins(day: DayRuns, nowMs: number): RunBin[];
+export declare const NICE: number[];
+/** Chart y max: max(peak, 4) rounded up to a nice value. */
+export declare function niceMax(peak: number): number;
+/** Lane order: waiting for a reply, then running, then the newest run, then the next fire, then the name. */
+export declare function orderJobs(jobs: AqJob[]): AqJob[];
+/** The up-next queue: jobs with a next fire, soonest first. */
+export declare function upNext(jobs: AqJob[]): AqJob[];
+/** A job's runs, newest first. */
+export declare function jobRuns(j: AqJob): AqRun[];
+/**
+ * Schedule in words for the common cron shapes; anything else stays the raw expression. Clock times read in
+ * the viewer's zone from the next fire (the expression is UTC).
+ */
+export declare function scheduleLabel(expr: string | undefined, nextRunAt: number | undefined, lang?: 'en' | 'ko'): string;