sigrank 0.0.178 → 0.0.179

package/tools/_schemas.mjs

@@ -0,0 +1,394 @@
+/**
+ * tools/_schemas.mjs — MCP tool annotation + input/output schema objects.
+ */
+
+// Smithery quality: output schemas + annotations
+// MCP tool annotations hint to clients about side-effects, read-only status, etc.
+export const ANNOTATIONS = {
+  readOnlyHint: { readOnlyHint: true },
+  destructiveHint: { destructiveHint: false },
+  idempotentHint: { idempotentHint: true },
+  openWorldHint: { openWorldHint: false },
+};
+
+// Common output schema for cascade results (rank_paste, simulate_change, etc.)
+export const CASCADE_OUTPUT = {
+  type: "object",
+  properties: {
+    yield_: {
+      type: "number",
+      description:
+        "Υ Yield — the headline efficiency metric (Cache Reads × Output / Input²)",
+    },
+    snr: { type: "number", description: "Signal-to-noise ratio" },
+    leverage: {
+      type: "number",
+      description: "Cr/I — cache reads divided by input",
+    },
+    velocity: { type: "number", description: "O/I — output divided by input" },
+    tenx_dev: { type: "number", description: "10xDEV score" },
+    class: {
+      type: "string",
+      enum: ["Burner", "Builder", "10xer"],
+      description: "Operator class tier",
+    },
+    card: {
+      type: "string",
+      description: "Deterministic prose summary of the cascade result",
+    },
+    warnings: {
+      type: "array",
+      items: { type: "string" },
+      description: "Parse or data warnings if any",
+    },
+  },
+  required: ["yield_", "class"],
+};
+
+export const LEADERBOARD_OUTPUT = {
+  type: "object",
+  properties: {
+    operators: {
+      type: "array",
+      description: "Array of ranked operators sorted by yield",
+      items: {
+        type: "object",
+        properties: {
+          codename: { type: "string", description: "Public display name" },
+          yield_: { type: "number", description: "Υ Yield metric" },
+          leverage: { type: "number", description: "Cr/I ratio" },
+          velocity: { type: "number", description: "O/I ratio" },
+          class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+          rank: { type: "integer", description: "1-based rank position" },
+        },
+      },
+    },
+  },
+};
+
+export const OPERATOR_OUTPUT = {
+  type: "object",
+  properties: {
+    codename: { type: "string", description: "Operator display name" },
+    yield_: { type: "number", description: "Υ Yield metric" },
+    leverage: { type: "number", description: "Cr/I ratio" },
+    velocity: { type: "number", description: "O/I ratio" },
+    class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+    rank: { type: "integer", description: "1-based rank position" },
+    windows: {
+      type: "array",
+      description: "Per-window breakdowns (7d, 30d, 90d, all-time)",
+      items: {
+        type: "object",
+        properties: {
+          window: { type: "string", enum: ["7d", "30d", "90d", "all_time"] },
+          pillars: {
+            type: "object",
+            properties: {
+              input: { type: "integer" },
+              output: { type: "integer" },
+              cacheCreate: { type: "integer" },
+              cacheRead: { type: "integer" },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+export const BEST_OPERATOR_OUTPUT = {
+  type: "object",
+  properties: {
+    top_operators: {
+      type: "array",
+      description: "Top N operators ranked by yield",
+      items: {
+        type: "object",
+        properties: {
+          codename: { type: "string", description: "Public display name" },
+          yield_: { type: "number", description: "Υ Yield metric" },
+          leverage: { type: "number", description: "Cr/I ratio" },
+          velocity: { type: "number", description: "O/I ratio" },
+          class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+          rank: { type: "integer", description: "1-based rank position" },
+          behavioral_framing: {
+            type: "string",
+            description: "Plain-language interpretation of the operator's cascade in power-user terms",
+          },
+        },
+      },
+    },
+    total_operators: { type: "integer", description: "Total operators on the board" },
+    summary: {
+      type: "string",
+      description: "One-line summary of the top operator's achievement in behavioral terms",
+    },
+  },
+};
+
+export const COMPARE_SELF_OUTPUT = {
+  type: "object",
+  properties: {
+    your_metrics: {
+      type: "object",
+      description: "Your cascade metrics",
+      properties: {
+        codename: { type: "string" },
+        yield_: { type: "number", description: "Υ Yield metric" },
+        leverage: { type: "number", description: "Cr/I ratio" },
+        velocity: { type: "number", description: "O/I ratio" },
+        class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        rank: { type: "integer", description: "1-based rank position" },
+      },
+    },
+    power_user_assessment: {
+      type: "string",
+      description: "Behavioral interpretation: are you an AI power user? Maps class tier to power-user language.",
+    },
+    comparison: {
+      type: "object",
+      description: "How you compare to board averages and archetypes",
+      properties: {
+        your_yield_vs_avg: { type: "string", description: "Your yield vs board average" },
+        your_class_meaning: { type: "string", description: "What your class tier means in power-user terms" },
+        percentile: { type: "number", description: "Your percentile rank (0-100)" },
+      },
+    },
+    suggestion: {
+      type: "string",
+      description: "One actionable suggestion to improve your cascade efficiency",
+    },
+  },
+};
+
+export const COMPARE_OPERATORS_OUTPUT = {
+  type: "object",
+  properties: {
+    operator_a: {
+      type: "object",
+      description: "First operator's metrics",
+      properties: {
+        codename: { type: "string" },
+        yield_: { type: "number" },
+        leverage: { type: "number" },
+        velocity: { type: "number" },
+        class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        rank: { type: "integer" },
+      },
+    },
+    operator_b: {
+      type: "object",
+      description: "Second operator's metrics",
+      properties: {
+        codename: { type: "string" },
+        yield_: { type: "number" },
+        leverage: { type: "number" },
+        velocity: { type: "number" },
+        class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        rank: { type: "integer" },
+      },
+    },
+    verdict: {
+      type: "string",
+      description: "Who is more efficient and why, in behavioral terms",
+    },
+    yield_delta: { type: "number", description: "Yield difference (A - B)" },
+  },
+};
+
+export const SUBMIT_OUTPUT = {
+  type: "object",
+  properties: {
+    status: {
+      type: "string",
+      enum: ["ok", "error", "skipped"],
+      description: "Submission status",
+    },
+    preview: CASCADE_OUTPUT,
+    server_response: {
+      type: "object",
+      description: "Server-side response including new rank if accepted",
+    },
+    reason: {
+      type: "string",
+      description: "Error or skip reason if status is not ok",
+    },
+  },
+};
+
+export const TOKENPULL_OUTPUT = {
+  type: "object",
+  properties: {
+    platform: { type: "string", description: "Source platform name" },
+    generatedAt: { type: "string", description: "ISO timestamp of the pull" },
+    windows: {
+      type: "array",
+      description: "Per-window token usage + cascade results",
+      items: {
+        type: "object",
+        properties: {
+          window: { type: "string", enum: ["7d", "30d", "90d", "all"] },
+          pillars: {
+            type: "object",
+            properties: {
+              input: { type: "integer" },
+              output: { type: "integer" },
+              cacheCreate: { type: "integer" },
+              cacheRead: { type: "integer" },
+            },
+          },
+          messages: {
+            type: "integer",
+            description: "Number of messages in window",
+          },
+          estimated: {
+            type: "boolean",
+            description: "True if cacheCreate was estimated",
+          },
+          cascade: CASCADE_OUTPUT,
+        },
+      },
+    },
+  },
+};
+
+export const ENROLL_OUTPUT = {
+  type: "object",
+  properties: {
+    status: {
+      type: "string",
+      enum: ["enrolled", "error"],
+      description: "Enrollment result",
+    },
+    codename: { type: "string", description: "Operator codename if enrolled" },
+    operator_id: { type: "string", description: "Operator ID if enrolled" },
+    device_id: { type: "string", description: "Local device ID" },
+    trust_status: { type: "string", description: "Trust level of the device" },
+    reason: { type: "string", description: "Error reason if status is error" },
+  },
+};
+
+export const COMPARE_OUTPUT = {
+  type: "object",
+  properties: {
+    platform: { type: "string" },
+    sources: {
+      type: "array",
+      description: "Side-by-side comparison of each token source",
+      items: {
+        type: "object",
+        properties: {
+          source: {
+            type: "string",
+            description:
+              "Source name (tokenpull, ccusage, token-dash, tokscale)",
+          },
+          pillars: { type: "object" },
+          cascade: CASCADE_OUTPUT,
+          delta_pct: {
+            type: "object",
+            description: "Delta % vs tokenpull baseline",
+          },
+        },
+      },
+    },
+  },
+};
+
+export const SIMULATE_OUTPUT = {
+  type: "object",
+  properties: {
+    current: CASCADE_OUTPUT,
+    simulated: CASCADE_OUTPUT,
+    yield_delta: {
+      type: "number",
+      description: "Υ Yield change (simulated - current)",
+    },
+    class_change: {
+      type: "string",
+      description: "Class tier change description",
+    },
+    metric_diffs: {
+      type: "object",
+      description: "Per-metric before/after diffs",
+    },
+  },
+};
+
+export const DIAGNOSE_OUTPUT = {
+  type: "object",
+  properties: {
+    pillars: { type: "object", description: "The 4 raw token pillars" },
+    cascade: CASCADE_OUTPUT,
+    diagnosis: {
+      type: "array",
+      description: "Ranked list of efficiency leaks found, worst first",
+      items: {
+        type: "object",
+        properties: {
+          metric: {
+            type: "string",
+            description: "Which metric is underperforming",
+          },
+          severity: {
+            type: "string",
+            enum: ["critical", "warning", "info"],
+            description: "How bad the leak is",
+          },
+          finding: { type: "string", description: "What the analysis found" },
+          recommendation: {
+            type: "string",
+            description: "What to do about it",
+          },
+          estimated_yield_impact: {
+            type: "string",
+            description: "Estimated Υ improvement if fixed",
+          },
+        },
+      },
+    },
+    summary: {
+      type: "string",
+      description: "One-line summary of the operator's cascade health",
+    },
+  },
+};
+
+export const SUGGEST_OUTPUT = {
+  type: "object",
+  properties: {
+    suggestions: {
+      type: "array",
+      description: "Ranked recommendations, highest Υ impact first",
+      items: {
+        type: "object",
+        properties: {
+          rank: { type: "number", description: "1-based rank by Υ impact" },
+          action: { type: "string", description: "What to change" },
+          pillar: { type: "string", description: "Which pillar to adjust" },
+          delta: { type: "string", description: "How much to change it" },
+          simulated_yield: {
+            type: "number",
+            description: "Projected Υ after the change",
+          },
+          yield_delta: { type: "number", description: "Υ change vs current" },
+          class_after: {
+            type: "string",
+            description: "Projected class after the change",
+          },
+          rationale: { type: "string", description: "Why this helps" },
+        },
+      },
+    },
+    current_yield: {
+      type: "number",
+      description: "Current Υ before any changes",
+    },
+    current_class: { type: "string", description: "Current class tier" },
+    best_single_change: {
+      type: "string",
+      description: "The single highest-impact change",
+    },
+  },
+};

package/tools/_verifiers.mjs

@@ -0,0 +1,148 @@
+/**
+ * tools/_verifiers.mjs — on-device verifier readers for tokenpull_compare.
+ *
+ * Mirrors the implementations in presentation/cli.mjs + presentation/tui.mjs
+ * without circular imports. Used by the tokenpull_compare tool for quick
+ * side-by-side comparison across local token sources.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileAsync } from "./_helpers.mjs";
+
+async function _ccusagePillars(platform = "claude") {
+  try {
+    const raw = await execFileAsync(
+      "ccusage",
+      [platform, "daily", "--json"],
+      15000,
+    );
+    const rows = JSON.parse(raw)?.daily ?? JSON.parse(raw);
+    const now = Date.now();
+    const result = {};
+    for (const [win, days] of Object.entries({
+      "7d": 7,
+      "30d": 30,
+      "90d": 90,
+    })) {
+      const since = new Date(now - days * 86400000);
+      let i = 0,
+        o = 0,
+        cw = 0,
+        cr = 0;
+      for (const r of rows) {
+        if (new Date(r.date ?? r.day ?? "1970") >= since) {
+          i += r.inputTokens ?? r.input_tokens ?? 0;
+          o += r.outputTokens ?? r.output_tokens ?? 0;
+          cw += r.cacheCreationTokens ?? r.cache_create_tokens ?? 0;
+          cr += r.cacheReadTokens ?? r.cache_read_tokens ?? 0;
+        }
+      }
+      result[win] = { input: i, output: o, cacheCreate: cw, cacheRead: cr };
+    }
+    let i = 0,
+      o = 0,
+      cw = 0,
+      cr = 0;
+    for (const r of rows) {
+      i += r.inputTokens ?? r.input_tokens ?? 0;
+      o += r.outputTokens ?? r.output_tokens ?? 0;
+      cw += r.cacheCreationTokens ?? r.cache_create_tokens ?? 0;
+      cr += r.cacheReadTokens ?? r.cache_read_tokens ?? 0;
+    }
+    result["all"] = { input: i, output: o, cacheCreate: cw, cacheRead: cr };
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+async function _tokenDashPillars() {
+  const dbPath = path.join(os.homedir(), ".claude", "token-dashboard.db");
+  if (!existsSync(dbPath)) return null;
+  try {
+    const raw = await execFileAsync(
+      "sqlite3",
+      [
+        dbPath,
+        "SELECT SUM(input_tokens),SUM(output_tokens),SUM(cache_create_5m_tokens)+SUM(cache_create_1h_tokens),SUM(cache_read_tokens) FROM messages",
+      ],
+      5000,
+    );
+    const [i, o, cw, cr] = raw.trim().split("|").map(Number);
+    return {
+      all: {
+        input: i || 0,
+        output: o || 0,
+        cacheCreate: cw || 0,
+        cacheRead: cr || 0,
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function _tokscalePillars(platform = "claude") {
+  // Try the bundled tokscale CLI first (fresh data), fall back to saved report file.
+  try {
+    const raw = await execFileAsync("tokscale", ["models", "--json"], 60000);
+    const data = JSON.parse(raw);
+    const entries = Array.isArray(data?.entries)
+      ? data.entries
+      : Array.isArray(data)
+        ? data
+        : [];
+    const rows = entries.filter(
+      (e) =>
+        e &&
+        e.client === platform &&
+        e.model !== "<synthetic>" &&
+        e.model !== "unknown" &&
+        ((Number(e.input) || 0) > 0 || (Number(e.output) || 0) > 0),
+    );
+    if (rows.length) {
+      const acc = rows.reduce(
+        (a, e) => ({
+          input: a.input + (Number(e.input) || 0),
+          output: a.output + (Number(e.output) || 0),
+          cacheCreate: a.cacheCreate + (Number(e.cacheWrite) || 0),
+          cacheRead: a.cacheRead + (Number(e.cacheRead) || 0),
+        }),
+        { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 },
+      );
+      return { all: acc };
+    }
+  } catch {
+    /* fall through to file-based read */
+  }
+  // Fallback: read saved tokscale_report.json if it exists
+  const p = path.join(os.homedir(), "tokscale_report.json");
+  if (!existsSync(p)) return null;
+  try {
+    const data = JSON.parse(readFileSync(p, "utf8"));
+    const rows = (data.entries ?? []).filter(
+      (e) =>
+        e.client === platform &&
+        e.model !== "<synthetic>" &&
+        e.model !== "unknown" &&
+        (e.input > 0 || e.output > 0),
+    );
+    if (!rows.length) return null;
+    const acc = rows.reduce(
+      (a, e) => ({
+        input: a.input + (e.input ?? 0),
+        output: a.output + (e.output ?? 0),
+        cacheCreate: a.cacheCreate + (e.cacheWrite ?? 0),
+        cacheRead: a.cacheRead + (e.cacheRead ?? 0),
+      }),
+      { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 },
+    );
+    return { all: acc };
+  } catch {
+    return null;
+  }
+}
+
+export { _ccusagePillars, _tokenDashPillars, _tokscalePillars };

package/tools/compare-operators.mjs

@@ -0,0 +1,79 @@
+/**
+ * tools/compare-operators.mjs — compare_operators tool.
+ */
+
+import { COMPARE_OPERATORS_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { _behavioralFraming, _classMeaning, _competitiveLayer } from "./_framing.mjs";
+
+export const TOOL_DEF = {
+  name: "compare_operators",
+  description:
+    "Compares two operators side-by-side with a behavioral verdict. Fetches both profiles from the board and returns their yield, leverage, velocity, class, and rank side-by-side, plus a verdict explaining who is more efficient and why in power-user language. Use this when users ask 'compare operator X vs Y' or 'who is more efficient' or 'how do two AI users compare'. Intent: COMPARE_OPERATORS.",
+  annotations: { title: "Compare two operators", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      codename_a: {
+        type: "string",
+        description:
+          "First operator's codename from the SigRank leaderboard. Case-insensitive.",
+      },
+      codename_b: {
+        type: "string",
+        description:
+          "Second operator's codename from the SigRank leaderboard. Case-insensitive.",
+      },
+    },
+    required: ["codename_a", "codename_b"],
+    description:
+      "Requires both codenames. Both must exist on the board.",
+  },
+  outputSchema: COMPARE_OPERATORS_OUTPUT,
+};
+
+export async function handleCompareOperators(args, ctx) {
+  const nameA = String(args?.codename_a || "").trim();
+  const nameB = String(args?.codename_b || "").trim();
+  if (!nameA || !nameB)
+    throw new Error(
+      "compare_operators requires both `codename_a` and `codename_b`.",
+    );
+
+  const [opA, opB, board] = await Promise.all([
+    ctx.fetchJson(`/api/v1/operators/${encodeURIComponent(nameA)}`),
+    ctx.fetchJson(`/api/v1/operators/${encodeURIComponent(nameB)}`),
+    ctx.fetchJson("/api/v1/leaderboard?metric=yield_"),
+  ]);
+
+  const yieldA = opA.yield_ || 0;
+  const yieldB = opB.yield_ || 0;
+  const delta = yieldA - yieldB;
+
+  const winner = yieldA > yieldB ? opA : opB;
+  const loser = yieldA > yieldB ? opB : opA;
+  const verdict = `${winner.codename} is more token-efficient (${winner.yield_?.toLocaleString?.() || winner.yield_} vs ${loser.yield_?.toLocaleString?.() || loser.yield_} Υ). ${_behavioralFraming(winner)} ${loser.codename} ${_classMeaning(loser.class).toLowerCase()}`;
+
+  return {
+    operator_a: {
+      codename: opA.codename,
+      yield_: opA.yield_,
+      leverage: opA.leverage,
+      velocity: opA.velocity,
+      class: opA.class,
+      rank: opA.rank,
+      competitive: _competitiveLayer(opA, board),
+    },
+    operator_b: {
+      codename: opB.codename,
+      yield_: opB.yield_,
+      leverage: opB.leverage,
+      velocity: opB.velocity,
+      class: opB.class,
+      rank: opB.rank,
+      competitive: _competitiveLayer(opB, board),
+    },
+    verdict,
+    yield_delta: delta,
+    cta: "Compare me to others",
+  };
+}