sigrank 0.19.0 → 1.0.2

package/tools/tokscale-breakdown.mjs

@@ -0,0 +1,119 @@
+/**
+ * tools/tokscale-breakdown.mjs — tokscale_breakdown tool.
+ */
+
+import { execFileAsync } from "./_helpers.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+import { TOKSCALE_CLIENT_MAP } from "../lib/constants.mjs";
+
+export const TOOL_DEF = {
+  name: "tokscale_breakdown",
+  description:
+    "Show a per-model breakdown of your token usage across all platforms detected by tokscale. Models under the threshold (default 1%) are lumped into 'other' to keep the display clean. Useful for seeing which models you actually use per platform (e.g. claude-opus-4-8 76%, claude-sonnet-4-6 11%, other 0.3%). Returns { platform: [{ model, input, output, cacheRead, cacheCreate, pct }] }.",
+  annotations: {
+    title: "Model breakdown",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      threshold: {
+        type: "number",
+        description:
+          "Models below this fraction of their platform's total tokens are lumped into 'other'. Default 0.01 (1%). Set 0 to see every model.",
+        default: 0.01,
+      },
+    },
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      platforms: {
+        type: "object",
+        description: "Map of platform name → array of { model, input, output, cacheRead, cacheCreate, pct }",
+      },
+    },
+  },
+};
+
+// TOKSCALE_CLIENT_MAP is imported from lib/constants.mjs (single source of truth).
+
+/**
+ * Run `tokscale models --json` and return a model-level breakdown per platform.
+ * Models under `threshold` (default 1%) of their platform's total are lumped
+ * into "other" to keep the display clean.
+ *
+ * Returns: { platform: [{ model, input, output, cacheRead, cacheCreate, pct }] }
+ */
+export async function tokscaleModelBreakdown(threshold = 0.01) {
+  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
+      : [];
+  if (!entries.length) return {};
+
+  // Group entries by our platform name
+  const byPlatform = {};
+  for (const e of entries) {
+    if (!e || !e.client) continue;
+    if (e.model === "<synthetic>" || e.model === "unknown") continue;
+    const input = Number(e.input) || 0;
+    const output = Number(e.output) || 0;
+    if (input + output === 0) continue;
+    const platform = TOKSCALE_CLIENT_MAP[e.client];
+    if (platform === null) continue;
+    const p = platform || "other";
+    if (!byPlatform[p]) byPlatform[p] = [];
+    byPlatform[p].push({
+      model: e.model,
+      input,
+      output,
+      cacheRead: Number(e.cacheRead) || 0,
+      cacheCreate: Number(e.cacheWrite) || 0,
+    });
+  }
+
+  // For each platform: sort by total tokens desc, lump small models into "other"
+  const result = {};
+  for (const [platform, models] of Object.entries(byPlatform)) {
+    const total = models.reduce(
+      (s, m) => s + m.input + m.output + m.cacheRead + m.cacheCreate,
+      0,
+    );
+    if (total === 0) continue;
+    const sorted = models.sort(
+      (a, b) =>
+        b.input + b.output + b.cacheRead + b.cacheCreate -
+        (a.input + a.output + a.cacheRead + a.cacheCreate),
+    );
+    const big = [];
+    const small = { model: "other", input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
+    for (const m of sorted) {
+      const t = m.input + m.output + m.cacheRead + m.cacheCreate;
+      if (t / total < threshold) {
+        small.input += m.input;
+        small.output += m.output;
+        small.cacheRead += m.cacheRead;
+        small.cacheCreate += m.cacheCreate;
+      } else {
+        big.push({ ...m, pct: t / total });
+      }
+    }
+    if (small.input + small.output + small.cacheRead + small.cacheCreate > 0) {
+      const t = small.input + small.output + small.cacheRead + small.cacheCreate;
+      big.push({ ...small, pct: t / total });
+    }
+    result[platform] = big;
+  }
+  return result;
+}
+
+export async function handleTokscaleBreakdown(args) {
+  const threshold = Number(args?.threshold ?? 0.01);
+  const platforms = await tokscaleModelBreakdown(threshold);
+  return { platforms };
+}

package/tools/tokscale-competitive-intel.mjs

@@ -0,0 +1,45 @@
+/**
+ * tools/tokscale-competitive-intel.mjs — tokscale_competitive_intel tool.
+ */
+
+import { tokscaleCompetitiveIntel } from "../tokscale_analytics.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "tokscale_competitive_intel",
+  description:
+    "Competitive intelligence for any AI tool company. Pass a target tool (by tokscale client slug like 'claude', 'codex', 'devin-cli' or canonical platform name like 'devin', 'other') and get: the target's rank by tokens among all detected tools, its full profile (tokens, cost, model mix, cache_read_pct, cost_per_million_tokens, market share), and a head-to-head comparison against every competitor (each competitor's tokens, cost, model_count, share, cost_per_million_tokens). Returns market_totals for context. If the target is not found, lists all detected clients. Use this to benchmark one AI tool against its competitors on this machine. All data is local — this is your own usage, not aggregate market data.",
+  annotations: { title: "Competitive intelligence", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      target: {
+        type: "string",
+        description:
+          "The AI tool to analyze. Accepts a tokscale client slug (e.g. 'claude', 'codex', 'devin-cli', 'copilot') or a canonical platform name (e.g. 'devin', 'claude', 'other'). Case-insensitive. To discover valid slugs, call tokscale_market_share first.",
+      },
+    },
+    required: ["target"],
+    description: "Requires the target tool name. No other parameters accepted.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      target: { type: "string", description: "The resolved target slug(s)" },
+      found: { type: "boolean", description: "Whether the target was found in local data" },
+      rank_by_tokens: { type: "integer", description: "Target's rank among all detected tools by token volume" },
+      target_profile: { type: "object", description: "Target's full usage profile with model mix and market share" },
+      competitors: { type: "array", description: "All other detected tools with comparison metrics" },
+      market_totals: { type: "object", description: "Aggregate market context: { tokens, cost, messages, tool_count }" },
+      error: { type: "string", description: "Present if tokscale is unavailable or target is empty" },
+    },
+  },
+};
+
+export async function handleTokscaleCompetitiveIntel(args) {
+  const target = String(args?.target || "").trim();
+  if (!target) {
+    throw new Error("tokscale_competitive_intel requires a non-empty `target` argument (a tokscale client slug like 'claude' or 'codex').");
+  }
+  return await tokscaleCompetitiveIntel(target);
+}

