nexus-agents 3.13.4 → 3.14.0

package/dist/{chunk-GUDO6DBM.js → chunk-JTH44T6O.js}

@@ -3,6 +3,7 @@ import {
 } from "./chunk-M7BBFYO6.js";
 import {
   CACHE_TIMEOUTS,
+  JsonlStore,
   MCP_TIMEOUTS,
   SecurityError,
   TIMEOUT_GUARD,
@@ -18,7 +19,8 @@ import {
   resolveToolClassGuardMs
 } from "./chunk-APAOZHV5.js";
 import {
-  getNexusDataDir
+  getNexusDataDir,
+  nexusDataPath
 } from "./chunk-OQLFRJCW.js";
 
 // src/mcp/middleware/validation.ts
@@ -1019,6 +1021,144 @@ import { randomUUID } from "crypto";
 import { appendFileSync, existsSync, mkdirSync } from "fs";
 import { dirname, join } from "path";
 
+// src/governance/tool-fitness-ledger.ts
+import { z as z3 } from "zod";
+var ToolFitnessEventSchema = z3.object({
+  /** Schema version. Forward-compat for on-disk evolution. */
+  v: z3.literal(1),
+  /** ISO-8601 timestamp of the invocation. */
+  ts: z3.iso.datetime(),
+  /** Tool identifier (e.g. the MCP tool name). */
+  tool: z3.string().min(1).max(100),
+  /** Whether the invocation succeeded. Drives the success/failure correlation. */
+  success: z3.boolean(),
+  /**
+   * Cost of the invocation in arbitrary units (e.g. tokens), when the calling
+   * surface exposes it. Placeholder until full cost accounting lands with
+   * Epic G — absent (not zero) when unknown so aggregates don't conflate
+   * "free" with "unmeasured".
+   */
+  cost: z3.number().nonnegative().optional(),
+  /**
+   * OPTIONAL workspace/repo dimension (#3852 concern 1 — context-poisoning).
+   * The ledger is homedir-global, so a tool that fails only in ONE workspace
+   * (local perms, missing deps, repo-specific config) would otherwise aggregate
+   * into a single global fitness number and could wrongly flag a tool that is
+   * healthy everywhere else. Recording the originating workspace lets the
+   * consumer scope/weight fitness so a one-workspace failure doesn't get
+   * globally penalized. BACKWARD-COMPATIBLE: optional, absent on legacy events
+   * (treated as the unattributed/global bucket by the consumer).
+   */
+  workspace: z3.string().min(1).max(256).optional()
+});
+var UNATTRIBUTED_WORKSPACE = "(unattributed)";
+var DEFAULT_MAX_EVENTS = 5e4;
+var LEDGER_SUBDIR = "tool-fitness";
+var LEDGER_FILE = "ledger.jsonl";
+var ToolFitnessLedger = class {
+  store;
+  constructor(config) {
+    this.store = new JsonlStore({
+      filePath: config?.filePath ?? nexusDataPath(LEDGER_SUBDIR, LEDGER_FILE),
+      schema: ToolFitnessEventSchema,
+      maxRecords: config?.maxEvents ?? DEFAULT_MAX_EVENTS,
+      component: "ToolFitnessLedger"
+    });
+  }
+  /**
+   * Record one tool invocation. `v`/`ts` are stamped here so callers pass only
+   * the observed signal. Best-effort durability (inherited from JsonlStore):
+   * never throws into the observed operation.
+   */
+  record(event) {
+    const record = {
+      v: 1,
+      ts: event.ts ?? (/* @__PURE__ */ new Date()).toISOString(),
+      tool: event.tool,
+      success: event.success,
+      ...event.cost !== void 0 ? { cost: event.cost } : {},
+      ...event.workspace !== void 0 ? { workspace: event.workspace } : {}
+    };
+    this.store.append(record);
+  }
+  /** Total retained events across all tools. */
+  size() {
+    return this.store.count();
+  }
+  /**
+   * Aggregate stats for a single tool, or `undefined` when the tool has no
+   * recorded events (unknown tool / empty ledger). Pure over the current
+   * event set — no I/O.
+   */
+  statFor(tool) {
+    const events = this.store.all().filter((e) => e.tool === tool);
+    if (events.length === 0) return void 0;
+    return aggregate(tool, events);
+  }
+  /**
+   * Aggregate stats for a single tool RESTRICTED to one workspace (#3852
+   * concern 1 — context-poisoning). Pass {@link UNATTRIBUTED_WORKSPACE} to
+   * select the legacy/global bucket of events that carried no `workspace`.
+   * Returns `undefined` when the tool has no events in that workspace.
+   *
+   * This is the primitive that lets the consumer answer "is this tool low-fitness
+   * EVERYWHERE, or only in one repo?" so a single-workspace failure can't
+   * globally mis-flag a healthy tool.
+   */
+  statForInWorkspace(tool, workspace) {
+    const events = this.store.all().filter((e) => e.tool === tool && (e.workspace ?? UNATTRIBUTED_WORKSPACE) === workspace);
+    if (events.length === 0) return void 0;
+    return aggregate(tool, events);
+  }
+  /**
+   * Aggregate stats for every tool with at least one event, sorted by
+   * descending invocation count (most-used first) then tool name for a stable
+   * order. Returns `[]` for an empty ledger.
+   */
+  report() {
+    const byTool = /* @__PURE__ */ new Map();
+    for (const event of this.store.all()) {
+      const bucket = byTool.get(event.tool);
+      if (bucket === void 0) byTool.set(event.tool, [event]);
+      else bucket.push(event);
+    }
+    const stats = [];
+    for (const [tool, events] of byTool) {
+      stats.push(aggregate(tool, events));
+    }
+    stats.sort((a, b) => b.invocationCount - a.invocationCount || a.tool.localeCompare(b.tool));
+    return stats;
+  }
+};
+function aggregate(tool, events) {
+  let successCount = 0;
+  let lastUsedAt = "";
+  let totalCost;
+  const workspaces = /* @__PURE__ */ new Set();
+  for (const event of events) {
+    if (event.success) successCount++;
+    if (lastUsedAt === "" || Date.parse(event.ts) >= Date.parse(lastUsedAt)) lastUsedAt = event.ts;
+    if (event.cost !== void 0) totalCost = (totalCost ?? 0) + event.cost;
+    workspaces.add(event.workspace ?? UNATTRIBUTED_WORKSPACE);
+  }
+  const invocationCount = events.length;
+  return {
+    tool,
+    invocationCount,
+    successCount,
+    failureCount: invocationCount - successCount,
+    successRate: successCount / invocationCount,
+    lastUsedAt,
+    totalCost,
+    workspaces: [...workspaces].sort((a, b) => a.localeCompare(b))
+  };
+}
+var singleton;
+function getToolFitnessLedger() {
+  singleton ??= new ToolFitnessLedger();
+  return singleton;
+}
+
 // src/mcp/middleware/timeout-guard.ts
 var DEFAULT_TIMEOUT_MS = TIMEOUT_GUARD.defaultMs;
 var MAX_TIMEOUT_MS = TIMEOUT_GUARD.maxMs;
@@ -1599,10 +1739,27 @@ function createMiddlewareChain(config) {
       const requestContext = createRequestContext({ toolName: config.toolName });
       const requestLogger = logger.child(contextForLogging(requestContext));
       const ctx = { requestContext, logger: requestLogger };
-      return composed(args, ctx, (finalArgs, finalCtx) => handler(finalArgs, finalCtx));
+      try {
+        const result = await composed(
+          args,
+          ctx,
+          (finalArgs, finalCtx) => handler(finalArgs, finalCtx)
+        );
+        recordToolFitness(config.toolName, result.isError !== true);
+        return result;
+      } catch (error) {
+        recordToolFitness(config.toolName, false);
+        throw error;
+      }
     };
   };
 }
