sigrank 0.0.178 → 0.0.180

package/tools/self-improve.mjs

@@ -0,0 +1,423 @@
+/**
+ * tools/self-improve.mjs — self_improve tool.
+ */
+
+import { cascade, parsePillars, detectMode, qualityScore, MODE_EXPECTED_YIELD } from "../analytics/cascade.mjs";
+import { computeBadges } from "../badges.mjs";
+import { CASCADE_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+import {
+  _pullDailyRows,
+  _compoundWeekly,
+  _modeDistribution,
+  _modeWeightedYield,
+  _peakYield,
+  _healthScore,
+  _yieldForDays,
+  _trajectory,
+  _phasePattern,
+  _dailyAssessment,
+  _dailyAdvice,
+} from "./_report.mjs";
+
+export const TOOL_DEF = {
+  name: "self_improve",
+  description:
+    "Runs the full self-improvement cycle in one call: (1) gets your current token pillars — either from the provided text or by running tokenpull on your local logs, (2) diagnoses where you're leaking efficiency (diagnose_cascade), (3) generates ranked improvement suggestions (suggest_improvements), (4) simulates the top suggestion (simulate_change), and (5) returns the complete cycle: diagnosis + suggestions + the simulated impact of the best change. This is the 'one-click optimize' tool — call it at the end of a session to see what to improve next time. If you provide pillars in `text`, it skips the tokenpull step. If you omit `text`, it runs tokenpull first (requires local ccusage logs). Pure local math — no network, no submission. The `scope` parameter adds mode detection (BUILD/EDIT/DEBUG/MAINTAIN/IDLE) and scoped analysis: 'daily' (default — current behavior + mode), 'weekly' (compound into weekly snapshots + report artifact), 'trend' (30d/90d trajectory analysis).",
+  annotations: {
+    title: "Self-improve plan",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      text: {
+        type: "string",
+        description:
+          'Optional: token pillars — ccusage JSON or "input output cacheCreate cacheRead". If omitted, runs tokenpull to get current pillars from local logs.',
+      },
+      window: {
+        type: "string",
+        enum: ["7d", "30d", "90d", "all"],
+        description:
+          "Which time window to pull when running tokenpull (default: 30d). Ignored if `text` is provided.",
+      },
+      scope: {
+        type: "string",
+        enum: ["daily", "weekly", "trend"],
+        description:
+          'Analysis scope: "daily" (default — current behavior + mode detection), "weekly" (compound daily rows into weekly snapshots + report artifact with badges), "trend" (30d/90d trajectory + phase patterns). Daily modes never leave the machine — only weekly distribution goes in submitted reports.',
+      },
+    },
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      pillars: {
+        type: "object",
+        description: "The 4 raw token pillars used",
+      },
+      current_cascade: CASCADE_OUTPUT,
+      diagnosis: {
+        type: "array",
+        description: "Efficiency leaks found (from diagnose_cascade)",
+      },
+      suggestions: {
+        type: "array",
+        description: "Ranked improvements (from suggest_improvements)",
+      },
+      best_simulation: {
+        type: "object",
+        description: "Simulated result of the top suggestion",
+      },
+      cycle_summary: {
+        type: "string",
+        description: "One-line summary of the full cycle",
+      },
+      // Scope-specific fields
+      mode: {
+        type: "object",
+        description:
+          "Detected mode { mode, confidence } — present when scope is daily/weekly/trend",
+      },
+      quality_score: {
+        type: "number",
+        description: "Yield relative to mode expectation (daily scope)",
+      },
+      assessment: {
+        type: "string",
+        description: "One-line assessment for daily scope",
+      },
+      advice: {
+        type: "string",
+        description: "Advice for next session (daily scope)",
+      },
+      report: {
+        type: "object",
+        description: "Weekly report artifact (weekly scope)",
+      },
+      trend: { type: "object", description: "Trend analysis (trend scope)" },
+    },
+  },
+};
+
+export async function handleSelfImprove(args, ctx) {
+  // The full self-improvement cycle: pull → diagnose → suggest → simulate.
+  // If text is provided, use it as pillars. If not, run tokenpull first.
+  let pillars;
+  let pulledFrom = "provided";
+
+  if (args?.text) {
+    if (typeof args.text === "string" && args.text.length > MAX_INPUT) {
+      return {
+        status: "error",
+        reason: "input_too_large",
+        detail: `text exceeds ${MAX_INPUT} chars.`,
+      };
+    }
+    pillars = parsePillars(args.text);
+  } else {
+    // Run tokenpull to get current pillars from local logs
+    const windowType = args?.window || "30d";
+    try {
+      const pullResult = await ctx.callTool(
+        "tokenpull",
+        { window: windowType },
+      );
+      if (pullResult?.status === "error" || !pullResult?.windows?.length) {
+        return {
+          status: "error",
+          reason: "tokenpull_failed",
+          detail:
+            "Could not pull pillars from local logs. Provide pillars via `text` argument instead.",
+          pull_result: pullResult,
+        };
+      }
+      // Use the first window's pillars
+      const w = pullResult.windows[0];
+      pillars = w.pillars;
+      pulledFrom = `tokenpull ${w.window || windowType}`;
+    } catch (e) {
+      return {
+        status: "error",
+        reason: "tokenpull_error",
+        detail: String(e.message || e),
+        hint: "Provide pillars via `text` argument instead.",
+      };
+    }
+  }
+
+  const currentResult = withParseWarnings(pillars, cascade(pillars));
+  const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = pillars;
+
+  // ── Step 1: Diagnose ──────────────────────────────────────────────
+  const diagnosis = [];
+  const leverage = currentResult.leverage;
+  if (leverage !== null && leverage < 10) {
+    diagnosis.push({
+      metric: "cache_leverage",
+      severity: "critical",
+      finding: `Cache leverage is ${leverage}× — TRANSMITTER-class operators hit 200×+.`,
+      recommendation:
+        "Increase context reuse: load prior session context, use longer threads.",
+    });
+  } else if (leverage !== null && leverage < 50) {
+    diagnosis.push({
+      metric: "cache_leverage",
+      severity: "warning",
+      finding: `Cache leverage is ${leverage}× — below ARCH+ threshold (~100×+).`,
+      recommendation: "Push cache reads higher by reusing prior context.",
+    });
+  }
+
+  const velocity = currentResult.velocity;
+  if (velocity !== null && velocity < 0.5) {
+    diagnosis.push({
+      metric: "velocity",
+      severity: "critical",
+      finding: `Velocity is ${velocity} — generating only ${velocity}× input as output.`,
+      recommendation: "Increase output per turn, reduce over-reading.",
+    });
+  } else if (velocity !== null && velocity < 1.0) {
+    diagnosis.push({
+      metric: "velocity",
+      severity: "warning",
+      finding: `Velocity is ${velocity} — below 1.0. Healthy operators hit 1.5×+.`,
+      recommendation: "Generate more output per input token.",
+    });
+  }
+
+  if (currentResult.dev10x === null && cw === 0) {
+    diagnosis.push({
+      metric: "10xdev",
+      severity: "critical",
+      finding: "No cache creation — cascade cannot compound.",
+      recommendation:
+        "Switch to a platform with prompt caching (Claude Code).",
+    });
+  }
+
+  const total = i + o + cw + cr;
+  if (total > 0 && (i / total) * 100 > 10) {
+    diagnosis.push({
+      metric: "input_bloat",
+      severity: "warning",
+      finding: `Fresh input is ${((i / total) * 100).toFixed(1)}% of total flow — efficient operators keep it under 1%.`,
+      recommendation: "Reduce fresh input by reusing prior context.",
+    });
+  }
+
+  // ── Step 2: Suggest (generate + simulate candidates) ──────────────
+  const candidates = [];
+  // If cacheRead is 0, suggest absolute amounts instead of percentage boosts
+  const crBoosts = cr > 0 ? [1.5, 2, 3, 5] : [];
+  for (const mult of crBoosts) {
+    const sim = cascade({ ...pillars, cacheRead: Math.round(cr * mult) });
+    if (sim.yield !== null)
+      candidates.push({
+        action: `Increase cache reads by ${Math.round((mult - 1) * 100)}%`,
+        pillar: "cacheRead",
+        delta: `+${Math.round(cr * (mult - 1)).toLocaleString()}`,
+        simulated_yield: sim.yield,
+        yield_delta: Number(
+          (sim.yield - (currentResult.yield ?? 0)).toFixed(2),
+        ),
+        class_after: sim.class,
+        rationale: "Cache reads are the strongest Υ multiplier.",
+      });
+  }
+  // For zero-cache operators, suggest enabling caching with a starter amount
+  if (cr === 0 && cw === 0) {
+    const starterAmounts = [
+      Math.round(i * 10),
+      Math.round(i * 50),
+      Math.round(i * 100),
+    ];
+    for (const amt of starterAmounts) {
+      const sim = cascade({
+        ...pillars,
+        cacheCreate: Math.round(amt * 0.5),
+        cacheRead: amt,
+      });
+      if (sim.yield !== null && sim.yield > 0)
+        candidates.push({
+          action: `Enable caching with ${amt.toLocaleString()} cache reads`,
+          pillar: "cacheRead",
+          delta: `+${amt.toLocaleString()}`,
+          simulated_yield: sim.yield,
+          yield_delta: Number(
+            (sim.yield - (currentResult.yield ?? 0)).toFixed(2),
+          ),
+          class_after: sim.class,
+          rationale:
+            "You have no cache — enabling it unlocks the cascade. Start by reusing prior context.",
+        });
+    }
+  }
+  for (const mult of [0.9, 0.75, 0.5]) {
+    const newInput = Math.round(i * mult);
+    if (newInput < 1) continue;
+    const sim = cascade({ ...pillars, input: newInput });
+    if (sim.yield !== null)
+      candidates.push({
+        action: `Reduce fresh input by ${Math.round((1 - mult) * 100)}%`,
+        pillar: "input",
+        delta: `-${Math.round(i * (1 - mult)).toLocaleString()}`,
+        simulated_yield: sim.yield,
+        yield_delta: Number(
+          (sim.yield - (currentResult.yield ?? 0)).toFixed(2),
+        ),
+        class_after: sim.class,
+        rationale: "Input is squared in Υ denominator — quadratic payoff.",
+      });
+  }
+  for (const mult of [1.25, 1.5, 2]) {
+    const sim = cascade({ ...pillars, output: Math.round(o * mult) });
+    if (sim.yield !== null)
+      candidates.push({
+        action: `Increase output by ${Math.round((mult - 1) * 100)}%`,
+        pillar: "output",
+        delta: `+${Math.round(o * (mult - 1)).toLocaleString()}`,
+        simulated_yield: sim.yield,
+        yield_delta: Number(
+          (sim.yield - (currentResult.yield ?? 0)).toFixed(2),
+        ),
+        class_after: sim.class,
+        rationale: "Output is a linear multiplier in Υ.",
+      });
+  }
+  candidates.sort((a, b) => b.yield_delta - a.yield_delta);
+  const suggestions = candidates
+    .slice(0, 8)
+    .map((c, idx) => ({ rank: idx + 1, ...c }));
+
+  // ── Step 3: Simulate the top suggestion ───────────────────────────
+  const best = suggestions[0];
+  let bestSimulation = null;
+  if (best) {
+    const simPillars = { ...pillars };
+    const delta = parseInt(best.delta.replace(/[+\-,]/g, ""), 10);
+    if (best.pillar === "cacheRead") simPillars.cacheRead = cr + delta;
+    else if (best.pillar === "input")
+      simPillars.input = Math.max(i - delta, 1);
+    else if (best.pillar === "output") simPillars.output = o + delta;
+    const simResult = cascade(simPillars);
+    bestSimulation = {
+      action: best.action,
+      current_yield: currentResult.yield,
+      simulated_yield: simResult.yield,
+      yield_delta: best.yield_delta,
+      current_class: currentResult.class,
+      simulated_class: simResult.class,
+      class_changed: currentResult.class !== simResult.class,
+    };
+  }
+
+  // ── Step 4: Cycle summary ─────────────────────────────────────────
+  const criticalCount = diagnosis.filter(
+    (d) => d.severity === "critical",
+  ).length;
+  const cycleSummary = best
+    ? `Pulled from ${pulledFrom}. Υ ${currentResult.yield} (${currentResult.class}). ${criticalCount} critical, ${diagnosis.length - criticalCount} other findings. Best: ${best.action} → Υ ${best.simulated_yield} (+${best.yield_delta}).`
+    : `Pulled from ${pulledFrom}. Υ ${currentResult.yield} (${currentResult.class}). ${diagnosis.length} findings. No improvements suggested — cascade is optimized.`;
+
+  // ── Step 5: Scope-specific analysis ───────────────────────────────
+  const scope = args?.scope || "daily";
+  const modeInfo = currentResult.mode; // { mode, confidence }
+  const scopeResult = {};
+
+  if (scope === "daily") {
+    // Daily: mode + quality score + assessment + advice
+    const qs = qualityScore(currentResult.yield ?? 0, modeInfo.mode);
+    const expected = MODE_EXPECTED_YIELD[modeInfo.mode] ?? 0;
+    const assessment = _dailyAssessment(
+      modeInfo.mode,
+      currentResult.yield,
+      qs,
+      expected,
+    );
+    const advice = _dailyAdvice(modeInfo.mode, currentResult.yield, qs);
+    scopeResult.mode = modeInfo;
+    scopeResult.quality_score = Math.round(qs * 100) / 100;
+    scopeResult.assessment = assessment;
+    scopeResult.advice = advice;
+  }
+
+  if (scope === "weekly" || scope === "trend") {
+    // Pull daily rows from ccusage to build weekly snapshots
+    const dailyRows = await _pullDailyRows(ctx.opts);
+    const weeklySnapshots = _compoundWeekly(dailyRows);
+    const modeDistribution = _modeDistribution(weeklySnapshots);
+    const modeWeightedYield = _modeWeightedYield(weeklySnapshots);
+
+    // Compute badges
+    const historyForBadges = weeklySnapshots.map((w) => ({
+      date: w.weekStart,
+      mode: w.mode,
+      yield: w.yield,
+      pillars: w.pillars,
+    }));
+    const badges = computeBadges({
+      pillars,
+      cascade: currentResult,
+      history: historyForBadges,
+      isVerified: false, // set by submit_verified
+      rank: null, // server-side
+    });
+
+    if (scope === "weekly") {
+      scopeResult.mode = modeInfo;
+      // Strip dailyModes from weekly_snapshots — privacy boundary (daily modes never leave the machine)
+      const safeSnapshots = weeklySnapshots.map(
+        ({ dailyModes, ...rest }) => rest,
+      );
+      scopeResult.report = {
+        current_mode: modeInfo.mode,
+        mode_confidence: modeInfo.confidence,
+        mode_distribution: modeDistribution,
+        mode_weighted_yield: modeWeightedYield,
+        peak_yield: _peakYield(weeklySnapshots),
+        health_score: _healthScore(weeklySnapshots, modeWeightedYield),
+        weekly_snapshots: safeSnapshots,
+        badges,
+      };
+    }
+
+    if (scope === "trend") {
+      const yield7d = _yieldForDays(weeklySnapshots, 7);
+      const yield30d = _yieldForDays(weeklySnapshots, 30);
+      const yield90d = _yieldForDays(weeklySnapshots, 90);
+      const trajectory = _trajectory(yield7d, yield30d, yield90d);
+      scopeResult.mode = modeInfo;
+      scopeResult.trend = {
+        yield_7d: yield7d,
+        yield_30d: yield30d,
+        yield_90d: yield90d,
+        trajectory,
+        mode_distribution: modeDistribution,
+        phase_pattern: _phasePattern(weeklySnapshots),
+      };
+    }
+  }
+
+  return {
+    pillars,
+    current_cascade: {
+      yield_: currentResult.yield,
+      snr: currentResult.snr,
+      leverage: currentResult.leverage,
+      velocity: currentResult.velocity,
+      tenx_dev: currentResult.dev10x,
+      class: currentResult.class,
+      mode: modeInfo,
+      warnings: currentResult.warnings,
+    },
+    diagnosis,
+    suggestions,
+    best_simulation: bestSimulation,
+    cycle_summary: cycleSummary,
+    ...scopeResult,
+  };
+}

