sigrank 0.0.178 → 0.0.180

package/tools/submit-paste.mjs

@@ -0,0 +1,118 @@
+/**
+ * tools/submit-paste.mjs — submit_paste tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { narrate } from "../presentation/narrate.mjs";
+import { SUBMIT_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import {
+  MAX_INPUT,
+  uploadStamp,
+  withParseWarnings,
+} from "./_helpers.mjs";
+
+export const TOOL_DEF = {
+  name: "submit_paste",
+  description:
+    "Ranks a paste of token counts AND publishes it to the live SigRank board at signalaf.com in one call. First computes the cascade locally for an instant preview (yield, leverage, velocity, class, card), then submits the raw paste to the board's web-paste endpoint, which re-parses and re-scores it server-side. The server score is authoritative — it may differ from the local preview if the board applies additional validation. Returns both the local preview and the server response (including the operator's new rank if accepted). A codename is required to publish — omit it for a local preview only (no board submission). Token-only, no auth required. Use this when you have token counts from ccusage or a dashboard and want to both see your score and publish it. Do NOT use this if you want to pull your local usage automatically — use tokenpull_submit for the zero-paste flow. Do NOT use this for multi-window dashboard pastes — use rank_windows to rank them first, then submit each window. After calling this, use get_operator with your codename to verify your submission appeared on the board.",
+  annotations: {
+    title: "Submit paste to board",
+    ...ANNOTATIONS.destructiveHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      text: {
+        type: "string",
+        description:
+          'Token counts to rank and submit. Two formats: (1) JSON {"input":N,"output":N,"cacheCreate":N,"cacheRead":N} from ccusage (preferred — the board parses this reliably), or (2) four whitespace-separated numbers: input output cacheCreate cacheRead. The 4-number form ranks locally but the board may reject it. Example: {"input":1000000,"output":500000,"cacheCreate":50000,"cacheRead":800000}',
+      },
+      codename: {
+        type: "string",
+        description:
+          'Operator codename to publish under on the leaderboard (e.g. "Ghost Falcon"). Required to submit — omit for local preview only (no board submission, just returns the local cascade result). Must be a non-empty string.',
+      },
+    },
+    required: ["text"],
+    description:
+      "Requires token counts (text). Codename is optional but required for board submission — omit it for preview-only mode.",
+  },
+  outputSchema: SUBMIT_OUTPUT,
+};
+
+export async function handleSubmitPaste(args, ctx) {
+  if (!args?.text)
+    throw new Error("submit_paste requires a non-empty `text` argument.");
+  if (typeof args.text === "string" && args.text.length > MAX_INPUT) {
+    return {
+      status: "error",
+      reason: "input_too_large",
+      detail: `text exceeds ${MAX_INPUT} chars (${args.text.length}). Paste only the token-count table, not full output.`,
+    };
+  }
+  // Local preview first — also validates the paste is parseable before any POST.
+  const pillars = parsePillars(args.text);
+  const c = withParseWarnings(pillars, cascade(pillars));
+  const codename = String(args?.codename || "").trim();
+  const card = narrate(c, codename || "This operator");
+
+  // No codename → cannot publish (the board endpoint requires it). Fail fast at the
+  // tool boundary with a clear message instead of an opaque server 400.
+  if (!codename) {
+    return {
+      ...c,
+      card,
+      submission: {
+        status: "not_submitted",
+        reason: "codename_required",
+        detail:
+          "Pass a codename to publish to the board. Showing local preview only.",
+      },
+    };
+  }
+
+  // Submit the RAW paste so the server re-parses + re-scores authoritatively — the
+  // MCP's local cascade is only a preview; the board stays the single source of truth.
+  const stamp = uploadStamp({
+    codename,
+    pillars: c.pillars,
+    source: "web_paste",
+  });
+  const res = await ctx.doFetch(`${ctx.apiBase}/api/v1/ingest-paste`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json",
+    },
+    body: JSON.stringify({
+      codename,
+      raw_paste: String(args?.text || ""),
+      consent_acknowledged: true,
+      terms_version: "2026-07-21",
+      privacy_version: "2026-07-21",
+      ...stamp,
+    }),
+  });
+  let ack;
+  try {
+    ack = await res.json();
+  } catch {
+    ack = {
+      status: "error",
+      detail: `HTTP ${res.status} (non-JSON response)`,
+    };
+  }
+  const ranked = !!(
+    res.ok &&
+    ack.verification_tier === "verified" &&
+    ack.persisted === true
+  );
+  return {
+    ...c,
+    card,
+    ranked,
+    submission: { ...stamp, httpStatus: res.status, ranked, ...ack },
+  };
+}

package/tools/submit-verified.mjs

@@ -0,0 +1,153 @@
+/**
+ * tools/submit-verified.mjs — submit_verified tool.
+ */
+
+import { ALL_PLATFORMS } from "../adapters/index.mjs";
+import { ensureIdentity } from "../identity/keystore.mjs";
+import { submitSignedWindow } from "../submit/index.mjs";
+import { SUBMIT_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { pullByPlatform, WINDOW_TYPE } from "./_helpers.mjs";
+import { _computeReportBlock } from "./_report.mjs";
+
+export const TOOL_DEF = {
+  name: "submit_verified",
+  description:
+    "Publish your LOCAL token runs to the SigRank board as a VERIFIED operator — the enrolled, signed path. Reads your pillars (tokenpull), builds the canonical Schema 1.0 snapshot per window, ed25519-signs it with your device key, and POSTs to /api/v1/snapshots. Requires `npx sigrank-mcp enroll` first (a bound device). Only signed submissions from a trusted device rank on the board. Token-only; the private key never leaves your machine. Pass dry_run:true to inspect the exact signed payload without publishing.",
+  annotations: {
+    title: "Submit verified score",
+    ...ANNOTATIONS.destructiveHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      window: {
+        type: "string",
+        enum: ["7d", "30d", "90d", "all"],
+        description: "submit only this window (default: all 4)",
+      },
+      platform: {
+        type: "string",
+        enum: [...ALL_PLATFORMS, "multi"],
+        description:
+          "source platform (default: claude). 'multi' = combined cascade summed across all locally-detected platforms (needs 2+ active); empty windows are skipped.",
+      },
+      dry_run: {
+        type: "boolean",
+        description:
+          "build + sign but do NOT publish — returns the exact payload that would be POSTed (token counts only), so you can inspect before submitting",
+      },
+    },
+  },
+  outputSchema: SUBMIT_OUTPUT,
+};
+
+export async function handleSubmitVerified(args, ctx) {
+  // The enrolled, signed publish path → /api/v1/snapshots (only verified rows rank).
+  const id = ctx.opts.identity || ensureIdentity();
+  if (!id.codename || !id.operator_id) {
+    return {
+      status: "not_enrolled",
+      detail: "Run `npx sigrank-mcp enroll` to bind this device first.",
+    };
+  }
+  const platform = args?.platform || "claude";
+
+  // MULTI: the combined cross-platform cascade. The dashboard already SUMS every
+  // active platform's pillars (a "claude+codex" row) but never submitted it — this
+  // is that missing submission. Aggregate every locally-detected platform's pillars
+  // per window and publish as platform='multi' = the operator's TOTAL usage. Empty
+  // windows are skipped so a no-activity window never lands as a degenerate row.
+  if (platform === "multi") {
+    const detected = [];
+    for (const p of ALL_PLATFORMS) {
+      const r = await pullByPlatform(p, ctx.opts).catch(() => null);
+      const live =
+        r &&
+        (r.windows || []).some(
+          (w) =>
+            w.pillars.input +
+              w.pillars.output +
+              w.pillars.cacheCreate +
+              w.pillars.cacheRead >
+            0,
+        );
+      if (live) detected.push(r);
+    }
+    if (detected.length < 2) {
+      return {
+        platform: "multi",
+        codename: id.codename,
+        operator_id: id.operator_id,
+        status: "skipped",
+        reason: "need_2_platforms",
+        detail: `multi needs 2+ active platforms; found ${detected.length} (${detected.map((d) => d.platform).join(", ") || "none"}).`,
+        windows: [],
+      };
+    }
+    const winKeys = args?.window
+      ? [args.window]
+      : ["7d", "30d", "90d", "all"];
+    const out = [];
+    for (const wk of winKeys) {
+      const sum = { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 };
+      let msgs = 0;
+      for (const d of detected) {
+        const w = (d.windows || []).find((x) => x.window === wk);
+        if (!w) continue;
+        sum.input += w.pillars.input || 0;
+        sum.output += w.pillars.output || 0;
+        sum.cacheCreate += w.pillars.cacheCreate || 0;
+        sum.cacheRead += w.pillars.cacheRead || 0;
+        msgs += w.messages || 0;
+      }
+      if (sum.input + sum.output + sum.cacheCreate + sum.cacheRead <= 0)
+        continue; // skip empty window
+      const report = _computeReportBlock(sum);
+      const r = await submitSignedWindow(wk, sum, msgs, id, {
+        apiBase: ctx.apiBase,
+        fetchImpl: ctx.doFetch,
+        platform: "multi",
+        now: ctx.opts.now,
+        dryRun: !!args?.dry_run,
+        report,
+      });
+      out.push({ window: wk, pillars: sum, ...r });
+    }
+    return {
+      platform: "multi",
+      codename: id.codename,
+      operator_id: id.operator_id,
+      sources: detected.map((d) => d.platform),
+      windows: out,
+    };
+  }
+
+  const pulled = await pullByPlatform(platform, ctx.opts);
+  const targets = args?.window
+    ? pulled.windows.filter((w) => w.window === args.window)
+    : pulled.windows;
+  const out = [];
+  for (const w of targets) {
+    // Compute the cascade report block (mode + badges + health) for this window.
+    // Pure math, computed locally, submitted alongside the 4 token pillars.
+    const report = _computeReportBlock(w.pillars);
+    const r = await submitSignedWindow(w.window, w.pillars, w.messages, id, {
+      apiBase: ctx.apiBase,
+      fetchImpl: ctx.doFetch,
+      platform: pulled.platform,
+      now: ctx.opts.now,
+      dryRun: !!args?.dry_run,
+      report,
+    });
+    out.push({ window: w.window, pillars: w.pillars, ...r });
+  }
+  return {
+    platform: pulled.platform,
+    codename: id.codename,
+    operator_id: id.operator_id,
+    generatedAt: pulled.generatedAt,
+    windows: out,
+  };
+}