package/tools/tokscale-cost-analysis.mjs

@@ -0,0 +1,31 @@
+/**
+ * tools/tokscale-cost-analysis.mjs — tokscale_cost_analysis tool.
+ */
+
+import { tokscaleCostAnalysis } from "../tokscale_analytics.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "tokscale_cost_analysis",
+  description:
+    "Cost analysis per developer per model from your local tokscale data. Returns a per-client × per-model cost breakdown with cost_per_million_tokens, cost_per_message, and share_cost. Includes a per-client cost rollup and totals: total_cost, total_tokens, avg_cost_per_million_tokens, most_expensive_model, cheapest_per_token. Use this to see exactly where your AI spend goes — which tools and models cost the most and which give the best value per token. Do NOT use this for market share — use tokscale_market_share for that.",
+  annotations: { title: "Cost analysis per model", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {},
+    description: "No parameters. Derives cost breakdown from tokscale models data.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      entries: { type: "array", description: "Per-client×per-model cost rows sorted by cost desc" },
+      client_rollup: { type: "array", description: "Per-client cost summary with share_cost and cost_per_million_tokens" },
+      totals: { type: "object", description: "Aggregate cost totals and extremes" },
+      error: { type: "string", description: "Present if tokscale is unavailable" },
+    },
+  },
+};
+
+export async function handleTokscaleCostAnalysis() {
+  return await tokscaleCostAnalysis();
+}

package/tools/tokscale-developer-profile.mjs

