sigrank 0.19.0 → 1.0.2

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.",
+  };
+}

package/tools/standard-record.mjs

@@ -0,0 +1,108 @@
+import { cascade } from "../analytics/cascade.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+
+export const SIGRANK_STANDARD_VERSION = "sigrank/0.1-draft";
+
+export const TOOL_DEF = {
+  name: "get_sigrank_standard_record",
+  description:
+    "Build a SigRank Standard v0.1-draft portable operator record from four token pillars. Computes the canonical cascade locally through @sigrank/cascade and returns versioned telemetry plus the normative core metrics: Yield, Leverage, Velocity, SNR, and 10xDEV. No data is submitted or persisted. The core record contains token telemetry only and does not require prompt text, code, or response content.",
+  annotations: {
+    title: "Export SigRank standard record",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.destructiveHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    required: ["input", "output", "cache_write", "cache_read"],
+    properties: {
+      input: { type: "number", minimum: 0, description: "Fresh input tokens." },
+      output: { type: "number", minimum: 0, description: "Output tokens." },
+      cache_write: { type: "number", minimum: 0, description: "Cache-write / cache-creation tokens." },
+      cache_read: { type: "number", minimum: 0, description: "Cache-read tokens." },
+      provider: { type: "string", description: "Optional provider identifier." },
+      model: { type: "string", description: "Optional model identifier." },
+      tool: { type: "string", description: "Optional tool/client identifier." },
+      timestamp: { type: "string", description: "Optional ISO-8601 timestamp. Defaults to the current time." }
+    }
+  },
+  outputSchema: {
+    type: "object",
+    required: ["spec", "timestamp", "source", "telemetry", "metrics"],
+    properties: {
+      spec: { type: "string", description: "SigRank specification version." },
+      timestamp: { type: "string", description: "ISO-8601 record timestamp." },
+      source: {
+        type: "object",
+        properties: {
+          provider: { type: "string" },
+          model: { type: "string" },
+          tool: { type: "string" }
+        }
+      },
+      telemetry: {
+        type: "object",
+        properties: {
+          input: { type: "number" },
+          output: { type: "number" },
+          cache_write: { type: "number" },
+          cache_read: { type: "number" }
+        }
+      },
+      metrics: {
+        type: "object",
+        properties: {
+          yield: { type: ["number", "null"] },
+          leverage: { type: ["number", "null"] },
+          velocity: { type: ["number", "null"] },
+          snr: { type: ["number", "null"] },
+          dev10x: { type: ["number", "null"] }
+        }
+      },
+      warnings: { type: "array", items: { type: "string" } }
+    }
+  }
+};
+
+export async function handleGetSigRankStandardRecord(args) {
+  const input = Number(args?.input);
+  const output = Number(args?.output);
+  const cacheWrite = Number(args?.cache_write);
+  const cacheRead = Number(args?.cache_read);
+
+  if (![input, output, cacheWrite, cacheRead].every(Number.isFinite)) {
+    throw new Error("get_sigrank_standard_record requires four finite numeric token pillars.");
+  }
+  if ([input, output, cacheWrite, cacheRead].some((v) => v < 0)) {
+    throw new Error("get_sigrank_standard_record requires non-negative token pillars.");
+  }
+
+  const c = cascade({ input, output, cacheCreate: cacheWrite, cacheRead });
+
+  return {
+    spec: SIGRANK_STANDARD_VERSION,
+    timestamp: args?.timestamp || new Date().toISOString(),
+    source: {
+      provider: args?.provider || "unknown",
+      model: args?.model || "unknown",
+      tool: args?.tool || "sigrank-mcp",
+    },
+    telemetry: {
+      input,
+      output,
+      cache_write: cacheWrite,
+      cache_read: cacheRead,
+    },
+    metrics: {
+      yield: c.yield,
+      leverage: c.leverage,
+      velocity: c.velocity,
+      snr: c.snr,
+      dev10x: c.dev10x,
+    },
+    warnings: c.warnings || [],
+  };
+}

package/tools/submit-paste.mjs

@@ -0,0 +1,121 @@
+/**
+ * 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";
+import { TERMS_VERSION, PRIVACY_VERSION, isRankedAck } from "../lib/constants.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.",
+      },
+    };
+  }
+
+  // Privacy: send ONLY the 4 parsed token numbers (canonical "input output
+  // cacheCreate cacheRead" form), never the raw user text. parsePillars above
+  // already validated the input — we reconstruct from the parsed pillars so
+  // no conversation content or prose can leak to the server. The server's
+  // ingestMeta() re-parses these 4 numbers authoritatively (Strategy 3:
+  // four bare numbers). This makes every submit path — signed and paste —
+  // send only token counts.
+  const canonicalPaste = `${pillars.input} ${pillars.output} ${pillars.cacheCreate} ${pillars.cacheRead}`;
+  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: canonicalPaste,
+      consent_acknowledged: true,
+      terms_version: TERMS_VERSION,
+      privacy_version: PRIVACY_VERSION,
+      ...stamp,
+    }),
+  });
+  let ack;
+  try {
+    ack = await res.json();
+  } catch {
+    ack = {
+      status: "error",
+      detail: `HTTP ${res.status} (non-JSON response)`,
+    };
+  }
+  const ranked = isRankedAck(res, ack);
+  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,
+  };
+}