sigrank 0.19.0 → 1.0.1

package/tools/_schemas.mjs

@@ -0,0 +1,492 @@
+/**
+ * tools/_schemas.mjs — MCP tool annotation + input/output schema objects.
+ */
+
+import { SIGNAL_CLASSES, UNCLASSED } from "../analytics/cascade.mjs";
+
+// 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 },
+};
+
+// The canonical class-tier enum, single-sourced from analytics/cascade.mjs.
+// Every output schema that exposes a `class` field uses this so the enum can
+// never drift between tools. SIGNAL_CLASSES is the 24 sub-stage names (8 tiers
+// × 3 sub-stages I/II/III) that classify() emits and the API returns.
+// UNCLASSED is included for the degenerate no-data case. Exported so tool
+// files that declare their own output schema (optimize-efficiency.mjs,
+// describe-power-user.mjs) import the same enum instead of re-inlining a
+// stale tier list.
+export const CLASS_ENUM = [...SIGNAL_CLASSES, UNCLASSED];
+
+// Common output schema for cascade results (rank_paste, simulate_change, etc.)
+// Field names match the actual cascade() output in analytics/cascade.mjs:
+//   `yield` (not `yield_` — `yield_` was a schema-only alias that didn't match
+//   the real payload), `dev10x` (not `tenx_dev`), `class`, `snr`, `leverage`,
+//   `velocity`, `pillars`, `mode`, `warnings`, plus the tool-added `card`.
+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" },
+    dev10x: { type: "number", description: "10xDEV score (log10 of the cascade product)" },
+    class: {
+      type: "string",
+      enum: CLASS_ENUM,
+      description: "Operator class tier (dev10x taxonomy)",
+    },
+    mode: {
+      type: "object",
+      description: "Detected working mode (BUILD/EDIT/DEBUG/MAINTAIN/IDLE) + confidence",
+    },
+    pillars: {
+      type: "object",
+      description: "The four raw token pillars the cascade was computed from",
+    },
+    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: CLASS_ENUM },
+          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: CLASS_ENUM },
+    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" },
+            },
+          },
+        },
+      },
+    },
+    batched: {
+      type: "object",
+      description:
+        "Submission-based rolled-forward totals (never decrease when platforms delete old logs). Present when the operator has submission history.",
+      properties: {
+        per_platform: {
+          type: "object",
+          description: "Per-platform batched windows",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              "90d": {
+                type: "object",
+                description: "Rolled-forward 90d pillars (sum of batches <=90 days old)",
+                properties: {
+                  input: { type: "integer" },
+                  output: { type: "integer" },
+                  cacheCreate: { type: "integer" },
+                  cacheRead: { type: "integer" },
+                },
+              },
+              all: {
+                type: "object",
+                description: "All-time pillars (baseline + all deltas — never decreases)",
+                properties: {
+                  input: { type: "integer" },
+                  output: { type: "integer" },
+                  cacheCreate: { type: "integer" },
+                  cacheRead: { type: "integer" },
+                },
+              },
+              submission_count: {
+                type: "integer",
+                description: "Number of archived submissions for this platform",
+              },
+              baseline_date: {
+                type: "string",
+                description: "ISO date of the first (baseline) submission",
+              },
+            },
+          },
+        },
+        combined: {
+          type: "object",
+          description: "Combined batched windows across all platforms",
+          properties: {
+            "90d": {
+              type: "object",
+              properties: {
+                input: { type: "integer" },
+                output: { type: "integer" },
+                cacheCreate: { type: "integer" },
+                cacheRead: { type: "integer" },
+              },
+            },
+            all: {
+              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: CLASS_ENUM },
+          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: CLASS_ENUM },
+        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: CLASS_ENUM },
+        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: CLASS_ENUM },
+        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" },
+    window: {
+      type: "string",
+      enum: ["7d", "30d", "90d", "all"],
+      description: "The watched window (watch_tokenpull watches one window per call)",
+    },
+    pillars: {
+      type: "object",
+      description: "The four raw token pillars for the watched window",
+      properties: {
+        input: { type: "integer" },
+        output: { type: "integer" },
+        cacheCreate: { type: "integer" },
+        cacheRead: { type: "integer" },
+      },
+    },
+    messages: {
+      type: "integer",
+      description: "Number of messages in the watched window",
+    },
+    cascade: CASCADE_OUTPUT,
+    card: { type: "string", description: "Deterministic prose summary" },
+    generatedAt: { type: "string", description: "ISO timestamp of the pull" },
+    poll_interval_s: {
+      type: "number",
+      description: "Advisory poll cadence echoed back (does not make the call block)",
+    },
+    auth_submit: {
+      type: ["object", "null"],
+      description:
+        "Present only when submit:true. One of: {status:'received'|'cooldown'|'not_enrolled'|'error', ...}. Null when submit is false (preview only).",
+    },
+    note: {
+      type: "string",
+      description: "Reminder that one snapshot is returned per call — re-call to detect changes.",
+    },
+  },
+};
+
+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 };