nexus-agents 3.14.0 → 3.14.1

package/dist/{chunk-MHLXBATW.js → chunk-267ZPTK3.js}

@@ -1,15 +1,13 @@
 import {
   REJECTION_CATEGORIES,
-  UNATTRIBUTED_WORKSPACE,
   createSecureHandler,
   getToolAnnotations,
-  getToolFitnessLedger,
   getToolTimeout,
   toSdkCallback,
   toolStructuredError,
   toolSuccessStructured,
   wrapToolWithTimeout
-} from "./chunk-JTH44T6O.js";
+} from "./chunk-4FXWGQ6Q.js";
 import {
   JsonlStore,
   SECURITY_KEYWORDS,
@@ -31,7 +29,7 @@ import {
 import { execFile as execFile2 } from "child_process";
 import { readFile } from "fs/promises";
 import { promisify as promisify2 } from "util";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/mcp/middleware/tool-prerequisites.ts
 import { execFile } from "child_process";
@@ -895,6 +893,144 @@ function consolidationSignal(stat, family, busiestTool, busiestCount, windowLabe
   });
 }
 
+// src/governance/tool-fitness-ledger.ts
+import { z } from "zod";
+var ToolFitnessEventSchema = z.object({
+  /** Schema version. Forward-compat for on-disk evolution. */
+  v: z.literal(1),
+  /** ISO-8601 timestamp of the invocation. */
+  ts: z.iso.datetime(),
+  /** Tool identifier (e.g. the MCP tool name). */
+  tool: z.string().min(1).max(100),
+  /** Whether the invocation succeeded. Drives the success/failure correlation. */
+  success: z.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: z.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: z.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/tools/improvement-review-tool-fitness.ts
 function isHealthyInAnyOtherWorkspace(stat, statInWorkspace) {
   const realWorkspaces = stat.workspaces.filter((w) => w !== UNATTRIBUTED_WORKSPACE);
@@ -1125,7 +1261,7 @@ function improvementSignalsToTasks(signals, existingTaskIds) {
 }
 
 // src/mcp/tools/improvement-remediation-shadow.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/mcp/tools/diff-secret-scan.ts
 var SECRET_PATTERNS = [
@@ -1210,30 +1346,30 @@ function recordRemediationShadow(signals, sink = getRemediationShadowSink()) {
   for (const record of records) sink.record(record);
   return records;
 }
-var SoakVoteOutcomeSchema = z.object({
-  approved: z.boolean(),
+var SoakVoteOutcomeSchema = z2.object({
+  approved: z2.boolean(),
   /** Approval percentage at vote time, 0–100 (the consensus tally). */
-  approvalPercentage: z.number()
+  approvalPercentage: z2.number()
 });
-var RemediationSoakRecordSchema = z.object({
+var RemediationSoakRecordSchema = z2.object({
   /** ISO-8601 capture time. */
-  timestamp: z.string(),
+  timestamp: z2.string(),
   /** The improvement signal's stable key. */
-  signalKey: z.string(),
+  signalKey: z2.string(),
   /** The signal's category. */
-  category: z.string(),
+  category: z2.string(),
   /** The classified remediation priority (p0–p4). */
-  priority: z.string(),
+  priority: z2.string(),
   /** The signal's declared severity. */
-  severity: z.string(),
+  severity: z2.string(),
   /** Vote outcome (approved/rejected + tally), undefined if the signal never reached a vote. */
   voteOutcome: SoakVoteOutcomeSchema.optional(),
   /** Number of plan steps research produced (0 if research/plan failed). */
-  planStepCount: z.number(),
+  planStepCount: z2.number(),
   /** p0 dry-run result detail (scrubbed); undefined for non-p0 or when no dry-run ran. */
-  dryRunResult: z.string().optional(),
+  dryRunResult: z2.string().optional(),
   /** Human-readable verdict reason (scrubbed). */
-  reason: z.string()
+  reason: z2.string()
 });
 var SOAK_MAX_RECORDS = 1e4;
 function getRemediationSoakFile() {
@@ -1421,14 +1557,14 @@ function classifySignalPriority(signal) {
 
 // src/mcp/tools/improvement-review.ts
 var execFileAsync2 = promisify2(execFile2);
-var ImprovementReviewInputSchema = z2.object({
-  lookbackDays: z2.number().int().min(1).max(90).optional().default(7).describe("Lookback window for outcome data, in days. Default 7."),
-  fileIssues: z2.boolean().optional().default(false).describe(
+var ImprovementReviewInputSchema = z3.object({
+  lookbackDays: z3.number().int().min(1).max(90).optional().default(7).describe("Lookback window for outcome data, in days. Default 7."),
+  fileIssues: z3.boolean().optional().default(false).describe(
     "When true, file candidate issues via `gh issue create` for crossed thresholds (rate-limited to 5 per run, deduped against open issues). When false (default), return signals only."
   ),
-  minSampleSize: z2.number().int().min(1).max(1e3).optional().default(5).describe("Minimum sample size before a CLI/category signal can fire."),
-  fitnessFloor: z2.number().int().min(0).max(100).optional().default(90).describe("Fitness score below this threshold triggers a tech-debt signal."),
-  selfEvalReportPath: z2.string().optional().describe(
+  minSampleSize: z3.number().int().min(1).max(1e3).optional().default(5).describe("Minimum sample size before a CLI/category signal can fire."),
+  fitnessFloor: z3.number().int().min(0).max(100).optional().default(90).describe("Fitness score below this threshold triggers a tech-debt signal."),
+  selfEvalReportPath: z3.string().optional().describe(
     "Optional path to a self-eval JSON report (from `self-eval --json`). When set, high-confidence unanimous deprecate/refactor findings are surfaced as tech-debt signals through the same deduped/rate-limited issue path (#3224). Unreadable/malformed reports are skipped (no signal). Absent \u2192 no self-eval signals."
   )
 });
@@ -1707,14 +1843,14 @@ function detectFitnessSignals(audit, fitnessFloor) {
   return signals;
 }
 var SELF_EVAL_CONFIDENCE_FLOOR = 0.8;
-var SelfEvalReportSchema = z2.object({
-  results: z2.array(
-    z2.object({
-      component: z2.string(),
-      finalRecommendation: z2.string(),
-      confidence: z2.number(),
-      dissent: z2.array(z2.unknown()).optional().default([]),
-      evidenceQuality: z2.number().optional()
+var SelfEvalReportSchema = z3.object({
+  results: z3.array(
+    z3.object({
+      component: z3.string(),
+      finalRecommendation: z3.string(),
+      confidence: z3.number(),
+      dissent: z3.array(z3.unknown()).optional().default([]),
+      evidenceQuality: z3.number().optional()
     })
   )
 });
@@ -1937,13 +2073,13 @@ async function reviewHandler(args, ctx) {
 }
 var description = "Periodic threshold-gated observability-driven improvement loop. Reads OutcomeStore + fitness audit, surfaces patterns crossing documented thresholds as candidate findings. When fileIssues=true, files candidate GitHub issues via `gh issue create` (rate-limited to 5 per run, deduped against open issues). Never auto-merges. Replaces the deleted self-development engine (#2402).";
 var TOOL_INPUT_SCHEMA = {
-  lookbackDays: z2.number().int().min(1).max(90).optional().describe("Lookback window for outcome data, in days. Default 7."),
-  fileIssues: z2.boolean().optional().describe(
+  lookbackDays: z3.number().int().min(1).max(90).optional().describe("Lookback window for outcome data, in days. Default 7."),
+  fileIssues: z3.boolean().optional().describe(
     "When true, file candidate issues for crossed thresholds (default false \u2014 return signals only)"
   ),
-  minSampleSize: z2.number().int().min(1).max(1e3).optional().describe("Minimum sample size before a CLI/category signal fires (default 5)."),
-  fitnessFloor: z2.number().int().min(0).max(100).optional().describe("Fitness score below this threshold triggers a tech-debt signal (default 90)."),
-  selfEvalReportPath: z2.string().optional().describe(
+  minSampleSize: z3.number().int().min(1).max(1e3).optional().describe("Minimum sample size before a CLI/category signal fires (default 5)."),
+  fitnessFloor: z3.number().int().min(0).max(100).optional().describe("Fitness score below this threshold triggers a tech-debt signal (default 90)."),
+  selfEvalReportPath: z3.string().optional().describe(
     "Optional path to a self-eval JSON report. High-confidence unanimous deprecate/refactor findings surface as tech-debt signals (#3224)."
   )
 };
@@ -1996,4 +2132,4 @@ export {
   runImprovementReview,
   registerImprovementReviewTool
 };
-//# sourceMappingURL=chunk-MHLXBATW.js.map
+//# sourceMappingURL=chunk-267ZPTK3.js.map