package/tools/simulate-change.mjs

@@ -0,0 +1,207 @@
+/**
+ * tools/simulate-change.mjs — simulate_change tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { SIMULATE_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+
+export const TOOL_DEF = {
+  name: "simulate_change",
+  description:
+    "The first PRESCRIPTIVE SigRank tool — 'what if I changed my token mix?' Takes your current 4 pillars (input/output/cacheCreate/cacheRead) and one or more proposed changes, runs the canonical cascade on BOTH the current and simulated values, and returns the exact Υ Yield delta, class change, and per-metric diffs. This is the 'show me the payoff before I do the work' primitive: no network, no submission, pure local math. Use it to answer 'would increasing my cache-read by 50k tokens actually move my class?' before you change your workflow. Accepts the current pillars as JSON or 4 numbers (same as rank_paste) plus a `changes` object with any of the 4 pillar names mapped to new absolute values OR relative deltas (e.g. {cacheRead: '+50000'} or {input: 800000}).",
+  annotations: {
+    title: "Simulate metric change",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      text: {
+        type: "string",
+        description:
+          'Current token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).',
+      },
+      changes: {
+        type: "object",
+        description:
+          "Proposed changes to apply. Keys: input, output, cacheCreate, cacheRead. Values are either absolute numbers (replace) or strings starting with +/- for relative deltas (add/subtract). Omitted pillars are unchanged.",
+        properties: {
+          input: {
+            type: ["number", "string"],
+            description:
+              'new input token count (absolute) or "+/-N" for a relative delta',
+          },
+          output: {
+            type: ["number", "string"],
+            description:
+              'new output token count (absolute) or "+/-N" for a relative delta',
+          },
+          cacheCreate: {
+            type: ["number", "string"],
+            description:
+              'new cache-create token count (absolute) or "+/-N" for a relative delta',
+          },
+          cacheRead: {
+            type: ["number", "string"],
+            description:
+              'new cache-read token count (absolute) or "+/-N" for a relative delta',
+          },
+        },
+      },
+    },
+    required: ["text", "changes"],
+  },
+  outputSchema: SIMULATE_OUTPUT,
+};
+
+export async function handleSimulateChange(args) {
+  // The first prescriptive tool — "what if I changed my token mix?"
+  // Pure local math: parse current pillars, apply proposed changes, run the
+  // cascade on both, return the delta. No network, no submission.
+  if (!args?.text)
+    throw new Error(
+      "simulate_change requires a non-empty `text` argument (current pillars).",
+    );
+  if (typeof args.text === "string" && args.text.length > MAX_INPUT) {
+    return {
+      status: "error",
+      reason: "input_too_large",
+      detail: `text exceeds ${MAX_INPUT} chars.`,
+    };
+  }
+  if (!args?.changes || typeof args.changes !== "object") {
+    throw new Error(
+      "simulate_change requires a `changes` object with at least one pillar change.",
+    );
+  }
+
+  const currentPillars = parsePillars(args.text);
+  const current = withParseWarnings(currentPillars, cascade(currentPillars));
+
+  // Apply changes: each pillar is either an absolute number (replace) or a
+  // string starting with +/- (relative delta). Omitted pillars are unchanged.
+  const PILLAR_KEYS = ["input", "output", "cacheCreate", "cacheRead"];
+  const simulated = { ...currentPillars };
+  const appliedChanges = {};
+
+  for (const key of PILLAR_KEYS) {
+    if (args.changes[key] == null) continue;
+    const raw = args.changes[key];
+    let newVal;
+
+    if (typeof raw === "number") {
+      newVal = raw;
+    } else if (typeof raw === "string") {
+      const trimmed = raw.trim();
+      if (trimmed.startsWith("+") || trimmed.startsWith("-")) {
+        // Relative delta: add/subtract from current value
+        const delta = Number(trimmed);
+        if (!Number.isFinite(delta)) {
+          return {
+            status: "error",
+            reason: "invalid_change",
+            detail: `changes.${key}: "${raw}" is not a valid relative delta.`,
+          };
+        }
+        newVal = currentPillars[key] + delta;
+      } else {
+        // Absolute value as a string
+        newVal = Number(trimmed);
+      }
+    } else {
+      return {
+        status: "error",
+        reason: "invalid_change",
+        detail: `changes.${key}: expected number or string, got ${typeof raw}.`,
+      };
+    }
+
+    if (!Number.isFinite(newVal)) {
+      return {
+        status: "error",
+        reason: "invalid_change",
+        detail: `changes.${key}: result is not a finite number.`,
+      };
+    }
+    // Clamp to non-negative — token counts can't be negative
+    if (newVal < 0) {
+      return {
+        status: "error",
+        reason: "invalid_change",
+        detail: `changes.${key}: result ${newVal} is negative — token counts must be >= 0.`,
+      };
+    }
+
+    simulated[key] = newVal;
+    appliedChanges[key] = {
+      from: currentPillars[key],
+      to: newVal,
+      delta: newVal - currentPillars[key],
+    };
+  }
+
+  if (Object.keys(appliedChanges).length === 0) {
+    return {
+      status: "error",
+      reason: "no_changes",
+      detail: "No pillar changes specified in the `changes` object.",
+    };
+  }
+
+  const simulatedResult = cascade(simulated);
+
+  // Compute deltas for every cascade metric
+  const metricDelta = (curr, sim) => {
+    if (curr == null && sim == null) return null;
+    if (curr == null) return { from: null, to: sim, delta: null };
+    if (sim == null) return { from: curr, to: null, delta: null };
+    return { from: curr, to: sim, delta: Number((sim - curr).toFixed(4)) };
+  };
+
+  const classChanged = current.class !== simulatedResult.class;
+
+  return {
+    current: {
+      pillars: currentPillars,
+      yield: current.yield,
+      snr: current.snr,
+      leverage: current.leverage,
+      velocity: current.velocity,
+      dev10x: current.dev10x,
+      class: current.class,
+    },
+    simulated: {
+      pillars: {
+        input: simulated.input,
+        output: simulated.output,
+        cacheCreate: simulated.cacheCreate,
+        cacheRead: simulated.cacheRead,
+      },
+      yield: simulatedResult.yield,
+      snr: simulatedResult.snr,
+      leverage: simulatedResult.leverage,
+      velocity: simulatedResult.velocity,
+      dev10x: simulatedResult.dev10x,
+      class: simulatedResult.class,
+    },
+    changes: appliedChanges,
+    deltas: {
+      yield: metricDelta(current.yield, simulatedResult.yield),
+      snr: metricDelta(current.snr, simulatedResult.snr),
+      leverage: metricDelta(current.leverage, simulatedResult.leverage),
+      velocity: metricDelta(current.velocity, simulatedResult.velocity),
+      dev10x: metricDelta(current.dev10x, simulatedResult.dev10x),
+    },
+    class_changed: classChanged,
+    ...(classChanged
+      ? { class_transition: `${current.class} → ${simulatedResult.class}` }
+      : {}),
+    ...(simulatedResult.warnings
+      ? { simulated_warnings: simulatedResult.warnings }
+      : {}),
+    note: "Local simulation only — no submission. The actual score depends on server-side RS.xx weights and class thresholds.",
+  };
+}