nexus-agents 3.0.0 → 3.1.0

package/dist/{child-mcp-config-ZW5PFQEJ.js → child-mcp-config-IGZEHG37.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-YAF73ZMR.js";
 import {
   createLogger
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 import "./chunk-2HUC6NZN.js";
 import "./chunk-OQLFRJCW.js";
 import "./chunk-ZPWHCABL.js";
@@ -62,4 +62,4 @@ export {
   generateMcpConfig,
   getDefaultAllowedTools
 };
-//# sourceMappingURL=child-mcp-config-ZW5PFQEJ.js.map
+//# sourceMappingURL=child-mcp-config-IGZEHG37.js.map

package/dist/{chunk-BFDUELKY.js → chunk-25TDC2C4.js}

@@ -1,7 +1,7 @@
 import {
   getRandomProvider,
   getTimeProvider
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 
 // src/utils/id-utils.ts
 import { randomUUID } from "crypto";
@@ -24,4 +24,4 @@ export {
   generateHyphenId,
   generateUUID
 };
-//# sourceMappingURL=chunk-BFDUELKY.js.map
+//# sourceMappingURL=chunk-25TDC2C4.js.map

package/dist/{chunk-IKFUFHEG.js → chunk-2WRW3MWB.js}

@@ -9,11 +9,11 @@ import {
   gateWithReputation,
   resolveReputationGatingMode,
   sanitizeInput
-} from "./chunk-WSNUM6MS.js";
+} from "./chunk-TIQXKIIA.js";
 import {
   createLogger,
   getTimeProvider
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 
 // src/dogfooding/pr-reviewer-helpers.ts
 import { randomUUID } from "crypto";
@@ -288,4 +288,4 @@ export {
   formatReviewComment,
   createFailedReview
 };
-//# sourceMappingURL=chunk-IKFUFHEG.js.map
+//# sourceMappingURL=chunk-2WRW3MWB.js.map

package/dist/{chunk-7T5LHZLI.js → chunk-344IEWHJ.js}

@@ -1,6 +1,6 @@
 import {
   getDefaultRegistry
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 import {
   getNexusDataDir
 } from "./chunk-OQLFRJCW.js";
@@ -124,4 +124,4 @@ export {
   loadUsageEvents,
   rollupByModel
 };
-//# sourceMappingURL=chunk-7T5LHZLI.js.map
+//# sourceMappingURL=chunk-344IEWHJ.js.map

package/dist/{chunk-KDZCQPLH.js → chunk-43YJRZZW.js}

@@ -1,6 +1,6 @@
 import {
   getErrorMessage
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 
 // src/cli/setup-config.ts
 import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "fs";
@@ -77,4 +77,4 @@ function ensureBackup(outputPath) {
 export {
   runConfigInitSync
 };
-//# sourceMappingURL=chunk-KDZCQPLH.js.map
+//# sourceMappingURL=chunk-43YJRZZW.js.map

package/dist/{chunk-HHV6DOS4.js → chunk-47WSUCLS.js}

@@ -7,7 +7,7 @@ import {
   toolStructuredError,
   toolSuccessStructured,
   wrapToolWithTimeout
-} from "./chunk-3VRG7I7N.js";
+} from "./chunk-VV7KSMMR.js";
 import {
   JsonlStore,
   SECURITY_KEYWORDS,
@@ -19,7 +19,7 @@ import {
   getPipelineEventBus,
   getTimeProvider,
   isDeclaredNeverDeprecate
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 import {
   getNexusDataDir,
   nexusDataPath
@@ -2132,4 +2132,4 @@ export {
   runImprovementReview,
   registerImprovementReviewTool
 };
-//# sourceMappingURL=chunk-HHV6DOS4.js.map
+//# sourceMappingURL=chunk-47WSUCLS.js.map

package/dist/{chunk-4LLIXFC2.js → chunk-4AF6CP7P.js}

@@ -1,9 +1,9 @@
 import {
   createAutoAdapter
-} from "./chunk-NO6GYQAS.js";
+} from "./chunk-A5QBZ5EC.js";
 import {
   mapModelErrorToCategory
-} from "./chunk-JKGYQG6V.js";
+} from "./chunk-OKVCJFZM.js";
 import {
   CLI_NAMES,
   CircularBuffer,
@@ -21,7 +21,7 @@ import {
   ok,
   recordRateLimitEvent,
   toRateLimitError
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 
 // src/agents/collaboration/event-bus-helpers.ts
 import { randomUUID } from "crypto";
@@ -833,4 +833,4 @@ export {
   getGlobalRegistry,
   resetGlobalRegistry
 };
-//# sourceMappingURL=chunk-4LLIXFC2.js.map
+//# sourceMappingURL=chunk-4AF6CP7P.js.map

package/dist/{chunk-DYIDH4YE.js → chunk-4UN4M4NI.js}

@@ -1,6 +1,6 @@
 import {
   computeCostDetail
-} from "./chunk-7T5LHZLI.js";
+} from "./chunk-344IEWHJ.js";
 import {
   DEFAULT_CONSENSUS_CONFIG,
   DEFAULT_INCREMENTAL_QUORUM_CONFIG,
@@ -18,20 +18,20 @@ import {
   toolSuccess,
   withProgressHeartbeat,
   wrapToolWithTimeout
-} from "./chunk-3VRG7I7N.js";
+} from "./chunk-VV7KSMMR.js";
 import {
   createEvent,
   getGlobalRegistry
-} from "./chunk-4LLIXFC2.js";
+} from "./chunk-4AF6CP7P.js";
 import {
   getToolMemory
-} from "./chunk-4QAYK6FB.js";
+} from "./chunk-GTU2GK4H.js";
 import {
   authRemediation,
   delay,
   getAvailableClis,
   withTimeout
-} from "./chunk-NO6GYQAS.js";
+} from "./chunk-A5QBZ5EC.js";
 import {
   AgentError,
   CLI_NAMES,
@@ -60,7 +60,7 @@ import {
   resolveClassGuardMs,
   resolveModelIdentitySync,
   resolveVoteTimeout
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 import {
   ensureLearningDir,
   getOutcomesFile
@@ -5939,7 +5939,7 @@ async function processVotesWithCascade(engineVotes, opts) {
 var CONTRARIAN_ESCALATION_THRESHOLD = 0.8;
 async function runContrarianCheck(proposal, log) {
   try {
-    const { executeExpert } = await import("./expert-bridge-MMBE2ZPR.js");
+    const { executeExpert } = await import("./expert-bridge-NIYLN24L.js");
     const prompt = [
       "You are a contrarian analyst. Your job is to find reasons this proposal should be REJECTED.",
       "Look for: YAGNI (not needed), MISALIGNED (wrong tech/architecture), SECURITY_RISK, SCOPE_CREEP.",
@@ -6466,4 +6466,4 @@ export {
   CONSENSUS_VOTE_OUTPUT_SCHEMA,
   registerConsensusVoteTool
 };
-//# sourceMappingURL=chunk-DYIDH4YE.js.map
+//# sourceMappingURL=chunk-4UN4M4NI.js.map

package/dist/{chunk-NO6GYQAS.js → chunk-A5QBZ5EC.js}

@@ -5,34 +5,34 @@ import {
   planOptionalParams,
   requireApiKey,
   validateApiKeyPresence
-} from "./chunk-MCICMFFK.js";
+} from "./chunk-HEZ6VTMO.js";
 import {
   CUSTOM_API_DEFAULT_MODEL
-} from "./chunk-MHGARBUZ.js";
+} from "./chunk-NGFG5TIB.js";
 import {
   CUSTOM_API_BASE_URL_ENV,
   PROVIDER_ENV_KEYS,
   assertCustomApiHostResolvesPublic,
   validateCustomApiBaseUrl
-} from "./chunk-54MDYWNI.js";
+} from "./chunk-ZBTEOM3T.js";
 import {
   nexusMkdtempSync
 } from "./chunk-YAF73ZMR.js";
 import {
   getAvailabilityCache
-} from "./chunk-JHJV7CYZ.js";
+} from "./chunk-RHO52DBX.js";
 import {
   extractSystemPrompt
 } from "./chunk-QZUG667L.js";
 import {
   generateHyphenId
-} from "./chunk-BFDUELKY.js";
+} from "./chunk-25TDC2C4.js";
 import {
   CliCircuitBreaker,
   DEFAULT_CIRCUIT_BREAKER_CONFIG,
   getCliCircuitBreakerSnapshot,
   getDefaultCliCircuitBreakerRegistry
-} from "./chunk-JKGYQG6V.js";
+} from "./chunk-OKVCJFZM.js";
 import {
   CLI_SUBPROCESS_TIMEOUTS,
   CLI_TIMEOUTS,
@@ -69,7 +69,7 @@ import {
   ok,
   parseRetryAfterMs,
   resolveCliAlias
-} from "./chunk-UU6NLFCT.js";
+} from "./chunk-ATNHVLKJ.js";
 
 // src/cli-adapters/cli-to-model-adapter.ts
 var CliToModelAdapter = class {
@@ -4724,4 +4724,4 @@ export {
   SdkAdapter,
   createAutoAdapter
 };
-//# sourceMappingURL=chunk-NO6GYQAS.js.map
+//# sourceMappingURL=chunk-A5QBZ5EC.js.map

package/dist/{chunk-UU6NLFCT.js → chunk-ATNHVLKJ.js}

@@ -2623,7 +2623,7 @@ function setDefaultRegistry(registry) {
 }
 async function reloadDefaultRegistry() {
   globalRegistry = buildDefaultRegistry();
-  const { resetGlobalRegistry } = await import("./unified-registry-6YQEVB6A.js");
+  const { resetGlobalRegistry } = await import("./unified-registry-K4DRV5PF.js");
   resetGlobalRegistry();
   return globalRegistry;
 }
@@ -9120,6 +9120,172 @@ var KnnRoutingStage = class {
   }
 };
 
+// src/cli-adapters/routing/stages/capacity-stage.ts
+var CAPACITY_EXHAUSTED = "capacity_exhausted";
+var DEFAULT_CONFIG7 = {
+  enforceHardLimits: false,
+  probeTimeoutMs: 2e3
+};
+function assessCapacity(status) {
+  if (!status.observed) return "unmeasured";
+  if (status.exhausted || status.remainingTokens <= 0) return "exhausted";
+  return "healthy";
+}
+var CapacityFilterStage = class {
+  name = "capacity-filter";
+  /**
+   * Only consulted by `RoutingPipeline`. `CompositeRouter` hand-wires stages and
+   * takes call order from the body of `composite-router-stages.ts`, so this
+   * number does not position the stage there. Set adjacent to
+   * `BudgetFilterStage` (20) to keep the two hard filters together.
+   */
+  priority = 25;
+  adapters;
+  config;
+  logger;
+  excludedCount = 0;
+  unmeasuredCount = 0;
+  constructor(adapters, config = {}, logger15) {
+    this.adapters = adapters;
+    this.config = { ...DEFAULT_CONFIG7, ...config };
+    this.logger = logger15 ?? createLogger({ component: "CapacityFilterStage" });
+  }
+  canHandle(ctx) {
+    return getRemainingCandidates(ctx).length > 0;
+  }
+  async route(ctx) {
+    const time = getTimeProvider();
+    const startTime = time.now();
+    const remaining = getRemainingCandidates(ctx);
+    const assessments = await this.assessAll(remaining);
+    let updatedCtx = ctx;
+    let exhausted = 0;
+    let unmeasured = 0;
+    for (const [cli, assessment] of assessments) {
+      if (assessment === "unmeasured") {
+        unmeasured++;
+        continue;
+      }
+      if (assessment !== "exhausted") continue;
+      exhausted++;
+      if (this.config.enforceHardLimits) {
+        updatedCtx = filterCandidate(
+          updatedCtx,
+          cli,
+          `${CAPACITY_EXHAUSTED}: no capacity remaining`
+        );
+        this.excludedCount++;
+      }
+    }
+    this.unmeasuredCount += unmeasured;
+    const signals = this.buildSignals(ctx.signals, exhausted, unmeasured);
+    const eligible = getRemainingCandidates(updatedCtx);
+    const durationMs2 = time.now() - startTime;
+    const finalCtx = addTrace(
+      updatedCtx,
+      this.name,
+      durationMs2,
+      "filter",
+      `Eligible: ${String(eligible.length)}/${String(remaining.length)}, exhausted: ${String(exhausted)}, unmeasured: ${String(unmeasured)}`
+    );
+    this.logger.debug("Capacity filter complete", {
+      eligible: eligible.length,
+      exhausted,
+      unmeasured,
+      enforced: this.config.enforceHardLimits
+    });
+    return ok({
+      context: { ...finalCtx, signals },
+      continuesPipeline: eligible.length > 0
+    });
+  }
+  getStats() {
+    return { excludedCount: this.excludedCount, unmeasuredCount: this.unmeasuredCount };
+  }
+  /**
+   * Races a capacity probe against `probeTimeoutMs`.
+   *
+   * `ICliAdapter.getCapacity()` carries no timeout of its own, and the router's
+   * `maxDecisionTimeMs` is declared but not enforced anywhere, so without this a
+   * single hanging adapter would stall every routing decision. A timed-out probe
+   * rejects, which lands in the `unmeasured` branch — never `exhausted`.
+   */
+  async probeWithTimeout(adapter) {
+    let timer;
+    try {
+      return await Promise.race([
+        adapter.getCapacity(),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => {
+            reject(
+              new Error(`capacity probe timed out after ${String(this.config.probeTimeoutMs)}ms`)
+            );
+          }, this.config.probeTimeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
+  /**
+   * Reads capacity for every remaining candidate concurrently.
+   *
+   * A candidate with no registered adapter, whose probe rejects, or whose
+   * adapter does not implement `getCapacity` at all, is reported `unmeasured` —
+   * never excluded. Exclusion is destructive and a failed probe is an absence of
+   * evidence, not evidence of exhaustion.
+   *
+   * The callback is `async` deliberately. An adapter that does not implement
+   * `getCapacity` makes `adapter.getCapacity()` throw a TypeError *synchronously*
+   * inside `.map()`, which escapes `Promise.allSettled` entirely and would take
+   * down the whole routing call — turning a partially-implemented adapter into a
+   * total routing failure. An async callback converts that throw into a
+   * rejection, so it lands in the `unmeasured` branch like any other bad probe.
+   * `ICliAdapter` declares `getCapacity` as required, so only a structurally
+   * partial adapter reaches this path — which is exactly the case that must not
+   * be fatal.
+   */
+  async assessAll(candidates) {
+    const settled = await Promise.allSettled(
+      candidates.map(async (cli) => {
+        const adapter = this.adapters.get(cli);
+        if (adapter === void 0) throw new Error("no adapter registered");
+        return this.probeWithTimeout(adapter);
+      })
+    );
+    const result = /* @__PURE__ */ new Map();
+    for (const [idx, cli] of candidates.entries()) {
+      const outcome = settled[idx];
+      if (outcome?.status === "fulfilled") {
+        result.set(cli, assessCapacity(outcome.value));
+      } else {
+        this.logger.debug("Capacity probe unavailable \u2014 not excluding", { cli });
+        result.set(cli, "unmeasured");
+      }
+    }
+    return result;
+  }
+  /**
+   * Emits counts for both exhausted and unmeasured candidates.
+   *
+   * `capacity:unmeasured-N` lets a downstream consumer tell a genuinely healthy
+   * panel from one nobody has measured. It is emitted only when the count is
+   * non-zero — its *absence* therefore means every candidate was measured, which
+   * is the distinction that matters. (An earlier version of this comment claimed
+   * the signal was emitted at zero too; it never was.)
+   */
+  buildSignals(existing, exhausted, unmeasured) {
+    const signals = [...existing];
+    if (exhausted > 0) {
+      signals.push(`${CAPACITY_EXHAUSTED}:${String(exhausted)}`);
+    }
+    if (unmeasured > 0) {
+      signals.push(`capacity:unmeasured-${String(unmeasured)}`);
+    }
+    return signals;
+  }
+};
+
 // src/learning/strategy-distiller-types.ts
 var DEFAULT_DISTILLER_CONFIG = {
   triggerThreshold: 50,
@@ -10182,7 +10348,17 @@ var CompositeRouterConfigSchema = z12.object({
   linucbAlpha: z12.number().positive().default(1),
   /** Billing mode: 'plan' zeroes cost weight, 'api' preserves current behavior (default: 'plan') */
   billingMode: z12.enum(["plan", "api"]).default("plan"),
-  /** Enable capacity-aware load balancing (deprioritize exhausted CLIs) (default: true) (Issue #807) */
+  /**
+   * Enable capacity-aware routing exclusion — remove a candidate whose adapter
+   * reports *measurably* exhausted capacity (default: true) (#807, #4373).
+   *
+   * Declared for #807 but never read by any stage until #4373: for its whole
+   * life this flag defaulted to `true` while promising a behaviour that did not
+   * exist. It is reused rather than replaced by a new flag so there is one
+   * canonical switch for the concern. The wording changed from "deprioritize"
+   * to "exclude" to match #4351 criterion 3; nothing can depend on the former,
+   * since no deprioritization was ever implemented.
+   */
   enableCapacityBalancing: z12.boolean().default(true),
   /** Maximum routing decision time in ms (default: 50) */
   maxDecisionTimeMs: z12.number().positive().default(50),
@@ -10737,7 +10913,7 @@ function containsPromotionKeyword(text) {
 }
 
 // src/mcp/gateway/tier-recommender.ts
-var DEFAULT_CONFIG7 = {
+var DEFAULT_CONFIG8 = {
   minSamples: 20,
   promoteFailureRate: 0.3,
   demoteSuccessRate: 0.95,
@@ -10763,7 +10939,7 @@ function getCategoryTier(category) {
   return 2 /* ANALYZED */;
 }
 function generateTierRecommendations(summary, config) {
-  const cfg = { ...DEFAULT_CONFIG7, ...config };
+  const cfg = { ...DEFAULT_CONFIG8, ...config };
   const recommendations = [];
   for (const [category, stats] of summary.byCategory) {
     const rec = evaluateCategory(category, stats, cfg);
@@ -13037,6 +13213,39 @@ function runBudgetStage(task, candidates, stagesExecuted, deps) {
   }
   return ok({ candidates: result.eligible, withinBudget: result.withinBudget });
 }
+async function runCapacityStage(task, candidates, stagesExecuted, deps) {
+  if (!deps.config.enableCapacityBalancing || deps.capacityFilterStage === void 0) {
+    return ok(candidates);
+  }
+  const ctx = createRoutingContext(task.content, armsToSlots(candidates));
+  stagesExecuted.push("capacity-filter");
+  let result;
+  try {
+    result = await deps.capacityFilterStage.route(ctx);
+  } catch (error) {
+    deps.logger.debug("Capacity stage threw - keeping all candidates", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return ok(candidates);
+  }
+  if (!result.ok) {
+    deps.logger.debug("Capacity stage failed - keeping all candidates", {
+      error: result.error.message
+    });
+    return ok(candidates);
+  }
+  const eligible = keepArmsForSlots(candidates, getRemainingCandidates(result.value.context));
+  if (eligible.length === 0) {
+    const reasons = [...result.value.context.filtered.entries()].map(([cli, reason]) => `${cli} (${reason})`).join(", ");
+    return err(
+      new CompositeRoutingError(
+        `All routing candidates excluded \u2014 ${CAPACITY_EXHAUSTED}. Excluded: ${reasons}`,
+        "capacity-filter"
+      )
+    );
+  }
+  return ok(eligible);
+}
 var DEFAULT_COMPLEXITY = "moderate";
 function extractComplexityFromSignals(signals) {
   for (const s of signals) {
@@ -13468,6 +13677,9 @@ async function runPipeline(task, taskProfile, stagesExecuted, cliNames, deps) {
   if (!budgetResult.ok) return budgetResult;
   candidates = budgetResult.value.candidates;
   const withinBudget = budgetResult.value.withinBudget;
+  const capacityResult = await runCapacityStage(task, candidates, stagesExecuted, deps);
+  if (!capacityResult.ok) return capacityResult;
+  candidates = capacityResult.value;
   const scoring = await runScoringStages(task, candidates, stagesExecuted, deps);
   candidates = scoring.candidates;
   const constrained = await applyQualityConstraints(candidates, stagesExecuted, deps);
@@ -14192,6 +14404,8 @@ var CompositeRouter = class _CompositeRouter {
   qualityConstraintStage;
   /** Resource strategy stage instance (Issue #998) */
   resourceStrategyStage;
+  /** Capacity filter stage instance (#4373, #4351 criterion 3) */
+  capacityFilterStage;
   /** Distilled rule stage instance (Issue #999) */
   distilledRuleStage;
   /** KNN routing stage instance (arXiv:2505.12601) */
@@ -14317,6 +14531,9 @@ var CompositeRouter = class _CompositeRouter {
     if (this.config.enableResourceStrategy) {
       this.resourceStrategyStage = new ResourceStrategyStage(stageConfigs.resourceStrategy);
     }
+    if (this.config.enableCapacityBalancing) {
+      this.capacityFilterStage = new CapacityFilterStage(this.adapters, {}, this.logger);
+    }
     if (this.config.enableStrategyDistillation) {
       this.strategyDistiller = isPersistenceEnabled() ? createPersistentDistillerOrFallback(getOutcomeStore(), this.logger) : new StrategyDistiller(getOutcomeStore(), this.logger);
       this.distilledRuleStage = new DistilledRuleStage(
@@ -14410,7 +14627,7 @@ var CompositeRouter = class _CompositeRouter {
    */
   async consultUnifiedContext(task) {
     try {
-      const { getContextForTask, inferTaskCategory } = await import("./context-retriever-ZVFRYEDL.js");
+      const { getContextForTask, inferTaskCategory } = await import("./context-retriever-UDERFG2L.js");
       const ctx = await getContextForTask({
         task: task.content,
         category: inferTaskCategory(task.content),
@@ -14614,6 +14831,8 @@ var CompositeRouter = class _CompositeRouter {
       qualityConstraintStage: this.qualityConstraintStage,
       // Issue #998 resource strategy
       resourceStrategyStage: this.resourceStrategyStage,
+      // #4373 capacity exclusion
+      capacityFilterStage: this.capacityFilterStage,
       // Issue #999 distilled rule stage
       distilledRuleStage: this.distilledRuleStage,
       // arXiv:2505.12601 KNN routing
@@ -15992,4 +16211,4 @@ export {
   AgentCapability,
   OrchestratorError
 };
-//# sourceMappingURL=chunk-UU6NLFCT.js.map
+//# sourceMappingURL=chunk-ATNHVLKJ.js.map