@@ -0,0 +1,36 @@
+/**
+ * tools/tokscale-developer-profile.mjs — tokscale_developer_profile tool.
+ */
+
+import { tokscaleDeveloperProfile } from "../tokscale_analytics.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "tokscale_developer_profile",
+  description:
+    "Per-developer usage profile across all 20+ AI tools detected by tokscale on this machine. For each tool: model mix (per-model tokens/cost/messages/performance), token pillars (input/output/cache_read/cache_write/reasoning), cache_read_pct, session count, scan path (redacted to ~), workspace breakdown, and headless support flag. Returns a summary with tool_count, total_cost, dominant_tool. All filesystem paths are redacted (home dir → ~). Use this to understand your full AI tool footprint — which tools you use, which models per tool, and how your usage is distributed. Do NOT use this for cost-only analysis — use tokscale_cost_analysis for that.",
+  annotations: { title: "Developer usage profile", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {},
+    description: "No parameters. Profiles all locally-detected AI tools via tokscale.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      tools: {
+        type: "array",
+        description: "Per-tool profile with model mix, token pillars, session counts, workspaces",
+      },
+      summary: {
+        type: "object",
+        description: "Aggregate summary: { tool_count, total_cost, total_tokens, total_messages, avg_cost_per_tool, dominant_tool }",
+      },
+      error: { type: "string", description: "Present if tokscale is unavailable" },
+    },
+  },
+};
+
+export async function handleTokscaleDeveloperProfile() {
+  return await tokscaleDeveloperProfile();
+}

package/tools/tokscale-device-profile.mjs

@@ -0,0 +1,35 @@
+/**
+ * tools/tokscale-device-profile.mjs — tokscale_device_profile tool.
+ */
+
+import { tokscaleDeviceProfile } from "../tokscale_analytics.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "tokscale_device_profile",
+  description:
+    "Device fingerprinting: profiles this machine's AI tool footprint — which AI tools are installed, where their session logs live (paths redacted to ~), how many sessions and messages each has, when the machine was active (daily activity + day-of-week distribution), session concurrency, and longest continuous session. Combines tokscale clients + graph data. All filesystem paths are redacted so no local username leaks. Use this to audit your own machine's AI tool installation and activity pattern. This is local-only — it profiles the current machine, not remote devices.",
+  annotations: { title: "Device profile", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {},
+    description: "No parameters. Profiles the local machine via tokscale.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      installed_tools: { type: "array", description: "Detected AI tools with redacted session paths and message counts" },
+      installed_tool_count: { type: "integer" },
+      active_tool_count: { type: "integer", description: "Tools whose session path exists on disk" },
+      date_range: { type: "object", description: "{ start, end } of the activity data" },
+      activity: { type: "object", description: "Daily activity + day-of-week token distribution" },
+      sessions: { type: "object", description: "Session metrics: count, total/longest active time, max concurrent" },
+      summary: { type: "object", description: "Cost summary from graph: total_tokens, total_cost, avg_per_day, max_single_day" },
+      error: { type: "string", description: "Present if tokscale is unavailable" },
+    },
+  },
+};
+
+export async function handleTokscaleDeviceProfile() {
+  return await tokscaleDeviceProfile();
+}

package/tools/tokscale-market-share.mjs

@@ -0,0 +1,38 @@
+/**
+ * tools/tokscale-market-share.mjs — tokscale_market_share tool.
+ */
+
+import {
+  tokscaleMarketShare,
+} from "../tokscale_analytics.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "tokscale_market_share",
+  description:
+    "Complete AI tool market share analysis from your local tokscale data. Aggregates per-model usage by client (AI tool) and computes each tool's share of total tokens, cost, and messages. Returns each tool ranked by token share, with share_tokens / share_cost / share_messages percentages and a totals rollup. All data is read locally from tokscale's scan of your session logs — no network calls, no PII. Use this to see which AI coding tools dominate your workflow by volume, spend, or activity. Do NOT use this for per-model detail — use tokscale_developer_profile for that.",
+  annotations: { title: "AI tool market share", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {},
+    description: "No parameters. Scans all locally-detected AI tools via tokscale.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      tools: {
+        type: "array",
+        description: "AI tools ranked by token share, each with { client, label, tokens, cost, messages, model_count, share_tokens, share_cost, share_messages }",
+      },
+      totals: {
+        type: "object",
+        description: "Aggregate totals: { tokens, cost, messages, tool_count }",
+      },
+      error: { type: "string", description: "Present if tokscale is unavailable" },
+    },
+  },
+};
+
+export async function handleTokscaleMarketShare() {
+  return await tokscaleMarketShare();
+}

package/tools/tokscale-mcp-usage.mjs

