@ken-jo/agent-connector 0.1.0

package/dist/chunk-JNM3TPLX.js

@@ -0,0 +1,593 @@
+#!/usr/bin/env node
+import {
+  getTokenizer,
+  inferModelFamily,
+  openStore,
+  worstConfidence
+} from "./chunk-BCHWFTV4.js";
+
+// src/telemetry/surface-footprint.ts
+function countParts(parts, family, tok) {
+  return tok.count(parts.join("\n"), family).tokens;
+}
+function computeSurfaceFootprints(connector, tok = getTokenizer()) {
+  const family = inferModelFamily("", connector.telemetry.modelFamilyHint);
+  const out = [];
+  for (const cmd of connector.commands) {
+    const parts = [];
+    if (cmd.description !== void 0) parts.push(cmd.description);
+    parts.push(cmd.prompt);
+    if (cmd.argumentHint !== void 0) parts.push(cmd.argumentHint);
+    out.push({
+      surfaceKind: "command",
+      name: cmd.name,
+      tokens: countParts(parts, family, tok)
+    });
+  }
+  for (const skill of connector.skills) {
+    const parts = [skill.description, skill.body];
+    if (skill.resources !== void 0) {
+      const paths = Object.keys(skill.resources).sort();
+      for (const p of paths) {
+        const value = skill.resources[p];
+        if (value !== void 0) parts.push(value);
+      }
+    }
+    out.push({
+      surfaceKind: "skill",
+      name: skill.name,
+      tokens: countParts(parts, family, tok)
+    });
+  }
+  for (const agent of connector.subagents) {
+    out.push({
+      surfaceKind: "subagent",
+      name: agent.name,
+      tokens: countParts([agent.description, agent.prompt], family, tok)
+    });
+  }
+  return out;
+}
+
+// src/telemetry/leaderboard.ts
+var SCOPE_FILTER_VALUES = [
+  "user",
+  "project",
+  "npx",
+  "bunx",
+  "uvx",
+  "node",
+  "binary",
+  "http",
+  "unknown"
+];
+function isScopeFilter(value) {
+  return SCOPE_FILTER_VALUES.includes(value);
+}
+var INSTALL_SCOPES = /* @__PURE__ */ new Set(["user", "project"]);
+function matchesScope(record, scope) {
+  if (scope === "unknown") {
+    return record.installScope === void 0 && record.launchMethod === void 0;
+  }
+  if (INSTALL_SCOPES.has(scope)) {
+    return record.installScope === scope;
+  }
+  return record.launchMethod === scope;
+}
+function toFilter(opts) {
+  const filter = {};
+  if (opts.sinceMs !== void 0) filter.sinceMs = opts.sinceMs;
+  if (opts.connectorId !== void 0 && opts.connectorId !== "") {
+    filter.connectorId = opts.connectorId;
+  }
+  return filter;
+}
+function selectRecords(opts, includeModelTurn = false) {
+  const store = opts.store ?? openStore({});
+  const owned = opts.store === void 0;
+  try {
+    let rows = store.query(toFilter(opts));
+    rows = includeModelTurn ? rows.filter((r) => r.scope === "model_turn") : rows.filter((r) => r.scope !== "model_turn");
+    if (opts.scope === void 0) return rows;
+    const scope = opts.scope;
+    return rows.filter((r) => matchesScope(r, scope));
+  } finally {
+    if (owned) store.close();
+  }
+}
+function mcpLeaderboard(opts = {}) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const r of selectRecords(opts)) {
+    let g = groups.get(r.connectorId);
+    if (g === void 0) {
+      g = {
+        connectorId: r.connectorId,
+        calls: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        tools: /* @__PURE__ */ new Set(),
+        hostPlatforms: /* @__PURE__ */ new Set(),
+        confidence: r.confidenceSource,
+        lastTs: r.ts
+      };
+      groups.set(r.connectorId, g);
+    }
+    if (r.scope === "call") {
+      g.calls += 1;
+      g.tools.add(r.toolName);
+    }
+    g.inputTokens += r.inputTokens;
+    g.outputTokens += r.outputTokens;
+    g.totalTokens += r.inputTokens + r.outputTokens;
+    g.hostPlatforms.add(r.hostPlatform);
+    g.confidence = worstConfidence(g.confidence, r.confidenceSource);
+    if (r.ts > g.lastTs) g.lastTs = r.ts;
+  }
+  const rows = [];
+  for (const g of groups.values()) {
+    rows.push({
+      connectorId: g.connectorId,
+      calls: g.calls,
+      inputTokens: g.inputTokens,
+      outputTokens: g.outputTokens,
+      totalTokens: g.totalTokens,
+      tools: g.tools.size,
+      hostPlatforms: [...g.hostPlatforms].sort(),
+      confidence: g.confidence,
+      lastTs: g.lastTs
+    });
+  }
+  rows.sort((a, b) => b.totalTokens - a.totalTokens || b.lastTs - a.lastTs);
+  return rows;
+}
+function toolLeaderboard(opts = {}) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const r of selectRecords(opts)) {
+    const key = `${r.connectorId}\0${r.toolName}\0${r.scope}`;
+    const g = groups.get(key);
+    if (g === void 0) {
+      groups.set(key, {
+        connectorId: r.connectorId,
+        toolName: r.toolName,
+        scope: r.scope,
+        calls: r.scope === "call" ? 1 : 0,
+        inputTokens: r.inputTokens,
+        outputTokens: r.outputTokens,
+        totalTokens: r.inputTokens + r.outputTokens,
+        confidence: r.confidenceSource,
+        lastTs: r.ts
+      });
+    } else {
+      if (r.scope === "call") g.calls += 1;
+      g.inputTokens += r.inputTokens;
+      g.outputTokens += r.outputTokens;
+      g.totalTokens += r.inputTokens + r.outputTokens;
+      g.confidence = worstConfidence(g.confidence, r.confidenceSource);
+      if (r.ts > g.lastTs) g.lastTs = r.ts;
+    }
+  }
+  const rows = [...groups.values()];
+  rows.sort((a, b) => b.totalTokens - a.totalTokens || b.lastTs - a.lastTs);
+  return rows;
+}
+function hostNativeTurns(opts = {}) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const r of selectRecords(
+    opts,
+    /* includeModelTurn */
+    true
+  )) {
+    const key = `${r.hostPlatform}\0${r.sessionId}`;
+    let g = groups.get(key);
+    if (g === void 0) {
+      g = {
+        hostPlatform: r.hostPlatform,
+        sessionId: r.sessionId,
+        turns: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        connectors: /* @__PURE__ */ new Set(),
+        confidence: r.confidenceSource,
+        lastTs: r.ts
+      };
+      groups.set(key, g);
+    }
+    g.turns += 1;
+    g.inputTokens += r.inputTokens;
+    g.outputTokens += r.outputTokens;
+    g.totalTokens += r.inputTokens + r.outputTokens;
+    g.connectors.add(r.connectorId);
+    g.confidence = worstConfidence(g.confidence, r.confidenceSource);
+    if (r.ts > g.lastTs) g.lastTs = r.ts;
+  }
+  const rows = [];
+  for (const g of groups.values()) {
+    rows.push({
+      hostPlatform: g.hostPlatform,
+      sessionId: g.sessionId,
+      turns: g.turns,
+      inputTokens: g.inputTokens,
+      outputTokens: g.outputTokens,
+      totalTokens: g.totalTokens,
+      connectors: [...g.connectors].sort(),
+      confidence: g.confidence,
+      lastTs: g.lastTs
+    });
+  }
+  rows.sort((a, b) => b.totalTokens - a.totalTokens || b.lastTs - a.lastTs);
+  return rows;
+}
+function recordSurfaceKind(r) {
+  if (r.surfaceKind !== void 0) return r.surfaceKind;
+  return "server";
+}
+function surfaceLeaderboard(opts = {}) {
+  const runtime = /* @__PURE__ */ new Map();
+  for (const r of selectRecords(opts)) {
+    const surfaceKind = recordSurfaceKind(r);
+    const key = `${surfaceKind} ${r.toolName}`;
+    let g = runtime.get(key);
+    if (g === void 0) {
+      g = {
+        surfaceKind,
+        name: r.toolName,
+        calls: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        confidence: r.confidenceSource,
+        lastTs: r.ts
+      };
+      runtime.set(key, g);
+    }
+    if (r.scope === "call" || r.scope === "hook") g.calls += 1;
+    g.inputTokens += r.inputTokens;
+    g.outputTokens += r.outputTokens;
+    g.totalTokens += r.inputTokens + r.outputTokens;
+    g.confidence = worstConfidence(g.confidence, r.confidenceSource);
+    if (r.ts > g.lastTs) g.lastTs = r.ts;
+  }
+  const rows = [];
+  for (const g of runtime.values()) {
+    rows.push({
+      surfaceKind: g.surfaceKind,
+      name: g.name,
+      kind: "runtime",
+      calls: g.calls,
+      inputTokens: g.inputTokens,
+      outputTokens: g.outputTokens,
+      totalTokens: g.totalTokens,
+      confidence: g.confidence,
+      lastTs: g.lastTs
+    });
+  }
+  const staticRows = /* @__PURE__ */ new Map();
+  for (const connector of opts.connectors ?? []) {
+    for (const fp of computeSurfaceFootprints(connector)) {
+      const key = `${fp.surfaceKind} ${fp.name}`;
+      const existing = staticRows.get(key);
+      if (existing === void 0) {
+        staticRows.set(key, { surfaceKind: fp.surfaceKind, name: fp.name, tokens: fp.tokens });
+      } else {
+        existing.tokens += fp.tokens;
+      }
+    }
+  }
+  const staticConfidence = staticFootprintConfidence(opts.connectors ?? []);
+  for (const s of staticRows.values()) {
+    rows.push({
+      surfaceKind: s.surfaceKind,
+      name: s.name,
+      kind: "static",
+      calls: 0,
+      inputTokens: s.tokens,
+      outputTokens: 0,
+      totalTokens: s.tokens,
+      confidence: staticConfidence,
+      lastTs: 0
+    });
+  }
+  rows.sort((a, b) => b.totalTokens - a.totalTokens || b.lastTs - a.lastTs);
+  return rows;
+}
+function staticFootprintConfidence(connectors) {
+  const first = connectors[0];
+  if (first === void 0) return "tokenizer-approx";
+  return first.telemetry.modelFamilyHint === "openai" ? "tokenizer-exact" : "tokenizer-approx";
+}
+var ESTIMATE_SOURCES = /* @__PURE__ */ new Set([
+  "heuristic",
+  "tokenizer-approx",
+  "tokenizer-calibrated"
+]);
+function fmtInt(n) {
+  return n.toLocaleString("en-US");
+}
+function padRight(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+function padLeft(s, width) {
+  return s.length >= width ? s : " ".repeat(width - s.length) + s;
+}
+function renderTable(headers, dataRows, leftAlignedCols, totalRow, emptyMessage) {
+  const widths = headers.map((h, col) => {
+    let w = h.length;
+    for (const row of dataRows) w = Math.max(w, (row[col] ?? "").length);
+    w = Math.max(w, (totalRow[col] ?? "").length);
+    return w;
+  });
+  const renderRow = (cells) => cells.map(
+    (c, col) => leftAlignedCols.has(col) ? padRight(c, widths[col] ?? 0) : padLeft(c, widths[col] ?? 0)
+  ).join("  ").trimEnd();
+  const ruleWidth = widths.reduce((a, b) => a + b, 0) + 2 * (widths.length - 1);
+  const rule = "-".repeat(ruleWidth);
+  const lines = [];
+  lines.push(renderRow(headers));
+  lines.push(rule);
+  if (dataRows.length === 0) {
+    lines.push(emptyMessage);
+  } else {
+    for (const row of dataRows) lines.push(renderRow(row));
+  }
+  lines.push(rule);
+  lines.push(renderRow(totalRow));
+  return lines;
+}
+function appendEstimateLegend(lines, confidences) {
+  if (confidences.some((c) => ESTIMATE_SOURCES.has(c))) {
+    lines.push("");
+    lines.push(
+      "note: heuristic and tokenizer-approx token counts are estimates, not exact host-reported usage."
+    );
+    if (confidences.some((c) => c === "tokenizer-calibrated")) {
+      lines.push(
+        "note: tokenizer-calibrated = local approx adjusted by a sampled Anthropic count_tokens factor (opt-in; content sampled off-box only when AGENT_CONNECTOR_CALIBRATE=anthropic)."
+      );
+    }
+  }
+}
+function formatMcpLeaderboard(rows) {
+  const sorted = [...rows].sort(
+    (a, b) => b.totalTokens - a.totalTokens || b.lastTs - a.lastTs
+  );
+  const headers = [
+    "RANK",
+    "CONNECTOR",
+    "CALLS",
+    "TOOLS",
+    "IN",
+    "OUT",
+    "TOTAL",
+    "HOSTS",
+    "CONFIDENCE"
+  ];
+  const dataRows = sorted.map((r, i) => [
+    `${i + 1}`,
+    r.connectorId,
+    fmtInt(r.calls),
+    fmtInt(r.tools),
+    fmtInt(r.inputTokens),
+    fmtInt(r.outputTokens),
+    fmtInt(r.totalTokens),
+    r.hostPlatforms.length === 0 ? "-" : r.hostPlatforms.join(","),
+    r.confidence
+  ]);
+  const totals = sorted.reduce(
+    (acc, r) => {
+      acc.calls += r.calls;
+      acc.inputTokens += r.inputTokens;
+      acc.outputTokens += r.outputTokens;
+      acc.totalTokens += r.totalTokens;
+      return acc;
+    },
+    { calls: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+  );
+  const totalRow = [
+    "",
+    "TOTAL",
+    fmtInt(totals.calls),
+    "",
+    fmtInt(totals.inputTokens),
+    fmtInt(totals.outputTokens),
+    fmtInt(totals.totalTokens),
+    "",
+    ""
+  ];
+  const leftCols = /* @__PURE__ */ new Set([0, 1, 7, 8]);
+  const lines = renderTable(
+    headers,
+    dataRows,
+    leftCols,
+    totalRow,
+    "(no MCP telemetry recorded)"
+  );
+  appendEstimateLegend(
+    lines,
+    sorted.map((r) => r.confidence)
+  );
+  return lines.join("\n");
+}
+function formatToolLeaderboard(rows) {
+  const sorted = [...rows].sort(
+    (a, b) => b.totalTokens - a.totalTokens || b.lastTs - a.lastTs
+  );
+  const headers = [
+    "RANK",
+    "CONNECTOR",
+    "TOOL",
+    "SCOPE",
+    "CALLS",
+    "IN",
+    "OUT",
+    "TOTAL",
+    "CONFIDENCE"
+  ];
+  const dataRows = sorted.map((r, i) => [
+    `${i + 1}`,
+    r.connectorId,
+    r.toolName,
+    r.scope,
+    fmtInt(r.calls),
+    fmtInt(r.inputTokens),
+    fmtInt(r.outputTokens),
+    fmtInt(r.totalTokens),
+    r.confidence
+  ]);
+  const totals = sorted.reduce(
+    (acc, r) => {
+      acc.calls += r.calls;
+      acc.inputTokens += r.inputTokens;
+      acc.outputTokens += r.outputTokens;
+      acc.totalTokens += r.totalTokens;
+      return acc;
+    },
+    { calls: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+  );
+  const totalRow = [
+    "",
+    "TOTAL",
+    "",
+    "",
+    fmtInt(totals.calls),
+    fmtInt(totals.inputTokens),
+    fmtInt(totals.outputTokens),
+    fmtInt(totals.totalTokens),
+    ""
+  ];
+  const leftCols = /* @__PURE__ */ new Set([0, 1, 2, 3, 8]);
+  const lines = renderTable(
+    headers,
+    dataRows,
+    leftCols,
+    totalRow,
+    "(no MCP telemetry recorded)"
+  );
+  appendEstimateLegend(
+    lines,
+    sorted.map((r) => r.confidence)
+  );
+  return lines.join("\n");
+}
+function formatHostNativeTurns(rows) {
+  const sorted = [...rows].sort(
+    (a, b) => b.totalTokens - a.totalTokens || b.lastTs - a.lastTs
+  );
+  const headers = [
+    "RANK",
+    "HOST",
+    "SESSION",
+    "TURNS",
+    "IN",
+    "OUT",
+    "TOTAL",
+    "CONNECTORS",
+    "CONFIDENCE"
+  ];
+  const dataRows = sorted.map((r, i) => [
+    `${i + 1}`,
+    r.hostPlatform,
+    r.sessionId === "" ? "-" : r.sessionId,
+    fmtInt(r.turns),
+    fmtInt(r.inputTokens),
+    fmtInt(r.outputTokens),
+    fmtInt(r.totalTokens),
+    r.connectors.length === 0 ? "-" : r.connectors.join(","),
+    r.confidence
+  ]);
+  const totals = sorted.reduce(
+    (acc, r) => {
+      acc.turns += r.turns;
+      acc.inputTokens += r.inputTokens;
+      acc.outputTokens += r.outputTokens;
+      acc.totalTokens += r.totalTokens;
+      return acc;
+    },
+    { turns: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+  );
+  const totalRow = [
+    "",
+    "TOTAL",
+    "",
+    fmtInt(totals.turns),
+    fmtInt(totals.inputTokens),
+    fmtInt(totals.outputTokens),
+    fmtInt(totals.totalTokens),
+    "",
+    ""
+  ];
+  const leftCols = /* @__PURE__ */ new Set([0, 1, 2, 7, 8]);
+  const lines = renderTable(
+    headers,
+    dataRows,
+    leftCols,
+    totalRow,
+    "(no host-native turns recorded \u2014 enable opt-in host-native usage)"
+  );
+  return lines.join("\n");
+}
+function formatSurfaceLeaderboard(rows) {
+  const sorted = [...rows].sort(
+    (a, b) => b.totalTokens - a.totalTokens || b.lastTs - a.lastTs
+  );
+  const headers = ["SURFACE", "NAME", "IN", "OUT", "TOTAL", "KIND"];
+  const dataRows = sorted.map((r) => [
+    r.surfaceKind,
+    r.name,
+    fmtInt(r.inputTokens),
+    fmtInt(r.outputTokens),
+    fmtInt(r.totalTokens),
+    r.kind
+  ]);
+  const totals = sorted.reduce(
+    (acc, r) => {
+      acc.inputTokens += r.inputTokens;
+      acc.outputTokens += r.outputTokens;
+      acc.totalTokens += r.totalTokens;
+      return acc;
+    },
+    { inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+  );
+  const totalRow = [
+    "TOTAL",
+    "",
+    fmtInt(totals.inputTokens),
+    fmtInt(totals.outputTokens),
+    fmtInt(totals.totalTokens),
+    ""
+  ];
+  const leftCols = /* @__PURE__ */ new Set([0, 1, 5]);
+  const lines = renderTable(
+    headers,
+    dataRows,
+    leftCols,
+    totalRow,
+    "(no developer surfaces recorded)"
+  );
+  if (sorted.some((r) => r.kind === "static")) {
+    lines.push("");
+    lines.push(
+      "note: KIND=static rows are the tokenized FOOTPRINT a command/skill/subagent imposes on a host that loads it as context \u2014 not intercepted usage rows."
+    );
+  }
+  appendEstimateLegend(
+    lines,
+    sorted.map((r) => r.confidence)
+  );
+  return lines.join("\n");
+}
+
+export {
+  SCOPE_FILTER_VALUES,
+  isScopeFilter,
+  mcpLeaderboard,
+  toolLeaderboard,
+  hostNativeTurns,
+  surfaceLeaderboard,
+  formatMcpLeaderboard,
+  formatToolLeaderboard,
+  formatHostNativeTurns,
+  formatSurfaceLeaderboard
+};
+//# sourceMappingURL=chunk-JNM3TPLX.js.map