+function recordToolFitness(toolName, success) {
+  try {
+    getToolFitnessLedger().record({ tool: toolName, success });
+  } catch {
+  }
+}
 function withMiddleware(toolName, handler, options) {
   const config = {
     toolName,
@@ -1824,8 +1981,8 @@ function getToolAnnotations(name) {
 }
 
 // src/consensus/types-core.ts
-import { z as z3 } from "zod";
-var ConsensusAlgorithmSchema = z3.enum([
+import { z as z4 } from "zod";
+var ConsensusAlgorithmSchema = z4.enum([
   "simple_majority",
   "supermajority",
   "unanimous",
@@ -1833,8 +1990,8 @@ var ConsensusAlgorithmSchema = z3.enum([
   "opinion_wise",
   "higher_order"
 ]);
-var VoteDecisionSchema = z3.enum(["approve", "reject", "abstain"]);
-var ProposalStatusSchema = z3.enum([
+var VoteDecisionSchema = z4.enum(["approve", "reject", "abstain"]);
+var ProposalStatusSchema = z4.enum([
   "pending",
   "voting",
   "approved",
@@ -1842,7 +1999,7 @@ var ProposalStatusSchema = z3.enum([
   "timeout",
   "closed"
 ]);
-var RejectionCategorySchema = z3.enum([
+var RejectionCategorySchema = z4.enum([
   "YAGNI",
   "DRY_VIOLATION",
   "OVER_ENGINEERING",
@@ -1852,74 +2009,74 @@ var RejectionCategorySchema = z3.enum([
   "INSUFFICIENT_EVIDENCE"
 ]);
 var REJECTION_CATEGORIES = RejectionCategorySchema.options;
-var FindingShapeSchema = z3.object({
-  summary: z3.string().min(1).max(500),
-  location: z3.string().min(1).max(200),
-  severity: z3.enum(["critical", "high", "medium", "low"]).default("medium"),
-  gate: z3.object({
-    reread_cited_line: z3.enum(["passed", "failed", "skipped"]).default("skipped"),
-    traced_call_path: z3.enum(["passed", "failed", "skipped"]).default("skipped"),
-    named_assertion: z3.string().default(""),
-    ruled_out_language_non_issue: z3.enum(["passed", "failed", "skipped"]).default("skipped")
+var FindingShapeSchema = z4.object({
+  summary: z4.string().min(1).max(500),
+  location: z4.string().min(1).max(200),
+  severity: z4.enum(["critical", "high", "medium", "low"]).default("medium"),
+  gate: z4.object({
+    reread_cited_line: z4.enum(["passed", "failed", "skipped"]).default("skipped"),
+    traced_call_path: z4.enum(["passed", "failed", "skipped"]).default("skipped"),
+    named_assertion: z4.string().default(""),
+    ruled_out_language_non_issue: z4.enum(["passed", "failed", "skipped"]).default("skipped")
   }),
-  claim: z3.string().min(1).max(2e3)
+  claim: z4.string().min(1).max(2e3)
 });
-var VoteSchema = z3.object({
+var VoteSchema = z4.object({
   decision: VoteDecisionSchema,
-  reasoning: z3.string().min(1).describe("Explanation for the vote"),
-  confidence: z3.number().min(0).max(1).describe("Confidence level 0-1"),
-  conditions: z3.array(z3.string()).optional().describe("Conditions for approval"),
+  reasoning: z4.string().min(1).describe("Explanation for the vote"),
+  confidence: z4.number().min(0).max(1).describe("Confidence level 0-1"),
+  conditions: z4.array(z4.string()).optional().describe("Conditions for approval"),
   /** Structured rejection categories for reject→refine→re-vote loops (Issue #1213). */
-  rejectionCategories: z3.array(RejectionCategorySchema).optional().describe("Rejection reason categories when decision is reject"),
+  rejectionCategories: z4.array(RejectionCategorySchema).optional().describe("Rejection reason categories when decision is reject"),
   /** Pre-verified PR-review findings (#2245 v4 follow-up). Optional;
    * populated only when the voter emits the structured top-level array. */
-  findings: z3.array(FindingShapeSchema).optional().describe("PR-review findings (pre-verified)"),
+  findings: z4.array(FindingShapeSchema).optional().describe("PR-review findings (pre-verified)"),
   /** Which declared option this voter chose, when the proposal declared
    * `options` (#4472). Absent when the proposal declared none, or when the
    * voter's selection matched no declared option — an unmatched selection is
    * recorded as absent, never coerced onto a default. */
-  selectedOption: z3.string().optional().describe("Chosen option when the proposal declares options"),
-  timestamp: z3.iso.datetime().optional()
+  selectedOption: z4.string().optional().describe("Chosen option when the proposal declares options"),
+  timestamp: z4.iso.datetime().optional()
 });
-var ProposalSchema = z3.object({
-  id: z3.string().optional().describe("Auto-generated if not provided"),
-  title: z3.string().min(1).max(200).describe("Short proposal title"),
-  description: z3.string().min(1).describe("Detailed proposal description"),
+var ProposalSchema = z4.object({
+  id: z4.string().optional().describe("Auto-generated if not provided"),
+  title: z4.string().min(1).max(200).describe("Short proposal title"),
+  description: z4.string().min(1).describe("Detailed proposal description"),
   algorithm: ConsensusAlgorithmSchema,
-  timeout: z3.number().int().positive().optional().describe("Timeout in milliseconds"),
-  requiredVoters: z3.array(z3.string()).optional().describe("Agent IDs that must vote"),
-  metadata: z3.record(z3.string(), z3.unknown()).optional().describe("Additional context"),
-  createdAt: z3.iso.datetime().optional()
+  timeout: z4.number().int().positive().optional().describe("Timeout in milliseconds"),
+  requiredVoters: z4.array(z4.string()).optional().describe("Agent IDs that must vote"),
+  metadata: z4.record(z4.string(), z4.unknown()).optional().describe("Additional context"),
+  createdAt: z4.iso.datetime().optional()
 });
-var ConsensusResultSchema = z3.object({
-  proposalId: z3.string(),
+var ConsensusResultSchema = z4.object({
+  proposalId: z4.string(),
   proposal: ProposalSchema,
   outcome: ProposalStatusSchema,
-  votes: z3.map(z3.string(), VoteSchema),
-  voteCounts: z3.object({
-    approve: z3.number().int().nonnegative(),
-    reject: z3.number().int().nonnegative(),
-    abstain: z3.number().int().nonnegative(),
-    total: z3.number().int().nonnegative()
+  votes: z4.map(z4.string(), VoteSchema),
+  voteCounts: z4.object({
+    approve: z4.number().int().nonnegative(),
+    reject: z4.number().int().nonnegative(),
+    abstain: z4.number().int().nonnegative(),
+    total: z4.number().int().nonnegative()
   }),
-  weightedCounts: z3.object({
-    approve: z3.number().nonnegative(),
-    reject: z3.number().nonnegative(),
-    abstain: z3.number().nonnegative(),
-    totalWeight: z3.number().nonnegative()
+  weightedCounts: z4.object({
+    approve: z4.number().nonnegative(),
+    reject: z4.number().nonnegative(),
+    abstain: z4.number().nonnegative(),
+    totalWeight: z4.number().nonnegative()
   }).optional(),
-  approvalPercentage: z3.number().min(0).max(100),
-  quorumReached: z3.boolean(),
-  startedAt: z3.iso.datetime(),
-  closedAt: z3.iso.datetime(),
-  durationMs: z3.number().int().nonnegative()
+  approvalPercentage: z4.number().min(0).max(100),
+  quorumReached: z4.boolean(),
+  startedAt: z4.iso.datetime(),
+  closedAt: z4.iso.datetime(),
+  durationMs: z4.number().int().nonnegative()
 });
-var AgentPerformanceSchema = z3.object({
-  agentId: z3.string(),
-  totalVotes: z3.number().int().nonnegative(),
-  correctVotes: z3.number().int().nonnegative(),
-  successRate: z3.number().min(0).max(1),
-  lastUpdated: z3.iso.datetime()
+var AgentPerformanceSchema = z4.object({
+  agentId: z4.string(),
+  totalVotes: z4.number().int().nonnegative(),
+  correctVotes: z4.number().int().nonnegative(),
+  successRate: z4.number().min(0).max(1),
+  lastUpdated: z4.iso.datetime()
 });
 var DEFAULT_INCREMENTAL_QUORUM_CONFIG = {
   enabled: false,
@@ -1928,19 +2085,19 @@ var DEFAULT_INCREMENTAL_QUORUM_CONFIG = {
   confidenceThreshold: 0.6,
   ambiguityBand: 0.15
 };
-var ProposalCacheConfigSchema = z3.object({
-  enabled: z3.boolean().default(false),
-  ttlMs: z3.number().int().positive().default(36e5),
+var ProposalCacheConfigSchema = z4.object({
+  enabled: z4.boolean().default(false),
+  ttlMs: z4.number().int().positive().default(36e5),
   // 1 hour
-  maxEntries: z3.number().int().positive().default(500)
+  maxEntries: z4.number().int().positive().default(500)
 });
-var ConsensusEngineConfigSchema = z3.object({
-  defaultTimeout: z3.number().int().positive().default(3e5),
+var ConsensusEngineConfigSchema = z4.object({
+  defaultTimeout: z4.number().int().positive().default(3e5),
   // 5 minutes
-  minVotersForQuorum: z3.number().int().positive().default(2),
-  maxActiveProposals: z3.number().int().positive().default(100),
-  enablePerformanceTracking: z3.boolean().default(true),
-  maxClosedProposals: z3.number().int().positive().default(1e3),
+  minVotersForQuorum: z4.number().int().positive().default(2),
+  maxActiveProposals: z4.number().int().positive().default(100),
+  enablePerformanceTracking: z4.boolean().default(true),
+  maxClosedProposals: z4.number().int().positive().default(1e3),
   // Issue #549
   proposalCache: ProposalCacheConfigSchema.optional()
   // Issue #589
@@ -1966,14 +2123,14 @@ var VOTING_THRESHOLDS = {
   higher_order: 0.5
   // Alias for opinion_wise (Issue #514)
 };
-var ConsensusMetricsSchema = z3.object({
-  totalProposals: z3.number().int().nonnegative(),
-  approvedProposals: z3.number().int().nonnegative(),
-  rejectedProposals: z3.number().int().nonnegative(),
-  timedOutProposals: z3.number().int().nonnegative(),
-  averageDurationMs: z3.number().nonnegative(),
-  averageVotesPerProposal: z3.number().nonnegative(),
-  algorithmUsage: z3.record(ConsensusAlgorithmSchema, z3.number().int().nonnegative())
+var ConsensusMetricsSchema = z4.object({
+  totalProposals: z4.number().int().nonnegative(),
+  approvedProposals: z4.number().int().nonnegative(),
+  rejectedProposals: z4.number().int().nonnegative(),
+  timedOutProposals: z4.number().int().nonnegative(),
+  averageDurationMs: z4.number().nonnegative(),
+  averageVotesPerProposal: z4.number().nonnegative(),
+  algorithmUsage: z4.record(ConsensusAlgorithmSchema, z4.number().int().nonnegative())
 });
 
 export {
@@ -2001,6 +2158,8 @@ export {
   toolStructuredError,
   toolError,
   createSecureHandler,
+  UNATTRIBUTED_WORKSPACE,
+  getToolFitnessLedger,
   createMcpNotifier,
   NOOP_NOTIFIER,
   abortSignalStorage,
@@ -2028,4 +2187,4 @@ export {
   VOTING_THRESHOLDS,
   ConsensusMetricsSchema
 };
-//# sourceMappingURL=chunk-GUDO6DBM.js.map
+//# sourceMappingURL=chunk-JTH44T6O.js.map