@@ -0,0 +1,33 @@
+/**
+ * tools/tokscale-mcp-usage.mjs — tokscale_mcp_usage tool.
+ */
+
+import { tokscaleMcpUsage } from "../tokscale_analytics.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "tokscale_mcp_usage",
+  description:
+    "MCP server usage patterns from your local tokscale data. Reports which MCP servers tokscale detected on this machine, the detection window, and active days in that window. tokscale currently exposes detected MCP servers as a set (not per-session attribution), so the report notes the detection window. Use this to see which MCP servers are active on your machine. If no servers are detected, the response explains that MCP server tracking requires a tokscale version that records per-session MCP attribution.",
+  annotations: { title: "MCP server usage", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {},
+    description: "No parameters. Reads MCP server data from tokscale graph output.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      servers: { type: "array", description: "Detected MCP servers: [{ name, detected: true }]" },
+      server_count: { type: "integer" },
+      detection_window: { type: "object", description: "{ start, end } date range" },
+      active_days_in_window: { type: "integer" },
+      note: { type: "string", description: "Explanation of the MCP server data granularity" },
+      error: { type: "string", description: "Present if tokscale is unavailable" },
+    },
+  },
+};
+
+export async function handleTokscaleMcpUsage() {
+  return await tokscaleMcpUsage();
+}

package/tools/tokscale-model-trends.mjs

@@ -0,0 +1,32 @@
+/**
+ * tools/tokscale-model-trends.mjs — tokscale_model_trends tool.
+ */
+
+import { tokscaleModelTrends } from "../tokscale_analytics.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+
+export const TOOL_DEF = {
+  name: "tokscale_model_trends",
+  description:
+    "Model adoption trends over time from your local tokscale data. Combines monthly aggregates with per-day contribution data to build a model-level adoption timeline: each model's first_seen / last_seen / active_days / tokens / clients, plus a month-by-month adoption curve showing how many new models appeared each month. Returns months[], models[], and adoption_curve[]. Use this to track which AI models you adopted when, and how your model mix evolved over time. Do NOT use this for cost trends — use tokscale_cost_analysis for current cost breakdown.",
+  annotations: { title: "Model adoption trends", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.openWorldHint },
+  inputSchema: {
+    type: "object",
+    properties: {},
+    description: "No parameters. Derives trends from tokscale monthly + graph data.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      months: { type: "array", description: "Per-month aggregates: { month, models, model_count, input, output, cache_read, messages, cost }" },
+      models: { type: "array", description: "Per-model adoption: { model, first_seen, last_seen, active_days, tokens, cost, messages, client_count, clients }" },
+      adoption_curve: { type: "array", description: "Per-month new-model count: { month, new_models, new_model_count, total_models }" },
+      date_range: { type: "object", description: "{ start, end } date range of the data" },
+      error: { type: "string", description: "Present if tokscale is unavailable" },
+    },
+  },
+};
+
+export async function handleTokscaleModelTrends() {
+  return await tokscaleModelTrends();
+}

package/tools/watch-tokenpull.mjs

