@goodandready/dsh-key-rotation 0.8.87 → 0.8.88

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.8.88 (2026-11-03)
+
+### Subagent Concurrency Partitions & Task Isolation (Block 15 Release)
+- **Subagent Partitions Module (Issue #575)**: Introduced `src/subagent-partitions.js` to detect child tasks and background subagents (`extractSubagentContext`) and partition pool capacity (`partitionPoolKeys`).
+- **Primary Chat Immunity**: Protects main user conversations from rate limit spikes and concurrency starvation caused by parallel background tasks by reserving dedicated subagent keys (`subagentReservedKeysCount`) or applying isolated partitioning (`subagentPartitionStrategy: 'isolated' | 'shared-burst'`).
+- **Per-Key Subagent Concurrency Caps**: Implemented `subagentMaxConcurrencyPerKey` (default: 2) to cap parallel subagent calls per key, preventing sudden RPM/TPM exhaustion.
+- **Config & Schemastery Support**: Added `subagentPartitionsEnabled`, `subagentReservedKeysCount`, `subagentPartitionStrategy`, and `subagentMaxConcurrencyPerKey` across Schemastery configuration, pool builders, and TypeScript types.
+
 ## 0.8.87 (2026-11-03)
 
 ### Cache-Affinity Router for Hot Prompt Cache (Block 14 Release)

package/lib/index.js

@@ -146,6 +146,10 @@ const SettingsSchema = Schema.object({
   cacheAffinityEnabled: Schema.boolean().default(true),
   cacheAffinityTtlMs: Schema.number().default(300000),
   cacheAffinityPrefixChars: Schema.number().default(2048),
+  subagentPartitionsEnabled: Schema.boolean().default(true),
+  subagentReservedKeysCount: Schema.number().default(0),
+  subagentPartitionStrategy: Schema.union(['shared-burst', 'isolated']).default('shared-burst'),
+  subagentMaxConcurrencyPerKey: Schema.number().default(2),
   providers: Schema.array(Schema.object({
     provider: Schema.string().required(),
     keys: Schema.array(Schema.string()).default([]),
@@ -184,6 +188,10 @@ const SettingsSchema = Schema.object({
     cacheAffinityEnabled: Schema.boolean(),
     cacheAffinityTtlMs: Schema.number(),
     cacheAffinityPrefixChars: Schema.number(),
+    subagentPartitionsEnabled: Schema.boolean(),
+    subagentReservedKeysCount: Schema.number(),
+    subagentPartitionStrategy: Schema.union(['shared-burst', 'isolated']),
+    subagentMaxConcurrencyPerKey: Schema.number(),
   })).default([...DEFAULT_PROVIDERS]),
 });
 

package/lib/pool-builder.js

@@ -50,6 +50,10 @@ export function buildPoolItem({
   cacheAffinityEnabled = true,
   cacheAffinityTtlMs = 300000,
   cacheAffinityPrefixChars = 2048,
+  subagentPartitionsEnabled = true,
+  subagentReservedKeysCount = 0,
+  subagentPartitionStrategy = 'shared-burst',
+  subagentMaxConcurrencyPerKey = 2,
 }) {
   const seen = new Set();
   const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
@@ -169,6 +173,10 @@ const weightsMap = {};
     cacheAffinityEnabled: cacheAffinityEnabled ?? true,
     cacheAffinityTtlMs: typeof cacheAffinityTtlMs === 'number' && Number.isFinite(cacheAffinityTtlMs) && cacheAffinityTtlMs > 0 ? Math.floor(cacheAffinityTtlMs) : 300000,
     cacheAffinityPrefixChars: typeof cacheAffinityPrefixChars === 'number' && Number.isFinite(cacheAffinityPrefixChars) && cacheAffinityPrefixChars > 0 ? Math.floor(cacheAffinityPrefixChars) : 2048,
+    subagentPartitionsEnabled: subagentPartitionsEnabled ?? true,
+    subagentReservedKeysCount: typeof subagentReservedKeysCount === 'number' && Number.isFinite(subagentReservedKeysCount) && subagentReservedKeysCount >= 0 ? Math.floor(subagentReservedKeysCount) : 0,
+    subagentPartitionStrategy: subagentPartitionStrategy === 'isolated' ? 'isolated' : 'shared-burst',
+    subagentMaxConcurrencyPerKey: typeof subagentMaxConcurrencyPerKey === 'number' && Number.isFinite(subagentMaxConcurrencyPerKey) && subagentMaxConcurrencyPerKey > 0 ? Math.floor(subagentMaxConcurrencyPerKey) : 2,
     preemptiveRotationEnabled: preemptiveRotationEnabled ?? true,
     preemptiveSafetyMarginTokens: typeof preemptiveSafetyMarginTokens === 'number' && Number.isFinite(preemptiveSafetyMarginTokens) && preemptiveSafetyMarginTokens >= 0 ? Math.floor(preemptiveSafetyMarginTokens) : 4000,
     preemptiveSafetyMarginRequests: typeof preemptiveSafetyMarginRequests === 'number' && Number.isFinite(preemptiveSafetyMarginRequests) && preemptiveSafetyMarginRequests >= 0 ? Math.floor(preemptiveSafetyMarginRequests) : 2,
@@ -228,6 +236,10 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
       cacheAffinityEnabled: p.cacheAffinityEnabled ?? cfg.cacheAffinityEnabled ?? true,
       cacheAffinityTtlMs: p.cacheAffinityTtlMs ?? cfg.cacheAffinityTtlMs ?? 300000,
       cacheAffinityPrefixChars: p.cacheAffinityPrefixChars ?? cfg.cacheAffinityPrefixChars ?? 2048,
+      subagentPartitionsEnabled: p.subagentPartitionsEnabled ?? cfg.subagentPartitionsEnabled ?? true,
+      subagentReservedKeysCount: p.subagentReservedKeysCount ?? cfg.subagentReservedKeysCount ?? 0,
+      subagentPartitionStrategy: p.subagentPartitionStrategy ?? cfg.subagentPartitionStrategy ?? 'shared-burst',
+      subagentMaxConcurrencyPerKey: p.subagentMaxConcurrencyPerKey ?? cfg.subagentMaxConcurrencyPerKey ?? 2,
       preemptiveRotationEnabled: p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
       preemptiveSafetyMarginTokens: p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
       preemptiveSafetyMarginRequests: p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,
@@ -272,6 +284,10 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
         cacheAffinityEnabled: mp.cacheAffinityEnabled ?? p.cacheAffinityEnabled ?? cfg.cacheAffinityEnabled ?? true,
         cacheAffinityTtlMs: mp.cacheAffinityTtlMs ?? p.cacheAffinityTtlMs ?? cfg.cacheAffinityTtlMs ?? 300000,
         cacheAffinityPrefixChars: mp.cacheAffinityPrefixChars ?? p.cacheAffinityPrefixChars ?? cfg.cacheAffinityPrefixChars ?? 2048,
+        subagentPartitionsEnabled: mp.subagentPartitionsEnabled ?? p.subagentPartitionsEnabled ?? cfg.subagentPartitionsEnabled ?? true,
+        subagentReservedKeysCount: mp.subagentReservedKeysCount ?? p.subagentReservedKeysCount ?? cfg.subagentReservedKeysCount ?? 0,
+        subagentPartitionStrategy: mp.subagentPartitionStrategy ?? p.subagentPartitionStrategy ?? cfg.subagentPartitionStrategy ?? 'shared-burst',
+        subagentMaxConcurrencyPerKey: mp.subagentMaxConcurrencyPerKey ?? p.subagentMaxConcurrencyPerKey ?? cfg.subagentMaxConcurrencyPerKey ?? 2,
         preemptiveRotationEnabled: mp.preemptiveRotationEnabled ?? p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
         preemptiveSafetyMarginTokens: mp.preemptiveSafetyMarginTokens ?? p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
         preemptiveSafetyMarginRequests: mp.preemptiveSafetyMarginRequests ?? p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,

package/lib/resolver.js

@@ -13,6 +13,7 @@ import { envValue, sortAttemptList, isKeyPaused, isKeyRevoked, isKeyBroken, cost
 import { decryptSecret } from './crypto-storage.js';
 import { applyPreemptiveYield } from './preemptive-yield.js';
 import { extractPromptPrefixKey, applyCacheAffinity } from './cache-affinity.js';
+import { partitionPoolKeys } from './subagent-partitions.js';
 import { resolveRefPool, isQuotaManagedRequest, providerOfBase, basePoolForBase } from './pool-index.js';
 import {
   isModelQuotaAvailable,
@@ -139,6 +140,8 @@ export function createResolver({
     if (cacheKey) {
       list = applyCacheAffinity(list, pool, { cacheKey, now: Date.now() });
     }
+    // Issue #575: Subagent Concurrency Partitions
+    list = partitionPoolKeys(list, pool, { reqOptions: resolveOpts, concurrencyTracker, now: Date.now() });
     // Issue #571: Pre-emptive Token & Request Yield before 429
     list = applyPreemptiveYield(list, pool, { now: Date.now() });
     // Fail closed: when this request is managed by a model pool that has local

package/lib/rotate.js

@@ -29,6 +29,7 @@ import { recordStreamSuccessMetrics, preserveDispatchContext } from './stream-me
 import { withStreamWatchdog, StreamStallError } from './stream-watchdog.js';
 import { applyPreemptiveYield } from './preemptive-yield.js';
 import { extractPromptPrefixKey, applyCacheAffinity } from './cache-affinity.js';
+import { partitionPoolKeys } from './subagent-partitions.js';
 import { penalizeKey } from './rotate-penalty.js';
 import { recordPromptCache } from './prompt-cache.js';
 import { recordRequestOutcome, recordFailureCategory } from './ops-analytics.js';
@@ -210,6 +211,8 @@ export function createRotate(deps) {
       if (reqStore.cacheKey) {
         attemptList = applyCacheAffinity(attemptList, pool, { cacheKey: reqStore.cacheKey, now: wallNow, trace, pushEvent });
       }
+      // Issue #575: Subagent Concurrency Partitions
+      attemptList = partitionPoolKeys(attemptList, pool, { reqOptions: options, concurrencyTracker, now: wallNow, trace });
 
       // Issue #571: Pre-emptive Token & Request Yield before 429
       attemptList = applyPreemptiveYield(attemptList, pool, {

package/lib/subagent-partitions.js

@@ -0,0 +1,163 @@
+// src/subagent-partitions.js — Subagent Concurrency Partitions & Isolation (#575).
+// Pure module: zero runtime dependencies, strictly < 600 lines.
+
+export const DEFAULT_SUBAGENT_MAX_CONCURRENCY_PER_KEY = 2;
+
+/**
+ * Extracts subagent or background task context from request options and metadata.
+ * @param {object} options
+ * @returns {{ isSubagent: boolean, subagentId?: string, parentSessionId?: string }}
+ */
+export function extractSubagentContext(options) {
+  if (!options || typeof options !== 'object') return { isSubagent: false };
+  const meta = options.metadata || options.meta || {};
+  const parentSessionId = typeof meta.parentSessionId === 'string' && meta.parentSessionId.trim() ? meta.parentSessionId.trim() : undefined;
+
+  let isSubagent = false;
+  let subagentId = undefined;
+
+  if (options.isSubagent === true || meta.isSubagent === true) {
+    isSubagent = true;
+    subagentId = options.subagentId || meta.subagentId;
+  } else if (typeof options.subagentId === 'string' && options.subagentId.trim()) {
+    isSubagent = true;
+    subagentId = options.subagentId.trim();
+  } else if (typeof meta.subagentId === 'string' && meta.subagentId.trim()) {
+    isSubagent = true;
+    subagentId = meta.subagentId.trim();
+  } else if (typeof options.subagent === 'string' && options.subagent.trim()) {
+    isSubagent = true;
+    subagentId = options.subagent.trim();
+  } else if (options.subagent === true) {
+    isSubagent = true;
+  } else if (parentSessionId) {
+    isSubagent = true;
+    subagentId = meta.childSessionId;
+  } else {
+    // Check sessionId prefixes
+    const sid = String(options.sessionId || options.session || options.chatId || options.conversationId || '').trim();
+    if (
+      sid.startsWith('subagent:') ||
+      sid.startsWith('subagent-') ||
+      sid.startsWith('subtask:') ||
+      sid.startsWith('subtask-') ||
+      sid.startsWith('agent:sub:')
+    ) {
+      isSubagent = true;
+      subagentId = sid;
+    } else {
+      // Check tags
+      const tags = Array.isArray(options.tags) ? options.tags : (Array.isArray(meta.tags) ? meta.tags : []);
+      if (tags.some(t => typeof t === 'string' && (t === 'subagent' || t === 'subtask' || t === 'background'))) {
+        isSubagent = true;
+        subagentId = options.subagentId || meta.subagentId;
+      }
+    }
+  }
+
+  if (isSubagent) {
+    const res = { isSubagent: true };
+    if (subagentId) res.subagentId = subagentId;
+    if (parentSessionId) res.parentSessionId = parentSessionId;
+    return res;
+  }
+
+  return { isSubagent: false };
+}
+
+/**
+ * Partitions or reorders candidate keys according to subagent isolation rules.
+ * @param {string[]} attemptList
+ * @param {object} pool
+ * @param {object} [options]
+ * @returns {string[]}
+ */
+export function partitionPoolKeys(attemptList, pool, options = {}) {
+  if (!Array.isArray(attemptList) || attemptList.length <= 1 || !pool) {
+    return (attemptList ?? []).slice();
+  }
+
+  const enabled = options.enabled ?? pool.subagentPartitionsEnabled ?? true;
+  if (!enabled) return attemptList.slice();
+
+  const subCtx = options.subagentContext ?? extractSubagentContext(options.reqOptions);
+  const isSubagent = Boolean(subCtx.isSubagent);
+  const reservedCount = pool.subagentReservedKeysCount ?? 0;
+  const strategy = pool.subagentPartitionStrategy ?? 'shared-burst';
+  const labels = pool.labels || {};
+
+  const explicitSubagentRefs = new Set();
+  const explicitPrimaryRefs = new Set();
+
+  for (const [ref, label] of Object.entries(labels)) {
+    const lbl = String(label).toLowerCase();
+    if (lbl === 'subagent' || lbl === 'subtask' || lbl === 'worker') explicitSubagentRefs.add(ref);
+    if (lbl === 'primary' || lbl === 'main' || lbl === 'user') explicitPrimaryRefs.add(ref);
+  }
+
+  // If reservedCount > 0, reserve the last reservedCount keys of pool.refs if not already labelled primary
+  if (reservedCount > 0 && pool.refs && pool.refs.length > reservedCount) {
+    const reservedSlice = pool.refs.slice(pool.refs.length - reservedCount);
+    for (const r of reservedSlice) {
+      if (!explicitPrimaryRefs.has(r)) explicitSubagentRefs.add(r);
+    }
+  }
+
+  const hasPartitioning = explicitSubagentRefs.size > 0;
+  let list = attemptList.slice();
+
+  if (isSubagent) {
+    // SUBAGENT REQUEST
+    if (hasPartitioning) {
+      const dedicated = list.filter(r => explicitSubagentRefs.has(r));
+      const shared = list.filter(r => !explicitSubagentRefs.has(r));
+
+      if (strategy === 'isolated') {
+        if (dedicated.length > 0) list = dedicated;
+      } else {
+        list = dedicated.concat(shared);
+      }
+    }
+  } else {
+    // PRIMARY / USER REQUEST
+    if (hasPartitioning) {
+      const primary = list.filter(r => !explicitSubagentRefs.has(r));
+      const subOnly = list.filter(r => explicitSubagentRefs.has(r));
+
+      if (primary.length > 0) {
+        list = strategy === 'isolated' ? primary : primary.concat(subOnly);
+      }
+    }
+  }
+
+  // Apply subagent per-key concurrency cap
+  const tracker = options.concurrencyTracker;
+  const maxSubConcurrency = pool.subagentMaxConcurrencyPerKey ?? DEFAULT_SUBAGENT_MAX_CONCURRENCY_PER_KEY;
+  if (isSubagent && tracker && typeof tracker.getActive === 'function' && maxSubConcurrency > 0) {
+    const now = options.now ?? Date.now();
+    const withinCap = [];
+    const saturated = [];
+    for (const r of list) {
+      const active = tracker.getActive(r, now) ?? 0;
+      if (active >= maxSubConcurrency) {
+        saturated.push(r);
+      } else {
+        withinCap.push(r);
+      }
+    }
+    if (withinCap.length > 0 && saturated.length > 0) {
+      list = withinCap.concat(saturated);
+    }
+  }
+
+  if (options.trace && typeof options.trace.addStep === 'function' && list[0] !== attemptList[0]) {
+    options.trace.addStep(
+      list[0],
+      'PRIORITIZED',
+      'SUBAGENT_PARTITION',
+      isSubagent ? 'Subagent partition key allocated' : 'Primary chat partition prioritized'
+    );
+  }
+
+  return list;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.87",
+  "version": "0.8.88",
   "packageManager": "pnpm@10.33.2",
   "description": "Per-provider API key rotation for DeepSeek Harness: a key pool per provider, auto-created clone routes, and switching to the next key on quota/rate-limit errors. Includes a Settings section (Key Rotation) to edit the key pools, cooldown and switch codes.",
   "keywords": [