package/tools/suggest-improvements.mjs

@@ -0,0 +1,168 @@
+/**
+ * tools/suggest-improvements.mjs — suggest_improvements tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { SUGGEST_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+
+export const TOOL_DEF = {
+  name: "suggest_improvements",
+  description:
+    "Generates ranked, simulated improvement suggestions for your token cascade. Takes your 4 pillars, tests multiple improvement strategies (increase cache reads, reduce fresh input, increase output, optimize cache creation), simulates each with the canonical cascade engine, and returns them ranked by Υ yield impact. Each suggestion includes: the action, which pillar to change, how much to change it, the projected Υ after the change, the yield delta, the projected class tier, and a rationale. Also returns the single highest-impact change (best_single_change). Pure local math — no network, no submission. Use this after diagnose_cascade to get actionable next steps, then use simulate_change to fine-tune before committing. Accepts the same input formats as rank_paste.",
+  annotations: {
+    title: "Suggest improvements",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      text: {
+        type: "string",
+        description:
+          'Token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).',
+      },
+    },
+    required: ["text"],
+  },
+  outputSchema: SUGGEST_OUTPUT,
+};
+
+export async function handleSuggestImprovements(args) {
+  if (!args?.text)
+    throw new Error(
+      "suggest_improvements requires a non-empty `text` argument (token pillars).",
+    );
+  if (typeof args.text === "string" && args.text.length > MAX_INPUT) {
+    return {
+      status: "error",
+      reason: "input_too_large",
+      detail: `text exceeds ${MAX_INPUT} chars.`,
+    };
+  }
+
+  const p = parsePillars(args.text);
+  const current = withParseWarnings(p, cascade(p));
+  const { input: i, output: o, cacheCreate: cw, cacheRead: cr } = p;
+
+  // Generate candidate improvements, simulate each, rank by Υ impact
+  const candidates = [];
+
+  // Strategy 1: Increase cache reads (the #1 lever)
+  const crBoosts = cr > 0 ? [1.5, 2, 3, 5] : [];
+  for (const mult of crBoosts) {
+    const sim = cascade({ ...p, 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 - (current.yield ?? 0)).toFixed(2)),
+        class_after: sim.class,
+        rationale:
+          "Cache reads are the strongest Υ multiplier. More reuse = higher leverage = higher yield.",
+      });
+    }
+  }
+  // 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({
+        ...p,
+        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 - (current.yield ?? 0)).toFixed(2)),
+          class_after: sim.class,
+          rationale:
+            "You have no cache — enabling it unlocks the cascade. Start by reusing prior context.",
+        });
+      }
+    }
+  }
+
+  // Strategy 2: Reduce fresh input (Υ = Cr·O/I² — input is squared in the denominator)
+  const inputReductions = [0.9, 0.75, 0.5];
+  for (const mult of inputReductions) {
+    const newInput = Math.round(i * mult);
+    if (newInput < 1) continue;
+    const sim = cascade({ ...p, 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 - (current.yield ?? 0)).toFixed(2)),
+        class_after: sim.class,
+        rationale:
+          "Input is squared in the Υ denominator (Υ = Cr·O/I²). Reducing input has a quadratic payoff.",
+      });
+    }
+  }
+
+  // Strategy 3: Increase output
+  const outputBoosts = [1.25, 1.5, 2];
+  for (const mult of outputBoosts) {
+    const sim = cascade({ ...p, 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 - (current.yield ?? 0)).toFixed(2)),
+        class_after: sim.class,
+        rationale:
+          "Output is a linear multiplier in Υ. More output per session = higher yield.",
+      });
+    }
+  }
+
+  // Strategy 4: Optimize cache creation (reduce if over-committing)
+  if (cw > o * 10) {
+    const sim = cascade({ ...p, cacheCreate: Math.round(o * 5) });
+    if (sim.yield !== null) {
+      candidates.push({
+        action: "Reduce cache creation to 5× output",
+        pillar: "cacheCreate",
+        delta: `-${Math.round(cw - o * 5).toLocaleString()}`,
+        simulated_yield: sim.yield,
+        yield_delta: Number((sim.yield - (current.yield ?? 0)).toFixed(2)),
+        class_after: sim.class,
+        rationale:
+          "You're over-committing cache (cw >> output). Trimming to a healthy ratio reduces cost without hurting yield.",
+      });
+    }
+  }
+
+  // Sort by yield_delta descending, take top 8
+  candidates.sort((a, b) => b.yield_delta - a.yield_delta);
+  const top = candidates
+    .slice(0, 8)
+    .map((c, idx) => ({ rank: idx + 1, ...c }));
+
+  const best = top[0];
+  return {
+    suggestions: top,
+    current_yield: current.yield,
+    current_class: current.class,
+    best_single_change: best
+      ? `${best.action} (Υ ${current.yield} → ${best.simulated_yield}, +${best.yield_delta} yield, class ${best.class_after})`
+      : "No improvements found — your cascade is already optimized.",
+  };
+}

package/tools/tokenpull-compare.mjs

@@ -0,0 +1,123 @@
+/**
+ * tools/tokenpull-compare.mjs — tokenpull_compare tool.
+ */
+
+import { cascade } from "../analytics/cascade.mjs";
+import { ALL_PLATFORMS } from "../adapters/index.mjs";
+import { COMPARE_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { pullByPlatform } from "./_helpers.mjs";
+import { _ccusagePillars, _tokenDashPillars, _tokscalePillars } from "./_verifiers.mjs";
+
+export const TOOL_DEF = {
+  name: "tokenpull_compare",
+  description:
+    "Pull token usage from ALL four local sources in parallel — tokenpull (JSONL canon), ccusage CLI, token-dashboard SQLite, and tokscale report — and return them side-by-side with delta % vs tokenpull as the baseline. Also computes the cascade (Υ, SNR, Leverage, class) for each source so you can see how each verifier scores. Useful for validating your numbers before submitting, or understanding discrepancies between tools. Claude only for token-dash; codex and others use tokenpull + ccusage + tokscale. Token-only, on-device.",
+  annotations: { title: "Compare token sources", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      platform: {
+        type: "string",
+        enum: ALL_PLATFORMS,
+        description:
+          "platform to compare (default: claude). token-dash and App only available for claude.",
+      },
+    },
+  },
+  outputSchema: COMPARE_OUTPUT,
+};
+
+export async function handleTokenpullCompare(args, ctx) {
+  const platform = args?.platform || "claude";
+  const WINS = ["7d", "30d", "90d", "all"];
+
+  // Pull all four sources in parallel (verifiers are now async via execFile)
+  const [tpResult, ccPillars, tdPillars, tsPillars] = await Promise.all([
+    pullByPlatform(platform, ctx.opts).catch(() => null),
+    _ccusagePillars(platform).catch(() => null),
+    (platform === "claude"
+      ? _tokenDashPillars()
+      : Promise.resolve(null)
+    ).catch(() => null),
+    _tokscalePillars(platform).catch(() => null),
+  ]);
+
+  // Build tokenpull window lookup
+  const tpByWin = {};
+  for (const w of tpResult?.windows ?? []) tpByWin[w.window] = w.pillars;
+
+  // Helper: delta % vs tokenpull baseline
+  const delta = (val, base) =>
+    base > 0 ? +(((val - base) / base) * 100).toFixed(1) : null;
+
+  // Build per-source per-window comparison
+  const SOURCES = [
+    {
+      source: "tokenpull",
+      note: "JSONL deduped by msg id — canon source",
+      byWin: tpByWin,
+    },
+    {
+      source: "ccusage",
+      note: "ccusage CLI — monthly only",
+      byWin: ccPillars ?? {},
+    },
+    {
+      source: "token-dash",
+      note: "token-dashboard SQLite — all-time only",
+      byWin: tdPillars ?? {},
+    },
+    {
+      source: "tokscale",
+      note: "tokscale_report.json — all-time only",
+      byWin: tsPillars ?? {},
+    },
+  ];
+
+  const comparison = {};
+  for (const win of WINS) {
+    const baseP = tpByWin[win];
+    comparison[win] = SOURCES.filter((s) => s.byWin[win] != null).map((s) => {
+      const p = s.byWin[win];
+      const cas = cascade(p);
+      const entry = {
+        source: s.source,
+        note: s.note,
+        pillars: p,
+        cascade: {
+          yield: cas.yield,
+          snr: cas.snr,
+          leverage: cas.leverage,
+          velocity: cas.velocity,
+          dev10x: cas.dev10x,
+          class: cas.class,
+        },
+      };
+      if (s.source !== "tokenpull" && baseP) {
+        entry.delta_vs_tokenpull = {
+          input: delta(p.input, baseP.input),
+          output: delta(p.output, baseP.output),
+          cacheCreate: delta(p.cacheCreate, baseP.cacheCreate),
+          cacheRead: delta(p.cacheRead, baseP.cacheRead),
+        };
+      }
+      return entry;
+    });
+  }
+
+  // Sources available summary
+  const available = SOURCES.filter(
+    (s) => Object.keys(s.byWin).length > 0,
+  ).map((s) => s.source);
+
+  return {
+    platform,
+    estimated: tpResult?.estimated ?? false,
+    generatedAt: tpResult?.generatedAt ?? new Date().toISOString(),
+    sources_available: available,
+    sources_missing: SOURCES.map((s) => s.source).filter(
+      (s) => !available.includes(s),
+    ),
+    comparison,
+  };
+}