@@ -0,0 +1,134 @@
+/**
+ * tools/watch-tokenpull.mjs — watch_tokenpull tool.
+ */
+
+import { cascade } from "../analytics/cascade.mjs";
+import { narrate } from "../presentation/narrate.mjs";
+import { ALL_PLATFORMS } from "../adapters/index.mjs";
+import { ensureIdentity } from "../identity/keystore.mjs";
+import { submitSignedWindow } from "../submit/index.mjs";
+import { TOKENPULL_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import {
+  pullByPlatform,
+  WATCH_SUBMIT_COOLDOWN_MS,
+  _lastWatchSubmitAt,
+} from "./_helpers.mjs";
+
+export const TOOL_DEF = {
+  name: "watch_tokenpull",
+  description:
+    "One poll per call: pulls your local token logs and returns the current cascade for the watched window — the tool never blocks or loops. Re-call at your desired cadence to watch for changes (interval_s is advisory only and echoed back as poll_interval_s). With submit:true (and an enrolled device) each call may also sign + publish the watched window to the board, rate-limited to once per 5 min per platform+window; default is preview-only (no submit).",
+  annotations: {
+    title: "Watch token pull",
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      platform: {
+        type: "string",
+        enum: ALL_PLATFORMS,
+        description: "platform to watch (default: claude)",
+      },
+      interval_s: {
+        type: "number",
+        description:
+          "advisory poll cadence in seconds (default: 60, min: 10) — echoed back as poll_interval_s; does not make the call block or loop",
+      },
+      window: {
+        type: "string",
+        enum: ["7d", "30d", "90d", "all"],
+        description:
+          "which window to watch (default: 7d — most sensitive to recent activity)",
+      },
+      submit: {
+        type: "boolean",
+        description:
+          "auto-submit the watched window to the board as a VERIFIED operator each poll (requires `enroll`; default false = preview only)",
+      },
+    },
+  },
+  outputSchema: TOKENPULL_OUTPUT,
+};
+
+export async function handleWatchTokenpull(args, ctx) {
+  // Poll the local token logs at a configurable interval and return the cascade
+  // diff whenever new sessions appear. One poll cycle per MCP call — the client
+  // is responsible for re-calling at the desired cadence (MCP tools are stateless;
+  // a persistent background watcher lives outside the tool boundary).
+  //
+  // With submit:true + an enrolled device, this also signs + POSTs the watched window
+  // to the verified ingest path each poll (the server dedups identical re-submits).
+  const platform = args?.platform || "claude";
+  const watchWindow = args?.window || "7d";
+  const intervalS = Math.max(10, Number(args?.interval_s) || 60);
+
+  const pulled = await pullByPlatform(platform, ctx.opts);
+  const win = pulled.windows.find((w) => w.window === watchWindow);
+  if (!win)
+    throw new Error(
+      `watch_tokenpull: window '${watchWindow}' not found in pull result.`,
+    );
+
+  const c = cascade(win.pillars);
+  const card = narrate(c, `${watchWindow} ${platform}`);
+
+  // AUTH.WIRE (D7 §7): when submit is on AND the device is enrolled, sign + POST the
+  // watched window to the verified ingest path. Default OFF = preview only. The server
+  // dedups identical re-submits (exact snapshot_hash → 422), so re-calling is safe.
+  let auth_submit = null;
+  if (args?.submit === true) {
+    const id = ctx.opts.identity || ensureIdentity();
+    if (id.codename && id.operator_id && id.private_key_pkcs8_b64) {
+      // E3: client-side cooldown — at most one auto-submit per platform+window per 5 min.
+      // Prevents a fast poll loop from churning the board even before the server's
+      // hash-dedup kicks in. Armed only on a non-error outcome so failed submits retry.
+      const clockNow = typeof ctx.opts.now === "number" ? ctx.opts.now : Date.now();
+      const cdKey = `${pulled.platform}:${watchWindow}`;
+      const last = _lastWatchSubmitAt.get(cdKey);
+      if (last != null && clockNow - last < WATCH_SUBMIT_COOLDOWN_MS) {
+        const waitS = Math.ceil(
+          (WATCH_SUBMIT_COOLDOWN_MS - (clockNow - last)) / 1000,
+        );
+        auth_submit = {
+          status: "cooldown",
+          detail: `auto-submit for '${cdKey}' on cooldown — next in ~${waitS}s (max once / 5 min).`,
+          retry_after_s: waitS,
+        };
+      } else {
+        auth_submit = await submitSignedWindow(
+          watchWindow,
+          win.pillars,
+          win.messages,
+          id,
+          {
+            apiBase: ctx.apiBase,
+            fetchImpl: ctx.doFetch,
+            platform: pulled.platform,
+            now: ctx.opts.now,
+          },
+        );
+        if (auth_submit?.status !== "error")
+          _lastWatchSubmitAt.set(cdKey, clockNow);
+      }
+    } else {
+      auth_submit = {
+        status: "not_enrolled",
+        detail: "Run `npx sigrank-mcp enroll` to auto-submit verified runs.",
+      };
+    }
+  }
+  return {
+    platform: pulled.platform,
+    window: watchWindow,
+    pillars: win.pillars,
+    messages: win.messages,
+    cascade: c,
+    card,
+    generatedAt: pulled.generatedAt,
+    poll_interval_s: intervalS,
+    auth_submit,
+    note: "One snapshot per call — re-call at your poll interval to detect changes.",
+  };
+}