dsh-subscriptions 0.3.0 → 0.3.1

package/lib/index.js

@@ -7819,22 +7819,29 @@ var PoolAdapter = class extends LlmAdapter {
 		throw this.exhaustedWithWarn(options.model, members, failures);
 	}
 	/**
-	* Order the candidates for one request. Health filters both strategies;
-	* `quota_aware` then ranks by urgency (members without telemetry, e.g.
-	* copilot, score zero and sink to the bottom of their class), while
-	* quota-exhausted members stay as a last-resort tail in pool order. The
-	* sticky member keeps its lead unless a challenger out-scores it by
-	* `switchMargin`.
+	* Order the candidates for one request. Health and known exhaustion filter
+	* both strategies: an applicable window at 100% must never become a paid
+	* fallback. `quota_aware` then ranks by urgency (members without telemetry,
+	* e.g. copilot, score zero and sink to the bottom of their class), while
+	* near-full members stay as a last-resort tail in urgency order. The sticky
+	* member keeps its lead unless a challenger out-scores it by `switchMargin`.
 	*/
 	async select(poolId, members, sessionId) {
 		const usable = members.filter((member) => this.options.adapters[member.provider] !== void 0 && this.options.health.isMemberAvailable(member.provider, member.account, member.model));
 		if (usable.length === 0) return [];
-		const stickyMember = sessionId === void 0 ? void 0 : usable.find((member) => memberKey(member.provider, member.account, member.model) === this.sticky.get(stickyKey(poolId, sessionId)));
-		if (this.options.strategy === "priority") return stickyMember === void 0 ? usable : [stickyMember, ...usable.filter((member) => member !== stickyMember)];
 		const quotas = new Map(await Promise.all(usable.map(async (member) => [member, await this.options.usage.quotaFor(member)])));
-		const scored = usable.filter((member) => quotas.get(member)?.available === true);
-		const quotaFull = usable.filter((member) => quotas.get(member)?.available === false);
+		const candidates = usable.filter((member) => quotas.get(member)?.exhausted !== true);
+		if (candidates.length === 0) {
+			const message = `${poolId}: all currently usable accounts have exhausted subscription quota; the request was stopped before spending paid credits. After an external reset, use Settings > Subscriptions > Refresh to re-check usage.`;
+			this.warnOnce(message);
+			throw new LlmError(message, QUOTA_EXCEEDED_CODE);
+		}
+		const stickyMember = sessionId === void 0 ? void 0 : candidates.find((member) => memberKey(member.provider, member.account, member.model) === this.sticky.get(stickyKey(poolId, sessionId)));
+		if (this.options.strategy === "priority") return stickyMember === void 0 ? candidates : [stickyMember, ...candidates.filter((member) => member !== stickyMember)];
+		const scored = candidates.filter((member) => quotas.get(member)?.available === true);
+		const quotaFull = candidates.filter((member) => quotas.get(member)?.available === false);
 		scored.sort((a, b) => (quotas.get(b)?.urgency ?? 0) - (quotas.get(a)?.urgency ?? 0));
+		quotaFull.sort((a, b) => (quotas.get(b)?.urgency ?? 0) - (quotas.get(a)?.urgency ?? 0));
 		if (stickyMember !== void 0 && scored.includes(stickyMember)) {
 			const best = scored[0];
 			const stickyUrgency = quotas.get(stickyMember)?.urgency ?? 0;
@@ -8254,21 +8261,19 @@ var PoolUsageTracker = class {
 	* (member selection must never block on the network mid-conversation). A
 	* failure still cooling down degrades immediately with no network call.
 	*
-	* Deliberately does NOT fall back to `lastSnapshot` the way
-	* {@link snapshotFor} does: scoring routing decisions off data that is
-	* known to be stale-and-unrefreshable risks steering traffic by a urgency
-	* number the endpoint itself is no longer vouching for, whereas
-	* `snapshotFor`'s stale-display concern (the Settings page, the composer
-	* badge) has no such downside — showing an old percentage beats showing
-	* nothing.
+	* A failed refresh does not reuse stale urgency for routing order, but it
+	* does retain a stale snapshot's known exhaustion bit. That one-way safety
+	* guard prevents a failed Settings refresh from re-enabling paid-credit
+	* fallback; an account with no successful usage sample still fails open.
 	* @param member - the pool member to score (account resolved).
-	* @returns availability plus the urgency score.
+	* @returns availability, known exhaustion, and the urgency score.
 	*/
 	async quotaFor(member) {
 		const key = `${member.provider}/${member.account}`;
 		const fetcher = this.fetcherFor(member.provider, member.account);
 		if (fetcher === void 0) return {
 			available: true,
+			exhausted: false,
 			urgency: 0,
 			fetchedAt: 0
 		};
@@ -8279,7 +8284,7 @@ var PoolUsageTracker = class {
 				if (!fresh) this.refresh(key, fetcher).catch(() => void 0);
 				return this.score(member, entry);
 			}
-			if (fresh) return degradedQuota(entry.error);
+			if (fresh) return this.degraded(member, entry.error, entry.lastSnapshot);
 		}
 		try {
 			const snapshot = await this.refresh(key, fetcher);
@@ -8288,7 +8293,8 @@ var PoolUsageTracker = class {
 				at: Date.now()
 			});
 		} catch (error) {
-			return degradedQuota(error);
+			const failed = this.entries.get(key);
+			return this.degraded(member, error, failed?.snapshot ?? failed?.lastSnapshot);
 		}
 	}
 	/**
@@ -8394,17 +8400,27 @@ var PoolUsageTracker = class {
 		}
 		return pending;
 	}
+	/** Degrade ordering while retaining only a cached safety exhaustion bit. */
+	degraded(member, error, snapshot) {
+		return degradedQuota(error, (snapshot === void 0 ? void 0 : this.score(member, {
+			snapshot,
+			at: 0
+		}))?.exhausted === true);
+	}
 	/** Score one member against a snapshot's windows. */
 	score(member, entry) {
 		const windows = (entry.snapshot.windows ?? []).filter((window) => windowApplies(window, member.model));
 		let available = true;
+		let exhausted = false;
 		let urgency = 0;
 		for (const window of windows) {
 			if (window.usedPercent >= QUOTA_FULL_PERCENT) available = false;
+			if (window.usedPercent >= 100) exhausted = true;
 			urgency = Math.max(urgency, windowUrgency(window));
 		}
 		return {
 			available,
+			exhausted,
 			urgency,
 			fetchedAt: entry.at
 		};
@@ -8412,17 +8428,14 @@ var PoolUsageTracker = class {
 };
 /**
 * The routing view of a fetch failure. Logged out: the member cannot serve
-* at all. Any other failure (network, endpoint rate limit) must not block
-* routing — the member stays available with a zero score, degrading the
-* strategy to plain priority order for it.
+* at all. Any other failure (network, endpoint rate limit) has a zero urgency;
+* without a successful sample it stays available, while known exhaustion
+* remains unavailable so stale telemetry cannot re-enable paid fallback.
 */
-function degradedQuota(error) {
-	return isMissingOrInvalidCredential(error) ? {
-		available: false,
-		urgency: 0,
-		fetchedAt: 0
-	} : {
-		available: true,
+function degradedQuota(error, exhausted = false) {
+	return {
+		available: !isMissingOrInvalidCredential(error) && !exhausted,
+		exhausted,
 		urgency: 0,
 		fetchedAt: 0
 	};

package/lib/providers/claude.d.ts

@@ -172,7 +172,9 @@ export declare const CLAUDE_REQUEST_IMAGE_BUDGET: number;
  * five-minute mark can still read an entry a one-hour mark wrote.
  * @returns the JSON body to POST.
  */
-export declare function claudeRequestBody(options: GenerateOptions, messages: readonly TranslatableMessage[], maxTokens: number, thinking?: Record<string, unknown>, effort?: string, cacheTtl?: PromptCacheTtl): Record<string, unknown>;
+export declare function claudeRequestBody(options: Omit<GenerateOptions, 'purpose'> & {
+    purpose?: string;
+}, messages: readonly TranslatableMessage[], maxTokens: number, thinking?: Record<string, unknown>, effort?: string, cacheTtl?: PromptCacheTtl): Record<string, unknown>;
 /** Claude wire adapter: one instance serves the `claude` provider route. */
 export declare class ClaudeAdapter extends LlmAdapter {
     private readonly options;

package/lib/providers/claude.js

@@ -580,8 +580,8 @@ const CLAUDE_MODALITIES = ['text', 'image'];
  * @returns the JSON body to POST.
  */
 export function claudeRequestBody(options, messages, maxTokens, thinking, effort, cacheTtl) {
-    // Read structurally so older host types need not declare `purpose`. Hosts
-    // that do not classify auxiliary calls follow the configured TTL.
+    // Auxiliary callers own this extension even when a host's GenerateOptions
+    // omits or reserves `purpose`; ordinary turns retain the configured TTL.
     const purpose = options.purpose;
     const ttl = purpose === undefined ? cacheTtl : undefined;
     const anthropicMessages = toAnthropicMessages(messages);

package/lib/providers/pool-usage.d.ts

@@ -19,8 +19,10 @@ export declare const QUOTA_FULL_PERCENT = 95;
 export declare const USAGE_TTL_MS: number;
 /** The scheduling view of one member's quota. */
 export interface MemberQuota {
-    /** False when a window is effectively full or the login is gone. */
+    /** Near-full gate: false at 95% or when the login is gone; may still serve as a fallback. */
     available: boolean;
+    /** True at 100%: never spend this member's subscription quota or paid fallback. */
+    exhausted: boolean;
     /** Required burn rate (fraction of window per ms); 0 when unknown. */
     urgency: number;
     /** Epoch ms of the snapshot this was computed from; 0 when none. */
@@ -51,15 +53,12 @@ export declare class PoolUsageTracker {
      * (member selection must never block on the network mid-conversation). A
      * failure still cooling down degrades immediately with no network call.
      *
-     * Deliberately does NOT fall back to `lastSnapshot` the way
-     * {@link snapshotFor} does: scoring routing decisions off data that is
-     * known to be stale-and-unrefreshable risks steering traffic by a urgency
-     * number the endpoint itself is no longer vouching for, whereas
-     * `snapshotFor`'s stale-display concern (the Settings page, the composer
-     * badge) has no such downside — showing an old percentage beats showing
-     * nothing.
+     * A failed refresh does not reuse stale urgency for routing order, but it
+     * does retain a stale snapshot's known exhaustion bit. That one-way safety
+     * guard prevents a failed Settings refresh from re-enabling paid-credit
+     * fallback; an account with no successful usage sample still fails open.
      * @param member - the pool member to score (account resolved).
-     * @returns availability plus the urgency score.
+     * @returns availability, known exhaustion, and the urgency score.
      */
     quotaFor(member: ConcretePoolMember): Promise<MemberQuota>;
     /**
@@ -93,6 +92,8 @@ export declare class PoolUsageTracker {
      * waiting out a stale cooldown.
      */
     private refresh;
+    /** Degrade ordering while retaining only a cached safety exhaustion bit. */
+    private degraded;
     /** Score one member against a snapshot's windows. */
     private score;
 }

package/lib/providers/pool-usage.js

@@ -49,21 +49,18 @@ export class PoolUsageTracker {
      * (member selection must never block on the network mid-conversation). A
      * failure still cooling down degrades immediately with no network call.
      *
-     * Deliberately does NOT fall back to `lastSnapshot` the way
-     * {@link snapshotFor} does: scoring routing decisions off data that is
-     * known to be stale-and-unrefreshable risks steering traffic by a urgency
-     * number the endpoint itself is no longer vouching for, whereas
-     * `snapshotFor`'s stale-display concern (the Settings page, the composer
-     * badge) has no such downside — showing an old percentage beats showing
-     * nothing.
+     * A failed refresh does not reuse stale urgency for routing order, but it
+     * does retain a stale snapshot's known exhaustion bit. That one-way safety
+     * guard prevents a failed Settings refresh from re-enabling paid-credit
+     * fallback; an account with no successful usage sample still fails open.
      * @param member - the pool member to score (account resolved).
-     * @returns availability plus the urgency score.
+     * @returns availability, known exhaustion, and the urgency score.
      */
     async quotaFor(member) {
         const key = `${member.provider}/${member.account}`;
         const fetcher = this.fetcherFor(member.provider, member.account);
         if (fetcher === undefined)
-            return { available: true, urgency: 0, fetchedAt: 0 };
+            return { available: true, exhausted: false, urgency: 0, fetchedAt: 0 };
         const entry = this.entries.get(key);
         if (entry !== undefined) {
             const fresh = Date.now() - entry.at < (entry.cooldownMs ?? this.ttlMs);
@@ -73,7 +70,7 @@ export class PoolUsageTracker {
                 return this.score(member, entry);
             }
             if (fresh)
-                return degradedQuota(entry.error);
+                return this.degraded(member, entry.error, entry.lastSnapshot);
             // The cooldown expired: fall through to a fresh, blocking attempt.
         }
         try {
@@ -81,7 +78,8 @@ export class PoolUsageTracker {
             return this.score(member, { snapshot, at: Date.now() });
         }
         catch (error) {
-            return degradedQuota(error);
+            const failed = this.entries.get(key);
+            return this.degraded(member, error, failed?.snapshot ?? failed?.lastSnapshot);
         }
     }
     /**
@@ -214,29 +212,42 @@ export class PoolUsageTracker {
         }
         return pending;
     }
+    /** Degrade ordering while retaining only a cached safety exhaustion bit. */
+    degraded(member, error, snapshot) {
+        const cached = snapshot === undefined
+            ? undefined
+            : this.score(member, { snapshot, at: 0 });
+        return degradedQuota(error, cached?.exhausted === true);
+    }
     /** Score one member against a snapshot's windows. */
     score(member, entry) {
         const windows = (entry.snapshot.windows ?? []).filter((window) => windowApplies(window, member.model));
         let available = true;
+        let exhausted = false;
         let urgency = 0;
         for (const window of windows) {
             if (window.usedPercent >= QUOTA_FULL_PERCENT)
                 available = false;
+            if (window.usedPercent >= 100)
+                exhausted = true;
             urgency = Math.max(urgency, windowUrgency(window));
         }
-        return { available, urgency, fetchedAt: entry.at };
+        return { available, exhausted, urgency, fetchedAt: entry.at };
     }
 }
 /**
  * The routing view of a fetch failure. Logged out: the member cannot serve
- * at all. Any other failure (network, endpoint rate limit) must not block
- * routing — the member stays available with a zero score, degrading the
- * strategy to plain priority order for it.
+ * at all. Any other failure (network, endpoint rate limit) has a zero urgency;
+ * without a successful sample it stays available, while known exhaustion
+ * remains unavailable so stale telemetry cannot re-enable paid fallback.
  */
-function degradedQuota(error) {
-    return isMissingOrInvalidCredential(error)
-        ? { available: false, urgency: 0, fetchedAt: 0 }
-        : { available: true, urgency: 0, fetchedAt: 0 };
+function degradedQuota(error, exhausted = false) {
+    return {
+        available: !isMissingOrInvalidCredential(error) && !exhausted,
+        exhausted,
+        urgency: 0,
+        fetchedAt: 0,
+    };
 }
 /** How long to hold a failure in the negative cache: the endpoint's own `retry-after`, or the default TTL. */
 function cooldownFor(error, defaultTtlMs) {

package/lib/providers/pool.d.ts

@@ -95,12 +95,12 @@ export declare class PoolAdapter extends LlmAdapter {
      */
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
     /**
-     * Order the candidates for one request. Health filters both strategies;
-     * `quota_aware` then ranks by urgency (members without telemetry, e.g.
-     * copilot, score zero and sink to the bottom of their class), while
-     * quota-exhausted members stay as a last-resort tail in pool order. The
-     * sticky member keeps its lead unless a challenger out-scores it by
-     * `switchMargin`.
+     * Order the candidates for one request. Health and known exhaustion filter
+     * both strategies: an applicable window at 100% must never become a paid
+     * fallback. `quota_aware` then ranks by urgency (members without telemetry,
+     * e.g. copilot, score zero and sink to the bottom of their class), while
+     * near-full members stay as a last-resort tail in urgency order. The sticky
+     * member keeps its lead unless a challenger out-scores it by `switchMargin`.
      */
     private select;
     /** Pin the serving member to the session (with bounded memory). */

package/lib/providers/pool.js

@@ -287,31 +287,43 @@ export class PoolAdapter extends LlmAdapter {
         throw this.exhaustedWithWarn(options.model, members, failures);
     }
     /**
-     * Order the candidates for one request. Health filters both strategies;
-     * `quota_aware` then ranks by urgency (members without telemetry, e.g.
-     * copilot, score zero and sink to the bottom of their class), while
-     * quota-exhausted members stay as a last-resort tail in pool order. The
-     * sticky member keeps its lead unless a challenger out-scores it by
-     * `switchMargin`.
+     * Order the candidates for one request. Health and known exhaustion filter
+     * both strategies: an applicable window at 100% must never become a paid
+     * fallback. `quota_aware` then ranks by urgency (members without telemetry,
+     * e.g. copilot, score zero and sink to the bottom of their class), while
+     * near-full members stay as a last-resort tail in urgency order. The sticky
+     * member keeps its lead unless a challenger out-scores it by `switchMargin`.
      */
     async select(poolId, members, sessionId) {
         const usable = members.filter((member) => this.options.adapters[member.provider] !== undefined &&
             this.options.health.isMemberAvailable(member.provider, member.account, member.model));
         if (usable.length === 0)
             return [];
+        const quotas = new Map(await Promise.all(usable.map(async (member) => [member, await this.options.usage.quotaFor(member)])));
+        const candidates = usable.filter((member) => quotas.get(member)?.exhausted !== true);
+        if (candidates.length === 0) {
+            const message = `${poolId}: all currently usable accounts have exhausted subscription quota; ` +
+                'the request was stopped before spending paid credits. After an external reset, ' +
+                'use Settings > Subscriptions > Refresh to re-check usage.';
+            this.warnOnce(message);
+            throw new LlmError(message, QUOTA_EXCEEDED_CODE);
+        }
         const stickyMember = sessionId === undefined
             ? undefined
-            : usable.find((member) => memberKey(member.provider, member.account, member.model) ===
+            : candidates.find((member) => memberKey(member.provider, member.account, member.model) ===
                 this.sticky.get(stickyKey(poolId, sessionId)));
         if (this.options.strategy === 'priority') {
             return stickyMember === undefined
-                ? usable
-                : [stickyMember, ...usable.filter((member) => member !== stickyMember)];
+                ? candidates
+                : [
+                    stickyMember,
+                    ...candidates.filter((member) => member !== stickyMember),
+                ];
         }
-        const quotas = new Map(await Promise.all(usable.map(async (member) => [member, await this.options.usage.quotaFor(member)])));
-        const scored = usable.filter((member) => quotas.get(member)?.available === true);
-        const quotaFull = usable.filter((member) => quotas.get(member)?.available === false);
+        const scored = candidates.filter((member) => quotas.get(member)?.available === true);
+        const quotaFull = candidates.filter((member) => quotas.get(member)?.available === false);
         scored.sort((a, b) => (quotas.get(b)?.urgency ?? 0) - (quotas.get(a)?.urgency ?? 0));
+        quotaFull.sort((a, b) => (quotas.get(b)?.urgency ?? 0) - (quotas.get(a)?.urgency ?? 0));
         if (stickyMember !== undefined && scored.includes(stickyMember)) {
             const best = scored[0];
             const stickyUrgency = quotas.get(stickyMember)?.urgency ?? 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-subscriptions",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Unified subscription providers and usage dashboard for DeepSeek Harness",
   "icon": "./icon.svg",
   "license": "MIT",