@askalf/dario 6.15.0 → 6.17.0

package/dist/pool.d.ts

@@ -396,8 +396,24 @@ export interface PoolStatus {
  * order is the operator's knob — name seats `1-main` / `2-overflow` to
  * pick the fill order. Sticky bindings behave identically in both modes;
  * strategy only decides where UNBOUND (new) conversations land.
+ *
+ * `headroom-by-plan` (opt-in): headroom, with each seat's headroom counted
+ * by its plan size (see planWeight). Never the default: utilization is a
+ * ratio of an account-wide budget that also carries the owner's own use, no
+ * absolute capacity reaches the wire, and the window that binds (5h or 7d)
+ * matters more than the plan name. A smaller plan regularly has more real
+ * room than a bigger one. It is for operators who know their seats are
+ * otherwise idle and want the bigger plan to carry proportionally more.
+ */
+export type PoolStrategy = 'headroom' | 'headroom-by-plan' | 'fill-first' | 'expiring-first';
+/**
+ * How much a seat's headroom counts under `headroom-by-plan`: N for a Max Nx
+ * plan (from the profile's `rate_limit_tier`, e.g. `default_claude_max_20x`),
+ * 1 for Pro, and 1 for anything unrecognised or unknown, so a seat whose plan
+ * dario cannot read is never favoured. Only the whole `default_claude_max_Nx`
+ * tier name counts; a tier that merely contains `max_Nx` is unrecognised.
  */
-export type PoolStrategy = 'headroom' | 'fill-first' | 'expiring-first';
+export declare function planWeight(rateLimitTier: string | undefined): number;
 /**
  * `expiring-first` — fill-first, ordered by WHEN each seat's capacity expires
  * instead of by alias: new conversations fill the seat whose 7-day window
@@ -602,6 +618,7 @@ export declare function headroomFloorProblem(value: string | number | null | und
  */
 export declare function headroomFloorFlagProblem(value: string): string;
 export declare function resolvePoolHeadroomFloor(explicit?: string | number | null, env?: NodeJS.ProcessEnv): number;
+export declare function pickMaxHeadroom(accounts: PoolAccount[], family?: string | null, byPlan?: boolean): PoolAccount;
 /**
  * The 7-day reset `expiring-first` orders by, in epoch ms: the seat's own
  * reading while it is still ahead of `now`, else +Infinity (never read, or the

package/dist/pool.js

@@ -408,6 +408,18 @@ export function accountAction(account, now = Date.now()) {
         return 'wait';
     return 'none';
 }
+/**
+ * How much a seat's headroom counts under `headroom-by-plan`: N for a Max Nx
+ * plan (from the profile's `rate_limit_tier`, e.g. `default_claude_max_20x`),
+ * 1 for Pro, and 1 for anything unrecognised or unknown, so a seat whose plan
+ * dario cannot read is never favoured. Only the whole `default_claude_max_Nx`
+ * tier name counts; a tier that merely contains `max_Nx` is unrecognised.
+ */
+export function planWeight(rateLimitTier) {
+    const m = /^default_claude_max_(\d+)x$/i.exec(rateLimitTier ?? '');
+    const n = m ? Number(m[1]) : 1;
+    return Number.isFinite(n) && n >= 1 ? n : 1;
+}
 /**
  * `expiring-first` — fill-first, ordered by WHEN each seat's capacity expires
  * instead of by alias: new conversations fill the seat whose 7-day window
@@ -431,7 +443,7 @@ export function resolvePoolStrategy(explicit, env = process.env) {
         if (typeof c !== 'string')
             continue;
         const s = c.trim().toLowerCase();
-        if (s === 'headroom' || s === 'fill-first' || s === 'expiring-first')
+        if (s === 'headroom' || s === 'headroom-by-plan' || s === 'fill-first' || s === 'expiring-first')
             return s;
     }
     return 'headroom';
@@ -446,6 +458,8 @@ export function resolvePoolStrategy(explicit, env = process.env) {
 export function describePoolStrategy(strategy, floor = DEFAULT_POOL_HEADROOM_FLOOR) {
     const pct = `${Math.round(floor * 100)}% floor`;
     switch (strategy) {
+        case 'headroom-by-plan':
+            return `headroom-by-plan: new conversations go to the seat with the most headroom counted by plan size (Max Nx counts N, Pro 1); ${pct}`;
         case 'fill-first':
             return `fill-first — new conversations fill the alphabetically-first seat until the ${pct}, then spill`;
         case 'expiring-first':
@@ -866,14 +880,21 @@ export function resolvePoolHeadroomFloor(explicit, env = process.env) {
 // Pick the account with the most headroom in a single pass. The prior
 // `.reduce()` form recomputed the incumbent's headroom every iteration
 // (~2n computeHeadroom calls); this computes each once (#642-audit).
-function pickMaxHeadroom(accounts, family) {
+// `byPlan` scales positive headroom by planWeight; zero and negative headroom
+// stay unscaled, so a bigger plan that is over its limit never ranks lower
+// than a smaller one that is over by the same amount.
+export function pickMaxHeadroom(accounts, family, byPlan = false) {
+    const score = (a) => {
+        const h = computeHeadroom(a.rateLimit, family);
+        return byPlan && h > 0 ? h * planWeight(a.rateLimitTier) : h;
+    };
     let best = accounts[0];
-    let bestHeadroom = computeHeadroom(best.rateLimit, family);
+    let bestScore = score(best);
     for (let i = 1; i < accounts.length; i++) {
-        const h = computeHeadroom(accounts[i].rateLimit, family);
-        if (h > bestHeadroom) {
+        const s = score(accounts[i]);
+        if (s > bestScore) {
             best = accounts[i];
-            bestHeadroom = h;
+            bestScore = s;
         }
     }
     return best;
@@ -1107,10 +1128,10 @@ export class AccountPool {
                     return first;
             }
             if (!this.hardHeadroomFloor)
-                return pickMaxHeadroom(eligible, family);
+                return pickMaxHeadroom(eligible, family, this.strategy === 'headroom-by-plan');
             const aboveFloor = eligible.filter(a => isAboveHeadroomFloor(computeHeadroom(a.rateLimit, family, now), this.headroomFloor));
             return aboveFloor.length > 0
-                ? pickMaxHeadroom(aboveFloor, family)
+                ? pickMaxHeadroom(aboveFloor, family, this.strategy === 'headroom-by-plan')
                 : pickFloorProbe(eligible, family, this.headroomFloor, now);
         }
         // No seat is eligible. A seat parked inside a live window is not
@@ -1287,10 +1308,10 @@ export class AccountPool {
                     return first;
             }
             if (!this.hardHeadroomFloor)
-                return pickMaxHeadroom(eligible, family);
+                return pickMaxHeadroom(eligible, family, this.strategy === 'headroom-by-plan');
             const aboveFloor = eligible.filter(a => isAboveHeadroomFloor(computeHeadroom(a.rateLimit, family, now), this.headroomFloor));
             return aboveFloor.length > 0
-                ? pickMaxHeadroom(aboveFloor, family)
+                ? pickMaxHeadroom(aboveFloor, family, this.strategy === 'headroom-by-plan')
                 : pickFloorProbe(eligible, family, this.headroomFloor, now);
         }
         // Mid-flight: the seats a 429 could still hand this request to. A seat

package/dist/proxy.d.ts

@@ -503,7 +503,10 @@ interface ProxyOptions {
     maxConcurrentPerConsumer?: number;
     /**
      * Max ms before the upstream fetch is aborted. Default 300000 (5 min,
-     * matching the Anthropic SDK). Injectable so tests can exercise the
+     * matching the Anthropic SDK). It caps the wait until the response
+     * streams; once a 2xx body is being read it is the longest allowed gap
+     * between two chunks, so a live stream is never cut. `--upstream-timeout`
+     * / `DARIO_UPSTREAM_TIMEOUT_MS`. Injectable so tests can exercise the
      * timeout → slot-release path without waiting 5 minutes (dario#905).
      */
     upstreamTimeoutMs?: number;
@@ -668,6 +671,16 @@ interface ProxyOptions {
      * a CLI flag, so the key never lands in `ps`/argv).
      */
     upstreamApiKey?: string;
+    /**
+     * The key behind a `credits:<model>` entry of `--pool-fallback`
+     * (credits-rung.ts): a Console API key of the organization a Max plan is
+     * linked to, spending the monthly API credits that plan includes. Used
+     * only when every seat is drained or cooling and no subscription rung can
+     * serve; the pool stays the first choice. Sourced from
+     * DARIO_CREDITS_API_KEY (env-only, like `upstreamApiKey`, so it never lands
+     * in argv). A chain entry without the key is inert and said so at startup.
+     */
+    creditsApiKey?: string;
     /**
      * Overage-guard — halt the proxy on the first response that bills to
      * anything other than the subscription pool (`overage`, `api`, or a new